nold-ai · djm81 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/README.md b/README.md
@@ -40,10 +40,12 @@ hatch run format
 hatch run type-check
 hatch run lint
 hatch run yaml-lint
+hatch run check-bundle-imports
 hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump
 hatch run contract-test
 hatch run smart-test
 hatch run test
+hatch run specfact code review run --json --out .specfact/code-review.json
 ```
 
 To mirror CI locally with git hooks, enable pre-commit:
@@ -53,7 +55,7 @@ pre-commit install
 pre-commit run --all-files
 ```
 
-**Code review gate (matches specfact-cli core):** runs in **Block 2** after module signatures and Block 1 quality hooks (`pre-commit-quality-checks.sh block2`, which calls `scripts/pre_commit_code_review.py`). Staged `*.py` / `*.pyi` files run `specfact code review run --json --out .specfact/code-review.json`. The helper prints only a short findings summary and copy-paste prompts on stderr (not the nested CLI’s full tool output). Block 1 is split into separate pre-commit hooks so output appears between stages instead of buffering until the end. Requires a local **specfact-cli** install (`hatch run dev-deps` resolves sibling `../specfact-cli` or `SPECFACT_CLI_REPO`).
+**Code review gate (matches specfact-cli core):** runs in **Block 2** after module signatures and Block 1 quality hooks (`pre-commit-quality-checks.sh block2`, which calls `scripts/pre_commit_code_review.py`). Staged paths under `packages/`, `registry/`, `scripts/`, `tools/`, `tests/`, and `openspec/changes/` (excluding `TDD_EVIDENCE.md`) are forwarded to the helper, which runs `specfact code review run --json --out .specfact/code-review.json` with that path list. The helper prints only a short findings summary and copy-paste prompts on stderr (not the nested CLI’s full tool output). Block 1 is split into separate pre-commit hooks so output appears between stages instead of buffering until the end. Requires a local **specfact-cli** install (`hatch run dev-deps` resolves sibling `../specfact-cli` or `SPECFACT_CLI_REPO`).
 
 Scope notes:
 - Pre-commit runs `hatch run lint` in the **Block 1 — lint** hook when any staged path matches `*.py` / `*.pyi`, matching the CI quality job (Ruff alone does not run pylint).

diff --git a/docs/agent-rules/50-quality-gates-and-review.md b/docs/agent-rules/50-quality-gates-and-review.md
@@ -42,16 +42,18 @@ depends_on:
 2. `hatch run type-check`
 3. `hatch run lint`
 4. `hatch run yaml-lint`
-5. `hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump`
-6. `hatch run contract-test`
-7. `hatch run smart-test`
-8. `hatch run test`
+5. `hatch run check-bundle-imports`
+6. `hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump`
+7. `hatch run contract-test`
+8. `hatch run smart-test`
+9. `hatch run test`
+10. `hatch run specfact code review run --json --out .specfact/code-review.json` (full-repo scope when required: add `--scope full`; machine-readable evidence lives at `.specfact/code-review.json` and unresolved findings block merge unless an explicit exception is documented)
 
 ## Pre-commit order
 
 1. Module signature verification (`.pre-commit-config.yaml`, `fail_fast: true` so a failing earlier hook never runs later stages).
 2. **Block 1** — four separate hooks (each flushes pre-commit output when it exits, so you see progress between stages): `pre-commit-quality-checks.sh block1-format` (always), `block1-yaml` when staged `*.yaml` / `*.yml`, `block1-bundle` (always), `block1-lint` when staged `*.py` / `*.pyi`.
-3. **Block 2** — `pre-commit-quality-checks.sh block2` (skipped for “safe-only” staged paths): `hatch run python scripts/pre_commit_code_review.py …` on **staged `*.py` and `*.pyi`** (same glob as `staged_python_files()` in the script—type stubs count), then `contract-test-status` / `hatch run contract-test`.
+3. **Block 2** — `pre-commit-quality-checks.sh block2` (skipped for “safe-only” staged paths): `hatch run python scripts/pre_commit_code_review.py …` on **staged paths under `packages/`, `registry/`, `scripts/`, `tools/`, `tests/`, and `openspec/changes/`** (excluding `TDD_EVIDENCE.md`), then `contract-test-status` / `hatch run contract-test`.
 
 Run the full pipeline manually with `./scripts/pre-commit-quality-checks.sh` or `… all`.
 

