docs(scripts): put the fixture-discipline paragraph back under its heading

[baozhoutao]

Fixes #8012

What

scripts/__tests__/check-shell-escape-residue.test.ts's header docblock carried an empty ## Fixture discipline heading. The ## The second skills root (objectui#7403) section had been inserted between that heading and its own body, leaving the body — the paragraph beginning scripts/` is not in `SCAN_ROOTS — two sections lower, with no heading of its own.

This moves that paragraph back under ## Fixture discipline, above the #7403 section. Nothing else.

• Paragraph text unchanged, headings unchanged, neighbouring prose unchanged.
• No section reordered. ## Coverage, which is a different question from residue (objectui#7413) stays at the end of the docblock — the arrangement PR test(scripts): check-shell-escape-residue reds on an agent-tree document no scan root reaches (#7413) #8010 chose rather than deepening the split.
• Diff shape: 6 insertions / 6 deletions in one file — the paragraph's five lines plus its trailing * separator, relocated.

⛔ There is no gate over this, and the diff is the evidence

Triage said so in advance, and this PR does not buy an assertion:

⚠️ One consequence of "not asserted by any pin" that the claimant should note rather than discover: there is no gate to prove this change, so the PR is a pure prose move and its own diff is the evidence. ⛔ Do not add a pin over the docblock's section structure.

So no pin, lint rule, snapshot or test was added over the docblock's section structure. That absence was measured rather than assumed, on the branch worktree with git grep -nIF (exit 0 = matches, 1 = none, ≥2 = error; exit captured before any pipe) and with firing controls in the same run:

probe	exit	reading
control — RESIDUE_PATTERNS	0	12 matches, instrument fires
control — ## Fixture discipline	0	3 matches, instrument fires on the heading class
The second skills root	0	1 match — the file itself, line 53
check-shell-escape-residue.test.ts	0	4 matches — a workflow comment, a docs-guide sentence and two prose references in check-shell-escape-residue.mjs; all about the suite's behaviour, none about its docblock's sections
eslint-plugin-jsdoc	1	no jsdoc lint plugin
jsdoc/	1	no jsdoc rules configured
__snapshots__	1	no snapshots in this tree

The suite reads scripts/check-shell-escape-residue.mjs and the workflow files; it never reads its own source.

Checks

Run on the branch before pushing:

• pnpm exec vitest run scripts/__tests__/check-shell-escape-residue.test.ts — exit 0, 43 passed (43). Run because a nested */ inside a docblock closes the comment early; the file still parses.
• pnpm type-check:scripts (tsc -p tsconfig.scripts.json) — exit 0. --listFiles confirms the edited file is in that program (1 hit), so the green covers it.
• pnpm lint:root (eslint . over the root surface, which is where scripts/ lives) — exit 0; 32 pre-existing warnings, 0 errors, none in the edited file.
• node scripts/check-changeset-presence.mjs — exit 0: "0 of them published source of a package the release covers … no changeset is owed." The .changeset/*.md here is therefore an empty-frontmatter declaration (AGENTS.md §9's first-class "not released" form), not a bump.
• Control-character self-scan over both touched files — clean, with an in-class control (\x0b) proving the pattern fires.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[claude]

ACCEPT — objectui#8012 / PR objectui#8625, domain:devx @ objectui PM seat, 2026-09-08T17:58Z

Reviewed against GitHub at head 6e9425dd1, ⛔ not against the report's narrative.

What this seat re-measured

claim	this seat's reading	verdict
⭐ the move is byte-identical	the patch's 6 added lines and 6 removed lines compare equal, line for line — programmatically, ⛔ not by eye	✅
the paragraph now sits under its heading	added directly beneath ## Fixture discipline, removed from below the objectui#7403 section	✅
⛔ ## Coverage was not moved	absent from the patch entirely	✅
⛔ the fence held — no pin was added	⛔ zero expect( / it( / describe( among the added lines. The diff is 6 lines of comment prose relocated and nothing else	✅
draft, Fixes #8012	draft: true, body carries it	✅
changeset	empty frontmatter, AGENTS.md §9's first-class "not released" declaration; the presence gate says none is owed	✅

⭐ Two pieces of method worth naming, because both are the discipline this lane keeps failing at

It discarded a control that was not in the class being controlled. Its first control-byte probe used a tab, and it threw that reading out on the grounds that \x09 is deliberately outside the scanned class — so it was not a control for that class at all. ⭐ That is exactly the shape of trap this seat has hit repeatedly, caught by the dev unprompted.

Its precondition-4 zero came with an in-class firing control: '## Fixture discipline' itself (3 matches) and RESIDUE_PATTERNS (12), in the same run, on the same instrument, with the exit code captured before any pipe and the work-tree check ruling out the exit-128 false zero. ⇒ "nothing asserts this docblock's structure" is a reading, ⛔ not a silence.

⭐ And it declined to build the pin — with the right reason

The brief said a dev who believes a structural pin is warranted must report it, ⛔ not build it. It went further and argued the pin should not exist:

A pin over "every ## heading in this docblock is followed by a non-heading line" asserts shape, not truth: it goes green the moment someone puts one filler sentence under the empty heading — which is exactly the two-answers-to-one-fact outcome the card exists to prevent.

⭐ And it grounded that in the docblock's own words at :41 — "the limitation is asserted as a FACT, never as a sentence". ⇒ this seat accepts the recommendation: ⛔ no follow-up card is filed. A gate that can be satisfied by writing anything at all is not a gate.

Next

ci-wait on 6e9425dd1; then flip ready, re-read the check set after the flip, arm SQUASH, confirm the enqueue from the timeline event, and probe the landing on a re-fetched origin/main.

Landing probe, scoped now so it cannot be shaped afterwards: on origin/main, the paragraph beginning `scripts/` is not in `SCAN_ROOTS` must appear between ## Fixture discipline and ## The second skills root — checked by line order, ⛔ not by mere presence, since presence was already true before this PR. Firing control: ## Coverage still last. Nonsense control: exit 1.

---

Generated by Claude Code

[claude]

Armed — objectui#8625, 2026-09-08T18:14Z

step	reading
CI on 6e9425dd1	29 success, 3 skipped, 0 pending, 0 failures
flipped ready	ready_for_review@2026-09-08T18:13:29Z
⚠️ post-flip guard	the flip spawned a new Governed Surface Queue Guard; the post-flip run is completed/success@2026-09-08T18:13:59Z
armed	enable_pr_auto_merge SQUASH
⭐ enqueue	added_to_merge_queue@2026-09-08T18:14:08Z, from the timeline event, ⛔ not the auto_merge field

Landing probe, restated here before the merge so it cannot be shaped afterwards — and ⚠️ note the shape it has to take:

⛔ A presence check proves nothing on this card: the paragraph was already present before this PR, two sections lower. ⇒ the probe reads line order on a re-fetched origin/main:

index(`## Fixture discipline`)  <  index(`scripts/` is not in `SCAN_ROOTS`)  <  index(`## The second skills root`)

• Firing control: ## Coverage, which is a different question from residue is still the last heading in the docblock (it was not moved).
• Nonsense control: exit 1.

---

Generated by Claude Code

[claude]

LANDED — objectui#8012 via PR objectui#8625, merged e11c7bfc6

merged_at 2026-09-08T18:31:16Z. ⭐ merged and removed_from_merge_queue share that timestamp with merged: true ⇒ that removal is the merge, ⛔ not a dequeue.

Landing probe on a re-fetched origin/main (tip e11c7bfc6)

⚠️ Run exactly as the Armed note scoped it — and as line ORDER, ⛔ never presence: the paragraph was already present before this PR, two sections lower, so a presence check would have passed on the unfixed tree.

:51  ## Fixture discipline
:53  `scripts/` is not in `SCAN_ROOTS` …        <- its body, now directly beneath it
:59  ## The second skills root (objectui#7403)
:69  ## Coverage, which is a different question …   <- FIRING CONTROL: still the last heading

check	reading
order ## Fixture discipline < body < ## The second skills root	✅ 51 < 53 < 59
firing control — ## Coverage still last, ⛔ not moved	✅ 69 > 59
the file was actually read	✅ 755 lines (⛔ a bare zero would have proved nothing)
nonsense control	✅ exit 1

What is now true that was not

## Fixture discipline had no body at all, and the paragraph that belongs to it sat two sections lower with no heading of its own — because the objectui#7403 section was inserted between a heading and its own body. ⇒ from e11c7bfc6 the heading and its paragraph are together again.

⭐ The cost this repairs is not cosmetic and is already documented: PR objectui#8010 hit the fork this created, placed its new ## Coverage section at the same insertion point, and had to move it to the end instead. The defect had already cost one author a decision.

⛔ What was deliberately not built, and why the recommendation is accepted

The dispatch fence said a dev who thinks a structural pin is warranted must report it, ⛔ not build it. It reported — and argued the pin should not exist:

A pin over "every ## heading in this docblock is followed by a non-heading line" asserts shape, not truth: it goes green the moment someone puts one filler sentence under the empty heading — which is exactly the two-answers-to-one-fact outcome the card exists to prevent.

⭐ Grounded in this same docblock's own line — "the limitation is asserted as a FACT, never as a sentence". ⇒ accepted, and ⛔ no follow-up card is filed: a gate that can be satisfied by writing anything at all is not a gate.

---

Generated by Claude Code