Skip to content

The Loop Contract

Designing the loop is the central act of loop engineering. Before any code runs, you answer five questions about the loop itself:

Design question What it decides Contract property
What? The purpose and what the loop may touch SCOPE
How? What the loop actually does each time it fires ACTION
When? What starts it — schedule, event, or signal TRIGGER
How much? The cost and runtime it is allowed to spend BUDGET
How do you know it's done? What "done" looks like and the verifier that confirms it STOP + verifier

The fifth question is a peer, not a footnote of "what." Knowing — and checking — when the loop is done is the hardest and most-failed design decision: it is what the Stop Condition Taxonomy below and all of Verification exist to answer. A sixth property, REPORT, says what the loop tells you when it finishes.

The Loop Contract is the concrete instrument for answering these. Get the design right and execution is mechanical; get it wrong and no amount of model quality rescues it. A loop without a complete contract is guaranteed to under-deliver or over-spend. This design step — not the prompting, not the model choice — is where loop engineering lives. ("The harness now matters more than the model" — see The Paradigm Shift.)

(Source: explainx.ai, "How to Build Your First Agent Loop: A Step-by-Step Guide", Jun 2026.)

The Six Properties

Each property answers one of the design questions above. Define all six explicitly before launching:

Property Question it answers Example
TRIGGER What starts this loop? PR opened, file changed, daily 08:00 UTC
SCOPE What can the loop touch? Only files in src/; read-only on main
ACTION What does it do when triggered? Run tests, summarise failures, open a GitHub issue
BUDGET What are the hard caps? --max-turns 50 --max-budget-usd 2.00
STOP When does it declare success? All tests pass, or issue is open with failure list
REPORT What does it say when done? Post a PR comment with pass/fail summary

A loop that lacks BUDGET or STOP is not a loop — it is a runaway process.

"If you can't say what 'done' looks like, you don't have a loop. You have a wish." — Sabrina Ramonov, Jun 2026

A Cost Datapoint — and How Far to Trust It

The most-cited number for why BUDGET exists, quoted exactly as its source states it:

"Uber capped engineers at $1,500 per person per tool per month for Claude Code and Cursor after burning its annual AI budget in four months, per June 2026 reporting in the discourse."

— explainx.ai, "Loop Engineering: How to Design Coding Agent Loops That Run While You Sleep (2026 Guide)", Jun 2026

Three things the KB previously got wrong or dropped, now restored: the cap is per person per tool per month, not a flat per-tool cap; it covers two tools (Claude Code and Cursor); and the source itself claims no primary reporting — it attributes the figure to "reporting in the discourse," meaning social-media discussion, not a filing, a press report, or Uber. Treat it as a widely-repeated anecdote, not a measurement. No primary source has been located (KB_GAPS.md V17).

That caveat does not weaken the design point, because the design point does not rest on the number: a per-seat spend cap imposed after the fact is what BUDGET-by-design exists to make unnecessary. See also Cost & Turn Control, which carries cost figures that are primary-sourced and arithmetic-checked.

The Anchor File Pattern

The Loop Contract can be materialised as four files in the repo:

File Purpose
VISION.md High-level goal — what success looks like at the end
CLAUDE.md Rules — what the loop can and cannot do
AGENTS.md Roles — which agent does what in multi-agent setups
PROMPT.md Task — the current specific work unit

The loop reads all four at startup. Updating PROMPT.md re-tasks the loop without changing its rules or goal.

Plan-as-contract for one-off fleet dispatch. A lighter variant for a single orchestrator dispatching to worker agents (rather than a standing loop): the orchestrator writes one plans/<name>/PLAN.md per unit of work — the SCOPE and ACTION properties for that dispatch — and the worker's only contract is to execute exactly that plan and report back. Because the plan lives in git, a failed dispatch can be trivially re-issued from the same file rather than re-specified from scratch. (walidboulanouar/loop-engineering, Jul 2026.)

Quota-Aware Should-Run Gate

