bigpowers 2.73.9 → 2.74.1

package/scripts/validate-skill-catalog.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# story: e45s12
+# validate-skill-catalog.sh — code-enforced skill catalog hygiene (Hermes Curator pattern)
+# Exit 0 when catalog passes; 1 on violations. --archive lists zero-usage skills for archiving.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO_ROOT"
+
+SKILLS_ROOT="$REPO_ROOT/skills"
+[[ -d "$SKILLS_ROOT" ]] || SKILLS_ROOT="$REPO_ROOT"
+
+ARCHIVE_MODE=false
+STRICT=false
+TARGET_SKILL=""
+VIOLATIONS=0
+WARNINGS=0
+
+# Documented naming exceptions (craft-skill REFERENCE.md)
+VERB_NOUN_EXCEPTIONS="grill-me grill-with-docs context7-mcp using-bigpowers deploy"
+
+usage() {
+  echo "Usage: bash scripts/validate-skill-catalog.sh [--archive] [--strict] [--skill <name>]"
+  exit 2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --archive) ARCHIVE_MODE=true; shift ;;
+    --strict) STRICT=true; shift ;;
+    --skill) TARGET_SKILL="${2:-}"; shift 2 ;;
+    --skill=*) TARGET_SKILL="${1#*=}"; shift ;;
+    -h|--help) usage ;;
+    *) echo "Unknown flag: $1" >&2; usage ;;
+  esac
+done
+
+report_catalog_violation() { echo "FAIL: $1" >&2; VIOLATIONS=$((VIOLATIONS + 1)); }
+report_catalog_warning() { echo "WARN: $1" >&2; WARNINGS=$((WARNINGS + 1)); }
+
+check_verb_noun() {
+  local name="$1"
+  if echo " $VERB_NOUN_EXCEPTIONS " | grep -q " $name "; then
+    return 0
+  fi
+  if [[ ! "$name" =~ ^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$ ]]; then
+    report_catalog_violation "$name: not verb-noun kebab-case"
+    return 1
+  fi
+  local segments
+  segments=$(echo "$name" | tr '-' '\n' | wc -l | tr -d ' ')
+  if [[ "$segments" -gt 2 ]]; then
+    report_catalog_violation "$name: more than two hyphen segments (verb-noun only)"
+  fi
+}
+
+check_skill() {
+  local skill_md="$1"
+  local name
+  name=$(basename "$(dirname "$skill_md")")
+
+  check_verb_noun "$name" || true
+
+  if ! grep -q 'HARD GATE' "$skill_md" 2>/dev/null; then
+    if $STRICT; then report_catalog_violation "$name: missing HARD GATE block"; else report_catalog_warning "$name: missing HARD GATE block"; fi
+  fi
+
+  local desc
+  desc=$(awk 'BEGIN{f=0} /^---$/{f++; next} f==1{print} f==2{exit}' "$skill_md" \
+    | grep -E '^description:' | head -1 | sed 's/^description: *//; s/^> //' | tr -d '"' || true)
+  if [[ -n "$desc" && ${#desc} -gt 1024 ]]; then
+    report_catalog_violation "$name: description ${#desc} chars (max 1024)"
+  fi
+
+  local lines
+  lines=$(wc -l < "$skill_md" | tr -d ' ')
+  if [[ "$lines" -gt 300 ]]; then
+    report_catalog_warning "$name: SKILL.md $lines lines (target ≤300; split to REFERENCE.md)"
+  fi
+
+  local cmd
+  cmd=$(grep -E '^(> )?→ verify:' "$skill_md" 2>/dev/null | tail -1 | sed 's/^> // ; s/^→ verify: *//' || true)
+  if [[ -z "$cmd" ]]; then
+    if $STRICT; then report_catalog_violation "$name: missing → verify: command"; else report_catalog_warning "$name: missing → verify: command"; fi
+  fi
+}
+
+echo "Validating skill catalog under $SKILLS_ROOT ..."
+if [[ -n "$TARGET_SKILL" ]]; then
+  skill_md="$SKILLS_ROOT/$TARGET_SKILL/SKILL.md"
+  [[ -f "$skill_md" ]] || { echo "FAIL: $skill_md not found" >&2; exit 1; }
+  check_skill "$skill_md"
+else
+  for skill_md in "$SKILLS_ROOT"/*/SKILL.md; do
+    [[ -f "$skill_md" ]] || continue
+    check_skill "$skill_md"
+  done
+fi
+
+if $ARCHIVE_MODE; then
+  STATE="$REPO_ROOT/specs/state.yaml"
+  echo ""
+  echo "=== Archive candidates (zero calls in metrics.skill_timings) ==="
+  if [[ ! -f "$STATE" ]]; then
+    echo "  (no specs/state.yaml — skip usage scan)"
+  else
+    python3 - "$STATE" "$SKILLS_ROOT" <<'PY'
+import sys, glob, os
+from pathlib import Path
+
+state_path, skills_root = sys.argv[1], sys.argv[2]
+text = Path(state_path).read_text(encoding="utf-8")
+timings = set()
+in_timings = False
+for line in text.splitlines():
+    if line.strip() == "skill_timings:":
+        in_timings = True
+        continue
+    if in_timings:
+        if line.startswith("  ") and not line.startswith("    ") and line.rstrip().endswith(":"):
+            timings.add(line.strip().rstrip(":"))
+        elif line.strip() and not line.startswith(" "):
+            in_timings = False
+
+skills = [os.path.basename(os.path.dirname(p)) for p in glob.glob(f"{skills_root}/*/SKILL.md")]
+zero = sorted(s for s in skills if s not in timings)
+if zero:
+    for s in zero:
+        print(f"  ARCHIVE_CANDIDATE: {s} (0 calls — move to specs/epics/archive/ or delete)")
+else:
+    print("  (no zero-usage skills)")
+PY
+  fi
+fi
+
+echo ""
+if [[ "$VIOLATIONS" -gt 0 ]]; then
+  echo "CATALOG INVALID: $VIOLATIONS violation(s), $WARNINGS warning(s)"
+  exit 1
+fi
+if $STRICT && [[ "$WARNINGS" -gt 0 ]]; then
+  echo "CATALOG INVALID (strict): $WARNINGS warning(s)"
+  exit 1
+fi
+echo "CATALOG OK: $WARNINGS warning(s)"
+exit 0

package/scripts/validate-skill-description.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# story: e45s02
+# CSO description discipline — max 1024 chars, no workflow-summary leakage.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SKILLS_ROOT="$REPO_ROOT/skills"
+[[ -d "$SKILLS_ROOT" ]] || SKILLS_ROOT="$REPO_ROOT"
+
+MAX_LEN=1024
+ERRORS=0
+
+audit_skill_description_cso() {
+  local path="$1"
+  local skill desc len
+
+  skill="$(basename "$(dirname "$path")")"
+  desc="$(
+    awk 'BEGIN{n=0} /^---$/{n++; next} n==1{print; next} n>=2{exit}' "$path" \
+      | grep -E '^description:' | head -1 | sed 's/^description:[[:space:]]*//' | sed 's/^"//;s/"$//'
+  )"
+
+  if [[ -z "$desc" ]]; then
+    echo "FAIL: $skill — missing description frontmatter"
+    ERRORS=$((ERRORS + 1))
+    return
+  fi
+
+  len=${#desc}
+  if (( len > MAX_LEN )); then
+    echo "FAIL: $skill — description ${len} chars (max ${MAX_LEN})"
+    ERRORS=$((ERRORS + 1))
+  fi
+
+  # Workflow-summary leakage: numbered steps, phase chains, verify prose in description
+  local leak=0
+  if echo "$desc" | grep -qE '(^|[[:space:]])([0-9]+\.|Step [0-9]+|First,|Then,|Finally,|→ verify:|HARD GATE|Process:|Workflow:)'; then
+    leak=1
+  fi
+  if echo "$desc" | grep -qE '(discover →|scope-work →|plan-work →|develop-tdd →|verify-work →|→ .* → )'; then
+    leak=1
+  fi
+  if (( leak )); then
+    echo "FAIL: $skill — workflow-summary leakage in description (keep triggers only; move steps to body)"
+    ERRORS=$((ERRORS + 1))
+  fi
+
+  if echo "$desc" | grep -qE 'model:[[:space:]]*(haiku|sonnet|opus)'; then
+    echo "FAIL: $skill — model hint belongs in frontmatter, not description"
+    ERRORS=$((ERRORS + 1))
+  fi
+}
+
+if [[ $# -gt 0 ]]; then
+  for f in "$@"; do
+    [[ -f "$f" ]] || { echo "FAIL: not found: $f" >&2; exit 1; }
+    audit_skill_description_cso "$f"
+  done
+else
+  while IFS= read -r f; do
+    audit_skill_description_cso "$f"
+  done < <(find "$SKILLS_ROOT" -maxdepth 2 -name SKILL.md | sort)
+fi
+
+if (( ERRORS > 0 )); then
+  echo "validate-skill-description: $ERRORS issue(s)" >&2
+  exit 1
+fi
+
+echo "validate-skill-description: PASS"

package/skills/audit-code/SKILL.md

@@ -1,4 +1,6 @@
 # story: e51s04
+# story: e45s18
+# story: e45s31
 ---
 name: audit-code
 model: haiku
@@ -14,11 +16,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
 
@@ -110,24 +128,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/skills/build-epic/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: build-epic
-# story: e38s02
+# story: e18s01 e18s02 e18s03 e38s02
 model: sonnet
 effort: standard
 description: Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.
 ---
 
+# story: e20s05
+
 # Build Epic
 
 Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
@@ -90,3 +92,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/skills/change-request/SKILL.md

@@ -5,6 +5,9 @@ effort: standard
 description: Add a new requirement or reorder epics by WSJF against specs/release-plan.yaml and epic capsule directories. Modes Add and Reorder. Use when a new requirement arrives mid-release or the plan needs prioritization.
 ---
 
+# 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/skills/compose-workflow/SKILL.md

@@ -5,6 +5,10 @@ model: sonnet
 effort: standard
 ---
 
+# 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 @@ effort: standard
 > **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/skills/context7-mcp/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: context7-mcp
+# story: e45s19 e45s20
+model: haiku
+effort: light
+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.
+---
+
+# 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/skills/craft-skill/SKILL.md

@@ -1,3 +1,5 @@
+# story: e45s02
+<!-- story: e45s12 -->
 ---
 name: craft-skill
 model: sonnet
@@ -9,6 +11,19 @@ description: Create new bigpowers skills with proper structure, progressive disc
 
 > **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 +55,12 @@ description: Create new bigpowers skills with proper structure, progressive disc
    - 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,10 +74,18 @@ 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/skills/deepen-architecture/SKILL.md

@@ -1,3 +1,5 @@
+# story: e45s31
+<!-- story: e45s14 -->
 ---
 name: deepen-architecture
 model: sonnet
@@ -45,6 +47,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,3 +101,17 @@ 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`
+

package/skills/delegate-task/SKILL.md

@@ -5,6 +5,8 @@ effort: standard
 description: Delegate one complex task to a single subagent, review its work in two stages before merging back. Sequential — one agent at a time, with oversight. Use when a task is complex and requires careful review before the result is accepted. Distinct from dispatch-agents (no parallelism here; reviewer sees full diff before proceeding).
 ---
 
+# 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

package/skills/deploy/SKILL.md

@@ -1,3 +1,4 @@
+<!-- story: e45s15 -->
 ---
 name: deploy
 description: "Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production."
@@ -105,3 +106,11 @@ 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`
+

package/skills/develop-tdd/SKILL.md

@@ -1,4 +1,7 @@
 # story: e51s04
+# story: e45s06
+# story: e45s08
+# story: e45s34
 ---
 name: develop-tdd
 model: sonnet
@@ -52,16 +55,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)
 

package/skills/diagnose-stall/SKILL.md

@@ -0,0 +1,56 @@
+# story: e45s38
+---
+name: diagnose-stall
+model: haiku
+effort: light
+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.
+---
+
+# 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`