Implementation loop

The implementer writes the code; you own the judgment. The implementer is fast at implementation but it self-reports success, cannot commit, and will hang a machine if pointed at a long test suite. You give it a precise spec, then be the thing that actually verifies and ships. This includes bug fixes: a bug found at review, at the gate, or later is a unit like any other — you diagnose and spec, the implementer implements. Editing code directly "because it's faster" silently inverts the division of labor and costs review its independence.

The loop: decompose → dispatch → review → iterate → gate → publish → next.

Non-negotiables

1. Review is mandatory and independent. Codex's summary is a claim; the diff is the evidence. Never skip review because it says it's done.
2. An assumed default never leaves the machine. With no explicit user choice, stop at the working tree — even a local commit can fire hooks/signing. Commit, push, PR, and merge each need the user to have said yes once for this repo, asked at kickoff, not discovered at publish time. Once is once: that authorization is per-repo, persists across sessions until revoked or the work changes character — never re-ask per unit.
3. Never push straight to the default branch.
4. The full-suite gate is yours, run by you, with the real exit code. A fix means the code satisfies the test — a weakened assertion, deleted case, or widened tolerance to turn red green is a stop, not a pass.
5. Don't let the implementer run the full test suite by default — focused subsets only, unless calibration showed the suite is small and fast.

Dials (settle at kickoff, record, stop re-asking)

Dial	Options	Recommended default
Backend	codex / grok / cursor-agent	codex; changes are resurfaced (see dials.md)
Stop point	worktree / commit / pr / merge	recommend pr; assumed default stops at worktree
Dispatch mode	implement / read-only	implement
Gate policy	baseline / strict / skip	baseline
On gate red	stop / iterate	stop
Review depth	light / standard / deep	standard
Cadence	confirm / continuous	confirm; continuous fits stop=merge
Fix lane	codex / claude-trivial-ok	codex

Full rationale: references/dials.md. Compressed non-obvious parts:

• continuous fits stop=merge because dependent units otherwise stack on unit 1's unmerged changes and review attribution breaks. Independent units don't stack, so pr + continuous is a real option — the safer one for unattended runs.
• Fix lane drifts silently — hand-fixing feels faster every time. claude-trivial-ok is a user-granted carve-out for mechanical one-liners only; logic always goes to Codex; the gate runs either way.
• deep review = an independent subagent given the diff and repo but not your spec — for changes touching security, concurrency, migrations, auth, or money.
• skip gate only for changes with no runtime surface. read-only dispatch is investigation — no diff, nothing to gate; useful as a first pass before an implement dispatch on gnarly problems.

The kickoff question — ask it BEFORE the first dispatch

Read the repo's calibration record first, then ask one compact question covering only what it doesn't already answer:

1. How far units travel — the stop point. Needed before dispatch, not at publish: the unit branch is created at dispatch time, and asking at publish means the user waited through a whole dispatch/review/gate to be told you can't ship.
2. Whether to pause between units — the cadence. If the user wants it left running unattended, say so here: it changes which answers are safe and adds a preflight (see Unattended runs).
3. Thinking level and speed — model/effort for the selected backend and service tier where that backend supports one, presenting its standing configuration as the inherit option.
4. Which backend implements — settle codex, grok, or cursor-agent and record it in user-level private memory. A backend named by the repo is only a claim to reconfirm; an existing record with no backend means codex, while any later backend change is resurfaced. After resolving a grok tuple, ask separately for the D10(f) per-repo carve-out when needed; that grant never authorizes publication. For cursor-agent, effort is embedded in the model id and the default is cursor-grok-4.6-xhigh.

On a multi-unit plan, lead with the hands-off preset: stop=pr, cadence=continuous, on-red=iterate (capped) plus the unattended preflight, offered as one named option next to the individual dials. One yes grants every authorization a zero-stop run needs — the user shouldn't have to know dial names to buy an uninterrupted run.

Batch the foreseeable unit questions into the same ask. Scan the plan's units for unsettled forks while composing the kickoff question and settle them here: the same fork costs one line in this batch or a stalled run later.

Write the calibration records the moment the answers land — before the first dispatch, not at run end. A record deferred to the end dies with any session that doesn't reach it, and the next session re-asks everything this one already settled.

The answers hold for the entire invocation — never re-ask per unit. A recorded calibration or standing preference ("always inherit, stop asking") suppresses the corresponding part; a fully recorded repo means no question at all. Everything else runs at its recommended default until something makes it worth raising.

