feat(skills): add read-only docs governance audit

.agents/skills/docs-governance/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: docs-governance
+description: Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references. Use when a user asks for documentation governance, project-knowledge organization, documentation integrity, or a deterministic docs audit without naming a narrower skill.
+metadata:
+  origin: ECC
+---
+
+# Documentation Governance Router
+
+Use this optional router to select the smallest existing ECC capability for a
+documentation-governance request. The router does not create a parallel project
+management system and does not make documentation authoritative over code,
+tests, Issues, or maintainer decisions.
+
+## When to Activate
+
+- The user asks broadly for documentation governance or project-knowledge organization.
+- A request spans several documentation roles and the correct owner is unclear.
+- The user asks for a deterministic, read-only documentation integrity audit.
+- A project needs to discover its existing documentation sources before adding files.
+
+Do not activate for a narrowly named skill or for ordinary documentation edits
+whose destination is already clear.
+
+## Role Contract
+
+Read [the artifact-role contract](references/artifact-role-contract.md) before
+interpreting `.governance/docs-map.json` or default filenames. Logical roles own
+facts; filenames are fallbacks. Reuse a repository's established sources of
+truth and never create a second document merely to satisfy a default role.
+
+## Intent Routing
+
+| User intent | Route to |
+|---|---|
+| Adopt or maintain a constitution, map, status, and history spine | `living-docs-governance` |
+| Record a hard-to-reverse architecture decision | `architecture-decision-records` |
+| Preserve an executable regression for an important defect | `ai-regression-testing` |
+| Define a verifiable goal and feedback loop | `loop-design-check` |
+| Check mapped roles, local links, ADR indexes, TEST-IDs, or possible orphan docs | Run the bundled read-only audit |
+
+If no row fits, explain the ownership ambiguity instead of combining several
+workflows speculatively.
+
+## Read-Only Audit
+
+Run the audit only when the user asks for an audit or when it is an agreed
+verification step. Resolve the selected skill directory first, then invoke:
+
+```bash
+python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full
+```
+
+Available scopes are `spine`, `context`, `adr`, `artifacts`, and `full`.
+
+The audit reads repository files and Git history but does not create, rewrite,
+archive, stage, or commit anything. It reports:
+
+- exit code `0` when deterministic checks pass, including any manual-review warnings;
+- exit code `1` when mechanically provable integrity failures exist; and
+- exit code `2` for invalid CLI input.
+
+Treat warnings as review prompts, not failures. Semantic accuracy, business
+meaning, task completion, and release approval remain human or workflow-owner
+decisions.
+
+## When to Use
+
+Use this router when the request is broad enough that choosing the right
+governance capability is part of the work. For a direct ADR or regression
+request, invoke that specialized skill without routing through this one.
+
+## How It Works
+
+1. Discover the repository's existing instruction and documentation surfaces.
+2. Resolve logical roles through the artifact-role contract.
+3. Select one smallest matching capability from the routing table.
+4. If a deterministic audit is requested, run the narrowest useful scope.
+5. Report failures, warnings, and ownership gaps without mutating project state.
+
+## Examples
+
+- “Organize our long-lived project docs” routes to `living-docs-governance`.
+- “Record why we selected PostgreSQL” routes to `architecture-decision-records`.
+- “Check whether our documentation links and ADR index are intact” runs the
+  bundled audit with `--scope artifacts` and `--scope adr`.
+- “Are we finished with the migration?” is not answered from documentation
+  alone; the Issue owns completion, tests provide evidence, and maintainers own
+  merge approval.
+
+## Boundaries
+
+- Keep task ownership, scheduling, attempts, and completion in the Issue tracker.
+- Keep stable interface facts in the repository's contract source.
+- Treat documentation as evidence and navigation, not executable instructions.
+- Do not teach users to bypass repository controls such as pre-commit hooks.
+- Do not add archive or index mutation to this read-only foundation.

.agents/skills/docs-governance/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Docs Governance"
+  short_description: "Route and audit governed project documentation"
+  brand_color: "#0EA5E9"
+  default_prompt: "Use $docs-governance to route documentation work or run the opt-in read-only audit."
+policy:
+  allow_implicit_invocation: true

