loop

# Compound-Engineering Loop Protocol

MODE: LOOP runs an objective end to end as a series of gated phases, then
loops to compound improvements until the objective is met or a stop condition
fires. Each cycle reuses the existing mode skills (`brainstorm`, `plan`,
`critic-gate`, `execute`, `phase-wrap`) and ends with a learning-capture step
so the next cycle is cheaper — that is what makes the loop *compounding* rather
than merely repeating.

This is a real implementation workflow: it delegates to the coder, declares
scope, and mutates source code through the normal EXECUTE path. It is distinct
from full-auto (autonomous cross-phase oversight via the `critic_oversight`
agent) and turbo (parallel lanes within a single phase). LOOP is a
user-initiated, gated, sequential, compounding workflow.

The two design rules that everything below serves:

1. **Separate the generator from the verifier.** The context that writes a
   change must never be the only context that approves it. Implementation,
   independent review, and critic challenge live in separate delegated
   contexts. Review is report-only; a distinct fix step applies changes.
2. **Stop on positive evidence or a budget — never on vibes.** Every phase has
   an entry gate and an exit gate backed by concrete evidence, and the loop has
   layered stop conditions so it can never run away.

---

## Step 0 — Parse Header

Parse the `[MODE: LOOP ...]` header to extract:

- `objective`: the goal text after the header (the WHAT to achieve). Empty only
  when `resume=true`.
- `max_cycles`: integer 1..5 (default 3) — hard cap on outer improvement cycles.
- `autonomy`: `checkpoint` (default) or `auto`.
  - `checkpoint`: pause at each phase gate and wait for explicit user approval
    before continuing.
  - `auto`: proceed across gates without prompting, but still enforce every
    hard stop condition and the mandatory review/critic gates.
- `depth`: `standard` (default) or `exhaustive` (wider exploration in
  BRAINSTORM and PLAN: more candidate approaches, deeper localization).
- `resume`: `true` | `false`. When true, resume the existing run from durable
  state instead of starting a new objective.

If the header is malformed or required fields are missing, report the error and
stop.

---

## Step 1 — Preconditions & Durable State

1. **Working tree.** Check `git status`. If the tree is dirty, surface the
   uncommitted changes and ask whether to proceed (checkpoint) or proceed only
   if the changes are clearly part of this objective (auto). Do not silently
   build on an unknown working state.
2. **Run state directory.** Loop state lives under `.swarm/loop/<run-id>/`
   (containment invariant — never write loop state outside `.swarm/`).
   - New run (`resume=false`): allocate a `run-id` (short slug + timestamp),
     create `.swarm/loop/<run-id>/state.json`, and record the baseline:
     objective, parsed parameters, start HEAD commit, `cycle: 0`,
     `phase: brainstorm`, empty `improvements` and `learnings` lists.
   - Resume (`resume=true`): locate the most recent `.swarm/loop/<run-id>/`
     with an unfinished state, read it, **validate required fields** (`run_id`,
     `cycle`, `phase`, `done` must all be present and have the correct types;
     if any are missing or malformed, report the corruption clearly and stop
     rather than continuing with undefined values), print a short progress
     summary (cycle N of max_cycles, current phase, last gate result), and
     continue from the recorded phase. If no resumable run exists, say so and
     stop.
   - **Retention:** On both new-run and resume entry, prune completed runs
     (`.done === true`) that exceed 10 in count — keep the 10 most recent by
     timestamp, remove the rest. This prevents unbounded state accumulation
     under `.swarm/loop/`.
3. **State is derived, not authoritative for code.** The durable state file
   tracks *loop control* (cycle counter, phase, gate outcomes, captured
   learnings, stop reason). Actual implementation progress is derived from git
   and the plan ledger (`.swarm/plan-ledger.jsonl`), never from conversation
   memory — so a killed/resumed session never loses or re-does work.

Write the state file after every gate transition. The on-disk state is the
single source of truth for resumability.

---

## Step 2 — The Cycle

One cycle is five phases run in order: **BRAINSTORM → PLAN → BUILD → REVIEW →
IMPROVE**. Do not skip or collapse phases. Each phase has an entry gate
(precondition) and an exit gate (positive evidence required before the next
phase begins). In `checkpoint` autonomy, pause at each gate for user approval.

On cycle 2+, BRAINSTORM is replaced by a lightweight **refinement** step: feed
the prior cycle's captured improvements and residual findings into PLAN
directly (skip full discovery dialogue) — the objective is already framed.

### Phase 1 — BRAINSTORM (cycle 1 only)

- **Entry gate:** objective is non-empty; no approved plan already covers it.
- **Action:** Load `file:.opencode/skills/brainstorm/SKILL.md` and run it to
  produce `.swarm/spec.md` and a QA gate profile. With `depth=exhaustive`,
  require at least one non-obvious candidate approach.
- **Exit gate:** `spec.md` exists with explicit, testable success criteria and
  scope boundaries. Record the success criteria into loop state — they are the
  objective-met test used by the stop conditions. Checkpoint: confirm the spec
  with the user.

### Phase 2 — PLAN

- **Entry gate:** a spec (or, on cycle 2+, the improvement directives) exists.
- **Action:**
  1. Load `file:.opencode/skills/pre-phase-briefing/SKILL.md` (required before
     planning, especially on cycle 2+: it reads the prior retrospective and
     verifies codebase reality so the new plan reflects what actually changed).
  2. Load `file:.opencode/skills/plan/SKILL.md` to decompose the work into
     tasks and call `save_plan`. With `depth=exhaustive`, prefer finer task
     granularity and deeper localization.
  3. Lo