# Documentation governance checks (repair map)

**Audience:** agents and maintainers fixing **`pnpm run check`** failures in documentation / mirror / ledger gates. **Agents:** prefer this file over spelunking `docs/maintainers/` prose; maintainer depth stays in **`docs/maintainers/DOCUMENTATION-LIFECYCLE.md`**.

## Stages vs fixes (`scripts/run-check-stages.mjs`)

| Stage `id` | What it enforces | Primary repair |
| --- | --- | --- |
| `documentation-data` | `src/modules/documentation/data/*.json` validity; committed **`docs/maintainers/ROADMAP.md`** + **`FEATURE-TAXONOMY.md`** match deterministic renderers (needs `dist/` from `tsc`). | Fix JSON sources, then `pnpm run wk run generate-document '{"documentType":"ROADMAP.md"}'` / same for **`FEATURE-TAXONOMY.md`** as needed. |
| `doc-lifecycle-report` | Repo-root `*.md` allowlist vs **`CONTRIBUTING.md`**; **`documentation-ledger.v1.json`** shape + root Markdown set matches disk. | Remove stray root `*.md` or extend **`scripts/build-documentation-ledger.mjs`** + allowlist helpers; run **`pnpm run build:documentation-ledger`**. |
| `documentation-deletion-register` | **`docs/maintainers/data/documentation-deletion-register.v1.json`** rows match disk (deleted stays gone; archived lives under **`docs/maintainers/archive/`**). | Update the register when deleting/archiving paths; see **`scripts/documentation-deletion-register-helpers.mjs`**. |
| `ai-to-docs-drift` | Mirrored `.ai` → **`docs/maintainers`** outputs match generated bytes for covered paths. | Edit **`.ai`** sources, run **`pnpm run generate-maintainer-docs-from-ai`**, commit outputs. |
| `orphan-ai-sources` | Covered **`.ai/**/*.md`** trees list every file in **`docs/maintainers/data/ai-to-docs-coverage.json`**. | Add missing mappings (or move prose out of covered trees). |
| `orphan-instructions` | Every shipped **`src/modules/*/instructions/*.md`** is registered as a command surface. | Add/adjust module commands + manifest wiring per task-engine contracts. |

## Documentation module commands (when drift is view-backed)

- **`pnpm exec wk run document-project`** — batch regen for view models (see **`src/modules/documentation/instructions/document-project.md`**).
- **`pnpm exec wk run generate-document`** — single target (`README.md`, `TERMS.md`, …) per **`src/modules/documentation/instructions/generate-document.md`**.

## `.ai` → `docs/maintainers` mirror pipeline (Phase 56)

- Generator: **`pnpm run generate-maintainer-docs-from-ai`**
- Manifest / coverage: **`docs/maintainers/data/ai-to-docs-coverage.json`**
- ADR: **`docs/maintainers/adrs/ADR-ai-canonical-maintainer-docs-pipeline.md`** (human render; agents use machine routing + this runbook for repairs).

## Exception / coverage review cadence

- **Quarterly (or when Phase doc work lands):** skim **`ai-to-docs-coverage.json`** for stale `mappings` (paths that no longer exist) and for **new** `.md` files under covered `.ai/` subtrees that are not yet mapped.
- **Goal:** shrink exceptions over time — prefer adding a mapping + generated human stub over widening “ignored” trees.

## Related

- **`src/modules/documentation/RULES.md`** — module precedence + ledger/deletion register pointers.
- **`docs/maintainers/DOCUMENTATION-LIFECYCLE.md`** — maintainer lifecycle taxonomy + ledger/deletion register sections.
- **CI wiring guard:** **`scripts/check-doc-governance-stages.mjs`** asserts this runbook exists and core doc stages remain in **`run-check-stages.mjs`**.
