release: promote dev to main

CHANGELOG.md

@@ -10,6 +10,48 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.52.3] - 2026-07-14
+
+### Fixed
+
+- **Upstream evidence review remediation**: preserve wrapped OpenSpec scenario
+  clauses, report malformed Spec Kit requirement entries, and tolerate invalid
+  UTF-8 in optional profile configuration.
+
+---
+
+## [0.52.2] - 2026-07-13
+
+### Fixed
+
+- **OpenSpec schema import resilience**: reject invalid UTF-8 configuration
+  with the standard fail-closed source-schema diagnostic instead of crashing.
+
+---
+
+## [0.52.1] - 2026-07-13
+
+### Fixed
+
+- **Import evidence review hardening**: reject malformed OpenSpec schema
+  declarations, preserve unique deterministic requirement identities, resolve
+  relative source locators from the project root, and tolerate unreadable
+  optional profile configuration.
+
+---
+
+## [0.52.0] - 2026-07-13
+
+### Added
+
+- **Upstream requirements evidence import**: normalize native OpenSpec and
+  Spec Kit requirement sources into deterministic, auditable records, with
+  source hashes, import gates, layered profile mappings, and required-field
+  advisories. Unsupported or customized source schemas now fail closed without
+  emitting partial records.
+
+---
+
 ## [0.51.2] - 2026-07-10
 
 ### Fixed

docs/reference/requirements-context-adapter.md

@@ -9,8 +9,10 @@ expertise_level: [advanced]
 doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/requirements/context.py
+  - src/specfact_cli/requirements/importers.py
   - tests/unit/requirements/test_context_adapter.py
-last_reviewed: 2026-07-08
+  - tests/unit/requirements/test_upstream_evidence_imports.py
+last_reviewed: 2026-07-13
 exempt: false
 exempt_reason: ""
 ---
@@ -26,6 +28,10 @@ requirements authoring workflow.
 
 - `normalize_requirement_records(...)` converts source-attributed mappings or
   `RequirementInput` objects into normalized records and bounded diagnostics.
+- `import_openspec_change(...)` reads a native OpenSpec change folder and
+  derives deterministic, source-attributed requirement records.
+- `import_speckit_feature(...)` reads a native Spec Kit feature folder through
+  the existing scanner and derives deterministic requirement records.
 - `attach_requirements_to_bundle(...)` stores normalized records under the
   existing `requirements.inputs` `ProjectBundle` extension.
 - `load_requirements_from_bundle(...)` reads that extension back into
@@ -38,6 +44,49 @@ requirements authoring workflow.
   callers supply `known_targets`, it also returns deterministic stale-link drift
   findings for evidence consumers.
 
