The Deterministic Spine

By Yianna Kokalas & Claude

Position: models should own judgment; executable code should own control. In the agent system described here, every repeatable lifecycle operation should move into a tested state machine that stops when the evidence needed to proceed is missing. Models remain workers at the places where the answer must be synthesized: planning, implementation, diagnosis, review, and repair.

The setting is software built for the Magic: The Gathering community, with real users. The drain is the program that takes approved tickets through implementation, review, and deployment checks. Its /implement workflow runs a supervisor session that calls separate implementation and review agents. The question in this paper is which parts of that workflow still need a model to decide what happens next.

This paper presents an architectural decision and a partly completed migration. It does not yet establish a reduction in tokens, cost, or incidents. The comparison plan and evidence limits are described in section 8.

bin/drain remains the durable outer state machine. The target is for deterministic scripts under /implement to decide when a worker may run, what evidence it receives, what contract it must return, and which verified state transition may follow. The worker decides the part code cannot: what should be built, what is wrong, and how to fix it.

The September 4, 2026 audit found that 49 of 52 skill entry points required model interpretation. A skill is a reusable set of instructions for an agent. This counts entry points, not the proportion of work that needs judgment. The drain already enforced important decisions in code, including queue admission, timeouts, and deployment checks. Inside /implement, however, the model still interpreted instructions for setting up worktrees, running checks, and handling commits and pull requests.

The frozen baseline recorded on September 6 contains 165 dispatches, of which 151 have a terminal result. Backend dispatches had a median of 151 Bash calls and 20.7 million billed cache-read tokens (previously cached input reused by the model); frontend dispatches had 140 calls and 17.4 million cache-read tokens. A rough command classifier labeled just over half the Bash calls mechanical. Some of those commands read code, so the classification is not a count of work we can safely remove.

A script can combine several repeatable operations into one invocation and return a compact result. That may reduce model requests and the context carried into later requests. We cannot infer an exact saving per Bash call: calls can share a message, and streaming records are not identical to billable requests. The efficiency case needs an outcome measurement alongside the reliability case.

1. The boundary

The target boundary is a rule:

If the same validated observed state should always produce the same next action, that action belongs in the deterministic runner. If the action requires interpretation, synthesis, or adversarial judgment, it belongs to a model behind a typed contract.

A typed contract specifies the fields and values a result must contain before code can use it. The contract checks the response’s structure; it cannot establish that the reviewer found every defect.

---REVIEW RESULT---
reviewer: correctness
verdict: PASS
finding_count: 0
findings: []
---END---

Examples that belong in code:

• Resolve a ticket and repository.
• Claim a ticket, acquire a lock, and create or recover a worktree.
• Select an approved test profile and invoke its argv without a shell re-interpretation.
• Parse exit codes, test reports, GitHub state, and deploy probes.
• Enforce file scope, budgets, fix-cycle limits, and tree identity.
• Create a commit and PR, compute merge eligibility, merge, tear down, and transition ticket state.

Examples that belong to a model:

• Decide the implementation shape inside an approved ticket boundary.
• Write or change product code.
• Judge whether code satisfies the acceptance criteria.
• Find security and correctness defects not reducible to a fixed predicate.
• Diagnose an unknown failure and propose a repair.

The distinction is semantic, not tool-based. A model invoking git, gh, and test commands is still model-mediated control. A runner invoking a model to produce code is still deterministic control around nondeterministic work.

2. The starting point and target shape

At the September 4 audit, the drain owned the durable lifecycle, but /implement still contained both the semantic work and much of the mechanical workflow:

ticket -> drain: claim / timeout / recovery / terminal state
             |
             +-> one /implement supervisor session
                    -> reads 1,426 lines of pipeline prose
                    -> creates worktree / carries lock tokens
                    -> invokes implementation agent
                    -> chooses and parses tests
                    -> keeps pre-merge review/fix loop in-session
                    -> commits / creates PR / computes merge branch
             |
             +-> drain: deploy and smoke verification / post-deploy recovery

