Prevent + detect canonical-source drift in machine-local vendor files (CLAUDE.md, ~/.codex/AGENTS.md) — starting with the worktree-placement gap

[nathanjohnpayne]

What to document

Concrete gap: Neither the canonical docs (docs/agents/operating-rules.md § "Worktree lifecycle") nor the Phase 4b trusted-path text (REVIEW_POLICY.md, AGENTS.md, scripts/phase-4b/README.md) say where on disk a trusted-main-ref checkout or a Phase 4b external-reviewer session should live. The trusted-path rule ("run from a trusted main-ref checkout, never from the PR-under-review's own checkout") is entirely about which ref/branch — it says nothing about filesystem location — so an agent following it correctly can still land its checkout somewhere inconsistent (a stray sibling directory, /tmp, anywhere).

This surfaced concretely: in a downstream repo (gaycruisebingo), a Phase 4b manual-handoff external review (nathanpayne-codex) created its trusted checkout at /tmp/gaycruisebingo-pr135-review. The review itself was correct (right ref, real fixes, genuine APPROVED), but the checkout location doesn't match that machine's own worktree-hygiene convention (git worktrees for PR/branch work live in a hidden per-repo folder, ~/GitHub/.<repo>-worktrees/<slug>, never /tmp or a visible sibling dir) — because that convention is only documented locally on that machine's ~/GitHub/CLAUDE.md, not in mergepath, so it never reached the reviewer session.

The systemic gap this reveals: ~/GitHub/CLAUDE.md is not version-controlled — it's a loose, untracked file outside any git repo. Some of its sections carry an explicit > Canonical source: mergepath/... annotation (e.g. the 1Password PAT lookup table), meaning a mergepath change is known to require syncing back. "Worktree Placement" carries no such annotation — proof that it was authored directly into the machine file and never pushed into mergepath, with nothing catching that omission. Every coding-agent CLI on the machine has (or could have) its own such file — Claude Code discovers CLAUDE.md by walking up the directory tree; Codex CLI already reads a global ~/.codex/AGENTS.md (currently empty); Cursor has its own rules-file convention — so content added to any ONE of them is invisible to the others unless someone remembers to mirror it by hand.

Propagation and new-repo feasibility (verified, not assumed)

Before proposing fixes, I checked whether mergepath's existing propagation machinery (.mergepath-sync.yml, scripts/sync-to-downstream.sh, the bootstrap wizard) would carry a docs/agents/operating-rules.md fix to existing consumers or new repos automatically. It will not, for two separate, verified reasons:

