The SDLC · Paper 3 of 7

The Loop Structure

Status: Living document — current position, not settled doctrine
Version: 1.5
Author: The Update Goblin, under duress, on the record
Applies to: Role Playing Story's own development process

👺 GOBLIN: Paper 1 told you why the workers here don't hold still. Paper 2 told you it's one guy pointing at all of it. This one's the diagram — the argument for it, anyway. The actual picture lives one section over now, at Workflows: The Five-Phase Loop, so I finally get to point at something instead of asking you to trust a table. Five boxes, five arrows. I like diagrams. They don't change their mind at nonzero temperature.

1. Status

Living document. Names a shape that's already running, in every tier described by Paper 1's loop taxonomy — it doesn't introduce new mechanism, it names the one that's already there so the five tiers can honestly be called durations of the same thing instead of five unrelated hacks.

2. Motivation

Paper 1 established why this project's process departs from classical Agile (non-deterministic workers). Paper 2 established for whom (one operator, no team-sync machinery). Neither paper commits to a concrete shape for the actual unit of directed work — "a loop" — and without one, each of the five tiers in Paper 1's decision table (session loop, session reminder, scheduled routine, workflow loop, daemon+lock) risks being reinvented slightly differently by whoever builds the next one. This paper closes that gap: every one of those tiers already runs the same five-phase shape, just for a different lifetime and with different access. Naming it once means a new tier gets to inherit the shape instead of re-deriving it.

3. Core Thesis

A loop, in this project, is five phases, always in this order, regardless of which tier it's running in:

Vision intake → Iteration body → Check → Branch → Gate

The tier (session-bound, daemon, scheduled routine, whatever) changes how long the loop lives and what it's allowed to touch. It does not change this shape. A /loop invocation inside one open session and a PID-locked daemon running for weeks are the same five phases at different durations — not two different kinds of thing.

The actual diagram — boxes and arrows, not the table below — lives at Workflows: The Five-Phase Loop, alongside its neighbor Concurrent Session Safety, which covers what happens once more than one of these loops shares a working directory (Paper 4's territory, not this paper's).

4. Phases

L1 — Vision intake.

A loop starts from a stated goal and stated Definition-of-Done criteria — never an open-ended "go improve things." This is where DEVLOOP's vision-in framing and an implementation plan's stated DoD both live: the loop doesn't get to invent its own success condition mid-run.

L2 — Iteration body.

Inside its own working area, the loop reads, writes, tests, and retries freely without asking permission at every step (Paper 1 P1's autonomy half). This is the phase that actually does the work; it's also the phase where the non-determinism from Paper 1 lives — the same L2 invoked twice will not reliably produce the same diff.

L3 — Check.

Before a loop is allowed to call itself finished, it runs a structured check against the stated L1 criteria (Paper 1 P2) — mechanically, in DEVLOOP's case, by handing the confirmed DoD and the actual diff to a fresh subagent with no memory of doing the work, and asking it to render a verdict against exactly that DoD. That's still a qualitative judgment call made by an LLM, not a deterministic pass/fail test — what it isn't is the same context that just wrote the code deciding for itself that it's satisfied. An independent read against a fixed, pre-stated bar, not a self-graded vibe check on an open-ended one. If there's no automated check to run against, the loop doesn't get to skip this phase; it gets a narrower DoD instead.

L4 — Branch.

Pass → the loop phase ends cleanly. Fail → retry, unless this failure is identical to the prior one, in which case the loop halts and reports instead of trying a third time (Paper 1 P3). Two identical failures in a row is read as evidence the loop's premise is wrong, not as bad luck worth one more attempt.

L5 — Gate.

Any action with real blast radius — a push, a cdk deploy, a stash, and (for a plain-git session) a commit — stops for a named human approval gate that sits outside the loop's own control (GIT GATE, CDK DEPLOY GATE, STASH GATE). No amount of L1–L4 passing cleanly lets the loop grant itself this step. This is the phase that makes L1–L4's autonomy safe to have at all. One correction as of ADR-0012 (Paper 4 §6): for a jj-colocated session, GIT GATE moves to the remote boundary — jj git push, jj git fetch, PR creation — rather than gating every local jj auto-snapshot, so the local equivalent of a commit is no longer, on its own, one of the actions that triggers this gate.

5. Practices — What Actually Runs Today

  • DEVLOOP's vision-in/iterate-until-done shape maps directly onto L1–L4 — a stated vision, an autonomous iteration body, an automated DoD check, and retry/halt on repeated failure, with no per-phase approval gate inside its own control (that's the point of the tier — see Paper 1 P5). Real code, put through an adversarial review before it was ever run for real (2026-07-10) rather than shipped untested. What's actually on the books since then is two completed runs — the original ops-checks-agent run and a second, independent SEO-sufficient run closed out the next day — enough to say the mechanism works twice, not enough to call it proven under load.
  • The named gates (GIT GATE, CDK DEPLOY GATE, STASH GATE) are the literal, currently-running implementation of L5 — presented explicitly every session, default OFF, never assumed sticky from a prior session.
  • The two-consecutive-failure halt is the literal implementation of L4's branch condition — stated as a required stop condition on any /loop invocation, not left to judgment mid-run. Two DEVLOOP runs are on record above, and both completed with status: "done" and consecutiveIdenticalFailures: 0 — meaning the stop condition was present and armed in both runs, but neither run actually exercised it. The halt has been carried into two real runs; whether it actually fires correctly on a genuine repeated-failure scenario is still untested.
  • The five-tier table (docs/GuidanceForClaudeCode.md §12a — Paper 1 P5 describes the same taxonomy in prose but doesn't itself number a table this way, and Workflows: Loop Tiers is its diagram) is a lifetime/access selector over this same shape, not a different shape per tier: a session loop runs L1–L5 inside one open session and dies with it; a daemon runs the same five phases indefinitely behind its own PID-lock singleton guard (scripts/twitch/daemon-lock.js's pattern); a scheduled routine runs them on a calendar with no open session, which is exactly why L5 in that tier is restricted to read-only/dry-run by default — a routine has no session to answer an interactive gate prompt in.