A refinement of the BUDGET property for loops that persist across many agent turns and restarts: rather than BUDGET being only a hard ceiling (spend no more than $X), gate every turn through an explicit should-run decision. loopx's own state model (docs/quota-allocation.md) recognises seven compact states — eligible (run now), focus_wait and waiting (blocked on delivery focus or external evidence), throttled (quota spent), operator_gate (needs a human decision), paused, and blocked_health (registry/contract/boundary problem) — collapsing, for this doc's purposes, to: run now, wait, ask a human, or stay idle. This turns "did we run out of budget?" from a single end-of-run check into a per-turn admission decision, and gives the loop a defined state for "there is budget left but proceeding isn't the right call yet" — a case a binary budget cap cannot express. Paired with a safe fallback rule: when the primary (P0) objective is gated, the loop may still make progress on lower-priority (P1) work rather than sitting fully idle, provided that work is tracked with the same evidence and ownership discipline as the primary objective (see claimed_by todo ownership). (huangruiteng/loopx, Jul 2026.)

Two Quality Gates

Before a loop iteration continues or launches, apply two explicit checkpoints:

Gate Question When
Gate 1 — Evidence completeness Is the output backed by objective evidence (test results, logs, metrics)? Before allowing the loop to continue to the next iteration
Gate 2 — Stopping condition clarity Can you state exactly what "done" looks like before the loop starts? Before launching the loop at all

Gate 2 maps directly to the STOP property in the Loop Contract above. Gate 1 is what enforces it at runtime — without objective evidence, the loop cannot know whether STOP has been met.

(Wooheum Xin, "もうプロンプトを書くな──「Loop Engineering」という新しいパラダイムの正体" — "Stop Writing Prompts: The True Nature of the New Paradigm Called Loop Engineering" (translated from Japanese), Zenn, Jun 2026.)

Stop Condition Taxonomy

The STOP property is the single most-cited failure point in loop engineering. A loop that cannot say what "done" looks like stops too early (undercooked), runs forever (overcooked), or never reports (forgotten) — the rice-cooker problem. (Martin Ma, "What the Hell Is Loop Engineering?", Jun 2026.)

Every STOP property is built from one or more of four stop-condition categories. This is the canonical taxonomy — other docs reference it rather than re-defining it.

"Done" scales with who's asking, not just what the task is. A practical framework for setting the completion check itself, by organizational scale: at enterprise scale, build internal eval systems ("school for agents" — cites Block's Goose and Shopify's River), integrate into the tools the team already uses, and tie evals to company standards rather than generic benchmarks — a code-review test being "can your second- or third-best engineer understand a random agent-written file within 20 minutes?" At SMB and solo scale — which the source treats as one group, since neither can build an enterprise-style internal eval system and both stay closer to their own tools — tie the metric to an observable business outcome (replies earned, not emails sent; problems resolved, not tickets closed) and have the owner personally verify domain-expert areas. The sharpest line, applicable at every scale: "agents optimize for the grader, not the goal" — the completion check is the spec, as far as the agent is concerned, so a grader that doesn't match the real goal gets gamed by construction, not by malice. (MindStudio, "How to Define 'Done' for AI Agents", Aug 2026.)

Category Fires when Role
Completion check A verifier confirms the objective is met (tests pass, VERDICT: PASS, checklist complete) The only success stop
Budget exhausted --max-budget-usd or --max-turns cap reached Safety stop — contain cost
Max iterations Fixed iteration count reached (e.g. /goal stop-after-N: rename 25, CSV 30, PDF 40 turns) Safety stop — bound runtime
No-progress (stall) N consecutive iterations produce no measurable change (no new passing test, no diff) Safety stop — detect dead-ends

Only the completion check means success. The other three are safety stops: they prevent a runaway but leave the work incomplete, so they must escalate to a human or a retry — never report PASS. A production loop pairs a completion check (success) with at least one safety stop (containment); a loop with only safety stops can never succeed, and a loop with only a completion check can never be contained.

Verification is the completion check. "An agent loop without a verifier just compounds its own mistakes on a schedule." (@bojan_ai, Jun 2026.) The completion-check stop is only as trustworthy as the verifier behind it — see Verification for building a verifier the STOP property can rely on, and the maker/checker separation that stops the agent grading its own work.

The runtime termination signals in The Core Agent Loop Cycle (success, error_max_turns, error_max_budget_usd, Stop-hook rejection) are the mechanical events that enforce these design-time categories: success enforces the completion check; error_max_turns / error_max_budget_usd enforce the budget and max-iteration stops.

(Stop-condition categories: Akshay Pachaar, "Loop Engineering Clearly Explained", Jun 2026; bounded N-turn examples: Sabrina Ramonov, Jun 2026; three-checkpoint model: MindStudio, Jun 2026.)

