Conversation
…1) (#275) - Use discover_all_package_metadata() in init so list-modules/enable/disable use same roots as registry (built-in + workspace modules + SPECFACT_MODULES_ROOTS) - Extend backlog-core-01 OpenSpec: init-module-discovery-alignment spec, tasks 0.5.x, TDD evidence - Bump version to 0.34.0; CHANGELOG Fixes #116 Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: add thorough codebase validation (validation-01) - Add --crosshair-per-path-timeout to specfact repro and ReproChecker - Add docs/reference/thorough-codebase-validation.md (quick check, contract-full, sidecar, dogfooding) - Unit test and TDD evidence for CrossHair per-path timeout - OpenSpec validation-01-deep-validation tasks and TDD_EVIDENCE updated * fix: reject non-positive CrossHair per-path timeout (review) * docs: CHANGELOG v0.34.0 and doc updates for thorough codebase validation --------- Signed-off-by: Dom <39115308+djm81@users.noreply.github.com> Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat(patch-mode): add patch apply (local + --write with confirmation) [#177] - Add patch_mode module: pipeline (generator, applier, idempotency), patch apply command - specfact patch apply <file> (local + preflight), patch apply --write --yes (upstream, idempotent) - OpenSpec patch-mode-01-preview-apply: proposal Source Tracking, tasks, TDD_EVIDENCE - CHANGELOG [Unreleased] entry for v0.34.0 merge Co-authored-by: Cursor <cursoragent@cursor.com> * fix(patch-mode): sanitize idempotency keys, derive key from patch content [PR review] * Fix errors and ensure module compatibility --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: add bundle-mapper module with confidence-based spec-to-bundle mapping - BundleMapping model and BundleMapper engine (explicit label, historical, content similarity) - Mapping history persistence and MappingRule (save_user_confirmed_mapping, load_bundle_mapping_config) - Interactive UI (ask_bundle_mapping) with Rich confidence visualization - Unit tests and TDD_EVIDENCE for bundle-mapper-01 (OpenSpec #121) Co-authored-by: Cursor <cursoragent@cursor.com> * fix(bundle-mapper): address PR review findings (P1/P2) - P1 interactive: no default accept for low-confidence; use default only when conf >= 0.5 - P1 history: ignore empty key fields in item_keys_similar (only count non-empty matches) - P2 engine: add historical weight only when hist_bundle == primary_bundle_id - Add test_item_keys_similar_empty_fields_not_counted to lock empty-key behavior Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* fix: implement verification-01 delta for bundle mapping, patch apply, and docs parity * test: fix patch write yes scenario for real diff apply * fix: keep bundle mapping history out of bundle manifest --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com> Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
* feat: launch module marketplace lifecycle and trust-first UX Deliver the central module marketplace workflow with source-aware discovery, lifecycle management, and trust/publisher visibility so users can safely manage official vs local modules. This also aligns docs and OpenSpec artifacts with the shipped behavior, including command introspection and clearer install/uninstall guidance. Co-authored-by: Cursor <cursoragent@cursor.com> * fix: respect explicit discovery roots in module tests Disable implicit legacy/workspace roots when explicit roots are passed to module discovery so isolated test roots are honored and deterministic. Co-authored-by: Cursor <cursoragent@cursor.com> * fix: enforce safe module extraction and upgrade reinstall --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: add bundle-mapper module with confidence-based spec-to-bundle mapping - BundleMapping model and BundleMapper engine (explicit label, historical, content similarity) - Mapping history persistence and MappingRule (save_user_confirmed_mapping, load_bundle_mapping_config) - Interactive UI (ask_bundle_mapping) with Rich confidence visualization - Unit tests and TDD_EVIDENCE for bundle-mapper-01 (OpenSpec #121) Co-authored-by: Cursor <cursoragent@cursor.com> * fix(bundle-mapper): address PR review findings (P1/P2) - P1 interactive: no default accept for low-confidence; use default only when conf >= 0.5 - P1 history: ignore empty key fields in item_keys_similar (only count non-empty matches) - P2 engine: add historical weight only when hist_bundle == primary_bundle_id - Add test_item_keys_similar_empty_fields_not_counted to lock empty-key behavior Co-authored-by: Cursor <cursoragent@cursor.com> * fix: address bundle-mapper review defects with tdd evidence * test: make specmatic integration tests plugin-agnostic --------- Signed-off-by: Dom <39115308+djm81@users.noreply.github.com> Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: add interactive backlog issue creation flow * feat(backlog): add interactive issue creation and mapping setup * fix: align backlog protocol test fakes and module manifest versions * Fix type error * fix(backlog): persist ado sprint and normalize github create id * fix(backlog-core): address review findings for add/config/github --------- Signed-off-by: Dom <39115308+djm81@users.noreply.github.com> Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
#292) * chore(openspec): archive completed changes and align architecture docs * docs(architecture): refresh discrepancies report after arch-08 remediation --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
…log prompt (#294) * fix(backlog): restore installed runtime discovery and add backlog prompt * Archive bugfix change --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* fix: harden module lifecycle bootstrap and signing workflows * fix: stabilize module signature hashing across environments * fix: stabilize bundle module signature verification in CI --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat: add github hierarchy cache sync * Backport improvements from modules scripts * Fix review findings * Make github sync script executable --------- Signed-off-by: Dom <39115308+djm81@users.noreply.github.com> Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
* feat: compact agent governance loading * docs: mark governance PR task complete * docs: sync governance-03 github issue metadata * fix: restore dev branch governance block * Apply review findings * docs: add sibling internal wiki context for OpenSpec design Point AGENTS.md, Claude/Copilot/Cursor surfaces, and the OpenSpec rule at docs/agent-rules/40-openspec-and-tdd.md to read-only wiki paths (hot.md, graph.md, concepts) via absolute paths when specfact-cli-internal is present. Update INDEX applicability notes and extend governance tests. Made-with: Cursor --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
djm81
added
documentation
This was
linked to
issues
Apr 10, 2026
Contributor
|
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 (284)
📝 WalkthroughWalkthroughConsolidates agent bootstrap into canonical docs under Changes
Sequence Diagram(s)sequenceDiagram
participant Agent as Agent / Session
participant Bootstrap as Bootstrap Loader
participant RuleIndex as docs/agent-rules/INDEX.md
participant Cache as Local Cache (.specfact/backlog)
participant GitHub as GitHub API
Agent->>Bootstrap: start session (AGENTS.md loaded)
Bootstrap->>Bootstrap: detect repo root / branch / worktree
Bootstrap->>RuleIndex: load always-load rules (checklist, session-bootstrap)
RuleIndex->>Agent: enforce non-negotiable gates
Agent->>Cache: read .specfact/backlog/github_hierarchy_cache.md
alt cache missing or stale
Agent->>GitHub: run scripts/sync_github_hierarchy_cache.py -> GraphQL queries
GitHub-->>Cache: return Epic/Feature metadata
Cache->>Cache: write markdown + state fingerprint
end
Bootstrap->>RuleIndex: load task-specific rules via applies_when
Agent->>Agent: execute task (obey openspec-and-tdd, run quality gates, run openspec archive post-merge)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related issues
Possibly related PRs
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
![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: c5083cf1eb
ℹ️ 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".
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com> Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 27
🤖 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/agent-rules/60-github-change-governance.md`:
- Around line 57-59: Update the "Concurrency ambiguity" section to require an
explicit cache freshness check before treating a linked GitHub issue marked `in
progress` as a blocking condition: instruct agents to run or call the hierarchy
cache sync (referencing the script name scripts/sync_github_hierarchy_cache.py)
when the cache is older than a short threshold (e.g., 5 minutes) and verify the
`in progress` status is current, then only after this verification pause
implementation and prompt the user; add these steps to the Concurrency ambiguity
paragraph and mention the cache-sync requirement in the public-work readiness
checks so agents refresh before status checks.
- Around line 39-45: Update the governance doc to explicitly mark that the
cache-first pattern is currently not implemented in the specfact-cli-modules
repo: state that specfact-cli-modules does not yet include
scripts/sync_github_hierarchy_cache.py or the .specfact/backlog/*.md/.json cache
files and add a short TODO requiring the modules repo to implement a compatible
sync_github_hierarchy_cache.py that produces the same markdown structure and
fingerprint (.specfact/backlog/github_hierarchy_cache_state.json) and follows
the three cache-first rules described so downstream tooling can rely on
identical ordering and deterministic rendering.
In `@docs/agent-rules/70-release-commit-and-docs.md`:
- Around line 39-42: Add an automated quality gate that fails the release if the
version in pyproject.toml, setup.py, and src/specfact_cli/__init__.py diverge:
implement a Hatch-run script (hooked to "hatch run release") or a pre-commit
hook that extracts version strings via regex from those three files and compares
them, returning a non-zero exit and a clear error message if any mismatch is
found; update pre-commit-smart-checks.sh to call the new validator (instead of
treating these files as safe changes) and optionally note the check in
verify-modules-signature.py’s flow so release automation always invokes the
validator.
In `@docs/agent-rules/INDEX.md`:
- Around line 64-72: The applicability matrix currently uses freeform task
signal strings which leads to drift; add a canonical task-signal list and a
validation step: update the "Applicability matrix" section in INDEX.md to
include a "Task signal definitions" subsection enumerating canonical signals
(e.g., implementation-request, branch-change, github-public-work,
release-finalization, repo-orientation), then implement a hatch/CI validation
that checks each rule file's frontmatter `applies_when` values against that
canonical set and surface errors; reference the "Applicability matrix" header,
the `applies_when` frontmatter key, and mention AGENTS.md/bootstrap consumers so
consumers use the canonical names.
In `@openspec/CHANGE_ORDER.md`:
- Around line 184-185: Update the entry for governance-02-github-hierarchy-cache
in openspec/CHANGE_ORDER.md to reflect its archived lifecycle state to match the
new artifact path
openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache; locate
the row with governance | 02 | governance-02-github-hierarchy-cache and move or
change its status from Pending to Archived (or the project's archive/status
token) so the CHANGE_ORDER sequencing matches the committed archive artifact
introduced in the same PR.
In
`@openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/CHANGE_VALIDATION.md`:
- Line 8: Add a single blank line immediately before the header "## Notes" so
the header is separated from the preceding list, ensuring the markdown follows
MD022 (headers surrounded by blank lines); locate the "## Notes" header in
CHANGE_VALIDATION.md and insert one blank line directly above it.
In
`@openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/design.md`:
- Around line 25-31: The implementation relies on _run_graphql_query() as the
sole upstream GitHub source but lacks integration tests and graceful failure
when the GraphQL schema changes; add an integration test suite that calls
_run_graphql_query() (or a test helper that invokes the same parameterized
GraphQL query) and asserts the presence and types of the fields issue.type,
labels, parent.number, and children[].number, and make the production path
detect missing/changed fields from the query result and fail fast (emit an
explicit error log via your logger and abort cache update) rather than silently
producing incomplete cache data.
In
`@openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/specs/agile-feature-hierarchy/spec.md`:
- Around line 3-22: The markdown headings are missing required blank lines
(MD022); add a single blank line immediately after the "Requirement: GitHub
Agile Feature Hierarchy" heading and after each "Scenario: Feature issues group
user stories under the correct epic", "Scenario: CHANGE_ORDER stays aligned with
the GitHub hierarchy", and "Scenario: Local cache is consulted before manual
hierarchy lookup" headings so each header is surrounded by a blank line to
satisfy the linter.
In
`@openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/tasks.md`:
- Around line 1-20: The tasks.md checklist for
governance-02-github-hierarchy-cache omits the mandated worktree lifecycle
steps; update the checklist (the top-level sections like "1. Change setup and
governance sync" / "3. Implementation" / "4. Verification") to include explicit
worktree lifecycle steps: add Phase 0 or expand Phase 1 to document creating a
git worktree from origin/dev, running hatch env create inside the worktree,
running pre-flight checks (hatch run smart-test-status and hatch run
contract-test-status), and add post-merge cleanup steps (git worktree remove,
git branch -d, git worktree prune) so future task artifacts follow the
repository governance workflow.
In
`@openspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/TDD_EVIDENCE.md`:
- Around line 33-34: The committed TDD evidence contains user-specific absolute
paths in the example commands (the Ruff and basedpyright invocations referencing
a local .venv and PYTHONPATH); update the lines in TDD_EVIDENCE.md to use
repository-relative, portable commands instead—e.g., invoke tools from a
project-local venv with ./venv/bin/ruff or rely on PATH and relative PYTHONPATH
like PYTHONPATH=src ruff check scripts/sync_github_hierarchy_cache.py
tests/unit/scripts/test_sync_github_hierarchy_cache.py, and similarly for
basedpyright, keeping the script and test paths
(scripts/sync_github_hierarchy_cache.py,
tests/unit/scripts/test_sync_github_hierarchy_cache.py) and tool names (ruff,
basedpyright) intact.
In
`@openspec/changes/governance-03-deterministic-agent-governance-loading/proposal.md`:
- Around line 16-20: The Markdown headings "### New Capabilities" and "###
Modified Capabilities" are missing the required blank line above them (MD022);
insert a single blank line immediately before each heading so there is an empty
line separating the previous paragraph from the headings, i.e., add a blank line
before the lines containing "### New Capabilities" and "### Modified
Capabilities" in proposal.md to satisfy the linter.
In
`@openspec/changes/governance-03-deterministic-agent-governance-loading/tasks.md`:
- Around line 30-32: The task 4.2 is marked complete but lacks the required
evidence file .specfact/code-review.json because the nold-ai/specfact-codebase
module is missing; either run the mandated command (hatch run specfact code
review run --json --out .specfact/code-review.json) in a worktree where
nold-ai/specfact-codebase is installed to produce and commit the
.specfact/code-review.json artifact, or revert the checkbox for "4.2" and add an
explicit waiver entry explaining the blocker and maintainer-approved rationale
(referencing task "4.2", the hatch command, and the missing module
nold-ai/specfact-codebase) so the PR no longer claims mandatory evidence has
been provided.
In
`@openspec/changes/profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.md`:
- Around line 10-12: The dense third bullet ("GitHub tracking is synced...")
exceeds markdown readability; edit that bullet in CHANGE_VALIDATION.md to use
reference-style links (e.g., define [`#490`]: URL, [`#365`]: URL, [`#487`]: URL at
bottom) and wrap the bullet across multiple shorter lines (each ≤120 characters)
so the text is easier to read and compliant with style guidelines; keep the
existing identifiers (`#490`, `#365`, `#487`) and ensure the reference definitions are
added after the list.
In `@openspec/changes/profile-04-safe-project-artifact-writes/design.md`:
- Around line 96-101: Add the suggested initial "protected path" CI rule set to
the design document: update the open question section about the first
protected-path CI rule set (the "protected path" CI rule set) to propose
starting with the specific paths `.vscode/settings.json`,
`.github/copilot-instructions.md`, all files matching `.cursor/rules/*.mdc`, and
any `pyproject.toml` sections owned by SpecFact, and note these as the initial
scoped set to be enforced by the first gate with allowance for future
adjustments.
In `@openspec/changes/profile-04-safe-project-artifact-writes/proposal.md`:
- Around line 19-23: The markdown linter flagged missing blank lines before the
subheadings; insert a single blank line immediately above the "### New
Capabilities" and another blank line immediately above the "### Modified
Capabilities" headings in the proposal.md content so each subheading is preceded
by an empty line (i.e., ensure a newline exists before the lines that start with
"### New Capabilities" and "### Modified Capabilities") to satisfy MD022.
In
`@openspec/changes/profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.md`:
- Around line 3-23: The markdown headings in spec.md need blank lines after them
to comply with MD022; add an empty line after each of the listed headings:
"Requirement: Init IDE SHALL preserve unrelated VS Code settings", "Scenario:
Existing non-SpecFact settings survive prompt export", "Scenario: Selective
prompt export removes only prior SpecFact-managed recommendations",
"Requirement: Init IDE SHALL fail safe on malformed settings documents", and
"Scenario: Malformed settings file blocks destructive rewrite" so each heading
is followed by a single blank line, preserving the existing paragraph and list
spacing otherwise.
In
`@openspec/changes/profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.md`:
- Around line 3-13: Add a blank line immediately after each Markdown heading to
satisfy MD022: insert an empty line after the "### Requirement: Core
materialization of module-owned IDE assets SHALL use safe project writes"
heading, after the "#### Scenario: Module-owned prompt export uses safe-write
helper for settings mutation" heading, and after the "#### Scenario:
Module-owned template copy does not silently replace existing user
customization" heading so each header is separated from its following content.
In
`@openspec/changes/profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.md`:
- Around line 1-40: Several Markdown headers in the spec (e.g., "Requirement:
Core commands SHALL classify project artifact writes by ownership and mutation
mode", "Scenario: Partial-ownership artifact cannot use implicit full
replacement", "Scenario: Unowned existing artifact fails safe", "Requirement:
Lossy project artifact mutations SHALL create recovery material", "Scenario:
Explicit replacement emits backup path", "Scenario: Failed structured merge
leaves original file untouched", "Requirement: CI SHALL detect unsafe core
writes to user-project artifacts", "Scenario: Raw overwrite path is rejected in
CI", "Scenario: Regression fixture preserves unrelated user configuration") are
missing the required blank line separation causing MD022; fix by adding a single
blank line immediately before and after each header line so every header is
surrounded by blank lines, then re-run the Markdown linter to confirm MD022
violations are resolved.
- Around line 3-14: Add a contract-first API to the safe-write helper by
defining a public function (e.g., safe_write_project_artifact) that is annotated
with `@beartype` and guarded with `@icontract` preconditions/postconditions: require
ownership_mode is one of
{"create-only","mergeable","append-managed","explicit-replace"} and that
target_path is a Path and content is str|dict, ensure a postcondition that a
backup is created when ownership_mode == "explicit-replace", and specify a typed
WriteResult return (success/failure, backup path, conflict details); update
callers in ide_setup.py to call this function instead of directly using
write_text() so ownership validation and fail-safe behavior are enforced at call
time.
- Around line 29-40: The design doc correctly proposes AST-based detection of
unsafe writes but lacks a concrete allowlist and enforcement steps; update the
implementation plan and CI rules to (1) add a curated protected-path allowlist
(e.g., ".vscode/settings.json", ".specfact/modules.yaml" and any other declared
user-project artifact paths) documented in the spec, (2) implement AST-pattern
checks (match Path.write_text/Path.write_bytes calls) targeting code in
src/specfact_cli/utils/ide_setup.py and src/specfact_cli/commands/init*.py (use
ast-grep or similar) and treat uses not routed through the sanctioned safe-write
helper as failures, and (3) add regression fixtures that run init/setup flows
against sample user configs to assert only SpecFact-managed sections change;
document the protected paths and the chosen analysis tool in the design note.
In `@openspec/changes/profile-04-safe-project-artifact-writes/tasks.md`:
- Around line 21-28: Add a new "5. Worktree cleanup" section after item 4.6 that
documents the mandated post-merge cleanup steps: 5.1 remove the worktree (e.g.,
git worktree remove
../specfact-cli-worktrees/bugfix/profile-04-safe-project-artifact-writes), 5.2
delete the local branch (git branch -d
bugfix/profile-04-safe-project-artifact-writes), and 5.3 prune worktree refs
(git worktree prune); update TDD_EVIDENCE.md to record the cleanup completion
and reference this checklist alongside the existing 4.x verification steps.
- Around line 16-19: The public safe-write helper lacks runtime contracts and a
structured return type; implement a contract-first API: add a frozen dataclass
WriteResult (fields: success, target_path, backup_path, conflict_reason) and
change safe_write_project_artifact to use `@beartype` for type checks and
`@icontract.require/ensure` to validate ownership_mode ∈
{"create-only","mergeable","append-managed","explicit-replace"} and
postconditions on result; update callers (notably the mutation path in
src/specfact_cli/utils/ide_setup.py that writes .vscode/settings.json) to route
through safe_write_project_artifact and handle WriteResult (preserve unrelated
settings, create backups for explicit-replace, and surface conflict_reason
instead of relying on exceptions).
In `@openspec/specs/agile-feature-hierarchy/spec.md`:
- Line 7: The MD022 and line-length issues are caused by the new "####" scenario
heading not being surrounded by blank lines and the long requirement sentence
("The project governance workflow SHALL maintain a three-level GitHub planning
hierarchy of Epic -> Feature -> User Story...") exceeding 120 chars; fix by
inserting a blank line before and after the "####" heading and reflowing that
long sentence into multiple lines under 120 characters (wrap after logical
breaks like "Epic -> Feature -> User Story" or at clause boundaries), and apply
the same blank-line and wrapping fixes to the other affected scenario block
lines (around the same "Epic -> Feature -> User Story" requirement at lines
21-25).
In `@openspec/specs/github-hierarchy-cache/spec.md`:
- Around line 3-6: The top-of-file Markdown headings need blank lines before and
after them to satisfy MD022; update the section around the headings "##
Purpose", "## Requirements", and "### Requirement: Repository hierarchy cache
sync" so each heading is preceded and followed by an empty line (e.g., add a
blank line before "## Purpose", one after its content and before "##
Requirements", and ensure "### Requirement: Repository hierarchy cache sync"
also has blank lines surrounding it).
- Around line 3-5: The spec's canonical Purpose section still contains the
placeholder "TBD"; update the "Purpose" heading in spec.md by replacing the
`TBD` text with a concise, final purpose statement that summarizes the archived
change (referencing the governance-02-github-hierarchy-cache archive) and
clarifies the spec's intent and scope so the openspec source-of-truth is no
longer ambiguous.
In `@scripts/check_doc_frontmatter.py`:
- Around line 434-456: The suggest_frontmatter() function currently uses
json.dumps() (e.g., layout_val, permalink_val, description_val) which emits
JSON-style quoting; change it to emit YAML-native scalars by writing plain YAML
lines (e.g., build optional_lines and the frontmatter string using quoted YAML
scalars like description: "..." and permalink: /path or permalink: "/path" as
appropriate) instead of json.dumps, ensuring variables like layout_val,
permalink_val, description_val and canonical_id are safely escaped/quoted for
YAML when interpolated.
In `@tests/unit/scripts/test_sync_github_hierarchy_cache.py`:
- Around line 381-396: The test
test_default_repo_name_falls_back_when_git_unavailable currently manually clears
_load_script_module cache and pops sync_github_hierarchy_cache from sys.modules
only at the end, which can leave state corrupted if an assertion fails; replace
the manual cleanup by adding a pytest fixture (e.g., cleared_module_cache) that
clears _load_script_module.cache_clear() and removes
sys.modules["sync_github_hierarchy_cache"] before yielding and repeats the same
cleanup in teardown, then accept this fixture in the test signature and remove
the trailing manual cache_clear/sys.modules.pop lines so cleanup always runs
even on failure; keep the monkeypatch of subprocess.run as-is.
🪄 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: 947bf80d-101c-4f92-abd2-d7e5800c001e
📒 Files selected for processing (52)
.cursor/rules/automatic-openspec-workflow.mdc.cursor/rules/session_startup_instructions.mdc.cursorrules.github/copilot-instructions.mdAGENTS.mdCLAUDE.mddocs/.doc-frontmatter-enforceddocs/_data/nav.ymldocs/agent-rules/05-non-negotiable-checklist.mddocs/agent-rules/10-session-bootstrap.mddocs/agent-rules/20-repository-context.mddocs/agent-rules/30-worktrees-and-branching.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/50-quality-gates-and-review.mddocs/agent-rules/60-github-change-governance.mddocs/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/80-current-guidance-catalog.mddocs/agent-rules/INDEX.mddocs/contributing/frontmatter-schema.mdopenspec/CHANGE_ORDER.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/.openspec.yamlopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/design.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/proposal.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/specs/agile-feature-hierarchy/spec.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/archive/2026-04-09-governance-02-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/.openspec.yamlopenspec/changes/governance-03-deterministic-agent-governance-loading/TDD_EVIDENCE.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/design.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/proposal.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/specs/agent-governance-loading/spec.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-deterministic-agent-governance-loading/tasks.mdopenspec/changes/profile-04-safe-project-artifact-writes/.openspec.yamlopenspec/changes/profile-04-safe-project-artifact-writes/CHANGE_VALIDATION.mdopenspec/changes/profile-04-safe-project-artifact-writes/design.mdopenspec/changes/profile-04-safe-project-artifact-writes/proposal.mdopenspec/changes/profile-04-safe-project-artifact-writes/specs/init-ide-prompt-source-selection/spec.mdopenspec/changes/profile-04-safe-project-artifact-writes/specs/module-owned-ide-prompts/spec.mdopenspec/changes/profile-04-safe-project-artifact-writes/specs/project-artifact-write-safety/spec.mdopenspec/changes/profile-04-safe-project-artifact-writes/tasks.mdopenspec/config.yamlopenspec/specs/agile-feature-hierarchy/spec.mdopenspec/specs/github-hierarchy-cache/spec.mdscripts/check_doc_frontmatter.pyscripts/sync_github_hierarchy_cache.pytests/helpers/doc_frontmatter_types.pytests/unit/docs/test_agent_rules_governance.pytests/unit/scripts/test_doc_frontmatter/test_agent_rule_frontmatter.pytests/unit/scripts/test_sync_github_hierarchy_cache.py
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@scripts/sync_github_hierarchy_cache.py`:
- Around line 579-596: Wrap the call to sync_cache in main() with a try/except
that catches RuntimeError (and any other expected exceptions like subprocess
timeouts if they surface as RuntimeError) and handle failures by writing an
error message including the exception details to stderr (use sys.stderr.write)
and returning a non-zero exit code (e.g., return 1); leave the existing success
path that writes to stdout and returns 0 untouched so main() still satisfies the
`@ensure` non-negative exit requirement.
🪄 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: f82bda92-4421-4d74-957d-2473e4d6c0c3
📒 Files selected for processing (7)
.cursor/rules/session_startup_instructions.mdcAGENTS.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/70-release-commit-and-docs.mdscripts/check_doc_frontmatter.pyscripts/sync_github_hierarchy_cache.pytests/unit/scripts/test_sync_github_hierarchy_cache.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). (2)
- GitHub Check: Quality Gates (Advisory)
- GitHub Check: Compatibility (Python 3.11)
🧰 Additional context used
📓 Path-based instructions (9)
**/*.{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:
AGENTS.mddocs/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/40-openspec-and-tdd.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:
AGENTS.md
AGENTS.md
📄 CodeRabbit inference engine (.cursorrules)
Check the current status and development workflow in
AGENTS.mdwhen starting a new task.AGENTS.mdis the authoritative source for development workflow and overrides other sources
Files:
AGENTS.md
docs/**/*.md
📄 CodeRabbit inference engine (.cursor/rules/spec-fact-cli-rules.mdc)
Update architecture documentation in docs/ for architecture changes, state machine documentation for FSM modifications, interface documentation for API changes, and configuration guides for configuration changes. DO NOT create internal docs in specfact-cli repo folder that should not be visible to end users; use the respective internal repository instead.
Files:
docs/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/40-openspec-and-tdd.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/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/40-openspec-and-tdd.md
**/*.py
📄 CodeRabbit inference engine (.cursor/rules/python-github-rules.mdc)
**/*.py: Maintain minimum 80% test coverage, with 100% coverage for critical paths in Python code
Use clear naming and self-documenting code, preferring clear names over comments
Ensure each function/class has a single clear purpose (Single Responsibility Principle)
Extract common patterns to avoid code duplication (DRY principle)
Apply SOLID object-oriented design principles in Python code
Use type hints everywhere in Python code and enable basedpyright strict mode
Use Pydantic models for data validation and serialization in Python
Use async/await for I/O operations in Python code
Use context managers for resource management in Python
Use dataclasses for simple data containers in Python
Enforce maximum line length of 120 characters in Python code
Use 4 spaces for indentation in Python code (no tabs)
Use 2 blank lines between classes and 1 blank line between methods in Python
Organize imports in order: Standard library → Third party → Local in Python files
Use snake_case for variables and functions in Python
Use PascalCase for class names in Python
Use UPPER_SNAKE_CASE for constants in Python
Use leading underscore (_) for private methods in Python classes
Use snake_case for Python file names
Enable basedpyright strict mode with strict type checking configuration in Python
Use Google-style docstrings for functions and classes in Python
Include comprehensive exception handling with specific exception types in Python code
Use logging with structured context (extra parameters) instead of print statements
Use retry logic with tenacity decorators (@retry) for operations that might fail
Use Pydantic BaseSettings for environment-based configuration in Python
Validate user input using Pydantic validators in Python models
Use@lru_cacheand Redis-based caching for expensive calculations in Python
Run code formatting with Black (120 character line length) and isort in Python
Run type checking with basedpyright on all Python files
Run linting with ruff and pylint on all Pyth...
Files:
scripts/check_doc_frontmatter.pytests/unit/scripts/test_sync_github_hierarchy_cache.pyscripts/sync_github_hierarchy_cache.py
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: subprocess safety, Hatch integration, and parity with documented
quality gates (format, type-check, module signing).
Files:
scripts/check_doc_frontmatter.pyscripts/sync_github_hierarchy_cache.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/scripts/test_sync_github_hierarchy_cache.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 oraclesSecret redaction via
LoggerSetup.redact_secretsmust be covered by unit tests
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.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/scripts/test_sync_github_hierarchy_cache.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/scripts/test_sync_github_hierarchy_cache.py
🧠 Learnings (41)
📓 Common learnings
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: `AGENTS.md` is the authoritative source for development workflow and overrides any skill, command, or OpenSpec workflow instructions. When there is a conflict between AGENTS.md and any other source, always follow AGENTS.md.
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.
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: Ensure an OpenSpec change (new or delta) exists for any code modification in specfact-cli (`src/`, `tools/`, tests, or significant docs) unless user explicitly opts out with 'skip openspec', 'direct implementation', 'simple fix', or similar
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: When creating OpenSpec changes for specfact-cli, use unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas in `changes/<id>/specs/<capability>/spec.md`
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 @(README.md|AGENTS.md) : Check README.md and AGENTS.md for current project status and development guidelines. Review .cursor/rules/ for detailed development standards and testing procedures.
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
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: .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.
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Before modifying application code, follow the OpenSpec workflow in `.cursor/rules/automatic-openspec-workflow.mdc`: read and apply `openspec/config.yaml`, ensure an OpenSpec change (new or delta) exists and is validated, then implement. Exception: only when the user explicitly says 'skip openspec', 'direct implementation', 'simple fix', or similar.
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
URL:
File: .cursor/rules/automatic-openspec-workflow.mdc:undefined-undefined
Timestamp: 2026-04-10T22:00:56.827Z
Learning: The OpenSpec workflow applies to every code modification request in specfact-cli that adds features, modifies existing code, updates functionality, changes code structure, refactors code, implements new capabilities, enhances existing functionality, removes features, fixes bugs, adds tests, updates comments/formatting, or updates configuration (skip only if user explicitly says 'skip openspec', 'direct implementation', 'simple fix', or 'just fix it')
Learnt from: CR
URL:
File: .cursor/rules/automatic-openspec-workflow.mdc:undefined-undefined
Timestamp: 2026-04-10T22:00:56.827Z
Learning: Before creating a new OpenSpec change, always search for existing related changes by navigating to specfact-cli workspace, running openspec list, and reviewing change IDs and descriptions to check for overlaps and avoid duplicate work
Learnt from: CR
URL:
File: .cursor/rules/automatic-openspec-workflow.mdc:undefined-undefined
Timestamp: 2026-04-10T22:00:56.827Z
Learning: When a code modification request contains vague requirements (e.g., 'intuitive', 'fast', 'better', 'improved') or unclear architecture patterns, ask the user for specific metrics, concrete behaviors, or clarification about integration points and existing patterns before creating or updating an OpenSpec change
Learnt from: CR
URL:
File: .cursor/rules/automatic-openspec-workflow.mdc:undefined-undefined
Timestamp: 2026-04-10T22:00:56.827Z
Learning: Use spec-driven development (SDD) and test-driven development (TDD) discipline when implementing OpenSpec changes: apply /opsx:apply <change-id> workflow, implement tests first, then code, update task checklists, and ensure contract-first approach with contract decorators included in OpenSpec changes
Learnt from: CR
URL:
File: .cursor/rules/automatic-openspec-workflow.mdc:undefined-undefined
Timestamp: 2026-04-10T22:00:56.827Z
Learning: When the OpenSpec CLI is not available or specfact-cli workspace/openspec/ directory is not accessible, do not modify application code unless the user explicitly confirms to proceed without OpenSpec by saying 'Proceed without OpenSpec' or similar; inform the user that no code changes will be made until an OpenSpec change exists
Learnt from: CR
URL:
File: .cursor/rules/session_startup_instructions.mdc:undefined-undefined
Timestamp: 2026-04-10T22:01:02.268Z
Learning: Bootstrap Cursor sessions by reading `AGENTS.md` and the canonical agent governance documents in `docs/agent-rules/` (specifically INDEX.md and 05-non-negotiable-checklist.md) instead of relying on stale inline reminders
Learnt from: CR
URL:
File: .cursor/rules/session_startup_instructions.mdc:undefined-undefined
Timestamp: 2026-04-10T22:01:02.268Z
Learning: Detect repository root, branch, and worktree state before implementation
Learnt from: CR
URL:
File: .cursor/rules/session_startup_instructions.mdc:undefined-undefined
Timestamp: 2026-04-10T22:01:02.268Z
Learning: When designing or scoping an OpenSpec change and a sibling `specfact-cli-internal/` checkout exists, follow internal wiki guidance by reading `wiki/hot.md`, `wiki/graph.md`, and relevant `wiki/concepts/*.md` files from the internal checkout; do not import wiki text into the main repository
Learnt from: CR
URL:
File: .cursor/rules/session_startup_instructions.mdc:undefined-undefined
Timestamp: 2026-04-10T22:01:02.268Z
Learning: After merges that ship OpenSpec- or GitHub-related work when `specfact-cli-internal` exists, run `python3 scripts/wiki_openspec_gh_status.py` and `python3 scripts/wiki_rebuild_graph.py` if `docs/agent-rules/` frontmatter files changed significantly
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: `AGENTS.md` is the **authoritative source** for development workflow and **OVERRIDES** any skill, command, or OpenSpec workflow instructions. When there is a conflict between AGENTS.md and any other source (including `/opsx:*` commands, `.cursor/skills/`, or OpenSpec defaults), **ALWAYS follow AGENTS.md**
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: Before executing ANY workflow command (`/opsx:ff`, `/opsx:apply`, `/opsx:continue`, etc.), perform the Pre-Execution Checklist: verify Git Worktree setup, TDD Evidence creation, Documentation updates, Module Signing requirements, and state confirmation of AGENTS.md compliance
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
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` (not `git checkout -b`). Allowed types: `feature/`, `bugfix/`, `hotfix/`, `chore/`. Forbidden in worktrees: `dev`, `main`. After creating worktree, run `hatch env create` and pre-flight checks (`hatch run smart-test-status`, `hatch run contract-test-status`)
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: After any code changes, follow this workflow in order: (1) Apply linting and formatting with `hatch run format`, (2) Type checking with `hatch run type-check` (basedpyright), (3) Run contract tests with `hatch run contract-test`, (4) Run full test suite with `hatch test --cover -v`, (5) Verify all tests pass and contracts are satisfied, (6) Fix issues and repeat until all tests pass
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: All changes must be made via Pull Requests to `dev` or `main`. Direct commits to protected branches are not allowed
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: Only write high-value comments if at all. Avoid talking to the user through comments
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: Work directly with major artifacts (strategic plans, implementation plans, etc.). Do NOT create plans for plans, tracking documents for tracking documents, or status artifacts for status artifacts. Only create new documentation artifacts when they add clear value and are not redundant with existing artifacts. Update existing artifacts with status annotations rather than creating separate status files
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: Before modifying application code, follow the OpenSpec workflow in `.cursor/rules/automatic-openspec-workflow.mdc`: read and apply `openspec/config.yaml`, ensure an OpenSpec change (new or delta) exists and is validated, then implement. Exception: only when the user explicitly says 'skip openspec', 'direct implementation', 'simple fix', or similar
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: Always finish each output by listing: (1) Which rulesets have been applied (e.g., `.cursorrules`, `AGENTS.md`, specific `.cursor/rules/*.mdc`), (2) Confirmation of Git Worktree Policy compliance (if applicable), (3) Which AI (LLM) provider and model version you are using with accurate version information
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: For `/opsx:ff` (Fast-Forward Change Creation), add to tasks.md explicitly: Worktree creation task as Step 1 (not just 'create branch'), TDD_EVIDENCE.md tracking task in section 2 (Tests), Documentation research task per openspec/config.yaml, Module signing quality gate if applicable, Worktree cleanup steps in final section
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: For `/opsx:apply` (Implementation), verify AGENTS.md requirements before implementing each task: Confirm you are IN a worktree (not primary checkout) before modifying code, Record failing test evidence in TDD_EVIDENCE.md BEFORE implementing, Record passing test evidence AFTER implementation, Run quality gates from worktree (format, type-check, contract-test), Use GPG-signed commits (`git commit -S`), Make PR to `dev` branch (never direct push)
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: For `/opsx:continue` (Resume Change), verify on continuation: If change was created before this session, check if worktree exists using `git worktree list`. If worktree missing but needed for implementation, create it before proceeding. Update tasks.md to include worktree steps if missing
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-10T22:01:28.839Z
Learning: For `/opsx:archive` (Archive Change), include in final tasks: Module signing and cleanup requirements. Agents MUST run `openspec archive <change-id>` from repo root (no manual `mv` under `openspec/changes/archive/`)
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-10T22:01:33.717Z
Learning: Use AGENTS.md as the mandatory bootstrap surface and docs/agent-rules/INDEX.md as the canonical governance dispatcher
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-10T22:01:33.717Z
Learning: When a sibling internal repository exists (e.g., ../specfact-cli-internal/), read its wiki/ files by absolute path before designing an OpenSpec change, referencing Strategic context in AGENTS.md and docs/agent-rules/40-openspec-and-tdd.md
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-10T22:01:33.717Z
Learning: Enforce the clean-code review gate through `hatch run specfact code review run --json --out .specfact/code-review.json`
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-10T22:01:33.717Z
Learning: Work belongs on feature/*, bugfix/*, hotfix/*, or chore/* branches, normally in a worktree
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-10T22:01:33.717Z
Learning: The full governance rules live in docs/agent-rules/; do not treat this file as a complete standalone handbook
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Read AGENTS.md, docs/agent-rules/INDEX.md, and docs/agent-rules/05-non-negotiable-checklist.md before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Detect repository root, active branch, and worktree state before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Reject implementation from the `dev` or `main` checkout unless the user explicitly overrides that rule
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Load any additional rule files required by the applicability matrix in docs/agent-rules/INDEX.md before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Work in a git worktree unless the user explicitly overrides that rule
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Treat a provided OpenSpec change id as candidate scope, not automatic permission to proceed
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Verify the selected change against current repository reality and dependency state before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Do not auto-refine stale or ambiguous changes without the user
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Perform `spec -> tests -> failing evidence -> code -> passing evidence` in that order for behavior changes
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Require public GitHub metadata completeness before implementation when linked issue workflow applies: parent, labels, project assignment, blockers, and blocked-by relationships
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: If a linked GitHub issue is already `in progress`, pause and ask for clarification before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Run the required verification and quality gates for the touched scope before finalization
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Fix SpecFact code review findings, including warnings, unless a rare explicit exception is documented
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Treat the clean-code compliance gate as mandatory: the review surface enforces `naming`, `kiss`, `yagni`, `dry`, and `solid` categories and blocks regressions
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Enforce module signatures and version bumps when signed module assets or manifests are affected
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: Design and dependency context may live in a sibling internal repository; read wiki paths using absolute paths and treat the wiki as read-only context
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-10T22:01:45.172Z
Learning: After merges that ship OpenSpec or related work, run internal wiki scripts from the sibling checkout including `wiki_rebuild_graph.py` when frontmatter churn is large
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-10T22:01:49.560Z
Learning: Follow AGENTS.md as the primary bootstrap contract, then load canonical governance docs in docs/agent-rules/INDEX.md
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-10T22:01:49.560Z
Learning: Treat canonical rule docs in docs/agent-rules/ as the source of truth for worktree policy, OpenSpec gating, GitHub completeness checks, TDD order, quality gates, versioning, and documentation rules
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-10T22:01:49.560Z
Learning: Read wiki files by absolute path from sibling internal repository wiki/ trees before designing a new OpenSpec change, and keep wiki content out of the public repository
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-10T22:01:49.560Z
Learning: Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, solid) in code review
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-10T22:01:49.560Z
Learning: Treat clean-code regressions as blocking until they are fixed or explicitly justified
📚 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: `AGENTS.md` is the authoritative source for development workflow and overrides any skill, command, or OpenSpec workflow instructions. When there is a conflict between AGENTS.md and any other source, always follow AGENTS.md.
Applied to files:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.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 @(README.md|AGENTS.md) : Check README.md and AGENTS.md for current project status and development guidelines. Review .cursor/rules/ for detailed development standards and testing procedures.
Applied to files:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.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:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.mdscripts/check_doc_frontmatter.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: When starting a new task, first check the project overview and current status in `README.md` and `AGENTS.md`.
Applied to files:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.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:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.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:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/40-openspec-and-tdd.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:
AGENTS.mddocs/agent-rules/40-openspec-and-tdd.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 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:
AGENTS.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:
AGENTS.md
📚 Learning: 2026-03-25T21:32:57.944Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/spec-fact-cli-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:57.944Z
Learning: Applies to src/**/agent*.py : All agent components must implement the standardized BaseAgent interface.
Applied to files:
AGENTS.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:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/70-release-commit-and-docs.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:
AGENTS.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:
AGENTS.mddocs/agent-rules/40-openspec-and-tdd.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Before executing any workflow command (`/opsx:ff`, `/opsx:apply`, `/opsx:continue`, etc.), perform a pre-execution checklist: verify Git Worktree creation, TDD evidence documentation, user-facing documentation updates, module signing verification, and confirm AGENTS.md compliance.
Applied to files:
AGENTS.md.cursor/rules/session_startup_instructions.mdc
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Before modifying application code, follow the OpenSpec workflow in `.cursor/rules/automatic-openspec-workflow.mdc`: read and apply `openspec/config.yaml`, ensure an OpenSpec change (new or delta) exists and is validated, then implement. Exception: only when the user explicitly says 'skip openspec', 'direct implementation', 'simple fix', or similar.
Applied to files:
AGENTS.md.cursor/rules/session_startup_instructions.mdcdocs/agent-rules/40-openspec-and-tdd.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:
AGENTS.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:
AGENTS.mddocs/agent-rules/40-openspec-and-tdd.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 starting a new chat session, get familiar with the build and test guide (refer to `.cursor/rules/testing-and-build-guide.mdc`).
Applied to files:
.cursor/rules/session_startup_instructions.mdc
📚 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 `GEMINI.md` for session-specific goals or instructions when using GEMINI CLI
Applied to files:
.cursor/rules/session_startup_instructions.mdc
📚 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 `CLAUDE.md` for session-specific goals or instructions when using Claude CLI
Applied to files:
.cursor/rules/session_startup_instructions.mdc
📚 Learning: 2026-03-25T21:33:15.296Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/testing-and-build-guide.mdc:0-0
Timestamp: 2026-03-25T21:33:15.296Z
Learning: Applies to CHANGELOG.md : Update CHANGELOG.md to document all significant changes under Added, Fixed, Changed, or Removed sections when making a version change
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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:
docs/agent-rules/70-release-commit-and-docs.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: Applies to **/module-package.yaml : Module signature verification is required before PR creation; run `hatch run ./scripts/verify-modules-signature.py --require-signature`
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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 @(pyproject.toml|setup.py|src/__init__.py|src/specfact_cli/__init__.py) : Maintain synchronized versions across pyproject.toml, setup.py, src/__init__.py, and src/specfact_cli/__init__.py.
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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 {pyproject.toml,setup.py,src/specfact_cli/__init__.py} : Sync version across pyproject.toml, setup.py, and src/specfact_cli/__init__.py whenever bumping version
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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: 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/agent-rules/70-release-commit-and-docs.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:
docs/agent-rules/70-release-commit-and-docs.md
📚 Learning: 2026-03-25T21:32:29.182Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/python-github-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:29.182Z
Learning: Applies to {src/__init__.py,pyproject.toml,setup.py} : Maintain version synchronization across src/__init__.py, pyproject.toml, and setup.py
Applied to files:
docs/agent-rules/70-release-commit-and-docs.md
📚 Learning: 2026-03-25T21:33:22.650Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/yaml-and-workflows.md:0-0
Timestamp: 2026-03-25T21:33:22.650Z
Learning: Run `hatch run yaml-check-all` in CI and before pull requests to validate all YAML and workflow files
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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:
docs/agent-rules/70-release-commit-and-docs.md
📚 Learning: 2026-03-25T21:32:38.156Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/session_startup_instructions.mdc:0-0
Timestamp: 2026-03-25T21:32:38.156Z
Learning: Applies to {CHANGELOG.md,pyproject.toml,setup.py,src/__init__.py} : When releasing, update `CHANGELOG.md`, `pyproject.toml`, `setup.py`, and `src/__init__.py`
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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: Applies to CHANGELOG.md : Keep `CHANGELOG.md` updated with every meaningful change following Keep a Changelog format (`Added`, `Changed`, `Fixed`, `Removed`, `Security`); each version entry must match the version in `pyproject.toml`
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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 CHANGELOG.md : Update CHANGELOG.md with every meaningful change using Keep a Changelog format (Added, Changed, Fixed, Removed, Security), synced in same commit as version bump
Applied to files:
docs/agent-rules/70-release-commit-and-docs.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:
docs/agent-rules/40-openspec-and-tdd.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:
docs/agent-rules/40-openspec-and-tdd.md
📚 Learning: 2026-03-25T21:31:01.827Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursorrules:0-0
Timestamp: 2026-03-25T21:31:01.827Z
Learning: Applies to TDD_EVIDENCE.md : For tasks involving behavior changes, create and update `TDD_EVIDENCE.md` per AGENTS.md 'Hard Gate: Strict TDD Order', recording failing test evidence before implementation and passing test evidence after implementation.
Applied to files:
docs/agent-rules/40-openspec-and-tdd.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:
docs/agent-rules/40-openspec-and-tdd.md
📚 Learning: 2026-03-25T21:31:33.886Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/automatic-openspec-workflow.mdc:0-0
Timestamp: 2026-03-25T21:31:33.886Z
Learning: When creating OpenSpec changes for specfact-cli, use unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas in `changes/<id>/specs/<capability>/spec.md`
Applied to files:
docs/agent-rules/40-openspec-and-tdd.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:
docs/agent-rules/40-openspec-and-tdd.md
📚 Learning: 2026-03-25T21:32:29.182Z
Learnt from: CR
Repo: nold-ai/specfact-cli PR: 0
File: .cursor/rules/python-github-rules.mdc:0-0
Timestamp: 2026-03-25T21:32:29.182Z
Learning: Applies to **/test_*.py : Ensure each test is independent and repeatable with no shared state between tests
Applied to files:
tests/unit/scripts/test_sync_github_hierarchy_cache.py
🪛 LanguageTool
AGENTS.md
[style] ~9-~9: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...NDEX.md](docs/agent-rules/INDEX.md). 3. Read [docs/agent-rules/05-non-negotiable-che...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~12-~12: The official name of this software platform is spelled with a capital “H”.
Context: ...GitHub hierarchy metadata is needed and .specfact/backlog/github_hierarchy_cache.md is missing or stale...
(GITHUB)
[uncategorized] ~12-~12: The official name of this software platform is spelled with a capital “H”.
Context: ...dis missing or stale, refresh it withpython scripts/sync_github_hierarchy_cache.py`. 7. Load any additi...
(GITHUB)
🔀 Multi-repo context nold-ai/specfact-cli-modules
Linked repositories findings
nold-ai/specfact-cli-modules
-
Archive enforcement / consumers of archive semantics
- openspec/config.yaml explicitly requires archiving via the CLI: "Archive changes only via
openspec archive <change-id>" — tooling must not rely on manual folder moves. [::nold-ai/specfact-cli-modules::openspec/config.yaml:40] - CLAUDE.md documents the same MUST and forbids manual moves into
openspec/changes/archive/. [::nold-ai/specfact-cli-modules::CLAUDE.md:90] - AGENTS.md also records the same archiving MUST and related restrictions. [::nold-ai/specfact-cli-modules::AGENTS.md:117]
- docs/integrations/devops-adapter-overview.md describes adapters reading from openspec/changes/ and notes archived proposals live under openspec/changes/archive/ (and --include-archived behavior). Review adapter behavior to ensure it matches the new CLI-driven archive lifecycle. [::nold-ai/specfact-cli-modules::docs/integrations/devops-adapter-overview.md:1138-1183]
- openspec/config.yaml explicitly requires archiving via the CLI: "Archive changes only via
-
Scripts and automation that inspect or report on openspec paths
- scripts/sync-dev-from-main.sh inspects "openspec/changes/" and reports modified openspec files after merges — ensure it remains correct under CLI archive semantics (it currently detects changes via git diff on openspec/changes/). [::nold-ai/specfact-cli-modules::scripts/sync-dev-from-main.sh:96-98]
- Multiple packages/specfact-project bridge/sync runtime modules read/write OpenSpec change proposals and reference archive directories:
- packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_save_openspec_parts_impl.py references an "archive" dir under openspec changes. [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_save_openspec_parts_impl.py:39]
- packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_read_openspec_proposals.py references an "archive" dir. [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync_read_openspec_proposals.py:170]
- The primary BridgeSync implementation and many sync helpers read/write from openspec/changes/ (bridge_sync.py and many submodules). These are direct consumers of the change lifecycle and may need to rely on the openspec CLI archive operation or handle archived proposals consistently. [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync_runtime/bridge_sync.py:490,1127-1129] and many other files under packages/specfact-project/src/specfact_project/sync_runtime/ (see multiple matches)
- Several import/sync command modules call into BridgeSync and resolve artifact paths under openspec/changes/ (import_cmd/commands.py and sync/commands.py). [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/import_cmd/commands.py:2097,2181] [::nold-ai/specfact-cli-modules::packages/specfact-project/src/specfact_project/sync/commands.py:609]
-
Documentation & prompts referencing archive/cache-first rules
- docs/guides/openspec-journey.md and other guides show workflows that read from openspec/changes/; some content notes archived proposals are excluded by default and require --include-archived. Confirm docs remain consistent with the enforced CLI archive step. [::nold-ai/specfact-cli-modules::docs/guides/openspec-journey.md:368] [::nold-ai/specfact-cli-modules::docs/integrations/devops-adapter-overview.md:1138]
- packages/specfact-backlog and prompts reference reading openspec/changes/ including archive. [::nold-ai/specfact-cli-modules::packages/specfact-backlog/resources/prompts/specfact.sync-backlog.md:124,286]
-
Tests & code-review tooling references
- Unit tests reference BridgeSync and other sync runtime modules that consume openspec change artifacts; these tests may need to account for any behavioral changes where archiving must be performed by the CLI rather than file moves. [::nold-ai/specfact-cli-modules::tests/unit/sync_runtime/test_bridge_sync_speckit_backlog.py:18] and other test files
Summary / impact:
- There are numerous consumers (adapters, sync/runtime BridgeSync code, import/export commands, scripts, docs, and tests) that read/write or otherwise assume the layout under openspec/changes/ and the presence/absence of archived proposals. The repo contains scripts (e.g., scripts/sync-dev-from-main.sh) and code paths that detect or report changed OpenSpec files via filesystem/git diffs; these consumers should be reviewed to ensure they remain compatible with the new rule that archiving is performed via
openspec archive <change-id>(i.e., tools must not perform manual mv/rename into openspec/changes/archive/ and should call or respect the CLI archive operation or its semantics). - Adapters and sync code that exclude archived proposals by default (and support --include-archived) are present; verify their usage of archive detection matches the new permitted archive flags and validation constraints introduced by the PR.
This was referenced Apr 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Merges
devintomain, including the governance and GitHub hierarchy work called out for this release, plus all other commits already ondevand not yet onmain.Highlighted changes
AGENTS.md, rule index, frontmatter, cache-first bootstrap (#493)openspec archivefor finalized changesScope
origin/main..(origin/dev) is 381 commits (includes merge commits and fulldevdelta vsmain).Checklist
Made with Cursor