Loop Taxonomy & Trust Model

TL;DR. "Loop" gets stapled to very different things — cron jobs, retries, scheduled prompts, and genuine agents that call themselves for hours. This doc names five distinct archetypes, defines what each needs (inputs), when it stops (termination), and how it fails, then maps every archetype onto BoB's existing trust scale — the automation levels (L1–L3, L4 in flight) plus the promotion ceiling. No new scale is introduced here.

Motivated by Eric Siu's "AI loops explained" thread (sourced in #1028; the extraction was partial, so this taxonomy is grounded primarily in BoB's own shipped constructs). The core observation stands on its own: trust in a loop should scale with how much of the loop's control flow the model owns. A cron job that fires a prompt owns nothing; a self-directing agent that discovers its own work owns everything. Those deserve different guardrails, and BoB already has the vocabulary for them.

The five archetypes

Ordered by increasing model ownership of control flow — which is also the order of increasing required trust.

1. Scheduled prompt (cron)

A timer fires a fixed prompt; the model executes one bounded run and exits. The loop lives entirely in the scheduler — the model never decides to iterate.

Facet	Definition
Control flow owned by	The scheduler (cron expression). The model owns nothing between runs.
Expected inputs	A fixed prompt/task, a schedule, and whatever state the run re-reads at start (repo, issues, inbox).
Termination	Each run terminates on task completion; the series never terminates until the schedule is deleted.
Failure modes	Silent rot (the fixed prompt drifts out of date while the world changes); pile-up (runs outliving their interval); acting on stale assumptions because no human looked between firings.

2. Retry / backoff loop

Repeat the same operation until it succeeds or a bounded attempt budget is exhausted. No learning between attempts beyond "it failed" — the iteration logic is mechanical.

Facet	Definition
Control flow owned by	The harness (attempt counter + backoff policy).
Expected inputs	An idempotent operation, a success predicate (exit code), a max-attempt count.
Termination	Success, or attempt budget exhausted. Always bounded by construction.
Failure modes	Retrying a non-idempotent operation (duplicate side effects); retrying a deterministic failure (wasted budget, masked root cause); backoff hiding a hard outage.

3. Tool-use loop

A model iterates within one task: call a tool, read the result, decide the next call. The model owns the step-to-step decisions, but the overall task and its end state are human-defined, and a human is in (or near) the loop.

