bigpowers 2.73.8 → 2.74.0

package/.pi/skills/security-review/SKILL.md

@@ -5,12 +5,24 @@ model: sonnet
 ---
 
 
+# story: e45s26
+
 # Security Review
 
 > **HARD GATE** — Requires git context (branch with merge-base or diff). Never
 > writes files outside `specs/security/`. Findings below confidence 8/10 are
 > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"`
 
+## Parallel worktree mode (e45s18)
+
+When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index:
+
+```bash
+bash scripts/lib/parallel-review-worktrees.sh security-review
+```
+
+Each check gets a detached worktree at `.bigpowers/worktrees/review-<name>/`; reports still write only under `specs/security/`.
+
 ## 5-phase scan
 
 | # | Phase | What |
@@ -25,6 +37,37 @@ model: sonnet
 
 Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi
 
+## CWE mapping mandate (e45s26)
+
+Every **new detection rule** added to this skill MUST:
+
+1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79).
+2. Ship **two fixture pairs** under `skills/security-review/fixtures/`:
+   - **Positive** — minimal code the rule MUST flag (vulnerable pattern present).
+   - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard).
+
+| Rule | CWE | Positive fixture | Negative fixture |
+|------|-----|------------------|------------------|
+| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` |
+| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` |
+
+Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes.
+
+## SQL-safety doctrine (e45s41 — proven authorship)
+
+Formal rule for SQL injection classification:
+
+| SQL source | Attacker-reachable input? | Verdict |
+|------------|---------------------------|---------|
+| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship |
+| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** |
+| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi |
+| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized |
+| Stored procedure call with bound args | Args from trusted constants only | **Safe** |
+| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** |
+
+**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not.
+
 ## BCP Plus Integration
 
 This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.
@@ -176,14 +219,15 @@ Automatically exclude findings matching these patterns:
 | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic |
 | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners |
 | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees |
-| 11 | **Unit test files only** | Not production risk |
-| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln |
-| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable |
-| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability |
-| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln |
-| 16 | **Regex DOS** | Excluded alongside general DOS |
-| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities |
-| 18 | **Lack of audit logs** | Not a vulnerability |
+| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) |
+| 12 | **Unit test files only** | Not production risk |
+| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln |
+| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable |
+| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability |
+| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln |
+| 17 | **Regex DOS** | Excluded alongside general DOS |
+| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities |
+| 19 | **Lack of audit logs** | Not a vulnerability |
 
 ## Precedent Rules
 
@@ -235,6 +279,8 @@ Each category: vulnerable pattern → safe pattern → code example.
 | Aspect | Detail |
 |--------|--------|
 | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` |
+| **CWE** | CWE-89 (SQL Injection) |
+| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) |
 | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` |
 | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` |
 | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). |
@@ -244,6 +290,8 @@ Each category: vulnerable pattern → safe pattern → code example.
 | Aspect | Detail |
 |--------|--------|
 | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` |
+| **CWE** | CWE-79 (Cross-site Scripting) |
+| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) |
 | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping |
 | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) |
 | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). |

package/.pi/skills/seed-conventions/SKILL.md

@@ -63,7 +63,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`).
 
+### Self-installing fenced markers (e45s21)
 
+Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered:
+
+```markdown
+<!-- BEGIN bigpowers:section-id -->
+…agent-managed content only…
+<!-- END bigpowers:section-id -->
+```
+
+**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file.
+
+**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
+
+| Marker ID | Owner skill | Purpose |
+|-----------|-------------|---------|
+| `project` | seed-conventions | Project, Commands, Architecture |
+| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table |
+| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts |
+| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills |
+
+Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred.
 
 - [ ] CLAUDE.md exists and is populated
 - [ ] CONVENTIONS.md exists and includes specs/ output convention
@@ -77,8 +98,48 @@ When generating `CLAUDE.md`, if the user did not name a Preflight command, chain
 ---
 
 # story: e51s02 e37s01 e37s03 e37s14
+# story: e45s21
 # Seed Conventions — Reference Templates
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1–4 | Title + story tags |
+| 6–22 | Navigation (this table) |
+| 24–35 | AGENTS.md spine |
+| 37–76 | Agent config template |
+| 78–85 | opencode.json template |
+| 87–96 | Aider bridge |
+| 98–108 | Codex CLI wiring |
+| 110–118 | CONVENTIONS.md |
+| 120–122 | Stack profile fragments |
+| 124–153 | Local tool wiring |
+
+## Fenced markers (e45s21)
+
+Self-installing blocks prevent skills from overwriting user-authored prose. Pattern:
+
+```markdown
+<!-- BEGIN bigpowers:section-id -->
+…managed content…
+<!-- END bigpowers:section-id -->
+```
+
+**Merge algorithm:**
+
+1. If `BEGIN bigpowers:<id>` exists → replace inner content only.
+2. If missing → append new fenced block at EOF.
+3. Never delete content outside fences.
+
+Seed these marker IDs in generated `AGENTS.md`:
+
+| ID | Initial content |
+|----|-----------------|
+| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules |
+| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) |
+| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists |
+
 ## AGENTS.md spine (Reach Template — e37s01)
 
 Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template).

package/.pi/skills/session-state/SKILL.md

@@ -5,6 +5,8 @@ model: haiku
 ---
 
 
+# story: e45s23
+
 # Session State
 > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct.
 
@@ -19,6 +21,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml
 
 Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
 
+When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21.
+
 ## Handoff block (cold start)
 
 When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
@@ -65,6 +69,7 @@ When starting a new session or after a significant context flush:
 Whenever a significant decision is made or a milestone is reached:
 
 - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23).
 - [ ] Update `handoff.open_decisions` with rationale.
 - [ ] Update `epic_cycle` when advancing `ship-epic` steps.
 - [ ] Record open questions under `handoff.open_decisions` or an ADR.
@@ -131,16 +136,6 @@ handoff:
   next_skill: survey-context
 ```
 
