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

New issue

Open

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

hexajon commented

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

Owner

Goal

An accepted decision in docs/decisions/ is either enforced by a check the gate runs, or tracked by an open epic until it is. A decision can no longer sit accepted and unfinished with every check green.

Why

ADR 0008 is accepted, yet 1 of 258 CLI command files follows it, and its Confirmation can only fail for finished work. ADR 0023 forbids internal codes in shipped strings, yet adr check shipped them. repos get hides fields repos edit sets, and actions runs reads one forge's field names. The checks in internal/parity guard single past incidents, not the rules.

Design (the Go way)

Rules as checks: go/analysis analyzers (the go vet framework) for code and string rules.
Migrations behind a one-way limit: golden-file baselines in testdata/, updated with -update, that may only shrink.
One source per fact, derived everywhere: struct tags or opspec entries read with reflect in tests; generated files through go generate (#513).
Everything runs in scripts/gate.sh, and CI only checks.

Children

#514 accepted record needs a gate-run Confirmation or an open epic
#515 ADR 0008 migration behind a one-way limit
#516 ADR 0023 analyzer for shipped strings
#517 decision: single source of record for fields

Related: #492 (remove the adr check codes), #513 (go generate and one stale-file check).

Exit criterion

All children closed, and every accepted record's Confirmation runs in the gate.

## Goal An accepted decision in `docs/decisions/` is either enforced by a check the gate runs, or tracked by an open epic until it is. A decision can no longer sit accepted and unfinished with every check green. ## Why ADR 0008 is accepted, yet 1 of 258 CLI command files follows it, and its Confirmation can only fail for finished work. ADR 0023 forbids internal codes in shipped strings, yet `adr check` shipped them. `repos get` hides fields `repos edit` sets, and `actions runs` reads one forge's field names. The checks in `internal/parity` guard single past incidents, not the rules. ## Design (the Go way) - **Rules as checks:** `go/analysis` analyzers (the `go vet` framework) for code and string rules. - **Migrations behind a one-way limit:** golden-file baselines in `testdata/`, updated with `-update`, that may only shrink. - **One source per fact, derived everywhere:** struct tags or `opspec` entries read with `reflect` in tests; generated files through `go generate` (#513). - Everything runs in `scripts/gate.sh`, and CI only checks. ## Children - #514 accepted record needs a gate-run Confirmation or an open epic - #515 ADR 0008 migration behind a one-way limit - #516 ADR 0023 analyzer for shipped strings - #517 decision: single source of record for fields Related: #492 (remove the `adr check` codes), #513 (`go generate` and one stale-file check). ## Exit criterion All children closed, and every accepted record's Confirmation runs in the gate.  - [ ] #514 - [ ] #515 - [ ] #516 - [ ] #517

hexajon added the

epic

label

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

hexajon added a new dependency

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

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

hexajon added a new dependency

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

#515 opspec: finish the ADR 0008 migration behind a one-way limit, so hand-written CLI help can only shrink

hexajon added a new dependency

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