Blacksite/docs/workflow/documentation-policy.md

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.