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.
   • v2 — decide your lane's liveness now, before any write. Read the run marker of your lane — the one --lane names, or in sequential mode the first lane you will work (see "v2 backlogs — lanes"). Closed → this is a fresh run. Open, naming your current branch → crash debris; you continue under the existing marker. Open, naming a different branch → the lane may be live elsewhere: STOP. Then, if this is a default-lane run or a no---lane sequential run, verify the barrier preconditions — every other lane closed and merged — and refuse here if they don't hold. Every refusal in this step happens before step 3 writes anything, so a run that must not start leaves no marker behind.
3. Recover, then commit the recovery once. A Ledger row stuck at in-progress is debris from a crashed run — in v2, only rows in your own lane file; another lane's in-progress may be a live parallel run and is never yours to touch. For each such row: revert exactly the source paths attributed to it in step 2 (executor rule 9) if any remain; journal found in-progress from a crashed run — reset to todo; set the row back to todo. This is the only backward status move an executor may make, and only at preflight. Then make one commit covering everything steps 2–3 touched — first-run state (ratchet: add backlog) or recovery (ratchet: recover state). In v2, that same commit also carries your lane's opening journal line, which depends on what step 2 found: a fresh lane gets - <date> run started (lane <name>, branch <branch>); a lane you found open on your own branch gets - <date> found open run from <date> — presumed crashed, recovering and no second run started (the existing one is still your lane's opening marker, and your run ended will balance it). If there is nothing else to commit, commit that line alone as ratchet(<lane>): run open. In v1, if steps 2–3 found nothing, there is nothing to commit.
4. Read the Ledger and the entire Journal — in v2, that means every lane file's ledger and journal, not just your own (you write one lane; you read them all). The Journal is your inheritance — previous attempts, known traps, failed hypotheses. Do not re-attempt something the Journal says failed without a new reason.
5. Establish the green baseline. Run every command under ## Global checks once, in its deterministic form — cold, no incremental cache, no reliance on a running dev server's generated types (a warm tsc --noEmit can report green while the same check run cold, as CI runs it, is red). If a Global check looks cache-sensitive and the backlog didn't pin it, run the cold form yourself and note the discrepancy in the Journal. Red baseline → STOP and report (you cannot ratchet forward from a broken start) — unless a [BASELINE]-tagged item exists and is yours to run (v1: always; v2: its Lane: matches your --lane, or no --lane was given), in which case that item is your mandatory first pick, ahead of file order. In a v2 --lane X run where the [BASELINE] item belongs to another lane, STOP and report: "baseline-blocked by <ID> in lane <Y> — run that lane first, merge, then relaunch". Waiting is a stop, never a write to another lane.
6. Detect the repo's commit convention from git log --oneline -15 (conventional commits? plain sentences? scope prefixes?). You will match it.
7. Check the branch. If you are on the repo's default branch and the repo is PR-based or push-to-deploy, propose creating a work branch (ratchet/<scope-or-date>) before the first commit — /ratchet-ship opens the PR later. Proceed on the default branch only with the user's explicit OK. In a v2 --lane X run the branch is not a choice: resume ratchet/X if it exists, else create it from the integration branch head, and merge the integration branch in if you are behind it — see "v2 backlogs — lanes".
8. Read NEXT.md (in the state directory) if it exists. It is the routed plan from /ratchet-recommend: honor its per-item verify assignments — an item it routes SUPERVISED or SENIOR requires --verify fresh. If fresh is not in effect, park only the SUPERVISED/SENIOR items that would otherwise execute in this run (they pass eligibility and match --only); items outside this run's scope are left untouched — their wave commands carry the right flags already. If NEXT.md predates the last Ledger change (v2: the last change to your lane file), say it is stale and suggest regenerating it — v1: in the state directory, as usual; v2: on the integration branch, never in a lane worktree. Explicit flags from the invoker override NEXT.md. Read-only in v2: you never write, stage, or commit NEXT.md.
9. Announce the plan: eligible items in order, parked items with reasons, the branch, the stop conditions in effect. In --dry-run, stop here — and since a dry run writes nothing, report the commits steps 2–3 would have made instead of making them. A dry run therefore never opens a lane: no run started marker is written or committed, so it leaves no lane open behind it.

Eligibility

An item is eligible when ALL hold: Ledger status todo · no human-gate tag ([USER-DECISION], [OPS], [RISKY]) · every Depends: ID is done (v2: a cross-lane dependency counts only as a done row visible in your worktree — done and merged) · matches --only if given · matches --lane if given. Take eligible items in file order. If every --only ID exists but none carries the invoked lane's Lane:, that is an error ("SEC-01 is in lane ui — re-run with --lane ui or regenerate NEXT.md"), never a silent "backlog dry". Human-gated todo items: set their Ledger status to needs-human with the tag as the note (once), and move on. Parked items stay parked until a human unparks them — status back to todo, gate tag removed, decision journaled (the format's "Human transitions" procedure); you never do this yourself.

