Repository navigation
ADR trim: ADRs hold decisions, not details #182
Copy link
Copy link
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Milestone
Description
What
Trim every ADR to its decision, context, trade-offs, consequences and reversal triggers, and move
details (step order, constants, timeouts, class names, platform tables, dated evidence) to the
canon that owns them. The test for each sentence: would changing it reopen the decision? If not, it
is a detail.
- ADR-0025 to ADR-0032. Re-audit against current master, give every detail without a canon
home one first, then trim. Known stale statements:- ADR-0026:22-24 calls its interop "the first platform interop in the shipped SDK" that "binds
one function of the C library"; - ADR-0028:84 says a related print is "tracked separately (issue Response envelopes print the raw error body in ToString #100)", and Response envelopes print the raw error body in ToString #100 is closed;
- ADR-0032 carries Windows divergence rows, while ADR-0031 puts divergence lists in canon.
- ADR-0026:22-24 calls its interop "the first platform interop in the shipped SDK" that "binds
- ADR-0001 to ADR-0023. Audit the same way, then trim. Known items:
- ADR-0001:31-32 still plans .NET 11
ReadAllLinesAsyncandKillOnParentExitas light-up,
which ADR-0032's Target frameworks section contradicts; - ADR-0008:34-35 says the transport-owned fingerprint hashes "transitive schemas", while
tools/OpenCode.Sdk.Tools/Generator/Binding/TransportOwnedFingerprint.cs:17-22identifies
referenced components by name only; - ADR-0021's
Date:against its revised Scope section (documentation.md:49defines what the
date means).
- ADR-0001:31-32 still plans .NET 11
Also write the process-primitive order (the BCL first, then a faithful Polyfill backport, then the
SDK's own code) into canon; today only ADR-0032 applies it (:59-61).
Why in 1.0
The ADRs are the decision record of the 1.0 surface, and details inside them go stale with every
change; the statements above are examples. The trim is in scope for 1.0 by the maintainer's
decision.
Evidence
docs/engineering/documentation.md:15(ADRs hold decision rationale) and:34(documentation
refactors are lossless relocations).- The lines cited above. The longest ADRs today: ADR-0011 (136 lines), ADR-0027 (97), ADR-0032
(96), ADR-0028 (87).
Done when
- ADR-0025 to ADR-0032 are re-audited and trimmed, and each relocated fact has exactly one canon
owner. - ADR-0001 to ADR-0023 are audited and trimmed.
- The stale statements above are gone. ADR-0008's fingerprint wording matches the implementation,
or the fingerprint walks referenced schemas if the reachable-schema checks turn out not to cover
them. - No useful unique information is lost.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Type
Projects
- StatusShow more project fieldsQueue
Activity
Blind-Striker commentedon Oct 14, 2026
One more stale row for this trim.
docs/adr/0032-launcher-places-and-ends-its-server-on-platform-primitives.md:46still lists the "Exit report" divergence: the launcher reports the root's exit as soon as it is observed.OpenCodeServer.Exited(#174, PR #231) now completes once the output has ended, or one second after the exit, as upstream'sexiteddoes. The canonical divergence tables inclient-runtime.mddrop the row in #231; the ADR row goes with this trim. Found independently by a second review of #231 and by the Surface lane.