bigpowers 2.58.1 → 2.58.3

package/scripts/lib/blind-spots.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""story: e38s04 — TEA-inspired heuristic blind-spot detector (Python engine).
+
+Reads execution-status.yaml + traceability-matrix.json, runs 6 structural
+quality checks, and emits specs/blind-spots.json.
+
+Usage: called by scripts/check-blind-spots.sh with positional args:
+  python3 scripts/lib/blind-spots.py <repo_root> <blind_spots_json>
+      <exec_status_yaml> <matrix_json> <verifications_dir> <epics_dir>
+"""
+
+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] = []
+
+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)
+
+matrix_data: dict | None = None
+if MATRIX_JSON.exists():
+    matrix_data = json.loads(MATRIX_JSON.read_text(encoding="utf-8"))
+
+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)
+
+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)))
+
+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 exists 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 the tagged files: {', '.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 from files 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. If it's a shared utility, this is acceptable."
+        })
+
+# Check F: bootstrap-testless
+for sid in sorted(dev_status.keys()):
+    if dev_status[sid] in ("active",):
+        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])}"
+                })
+
+# Deduplicate
+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/git-hours.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# story: e40s04
+# git-hours.sh — deterministic, additive git-hours effort engine.
+# Source this file in scripts that compute effort from commit history.
+# Requires: IDLE_SECONDS, PAD_SECONDS, ROOT set before sourcing.
+#
+# Model (kimmobrunfeldt/git-hours):
+#   * commits sorted by author-date across the WHOLE range;
+#   * gap < IDLE  -> real elapsed time, credited to later commit's story;
+#   * gap >= IDLE -> session boundary: credit PAD to later commit's story;
+#   * first commit never padded.
+#
+# partition() emits per-story TSV: story \t effort_hours \t commits \t first_epoch \t last_epoch
+# whole_range_hours() emits a single float: whole-range effort (additivity oracle)
+
+partition() {
+  local range="$1" key="$2"
+  git -C "$ROOT" log --no-merges "$range" \
+      --pretty=format:"%at%x1f%H%x1f%(trailers:key=${key},valueonly,separator=%x2C)" \
+    | sort -n \
+    | awk -F '\x1f' -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
+        {
+          ts = $1 + 0; story = $3
+          gsub(/[[:space:]]/, "", story)
+          if (story == "") story = "unattributed"
+          count[story]++; seen[story] = 1
+          if (NR > 1) {
+            gap = ts - prev
+            if (gap < 0) gap = 0
+            if (gap < IDLE) eff[story] += gap
+            else            eff[story] += PAD
+          }
+          if (!(story in first)) first[story] = ts
+          last[story] = ts; prev = ts
+        }
+        END {
+          for (s in seen)
+            printf "%s\t%.4f\t%d\t%d\t%d\n", s, eff[s] / 3600.0, count[s], first[s], last[s]
+        }' \
+    | sort
+}
+
+whole_range_hours() {
+  local range="$1"
+  git -C "$ROOT" log --no-merges "$range" --pretty=format:"%at" \
+    | sort -n \
+    | awk -v IDLE="$IDLE_SECONDS" -v PAD="$PAD_SECONDS" '
+        { ts=$1+0; if(NR>1){gap=ts-prev; if(gap<0)gap=0; if(gap<IDLE)e+=gap; else e+=PAD} prev=ts }
+        END { printf "%.4f\n", e/3600.0 }'
+}

package/scripts/lib/trace-stories.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""story: e38s01 — deterministic spec-to-code coverage matrix builder (Python engine).
+
+Parses release-plan.yaml + execution-status.yaml, greps codebase for story tags,
+builds oracle-tiered coverage matrix, emits JSON + markdown + OKF wiki.
+
+Usage: called by scripts/trace-stories.sh with positional args:
+  python3 scripts/lib/trace-stories.py <repo_root> <matrix_json> <trace_md>
+      <okf_dir> <strict> <mode>
+
+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, subprocess, sys
+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 = {}
+    stack: list = [(0, root, None, None)]
+    skip_until_indent = None
+    for i, raw in enumerate(text.splitlines()):
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        if skip_until_indent is not None:
+            if indent > skip_until_indent:
+                continue
+            else:
+                skip_until_indent = None
+        while len(stack) > 1:
+            if indent < stack[-1][0]:
+                stack.pop()
+            elif indent == stack[-1][0]:
+                if isinstance(stack[-1][1], list) and stripped.startswith("- "):
+                    break
+                elif isinstance(stack[-1][1], dict) and stripped.startswith("- "):
+                    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()
+            else:
+                break
+        container = stack[-1][1]
+        parent_dict = stack[-1][2]
+        key_in_parent = stack[-1][3]
+        if stripped.startswith("- "):
+            inner = stripped[2:]
+            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()
+                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
+        if ":" not in stripped:
+            continue
+        key, _, val = stripped.partition(":")
+        key = key.strip(); val = val.strip()
+        if val in ("|", ">", "|-", ">-", "|+", ">+"):
+            if isinstance(container, list) and container:
+                container[-1][key] = val
+            elif isinstance(container, dict):
+                container[key] = val
+            skip_until_indent = indent; continue
+        if isinstance(container, list) and container:
+            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 == "":
+                nxt = {}; container[key] = nxt
+                stack.append((indent, nxt, container, key))
+            else:
+                container[key] = _yaml_scalar(val)
+    return root
+
+def _yaml_scalar(val: str):
+    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
+
+release_text = (ROOT / "specs" / "release-plan.yaml").read_text(encoding="utf-8")
+release = parse_simple_yaml(release_text)
+exec_text = (ROOT / "specs" / "execution-status.yaml").read_text(encoding="utf-8")
+exec_status = parse_simple_yaml(exec_text)
+dev_status = exec_status.get("development_status", {})
+
+# -----------------------------------------------------------------------
+# 2. Build story inventory
+# -----------------------------------------------------------------------
+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)
+    capsule_dir = epic.get("capsule_dir", "")
+    if capsule_dir:
+        capsule_path = ROOT / "specs" / capsule_dir / "epic.yaml"
+        if capsule_path.exists():
+            cap = parse_simple_yaml(capsule_path.read_text(encoding="utf-8"))
+            for s in cap.get("stories", []) or []:
+                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", "")}
+    file_key = epic.get("file", "")
+    if file_key and not capsule_dir:
+        legacy_path = ROOT / "specs" / file_key
+        if legacy_path.exists():
+            leg = parse_simple_yaml(legacy_path.read_text(encoding="utf-8"))
+            for s in leg.get("stories", []) or []:
+                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 tags
+# -----------------------------------------------------------------------
+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] = []
+tagged_sids: set[str] = set()
+tag_index: dict[str, list] = {}
+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)
+        try: fpath = str(Path(fpath).relative_to(ROOT))
+        except ValueError: pass
+        tag_inventory.append({"file": fpath, "line": fline, "story_id": sid})
+        tagged_sids.add(sid)
+        tag_index.setdefault(sid, []).append({"file": fpath, "line": fline})
+
+# -----------------------------------------------------------------------
+# 4. Oracle tiers
+# -----------------------------------------------------------------------
+all_files = []
+for root_dir, dirs, files in os.walk(str(ROOT)):
+    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:
+    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:
+    slug = slugify(story_title)
+    words = slug.split("-")
+    fname = Path(file_path).stem.lower()
+    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]:
+    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:
+                refs.append({"file": str(task_yaml.relative_to(ROOT)), "type": "task_yaml"})
+        except Exception: pass
+    return refs
+
+matrix_stories = []
+dark_stories = []
+for sid, sinfo in sorted(stories.items()):
+    links = []
+    sid_status = dev_status.get(sid, "backlog")
+    if sid in tag_index:
+        for t in tag_index[sid]:
+            links.append({"file": t["file"], "line": t["line"], "confidence": "high", "method": "explicit_tag"})
+    for fpath in all_files:
+        if heuristic_match(sinfo["title"], fpath):
+            if not any(l["file"] == fpath for l in links):
+                links.append({"file": fpath, "line": 0, "confidence": "medium", "method": "file_heuristic"})
+    for tr in find_task_references(sid):
+        existing = {l["file"] for l in links}
+        if tr["file"] not in existing:
+            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)
+    })
+    if len(links) == 0 and sid_status != "backlog":
+        dark_stories.append(sid)
+
+orphan_tags = [sid for sid in sorted(tagged_sids) if sid not in stories]
+stale_tags = [sid for sid in sorted(tagged_sids) if sid in stories and dev_status.get(sid) == "done"]
+
+# -----------------------------------------------------------------------
+# 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
+# -----------------------------------------------------------------------
+lines = ["# Traceability Matrix", "",
+    f"**Generated:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}",
+    f"**Total stories:** {len(stories)}",
+    f"**Tagged stories:** {len(tagged_sids & set(stories.keys()))}",
+    f"**Dark stories:** {len(dark_stories)}",
+    f"**Orphan tags:** {len(orphan_tags)}",
+    f"**Stale tags:** {len(stale_tags)}",
+    "", "## Oracle Stats", "",
+    f"- **High** (explicit tag): {matrix['summary']['oracle_stats']['high']}",
+    f"- **Medium** (file heuristic): {matrix['summary']['oracle_stats']['medium']}",
+    f"- **Low** (task reference): {matrix['summary']['oracle_stats']['low']}",
+    "", "## Story Coverage", "",
+    "| Story | Title | Epic | BCP | WSJF | Status | Links |",
+    "|-------|-------|------|-----|------|--------|-------|"]
+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("")
+if dark_stories:
+    lines.append("## Dark Stories (no code links)\n")
+    for ds in dark_stories:
+        si = stories.get(ds, {})
+        lines.append(f"- **{ds}**: {si.get('title', 'Unknown')} (status: {dev_status.get(ds, '?')})")
+    lines.append("")
+if orphan_tags:
+    lines.append("## Orphan Tags (tag in code, no matching story)\n")
+    for ot in orphan_tags: lines.append(f"- `{ot}`")
+    lines.append("")
+if stale_tags:
+    lines.append("## Stale Tags (story done, tag still in code)\n")
+    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)
+idx_lines = ["---", "type: Index",
+    f"generated_at: {datetime.now(timezone.utc).isoformat()}",
+    f"total_concepts: {len(stories)}", "---", "",
+    "# Codebase Wiki — Story Traceability", "",
+    "Auto-generated OKF bundle from trace-stories.sh.", "",
+    "| Story | Title | Confidence | Links |",
+    "|-------|-------|------------|-------|"]
+for s in matrix_stories:
+    confs = {l["confidence"] for l in s["links"]}
+    mc = "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]} | {mc} | {s['link_count']} |")
+idx_lines.append("")
+(OKF_DIR / "index.md").write_text("\n".join(idx_lines), encoding="utf-8")
+for s in matrix_stories:
+    concept = ["---", f"type: Story", f"id: {s['id']}", f"epic: {s['epic_id']}",
+        f"bcps: {s['bcp']}", f"wsjf: {s['wsjf']}",
+        f"implementation_status: {s['status']}"]
+    max_confs = {l["confidence"] for l in s["links"]}
+    conf = "high" if "high" in max_confs else ("medium" if "medium" in max_confs else ("low" if max_confs else "none"))
+    concept.extend([f"coverage_status: {'covered' if s['link_count'] > 0 else 'dark'}",
+        f"confidence: {conf}", "links:"])
+    for l in s["links"]:
+        concept.extend([f"  - file: {l['file']}", f"    line: {l['line']}",
+            f"    confidence: {l['confidence']}", f"    method: {l['method']}"])
+    concept.extend(["---", "", f"# {s['id']}: {s['title']}", "",
+        f"**Epic:** {s['epic_id']} — {s.get('epic_title', 'Unknown')}",
+        f"**Status:** {s['status']}",
+        f"**BCP:** {s['bcp']} | **WSJF:** {s['wsjf']}", ""])
+    if s["links"]:
+        concept.append("## Implemented In\n")
+        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
+# -----------------------------------------------------------------------
+if STRICT:
+    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 = [s["id"] for s in matrix_stories if s["wsjf"] >= p0_threshold and len(s["links"]) == 0]
+        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)