release: merge dev into main

[djm81]

Summary

• Promote the current dev branch to main.
• Includes the merged source-readiness work and other accumulated development changes.

Validation

• GitHub Actions will validate the merge against main.

[strix-security]

Strix is installed on this repository, but we couldn't run this PR security review because this workspace's trial has ended. Add a card to resume code reviews here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5f762466-a265-4166-8ffd-6d37530466a2

📥 Commits

Reviewing files that changed from the base of the PR and between 011417f and 0cf57ca.

⛔ Files ignored due to path filters (2)

• docs/reference/commands.generated.json is excluded by !**/*.generated.*
• docs/reference/commands.generated.md is excluded by !**/*.generated.*

📒 Files selected for processing (2)

• docs/reference/requirements-context-adapter.md
• llms.txt

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• nold-ai/specfact-cli-modules (manual) → reviewed against branch dev instead of the default branch

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/reference/requirements-context-adapter.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (10)

• GitHub Check: Linting (ruff, pylint, safe-write guard)
• GitHub Check: Runtime Discovery Smoke (macOS)
• GitHub Check: CLI Command Validation
• GitHub Check: Tests (Python 3.12)
• GitHub Check: Independent Static Analysis
• GitHub Check: Compatibility (Python 3.11)
• GitHub Check: Tests (Python 3.12)
• GitHub Check: CLI Command Validation
• GitHub Check: Runtime Discovery Smoke (macOS)
• GitHub Check: Compatibility (Python 3.11)

🧰 Additional context used

🔀 Multi-repo context nold-ai/specfact-cli-modules

Linked repositories findings

nold-ai/specfact-cli-modules — inspected dev ref

• The module’s runtime compatibility messages are stale relative to this PR: packages/specfact-requirements/src/specfact_requirements/requirements/runtime.py:37 and :74 still require specfact-cli >=0.52.0 and reference core change #350. This PR documents the native-import compatibility floor as 0.53.1 and identifies the source-readiness contract as core issue #648 / modules issue #346. [::nold-ai/specfact-cli-modules::]
• The module delegates native parsing and validation to core rather than reimplementing it. packages/specfact-requirements/src/specfact_requirements/requirements/commands.py:115-124 calls import_native_requirements_to_bundle, while the module specification explicitly requires unchanged core diagnostics, zero persistence on readiness errors, and read-only upstream sources. [::nold-ai/specfact-cli-modules::]
• The module’s validation call already forwards profile and project_root to core at packages/specfact-requirements/src/specfact_requirements/requirements/runtime.py:282, matching the updated validate_requirement_context signature. [::nold-ai/specfact-cli-modules::]
• A second stale core-version pin exists in requirements-docs-ci.txt:11, which pins specfact-cli==0.46.2; this is below both the old runtime message floor (0.52.0) and the new documented native-import floor (0.53.1). [::nold-ai/specfact-cli-modules::]

🔇 Additional comments (1)

llms.txt (1)

120-120: LGTM!

---

📝 Walkthrough

User-visible behavior and CLI surface

• Native upstream imports now fail closed on incomplete/invalid/unrecognized Spec Kit and OpenSpec sources (including invalid UTF-8 spec.md bytes), returning zero normalized requirement records rather than emitting partial/placeholder requirements.
• Source readiness is enforced before normalization:
  • Rejects incomplete Spec Kit scaffolds/templates (including unresolved “needs clarification” style markers), missing substantive FR content, and missing complete Given/When/Then acceptance scenarios.
  • Spec Kit scenario → requirement evidence mapping is limited to FRs explicitly referenced in the corresponding user-story block(s).
• Native OpenSpec validation runs only when enabled by layered config (e.g., validation.openspec.require_native_validation), with bounded execution:
  • Validation failures emit source-invalid.
  • Missing required OpenSpec validator executable emits upstream-validator-unavailable.
• specfact requirements import source options are documented/contracted to support --from-file, --from-openspec, and --from-speckit.

Contract/API impact

• Expanded public exports in src/specfact_cli/requirements/__init__.py:
  • import_openspec_change
  • import_speckit_feature
  • requires_native_openspec_validation
• API signature updates:
  • validate_requirement_context(bundle, *, profile: RequirementContextValidationProfile | None = None, project_root: Path | None = None)
  • import_openspec_change(change_dir, *, profile: RequirementContextValidationProfile | None = None, project_root: Path | None = None)
