decisions

Decisions packet — the living source of truth

Why this exists. We kept losing context: an agent built SANDBOX_RUNTIME=controller with no idea of our decisions; a retrospective pack nearly evaporated in a zip; the "why" lived in one giant chat session that isn't durable. This directory is the antidote. If a decision isn't written here, it didn't happen. Reference it every session; update it every session.

Status of everything here: drafts I (Claude) inferred from the recovered pack, git history, and Kevin's 2026-06-05 brain-dump. Kevin confirms/edits each. Lines marked DRAFT — confirm are my guesses, not settled.

What lives where

File	Holds	Cadence
why-cutover.md	Read first. Why the cutover exists, the approach, and what NOT to do	rarely
README.md (this)	The map + how to use the packet + the rules→AGENTS.md plan	rarely
decision-log.md	Index of every ADR with status (Proposed / Accepted / Superseded)	per decision
adr/NNNN-*.md	One Architecture Decision Record each: context → decision → consequences	per decision
current-state.md	Snapshot: where we are right now, what's built, where to pick up	per work session
action-log.md	Chronological "what we did" — the durable diary	per work session
fault-catalog.md	The load-bearing faults: what / how / why, per port. The teeth.	as ports land
learnings.md	Hot store: the recent ~20 durable lessons (what we now know + why)	per milestone
learnings-archive/YYYY-MM.md	Cold learnings; loaded on demand, not every session	on rotation
rules-for-agents.md	Always-on rules staged here, then distilled into AGENTS.md	as rules harden

Harness note (load-bearing): in Claude Code, only AGENTS.md (the CLAUDE.md symlink) auto-loads — the .opencode/rules/*.md blocks do NOT. This packet lives in docs/ precisely so it's harness-neutral and reachable from the AGENTS.md pointer. See learnings.md L-009.

Map — where everything is (the scattered docs, by topic)

The "why/approach" is in this packet. The depth is scattered across docs/design/. This map is the single index so you don't have to hunt. Start at the top; drop to a cluster on demand.

Start here (this packet, L1 truth): why-cutover.md → current-state.md → adr/ + decision-log.md → learnings.md. Parked-for-later work: parked/.

The why / retrospective — docs/design/architecture-retrospective/:

• 01-system-frame.md (the two-plane shape) · 02-mistakes-and-root-causes.md (M1–M7) · 03-learnings-and-principles.md (what to do instead). The ADRs cite this pack.

Conformance / testing / faults / registry (the "is it working" layer):

• docs/design/architecture-retrospective/05-testing-conformance-faults.md — the conformance model
• docs/design/architecture-retrospective/04-port-registry.md — the 14-port registry
• docs/design/architecture-retrospective/registry-governance.md — how the registry is enforced
• docs/design/architecture-retrospective/verification-techniques.md — how to verify a port
• docs/decisions/fault-catalog.md — the load-bearing faults (the teeth), per port
• docs/design/sandboxes-and-snapshots/testability.md — testability of the target design
• Code: src/lib/ports/ · test/ports/conformance-registry.test.ts · test/integration/walking-skeleton.test.ts · test/integration/disruption.test.ts

Target architecture / ports / the build ladder — docs/design/sandboxes-and-snapshots/:

• decoupled-architecture.md · port-catalog.md · target-architecture.md · failure-modes.md · local-to-prod-playbook.md (local→prod, the rung ladder of ADR-0006)

The big design pack (comprehensive TARGET spec — aspirational, not current code) — docs/design/background-agent-platform/ (numbered 00–14; see its MANIFEST.md). Subsystem designs: llm-gateway/, secrets-and-environments/, event-log/, coding-agent-seam/, agent-workspace-ui/, security-designs/, postgres-litellm-environment/.

As-built gap analysis / status: docs/design/agent-architecture-review/ (subsystem-map, gaps-and-risks) · docs/gaps-and-issues/ (the living gap list + details/) · docs/handoff/ (session handoffs) · docs/runbooks/ (scanning-errors, oauth).

How to use it (for any agent, including future-me)

1. Read why-cutover.md first, then current-state.md. Don't read the code first — read why we're doing this and what NOT to do, then where we are.
2. A decision is an ADR. Small or large, if we chose something, it gets a numbered record. Cite the source (recovered pack item, git SHA, or "Kevin, ").
3. A port is a bundle, never a bare interface: (interface, ≥1 real adapter, 1 fake adapter, 1 contract test, 1 fault catalog). "Done" = all adapters pass the contract test and the fault catalog.
4. The fault catalog is the spec, not scaffolding. Never weaken a negative test — especially a fail-closed one — to make a build green. A registry tuned until everything passes is worse than none.
5. Verify platform facts against live docs, not memory (Cloudflare DO observability export, Modal lifecycle, gateway routing config). The interface is stable; the adapter needs the live check.

The rules → AGENTS.md plan

rules-for-agents.md is the staging area. Once a rule has earned its place (we've followed it for real, it caught something), it graduates into AGENTS.md as an always-on rule so it activates every session without anyone remembering to look. The eventual goal is a thin set of AGENTS.md rules + (where the harness supports it) hooks that enforce the transforms automatically on both sides. Until a rule graduates, it lives here.