diff --git a/docs/agent-rules/60-github-change-governance.md b/docs/agent-rules/60-github-change-governance.md
@@ -59,6 +59,6 @@ Before implementation on a publicly tracked change issue:
 
 If the linked GitHub issue appears to be `in progress`, do not treat that as blocking until you have a current view of GitHub state:
 
-1. If `.specfact/backlog/github_hierarchy_cache.md` is missing, or was last updated more than about five minutes ago, run `python scripts/sync_github_hierarchy_cache.py`.
+1. If `.specfact/backlog/github_hierarchy_cache.md` is missing, or its hierarchy metadata is older than **300 seconds** compared to current UTC time, run `python scripts/sync_github_hierarchy_cache.py`. Treat the cache as fresh when `.specfact/backlog/github_hierarchy_cache_state.json` exists and its `generated_at` ISO-8601 timestamp is within the last 300 seconds; otherwise compare the markdown file’s last modification time (mtime) in UTC against “now” and refresh when the age exceeds 300 seconds.
 2. Re-read the issue state from GitHub or the refreshed cache-backed workflow and confirm the issue is still `in progress`.
 3. Only after that verification, if it remains `in progress`, pause implementation and ask the user to clarify whether the change is already being worked in another session.
diff --git a/docs/agent-rules/70-release-commit-and-docs.md b/docs/agent-rules/70-release-commit-and-docs.md
@@ -42,7 +42,7 @@ depends_on:
 
 ## Registry and publish flow
 
-1. Branch from `origin/dev` into a feature or hotfix branch.
+1. Branch from `origin/dev` into a worktree branch whose name uses one of: `feature/*`, `bugfix/*`, `hotfix/*`, or `chore/*` (expected sibling worktrees live under `../specfact-cli-modules-worktrees/` per session-bootstrap rules).
 2. Bump the bundle version in `packages/<bundle>/module-package.yaml`.
 3. Run `python scripts/publish_module.py --bundle <bundle>` as the publish pre-check.
 4. Publish with the project tooling wrapper when release work is actually intended.

diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md
@@ -32,6 +32,7 @@
 | ✅ speckit-03-change-proposal-bridge | archived 2026-04-05 |
 | ✅ packaging-01-bundle-resource-payloads | archived 2026-04-05 |
 | ✅ module-bundle-deps-auto-install | archived 2026-04-05 |
+| ✅ governance-03-github-hierarchy-cache | archived 2026-04-09 |
 
 ## Pending
 
