fix(docs): enforce module accountability

.github/workflows/docs-review.yml

@@ -21,6 +21,7 @@ on:
       - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
       - "scripts/check-command-contract.py"
+      - "scripts/check-documentation-accountability.py"
       - "scripts/generate-command-overview.py"
       - "docs/reference/commands.generated.*"
       - "llms.txt"
@@ -49,6 +50,7 @@ on:
       - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
       - "scripts/check-command-contract.py"
+      - "scripts/check-documentation-accountability.py"
       - "scripts/generate-command-overview.py"
       - "docs/reference/commands.generated.*"
       - "llms.txt"
@@ -121,6 +123,9 @@ jobs:
       - name: Validate generated command contract
         run: hatch run check-command-contract
 
+      - name: Validate documentation accountability
+        run: hatch run check-documentation-accountability
+
       - name: Cross-site links (warn-only; live site may lag deploys)
         continue-on-error: true
         run: hatch run check-cross-site-links --warn-only

CHANGELOG.md

@@ -10,6 +10,18 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.51.2] - 2026-07-10
+
+### Fixed
+
+- **Documentation accountability**: derive the official module inventory from
+  signed module manifests and the marketplace registry, then fail local
+  pre-commit and PR documentation validation when core catalogues, generated
+  command records, or core/modules ownership statements drift. The repaired
+  catalogues now cover the installed requirements and code-review modules.
+
+---
+
 ## [0.51.1] - 2026-07-10
 
 ### Fixed

README.md

