SafeBuilder

Durable Orchestration · Integrity at Every Boundary · Verified Artifacts

SafeBuilder is a durable, model-agnostic orchestration spine that mechanizes the AI-first build methodology — scheduling executors, enforcing integrity at every stage boundary, and moving verified artifacts between stages — without ever reasoning about the codebase itself.

It is to the AI-first methodology what a CI/CD engine is to compilation: it never does the work, it orchestrates the things that do, and it enforces contracts at the boundaries. The executors that write code are treated as commodity, swappable runners. The integrity guarantees that wrap them are the defensible core. SafeBuilder owns the loop; it rents the muscle.

SafeBuilder — Architecture Overview

What It Is

An orchestration and verification spine for the AI-first build methodology. It never reasons about the code. It schedules executors, enforces contracts, and moves verified artifacts between stages. Executors (agentic CLIs) do the work; gates verify it.

The system is deliberately small and stays that way: work is always delegated outward to standalone, swappable external processes, and the spine is the only component coupled to the workflow engine.

The Problem It Solves

The AI-first engineering methodology works today as a human-orchestrated process: a reasoning LLM drafts task prompts, an agentic executor CLI runs each prompt against a real codebase, and the cycle repeats 40+ times per build with periodic audits and recalibration. It produces verified, fully-tested, 100%-AI-generated code at rates far beyond traditional development — but it has two structural weaknesses, both rooted in long-horizon state loss:

Drift (the Xerox effect). Across a multi-prompt cycle, an executor progressively substitutes its own paraphrase of the source-of-truth documents for the documents themselves. Each successive prompt operates on a lossier copy of the prior understanding. Prompt 30 is materially worse than prompt 3.
Decay. The executor stops re-reading source documents because they are nominally "already in context" from many prompts earlier — except the runtime has since compressed or evicted them, and the executor now confabulates from a half-remembered summary rather than re-reading from disk.

The shared root cause is that the executor is permitted to treat its own memory as a substitute for the source of truth. The governing principle — never from memory, conversation context, or inference; always from verified source of truth — is currently enforced only by instruction-following, which degrades precisely when it is needed most. A second weakness is orchestration fragility: the cycle, audit cadence, and corrective re-invocations live in the operator's working memory with no durable record and no mechanical enforcement.

SafeBuilder removes both by making integrity a mechanical gate, not a hope, and by moving long-horizon state into a durable spine.

Vision

The frontier labs are commoditizing the executor — the agent that turns a well-specified task into code. SafeBuilder deliberately does not compete there. Its value is the orchestration-and-verification layer that guarantees specification fidelity before execution and verification quality after it. The executors are commodity, swappable runners; the integrity guarantees that wrap them are the defensible core.

Key Principles

The spine never reasons about the code. It schedules, enforces contracts, and moves artifacts. All reasoning about the codebase happens inside executors and gates, never in the orchestrator.
Source of truth is referenced, never remembered — and provenance is observed, never self-reported. No stage passes another a paraphrase. Stages communicate exclusively through verifiable artifacts with line-anchored provenance, and that provenance is captured by the harness at the tool boundary — a recording of what the executor actually read, not a manifest the executor produces about itself. The system trusts telemetry, not testimony.
Sessions are ephemeral by design. Each prompt cycle is born, hydrates from durable on-disk artifacts, runs one task, emits its report, and dies. No transient understanding accumulates or degrades across cycles.
Integrity is a gate, not a hope. Methodology rules are enforced mechanically at stage boundaries, not requested in prose preambles.
Not monolithic. Executors and gates are standalone, swappable, external CLIs. The system stays small forever because work is always delegated outward.
v1 integrity is provable. The v1 integrity layer is fully deterministic. No probabilistic model judgment sits in the critical path until the deterministic baseline is established and trusted.

How It Works — Architectural Overview

SafeBuilder is a five-concern system. The concerns are kept genuinely separate; that separation is the anti-monolith discipline.

Concern	Responsibility	v1 Realization
Spine	Durable orchestration: roadmap position, advancement, scheduling, correction. Never reasons about code.	Temporal parent + child workflows (Java SDK)
Executor plugins	Adapt a generic "run this prompt against this repo, capture reads, return a report" into a specific agentic CLI.	Trusted-provenance adapters (Claude Code, OpenCode, LockedCode)
Gate plugins	Verify a completed cycle's artifacts; return pass/fail + findings. Methodology made mechanical.	Deterministic gates: drift, citation-integrity, coverage. Pluggable interface accepts future gates.
Artifact bus	Move and persist verifiable artifacts with provenance between stages.	Local-filesystem build workspace (named evolution path to volume / object store)
Front door	Human entry: start and observe a build.	Factory CLI

