adr

Architecture Decision Records

This directory records architecturally significant decisions about Tolokaforge. We follow the Markdown ADR (MADR) format, lightly adapted.

When to write an ADR

Write one when a decision:

• changes a boundary in the Building Block View,
• introduces or removes a cross-cutting rule,
• locks in a quality trade-off (e.g. determinism vs. flexibility, isolation vs. simplicity),
• or replaces an earlier ADR.

Day-to-day implementation choices that don't affect the system shape do not need an ADR — a clear PR description is enough.

How to write one

1. Copy 0000-template.md to NNNN-kebab-case-title.md, where NNNN is the next free number. Never renumber existing ADRs.
2. Fill in the sections. Keep "Context" focused on the forces that drove the decision, not the implementation.
3. An ADR implemented by the PR that introduces it lands Accepted — the decision is in effect the moment that PR merges. Proposed is for a design-first ADR opened ahead of its implementation, and flips to Accepted when the implementing PR merges.
4. If a later decision overrides this one, set the old ADR's status to Superseded by ADR-NNNN and add the back-link in the new ADR's "Decision Drivers".

Statuses

• Proposed — under discussion in a PR.
• Accepted — merged and in effect.
• Deprecated — no longer applies, but not replaced by anything specific.
• Superseded by ADR-NNNN — replaced; keep the old file as historical record.

Index

#	Title	Status
0001	Record architecture decisions in ADRs	Accepted
0002	External model registry — operator-overridable preset data	Accepted
0003	TrialSpec and TrialResult as the typed control↔trial seam	Accepted
0004	TrialArtifactWriter as the typed data-plane seam	Accepted
0005	RunAggregateWriter as the run-level data-plane seam	Accepted
0006	EnvEndpoints — typed runner service URLs on TrialSpec	Accepted
0007	RuntimeBackend Protocol — lift SharedStackRuntimeBackend behind a typed seam	Accepted
0008	Conductor Protocol — per-trial executor seam	Accepted
0009	EnvironmentManifest — typed schema for per-trial multicontainer environments	Accepted
0010	RuntimeBackend provisioning contract — provision / await_ready / endpoints / teardown	Accepted
0011	Seam-definition and data-declaration conventions for new components	Accepted
0012	CheckExecutor Protocol — the custom-checks extension seam	Accepted
0013	RuntimeBackend owns per-trial RPC methods — collapse DockerRunnerAdapter	Accepted
0014	TrialGrader Protocol — swappable trial-grading strategy	Accepted
0015	TrialExecutor Protocol — per-trial substrate-lifecycle seam	Accepted
0016	Runtime backend comparison: shared vs per_trial (lifecycle axis)	Accepted
0017	Persistent agent shell + first-class editor tools + tool-lifecycle evolution	Proposed
0018	Multi-container capability under shared runtime (composition axis)	Accepted
0019	Front-end pluggability via tolokaforge.dx	Accepted
0020	Judge Protocol — the grading-plane judge seam	Accepted
0021	Component-oriented monitoring — ComponentSnapshot / component_* events, panel widget with auto-expand-on-fail	Accepted
0022	Runtime independence — Protocol registries, run_trial, run-trial subprocess contract	Accepted
0023	Runner image internals — monolithic wheel + [runner] extra, internals not a stability commitment	Accepted
0024	Container command surface — the committed contract of tolokaforge-runner	Accepted
0025	Runner wheel split — slim subset artifact + _runner_subset enumeration	Accepted
0026	Service-readiness contract as a fourth entry-point-registry seam	Accepted
0027	Subset-native CLI shim	Accepted
0028	Multi-actor turn policy — interaction_mode + Actor + TurnPolicy	Accepted
0029	build_check as a generic peer-service HTTP probe in core	Accepted
0030	Model data as a second PyPI wheel — tolokaforge-models from the same monorepo	Proposed
0031	Wheel consumers pull published images by default — docker.image_source policy	Proposed
0032	The agent's completion is structural; ###STOP### is the user simulator's	Accepted
0033	External harness registry — operator-overridable YAML for coding-CLI parity knobs	Accepted
0034	External harness plugin discovery — pip-installable harness bundles	Accepted
0035	Whether an agent must act is a per-task assertion, not a stuck heuristic	Accepted
0036	Coding-harness code as a top-level workspace package — tolokaforge_coding_harnesses	Accepted
0037	A runtime gateway is harness data, and its token dialect belongs to the runtime that provisions it	Accepted
0038	Grader detachment — grader as an independently deployable and scalable component	Proposed
0039	Coding-harness as an adapter-agnostic run-config concept	Accepted
0040	Standalone-grader substrate — multi-topology grading behind one Protocol	Accepted
0041	Zero-coverage exit signal on run_state.json	Accepted
0042	Adapter-blind authoring gate — three new BaseAdapter hooks + SkipKind split	Accepted