codeharness 0.8.0 → 0.10.0

package/dist/index.js

@@ -919,6 +919,14 @@ function storyVerificationPatch() {
 - [ ] All acceptance criteria verified with real-world evidence
 - [ ] Test coverage meets target (100%)
 
+### Verification Tags
+
+For each AC, append a verification tag to indicate how it can be verified:
+- \`<!-- verification: cli-verifiable -->\` \u2014 AC can be verified by running CLI commands in a subprocess
+- \`<!-- verification: integration-required -->\` \u2014 AC requires integration testing, multi-system interaction, or manual verification
+
+ACs referencing workflows, sprint planning, user sessions, or external system interactions should be tagged as \`integration-required\`. If no tag is present, a heuristic classifier will attempt to determine verifiability at runtime.
+
 ## Documentation Requirements
 
 - [ ] Relevant AGENTS.md files updated (list modules touched)
@@ -1340,7 +1348,7 @@ function importStoriesToBeads(stories, opts, beadsFns) {
 }
 
 // src/commands/init.ts
-var HARNESS_VERSION = true ? "0.8.0" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.10.0" : "0.0.0-dev";
 function getStackLabel(stack) {
   if (stack === "nodejs") return "Node.js (package.json)";
   if (stack === "python") return "Python";
@@ -2400,7 +2408,7 @@ function buildSpawnArgs(opts) {
   return args;
 }
 function registerRunCommand(program) {
-  program.command("run").description("Execute the autonomous coding loop").option("--max-iterations <n>", "Maximum loop iterations", "50").option("--timeout <seconds>", "Total loop timeout in seconds", "14400").option("--iteration-timeout <minutes>", "Per-iteration timeout in minutes", "15").option("--live", "Show live output streaming", false).option("--calls <n>", "Max API calls per hour", "100").option("--max-story-retries <n>", "Max retries per story before flagging", "3").action(async (options, cmd) => {
+  program.command("run").description("Execute the autonomous coding loop").option("--max-iterations <n>", "Maximum loop iterations", "50").option("--timeout <seconds>", "Total loop timeout in seconds", "14400").option("--iteration-timeout <minutes>", "Per-iteration timeout in minutes", "30").option("--live", "Show live output streaming", false).option("--calls <n>", "Max API calls per hour", "100").option("--max-story-retries <n>", "Max retries per story before flagging", "3").action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const isJson = !!globalOpts.json;
     const outputOpts = { json: isJson };
@@ -2573,6 +2581,29 @@ var DB_KEYWORDS = [
   "sql",
   "table"
 ];
+var INTEGRATION_KEYWORDS = [
+  "sprint planning",
+  "workflow",
+  "run /command",
+  "user session",
+  "multi-step",
+  "external system",
+  "real infrastructure",
+  "integration test",
+  "manual verification"
+];
+function classifyVerifiability(description) {
+  const lower = description.toLowerCase();
+  for (const kw of INTEGRATION_KEYWORDS) {
+    if (lower.includes(kw)) return "integration-required";
+  }
+  return "cli-verifiable";
+}
+var VERIFICATION_TAG_PATTERN = /<!--\s*verification:\s*(cli-verifiable|integration-required)\s*-->/;
+function parseVerificationTag(text) {
+  const match = VERIFICATION_TAG_PATTERN.exec(text);
+  return match ? match[1] : null;
+}
 function classifyAC(description) {
   const lower = description.toLowerCase();
   for (const kw of UI_KEYWORDS) {
@@ -2622,10 +2653,13 @@ function parseStoryACs(storyFilePath) {
     if (currentId !== null && currentDesc.length > 0) {
       const description = currentDesc.join(" ").trim();
       if (description) {
+        const tag = parseVerificationTag(description);
+        const verifiability = tag ?? classifyVerifiability(description);
         acs.push({
           id: currentId,
           description,
-          type: classifyAC(description)
+          type: classifyAC(description),
+          verifiability
         });
       } else {
         warn(`Skipping malformed AC #${currentId}: empty description`);
@@ -2764,6 +2798,62 @@ function getNewestSourceMtime(dir) {
   walk(dir);
   return newest;
 }
+function getSourceFilesInModule(modulePath) {
+  const files = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = readdirSync2(current);
+    } catch {
+      return;
+    }
+    const dirName = current.split("/").pop() ?? "";
+    if (dirName === "node_modules" || dirName === ".git" || dirName === "__tests__" || dirName === "dist" || dirName === "coverage" || dirName.startsWith(".") && current !== modulePath) return;
+    for (const entry of entries) {
+      const fullPath = join9(current, entry);
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+      } else if (stat.isFile()) {
+        const ext = getExtension(entry);
+        if (SOURCE_EXTENSIONS.has(ext) && !isTestFile(entry)) {
+          files.push(entry);
+        }
+      }
+    }
+  }
+  walk(modulePath);
+  return files;
+}
+function getMentionedFilesInAgentsMd(agentsPath) {
+  if (!existsSync11(agentsPath)) return [];
+  const content = readFileSync9(agentsPath, "utf-8");
+  const mentioned = /* @__PURE__ */ new Set();
+  const filenamePattern = /[\w./-]*[\w-]+\.(?:ts|js|py)\b/g;
+  let match;
+  while ((match = filenamePattern.exec(content)) !== null) {
+    const fullMatch = match[0];
+    const basename3 = fullMatch.split("/").pop();
+    if (!isTestFile(basename3)) {
+      mentioned.add(basename3);
+    }
+  }
+  return Array.from(mentioned);
+}
+function checkAgentsMdCompleteness(agentsPath, modulePath) {
+  const sourceFiles = getSourceFilesInModule(modulePath);
+  const mentionedFiles = new Set(getMentionedFilesInAgentsMd(agentsPath));
+  const missing = sourceFiles.filter((f) => !mentionedFiles.has(f));
+  return {
+    complete: missing.length === 0,
+    missing
+  };
+}
 function checkAgentsMdForModule(modulePath, dir) {
   const root = dir ?? process.cwd();
   const fullModulePath = join9(root, modulePath);
@@ -2782,13 +2872,15 @@ function checkAgentsMdForModule(modulePath, dir) {
   }
   const docMtime = statSync(agentsPath).mtime;
   const codeMtime = getNewestSourceMtime(fullModulePath);
-  if (codeMtime !== null && codeMtime.getTime() > docMtime.getTime()) {
+  const { complete, missing } = checkAgentsMdCompleteness(agentsPath, fullModulePath);
+  if (!complete) {
+    const missingList = missing.join(", ");
     return {
       path: relative(root, agentsPath),
       grade: "stale",
       lastModified: docMtime,
       codeLastModified: codeMtime,
-      reason: `AGENTS.md stale for module: ${modulePath}`
+      reason: `AGENTS.md stale for module: ${modulePath} \u2014 missing: ${missingList}`
     };
   }
   return {
@@ -2818,22 +2910,30 @@ function scanDocHealth(dir) {
   if (existsSync11(rootAgentsPath)) {
     if (modules.length > 0) {
       const docMtime = statSync(rootAgentsPath).mtime;
-      let newestCode = null;
+      let allMissing = [];
       let staleModule = "";
+      let newestCode = null;
       for (const mod of modules) {
-        const modMtime = getNewestSourceMtime(join9(root, mod));
+        const fullModPath = join9(root, mod);
+        const modAgentsPath = join9(fullModPath, "AGENTS.md");
+        if (existsSync11(modAgentsPath)) continue;
+        const { missing } = checkAgentsMdCompleteness(rootAgentsPath, fullModPath);
+        if (missing.length > 0 && staleModule === "") {
+          staleModule = mod;
+          allMissing = missing;
+        }
+        const modMtime = getNewestSourceMtime(fullModPath);
         if (modMtime !== null && (newestCode === null || modMtime.getTime() > newestCode.getTime())) {
           newestCode = modMtime;
-          staleModule = mod;
         }
       }
-      if (newestCode !== null && newestCode.getTime() > docMtime.getTime()) {
+      if (allMissing.length > 0) {
         documents.push({
           path: "AGENTS.md",
           grade: "stale",
           lastModified: docMtime,
           codeLastModified: newestCode,
-          reason: `AGENTS.md stale for module: ${staleModule}`
+          reason: `AGENTS.md stale for module: ${staleModule} \u2014 missing: ${allMissing.join(", ")}`
         });
       } else {
         documents.push({
@@ -3189,10 +3289,44 @@ function runShowboatVerify(proofPath) {
     return { passed: false, output: stdout || stderr || message };
   }
 }
-function proofHasContent(proofPath) {
-  if (!existsSync12(proofPath)) return false;
+function validateProofQuality(proofPath) {
+  if (!existsSync12(proofPath)) {
+    return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+  }
   const content = readFileSync10(proofPath, "utf-8");
-  return content.includes("<!-- /showboat exec -->") || content.includes("<!-- showboat image:");
+  const acHeaderPattern = /^## AC \d+:/gm;
+  const matches = [...content.matchAll(acHeaderPattern)];
+  if (matches.length === 0) {
+    return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
+  }
+  let verified = 0;
+  let pending = 0;
+  let escalated = 0;
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : content.length;
+    const section = content.slice(start, end);
+    if (section.includes("[ESCALATE]")) {
+      escalated++;
+      continue;
+    }
+    const hasEvidence = section.includes("<!-- /showboat exec -->") || section.includes("<!-- showboat image:") || /```(?:bash|shell)\n[\s\S]*?```\n+```output\n/m.test(section);
+    if (hasEvidence) {
+      verified++;
+    } else {
+      pending++;
+    }
+  }
+  const total = verified + pending + escalated;
+  return {
+    verified,
+    pending,
+    escalated,
+    total,
+    // Proof passes when no pending ACs remain and at least one is verified.
+    // Escalated ACs are allowed — they are explicitly acknowledged as unverifiable.
+    passed: pending === 0 && verified > 0
+  };
 }
 function updateVerificationState(storyId, result, dir) {
   const { state, body } = readStateWithBody(dir);
@@ -3333,36 +3467,52 @@ function verifyStory(storyId, isJson, root) {
     return;
   }
   const storyTitle = extractStoryTitle(storyFilePath);
-  const proofPath = createProofDocument(storyId, storyTitle, acs, root);
-  let showboatStatus = "skipped";
-  if (proofHasContent(proofPath)) {
-    const showboatResult = runShowboatVerify(proofPath);
-    if (showboatResult.output === "showboat not available") {
-      showboatStatus = "skipped";
-      warn("Showboat not installed \u2014 skipping re-verification");
+  const expectedProofPath = join11(root, "verification", `${storyId}-proof.md`);
+  const proofPath = existsSync13(expectedProofPath) ? expectedProofPath : createProofDocument(storyId, storyTitle, acs, root);
+  const proofQuality = validateProofQuality(proofPath);
+  if (!proofQuality.passed) {
+    if (isJson) {
+      jsonOutput({
+        status: "fail",
+        message: `Proof quality check failed: ${proofQuality.verified}/${proofQuality.total} ACs verified`,
+        proofQuality: { verified: proofQuality.verified, pending: proofQuality.pending, escalated: proofQuality.escalated, total: proofQuality.total }
+      });
     } else {
-      showboatStatus = showboatResult.passed ? "pass" : "fail";
-      if (!showboatResult.passed) {
-        fail(`Showboat verify failed: ${showboatResult.output}`, { json: isJson });
-        process.exitCode = 1;
-        return;
-      }
+      fail(`Proof quality check failed: ${proofQuality.verified}/${proofQuality.total} ACs verified`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  if (proofQuality.escalated > 0) {
+    warn(`Story ${storyId} has ${proofQuality.escalated} ACs requiring integration verification`);
+    info("Run these ACs manually or in a dedicated verification session");
+  }
+  let showboatStatus = "skipped";
+  const showboatResult = runShowboatVerify(proofPath);
+  if (showboatResult.output === "showboat not available") {
+    showboatStatus = "skipped";
+    warn("Showboat not installed \u2014 skipping re-verification");
+  } else {
+    showboatStatus = showboatResult.passed ? "pass" : "fail";
+    if (!showboatResult.passed) {
+      fail(`Showboat verify failed: ${showboatResult.output}`, { json: isJson });
+      process.exitCode = 1;
+      return;
     }
   }
-  const acsVerified = showboatStatus === "pass";
-  const verifiedCount = acsVerified ? acs.length : 0;
   const result = {
     storyId,
     success: true,
-    totalACs: acs.length,
-    verifiedCount,
-    failedCount: acs.length - verifiedCount,
+    totalACs: proofQuality.total,
+    verifiedCount: proofQuality.verified,
+    failedCount: proofQuality.pending,
+    escalatedCount: proofQuality.escalated,
     proofPath: `verification/${storyId}-proof.md`,
     showboatVerifyStatus: showboatStatus,
     perAC: acs.map((ac) => ({
       id: ac.id,
       description: ac.description,
-      verified: acsVerified,
+      verified: true,
       evidencePaths: []
     }))
   };
@@ -3394,7 +3544,10 @@ function verifyStory(storyId, isJson, root) {
     warn(`Failed to complete exec-plan: ${message}`);
   }
   if (isJson) {
-    jsonOutput(result);
+    jsonOutput({
+      ...result,
+      proofQuality: { verified: proofQuality.verified, pending: proofQuality.pending, escalated: proofQuality.escalated, total: proofQuality.total }
+    });
   } else {
     ok(`Story ${storyId}: verified \u2014 proof at verification/${storyId}-proof.md`);
   }
@@ -6630,7 +6783,7 @@ function registerGithubImportCommand(program) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.8.0" : "0.0.0-dev";
+var VERSION = true ? "0.10.0" : "0.0.0-dev";
 function createProgram() {
   const program = new Command();
   program.name("codeharness").description("Makes autonomous coding agents produce software that actually works").version(VERSION).option("--json", "Output in machine-readable JSON format");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {

package/ralph/AGENTS.md

@@ -1,22 +1,23 @@
 # ralph/
 
-Vendored autonomous execution loop. Spawns fresh Claude Code instances per iteration with verification gates, circuit breaker protection, and crash recovery.
+Vendored autonomous execution loop. Spawns fresh Claude Code instances per iteration with verification gates, circuit breaker protection, and crash recovery. Each iteration runs `/harness-run` which owns story lifecycle, verification, and session retrospective.
 
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| ralph.sh | Core loop — iteration, termination, rate limiting |
-| bridge.sh | BMAD→Ralph task bridge — converts epics to progress.json |
+| ralph.sh | Core loop — iteration, retry tracking, progress reporting, termination |
+| bridge.sh | BMAD→Ralph task bridge — converts epics to progress.json (legacy) |
 | verify_gates.sh | Per-story verification gate checks (4 gates) |
-| drivers/claude-code.sh | Claude Code instance lifecycle and command building |
+| drivers/claude-code.sh | Claude Code instance lifecycle, allowed tools, command building |
+| harness_status.sh | Sprint status display via CLI |
 | lib/date_utils.sh | Cross-platform date/timestamp utilities |
 | lib/timeout_utils.sh | Cross-platform timeout command detection |
 | lib/circuit_breaker.sh | Stagnation detection (CLOSED→HALF_OPEN→OPEN) |
 
 ## Dependencies
 
-- `jq`: JSON processing for progress/status files
+- `jq`: JSON processing for status files
 - `gtimeout`/`timeout`: Per-iteration timeout protection
 - `git`: Progress detection via commit diff
 
@@ -24,10 +25,19 @@ Vendored autonomous execution loop. Spawns fresh Claude Code instances per itera
 
 - All scripts use `set -e` and are POSIX-compatible bash
 - Driver pattern: `drivers/{name}.sh` implements the driver interface
-- State files: `status.json` (loop state), `progress.json` (task tracking)
-- Logs written to `logs/ralph.log`
+- Primary task source: `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- State files: `status.json` (loop state), `.story_retries` (per-story retry counts), `.flagged_stories` (exceeded retry limit)
+- Logs written to `logs/ralph.log` and `logs/claude_output_*.log`
 - Scripts guard main execution with `[[ "${BASH_SOURCE[0]}" == "${0}" ]]`
 
+## Post-Iteration Output
+
+After each iteration, Ralph prints:
+- Completed stories with titles and proof file paths
+- Progress summary with next story in queue
+- Session issues (from `.session-issues.md` written by subagents)
+- Session retro highlights (action items from `session-retro-{date}.md`)
+
 ## Testing
 
 ```bash

package/ralph/drivers/claude-code.sh

@@ -41,9 +41,12 @@ driver_valid_tools() {
         "Bash"
         "Bash(git *)"
         "Bash(npm *)"
+        "Bash(npx *)"
         "Bash(bats *)"
         "Bash(python *)"
         "Bash(node *)"
+        "Bash(showboat *)"
+        "Bash(codeharness *)"
         "NotebookEdit"
     )
 }

package/ralph/harness_status.sh

@@ -130,15 +130,6 @@ if [[ -f "$PROGRESS_FILE" ]]; then
 
     echo ""
 
-    # Verification summary
-    VLOG="$PROJECT_DIR/ralph/verification-log.json"
-    if [[ -f "$VLOG" ]]; then
-        v_total=$(jq '.events | length' "$VLOG" 2>/dev/null || echo "0")
-        v_pass=$(jq '[.events[] | select(.result == "pass")] | length' "$VLOG" 2>/dev/null || echo "0")
-        echo "  Verification: $v_pass passed / $v_total checks"
-        echo ""
-    fi
-
     # Next action
     current=$(jq -r '.tasks[] | select(.status == "pending" or .status == "in_progress") | .id' "$PROGRESS_FILE" 2>/dev/null | head -1)
     if [[ -n "$current" && "$current" != "null" ]]; then

package/ralph/ralph.sh

@@ -38,7 +38,7 @@ LOG_DIR=""
 MAX_ITERATIONS=${MAX_ITERATIONS:-50}
 MAX_STORY_RETRIES=${MAX_STORY_RETRIES:-3}
 LOOP_TIMEOUT_SECONDS=${LOOP_TIMEOUT_SECONDS:-14400}  # 4 hours default
-ITERATION_TIMEOUT_MINUTES=${ITERATION_TIMEOUT_MINUTES:-15}
+ITERATION_TIMEOUT_MINUTES=${ITERATION_TIMEOUT_MINUTES:-30}
 
 # Rate limiting
 MAX_CALLS_PER_HOUR=${MAX_CALLS_PER_HOUR:-100}
@@ -447,6 +447,7 @@ print_progress_summary() {
     counts=$(get_task_counts)
     local total=${counts%% *}
     local completed=${counts##* }
+    local remaining=$((total - completed))
     local elapsed=$(( $(date +%s) - loop_start_time ))
     local elapsed_fmt
 
@@ -458,7 +459,62 @@ print_progress_summary() {
         elapsed_fmt="${elapsed}s"
     fi
 
-    log_status "INFO" "Progress: ${completed}/${total} stories complete (iterations: ${loop_count}, elapsed: ${elapsed_fmt})"
+    log_status "INFO" "Progress: ${completed}/${total} done, ${remaining} remaining (iterations: ${loop_count}, elapsed: ${elapsed_fmt})"
+
+    # Show the next story in line (first non-done, non-flagged)
+    if [[ -f "$SPRINT_STATUS_FILE" ]]; then
+        local next_story=""
+        while IFS=: read -r key value; do
+            key=$(echo "$key" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            value=$(echo "$value" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            [[ -z "$key" || "$key" == \#* ]] && continue
+            if [[ "$key" =~ ^[0-9]+-[0-9]+- && "$value" != "done" ]]; then
+                if ! is_story_flagged "$key"; then
+                    next_story="$key ($value)"
+                    break
+                fi
+            fi
+        done < "$SPRINT_STATUS_FILE"
+        if [[ -n "$next_story" ]]; then
+            log_status "INFO" "Next up: ${next_story}"
+        fi
+    fi
+}
+
+# ─── Iteration Insights ──────────────────────────────────────────────────────
+
+print_iteration_insights() {
+    local project_root
+    project_root="$(pwd)"
+    local issues_file="$project_root/_bmad-output/implementation-artifacts/.session-issues.md"
+    local today
+    today=$(date +%Y-%m-%d)
+    local retro_file="$project_root/_bmad-output/implementation-artifacts/session-retro-${today}.md"
+
+    # Show session issues (last 20 lines — most recent subagent)
+    if [[ -f "$issues_file" ]]; then
+        local issue_count
+        issue_count=$(grep -c '^### ' "$issues_file" 2>/dev/null || echo "0")
+        if [[ $issue_count -gt 0 ]]; then
+            echo ""
+            log_status "INFO" "━━━ Session Issues ($issue_count entries) ━━━"
+            # Print the last subagent's issues block
+            awk '/^### /{block=""} {block=block $0 "\n"} END{printf "%s", block}' "$issues_file" | head -15
+            echo ""
+        fi
+    fi
+
+    # Show retro summary if generated
+    if [[ -f "$retro_file" ]]; then
+        log_status "INFO" "━━━ Session Retro ━━━"
+        # Print action items section if present, otherwise first 10 lines
+        if grep -q '## Action items\|## Action Items' "$retro_file" 2>/dev/null; then
+            sed -n '/^## Action [Ii]tems/,/^## /p' "$retro_file" | head -20
+        else
+            head -10 "$retro_file"
+        fi
+        echo ""
+    fi
 }
 
 # ─── Driver Management ──────────────────────────────────────────────────────
@@ -474,6 +530,13 @@ load_platform_driver() {
     source "$driver_file"
 
     driver_valid_tools
+
+    # Auto-populate CLAUDE_ALLOWED_TOOLS from driver's valid tool patterns
+    # so Ralph runs autonomously without permission prompts
+    if [[ -z "$CLAUDE_ALLOWED_TOOLS" && ${#VALID_TOOL_PATTERNS[@]} -gt 0 ]]; then
+        CLAUDE_ALLOWED_TOOLS=$(IFS=','; echo "${VALID_TOOL_PATTERNS[*]}")
+    fi
+
     log_status "INFO" "Platform driver: $(driver_display_name) ($(driver_cli_binary))"
 }
 
@@ -496,8 +559,10 @@ execute_iteration() {
     log_status "LOOP" "Iteration $iteration — Task: ${task_id:-'(reading from prompt)'}"
     local timeout_seconds=$((ITERATION_TIMEOUT_MINUTES * 60))
 
-    # Build loop context
-    local loop_context="Loop #${iteration}."
+    # Build loop context — pass time budget so the session can prioritize retro
+    local start_time
+    start_time=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local loop_context="Loop #${iteration}. Time budget: ${ITERATION_TIMEOUT_MINUTES} minutes (started: ${start_time}). Reserve the last 5 minutes for Step 8 (session retrospective) — do not start new story work if less than 10 minutes remain."
     if [[ -n "$task_id" ]]; then
         loop_context+=" Current task: $task_id."
     fi
@@ -509,6 +574,10 @@ execute_iteration() {
         return 1
     fi
 
+    # Write deadline file for time-warning hook
+    local deadline=$(( $(date +%s) + timeout_seconds ))
+    echo "$deadline" > "ralph/.iteration_deadline"
+
     log_status "INFO" "Starting $(driver_display_name) (timeout: ${ITERATION_TIMEOUT_MINUTES}m)..."
 
     # Execute with timeout
@@ -648,7 +717,7 @@ Options:
     --max-iterations NUM      Maximum loop iterations (default: 50)
     --max-story-retries NUM   Max retries per story before flagging (default: 3)
     --timeout SECONDS         Total loop timeout in seconds (default: 14400 = 4h)
-    --iteration-timeout MIN   Per-iteration timeout in minutes (default: 15)
+    --iteration-timeout MIN   Per-iteration timeout in minutes (default: 30)
     --calls NUM               Max API calls per hour (default: 100)
     --prompt FILE             Prompt file for each iteration
     --progress FILE           Progress file (tasks JSON)
@@ -834,11 +903,12 @@ main() {
                 after_snapshot=$(snapshot_story_statuses)
                 detect_story_changes "$before_snapshot" "$after_snapshot"
 
-                # For each non-done, non-flagged story, increment retry count
+                # Only increment retry for the FIRST non-done, non-flagged story
+                # (the one harness-run would have picked up). Other stories were
+                # never attempted — don't penalise them for not progressing.
                 if [[ -n "$UNCHANGED_STORIES" ]]; then
                     while IFS= read -r skey; do
                         [[ -z "$skey" ]] && continue
-                        # Skip already-flagged stories
                         if is_story_flagged "$skey"; then
                             continue
                         fi
@@ -850,13 +920,29 @@ main() {
                         else
                             log_status "WARN" "Story ${skey} — retry ${retry_count}/${MAX_STORY_RETRIES}"
                         fi
+                        break  # only retry the first actionable story
                     done <<< "$UNCHANGED_STORIES"
                 fi
 
                 if [[ -n "$CHANGED_STORIES" ]]; then
                     while IFS= read -r skey; do
                         [[ -z "$skey" ]] && continue
-                        log_status "SUCCESS" "Story ${skey}: DONE"
+                        # Extract story title from story file if available
+                        local story_file="$project_root/_bmad-output/implementation-artifacts/${skey}.md"
+                        local story_title=""
+                        if [[ -f "$story_file" ]]; then
+                            story_title=$(grep -m1 '^# \|^## Story' "$story_file" 2>/dev/null | sed 's/^#* *//' | head -c 60)
+                        fi
+                        local proof_file="$project_root/verification/${skey}-proof.md"
+                        local proof_info=""
+                        if [[ -f "$proof_file" ]]; then
+                            proof_info=" [proof: verification/${skey}-proof.md]"
+                        fi
+                        if [[ -n "$story_title" ]]; then
+                            log_status "SUCCESS" "Story ${skey}: DONE — ${story_title}${proof_info}"
+                        else
+                            log_status "SUCCESS" "Story ${skey}: DONE${proof_info}"
+                        fi
                     done <<< "$CHANGED_STORIES"
                 fi
 
@@ -892,6 +978,9 @@ main() {
         # Print progress summary after every iteration
         print_progress_summary
 
+        # ── Show session issues and retro highlights ──
+        print_iteration_insights
+
         log_status "LOOP" "=== End Iteration #$loop_count ==="
     done
 
@@ -919,14 +1008,6 @@ main() {
         "$(if [[ $completed -eq $total && $total -gt 0 ]]; then echo "completed"; else echo "stopped"; fi)" \
         "completed:$completed/$total"
 
-    # Mandatory retrospective — cannot be skipped
-    log_status "INFO" "Triggering mandatory sprint retrospective..."
-    if [[ -f "$SCRIPT_DIR/retro.sh" ]]; then
-        local project_root
-        project_root="$(pwd)"
-        "$SCRIPT_DIR/retro.sh" --project-dir "$project_root" 2>&1 || \
-            log_status "WARN" "Retro report generation failed"
-    fi
 }
 
 # ─── CLI Parsing ─────────────────────────────────────────────────────────────

package/ralph/verify_gates.sh

@@ -162,39 +162,10 @@ increment_iteration() {
     fi
 }
 
-# ─── Verification log ─────────────────────────────────────────────────────
-
-append_verification_log() {
-    local result="$1"
-    local log_file="$PROJECT_DIR/ralph/verification-log.json"
-    local timestamp
-    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-    local event
-    event=$(jq -n \
-        --arg story_id "$STORY_ID" \
-        --arg result "$result" \
-        --argjson gates_passed "$GATES_PASSED" \
-        --argjson gates_total "$GATES_TOTAL" \
-        --arg timestamp "$timestamp" \
-        '{story_id: $story_id, result: $result, gates_passed: $gates_passed, gates_total: $gates_total, timestamp: $timestamp}')
-
-    if [[ -f "$log_file" ]]; then
-        log_data=$(jq --argjson event "$event" '.events += [$event]' "$log_file" 2>/dev/null)
-        if [[ -n "$log_data" ]]; then
-            echo "$log_data" > "$log_file"
-        fi
-    else
-        jq -n --argjson event "$event" '{events: [$event]}' > "$log_file"
-    fi
-}
-
 # ─── Decision ─────────────────────────────────────────────────────────────
 
 if [[ $GATES_PASSED -eq $GATES_TOTAL ]]; then
     # Log pass event
-    append_verification_log "pass"
-
     # All gates pass — mark story complete
     local_updated=$(jq --arg id "$STORY_ID" \
         '(.tasks[] | select(.id == $id)).status = "complete"' \
@@ -224,8 +195,6 @@ if [[ $GATES_PASSED -eq $GATES_TOTAL ]]; then
     exit 0
 else
     # Log fail event
-    append_verification_log "fail"
-
     # Gates failed — increment iteration, report failures
     increment_iteration
 

package/ralph/doc_gardener.sh

@@ -1,352 +0,0 @@
-#!/usr/bin/env bash
-# doc_gardener.sh — Documentation freshness scanner
-# Finds: missing AGENTS.md, stale AGENTS.md, stale exec-plans.
-# Used by the doc-gardener subagent and during retrospectives.
-#
-# Usage: ralph/doc_gardener.sh --project-dir DIR [--json]
-
-set -e
-
-PROJECT_DIR=""
-JSON_OUTPUT=false
-GENERATE_REPORT=false
-COMPLEXITY_THRESHOLD=3  # Minimum source files to require AGENTS.md
-
-show_help() {
-    cat << 'HELPEOF'
-Doc-Gardener Scanner — find stale and missing documentation
-
-Usage:
-    ralph/doc_gardener.sh --project-dir DIR [--json]
-
-Checks:
-    1. Modules with 3+ source files but no AGENTS.md
-    2. AGENTS.md files older than corresponding source code changes
-    3. Exec-plans in active/ for already-completed stories
-
-Options:
-    --project-dir DIR   Project root directory
-    --json              Output findings as JSON (default: human-readable)
-    --report            Generate quality-score.md and tech-debt-tracker.md
-    --threshold N       Min source files to require AGENTS.md (default: 3)
-    -h, --help          Show this help message
-HELPEOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        --project-dir)
-            PROJECT_DIR="$2"
-            shift 2
-            ;;
-        --json)
-            JSON_OUTPUT=true
-            shift
-            ;;
-        --report)
-            GENERATE_REPORT=true
-            shift
-            ;;
-        --threshold)
-            COMPLEXITY_THRESHOLD="$2"
-            shift 2
-            ;;
-        *)
-            echo "Unknown option: $1" >&2
-            exit 1
-            ;;
-    esac
-done
-
-if [[ -z "$PROJECT_DIR" ]]; then
-    echo "Error: --project-dir is required" >&2
-    exit 1
-fi
-
-if [[ ! -d "$PROJECT_DIR" ]]; then
-    echo "Error: project directory not found: $PROJECT_DIR" >&2
-    exit 1
-fi
-
-# ─── Findings collection ─────────────────────────────────────────────────
-
-FINDINGS_JSON="[]"
-
-add_finding() {
-    local type="$1"
-    local path="$2"
-    local message="$3"
-
-    FINDINGS_JSON=$(echo "$FINDINGS_JSON" | jq \
-        --arg type "$type" \
-        --arg path "$path" \
-        --arg message "$message" \
-        '. += [{"type": $type, "path": $path, "message": $message}]')
-}
-
-# ─── Check 1: Missing AGENTS.md for modules above complexity threshold ────
-
-check_missing_agents_md() {
-    # Find directories with source files but no AGENTS.md
-    # Exclude hidden dirs, node_modules, _bmad, .ralph, docs, tests
-    while IFS= read -r dir; do
-        [[ -z "$dir" ]] && continue
-
-        # Count source files (common extensions)
-        local src_count
-        src_count=$(find "$dir" -maxdepth 1 \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.sh" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) 2>/dev/null | wc -l | tr -d ' ')
-
-        if [[ $src_count -ge $COMPLEXITY_THRESHOLD ]]; then
-            if [[ ! -f "$dir/AGENTS.md" ]]; then
-                local rel_path="${dir#$PROJECT_DIR/}"
-                add_finding "missing_agents_md" "$rel_path" "Module $rel_path has $src_count source files but no AGENTS.md"
-            fi
-        fi
-    done < <(find "$PROJECT_DIR" -type d \
-        -not -path "$PROJECT_DIR/.*" \
-        -not -path "*/node_modules/*" \
-        -not -path "*/_bmad/*" \
-        -not -path "*/.ralph/*" \
-        -not -path "*/docs/*" \
-        -not -path "*/tests/*" \
-        -not -path "$PROJECT_DIR" \
-        2>/dev/null)
-}
-
-# ─── Check 2: Stale AGENTS.md (code changed after docs) ──────────────────
-
-check_stale_agents_md() {
-    while IFS= read -r agents_file; do
-        [[ -z "$agents_file" ]] && continue
-
-        local dir
-        dir=$(dirname "$agents_file")
-        local rel_dir="${dir#$PROJECT_DIR/}"
-
-        # Get AGENTS.md last commit time
-        local agents_commit_time
-        agents_commit_time=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- "$agents_file" 2>/dev/null || echo "0")
-
-        # Get latest source file commit time in the same directory
-        local latest_src_time="0"
-        while IFS= read -r src_file; do
-            [[ -z "$src_file" ]] && continue
-            local src_time
-            src_time=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- "$src_file" 2>/dev/null || echo "0")
-            if [[ $src_time -gt $latest_src_time ]]; then
-                latest_src_time=$src_time
-            fi
-        done < <(find "$dir" -maxdepth 1 \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.sh" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) -not -name "AGENTS.md" 2>/dev/null)
-
-        if [[ $latest_src_time -gt $agents_commit_time && $agents_commit_time -gt 0 ]]; then
-            add_finding "stale_agents_md" "$rel_dir" "AGENTS.md in $rel_dir is stale — source code changed after docs"
-        fi
-    done < <(find "$PROJECT_DIR" -name "AGENTS.md" \
-        -not -path "*/node_modules/*" \
-        -not -path "*/_bmad/*" \
-        -not -path "*/.ralph/*" \
-        2>/dev/null)
-}
-
-# ─── Check 3: Stale exec-plans (completed stories still in active/) ──────
-
-check_stale_exec_plans() {
-    local progress_file="$PROJECT_DIR/ralph/progress.json"
-    local active_dir="$PROJECT_DIR/docs/exec-plans/active"
-
-    if [[ ! -f "$progress_file" || ! -d "$active_dir" ]]; then
-        return 0
-    fi
-
-    # Find active exec-plans for completed stories
-    for plan_file in "$active_dir"/*.md; do
-        [[ -f "$plan_file" ]] || continue
-
-        local story_id
-        story_id=$(basename "$plan_file" .md)
-
-        local story_status
-        story_status=$(jq -r --arg id "$story_id" '.tasks[] | select(.id == $id) | .status // ""' "$progress_file" 2>/dev/null)
-
-        if [[ "$story_status" == "complete" ]]; then
-            add_finding "stale_exec_plan" "docs/exec-plans/active/$story_id.md" \
-                "Exec-plan for story $story_id is still in active/ but story is complete — should be in completed/"
-        fi
-    done
-}
-
-# ─── Quality scoring ──────────────────────────────────────────────────────
-
-# Collect module info for quality grading
-declare -A MODULE_GRADES
-
-grade_modules() {
-    while IFS= read -r dir; do
-        [[ -z "$dir" ]] && continue
-
-        local src_count
-        src_count=$(find "$dir" -maxdepth 1 \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.sh" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \) 2>/dev/null | wc -l | tr -d ' ')
-
-        # Skip directories with no source files
-        [[ $src_count -eq 0 ]] && continue
-
-        local rel_path="${dir#$PROJECT_DIR/}"
-        local has_agents="false"
-        local is_stale="false"
-
-        if [[ -f "$dir/AGENTS.md" ]]; then
-            has_agents="true"
-
-            # Check staleness
-            local agents_time
-            agents_time=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- "$dir/AGENTS.md" 2>/dev/null || echo "0")
-            local latest_src="0"
-            while IFS= read -r sf; do
-                [[ -z "$sf" ]] && continue
-                local st
-                st=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- "$sf" 2>/dev/null || echo "0")
-                [[ $st -gt $latest_src ]] && latest_src=$st
-            done < <(find "$dir" -maxdepth 1 \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.sh" \) -not -name "AGENTS.md" 2>/dev/null)
-
-            if [[ $latest_src -gt $agents_time && $agents_time -gt 0 ]]; then
-                is_stale="true"
-            fi
-        fi
-
-        # Grade: A = has fresh AGENTS.md, B = has stale AGENTS.md, F = missing
-        local grade="F"
-        if [[ "$has_agents" == "true" && "$is_stale" == "false" ]]; then
-            grade="A"
-        elif [[ "$has_agents" == "true" && "$is_stale" == "true" ]]; then
-            grade="B"
-        fi
-
-        MODULE_GRADES["$rel_path"]="$grade"
-    done < <(find "$PROJECT_DIR" -type d \
-        -not -path "$PROJECT_DIR/.*" \
-        -not -path "*/node_modules/*" \
-        -not -path "*/_bmad/*" \
-        -not -path "*/.ralph/*" \
-        -not -path "*/docs/*" \
-        -not -path "*/tests/*" \
-        -not -path "$PROJECT_DIR" \
-        2>/dev/null)
-}
-
-generate_quality_report() {
-    local output_file="$PROJECT_DIR/docs/quality/quality-score.md"
-    mkdir -p "$(dirname "$output_file")"
-
-    local timestamp
-    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-    {
-        echo "<!-- DO NOT EDIT MANUALLY — generated by doc-gardener -->"
-        echo ""
-        echo "# Documentation Quality Score"
-        echo ""
-        echo "**Generated:** $timestamp"
-        echo ""
-        echo "## Module Grades"
-        echo ""
-        echo "| Module | Grade | Status |"
-        echo "|--------|-------|--------|"
-
-        # Sort and output grades
-        for module in $(echo "${!MODULE_GRADES[@]}" | tr ' ' '\n' | sort); do
-            local grade="${MODULE_GRADES[$module]}"
-            local status_text
-            case "$grade" in
-                A) status_text="AGENTS.md present and current" ;;
-                B) status_text="AGENTS.md present but stale" ;;
-                F) status_text="AGENTS.md missing" ;;
-            esac
-            echo "| $module | $grade | $status_text |"
-        done
-
-        echo ""
-        echo "## Grade Legend"
-        echo ""
-        echo "- **A**: Module has current AGENTS.md"
-        echo "- **B**: Module has AGENTS.md but code changed since last update"
-        echo "- **F**: Module has no AGENTS.md (3+ source files)"
-    } > "$output_file"
-}
-
-generate_tech_debt_report() {
-    local output_file="$PROJECT_DIR/docs/exec-plans/tech-debt-tracker.md"
-    mkdir -p "$(dirname "$output_file")"
-
-    local timestamp
-    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-    {
-        echo "<!-- DO NOT EDIT MANUALLY — generated by doc-gardener -->"
-        echo ""
-        echo "# Documentation Tech Debt"
-        echo ""
-        echo "**Generated:** $timestamp"
-        echo ""
-
-        local debt_count
-        debt_count=$(echo "$FINDINGS_JSON" | jq '. | length')
-
-        if [[ $debt_count -eq 0 ]]; then
-            echo "No documentation debt items."
-        else
-            echo "| # | Type | Path | Issue |"
-            echo "|---|------|------|-------|"
-
-            local i=1
-            echo "$FINDINGS_JSON" | jq -r '.[] | "\(.type)\t\(.path)\t\(.message)"' | while IFS=$'\t' read -r type path message; do
-                echo "| $i | $type | $path | $message |"
-                i=$((i + 1))
-            done
-        fi
-    } > "$output_file"
-}
-
-# ─── Run all checks ──────────────────────────────────────────────────────
-
-check_missing_agents_md
-check_stale_agents_md
-check_stale_exec_plans
-
-# Generate reports if requested
-if [[ "$GENERATE_REPORT" == "true" ]]; then
-    grade_modules
-    generate_quality_report
-    generate_tech_debt_report
-fi
-
-# ─── Output ───────────────────────────────────────────────────────────────
-
-finding_count=$(echo "$FINDINGS_JSON" | jq '. | length')
-
-if [[ "$JSON_OUTPUT" == "true" ]]; then
-    jq -n \
-        --argjson findings "$FINDINGS_JSON" \
-        --argjson count "$finding_count" \
-        --arg scanned_at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
-        '{
-            scanned_at: $scanned_at,
-            finding_count: $count,
-            findings: $findings
-        }'
-else
-    echo "Doc-Gardener Scan"
-    echo ""
-
-    if [[ $finding_count -eq 0 ]]; then
-        echo "[OK] No documentation issues found"
-    else
-        echo "$FINDINGS_JSON" | jq -r '.[] | "  [WARN] \(.type): \(.message)"'
-    fi
-
-    echo ""
-    echo "$finding_count finding(s) total"
-fi

package/ralph/retro.sh

@@ -1,298 +0,0 @@
-#!/usr/bin/env bash
-# retro.sh — Sprint Retrospective Report Generator
-# Produces docs/quality/retro-report.md with sprint summary, verification
-# effectiveness, and documentation health analysis.
-# Must complete within 30 seconds (NFR20).
-#
-# Usage: ralph/retro.sh --project-dir DIR
-
-set -e
-
-PROJECT_DIR=""
-GENERATE_COVERAGE=false
-GENERATE_FOLLOWUP=false
-
-show_help() {
-    cat << 'HELPEOF'
-Sprint Retrospective — generate structured retro report
-
-Usage:
-    ralph/retro.sh --project-dir DIR
-
-Generates docs/quality/retro-report.md with:
-    1. Sprint summary (stories, iterations, duration)
-    2. Verification effectiveness (pass rates, iteration counts)
-    3. Documentation health (doc-gardener findings)
-
-Options:
-    --project-dir DIR   Project root directory
-    --coverage          Also generate docs/quality/test-coverage.md
-    -h, --help          Show this help message
-HELPEOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        -h|--help)
-            show_help
-            exit 0
-            ;;
-        --project-dir)
-            PROJECT_DIR="$2"
-            shift 2
-            ;;
-        --coverage)
-            GENERATE_COVERAGE=true
-            shift
-            ;;
-        --followup)
-            GENERATE_FOLLOWUP=true
-            shift
-            ;;
-        *)
-            echo "Unknown option: $1" >&2
-            exit 1
-            ;;
-    esac
-done
-
-if [[ -z "$PROJECT_DIR" ]]; then
-    echo "Error: --project-dir is required" >&2
-    exit 1
-fi
-
-PROGRESS_FILE="$PROJECT_DIR/ralph/progress.json"
-VLOG_FILE="$PROJECT_DIR/ralph/verification-log.json"
-OUTPUT_FILE="$PROJECT_DIR/docs/quality/retro-report.md"
-
-mkdir -p "$(dirname "$OUTPUT_FILE")"
-
-timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-# ─── Gather data ──────────────────────────────────────────────────────────
-
-# Sprint progress
-total_stories=0
-completed_stories=0
-total_iterations=0
-
-if [[ -f "$PROGRESS_FILE" ]]; then
-    total_stories=$(jq '.tasks | length' "$PROGRESS_FILE" 2>/dev/null || echo "0")
-    completed_stories=$(jq '[.tasks[] | select(.status == "complete")] | length' "$PROGRESS_FILE" 2>/dev/null || echo "0")
-    total_iterations=$(jq '[.tasks[].iterations // 0] | add // 0' "$PROGRESS_FILE" 2>/dev/null || echo "0")
-fi
-
-avg_iterations="N/A"
-if [[ $completed_stories -gt 0 ]]; then
-    avg_iterations=$(echo "scale=1; $total_iterations / $completed_stories" | bc 2>/dev/null || echo "$((total_iterations / completed_stories))")
-fi
-
-# Verification log
-v_total=0
-v_pass=0
-v_fail=0
-pass_rate="N/A"
-
-if [[ -f "$VLOG_FILE" ]]; then
-    v_total=$(jq '.events | length' "$VLOG_FILE" 2>/dev/null || echo "0")
-    v_pass=$(jq '[.events[] | select(.result == "pass")] | length' "$VLOG_FILE" 2>/dev/null || echo "0")
-    v_fail=$(jq '[.events[] | select(.result == "fail")] | length' "$VLOG_FILE" 2>/dev/null || echo "0")
-    if [[ $v_total -gt 0 ]]; then
-        pass_rate="$((v_pass * 100 / v_total))%"
-    fi
-fi
-
-# ─── Generate report ──────────────────────────────────────────────────────
-
-{
-    echo "<!-- DO NOT EDIT MANUALLY — generated by retro.sh -->"
-    echo ""
-    echo "# Sprint Retrospective Report"
-    echo ""
-    echo "**Generated:** $timestamp"
-    echo ""
-
-    # ── Sprint Summary ──
-    echo "## Sprint Summary"
-    echo ""
-    echo "| Metric | Value |"
-    echo "|--------|-------|"
-    echo "| Stories completed | $completed_stories / $total_stories |"
-    echo "| Total verification iterations | $total_iterations |"
-    echo "| Average iterations per story | $avg_iterations |"
-    echo "| Verification checks | $v_total ($v_pass pass, $v_fail fail) |"
-    echo "| Pass rate | $pass_rate |"
-    echo ""
-
-    # ── Verification Effectiveness ──
-    echo "## Verification Effectiveness"
-    echo ""
-
-    if [[ -f "$PROGRESS_FILE" ]]; then
-        echo "### Per-Story Iteration Counts"
-        echo ""
-        echo "| Story | Title | Iterations | Status |"
-        echo "|-------|-------|------------|--------|"
-        jq -r '.tasks[] | "\(.id)\t\(.title)\t\(.iterations // 0)\t\(.status)"' "$PROGRESS_FILE" 2>/dev/null | \
-        while IFS=$'\t' read -r id title iters status; do
-            echo "| $id | ${title:0:40} | $iters | $status |"
-        done
-        echo ""
-    fi
-
-    if [[ -f "$VLOG_FILE" && $v_fail -gt 0 ]]; then
-        echo "### Common Failure Patterns"
-        echo ""
-        # Count failures per gate count
-        jq -r '.events[] | select(.result == "fail") | "gates_passed=\(.gates_passed)/\(.gates_total)"' "$VLOG_FILE" 2>/dev/null | \
-            sort | uniq -c | sort -rn | head -5 | while read -r count pattern; do
-                echo "- $count occurrences: $pattern"
-            done
-        echo ""
-    fi
-
-    # ── Documentation Health ──
-    echo "## Documentation Health"
-    echo ""
-
-    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-    if [[ -f "$SCRIPT_DIR/doc_gardener.sh" ]]; then
-        doc_findings=$("$SCRIPT_DIR/doc_gardener.sh" --project-dir "$PROJECT_DIR" --json 2>/dev/null || echo '{"finding_count":0,"findings":[]}')
-        doc_count=$(echo "$doc_findings" | jq '.finding_count // 0' 2>/dev/null || echo "0")
-        echo "Doc-gardener findings: **$doc_count**"
-        echo ""
-
-        if [[ $doc_count -gt 0 ]]; then
-            echo "$doc_findings" | jq -r '.findings[] | "- [\(.type)] \(.message)"' 2>/dev/null
-            echo ""
-        fi
-    else
-        echo "Doc-gardener not available."
-        echo ""
-    fi
-
-    # ── Recommendations ──
-    echo "## Recommendations"
-    echo ""
-
-    if [[ $v_fail -gt 0 ]]; then
-        echo "- Review verification failures — $v_fail checks failed"
-    fi
-
-    if [[ $total_iterations -gt $((completed_stories * 2)) && $completed_stories -gt 0 ]]; then
-        echo "- High iteration count ($avg_iterations avg) — stories may need better AC definition"
-    fi
-
-    if [[ $completed_stories -lt $total_stories ]]; then
-        remaining=$((total_stories - completed_stories))
-        echo "- $remaining stories incomplete — carry forward to next sprint"
-    fi
-
-    if [[ $completed_stories -eq $total_stories && $total_stories -gt 0 ]]; then
-        echo "- All stories completed — sprint success"
-    fi
-
-} > "$OUTPUT_FILE"
-
-# ─── Coverage report ──────────────────────────────────────────────────────
-
-if [[ "$GENERATE_COVERAGE" == "true" ]]; then
-    COV_FILE="$PROJECT_DIR/docs/quality/test-coverage.md"
-    STATE_FILE="$PROJECT_DIR/.claude/codeharness.local.md"
-
-    # Read baseline and current from state file
-    baseline_cov="N/A"
-    current_cov="N/A"
-    if [[ -f "$STATE_FILE" ]]; then
-        baseline_cov=$(grep -o 'baseline: *[0-9]*' "$STATE_FILE" 2>/dev/null | head -1 | awk '{print $2}')
-        current_cov=$(grep -o 'current: *[0-9]*' "$STATE_FILE" 2>/dev/null | head -1 | awk '{print $2}')
-    fi
-    baseline_cov="${baseline_cov:-N/A}"
-    current_cov="${current_cov:-N/A}"
-
-    {
-        echo "<!-- DO NOT EDIT MANUALLY — generated by retro.sh -->"
-        echo ""
-        echo "# Test Coverage Report"
-        echo ""
-        echo "**Generated:** $timestamp"
-        echo ""
-        echo "## Coverage Summary"
-        echo ""
-        echo "| Metric | Value |"
-        echo "|--------|-------|"
-        echo "| Baseline (sprint start) | ${baseline_cov}% |"
-        echo "| Final (sprint end) | ${current_cov}% |"
-
-        if [[ "$baseline_cov" != "N/A" && "$current_cov" != "N/A" ]]; then
-            delta=$((current_cov - baseline_cov))
-            echo "| Delta | +${delta}% |"
-        fi
-
-        echo ""
-        echo "## Per-Story Coverage Deltas"
-        echo ""
-        echo "| Story | Title | Before | After | Delta |"
-        echo "|-------|-------|--------|-------|-------|"
-
-        if [[ -f "$PROGRESS_FILE" ]]; then
-            jq -r '.tasks[] | "\(.id)\t\(.title)\t\(.coverage_delta.before // "N/A")\t\(.coverage_delta.after // "N/A")"' "$PROGRESS_FILE" 2>/dev/null | \
-            while IFS=$'\t' read -r id title before after; do
-                d=""
-                if [[ "$before" != "N/A" && "$after" != "N/A" && "$before" != "null" && "$after" != "null" ]]; then
-                    d="+$((after - before))%"
-                fi
-                echo "| $id | ${title:0:30} | ${before}% | ${after}% | $d |"
-            done
-        fi
-    } > "$COV_FILE"
-
-    echo "[OK] Coverage report generated → $COV_FILE"
-fi
-
-# ─── Follow-up story generation ───────────────────────────────────────────
-
-if [[ "$GENERATE_FOLLOWUP" == "true" ]]; then
-    FOLLOWUP_FILE="$PROJECT_DIR/docs/quality/retro-followup.md"
-    followup_num=0
-
-    {
-        echo "# Sprint Retrospective Follow-up Items"
-        echo ""
-        echo "**Generated:** $timestamp"
-        echo ""
-        echo "Review and approve items below before adding to next sprint."
-        echo ""
-        echo "| # | Type | Item | Source |"
-        echo "|---|------|------|--------|"
-
-        # Carry-forward: incomplete stories
-        if [[ -f "$PROGRESS_FILE" ]]; then
-            jq -r '.tasks[] | select(.status != "complete") | "\(.id)\t\(.title)"' "$PROGRESS_FILE" 2>/dev/null | \
-            while IFS=$'\t' read -r id title; do
-                followup_num=$((followup_num + 1))
-                echo "| $followup_num | carry-forward | Story $id: $title (pending/incomplete) | Sprint backlog |"
-            done
-        fi
-
-        # High-iteration stories: need better AC
-        if [[ -f "$PROGRESS_FILE" ]]; then
-            jq -r '.tasks[] | select(.iterations > 3) | "\(.id)\t\(.title)\t\(.iterations)"' "$PROGRESS_FILE" 2>/dev/null | \
-            while IFS=$'\t' read -r id title iters; do
-                followup_num=$((followup_num + 1))
-                echo "| $followup_num | story | Refine AC for $id ($title) — took $iters iterations | Retro analysis |"
-            done
-        fi
-
-        # Verification failures: enforcement gaps
-        if [[ -f "$VLOG_FILE" && $v_fail -gt 0 ]]; then
-            followup_num=$((followup_num + 1))
-            echo "| $followup_num | enforcement | Review $v_fail verification failures — check gate coverage | Verification log |"
-        fi
-
-    } > "$FOLLOWUP_FILE"
-
-    echo "[OK] Follow-up items generated → $FOLLOWUP_FILE"
-fi
-
-echo "[OK] Retro report generated → $OUTPUT_FILE"