Architecture decision records
Decisions that shape what Gesso is, rather than how one part of it works. A change that contradicts an accepted ADR needs a new ADR that supersedes it, not just a pull request.
| ADR | Status | Date | Decision |
|---|---|---|---|
| 0001 — Align the v2 technical identity with Gesso | Accepted | 2026-07-13 | Namespace, package, and CLI rename to the Gesso identity, with the scope boundaries the rename did not authorize. |
| 0002 — Phase Arazzo workflow execution behind shared runtime expressions | Accepted, amended 2026-10-13 and 2026-10-26 | 2026-07-30 | Arazzo support lands in phases, starting from a runtime-expression evaluator shared with the existing validators. Amendments: embedded non-scalar runtime-expression values stay rejected until #430; the workflow runner moves to a separate package while the evaluator stays in the core. |
| 0003 — Branch-complete response payloads and an SDK round-trip harness | Accepted | 2026-07-31 | Close the SDK ⇄ spec gap by feeding spec-derived payloads through a generated decoder. |
| 0004 — v3 consistency policy and protected core | Accepted, amended 2026-08-12; partly superseded by 0007 | 2026-08-06 | v3 changes shape, not capability: the invariants that may not regress, the inclusion criterion and its non-goals, and the rule a reduction PR is held to. Amendments: the #508 exception; the sequencing rule that the final v2 minors carry the adopter-visible value while v3.0 deletes; and the condition — not a date — that opens the v3.0 window. |
| 0005 — v3 configuration and CLI naming | Accepted | 2026-08-06 | Resolves the naming conflicts between the four v3 rename issues, and fixes the gesso.php key set and the coverage:merge flag set they all target. |
| 0006 — Server base paths and request-path matching | Accepted; sections 1 and 4 superseded by 0008 | 2026-08-07 | servers[].url stays out of path matching; strip_prefixes remains authoritative, and a failed match names the server base path that would have matched. |
| 0007 — v3 scope and release window | Accepted, amended 2026-11-15 | 2026-10-26 | Lets v3 add capability, change verdicts toward spec agreement, and remove surfaces with a shipped deprecation plus evidence, and replaces ADR 0004's v1-EOL floor and trigger with release gates. Supersedes ADR 0004's Decision section and its 2026-08-07 and 2026-08-12 amendments. |
| 0008 — Server base paths in request-path matching | Accepted | 2026-11-05 | v3 matches the base paths the spec's servers declare: the path as written first, then each base path verified against the template's effective servers; disagreeing base paths fail loudly, and a non-empty strip_prefixes turns them off. Supersedes ADR 0006 sections 1 and 4. |
Writing one
Follow the most recent file. The header carries Status, Date, Issue, and Related; 0004 adds Supersedes, which every later ADR should carry even when the value is none. Number files sequentially and add the row above in the same change, so this page never lags the directory.