Skip to content

docs(todo): track small follow-ups and external deps in TODO.md#179

Merged
donbeave merged 1 commit into
mainfrom
chore/todo-follow-up-tracker
Apr 25, 2026
Merged

docs(todo): track small follow-ups and external deps in TODO.md#179
donbeave merged 1 commit into
mainfrom
chore/todo-follow-up-tracker

Conversation

@donbeave

@donbeave donbeave commented Apr 25, 2026

Copy link
Copy Markdown
Member

Summary

Repurpose the existing root TODO.md from a thin roadmap pointer + per-PR checklist into a periodic-review tracker for small items that don't warrant a full roadmap design doc.

Why

We've started accumulating small follow-ups that need a periodic-review home:

  • External dependencies waiting on upstream releases — e.g., ci(docs): bump lychee-action and lychee for sitemap URL extraction #176 had to pin lycheeverse/lychee-action to a master commit (faea714) because the v0.24.x fix is unreleased. We need a tracked place to remember to revert that pin to a tag SHA when upstream cuts a release.
  • Internal small polish that's too small for a roadmap doc — renames for consistency, single-line cleanups, etc.

These don't fit the existing roadmap (problem statement + design discussion). They also don't fit DEPRECATED.md (deprecation ledger). They need a checklist.

What's in TODO.md after this PR

  • Follow-ups section. Each entry uses a stable kebab-case anchor (#external-dependencies, then per-item heading like ### lychee-action-sha-pin — …) and the recommended fields: What, Why, Tracking, Last verified, Done when.
  • Code-level marker convention. Anything that has an in-code anchor uses // TODO(<topic>): one-line summary — see TODO.md "Follow-ups" → "<heading>", where <topic> matches the heading anchor. One grep finds both ends: 
    grep -rn 'TODO(<topic>)' .
  • Roadmap pointer — kept; still the right home for design proposals (now with a one-liner about how to choose between roadmap and follow-up).
  • Stale-docs checklist — kept; per-PR drift check, unchanged.

Wiring

  • AGENTS.md "Shared conventions" gains a TODO.md bullet (right after DEPRECATED.md, since both are ledgers of work to address eventually).
  • PROJECT_STRUCTURE.md row for TODO.md rewritten to describe the dual role.

Concrete entry today

Just one — the lychee-action SHA pin from #176. Walk-through:

What: swap .github/workflows/docs.yml's lycheeverse/lychee-action SHA pin from faea714062690f6c2e6f7f388469ec4fa6d9c4e1 (master, post-v2.8.0) back to a tagged release SHA.
Done when: a tag at or after faea714 ships → replace SHA, update inline comment from "post-v2.8.0 master" to the tag name.

I'll add a matching # TODO(lychee-action-sha-pin) marker line to docs.yml in #176 as a follow-up amendment to that PR (so the marker lives next to the pinned SHA, not in this infra-only PR).

Code TODO scan

A repo-wide search for TODO|FIXME|XXX|HACK in src/, docs/scripts/, docs/src/components/, docker/, and top-level config returned zero existing markers. So this PR establishes the convention without retro-cataloging — future markers will be added alongside the change that introduces them.

Test plan

  • CI green.
  • After merge, walk the file once a month: update Last verified dates; if Done when is satisfied, delete the entry and remove the matching TODO(<topic>) marker(s) in the same PR.

🤖 Generated with Claude Code

@donbeave @claude
docs(todo): track small follow-ups and external deps in TODO.md
3d84c51 
Repurpose the existing TODO.md from a thin roadmap pointer + per-PR
checklist into a periodic-review tracker for small items that don't
warrant a full roadmap design doc:

- External dependencies waiting on upstream fixes (e.g., upstream
  releases, library bugs we're working around).
- Internal consistency or polish work.

Each entry uses a stable kebab-case anchor so code can link back with a
matching `TODO(<topic>): … — see TODO.md "<heading>"` marker, kept
greppable (`grep -rn 'TODO(<topic>)' .`). Document this convention in
the file so future authors don't reinvent it.

Add the one open item we have today: the lychee-action SHA pin
introduced in #176 currently points at master HEAD (faea714) because
the v0.24.x compatibility fix is unreleased. Tracked here so it can be
reverted to a tag SHA on the next lychee-action release.

Wire TODO.md into AGENTS.md "Shared conventions" (right after
DEPRECATED.md, since both are ledgers of work to address eventually)
and refresh its row in PROJECT_STRUCTURE.md to describe the dual role.

The roadmap pointer and the stale-docs checklist remain in TODO.md
unchanged — they're still the right home for those concerns and
co-locating with follow-ups gives all "things to verify" one place.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
donbeave added a commit that referenced this pull request Apr 25, 2026
@donbeave @claude
ci(docs): add TODO(lychee-action-sha-pin) marker
10e4daf 
Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
@donbeave donbeave merged commit 9abd255 into main Apr 25, 2026
6 checks passed
@donbeave donbeave deleted the chore/todo-follow-up-tracker branch April 25, 2026 21:19
donbeave added a commit that referenced this pull request Apr 25, 2026
@donbeave @claude
ci(docs): bump lychee-action and lychee for sitemap URL extraction (#176
34bb396 
)

* ci(docs): bump lychee to v0.24.0 to fix sitemap URL extraction

The first Docs workflow run on main after #173 (commit f3f3e5e) failed
in deploy → "Check deployed docs links" with "No files found for this
input source". Root cause: the previous step ran lychee --dump on the
deployed sitemap URL, but lychee 0.23.0 (the lycheeverse/lychee-action
v2 default) only extracts <a href> from HTML and matching patterns from
markdown — it does not parse <loc> entries from XML sitemaps. The dump
produced an empty list and the follow-up --files-from step had nothing
to read.

Upstream already fixed this. lycheeverse/lychee#2071 (merged
2026-03-13, tagged in v0.24.0 on 2026-04-24) adds <loc> extraction
from sitemap.xml, closing lycheeverse/lychee#2062 and #1819. Verified
locally on 0.24.0:

  $ lychee --version
  lychee 0.24.0
  $ lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Pin LYCHEE_VERSION at the workflow env level and reference it from
every lychee-action call so future bumps are one-line. v0.24.0's
breaking changes are in lychee-lib (the Rust API consumers); the CLI
surface we use is unchanged.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* ci(docs): bump lychee-action and lychee for sitemap URL extraction

Replace the previous v0.24.0 bump with the only combination that
actually works against the current lychee release pipeline:

  - lycheeverse/lychee-action SHA 8646ba3 (tagged v2.8.0) → faea714
    (post-v2.8.0 master). Adds subfolder-aware install needed for any
    lychee 0.24.x tarball.
  - LYCHEE_VERSION 'v0.24.0' → 'v0.24.1'.

Why both moves:

* lychee 0.24.0 added <loc> extraction from XML sitemaps
  (lycheeverse/lychee#2071), which is what the deploy and check-deployed
  jobs need to feed --files-from. lychee 0.23.0 dumps zero links from a
  sitemap, which is what produced the "No files found for this input
  source" failure on f3f3e5e.
* lychee 0.24.0's release tarball was repackaged with a top-level
  subfolder AND the asset filename was renamed to
  lychee-lychee-v0.24.0-{arch}-... — both incompatible with
  lychee-action v2.8.0's hardcoded download URL and flat-extract logic.
* lychee 0.24.1 (released the same day) reverted to the original asset
  filename but kept the subfolder layout AND kept the sitemap fix.
* lychee-action faea714 (unreleased; current HEAD of master) bumps the
  default to 0.24.1 and adds subfolder-aware install. Pinning the SHA
  is the same security model we already use for v2.8.0.

The combination 8646ba3 + 'latest' or 8646ba3 + 'v0.24.x' both fail.
The combination faea714 + 'v0.24.1' works.

Verified locally:

  $ lychee-v0.24.1/lychee --version
  lychee 0.24.1
  $ lychee-v0.24.1/lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* ci(docs): add TODO(lychee-action-sha-pin) marker

Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 6, 2026
@donbeave @claude
docs(todo): track small follow-ups and external deps in TODO.md (#179)
327fd1b 
Repurpose the existing TODO.md from a thin roadmap pointer + per-PR
checklist into a periodic-review tracker for small items that don't
warrant a full roadmap design doc:

- External dependencies waiting on upstream fixes (e.g., upstream
  releases, library bugs we're working around).
- Internal consistency or polish work.

Each entry uses a stable kebab-case anchor so code can link back with a
matching `TODO(<topic>): … — see TODO.md "<heading>"` marker, kept
greppable (`grep -rn 'TODO(<topic>)' .`). Document this convention in
the file so future authors don't reinvent it.

Add the one open item we have today: the lychee-action SHA pin
introduced in #176 currently points at master HEAD (faea714) because
the v0.24.x compatibility fix is unreleased. Tracked here so it can be
reverted to a tag SHA on the next lychee-action release.

Wire TODO.md into AGENTS.md "Shared conventions" (right after
DEPRECATED.md, since both are ledgers of work to address eventually)
and refresh its row in PROJECT_STRUCTURE.md to describe the dual role.

The roadmap pointer and the stale-docs checklist remain in TODO.md
unchanged — they're still the right home for those concerns and
co-locating with follow-ups gives all "things to verify" one place.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 6, 2026
@donbeave @claude
ci(docs): bump lychee-action and lychee for sitemap URL extraction (#176
4d3ffce 
)

* ci(docs): bump lychee to v0.24.0 to fix sitemap URL extraction

The first Docs workflow run on main after #173 (commit f3f3e5e) failed
in deploy → "Check deployed docs links" with "No files found for this
input source". Root cause: the previous step ran lychee --dump on the
deployed sitemap URL, but lychee 0.23.0 (the lycheeverse/lychee-action
v2 default) only extracts <a href> from HTML and matching patterns from
markdown — it does not parse <loc> entries from XML sitemaps. The dump
produced an empty list and the follow-up --files-from step had nothing
to read.

Upstream already fixed this. lycheeverse/lychee#2071 (merged
2026-03-13, tagged in v0.24.0 on 2026-04-24) adds <loc> extraction
from sitemap.xml, closing lycheeverse/lychee#2062 and #1819. Verified
locally on 0.24.0:

  $ lychee --version
  lychee 0.24.0
  $ lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Pin LYCHEE_VERSION at the workflow env level and reference it from
every lychee-action call so future bumps are one-line. v0.24.0's
breaking changes are in lychee-lib (the Rust API consumers); the CLI
surface we use is unchanged.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* ci(docs): bump lychee-action and lychee for sitemap URL extraction

Replace the previous v0.24.0 bump with the only combination that
actually works against the current lychee release pipeline:

  - lycheeverse/lychee-action SHA 8646ba3 (tagged v2.8.0) → faea714
    (post-v2.8.0 master). Adds subfolder-aware install needed for any
    lychee 0.24.x tarball.
  - LYCHEE_VERSION 'v0.24.0' → 'v0.24.1'.

Why both moves:

* lychee 0.24.0 added <loc> extraction from XML sitemaps
  (lycheeverse/lychee#2071), which is what the deploy and check-deployed
  jobs need to feed --files-from. lychee 0.23.0 dumps zero links from a
  sitemap, which is what produced the "No files found for this input
  source" failure on f3f3e5e.
* lychee 0.24.0's release tarball was repackaged with a top-level
  subfolder AND the asset filename was renamed to
  lychee-lychee-v0.24.0-{arch}-... — both incompatible with
  lychee-action v2.8.0's hardcoded download URL and flat-extract logic.
* lychee 0.24.1 (released the same day) reverted to the original asset
  filename but kept the subfolder layout AND kept the sitemap fix.
* lychee-action faea714 (unreleased; current HEAD of master) bumps the
  default to 0.24.1 and adds subfolder-aware install. Pinning the SHA
  is the same security model we already use for v2.8.0.

The combination 8646ba3 + 'latest' or 8646ba3 + 'v0.24.x' both fail.
The combination faea714 + 'v0.24.1' works.

Verified locally:

  $ lychee-v0.24.1/lychee --version
  lychee 0.24.1
  $ lychee-v0.24.1/lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

* ci(docs): add TODO(lychee-action-sha-pin) marker

Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>

---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude @codex
docs(todo): track small follow-ups and external deps in TODO.md (#179)
15d9a58 
Repurpose the existing TODO.md from a thin roadmap pointer + per-PR
checklist into a periodic-review tracker for small items that don't
warrant a full roadmap design doc:

- External dependencies waiting on upstream fixes (e.g., upstream
  releases, library bugs we're working around).
- Internal consistency or polish work.

Each entry uses a stable kebab-case anchor so code can link back with a
matching `TODO(<topic>): … — see TODO.md "<heading>"` marker, kept
greppable (`grep -rn 'TODO(<topic>)' .`). Document this convention in
the file so future authors don't reinvent it.

Add the one open item we have today: the lychee-action SHA pin
introduced in #176 currently points at master HEAD (faea714) because
the v0.24.x compatibility fix is unreleased. Tracked here so it can be
reverted to a tag SHA on the next lychee-action release.

Wire TODO.md into AGENTS.md "Shared conventions" (right after
DEPRECATED.md, since both are ledgers of work to address eventually)
and refresh its row in PROJECT_STRUCTURE.md to describe the dual role.

The roadmap pointer and the stale-docs checklist remain in TODO.md
unchanged — they're still the right home for those concerns and
co-locating with follow-ups gives all "things to verify" one place.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude @codex
ci(docs): bump lychee-action and lychee for sitemap URL extraction (#176
d580c05 
)

* ci(docs): bump lychee to v0.24.0 to fix sitemap URL extraction

The first Docs workflow run on main after #173 (commit f3f3e5e) failed
in deploy → "Check deployed docs links" with "No files found for this
input source". Root cause: the previous step ran lychee --dump on the
deployed sitemap URL, but lychee 0.23.0 (the lycheeverse/lychee-action
v2 default) only extracts <a href> from HTML and matching patterns from
markdown — it does not parse <loc> entries from XML sitemaps. The dump
produced an empty list and the follow-up --files-from step had nothing
to read.

Upstream already fixed this. lycheeverse/lychee#2071 (merged
2026-03-13, tagged in v0.24.0 on 2026-04-24) adds <loc> extraction
from sitemap.xml, closing lycheeverse/lychee#2062 and #1819. Verified
locally on 0.24.0:

  $ lychee --version
  lychee 0.24.0
  $ lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Pin LYCHEE_VERSION at the workflow env level and reference it from
every lychee-action call so future bumps are one-line. v0.24.0's
breaking changes are in lychee-lib (the Rust API consumers); the CLI
surface we use is unchanged.

Co-authored-by: Claude <noreply@anthropic.com>

* ci(docs): bump lychee-action and lychee for sitemap URL extraction

Replace the previous v0.24.0 bump with the only combination that
actually works against the current lychee release pipeline:

  - lycheeverse/lychee-action SHA 8646ba3 (tagged v2.8.0) → faea714
    (post-v2.8.0 master). Adds subfolder-aware install needed for any
    lychee 0.24.x tarball.
  - LYCHEE_VERSION 'v0.24.0' → 'v0.24.1'.

Why both moves:

* lychee 0.24.0 added <loc> extraction from XML sitemaps
  (lycheeverse/lychee#2071), which is what the deploy and check-deployed
  jobs need to feed --files-from. lychee 0.23.0 dumps zero links from a
  sitemap, which is what produced the "No files found for this input
  source" failure on f3f3e5e.
* lychee 0.24.0's release tarball was repackaged with a top-level
  subfolder AND the asset filename was renamed to
  lychee-lychee-v0.24.0-{arch}-... — both incompatible with
  lychee-action v2.8.0's hardcoded download URL and flat-extract logic.
* lychee 0.24.1 (released the same day) reverted to the original asset
  filename but kept the subfolder layout AND kept the sitemap fix.
* lychee-action faea714 (unreleased; current HEAD of master) bumps the
  default to 0.24.1 and adds subfolder-aware install. Pinning the SHA
  is the same security model we already use for v2.8.0.

The combination 8646ba3 + 'latest' or 8646ba3 + 'v0.24.x' both fail.
The combination faea714 + 'v0.24.1' works.

Verified locally:

  $ lychee-v0.24.1/lychee --version
  lychee 0.24.1
  $ lychee-v0.24.1/lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Co-authored-by: Claude <noreply@anthropic.com>

* ci(docs): add TODO(lychee-action-sha-pin) marker

Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.

Co-authored-by: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Codex <codex@openai.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
docs(todo): track small follow-ups and external deps in TODO.md (#179)
6b8e3e2 
Repurpose the existing TODO.md from a thin roadmap pointer + per-PR
checklist into a periodic-review tracker for small items that don't
warrant a full roadmap design doc:

- External dependencies waiting on upstream fixes (e.g., upstream
  releases, library bugs we're working around).
- Internal consistency or polish work.

Each entry uses a stable kebab-case anchor so code can link back with a
matching `TODO(<topic>): … — see TODO.md "<heading>"` marker, kept
greppable (`grep -rn 'TODO(<topic>)' .`). Document this convention in
the file so future authors don't reinvent it.

Add the one open item we have today: the lychee-action SHA pin
introduced in #176 currently points at master HEAD (faea714) because
the v0.24.x compatibility fix is unreleased. Tracked here so it can be
reverted to a tag SHA on the next lychee-action release.

Wire TODO.md into AGENTS.md "Shared conventions" (right after
DEPRECATED.md, since both are ledgers of work to address eventually)
and refresh its row in PROJECT_STRUCTURE.md to describe the dual role.

The roadmap pointer and the stale-docs checklist remain in TODO.md
unchanged — they're still the right home for those concerns and
co-locating with follow-ups gives all "things to verify" one place.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
ci(docs): bump lychee-action and lychee for sitemap URL extraction (#176
37fd883 
)

* ci(docs): bump lychee to v0.24.0 to fix sitemap URL extraction

The first Docs workflow run on main after #173 (commit f3f3e5e) failed
in deploy → "Check deployed docs links" with "No files found for this
input source". Root cause: the previous step ran lychee --dump on the
deployed sitemap URL, but lychee 0.23.0 (the lycheeverse/lychee-action
v2 default) only extracts <a href> from HTML and matching patterns from
markdown — it does not parse <loc> entries from XML sitemaps. The dump
produced an empty list and the follow-up --files-from step had nothing
to read.

Upstream already fixed this. lycheeverse/lychee#2071 (merged
2026-03-13, tagged in v0.24.0 on 2026-04-24) adds <loc> extraction
from sitemap.xml, closing lycheeverse/lychee#2062 and #1819. Verified
locally on 0.24.0:

  $ lychee --version
  lychee 0.24.0
  $ lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Pin LYCHEE_VERSION at the workflow env level and reference it from
every lychee-action call so future bumps are one-line. v0.24.0's
breaking changes are in lychee-lib (the Rust API consumers); the CLI
surface we use is unchanged.


* ci(docs): bump lychee-action and lychee for sitemap URL extraction

Replace the previous v0.24.0 bump with the only combination that
actually works against the current lychee release pipeline:

  - lycheeverse/lychee-action SHA 8646ba3 (tagged v2.8.0) → faea714
    (post-v2.8.0 master). Adds subfolder-aware install needed for any
    lychee 0.24.x tarball.
  - LYCHEE_VERSION 'v0.24.0' → 'v0.24.1'.

Why both moves:

* lychee 0.24.0 added <loc> extraction from XML sitemaps
  (lycheeverse/lychee#2071), which is what the deploy and check-deployed
  jobs need to feed --files-from. lychee 0.23.0 dumps zero links from a
  sitemap, which is what produced the "No files found for this input
  source" failure on f3f3e5e.
* lychee 0.24.0's release tarball was repackaged with a top-level
  subfolder AND the asset filename was renamed to
  lychee-lychee-v0.24.0-{arch}-... — both incompatible with
  lychee-action v2.8.0's hardcoded download URL and flat-extract logic.
* lychee 0.24.1 (released the same day) reverted to the original asset
  filename but kept the subfolder layout AND kept the sitemap fix.
* lychee-action faea714 (unreleased; current HEAD of master) bumps the
  default to 0.24.1 and adds subfolder-aware install. Pinning the SHA
  is the same security model we already use for v2.8.0.

The combination 8646ba3 + 'latest' or 8646ba3 + 'v0.24.x' both fail.
The combination faea714 + 'v0.24.1' works.

Verified locally:

  $ lychee-v0.24.1/lychee --version
  lychee 0.24.1
  $ lychee-v0.24.1/lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45


* ci(docs): add TODO(lychee-action-sha-pin) marker

Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.


---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
docs(todo): track small follow-ups and external deps in TODO.md (#179)
e2f933f 
Repurpose the existing TODO.md from a thin roadmap pointer + per-PR
checklist into a periodic-review tracker for small items that don't
warrant a full roadmap design doc:

- External dependencies waiting on upstream fixes (e.g., upstream
  releases, library bugs we're working around).
- Internal consistency or polish work.

Each entry uses a stable kebab-case anchor so code can link back with a
matching `TODO(<topic>): … — see TODO.md "<heading>"` marker, kept
greppable (`grep -rn 'TODO(<topic>)' .`). Document this convention in
the file so future authors don't reinvent it.

Add the one open item we have today: the lychee-action SHA pin
introduced in #176 currently points at master HEAD (faea714) because
the v0.24.x compatibility fix is unreleased. Tracked here so it can be
reverted to a tag SHA on the next lychee-action release.

Wire TODO.md into AGENTS.md "Shared conventions" (right after
DEPRECATED.md, since both are ledgers of work to address eventually)
and refresh its row in PROJECT_STRUCTURE.md to describe the dual role.

The roadmap pointer and the stale-docs checklist remain in TODO.md
unchanged — they're still the right home for those concerns and
co-locating with follow-ups gives all "things to verify" one place.

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
donbeave added a commit that referenced this pull request May 7, 2026
@donbeave @claude
ci(docs): bump lychee-action and lychee for sitemap URL extraction (#176
bc6dd35 
)

* ci(docs): bump lychee to v0.24.0 to fix sitemap URL extraction

The first Docs workflow run on main after #173 (commit f3f3e5e) failed
in deploy → "Check deployed docs links" with "No files found for this
input source". Root cause: the previous step ran lychee --dump on the
deployed sitemap URL, but lychee 0.23.0 (the lycheeverse/lychee-action
v2 default) only extracts <a href> from HTML and matching patterns from
markdown — it does not parse <loc> entries from XML sitemaps. The dump
produced an empty list and the follow-up --files-from step had nothing
to read.

Upstream already fixed this. lycheeverse/lychee#2071 (merged
2026-03-13, tagged in v0.24.0 on 2026-04-24) adds <loc> extraction
from sitemap.xml, closing lycheeverse/lychee#2062 and #1819. Verified
locally on 0.24.0:

  $ lychee --version
  lychee 0.24.0
  $ lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45

Pin LYCHEE_VERSION at the workflow env level and reference it from
every lychee-action call so future bumps are one-line. v0.24.0's
breaking changes are in lychee-lib (the Rust API consumers); the CLI
surface we use is unchanged.


* ci(docs): bump lychee-action and lychee for sitemap URL extraction

Replace the previous v0.24.0 bump with the only combination that
actually works against the current lychee release pipeline:

  - lycheeverse/lychee-action SHA 8646ba3 (tagged v2.8.0) → faea714
    (post-v2.8.0 master). Adds subfolder-aware install needed for any
    lychee 0.24.x tarball.
  - LYCHEE_VERSION 'v0.24.0' → 'v0.24.1'.

Why both moves:

* lychee 0.24.0 added <loc> extraction from XML sitemaps
  (lycheeverse/lychee#2071), which is what the deploy and check-deployed
  jobs need to feed --files-from. lychee 0.23.0 dumps zero links from a
  sitemap, which is what produced the "No files found for this input
  source" failure on f3f3e5e.
* lychee 0.24.0's release tarball was repackaged with a top-level
  subfolder AND the asset filename was renamed to
  lychee-lychee-v0.24.0-{arch}-... — both incompatible with
  lychee-action v2.8.0's hardcoded download URL and flat-extract logic.
* lychee 0.24.1 (released the same day) reverted to the original asset
  filename but kept the subfolder layout AND kept the sitemap fix.
* lychee-action faea714 (unreleased; current HEAD of master) bumps the
  default to 0.24.1 and adds subfolder-aware install. Pinning the SHA
  is the same security model we already use for v2.8.0.

The combination 8646ba3 + 'latest' or 8646ba3 + 'v0.24.x' both fail.
The combination faea714 + 'v0.24.1' works.

Verified locally:

  $ lychee-v0.24.1/lychee --version
  lychee 0.24.1
  $ lychee-v0.24.1/lychee --dump https://jackin.tailrocks.com/sitemap-0.xml | wc -l
  45


* ci(docs): add TODO(lychee-action-sha-pin) marker

Companion to #179, which establishes the convention. Mark the spot
where the SHA pin needs to be reverted once lycheeverse/lychee-action
cuts a tagged release at or after faea714, with a back-link to the
tracked entry in TODO.md so a single grep finds both ends.


---------

Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@donbeave