bigpowers 2.73.9 → 2.74.1

package/.pi/prompts/seed-conventions.md

@@ -3,6 +3,13 @@ description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project throu
 ---
 
 
+# story: e10s01
+# story: e47s02
+# story: e10s02
+# story: e51s02
+# story: e45s21
+
+
 # Seed Conventions
 > **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
 
@@ -61,7 +68,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
@@ -75,8 +103,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/prompts/session-state.md

@@ -3,6 +3,8 @@ description: Track implementation decisions and progress in specs/state.yaml to
 ---
 
 
+# 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.
 
@@ -17,6 +19,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`:
@@ -63,6 +67,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.
@@ -129,16 +134,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/prompts/slice-tasks.md

@@ -3,6 +3,8 @@ description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD
 ---
 
 
+# story: e45s29
+
 # Slice Tasks
 
 > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
@@ -35,6 +37,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/prompts/smoke-test.md

@@ -68,6 +68,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/prompts/stocktake-skills.md

@@ -3,6 +3,10 @@ description: Sequential subagent batch audit of the bigpowers skill catalog —
 ---
 
 
+# story: e09s01
+<!-- story: e45s12 -->
+
+
 # Stocktake Skills
 > **HARD GATE** — **HARD GATE** — Skill inventory must be current. Missing HARD GATEs, stale descriptions, or broken verify commands are defects, not cosmetic. Fix them in `evolve-skill`.
 
@@ -19,6 +23,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, &lt;300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
@@ -50,7 +55,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/prompts/validate-contracts.md

@@ -113,6 +113,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/prompts/validate-fix.md

@@ -9,6 +9,8 @@ description: Prove a fix works before declaring done — re-run the failing test
 
 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/prompts/verify-work.md

@@ -3,6 +3,17 @@ description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint,
 ---
 
 
+<!-- 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.
@@ -43,12 +54,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)
@@ -91,6 +110,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"
@@ -112,26 +136,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
 
@@ -166,3 +171,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/prompts/wire-ci.md

@@ -106,6 +106,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/prompts/write-document.md

@@ -80,6 +80,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/.pi/skills/audit-code/SKILL.md

@@ -13,11 +13,27 @@ Run this self-review before asking anyone else to look at the code. The goal is
 
 **Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.
 
+## Look-here-first (churn heuristic)
+
+Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size.
+
+```bash
+bash scripts/bp-churn-rank.sh --since 90.days --limit 15
+```
+
+Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope.
+
 ## Modes
 
 - Default: full checklist
 - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
 - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
+- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or:
+
+```bash
+bash scripts/lib/parallel-review-worktrees.sh audit-code
+```
+
 
 ## Checklist
 
@@ -109,24 +125,12 @@ Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs
 If all items pass: suggest running `request-review` for an independent second opinion.
 If any items fail: fix them before proceeding.
 
-### Gate mode output (`--gate`)
-
-In `--gate` mode, print one summary line per checklist section:
-
-```
-PASS Supply Chain & Security
-FAIL Provenance & Metadata (2 items)
-PASS Law of Demeter
-...
-```
-
-Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT-<epic>-<story>.md` as a permanent record.
+In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT-<epic>-<story>.md`.
 
 ## Verify
 
 → verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"`
 
-
 ## Handoff
 
 Gate: READY -> next: commit-message

package/.pi/skills/build-epic/SKILL.md

@@ -5,6 +5,8 @@ model: sonnet
 ---
 
 
+# story: e20s05
+
 # Build Epic
 
 Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
@@ -89,3 +91,6 @@ Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mi
 ## Verify
 
 → verify: `test -f specs/state.yaml && test -f specs/execution-status.yaml && test -f specs/release-plan.yaml && test -d skills/assess-impact && test -d skills/audit-code && test -d skills/security-review && echo "OK: build-epic dependencies present" || echo "FAIL"`
+
+
+<!-- story: e38s02 -->

package/.pi/skills/change-request/SKILL.md

@@ -5,6 +5,9 @@ model: sonnet
 ---
 
 
+# story: e45s29
+# story: e20s01
+
 # Change Request
 
 > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first.
