bigpowers 2.73.8 → 2.74.0

package/scripts/lib/trace_renderer.py

@@ -0,0 +1,147 @@
+# story: e38s01
+# trace_renderer.py — Output renderer for traceability matrix data.
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def emit_matrix_json(matrix_json_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list) -> dict:
+    matrix = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "matrix_version": "1.0",
+        "stories": matrix_stories,
+        "summary": {
+            "total_stories": len(stories),
+            "tagged_stories": len(tagged_sids & set(stories.keys())),
+            "dark_stories": dark_stories,
+            "dark_count": len(dark_stories),
+            "orphan_tags": orphan_tags,
+            "orphan_count": len(orphan_tags),
+            "stale_tags": stale_tags,
+            "stale_count": len(stale_tags),
+            "oracle_stats": {
+                "high": sum(1 for s in matrix_stories for l in s["links"] if l["confidence"] == "high"),
+                "medium": sum(1 for s in matrix_stories for l in s["links"] if l["confidence"] == "medium"),
+                "low": sum(1 for s in matrix_stories for l in s["links"] if l["confidence"] == "low")
+            }
+        }
+    }
+    matrix_json_path.parent.mkdir(parents=True, exist_ok=True)
+    matrix_json_path.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
+    return matrix
+
+def emit_trace_md(trace_md_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list, matrix: dict, dev_status: dict) -> None:
+    lines = []
+    lines.append("# Traceability Matrix")
+    lines.append("")
+    lines.append(f"**Generated:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}")
+    lines.append(f"**Total stories:** {len(stories)}")
+    lines.append(f"**Tagged stories:** {len(tagged_sids & set(stories.keys()))}")
+    lines.append(f"**Dark stories:** {len(dark_stories)}")
+    lines.append(f"**Orphan tags:** {len(orphan_tags)}")
+    lines.append(f"**Stale tags:** {len(stale_tags)}")
+    lines.append("")
+    lines.append("## Oracle Stats")
+    lines.append("")
+    lines.append(f"- **High** (explicit tag): {matrix['summary']['oracle_stats']['high']}")
+    lines.append(f"- **Medium** (file heuristic): {matrix['summary']['oracle_stats']['medium']}")
+    lines.append(f"- **Low** (task reference): {matrix['summary']['oracle_stats']['low']}")
+    lines.append("")
+    
+    # Story coverage table
+    lines.append("## Story Coverage")
+    lines.append("")
+    lines.append("| Story | Title | Epic | BCP | WSJF | Status | Links |")
+    lines.append("|-------|-------|------|-----|------|--------|-------|")
+    for s in matrix_stories:
+        lines.append(f"| {s['id']} | {s['title'][:60]} | {s['epic_id']} | {s['bcp']} | {s['wsjf']} | {s['status']} | {s['link_count']} |")
+    lines.append("")
+    
+    # Findings
+    if dark_stories:
+        lines.append("## Dark Stories (no code links)")
+        lines.append("")
+        for ds in dark_stories:
+            sinfo = stories.get(ds, {})
+            lines.append(f"- **{ds}**: {sinfo.get('title', 'Unknown')} (status: {dev_status.get(ds, '?')})")
+        lines.append("")
+    
+    if orphan_tags:
+        lines.append("## Orphan Tags (tag in code, no matching story)")
+        lines.append("")
+        for ot in orphan_tags:
+            lines.append(f"- `{ot}`")
+        lines.append("")
+    
+    if stale_tags:
+        lines.append("## Stale Tags (story done, tag still in code)")
+        lines.append("")
+        for st in stale_tags:
+            lines.append(f"- `{st}`")
+        lines.append("")
+    
+    trace_md_path.parent.mkdir(parents=True, exist_ok=True)
+    trace_md_path.write_text("\n".join(lines), encoding="utf-8")
+
+def emit_okf_bundle(okf_dir: Path, stories: dict, matrix_stories: list) -> None:
+    okf_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Generate index.md
+    idx_lines = []
+    idx_lines.append("---")
+    idx_lines.append("type: Index")
+    idx_lines.append(f"generated_at: {datetime.now(timezone.utc).isoformat()}")
+    idx_lines.append(f"total_concepts: {len(stories)}")
+    idx_lines.append("---")
+    idx_lines.append("")
+    idx_lines.append("# Codebase Wiki — Story Traceability")
+    idx_lines.append("")
+    idx_lines.append("Auto-generated OKF bundle from trace-stories.sh.")
+    idx_lines.append("")
+    idx_lines.append("| Story | Title | Confidence | Links |")
+    idx_lines.append("|-------|-------|------------|-------|")
+    for s in matrix_stories:
+        confs = {l["confidence"] for l in s["links"]}
+        max_conf = "high" if "high" in confs else ("medium" if "medium" in confs else ("low" if confs else "none"))
+        idx_lines.append(f"| [{s['id']}](./{s['id']}.md) | {s['title'][:60]} | {max_conf} | {s['link_count']} |")
+    idx_lines.append("")
+    (okf_dir / "index.md").write_text("\n".join(idx_lines), encoding="utf-8")
+    
+    # Generate one concept per story
+    for s in matrix_stories:
+        concept = []
+        concept.append("---")
+        concept.append(f"type: Story")
+        concept.append(f"id: {s['id']}")
+        concept.append(f"epic: {s['epic_id']}")
+        concept.append(f"bcps: {s['bcp']}")
+        concept.append(f"wsjf: {s['wsjf']}")
+        concept.append(f"implementation_status: {s['status']}")
+        max_confs = set()
+        for l in s["links"]:
+            max_confs.add(l["confidence"])
+        conf = "high" if "high" in max_confs else ("medium" if "medium" in max_confs else ("low" if max_confs else "none"))
+        concept.append(f"coverage_status: {'covered' if s['link_count'] > 0 else 'dark'}")
+        concept.append(f"confidence: {conf}")
+        concept.append("links:")
+        for l in s["links"]:
+            concept.append(f"  - file: {l['file']}")
+            concept.append(f"    line: {l['line']}")
+            concept.append(f"    confidence: {l['confidence']}")
+            concept.append(f"    method: {l['method']}")
+        concept.append("---")
+        concept.append("")
+        concept.append(f"# {s['id']}: {s['title']}")
+        concept.append("")
+        concept.append(f"**Epic:** {s['epic_id']} — {s.get('epic_title', 'Unknown')}")
+        concept.append(f"**Status:** {s['status']}")
+        concept.append(f"**BCP:** {s['bcp']} | **WSJF:** {s['wsjf']}")
+        concept.append("")
+        if s["links"]:
+            concept.append("## Implemented In")
+            concept.append("")
+            for l in s["links"]:
+                concept.append(f"- `{l['file']}` (line {l['line']}, confidence: {l['confidence']}, method: {l['method']})")
+        else:
+            concept.append("*No code links found — this is a dark story.*")
+        concept.append("")
+        (okf_dir / f"{s['id']}.md").write_text("\n".join(concept), encoding="utf-8")

