feat: machine-scoped guidance blocks go user-level — ~/.codex/AGENTS.md target (ADR-0008) - #50
Merged
Merged
Conversation
…md target (ADR-0008) The block registry knew two guidance targets: machine-wide ~/.claude/CLAUDE.md and the PROJECT AGENTS.md. That asymmetry meant (a) only synced repos ever got codex-side guidance, and (b) machine state leaked into git — the dual-mode block exists only when both hosts are enabled in kit.json, a fact about one machine, yet it was committed into shared checked-in AGENTS.md files. - New `agents-user` target → ~/.codex/AGENTS.md (codex's global guidance file). Dir-exists gated — ak never creates ~/.codex; one-time .bak before the first managed rewrite, mirroring CLAUDE.md's. - `ruflo-dual-mode-reference` re-scoped to ['claude','agents-user']; the project `agents` target stays for genuinely repo-scoped rows. - Migration: each target now also strips sentinel-present blocks that no longer list it (`retiredForTarget` forced-strip rows), so project AGENTS.md files carrying the old block heal on their next sync. - One shared `guidanceTargets()` helper replaces the duplicated target lists in sync.mjs/status.mjs. - Docs aligned with this and #47/#48: template sentinel comment, README setup/status/dual rows (truthful natives, memory-pin, pre-flight refusal), MAINTAINER.md registry description, UPGRADING/ TROUBLESHOOTING remedies. ADR-0008 records the scope split. 314 kit tests green (10 new); full check chain green. Live dry-run: CLAUDE.md upsert + project AGENTS.md strip + ~/.codex/AGENTS.md upsert.
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The block registry knew two guidance targets: machine-wide
~/.claude/CLAUDE.md(claude) and the projectAGENTS.md(codex). Two consequences of that asymmetry, one of which bit this very repo today:ak synchas run ever get codex-side guidance — fresh clones and new projects get nothing.AGENTS.mdfiles (see 371da30 on this repo).Codex has the exact mechanism for machine-scoped guidance: its global
~/.codex/AGENTS.md.What
agents-usertarget →~/.codex/AGENTS.md, processed by bothsync(apply) andstatus(dry-run drift). Gated on the~/.codexdir existing — ak never creates it; codex-less machines see zero change. One-time.bakbefore the first managed rewrite, mirroring CLAUDE.md's.ruflo-dual-mode-referencere-scoped to['claude','agents-user']— machine-scoped content in machine-scoped files. The projectagentstarget remains for genuinely repo-scoped rows.retiredForTargetforced-strip rows), so projectAGENTS.mdfiles carrying the old block heal on their nextsync— no orphaned sentinels.guidanceTargets()helper replaces the duplicated target lists insync.mjs/status.mjs.memory-pinwarning, and the dual-run pre-flight refusal; MAINTAINER.md names the three targets; TROUBLESHOOTING/UPGRADING carry the new remedies. ADR-0008 records the scope-split decision.Verification
tests/kit/guidance-targets.test.mjs: dir-gating incl. never-mkdir, re-scope, project strip + idempotency, user-level upsert +.bak, no-empty-file/no-spurious-backup).pnpm run checkgreen; internal link check 0 errors.ak sync --dry-runon a dual-host machine shows exactly the intended plan: CLAUDE.md upsert + project AGENTS.md strip +~/.codex/AGENTS.mdupsert.After merge
The next
ak syncin this repo strips the dual-mode block from the checked-inAGENTS.md(committed in 371da30) — that strip will land as its own small follow-up commit.🤖 Generated with Claude Code