• Import/validation behavior now produces richer structured diagnostics and enforces atomic/readonly behavior on readiness failures (empty RequirementContextImportResult.requirements while preserving diagnostics), including codes such as:
  • missing-evidence, scenario-unverified, ambiguous-mapping
  • unsupported-profile-field, required-field-missing
  • incomplete-source-template, source-incomplete, source-malformed, unsupported-source-schema, source-invalid, upstream-validator-unavailable
• New/updated readiness gating is implemented as a policy-driven preflight distinct from downstream evidence gating.

Testing and quality gates

• Expanded upstream evidence import tests to cover:
  • Spec Kit scaffold/template rejection and scenario scoping to explicitly referenced FRs
  • OpenSpec parse-failure behavior discarding previously accumulated records
  • Invalid UTF-8 handling for both OpenSpec and Spec Kit sources (reject without partial records)
  • Ambiguity detection that ignores supplemental FILE sources
  • Updated expectations for diagnostic codes (e.g., source-malformed)
• GitHub Actions quality-gates update:
  • Coverage gate now enables set -o pipefail
  • Coverage threshold is taken directly from pyproject.toml (tool.coverage.report.fail_under) with no hard max(..., 80.0) minimum

OpenSpec, documentation, and release updates

• Added and documented the new requirements-04-upstream-source-readiness contract/design/specs, including deterministic fail-closed readiness semantics and policy-gated native OpenSpec validation behavior.
• Updated OpenSpec plan/docs (openspec/CHANGE_ORDER.md, openspec-01-intent-trace/*) to reflect the import-first requirement-evidence model and the rescoped, deterministic gate framing; updated referenced issue IDs.
• Documentation updates include docs/reference/requirements-context-adapter.md (new Source Readiness section and updated native import compatibility floor).
• Version bump to 0.53.2 across pyproject.toml, setup.py, and package __version__ exports.
• CHANGELOG.md updated with new release entries (0.53.2/0.53.1/0.53.0) describing the hardening and source-readiness/coverage-gate fixes.

Walkthrough

Native OpenSpec and Spec Kit imports now reject incomplete or invalid sources before normalization, optionally run strict OpenSpec validation, preserve zero-record failure semantics, expand context validation, update regression coverage, and align release metadata and coverage enforcement.

Changes

Requirements evidence import

Layer / File(s)	Summary
Readiness contracts and specifications openspec/changes/requirements-04-upstream-source-readiness/*, openspec/changes/openspec-01-intent-trace/*, docs/reference/requirements-context-adapter.md	Defines fail-closed readiness diagnostics, native validation policy, deterministic provenance, and portable import behavior.
Native importer readiness flow src/specfact_cli/requirements/importers.py, src/specfact_cli/requirements/__init__.py	Adds Spec Kit completeness checks, optional strict OpenSpec CLI validation, UTF-8 failure handling, atomic parse failures, and FR-specific scenario mapping.
Profile resolution and import gates src/specfact_cli/requirements/context.py	Adds layered profile resolution, native-validation policy lookup, required-field mapping, source-integrity checks, unverified-scenario detection, and ambiguity diagnostics.
Import and readiness regression coverage tests/unit/requirements/test_upstream_evidence_imports.py, tests/fixtures/speckit/*, openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md	Covers validator outcomes, portable imports, incomplete sources, malformed bytes, parse failures, deterministic scenario mapping, and validation behavior.
Release and quality alignment .github/workflows/pr-orchestrator.yml, pyproject.toml, setup.py, src/**/__init__.py, CHANGELOG.md, openspec/CHANGE_ORDER.md	Updates package version metadata, release notes, change ordering, and coverage-gate enforcement with pipefail and the configured threshold.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SourceFolder
  participant import_openspec_change
  participant requires_native_openspec_validation
  participant openspec_validate
  participant RequirementContextImportResult
  SourceFolder->>import_openspec_change: provide native change artifacts
  import_openspec_change->>requires_native_openspec_validation: resolve profile and policy
  requires_native_openspec_validation->>openspec_validate: invoke strict JSON validation when required
  openspec_validate-->>import_openspec_change: return valid result or diagnostic
  import_openspec_change->>RequirementContextImportResult: emit normalized records or zero records with diagnostics

Loading

Possibly related issues

• nold-ai/specfact-cli#648 — Directly covers native source-readiness behavior implemented in the importers and validation tests.
• nold-ai/specfact-cli-modules#346 — Covers the paired upstream source-readiness and diagnostic contract.
• nold-ai/specfact-cli-modules#168 — Relates to the earlier module runtime contract refined by these core import helpers.

Possibly related PRs

• nold-ai/specfact-cli#649 — Directly overlaps the native source-readiness implementation and tests.
• nold-ai/specfact-cli#646 — Preceding OpenSpec/Spec Kit evidence-import work extended here.
• nold-ai/specfact-cli#647 — Established the import-first requirements evidence adapter and exports.

Suggested labels: documentation, bug

Suggested reviewers: repo-owners

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description omits most required template sections, including issue links, change type, testing evidence, and checklists.	Fill in the repository template sections, especially fixes/new features, contract references, testing evidence, test environment, checklist, and quality gates.
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR's main action of merging dev into main.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 154a8bb1ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 13

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

openspec/changes/requirements-04-upstream-source-readiness/tasks.md (1)

54-60: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Complete the strict validation gate before merging.

Tasks 5.1–5.3 remain unchecked, including openspec validate ... --strict, final cross-repository synchronization, and release coordination. The recorded test evidence does not replace this required specification validation.

As per path instructions, OpenSpec changes must be strictly validated before the change is considered complete.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/requirements-04-upstream-source-readiness/tasks.md` around
lines 54 - 60, Complete and verify tasks 5.1–5.3 in the release coordination
checklist: run the strict OpenSpec validation command, synchronize the
referenced issue and wiki with the final scope, version, dependencies, and
status, then release the core contract and coordinate the dependent modules
issue, implementation, and PR only after compatibility is published. Mark each
task complete only after its required evidence is recorded.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/requirements-context-adapter.md`:
- Around line 152-155: Update the requirements-context-adapter documentation to
use the authoritative paired-module issue nold-ai/specfact-cli-modules#346 and
the changed core compatibility floor 0.53.1, replacing the stale `#168` and 0.52.0
references while preserving the surrounding release-compatibility explanation.
- Around line 146-155: The release documentation in
docs/reference/requirements-context-adapter.md lines 146-155 and the
corresponding llms.txt entry at line 120 still describe --from-openspec and
--from-speckit as future-only. Update both references to reflect that these
native import flags are already exposed, while retaining the --from-file
fallback and compatibility details that remain accurate.

In `@openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md`:
- Around line 24-28: Update the compatibility-extension statement in
CHANGE_VALIDATION.md to scope the “no public parameter or model change” claim to
the earlier change, or reconcile it with the documented keyword-only profile and
project_root parameters of import_openspec_change. Ensure the OpenSpec
validation artifacts consistently identify the new API contract as the
specification source of truth.

In `@openspec/changes/openspec-01-intent-trace/proposal.md`:
- Around line 108-116: Resolve the native-import availability contradiction by
aligning the claim in openspec/changes/openspec-01-intent-trace/proposal.md
lines 108-116 with the actual paired module runtime release state, stating that
native import is unavailable until that runtime ships if issue `#168` remains
pending. In
openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
lines 33-41, retain or update the pending-runtime wording consistently; ensure
both artifacts describe one cross-repository CLI contract.

In
`@openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md`:
- Around line 104-144: The OpenSpec compatibility preflight can crash when
`_openspec_compatibility_error` reads a corrupt `spec.md` as UTF-8. Update that
preflight path to catch decoding and relevant read errors, return
`unsupported-source-schema`, and prevent any requirement records from being
emitted; add a regression test covering an invalid-UTF-8 artifact.
- Around line 60-67: Update the malformed Spec Kit requirement scenario and its
implementation contract so malformed entries use a distinct diagnostic category
rather than source-missing. Define the new diagnostic consistently in the
relevant requirements specification and this scenario, preserving one bounded
warning per malformed entry with the source artifact and entry index; keep
source-missing reserved for unresolved source locators.

In `@openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md`:
- Around line 127-136: Raise repository coverage to the required 80% minimum,
run the prescribed smart-test and PR Tests/Quality Gates checks, and update
TDD_EVIDENCE.md with successful results. In tasks.md, keep task 5.1 unchecked
until those quality gates pass; update it only after green evidence is recorded.

In `@src/specfact_cli/requirements/context.py`:
- Around line 465-467: Update the identity collection logic in the requirement
mapping flow to include only imported-source locators when determining
ambiguity, excluding supplemental FILE and DOCUMENT sources. Preserve the
existing requirement.requirement_id grouping and ambiguity detection behavior
for qualifying imported sources.
- Around line 544-554: Add the required `@beartype` decorator to the public
validate_requirement_context function, alongside its existing `@require` and
`@ensure` icontract guards, so runtime type checking covers the bundle, profile,
project_root, and return value.

In `@src/specfact_cli/requirements/importers.py`:
- Around line 491-499: Update the requirement construction flow around
_speckit_rules() so scenarios are not attached to every Functional Requirement:
preserve unmatched scenarios as unmapped evidence and only assign them when an
explicit source relationship identifies the FR. Ensure multi-FR/multi-story
input produces no false many-to-many trace links, and add a regression test
covering that case.
- Around line 388-428: The OpenSpec import must discard all accumulated
requirements when any spec fails to parse. In the import loop around
parser.parse_change_spec_delta, return an empty RequirementContextImportResult
with the collected diagnostics immediately when parsed is None, rather than
continuing with previously collected records.

In `@tests/unit/requirements/test_upstream_evidence_imports.py`:
- Around line 31-41: Isolate the tests in test_upstream_evidence_imports.py from
the developer’s user-level SpecFact configuration by adding a module-level
fixture that redirects Path.home() to a temporary directory containing no
config.yaml. Ensure the fixture applies to every test that uses _bundle() and
preserves the existing test behavior while preventing native validation settings
from leaking into the suite.

In `@tests/unit/workflows/test_trustworthy_green_checks.py`:
- Around line 215-217: Restore the 80% total Python coverage contract: in
tests/unit/workflows/test_trustworthy_green_checks.py lines 215-217, update the
workflow assertions around configured_fail_under so the enforced minimum cannot
fall below 80%; in
openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md lines
32-34, remove or correct the claim that 64% coverage against a 50% threshold is
compliant, unless the authoritative policy is explicitly changed first.

---

Outside diff comments:
In `@openspec/changes/requirements-04-upstream-source-readiness/tasks.md`:
- Around line 54-60: Complete and verify tasks 5.1–5.3 in the release
coordination checklist: run the strict OpenSpec validation command, synchronize
the referenced issue and wiki with the final scope, version, dependencies, and
status, then release the core contract and coordinate the dependent modules
issue, implementation, and PR only after compatibility is published. Mark each
task complete only after its required evidence is recorded.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6938cf94-e145-4b22-bec8-040a1fa66062

📥 Commits

Reviewing files that changed from the base of the PR and between b0f4404 and 154a8bb.

⛔ Files ignored due to path filters (2)

• docs/reference/commands.generated.json is excluded by !**/*.generated.*
• docs/reference/commands.generated.md is excluded by !**/*.generated.*

📒 Files selected for processing (33)

• .github/workflows/pr-orchestrator.yml
• CHANGELOG.md
• docs/reference/requirements-context-adapter.md
• llms.txt
• openspec/CHANGE_ORDER.md
• openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md
• openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• openspec/changes/openspec-01-intent-trace/tasks.md
• openspec/changes/requirements-04-upstream-source-readiness/.openspec.yaml
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/README.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• pyproject.toml
• setup.py
• src/__init__.py
• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py
• tests/fixtures/speckit/spec-template-v0.12.18.md
• tests/unit/requirements/test_upstream_evidence_imports.py
• tests/unit/workflows/test_trustworthy_green_checks.py

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• nold-ai/specfact-cli-modules (manual) → reviewed against branch dev instead of the default branch

💤 Files with no reviewable changes (3)

• openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Tests (Python 3.12)

🧰 Additional context used

📓 Path-based instructions (20)

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/*.py: Maintain minimum 80% test coverage, with 100% coverage for critical paths in Python code
Use clear naming and self-documenting code, preferring clear names over comments
Ensure each function/class has a single clear purpose (Single Responsibility Principle)
Extract common patterns to avoid code duplication (DRY principle)
Apply SOLID object-oriented design principles in Python code
Use type hints everywhere in Python code and enable basedpyright strict mode
Use Pydantic models for data validation and serialization in Python
Use async/await for I/O operations in Python code
Use context managers for resource management in Python
Use dataclasses for simple data containers in Python
Enforce maximum line length of 120 characters in Python code
Use 4 spaces for indentation in Python code (no tabs)
Use 2 blank lines between classes and 1 blank line between methods in Python
Organize imports in order: Standard library → Third party → Local in Python files
Use snake_case for variables and functions in Python
Use PascalCase for class names in Python
Use UPPER_SNAKE_CASE for constants in Python
Use leading underscore (_) for private methods in Python classes
Use snake_case for Python file names
Enable basedpyright strict mode with strict type checking configuration in Python
Use Google-style docstrings for functions and classes in Python
Include comprehensive exception handling with specific exception types in Python code
Use logging with structured context (extra parameters) instead of print statements
Use retry logic with tenacity decorators (@retry) for operations that might fail
Use Pydantic BaseSettings for environment-based configuration in Python
Validate user input using Pydantic validators in Python models
Use @lru_cache and Redis-based caching for expensive calculations in Python
Run code formatting with Black (120 character line length) and isort in Python
Run type checking with basedpyright on all Python files
Run linting with ruff and pylint on all Pyth...

Files:

• src/__init__.py
• src/specfact_cli/__init__.py
• setup.py
• tests/unit/workflows/test_trustworthy_green_checks.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py
• tests/unit/requirements/test_upstream_evidence_imports.py

{src/__init__.py,pyproject.toml,setup.py}

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

{src/__init__.py,pyproject.toml,setup.py}: Update src/init.py first as primary source of truth for package version, then pyproject.toml and setup.py
Maintain version synchronization across src/init.py, pyproject.toml, and setup.py

Files:

• src/__init__.py
• setup.py
• pyproject.toml

src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

src/**/*.py: All code changes must be followed by running the full test suite using the smart test system.
All Python files in src/ and tools/ directories must have corresponding test files in tests/ directory. If you modify src/common/logger_setup.py, you MUST have tests/unit/common/test_logger_setup.py. NO EXCEPTIONS - even small changes require tests.
All new Python runtime code files must have corresponding test files created BEFORE committing the code. NO EXCEPTIONS - no code without tests.
Test Coverage Validation: Run hatch run smart-test-unit for modified files, hatch run smart-test-folder for modified directories, and hatch run smart-test-full before committing. ALL TESTS MUST PASS.
All components must support TEST_MODE=true environment variable with test-specific behavior defined as: if os.environ.get('TEST_MODE') == 'true': # test-specific behavior
Use src/common/logger_setup.py for all logging via: from common.logger_setup import get_logger; logger = get_logger(name)
Use src/common/redis_client.py with fallback for Redis operations via: from common.redis_client import get_redis_client; redis_client = get_redis_client()
Type checking must pass with no errors using: mypy .
Test coverage must meet or exceed 80% total coverage. New code must have corresponding tests. Modified code must maintain or improve coverage. Critical paths must have 100% coverage.
Use Pydantic v2 validation for all context and data schemas.

Add/update contracts on new or modified public APIs, stateful classes and adapters using icontract decorators and beartype runtime type checks

src/**/*.py: Meaningful Naming — identifiers reveal intent; avoid abbreviations. Identifiers in src/ must use snake_case (modules/functions), PascalCase (classes), UPPER_SNAKE_CASE (constants). Avoid single-letter names outside short loop variables.
KISS — keep functions and modules small and single-purpose. Maximum function length: 120 lines (Phase A error threshold). Maximum cyclomati...

Files:

• src/__init__.py
• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py

@(src|tests)/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Linting must pass with no errors using: pylint src tests

Files:

• src/__init__.py
• src/specfact_cli/__init__.py
• tests/unit/workflows/test_trustworthy_green_checks.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py
• tests/unit/requirements/test_upstream_evidence_imports.py

{pyproject.toml,setup.py,src/__init__.py}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Manually update version numbers in pyproject.toml, setup.py, and src/init.py when making a formal version change

Files:

• src/__init__.py
• setup.py
• pyproject.toml

**/*.{py,pyi}

📄 CodeRabbit inference engine (.cursorrules)

**/*.{py,pyi}: After any code changes, follow these steps in order: (1) Apply linting and formatting to ensure code quality: hatch run format, (2) Type checking: hatch run type-check (basedpyright), (3) Contract-first approach: Run hatch run contract-test for contract validation, (4) Run full test suite: hatch test --cover -v, (5) Verify all tests pass and contracts are satisfied, (6) Fix any issues and repeat steps until all tests pass
All public APIs must have @icontract decorators and @beartype type checking
Use Pydantic models for all data structures with data validation
Only write high-value comments if at all. Avoid talking to the user through comments

Files:

• src/__init__.py
• src/specfact_cli/__init__.py
• setup.py
• tests/unit/workflows/test_trustworthy_green_checks.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py
• tests/unit/requirements/test_upstream_evidence_imports.py

src/specfact_cli/**/*.py

⚙️ CodeRabbit configuration file

src/specfact_cli/**/*.py: Focus on modular CLI architecture: lazy module loading, registry/bootstrap patterns, and
dependency direction. Flag breaking changes to public APIs, Pydantic models, and resource
bundling. Verify @icontract + @beartype on public surfaces; prefer centralized logging
(get_bridge_logger) over print().

Files:

• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py

**/*.{md,mdc}

📄 CodeRabbit inference engine (.cursor/rules/markdown-rules.mdc)

**/*.{md,mdc}: Do not use more than one consecutive blank line anywhere in the document (MD012: No Multiple Consecutive Blank Lines)
Fenced code blocks should be surrounded by blank lines (MD031: Fenced Code Blocks)
Lists should be surrounded by blank lines (MD032: Lists)
Files must end with a single empty line (MD047: Files Must End With Single Newline)
Lines should not have trailing spaces (MD009: No Trailing Spaces)
Use asterisks (**) for strong emphasis, not underscores (__) (MD050: Strong Style)
Fenced code blocks must have a language specified (MD040: Fenced Code Language)
Headers should increment by one level at a time (MD001: Header Increment)
Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines)
Only one top-level header (H1) is allowed per document (MD025: Single H1 Header)
Use consistent list markers, preferring dashes (-) for unordered lists (MD004: List Style)
Nested unordered list items should be indented consistently, typically by 2 spaces (MD007: Unordered List Indentation)
Use exactly one space after the list marker (e.g., -, *, +, 1.) (MD030: Spaces After List Markers)
Use incrementing numbers for ordered lists (MD029: Ordered List Item Prefix)
Enclose bare URLs in angle brackets or format them as links (MD034: Bare URLs)
Don't use spaces immediately inside code spans (MD038: Spaces Inside Code Spans)
Use consistent indentation (usually 2 or 4 spaces) throughout markdown files
Keep line length under 120 characters in markdown files
Use reference-style links for better readability in markdown files
Use a trailing slash for directory paths in markdown files
Ensure proper escaping of special characters in markdown files

Files:

• openspec/changes/requirements-04-upstream-source-readiness/README.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• tests/fixtures/speckit/spec-template-v0.12.18.md
• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/CHANGE_ORDER.md
• openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• CHANGELOG.md
• docs/reference/requirements-context-adapter.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md
• openspec/changes/openspec-01-intent-trace/tasks.md

**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

• openspec/changes/requirements-04-upstream-source-readiness/README.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• tests/fixtures/speckit/spec-template-v0.12.18.md
• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/CHANGE_ORDER.md
• openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• CHANGELOG.md
• docs/reference/requirements-context-adapter.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md
• openspec/changes/openspec-01-intent-trace/tasks.md

openspec/changes/**/*.md

📄 CodeRabbit inference engine (.cursorrules)

For /opsx:archive (Archive change): Include module signing and cleanup in final tasks. Agents MUST run openspec archive <change-id> from repo root (no manual mv under openspec/changes/archive/)

Files:

• openspec/changes/requirements-04-upstream-source-readiness/README.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md
• openspec/changes/openspec-01-intent-trace/tasks.md

openspec/**/*.md

⚙️ CodeRabbit configuration file

openspec/**/*.md: Treat as specification source of truth: proposal/tasks/spec deltas vs. code behavior,
CHANGE_ORDER consistency, and scenario coverage. Surface drift between OpenSpec and
implementation.