1. docs/agents/*.md, AGENTS.md, and REVIEW_POLICY.md are not in .mergepath-sync.yml's tracked paths at all. The manifest only covers .github/, examples/, scripts/, and tests/ (canonical/kit/templated entries). So even for the 8 actively-synced consumers (matchline, nathanpaynedotcom, overridebroadway, device-source-of-truth, friends-and-family-billing, device-platform-reporting, swipewatch, tadlockpsychiatry), a docs fix here never auto-propagates — it needs manual, per-repo porting. This isn't a new problem: docs/agents/documentation-rules.md already documents this exact posture for the Markdown prose-wrap convention ("Other repos have no gate yet — apply the convention by hand"). Mergepath has already chosen "apply by hand" once for a closely analogous case; this issue should decide explicitly whether to extend that same posture or diverge from it, not silently assume one or the other.

2. The bootstrap wizard (scripts/bootstrap-new-repo.sh / scripts/bootstrap/template-mirror.sh) rsyncs mergepath's LIVE current worktree into a brand-new repo (not a frozen template snapshot), so a repo bootstrapped after a docs fix lands would inherit it automatically — the new-repo case is handled for free, for the doc-fix half of this issue. It is NOT handled for the canonical-source-discipline / audit-script half, because that targets machine-level files (~/GitHub/CLAUDE.md, ~/.codex/AGENTS.md) that exist outside any repo and are never touched by bootstrap regardless of repo age.

Feasibility of actually syncing docs (not just documenting them), evaluated against the existing sync-type taxonomy:

• Option A — add whole docs/agents/*.md files as canonical/kit manifest entries. Rejected as infeasible for most files: canonical requires a byte-identical match and kit only tolerates extra files in a directory, not extra sections inside one file. Most docs/agents/*.md content (deployment specifics, testing frameworks, repo layout) is legitimately repo-specific — a byte-identical sync would either force-overwrite real per-repo customization or immediately register as permanent "drift" on every consumer.
• Option B — extract only the genuinely universal, tech-stack-independent policies into small, dedicated single-purpose files (e.g. docs/agents/worktree-placement.md), and sync those as ordinary canonical entries — the same proven mechanism already used for scripts/*.sh. Each consumer's own operating-rules.md (or equivalent) references/links the dedicated file rather than embedding the policy text inline. Recommended starting point — reuses existing, already-trusted machinery with no new sync-engine work, and sidesteps the mixed-content problem in Option A by never mixing universal and repo-specific prose in the same file in the first place.
• Option C — a lighter, non-git "canonical policy audit": a registry of policies mergepath considers universal (name + canonical text/hash + mergepath path), checked by a script — the SAME script proposed below for machine-level files, generalized to also run against a repo's own doc tree — that flags drift without opening a PR or overwriting anything. Safer against clobbering legitimate customization than A or B, but weaker: it surfaces drift, it doesn't fix it, so someone still has to act on the report.

None of these is mutually exclusive with the others. B (small canonical docs, synced like scripts) is the concrete, low-risk first move; C (the generalized audit) is a good complementary safety net whether or not B ships, and unifies with the machine-level audit-script scope below into one tool instead of two.

Acceptance criteria

• docs/agents/operating-rules.md § "Worktree lifecycle" documents a placement convention for agent-created worktrees/checkouts (a hidden per-repo folder pattern, e.g. ~/GitHub/.<repo>-worktrees/<slug>, or whatever mergepath adopts as canonical) — not just cleanup of them.
• The Phase 4b trusted-path rule text (REVIEW_POLICY.md, AGENTS.md, scripts/phase-4b/README.md) cross-links to that placement convention.
• A decision is made and recorded on Option A/B/C above (or a combination) for propagating this specific convention (and future ones like it) to the 8 existing consumers — not left implicit. If Option B is chosen, the new dedicated file(s) are added to .mergepath-sync.yml as canonical entries and at least one canary consumer sync is exercised per the manifest's own canary-first procedure.
• A short "canonical-source discipline" rule is added to mergepath's docs instructing agents: new cross-repo / agent-agnostic conventions get authored in mergepath first (in a dedicated synced file if Option B ships, else in docs/agents/*.md generally), then mirrored into any vendor-specific file (CLAUDE.md, ~/.codex/AGENTS.md, a consumer's own docs) with a > Canonical source: ... annotation — never authored directly into the downstream/vendor copy first.
• A new script (name TBD, e.g. scripts/audit-canonical-mirrors.sh) that: takes a configurable list of local vendor files (default candidates: ~/GitHub/CLAUDE.md, ~/.codex/AGENTS.md) AND, if Option C is pursued, a consumer repo's own doc tree, parses top-level sections, and reports (read-only — no auto-edits, no auto-migration) which sections lack a Canonical source: annotation or have drifted from the annotated source, as candidates for a human/agent to triage. Documented as an on-demand / session-finalization-style local check, explicitly NOT wired into any GitHub Actions workflow for the machine-file case (unreachable from CI) though it MAY be wireable as a consumer-repo CI check for the Option-C doc case.
• The updated docs are honest about scope: machine-level files only benefit an operator who runs the script locally — mergepath's own CI cannot see or enforce anything about files outside a git repo it doesn't have access to.

Notes / risks

• The audit script is expected to produce false positives on genuinely machine- or repo-local content that will never need a canonical-source line; it must not attempt to auto-classify or auto-migrate — the judgment of "is this cross-agent-worthy" stays with whoever reviews the flagged output.
• Don't conflate any of this with propagation-drift / weekly-drift-audit.yml / scripts/sync-to-downstream.sh --audit — that mechanism is repo-to-repo, CI-driven, and manifest-scoped to .github//examples//scripts//tests/; it does not see docs today and does not see files outside a tracked consumer repo at all.
• Separate, already-filed issue: gaycruisebingo — the repo that surfaced this whole thread — is registered in mergepath's "loop docs" (DEPLOYMENT.md, REVIEW_POLICY.md) and carries byte-identical mergepath scripts (confirmed: scripts/gh-as-author.sh diffs clean), but is absent from .mergepath-sync.yml's consumers: list — so none of this (or any future mergepath change) reaches it via the ongoing sync mechanism regardless of what this issue decides. Tracked separately; do not fold that fix into this issue.
• Affected consumers: any repo's AGENTS.md/docs/agents/*.md that mirrors mergepath content, plus every vendor-specific machine-level file (Claude, Codex, and any future agent CLI) that should eventually carry canonical-source annotations pointing back here.