@rvdbreemen/adr-kit-opencode 0.56.0 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,331 @@
1
+ #!/usr/bin/env python3
2
+ """The phases of docs/RELEASING.md, each one able to say whether it is already done.
3
+
4
+ ADR-042 makes this the sanctioned way to cut a release, and keeps
5
+ docs/RELEASING.md as the specification: every phase here mirrors one step
6
+ there, in the same order, so a divergence between the two is visible in review
7
+ rather than hidden.
8
+
9
+ Every phase is idempotent. A release that dies halfway is the normal case - a
10
+ check goes red, a merge waits on CI, a machine is closed - and the recovery has
11
+ to be "run it again", not "work out which half already happened". Each phase
12
+ answers `done(ctx)` from the repository's actual state rather than from a
13
+ progress file, because a progress file is one more thing that can disagree with
14
+ reality.
15
+
16
+ `verify_tag` exists because nothing checked it before and its absence cost a
17
+ release: it asserts the tag resolves to `origin/main`. v0.55.0 was burned by a
18
+ tag on the dev tip, where every version site still read the previous release,
19
+ and the gate correctly refused to publish it.
20
+
21
+ The npm step is not a phase and lives in release_npm.py. It is the one part of
22
+ a release no tool may finish, so it sits on the other side of ADR-042's
23
+ automation boundary rather than inside PHASES.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import json
28
+ import re
29
+ import sys
30
+ from pathlib import Path
31
+ from typing import Callable, List, NamedTuple, Tuple
32
+
33
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
34
+
35
+ from release_shell import ( # noqa: E402
36
+ CLIENTS,
37
+ PACKAGE,
38
+ ROOT,
39
+ Context,
40
+ ReleaseError,
41
+ _clean_tree,
42
+ _client_version,
43
+ _main_sha,
44
+ _version_everywhere,
45
+ _wait_until,
46
+ git,
47
+ run,
48
+ script,
49
+ )
50
+
51
+
52
+ # --- phase 0: preflight -----------------------------------------------------
53
+
54
+
55
+ def preflight_done(ctx: Context) -> bool:
56
+ return False # cheap, and its answer can change between runs
57
+
58
+
59
+ def preflight(ctx: Context) -> List[str]:
60
+ notes = []
61
+ if not _clean_tree():
62
+ raise ReleaseError(
63
+ "the working tree has uncommitted changes. Commit or stash them "
64
+ "first: a release commit must contain the version bump and nothing "
65
+ "that happened to be lying around."
66
+ )
67
+ code, out, _ = script("check-branch-sync.py")
68
+ if code == 1:
69
+ raise ReleaseError(
70
+ "dev does not carry every published release:\n"
71
+ + out
72
+ + "\nMerge main back into dev and land that first. A release branch "
73
+ "cut from a stale dev collides with main on every version stamp."
74
+ )
75
+ if code == 2:
76
+ notes.append("branch-sync check could not run; treated as infrastructure noise")
77
+ if run(["gh", "auth", "status"])[0] != 0:
78
+ raise ReleaseError(
79
+ "gh is not authenticated. The driver opens the pull request with "
80
+ "your credentials on purpose: GitHub does not start workflow runs "
81
+ "for events caused by GITHUB_TOKEN, so a bot-opened PR would never "
82
+ "receive the checks main requires (ADR-042)."
83
+ )
84
+ notes.append("working tree clean, dev current, gh authenticated")
85
+ return notes
86
+
87
+
88
+ # --- phase 1: prepare the version and the release notes ---------------------
89
+
90
+
91
+ def prepare_done(ctx: Context) -> bool:
92
+ return _version_everywhere(ctx) and not _changelog_is_placeholder(ctx)
93
+
94
+
95
+ def _changelog_section(ctx: Context) -> str:
96
+ text = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
97
+ match = re.search(
98
+ rf"^## \[{re.escape(ctx.version)}\][^\n]*\n(.*?)(?=^## \[|\Z)",
99
+ text,
100
+ re.MULTILINE | re.DOTALL,
101
+ )
102
+ return match.group(1) if match else ""
103
+
104
+
105
+ def _changelog_is_placeholder(ctx: Context) -> bool:
106
+ """Is this section still the stub `bump-version.py` wrote, or empty?
107
+
108
+ Matched on the placeholder's SHAPE, a top-level `- TODO:` list item, rather
109
+ than on the word anywhere in the section. The substring test blocked 0.57.0,
110
+ whose notes describe the placeholder-detection work of TASK-198 and TASK-199
111
+ and therefore quote `- TODO:` markers five times, none of them a placeholder.
112
+ A gate that cannot let a release describe its own subject matter leaves the
113
+ author no move except degrading the notes.
114
+
115
+ Still catches a leftover TODO item an author wrote themselves, which
116
+ comparing against `bump-version.py`'s exact string would miss.
117
+ """
118
+ body = _changelog_section(ctx)
119
+ return (not body.strip()) or any(
120
+ line.strip().startswith("- TODO:") for line in body.splitlines()
121
+ )
122
+
123
+
124
+ def prepare(ctx: Context) -> List[str]:
125
+ notes = []
126
+ if not _version_everywhere(ctx):
127
+ _, out, _ = script("bump-version.py", ctx.version, check=True)
128
+ notes.append(out.strip().splitlines()[0] if out.strip() else "version written")
129
+ script("build-client-adapters.py", check=True)
130
+ notes.append("client adapters regenerated")
131
+ if _changelog_is_placeholder(ctx):
132
+ raise ReleaseError(
133
+ f"CHANGELOG.md's [{ctx.version}] section is still the placeholder.\n"
134
+ "release-publish.yml publishes that section verbatim as the GitHub "
135
+ "Release body, so it has to read as the announcement: group the "
136
+ "changes, name the user-facing impact, call out upgrade steps.\n"
137
+ "Write it, then run this command again - everything else is already "
138
+ "in place."
139
+ )
140
+ notes.append(f"every version site reads {ctx.version}")
141
+ return notes
142
+
143
+
144
+ # --- phase 2: the gates CI will run anyway ----------------------------------
145
+
146
+
147
+ def verify_done(ctx: Context) -> bool:
148
+ return False # the point is to run them
149
+
150
+
151
+ def verify(ctx: Context) -> List[str]:
152
+ notes = []
153
+ for label, cmd in (
154
+ ("version consistency", lambda: script("check-release-version.py", "--expect", ctx.tag)),
155
+ ("adapter drift", lambda: script("build-client-adapters.py", "--check")),
156
+ ):
157
+ if cmd()[0] != 0:
158
+ raise ReleaseError(f"{label} check failed; run it directly to see the detail")
159
+ notes.append(f"{label}: pass")
160
+ for label, cmd in (
161
+ ("adr-lint --strict", ["bin/adr-lint", "--strict", "docs/adr"]),
162
+ ("adr-index --check", ["bin/adr-index", "--check", "docs/adr"]),
163
+ ):
164
+ if run([sys.executable, str(ROOT / cmd[0]), *cmd[1:]])[0] != 0:
165
+ raise ReleaseError(f"{label} failed; run it directly to see the detail")
166
+ notes.append(f"{label}: pass")
167
+ if ctx.skip_tests:
168
+ notes.append("pytest SKIPPED by request; CI still runs it on the pull request")
169
+ return notes
170
+ code, out, _ = run([sys.executable, "-m", "pytest", "-q", "-p", "no:cacheprovider"])
171
+ tail = (out.strip().splitlines() or ["no output"])[-1]
172
+ if code != 0:
173
+ raise ReleaseError(
174
+ f"the test suite failed: {tail}\n"
175
+ "Before treating this as real, check that no second pytest is "
176
+ "running: a killed background wrapper leaves its child alive, and "
177
+ "two concurrent runs produce failures that are artefacts."
178
+ )
179
+ notes.append(f"pytest: {tail}")
180
+ return notes
181
+
182
+
183
+ # --- phase 3: land on main --------------------------------------------------
184
+
185
+
186
+ def land_done(ctx: Context) -> bool:
187
+ git("fetch", "origin", "--tags")
188
+ code, head, _ = git("show", "origin/main:CHANGELOG.md")
189
+ if code != 0:
190
+ return False
191
+ return bool(re.search(rf"^## \[{re.escape(ctx.version)}\]", head, re.MULTILINE))
192
+
193
+
194
+ def land(ctx: Context) -> List[str]:
195
+ notes = []
196
+ current = git("rev-parse", "--abbrev-ref", "HEAD")[1].strip()
197
+ if current != ctx.branch:
198
+ if git("rev-parse", "--verify", ctx.branch)[0] == 0:
199
+ git("checkout", ctx.branch, check=True)
200
+ else:
201
+ git("checkout", "-b", ctx.branch, check=True)
202
+ notes.append(f"on {ctx.branch}")
203
+ if not _clean_tree():
204
+ git("add", "-A", check=True)
205
+ git("commit", "-m", f"chore(release): {ctx.tag}", check=True)
206
+ notes.append("release commit written")
207
+ git("push", "-u", "origin", ctx.branch, check=True)
208
+
209
+ existing = run(["gh", "pr", "list", "--head", ctx.branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
210
+ if not existing:
211
+ body = (
212
+ f"Release {ctx.tag}. Prepared by `scripts/release.py`, which mirrors "
213
+ f"`docs/RELEASING.md`.\n\n"
214
+ f"**Do not tag this by hand.** Since ADR-042 `release-publish.yml` "
215
+ f"creates the tag from the merged commit and publishes in the same "
216
+ f"run. Tagging by hand is how v0.55.0 was burned.\n\n"
217
+ f"Release notes are the `## [{ctx.version}]` CHANGELOG section, which "
218
+ f"the workflow publishes verbatim."
219
+ )
220
+ run(["gh", "pr", "create", "--base", "main", "--head", ctx.branch,
221
+ "--title", f"chore(release): {ctx.tag}", "--body", body], check=True)
222
+ notes.append("pull request opened into main")
223
+ number = run(["gh", "pr", "list", "--head", ctx.branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
224
+ run(["gh", "pr", "merge", number, "--auto", "--merge"])
225
+ notes.append(f"auto-merge armed on #{number}; waiting for the required checks")
226
+ _wait_until(lambda: land_done(ctx), ctx, f"pull request #{number} to merge into main")
227
+ notes.append("merged into main")
228
+ return notes
229
+
230
+
231
+ # --- phase 4: the tag the workflow creates ----------------------------------
232
+
233
+
234
+ def verify_tag_done(ctx: Context) -> bool:
235
+ git("fetch", "origin", "--tags")
236
+ peeled = git("rev-parse", f"{ctx.tag}^{{}}")
237
+ return peeled[0] == 0 and peeled[1].strip() == _main_sha()
238
+
239
+
240
+ def verify_tag(ctx: Context) -> List[str]:
241
+ _wait_until(lambda: git("rev-parse", f"{ctx.tag}^{{}}")[0] == 0, ctx,
242
+ f"release-publish.yml to create {ctx.tag}")
243
+ peeled = git("rev-parse", f"{ctx.tag}^{{}}")[1].strip()
244
+ main = _main_sha()
245
+ if peeled != main:
246
+ raise ReleaseError(
247
+ f"{ctx.tag} resolves to {peeled[:7]} but origin/main is {main[:7]}.\n"
248
+ "A tag on a commit whose version sites disagree with it is exactly "
249
+ "what cost v0.55.0. Do not move the tag: a pushed tag is a public "
250
+ "ref consumers may register a marketplace from. Release the next "
251
+ "patch version instead."
252
+ )
253
+ return [f"{ctx.tag} resolves to {peeled[:7]}, equal to origin/main"]
254
+
255
+
256
+ # --- phase 5: merge back into dev -------------------------------------------
257
+
258
+
259
+ def syncback_done(ctx: Context) -> bool:
260
+ return script("check-branch-sync.py")[0] == 0
261
+
262
+
263
+ def syncback(ctx: Context) -> List[str]:
264
+ branch = f"sync/{ctx.tag}-to-dev"
265
+ git("fetch", "origin")
266
+ if git("rev-parse", "--verify", branch)[0] != 0:
267
+ git("checkout", "-b", branch, "origin/dev", check=True)
268
+ else:
269
+ git("checkout", branch, check=True)
270
+ code, out, err = git("merge", "origin/main", "--no-edit")
271
+ if code != 0:
272
+ raise ReleaseError(
273
+ "the merge back into dev has conflicts:\n" + out + err +
274
+ "\nResolve them with main authoritative for anything a release "
275
+ "touches - version sites, generated adapters, manifests, the "
276
+ "OpenCode package - and keep dev's [Unreleased] entries above "
277
+ "main's published sections in CHANGELOG.md. Then run this again."
278
+ )
279
+ git("push", "-u", "origin", branch, check=True)
280
+ if not run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])[1].strip():
281
+ run(["gh", "pr", "create", "--base", "dev", "--head", branch,
282
+ "--title", f"Merge the published {ctx.tag} release back into dev",
283
+ "--body", "Step 5 of docs/RELEASING.md. Skipping it is silent at "
284
+ "the time and arms the next release to revert this one."], check=True)
285
+ number = run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])[1].strip()
286
+ run(["gh", "pr", "merge", number, "--auto", "--merge"])
287
+ return [f"sync pull request #{number} opened and armed"]
288
+
289
+
290
+ # --- phase 6: this machine's prepared-directory marketplace -----------------
291
+
292
+
293
+
294
+ def install_done(ctx: Context) -> bool:
295
+ return all(_client_version(name) == ctx.version for name in CLIENTS)
296
+
297
+
298
+ def install(ctx: Context) -> List[str]:
299
+ run([sys.executable, str(ROOT / "scripts" / "install-agent-envs.py"), "--clients", "all"])
300
+ # The exit code is not the answer: read each client back. A rollback that
301
+ # cannot validate reports failure while leaving the install intact, and an
302
+ # install that reports success can still be blocked on one client.
303
+ reported = {name: _client_version(name) for name in CLIENTS}
304
+ behind = [f"{n}={v or 'unreadable'}" for n, v in reported.items() if v != ctx.version]
305
+ if behind:
306
+ raise ReleaseError(
307
+ "these clients do not report the released version: " + ", ".join(behind) + "\n"
308
+ "On Windows a client that is running holds its own plugin directory: "
309
+ "an MCP server started with a relative command has that directory as "
310
+ "its working directory, which locks it. Close the client, confirm no "
311
+ "adr-mcp process survives it, then run this command again."
312
+ )
313
+ return [f"all three clients report {ctx.version}"]
314
+
315
+
316
+ class Phase(NamedTuple):
317
+ name: str
318
+ step: str
319
+ done: Callable[[Context], bool]
320
+ run: Callable[[Context], List[str]]
321
+
322
+
323
+ PHASES: Tuple[Phase, ...] = (
324
+ Phase("preflight", "0", preflight_done, preflight),
325
+ Phase("prepare", "1", prepare_done, prepare),
326
+ Phase("verify", "2", verify_done, verify),
327
+ Phase("land", "3", land_done, land),
328
+ Phase("tag", "3", verify_tag_done, verify_tag),
329
+ Phase("syncback", "4", syncback_done, syncback),
330
+ Phase("install", "6", install_done, install),
331
+ )
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env python3
2
+ """How the release driver talks to the outside world.
3
+
4
+ Split from release_phases.py along the seam ADR-010 asks for: this module is
5
+ process invocation and repository interrogation, that one is the sequence of
6
+ steps. Keeping them apart means a phase reads as the runbook step it mirrors,
7
+ with the Windows and PATH details out of the way.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ import shutil
14
+ import subprocess
15
+ import sys
16
+ import time
17
+ from pathlib import Path
18
+ from typing import Callable, NamedTuple, Optional, Sequence, Tuple
19
+
20
+ ROOT = Path(__file__).resolve().parent.parent
21
+ PACKAGE = "@rvdbreemen/adr-kit-opencode"
22
+ CLIENTS = ("claude", "codex", "copilot")
23
+
24
+
25
+ class ReleaseError(RuntimeError):
26
+ """A phase refused to continue. The message says what to do next."""
27
+
28
+
29
+ class Context(NamedTuple):
30
+ version: str
31
+ skip_tests: bool
32
+ timeout_min: int
33
+
34
+ @property
35
+ def tag(self) -> str:
36
+ return f"v{self.version}"
37
+
38
+ @property
39
+ def branch(self) -> str:
40
+ return f"release/v{self.version}"
41
+
42
+
43
+ def run(
44
+ cmd: Sequence[str],
45
+ *,
46
+ check: bool = False,
47
+ cwd: Optional[Path] = None,
48
+ ) -> Tuple[int, str, str]:
49
+ """Run a command and return (code, stdout, stderr), never raising on exit code.
50
+
51
+ Returning the code rather than raising is deliberate: most callers here are
52
+ asking a question ("is this already done?") where a non-zero answer is
53
+ information, not a failure.
54
+ """
55
+ argv = list(cmd)
56
+ # shutil.which applies PATHEXT, so `npm` finds npm.cmd on Windows. Without
57
+ # it subprocess raises FileNotFoundError for every shim on PATH.
58
+ resolved = shutil.which(argv[0])
59
+ if resolved is None:
60
+ return 127, "", f"{argv[0]}: not found on PATH"
61
+ proc = subprocess.run(
62
+ [resolved, *argv[1:]],
63
+ cwd=str(cwd or ROOT),
64
+ capture_output=True,
65
+ text=True,
66
+ encoding="utf-8",
67
+ errors="replace",
68
+ )
69
+ if check and proc.returncode != 0:
70
+ raise ReleaseError(
71
+ f"{' '.join(cmd)} failed ({proc.returncode})\n{proc.stdout}{proc.stderr}"
72
+ )
73
+ return proc.returncode, proc.stdout or "", proc.stderr or ""
74
+
75
+
76
+ def git(*args: str, check: bool = False) -> Tuple[int, str, str]:
77
+ return run(["git", *args], check=check)
78
+
79
+
80
+ def script(name: str, *args: str, check: bool = False) -> Tuple[int, str, str]:
81
+ return run([sys.executable, str(ROOT / "scripts" / name), *args], check=check)
82
+
83
+
84
+ def _clean_tree() -> bool:
85
+ return not git("status", "--porcelain")[1].strip()
86
+
87
+
88
+ def _version_everywhere(ctx: Context) -> bool:
89
+ return script("check-release-version.py", "--expect", ctx.tag)[0] == 0
90
+
91
+
92
+ def _main_sha() -> str:
93
+ git("fetch", "origin", "--tags")
94
+ return git("rev-parse", "origin/main")[1].strip()
95
+
96
+ def _wait_until(predicate: Callable[[], bool], ctx: Context, what: str) -> None:
97
+ deadline = time.monotonic() + ctx.timeout_min * 60
98
+ while time.monotonic() < deadline:
99
+ if predicate():
100
+ return
101
+ time.sleep(30)
102
+ raise ReleaseError(
103
+ f"gave up waiting for {what} after {ctx.timeout_min} minutes. Nothing is "
104
+ "broken: re-run this command once it has happened and the finished "
105
+ "phases will be skipped."
106
+ )
107
+
108
+
109
+ def _client_version(client: str) -> Optional[str]:
110
+ """Read the version a client reports, rather than trusting an exit code."""
111
+ listings = {
112
+ "claude": ["claude", "plugin", "list"],
113
+ "copilot": ["copilot", "plugin", "list"],
114
+ "codex": ["codex", "plugin", "list"],
115
+ }
116
+ code, out, _ = run(listings[client])
117
+ if code != 0:
118
+ return None
119
+ for line in out.splitlines():
120
+ if "adr-kit" in line.lower() or "version" in line.lower():
121
+ found = re.search(r"(\d+\.\d+\.\d+)", line)
122
+ if found:
123
+ return found.group(1)
124
+ return None
@@ -168,6 +168,11 @@ Enforcement coverage percent (from 2c) in the append-only trend log.
168
168
  Estimated cost: ~$0.10–0.30. Run now? (y/N)
169
169
  ```
170
170
 
171
+ Before printing it, run `"$ADR_KIT/bin/adr-substance" --estimate` and add
172
+ its line to the prompt: the section-substance check in 3a-bis costs one more
173
+ model call per Proposed ADR with written sections, and the user is agreeing
174
+ to that number too.
175
+
171
176
  And wait for an explicit `y` / `yes`. If the user says no (or presses Enter on the default), skip the LLM tier and stop at Step 4.
172
177
 
173
178
  - If `guardian.llm_autorun` is `true`, proceed without asking (user opted in explicitly in config).
@@ -187,6 +192,22 @@ Read `/tmp/guardian-suggest.json`.
187
192
 
188
193
  **Response (mix-by-finding-type: Missing ADR):** Passive. List candidates where `needs_adr=true` with `confidence >= medium`. Offer to author selected ones via the `adr-generator` subagent. User picks; never auto-create.
189
194
 
195
+ ### 3a-bis. Written sections that say nothing (adr-substance)
196
+
197
+ The deterministic checks report a missing, empty or `- TODO:` section. They
198
+ cannot tell "TBD", "see above" or generic prose from an answer. This step asks
199
+ the model, one isolated call per Proposed ADR (TASK-203):
200
+
201
+ ```bash
202
+ "$ADR_KIT/bin/adr-substance" --adr-dir docs/adr/ --json > /tmp/guardian-substance.json
203
+ ```
204
+
205
+ **Response (advisory):** For each finding, show the ADR, the section and the
206
+ quoted text, and offer `/adr-kit:grill ADR-NNN` to answer it. Nothing blocks:
207
+ the exit code is always 0, `adr-lint` and `adr accept` are unaffected, and a
208
+ `degraded` field means the model gave no usable answer for the ADRs it names,
209
+ not that they are fine.
210
+
190
211
  ### 3b. Full audit (adr-judge with LLM pass, one ADR at a time)
191
212
 
192
213
  The audit judges each ADR in an isolated call and stamps its verdict the moment
@@ -82,6 +82,24 @@ For violations, offer the same three resolution paths as `/adr-kit:judge` (new A
82
82
 
83
83
  If the user wants the semantic pass too, offer `--llm` as an explicit follow-up (costs money; same cost posture as `/adr-kit:judge`).
84
84
 
85
+ ### 3b. Is the decision implemented where it says it applies?
86
+
87
+ The judge answers "was a rule violated?", which is green when the rule checks nothing. Run the deterministic half first:
88
+
89
+ ```bash
90
+ "$ADR_KIT/bin/adr-judge" --check-scope --adr-dir docs/adr/ \
91
+ --repo-root "$(git rev-parse --show-toplevel)"
92
+ ```
93
+
94
+ Report each ADVISORY: an Enforcement `path_glob` that matches no tracked file can never fire.
95
+
96
+ Then check the half no tool can, for each Accepted ADR the range touches whose Decision enumerates cases or names targets:
97
+
98
+ - **Every enumerated case has code that tests it.** ADR-041 named five reasons a record is queue-eligible; the code tested one, and every check stayed green because each sentence of the ADR was true.
99
+ - **Every named target compiles the code path.** In one firmware project the mitigation call sat inside an `#if` that was 1 only on another board, so the target the ADR named never ran it. Look for preprocessor guards, feature flags and platform checks around the call sites.
100
+
101
+ Report a gap as an advisory finding with the ADR id, the case or target, and the file:line where it is missing. It does not block; it goes to the user like an enforcement finding.
102
+
85
103
  ## Step 4 - Discovery pass
