decisions: reconcile all areas

MI
8h ago
+814-0

Adds docs/decisions/, the Current Decisions pages of this repository. Each page lists the design decisions of one functional area that hold today, with stable area-prefixed IDs, their deciders, the spec they come from, and what a check of the code found. The pages keep only choices that a reader of the code would likely get wrong. Smaller decisions, decisions whose reason the code already states, and decisions that a spec replaced while it was drafted stay in their specs and are counted on each page's "Not shown" line.

Areas

Each area has a three-letter prefix, and its decision IDs count from 001. Area owners, please check your prefix.

  • Artifact CAS (CAS, owner @migmartri): CAS-001 to CAS-008. Existence cache store, location, and tenant key, credentials kept in process, and the browser download cache (Authorization header, existence check before 304).
  • Attestation Process (ATT, owner @migmartri): ATT-001, ATT-003, ATT-004. Organization order with .chainloop.yml, one reader shared with Trace, and the API token check. Non-Confirmed: ATT-002, because attestation verify does not read the file yet (#3063 is open).
  • Authentication (AUT, owner @migmartri): AUT-001 to AUT-007. Handoff code exchange, S256 binding, code store with no token at rest, opt-in detection, legacy ?t= handling in the CLI, uniform exchange errors, and a gRPC-only exchange endpoint.
  • Service Operations (OPS, owner @migmartri): OPS-002 to OPS-005. Separate metrics and profiler ports, TLS on the shared endpoint, the HTTP port as the shared endpoint, and multiplexing in the server process. Non-Confirmed: OPS-001.
  • Chainloop Trace (TRC, owner @jiparis): TRC-001 to TRC-039. Spec capture, skills, transcript pointers, pasted images, local mode, the e2e matrix, line attribution, and the Pi and Codex providers. Non-Confirmed: TRC-019 and TRC-028.

Open conflicts

  • Service Operations: issue-3628-controlplane-http-dispatch D-003 (OPS-001) and issue-3628-single-endpoint D-020 disagree about the CAS transport, and neither has a "replaces" note. The code follows D-020. Proposed: a spec change that records D-020 as the replacement.
  • Chainloop Trace: issue-3515 D-009 (TRC-003) and issue-3569 D-004 (TRC-019) disagree about whether the agent captures pasted images. The instructions follow TRC-003. Proposed: a spec change that records the current rule.
  • Chainloop Trace: issue-3635 D-011 (TRC-028) plans a nightly e2e run, but no workflow runs the suite. Proposed: a spec change that drops the nightly run.

No conflict was on a page before this change, because the pages are new.

One point for the Trace owner: TRC-029 says that the e2e suite pins the agent versions. The suite does not install the agents. It only warns when the installed version is different, so the pin is not enforced.

Each area owner approves the area map entry and prefix, the key decision cut, and the Language section of their area.

AI disclosure: Claude Code assisted with this change. It ran the eng-adr reconcile, checked each decision against the code, and drafted the pages. A person approved the area map, the cut, the Language sections, and the conflict proposals.