Filed as its own card because scripts/pm/check-skill-line-ratchet.mjs:58 requires it: a ceiling change "needs its own card and a maintainer's ruling, not a CEILINGS row added in passing.":66 and :85–:86 add that raising one requires a maintainer ruling quoted verbatim in the raising PR.
Why a repair is owed at all
scripts/check-cross-package-test-inputs.mjs is a source scan, so a path spelling it does not recognise produces no flag — a test whose reads escape its package goes undeclared silently. That is why its recognised set is published in AGENTS.md instead of living only in the implementation. Nothing held the two copies in step, and the copy has drifted three times (#10163, #10854, #10855). Measured on current origin/main:
| reading | count |
|---|
findUp occurrences in the detector | 23 |
findUp mentions in AGENTS.md | 0 |
control — __dirname in AGENTS.md (a spelling that IS published) | 2 |
The control makes that zero a reading rather than a dead grep. ⭐ Twice the stale line was the stated reason for a prohibition, so a rotting mirror does not merely misinform — it launders an obsolete rule into a live one.
Why it cannot be paid in place
The ratchet's doctrine is to cross a ceiling by compressing in place. AGENTS.md sits at 961/961 — zero headroom, and the section cannot be reflowed shorter. Raw line widths of the five paragraphs, against the 90-column target the previous raise was measured at:
lines 80-85: 86 75 84 90 86 82
lines 87-90: 78 86 82 72
lines 106-109: 86 87 90 89
lines 111-116: 77 89 87 87 86 42
lines 118-119: 90 75
Lines already sitting at 72–90 against a 90-column target have no slack. The dev measured lossless rewrap headroom at 0 lines by greedy rewrap; I re-derived the widths independently and reach the same conclusion. Compression here means deleting content, not reflowing it.
The +8, itemised
| cost | lines |
|---|
block 11 → 17: the two findUp anchor seeds (one broken across two lines) | +3 |
| the ⛔ manifest-name prohibition that qualifies them | +2 |
the -> repo root annotation | +1 |
| prose 4 → 6: names the ratchet and that it can only go red | +2 |
+6 is the smallest number that leaves the block honest; +8 is the smallest that leaves it honest AND self-documenting.
Options
- A — raise 961 → 969, recorded in the map's comment the way the only previous raise (958 → 961) is, with the ruling quoted verbatim.
- B — raise to 967 and drop the two prose lines that name the ratchet. Authors then meet the gate as a CI red instead of reading about it in the file.
- C — compress 8 lines elsewhere in the section. Measured headroom is 0, so this means deleting load-bearing prose.
- D — stop publishing the list in
AGENTS.md and point at the tool (net −8, and it retires the drift class outright rather than policing it).
Recommendation: A
C is the one I'd rule out. It buys lines by deleting the section's own reasoning — trading a documentation defect for a worse one on the same page, and the prose it would have to cut is the prohibitions themselves.
D deserves a fairer hearing than "it contradicts the section." It is the only option that ends the class instead of policing it, and the sentence it contradicts is itself a policy choice you could revisit. What settles it against D: AGENTS.mdis the instruction surface agents read, and the failure mode here is silence — an unrecognised spelling yields no flag, so the published list is the only thing telling an author what the scanner can see. An agent that must shell out to a tool to learn the spellings will frequently just not, and will never know it guessed wrong. The published copy earns its lines. But if the ceiling must hold at 961, D is the honest choice, not C — it needs the published-list paragraph deliberately rewritten, which is your call, not a line-budget tactic.
A over B is the closer call. B's two lines are real savings and "authors meet it as a CI red" is a survivable cost. A wins because the gate is new and otherwise undiscoverable — and this whole card exists because a silent mechanism was undiscoverable. Learning about a ratchet from a red at review time is exactly the cost #10855 was filed to remove.
A is also a one-time truthful re-sync of a copy that had rotted, not a growth trend: the mirror is mechanically enforced from now on, so every later line is priced at the moment it is incurred.
The follow-up once a ruling exists is one line — ['AGENTS.md', 961] → ['AGENTS.md', 969] in scripts/pm/check-skill-line-ratchet.mjs, with the ruling quoted beside it.
Filed as its own card because
scripts/pm/check-skill-line-ratchet.mjs:58requires it: a ceiling change "needs its own card and a maintainer's ruling, not a CEILINGS row added in passing.":66and:85–:86add that raising one requires a maintainer ruling quoted verbatim in the raising PR.check:pm-skill-ratchetis red there until this is ruled.Why a repair is owed at all
scripts/check-cross-package-test-inputs.mjsis a source scan, so a path spelling it does not recognise produces no flag — a test whose reads escape its package goes undeclared silently. That is why its recognised set is published inAGENTS.mdinstead of living only in the implementation. Nothing held the two copies in step, and the copy has drifted three times (#10163, #10854, #10855). Measured on currentorigin/main:findUpoccurrences in the detectorfindUpmentions inAGENTS.md__dirnameinAGENTS.md(a spelling that IS published)The control makes that zero a reading rather than a dead grep. ⭐ Twice the stale line was the stated reason for a prohibition, so a rotting mirror does not merely misinform — it launders an obsolete rule into a live one.
Why it cannot be paid in place
The ratchet's doctrine is to cross a ceiling by compressing in place.
AGENTS.mdsits at 961/961 — zero headroom, and the section cannot be reflowed shorter. Raw line widths of the five paragraphs, against the 90-column target the previous raise was measured at:Lines already sitting at 72–90 against a 90-column target have no slack. The dev measured lossless rewrap headroom at 0 lines by greedy rewrap; I re-derived the widths independently and reach the same conclusion. Compression here means deleting content, not reflowing it.
The +8, itemised
findUpanchor seeds (one broken across two lines)-> repo rootannotation+6 is the smallest number that leaves the block honest; +8 is the smallest that leaves it honest AND self-documenting.
Options
AGENTS.mdand point at the tool (net −8, and it retires the drift class outright rather than policing it).Recommendation: A
C is the one I'd rule out. It buys lines by deleting the section's own reasoning — trading a documentation defect for a worse one on the same page, and the prose it would have to cut is the prohibitions themselves.
D deserves a fairer hearing than "it contradicts the section." It is the only option that ends the class instead of policing it, and the sentence it contradicts is itself a policy choice you could revisit. What settles it against D:
AGENTS.mdis the instruction surface agents read, and the failure mode here is silence — an unrecognised spelling yields no flag, so the published list is the only thing telling an author what the scanner can see. An agent that must shell out to a tool to learn the spellings will frequently just not, and will never know it guessed wrong. The published copy earns its lines. But if the ceiling must hold at 961, D is the honest choice, not C — it needs the published-list paragraph deliberately rewritten, which is your call, not a line-budget tactic.A over B is the closer call. B's two lines are real savings and "authors meet it as a CI red" is a survivable cost. A wins because the gate is new and otherwise undiscoverable — and this whole card exists because a silent mechanism was undiscoverable. Learning about a ratchet from a red at review time is exactly the cost #10855 was filed to remove.
A is also a one-time truthful re-sync of a copy that had rotted, not a growth trend: the mirror is mechanically enforced from now on, so every later line is priced at the moment it is incurred.
The follow-up once a ruling exists is one line —
['AGENTS.md', 961]→['AGENTS.md', 969]inscripts/pm/check-skill-line-ratchet.mjs, with the ruling quoted beside it.