Skip to content

README.md

Latest commit

 

History

History
75 lines (64 loc) · 6.97 KB

README.md

File metadata and controls

75 lines (64 loc) · 6.97 KB
Raw

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