---
name: blacksite-doc-integrity
description: Prevent stale or contradictory Blacksite documentation from becoming design context by enforcing documentation authority, archiving superseded plans, comparing changed behavior with canonical docs and accepted ADRs, and running the documentation audit.
---

# Blacksite documentation integrity

Read `.codex/workflow.toml`, `docs/authority.toml`, and [the authority reference](references/documentation-authority.md) before treating repository prose as design guidance.

Trigger this Skill for user-visible behavior, schema/command/component renames, architectural changes, candidate preparation, documentation requests, or discovered contradictions.

1. Identify the changed public behavior from code and focused tests.
2. Load only the canonical docs for its topic and relevant accepted ADRs.
3. Read the exact Gitea acceptance criteria when tracked.
4. Search historical material only for contradictions, never as authority.
5. Write a bounded `.codex/session/doc-contradictions.md` listing claim, source, current truth, and action.
6. Update the smallest canonical owner at the stable slice boundary, within the same task.
7. Mark completed plans historical and freeze their substantive contents. Add required banners and replacement links.
8. Run `python scripts/codex/docs_audit.py --changed`, then the full audit at a documentation slice gate.

Keep README as an overview. Do not duplicate detailed contracts across guides, plans, ADRs, and tracker bodies. Coordinate a dry-run Gitea scope/status update when tracker truth has drifted.
