Ship Loop v5.0 — TARS Convergence

Orchestrate multi-segment feature work as a self-healing pipeline. Three nested loops ensure maximum autonomy: Loop 1 runs the standard code→preflight→ship→verify chain, Loop 2 auto-repairs failures via the coding agent, Loop 3 spawns experiment branches when repairs stall. A SQLite state backend provides crash recovery and cross-run analytics. A verdict router replaces hardcoded branching with a configurable decision table. A reflection loop audits historical effectiveness and auto-generates learnings.

Architecture: Three Loops + Event Queue + Verdict Router

CODEBLOCK0

Security Notice

SHIPLOOP.yml is equivalent to running a script. The agent_command, all preflight commands (build, lint, test), and custom deploy scripts execute with your full user privileges. Ship Loop does not sandbox these commands. Never use on untrusted repos without reviewing the config. Treat SHIPLOOP.yml with the same caution as a Makefile or CI pipeline.

When to Use

• - Building multiple features for a project in sequence
• Any work that follows: code → preflight → commit → deploy → verify → next
• When you need checkpointing so progress survives session restarts
• When you want self-healing: failures auto-repair before asking humans
• When you want cost visibility and learning from past runs

Prerequisites

• - Python 3.10+ with pyyaml and pydantic installed
• A git repository with a remote
• A deployment pipeline triggered by push (Vercel, Netlify, etc.)
• A coding agent CLI configured via agent_command in SHIPLOOP.yml

Installation

CODEBLOCK1

CLI Usage

CODEBLOCK2

Pipeline Definition (SHIPLOOP.yml)

CODEBLOCK3

SQLite State Backend (v5.0)

State is now stored in .shiploop/tars.db (SQLite, WAL mode). SHIPLOOP.yml is config-only.

Tables

Table	Purpose
INLINECODE8	Pipeline execution records (id, project, startedat, status, cost)
INLINECODE9

Segment execution records per run (status, commit, touchedpaths) | | run_events | Event queue for crash recovery and audit trail | | learnings | Failure/success lessons with effectiveness scores | | usage | Token and cost records per agent invocation | | decision_gaps | Situations the system didn't know how to handle |

Event Types

Event	When emitted
INLINECODE14	Agent invocation begins
INLINECODE15

All preflight steps pass | | preflight_failed | Any preflight step fails | | repair_done | Repair loop succeeded | | repair_failed | Repair loop failed or exhausted | | meta_done | Meta loop winner merged | | segment_shipped | Segment fully complete | | segment_failed | Segment permanently failed | | deploy_failed | Deploy or verification failed | | file_overlap_warning | Segment may touch files changed by prior segment |

Crash recovery: On startup, unprocessed events are replayed to restore pipeline state.

Verdict Router (v5.0)

The orchestrator no longer uses if/else chains. Every outcome maps to a Verdict, and a VerdictRouter maps verdicts to Action values.

Default Routing Table

Verdict	Default Action
INLINECODE28	INLINECODE29
INLINECODE30

repair | | agent_fail | fail | | deploy_fail | retry | | repair_success | ship | | repair_exhausted | meta | | meta_success | ship | | meta_exhausted | fail | | budget_exceeded | fail | | converged | meta ← skip remaining repairs, jump to meta | | no_changes | fail | | unknown | pause_and_alert |

Override via router: section in SHIPLOOP.yml (see above).

Meta-Reflection Loop (v5.0)

Runs automatically after pipeline completion (when reflection.auto_run: true) or manually via shiploop reflect.

What It Analyzes

1. 1. Repeat failures — same error_signature across multiple segments/runs
2. Repair-heavy segments — segments that needed >1 repair loop (same error type)
3. Efficiency trends — cost/time per segment trending up or down
4. Stale learnings — learnings with score < 0.3 that haven't helped
5. Decision gaps — situations that triggered INLINECODE55

Auto-creates learnings from patterns

If an error signature appears 3+ times across runs, the reflect loop auto-generates a AUTO-<sig> learning flagging it for human review.

CODEBLOCK4

Playbook Evolution (v5.0)

When a repair fails with an error that doesn't match any existing learning, the system records a decision_gap:

CODEBLOCK5

Decision gaps surface in shiploop reflect output and the decision_gaps DB table. Operators use them to add new learnings or router overrides.

Convergence Detection (v5.0 Enhanced)

Same-segment: if two consecutive repair attempts produce the same error hash → CONVERGED verdict → router jumps to META (skipping remaining repair attempts).

Cross-segment: before starting a segment, the orchestrator checks if any already-shipped segment touched the same files (via touched_paths in DB). If overlap detected, a file_overlap_warning event is emitted.

Learnings Scoring (v5.0)

CODEBLOCK6

Search results are sorted by combined keyword-relevance × score. Learnings with score < 0.3 are flagged as stale in reflection.

CODEBLOCK7

State Machine

CODEBLOCK8

SHIPLOOP.yml checkpointed after every transition (for backward compat). SQLite is the primary state store.

Deploy Providers

Provider	How it works
INLINECODE64	Polls routes for HTTP 200, checks x-vercel-deployment-url header
INLINECODE66

Polls routes for HTTP 200, checks x-nf-request-id header | | custom | Runs deploy.script with SHIPLOOP_COMMIT and SHIPLOOP_SITE env vars |

Budget Tracking

Token usage and estimated costs tracked per agent invocation in SQLite (falls back to metrics.json).

CODEBLOCK9

Critical Rules

1. 1. Never break the chain — after a segment ships, immediately start the next
2. Preflight is mandatory — no exceptions, no "ship now fix later"
3. Explicit staging only — never git add -A, only changed files from INLINECODE74
4. Prompts via file — never shell arguments (prevents injection)
5. SQLite is source of truth — SHIPLOOP.yml config-only; runtime state in INLINECODE75
6. Agent command from config — always read from agent_command, never hardcode
7. Budget-aware — track costs, enforce limits, fail gracefully

Project Structure

CODEBLOCK10

Changelog

v5.0.0 (2026-03-27) — TARS Convergence

• - SQLite state backend: tars.db replaces metrics.json + learnings.yml for runtime state
• Event queue: all phase transitions emit events; unprocessed events enable crash recovery
• Verdict router: configurable Verdict → Action table replaces if/else chains in orchestrator
• Meta-reflection loop: shiploop reflect analyzes run history, finds patterns, auto-generates learnings
• Playbook evolution: MISSING_DECISION_BRANCH detection → decision_gaps table
• Cross-segment convergence: touched_paths tracked per segment for overlap warnings
• Learnings scoring: score field (+0.1 on success, -0.2 on failure), sorted by score
• New CLI commands: reflect, events, INLINECODE87
• New config sections: reflection, INLINECODE89

v4.0.0

• - Python CLI replaces bash scripts
• Pydantic v2 config validation
• Budget tracking with per-segment and per-run limits
• Error convergence detection (hash-based)
• Deploy provider plugins (Vercel, Netlify, Custom)