bigpowers 2.73.9 → 2.74.1

package/scripts/hooks/token-mgmt-pre-tool-use.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# story: e45s03
+# Mechanical PreToolUse backstop — block oversized Read/Grep/Bash before context bloat.
+set -euo pipefail
+
+READ_MAX_BYTES=102400   # 100KB
+GREP_MAX_MATCHES=200
+BASH_WARN_PATTERNS='^(npm test|pnpm test|yarn test|cargo test|go test|jest|vitest|pytest|rake test|rspec|git log|git diff|docker logs|kubectl logs|find |rg |grep )'
+
+deny() {
+  echo "TOKEN-MGMT BLOCK: $1" >&2
+  echo "Use sqz_read_file / sqz_grep / rtk / bts compress per CLAUDE.md § Token Management." >&2
+  exit 2
+}
+
+INPUT="$(cat)"
+TOOL="$(echo "$INPUT" | jq -r '.tool_name // .tool // empty')"
+TOOL_INPUT="$(echo "$INPUT" | jq -c '.tool_input // .input // {}')"
+
+case "$TOOL" in
+  Read|read)
+    PATH_ARG="$(echo "$TOOL_INPUT" | jq -r '.path // .file_path // .file // empty')"
+    [[ -n "$PATH_ARG" && -f "$PATH_ARG" ]] || exit 0
+    SIZE="$(wc -c < "$PATH_ARG" | tr -d ' ')"
+    if (( SIZE > READ_MAX_BYTES )); then
+      deny "Read $PATH_ARG is ${SIZE} bytes (max ${READ_MAX_BYTES}). Use sqz_read_file or bts compress."
+    fi
+    ;;
+  Grep|grep)
+    LIMIT="$(echo "$TOOL_INPUT" | jq -r '.head_limit // .max_matches // empty')"
+    if [[ -z "$LIMIT" || "$LIMIT" == "null" ]]; then
+      deny "Grep without head_limit (max ${GREP_MAX_MATCHES}). Set head_limit<=${GREP_MAX_MATCHES} or use sqz_grep."
+    fi
+    if [[ "$LIMIT" =~ ^[0-9]+$ ]] && (( LIMIT > GREP_MAX_MATCHES )); then
+      deny "Grep head_limit=${LIMIT} exceeds ${GREP_MAX_MATCHES}. Lower limit or use sqz_grep."
+    fi
+    ;;
+  Bash|bash|Shell|shell)
+    CMD="$(echo "$TOOL_INPUT" | jq -r '.command // empty')"
+    [[ -n "$CMD" ]] || exit 0
+    if echo "$CMD" | grep -qE 'sqz compress|bts compress|rtk |SQZ_NO_DEDUP'; then
+      exit 0
+    fi
+    if echo "$CMD" | grep -qE "$BASH_WARN_PATTERNS"; then
+      deny "Bash may exceed 500 lines of output. Prefix with rtk or pipe through sqz compress."
+    fi
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+exit 0

package/scripts/install.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e45s16
 # install.sh — global symlink install for bigpowers skills
 #
 # Supported tools:
@@ -83,6 +84,9 @@ install_claude() {
   link "$REPO_ROOT/.gemini/extensions/bigpowers/hooks/run-hook.cmd" "$CLAUDE_HOOKS_DIR/run-hook.cmd"
   link "$REPO_ROOT/guard-git/scripts/block-dangerous-git.sh" "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh"
   link "$REPO_ROOT/guard-git/scripts/lib" "$CLAUDE_HOOKS_DIR/lib"
+  link "$REPO_ROOT/scripts/hooks/rtk-rewrite.sh" "$CLAUDE_HOOKS_DIR/rtk-rewrite.sh"
+  # story: e45s16
+  chmod +x "$REPO_ROOT/scripts/hooks/rtk-rewrite.sh" 2>/dev/null || true
 
   if [[ -f "$CLAUDE_SETTINGS" ]]; then
     echo "  Configuring global hooks in $CLAUDE_SETTINGS..."
@@ -92,6 +96,7 @@ install_claude() {
       cat "$CLAUDE_SETTINGS" | jq '
         .hooks.SessionStart += [{"matcher":"startup|clear|compact","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/run-hook.cmd"'\" session-start","async":false}]}] |
         .hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/block-dangerous-git.sh"'\""}]}] |
+        .hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":"\"'"$CLAUDE_HOOKS_DIR/rtk-rewrite.sh"'\""}]}] |
         # deduplicate
         .hooks.SessionStart |= unique |
         .hooks.PreToolUse |= unique
