/ratchet-loop

name: ratchet-loop
description: Execute a ratchet BACKLOG.md in a verified engineering loop — pick the next eligible item, implement exactly its spec, run its acceptance criteria until green (bounded attempts), lock it in as one atomic commit, update the ledger, repeat until the backlog is dry or a stop condition fires. Supports ratchet:v2 parallel lanes via --lane, so several agents can work one backlog concurrently. Use when the user says "run the backlog", "ratchet", "work through BACKLOG.md", "run the api lane", or wants autonomous-but-verified execution of a prepared item list. Requires a backlog conforming to the ratchet:v1 or ratchet:v2 format.

Ratchet Loop — the executor

You are executing a ratchet backlog. Your contract is **forward motion only**: an item is either done-verified-committed, or it is not done and the Ledger says exactly why. Nothing in between survives your run.

The backlog file is the single source of state. You are stateless; treat every run as if a different agent did the previous one (often true). Everything you learn that matters goes in the file, not in your head.

**Load the executor rules first.** Read `executor-rules.md` from this skill's own directory (the folder this SKILL.md lives in) before touching any item — 13 binding, do-this-exactly rules distilled from field runs. When a rule and your instinct disagree, follow the rule.

Invocation

/ratchet-loop [path] [--lane NAME] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]

• `path` — backlog file. Default: `ratchet/BACKLOG.md`, else `BACKLOG.md` at repo root. If neither exists, say so and suggest `/ratchet-audit` or `/ratchet-backlog create`. The resolved path is **the backlog file** everywhere below, and its containing directory is the loop's **state directory** (default `ratchet/`).
• `--lane NAME` — v2 backlogs only (error on a v1 file): restrict eligibility to items with `Lane: NAME` and write state only to `lanes/NAME.md`. This is the parallel-safe mode — see "v2 backlogs — lanes" below. **`--lane` is a state selector, not routing: it never satisfies the high-stakes gate's `--only` requirement.**
• `--max-items N` — stop after N items reach a terminal state this run.
• `--only` — restrict eligibility to the listed IDs (dependencies still respected). Also the explicit-routing signal the high-stakes gate requires — see below.
• `--verify` — verification mode, see "Verification modes" below. Default `inline`.
• `--dry-run` — do Phase 0 only: validate, report the execution plan and any recovery a real run would perform, **write and commit nothing**.

**The state file.** Everywhere below, your ledger and journal writes go to **the state file**: in v1 that is the backlog file itself; in v2 it is your lane's file, `lanes/<lane>.md`, and the backlog file is read-only to you.

Phase 0 — Preflight (never skip, never reorder)

1. **Read the backlog file in full and validate its structure:** the version marker near the top — exactly `<!-- ratchet:v1 -->` or exactly `<!-- ratchet:v2 -->` (a marker containing `:lane` means you were pointed at a lane file, not a backlog — refuse and point at the real backlog); for v1, all four sections (`## Items`, `## Ledger`, `## Journal`, optionally `## Global checks`); for v2, `## Lanes` + `## Items` (+ optional `## Global checks`), **no** Ledger/Journal in the backlog, plus the v2 structural checks in "v2 backlogs — lanes" below; IDs matching `[A-Z]+-\d+` and unique; every item has a Spec and ≥1 Acceptance criterion; a Ledger row per item (v2: in the lane file its `Lane:` names) with a status from the legal set (`todo` / `in-progress` / `done` / `blocked` / `needs-human` / `skipped`). Structurally broken → STOP, report the exact problems, suggest `/ratchet-backlog validate`. Never guess at a malformed file. Per-item defects that don't break structure — stale evidence, unrunnable criteria on an *ungated* item — are handled later by parking **that item**, not by refusing the file. (Full contract: `docs/backlog-format.md` in the ratchet repo; the checks you need are the ones listed here.) 2. **Require a clean working tree — with the loop-state exception.** `git status` must show no staged or unstaged changes to tracked files. Classify any dirt you find:

• **Your own state** — v1: the backlog file and the state directory. v2: **your lane file only**. **Untracked** → not user dirt; it will be committed in step 3 (in v1, this is how the curator's freshly-written backlog enters history). **Dirty but tracked** → state left by a previous run (a crash, or an unsynced sha backfill); journal one line and let step 3 commit it.
• **v2 only — what is not yours is never yours to clean.** `BACKLOG.md` is read-only to you, so it is never "previous-run state": **dirty tracked** → an out-of-window human edit or merge debris → **STOP** and report. **Untracked** (backlog or lane files) → the curator's output was never committed; that is fine only on the integration branch, where step 3 commits it as `ratchet: add backlog` exactly as in v1. On a lane branch, untracked state means you were launched before the backlog was committed → **STOP** ("commit the backlog on the integration branch first"). Another lane's file, dirty or holding an `in-progress` row: a second run may be using this worktree → **STOP** ("possible live parallel run — give each lane its own worktree"). Never commit either, never recover either. A dirty or untracked `NEXT.md` in a lane worktree: leave it exactly as it is (never stage, never commit — it is integration-branch-only) and note it in the report.
• Dirty *source* paths that belong to an `in-progress` Ledger item are crash debris, handled in step 3 — attribute them via the Journal tail and the item's Evidence/Spec; if the attribution is ambiguous, STOP and ask.
• Any other dirty tracked file → STOP and ask the user (their work is not yours to stash). This invariant is what makes your failure-recovery safe.

-