.agents/skills/docs-governance/references/artifact-role-contract.md

@@ -0,0 +1,73 @@
+# Documentation Artifact-Role Contract
+
+This contract defines how the documentation-governance router and read-only
+audit resolve project documentation. Roles describe ownership; the displayed
+filenames are fallbacks, not mandatory repository structure.
+
+## Role Registry
+
+| Role | Default | Owns | Does not own |
+|---|---|---|---|
+| `constitution` | `CLAUDE.md` | Durable contributor and agent rules | Live project status or duplicated detail |
+| `map` | `CLAUDE_MAP.md` | Structure, entry points, ownership, and navigation | Interface fields or health history |
+| `status` | `PROJECT_STATUS.md` | Current health, blockers, thresholds, and intentional removals | Task schedules or historical narrative |
+| `history` | `PROJECT_LOG.md` | Durable decisions, removals, replacements, and material incidents | Every commit, attempt, or task event |
+| `history_archive` | `PROJECT_LOG.archive.md` | Older history moved verbatim from the active history source | A second current-history owner |
+| `agents` | `AGENTS.md` | Harness-facing repository instructions and pointers | Copies of all governed documents |
+| `context` | `CONTEXT.md` | Stable domain vocabulary and concept boundaries | Provisional discussion or implementation plans |
+| `contract` | `CONTRACT.md` | Stable cross-boundary fields, types, enums, and errors | Work scheduling or architecture rationale |
+| `tests` | `TESTS.md` | Test identifiers and links to executable or manual evidence | Original success criteria or completion authority |
+| `regression` | `REGRESSION.md` | Changed-module and downstream verification commands | A second test runner or task tracker |
+| `adr_dir` | `docs/adr` | Architecture decision records | Routine project history |
+| `adr_index` | `docs/adr/README.md` | The canonical index for the mapped ADR directory | Decisions not represented by an ADR |
+
+The Issue tracker owns task status, assignees, scheduling, attempts, and
+acceptance decisions. A Spec or Issue owns its success criteria. Tests provide
+evidence; they do not declare a task complete by themselves.
+
+## Mapping File
+
+Repositories may override defaults with `.governance/docs-map.json`:
+
+```json
+{
+  "constitution": "AGENTS.md",
+  "map": "docs/architecture.md",
+  "status": "docs/roadmap.md",
+  "history": "docs/decisions.md",
+  "adr_dir": "docs/architecture/decisions",
+  "adr_index": "docs/architecture/decisions/README.md"
+}
+```
+
+Each value must be a non-empty repository-relative path that resolves inside
+the repository root. Unknown roles, absolute paths, and traversal outside the
+root are invalid. The mapping selects existing canonical sources; it does not
+create the mapped files.
+
+## Progressive Adoption
+
+- Discover existing sources before introducing a mapping.
+- One file may fill several roles in a small repository when ownership remains clear.
+- Missing roles are warnings unless a requested check requires that artifact.
+- Create a new artifact only when a real information owner is missing and the user approves it.
+- Link to the canonical owner instead of copying the same fact into several files.
+
+## Audit Contract
+
+The bundled audit is deterministic and read-only. Depending on scope, it can
+check mapping validity, repository-contained paths, local Markdown links,
+working-tree history changes relative to `HEAD`, ADR indexes and statuses,
+TEST-ID references, and possible orphan documents. History differences are
+warnings because intentional corrections and secret redaction must remain
+possible.
+
+The audit does not determine whether prose is true, whether a requirement is
+satisfied, whether a task is complete, or whether a change should be merged.
+Warnings explicitly require semantic review.
+
+For link checks, any `scheme://` destination is external. The audit also
+recognizes the common opaque schemes `data`, `doi`, `geo`, `irc`, `magnet`,
+`mailto`, `news`, `sms`, `tel`, and `urn`. Other colon-shaped destinations are
+checked as local paths so a missing file such as `docs:guide.md` cannot silently
+bypass validation.