@mseep/open-computer-use 1.0.0

package/docs/architecture/adr/0009-audit-pipeline-pluggable-by-contract.md

@@ -0,0 +1,76 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-06
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC7.2, ISO27001-A.8.15, NYDFS-500.06, DORA-Art.10, EU-AI-Act-Art.12]
+license-impact: none
+threat-mitigation-link: ../06-threat-model.md
+---
+
+The audit pipeline's durable bus, WORM store, SIEM, and transparency log are integration contracts the customer fills; OCU delivers only the chain of custody and a local durable commit.
+
+# ADR-0009: Audit pipeline is pluggable-by-contract
+
+## Status
+
+`proposed`
+
+## Context
+
+The Audit pipeline ([component 07](../components/07-audit-pipeline.md), trust-zone 5 of [02-trust-boundaries.md](../02-trust-boundaries.md) §2) turns each source's OCSF event into a durable, ordered, tamper-evident record and forwards it to a customer sink. Two substrates were left undecided: the durable-bus product and the WORM cold-tier store ([component 07](../components/07-audit-pipeline.md) Shelf delta — "ADR-level picks; neither is decided here"). [02-trust-boundaries.md](../02-trust-boundaries.md) §10 held "mandatory in code, pluggable in sinks" unanchored by an ADR.
+
+The build-scope principle ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)) sets the rule: OCU builds the control plane and the sandbox; every neighbouring capability is integrated off-the-shelf, bundled only as a one-click-solo reference. A bus, an object store, a SIEM, and a transparency log are neighbouring systems that run when OCU is stopped. The open question is where, inside the audit pipeline, the build/buy line falls — what OCU must author versus what the customer plugs in.
+
+## Decision
+
+We draw the build/buy line once for the whole audit tract: OCU delivers the chain of custody and a local durable commit; everything downstream — bus, store, SIEM, transparency log, signing-key custody — is a published contract the customer fills, with a one-click-solo reference default, carrying no OCU CVE responsibility.
+
+## Consequences
+
+OCU's mandatory core (the DELIVER side of [02-nfrs.md](../manifesto/02-nfrs.md) §Scope ownership), present on both shelves and chaos-testable:
+
+- **Host-attested ingest** — binds the OCSF `source` to the verified channel identity, never the payload ([NFR-SEC-09](../manifesto/02-nfrs.md)).
+- **A local durable commit** — fsync-then-ack on the always-present file-system sink, before the source's publish is acknowledged. This is what [NFR-REL-03](../manifesto/02-nfrs.md) (RPO = 0) forces: an arbitrary customer bus whose ack semantics OCU does not control cannot hold RPO = 0, so the no-loss commit point is OCU's, upstream of any seam. It does not force OCU to own the bus. Write-before-ack and "no synchronous DB on the critical path" are [NFR-REL-12](../manifesto/02-nfrs.md).
+- **Chain writer + Merkle-head accumulator + envelope signer** — per-source hash linkage, the daily head, and the submission-envelope signature ([NFR-SEC-03](../manifesto/02-nfrs.md)). OCU signs only the envelope; the transparency-log operator signs the head.
+- **OCSF envelope and retention-policy enforcement** — the mandatory fields out-of-band of the payload ([NFR-MAINT-AUDIT-SCHEMA](../manifesto/02-nfrs.md)) and the 7 y / 10 y floor on both shelves ([NFR-COMP-01](../manifesto/02-nfrs.md)).
+
+The pluggable seams (the ENABLE side), each a contract plus a solo-reference default:
+
+| Seam | Solo reference | Full-shelf | Open question |
+|---|---|---|---|
+| Durable-bus product | embedded append-only file / WAL | customer NATS or Kafka | [#150](https://github.com/Wide-Moat/open-computer-use/issues/150) |
+| WORM cold-tier store | none — FS + hash-chain is the floor | customer S3 Object Lock Compliance / Ceph RGW | — |
+| SIEM sink | file-system sink only | OCSF bridge (Splunk HEC, syslog-TLS, ECS, UDM) | [#150](https://github.com/Wide-Moat/open-computer-use/issues/150) |
+| Transparency-log endpoint | local Merkle head | customer-pointed (public or private) | [#151](https://github.com/Wide-Moat/open-computer-use/issues/151) |
+| Envelope-key custody | host-local key | HSM-rooted PKCS#11 / KMIP | — |
+
+- Positive: the minimal shelf runs from one `docker-compose up` with no bus, no object store, and no SIEM; the FS sink plus hash-chain and signed Merkle head is the complete tamper-evidence story. The enterprise shelf points each seam at infrastructure the customer already operates and audits.
+- Positive: OCU carries no CVE, SBOM, or version lifecycle for a bus, store, SIEM, or log it does not write. The reference defaults exist for the solo path, not as a bundled product line.
+- Negative: the minimal-shelf tamper-evidence is detective (the chain detects deletion or truncation after the fact), not the preventive WORM-immutability of the full shelf ([NFR-COMP-01](../manifesto/02-nfrs.md)). A deployment whose threat model needs immutability against a privileged actor wires the WORM seam.
+- Neutral: this resolves the two [component 07](../components/07-audit-pipeline.md) Shelf-delta picks in one boundary rule and anchors [02-trust-boundaries.md](../02-trust-boundaries.md) §10 to an ADR. Per-seam transport and backpressure detail stays open ([#150](https://github.com/Wide-Moat/open-computer-use/issues/150), [#151](https://github.com/Wide-Moat/open-computer-use/issues/151)).
+
+## Alternatives considered
+
+- **Bundle a durable bus (ship NATS or Kafka, own its CVE/SBOM/version lifecycle).** Rejected: a bus is a neighbouring system that runs without OCU, so bundling it violates the build-scope principle ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)) and makes OCU accountable for a CVE surface the customer's own platform team already operates. The reference default for the solo path is an embedded WAL, not a bundled bus product.
+- **Make the durable commit pluggable too (write straight to the customer's bus, no OCU-local commit).** Rejected: [NFR-REL-03](../manifesto/02-nfrs.md) RPO = 0 cannot hold against an arbitrary bus whose ack semantics OCU does not control — acking before the bus confirms durability opens a loss window, blocking on a slow bus violates the spill-not-block behaviour of [NFR-REL-12](../manifesto/02-nfrs.md). The thin local commit is the one part that cannot be a pure plug.
+- **Two ADRs, one per substrate (bus / WORM).** Rejected: under the build-scope principle both are pluggable seams on the same side of one boundary, so the build/buy line is a single decision; splitting it duplicates the rationale and fragments a Nygard one-decision-per-file record. The [ADR-0005](0005-egress-credential-delivery-envoy-sds.md) precedent records one role for one container.
+
+## Compliance impact
+
+- `SOC2-CC7.2` / `ISO27001-A.8.15`: the chain of custody (hash linkage, Merkle head, envelope signature) is OCU-authored and present on both shelves; logging integrity does not depend on the customer's choice of sink.
+- `NYDFS-500.06` / `DORA-Art.10`: the audit trail and its retention floor are machine-enforced on both shelves ([NFR-COMP-01](../manifesto/02-nfrs.md)); the WORM substrate satisfies the immutability expectation when the full-shelf seam is wired.
+- `EU-AI-Act-Art.12`: the record-keeping obligation is met by the mandatory core; the transparency-log endpoint is the customer's choice of public or private operator.
+
+## License impact
+
+None. No bus, store, SIEM, or transparency-log dependency is bundled by this decision; the reference defaults (embedded WAL, file-system sink, local Merkle head) are OCU code. Customer-provided substrates are integrated over their standard APIs.
+
+## Threat mitigation
+
+Addresses Tampering and Repudiation on the audit path: the chain of custody is authored before any record leaves the pipeline, so a record's integrity is independent of the pluggable sink, and the local durable commit holds RPO = 0 against a stalled or hostile downstream. Per-seam residuals — SIEM-bridge backpressure ([#150](https://github.com/Wide-Moat/open-computer-use/issues/150)) and the transparency-log publishing path ([#151](https://github.com/Wide-Moat/open-computer-use/issues/151)) — stay open.

package/docs/architecture/adr/0010-storage-backend-pluggable-adapter.md

@@ -0,0 +1,60 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-07
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, ISO27001-A.8.10]
+license-impact: none
+threat-mitigation-link: ../06-threat-model.md
+---
+
+The Storage broker owns the guest file-operation contract and drives the backend through a pluggable engine adapter — a local volume and an S3 store from day one — so the guest never sees the backend protocol and no engine is bundled for production.
+
+# ADR-0010: Storage backend is a pluggable adapter behind the broker
+
+## Status
+
+`proposed`
+
+## Context
+
+The Storage broker ([component 04](../components/04-storage-broker.md)) is the sole component that speaks the backend protocol and signs every backend request ([NFR-SEC-25](../manifesto/02-nfrs.md)); the guest holds only a `filesystem_id` handle and issues file-operation verbs that name no backend object (invariant 2). Which engine sits behind that signer was deferred — [component 04](../components/04-storage-broker.md) Shelf delta carried `needs ADR: object-store engine selection`, and the same question is phrased identically as an open item in [08-contracts.md](../08-contracts.md) §6 ([#208](https://github.com/Wide-Moat/open-computer-use/issues/208)): does the file-operation contract stay distinct from any object-store API at every shelf, and where is that boundary asserted.
+
+OCU is an ephemeral workspace ([04-non-goals.md](../manifesto/04-non-goals.md)): it retains the audit record of file activity, never the customer file bytes, so the engine carries no retention, WORM, versioning, or erasure duty — those belong to the customer's store. Under the build-scope principle ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)) an object store is a neighbouring system that runs when OCU is stopped.
+
+## Decision
+
+The broker drives the backend through a pluggable engine adapter behind its single object-store client: the guest↔broker file-operation contract is OCU-defined and stays distinct from the backend protocol at every shelf, a local-volume engine and an S3 engine are both present from day one, and no engine is bundled for production.
+
+## Consequences
+
+- **The two contracts stay distinct, and this closes [#208](https://github.com/Wide-Moat/open-computer-use/issues/208).** The guest↔broker contract is the OCU-defined file-operation interface (open/read/write/list over FUSE / virtio-fs / 9p, [08-contracts.md](../08-contracts.md)), deliberately POSIX-shaped, never the backend protocol. The boundary is asserted inside the broker's object-store client: invariant 2 ([component 04](../components/04-storage-broker.md)) — no caller request names a backend object directly — is the falsifiable statement of the split. The engine choice is the role `conform` backend leg ([08-contracts.md](../08-contracts.md)); the file-op mount is the role `define` surface.
+- Positive: swapping the engine changes neither the file-operation contract nor any of the broker's ten invariants ([component 04](../components/04-storage-broker.md)) — substrate and transport are component-spec choices, not contract. A later engine (e.g. a cloud object store) is a third adapter behind the unchanged contract, with the guest mount and the schema untouched.
+- Positive: the local-volume engine has no network leg, so the minimal shelf runs from one `docker-compose up` with no external object store and no cloud credential, holding the one-click-solo invariant ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)). The egress-transit invariant ([NFR-SEC-25](../manifesto/02-nfrs.md)) applies to a network engine's leg, not to the local-volume engine, which has nothing to transit.
+- Positive: production engines are customer-provided and not bundled — AWS S3, Ceph RGW (the reference object store in [05-licensing-posture.md](../manifesto/05-licensing-posture.md)), or any S3-compatible store. OCU owns no engine CVE, SBOM, or version lifecycle, mirroring [ADR-0009](0009-audit-pipeline-pluggable-by-contract.md)'s no-CVE posture.
+- Neutral: resolves the engine half of the [component 04](../components/04-storage-broker.md) Shelf-delta picks; the broker runtime tier is a separate concern, resolved in [component 04](../components/04-storage-broker.md) §Operational concerns at the [NFR-SEC-02](../manifesto/02-nfrs.md) hardened-`runc` floor (profile-independent, no tier ladder). Per-tenant instantiation ([NFR-SEC-76](../manifesto/02-nfrs.md)) and the credential substrate ([NFR-SEC-60](../manifesto/02-nfrs.md) / [NFR-SEC-25](../manifesto/02-nfrs.md)) are unchanged — both engines serve both shelves, differing only in whether the credential is a host filesystem permission (local volume) or a backend key (network engine).
+- Negative: the local-volume engine is durability/HA-naive (single host, no erasure coding) and is a solo-reference only; a production deployment wires the S3 engine to its own store. OCU makes no durability promise for the local-volume path.
+- Negative: the file-operation contract must carry chunked upload and Range read as first-class verbs so a large object never crosses as one message; this puts the size ceiling in the broker's chunk policy, not the engine, and obliges every adapter to translate chunking to the backend's transfer model.
+
+## Alternatives considered
+
+- **Make S3 the conformance target — the broker's contract is the S3 API, solo bundles an S3 server (the prior closed draft).** Rejected: inverts the canon topology — [component 04](../components/04-storage-broker.md) invariant 2 makes the guest speak a file-operation interface that names no backend object, and [08-contracts.md](../08-contracts.md) already separates the `define` mount leg from the `conform` backend leg. Collapsing them re-exposes the backend protocol guest-ward, contradicts [NFR-SEC-25](../manifesto/02-nfrs.md), and fails [#208](https://github.com/Wide-Moat/open-computer-use/issues/208) by denying the distinction it asks us to assert.
+- **Bundle a production engine (ship Ceph or MinIO and own its lifecycle).** Rejected: an object store is a neighbouring system that runs without OCU, so bundling it for production violates the build-scope principle ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)) and the durable-store non-goal ([04-non-goals.md](../manifesto/04-non-goals.md)), and takes on a CVE surface the customer's platform team already operates. MinIO's community edition is AGPL ([05-licensing-posture.md](../manifesto/05-licensing-posture.md) rejection table).
+- **Ship one engine (S3 only), add local-volume later.** Rejected: breaks the one-click-solo invariant ([03-non-negotiables.md](../manifesto/03-non-negotiables.md)) — the minimal shelf would require an external object store and a credential before the first session. The local-volume engine is what lets the solo path run with no external service, so both exist from day one.
+
+## Compliance impact
+
+- `SOC2-CC6.1` / `ISO27001-A.8.10`: backend-credential confidentiality holds because the broker is the sole backend-protocol speaker and the guest never receives a backend key; the engine choice does not change this property on either shelf.
+
+## License impact
+
+No production engine is bundled. The local-volume reference engine is OCU code over the host filesystem and pulls in no third-party dependency. Customer-provided engines are integrated over the backend protocol and carry no OCU lifecycle.
+
+## Threat mitigation
+
+Addresses Information Disclosure on the backend leg: the backend protocol terminates inside the broker's object-store client, the request is broker-signed, and a network engine's leg traverses the storage-dedicated lane on the egress edge allow-list-only without TLS termination ([NFR-SEC-25](../manifesto/02-nfrs.md), [ADR-0011](0011-storage-egress-lane.md)), so the signed request is byte-intact and no backend credential or endpoint reaches the guest. A local-volume engine opens no network leg, so the in-transit obligation is vacuous for it.

package/docs/architecture/adr/0011-storage-egress-lane.md

@@ -0,0 +1,67 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-07
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, ISO27001-A.8.10, NYDFS-500.15, DORA-Art.28]
+license-impact: none
+threat-mitigation-link: ../06-threat-model.md
+---
+
+The storage-backend leg is reached over a storage-dedicated lane on the Egress trust-edge — out-of-process from the broker, distinct from the guest egress lane — so detaching storage from the guest-egress policy class does not move the enforcement into the credential-holder.
+
+# ADR-0011: Storage backend reached over a storage-dedicated egress lane
+
+## Status
+
+`proposed`
+
+## Context
+
+A network backend engine's leg ([ADR-0010](0010-storage-backend-pluggable-adapter.md)) was routed through the same Egress trust-edge lane that governs the guest's LLM / internet egress ([NFR-SEC-25](../manifesto/02-nfrs.md), [08-contracts.md](../08-contracts.md) F9). Storage and guest-internet are different traffic classes with different authorization — file scope/intent/`downloadable` on one side, the upstream allow-list and credential injection on the other ([05-c4-container.md](../05-c4-container.md) §4) — yet a single shared lane cannot express a storage-specific policy without touching the guest lane. A local-volume engine has no network leg at all, so the shared-lane wording was over-broad for it.
+
+Two constraints bound where the storage leg's network enforcement can live. The broker holds the backend credential, so a control co-located inside the broker process dies with broker compromise (the confused-deputy path P4-E1 is already live) — strictly weaker than the status quo, where the enforcement is a separate container the broker cannot edit. And P4-E2 ([06-threat-model.md](../06-threat-model.md) §3) requires "no outbound path the control cannot see"; detaching from the guest lane must not re-open that hole.
+
+## Decision
+
+The broker-originated backend leg is reached over a storage-dedicated lane on the Egress trust-edge — a distinct policy lane, out-of-process from the broker, on the existing outbound-mediation container — not the guest-egress lane and not a control inside the broker. The broker holds the credential, signs once, and originates the leg; the lane forwards it allow-list-only with no TLS termination and enforces, where the broker cannot suppress it, the destination allow-list, the one proxy-owned resolver and its deny-set, the exfil tripwire, and an edge-authored OCSF event per backend operation ([NFR-SEC-85](../manifesto/02-nfrs.md)).
+
+## Consequences
+
+- The enforcement stays out-of-broker, so it survives broker compromise: a fully-compromised broker holds the credential but can neither relax the storage allow-list, nor silence the connect-time deny, nor suppress or backfill the edge-authored OCSF event — the property the shared-lane transit gave today, kept ([NFR-SEC-85](../manifesto/02-nfrs.md), closing the in-broker-control weakening).
+- P4-E2 holds equal-or-stronger. The leg is now a distinguishable policy class rather than an indistinguishable guest-egress lookalike, so the lane can express a storage-specific deny it could not before, while the count of outbound paths the control can see is unchanged — still one outbound-mediation container, with the direct broker-to-backend dial still forbidden ([NFR-SEC-16](../manifesto/02-nfrs.md)).
+- The one proxy-owned resolver is the sole resolution authority for both lanes ([NFR-SEC-12](../manifesto/02-nfrs.md)) — the storage lane shares it, it does not bring its own, so detaching the lane creates no second resolver and no second SSRF/rebind surface.
+- No new container. The storage lane is a second listener on the existing Egress trust-edge container, so the five-zone / six-container model ([05-c4-container.md](../05-c4-container.md) §1) is unchanged.
+- Positive: single-egress is single-egress-per-purpose ([NFR-SEC-05](../manifesto/02-nfrs.md), [NFR-SEC-16](../manifesto/02-nfrs.md)) — guest-internet / upstream-API on the forward-proxy lane, customer object storage on the storage lane, both deny-by-default and audited. The storage lane does no credential injection, no customer-CA bump, no edge ICAP — those are upstream-API-shaped and never applied to storage.
+- Positive: a local-volume engine ([ADR-0010](0010-storage-backend-pluggable-adapter.md)) opens no network leg, so the lane is vacuous for it; the minimal shelf holds the one-click-solo property unchanged.
+- Neutral: storage user-data content inspection runs at the broker on plaintext before signing ([NFR-SEC-81](../manifesto/02-nfrs.md)), since the lane is pass-through and sees only the broker-signed ciphertext — this is where the content-blind-storage residual ([#182](https://github.com/Wide-Moat/open-computer-use/issues/182)) is closed for storage.
+- Negative: in-transit confidentiality on the leg rests on the broker's own TLS to the backend ([NFR-SEC-25](../manifesto/02-nfrs.md) — the broker signs and originates the request), not on a shared-edge property; the broker must validate the backend certificate strictly and fail closed. P4-T2 in-transit confidentiality now rests on [NFR-SEC-25](../manifesto/02-nfrs.md) + [NFR-SEC-85](../manifesto/02-nfrs.md) (broker-originated TLS); [NFR-SEC-05](../manifesto/02-nfrs.md) stays guest-egress-scoped.
+
+## Alternatives considered
+
+- **Keep the storage leg on the shared guest-egress lane (the status quo before this ADR).** Rejected: storage and guest-internet are different traffic classes, so one lane cannot carry a storage-specific policy without touching the guest lane; the leg is also indistinguishable from guest egress for audit and deny purposes. Fails the separation the storage contour requires.
+- **Move the allow-list, resolver, tripwire, and OCSF emit into the broker (broker enforces its own exit).** Rejected: the broker holds the backend credential, so a control in the same process is defeated by broker compromise (P4-E1 confused-deputy is live) — strictly weaker than today's separate-container enforcement, and it re-opens the P4-E2 uncontrolled-exit hole. It would also stand up a second resolver, contradicting [NFR-SEC-12](../manifesto/02-nfrs.md).
+- **A dedicated storage-egress sidecar (own process, own resolver) in the Egress zone.** Rejected: a standalone process reads as a seventh container against the five-zone / six-container model ([05-c4-container.md](../05-c4-container.md) §1), and its own resolver violates the single-resolution-authority clause of [NFR-SEC-12](../manifesto/02-nfrs.md). A second listener on the existing edge delivers the same separation without either cost.
+
+## Compliance impact
+
+- `SOC2-CC6.1` / `ISO27001-A.8.10`: backend-credential confidentiality holds — the broker is the sole credential holder and the lane terminates no TLS, so no credential reaches the lane or the guest.
+- `NYDFS-500.15` / `DORA-Art.28`: the storage leg is a controlled, audited outbound path with an edge-authored event a compromised broker cannot suppress; third-party-storage access is governed and recorded.
+
+## License impact
+
+None. The storage lane is a listener configuration on the already-bundled outbound-mediation edge ([ADR-0006](0006-egress-forward-proxy-substrate.md)); no new dependency is introduced.
+
+## Threat mitigation
+
+Re-homes P4-D2 and P4-E2 ([06-threat-model.md](../06-threat-model.md) §3) off the shared single-egress wording onto the storage lane: the broker-signed leg traverses an out-of-broker enforcement point under a deny-by-default allow-list, the deny-set, the exfil tripwire, and an edge-authored OCSF event, so no outbound path the control cannot see exists by policy even under broker compromise. P4-T2 in-transit confidentiality re-anchors onto the broker-originated TLS ([NFR-SEC-25](../manifesto/02-nfrs.md) + [NFR-SEC-85](../manifesto/02-nfrs.md)), off the now guest-egress-scoped [NFR-SEC-05](../manifesto/02-nfrs.md).
+
+## Open questions
+
+1. Per-session backend byte / rate ceiling on the storage lane — resource-exhaustion theme, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188).
+2. Whether broker-side plaintext DLP on user-data is mandatory or per-deployment on the storage path — content-blind theme, [#182](https://github.com/Wide-Moat/open-computer-use/issues/182).

package/docs/architecture/adr/0012-implementation-language.md

@@ -0,0 +1,67 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-08
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: [future-architecture/adr/0001-control-plane-language-go, future-architecture/adr/0002-guest-agent-language-go]
+superseded-by: null
+compliance-impact: [SOC2-CC8.1]
+license-impact: none
+threat-mitigation-link: ../02-trust-boundaries.md#4-per-tenant-isolation-menu
+---
+
+Fixes the implementation language for each build target: Go for the host-side control and supervision processes, Rust for the in-sandbox guest agent. Audience: anyone writing or reviewing component code.
+
+# ADR-0012: Implementation language
+
+## Status
+
+`proposed`
+
+## Context
+
+No prior ADR in this set fixes an implementation language; the choice crosses every component (the guest agent, the host exec-supervisor, the Control / operator API) and is expensive to reverse once code lands.
+
+Two build targets sit in different trust zones with different constraints:
+
+- **Host-side control and supervision** — the Control / operator API ([component 02](../components/02-control-operator-api.md)) and the host exec-supervisor that the Session sandbox spec ([component 05](../components/05-session-sandbox.md)) places outside the guest. This grows into session lifecycle, quota, denylist, kill-switch, and (on the full shelf) k8s orchestration and cloud-provider integration. It is operated daily.
+- **The in-sandbox guest agent** — PID 1 inside the sandbox ([component 05](../components/05-session-sandbox.md)). It is the inner attack target: untrusted agent-issued code, prompt-injected agents, and compromised in-sandbox dependencies all reach it first. Its control-channel handler is a direct RCE target, and it ships inside every sandbox image.
+
+The two talk over a wire contract ([`exec/exec-channel.schema.json`](../../../contracts/exec/exec-channel.schema.json)), not shared memory, so they need not share a language.
+
+## Decision
+
+Host-side control and supervision processes are written in **Go**: the Control / operator API and the host exec-supervisor — the process that terminates the exec WebSocket, spawns and reaps guest processes, and strips the deny-pattern env set at fork ([component 05](../components/05-session-sandbox.md)). The in-sandbox PID-1 guest agent is written in **Rust**. The fork/exec boundary is the Go/Rust seam: the Go supervisor writes the spawn frame onto the exec channel; the Rust agent runs on the other side. The two share no runtime and no in-process state.
+
+## Consequences
+
+- The Go side gets the canonical k8s client (`client-go`), mature AWS and GCP SDKs, and goroutine-per-connection concurrency that fits the long-lived control and exec channels — the full-shelf orchestration path stays on the ecosystem built for it. Go is the language the project currently operates in; the maintenance surface carries no additional toolchain cost.
+- The Rust guest agent is a static-PIE binary on the RCE target: memory safety removes a bug class from the control-channel handler, the binary that ships in every image stays a few megabytes rather than ten-plus, and `tokio` fits the long-lived channel with bounded per-stream stdio (NFR-SEC-74). The cost is a second toolchain and a language the project is less fluent in — accepted because the guest surface is protocol-shaped (bounded schema, no ambient library surface), which is where that toolchain cost is lowest.
+- The exec-channel union ([`exec/exec-channel.schema.json`](../../../contracts/exec/exec-channel.schema.json)) is the single source for the wire types both sides build against; the Go host side and the Rust guest side each conform to it (generated or validated in CI, the carrier owned by [`08-contracts.md`](../08-contracts.md) §4), not by hand-maintained parallel definitions.
+- A Cargo workspace MAY share a wire-types crate across Rust binaries, but the guest agent and any host-side Rust helper compile to separate binaries; the guest binary ships inside the hostile rootfs and the host binaries never do.
+- Component specs record no language in their prose; this ADR is the single source. New source files carry the SPDX header in the comment syntax of their language.
+- This decision binds implementation only. It forces no Layer-6 container split and changes no contract, NFR, or trust boundary.
+- The "ships inside every image / rootfs" phrasing above describes where the agent *runs* (PID 1 in the hostile guest), not where it is *stored*: [ADR-0020](0020-sandbox-image-provisioning.md) fixes the agent as a runtime artifact injected at session-start, never baked into a sandbox image. The language choice here is unaffected.
+
+## Alternatives considered
+
+- **Go everywhere (including the guest agent).** One toolchain, one hiring story, `chromedp` available for later CDP work. Rejected for the guest agent: a garbage-collected ten-plus-megabyte binary on the per-image RCE target trades away the memory-safety class and the small-surface audit benefit for a code-sharing win that does not exist (the two sides talk over a wire contract, not shared code).
+- **Rust everywhere (including the control plane).** Smallest binaries, one memory-safety story. Rejected for the host side: the k8s client and cloud-provider SDKs are a fraction as mature in Rust as in Go, the control plane is the daily-operated surface where the project is most fluent in Go, and a control-plane-heavy codebase is where Rust's iteration friction is highest. Code the team cannot maintain confidently is a liability.
+- **Python (continue the PoC stack).** Zero migration from the current `main`-line server. Rejected: no static binary, a weaker k8s-controller story, and weaker type safety for a long-lived production service — the wrong base for a regulated-enterprise control plane.
+
+## Compliance impact
+
+| Control | Component | Evidence |
+|---|---|---|
+| SOC2-CC8.1 | all build targets | one recorded language per target → deterministic toolchain, SBOM surface, and supply-chain scan per artifact (this ADR) |
+
+## License impact
+
+None. Both toolchains and their standard libraries clear the licence gate ([`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md)): Go is BSD-3, Rust is MIT/Apache-2.0. Per-dependency gating is unchanged; this ADR adopts no library.
+
+## Threat mitigation
+
+The Rust guest agent narrows the in-sandbox RCE target's bug class on the boundary the threat model marks as the inner attack surface ([component 05](../components/05-session-sandbox.md) failure modes, reaching actor A1). Per-tier escape resistance and the per-release red-team gate stay governed by NFR-SEC-02; this ADR adds no requirement to either and substitutes for no isolation control — a memory-safe agent is not a substitute for the sandbox boundary.

package/docs/architecture/adr/0020-sandbox-image-provisioning.md

@@ -0,0 +1,82 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-16
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [DORA-Art.28, EU-AI-Act-Art.15, NIST-SP-800-190]
+license-impact: bundled-images
+threat-mitigation-link: null
+---
+
+Fixes which image a sandbox runs and how a customer supplies their own — the axis canon names nowhere. Audience: anyone touching the Session sandbox rootfs, the control-plane admission path, or the Bill of Materials.
+
+# ADR-0020: Sandbox image provisioning
+
+## Status
+
+`proposed` — **stub**. Context and the axis are fixed; the Decision is held open behind the owner rulings and open questions below. This ADR does not leave draft until those close.
+
+## Context
+
+[Component 05](../components/05-session-sandbox.md) and [ADR-0003](0003-sandbox-runtime-tier-ladder.md) specify the sandbox's runtime *security* and *isolation* exhaustively, but nothing specifies what **image** runs inside it or how a customer brings their own. The gap already leaks: NFR-FS-01/02 say "per-template", yet [`glossary.md`](../glossary.md) defines no `template` or `image` term (a one-source-of-truth break). A regulated buyer cannot adopt a fixed Ubuntu blob — their InfoSec mandates a hardened base, their workloads need different toolchains, and air-gap forbids any phone-home pull. "Bring your own image" is therefore a deal-requirement, not a convenience, and — unlike the agent loop ([04-non-goals](../manifesto/04-non-goals.md)) — a sandbox without an image cannot be a non-goal.
+
+Two axes are in play and must not collapse into one: **image-fatness** (what is *in* the box) and the **runtime tier** (what *isolates* the box, fixed by [ADR-0003](0003-sandbox-runtime-tier-ladder.md) — runc/gVisor/microVM). ADR-0003 scopes itself to the runtime-tier ladder only; the image-fatness axis is this ADR's to fix. The [ADR-0012](0012-implementation-language.md) Rust static-PIE guest agent is not part of any image — it is part of the runtime, injected into every image at start, so an image carries only its userland. A bundled image is a release artifact carrying full CVE/SBOM/SLSA/RoI responsibility ([05-licensing-posture](../manifesto/05-licensing-posture.md)).
+
+## Decision
+
+**TBD.** The shape below is the owner's locked input; the load-bearing choices stay open (see Open questions). The ADR records the direction, not yet the decision.
+
+Owner rulings (authoritative, not relitigated):
+
+1. **One materialize path for every image.** There is no "OCU image" versus "BYO image" as two modes. An image (an OCU-prebuilt rung or a customer base) is given → OCU appends its runtime layers → OCU starts it. The agent is part of the runtime, never baked into an image; the prebuilt rungs are a shelf of convenient agent-less userlands that flow through the same pipe as a customer image. `FROM-min-base` as a second path is rejected — it reintroduced the duality.
+2. **Injection is an appended OCI layer, not a bake or a synthetic file.** OCU appends the runtime as standard OCI layers over the base (`mutate.AppendLayers`-style), leaving the base image byte-unmutated — the common-tooling path, not a microVM/FUSE-specific synthetic-file scheme. Two static (no-libc) binaries ride these layers: the control agent (PID 1) and the `ocu-rclone-filestore` mount binary the agent starts; the mount binary needs `/dev/fuse` + `SYS_ADMIN` from the runtime.
+3. **Image-fatness is a named axis orthogonal to the [ADR-0003](0003-sandbox-runtime-tier-ladder.md) runtime tier**, exposing a four-rung shelf — `min`, `medium` (+ userland, no browser), `high` (+ Chromium + CDP), `xhigh` (+ Claude Code CLI as an on-rootfs binary) — plus customer **BYO** through the identical path.
+4. **All four rungs are bundled.** OCU builds, signs, and owns the CVE/SBOM/SLSA/RoI of every rung, including Chromium and the Claude Code CLI. There is no customer-overlay tier.
+5. **Provenance is two-signature and uniform.** The image (OCU's or the customer's) carries its own signature OCU verifies; the agent carries OCU's signature, the same known binary every time. Admission verifies the two separately; the per-session provenance record, not a merged-rootfs signature, is the system of record.
+6. **Injection is covered by a merge-blocking test matrix.** A CI gate proves agent-as-PID-1, mount-comes-up, base-image-byte-unmutated, two-signature verification, and the NFR-SEC-14 posture across substrate × image-rung × BYO; negative cells (unsigned base, missing `/dev/fuse`/`SYS_ADMIN`) must fail closed. Carried as an NFR row, not restated here.
+
+Provisioning is a **role on the existing control plane** ([component 02](../components/02-control-operator-api.md)) — selection, admission validation, materialization — not a new component or deployable; it is the session-create step *before* the mount-config push. The runtime tier stays the deployment-wide knob, never a field on the image request.
+
+## Consequences
+
+- Positive: one materialize path means identical sandbox behaviour for a prebuilt rung and a customer base — no "worked on ours, broke on theirs" class; a hardened-base BYO path becomes expressible; the `min`/`medium` floor preserves the one-click solo shelf (a Chromium critical rebuilds `high`/`xhigh` only).
+- Negative: bundling all four rungs puts OCU on the Chromium release cadence under the NFR-MAINT-01 patch SLA (≤7d for CVSS ≥9.0) — `xhigh` (CLI + Chromium) sets the release cadence and is the most expensive artifact to keep in SLA.
+- Neutral: image provisioning consumes a pre-built OCI artifact read-only; OCU runs no session-time registry-push build (unlike the E2B template-manager model).
+- Affects [component 02](../components/02-control-operator-api.md) (admission role), [component 05](../components/05-session-sandbox.md) (agent injected as PID 1, not image-borne), [05-licensing-posture](../manifesto/05-licensing-posture.md) (bundled BoM rows), [glossary.md](../glossary.md) (two new terms).
+- Per-substrate boot/materialize mechanics (runc, gVisor, Firecracker, Docker-compose, Kubernetes) are an internal design detail of components 02/05, not ADR Decision text.
+
+## Alternatives considered
+
+- **Customer-overlay for high/xhigh** (OCU ships only the recipe) — rejected by owner ruling 4; OCU owns all CVE/RoI instead.
+- **Two paths — agent baked in OCU images, injected only for BYO** — rejected: two behaviours is two bug surfaces ("worked on ours, broke on theirs"); the agent is part of the runtime and injected uniformly, so `FROM-min-base` as a second path is dropped.
+- **Synthetic FUSE file for the agent** (microsandbox `init.krun`-style) — rejected as the primary mechanism: microVM/FUSE-centric, not common OCI tooling; the appended-OCI-layer path works on every substrate. May resurface as a microVM-tier option only.
+- **Fold image-fatness into ADR-0003** — rejected: ADR-0003 selects the isolation boundary; conflating it with what-is-in-the-box collapses two independent axes.
+- **Build-from-image at session time** (E2B template-manager) — rejected: OCU consumes a pre-built signed OCI artifact read-only; no session-time build surface.
+
+## Compliance impact
+
+- `DORA-Art.28`: each bundled rung carries a Register-of-Information row (the Chromium and Claude Code CLI fourth-party entries are OCU's once bundled).
+- `EU-AI-Act-Art.15`: the image is part of the agent-execution boundary; SBOM/provenance per rung is the cybersecurity evidence.
+- `NIST-SP-800-190` §3: image provenance, digest-pinning, and signature verification at admission.
+
+## License impact
+
+`min` and `medium` enter the Bill of Materials in [`05-licensing-posture.md`](../manifesto/05-licensing-posture.md) as bundled images; `high` (Chromium) and `xhigh` (Claude Code CLI) add bundled rows whose CVE/RoI OCU owns. The Claude Code CLI must clear the dependency licence gate before its row lands — not yet verified.
+
+## Threat mitigation
+
+Not threat-driven. The admission floor (image digest-pin, cosign-verify image and the injected agent against offline-bundle keys, agent-version-match on the injected runtime binary, arch match, runtime-tier match) attaches to NFR-SEC-16/18/38 once the Decision lands. The agent's presence is not checked on the image — OCU injects its own known binary every time.
+
+## Open questions
+
+1. Ship `medium` bundled, or bundle `min` only and treat `medium` as the first heavier rung? Bundling `medium` is an ongoing CVE commitment (CPython/OpenSSL/glibc churn under NFR-MAINT-01). — owner ruling needed, track issue.
+2. BoM rows for `high`/`xhigh`/Chromium/Claude-Code-CLI do not exist in [`05-licensing-posture.md`](../manifesto/05-licensing-posture.md); the CLI's licence-gate result is unverified. — must land before this ADR cites them, track issue.
+3. Agent injection on Firecracker writes into a freshly-built ext4 with no content-addressed layer identity; OCU signs the final template. Confirm the two-signature record (image + agent) covers the converted artifact. — track issue.
+4. Does `image_tier`/`image_ref` ride the existing gateway→Control session-setup RPC as additive fields, or warrant a typed surface in [08-contracts](../08-contracts.md) §1? — confirm with contracts owner.
+5. FIPS-140-3 variant per bundled rung (NFR-SEC-28) doubles the bundled evidence set (min/medium × default+FIPS). — release-pipeline scope decision, track issue.
+6. The merge-blocking injection test-matrix gate (ruling 6) is not yet an NFR row in [`02-nfrs.md`](../manifesto/02-nfrs.md); the FUSE-under-gVisor and `/dev/fuse`-in-Firecracker mount cells need proving, not assuming. — land the NFR row + CI gate, track issue.

package/docs/architecture/adr/README.md

@@ -0,0 +1,53 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: stub
+last-reviewed: 2026-06-06
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Architecture Decision Records. One file per decision. ADRs appear on demand following the decision tree in `CLAUDE.md`; no bulk-creation of empty stubs.
+
+## Template
+
+[`0000-template.md`](./0000-template.md) — copy when starting a new ADR.
+
+## Index
+
+| Number | Title | Status | Supersedes | Last-reviewed |
+|---|---|---|---|---|
+| [0001](0001-layer-0-gate-legacy-exclusion.md) | Layer 0 gate — legacy exclusion | accepted | — | 2026-05-24 |
+| [0002](0002-session-view-descriptor.md) | Session view is descriptor-driven | proposed | — | 2026-06-01 |
+| [0003](0003-sandbox-runtime-tier-ladder.md) | Sandbox runtime tier ladder | proposed | — | 2026-06-01 |
+| [0004](0004-operator-authentication-substrate.md) | Operator authentication substrate | proposed | — | 2026-06-01 |
+| [0005](0005-egress-credential-delivery-envoy-sds.md) | Egress credential delivery is off-the-shelf Envoy SDS | proposed | — | 2026-06-01 |
+| [0006](0006-egress-forward-proxy-substrate.md) | Egress forward-proxy substrate | proposed | — | 2026-06-01 |
+| [0007](0007-egress-auth-mechanism.md) | Egress auth mechanism — edge-inject vs protocol-broker | proposed | — | 2026-06-01 |
+| [0008](0008-session-egress-attribution.md) | Session-to-egress attribution by presented token | proposed | — | 2026-06-02 |
+| [0009](0009-audit-pipeline-pluggable-by-contract.md) | Audit pipeline is pluggable-by-contract | proposed | — | 2026-06-06 |
+| [0010](0010-storage-backend-pluggable-adapter.md) | Storage backend is a pluggable adapter behind the broker | proposed | — | 2026-06-07 |
+| [0011](0011-storage-egress-lane.md) | Storage backend reached over a storage-dedicated egress lane | proposed | — | 2026-06-07 |
+| [0012](0012-implementation-language.md) | Implementation language — Go host-side, Rust guest agent | proposed | legacy 0001/0002 | 2026-06-08 |
+| [0020](0020-sandbox-image-provisioning.md) | Sandbox image provisioning (image-fatness ladder + BYO) — stub | proposed | — | 2026-06-16 |
+
+## Lifecycle
+
+`proposed` → `accepted` (on PR merge) → `superseded` (when replaced by a later ADR; both files cross-link via front-matter).
+
+`deprecated` is for decisions that no longer apply but were not superseded by a specific replacement.
+
+## ADR threshold
+
+An ADR is for decisions that are:
+
+- **Load-bearing** — other components rely on this being decided one way.
+- **Hard to reverse** — undoing it costs more than a typical refactor.
+- **Cross-component** — affects at least two components or boundaries.
+
+Decisions that don't meet the bar belong inline in the relevant component spec. See `CLAUDE.md` decision tree §3 for the test.
+
+## Hard cap
+
+Each ADR ≤ 200 lines. If it doesn't fit, the decision is too big — split it.

package/docs/architecture/components/00-overview.md

@@ -0,0 +1,42 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-03
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Index of the `components/` directory: one spec slot per Layer 6 container, its spec status, and the decisions and contracts already bound to it. Audience: an engineer about to open or write a component spec.
+
+## 1. Index scope
+
+Layer 6 ([`05-c4-container.md`](../05-c4-container.md) §3) is the source of truth for what each container does; this index does not restate it — it records where each is specified and what already binds it.
+
+A spec is added per [PROCESS.md](../PROCESS.md): open an issue, create `components/NN-<name>.md` from [`0000-template.md`](0000-template.md) at `status: stub`, discuss in the PR. The number `NN` is the container's row order below; it is assigned here and does not change once given.
+
+## 2. Container specs
+
+Each row links the container's responsibility (Layer 6) and lists the spec file, its current status, and the ADRs and contracts that already bind it. `—` in the Bound ADRs column means no ADR binds the container yet; opening one is its own PR. `NN` is the container row identifier — there is no `03`, the set is the six containers of [`05-c4-container.md`](../05-c4-container.md) §3, and the number does not track a trust zone (the Session sandbox is container 05, trust zone 3).
+
+| NN | Container | Spec | Status | Bound ADRs | Bound contracts |
+|---|---|---|---|---|---|
+| 01 | MCP gateway (agent-facing) | [`01-mcp-gateway.md`](01-mcp-gateway.md) | draft | — | [`mcp/ocu-constraints`](../../../contracts/mcp/2025-06-18/ocu-constraints.schema.json) |
+| 02 | Control / operator API | [`02-control-operator-api.md`](02-control-operator-api.md) | draft | [0004](../adr/0004-operator-authentication-substrate.md) | — |
+| 04 | Storage broker | [`04-storage-broker.md`](04-storage-broker.md) | draft | [0002](../adr/0002-session-view-descriptor.md), [0010](../adr/0010-storage-backend-pluggable-adapter.md), [0011](../adr/0011-storage-egress-lane.md) | [`storage/mount-config`](../../../contracts/storage/mount-config.schema.json), [`storage/file-ops`](../../../contracts/storage/file-ops.schema.json), [`storage/file-artifact-api`](../../../contracts/storage/file-artifact-api.schema.json) |
+| 05 | Session sandbox `[1..N]` | [`05-session-sandbox.md`](05-session-sandbox.md) | draft | [0003](../adr/0003-sandbox-runtime-tier-ladder.md) | [`exec/exec-channel`](../../../contracts/exec/exec-channel.schema.json) |
+| 06 | Egress trust-edge proxy | [`06-egress-trust-edge.md`](06-egress-trust-edge.md) | draft | [0005](../adr/0005-egress-credential-delivery-envoy-sds.md), [0006](../adr/0006-egress-forward-proxy-substrate.md), [0007](../adr/0007-egress-auth-mechanism.md), [0008](../adr/0008-session-egress-attribution.md) | — |
+| 07 | Audit pipeline | [`07-audit-pipeline.md`](07-audit-pipeline.md) | draft | [0009](../adr/0009-audit-pipeline-pluggable-by-contract.md) | [`audit/audit-fanin`](../../../contracts/audit/audit-fanin.asyncapi.yaml) |
+
+The guest agent is the process that constitutes the Session sandbox container ([`05-c4-container.md`](../05-c4-container.md) §3), not a separate row; its protocol is specified inside `05-session-sandbox.md`.
+
+## 3. Maturation order
+
+All six are at `draft`. The ones a contract or a pending decision already pins harden to `proposed`/`accepted` first, because their spec has the least free design left and the most to verify against:
+
+1. **Storage broker** — three contracts and seven NFR anchors already fix its surface; the spec records the two-face component split and the per-tenant instantiation question ([#175](https://github.com/Wide-Moat/open-computer-use/issues/175)).
+2. **Session sandbox** — the exec-channel contract fixes its machine edge; the runtime-tier-by-`workload_trust_profile` decision is fixed by [ADR-0003](../adr/0003-sandbox-runtime-tier-ladder.md) and the sub-container split is open ([#174](https://github.com/Wide-Moat/open-computer-use/issues/174)).
+3. **Egress trust-edge** — no built contract yet, but the deny-reason and egress-wide-bump behaviour are NFR-anchored and cross the broker boundary; the auth mechanism is fixed by [ADR-0007](../adr/0007-egress-auth-mechanism.md) (edge-inject in v1), the substrate is Envoy plus a self-hosted SDS minting service, and the upstream credential arrives over Envoy SDS.
+
+The other three reach `accepted` once these three settle their shared invariants and the ADRs their `adr:` keys cite ([ADR-0003](../adr/0003-sandbox-runtime-tier-ladder.md) runtime tier, [ADR-0004](../adr/0004-operator-authentication-substrate.md) operator-auth, [ADR-0010](../adr/0010-storage-backend-pluggable-adapter.md) object-store engine) move from `proposed` to `accepted`.

package/docs/architecture/components/0000-template.md

@@ -0,0 +1,50 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: stub
+last-reviewed: YYYY-MM-DD
+owner: "@github-handle"
+applies-to: next/v1
+compliance: []
+threat-model: null
+contract: null
+adr: []
+---
+
+Template for a component specification, used by `next/v1` engineers when adding a new component to the architecture.
+
+# Component-NN: <name>
+
+## Purpose
+
+One sentence: what role does this component play, and for whom? No marketing tone.
+
+## Boundaries
+
+What crosses in, what crosses out, what state does this component own.
+
+| Direction | What | From / to | Protocol |
+|---|---|---|---|
+
+If the table has fewer than three rows, use prose.
+
+## Invariants
+
+The rules this component upholds, independent of its caller. Each invariant is enforceable by a test.
+
+## Failure modes
+
+What can go wrong, how it manifests, what the recovery contract is.
+
+## Operational concerns
+
+Configuration, observability, scaling axis, capacity model, upgrade discipline. Cite the relevant ADRs.
+
+## Open questions
+
+Capped at 5. Each entry links to a GitHub issue. If you hit 6, either resolve one or promote it to an ADR.
+
+---
+
+Hard cap: 600 lines. Sections appear in this fixed order. No additional H2 headings outside this list.