@@ -19,7 +22,7 @@ Intake a new requirement mid-flight without disrupting work in progress.
 
 1. **Capture**: What is the change? What problem does it solve?
 2. **Locate**: Which existing stories in `specs/epics/` does it affect or replace?
-3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`).
+3. **Draft**: Add story + `tasks[]` with Gherkin-style AC in epic YAML (each task has `verify`). Tag requirement deltas: `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` with before/after for non-`ADDED` changes (e45s29).
 4. **Place**: Append story under existing epic capsule, or create `specs/epics/eNN-slug.yaml` and register in `release-plan.yaml` `epics[]`.
 5. **Score**: Compute WSJF; note if it outranks in-progress work.
 

package/.pi/skills/compose-workflow/SKILL.md

@@ -5,6 +5,10 @@ model: sonnet
 ---
 
 
+# story: e09s01
+# story: e45s27
+# story: e21s04
+
 # Compose Workflow
 > **HARD GATE** — **HARD GATE** — Workflows are orchestration, not automation. Do NOT create workflows for tasks that should be single skills. Workflow complexity must be justified.
 
@@ -21,6 +25,19 @@ model: sonnet
 > **Prefer the YAML recipe format** over the legacy `specs/WORKFLOW-<name>.md` markdown format.
 > YAML recipes are command-mappable, machine-readable, and listed in the Standard Recipe Library.
 
+## Terminal-state taxonomy (e45s27)
+
+Every workflow step and `/loop` tick MUST exit with exactly one terminal state:
+
+| State | Meaning | Next action |
+|-------|---------|-------------|
+| `success` | Step verify passed; artifacts written | Advance to next skill in recipe |
+| `no-op` | Nothing to do (already green / already applied) | Skip step; advance |
+| `blocked` | External gate (approval, red CI, missing dep) | `diagnose-stall` or escalate to user |
+| `exhausted` | Max iterations/cycles reached (review cap, dispatch cycles) | Stop; human decision required |
+
+Record terminal state in `specs/state.yaml` `handoff.last_terminal_state` when a recipe step completes. `/loop` ticks that produce no progress for two consecutive wakes → invoke `diagnose-stall`.
+
 ## Standard Recipe Library
 
 Pre-built recipes in `specs/workflows/` map agentic stack commands to skill chains.

package/.pi/skills/context7-mcp/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: context7-mcp
+description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
+model: haiku
+---
+
+
+# Context7 MCP
+
+> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
+>
+> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
+
+## When to Use
+
+- Setup/configuration questions ("How do I configure Next.js middleware?")
+- Code involving libraries ("Write a Prisma query for…")
+- API references ("What are the Supabase auth methods?")
+- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
+
+## Bounded Retry (max 3x)
+
+| Attempt | Action |
+|---------|--------|
+| 1 | `resolve-library-id` → pick best match |
+| 2 | `query-docs` with selected `libraryId` |
+| 3 | Retry `query-docs` once with refined query (narrower scope) |
+
+After 3 failures, stop and print:
+
+```
+CONTEXT7_UNAVAILABLE
+Reason: <quota|rate-limit|no-match|timeout>
+Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
+Do NOT substitute training-data answers without labeling them UNVERIFIED.
+```
+
+## Fetch Cache (ETag-revalidated)
+
+1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
+2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
+3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
+4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
+
+`bts docs <lib>` shares the same cache helper when invoked from this skill.
+
+## Process
+
+1. `resolve-library-id` with `libraryName` + full user `query`.
+2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
+3. `query-docs` with `libraryId` + specific question (one concept per call).
+4. Answer using fetched docs; cite library/version when relevant.
+
+## Verify
+
+→ verify: `test -f scripts/lib/doc-fetch-cache.sh && grep -q CONTEXT7_UNAVAILABLE skills/context7-mcp/SKILL.md && echo OK || echo FAIL`

package/.pi/skills/craft-skill/SKILL.md

@@ -9,6 +9,19 @@ model: sonnet
 
 > **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md.
 
+## CSO Description Discipline (e45s02)
+
+The YAML `description` is the **Catalog Selection Object** — the only field agents see when picking a skill.
+
+| Rule | Limit |
+|------|-------|
+| Max length | 1024 characters |
+| Voice | Third person |
+| Content | Capability + `Use when …` triggers only |
+| Forbidden | Workflow steps, phase chains, numbered lists, `→ verify:`, HARD GATE prose |
+
+Move process detail into the SKILL.md body or REFERENCE.md — never into `description`.
+
 ## Process
 
 1. **Gather requirements** — ask user about:
@@ -40,6 +53,12 @@ model: sonnet
    - Anything missing or unclear?
    - Should any section be more/less detailed?
 
+6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done:
+   - Run `bash scripts/validate-skill-description.sh skills/<name>/SKILL.md` — must exit 0
+   - Run `bash scripts/sync-skills.sh` — must complete without error
+   - Run `bash scripts/run-skill-verify.sh <name>` if the skill defines a verify command
+   - Show terminal output for each — narration without evidence is rejected
+
 ## Naming Rules
 
 Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions.
@@ -53,12 +72,21 @@ If the skill produces written output, it goes in `specs/` at the project root. D
 After drafting, verify:
 
 - [ ] Name is a two-word verb-noun pair (or follows grill-me exception)
+- [ ] Description < 1024 chars, triggers only, no workflow-summary leakage
 - [ ] Description includes triggers ("Use when...")
 - [ ] SKILL.md under 100 lines
 - [ ] No time-sensitive info
 - [ ] Consistent terminology with CONVENTIONS.md
 - [ ] specs/ output documented if applicable
+- [ ] `validate-skill-description.sh` exits 0
 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
+- [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty)
+
+> **HARD GATE** — Do NOT declare the skill done until `bash scripts/validate-skill-catalog.sh --strict --skill <name>` exits 0. Validator enforces verb-noun name, HARD GATE block, description ≤1024 chars, and `→ verify:` command.
+
+## Verify
+
+→ verify: `bash scripts/validate-skill-catalog.sh --strict --skill craft-skill && bash scripts/validate-skill-description.sh skills/craft-skill/SKILL.md && echo OK || echo FAIL`
 
 ---
 

package/.pi/skills/deepen-architecture/SKILL.md

@@ -45,6 +45,12 @@ Read existing documentation first:
 
 If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront.
 
+**Look-here-first (churn heuristic):** Before organic exploration, rank candidate modules by recent commit frequency. High-churn files are architectural friction magnets — start there.
+
+```bash
+bash scripts/bp-churn-rank.sh --since 90.days --limit 20
+```
+
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
 
 - Where does understanding one concept require bouncing between many small modules?
@@ -93,6 +99,20 @@ Side effects happen inline as decisions crystallize:
 - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md).
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
 
+### 5. Import-boundary hygiene (e45s14)
+
+When a deepening move **splits or merges modules**, update `specs/import-boundaries.json` (Playwright `DEPS.list` pattern) — declare which `scripts/lib/*.sh` files may `source` which peers. CI enforces via:
+
+```bash
+bash scripts/check-import-boundaries.sh
+```
+
+Run the check before proposing cross-module `source` edges. Convention docs alone do not authorize new imports; the allowlist must list them.
+
+## Verify
+
+→ verify: `test -f specs/import-boundaries.json && bash scripts/check-import-boundaries.sh && echo OK || echo FAIL`
+
 ---
 
 # Deepening

package/.pi/skills/delegate-task/SKILL.md

@@ -5,6 +5,8 @@ model: sonnet
 ---
 
 
+# story: e45s30
+
 # Delegate Task
 > **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently.
 
@@ -13,6 +15,18 @@ Delegate a single complex task to a subagent with a two-stage review gate before
 
 **Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates.
 
+## Subagent depth tiers (e45s30)
+
+Select brief depth from task `risk:` and skill `effort:` before spawning:
+
+| Tier | When | Brief includes |
+|------|------|----------------|
+| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present |
+| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions |
+| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) |
+
+State `depth: <tier>` in the Agent tool description field.
+
 ## Process
 
 ### 1. Define the task