Supervised convergence

The use case: run an implement and check loop until it converges or needs you. This is not a chit runtime feature. It is an orchestrator pattern on top of chit's primitives, and it is the recommended shape today.

Why it lives above chit, not inside it

• chit manifests are static DAGs: no loops, no conditionals, no human-checkpoint step (parse.ts topological sort rejects cycles; step kinds are only call and format). A "repeat until" cannot be expressed in a manifest, by design.
• chit's implementer is real. claude-cli runs claude --print, which uses tools and edits files, and the converge manifest (examples/converge.json) drives it autonomously (by default a write-capable Claude implements and a read-only codex-exec --sandbox read-only reviews; the roles are assigned in the manifest, not fixed to a vendor, see self-hosting). So the executor can be either the interactive Claude Code chat (full conversational context, your per-edit approval) or a chit-spawned agent (autonomous, run under a worktree plus a human checkpoint).

So the loop and the checkpoint belong to the orchestrator (the chat); chit runs one bounded check per call.

The role split

One chit run is one turn of the loop. The while lives in the chat.

The loop

Per iteration (default budget: 3):

1. The chat implements one small, verifiable slice.
2. The chat calls the advisor with chit_start (the advisor manifest is a one-shot) using a stable scope per thread, cwd set to the repo, and inputs that describe the task plus what changed, then advances the review step with chit_next.
3. The chat decides on the proceed | revise | block verdict. proceed moves to the next slice (or stops if done); revise fixes and re-checks (verify each finding first, since Codex is not ground truth); block stops and surfaces to the human.

Stop conditions: a block; an ambiguous product or design decision; failing tests needing a user choice; any destructive or outward-facing action; or max iterations.

Supervised convergence is currently an operating pattern, not a packaged skill or bundled example. The stable primitive is the MCP run tools plus a human-driven loop.

What this is not (and why)

• Not the only mode. The autonomous loop also exists: the converge manifest (examples/converge.json) runs, by default, a write-capable claude-cli implementer plus a read-only codex-exec reviewer (the roles are manifest-assigned, not vendor-locked), driven from the MCP one iteration at a time (chit_start then chit_next) while a human sequences and checkpoints (run under a worktree). Supervised convergence is the lighter-weight mode when you want this conversation's context to do the implementing; reach for the converge manifest (see self-hosting) when you want the agents to run it themselves. The real constraint is unchanged: manifests cannot loop, so the iteration is always driven by an orchestrator, never the manifest.
• Not a manifest loop, conditional, or checkpoint step kind. That would break the static-DAG thesis; the chat loops and checkpoints for free.
• Not a second headless Claude inside chit. That is weak, context-blind, and drifts from the chat.

Reminders that bite

• Prefer codex-exec as the checker: it runs in a hard OS sandbox (--sandbox read-only), the firmest read-only guarantee. claude-cli also enforces read_only via --permission-mode plan (a softer, permission-level guarantee inside Claude, not an OS sandbox), so it can serve as a read-only reviewer too; codex stays the default for the strongest boundary.
• Reuse one scope per thread; pass cwd set to the repo; do not edit the advisor role mid-thread (it is in the session fingerprint and forks a fresh thread).
• Keep the advisor serial per scope (the session store has a read-modify-write race on concurrent same-scope writes).

Platform note (others building on top)

The substrate to build on is the MCP run tools (chit_start, chit_next, chit_status, chit_cancel, chit_trace) with one invariant: chit governs the declared legal order and runs one bounded handoff to a result; the orchestrator owns the loop and the checkpoint. Build loop policies (like this one) above that line, not inside the manifest.