Restructure ADRs into short decision records

Purpose

ADRs must record decisions, not implementations. Today docs/adr/ has 33 ADRs and 689 KB. Several ADRs are 40–94 KB and mix the decision with file maps, measurements, rollout plans, and amendment history. Contributors and agents cannot find the current decision quickly, and the implementation detail gets stale.

Required behavior

Add docs/adr/FORMAT.md with the authoring rules. Give it its own byte budget in the agent-guidance test.
Split the AGENTS.md route: "Read architecture decisions" goes to docs/adr/README.md. "Write or amend an ADR" goes to docs/adr/FORMAT.md.
Write an ADR only if the decision is hard to reverse, surprising without context, and the result of a real trade-off.
An ADR contains the decision (API, data flow, invariants, constraints, boundaries), why, the rejected alternatives with reasons, and the consequences and open gaps. Exact names (commands, wire fields, typed reasons) stay when they explain the decision.
An ADR does not contain implementation inventories, measurements, rollout or migration plans, PR logs, or status change-logs. Each moves to its owner: registries, types, and gates; package docs and help; docs/evidence/; or an umbrella issue.
An ADR is a living record. The decision states the current truth. An optional dated "Decision history" line records a real change of direction, with its reason and a link. A new ADR is written only when the problem or the scope changes.
Proposals live in umbrella issues. An ADR is written when a decision is accepted.

Completion conditions

Each ADR has one classification: keep, merge, move to evidence, or convert to an issue.
Each kept decision is checked against the code. If the code changed for a good reason, the ADR states the new decision and its reason. If the code drifted by mistake, an issue records it.
Each PR has a migration ledger: old section → kept, moved to a named owner, or deleted with a reason.
Each PR updates the code comments that cite the ADR sections that it changes.
A size gate (about 8 KB for each ADR) runs last, with no allowlist.

Dependencies

Blocked by docs(adr): write ADRs 0001–0011 and 0013–0017 in ASD-STE100 #3729, docs(adr): write runtime and architecture ADRs in ASD-STE100 #3731, and the stale-facts PR that stacks on them.

Decision: classification of the ADRs (maintainer, 2026-10-16).

Delete the Proposed ADRs 0018 (unified event journal), 0020 (composable recorded fragments), and 0028 (capability cell vocabulary). Create no issue for them. Git history keeps their text.
ADR 0024 (screen recording): move its implemented decisions to an accepted record. Track the remaining work in its own umbrella issue. Then delete the proposal.
ADR 0023 (hop trace): move to docs/evidence/. It is a measurement, not a decision.
ADR 0033 (collocation table): move the placement audit to docs/evidence/. Keep only a general decision, if one passes the three-condition test.
ADR 0003 (daemon command registry): merge into ADR 0008 (command descriptor registry). ADR 0003 becomes a short redirect.
ADRs 0022 (coupling audit) and 0027 (closure budget): move the audits and tables to docs/evidence/. Merge their lasting decisions into ADR 0019.
Keep the other ADRs, after a check that each decision still holds.
Use PRs of one to three related ADRs. Start with a pilot on ADR 0003/0008 and ADR 0012.

Decision: results of the ADR decision audit (maintainer, 2026-10-16).

Four read-only audits checked each decision of each kept ADR against the code at bd4fd688e7. About 33 differences are deliberate: the ADR text follows the code, with one dated "Decision history" line when the direction changed. These differences are real drift, and the code gets fixed:

ADR 0019: binding cleanup runs after the execution lock is released. The lock must cover the cleanup.
ADR 0012: a healed script drops snapshots that the author wrote and --record corrections.
ADR 0031: a macOS screenshot can capture the largest window instead of the front window. Refuse with a typed error.
ADR 0025: panel identity can come from array order when no panel is primary. Refuse with a typed error.
ADR 0012: replay suggestions do not rank candidates in the same scroll region first.
ADR 0010: the SDK lease client throws a bare Error.
ADR 0033: two internal barrels in packages/daemon/src/sessions/.
ADR 0022: the R75 gate message offers an ADR approval that the gate does not have.

Text-only drift (ADRs 0007, 0011, 0012, 0025) is corrected in the restructure.

ADR 0012 splits into about five short ADRs, one for each independent decision: no unattended selector rewriting; resolution disclosure; portable target identity; resume and divergence; repair ownership. Each contract that lives only in ADR 0012 gets an owner before it leaves the ADR.

The classification in the first Decision: comment still fits: every kept ADR passes the three-condition test.

Current state: 2026-10-16.

Merged:

docs(adr): write the replay ADR and proposed ADRs in ASD-STE100 #3730: ADR 0012 and the Proposed ADRs 0018, 0020, 0024, 0028 in ASD-STE100.

Open, ready for review:

docs(adr): write ADRs 0001–0011 and 0013–0017 in ASD-STE100 #3729: ADRs 0001–0011, 0013–0017 in ASD-STE100.
docs(adr): write runtime and architecture ADRs in ASD-STE100 #3731: runtime and architecture ADRs in ASD-STE100.
fix(daemon): retain cleanup locks and preserve healed snapshots #3760: drift fixes for ADR 0019 (the execution lock covers binding cleanup) and ADR 0012 (healed scripts keep authored snapshots and --record corrections).
fix(apple): refuse captures whose window or panel identity is unknown #3761: drift fixes for ADR 0031 (front-window screenshot or typed refusal) and ADR 0025 (no panel identity from array order). Needs a live check: macOS with Screen Recording permission, and an iOS 27.1 iPhone Duo.
fix: align replay, SDK, and session boundaries with ADRs #3762: drift fixes for ADRs 0012, 0010, 0033, and 0022.

Ready, not opened:

docs/adr-stale-facts: 21 stale facts in ADRs and code comments. It opens after docs(adr): write ADRs 0001–0011 and 0013–0017 in ASD-STE100 #3729 and docs(adr): write runtime and architecture ADRs in ASD-STE100 #3731 merge.

Next step: after #3729, #3731, and the stale-facts PR merge, add docs/adr/FORMAT.md and the two AGENTS.md routes. Then start the pilot on ADR 0003/0008 and the split of ADR 0012.

Navigation Menu

Repository navigation

Restructure ADRs into short decision records #3744

Purpose

Required behavior

Completion conditions

Dependencies

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Restructure ADRs into short decision records #3744

Description

Purpose

Required behavior

Completion conditions

Dependencies

Activity

thymikee commented on Oct 16, 2026

thymikee commented on Oct 16, 2026

thymikee commented on Oct 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions