codeharness 0.6.1

package/ralph/retro.sh

@@ -0,0 +1,298 @@
+#!/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"

package/ralph/validate_epic_docs.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# validate_epic_docs.sh — Validate architectural docs at epic completion
+# Checks that ARCHITECTURE.md exists and is current when all stories in an epic are verified.
+#
+# Usage: ralph/validate_epic_docs.sh --epic NAME --project-dir DIR --progress PATH
+
+set -e
+
+EPIC_NAME=""
+PROJECT_DIR=""
+PROGRESS_FILE=""
+
+show_help() {
+    cat << 'HELPEOF'
+Design-Doc Validation — validate architecture docs at epic completion
+
+Usage:
+    ralph/validate_epic_docs.sh --epic NAME --project-dir DIR --progress PATH
+
+Checks:
+    1. All stories in the epic are complete
+    2. ARCHITECTURE.md exists
+    3. ARCHITECTURE.md was updated since the epic's code changes
+
+Options:
+    --epic NAME         Epic name to validate (e.g., "Epic 1: Auth")
+    --project-dir DIR   Project root directory
+    --progress PATH     Path to ralph/progress.json
+    -h, --help          Show this help message
+HELPEOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        --epic)
+            EPIC_NAME="$2"
+            shift 2
+            ;;
+        --project-dir)
+            PROJECT_DIR="$2"
+            shift 2
+            ;;
+        --progress)
+            PROGRESS_FILE="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# ─── Validation ───────────────────────────────────────────────────────────
+
+if [[ -z "$EPIC_NAME" ]]; then
+    echo "Error: --epic is required" >&2
+    exit 2
+fi
+
+if [[ -z "$PROJECT_DIR" ]]; then
+    echo "Error: --project-dir is required" >&2
+    exit 2
+fi
+
+if [[ -z "$PROGRESS_FILE" ]]; then
+    echo "Error: --progress is required" >&2
+    exit 2
+fi
+
+if [[ ! -f "$PROGRESS_FILE" ]]; then
+    echo "Error: progress file not found: $PROGRESS_FILE" >&2
+    exit 2
+fi
+
+# ─── Check 1: All stories in epic are complete ────────────────────────────
+
+total_in_epic=$(jq --arg epic "$EPIC_NAME" \
+    '[.tasks[] | select(.epic == $epic)] | length' \
+    "$PROGRESS_FILE" 2>/dev/null || echo "0")
+
+if [[ "$total_in_epic" == "0" ]]; then
+    echo "[FAIL] No stories found for epic: $EPIC_NAME" >&2
+    exit 1
+fi
+
+pending_in_epic=$(jq --arg epic "$EPIC_NAME" \
+    '[.tasks[] | select(.epic == $epic and .status != "complete")] | length' \
+    "$PROGRESS_FILE" 2>/dev/null || echo "0")
+
+if [[ "$pending_in_epic" != "0" ]]; then
+    echo "[FAIL] Epic \"$EPIC_NAME\" is not complete — $pending_in_epic stories still pending" >&2
+    exit 1
+fi
+
+# ─── Check 2: ARCHITECTURE.md exists ─────────────────────────────────────
+
+ARCH_FILE="$PROJECT_DIR/ARCHITECTURE.md"
+
+if [[ ! -f "$ARCH_FILE" ]]; then
+    echo "[FAIL] ARCHITECTURE.md not found — epic \"$EPIC_NAME\" cannot be marked complete"
+    echo "  → Create ARCHITECTURE.md documenting architectural decisions from this epic"
+    exit 1
+fi
+
+# ─── Check 3: ARCHITECTURE.md is current ─────────────────────────────────
+
+# Get ARCHITECTURE.md last commit time
+arch_commit_time=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- "$ARCH_FILE" 2>/dev/null || echo "0")
+
+# Get the latest commit time across all tracked files (excluding ARCHITECTURE.md itself)
+latest_code_time=$(git -C "$PROJECT_DIR" log -1 --format="%ct" -- . 2>/dev/null || echo "0")
+
+# If code was committed after ARCHITECTURE.md, it may be stale
+if [[ $latest_code_time -gt $arch_commit_time && $arch_commit_time -gt 0 ]]; then
+    echo "[FAIL] ARCHITECTURE.md is stale — code changed after architecture doc was last updated"
+    echo "  Epic: $EPIC_NAME ($total_in_epic stories)"
+    echo "  → Update ARCHITECTURE.md to reflect architectural decisions made during this epic"
+    exit 1
+fi
+
+# ─── All checks pass ─────────────────────────────────────────────────────
+
+echo "[OK] Epic \"$EPIC_NAME\" — architecture docs validated ($total_in_epic stories verified)"
+exit 0