@@ -72,6 +72,11 @@ For cleanup work, run a JSON review, inspect the cleanup forecast and AI-bloat i
 
 These findings are bloat-shape detection and cleanup guidance, not AI-authorship detection. Exact simplify flags and report fields live in the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) and [Code Review run guide](https://modules.specfact.io/bundles/code-review/run/) on the modules docs site.
 
+Official workflow package IDs are `nold-ai/specfact-project`,
+`nold-ai/specfact-backlog`, `nold-ai/specfact-codebase`,
+`nold-ai/specfact-code-review`, `nold-ai/specfact-spec`,
+`nold-ai/specfact-govern`, and `nold-ai/specfact-requirements`.
+
 ## What SpecFact does
 
 - **Defends against AI bloat deterministically** — forecast cleanup impact and route remediation packets to your AI IDE
@@ -163,6 +168,7 @@ specfact module install nold-ai/specfact-backlog
 specfact module install nold-ai/specfact-codebase
 specfact module install nold-ai/specfact-code-review
 specfact module install nold-ai/specfact-govern
+specfact module install nold-ai/specfact-spec
 specfact module install nold-ai/specfact-requirements
 ```
 

docs/.doc-frontmatter-enforced

@@ -6,4 +6,11 @@ docs/core-cli/init.md
 docs/reference/documentation-url-contract.md
 docs/contributing/docs-sync.md
 docs/contributing/frontmatter-schema.md
+docs/module-system/marketplace.md
+docs/reference/commands.md
+docs/reference/module-categories.md
+docs/reference/directory-structure.md
+docs/getting-started/installation.md
+docs/architecture/overview.md
+docs/architecture/implementation-status.md
 docs/agent-rules/*.md

docs/architecture/implementation-status.md

@@ -6,6 +6,11 @@ description: Implemented vs planned architecture capabilities.
 keywords: [implementation status, roadmap, architecture]
 audience: [team, enterprise]
 expertise_level: [advanced]
+doc_owner: specfact-cli
+tracks: [src/specfact_cli/**, openspec/**, ../specfact-cli-modules/packages/**]
+last_reviewed: 2026-07-10
+exempt: false
+exempt_reason: ""
 ---
 
 # Architecture Implementation Status
@@ -23,7 +28,8 @@ This page tracks implemented vs planned architecture capabilities.
 
 - Shared architecture and traceability contracts remain planned in OpenSpec.
   - Source: `architecture-01-solution-layer`, `traceability-01-index-and-orphans`, and related follow-up changes.
-- Older flat command families such as `specfact architecture ...`, `specfact requirements ...`, and `specfact trace ...` are not canonical delivery targets.
+- Older flat core command families such as `specfact architecture ...` and `specfact trace ...` are not canonical delivery targets. `specfact requirements ...` is instead an installed grouped surface owned by `nold-ai/specfact-requirements`.
+- Canonical bundle-deep documentation is owned by the [modules documentation site](https://modules.specfact.io/).
   - Any future runtime implementation must be rescoped into grouped bundle-owned surfaces in `specfact-cli-modules`; core retains only shared models, schemas, and integration contracts.
 - Protocol FSM runtime engine is partial (models/specs exist; full execution engine/guards are planned).
   - Source: OpenSpec `architecture-01-solution-layer` and dependent validation changes.

docs/architecture/overview.md

@@ -7,6 +7,11 @@ redirect_from:
 keywords: [architecture, module system, runtime, registry]
 audience: [team, enterprise]
 expertise_level: [intermediate, advanced]
+doc_owner: specfact-cli
+tracks: [src/specfact_cli/registry/**, src/specfact_cli/modules/**, ../specfact-cli-modules/packages/**]
+last_reviewed: 2026-07-10
+exempt: false
+exempt_reason: ""
 ---
 
 # Architecture
@@ -16,8 +21,9 @@ SpecFact CLI is a contract-first Python CLI with a production-ready module regis
 ## Current Architecture Status
 
 - Module system is **production-ready** (introduced in `v0.27`) and is the default command-loading path.
-- Older flat command concepts such as `specfact architecture ...`, `specfact requirements ...`, and `specfact trace ...` are **not** part of the canonical current CLI surface.
+- Older flat core command concepts such as `specfact architecture ...` and `specfact trace ...` are **not** part of the canonical current CLI surface. The installed `nold-ai/specfact-requirements` bundle owns the canonical grouped `specfact requirements ...` surface.
 - The related OpenSpec changes now follow a split/rescope model: core owns schemas, contracts, and integration boundaries, while any future user-facing runtime delivery must land under canonical grouped bundle commands in `specfact-cli-modules`.
+- Canonical bundle-deep documentation is owned by the [modules documentation site](https://modules.specfact.io/).
 - Protocol FSM modeling exists in data models; a full runtime FSM engine is still planned.
 
 ## Layer Model

docs/contributing/docs-sync.md

@@ -10,7 +10,7 @@ doc_owner: specfact-cli
 tracks:
   - scripts/check_doc_frontmatter.py
   - docs/**
-last_reviewed: 2026-03-29
+last_reviewed: 2026-07-10
 exempt: false
 exempt_reason: ""
 ---
@@ -50,6 +50,12 @@ Docs-only PRs rely on the dedicated `Docs Review` workflow as the required docum
 cross-site link check remains advisory because the published site can lag deployment, while
 frontmatter validation and docs test suites remain merge-blocking for docs-owned changes.
 
+`hatch run check-documentation-accountability` is also blocking locally and in
+PR CI. It reads the official module inventory from a local
+`specfact-cli-modules` checkout (or `SPECFACT_MODULES_REPO`) and verifies that
+core catalogues, generated command artifacts, and ownership statements agree.
+It fails closed when that source is unavailable or inconsistent.
+
 ## Troubleshooting
 
 - **Missing `doc_owner`**: add the field and a sensible `tracks` list for the code or specs this page describes.

docs/getting-started/installation.md

@@ -5,6 +5,11 @@ permalink: /getting-started/installation/
 keywords: [install, setup, bootstrap, cli]
 audience: [solo, team]
 expertise_level: [beginner]
+doc_owner: specfact-cli
+tracks: [src/specfact_cli/modules/init/**, src/specfact_cli/registry/**, ../specfact-cli-modules/packages/**]
+last_reviewed: 2026-07-10
+exempt: false
+exempt_reason: ""
 ---
 
 # Getting Started with SpecFact CLI
@@ -210,6 +215,12 @@ Category groups appear after bundle installation:
 - `specfact code ...`
 - `specfact spec ...`
 - `specfact govern ...`
+- `specfact requirements ...` (after installing `nold-ai/specfact-requirements`)
+
+Official workflow package IDs are `nold-ai/specfact-project`,
+`nold-ai/specfact-backlog`, `nold-ai/specfact-codebase`,
+`nold-ai/specfact-code-review`, `nold-ai/specfact-spec`,
+`nold-ai/specfact-govern`, and `nold-ai/specfact-requirements`.
 
 Backlog authentication commands such as `specfact backlog auth ...` are provided by the
 installed backlog bundle, not by the permanent core command surface.
@@ -225,7 +236,11 @@ Legacy workflow presets remain available for bundle-first bootstrap:
 | `solo-developer` | `specfact-codebase`, `specfact-code-review` | `code` |
 | `backlog-team` | `specfact-project`, `specfact-backlog`, `specfact-codebase` | `project`, `backlog`, `code` |
 | `api-first-team` | `specfact-spec`, `specfact-codebase` (+`specfact-project` dependency) | `project`, `code`, `spec` |
-| `enterprise-full-stack` | all five bundles | `project`, `backlog`, `code`, `spec`, `govern` |
+| `enterprise-full-stack` | five profile-selected bundles | `project`, `backlog`, `code`, `spec`, `govern` |
+
+`nold-ai/specfact-requirements` is an official, opt-in evidence module rather
+than a current profile default. Install it with `specfact init --install requirements`;
+it adds `specfact requirements ...`.
 
 ### Upgrading from Pre-Slimming Versions
 

docs/module-system/marketplace.md

@@ -9,6 +9,11 @@ description: Official SpecFact bundle IDs, trust tiers, and bundle dependency be
 keywords: [bundles, official modules, trust tiers]
 audience: [solo, team, enterprise]
 expertise_level: [intermediate]
+doc_owner: specfact-cli
+tracks: [src/specfact_cli/registry/**, ../specfact-cli-modules/packages/**, ../specfact-cli-modules/registry/index.json]
+last_reviewed: 2026-07-10
+exempt: false
+exempt_reason: ""
 ---
 
 # Marketplace Bundles
@@ -28,6 +33,7 @@ Install commands:
 specfact module install nold-ai/specfact-project
 specfact module install nold-ai/specfact-backlog
 specfact module install nold-ai/specfact-codebase
+specfact module install nold-ai/specfact-code-review
 specfact module install nold-ai/specfact-spec
 specfact module install nold-ai/specfact-govern
 specfact module install nold-ai/specfact-requirements
@@ -38,6 +44,7 @@ Bundle overview:
 - `nold-ai/specfact-project`: grouped project workflows (`project`, `plan`, `import`, `sync`, `migrate`)
 - `nold-ai/specfact-backlog`: grouped backlog workflows (`backlog`, `policy`, `backlog auth`)
 - `nold-ai/specfact-codebase`: grouped code workflows (`analyze`, `drift`, `validate`, `repro`)
+- `nold-ai/specfact-code-review`: scored clean-code and AI-bloat review workflows (`code review`)
 - `nold-ai/specfact-spec`: grouped spec workflows (`contract`, `api`, `sdd`, `generate`)
 - `nold-ai/specfact-govern`: grouped governance workflows (`enforce`, `patch`)
 - `nold-ai/specfact-requirements`: grouped requirements evidence workflows (`requirements`)

docs/reference/commands.generated.json

@@ -30,6 +30,7 @@
       "init",
       "module",
       "project",
+      "requirements",
       "spec",
       "upgrade"
     ]
@@ -2068,6 +2069,99 @@
     "source": "specfact_project.project.commands:app",
     "subcommands": []
   },
+  {
+    "arguments": [],
+    "bare_invocation": "requires-subcommand",
+    "command": "specfact requirements",
+    "deprecated": false,
+    "hidden": false,
+    "install_prerequisite": "specfact module install nold-ai/specfact-requirements",
+    "options": [
+      "--install-completion",
+      "--show-completion"
+    ],
+    "owner_package": "nold-ai/specfact-requirements",
+    "owner_repo": "nold-ai/specfact-cli",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": [
+      "coverage",
+      "import",
+      "list",
+      "validate"
+    ]
+  },
+  {
+    "arguments": [],
+    "bare_invocation": "executes",
+    "command": "specfact requirements coverage",
+    "deprecated": false,
+    "hidden": false,
+    "install_prerequisite": "specfact module install nold-ai/specfact-requirements",
+    "options": [
+      "--bundle",
+      "--format"
+    ],
+    "owner_package": "nold-ai/specfact-requirements",
+    "owner_repo": "nold-ai/specfact-cli",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": []
+  },
+  {
+    "arguments": [],
+    "bare_invocation": "executes",
+    "command": "specfact requirements import",
+    "deprecated": false,
+    "hidden": false,
+    "install_prerequisite": "specfact module install nold-ai/specfact-requirements",
+    "options": [
+      "--bundle",
+      "--format",
+      "--from-file"
+    ],
+    "owner_package": "nold-ai/specfact-requirements",
+    "owner_repo": "nold-ai/specfact-cli",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": []
+  },
+  {
+    "arguments": [],
+    "bare_invocation": "executes",
+    "command": "specfact requirements list",
+    "deprecated": false,
+    "hidden": false,
+    "install_prerequisite": "specfact module install nold-ai/specfact-requirements",
+    "options": [
+      "--bundle",
+      "--format",
+      "--show-coverage"
+    ],
+    "owner_package": "nold-ai/specfact-requirements",
+    "owner_repo": "nold-ai/specfact-cli",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": []
+  },
+  {
+    "arguments": [],
+    "bare_invocation": "executes",
+    "command": "specfact requirements validate",
+    "deprecated": false,
+    "hidden": false,
+    "install_prerequisite": "specfact module install nold-ai/specfact-requirements",
+    "options": [
+      "--bundle",
+      "--format",
+      "--profile"
+    ],
+    "owner_package": "nold-ai/specfact-requirements",
+    "owner_repo": "nold-ai/specfact-cli",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": []
+  },
   {
     "arguments": [],
     "bare_invocation": "requires-subcommand",

docs/reference/commands.generated.md

@@ -12,7 +12,7 @@ This file is generated from the current CLI command tree. Do not edit by hand.
 
 | Command | Owner | Options | Subcommands | Context |
 | --- | --- | --- | --- | --- |
-| `specfact` | core | --banner, --debug, --input-format, --install-completion, --interactive, --mode, --no-interactive, --output-format, --show-completion, --skip-checks, --version; args: - | backlog, code, govern, init, module, project, spec, upgrade |  |
+| `specfact` | core | --banner, --debug, --input-format, --install-completion, --interactive, --mode, --no-interactive, --output-format, --show-completion, --skip-checks, --version; args: - | backlog, code, govern, init, module, project, requirements, spec, upgrade |  |
 | `specfact backlog` | nold-ai/specfact-backlog | --install-completion, --show-completion; args: - | add, analyze-deps, auth, ceremony, daily, delta, diff, init-config, map-fields, promote, refine, sync, verify-readiness |  |
 | `specfact backlog add` | nold-ai/specfact-backlog | --acceptance-criteria, --adapter, --body, --body-end-marker, --business-value, --check-dor, --custom-config, --description-format, --non-interactive, --parent, --priority, --project-id, --provider-field, --repo-path, --sprint, --story-points, --template, --title, --type; args: - | - |  |
 | `specfact backlog analyze-deps` | nold-ai/specfact-backlog | --adapter, --custom-config, --json-export, --output, --project-id, --template; args: - | - |  |
@@ -113,6 +113,11 @@ This file is generated from the current CLI command tree. Do not edit by hand.
 | `specfact project version bump` | nold-ai/specfact-project | --bundle, --repo, --type; args: - | - |  |
 | `specfact project version check` | nold-ai/specfact-project | --bundle, --repo; args: - | - |  |
 | `specfact project version set` | nold-ai/specfact-project | --bundle, --repo, --version; args: - | - |  |
+| `specfact requirements` | nold-ai/specfact-requirements | --install-completion, --show-completion; args: - | coverage, import, list, validate |  |
+| `specfact requirements coverage` | nold-ai/specfact-requirements | --bundle, --format; args: - | - |  |
+| `specfact requirements import` | nold-ai/specfact-requirements | --bundle, --format, --from-file; args: - | - |  |
+| `specfact requirements list` | nold-ai/specfact-requirements | --bundle, --format, --show-coverage; args: - | - |  |
+| `specfact requirements validate` | nold-ai/specfact-requirements | --bundle, --format, --profile; args: - | - |  |
 | `specfact spec` | nold-ai/specfact-spec | --install-completion, --show-completion; args: - | backward-compat, generate-tests, mock, validate |  |
 | `specfact spec backward-compat` | nold-ai/specfact-spec | -; args: - | - |  |
 | `specfact spec generate-tests` | nold-ai/specfact-spec | --bundle, --force, --out, --output; args: - | - |  |

docs/reference/commands.md

@@ -5,6 +5,11 @@ permalink: /reference/commands/
 keywords: [command reference, cli surface, command groups]
 audience: [solo, team, enterprise]
 expertise_level: [intermediate, advanced]
+doc_owner: specfact-cli
+tracks: [scripts/generate-command-overview.py, scripts/check-command-contract.py, ../specfact-cli-modules/packages/**]
+last_reviewed: 2026-07-10
+exempt: false
+exempt_reason: ""
 ---
 
 # Command Reference
@@ -23,6 +28,7 @@ The live root command surface includes:
 - `specfact code ...`
 - `specfact govern ...`
 - `specfact project ...`
+- `specfact requirements ...` (when `nold-ai/specfact-requirements` is installed)
 - `specfact spec ...`
 
 Use `specfact init --profile <name>` or `specfact init --install <comma-list>` to bootstrap the workflow bundles you need.
@@ -114,6 +120,13 @@ Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ..
 - `code validate`
 - `code repro`
 
+### `specfact requirements` (optional module)
+
+- `requirements import`
+- `requirements list`
+- `requirements coverage`
+- `requirements validate`
+
 ### `specfact spec`
 
 - `spec validate`
@@ -132,7 +145,8 @@ Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ..
 |---|---|---|
 | `nold-ai/specfact-project` | `project` | `project link-backlog`, `project health-check`, `project devops-flow`, `project snapshot`, `project regenerate`, `project export-roadmap`, `project import`, `project export`, `project sync`, `project version` |
 | `nold-ai/specfact-backlog` | `backlog` | `backlog ceremony`, `backlog refine`, `backlog daily`, `backlog sync`, `backlog auth`, `backlog analyze-deps`, `backlog verify-readiness`, `backlog delta`, `backlog add`, `backlog map-fields` |
-| `nold-ai/specfact-codebase` | `code` | `code analyze`, `code drift`, `code validate`, `code repro`, `code import`, `code review` |
+| `nold-ai/specfact-codebase` | `code` | `code analyze`, `code drift`, `code validate`, `code repro`, `code import` |
+| `nold-ai/specfact-code-review` | `code review` | `code review run`, `code review rules`, `code review ledger` |
 | `nold-ai/specfact-spec` | `spec` | `spec validate`, `spec backward-compat`, `spec generate-tests`, `spec mock` |
 | `nold-ai/specfact-govern` | `govern` | `govern enforce`, `govern patch` |
 | `nold-ai/specfact-requirements` | `requirements` | `requirements import`, `requirements list`, `requirements coverage`, `requirements validate` |