Skip to content

AGENTS.md's RECOGNISED_PATH_SPELLINGS mirror has drifted three times — nothing checks that the published list matches the detector #10855

Description

@claude

Filed by the domain:devx PM seat (#6023, session session_01DdCnBGcHeufjrq7drTD3wt) as ruling C on PR #10852's open question 1. Unassigned; recording the class, not claiming it.

The mirror, and that it is unchecked

scripts/check-cross-package-test-inputs.mjs recognises a fixed set of directory-seed and path spellings. Its own header says the set is "printed in the failure text and mirrored in AGENTS.md" — the published copy lives in the fenced block at AGENTS.md:96-106.

Nothing mechanically compares the two. The detector can grow a spelling and the published list can stay short indefinitely; the only signal is a human noticing.

Three rounds, which is what makes it a class

rounddriftoutcome
1#10163 — three files said the detector recognised two seeds; it recognised five (widened by #8995 / #9763)closed by #10690
2#10854 — three files still say the detector cannot resolve a findUp walk; after PR #10852 it canopen
3thisAGENTS.md:96-106 is short by the two findUp anchor seeds PR #10852 addsopen

⭐ Rounds 1 and 2 share a nastier property, and it is the reason this is worth mechanising rather than re-fixing: in both, the stale sentence was the stated reason for a prohibition.#10163's wrong "only two seeds" line was the justification for "this seed may not change"; #10854's is the same shape. A rotting mirror does not merely misinform — it launders an obsolete rule into a live one.

⚠️ Note also that one of #10854's three claims ("process.cwd() appears nowhere in that detector") was already false on origin/main before PR #10852 — it occurs once, in prose at :1346. So the drift is not only "the code moved and the docs lagged"; a published claim was wrong on arrival and nothing caught it.

What a remedy looks like

A gate asserting that every entry in the detector's RECOGNISED_PATH_SPELLINGS appears in AGENTS.md's published block — the same shape as the repo's other mirror ratchets. Cheap, and it retires the class instead of its third instance.

⚠️ Two things whoever takes this must weigh, neither of which I am deciding:

  1. AGENTS.md is governed (scripts/pm/check-governed-merges.mjs:274-280), human-merge-only. A gate that reads it is fine; a fix that edits it is a maintainer merge. So the gate can only ever red — it can never auto-repair — and the card should say so up front rather than discovering it at review.
  2. The comparison must not be a phantom check. A gate that greps for a literal that happens to appear anywhere in AGENTS.md, or that passes vacuously when the block cannot be located, re-creates the defect it is closing one level up. It needs a self-test with an ablation in both directions: a spelling added to the detector and not to AGENTS.md must red, and a mangled/renamed fenced block must refuse rather than pass empty.

⛔ Not in scope: widening or narrowing what the detector recognises. This is about keeping the published copy honest, nothing else.

Refs: PR #10852 (#10029 direction B, where this surfaced) · #10854 (round 2, open) · #10163#10690 (round 1) · #8995 / #9763 (the widenings that started the drift)


Generated by Claude Code

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions