Give adr-new one route that removes an ADR whose one-way-door reason is gone #1715

New issue

Open

opened 2026-11-12 17:57:33 +00:00 by jared · 0 comments

jared commented

2026-11-12 17:57:33 +00:00

Owner

Problem

adr-new has four routes that can change an Accepted ADR: supersede, challenge, amend, and delete. On ADR-0232, each route refuses and names a different route. The ADR records a one-way door whose reason no longer exists, and the challenge and delete judges read only the stale ADR text. Thus no route can remove or correct the record.

Observed

Each command ran as ruby ~/.claude/plugins/os-adr/bin/adr-new <route> --root /home/jared/dev/cc-os on 2026-11-12.

Create with supersedes: 0232 exits 3.

REJECTED (reversal test): The only callers named are skills, maps and agent prompts inside os-sdlc. The record says a 2026-11-12 search found no caller in another plugin or in cc-plugins, and the `os` usage sweep that made ADR-0232 a one-way door no longer exists. Script names, flags and exit code 3 are therefore a CLI contract that only os-sdlc's own code reads, which a reversing commit can change. The Thor refusal-text claim is explicitly not a contract. Record this nowhere; put the reason in the commit message.

challenge 0232 exits 0 and keeps the ADR. The file plugins/os/lib/worktree/usage_sweep.rb that the verdict relies on does not exist.

0232 accept: The decision sets a CLI contract (script names, flags, stdout shape, exit code 3) that the separate `os` plugin's usage sweep calls (`os-sdlc-implementation-report`). Reversing it would break that cross-plugin caller. The remaining text is framing around that contract.

amend 0232 with text that removes the stale caller exits 3.

adr-new: REJECTED (reversal test): The amended text says no file outside plugins/os-sdlc calls these scripts. The only callers left are agent prompts, map gate lines and runtime messages, all in the same plugin. Script names, flags, stdout shape and exit code 3 are therefore habits that one commit can rename together. The PATH symlink and the restart note describe a one-time merge step, not a door that stays shut. Record this nowhere; put the reason in the commit message. To drop the record entirely, run: adr-new delete 0232

delete 0232 exits 3.

adr-new: ADR 0232 records a one-way door; supersede it instead of deleting it.

A second defect: adr-new help and adr-new help amend raise JSON::ParserError. The CLI reads help as a create with empty stdin. Amend has no reason field.

Effect: ADR-0232 stays Accepted with three false statements: the os usage sweep caller, the --sweep-only flag (deleted in 063075f19), and "byte-identical to the former os-sdlc-runner subcommands". Jared ruled on 2026-11-10 that ADR-0232 goes.

Reproduce

ruby ~/.claude/plugins/os-adr/bin/adr-new delete 0232 --root /home/jared/dev/cc-os </dev/null

Acceptance criteria

Given an Accepted ADR whose amended or superseding text the judge rejects as a habit, when the caller follows the route that the rejection names, then that route removes the record or states one route that can.
Given adr-new help, when it runs, then it prints usage and exits 0 with no stack trace.

Origin

Trigger: the four adr-new commands above, run to remove ADR-0232 for #1646.
Improvised this session: none. ADR-0232 was left unchanged.
Chain: ADR-0232 cannot be removed ← the delete and challenge judges read only the ADR text, and the supersede and amend judges read the proposed text ← DESIGN (plugins/os-adr/lib/adr/record/amendment.rb and the judge prompts under plugins/os-adr).
Root candidate: none found; searched adr-new, 0232, amend, delete, retire, os-adr judge
Where: plugins/os-adr/bin/adr-new, plugins/os-adr/lib/adr/record/
Session: 66fd4451-ebac-488b-9d88-733faf4a141c
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os-plugins-os-sdlc/66fd4451-ebac-488b-9d88-733faf4a141c.jsonl

VERDICT: CREATE. The four routes refuse in a loop, reproduced with exit codes; the defect blocks Jared's 2026-11-10 ruling; no open ticket covers it (#1649 and #1310 name a different fault).

## Problem `adr-new` has four routes that can change an Accepted ADR: supersede, challenge, amend, and delete. On ADR-0232, each route refuses and names a different route. The ADR records a one-way door whose reason no longer exists, and the challenge and delete judges read only the stale ADR text. Thus no route can remove or correct the record. ## Observed Each command ran as `ruby ~/.claude/plugins/os-adr/bin/adr-new <route> --root /home/jared/dev/cc-os` on 2026-11-12. Create with `supersedes: 0232` exits 3. ``` REJECTED (reversal test): The only callers named are skills, maps and agent prompts inside os-sdlc. The record says a 2026-11-12 search found no caller in another plugin or in cc-plugins, and the `os` usage sweep that made ADR-0232 a one-way door no longer exists. Script names, flags and exit code 3 are therefore a CLI contract that only os-sdlc's own code reads, which a reversing commit can change. The Thor refusal-text claim is explicitly not a contract. Record this nowhere; put the reason in the commit message. ``` `challenge 0232` exits 0 and keeps the ADR. The file `plugins/os/lib/worktree/usage_sweep.rb` that the verdict relies on does not exist. ``` 0232 accept: The decision sets a CLI contract (script names, flags, stdout shape, exit code 3) that the separate `os` plugin's usage sweep calls (`os-sdlc-implementation-report`). Reversing it would break that cross-plugin caller. The remaining text is framing around that contract. ``` `amend 0232` with text that removes the stale caller exits 3. ``` adr-new: REJECTED (reversal test): The amended text says no file outside plugins/os-sdlc calls these scripts. The only callers left are agent prompts, map gate lines and runtime messages, all in the same plugin. Script names, flags, stdout shape and exit code 3 are therefore habits that one commit can rename together. The PATH symlink and the restart note describe a one-time merge step, not a door that stays shut. Record this nowhere; put the reason in the commit message. To drop the record entirely, run: adr-new delete 0232 ``` `delete 0232` exits 3. ``` adr-new: ADR 0232 records a one-way door; supersede it instead of deleting it. ``` A second defect: `adr-new help` and `adr-new help amend` raise `JSON::ParserError`. The CLI reads `help` as a create with empty stdin. Amend has no reason field. Effect: ADR-0232 stays Accepted with three false statements: the `os` usage sweep caller, the `--sweep-only` flag (deleted in 063075f19), and "byte-identical to the former `os-sdlc-runner` subcommands". Jared ruled on 2026-11-10 that ADR-0232 goes. ## Reproduce ``` ruby ~/.claude/plugins/os-adr/bin/adr-new delete 0232 --root /home/jared/dev/cc-os </dev/null ``` ## Acceptance criteria 1. Given an Accepted ADR whose amended or superseding text the judge rejects as a habit, when the caller follows the route that the rejection names, then that route removes the record or states one route that can. 2. Given `adr-new help`, when it runs, then it prints usage and exits 0 with no stack trace. ## Origin - Trigger: the four `adr-new` commands above, run to remove ADR-0232 for #1646. - Improvised this session: none. ADR-0232 was left unchanged. - Chain: ADR-0232 cannot be removed ← the delete and challenge judges read only the ADR text, and the supersede and amend judges read the proposed text ← DESIGN (`plugins/os-adr/lib/adr/record/amendment.rb` and the judge prompts under `plugins/os-adr`). - Root candidate: none found; searched adr-new, 0232, amend, delete, retire, os-adr judge - Where: `plugins/os-adr/bin/adr-new`, `plugins/os-adr/lib/adr/record/` - Session: 66fd4451-ebac-488b-9d88-733faf4a141c - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os-plugins-os-sdlc/66fd4451-ebac-488b-9d88-733faf4a141c.jsonl VERDICT: CREATE. The four routes refuse in a loop, reproduced with exit codes; the defect blocks Jared's 2026-11-10 ruling; no open ticket covers it (#1649 and #1310 name a different fault).

jared added the

plugin/os-adr

filed-by/agent

category/code-change

labels

2026-11-12 17:57:33 +00:00

jared referenced this issue

2026-11-12 18:28:29 +00:00

os-sdlc entry: decide and build Thor for argument parsing behind the fixed os-sdlc-* script names (ADR-0232) #1646