53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# 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.
|