# Documentation Authority Policy

`docs/authority.toml` classifies every root README, repository documentation page, and Cursor plan
before it may be used as guidance. Run `python scripts/codex/docs_audit.py` after changing behavior,
schemas, commands, component names, workflows, plans, or evidence records.

## Authority order

For desired scope and acceptance, use the latest user direction, exact current Gitea scope, and then
an active plan. For implemented behavior, use source and tests, then current native evidence and
canonical current documentation. Accepted ADRs own architecture decisions. Do not merge conflicting
sources silently; report and reconcile the conflict at the smallest owning surface.

## Classifications

Each authority rule has a lifecycle classification and a role. Lifecycle controls whether a page
may guide current work; roles distinguish overview, canonical behavior, architecture, active plan,
evidence, historical record, and superseded record. Accepted ADRs use the architecture role and are
authoritative only for their surviving decision scope.

| Class | Meaning | May define current behavior? |
|-------|---------|------------------------------|
| `current` | Canonical workflow, architecture, intent, or user guidance | Yes, within its stated role |
| `active-plan` | Unaccepted desired scope and acceptance work | No; source and current docs describe what exists |
| `evidence` | Dated automated or native observations | No |
| `historical` | Preserved context from completed work | No |
| `superseded` | Replaced contract retained for provenance | No |

Historical and superseded documents carry an obvious banner linking current guidance. Evidence
records carry an evidence-only banner. Active plans identify themselves and must become historical
when their acceptance target is complete.

## One home per fact

- Root `README.md`: user commands, controls, troubleshooting, and shipped checklist.
- `docs/mission.md`: product intent and non-goals.
- `docs/adr/`: accepted decisions and durable constraints.
- `docs/editor/`: current editor workflows and subsystem contracts.
- `.cursor/plans/`: active or historical implementation roadmaps, never implementation truth.
- `docs/editor/evaluations/`: dated evidence, never product requirements.
- `docs/archive/`: preserved records that no longer belong in a live topic tree.

Update canonical documentation when behavior stabilizes at a slice boundary. Tiny intermediate edits
do not require repeated narrative churn, but the slice cannot become engineering-complete while its
canonical docs contradict the implementation.

## Audit contract

The audit discovers `README.md`, every `docs/**/*.md`, and every `.cursor/plans/**/*.md`. The
highest-priority matching authority rule wins; equal-priority disagreement fails. It also verifies
lifecycle banners and configured replacement links. New documents fail until a deterministic rule
classifies them.