** Build Loop Semantic Convergence Detector with Infinite Loop Prevention

[github-actions]

Strategic Improvement

** Current convergence detection uses line-count changes, missing semantic no-progress loops (e.g., agent alternates between two solutions, makes trivial formatting changes, or edits unrelated files). Implement AST-based semantic diff analysis, detect cyclical patterns in file changes, and abort with actionable feedback when loop detected. Prevents wasted iterations and reduces cost per pipeline.

Acceptance Criteria

• AST-based semantic diff detector (not just line counts) identifies meaningful vs trivial changes
• Cyclical pattern detector identifies loops (hash of file states, detect repetition within 3-5 iterations)
• Infinite loop abort with synthesized feedback: "Detected alternation between states A and B, consider different approach"
• Integration with build loop: abort after 2 detected cycles, write loop-summary.json with pattern evidence
• Metrics: iterations saved, cost saved, false positive rate < 5%
• Test suite with 5 loop scenarios: formatting churn, A/B alternation, unrelated file edits, silent failure loop, genuine progress
• Config knobs: cycle_detection_window, semantic_diff_threshold

Context

• Priority: ** P0
• Complexity: ** standard
• Generated by: Strategic Intelligence Agent
• Strategy alignment: ** P0: Reliability & Success Rate + P3: Cost Efficiency

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Improves core build loop reliability by detecting infinite loops through semantic analysis; reduces iteration waste and cost with well-scoped acceptance criteria.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	30083041609

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 (215 lines)

Implementation Plan — Build Loop Semantic Convergence Detector with Infinite Loop Prevention

Issue: #804 · Priority: P0 · Complexity: standard · Branch: feat/-build-loop-semantic-convergence-detecto-804

---

Context: What Already Exists

The build loop already has convergence machinery. This feature extends it — it does not replace it.

Existing module	What it does	Gap for this issue
scripts/lib/convergence.sh (594 ln)	Scores each iteration 0–100 from line-count signals; detects converged/diverging/oscillating/stalled from the score series. Integration hook convergence_integrate() returns 1/2/3.	Oscillation is inferred from score deltas, not from actual file-state cycling. Trivial (whitespace/comment) edits still score as "code changes."
scripts/lib/loop-convergence.sh (350 ln)	detect_stuckness() hashes git diff HEAD and error logs; flags "identical or zero diffs in last 3 iterations." check_progress() counts insertions vs MIN_PROGRESS_LINES.	Detects identical diffs (A,A,A) but not alternation (A,B,A,B). Hashes the raw diff, so reformatting reads as progress. Only injects a hint — never aborts with feedback.

Design principle: reuse the artifact convention (ARTIFACTS_DIR), emit_event, _smart_int config chaining, the portability shims in loop-convergence.sh, and the existing integration site in sw-loop.sh (line ~2422). Add a new, independent detector module that plugs into the same call site and can veto/abort. Do not rewrite convergence.sh or detect_stuckness.

On "AST-based" in a polyglot, bash-orchestrated repo

A true multi-language AST parser is out of scope for a standard P0 and would be a large dependency risk (Shipwright is bash + a TS dashboard; target repos are arbitrary languages). The minimum viable semantic diff that satisfies "meaningful vs trivial" is a normalized-token diff: for each changed file, strip whitespace, blank lines, and comments (language-aware by suffix, generic fallback otherwise), then hash. A change whose normalized content is unchanged is trivial (formatting/comment churn); otherwise meaningful. Deterministic, dependency-free, bash-3.2-safe, and covers the churn cases the issue explicitly names. AST parsing is documented as future work in the module header.

---

Files to Modify

Create

• scripts/lib/semantic-convergence.sh — new detector module (~320 ln). Semantic-normalized diff classifier, per-iteration file-state hashing, cyclical/A-B pattern detector, abort decision, loop-summary.json writer, metrics.
• scripts/sw-semantic-convergence-test.sh — new test suite (~380 ln, fully mocked; no real loop). The 5 required scenarios + config + false-positive cases.

Modify