Write the done condition, not a better prompt. The completion check is where the design effort belongs, not step-by-step instruction quality: "an agent given a checkable definition of finished can find its own way there and can tell you when it did not." A loop with a vague or unchecked done condition can't self-correct no matter how carefully the rest of the prompt is written — restating this section's own point from the builder's side rather than the taxonomy's. (@kachar136, Sep 2026.)

The same author backs this with an audit of his own usage: across 138 Claude Code /goal invocations over five weeks and eleven projects, 73% never stated a done-condition (86% on a strict reading). His own read of that gap is not that those goals were sloppy — the done-condition "didn't disappear, it got factored out" into standing rules held once in CLAUDE.md rather than repeated per goal. He offers 85 of 100 session-opening goals still naming no done-condition as confirmation the standing gates cover session starts too, not as a residual failure. The load-bearing caveat for treating /goal as a verifier: "the evaluator is a fresh model, but it cannot run your tests. It reads Claude's account of having run them." (Ilko Kacharov, "Write the done-condition, not the prompt", Jul 2026.)

Reference implementation: the three exit codes

A minimal loop that provably halts maps the taxonomy onto three deterministic exit codes, with the check run by the loop itself (not the agent — see Verifier Integrity):

Exit Category Fires when
0 Completion check the real check passes
3 No-progress the objective score stays flat for K iterations
2 Max iterations a hard iteration ceiling is hit

Two design points sharpen the taxonomy:

  • Score the goal, not the activity. No-progress is measured by an objective score=<fraction> line, where the scorer "exits 0 iff the goal is met." "Progress is the score moving, not 'did files change' — a busy-but-stuck agent still halts." A loop that watches for file edits or token spend mistakes motion for progress.
  • The verifier is external. The loop runs the real check every iteration, so the worker cannot fake completion; the control system is fixed and deterministic while the worker is stochastic and swappable.