The spine is the only component coupled to Temporal. Executors and gates are standalone external processes the spine invokes through activities. This is what makes the muscle swappable and the loop ownable.

The Three-Layer Execution Model

An executor is not a black box. It decomposes into three layers, and the distinction is load-bearing for provenance:

  Reasoning Model        (e.g., Claude Opus)      — decides what to do
        |
        v
     Executor            (e.g., Claude Code)      — turns decisions into tool calls
        |
        v
      Tools              (e.g., the Read tool)    — touch the source of truth

The source-of-truth interaction happens in the tool layer. Therefore provenance is captured there — at the tool-call boundary — not inferred from what the model says it did. The read-log is a recording made at this layer. This is the mechanical basis for provenance is observed, never self-reported.

Build Lifecycle (Canonical Flow)

  Task Roadmap
        |
        v
  [ FactoryBuildWorkflow ]  (parent — durable, holds position + advancement rule)
        |
        |  for each roadmap entry, in dependency order:
        v
  +------------------------------------------------------------------+
  |  [ PromptCycleWorkflow ]  (child — one task, ephemeral)          |
  |        |                                                         |
  |        v                                                         |
  |   Pre-flight gates  ---- fail ---->  (report to parent)          |
  |        | pass                                                    |
  |        v                                                         |
  |   Executor activity  (heartbeating)                              |
  |     - adapter installs tool-boundary interceptor                 |
  |     - CLI runs the prompt; every read captured to read-log       |
  |     - CLI writes code + completion-report.json to workspace      |
  |        |                                                         |
  |        v                                                         |
  |   Post-flight gates  (run in parallel — read-only):              |
  |     - drift gate        (read-log vs disk)                       |
  |     - citation-integrity gate (code vs read-log)                 |
  |     - coverage gate     (measured % vs contract)                 |
  |        |                                                         |
  |        v                                                         |
  |   Gate verdict  -------> returned to parent                      |
  +------------------------------------------------------------------+
        |
        v
  [ Parent advancement decision ]
        |
        +-- all gates pass ----------> commit + push, advance to next entry
        |
        +-- gate failure ------------> spawn corrective child (same task,
        |                              seeded with prior findings)
        |
        +-- audit cadence reached ---> spawn audit child, then recalibrate
        |
        +-- roadmap exhausted -------> build complete (STATUS=complete)

  (Between children only, never mid-child:
   parent may Continue-As-New to bound its event history.)

The Spine — Temporal Workflows

FactoryBuildWorkflow (Parent)

One instance per build. Owns durable long-horizon state and nothing transient: the ordered roadmap (each entry carrying its task ID, prompt pointer, and declared dependencies), the current position, per-task status, the audit cadence counter, and pointers to each completed cycle's artifacts. It determines the next runnable entry, spawns children, applies the advancement decision (advance / corrective child / audit child / halt / complete), and manages its own event-history size via Continue-As-New.

What it must never do: read, parse, summarize, or reason about codebase content, prompt bodies, or report bodies beyond the structured status fields it needs to decide advancement. Any such logic is a defect.

PromptCycleWorkflow (Child)

One instance per task attempt. Born, hydrates from on-disk artifacts, runs one cycle, returns a structured result, dies — its event history dying with it, which is why the parent stays lean. It runs pre-flight gates, invokes the executor (heartbeating activity), runs post-flight gates in parallel, and returns the cycle result. The child does not commit or push; that is the parent's decision after seeing the verdict, keeping "what passed" and "what gets persisted to git" as one authority.

Continue-As-New Invariant (Hard Rule)

The parent bounds its event history with Continue-As-New. Because child workflows are not retained across a parent's Continue-As-New (the parent receives a new run ID; in-flight children would be orphaned and signals broken):

The parent may invoke Continue-As-New only between prompt children, after explicitly awaiting completion of the current child and before spawning the next. It must never Continue-As-New while any child is in flight.

This is safe by construction given sequential execution.

Execution Order — Sequential with Declared Independent Batches

Default execution is strictly sequential in roadmap order. The exception is roadmap-declared independence: when a contiguous group of entries are mutually declared independent, the parent may run them as a parallel batch. Independence is always declared in the roadmap, never inferred by the spine — inferring it would be reasoning about the work. Batches are bounded on both sides by sequential barriers, and the Continue-As-New invariant applies to batch boundaries exactly as to single children.

Activities