@@ -115,6 +120,7 @@ uninstall_claude() {
     unlink_if_managed "$CLAUDE_HOOKS_DIR/session-start" "$REPO_ROOT/"
     unlink_if_managed "$CLAUDE_HOOKS_DIR/run-hook.cmd" "$REPO_ROOT/"
     unlink_if_managed "$CLAUDE_HOOKS_DIR/block-dangerous-git.sh" "$REPO_ROOT/"
+    unlink_if_managed "$CLAUDE_HOOKS_DIR/rtk-rewrite.sh" "$REPO_ROOT/"
     unlink_if_managed "$CLAUDE_HOOKS_DIR/lib" "$REPO_ROOT/"
   fi
 }

package/scripts/lib/completeness-critic.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# story: e45s05
+# Adversarial gap-finding completeness critic — post gate-trace.
+# Classifications: BLOCKER | WARNING | FILLED
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+BLOCKERS=0
+WARNINGS=0
+FILLED=0
+
+classify() {
+  local kind="$1" msg="$2"
+  echo "[$kind] $msg"
+  case "$kind" in
+    BLOCKER) BLOCKERS=$((BLOCKERS + 1)) ;;
+    WARNING) WARNINGS=$((WARNINGS + 1)) ;;
+    FILLED) FILLED=$((FILLED + 1)) ;;
+  esac
+}
+
+# Ensure upstream artifacts exist
+[[ -f specs/traceability-matrix.json ]] \
+  || classify BLOCKER "Missing specs/traceability-matrix.json — run trace-stories.sh --json"
+[[ -f specs/blind-spots.json ]] \
+  || classify BLOCKER "Missing specs/blind-spots.json — run check-blind-spots.sh"
+
+if [[ -f specs/traceability-matrix.json ]]; then
+  UNDONE="$(jq '[.stories[]? | select(.status != "done" and (.code_tags // 0) == 0)] | length' specs/traceability-matrix.json 2>/dev/null || echo 0)"
+  (( UNDONE > 0 )) && classify BLOCKER "$UNDONE active story(ies) with zero code tags"
+  COVERAGE="$(jq -r '.summary.coverage_percent // .coverage_percent // empty' specs/traceability-matrix.json 2>/dev/null)"
+  if [[ -n "$COVERAGE" && "$COVERAGE" != "null" ]]; then
+    awk -v c="$COVERAGE" 'BEGIN{if(c+0 < 60) exit 1}' || classify WARNING "Trace coverage ${COVERAGE}% below 60% target"
+    awk -v c="$COVERAGE" 'BEGIN{if(c+0 >= 80) exit 0; exit 1}' && classify FILLED "Trace coverage ${COVERAGE}% meets 80% PASS bar"
+  fi
+fi
+
+if [[ -f specs/blind-spots.json ]]; then
+  HIGH="$(jq '[.findings[]? | select(.severity == "HIGH")] | length' specs/blind-spots.json 2>/dev/null || echo 0)"
+  (( HIGH > 0 )) && classify BLOCKER "$HIGH HIGH-severity blind-spot finding(s) remain open"
+fi
+
+# Verify evidence for done stories
+if [[ -d specs/verifications ]]; then
+  VC="$(find specs/verifications -maxdepth 1 -name '*-verify.yaml' 2>/dev/null | wc -l | tr -d ' ')"
+  (( VC == 0 )) && classify WARNING "No specs/verifications/*-verify.yaml evidence bundles"
+  (( VC > 0 )) && classify FILLED "$VC verification evidence bundle(s) on disk"
+else
+  classify WARNING "specs/verifications/ directory missing"
+fi
+
+echo "---"
+echo "completeness-critic: BLOCKER=$BLOCKERS WARNING=$WARNINGS FILLED=$FILLED"
+
+if (( BLOCKERS > 0 )); then
+  echo "MERGE GATE ABORT: BLOCKER findings must be resolved" >&2
+  exit 1
+fi
+
+exit 0

