bigpowers 2.56.1 → 2.57.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.56.1",
+  "version": "2.57.0",
   "description": "73 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.57.0](https://github.com/danielvm-git/bigpowers/compare/v2.56.1...v2.57.0) (2026-07-03)
+
+
+### Features
+
+* **compliance:** add waiver subsystem to audit-compliance.sh ([985b67d](https://github.com/danielvm-git/bigpowers/commit/985b67dcaf8df61108d372a0572ffced99f5af29))
+
 ## [2.56.1](https://github.com/danielvm-git/bigpowers/compare/v2.56.0...v2.56.1) (2026-07-03)
 
 

package/package.json

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

package/scripts/audit-compliance.sh

@@ -67,6 +67,43 @@ fi
 # --- Global Stats ---
 TOTAL_GLOBAL_PASS=0
 TOTAL_GLOBAL_FAIL=0
+TOTAL_GLOBAL_WAIVED=0
+TOTAL_GLOBAL_EXPIRED=0
+
+# --- Waiver Subsystem ---
+# Loads waivers.yaml and provides is_waived() for bash 3.2+ compatibility.
+# Waived steps are excluded from the denominator; expired waivers re-enter as FAILs.
+WAIVER_FILE="specs/verifications/waivers.yaml"
+
+is_waived() {
+  local step_sanitized="$1"
+  local waiver_file="${WAIVER_FILE:-specs/verifications/waivers.yaml}"
+
+  if [[ ! -f "$waiver_file" ]]; then
+    return 1  # No waiver file → not waived
+  fi
+
+  # Check if step has any waiver entry
+  if ! grep -q "step_sanitized: $step_sanitized" "$waiver_file" 2>/dev/null; then
+    return 1  # Not found → not waived
+  fi
+
+  # Extract review_date for this step (parses the YAML block)
+  local review_date
+  review_date=$(awk -v slug="$step_sanitized" '
+    $0 ~ "step_sanitized: " slug { found=1; next }
+    found && /review_date:/ { gsub(/[^0-9-]/, "", $0); print; exit }
+  ' "$waiver_file")
+
+  # Check expiry: if review_date < today, waiver is expired
+  local today
+  today=$(date +%Y-%m-%d)
+  if [[ -n "$review_date" && "$review_date" < "$today" ]]; then
+    return 2  # Expired waiver → counts as FAIL
+  fi
+
+  return 0  # Valid waiver → excluded from denominator
+}
 
 # --- Judging Logic ---
 
@@ -150,7 +187,7 @@ process_step() {
   local scenario_name="$3"
   local report_file="$4"
   echo "    [STEP] $step"
-  
+
   if [[ "$DRY_RUN" == "true" ]]; then
     return 0
   fi
@@ -167,12 +204,44 @@ process_step() {
 
     if [[ "$JUDGE" == "gemini" ]]; then
       judge_with_gemini "$step" "$feature_name" "$scenario_name" "$evidence" "$report_file"
+      # Gemini path: rely on judge return code (no waiver check for LLM path)
     else
-      judge_binary "$step" "$exit_code" "$evidence" "$report_file"
+      # Binary path: check waivers before counting as FAIL
+      if [[ $exit_code -eq 0 ]]; then
+        echo "      Result: PASS"
+        echo "- [x] $step (PASS)" >> "$report_file"
+        return 0
+      fi
+
+      # Step failed — check if it has a valid waiver
+      is_waived "$sanitized_step"
+      local waiver_code=$?
+
+      if [[ $waiver_code -eq 0 ]]; then
+        # Valid waiver — exclude from denominator
+        echo "      Result: WAIVED (documented exception)"
+        echo "- [~] $step (WAIVED)" >> "$report_file"
+        ((TOTAL_GLOBAL_WAIVED++))
+        return 3  # Special code: waived (not PASS, not FAIL)
+      elif [[ $waiver_code -eq 2 ]]; then
+        # Expired waiver — re-enter denominator as FAIL
+        echo "      Result: FAIL (EXPIRED WAIVER)"
+        echo "- [ ] $step (FAIL) - EXPIRED WAIVER: review_date has passed" >> "$report_file"
+        ((TOTAL_GLOBAL_EXPIRED++))
+        ((TOTAL_GLOBAL_FAIL++))
+        return 1
+      else
+        # No waiver — genuine FAIL
+        echo "      Result: FAIL"
+        echo "- [ ] $step (FAIL) - $evidence" >> "$report_file"
+        ((TOTAL_GLOBAL_FAIL++))
+        return 1
+      fi
     fi
   else
     echo "      Result: FAIL (Missing evidence: $step_script)"
     echo "- [ ] $step (FAIL) - No verification script found at $step_script" >> "$report_file"
+    ((TOTAL_GLOBAL_FAIL++))
     return 1
   fi
 }
@@ -214,12 +283,17 @@ run_audit_file() {
       echo "### Scenario: $CURRENT_SCENARIO" >> "$REPORT_FILE"
     elif [[ "$line" =~ ^(Given|When|Then|And|But)\  ]]; then
       if [[ "$IN_SCENARIO" == "true" ]]; then
-        if process_step "$line" "$CURRENT_FEATURE" "$CURRENT_SCENARIO" "$REPORT_FILE"; then
+        local step_result
+        process_step "$line" "$CURRENT_FEATURE" "$CURRENT_SCENARIO" "$REPORT_FILE"
+        step_result=$?
+        if [[ $step_result -eq 3 ]]; then
+          # Waived — excluded from both pass and fail counts
+          :
+        elif [[ $step_result -eq 0 ]]; then
           ((TOTAL_PASS++))
           ((TOTAL_GLOBAL_PASS++))
         else
           ((TOTAL_FAIL++))
-          ((TOTAL_GLOBAL_FAIL++))
         fi
       fi
     fi
@@ -247,15 +321,23 @@ done
 
 echo "============================================================"
 echo "Global Audit Summary:"
-echo "  TOTAL PASS: $TOTAL_GLOBAL_PASS"
-echo "  TOTAL FAIL: $TOTAL_GLOBAL_FAIL"
 TOTAL_GLOBAL_ALL=$((TOTAL_GLOBAL_PASS + TOTAL_GLOBAL_FAIL))
+echo "  TOTAL PASS:   $TOTAL_GLOBAL_PASS"
+echo "  TOTAL FAIL:   $TOTAL_GLOBAL_FAIL"
+echo "  TOTAL WAIVED: $TOTAL_GLOBAL_WAIVED  (excluded from denominator)"
+if [[ $TOTAL_GLOBAL_EXPIRED -gt 0 ]]; then
+  echo "  EXPIRED WAIVERS: $TOTAL_GLOBAL_EXPIRED (counted as FAIL)"
+fi
 if [[ $TOTAL_GLOBAL_ALL -gt 0 ]]; then
   SCORE=$(awk "BEGIN { printf \"%d\", $TOTAL_GLOBAL_PASS * 100 / $TOTAL_GLOBAL_ALL }")
 else
   SCORE=0
 fi
-echo "  SCORE: ${SCORE}% (threshold 94%)"
+if [[ $TOTAL_GLOBAL_WAIVED -gt 0 ]]; then
+  echo "  SCORE: ${SCORE}% (of ${TOTAL_GLOBAL_ALL} unwaived checks, threshold 94%)"
+else
+  echo "  SCORE: ${SCORE}% (threshold 94%)"
+fi
 if [[ $SCORE -ge 94 ]]; then
   echo "  GATE: PASS"
   exit 0

package/scripts/lib/blind-spot-checks.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+# story: e38s04
+# blind-spot-checks.py — TEA-inspired heuristic blind-spot detector (Python engine).
+# Called by scripts/check-blind-spots.sh. Not meant to be run standalone without args.
+
+import json, os, re, sys
+from pathlib import Path
+from datetime import datetime, timezone
+
+ROOT = Path(sys.argv[1])
+BLIND_SPOTS_JSON = Path(sys.argv[2])
+EXEC_STATUS = Path(sys.argv[3])
+MATRIX_JSON = Path(sys.argv[4])
+VERIFICATIONS_DIR = Path(sys.argv[5])
+EPICS_DIR = Path(sys.argv[6])
+
+findings: list[dict] = []
+
+# Parse execution-status.yaml → flat dict of story_id → status
+def parse_exec_status(path: Path) -> dict[str, str]:
+    status: dict[str, str] = {}
+    if not path.exists():
+        return status
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    in_dev_status = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("development_status:"):
+            in_dev_status = True
+            continue
+        if not in_dev_status:
+            if stripped and not stripped.startswith(" ") and not stripped.startswith("#"):
+                if ":" in stripped:
+                    in_dev_status = False
+            continue
+        if ":" in stripped and not stripped.startswith("#"):
+            m = re.match(r'\s+(\S+):\s*"([^"]*)"', stripped)
+            if m:
+                status[m.group(1)] = m.group(2)
+    return status
+
+dev_status = parse_exec_status(EXEC_STATUS)
+
+# Read traceability matrix (if available)
+matrix_data: dict | None = None
+if MATRIX_JSON.exists():
+    matrix_data = json.loads(MATRIX_JSON.read_text(encoding="utf-8"))
+
+# Build indexes from matrix
+tagged_files: dict[str, list[str]] = {}
+file_story_counts: dict[str, set[str]] = {}
+if matrix_data:
+    for s in matrix_data.get("stories", []):
+        sid = s["id"]
+        for link in s.get("links", []):
+            f = link["file"]
+            tagged_files.setdefault(sid, []).append(f)
+            file_story_counts.setdefault(f, set()).add(sid)
+
+# Enumerate all tracked code files
+CODE_EXTENSIONS = {".sh", ".py", ".js", ".ts", ".jsx", ".tsx", ".md", ".yaml", ".yml", ".cjs", ".mjs", ".json"}
+SKIP_DIRS = {".git", "node_modules", ".cursor", ".gemini", ".pi", "specs", "dist", "build", "__pycache__", ".bigpowers"}
+
+def is_code_file(p: Path) -> bool:
+    return p.suffix in CODE_EXTENSIONS and not any(s in p.parts for s in SKIP_DIRS)
+
+all_code_files: list[str] = []
+for root, dirs, files in os.walk(str(ROOT)):
+    dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+    rel_root = str(Path(root).relative_to(ROOT))
+    for fname in files:
+        fpath = Path(root) / fname
+        if is_code_file(fpath):
+            all_code_files.append(str(fpath.relative_to(ROOT)))
+
+# Helper: find test files for a given code file
+TEST_PATTERNS = [
+    re.compile(r"(^|/)test(s)?/", re.IGNORECASE),
+    re.compile(r"(^|/)__tests__/", re.IGNORECASE),
+    re.compile(r"\.test\.", re.IGNORECASE),
+    re.compile(r"\.spec\.", re.IGNORECASE),
+    re.compile(r"_test\.", re.IGNORECASE),
+    re.compile(r"test_", re.IGNORECASE),
+]
+
+def has_test_files(code_files: list[str]) -> bool:
+    for cf in code_files:
+        cf_path = Path(cf)
+        cf_dir = cf_path.parent
+        cf_stem = cf_path.stem
+        for tf in all_code_files:
+            tp = Path(tf)
+            if tp.parent == cf_dir:
+                for pat in TEST_PATTERNS:
+                    if pat.search(tp.name) and cf_stem in tp.name:
+                        return True
+            for tdn in ["tests", "test", "__tests__"]:
+                test_dir = cf_dir / tdn
+                if str(test_dir) in tf:
+                    if cf_stem in tp.name:
+                        return True
+    return False
+
+# Check A: verify-gap
+for sid, sstatus in dev_status.items():
+    if sstatus == "done":
+        verify_file = VERIFICATIONS_DIR / f"{sid}-verify.yaml"
+        if not verify_file.exists():
+            findings.append({
+                "check": "verify-gap", "story_id": sid, "severity": "HIGH",
+                "description": f"Story {sid} is marked done but no verification evidence at specs/verifications/{sid}-verify.yaml",
+                "remediation": f"Run verify-work for {sid} or create the verification evidence file"
+            })
+
+# Check B: test-gap
+for sid, files in tagged_files.items():
+    if dev_status.get(sid) in ("done", "active"):
+        if not has_test_files(files):
+            code_only = [f for f in files if Path(f).suffix in {".sh", ".py", ".js", ".ts", ".jsx", ".tsx"} and "SKILL.md" not in f]
+            if code_only:
+                findings.append({
+                    "check": "test-gap", "story_id": sid, "severity": "MEDIUM",
+                    "description": f"Story {sid} has {len(code_only)} tagged code file(s) with no matching test files",
+                    "remediation": f"Add test coverage for: {', '.join(code_only[:3])}"
+                })
+
+# Check C: epic-orphan
+if EPICS_DIR.exists():
+    for epic_dir in sorted(EPICS_DIR.iterdir()):
+        if not epic_dir.is_dir() or epic_dir.name == "archive":
+            continue
+        epic_yaml = epic_dir / "epic.yaml"
+        if not epic_yaml.exists():
+            continue
+        for task_file in sorted(epic_dir.glob("e*[0-9]-tasks.yaml")):
+            sid_match = re.match(r"(e\d+s\d+)", task_file.name)
+            if not sid_match:
+                continue
+            sid = sid_match.group(1)
+            sstatus = dev_status.get(sid, "backlog")
+            if sstatus in ("done", "active") and sid not in tagged_files:
+                findings.append({
+                    "check": "epic-orphan", "story_id": sid, "severity": "LOW",
+                    "description": f"Story {sid} has capsule tasks but no story tags found in any code file",
+                    "remediation": f"Add `// story: {sid}` tags to implementing files"
+                })
+
+# Check D: stale-tag
+stale_from_matrix: set[str] = set()
+if matrix_data:
+    stale_from_matrix = set(matrix_data.get("summary", {}).get("stale_tags", []))
+for sid in stale_from_matrix:
+    findings.append({
+        "check": "stale-tag", "story_id": sid, "severity": "LOW",
+        "description": f"Story {sid} is marked done but still has story tags in code",
+        "remediation": f"Remove `// story: {sid}` tags or confirm the story should remain done"
+    })
+
+# Check E: double-tag
+for fpath, sids in file_story_counts.items():
+    if len(sids) > 1:
+        findings.append({
+            "check": "double-tag", "file": fpath, "severity": "MEDIUM",
+            "description": f"File '{fpath}' is tagged with multiple stories: {', '.join(sorted(sids))}",
+            "remediation": "Review whether this file genuinely implements multiple stories."
+        })
+
+# Check F: bootstrap-testless
+active_and_recent = [sid for sid in sorted(dev_status.keys()) if dev_status[sid] == "active"]
+for sid in active_and_recent:
+    if sid in tagged_files:
+        code_files = tagged_files[sid]
+        code_only = [f for f in code_files if Path(f).suffix in {".sh", ".py", ".js", ".ts", ".jsx", ".tsx"} and "SKILL.md" not in f]
+        if code_only and not has_test_files(code_files):
+            findings.append({
+                "check": "bootstrap-testless", "story_id": sid, "severity": "HIGH",
+                "description": f"Active story {sid} has {len(code_only)} tagged code file(s) but no test files detected",
+                "remediation": f"Add test files for: {', '.join(code_only[:3])}"
+            })
+
+# De-duplicate findings
+seen: set[tuple] = set()
+deduped: list[dict] = []
+for f in findings:
+    key = (f["check"], f.get("story_id", f.get("file", "")))
+    if key not in seen:
+        seen.add(key)
+        deduped.append(f)
+findings = deduped
+
+# Emit blind-spots.json
+high_count = sum(1 for f in findings if f["severity"] == "HIGH")
+medium_count = sum(1 for f in findings if f["severity"] == "MEDIUM")
+low_count = sum(1 for f in findings if f["severity"] == "LOW")
+
+blind_spots = {
+    "generated_at": datetime.now(timezone.utc).isoformat(),
+    "version": "1.0",
+    "summary": {"total_findings": len(findings), "high": high_count, "medium": medium_count, "low": low_count},
+    "findings": findings
+}
+
+BLIND_SPOTS_JSON.parent.mkdir(parents=True, exist_ok=True)
+BLIND_SPOTS_JSON.write_text(json.dumps(blind_spots, indent=2), encoding="utf-8")
+
+print(f"check-blind-spots.sh: {len(findings)} findings ({high_count} HIGH, {medium_count} MEDIUM, {low_count} LOW)")
+for f in findings:
+    print(f"  [{f['severity']}] {f['check']}: {f['description'][:100]}")
+if high_count > 0:
+    print(f"\n⚠️  {high_count} HIGH-severity finding(s) — review specs/blind-spots.json")
+    sys.exit(1)
+sys.exit(0)

package/scripts/lib/emit-okf-metrics.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# story: e40s06
+# emit-okf-metrics.sh — shared OKF story-metrics bundle emitter (e40 provenance gate).
+# Sourced by scripts/record-cycle-time.sh; emits YAML frontmatter + markdown body.
+# Not meant to be run standalone.
+
+# Usage: emit_okf_metrics <story> <bcps> <effort_hours> <lead_min> <commit_range> <generated_at>
+#                         <agent_cost> <agent_tokens_total> <agent_cache_hit>
+#                         <agent_compression> <agent_tool_calls> <agent_api_requests>
+#                         <agent_duration_ms> <agent_model> <agent_tier>
+#                         <agent_downgraded> <agent_skills>
+#                         <agent_tokens_in> <agent_tokens_out>
+#                         <agent_tokens_cache_read> <agent_tokens_cache_write>
+#                         [--file <path>]
+emit_okf_metrics() {
+  local story="$1" bcps="$2" eff="$3" lead_min="$4" commit_range="$5" generated_at="$6"
+  local agent_cost="${7:-null}" agent_tokens_total="${8:-null}" agent_cache_hit="${9:-null}"
+  local agent_compression="${10:-null}" agent_tool_calls="${11:-null}" agent_api_requests="${12:-null}"
+  local agent_duration_ms="${13:-null}" agent_model="${14:-null}" agent_tier="${15:-null}"
+  local agent_downgraded="${16:-null}" agent_skills="${17:-[]}"
+  local agent_tokens_in="${18:-null}" agent_tokens_out="${19:-null}"
+  local agent_tokens_cache_read="${20:-null}" agent_tokens_cache_write="${21:-null}"
+
+  local file
+  file="$(git rev-parse --show-toplevel 2>/dev/null)/specs/metrics/cycle-times.yaml"
+  while [ $# -gt 0 ]; do
+    case "$1" in --file) file="$2"; shift 2 ;; *) shift ;; esac
+  done
+
+  {
+    printf -- '---\n'
+    printf -- 'okf_kind: story-metrics\n'
+    printf -- 'okf_version: "0.1"\n'
+    printf -- 'id: %s\n' "$story"
+    printf -- 'epic: %s\n' "${story%%s*}"
+    printf -- 'bcps: %s\n' "$bcps"
+    printf -- 'commit_range: "%s"\n' "$commit_range"
+    printf -- 'source: measured\n'
+    printf -- 'generated_at: %s\n' "$generated_at"
+    printf -- 'generator: scripts/record-cycle-time.sh\n'
+    printf -- '\n'
+    printf -- '# DORA — the four keys (market standard). ⌀ median aggregate.\n'
+    printf -- 'dora:\n'
+    printf -- '  lead_time_for_changes_min: %s   # ⌀ first commit → merge\n' "$lead_min"
+    printf -- '  deployment_frequency: null           # %% populated by e40s05\n'
+    printf -- '  change_failure: null                   # %% populated by e40s05\n'
+    printf -- '  time_to_restore_min: null              # ⌀ populated by e40s05\n'
+    printf -- '\n'
+    printf -- '# Agent code-generation telemetry (GSD-2 style). Σ additive.\n'
+    printf -- 'agent:\n'
+    printf -- '  cost_usd: %s                         # Σ\n' "$agent_cost"
+    printf -- '  tokens:\n'
+    printf -- '    input: %s\n' "$agent_tokens_in"
+    printf -- '    output: %s\n' "$agent_tokens_out"
+    printf -- '    cache_read: %s\n' "$agent_tokens_cache_read"
+    printf -- '    cache_write: %s\n' "$agent_tokens_cache_write"
+    printf -- '    total: %s\n' "$agent_tokens_total"
+    printf -- '  cache_hit_rate_pct: %s               # %%\n' "$agent_cache_hit"
+    printf -- '  compression_savings_pct: %s          # %%\n' "$agent_compression"
+    printf -- '  tool_calls: %s                       # Σ\n' "$agent_tool_calls"
+    printf -- '  api_requests: %s                     # Σ\n' "$agent_api_requests"
+    printf -- '  agent_duration_ms: %s                # Σ\n' "$agent_duration_ms"
+    printf -- '  model: %s                            # •\n' "$agent_model"
+    printf -- '  tier: %s                             # •\n' "$agent_tier"
+    printf -- '  model_downgraded: %s                 # •\n' "$agent_downgraded"
+    printf -- '  skills: %s                           # Σ\n' "$agent_skills"
+    printf -- '\n'
+    printf -- '# Effort (git-derived, idle-stripped, ADDITIVE).\n'
+    printf -- 'effort:\n'
+    printf -- '  effort_hours: %s              # Σ idle-stripped\n' "$eff"
+    printf -- '  idle_threshold_min: 120              # •\n'
+    printf -- '\n'
+    printf -- '# Quality gate. ⌀ median / • static.\n'
+    printf -- 'quality:\n'
+    printf -- '  audit_score_pct: null                 # ⌀\n'
+    printf -- '  coverage_pct: null                    # ⌀\n'
+    printf -- '  tests_passed: null                    # •\n'
+    printf -- '  verify_status: null                   # pass|waived\n'
+    printf -- '  rework_count: null                    # Σ\n'
+    printf -- '\n'
+    printf -- '# Flow (worktree telemetry).\n'
+    printf -- 'flow:\n'
+    printf -- '  merge_duration_ms: null               # ⌀\n'
+    printf -- '  merge_conflicts: null                 # Σ\n'
+    printf -- '  worktree_orphaned: null               # •\n'
+    printf -- '---\n'
+    printf -- '\n'
+    printf -- '# Story metrics — %s\n' "$story"
+    printf -- '\n'
+    printf -- 'Effort derived from git commit history via the git-hours model\n'
+    printf -- '(src: kimmobrunfeldt/git-hours, 120-min idle threshold, 120-min\n'
+    printf -- 'first-commit pad). Lead time is calendar latency (first commit → merge).\n'
+    printf -- '\n'
+    printf -- 'Aggregation tags: Σ additive (sum → total) · ⌀ median/p95 (never sum)\n'
+    printf -- '· %% rate (ratio over window) · • static (identity).\n'
+  } >> "$file"
+}

package/scripts/lib/trace-matrix.py

@@ -0,0 +1,523 @@
+#!/usr/bin/env python3
+# story: e38s01
+# trace-matrix.py — deterministic spec-to-code coverage matrix builder (Python engine).
+# Called by scripts/trace-stories.sh. Not meant to be run standalone without args.
+#
+# Oracle tiers (TEA-inspired):
+#   Tier 1: explicit story tag → confidence high
+#   Tier 2: file-name heuristic match → confidence medium
+#   Tier 3: epic capsule task reference → confidence low
+
+import json, os, re, sys, time
+from pathlib import Path
+from datetime import datetime, timezone
+
+ROOT = Path(sys.argv[1])
+MATRIX_JSON = Path(sys.argv[2])
+TRACE_MD = Path(sys.argv[3])
+OKF_DIR = Path(sys.argv[4])
+STRICT = int(sys.argv[5])
+MODE = sys.argv[6]
+
+# -----------------------------------------------------------------------
+# 1. Parse release-plan.yaml → story inventory
+# -----------------------------------------------------------------------
+def parse_simple_yaml(text: str) -> dict:
+    """Parse flat and one-level-nested YAML including lists of objects."""
+    root: dict = {}
+    # Each stack entry: (indent, container, parent_dict, key_in_parent)
+    stack: list = [(0, root, None, None)]
+    skip_until_indent = None  # skip block scalar continuation lines (| and >)
+    for i, raw in enumerate(text.splitlines()):
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            # Reset block-scalar skip on blank lines
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        
+        # Skip block scalar continuation (| and > in YAML)
+        if skip_until_indent is not None:
+            if indent > skip_until_indent:
+                continue
+            else:
+                skip_until_indent = None
+        
+        # Pop stack until we're at the right nesting level
+        # Don't pop list containers at same indent — sibling items stay in same list
+        while len(stack) > 1:
+            if indent < stack[-1][0]:
+                stack.pop()
+            elif indent == stack[-1][0]:
+                # Same indent: pop dicts (moving to sibling key), keep lists (sibling items)
+                if isinstance(stack[-1][1], list) and stripped.startswith("- "):
+                    break  # stay in same list for next item
+                elif isinstance(stack[-1][1], dict) and stripped.startswith("- "):
+                    # dict at same indent with upcoming list item — convert to list
+                    entry_container = stack[-1][1]
+                    entry_parent = stack[-1][2]
+                    entry_key = stack[-1][3]
+                    if entry_parent is not None and entry_key is not None:
+                        if not isinstance(entry_parent.get(entry_key), list):
+                            entry_parent[entry_key] = []
+                            stack[-1] = (stack[-1][0], entry_parent[entry_key], entry_parent, entry_key)
+                            break
+                    stack.pop()
+                else:
+                    stack.pop()  # other same-indent transitions
+            else:
+                break  # indent > stack indent — staying inside
+        
+        container = stack[-1][1]
+        parent_dict = stack[-1][2]
+        key_in_parent = stack[-1][3]
+        
+        # List item
+        if stripped.startswith("- "):
+            inner = stripped[2:]
+            # Convert dict to list if needed (preserve original indent from dict push)
+            if isinstance(container, dict) and parent_dict is not None and key_in_parent is not None:
+                if not isinstance(parent_dict.get(key_in_parent), list):
+                    orig_indent = stack[-1][0]
+                    parent_dict[key_in_parent] = []
+                    container = parent_dict[key_in_parent]
+                    stack[-1] = (orig_indent, container, parent_dict, key_in_parent)
+            
+            if ":" in inner:
+                k, _, v = inner.partition(":")
+                k = k.strip()
+                v = v.strip()
+                # Detect block scalars in list items too
+                if v in ("|", ">", "|-", ">-", "|+", ">+"):
+                    item = {k: v}
+                    container.append(item)
+                    skip_until_indent = indent
+                    continue
+                item = {k: _yaml_scalar(v) if v else None}
+                container.append(item)
+                if v == "":
+                    stack.append((indent, item, container, k))
+            else:
+                container.append(_yaml_scalar(inner))
+            continue
+        
+        # Key: value
+        if ":" not in stripped:
+            continue
+        key, _, val = stripped.partition(":")
+        key = key.strip()
+        val = val.strip()
+        
+        # Detect block scalars (|, >, |- etc.)
+        if val in ("|", ">", "|-", ">-", "|+", ">+"):
+            if isinstance(container, list) and container:
+                container[-1][key] = val  # store the marker
+            elif isinstance(container, dict):
+                container[key] = val
+            skip_until_indent = indent
+            continue
+        
+        if isinstance(container, list) and container:
+            # Inside a list item dict
+            container[-1][key] = _yaml_scalar(val) if val else None
+            if val == "":
+                nxt = {}
+                container[-1][key] = nxt
+                stack.append((indent, nxt, container[-1], key))
+        elif isinstance(container, dict):
+            if val == "":
+                # Store as dict first; will convert to list if next line is "-"
+                nxt = {}
+                container[key] = nxt
+                stack.append((indent, nxt, container, key))
+            else:
+                container[key] = _yaml_scalar(val)
+    return root
+
+
+def _yaml_scalar(val: str):
+    """Convert a YAML scalar string to Python type."""
+    val = val.strip('"').strip("'")
+    if val in ("true", "false"):
+        return val == "true"
+    if val in ("null", "~", ""):
+        return None
+    try:
+        return int(val)
+    except ValueError:
+        try:
+            return float(val)
+        except ValueError:
+            return val
+
+# Parse release plan for epics/stories
+release_plan_path = ROOT / "specs" / "release-plan.yaml"
+release_text = release_plan_path.read_text(encoding="utf-8")
+release = parse_simple_yaml(release_text)
+
+# Parse execution status
+exec_path = ROOT / "specs" / "execution-status.yaml"
+exec_text = exec_path.read_text(encoding="utf-8")
+exec_status = parse_simple_yaml(exec_text)
+dev_status = exec_status.get("development_status", {})
+
+# -----------------------------------------------------------------------
+# 2. Build story inventory from release-plan.yaml
+# -----------------------------------------------------------------------
+stories: dict[str, dict] = {}
+epics = release.get("epics", [])
+if not isinstance(epics, list):
+    epics = []
+
+for epic in epics:
+    if not isinstance(epic, dict):
+        continue
+    eid = epic.get("id", "")
+    ebcp = epic.get("bcps", 0)
+    etitle = epic.get("title", "")
+    ewsjf = epic.get("wsjf", 0)
+    
+    # Check for capsule_dir with stories
+    capsule_dir = epic.get("capsule_dir", "")
+    if capsule_dir:
+        capsule_path = ROOT / "specs" / capsule_dir / "epic.yaml"
+        if capsule_path.exists():
+            cap_text = capsule_path.read_text(encoding="utf-8")
+            cap = parse_simple_yaml(cap_text)
+            cap_stories = cap.get("stories", [])
+            if isinstance(cap_stories, list):
+                for s in cap_stories:
+                    if isinstance(s, dict):
+                        sid = s.get("id", "")
+                        stories[sid] = {
+                            "id": sid,
+                            "title": s.get("title", ""),
+                            "epic_id": eid,
+                            "epic_title": etitle,
+                            "bcp": s.get("bcp", 0),
+                            "wsjf": float(ewsjf),
+                            "description": s.get("description", "")
+                        }
+    
+    # Also check legacy flat epics (file: epics/eNN-*.yaml patterns)
+    file_key = epic.get("file", "")
+    if file_key and not capsule_dir:
+        legacy_path = ROOT / "specs" / file_key
+        if legacy_path.exists():
+            leg_text = legacy_path.read_text(encoding="utf-8")
+            leg = parse_simple_yaml(leg_text)
+            leg_stories = leg.get("stories", [])
+            if isinstance(leg_stories, list):
+                for s in leg_stories:
+                    if isinstance(s, dict):
+                        sid = s.get("id", "")
+                        stories[sid] = {
+                            "id": sid,
+                            "title": s.get("title", ""),
+                            "epic_id": eid,
+                            "epic_title": etitle,
+                            "bcp": s.get("bcp", 0),
+                            "wsjf": float(ewsjf),
+                            "description": s.get("description", "")
+                        }
+
+# -----------------------------------------------------------------------
+# 3. Grep codebase for story: eNNsNN tags
+# -----------------------------------------------------------------------
+import subprocess
+result = subprocess.run(
+    ["grep", "-rn", "--include=*.md", "--include=*.sh", "--include=*.py",
+     "--include=*.js", "--include=*.ts", "--include=*.yaml", "--include=*.yml",
+     "-E", r"story:\s*e\d{2}s\d{2}", str(ROOT)],
+    capture_output=True, text=True, cwd=str(ROOT)
+)
+
+tag_inventory: list[dict] = []
+for line in result.stdout.splitlines():
+    m = re.match(r"^(.+?):(\d+):(.*story:\s*(e\d{2}s\d{2}).*)$", line)
+    if m:
+        fpath = m.group(1)
+        fline = int(m.group(2))
+        sid = m.group(4)
+        # Make path relative to repo root
+        try:
+            fpath = str(Path(fpath).relative_to(ROOT))
+        except ValueError:
+            pass
+        tag_inventory.append({"file": fpath, "line": fline, "story_id": sid})
+
+# -----------------------------------------------------------------------
+# 4. Resolve each story through oracle tiers
+# -----------------------------------------------------------------------
+# Tier 1: explicit story tag (already captured above)
+# Tier 2: file-name heuristic match
+# Tier 3: epic capsule task reference
+
+# Collect all file basenames for heuristic matching
+all_files = []
+for root_dir, dirs, files in os.walk(str(ROOT)):
+    # Skip generated/artifacts
+    dirs[:] = [d for d in dirs if d not in (".git", "node_modules", ".cursor")]
+    for f in files:
+        all_files.append(str(Path(root_dir, f).relative_to(ROOT)))
+
+def slugify(text: str) -> str:
+    """Convert title to a kebab-case slug."""
+    text = re.sub(r"[^a-zA-Z0-9\s-]", "", text.lower())
+    return re.sub(r"\s+", "-", text.strip())
+
+def heuristic_match(story_title: str, file_path: str) -> bool:
+    """Check if file-path contains keywords from story title."""
+    slug = slugify(story_title)
+    words = slug.split("-")
+    fname = Path(file_path).stem.lower()
+    # Must match at least 2 significant keywords
+    sig_words = [w for w in words if len(w) > 2]
+    if len(sig_words) < 2:
+        sig_words = words
+    matches = sum(1 for w in sig_words if w in fname)
+    return matches >= min(2, len(sig_words))
+
+def find_task_references(story_id: str) -> list[dict]:
+    """Find epic capsule task YAML files that reference this story's verify paths."""
+    refs = []
+    epics_dir = ROOT / "specs" / "epics"
+    if not epics_dir.exists():
+        return refs
+    for task_yaml in epics_dir.rglob("*tasks.yaml"):
+        try:
+            content = task_yaml.read_text(encoding="utf-8")
+            if f"story_id: {story_id}" in content or story_id in content:
+                rel = str(task_yaml.relative_to(ROOT))
+                refs.append({"file": rel, "type": "task_yaml"})
+        except Exception:
+            pass
+    return refs
+
+# Build the coverage matrix
+matrix_stories = []
+tagged_sids = set(t["story_id"] for t in tag_inventory)
+tag_index: dict[str, list] = {}
+for t in tag_inventory:
+    tag_index.setdefault(t["story_id"], []).append(t)
+
+dark_stories = []
+orphan_tags = []
+stale_tags = []
+
+for sid, sinfo in sorted(stories.items()):
+    links = []
+    sid_status = dev_status.get(sid, "backlog")
+    
+    # Tier 1: explicit tags
+    if sid in tag_index:
+        for t in tag_index[sid]:
+            links.append({"file": t["file"], "line": t["line"], "confidence": "high", "method": "explicit_tag"})
+    
+    # Tier 2: file-name heuristic
+    for fpath in all_files:
+        if heuristic_match(sinfo["title"], fpath):
+            # Don't add if already covered by explicit tag
+            if not any(l["file"] == fpath for l in links):
+                links.append({"file": fpath, "line": 0, "confidence": "medium", "method": "file_heuristic"})
+    
+    # Tier 3: task references
+    task_refs = find_task_references(sid)
+    for tr in task_refs:
+        existing_files = {l["file"] for l in links}
+        if tr["file"] not in existing_files:
+            links.append({"file": tr["file"], "line": 0, "confidence": "low", "method": "task_reference"})
+    
+    matrix_stories.append({
+        "id": sid,
+        "title": sinfo["title"],
+        "epic_id": sinfo["epic_id"],
+        "epic_title": sinfo["epic_title"],
+        "bcp": sinfo["bcp"],
+        "wsjf": sinfo["wsjf"],
+        "status": sid_status,
+        "links": links,
+        "link_count": len(links)
+    })
+    
+    # Classify findings
+    if len(links) == 0 and sid_status != "backlog":
+        dark_stories.append(sid)
+
+# Check for orphan tags (tag in code, not in story inventory)
+for sid in sorted(tagged_sids):
+    if sid not in stories:
+        orphan_tags.append(sid)
+
+# Check for stale tags (story done, tag still in code)
+for sid in sorted(tagged_sids):
+    if sid in stories and dev_status.get(sid) == "done":
+        stale_tags.append(sid)
+
+# -----------------------------------------------------------------------
+# 5. Emit matrix JSON
+# -----------------------------------------------------------------------
+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.parent.mkdir(parents=True, exist_ok=True)
+MATRIX_JSON.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
+
+# -----------------------------------------------------------------------
+# 6. Emit TRACEABILITY_LATEST.md (human-readable report)
+# -----------------------------------------------------------------------
+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.parent.mkdir(parents=True, exist_ok=True)
+TRACE_MD.write_text("\n".join(lines), encoding="utf-8")
+
+# -----------------------------------------------------------------------
+# 7. Emit OKF bundle (specs/codebase-wiki/)
+# -----------------------------------------------------------------------
+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")
+
+# -----------------------------------------------------------------------
+# 8. Strict mode — exit non-zero on P0 uncovered
+# -----------------------------------------------------------------------
+if STRICT:
+    # P0 = top WSJF quartile among stories
+    if matrix_stories:
+        wsjf_sorted = sorted(set(s["wsjf"] for s in matrix_stories), reverse=True)
+        cutoff_idx = max(0, len(wsjf_sorted) // 4 - 1)
+        p0_threshold = wsjf_sorted[cutoff_idx] if cutoff_idx < len(wsjf_sorted) else 0
+        
+        uncovered_p0 = []
+        for s in matrix_stories:
+            if s["wsjf"] >= p0_threshold and len(s["links"]) == 0:
+                uncovered_p0.append(s["id"])
+        
+        if uncovered_p0:
+            print(f"trace-stories.sh: STRICT FAIL — P0 stories with 0% coverage: {', '.join(uncovered_p0)}", file=sys.stderr)
+            sys.exit(2)
+
+sys.exit(0)