Monolith Decomposition: Refactor sw-loop.sh Core (2654 lines → Modular Architecture)

[github-actions]

Strategic Improvement

sw-loop.sh at 2654 lines is the largest script and most critical component (build loop = heart of system). Decompose into focused modules: lib/loop-orchestrator.sh, lib/loop-context.sh, lib/loop-iteration.sh, lib/loop-restart.sh. Improves testability, enables optimization, demonstrates platform can improve its own architecture.

Acceptance Criteria

• sw-loop.sh reduced to <500 lines (orchestration + CLI interface only)
• Core logic moved to 4 focused lib modules, each <600 lines
• All existing tests pass without modification (same CLI interface)
• Each module gets dedicated test suite with improved coverage
• Session restart, context management, iteration logic independently testable
• Documentation update showing new architecture and module responsibilities

Context

• Priority: P6
• Complexity: full
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P6: Platform Self-Improvement (AGI-Level Readiness)

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	full
Max Iterations	30
Triage	Core build loop refactoring improves testability and demonstrates platform self-improvement; 2654→4 focused modules with clear acceptance criteria and backward-compatible interface.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	25594982325

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

Plan: Decompose sw-loop.sh (2675 lines → Modular Architecture)

Current State

scripts/sw-loop.sh is 2675 lines with 39 functions. Partial decomposition already exists:

Existing module	Lines	Status
lib/loop-iteration.sh	682	Iteration helpers (extracted)
lib/loop-convergence.sh	350	Convergence detection (extracted)
lib/loop-restart.sh	185	Restart helpers (extracted)
lib/loop-progress.sh	48	Progress markers (extracted)

Gap: ~2200 lines of orchestration, prompt composition, quality gates, model/token logic, and multi-agent coordination remain in the monolith.

Target Architecture

sw-loop.sh (<500 lines)        # CLI parsing + main() orchestration only
  ├─ lib/loop-cli.sh           # show_help, arg parsing, banner, summary
  ├─ lib/loop-context.sh       # prompt composition, model selection, token/budget tracking
  ├─ lib/loop-quality.sh       # audit, quality gates, DoD, holistic gate, completion guard
  ├─ lib/loop-orchestrator.sh  # single-agent + multi-agent loop drivers, worker spawning
  └─ (existing) loop-iteration.sh, loop-convergence.sh, loop-restart.sh, loop-progress.sh

Each new module: <600 lines, single responsibility, independently sourceable for testing.

Module Responsibilities & Function Mapping

lib/loop-cli.sh (~400 lines)

Pure CLI surface — parses args, validates, displays.

• show_help() (L152-470)
• show_banner() (L1650-1672)
• show_summary() (L1674-1730)
• format_duration() (L709-737)
• parse_loop_args() (new — extracted from main) sets globals: GOAL, TEST_CMD, MAX_ITER, MAX_RESTARTS, AGENT_COUNT, ROLES, etc.

lib/loop-context.sh (~550 lines)

Prompt assembly + model/token/budget management.

• select_adaptive_model() (L475-510)
• select_audit_model() (L511-528)
• accumulate_loop_tokens() (L530-579)
• _extract_text_from_json() (L580-641)
• write_loop_tokens() (L642-659)
• apply_adaptive_budget() (L660-708)
• validate_claude_output() (L738-793)
• check_budget_gate() (L794-817)
• compose_worker_prompt() (L1579-1648)
• compose_audit_section() (L1516-1552)

✅ Task Checklist

• Task 1: Run baseline test suite, capture pass/fail counts (blocks all later tasks)
• Task 2: Create 4 module skeletons with VERSION + source guards
• Task 3: Extract loop-cli.sh (display/CLI functions); source from sw-loop.sh; tests green
• Task 4: Extract loop-context.sh (prompt/model/token/budget); tests green
• Task 5: Extract loop-quality.sh (audit/gates/DoD); tests green
• Task 6: Extract loop-orchestrator.sh (single+multi agent drivers); tests green
• Task 7: Trim sw-loop.sh to <500 lines (verify with wc -l)
• Task 8: Write sw-lib-loop-cli-test.sh (≥10 unit tests)
• Task 9: Write sw-lib-loop-context-test.sh (≥15 unit tests, mock claude binary)
• Task 10: Write sw-lib-loop-quality-test.sh (≥12 unit tests, mock test cmd)
• Task 11: Write sw-lib-loop-orchestrator-test.sh (≥10 unit tests, mock multi-agent)
• Task 12: Register 4 new test files in package.json
• Task 13: Run full npm test; zero regressions vs baseline
• Task 14: Update .claude/CLAUDE.md architecture section with new module table
• Task 15: Run shipwright doctor and shipwright version check
• wc -l scripts/sw-loop.sh < 500
• wc -l scripts/lib/loop-{cli,context,quality,orchestrator}.sh each < 600
• npm test exit 0; total PASS count ≥ baseline
• 4 new test suites exist, each with ≥10 PASS assertions
• All new test suites registered in package.json

