What Is a 'Turn' in reins?

Image: AI generated

Anyone who has handed a large job to an AI agent knows this. The loop always collapses at the same point: the moment the model declares “I’m done” on its own — when in fact it isn’t.

reins is a quest CLI framework that takes that authority to declare completion away from the AI and hands it to a machine. It splits a work list into individual items like quests in a game, gives them to the AI one at a time, and decides “is it done?” not by the AI’s word but by machine inspection. And at its heart sits a small unit called the turn.

Two words will keep appearing, so let’s secure them first.

• Gate — an inspector that mechanically checks a submission and rules PASS or FAIL. Not a human’s impression, not the AI’s self-assessment.
• Ratchet — a gear that turns in one direction only. We use it to mean that an item locked by a pass never reopens.

This article follows one turn from beginning to end, through exactly what it goes through. The turn looks small, but taken apart, it is reins in miniature.

The Six Core Elements of Reins Engineering

Compress the engineering reins stands on into one line and it reads: the engineering of moving the authority to declare completion from the AI to a deterministic machine gate. “Deterministic” here is not a difficult word. It means the same input always yields the same result. A test either passes or fails, and yesterday’s verdict does not differ from today’s according to mood.

In the lineage of prompt engineering (choosing the words) → context engineering (supplying the context) → harness engineering (building the fences), Reins is the rein that sets the direction. This engineering is assembled from six elements.

It’s fine if the table’s terms still feel unfamiliar. The turn is the smallest unit where these six meet within a single cycle, so following one turn all the way through brings all six elements together, each in its place. Sketching the map in advance: compose, the turn’s first step, assembles the directional context and the deterministic feedback; judge delivers the machine verdict (cheese defense is the design quality of that gate); record locks the ratchet and persists progress.

What Is a Reins Turn?

A Reins Turn is the smallest unit of execution in reins, in which one attempt at one quest item concludes as generation → judgment → record. A loop is nothing but the repetition of turns, and a quest’s progress is nothing but the accumulation of turns. So the definition fits in one line.

Turn N = the Nth recorded Attempt. What is not recorded is not a turn.

An Attempt is “one record of one try.” Here lies a subtle point — a turn is not “the LLM was called once.” The condition for a turn’s existence is not the call but the record. If the LLM was called but the result was never recorded to the ratchet, that turn never happened. Conversely, a result a human submitted by hand, once recorded, is a turn. Even without an LLM. The one who counts turns is not the model but the ratchet.

This single definition is the root of every property to come — driver independence, restart resilience, auditability. For now, let the names just pass by. We will meet each again in its proper place.

One Turn Is Exactly Four Steps

A turn passes through four steps in order. The steps carry English names, but what they do is simple — assemble (compose), generate (generate), judge (judge), record (record).

“Pure function” means the same input always yields the same output with no other side effects, and “irreversible” means once executed it cannot be undone. Then the table’s core comes into view — of the four steps, only ② is probabilistic, and only ④ is irreversible. Generation cannot judge, and judgment cannot generate. The AI’s uncertainty is confined to one cell, and the undoable decision to another.

One peculiar design choice is worth noting. This four-step cascade is not implemented as two sets of Go code. It is defined in a single human-readable document called pkg/cli/turn.md (a TANGEUL document), embedded into the binary (go:embed) and interpreted at runtime. The canonical source of “how a turn runs” is not code but a readable document — the reason for this choice returns at the end of this article.

① compose — Context Comes Only from the Log

The Log is the ledger, kept on disk, in which every turn so far is recorded. And the input for assembling turn N’s prompt is exactly one thing: this Log. State that hides somewhere in program memory and vanishes when the process dies — no such thing exists.

The prompt assembled from the Log has three layers.

• What to do — what must be produced for this item (the writing instructions and the verification context)
• Manual — the global system prompt, plus, if the previous turn was a FAIL, the coaching for the rule that caused it (the per-rule manual)
• Feedback tail — the facts of the previous FAIL. “Where, what it should be, what it actually was”

In the language of the six elements above, the manual is the directional context and the feedback tail is the deterministic feedback. Both are assembled mechanically from the Log, every turn.

There is one subtle but important rule. What compose takes as its reference is not the last Attempt but the last Attempt that was judged — carried through to a verdict. Even if a generation error like an LLM server outage sits in between, what the retry sees is not the infrastructure error message but the fact-based feedback of the previous FAIL. Operational failures do not contaminate the work’s context.

② generate — The LLM Only Generates

The assembled prompt goes to the LLM backend in a single call. It does not matter whether the backend is an HTTP API (ollama/xai/gemini) or a command-line tool (claude/grok/codex/geminicli). Either way, its role is fixed: generator. The framework exposes no API through which an LLM could be granted PASS authority. It is not that the framework “chose not to grant” the authority to judge — there is no way to grant it. This is how element 1 of the six (machine-judged completion) becomes structure.

