bigpowers 2.73.9 → 2.74.1

package/.pi/skills/verify-work/SKILL.md

@@ -5,6 +5,17 @@ model: haiku
 ---
 
 
+<!-- story: e02s01 e46s03 -->
+<!-- story: e38s05 -->
+<!-- story: e45s05 -->
+<!-- story: e45s09 -->
+<!-- story: e45s13 -->
+<!-- story: e45s40 -->
+<!-- story: e51s03 -->
+<!-- story: e20s04 -->
+<!-- story: e20s06 -->
+
+
 # Verify Work
 
 > **HARD GATE** — No story is "done" until manual UAT for the active story is confirmed with evidence.
@@ -45,12 +56,20 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 2. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch.
 3. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command.
 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3.
+
+> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block.
+
 5. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
 5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
+5a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only.
+
 5b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate.
 6. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 
+7a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`.
+7b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries.
+
 ## Verify sub-operations
 
 ### Cold-Start Smoke (absorbed)
@@ -93,6 +112,11 @@ phases:
   tests:
     passed: true
     coverage: "94.2%"
+  terminal_verdict:
+    command: "npm test"
+    exit_code: 0
+    captured_at: "2026-06-11T14:25:00Z"
+    note: "Single run — do not merge output from other attempts"
   manual:
     steps:
       - step: "Open /login"
@@ -114,26 +138,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co
 
 ## --cli mode
 
-For CLI tools where cold-start smoke (stop server / clear caches) does not apply. Auto-detected when the project has no server process (no `listen()`, no `server.js`, no blocking `main()`); or explicitly activated with `--cli`.
-
-**Auto-detect binary name:**
-```bash
-# Cargo.toml
-BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}')
-# package.json
-BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null)
-# Makefile
-BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}')
-```
-
-**CLI verification checklist (replaces cold-start smoke):**
-
-1. `--help` smoke: `$BINARY --help` → assert output contains "Usage"
-2. `--version` check: `$BINARY --version` → assert version matches manifest (Cargo.toml / package.json)
-3. Happy-path: run documented example command from README.md → assert non-empty output
-4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed
-
-No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged.
+CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode).
 
 ## Verify
 
@@ -168,3 +173,20 @@ sleep 3 && curl -sf http://localhost:<port>/health || echo "BOOT FAIL"
 ```
 
 Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work.
