sixfold-space/madtea

SHA256

Fork 0

Epic: consolidate the decision records #646

New issue

Open

opened 2026-09-29 15:07:20 +00:00 by hexajon · 3 comments

hexajon commented

2026-09-29 15:07:20 +00:00

Owner

Goal

Every record in docs/decisions/ states only its current decision, makes sense without opening an issue, and the record numbers run from 0001 with no gap.

Rules for this work

A changed decision is edited in place, and the record keeps its number. Git holds the history, so a record carries no "Amended" lines.
Two records on one subject merge into the lower number, because the first record on a subject is its home.
After a merge, every record above the gap is renumbered, so the numbers stay consecutive as MADR expects. Every citation in the repo changes in the same PR.
A record heading carries no number. The number lives only in the file name.
Each edit to a decided record needs my sign-off.

Why

I read every record in full. Most still carry the house format from before MADR: a Tracking: line, "Amended" lines, stray </content> lines, and references to files and tests that no longer exist. Four pairs of records set rules on one subject, and some records contradict another record or their own later text.

Exit criterion

All children are closed, adr check passes, and the record numbers run from 0001 with no gap.

Related: sixfold-space/madtea-site#75, which keys the site's record pages by title, so that a renumber moves no page.

## Goal Every record in `docs/decisions/` states only its current decision, makes sense without opening an issue, and the record numbers run from 0001 with no gap. ## Rules for this work - A changed decision is edited in place, and the record keeps its number. Git holds the history, so a record carries no "Amended" lines. - Two records on one subject merge into the lower number, because the first record on a subject is its home. - After a merge, every record above the gap is renumbered, so the numbers stay consecutive as MADR expects. Every citation in the repo changes in the same PR. - A record heading carries no number. The number lives only in the file name. - Each edit to a decided record needs my sign-off. ## Why I read every record in full. Most still carry the house format from before MADR: a `Tracking:` line, "Amended" lines, stray `</content>` lines, and references to files and tests that no longer exist. Four pairs of records set rules on one subject, and some records contradict another record or their own later text. ## Exit criterion All children are closed, `adr check` passes, and the record numbers run from 0001 with no gap. Related: sixfold-space/madtea-site#75, which keys the site's record pages by title, so that a renumber moves no page.  - [ ] #647 - [ ] #648 - [ ] #649 - [ ] #650 - [ ] #651 - [ ] #652 - [ ] #657

hexajon added the

epic

label

2026-09-29 15:07:20 +00:00

hexajon added a new dependency

2026-09-29 15:17:53 +00:00

#647 records: remove the Tracking lines, the stray artifacts, and the 0035 index mismatch

hexajon added a new dependency

2026-09-29 15:17:53 +00:00

#648 records: fold the history lines into the current text

hexajon added a new dependency

2026-09-29 15:17:54 +00:00

#649 records: merge four pairs into the lower number, then renumber

hexajon added a new dependency

2026-09-29 15:17:54 +00:00

#650 records: make 0034 and 0037 state the current rules for records

hexajon added a new dependency

2026-09-29 15:17:54 +00:00

#651 records: close the open items in 0038 and 0039

hexajon commented

2026-09-29 15:18:57 +00:00

Author

Owner

This epic changes a recorded decision. On main, ADR 0037 says "amended is not added: a changed decision gets a new record." Under this epic, a decided record is edited in place instead, with my sign-off, and it keeps its number. #650 changes that line of 0037 to match.

This epic changes a recorded decision. On main, ADR 0037 says "`amended` is not added: a changed decision gets a new record." Under this epic, a decided record is edited in place instead, with my sign-off, and it keeps its number. #650 changes that line of 0037 to match.

hexajon added a new dependency

2026-09-29 15:19:02 +00:00

#652 records: fix references to files and tests that do not exist

hexajon commented

2026-09-29 16:38:58 +00:00

Author

Owner

The work for this epic runs in the branch docs/adr-one-guard-for-every-surface, together with ADR 0046 and ADR 0047, so there is one merge. The rules for the pass:

A decided record is edited in place, and it keeps its number. Each edit needs my sign-off.
adr check allows only MADR's five statuses (ADR 0037).
A reference to a file follows ADR 0037: a plain path names a file in this repo and must exist; a file in another repo is a full URL; a path that starts with ~/ or / is a file on a user's machine. A record names no function, test, line number, or count of code.
Forge-facing tests run against the live forge API and a test repo.

The records split into six groups by subject, and each group is edited in one pass: the Tracking: lines, the stray artifacts, the history lines, the reference rule, and the content of any merge in the group. Then the four higher records are deleted, the set is renumbered, and every citation is rewritten.

The work for this epic runs in the branch `docs/adr-one-guard-for-every-surface`, together with ADR 0046 and ADR 0047, so there is one merge. The rules for the pass: - A decided record is edited in place, and it keeps its number. Each edit needs my sign-off. - `adr check` allows only MADR's five statuses (ADR 0037). - A reference to a file follows ADR 0037: a plain path names a file in this repo and must exist; a file in another repo is a full URL; a path that starts with `~/` or `/` is a file on a user's machine. A record names no function, test, line number, or count of code. - Forge-facing tests run against the live forge API and a test repo. The records split into six groups by subject, and each group is edited in one pass: the `Tracking:` lines, the stray artifacts, the history lines, the reference rule, and the content of any merge in the group. Then the four higher records are deleted, the set is renumbered, and every citation is rewritten.

hexajon added a new dependency

2026-09-29 16:39:28 +00:00

#657 records: apply the reference rule of ADR 0037 to every record

hexajon commented

2026-09-29 19:02:30 +00:00

Author

Owner

Status: #647, #648, #649, #650, and #652 are done in #667. #651 (the open check in ADR 0038) and #657 (the reference audit, which the check in #658 makes permanent) stay open.