Skip to content

ADR trim: ADRs hold decisions, not details #182

Open

Description

@Blind-Striker

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.

  1. ADR-0025 to ADR-0032. Re-audit against current master, give every detail without a canon
    home one first, then trim. Known stale statements:
  2. ADR-0001 to ADR-0023. Audit the same way, then trim. Known items:
    • ADR-0001:31-32 still plans .NET 11 ReadAllLinesAsync and KillOnParentExit as 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-22 identifies
      referenced components by name only;
    • ADR-0021's Date: against its revised Scope section (documentation.md:49 defines what the
      date means).

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.

Activity

  1. added this to the 1.0 milestone on Oct 14, 2026
  2. Blind-Striker commented on Oct 14, 2026

    @Blind-Striker
    CollaboratorAuthor

    One more stale row for this trim. docs/adr/0032-launcher-places-and-ends-its-server-on-platform-primitives.md:46 still 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's exited does. The canonical divergence tables in client-runtime.md drop the row in #231; the ADR row goes with this trim. Found independently by a second review of #231 and by the Surface lane.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions