fix: three gates that could report success without checking

[kevintseng]

Three gates that could report success without checking anything. Each was found
by the previous one — the chain starts with a poll I watched land on PR #190.

1. wait-for-checks.mjs could call a partial matrix green

The script exists because gh pr checks' exit code cannot be trusted as a
verdict. It carried the same hole one level down: it asked "is pending zero?"
and returned 0 when the answer was yes. That is sound only if every check has
registered, and GitHub registers them in batches.

Observed, on PR #190:

2026-08-23T05:42:17Z pass=0 pending=1 fail=0 not-passed=[Analyze (javascript-typescript) [pending/IN_PROGRESS]]
2026-08-23T05:42:48Z pass=0 pending=12 fail=0 not-passed=[... twelve rows ...]

Thirty seconds where only one of thirteen legs existed. Had that row been
pass at that instant, the script would have printed
RESULT pass=1 fail=0 pending=0 exit=0.

A PASS now also requires the set of check names to be identical across two
consecutive polls. A FAIL is still immediate. Keyed on the name set, not the
count, because concurrency.cancel-in-progress can swap one run's legs for
another's at the same cardinality. Cost: one extra poll interval on a green run.

2. check-doc-claims checked the parent and ignored the child

It verified every memesh <word> names a registered command — capturing only
the first word. So memesh kg backfill read as kg, a real command, and
passed. The real name is kg backfill-relations.

The gate found a live one the moment it was added:
docs/api/API_REFERENCE.md:803 told readers the evidence edges are drawn by
memesh kg backfill. Fixed in the same commit.

Per-parent sets, not one flat set — patterns is registered twice, top-level
and under dream. Zero mentions fails, so the extraction cannot go quiet
and keep reporting "all resolve".

3. C3 counted a filename written in a comment as a caller

C3 finds gate-like scripts nothing runs, by counting basename occurrences. It
counted raw text.

This had already happened, been diagnosed, and been worked around instead of
fixed. measure-injection-tokens.mjs opens with "Companion to
measure-work-topology-baseline.mjs" — one sentence, enough to make the
companion look called. Its correct entry was reported stale and pruned, and the
explanation was written into the other entry's reason field as a warning
not to delete the comment:

"…this file's header names measure-work-topology-baseline.mjs, and C3 counts
any basename reference — which is why that script stopped appearing as a hit
and its entry was pruned."

It happened again in this branch the moment a test header named
wait-for-checks.mjs, and the audit invited me to prune that entry too.

Comments now come out before counting. Over-stripping is the safe direction: a
lost reference makes a script look uncalled, which fails loudly and gets
triaged; a reference wrongly kept hides a finding silently. Consequences, all
correct: wait-for-checks.mjs is a hit again and its entry stands;
measure-work-topology-baseline.mjs surfaced and carries its own entry; the
obsolete note is gone.

The test's fixtures use invented filenames — the first version used the real
ones, and the strings holding them counted as references in exactly the
detector the test protects.

4. Reviewing the above found three more

The first version of #2 scanned single-backtick spans only, in a hand-listed
set of documents. Measured: that missed 19 distinct nested commands living in
fenced code blocks — more than the 25 it saw — and the fenced ones are what an
agent copies out of llms-install.md and runs. It also never opened
skills/memesh-review/SKILL.md, which was not on the list. Now whole-document,
every tracked .md, derived from git ls-files instead of a list that drifts:
89 mentions across 31 files.

The widened gate then found a second dead command. memesh dream review,
in the 4.5.1 release notes:

$ git log -S "dream review" -- src/transports/cli/cli.ts
(no output — the string has never been in that file)

Not a retired command in frozen history: one that has never existed, published,
telling readers to run it. The passage means memesh dream show. Fixed.

That also settled a design question the honest way. The first version scanned
only [Unreleased] and the current version's section, reasoning that older
sections are frozen history which may name since-retired commands. The
reasoning was sound and the rule was wrong — it would have walked straight past
this. The CHANGELOG is read in full now.

A zero-row poll bypassed the settle bookkeeping. wait-for-checks.mjs
short-circuited on an empty check list with its own early return, and that
return never touched prevNamesKey/stablePolls — so "13 green, zero rows, the
same 13 green" counted as two agreeing polls and settled. A response that lost
every row is the clearest possible evidence the list is not holding still.
Fixed by deleting the early return rather than patching it: evaluatePoll owns
the empty case now (and must — two consecutive empty polls would otherwise
settle on an empty list). The script is 6 lines shorter and the case is finally
reachable from a test.

Two suspicions that measurement cleared

Reported because "I checked and it was fine" is worth as much as a finding:

• Should the top-level check widen to all documents too? No. Measured: 59
  false positives, because memesh is the product name and prose says "memesh
  now…", "memesh has…". Its scope to llms-install.md + AGENTS.md — documents
  that are executed — is correct, not an oversight. The nested check does not
  have this problem: its parent word must be exactly config|kg|dream.
• Does \s+ between parent and child wrongly match across a newline? Two
  matches do span one, and both are legitimate wrapped commands in the
  CHANGELOG (memesh dream\n conflicts, memesh\n config set). Narrowing
  to [ \t]+ would lose two real mentions and catch nothing. Left as is.

Verification

node scripts/run-tests-isolated.mjs   exit=0   157 files / 2308 tests (was 155/2284 — both new files ran), no "Errors" line
npm run verify:release                exit=0   ✓ 89 nested mentions across 31 markdown files all resolve
npm run lint / typecheck              exit=0

Break-test — mutate the source, not the assertion; restore by writing the
original string back and confirming sha256 is unchanged. 15/15 KILLED:

target	mutation
settle guard	accept the first green poll as a verdict	KILLED
settle guard	set the threshold to 1 (guard inert)	KILLED
settle guard	make the name key order-dependent	KILLED
settle guard	let a zero-row poll count toward settling	KILLED
nested gate	a mistyped child in a doc	KILLED
nested gate	a mistyped child in the live CHANGELOG section	KILLED
nested gate	a mistyped child inside a fenced code block	KILLED
nested gate	a mistyped child in a frozen older CHANGELOG section	KILLED
nested gate	the backtick extraction stops matching	KILLED
nested gate	the parent extraction loses a parent	KILLED
stripComments	stop stripping block comments	KILLED
stripComments	stop stripping line comments	KILLED
stripComments	stop stripping YAML/shell comments	KILLED
stripComments	strip too much (unknown extension)	KILLED
stripComments	treat the // in a URL as a comment	KILLED

Loop-closure check (/verify-loop-closure): C1 and C2 do not apply — the diff
has no write/read persistence pair and no mocks at all (enumerated, both scans
empty). C4's three replace() hits are all inside stripComments, applied at
one point rather than on two sides of a round trip. C3 is the one that applies
and is the table above. PASS.

Not done, and why

The CI matrix is unchanged. I proposed tiering Windows onto push: main
only, then measured the run and the proposal did not survive it:

12.3 min  Build & Test (windows-latest, Node 22)
10.7 min  Build & Test (windows-latest, Node 24)
 2.7 min  Build & Test (macos-latest, Node 24)
 2.5 min  Build & Test (ubuntu-latest, Node 22)   … every other leg ≤ 2.7 min

The legs run in parallel, so dropping one Windows leg from PRs frees a queue
slot and changes wall-clock by nothing — the PR still waits ~12 min for the
other one. The gap is GitHub's degraded Windows runners (~5x), already
root-caused in this repository; cache: 'npm' is on and the double build was
removed. There is no change here that buys time without dropping the Windows
coverage that has caught Windows-only bugs before.