AGENTS.md migration gaps for repos bootstrapped before #297

[stackbilt-admin]

Follow-up from #297 / PR #301, which changed bootstrap and adf init --emit-pointers to write uppercase AGENTS.md and removed lowercase agents.md from the generated pre-commit hook's VENDOR_FILES. That fix is correct for new repos but leaves three gaps for repos that already exist.

1. Repos tracking lowercase agents.md lose hook auto-tidy

The generated hook matches git diff --cached --name-only, which reports git's recorded path. After charter hook install --pre-commit is re-run, a tracked lowercase agents.md matches nothing in VENDOR_FILES and silently stops being auto-tidied on commit — on any filesystem, case-sensitive or not.

Mitigations that already exist: charter adf tidy and charter doctor run directly still handle both spellings (adf-tidy.ts keeps both deliberately). Generated hooks in existing checkouts don't change until reinstall, so this is latent rather than immediate.

Affected population is precisely the people who bootstrapped before the fix — i.e. the reporter of #297.

2. A hand-written uppercase AGENTS.md on Linux hits a dead end

bootstrap tells the user to run charter adf migrate first, but AGENTS.md is not in the AGENT_CONFIG_FILES scan lists (adf-migrate.ts:44, bootstrap.ts:960) — migrate never looks at that name. The instruction cannot succeed.

3. Adding AGENTS.md to those scan lists needs de-dup first

On a case-insensitive mount (macOS, WSL /mnt/c) agents.md and AGENTS.md are the same file, so naively adding the uppercase name double-processes it. This is not hypothetical: adf-tidy.ts:34-35 already walks the same file twice on such mounts today.

What a fix needs

• A migration path for existing lowercase agents.md (case-safe two-step git mv, with handling for dirty index / untracked file / non-git directory — deliberately deferred from PR fix(bootstrap): emit AGENTS.md instead of lowercase agents.md #301 as a feature in its own right)
• AGENTS.md added to the migrate scan lists, gated behind case-insensitivity de-dup
• Ideally a doctor check that detects a tracked lowercase agents.md and tells the user what to run

Identified during constellation-loop review of PR #301.

[stackbilt-admin]

Docs sweep update — 2026-09-20

All three gaps are still open. Line references have shifted (#317 refactored bootstrap, #319 touched tidy), and there is now a precedent for the doctor check this issue asks for.

Stale line references:

Cited	Current	Still true?
adf-migrate.ts:44 — AGENT_CONFIG_FILES	adf-migrate.ts:41	yes — AGENTS.md is still absent from the scan list
bootstrap.ts:960 — scan list	bootstrap.ts:1058-1059	yes — the array carries lowercase 'agents.md' only
adf-tidy.ts:34-35 — the double-walk	adf-tidy.ts:32-38	yes — VENDOR_FILES still lists both agents.md and AGENTS.md

So gap 2 (a hand-written uppercase AGENTS.md hits a dead end, because bootstrap advises charter adf migrate and migrate never scans that name) and gap 3 (adding it naively double-processes on a case-insensitive mount) are both confirmed live on 156c522.

New precedent for the third bullet under "What a fix needs". This issue asks for "ideally a doctor check that detects a tracked lowercase agents.md and tells the user what to run". #306 / PR #316 has since built exactly that shape for a different drift: checkTelemetryTracking reads the git index via git ls-files, names the offending paths, and prints an ordered remedy. Two design points from it that apply directly here:

• It reads only the git index, never fs.existsSync. That matters a great deal for this issue, since the whole problem is case: existsSync is case-blind on /mnt/c and macOS while git is case-sensitive, so an index-only check behaves identically on both and a test cannot pass locally while the logic is wrong on a case-sensitive checkout.
• It is INFO, not WARN, deliberately — doctor fails CI on any WARN, and this class of drift is state Charter's own bootstrap created rather than something the user opted into, so warning would break an existing repo's CI purely on upgrade. A tracked lowercase agents.md is the same class and should be INFO for the same reason. Precedent and rationale: doctor.ts:511-513 (#186).

Unchanged: the migration path for an existing lowercase agents.md (case-safe two-step git mv, handling a dirty index, an untracked file, and a non-git directory) is still the substantial part, and still a feature in its own right rather than a bugfix.

Auto-updated by /docs skill.