codeharness 0.9.0 → 0.11.0

package/dist/index.js

@@ -1348,7 +1348,7 @@ function importStoriesToBeads(stories, opts, beadsFns) {
 }
 
 // src/commands/init.ts
-var HARNESS_VERSION = true ? "0.9.0" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.11.0" : "0.0.0-dev";
 function getStackLabel(stack) {
   if (stack === "nodejs") return "Node.js (package.json)";
   if (stack === "python") return "Python";
@@ -2405,10 +2405,13 @@ function buildSpawnArgs(opts) {
   if (opts.live) {
     args.push("--live");
   }
+  if (opts.reset) {
+    args.push("--reset");
+  }
   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").option("--reset", "Clear retry counters, flagged stories, and circuit breaker before starting", false).action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const isJson = !!globalOpts.json;
     const outputOpts = { json: isJson };
@@ -2477,7 +2480,8 @@ function registerRunCommand(program) {
       iterationTimeout,
       calls,
       live: options.live,
-      maxStoryRetries
+      maxStoryRetries,
+      reset: options.reset
     });
     const env = { ...process.env };
     if (isJson) {
@@ -3294,7 +3298,7 @@ function validateProofQuality(proofPath) {
     return { verified: 0, pending: 0, escalated: 0, total: 0, passed: false };
   }
   const content = readFileSync10(proofPath, "utf-8");
-  const acHeaderPattern = /^## AC \d+:/gm;
+  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 };
@@ -6783,7 +6787,7 @@ function registerGithubImportCommand(program) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.9.0" : "0.0.0-dev";
+var VERSION = true ? "0.11.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.9.0",
+  "version": "0.11.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}
@@ -50,6 +50,9 @@ CLAUDE_OUTPUT_FORMAT="${CLAUDE_OUTPUT_FORMAT:-json}"
 CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-}"
 CLAUDE_USE_CONTINUE="${CLAUDE_USE_CONTINUE:-false}"  # Fresh context per iteration by default
 
+# Reset retry state on start
+RESET_RETRIES=false
+
 # Live output
 LIVE_OUTPUT=false
 
@@ -447,6 +450,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 +462,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 +533,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 +562,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 +577,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,11 +720,12 @@ 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)
     --live                    Show live output streaming
+    --reset                   Clear retry counters, flagged stories, and circuit breaker before starting
     --reset-circuit           Reset circuit breaker and exit
     --status                  Show current status and exit
 
@@ -736,7 +809,20 @@ main() {
         fi
     fi
 
-    # Preserve retry state across restarts (Task 5.3)
+    # Reset retry state if --reset flag was passed
+    if [[ "$RESET_RETRIES" == "true" ]]; then
+        if [[ -f "$STORY_RETRY_FILE" ]]; then
+            rm -f "$STORY_RETRY_FILE"
+            log_status "INFO" "Cleared story retry counters"
+        fi
+        if [[ -f "$FLAGGED_STORIES_FILE" ]]; then
+            rm -f "$FLAGGED_STORIES_FILE"
+            log_status "INFO" "Cleared flagged stories"
+        fi
+        reset_circuit_breaker "Reset via --reset flag"
+        log_status "INFO" "Circuit breaker reset to CLOSED"
+    fi
+
     # .story_retries and .flagged_stories are file-based — they persist automatically
 
     log_status "SUCCESS" "Ralph loop starting"
@@ -834,11 +920,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 +937,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 +995,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 +1025,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 ─────────────────────────────────────────────────────────────
@@ -975,6 +1073,10 @@ while [[ $# -gt 0 ]]; do
             LIVE_OUTPUT=true
             shift
             ;;
+        --reset)
+            RESET_RETRIES=true
+            shift
+            ;;
         --reset-circuit)
             # Derive state paths so circuit breaker uses the correct directory
             HARNESS_STATE_DIR="$(pwd)/.claude"

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"