Activity	Role	Notes
`RunPreflightGates`	Execute pre-flight gate CLIs	Returns structured findings
`InvokeExecutor`	Shell out to the executor adapter	Heartbeating; long-running
`RunPostflightGates`	Execute post-flight gate CLIs in parallel	Read-only; per-gate verdicts
`CommitAndPush`	Git commit + push on pass	Parent-authorized only; records commit hash
`RunAudit`	Execute the audit step for an audit child	Produces a fresh audit artifact

InvokeExecutor uses Temporal heartbeating with a heartbeat timeout (to detect a hung executor) and a start-to-close timeout (to bound cycle duration). Retries honor the STOP-LOSS discipline: a cycle that cannot go green is not looped indefinitely — it fails to the parent with the suspected cause logged, and the parent decides corrective re-invocation vs. halt. All timeout and retry values are centralized constants.

Contracts

Both contracts are JSON Schema documents validating on-disk artifacts, not network payloads. The executor activity passes data by reference: it writes artifacts to the workspace and returns their paths; the spine and gates read them from disk. JSON Schema (not OpenAPI) is the basis because the executor contract is a data shape, not an HTTP API surface.

completion-report (Executor → Spine)

Carries task_id, attempt, status (complete | blocked | partial), commit_hash (required when complete; absence fails validation), coverage ({ line_pct, branch_pct, measured: true } — self-declared, then independently re-checked by the coverage gate, which is authoritative), files_touched, deviations (the STOP-LOSS log), gate_results (filled by the spine, not the executor), and read_log_ref (a pointer to the harness-captured read-log — the executor does not inline provenance). The human-readable .md report is a rendering of this JSON, not the source of truth.

read-log (Harness → Gates)

Produced by the adapter's interceptor, never by the executor — the provenance of record. Carries task_id / attempt, executor (and capability tier — v1 is always trusted-provenance), an ordered reads list (one entry per content-surfacing tool call, with tool, path, range, content_hash, returned_content_ref, and timestamp), and an interception_manifest confirming the log was produced under a complete interception configuration. Because it is a recording, the entity being recorded cannot fabricate it.

Executor Input

A prompt.md (beginning with the mandatory STOP / read-these-files header), the repo_path, and source_pointers (the authorized source-of-truth files — OpenAPI spec, audit, architecture, conventions). The source pointers are the authorization set; the read-log is the actual set; the gates compare them.

Executor Plugins and the Interception Map

Each adapter wraps one agentic CLI and is responsible for two things: invoking it under the executor contract, and installing the tool-boundary interceptor that produces the read-log. v1 supports only trusted-provenance executors — those whose file reads are observable at the tool boundary. The adapter's defining responsibility is interception completeness: capturing every path by which the executor obtains file content, not only direct reads.

Claude Code — capture via Claude Code hooks at the tool boundary. The Read tool and content-surfacing search tools (Grep, Glob, and any file-content-returning search) are each matched at the post-tool hook and recorded as read entries. Hooks fire deterministically (shell commands, not model prompts), so capture is not subject to model cooperation.
OpenCode — capture via the plugin system: tool.execute.after is the primary capture hook, tool.execute.before a secondary control point, and experimental.session.compacting is captured as a first-class integrity event — the literal Xerox moment — so context-compaction is recorded rather than silently losing reads.
LockedCode (OpenCode fork) — inherits all OpenCode capture points, hardened in the fork: because the read path is owned, every file-content-returning operation can be routed through a single recording chokepoint, making the read-log a property of the runtime rather than a cooperating plugin. This yields provenance the executor cannot route around.

Every adapter emits the same two artifacts (completion-report.json rendered also as .md, and read-log.json) — the uniformity that makes a new trusted-provenance executor one new adapter plus its interception map and per-path capture tests.

Integrity Gates

Gates are standalone external CLIs. Each consumes a cycle's artifacts and emits a structured findings artifact plus a pass/fail exit status. The spine aggregates verdicts; the spine never judges code itself. Every gate conforms to one pluggable interface (workspace path + artifact pointers in; gate-findings.json + exit status out) and is read-only with respect to the repo, which is what permits running post-flight gates in parallel.