• scripts/sw-loop.sh — source the new module (near lines 38–47 where sibling libs load); read the two config knobs beside MIN_PROGRESS_LINES (line ~125); add a detector call + abort branch immediately after the existing convergence_integrate case block (after line ~2450).
• .claude/daemon-config.json — add loop.cycle_detection_window and loop.semantic_diff_threshold to the existing loop object (currently circuit_breaker_threshold, min_progress_lines).
• package.json — register sw-semantic-convergence-test.sh in the test script. (sw-convergence-test.sh itself is currently unregistered — register it too while here.)
• .claude/CLAUDE.md — add two rows to the Loop Configuration table and one bullet to Build Loop Capabilities. (The AUTO test-suites section will pick up the new test file on next docs sync — do not hand-edit it.)

---

API / Function Contract & Artifact Schema

This is an internal bash module with no network surface, so the REST-specific parts of the API Design skill (endpoints, HTTP status codes, rate limiting, versioning) are N/A — see the note at the end. The equivalent contract is the function API (inputs → outputs → return codes) and the artifact schema.

semantic-convergence.sh function API

Function	Inputs	Output	Return
sc_normalize_file <path>	changed file path	normalized (comment/blank/whitespace-stripped) content on stdout	0
sc_classify_iteration	git diff --name-only HEAD~1; SEMANTIC_DIFF_THRESHOLD	meaningful | trivial | none	0
sc_state_hash	changed files (bookkeeping excluded)	short hash of normalized state	0
sc_record_state <iter> <hash> <class> <files>	—	atomic append to semantic-state-history.jsonl	0
sc_detect_cycle	history + CYCLE_DETECTION_WINDOW	JSON {cycle_type, states, cycles_seen, evidence[]}	0
sc_synthesize_feedback <cycle_json>	—	actionable feedback naming states A/B	0

✅ Task Checklist

• Task 1: Scaffold scripts/lib/semantic-convergence.sh (header, guard, VERSION, md5 shim, defaults)
• Task 2: sc_normalize_file + sc_classify_iteration (comment/whitespace strip, bookkeeping exclusion, threshold)
• Task 3: sc_state_hash (deterministic, sorted, portable)
• Task 4: sc_record_state (atomic, jq --arg-safe append)
• Task 5: sc_detect_cycle (A/B, fixed-point, k-cycle; bash-3.2 arrays)
• Task 6: sc_synthesize_feedback (names states A/B, actionable)
• Task 7: sc_compute_metrics (iterations_saved, cost_saved, false_positive; guarded)
• Task 8: sc_write_loop_summary (atomic loop-summary.json + emit_event)
• Task 9: semantic_convergence_integrate (orchestrate, return 4 on 2 cycles) + export -f
• Task 10: Wire into sw-loop.sh (source, config reads, abort branch)
• Task 11: Add knobs to daemon-config.json + docs to .claude/CLAUDE.md
• Task 12: Register tests in package.json
• Task 13: Write + pass 5-scenario suite; run sw-loop-test.sh + sw-convergence-test.sh
• Semantic diff distinguishes meaningful vs trivial vs none (normalized, not raw line count) — scenario 1.
• Cyclical detector identifies A/B and k-cycles within the window via state hashing — scenarios 2 & 4.
• Abort emits synthesized feedback naming states A and B and writes loop-summary.json with evidence[] — scenario 2 asserts fields.
• Loop aborts after 2 detected cycles with STATUS=loop_detected, exit path exercised — wiring test + scenario 2.
• Metrics present: iterations_saved, cost_saved_usd, false_positive; measured FP rate < 5% — scenario 5 + FP case.
• Config knobs cycle_detection_window, semantic_diff_threshold honored (config + env) — config test.
• New suite registered in package.json and green; sw-loop-test.sh + sw-convergence-test.sh still green.

---

Generated by shipwright pipeline at 2026-07-24T09:44:38Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (124 lines)

I have enough grounding. The plan is accurate: the integration site at sw-loop.sh:2422 matches, sw-convergence-test.sh is genuinely unregistered, the atomic-write and md5-shim conventions are real. Here is the ADR.

Design: ** Build Loop Semantic Convergence Detector with Infinite Loop Prevention

Context

The build loop (scripts/sw-loop.sh, 2675 ln) already has two convergence subsystems, but both have a blind spot the issue targets:

• scripts/lib/convergence.sh (594 ln) scores each iteration 0–100 from line-count signals and infers converged/diverging/oscillating from the score series. It loses state identity — a score of 50 twice tells you nothing about whether the same file content recurred.
• scripts/lib/loop-convergence.sh (350 ln) detect_stuckness() hashes the raw git diff HEAD. It catches identical diffs (A,A,A) but not alternation (A,B,A,B), and because it hashes raw text, reformatting reads as fresh progress. It only injects a hint; it never aborts.