+
+## CLI mode
+
+For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`.
+
+**Auto-detect binary name:**
+```bash
+BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}')  # Cargo
+BINARY=$(node -e "console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')" 2>/dev/null)
+BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}')
+```
+
+**Checklist (replaces cold-start smoke):**
+1. `$BINARY --help` → output contains "Usage"
+2. `$BINARY --version` → matches manifest
+3. README example command → non-empty output
+4. `$BINARY --invalid-flag` → exit ≠ 0 with error message

package/.pi/skills/wire-ci/SKILL.md

@@ -108,6 +108,17 @@ Add the following to the project's documentation or CLAUDE.md after setup:
 
 # Wire Ci — Reference
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–14 | Navigation |
+| 16–38 | Examples |
+| 40–52 | Options |
+| 54–62 | Integration with build-epic |
+| 64–270 | Reference blocks 1–8 |
+
 ## Examples
 
 ### Create CI for a Rust project

package/.pi/skills/write-document/SKILL.md

@@ -82,6 +82,16 @@ Suggest next skill: `audit-code` or `sync-skills.sh`.
 
 Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 5–16 | Navigation |
+| 18–24 | Sections intro |
+| 26–178 | README section templates (1–15) |
+| 180–183 | Verify |
+
 ## Sections
 
 ### 1. Title + Badges

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.74.1](https://github.com/danielvm-git/bigpowers/compare/v2.74.0...v2.74.1) (2026-07-07)
+
+
+### Bug Fixes
+
+* **planning:** resolve yaml status drift for implemented epics ([fd06c68](https://github.com/danielvm-git/bigpowers/commit/fd06c68fc491746b7b7ff283fa561fce72ebb883))
+* **traceability:** backfill story tags for e01-e29, fix YAML/size issues ([cca4942](https://github.com/danielvm-git/bigpowers/commit/cca494288a4c2e90a2dc871d46acefacf50ccf0b))
+
+# [2.74.0](https://github.com/danielvm-git/bigpowers/compare/v2.73.9...v2.74.0) (2026-07-07)
+
+
+### Features
+
+* **e45:** skill hardening & verification patterns (s01–s41) ([9253dc0](https://github.com/danielvm-git/bigpowers/commit/9253dc04d4304256cdc07263a24eaf0ec7d757df))
+
 ## [2.73.9](https://github.com/danielvm-git/bigpowers/compare/v2.73.8...v2.73.9) (2026-07-07)
 
 

package/CLAUDE.md

@@ -1,10 +1,50 @@
 # story: e38s08
 # story: e51s05
+# story: e45s22
+# story: e45s23
 
 # bigpowers — Claude Code
 
 Read CONVENTIONS.md before any GitHub or git operation.
 
+<!-- BEGIN bigpowers:context-routing -->
+## Context Routing
+
+Load subdirectory context **by file glob** — do not read the full doc tree up front.
+
+| Glob / trigger | Load first | Fallback |
+|----------------|------------|----------|
+| `skills/**` | Active skill's `SKILL.md` + sibling `REFERENCE.md` if linked | `SKILL-INDEX.md` |
+| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` |
+| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` |
+| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` if present | `CONVENTIONS.md` |
+| `scripts/**` | `CONVENTIONS.md` § Generated artifact targets | This file § Commands |
+| `website/**` | `website/README.md` if present | Never edit `website/src/content/docs/` (generated) |
+| `docs/**` | Matching doc under `docs/` | `docs/references/` |
+| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` |
+
+Sub-AGENTS.md files (when present in consumer projects) override this table for their directory only.
+<!-- END bigpowers:context-routing -->
+
+<!-- BEGIN bigpowers:learned-preferences -->
+## Learned User Preferences
+
+_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._
+
+- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings).
+- Run Preflight before forward work; never dismiss red gates as pre-existing.
+- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts.
+
+## Workspace Facts
+
+_Stable repo facts — prefer these over re-discovery._
+
+- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`.
+- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`.
+- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI.
+- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md).
+<!-- END bigpowers:learned-preferences -->
+
 ## Project
 
 bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs).
@@ -62,6 +102,18 @@ Collection of verb-noun skills under `skills/`, each with a SKILL.md source file
 
 ## Token Management
 
+**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (alongside `hooks/pre-tool-use.sh` for git safety). Thresholds: Read >100KB, Grep >200 matches without `head_limit`, Bash commands likely to exceed 500 output lines without `rtk`/`sqz compress`. Install snippet:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Read|Grep|Bash", "hooks": [{ "type": "command", "command": "bash scripts/hooks/token-mgmt-pre-tool-use.sh" }] }
+    ]
+  }
+}
+```
+
 Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`):
 
 - **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments.
@@ -113,9 +165,15 @@ Before any task, run this sequence — not optional:
 - Search with `bts find` before opening files to locate a symbol or pattern.
 - Pipe anything > 200 lines through `bts compress` before adding to context.
 - Run `bts map` when asked for a repo overview.
-- Use `bts docs <lib>` before answering questions about library APIs.
+- Use `bts docs <lib>` before answering questions about library APIs. Doc fetches use `scripts/lib/doc-fetch-cache.sh` (ETag-revalidated, 300s TTL — see `context7-mcp` skill, e45s20).
 - If a tool is missing, say so and run `bts doctor` — do not silently substitute.
 
+<!-- BEGIN rtk-pretooluse-hook (e45s16 — mechanical PreToolUse backstop; remove block to disable) -->
+
+**RTK hook (installed):** `scripts/hooks/rtk-rewrite.sh` is symlinked into `~/.claude/hooks/` by `bash scripts/install.sh` and registered as a Bash `PreToolUse` hook. It delegates to `rtk hook claude` — prose rules below are a fallback only when the hook is absent.
+
+<!-- END rtk-pretooluse-hook -->
+
 <!-- BEGIN sqz-claude-guidance (auto-installed by sqz init; remove this block to disable) -->
 
 ## sqz — Context Compression (READ FIRST)

package/CONVENTIONS.md

@@ -1,7 +1,15 @@
+# story: e05s01 e46s04
+# story: e06s02
+# story: e07s01
 # story: e30s02
 # story: e30s03
 # story: e38s08
+# story: e45s10
 # story: e51s01
+# story: e45s25
+# story: e45s36
+# story: e27s01
+# story: e29s03
 
 # Conventions
 
@@ -86,6 +94,43 @@ Discovered fixes ship in the **same PR** as the original work but in **separate
 
 **Hard block:** Red Preflight or red CI blocks kickoff-branch, develop-tdd, and verify-work forward progress until fix-or-log produces green.
 
+## Risk Tiers (Effective Rule Matrix)
+
+Human-readable source of truth for verification depth. Machine-readable compile:
+
+```bash
+bash scripts/compile-rule-matrix.sh   # → specs/rule-matrix.json
+```
+
+Diff `specs/rule-matrix.json` across git tags to audit rule drift. Schema version in JSON `matrix_version` field.
+
+### P0 — Critical (never violate)
+
+- **[always-green]**: Preflight and CI must be green before forward work. (`verify-work`, `kickoff-branch`, `develop-tdd`)
+- **[no-direct-coding]**: Route feature work through bigpowers skills — no ad-hoc implementation without a plan in `specs/`. (`plan-work`, `orchestrate-project`)
+- **[traceability]**: Every story has ≥1 `story: eNNsNN` tag in implementing code or tests. (`trace-stories.sh --strict`)
+- **[no-generated-edits]**: Never edit `.cursor/rules/`, `.gemini/`, or `website/src/content/docs/` directly. (`sync-skills.sh`)
+
+### P1 — High (fix before merge)
+
+- **[conventional-commits]**: All commits follow Conventional Commits; semantic-release owns version bumps. (`commit-message`, `release-branch`)
+- **[verify-per-story]**: Every story/task has runnable `verify:` commands; `verify-work` confirms before done. (`plan-work`, `verify-work`)
+- **[test-on-change]**: New functions and bug fixes include tests; regressions get regression tests. (`develop-tdd`, `validate-fix`)
+- **[branch-protection]**: No direct work on `main`/`master`; feature branches via `kickoff-branch`. (`guard-git`)
+
+### P2 — Medium (address in same epic or next)
+
+- **[plan-tests-waiver]**: P2/P3-dominant epics may set `test_plan: waived` in `state.yaml`. (`plan-tests`)
+- **[file-size-cap]**: Source files under 300 lines unless listed in § File-Size Exceptions. (`audit-code`)
+- **[handoff-signaling]**: Critical-path skills write `handoff.next_skill` to `state.yaml`. (`session-state`)
+- **[delta-requirements]**: Behavior changes require `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` tags in requirement specs. (`plan-work`, `change-request`)
+
+### P3 — Low (best effort)
+
+- **[boy-scout]**: Leave touched files at least as clean as found. (`audit-code`)
+- **[terse-when-heavy]**: Switch to `terse-mode` when context exceeds ~20 turns. (`terse-mode`)
+- **[skill-naming]**: Verb-noun kebab-case under `skills/`; documented exceptions only. (`craft-skill`)
+
 ### Banned dismissive phrases
 
 Agents MUST NOT use these phrases (or close paraphrases) to ignore reproducible failures:
@@ -178,6 +223,30 @@ When planning closes, copy to `specs/product/snapshots/release-<version>/` (`rel
 
 Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`.
 
+### Documentation Responsibilities (e45s36)
+
+Each specs/ artifact owns specific facts. Update the owning file when the fact changes — do not duplicate across files.
+
+| File / directory | Owns | Update when |
+|------------------|------|-------------|
+| `specs/state.yaml` | Active session, handoff, story timing, workflow mode | Every skill handoff; branch switch; story start/end |
+| `specs/release-plan.yaml` | Epic ordering, WSJF, BCP baselines, release codename | New epic scoped; WSJF re-prioritized; BCP re-estimated |
+| `specs/execution-status.yaml` | Story/epic done/todo status (sole SoT) | Story completes; gate-trace runs; manual status change |
+| `specs/product/SCOPE_LATEST.yaml` | In/out of scope, initiative boundaries | scope-work; change-request Add mode |
+| `specs/product/VISION_LATEST.yaml` | North star, strategic intent | Major product pivot; scope-work |
+| `specs/product/GLOSSARY_LATEST.yaml` | Canonical domain terms | define-language; model-domain term crystallizes |
+| `specs/epics/eNN-*/epic.yaml` | Epic manifest, story list, BCPs | slice-tasks; plan-work adds stories |
+| `specs/epics/eNN-*/eNNsYY-*.md` | Story requirements (countable-story-format) | plan-work; section approval state changes |
+| `specs/epics/eNN-*/eNNsYY-tasks.yaml` | Runnable implementation tasks + verify | plan-work; develop-tdd task completion |
+| `specs/tech-architecture/tech-stack.md` | Stack, modules, gray areas | map-codebase; deepen-architecture; model-domain |
+| `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` | P0/P1 test scenarios per epic | plan-tests |
+| `specs/adr/ADR-*.md` | Architectural decisions | model-domain; deepen-architecture ADR offer accepted |
+| `specs/bugs/BUG-*.md` | Bug RCA + fix plan | investigate-bug |
+| `specs/bugs/registry.yaml` | Bug index (generated) | inspect-quality; sync-bugs-registry.sh |
+| `specs/verifications/*` | Verify evidence, audit reports, eval reports | verify-work; audit-code; run-evals |
+| `specs/security/REVIEW.md` | Latest security scan findings | security-review |
+| `specs/metrics/cycle-times.yaml` | Delivery velocity ledger | release-branch lands story |
+
 ### Generated artifact targets
 
 Skill content is edited in `skills/*/SKILL.md` and auto-propagated to these targets by `bash scripts/sync-skills.sh`:
@@ -300,3 +369,15 @@ BUG-2026-07-06-gate-trace-matrix-oversized. Prior exception rows for trace-matri
 and trace-stories.py are removed — both are now under the 300-line cap.
 
 Any new exception requires an entry in this table with rationale and a review date.
+
+## docs/references SSOT Sync (e45s10)
+
+Agent-guidance files under `docs/references/` are **distilled from upstream sources**, not hand-edited ad hoc. Canonical inputs live in `CLAUDE.md`, `docs/PRINCIPLES.md`, and `skills/*/SKILL.md`.
+
+| Action | Command |
+|--------|---------|
+| Regenerate locally | `bash scripts/sync-references.sh` |
+| Manifest | `scripts/references-manifest.yaml` |
+| Scheduled CI | `.github/workflows/sync-references.yml` (weekly) |
+
+After changing SKILL.md `model:` frontmatter or token-management prose in CLAUDE.md, run `sync-references.sh` to refresh reference docs and `.sync-stamp`.

package/README.md

@@ -2,7 +2,7 @@
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![npm version](https://img.shields.io/npm/v/bigpowers.svg)
-![Skills](https://img.shields.io/badge/skills-75-brightgreen.svg)
+![Skills](https://img.shields.io/badge/skills-77-brightgreen.svg)
 
 **Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.**
 

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Skills:** 75
+**Skills:** 77
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.9",
+  "version": "2.74.1",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/bp-churn-rank.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# story: e45s31
+# Rank files by git churn for review prioritization (aidd-churn pattern).
+# Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit N] [path...]
+set -euo pipefail
+
+SINCE="90.days"
+LIMIT=20
+PATHS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since)
+      SINCE="${2:?--since requires a value}"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="${2:?--limit requires a number}"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit 20] [path...]"
+      exit 0
+      ;;
+    *)
+      PATHS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo "FAIL: not a git repository" >&2
+  exit 1
+fi
+
+PATHSPEC=""
+if [[ ${#PATHS[@]} -gt 0 ]]; then
+  PATHSPEC="-- ${PATHS[*]}"
+fi
+
+# shellcheck disable=SC2086
+git log --since="$SINCE" --name-only --pretty=format: $PATHSPEC \
+  | grep -v '^$' \
+  | sort \
+  | uniq -c \
+  | sort -rn \
+  | head -n "$LIMIT" \
+  | awk '{printf "%4d  %s\n", $1, $2}'

package/scripts/bp-read-agents.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e21s03
 # bp-read-agents.sh — Extract preflight/test/build/lint/deploy commands from AGENTS.md.
 # Outputs env-var exports: BP_PREFLIGHT, BP_TEST, BP_BUILD, BP_LINT, BP_DEPLOY
 # Usage: eval "$(bash scripts/bp-read-agents.sh)"  # imports env vars

package/scripts/check-import-boundaries.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# story: e45s14
+# check-import-boundaries.sh — enforce specs/import-boundaries.json in CI
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BOUNDARIES="$REPO_ROOT/specs/import-boundaries.json"
+
+if [[ ! -f "$BOUNDARIES" ]]; then
+  echo "FAIL: missing $BOUNDARIES"
+  exit 1
+fi
+
+python3 - "$REPO_ROOT" "$BOUNDARIES" <<'PY'
+import json, re, sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+rules_path = Path(sys.argv[2])
+rules = json.loads(rules_path.read_text(encoding="utf-8"))
+
+def glob_match(pattern: str, path: str) -> bool:
+    import fnmatch
+    return fnmatch.fnmatch(path, pattern)
+
+violations = []
+
+for boundary in rules.get("boundaries", []):
+    from_pat = boundary["from"]
+    allow = boundary.get("allow", [])
+    deny = boundary.get("deny", [])
+
+    for sh in root.glob("scripts/**/*.sh"):
+        rel = sh.relative_to(root).as_posix()
+        if not glob_match(from_pat, rel):
+            continue
+        text = sh.read_text(encoding="utf-8", errors="replace")
+        for line in text.splitlines():
+            m = re.match(r'^\s*(?:source|\.)\s+["\']?([^"\']+)["\']?', line)
+            if not m:
+                continue
+            target = m.group(1)
+            if target.startswith("$"):
+                continue
+            if not target.startswith("scripts/") and not target.startswith("guard-git/"):
+                if any(glob_match(d, target) for d in deny):
+                    violations.append(f"{rel}: forbidden source {target}")
+                continue
+            rel_target = target
+            if not (Path(root / rel_target).exists() or glob_match(rel_target, rel_target)):
+                pass
+            allowed = any(glob_match(a, rel_target) for a in allow)
+            if not allowed:
+                violations.append(f"{rel}: source {rel_target} not in allowlist for {from_pat}")
+
+if violations:
+    print("IMPORT BOUNDARY FAIL:")
+    for v in violations:
+        print(f"  {v}")
+    sys.exit(1)
+
+print(f"IMPORT BOUNDARIES OK ({len(rules.get('boundaries', []))} rules)")
+PY