@@ -75,8 +76,7 @@ These changes are the modules-side runtime companions to split core governance a
 |--------|-------|---------------|----------|------------|
 | governance | 01 | governance-01-evidence-output | [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#247`; validation runtime `#171` |
 | governance | 02 | governance-02-exception-management | [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#248`; policy runtime `#158` |
-| governance | 03 | governance-03-github-hierarchy-cache | [#178](https://github.com/nold-ai/specfact-cli-modules/issues/178) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); paired core `governance-02-github-hierarchy-cache` [specfact-cli#491](https://github.com/nold-ai/specfact-cli/issues/491) |
-| governance | 04 | governance-04-deterministic-agent-governance-loading | [#181](https://github.com/nold-ai/specfact-cli-modules/issues/181) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); paired core [specfact-cli#494](https://github.com/nold-ai/specfact-cli/issues/494); baseline [#178](https://github.com/nold-ai/specfact-cli-modules/issues/178) |
+| governance | 04 | governance-04-deterministic-agent-governance-loading | [#181](https://github.com/nold-ai/specfact-cli-modules/issues/181) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); paired core [specfact-cli#494](https://github.com/nold-ai/specfact-cli/issues/494); baseline [#178](https://github.com/nold-ai/specfact-cli-modules/issues/178) (implements archived `governance-03-github-hierarchy-cache`, paired core [specfact-cli#491](https://github.com/nold-ai/specfact-cli/issues/491)) |
 | validation | 02 | validation-02-full-chain-engine | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#241`; runtime inputs from `#164` and `#165`; policy semantics from `#158` |
 
 ### Documentation restructure

diff --git a/...hive/2026-04-09-governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md b/...hive/2026-04-09-governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md
@@ -1,6 +1,9 @@
+# Archived backlog-sync delta (governance-03)
+
 ## MODIFIED Requirements
 
 ### Requirement: Restore backlog sync command functionality
+
 The system SHALL provide `specfact backlog sync` command for bidirectional backlog synchronization, and related governance workflows SHALL be able to resolve current Epic and Feature planning metadata from the repo-local hierarchy cache before performing manual GitHub lookups.
 
 #### Scenario: Sync from OpenSpec to backlog
@@ -10,25 +13,30 @@ The system SHALL provide `specfact backlog sync` command for bidirectional backl
 - **AND** state mapping preserves status semantics
 
 #### Scenario: Bidirectional sync with cross-adapter
+
 - **WHEN** the user runs sync with cross-adapter configuration
 - **THEN** state is mapped between adapters using canonical status
 - **AND** lossless round-trip preserves content
 
 #### Scenario: Sync with bundle integration
+
 - **WHEN** sync is run within an OpenSpec bundle context
 - **THEN** synced items update bundle state and source tracking
 
 #### Scenario: Ceremony alias works
+
 - **WHEN** the user runs `specfact backlog ceremony sync`
 - **THEN** the command forwards to `specfact backlog sync`
 
 #### Scenario: Cache-first hierarchy lookup for parent issue assignment
+
 - **GIVEN** a contributor needs a parent Feature or Epic while preparing GitHub sync metadata
 - **WHEN** the local hierarchy cache is present and current
 - **THEN** the contributor can resolve the parent relationship from the cache without an additional GitHub lookup
 - **AND** the sync script is rerun only when the cache is stale or missing
 
 ### Requirement: Backlog sync checks for existing external issue mappings before creation
+
 The backlog sync system SHALL check for existing issue mappings from external tools (including spec-kit extensions) before creating new backlog issues, to prevent duplicates.
 
 #### Scenario: Backlog sync with spec-kit extension mappings available

diff --git a/...anges/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md b/...anges/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md
@@ -2,7 +2,7 @@
 
 - **Validated on (local):** 2026-04-12
 - **Strict command:** `openspec validate governance-04-deterministic-agent-governance-loading --strict`
-- **Result:** PASS
+- **Result:** **PENDING / BLOCKED** — `openspec validate … --strict` passed, but the mandatory full-repo SpecFact code review gate is still **FAIL** (`.specfact/code-review.json` reports **934** findings). Do not mark this change fully validated until `hatch run specfact code review run --json --out .specfact/code-review.json --scope full` exits **PASS** or an explicit, approved exception is recorded.
 
 ## Scope summary
 

diff --git a/...ec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md b/...ec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md
@@ -52,3 +52,7 @@
   - `hatch run specfact module install nold-ai/specfact-codebase nold-ai/specfact-code-review --scope project --source bundled --repo . --reinstall` → bundled module artifacts not found for those ids
 - Local worktree note:
   - After relocating the worktree directory, the ignored `.venv/bin/semgrep` and `.venv/bin/pysemgrep` entrypoints had stale absolute shebangs. Those local launchers were repaired in-place so changed-scope code review could run successfully from the corrected worktree path.
+
+## Change validation / release note
+
+- **Full-repo review gate:** Until `hatch run specfact code review run --json --out .specfact/code-review.json --scope full` passes (or an approved exception is documented for task **4.2** with the report artifact attached), promotion trains that require a green full review remain blocked. Triage should start with high-severity items (for example legacy complexity in `packages/specfact-backlog/src/specfact_backlog/backlog/commands.py`).
diff --git a/openspec/changes/governance-04-deterministic-agent-governance-loading/proposal.md b/openspec/changes/governance-04-deterministic-agent-governance-loading/proposal.md
@@ -1,3 +1,5 @@
+# Proposal: Deterministic agent governance loading
+
 ## Why
 
 `AGENTS.md` in **specfact-cli-modules** mixes bootstrap policy, quality gates, and long-form workflow detail in one surface. That raises token cost for every session and makes cross-model behavior less deterministic around worktrees, OpenSpec, cache-first GitHub hierarchy, TDD, and PR completion gates. This change aligns the modules repo with the **deterministic agent-governance** model already shipped in **specfact-cli** ([specfact-cli#494](https://github.com/nold-ai/specfact-cli/issues/494)) so both repositories share the same loading semantics and stop conditions.

diff --git a/...4-deterministic-agent-governance-loading/specs/agent-governance-loading/spec.md b/...4-deterministic-agent-governance-loading/specs/agent-governance-loading/spec.md
@@ -1,3 +1,5 @@
+# Specification: Agent governance loading
+
 ## ADDED Requirements
 
 ### Requirement: Compact AGENTS bootstrap contract

diff --git a/...changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md b/...changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md
@@ -1,9 +1,13 @@
+# Backlog add requirements
+
 ## ADDED Requirements
 
 ### Requirement: Backlog add local artifact helpers SHALL preserve user-managed content
+
 Any `specfact backlog add` helper flow that writes local project artifacts SHALL use the runtime safe-write contract and preserve unrelated user-managed content.
 
 #### Scenario: Existing local config is not silently replaced
+
 - **WHEN** a backlog-add related local helper targets an existing user-project artifact
 - **THEN** the helper SHALL skip, merge, or require explicit replacement according to declared ownership
 - **AND** SHALL NOT silently overwrite the existing file
diff --git a/...hanges/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md b/...hanges/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md
@@ -1,9 +1,13 @@
+# Backlog sync requirements
+
 ## ADDED Requirements
 
 ### Requirement: Backlog sync local export paths SHALL avoid silent overwrite
+
 Any `specfact backlog sync` local export or artifact materialization path SHALL avoid silent overwrites of existing user-project artifacts.
 
 #### Scenario: Existing export target produces conflict or safe merge
+
 - **WHEN** backlog sync would write to a local artifact path that already exists
 - **THEN** the command SHALL use the runtime safe-write contract to merge, skip, or require explicit replacement
 - **AND** SHALL surface the chosen behavior in command output
diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md b/openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md
@@ -20,7 +20,6 @@
 
 - [ ] 4.1 Re-run the targeted runtime tests and any broader affected package coverage, then record passing evidence in `TDD_EVIDENCE.md`.
 - [ ] 4.2 Update affected modules docs to explain preservation guarantees and explicit replacement semantics for adopted commands.
-- [ ] 4.3 Run quality gates: `hatch run format`, `hatch run type-check`, `hatch run lint`, `hatch run yaml-lint`, `hatch run contract-test`, and the relevant `smart-test`/`test` coverage for changed packages.
-- [ ] 4.4 Run module signature verification, bump package versions where required, re-sign changed manifests if needed, and verify registry consistency.
-- [ ] 4.5 Ensure `.specfact/code-review.json` is fresh, remediate all findings, and record the final review command/timestamp in `TDD_EVIDENCE.md` or PR notes.
-- [ ] 4.6 Open the modules PR to `dev`, cross-link the paired core PR, and note any deferred runtime adoption paths as follow-up issues if the initial scope is intentionally limited.
+- [ ] 4.3 Run quality gates in order: `hatch run format` → `hatch run type-check` → `hatch run lint` → `hatch run yaml-lint` → `hatch run check-bundle-imports` → `hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump`, then bump package versions and re-sign changed manifests if verification failed for that reason, then `hatch run contract-test`, then the relevant `hatch run smart-test` / `hatch run test` coverage for changed packages.
+- [ ] 4.4 Run `hatch run specfact code review run --json --out .specfact/code-review.json --scope full`, remediate all findings (or document a rare approved exception), attach or cite the resulting `.specfact/code-review.json`, and record the exact review command and timestamp in `TDD_EVIDENCE.md` or PR notes (last governance action before merge).
+- [ ] 4.5 Open the modules PR to `dev`, cross-link the paired core PR, and note any deferred runtime adoption paths as follow-up issues if the initial scope is intentionally limited.
diff --git a/openspec/specs/backlog-sync/spec.md b/openspec/specs/backlog-sync/spec.md
@@ -1,10 +1,14 @@
 # backlog-sync Specification
 
 ## Purpose
+
 TBD - created by archiving change backlog-02-migrate-core-commands. Update Purpose after archive.
+
 ## Requirements
+
 ### Requirement: Restore backlog sync command functionality
-The system SHALL provide `specfact backlog sync` command for bidirectional backlog synchronization, and related governance workflows SHALL be able to resolve current Epic and Feature planning metadata from the repo-local hierarchy cache before performing manual GitHub lookups.
+
+The system SHALL provide `specfact backlog sync` command for bidirectional backlog synchronization, and related governance workflows SHALL resolve current Epic and Feature planning metadata from **`.specfact/backlog/github_hierarchy_cache.md`**, with deterministic sync state in **`.specfact/backlog/github_hierarchy_cache_state.json`**, before performing manual GitHub lookups. Tools that participate in backlog or OpenSpec workflows MUST read and write those exact paths (or invoke `python scripts/sync_github_hierarchy_cache.py`, which uses them by default) and MUST fall back to live GitHub lookup only when the files are missing, unreadable, or stale per governance rules.
 
 #### Scenario: Sync from OpenSpec to backlog
 
@@ -13,25 +17,30 @@ The system SHALL provide `specfact backlog sync` command for bidirectional backl
 - **AND** state mapping preserves status semantics
 
 #### Scenario: Bidirectional sync with cross-adapter
+
 - **WHEN** the user runs sync with cross-adapter configuration
 - **THEN** state is mapped between adapters using canonical status
 - **AND** lossless round-trip preserves content
 
 #### Scenario: Sync with bundle integration
+
 - **WHEN** sync is run within an OpenSpec bundle context
 - **THEN** synced items update bundle state and source tracking
 
 #### Scenario: Ceremony alias works
+
 - **WHEN** the user runs `specfact backlog ceremony sync`
 - **THEN** the command forwards to `specfact backlog sync`
 
 #### Scenario: Cache-first hierarchy lookup for parent issue assignment
+
 - **GIVEN** a contributor needs a parent Feature or Epic while preparing GitHub sync metadata
-- **WHEN** the local hierarchy cache is present and current
+- **WHEN** `.specfact/backlog/github_hierarchy_cache.md` is present and current (per `.specfact/backlog/github_hierarchy_cache_state.json` / refresh rules)
 - **THEN** the contributor can resolve the parent relationship from the cache without an additional GitHub lookup
-- **AND** the sync script is rerun only when the cache is stale or missing
+- **AND** `specfact backlog sync` (and the alias `specfact backlog ceremony sync`) rely on that cache-first contract; the sync script is rerun only when the cache is stale or missing
 
 ### Requirement: Backlog sync checks for existing external issue mappings before creation
+
 The backlog sync system SHALL check for existing issue mappings from external tools (including spec-kit extensions) before creating new backlog issues, to prevent duplicates.
 
 #### Scenario: Backlog sync with spec-kit extension mappings available
@@ -50,4 +59,3 @@ The backlog sync system SHALL check for existing issue mappings from external to
 - **WHEN** `specfact backlog sync` runs
 - **THEN** the sync creates issues for all tasks as before (no behavior change)
 - **AND** no spec-kit extension detection is attempted
-