adr: add rebuild to regenerate the README index from the records #508

New issue

Closed

opened 2026-09-15 22:18:04 +00:00 by hexajon · 2 comments

hexajon commented

2026-09-15 22:18:04 +00:00

Owner

What happens

adr new appends one index row when it creates a record. Nothing rebuilds the index after that. When a status changes, a record is renamed, or a merge drops a row, the author fixes the ## Index table in README.md by hand. adr check reports a missing row or a row with no record, but gives no command to fix it. A row whose status differs from its record is not reported at all.

Design

Read every record file in docs/decisions/: number, title, status, and date.
Replace only the data rows of the ## Index table in README.md with one row per record, sorted by number. Use the row format adr new writes today: | [0036](0036-slug.md) | Title | accepted | 2026-09-15 |. Leave the rest of the README unchanged.
adr check also reports an index row whose status or title differs from its record.
When adr check finds any index drift, its message points at adr rebuild.
MCP: madt_adr action=rebuild, same behaviour.

Open design points

A README with no ## Index table: skip it, or create the table behind a flag.
A repo whose index table uses other columns: refuse with a clear message, or keep unknown columns.

Prior art: ADG rebuild regenerates its own index file. adr-log generates a decision log from MADR files.

Acceptance

After a status edit, adr rebuild updates that row and adr check passes.
A README with extra content around the table keeps that content byte for byte.
adr check reports a status or title mismatch between a record and its index row.

## What happens `adr new` appends one index row when it creates a record. Nothing rebuilds the index after that. When a status changes, a record is renamed, or a merge drops a row, the author fixes the `## Index` table in `README.md` by hand. `adr check` reports a missing row or a row with no record, but gives no command to fix it. A row whose status differs from its record is not reported at all. ## Design - Read every record file in `docs/decisions/`: number, title, status, and date. - Replace only the data rows of the `## Index` table in `README.md` with one row per record, sorted by number. Use the row format `adr new` writes today: `| [0036](0036-slug.md) | Title | accepted | 2026-09-15 |`. Leave the rest of the README unchanged. - `adr check` also reports an index row whose status or title differs from its record. - When `adr check` finds any index drift, its message points at `adr rebuild`. - MCP: `madt_adr action=rebuild`, same behaviour. ## Open design points - A README with no `## Index` table: skip it, or create the table behind a flag. - A repo whose index table uses other columns: refuse with a clear message, or keep unknown columns. Prior art: ADG `rebuild` regenerates its own index file. `adr-log` generates a decision log from MADR files. ## Acceptance - After a status edit, `adr rebuild` updates that row and `adr check` passes. - A README with extra content around the table keeps that content byte for byte. - `adr check` reports a status or title mismatch between a record and its index row.

hexajon added the

enhancement

label

2026-09-15 22:18:04 +00:00

hexajon added a new dependency

2026-09-15 22:18:09 +00:00

#496 Epic: adr tooling guides the author, not only fails

~~hexajon referenced this issue 2026-09-15 22:18:10 +00:00~~

Epic: adr tooling guides the author, not only fails #496

hexajon commented

2026-09-15 22:26:03 +00:00

Author

Owner

A live example on main today: record 0035 says status: "accepted", while its README index row still says proposed. adr check passes, because it does not compare statuses. The new status-mismatch report, and adr rebuild, would catch and fix this.

A live example on `main` today: record 0035 says `status: "accepted"`, while its README index row still says `proposed`. `adr check` passes, because it does not compare statuses. The new status-mismatch report, and `adr rebuild`, would catch and fix this.

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:57:17 +00:00

Author

Owner

Decided: adr rebuild refuses a README with no ## Index table, and it refuses an index table with other columns. In both cases it says what to fix. It never adds a table, and it never keeps unknown columns.

Decided: `adr rebuild` refuses a README with no `## Index` table, and it refuses an index table with other columns. In both cases it says what to fix. It never adds a table, and it never keeps unknown columns.

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:59 +00:00

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

hexajon referenced this issue from a commit

2026-10-15 22:23:13 +00:00

feat(adr): #508 add adr rebuild and report index status/title drift

hexajon referenced this issue from a commit

2026-10-15 22:23:13 +00:00

feat(adr): #508 flag an index date drift in adr check