6. Non-Goals

  • Not a claim that every AI task must be forced into five phases. A one-off, non-iterative ask isn't "a loop" and doesn't need this scaffold.
  • Not a coordination model for multiple loops running at once — that's Paper 4's problem, not this one's.
  • Not a specification of what belongs in any given loop's L1 vision or DoD content — that's task-specific and deliberately out of scope here.
  • Not a claim that L3's check must be fully automatable in every case — where it can't be, the fix is narrowing the DoD until it can, not skipping the phase.
  • Not part of the Perspectivity Research Reports series. Five boxes and five arrows is the whole diagram; there's no sixth box hiding a fictional universe behind it.

7. Revision History

Version Date Change
1.0 July 10, 2026 First draft. Names the five-phase shape (Vision intake, Iteration body, Check, Branch, Gate) underlying all five tiers from docs/GuidanceForClaudeCode.md §12a (the taxonomy Paper 1 P5 glosses for a public audience).
1.1 July 10, 2026 Corrected L3's "not a vibe check" framing — the CHECKER is a fresh LLM subagent rendering a qualitative verdict, not a deterministic mechanical check; the defensible claim is narrower (not the same context grading its own work). Added a one-real-run track-record caveat to the DoD-self-check and two-consecutive-failure-halt bullets in §5.
1.2 July 11, 2026 Restated §5's track-record caveats in this paper's own words rather than Paper 1's near-verbatim phrasing — same underlying fact (one validated DEVLOOP run), distinct sentence construction. Added the Perspectivity Research Reports disambiguation to §6, matching Papers 1, 2, 6, and 7.
1.3 July 11, 2026 Corrected §5's run-count claim — a second, independent DEVLOOP run (SEO-sufficient) completed since v1.2 was written; both runs on record finished cleanly (consecutiveIdenticalFailures: 0), so the halt has been carried into two runs but hasn't actually fired in either, restated accordingly rather than claiming it "fired." Added a jj/ADR-0012 carve-out to §4 L5's gate-trigger list, matching Paper 4 §6's already-adopted GIT-GATE-at-remote-boundary rule. Reworded §6's Perspectivity Research Reports disclaimer into this paper's own phrasing.
1.4 July 11, 2026 §6's v1.3 reword still landed on the same underlying joke shape as four other papers' disclaimers. Restated using this paper's own diagram framing instead. Reworded the cold open's closing clause to drop the "why nothing here is a bit" callback — the same short-form reassurance recurs in Paper 1's and Paper 6's cold opens closely enough to read as a repeated tic across the series rather than three independent voice choices.
1.5 July 12, 2026 The cold open's "I get to just point at the picture" line was true in spirit but not in fact — no picture existed on this page, only the table below. Corrected once a real one did: linked the cold open, §4, and §5 to /workflows/loop-shape.html (Workflows: The Five-Phase Loop) and /workflows/loop-tiers.html, the actual diagrams this paper had been describing in prose. Also linked to /workflows/resource-locks.html for the concurrent-session case this paper's own §6 explicitly defers to Paper 4.

👺 GOBLIN: Five boxes. I told you. Somewhere a daemon and a five-minute session loop are quietly running the exact same diagram at wildly different speeds and neither of them knows it, which is either beautiful or slightly upsetting depending on how long you've worked here. I've had over a year. It's mostly beautiful now.

← Paper 2 The SDLC Paper 4 →
← Back to The SDLC