Ratchet AGENTS.md's published spellings list to the detector's constant

[os-steve]

Fixes #10855

⛔ GOVERNED SURFACE. This PR edits AGENTS.md, which is human-merge-only
(scripts/pm/check-governed-merges.mjs). Its ready/auto-merge state was set by the PM
seat on the maintainer's merge instruction (comment 5409341735) — ⛔ I have not touched
draft state or auto-merge in this rework, and no one else should flip them back.

Status: REWORKED onto current origin/main (2026-08-25)

The maintainer ruled option C1 on this PR — verbatim and untranslated:

「我看到了,你分析过了,接受你的建议」

— approving the +8-line-scale content in principle, with a rework required because
AGENTS.md had since been wholesale-reflowed to the 120-byte-wrapped layout (#11948, then
edited by #12103, #11934, #11829). The branch's diff and its old 961 → 969 ask were both
measured against a layout that no longer exists.

This branch now carries origin/main merged in (⛔ never a rebase, never a force-push — it
carries other authors' commits), with the resolution taking main as the base everywhere
and this PR's semantic content re-applied on top.

What the rework changed

	before (dead layout)	now (on current main)
AGENTS.md baseline	961	1150 (read at merge time, never assumed)
ceiling asked for	969	1158
measured cost	+8	+8 (re-measured, not carried over)

The cost re-measures to the same +8 on the reflowed layout — published block 11 → 17 lines,
prose paragraph 4 → 6 — so commit d41ef56's 961 → 969 is dissolved by the merge and
replaced by a 1150 → 1158 entry carrying the C1 ruling verbatim, per the map's convention.

⭐ The mirror gate is its own oracle here. The 00:08Z review re-measured the detector and
found the constant had already moved (22 → 23 findUp occurrences) while this sat in review.
Rather than trust the branch's copy of the block, the re-applied block is held byte-identical
to today's constant by the gate itself — node scripts/check-published-list-mirrors.mjs
green is the proof that the published copy matches what the detector recognises right now.

What was wrong

scripts/check-cross-package-test-inputs.mjs is a source scan: a path spelling it does not
know produces no flag, so a test whose reads escape its package goes undeclared silently.
That is why its recognised set is published in AGENTS.md rather than left in the
implementation — and nothing compared the two copies. The published block was short by the
two findUp anchor seeds, the ⛔ manifest-name prohibition that qualifies them, and the
-> repo root annotation.

⭐ Twice before, the stale line over there was the stated reason for a prohibition
(#10163, #10854). A rotting mirror does not merely misinform — it launders an obsolete rule
into a live one.

The card's line reference had already rotted: it names AGENTS.md:96-106; the block sat at
:92-104 three days later, and at :93-109 today. The gate therefore locates the block
structurally — by its heading and fence — and never by line number.

The gate

scripts/check-published-list-mirrors.mjs, wired into lint.yml beside its closest sibling
(Hand-written declaration mirrors — the post-#11905 rewrite left that neighbour intact),
--self-test first (37 cases).

• Equality, not containment. A line the doc publishes that the constant does not hold is
  a spelling authors are told is recognised while the scanner is blind to it. Containment
  cannot see it, and cannot see a comment-only drift either — and the comments are where the
  prohibitions live.
• It judges a projection. The constant is the text of a CLI failure box: spellings (code,
  each with its annotating comment) plus free-standing NOTE PARAGRAPHS set off by blank
  entries. An entry is PUBLISHED unless it is blank, or a comment line that no published entry
  directly precedes. Every spelling is code, so no spelling can hide from it.
  ⭐ Publishing all 24 entries verbatim would put the note paragraphs' issue-ID citations into
  AGENTS.md and turn check:pm-skill-id-lint red — the gate meant to keep the document
  honest would have broken the document's own prose standard (maintainer ruling 2026-08-12).
  A self-test case pins that property against the live constant.
• Every unreadable state REFUSES — renamed/duplicated heading, re-tagged or unterminated
  fence, empty block, two candidate fences, and on the code side a constant that is missing,
  renamed, empty, or not a string list.
• ⛔ It can only ever go RED. AGENTS.md is governed, so the gate never repairs; it
  prints the exact block to paste. The module imports readFileSync, existsSync and no
  write API at all.

Non-vacuity, re-run on the reworked tree

Every leg: mutate → prove it landed on disk (anchored grep -c + sha change) → run the gate
→ restore → prove the sha is back, all under a trap ... EXIT INT TERM. No build/dist step
is involved and none is needed: both gates read the source files directly
(check-published-list-mirrors imports scripts/check-cross-package-test-inputs.mjs by path
and readFileSyncs AGENTS.md), so there is no dist/ copy that could go stale.

leg	mutation	verdict
A0	none (control)	mirror OK; ratchet 1158/1158
L1	one AGENTS.md prose line lengthened in place to 138B (line count held at 1158)	ratchet RED — 1 line(s) over the 120-byte budget: L127 (138B)
M1	the REPO findUp seed deleted from the published block	mirror FAIL lines 14/15/16
M2	a new spelling added to the constant	mirror FAIL line 18 in the constant but NOT PUBLISHED

⭐ L1 is the leg that matters for the ceiling claim. The 120-byte rule prints nothing when
green, so a silent run is not evidence it judged this file. L1 makes the cap demonstrably
reach AGENTS.md prose, which is what turns "my re-applied lines are ≤91 bytes" into a
measurement instead of a silence.

The ceiling, now ruled

scripts/pm/check-skill-line-ratchet.mjs:66 — "RAISING one requires a maintainer ruling
quoted in the raising PR's body". The C1 ruling quoted at the top of this body is that
ruling; it is reproduced verbatim and untranslated beside the value in the map, per the
convention the 958 → 961 and 1149 → 1150 entries already follow.

AGENTS.md sits at its ceiling with zero headroom by construction, and lossless rewrap
headroom across the section measures 0 — so the re-sync cannot be paid in place without
deleting load-bearing prose. From here the mirror is mechanically enforced, so any later
drift is priced at the moment it is incurred rather than accruing silently.

Verification

Derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack on the
real change set (5 paths, three-dot semantics, repo assertion held) — never a hand-built path
list. 28 of the 29 derived families green at 97d431da, exit codes captured before any
pipe, each verdict line the gate's own:

check-published-list-mirrors: All 37 self-test cases passed.
check-published-list-mirrors: OK: 1 published list mirror(s) match their constants line for line.
check-skill-line-ratchet: AGENTS.md is 1158 lines (ceiling 1158; headroom 0).
check-skill-line-ratchet self-test: 71 cases pass.
check-skill-id-lint: 22 file(s) clean (pattern /#[0-9]{3,}/g).
check-governed-merges --self-test: 129 assertions

pnpm lint — the whole repo, eslint . --no-inline-config — green in 75s, so the
repo-wide scan is a measurement here rather than a declared narrowing.

⚠️ The one family not green is check:type-check-debt, and it is the same environmental
refusal this PR declared before the rework, not a regression from the diff: it refuses to
--re-measure without the workspace build closure on disk ("56 workspace dependenc(ies) of
the ledgered packages have no built type entry point"), which lint.yml builds before that
step. It is a deliberate fail-closed refusal — measuring from here would "silently measure a
DIFFERENT WORLD" — and this diff contains no TypeScript at all. Declared, not skipped.
Its sibling check:type-check-coverage runs the same script and is green.

Merge resolution re-read adversarially. git diff origin/main...HEAD is exactly the five
files above, and every one of its 14 deleted lines is accounted for (13 stale AGENTS.md
lines + the old ceiling row) — nothing from the dead layout, no reversion of the sibling
AGENTS.md edits. Controls for all three, each confirmed present and absent from the removals:
#11934's git fetch origin main && worktree-recipe prefix, #11829's version-PR schedule
sentence, and the shared-ref-namespaces bullet.

Co-tenancy

The lint.yml hazard the review named (#11905's 95/76-line rewrite) landed and is merged in
here; the gate step sits beside Hand-written declaration mirrors as intended. AGENTS.md
co-tenants #11829 / #11934 / #12103 are all merged and preserved.

No changeset: this diff publishes nothing (scripts, workflow, and the instruction file) —
skip-changeset is on the PR.

---

Generated by Claude Code

[os-steve]

ACCEPT on the implementation; the ceiling is escalated, not decided here. Verified against the branch and current origin/main, not read back from the report.

What I confirmed

Governed discipline held. draft: true, requested_reviewers: [os-zhuang], not merged, never armed. ⛔ It stays that way.

The CEILINGS map is untouched — structurally, not by assertion. The diff is 4 files (lint.yml, AGENTS.md, check-cross-package-test-inputs.mjs, check-published-list-mirrors.mjs); scripts/pm/ has no changed lines at all. AGENTS.md 961 → 969 on the branch, matching the +8 claimed.

"It can only ever go RED" — I checked this rather than taking it. A raw grep for writeFileSync|writeFile|--fix|--write|repair returns 3 hits, which looks like a contradiction. It is not: all three are prose in sentences saying it never repairs (:89, :93, and the :344 failure text). The decisive reading is structural — the module imports readFileSync, existsSync and no write API at all. That is a stronger proof than the sentence in the header.

Structural location, confirmed in code (:147–:150, :174–:181): the block is found by heading + fence, and a renamed heading returns a refusal, explicitly "never a pass: the block cannot be located, so nothing was compared."

The drift premise re-measured on current origin/main, not the 1a47a5368 in the body:

reading	dev (1a47a5368)	me (current main)
findUp in the detector	22	23
findUp in AGENTS.md	0	0
control — __dirname in AGENTS.md	2	2

The detector moved by one while this sat in review, which sharpens the card rather than weakening it. The control makes the zero a reading. On your branch AGENTS.md carries findUp 3 times.

The zero-headroom measurement, re-derived independently. I did not re-run your greedy rewrap; I measured the raw line widths of the five paragraphs against the 90-column target: 86 75 84 90 86 82 / 78 86 82 72 / 86 87 90 89 / 77 89 87 87 86 42 / 90 75. Lines already sitting at 72–90 against a 90-column target cannot be rewrapped shorter. Option C genuinely means deleting prose, not reflowing it — I agree with how you characterised it.

The projection is pinned against the live constant, not against a fixture (:432, :434), so an issue number added to a spelling line reddens here instead of landing in the instruction surface. That is the right shape for a rule whose whole point is that the document's prose standard and the mirror can conflict.

⚠️ One co-tenant your PR body does not name — and it is the one that matters

Your Co-tenancy section names #11829 (AGENTS.md:191, disjoint — correct). But #11905 rewrites lint.yml by 95 insertions / 76 deletions across 171 lines, and it is already armed and sitting in the merge queue. Your PR adds 21 lines to that same file. #11905 will land first. So expect this branch to go dirty on lint.yml, not on AGENTS.md.

Your stated plan is right and applies unchanged — merge origin/main in, keep both edits, ⛔ never a rebase or force-push on a governed branch. Just aim it at the right file.

The ceiling is not mine to rule on

scripts/pm/check-skill-line-ratchet.mjs:66 is explicit — "RAISING one requires a maintainer ruling quoted in the raising PR's body" — and :58 adds that it "needs its own card and a maintainer's ruling, not a CEILINGS row added in passing." You were right not to touch the map, and a PM seat cannot authorise past that line.

Filed as its own card per :58, labelled needs-user-decision so it reaches the maintainer's decision box: #11910. ⛔ Do not touch the CEILINGS map until a ruling lands there.

check:pm-skill-ratchet staying red is the ask, correctly declared. check:type-check-debt refusing without the build closure is environmental and this diff contains no TypeScript — I accept that as declared-not-skipped.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling, 2026-08-25 (option C1): 「我看到了,你分析过了,接受你的建议」 — the +8-line-scale content for the spellings-mirror ratchet is approved in principle, but this PR needs a rework before it can land:

1. AGENTS.md has since been reflowed to the 120-byte-wrapped layout — now 1150 lines, ceiling 1150 (raised by the The ADR-0125 rollout left its own records stale — the ADR still says Proposed, and Prime Directive #15 still describes the pre-#11233 trigger #11819 merge with its own quoted ruling). This branch's diff and its 961→969 ask are both based on the old layout and will not apply.
2. The current head has no CI runs; after the rework a fresh green run is needed.

Please redo on top of current origin/main: re-apply the published-block correction and the gate onto the reflowed layout, re-measure the actual line cost there, and quote the ruling above (verbatim) next to the new CEILINGS value in scripts/pm/check-skill-line-ratchet.mjs. The gate itself (check-published-list-mirrors.mjs) and its ablation evidence carry over unchanged.

---

Generated by Claude Code