Promote dev to main: requirements runtime module

docs/_data/nav.yml

@@ -55,6 +55,11 @@
         - title: Import & Migration
           url: /bundles/project/import-migration/
           expertise: [intermediate, advanced]
+    - name: Requirements
+      items:
+        - title: Overview
+          url: /bundles/requirements/overview/
+          expertise: [beginner, intermediate]
     - name: Codebase
       items:
         - title: Overview

docs/bundles/requirements/overview.md

@@ -0,0 +1,97 @@
+---
+layout: default
+title: Requirements bundle overview
+nav_order: 2
+permalink: /bundles/requirements/overview/
+keywords: [requirements, bundle, validation, evidence, coverage]
+audience: [solo, team, enterprise]
+expertise_level: [beginner, intermediate]
+---
+
+# Requirements bundle overview
+
+The **Requirements** bundle (`nold-ai/specfact-requirements`) imports existing
+requirement context into SpecFact validation evidence. It normalizes upstream
+records, stores them on project bundles as `requirements.inputs`, validates
+evidence usefulness by profile, and reports coverage. It does not replace your
+planning or product-management system.
+
+## Prerequisites
+
+- SpecFact CLI with core requirements context helpers
+- Bundle installed: `specfact module install nold-ai/specfact-requirements`
+- A project bundle directory, usually created by the [Project](/bundles/project/overview/) bundle
+- Local JSON or YAML requirement records with source attribution
+
+## Command surface
+
+After installation, `specfact requirements --help` lists the runtime command
+group.
+
+| Command | Purpose |
+|--------|---------|
+| `import` | Import local JSON/YAML requirement records into a project bundle |
+| `validate` | Validate attached requirement context against a profile |
+| `list` | List attached requirement records, optionally with coverage |
+| `coverage` | Print coverage counts for downstream evidence links |
+
+## Input shape
+
+Import accepts either a list of records or a mapping with a `requirements` list.
+Each record follows the core `RequirementInput` model and must include
+`schema_version`, `requirement_id`, `title`, and at least one source reference.
+
+```json
+{
+  "requirements": [
+    {
+      "schema_version": "1",
+      "requirement_id": "REQ-101",
+      "title": "Checkout requires fraud screening",
+      "sources": [
+        {
+          "source_type": "issue",
+          "locator": "https://github.com/example/shop/issues/101"
+        }
+      ],
+      "evidence_links": [
+        {
+          "link_type": "test",
+          "target": "tests/test_checkout_fraud.py"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Quick examples
+
+```bash
+specfact requirements import --from-file requirements.json --bundle .specfact/projects/shop --format json
+specfact requirements list --bundle .specfact/projects/shop --show-coverage --format json
+specfact requirements validate --bundle .specfact/projects/shop --profile enterprise --format json
+specfact requirements coverage --bundle .specfact/projects/shop --format json
+```
+
+## Storage
+
+The command runtime rehydrates the core `requirements.inputs` extension before
+delegating to validation helpers. Because current project bundle serialization
+does not persist arbitrary extensions directly, the module also writes
+`requirements.inputs.yaml` in the bundle root as the local persistence sidecar.
+
+## Scope boundaries
+
+The bundle is read-first and evidence-focused.
+
+- It imports and normalizes source-attributed requirement context.
+- It reports validation findings and coverage gaps.
+- It does not expose authoring templates.
+- It does not perform bidirectional backlog sync or ceremony automation.
+
+## See also
+
+- [Project bundle overview](/bundles/project/overview/)
+- [Backlog adapter patterns](/adapters/backlog-adapter-patterns/)
+- [ProjectBundle schema](/reference/projectbundle-schema/)

docs/index.md

@@ -69,6 +69,7 @@ The modules site owns all bundle-specific deep guidance. Core CLI platform docs
 |--------|----------|------------|
 | Backlog | [Overview](bundles/backlog/overview/) | [Refinement](bundles/backlog/refinement/), [Delta](bundles/backlog/delta/), [Policy Engine](bundles/backlog/policy-engine/), [Dependency Analysis](bundles/backlog/dependency-analysis/) |
 | Project | [Overview](bundles/project/overview/) | [DevOps Flow](bundles/project/devops-flow/), [Import & Migration](bundles/project/import-migration/) |
+| Requirements | [Overview](bundles/requirements/overview/) | Import, validate, list, coverage |
 | Codebase | [Overview](bundles/codebase/overview/) | [Sidecar Validation](bundles/codebase/sidecar-validation/), [Analyze](bundles/codebase/analyze/), [Drift](bundles/codebase/drift/), [Repro](bundles/codebase/repro/) |
 | Spec | [Overview](bundles/spec/overview/) | [Validate](bundles/spec/validate/), [Generate Tests](bundles/spec/generate-tests/), [Mock](bundles/spec/mock/) |
 | Govern | [Overview](bundles/govern/overview/) | [Enforce](bundles/govern/enforce/), [Patch](bundles/govern/patch/) |

docs/reference/commands.generated.json

@@ -1695,6 +1695,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-modules",
+    "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-modules",
+    "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-modules",
+    "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-modules",
+    "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-modules",
+    "short_help": "",
+    "source": "specfact_requirements.requirements.commands:app",
+    "subcommands": []
+  },
   {
     "arguments": [],
     "bare_invocation": "requires-subcommand",

docs/reference/commands.generated.md

@@ -93,6 +93,11 @@ This file is generated from the current module command trees. Do not edit by han
 | `specfact project version bump` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo, --type; args: - | - |  |
 | `specfact project version check` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo; args: - | - |  |
 | `specfact project version set` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo, --version; args: - | - |  |
+| `specfact requirements` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --install-completion, --show-completion; args: - | coverage, import, list, validate |  |
+| `specfact requirements coverage` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format; args: - | - |  |
+| `specfact requirements import` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --from-file; args: - | - |  |
+| `specfact requirements list` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --show-coverage; args: - | - |  |
+| `specfact requirements validate` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --profile; args: - | - |  |
 | `specfact spec` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | --install-completion, --show-completion; args: - | backward-compat, generate-tests, mock, validate |  |
 | `specfact spec backward-compat` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | -; args: - | - |  |
 | `specfact spec generate-tests` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | --bundle, --force, --out, --output; args: - | - |  |

llms.txt

@@ -97,6 +97,11 @@ This file is generated from the current module command trees. Do not edit by han
 | `specfact project version bump` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo, --type; args: - | - |  |
 | `specfact project version check` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo; args: - | - |  |
 | `specfact project version set` | nold-ai/specfact-project | `specfact module install nold-ai/specfact-project` | --bundle, --repo, --version; args: - | - |  |
+| `specfact requirements` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --install-completion, --show-completion; args: - | coverage, import, list, validate |  |
+| `specfact requirements coverage` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format; args: - | - |  |
+| `specfact requirements import` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --from-file; args: - | - |  |
+| `specfact requirements list` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --show-coverage; args: - | - |  |
+| `specfact requirements validate` | nold-ai/specfact-requirements | `specfact module install nold-ai/specfact-requirements` | --bundle, --format, --profile; args: - | - |  |
 | `specfact spec` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | --install-completion, --show-completion; args: - | backward-compat, generate-tests, mock, validate |  |
 | `specfact spec backward-compat` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | -; args: - | - |  |
 | `specfact spec generate-tests` | nold-ai/specfact-spec | `specfact module install nold-ai/specfact-spec` | --bundle, --force, --out, --output; args: - | - |  |

openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md

@@ -1,31 +1,64 @@
-# Change Validation: requirements-02-module-commands
+# Change Validation Report: requirements-02-module-commands
 
-- **Validated on (UTC):** 2026-02-15T21:54:26Z
-- **Workflow:** /wf-validate-change (proposal-stage dry-run validation)
+- **Validation Date (Europe/Berlin):** 2026-07-08T21:32:32+02:00
+- **Workflow:** OpenSpec validate-change refresh and implementation final gate
 - **Strict command:** `openspec validate requirements-02-module-commands --strict`
 - **Result:** PASS
 
 ## Scope Summary
 
-- **New capabilities:** requirements-module
-- **Modified capabilities:** module-io-contract,backlog-adapter
-- **Declared dependencies:** requirements-01 (data model), arch-07 (#213, schema extensions for ProjectBundle)
-- **Proposed affected code paths:** - `modules/requirements/` (new module);- `modules/backlog/src/adapters/` (extend adapters with AC text extraction interface) - `src/specfact_cli/contracts/module_interface.py` (no change — new implementation)
+- **New capabilities:** requirements-validation-runtime
+- **Modified capabilities:** module-io-contract, backlog-adapter
+- **Declared dependencies:** core requirements input model and core
+  requirements context helpers from `nold-ai/specfact-cli#239`
+- **Proposed affected code paths:**
+  - `packages/specfact-requirements/`
+  - `tests/unit/specfact_requirements/`
+  - `tests/integration/specfact_requirements/`
+  - `docs/bundles/requirements/`
+  - `docs/reference/commands.generated.*`
+  - `llms.txt`
+  - `scripts/check-bundle-imports.py`
+  - `scripts/generate-command-overview.py`
 
