Iteration Waste & Stuck Loop Detector with Early Termination

[github-actions]

Strategic Improvement

Detects when build loop makes no meaningful progress (circular edits, recurring identical errors, no file changes, semantically similar consecutive edits). Triggers early termination with diagnostic report instead of burning all iterations. Saves $2-5 per stuck run, improves cost efficiency, reduces developer frustration from spinning loops.

Acceptance Criteria

• Monitors iterations for waste signals: identical error signatures, circular file edits, semantic similarity below threshold, zero file changes
• Configurable thresholds in daemon-config.json (min_progress_threshold, circular_edit_window, semantic_similarity_threshold)
• Early termination after N consecutive waste iterations with structured diagnostic report
• Emits waste_detected event to events.jsonl with iteration details for learning
• Dashboard shows waste detection metrics, trends, and cost savings
• Documentation in CLAUDE.md under build loop capabilities

Context

• Priority: P0
• Complexity: standard
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P0: Reliability & Success Rate

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Improves build loop reliability and cost efficiency by detecting stuck iterations; touches loop logic, config, events, and dashboard but is well-scoped.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25252018195

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (214 lines)

Implementation Plan: Iteration Waste & Stuck Loop Detector

Approach Decision (Socratic Refinement)

Minimum viable change: Add a new scripts/lib/loop-waste-detector.sh module sourced by sw-loop.sh. After each iteration, it computes waste signals (identical errors, circular edits, low semantic similarity, zero file changes) and increments a counter. When consecutive_waste >= threshold, it returns a non-zero status that the main loop checks alongside the existing circuit breaker, terminating early with a diagnostic report.

Alternatives considered:

1. Inline detection in sw-loop.sh — Lower complexity, but bloats an already 2675-line file. Harder to test in isolation. Rejected.
2. Standalone command (shipwright waste) — Higher reuse, but adds CLI surface and requires IPC with the loop. Overkill for a per-iteration check. Rejected.
3. Lib module sourced into the loop ✅ — Matches existing pattern (loop-convergence.sh, loop-progress.sh). Testable via standalone *-test.sh. Lowest blast radius. Chosen.

Why this approach: The codebase already has CIRCUIT_BREAKER_THRESHOLD and MIN_PROGRESS_LINES for similar detection. We extend this pattern rather than replacing it — circuit breaker handles raw line-count progress; waste detector handles semantic progress (errors, file churn diversity, edit similarity).

---

Files to Modify

Create:

• scripts/lib/loop-waste-detector.sh — core detection module (~250 lines)
• scripts/sw-loop-waste-detector-test.sh — unit tests (~250 lines)

Modify:

• scripts/sw-loop.sh — source the module, call waste_detector_check per iteration, handle early termination
• .claude/daemon-config.json (template) and scripts/sw-prep.sh if it generates config — add new loop.waste_detector section
• .claude/CLAUDE.md — document under "Build Loop Capabilities" (AUTO section regen via shipwright docs sync if applicable)
• dashboard/server.ts — add /api/waste-metrics endpoint reading from events.jsonl
• dashboard/public/ — add waste detection panel (HTML/JS, small addition)
• package.json — register the new test script in the test aggregator

---

Implementation Steps

1. scripts/lib/loop-waste-detector.sh

Functions:

• waste_detector_init() — initialize state file at .claude/pipeline-artifacts/waste-state.json with {consecutive_waste: 0, last_error_hash: "", recent_files: [], recent_edit_hashes: []}. Use atomic tmp+mv writes.
• waste_detector_error_hash <error_summary_file> — normalize error text (strip line numbers, paths, timestamps) then sha256sum → 16-char hash. Returns hash on stdout.
• waste_detector_files_in_iteration <work_dir> — git -C "$work_dir" diff --name-only HEAD~1 HEAD 2>/dev/null for last commit; empty if no commit.
• waste_detector_edit_hash <work_dir> — hash of git diff HEAD~1 HEAD content (or empty).
• waste_detector_circular_score <new_files_csv> <recent_files_window> — count files in new set that appeared in any prior window iteration; return ratio 0-100. Threshold-driven.
• waste_detector_semantic_similarity <hash_a> <hash_b> — bash 3.2 fallback: exact match = 100, else 0 (no fuzzy hashing in pure bash). Hook in optional simhash python helper if available; otherwise binary similarity is sufficient for v1.
• waste_detector_check <iteration> <work_dir> <error_summary_file> — main entry. Computes signals, decides if iteration is "wasteful" using config thresholds, updates state, emits waste.signal event. Returns 0 (continue) or 2 (terminate).
• waste_detector_emit_diagnostic <reason> <iteration> — writes .claude/pipeline-artifacts/waste-diagnostic.json with iteration history, signals triggered, estimated tokens/cost saved, and emits waste.terminated event to events.jsonl.

Waste signal logic (any 2-of-4 within an iteration counts as wasteful):

1. Identical error: error_hash == last_error_hash AND non-empty
2. Zero file changes: files_in_iteration is empty
3. Circular edits: circular_score >= 80 over circular_edit_window (default 3)
4. Low semantic progress: edit_hash matches any of last N edit hashes

✅ Task Checklist