Files:

• openspec/changes/requirements-04-upstream-source-readiness/README.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/CHANGE_ORDER.md
• openspec/changes/openspec-01-intent-trace/TDD_EVIDENCE.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md
• openspec/changes/openspec-01-intent-trace/tasks.md

openspec/**/{proposal.md,tasks.md,design.md,spec.md}

📄 CodeRabbit inference engine (.cursor/rules/automatic-openspec-workflow.mdc)

openspec/**/{proposal.md,tasks.md,design.md,spec.md}: Apply openspec/config.yaml project context and per-artifact rules (for proposal, specs, design, tasks) when creating or updating any OpenSpec change artifact in the specfact-cli codebase
After implementation, validate the change with openspec validate <change-id> --strict; fix validation errors in proposal, specs, design, or tasks and re-validate until passing before considering the change complete

Files:

• openspec/changes/requirements-04-upstream-source-readiness/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/openspec-01-intent-trace/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/specs/requirements-module/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/openspec-01-intent-trace/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/openspec-01-intent-trace/design.md
• openspec/changes/openspec-01-intent-trace/tasks.md

pyproject.toml

📄 CodeRabbit inference engine (.cursorrules)

When updating the version in pyproject.toml, ensure it's newer than the latest PyPI version. The CI/CD pipeline will automatically publish to PyPI only if the new version is greater than the published version

Files:

• pyproject.toml

**/test_*.py

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

**/test_*.py: Write tests first in test-driven development (TDD) using the Red-Green-Refactor cycle
Ensure each test is independent and repeatable with no shared state between tests
Organize Python imports in tests using unittest.mock for Mock and patch
Use setup_method() for test initialization and Arrange-Act-Assert pattern in test files
Use @pytest.mark.asyncio decorator for async test functions in Python
Organize test files in structure: tests/unit/, tests/integration/, tests/e2e/ by module

Files:

• tests/unit/workflows/test_trustworthy_green_checks.py
• tests/unit/requirements/test_upstream_evidence_imports.py

tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Tests must be meaningful and test actual functionality, cover both success and failure cases, be independent and repeatable, and have clear, descriptive names. NO EXCEPTIONS - no placeholder or empty tests.

tests/**/*.py: Trim low-value unit tests when a contract covers the same assertion (type/shape/raises on negative checks)
Delete tests that only assert input validation, datatype/shape enforcement, or raises on negative conditions now guarded by contracts and runtime typing
Convert repeated edge-case permutations into one Hypothesis property with contracts acting as oracles

Secret redaction via LoggerSetup.redact_secrets must be covered by unit tests

Files:

• tests/unit/workflows/test_trustworthy_green_checks.py
• tests/unit/requirements/test_upstream_evidence_imports.py

