docs: restructure README for star conversion#480
Conversation
Co-authored-by: Dom <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 (12)
📝 WalkthroughDocumentation Restructuring: Proof-First README and Onboarding FlowOpenSpec Change ID: User-Visible ChangesNo CLI surface or runtime behavior changes. This PR restructures repository documentation to present a proof-first onboarding experience:
Contract and API ImpactNo public API changes. Documentation-only restructuring:
Testing and Quality GatesTest contracts enhanced to validate new proof-first documentation structure:
Quality gates: OpenSpec and Documentation ArtifactsOpenSpec change tracked in
Support artifacts added under
Docs changes tracked in No Module or Version BumpsNo module signing, version bumps, or CHANGELOG updates in this PR (documentation-only). WalkthroughDocumentation-first change: README and docs reframed to a proof-first onboarding with an inline uvx quickstart and reproducible sample output; added OpenSpec change artifacts, a capture script plus sample-output evidence, and updated docs-focused contract tests to enforce the new first-contact story. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related issues
Possibly related PRs
Suggested labels
Architectural observations
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Co-authored-by: Dom <djm81@users.noreply.github.com>
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: bfbb6303d7
ℹ️ 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: 11
🤖 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/CHANGE_ORDER.md`:
- Line 130: Change the dependency wording in the change entry for
readme-star-conversion-01 so the dependency column uses explicit blocker
language instead of “related”; update the row so the Blocked by column reads
something like "blocked by `docs-new-user-onboarding` [`#476`]" for the pending
entry `readme-star-conversion-01` to reflect the explicit blocker relationship
to issue `#476`.
In `@openspec/changes/readme-star-conversion-01/proposal.md`:
- Around line 44-45: The two adjacent headings "## Capabilities" and "### New
Capabilities" violate MD022; insert a single blank line between these headings
in proposal.md so the file contains "## Capabilities" followed by one empty line
and then "### New Capabilities" to satisfy the lint rule.
- Line 92: The file proposal.md currently ends with the line "**Sanitized**:
false" and triggers MD047; fix it by ensuring the file ends with exactly one
trailing newline character (no extra blank lines or missing newline) so EOF has
a single empty line; open proposal.md, remove or add final blank lines as needed
and save so the file ends with one newline.
In `@openspec/changes/readme-star-conversion-01/tasks.md`:
- Around line 1-8: Update the checklist to include mandatory pre-flight and
cleanup tasks: under the branch/change setup (referencing branch
cursor/readme-star-conversion-a583 and checklist item “1.4 Validate change”),
add steps to create the worktree from origin/dev, run `hatch env create`, run
pre-flight checks `hatch run smart-test-status` and `hatch run
contract-test-status`, and add a post-merge worktree cleanup step (e.g., remove
or prune worktree). Ensure each new task is checked/unchecked appropriately and
described so the OpenSpec CLI validation and audit flow is complete.
In `@openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md`:
- Around line 38-47: Add the mandatory full SpecFact code-review command and
output (.specfact/code-review.json) into the "Commands run" list so audit
evidence is captured alongside the other gates: insert the command `hatch run
specfact code review run --json --out .specfact/code-review.json` into the block
that contains the other commands (the "Commands run" section around the existing
specfact invocation) and likewise add the same command/expected output entry at
the second occurrence referenced (the block around lines 66-68) so the required
artifact `.specfact/code-review.json` is produced and listed as mandatory
evidence before PR completion.
In `@README.md`:
- Around line 95-98: Update the GitHub Actions run step in the README where the
specfact-cli invocation uses "enforce stage" so it calls the canonical command
"govern enforce stage"; specifically replace the existing run line that invokes
"uvx specfact-cli@latest enforce stage --preset minimal" with "uvx
specfact-cli@latest govern enforce stage --preset minimal" so the CLI matches
the current documented command surface (see the run step string in the YAML
snippet).
In `@scripts/capture-readme-output.sh`:
- Around line 21-24: The current script reuses whatever git state exists in
WORK_DIR which makes captures non-deterministic; update the clone/checkout logic
around WORK_DIR/REPO_SLUG to always fetch and checkout a configured ref (e.g.,
an env var like CAPTURE_REF or CAPTURE_COMMIT) after cloning or when WORK_DIR
already exists: ensure you run git fetch --all and git checkout <CONFIGURED_REF>
(or git reset --hard <CONFIGURED_REF>) and use REPO_SLUG and WORK_DIR to locate
the repo, falling back to a documented default only if the env var is empty, so
the captured output is pinned to a known commit/ref.
- Around line 31-42: The script currently swallows failures by appending "||
true" to the uvx/specfact invocation, hiding real exit codes and producing
misleading evidence; remove the "|| true" and instead capture the command's exit
status (e.g., run uvx ... >"$RAW_OUTPUT_PATH" 2>&1; RC=$?) and then write or
export that RC so downstream evidence/metadata records the real result
(failures) and exit non-zero when appropriate; ensure you still redirect
stdout/stderr to RAW_OUTPUT_PATH and use the saved RC to fail the script or
persist the status to your evidence metadata.
In `@tests/unit/docs/test_first_contact_story.py`:
- Around line 18-19: The HOOK and SUBHOOK strings are duplicated across docs
contract tests causing drift; extract them into a single shared constants module
and import them in tests to ensure consistency. Create a new module (e.g.,
docs_test_constants) exporting HOOK and SUBHOOK, update tests like
test_first_contact_story.py to replace local HOOK/SUBHOOK literals with imports
from that module, and update any other docs contract tests to use the same
imports so README/landing-page assertions use the canonical values.
- Around line 45-51: The test uses a brittle 40-line heuristic (first_screen =
"\n".join(readme.splitlines()[:40])) to define the “first screen”; change this
to a section-anchored scope by slicing the README up to the "## Try it in 60
seconds" heading instead (find the index of that header in readme.lower() and
join lines before it, or split on a regex matching the header) so first_screen
reliably contains content prior to that section; update references to
first_screen accordingly in test_first_contact_story.py (keep assertions for
HOOK and SUBHOOK unchanged).
In `@tests/unit/docs/test_wow_entrypoint_contract.py`:
- Around line 75-78: The test_readme_capture_script_and_evidence_folder_exist
currently only checks CAPTURE_SCRIPT.is_file() and EVIDENCE_DIR.is_dir(),
allowing an empty evidence folder to pass; update the test to assert
CAPTURE_SCRIPT exists and then verify EVIDENCE_DIR contains at least one
artifact (e.g., iterate EVIDENCE_DIR.iterdir() or check any child is a file) and
optionally assert that at least one evidence file has non-zero size so empty
bundles fail; refer to the test_readme_capture_script_and_evidence_folder_exist
function and the CAPTURE_SCRIPT and EVIDENCE_DIR symbols when making the change.
🪄 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: edb379c1-ca85-4878-9987-00f213a0e6a0
📒 Files selected for processing (15)
README.mddocs/index.mdevidence/readme-sample-output/README.mdevidence/readme-sample-output/init-output.txtevidence/readme-sample-output/review-output.txtopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/.openspec.yamlopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/tasks.mdscripts/capture-readme-output.shtests/unit/docs/test_first_contact_story.pytests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_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: Tests (Python 3.12)
🧰 Additional context used
📓 Path-based instructions (15)
**/*.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:
evidence/readme-sample-output/README.mddocs/index.mdopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.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:
evidence/readme-sample-output/README.mddocs/index.mdopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
docs/**/*.md
📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)
Update architecture documentation in docs/ for architecture changes, state machine documentation for FSM modifications, interface documentation for API changes, and configuration guides for configuration changes. DO NOT create internal docs in specfact-cli repo folder that should not be visible to end users; use the respective internal repository instead.
Preserve all front-matter on every edit to docs files (title, layout, nav_order, permalink, etc.)
Preserve all YAML front-matter on docs when editing (
title,layout,nav_order,permalink, etc.); checkdocs/_layouts/default.htmlanddocs/index.mdbefore modifying front-matter keys
Files:
docs/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/index.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: 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...
Files:
tests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.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/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.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/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.pytests/unit/docs/test_first_contact_story.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
tests/**/*.py: Use@pytest.mark.asynciofor async tests
Test structure must mirror source: tests/unit/, tests/integration/, tests/e2e/ with corresponding source paths
Contract-first approach:@icontractcontracts on public APIs are primary coverage mechanism (target 80%+ API coverage); remove redundant unit tests that merely assert input validation or type checksSecret redaction via
LoggerSetup.redact_secretsmust be covered by unit tests
Files:
tests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.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/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.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/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.pytests/unit/docs/test_first_contact_story.py
**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{py,pyi}: Run code formatting withhatch run format(ruff format + fix) after every code change
Run type checking withhatch run type-check(basedpyright strict mode) on all Python code
All public APIs must use@icontractdecorators (@require,@ensure,@invariant) and@beartypefor runtime type checking
Use Python 3.11+, line length 120, and Google-style docstrings
Usesnake_casefor files/modules,PascalCasefor classes,UPPER_SNAKE_CASEfor constants
CLI commands usetyper.Typer()+rich.console.Console()pattern
Usefrom specfact_cli.common import get_bridge_loggerfor logging; avoidprint()in production command paths
Only write high-value comments and avoid verbose or redundant commentary
Keep backlog functionality grouped under the common top-levelbacklogcommand with subcommands:ceremony,analyze-deps,delta,verify-readiness
Project-scoped orchestration belongs underprojectcommand with subcommands:link-backlog,health-check,devops-flow,snapshot,regenerate,export-roadmap
Files:
tests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.pytests/unit/docs/test_first_contact_story.py
tests/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
tests/**/*.{py,pyi}: Test structure mirrors source:tests/unit/,tests/integration/,tests/e2e/. Use@pytest.mark.asynciofor async tests
Guard environment-sensitive logic withos.environ.get("TEST_MODE") == "true"
Files:
tests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.pytests/unit/docs/test_first_contact_story.py
tests/unit/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
Redundant unit tests that only assert input validation or type checks should be removed because contracts and beartype already cover them
Files:
tests/unit/docs/test_release_docs_parity.pytests/unit/docs/test_wow_entrypoint_contract.pytests/unit/docs/test_first_contact_story.py
openspec/CHANGE_ORDER.md
📄 CodeRabbit inference engine (CLAUDE.md)
Consult openspec/CHANGE_ORDER.md before creating, implementing, or archiving any change to verify blockers, module grouping, and dependencies; update CHANGE_ORDER.md in same commit as lifecycle events
Files:
openspec/CHANGE_ORDER.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/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.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
README.md
📄 CodeRabbit inference engine (CLAUDE.md)
Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
Files:
README.md
🧠 Learnings (32)
📓 Common learnings
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: README.md and docs landing page must stay in sync with actual CLI interface and command list; reconsider README from external/new-user perspective; lead with value and USP, not internal architecture; first-time reader should understand what SpecFact does and how to get started within first screen
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to README.md : Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
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: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: SpecFact code review must pass: run `hatch run specfact code review run --json --out .specfact/code-review.json` before PR creation; re-run when proposal, specs, tasks, design, or code change (not required for evidence-only edits); treat `.specfact/code-review.json` as mandatory evidence before change completion
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`
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: For behavior changes, follow strict TDD order: update specs first, add tests next with failing result evidence, then modify production code, re-run tests until passing; record evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
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
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
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Clean-code review enforces 7-principle charter through `specfact code review run` with categories: `naming`, `kiss`, `yagni`, `dry`, `solid`; zero regressions required before merge; Phase A thresholds are active (LOC >80 warning / >120 error); Phase B deferred
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: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Hard gate: strict TDD order is mandatory and auditable - update specs first, add tests next, run failing test, implement production code, re-run passing tests; create TDD_EVIDENCE.md in openspec/changes/<change-id>/
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Consult `openspec/CHANGE_ORDER.md` as the single source of truth for change sequencing before creating, implementing, or archiving changes; update it in the same commit when change lifecycle events occur
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.
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.
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to openspec/CHANGE_ORDER.md : Consult openspec/CHANGE_ORDER.md before creating, implementing, or archiving any change to verify blockers, module grouping, and dependencies; update CHANGE_ORDER.md in same commit as lifecycle events
📚 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/readme-star-conversion-01/.openspec.yamlevidence/readme-sample-output/README.mdopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to openspec/CHANGE_ORDER.md : Consult openspec/CHANGE_ORDER.md before creating, implementing, or archiving any change to verify blockers, module grouping, and dependencies; update CHANGE_ORDER.md in same commit as lifecycle events
Applied to files:
openspec/changes/readme-star-conversion-01/.openspec.yamlopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.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/readme-star-conversion-01/.openspec.yamlevidence/readme-sample-output/README.mddocs/index.mdtests/unit/docs/test_release_docs_parity.pyopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdtests/unit/docs/test_wow_entrypoint_contract.pyscripts/capture-readme-output.shREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Consult `openspec/CHANGE_ORDER.md` as the single source of truth for change sequencing before creating, implementing, or archiving changes; update it in the same commit when change lifecycle events occur
Applied to files:
openspec/changes/readme-star-conversion-01/.openspec.yamlopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/tasks.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: 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:
evidence/readme-sample-output/init-output.txtevidence/readme-sample-output/README.mddocs/index.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shREADME.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Clean-code review enforces 7-principle charter through `specfact code review run` with categories: `naming`, `kiss`, `yagni`, `dry`, `solid`; zero regressions required before merge; Phase A thresholds are active (LOC >80 warning / >120 error); Phase B deferred
Applied to files:
evidence/readme-sample-output/init-output.txtevidence/readme-sample-output/README.mddocs/index.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shREADME.mdopenspec/changes/readme-star-conversion-01/tasks.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:
evidence/readme-sample-output/init-output.txtevidence/readme-sample-output/README.mddocs/index.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: SpecFact code review must pass: run `hatch run specfact code review run --json --out .specfact/code-review.json` before PR creation; re-run when proposal, specs, tasks, design, or code change (not required for evidence-only edits); treat `.specfact/code-review.json` as mandatory evidence before change completion
Applied to files:
evidence/readme-sample-output/init-output.txtevidence/readme-sample-output/README.mddocs/index.mdtests/unit/docs/test_release_docs_parity.pyopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdtests/unit/docs/test_wow_entrypoint_contract.pyscripts/capture-readme-output.shopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.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:
evidence/readme-sample-output/init-output.txtdocs/index.mdopenspec/changes/readme-star-conversion-01/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:
evidence/readme-sample-output/README.mddocs/index.mdtests/unit/docs/test_release_docs_parity.pyopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shREADME.mdopenspec/changes/readme-star-conversion-01/tasks.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:
evidence/readme-sample-output/README.mddocs/index.mdtests/unit/docs/test_release_docs_parity.pyopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: README.md and docs landing page must stay in sync with actual CLI interface and command list; reconsider README from external/new-user perspective; lead with value and USP, not internal architecture; first-time reader should understand what SpecFact does and how to get started within first screen
Applied to files:
evidence/readme-sample-output/README.mddocs/index.mdtests/unit/docs/test_release_docs_parity.pyopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdtests/unit/docs/test_wow_entrypoint_contract.pyscripts/capture-readme-output.shREADME.mdtests/unit/docs/test_first_contact_story.py
📚 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:
evidence/readme-sample-output/README.mdREADME.md
📚 Learning: 2026-03-31T22:37:49.299Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-03-31T22:37:49.299Z
Learning: Run `hatch run specfact code review run --json --out .specfact/code-review.json` before submitting PR
Applied to files:
evidence/readme-sample-output/README.mddocs/index.mdscripts/capture-readme-output.sh
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to README.md : Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
Applied to files:
docs/index.mdopenspec/CHANGE_ORDER.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdtests/unit/docs/test_wow_entrypoint_contract.pyscripts/capture-readme-output.shREADME.md
📚 Learning: 2026-03-31T22:37:49.299Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-03-31T22:37:49.299Z
Learning: Enforce 7-principle clean-code charter (naming, kiss, yagni, dry, solid) as defined in `skills/specfact-code-review/SKILL.md`
Applied to files:
docs/index.md
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to src/specfact_cli/modules/*/ : Each module package must have module-package.yaml with metadata (name, version, commands, dependencies) and src/{name}/ directory with __init__.py and main.py containing typer.Typer app
Applied to files:
tests/unit/docs/test_release_docs_parity.py
📚 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.mdREADME.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: For behavior changes, follow strict TDD order: update specs first, add tests next with failing result evidence, then modify production code, re-run tests until passing; record evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdtests/unit/docs/test_wow_entrypoint_contract.pyopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Hard gate: strict TDD order is mandatory and auditable - update specs first, add tests next, run failing test, implement production code, re-run passing tests; create TDD_EVIDENCE.md in openspec/changes/<change-id>/
Applied to files:
openspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/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/readme-star-conversion-01/specs/readme-first-contact/spec.mdscripts/capture-readme-output.shopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to tests/**/*.py : Contract-first approach: icontract contracts on public APIs are primary coverage mechanism (target 80%+ API coverage); remove redundant unit tests that merely assert input validation or type checks
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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: Record the contract or property that supersedes a removed test in the PR description
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 tests/**/*.py : Convert repeated edge-case permutations into one Hypothesis property with contracts acting as oracles
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 tests/**/*.py : Trim low-value unit tests when a contract covers the same assertion (type/shape/raises on negative checks)
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 tests/**/*.py : Delete tests that only assert input validation, datatype/shape enforcement, or raises on negative conditions now guarded by contracts and runtime typing
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 src/**/*.py : Add/update contracts on new or modified public APIs, stateful classes and adapters using `icontract` decorators and `beartype` runtime type checks
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.py
📚 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:
scripts/capture-readme-output.sh
📚 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/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/tasks.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: Before making a pull request, locally run format, lint, contract tests, and full test suite: `hatch run format`, `hatch run lint`, `hatch run contract-test`, `hatch test --cover -v`
Applied to files:
openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.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: Run contract-first validation locally before committing: `hatch run contract-test-contracts`, `hatch run contract-test-exploration`, and `hatch run contract-test-scenarios`
Applied to files:
openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md
🪛 LanguageTool
openspec/changes/readme-star-conversion-01/proposal.md
[style] ~55-~55: Consider a different adjective to strengthen your wording.
Context: ...es while preserving truthful claims and deeper product context below the fold - `entry...
(DEEP_PROFOUND)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/readme-star-conversion-01/proposal.md
[warning] 44-44: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 45-45: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
[warning] 92-92: Files should end with a single newline character
(MD047, single-trailing-newline)
🔇 Additional comments (6)
openspec/changes/readme-star-conversion-01/.openspec.yaml (1)
1-2: OpenSpec scaffold metadata looks correct.The change metadata is minimal and valid for a new OpenSpec change folder.
evidence/readme-sample-output/README.md (1)
1-15: Evidence manifest is complete and reproducible.This captures the right operational details (version, repo context, exact commands, and artifact paths) for proof-block traceability.
docs/index.md (1)
20-24: First-contact rewrite is aligned and clear.The updated hook + immediate action framing improves onboarding while preserving the core CLI path.
Based on learnings: “README.md and docs landing page must stay in sync … lead with value and USP … first-time reader should understand what SpecFact does and how to get started within first screen.”
Also applies to: 31-33
tests/unit/docs/test_release_docs_parity.py (1)
351-352: Parity assertions correctly enforce the new first-contact contract.These checks appropriately lock README/docs landing alignment for the updated onboarding narrative.
Also applies to: 355-355
evidence/readme-sample-output/init-output.txt (1)
24-45: Init evidence captures the right operational signals.The output includes the expected bootstrap milestones and completion telemetry needed for README proof traceability.
README.md (1)
3-69: Proof-first structure and trust-bridge flow are strong.The new top-of-file experience, evidence-backed sample, and downstream topology handoff are well organized for first-contact conversion.
Based on learnings: “Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture.”
Also applies to: 100-167
Co-authored-by: Dom <djm81@users.noreply.github.com>
Co-authored-by: Dom <djm81@users.noreply.github.com>
Co-authored-by: Dom <djm81@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
openspec/changes/readme-star-conversion-01/proposal.md (1)
44-45:⚠️ Potential issue | 🟡 MinorInsert a blank line between adjacent headings to satisfy MD022.
Line 44 and Line 45 are adjacent headings with no separating blank line.
🛠️ Suggested fix
## Capabilities + ### New CapabilitiesAs per coding guidelines: “Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines).”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/readme-star-conversion-01/proposal.md` around lines 44 - 45, Insert a single blank line between the adjacent headings "## Capabilities" and "### New Capabilities" in proposal.md so headers are surrounded by blank lines (MD022); locate the two heading lines and add one empty line between them to satisfy the lint rule.tests/unit/docs/test_wow_entrypoint_contract.py (1)
75-78:⚠️ Potential issue | 🟠 MajorStrengthen evidence assertions so empty bundles fail.
Line 77 and Line 78 only check existence of the script/folder; an empty
sample-output/directory still passes this contract test.✅ Suggested tightening
def test_readme_capture_script_and_evidence_folder_exist() -> None: """README sample output must be backed by reproducible evidence artifacts.""" assert CAPTURE_SCRIPT.is_file(), "Missing docs/_support/readme-first-contact/capture-readme-output.sh" assert EVIDENCE_DIR.is_dir(), "Missing docs/_support/readme-first-contact/sample-output/" + capture_metadata = EVIDENCE_DIR / "capture-metadata.txt" + raw_output = EVIDENCE_DIR / "review-output.txt" + init_output = EVIDENCE_DIR / "init-output.txt" + for artifact in (capture_metadata, raw_output, init_output): + assert artifact.is_file(), f"Missing {artifact.relative_to(REPO_ROOT)}" + assert artifact.stat().st_size > 0, f"Empty {artifact.relative_to(REPO_ROOT)}"Based on learnings: README/docs first-contact must stay in sync with real CLI evidence and reproducible output artifacts.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/unit/docs/test_wow_entrypoint_contract.py` around lines 75 - 78, The current test_readme_capture_script_and_evidence_folder_exist only checks that CAPTURE_SCRIPT.exists() and EVIDENCE_DIR.is_dir(), allowing an empty sample-output/ to pass; change the assertions so the CAPTURE_SCRIPT is a non-empty file (e.g., CAPTURE_SCRIPT.is_file() and CAPTURE_SCRIPT.stat().st_size > 0) and the EVIDENCE_DIR contains at least one file/artifact (e.g., any(EVIDENCE_DIR.rglob("*")) or len(list(EVIDENCE_DIR.iterdir())) > 0) so empty bundles fail; update the assertions and messages in the test to reference CAPTURE_SCRIPT and EVIDENCE_DIR accordingly.openspec/changes/readme-star-conversion-01/tasks.md (1)
1-8:⚠️ Potential issue | 🟠 MajorAdd mandatory worktree lifecycle and pre-flight checklist items.
The task plan still omits required setup/teardown workflow steps, so execution evidence is incomplete.
📋 Suggested checklist patch
## 1. Branch and change setup @@ -- [ ] 1.4 Validate change with OpenSpec CLI +- [ ] 1.4 Verify worktree is created from `origin/dev` +- [ ] 1.5 Run `hatch env create` in the worktree +- [ ] 1.6 Run pre-flight checks: + - `hatch run smart-test-status` + - `hatch run contract-test-status` +- [ ] 1.7 Validate change with OpenSpec CLI - blocked in this environment: `openspec` command is not installed @@ ## 6. Git and PR @@ - [ ] 6.3 Create or update the PR against `dev` +- [ ] 6.4 Clean up worktree after mergeBased on learnings: OpenSpec task plans must explicitly include worktree creation from
origin/dev, env setup, pre-flight checks, and post-merge cleanup.Also applies to: 48-52
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/readme-star-conversion-01/tasks.md` around lines 1 - 8, Update the task plan under "Branch and change setup" in tasks.md to include the full worktree lifecycle and pre-flight checklist: add explicit steps to create a worktree from origin/dev (e.g., "git worktree add ... from origin/dev"), environment setup commands (install openspec, required tools), pre-flight validation (run openspec CLI validation and any lints/tests), and post-merge cleanup (remove worktree and restore branches). Ensure these items are added as mandatory checklist entries (alongside 1.1–1.4) so execution evidence is complete and visible in the task plan.openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md (1)
39-47:⚠️ Potential issue | 🟡 MinorPromote mandatory full
.specfact/code-review.jsonrun into the primary command list.The full-scope command is documented only in environment notes; move it into “Commands run” for stronger auditability.
🧾 Suggested update
### Commands run - `hatch run pytest tests/unit/docs/test_wow_entrypoint_contract.py tests/unit/docs/test_first_contact_story.py tests/unit/docs/test_release_docs_parity.py -q --no-cov` - `hatch run yaml-lint` - `hatch run format` - `hatch run type-check` - `hatch run contract-test` +- `hatch run specfact code review run --json --out .specfact/code-review.json --scope full` - `hatch run specfact code review run tests/unit/docs/test_wow_entrypoint_contract.py tests/unit/docs/test_first_contact_story.py tests/unit/docs/test_release_docs_parity.py --json --out .specfact/code-review-docs-tests.json` - `docs/_support/readme-first-contact/capture-readme-output.sh`Based on learnings:
.specfact/code-review.jsonis mandatory evidence and should be explicitly captured before change completion.Also applies to: 64-71
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md` around lines 39 - 47, Update the "Commands run" section to include the mandatory full-scope specfact run by adding the command that generates .specfact/code-review.json (the same invocation currently only documented in environment notes) so the artifact is produced as part of the recorded commands; ensure the exact command uses the same flags as the environment note (e.g., specfact code review run ... --json --out .specfact/code-review.json), and keep the existing related commands (hatch run contract-test and docs/_support/readme-first-contact/capture-readme-output.sh) in place to preserve ordering and auditability.README.md (1)
94-97:⚠️ Potential issue | 🔴 CriticalUse the canonical
govern enforce stagecommand in the GitHub Actions snippet.Line 96 still documents
enforce stage; this can send users to a stale command path.🔧 Suggested fix
- name: SpecFact Gate - run: uvx specfact-cli@latest enforce stage --preset minimal + run: uvx specfact-cli@latest govern enforce stage --preset minimal#!/bin/bash set -euo pipefail # Verify command references in docs/tests. rg -n -C2 '\b(specfact-cli(`@latest`)?\s+)?(enforce\s+stage|govern\s+enforce\s+stage)\b' # Verify command surface references in source declarations. rg -n -C3 'govern|enforce|@.*\.command\(' src tests -g '*.py' || trueExpected result: docs should standardize on
govern enforce stageand source/docs should not promoteenforce stageas canonical.Based on learnings: README.md must stay in sync with the actual CLI interface and command list from a first-time user perspective.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 94 - 97, Update the GitHub Actions snippet in README.md to use the canonical CLI invocation by replacing the uvx action call that references "specfact-cli@latest enforce stage" with the equivalent "uvx govern@latest enforce stage --preset minimal" (or otherwise invoke the "govern enforce stage" command directly), and make sure the surrounding text and the "SpecFact Gate" snippet consistently reference "govern enforce stage" so docs align with the CLI surface.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/_support/readme-first-contact/capture-readme-output.sh`:
- Around line 1-65: Add a prerequisite check at the start of the script
(immediately after set -euo pipefail) to verify required external commands (git,
gh, uvx) are available; for each command, use command -v (or which) to detect
presence and if missing print a clear error like "Missing required tool: <tool>;
please install" and exit non‑zero. Update the top of capture-readme-output.sh so
the check runs before any work with WORK_DIR/gh/uvx and ensures the script fails
fast with a helpful message when git, gh, or uvx are not found.
---
Duplicate comments:
In `@openspec/changes/readme-star-conversion-01/proposal.md`:
- Around line 44-45: Insert a single blank line between the adjacent headings
"## Capabilities" and "### New Capabilities" in proposal.md so headers are
surrounded by blank lines (MD022); locate the two heading lines and add one
empty line between them to satisfy the lint rule.
In `@openspec/changes/readme-star-conversion-01/tasks.md`:
- Around line 1-8: Update the task plan under "Branch and change setup" in
tasks.md to include the full worktree lifecycle and pre-flight checklist: add
explicit steps to create a worktree from origin/dev (e.g., "git worktree add ...
from origin/dev"), environment setup commands (install openspec, required
tools), pre-flight validation (run openspec CLI validation and any lints/tests),
and post-merge cleanup (remove worktree and restore branches). Ensure these
items are added as mandatory checklist entries (alongside 1.1–1.4) so execution
evidence is complete and visible in the task plan.
In `@openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md`:
- Around line 39-47: Update the "Commands run" section to include the mandatory
full-scope specfact run by adding the command that generates
.specfact/code-review.json (the same invocation currently only documented in
environment notes) so the artifact is produced as part of the recorded commands;
ensure the exact command uses the same flags as the environment note (e.g.,
specfact code review run ... --json --out .specfact/code-review.json), and keep
the existing related commands (hatch run contract-test and
docs/_support/readme-first-contact/capture-readme-output.sh) in place to
preserve ordering and auditability.
In `@README.md`:
- Around line 94-97: Update the GitHub Actions snippet in README.md to use the
canonical CLI invocation by replacing the uvx action call that references
"specfact-cli@latest enforce stage" with the equivalent "uvx govern@latest
enforce stage --preset minimal" (or otherwise invoke the "govern enforce stage"
command directly), and make sure the surrounding text and the "SpecFact Gate"
snippet consistently reference "govern enforce stage" so docs align with the CLI
surface.
In `@tests/unit/docs/test_wow_entrypoint_contract.py`:
- Around line 75-78: The current
test_readme_capture_script_and_evidence_folder_exist only checks that
CAPTURE_SCRIPT.exists() and EVIDENCE_DIR.is_dir(), allowing an empty
sample-output/ to pass; change the assertions so the CAPTURE_SCRIPT is a
non-empty file (e.g., CAPTURE_SCRIPT.is_file() and CAPTURE_SCRIPT.stat().st_size
> 0) and the EVIDENCE_DIR contains at least one file/artifact (e.g.,
any(EVIDENCE_DIR.rglob("*")) or len(list(EVIDENCE_DIR.iterdir())) > 0) so empty
bundles fail; update the assertions and messages in the test to reference
CAPTURE_SCRIPT and EVIDENCE_DIR accordingly.
🪄 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: 75359b69-22ca-4c05-8b79-d505001b6f1b
📒 Files selected for processing (10)
README.mddocs/_support/readme-first-contact/capture-readme-output.shdocs/_support/readme-first-contact/sample-output/capture-metadata.txtdocs/_support/readme-first-contact/sample-output/init-output.txtdocs/_support/readme-first-contact/sample-output/review-output.txtopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/tasks.mdtests/unit/docs/test_wow_entrypoint_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: Tests (Python 3.12)
🧰 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:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.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:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.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/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/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
README.md
📄 CodeRabbit inference engine (CLAUDE.md)
Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
Files:
README.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: 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...
Files:
tests/unit/docs/test_wow_entrypoint_contract.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/docs/test_wow_entrypoint_contract.py
{src,tests}/**/*.py
📄 CodeRabbit inference engine (.cursor/rules/session_startup_instructions.mdc)
Apply
pylint src testsfor linting before committing
Files:
tests/unit/docs/test_wow_entrypoint_contract.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
tests/**/*.py: Use@pytest.mark.asynciofor async tests
Test structure must mirror source: tests/unit/, tests/integration/, tests/e2e/ with corresponding source paths
Contract-first approach:@icontractcontracts on public APIs are primary coverage mechanism (target 80%+ API coverage); remove redundant unit tests that merely assert input validation or type checksSecret redaction via
LoggerSetup.redact_secretsmust be covered by unit tests
Files:
tests/unit/docs/test_wow_entrypoint_contract.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/docs/test_wow_entrypoint_contract.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/docs/test_wow_entrypoint_contract.py
**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{py,pyi}: Run code formatting withhatch run format(ruff format + fix) after every code change
Run type checking withhatch run type-check(basedpyright strict mode) on all Python code
All public APIs must use@icontractdecorators (@require,@ensure,@invariant) and@beartypefor runtime type checking
Use Python 3.11+, line length 120, and Google-style docstrings
Usesnake_casefor files/modules,PascalCasefor classes,UPPER_SNAKE_CASEfor constants
CLI commands usetyper.Typer()+rich.console.Console()pattern
Usefrom specfact_cli.common import get_bridge_loggerfor logging; avoidprint()in production command paths
Only write high-value comments and avoid verbose or redundant commentary
Keep backlog functionality grouped under the common top-levelbacklogcommand with subcommands:ceremony,analyze-deps,delta,verify-readiness
Project-scoped orchestration belongs underprojectcommand with subcommands:link-backlog,health-check,devops-flow,snapshot,regenerate,export-roadmap
Files:
tests/unit/docs/test_wow_entrypoint_contract.py
tests/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
tests/**/*.{py,pyi}: Test structure mirrors source:tests/unit/,tests/integration/,tests/e2e/. Use@pytest.mark.asynciofor async tests
Guard environment-sensitive logic withos.environ.get("TEST_MODE") == "true"
Files:
tests/unit/docs/test_wow_entrypoint_contract.py
tests/unit/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
Redundant unit tests that only assert input validation or type checks should be removed because contracts and beartype already cover them
Files:
tests/unit/docs/test_wow_entrypoint_contract.py
🧠 Learnings (46)
📓 Common learnings
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: README.md and docs landing page must stay in sync with actual CLI interface and command list; reconsider README from external/new-user perspective; lead with value and USP, not internal architecture; first-time reader should understand what SpecFact does and how to get started within first screen
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to README.md : Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
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/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
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.
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: SpecFact code review must pass: run `hatch run specfact code review run --json --out .specfact/code-review.json` before PR creation; re-run when proposal, specs, tasks, design, or code change (not required for evidence-only edits); treat `.specfact/code-review.json` as mandatory evidence before change completion
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`
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
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: For behavior changes, follow strict TDD order: update specs first, add tests next with failing result evidence, then modify production code, re-run tests until passing; record evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Clean-code review enforces 7-principle charter through `specfact code review run` with categories: `naming`, `kiss`, `yagni`, `dry`, `solid`; zero regressions required before merge; Phase A thresholds are active (LOC >80 warning / >120 error); Phase B deferred
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
📚 Learning: 2026-03-31T22:37:49.299Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-03-31T22:37:49.299Z
Learning: Run `hatch run specfact code review run --json --out .specfact/code-review.json` before submitting PR
Applied to files:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.sh
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: SpecFact code review must pass: run `hatch run specfact code review run --json --out .specfact/code-review.json` before PR creation; re-run when proposal, specs, tasks, design, or code change (not required for evidence-only edits); treat `.specfact/code-review.json` as mandatory evidence before change completion
Applied to files:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mddocs/_support/readme-first-contact/sample-output/init-output.txtREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: README.md and docs landing page must stay in sync with actual CLI interface and command list; reconsider README from external/new-user perspective; lead with value and USP, not internal architecture; first-time reader should understand what SpecFact does and how to get started within first screen
Applied to files:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 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:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mddocs/_support/readme-first-contact/sample-output/init-output.txtREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mddocs/_support/readme-first-contact/capture-readme-output.sh
📚 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:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to README.md : Keep README.md in sync with actual CLI interface and command list; prioritize new-user perspective with value/USP up front, not internal architecture
Applied to files:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Clean-code review enforces 7-principle charter through `specfact code review run` with categories: `naming`, `kiss`, `yagni`, `dry`, `solid`; zero regressions required before merge; Phase A thresholds are active (LOC >80 warning / >120 error); Phase B deferred
Applied to files:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mddocs/_support/readme-first-contact/sample-output/init-output.txtopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 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:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mddocs/_support/readme-first-contact/sample-output/init-output.txtopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 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:
docs/_support/readme-first-contact/sample-output/capture-metadata.txtopenspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
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:
docs/_support/readme-first-contact/sample-output/capture-metadata.txt
📚 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/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.sh
📚 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/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.sh
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to openspec/CHANGE_ORDER.md : Consult openspec/CHANGE_ORDER.md before creating, implementing, or archiving any change to verify blockers, module grouping, and dependencies; update CHANGE_ORDER.md in same commit as lifecycle events
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: For behavior changes, follow strict TDD order: update specs first, add tests next with failing result evidence, then modify production code, re-run tests until passing; record evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdtests/unit/docs/test_wow_entrypoint_contract.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 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:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdREADME.mdopenspec/changes/readme-star-conversion-01/proposal.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.sh
📚 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/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mdtests/unit/docs/test_wow_entrypoint_contract.py
📚 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/readme-star-conversion-01/tasks.mdREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.mddocs/_support/readme-first-contact/capture-readme-output.shtests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Pre-commit checklist order: format → type-check → lint → yaml-lint → contract-test → smart-test; all must pass before committing
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.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/readme-star-conversion-01/tasks.mddocs/_support/readme-first-contact/sample-output/init-output.txtREADME.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.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: Before making a pull request, locally run format, lint, contract tests, and full test suite: `hatch run format`, `hatch run lint`, `hatch run contract-test`, `hatch test --cover -v`
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/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 **/*.{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/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Always verify that an active OpenSpec change in `openspec/changes/` explicitly covers any requested code modification before implementing; ask for clarification (new change, modify existing, or delta) if no such change exists
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.md
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Hard gate: strict TDD order is mandatory and auditable - update specs first, add tests next, run failing test, implement production code, re-run passing tests; create TDD_EVIDENCE.md in openspec/changes/<change-id>/
Applied to files:
openspec/changes/readme-star-conversion-01/tasks.mdopenspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Consult `openspec/CHANGE_ORDER.md` as the single source of truth for change sequencing before creating, implementing, or archiving changes; update it in the same commit when change lifecycle events occur
Applied to files:
openspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.mdopenspec/changes/readme-star-conversion-01/proposal.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:
README.mdopenspec/changes/readme-star-conversion-01/proposal.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-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to src/specfact_cli/modules/project/**/*.py : Project-scoped orchestration belongs under 'project' command: link-backlog, health-check, devops-flow, snapshot, regenerate, export-roadmap
Applied to files:
README.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Headers should be surrounded by blank lines (MD022: Headers Should Be Surrounded By Blank Lines)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Fenced code blocks should be surrounded by blank lines (MD031: Fenced Code Blocks)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Lists should be surrounded by blank lines (MD032: Lists)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Use exactly one space after the list marker (e.g., -, *, +, 1.) (MD030: Spaces After List Markers)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Do not use more than one consecutive blank line anywhere in the document (MD012: No Multiple Consecutive Blank Lines)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Lines should not have trailing spaces (MD009: No Trailing Spaces)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Don't use spaces immediately inside code spans (MD038: Spaces Inside Code Spans)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Files must end with a single empty line (MD047: Files Must End With Single Newline)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Headers should increment by one level at a time (MD001: Header Increment)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Only one top-level header (H1) is allowed per document (MD025: Single H1 Header)
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.md
📚 Learning: 2026-03-25T21:32:08.987Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/markdown-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:08.987Z
Learning: Applies to **/*.{md,mdc} : Ensure proper escaping of special characters in markdown files
Applied to files:
openspec/changes/readme-star-conversion-01/proposal.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:
docs/_support/readme-first-contact/capture-readme-output.sh
📚 Learning: 2026-03-31T22:37:49.299Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-03-31T22:37:49.299Z
Learning: Enforce 7-principle clean-code charter (naming, kiss, yagni, dry, solid) as defined in `skills/specfact-code-review/SKILL.md`
Applied to files:
docs/_support/readme-first-contact/capture-readme-output.sh
📚 Learning: 2026-03-31T22:38:12.286Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T22:38:12.286Z
Learning: Applies to tests/**/*.py : Contract-first approach: icontract contracts on public APIs are primary coverage mechanism (target 80%+ API coverage); remove redundant unit tests that merely assert input validation or type checks
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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: Record the contract or property that supersedes a removed test in the PR description
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 tests/**/*.py : Convert repeated edge-case permutations into one Hypothesis property with contracts acting as oracles
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.py
📚 Learning: 2026-03-31T22:38:56.776Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T22:38:56.776Z
Learning: Contract-first development: all public APIs must use `icontract` contracts on public APIs as the primary coverage mechanism targeting 80%+ API coverage; CrossHair discovers counterexamples via symbolic execution
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.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 tests/**/*.py : Trim low-value unit tests when a contract covers the same assertion (type/shape/raises on negative checks)
Applied to files:
tests/unit/docs/test_wow_entrypoint_contract.py
🪛 LanguageTool
openspec/changes/readme-star-conversion-01/proposal.md
[style] ~55-~55: Consider a different adjective to strengthen your wording.
Context: ...es while preserving truthful claims and deeper product context below the fold - `entry...
(DEEP_PROFOUND)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/readme-star-conversion-01/proposal.md
[warning] 35-35: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 49-49: Multiple headings with the same content
(MD024, no-duplicate-heading)
🔇 Additional comments (5)
docs/_support/readme-first-contact/capture-readme-output.sh (5)
44-45: The|| truestill silently swallows review command failures.This concern was raised in a previous review. For evidence-generation scripts, masking the exit code makes it impossible to distinguish between "review ran and found issues" versus "review crashed due to missing dependency or bootstrap failure." The metadata file should record the actual exit status.
🧪 Capture exit code while preserving output redirection
pushd "$WORK_DIR" >/dev/null +review_exit_code=0 uvx \ --from "specfact-cli==$CLI_VERSION" \ --with ruff \ --with radon \ --with semgrep \ --with basedpyright \ --with pylint \ --with crosshair-tool \ specfact code review run --path . --scope full \ - >"$RAW_OUTPUT_PATH" 2>&1 || true + >"$RAW_OUTPUT_PATH" 2>&1 || review_exit_code=$? popd >/dev/null + +if [[ ! -s "$RAW_OUTPUT_PATH" ]]; then + echo "ERROR: Review produced no output at $RAW_OUTPUT_PATH" >&2 + exit 1 +fiThen in the metadata section:
- Raw output: \`$RAW_OUTPUT_PATH\` - Init output: \`$INIT_OUTPUT_PATH\` +- Review exit code: \`$review_exit_code\` EOF
1-6: Solid foundation with strict Bash settings and deterministic path resolution.The
set -euo pipefailensures fail-fast behavior, and derivingREPO_ROOTfrom script location makes the script portable across worktree checkouts. This aligns well with the OpenSpec evidence workflow that requires reproducible captures.
8-16: Configuration design supports both CI reproducibility and local override flexibility.Pinning
CLI_VERSIONandREPO_REFto specific values while allowing environment variable overrides is the right pattern for evidence-generation scripts. The commit SHA pin (2b5ba8cd...) directly addresses the previous review concern about non-deterministic captures.
48-65: Metadata capture provides good traceability for OpenSpec evidence.Recording CLI version, repo ref, and command invocation in
capture-metadata.txtsupports the TDD evidence requirements. This makes it straightforward to reproduce or audit captures during code review cycles. Based on learnings, this evidence pattern aligns with the OpenSpec workflow requirement to record evidence inTDD_EVIDENCE.md.
27-28: Review comment references code that does not match the actual file implementation.The review shows
git fetch --depth 1 origin "$REPO_REF"with shallow fetch concerns, but the actual implementation at lines 27-29 usesgit fetch --all --tags --prunefollowed byreset --hard— a more comprehensive and robust approach. The code uses the$CAPTURE_REFvariable, not$REPO_REF. The concerns about shallow fetch reliability and the suggestedgit clean -fdxare not applicable to the current implementation, which was likely refined between review and merge.> Likely an incorrect or invalid review comment.
1 participant
Description
Restructure the repository
README.mdaround a proof-first onboarding flow so first-time visitors see a concrete value proposition, runnable commands, and real sample output before the deeper platform story.Fixes #476
New Features #(issue)
Contract References: Updates the docs-first contract tests for the README and
docs/index.mdfirst-contact story; no runtime@icontractAPI changes.Type of Change
@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✅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: Added README/docs contract tests for the proof-first hero, sample-output proof block, section ordering, and reproducible evidence assets. Captured failing-before and passing-after evidence in
openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md.Manual Testing
Automated Testing
Test Environment
Checklist
@icontract,@beartype)Quality Gates Status
hatch run type-check)hatch run lint)hatch run contract-test)hatch run contract-test-exploration)hatch run contract-test-scenarios)Notes
readme-star-conversion-01#481openspec validate readme-star-conversion-01 --strictdocs/_support/readme-first-contact/capture-readme-output.shnold-ai/specfact-demo-repoto commit2b5ba8cd57d16c1a1f24463a297fdb28fbede123specfact-smart-checksgovern enforce stagedocs/_support/readme-first-contact/sample-output/capture-metadata.txt,docs/_support/readme-first-contact/sample-output/init-output.txt,docs/_support/readme-first-contact/sample-output/review-output.txthatch run smart-testcurrently fails on an unrelated baseline issue during collection intests/integration/test_command_package_runtime_validation.py(IndexError: 2); seeopenspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md.Screenshots/Recordings (if applicable)
Not applicable for this docs-only change.