Plugin Seam Refactor
Static Extension Seams
Harnesses and production drivers were pulled behind explicit in-process contracts.
5 milestones 27 tasks 62 agents
16 plan 35 execute 42 review 2 fix
245k peak context
129k median execute
8h 9m total 11m 58s per task
15m 39s plan 5h 2m execute 1h 48m review
340 edits 2k commands
codex harness
This run was a broad refactor of Gantry's extension boundaries. It started by taking accidental state and cross-driver knowledge out of the shared build context, then gave harnesses a registry, then moved driver execution and cold read behavior toward explicit service contracts. The live tree has since moved the driver side into the generic pattern system, so some original modules are gone; the important result still visible is the rule that extension points are declared through stable in-process surfaces instead of scattered matches.
How this walkthrough is structured
Feature
What did the run build and ship?
Harness selection still runs through a registry, while the driver seam has evolved into pattern pins, read-side contracts, shared services, and pattern-independent partial merge.
Build
How did Gantry structure the work?
The cut separated harness work from driver work, then let reviews reopen the driver side where the first registry pass had preserved too much central dispatch.
Milestone 1
Foundation Cleanup
4 tasks 12 agents 56m wall time 206k peak context
The exact build modules from this period have been reorganized, but the concepts still stand in the current run code and driver documentation. Unit-local state, goal-cycle support, roster announcement, and driver-owned footprint knowledge now appear as named surfaces rather than incidental fields or private reaches.
This milestone carried the preparatory work that had to happen before either registry could be meaningful. Its boundary was deliberately conservative: preserve the existing dispatch model while removing state and dependency shapes that later modules would otherwise trip over. The run-level ledger recorded it green, and the nested work stayed focused on refactor points rather than new extension APIs.
Unit Context Extraction
2 agents 17m 51s wall time 206k peak context
The current source still documents `UnitContext` as the way unit-local variation reaches the shared service path. Later pattern work moved files around, but milestone attribution and design-specific preamble selection remain described as data supplied to the shared primitive, not as broad driver-private state on a common context.
This sprint was asked to pull milestone attribution and design prompt details out of shared mutable context into a unit descriptor. That was a small enough slice for a fresh agent because it changed ownership of a few specific state values without changing the run model. The gate and review stayed green, so later work could treat the descriptor as available.
Driver Coupling Removal
2 agents 13m 53s wall time 140k peak context
The live tree still has named goal and loop support in the run layer, and the driver contract describes that pattern-specific behavior belongs in support traits or production-world effects. Roster announcement is also called out as a service operation, which is the durable form of this cleanup.
This sprint targeted the accidental reaches between loop and goal behavior, and between map and milestone roster behavior. The cut was narrow: make the shared dependency explicit before any registry existed. It completed without recorded recovery, which meant the later service surface could rely on named support rather than inherited private methods.
Loud Harness Fallbacks
4 agents 6m 53s wall time 82k peak context
The agent runner still errors when a resolved harness implementation or config slice is missing. The harness resolver also treats unknown user ids as named errors, while startup and assistant defaults remain ordinary defaults. That distinction is visible in both code and documentation.
This was the one behavior-changing preparatory slice. It converted internal harness drift from an implicit Claude run into a named error, while leaving product defaults alone. The sprint started more than once but landed as a contained change, keeping the harness registry milestone from mixing refactor with fallback semantics.
Local Driver Footprints
1 agents 6m 30s wall time 69k peak context
The current pattern contract no longer treats run footprints as random core literals. Resume, read-side projection, and partial merge derive their answers from persisted pattern data and declared capabilities, while map and goal effects remain behind their own support surfaces.
This sprint moved goal snapshot names and map checkpoint behavior toward the driver areas that owned them. It was scoped as ownership relocation, not a registry change, so persisted layouts and resume behavior stayed fixed. The nested ledger shows it landed without a recovery note.
Milestone 2
Harness Registry
4 tasks 12 agents 44m 11s wall time 117k peak context
The harness registry is still a direct live feature. `HARNESS_REGISTRY` declares the supported harness ids, config constructors, display labels, shortcuts, and fixture harness entry, while the docs describe a static in-process extension model and keep harness choice separate from pattern binding.
This milestone isolated the harness axis before the driver work began. The first registry slice hit a gate failure and needed repair, which is where the difficulty belonged: moving defaults, metadata, construction, and drift errors into one source of truth without changing user selection. Later sprints used that foundation for launch behavior, invariants, and docs.
Registry Foundation
4 agents 16m 52s wall time 117k peak context 1 fix
The registry entry type and registry table remain in `src/engine/harness/mod.rs`. Construction, environment-backed config, display names, shortcuts, known-id checks, and named defaults now flow through registry helpers instead of scattered id branches.
This sprint replaced parallel harness identity and metadata dispatch with a registry and a defaults block. It was the milestone's pressure point: the gate failed once and a fix ran before it settled. That boundary made sense because every later harness behavior needed a single resolved entry to ask.
Interactive Launch Hook
2 agents 6m 54s wall time 91k peak context
Each harness can now provide its own interactive launch command through the harness trait. The shared helper resolves installed options and launch metadata from the registry, so foreground investigation does not require core code to branch by concrete harness id.
This sprint moved blocker-investigation launch behavior behind a harness capability. Its gate recorded a note but no retry, which fits a migration of launch details where preserving each harness's invocation shape was the main risk. It kept normal non-interactive execution out of scope.
Fifth Harness Invariant
1 agents 11m 6s wall time 88k peak context
A fixture harness entry remains in the registry specifically to keep the extension path wider than the shipped set. Source-shape tests still reject production code that hardcodes built-in harness ids or display labels outside the allowed registry and defaults surfaces.
This sprint turned the registry rule into a testable extension path. The requested toy harness kept the scope concrete: prove a new entry exercises construction, config, display, shortcut, and launch behavior without adding core branches. The run facts show this slice stayed green.
Registry Documentation
2 agents 3m 21s wall time 61k peak context
The harness docs now describe static in-process registry entries, role-based selection, startup fallback, remembered run harnesses, assistant harness resolution, and per-harness environment settings. They also explicitly separate harnesses from the pattern system.
This sprint documented the harness seam after the implementation pieces were already in place. It was intentionally thin: align public and contributor docs with the registry without promising dynamic loading or changing harness selection. The gate stayed green.
Milestone 3
Driver Surface
5 tasks 19 agents 1h 56m wall time 181k peak context
The original build directory has been renamed into the current run and pattern layers, but the service contract survives in the driver reference. `DriverServices`, `UnitContext`, roster announcement, goal support, map effects, and partial-merge state are still described as the surfaces production worlds may use.
This milestone created the shared service surface and named work-unit primitive before the driver registry moved dispatch. Most slices stayed green, but map enforcement and docs stopped once and were replanned twice, showing that documenting and enforcing the boundary was harder than carving the first service methods.
Service Surface
1 agents 17m 37s wall time 95k peak context
The current contract reference still names `DriverServices` as the shared run surface. Its listed capabilities cover orchestration work while steering pattern-specific behavior into production worlds or named support traits, which is the later form of this service foundation.
This sprint introduced the named service contract for shared run operations. It was a foundation slice, broad enough to cover events, agents, gates, ledgers, worktree helpers, recovery hooks, metadata, and partial-merge state while excluding unit-local driver data. The record shows no recovery at this boundary.
Gated Work Unit
2 agents 11m 58s wall time 146k peak context
The live system now expresses the same idea through generic pattern execution and the sprint pipeline. The docs still describe the service surface and pattern interpreter as the place where shared gate, ledger, roster, and finish behavior live rather than letting each production shape reinvent them.
This sprint named the shared plan-to-sprints primitive and exposed it through the service surface. It was the central reusable unit: flat runs were the bare form, while milestone and design runs added unit context. A clean boundary here let later migrations reuse the same proof loop.
Milestone Service Migration
2 agents 6m 38s wall time 116k peak context
Modern build and design execution have since been absorbed into pattern composition, but the persisted documentation still treats those differences as declared pattern inputs and unit state. The important residue is that shared orchestration is reached through contracts, not arbitrary access to a backing context.
This sprint moved milestone and design flows onto the service surface and the gated unit primitive. That was the first real consumer test for unit context because it carried milestone attribution and design prompt variation. The sprint stayed green, which meant the primitive could support non-default unit state.
Goal Loop Migration
2 agents 18m 39s wall time 181k peak context
Goal and loop behavior still share named support in the current run layer. The driver reference explicitly says goal and loop iteration behavior belongs behind `GoalIterationSupport`, while the public drivers doc describes goal and Ralph runs as pattern executions with declared state and gates.
This sprint moved goal and loop behavior toward the service-based execution path. Its charge was bounded by the earlier goal-cycle support work, so the agent could focus on iteration support rather than general dispatch. The gate and review completed without recovery.
Map Enforcement Docs
9 agents 54m 3s wall time 120k peak context 2 replans
Map behavior is now described as a bundled pattern with fan-out work and a bounded worker pool. The contract reference routes map-specific classification and checkpoint behavior through the map effects surface, and modern runs rely on persisted pattern evidence rather than layout guesses.
This sprint had to enforce the map contract and write the boundary down. It stopped on the first attempt and then went through replanning before landing, which marks the documentation and enforcement edge as the uncertain part of the milestone. The final attempt completed green.
Milestone 4
Run Dispatch Registry
7 tasks 30 agents 2h 56m wall time 245k peak context
Little of this milestone's exact registry shape remains in the live tree. Its durable contribution is visible as the current requirement that pattern identity, read-side behavior, run capabilities, and partial merge come from persisted pattern contracts rather than core matches over built-in driver names.
This milestone attempted to move run, resume, and read-side dispatch behind registered drivers. It landed useful contract pieces, but its own review notes later judged the scope incomplete because central built-in dispatch still selected too much behavior. The next milestone had to treat this as groundwork, not as a finished seam.
Driver Contract Base
3 agents 19m 3s wall time 152k peak context 1 replan
The live driver contract no longer presents a closed payload registry as the top-level model, but it keeps the contract vocabulary this sprint introduced. Driver read-side behavior, service access, run capabilities, and compatibility rules are now documented against generic patterns.
This sprint established the first driver interfaces and shared contract shapes. A replan stage ran even though the sprint finished green, which suggests the reviewer adjusted the remaining path early. The slice was still suitable as a base because it did not yet claim to remove every dispatch branch.
Registry Job Selection
2 agents 7m 55s wall time 129k peak context
Current Gantry selects patterns through `--pattern` and bundled flag sugar, then freezes the selected pattern and inputs. That supersedes the original job-selection registry while preserving the idea that identity is pinned and read back from durable run state.
This sprint moved job selection responsibility toward the registry layer. It completed green, but the later milestone note shows this kind of central selection was not enough by itself. The useful boundary was identifying the selected owner before run dispatch, while the incomplete part was still rebuilding built-in routes around it.
Driver Dispatch Routing
9 agents 1h 29m wall time 245k peak context 2 replans
The exact registry dispatch path from this sprint has been replaced. In the current tree, production enters generic pattern execution from a frozen invocation, and the docs explicitly reject adding core matches for parsing, routing, resume, replay, artifact browsing, capability checks, or partial merge.
This was the hard run-dispatch slice. It needed a retry and multiple replans, and later review still found the central built-in route machinery too strong. The stress correctly located the main problem: forwarding through drivers is not the same as letting drivers own dispatch.
Driver Service Classification
2 agents 7m 38s wall time 117k peak context
That classification survives as the current `DriverServices` description. The reference distinguishes audited shared capabilities from goal iteration support, map effects, and pattern-specific production behavior, which is exactly the separation this sprint was asked to establish.
This sprint classified provisional service hooks after real driver calls exposed what they were. Its boundary was cleanup inside the service surface: keep shared operations shared, move private behavior back to owning modules, and carve narrow support traits where needed. It landed green.
Registry Read Surfaces
7 agents 33m 32s wall time 157k peak context 1 fix 2 replans
The current read-side contract is pattern based rather than the original registered-driver surface. It still serves the same purpose: status, replay synthesis, counts, and artifact drill-down are derived from persisted pattern events and declared read-side shape instead of fresh live context.
This sprint moved cold read behavior behind registry entry points. It hit a red gate, ran a fix, then replanned, which fits a read-side migration where status, replay, roster, and artifact views all had to keep legacy shapes. The sprint landed, but later review still found the broader registry seam incomplete.
Driver Merge Support
2 agents 8m 46s wall time 91k peak context
Partial merge is now documented as a pattern-independent run contract. The offline path merges the run branch tip through shared mechanics, while live runs honor a service latch at safe points; the modern design is less driver-specific than the sprint's original target.
This sprint gave drivers a way to supply partial merge behavior for composed runs. It was sequenced after run and read surfaces because partial merge needs both durable identity and shared finalize mechanics. The run facts show it stayed green.
Extension Invariants Docs
2 agents 4m 10s wall time 96k peak context
Some wording from this sprint was later replaced when generic patterns superseded the closed driver registry. The surviving documentation still carries the invariant in updated terms: adding extension behavior should not require new core dispatch matches over built-in production shapes.
This sprint codified the extension rules and documented the registry model as it then stood. It finished green, but the milestone-level review still rejected the claim that the seam was complete. That made the docs and invariant useful evidence for what remained, rather than the final contract.
Milestone 5
Extension Contract
7 tasks 25 agents 1h 59m wall time 187k peak context
The live tree has since generalized this work into the pattern architecture. The visible result is stronger than the narrow driver registry: modern runs carry generic pattern pins, production worlds use documented services, cold readers consume pattern evidence, and partial merge is not selected by built-in driver identity.
This final milestone reopened the driver seam from the incomplete registry state. It had to finish run dispatch, read-side ownership, compiler visibility, partial merge, invariants, and documentation. Several slices were retried or replanned, but the final ledger marked the milestone green after absorbing the earlier central-dispatch debt.
Driver Selection
2 agents 18m 27s wall time 175k peak context
The specific driver-selection payload has been retired by generic pattern binding. Its successor is `pattern.toml`, which records the selected pattern name, compatibility marker, frozen closure, and bound inputs so resume and cold projection no longer reconstruct a driver from layout alone.
This sprint defined the payload used to select which driver should run. It was the new foundation after the prior milestone's central enum path proved insufficient. The slice landed cleanly, giving later work a place to hang run, read, and merge behavior.
Run Dispatch
4 agents 22m 46s wall time 187k peak context
Current execution no longer depends on that exact selected-driver route. New runs enter the generic pattern interpreter with frozen inputs, while legacy driver-shaped pins are deliberately rejected instead of inferred through a hidden compatibility dispatch.
This sprint routed selected drivers to execution through the new contract. It needed a retry, which matches the risk in replacing direct entry calls while keeping old runs resumable. The retry still completed within the same bounded slice.
Read Side
2 agents 9m 57s wall time 107k peak context
The modern `DriverReadSide` section in the reference preserves this surface in pattern form. Cold readers now rely on `pattern-events.jsonl` and declared artifact or progress directories, and unreadable legacy directories project empty instead of guessing from shape.
This sprint completed the cold read path for driver-facing state and results. It was scoped to status, replay, roster, progress, and artifact lookup, so a fresh agent could check it against persisted run data rather than live execution. The sprint stayed green.
Boundary Visibility
5 agents 28m 36s wall time 159k peak context 1 replan
The original backing context files are gone, but the current docs keep the same rule for production worlds. They compile against documented `DriverServices` and named support traits, while private engine state remains outside the extension contract.
This sprint made the service boundary structural instead of merely conventional. It replanned once because hiding the backing context from production drivers required module movement, not a grep rule. That was the right local difficulty: Rust privacy had to enforce the contract.
Partial Merge
2 agents 6m 46s wall time 121k peak context
Partial merge is now even more generic than the sprint brief requested. The reference says every modern pattern run may attempt the stopped-run path, live runs honor the same service latch, and unsupported legacy pins are refused before merge work starts.
This sprint moved partial merge out of core driver-specific branching. It could proceed after boundary visibility because the owning routine needed both shared mechanics and a clear extension surface. The run facts show it finished without recovery.
Invariant Hardening
5 agents 23m 56s wall time 135k peak context 1 replan
The live docs now state the invariant in pattern terms: adding a pattern file or production effect should not add core matches for routing, resume, read-side derivation, plan-source identity, capabilities, or partial merge. The old built-in route framing has been replaced.
This sprint closed the remaining central routing leak and encoded the extension invariant. It replanned once, which aligns with the brief's warning that route-like machinery still mapped built-in labels back into dispatch. The final slice made that inventory testable.
Contract Docs
2 agents 3m 19s wall time 71k peak context
The current driver and harness docs remain the public form of that contract, updated for generic patterns. They spell out static extension, frozen durable pins, declared capabilities, service boundaries, and the separation between coding-agent harnesses and production-flow patterns.
This sprint wrote the reference after the code-side contract was complete. Its scope was documentation as a deliverable: explain identity, run dispatch, read-side behavior, services, compatibility, and partial merge without promising dynamic plugins. It landed green.