If a later step needs a dial nobody settled, you asked too late — that's the failure this section exists to prevent, not a reason to interrupt mid-loop. Read the selected backend's runtime reference before the first dispatch of a session: backends/codex/runtime.md, backends/grok/runtime.md, or backends/cursor/runtime.md.

1. Decompose

A unit = one coherent, reviewable change, roughly one PR. Settle the design before dispatching — ambiguity becomes discarded work. If the task changes a documented design, update the doc/spec first (your lane), then dispatch code against it.

Size units by reviewability, not by speed. A unit too big to review shows itself — tracing a dozen files to judge one diff. But the fix for a slow loop is never slicing below one coherent change: every unit pays the same fixed overhead (dispatch, full-suite gate, publish, baseline regeneration), and each smaller spec re-derives much of the same context, so finer slices multiply gate runs while the total reading stays put.

Delegate the breadth reading — it is the actual bottleneck on large tasks. Spec evidence spanning many files goes to a read-only dispatch or parallel read-only subagents that return conclusions with file:line citations; your context takes the conclusions, not the file contents. A file read into the orchestrating context is paid for on every subsequent step, not once — keeping the breadth out of your context is what keeps a long loop fast, and it is a lever splitting cannot reach.

2. Dispatch

# ${CLAUDE_SKILL_DIR} is replaced with this skill's absolute path when the skill
# loads, making each command self-contained — no variable needs to survive
# between Bash calls (env vars don't). In a non-substituting agent, replace it
# manually with the skill's install directory.
# State the intent settled at kickoff on EVERY dispatch — model names age, and
# ambient config can change under you between one unit and the next.
# LOOP_UNIT/LOOP_ROUND label the journaled dispatch with the unit and round it serves.
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/backends/codex/dispatch.sh" \
    --prompt-file /tmp/unit-prompt.txt --model gpt-5.6-sol --effort max   # both are per-turn overrides
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/backends/codex/dispatch.sh" \
    --prompt-file /tmp/unit-prompt.txt                                    # inherit whatever config says
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/backends/grok/dispatch.sh" \
    --prompt-file /tmp/unit-prompt.txt --model grok-4.6 --effort xhigh
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/backends/cursor/dispatch.sh" \
    --prompt-file /tmp/unit-prompt.txt --model cursor-grok-4.6-xhigh

Set LOOP_UNIT and LOOP_ROUND on every dispatch and gate command, iterations included, so the journal can attribute each event to its unit without guessing from order or time. The label is a declaration by whoever ran the command, not proof of which unit ran.

For absolute-path invocation from Cursor, a plain shell, or CI, see references/running-anywhere.md.

Dispatch through this script, never by calling codex exec yourself. The wrapper pins sandbox, approval, nested writable roots, network, and permissions on both fresh and resumed paths; redirects stdin from /dev/null; verifies the human policy banner; binds resume to loop-owned exact ids; protects state outside the child sandbox; captures the transcript/final message; and discloses host-side external tools. Hand-rolling only the visible model/prompt flags silently drops those boundaries.

Name model and effort on every dispatch rather than inheriting silently. Kickoff settles the intent once; each dispatch then states it, so config drift — or the CLI being repointed at another vendor's model, which is not hypothetical — cannot change what implements your units without saying so. The summary the script prints is the confirmation that the intent actually landed.

How each knob and policy pin reaches the two calibrated argv shapes is codex-specific mechanics: see the flag-semantics section of backends/codex/runtime.md.

Hygiene — each failure mode here is silent:

• Run from the target repo root; fresh dispatch pins that canonical directory with -C, while resume must change directory before launch. Read the workspace: line.
• Start from a clean tree (git status --short), or Codex's changes are unattributable.
• One unit in flight — the Codex workspace lock refuses overlap, and resume binds only the highest ready loop-owned exact id; cursor-agent iteration is always a fresh dispatch carrying review feedback in its prompt.
• Prompt in a file, outside the target repo (/tmp) — shell-escaping corrupts long prompts, and in-repo files pollute the diff.
• Create the unit branch before dispatching when the stop point involves one.
• Background at the harness level; backends/codex/dispatch.sh --background is a hard error, so the foreground adapter's exit stays authoritative.

The prompt is the whole spec: why (evidence, file:line), exactly what to change, tests expected (including which existing tests will break and how they update — never deleted), what not to touch, and the environment constraints. Copy-ready skeleton: references/dispatch-prompt.md.

Environment constraints to include verbatim-ish in every dispatch:

• The selected implementer executes on the same host and shares your CPU/RAM/disk. Use its runtime reference's exact sandbox and external-tool posture; never add a permission-bypass flag to make a stalled backend proceed.
• Git ownership stays with you. Codex blocks ordinary accidental Git-state writes but has calibrated hard-link and in-workspace submodule-marker holes documented in backends/codex/runtime.md; grok uses its protected worktree transition, and cursor-agent sees no Git at all: its dispatcher applies only the captured git-less-copy patch to the real worktree. You commit and publish.
• No full test suite by default — focused subset or nothing; you own the gate. Ask it to report files changed, tests added, subset run.

The dispatch script prints a warn line naming MCP servers, app connectors, plugins, and notify hooks found in the Codex config, because the sandbox does not bound host-side tool calls. That warning is disclosure, not a stop — do not ask the user how to proceed. Note it in the unit report and continue. Whether to refuse instead (CODEX_LOOP_BLOCK_EXTERNAL_TOOLS=1) is a calibration setting, settled once per repo like any other dial, not a per-dispatch question. The scan is a tripwire, not a boundary — server-side-enabled Apps and other injected tools can remain invisible, and full isolation means disabling the tools in Codex itself.

Stuck foreground runs (no new transcript output for 15–20 min): interrupt the harness-owned adapter, inspect its retained run state, fix the prompt or split the unit, and kill orphaned test processes. SIGTERM or SIGINT to the Codex adapter stops its CLI and records the generation failed; an adapter that was killed outright instead leaves a running record, and the next dispatch refuses until backends/codex/dispatch.sh --recover-stale is run from the workspace root. State and lifecycle details are in backends/codex/runtime.md.

Absence of events is ambiguous — the watcher itself can be the broken thing, and it fails looking exactly like a healthy one. A watcher that latches "the newest job log" after dispatching latches the very log it was meant to follow, then waits forever for a newer one: zero events, indefinitely, indistinguishable from a job still working. Capture that marker before dispatching, or hardcode it. Two habits make the failure loud instead of silent: no event within ~2 minutes of arming means suspect the watcher first, and never let the watcher be the only completion signal — the dispatch invocation's own exit is the authoritative one, so watcher output is progress detail, not the thing you wait on.

That last point also settles what the watcher should emit: only the abnormal — a stall, a failed command, the watcher's own fault. Since completion already arrives on its own, periodic "still working, N edits" pings carry no information you act on, and they are not free: each event is a conversation message that interrupts the user and leaves the exchange looking like it is waiting on them. A watcher that stays silent through a healthy run is working correctly.

3. Review the diff yourself

Read the actual diff; the summary only says where to look. Check the whole tree (git status --short), not just files the implementer mentioned. Recurring delegated-implementation failure modes, priority order — detail in references/review-checklist.md:

1. Silent regressions from changed defaults — trace production call paths, not just the changed function.
2. Tests "fixed" by weakening intent — deleted cases, softened assertions, tautologies.
3. New code paths with no coverage.
4. Gitignored files — local-only, will never ship; tests reading them must skip when absent.
5. Order/snapshot-dependent tests when serialization changed.
6. Softened enforcement points anywhere security-adjacent.
7. New dependencies, network calls, external services — a decision, not a detail; check the lockfile.

