@rvdbreemen/adr-kit-opencode 0.57.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 +47 -18
- package/bin/adr-audit +41 -2
- package/bin/adr-judge +146 -4
- package/bin/adr-judge-precommit +30 -12
- package/bin/adr-lint +96 -18
- package/bin/adr-migrate +25 -5
- package/bin/adr-substance +310 -0
- package/bin/adr_format.py +112 -51
- package/bin/adr_llm.py +68 -8
- package/bin/adr_readiness.py +3 -0
- 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/skills/guardian/SKILL.md +21 -0
- package/skills/review/SKILL.md +18 -0
- package/templates/adr-kit-guide.md +1 -1
- 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
package/bin/adr_format.py
CHANGED
|
@@ -10,7 +10,7 @@ from __future__ import annotations
|
|
|
10
10
|
import re
|
|
11
11
|
from functools import lru_cache
|
|
12
12
|
from pathlib import Path
|
|
13
|
-
from typing import Dict, List, Optional, Tuple
|
|
13
|
+
from typing import Any, Dict, List, Optional, Tuple
|
|
14
14
|
|
|
15
15
|
|
|
16
16
|
DEFAULT_PROFILE = "madr"
|
|
@@ -361,38 +361,100 @@ def h2_headings(text: str) -> List[str]:
|
|
|
361
361
|
return headings
|
|
362
362
|
|
|
363
363
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
364
|
+
_OPEN_QUESTION_BULLET_RE = re.compile(r"^(?P<indent>[ \t]*)[-*+]\s+")
|
|
365
|
+
_NO_OPEN_QUESTIONS = {"none", "no open questions", "no unresolved questions"}
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
def open_question_items(section: str) -> List[Dict[str, Any]]:
|
|
369
|
+
"""Group an Open Questions section into items, one per question.
|
|
370
|
+
|
|
371
|
+
A question is a top-level bullet plus every line that belongs to it: an
|
|
372
|
+
indented continuation, a nested bullet, or an unindented line that
|
|
373
|
+
directly follows it (a Markdown lazy continuation). A paragraph outside
|
|
374
|
+
any bullet is an item too, and counts as a question only when one of its
|
|
375
|
+
lines ends in `?`. Reading line by line instead split a wrapped question
|
|
376
|
+
into fragments, and a fragment ending in `?` became a question nobody
|
|
377
|
+
could answer (TASK-194).
|
|
378
|
+
|
|
379
|
+
Each item carries `start`/`end` (inclusive indexes into
|
|
380
|
+
`section.splitlines()`), `question` (its identity, see
|
|
381
|
+
`_normalise_question`), `text` (the readable form, markup kept),
|
|
382
|
+
`answered`, `is_question`, and `placeholder` (a
|
|
383
|
+
"None."-style line that says there is nothing open).
|
|
384
|
+
"""
|
|
385
|
+
lines = section.splitlines()
|
|
386
|
+
groups: List[Dict[str, Any]] = []
|
|
387
|
+
current: Optional[Dict[str, Any]] = None
|
|
388
|
+
base: Optional[int] = None
|
|
389
|
+
previous_blank = True
|
|
390
|
+
in_fence = False
|
|
391
|
+
for index, raw in enumerate(lines):
|
|
392
|
+
stripped = raw.strip()
|
|
393
|
+
if stripped.startswith("```"):
|
|
394
|
+
in_fence = not in_fence
|
|
395
|
+
current = None
|
|
373
396
|
continue
|
|
374
|
-
|
|
375
|
-
if normalized.casefold().rstrip(".") in {
|
|
376
|
-
"none",
|
|
377
|
-
"no open questions",
|
|
378
|
-
"no unresolved questions",
|
|
379
|
-
}:
|
|
397
|
+
if in_fence:
|
|
380
398
|
continue
|
|
381
|
-
if
|
|
399
|
+
if not stripped:
|
|
400
|
+
previous_blank = True
|
|
382
401
|
continue
|
|
383
|
-
if
|
|
402
|
+
if stripped.startswith(("<!--", "-->")):
|
|
384
403
|
continue
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
404
|
+
indent = len(raw) - len(raw.lstrip())
|
|
405
|
+
bullet = _OPEN_QUESTION_BULLET_RE.match(raw)
|
|
406
|
+
if bullet and (base is None or indent <= base):
|
|
407
|
+
base = indent if base is None else base
|
|
408
|
+
current = {"start": index, "end": index, "bullet": True}
|
|
409
|
+
groups.append(current)
|
|
410
|
+
elif current is not None and (indent > (base or 0) or not previous_blank):
|
|
411
|
+
current["end"] = index
|
|
390
412
|
else:
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
413
|
+
current = {"start": index, "end": index, "bullet": False}
|
|
414
|
+
groups.append(current)
|
|
415
|
+
previous_blank = False
|
|
416
|
+
|
|
417
|
+
items: List[Dict[str, Any]] = []
|
|
418
|
+
for group in groups:
|
|
419
|
+
own = lines[group["start"] : group["end"] + 1]
|
|
420
|
+
first = re.sub(r"^\s*[-*+]\s+", "", own[0].strip()) if group["bullet"] else own[0].strip()
|
|
421
|
+
joined = " ".join(
|
|
422
|
+
[own[0].strip()]
|
|
423
|
+
+ [re.sub(r"^[-*+]\s+", "", line.strip()) for line in own[1:]]
|
|
424
|
+
)
|
|
425
|
+
answered = bool(re.match(r"^\[[xX]\]\s+", first)) or bool(
|
|
426
|
+
re.match(r"^(?:answered|resolved)\s*:", first, re.IGNORECASE)
|
|
427
|
+
)
|
|
428
|
+
placeholder = len(own) == 1 and first.casefold().rstrip(".") in _NO_OPEN_QUESTIONS
|
|
429
|
+
is_question = group["bullet"] or any(line.rstrip().endswith("?") for line in own)
|
|
430
|
+
readable = re.sub(r"^\s*[-*+]\s+", "", joined)
|
|
431
|
+
readable = re.sub(r"^\[[ xX]\]\s*", "", readable)
|
|
432
|
+
readable = re.split(r"\s+[—-]{1,2}\s+\*\*Answered\b", readable)[0]
|
|
433
|
+
items.append(
|
|
434
|
+
{
|
|
435
|
+
"start": group["start"],
|
|
436
|
+
"end": group["end"],
|
|
437
|
+
"question": _normalise_question(joined),
|
|
438
|
+
# The same words with their markup, for showing and searching.
|
|
439
|
+
"text": re.sub(r"\s+", " ", readable).strip(),
|
|
440
|
+
"answered": answered,
|
|
441
|
+
"is_question": is_question and not placeholder,
|
|
442
|
+
"placeholder": placeholder,
|
|
443
|
+
}
|
|
444
|
+
)
|
|
445
|
+
return items
|
|
446
|
+
|
|
447
|
+
|
|
448
|
+
def unresolved_open_questions(text: str) -> List[str]:
|
|
449
|
+
"""Return stable unresolved items from the optional Open Questions role."""
|
|
450
|
+
section = section_text(text, "open_questions")
|
|
451
|
+
if not section:
|
|
452
|
+
return []
|
|
453
|
+
questions = [
|
|
454
|
+
item["question"]
|
|
455
|
+
for item in open_question_items(section)
|
|
456
|
+
if item["is_question"] and not item["answered"] and item["question"]
|
|
457
|
+
]
|
|
396
458
|
return sorted(dict.fromkeys(questions), key=str.casefold)
|
|
397
459
|
|
|
398
460
|
|
|
@@ -424,30 +486,13 @@ def all_open_questions(text: str) -> "Dict[str, bool]":
|
|
|
424
486
|
if not section:
|
|
425
487
|
return {}
|
|
426
488
|
found: Dict[str, bool] = {}
|
|
427
|
-
for
|
|
428
|
-
|
|
429
|
-
if not line or line.startswith(("```", "<!--", "-->")):
|
|
430
|
-
continue
|
|
431
|
-
stripped = re.sub(r"^\s*[-*+]\s+", "", line).strip()
|
|
432
|
-
if stripped.casefold().rstrip(".") in {
|
|
433
|
-
"none",
|
|
434
|
-
"no open questions",
|
|
435
|
-
"no unresolved questions",
|
|
436
|
-
}:
|
|
437
|
-
continue
|
|
438
|
-
answered = bool(re.match(r"^\[[xX]\]\s+", stripped))
|
|
439
|
-
if not answered and not (
|
|
440
|
-
re.match(r"^\[\s\]\s+", stripped)
|
|
441
|
-
or re.match(r"^[-*+]\s+", line)
|
|
442
|
-
or stripped.endswith("?")
|
|
443
|
-
):
|
|
444
|
-
continue
|
|
445
|
-
question = _normalise_question(line)
|
|
446
|
-
if not question:
|
|
489
|
+
for item in open_question_items(section):
|
|
490
|
+
if not (item["is_question"] or item["answered"]) or not item["question"]:
|
|
447
491
|
continue
|
|
448
492
|
# An answered form wins: a question listed twice, once each way, is
|
|
449
493
|
# answered.
|
|
450
|
-
|
|
494
|
+
question = item["question"]
|
|
495
|
+
found[question] = found.get(question, False) or item["answered"]
|
|
451
496
|
return found
|
|
452
497
|
|
|
453
498
|
|
|
@@ -851,6 +896,11 @@ def _unwritten_required_sections(text: str, profile: str) -> List[tuple]:
|
|
|
851
896
|
decision: an imported record must not fail a blocking gate on arrival. Only
|
|
852
897
|
a caller that can tell the two apart can say something true about either.
|
|
853
898
|
"""
|
|
899
|
+
return [(title, kind) for _role, title, kind in _unwritten_required_roles(text, profile)]
|
|
900
|
+
|
|
901
|
+
|
|
902
|
+
def _unwritten_required_roles(text: str, profile: str) -> List[tuple]:
|
|
903
|
+
"""(role, heading, kind) for each required heading nobody has written yet."""
|
|
854
904
|
normalized = normalize_profile(profile)
|
|
855
905
|
unwritten: List[tuple] = []
|
|
856
906
|
for role in PROFILE_REQUIRED_ROLES[normalized]:
|
|
@@ -869,12 +919,23 @@ def _unwritten_required_sections(text: str, profile: str) -> List[tuple]:
|
|
|
869
919
|
if visible and not all(_PLACEHOLDER_LINE_RE.match(ln) for ln in visible):
|
|
870
920
|
continue
|
|
871
921
|
if not visible and not body.strip():
|
|
872
|
-
unwritten.append((title, SECTION_EMPTY))
|
|
922
|
+
unwritten.append((role, title, SECTION_EMPTY))
|
|
873
923
|
else:
|
|
874
|
-
unwritten.append((title, SECTION_PLACEHOLDER))
|
|
924
|
+
unwritten.append((role, title, SECTION_PLACEHOLDER))
|
|
875
925
|
return unwritten
|
|
876
926
|
|
|
877
927
|
|
|
928
|
+
def unfilled_required_roles(text: str, profile: str) -> List[str]:
|
|
929
|
+
"""The roles behind `unfilled_required_sections`.
|
|
930
|
+
|
|
931
|
+
Two profiles name the same role differently ("Context" against "Context
|
|
932
|
+
and Problem Statement"), so a before/after comparison across a profile
|
|
933
|
+
conversion has to compare roles; comparing titles blamed the conversion
|
|
934
|
+
for every hole the source already had (TASK-201).
|
|
935
|
+
"""
|
|
936
|
+
return [role for role, _title, _kind in _unwritten_required_roles(text, profile)]
|
|
937
|
+
|
|
938
|
+
|
|
878
939
|
def unfilled_required_sections(text: str, profile: str) -> List[str]:
|
|
879
940
|
"""Required headings present in `text` that nobody has actually written yet.
|
|
880
941
|
|
package/bin/adr_llm.py
CHANGED
|
@@ -22,8 +22,10 @@ import os
|
|
|
22
22
|
import re
|
|
23
23
|
import shlex
|
|
24
24
|
import shutil
|
|
25
|
+
import signal
|
|
25
26
|
import subprocess
|
|
26
27
|
import sys
|
|
28
|
+
import tempfile
|
|
27
29
|
from typing import Dict, List, Optional, Tuple
|
|
28
30
|
|
|
29
31
|
# Which entry point is running, used only as the warning prefix. A plain module
|
|
@@ -136,6 +138,71 @@ class LLMBackend:
|
|
|
136
138
|
raise NotImplementedError
|
|
137
139
|
|
|
138
140
|
|
|
141
|
+
def _kill_tree(proc: "subprocess.Popen[bytes]") -> None:
|
|
142
|
+
"""Stop `proc` and everything it started, as far as the platform allows.
|
|
143
|
+
|
|
144
|
+
POSIX: the CLI runs in its own session, so its process group is the tree.
|
|
145
|
+
Windows: `taskkill /T` walks the tree from the live parent. A grandchild
|
|
146
|
+
whose parent has already exited is outside that tree and survives; the
|
|
147
|
+
caller still returns on time, because nothing waits on its pipes.
|
|
148
|
+
"""
|
|
149
|
+
if os.name == "nt":
|
|
150
|
+
try:
|
|
151
|
+
subprocess.run(
|
|
152
|
+
["taskkill", "/T", "/F", "/PID", str(proc.pid)],
|
|
153
|
+
stdin=subprocess.DEVNULL,
|
|
154
|
+
stdout=subprocess.DEVNULL,
|
|
155
|
+
stderr=subprocess.DEVNULL,
|
|
156
|
+
timeout=10,
|
|
157
|
+
check=False,
|
|
158
|
+
)
|
|
159
|
+
except (OSError, subprocess.SubprocessError):
|
|
160
|
+
pass
|
|
161
|
+
else:
|
|
162
|
+
try:
|
|
163
|
+
os.killpg(proc.pid, signal.SIGKILL)
|
|
164
|
+
except OSError:
|
|
165
|
+
pass
|
|
166
|
+
try:
|
|
167
|
+
proc.kill()
|
|
168
|
+
except OSError:
|
|
169
|
+
pass
|
|
170
|
+
try:
|
|
171
|
+
proc.wait(timeout=5)
|
|
172
|
+
except subprocess.TimeoutExpired:
|
|
173
|
+
pass
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def run_cli(cmd: List[str], input_text: str, timeout_s: float) -> subprocess.CompletedProcess:
|
|
177
|
+
"""Run a host CLI with a wall-clock bound that its children cannot defeat.
|
|
178
|
+
|
|
179
|
+
`subprocess.run(capture_output=True, timeout=N)` kills only the direct
|
|
180
|
+
child and then waits for EOF on the pipes, so a grandchild that inherited
|
|
181
|
+
stdout held the call open until it exited: measured at 60 s for a 2 s
|
|
182
|
+
timeout (TASK-210). Output therefore goes to temporary files, which nobody
|
|
183
|
+
waits on, and a timeout takes the whole process tree down. Raises
|
|
184
|
+
`subprocess.TimeoutExpired` on timeout, like `subprocess.run`.
|
|
185
|
+
"""
|
|
186
|
+
session = {"start_new_session": True} if os.name != "nt" else {}
|
|
187
|
+
with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
|
|
188
|
+
proc = subprocess.Popen(
|
|
189
|
+
cmd, stdin=subprocess.PIPE, stdout=out, stderr=err, **session
|
|
190
|
+
)
|
|
191
|
+
try:
|
|
192
|
+
proc.communicate(input=input_text.encode("utf-8"), timeout=timeout_s)
|
|
193
|
+
except subprocess.TimeoutExpired:
|
|
194
|
+
_kill_tree(proc)
|
|
195
|
+
raise
|
|
196
|
+
out.seek(0)
|
|
197
|
+
err.seek(0)
|
|
198
|
+
return subprocess.CompletedProcess(
|
|
199
|
+
cmd,
|
|
200
|
+
proc.returncode,
|
|
201
|
+
out.read().decode("utf-8", errors="replace"),
|
|
202
|
+
err.read().decode("utf-8", errors="replace"),
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
|
|
139
206
|
class SubprocessBackend(LLMBackend):
|
|
140
207
|
"""Spawn a client CLI, feed it the prompt on stdin, read stdout.
|
|
141
208
|
|
|
@@ -167,14 +234,7 @@ class SubprocessBackend(LLMBackend):
|
|
|
167
234
|
|
|
168
235
|
def judge(self, prompt: str, timeout_s: int, adr_id: str) -> Optional[str]:
|
|
169
236
|
try:
|
|
170
|
-
result =
|
|
171
|
-
self.cmd,
|
|
172
|
-
input=prompt,
|
|
173
|
-
capture_output=True,
|
|
174
|
-
text=True,
|
|
175
|
-
encoding="utf-8",
|
|
176
|
-
timeout=timeout_s,
|
|
177
|
-
)
|
|
237
|
+
result = run_cli(self.cmd, prompt, timeout_s)
|
|
178
238
|
except subprocess.TimeoutExpired:
|
|
179
239
|
_warn(
|
|
180
240
|
f"LLM call timed out after {timeout_s}s on {adr_id}; skipping "
|
package/bin/adr_readiness.py
CHANGED
|
@@ -405,6 +405,9 @@ def readiness_for_record(
|
|
|
405
405
|
"title": record["title"],
|
|
406
406
|
"path": normalize_path(str(record["path"])),
|
|
407
407
|
"status": record["status"],
|
|
408
|
+
# The latest status-history date, else the frontmatter date, as the
|
|
409
|
+
# catalog resolved it. The guardian queue ranks age on it (TASK-200).
|
|
410
|
+
"date": record.get("date"),
|
|
408
411
|
"format": record["format"],
|
|
409
412
|
"evaluated_on": evaluated_on.isoformat(),
|
|
410
413
|
"classification": classification,
|
package/package.json
CHANGED
|
@@ -166,6 +166,12 @@
|
|
|
166
166
|
"minimum": 1,
|
|
167
167
|
"default": 120
|
|
168
168
|
},
|
|
169
|
+
"llm_pass_timeout_seconds": {
|
|
170
|
+
"type": "integer",
|
|
171
|
+
"description": "Ceiling in seconds for the whole per-commit LLM pass, across every llm_judge ADR it calls. Default 600. Each call gets the smaller of llm_timeout_seconds and the time left; ADRs reached after the ceiling get no verdict, and the attestation marks the pass degraded and names them (ADR-038). The commit is not blocked by the ceiling: the declarative pass still decides.",
|
|
172
|
+
"minimum": 1,
|
|
173
|
+
"default": 600
|
|
174
|
+
},
|
|
169
175
|
"pre_commit_timeout_ms": {
|
|
170
176
|
"type": "integer",
|
|
171
177
|
"description": "Performance budget in milliseconds for the non-blocking pre-commit perf WARN (TASK-712 performance-bounded hooks; surfaced in bin/adr-judge --profile). When the pre-commit pass runs longer than this and warn_on_exceed is true, a non-blocking WARN is printed; the commit is never blocked by this budget. Distinct from llm_timeout_seconds, which is the hard per-call LLM call timeout. Default 5000.",
|
|
@@ -15,6 +15,12 @@ from client_certification import support_matrix, validate
|
|
|
15
15
|
from client_evidence import CertificationError, assemble_native_bundle, write_bundle
|
|
16
16
|
|
|
17
17
|
|
|
18
|
+
# ADR-010: release evidence older than this is stale. A simulated fixture has a
|
|
19
|
+
# fixed date, so the CI check that renders docs/client-support.md from it
|
|
20
|
+
# passes a wider window explicitly; release evidence cannot.
|
|
21
|
+
CERTIFICATION_MAX_AGE_DAYS = 30
|
|
22
|
+
|
|
23
|
+
|
|
18
24
|
def main(argv: list[str] | None = None) -> int:
|
|
19
25
|
parser = argparse.ArgumentParser()
|
|
20
26
|
parser.add_argument("--check", action="store_true", help="fail when generated files drift")
|
|
@@ -24,6 +30,15 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
24
30
|
parser.add_argument("--certify", type=Path)
|
|
25
31
|
parser.add_argument("--candidate-commit")
|
|
26
32
|
parser.add_argument("--release-candidate", action="store_true")
|
|
33
|
+
parser.add_argument(
|
|
34
|
+
"--max-age-days",
|
|
35
|
+
type=int,
|
|
36
|
+
default=CERTIFICATION_MAX_AGE_DAYS,
|
|
37
|
+
help=(
|
|
38
|
+
"oldest acceptable contract date for --certify; only a simulated "
|
|
39
|
+
"bundle may relax it, never --release-candidate evidence"
|
|
40
|
+
),
|
|
41
|
+
)
|
|
27
42
|
parser.add_argument("--support-output", type=Path)
|
|
28
43
|
parser.add_argument(
|
|
29
44
|
"--assemble-native-evidence",
|
|
@@ -82,7 +97,11 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
82
97
|
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
83
98
|
print(f"certification bundle error: {exc}", file=sys.stderr)
|
|
84
99
|
return 2
|
|
85
|
-
|
|
100
|
+
if args.release_candidate and args.max_age_days != CERTIFICATION_MAX_AGE_DAYS:
|
|
101
|
+
parser.error("--max-age-days cannot relax --release-candidate evidence")
|
|
102
|
+
errors = validate(
|
|
103
|
+
bundle, args.candidate_commit, args.release_candidate, args.max_age_days
|
|
104
|
+
)
|
|
86
105
|
if args.support_output and not errors:
|
|
87
106
|
payload = support_matrix(bundle)
|
|
88
107
|
if args.check:
|
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
|
|
|
@@ -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
|