Add task to split AGENTS.md into scoped documents - #1560

Reviewed at cf633320a487727d2bed3fb55ef4e90167c5bd48, merge-base origin/main 2df303a9. Draft, which per the standing arrangement I review normally.

Contents are a single new file, todo/agents-md-split.md (+144), matching the title. Docs-only, so no changelog entry is needed (§8.3) and none is added — correct. node bin/linkcheck.mjs gives a broken-link set identical to 2df303a9 (151 lines each, diff clean), so none of the new links are dead.

A proposal's value is in its numbers, so I re-derived all of them.

What reproduces

• "AGENTS.md is ~1300 lines" — wc -l gives 1313.
• "the twelve-row test-runner table" in §1.4 — exactly 12 data rows, from npm test to bunx functionalscript test.
• Every section number and title in the destination map matches the real file: §1 Development environment (§1.4 "Ways to run the FunctionalScript test suite", §1.5 Updating dependencies, §1.6 Rust commands), §2 Everyday workflow, §3 Testing and proof coverage, §4 Documentation, §5 Design principles with §5.1 through §5.8 all present, §6 Coding style with §6.1–6.6 and §6.7 Rust, §7 Issues (todo/), §8 Pull requests with §8.1–8.4. No phantom sections, no gaps.
• "~700 lines of TypeScript/JSDoc coding style" that a Rust agent pays for — §4 spans lines 249–338 and §6.1–6.6 spans 524–1163, so ~730. Fair, and conservative if you also count §3.
• Every referenced path exists: CONTRIBUTING.md, todo/README.md, changelog/README.md, fjs/fsc/README.md. fjs/fsc/README.md really does hold the extension contract, so parking those details there is right. fjs/AGENTS.md, nanvm-lib/AGENTS.md and doc/design.md are absent, as intended — they are the output.
• CONTRIBUTING.md really does declare the anti-drift rule the proposal credits it with, near enough verbatim: "it links to AGENTS.md rather than restating it, so the two cannot drift apart" (CONTRIBUTING.md:10–11).

Two corrections

1. The inbound-link inventory identifies the wrong files.

Only four files link to AGENTS.md# anchors today (CONTRIBUTING.md and a few todo/ files), so no redirect stubs are needed

Four is right — but the parenthetical is not. Excluding this PR's own file, the nine AGENTS.md# references live in exactly these four:

So it is one todo/ file, not "a few", and two of the four are README.mds. docker/README.md is the one that matters: it is named nowhere else in the proposal, and an implementer who takes the parenthetical at face value will grep CONTRIBUTING.md and todo/ and miss it. changelog/README.md is at least listed under Related, though as an absorber of content rather than as a link source.

Worth noting too that fjs/bnf/todo/669-… links to two deep ####-level anchors inside §6.3 and §5.2. The §5.2 one cannot be repointed until the §5 open question is decided, which is consistent with the ordering the task list already has, but it means "update the links to the new homes" is gated on that decision rather than mechanical.

2. The §8 row is already one subsection out of date.

The destination map's last row splits §8 as "§8.3 entry rules and §8.4 versioning into changelog/README.md; §8.1–8.2 stay as the root brief". #1561, open right now and by you, adds §8.5 Commit messages — about 50 lines covering title form, the Changelog: section, and squash-merge policy. Whichever of the two lands second, §8.5 has no destination. It is not obviously changelog/README.md either: the title-and-squash half is a PR-process rule, closer to CONTRIBUTING.md, and todo/commit-message-enforcement.md will eventually lint against wherever it ends up. Worth adding a row now while both are in flight.

Related: #1561 also adds AGENTS.md# anchor links from CONTRIBUTING.md, todo/commit-message-enforcement.md and todo/commit-message-standard.md, which takes the inventory above from four files to six and makes "a few todo/ files" retroactively true. Either way the number in this file will need a refresh once #1561 merges.

One thing I could not verify

"Agent tooling (Claude Code, Codex, Cursor) discovers nested AGENTS.md files when working inside a subtree" is the load-bearing assumption for co-locating the scoped documents, and it is a claim about three external tools whose behaviour I cannot check from this repo. I am not disputing it — just flagging that it is the one premise here resting on nothing in-tree, and it is worth a line of evidence given the whole co-location design falls back to "a file nobody reads" if any of the three does not.

The structure of the proposal is sound and the destination map is the useful part — it is specific, it is section-by-section, and apart from §8.5 it accounts for the whole file. The two open questions are the genuinely open ones, and "move text, don't rewrite it" is the right constraint for making the follow-up PR reviewable. Fix the inbound-link parenthetical and add the §8.5 row and this is good to go.

Re-reviewed at 97dec7e4 against origin/main = de959db7 (types/nullable: derive map from match… (#1558)). Both findings from the cf633320 round are fixed. I recomputed the inventory from scratch rather than reading the new list, since main moved in between.

Both prior findings resolved

1. Inbound-link inventory. grep -rn 'AGENTS\.md#' --include='*.md' on de959db7 returns exactly four files, and they are exactly the four now named:

The "(five anchors)" parenthetical is right on the nose. The forward-looking note is right too: I checked #1561's tree at d38de23f, and it adds AGENTS.md# links in CONTRIBUTING.md, todo/commit-message-enforcement.md and todo/commit-message-standard.md — "CONTRIBUTING.md and two commit-message todo/ files", exactly. Telling the implementer to re-run the grep is the right call given the set has already moved once.

2. §8.5 row. The destination map now carries it, marked in-flight with the PR link, and the §8 row's "§8.3 entry rules and §8.4 versioning into changelog/README.md; §8.1–8.2 stay as the root brief" now composes with it to cover all of §8. Sending §8.5 to CONTRIBUTING.md rather than changelog/README.md is a defensible split and the reason given (PR-process vs changelog content) holds; the reminder to repoint todo/commit-message-enforcement.md's links in the same PR is a real consequence that would otherwise be missed.

Also re-verified on this head

• node bin/linkcheck.mjs on 97dec7e4 vs de959db7: identical broken-link sets, 129 on both. All links in the new file resolve.
• AGENTS.md on de959db7 is still 1313 lines, so "~1300" and the "~700 lines" cost figure still hold.
• The nested-AGENTS.md premise is no longer load-bearing — the rewrite makes the root brief's explicit links the mechanism and demotes auto-discovery to an optimization, which is the right shape for a claim about third-party tooling. The agents.md citation checks out (the page's monorepo section reads "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence…").
• The §5 open question the bnf caveat depends on is present and unresolved, as the caveat assumes.
• No changelog entry needed — todo/-only, per §8.3.

One nit, not a blocker

the bnf issue links to deep #### anchors inside §5.2 and §6.3

Only one of the two is a deep anchor. fjs/bnf/todo/669-bnf-matcher-shared-core.md:152 points at #place-curried-partial-applications-at-their-dependencys-scope, which is AGENTS.md:1014, a #### inside §6.3 — that one is as described. But line 170's #52-the-api-is-the-most-important-part-of-quality is AGENTS.md:358, the ### 5.2 section heading itself, not something nested inside it. The action doesn't change (it still can't be repointed until the §5 question is decided), so this is just the description; "a deep #### anchor inside §6.3, and §5.2's own heading" would be accurate.

Approving — the substance is sound, the two corrections landed, and the remaining nit is a wording detail in a caveat.