sixfold-space/madtea

SHA256

Fork 0

adr: remove the legacy docs/adr/ layout, because its folder name lets a record skip every rule #639

New issue

Closed

opened 2026-09-27 00:16:18 +00:00 by hexajon · 2 comments

hexajon commented

2026-09-27 00:16:18 +00:00

Owner

What happens

adr check picks its rules from the folder name. A repo with docs/decisions/ gets the MADR check: front matter, status, date, sections, the index, links, and decision issues. A repo with docs/adr/ gets three checks only: unique numbers, an index that matches the files, and links between records that resolve.

So anyone can skip every MADR rule by writing records in docs/adr/ instead of docs/decisions/. A record there can hold any text and any status, and adr check passes it. With no tree at all, the error even offers that path: "run adr init to create docs/decisions/, or add a legacy docs/adr/ tree". In that layout, adr new --decision-issues writes any text it gets.

ADR 0034 kept the old layout for other repos. That keeps a way around the rules open in every repo that uses madtea.

Decision

The legacy docs/adr/ layout goes. adr refuses a docs/adr/ tree and says to move the records to docs/decisions/. A new decision record replaces the part of ADR 0034 that keeps the old layout, and the status of ADR 0034 points to it.

Impact

The old layout shipped from v0.15.2 to v0.18.5. A repo that adopted adr then has a docs/adr/ tree, and adr stops working there until the records move. The release notes must say so.

Open question

Does madtea help a repo move its records (a migrate step), or does the refusal message only say to move them?

Acceptance criteria

adr check, adr new, and adr init refuse a docs/adr/ tree, with a message that says to move the records to docs/decisions/.
The error for a repo with no tree no longer mentions docs/adr/.
The legacy code (checkLegacy, newLegacy, renderTemplate, the legacy branch of the layout detection) and its tests are removed.
A new decision record replaces the legacy-layout part of ADR 0034, and the status of ADR 0034 points to it.
The help text, the reference docs, and docs/COMPARISON.md no longer describe the legacy layout.

## What happens `adr check` picks its rules from the folder name. A repo with `docs/decisions/` gets the MADR check: front matter, status, date, sections, the index, links, and decision issues. A repo with `docs/adr/` gets three checks only: unique numbers, an index that matches the files, and links between records that resolve. So anyone can skip every MADR rule by writing records in `docs/adr/` instead of `docs/decisions/`. A record there can hold any text and any status, and `adr check` passes it. With no tree at all, the error even offers that path: "run `adr init` to create docs/decisions/, or add a legacy docs/adr/ tree". In that layout, `adr new --decision-issues` writes any text it gets. ADR 0034 kept the old layout for other repos. That keeps a way around the rules open in every repo that uses madtea. ## Decision The legacy `docs/adr/` layout goes. `adr` refuses a `docs/adr/` tree and says to move the records to `docs/decisions/`. A new decision record replaces the part of ADR 0034 that keeps the old layout, and the status of ADR 0034 points to it. ## Impact The old layout shipped from v0.15.2 to v0.18.5. A repo that adopted `adr` then has a `docs/adr/` tree, and `adr` stops working there until the records move. The release notes must say so. ## Open question Does madtea help a repo move its records (a migrate step), or does the refusal message only say to move them? ## Acceptance criteria - [ ] `adr check`, `adr new`, and `adr init` refuse a `docs/adr/` tree, with a message that says to move the records to `docs/decisions/`. - [ ] The error for a repo with no tree no longer mentions `docs/adr/`. - [ ] The legacy code (`checkLegacy`, `newLegacy`, `renderTemplate`, the legacy branch of the layout detection) and its tests are removed. - [ ] A new decision record replaces the legacy-layout part of ADR 0034, and the status of ADR 0034 points to it. - [ ] The help text, the reference docs, and `docs/COMPARISON.md` no longer describe the legacy layout.

hexajon referenced this issue

2026-09-28 18:16:43 +00:00

decision: move the ADR tooling into its own Go module, or keep it in madtea and improve it? #643

hexajon commented

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

Author

Owner

Decided: adr refuses a docs/adr/ tree and has no migrate command. The refusal names a help topic that lists the steps to move each record to docs/decisions/ and rewrite it as MADR: the front matter, the required sections, and a Decision issues: list. An agent follows those steps, because each rewrite needs judgment that a fixed converter does not have.

Decided: `adr` refuses a `docs/adr/` tree and has no migrate command. The refusal names a help topic that lists the steps to move each record to `docs/decisions/` and rewrite it as MADR: the front matter, the required sections, and a `Decision issues:` list. An agent follows those steps, because each rewrite needs judgment that a fixed converter does not have.

hexajon referenced this issue

2026-09-29 19:31:31 +00:00

epic: v0.20.0 - breaking: clearer ADR tooling and the write guard on every surface #675

hexajon added a new dependency

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

#675 epic: v0.20.0 - breaking: clearer ADR tooling and the write guard on every surface

hexajon referenced this issue from a pull request that will close it,

2026-10-16 00:09:55 +00:00

feat(adr)!: #639 remove the legacy docs/adr layout #781

hexajon referenced this issue from a commit

2026-10-16 00:09:58 +00:00

feat(adr): remove the legacy docs/adr layout

hexajon closed this issue

2026-10-16 00:10:01 +00:00

hexajon commented

2026-10-16 02:28:58 +00:00

Author

Owner

Decided and shipped in 0054-remove-the-legacy-docs-adr-layout. adr check, adr new, adr init, and adr rebuild now refuse a docs/adr tree and name the adr-legacy help topic for the steps to move each record into docs/decisions. No migrate command: the refusal lists the steps, because each rewrite needs judgment.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks

#675 epic: v0.20.0 - breaking: clearer ADR tooling and the write guard on every surface

sixfold-space/madtea

Reference

sixfold-space/madtea#639

No description provided.

Rows
Columns