package/ralph/verify_gates.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+# DEPRECATED: Verification gates are now handled by the /harness-run sprint execution skill.
+# This script is kept as a standalone diagnostic tool.
+#
+# verify_gates.sh — Verification gates for the Ralph loop
+# Checks that a story has: Showboat proof, tests passing, coverage met, verification run.
+# Previously called by ralph.sh after each iteration to decide: mark done or iterate again.
+#
+# Usage:
+#   ralph/verify_gates.sh --story-id ID --project-dir DIR --progress PATH
+#
+# Exit codes:
+#   0 = all gates pass, story marked complete
+#   1 = gates failed, story needs more work (iteration incremented)
+#   2 = error (missing files, unknown story)
+
+set -e
+
+# Portable in-place sed (macOS uses -i '', Linux uses -i)
+sed_i() {
+    if sed --version 2>/dev/null | grep -q GNU; then
+        sed -i "$@"
+    else
+        sed -i '' "$@"
+    fi
+}
+
+# ─── Arguments ────────────────────────────────────────────────────────────
+
+STORY_ID=""
+PROJECT_DIR=""
+PROGRESS_FILE=""
+
+show_help() {
+    cat << 'HELPEOF'
+Verification Gates — check if a story is truly done
+
+Usage:
+    ralph/verify_gates.sh --story-id ID --project-dir DIR --progress PATH
+
+Gates checked:
+    1. Showboat proof document exists for the story
+    2. Tests have passed (session_flags.tests_passed)
+    3. Coverage at 100% (session_flags.coverage_met)
+    4. Verification has been run (session_flags.verification_run)
+
+On pass: story marked complete in progress.json, session flags reset
+On fail: iteration count incremented, failures listed
+
+Options:
+    -h, --help    Show this help message
+HELPEOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_help
+            exit 0
+            ;;
+        --story-id)
+            STORY_ID="$2"
+            shift 2
+            ;;
+        --project-dir)
+            PROJECT_DIR="$2"
+            shift 2
+            ;;
+        --progress)
+            PROGRESS_FILE="$2"
+            shift 2
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 2
+            ;;
+    esac
+done
+
+# ─── Validation ───────────────────────────────────────────────────────────
+
+if [[ -z "$STORY_ID" || -z "$PROJECT_DIR" || -z "$PROGRESS_FILE" ]]; then
+    echo "[FAIL] Missing required arguments: --story-id, --project-dir, --progress" >&2
+    exit 2
+fi
+
+STATE_FILE="$PROJECT_DIR/.claude/codeharness.local.md"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "[FAIL] Harness state file not found: $STATE_FILE — harness not initialized" >&2
+    exit 2
+fi
+
+if [[ ! -f "$PROGRESS_FILE" ]]; then
+    echo "[FAIL] Progress file not found: $PROGRESS_FILE" >&2
+    exit 2
+fi
+
+# Check that the story exists in progress
+STORY_EXISTS=$(jq -r --arg id "$STORY_ID" '.tasks[] | select(.id == $id) | .id' "$PROGRESS_FILE" 2>/dev/null)
+if [[ -z "$STORY_EXISTS" || "$STORY_EXISTS" == "null" ]]; then
+    echo "[FAIL] Story $STORY_ID not found in $PROGRESS_FILE" >&2
+    exit 2
+fi
+
+# ─── Read proof path from progress ────────────────────────────────────────
+
+PROOF_PATH=$(jq -r --arg id "$STORY_ID" \
+    '.tasks[] | select(.id == $id) | .verification.proof_path // ""' \
+    "$PROGRESS_FILE" 2>/dev/null)
+
+if [[ -z "$PROOF_PATH" ]]; then
+    PROOF_PATH="verification/${STORY_ID}-proof.md"
+fi
+
+# ─── Gate Checks ──────────────────────────────────────────────────────────
+
+FAILURES=""
+GATES_PASSED=0
+GATES_TOTAL=4
+
+# Gate 1: Showboat proof exists
+if [[ -f "$PROJECT_DIR/$PROOF_PATH" ]]; then
+    GATES_PASSED=$((GATES_PASSED + 1))
+else
+    FAILURES="${FAILURES}\n  - Showboat proof not found: $PROOF_PATH"
+fi
+
+# Gate 2: Tests passed
+TESTS_PASSED=$(grep -o 'tests_passed: *[a-z]*' "$STATE_FILE" 2>/dev/null | head -1 | awk '{print $2}')
+if [[ "$TESTS_PASSED" == "true" ]]; then
+    GATES_PASSED=$((GATES_PASSED + 1))
+else
+    FAILURES="${FAILURES}\n  - Tests not passed (tests_passed: ${TESTS_PASSED:-unknown})"
+fi
+
+# Gate 3: Coverage met
+COVERAGE_MET=$(grep -o 'coverage_met: *[a-z]*' "$STATE_FILE" 2>/dev/null | head -1 | awk '{print $2}')
+if [[ "$COVERAGE_MET" == "true" ]]; then
+    GATES_PASSED=$((GATES_PASSED + 1))
+else
+    FAILURES="${FAILURES}\n  - Test coverage not at 100% (coverage_met: ${COVERAGE_MET:-unknown})"
+fi
+
+# Gate 4: Verification run
+VERIFICATION_RUN=$(grep -o 'verification_run: *[a-z]*' "$STATE_FILE" 2>/dev/null | head -1 | awk '{print $2}')
+if [[ "$VERIFICATION_RUN" == "true" ]]; then
+    GATES_PASSED=$((GATES_PASSED + 1))
+else
+    FAILURES="${FAILURES}\n  - Verification not run (verification_run: ${VERIFICATION_RUN:-unknown})"
+fi
+
+# ─── Increment iteration count (always, on check) ─────────────────────────
+
+increment_iteration() {
+    local updated
+    updated=$(jq --arg id "$STORY_ID" \
+        '(.tasks[] | select(.id == $id)).iterations = ((.tasks[] | select(.id == $id)).iterations // 0) + 1' \
+        "$PROGRESS_FILE" 2>/dev/null)
+    if [[ -n "$updated" ]]; then
+        echo "$updated" > "$PROGRESS_FILE"
+    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"' \
+        "$PROGRESS_FILE" 2>/dev/null)
+    if [[ -n "${local_updated}" ]]; then
+        echo "${local_updated}" > "$PROGRESS_FILE"
+    fi
+
+    # Reset session flags for the next story
+    sed_i 's/tests_passed: true/tests_passed: false/' "$STATE_FILE"
+    sed_i 's/coverage_met: true/coverage_met: false/' "$STATE_FILE"
+    sed_i 's/verification_run: true/verification_run: false/' "$STATE_FILE"
+    sed_i 's/logs_queried: true/logs_queried: false/' "$STATE_FILE"
+
+    # Move exec-plan from active to completed (if exec-plans exist)
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    exec_plans_dir="$PROJECT_DIR/docs/exec-plans"
+    if [[ -f "$exec_plans_dir/active/$STORY_ID.md" && -f "$SCRIPT_DIR/exec_plans.sh" ]]; then
+        "$SCRIPT_DIR/exec_plans.sh" complete \
+            --story-id "$STORY_ID" \
+            --output-dir "$exec_plans_dir" \
+            --proof-path "$PROOF_PATH" 2>/dev/null || true
+    fi
+
+    echo "[PASS] Story $STORY_ID — all $GATES_TOTAL verification gates passed"
+    echo "  → Story marked complete, session flags reset for next story"
+    exit 0
+else
+    # Log fail event
+    append_verification_log "fail"
+
+    # Gates failed — increment iteration, report failures
+    increment_iteration
+
+    iterations=$(jq -r --arg id "$STORY_ID" \
+        '.tasks[] | select(.id == $id) | .iterations // 0' \
+        "$PROGRESS_FILE" 2>/dev/null)
+
+    echo "[BLOCKED] Story $STORY_ID — $GATES_PASSED/$GATES_TOTAL gates passed (iteration $iterations)"
+    echo -e "  Failures:$FAILURES"
+    echo ""
+    echo "  → Agent must fix failures and re-verify before story completion"
+    exit 1
+fi