86
104
 
87
105
  Two signals, cheapest first.
@@ -1,4 +1,4 @@
1
- <!-- adr-kit-guide v0.56.0 -->
1
+ <!-- adr-kit-guide v0.58.0 -->
2
2
  <!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
3
3
  <!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
4
4
 
@@ -210,7 +210,12 @@ Steps 3 and 4 may run in either order. Accepting first is the safer habit, becau
210
210
 
211
211
  Never edit Decision, Context, Consequences, or Alternatives of an Accepted/Deprecated ADR. Only the Status line and an appended Status History transition may change.
212
212
 
213
- **One thing the commands cannot recover.** An ADR authored before the `## Status History` convention has its acceptance date in the Status line and nowhere else. The lifecycle commands seed a recovered entry from that line before replacing it, recording `changed_by: unknown` and `changed_via: unrecorded` rather than inventing a signer. If the Status line does not yield both a status and a date, the command refuses instead of writing a history that silently omits the earlier transition — fix the line, then re-run.
213
+ **One thing the commands cannot recover.** An ADR authored before the `## Status History` convention has its acceptance date in the Status line and nowhere else. The lifecycle commands seed a recovered entry from that line before replacing it, recording `changed_by: unknown` and `changed_via: unrecorded` rather than inventing a signer. The recovered entry also carries the Status line verbatim in its `reason`, so anything the parser cannot turn into structure — a `Decision Maker:` attribution, a note about which release line the decision applied to — survives in the record rather than being discarded for not fitting a field.
214
+
215
+ There are two ways the command refuses rather than rewriting, and both exist so it never writes a history that silently omits an earlier transition:
216
+
217
+ - The Status line does not yield both a status and a date. Fix the line, then re-run.
218
+ - The Status line carries a **second** transition the recovered one does not account for, for example `Superseded by ADR-088, 2026-08-07. Originally Accepted, 2026-05-08.` Only the leading status and the first date are read, so the command can see that it is about to discard something without knowing what. Write the `## Status History` block first, recording each transition the line names, then re-run.
214
219
 