Drift Gate (deterministic). Consumes the read-log; for each recorded read, compares the captured content (by hash, then by content on hash mismatch) against the current on-disk content at the recorded path/range, verifying the range is still valid. Fails on any mismatch or invalid range. Zero model involvement. This catches the most common and most dangerous failure mode — stale context / the Xerox effect — provably.
Citation-Integrity Gate (deterministic). Verifies that every entity the produced code depends on or modifies corresponds to something present in the read-log. An entity touched but never read is generation-from-ignorance — hallucination caught mechanically at the tool layer, with no model cooperation.
Coverage Gate (deterministic). Independently measures line and branch coverage (it does not trust the report's self-declared number) and compares against the 100% contract. "Coverage" here is strictly test coverage of code, never build completeness.

Artifact Bus and Trust Boundary

All stage-to-stage communication is through verifiable artifacts on disk. The v1 store is the local filesystem — a per-build workspace containing prompts, the repo, completion reports, read-logs with captured content, gate findings, drift reports, and audit artifacts. Every artifact is associated with its task_id and attempt; failed-attempt artifacts are retained as a forensic history of drift-and-correction.

Because Temporal holds only pointers, the artifact store is inside the trust boundary — every gate assumes store integrity. The store is local and single-tenant in v1; a mounted volume or object store (MinIO / S3-compatible) is a named evolution that would require revisiting this assumption.

Factory CLI (Front Door)

The human entry point, delegating all heavy lifting to Temporal. Its minimum command surface: start a build over a declared roadmap range (with optional executor selection), stream build status/progress (current task, per-task verdicts, drift/correction events), and inspect a specific cycle's artifacts. It is the v1 observation surface in lieu of a dashboard, runnable directly from the developer machine.

Cross-Cutting Conventions

Centralized logging — the spine, adapters, and gates log through a centralized configuration; no ad hoc logging.
Centralized constants — all timeouts, retry counts, cadence values, and coverage thresholds live in one location, never inline.
Documentation — Javadoc on every class and public method (excluding DTOs, entities, generated code), shipped in the same pass.
Testing — unit + integration tests at 100% line and branch coverage, in the same pass; never a follow-up task.
Maven only — the Java spine builds with Maven; no Gradle.
Persistence during development — Hibernate, not Flyway; Flyway only at production.

Scope — v1

v1 is the integrity layer working. A loop with stub gates is a worse CI engine; the gates are the product. v1 is the complete loop with real, working integrity gates, built to completion in a single pass.

In scope: the parent-child Temporal spine on the Java SDK driving a real roadmap end to end; at least one working executor adapter; the executor and gate contracts published as JSON Schema and enforced by the spine; the on-disk artifact bus with provenance; the three deterministic integrity gates; the scheduled-audit cadence and corrective re-invocation loop; the Factory CLI; and the full planning-document set for SafeBuilder itself.

Out of scope (v1): Inspector and Compass integration; the semantic drift gate; parallel prompt-cycle execution; a bespoke front-end dashboard; multi-build / multi-project concurrent orchestration.

Non-goals (any version): not a coding agent; not an IDE or editor; not a dashboard product (in v1); not a replacement for executors; not a semantic correctness oracle — it verifies provenance and contract conformance, not whether the code is good.

Success Criteria (v1)

v1 is complete — STATUS=complete in the methodology's sense — when all of the following hold, with no stubs and no deferred tests:

A real, dependency-ordered build of non-trivial size runs to completion through the spine, executor, and gates, unattended across the full cycle.
The spine survives a process restart mid-build and resumes correctly from durable state.
The drift gate provably detects a deliberately-introduced stale-read case and halts/corrects the cycle, operating from the harness read-log.
The citation-integrity gate provably fails a cycle whose code touches an entity absent from the read-log, and the coverage gate provably fails a deliberately under-covered cycle.
Interception completeness is demonstrated: for the supported executor, every content-surfacing tool path (direct read plus grep/glob/search) is shown to be captured in the read-log, with a test per path.
A failed gate triggers a corrective re-invocation seeded with prior findings, and the forensic history of the drift-and-correction is retained and queryable.
The executor is swappable: a second trusted-provenance adapter can be substituted via config alone, with no spine code change.
All v1 code ships with unit and integration tests at 100% line and branch coverage (measured), with documentation on every class and public method, in the same pass.

Future Work — Semantic Drift Gate (Probabilistic, v2)

The v1 drift gate is deterministic and catches stale-source drift. It does not catch misunderstanding drift — where the source is current but the executor's interpretation of it is wrong. Detecting that requires judgment, and therefore a model. This is explicitly deferred to v2 and explicitly marked probabilistic, because a drift that slips through must be unambiguously attributable to architecture rather than to an uncalibrated gate model.

When built, the semantic gate is itself just another gate plugin — a standalone external CLI, identical in contract to every deterministic gate — running a short, focused, small-context invocation against fresh targeted disk extracts and emitting findings plus a confidence signal. The v1 interface already reserves the drift_mode configuration point (extractive | hybrid | semantic), fixed at extractive for now, so the semantic gate is a drop-in without a v1 redesign. It is intended to run on a locally-hosted LLM — a cheap tripwire, not an oracle.

Architecture Overview · Author: Adam Allard · 2026-06-05 Governing document: SafeBuilder Charter v1.2.0 · Architecture Document v1.0.0