test(scripts): check-shell-escape-residue reds on an agent-tree document no scan root reaches (#7413)

[baozhoutao]

Fixes #7413

Direction 2 of the card, which is the general form: the gate now judges whether anything in the agent tree is off its scan surface, as its own verdict — not a widened row.

The assertion's design

SCAN_ROOTS answers what is scanned. Nothing answered is anything in the agent tree NOT scanned, and no minFiles floor can: a floor detects a root that collapsed, never a document that was never on the surface. Three shapes, only one of which had a signal before this:

shape	signal before
a declared root walks to zero	minFiles fires (#7403's fix)
a declared root vanishes from disk	unresolved fires
a new document outside every row	nothing
a SCAN_ROOTS row is deleted	nothing

COVERAGE_TREES adds the missing judgement: trees in which every .md/.mdx must be reached by some declared row, reported by file name when one is not.

It cannot disagree with the scan about what a document is. Coverage is set membership in the walk's own output — scan collects every path listDocuments returned for every resolved root, then asks the same listDocuments for the tree. One walk, one DOC_EXTENSIONS, one definition. A second glob or a prefix match on the row spec would be a second answer to one fact (#3261/#3279), and the drift would land on the side that reads as coverage.

An unresolvable coverage tree is loud for the reason a scan root is — a mistyped .claude covers nothing and reads as coverage forever — and it carries a role so the remedy names the right declaration list. The coverage figure rides in the verdict line, so a green still shows its population:

✅  check-shell-escape-residue: OK (… ; coverage -- .claude: 4/4; skills: 16/16 document(s) under a declared root).

The skills/-side measurement the card asked for

It generalises, at the cost of one extra walk of 16 files, so it is included.

• .claude — the card's case. The declared row is a proper subtree, so the tree can grow documents outside it. 4/4 covered on e1545cf; green today by construction, and its whole job is the next file.
• skills — the row is the whole tree, so today the test is a tautology (16/16). Declared anyway because it stops being one under the single edit nothing else here catches: narrowing or deleting the row. A vanished root is loud; a row someone removed leaves nothing behind to be loud about, and the published skills tree would walk off the surface silently. That case is pinned.
• content/docs — deliberately not a coverage tree, and this is the one judgement call in the change. Same mechanism, different claim: this gate's roots are the agent-facing surface (没有任何门禁校验文档里 fenced shell 示例的可执行性:实测 shell 转义泄漏进代码块对全部门禁不可见 #5151 ruled it, check-shell-escape-residue lost the same two guides #7251 moved — its skills root does not reach .claude/skills #7403 widened it), and content/docs is published prose that happens to share the scan. Declaring coverage over it asserts a completeness promise about the docs tree that no card has made. Filed as its own finding rather than decided here.

⛔ No allowlist and no per-file opt-out: the two ways to clear a finding are to move the document under a declared root, or to declare a root for it — both the deliberate decision the gap deserves.

Reverse verification

On disk, against the real gate. .claude/agents/reviewer.md — the card's literal scenario — planted with a fenced bash block, inside a trap:

=== BEFORE: .claude md count = 4, reviewer.md present = no
=== AFTER plant: .claude md count = 5, reviewer.md present = yes
=== PLANTED gate EXIT=1

❌  check-shell-escape-residue: 1 agent-tree document is on no scan root

    - .claude/agents/reviewer.md (under the coverage tree `.claude`)

=== RESTORED: .claude md count = 4, agents dir present = no
=== RESTORED gate EXIT=0
=== git status --porcelain (must be empty):
(end)

Ablation of the implementation. Committed first, then the detection line mutated on disk (const missing = documents.filter(…) → []), verified landed by marker count and by a blob-hash mismatch against HEAD, then restored:

=== BEFORE: detection line present? 1
=== AFTER mutation: original line count = 0, marker count = 1
=== MUTATED vitest EXIT=1
      Tests  4 failed | 39 passed (43)
=== RESTORED: hash matches HEAD? YES
=== git diff HEAD (must be empty):
(end)

The four that go red are the coverage ablation, the row-deletion case, the same-walk case, and the pre-existing out-of-scope case whose fixture already contained a .claude/hooks/notes.md nobody was reporting. The ⭐ REDS on this card's own scenario case also asserts that every other signal in the same run reads healthy — no unresolved, no vacuous, .claude/skills still returning its file, the planted residue not even judged. Without that half the case would pass for a gate that reddened on anything.

Gates (all at 150ff53, exit codes captured by redirect-then-capture)

gate	verdict
node scripts/check-shell-escape-residue.mjs	exit 0 — OK (5/5 root(s) resolved …; coverage -- .claude: 4/4; skills: 16/16 …)
pnpm exec vitest run scripts/__tests__/check-shell-escape-residue.test.ts	exit 0 — Test Files 1 passed (1) / Tests 43 passed (43)
pnpm exec vitest run scripts/__tests__/	exit 0 — Test Files 107 passed (107) / Tests 3253 passed (3253)
pnpm type-check:scripts	exit 0
pnpm lint:root	exit 0 — 32 problems (0 errors, 32 warnings), none in the two changed files
pnpm check:control-bytes	exit 0 — scanned 6440 tracked text file(s); plus a direct control-byte grep over both files: clean
node scripts/check-changeset-presence.mjs	exit 0 — No source or published contract of a released package changed in this range, so no changeset is owed
node scripts/check-governed-queue-guard.mjs --test THE_2_CHANGED_PATHS	exit 0 — NOT GOVERNED — 2 path(s) checked against 5 governed surface(s); none matched

Readers

git grep -l check-shell-escape-residue -- scripts/ .github/ returns exactly three files: the gate, its test, and .github/workflows/shell-escape-residue.yml.

The workflow needs no .claude trigger path — it deliberately has no path filter at all. Its header: "Hence: no paths and no paths-ignore here, deliberately. scripts/__tests__/check-shell-escape-residue.test.ts fails if either is ever added" — and that pin (runs it in NO path-filtered workflow) is still green. It fires on every pull request shape, which is also what makes it requirable.

Note on CI

Live E2E (informational) is red on every branch today for an upstream reason (#7990 / objectstack#16186), unrelated to this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MM7kaS4dPpYHV5BsMyu4tQ

---

Generated by Claude Code

[baozhoutao]

Standing down on Live E2E (informational) — red on the base branch too, not this PR's. domain:devx @ objectui execution seat, PM session session_01MM7kaS4dPpYHV5BsMyu4tQ, R45, 2026-09-06T08:41Z. Same signature as main's scheduled run 34017174769 (job 101442890465): the published backend boots without its auth core (objectstack#16186); consumer-side anchor #7990. This diff is one scripts/ gate and its test — no backend pin, no e2e/ path. No fix to port, no re-run spent. Flip and arming wait on the remaining shards (ACCEPT 5558086543 on #7413).

---

Generated by Claude Code