nold-ai · djm81 · Jul 9, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,28 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.51.1] - 2026-07-10
+
+### Fixed
+
+- **Requirements traceability drift**: do not classify linked requirements as
+  stale when callers have not supplied the target universe; stale-link drift
+  remains enabled when `known_targets` is provided.
+
+---
+
+## [0.51.0] - 2026-07-09
+
+### Added
+
+- **Core evidence and traceability contracts**: add a typed evidence envelope
+  with deterministic CI verdict derivation plus a generic artifact index,
+  stable links/fingerprints, incremental rebuild facts, and deterministic
+  orphan/drift/ambiguity/contradiction classification. Requirements is the
+  first integrated adapter; runtime persistence and commands remain deferred.
+
+---
+
 ## [0.50.2] - 2026-07-08
 
 ### Fixed

diff --git a/docs/reference/README.md b/docs/reference/README.md
@@ -26,6 +26,7 @@ For bundle-specific deep command guides and runbooks, use the canonical modules
 - **[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
+- **[Validation Evidence Contracts](validation-evidence-contracts.md)** - Core envelope and traceability result contracts
 - **[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/requirements-context-adapter.md b/docs/reference/requirements-context-adapter.md
@@ -34,6 +34,9 @@ requirements authoring workflow.
   usefulness by profile.
 - `inspect_requirement_context_coverage(...)` returns machine-readable coverage
   counts for downstream command handlers.
+- `analyze_requirement_traceability(...)` reads `requirements.inputs`; when
+  callers supply `known_targets`, it also returns deterministic stale-link drift
+  findings for evidence consumers.
 
 ```python
 from specfact_cli.models.requirements import RequirementInput, RequirementSourceReference
@@ -73,7 +76,9 @@ payloads directly inside root CLI code.
   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.
+- Enterprise, strict, and enterprise_full_stack validation treat missing
+  downstream evidence links as errors. Less strict profiles receive warnings.
 - Backlog write-back and interactive requirement authoring remain outside this
   core surface.
+- Evidence files, CI flags, terminal rendering, and query commands are owned by
+  paired module runtimes rather than core.
diff --git a/docs/reference/validation-evidence-contracts.md b/docs/reference/validation-evidence-contracts.md
@@ -0,0 +1,38 @@
+---
+layout: default
+title: Validation Evidence Contracts
+permalink: /reference/validation-evidence-contracts/
+description: Core contracts for deterministic validation evidence and requirements-first traceability.
+keywords: [validation, evidence, traceability, requirements]
+audience: [team, enterprise]
+expertise_level: [advanced]
+doc_owner: specfact-cli
+tracks:
+  - src/specfact_cli/evidence.py
+  - src/specfact_cli/traceability.py
+last_reviewed: 2026-07-09
+exempt: false
+exempt_reason: ""
+---
+
+# Validation Evidence Contracts
+
+Core exposes typed contracts only. Module runtimes own command flags, evidence
+file persistence, and rendering.
+
+- `EvidenceEnvelope` derives `PASS`, `PASS_WITH_ADVISORY`, or `FAIL` and its CI
+  exit code from typed result summaries.
+- `ArtifactRecord`, `ArtifactLink`, and `build_artifact_index(...)` provide a
+  generic, deterministic, JSON-serializable index for normalized inputs from
+  requirements, architecture, specifications, code, tests, contracts, and other
+  adapters.
+- The index classifies unlinked artifacts, dangling links, duplicate identities,
+  and self-referential contradictions; rebuild results report changed and
+  removed identities.
+- `requirements_to_artifact_records(...)` is the first integrated adapter.
+  Architecture and other inputs are optional; their absence does not create a
+  finding.
+
+Use these contracts as inputs to validation and governance modules; they do not
+introduce a `specfact trace` command, index-file persistence, or requirements
+authoring workflow.
diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
@@ -51,12 +51,13 @@ into auditable validation evidence and cleanup feedback.
 | 1 | `profile-01-config-layering` | [#237](https://github.com/nold-ai/specfact-cli/issues/237) | Rollout modes for validation severity and evidence strictness | - |
 | 2 | `governance-01-evidence-output` | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | Evidence JSON, CI verdicts, remediation packet attachment points | modules `policy-02` |
 | 3 | `governance-02-exception-management` | [#248](https://github.com/nold-ai/specfact-cli/issues/248) | Time-bound validation exceptions and waiver evidence | governance-01; modules `policy-02` |
-| 4 | `traceability-01-index-and-orphans` | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | Artifact drift and orphan detection across inputs | requirements/architecture adapter contracts where present |
+| 4 | `traceability-01-index-and-orphans` | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | Generic artifact index and orphan/drift classification across normalized inputs | requirements input contracts; other adapters optional when present |
 | 5 | `validation-02-full-chain-engine` | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | Validation evidence graph over existing inputs, not a product lifecycle engine | governance-01, traceability-01 |
 | 6 | `dogfooding-01-full-chain-e2e-proof` | [#255](https://github.com/nold-ai/specfact-cli/issues/255) | AI-bloat defense and validation proof on real PRs | governance-01, validation-02, traceability-01 |
 
-**Critical path**: profile-01 plus governance-01 -> traceability-01 ->
-validation-02 -> dogfooding proof.
+**Critical path**: profile-01, governance-01, and traceability-01 converge at
+validation-02 -> dogfooding proof. Traceability requires requirements inputs;
+governance and traceability do not block each other.
 
 ### Track B - AI IDE Validation Distribution
 

diff --git a/...rements-02-module-commands/.openspec.yaml → ...rements-02-module-commands/.openspec.yaml b/...rements-02-module-commands/.openspec.yaml → ...rements-02-module-commands/.openspec.yaml
diff --git a/...s-02-module-commands/CHANGE_VALIDATION.md → ...s-02-module-commands/CHANGE_VALIDATION.md b/...s-02-module-commands/CHANGE_VALIDATION.md → ...s-02-module-commands/CHANGE_VALIDATION.md
diff --git a/...ements-02-module-commands/TDD_EVIDENCE.md → ...ements-02-module-commands/TDD_EVIDENCE.md b/...ements-02-module-commands/TDD_EVIDENCE.md → ...ements-02-module-commands/TDD_EVIDENCE.md
diff --git a/...requirements-02-module-commands/design.md → ...requirements-02-module-commands/design.md b/...requirements-02-module-commands/design.md → ...requirements-02-module-commands/design.md
diff --git a/...quirements-02-module-commands/proposal.md → ...quirements-02-module-commands/proposal.md b/...quirements-02-module-commands/proposal.md → ...quirements-02-module-commands/proposal.md
diff --git a/...le-commands/specs/backlog-adapter/spec.md → ...le-commands/specs/backlog-adapter/spec.md b/...le-commands/specs/backlog-adapter/spec.md → ...le-commands/specs/backlog-adapter/spec.md
@@ -1,6 +1,6 @@
-## MODIFIED Requirements
+## ADDED Requirements
 
-### Requirement: Backlog Adapter
+### Requirement: Source-Attributed Backlog Requirement Snippets
 
 The system SHALL define source-attributed backlog requirement snippets that
 requirements runtime adapters can normalize without provider-specific parsing in

diff --git a/...commands/specs/module-io-contract/spec.md → ...commands/specs/module-io-contract/spec.md b/...commands/specs/module-io-contract/spec.md → ...commands/specs/module-io-contract/spec.md
@@ -1,6 +1,6 @@
-## MODIFIED Requirements
+## ADDED Requirements
 
-### Requirement: Module Io Contract
+### Requirement: Requirements Module IO Contract
 
 Requirements implementations SHALL consume core requirements context adapter
 helpers through the existing `ModuleIOContract` boundary.

diff --git a/...ommands/specs/requirements-module/spec.md → ...ommands/specs/requirements-module/spec.md b/...ommands/specs/requirements-module/spec.md → ...ommands/specs/requirements-module/spec.md
diff --git a/.../requirements-02-module-commands/tasks.md → ...-requirements-02-module-commands/tasks.md b/.../requirements-02-module-commands/tasks.md → ...-requirements-02-module-commands/tasks.md
diff --git a/openspec/changes/governance-01-evidence-output/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md
@@ -17,9 +17,19 @@ validation results consumable by any deterministic gate or agent handoff.
 - Target modules-repo follow-up issue: [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) in `nold-ai/specfact-cli-modules`
 - Downstream changes may extend the envelope, but they MUST NOT redefine the schema or imply core ownership of bundle runtime behavior.
 
+## Core Slice (2026-07-09)
+
+- This change delivers the typed envelope, result semantics, and deterministic CI
+  verdict derivation only.
+- Runtime flags, file persistence, terminal rendering, and emitters remain
+  deferred to modules issue #169.
+- `validation-02` is a downstream producer of envelope sections, not a
+  prerequisite for this core contract.
+
 ## What Changes
 
-- **NEW**: Evidence writer producing standardized JSON artifacts:
+- **NEW**: Typed evidence-envelope schema and field semantics for the
+  standardized JSON shape consumed by runtime emitters:
 
   ```json
   {
@@ -51,26 +61,23 @@ validation results consumable by any deterministic gate or agent handoff.
   }
   ```
 
-- **NEW**: `--evidence-dir .specfact/evidence/` flag on validation and code-review runs to persist evidence artifacts per run
-- **NEW**: `--ci-mode` flag that sets exit codes based on profile enforcement mode: advisory=always 0, mixed=1 for hard-fail rules only, hard=1 for any failure
-- **NEW**: Evidence artifact naming: `{timestamp}_{run_id}_evidence.json` for audit trail
-- **NEW**: Evidence summary on terminal: human-readable table alongside JSON output
-- **EXTEND**: Validation evidence graph (validation-02) extended to produce evidence artifacts
-- **EXTEND**: Validation evidence can append `code_quality` as a parallel section when the run includes review-based clean-code checks
-- **EXTEND**: Policy engine results formatted as evidence-compatible structures
+- **NEW**: Deterministic core CI verdict derivation from typed result summaries.
+- **DEFERRED TO MODULES #169**: `--evidence-dir`, `--ci-mode`, file
+  persistence, artifact naming, terminal rendering, and command emitters.
+- **DOWNSTREAM**: validation-02 and policy owners populate compatible envelope
+  sections; they do not change the core schema ownership.
 - **NEW**: Ownership authority — this change is authoritative for evidence JSON envelope/schema; sibling governance changes may add fields only through this envelope contract.
 
 ## Capabilities
 
 ### New Capabilities
 
-- `governance-evidence-output`: Machine-readable JSON evidence artifacts for CI/CD gates and audit systems, with per-run persistence, CI exit code modes, coverage percentages, exception status, and profile-aware verdicts.
+- `governance-evidence-output`: Typed machine-readable evidence envelope and
+  deterministic CI verdict contract for CI/CD gates and audit consumers.
 
 ### Modified Capabilities
 
-- `validation-evidence-graph`: Extended with evidence artifact generation via `--evidence-dir` and `--ci-mode` flags
-- `policy-engine`: Results formatted as evidence-compatible structures with run_id and timestamps
-- `governance-evidence-output`: Extended with a `code_quality` section that remains parallel to `validation_results` rather than introducing a new traceability layer
+(none; runtime delivery and downstream producers remain separately owned)
 
 ---
 

diff --git a/openspec/changes/governance-01-evidence-output/tasks.md b/openspec/changes/governance-01-evidence-output/tasks.md
@@ -17,7 +17,7 @@
 
 - [ ] 3.1 Implement minimal production code required to satisfy the new scenarios.
 - [ ] 3.2 Add/update contract decorators and type enforcement on public APIs.
-- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only.
+- [ ] 3.3 Add the core envelope models and deterministic verdict derivation; do not add command wiring, emitters, or persistence.
 - [ ] 3.4 Keep clean-code evidence as a sibling `code_quality` section in the envelope rather than adding a new validation layer.
 
 ## 4. Validation and documentation

diff --git a/openspec/changes/profile-01-config-layering/proposal.md b/openspec/changes/profile-01-config-layering/proposal.md
@@ -62,6 +62,6 @@ layering around validation.
 <!-- source_repo: nold-ai/specfact-cli -->
 - **GitHub Issue**: #237
 - **Issue URL**: <https://github.com/nold-ai/specfact-cli/issues/237>
-- **Last Synced Status**: implementation-ready / PR candidate on `feature/profile-01-config-layering-baseline`
+- **Last Synced Status**: implemented in PR [#624](https://github.com/nold-ai/specfact-cli/pull/624); GitHub issue #237 closed on 2026-07-08.
 - **Sanitized**: false
 <!-- content_hash: d7dfe1519fa64668 -->
diff --git a/openspec/changes/profile-01-config-layering/tasks.md b/openspec/changes/profile-01-config-layering/tasks.md
@@ -29,4 +29,4 @@
 ## 5. Delivery
 
 - [x] 5.1 Confirm `openspec/CHANGE_ORDER.md` did not need status/dependency updates; implementation sequencing stayed unchanged.
-- [ ] 5.2 Open a PR from `feature/profile-01-config-layering-baseline` to `dev` with spec/test/code/docs evidence.
+- [x] 5.2 Merge PR [#624](https://github.com/nold-ai/specfact-cli/pull/624) to `dev` with spec/test/code/docs evidence; promotion to `main` remains pending release PR #642.
diff --git a/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md b/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md
@@ -1,31 +1,78 @@
-# Change Validation: traceability-01-index-and-orphans
+# Change Validation Report: traceability-01-index-and-orphans
 
-- **Validated on (UTC):** 2026-02-15T21:54:26Z
-- **Workflow:** /wf-validate-change (proposal-stage dry-run validation)
-- **Strict command:** `openspec validate traceability-01-index-and-orphans --strict`
-- **Result:** PASS
+**Validation Date**: 2026-07-09 (Europe/Berlin)
+**Change Proposal**: [proposal.md](./proposal.md)
+**Validation Method**: Dry-run interface and dependency analysis in
+`/tmp/specfact-validation-traceability-01-index-and-orphans.R4HtLY`
 
-## Scope Summary
+## Executive Summary
 
-- **New capabilities:** traceability-index
-- **Modified capabilities:** (none)
-- **Declared dependencies:** requirements-02 (requirements module), architecture-01 (architecture module)
-- **Proposed affected code paths:** - `modules/trace/` (new module);- `.specfact/trace/index.json` (new generated artifact)
+- Breaking changes: 0 detected / 0 unresolved
+- Dependent files: 3 affected (`traceability.py` and its two unit-test modules)
+- Impact level: Low
+- Validation result: Pass
+- User decision: Extend the change to complete generic core issue #242; keep
+  persistence and runtime UX in modules #170.
 
-## Breaking-Change Analysis (Dry-Run)
+## Interface and Dependency 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 new public contract adds `ArtifactRecord`, `ArtifactLink`,
+`ArtifactEvidenceIndex`, and `build_artifact_index(...)`. It does not change an
+existing public function signature. The existing
+`analyze_requirement_traceability(...)` helper remains available and delegates
+to the generic index.
 
-## Dependency and Integration Review
+`TraceabilityResult` remains an alias for the returned model, and the legacy
+`TraceabilityFinding.requirement_id` read surface remains available as a
+compatibility property. Repository search found no production callers outside
+`src/specfact_cli/traceability.py`; the two existing requirement-traceability
+tests were updated for the generalized finding names.
 
-- 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.
+No downstream runtime command or persistence dependency is introduced. The
+requirements adapter is the sole required integrated input. Missing
+architecture records cannot produce a finding because classification considers
+only supplied normalized records.
 
-## Validation Outcome
+## Required Updates
 
-- 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.
+### Critical Updates
+
+None.
+
+### Completed Updates
+
+- Added generic index tests for canonical ordering, all four classifications,
+  rebuild deltas, JSON serialization, and requirements mapping.
+- Updated the traceability contract, proposal, design, task list, change order,
+  and validation-evidence reference documentation.
+- Updated the internal wiki source and rebuilt its dependency graph.
+
+## Impact Assessment
+
+- **Code impact**: One core traceability module gains a generic, in-memory
+  index contract and compatibility adapter.
+- **Test impact**: Existing requirements-only tests are retained; new unit
+  tests cover the generalized contract.
+- **Documentation impact**: Public evidence-contract documentation now
+  distinguishes core index ownership from modules runtime delivery.
+- **Release impact**: Minor (new public core contract; no removals).
+
+## Format Validation
+
+- **proposal.md format**: Pass
+- **tasks.md format**: Pass; worktree, TDD, documentation, validation, and PR
+  tasks are explicit.
+- **specs format**: Pass; each requirement uses Given/When/Then scenarios.
+- **Config compliance**: Pass, subject to final repository quality gates.
+
+## OpenSpec Validation
+
+- **Status**: Pass
+- **Command**: `openspec validate traceability-01-index-and-orphans --strict`
+- **Issues found/fixed**: 0 / 0
+
+## Scope Resolution
+
+Core issue #242 is complete when this reusable artifact index is merged.
+Modules issue #170 remains a separate delivery follow-up for persistence,
+commands, flags, rendering, and query UX; it is not a core-issue blocker.
diff --git a/openspec/changes/traceability-01-index-and-orphans/TDD_EVIDENCE.md b/openspec/changes/traceability-01-index-and-orphans/TDD_EVIDENCE.md
@@ -0,0 +1,22 @@
+# TDD Evidence: traceability-01-index-and-orphans
+
+- Failing-before: `hatch run pytest tests/unit/traceability/test_evidence_traceability.py -q` — 2026-07-09 Europe/Berlin; failed during collection because `specfact_cli.traceability` did not exist.
+- Passing-after: `hatch run pytest tests/unit/traceability/test_evidence_traceability.py -q` — 2026-07-09 Europe/Berlin; 3 passed.
+- Failing-before generic-index expansion: `hatch run pytest tests/unit/traceability/test_artifact_index.py -q` — 2026-07-09 Europe/Berlin; failed during collection because the generic index contracts did not exist.
+- Passing-after generic-index expansion: `hatch run pytest tests/unit/traceability -q` — 2026-07-09 Europe/Berlin; 7 passed after aligning the compatibility assertion to the generic finding taxonomy.
+
+## Quality Gate Evidence
+
+Verified 2026-07-10T00:41:51+0200 Europe/Berlin after Codex and CodeRabbit
+remediation:
+
+- `hatch run pytest tests/unit/traceability tests/unit/requirements/test_context_adapter.py -q` — PASS, 18 passed.
+- `hatch run type-check` — PASS, 0 errors; 1,627 pre-existing baseline warnings.
+- `hatch run docs-validate` and `hatch run yaml-lint` — PASS.
+- `hatch run contract-test` — PASS.
+- `hatch run bandit-scan`, `hatch run semgrep-sast --json`, and
+  `hatch run semgrep-sast-gate` — PASS, no blocking findings.
+- `hatch run specfact code review run --json --out .specfact/code-review.json --scope changed` — PASS, no findings.
+- `openspec validate traceability-01-index-and-orphans --strict`,
+  `openspec validate governance-01-evidence-output --strict`, and
+  `openspec validate profile-01-config-layering --strict` — PASS.