MR-12 — The CLAUDE.md is the projection, not the source
CLAUDE.md is what a fresh agent reads first. It is a projection of
content from docs/north-star/, MILESTONES.md, and the spec. It does
not introduce content not grounded elsewhere.
When something in CLAUDE.md would otherwise be the source of truth,
move it to its proper home (docs/spec/ for requirements,
docs/north-star/ for intent, MILESTONES.md for sequencing) and
have CLAUDE.md reference it.
The bootstrap-agent’s self-audit checks this. The drift-watcher
re-checks it on drift.suspected.
How these rules get enforced
Section titled “How these rules get enforced”- At commit time: the
.github/workflows/docs-invariants.ymlCI job validates the rank-graph DAG, ISO date formats, theAGENTS.xmlschema, and milestone-ID cross-references. - By subagents: every subagent’s
<refusal_conditions>enumerates which MR it would violate by proceeding. - By the orchestrator: the prompts in
prompts/reference MRs by number. When you pasteprompts/02-phase-close.md, the agent loads MR-2 and MR-10. - By you, the human: when something feels off, scan this file. The rule that’s being broken is almost always one of these twelve.
Updating these rules
Section titled “Updating these rules”These rules are meta — changing one is a bigger deal than changing a project invariant. To change one:
- Open a decision doc (
docs/decisions/YYYY-MM-DD-meta-rule-change-<slug>.md). - State the rule being changed, the proposed new wording, the trigger (what surfaced this), and the implications for in-flight work.
- Get explicit human approval (no agent self-modification of meta-rules).
- Update this file. Update any referencing prompts. Update the CI job if the change is mechanically enforceable.
- Bump the meta-rules version in this file’s header.
Meta-rules version: 1.0 (initial).
Return to the meta-rules index.