Conversation
Complete OpenSpec change governance-04-deterministic-agent-governance-loading: - Compact AGENTS.md/CLAUDE.md bootstrap; Cursor/Copilot alias surfaces - Canonical docs/agent-rules/ INDEX and domain rule files; docs nav - validate_agent_rule_applies_when.py; pre-commit and hierarchy-cache hardening - Unit tests for agent rules, applies_when validator, and cache script - openspec/config.yaml and change artifacts (TDD_EVIDENCE, validation) Refs: #181, #163, #178; nold-ai/specfact-cli#494 Made-with: Cursor
📝 WalkthroughPull Request Summary: Deterministic Agent Governance Loading (governance-04)Bundle and module surface
Manifest and integrity
Cross-repo / compatibility
Docs: site & documentation-url contract
Scripts and tooling impact
Tests and validation
OpenSpec change ID and coverage
Impact summary for maintainers
WalkthroughAdds a deterministic agent-governance bootstrap: AGENTS.md now delegates to a new docs/agent-rules INDEX which loads numbered rule files (05–80). Includes validator CLI, pre-commit pipeline restructuring, GitHub-hierarchy cache improvements, workspace env helpers, tests, and OpenSpec bookkeeping for governance-04. Changes
Sequence Diagram(s)sequenceDiagram
participant Agent
participant Repo as "Repository (docs + scripts)"
participant Validator as "Validator CLI"
participant Cache as "sync_github_hierarchy_cache.py"
participant GitHub
Agent->>Repo: Read `AGENTS.md`
Agent->>Repo: Load `docs/agent-rules/INDEX.md`
Repo-->>Agent: INDEX lists applicable rule files (05..80)
Agent->>Repo: Load applicable rule files
Agent->>Validator: Optionally run `validate-agent-rule-signals`
Agent->>Cache: Check `.specfact/backlog/github_hierarchy_cache.md`
Cache->>GitHub: Fetch hierarchy if missing/stale
GitHub-->>Cache: Return hierarchy
Cache-->>Agent: Write/update cache
Agent->>Repo: Enforce pre-commit quality-gates (Block1 -> Block2)
Agent->>Repo: Follow TDD/OpenSpec flows per loaded rules
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
djm81
added
enhancement
![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: 1270fe9210
ℹ️ 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: 7
🤖 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/30-worktrees-and-branching.md`:
- Line 43: Remove the host-specific absolute path "/home/dom/git/nold-ai/" from
the canonical policy sentence and replace it with a generic description or
placeholder (e.g., "your-repo-root" or "REPO_ROOT") so the example remains
portable; keep the mention of the relative worktree path
"../specfact-cli-modules-worktrees/" and clarify that the absolute worktree root
should be derived from the repository parent directory rather than hardcoding a
host-specific path.
In `@docs/agent-rules/70-release-commit-and-docs.md`:
- Line 47: The docs reference the wrong script name; update the publish
pre-check command to call the actual entrypoint scripts/publish_module.py (not
publish-module.py). Replace the example line "python scripts/publish-module.py
--bundle <bundle>" with "python scripts/publish_module.py --bundle <bundle>" so
the CLI example matches the repository entrypoint.
In
`@openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md`:
- Line 15: Replace host-specific absolute paths in validation artifacts by
substituting hardcoded prefixes like "/home/dom/" in the `git worktree repair
...` evidence lines (and the other similar evidence lines) with a neutral
placeholder (e.g. "<USER_HOME>" or "<WORKTREE_PATH>") or a relative path; update
each occurrence of the literal path string
`/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-04-deterministic-agent-governance-loading`
(and the other two similar lines) so the output is environment-agnostic and
suitable for CI/contributor logs.
In
`@openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md`:
- Line 16: Task 2.3 is still unchecked even though tasks 3.1–3.7 are done;
update TDD_EVIDENCE.md to record the failing-first evidence (or mark 2.3
complete if that evidence already exists elsewhere). Open TDD_EVIDENCE.md and
add a short entry referencing the failing state you observed (e.g., validation
hooks failing on missing docs/agent-rules/ files or other implicit failure),
mention that you implemented governance edits (AGENTS.md and docs/agent-rules/)
afterwards, and then either check off Task 2.3 or annotate why it was captured
elsewhere.
In
`@openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md`:
- Line 7: Update
openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
to either (A) add the missing failing-first evidence for task `2.3` (commit/test
output, failing test names, and a short timestamped note showing the spec delta
led to failing tests) or (B) explicitly mark task `2.3` as waived with an
approval note and rationale. Ensure entries reference task `2.3` and include
enough provenance (test names, commands run, and author) so the TDD order (spec
delta → failing tests → implementation → passing tests) is clearly documented.
In `@scripts/sync_github_hierarchy_cache.py`:
- Around line 550-555: The two identical except blocks catching RuntimeError and
OSError should be consolidated to a single except that catches both; replace the
separate handlers "except RuntimeError as exc:" and "except OSError as exc:"
with one combined handler "except (RuntimeError, OSError) as exc:" and keep the
existing body (sys.stderr.write(...) and return 1) to reduce duplication.
In `@scripts/validate_agent_rule_applies_when.py`:
- Around line 54-55: The script currently silently skips files when frontmatter
parsing yields None (if data is None: continue); change this to fail-closed by
raising an explicit error or exiting non-zero so malformed or missing
frontmatter fails the validation run. Locate the frontmatter parsing branch that
checks the variable data in scripts/validate_agent_rule_applies_when.py and
replace the continue with a call to raise ValueError(f"Missing or malformed
frontmatter in {filename}") or process exit (e.g., sys.exit(1)) and ensure any
surrounding try/except does not swallow that error so CI fails
deterministically.
🪄 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: 387a0faa-b7a3-4c76-932a-fdf9307e53be
📒 Files selected for processing (29)
.cursorrules.github/copilot-instructions.mdAGENTS.mdCLAUDE.mddocs/_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.mdopenspec/CHANGE_ORDER.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/config.yamlpyproject.tomlscripts/pre_commit_code_review.pyscripts/sync_github_hierarchy_cache.pyscripts/validate_agent_rule_applies_when.pytests/__init__.pytests/unit/docs/test_agent_rules_governance.pytests/unit/scripts/test_sync_github_hierarchy_cache.pytests/unit/scripts/test_validate_agent_rule_applies_when.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). (3)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.13)
🧰 Additional context used
📓 Path-based instructions (4)
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/__init__.pytests/unit/scripts/test_validate_agent_rule_applies_when.pytests/unit/scripts/test_sync_github_hierarchy_cache.pytests/unit/docs/test_agent_rules_governance.py
openspec/**/*.md
⚙️ CodeRabbit configuration file
openspec/**/*.md: Specification truth: proposal/tasks/spec deltas vs. bundle behavior, CHANGE_ORDER, and
drift vs. shipped modules or docs.
Files:
openspec/CHANGE_ORDER.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
docs/**/*.md
⚙️ CodeRabbit configuration file
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.
Files:
docs/agent-rules/20-repository-context.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/50-quality-gates-and-review.mddocs/agent-rules/30-worktrees-and-branching.mddocs/agent-rules/05-non-negotiable-checklist.mddocs/agent-rules/INDEX.mddocs/agent-rules/70-release-commit-and-docs.mddocs/agent-rules/80-current-guidance-catalog.mddocs/agent-rules/60-github-change-governance.mddocs/agent-rules/10-session-bootstrap.md
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/sync_github_hierarchy_cache.pyscripts/pre_commit_code_review.pyscripts/validate_agent_rule_applies_when.py
🧠 Learnings (20)
📓 Common learnings
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T21:11:13.789Z
Learning: Follow `AGENTS.md` as the mandatory bootstrap contract
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T21:11:13.789Z
Learning: Load `docs/agent-rules/INDEX.md` and apply canonical rule files selected by its applicability matrix
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T21:11:13.789Z
Learning: Do not treat this file as a standalone handbook - consult `docs/agent-rules/` for canonical source of truth on worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:11:19.619Z
Learning: Use AGENTS.md as the mandatory bootstrap surface for GitHub Copilot instructions
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:11:19.619Z
Learning: Use docs/agent-rules/INDEX.md as the canonical governance dispatcher
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:11:19.619Z
Learning: Work must be committed on feature/*, bugfix/*, hotfix/*, or chore/* branches, typically in a worktree rooted under ../specfact-cli-modules-worktrees/
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:11:19.619Z
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-12T21:11:19.619Z
Learning: Signed module or manifest changes require version-bump review and verify-modules-signature validation
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:11:19.619Z
Learning: Refer to docs/agent-rules/ for the full governance rules; do not treat GitHub Copilot Instructions as a complete standalone handbook
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
Learning: Read AGENTS.md as the mandatory bootstrap governance surface for coding agents working in the repository before proceeding with any implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
Learning: Read docs/agent-rules/INDEX.md to understand the applicability matrix of additional rules after reading AGENTS.md
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
Learning: Read docs/agent-rules/05-non-negotiable-checklist.md as part of mandatory bootstrap before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
Learning: Detect repository root, active branch, and worktree state during session bootstrap
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
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-12T21:11:30.179Z
Learning: Refresh GitHub hierarchy metadata cache by running `python scripts/sync_github_hierarchy_cache.py` if `.specfact/backlog/github_hierarchy_cache.md` is missing or stale
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
Learning: Do not implement from the `dev` or `main` checkout by default
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
Learning: Do not auto-refine stale or ambiguous changes without the user
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
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-12T21:11:30.179Z
Learning: Finalize completed OpenSpec changes with `openspec archive <change-id>` and do not manually move change folders under `openspec/changes/archive/`
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:11:34.065Z
Learning: Treat canonical rule docs in docs/agent-rules/INDEX.md 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-12T21:11:34.065Z
Learning: When a change is paired with work in specfact-cli, review the paired public change artifacts there before widening scope or redefining shared workflow semantics
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:11:34.065Z
Learning: Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, and solid)
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:11:34.065Z
Learning: Treat clean-code regressions as blocking until they are fixed or explicitly justified
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Applied to files:
pyproject.tomlopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md.github/copilot-instructions.mdopenspec/config.yamlopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mddocs/agent-rules/50-quality-gates-and-review.mddocs/agent-rules/05-non-negotiable-checklist.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdCLAUDE.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Run quality gates in order: format, type-check, lint, yaml-lint, verify-modules-signature, contract-test, smart-test, test
Applied to files:
pyproject.tomldocs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to packages/*/src/**/*.py : Only allowed `specfact_cli.*` prefixes may be imported in bundle code (CORE/SHARED APIs only)
Applied to files:
tests/__init__.pyopenspec/config.yamlscripts/pre_commit_code_review.py
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Keep worktree paths under ../specfact-cli-modules-worktrees/<branch-type>/<branch-slug> and forbid dev/main branches in worktrees
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md.github/copilot-instructions.mddocs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-04-02T21:49:11.371Z
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md.github/copilot-instructions.mdopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: dev-deps installs specfact-cli from $SPECFACT_CLI_REPO when set, otherwise ../specfact-cli; in worktrees, bootstrap should prefer matching specfact-cli-worktrees/<branch> checkout before falling back to canonical sibling repo
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md.github/copilot-instructions.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Use Git worktrees for parallel branch work with paths: `../specfact-cli-modules-worktrees/<branch-type>/<branch-slug>`
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md.github/copilot-instructions.mddocs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Follow strict TDD order: spec delta -> failing tests -> implementation -> passing tests -> quality gates. Record TDD evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/config.yamlopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/50-quality-gates-and-review.mddocs/agent-rules/05-non-negotiable-checklist.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Verify an active OpenSpec change explicitly covers the requested scope before changing code; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/config.yamlopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/50-quality-gates-and-review.mddocs/agent-rules/05-non-negotiable-checklist.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Record failing/passing test evidence in openspec/changes/<change-id>/TDD_EVIDENCE.md and record review commands/timestamps when changes touch behavior or quality gates
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/config.yamlopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mddocs/agent-rules/40-openspec-and-tdd.mddocs/agent-rules/50-quality-gates-and-review.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Generate and maintain .specfact/code-review.json using 'hatch run specfact code review run --json --out .specfact/code-review.json' before marking OpenSpec changes as complete
Applied to files:
.github/copilot-instructions.mdopenspec/config.yamldocs/agent-rules/50-quality-gates-and-review.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to openspec/changes/** : Never manually move folders under `openspec/changes/` into `archive/`. Archiving MUST use `openspec archive <change-id>` command
Applied to files:
openspec/config.yamldocs/agent-rules/40-openspec-and-tdd.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Use 'openspec archive <change-id>' for archiving changes; do not manually move folders under openspec/changes/ into openspec/changes/archive/
Applied to files:
openspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Re-run code review when files in packages/, registry/, scripts/, tools/, tests/, or openspec/changes/<change-id>/ (excluding TDD_EVIDENCE.md) are modified
Applied to files:
openspec/config.yamlscripts/pre_commit_code_review.pyopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mddocs/agent-rules/40-openspec-and-tdd.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Install and configure pre-commit hooks to mirror CI quality gates, running in order: module signature verification → scripts/pre-commit-quality-checks.sh → scripts/pre_commit_code_review.py
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Scope type-check and lint quality gates to src/, tests/, and tools/ directories for repo tooling quality
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Use feature branches (`feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`) for development. Never work directly on `dev` and `main` branches
Applied to files:
docs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Use feature branches for implementation: feature/*, bugfix/*, hotfix/*, chore/* naming convention
Applied to files:
docs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to packages/*/module-package.yaml : Use SemVer for bundle versioning: patch (bug fix), minor (new command/option/API), major (breaking change/removal)
Applied to files:
docs/agent-rules/70-release-commit-and-docs.md
🪛 LanguageTool
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md
[uncategorized] ~21-~21: The official name of this software platform is spelled with a capital “H”.
Context: ...i-modules-worktrees/, hierarchy script python scripts/sync_github_hierarchy_cache.py`, bundle/registry po...
(GITHUB)
[uncategorized] ~23-~23: The official name of this software platform is spelled with a capital “H”.
Context: ...as a compact Cursor alias, add/update.github/copilot-instructions.md` as a compact C...
(GITHUB)
[uncategorized] ~24-~24: The official name of this software platform is spelled with a capital “H”.
Context: ...guidance explicitly requires refreshing .specfact/backlog/github_hierarchy_cache.md when missing or sta...
(GITHUB)
[uncategorized] ~26-~26: The official name of this software platform is spelled with a capital “H”.
Context: ...dules-specific wording. - [x] 3.7 Bring scripts/sync_github_hierarchy_cache.py and its tests up to...
(GITHUB)
.github/copilot-instructions.md
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...fact-cli-modules-worktrees/. - Refresh .specfact/backlog/github_hierarchy_cache.mdwithpython script...
(GITHUB)
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...backlog/github_hierarchy_cache.mdwithpython scripts/sync_github_hierarchy_cache.py` when GitHub hierarc...
(GITHUB)
openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
[uncategorized] ~15-~15: The official name of this software platform is spelled with a capital “H”.
Context: ...tract-test-status→ PASS - 2026-04-12:python3 -m pytest tests/unit/docs/test_agent_rules_governance.py tests/unit/scripts/test_validate_agent_rule_applies_when.py tests/unit/scripts/test_sync_github_hierarchy_cache.py -q` → PASS - 2026-04...
(GITHUB)
[uncategorized] ~22-~22: The official name of this software platform is spelled with a capital “H”.
Context: ...gent-rule-signals→ PASS - 2026-04-12:hatch run test tests/unit/docs/test_agent_rules_governance.py tests/unit/scripts/test_validate_agent_rule_applies_when.py tests/unit/scripts/test_sync_github_hierarchy_cache.py -q` → PASS (helper e...
(GITHUB)
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)
docs/agent-rules/05-non-negotiable-checklist.md
[style] ~39-~39: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... dev or main checkout by default. - SHALL treat a provided OpenSpec change id as ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~40-~40: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... not automatic permission to proceed. - SHALL verify selected change validity against...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~41-~41: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...pendency state before implementation. - SHALL not auto-refine stale, superseded, or a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~42-~42: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...r ambiguous changes without the user. - SHALL consult openspec/CHANGE_ORDER.md befo...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~43-~43: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... implementing, or archiving a change. - SHALL finalize completed OpenSpec changes wit...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~44-~44: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...enspec/changes//by hand. - SHALL consult.specfact/backlog/github_hiera...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~44-~44: The official name of this software platform is spelled with a capital “H”.
Context: ...//by hand. - SHALL consult.specfact/backlog/github_hierarchy_cache.md` before manual GitHu...
(GITHUB)
[style] ~45-~45: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ALL refresh it when missing or stale. - SHALL require public GitHub metadata complete...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~46-~46: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ockers, and blocked-by relationships. - SHALL check whether a linked GitHub issue is ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~47-~47: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ation if concurrent work is possible. - SHALL perform `spec -> tests -> failing evide...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~48-~48: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...` in that order for behavior changes. - SHALL run required verification and quality g...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~49-~49: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...he touched scope before finalization. - SHALL fix SpecFact code review findings, incl...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~50-~50: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...and explicit exception is documented. - SHALL enforce module signatures and version b...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~51-~51: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ule assets or manifests are affected. - SHALL preserve existing instructions by movin...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/agent-rules/INDEX.md
[style] ~41-~41: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...](./05-non-negotiable-checklist.md). 4. Load [10-session-bootstrap.md](./10-sessio...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~44-~44: 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] ~44-~44: 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`. 8. Load additional...
(GITHUB)
docs/agent-rules/60-github-change-governance.md
[uncategorized] ~44-~44: The official name of this software platform is spelled with a capital “H”.
Context: ...If the cache is missing or stale, rerun python scripts/sync_github_hierarchy_cache.py. - Use manual GitHu...
(GITHUB)
[style] ~54-~54: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... current cache-backed GitHub reality. - Verify required labels are present. - Verify p...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~55-~55: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...- Verify required labels are present. - Verify project assignment is present. - Verify...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~56-~56: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...Verify project assignment is present. - Verify blockers and blocked-by relationships a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ... a current view of GitHub state: 1. If .specfact/backlog/github_hierarchy_cache.md is missing, or was ...
(GITHUB)
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...d more than about five minutes ago, run python scripts/sync_github_hierarchy_cache.py. 2. Re-read the iss...
(GITHUB)
docs/agent-rules/10-session-bootstrap.md
[uncategorized] ~41-~41: The official name of this software platform is spelled with a capital “H”.
Context: ...Hub hierarchy data is required, confirm .specfact/backlog/github_hierarchy_cache.md is present and fres...
(GITHUB)
[uncategorized] ~42-~42: The official name of this software platform is spelled with a capital “H”.
Context: ...he is missing or stale, refresh it with python scripts/sync_github_hierarchy_cache.py. 7. Load the additi...
(GITHUB)
[style] ~49-~49: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...gation mode until the user clarifies. - If GitHub hierarchy metadata is needed and...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~50-~50: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...esh, manual GitHub lookup is allowed. - If the task is purely explanatory or read-...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔀 Multi-repo context nold-ai/specfact-cli
nold-ai/specfact-cli
-
scripts/validate_agent_rule_applies_when.py is wired into pyproject and CI:
- pyproject.toml: validate-agent-rule-signals entry and docs-validate sequence. [::nold-ai/specfact-cli::pyproject.toml:235,238]
- .github/workflows/docs-review.yml invokes hatch run validate-agent-rule-signals. [::nold-ai/specfact-cli::.github/workflows/docs-review.yml:89]
- docs/agent-rules/INDEX.md documents the validation and lists the script. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:17,87]
- Unit test exercising the script: tests/unit/scripts/test_validate_agent_rule_applies_when.py. [::nold-ai/specfact-cli::tests/unit/scripts/test_validate_agent_rule_applies_when.py:1-11]
-
scripts/sync_github_hierarchy_cache.py is referenced broadly and expected by governance docs:
- Docs instruct refresh when cache missing/stale: AGENTS.md, docs/agent-rules/INDEX.md, 10-session-bootstrap.md, 60-github-change-governance.md, openspec/config.yaml. [::nold-ai/specfact-cli::AGENTS.md:12][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:45][::nold-ai/specfact-cli::docs/agent-rules/10-session-bootstrap.md:14][::nold-ai/specfact-cli::docs/agent-rules/60-github-change-governance.md:13][::nold-ai/specfact-cli::openspec/config.yaml:92-93]
- Script default paths referenced in tests: DEFAULT_OUTPUT_PATH and DEFAULT_STATE_PATH constants asserted in tests. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py:73-74][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py:174-175]
- Many docs and openspec artifacts declare this cache-first contract and note a TODO for specfact-cli-modules to provide a compatible script. [::nold-ai/specfact-cli::docs/agent-rules/60-github-change-governance.md:49-51]
-
scripts/pre_commit_code_review.py changes are consumed by tooling/tests/hooks:
- Pre-commit invocations and scripts reference the command (setup-git-hooks.sh, pre-commit-smart-checks.sh). [::nold-ai/specfact-cli::scripts/setup-git-hooks.sh:69][::nold-ai/specfact-cli::scripts/pre-commit-smart-checks.sh:232]
- Docs/rules reference the pre-commit/code-review gate (docs/agent-rules/50-quality-gates-and-review.md, docs/modules/code-review.md). [::nold-ai/specfact-cli::docs/agent-rules/50-quality-gates-and-review.md:14][::nold-ai/specfact-cli::docs/modules/code-review.md:122]
- Unit tests load the script as a module: tests/unit/scripts/test_pre_commit_code_review.py. [::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py:18-20]
-
Frontmatter/agent-rule validation and tests:
- New docs under docs/agent-rules/ are validated by test suite (tests/unit/docs/test_agent_rules_governance.py, tests/unit/scripts/test_doc_frontmatter/test_agent_rule_frontmatter.py). These assert required frontmatter keys and index presence. [::nold-ai/specfact-cli::tests/unit/docs/test_agent_rules_governance.py:1-53][::nold-ai/specfact-cli::tests/unit/scripts/test_doc_frontmatter/test_agent_rule_frontmatter.py:84,124]
- INDEX.md declares canonical applies_when tokens which scripts/validate_agent_rule_applies_when.py must mirror. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:69][::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:13]
-
CI / workflow surface impact:
- docs-review workflow explicitly includes the new index and validation script. Merging these docs changes will affect Docs Review CI step (runs validate-agent-rule-signals). [::nold-ai/specfact-cli::.github/workflows/docs-review.yml:24,45,89][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:17]
Summary / risk pointers
- validate_agent_rule_applies_when.py is now part of docs validation in CI; ensure its canonical signal set stays in sync with INDEX.md (both are referenced in code/tests). [::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:13][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:69]
- sync_github_hierarchy_cache.py is relied on by governance docs and tests; its API/outputs (markdown and state JSON layout/paths/fingerprint) must remain stable for dependent tooling/tests and for specfact-cli-modules (docs note TODO to add compatible script). [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py:73-74][::nold-ai/specfact-cli::docs/agent-rules/60-github-change-governance.md:49-51]
- pre_commit_code_review.py refactor affects pre-commit hooks and tests that import/load it; ensure the dynamic loader preserves expected entrypoints and behavior. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py:18-20]
🔇 Additional comments (28)
tests/__init__.py (1)
1-1: LGTM!Clean package marker enabling pylint traversal and proper test discovery. This aligns with the PR's stated goal of making pylint succeed on the tests tree.
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md (1)
5-5: LGTM — Worktree path resolution clarification is well-documented.The environment-specific path example (
/home/dom/git/nold-ai/) provides concrete guidance while the pattern (../specfact-cli-modules-worktrees/<type>/<slug>resolved from repo parent) remains portable. This aligns with the paired specfact-cli#494 semantics.scripts/sync_github_hierarchy_cache.py (3)
292-294: LGTM — Clean consolidation of precondition helpers.The shared
_require_non_blank_argumentpredicate eliminates duplication across multiple@requiredecorators. The*_unusedparameter accommodates icontract's signature inspection without affecting logic.
304-307: Pylint disable is appropriate here.The
unnecessary-lambdasuppression is needed because icontract's@requiredecorator requires the lambda for parameter binding by name. This is a known pattern when using icontract with beartype.
483-490: Repo-aware cache validation is a critical hardening.The early-return now requires
state["repo"] == repo_full_namein addition to fingerprint match, preventing false cache hits when the same state file is reused across different repository checkouts. This aligns with the linked test cases (test_sync_cache_repo_mismatch_rewrites_despite_matching_fingerprint,test_sync_cache_missing_repo_in_state_rewrites) intests/unit/scripts/test_sync_github_hierarchy_cache.py:276-312.scripts/pre_commit_code_review.py (2)
31-42: Dynamic loading pattern correctly handles pre-commit bootstrap.Loading
dev_bootstrap.pyviaimportlib.utilavoids package installation assumptions during pre-commit. The path construction and type cast align with the function signature insrc/specfact_cli_modules/dev_bootstrap.py:54-63. This mirrors the pattern intools/dev_bootstrap_support.py:13-16but uses file-based loading for the pre-commit context.
93-121: Clean refactor of severity classification logic.The extracted
_classify_severityhelper centralizes normalization (handlingerr/error,warn/warning,advise/advisoryvariants) and defensive checks for non-dict items or missing severity fields. This improves maintainability over inline branching.pyproject.toml (1)
63-63: Aligns with specfact-cli validation surface.The
validate-agent-rule-signalsscript entry mirrors the paired specfact-cli setup (pyproject.toml:235,238 and .github/workflows/docs-review.yml:89 per linked repo context). This enables the same canonicalapplies_whensignal validation across both repositories.openspec/CHANGE_ORDER.md (1)
79-79: CHANGE_ORDER entry correctly documents dependencies.The row properly captures the three-way dependency chain: parent feature (
#163), paired core change (specfact-cli#494), and baseline (#178for hierarchy-cache). This maintains the traceability contract between modules and core repositories.openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md (1)
5-9: Task completion state looks correct.Branch setup, worktree creation, environment prep, pre-flight checks, and initial validation are appropriately marked complete. The environment-specific path clarification in 1.2 aligns with the corresponding update in
design.md.docs/_data/nav.yml (1)
193-225: Navigation URLs align with markdown frontmatter permalinks.All 11 items in the Agent Governance section correctly map to the
/contributing/agent-rules/permalinks defined in the corresponding markdown files (INDEX, 05-non-negotiable-checklist through 80-current-guidance-catalog)..cursorrules (1)
1-5: Bootstrap alias is clear and appropriately minimal.This keeps
.cursorrulesas a thin dispatcher and avoids policy duplication.tests/unit/scripts/test_validate_agent_rule_applies_when.py (1)
10-18: Good targeted coverage for the governance signal validator.This test exercises the script boundary end-to-end and gives actionable failure output.
docs/agent-rules/80-current-guidance-catalog.md (1)
1-52: Canonical migrated-guidance catalog looks consistent and complete.Frontmatter and content structure fit the deterministic agent-rule framework.
.github/copilot-instructions.md (1)
3-11: Copilot bootstrap alias is aligned with canonical governance dispatch.Good concise reminders around core module boundaries (cache sync, review gate, and signature/version checks).
CLAUDE.md (1)
3-13: Alias refactor is clean and governance-consistent.Good reduction of duplicated policy while preserving the clean-code blocking contract.
docs/agent-rules/20-repository-context.md (1)
1-67: Repository-context rule is well-scoped and operationally accurate.The architecture/commands/bootstrap sections are crisp and useful for deterministic agent onboarding.
tests/unit/scripts/test_sync_github_hierarchy_cache.py (2)
234-237: Good coverage for repo-aware cache invalidation paths.These additions correctly lock in the new behavior for repo-mismatch and missing-repo state handling, preventing false skip decisions when fingerprints match.
As per coding guidelines: "
tests/**/*.py: Ensure changes to adapters or bridges have targeted coverage."Also applies to: 276-349
477-499: CLI runtime-error behavior is validated cleanly.The test asserts exit code, stderr content, and stdout silence, which gives strong regression protection for
main()failure handling.As per coding guidelines: "
tests/**/*.py: Ensure changes to adapters or bridges have targeted coverage."openspec/config.yaml (1)
43-45: Governance gating updates are consistent and well-scoped.Making cache-first hierarchy checks and explicit public-work readiness tasks mandatory improves deterministic execution and reduces metadata drift before implementation.
Based on learnings: "Require public GitHub metadata completeness before implementation when linked issue workflow applies: parent, labels, project assignment, blockers, and blocked-by relationships."
Also applies to: 64-65, 82-85
AGENTS.md (1)
5-39: Compact bootstrap contract is clear and enforceable.The precedence model, non-negotiable gates, and canonical rule-doc pointers are coherent and reduce instruction drift across agent surfaces.
Based on learnings: "Follow
AGENTS.mdas the mandatory bootstrap contract" and "Loaddocs/agent-rules/INDEX.md... selected by its applicability matrix."Also applies to: 44-57
tests/unit/docs/test_agent_rules_governance.py (1)
30-66: Governance docs contract coverage is solid.These tests enforce required frontmatter shape and bootstrap invariants, which should catch documentation drift early.
As per coding guidelines: "
tests/**/*.py: Contract-first and integration tests ... Ensure changes to adapters or bridges have targeted coverage."Also applies to: 68-74
docs/agent-rules/10-session-bootstrap.md (1)
37-44: Bootstrap rule sequencing is clear and operationally practical.The checks are ordered well, and the cache refresh/fallback behavior is explicit enough for deterministic execution.
Also applies to: 47-50
docs/agent-rules/60-github-change-governance.md (1)
41-46: Cache-first public-work governance is well defined.The readiness and concurrency steps are explicit and should reduce parent/linkage and in-progress ambiguity failures.
Also applies to: 49-64
docs/agent-rules/50-quality-gates-and-review.md (1)
41-55: Quality-gate and pre-commit ordering looks consistent.The gate ordering and pre-commit sequence are aligned with the repository hook flow and read as operationally clear.
docs/agent-rules/40-openspec-and-tdd.md (1)
56-70: OpenSpec/TDD ordering and archive guardrails are clear and consistent.The strict sequence and archive-only-via-CLI wording are precise and match the expected governance contract.
docs/agent-rules/05-non-negotiable-checklist.md (1)
37-51: Checklist language is appropriately strict for a blocking always-load rule.No actionable issues here; the normative SHALL format is suitable for this control surface.
docs/agent-rules/INDEX.md (1)
68-87: Canonical signal set and validator command are in sync.Good alignment between the index definitions and the enforcement script/command path.
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 304-307: The repeated inline pylint disable comments for
"unnecessary-lambda" used with icontract's `@require/`@ensure decorators should be
consolidated: add a single file-level disable comment near the top (after
imports) like "# pylint: disable=unnecessary-lambda # icontract `@require` needs
lambdas for param introspection" and remove the three inline disables that
precede the decorated functions (the decorators using require and ensure in this
file). Update occurrences around the decorators (the `@require/`@ensure usages) so
they no longer carry the inline "# pylint: disable=unnecessary-lambda" comments.
- Around line 292-294: The helper function _require_non_blank_argument currently
accepts a variadic *_unused parameter that is never used; remove the unused
variadic parameter so the signature is def _require_non_blank_argument(value:
str) -> bool and adjust any references accordingly (the lambdas used with the
icontract `@require` decorators like lambda repo_owner:
_require_non_blank_argument(repo_owner) will continue to work unchanged),
keeping the implementation returning _is_not_blank(value).
🪄 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: dd0d4421-ff9b-4862-a628-a8ee5fff3858
📒 Files selected for processing (9)
docs/agent-rules/30-worktrees-and-branching.mddocs/agent-rules/70-release-commit-and-docs.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdscripts/sync_github_hierarchy_cache.pyscripts/validate_agent_rule_applies_when.pytests/unit/scripts/test_validate_agent_rule_applies_when.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). (3)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.13)
🧰 Additional context used
📓 Path-based instructions (5)
openspec/**/*.md
⚙️ CodeRabbit configuration file
openspec/**/*.md: Specification truth: proposal/tasks/spec deltas vs. bundle behavior, CHANGE_ORDER, and
drift vs. shipped modules or docs.
Files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.md
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/sync_github_hierarchy_cache.pyscripts/validate_agent_rule_applies_when.py
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/unit/scripts/test_validate_agent_rule_applies_when.py
docs/agent-rules/**/*.md
📄 CodeRabbit inference engine (.cursorrules)
Load
docs/agent-rules/INDEX.mdand select canonical rule files based on its applicability matrixConsult
docs/agent-rules/for the canonical source of truth for worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules
Files:
docs/agent-rules/30-worktrees-and-branching.mddocs/agent-rules/70-release-commit-and-docs.md
docs/**/*.md
⚙️ CodeRabbit configuration file
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.
Files:
docs/agent-rules/30-worktrees-and-branching.mddocs/agent-rules/70-release-commit-and-docs.md
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: Use AGENTS.md as the mandatory bootstrap surface for GitHub Copilot instructions
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: Use docs/agent-rules/INDEX.md as the canonical governance dispatcher
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: Work belongs on feature/*, bugfix/*, hotfix/*, or chore/* branches in worktrees rooted under ../specfact-cli-modules-worktrees/
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: Refresh .specfact/backlog/github_hierarchy_cache.md with python scripts/sync_github_hierarchy_cache.py when GitHub hierarchy metadata is missing or stale before parent or blocker work
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: Repository enforces 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-12T21:34:43.013Z
Learning: Signed module or manifest changes require version-bump review and verify-modules-signature verification
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T21:34:43.013Z
Learning: 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-12T21:34:54.475Z
Learning: Read AGENTS.md file as the mandatory bootstrap governance surface for coding agents working in this repository
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
Learning: Read docs/agent-rules/INDEX.md to understand the applicability matrix of additional rule files
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
Learning: Read docs/agent-rules/05-non-negotiable-checklist.md as part of mandatory bootstrap
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
Learning: Detect repository root, active branch, and worktree state before proceeding with implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
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-12T21:34:54.475Z
Learning: If GitHub hierarchy metadata is needed and `.specfact/backlog/github_hierarchy_cache.md` is missing or stale, refresh it with `python scripts/sync_github_hierarchy_cache.py`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
Learning: Do not auto-refine stale or ambiguous changes without the user
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
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-12T21:34:54.475Z
Learning: Finalize completed OpenSpec changes with `openspec archive <change-id>` (see docs/agent-rules/40-openspec-and-tdd.md); do not manually move change folders under `openspec/changes/archive/`
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:35:00.203Z
Learning: Follow AGENTS.md as the primary bootstrap contract for Claude Code governance
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:35:00.203Z
Learning: Treat canonical rule docs in docs/agent-rules/INDEX.md 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-12T21:35:00.203Z
Learning: Do not rely on CLAUDE.md as a standalone governance handbook
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:35:00.203Z
Learning: When changes are paired with work in specfact-cli, review paired public change artifacts there before widening scope or redefining shared workflow semantics
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:35:00.203Z
Learning: Preserve clean-code compliance gate with category references for naming, kiss, yagni, dry, and solid principles
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T21:35:00.203Z
Learning: Treat clean-code regressions as blocking until they are fixed or explicitly justified
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Record failing/passing test evidence in openspec/changes/<change-id>/TDD_EVIDENCE.md and record review commands/timestamps when changes touch behavior or quality gates
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Follow strict TDD order: spec delta -> failing tests -> implementation -> passing tests -> quality gates. Record TDD evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Generate and maintain .specfact/code-review.json using 'hatch run specfact code review run --json --out .specfact/code-review.json' before marking OpenSpec changes as complete
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Re-run code review when files in packages/, registry/, scripts/, tools/, tests/, or openspec/changes/<change-id>/ (excluding TDD_EVIDENCE.md) are modified
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Verify an active OpenSpec change explicitly covers the requested scope before changing code; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/tasks.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Keep worktree paths under ../specfact-cli-modules-worktrees/<branch-type>/<branch-slug> and forbid dev/main branches in worktrees
Applied to files:
docs/agent-rules/30-worktrees-and-branching.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Use Git worktrees for parallel branch work with paths: `../specfact-cli-modules-worktrees/<branch-type>/<branch-slug>`
Applied to files:
docs/agent-rules/30-worktrees-and-branching.mdopenspec/changes/governance-04-deterministic-agent-governance-loading/design.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Use feature branches (`feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`) for development. Never work directly on `dev` and `main` branches
Applied to files:
docs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Use feature branches for implementation: feature/*, bugfix/*, hotfix/*, chore/* naming convention
Applied to files:
docs/agent-rules/30-worktrees-and-branching.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Run publish pre-check with 'python scripts/publish-module.py --bundle <bundle>' before publishing
Applied to files:
docs/agent-rules/70-release-commit-and-docs.md
📚 Learning: 2026-04-02T21:49:11.371Z
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: dev-deps installs specfact-cli from $SPECFACT_CLI_REPO when set, otherwise ../specfact-cli; in worktrees, bootstrap should prefer matching specfact-cli-worktrees/<branch> checkout before falling back to canonical sibling repo
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Keep registry metadata in registry/index.json and packages/*/module-package.yaml
Applied to files:
openspec/changes/governance-04-deterministic-agent-governance-loading/design.md
🪛 LanguageTool
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md
[uncategorized] ~21-~21: The official name of this software platform is spelled with a capital “H”.
Context: ...i-modules-worktrees/, hierarchy script python scripts/sync_github_hierarchy_cache.py`, bundle/registry po...
(GITHUB)
[uncategorized] ~23-~23: The official name of this software platform is spelled with a capital “H”.
Context: ...as a compact Cursor alias, add/update.github/copilot-instructions.md` as a compact C...
(GITHUB)
[uncategorized] ~24-~24: The official name of this software platform is spelled with a capital “H”.
Context: ...guidance explicitly requires refreshing .specfact/backlog/github_hierarchy_cache.md when missing or sta...
(GITHUB)
[uncategorized] ~26-~26: The official name of this software platform is spelled with a capital “H”.
Context: ...dules-specific wording. - [x] 3.7 Bring scripts/sync_github_hierarchy_cache.py and its tests up to...
(GITHUB)
openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
[uncategorized] ~30-~30: The official name of this software platform is spelled with a capital “H”.
Context: ...tract-test-status→ PASS - 2026-04-12:python3 -m pytest tests/unit/docs/test_agent_rules_governance.py tests/unit/scripts/test_validate_agent_rule_applies_when.py tests/unit/scripts/test_sync_github_hierarchy_cache.py -q` → PASS - 2026-04...
(GITHUB)
[uncategorized] ~37-~37: The official name of this software platform is spelled with a capital “H”.
Context: ...gent-rule-signals→ PASS - 2026-04-12:hatch run test tests/unit/docs/test_agent_rules_governance.py tests/unit/scripts/test_validate_agent_rule_applies_when.py tests/unit/scripts/test_sync_github_hierarchy_cache.py -q` → PASS (helper e...
(GITHUB)
🔀 Multi-repo context nold-ai/specfact-cli
Linked repositories findings
nold-ai/specfact-cli
-
scripts/validate_agent_rule_applies_when.py is added and:
- Is invoked by pyproject.toml as hatch script "validate-agent-rule-signals". [::nold-ai/specfact-cli::pyproject.toml:235]
- Is run in CI Docs Review workflow (docs-review job). [::nold-ai/specfact-cli::.github/workflows/docs-review.yml:89]
- Is documented in docs/agent-rules/INDEX.md as the validation step for rule frontmatter signals. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:17,87]
- The script contains a canonical CANONICAL_TASK_SIGNALS set that must remain consistent with INDEX.md. [::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:1-99]
- Unit test exercises the script as a subprocess and asserts exit code 0. [::nold-ai/specfact-cli::tests/unit/scripts/test_validate_agent_rule_applies_when.py:1-20]
-
scripts/sync_github_hierarchy_cache.py is used by docs and tests:
- Governance docs and AGENTS.md instruct callers to run this script when the cache is missing/stale. [::nold-ai/specfact-cli::AGENTS.md:12][::nold-ai/specfact-cli::docs/agent-rules/10-session-bootstrap.md:14][::nold-ai/specfact-cli::docs/agent-rules/60-github-change-governance.md:13,44,49,57,68]
- Tests load the script module directly and assert behavior/constant values (DEFAULT_OUTPUT_PATH, DEFAULT_STATE_PATH, fingerprint logic, repo field handling). Changes to output/state JSON shape or the DEFAULT_* constants will affect tests. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py:DEFAULT_OUTPUT_PATH/DEFAULT_STATE_PATH definitions][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py:1-220, sync tests referencing state repo field]
- openspec/config.yaml and several docs reference running this script for cache refresh. [::nold-ai/specfact-cli::openspec/config.yaml:93,168]
-
scripts/pre_commit_code_review.py refactor is consumed by tooling/tests:
- The script is referenced by docs/rules and helper scripts (pre-commit wrappers). [::nold-ai/specfact-cli::docs/agent-rules/50-quality-gates-and-review.md:14][::nold-ai/specfact-cli::scripts/setup-git-hooks.sh:69][::nold-ai/specfact-cli::scripts/pre-commit-smart-checks.sh:232]
- Unit tests import/load this script as a module; refactors (dynamic loading, severity mapping) must preserve the expected entrypoints/behaviour used by tests. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py:18-20]
-
CI / workflows impact:
- Docs Review workflow triggers on changes to docs and scripts including scripts/validate_agent_rule_applies_when.py and docs/agent-rules/INDEX.md; merging this PR enables the new validation in CI. [::nold-ai/specfact-cli::.github/workflows/docs-review.yml: on: paths / job steps]
Summary / risk pointers
- Keep CANONICAL_TASK_SIGNALS in scripts/validate_agent_rule_applies_when.py synchronized with docs/agent-rules/INDEX.md; mismatch will make CI fail. [::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:CANONICAL_TASK_SIGNALS][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:69]
- Ensure sync_github_hierarchy_cache.py preserves the output markdown/state JSON shape (including the repo field and fingerprint semantics) and DEFAULT_* paths; tests and governance docs rely on these conventions. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py:DEFAULT_OUTPUT_PATH,DEFAULT_STATE_PATH][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py]
- Ensure pre_commit_code_review.py refactor remains compatible with callers and tests that import and call its functions. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py]
🔇 Additional comments (22)
docs/agent-rules/30-worktrees-and-branching.md (2)
1-31: Frontmatter contract looks correct and deterministic.Metadata shape, applicability, blocking semantics, and dependency wiring are consistent with the canonical agent-rule pattern.
41-44: Portable worktree-path guidance is now correctly host-agnostic.The
REPO_ROOT/..explanation preserves deterministic path resolution without hardcoding machine-specific absolute paths.scripts/validate_agent_rule_applies_when.py (2)
52-73: Fail-closed validation behavior is implemented correctly.Malformed frontmatter and invalid
applies_whentypes are surfaced as explicit errors instead of being silently skipped.
100-113: CLI contract is clear and deterministic.Exit code handling (
0pass,1validation failures,2missing rules dir) is appropriate for local and CI enforcement.openspec/changes/governance-04-deterministic-agent-governance-loading/design.md (1)
5-5: Design note now aligns with deterministic worktree-root policy.Good update to keep path semantics consistent across governance docs and implementation guidance.
openspec/changes/governance-04-deterministic-agent-governance-loading/tasks.md (2)
6-6: Worktree path clarification is precise and portable.The
REPO_ROOT/..note removes ambiguity when rendering absolute worktree paths across environments.
30-31: Validation checklist communicates gate status clearly.Keeping task
4.2explicitly open while marking completed gates helps prevent false-ready interpretation.openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md (2)
12-29: Validation evidence is concrete and audit-friendly.Exact commands with explicit PASS/FAIL outcomes are documented in a deterministic format.
32-34: Changed-scope vs full-scope review outcomes are documented correctly.The split between branch-local clean results and existing repo-wide findings is clearly captured.
openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md (2)
8-23: Failing-first waiver is explicit and well-scoped.This records the exception clearly while still tying enforcement to concrete validation hooks.
24-47: Passing-after and remaining-blocker evidence is clearly separated.Chronological command evidence plus explicit blocker tracking gives good governance traceability.
tests/unit/scripts/test_validate_agent_rule_applies_when.py (2)
24-33: Good end-to-end smoke check for the validator CLI.This verifies the script entrypoint behavior against real repository rule docs.
35-88: Targeted malformed-frontmatter coverage is strong.The test set covers missing frontmatter, invalid YAML, non-mapping roots, and a passing canonical case.
scripts/sync_github_hierarchy_cache.py (4)
542-552: LGTM — robust error handling for operational failures.The combined
except (RuntimeError, OSError)handler gracefully catches GraphQL failures (timeouts, auth issues, network errors) and filesystem issues, writing a clear message to stderr and returning exit code1. This enables callers (governance scripts, CI) to detect failures without stack traces polluting output.The past review suggestion to consolidate the exception handlers has been addressed here.
298-300: LGTM!Postcondition helper cleanly validates the contract that only
EpicandFeatureissues are returned. The generator expression is efficient and readable.
401-411: LGTM!The
repo_full_nameparameter provides a cleaner interface (single canonical identifier vs. separate owner/name), and the preconditions ensure required metadata is validated before rendering. This aligns with the state JSON shape expected by downstream consumers.
483-496: LGTM — solid cache invalidation strengthening.Adding the
state.get("repo") == repo_full_namecheck ensures the cache isn't mistakenly reused when the script runs against a different repository (e.g., in a worktree pointing elsewhere). This is a sensible boundary enforcement that prevents cross-repo cache bleed.The
.get()calls handle missing keys gracefully, returningNonewhich fails the equality check and correctly triggers a refresh.Per the linked repository findings, tests and governance docs rely on this state shape—this change is compatible.
docs/agent-rules/70-release-commit-and-docs.md (5)
37-41: Versioning guidance correctly addresses bundle-to-core adapter boundaries.The rule properly identifies the critical touchpoints:
module-package.yamlsemver updates synchronized withcore_compatibilityand registry metadata when a bundle requires a newerspecfact-cli. Treating version bumps and registry updates as a unified release surface prevents the common pitfall of desynchronized manifest/registry state.
43-49: Registry workflow correctly enforces pre-check validation before publish.The flow properly sequences version bump → pre-check (
scripts/publish_module.py) → tooling-wrapper publish → registry update. This prevents publishing artifacts that would fail validation and ensuresregistry/index.jsonremains synchronized with published bundle state.
51-54: Commit signing guidance preserves security in non-interactive contexts.Providing the explicit
git commit -S -m "<message>"command when automation encounters signing failures ensures the security requirement isn't silently bypassed. This is especially valuable for CI/automation scenarios where interactive signing prompts would otherwise block or cause silent failures.
56-61: Documentation rules properly address Jekyll frontmatter and cross-site link integrity.The explicit requirement to "keep cross-links between
docs.specfact.ioandmodules.specfact.iohonest" (line 61) is critical for preventing drift between the main documentation and modules documentation surfaces—a common failure mode when bundle/registry changes span both sites.
1-33: The applies_when values are canonical and valid; no validation error will occur.The file's frontmatter is compliant with the validation script. The
applies_whenlist contains only canonical task signals (finalization,release,documentation-update), all of which are present inCANONICAL_TASK_SIGNALS. The validation script does not require or check for arule_namefield—it only validates YAML structure and applies_when values against the canonical set. Theidfield matches the pattern used consistently across all other rule files in the repository.> Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/specfact_cli_modules/dev_bootstrap.py (1)
69-75:⚠️ Potential issue | 🟠 MajorAligned-core verification is missing before the early success return
At Line 72, this returns success when any
specfact_cliis importable, even if it is not the paired/resolved core checkout. That can silently couple this modules repo to the wrong core API surface.Suggested fix
def _installed_core_exists() -> bool: return importlib.util.find_spec("specfact_cli") is not None + + +def _installed_core_matches(core_repo: Path | None) -> bool: + spec = importlib.util.find_spec("specfact_cli") + if spec is None: + return False + if core_repo is None: + return True + locations = list(getattr(spec, "submodule_search_locations", []) or []) + if not locations: + return False + installed_pkg = Path(locations[0]).resolve() + expected_pkg = (core_repo / "src" / "specfact_cli").resolve() + return installed_pkg == expected_pkg def ensure_core_dependency(repo_root: Path) -> int: """Install specfact-cli editable dependency if the active environment is not aligned.""" apply_specfact_workspace_env(repo_root) - if _installed_core_exists(): - return 0 core_repo = resolve_core_repo(repo_root) + if _installed_core_matches(core_repo): + return 0 if core_repo is None: print("Unable to resolve specfact-cli checkout. Set SPECFACT_CLI_REPO.", file=sys.stderr) return 1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/specfact_cli_modules/dev_bootstrap.py` around lines 69 - 75, The early-return in ensure_core_dependency wrongly succeeds whenever specfact_cli is importable; change the flow to resolve and verify the paired checkout before returning: call resolve_core_repo(repo_root) (or move the existing call above the _installed_core_exists() check), and if _installed_core_exists() is True then verify the installed specfact_cli points to the resolved core checkout (e.g., inspect the imported specfact_cli package path/module __file__ and compare to core_repo) — only return success when the installed package matches core_repo; otherwise proceed to install the editable core. Ensure you still call apply_specfact_workspace_env(repo_root) as before.
🤖 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/50-quality-gates-and-review.md`:
- Around line 50-56: Update the Block 2 docs to explicitly state that staged
Python sources include both .py and .pyi files: mention that
pre-commit-quality-checks.sh invokes `pre_commit_code_review.py` on staged
patterns `*.py` and `*.pyi` (as collected in the script’s block2 logic), so type
stub files (.pyi) are included in the pre-commit checks and adapter/bundle
boundaries when stubs are staged.
In `@scripts/pre-commit-quality-checks.sh`:
- Around line 239-242: The usage() function's message currently lists
subcommands but omits the documented help aliases; update the error "Usage: $0
{…}" string inside usage() so it also mentions the help aliases (-h, --help,
help) (the usage function and the help handling block around the help aliases
should match), e.g., append or include "(also: -h | --help | help)" to the usage
text so callers see the available help aliases.
- Around line 171-186: The status command currently always exits 0 which makes
the shell check in run_contract_tests_visible skip tests; update the
_contract_cli_status() implementation in tools/contract_first_smart_test.py so
it returns/executes sys.exit(0) when no input changes require testing and
sys.exit(1) (or any non-zero) when input changes are present and tests should
run, ensuring the shell conditional (hatch run contract-test-status) behaves
correctly and triggers hatch run contract-test when appropriate.
In `@tests/unit/test_dev_bootstrap.py`:
- Around line 49-76: Add a test covering the unresolved-core branch by calling
apply_specfact_workspace_env with resolve_core_repo mocked to return None (use
monkeypatch.setattr on "specfact_cli_modules.dev_bootstrap.resolve_core_repo" to
a lambda that returns None), ensure SPECFACT_MODULES_REPO is set to the provided
repo_root as before, and assert that SPECFACT_REPO_ROOT is not created in
os.environ (i.e., the key is absent or not set) to validate the adapter contract
when resolve_core_repo yields None.
---
Outside diff comments:
In `@src/specfact_cli_modules/dev_bootstrap.py`:
- Around line 69-75: The early-return in ensure_core_dependency wrongly succeeds
whenever specfact_cli is importable; change the flow to resolve and verify the
paired checkout before returning: call resolve_core_repo(repo_root) (or move the
existing call above the _installed_core_exists() check), and if
_installed_core_exists() is True then verify the installed specfact_cli points
to the resolved core checkout (e.g., inspect the imported specfact_cli package
path/module __file__ and compare to core_repo) — only return success when the
installed package matches core_repo; otherwise proceed to install the editable
core. Ensure you still call apply_specfact_workspace_env(repo_root) as before.
🪄 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: 5cc904f9-a7a0-4411-9c5b-7bb75b9b246d
📒 Files selected for processing (14)
.pre-commit-config.yamlREADME.mddocs/agent-rules/20-repository-context.mddocs/agent-rules/50-quality-gates-and-review.mdopenspec/config.yamlpyproject.tomlscripts/pre-commit-quality-checks.shscripts/pre_commit_code_review.pyscripts/sync_github_hierarchy_cache.pysrc/specfact_cli_modules/dev_bootstrap.pytests/conftest.pytests/unit/scripts/test_pre_commit_code_review.pytests/unit/test_dev_bootstrap.pytests/unit/test_pre_commit_quality_parity.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). (3)
- GitHub Check: quality (3.13)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.11)
🧰 Additional context used
📓 Path-based instructions (4)
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/unit/scripts/test_pre_commit_code_review.pytests/unit/test_pre_commit_quality_parity.pytests/unit/test_dev_bootstrap.pytests/conftest.py
src/**/*.py
⚙️ CodeRabbit configuration file
src/**/*.py: Repo infrastructure (not bundle code): keep parity with specfact-cli quality patterns;
contract-first public helpers where applicable; avoid print() in library paths.
Files:
src/specfact_cli_modules/dev_bootstrap.py
docs/**/*.md
⚙️ CodeRabbit configuration file
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.
Files:
docs/agent-rules/20-repository-context.mddocs/agent-rules/50-quality-gates-and-review.md
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/pre_commit_code_review.pyscripts/sync_github_hierarchy_cache.py
🧠 Learnings (18)
📓 Common learnings
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:01:13.487Z
Learning: Follow `AGENTS.md` as the mandatory bootstrap contract
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:01:13.487Z
Learning: Load `docs/agent-rules/INDEX.md` and the canonical rule files selected by its applicability matrix
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:01:13.487Z
Learning: Do not treat documentation files as standalone handbooks; refer to `docs/agent-rules/` as the source of truth for worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Use AGENTS.md as the mandatory bootstrap surface for GitHub Copilot instructions
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Use docs/agent-rules/INDEX.md as the canonical governance dispatcher
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Work belongs on feature/*, bugfix/*, hotfix/*, or chore/* branches
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Refresh .specfact/backlog/github_hierarchy_cache.md with python scripts/sync_github_hierarchy_cache.py when GitHub hierarchy metadata is missing or stale
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Enforce 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-12T22:01:19.740Z
Learning: Signed module or manifest changes require version-bump review and verify-modules-signature
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:01:19.740Z
Learning: Refer to full governance rules in docs/agent-rules/ rather than treating this file as a complete standalone handbook
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Read AGENTS.md as the mandatory bootstrap governance surface before working on code
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Read docs/agent-rules/INDEX.md as part of mandatory bootstrap process
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Read docs/agent-rules/05-non-negotiable-checklist.md as part of mandatory bootstrap process
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Detect repository root, active branch, and worktree state as part of bootstrap
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Reject implementation from the dev or main checkout unless the user explicitly overrides
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Refresh docs/.specfact/backlog/github_hierarchy_cache.md with python scripts/sync_github_hierarchy_cache.py when GitHub hierarchy metadata is needed
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Load 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-12T22:01:32.279Z
Learning: Follow precedence order: direct system/developer instructions > explicit user override > AGENTS.md > 05-non-negotiable-checklist.md > other docs/agent-rules/ files > change-local OpenSpec artifacts
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
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-12T22:01:32.279Z
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-12T22:01:32.279Z
Learning: Verify selected change against current repository reality and dependency state before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Do not auto-refine stale or ambiguous changes without the user
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
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-12T22:01:32.279Z
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-12T22:01:32.279Z
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-12T22:01:32.279Z
Learning: Run required verification and quality gates for touched scope before finalization
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
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-12T22:01:32.279Z
Learning: Treat the clean-code compliance gate as mandatory: enforce naming, kiss, yagni, dry, and solid categories and block regressions
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
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-12T22:01:32.279Z
Learning: Finalize completed OpenSpec changes with openspec archive <change-id> rather than manually moving change folders under openspec/changes/archive/
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: Design governance context lives in paired public specfact-cli repository and active OpenSpec artifacts in this repo, not in internal wiki checkouts
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:01:32.279Z
Learning: When a modules change is explicitly paired with a core change, review both public change folders before widening scope or redefining shared workflow semantics
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:01:36.806Z
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-12T22:01:36.806Z
Learning: Treat canonical rule docs in docs/agent-rules/INDEX.md 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-12T22:01:36.806Z
Learning: When a change is paired with work in specfact-cli, review the paired public change artifacts there before widening scope or redefining shared workflow semantics
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:01:36.806Z
Learning: Preserve the clean-code compliance gate and its category references (naming, kiss, yagni, dry, solid) during code review
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:01:36.806Z
Learning: Treat clean-code regressions as blocking until they are fixed or explicitly justified
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: dev-deps installs specfact-cli from $SPECFACT_CLI_REPO when set, otherwise ../specfact-cli; in worktrees, bootstrap should prefer matching specfact-cli-worktrees/<branch> checkout before falling back to canonical sibling repo
Applied to files:
pyproject.tomlsrc/specfact_cli_modules/dev_bootstrap.pytests/unit/test_dev_bootstrap.pyscripts/pre_commit_code_review.pytests/conftest.py
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to packages/*/src/**/*.py : Only allowed `specfact_cli.*` prefixes may be imported in bundle code (CORE/SHARED APIs only)
Applied to files:
pyproject.tomlsrc/specfact_cli_modules/dev_bootstrap.pyscripts/pre_commit_code_review.pytests/conftest.pyopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Generate and maintain .specfact/code-review.json using 'hatch run specfact code review run --json --out .specfact/code-review.json' before marking OpenSpec changes as complete
Applied to files:
pyproject.tomltests/unit/scripts/test_pre_commit_code_review.pyREADME.mddocs/agent-rules/50-quality-gates-and-review.mdscripts/pre_commit_code_review.pyopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Applied to files:
pyproject.tomltests/unit/scripts/test_pre_commit_code_review.pytests/unit/test_pre_commit_quality_parity.pyREADME.mddocs/agent-rules/50-quality-gates-and-review.md.pre-commit-config.yamlopenspec/config.yamlscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Run quality gates in order: format, type-check, lint, yaml-lint, verify-modules-signature, contract-test, smart-test, test
Applied to files:
pyproject.tomltests/unit/test_pre_commit_quality_parity.pyREADME.mddocs/agent-rules/50-quality-gates-and-review.md.pre-commit-config.yamlopenspec/config.yamlscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Record failing/passing test evidence in openspec/changes/<change-id>/TDD_EVIDENCE.md and record review commands/timestamps when changes touch behavior or quality gates
Applied to files:
tests/unit/scripts/test_pre_commit_code_review.pydocs/agent-rules/50-quality-gates-and-review.mdopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Re-run code review when files in packages/, registry/, scripts/, tools/, tests/, or openspec/changes/<change-id>/ (excluding TDD_EVIDENCE.md) are modified
Applied to files:
tests/unit/scripts/test_pre_commit_code_review.pyREADME.mdscripts/pre_commit_code_review.pyopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Install and configure pre-commit hooks to mirror CI quality gates, running in order: module signature verification → scripts/pre-commit-quality-checks.sh → scripts/pre_commit_code_review.py
Applied to files:
tests/unit/test_pre_commit_quality_parity.pyREADME.mddocs/agent-rules/50-quality-gates-and-review.md.pre-commit-config.yamlopenspec/config.yamlscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Pre-commit hooks must mirror CI configuration: run `pre-commit install && pre-commit run --all-files`
Applied to files:
tests/unit/test_pre_commit_quality_parity.pyREADME.md.pre-commit-config.yamlscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to **/*.py : `ruff` linting runs on the full repository
Applied to files:
README.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Scope type-check and lint quality gates to src/, tests/, and tools/ directories for repo tooling quality
Applied to files:
README.mddocs/agent-rules/50-quality-gates-and-review.mdopenspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Verify an active OpenSpec change explicitly covers the requested scope before changing code; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Applied to files:
README.mddocs/agent-rules/50-quality-gates-and-review.mdopenspec/config.yaml
📚 Learning: 2026-04-02T21:49:11.371Z
Learnt from: djm81
Repo: nold-ai/specfact-cli-modules PR: 136
File: registry/modules/specfact-spec-0.40.17.tar.gz.sha256:1-1
Timestamp: 2026-04-02T21:49:11.371Z
Learning: In nold-ai/specfact-cli-modules, module tarball signatures (registry/signatures/*.tar.sig) are generated by the `publish-modules` GitHub Actions runner during the publish workflow, not committed locally to the branch. Missing signature files should NOT be flagged as a pre-merge blocker in PRs.
Applied to files:
README.mdopenspec/config.yaml
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Follow strict TDD order: spec delta -> failing tests -> implementation -> passing tests -> quality gates. Record TDD evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Applied to files:
openspec/config.yaml
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to openspec/changes/** : Never manually move folders under `openspec/changes/` into `archive/`. Archiving MUST use `openspec archive <change-id>` command
Applied to files:
openspec/config.yaml
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Use 'openspec archive <change-id>' for archiving changes; do not manually move folders under openspec/changes/ into openspec/changes/archive/
Applied to files:
openspec/config.yaml
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Run `hatch run check-bundle-imports` to enforce bundle import policies
Applied to files:
scripts/pre-commit-quality-checks.sh
🔀 Multi-repo context nold-ai/specfact-cli
Linked repositories findings
nold-ai/specfact-cli
-
scripts/validate_agent_rule_applies_when.py
- New validator is invoked by hatch script
validate-agent-rule-signalsin pyproject.toml and run by the Docs Review CI job: pyproject.toml (scripts) & .github/workflows/docs-review.yml — CI runshatch run validate-agent-rule-signals. [::nold-ai/specfact-cli::pyproject.toml:235][::nold-ai/specfact-cli::.github/workflows/docs-review.yml:89] - INDEX.md documents that validation step and ties the script to the canonical signals set referenced in the docs: docs/agent-rules/INDEX.md (validation mention & index header). Mismatch between the script's CANONICAL_TASK_SIGNALS and INDEX.md's applicability matrix will cause CI failures. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:87][::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:14,70]
- New validator is invoked by hatch script
-
docs/agent-rules/INDEX.md and the new rule files
- The INDEX and rule pages are the canonical source for agent loading and reference running sync_github_hierarchy_cache.py when cache is missing/stale: docs/agent-rules/INDEX.md (bootstrap step), docs/agent-rules/10-session-bootstrap.md, docs/agent-rules/60-github-change-governance.md. If the script behavior or outputs change, docs/tests that assume its contract may be affected. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:1-20][::nold-ai/specfact-cli::docs/agent-rules/10-session-bootstrap.md:14][::nold-ai/specfact-cli::docs/agent-rules/60-github-change-governance.md:13]
-
scripts/sync_github_hierarchy_cache.py
- Script is referenced from docs and expected to produce specific state/markdown artifacts used by agent rules and tests. Tests updated to require
state.repopresence and fingerprint semantics — changes to state JSON shape or DEFAULT paths will break tests: tests/unit/scripts/test_sync_github_hierarchy_cache.py and docs references. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py]
- Script is referenced from docs and expected to produce specific state/markdown artifacts used by agent rules and tests. Tests updated to require
-
scripts/pre_commit_code_review.py
- Refactor changes dynamic import/behavior and report handling; it is invoked indirectly by pre-commit wrappers and scripts/pre-commit-quality-checks.sh and is imported/used by unit tests. Ensure the refactor preserves the report file location/shape and public entry behavior expected by tests and callers. Relevant references: scripts/pre_commit_code_review.py, scripts/pre-commit-quality-checks.sh, tests/unit/scripts/test_pre_commit_code_review.py. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py][::nold-ai/specfact-cli::scripts/pre-commit-quality-checks.sh][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py]
-
Tests and CI integration
- New/updated tests exercise validate_agent_rule_applies_when, sync_github_hierarchy_cache, and pre_commit_code_review behavior (tests/unit/scripts/test_validate_agent_rule_applies_when.py, tests/unit/scripts/test_sync_github_hierarchy_cache.py, tests/unit/scripts/test_pre_commit_code_review.py). Any change in those scripts' public behavior, exit codes, output locations, or JSON report schemas will cause unit/CI failures. [::nold-ai/specfact-cli::tests/unit/scripts/test_validate_agent_rule_applies_when.py][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py]
-
Summary risk pointers (observed)
- Keep CANONICAL_TASK_SIGNALS in scripts/validate_agent_rule_applies_when.py aligned with the applicability matrix in docs/agent-rules/INDEX.md; CI runs this validator. [::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:14][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:69+]
- Preserve expected state JSON/markdown output shape and DEFAULT_* paths in sync_github_hierarchy_cache.py because docs and tests rely on
state.repoand fingerprint semantics. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py] - Ensure pre_commit_code_review.py still produces the report at
.specfact/code-review.json(or the same path/tests expectations) and retains callable behaviors used by pre-commit wrappers and unit tests. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py][::nold-ai/specfact-cli::scripts/pre-commit-quality-checks.sh: invoke][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py]
🔇 Additional comments (29)
docs/agent-rules/20-repository-context.md (3)
1-31: Front matter contract is complete and governance-ready.The page includes the expected governance metadata (
id,priority,applies_when,depends_on,stop_conditions, etc.) and is structured for deterministic rule loading.As per coding guidelines, this satisfies the docs governance requirement for user-facing accuracy and rule-page contract consistency.
67-77: Good cross-repo boundary guidance for modules vs core CLI.This section clearly distinguishes module-repo behavior, sibling core checkout resolution, and project-vs-user module precedence, which helps prevent adapter-boundary drift between
specfact-cli-modulesand corespecfact-cli.
41-53: 🧹 Nitpick | 🔵 TrivialReorder the command sequence to match the documented quality-gate flow.
Move
hatch run specfact code review run --json --out .specfact/code-review.jsoninto the quality-gate order near contract-test/block-2 steps, instead of placing it last, so docs and enforcement flow stay aligned.♻️ Proposed doc-order tweak
hatch run format hatch run type-check hatch run lint hatch run yaml-lint hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run specfact code review run --json --out .specfact/code-review.json hatch run contract-test hatch run smart-test hatch run test -hatch run specfact code review run --json --out .specfact/code-review.jsonAs per coding guidelines, the ordered quality/verification pipeline should remain consistent in user-facing docs.
⛔ Skipped due to learnings
Learnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code reviewLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-25T21:31:11.712Z Learning: Run quality gates in order: format, type-check, lint, yaml-lint, verify-modules-signature, contract-test, smart-test, testLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Generate and maintain .specfact/code-review.json using 'hatch run specfact code review run --json --out .specfact/code-review.json' before marking OpenSpec changes as completeLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Record failing/passing test evidence in openspec/changes/<change-id>/TDD_EVIDENCE.md and record review commands/timestamps when changes touch behavior or quality gatesLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-25T21:31:11.712Z Learning: Follow strict TDD order: spec delta -> failing tests -> implementation -> passing tests -> quality gates. Record TDD evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`Learnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Install and configure pre-commit hooks to mirror CI quality gates, running in order: module signature verification → scripts/pre-commit-quality-checks.sh → scripts/pre_commit_code_review.pyLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Verify an active OpenSpec change explicitly covers the requested scope before changing code; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gatesLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-25T21:31:11.712Z Learning: Run `hatch run check-bundle-imports` to enforce bundle import policiesLearnt from: CR Repo: nold-ai/specfact-cli-modules PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-03-31T23:13:02.695Z Learning: Re-run code review when files in packages/, registry/, scripts/, tools/, tests/, or openspec/changes/<change-id>/ (excluding TDD_EVIDENCE.md) are modifiedscripts/sync_github_hierarchy_cache.py (5)
21-22: Good consolidation of lint suppression scope.Moving
unnecessary-lambdasuppression to file scope removes duplication while preserving the icontract introspection pattern.
294-308: Precondition/postcondition refactor is cleaner and still deterministic.The shared non-blank predicate and extracted supported-type ensure improve readability without changing contract behavior.
402-405: Strong guardrails on cache-render inputs.These
@requirechecks make markdown generation fail-fast for invalid metadata, which protects deterministic cache output.
482-510: Repo-aware cache short-circuit is a solid correctness fix.Including
state["repo"]in the skip predicate and writing the same value to markdown/state closes cross-repo cache reuse risk while keeping state evolution backward-safe.
541-551: CLI error handling is now consistent and user-friendly.Catching operational exceptions and returning
1with a clear stderr message gives stable behavior for automation and pre-commit hooks.tests/conftest.py (1)
13-19: Good adapter-boundary consolidation for test bootstrapUsing
apply_specfact_workspace_envhere keeps test bootstrap behavior aligned with runtime/pre-commit bootstrap behavior.tests/unit/scripts/test_pre_commit_code_review.py (1)
89-99: Nice contract-hardening around pre-commit review report behaviorThese updates correctly model the report side effect and validate the new missing-report stderr contract.
Also applies to: 167-169
tests/unit/test_pre_commit_quality_parity.py (1)
11-38: Strong parity test upgrade for hook-order and pipeline contractThis materially improves protection against hook drift and ordering regressions in the pre-commit adapter path.
Also applies to: 69-83, 90-91
README.md (1)
56-60: Docs parity looks accurate for the new staged pre-commit flowThe Block 2/code-review and Block 1-lint scope description is clear and aligned with the new hook model.
.pre-commit-config.yaml (1)
1-2: Pre-commit stage split and fail-fast wiring are solidThis setup gives deterministic gate sequencing and clearer failure locality across signature checks, Block 1 stages, and Block 2.
Also applies to: 13-47
pyproject.toml (1)
68-68:validate-agent-rule-signalsis correctly enforced in the consuming repoThe hatch alias at Line 68 is properly wired: the parent repository (
specfact-cli) imports this module and invokes the validator viahatch run validate-agent-rule-signalsin its.github/workflows/docs-review.yml:89CI gate. This is the correct adapter boundary—the module repo exports the validation tool and tests, while the consumer repo enforces it against its own agent-rules documentation. The module's pre-commit hooks (per.pre-commit-config.yaml) rightly focus on module integrity (signatures → quality checks → code review), not on consumer-side governance rules.openspec/config.yaml (3)
32-36: LGTM — Pre-commit pipeline documentation aligns with implementation.The Block 1/Block 2 structure description accurately reflects the refactored
scripts/pre-commit-quality-checks.shsubcommand architecture. TheSPECFACT_MODULES_REPOandSPECFACT_REPO_ROOTenv var behavior matches whatapply_specfact_workspace_envdoes insrc/specfact_cli_modules/dev_bootstrap.py, maintaining parity with specfact-cli test/CI module discovery.
46-48: LGTM — Canonical governance reference aligns with bootstrap contract.The redirect to
AGENTS.mdplusdocs/agent-rules/**as the source of truth for workflow prose matches the retrieved learnings and eliminates duplication of long-form policy inside individual OpenSpec artifacts.
85-88: LGTM — Explicit readiness tasks strengthen public GitHub metadata completeness.The new readiness requirements for parent linkage, labels, project assignment, blockers/blocked-by, and
in progressconcurrency verification align with the governance contract indocs/agent-rules/60-github-change-governance.mdand the retrieved learnings about GitHub hierarchy cache usage.docs/agent-rules/50-quality-gates-and-review.md (3)
1-35: LGTM — Front matter metadata well-structured for agent governance.The
applies_whensignals (implementation,verification,finalization) andstop_conditionsalign with the validator expectations inscripts/validate_agent_rule_applies_when.py. Thedepends_onchain correctly establishes the loading order relative to the index and TDD rules.
39-48: LGTM — Quality gate order matches canonical pipeline.The sequence (
format→type-check→lint→yaml-lint→verify-modules-signature→contract-test→smart-test→test) aligns with retrieved learnings and the coding guidelines. The signature verification flags (--require-signature --payload-from-filesystem --enforce-version-bump) correctly enforce the module boundary contract for signed bundle assets.
69-71: LGTM — Module signature gate correctly documents re-sign + version bump flow.This accurately reflects the adapter boundary requirement: when bundle content changes break signature verification, manifests must be re-signed and module versions bumped before re-verification. This is critical for maintaining registry integrity and aligns with the linked repositories context about
module-package.yamland signature handling.scripts/pre-commit-quality-checks.sh (3)
19-22: LGTM — stderr redirection aligns with pre-commit buffering model.Redirecting all
info/success/warn/erroroutput to stderr (>&2) ensures progress messages appear incrementally between hooks rather than being buffered until hook completion. This matches the documented behavior in the header comment (lines 4-6).
54-60: LGTM — Extended Python detection to include.pyitype stubs.The
\.pyi?$pattern correctly matches both.pyand.pyifiles. The|| trueinstaged_python_filespreventsset -efrom exiting when no Python files are staged—important for the adapter boundary since bundle type stubs inpackages/*/src/**/*.pyishould be linted and reviewed.
149-169: LGTM — Code review gate correctly forwards staged files to the Python script.The
read/whileloop properly builds an array fromstaged_python_filesoutput, handling empty lines and passing file paths as separate arguments topre_commit_code_review.py. This matches the expected interface documented in the relevant code snippet (main(argv)accepts file paths).scripts/pre_commit_code_review.py (6)
31-44: LGTM — Dynamic loading isolates pre-commit from package install state.The
importlib.util.spec_from_file_locationapproach correctly loadsdev_bootstrap.pywithout requiring the package to be installed. This is essential for the adapter boundary since pre-commit hooks may run beforehatch run dev-depscompletes. TheRuntimeErroron load failure provides clear diagnostics.
100-106: LGTM — Stale report cleanup prevents false positives.The
_prepare_report_pathfunction correctly removes any existing report file before running a new review. This ensures the gate doesn't accidentally pass based on a stale report from a previous run—critical for maintaining the.specfact/code-review.jsoncontract documented in the linked repositories context.
109-128: LGTM — Subprocess execution with timeout and explicit error handling.The 300-second timeout is reasonable for large staged file sets. Returning
NoneonTimeoutExpiredallows the caller to cleanly exit with code 1. Thecapture_output=Truewithtext=Truecorrectly captures stdout/stderr as strings for diagnostic output.
138-148: LGTM — Missing report handling preserves subprocess exit code.The
_missing_report_exit_codefunction correctly forwards the subprocess return code when non-zero, and falls back to 1 when the subprocess succeeded but the report is missing. This handles edge cases where the nestedspecfact code review runexits 0 but fails to write the JSON artifact.
150-168: LGTM — Severity classification handles known bucket aliases.The
_classify_severityfunction correctly maps common severity aliases (err→error,warn→warning,advise→advisory) and falls back tootherfor unknown values. This provides resilience against minor schema variations in the code review output while maintaining the documented severity buckets.
249-275: LGTM — Main refactor correctly sequences workspace env and review execution.The early call to
apply_specfact_workspace_env(REPO_ROOT)ensuresSPECFACT_MODULES_REPOandSPECFACT_REPO_ROOTare set before any downstream operations. The control flow correctly handles:
- No files → skip with exit 0
- Runtime unavailable → exit 1 with guidance
- Timeout → exit 1
- Missing report → exit with subprocess code or 1
- Summary parse failure → exit 1
- Success → forward subprocess return code
This preserves the gate contract expected by
scripts/pre-commit-quality-checks.sh.
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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/pre-commit-quality-checks.sh`:
- Around line 171-186: Update the failure hint in run_contract_tests_visible to
suggest running the full test command for debugging: replace the current
advisory text that tells the user to run "hatch run contract-test-status" with a
message recommending "hatch run contract-test" (or both commands if you want to
preserve status check guidance), so when contract-first tests fail the user is
directed to run hatch run contract-test to reproduce and investigate the
failure.
In `@src/specfact_cli_modules/dev_bootstrap.py`:
- Around line 50-62: The apply_specfact_workspace_env function currently uses
os.environ.setdefault which leaves stale SPECFACT_MODULES_REPO and
SPECFACT_REPO_ROOT values from other worktrees; change it to unconditionally set
SPECFACT_MODULES_REPO to the resolved repo_root (use
os.environ["SPECFACT_MODULES_REPO"] = str(resolved)) and, for
SPECFACT_REPO_ROOT, set it to the resolved core when
resolve_core_repo(repo_root) returns a Path and remove or clear the env var (del
os.environ["SPECFACT_REPO_ROOT"] or os.environ.pop(..., None)) when core is None
so stale values are not retained.
- Around line 69-84: The _installed_core_root function currently imports
specfact_cli which can execute import-time code and fail; instead use
importlib.util.find_spec("specfact_cli") to get the ModuleSpec and read
spec.origin (or spec.loader.get_filename if needed) to locate the package file
without importing, then resolve that path and iterate parents with the existing
_is_core_repo check; keep the early guard with _installed_core_exists() and
preserve the same None returns when spec is missing or origin is None.
In `@tests/unit/tools/test_contract_first_smart_test.py`:
- Around line 44-61: Add a test that verifies _contract_test_status returns 1
when relevant files are staged: monkeypatch cfst_mod._git_staged_names to return
a list containing a relevant path (e.g., a test or src file like
"tests/unit/test_foo.py") and assert cfst_mod._contract_test_status() == 1 so
the positive path for running contract-tests is covered; place this new test
alongside the existing tests in
tests/unit/tools/test_contract_first_smart_test.py and reference the same
cfst_mod fixture and monkeypatch usage as the other tests.
🪄 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: fdb188f6-7a62-41a4-80a9-3a4c27745c24
📒 Files selected for processing (7)
docs/agent-rules/50-quality-gates-and-review.mdscripts/pre-commit-quality-checks.shsrc/specfact_cli_modules/dev_bootstrap.pytests/unit/test_dev_bootstrap.pytests/unit/test_pre_commit_quality_parity.pytests/unit/tools/test_contract_first_smart_test.pytools/contract_first_smart_test.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). (3)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.13)
🧰 Additional context used
📓 Path-based instructions (4)
tools/**/*.py
⚙️ CodeRabbit configuration file
tools/**/*.py: Developer tooling aligned with pyproject Hatch scripts and CI expectations.
Files:
tools/contract_first_smart_test.py
tests/**/*.py
⚙️ CodeRabbit configuration file
tests/**/*.py: Contract-first and integration tests: migration suites, bundle validation, and flakiness.
Ensure changes to adapters or bridges have targeted coverage.
Files:
tests/unit/test_pre_commit_quality_parity.pytests/unit/tools/test_contract_first_smart_test.pytests/unit/test_dev_bootstrap.py
src/**/*.py
⚙️ CodeRabbit configuration file
src/**/*.py: Repo infrastructure (not bundle code): keep parity with specfact-cli quality patterns;
contract-first public helpers where applicable; avoid print() in library paths.
Files:
src/specfact_cli_modules/dev_bootstrap.py
docs/**/*.md
⚙️ CodeRabbit configuration file
docs/**/*.md: User-facing and cross-site accuracy: Jekyll front matter, links per documentation-url-contract,
CLI examples matching bundled commands.
Files:
docs/agent-rules/50-quality-gates-and-review.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:51:09.821Z
Learning: Follow `AGENTS.md` as the mandatory bootstrap contract for all development workflows
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:51:09.821Z
Learning: Load `docs/agent-rules/INDEX.md` and the canonical rule files selected by its applicability matrix as the source of truth for worktree policy, OpenSpec gating, GitHub hierarchy-cache refresh, TDD order, quality gates, versioning, and documentation rules
Learnt from: CR
URL:
File: .cursorrules:undefined-undefined
Timestamp: 2026-04-12T22:51:09.821Z
Learning: Do not treat the bootstrap file as a standalone handbook; always cross-reference `docs/agent-rules/` for policy, gating, caching, TDD, quality, versioning, and documentation rules
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:51:17.187Z
Learning: Use AGENTS.md as the mandatory bootstrap surface for GitHub Copilot instructions
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:51:17.187Z
Learning: Use docs/agent-rules/INDEX.md as the canonical governance dispatcher
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:51:17.187Z
Learning: Work on feature/*, bugfix/*, hotfix/*, or chore/* branches, normally in a worktree rooted under ../specfact-cli-modules-worktrees/
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:51:17.187Z
Learning: Refresh .specfact/backlog/github_hierarchy_cache.md by running `python scripts/sync_github_hierarchy_cache.py` when GitHub hierarchy metadata is missing or stale
Learnt from: CR
URL:
File: .github/copilot-instructions.md:undefined-undefined
Timestamp: 2026-04-12T22:51:17.187Z
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-12T22:51:17.187Z
Learning: Full governance rules live in docs/agent-rules/; do not treat the GitHub Copilot Instructions file as a complete standalone handbook
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
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-12T22:51:28.164Z
Learning: Do not implement from the `dev` or `main` checkout by default
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
Learning: Do not auto-refine stale or ambiguous changes without the user
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
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-12T22:51:28.164Z
Learning: Finalize completed OpenSpec changes with `openspec archive <change-id>` (do not manually move change folders under `openspec/changes/archive/`)
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
Learning: Read AGENTS.md file before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
Learning: Read docs/agent-rules/INDEX.md before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
Learning: Read docs/agent-rules/05-non-negotiable-checklist.md before implementation
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
Learning: Detect repository root, active branch, and worktree state during session bootstrap
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
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-12T22:51:28.164Z
Learning: If GitHub hierarchy metadata is needed and `.specfact/backlog/github_hierarchy_cache.md` is missing or stale, refresh it with `python scripts/sync_github_hierarchy_cache.py`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-12T22:51:28.164Z
Learning: Load any additional rule files required by the applicability matrix in docs/agent-rules/INDEX.md before implementation
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:51:32.313Z
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-12T22:51:32.313Z
Learning: Treat canonical rule docs in docs/agent-rules/INDEX.md 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-12T22:51:32.313Z
Learning: Do not rely on CLAUDE.md as a standalone governance handbook
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:51:32.313Z
Learning: When a change is paired with work in specfact-cli, review the paired public change artifacts there before widening scope or redefining shared workflow semantics
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:51:32.313Z
Learning: Preserve the clean-code compliance gate and enforce its category references: naming, kiss, yagni, dry, and solid
Learnt from: CR
URL:
File: CLAUDE.md:undefined-undefined
Timestamp: 2026-04-12T22:51:32.313Z
Learning: Treat clean-code regressions as blocking until they are fixed or explicitly justified
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Install and configure pre-commit hooks to mirror CI quality gates, running in order: module signature verification → scripts/pre-commit-quality-checks.sh → scripts/pre_commit_code_review.py
Applied to files:
tests/unit/test_pre_commit_quality_parity.pydocs/agent-rules/50-quality-gates-and-review.mdscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Applied to files:
tests/unit/test_pre_commit_quality_parity.pydocs/agent-rules/50-quality-gates-and-review.mdscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Run quality gates in order: format, type-check, lint, yaml-lint, verify-modules-signature, contract-test, smart-test, test
Applied to files:
tests/unit/test_pre_commit_quality_parity.pydocs/agent-rules/50-quality-gates-and-review.mdscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Pre-commit hooks must mirror CI configuration: run `pre-commit install && pre-commit run --all-files`
Applied to files:
tests/unit/test_pre_commit_quality_parity.pyscripts/pre-commit-quality-checks.sh
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: dev-deps installs specfact-cli from $SPECFACT_CLI_REPO when set, otherwise ../specfact-cli; in worktrees, bootstrap should prefer matching specfact-cli-worktrees/<branch> checkout before falling back to canonical sibling repo
Applied to files:
src/specfact_cli_modules/dev_bootstrap.pytests/unit/test_dev_bootstrap.py
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Applies to packages/*/src/**/*.py : Only allowed `specfact_cli.*` prefixes may be imported in bundle code (CORE/SHARED APIs only)
Applied to files:
src/specfact_cli_modules/dev_bootstrap.pytests/unit/test_dev_bootstrap.py
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Record failing/passing test evidence in openspec/changes/<change-id>/TDD_EVIDENCE.md and record review commands/timestamps when changes touch behavior or quality gates
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Generate and maintain .specfact/code-review.json using 'hatch run specfact code review run --json --out .specfact/code-review.json' before marking OpenSpec changes as complete
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Scope type-check and lint quality gates to src/, tests/, and tools/ directories for repo tooling quality
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-31T23:13:02.695Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-31T23:13:02.695Z
Learning: Verify an active OpenSpec change explicitly covers the requested scope before changing code; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Applied to files:
docs/agent-rules/50-quality-gates-and-review.md
📚 Learning: 2026-03-25T21:31:11.712Z
Learnt from: CR
Repo: nold-ai/specfact-cli-modules PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-25T21:31:11.712Z
Learning: Run `hatch run check-bundle-imports` to enforce bundle import policies
Applied to files:
scripts/pre-commit-quality-checks.sh
🔀 Multi-repo context nold-ai/specfact-cli
nold-ai/specfact-cli
-
validate_agent_rule_applies_when.py defines CANONICAL_TASK_SIGNALS that must match the applicability tokens documented in docs/agent-rules/INDEX.md; the validator is exposed via hatch script and run by CI. Mismatch will cause CI/test failures. [::nold-ai/specfact-cli::scripts/validate_agent_rule_applies_when.py:1-120][::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:1-220]
-
docs/agent-rules/INDEX.md contains the canonical applicability matrix and explicitly documents running the validator (hatch run validate-agent-rule-signals). Tests assert existence and frontmatter keys of these rule files. [::nold-ai/specfact-cli::docs/agent-rules/INDEX.md:1-220][::nold-ai/specfact-cli::tests/unit/docs/test_agent_rules_governance.py:1-200]
-
sync_github_hierarchy_cache.py:
- Defaults: DEFAULT_OUTPUT_PATH = .specfact/backlog/github_hierarchy_cache.md and DEFAULT_STATE_PATH = .specfact/backlog/github_hierarchy_cache_state.json.
- The script now requires/uses a
repofield in the state JSON and compares repo_full_name + fingerprint to decide whether to skip regeneration. Tests check these defaults and the repo/fingerprint semantics; changing state layout or these keys will break tests and docs that rely on the cache semantics. [::nold-ai/specfact-cli::scripts/sync_github_hierarchy_cache.py:1-240][::nold-ai/specfact-cli::tests/unit/scripts/test_sync_github_hierarchy_cache.py:1-240][::nold-ai/specfact-cli::docs/agent-rules/10-session-bootstrap.md:1-80]
-
pre_commit_code_review.py:
- Writes/reads machine-readable report at .specfact/code-review.json (REVIEW_JSON_OUT), prepares the report path, runs nested review subprocess, and fails the gate if the report is missing or summary parsing fails.
- Tests expect the report file path, specific stderr summary lines, and particular missing-report messaging; changing the report path, name, or summary/output format will break tests and pre-commit integration. [::nold-ai/specfact-cli::scripts/pre_commit_code_review.py:1-320][::nold-ai/specfact-cli::tests/unit/scripts/test_pre_commit_code_review.py:1-240][::nold-ai/specfact-cli::scripts/pre-commit-smart-checks.sh:230-240]
Summary risk pointers
- Keep CANONICAL_TASK_SIGNALS in scripts/validate_agent_rule_applies_when.py synchronized with docs/agent-rules/INDEX.md (CI validation depends on this).
- Preserve .specfact/code-review.json path/semantics and the summary text/shape produced by pre_commit_code_review.py (pre-commit hooks and tests rely on exact location and messaging).
- Preserve DEFAULT_OUTPUT_PATH/DEFAULT_STATE_PATH and the state JSON keys (
repo,fingerprint) plus their semantics in sync_github_hierarchy_cache.py (docs/tests rely on them and other repos/modules are expected to implement compatible cache outputs).
🔇 Additional comments (20)
docs/agent-rules/50-quality-gates-and-review.md (4)
1-35: Well-structured frontmatter with correct applicability tokens.The frontmatter correctly declares
applies_when: [implementation, verification, finalization]which aligns with the canonical task signals expected byscripts/validate_agent_rule_applies_when.py. Thedepends_onreferences toagent-rules-indexandagent-rules-openspec-and-tddestablish proper rule loading order.
41-48: Quality gate order matches governance requirements.The documented order (format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test) aligns with learnings and the coding guidelines in
docs/agent-rules/50-quality-gates-and-review.md. This ensures pre-commit and CI parity.
50-56: Block 2 description now explicitly includes.pyiscope.Line 54 now correctly states "staged
*.pyand*.pyi" matching thestaged_python_files()implementation inscripts/pre-commit-quality-checks.sh. This addresses the previous review comment about type stub inclusion.
69-71: Module signature gate preserves adapter/bundle boundary enforcement.This gate ensures any change to signed module assets or manifests (registry,
module-package.yaml, bundle payloads) triggers re-signing and version bumps. This is critical for cross-repo contract integrity withspecfact-clicore's module verification expectations.tools/contract_first_smart_test.py (4)
15-25: Contract-test relevance patterns look complete for bundle/registry boundaries.The
_RELEVANT_PREFIXEStuple covers the key adapter surfaces (packages/,registry/,src/,tools/) plustests/andopenspec/. The_RELEVANT_SCRIPT_PYregex correctly matchesscripts/*.pyandscripts/*.pyiat the top level.One edge case: the regex
^scripts/.+\.pyi?$will matchscripts/subdir/foo.pybut only if such nested structures exist. Given this repo's flatscripts/layout, this is fine.
28-39: Defensive git index reading with proper failure handling.
_git_staged_namesreturnsNoneon failure rather than raising, which allows_contract_test_statusto fall back to running contract tests when git is unavailable. The-c core.quotepath=falseflag ensures filenames with special characters are returned unquoted.
54-74: Status semantics now correctly implemented: exit 0=skip, exit 1=run.This addresses the prior review finding. The logic:
Nonefrom git → return 1 (run tests, safe fallback)- Empty staging → return 0 (skip)
- Relevant paths staged → return 1 (run tests)
- Only irrelevant paths → return 0 (skip)
This matches the shell script's conditional:
if hatch run contract-test-status; then skip; else run.
94-95: Status command dispatch and safer fallback for unrecognized commands.The
statuscommand correctly routes to_contract_test_status(). The fallback change fromreturn 0toreturn 1for unrecognized commands is a safer default—unknown commands should fail rather than silently succeed.Also applies to: 105-105
tests/unit/test_pre_commit_quality_parity.py (4)
11-21: Hook order contract aligns with .pre-commit-config.yaml.The
_EXPECTED_HOOK_ORDERlist matches the hook IDs defined in.pre-commit-config.yaml(per context snippet). The_FORBIDDEN_HOOK_IDSset explicitly gates against legacy hooks (modules-quality-checks,specfact-code-review-gate), preventing regression to the old single-hook pattern.
23-41: Script fragments cover Block 1/Block 2 stage surface.The
_REQUIRED_SCRIPT_FRAGMENTStuple validates thatscripts/pre-commit-quality-checks.shcontains all expected commands (hatch run format,hatch run lint, etc.) and stage identifiers (Block 1 — stage 1/4,block1-format,run_block2, etc.). This acts as a contract test ensuring the shell script's structure doesn't silently regress.
72-75: Pairwise order assertion is concise and correct.Using
itertools.pairwise(Python 3.10+) to validate that each hook appears before its successor in the expected order is an elegant solution. The assertion will fail with a clearKeyErrorif any expected hook is missing from the config.
78-85: Test validates fail_fast and hook ordering contract.The test now explicitly asserts
fail_fast: True(line 80), which is critical for the Block 1 → Block 2 ordering semantics. Combined with the pairwise order check, this ensures pre-commit behavior matches the documented governance indocs/agent-rules/50-quality-gates-and-review.md.tests/unit/tools/test_contract_first_smart_test.py (2)
15-28: Dynamic module loading avoids bootstrap side effects.Loading
contract_first_smart_test.pyviaimportlib.utilrather than a direct import preventsdev_bootstrap_support.ensure_core_dependencyfrom running during test collection. The module-scoped fixture ensures the module is loaded once per test session.
31-41: Relevant path detection test covers key adapter boundaries.The test validates that
_names_require_contract_testcorrectly identifies paths touching contract surfaces:tests/,packages/,src/,tools/,openspec/,registry/,pyproject.toml, andscripts/*.py. It also confirmsdocs/README.mdand.pre-commit-config.yamlare correctly excluded.scripts/pre-commit-quality-checks.sh (6)
1-9: Clear subcommand architecture documentation.The header comment effectively explains why the script is split into subcommands: pre-commit buffers output per hook, so splitting stages allows progress visibility. This matches the
.pre-commit-config.yamlstructure where eachblock1-*andblock2hook invokes its own subcommand.
19-22: Output redirected to stderr for pre-commit compatibility.Redirecting all
info,success,warn,erroroutput to stderr (>&2) ensures pre-commit's buffering doesn't swallow status messages. This is the correct pattern for hook scripts.
54-60: Python file detection now includes type stubs (.pyi).Both
has_staged_pythonandstaged_python_filesnow use\.pyi?$regex, ensuring adapter type stubs in bundles are included in lint and code review gates. This aligns with the documentation update indocs/agent-rules/50-quality-gates-and-review.md.
149-168: Code review gate correctly collects staged Python files.The
run_code_review_gatefunction builds an array of staged*.pyand*.pyifiles and passes them topre_commit_code_review.py. The skip condition when no Python files are staged avoids unnecessary subprocess invocation.
239-248: Usage and help messages now include alias documentation.The
usage_errorfunction at line 240 now includes "(also: -h | --help | help)" addressing the prior review comment. Theshow_helpfunction provides a clean help output with alias documentation.
250-277: Main dispatcher covers all documented subcommands.The case statement correctly routes all Block 1 stages (
block1-format,block1-yaml,block1-bundle,block1-lint), Block 2 (block2), the full pipeline (all), and help variants. The default case (*) callsusage_errorensuring invalid subcommands fail explicitly.
| run_contract_tests_visible() { | ||
| info "📦 Block 2 — stage 2/2: contract tests — running \`hatch run contract-test-status\`" | ||
| if hatch run contract-test-status > /dev/null 2>&1; then | ||
| success "✅ Block 2 — stage 2/2: contract tests — skipped (contract-test-status: no input changes)" | ||
| else | ||
| info "📦 Block 2 — stage 2/2: contract tests — running \`hatch run contract-test\`" | ||
| if hatch run contract-test; then | ||
| success "✅ Block 2 — stage 2/2: contract-first tests passed" | ||
| warn "💡 CI may still run the full quality matrix" | ||
| else | ||
| error "❌ Block 2 — stage 2/2: contract-first tests failed" | ||
| warn "💡 Run: hatch run contract-test-status" | ||
| exit 1 | ||
| fi | ||
| fi | ||
| } |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Contract test stage correctly consumes status exit code.
The run_contract_tests_visible function uses the documented semantics: hatch run contract-test-status exits 0 to skip, non-zero to run tests. The /dev/null redirect is correct since only the exit code matters.
One minor note: the guidance at line 182 suggests running contract-test-status, but after a test failure the user likely wants to run hatch run contract-test directly to debug. Consider updating the hint.
📝 Optional guidance improvement
error "❌ Block 2 — stage 2/2: contract-first tests failed"
- warn "💡 Run: hatch run contract-test-status"
+ warn "💡 Run: hatch run contract-test"
exit 1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@scripts/pre-commit-quality-checks.sh` around lines 171 - 186, Update the
failure hint in run_contract_tests_visible to suggest running the full test
command for debugging: replace the current advisory text that tells the user to
run "hatch run contract-test-status" with a message recommending "hatch run
contract-test" (or both commands if you want to preserve status check guidance),
so when contract-first tests fail the user is directed to run hatch run
contract-test to reproduce and investigate the failure.
| def apply_specfact_workspace_env(repo_root: Path) -> None: | ||
| """Default SPECFACT_* workspace env for this checkout (matches specfact-cli test/CI patterns). | ||
|
|
||
| Pins ``SPECFACT_MODULES_REPO`` to the modules repo root and ``SPECFACT_REPO_ROOT`` to the resolved | ||
| sibling/core specfact-cli checkout when known. Discovery then agrees with ``specfact module list | ||
| --show-origin`` expectations; project ``.specfact/modules`` still wins over ``~/.specfact/modules`` | ||
| when both exist—remove stale user copies with ``specfact module uninstall <name> --scope user``. | ||
| """ | ||
| resolved = repo_root.resolve() | ||
| os.environ.setdefault("SPECFACT_MODULES_REPO", str(resolved)) | ||
| core = resolve_core_repo(repo_root) | ||
| if core is not None: | ||
| os.environ.setdefault("SPECFACT_REPO_ROOT", str(core)) |
There was a problem hiding this comment.
Overwrite derived workspace paths instead of inheriting stale SPECFACT_* values.
This helper is called at startup from tests/conftest.py:18 and scripts/pre_commit_code_review.py:252. Using setdefault() means a shell that still has SPECFACT_MODULES_REPO / SPECFACT_REPO_ROOT from another worktree keeps pointing this checkout at the old core, and the resolve_core_repo() is None path never clears that stale core root. That makes the bootstrap non-deterministic across worktrees.
Suggested fix
def apply_specfact_workspace_env(repo_root: Path) -> None:
@@
resolved = repo_root.resolve()
- os.environ.setdefault("SPECFACT_MODULES_REPO", str(resolved))
- core = resolve_core_repo(repo_root)
+ os.environ["SPECFACT_MODULES_REPO"] = str(resolved)
+ core = resolve_core_repo(resolved)
if core is not None:
- os.environ.setdefault("SPECFACT_REPO_ROOT", str(core))
+ os.environ["SPECFACT_REPO_ROOT"] = str(core.resolve())
+ else:
+ os.environ.pop("SPECFACT_REPO_ROOT", None)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/specfact_cli_modules/dev_bootstrap.py` around lines 50 - 62, The
apply_specfact_workspace_env function currently uses os.environ.setdefault which
leaves stale SPECFACT_MODULES_REPO and SPECFACT_REPO_ROOT values from other
worktrees; change it to unconditionally set SPECFACT_MODULES_REPO to the
resolved repo_root (use os.environ["SPECFACT_MODULES_REPO"] = str(resolved))
and, for SPECFACT_REPO_ROOT, set it to the resolved core when
resolve_core_repo(repo_root) returns a Path and remove or clear the env var (del
os.environ["SPECFACT_REPO_ROOT"] or os.environ.pop(..., None)) when core is None
so stale values are not retained.
| def _installed_core_root() -> Path | None: | ||
| """If ``specfact_cli`` is importable from a checkout layout, return that repo root.""" | ||
| if not _installed_core_exists(): | ||
| return None | ||
| try: | ||
| specfact_cli = importlib.import_module("specfact_cli") | ||
| except ModuleNotFoundError: | ||
| return None | ||
| init_file = specfact_cli.__file__ | ||
| if init_file is None: | ||
| return None | ||
| init_path = Path(init_file).resolve() | ||
| for parent in init_path.parents: | ||
| if _is_core_repo(parent): | ||
| return parent | ||
| return None |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find the dev_bootstrap.py file and understand the codebase structure
find . -name "dev_bootstrap.py" -type f
fd -t f "\.py$" src/ | head -20
</parameter>Repository: nold-ai/specfact-cli-modules
Length of output: 317
🏁 Script executed:
#!/bin/bash
# Read the dev_bootstrap.py file to verify the current state
cat -n src/specfact_cli_modules/dev_bootstrap.py
</parameter>Repository: nold-ai/specfact-cli-modules
Length of output: 4792
🏁 Script executed:
#!/bin/bash
# Search for ensure_core_dependency function in this repo
rg "ensure_core_dependency" --type py
</parameter>Repository: nold-ai/specfact-cli-modules
Length of output: 2588
🏁 Script executed:
#!/bin/bash
# Search for ensure_core_dependency and related bootstrap patterns in specfact-cli
rg "ensure_core_dependency" --type py -A 3
</parameter>Repository: nold-ai/specfact-cli
Length of output: 169
🏁 Script executed:
#!/bin/bash
# Check how specfact-cli does module probing to understand the pattern
rg "importlib.import_module|find_spec" --type py | head -20
</parameter>Repository: nold-ai/specfact-cli
Length of output: 2470
🏁 Script executed:
#!/bin/bash
# Check test file to understand how _installed_core_root is tested
cat -n tests/unit/test_dev_bootstrap.py | grep -A 20 "_installed_core_root\|_installed_core_exists"
</parameter>Repository: nold-ai/specfact-cli-modules
Length of output: 1813
🏁 Script executed:
#!/bin/bash
# Examine the full test file structure
wc -l tests/unit/test_dev_bootstrap.py
head -100 tests/unit/test_dev_bootstrap.py
</parameter>Repository: nold-ai/specfact-cli-modules
Length of output: 4053
🏁 Script executed:
#!/bin/bash
# Check if specfact-cli has bootstrap or similar patterns using find_spec
rg "find_spec" --type py -B 2 -A 5 | head -50
</parameter>Repository: nold-ai/specfact-cli
Length of output: 1710
Use importlib.util.find_spec() to safely probe the installed specfact-cli path without side effects.
Calling importlib.import_module("specfact_cli") during bootstrap triggers package import-time code. If the installed core has a broken or missing import-time dependency, this will crash before ensure_core_dependency() can recover by reinstalling. Use spec.origin instead to get the module path without importing. This pattern already exists in specfact-cli (ide_setup.py, modules/init/src/commands.py).
Suggested fix
def _installed_core_root() -> Path | None:
"""If ``specfact_cli`` is importable from a checkout layout, return that repo root."""
- if not _installed_core_exists():
- return None
- try:
- specfact_cli = importlib.import_module("specfact_cli")
- except ModuleNotFoundError:
- return None
- init_file = specfact_cli.__file__
+ spec = importlib.util.find_spec("specfact_cli")
+ if spec is None:
+ return None
+ init_file = spec.origin
if init_file is None:
return None
init_path = Path(init_file).resolve()
for parent in init_path.parents:
if _is_core_repo(parent):
return parent
return None📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| def _installed_core_root() -> Path | None: | |
| """If ``specfact_cli`` is importable from a checkout layout, return that repo root.""" | |
| if not _installed_core_exists(): | |
| return None | |
| try: | |
| specfact_cli = importlib.import_module("specfact_cli") | |
| except ModuleNotFoundError: | |
| return None | |
| init_file = specfact_cli.__file__ | |
| if init_file is None: | |
| return None | |
| init_path = Path(init_file).resolve() | |
| for parent in init_path.parents: | |
| if _is_core_repo(parent): | |
| return parent | |
| return None | |
| def _installed_core_root() -> Path | None: | |
| """If ``specfact_cli`` is importable from a checkout layout, return that repo root.""" | |
| spec = importlib.util.find_spec("specfact_cli") | |
| if spec is None: | |
| return None | |
| init_file = spec.origin | |
| if init_file is None: | |
| return None | |
| init_path = Path(init_file).resolve() | |
| for parent in init_path.parents: | |
| if _is_core_repo(parent): | |
| return parent | |
| return None |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/specfact_cli_modules/dev_bootstrap.py` around lines 69 - 84, The
_installed_core_root function currently imports specfact_cli which can execute
import-time code and fail; instead use importlib.util.find_spec("specfact_cli")
to get the ModuleSpec and read spec.origin (or spec.loader.get_filename if
needed) to locate the package file without importing, then resolve that path and
iterate parents with the existing _is_core_repo check; keep the early guard with
_installed_core_exists() and preserve the same None returns when spec is missing
or origin is None.
| def test_contract_test_status_returns_one_when_git_fails(monkeypatch: pytest.MonkeyPatch, cfst_mod) -> None: | ||
| monkeypatch.setattr( | ||
| cfst_mod, | ||
| "_git_staged_names", | ||
| lambda _root: None, | ||
| ) | ||
| assert cfst_mod._contract_test_status() == 1 | ||
|
|
||
|
|
||
| def test_contract_test_status_returns_zero_when_only_irrelevant_staged( | ||
| monkeypatch: pytest.MonkeyPatch, cfst_mod | ||
| ) -> None: | ||
| monkeypatch.setattr( | ||
| cfst_mod, | ||
| "_git_staged_names", | ||
| lambda _root: ["docs/README.md"], | ||
| ) | ||
| assert cfst_mod._contract_test_status() == 0 |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider adding test for relevant paths triggering contract-test run.
The tests cover git failure (returns 1) and irrelevant-only paths (returns 0), but there's no explicit test verifying _contract_test_status returns 1 when relevant paths ARE staged. This would complete the contract coverage.
📝 Suggested additional test case
def test_contract_test_status_returns_one_when_relevant_staged(
monkeypatch: pytest.MonkeyPatch, cfst_mod
) -> None:
monkeypatch.setattr(
cfst_mod,
"_git_staged_names",
lambda _root: ["tests/unit/test_foo.py"],
)
assert cfst_mod._contract_test_status() == 1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/unit/tools/test_contract_first_smart_test.py` around lines 44 - 61, Add
a test that verifies _contract_test_status returns 1 when relevant files are
staged: monkeypatch cfst_mod._git_staged_names to return a list containing a
relevant path (e.g., a test or src file like "tests/unit/test_foo.py") and
assert cfst_mod._contract_test_status() == 1 so the positive path for running
contract-tests is covered; place this new test alongside the existing tests in
tests/unit/tools/test_contract_first_smart_test.py and reference the same
cfst_mod fixture and monkeypatch usage as the other tests.
1 participant
Summary
Implements OpenSpec
governance-04-deterministic-agent-governance-loading: move long-form agent policy into canonicaldocs/agent-rules/with an applicability matrix, keepAGENTS.md/CLAUDE.md/.cursorrules/.github/copilot-instructions.mdas thin bootstrap aliases, addscripts/validate_agent_rule_applies_when.pyand doc/unit tests, hardensync_github_hierarchy_cache.pyand pre-commit review integration, and refreshopenspec/config.yaml, nav, and change artifacts (TDD_EVIDENCE.md, validation).Also adds
tests/__init__.pysohatch run lint(pylint on theteststree) succeeds on pylint 4.x.Refs:
Scope
packages/registry/index.json,packages/*/module-package.yaml).github/workflows/*)docs/*,README.md,AGENTS.md)scripts/sign-modules.py,scripts/verify-modules-signature.py)Bundle Impact
No bundle or registry edits in this PR; versions unchanged.
nold-ai/specfact-project: n/anold-ai/specfact-backlog: n/anold-ai/specfact-codebase: n/anold-ai/specfact-spec: n/anold-ai/specfact-govern: n/aValidation Evidence
Local gates (worktree, 2026-04-12):
hatch run format— passedhatch run type-check— passedhatch run lint— passed (after addingtests/__init__.py)hatch run yaml-lint— passedhatch run check-bundle-imports— passedhatch run contract-test— passedhatch run smart-test— passedopenspec validate governance-04-deterministic-agent-governance-loading --strict— passedRequired local gates
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run contract-testhatch run smart-test(orhatch run test)Signature + version integrity (required)
module-package.yaml/ registry payload changes (pre-commit signature hook still passed on commit)hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump(skipped — no signed payload changes)CI and Branch Protection
verify-module-signaturesquality (3.11)quality (3.12)quality (3.13)Docs / Pages
docs/)docs-pages.yml, if changed)specfact-clidocs updated (if applicable)Checklist
docs/agent-rules/; no runtime API change