The target makes the deterministic spine continuous without creating a second outer runner or forcing the healthy fix loop out of its supervisor session:

                              BIN/DRAIN
                     durable claim / recovery / truth
                                  |
                                  v
                      ONE /IMPLEMENT SUPERVISOR SESSION
                                  |
              +-------------------+-------------------+
              |                                       |
     deterministic scripts                    semantic agents
     setup / validate / git / PR          IMPLEMENT -> REVIEW -> FIX
     manifests / checkpoints                   ^             |
              |                                +-------------+
              +-------------------+-------------------+
                                  |
                                  v
                              BIN/DRAIN
                       deploy / smoke / terminal state

 resume is a recovery edge back into the same supervisor session,
 after drain reconciles durable state; it is not the normal loop

The existing phase prose is not discarded. It is a requirements corpus: each scar, invariant, fail-closed rule, and recovery condition becomes a runner branch plus a regression test. The migration succeeds only if the code preserves those earned rules.

Here, a manifest means a saved record of the run’s identity, worktree, and completed phases. Idempotent commands check that record and the observed state before acting, so repeating a completed command should recover its result without repeating its effect. Section 6 separates the implemented pieces from the remaining target.

3. The first move: compile /implement mechanics into scripts

The first draft of this paper proposed a deterministic “implementation runner.” That name hid an unnecessary duplication: the drain already is the durable outer runner. The highest-return change is narrower. Compile the mechanical phases into deterministic, idempotent commands that /implement invokes while its existing supervisor session owns the semantic implementation/review/fix loop. Reuse the manifest and contract ideas from bin/lib/pipeline_runner.rb, not its position as another top-level orchestrator.

Intended script responsibilities

1. Resolve and claim
   • Resolve slug, ticket-store row, repository, dependency state, and auto-merge policy.
   • Acquire the ticket claim and implementation lock atomically where possible.
   • Emit a run ID used by every later artifact and transition; the drain remains the authority that created the claim.
2. Prepare
   • Verify clean main, fetch/fast-forward, create or recover the worktree, and record branch/worktree identity.
   • Replace prose-carried lock owner, nonce, paths, and digests with manifest fields.
3. Invoke implementation
   • Give the implementation node the ticket, repository path, worktree, allowed paths, budget, and output-schema location.
   • Permit code judgment; make lifecycle mutations such as merge and ticket transition depend on executable gates. Complete enforcement across every invocation path remains a target, not a property established by this audit.
4. Validate
   • Select an argv-array test profile from a checked-in repository manifest. The /implement supervisor calls this deterministic command and consumes its artifact.
   • Run formatter, tests, lint, build, budget, scope, and tree-integrity checks with explicit timeouts and captured results.
   • Produce one canonical validation artifact. A missing result is failure, never PASS.
5. Review and repair
   • The /implement supervisor invokes correctness and security review independently.
   • Validate each result against a schema and preserve finding IDs across repair and re-review.
   • Keep the bounded pre-merge back-edge inside that live supervisor session. Scripts persist the current cycle and artifacts; they do not replace the semantic loop.
6. Land and verify
   • Verify the committed tree equals the validated tree.
   • Push, create or recover exactly one PR, probe GitHub independently, and calculate merge eligibility from validated artifacts and store policy.
   • Merge and clean up through idempotent commands. The drain continues to own deploy, smoke-test, recovery routing, and terminal state transitions.

Why the pre-merge fix loop stays in-session

The current /implement dispatch already has the right continuity during a healthy run: one top-level print-mode supervisor invokes the implementation worker, two reviewers, and each fix worker synchronously. Findings and the evolving verdict remain in the supervisor’s context. Fresh worker and reviewer contexts are a feature: fix workers get the complete finding set explicitly, and re-reviewers do not inherit the implementer’s framing.

Keeping this loop in the existing supervisor session preserves its findings and evolving verdict without requiring another context handoff. Deterministic scripts can be called from inside the skill. This is the chosen design; the audit did not compare its cost or reliability with a separate loop controller.

Semantic-node contract

The target is for each implementation, review, and fix worker to return a versioned structured result that code validates before relying on it. A schema checks required fields and allowed values. It cannot establish that a reviewer found every defect. The intended contracts cover:

• Implementation: status, changed paths, claimed acceptance-criteria IDs, summary, and blockers. Test truth does not come from this artifact; a deterministic command measures it.
• Review: reviewer role, verdict, finding IDs, severity, path/line evidence, acceptance-criteria linkage, and whether the finding is blocking.
• Fix: finding IDs attempted, disposition per finding, changed paths, and blockers. Test truth again comes from a deterministic command.

