#1280 Add a refresh path that edits an existing AGENTS.md instead of redrafting it

[williamthorsen]

What

Refines the update-project-guidance skill so that modification of an existing AGENTS.md is performed differently from generation of a new one. If an existing file already contains substantive guidance, the skill instructs an agent to edit it in place, making only the revisions needed to align its content with the codebase.

Separately, the published guidance checklist now also checks that the repository-root AGENTS.md file is harness-neutral and contains no CodeAssembly-managed rulebook regions.

Why

Run against a mature AGENTS.md, the skill drafted a replacement from its skeleton, so the densest sections, the ones carrying the most value, were the likeliest to be summarized away. Nothing checked the file's claims against the codebase either, and drift is what actually goes wrong in a mature ambient file: a stale directory listing, a count off by two, a tool named one hop from what runs. Each of those passes every check the guidance checklist could answer, whose only drift signal was a freshness count that any edit resets.

Details

🎉 Features

• Baseline resolution and path selection (Phase 1). The baseline is the first candidate carrying substantive claims: the repo-root AGENTS.md, else .agents/PROJECT.md, else .agents/AGENTS.md. A baseline takes the refresh path; no baseline takes the authoring path. Where both legacy files carry content, .agents/PROJECT.md is the baseline as the later convention and the other joins the gap-scan sources, so its content reaches the change list rather than being archived unread. The baseline resolves in memory, leaving the write gate as the only point the skill writes anything.
• Two constraints on the repo-root file (Phase 3), governing both paths. No path into a harness-owned directory, home-anchored or repository-local, since one body of text serves every harness; and no <!-- rulebook: marker, because sync strips a complete region from that file and an unpaired marker escapes the sweep instead.
• The refresh path (3c). A constraint pre-pass makes every violation a repair whatever the audit says about it. A two-tier audit follows: tier 1 sweeps every checkable token exhaustively, tier 2 the narrative prose in sections the gap-scan window touched. Verdicts are holds (requiring the command run or the path:line read as evidence), drifted (stating what is true now), and unchecked (stating why), and the ledger closes by naming what it did not audit.
• A bounded gap scan. The window reaches back to whichever is earlier: the last commit touching AGENTS.md, or twenty commits. Twenty is a floor, never a ceiling, so a drive-by edit to the file cannot shrink it. git status --porcelain joins it for the mid-session case, every git log names its own --format against a configured format.pretty, and a repository without history states its bound as whole-repo additions. One unbounded check against the skeleton asks whether an ambient category is missing altogether.
• Change-list vocabulary and placement. Anything the list does not name is carried through byte-identical. An addition lands in its matching skeleton section, a new section needs the user's agreement, a removal or relocation names its destination as a recommendation, and a relocation behind a pointer is the sanctioned response to an overrun of the line budget. A worked example carries a four-row ledger and the change list it produced.
• A closing checklist step (3g). Both paths end by running the published guidance checklist with rdy run --packages from the repository root, skipped where rdy is absent or no configured package publishes the kit, and never reported as a pass it did not produce. The freshness check's outcome is pre-declared: it reads committed history, so it still reports stale on an uncommitted refresh and its advice to re-run the skill is not to be acted on.
• Two checks in the guidance kit. AGENTS.md is harness-neutral and AGENTS.md hosts no rulebook region, both at recommend severity beside the existing content-quality checks, each skipping when the file is absent and reporting every offending line by number. Detection lives in guidance-constraints.ts as pure string transforms, matching the lib/ shape of guidance-import, guidance-size, and guidance-staleness.

🧪 Tests

• 16 unit tests over the three detection helpers in guidance-constraints.unit.test.ts: both harness-path spellings, a harness other than Claude, 1-based line numbers across a multi-line body, the .agents/ and .config/ near-misses that must not fire, an opening marker, a closing marker, an unpaired opener, irregular marker spacing, and a comment that merely mentions rulebooks.
• One test pins the detection pattern to the canonical HARNESSES table: a harness added there fails the suite until the pattern covers its home directory in both spellings. The pattern restates those two directory names so the compiled kit carries string literals rather than the table's filesystem imports, and the pin is what keeps that duplication from going stale unnoticed.

Closes #1280

[github-actions]

Dependency audit

Production dependency audit passed.