Conversation
…228) * fix: harden backlog refine prompt scaffold and parsing * fix: normalize mixed notes parsing and boundary flushing --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
GitHub's licensee gem only recognizes standard filenames (LICENSE, LICENSE.txt) — LICENSE.md caused the repo to show "Other" instead of "Apache License 2.0". Updated all references across pyproject.toml, README, docs, workflows, and FAQ. Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
) The LICENSE body had two non-standard edits that pushed it below GitHub licensee's ~95% similarity threshold, causing "Other" instead of "Apache License 2.0". Restored the canonical text; only the copyright line in the appendix is customized (as intended by the Apache template). Signed-off-by: Dom <39115308+djm81@users.noreply.github.com> Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
…#262) * feat(ci): attach test and repro log artifacts to PR orchestrator runs - Tests job: run smart-test-full, upload logs/tests/ as test-logs artifact - Contract-first-ci: capture repro to logs/repro/, upload repro-logs and repro-reports - Docs: CI and GitHub Actions section in troubleshooting (artifact names, usage) - Version 0.31.1, CHANGELOG entry Implements OpenSpec change ci-01-pr-orchestrator-log-artifacts. Fixes #260. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix workflow and test * ci(pr-orchestrator): add log artifacts for all pipeline jobs - type-check: capture output to logs/type-check/, upload type-check-logs - lint: capture to logs/lint/, upload lint-logs - compat-py311: capture to logs/compat-py311/, upload compat-py311-logs - quality-gates: capture to logs/quality-gates/, upload quality-gates-logs - compat-py311: use hatch -e ENV run run (not hatch test) for pytest - docs: list all CI artifact names and jobs in troubleshooting Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: enhanced module manifest security and integrity (arch-06) Co-authored-by: Cursor <cursoragent@cursor.com> * fix: remove duplicate ModulePackageMetadata import (ruff F811) * Fix failed tests * Fix type-check errors --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
…rch-07) (#265) * feat: add schema extension system for modular ProjectBundle extensions Enables modules to extend Feature and ProjectBundle with namespaced custom fields without modifying core models, supporting marketplace-ready interoperability. - Add extensions dict field to Feature and ProjectBundle models - Implement type-safe get/set extension accessors with namespace enforcement - Extend module manifest schema with schema_extensions declaration - Add ExtensionRegistry for collision detection and introspection - Extend module lifecycle registration to load and validate extensions OpenSpec Change: arch-07-schema-extension-system Resolves #213 * feat: schema extension system (arch-07) and quality gate fixes - Add extensions field and get_extension/set_extension to Feature and ProjectBundle - Add SchemaExtension model and schema_extensions to ModulePackageMetadata - Add ExtensionRegistry with collision detection; integrate in module registration - Parse schema_extensions in discover_package_metadata - Docs: extending-projectbundle guide, architecture section, sidebar - Version 0.32.0, CHANGELOG entry, TDD_EVIDENCE - Format: E402 (imports at top in project.py), UP042 (StrEnum in backlog-core), RUF043/B017 in schema extension tests - Type-check: pass schema_metadata/project_metadata in BundleManifest test calls OpenSpec Change: arch-07-schema-extension-system Resolves #213 Co-authored-by: Cursor <cursoragent@cursor.com> * Update change progress * Add docs guides and update changes * Use v0.32.0 as version and combine arch-06/arch-07 * Update change order plan --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
* feat(workflow): standardize worktree-first development flow * docs(openspec): mark workflow-01 delivery tasks complete * Apply review finding --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat(policy-engine): implement unified policy framework * docs(openspec): mark policy-engine-01 implemented in change order * fix(policy-engine): make module io contract compliant * feat(policy-engine): add policy init templates and docs coverage * fix: refine grouped policy limit semantics and outputs * docs: clarify policy engine value for new users --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* docs: sharpen first-contact story and onboarding * docs: address first-contact review feedback * docs: address onboarding review fixes * test: accept default-filtered site tokens in docs parity * docs: record completed onboarding quality gates * test: improve first-contact assertion failures --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughSpecFact CLI — Release: First-Contact Story & Onboarding (v0.43.3)User-visible behavior & CLI surface
Contract / API impact
Testing & quality gates
OpenSpec, docs & CHANGELOG
Module signing / version bumps
SummaryThis release is documentation-first: it overhauls first-contact messaging and onboarding across repository and docs surfaces, introduces OpenSpec specs and TDD evidence for the change, and hardens internal utilities to fail closed on pathological inputs. There are no public API or CLI behavior changes; package version incremented to 0.43.3. Test runs and documented quality gates for the change are recorded as passing in the TDD evidence, with a few unrelated runtime/CLI checklist items still unchecked. WalkthroughReframes first-contact surfaces (README, docs landing, CONTRIBUTING, modules handoff) to present SpecFact as a “validation and alignment layer for software delivery”, adds a required messaging hierarchy and fast-start routing, introduces OpenSpec artifacts for the change, and hardens CI/tests and parser/utility helpers to fail-closed on pathological inputs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 2 | ❌ 3❌ Failed checks (3 warnings)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
djm81
added
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 11391c953d
ℹ️ 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[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/ci-02-trustworthy-green-checks/proposal.md`:
- Line 14: Wrap the long markdown bullet(s) so no line exceeds 120 characters:
split the sentence beginning with "**EXTEND** required-check triggering
semantics..." into multiple wrapped lines while keeping the list marker and
bolded "**EXTEND**" intact and preserving the original meaning/punctuation; do
the same for the other occurrence mentioned (the line at 35) so all markdown
lines comply with the 120-character limit.
In `@openspec/changes/docs-14-first-contact-story-and-onboarding/proposal.md`:
- Around line 49-50: The bullet "- **POSITION** the future enterprise
policy-management path..." has an extra leading space before the hyphen causing
inconsistent list indentation; remove the leading space so the hyphen starts at
the same column as other top-level bullets (or re-indent all top-level bullets
consistently), locating the line by searching for the phrase "**POSITION**" and
adjusting that list item's indentation to match the other top-level entries.
In
`@openspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.md`:
- Around line 29-53: Update the unit tests in
tests/unit/docs/test_first_contact_story.py to assert the semantic requirements
rather than just keyword presence: in the brownfield scenario (previously
asserting "brownfield") add assertions that the rendered content contains one of
the spec-first handoff markers ("spec-first", "OpenSpec", or "Spec-Kit") and
that it describes handing structured insight to spec tooling; in the modules
landing scenario (previously asserting "modules.specfact.io") add assertions
that docs/index.md (or the rendered core landing content) includes explicit
redirect/orientation language such as "default starting point" or an instruction
to return to core docs/getting-started so un-oriented users are guided back.
Ensure the tests reference the same fixtures/parsers used by existing tests so
only the assertion strings change.
In
`@openspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.md`:
- Around line 6-11: Add a single blank line immediately before the unordered
list that begins with "the first-contact questions in a consistent order:" in
the first-contact story document so the list is separated from the preceding
paragraph and complies with MD032; locate the block containing that sentence
(the first-contact questions list) in spec.md and insert one empty line above
it.
- Around line 39-45: The markdown list beginning with "- **THEN** the page SHALL
explain that SpecFact addresses:" and its subsequent bullet lines must be
preceded by a blank line to satisfy MD032; edit the spec.md content to insert a
single blank line immediately before that list so the list is separated from the
preceding paragraph (no other changes required).
- Around line 70-80: Add an explicit cross-repo traceability note after the
"Requirement: Repo metadata reinforces the same story" block: mention that the
modules documentation site (modules.specfact.io / nold-ai/specfact-cli-modules
docs/index.md) SHALL either present the same first-contact story or provide an
explicit handoff to the core docs, and reference documentation-alignment/spec.md
for cross-site wording/ownership guidance so maintainers updating this spec see
the modules impact; insert the note immediately after the existing requirement
text and keep wording normative (SHALL) and concise.
- Around line 31-46: The tests lack explicit assertions that the README/docs
"Why does it exist?" section frames SpecFact around the four product pressures;
update the test suite by adding assertions in
test_readme_leads_with_validation_and_alignment_story,
test_readme_routes_users_by_outcome, and/or
test_docs_index_matches_first_contact_story to check that the README/docs
include the four pressures—AI-assisted (validation/vibe-coded changes),
brownfield reverse-engineering, backlog/spec/code drift, and team/enterprise
policy enforcement—and that the text presents them as reasons the product exists
(not merely a feature list); ensure the assertions verify the exact presence of
those four phrase groups or canonical synonyms and fail if any are missing.
In `@tests/unit/docs/test_first_contact_story.py`:
- Around line 88-101: The test test_docs_index_matches_first_contact_story
currently only checks for the word "brownfield" in docs_index; update this test
to also assert the required spec-first handoff language per the spec by adding
an assertion that docs_index (the variable read from DOCS_INDEX) contains either
"spec-first" or "openspec" or "spec-kit" (all checked case-insensitively, e.g.
using docs_index.lower()); keep the existing checks (_assert_question_order,
other assertions) and place the new assertion alongside them in
test_docs_index_matches_first_contact_story.
- Around line 11-19: The module-level assertions using REPO_ROOT, README,
DOCS_INDEX, and CONTRIBUTING cause import-time failures; move those checks into
a test or fixture that can skip the test instead. Replace the top-level assert
statements with a session- or module-scoped pytest fixture (or a first test)
that checks REPO_ROOT.exists() and each .is_file() for README, DOCS_INDEX and
CONTRIBUTING and calls pytest.skip() with a clear message when any are missing,
so missing docs produce skipped tests rather than collection errors.
In `@tests/unit/docs/test_release_docs_parity.py`:
- Around line 134-151: The regex in _resolve_site_token_link uses a nested
quantifier (the group around the pipe handling) which can cause exponential
backtracking; update the pattern used in the re.search call (the pattern that
produces match) to avoid a ".*?" inside a repeated group by restricting the
pipe-group to not consume closing-brace characters (e.g., replace the inner
".*?" with a character-class that excludes '}' or otherwise ensure the
pipe-handling is non-backtracking), so match reliably without exponential
backtracking and then keep the rest of the function logic (key, config lookup,
suffix handling) 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: ASSERTIVE
Plan: Pro
Run ID: fd0b2b4f-04df-4910-be22-062728fa6a0d
📒 Files selected for processing (21)
CONTRIBUTING.mdREADME.mddocs/README.mddocs/index.mddocs/reference/documentation-url-contract.mdopenspec/CHANGE_ORDER.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamlopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdtests/unit/docs/test_first_contact_story.pytests/unit/docs/test_release_docs_parity.pytests/unit/test_core_docs_site_contract.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (13)
**/*.md
📄 CodeRabbit inference engine (.cursorrules)
**/*.md: Finish each output by listing which rulesets have been applied (e.g.,.cursorrules,AGENTS.md, specific.cursor/rules/*.mdc), confirm Git Worktree Policy compliance if applicable, and state the AI provider and model version being used.
Follow markdown linting rules to avoid markdown linting errors (via markdown-rules).
Files:
docs/reference/documentation-url-contract.mdopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
docs/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
Preserve all front-matter in documentation files when editing (title, layout, nav_order, permalink, etc.); check
docs/_layouts/default.htmlanddocs/index.mdbefore modifying front-matterUpdate 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.
Update docs in
docs/when commands, options, or behaviour changes; preserve all front-matter on every edit
Files:
docs/reference/documentation-url-contract.mddocs/README.mddocs/index.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/documentation-url-contract.mddocs/README.mddocs/index.md
**/*.{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:
docs/reference/documentation-url-contract.mdopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/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/ci-02-trustworthy-green-checks/proposal.mdopenspec/CHANGE_ORDER.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
openspec/CHANGE_ORDER.md
📄 CodeRabbit inference engine (CLAUDE.md)
Update
openspec/CHANGE_ORDER.mdwhenever a change lifecycle event occurs (new change created, archived, modified, blocker resolved) in the same commitKeep
openspec/CHANGE_ORDER.mdupdated as the single source of truth for change sequencing, module grouping, and inter-change dependencies
Files:
openspec/CHANGE_ORDER.md
**/*.py
📄 CodeRabbit inference engine (.cursorrules)
**/*.py: All public APIs must have@icontractdecorators and@beartypetype checking.
Commands should follow typer patterns with rich console output.
Use Pydantic models for all data structures to ensure data validation.
Write only high-value comments if at all. Avoid talking to the user through comments.
Use GPG-signed commits (git commit -S) when implementing changes in a worktree.
**/*.py: Usesnake_casefor file and module names
UsePascalCasefor class names
UseUPPER_SNAKE_CASEfor constants
Use Google-style docstrings
Set line length to 120 characters maximum
All data structures must use PydanticBaseModelwithField(...)and descriptions
All public APIs must use@icontractdecorators (@require,@ensure,@invariant) for contract-first development
All public APIs must use@beartypefor runtime type checking
Only write high-value comments; avoid verbose or redundant commentary
**/*.py: No bare except or broad except Exception without re-raising or logging full context - use specific exceptions instead
Enforce consistent return types for public API methods - publishing/IO methods must return bool (True/False), not None
Prefer specific exceptions and re-raise after logging rather than swallowing exceptions
Limit function length to maximum 120 lines and cyclomatic complexity to maximum 12
Avoid filesystem operations with overly permissive modes - do not use 0o777 for mkdir/os.makedirs; use 0o755 or environment-controlled mode
Async / signal safety - signal handlers may only set a flag or call thread-safe routines; do not call asyncio.create_task directly from POSIX signal handlers
**/*.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-o...
Files:
tests/unit/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.py
tests/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
tests/**/*.py: Test structure must mirror source withtests/unit/,tests/integration/,tests/e2e/directories
Use@pytest.mark.asynciodecorator for async test functions
Guard environment-sensitive logic withos.environ.get("TEST_MODE") == "true"
tests/**/*.py: Secure secret redaction guaranteed - LoggerSetup.redact_secrets must be covered by unit tests for nested dicts and strings
Messaging coercion and strict validation - any use of MessagingStandardization.process_standardized_message must have tests validating coercion success/failure and metrics incrementsTests 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
tests/**/*.py: Use@pytest.mark.asynciofor async tests
Guard environment-sensitive logic withos.environ.get("TEST_MODE") == "true"
Test structure must mirror source structure:tests/unit/,tests/integration/,tests/e2e/
Files:
tests/unit/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.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/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.py
**/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.asynciodecorator for async test functions in Python
Organize test files in structure: tests/unit/, tests/integration/, tests/e2e/ by module
Files:
tests/unit/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.py
{src,tests}/**/*.py
📄 CodeRabbit inference engine (.cursor/rules/session_startup_instructions.mdc)
Apply
pylint src testsfor linting before committing
Files:
tests/unit/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.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/test_core_docs_site_contract.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.py
{README.md,docs/index.md}
📄 CodeRabbit inference engine (AGENTS.md)
Keep
README.mdand the docs landing page in sync with actual CLI interface and command list; lead with value and USP for new-user perspective
Files:
docs/index.mdREADME.md
openspec/changes/*/TDD_EVIDENCE.md
📄 CodeRabbit inference engine (AGENTS.md)
Create/update
openspec/changes/<change-id>/TDD_EVIDENCE.mdwith test command(s), timestamp, and failure/pass summary before and after implementation
Files:
openspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
@(README.md|AGENTS.md)
📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)
Check README.md and AGENTS.md for current project status and development guidelines. Review .cursor/rules/ for detailed development standards and testing procedures.
Files:
README.md
🧠 Learnings (42)
📓 Common learnings
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: After code implementation in specfact-cli, create or update corresponding GitHub issue with title `[Change] <Brief Description>`, labels `enhancement` and `change-proposal` if targeting public repo, and update `proposal.md` Source Tracking section with issue number, URL, repository, and status
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Read and apply `openspec/config.yaml` for project context (tech stack, constraints, architecture, SDD+TDD discipline) before any code modification in specfact-cli
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to {README.md,docs/index.md} : Keep `README.md` and the docs landing page in sync with actual CLI interface and command list; lead with value and USP for new-user perspective
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Ensure an OpenSpec change (new or delta) exists for any code modification in specfact-cli (`src/`, `tools/`, tests, or significant docs) unless user explicitly opts out with 'skip openspec', 'direct implementation', 'simple fix', or similar
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: When creating OpenSpec changes for specfact-cli, use unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas in `changes/<id>/specs/<capability>/spec.md`
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to openspec/CHANGE_ORDER.md : Keep `openspec/CHANGE_ORDER.md` updated as the single source of truth for change sequencing, module grouping, and inter-change dependencies
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamldocs/reference/documentation-url-contract.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: When creating OpenSpec changes for specfact-cli, use unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas in `changes/<id>/specs/<capability>/spec.md`
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamldocs/reference/documentation-url-contract.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Ensure an OpenSpec change (new or delta) exists for any code modification in specfact-cli (`src/`, `tools/`, tests, or significant docs) unless user explicitly opts out with 'skip openspec', 'direct implementation', 'simple fix', or similar
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamlopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:31:22.997Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:22.997Z
Learning: Applies to openspec/CHANGE_ORDER.md : Update `openspec/CHANGE_ORDER.md` whenever a change lifecycle event occurs (new change created, archived, modified, blocker resolved) in the same commit
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamlopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Before modifying application code, follow the OpenSpec workflow in `.cursor/rules/automatic-openspec-workflow.mdc`: read and apply `openspec/config.yaml`, ensure an OpenSpec change (new or delta) exists and is validated, then implement. Exception: only when the user explicitly says 'skip openspec', 'direct implementation', 'simple fix', or similar.
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yaml
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Read and apply `openspec/config.yaml` for project context (tech stack, constraints, architecture, SDD+TDD discipline) before any code modification in specfact-cli
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/.openspec.yamlCONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mddocs/index.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:32:57.944Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/spec-fact-cli-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:57.944Z
Learning: Applies to docs/**/*.md : 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.
Applied to files:
docs/reference/documentation-url-contract.mdopenspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/CHANGE_ORDER.mdCONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.mdtests/unit/docs/test_release_docs_parity.pyopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Applies to **/*.md : Finish each output by listing which rulesets have been applied (e.g., `.cursorrules`, `AGENTS.md`, specific `.cursor/rules/*.mdc`), confirm Git Worktree Policy compliance if applicable, and state the AI provider and model version being used.
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Verify that an active OpenSpec change in `openspec/changes/` explicitly covers any requested code modification before applying edits
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.md
📚 Learning: 2026-03-25T21:31:47.109Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/clean-code-principles.mdc:0-0
Timestamp: 2026-03-25T21:31:47.109Z
Learning: Enforce pre-commit and CI gating with checks for: black, isort, mypy, flake8 (with B/C plugins), radon complexity, state-machine sync tests, and rejection of PRs lacking test files when src/ is modified
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Before executing any workflow command (`/opsx:ff`, `/opsx:apply`, `/opsx:continue`, etc.), perform a pre-execution checklist: verify Git Worktree creation, TDD evidence documentation, user-facing documentation updates, module signing verification, and confirm AGENTS.md compliance.
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: When creating implementation plans or OpenSpec tasks.md, explicitly verify and include: worktree creation from `origin/dev`, `hatch env create` in the worktree, pre-flight checks (`hatch run smart-test-status`, `hatch run contract-test-status`), and worktree cleanup steps post-merge.
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: After code implementation in specfact-cli, create or update corresponding GitHub issue with title `[Change] <Brief Description>`, labels `enhancement` and `change-proposal` if targeting public repo, and update `proposal.md` Source Tracking section with issue number, URL, repository, and status
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/proposal.mdCONTRIBUTING.mdopenspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.md
📚 Learning: 2026-03-25T21:32:38.156Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/session_startup_instructions.mdc:0-0
Timestamp: 2026-03-25T21:32:38.156Z
Learning: Review `docs/README.md` to understand current development phase and priorities before proceeding with work
Applied to files:
openspec/CHANGE_ORDER.mdCONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to {README.md,docs/index.md} : Keep `README.md` and the docs landing page in sync with actual CLI interface and command list; lead with value and USP for new-user perspective
Applied to files:
CONTRIBUTING.mddocs/README.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/documentation-alignment/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/entrypoint-onboarding/spec.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/proposal.mdREADME.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/specs/first-contact-story/spec.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/design.md
📚 Learning: 2026-03-25T21:33:15.296Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/testing-and-build-guide.mdc:0-0
Timestamp: 2026-03-25T21:33:15.296Z
Learning: Applies to CHANGELOG.md : Update CHANGELOG.md to document all significant changes under Added, Fixed, Changed, or Removed sections when making a version change
Applied to files:
CONTRIBUTING.mdREADME.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: For new code in specfact-cli using OpenSpec workflow, follow TDD discipline: write tests first, then implementation code
Applied to files:
CONTRIBUTING.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mddocs/index.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.md
📚 Learning: 2026-03-25T21:31:47.109Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/clean-code-principles.mdc:0-0
Timestamp: 2026-03-25T21:31:47.109Z
Learning: Code changes modifying public API, state machine YAMLs, or generated state machine outputs MUST include unit tests, update docs/ and CHANGELOG.md, and include 'BREAKING' section in PR if public API changed
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdtests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-25T21:33:15.296Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/testing-and-build-guide.mdc:0-0
Timestamp: 2026-03-25T21:33:15.296Z
Learning: Applies to .github/workflows/{quality-gates,contract-enforcement,contracts,no-escape-gating,integrated-ci}.{yml,yaml} : Dependent workflows must download the coverage.xml artifact from the Tests workflow and fail early if it is missing
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.mdopenspec/changes/ci-02-trustworthy-green-checks/design.md
📚 Learning: 2026-03-25T21:33:22.650Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/yaml-and-workflows.md:0-0
Timestamp: 2026-03-25T21:33:22.650Z
Learning: Run `hatch run yaml-check-all` in CI and before pull requests to validate all YAML and workflow files
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/specs/trustworthy-green-checks/spec.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to docs/**/*.md : Update docs in `docs/` when commands, options, or behaviour changes; preserve all front-matter on every edit
Applied to files:
docs/README.mddocs/index.md
📚 Learning: 2026-03-25T21:31:22.997Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:22.997Z
Learning: Applies to src/specfact_cli/modules/**/module-package.yaml : Each module in `src/specfact_cli/modules/{name}/` must contain a `module-package.yaml` file with metadata (name, version, commands, dependencies) and a `src/{name}/main.py` file with typer.Typer command definitions
Applied to files:
docs/README.mddocs/index.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Use lazy-loaded module registry in `src/specfact_cli/modules/` with `module-package.yaml` metadata files and deferred imports until command invocation
Applied to files:
docs/README.mddocs/index.mdREADME.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Applies to **/*.{py} : After any code changes, apply linting and formatting using `hatch run format`, perform type checking with `hatch run type-check` (basedpyright), run contract validation with `hatch run contract-test`, and run full test suite with `hatch test --cover -v`. Verify all tests pass and contracts are satisfied before committing.
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/design.md
📚 Learning: 2026-03-25T21:32:57.944Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/spec-fact-cli-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:57.944Z
Learning: Applies to src/**/*.py : 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.
Applied to files:
openspec/changes/ci-02-trustworthy-green-checks/design.mdtests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to openspec/changes/*/TDD_EVIDENCE.md : Create/update `openspec/changes/<change-id>/TDD_EVIDENCE.md` with test command(s), timestamp, and failure/pass summary before and after implementation
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:22.997Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:22.997Z
Learning: Implement strict TDD order: update/add spec deltas first → add/modify tests mapped to spec scenarios → run tests and capture failing result → only then modify production code → re-run tests and quality gates until passing; record evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Applies to TDD_EVIDENCE.md : For tasks involving behavior changes, create and update `TDD_EVIDENCE.md` per AGENTS.md 'Hard Gate: Strict TDD Order', recording failing test evidence before implementation and passing test evidence after implementation.
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.mdopenspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Update or add spec deltas first, then add/modify tests mapped to spec scenarios, capture failing test results before implementation, only then modify production code
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/tasks.mdopenspec/changes/ci-02-trustworthy-green-checks/tasks.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to src/specfact_cli/modules/*/module-package.yaml : Increment module version using semver (major/minor/patch) before signing changed module contents; do not keep the same module version when module files or signatures change
Applied to files:
docs/index.md
📚 Learning: 2026-03-25T21:31:55.908Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/estimation-bias-prevention.mdc:0-0
Timestamp: 2026-03-25T21:31:55.908Z
Learning: Use TDD with quality gates (contract-driven, test-driven implementation, quality gate validation, documentation) as the standard development pattern
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: After implementing code changes in specfact-cli, run quality gates: `hatch run format`, `hatch run type-check`, `hatch run contract-test`, `hatch test` (or `hatch run smart-test`)
Applied to files:
openspec/changes/docs-14-first-contact-story-and-onboarding/TDD_EVIDENCE.mdREADME.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Run `openspec validate <change-id> --strict` before implementing any code changes in specfact-cli to validate the OpenSpec change
Applied to files:
README.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: All development work must use git worktrees per AGENTS.md Git Worktree Policy. Create worktree from origin/dev using `git worktree add ../specfact-cli-worktrees/<type>/<slug> -b <branch-name> origin/dev`. Allowed types: `feature/`, `bugfix/`, `hotfix/`, `chore/`. Never use `git checkout -b` in primary checkout.
Applied to files:
README.md
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Use Bridge pattern for tool integrations (GitHub, Azure DevOps, Jira, Linear) in `src/specfact_cli/adapters/`
Applied to files:
README.md
📚 Learning: 2026-03-25T21:31:22.997Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:22.997Z
Learning: Applies to {pyproject.toml,setup.py,src/specfact_cli/__init__.py} : Sync version updates across `pyproject.toml`, `setup.py`, and `src/specfact_cli/__init__.py`
Applied to files:
README.md
📚 Learning: 2026-03-25T21:31:47.109Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/clean-code-principles.mdc:0-0
Timestamp: 2026-03-25T21:31:47.109Z
Learning: Applies to tests/**/*.py : Messaging coercion and strict validation - any use of MessagingStandardization.process_standardized_message must have tests validating coercion success/failure and metrics increments
Applied to files:
tests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-25T21:32:57.944Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/spec-fact-cli-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:57.944Z
Learning: Applies to src/**/*.py : 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.
Applied to files:
tests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-25T21:31:22.997Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:22.997Z
Learning: Applies to tests/**/*.py : Test structure must mirror source with `tests/unit/`, `tests/integration/`, `tests/e2e/` directories
Applied to files:
tests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-30T00:25:28.054Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-30T00:25:28.054Z
Learning: Applies to tests/**/*.py : Test structure must mirror source structure: `tests/unit/`, `tests/integration/`, `tests/e2e/`
Applied to files:
tests/unit/docs/test_first_contact_story.py
📚 Learning: 2026-03-25T21:32:29.182Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/python-github-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:29.182Z
Learning: Applies to **/test_*.py : Organize test files in structure: tests/unit/, tests/integration/, tests/e2e/ by module
Applied to files:
tests/unit/docs/test_first_contact_story.py
🪛 GitHub Check: CodeQL
tests/unit/test_core_docs_site_contract.py
[failure] 45-45: Incomplete URL substring sanitization
The string https://modules.specfact.io/ may be at an arbitrary position in the sanitized URL.
tests/unit/docs/test_release_docs_parity.py
[failure] 138-138: Inefficient regular expression
This part of the regular expression may cause exponential backtracking on strings starting with '{{{{site.0|' and containing many repetitions of '|'.
[failure] 350-350: Incomplete URL substring sanitization
The string modules.specfact.io may be at an arbitrary position in the sanitized URL.
tests/unit/docs/test_first_contact_story.py
[failure] 100-100: Incomplete URL substring sanitization
The string modules.specfact.io may be at an arbitrary position in the sanitized URL.
🪛 LanguageTool
openspec/changes/ci-02-trustworthy-green-checks/proposal.md
[uncategorized] ~35-~35: The official name of this software platform is spelled with a capital “H”.
Context: ...aming consistency for checks emitted by .github/workflows/pr-orchestrator.yml and `.gi...
(GITHUB)
[uncategorized] ~35-~35: The official name of this software platform is spelled with a capital “H”.
Context: ...thub/workflows/pr-orchestrator.ymland.github/workflows/sign-modules.yml`. - **Affect...
(GITHUB)
openspec/changes/ci-02-trustworthy-green-checks/tasks.md
[uncategorized] ~43-~43: The official name of this software platform is spelled with a capital “H”.
Context: ...mandatory workflow validation in CI for .github/workflows/** changes. - [ ] 4.4 Rework...
(GITHUB)
🔀 Multi-repo context nold-ai/specfact-cli-modules
Linked repositories findings
nold-ai/specfact-cli-modules
-
docs/reference/documentation-url-contract.md — canonical handoff table and explicit rules for core↔modules linking; contains many absolute modules.specfact.io targets that core changes reference. [::nold-ai/specfact-cli-modules::docs/reference/documentation-url-contract.md: lines ~5,19–20,51–69]
-
docs/_config.yml — site-level canonical URLs referencing core and modules hosts (docs_home_url, modules_docs_url). These must remain consistent with core repo wording/links. [::nold-ai/specfact-cli-modules::docs/_config.yml: lines 4–7]
-
docs/index.md — modules site landing copy that currently states “The modules site owns all bundle-specific deep guidance. Core CLI platform docs remain at https://docs.specfact.io.” The PR in specfact-cli changes core wording/handoff; ensure this modules index still follows the new first-contact handoff contract and redirects/orients newcomers as required. [::nold-ai/specfact-cli-modules::docs/index.md: lines 1–20, 22–40]
-
tests/unit/test_modules_docs_site_contract.py — unit tests assert config values and URL strings for modules/core hosts and may enforce the URL contract; these tests could fail if core repo changes alter canonical host strings or expected phrasing. [::nold-ai/specfact-cli-modules::tests/unit/test_modules_docs_site_contract.py: lines 9–27]
-
scripts/check-docs-commands.py & tests/unit/test_check_docs_commands_script.py — contain logic and test fixtures validating allowed core/docs links (CORE_DOCS_HOST constant and validation messages). They may need to accept or validate new core phrasing or new handoff behavior mandated by the PR. [::nold-ai/specfact-cli-modules::scripts/check-docs-commands.py: lines ~20, 269–288; ::tests/unit/test_check_docs_commands_script.py:: lines ~106–107]
-
docs/_layouts/default.html — header links to docs.specfact.io and modules.specfact.io (visible navigation that must align with new entry-point narrative). [::nold-ai/specfact-cli-modules::docs/_layouts/default.html: lines 219–220]
-
Multiple docs mentioning “brownfield”, “Start Here”, and handoff guides (getting-started, bundles, guides) — these content locations are consumers of core's first-contact story and may require copy updates to comply with the new required messaging hierarchy (what/why/value/how/start). Notable files: docs/getting-started/, docs/guides/, docs/bundles/, docs/README references. [::nold-ai/specfact-cli-modules::docs/getting-started/installation.md, docs/guides/, docs/bundles/* — various lines cited above]
-
openspec entries and prior docs changes (docs-06, docs-12, etc.) — repository already contains OpenSpec and TDD evidence related to core↔modules contracts and redirects; the PR’s new specs/requirements should be reconciled with these existing entries (e.g., openspec/changes/docs-06-*/ and openspec/specs/modules-docs-publishing/spec.md). [::nold-ai/specfact-cli-modules::openspec/specs/modules-docs-publishing/spec.md and various openspec change files listed]
Assessment
- The modules repo contains multiple docs, tests, and tooling that consume or validate the core docs’ URL contract and entry-point messaging. The PR’s documentation wording and new first-contact handoff requirements in the core repo are relevant here: the modules site must preserve the handoff semantics (redirects/back-links, canonical wording) and tests/scripts that validate cross-site links or host constants may need updates to accept the new phrasing or locations.
|
Caution Review failedAn error occurred during the review process. Please try again later. 📝 WalkthroughWalkthroughThis PR establishes a unified first-contact narrative across SpecFact's key entry points (README, GitHub repository, docs.specfact.io, modules.specfact.io) by repositioning SpecFact as a "validation and alignment layer for software delivery" with consistent Q&A structure and explicit cross-site handoff contracts. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
2 participants
Description
Release
devtomainafter merging the first-contact entrypoint overhaul from #467.This release sharpens the public story across the core first-contact surfaces so new users can quickly understand what SpecFact is, why it exists, what value it provides, and how to get started.
Fixes #466
New Features #466
Contract References: No production
@icontractbehavior changes in this release. This PR updates user-facing documentation, docs contracts, and OpenSpec evidence for the docs-14 change.Type of Change
Please check all that apply:
@icontractdecorators)Contract-First Testing Evidence
Required for all changes affecting CLI commands or public APIs:
Contract Validation
@icontractdecorators on public APIs)@beartypedecorators applied)hatch run contract-test-explorationTest Execution
hatch run contract-test-contracts✅hatch run contract-test-exploration✅hatch run contract-test-scenarios✅hatch run contract-test-full✅Test Quality
How Has This Been Tested?
Contract-First Approach: Documentation contracts and first-contact docs tests validate that README, docs landing pages, and release parity stay aligned.
Manual Testing
Automated Testing
Test Environment
Checklist
@icontract,@beartype)Quality Gates Status
hatch run type-check)hatch run lint)hatch run contract-test-contracts)hatch run contract-test-exploration)hatch run contract-test-scenarios)Screenshots/Recordings (if applicable)
N/A