---

⚙️ CodeRabbit configuration file

tests/**/*.py: Contract-first testing: meaningful scenarios, not redundant assertions already covered by
contracts. Flag flakiness, environment coupling, and missing coverage for changed behavior.

Files:

• tests/unit/workflows/test_trustworthy_green_checks.py
• tests/unit/requirements/test_upstream_evidence_imports.py

.github/workflows/*.{yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Validate GitHub workflow files using hatch run lint-workflows before committing

.github/workflows/*.{yml,yaml}: Use actionlint for semantic validation of GitHub Actions workflows
Format GitHub Actions workflows using hatch run workflows-fmt and lint them with hatch run workflows-lint after editing

Files:

• .github/workflows/pr-orchestrator.yml

.github/workflows/!(tests).{yml,yaml}

📄 CodeRabbit inference engine (.cursor/rules/testing-and-build-guide.mdc)

Do not re-run the full test suite in other CI workflows; tests are enforced only in the dedicated Tests workflow (.github/workflows/tests.yml)

Files:

• .github/workflows/pr-orchestrator.yml

.github/workflows/**

⚙️ CodeRabbit configuration file

.github/workflows/**: CI safety: secrets usage, workflow dependencies, alignment with hatch test / contract-test
gates, and action versions.

Files:

• .github/workflows/pr-orchestrator.yml

CHANGELOG.md

📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)

Include new version entries at the top of CHANGELOG.md when updating versions

Update CHANGELOG.md with all code changes as part of version control requirements.

Update CHANGELOG.md to document all significant changes under Added, Fixed, Changed, or Removed sections when making a version change

Files:

• CHANGELOG.md

docs/**/*.md

📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)

Update architecture documentation in docs/ for architecture changes, state machine documentation for FSM modifications, interface documentation for API changes, and configuration guides for configuration changes. DO NOT create internal docs in specfact-cli repo folder that should not be visible to end users; use the respective internal repository instead.

Files:

• docs/reference/requirements-context-adapter.md

---

⚙️ CodeRabbit configuration file

docs/**/*.md: User-facing accuracy: CLI examples match current behavior; preserve Jekyll front matter;
call out when README/docs index need sync.

Files:

• docs/reference/requirements-context-adapter.md

🪛 ast-grep (0.44.1)

src/specfact_cli/requirements/importers.py

[error] 297-304: Command coming from incoming request
Context: subprocess.run(
["openspec", "validate", change_dir.name, "--strict", "--json"],
cwd=change_dir.parents[2],
capture_output=True,
check=False,
text=True,
timeout=_OPENSPEC_VALIDATOR_TIMEOUT_SECONDS,
)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)

---

[warning] 85-89: Regex pattern passed to re is built from a non-literal (variable, call, concatenation, or f-string) value. If that value is attacker-controlled it can introduce a malicious pattern with catastrophic backtracking (ReDoS). Use a hardcoded literal pattern, or validate/escape untrusted input with re.escape() and bound the regex complexity before compiling.
Context: re.search(
rf"^- **{clause.upper()}**\s+([^\n]+(?:\n[ \t]+[^\n]+)*)",
body,
re.MULTILINE | re.IGNORECASE,
)
Note: [CWE-1333] Inefficient Regular Expression Complexity.

