bigpowers 2.73.9 → 2.74.0

package/scripts/lib/run-benchmark.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# story: e45s01
+"""Run skill benchmarks from specs/benchmarks/ with train/validation split and delta grading."""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+BENCH_DIR = REPO_ROOT / "specs" / "benchmarks"
+REPORTS_DIR = BENCH_DIR / "reports"
+DEFAULT_RUNS = 3
+GRADER_TIMEOUT = 15
+
+
+def load_definition(skill: str) -> dict:
+    path = BENCH_DIR / f"{skill}.yaml"
+    if not path.exists():
+        print(f"ERROR: no benchmark definition at {path}", file=sys.stderr)
+        sys.exit(1)
+    with path.open() as f:
+        return yaml.safe_load(f)
+
+
+def list_skills() -> list[str]:
+    return sorted(p.stem for p in BENCH_DIR.glob("*.yaml") if p.stem not in ("axes",))
+
+
+def run_code_grader(command: str, cwd: Path) -> bool:
+    try:
+        result = subprocess.run(
+            ["bash", "-c", command],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=GRADER_TIMEOUT,
+        )
+        out = (result.stdout + result.stderr).strip()
+        if "PASS" in out.upper() and "FAIL" not in out.upper():
+            return True
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def scenario_pass_rate(scenario: dict, runs: int, with_skill: bool) -> tuple[float, str]:
+    grader = scenario.get("grader", {})
+    gtype = grader.get("type", "code")
+    if gtype == "rubric":
+        return (-1.0, "pending_agent_eval")
+    if gtype != "code":
+        return (-1.0, "unsupported_grader")
+    command = grader.get("command", "")
+    if not command:
+        return (-1.0, "missing_command")
+    if not with_skill:
+        command = f"test -f /dev/null"  # bare agent: code graders cannot pass without skill context
+    passes = sum(1 for _ in range(runs) if run_code_grader(command, REPO_ROOT))
+    return (passes / runs, "code")
+
+
+def pass_at_k(scenarios: list[dict], runs: int, with_skill: bool) -> float:
+    total_weight = 0.0
+    weighted = 0.0
+    for sc in scenarios:
+        rate, status = scenario_pass_rate(sc, runs, with_skill)
+        if status == "pending_agent_eval":
+            continue
+        weight = float(sc.get("weight", 1.0))
+        total_weight += weight
+        weighted += weight * max(rate, 0.0)
+    if total_weight == 0:
+        return 0.0
+    return round(weighted / total_weight, 2)
+
+
+def partition_scenarios(scenarios: list[dict]) -> tuple[list[dict], list[dict]]:
+    train, validation = [], []
+    for sc in scenarios:
+        split = sc.get("split", "validation")
+        if split == "train":
+            train.append(sc)
+        else:
+            validation.append(sc)
+    return train, validation
+
+
+def build_split_report(scenarios: list[dict], runs: int) -> dict:
+    if not scenarios:
+        return {"with_skill": 0.0, "without_skill": 0.0, "delta": 0.0, "scenarios": []}
+    with_score = pass_at_k(scenarios, runs, with_skill=True)
+    without_score = pass_at_k(scenarios, runs, with_skill=False)
+    return {
+        "with_skill": with_score,
+        "without_skill": without_score,
+        "delta": round(with_score - without_score, 2),
+        "scenarios": [sc["id"] for sc in scenarios],
+    }
+
+
+def scenario_details(scenarios: list[dict], runs: int) -> list[dict]:
+    rows = []
+    for sc in scenarios:
+        with_rate, status = scenario_pass_rate(sc, runs, with_skill=True)
+        without_rate, _ = scenario_pass_rate(sc, runs, with_skill=False)
+        if status == "pending_agent_eval":
+            rows.append(
+                {
+                    "id": sc["id"],
+                    "split": sc.get("split", "validation"),
+                    "status": "pending_agent_eval",
+                    "weight": sc.get("weight", 1.0),
+                }
+            )
+            continue
+        rows.append(
+            {
+                "id": sc["id"],
+                "split": sc.get("split", "validation"),
+                "with_pass_rate": round(max(with_rate, 0.0), 2),
+                "without_pass_rate": round(max(without_rate, 0.0), 2),
+                "delta": round(max(with_rate, 0.0) - max(without_rate, 0.0), 2),
+                "weight": sc.get("weight", 1.0),
+            }
+        )
+    return rows
+
+
+def run_benchmark(skill: str, baseline: bool = False) -> dict:
+    definition = load_definition(skill)
+    runs = int(definition.get("runs", DEFAULT_RUNS))
+    scenarios = definition.get("scenarios", [])
+    train_sc, val_sc = partition_scenarios(scenarios)
+    today = date.today().isoformat()
+    report = {
+        "skill": skill,
+        "run_date": today,
+        "runs_per_scenario": runs,
+        "train": build_split_report(train_sc, runs),
+        "validation": build_split_report(val_sc, runs),
+        "scenarios": scenario_details(scenarios, runs),
+    }
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    yaml_path = REPORTS_DIR / f"BENCHMARK-{skill}-{today}.yaml"
+    json_path = REPORTS_DIR / f"benchmark-{skill}.json"
+    with yaml_path.open("w") as f:
+        yaml.dump(
+            {
+                "skill": skill,
+                "run_date": today,
+                "runs_per_scenario": runs,
+                "train": {
+                    "pass_at_k_with": report["train"]["with_skill"],
+                    "pass_at_k_without": report["train"]["without_skill"],
+                    "delta": report["train"]["delta"],
+                },
+                "validation": {
+                    "pass_at_k_with": report["validation"]["with_skill"],
+                    "pass_at_k_without": report["validation"]["without_skill"],
+                    "delta": report["validation"]["delta"],
+                },
+                "scenarios": report["scenarios"],
+            },
+            f,
+            default_flow_style=False,
+        )
+    with json_path.open("w") as f:
+        json.dump(report, f, separators=(",", ":"))
+    print(f"Wrote {yaml_path}")
+    print(f"Wrote {json_path}")
+    if baseline:
+        import shutil
+
+        shutil.copy(yaml_path, REPORTS_DIR / f"BASELINE-{skill}.yaml")
+        shutil.copy(json_path, REPORTS_DIR / f"baseline-{skill}.json")
+        print(f"Pinned baseline for {skill}")
+    val_delta = report["validation"]["delta"]
+    if val_delta < 0:
+        print(f"REGRESSION: validation Δ {val_delta} — do NOT ship")
+    elif val_delta < 0.05:
+        print(f"WARN: validation Δ {val_delta} — marginal contribution")
+    else:
+        print(f"OK: validation Δ {val_delta}")
+    return report
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run skill quality benchmarks")
+    parser.add_argument("skill", nargs="?", help="Skill name to benchmark")
+    parser.add_argument("--all", action="store_true", help="Benchmark all skills with definitions")
+    parser.add_argument("--baseline", action="store_true", help="Pin results as baseline")
+    args = parser.parse_args()
+    if args.all:
+        for skill in list_skills():
+            run_benchmark(skill, baseline=args.baseline)
+    elif args.skill:
+        run_benchmark(args.skill, baseline=args.baseline)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/lib/sync-context-engineering-ref.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# story: e45s10
+# Refresh context-engineering.md sync stamp from SSOT (CLAUDE.md + PRINCIPLES.md).
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TARGET="$REPO_ROOT/docs/references/context-engineering.md"
+STAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+[[ -f "$TARGET" ]] || exit 0
+
+if grep -q 'Last synced:' "$TARGET"; then
+  sed -i.bak "s/\*\*Last synced:\*\*.*/\*\*Last synced:\*\* ${STAMP} (from CLAUDE.md + PRINCIPLES.md)/" "$TARGET"
+  rm -f "${TARGET}.bak"
+else
+  printf '\n**Last synced:** %s (from CLAUDE.md + PRINCIPLES.md)\n' "$STAMP" >> "$TARGET"
+fi
+
+echo "sync-context-engineering-ref: stamped $TARGET"

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/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`