-## Breaking-Change Analysis (Dry-Run)
+## Breaking-Change Analysis
 
-- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage.
-- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time.
-- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage.
+- The change adds a new module bundle and grouped command surface.
+- Existing bundles and registry entries remain backward compatible.
+- ProjectBundle integration remains optional through the existing
+  `requirements.inputs` extension namespace.
+- No existing runtime command signature is changed.
 
 ## Dependency and Integration Review
 
-- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing.
-- Cross-change integration points are explicitly represented in proposal/spec/task artifacts.
-- No additional mandatory scope expansion was required to pass strict OpenSpec validation.
+- Core `requirements-01-data-model` is implemented and archived.
+- Core `requirements-02-module-commands` (#239) is paired parallel work and
+  exposes the helpers this module consumes.
+- GitHub issue #165 was verified as open and not `in progress` through the
+  GitHub connector on 2026-07-08.
+- The hierarchy cache refresh command succeeded with approved network access on
+  2026-07-08T21:05:31+02:00.
+- The connector does not expose GitHub project parent fields; the refreshed
+  local hierarchy cache remains the available structure evidence.
 
 ## Validation Outcome
 
-- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`.
-- Strict OpenSpec validation passed.
-- Change is ready for implementation-phase intake once prerequisites are satisfied.
+- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`,
+  `tasks.md`.
+- Strict OpenSpec validation passed after implementation.
+- Targeted failing-first test evidence was captured before the module package
+  existed, then passed after implementation.
+- Final quality gates passed:
+  - `hatch run format`
+  - `hatch run type-check`
+  - `hatch run lint`
+  - `hatch run yaml-lint`
+  - `hatch run check-bundle-imports`
+  - `hatch run check-command-overview`
+  - `hatch run check-command-contract`
+  - `hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump --public-key-file resources/keys/module-signing-public.pem`
+  - `hatch run contract-test`
+  - `hatch run smart-test` (`849 passed, 2 warnings`)
+  - `hatch run test` (`849 passed, 2 warnings`)
+  - `hatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json`
+- SpecFact code review result: `PASS`, score `115`, `0` findings.

openspec/changes/requirements-02-module-commands/TDD_EVIDENCE.md

@@ -0,0 +1,41 @@
+# TDD Evidence: requirements-02-module-commands
+
+## Failing-before
+
+- **Timestamp (Europe/Berlin):** 2026-07-08T21:28:00+02:00
+- **Command:** `hatch run pytest tests/unit/specfact_requirements/test_requirements_runtime.py tests/integration/specfact_requirements/test_command_apps.py -q`
+- **Result:** FAIL, expected
+- **Summary:** Pytest failed during collection because the new requirements
+  runtime module did not exist yet.
+- **Key error:** `ModuleNotFoundError: No module named 'specfact_requirements'`
+
+## Passing-after
+
+- **Timestamp (Europe/Berlin):** 2026-07-08T21:43:00+02:00
+- **Command:** `hatch run pytest tests/unit/specfact_requirements/test_requirements_runtime.py tests/integration/specfact_requirements/test_command_apps.py -q`
+- **Result:** PASS
+- **Summary:** 6 targeted tests passed, covering file import, bounded
+  diagnostics, sidecar-backed bundle persistence, profile-aware validation,
+  JSON command output, coverage inspection, and absence of an authoring command.
+
+## Quality Gates
+
+- **Timestamp (Europe/Berlin):** 2026-07-08T21:32:32+02:00
+- **Result:** PASS
+- **Commands:**
+  - `openspec validate requirements-02-module-commands --strict`
+  - `hatch run format`
+  - `hatch run type-check`
+  - `hatch run lint`
+  - `hatch run yaml-lint`
+  - `hatch run check-bundle-imports`
+  - `hatch run check-command-overview`
+  - `hatch run check-command-contract`
+  - `hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump --public-key-file resources/keys/module-signing-public.pem`
+  - `hatch run contract-test`
+  - `hatch run smart-test`
+  - `hatch run test`
+  - `hatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json`
+- **Summary:** targeted and full gates passed after the requirements runtime
+  cleanup. `smart-test` and `test` both reported `849 passed, 2 warnings`.
+  SpecFact code review reported `PASS`, score `115`, and no findings.