bigpowers 2.73.7 → 2.73.9

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.7",
+  "version": "2.73.9",
   "description": "75 skills — 73 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,17 @@
+## [2.73.9](https://github.com/danielvm-git/bigpowers/compare/v2.73.8...v2.73.9) (2026-07-07)
+
+
+### Bug Fixes
+
+* **gate-trace:** split trace-matrix.py under 300-line cap ([ece8389](https://github.com/danielvm-git/bigpowers/commit/ece8389c815614d116d91b57dda9c67f6133caaf))
+
+## [2.73.8](https://github.com/danielvm-git/bigpowers/compare/v2.73.7...v2.73.8) (2026-07-07)
+
+
+### Bug Fixes
+
+* **audit-code:** split audit-compliance.sh into lib modules under 300-line cap ([#63](https://github.com/danielvm-git/bigpowers/issues/63)) ([7d5ea6e](https://github.com/danielvm-git/bigpowers/commit/7d5ea6e0f0c992f26b493b3843ede886770eed6f))
+
 ## [2.73.7](https://github.com/danielvm-git/bigpowers/compare/v2.73.6...v2.73.7) (2026-07-07)
 
 

package/CONVENTIONS.md

@@ -291,13 +291,12 @@ window. The following files are documented exceptions:
 
 | File | Lines | Rationale | Review date |
 |------|-------|-----------|-------------|
-| `scripts/lib/trace-matrix.py` | 523 | Traceability matrix engine: tag scanning, oracle-confidence scoring, and JSON/markdown emission share tightly-coupled dataclasses and a single pass over the story index. Splitting would fragment the matrix model across modules. Split candidate for a future plan-refactor (BUG-2026-07-04-filesize-gate-python-blindspot); documented meanwhile. Also exceeds the 500-line cap. | 2026-10-01 |
-| `scripts/lib/trace-stories.py` | 301 | Story-tag discovery + file-to-story mapping; the phases share regex state and a common file walk. One line over cap; monitor for split alongside trace-matrix.py. | 2026-10-01 |
 | `scripts/audit-compliance.sh` | 300 | Gherkin harness with embedded judge logic and waiver subsystem; splitting the judge loop from the reporting layer would require fragile state-passing. At the 300-line cap; monitor. | 2026-10-01 |
 
 **Note:** `scripts/trace-stories.sh` was refactored from a 613-line monolith into a
-69-line orchestrator delegating to the `scripts/lib/*.py` engine above — it is no
-longer an exception. The prior exception row (and its waiver) referenced a file
-that no longer exists; see BUG-2026-07-04-filesize-gate-python-blindspot.
+69-line orchestrator delegating to `scripts/lib/trace-stories.py`. `scripts/lib/trace-matrix.py`
+was split into `simple_yaml.py` + `trace_renderer.py` (252 lines); see
+BUG-2026-07-06-gate-trace-matrix-oversized. Prior exception rows for trace-matrix.py
+and trace-stories.py are removed — both are now under the 300-line cap.
 
 Any new exception requires an entry in this table with rationale and a review date.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.73.7",
+  "version": "2.73.9",
   "description": "73 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

@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 # audit-compliance.sh — Agentic Gherkin Compliance Harness (LLM-Judge Upgrade)
-show_help() {
+
+_LIB="$(dirname "${BASH_SOURCE[0]}")/lib"
+source "$_LIB/audit-compliance-runner.sh"
+source "$_LIB/audit-compliance-report.sh"
+
+audit_show_help() {
   cat <<EOF
 Usage: bash scripts/audit-compliance.sh [feature-file|directory] [options]
 
@@ -15,320 +20,45 @@ If a directory is provided, all .feature files in that directory will be process
 EOF
 }
 
-# --- Arguments Parsing ---
 DRY_RUN=false
 SCENARIO_FILTER=""
 JUDGE="binary"
 MODEL=""
 INPUTS=()
+TOTAL_GLOBAL_PASS=0
+TOTAL_GLOBAL_FAIL=0
+TOTAL_GLOBAL_WAIVED=0
+TOTAL_GLOBAL_EXPIRED=0
+SCORE=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --help)
-      show_help
-      exit 0
-      ;;
-    --dry-run)
-      DRY_RUN=true
-      shift
-      ;;
-    --scenario)
-      SCENARIO_FILTER="$2"
-      shift 2
-      ;;
-    --judge)
-      JUDGE="$2"
-      shift 2
-      ;;
-    --model)
-      MODEL="$2"
-      shift 2
-      ;;
-    -*)
-      echo "Unknown option: $1"
-      show_help
-      exit 1
-      ;;
-    *)
-      INPUTS+=("$1")
-      shift
-      ;;
+    --help) audit_show_help; exit 0 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --scenario) SCENARIO_FILTER="$2"; shift 2 ;;
+    --judge) JUDGE="$2"; shift 2 ;;
+    --model) MODEL="$2"; shift 2 ;;
+    -*) echo "Unknown option: $1"; audit_show_help; exit 1 ;;
+    *) INPUTS+=("$1"); shift ;;
   esac
 done
 
 if [[ ${#INPUTS[@]} -eq 0 ]]; then
   echo "Error: No feature file or directory specified."
-  show_help
+  audit_show_help
   exit 1
 fi
 
-# --- Global Stats ---
-TOTAL_GLOBAL_PASS=0
-TOTAL_GLOBAL_FAIL=0
-TOTAL_GLOBAL_WAIVED=0
-TOTAL_GLOBAL_EXPIRED=0
-
-# --- Waiver Subsystem ---
-# Sourced from scripts/lib/waiver-utils.sh — provides has_waiver().
-WAIVER_FILE="specs/verifications/waivers.yaml"
-true && source "$(dirname "${BASH_SOURCE[0]}")/lib/waiver-utils.sh"
-
-# --- Judging Logic ---
-
-judge_with_gemini() {
-  local step="$1"
-  local feature_name="$2"
-  local scenario_name="$3"
-  local evidence="$4"
-  local report_file="$5"
-
-  echo "    [JUDGE] Sending evidence to Gemini CLI..."
-  
-  local prompt="You are the Master Test Architect judging a compliance audit.
-Benchmark Feature: $feature_name
-Scenario: $scenario_name
-Compliance Step: $step
-
-Evidence gathered from the codebase:
----
-$evidence
----
-
-Based on the benchmark principles, does this evidence demonstrate compliance?
-Respond strictly in the following format:
-VERDICT: [PASS/FAIL]
-RATIONALE: [One sentence explanation]"
-
-  local model_output
-  local gemini_cmd="gemini --approval-mode plan"
-  if [[ -n "$MODEL" ]]; then
-    gemini_cmd="$gemini_cmd -m $MODEL"
-  fi
-  
-  model_output=$($gemini_cmd -p "$prompt" 2>&1)
-  local exit_code=$?
-
-  if [[ $exit_code -eq 0 ]]; then
-    local verdict
-    verdict=$(echo "$model_output" | grep "VERDICT:" | cut -d' ' -f2)
-    local rationale
-    rationale=$(echo "$model_output" | grep "RATIONALE:" | cut -d' ' -f2-)
-
-    if [[ "$verdict" == "PASS" ]]; then
-      echo "      Result: PASS"
-      echo "- [x] $step (PASS) - $rationale" >> "$report_file"
-      return 0
-    else
-      echo "      Result: FAIL"
-      echo "- [ ] $step (FAIL) - $rationale" >> "$report_file"
-      return 1
-    fi
-  else
-    echo "      Result: ERROR (Gemini CLI failed)"
-    echo "- [ ] $step (ERROR) - Gemini CLI exit code $exit_code. Output: $model_output" >> "$report_file"
-    return 1
-  fi
-}
-
-
-
-# --- Core Execution ---
-
-process_step() {
-  local step="$1"
-  local feature_name="$2"
-  local scenario_name="$3"
-  local report_file="$4"
-  echo "    [STEP] $step"
-
-  if [[ "$DRY_RUN" == "true" ]]; then
-    return 0
-  fi
-
-  local sanitized_step
-  sanitized_step=$(echo "$step" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  local step_script="specs/verifications/steps/${sanitized_step}.sh"
-
-  if [[ -f "$step_script" ]]; then
-    echo "    [EXEC] Gathering evidence: $step_script"
-    local evidence
-    evidence=$(bash "$step_script" 2>&1)
-    local exit_code=$?
-
-    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
-      # 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
-      has_waiver "$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
-}
-
-run_audit_file() {
-  local FEATURE_FILE="$1"
-  echo "------------------------------------------------------------"
-  echo "FEATURE: $FEATURE_FILE"
-  
-  local REPORT_FILE="specs/verifications/reports/audit-$(basename "$FEATURE_FILE" .feature)-$(date +%Y%m%d-%H%M%S).md"
-  mkdir -p specs/verifications/reports
-
-  echo "# Audit Report: $FEATURE_FILE" > "$REPORT_FILE"
-  echo "Date: $(date)" >> "$REPORT_FILE"
-  echo "Mode: Autonomous Verification (Judge: $JUDGE)" >> "$REPORT_FILE"
-  echo "" >> "$REPORT_FILE"
-
-  local TOTAL_PASS=0
-  local TOTAL_FAIL=0
-  local CURRENT_FEATURE=""
-  local CURRENT_SCENARIO=""
-  local IN_SCENARIO=false
-
-  while IFS= read -r line; do
-    line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-    
-    if [[ "$line" =~ ^Feature: ]]; then
-      CURRENT_FEATURE="${line#Feature: }"
-      echo "FEATURE: $CURRENT_FEATURE"
-      echo "## Feature: $CURRENT_FEATURE" >> "$REPORT_FILE"
-    elif [[ "$line" =~ ^Scenario: ]]; then
-      CURRENT_SCENARIO="${line#Scenario: }"
-      if [[ -n "$SCENARIO_FILTER" && "$CURRENT_SCENARIO" != "$SCENARIO_FILTER" ]]; then
-        IN_SCENARIO=false
-        continue
-      fi
-      IN_SCENARIO=true
-      echo "  SCENARIO: $CURRENT_SCENARIO"
-      echo "### Scenario: $CURRENT_SCENARIO" >> "$REPORT_FILE"
-    elif [[ "$line" =~ ^(Given|When|Then|And|But)\  ]]; then
-      if [[ "$IN_SCENARIO" == "true" ]]; 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++))
-        fi
-      fi
-    fi
-  done < "$FEATURE_FILE"
-
-  echo ""
-  echo "File Summary: PASS: $TOTAL_PASS, FAIL: $TOTAL_FAIL"
-  echo "Report saved to: $REPORT_FILE"
-}
-
-# --- Main Execution ---
 for input in "${INPUTS[@]}"; do
   if [[ -d "$input" ]]; then
     for f in "$input"/*.feature; do
-      if [[ -f "$f" ]]; then
-        run_audit_file "$f"
-      fi
+      [[ -f "$f" ]] && audit_run_file "$f"
     done
   elif [[ -f "$input" ]]; then
-    run_audit_file "$input"
+    audit_run_file "$input"
   else
     echo "Warning: Input not found: $input"
   fi
 done
 
-echo "============================================================"
-echo "Global Audit Summary:"
-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
-
-# ── OKF verification-report (e45s02) ────────────────────────────────────
-OKF_DIR="specs/verifications/reports"
-mkdir -p "$OKF_DIR"
-OKF_FILE="$OKF_DIR/audit-$(date +%Y-%m-%d).okf.md"
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-GIT_COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
-GATE=$(if [[ $SCORE -ge 94 ]]; then echo "pass"; else echo "fail"; fi)
-
-cat > "$OKF_FILE" << OKF_EOF
----
-okf_kind: verification-report
-okf_version: "0.1"
-score: ${SCORE}
-gate_status: "${GATE}"
-threshold: 94
-total_pass: ${TOTAL_GLOBAL_PASS}
-total_fail: ${TOTAL_GLOBAL_FAIL}
-total_waived: ${TOTAL_GLOBAL_WAIVED}
-generated_by: scripts/audit-compliance.sh
-generated_at: "${TIMESTAMP}"
-git_commit: "${GIT_COMMIT}"
----
-
-# Compliance Audit — $(date +%Y-%m-%d)
-
-**Score:** ${SCORE}% (${TOTAL_GLOBAL_PASS}/${TOTAL_GLOBAL_ALL} passed, ${TOTAL_GLOBAL_WAIVED} waived)
-**Gate:** ${GATE} | **Threshold:** 94%
-
-See \`specs/verifications/reports/audit-*.md\` for detailed step-by-step reports.
-OKF_EOF
-
-echo "OKF report: $OKF_FILE"
-
-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
-else
-  echo "  GATE: FAIL (below 94%)"
-  exit 1
-fi
+audit_print_summary_and_exit

package/scripts/lib/audit-compliance-judge.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# story: e45s02
+# Gemini LLM judge for audit-compliance.sh
+
+if [ -n "${AUDIT_COMPLIANCE_JUDGE_LOADED:-}" ]; then return 0; fi
+AUDIT_COMPLIANCE_JUDGE_LOADED=1
+
+audit_judge_with_gemini() {
+  local step="$1" feature_name="$2" scenario_name="$3" evidence="$4" report_file="$5"
+  local prompt model_output gemini_cmd exit_code verdict rationale
+
+  echo "    [JUDGE] Sending evidence to Gemini CLI..."
+
+  prompt="You are the Master Test Architect judging a compliance audit.
+Benchmark Feature: $feature_name
+Scenario: $scenario_name
+Compliance Step: $step
+
+Evidence gathered from the codebase:
+---
+$evidence
+---
+
+Based on the benchmark principles, does this evidence demonstrate compliance?
+Respond strictly in the following format:
+VERDICT: [PASS/FAIL]
+RATIONALE: [One sentence explanation]"
+
+  gemini_cmd="gemini --approval-mode plan"
+  [[ -n "$MODEL" ]] && gemini_cmd="$gemini_cmd -m $MODEL"
+
+  model_output=$($gemini_cmd -p "$prompt" 2>&1)
+  exit_code=$?
+
+  if [[ $exit_code -eq 0 ]]; then
+    verdict=$(echo "$model_output" | grep "VERDICT:" | cut -d' ' -f2)
+    rationale=$(echo "$model_output" | grep "RATIONALE:" | cut -d' ' -f2-)
+    if [[ "$verdict" == "PASS" ]]; then
+      echo "      Result: PASS"
+      echo "- [x] $step (PASS) - $rationale" >> "$report_file"
+      return 0
+    fi
+    echo "      Result: FAIL"
+    echo "- [ ] $step (FAIL) - $rationale" >> "$report_file"
+    return 1
+  fi
+
+  echo "      Result: ERROR (Gemini CLI failed)"
+  echo "- [ ] $step (ERROR) - Gemini CLI exit code $exit_code. Output: $model_output" >> "$report_file"
+  return 1
+}

package/scripts/lib/audit-compliance-report.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# story: e45s02
+# OKF report and gate verdict for audit-compliance.sh
+
+if [ -n "${AUDIT_COMPLIANCE_REPORT_LOADED:-}" ]; then return 0; fi
+AUDIT_COMPLIANCE_REPORT_LOADED=1
+
+audit_write_okf_report() {
+  local OKF_DIR OKF_FILE TIMESTAMP GIT_COMMIT GATE TOTAL_GLOBAL_ALL
+
+  TOTAL_GLOBAL_ALL=$((TOTAL_GLOBAL_PASS + TOTAL_GLOBAL_FAIL))
+  if [[ $TOTAL_GLOBAL_ALL -gt 0 ]]; then
+    SCORE=$(awk "BEGIN { printf \"%d\", $TOTAL_GLOBAL_PASS * 100 / $TOTAL_GLOBAL_ALL }")
+  else
+    SCORE=0
+  fi
+
+  OKF_DIR="specs/verifications/reports"
+  mkdir -p "$OKF_DIR"
+  OKF_FILE="$OKF_DIR/audit-$(date +%Y-%m-%d).okf.md"
+  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  GIT_COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+  GATE=$(if [[ $SCORE -ge 94 ]]; then echo "pass"; else echo "fail"; fi)
+
+  cat > "$OKF_FILE" << OKF_EOF
+---
+okf_kind: verification-report
+okf_version: "0.1"
+score: ${SCORE}
+gate_status: "${GATE}"
+threshold: 94
+total_pass: ${TOTAL_GLOBAL_PASS}
+total_fail: ${TOTAL_GLOBAL_FAIL}
+total_waived: ${TOTAL_GLOBAL_WAIVED}
+generated_by: scripts/audit-compliance.sh
+generated_at: "${TIMESTAMP}"
+git_commit: "${GIT_COMMIT}"
+---
+
+# Compliance Audit — $(date +%Y-%m-%d)
+
+**Score:** ${SCORE}% (${TOTAL_GLOBAL_PASS}/${TOTAL_GLOBAL_ALL} passed, ${TOTAL_GLOBAL_WAIVED} waived)
+**Gate:** ${GATE} | **Threshold:** 94%
+
+See \`specs/verifications/reports/audit-*.md\` for detailed step-by-step reports.
+OKF_EOF
+
+  echo "OKF report: $OKF_FILE"
+}
+
+audit_print_summary_and_exit() {
+  local TOTAL_GLOBAL_ALL=$((TOTAL_GLOBAL_PASS + TOTAL_GLOBAL_FAIL))
+
+  echo "============================================================"
+  echo "Global Audit Summary:"
+  echo "  TOTAL PASS:   $TOTAL_GLOBAL_PASS"
+  echo "  TOTAL FAIL:   $TOTAL_GLOBAL_FAIL"
+  echo "  TOTAL WAIVED: $TOTAL_GLOBAL_WAIVED  (excluded from denominator)"
+  [[ $TOTAL_GLOBAL_EXPIRED -gt 0 ]] && echo "  EXPIRED WAIVERS: $TOTAL_GLOBAL_EXPIRED (counted as FAIL)"
+
+  audit_write_okf_report
+
+  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
+  fi
+  echo "  GATE: FAIL (below 94%)"
+  exit 1
+}

package/scripts/lib/audit-compliance-runner.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# story: e45s02
+# Feature-file runner for audit-compliance.sh
+
+if [ -n "${AUDIT_COMPLIANCE_RUNNER_LOADED:-}" ]; then return 0; fi
+AUDIT_COMPLIANCE_RUNNER_LOADED=1
+
+source "$(dirname "${BASH_SOURCE[0]}")/audit-compliance-judge.sh"
+WAIVER_FILE="specs/verifications/waivers.yaml"
+true && source "$(dirname "${BASH_SOURCE[0]}")/waiver-utils.sh"
+
+audit_process_step() {
+  local step="$1" feature_name="$2" scenario_name="$3" report_file="$4"
+  local sanitized_step step_script evidence exit_code waiver_code
+
+  echo "    [STEP] $step"
+  [[ "$DRY_RUN" == "true" ]] && return 0
+
+  sanitized_step=$(echo "$step" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  step_script="specs/verifications/steps/${sanitized_step}.sh"
+
+  if [[ ! -f "$step_script" ]]; then
+    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
+
+  echo "    [EXEC] Gathering evidence: $step_script"
+  evidence=$(bash "$step_script" 2>&1)
+  exit_code=$?
+
+  if [[ "$JUDGE" == "gemini" ]]; then
+    audit_judge_with_gemini "$step" "$feature_name" "$scenario_name" "$evidence" "$report_file"
+    return $?
+  fi
+
+  if [[ $exit_code -eq 0 ]]; then
+    echo "      Result: PASS"
+    echo "- [x] $step (PASS)" >> "$report_file"
+    return 0
+  fi
+
+  has_waiver "$sanitized_step"
+  waiver_code=$?
+
+  if [[ $waiver_code -eq 0 ]]; then
+    echo "      Result: WAIVED (documented exception)"
+    echo "- [~] $step (WAIVED)" >> "$report_file"
+    ((TOTAL_GLOBAL_WAIVED++))
+    return 3
+  fi
+  if [[ $waiver_code -eq 2 ]]; then
+    echo "      Result: FAIL (EXPIRED WAIVER)"
+    echo "- [ ] $step (FAIL) - EXPIRED WAIVER: review_date has passed" >> "$report_file"
+    ((TOTAL_GLOBAL_EXPIRED++))
+    ((TOTAL_GLOBAL_FAIL++))
+    return 1
+  fi
+
+  echo "      Result: FAIL"
+  echo "- [ ] $step (FAIL) - $evidence" >> "$report_file"
+  ((TOTAL_GLOBAL_FAIL++))
+  return 1
+}
+
+audit_run_file() {
+  local FEATURE_FILE="$1" REPORT_FILE line TOTAL_PASS TOTAL_FAIL step_result
+  local CURRENT_FEATURE="" CURRENT_SCENARIO="" IN_SCENARIO=false
+
+  echo "------------------------------------------------------------"
+  echo "FEATURE: $FEATURE_FILE"
+
+  REPORT_FILE="specs/verifications/reports/audit-$(basename "$FEATURE_FILE" .feature)-$(date +%Y%m%d-%H%M%S).md"
+  mkdir -p specs/verifications/reports
+
+  {
+    echo "# Audit Report: $FEATURE_FILE"
+    echo "Date: $(date)"
+    echo "Mode: Autonomous Verification (Judge: $JUDGE)"
+    echo ""
+  } > "$REPORT_FILE"
+
+  TOTAL_PASS=0
+  TOTAL_FAIL=0
+
+  while IFS= read -r line; do
+    line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+    if [[ "$line" =~ ^Feature: ]]; then
+      CURRENT_FEATURE="${line#Feature: }"
+      echo "FEATURE: $CURRENT_FEATURE"
+      echo "## Feature: $CURRENT_FEATURE" >> "$REPORT_FILE"
+    elif [[ "$line" =~ ^Scenario: ]]; then
+      CURRENT_SCENARIO="${line#Scenario: }"
+      if [[ -n "$SCENARIO_FILTER" && "$CURRENT_SCENARIO" != "$SCENARIO_FILTER" ]]; then
+        IN_SCENARIO=false
+        continue
+      fi
+      IN_SCENARIO=true
+      echo "  SCENARIO: $CURRENT_SCENARIO"
+      echo "### Scenario: $CURRENT_SCENARIO" >> "$REPORT_FILE"
+    elif [[ "$line" =~ ^(Given|When|Then|And|But)\  ]]; then
+      [[ "$IN_SCENARIO" != "true" ]] && continue
+      audit_process_step "$line" "$CURRENT_FEATURE" "$CURRENT_SCENARIO" "$REPORT_FILE"
+      step_result=$?
+      if [[ $step_result -eq 3 ]]; then
+        :
+      elif [[ $step_result -eq 0 ]]; then
+        ((TOTAL_PASS++))
+        ((TOTAL_GLOBAL_PASS++))
+      else
+        ((TOTAL_FAIL++))
+      fi
+    fi
+  done < "$FEATURE_FILE"
+
+  echo ""
+  echo "File Summary: PASS: $TOTAL_PASS, FAIL: $TOTAL_FAIL"
+  echo "Report saved to: $REPORT_FILE"
+}

package/scripts/lib/simple_yaml.py

@@ -0,0 +1,130 @@
+# story: e38s01
+# simple_yaml.py — Custom lightweight YAML parser extracted from trace-matrix.py.
+import re
+
+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

package/scripts/lib/trace-matrix.py

@@ -12,6 +12,12 @@ import json, os, re, sys, time
 from pathlib import Path
 from datetime import datetime, timezone
 
+# Add parent or current directory to sys.path so we can import local helper modules
+sys.path.insert(0, str(Path(__file__).parent))
+
+from simple_yaml import parse_simple_yaml
+from trace_renderer import emit_matrix_json, emit_trace_md, emit_okf_bundle
+
 ROOT = Path(sys.argv[1])
 MATRIX_JSON = Path(sys.argv[2])
 TRACE_MD = Path(sys.argv[3])
@@ -19,136 +25,6 @@ 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")
@@ -248,10 +124,6 @@ for line in result.stdout.splitlines():
 # -----------------------------------------------------------------------
 # 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)):
@@ -353,153 +225,10 @@ 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")
+# Emit outputs via trace_renderer
+matrix = emit_matrix_json(MATRIX_JSON, stories, tagged_sids, dark_stories, orphan_tags, stale_tags, matrix_stories)
+emit_trace_md(TRACE_MD, stories, tagged_sids, dark_stories, orphan_tags, stale_tags, matrix_stories, matrix, dev_status)
+emit_okf_bundle(OKF_DIR, stories, matrix_stories)
 
 # -----------------------------------------------------------------------
 # 8. Strict mode — exit non-zero on P0 uncovered

package/scripts/lib/trace_renderer.py

@@ -0,0 +1,147 @@
+# story: e38s01
+# trace_renderer.py — Output renderer for traceability matrix data.
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def emit_matrix_json(matrix_json_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list) -> dict:
+    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_path.parent.mkdir(parents=True, exist_ok=True)
+    matrix_json_path.write_text(json.dumps(matrix, indent=2), encoding="utf-8")
+    return matrix
+
+def emit_trace_md(trace_md_path: Path, stories: dict, tagged_sids: set, dark_stories: list, orphan_tags: list, stale_tags: list, matrix_stories: list, matrix: dict, dev_status: dict) -> None:
+    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_path.parent.mkdir(parents=True, exist_ok=True)
+    trace_md_path.write_text("\n".join(lines), encoding="utf-8")
+
+def emit_okf_bundle(okf_dir: Path, stories: dict, matrix_stories: list) -> None:
+    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")

package/scripts/test-trace-matrix-size.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# test-trace-matrix-size.sh — recurrence guard for BUG-2026-07-06-gate-trace-matrix-oversized
+#
+# Asserts trace-matrix.py and its extracted modules stay under the 300-line cap.
+#
+# Usage: bash scripts/test-trace-matrix-size.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+CAP=300
+FAILURES=0
+
+pass() { echo -e "${GREEN}PASS${NC} $1"; }
+fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+
+check_lines() {
+  local file="$1"
+  local lines
+  lines=$(wc -l < "$REPO_ROOT/$file" | tr -d ' ')
+  if [[ "$lines" -le "$CAP" ]]; then
+    pass "$file: $lines lines (≤ $CAP)"
+  else
+    fail "$file: $lines lines (exceeds $CAP)"
+  fi
+}
+
+for f in \
+  scripts/lib/trace-matrix.py \
+  scripts/lib/simple_yaml.py \
+  scripts/lib/trace_renderer.py
+do
+  check_lines "$f"
+done
+
+if [[ "$FAILURES" -gt 0 ]]; then
+  echo "test-trace-matrix-size.sh: $FAILURES failure(s)" >&2
+  exit 1
+fi
+
+exit 0