# 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. **Authorship and editing** These papers began as a collaboration between me and Claude. I now review and revise them with Astra, an OpenAI model, as my editor. I make the final calls on what they say and what gets published. `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. **Source** Internal control-plane audit, September 4, 2026, and frozen dispatch baseline, September 6, 2026. The baseline covers August 5 through September 5 at 14:18:40 Eastern time; section 8 gives the cohort counts and measurement limits. ## 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](#example-review-result) 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. ### Example: A review result Illustrative response using the existing review-result format. All three scalar fields below are required: the reviewer must be correctness or security, the verdict must be PASS or FAIL, and the finding count must be an integer. Missing required fields or invalid values cause rejection. The merge gate separately requires results from both reviewer roles. The current validator does not check individual findings or reconcile the list's length with the reported count. ```yaml ---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. **Implementation note** Implementation and fix contract checks currently report telemetry without blocking the workflow. The merge command requires valid review evidence from both correctness and security roles. That gate is narrower than the target of enforcing every worker contract, and this audit does not establish that agents are unable to invoke every lifecycle operation through another path. ## 4. Repository profiles, not prompt branches [Repository profiles](#example-repository-profile) 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. ### Example: A repository profile Selected fields from the backend profile inspected on September 14, 2026; paths and unrelated settings are omitted. This excerpt pins the Ruby version, supplies the test command as separate arguments, restricts selected files to matching test paths, and sets a 60-second targeted-test timeout. The file placeholder is filled with validated test paths. This is an explanatory excerpt, not a complete runnable profile. ```yaml 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 ``` **Implementation note** The skill retains a prose fallback when validation, commit, or pull-request commands return exit code 2. That code covers several bad-input conditions as well as missing profiles. The workflow therefore does not yet reject every unknown profile or invalid invocation before model-directed execution can continue. This is a remaining enforcement gap, not evidence that a fallback ran in any particular dispatch. 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 --resume ` 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. | Phase | Recorded state | Remaining qualification | |---|---|---| | A: Observability and contracts | Landed September 5 | Billed usage is measured per dispatch. Stream counts distinguish supervisor and workers, but there is no billed token allocation per phase. Implementation/fix contract checks remain telemetry-only. | | B: Implementation commands | Landed September 6 | Setup, validation, commit, pull-request, merge, and teardown commands exist. Prose fallbacks remain; lock-release tokens are still passed through the skill. | | C: Bounded session resume | Landed September 7 | State reconciliation and a bounded continuation path exist. This audit establishes no production recovery success rate. | | D: Scenario selection | Planned September 8 | Selecting checks from the ticket's affected behavior remains planned in the inspected record; current queue status was not rechecked. | | E: Failure signatures | Landed September 9 | Code recognizes known failures before asking a model about unmatched cases. Model classification cannot itself authorize a retry. | | F: Direct command wrappers | Landed September 11 | The recorded rollout required operator interventions. Merged commands do not establish unattended completion. | **Source** Internal migration records through September 11, 2026, with selected source checks on September 14. Phase F's close-out report records operator intervention on four of eight tickets: three stopped before post-fix re-review, while another hit a budget limit after a second fix cycle and then encountered a worktree refusal. These are historical rollout observations, not current unresolved-ticket counts. 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. | Before cohort | Dispatches / terminal results | Median cache-read tokens | p90 cache-read tokens | Median Bash calls | |---|---|---|---|---| | Backend | 74 / 70 | 20.7 million | 38.1 million | 151 | | Frontend | 43 / 43 | 17.4 million | 36.1 million | 140 | **Source** Frozen per-dispatch baseline rows recorded September 6, 2026; the displayed values were recalculated from those rows on September 14. Token statistics use available terminal billing results; call counts use the available stream records, including runs without a terminal result. The summarizer selects an observed middle-ranked value for its median and uses its existing percentile convention for p90. 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.