Repository navigation
Restructure ADRs into short decision records #3744
Description
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.mdwith the authoring rules. Give it its own byte budget in the agent-guidance test. - Split the
AGENTS.mdroute: "Read architecture decisions" goes todocs/adr/README.md. "Write or amend an ADR" goes todocs/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.
Activity
thymikee commentedon Oct 16, 2026
Decision: classification of the ADRs (maintainer, 2026-10-16).
docs/evidence/. It is a measurement, not a decision.docs/evidence/. Keep only a general decision, if one passes the three-condition test.docs/evidence/. Merge their lasting decisions into ADR 0019.thymikee commentedon Oct 16, 2026
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:--recordcorrections.Error.packages/daemon/src/sessions/.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.thymikee commentedon Oct 16, 2026
Current state: 2026-10-16.
Merged:
Open, ready for review:
--recordcorrections).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.mdand the twoAGENTS.mdroutes. Then start the pilot on ADR 0003/0008 and the split of ADR 0012.fix(apple): refuse captures whose window or panel identity is unknown (…
thymikee commentedon Oct 18, 2026
Current state: 2026-10-18.
The prerequisites have merged: #3729, #3731, and stale-facts PR #3796. The stale-facts merge is
0fb25c474a. All 25 source threads received the PR link. Those threads remain open, as requested. The independent sentence review and all required checks passed before merge.The first restructure batch is now in progress. It adds
docs/adr/FORMAT.md, separate read and write routes inAGENTS.md, and a byte budget forFORMAT.md. It changes no ADR record. It adds no general ADR size gate.After that PR merges, the next batch is the ADR 0003/0008 pilot. The ADR 0012 split follows in the planned five decision groups. Each migration must move a still-true contract to its owner before deletion. The general ADR size gate remains last.
Separate open follow-up: #3791 was rebased onto the stale-facts merge. It awaits independent review and CI. Its daemon startup changes do not alter the restructure sequence.
docs(adr): keep the decision-history line optional and align FORMAT o…
docs(adr): add the ADR format guide and the write route (#3799)
thymikee commentedon Oct 18, 2026
Current state: 2026-10-18.
#3799 has merged. It adds
docs/adr/FORMAT.md, the read and write routes inAGENTS.md, and the format file's 4,000-byte budget. Independent sentence review and all required checks passed at8e46e04c1e.No ADR record changed in that batch. The next batch remains the ADR 0003/0008 pilot. The ADR 0012 split follows in five decision groups. The migration ledger and move-before-delete rule apply to each batch. The general ADR size gate remains last.
The maintainer requested a design review of #3797. That review now has priority. The ADR pilot is queued until this review is complete.
docs(adr): merge ADR 0003 into the ADR 0008 descriptor decision
docs(adr): merge ADR 0003 into the ADR 0008 descriptor decision
docs(adr): merge ADR 0003 into the ADR 0008 descriptor decision (#3810)
thymikee commentedon Oct 19, 2026
Current state: 2026-10-19.
#3810 merged at
82c0d705e4. ADR 0008 now owns the command-descriptor and daemon-policy decision. ADR 0003 is a short redirect. The migration ledger, independent sentence review, and validation evidence are in #3810. The FORMAT/routes batch #3799 and stale-facts batch #3796 are also merged.No restructure PR remains open from this coordinator. ADR 0012 is next. Its read-only plan keeps five decisions: no unattended selector rewrites, resolution disclosure, portable target identity, divergence/resume, and repair ownership. Authoring has not started. Refresh the code evidence and available ADR numbers before implementation. Move every still-true contract to its owner before deleting its old home. Use batches of one to three related ADRs. Keep the general size gate last.
This coordinator thread is closing at the maintainer's request. The remaining classification and migration work stays open in this issue.