Loop Eng

---
name: loop-eng
description: Closed-loop task execution and quality polishing for Claude Code. Use when the user wants a bounded task driven to completion hands-off — "keep iterating until tests pass", "don't stop until done", 自动循环/挂机/无人值守/跑到全绿 — via /autoloop (builder/checker rounds); wants code quality raised iteratively with every finding adversarially verified before fixing — 打磨/清理代码 — via /polish (review-verify-fix rounds); or asks how the loop-eng workflow works. Unlike prompt-only goal trackers, the Stop hook executes the contract's real verify commands and completion evidence is machine-written.
---

# loop-eng — closed-loop task execution & quality polishing

Two entry points:

- `/autoloop <task>` — drive a bounded task to completion: contract →
  builder/checker rounds → ALL GREEN or escalation. Also accepts a
  prioritized roadmap/checklist document: it triages items in document order
  (loopable → backlog with verify commands; too-big → split; not-loopable →
  deferred with reasons), loops the backlog, and ends with a
  Done / Deferred / Remaining ledger. See `commands/autoloop.md` (in this
  plugin) for the full protocol.
- `/polish [scope]` — iterative quality improvement: numeric baseline →
  4 independent review lenses → adversarial verification of every finding →
  fix queue → full regression → repeat until a dry round (no fresh finding
  entered the FIX QUEUE — not merely none confirmed: a confirmed finding that
  is `optional`, or deferred as a public-contract change, is one the loop will
  never act on, so counting it keeps a converged loop running). Behavior-preserving by definition; public-contract changes are
  listed for the human, never applied. See `commands/polish.md` (in this plugin).

## Which tasks fit a loop

GOOD fits (bounded goal + machine-verifiable done):
- Bug fixes with a reproducible failing check
- Small-to-medium refactors under existing test coverage
- Adding tests for existing code
- Style/consistency sweeps, library migrations with a compile/test gate

BAD fits (do NOT loop these — handle interactively):
- Architecture decisions, greenfield projects with no tests to verify against
- Legacy code with zero test coverage (build the safety net first)
- Anything touching production, databases/migrations, payments, external
  side effects — red actions always go through a human

## Core invariants (all loops)

1. Contract before code: `.loop/contract.md` for humans plus
   `.loop/criteria.tsv` (binary verify commands, fixed while the loop is
   armed) for the machine.
2. Maker/checker separation is enforced by tool whitelists, not trust:
   loop-builder has Write and Edit; loop-checker, loop-reviewer and
   loop-verifier have no Write or Edit tool. They do have Bash, which writes —
   the whitelist removes the writing TOOLS, and the red line against using Bash
   for writing is stated in each agent's own file. Claiming they cannot write
   at all would be stronger than the mechanism.
3. State lives on disk, not in the context window — `.loop/state.md` for
   `/autoloop`, `.loop/polish-state.md` (plus `polish-seen.md` and
   `polish-deferred.md`) for `/polish`.
4. Every loop is bounded, and the two are bounded differently:
   `/autoloop` — six stop rules, 5 rounds max.
   `/polish` — the stop rules under `## Stop rules` in `commands/polish.md`,
   three macro rounds.
   A single set of numbers for both was wrong about whichever one it was not
   describing.
5. Never weaken a check to make it pass.
6. Loop output is a proposal: always end with the diff for human review.
7. Completion evidence is machine-written: `run-contract.sh` produces
   `.loop/results.json` + `.loop/evidence/`; the evidence-gate hook denies
   model writes to them.

Asymmetry worth knowing: the stop-gate (criteria.tsv / `.loop/active`)
mechanically enforces /autoloop's completion contract. /polish has no
mechanism-layer completion gate — its dry-round convergence rests on the
orchestration prompt and the behavior-preserving red lines. One loop per
repo at a time: `.loop/` is shared state.

## Contract quality caps loop quality

The loop's output quality is capped by the contract's spec quality: builder
and checker faithfully execute the spec, including its holes. Four authoring
rules, learned from live pilots:

1. Every target criterion must be RED before arming — a criterion already
   green before any work may be vacuously satisfied (the arm-time red-check
   warns on these).
2. Specs must carry non-functional requirements — a perf/timeout constraint
   omitted from the contract is a regression faithfully implemented.
3. Encode "must not happen" as a checkable negative assertion — the checker
   only verifies what the acceptance commands list.
4. Criterion commands must be idempotent, verify-only commands — they execute
   for real (not sandboxed) at the arm-time red-check AND on every stop
   attempt, so a side-effecting criterion fires repeatedly.

### What the mechanism does and does NOT guarantee

Two limits worth stating plainly, so a loop's author does not over-trust it:

- **The red-check catches _vacuous_ criteria, not _weak_ ones.** Arming warns
  when a criterion is already green before any work (it may prove nothing). It
  cannot tell that a criterion is red-now-but-tests-the-wrong-thing — a grep
  that matches a substring the source will carry incidentally is red today and
  green forever after, yet verifies nothing real. Author criteria that key on a
  genuine symbol/behavior, not a coincidental string; the red-check is a floor,
  not a ceiling.
- **Machine-written evidence covers criteria pass/fail — not the orchestrator's
  prose.** `results.json` and the stop-gate guarantee that a criterion's
  `passes: true` was produced by running its command. They say nothing about
  the narrative an orchestrator writes _around_ the loop (a summary figure, a
  "reduced X to Y" claim). Those sentences are unguarded prose: cite them to
  fresh tool output the same way you would outside a loop. The loop guarantees
  the contract was met, not that every sentence about it is true.

## Templates

- `templates/contract.md` — acceptance contract skeleton
- `templates/state.md` — per-round state file skeleton