package/scripts/references-manifest.yaml

@@ -0,0 +1,19 @@
+# story: e45s10
+# SSOT → docs/references distillation manifest.
+# Each entry: source globs/files regenerate target via generator script.
+version: 1
+generated_at_field: docs/references/.sync-stamp
+
+entries:
+  - id: model-profiles-catalog
+    sources:
+      - skills/*/SKILL.md
+    target: docs/references/model-profiles.md
+    generator: scripts/generate-reference-tables.sh
+
+  - id: context-engineering
+    sources:
+      - CLAUDE.md
+      - docs/PRINCIPLES.md
+    target: docs/references/context-engineering.md
+    generator: scripts/lib/sync-context-engineering-ref.sh

package/scripts/run-benchmark.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# story: e45s01
+# run-benchmark.sh — N-run with/without-skill delta grading + train/validation split.
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+exec "$PYTHON" "$(dirname "${BASH_SOURCE[0]}")/lib/run-benchmark.py" "$@"

package/scripts/sync-references.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# story: e45s10
+# Regenerate docs/references from SSOT sources (see scripts/references-manifest.yaml).
+# Schedule: weekly via .github/workflows/sync-references.yml; also safe to run locally.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MANIFEST="$REPO_ROOT/scripts/references-manifest.yaml"
+STAMP_FILE="$REPO_ROOT/docs/references/.sync-stamp"
+
+cd "$REPO_ROOT"
+[[ -f "$MANIFEST" ]] || { echo "sync-references: missing manifest" >&2; exit 1; }
+
+run_generator() {
+  local gen="$1"
+  [[ -x "$REPO_ROOT/$gen" || -f "$REPO_ROOT/$gen" ]] || { echo "sync-references: generator not found: $gen" >&2; exit 1; }
+  bash "$REPO_ROOT/$gen"
+}
+
+# model-profiles catalog
+run_generator scripts/generate-reference-tables.sh
+run_generator scripts/lib/sync-context-engineering-ref.sh
+
+date -u +%Y-%m-%dT%H:%M:%SZ > "$STAMP_FILE"
+echo "sync-references: OK (stamp $(cat "$STAMP_FILE"))"

package/scripts/test-trace-matrix-size.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# test-trace-matrix-size.sh — recurrence guard for BUG-2026-07-06-gate-trace-matrix-oversized
+#
+# Asserts trace-matrix.py and its extracted modules stay under the 300-line cap.
+#
+# Usage: bash scripts/test-trace-matrix-size.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+CAP=300
+FAILURES=0
+
+pass() { echo -e "${GREEN}PASS${NC} $1"; }
+fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+
+check_lines() {
+  local file="$1"
+  local lines
+  lines=$(wc -l < "$REPO_ROOT/$file" | tr -d ' ')
+  if [[ "$lines" -le "$CAP" ]]; then
+    pass "$file: $lines lines (≤ $CAP)"
+  else
+    fail "$file: $lines lines (exceeds $CAP)"
+  fi
+}
+
+for f in \
+  scripts/lib/trace-matrix.py \
+  scripts/lib/simple_yaml.py \
+  scripts/lib/trace_renderer.py
+do
+  check_lines "$f"
+done
+
+if [[ "$FAILURES" -gt 0 ]]; then
+  echo "test-trace-matrix-size.sh: $FAILURES failure(s)" >&2
+  exit 1
+fi
+
+exit 0

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/change-request/SKILL.md

@@ -5,6 +5,8 @@ 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
+
 # Change Request
 
 > **HARD GATE** — `specs/release-plan.yaml` must exist before running either mode. If it doesn't, run `plan-release` first.
@@ -19,7 +21,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,8 @@ model: sonnet
 effort: standard
 ---
 
+# 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.
 
@@ -21,6 +23,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`