@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.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +5 -3
- package/bin/adr +79 -20
- package/bin/adr-audit +41 -2
- package/bin/adr-judge +146 -4
- package/bin/adr-judge-precommit +30 -12
- package/bin/adr-lint +136 -20
- package/bin/adr-migrate +48 -0
- package/bin/adr-substance +310 -0
- package/bin/adr_format.py +183 -49
- package/bin/adr_guardian_queue.py +15 -1
- package/bin/adr_llm.py +68 -8
- package/bin/adr_quality_core.py +19 -2
- package/bin/adr_readiness.py +62 -1
- package/instructions/ADR-guide.md +1 -1
- package/package.json +1 -1
- package/schemas/adr-kit-config.schema.json +6 -0
- package/schemas/adr-readiness.schema.json +1 -0
- package/scripts/build-client-adapters.py +20 -1
- package/scripts/check-changelog-sections.py +198 -0
- package/scripts/release.py +171 -0
- package/scripts/release_npm.py +117 -0
- package/scripts/release_phases.py +331 -0
- package/scripts/release_shell.py +124 -0
- package/skills/guardian/SKILL.md +21 -0
- package/skills/review/SKILL.md +18 -0
- package/templates/adr-kit-guide.md +7 -2
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
|
@@ -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
|
package/skills/guardian/SKILL.md
CHANGED
|
@@ -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
|
package/skills/review/SKILL.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|