Free-form prose may accompany a structured result. In the inspected implementation, workers return fenced result blocks that are parsed and validated against JSON schemas; they do not all write JSON files directly.

4. Repository profiles, not prompt branches

Repository profiles describe how to validate each supported codebase, including the backend, frontend, extensions, and internal tooling. The checked-in profiles supply:

• Repository resolution rules
• Safe formatter argv
• Targeted and full-suite argv
• Lint/build argv
• Required environment and toolchain pins
• Default timeouts

Deployment verification remains the drain’s responsibility; these profiles describe the validation commands run within an implementation worktree.

Profile commands are argument arrays. The validation command checks any selected test paths before running the approved command. This moves command construction and result parsing into code, although the supervising model still invokes it.

schema_version: repo_profiles/v1
profiles:
  BE:
    env:
      ASDF_RUBY_VERSION: "3.4.7"
    test_targeted:
      - env
      - RAILS_ENV=test
      - bin/rails
      - test
      - "{files}"
    targeted_end_of_options: true
    targeted_path_patterns:
      - "test/**/*_test.rb"
    timeouts:
      test_targeted: 60

The historical audit also recorded repeated environment and toolchain probes. Profiles make those settings explicit and reusable, but the existence of a profile does not show that every redundant probe disappeared. The after cohort must measure that.

5. Session continuity and recovery

At the September 4 audit, the drain did not retain a resumable session identity:

• implement_cmd and every post-deploy fixer attempt passed --no-session-persistence.
• Stream JSON included session_id, but the drain kept it only in the forensic log; it was not part of the parsed outcome, ticket store, telemetry, or a run manifest.
• The post-deploy self-heal loop persisted its attempt number, branch, and worktree, but each attempt started a fresh Claude session.

The adopted design gives the drain responsibility for session continuity:

1. Generate a UUID in the drain before spawning /implement and pass it through --session-id; do not pass --no-session-persistence on resumable lanes.
2. Persist {run_id, slug, dispatch_token, session_id, phase, attempt, forensic_log} before the child starts. Do not hide session identity only in a best-effort log.
3. On API interruption, missing terminal result, or drain restart, reconcile store, worktree, commit, PR, and deploy facts before deciding whether continuation is safe.
4. Resume with claude -p <recovery prompt> --resume <session_id> under a separate, bounded continuation budget. A hard timeout is not automatically resumable: a looped session may simply repeat its loop.
5. Make every deterministic phase command idempotent against its manifest checkpoint so a resumed model cannot create a second worktree, commit, PR, merge, or state change.
6. For post-deploy self-heal, allocate one fixer-session UUID for the whole <=3-attempt sequence and resume it between attempts. The reviewer subagents inside an attempt may remain fresh.

Session persistence preserves reasoning context. Durable manifests and idempotent scripts preserve correctness. Neither substitutes for the other.

The September 14 source check confirms that normal dispatches now receive a saved session identifier and omit --no-session-persistence. The continuation path checks the recorded state against the repository and ticket state, validates the identifier, and records that its single continuation allowance has been consumed before spawning. Hard timeouts remain ineligible for this continuation path. Source and fixture checks establish these mechanisms; production recovery effectiveness remains unmeasured here.

6. Migration sequence

One phase concerns which browser tests to run for a change. A scenario is a repeatable user workflow described as actions and expected results. We write its steps in YAML, and our compiler turns them into Playwright tests. Playwright automates the browser and can run headlessly, without a visible browser window. Scenario selection means choosing the workflows that exercise the behavior a ticket changes.

Recorded migration status

The internal status record through September 11 reports five phases landed and one planned. “Landed” means that the phase’s implementation work was recorded as merged; it does not establish that all target invariants hold or that its benefits were measured. The September 14 audit checked selected mechanisms in the current source. It did not verify deployment of every phase or query the live ticket queue.

The phase descriptions below preserve the adopted plan. The table above records implementation progress and departures from it. Outcome measurement remains open.

