feat(adr): `madtea adr` command group — `adr new` (race-free numbering) + `adr check` (consistency drift guard), org-wide via any repo's gate #26

New issue

Closed

opened 2026-07-11 22:07:56 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-11 22:07:56 +00:00

(Migrated from codeberg.org)

Decision

Enhance the ADR machinery machine/org-wide. Trigger incident: two sessions independently created ADR 0023 the same day (0023-shipped-strings-self-contained on main, 0023-declared-files-staging-contract on a separate branch); the tree happily carried both and NOTHING flagged it — not gate.sh, not docs-verify, not merge. Detection cost a conflicted PR, a renumber commit, and a reconcile dance.

Design

New CLI command group madtea adr (MCP action surface to match, per parity conventions — note: no gh/tea equivalent exists, so this is a new noun like worktree/orchestrate; document the naming rationale against ADR 0016):

madtea adr new <slug> — race-free creation: resolves the next free number from the ORIGIN default branch (not the local tree), writes docs/adr/NNNN-<slug>.md from a minimal template (title, Status/Date/Tracking header), and appends the index row to docs/adr/README.md. Kills the numbering race at creation time.
madtea adr check — consistency drift guard, exit-code clean/dirty for gate/CI wiring:
1. ADR numbers unique in the tree;
2. file ↔ index bijection (every NNNN-*.md has a README row; every row's link resolves);
3. (nice-to-have) supersession links resolve to existing ADRs.
Repo-agnostic: operates on any repo with a docs/adr/ (configurable path later if needed) so the SAME check serves every repo in the org that keeps ADRs — this is what makes the guard org-wide.

Wiring

madtea's own ./scripts/gate.sh adds an adr-check step (self-hosting the guard).
Org rollout (other repos' gates/CI adopting it + a handbook standard line) is follow-up work once the command ships — note it here, file separately when real.

Acceptance criteria

madtea adr new <slug> creates file + index row with the next free number resolved from origin's default branch
madtea adr check catches: duplicate numbers, orphan file (no index row), dangling index row
gate.sh runs adr check; a synthetic duplicate-number fixture proves it fails red
parity/COMPARISON/COMPAT/reference/help surfaces updated per house rules

Refs today's collision: an earlier issue / PR, ADR 0024 renumber.

## Decision Enhance the ADR machinery machine/org-wide. Trigger incident: two sessions independently created ADR 0023 the same day (`0023-shipped-strings-self-contained` on main, `0023-declared-files-staging-contract` on a separate branch); the tree happily carried both and NOTHING flagged it — not gate.sh, not docs-verify, not merge. Detection cost a conflicted PR, a renumber commit, and a reconcile dance. ## Design New CLI command group `madtea adr` (MCP action surface to match, per parity conventions — note: no gh/tea equivalent exists, so this is a new noun like `worktree`/`orchestrate`; document the naming rationale against ADR 0016): - **`madtea adr new <slug>`** — race-free creation: resolves the next free number from the ORIGIN default branch (not the local tree), writes `docs/adr/NNNN-<slug>.md` from a minimal template (title, Status/Date/Tracking header), and appends the index row to `docs/adr/README.md`. Kills the numbering race at creation time. - **`madtea adr check`** — consistency drift guard, exit-code clean/dirty for gate/CI wiring: 1. ADR numbers unique in the tree; 2. file ↔ index bijection (every `NNNN-*.md` has a README row; every row's link resolves); 3. (nice-to-have) supersession links resolve to existing ADRs. - Repo-agnostic: operates on any repo with a `docs/adr/` (configurable path later if needed) so the SAME check serves every repo in the org that keeps ADRs — this is what makes the guard org-wide. ## Wiring - madtea's own `./scripts/gate.sh` adds an `adr-check` step (self-hosting the guard). - Org rollout (other repos' gates/CI adopting it + a handbook standard line) is follow-up work once the command ships — note it here, file separately when real. ## Acceptance criteria - [ ] `madtea adr new <slug>` creates file + index row with the next free number resolved from origin's default branch - [ ] `madtea adr check` catches: duplicate numbers, orphan file (no index row), dangling index row - [ ] gate.sh runs adr check; a synthetic duplicate-number fixture proves it fails red - [ ] parity/COMPARISON/COMPAT/reference/help surfaces updated per house rules Refs today's collision: an earlier issue / PR, ADR 0024 renumber.

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.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#26

No description provided.

Rows
Columns

feat(adr): madtea adr command group — adr new (race-free numbering) + adr check (consistency drift guard), org-wide via any repo's gate #26

Decision

Design

Wiring

Acceptance criteria

feat(adr): `madtea adr` command group — `adr new` (race-free numbering) + `adr check` (consistency drift guard), org-wide via any repo's gate #26