feat(e45): Quality Core — skill hardening & verification patterns (s01–s41)

.cursor/rules/audit-code.mdc

@@ -12,11 +12,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
 
@@ -108,24 +124,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

.cursor/rules/change-request.mdc

@@ -4,6 +4,8 @@ alwaysApply: false
 ---
 
 
+# story: e45s29
+
 # Change Request
 
 > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first.
@@ -18,7 +20,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.
 

.cursor/rules/compose-workflow.mdc

@@ -4,6 +4,8 @@ alwaysApply: false
 ---
 
 
+# story: e45s27
+
 # 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.
 
@@ -20,6 +22,19 @@ alwaysApply: false
 > **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.

.cursor/rules/context7-mcp.mdc

@@ -0,0 +1,55 @@
+---
+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."
+alwaysApply: false
+---
+
+
+# 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`

.cursor/rules/craft-skill.mdc

@@ -8,6 +8,19 @@ alwaysApply: false
 
 > **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:
@@ -39,6 +52,12 @@ alwaysApply: false
    - 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.
@@ -52,12 +71,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`
 
 ---
 

.cursor/rules/deepen-architecture.mdc

@@ -44,6 +44,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?
@@ -92,6 +98,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

.cursor/rules/delegate-task.mdc

@@ -4,6 +4,8 @@ alwaysApply: false
 ---
 
 
+# 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.
 
@@ -12,6 +14,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

.cursor/rules/deploy.mdc

@@ -104,6 +104,14 @@ For comprehensive health-checking, chain to the `smoke-test` skill:
 bash scripts/run-smoke.sh "$DEPLOY_URL"
 ```
 
+### 7. Three-independent-facts verification (e45s15)
+
+Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts).
+
+## Verify
+
+→ verify: `command -v curl >/dev/null 2>&1 && grep -qi 'three-independent-facts' skills/deploy/SKILL.md && echo OK || echo FAIL`
+
 ---
 
 # Deploy — Reference

.cursor/rules/develop-tdd.mdc

@@ -50,16 +50,27 @@ Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Sel
 Write ONE test that confirms ONE thing about the system:
 
 ```
-RED:    Write test for first behavior → test fails → commit: test(<scope>): ...
-GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...
+RED:    Write test for first behavior → test fails → commit: test(<scope>): ...  (test-only; red in CI)
+GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...   (fix commit; green)
 REFACTOR (optional): clean up → commit: refactor(<scope>): ...
 ```
 
+> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Show `git log -2 --oneline` as evidence before proceeding to the next behavior.
+
+> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass.
+
 ### 3. Incremental Loop
 
-> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Emit a placeholder comment rather than going silent.
+> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly:
+
+```bash
+bash scripts/bp-yaml-snapshot.sh specs/state.yaml   # if state changed this cycle
+git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true
+```
+
+After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED.
 
-For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. Commit after every GREEN phase.
+For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase.
 
 ### 4. Visual Slices (UI alternate workflow)
 

.cursor/rules/diagnose-stall.mdc

@@ -0,0 +1,54 @@
+---
+description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned."
+alwaysApply: false
+---
+
+
+# Diagnose Stall
+
+> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state.
+
+Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode).
+
+## Stall signals
+
+| Signal | Likely cause |
+|--------|----------------|
+| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed |
+| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large |
+| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation |
+| Verify command running >15 min | Missing timeout or waiting on external service |
+| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff |
+
+## Process
+
+1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions.
+2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`.
+3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes.
+4. **Classify stall type:**
+   - **waiting_approval** — tool blocked on user consent
+   - **blocked_dependency** — prior task incomplete or red gate
+   - **agent_exhausted** — max iterations/cycles reached
+   - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed
+   - **external_io** — network, CI, or deploy wait without timeout
+   - **unknown** — escalate with evidence bundle
+5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user).
+6. **Write report** — `specs/verifications/STALL-<timestamp>.md` with classification, evidence, and recommended next skill.
+
+## Integration
+
+| Caller | When to invoke |
+|--------|----------------|
+| `/loop` (Cursor) | After two consecutive ticks with no observable progress |
+| `dispatch-agents` | When a wave exceeds expected duration with zero returns |
+| `execute-plan` | When a step checkpoint is overdue |
+| User | "Why did this stop?" / "Nothing is happening" |
+
+## Verify
+
+→ verify: `test -f specs/state.yaml && echo "OK: diagnose-stall can read session state" || echo "WARN: no state.yaml — diagnostic limited"`
+
+## Handoff
+
+Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml`
+Writes: `specs/verifications/STALL-*.md`