Even which backend to use is recomputed from the Log every turn. An item that keeps failing on the default model gets sent up to a stronger one (escalation), and this decision too is read off the Log each turn — “among the past FAILs’ causal rules, is any an escalation target?” There is no switch left on somewhere, no local variable inside the loop. Same program, same Log — same backend selected. The property of behaving identically after you kill and restart the process — restart resilience — comes for free.

③ judge — Only the Gate Judges

What rules on the output is the gate. A gate is a set of violation-detection rules. Each rule fires when it finds the problem it is responsible for, and leaves behind one fact — where (Where), what it should be (Expected), what it actually was (Actual).

Aggregation is deterministic. If even one Fail rule fires, FAIL. Otherwise, if a Review rule fires, REVIEW (a gray zone for a human to check). If nothing fires, PASS. Same submission, same rules — always the same verdict. There is no inspector here whose answer changes each time you ask.

In complex domains where rules entangle — where one violation makes another check meaningless — the verdict can be lifted onto an argumentation graph (toulmin), and the judging logic itself can be moved into an auditable document (gate.md). Whatever the form, one thing does not change: the judge is a machine.

④ record — The Only Irreversible Step

Apply the verdict to the ratchet, save to disk, and export the items that have concluded. This is the one point in a turn that cannot be undone.

• PASS / REVIEW / SKIPPED / BLOCKED → lock. The ratchet is one-way; it does not turn back.
• FAIL → the try count (Tries) increases by 1 and the item remains TODO. On reaching the maximum tries (default 3), it is locked as DONE. “This item does not work this way” is also a form of conclusion — one stuck item is not allowed to hold the whole loop hostage forever.
• Generation error → it is recorded in the Log as an Attempt (the trace of what happened is kept), but it does not consume a try. An LLM server going down is not the item’s fault; it is an operational failure. If the failure persists, a separate safeguard stops the loop (halt after N consecutive generation failures — a circuit breaker).

Only with this step does the Log exist for the next turn’s compose to read. record is the turn’s conclusion and the generator of the next turn.

Failure Is a Fact, Not an Opinion

What shape a FAIL comes back in — this is the key to a turn converging (getting closer to the answer with each retry). Not an opinion like “the quality is a bit lacking,” but this:

FAIL. root cause = who-anchor-present
  Fact: where=who.anchors expected="source substring" actual="Deputy Manager Kim Chanho"

Reading it is simple. Which field (where), what it should be (expected — a string that actually exists in the source), what it actually was (actual). Location + expected value + actual value. For the LLM, this is feedback with no one to flatter — numbers and locations are not emotions. It is this structured fact that leads a sycophantic model not into argument but into convergence.

One bonus on top. The FAIL text fed to the model is the exact same rendering as the string printed on screen when a human runs the submit command (feedback parity). The feedback a human sees and the feedback the model sees never diverge. The mystery of “what on earth was sent to the AI that it fixed it like this?” is structurally absent.

Three Entry Points, One Turn

Call whoever drives the turn a driver. reins has three: next, where a human receives the prompt directly; submit, where a human submits the result; and the unattended automatic loop. But these are not three separate implementations. They are three entry points into the same turn document. What separates manual from automatic is exactly one rule inside the document.

The practical property this yields: switch drivers mid-quest and the prompt stays byte-for-byte identical. Run the automatic loop yesterday, have a human take over with next today — given the same Log state, the same prompt comes out. It is possible because context comes only from the Log (we saw this in step ①), and it is a proven property, not a hope — a driver-swap golden test verifies byte identity by comparing outputs across drivers.

Following One Turn All the Way Through

Theory’s done. Let’s watch one real turn from start to finish. It is one item in a quest that extracts email addresses from documents, on its second attempt after the previous turn FAILed with “not a valid email format.”

[Turn entry check]  Is the item TODO? Are tries remaining? → proceed
① compose      Find the last judged Attempt in the Log → FAIL, cause = email-format
               Manual = global prompt + the email-format rule's coaching
               Prompt = what to do + "FAIL. Fact: where=email
                        expected='valid email format' actual='kim at example'"
② generate     LLM call → {"email":"kim@example.com", ...}
③ judge        Rule sweep: email-format passes, source-lacks-email passes, freemail passes
               → no Fail rule fired → PASS
④ record       Ratchet locks (irreversible) → Attempt #2 recorded → saved → export

The model, given the fact of the previous failure (“kim at example is not a valid email format”), fixed exactly that spot; the gate confirmed the pass; the ratchet locked it. This item is now PASS forever. The next turn skips it, and the remaining work only shrinks. When every item reaches a concluded state (PASS, REVIEW, or maximum tries), the loop ends. Not “when the AI feels finished” but when the remaining items hit zero. Convergence is guaranteed by structure.