• Task 1: Create scripts/lib/loop-waste-detector.sh with core detection functions and atomic state writes
• Task 2: Implement error hash normalization (strip paths, line numbers, timestamps)
• Task 3: Implement signal computation (identical-error, zero-changes, circular, semantic)
• Task 4: Implement waste_detector_check main entry with termination return code
• Task 5: Implement waste_detector_emit_diagnostic writing JSON artifact + event
• Task 6: Source new module in scripts/sw-loop.sh and wire into iteration loop
• Task 7: Add config keys via _smart_int reads with sensible defaults
• Task 8: Add waste_detected termination status display branch
• Task 9: Update .claude/daemon-config.json template and sw-prep.sh config generator
• Task 10: Create scripts/sw-loop-waste-detector-test.sh with 8+ unit tests
• Task 11: Register test in package.json
• Task 12: Add /api/waste-metrics endpoint in dashboard/server.ts
• Task 13: Add waste detection panel to dashboard frontend
• Task 14: Document feature in .claude/CLAUDE.md under Build Loop Capabilities
• Task 15: Run full test suite (npm test) and verify no regressions
• All 15 tasks complete
• New test suite passes locally and in CI
• Existing test suites pass (no regressions)
• shipwright doctor passes
• A simulated stuck loop terminates within termination_threshold iterations

---

Generated by shipwright pipeline at 2026-05-02T12:42:14Z

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (178 lines)

Design: Iteration Waste & Stuck Loop Detector with Early Termination

Context

The build loop in scripts/sw-loop.sh (2675 lines) drives autonomous iteration but only has coarse stop conditions: circuit_breaker_threshold (consecutive raw-line failures) and max_iterations. Loops that produce identical errors, churn the same files, or commit empty diffs still consume tokens and budget until iteration cap. Memory shows baseline successful runs converge in 3–5 iterations (success-patterns.json); anything beyond that with no semantic progress is waste.

Constraints from the codebase:

• Bash 3.2 compatible — no declare -A, no readarray, no ${var,,}. Pre-tool-use hook enforces.
• All script state via JSON + jq --arg, atomic tmp + mv writes (scripts/sw-loop.sh and lib pattern).
• Worktree-parallel pipelines share .claude/ — per-run state must live in WORK_DIR.
• Existing config chain: _smart_int "loop.X" default (env → daemon-config.json → default).
• Existing lib pattern: scripts/lib/loop-convergence.sh, loop-progress.sh sourced by sw-loop.sh.
• Test harness: standalone *-test.sh with mock binaries, registered in package.json.
• Events to ~/.shipwright/events.jsonl via emit_event.

Decision

Add scripts/lib/loop-waste-detector.sh as a sourced lib module, mirroring loop-convergence.sh. State persisted as JSON inside the worktree ($WORK_DIR/.claude/pipeline-artifacts/waste-state.json) to avoid cross-pipeline races. Per-iteration evaluator computes 4 independent signals (identical-error, zero-changes, circular-edits, low-semantic-progress); 2-of-4 marks an iteration wasteful; consecutive_waste >= termination_threshold (default 3) returns non-zero from waste_detector_check, which sw-loop.sh interprets as a TERMINATION_REASON=waste_detected break alongside the existing circuit breaker check.

Data flow: loop iteration → commit + test → waste_detector_check $ITERATION $WORK_DIR $ERROR_SUMMARY_FILE → reads state, computes signals, emits waste.signal event, updates state atomically, returns 0/2 → on 2, loop emits diagnostic JSON + waste.terminated event and breaks. Dashboard reads events.jsonl for the /api/waste-metrics endpoint (no caching; file-tailed per request).

Error handling: state file missing → re-init with defaults (idempotent). git errors → treat as zero-change iteration (conservative). jq parse errors on state → log warn, reset state, do not terminate the loop (fail-open). All public functions return shell exit codes; no stderr-only failure modes.

Alternatives Considered

1. Inline detection in sw-loop.sh — Pros: no new file, simplest source change. Cons: sw-loop.sh is already 2675 lines; harder to unit test in isolation; violates single-responsibility. Rejected.
2. Standalone shipwright waste command with IPC — Pros: reusable across pipeline stages and ad-hoc runs. Cons: IPC complexity (named pipe or polling), adds CLI surface, overkill for per-iteration sync check. Rejected.
3. Lib module sourced into the loop ✅ — Pros: matches loop-convergence.sh pattern, isolated unit testing, lowest blast radius, gated via config flag. Cons: another file to maintain (~250 lines). Chosen.
4. ML/embedding-based semantic similarity — Rejected: bash 3.2 environment, no Python/Node hard dep, marginal accuracy gain over hash-based comparison for v1.

Component Diagram

┌──────────────────────────────────────────────────┐
│              scripts/sw-loop.sh                  │  (orchestrator)
│  iteration loop → check circuit_breaker          │
│              → check waste_detector ◄──┐         │
└──────────────────────────────┬─────────┼─────────┘
                               │ source  │
                               ▼         │
┌──────────────────────────────────────┐ │
│  scripts/lib/loop-waste-detector.sh  │ │
│  - waste_detector_init               │ │
│  - waste_detector_error_hash         │ │
│  - waste_detector_files_in_iteration │ │
│  - waste_detector_edit_hash          │ │
│  - waste_detector_check  ────────────┘ │
│  - waste_detector_emit_diagnostic      │
└──────────┬─────────────────────┬───────┘
           │ jq read/write       │ emit_event
           ▼                     ▼
┌────────────────────────┐  ┌──────────────────────┐
│ $WORK_DIR/.claude/     │  │ ~/.shipwright/       │
│   pipeline-artifacts/  │  │   events.jsonl       │
│   waste-state.json     │  │ (waste.signal,       │
│   waste-diagnostic.json│  │  waste.terminated)   │
└────────────────────────┘  └──────────┬───────────┘
                                       │ tail-read
                                       ▼
                        ┌──────────────────────────┐

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-05-02T12:44:48Z_

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: opus

[github-actions]

[github-actions]

[github-actions]