Documentation Authority and Precedence
Status: Canonical (Draft) Last Updated: 2026-02-06 Owner: Engineering
Purpose
This document defines how documentation in the /docs directory is structured,
interpreted, and enforced.
It establishes:
- Which documents are authoritative
- How conflicts between documents are resolved
- How new documentation must be added
- How Codex and other AI coding agents are expected to use documentation
This document is itself authoritative and MUST be followed.
Scope
These rules apply to:
- All contributors (human and AI)
- All branches (dev, staging, production)
- All documentation under
/docs
No exception exists unless explicitly documented here.
Documentation Authority Order
When multiple documents describe overlapping behavior, the document with the higher authority level MUST take precedence.
Authority is defined strictly by directory, in the following order (highest to lowest):
/docs/governance//docs/contracts//docs/contracts/providers//docs/specs//docs/flows//docs/runbooks//docs/decisions//docs/testing//docs/prompts/
If a lower-authority document conflicts with a higher-authority document, the lower-authority document is considered incorrect and MUST be updated or removed.
Document Type Definitions
Governance Documents (/docs/governance/)
Define how documentation itself works.
Governance documents:
- Define authority and precedence
- Define naming and versioning rules
- Define documentation standards
Governance documents override all other documentation.
Contract Documents (/docs/contracts/)
Define system-wide invariants that MUST always hold.
Contracts:
- Define rules that MUST NOT be violated
- Are not feature-specific
- Apply across all specs and flows
Examples:
- Authorization rules
- RLS requirements
- Domain isolation rules
- Rate limiting and abuse rules
Contracts override:
- Specs
- Flows
- Runbooks
- Decisions
If a feature requires violating a contract, a new contract revision is required.
Provider Contracts (/docs/contracts/providers/)
Define pinned behavior of third-party services.
Provider contracts:
- Define expected request/response formats
- Define retry and failure semantics
- Define rate limits and constraints
Provider contracts override:
- Specs
- Flows
- Runbooks
Specifications (/docs/specs/)
Define what is being built.
Specifications:
- Describe feature or system behavior
- Reference applicable contracts
- Do not redefine contracts
If a specification conflicts with a contract, the contract wins.
User Flows (/docs/flows/)
Define how users experience a feature.
Flows:
- Describe page-by-page behavior
- Describe state transitions and UI behavior
- Must conform to specs and contracts
Flows do not define business rules.
Runbooks (/docs/runbooks/)
Define operational response procedures.
Runbooks:
- Describe what humans do during incidents
- Do not change system behavior
- Do not override specs or contracts
Decision Records (/docs/decisions/)
Document why decisions were made.
Decisions:
- Capture historical context
- Do not define current behavior
- Do not override any other document
Testing Artifacts (/docs/testing/)
Contain verification outputs.
Testing documents:
- Record test plans and results
- Validate behavior described elsewhere
- Do not define behavior
Prompt Documents (/docs/prompts/)
Contain reusable AI prompts.
Prompts:
- Assist execution
- Are never authoritative
- Must reference authoritative documents by path
Conflict Resolution Rules
- Higher-authority documents always win.
- Conflicts MUST be resolved in documentation, not in code comments.
- Silent deviation from documentation is not permitted.
- If documentation is ambiguous, implementation MUST halt until clarified.
File Naming Rules
The following naming conventions are mandatory:
- Specifications:
*.spec.md - User Flows:
*.flow.md - Decision Records:
adr-XXXX-*.md - Templates: prefixed with
template. - Draft placeholders: suffixed with
.new.md
Removing .new.md indicates the document is authoritative.
Change Management
- All changes to authoritative documents require review.
- Contract changes require explicit approval.
- Changes to governance documents require senior engineering approval.
AI Execution Rules
When Codex or other AI coding agents are used:
- Agents MUST read applicable documentation before implementation.
- Agents MUST follow documentation authority order.
- Agents MUST NOT invent behavior not described in specs or contracts.
- Agents MUST halt and report conflicts rather than guess.
Failure to follow these rules is considered an execution error.
Enforcement
Violation of this document constitutes a documentation breach.
Breaches MUST be corrected before implementation continues.
End of Document