package/scripts/lib/doc-fetch-cache.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# story: e45s20
+# doc-fetch-cache.sh — ETag-revalidated fetch cache for Context7 / bts docs queries.
+# Usage:
+#   bash scripts/lib/doc-fetch-cache.sh get <cache-key>     # print cached body or empty
+#   bash scripts/lib/doc-fetch-cache.sh put <key> <etag> <body-file>
+#   bash scripts/lib/doc-fetch-cache.sh stale <cache-key>   # exit 0 if TTL expired
+set -euo pipefail
+
+CACHE_DIR="${DOC_CACHE_DIR:-.bigpowers/cache/docs}"
+TTL_SEC="${DOC_CACHE_TTL:-300}"
+
+mkdir -p "$CACHE_DIR"
+
+_key_path() {
+  local key="$1"
+  local hash
+  hash=$(printf '%s' "$key" | shasum -a 256 | awk '{print $1}')
+  echo "$CACHE_DIR/${hash}"
+}
+
+cmd_get() {
+  local key="$1" base etag_file body_file meta_file
+  base="$(_key_path "$key")"
+  body_file="${base}.body"
+  etag_file="${base}.etag"
+  meta_file="${base}.meta"
+
+  [[ -f "$body_file" && -f "$meta_file" ]] || exit 1
+
+  local cached_at now
+  cached_at=$(grep '^cached_at=' "$meta_file" | cut -d= -f2)
+  now=$(date +%s)
+  if [[ -n "$cached_at" && $((now - cached_at)) -gt "$TTL_SEC" ]]; then
+    exit 1
+  fi
+
+  cat "$body_file"
+  [[ -f "$etag_file" ]] && printf 'ETAG:%s\n' "$(cat "$etag_file")" >&2
+  exit 0
+}
+
+cmd_put() {
+  local key="$1" etag="$2" body_file="$3" base
+  base="$(_key_path "$key")"
+  cp "$body_file" "${base}.body"
+  printf '%s' "$etag" > "${base}.etag"
+  printf 'cached_at=%s\nkey=%s\n' "$(date +%s)" "$key" > "${base}.meta"
+}
+
+cmd_stale() {
+  local key="$1" base meta_file
+  base="$(_key_path "$key")"
+  meta_file="${base}.meta"
+  [[ -f "$meta_file" ]] || exit 0
+  local cached_at now
+  cached_at=$(grep '^cached_at=' "$meta_file" | cut -d= -f2)
+  now=$(date +%s)
+  [[ $((now - cached_at)) -gt "$TTL_SEC" ]] && exit 0
+  exit 1
+}
+
+case "${1:-}" in
+  get)   cmd_get "${2:?key}" ;;
+  put)   cmd_put "${2:?key}" "${3:?etag}" "${4:?body}" ;;
+  stale) cmd_stale "${2:?key}" ;;
+  *)
+    echo "Usage: doc-fetch-cache.sh get|put|stale <key> [etag] [body-file]" >&2
+    exit 2
+    ;;
+esac

package/scripts/lib/golden-suite-gates.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# story: e42s04 e45s02
+# story: e42s04 e45s02 e45s14
 # Deterministic gate runner for golden suite — sourced by golden-suite-run.sh
 
 if [ -n "${GOLDEN_GATES_LOADED:-}" ]; then return 0; fi
@@ -14,6 +14,8 @@ GOLDEN_GATES=(
   "g09-yaml-roundtrip:bash scripts/golden-g09-yaml-roundtrip.sh:false"
   "g10-trace-anti-vacuity:bash scripts/golden-g10-trace-anti-vacuity.sh:false"
   "g11-gitignore-venv:bash scripts/golden-g11-gitignore-venv.sh:false"
+  "import-boundaries:bash scripts/check-import-boundaries.sh:false"
+  "skill-catalog:bash scripts/validate-skill-catalog.sh:false"
   "specs-parse:bash scripts/validate-specs-yaml.sh:false"
 )
 

package/scripts/lib/parallel-review-worktrees.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# story: e45s18
+# parallel-review-worktrees.sh — isolated git worktrees for parallel audit-code / security-review
+# Usage: bash scripts/lib/parallel-review-worktrees.sh <audit-code|security-review>
+set -euo pipefail
+
+CHECK="${1:?usage: parallel-review-worktrees.sh <audit-code|security-review>}"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+BASE=".bigpowers/worktrees/review-${CHECK}"
+mkdir -p "$(dirname "$BASE")"
+
+if git worktree list | grep -q "$BASE"; then
+  git worktree remove --force "$BASE" 2>/dev/null || true
+fi
+
+git worktree add --detach "$BASE" HEAD >/dev/null
+echo "WORKTREE: $BASE (detached @ $(git -C "$BASE" rev-parse --short HEAD))"
+
+case "$CHECK" in
+  audit-code)
+    echo "Run audit-code checklist inside worktree; reports → specs/verifications/"
+    ;;
+  security-review)
+    echo "Run security-review 5-phase scan inside worktree; reports → specs/security/"
+    ;;
+  *)
+    echo "Unknown check: $CHECK" >&2
+    exit 2
+    ;;
+esac
+
+echo "OK: isolated worktree ready — parallel checks cannot corrupt parent working tree"

