Status: accepted · ADR-12 · Filed 2026-04-17
Decision
ORG.md is introduced as a new file in the four-file boot chain, sitting at Ring 2.5 between PRISM.md (Ring 2 app methodology) and prism_start (Ring 3 live state). Its purpose is to carry organization-level overrides or additions to instructions established by prior files in the chain. Scope is ORG-LEVEL, not per-project — one ORG.md applies to every project in the org. Placement: one file at the org root, conventionally at $PROJECT_ROOT/ORG.md (alongside user projects). No per-project replica; org projects read the single org-wide file. For now ORG.md is a STUB — either an empty file or a file containing a single comment instructing the agent to ignore its contents. Override semantics (whether ORG.md can override BIOS, only app-layer, or is additive-only) are EXPLICITLY DEFERRED to a future philosophy session per Frank. See TODO #48 for the reminder.
Rationale
ORG.md fills a real gap in the ring architecture accepted in ADR #6. ADR #6 specifies Ring 1 (BIOS), Ring 2 (app methodology via PRISM.md), Ring 3 (live state via prism_start) and Ring 4 (server enforcement hooks). It does NOT address org-level instructions that apply across projects — a real need when a tenant has multiple projects that share org policy (e.g. “never commit to main on Fridays,” “all code reviews require Donna sign-off”). Without ORG.md these facts would have to be duplicated into every project’s PRISM.md, creating the exact drift surface we just fixed for CLAUDE.md. Placing ORG.md AFTER PRISM.md in the read order means it can respond to (override or augment) whatever PRISM.md established, giving orgs the ability to impose policy without modifying per-project methodology. Org-level scope (not per-project) enforces single-source-of-truth for org policy. Stub-for-now defers the override-power decision until we have real use cases driving it — Frank was explicit that this deserves a philosophy session rather than a guess.
Alternatives Considered
Skip ORG.md entirely — rejected, there is a real org-level gap ADR #6 doesn’t address. Put ORG.md BEFORE PRISM.md — rejected, defeats the “override” semantic since PRISM.md would then get the last word. Put ORG.md at Ring 1 as a peer of AGENTS.md — rejected, conflates org-level instructions with universal-agent principles; AGENTS.md applies to any agent anywhere, ORG.md applies only within one org. Per-project ORG.md — rejected, duplicates the drift problem we just solved; per-project instructions belong in PRISM.md. Resolve override semantics now — rejected per Frank, defer to philosophy session.
