Status:
accepted · ADR-13 · Filed 2026-04-17Decision
The env-var path convention and SOR/replica pattern defined in ADR #11 for CLAUDE.md is extended to cover ALL FOUR files in the boot chain: CLAUDE.md (Ring 1 BIOS), AGENTS.md (Ring 1 BIOS), PRISM.md (Ring 2 app methodology), and ORG.md (Ring 2.5 override layer). All four files must derive paths from the two env vars PRISM_ROOT — no hardcoded absolute paths anywhere. CLAUDE.md and AGENTS.md are SOR + per-project replica (their replicas ship with each project). PRISM.md is SOR-template + per-project composed-replica (composed at bootstrap from prism-base.md + prism-<ptype>.md). ORG.md is SOR-only at $PROJECT_ROOT/ORG.md — one file org-wide, no per-project replica (the org is the scope). All replica-bearing files carry a version header (bios_version for CLAUDE.md/AGENTS.md, methodology_version for PRISM.md). The prism_sync_bios verb (originally scoped to CLAUDE.md) is generalized to sync any replica-bearing file. Drift detection runs on all of them at prism_start.
Rationale
ADR #11 solved the legacy-path problem for CLAUDE.md but the same problem exists for AGENTS.md and PRISM.md — both are read at session bootstrap and both can carry paths. Fixing only CLAUDE.md leaves AGENTS.md and PRISM.md as drift surfaces: the next time Frank moves machines or a new project ships, the same “hardcodedX:\DFW\DFWP” problem recurs. Frank was explicit: “all files need to be aware of Project Root and Prism Root or we are in the shitter. Mandatory.” ORG.md is newer (per ADR #12) but the same principle applies — no hardcoded paths. Generalizing the sync verb avoids N separate verbs for N files. Version headers must be consistent across files so the drift-detection logic in prism_start is one implementation, not four. ORG.md differs from the other three by having no replica because org-scope means one file, so the sync logic for ORG.md is “read from org root, no replica to maintain” — a degenerate case the general sync verb must handle.
Alternatives Considered
Scope the convention to CLAUDE.md only (ADR #11 as originally filed) — rejected, leaves AGENTS.md and PRISM.md as drift surfaces for the exact same failure mode. Use a different env var or path scheme for each file — rejected, multiplies the drift surface instead of collapsing it. Give each file its own sync verb (prism_sync_claude, prism_sync_agents, etc.) — rejected, same logic duplicated; prefer one verb with a files parameter. Skip version headers for PRISM.md because it is composed — rejected, composed files still need a version to detect when the component templates have moved on.