Conversation
📝 WalkthroughOpenSpec Governance Change: GitHub Hierarchy Cache Sync (modules-local)Change ID: governance-03-github-hierarchy-cache Bundle & Module SurfaceNo impact. All six module-package.yaml manifests remain unchanged. The new script ( Manifest & IntegrityNo semver, signature, or registry impacts. Module manifests and versioning remain stable across all packages. Cross-Repo AlignmentThis change is paired with a specfact-cli governance entry but involves no code sharing or import coupling. The modules-side script is repo-local and deterministic; its implementation must remain aligned with the core change on the cache-first lookup model (both repos consult Implementation Details
Governance & Workflow Documentation
New Public Entities (scripts/sync_github_hierarchy_cache.py only)
Test Coverage & Quality GatesTDD evidence confirms passing unit tests (11 scenarios), py_compile validation, forced sync execution, fingerprint stability checks, and quality gate compliance (Ruff, basypyright, pytest, code review). Code review JSON updated and passing. WalkthroughThis PR implements a repository-local GitHub Epic/Feature hierarchy cache for the modules repo, including a deterministic sync script, comprehensive unit tests, OpenSpec governance documentation, and updated AGENTS.md workflow guidance for cache-first issue parenting. Changes
Sequence DiagramsequenceDiagram
actor Agent as Agent / Contributor
participant Cache as Local Cache<br/>(.specfact/backlog/)
participant Script as sync_github_hierarchy<br/>_cache.py
participant GH as GitHub API<br/>(GraphQL)
participant State as State File<br/>(fingerprint)
Agent->>Script: Run sync script (or auto-trigger)
Script->>State: Load persisted fingerprint
Script->>GH: Fetch Epic & Feature issues<br/>(paginated GraphQL)
GH-->>Script: Issue nodes (metadata, hierarchy)
Script->>Script: Compute current fingerprint<br/>(SHA-256 of hierarchy)
Script->>Script: Compare: current == stored?
alt Fingerprints Match & Cache Exists
Script->>Agent: Report: no update needed
else Fingerprint Changed or Force Flag Set
Script->>Script: Normalize & render<br/>deterministic Markdown
Script->>Cache: Write github_hierarchy_cache.md
Script->>State: Update state file<br/>(new fingerprint, timestamp)
Script->>Agent: Report: cache updated
end
Agent->>Cache: Consult cache for<br/>Epic/Feature parenting<br/>(skip GitHub lookup)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes The implementation includes a substantial new script with GraphQL pagination, deterministic fingerprinting, markdown rendering, and file state management (594 LoC), paired with a comprehensive test suite exercising mocked GraphQL, module reloading, and edge cases. The governance/spec documentation is well-structured but requires tracing cross-repo coupling with Possibly related issues
Suggested labels
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![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: c735883230
ℹ️ 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: 9
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/governance-03-github-hierarchy-cache/proposal.md`:
- Around line 8-9: Proposal text currently states the central markdown inventory
is under "openspec/" but the implemented cache writes to
".specfact/backlog/github_hierarchy_cache.md"; update the proposal paragraph in
governance-03-github-hierarchy-cache/proposal.md to reference the actual cache
path ".specfact/backlog/github_hierarchy_cache.md" (and mention the
fingerprint/state check remains) so the documented contract matches the
implemented behavior and avoids drift between the proposal and the script that
produces the cache.
- Around line 25-31: The paired core change reference
`specfact-cli/governance-02-github-hierarchy-cache` is not verifiable in the
core repo's CHANGE_ORDER which only lists `governance-02-exception-management`;
either update the proposal to point to the actual specfact-cli artifact (verify
and replace the `specfact-cli/governance-02-github-hierarchy-cache` reference
with the correct CHANGE_ORDER entry or PR/issue link) or reword the
paired-change line to state this is "intended alignment pending paired core
change implementation" so the proposal no longer asserts a non-existent core
artifact; check `CHANGE_ORDER`, `governance-02-exception-management`, and the
referenced issue IDs to confirm the correct cross-repo link.
In
`@openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md`:
- Around line 1-24: The markdown has linter issues: change the first line from
"## ADDED Requirements" to a top-level heading (prepend a single "#" so it
becomes H1) and ensure every heading (e.g., "Requirement: Repository hierarchy
cache sync", "Scenario: Generate hierarchy cache from GitHub metadata",
"Scenario: Fast exit on unchanged hierarchy state", "Requirement: Modules
governance must use cache-first hierarchy lookup", "Scenario: Cache-first
governance guidance") is followed by a single blank line; update those headings
in the spec.md so there is one blank line after each heading and remove any
immediate text on the same line as a heading to satisfy the markdown linter.
In `@openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md`:
- Around line 30-36: Update the "Final scoped quality gates" section in
TDD_EVIDENCE.md (the "Final scoped quality gates" block) to either (A) record
the full ordered run of quality gates matching the required sequence (format →
type-check → lint → yaml-lint → verify-modules-signature → contract-test →
smart-test → test → specfact code review), including the exact commands and
their PASS/FAIL results, or (B) add a clear, explicit scoped-exception rationale
that states which gates were intentionally omitted, why, who approved the
exception, and the date/identifier of approval; ensure the entry replaces the
current incomplete list and clearly references each gate name in the order
above.
In `@scripts/sync_github_hierarchy_cache.py`:
- Around line 410-466: sync_cache currently calls fetch_hierarchy_issues twice
(once with fingerprint_only=True and again with fingerprint_only=False),
doubling GitHub API requests; fix by fetching full issue details only once when
an update is likely or reuse the detailed fetch to compute the fingerprint: call
fetch_hierarchy_issues(repo_owner=..., repo_name=..., fingerprint_only=False)
into detailed_issues, compute fingerprint via
compute_hierarchy_fingerprint(detailed_issues), compare to
state.get("fingerprint") and short-circuit if unchanged, otherwise proceed to
write output and state; alternatively, if you want to preserve the bandwidth
optimization, cache the first fingerprint-only result and reuse it instead of
re-calling fetch_hierarchy_issues — update the sync_cache logic and any variable
names (detailed_issues, fingerprint) accordingly.
- Around line 303-309: SUPPORTED_ISSUE_TYPES is a frozenset so iterating it
yields an implementation-dependent order; change _group_issues_by_type to
iterate a deterministic sequence instead (e.g., introduce an explicit ordered
tuple like SUPPORTED_ISSUE_TYPES_ORDER = ("Epic","Feature") or similar and use
that) and return the groups in that order (or return an OrderedDict) so the dict
keys are produced deterministically; update references to use
SUPPORTED_ISSUE_TYPES_ORDER in _group_issues_by_type (and keep
render_cache_markdown as-is which expects a specific ordering).
- Around line 28-67: The two GraphQL strings _FINGERPRINT_QUERY and
_DETAIL_QUERY are duplicated except for bodyText; consolidate by creating a
single base query template used by both paths and parameterize whether bodyText
is included (for example by constructing the query string dynamically or using a
helper function like build_issue_query(include_body: bool) that returns the
query with or without bodyText), update callers to use the new builder, and
remove the redundant _FINGERPRINT_QUERY/_DETAIL_QUERY constants so schema
changes are maintained in one place.
- Around line 198-222: The _run_graphql_query function currently calls
subprocess.run without a timeout which can hang; add a reasonable timeout
argument to the subprocess.run call (e.g., timeout=30) and wrap the call in a
try/except that catches subprocess.TimeoutExpired and raises a RuntimeError
including the timeout exception details (and any partial stdout/stderr) so
callers get a clear failure instead of hanging; update references to
subprocess.run in _run_graphql_query and ensure the new exception path produces
a descriptive RuntimeError.
In `@tests/unit/scripts/test_sync_github_hierarchy_cache.py`:
- Around line 172-215: Add unit tests covering the missing scenarios around
sync_cache: create a test that calls sync_cache(..., force=True) and asserts
that the output file is rewritten even when compute_hierarchy_fingerprint
returns the same value (use monkeypatch on compute_hierarchy_fingerprint and
fetch_hierarchy_issues to simulate regeneration), add a test that monkeypatches
_run_graphql_query (or the module-level function used by fetch_hierarchy_issues)
to raise RuntimeError and assert sync_cache surfaces or handles the error as
expected, and add a test that writes a malformed JSON into the state file and
asserts sync_cache either regenerates the cache or returns a clear error;
reference sync_cache, fetch_hierarchy_issues, compute_hierarchy_fingerprint, and
_run_graphql_query when locating code to patch.
🪄 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: 7cde521a-a1d7-4ab1-8edd-4a2f1c85334f
📒 Files selected for processing (13)
AGENTS.mdopenspec/CHANGE_ORDER.mdopenspec/changes/governance-03-github-hierarchy-cache/.openspec.yamlopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/config.yamlscripts/sync_github_hierarchy_cache.pytests/unit/scripts/test_sync_github_hierarchy_cache.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.13)
- GitHub Check: quality (3.11)
🧰 Additional context used
📓 Path-based instructions (10)
openspec/changes/**
📄 CodeRabbit inference engine (CLAUDE.md)
Never manually move folders under
openspec/changes/intoarchive/. Archiving MUST useopenspec archive <change-id>command
Files:
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/design.md
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-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/CHANGE_ORDER.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/design.md
openspec/changes/*/TDD_EVIDENCE.md
📄 CodeRabbit inference engine (AGENTS.md)
Record failing/passing evidence in
openspec/changes/<change-id>/TDD_EVIDENCE.mdRecord SpecFact code review command(s) and timestamp in
openspec/changes/<change-id>/TDD_EVIDENCE.mdor PR description when the change touches behavior or quality gates
Files:
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md
openspec/CHANGE_ORDER.md
📄 CodeRabbit inference engine (AGENTS.md)
Update
openspec/CHANGE_ORDER.mdin the same change when archive status changes
Files:
openspec/CHANGE_ORDER.md
**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.py: Line length must be 120 characters
Python target version is 3.11+
rufflinting runs on the full repository
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.pyscripts/sync_github_hierarchy_cache.py
{src,tests,tools}/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
basedpyrightandpylintare scoped tosrc/,tests/, andtools/directories
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.py
{src,tests,tools}/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
Scope
type-checkandlinttosrc/,tests/, andtools/for repo tooling quality
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.py
tests/**/*.{py,pyi}
📄 CodeRabbit inference engine (AGENTS.md)
Use
tests/for bundle behavior and migration parity tests
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.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_sync_github_hierarchy_cache.py
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/sync_github_hierarchy_cache.py
🧠 Learnings (16)
📓 Common learnings
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Keep bundle package code under `packages/`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Keep registry metadata in `registry/index.json` and `packages/*/module-package.yaml`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: This repository hosts official nold-ai bundles only; third-party bundles publish from their own repositories
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Use SemVer patch for bug fixes with no command/API change
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Use SemVer minor for new command, option, or public API addition
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Use SemVer major for breaking API/behavior change or command removal
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Treat `core_compatibility` review as mandatory on each version bump
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Never work directly on `dev` and `main` branches; use feature branches: `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Use worktrees for parallel branch work; allowed branch types are `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`; forbidden in worktrees: `dev`, `main`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Keep primary checkout as canonical `dev` workspace; keep worktree paths under `../specfact-cli-modules-worktrees/<branch-type>/<branch-slug>`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Before changing code, verify an active OpenSpec change explicitly covers the requested scope; if missing scope, create or extend a change first
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Do not manually move folders under `openspec/changes/` into `openspec/changes/archive/`; use `openspec archive <change-id>` command instead
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: When SpecFact code review JSON is missing or stale (older than any changed file under `packages/`, `registry/`, `scripts/`, `tools/`, `tests/`, or `openspec/changes/` except `TDD_EVIDENCE.md`), re-run `hatch run specfact code review run --json --out .specfact/code-review.json`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Prefer `--scope changed` for SpecFact code review when iterating on a branch for fast feedback; run `--scope full` before final PR submission
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Read the SpecFact code review JSON report and fix every finding at any severity unless the change proposal documents a rare, explicit, justified exception
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Include explicit tasks for generating/updating SpecFact code review JSON and clearing findings in OpenSpec change `tasks.md` (per `openspec/config.yaml` → `rules.tasks` → 'SpecFact code review JSON')
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Rerun `python scripts/sync_github_hierarchy_cache.py` when GitHub hierarchy cache is missing or stale; recreate it as part of OpenSpec and GitHub issue work; do not commit `.specfact/backlog/github_hierarchy_cache.md`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: For GitHub issue setup, parent linking, or blocker lookup, consult `.specfact/backlog/github_hierarchy_cache.md` first
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Install and run pre-commit hooks to mirror CI quality gates: module signature verification → `scripts/pre-commit-quality-checks.sh` (includes `hatch run lint` / pylint for staged Python) → `scripts/pre_commit_code_review.py`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Bootstrap in worktrees should prefer matching `specfact-cli-worktrees/<branch>` checkout before falling back to canonical sibling repo
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Branch from `origin/dev` into a feature/hotfix branch, bump bundle version in `packages/<bundle>/module-package.yaml`, run publish pre-check with `python scripts/publish-module.py --bundle <bundle>`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:13:12.336Z
Learning: Publish with `scripts/publish-module.py --bundle <name>` wrapper plus packaging flow, update `registry/index.json` with new `latest_version`, artifact URL, and checksum, tag release and merge via PR after quality gates pass
📚 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/changes/governance-03-github-hierarchy-cache/.openspec.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/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/changes/governance-03-github-hierarchy-cache/.openspec.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/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: Verify an active OpenSpec change covers the requested scope before changing code. Create or extend a change first if missing
Applied to files:
AGENTS.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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/CHANGE_ORDER.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:
AGENTS.mdopenspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/CHANGE_ORDER.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: Update core_compatibility in packages/<bundle>/module-package.yaml and registry/index.json when a bundle requires a newer minimum specfact-cli version
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 {packages/*/module-package.yaml,registry/index.json} : When bumping a bundle version, review and update `core_compatibility` in both `module-package.yaml` and `registry/index.json`
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 packages/*/module-package.yaml : Use SemVer for bundle versioning: patch (bug fix), minor (new command/option/API), major (breaking change/removal)
Applied to files:
openspec/config.yaml
📚 Learning: 2026-04-02T21:49:07.435Z
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:07.435Z
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/config.yamlopenspec/CHANGE_ORDER.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:
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 quality gates in order: format, type-check, lint, yaml-lint, verify-modules-signature, contract-test, smart-test, test
Applied to files:
openspec/config.yaml
🪛 LanguageTool
AGENTS.md
[uncategorized] ~112-~112: The official name of this software platform is spelled with a capital “H”.
Context: ...ent linking, or blocker lookup, consult .specfact/backlog/github_hierarchy_cache.md first. This cache i...
(GITHUB)
[uncategorized] ~113-~113: The official name of this software platform is spelled with a capital “H”.
Context: ...tate and MUST NOT be committed. - Rerun python scripts/sync_github_hierarchy_cache.py whenever the cache ...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/tasks.md
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...ripts/. - [x] 3.2 Generate the initial .specfact/backlog/github_hierarchy_cache.md` output and ensure r...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...failed with FileNotFoundError because scripts/sync_github_hierarchy_cache.py did not exist yet. ...
(GITHUB)
[uncategorized] ~28-~28: The official name of this software platform is spelled with a capital “H”.
Context: ...log/github_hierarchy_cache.md- Secondpython3 scripts/sync_github_hierarchy_cache.pyrun →GitHub hiera...
(GITHUB)
[uncategorized] ~33-~33: The official name of this software platform is spelled with a capital “H”.
Context: ...mp: 2026-04-09T22:04:19+02:00 - Ruff: `PATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/.venv/bin:$PATH PYTHONPATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/src .venv/bin/ruff check scripts/sync_github_hierarchy_cache.py tests/unit/scripts/t...
(GITHUB)
[uncategorized] ~34-~34: The official name of this software platform is spelled with a capital “H”.
Context: ...rarchy_cache.py→ PASS - basedpyright:PATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/.venv/bin:$PATH PYTHONPATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/src .venv/bin/basedpyright scripts/sync_github_hierarchy_cache.py tests/unit/scripts/t...
(GITHUB)
[uncategorized] ~35-~35: The official name of this software platform is spelled with a capital “H”.
Context: ...PASS (0 errors, 0 warnings) - pytest: PATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/.venv/bin:$PATH PYTHONPATH=/home/dom/git/nold-ai/specfact-cli-modules-worktrees/feature/governance-03-github-hierarchy-cache/src .venv/bin/pytest tests/unit/scripts/test_sync_github_hierarchy_cache.py -q → PASS (`5 passe...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/design.md
[uncategorized] ~35-~35: Did you mean the formatting language “Markdown” (= proper noun)?
Context: .... ### Split fingerprint detection from markdown rendering The script will compute a fin...
(MARKDOWN_NNP)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 12-12: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 17-17: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 16-16: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 16-16: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/design.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 29-29: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔀 Multi-repo context nold-ai/specfact-cli
Findings
nold-ai/specfact-cli
-
No code or docs reference the new script name or cache filename: searches for "sync_github_hierarchy_cache" and "github_hierarchy_cache" returned no matches in this repository. [::nold-ai/specfact-cli::]
-
The repository contains extensive backlog-related command code, specs, and docs that are the logical consumers/owners of backlog-parenting behavior (potentially impacted by a cache-first workflow). Notable files and locations (examples from search results):
- backlog command CLI surface and registry: src/specfact_cli/cli.py [::nold-ai/specfact-cli::]
- GitHub/ADO adapter guidance and auth helpers (may be used by backlog operations): src/specfact_cli/adapters/github.py, src/specfact_cli/adapters/ado.py [::nold-ai/specfact-cli::]
- Backlog sync / backlog-sync specification and requirements: openspec/specs/backlog-sync/spec.md and many other backlog-related specs under openspec/specs/ and openspec/changes/* [::nold-ai/specfact-cli::]
- Integration and unit tests exercising backlog behavior: tests/integration/sync/* and tests/unit/commands/test_backlog_daily.py etc. [::nold-ai/specfact-cli::]
Interpretation (observed): there are many backlog-related entrypoints and specs that could be affected by a modules-side cache-first guidance, but there are no direct code references to the new script or cache file in this repository. [::nold-ai/specfact-cli::]
Tag:
🔇 Additional comments (14)
scripts/sync_github_hierarchy_cache.py (4)
1-25: LGTM on module setup and defaults.The imports, constants, and default paths are well-organized. The default paths correctly point to
.specfact/backlog/which is gitignored per the context snippet. The use offrozensetforSUPPORTED_ISSUE_TYPESensures immutability.
70-101: LGTM on data models.The frozen dataclasses are appropriate for immutable issue representations.
SyncResultcleanly captures the sync outcome for callers.
469-498: LGTM on CLI implementation.The argument parser and
mainfunction are clean. The@ensureon exit code is a nice touch. Output messages clearly indicate whether the cache was updated.
281-300: 🧹 Nitpick | 🔵 TrivialRedundant label sorting in fingerprint computation.
Line 293 sorts labels again with
sorted(issue.labels, key=str.lower), but_label_names(line 161) already returns sorted labels. This is harmless for correctness but adds unnecessary work.♻️ Minor cleanup
- "labels": sorted(issue.labels, key=str.lower), + "labels": issue.labels, # Already sorted by _label_names> Likely an incorrect or invalid review comment.tests/unit/scripts/test_sync_github_hierarchy_cache.py (2)
22-33: Dynamic module loading is appropriate here.Since
scripts/isn't a Python package, usingimportlib.utilto load the script as a module is the right approach. Thelru_cacheensures the module is loaded once per test session.
75-105: Good test for fingerprint determinism.This test correctly validates that the fingerprint is order-independent, which is critical for the fast-exit optimization.
openspec/changes/governance-03-github-hierarchy-cache/.openspec.yaml (1)
1-2: LGTM on OpenSpec manifest.The manifest correctly declares
spec-drivenschema and creation date.openspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.md (1)
1-12: LGTM on validation record.The validation evidence correctly documents the
openspec validate --strictpass and notes the spec alignment.AGENTS.md (1)
112-113: LGTM on cache-first workflow guidance.The new instructions correctly direct users to consult the local hierarchy cache before GitHub lookups, and to rerun the sync script when stale. This aligns with the spec in
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md.Note: The static analysis hints about capitalizing "GitHub" are false positives—these refer to file paths and command strings where the casing is correct.
Cross-repo consideration: The linked
nold-ai/specfact-clirepository has extensive backlog-related commands but no current references to this cache workflow. If future CLI backlog commands should integrate with this cache-first approach, ensure alignment is tracked in the paired core change referenced in CHANGE_ORDER.md (specfact-cli/governance-02-github-hierarchy-cache).openspec/CHANGE_ORDER.md (3)
56-56: LGTM on project-runtime entry.The entry correctly tracks
project-runtime-01-safe-artifact-write-policywith its parent feature and paired core/bug references.
78-78: LGTM on governance-03 entry.The entry correctly references parent feature
#163and the paired core changespecfact-cli/governance-02-github-hierarchy-cache.
81-85: LGTM on new section.The "Code review and sidecar validation improvements" section is properly structured with the expected table format.
openspec/config.yaml (2)
57-57: LGTM on proposal rule.The new rule correctly enforces cache-first hierarchy lookup for GitHub issue setup, with clear guidance on when to rerun the sync script.
71-71: LGTM on task precondition.The task rule properly sequences the cache consultation before GitHub issue creation or parent linking, and correctly identifies the cache as ephemeral.
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md
Outdated
Show resolved
Hide resolved
djm81
added
enhancement
djm81
force-pushed
the
feature/governance-03-github-hierarchy-cache
branch
from
c735883 to
112d332
Compare
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@openspec/changes/governance-03-github-hierarchy-cache/design.md`:
- Line 1: The top-level heading "## Context" should be an H1 and several
headings (the ones at lines referenced in the review: the headings currently at
line 23, line 29, and line 35) need a blank line following them to satisfy
markdownlint MD041/MD022; change "## Context" to "# Context" and ensure there is
a single blank line after each of the headings at those three locations so every
heading is followed by a blank line.
In `@openspec/changes/governance-03-github-hierarchy-cache/proposal.md`:
- Line 1: The document starts with an H2 ("## Why") so MD041 is triggered; add a
single top-level H1 title as the first line (e.g., "# <descriptive title for
this proposal>") and move the existing "## Why" heading to remain as an H2 below
it so the file begins with an H1 and the Why section stays as "## Why" (adjust
the first-line heading in the proposal.md accordingly).
In
`@openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md`:
- Around line 7-8: Change the spec's outcome for the GitHub-specific scenario so
it only mentions GitHub issues: update the WHEN line using the command specfact
backlog sync --adapter github --project-id <repo> and replace the THEN text that
currently reads "OpenSpec changes are exported to GitHub issues/ADO work items"
with a GitHub-only outcome like "OpenSpec changes are exported to GitHub issues"
so the scenario does not imply ADO work-item creation.
In
`@openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md`:
- Around line 1-4: The markdown uses H3 (###) under the top-level H1 "ADDED
Requirements" but these should be H2 to normalize heading increments; change the
"Requirement: Repository hierarchy cache sync" heading (and the other
"Requirement:" headings in the same document section) from ### to ## so they are
direct H2 children of "ADDED Requirements" and ensure all subsequent requirement
headings in that block (the other occurrence covering lines ~20-24) are likewise
demoted from H3 to H2 to fix MD001 violations.
In `@openspec/changes/governance-03-github-hierarchy-cache/tasks.md`:
- Around line 19-20: The task list shows item "4.2" as incomplete while
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md claims all
gates passed; update the task state or provide rationale: either mark "4.2 Run
the required repo quality gates..." as checked in tasks.md, or add a short note
under that task explaining why gates remain open (e.g., waiting on
.specfact/code-review.json refresh or a specific failing gate), and ensure the
TDD_EVIDENCE.md is consistent with the tasks and mentions the status of
.specfact/code-review.json and the documented gate order.
In `@openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md`:
- Around line 1-39: This PR mixes an unrelated OpenSpec change ("Runtime
Adoption Of Safe Artifact Write Policy") into a PR scoped to
governance-03-github-hierarchy-cache; remove the
project-runtime-01-safe-artifact-write-policy proposal and any references to
capability names like runtime-artifact-write-safety, backlog-add, backlog-sync,
and related source tracking lines (GitHub Issue `#177` / specfact-cli-modules)
from this PR, and instead create a new, separate PR that only contains that
OpenSpec change (with clear linkage to the paired core change specfact-cli#487 /
profile-04-safe-project-artifact-writes, tests, and TDD steps); ensure the
current PR only contains artifacts and OpenSpec deltas relevant to
governance-03-github-hierarchy-cache and add a brief note in the new PR
describing the separation for reviewers.
In
`@openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md`:
- Line 7: Update the phrasing in the "**WHEN**" clause that currently reads "a
backlog-add related local helper targets an existing user-project artifact" to
use a hyphenated compound adjective: change it to "a backlog-add-related local
helper targets an existing user-project artifact" so the spec reads more
clearly; locate the "**WHEN**" line in the spec (the clause starting with "a
backlog-add related local helper") and apply the hyphenation to
"backlog-add-related" throughout the document if repeated.
In
`@openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md`:
- Around line 3-6: Add a trailing blank line after the Markdown headings "###
Requirement: Backlog sync local export paths SHALL avoid silent overwrite" and
"#### Scenario: Existing export target produces conflict or safe merge" so each
heading is followed by an empty line (fixing MD022); update the spec.md content
around those headings (the heading strings are unique identifiers) to insert a
single blank line immediately after each heading.
In
`@openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md`:
- Around line 1-6: Change the first heading to a top-level heading and add a
blank line after each heading to satisfy markdownlint: replace "## ADDED
Requirements" with "# ADDED Requirements", and ensure there is a blank line
following the "Requirement: Bundle runtime commands SHALL use the core
safe-write contract for user-project artifacts" heading and the "Scenario:
Runtime command writes owned artifact through safe-write helper" heading (and
any other headings in the same block) so every heading is followed by an empty
line.
In `@openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md`:
- Around line 23-25: The checklist in tasks.md runs contract-test before module
signature verification; reorder the quality-gate checklist so the sequence is:
run format → type-check → lint → yaml-lint → verify-modules-signature (the step
that bumps/resigns/verifies manifests) → contract-test → smart-test/test
coverage for changed packages → ensure .specfact/code-review.json is fresh and
record final review command/timestamp in TDD_EVIDENCE.md or PR notes; update the
lines that currently list "hatch run contract-test" and "Run module signature
verification..." (and the final specfact/code-review item) to match this
mandated order.
In `@openspec/config.yaml`:
- Line 57: The governance text hard-codes a "cache-first parent-lookup" contract
referencing the cache path ".specfact/backlog/github_hierarchy_cache.md" and the
sync script "scripts/sync_github_hierarchy_cache.py" even though core backlog
commands do not implement it; either update this rule to be pending or align it
with a core change: either (A) mark the governance rule as pending (add a clear
"pending until core implements cache-first lookup" note) and document the exact
expected core API/behavior for backlog add/sync commands, or (B) coordinate this
PR with a core PR that implements cache-first lookup in the backlog add/sync
codepaths so the governance text can remain active; ensure the rule references
the cache file path and the sync script name and explicitly states the required
core functions/behaviors to be implemented.
In `@scripts/sync_github_hierarchy_cache.py`:
- Around line 89-91: Update the GraphQL subIssues fragment to fetch child issue
types by adding "issueType { name }" to the subIssues selection, and in the
_child_links function filter the child nodes to only include those whose
issueType.name is "Epic" or "Feature" before adding them to the cache; locate
the subIssues fragment in the query and modify it accordingly and then apply the
filter in the _child_links function (or its equivalent) so only Epic/Feature
children populate the hierarchy cache.
🪄 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: a1561cf6-71b9-4d65-bb3b-d3ec2e8ff734
📒 Files selected for processing (21)
AGENTS.mdopenspec/CHANGE_ORDER.mdopenspec/changes/governance-03-github-hierarchy-cache/.openspec.yamlopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yamlopenspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/design.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.mdopenspec/config.yamlscripts/sync_github_hierarchy_cache.pytests/unit/scripts/test_sync_github_hierarchy_cache.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: quality (3.11)
- GitHub Check: quality (3.13)
- GitHub Check: quality (3.12)
🧰 Additional context used
📓 Path-based instructions (7)
openspec/changes/**
📄 CodeRabbit inference engine (CLAUDE.md)
Never manually move folders under
openspec/changes/intoarchive/. Archiving MUST useopenspec archive <change-id>command
Files:
openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/design.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
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/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/CHANGE_ORDER.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/design.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.py: Line length must be 120 characters
Python target version is 3.11+
rufflinting runs on the full repository
Files:
scripts/sync_github_hierarchy_cache.pytests/unit/scripts/test_sync_github_hierarchy_cache.py
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/sync_github_hierarchy_cache.py
{src,tests,tools}/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
basedpyrightandpylintare scoped tosrc/,tests/, andtools/directories
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.py
{src,tests,tools}/**
📄 CodeRabbit inference engine (AGENTS.md)
Type-check and lint scopes are limited to
src/,tests/, andtools/for repo tooling quality
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.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_sync_github_hierarchy_cache.py
🧠 Learnings (18)
📓 Common learnings
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: SpecFact code review JSON (`.specfact/code-review.json`) is a mandatory quality gate and must pass before OpenSpec change is considered complete
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Use feature branches for implementation: `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`; never work directly on `dev` or `main`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Git worktrees must follow policy: allowed branch types are `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`; forbidden are `dev` and `main`; keep paths under `../specfact-cli-modules-worktrees/<branch-type>/<branch-slug>`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Before changing code, verify an active OpenSpec change explicitly covers the requested scope; follow TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Record failing/passing test evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Archiving of OpenSpec changes MUST use `openspec archive <change-id>` command; do not manually move folders under `openspec/changes/` to `openspec/changes/archive/`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Keep bundle package code under `packages/` directory
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Keep registry metadata in `registry/index.json` and `packages/*/module-package.yaml`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Use `tests/` directory for bundle behavior and migration parity tests
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: This repository hosts official nold-ai bundles only; third-party bundles must publish from their own repositories
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: SemVer patch bump: bug fix with no command/API change
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: SemVer minor bump: new command, option, or public API addition
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: SemVer major bump: breaking API/behavior change or command removal
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Treat `core_compatibility` review as mandatory on each version bump
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T20:45:45.631Z
Learning: Rerun `python scripts/sync_github_hierarchy_cache.py` whenever the cache is missing or stale as part of OpenSpec and GitHub issue work
📚 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/changes/governance-03-github-hierarchy-cache/.openspec.yamlAGENTS.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/changes/governance-03-github-hierarchy-cache/.openspec.yamlopenspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yamlopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdAGENTS.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/design.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/config.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/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: 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/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.mdopenspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/config.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.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-03-github-hierarchy-cache/CHANGE_VALIDATION.mdopenspec/config.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/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/config.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/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: Update core_compatibility in packages/<bundle>/module-package.yaml and registry/index.json when a bundle requires a newer minimum specfact-cli version
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 {packages/*/module-package.yaml,registry/index.json} : When bumping a bundle version, review and update `core_compatibility` in both `module-package.yaml` and `registry/index.json`
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 packages/*/module-package.yaml : Use SemVer for bundle versioning: patch (bug fix), minor (new command/option/API), major (breaking change/removal)
Applied to files:
openspec/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:
openspec/config.yamlopenspec/CHANGE_ORDER.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/config.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.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:
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.yamlAGENTS.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.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:
openspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/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: Verify an active OpenSpec change covers the requested scope before changing code. Create or extend a change first if missing
Applied to files:
AGENTS.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:
openspec/changes/governance-03-github-hierarchy-cache/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: 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:
scripts/sync_github_hierarchy_cache.py
🪛 LanguageTool
openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...lently replaced - WHEN a backlog-add related local helper targets an existing...
(QB_NEW_EN_HYPHEN)
AGENTS.md
[uncategorized] ~112-~112: The official name of this software platform is spelled with a capital “H”.
Context: ...ent linking, or blocker lookup, consult .specfact/backlog/github_hierarchy_cache.md first. This cache i...
(GITHUB)
[uncategorized] ~113-~113: The official name of this software platform is spelled with a capital “H”.
Context: ...tate and MUST NOT be committed. - Rerun python scripts/sync_github_hierarchy_cache.py whenever the cache ...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...failed with FileNotFoundError because scripts/sync_github_hierarchy_cache.py did not exist yet. ...
(GITHUB)
[uncategorized] ~28-~28: The official name of this software platform is spelled with a capital “H”.
Context: ...log/github_hierarchy_cache.md- Secondpython3 scripts/sync_github_hierarchy_cache.pyrun →GitHub hiera...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/tasks.md
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...ripts/. - [x] 3.2 Generate the initial .specfact/backlog/github_hierarchy_cache.md` output and ensure r...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/design.md
[uncategorized] ~35-~35: Did you mean the formatting language “Markdown” (= proper noun)?
Context: .... ### Split fingerprint detection from markdown rendering The script will compute a fin...
(MARKDOWN_NNP)
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ... repo-local markdown hierarchy cache at .specfact/backlog/github_hierarchy_cache.md (ignored; not commi...
(GITHUB)
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...plus a companion fingerprint/state file .specfact/backlog/github_hierarchy_cache_state.json so the sync...
(GITHUB)
openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md
[style] ~11-~11: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...t emit or mutate project artifacts. - NEW: Define adoption guidance so bundle a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
[warning] 3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
openspec/changes/governance-03-github-hierarchy-cache/design.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 29-29: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 29-29: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 29-29: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 35-35: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 11-11: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 16-16: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 24-24: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔀 Multi-repo context nold-ai/specfact-cli
Linked repositories findings
nold-ai/specfact-cli
-
No direct callers or references to the new script name or cache filename discovered:
- Search for "sync_github_hierarchy_cache", "github_hierarchy_cache", "github-hierarchy-cache" returned no matches. [::nold-ai/specfact-cli::]
-
Backlog-related code and specs that are likely consumers of the modules-side cache-first guidance:
- Command specs and implementations for backlog flows that resolve GitHub repo context or perform sync/add operations:
- openspec/specs/backlog-sync/spec.md (backlog sync requirements) [::nold-ai/specfact-cli::]
- openspec/specs/backlog-add/spec.md (backlog add requirements) [::nold-ai/specfact-cli::]
- openspec/specs/devops-sync/spec.md (references baseline files and --project-id usage) [::nold-ai/specfact-cli::]
- openspec/specs/daily-standup/spec.md (describes resolution order and git-remote inference for repo context) [::nold-ai/specfact-cli::]
- Tests and utilities referencing repository-local .specfact artifacts and repo inference:
- tests/unit/commands/test_backlog_config.py (loads .specfact/backlog.yaml) [::nold-ai/specfact-cli::]
- tests/integration/sync/test_backlog_sync.py and tests/integration/sync/test_multi_adapter_backlog_sync.py (integration tests for backlog sync) [::nold-ai/specfact-cli::]
- tests/unit/utils/test_ide_setup.py (backlog add prompt scaffolding) [::nold-ai/specfact-cli::]
- Multiple spec/docs reference persisted artifacts under .specfact (e.g., .specfact/backlog-baseline.json, .specfact/backlog-config.yaml) used by sync/add flows and policy engine. Examples:
- openspec/specs/policy-engine/spec.md (loads .specfact/backlog-baseline.json) [::nold-ai/specfact-cli::]
- openspec/specs/devops-sync/spec.md (baseline file default .specfact/backlog-baseline.json) [::nold-ai/specfact-cli::]
- Command specs and implementations for backlog flows that resolve GitHub repo context or perform sync/add operations:
-
Potential integration touchpoints (observed, not code-linked):
- The modules script introduces defaults and behaviors (default output path .specfact/backlog/github_hierarchy_cache.md; state file .specfact/backlog/github_hierarchy_cache_state.json; repo name parsing from git remote). Core already implements repo inference from git remote and consumes various .specfact artifacts, so the new modules-side cache and its repo-name parsing logic could affect how backlog add/sync commands decide parent lookup or skip GitHub lookups if they adopt the cache-first guidance. Files showing similar behavior:
- openspec/specs/daily-standup/spec.md (git remote inference) [::nold-ai/specfact-cli::]
- tests referencing baseline/config artifacts (see tests above) [::nold-ai/specfact-cli::]
- The modules script introduces defaults and behaviors (default output path .specfact/backlog/github_hierarchy_cache.md; state file .specfact/backlog/github_hierarchy_cache_state.json; repo name parsing from git remote). Core already implements repo inference from git remote and consumes various .specfact artifacts, so the new modules-side cache and its repo-name parsing logic could affect how backlog add/sync commands decide parent lookup or skip GitHub lookups if they adopt the cache-first guidance. Files showing similar behavior:
Conclusion: No direct code-level references to the new script or cache file in this repo were found, but numerous backlog commands, specs, and tests consume or expect repo-local .specfact artifacts and perform repo inference—these are the logical consumers that should be checked when adopting the cache-first workflow introduced by this PR. Recommend reviewers verify runtime expectations and default paths (output/state filenames and repo inference) align between modules and core backlog adapters/commands. [::nold-ai/specfact-cli::]
🔇 Additional comments (6)
openspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yaml (1)
1-2: OpenSpec manifest metadata looks correct.
schemaandcreatedfields are present and consistent with a new change manifest.openspec/changes/governance-03-github-hierarchy-cache/.openspec.yaml (1)
1-2: Manifest header is valid for a new OpenSpec change.No issues in this metadata block.
openspec/changes/governance-03-github-hierarchy-cache/CHANGE_VALIDATION.md (1)
1-12: Validation artifact is clear and complete.The strict validation command and PASS result are documented with useful notes.
openspec/CHANGE_ORDER.md (1)
56-56: CHANGE_ORDER additions are well-formed and traceable.Both new rows match the existing dependency/blocked-by structure and improve sequencing clarity.
Also applies to: 78-78
AGENTS.md (1)
112-113: Cache-first workflow guidance is explicit and actionable.This correctly codifies parent-linking via local cache plus stale/missing cache resync.
Based on learnings: “Rerun
python scripts/sync_github_hierarchy_cache.pywhenever the cache is missing or stale as part of OpenSpec and GitHub issue work.”openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md (1)
30-44: Quality-gate evidence now matches required ordered sequence.The final block includes all required gates in order and records the code-review JSON output, which closes the prior gap.
openspec/changes/governance-03-github-hierarchy-cache/design.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
Show resolved
Hide resolved
openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md
Outdated
Show resolved
Hide resolved
...es/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md
Outdated
Show resolved
Hide resolved
openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.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
`@openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md`:
- Line 1: The file currently begins with an H2 ("## MODIFIED Requirements")
which violates markdownlint MD041; add a single top-level H1 line above it (for
example "# Backlog Sync Requirements" or another appropriate concise title) so
the first line is an H1 and the existing H2 remains unchanged; update the
document header only (no other content changes) to satisfy MD041.
In `@scripts/sync_github_hierarchy_cache.py`:
- Around line 54-68: The subprocess.run call in _default_repo_name_from_git
should include a short timeout (e.g., timeout=3) to avoid hanging imports; add
the timeout argument to the subprocess.run invocation and catch
subprocess.TimeoutExpired (alongside FileNotFoundError/OSError) to return None,
leaving the existing return-path that calls
parse_repo_name_from_remote_url(completed.stdout) unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6e2a4392-38f5-42c0-a0e7-0c6b1b4bf7f6
📒 Files selected for processing (9)
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/config.yamlscripts/sync_github_hierarchy_cache.pytests/unit/scripts/test_sync_github_hierarchy_cache.py
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: quality (3.13)
- GitHub Check: quality (3.12)
- GitHub Check: quality (3.11)
🧰 Additional context used
📓 Path-based instructions (6)
openspec/changes/**
📄 CodeRabbit inference engine (CLAUDE.md)
Never manually move folders under
openspec/changes/intoarchive/. Archiving MUST useopenspec archive <change-id>command
Files:
openspec/changes/governance-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
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-03-github-hierarchy-cache/design.mdopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md
**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.py: Line length must be 120 characters
Python target version is 3.11+
rufflinting runs on the full repository
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.pyscripts/sync_github_hierarchy_cache.py
{src,tests,tools}/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
basedpyrightandpylintare scoped tosrc/,tests/, andtools/directories
Files:
tests/unit/scripts/test_sync_github_hierarchy_cache.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_sync_github_hierarchy_cache.py
scripts/**/*.py
⚙️ CodeRabbit configuration file
scripts/**/*.py: Deterministic tooling: signing, publishing, docs generation; subprocess and path safety.
Files:
scripts/sync_github_hierarchy_cache.py
🧠 Learnings (17)
📓 Common learnings
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Install and run pre-commit hooks to mirror CI quality gates in local development
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Run quality gates in order: format → type-check → lint → yaml-lint → verify-modules-signature → contract-test → smart-test → test → specfact code review
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Run `hatch run specfact code review run --json --out .specfact/code-review.json` before final PR submission and whenever files under `packages/`, `registry/`, `scripts/`, `tools/`, `tests/`, or `openspec/changes/<change-id>/` are modified
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Use feature branches for implementation with naming convention: `feature/*`, `bugfix/*`, `hotfix/*`, or `chore/*`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Never work directly on protected `dev` and `main` branches; always work on feature branches
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Create Git worktrees under `../specfact-cli-modules-worktrees/<branch-type>/<branch-slug>` for parallel branch work; keep primary checkout as canonical `dev` workspace
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Before changing code, verify an active OpenSpec change explicitly covers the requested scope; follow strict TDD order: spec delta → failing tests → implementation → passing tests → quality gates
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Record failing/passing test evidence in `openspec/changes/<change-id>/TDD_EVIDENCE.md` as part of the change workflow
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Use `openspec archive <change-id>` command to archive changes; do not manually move folders under `openspec/changes/` into `openspec/changes/archive/`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Update `openspec/CHANGE_ORDER.md` when archive status changes for a change
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Keep bundle package code under `packages/` directory
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Keep registry metadata in `registry/index.json` and `packages/*/module-package.yaml`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Apply `type-check` and `lint` quality gates to `src/`, `tests/`, and `tools/` directories for repo tooling quality
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Use `tests/` directory for bundle behavior and migration parity tests
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Host only official nold-ai bundles in this repository; third-party bundles must publish from their own repositories
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Use SemVer for bundle versioning: patch for bug fixes with no command/API change, minor for new commands/options/public API additions, major for breaking API/behavior changes or command removal
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Update `core_compatibility` in `packages/<bundle>/module-package.yaml` and `registry/index.json` entry metadata when a bundle requires a newer minimum `specfact-cli` version
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Treat `core_compatibility` review as mandatory on each version bump
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Run `python scripts/publish-module.py --bundle <bundle>` as a publish pre-check before releasing a bundle
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Bump bundle version in `packages/<bundle>/module-package.yaml` before release and update `registry/index.json` with new `latest_version`, artifact URL, and checksum
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Tag release and merge via PR after quality gates pass in the release process
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Consult `.specfact/backlog/github_hierarchy_cache.md` first for GitHub issue setup, parent linking, or blocker lookup; do not commit this file as it is ephemeral local state
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Rerun `python scripts/sync_github_hierarchy_cache.py` whenever the cache is missing or stale, and recreate it as part of OpenSpec and GitHub issue work
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Install development dependencies with `hatch env create` and `hatch run dev-deps`; `dev-deps` installs `specfact-cli` from `$SPECFACT_CLI_REPO` when set, otherwise from `../specfact-cli`
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: In worktrees, the bootstrap should prefer the matching `specfact-cli-worktrees/<branch>` checkout before falling back to the canonical sibling repo
Learnt from: CR
URL:
File: AGENTS.md:undefined-undefined
Timestamp: 2026-04-09T21:16:29.496Z
Learning: Pre-commit hooks must run in order: module signature verification → `scripts/pre-commit-quality-checks.sh` → `scripts/pre_commit_code_review.py`, with the last hook writing `.specfact/code-review.json` for fast feedback on staged `*.py` / `*.pyi` files
📚 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/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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.yamlopenspec/changes/governance-03-github-hierarchy-cache/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: 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: Update core_compatibility in packages/<bundle>/module-package.yaml and registry/index.json when a bundle requires a newer minimum specfact-cli version
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 {packages/*/module-package.yaml,registry/index.json} : When bumping a bundle version, review and update `core_compatibility` in both `module-package.yaml` and `registry/index.json`
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 packages/*/module-package.yaml : Use SemVer for bundle versioning: patch (bug fix), minor (new command/option/API), major (breaking change/removal)
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: 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.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.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/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.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:
openspec/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:
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: 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/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/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: 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/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/proposal.mdopenspec/changes/governance-03-github-hierarchy-cache/tasks.mdopenspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.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:
openspec/config.yamlopenspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.mdopenspec/changes/governance-03-github-hierarchy-cache/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: Scope type-check and lint quality gates to src/, tests/, and tools/ directories for repo tooling quality
Applied to files:
openspec/changes/governance-03-github-hierarchy-cache/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: 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:
openspec/changes/governance-03-github-hierarchy-cache/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: 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:
scripts/sync_github_hierarchy_cache.py
🪛 LanguageTool
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md
[uncategorized] ~8-~8: The official name of this software platform is spelled with a capital “H”.
Context: ...failed with FileNotFoundError because scripts/sync_github_hierarchy_cache.py did not exist yet. ...
(GITHUB)
[uncategorized] ~28-~28: The official name of this software platform is spelled with a capital “H”.
Context: ...log/github_hierarchy_cache.md- Secondpython3 scripts/sync_github_hierarchy_cache.pyrun →GitHub hiera...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/proposal.md
[uncategorized] ~10-~10: The official name of this software platform is spelled with a capital “H”.
Context: ... repo-local markdown hierarchy cache at .specfact/backlog/github_hierarchy_cache.md (ignored; not commi...
(GITHUB)
[uncategorized] ~10-~10: The official name of this software platform is spelled with a capital “H”.
Context: ...plus a companion fingerprint/state file .specfact/backlog/github_hierarchy_cache_state.json so the sync...
(GITHUB)
openspec/changes/governance-03-github-hierarchy-cache/tasks.md
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...ripts/. - [x] 3.2 Generate the initial .specfact/backlog/github_hierarchy_cache.md` output and ensure r...
(GITHUB)
🪛 markdownlint-cli2 (0.22.0)
openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🔀 Multi-repo context nold-ai/specfact-cli
Linked repositories findings
nold-ai/specfact-cli
-
No code references to the new script or exact cache names were found (search for "sync_github_hierarchy_cache", "github_hierarchy_cache", "github-hierarchy-cache" returned no matches). [::nold-ai/specfact-cli::]
-
Files that consume or define repo-local .specfact backlog artifacts (potential consumers / integration touchpoints):
- tests/unit/commands/test_backlog_config.py — loads/validates
.specfact/backlog.yamland repo-context resolution. [::nold-ai/specfact-cli::] - openspec/specs/daily-standup/spec.md — documents resolution order for repo context (CLI args > env >
.specfact/backlog.yaml) and allows inferring repo fromgit remote get-url origin. This overlaps with the script's repo-inference behavior. [::nold-ai/specfact-cli::] - openspec/specs/backlog-sync/spec.md — backlog sync requirements and alias
backlog ceremony sync→specfact backlog sync; describes expected sync behaviors that the modules-side cache-first guidance may affect. [::nold-ai/specfact-cli::] - openspec/specs/backlog-add/spec.md — backlog add requirements (parent selection/validation) which may be impacted if callers begin consulting the local hierarchy cache for parent resolution. [::nold-ai/specfact-cli::]
- tests/integration/sync/test_backlog_sync.py and tests/integration/sync/test_multi_adapter_backlog_sync.py — integration tests for bidirectional backlog sync (logical consumers of any cache-first behavior). [::nold-ai/specfact-cli::]
- openspec/specs/devops-sync/spec.md and many other openspec docs/specs reference
.specfact/backlog-baseline.json,.specfact/backlog-config.yaml, and other repo-local artifacts used by backlog flows. These show the project already relies on repo-local .specfact artifacts and related inference behaviors. [::nold-ai/specfact-cli::]
- tests/unit/commands/test_backlog_config.py — loads/validates
-
Noted potential mismatches to verify during review:
- Default paths/names: the modules PR defaults output to
.specfact/backlog/github_hierarchy_cache.mdand state.specfact/backlog/github_hierarchy_cache_state.json. Core expects and documents many.specfact/*filenames (e.g.,.specfact/backlog-baseline.json,.specfact/backlog-config.yaml,.specfact/backlog.yaml); reviewers should confirm naming conventions and discovery order are compatible if core will adopt cache-first behavior. [::nold-ai/specfact-cli::] - Repo-context inference: the script infers repo name from git remote; core also documents inference from
git remote get-url origin. Confirm parsing and fallback behavior align to avoid inconsistent repo resolution across modules and core. [::nold-ai/specfact-cli::] - Backlog sync/add semantics: core specs enforce duplicate-detection and spec-kit extension awareness for sync/add flows — if modules’ cache is consulted first, ensure sync/add still honor existing duplicate-detection contracts and do not introduce missed lookups or false skips. [::nold-ai/specfact-cli::]
- Default paths/names: the modules PR defaults output to
Conclusion: No direct callers were found in this repo for the new script or cache filename, but multiple backlog-related commands, specs, and tests are logical consumers of a repo-local cache. Reviewers should focus on default path naming, repo inference parsing/fallbacks, and ensuring cache-first guidance does not violate existing backlog-sync/add contracts (duplicate detection, spec-kit extension awareness, and artifact discovery order). [::nold-ai/specfact-cli::]
🔇 Additional comments (20)
openspec/config.yaml (1)
57-63: Good adapter-boundary guardrail for cache-first workflow.The “Pending until core” framing keeps modules governance aligned without implying runtime coupling in
specfact-clibefore the paired core behavior lands.Also applies to: 77-81
openspec/changes/governance-03-github-hierarchy-cache/specs/github-hierarchy-cache/spec.md (1)
3-29: Requirements are clear and operationally testable.Deterministic render, fingerprint no-op behavior, and cache-first/ephemeral governance guidance are all concretely specified and align with the modules-side workflow.
openspec/changes/governance-03-github-hierarchy-cache/design.md (1)
25-44: Design scope is clean and boundary-safe.Keeping the cache repo-local/ephemeral while mirroring the core contract shape avoids coupling drift and keeps governance tooling portable in this repo.
openspec/changes/governance-03-github-hierarchy-cache/TDD_EVIDENCE.md (1)
30-49: Verification evidence is now complete and auditable.The ordered gate log plus explicit code-review JSON outcome gives a clear, reviewable closeout trail for this governance change.
openspec/changes/governance-03-github-hierarchy-cache/proposal.md (1)
9-13: Proposal path contract now matches implementation reality.Documenting
.specfact/backlog/github_hierarchy_cache.mdand its companion state file removes governance/implementation drift for module-side planning workflows.openspec/changes/governance-03-github-hierarchy-cache/tasks.md (1)
19-20: Task-state consistency looks good now.Completing 4.2 brings the checklist in line with the recorded verification narrative.
tests/unit/scripts/test_sync_github_hierarchy_cache.py (1)
227-379: Strong hardening coverage on sync control paths.The
force=True, GraphQL failure propagation, malformed-state recovery, and unchanged-fingerprint no-op tests materially improve confidence in cache-sync behavior.scripts/sync_github_hierarchy_cache.py (13)
1-78: LGTM! Module setup is well-structured.Constants for paths (
.specfact/backlog/github_hierarchy_cache.md,.specfact/backlog/github_hierarchy_cache_state.json) align with the documented ephemeral local state conventions. TheSUPPORTED_ISSUE_TYPES_ORDERtuple ensures deterministic iteration, and the 120-second GraphQL timeout provides reasonable subprocess safety.
25-51: LGTM! URL parsing handles common Git remote formats.The function correctly handles
git@,https://, and bare path formats while stripping trailing slashes and.gitsuffixes. This parsing approach aligns with howspecfact-clicore infers repo context fromgit remote get-url originper the linked repository findings.
81-103: LGTM! Query builder consolidates previous duplicate queries and enables child filtering.The dynamic query construction addresses the earlier review feedback about duplicated
_FINGERPRINT_QUERYand_DETAIL_QUERY. Importantly, line 98 now fetchesissueType { name }forsubIssues, which enables the_child_linksfunction to filter children to only Epic/Feature types—addressing the prior concern about cache scope violation.
106-138: LGTM! Dataclasses are well-designed as immutable DTOs.The
frozen=Trueensures instance immutability. Whilelabelsandchildrenare mutable list types, the code constructs fresh sorted lists during parsing and never mutates them post-creation, maintaining effective immutability.
209-218: LGTM! Child filtering correctly restricts to Epic/Feature types.The
_child_linksfunction at line 215 now filterssubIssuesto only include items where_subissue_type_name(item) in SUPPORTED_ISSUE_TYPES. This directly addresses the previous review concern about Tasks, Bugs, and other issue types polluting the hierarchy cache.
243-282: LGTM! GraphQL execution has proper subprocess safety.The implementation correctly addresses prior timeout concerns with
timeout=_GH_GRAPHQL_TIMEOUT_SEC. Error handling is comprehensive:TimeoutExpiredis caught with partial output captured, non-zero return codes raiseRuntimeError, and GraphQL-level errors in the response payload are surfaced. No shell injection risk exists since command arguments are passed as a list.
309-335: LGTM! Fetch function has robust contracts and pagination.The
@requirepreconditions prevent blank repository parameters, and the@ensurepostcondition (_all_supported_issue_types) guarantees only Epic/Feature issues are returned—enforcing the cache scope contract at runtime. The pagination loop correctly handles GitHub's cursor-based pagination.
338-357: LGTM! Fingerprint computation is properly deterministic.The fingerprint includes the right fields (number, title, issue_type, updated_at, labels, parent, children) while deliberately excluding
url(stable) andsummary(body text churn shouldn't trigger updates). Sorting by(issue_type, number)withsort_keys=Truein JSON serialization ensures consistent hashes across runs.
360-461: LGTM! Rendering is deterministic with explicit section ordering.The
_group_issues_by_typefunction now usesSUPPORTED_ISSUE_TYPES_ORDER(a tuple) instead of the frozenset, addressing the earlier iteration order concern. The explicit("Epics", "Epic"), ("Features", "Feature")ordering at line 458 ensures consistent Markdown structure across syncs.
464-488: LGTM! State management handles edge cases gracefully.The
_load_statefunction safely returns an empty mapping for missing or malformed JSON files, preventing crashes on first run or corrupted state. The_write_statefunction creates parent directories as needed and uses formatted JSON for human readability.
510-558: LGTM! Sync logic now uses single API fetch path.The previous review noted the double API call inefficiency. This is now resolved:
fetch_hierarchy_issuesis called once withfingerprint_only=False(line 520-524), and the fingerprint is computed from those detailed results. The fast-exit path (line 527) correctly checks fingerprint match AND output file existence AND not--force.
561-594: LGTM! CLI entry point is clean and follows standard patterns.The argument parser uses sensible defaults from module constants, and
main()handles the sync flow with clear success messaging. Usingsys.stdout.writeprovides explicit control over output buffering. UnhandledRuntimeErrorfrom GraphQL failures will propagate naturally for non-zero exit.
73-74: I need the original review comment to verify and rewrite. Please provide the review comment that needs to be reviewed and rewritten.
| @@ -0,0 +1,49 @@ | |||
| ## MODIFIED Requirements | |||
There was a problem hiding this comment.
Add a top-level heading to clear markdownlint MD041.
Line 1 starts at H2; add a single H1 above it to satisfy first-line-heading.
Suggested markdown fix
+# Backlog Sync Spec Delta
+
## MODIFIED Requirements📝 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.
| ## MODIFIED Requirements | |
| # Backlog Sync Spec Delta | |
| ## MODIFIED Requirements |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@openspec/changes/governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md`
at line 1, The file currently begins with an H2 ("## MODIFIED Requirements")
which violates markdownlint MD041; add a single top-level H1 line above it (for
example "# Backlog Sync Requirements" or another appropriate concise title) so
the first line is an H1 and the existing H2 remains unchanged; update the
document header only (no other content changes) to satisfy MD041.
| @beartype | ||
| def _default_repo_name_from_git(script_dir: Path) -> str | None: | ||
| """Resolve the GitHub repository name from ``origin`` (works in worktrees).""" | ||
| try: | ||
| completed = subprocess.run( | ||
| ["git", "-C", str(script_dir), "config", "--get", "remote.origin.url"], | ||
| check=False, | ||
| capture_output=True, | ||
| text=True, | ||
| ) | ||
| except (FileNotFoundError, OSError): | ||
| return None | ||
| if completed.returncode != 0: | ||
| return None | ||
| return parse_repo_name_from_remote_url(completed.stdout) |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider adding a timeout to the git subprocess call.
While local git config reads are typically fast, the GraphQL subprocess correctly uses a timeout for resilience. For consistency and defensive coding in deterministic tooling, consider adding a short timeout here as well to prevent module import from hanging in edge cases (e.g., stale NFS mounts, broken git configurations).
⏱️ Proposed fix: add timeout
try:
completed = subprocess.run(
["git", "-C", str(script_dir), "config", "--get", "remote.origin.url"],
check=False,
capture_output=True,
text=True,
+ timeout=10,
)
- except (FileNotFoundError, OSError):
+ except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
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.
| @beartype | |
| def _default_repo_name_from_git(script_dir: Path) -> str | None: | |
| """Resolve the GitHub repository name from ``origin`` (works in worktrees).""" | |
| try: | |
| completed = subprocess.run( | |
| ["git", "-C", str(script_dir), "config", "--get", "remote.origin.url"], | |
| check=False, | |
| capture_output=True, | |
| text=True, | |
| ) | |
| except (FileNotFoundError, OSError): | |
| return None | |
| if completed.returncode != 0: | |
| return None | |
| return parse_repo_name_from_remote_url(completed.stdout) | |
| `@beartype` | |
| def _default_repo_name_from_git(script_dir: Path) -> str | None: | |
| """Resolve the GitHub repository name from ``origin`` (works in worktrees).""" | |
| try: | |
| completed = subprocess.run( | |
| ["git", "-C", str(script_dir), "config", "--get", "remote.origin.url"], | |
| check=False, | |
| capture_output=True, | |
| text=True, | |
| timeout=10, | |
| ) | |
| except (FileNotFoundError, OSError, subprocess.TimeoutExpired): | |
| return None | |
| if completed.returncode != 0: | |
| return None | |
| return parse_repo_name_from_remote_url(completed.stdout) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@scripts/sync_github_hierarchy_cache.py` around lines 54 - 68, The
subprocess.run call in _default_repo_name_from_git should include a short
timeout (e.g., timeout=3) to avoid hanging imports; add the timeout argument to
the subprocess.run invocation and catch subprocess.TimeoutExpired (alongside
FileNotFoundError/OSError) to return None, leaving the existing return-path that
calls parse_repo_name_from_remote_url(completed.stdout) unchanged.
1 participant
Summary
Verification
Tracking