Loop Engineering — The Industry Named the Same Problem

In June 2026, a shift in how agents are handled got a name. Peter Steinberger wrote, “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents,” and earlier that month Boris Cherny of Anthropic, who built Claude Code, said at an event, “I don’t prompt Claude anymore. I have loops running… My job is to write loops.” A few days later, Google’s Addy Osmani gave the current a name: Loop Engineering — from a person who prompts agents to a person who designs the systems that prompt agents.

This discourse draws a single narrative of transition. Prompt engineering (choosing the words) → context engineering (choosing what information to show) → harness engineering (building the execution environment) → loop engineering (designing the observe-act-verify-recover cycle itself). Leverage has moved outward one layer at a time: from words to information, from information to environment, from environment to cycle.

Osmani’s anatomy of a good loop should feel familiar to anyone who has read this far. Externalize state to disk or a board, not to the conversation. Separate the agent that builds from the agent that verifies. Let termination be confirmed by a separate adjudicator, not the coding agent’s self-declaration. Set it beside the turn and the correspondence is sharp.

The heart of the difference is the distance between recommendation and structure. The loop engineering literature itself concedes the hierarchy of verification — LLM-as-judge, entrusting the verdict to an AI, “can be gamed or can collude with the actor,” so wherever a deterministic check is possible, put a deterministic check. But that remains a best practice — a recommendation entrusted to the designer’s good will. If the verifier subagent is ultimately an LLM too, the door to collusion stays open. reins closes that door by design. Only the gate judges, and the framework exposes no way to give an LLM a PASS.

And where loop engineering speaks of the whole loop, reins turns one revolution of that loop into a contract. To go one step past Cherny’s “my job is to write loops,” what a loop does in one revolution — what is probabilistic, what is deterministic, what is irreversible — must be defined first. The name of that definition is the turn.

Why This Unit

Tighten the turn like this and you gain three things. The names that brushed past earlier find their places here.

• Auditability — the answer to “how does the automatic loop differ from the manual next?” is not a job of comparing two codebases but a single rule in a document. You can confirm with your own eyes that exactly one path in the document can lock a PASS. This is why the turn’s canonical source is a readable document, not code.
• Restart resilience — every input of a turn derives from the Log on disk, so even if the process dies, the same Log reproduces the same turn.
• Agent disposability — swap out the agents (LLMs, drivers) and progress still accumulates and never rolls back. “Agents are disposable; progress is cumulative.”

Put the other way around: a system where the turn is blurry — where context hides in session memory, the model self-declares completion, and retries lean on conversation history — loses all three.

The turn looks small. But as the smallest unit that separates and serializes generation (probability), judgment (determinism), and record (irreversibility) within a single cycle, to understand the turn is to understand all of reins.

Related Posts

• reins — Keep Only the Domain in a Quest CLI; Make the Ratchet a Framework — the framework this article stars, in full.
• Ratchet Pattern — How to Make an Agent Finish the Job — the full treatment of contract locking (element 4 of the six).
• How to Make a Quest CLI — Build a Tool That Lets the Machine Judge Completion — the practical blueprint: five quest parts, gate design, cheese defenses.
• Ratchet Code That Exploits IFEval — the experiment where deterministic feedback + directional context produce convergence.
• Reins Engineering — AI with Reins — the declaration of the prompt→context→harness→Reins lineage.
• TANGEUL — Rules Written in Markdown, Audited by Humans — why the turn’s canonical source is a document.

Further reading (external)

• Building Effective Agents — Anthropic — the classic on agent loop design. Its distinction between “workflows (deterministic orchestration) and agents (model-driven)” resonates with this article’s generation/judgment split.
• Agentic Loops: From ReAct to Loop Engineering — Data Science Dojo — a survey of the agent-loop lineage, from ReAct to loop engineering.
• The Anthropic leader who built Claude Code says he ditched prompting — now he just writes loops — The New Stack — industry coverage of Boris Cherny’s shift.

Sources

• Loop Engineering — Addy Osmani — 2026-06. The naming of the term and the anatomy of a good loop (automation, worktrees, skills, subagents, separate adjudicators, state externalization).
• What Is Loop Engineering? A Complete Guide from Prompt to Harness Engineering — Tosea.ai — the four-stage transition prompt→context→harness→loop, the determinism-first verification hierarchy, and the collusion risk of LLM-as-judge.
• Claude Code’s Creators Explain Agent Loops — The Neuron — Boris Cherny and Cat Wu on loop operations in detail: /loop and /goal, externalizing state to disk and Linear, separating builders from verifiers.

Changelog

• 2026-07-07: First edition