package/scripts/compile-rule-matrix.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# story: e45s25
+# Compile CONVENTIONS.md risk tiers → versioned specs/rule-matrix.json
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONVENTIONS="$REPO_ROOT/CONVENTIONS.md"
+OUTPUT="$REPO_ROOT/specs/rule-matrix.json"
+MATRIX_VERSION="1.0.0"
+
+show_help() {
+  cat <<EOF
+Usage: $(basename "$0") [OPTION]
+
+Compile CONVENTIONS.md § Risk Tiers into specs/rule-matrix.json.
+P0/P1/P2/P3 entries are diffable across git tags.
+
+Options:
+  --stdout   Print JSON to stdout instead of writing file
+  --help     Show this help and exit
+EOF
+}
+
+STDOUT_ONLY=0
+if [ "$#" -eq 1 ]; then
+  case "$1" in
+    --help) show_help; exit 0 ;;
+    --stdout) STDOUT_ONLY=1 ;;
+    *) echo "[ERROR] Unknown option: $1" >&2; exit 1 ;;
+  esac
+fi
+
+if [ ! -f "$CONVENTIONS" ]; then
+  echo "[ERROR] CONVENTIONS.md not found at $CONVENTIONS" >&2
+  exit 1
+fi
+
+$PYTHON - "$CONVENTIONS" "$OUTPUT" "$MATRIX_VERSION" "$STDOUT_ONLY" <<'PY'
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+conventions_path, output_path, matrix_version, stdout_only = sys.argv[1:5]
+stdout_only = stdout_only == "1"
+
+with open(conventions_path, encoding="utf-8") as f:
+    content = f.read()
+
+source_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
+
+# Extract Risk Tiers section
+m = re.search(
+    r"^## Risk Tiers \(Effective Rule Matrix\)\s*\n(.*?)(?=^## |\Z)",
+    content,
+    re.MULTILINE | re.DOTALL,
+)
+if not m:
+    print("[ERROR] CONVENTIONS.md missing '## Risk Tiers (Effective Rule Matrix)'", file=sys.stderr)
+    sys.exit(1)
+
+section = m.group(1)
+tier_re = re.compile(r"^### (P[0-3]) —[^\n]*\n(.*?)(?=^### |\Z)", re.MULTILINE | re.DOTALL)
+rule_re = re.compile(
+    r"^- \*\*\[([^\]]+)\]\*\*:\s*(.+?)\.\s*\(([^)]+)\)\s*$",
+    re.MULTILINE,
+)
+
+tiers: dict[str, list[dict]] = {"P0": [], "P1": [], "P2": [], "P3": []}
+
+for tier_match in tier_re.finditer(section):
+    tier = tier_match.group(1)
+    body = tier_match.group(2)
+    for rule_match in rule_re.finditer(body):
+        rule_id, text, enforce_raw = rule_match.groups()
+        enforce = [s.strip().strip("`") for s in enforce_raw.split(",")]
+        tiers[tier].append(
+            {
+                "id": rule_id,
+                "text": text.strip(),
+                "enforce": enforce,
+            }
+        )
+
+for tier in tiers:
+    if not tiers[tier]:
+        print(f"[ERROR] No rules parsed for tier {tier}", file=sys.stderr)
+        sys.exit(1)
+
+doc = {
+    "matrix_version": matrix_version,
+    "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "source": "CONVENTIONS.md",
+    "source_section": "Risk Tiers (Effective Rule Matrix)",
+    "source_hash": source_hash,
+    "tiers": tiers,
+}
+
+payload = json.dumps(doc, indent=2, sort_keys=True) + "\n"
+
+if stdout_only:
+    print(payload, end="")
+else:
+    import os
+
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as out:
+        out.write(payload)
+    total = sum(len(v) for v in tiers.values())
+    print(f"OK: wrote {output_path} ({total} rules, matrix_version={matrix_version})")
+PY

package/scripts/hooks/rtk-rewrite.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# story: e45s16
+# rtk-rewrite.sh — PreToolUse hook delegating to rtk's native Bash rewriter.
+set -euo pipefail
+
+if command -v rtk >/dev/null 2>&1; then
+  exec rtk hook claude
+fi
+
+# rtk missing — pass through unchanged (agent should run `bts doctor` / install rtk)
+exit 0