@rvdbreemen/adr-kit-opencode 0.55.1 → 0.57.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,117 @@
1
+ #!/usr/bin/env python3
2
+ """The one step of a release npm will not let any tool finish.
3
+
4
+ npm requires proof of presence to publish, so a staged package waits for the
5
+ maintainer's 2FA no matter what drives the release. That makes this the seam
6
+ between what ADR-042 automates and what it deliberately leaves to a person,
7
+ which is why it is its own module rather than an eighth entry in PHASES.
8
+
9
+ The distinction the rest of the driver depends on is between a version that is
10
+ still staged and a version that is published while `latest` names an older
11
+ release. From outside they look the same - `npm install` gives you the wrong
12
+ package either way - but only the second is a fault, and only the second has a
13
+ remedy the maintainer can apply without npm's approval flow.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import sys
19
+ from pathlib import Path
20
+
21
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
22
+
23
+ from release_shell import PACKAGE, Context, run # noqa: E402
24
+
25
+
26
+ DONE = "done"
27
+ WRONG_LATEST = "wrong-latest"
28
+ STAGED = "staged"
29
+ UNREACHABLE = "unreachable"
30
+
31
+
32
+ def _dist_tags(ctx: Context) -> dict | None:
33
+ """None means npm did not answer, which is not the same as an empty answer."""
34
+ code, out, _ = run(["npm", "view", PACKAGE, "dist-tags", "--json", "--prefer-online"])
35
+ if code != 0:
36
+ return None
37
+ try:
38
+ parsed = json.loads(out)
39
+ except json.JSONDecodeError:
40
+ return None
41
+ return parsed if isinstance(parsed, dict) else None
42
+
43
+
44
+ def npm_state(ctx: Context) -> str:
45
+ """Which of the four things npm is currently doing about this version.
46
+
47
+ Deciding this in one place is what keeps the driver's report and its exit
48
+ code from disagreeing, which is the defect this function replaced: the
49
+ predicate existed and nothing wired it to a failure.
50
+
51
+ A registry that does not answer gets its own state rather than being folded
52
+ into one of the others. Reporting "awaiting your 2FA" because npm was down
53
+ would be a guess presented as a reading, and it is the reading a maintainer
54
+ would act on.
55
+ """
56
+ tags = _dist_tags(ctx)
57
+ if tags is None:
58
+ return UNREACHABLE
59
+ if tags.get("latest") == ctx.version:
60
+ return DONE
61
+ return WRONG_LATEST if npm_published(ctx) else STAGED
62
+
63
+
64
+ def npm_published(ctx: Context) -> bool:
65
+ """Is the version on the registry at all, whatever `latest` points at?
66
+
67
+ This separates the two npm states that look identical from outside. A
68
+ version still staged is a release waiting on the maintainer's 2FA, which is
69
+ the normal end of a release rather than a fault. A version that IS
70
+ published while `latest` names an older release is the v0.55.1 defect:
71
+ `npm install` quietly serves the wrong package. Only the second is a
72
+ failure, and telling the maintainer to go and approve something that is
73
+ already approved sends them to the one place that cannot fix it.
74
+ """
75
+ code, out, _ = run(["npm", "view", PACKAGE, "versions", "--json", "--prefer-online"])
76
+ if code != 0:
77
+ return False
78
+ try:
79
+ versions = json.loads(out)
80
+ except json.JSONDecodeError:
81
+ return False
82
+ if isinstance(versions, str): # npm returns a bare string for a lone version
83
+ versions = [versions]
84
+ return isinstance(versions, list) and ctx.version in versions
85
+
86
+
87
+ def npm_wrong_latest(ctx: Context) -> str:
88
+ latest = (_dist_tags(ctx) or {}).get("latest") or "nothing this driver could read"
89
+ return (
90
+ f"{ctx.version} is published on npm, but `latest` names {latest}.\n\n"
91
+ f"`npm install {PACKAGE}` therefore serves {latest} rather than the "
92
+ f"release. npm sets `latest` to the version published LAST, not the "
93
+ f"highest, so approving staged versions out of order does exactly "
94
+ f"this. It left 0.55.1 released while `latest` read 0.54.0 for a "
95
+ f"week, and nothing surfaced it.\n\n"
96
+ f" npm dist-tag add {PACKAGE}@{ctx.version} latest\n"
97
+ f" npm dist-tag ls {PACKAGE} # latest must read {ctx.version}\n\n"
98
+ f"Read the first command's own exit code. Piping it into `tail` "
99
+ f"reports tail's status instead, and npm's failure disappears."
100
+ )
101
+
102
+
103
+ def npm_instructions(ctx: Context) -> str:
104
+ return (
105
+ f"The OpenCode package for {ctx.tag} is STAGED, not published. npm "
106
+ f"requires proof of presence, so no tool can finish this.\n\n"
107
+ f" npm login\n"
108
+ f" npm stage list {PACKAGE}\n"
109
+ f" npm stage view <stage-id> # inspect the tarball first\n"
110
+ f" npm stage approve <stage-id> # prompts for your OTP\n\n"
111
+ f" or from the browser: https://www.npmjs.com/staged-packages\n\n"
112
+ f"If more than one version is staged, approve them in ASCENDING order. "
113
+ f"npm sets `latest` to the version published LAST, not the highest. On "
114
+ f"2026-08-26 approving 0.55.1, then 0.53.0, then 0.54.0 left `latest` on "
115
+ f"0.54.0 while 0.55.1 was the release.\n\n"
116
+ f" npm dist-tag ls {PACKAGE} # latest must read {ctx.version}"
117
+ )
@@ -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
@@ -1,4 +1,4 @@
1
- <!-- adr-kit-guide v0.55.1 -->
1
+ <!-- adr-kit-guide v0.57.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.55.1",
5
+ "_wrapper_version": "0.57.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.55.1"
55
+ ADR_KIT_WRAPPER_VERSION="0.57.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.37.0
16
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@v0.57.0
17
17
  with:
18
18
  adr-dir: docs/adr