shipwright-cli 3.1.0 → 3.3.0

package/docs/plans/2026-03-01-pipeline-audit-trail-plan.md

@@ -0,0 +1,770 @@
+# Pipeline Audit Trail Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add structured, compliance-grade audit logging so every pipeline run produces full prompt-in → plan-out → test-evidence → audit-verdict → outcome traceability.
+
+**Architecture:** A new `scripts/lib/audit-trail.sh` library provides four functions (`audit_init`, `audit_emit`, `audit_save_prompt`, `audit_finalize`). These are called inline from existing code at key decision points. Events append to a crash-safe JSONL file. At pipeline end, `audit_finalize` reads the JSONL and generates both `pipeline-audit.json` (machine-readable) and `pipeline-audit.md` (human-readable compliance report). All audit calls are wrapped in `|| true` (fail-open — never blocks the pipeline).
+
+**Tech Stack:** Bash, jq, JSONL
+
+---
+
+### Task 1: Create `audit-trail.sh` Library — Tests First
+
+**Files:**
+- Create: `scripts/lib/audit-trail.sh`
+- Create: `scripts/sw-lib-audit-trail-test.sh`
+
+**Step 1: Write the test file skeleton**
+
+Create `scripts/sw-lib-audit-trail-test.sh`:
+
+```bash
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  audit-trail test suite                                                 ║
+# ║  Tests audit init, emit, prompt save, and finalize                      ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+set -euo pipefail
+trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/test-helpers.sh"
+
+print_test_header "Lib: audit-trail Tests"
+
+setup_test_env "sw-lib-audit-trail-test"
+trap cleanup_test_env EXIT
+
+# Provide required globals that audit-trail.sh expects
+ARTIFACTS_DIR="$TEST_TEMP_DIR/pipeline-artifacts"
+LOG_DIR="$TEST_TEMP_DIR/loop-logs"
+mkdir -p "$ARTIFACTS_DIR" "$LOG_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit_init creates JSONL and writes pipeline.start event
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_init() {
+    # Set up pipeline globals
+    ISSUE_NUMBER=42
+    GOAL="Add login page"
+    PIPELINE_NAME="standard"
+    MODEL="sonnet"
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+    audit_init
+
+    local jsonl="$ARTIFACTS_DIR/pipeline-audit.jsonl"
+    assert_pass "audit_init creates JSONL file" test -f "$jsonl"
+
+    local event_type
+    event_type=$(head -1 "$jsonl" | jq -r '.type')
+    assert_eq "first event is pipeline.start" "pipeline.start" "$event_type"
+
+    local issue
+    issue=$(head -1 "$jsonl" | jq -r '.issue')
+    assert_eq "pipeline.start has issue number" "42" "$issue"
+
+    local goal
+    goal=$(head -1 "$jsonl" | jq -r '.goal')
+    assert_eq "pipeline.start has goal" "Add login page" "$goal"
+}
+test_audit_init
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit_emit appends structured JSON lines
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_emit() {
+    # Reset
+    ARTIFACTS_DIR="$TEST_TEMP_DIR/emit-test"
+    mkdir -p "$ARTIFACTS_DIR"
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+    _AUDIT_JSONL="$ARTIFACTS_DIR/pipeline-audit.jsonl"
+    : > "$_AUDIT_JSONL"
+
+    audit_emit "stage.start" "stage=build" "config=standard"
+    audit_emit "stage.complete" "stage=build" "verdict=pass" "duration_s=120"
+
+    local line_count
+    line_count=$(wc -l < "$_AUDIT_JSONL" | tr -d ' ')
+    assert_eq "two events emitted" "2" "$line_count"
+
+    local type1 type2
+    type1=$(sed -n '1p' "$_AUDIT_JSONL" | jq -r '.type')
+    type2=$(sed -n '2p' "$_AUDIT_JSONL" | jq -r '.type')
+    assert_eq "first event type" "stage.start" "$type1"
+    assert_eq "second event type" "stage.complete" "$type2"
+
+    local verdict
+    verdict=$(sed -n '2p' "$_AUDIT_JSONL" | jq -r '.verdict')
+    assert_eq "stage.complete has verdict" "pass" "$verdict"
+
+    # Verify each line is valid JSON
+    local valid=true
+    while IFS= read -r line; do
+        echo "$line" | jq . >/dev/null 2>&1 || valid=false
+    done < "$_AUDIT_JSONL"
+    assert_pass "all lines are valid JSON" $valid
+}
+test_audit_emit
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit_save_prompt writes prompt file and returns path
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_save_prompt() {
+    LOG_DIR="$TEST_TEMP_DIR/prompt-test"
+    mkdir -p "$LOG_DIR"
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+
+    local prompt_text="You are a coding agent. Build the login page."
+    audit_save_prompt "$prompt_text" 3
+
+    local prompt_file="$LOG_DIR/iteration-3.prompt.txt"
+    assert_pass "prompt file created" test -f "$prompt_file"
+
+    local content
+    content=$(cat "$prompt_file")
+    assert_eq "prompt content matches" "$prompt_text" "$content"
+}
+test_audit_save_prompt
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit_emit with timestamp has ISO-8601 format
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_timestamp_format() {
+    ARTIFACTS_DIR="$TEST_TEMP_DIR/ts-test"
+    mkdir -p "$ARTIFACTS_DIR"
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+    _AUDIT_JSONL="$ARTIFACTS_DIR/pipeline-audit.jsonl"
+    : > "$_AUDIT_JSONL"
+
+    audit_emit "test.event" "key=value"
+
+    local ts
+    ts=$(head -1 "$_AUDIT_JSONL" | jq -r '.ts')
+    # ISO-8601 format: YYYY-MM-DDTHH:MM:SSZ
+    assert_pass "timestamp is ISO-8601" echo "$ts" | grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$'
+}
+test_audit_timestamp_format
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit_finalize generates JSON and Markdown reports
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_finalize() {
+    ARTIFACTS_DIR="$TEST_TEMP_DIR/finalize-test"
+    LOG_DIR="$TEST_TEMP_DIR/finalize-logs"
+    mkdir -p "$ARTIFACTS_DIR" "$LOG_DIR"
+
+    ISSUE_NUMBER=99
+    GOAL="Fix bug"
+    PIPELINE_NAME="fast"
+    MODEL="haiku"
+    PIPELINE_START_EPOCH=$(date +%s)
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+    _AUDIT_JSONL="$ARTIFACTS_DIR/pipeline-audit.jsonl"
+
+    # Simulate a pipeline run
+    audit_emit "pipeline.start" "issue=99" "goal=Fix bug" "template=fast" "model=haiku"
+    audit_emit "stage.start" "stage=intake"
+    audit_emit "stage.complete" "stage=intake" "verdict=pass" "duration_s=30"
+    audit_emit "stage.start" "stage=build"
+    audit_emit "loop.prompt" "iteration=1" "chars=15000" "path=iteration-1.prompt.txt"
+    audit_emit "loop.response" "iteration=1" "chars=5000" "exit_code=0" "tokens_in=3750" "tokens_out=1250"
+    audit_emit "loop.test_gate" "iteration=1" "commands=1" "all_passed=true"
+    audit_emit "stage.complete" "stage=build" "verdict=pass" "duration_s=180"
+    audit_emit "pipeline.complete" "outcome=success" "duration_s=210"
+
+    audit_finalize "success"
+
+    # Check JSON report
+    local json_report="$ARTIFACTS_DIR/pipeline-audit.json"
+    assert_pass "JSON report created" test -f "$json_report"
+
+    local outcome
+    outcome=$(jq -r '.outcome' "$json_report")
+    assert_eq "JSON has outcome" "success" "$outcome"
+
+    local stage_count
+    stage_count=$(jq '.stages | length' "$json_report")
+    assert_pass "JSON has stages array" test "$stage_count" -gt 0
+
+    # Check Markdown report
+    local md_report="$ARTIFACTS_DIR/pipeline-audit.md"
+    assert_pass "Markdown report created" test -f "$md_report"
+    assert_pass "Markdown has header" grep -q "Pipeline Audit Report" "$md_report"
+    assert_pass "Markdown has stage table" grep -q "intake" "$md_report"
+    assert_pass "Markdown has outcome" grep -q "success" "$md_report"
+}
+test_audit_finalize
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test: audit functions are fail-open (don't crash on bad input)
+# ═══════════════════════════════════════════════════════════════════════════════
+test_audit_fail_open() {
+    ARTIFACTS_DIR="/nonexistent/path"
+    LOG_DIR="/nonexistent/path"
+
+    source "$SCRIPT_DIR/lib/audit-trail.sh"
+
+    # These should not crash (fail-open)
+    audit_emit "test.event" "key=value" 2>/dev/null || true
+    assert_pass "audit_emit survives bad ARTIFACTS_DIR" true
+
+    audit_save_prompt "test prompt" 1 2>/dev/null || true
+    assert_pass "audit_save_prompt survives bad LOG_DIR" true
+}
+test_audit_fail_open
+
+# ═══════════════════════════════════════════════════════════════════════════════
+print_test_summary
+```
+
+**Step 2: Run the tests to verify they fail**
+
+Run: `bash scripts/sw-lib-audit-trail-test.sh`
+Expected: FAIL with "audit-trail.sh: No such file" or "audit_init: command not found"
+
+**Step 3: Write `scripts/lib/audit-trail.sh`**
+
+```bash
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  audit-trail.sh — Structured pipeline audit logging                     ║
+# ║                                                                         ║
+# ║  Provides compliance-grade traceability for pipeline runs:              ║
+# ║  prompt in → plan out → test evidence → audit verdict → outcome.       ║
+# ║                                                                         ║
+# ║  All functions are fail-open (|| true). Audit never blocks pipeline.   ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+[[ -n "${_AUDIT_TRAIL_LOADED:-}" ]] && return 0
+_AUDIT_TRAIL_LOADED=1
+
+# ─── Internal State ──────────────────────────────────────────────────────────
+_AUDIT_JSONL="${ARTIFACTS_DIR:-/tmp}/pipeline-audit.jsonl"
+
+# ─── audit_init ──────────────────────────────────────────────────────────────
+# Creates the JSONL file and writes the pipeline.start event.
+# Call once at pipeline start (from sw-pipeline.sh).
+audit_init() {
+    _AUDIT_JSONL="${ARTIFACTS_DIR:-/tmp}/pipeline-audit.jsonl"
+    mkdir -p "$(dirname "$_AUDIT_JSONL")" 2>/dev/null || return 0
+
+    local git_sha
+    git_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+
+    audit_emit "pipeline.start" \
+        "issue=${ISSUE_NUMBER:-0}" \
+        "goal=${GOAL:-}" \
+        "template=${PIPELINE_NAME:-unknown}" \
+        "model=${MODEL:-unknown}" \
+        "git_sha=$git_sha"
+}
+
+# ─── audit_emit ──────────────────────────────────────────────────────────────
+# Appends one JSON line to the audit JSONL.
+# Usage: audit_emit "event.type" "key1=val1" "key2=val2" ...
+audit_emit() {
+    local event_type="${1:-unknown}"; shift
+
+    local ts
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "unknown")
+
+    # Build JSON object
+    local json="{\"ts\":\"$ts\",\"type\":\"$event_type\""
+    while [[ $# -gt 0 ]]; do
+        local key="${1%%=*}"
+        local val="${1#*=}"
+        # Escape double quotes in values
+        val="${val//\"/\\\"}"
+        json="${json},\"${key}\":\"${val}\""
+        shift
+    done
+    json="${json}}"
+
+    echo "$json" >> "$_AUDIT_JSONL" 2>/dev/null || true
+}
+
+# ─── audit_save_prompt ───────────────────────────────────────────────────────
+# Saves the full prompt text to iteration-N.prompt.txt before sending to Claude.
+# Usage: audit_save_prompt "$prompt_text" "$iteration_number"
+audit_save_prompt() {
+    local prompt_text="${1:-}"
+    local iteration="${2:-0}"
+    local prompt_file="${LOG_DIR:-/tmp}/iteration-${iteration}.prompt.txt"
+
+    mkdir -p "$(dirname "$prompt_file")" 2>/dev/null || return 0
+    echo "$prompt_text" > "$prompt_file" 2>/dev/null || true
+}
+
+# ─── audit_finalize ──────────────────────────────────────────────────────────
+# Reads the JSONL and generates pipeline-audit.json + pipeline-audit.md.
+# Call once at pipeline end (success or failure).
+# Usage: audit_finalize "success|failure"
+audit_finalize() {
+    local outcome="${1:-unknown}"
+    local json_report="${ARTIFACTS_DIR:-/tmp}/pipeline-audit.json"
+    local md_report="${ARTIFACTS_DIR:-/tmp}/pipeline-audit.md"
+
+    [[ ! -f "$_AUDIT_JSONL" ]] && return 0
+
+    # ── Build JSON report ──
+    _audit_build_json "$outcome" > "$json_report" 2>/dev/null || true
+
+    # ── Build Markdown report ──
+    _audit_build_markdown "$outcome" > "$md_report" 2>/dev/null || true
+}
+
+# ─── Internal: JSON report builder ──────────────────────────────────────────
+_audit_build_json() {
+    local outcome="$1"
+    local duration_s=0
+    [[ -n "${PIPELINE_START_EPOCH:-}" ]] && duration_s=$(( $(date +%s) - PIPELINE_START_EPOCH ))
+
+    # Extract stages from JSONL
+    local stages="[]"
+    if command -v jq >/dev/null 2>&1; then
+        # Group stage.start + stage.complete pairs
+        stages=$(jq -s '
+            [.[] | select(.type == "stage.complete")] |
+            map({
+                name: .stage,
+                verdict: .verdict,
+                duration_s: (.duration_s // "0" | tonumber)
+            })
+        ' "$_AUDIT_JSONL" 2>/dev/null || echo "[]")
+
+        # Extract iterations from loop events
+        local iterations="[]"
+        iterations=$(jq -s '
+            [.[] | select(.type == "loop.prompt" or .type == "loop.response" or .type == "loop.test_gate")] |
+            group_by(.iteration) |
+            map({
+                number: (.[0].iteration // "0" | tonumber),
+                prompt_chars: ([.[] | select(.type == "loop.prompt") | .chars // "0" | tonumber] | first // 0),
+                prompt_path: ([.[] | select(.type == "loop.prompt") | .path // ""] | first // ""),
+                response_chars: ([.[] | select(.type == "loop.response") | .chars // "0" | tonumber] | first // 0),
+                exit_code: ([.[] | select(.type == "loop.response") | .exit_code // "0" | tonumber] | first // 0),
+                tests_passed: ([.[] | select(.type == "loop.test_gate") | .all_passed // ""] | first // "")
+            }) | sort_by(.number)
+        ' "$_AUDIT_JSONL" 2>/dev/null || echo "[]")
+
+        # Assemble final JSON
+        jq -n \
+            --arg version "1.0" \
+            --arg pipeline_id "pipeline-${ISSUE_NUMBER:-0}" \
+            --argjson issue "${ISSUE_NUMBER:-0}" \
+            --arg outcome "$outcome" \
+            --arg goal "${GOAL:-}" \
+            --arg template "${PIPELINE_NAME:-unknown}" \
+            --arg model "${MODEL:-unknown}" \
+            --argjson duration_s "$duration_s" \
+            --argjson stages "$stages" \
+            --argjson iterations "$iterations" \
+            '{
+                version: $version,
+                pipeline_id: $pipeline_id,
+                issue: $issue,
+                outcome: $outcome,
+                goal: $goal,
+                template: $template,
+                model: $model,
+                duration_s: $duration_s,
+                stages: $stages,
+                iterations: $iterations
+            }'
+    else
+        # Fallback without jq
+        echo "{\"version\":\"1.0\",\"outcome\":\"$outcome\",\"duration_s\":$duration_s}"
+    fi
+}
+
+# ─── Internal: Markdown report builder ──────────────────────────────────────
+_audit_build_markdown() {
+    local outcome="$1"
+    local duration_s=0
+    [[ -n "${PIPELINE_START_EPOCH:-}" ]] && duration_s=$(( $(date +%s) - PIPELINE_START_EPOCH ))
+
+    # Format duration
+    local duration_fmt="${duration_s}s"
+    if [[ "$duration_s" -ge 60 ]]; then
+        duration_fmt="$(( duration_s / 60 ))m $(( duration_s % 60 ))s"
+    fi
+
+    cat <<HEADER
+# Pipeline Audit Report — Issue #${ISSUE_NUMBER:-0}
+
+| Field | Value |
+|---|---|
+| **Pipeline** | ${PIPELINE_NAME:-unknown} |
+| **Issue** | #${ISSUE_NUMBER:-0} |
+| **Goal** | ${GOAL:-N/A} |
+| **Model** | ${MODEL:-unknown} |
+| **Duration** | ${duration_fmt} |
+| **Outcome** | ${outcome} |
+
+## Stage Summary
+
+| Stage | Duration | Verdict |
+|---|---|---|
+HEADER
+
+    # Extract stage rows from JSONL
+    if command -v jq >/dev/null 2>&1; then
+        jq -r 'select(.type == "stage.complete") |
+            "| \(.stage) | \(.duration_s // "?")s | \(.verdict // "?") |"' \
+            "$_AUDIT_JSONL" 2>/dev/null || true
+    fi
+
+    echo ""
+    echo "## Build Loop Detail"
+    echo ""
+
+    # Extract iteration details
+    if command -v jq >/dev/null 2>&1; then
+        jq -r 'select(.type == "loop.prompt") |
+            "### Iteration \(.iteration)\n- **Prompt**: \(.chars // "?") chars → \(.path // "N/A")\n"' \
+            "$_AUDIT_JSONL" 2>/dev/null || true
+
+        jq -r 'select(.type == "loop.response") |
+            "- **Response**: \(.chars // "?") chars, exit \(.exit_code // "?")\n"' \
+            "$_AUDIT_JSONL" 2>/dev/null || true
+
+        jq -r 'select(.type == "loop.test_gate") |
+            "- **Tests**: \(.commands // "?") commands, all passed: \(.all_passed // "?")\n"' \
+            "$_AUDIT_JSONL" 2>/dev/null || true
+    fi
+
+    echo ""
+    echo "---"
+    echo "*Generated by Shipwright audit-trail v1.0*"
+}
+```
+
+**Step 4: Run the tests**
+
+Run: `bash scripts/sw-lib-audit-trail-test.sh`
+Expected: All tests PASS
+
+**Step 5: Commit**
+
+```bash
+git add scripts/lib/audit-trail.sh scripts/sw-lib-audit-trail-test.sh
+git commit -m "feat(audit): add audit-trail.sh library with tests
+
+TDD: emit, save prompt, finalize to JSON + Markdown.
+All functions fail-open (|| true)."
+```
+
+---
+
+### Task 2: Save Prompts in `loop-iteration.sh`
+
+**Files:**
+- Modify: `scripts/lib/loop-iteration.sh:459-470`
+
+**Step 1: Write the test**
+
+Add to `scripts/sw-lib-audit-trail-test.sh` (or verify manually):
+
+The integration test is: after a loop iteration runs, `iteration-N.prompt.txt` exists in LOG_DIR.
+
+For now we verify by reading the code change — the unit tests in Task 1 cover `audit_save_prompt`.
+
+**Step 2: Modify `run_claude_iteration()` in `scripts/lib/loop-iteration.sh`**
+
+Find this block (lines 465-470):
+
+```bash
+    final_prompt=$(manage_context_window "$prompt")
+
+    local raw_prompt_chars=${#prompt}
+    local prompt_chars=${#final_prompt}
+    local approx_tokens=$((prompt_chars / 4))
+    info "Prompt: ~${approx_tokens} tokens (${prompt_chars} chars)"
+```
+
+Insert after `info "Prompt:..."` (after line 470):
+
+```bash
+    # Audit: save full prompt to disk for traceability
+    if type audit_save_prompt >/dev/null 2>&1; then
+        audit_save_prompt "$final_prompt" "$ITERATION" || true
+    fi
+    if type audit_emit >/dev/null 2>&1; then
+        audit_emit "loop.prompt" "iteration=$ITERATION" "chars=$prompt_chars" \
+            "raw_chars=$raw_prompt_chars" "path=iteration-${ITERATION}.prompt.txt" || true
+    fi
+```
+
+After the Claude response is processed (after line 530, the `accumulate_loop_tokens` call), add:
+
+```bash
+    # Audit: record response metadata
+    if type audit_emit >/dev/null 2>&1; then
+        local response_chars=0
+        [[ -f "$log_file" ]] && response_chars=$(wc -c < "$log_file" | tr -d ' ')
+        audit_emit "loop.response" "iteration=$ITERATION" "chars=$response_chars" \
+            "exit_code=$exit_code" "duration_s=$iter_duration" \
+            "path=iteration-${ITERATION}.json" || true
+    fi
+```
+
+**Step 3: Run the loop tests**
+
+Run: `bash scripts/sw-loop-test.sh`
+Expected: 56/61 pass (same as before — 5 pre-existing failures)
+
+**Step 4: Commit**
+
+```bash
+git add scripts/lib/loop-iteration.sh
+git commit -m "feat(audit): save prompts + emit loop events
+
+Captures iteration-N.prompt.txt before each Claude call.
+Emits loop.prompt and loop.response audit events."
+```
+
+---
+
+### Task 3: Emit Test Gate and Verification Gap Events in `sw-loop.sh`
+
+**Files:**
+- Modify: `scripts/sw-loop.sh:987-992` (after test evidence JSON write)
+- Modify: `scripts/sw-loop.sh:2231-2240` (verification gap handler)
+
+**Step 1: Add test gate audit event**
+
+After the existing test evidence write (line 989-990):
+
+```bash
+    # Write structured test evidence
+    if command -v jq >/dev/null 2>&1; then
+        echo "$test_results" > "${LOG_DIR}/test-evidence-iter-${ITERATION}.json"
+    fi
+```
+
+Add:
+
+```bash
+    # Audit: emit test gate event
+    if type audit_emit >/dev/null 2>&1; then
+        local cmd_count=0
+        command -v jq >/dev/null 2>&1 && cmd_count=$(echo "$test_results" | jq 'length' 2>/dev/null || echo 0)
+        audit_emit "loop.test_gate" "iteration=$ITERATION" "commands=$cmd_count" \
+            "all_passed=$all_passed" "evidence_path=test-evidence-iter-${ITERATION}.json" || true
+    fi
+```
+
+**Step 2: Add verification gap audit events**
+
+In the verification gap handler (after line 2234, the "override_audit" emit_event), add:
+
+```bash
+                audit_emit "loop.verification_gap" "iteration=$ITERATION" \
+                    "resolution=override" "tests_recheck=pass" || true
+```
+
+After line 2238 (the "retry" emit_event), add:
+
+```bash
+                audit_emit "loop.verification_gap" "iteration=$ITERATION" \
+                    "resolution=retry" "tests_recheck=fail" || true
+```
+
+**Step 3: Source `audit-trail.sh` in sw-loop.sh imports**
+
+At line 43 (after the error-actionability source), add:
+
+```bash
+# Audit trail for compliance-grade pipeline traceability
+[[ -f "$SCRIPT_DIR/lib/audit-trail.sh" ]] && source "$SCRIPT_DIR/lib/audit-trail.sh" 2>/dev/null || true
+```
+
+**Step 4: Run the tests**
+
+Run: `bash scripts/sw-loop-test.sh`
+Expected: 56/61 pass (unchanged)
+
+Run: `bash scripts/sw-lib-audit-trail-test.sh`
+Expected: All pass
+
+**Step 5: Commit**
+
+```bash
+git add scripts/sw-loop.sh
+git commit -m "feat(audit): emit test gate + verification gap events
+
+Adds audit events in run_test_gate() and verification gap handler.
+Sources audit-trail.sh library."
+```
+
+---
+
+### Task 4: Add Stage Events and Finalization in `sw-pipeline.sh`
+
+**Files:**
+- Modify: `scripts/sw-pipeline.sh:1374-1395` (run_pipeline start)
+- Modify: `scripts/sw-pipeline.sh:2500-2565` (pipeline completion)
+
+**Step 1: Source audit-trail.sh and call audit_init**
+
+Near the top of `sw-pipeline.sh` (after existing source statements), add:
+
+```bash
+# Audit trail for compliance-grade pipeline traceability
+[[ -f "$SCRIPT_DIR/lib/audit-trail.sh" ]] && source "$SCRIPT_DIR/lib/audit-trail.sh" 2>/dev/null || true
+```
+
+At the start of `run_pipeline()` (line 1376, after `rotate_event_log_if_needed`), add:
+
+```bash
+    # Initialize audit trail for this pipeline run
+    if type audit_init >/dev/null 2>&1; then
+        audit_init || true
+    fi
+```
+
+**Step 2: Add stage start/complete events**
+
+In the `run_pipeline()` stage loop, find where each stage runs. There's a section where `stage_*` functions are called (inside the `while IFS= read` loop). Before each stage function call (after the enabled check around line 1433), add:
+
+```bash
+        # Audit: stage start
+        if type audit_emit >/dev/null 2>&1; then
+            audit_emit "stage.start" "stage=$id" || true
+        fi
+```
+
+After each stage completes (near the "Stage X complete" success message), add:
+
+```bash
+        # Audit: stage complete
+        if type audit_emit >/dev/null 2>&1; then
+            audit_emit "stage.complete" "stage=$id" "verdict=pass" \
+                "duration_s=${stage_duration:-0}" || true
+        fi
+```
+
+For stage failures (near the "Pipeline failed at stage" error message around line 1678), add:
+
+```bash
+            if type audit_emit >/dev/null 2>&1; then
+                audit_emit "stage.complete" "stage=$id" "verdict=fail" \
+                    "duration_s=${stage_duration:-0}" || true
+            fi
+```
+
+**Step 3: Call audit_finalize at pipeline completion**
+
+At line 2520 (after the success `emit_event "pipeline.completed"`), add:
+
+```bash
+        # Finalize audit trail
+        if type audit_finalize >/dev/null 2>&1; then
+            audit_finalize "success" || true
+        fi
+```
+
+At line 2565 (after the failure `emit_event "pipeline.completed"`), add:
+
+```bash
+        # Finalize audit trail
+        if type audit_finalize >/dev/null 2>&1; then
+            audit_finalize "failure" || true
+        fi
+```
+
+**Step 4: Run existing pipeline tests**
+
+Run: `bash scripts/sw-pipeline-test.sh`
+Expected: All existing tests pass (audit is fail-open, won't break anything)
+
+**Step 5: Commit**
+
+```bash
+git add scripts/sw-pipeline.sh
+git commit -m "feat(audit): pipeline-level audit init, stage events, finalize
+
+Calls audit_init at pipeline start, emits stage.start/complete
+for each stage, and audit_finalize at pipeline end to generate
+pipeline-audit.json + pipeline-audit.md reports."
+```
+
+---
+
+### Task 5: Integration Verification
+
+**Files:**
+- No new files — verification only
+
+**Step 1: Run all audit tests**
+
+Run: `bash scripts/sw-lib-audit-trail-test.sh`
+Expected: All pass
+
+**Step 2: Run loop tests**
+
+Run: `bash scripts/sw-loop-test.sh`
+Expected: 56/61 pass (5 pre-existing)
+
+**Step 3: Run detection tests**
+
+Run: `bash scripts/sw-lib-pipeline-detection-test.sh`
+Expected: 70/70 pass
+
+**Step 4: Run full npm test suite**
+
+Run: `npm test`
+Expected: 191+ tests pass
+
+**Step 5: Run patrol meta-check (bash compat)**
+
+Run: `bash scripts/sw-patrol-meta.sh scripts/lib/audit-trail.sh`
+Expected: No `readarray`/`mapfile` violations
+
+**Step 6: Commit version bump**
+
+```bash
+# Bump sw-loop.sh VERSION to 3.4.0
+sed -i '' 's/VERSION="3.3.0"/VERSION="3.4.0"/' scripts/sw-loop.sh
+git add scripts/sw-loop.sh
+git commit -m "chore: bump sw-loop version to 3.4.0
+
+Audit trail feature complete:
+- pipeline-audit.jsonl (crash-safe event log)
+- pipeline-audit.json (machine-readable summary)
+- pipeline-audit.md (compliance report)
+- iteration-N.prompt.txt (full prompt preservation)"
+```
+
+**Step 7: Push**
+
+```bash
+git push origin main
+```
+
+---
+
+## File Summary
+
+| File | Action | Purpose |
+|---|---|---|
+| `scripts/lib/audit-trail.sh` | CREATE | Library: audit_init, audit_emit, audit_save_prompt, audit_finalize |
+| `scripts/sw-lib-audit-trail-test.sh` | CREATE | Tests for all audit functions |
+| `scripts/lib/loop-iteration.sh` | MODIFY | Save prompts, emit loop.prompt/loop.response events |
+| `scripts/sw-loop.sh` | MODIFY | Source library, emit test_gate/verification_gap events |
+| `scripts/sw-pipeline.sh` | MODIFY | Source library, audit_init, stage events, audit_finalize |
+
+## Verification Checklist
+
+- [ ] `bash scripts/sw-lib-audit-trail-test.sh` — all pass
+- [ ] `bash scripts/sw-loop-test.sh` — 56/61 (5 pre-existing)
+- [ ] `bash scripts/sw-lib-pipeline-detection-test.sh` — 70/70
+- [ ] `npm test` — 191+ pass
+- [ ] `bash scripts/sw-patrol-meta.sh scripts/lib/audit-trail.sh` — no bash compat violations
+- [ ] Run real pipeline — verify `pipeline-audit.jsonl`, `.json`, `.md` generated