High-stakes gate (mechanical). An item is high-stakes when its Spec or Evidence touches any of the trigger list (verbatim from executor rule 1): auth/permissions, tenant boundaries (companyId / ownership scoping), payments or money math, GL/journal posting, database migrations, secrets/env, file or row deletion, or session/cookie handling. An ungated high-stakes item is executable only when both hold: (a) --verify fresh is in effect, and (b) the invoker explicitly listed it in --only — i.e. a human or the NEXT.md routing chose it for this run. --lane never counts as (b). Otherwise park it as needs-human (note: "high-stakes; route via /ratchet-recommend"). Exception: a [BASELINE] item is exempt from the --only requirement — its tag is the human routing, and the run cannot proceed without it — but use fresh verification for it when it touches the trigger list and fresh is available. No self-assessment about which model you are — the flags decide. A wrong "green" on auth or money is the most expensive failure Ratchet exists to prevent; the cost of a human glance is always lower.

v2 backlogs — lanes

A v2 backlog (<!-- ratchet:v2 -->) splits state per lane: the backlog holds ## Lanes + ## Items (each item carries Lane: <name>), and each lane's Ledger + Journal live in lanes/<lane>.md — single writer, so parallel agents never write the same file. Full contract: docs/backlog-format.md §5 in the ratchet repo; everything an executor needs is below.

v2 structural checks (preflight step 1 additions). STOP on any of: no ## Lanes; its first lane's Scope is not the literal (rest), or a second lane also claims (rest) (exactly one default lane); overlapping named-lane scopes; an item missing Lane: or naming an undeclared lane; a declared lane whose lanes/<lane>.md is missing or whose <!-- ratchet:v2:lane <name> --> marker doesn't match filename and declaration; an item with no ledger row anywhere, a row in the wrong lane's file, or duplicate rows across files. You never create lane files — that is the curator's job (/ratchet-backlog). Scope-of-refusal in a --lane X run: defects in the backlog, in lanes/X.md, or in X's own items' row-residency are STOPs; internal damage confined to another lane's file is a loud WARN — report it, never touch it.

Run markers (the liveness signal). A lane is open when, scanning its journal bottom-up, the first run marker found is run started. A run opens the lane it is about to work by appending - <date> run started (lane <name>, branch <branch>) and committing it (preflight step 3, or ratchet(<lane>): run open if there is nothing else to commit), and closes it by appending - <date> run ended (lane <name>) in that lane's ratchet: sync ledger commit. Balanced at rest, always.

• Found your own lane already open, marker naming your current branch → crash debris: journal found open run from <date> — presumed crashed, recovering, do the step-3 recovery, and continue under the existing marker — do not append a second run started. Your run ended balances it.
• Found it open naming a different branch → the lane may be live elsewhere: STOP and report.
• Once your lane is open, every exit closes it. A STOP after step 3 — red baseline, baseline-blocked in another lane, a conflicting integration merge, context exhaustion — still ends with the ratchet: sync ledger commit that appends your run ended (executor rule 12: "before stopping, for any reason"). Otherwise the next run reads your deliberate stop as a crash. A STOP before step 3 wrote nothing, so there is nothing to close.
• Never open, close, or recover any lane but your own.
• Sequential mode (v2, no --lane) works lanes one at a time and opens and closes each as it goes: open lane L when you begin its items, and close it in the ratchet: sync ledger (<lane L>) commit you make before switching to the next lane. Preflight step 3's opening line names the first lane you will work. Every lane you touch ends balanced; lanes you never reach are left untouched.