(uppifyagency/loop-kernel, Jun 2026; firegnu/herdr-loop-lab, Jun 2026, independently converges on three exit codes for its own three-way halt — 0 = all satisfied, 2 = stalled/timeout/cap, 3 = quota exhausted (resumable) — though its 2/3 assignment differs from loop-kernel's.)

Extension: tamper-evident contracts and named exit codes

Three exit codes are the floor, not the ceiling. A Product Contract — the goal, acceptance criteria, verification commands, and stop conditions — can itself be tampered with (by the agent under pressure to declare success, or by an external edit); hashing the contract at approval time and treating any mismatch as its own stop condition — a hard, fail-closed refusal to start (exit 2) before the run ever begins — closes a gap the basic taxonomy doesn't address: the spec drifting is a different failure than the work drifting, and needs its own detectable, named exit state. Expanding from 3 to more named exit codes (loop-kit's own README described its stopping model as "eight named states with exit codes" at this doc's Jul 2026 writing; the project has grown since — 12 named states across 6 distinct exit codes as of Sep 2026) (rather than reusing one code for several distinct failure classes) makes the caller able to distinguish "no progress" from "spec tampered" from "reviewer disagreed" without parsing log text.

(Aitne-sh/loop-kit, Jul 2026.)

Experience Encoding — The Loop's Learning Step

After each iteration completes and before context is cleared, encode what was learned back into the project's persistent knowledge:

  1. Rules — add a new CLAUDE.md rule if a mistake was made that a rule would prevent
  2. Templates — update or create a skill in .claude/skills/ if a reusable procedure emerged
  3. Negative lessons — document anti-patterns encountered so the next iteration avoids them
  4. PROGRESS.md — mark the completed task and note any blockers or discoveries

This step closes the learning loop: each iteration makes the next one smarter, not just incrementally further along. The cycle is:

Goal Contract → Execution → Evidence Gate → Stopping Condition → Experience Encoding → next cycle

Skipping Experience Encoding means the loop accumulates runtime progress but no institutional knowledge. The skills file stays empty; the same mistakes recur.

Job-Description Framing

Rather than writing a loop prompt as a technical specification, write it as an employee onboarding document. A new employee needs:

Onboarding element Loop Contract property
Job title and scope TRIGGER + SCOPE
Output deliverables ACTION + REPORT
Working hours / frequency TRIGGER schedule
Escalation path Human-in-the-Loop gate — when to ask a human
Performance standard STOP condition
Budget authority BUDGET cap

The framing shift matters because onboarding documents describe intent and judgment boundaries — exactly what a loop needs to act autonomously without constant supervision. See Human-in-the-Loop Escalation.

(Claire Vo, Lenny's Newsletter, "How I AI: How to write AI agent loops", Jun 2026.)

Event Modeling — Task Decomposition for Loop Contracts

Event Modeling (Martin Dilger, Jun 2026) applies the Loop Contract to individual feature slices rather than to the whole task:

  1. Slice the work into discrete functionality units — each slice has clear status transitions: Planned → In Progress → Blocked → Done
  2. Assign each slice to one agent invocation — the slice is the unit of work for one context window; prevents confusion between tasks
  3. Subscribe agents to board changes so they automatically claim available slices
  4. Prevent concurrency — once a slice is In Progress, no second agent can claim it

The critical rule: never argue with an agent mid-task. The agent is not learning from your corrections — it agrees and carries the confusion forward until, in Dilger's words, "the signal is completely buried in the noise." Confusion is what produces hallucination: not a random event but the predictable result of a polluted context window. Instead:

1. Define tasks clearly before launching the agent
2. Execute one slice per clean context window
3. Record learnings in GOAL.md / CLAUDE.md after completion
4. Clear context completely
5. Start the next slice from a clean window with recorded learnings

"Clean iterations with recorded learnings will outperform long, polluted conversations every single time." — Martin Dilger, "Loop Engineering — or why you should never argue with an agent", Jun 2026

Governed Cross-Session Learning

Experience Encoding (above) captures per-iteration learning. Cross-session learning accumulates patterns across 2+ sessions and promotes them to standing rules:

Skill What it does When to use
/evolve Analyses session transcripts, extracts recurring patterns, records them as learnings After 2+ completed sessions on a loop
/reconcile Promotes eligible learnings into proposed .claude/rules/ files for operator approval Before any pattern is applied standing

Implementation note: /evolve and /reconcile are not built-in Claude Code commands. They are implemented as Claude Code Skills — on-demand workflows defined in .claude/skills/. To adopt this pattern, create evolve.md and reconcile.md as skills in your project.

Critical constraint: nothing auto-applies. /evolve produces a draft; /reconcile produces a reviewable file. The human reviews and approves before any pattern becomes a standing rule. This prevents the loop from silently encoding bad habits as governance.

The review gate for each proposal: 1. Does this pattern actually improve outcomes, or just describe what happened? 2. Does it conflict with any existing rule? 3. Does it generalise correctly, or is it specific to one anomalous session?

(session-orchestrator — Kanevry/session-orchestrator, Jun 2026.)

YAML-Declarative Loop Definition

Loops can be specified declaratively (rather than as imperative scripts), making the contract machine-readable and auditable:

# .loopflow/loops/pr-babysitter.yaml — VERDICT: PASS gate protocol
name: pr-babysitter
description: Babysit open PRs until CI is green and reviewed.

budget:
  max_usd: 1.00
  max_iterations: 3    # loopflow's real field; the schema caps this at 1–20 (default 3)

worktree: false        # set true to run in an isolated git worktree

steps:
  - id: fix
    prompt: ...
  - id: review
    gate: true         # must emit VERDICT: PASS or VERDICT: FAIL
    prompt: ...

VERDICT: PASS gate: a loop iteration is not done until it explicitly outputs VERDICT: PASS with supporting evidence. An iteration that ends without a verdict is treated as VERDICT: FAIL. This eliminates "looks done" exits where the agent ran out of turns mid-task.

Defense-in-depth budget enforcement: one configured ceiling, enforced twice — loopflow's own tracker checks cumulative spend, and the remaining budget is passed to every Claude invocation as --max-budget-usd, so a single runaway step is capped by Claude Code itself:

budget:
  max_usd: 2.00        # the only USD field in the schema — there is no separate per-step cap
  max_iterations: 3    # 1–20, default 3

(faisalishfaq2005/loopflow, Jun 2026.)

Self-Discovery Loop Pattern

Rather than relying on external work queues, a self-discovering loop finds its own tasks from live system signals each run:

Schedule → Discover → Build → Verify → Repeat
  1. Schedule — fire on cron or event; always exit early if nothing to discover
  2. Discover — scan failing CI runs, open issues with matching labels, recent commits that touched scope files; produce a ranked task list
  3. Build — each task runs in its own isolated git worktree; tasks are independent and can parallelise
  4. Verify — CI or dedicated verifier agent confirms the fix before merge
  5. Repeat — write learnings to GOAL.md / CLAUDE.md; next scheduled run starts from the updated state

Self-discovery eliminates the manual queue maintenance step: the loop knows what to work on because it reads the same signals a human engineer would check in morning triage.

(Attribution corrected 2026-09-06: this pattern is not from Anthropic's engineering blog — that index carries no June 2026 post and nothing resembling this five-step loop. It is a community synthesis that circulated around Jun 2026; the closest checkable primary source is Addy Osmani, "Loop Engineering" (7 Jun 2026), which quotes Boris Cherny and Peter Steinberger on the framing. Re-attribute to a specific, verified source before this section is quoted onward — see KB_GAPS.md.)

Relationship to Goal Engineering

When a loop's STOP condition is deterministic and the task is non-recurring, the loop degenerates into a Goal — a bounded task with a single verifiable completion state. The Goal Engineering doc covers the four Goal Primitives and the GOAL.md persistent state file in detail.

Cross-Run Memory Persistence

Every loop run should append a brief outcome record to a persistent memory file. This gives the next run the context of what the previous run found, decided, and cost — without requiring a human to summarise it.

# .loopflow/memory/pr-babysitter.md  (appended after each run, prepended to next run's prompt)

## Run 2026-06-25T06:41:00.000Z
- Outcome: success (iterations used: 2)
- Cost: $0.31
- Steps: fix ✓, review ✓

### Notes
2 stale PRs closed, 1 draft marked ready. PR #88 auth migration — merge blocked on CI flake,
not code; re-check PR #88 first next run.

"The agent forgets; the repo doesn't."

The memory file is distinct from STATE.md (execution phase) and GOAL.md (done conditions). It is an episodic log optimised for the next agent invocation — not a recovery mechanism but a continuity mechanism. See Memory Patterns for storage backends.

(faisalishfaq2005/loopflow, Jun 2026.)

Gate Feedback Injection

When a VERDICT gate returns FAIL, inject the rejection reason into ALL agent prompts in the next iteration — not just the gate step's prompt.

Standard retry pattern: gate fires → same loop re-runs → gate fires again.

Gate feedback injection: gate fires → rejection reason prepended to EVERY agent's task prompt → next iteration starts with every sub-agent aware of why the previous attempt failed.

This is distinct from simply retrying. The failure context propagates laterally to agents that weren't involved in the failing step — preventing them from repeating setup conditions that contributed to the failure.

Example injection:

[PREVIOUS RUN FAILED] Gate rejection: "PR description is missing the test evidence section.
All PRs must include a test output block." — apply this constraint in all PR-related steps.

(faisalishfaq2005/loopflow, Jun 2026.)

Concrete STOP+Verifier Implementations (Sept 2026 cohort)

A cluster of independent projects converged this run on the exact same shape: a scheduled or on-demand loop where the harness — not the agent — owns SCOPE/BUDGET/STOP and never merges or promotes a change without a separate verifier's sign-off. Read together, they are evidence the six-property contract above is not just a design heuristic but a pattern multiple unrelated builders arrive at independently once a loop runs unattended in production.

  • dream-machine — a 13-stage nightly pipeline that ends every cycle in ACCEPT / REJECT / INCONCLUSIVE, never merging autonomously (the human promotion gate is retained by design). Built explicitly against the Sakana AI Scientist reward-hacking failure mode, using adversarial critique and cryptographically witnessed provenance so a claimed pass can be audited after the fact. Extends metaharness's Darwin Mode into a full scheduled STOP-verifier loop rather than an on-demand mutation check. (ruvnet/dream-machine, Sep 2026.)
  • autogenous — "Governed Evolutionary Software": a closed production loop (observe failures → explain → generate adaptations → test → promote-or-rollback) that converts runtime failures into typed mutations. Adaptations ship as signed, capability-constrained, expiring "Antibody Packages," and promotion requires ≥2 independent pinned-judge signatures before a staged canary rollout with automatic rollback. A concrete, code-enforced SCOPE/ACTION/TRIGGER/BUDGET/STOP+verifier contract for production self-repair — the multi-judge signature requirement is a stronger completion check than this doc's own Stop Condition Taxonomy assumes by default (single verifier). (ruvnet/autogenous, Sep 2026.)
  • openAVO — a governed autonomous reasoning harness where the agent freely inspects/hypothesizes/edits/executes/evaluates/repairs, while the harness alone owns permissions, budgets, invariants, rollback, and evidence; every state transition produces a hash-chained signed receipt. Reports +160% resolved-task improvement over baseline on SWE-bench Verified at +97.7% cost — and is explicitly flagged by its own authors as exceeding the economics threshold for production release, a rare instance of a source reporting its own result as not yet worth shipping. (ruvnet/openAVO, Aug 2026.)
  • sparc — enforces the five SPARC phases (Specification/Pseudocode/Architecture/ Refinement/Completion) as an executable TypeScript state machine with immutable phase ordering and Ed25519-attested tamper-evident evidence. The key STOP-integrity detail: agents cannot self-execute their own stored test commands — evidence must come from a separate verifier process, closing the same self-grading gap Verifier Integrity documents. (ruvnet/sparc, Sep 2026.)
  • loop.js — states a Goal; rounds run until a skeptical, read-only Verify agent (no self-grading) settles it, with failure reasons feeding forward into the next round. Budgets (rounds / USD / timeout) are declarative and explicitly framed as runaway guards, not completion criteria — the same distinction this doc's Stop Condition Taxonomy draws between safety stops and the completion check. (loop-js/loop.js, Sep 2026.)
  • loop-contract-skill — states the whole doctrine of this page as a repo tagline: "an agent is bounded by its verifier, not its model." Implements frozen scope, red-before-work executable oracles (the check must fail before the fix is attempted, proving it actually tests something), per-item proofs, and a gate script (fold_ledger.py) that mechanically refuses to accept an unverified claim. DONE vs. KNOWN modes generalize the contract beyond code to data and research work. (hdkhosravian/loop-contract-skill, Aug 2026.)
  • DeMARS — outside software entirely: a computational-materials-science framework combining deterministic algorithms, bounded LLM-based judgment, task-specific verification, episodic maturation, and complete delegation — a Loop-Contract-style SCOPE/verifier pattern applied to scientific computing, evidence the contract shape generalizes past coding agents. (arXiv 2609.00795, "Agentic programs: an emerging form of scientific software", Sep 2026.)
  • Anthropic's own control-band framing (AI-Native SDLC). Rather than one STOP condition, the playbook grades a monitoring loop's own confidence into three escalating tiers, each with a different authorized action:
    tiers:
      1sigma: { action: log }
      2sigma: { action: diagnose, tools: "Read,Grep,Bash(gh run view *)" }
      3sigma: { action: propose, routes: [pull_request, runbook:rollback-deploy] }
    
    At 1σ the deviation is only logged; at 2σ Claude is invoked read-only to diagnose; at 3σ Claude may propose a fix — routed to a PR or a pre-approved rollback runbook, never applied directly. This is a BUDGET-shaped answer to a different question than the patterns above: not "when does the loop stop" but "how much autonomy does this run's own confidence level earn it" — a graduated authorization ladder rather than a binary STOP/CONTINUE. The same playbook states the maker/checker separation this KB documents elsewhere as a flat rule: "the agent that wrote the code has no way to approve it"; approval comes from a human through branch protection, informed by the findings. (Anthropic, "The AI-Native SDLC Playbook", Aug 2026.)
  • loopgain — replaces a fixed max_iterations cap with a stability-theoretic stopping condition: it applies the 1921 Barkhausen stability criterion to the agent loop's own error signal, classifying convergence via a multi-feature statistical detector rather than counting rounds, and rolls back to the best-scoring prior attempt if the run doesn't hold. On a public 2,000-trial benchmark this cut API spend by 92.8% versus a max_iterations=20 baseline — with an honestly documented failure mode: 4.5% of runs the detector called "converged" still failed a held-out test suite, i.e. the stopping condition is a strong cost lever, not a substitute for an independent verifier. Ships adapters for LangGraph, CrewAI, AutoGen, LangChain, the OpenAI Agents SDK, and the Claude Agent SDK. (loopgain-ai/loopgain, Sep 2026.)
  • A deterministic (non-prompt) circuit breaker. Rather than asking the model whether to stop, a code-level breaker normalizes failure signatures and uses trigram-Jaccard similarity (with containment) to detect "same failure, reworded" — distinguishing real stagnation from an agent that is actually making progress but describing each attempt differently. It also treats a "bookkeeping" iteration (one that touches files but closes no acceptance criterion) as transparent to the failure chain: it neither counts as progress nor resets the stuck counter, closing a gaming path a naively-implemented breaker would miss. Paired with a design-interview gate requiring ≥95% confidence across all dimensions before implementation starts, and a fresh-context "tenth-man" critic obliged to assume a signed-off plan is wrong. (huvii174/loop-engineering-plugin, Sep 2026.)

A later release replaces the breaker's free-text failure history with a single deterministic writer (loop-record.mjs) enforcing a strict verdict enum — closing a gap where prose history could let a genuine two-verifier-REJECT stagnation streak score zero on the circuit breaker. (huvii174/loop-engineering-plugin, v0.16.0, Sep 2026.)

The 0.18.2/0.18.3 releases move the per-item close out of prose too: loop-close.mjs makes closing a single work item a coded step (evidence attached, gate re-checked) rather than an instruction the agent follows on trust, alongside a new convergence rule scoped to specific evidence, a budget policy, a silent run-gate, and an epic-level gate sitting above the per-item one — the same "code the check, don't prompt for it" move loop-record.mjs already made for stagnation detection, now applied to closure itself. The later 0.19.0/0.19.1 Codex distribution exposes the workflows as skills through one runtime adapter; the deterministic scripts (breaker, recording, close, archive gates) still enforce, but the mechanical edit- and stop-blocking hooks stay Claude-only, so on Codex those two blocks are not hook-enforced (commit, Oct 2026). (huvii174/loop-engineering-plugin, v0.18.2/0.18.3, Sep 2026.)

  • A three-way closure-eligibility gate, mechanically checked. Where the huvii174 gates above check when to stop working, this checks whether a completed item is safe to close: reading the full descendant tree without writing status, it returns refuse (a precondition is missing), not-eligible (live descendants remain open), or eligible (an evidence packet ready for human confirmation) — a concrete three-way STOP/verifier split for the specific "can this be marked done" decision, distinct from "is this done" (the completion check above). (eugenelim/agent-ready-repo #1456, Sep 2026.)
  • A prefilter fixed to stop flagging its own in-progress marker as a collision. A small but concrete stopping-gate bug: a prefilter ahead of an LLM gate was comparing the current round's own [IN_PROGRESS] line against itself and treating the match as a self-collision false positive; the fix ignores the current round's own marker. The same release adds optional pre-checks placed in front of existing LLM gates, off by default — cheap deterministic checks that can short-circuit an expensive verifier call without replacing it. (InjayTseng/loop-engineering-on-product, Sep 2026.)
  • A new completion-assertion claim class for gate verdicts made without receipts. session-orchestrator's v5.3.0 adds PSA-006, flagging a "gate-verdict" completion claim that carries no attached evidence — the same failure this doc's Stop Condition Taxonomy guards against structurally (only a completion check backed by a verifier counts as success), now checked as a named, catchable claim class rather than left to review discretion. The same release adds hierarchical process-group management (SIGTERM→grace→ SIGKILL) with an orphan-reaper that re-verifies PID identity before killing, closing a pgid-recycling false-kill risk in long-running supervised loops. (Kanevry/session-orchestrator, v5.3.0, Sep 2026.)
  • Two retry budgets, and escalation only on plateau. ralphctl drives Claude Code, Copilot CLI, Codex CLI, OpenCode or Grok Build per task through a generator, then an independent evaluator, then a verify gate. Its README states that the two gates spend different budgets: a failed review re-runs the generator inside the same attempt, up to harness.maxTurns; a red verify fails the attempt and opens a fresh one, up to harness.maxAttempts, after which the task is marked blocked. A "strong-gate" preset pairs a cheap generator with a permanently flagship evaluator, and an escalation ladder climbs a model tier only on plateau. A concrete BUDGET and STOP example: the cap on revising and the cap on restarting are separate numbers, and the strong-gate preset puts the expensive model on the checker rather than the maker. (README claims, last push 2026-10-19; not independently tested here.)
  • A human gate whose results are recorded, not just passed. neal's planner/coder/reviewer loop now keeps a per-run record of each manual gate and shows the results to the coder and both reviewers, because passing gate checks only prove the operator did the work, not that it worked. On failure the coder opens a new gate or splits the plan so the fix is reviewed and the gate re-run, and an operator message can close a waiting gate whose checks can never pass — a way out for a human-in-the-loop stop condition that would otherwise deadlock. (navels/neal, 2026-10-08.)
  • Replan freedom versus a plan lock. ADR-0144 (accepted 2026-10-11) makes a supervisor shipped inside the work-loop skill the single owner of delivery procedure, replacing a phase engine, cohort writer, whole-plan hash lock and legacy review gate. Task order and decomposition can then change after initial review without approval, while criteria, evidence and structured review facts stay the only authority for completion. The ADR's stated trade-off is that an in-flight run started under the old engine is re-derived by the loop rather than read through a compatibility adapter; "pin the completion authority, not the plan" is this KB's own gloss. A companion verb, loop-cohort, screens a wave before dispatch and returns parallel-capable or sequential from plan Touches: globs and cohort state, under owner-approved input bounds and a closed set of refusal codes; the screen is explicitly not a greenlight.

Benchmarking the controller, not just the harness. LoopArena evaluates models specifically as runtime controllers guiding coding agents through long tasks — the loop-engineering equivalent of a harness conformance suite (docs/24), but scoring the controller's STOP/TRIGGER decisions rather than the harness's capability surface. Best Strict Success Rate on the benchmark: only 24.69% — evidence that getting the contract right in principle and a model executing it reliably in practice remain two different problems. A lightweight "Type II" evaluation correlates highly with full-task results as a cheap proxy metric for iterating on controller design. (arXiv 2608.28281, "LoopArena", Aug 2026.)

Guards That Failed Open

Several unrelated repos reported, within weeks of each other, a stop or verification guard that looked present and passed while checking nothing. Each is the same defect: a check that cannot tell must fail, and instead it passed. Cited from commit messages and release notes, so the measurements are the authors' own.

Repo What passed silently Fix
cobusgreyling/loop-engineering (loop-context, 2026-10-10) --similarity-threshold 95 (meant as 95%) switched stagnation and repeated-action detection off, so four identical failures returned CONTINUE CLI and library reject values outside (0, 1]; loop-drill reports a rejected config as a failed breaker drill
same repo (loop-audit, 2026-10-10) 19 empty files (142 bytes) scored 100/L3 on fileExists() signals Ignore placeholders; gate L3 on loop-drill.json proofs (see Maturity Model)
sdsrss/loop_eng v0.20.0 (2026-09-21) An unattended driver's (polish and autoloop) dirty-tree guard answered CLEAN on a dirty tree (grep -vq and a SIGPIPE under pipefail) Unattended drivers now exit 1 with "dirty tree, refusing unattended run"
andrewcigan/vibe-dev-plugin v9.0.4 (2026-10-03) A commit-scope guard checked zero commits because no writer maintained the field it read Derive the active feature from per-entry state; commit message reports 68 of 199 historical commits blocked by the old rules versus 23 by the new, all genuinely out of scope
same plugin v9.0.3 (2026-09-30) A guard's remediation hint named a relative script path; the agent ran a project-local lookalike that corrupted history state Installer writes the plugin path; a test executes every hint command from the filesystem root and checks the consequence (31 of 33 fail on the old code)
huvii174/loop-engineering-plugin 0.18.3 (2026-09-25) An instruction-only epic gate was found failing in its own epic Archive refuses the last item's run without a recorded epic_gate; no flag waives it
eugenelim/agent-ready-repo #1479 (2026-10-01) The run's event line reported no retry cap while the guard enforced a default of 5 The budget snapshot resolves caps through the same helper the guards use, so reported and enforced budgets cannot diverge
daonhan/ralph (2026-09-30) (Preventive) a REVIEW_CHECKLIST.md rule that pending or skipped checks are never reported as passed; checks run in order and stop on failure Reporting rule for the implementer and reviewer stages

Three moves recur across the rows, and they are this KB's synthesis rather than any one source's claim. Validate configuration at the boundary (the threshold row). Test the guard with a case it must reject, in both directions where possible (the drills, the hint-execution test). Report the value that is enforced, from the code path that enforces it (the retry-cap row). The assertion has to run against the artifact the guard protects, not against a file that describes the guard; for the same lesson applied to this KB's own tracker, see the repo's CLAUDE.md.

Relationship to the Factory Model

The Loop Contract is the specification document for a factory model workflow. Just as a factory floor has defined inputs, processes, and quality gates, the contract defines what the loop accepts, does, and produces. See The Factory Model.