Decision Records

Decision Records

Architecture Decision Records live in docs/adr/. Each records context, decision and consequences; several carry the data they were made from.

ADR	Decision	Why it matters
0001 Single writer, Sonnet worker, Opus advisor	One writer at a time; Sonnet does the work, Opus plans, advises and gates; a cheap router picks the tier	The topology every later decision assumes
0002 Harness conventions	Roles not models in code; typed outputs repaired at most twice; retries, budgets, caching and tracing in one place	Provider swap is config-only; the Fake provider is a first-class adapter
0003 Idempotent effects and sandbox tiers	Every side effect runs under an effect log with a world probe; local, Docker and E2B sandboxes	Crash mid-run resumes with zero duplicated side effects
0004 Loop and verification	Bounded act, verify, fix loops; verify in a fixed order with tests and lint as ground truth	No model verdict can pass a failing check
0005 Escalation policy	Six signals, a never-escalate list, one advisor call per step and K per run, outcomes decided by the next verify	Escalation is capped, logged and auditable
0006 Thresholds from data	repeat_threshold = 3, max_stall = 2 from a recorded sweep; the coupling max_stall >= repeat_threshold - 1 enforced in code	Carries its data, its limits and the first live data points
0007 Product mode	A product orchestrator above the task graph; memory in the target repository; a human approves each milestone; toolchain profiles; no product-level cap by default; ground truth defines product-ready	The direction for M6 to M11
0008 Advisor review of passing high-impact diffs	A passing verify whose diff is high impact gets one advisor review before commit; continue commits with no extra coder turn	Gave the advisor a deterministic live path; first live advisor data
0009 Toolchain profiles	Every stack-specific command and parser behind one protocol; the python profile reproduces the old behaviour byte for byte; a test guards the boundary	Other stacks become data plus a small parser
0010 Product graph and bootstrap	A separate graph with interrupts for every human stop, a normalised spec, and an idempotent bootstrap with the profile's checks as ground truth	scio new from an empty directory to a green repository

Related records

• docs/LESSONS_LEARNED.md: one retrospective per milestone, read end to end before every new milestone; the standing pre-flight list at the top.
• docs/ISSUE_LEDGER.md: every problem hit (I-001 to I-061 so far), each with root cause, fix and the sweep for the same construct elsewhere.
• docs/IDEAS_TRIAGE.md: proposed improvements triaged by return on investment against live data.
• docs/RESEARCH.md: the evidence behind the design.