The gap: an agent can thrash between two variants of the same file, or churn whitespace/comments on a settled file, forever — both score as "progress." The issue demands (a) a semantic diff that distinguishes meaningful from trivial change, (b) cyclical A/B and k-cycle detection, and (c) an abort with synthesized feedback after 2 cycles.

Hard constraints from the codebase:

• Bash 3.2 — no declare -A, readarray, ${var,,}. Confirmed conventions: atomic tmp.$$ + mv (convergence.sh:331), md5/md5sum portability shim (loop-convergence.sh:173), _smart_int config chaining, emit_event, $NO_GITHUB-safe.
• Target repos are arbitrary languages; Shipwright is bash + a TS dashboard. A true multi-language AST parser is an unacceptable dependency for a standard P0.
• The integration site is real: the convergence_integrate case block at sw-loop.sh:2422–2451, which already returns 1/2/3. A new detector must slot in immediately after and must not collide with those codes.

Decision

Add one new, independent, additive module — scripts/lib/semantic-convergence.sh — that plugs into the existing call site behind a type … >/dev/null guard and can veto/abort via a new return code 4. convergence.sh and detect_stuckness() are not modified.

Semantic diff = normalized-token hash (the minimum viable "semantic"): for each changed file, strip whitespace, blank lines, and comments (language-aware by suffix — # for sh/py/yaml, // + /* */ for js/ts/go/c/java; generic fallback otherwise), then hash. A change whose normalized content is unchanged is trivial; ≥ SEMANTIC_DIFF_THRESHOLD normalized added lines is meaningful; >0 but below is trivial; none is none. This is deterministic, dependency-free, bash-3.2-safe, and directly covers the whitespace/comment-churn cases the issue names. AST parsing is documented as future work in the module header.

Data flow (per iteration, guarded ITERATION ≥ 3):

sw-loop.sh loop body
   │  (after convergence_integrate case, line ~2451)
   ▼
semantic_convergence_integrate()          [orchestrator, returns 0|4]
   │
   ├─▶ sc_classify_iteration ──▶ sc_normalize_file (per changed file)
   │        │  git diff --name-only HEAD~1, bookkeeping excluded
   │        ▼
   │      class ∈ {meaningful, trivial, none}
   ├─▶ sc_state_hash  (normalized content, sorted by path → short hash)
   ├─▶ sc_record_state ──▶ semantic-state-history.jsonl  (atomic append)
   ├─▶ sc_detect_cycle  (tail -n window | jq -s) ──▶ cycle JSON
   │        {cycle_type, states, cycles_seen, evidence[]}
   │
   └─ if cycles_seen ≥ 2:
          sc_synthesize_feedback ─┐
          sc_compute_metrics ─────┼─▶ sc_write_loop_summary
                                  │      loop-summary.json (atomic) + emit_event
                                  ▼
                              return 4  ──▶ sw-loop: STATUS=loop_detected, abort

Cycle taxonomy (sc_detect_cycle over the last CYCLE_DETECTION_WINDOW=5 records):

• ab_alternation — exactly 2 distinct hashes as A,B,A,B…; cycles_seen = # of full A→B→A repeats.
• fixed_point — 1 distinct meaningful hash + ongoing trivial/none (formatting churn on a settled state).
• k_cycle — a repeating tuple length 2..⌊window/2⌋ (covers the "3–5 iteration" requirement).

Abort policy: abort only when cycles_seen ≥ 2. One cycle → warn + continue. This is the primary false-positive guard, reinforced by meaningful-class gating and the two config knobs.

Error handling: every git call is 2>/dev/null || echo ""; missing/malformed history → sc_detect_cycle yields "no cycle" and integrate returns 0 (degrade to current behavior — never crash, never false-abort). All JSON built with jq -c -n --arg (never string interpolation). All writes atomic tmp.$$ + mv. ITERATION ≥ 3 guard avoids HEAD~1-has-no-parent under set -e.

Alternatives Considered

---

Generated by shipwright pipeline design stage at 2026-07-24T09:47:16Z

[github-actions]

[github-actions]

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

[github-actions]

[github-actions]