---

Generated by shipwright pipeline at 2026-05-09T07:20:11Z

[github-actions]

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (200 lines)

Design: Monolith Decomposition: Refactor sw-loop.sh Core (2654 lines → Modular Architecture)

Context

scripts/sw-loop.sh is a 2675-line bash monolith with 39 functions that orchestrates the continuous agent loop — the build-stage workhorse for every pipeline. Partial decomposition exists (lib/loop-iteration.sh, loop-convergence.sh, loop-restart.sh, loop-progress.sh), but ~2200 lines of orchestration, prompt composition, quality gates, and multi-agent coordination remain entangled.

Constraints from the codebase:

• Bash 3.2 compatibility required (no declare -A, no ${var,,}, no readarray)
• All scripts use set -euo pipefail
• VERSION variable must stay in sync with package.json
• Existing test harness pattern (PASS/FAIL counters, ERR traps, mock binaries in temp dirs) — see sw-lib-pipeline-state-test.sh as template
• Meta-tests (sw-agi-roadmap-test.sh, sw-autoresearch-e2e-test.sh Test 18) grep specific patterns inside sw-loop.sh — extraction will break these unless greps are widened
• The build stage of every pipeline depends on sw-loop.sh's public CLI surface; changing it breaks downstream consumers
• Heavy global state coupling: ITERATION, MAX_ITER, LOOP_TOKENS_FILE, WORK_DIR, LOOP_LOG, BUDGET_*, GOAL, TEST_CMD are set in main() and read across nearly every function

Decision

Adopt the proposed 4-module split (loop-cli.sh, loop-context.sh, loop-quality.sh, loop-orchestrator.sh), with these architectural reinforcements:

Component Diagram

                  sw-loop.sh (<500 lines)
                  main() + parse_loop_args()
                          │
            ┌─────────────┼─────────────┬──────────────┐
            ▼             ▼             ▼              ▼
       loop-cli.sh   loop-context.sh  loop-quality.sh  loop-orchestrator.sh
       (display)     (prompts/        (audit/gates/    (drivers/
                      models/tokens)   DoD)             worktrees)
            │             │             │              │
            └─────────────┴──────┬──────┴──────────────┘
                                 ▼
              loop-iteration.sh, loop-convergence.sh,
              loop-restart.sh, loop-progress.sh (existing)

Dependency rule: orchestrator → quality → context → cli. No back-edges. cli has zero peer deps; context depends on nothing in the new set; quality may call context; orchestrator may call all three.

Interface Contracts (bash function signatures)

# loop-cli.sh
show_help()                    # stdout: help text;     exit: 0
show_banner()                  # stdout: banner;        reads: GOAL, MAX_ITER
show_summary()                 # stdout: summary;       reads: ITERATION, exit_status
format_duration <seconds>      # stdout: "Hh Mm Ss"
parse_loop_args "$@"           # sets globals: GOAL, TEST_CMD, MAX_ITER, MAX_RESTARTS,
                               #               AGENT_COUNT, ROLES, FAST_TEST_CMD, ...
                               # exit: 0 on success, 2 on bad args (with usage to stderr)

# loop-context.sh
select_adaptive_model <stage>           # stdout: model id;  reads: SW_MODEL_*, intelligence cache
select_audit_model                      # stdout: model id
accumulate_loop_tokens <json>           # appends to LOOP_TOKENS_FILE atomically
write_loop_tokens                       # finalizes token file
apply_adaptive_budget                   # exports: BUDGET_REMAINING; reads: BUDGET_TOTAL
validate_claude_output <file>           # exit: 0 valid JSON, 1 malformed
check_budget_gate                       # exit: 0 within budget, 1 exceeded
compose_worker_prompt <iter> <ctx>      # stdout: prompt text

</details>

---
_Generated by `shipwright pipeline` design stage at 2026-05-09T07:22:48Z_

[github-actions]

[github-actions]

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

[github-actions]

[github-actions]