<!-- informative -->

# Roadmap to Self-Hosting

This guide is the path from the current state to the first self-development run: the orchestrator proposes and
independently validates a real change to its own repository, which a human owner merges. It is a guide, not a
commitment; each phase names the one capability that unblocks the next and the gate that proves it.

Self-hosting here means using the orchestrator to develop the orchestrator. It does **not** mean autonomous production
deployment or an unattended merge: publication and integration stay human-owned
([Production, Integration, and Ownership](integration-and-conflicts.md#production-integration-and-ownership)).

## Starting Point

- The control plane is already general: `controller.submit_run()` admits any run specification.
- The experiment harness is fixed: `build_fixed_target()` builds a hard-coded four-file synthetic repository, and
  candidate code comes from `_SOLUTION_FILES` through `_commands_for`/`_write_script`, not from the model.
- Real runs currently exercise transport, pricing, and accounting while the model contributes only
  `SEMANTIC_EVALUATION` outputs.
- The decisive missing capability is the model-produced implementation path (the milestone-8 handoff's Axis 1).

## Phase Overview

| Phase | Deliverable | Exit gate |
|---|---|---|
| 1. Model writes code | Patch-producing `ARTEFACT` path | Changing the model reply changes the candidate tree and its grade |
| 2. Arbitrary target | `TargetSnapshot` built from any repository and base commit | One non-self repository runs end to end |
| 3. Project oracle | Acceptance manifest over the target's own gates | Known-good, known-bad, and unchanged candidates classify correctly on a real repository |
| 4. General decomposition | Derived obligations and bounded recursive planning | A multi-component task decomposes without hand-authored obligations |
| 5. Run entry point | CLI/run-spec for arbitrary targets | An operator starts, inspects, and stops a run without the harness |
| 6. Operational envelope | Robustness, supervisor, credential lifecycle, spend cap | Sustained real-provider runs settle cleanly under the cap |
| 7. Shadow self-host | Rehearsal on a frozen copy of this repository | One real change proposed, validated, and human-merged on a scratch clone |
| 8. First self-development | A real, small change to this repository | An accepted, human-merged orchestrator change produced by the orchestrator |

## Phase 1: Model-Produced Implementation

Goal: the model writes the code, not the harness. A new patch-producing path emits an `ARTEFACT` (a size-capped,
scope-validated unified diff) for the node's scope; it is admitted through the existing trusted boundary and applied
through the scope-gated `WorktreeManager` importer instead of `_commands_for`/`_write_script`.

Status: **delivered** as the patch-producing capability path. The design is in the
[Axis 1 design brief](research/axis1-patch-producer-design.md); the seam is a `PatchExecutor` whose patch phase applies the
model's admitted unified diff and whose verification phase is the unchanged sandboxed command sequence and trusted
importer. The cheap Axis 3 seed matrix is folded in. The measurement (a real model run under the frozen manifest) is the
next step and is deliberately not claimed here.

Exit gate: with everything else frozen, changing only the model reply changes the produced tree and therefore the hidden
oracle's grade. A model verdict of failure must produce a failing candidate; scripted candidate success must never be
relabelled as model coding capability. The gate is pinned by
`tests/test_axis1_patch_producer.py::test_axis1_exit_gate_model_reply_changes_tree_and_grade`.

## Phase 2: Arbitrary Target Repository

Goal: replace the fixed synthetic target with a `TargetSnapshot` builder over an existing repository and base commit.
Freeze the task statement, project kernel, owned scopes, visible commands, and environment image from that repository
rather than from constants.

Status: **delivered** (`experiment_target.build_target`), after the [Phase 2 adversarial review](research/phase2-patch-boundary-adversarial-review.md) remediation (verification addendum appended there). The builder validates the repository and base commit fail-closed
and freezes the task statement, project kernel, owned scope, visible commands, components, acceptance criteria, root
obligations, and trial scripts from the caller describing that repository — with bidirectional criterion coverage
between the criteria and the obligations. The trial machinery now derives the root contract from the target snapshot,
takes trial scripts from the target, validates oracle coverage against the target's criteria at freeze, and (in the
patch path) verifies with the target's visible commands only — the model's patch is the candidate, so nothing writes
code at BUILD time. Two Axis 1 defects were fixed on the way: the patch's changes are now imported as candidate changes
(previously snapshotted as base and silently dropped), and unified-diff hunks apply with strict preimage verification
(a partial hunk never truncates a file; a stale preimage fails the attempt closed).

Exit gate: a non-self repository is run end to end under the frozen manifest discipline. Pinned by
`tests/test_phase2_general_target.py`: a calculator repository with its own tests runs pilots, freeze, and a measured
comparison across all four arms, where changing only the model reply changes the produced tree and the held-out oracle
grade — the working reply is graded `CORRECT_ACCEPTANCE` and the broken reply is not — with the two frozen manifests
identical (the reply is the only variable).

## Phase 3: Project-Owned Oracle

Goal: an acceptance manifest whose visible and hidden checks are the target's own gates (for this repository:
`scripts/check-tests`, `scripts/check-static`, `scripts/check-docs`, `orchestrator.conformance`), with held-out checks
kept hidden from the workload. Keep the generator and the oracle independent.

Those gates now include meta-registries with floors (`min_covered`, `min_fixed`, fidelity ratchets, `prefix_revision`
completeness) alongside the command gates, so the oracle must freeze the registries as gates and bind them to the target
the R12 way — mismatch rejection, not a label echo. A candidate that adds a fixture or closes a declared deviation can
trip a floor, so the registries are part of the deliverable, not only of the oracle.

Status: **delivered** (`project_oracle.build_project_oracle`), after the
[Phase 3 design brief](research/phase3-project-oracle-design.md) settled the
measured constraints. The hidden checks are the target's own gates — the
command gates with **frozen script identities** (a candidate rewriting its own
gate to `exit 0` is graded FAIL) and the meta-registry floors frozen as gates
(`min_covered`, `min_fixed`, `min_open`, `min_parameters`, the fidelity
ratchet, the structural rules) — all in the ruling's sanctioned probe shape,
bound R12-style by content. Two measured deviations are documented in the
brief: `orchestrator.conformance` and the external-link half of
`scripts/check-docs` are trusted-side gates (nested sandbox construction is
unavailable from a grading sandbox; external links need the network the net
namespace denies), and `gate-check-tests` runs the suite's deterministic
subset (the runner-spawning modules and two nested-environment-sensitive tests
stay the trusted gate's). The ruff/pytest control files and baseline
`tests/**/*.py` corpus are content-frozen in the gate comparison: changing or
adding test/control files requires an explicit re-freeze. At build, the frozen
gate/config/test/registry inputs are checked against `TargetSnapshot.commit`,
so a dirty worktree cannot supply a different gate contract. Candidate-added
registry rows remain inspected by the frozen registry checks, but new tests
are not executed until a trusted freeze adopts them.

Exit gate: bidirectional coverage validation classifies known-good, known-bad, unchanged, timeout, and
infrastructure-failure candidates correctly on a real repository. Pinned by
`tests/test_phase3_project_oracle.py`: the five-case corpus runs over this
repository under the frozen floors — and the `unchanged` case is an
internally consistent floor demotion that the repository's own meta-gate
passes and only the **frozen floor** catches, which is the phase's whole
claim.

## Phase 4: General Decomposition

Goal: decompose a real repository without hand-authored obligations. Derive criterion coverage and owned scopes from the
task and kernel, and lift the current exclusion on recursive planning over model outputs for a bounded pilot.

Exit gate: a multi-component task decomposes into scoped children that reach evidence-bound acceptance, and the
decomposition structure — obligations, dependencies, scopes, criterion allocation — is **reproducibility-checked**:
a declared structure is admitted only when it is measurably divergent from what derivation produces, names only
axes that were measured, and carries a rationale. Necessity of a declared *edge* is not statically provable and is
not claimed. `_commands_for` and `_SOLUTION_FILES` are out of scope on two grounds: they are candidate production
rather than decomposition, and they are transitional machinery retired when the patch path replaces the scripted path
(`verify_commands_for` is the already target-general surface).

Status: **delivered.** Obligations are derived for real targets — `build_target` derives one obligation per
component from the declared components, criteria, and the tree at the base commit, with integration dependencies taken
from observed cross-component imports rather than from prose ([Phase 4 design](research/phase4-decomposition-design.md)).
The fixed target's structure is **declared**, and that declaration is now first-class and mechanically justified: it
lives in a versioned manifest, and `build_target` recomputes derivation on every build (including a supplied
declaration) and admits it only when the named axes **equal** the measured divergence ([option (e) spec](research/phase4-option-e-implementation-spec.md)). The bounded
recursive-planning pilot is **implemented and cleared by adversarial review** ([pilot
spec](research/phase4-recursive-planning-pilot-spec.md)): the guard derives every bound from replayable state, the
producer isolates the model from live state and records every proposal, and the kernel names the bounds with a pin
that binds them to the code ([producer review](research/phase4-recursive-planning-pilot-producer-review-report.md),
[closure](research/phase4-recursive-planning-pilot-producer-re-review-4.md)).

Integration is **delivered** in three steps — [provider](research/phase4-recursive-planning-integration-provider-implementer.md),
[fixes](research/phase4-recursive-planning-integration-fixes-implementer.md), and
[api-shape](research/phase4-recursive-planning-integration-api-shape-implementer.md). A deterministic
**scripted provider** is routed through the producer inside `RECURSIVE_LAZY`/`RECURSIVE_CONCURRENT` — a
provider inside an existing arm, not a new arm — so the seam and the record are exercised end to end, and
the model-output path is **structurally unable** to reach `DECOMPOSITION_ADMITTED`: admission requires a
non-data capability minted only at the two admission points, and the unguarded constructor is renamed to a
derived-only route.

## Phase 5: Run Entry Point

Goal: a documented CLI/run-spec that points the controller at an arbitrary repository and configures scopes, budgets,
policies, and evidence policy, with run inspection and cancellation. This is the user workflow the harness has stood in
for.

Exit gate: an operator can start, observe, and stop a run on an arbitrary repository without importing the experiment
harness.

Status: **delivered.** The run entry point is delivered through ten recorded rounds — the [run-entry](research/phase5-run-entry-implementer.md),
[fixes](research/phase5-run-entry-fixes-implementer.md), [fixes-2](research/phase5-run-entry-fixes-2-implementer.md),
[fixes-3](research/phase5-run-entry-fixes-3-implementer.md), [fixes-4](research/phase5-run-entry-fixes-4-implementer.md),
[fixes-5](research/phase5-run-entry-fixes-5-implementer.md), [fixes-6](research/phase5-run-entry-fixes-6-implementer.md),
[fixes-7](research/phase5-run-entry-fixes-7-implementer.md), [fixes-8](research/phase5-run-entry-fixes-8-implementer.md),
and [fixes-9](research/phase5-run-entry-fixes-9-implementer.md) reports — with F26–FRK-1/FFR-1–FFR-4/F43 disposed: the loader's named-refusal face is one envelope seam with its
generated-input pin (R10). FRK-1 (a non-string `kernel_id` coerced past the schema) is refused at load (R11),
and FFR-1–FFR-4/F43 close by the fixes-8 and fixes-9 briefs' text. The exit gate is claimed: an operator
starts, observes, and stops a run on an arbitrary repository without importing the experiment harness. The five
operator classes were re-driven live at FINAL through the documented `python3 scripts/orchestrate.py` heads
against a real frozen repository (each created via `git init`/`add`/`commit`, one derivable component): accept
exits 0 with `accepted: true` and `outcome: ACCEPTANCE_CLAIMED`; the failing-command refusal and the wall-clock
timeout (`limits.wall_clock_seconds: 1`, a sleeping command) exit 1 with `accepted: false` and `outcome:
INFEASIBLE`; the mid-run cancel's second-process `stop` exits 0 and the launcher exits 1 with `outcome:
CANCELLED` — each a settled terminal outcome, no traceback, the document equal to the durable fresh replay, and
`inspect` reading clean; the validation-stage face (a wrong-typed spec) refuses at load with the store absent; and
the injected-`ProtocolViolation` class rides on its committed pin `test_protocol_violation_refusal_shape` (an
executor-seam monkeypatch, named not rebuilt). `run_entry.py` is byte-identical to `ca9a25a` and the pin battery
is green.

## Phase 6: Operational Envelope

Goal: the robustness and lifecycle work needed for long, real runs: bounded provider retries and backoff, an external
supervisor for controller death, real credential issuance/revocation with no secret in a tracked file, and an
experiment-wide spend ceiling that covers pilots and retries.

Status: **delivered** — the exit gate is met. Bounded 429 backoff landed with Axis 2, the provider key is read from the
environment rather than a tracked file (rotation remains an owner action), and the experiment cap is wired. The
external supervisor is delivered through four recorded rounds — the [supervisor](research/phase6-supervisor-implementer.md),
[supervisor-fixes](research/phase6-supervisor-fixes-implementer.md),
[supervisor-fixes-2](research/phase6-supervisor-fixes-2-implementer.md), and
[boundary](research/phase6-supervisor-boundary-implementer.md) reports (freeze, descendant sweep,
sweep-to-quiescence, container boundary — F11/F12 fixed with red evidence). The exit gate draws on the 16-trial
real-provider campaign ([implementer](research/phase6-exit-gate-runs-implementer.md),
[review](research/phase6-exit-gate-runs-review.md); Record row `18d9f89`): sixteen trials settled across the four
arms and seeds 1001–1004 under one authorisation, ledger committed `0.8020469000000002` under the `10` cap,
credential-bytes scan 0 hits over the 2326 stores present, scope `tripped: none`.

Exit gate: sustained real-provider runs complete with every trial settled, no credential bytes in any store, and the cap
enforced before spend.

## Phase 7: Shadow Self-Host

Goal: rehearse on a frozen snapshot of this repository in a scratch clone, using a disposable worktree and branch. Pick
one small, low-risk task whose acceptance is the repository's own gates; keep held-out checks hidden; require human
review and a human-performed merge. No run touches the live working tree.

Exit gate: the orchestrator proposes one real change to a copy of this repository, validates it, and a human merges it on
the scratch clone; and the run completes within the performance bound set by the
[performance plan](research/performance-plan.md).

Status: scoped at R16 — one real change on a scratch clone: `load_run_spec` rejects every non-plain YAML tag at load
(R10's deferred hardening), its acceptance the repository's gates, held-out checks hidden until after the human merge.
The shadow run completes within 30 minutes wall-clock on the development host and under 5 USD of model spend (the
performance plan's measured baseline as the basis). The orchestrator proposes and validates; the human reviews and
merges.

## Phase 8: First Self-Development Run

Goal: one real, small, low-risk change to the orchestrator, produced by the orchestrator on a disposable worktree with
the repository's gates as visible checks and an independent hidden oracle, recorded with its evidence, cost, and audit
trail. The merge is human-owned.

Definition of done: an accepted change to this repository that a human reviewed and merged, with the run's outcome,
evidence, and ledger retained and replayable.

## Performance (Cross-Cutting)

Run time must scale with the work the target actually does, not with the orchestrator's own bookkeeping; otherwise a real
repository is unusable. The performance workstream is placed across the phases above and is detailed in the
[performance plan](research/performance-plan.md):

- **Before Phase 2** (after the Phase 1 capability work, with the Axis 3 seed matrix folded in): remove measured
  overhead and add the projection — session-scoped test fixtures, oracle grade caching, oracle consolidation (closed as
  no change on re-measurement; the R08 verdict stands), per-attempt sandboxing, and a cheap state clone gated
  by an inventory-independent input-purity property.
- **Phase 2-3**: scaling fixes — structural sharing, snapshots as a non-authoritative replay cache (with normative
  amendments), and git-native worktrees with content-addressed digests — triggered by the projection from the first
  block.
- **Phase 6**: throughput — parallel trials and model calls, after the experiment design is frozen.
- **Phase 7**: the exit gate includes the performance bound.

## Invariants for Self-Modification

These hold at every phase and must not regress:

- Candidate content never controls trusted Git metadata or hooks
  ([readiness review](report-milestone8-readiness.md), R01).
- A run never executes against the live working tree; disposable worktrees only.
- Publication and integration have a human owner; the orchestrator proposes, a human merges.
- Acceptance remains independent of the generator: the model that writes a candidate never grades it.
- Failures fail closed and are recorded; budget exhaustion, depth limits, and timeouts never imply success.
- An external supervisor exists before unattended long runs; controller death cannot leave unrecorded effects.
- Reported results stay honest: scripted or structural success is never presented as model capability.

## Out of Scope

Distributed execution, partitioned ordering, speculative alternatives, snapshots as authoritative state, multi-model
routing, learning-based routing, and autonomous production deployment. These stay excluded until a self-hosted run
demonstrates a requirement for them.