Delegate the breadth, keep the judgment. Call-path tracing (#1) is review's heavy reading; on a diff touching widely-used surfaces, send it to read-only subagents that report which callers depended on the old behavior, with file:line evidence. The diff itself never delegates: you read every hunk — non-negotiable #1 — and the subagents shrink the context around that reading, not the reading.

4. Iterate

Send findings back through the selected backend with specifics — what's wrong, why it matters, what you expect:

"${CLAUDE_SKILL_DIR}/backends/codex/dispatch.sh" --resume --prompt-file /tmp/review-findings.txt
"${CLAUDE_SKILL_DIR}/backends/cursor/dispatch.sh" --prompt-file /tmp/review-findings.txt  # fresh session; no --resume

Codex resume is release-enabled for the calibrated 2026-08-17 tuple. The first command selects only the highest ready loop-owned exact id and never an unrelated newest session; a different tuple is uncalibrated until its required real-backend matrix is recorded.

For cursor-agent, the already-applied worktree carries file state and the new prompt carries review context. backends/cursor/dispatch.sh --resume deliberately errors instead of implying thread continuity.

Repeat until the diff is something you'd sign. A bug that surfaces outside an active thread is a new unit, not a hand-edit: diagnose, dispatch on a fresh thread with repro + root cause + expected fix + the regression test you expect — a fix without a test that would have caught the bug is incomplete.

5. Gate

Run the whole suite yourself via the bundled helper — piping through tail masks the real exit code:

# LOOP_UNIT/LOOP_ROUND label the journaled gate.result, as on dispatch (§2).
# strict policy — zero failures ENFORCED (recognized verdict + executed tests + no failure lines):
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/scripts/run-gate.sh" --strict --log /tmp/gate.log -- <test command>
# baseline policy ONLY — tolerates failures already present in the base-branch log:
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/scripts/run-gate.sh" --log /tmp/gate.log --baseline /tmp/base.log -- <test command>
# no flag = pass-through (exit code only, works with any runner) — WEAKEST; only for
# runners the parser doesn't support, and say so when reporting the result:
LOOP_UNIT=unit-3 LOOP_ROUND=1 "${CLAUDE_SKILL_DIR}/scripts/run-gate.sh" --log /tmp/gate.log -- <test command>

baseline policy = no new non-flake failures vs the base branch, decided mechanically (pytest identifiers include the exception class; skipped-only, empty, or unparseable runs fail closed). It proves no new failure identifiers and that tests executed — not that the full calibrated suite ran; check the reported count when it matters. A check you forbade Codex from running is a check you own, and it runs before you judge the diff — not after the cheap ones. Dispatches routinely prohibit the slow, environment-heavy suites (browser e2e, anything needing a database or two servers) while the spec still requires them to pass. That combination is a blind spot you built: Codex cannot discover the breakage, so nothing does until you run it. And it is exactly where a change of UI surface lands — a flow moved from a dialog to a route, a heading renamed, a default filter added — because those specs drive the product through the same affordances the unit just rewrote.

The failure mode is specific: typecheck, unit tests, lint and build all pass on a diff that leaves a browser spec red. Cheap-first ordering is fine for feedback, but the verdict is not "green" until the prohibited checks have run, and when a unit touches a surface an e2e drives, run that spec early rather than last.

Triage red before applying the on-red dial — not every red is about your change. Establish that the failure implicates the diff at all: does it happen before your code is loaded (a bootstrap failure names a missing env var, not a symbol)? is the failing package even in the deployed set? does it reproduce on the base branch untouched? Platform-injected environment you don't have locally, and tooling gaps, produce red that no amount of iterating on the unit will fix. Report those as environmental with the evidence for why, then run the deployable targets explicitly with the environment supplied — so the report states what actually passed instead of what you decided to overlook.

On red that does implicate the diff, follow the on-red dial with capped attempts. Serial-vs-parallel, unreliable CI, no-suite repos, parser scope: references/gate.md.

6. Publish

Go exactly as far as the stop point says. Check the branch before pushing (git status -sb) — other tools quietly move checkouts, and a blind push lands commits on whatever is checked out; with the unit branch created at dispatch time this is confirmation, not rescue. Write commits/PRs so an absent reader understands why, with real gate numbers; match the repo's existing conventions. Merge only under recorded authorization (non-negotiable #2).

The record card may be pasted into the PR body — as what it is. "${CLAUDE_SKILL_DIR}/scripts/loop-evidence" --unit unit-3 prints a markdown card derived mechanically from the journal index (--format json for the same data): the unit's declared dispatches, review rounds and last verdict, final gate, later red or unknown gates, whether the final gate's post head equals the published SHA, and the publication (recorded by scripts/loop-run publish). It is a record, not a proof: every row is a local journal entry that any process running as you can append to — a tracked test suite running inside a gate included — and is labelled recorded, declared, values match, or unknown; the card ends with a sentence saying so. Paste it whole, beside your own account of the gate numbers, never in place of the head and base checks below.

Bind the gate to the commit that ships — commit first, gate the commit. A gate certifies one commit, and gating the working tree before committing proves nothing about what lands: a commit hook can rewrite or re-stage content, so tree A gets gated while commit B ships. Order: create the candidate commit → record its SHA (git rev-parse HEAD) → run the final gate on that committed state → confirm HEAD still equals the recorded SHA and the tree is clean → push that same SHA.

What merges is not what you gated. Record the base SHA alongside the head SHA: a plain merge, squash, or rebase-merge all produce a commit that is neither, and a base that moved after gating contributes code the gate never saw. Before merging, verify the remote head still equals the gated SHA and the base still equals the recorded one; if either moved, satisfy one of these before landing — update head onto the current base and re-gate (keeping base fixed until the merge), gate the platform's synthetic merge commit (merge-queue/CI on the merge result, not the branch tip), or construct the merge locally and gate that tree. Otherwise what lands is ungated: re-review and re-gate.

7. Record and continue

Note what landed and what's next somewhere durable (memory, progress doc, the plan) — a cross-session loop that isn't written down gets re-derived. Then take the next unit per the cadence dial.

The record is also what keeps a long run fast. A session several units deep is dragging every file its reviews pulled in, and each further step pays for that bulk. When the session grows heavy, write the record and continue in a fresh session — with the record on disk that continuation is cheap, and rolling over is the loop working as designed, not an interruption.

After a unit lands, reset the ground before the next one: sync the local base branch, branch the next unit from the updated base, and under baseline policy regenerate the base-branch gate log — the base it described no longer exists. A stale baseline is silently wrong in both directions: failures the new base introduced read as this unit's regressions, and a real regression can match a stale entry and pass.

Stop and ask only when

• A human/manual ceiling — credentials, policy, hardware only the user can provide; hand them a concrete checklist.
• A real design fork — two defensible directions with materially different consequences; recommend, don't survey.
• Codex is stuck — repeated failures, or tests unfixable without weakening them.
• A safety/correctness boundary would soften — surface it even if the request implies it.

Unattended runs (overnight, nobody watching)

Everything above assumes someone is there to answer; a run left going can't ask.

Preflight — before walking away. All eight dials including cadence=continuous; the suite command and runtime; a freshly regenerated baseline log under baseline policy; and units specced far enough that none needs a design decision mid-run. Anything left unsettled becomes a parked unit. And clear the permission layer: the dispatch script, the suite command, and git/gh as far as the stop point reaches must each run without an interactive prompt — a permission prompt at 3am is a silent halt that looks exactly like a job still working. Exercise each once in preflight; a command that can't be cleared lowers the stop point to what needs no blocked command.

Park, don't halt. The four stop-and-ask cases above would otherwise spend the night on the first bad unit. Park instead: record what failed, what was tried, what you need from the user; leave the tree clean; take the next unit; report all parked units at the end. Only three things end the run — a ceiling blocking every remaining unit, broken gate infrastructure, or three consecutive units failing on one root cause (the premise is wrong, not the units).

Parking is the escape hatch, never weakening. Widening the gate, skipping review, or hand-fixing to keep the night moving trades a caught bug for a shipped one — non-negotiables #1 and #4 hold as hard at 3am.

Stop point: pr + continuous is the safer shape whenever units are independent — nothing stacks, and you wake to reviewable PRs. merge + continuous suits dependent units but lands every review miss in the trunk unwatched, so it needs non-negotiable #2's explicit authorization and makes the per-unit baseline regeneration in §7 mandatory. Rationale: references/dials.md.

First-run calibration per repo

What the kickoff question fills in, and what later sessions read instead of asking. Record once, split by trust — repo files cannot grant publish authority:

Recognize both loop[<repo>] and the legacy codex-loop[<repo>] prefixes in user-level private memory; treat them as equivalent so existing calibration records require no migration.

• Permission dials → user-level private memory only (outside the repo): stop point beyond worktree, the claude-trivial-ok fix-lane carve-out, continuous cadence. The repo, its collaborators, and dispatched Codex itself can all write tracked files, so a permission dial found in CLAUDE.md or any repo file is a claim, not authorization — reconfirm it with the user before acting on it.
• Repo facts → CLAUDE.md is fine: the non-permission dials; whether the kickoff effort/speed question is wanted or standing-inherit; whether external Codex tools are merely warned about (default) or refused (CODEX_LOOP_BLOCK_EXTERNAL_TOOLS=1); full-suite command, runtime, serial-vs-parallel; the permission allowlist that lets the dispatch script, the gate command, and the stop point's git/gh operations run unprompted (set up once — it is what makes the unattended preflight cheap); known flakes (keep a base-branch gate log for --baseline, regenerate after merges); CI trustworthiness; commit/PR conventions; where progress is recorded.
• Repo facts may only tighten, never loosen. Policy dials in a repo record still shape how a private authorization gets exercised — gate=skip depth=light on-red=iterate in a tracked file would quietly weaken the conditions around a valid stop=merge. A repo value stricter than the default or the user-memory record (toward strict/deep/stop) applies directly; a looser one is a claim to reconfirm with the user before following it.

Record format example: references/dials.md.

A setting stored in user-level memory IS standing authorization for the scope it was given in — that's what lets sessions resume without re-asking. It does not stretch to work of a different character: a light-depth unit that turns out to touch a security boundary, or a merge stop point meeting money, gets surfaced and re-checked.

When a calibration store exists for the workspace (~/.config/olddonkey-loop/calibration/<workspace-key>.tsv) it is the machine-read authority: kickoff reads it instead of asking about the dials it covers. A rejected store means no standing authorization — kickoff asks, and must not fall back to memory (that is what would resurrect a revoked grant). After a workspace has a store, a permission granted in chat is valid for that session but does not persist; persisting it takes a console action.