package/scripts/lib/plan-consistency-check.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# story: e45s04
+# Pre-build cross-artifact consistency — slice-tasks output vs epic capsule.
+# Severity: CRITICAL | HIGH | MED | LOW (LOW is informational only).
+set -euo pipefail
+
+CAPSULE="${1:-}"
+if [[ -z "$CAPSULE" || ! -d "$CAPSULE" ]]; then
+  echo "Usage: bash scripts/lib/plan-consistency-check.sh specs/epics/eNN-slug" >&2
+  exit 2
+fi
+
+EPIC_YAML="$CAPSULE/epic.yaml"
+CRITICAL=0
+HIGH=0
+MED=0
+
+report() {
+  local sev="$1" msg="$2"
+  echo "[$sev] $msg"
+  case "$sev" in
+    CRITICAL) CRITICAL=$((CRITICAL + 1)) ;;
+    HIGH) HIGH=$((HIGH + 1)) ;;
+    MED) MED=$((MED + 1)) ;;
+  esac
+}
+
+[[ -f "$EPIC_YAML" ]] || report CRITICAL "Missing epic.yaml in $CAPSULE"
+
+# Story IDs declared in epic.yaml
+declare -A EPIC_STORIES=()
+if [[ -f "$EPIC_YAML" ]]; then
+  while IFS= read -r sid; do
+    [[ -n "$sid" ]] && EPIC_STORIES["$sid"]=1
+  done < <(grep -E '^[[:space:]]*- id: e[0-9]+s[0-9]+' "$EPIC_YAML" | awk '{print $3}')
+fi
+
+shopt -s nullglob
+SPECS=("$CAPSULE"/e*s*.md)
+TASKS=("$CAPSULE"/e*s*-tasks.yaml)
+shopt -u nullglob
+
+(( ${#SPECS[@]} > 0 )) || report CRITICAL "No story spec .md files in capsule (run slice-tasks first)"
+(( ${#TASKS[@]} > 0 )) || report CRITICAL "No *-tasks.yaml files in capsule (run plan-work first)"
+
+declare -A SPEC_IDS=()
+for spec in "${SPECS[@]}"; do
+  base="$(basename "$spec" .md)"
+  sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
+  [[ -n "$sid" ]] || continue
+  SPEC_IDS["$sid"]=1
+  [[ -n "${EPIC_STORIES[$sid]+x}" ]] || report HIGH "Story $sid in spec file but missing from epic.yaml manifest"
+  grep -qE '^## (17\.|Acceptance|Verification Script)' "$spec" \
+    || report HIGH "Story $sid spec missing §17 acceptance criteria or Verification Script"
+  grep -qiE 'ambiguous|TBD|TODO|FIXME' "$spec" \
+    && report MED "Story $sid spec contains ambiguous/TBD markers"
+done
+
+for tasks in "${TASKS[@]}"; do
+  base="$(basename "$tasks" -tasks.yaml)"
+  sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
+  [[ -n "$sid" ]] || continue
+  [[ -n "${SPEC_IDS[$sid]+x}" ]] || report CRITICAL "tasks.yaml for $sid without matching story spec .md"
+  grep -qE '^[[:space:]]*verify:' "$tasks" \
+    || report CRITICAL "Story $sid tasks.yaml missing runnable verify: commands"
+  grep -qE '^status:[[:space:]]*(failing|todo|passing)' "$tasks" \
+    || report MED "Story $sid tasks.yaml should use status: failing|passing ledger (e45s06)"
+done
+
+for sid in "${!EPIC_STORIES[@]}"; do
+  [[ -n "${SPEC_IDS[$sid]+x}" ]] || report HIGH "epic.yaml lists $sid but no story spec .md exists"
+done
+
+echo "---"
+echo "plan-consistency-check: CRITICAL=$CRITICAL HIGH=$HIGH MED=$MED"
+
+if (( CRITICAL > 0 || HIGH > 0 )); then
+  echo "BLOCKED: resolve CRITICAL/HIGH before code generation" >&2
+  exit 1
+fi
+
+if (( MED > 0 )); then
+  echo "WARN: MED findings present — confirm with user before build"
+  exit 0
+fi
+
+echo "PASS: capsule artifacts consistent"
+exit 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/run-skill-verify.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e22s01
 # Run all SKILL.md → verify: commands and report PASS/FAIL/SKIP.
 # Exit 0 only when zero FAILs.
 # Usage: bash scripts/run-skill-verify.sh [skill-name]

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/sync-skills.sh

@@ -1,5 +1,16 @@
 #!/usr/bin/env bash
-# story: e13s03 e28s03 e39s04
+# story: e05s01
+# story: e12s01
+# story: e12s02
+# story: e12s03
+# story: e12s04
+# story: e12s06
+# story: e13s03
+# story: e28s02
+# story: e28s03
+# story: e39s04
+# story: e29s01
+# story: e29s02
 # sync-skills.sh — generate Cursor, Gemini CLI, pi, and OKF artifacts from SKILL.md source files
 # Architecture: Parse→IR→Render. Each target is its own render_<target>() function.
 # Run this after adding or updating any skill. Symlinks carry changes through automatically.