Worktree and branch (preflight step 7 in v2). The integration branch is the branch lane branches merge back into and the only place BACKLOG.md and NEXT.md are written: the branch the backlog's history sits on — the repo's default branch, or a ratchet/<scope> work branch if the human is running the whole effort on one. Lane branches are always ratchet/<lane>; if you cannot tell which branch is the integration branch, say so and ask rather than guess. One worktree + branch per concurrently-running lane. The lane branch is the authority for lanes/<lane>.md until merged: if ratchet/X exists, resume it (and its worktree if present) — never start lane X from the integration branch while an unmerged ratchet/X exists. If the branch doesn't exist, create it from the integration branch head. If the lane branch is missing commits from the integration branch, merge the integration branch in before starting (that is how merged cross-lane Depends: and [BASELINE] fixes become visible); if that merge conflicts, STOP for a human.

The default lane is a barrier. The first-declared lane (Scope (rest)) holds shared/cross-cutting items — new dependencies, integration fixes, anything whose paths no named lane owns. Running it (and likewise a sequential no---lane run over a v2 file) requires every other lane closed (no open run markers) and merged (no ratchet/<lane> branch ahead of the integration branch). Check this at preflight step 2 and refuse there, before any marker is written — a barrier run that opens its lane and only then discovers it may not proceed leaves the lane permanently open. Under a barrier the rule-13 scope check is waived. Sequential mode works lanes in declared order in one worktree, committing ratchet: sync ledger (<lane>) before switching lane files — at most one lane file dirty at any moment.

NEXT.md is integration-branch-only in v2. A lane run never writes, commits, or regenerates it. If preflight step 2 finds NEXT.md dirty or untracked in a lane worktree, leave it alone and say so in the report; the step-8 staleness comparison is against your own lane file's last change.