One rollout lesson is already concrete. A budget-stopped run left a clean worktree and an open pull request. Redispatch then tried to choose a different branch and refused the surviving worktree. The operator finished the work, and an improvement was proposed to recognize and adopt a matching existing worktree. This is why recovery needs to check the effects of a previous attempt before starting another: a clean restart can still disagree with valid work already on disk. The incident supports that design requirement; it does not measure the reliability of the migration.

Phase A: Observability and contracts

• Add one run manifest spanning drain dispatch through deploy verification.
• Persist the drain-created Claude session ID and expose it in forensic metadata.
• Measure phase duration, model turns, tool calls, retries, and terminal reason.
• Measure billed tokens per dispatch and distinguish supervisor and worker activity. Per-phase token attribution remains a desired extension; stream usage is not a substitute for reconciled billing totals.
• Define and validate implementation/review/fix artifact schemas while the existing prompt pipeline still runs.
• Reject malformed contracts for consequential transitions, initially in shadow/report mode and then as a hard gate.

Phase B: Deterministic /implement primitives

• Implement idempotent phase commands and repository profiles under the existing drain.
• Port phase 0 setup, phase 3 validation, phase 4 commit, phase 5 PR handling, phase 6 teardown, and merge eligibility. Keep the healthy pre-merge fix loop in the supervisor session, with its cycle/artifact checkpoint persisted by the commands.
• Turn each incident comment in the current skill into a regression fixture before removing the corresponding prose branch.
• The plan called for rollout by repository profile, beginning with the backend and frontend. The implementation record says all profiles shipped together, so the planned staged rollout should not be presented as the rollout that occurred.

Phase C: Bounded session resume

• Enable persisted, drain-assigned UUIDs for /implement.
• Add reconcile-before-resume and one bounded continuation lane for recoverable interruptions.
• Reuse one persisted parent fixer session across post-deploy attempts.
• Measure resume success and duplicate-effect prevention before enabling timeout resume.

Phase D: Deterministic scenario dependency selection

• Require user-facing tickets to declare scenario names at promotion, or resolve them through a checked-in path/capability-to-scenario map.
• Validate that every referenced scenario exists.
• Use a semantic scenario-exploration node only when the manifest proves coverage is absent, not as the ordinary selection mechanism.

Phase E: Signature-first failure classification

• Extract timeout, budget, upstream API, test-no-result, toolchain, collision, and state divergence from structured envelopes and known signatures.
• Keep the RECOVERY table authoritative.
• Ask the local classifier only about unknown free-text tails. Its output may suggest an escalation label, but cannot independently authorize retry or mutation.

Phase F: Thin command surfaces

• Move /promote, /land, /post-merge, and /scenario-run to direct command wrappers wherever inputs and outputs are structured. The pattern extends the existing command wrappers used for document and ticket checks.
• Retain a model layer only for the genuinely semantic fallback: ambiguous ticket resolution, missing scenario design, or synthesis of a new follow-up.

7. Rollout and reversibility

The adopted rollout plan asked each command to earn authority in stages:

1. Fixture mode: replay captured manifests and failure artifacts with no external mutation.
2. Shadow mode: deterministic commands compute planned actions beside the live prompt phases, but do not perform them. Compare next-state decisions and surface divergence.
3. Profile canary: the commands own one repository profile and a bounded ticket class.
4. Default with escape hatch: expand only after the canary window; retain a deliberate operator-only legacy path during the initial rollout.
5. Retire prose execution: after parity, keep the old prose as history or concise model-role guidance, not as a second live state machine.

Shadow mode must never double-execute mutations. It compares plans and observations; the drain remains the durable outer authority and there is still exactly one writer.

This sequence is a design prescription. The records inspected here do not establish that every command passed through every stage, and the all-profile rollout in phase B departed from it. A migration account must retain that difference.

8. Success measures

The engineering targets are:

• 100% of consequential git and PR effects are emitted by idempotent commands, and 100% of deploy and terminal ticket transitions remain drain-owned.
• 100% of semantic nodes produce schema-valid artifacts; missing means fail-closed.
• The scripts can replay every known worktree, lock, wrong-PR, backgrounded-suite, tree-integrity, timeout, and state-divergence incident as a deterministic fixture.
• Median model-issued Bash calls fall by at least 50% within each repository cohort.
• Median billed cache-read tokens fall by at least 30% within each repository cohort, while the review and deployment checks retain their quality. This is a cache-read target; total token use and monetary cost must also be reported separately.
• Wrong-worktree, wrong-PR, stale-lock deletion, and “claimed green without a result” incidents remain at zero across 100 consecutive script-backed dispatches.
• Reviewer catch rate and post-deploy verification quality do not regress.
• A recoverable session interruption resumes the same drain-recorded session without a duplicate worktree, commit, PR, merge, or ticket transition.
• Cost and elapsed time fall, but never by weakening semantic review or fail-closed gates.

The targets are not achieved results. The frozen September 6 baseline supplies the following comparison values. A dispatch is one invocation of the implementation workflow. A terminal result can report an error; it does not mean the ticket succeeded.

The comparison protocol selects September 6 at 19:53:03 Eastern time as its after cutoff, the first dispatch recorded as entering all four compiled phase groups. It compares backend with backend and frontend with frontend. Internal tooling dispatches are reported separately. The written protocol says “15 dispatches per repo cohort, or 30 across BE and FE combined”; the current comparison command requires 15 on each side of each repository comparison. A combined count must not be used to justify a percentage for an undersized repository cohort. The wording needs to be settled before interpreting the outcome.

The baseline note calls this protocol preregistered, but its first preserved commit is timestamped September 6 at 21:46:24 Eastern time, after the selected cutoff. That does not prove when the protocol was first written or which results had been seen. This audit cannot verify the stronger claim that it was recorded before any after data existed; that claim needs earlier evidence or narrower wording.

The local logs inspected on September 14 contain 46 dispatches after the cutoff: 45 internal tooling dispatches, one backend dispatch, and no frontend dispatches. The latest local log is dated September 11. This does not establish the complete current sample on the machine running the drain. It does establish that this audit cannot publish the intended backend/frontend efficiency comparison.

Several limits remain before that comparison can support the argument:

• The call classifier uses command prefixes. Code-reading commands can be counted as mechanical, and stream message records can overcount actual billable requests. The rough 30–45% planning estimate is not a physical ceiling; a larger reduction would require investigation, not an automatic conclusion that useful work was cut.
• The original records describe a timeout increase from 3,600 to 4,400 seconds and a $20 dispatch budget. Report runtime settings and model assignments by date and role: a stable supervisor alias does not establish unchanged worker and reviewer models.
• Ticket size was not controlled. The protocol calls for modified-file counts, but the current cohort output does not include them. Those counts need a separate evidence source before interpreting the comparison.
• Fix cycles count repairs. They do not measure the fraction of defects reviewers caught, and a change in that count has several possible causes. The review-quality condition needs its own evaluation method; a stable repair count cannot satisfy it.
• The source decision says a reduction below 20%, with review quality held flat, would falsify the token-efficiency case. A result between 20% and 30% would miss the success target without meeting that specific revisit condition.

A result that misses the target deserves the same prominence as one that clears it. Reducing prompt length may also help, but this audit does not quantify its independent effect. Removing or shortening instructions must preserve the checks those instructions were intended to enforce.

9. What this deliberately does not automate away

The goal is not to turn product work into a compiler problem. The following remain judgment problems:

• Roadmap priority and product tradeoffs
• Ticket and acceptance-criteria substance
• Implementation design and code generation
• Root-cause synthesis for unknown failures
• Correctness and security review
• Copy, support responses, and scenario authoring

We improve those nodes through better evidence, isolation, role choice, and evaluation. We do not pretend their output can be made deterministic by wrapping it in JSON.

10. The architectural claim

The earlier papers describe how the drain checks claimed outcomes against observed state and how a transactional ticket store can own state while prose remains the human interface. This paper extends those design choices into the implementation workflow:

Files remain the specification. Agents remain the source of judgment. The drain remains the durable owner of motion, and deterministic scripts become the only way its live implementation session performs repeatable effects.

This is the architecture we are working toward. Tested commands give repeatable operations an explicit place to enforce their rules, while agents continue to design, implement, and review code. The remaining fallbacks and unenforced worker contracts show where that boundary is incomplete. The open outcome measurement will determine whether it also delivers the efficiency and reliability improvements we expect.