fix(ci): clear the lint, test, and doc gates

[John-David Dalton (jdalton)]

LLM Description written by Claude Code:claude-fable-5

Actions needed

• Review and merge when CI is green. Auto-merge is deliberately NOT enabled: this repo's main ruleset has no required status checks, so --auto would merge immediately instead of waiting for CI. A CI-repair PR should not land unverified.
• Decide on a fleet cascade run. Two of the five failures on main are NOT fixable here — see What this does not fix below. main stays red on the Check job until a cascade lands.

What was red

main has been failing since before today's merges. The same failure set appears at 0bd8b9e98 and at fb25a3ffe, so none of it came from a recent PR. Five independent causes; this PR fixes the three that live in repo-owned code.

1. lint — 18 max-comment-block-lines errors across 14 files

A newly cascaded rule caps an inline comment block at 20 lines. Nothing is suppressed and the rule is untouched — each site is restructured on its own merits:

treatment	sites
relocated to a doc	cmd-manifest-cdxgen.mts (~70 lines of pasted cdxgen --help)
split at paragraph boundaries	bazel-repo-discovery.mts, external-tools-install.mts, meow.mts
repaired damaged content	npm-packages.mts (×2), vfs-extract.mts
trimmed to the contract	spawn.mts, builder.mts (×2), checkpoint-manager.mts, platform-targets.mts, compress-facts.mts, cli-execution.mts (×2), workspace-helper.mts, basics/vfs-extract.mts

Two of these turned up real defects rather than just long prose:

• dlx/vfs-extract.mts had extractExternalTools' docblock stranded above MAX_EXTRACTION_DEPTH instead of above the function. It now sits on the function it documents.
• npm-packages.mts had two docblocks shredded by an earlier JSDoc reflow. One lost its node_modules/ archive tree into a bogus @cyclonedx JSDoc tag, so half the tree rendered as an unknown tag's body. Both are rewritten as prose saying the same thing.

2. Test — five assertions reading the wrong argument index

perform-reachability-analysis.mts:288 calls spawnCoanaDlx(coanaArgs, { … }) with two arguments. Two test files read the options bag at mock.calls[0][2], which is always undefined, so every one threw TypeError: Cannot read properties of undefined. Production is correct; the tests move to index 1.

The diagnosis I started from named one assertion in perform-reachability-analysis-coana.test.mts. There are five, across two files — four more in the sibling perform-reachability-analysis.test.mts. Only one surfaced in CI because the Test job shards: that run executed 55 of 646 test files. A local full-suite run shows all five.

3. claude-md-repo-section-is-a-bullet-index — one over-long bullet

CLAUDE.md:151 ran 230 chars against the 200 cap. It stated two separate rules — the X.Y.Z-prerelease hint in package.json and the notes accruing under CHANGELOG's ## [Unreleased] — so it becomes two bullets, which is what the check asks for anyway ("one rule per bullet").

What this does not fix

The remaining two failures are cascade lag on fleet-canonical files, and the fixes already exist in the shared template. scripts/fleet is linguist-generated=true in this repo's .gitattributes — the marker the fleet fork guard reads — and every change to it in this repo's history arrived as a chore(wheelhouse): cascade template@<sha> commit. Hand-authoring a fix here would be a local fork that the next cascade overwrites.

check-registrations-resolve and commits-have-no-ai-attribution

• check-registrations-resolve fails because scripts/fleet/check/tests-read-canonical-sources.mts is wired into no runner. The template already registers it, with a note that it no-ops cleanly in member repos that have no template/ tree. This repo's mirror predates that line.
• commits-have-no-ai-attribution fails in CI for a shallow-clone reason. It cannot be fixed by fetching full history: with full history it finds 20 old, already-published commits carrying Co-authored-by: and 🤖 Generated with [Claude Code] tag lines. Rewriting published main history is out of scope. The template has already rewritten this check — its default scope now reads origin/<default> and drops every finding at or below the release boundary, with full history moved behind a new --all flag. That clears exactly this case.

Scope of the lag: 115 files differ between this repo's scripts/fleet and the template's copy. The last cascade in was template@79a0d8d03; the template is now at template@f6cf95d3c.

Judgment calls

The comment restructuring. The rule's own message says to keep the constraint at the code and move the discussion into a doc behind a one-line pointer, so that is what the cdxgen --help dump got — docs/references/repo/cdxgen-flags.md, next to the existing repo reference doc. Splitting a run at its existing paragraph breaks is not a dodge here: the rule already ends a block at a blank line specifically because that is how a reader sees them, and the split blocks are genuinely separate facts. Where a block was one long JSDoc, only @example bodies that restated the signature came out, with any fact unique to the example folded into @param or @returns.

compress-facts.mts looked like the one case worth an inline socket-lint: allow long-comment-block suppression — every paragraph is a distinct constraint a caller can break. That turned out to be impossible by design: no-malformed-bypass-marker requires the marker within 12 lines of the code it exempts, which a 29-line block cannot satisfy. So it was tightened instead, and all five constraints survive — why compression is streamed off-thread, why the .br is a sibling rather than a temp-dir path, that it adds no new race, and the mandatory cleanup(). No suppression was added anywhere in this PR.

Scoping the attribution check rather than unshallowing. Confirmed and left alone. Unshallowing swaps the shallow-clone failure for 20 findings in published history, and rewriting main is not on the table. Scoping is the right shape — and the template already implements it, with a release-boundary freeze that is better than the --unpushed narrowing I had been pointed at. That is why it belongs in a cascade rather than here.

Verification

Run locally against this branch:

• pnpm run lint --all → passes, 0 errors (was 129 warnings / 18 errors).
• pnpm run test → 7533 passed, 625 of 646 files. The single failure is constants.test.mts asserting rootPath contains socket-cli, which is false only because the verification worktree is not named that. It passes in CI and in a normal checkout. That test is coupled to the checkout directory name, which is worth fixing separately.
• pnpm run check --all → lint.mts and claude-md-repo-section-is-a-bullet-index.mts now pass. Still failing: the two cascade-lag checks above, plus dispatch-table-is-current and path-tools-are-at-pinned-version, which are local-environment artifacts and did not fail in CI.

---

Note

Low Risk
Comment/doc/test-only changes plus a reference doc move; no runtime behavior changes except corrected test mocks aligned with existing spawnCoanaDlx arity.

Overview
Clears three independent main failures in repo-owned code: the max-comment-block-lines lint rule, reachability unit tests, and the CLAUDE.md bullet-length check.

Lint (18 errors, 14 files) — Long comment/JSDoc blocks are shortened or relocated without disabling the rule. The pasted cdxgen 11.2.7 --help text moves from cmd-manifest-cdxgen.mts to docs/references/repo/cdxgen-flags.md, with a one-line pointer in source. Other sites are split at paragraph breaks, trimmed to the API contract, or rewritten where prior reflow damaged docs (e.g. npm-packages.mts bogus @cyclonedx tag; dlx/vfs-extract.mts docblock moved onto extractExternalTools).

Tests — Five assertions in perform-reachability-analysis*.test.mts read spawnCoanaDlx options at mock.calls[0][2]; production passes options at index 1, so they now match (coanaArgs, { … }).

Docs — CLAUDE.md v1.x release bullet is split into two bullets (prerelease hint vs CHANGELOG ## [Unreleased]) to satisfy the 200-character cap.

Does not fix cascade-lag fleet checks (check-registrations-resolve, commits-have-no-ai-attribution) on main.

^{Reviewed by Cursor Bugbot for commit b03b5fb. Configure here.}