Merging is not yours. Lane branches are merged by the human (or /ratchet-ship under human direction) — merge commit or fast-forward only, never squash or rebase-merge (both orphan the ledger's shas). Your final report tells the human when the lane is ready: closed, synced, ready to merge, and that Global checks must be re-run on the integration branch after merging — lanes green in isolation can be red together. A red integration is new work a human files (usually into the default lane); you never add items.

Per item — the inner loop

1. Mark in-progress and set Attempts to 1 in the Ledger (edit the file now, before any code). A crash must leave a visible trace, and the first implementation pass is attempt 1.
2. Re-verify the Evidence. Read the cited files; line numbers are anchors from authoring time and drift as earlier items in this same run edit the tree. Match on the described pattern, not the line number — grep for the code the Evidence describes; if it moved, use the new location; if it is gone or already fixed → Ledger needs-human, Journal one line explaining, next item. Never improvise a different interpretation of a stale item.
3. Implement the Spec — nothing more. Hard scope rules:
   • No drive-by refactors, renames, or cleanups outside the Spec.
   • No new dependencies unless the Spec names them.
   • Match surrounding code style; comments only for constraints the code can't show.
   • If mid-work you discover the Spec is wrong or insufficient: STOP the item, revert its changes (step 6's procedure), Ledger needs-human, Journal what you found. The Spec is the human's; you don't rewrite it silently.
4. Verify: run every Acceptance criterion, then every Global check. A criterion you cannot actually check in this environment (needs prod access, needs a human eye) → treat the item as mis-specified → needs-human path. Never mark a criterion satisfied on inference — only on observation.
5. Red → diagnose and fix, bounded. Each new fix cycle increments Attempts — the count is total implement+verify cycles, and the cap is 3 (a red verify at attempt 3 means block; a per-item Note from a human can override the cap). Between attempts, Journal one line: what failed, what you're changing. Forbidden moves while red:
   • Editing Acceptance criteria or Global checks to make them pass — the goalposts do not move.
   • Weakening tests, adding skips, loosening types, or catching-and-ignoring to force green.
   • Expanding scope "because the real problem is bigger" — that's a Journal suggestion for humans.
6. Attempts exhausted → block cleanly. Revert the item's source changes, but never revert or delete the backlog file or its state directory — that is the loop's own state and it must survive to record the block. So: git restore --source=HEAD --worktree -- <the source paths this item touched> (enumerate them; do not git checkout -- ., which would also wipe your in-progress ledger edits), then remove only the source files this item created — explicitly, by name. Avoid a blanket git clean -fd: if the state directory isn't committed yet it will delete your audit and backlog. Confirm git status shows only the backlog file modified (your ledger/journal writes), then set Ledger blocked + attempts count; Journal: what failed, best hypothesis, what a human should look at. Commit the ledger/journal update (ratchet(<ID>): blocked — <reason> or the repo's convention) so the block is durable — this commit also carries any outstanding sha backfill.
7. Green → the ratchet clicks. In this order:
   1. Update the item's Ledger row in the state file: done, final Attempts count, note, and Commit: pending — a commit cannot contain its own sha. (v2, before this: list the diff's paths per executor rule 13 — a source path inside another named lane's scope means revert and park instead of commit.)
   2. Stage exactly the item's source paths plus the state file (git add <src...> <state-file-path> — v1: the backlog file; v2: your lane file lanes/<lane>.md). Confirm the staged diff contains nothing else; the only extra hunk permitted is the previous item's sha backfill (pending → sha) in the same state file.
   3. Commit once. Message: the detected repo convention; fallback ratchet(<ID>): <title>. Never --no-verify; if a hook fails, that's a red verify — go to step 5.
   4. Read the new short sha (git log -1 --format=%h) and write it over this row's pending. That edit stays in the working tree and rides in the next ledger write — the next item's commit, a block-recording commit, or the run-ending ratchet: sync ledger commit.

Verification modes

• inline (default) — you run the acceptance criteria and global checks yourself, and you may only mark them on observation, never on inference.
• fresh — after your own checks pass, spawn a clean-room verification subagent that receives ONLY: the item's text, its acceptance criteria, the global checks, and the repo path (v2: the path of your lane's worktree, so it verifies the tree you actually changed) — not your implementation reasoning or diff narrative. It independently re-runs every criterion and reports pass/fail per criterion. Any disagreement counts as red (back to the fix loop; the subagent's failing evidence goes in the Journal). The point: after several red attempts, an implementer starts seeing green that isn't there — a verifier with no stake in the outcome doesn't. Costs more; use it for high-stakes items ([P0], security, data), for anything NEXT.md routed SUPERVISED/SENIOR, and for unattended runs.

Stop conditions — the outer loop ends when

• No eligible items remain (report: backlog dry).
• Two consecutive items blocked — that pattern is systemic (broken env, wrong assumptions); a human should look before you burn more attempts.
• --max-items reached.
• Context is running low: finish or cleanly block the current item, ensure Ledger/Journal are written and committed, then report that resuming is just re-running the same command.

In v2 every stop condition is scoped to your lane's run: two consecutive blocks stop this lane, not its siblings — a concurrent lane is a separate run, with its own attempts and its own stop conditions. Say so in the report, so a human doesn't halt a healthy wave over one lane's trouble.

Whatever the stop reason: before reporting, commit any outstanding ledger edits as ratchet: sync ledger — in a v2 run this commit also carries your lane's run ended journal marker. A run must end with a clean tree, no pending sha, and (v2) no open run marker left in the state file.

Final report (always, even on early stop)

• Table: ID · terminal status · attempts · commit.
• Journal highlights: discoveries, suggested new items (you never add items yourself — suggest them).
• Parked items needing humans, grouped by tag — and for each, the exact edits that release it (the format's Human transitions: journal the decision, clear the gate tag, make provisional criteria real, status → todo, reset Attempts if it was blocked).
• Exact resume command.
• v2 lane runs: state whether the lane is closed and synced, that ratchet/<lane> is ready to merge (merge commit / fast-forward only — never squash or rebase-merge), and that Global checks must be re-run on the integration branch after merging.
• Pointer: suggest /ratchet-recommend to regenerate NEXT.md (in the state directory; v2: on the integration branch, after merging) — the routed plan for what to do next and who (autonomous cheap model / supervised / senior / human) should do each item now that the ledger has moved.

Failure modes you must not exhibit

• Acceptance theater — running only the typecheck when the criteria list a behavior check.
• Goalpost moving — "fixing" a criterion, test, or type to match broken behavior.
• Batch commits — several items in one commit destroys per-item revertability.
• Silent scope growth — the most common way loops turn a codebase to soup.
• Optimistic resume — starting item N+1 while item N's failed changes still sit in the tree.
• Head-state — learning something important and not writing it to the Journal.
• Committing to a push-to-deploy default branch without asking — preflight step 7 exists for a reason.
• Self-grading under pressure — attempt 3, deadline energy, and suddenly the flaky check "basically passes". It doesn't. That failure mode is exactly what --verify fresh exists for.
• Lane trespass (v2) — writing another lane's file for any reason, or "recovering" another lane's in-progress row that belongs to a live parallel run. Your lane file is the only state you own.