215
220
  ## Code review checks
216
221
 
@@ -2,7 +2,7 @@
2
2
  "_comment": "ADR Guardian SessionStart hook entry for .claude/settings.json",
3
3
  "_note": "Add this entry under hooks.SessionStart[0].hooks[] in the project's .claude/settings.json.",
4
4
  "_remove_marker": "adr-guardian-session-start",
5
- "_wrapper_version": "0.56.0",
5
+ "_wrapper_version": "0.58.0",
6
6
  "type": "command",
7
7
  "command": "ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1) && [ -n \"$ADR_KIT\" ] && _PY=$(command -v python3 || command -v python || command -v py) && [ -n \"$_PY\" ] && \"$_PY\" \"$ADR_KIT/bin/adr-guardian\" check 2>/dev/null || true",
8
8
  "timeout": 10
@@ -52,7 +52,7 @@ set -e
52
52
  # freezes at install time. adr-guardian compares this stamp against the
53
53
  # installed plugin version and nudges /adr-kit:upgrade when the wrapper lags.
54
54
  # Maintained by scripts/bump-version.py; do not edit by hand.
55
- ADR_KIT_WRAPPER_VERSION="0.56.0"
55
+ ADR_KIT_WRAPPER_VERSION="0.58.0"
56
56
 
57
57
  if [ "${ADR_KIT_HOOK_DISABLE:-0}" = "1" ]; then
58
58
  echo "[adr-kit] hook disabled for this commit (ADR_KIT_HOOK_DISABLE=1)" >&2
@@ -13,6 +13,6 @@ jobs:
13
13
  - uses: actions/checkout@v4
14
14
  with:
15
15
  fetch-depth: 0
16
- - uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@v0.56.0
16
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@v0.58.0
17
17
  with:
18
18
  adr-dir: docs/adr