-## Tracking commit ratio
-
-After `release-branch` lands, compute fix-to-feature ratio via:
-```bash
-FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ')
-FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ')
-FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT)))
-```
-Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`.
-
 ## Anti-Patterns
 
 - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.

package/.pi/skills/slice-tasks/SKILL.md

@@ -5,6 +5,8 @@ model: sonnet
 ---
 
 
+# story: e45s29
+
 # Slice Tasks
 
 > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
@@ -37,6 +39,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli
    - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`)
    - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md
    - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs
+   - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text.
 
 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest.
 

package/.pi/skills/smoke-test/SKILL.md

@@ -70,6 +70,17 @@ DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
 
 # Smoke Test — Reference
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–12 | Navigation |
+| 14–31 | Runner script |
+| 33–42 | Configuration reference |
+| 44–53 | Verification |
+| 55–160 | Reference blocks 1–5 |
+
 ## Runner script
 
 A ready-to-use runner is provided for standalone operation:

package/.pi/skills/stocktake-skills/SKILL.md

@@ -21,6 +21,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 
 ## Process
 
+0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
 2. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
@@ -52,7 +53,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls withi
 
 ## Verify
 
-→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING`
+→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING`
 
 See [REFERENCE.md](REFERENCE.md) for checklist.
 

package/.pi/skills/validate-contracts/SKILL.md

@@ -115,6 +115,18 @@ bash scripts/validate-contracts.sh <contract-file>
 
 # Validate Contracts — Reference
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–14 | Navigation |
+| 16–24 | Integration |
+| 26–35 | Configuration |
+| 37–46 | Verification |
+| 48–170 | Reference blocks + Examples 1–6 |
+| 172–190 | Integration (duplicate) + Configuration + Verification |
+
 ## Integration
 
 - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.

package/.pi/skills/validate-fix/SKILL.md

@@ -11,6 +11,8 @@ model: haiku
 
 Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
 
+> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(<scope>): …`), second commit applies the fix (`fix(<scope>): …`). Do not squash RED and GREEN before review.
+
 ## Checklist
 
 ### 1. Re-run the originally failing test

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

@@ -45,12 +45,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 +101,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 +127,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 +162,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,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **gate-trace:** split trace-matrix.py under 300-line cap ([ece8389](https://github.com/danielvm-git/bigpowers/commit/ece8389c815614d116d91b57dda9c67f6133caaf))
+
 ## [2.73.8](https://github.com/danielvm-git/bigpowers/compare/v2.73.7...v2.73.8) (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,10 @@
 # story: e30s02
 # story: e30s03
 # story: e38s08
+# story: e45s10
 # story: e51s01
+# story: e45s25
+# story: e45s36
 
 # Conventions
 
@@ -86,6 +89,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 +218,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`:
@@ -291,13 +355,24 @@ window. The following files are documented exceptions:
 
 | File | Lines | Rationale | Review date |
 |------|-------|-----------|-------------|
-| `scripts/lib/trace-matrix.py` | 523 | Traceability matrix engine: tag scanning, oracle-confidence scoring, and JSON/markdown emission share tightly-coupled dataclasses and a single pass over the story index. Splitting would fragment the matrix model across modules. Split candidate for a future plan-refactor (BUG-2026-07-04-filesize-gate-python-blindspot); documented meanwhile. Also exceeds the 500-line cap. | 2026-10-01 |
-| `scripts/lib/trace-stories.py` | 301 | Story-tag discovery + file-to-story mapping; the phases share regex state and a common file walk. One line over cap; monitor for split alongside trace-matrix.py. | 2026-10-01 |
 | `scripts/audit-compliance.sh` | 300 | Gherkin harness with embedded judge logic and waiver subsystem; splitting the judge loop from the reporting layer would require fragile state-passing. At the 300-line cap; monitor. | 2026-10-01 |
 
 **Note:** `scripts/trace-stories.sh` was refactored from a 613-line monolith into a
-69-line orchestrator delegating to the `scripts/lib/*.py` engine above — it is no
-longer an exception. The prior exception row (and its waiver) referenced a file
-that no longer exists; see BUG-2026-07-04-filesize-gate-python-blindspot.
+69-line orchestrator delegating to `scripts/lib/trace-stories.py`. `scripts/lib/trace-matrix.py`
+was split into `simple_yaml.py` + `trace_renderer.py` (252 lines); see
+BUG-2026-07-06-gate-trace-matrix-oversized. Prior exception rows for trace-matrix.py
+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`.