(redos-non-literal-regex-python)

🪛 LanguageTool

openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md

[style] ~12-~12: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...blocking environment warnings:** pytest could not write its cache in the sandboxed feat...

(REP_COULD_NOT)

🔇 Additional comments (14)

src/specfact_cli/__init__.py (1)

79-79: 🗄️ Data Integrity & Integration

Verify all release metadata uses 0.53.1.

This version bump must be synchronized with src/__init__.py, pyproject.toml, setup.py, and CHANGELOG.md before release.

As per coding guidelines, src/__init__.py is the primary version source and package metadata must remain synchronized.

Source: Coding guidelines

src/specfact_cli/requirements/__init__.py (1)

13-16: 📐 Maintainability & Code Quality

No contract change needed for these exports. The public helpers re-exported here already have @beartype plus @require/@ensure, so exposing them in __all__ is fine.

			> Likely an incorrect or invalid review comment.

openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md (1)

57-64: 🎯 Functional Correctness

No issue: the selected-change argv is already pinned. CHANGE_VALIDATION.md already spells out openspec validate requirements-04-upstream-source-readiness --strict --json, and the spec/design/proposal wording here is descriptive rather than a different invocation contract.

			> Likely an incorrect or invalid review comment.

src/specfact_cli/requirements/importers.py (1)

1-387: LGTM!

Also applies to: 429-490, 500-501

src/specfact_cli/requirements/context.py (1)

5-53: LGTM!

Also applies to: 152-464, 468-543, 555-577

tests/fixtures/speckit/spec-template-v0.12.18.md (1)

1-132: LGTM!

tests/unit/requirements/test_upstream_evidence_imports.py (1)

1-30: LGTM!

Also applies to: 42-267, 387-551

.github/workflows/pr-orchestrator.yml (2)

646-646: LGTM!

---

655-657: 📐 Maintainability & Code Quality

Keep the line-coverage gate sourced from pyproject.toml. tool.coverage.report.fail_under is 50% here; the repo’s 80% thresholds are for contract coverage, not this workflow’s line-coverage check.

			> Likely an incorrect or invalid review comment.

CHANGELOG.md (1)

13-70: LGTM!

openspec/CHANGE_ORDER.md (1)

11-11: LGTM!

Also applies to: 41-41, 85-88, 114-116, 160-167

pyproject.toml (1)

7-7: LGTM!

setup.py (1)

10-10: LGTM!

src/__init__.py (1)

6-6: LGTM!

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 19.30s
Checks: 4 total (1 passed) (3 skipped)

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 19.08s
Checks: 4 total (1 passed) (3 skipped)

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 19.05s
Checks: 4 total (1 passed) (3 skipped)