Audit and refresh todo/ issue tracker - #1567

Verified against origin/main at db76410 (types/byte_set: toRangeMap carries a boolean, not an FSM payload (#1566)), at head 118697e9. Docs-only, so no build/test gates apply and no CHANGELOG entry is needed (§8.3) — none was added, correctly. Every one of the 20 changed paths is under a todo/ directory, so "no behavior changes" holds.

Most of this audit is genuinely accurate — I recomputed a sample rather than taking the descriptions on trust, and the corrections land. But there is one real defect and the summary's numbers do not reconstruct.

1. Deleting nanvm-lib/todo/86.md strands an inbound link

nanvm-lib/todo/numeric-operator-home.md:50, which this PR does not touch:

- [86](86.md) — coercion traits for a future VM, a different layer

Comparing broken-link sets (not counts) between main and this head, nanvm-lib/todo/numeric-operator-home.md: [86](86.md) is a genuinely new entry. Either drop that bullet from numeric-operator-home.md or repoint it at nanvm-lib/src/vm/{string,number}_coercion.rs, the way todo/plan/capl.md was repointed in this same PR.

For completeness on the link sets, since counts alone would mislead here — 129 broken on main, 127 at this head:

• Fixed (3, all genuine): todo/plan/capl.md × 2 (../141-universal-type-system.md, ../143-rtti-data.md) and fjs/ci/todo/ci-integration-tests.md (669-scenario-testing.md).
• New (2, only 1 real): the 86.md one above, plus fjs/djs/todo/66e-parser-container-stack-bookkeeping.md: [' | '{') => (top: JsonStackElement) => …. That second one is a bin/linkcheck.mjs false positive, not your bug — it is the TypeScript union (status: '[' | '{') inside a \``tsfence, present verbatim onmaintoo (line 124 there, 110 here). It only surfaces now because the real broken linki157-json-djs-shared-core` that used to sit ahead of it in the scan is gone. No action needed.

2. The summary's three numbers do not reconstruct

• "340 todo/{slug}.md issue files" — on main I count 284 paths matching (^|/)todo/[^/]+\.md$ (the literal todo/{slug}.md reading), or 336 counting every .md at any depth under a todo/ directory (which folds in todo/lang/, todo/blocked/, todo/plan/, todo/demo/). Neither is 340. At this head they are 281 and 333.

• "Corrected 12 files" — git diff --name-status db76410 118697e9 gives 17 M and 3 D, not 12 and 3. All 17 look like real corrections, so this reads as an undercount rather than padding, but the number should match.

• "no .then( usage remains under fjs/effects" — one does:

  fjs/effects/node/memory/proof.mjs:37:        const result = await run(read(key)).then(
  

  This is the justification given for deleting fjs/todo/132.md, whose item 2 is "Use async functions and await instead of .then". The deletion is still defensible on other grounds — 132 is titled exec improvements and there is no exec module in the tree at all, and its item 1 (module.f.mjs over module.ts) is satisfied since no module.ts exists anywhere under fjs/. But the stated reason overreaches, and the honest version is "the referent is gone", not "item 2 is done".

What I verified and found correct

• fjs/types/todo/195.md deletion. Accurate, and better justified than the summary lets on: listToVec → tryListToVec → unpackListToVec = compose(foldAbsorbing(tryUnpackConcat(...)))(...), and the JSDoc on unpackListToVec states outright that foldAbsorbing "reduces as a balanced binary tree, so each merge joins two runs of comparable size — O(n log n) … instead of the O(n²) a left fold would spend". That is precisely the transformation 195 asked for, not merely an incidental use of foldAbsorbing.
• nanvm-lib/todo/86.md deletion (content, not the link). nanvm-lib/src/vm/any/mod.rs calls self.dispatch(StringCoercion) / self.dispatch(NumberCoercion) against pub struct NumberCoercion / StringCoercion — implemented as Dispatch visitors, as claimed.
• fjs/media/json/todo/parser-unexpected-token.md line refresh. All ten numbers are exactly right against main's fjs/media/json/parser/module.f.mjs: the nine 'unexpected token' literals at 133, 138, 148, 155, 162, 168, 175, 183, 192, and the stray 'error' at 35.
• todo/plan/capl.md. Both replacement targets resolve — fjs/types/rtti/data/module.f.mjs and fjs/types/todo/141.md both exist.
• The fjs/cas/todo/ trio. fjs/cas/cli/module.f.mjs exists and imports/uses writeFromStream; FileCas really does expose url: (v: Vec) => string in fjs/cas/types.ts. The fileKvStore → fileCas rename and the CLI relocation are both correct, and dropping stale line ranges in favour of naming the method is the right call.
• The Deno CI report. .github/workflows/ci.yml:388 and fjs/ci/config/module.f.mjs:34 both pin 2.9.5, not 2.8.3, and fjs/ci/deno/module.f.mjs really does run the deno run -A … npm:functionalscript@… test smoke test (line 26) before deno install --frozen (line 27) — so the "needs re-verification" status and the note are both justified.

Fixing the numeric-operator-home.md link and correcting the three numbers would make this clean.

One heads-up

#1569 deletes fjs/media/json/todo/parser-unexpected-token.md, which this PR modifies. Whichever lands second hits a modify/delete conflict; resolving in favour of the deletion is correct, and it costs this PR nothing since the line-number refresh becomes moot.

Thanks for the thorough recheck — all three points are fixed:

1. Dangling 86.md link — nanvm-lib/todo/numeric-operator-home.md's Related section now points at src/vm/string_coercion.rs / src/vm/number_coercion.rs directly instead of the deleted file.
2. .then( overreach on fjs/todo/132.md — you're right, that stray await run(read(key)).then( in fjs/effects/node/memory/proof.mjs means the ".then is gone" framing overreached. The deletion is still correct, but for the reason you gave: there's no exec module anywhere in the tree (the file was titled "exec improvements") and no module.ts under fjs/ either, so both of its listed items are moot regardless. Updated the PR description to say that instead.
3. Number mismatches — description now says 283/335 total files and 17 modified (not 340/12).

Also, no action needed on the #1569 modify/delete heads-up on parser-unexpected-token.md — agreed the deletion should win there and it costs this PR nothing.

Generated by Claude Code

Re-reviewed at e4eb1318, baseline origin/main = 60d04cb7 (media/json/parser: hoist the repeated unexpected-token error (#1569)). I re-derived each of the four open items from the tree rather than taking the claimed fixes on trust.

Approving. Three of the four are genuinely closed; the fourth is a residual off-by-one in the PR description only, called out below as non-blocking.

1. Stranded [86](86.md) — fixed

nanvm-lib/todo/86.md is still deleted, and nanvm-lib/todo/numeric-operator-home.md's Related section now points at src/vm/string_coercion.rs / src/vm/number_coercion.rs directly. git grep '86\.md' over the whole tree returns one hit, fjs/sul/todo/id-prefix-tag-factory.md:60 → ./186.md, which is a different file and resolves.

Comparing broken-link sets (bin/linkcheck.mjs, normalized and sorted, PR vs fs-main at 60d04cb7), the PR is a strict improvement on real links — three removed, none added:

- fjs/ci/todo/ci-integration-tests.md: [669-scenario-testing.md](669-scenario-testing.md)
- todo/plan/capl.md: [i141-universal-type-system](../141-universal-type-system.md)
- todo/plan/capl.md: [i143-rtti-data](../143-rtti-data.md)

The one set entry that appears only on the PR side is a linkcheck.mjs artifact, not a link: fjs/djs/todo/66e-parser-container-stack-bookkeeping.md:110, (status: '[' | '{') => (top: JsonStackElement) => ..., which sits inside a ```ts fence (fence opens at line 67). The checker does not skip fenced code, so ['[' | '{') parses as a link. Same class of false positive the checker already produces on main; not a defect in this PR.

2. #1569 conflict — resolved toward the deletion

#1569 deleted fjs/media/json/todo/parser-unexpected-token.md, which the earlier revision of this PR modified. After the merge the file is absent from the PR tree and absent from git diff --name-status 60d04cb7 HEAD, i.e. the resolution kept the deletion rather than resurrecting the file. git grep parser-unexpected-token over the tree: no hits. Clean.

3. "Corrected 17 files" — now accurate

$ git diff --name-status 60d04cb7 e4eb1318 | awk '{print $1}' | sort | uniq -c
   3 D
  17 M

Matches the description's "Deleted 3 / Corrected 17" exactly. The earlier "12" figure is gone.

4. The .then( claim — gone

The assertion that no .then( remains under fjs/effects is no longer made anywhere in the PR (the scope shrank considerably from 118697e9; AGENTS.md and friends are no longer touched). git grep 'then(' over *.md returns only unrelated language-spec and scenario text. Worth noting the underlying fact is still false — fjs/effects/node/memory/proof.mjs:37 has await run(read(key)).then( — so if that claim comes back in a future revision it is still wrong.

Non-blocking: the file counts are off by one after the merge

The description says "283 files matching that literal pattern; 335 counting every .md at any depth under a todo/ directory". Recomputed from git ls-tree -r --name-only:

283/335 is the pre-deletion count before this branch merged main; #1569's deletion of fjs/media/json/todo/parser-unexpected-token.md moved both down by one. So the audited universe is 282/334, not 283/335. This is prose in the PR description, nothing that lands in the repo, so it is not worth another round — just drop each by one if you touch the description again.

What I checked beyond the four items

• The three deletion rationales, re-derived from source rather than from the files' own text:
  • fjs/types/todo/195.md — asked for a balanced-tree concatenation order; unpackListToVec (fjs/types/bit_vec/module.f.mjs:250) is compose(foldAbsorbing(...))(nullableMap(pack)), and foldAbsorbing is exactly that reduction. Genuinely landed.
  • fjs/todo/132.md — git ls-files fjs has no exec module and no module.ts; both of its items are moot.
  • nanvm-lib/todo/86.md — nanvm-lib/src/vm/any/mod.rs:64,68 dispatch to StringCoercion / NumberCoercion. Implemented.
• CHANGELOG: every one of the 20 touched paths is under a todo/ directory, so no entry is required, and none is added. Correct per §8.3.
• No code, build, or test surface is touched, so the TypeScript and Rust gates do not apply here.

Re-review at b05e4bd6806ea0f39ce6a04342110b6a91525fb4. Previously approved at e4eb1318.

The delta since the last head is merge-only — git diff e4eb1318 b05e4bd6 is exactly the two Markdown files from b3544773 (#1570) — but that merge adds a todo/{slug}.md file, so I recomputed the two things it could move: the counts and the broken-link sets. Both against a fresh baseline at this PR's merge-base, b35447738e756288e6e1da08404b407ec5a9ab7d (= origin/main at the time of the run).

The count staleness I flagged last round is now resolved by the merge. Recomputed at the merge-base:

fjs/media/todo/shared-lock-format.md is the file that closed the off-by-one. The description's figures now match the tree exactly.

git diff --name-status <merge-base> HEAD is 17 M, 3 D — matches "Corrected 17 files / deleted 3" as written.

Broken links, comparing sets rather than counts: 122 on main → 120 here. Four real ones go away —

fjs/ci/todo/ci-integration-tests.md      → 669-scenario-testing.md
fjs/djs/todo/66e-parser-container-stack-bookkeeping.md → todo.md (i157)
todo/plan/capl.md                        → ../141-universal-type-system.md
todo/plan/capl.md                        → ../143-rtti-data.md

— and the two lines that appear only on the PR side are the link checker mis-parsing a TypeScript snippet inside a fenced block in 66e-parser-container-stack-bookkeeping.md ((status: '[' | '{') => ... at line 110). Not links. So the real set strictly improves and nothing is stranded, including the [86](86.md) repoint after nanvm-lib/todo/86.md was deleted.

Docs-only throughout — every touched path is under a todo/ directory — so no changelog entry and no build or test gate applies.

One note for whenever this lands: origin/main has since advanced to 6bd36947 (#1573), which deletes fjs/media/json/todo/bigint-parse-serialize.md and edits several other todo/*.md. That will shift the description's counts again on the next merge. The numbers are PR prose only and I would not hold the PR for them.

Approving.