feat(requirements): validate native source readiness

[djm81]

Summary

Implements core source-readiness validation for #648, paired with nold-ai/specfact-cli-modules#346.

• Rejects pristine or structurally incomplete Spec Kit sources before normalization.
• Adds profile- and layered-policy-gated native OpenSpec validation, with atomic diagnostics for failed, malformed, timed-out, and unavailable validators.
• Pins the byte-identical Spec Kit v0.12.18 scaffold fixture and preserves accepted-source IDs, hashes, scenarios, idempotency, and read-only behavior.
• Updates the OpenSpec contract, readiness documentation, quality evidence, and the required 0.53.0 feature version.

Validation

• hatch run test -- tests/unit/requirements/test_upstream_evidence_imports.py — 41 passed
• hatch run format, hatch run lint, hatch run yaml-lint, hatch run contract-test
• hatch run smart-test — full-suite evidence: 2,856 passed, 64% coverage (50% threshold)
• hatch run semgrep-sast, Semgrep baseline gate, and hatch run bandit-scan
• hatch run docs-validate
• openspec validate requirements-04-upstream-source-readiness --strict --json
• hatch run verify-modules-signature
• SpecFact code review: 0 findings

Follow-up

The paired modules release remains blocked on the published core version, as tracked by `nold-ai/specfact-cli-modules#346.

Fixes #648.

[github-actions]

SpecFact CLI Validation Report

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

[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: c106b030-c693-40d1-9021-c7d0c0123fc3

📥 Commits

Reviewing files that changed from the base of the PR and between ff77d25 and f901fec.

📒 Files selected for processing (12)

• .github/workflows/pr-orchestrator.yml
• CHANGELOG.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• pyproject.toml
• setup.py
• src/__init__.py
• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/importers.py
• 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 feature/requirements-04-upstream-source-readiness instead of the default branch

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

• src/init.py
• setup.py
• src/specfact_cli/init.py
• pyproject.toml
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• src/specfact_cli/requirements/importers.py
• tests/unit/requirements/test_upstream_evidence_imports.py

📜 Recent review details

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

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

🧰 Additional context used

📓 Path-based instructions (11)

**/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

**/*.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:

• tests/unit/workflows/test_trustworthy_green_checks.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

---

⚙️ 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

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

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

Linting must pass with no errors using: pylint src tests

Files:

• tests/unit/workflows/test_trustworthy_green_checks.py

**/*.{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:

• tests/unit/workflows/test_trustworthy_green_checks.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:

• CHANGELOG.md

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

**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

• CHANGELOG.md

.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

🔇 Additional comments (3)

CHANGELOG.md (1)

13-17: LGTM!

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

646-646: LGTM!

Also applies to: 657-657

tests/unit/workflows/test_trustworthy_green_checks.py (1)

215-217: LGTM!

---

📝 Walkthrough

User-visible behavior and CLI surface

• requirements import documents --from-openspec and --from-speckit.
• Native imports now reject incomplete Spec Kit sources and policy-invalid OpenSpec changes atomically, returning zero records with structured diagnostics.
• OpenSpec strict native validation runs only when enabled by profile/layered policy; portable imports do not probe ambient validators.
• Failed, malformed, timed-out, or unavailable validators produce named diagnostics while preserving source files, IDs, hashes, scenarios, and idempotency.

Contract/API impact

• Added and exported requires_native_openspec_validation(...).
• Extended import_openspec_change(...) with optional keyword-only profile and project_root parameters.
• No authoring-schema or Pydantic model changes; core retains readiness, policy, parsing, hashing, and diagnostics ownership.

Testing and quality gates

• Added coverage for scaffold/template detection, incomplete requirements and scenarios, strict OpenSpec validation failures, timeouts, unavailable validators, layered policy overrides, and non-probing portable imports.
• Updated quality-gate workflow to honor configured coverage thresholds directly and fail piped commands via pipefail.
• Validation evidence covers unit/contract/full-suite tests, formatting, linting, YAML and documentation checks, security scans, strict OpenSpec validation, signature verification, and code review.

OpenSpec, documentation, and release

• OpenSpec change: requirements-04-upstream-source-readiness.
• Added design, proposal, specification, tasks, validation report, and TDD evidence.
• Updated source-readiness documentation and CHANGELOG.md.
• Pinned the Spec Kit v0.12.18 scaffold fixture.
• Bumped package versions to 0.53.1.

Walkthrough

The PR adds atomic source-readiness checks for native OpenSpec and Spec Kit imports, policy-controlled validation, structured diagnostics, tests, documentation, workflow enforcement, release metadata, and OpenSpec sequencing records.

Changes

Native source-readiness

Layer / File(s)	Summary
Readiness contract and policy openspec/changes/requirements-04-upstream-source-readiness/...	Defines fail-closed readiness behavior, diagnostic codes, source preservation, Spec Kit completeness rules, and conditional strict OpenSpec validation.
Core importer readiness gates src/specfact_cli/requirements/context.py, src/specfact_cli/requirements/importers.py, src/specfact_cli/requirements/__init__.py	Adds public validation-policy resolution and readiness checks before native requirement normalization.
Fixtures and importer tests tests/fixtures/speckit/..., tests/unit/requirements/test_upstream_evidence_imports.py	Covers incomplete sources, validator failures, unavailable validators, configuration overrides, portability, diagnostics, and source immutability.
Traceability, documentation, quality gates, and release wiring llms.txt, openspec/CHANGE_ORDER.md, docs/reference/..., .github/workflows/..., CHANGELOG.md, pyproject.toml, setup.py, src/**/__init__.py	Updates command metadata, sequencing, documentation, validation evidence, coverage-gate behavior, changelog, and package versions to 0.53.1.

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

Possibly related issues

• nold-ai/specfact-cli-modules#346 — Covers the paired modules-side readiness contract and compatibility impact.

Possibly related PRs

• nold-ai/specfact-cli#632 — Provides the requirements context adapter extended by this PR.
• nold-ai/specfact-cli#634 — Provides related validation-profile behavior used by the new policy helper.
• nold-ai/specfact-cli#646 — Modifies the same upstream evidence import pipeline.

Suggested labels: QA, architecture, change-proposal

Suggested reviewers: repo-owners

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the summary, issue, and validation, but omits several required template sections and checklist details.	Add the missing template sections, including contract references, type of change, test environment, checklist items, and the prescribed testing subsections.
Out of Scope Changes check	⚠️ Warning	The PR includes unrelated CI/version/docs edits such as workflow threshold changes and llms.txt command-table updates beyond the source-readiness scope.	Split the nonessential workflow, versioning, and documentation updates into a separate PR unless they are required to deliver #648.
Docstring Coverage	⚠️ Warning	Docstring coverage is 56.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses a Conventional Commits-style prefix and clearly describes the main source-readiness change.
Linked Issues check	✅ Passed	The PR implements atomic readiness gating, named diagnostics, and portable import behavior aligned with #648's acceptance criteria.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/requirements-04-upstream-source-readiness

---

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

[github-actions]

SpecFact CLI Validation Report

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

[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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1feb0aee84

ℹ️ 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: 4

🤖 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 `@openspec/CHANGE_ORDER.md`:
- Line 11: Update the active-change count in openspec/CHANGE_ORDER.md so the
status snapshot and the active-track narrative agree on 19 active changes,
preserving the OpenSpec markdown as the source of truth.

In `@openspec/changes/requirements-04-upstream-source-readiness/design.md`:
- Around line 102-107: Define the upstream-validation policy contract in the
design/spec, including the explicit layered configuration key, precedence rules,
and strict/enterprise default mapping. Document when native “openspec validate
--strict --json” is mandatory versus when portable behavior is allowed, and add
scenarios covering each policy outcome.

In
`@openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md`:
- Around line 23-29: Define executable contract rules for “substantive
Functional Requirement” and “meaningful acceptance scenario” in the Spec Kit
evidence adapter specification, including exact section and marker requirements.
Add fixture mappings covering valid, incomplete, and scaffold-marked sources,
and document precedence when scaffold markers coexist with substantive content.
Ensure core and module `#346` classify identical inputs consistently and preserve
the source-incomplete diagnostic behavior.
- Around line 41-57: Extend the OpenSpec adapter specification with fail-closed
scenarios for validator timeouts, non-zero exits, malformed or empty JSON, and
zero-exit responses lacking a valid result. For each scenario, require zero
requirement records, an error diagnostic, and preservation of the source
directory without modifications; keep the existing invalid-change and
unavailable-validator behavior unchanged.

🪄 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: 378efcba-cf17-4ed7-a148-cbc601ff34b5

📥 Commits

Reviewing files that changed from the base of the PR and between d751a2d and 1feb0ae.

⛔ 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 (8)

• llms.txt
• openspec/CHANGE_ORDER.md
• openspec/changes/requirements-04-upstream-source-readiness/.openspec.yaml
• openspec/changes/requirements-04-upstream-source-readiness/README.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

🔗 Linked repositories identified

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

• nold-ai/specfact-cli-modules (manual) → reviewed against branch feature/requirements-04-upstream-source-readiness instead of the default branch

📜 Review details

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{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/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/CHANGE_ORDER.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.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/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/CHANGE_ORDER.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.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/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.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/proposal.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/CHANGE_ORDER.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.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/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md
• openspec/changes/requirements-04-upstream-source-readiness/design.md

🔇 Additional comments (8)

llms.txt (1)

120-120: LGTM!

openspec/CHANGE_ORDER.md (1)

86-87: LGTM!

Also applies to: 114-114, 166-167

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

1-5: LGTM!

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

1-4: LGTM!

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

1-64: LGTM!

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

1-58: LGTM!

Also applies to: 73-101

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

1-21: LGTM!

Also applies to: 31-39, 59-66

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

1-60: LGTM!

[github-actions]

SpecFact CLI Validation Report

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

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md`:
- Around line 26-36: The validation evidence must not claim release readiness
with insufficient coverage or missing required gates. In
openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md lines
26-36, raise total coverage to at least 80%, achieve 100% coverage for critical
paths, and record the required type-check, full-test, and smart-test commands
with passing results. In
openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
lines 7-13, retain “Validation Result: Pass” only after those requirements are
satisfied.

In `@src/specfact_cli/requirements/importers.py`:
- Around line 251-264: The Spec Kit readiness checks must enforce substantive
Functional Requirements and a valid acceptance scenario within a recognized
user-story block. Update the readiness logic around _SPECKIT_REQUIREMENT_PATTERN
and _speckit_rules to parse story blocks, reject placeholder-only FR content,
require at least one story with an in-block Given/When/Then scenario, and
prevent scenarios outside story blocks from satisfying readiness.

🪄 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: 9d73f61f-f76c-430b-bc81-c51722f3a8a6

📥 Commits

Reviewing files that changed from the base of the PR and between 1feb0ae and ff77d25.

📒 Files selected for processing (17)

• CHANGELOG.md
• docs/reference/requirements-context-adapter.md
• openspec/CHANGE_ORDER.md
• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.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/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

🔗 Linked repositories identified

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

• nold-ai/specfact-cli-modules (manual) → reviewed against branch feature/requirements-04-upstream-source-readiness instead of the default branch

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

• openspec/changes/requirements-04-upstream-source-readiness/design.md
• openspec/changes/requirements-04-upstream-source-readiness/tasks.md
• openspec/CHANGE_ORDER.md

📜 Review details

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

• GitHub Check: Package Runtime Matrix (hatch-source)
• GitHub Check: Type Checking (basedpyright)
• GitHub Check: Runtime Discovery Smoke (macOS)
• GitHub Check: Linting (ruff, pylint, safe-write guard)
• GitHub Check: Tests (Python 3.12)
• GitHub Check: Contract-First CI
• GitHub Check: Independent Static Analysis
• GitHub Check: CLI Command Validation
• GitHub Check: Compatibility (Python 3.11)

🧰 Additional context used

📓 Path-based instructions (17)

**/*.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
• setup.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/__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
• pyproject.toml
• setup.py

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/requirements/__init__.py
• src/specfact_cli/__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/requirements/__init__.py
• src/specfact_cli/__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
• pyproject.toml
• setup.py

**/*.{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
• setup.py
• src/specfact_cli/requirements/__init__.py
• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py
• tests/unit/requirements/test_upstream_evidence_imports.py

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

**/*.{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/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• docs/reference/requirements-context-adapter.md
• tests/fixtures/speckit/spec-template-v0.12.18.md
• CHANGELOG.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md

**/*.md

📄 CodeRabbit inference engine (.cursorrules)

Avoid markdown linting errors (refer to markdown-rules)

Files:

• openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• docs/reference/requirements-context-adapter.md
• tests/fixtures/speckit/spec-template-v0.12.18.md
• CHANGELOG.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.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/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.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/CHANGE_VALIDATION.md
• openspec/changes/requirements-04-upstream-source-readiness/TDD_EVIDENCE.md
• openspec/changes/requirements-04-upstream-source-readiness/specs/openspec-speckit-evidence-adapter/spec.md

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/requirements/__init__.py
• src/specfact_cli/__init__.py
• src/specfact_cli/requirements/context.py
• src/specfact_cli/requirements/importers.py

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

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

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/specs/openspec-speckit-evidence-adapter/spec.md

**/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/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/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/requirements/test_upstream_evidence_imports.py

🪛 ast-grep (0.44.1)

src/specfact_cli/requirements/importers.py

[error] 276-283: 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)

🪛 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 (11)

CHANGELOG.md (1)

13-22: LGTM!

docs/reference/requirements-context-adapter.md (1)

15-15: LGTM!

Also applies to: 67-90

openspec/changes/requirements-04-upstream-source-readiness/CHANGE_VALIDATION.md (2)

56-58: 🗄️ Data Integrity & Integration

Track the paired-module handoff before release.

The report says the sibling repository has no mirror and leaves tracking conditional. Because this PR is paired with specfact-cli-modules#346, verify that its release is pinned to core 0.53.0 and consumes these readiness diagnostics before publishing.

As per path instructions, OpenSpec validation artifacts must record dependent file updates and evidence for release coordination.

Source: Path instructions

---

1-6: LGTM!

Also applies to: 14-55, 59-59

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

1-25: LGTM!

Also applies to: 37-37

pyproject.toml (1)

7-7: LGTM!

setup.py (1)

10-10: LGTM!

src/__init__.py (1)

6-6: LGTM!

src/specfact_cli/__init__.py (1)

79-79: LGTM!

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

420-422: 🎯 Functional Correctness

import_speckit_feature already has the same boundary checks as import_openspec_change.
Nothing to add here.

			> Likely an incorrect or invalid review comment.

---

313-324: 🎯 Functional Correctness

OpenSpec validate output already matches this predicate. openspec validate --json uses items[*].id with valid, so this parser isn’t rejecting valid imports on a schema mismatch.

			> Likely an incorrect or invalid review comment.

[github-actions]

SpecFact CLI Validation Report

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