nold-ai · djm81 · Jul 8, 2026 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,27 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.50.1] - 2026-07-08
+
+### Fixed
+
+- **Release review follow-up**: persist bundle extension payloads through
+  directory save/load round trips so attached requirements evidence survives
+  reload, and make the requirements context adapter protocol stub type-check
+  cleanly.
+
+---
+
+## [0.50.0] - 2026-07-08
+
+### Added
+
+- **Requirements context adapter**: add core helpers for importing,
+  normalizing, validating, and inspecting source-attributed requirement context
+  as validation evidence for the future `requirements` runtime command group.
+
+---
+
 ## [0.49.1] - 2026-07-08
 
 ### Fixed

diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml
@@ -174,6 +174,9 @@
     - title: Requirements Evidence Input Model
       url: /reference/requirements-evidence-input-model/
       expertise: [advanced]
+    - title: Requirements Context Adapter
+      url: /reference/requirements-context-adapter/
+      expertise: [advanced]
     - title: Dependency Resolution
       url: /reference/dependency-resolution/
       expertise: [advanced]

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -11,7 +11,9 @@ expertise_level: [beginner]
 
 This guide will help you get started with SpecFact CLI in under 60 seconds — first with **no install** (uvx), then with a **persistent** install (pip) when you want IDE workflows and a stable `specfact` command.
 
-> **Primary use case**: brownfield code modernization — reverse-engineering existing codebases into documented specs with runtime contract enforcement. See the [5-Minute Quickstart](quickstart.md) for a full walkthrough.
+> **Primary use case**: validation evidence and AI-bloat defense for AI-assisted and brownfield Python delivery —
+> deterministic review, drift detection, and spec/contract evidence before code reaches PR.
+> See the [5-Minute Quickstart](quickstart.md) for a full walkthrough.
 
 ## Try it now — no install required
 

diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md
@@ -7,7 +7,7 @@ permalink: /getting-started/tutorial-openspec-speckit/
 # Tutorial: Using SpecFact with OpenSpec or Spec-Kit
 
 > **Complete step-by-step guide for new users**  
-> Learn how to use SpecFact CLI with OpenSpec or Spec-Kit for brownfield code modernization
+> Learn how to use SpecFact CLI with OpenSpec or Spec-Kit to validate existing codebases and keep specs, contracts, and code in sync
 
 **Time**: 15-30 minutes | **Prerequisites**: Python 3.11+, basic command-line knowledge
 

diff --git a/docs/guides/integrations-overview.md b/docs/guides/integrations-overview.md
@@ -50,7 +50,8 @@ SpecFact CLI integrations fall into four main categories:
 - Learning and exploration of state machines and contracts
 - Single-developer projects and rapid prototyping
 
-**Key difference**: Spec-Kit focuses on **new feature authoring**, while SpecFact CLI focuses on **brownfield code modernization**.
+**Key difference**: Spec-Kit focuses on **new feature authoring**, while SpecFact CLI focuses on
+**validating existing code and defending it against AI-bloat and drift**.
 
 **See also**: [Spec-Kit Journey Guide](./speckit-journey.md)
 

diff --git a/docs/guides/speckit-journey.md b/docs/guides/speckit-journey.md
@@ -7,7 +7,7 @@ permalink: /guides/speckit-journey/
 # The Journey: From Spec-Kit to SpecFact
 
 > **Spec-Kit and SpecFact are complementary, not competitive.**  
-> **Primary Use Case**: SpecFact CLI for brownfield code modernization  
+> **Primary Use Case**: SpecFact CLI for validation evidence and AI-bloat defense on existing codebases  
 > **Secondary Use Case**: Add SpecFact enforcement to Spec-Kit's interactive authoring for new features
 
 ---

diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md
@@ -10,7 +10,7 @@ redirect_from:
 
 Detailed use cases and examples for SpecFact CLI.
 
-> **Primary Use Case**: Brownfield code modernization (Use Case 1)  
+> **Primary Use Case**: Validation evidence and AI-bloat defense on existing codebases (Use Case 1)  
 > **Secondary Use Case**: Adding enforcement to Spec-Kit projects (Use Case 2)  
 > **Alternative**: Greenfield spec-first development (Use Case 3)  
 > **Validation Use Case**: Sidecar validation of external codebases (Use Case 4) 🆕

diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/**
   - openspec/**
-last_reviewed: 2026-05-21
+last_reviewed: 2026-07-08
 exempt: false
 exempt_reason: ""
 ---
@@ -157,6 +157,7 @@ bundle-specific adapters, and authoring guidance.
 - **[Module Categories](/reference/module-categories/)** - Category taxonomy
 - **[Module Contracts](/reference/module-contracts/)** - Contract interfaces
 - **[Requirements Evidence Input Model](/reference/requirements-evidence-input-model/)** - Requirement input records for validation evidence
+- **[Requirements Context Adapter](/reference/requirements-context-adapter/)** - Import and coverage helpers for requirement context evidence
 - **[Operational Modes](/core-cli/modes/)** - CI/CD and CoPilot modes
 - **[Debug Logging](/core-cli/debug-logging/)** - Diagnostic logging
 

diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -25,6 +25,7 @@ For bundle-specific deep command guides and runbooks, use the canonical modules
 - **[Module Security](module-security.md)** - Marketplace/module integrity and publisher metadata
 - **[Bridge Registry](bridge-registry.md)** - Registry-facing bridge converter declarations
 - **[Requirements Evidence Input Model](requirements-evidence-input-model.md)** - Requirement input records used by validation evidence
+- **[Requirements Context Adapter](requirements-context-adapter.md)** - Import, validation, and coverage helpers for requirement context evidence
 - **[Directory Structure](directory-structure.md)** - Project structure and organization
 - **[Feature Keys](feature-keys.md)** - Key normalization and formats
 - **[Dependency Resolution](dependency-resolution.md)** - Module/pip dependency resolution behavior

diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md
@@ -20,7 +20,10 @@ Use this document for repository-local artifact placement. Use
 [Module Development](../guides/module-development.md) and
 [Publishing modules](../guides/publishing-modules.md) for source/package layout.
 
-> **Primary Use Case**: SpecFact CLI is designed for **brownfield code modernization** - reverse-engineering existing codebases into documented specs with runtime contract enforcement. The directory structure reflects this brownfield-first approach.
+> **Primary Use Case**: SpecFact CLI produces **validation evidence and AI-bloat defense** for AI-assisted and
+> brownfield Python delivery - reverse-engineering existing codebases into documented specs, then detecting drift,
+> bloat, and weak contracts before merge. The directory structure reflects this evidence-first approach to
+> existing code.
 
 **CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.
 

diff --git a/docs/reference/module-categories.md b/docs/reference/module-categories.md
@@ -22,6 +22,7 @@ Category command groups:
 - `specfact code ...`
 - `specfact spec ...`
 - `specfact govern ...`
+- `specfact requirements ...`
 
 ## Canonical Category Assignments
 
@@ -47,6 +48,7 @@ Category command groups:
 | `generate` | `spec` | `specfact-spec` | `spec` | `generate` |
 | `enforce` | `govern` | `specfact-govern` | `govern` | `enforce` |
 | `patch_mode` | `govern` | `specfact-govern` | `govern` | `patch` |
+| `requirements` | `requirements` | `specfact-requirements` | `requirements` | `requirements` |
 
 ## Bundle Contents by Category
 
@@ -55,13 +57,14 @@ Category command groups:
 - `specfact-codebase`: `analyze`, `drift`, `validate`, `repro`
 - `specfact-spec`: `contract`, `api`, `sdd`, `generate`
 - `specfact-govern`: `enforce`, `patch`
+- `specfact-requirements`: `requirements`
 
 ## Bundle Package Layout and Namespaces
 
 Official bundle packages are published from the dedicated modules repository:
 
 - Repository: `nold-ai/specfact-cli-modules`
-- Package roots: `packages/specfact-project/`, `packages/specfact-backlog/`, `packages/specfact-codebase/`, `packages/specfact-spec/`, `packages/specfact-govern/`
+- Package roots: `packages/specfact-project/`, `packages/specfact-backlog/`, `packages/specfact-codebase/`, `packages/specfact-spec/`, `packages/specfact-govern/`, `packages/specfact-requirements/`
 
 Namespace mapping:
 
@@ -70,10 +73,11 @@ Namespace mapping:
 - `specfact-codebase` -> import namespace `specfact_codebase.*`
 - `specfact-spec` -> import namespace `specfact_spec.*`
 - `specfact-govern` -> import namespace `specfact_govern.*`
+- `specfact-requirements` -> import namespace `specfact_requirements.*`
 
 Compatibility note:
 
-- Flat top-level command shims were removed. Use category groups (`project`, `backlog`, `code`, `spec`, `govern`).
+- Flat top-level command shims were removed. Use category groups (`project`, `backlog`, `code`, `spec`, `govern`, `requirements`).
 - `specfact backlog auth ...` is provided by the backlog bundle, not by the permanent core command surface.
 
 > Modules docs handoff: this page remains in the core docs set as release-line overview content.
@@ -115,5 +119,5 @@ Before:
 
 After:
 
-- Core top-level commands plus grouped workflow families (`project`, `backlog`, `code`, `spec`, `govern`).
+- Core top-level commands plus grouped workflow families (`project`, `backlog`, `code`, `spec`, `govern`, `requirements`).
 - No backward-compatibility flat shims.
diff --git a/docs/reference/requirements-context-adapter.md b/docs/reference/requirements-context-adapter.md
@@ -0,0 +1,79 @@
+---
+layout: default
+title: Requirements Context Adapter
+permalink: /reference/requirements-context-adapter/
+description: Core helpers for importing, normalizing, validating, and inspecting upstream requirement context.
+keywords: [requirements, validation, evidence, adapter, projectbundle]
+audience: [team, enterprise]
+expertise_level: [advanced]
+doc_owner: specfact-cli
+tracks:
+  - src/specfact_cli/requirements/context.py
+  - tests/unit/requirements/test_context_adapter.py
+last_reviewed: 2026-07-08
+exempt: false
+exempt_reason: ""
+---
+
+# Requirements Context Adapter
+
+SpecFact core provides helpers that module runtimes can use to normalize
+upstream requirement context into validation evidence. The helpers are designed
+for import, validation, and inspection. They do not create a built-in
+requirements authoring workflow.
+
+## Core Surface
+
+- `normalize_requirement_records(...)` converts source-attributed mappings or
+  `RequirementInput` objects into normalized records and bounded diagnostics.
+- `attach_requirements_to_bundle(...)` stores normalized records under the
+  existing `requirements.inputs` `ProjectBundle` extension.
+- `load_requirements_from_bundle(...)` reads that extension back into
+  `RequirementInput` instances.
+- `validate_requirement_context(...)` emits a `ValidationReport` for evidence
+  usefulness by profile.
+- `inspect_requirement_context_coverage(...)` returns machine-readable coverage
+  counts for downstream command handlers.
+
+```python
+from specfact_cli.models.requirements import RequirementInput, RequirementSourceReference
+from specfact_cli.requirements.context import (
+    attach_requirements_to_bundle,
+    inspect_requirement_context_coverage,
+    normalize_requirement_records,
+)
+
+result = normalize_requirement_records(
+    [
+        {
+            "schema_version": "1",
+            "requirement_id": "REQ-239",
+            "title": "Imported context keeps source attribution",
+            "sources": [
+                {
+                    "source_type": "issue",
+                    "locator": "https://github.com/nold-ai/specfact-cli/issues/239",
+                }
+            ],
+        }
+    ],
+    source_locator="requirements.yaml",
+)
+```
+
+## Runtime Command Ownership
+
+The `requirements` command group is owned by the requirements module runtime.
+Runtime commands should call the core helpers instead of parsing provider
+payloads directly inside root CLI code.
+
+## Compatibility Notes
+
+- Requirement inputs must include `schema_version` and at least one source
+  reference.
+- Invalid imported records produce bounded diagnostics; valid records remain
+  usable.
+- Enterprise or strict validation treats missing downstream evidence links as
+  errors. Less strict profiles receive warnings.
+- Backlog write-back and interactive requirement authoring remain outside this
+  core surface.
diff --git a/docs/reference/requirements-evidence-input-model.md b/docs/reference/requirements-evidence-input-model.md
@@ -10,7 +10,7 @@ doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/models/requirements.py
   - tests/unit/models/test_requirements.py
-last_reviewed: 2026-07-07
+last_reviewed: 2026-07-08
 exempt: false
 exempt_reason: ""
 ---
@@ -76,3 +76,5 @@ bundle.set_extension(
   validation severity without blocking model construction by themselves.
 - No requirement authoring commands or backlog write-back behavior are provided
   by this model.
+- Import, validation, and coverage helpers for these records live in
+  [Requirements Context Adapter](requirements-context-adapter.md).
diff --git a/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md b/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md
@@ -1,31 +1,54 @@
-# 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:00:03+02:00
+- **Workflow:** OpenSpec validate-change refresh before implementation
 - **Strict command:** `openspec validate requirements-02-module-commands --strict`
 - **Result:** PASS
 
 ## Scope Summary
 
-- **New capabilities:** requirements-module
-- **Modified capabilities:** module-io-contract,backlog-adapter
+- **New capabilities:** requirements-context-adapter
+- **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)
+- **Proposed affected code paths:**
+  - `src/specfact_cli/requirements/context.py`
+  - `src/specfact_cli/requirements/__init__.py`
+  - `tests/unit/requirements/test_context_adapter.py`
+  - `docs/reference/requirements-context-adapter.md`
 
 ## Breaking-Change Analysis (Dry-Run)
 
-- 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 new helper APIs for module runtimes to reuse.
+- ProjectBundle integration remains optional through the existing
+  `requirements.inputs` schema-extension namespace.
+- No existing runtime command signature is changed.
+- Existing bundles without `requirements.inputs` remain backward compatible.
 
 ## 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.
+- `requirements-01-data-model` (#238) is implemented and archived on
+  2026-07-07.
+- `arch-07-schema-extension-system` (#213) is implemented and archived on
+  2026-02-18.
+- GitHub issue #239 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 and
+  reported no cache changes.
+- The roadmap places #239 under Requirements Layer / Epic #256; the connector
+  does not expose project parent fields, so the local roadmap remains the
+  available structure evidence.
+- The public issue body and title are aligned to the narrowed
+  validation-evidence format.
+- The internal wiki mirror `wiki/sources/requirements-02-module-commands.md`
+  must be updated when scope/status metadata changes and
+  `wiki_rebuild_graph.py` run from the internal repo root.
 
 ## 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.
+- TDD implementation evidence is complete for the narrowed context-adapter
+  scope, but repository-wide total coverage remains below the 80% policy
+  threshold recorded by CI.
+- Final release readiness is blocked until the required coverage gate is
+  satisfied or an explicit release-governance exception is recorded.