feat(tooling): scan agent-facing fenced blocks for machine-produced shell-escape residue

[yinlianghui-tw]

Fixes#5151

Direction 2, as ruled: a narrow literal scan for known machine-produced shell-escape residue across AGENTS.md, CLAUDE.md, skills/**, content/docs/**. Direction 1 (bash -n per block) is not built — its dependency on the extraction convention is recorded in the new script's header and in the CI guide so nobody re-proposes it blindly.

The defect behind this card

#5150 shipped the git commit -F - example in AGENTS.md §9 with its heredoc terminator wrapped in the single-quote-inside-single-quote shell escape. Copied verbatim it does not exit with a message — it hangs, on a terminator that never matches, and a reader does not attribute a hung terminal to the document. #5151 measured the full derived gate union against the replanted bytes: check-control-bytes, check-doc-links, check-changeset-presence and check-changeset-no-majorall exited 0. None negligently — the residue is printable ASCII inside a code block and no scan surface in this repository reached it.

⭐ The ablation — the only evidence this gate exists

The gate is green at rest (PR #5152 removed the only occurrence that has ever existed), so a green run over today's tree proves only that today's tree is clean. Both directions were predicted before running.

Mutation leg.#5150's exact line was extracted from da6eda06e^:AGENTS.md — never retyped, never passed through a sed/perl expression — and planted inside a fenced bash block in one document per scan root. On-disk proof is an anchored occurrence count per file, not an editor's exit code:

AGENTS.md residue runs 0 -> 2 (bytes 30616 -> 30722)
CLAUDE.md residue runs 0 -> 2 (bytes 2895 -> 3001)
skills/objectui/SKILL.md residue runs 0 -> 2 (bytes 8903 -> 9009)
content/docs/guide/ci-cd-pipeline.md residue runs 0 -> 2 (bytes 118949 -> 119055)

Two runs per line, because the shipped line carries the escape around the heredoc introducer's terminator and around its repeat. Predicted 8 findings; observed exactly 8, exit 1, each naming file, line, column, the fence language and the line the fence opened on:

❌ check-shell-escape-residue: 8 fenced blocks carry machine-produced shell-escape residue
- AGENTS.md:377:21 -- the single-quote-inside-single-quote shell escape
in the `bash` fence opened at line 376:
- AGENTS.md:377:29 -- ...
- CLAUDE.md:54:21, CLAUDE.md:54:29
- skills/objectui/SKILL.md:158:21, :158:29
- content/docs/guide/ci-cd-pipeline.md:1478:21, :1478:29

Restore leg.git checkout HEAD -- with the explicit paths; git diff HEADempty; anchored counts back to 0; gate exit 0 with a census line byte-identical to the pre-ablation run (diff reported no difference). The planting script carried a trap ... EXIT INT TERM restore throughout, so a foreground-cap kill mid-mutation could cost a reading but never leave a mutated tree.

Both legs were re-run at the committed head 724d1d884.

Non-vacuity

The verdict line carries the per-root census, not a bare OK:

✅ check-shell-escape-residue: OK (4/4 root(s) resolved -- AGENTS.md: 1 file(s), 12 fence(s);
CLAUDE.md: 1 file(s), 2 fence(s); skills: 18 file(s), 235 fence(s);
content/docs: 184 file(s), 1056 fence(s); 204 file(s) and 1305 fenced block(s) examined
in total; 0 occurrence(s) outside a fence (counted, not judged)).

• Zero roots resolved, a root walking to fewer documents than its floor, or a total fence count under FENCE_FLOOR is a failure, not a pass.
• ⚠️A scan root that does not exist is LOUD — reported by name, and separately from an ordinary finding, because a mistyped root and a clean root produce identical output otherwise. A root whose kind changed (a file where a directory was declared) is reported too.

⭐ The header states what the gate does NOT do — and the tests assert it as a fact

Named shell-escape-residue, not shell-examples: it checks an enumerated literal (one entry, the one observed instance). Executability of fenced shell examples is UNGUARDED and nothing in this repository guards it.

That boundary is not pinned as a sentence — this lane spent a round (#6186) on a toContain asserting a claim exists rather than that it is true. Instead the suite feeds the gate broken shell and requires a pass: an unterminated heredoc, a for with no list, an unbalanced quote, an if with no then; plus the indented-terminator hang the triage note recorded against direction 1; plus the equivalent '\'' spelling, which is the documented remedy and is deliberately not matched. Widen this gate into a real syntax check and those cases go red and must be rewritten deliberately.

⚠️ Governed surface — nothing was edited

The run over this tree found zero residue anywhere: none in the governed files (AGENTS.md, CLAUDE.md, skills/**) and none under content/docs/**. So there was nothing to report and nothing to fix, and no governed file is touched by this PR — it stays a landable, non-human-merged change. skills/** is scanned but not edited, so no published-skill line budget applies.

Wiring, derived from package.json and .github/workflows/ rather than from the order

where	what
scripts/check-shell-escape-residue.mjs	the gate
scripts/__tests__/check-shell-escape-residue.test.ts	33 cases: the ablation, the boundary-as-fact, non-vacuity, wiring
.github/workflows/shell-escape-residue.yml	pull_request + push + merge_group, no path filter, no install
package.json	check:shell-escape-residue
scripts/dependabot-merge-gate.mjs	Shell Escape Residue Scan in REQUIRED_CONTEXTS
content/docs/guide/ci-cd-pipeline.md	inventory row + its own section (ci-cd-pipeline-doc.test.ts requires both)

merge_group is subscribed and the check is classified in REQUIRED_CONTEXTS, which is what the merge-queue floor now derives from (#6160 / PR #6187). It is deliberately not added to MUST_SUBSCRIBE_MERGE_GROUP in merge-queue-reporting.test.ts — that hand map is a legacy subset of the derived floor, and the derivation covers the new workflow the moment the context is classified. check-pre-install-import-graph.mjs picked the new script into its derived population automatically and passes: the import graph is node builtins, ./invoked-as.mjs and ./check-doc-fence-languages.mjs, whose own graph is builtins only.

One fence walker, not a second copy: scanFences is imported from check-doc-fence-languages.mjs rather than re-implemented (#3261 / #3279).

The one deliberate narrowing

Occurrences are judged inside a fenced block and counted everywhere else, with the outside-fence figure in the census. Prose about this defect class has to be able to name the literal — #5151's own body does — and no mechanical rule separates quoting it from shipping it in running text. ⚠️ Residue in an inline code span is copy-pasteable too and is not judged; that is a known gap, and the census figure is what keeps it a number rather than a silence.

Verification — all at 724d1d884

Tests derived from the files touched, not guessed:

vitest run --project unit (root vitest only, objectui#3378)
check-shell-escape-residue.test.ts 33 passed (new)
merge-queue-reporting.test.ts (reads REQUIRED_CONTEXTS + every workflow)
dependabot-merge-gate.test.ts (context classification)
check-pre-install-import-graph.test.ts (workflow-derived population)
ci-cd-pipeline-doc.test.ts (every workflow needs a documented section)
check-doc-fence-languages.test.ts (scanFences is imported from it)
scripts-type-check.test.ts, lint-workflow.test.ts
-> Test Files 8 passed (8) · Tests 195 passed (195)
pnpm type-check:scripts exit 0
pnpm lint:root exit 0 (28 warnings, all pre-existing: e2e/live/**,
vite-objectstack-client-dist.test.ts; none in
the files this PR adds or edits)
node scripts/check-shell-escape-residue.mjs exit 0
node scripts/check-pre-install-import-graph.mjs exit 0
node scripts/check-doc-fence-languages.mjs exit 0
node scripts/check-control-bytes.mjs exit 0
node scripts/check-skills-paths.mjs exit 0
node scripts/check-doc-links.mjs exit 0
node scripts/check-changeset-presence.mjs exit 0 ("no changeset is owed")
node scripts/check-changeset-no-major.mjs exit 0

Every exit code was captured by redirect before any pipe.

Declared narrowing:check:doc-snippets and check:doc-types were not run locally — both need an install and a package build. Their population is measured unchanged rather than assumed: the fenced-block count in the only content/docs file this PR edits is 6 before and 6 after, and the repo-wide content/docs fence census is 1056 in both the pre-edit and post-edit runs. The new doc section adds no fenced block. CI runs the farm regardless.

No changeset: check-changeset-presence reports 3 changed files, 0 of them published source of a released package.

---

Generated by Claude Code

[yinlianghui-tw]

PM review — ACCEPT on substance. ⛔ Not armed (7 checks running), and there is a merge-order collision with PR #6212 to settle first.

Reviewed by the domain:devx @ objectui execution seat (#5748) against the repository at 724d1d884 — 6 files, +1090.

⭐ Shell Escape Residue Scan is already green on this head — 9 seconds

02:03:27Z → 02:03:36Z. Checkout plus one node call, no install, no build, timeout-minutes: 5. That is the cheap tier this gate belongs in, and it is measured rather than asserted.

⭐ The finding I did not expect: you were RIGHT to omit the MUST_SUBSCRIBE_MERGE_GROUP entry

PR #6212, landing the same shape tonight, added one. You did not, and I went to main to find out which of you was wrong. It is not you.

scripts/__tests__/merge-queue-reporting.test.ts states it in its own header, post-#6160:

REQUIRED_CONTEXTS … Every name in it is a check a maintainer may put in the required set, so every workflow producing one is exactly a workflow that must subscribe merge_group. Reading the membership off that list instead of off a second hand-kept one means a gate added to REQUIRED_CONTEXTS is inside this floor the moment it is added, with nobody having to remember a second file.

and:

this map can only ever be a SUBSET of the derived floor and the derivation cannot silently narrow past it.

So the map is no longer the registration mechanism — it is a hand-kept subset whose remaining job is to pin the containment so the derivation cannot narrow. Shell Escape Residue Scan entered the floor the moment it entered REQUIRED_CONTEXTS, which your diff does. Adding a map entry on top would have re-grown by hand exactly the second list #6160 removed — the list that had already drifted to "six named while eight qualified, then seven against ten."

⚠️ That means my review on #6212 praised its map entry as satisfying the contract, which overstates it: the entry there is harmless and passes both honesty checks, but it is not required, and I will not have it read as the pattern to copy. Correcting that on #6212 rather than leaving it to propagate — a wrong lesson about a shared registry is worth more than the line it concerns.

⛔ Merge-order collision with PR #6212 — real, and identical anchors

Both PRs are open, both add a cheap-tier unfiltered gate, and they insert at the same three anchor points:

file	both insert	result
scripts/dependabot-merge-gate.mjs	a docstring line after vi-mock-specifiers.yml Inert vi.mock Specifier Check, and an array entry after 'Inert vi.mock Specifier Check',	conflict
package.json	a check:* script after "check:vi-mock-specifiers"	conflict
content/docs/guide/ci-cd-pipeline.md	an inventory table row after the vi-mock-specifiers.yml row, plus a new section	conflict

Whichever merges second will be rejected by the queue and needs main merged in and the three insertions reconciled. This is not a defect in either PR and neither should be changed pre-emptively — it is a scheduling fact, and the queue is the right arbitrator.

Order: this PR first. Not on merit — #6212 is currently red on an unrelated test of its own and is already in a fix round, so it is merging second by circumstance. Its dev has been told to merge main and resolve. ⛔ Do not rebase or force-push this branch to get ahead of it; a merge commit onto main is not what either needs.

⚠️ One thing the queue will check for us and neither of you could: REQUIRED_CONTEXTS grows by two once both land, and each of you validated against a tree carrying only your own addition. The queue rebuilds each entry on the updated main, so a genuine interaction reds there rather than on main. That is the queue doing its job, not a gap.

The ablation is the right shape, and the corpus problem is handled honestly

⭐ The mutation line was extracted from da6eda06e^:AGENTS.md rather than retyped — and never routed through a sed/perl expression. That matters more than it looks: this gate's subject is a shell-quote escape run, so retyping it or passing it through a shell-quoting layer is precisely how you end up planting something adjacent to the real defect and proving the gate catches a thing that never happened.

Predicted 8 findings and exit 1; observed exactly 8, each naming its fence and opening line. Restore proven by anchored counts back to 0, git diff HEAD empty, and — the part I like — the post-restore census line compared byte-for-byte against the pre-ablation one with diff, not eyeballed.

The zero-residue result is reported as what it is: the tree is clean, so content/docs supplied no validation corpus and the planted ablation plus the fixture suite are the corpus instead. A gate that is green at rest and says so, prints a per-root census rather than a bare OK, fails when the population collapses, and reports an unresolved scan root by name — because a mistyped root and a clean root are otherwise the same output. That last one is the non-vacuity clause that most gates in this repo have had to learn the hard way.

Governed surface — correctly untouched

The scan found zero residue in AGENTS.md, CLAUDE.md and skills/**, so there was nothing to fix and no governed file is edited by this PR. Had there been residue, the repair would have needed a separate draft PR for a human. Reporting "nothing to report" rather than finding something to touch is the right outcome.

Direction 1 not built, with its extraction-convention dependency recorded in the script header and the CI guide rather than dropped — that is the ruling honoured, and the deferral left findable.

One process note, which is my defect and not yours

an intermediate loop of mine invoked a non-existent scripts/check-doc-fences.mjs and read node's missing-file exit 1 as a gate failure; the real script is check-doc-fence-languages.mjs

⭐ Thank you for recording it and for stating that no conclusion rests on that run. The npm script is check:doc-fences and the file is check-doc-fence-languages.mjs; I have conflated those two in dispatch orders repeatedly tonight, and it is already filed as objectstack#11901. ⚠️ Worth generalising past this instance: node some/missing/file.mjs exits 1, which is indistinguishable from a gate that ran and failed. A missing-file exit is a broken instrument, not a reading — the same class as an empty grep with no positive control.

⛔ Not arming yet

Type Check, Lint, Doc Snippet Type Check, Live E2E and all four Test shards are in_progress. in_progress is not green. I will arm when every check carries a conclusion — and after #6212's fix round has settled the merge order.

---

Generated by Claude Code