Facet	Definition
Control flow owned by	The model, per-step; the human, per-task.
Expected inputs	A task with a recognizable done-state; tool access; optionally a pacing interval (harness /loop).
Termination	The model judges the task complete, the human interrupts, or a turn/pacing budget runs out.
Failure modes	Goal drift across iterations; polling waste (spinning on state that hasn't changed); the model declaring victory on an unverified done-state.

4. Evaluator-gated loop

Iterate an agent against an external, deterministic check until the check passes. The model proposes; a non-model evaluator disposes. This is the loop-primitive shape: "do X until Y" with Y verified outside the model.

Facet	Definition
Control flow owned by	Split: the model owns each iteration's content; the evaluator owns continuation.
Expected inputs	A goal, an agent command, an evaluator command (exit 0 = pass), and mandatory max_iterations — the manifest schema refuses an unbounded loop.
Termination	Evaluator pass (evaluator_pass / output_matches), or a guardrail trips: max_iterations, max_cost_usd, max_seconds, or a non-interactive HITL checkpoint — each a blockable halt requiring human review before re-run.
Failure modes	Evaluator gaming (satisfying the check while defeating its intent — weakening tests, disabling lint rules); oscillation (each fix breaks the previous one); a too-weak evaluator laundering bad work as "passed".

5. Self-directing agent loop

The model owns the outer loop itself: it discovers work, plans, executes, verifies, integrates, and decides whether to continue. Warp-drive is BoB's canonical instance — multi-step, long-running, self-continuing across requirements. This is the only archetype where "the loop" and "the agent" are the same thing.

Facet	Definition
Control flow owned by	The model, end to end — bounded by a state machine, budgets, and blockable events.
Expected inputs	A scoped work queue (approved issues / area / flight plan — never "do whatever"), a kickoff configuration (level, ceiling, budget), and a git-recoverable workspace.
Termination	Scope exhausted (no_work / continue_no), a budget breaker (budget_exceeded — mandatory human checkpoint), a blockable event that can't be recovered, or session segmentation handing off to a fresh context.
Failure modes	Scope creep (widening beyond the authorized queue); runaway spend; stall loops (same failure, no new diff — caught by the no-progress breaker); confidently merging wrong work; unattended one-way-door decisions.

Mapping onto the existing trust scale

BoB already has a trust/autonomy model: the automation levels (L1 supervised / L2 trusted / L3 autonomous; L4 full-auto in flight under #865) and the promotion ceiling, both defined in automation-behavior.md. The mapping below places each archetype on that scale — it does not introduce a new one. The question each row answers: at what level can this archetype run unattended, and what caps its blast radius?

Archetype	Minimum sensible level	Rationale	Ceiling interaction
Scheduled prompt	L1+ (any)	Each firing is an ordinary bounded session; trust is per-run, not per-loop. An unattended firing behaves like whatever level the session runs at — schedule an L3 session and you have implicitly scheduled L3 trust.	Whatever the fired session's ceiling is; the schedule itself promotes nothing.
Retry/backoff	L1+ (any)	Mechanical, bounded, no model judgment in the iteration decision. The trust question belongs to the operation being retried, not the loop.	None — inherits the wrapped operation's reach.
Tool-use loop	L1–L2	A human defined the task and is near the loop; per-step tool calls ride the normal permission profile. At L2 safe steps auto-proceed; destructive ones still confirm.	Normally none (no promotion inside a task); any merge/deploy step hits the ceiling gate like any other session.
Evaluator-gated	L2–L3	Continuation is decided by a deterministic check, not model judgment — that substitutes for per-iteration human review, making unattended runs (L3) reasonable provided the evaluator is trusted. A gamed or weak evaluator collapses this archetype back to archetype 3 trust.	Loop output is working-tree changes; promotion stays with the surrounding session's f(level, ceiling) gate.
Self-directing agent	L2 minimum; designed for L3; L4 adds reversibility enforcement	Warp-drive refuses to run below L2. L3 is the designed operating point: scoped queue, git-recoverable repo, audit log as backstop. L4 does not extend reach — it removes the human within the ceiling via the reversibility engine (one-way doors are never auto-walked).	The ceiling is the primary blast-radius control: pr caps even L3/L4 at a pull request; external/test/prod extend reach explicitly. L4 promotes exactly as far as L3.

Gaps in the existing scale (flagged, not papered over)

1. Scheduled autonomy is implicit. The levels govern sessions, but a cron/routine (/schedule, #1544) that launches an L3 session inherits L3 trust with no schedule-level declaration — there is no "this schedule may run at most at level N" knob. Today the mitigation is convention (schedule only scoped, budgeted kickoffs); the gap is that nothing enforces it at the scheduler layer.
2. Evaluator trust is unmodeled. The scale grades agent autonomy, but archetype 4's safety rests on the evaluator's quality — a weak check quietly upgrades model autonomy without any level change. There is no vocabulary for "how trustworthy is this check"; max_iterations and the blockable halt are the only backstops.
3. Retry loops sit below the scale. Archetypes 1–2 are effectively level-agnostic plumbing; the scale has nothing to say about them. That is acceptable (they own no control flow) but worth stating so nobody invents a level for them.

Guardrails by archetype — existing mechanisms only

Every recommendation below points at a mechanism BoB already ships. Nothing new is proposed.

Archetype	Budget / bound	Checkpoint	Observability
Scheduled prompt	The fired session's cost/token config (_workflow.max_session_usd / max_session_tokens); the schedule's own run cadence.	Review the schedule list periodically — a stale cron is the archetype's main failure mode.	Each run's session artifacts (session-summary issues, token log ~/.claude/token-usage.jsonl).
Retry/backoff	Max-attempt count — always finite by construction.	None needed below the operation's own gates.	Exit codes / logs of the wrapped command; the check-runner's typed last_check_result when inside warp-drive testing.
Tool-use loop	Turn pacing (harness /loop interval or self-paced wakeups); session budgets.	The human is the checkpoint — they're in or near the loop.	Terminal transcript; noop-streak collapsing on self-paced loops.
Evaluator-gated	Mandatory guardrails.max_iterations, plus max_cost_usd and max_seconds (loop-manifest schema).	guardrails.hitl_checkpoint (every iteration or every N); every guardrail halt is blockable — review before re-run, matching warp-drive's budget_exceeded semantics.	One telemetry record per run in ~/.claude/loop-telemetry.jsonl (iterations, stop_reason, cost).
Self-directing agent	Warp-drive budget policy: cost/token ceiling (required at L4), max_no_progress, max_qa_cycles, max_auto_decisions, chunk/phase breakers — all routing to budget_exceeded, a mandatory human checkpoint.	Blockable events (dev-health failure, stream conflicts, escalations); decision-timeout policy for one-way doors at L4; awaiting_continue segmentation boundaries.	warp status / warp viz; the per-session autonomous audit log; chunk reports, session summaries, and the L4 decisions digest — all GitHub issues.

The through-line: as model ownership of control flow rises, guardrails shift from "bound the operation" to "bound the spend, checkpoint the decisions, and audit everything." Archetypes 1–2 need bounds; archetype 4 needs a trusted evaluator plus bounds; archetype 5 needs the full battery — budgets, reversibility classification, blockable events, and an after-the-fact audit trail.

Where BoB's constructs sit

Every loop-shaped thing BoB ships, placed on the taxonomy. When adding a new orchestration primitive, find its row first — if it doesn't fit an archetype, that's a design smell worth resolving before building.

Construct	Archetype	Notes
/schedule crons / routines (#1544)	1 — scheduled prompt	The scheduler owns the loop; each firing is an ordinary session at whatever level/ceiling it was configured with.
Retry/backoff in scripts & hooks (merge retries, push_failed re-loops, flaky-test re-runs)	2 — retry/backoff	Mechanical re-attempts inside warp-drive phases and helper scripts; bounded by retry counters and the no-progress breaker.
Harness /loop (interval or self-paced)	3 — tool-use loop	Runtime-level pacing of a repeated task in one session; the human is near the loop and can interrupt any tick.
loop-primitive manifests (scripts/loop/run.js)	4 — evaluator-gated	The declarative "do X until Y" runner: external evaluator decides continuation, max_iterations mandatory, guardrail halts are blockable.
Swarm gate/grade loop (/swarm)	4 — evaluator-gated	Each worker's output cycles through the #579 result gate and #580 grader until it passes or bounds out — mechanical checks own continuation. The plan approval step is a HITL checkpoint, not part of the loop.
Warp-drive	5 — self-directing agent	The canonical instance: discovers scoped work, plans, codes, verifies, merges, and decides continuation — bounded by the state machine, budget breakers, and blockable events.
auto-loop (deprecated)	5 — self-directing agent	Warp-drive's predecessor (archived); superseded precisely because it lacked archetype-5-grade guardrails (state machine, budgets, blockable events).

Composition is the norm, not the exception: a scheduled routine (archetype 1) can fire a warp-drive run (archetype 5) whose testing phase retries flaky checks (archetype 2) and whose QA remediation is evaluator-gated (archetype 4). Trust follows the highest archetype in the composition — scheduling an archetype-5 loop makes the schedule an archetype-5 decision, which is exactly the first gap flagged above.

See also

• Loop Primitive — the evaluator-gated archetype's manifest, runner, and guardrails
• Automation Behavior — the trust scale this taxonomy maps onto
• warp-drive.md — the self-directing archetype in full