bigpowers 2.73.9 → 2.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.9",
+  "version": "2.74.0",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/bp-churn-rank.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# story: e45s31
+# Rank files by git churn for review prioritization (aidd-churn pattern).
+# Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit N] [path...]
+set -euo pipefail
+
+SINCE="90.days"
+LIMIT=20
+PATHS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since)
+      SINCE="${2:?--since requires a value}"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="${2:?--limit requires a number}"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: bash scripts/bp-churn-rank.sh [--since 90.days] [--limit 20] [path...]"
+      exit 0
+      ;;
+    *)
+      PATHS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo "FAIL: not a git repository" >&2
+  exit 1
+fi
+
+PATHSPEC=""
+if [[ ${#PATHS[@]} -gt 0 ]]; then
+  PATHSPEC="-- ${PATHS[*]}"
+fi
+
+# shellcheck disable=SC2086
+git log --since="$SINCE" --name-only --pretty=format: $PATHSPEC \
+  | grep -v '^$' \
+  | sort \
+  | uniq -c \
+  | sort -rn \
+  | head -n "$LIMIT" \
+  | awk '{printf "%4d  %s\n", $1, $2}'

package/scripts/check-import-boundaries.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# story: e45s14
+# check-import-boundaries.sh — enforce specs/import-boundaries.json in CI
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BOUNDARIES="$REPO_ROOT/specs/import-boundaries.json"
+
+if [[ ! -f "$BOUNDARIES" ]]; then
+  echo "FAIL: missing $BOUNDARIES"
+  exit 1
+fi
+
+python3 - "$REPO_ROOT" "$BOUNDARIES" <<'PY'
+import json, re, sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+rules_path = Path(sys.argv[2])
+rules = json.loads(rules_path.read_text(encoding="utf-8"))
+
+def glob_match(pattern: str, path: str) -> bool:
+    import fnmatch
+    return fnmatch.fnmatch(path, pattern)
+
+violations = []
+
+for boundary in rules.get("boundaries", []):
+    from_pat = boundary["from"]
+    allow = boundary.get("allow", [])
+    deny = boundary.get("deny", [])
+
+    for sh in root.glob("scripts/**/*.sh"):
+        rel = sh.relative_to(root).as_posix()
+        if not glob_match(from_pat, rel):
+            continue
+        text = sh.read_text(encoding="utf-8", errors="replace")
+        for line in text.splitlines():
+            m = re.match(r'^\s*(?:source|\.)\s+["\']?([^"\']+)["\']?', line)
+            if not m:
+                continue
+            target = m.group(1)
+            if target.startswith("$"):
+                continue
+            if not target.startswith("scripts/") and not target.startswith("guard-git/"):
+                if any(glob_match(d, target) for d in deny):
+                    violations.append(f"{rel}: forbidden source {target}")
+                continue
+            rel_target = target
+            if not (Path(root / rel_target).exists() or glob_match(rel_target, rel_target)):
+                pass
+            allowed = any(glob_match(a, rel_target) for a in allow)
+            if not allowed:
+                violations.append(f"{rel}: source {rel_target} not in allowlist for {from_pat}")
+
+if violations:
+    print("IMPORT BOUNDARY FAIL:")
+    for v in violations:
+        print(f"  {v}")
+    sys.exit(1)
+
+print(f"IMPORT BOUNDARIES OK ({len(rules.get('boundaries', []))} rules)")
+PY

package/scripts/compile-rule-matrix.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# story: e45s25
+# Compile CONVENTIONS.md risk tiers → versioned specs/rule-matrix.json
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONVENTIONS="$REPO_ROOT/CONVENTIONS.md"
+OUTPUT="$REPO_ROOT/specs/rule-matrix.json"
+MATRIX_VERSION="1.0.0"
+
+show_help() {
+  cat <<EOF
+Usage: $(basename "$0") [OPTION]
+
+Compile CONVENTIONS.md § Risk Tiers into specs/rule-matrix.json.
+P0/P1/P2/P3 entries are diffable across git tags.
+
+Options:
+  --stdout   Print JSON to stdout instead of writing file
+  --help     Show this help and exit
+EOF
+}
+
+STDOUT_ONLY=0
+if [ "$#" -eq 1 ]; then
+  case "$1" in
+    --help) show_help; exit 0 ;;
+    --stdout) STDOUT_ONLY=1 ;;
+    *) echo "[ERROR] Unknown option: $1" >&2; exit 1 ;;
+  esac
+fi
+
+if [ ! -f "$CONVENTIONS" ]; then
+  echo "[ERROR] CONVENTIONS.md not found at $CONVENTIONS" >&2
+  exit 1
+fi
+
+$PYTHON - "$CONVENTIONS" "$OUTPUT" "$MATRIX_VERSION" "$STDOUT_ONLY" <<'PY'
+import hashlib
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+conventions_path, output_path, matrix_version, stdout_only = sys.argv[1:5]
+stdout_only = stdout_only == "1"
+
+with open(conventions_path, encoding="utf-8") as f:
+    content = f.read()
+
+source_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
+
+# Extract Risk Tiers section
+m = re.search(
+    r"^## Risk Tiers \(Effective Rule Matrix\)\s*\n(.*?)(?=^## |\Z)",
+    content,
+    re.MULTILINE | re.DOTALL,
+)
+if not m:
+    print("[ERROR] CONVENTIONS.md missing '## Risk Tiers (Effective Rule Matrix)'", file=sys.stderr)
+    sys.exit(1)
+
+section = m.group(1)
+tier_re = re.compile(r"^### (P[0-3]) —[^\n]*\n(.*?)(?=^### |\Z)", re.MULTILINE | re.DOTALL)
+rule_re = re.compile(
+    r"^- \*\*\[([^\]]+)\]\*\*:\s*(.+?)\.\s*\(([^)]+)\)\s*$",
+    re.MULTILINE,
+)
+
+tiers: dict[str, list[dict]] = {"P0": [], "P1": [], "P2": [], "P3": []}
+
+for tier_match in tier_re.finditer(section):
+    tier = tier_match.group(1)
+    body = tier_match.group(2)
+    for rule_match in rule_re.finditer(body):
+        rule_id, text, enforce_raw = rule_match.groups()
+        enforce = [s.strip().strip("`") for s in enforce_raw.split(",")]
+        tiers[tier].append(
+            {
+                "id": rule_id,
+                "text": text.strip(),
+                "enforce": enforce,
+            }
+        )
+
+for tier in tiers:
+    if not tiers[tier]:
+        print(f"[ERROR] No rules parsed for tier {tier}", file=sys.stderr)
+        sys.exit(1)
+
+doc = {
+    "matrix_version": matrix_version,
+    "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "source": "CONVENTIONS.md",
+    "source_section": "Risk Tiers (Effective Rule Matrix)",
+    "source_hash": source_hash,
+    "tiers": tiers,
+}
+
+payload = json.dumps(doc, indent=2, sort_keys=True) + "\n"
+
+if stdout_only:
+    print(payload, end="")
+else:
+    import os
+
+    os.makedirs(os.path.dirname(output_path), exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as out:
+        out.write(payload)
+    total = sum(len(v) for v in tiers.values())
+    print(f"OK: wrote {output_path} ({total} rules, matrix_version={matrix_version})")
+PY

package/scripts/hooks/rtk-rewrite.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# story: e45s16
+# rtk-rewrite.sh — PreToolUse hook delegating to rtk's native Bash rewriter.
+set -euo pipefail
+
+if command -v rtk >/dev/null 2>&1; then
+  exec rtk hook claude
+fi
+
+# rtk missing — pass through unchanged (agent should run `bts doctor` / install rtk)
+exit 0

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