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

New issue

Open

opened 2026-09-15 23:09:26 +00:00 by hexajon · 1 comment

hexajon commented

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

Owner

What happens

ADR 0008 moved all help and metadata into the surface-neutral registry in internal/opspec, and retired the hand-written Cobra help. The migration stopped at the start:

1 of 258 CLI command files in internal/cmd uses opspec (the labels noun).
343 hand-written Long: help strings remain.
Nothing stops a new command from adding more hand-written help.

Ask

A test with a checked-in baseline (a golden file in testdata/, updated with an -update flag, the pattern Go's own go/printer and go/doc tests use) that lists every CLI command still using hand-written help. The test fails when the list grows. The list may only shrink.
A new CLI command must render from opspec; the test fails for any new entry.
An epic with one child per noun, whose exit criterion is an empty baseline. Then the ADR 0008 Confirmation can fail for unfinished work.

Acceptance

Adding a hand-written Long: to a new command fails the test.
Migrating a noun and running the test with -update shrinks the baseline.
The epic lists every remaining noun.

## What happens ADR 0008 moved all help and metadata into the surface-neutral registry in `internal/opspec`, and retired the hand-written Cobra help. The migration stopped at the start: - 1 of 258 CLI command files in `internal/cmd` uses `opspec` (the `labels` noun). - 343 hand-written `Long:` help strings remain. - Nothing stops a new command from adding more hand-written help. ## Ask 1. A test with a checked-in baseline (a golden file in `testdata/`, updated with an `-update` flag, the pattern Go's own `go/printer` and `go/doc` tests use) that lists every CLI command still using hand-written help. The test fails when the list grows. The list may only shrink. 2. A new CLI command must render from `opspec`; the test fails for any new entry. 3. An epic with one child per noun, whose exit criterion is an empty baseline. Then the ADR 0008 Confirmation can fail for unfinished work. ## Acceptance - Adding a hand-written `Long:` to a new command fails the test. - Migrating a noun and running the test with `-update` shrinks the baseline. - The epic lists every remaining noun.

hexajon added the

enhancement

label

2026-09-15 23:09:26 +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

hexajon commented

2026-09-27 00:09:28 +00:00

Author

Owner

A concrete case from the #634 work. adr still uses hand-written help, so one change had to write the same facts in three places: the CLI help in internal/cmd/adr/adr.go, the MCP parameter doc in internal/opspec/paramdocs.go, and the MCP example in internal/mcp/tools_adr.go.

They drifted at once. The CLI examples show --decision-issues "#42". The MCP example still shows madt_adr(action="new", slug="origin-first-forge-resolution") with no decision issues, and a record made that way now fails adr check. Nothing caught it, because the parity test checks names, not help text or examples.

The same change also made the hand-written adr help longer, which is the direction this issue wants to stop. adr has three actions (init, new, check), so it is a small command group to move.

A concrete case from the #634 work. `adr` still uses hand-written help, so one change had to write the same facts in three places: the CLI help in `internal/cmd/adr/adr.go`, the MCP parameter doc in `internal/opspec/paramdocs.go`, and the MCP example in `internal/mcp/tools_adr.go`. They drifted at once. The CLI examples show `--decision-issues "#42"`. The MCP example still shows `madt_adr(action="new", slug="origin-first-forge-resolution")` with no decision issues, and a record made that way now fails `adr check`. Nothing caught it, because the parity test checks names, not help text or examples. The same change also made the hand-written `adr` help longer, which is the direction this issue wants to stop. `adr` has three actions (`init`, `new`, `check`), so it is a small command group to move.

hexajon referenced this issue

2026-10-21 16:37:47 +00:00

test: hold hand-written CLI help to a baseline that may only shrink #863

hexajon referenced this issue from a commit

2026-10-21 16:37:48 +00:00

test: hold hand-written CLI help to a baseline that may only shrink

hexajon referenced this issue from a commit

2026-10-21 16:37:48 +00:00

fix: keep rendered-help records per command and check Short too