adr: an accepted record needs a Confirmation the gate runs, or an open tracking epic #514

New issue

Open

opened 2026-09-15 23:09:20 +00:00 by hexajon · 0 comments

hexajon commented

2026-09-15 23:09:20 +00:00

Owner

What happens

A record goes to accepted when the decision is made. Nothing tracks whether the decision is carried out, and nothing fails when it is not.

Example: ADR 0008 is accepted. It says every surface renders its help from one registry (internal/opspec) and "the hand-written Cobra help strings are retired". Today 1 of 258 CLI command files uses opspec, and 343 hand-written Long: help strings remain. No open epic tracks the migration.

Its Confirmation says "docs generate --verify plus the new content-parity test gate the noun-by-noun migration". That checks only the nouns already migrated, so it cannot fail for the work not done.

Ask

Each accepted record in this repo either names a Confirmation check that runs in scripts/gate.sh, or links an open tracking epic whose exit criterion is "the Confirmation runs in the gate".
A Confirmation must be able to fail for work not yet done, for example a count that must reach zero, not a check that covers only finished parts.
Audit all accepted records (0001 to 0037) and list, per record: the Confirmation, whether the gate runs it, and the open epic if not.
Enforce it in this repo's own gate. Whether adr check offers this to other repos is a separate product choice; madtea must not force this repo's policy on its users.

Acceptance

The audit table exists.
The gate fails when an accepted record has neither a gate-run Confirmation nor an open tracking epic.

## What happens A record goes to `accepted` when the decision is made. Nothing tracks whether the decision is carried out, and nothing fails when it is not. Example: ADR 0008 is accepted. It says every surface renders its help from one registry (`internal/opspec`) and "the hand-written Cobra help strings are retired". Today 1 of 258 CLI command files uses `opspec`, and 343 hand-written `Long:` help strings remain. No open epic tracks the migration. Its Confirmation says "`docs generate --verify` plus the new content-parity test gate the noun-by-noun migration". That checks only the nouns already migrated, so it cannot fail for the work not done. ## Ask - Each accepted record in this repo either names a Confirmation check that runs in `scripts/gate.sh`, or links an open tracking epic whose exit criterion is "the Confirmation runs in the gate". - A Confirmation must be able to fail for work not yet done, for example a count that must reach zero, not a check that covers only finished parts. - Audit all accepted records (0001 to 0037) and list, per record: the Confirmation, whether the gate runs it, and the open epic if not. - Enforce it in this repo's own gate. Whether `adr check` offers this to other repos is a separate product choice; madtea must not force this repo's policy on its users. ## Acceptance - The audit table exists. - The gate fails when an accepted record has neither a gate-run Confirmation nor an open tracking epic.

hexajon added the

enhancement

label

2026-09-15 23:09:20 +00:00

hexajon referenced this issue

2026-09-15 23:09:55 +00:00

Epic: accepted decisions are enforced by checks, not only recorded #518

hexajon added a new dependency

2026-09-15 23:09:59 +00:00

#518 Epic: accepted decisions are enforced by checks, not only recorded