+Both native import helpers are read-only. They derive stable IDs, preserve
+Given/When/Then scenarios as business rules, and record the parsed artifact's
+`sha256:` revision. Re-running unchanged input produces the same records.
+
+## Source Compatibility Boundary
+
+Imports are deliberately fail-closed. The core supports only fixture-backed
+default Markdown profiles: OpenSpec `spec-driven` (or no declared schema) with
+native `Requirement` and `Scenario` headings, and the default Spec Kit
+`Feature Specification`/`FR-` template. A custom OpenSpec schema, a Spec Kit
+template override/preset/extension root, or unknown required heading produces
+an error `unsupported-source-schema` diagnostic and no records from that
+source.
+
+The adapter does not infer an upstream CLI version from Markdown or fetch a
+live schema during import: native artifacts do not consistently carry a tool
+version, and network-dependent parsing would make CI non-reproducible. To add
+an upstream format, add a pinned representative fixture, extend the core
+profile, and pass its compatibility test before release.
+
+## Import Validation Gates
+
+For OpenSpec and Spec Kit records, `validate_requirement_context(...)` emits
+machine-readable findings for:
+
+- `scenario-unverified`: a derived scenario has no test or validation link.
+- `stale-import`: an artifact's current bytes no longer match its imported
+  `sha256:` revision.
+- `source-missing`: an imported artifact is no longer available.
+- `ambiguous-mapping`: different imported sources claim the same derived ID.
+
+An error-severity finding makes the paired `requirements validate` command
+exit non-zero; the module runtime owns terminal formatting and command flags.
+The core helper also preserves `missing-evidence` as a stable, machine-readable
+finding code.
+
+When no profile is passed, validation resolves the layered profile from the
+organization, repository, and developer-local configuration. The adapter maps
+only evidence-backed required fields: `id`, `title`, `acceptance`, and
+`trace_links`. Other profile fields are surfaced as
+`unsupported-profile-field` advisories rather than requiring OpenSpec or Spec
+Kit authors to add SpecFact metadata.
+
 ```python
 from specfact_cli.models.requirements import RequirementInput, RequirementSourceReference
 from specfact_cli.requirements.context import (
@@ -70,6 +119,17 @@ 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.
 
+After this core change ships, the paired module change will add
+`requirements import --from-openspec` and `--from-speckit`; those flags will
+delegate entirely to these core helpers.
+`requirements import --from-file` remains the generic fallback for records
+outside the supported native profiles.
+
+The currently released requirements module does not expose those native-import
+flags yet. It remains compatible because it uses only `--from-file`; the paired
+module release for #168 will declare a `0.52.0` core compatibility floor before
+exposing `--from-openspec` or `--from-speckit`.
+
 ## Compatibility Notes
 
 - Requirement inputs must include `schema_version` and at least one source

openspec/CHANGE_ORDER.md

@@ -82,9 +82,9 @@ planning workflows.
 |---:|---|---|---|---|
 | 1 | `requirements-01-data-model` | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | Normalized requirements-input records for evidence | arch-07 |
 | 2 | `requirements-02-module-commands` | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | Import and normalize existing requirement context | requirements-01 |
-| 3 | `requirements-03-backlog-sync` | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | Read-first drift evidence; no write-back critical path | requirements-02; modules `sync-01` |
+| 3 | `openspec-01-intent-trace` | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | Import-first OpenSpec and Spec Kit requirement evidence with pass/fail gates (rescoped 2026-07-13) | requirements-01/02 |
 | 4 | `architecture-01-solution-layer` | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | Architecture-boundary records and drift validation | requirements input contracts |
-| 5 | `openspec-01-intent-trace` | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | Optional OpenSpec and Spec Kit evidence adapter | requirements-01/02 |
+| Parked | `requirements-03-backlog-sync` | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | Read-first drift evidence; no write-back critical path. Deprioritized 2026-07-13 behind openspec-01 | requirements-02; modules `sync-01` |
 | Gated | `architecture-02-well-architected-review` | [#524](https://github.com/nold-ai/specfact-cli/issues/524) | Architecture-boundary review findings | architecture-01 shipped plus one usage cycle |
 | Gated | `telemetry-01-opentelemetry-default-on` | [#518](https://github.com/nold-ai/specfact-cli/issues/518) | Opt-in validation outcome telemetry only | governance-01 evidence fields |
 
@@ -111,7 +111,7 @@ Update each proposal first, then run strict OpenSpec validation.
 | `requirements-02-module-commands` | Drop requirement authoring as a flagship path. Keep import, normalization, validation, and coverage inspection. |
 | `requirements-03-backlog-sync` | Make drift detection/read-first import the product value. Keep write-back preview out of the critical path. |
 | `architecture-01-solution-layer` | Reduce to architecture-boundary validation and drift evidence. Do not generate architecture. |
-| `openspec-01-intent-trace` | Rewrite as an optional adapter that consumes OpenSpec and Spec Kit artifacts. |
+| `openspec-01-intent-trace` | Done 2026-07-13: rescoped to import-first adapter consuming native OpenSpec and Spec Kit artifacts with deterministic pass/fail gates. |
 | `dogfooding-01-full-chain-e2e-proof` | Rewrite proof around real PR review, JSON evidence, AI-bloat findings, remediation packets, rerun proof. |
 | `ai-integration-01-agent-skill` | Teach agents to run SpecFact validation and interpret evidence. |
 | `ai-integration-03-instruction-files` | Generate lightweight validation aliases only. |
@@ -155,9 +155,12 @@ Update each proposal first, then run strict OpenSpec validation.
 
 ### Wave 5 - Optional adapters and later extensions
 
-- `requirements-01/02/03` only as validation input adapters.
+- `requirements-01/02` only as validation input adapters (shipped);
+  `requirements-03` parked 2026-07-13.
 - `architecture-01` only as architecture-boundary validation input.
-- `openspec-01` as optional OpenSpec and Spec Kit evidence adapter.
+- `openspec-01` as import-first OpenSpec and Spec Kit requirement evidence
+  adapter with deterministic gates; pulled forward to Track C order 3 on
+  2026-07-13 (rescoped, no longer positioned as optional-only).
 - `architecture-02`, `telemetry-01`, and `ai-integration-02` only after pull
   from the validation loop exists.