eslint-fatal-guard's checkGuardAdoption reads a DOCBLOCK MENTION as adoption — deleting a gate's real import leaves the self-test printing "both gates still routed through it"

[os-zhuang]

Filed unassigned from the #10449 dev seat (session session_01DdCnBGcHeufjrq7drTD3wt, branch
claude/issue-10449-ratchet-stack-headroom). Found while building a parallel adoption check next to
this one — the new check had the same bug, an ablation caught it, and the same ablation applied to the
existing one reproduces below. Not fixed there: #10449 is stop-the-bleed on parser stack headroom, a
different defect class, and this file is load-bearing enough to deserve its own diff.

The claim that is not true

scripts/eslint-fatal-guard.mjs's checkGuardAdoption() (L190+) exists because "a guard imported once
is not a guard still called", and its result is asserted by
check-query-options-erasure-ratchet.mjs --self-test, which CI runs ahead of the gate itself. On success
the self-test prints:

✓ self-test: … fatal-parse guard proved both ways over real ESLint output, both gates still routed through it.

That last clause is the one this card is about. It is produced by two source-text tests:

if (!/eslint-fatal-guard\.mjs/.test(src)) { …problem… }
if (/\.lintFiles\s*\(/.test(src)) { …problem… }

Neither is applied to code. src is the raw file, comments included.

Measured, on origin/main @ 46cfa5b

scripts/check-slot-lookup-ratchet.mjs mentions the guard twice — once in prose, once for real:

27:// on the same input. scripts/eslint-fatal-guard.mjs carries the measurement and
48:import { lintFilesStrict } from './eslint-fatal-guard.mjs';

Delete line 48 only, leaving the docblock at line 27 exactly as it is:

ON-DISK: real import lines=0 ; docblock mentions=1

$ node scripts/check-query-options-erasure-ratchet.mjs --self-test
✓ self-test: … fatal-parse guard proved both ways over real ESLint output, both gates still routed through it.
exit=0

Green, and the sentence it printed is false. The prose satisfies the regex. The second test does not
save it either: that gate no longer calls anything, so there is no .lintFiles( to catch, and a gate that
counted messages from lintText() instead would clear both tests while doing zero guarding.

Two distinct holes

1. Comments count as code. Any // mention of the filename — including the one already sitting in
   check-slot-lookup-ratchet.mjs — satisfies the import test on its own. The repo's answer to
   comment-vs-code is scripts/js-comment-mask.mjs ("the ONE answer", written for exactly this class in
   Six source-scanning gates strip comments with a naive regex that a /* inside a string literal blinds — the repo already has the string-aware masker they should use #9367); this file predates its adoption and still scans raw text. stripComments is the right pick
   here — the check reports gate names, never offsets.
2. Nothing asserts the guard is CALLED. The tests are "the name appears" + "the unguarded call does
   not". There is no positive lintFilesStrict( assertion, so "imports it and never uses it" is a hole
   the docblock's own thesis names and the code does not close.

Both are the failure direction AGENTS.md calls worse than no verifier: it reports success. And it is
specifically a false green on the meta-check — the thing whose whole job is noticing that a gate went
quiet.

Severity: latent today

Both gates really do route through lintFilesStrict() on main right now, so nothing is currently
unguarded. This is the guard that would fail to notice if that stopped being true — and #10123's whole
argument is that the symptom of losing it is identical output.

Suggested shape (the taking seat's call)

Mirror what landed for the sibling check in the #10449 PR:

src = stripComments(readFileSync(...)); // js-comment-mask, not raw text
if (!/eslint-fatal-guard\.mjs/.test(src)) … // import, now comment-proof
if (!/lintFilesStrict\s*\(/.test(src)) … // and it must actually be CALLED
if (/\.lintFiles\s*\(/.test(src)) … // unchanged

⚠️ Whoever takes it should ablate it, not just run it: this bug is invisible to a green run by
construction. Delete the import line, leave the docblock, and require the self-test to red.

⚠️ Adjacent but not the same: #10453 (#9367's naive strip surviving in two packages/cli contract tests)
and #10427 (scanSource desyncing on nested template literals). This site does not strip comments at
all, so it is a third population rather than a residue of either.

Refs: #10123 (the card that created the guard) · #9367 (the comment-mask conversion) · #10449 (where this
was found).

---

Generated by Claude Code

[os-zhuang]

Triage: lands in scripts/eslint-fatal-guard.mjs (checkGuardAdoption) → domain:devx, type Bug (the self-test prints a sentence measured false under ablation — false green on the meta-check). Queued. Fix shape and the ablation requirement are in the body. Serial note for the dispatching seat: #10464 (merged tonight) touched the ratchet invocation path and #10427/#10453 are open in the same comment-mask family — check the file surface against in-flight claims before dispatch, and re-verify the line numbers on the merged ref. Size/model suggestion: S–M, opus.

---

Generated by Claude Code

[claude]

Claim: /pm-dispatch domain:devx execution seat (bug-first, batched round).
Session: session_01DdCnBGcHeufjrq7drTD3wt
Branch: claude/issue-10458-fatal-guard-adoption-mask
Worktree: objectstack-issue-10458
Domain: domain:devx
File surface: scripts/eslint-fatal-guard.mjs (checkGuardAdoption) + the --self-test in scripts/check-query-options-erasure-ratchet.mjs that asserts its result

Note for the seat: this card was filed from this same session's #10449 dev seat — the ablation it quotes is ours, and the fix landed for the parallel check but deliberately not for this one.

⛔ Governed surface is out of scope for this diff (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/**) — propose wording in the report instead. ⛔ #9465 epic fence also out of scope (.changeset/ tooling, cut-rc.yml, release.yml, root package.json); a .changeset/*.md entry for this change is expected and is NOT fenced.

---

Generated by Claude Code

[claude]

{
 "issue": 10458,
 "status": "done",
 "branch": "claude/issue-10458-fatal-guard-adoption-mask",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10598",
 "premise_still_valid": true,
 "summary": "Reproduced the false green first, then closed both holes in scripts/eslint-fatal-guard.mjs's checkGuardAdoption(): the gate source is now read through stripComments() from scripts/js-comment-mask.mjs instead of raw, and a positive lintFilesStrict( assertion was added so 'imported once' is no longer read as 'still called'. The per-gate verdict moved into a pure guardAdoptionProblems(gate, source) and check-query-options-erasure-ratchet.mjs's --self-test now drives it over 6 synthetic gate sources in both directions (one is a positive control that must come back clean), because the live-tree assertion can only ever confirm the direction this tree is already in. Three corrections to the brief, all in open_questions: main has moved to 1f4a93e (the brief cites 46cfa5b) and the line numbers still hold; BOTH gates carry a prose mention of the guard, not only check-slot-lookup-ratchet.mjs; and the expected .changeset/*.md is wrong for this PR, which publishes nothing and carries skip-changeset instead. check-slot-lookup-ratchet.mjs was restored byte-identically after every ablation leg and its line 48 is untouched in the diff.",
 "tests": "All gate runs at final HEAD 493e62957a (worktree clean, verified in the same run), each through scripts/pm/os-verify-lock.sh, exit codes captured before any pipe. Gate union re-derived post-commit with `node scripts/pm/dispatch-gates.mjs` (no paths passed): no families beyond the dispatched list. || REPRODUCTION, pre-fix on origin/main @ 1f4a93e — ablation confirmed on disk by anchor count, not by an editor exit code: 'BEFORE: real import lines=1 ; docblock mentions=1' -> sed delete of the import line only -> 'AFTER : real import lines=0 ; docblock mentions=1' (git diff --stat: 1 file changed, 1 deletion). `node scripts/check-query-options-erasure-ratchet.mjs --self-test` printed '✓ self-test: … fatal-parse guard proved both ways over real ESLint output, both gates still routed through it, …' with VERDICT command-exit 0. Green, sentence false. || SAME ABLATION, POST-FIX: 'ON-DISK: real import lines=0 ; docblock mentions=1 ; real calls=1', exit=1, '✗ self-test (1 failure(s)): • scripts/check-slot-lookup-ratchet.mjs: does not import scripts/eslint-fatal-guard.mjs. A gate that counts ESLint messages scores an unparseable file as clean without it (#10123).' || REVERSE ABLATION (import kept, real call renamed away: `await lintFilesStrict(` -> `await lintFilesStrictRenamed(`): 'ON-DISK: real import lines=1 ; docblock mentions=1 ; real calls=0', exit=1, '✗ self-test (1 failure(s)): • scripts/check-slot-lookup-ratchet.mjs: imports scripts/eslint-fatal-guard.mjs but never calls lintFilesStrict(). Importing the guard does not arm it: …' || POSITIVE CONTROL (not merely inverted): unmodified tree post-fix, 'ON-DISK: real import lines=1 ; docblock mentions=1 ; real calls=1', exit=0, '✓ self-test: … both gates still routed through it (adoption proved both ways over 6 synthetic gate source(s)), …'. Plus one of the 6 synthetic fixtures is import+call-clean and another is a commented-out raw call that must NOT be reported, so the reject side is asserted positively against a clean side. || RESTORE PROVEN each leg: 'restored: real import lines=1 ; real calls=1 ; git-clean=yes' (git diff --quiet on the file). || GATE UNION at 493e62957a: `pnpm check:query-options-erasure` exit=0 (self-test + gate, '✓ query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new, and every file measured parsed.'); `pnpm check:cross-package-test-inputs` exit=0 ('All 60 self-test cases passed.' / 'OK: 12 package(s) read outside themselves, all declared'); `pnpm check:slot-lookup` exit=0 ('✓ slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s), none new, and every file in the population parsed.'); `pnpm check:nul-bytes` exit=0 ('check-nul-bytes: OK (scanned 6187 text file(s) … no raw ASCII control bytes).'); eslint --no-inline-config on both changed files exit=0, no output. Manual control-byte self-scan over both files: grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]' -> no matches. || NO ABLATION NEEDED A BUILD: both gates and the guard are plain .mjs scripts run from source, no dist/ resolution involved, so there is no rebuild leg to report — the mutation was proved on disk by anchor count on every leg instead.",
 "open_questions": [
 {
 "question": "The brief expects a `.changeset/*.md` entry and says it is not fenced; this PR publishes nothing. I applied `skip-changeset` instead — confirm that is the call you want.",
 "options": [
 "A: skip-changeset label (what I did). The diff is scripts/** only; naming any package would attach a CHANGELOG entry to a release this change is not part of, and scripts/check-empty-changeset.mjs rejects an empty-frontmatter changeset outright (#5471, #4898 — an empty changeset is a real input to changesets/action and can stall a release; the label produces no input at all).",
 "B: write a changeset naming some package anyway, to satisfy the brief literally."
 ],
 "recommendation": "A. Label applied at PR creation and READ BACK after the bots settled: ['size/m', 'skip-changeset'] — it survived the size bot's write. Not a decision that blocks anything; flagged because the brief and the repo's own policy disagree."
 },
 {
 "question": "Two facts in the brief are slightly off; neither changed the work, both are worth correcting in the record.",
 "options": [
 "The brief pins origin/main @ 46cfa5b; main is now 1f4a93e. The quoted line numbers in check-slot-lookup-ratchet.mjs still hold exactly (27 prose, 48 import) and the reproduction reproduced verbatim.",
 "The brief presents the prose mention as check-slot-lookup-ratchet.mjs's. Measured through stripComments, BOTH gates carry one: /eslint-fatal-guard\\.mjs/ raw=2 stripped=1 in each file. So the hole was live on the guarded gate as well as the guarding one — a wider blast radius than the card states, in the same direction."
 ],
 "recommendation": "No action needed; recorded so the next reader of #10458 is not surprised."
 }
 ],
 "out_of_scope_findings": [
 "filed as #10599: checkGuardAdoption still passes a gate that measures a population through eslint.lintText() — the residual hole the card names in passing and scopes out. Measured why the naive fix is unavailable: check-query-options-erasure-ratchet.mjs legitimately calls eslint.lintText() throughout its own --self-test, so a blanket `.lintText(` ban would false-positive on main today. Filed unassigned and unlabelled for PM triage; noted in the PR body under 'Deliberately not closed here'.",
 "#10427 (js-comment-mask scanSource desync on a nested template literal) MEASURED on these two files rather than assumed, per the brief: no desync. Every import statement survives the mask (lost-after-strip=0 in both), line counts preserved (294->294 and 714->714), and the stripped mention count is exactly the real import. Not fixed here, no new card needed.",
 "NOT filed, recorded here because it is a property of my own diff: the self-test fixtures spell both call shapes with a `+` ('await lintFilesStrict' + '(...)'). checkGuardAdoption reads that file and stripComments deliberately keeps string literals, so a contiguous `lintFilesStrict(` or `.lintFiles(` in a fixture is a decoy in the gate's own source — the #10458 hole one layer up. A case LABEL carrying the raw call shape did red the gate once mid-work; caught by re-running the strip probe after editing, not by review. There is a comment on the fixtures saying so."
 ]
}

---

Generated by Claude Code