# DOC_RULES.md - Doc Compiler Contract
**Authority:** interface (doc compilation rules)
**Layer:** Interfaces
**Binding:** Yes
This document defines how markdown behaves as a machine interface in Decapod-managed repos.
If a rule is not declared here, it is not enforceable (claim: claim.doc.no_shadow_policy). If it is declared here, it is intended to become enforceable (via `decapod validate`).
---
## 1. Canonical Doc Header (Required)
Every canonical doc under `docs/` MUST include the following header fields (exact spelling):
- `**Canonical:** <repo-relative path>`
- `**Version:** vX.Y.Z`
- `**Authority:** <short role>`
- `**Layer:** Constitution | Interfaces | Guides`
- `**Binding:** Yes | No`
Optional but encouraged:
- `**Scope:** <what this doc is allowed to define>`
- `**Non-goals:** <what it must not define>`
---
## 2. Layers (Meaning)
### 2.1 Constitution (Binding)
Defines authority and behavior. Rarely edited. Short by design.
Allowed:
- authority hierarchy
- proof doctrine
- agent persona/interaction contract
- methodology contract (intent-first flow)
Forbidden:
- enumerating subsystem commands
- describing storage layouts in detail
- describing planned features as if implemented
### 2.2 Interfaces (Binding or Planned)
Defines machine surfaces: commands, schemas, store semantics, invariants, and safety gates.
Allowed:
- subsystem registry and truth labeling
- interface envelopes and schema surfaces
- store selection and purity model
- validate taxonomy and coverage matrix
Forbidden:
- tutorial prose that introduces new requirements (route to Guides instead)
### 2.3 Guides (Non-binding)
Operational guidance only. Guides may be verbose.
Allowed:
- suggested workflows
- examples and operator steps
Forbidden:
- new requirements (no "MUST", "NEVER", "REQUIRED")
Guides MUST include a disclaimer: if a guide conflicts with Constitution/Interfaces, the guide is wrong.
---
## 3. Links Footer (Graph Contract)
The canonical markdown dependency graph is defined exclusively by `## Links` footers.
Rules:
- Every canonical doc MUST have a `## Links` footer.
- Links SHOULD be repo-relative paths in backticks (e.g. `core/DECAPOD.md`).
- `core/DECAPOD.md` MUST reach every canonical doc via the `## Links` graph (reachability) (claim: claim.doc.decapod_reaches_all_canonical).
- Constitution hop constraint (intended invariant):
- Every Constitution doc with `**Binding:** Yes` SHOULD be linked directly from `core/DECAPOD.md` (no buried law).
- Interfaces hop constraint (intended invariant):
- Every Interfaces doc with `**Binding:** Yes` SHOULD be reachable from `core/DECAPOD.md` within 2 hops (directly or via a single router doc).
- `docs/DOC_MAP.md` is derived from this graph and MUST NOT be edited by hand.
---
## 4. Subsystem Truth (Single Source)
The only canonical place allowed to list subsystems and their statuses is:
- `core/PLUGINS.md` (Subsystem Registry)
Any other doc that needs to refer to subsystems MUST point to the registry instead of restating it.
---
## 5. Truth Labels (For Interfaces)
Any interface statement that looks like an API (commands, schemas, guarantees) MUST be tagged with one of:
- `REAL`: implemented and working now, with a named proof surface
- `STUB`: surface exists, behavior incomplete
- `SPEC`: intended interface; not implemented
- `IDEA`: exploratory; not a commitment
- `DEPRECATED`: do not use
Constraint:
- `REAL` requires a named proof surface.
- If no proof surface exists, the statement MUST be labeled `STUB` or `SPEC` instead.
- This is a claim: (claim: claim.doc.real_requires_proof).
Truth labels are required in:
- subsystem registry rows
- command lists (if present)
- schema descriptions (if present)
---
## 6. No Duplicate Authority
No requirement may be defined in multiple places (claim: claim.doc.no_duplicate_authority).
If two docs define the same requirement:
- Constitution wins
- Interfaces must defer (reference Constitution)
- Guides must delete or soften the statement (guidance only)
Meta-rule:
- If two canonical binding docs appear to disagree, the system is in an invalid state.
- Resolution is not interpretation; resolution is amendment (see `specs/AMENDMENTS.md`).
---
## 7. Claims Ledger (Promises Must Be Registered)
Any guarantee/invariant in a canonical doc MUST:
- include a claim-id (e.g. `(claim: claim.store.blank_slate)`) near the guarantee
- be registered in `interfaces/CLAIMS.md`
- declare its proof surface if labeled `REAL` (see §5)
If a guarantee is not registered, treat it as non-existent for enforcement purposes.
---
## 8. Decision Rights Matrix (Authority Routing, Not RACI)
This matrix defines which canonical doc owns which type of decision. If you need to change a decision, amend the owner doc (see `specs/AMENDMENTS.md`).
| Authority hierarchy, proof doctrine, contradiction handling | `specs/SYSTEM.md` |
| Change control for binding docs | `specs/AMENDMENTS.md` |
| Methodology contract (how agents should work) | `specs/INTENT.md` |
| Agent persona/interaction constraints | `methodology/SOUL.md` |
| Doc compilation rules, graph semantics, truth labels, claims registration | `interfaces/DOC_RULES.md` |
| Claims registry (what we promise + proof surfaces) | `interfaces/CLAIMS.md` |
| Store semantics and purity model | `interfaces/STORE_MODEL.md` |
| Subsystem existence/status/truth labels registry | `core/PLUGINS.md` |
| Control-plane sequencing patterns | `interfaces/CONTROL_PLANE.md` |
| Deprecation and migration contract | `core/DEPRECATION.md` |
| Loaded-term definitions | `interfaces/GLOSSARY.md` |
---
## Links
### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**
### Authority (Constitution Layer)
- `specs/INTENT.md` - **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` - System definition and authority doctrine
- `specs/AMENDMENTS.md` - Change control
### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index
- `core/DEPRECATION.md` - Deprecation contract
### Contracts (Interfaces Layer - This Document)
- `interfaces/CLAIMS.md` - Promises ledger
- `interfaces/STORE_MODEL.md` - Store semantics
- `interfaces/GLOSSARY.md` - Term definitions
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns
- `interfaces/TESTING.md` - Testing contract