@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
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "adr-kit",
|
|
3
3
|
"description": "Architecture Decision Record toolkit for AI coding agents: bootstrap, multi-format authoring, bounded deterministic enforcement, lifecycle workflows, context injection, generated graph indexes, and local health checks.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.58.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Robert van den Breemen",
|
|
7
7
|
"url": "https://github.com/rvdbreemen"
|
package/README.md
CHANGED
|
@@ -314,7 +314,7 @@ For another project, use the published package:
|
|
|
314
314
|
```json
|
|
315
315
|
{
|
|
316
316
|
"$schema": "https://opencode.ai/config.json",
|
|
317
|
-
"plugin": ["@rvdbreemen/adr-kit-opencode@0.
|
|
317
|
+
"plugin": ["@rvdbreemen/adr-kit-opencode@0.58.0"]
|
|
318
318
|
}
|
|
319
319
|
```
|
|
320
320
|
|
|
@@ -419,6 +419,8 @@ Three layers, each with a clear path:
|
|
|
419
419
|
- **The Guardian (`bin/adr-guardian`, `/adr-kit:guardian`)**: a session-start staleness detector with two tiers. The cheap tier (daily, free) checks for code drift against Enforcement rules, retirement candidates, lint health, and refreshes a bounded Proposed-ADR work queue. SessionStart reads only that local 24-hour cache and offers at most three next actions; it never scans or starts an interview in the hook. The LLM tier (bi-weekly, asks before spending) hunts for missing ADRs and runs the full model-reviewed audit. Findings get mixed responses by type: drift is surfaced loudly with file:line, missing decisions are offered for authoring, stale ADRs get a retirement draft for review. Never runs in the background, never spends without asking.
|
|
420
420
|
- **Team mode (v0.22.0+)**: a weekly CI cron sweep maintains a single "ADR guardian audit" tracking issue (created on findings, updated, closed when clean) so the whole team sees ADR health, not just whoever opened a session today. Copy `templates/github-workflows/adr-guardian-audit.yml` into your repo.
|
|
421
421
|
- **Trend history (v0.29.0+)**: every sweep appends to a 52-entry trend log, and the nudge shows the delta: `trend: drift 2 -> 0, retire 1 -> 2, coverage 40% -> 45%`. A KPI with memory, not a snapshot.
|
|
422
|
+
- **Sections that say nothing (v0.58.0+)**: in the LLM tier, `bin/adr-substance` asks the model whether each written section of a Proposed ADR answers its heading, and reports "TBD", "see above" and generic prose with the author's own words quoted. One call per Proposed ADR, counted in the cost prompt; advisory only.
|
|
423
|
+
- **Rules that check nothing (`adr-judge --check-scope`, v0.58.0+)**: names every Enforcement rule of an Accepted ADR whose `path_glob` matches no tracked file, because such a rule stays green forever. `adr-audit --whole-codebase` includes it as advisory.
|
|
422
424
|
- **Health dashboard (`adr-audit status`)**: totals, status breakdown, average age, enforcement health, retirement candidates, retrieval probe results, Accepted-binding metadata completeness, and the **Enforcement coverage percentage** of your Accepted ADRs. JSON, markdown, or table.
|
|
423
425
|
- **Quality scoring (`adr-audit quality`)**: grades every ADR A to D across the four gates (Completeness 40%, Evidence 20%, Clarity 20%, Consistency 20%), with per-gate issue codes. Exits 1 below grade B, so you can gate CI on ADR quality.
|
|
424
426
|
- **Generated index refresh (`bin/adr-index docs/adr/`)**: atomically rebuilds the sentinel-owned `docs/adr/README.md` block plus `ADR-INDEX.md` and `ADR-INDEX.json`. `--check` exits non-zero when any generated view is missing or stale, or duplicate ADR ids exist. Use `--format graph --adr-dir docs/adr` to inspect the graph without writing.
|
|
@@ -671,7 +673,7 @@ jobs:
|
|
|
671
673
|
- uses: actions/checkout@v4
|
|
672
674
|
with:
|
|
673
675
|
fetch-depth: 0 # both sides of the diff must be available
|
|
674
|
-
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.
|
|
676
|
+
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.58.0
|
|
675
677
|
with:
|
|
676
678
|
adr-dir: docs/adr/
|
|
677
679
|
```
|
|
@@ -685,7 +687,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
|
|
|
685
687
|
```yaml
|
|
686
688
|
repos:
|
|
687
689
|
- repo: https://github.com/rvdbreemen/adr-kit
|
|
688
|
-
rev: v0.
|
|
690
|
+
rev: v0.58.0
|
|
689
691
|
hooks:
|
|
690
692
|
- id: adr-judge
|
|
691
693
|
```
|
package/bin/adr
CHANGED
|
@@ -18,6 +18,9 @@ from pathlib import Path
|
|
|
18
18
|
from typing import Dict, List, Optional, Tuple
|
|
19
19
|
|
|
20
20
|
_BIN_DIR = Path(__file__).resolve().parent
|
|
21
|
+
# Ceiling for the quality and lint runs `accept` waits on. Both finish in
|
|
22
|
+
# seconds; without a ceiling a lint that never returned held `accept` forever.
|
|
23
|
+
LIFECYCLE_TOOL_TIMEOUT_S = 120
|
|
21
24
|
|
|
22
25
|
|
|
23
26
|
def _load_sibling(name: str):
|
|
@@ -52,6 +55,7 @@ from adr_format import (
|
|
|
52
55
|
AdrFormatError,
|
|
53
56
|
configured_profile,
|
|
54
57
|
normalize_profile,
|
|
58
|
+
open_question_items,
|
|
55
59
|
profile_catalog,
|
|
56
60
|
profile_template_path,
|
|
57
61
|
section_span,
|
|
@@ -625,7 +629,18 @@ def _auto_accept_config(args, adr_dir: Path) -> Tuple[str, float]:
|
|
|
625
629
|
|
|
626
630
|
|
|
627
631
|
def _run_json_tool(command: List[str]) -> Tuple[int, Dict]:
|
|
628
|
-
|
|
632
|
+
try:
|
|
633
|
+
result = subprocess.run(
|
|
634
|
+
command,
|
|
635
|
+
capture_output=True,
|
|
636
|
+
text=True,
|
|
637
|
+
stdin=subprocess.DEVNULL,
|
|
638
|
+
timeout=LIFECYCLE_TOOL_TIMEOUT_S,
|
|
639
|
+
)
|
|
640
|
+
except subprocess.TimeoutExpired as exc:
|
|
641
|
+
raise AdrLifecycleError(
|
|
642
|
+
f"tool timed out after {LIFECYCLE_TOOL_TIMEOUT_S:g}s: {' '.join(command)}"
|
|
643
|
+
) from exc
|
|
629
644
|
if result.returncode != 0 and not result.stdout.strip():
|
|
630
645
|
# A non-zero exit with no stdout is a crash, not a gate verdict: the
|
|
631
646
|
# tool never reached its JSON writer. Surface stderr instead of
|
|
@@ -935,25 +950,32 @@ def command_answer(args) -> List[str]:
|
|
|
935
950
|
start, end, section = _open_questions_section(body)
|
|
936
951
|
|
|
937
952
|
lines = section.splitlines()
|
|
953
|
+
# A question is an item, not a line: a wrapped question or one with nested
|
|
954
|
+
# bullets is answered once, after its last line (TASK-194).
|
|
938
955
|
unresolved = [
|
|
939
|
-
|
|
940
|
-
for
|
|
941
|
-
if
|
|
942
|
-
and not re.match(r"^\s*[-*+]\s*\[[xX]\]", line)
|
|
943
|
-
and re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", line).strip().casefold().rstrip(".")
|
|
944
|
-
not in {"none", "no open questions", "no unresolved questions"}
|
|
956
|
+
item
|
|
957
|
+
for item in open_question_items(section)
|
|
958
|
+
if item["is_question"] and not item["answered"] and item["question"]
|
|
945
959
|
]
|
|
946
960
|
if not unresolved:
|
|
947
961
|
raise AdrLifecycleError(f"{adr_id} has no unresolved question to answer")
|
|
948
962
|
|
|
949
963
|
target = _select_question(unresolved, args.question)
|
|
950
|
-
|
|
951
|
-
question_text = re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", line).strip()
|
|
964
|
+
question_text = target["text"]
|
|
952
965
|
changed_by = resolve_signer(adr_dir, args.changed_by)
|
|
953
|
-
|
|
954
|
-
f"
|
|
955
|
-
f"{str(args.answer).strip()}"
|
|
966
|
+
marker = (
|
|
967
|
+
f"— **Answered {args.date} by {changed_by}:** {str(args.answer).strip()}"
|
|
956
968
|
)
|
|
969
|
+
first = lines[target["start"]]
|
|
970
|
+
if re.match(r"^\s*[-*+]\s", first):
|
|
971
|
+
first_text = re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", first).strip()
|
|
972
|
+
else:
|
|
973
|
+
first_text = first.strip()
|
|
974
|
+
if target["start"] == target["end"]:
|
|
975
|
+
lines[target["start"]] = f"- [x] {first_text} {marker}"
|
|
976
|
+
else:
|
|
977
|
+
lines[target["start"]] = f"- [x] {first_text}"
|
|
978
|
+
lines.insert(target["end"] + 1, f" {marker}")
|
|
957
979
|
|
|
958
980
|
# splitlines() drops the section's trailing newline; putting it back is what
|
|
959
981
|
# keeps the blank line before the next heading, and a heading that loses its
|
|
@@ -962,19 +984,26 @@ def command_answer(args) -> List[str]:
|
|
|
962
984
|
body = body[:start] + rewritten + body[end:]
|
|
963
985
|
_commit_lifecycle_changes(adr_dir, [(path, render_frontmatter(data) + body)])
|
|
964
986
|
return [
|
|
965
|
-
f"answered in {path.name}: {question_text
|
|
987
|
+
f"answered in {path.name}: {_shorten(question_text, 100)}",
|
|
966
988
|
"the question and its answer stay in the record; acceptance is no longer blocked by it",
|
|
967
989
|
]
|
|
968
990
|
|
|
969
991
|
|
|
970
|
-
def
|
|
992
|
+
def _shorten(text: str, limit: int) -> str:
|
|
993
|
+
"""`text` whole, or cut at the last word boundary before `limit` plus " ..."."""
|
|
994
|
+
if len(text) <= limit:
|
|
995
|
+
return text
|
|
996
|
+
cut = text[:limit].rsplit(" ", 1)[0]
|
|
997
|
+
return f"{cut} ..."
|
|
998
|
+
|
|
999
|
+
|
|
1000
|
+
def _select_question(unresolved: List[Dict], wanted: Optional[str]):
|
|
971
1001
|
"""Pick the question to answer: the only one, an index, or a substring."""
|
|
972
1002
|
if wanted is None:
|
|
973
1003
|
if len(unresolved) > 1:
|
|
974
1004
|
listing = "; ".join(
|
|
975
|
-
f"{position}: "
|
|
976
|
-
|
|
977
|
-
for position, (_index, line) in enumerate(unresolved, 1)
|
|
1005
|
+
f"{position}: {_shorten(item['text'], 60)}"
|
|
1006
|
+
for position, item in enumerate(unresolved, 1)
|
|
978
1007
|
)
|
|
979
1008
|
raise AdrLifecycleError(
|
|
980
1009
|
f"{len(unresolved)} unresolved questions; name one with "
|
|
@@ -991,7 +1020,7 @@ def _select_question(unresolved: List[Tuple[int, str]], wanted: Optional[str]):
|
|
|
991
1020
|
return unresolved[position - 1]
|
|
992
1021
|
|
|
993
1022
|
needle = str(wanted).casefold()
|
|
994
|
-
matches = [item for item in unresolved if needle in item[
|
|
1023
|
+
matches = [item for item in unresolved if needle in item["text"].casefold()]
|
|
995
1024
|
if not matches:
|
|
996
1025
|
raise AdrLifecycleError(f"no unresolved question matches {wanted!r}")
|
|
997
1026
|
if len(matches) > 1:
|
package/bin/adr-audit
CHANGED
|
@@ -239,6 +239,30 @@ def run_judge(
|
|
|
239
239
|
return {"clean": not violations, "violations": violations, "empty": False}
|
|
240
240
|
|
|
241
241
|
|
|
242
|
+
def run_scope(adr_dir: Path, repo_root: Path) -> Dict:
|
|
243
|
+
"""Enforcement rules whose path_glob reaches no tracked file (TASK-204).
|
|
244
|
+
|
|
245
|
+
Advisory by construction: it never moves the exit code, and a failure to
|
|
246
|
+
run is reported in the result rather than failing the audit, because the
|
|
247
|
+
two questions the audit answers do not depend on it.
|
|
248
|
+
"""
|
|
249
|
+
argv = [
|
|
250
|
+
sys.executable, str(_BIN_DIR / "adr-judge"), "--check-scope", "--json",
|
|
251
|
+
"--adr-dir", str(adr_dir), "--repo-root", str(repo_root),
|
|
252
|
+
]
|
|
253
|
+
try:
|
|
254
|
+
result = _run(argv, repo_root)
|
|
255
|
+
payload = json.loads(result.stdout or "{}")
|
|
256
|
+
except (OSError, subprocess.SubprocessError, ValueError) as exc:
|
|
257
|
+
return {"error": f"scope check did not run ({exc})", "findings": []}
|
|
258
|
+
if result.returncode != 0 or not isinstance(payload, dict):
|
|
259
|
+
return {
|
|
260
|
+
"error": (result.stderr or "scope check failed").strip()[:300],
|
|
261
|
+
"findings": [],
|
|
262
|
+
}
|
|
263
|
+
return payload
|
|
264
|
+
|
|
265
|
+
|
|
242
266
|
# ---------------------------------------------------------------------------
|
|
243
267
|
# Reporting
|
|
244
268
|
# ---------------------------------------------------------------------------
|
|
@@ -255,7 +279,9 @@ def exit_code(lint: Dict, judge: Dict) -> int:
|
|
|
255
279
|
return EXIT_OK
|
|
256
280
|
|
|
257
281
|
|
|
258
|
-
def render_text(
|
|
282
|
+
def render_text(
|
|
283
|
+
lint: Dict, judge: Dict, mode: str, code: int, scope: Optional[Dict] = None
|
|
284
|
+
) -> str:
|
|
259
285
|
lines = [f"[adr-audit] {mode}"]
|
|
260
286
|
|
|
261
287
|
if lint["clean"]:
|
|
@@ -289,6 +315,17 @@ def render_text(lint: Dict, judge: Dict, mode: str, code: int) -> str:
|
|
|
289
315
|
if len(judge["violations"]) > 10:
|
|
290
316
|
lines.append(f" ... and {len(judge['violations']) - 10} more")
|
|
291
317
|
|
|
318
|
+
if scope is not None:
|
|
319
|
+
if scope.get("error"):
|
|
320
|
+
lines.append(f" scope: not checked ({scope['error']})")
|
|
321
|
+
else:
|
|
322
|
+
lines.append(
|
|
323
|
+
f" scope: {scope.get('rules_checked', 0)} rule glob(s), "
|
|
324
|
+
f"{len(scope['findings'])} reach no tracked file (advisory)"
|
|
325
|
+
)
|
|
326
|
+
for finding in scope["findings"][:10]:
|
|
327
|
+
lines.append(f" {finding['adr']} {finding['message']}")
|
|
328
|
+
|
|
292
329
|
lines.append(f" verdict: exit {code} ({_VERDICTS[code]})")
|
|
293
330
|
return "\n".join(lines)
|
|
294
331
|
|
|
@@ -423,6 +460,7 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
423
460
|
diff_text, adr_dir, repo_root,
|
|
424
461
|
args.snapshot or "worktree", budget, args.llm,
|
|
425
462
|
)
|
|
463
|
+
scope = run_scope(adr_dir, repo_root) if args.whole_codebase else None
|
|
426
464
|
except AuditError as exc:
|
|
427
465
|
print(f"adr-audit: {exc}", file=sys.stderr)
|
|
428
466
|
return EXIT_TOOLING
|
|
@@ -434,13 +472,14 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
434
472
|
"mode": mode,
|
|
435
473
|
"decisions": lint,
|
|
436
474
|
"code": judge,
|
|
475
|
+
"scope": scope,
|
|
437
476
|
"exit_code": code,
|
|
438
477
|
"verdict": _VERDICTS[code],
|
|
439
478
|
},
|
|
440
479
|
indent=2, ensure_ascii=False,
|
|
441
480
|
))
|
|
442
481
|
else:
|
|
443
|
-
print(render_text(lint, judge, mode, code))
|
|
482
|
+
print(render_text(lint, judge, mode, code, scope))
|
|
444
483
|
return code
|
|
445
484
|
|
|
446
485
|
|
package/bin/adr-judge
CHANGED
|
@@ -128,6 +128,10 @@ RegexEvaluationError = _adr_regex.RegexEvaluationError
|
|
|
128
128
|
bounded_regex_search = _adr_regex.bounded_regex_search
|
|
129
129
|
|
|
130
130
|
DEFAULT_LLM_TIMEOUT_S = 120
|
|
131
|
+
# Ceiling for the whole LLM pass (TASK-210). Without it the pass was bounded
|
|
132
|
+
# only by targets x DEFAULT_LLM_TIMEOUT_S, and a host CLI that outlived its
|
|
133
|
+
# timeout held it longer still.
|
|
134
|
+
DEFAULT_LLM_PASS_TIMEOUT_S = 600
|
|
131
135
|
|
|
132
136
|
# ---------- backend registry (ADR-017), shared with bin/adr-suggest ----------
|
|
133
137
|
#
|
|
@@ -1472,9 +1476,15 @@ def run_llm_batch(
|
|
|
1472
1476
|
backend: "LLMBackend | List[str] | str | None",
|
|
1473
1477
|
timeout_s: int,
|
|
1474
1478
|
attestation: Optional[Dict] = None,
|
|
1479
|
+
pass_timeout_s: Optional[float] = None,
|
|
1475
1480
|
) -> Optional[List[Dict]]:
|
|
1476
1481
|
"""Run the LLM judge over every `llm_judge: true` target, one call each.
|
|
1477
1482
|
|
|
1483
|
+
`pass_timeout_s` bounds the whole pass. Each call gets the smaller of
|
|
1484
|
+
`timeout_s` and what is left; once nothing is left the remaining ADRs get
|
|
1485
|
+
no verdict and the attestation says so (TASK-210). Without it the pass was
|
|
1486
|
+
bounded only by targets x timeout_s.
|
|
1487
|
+
|
|
1478
1488
|
"batch" is now the target SET, not a single shared call: each ADR is judged
|
|
1479
1489
|
in isolation so no sibling ADR's text can reach the context that decides
|
|
1480
1490
|
its verdict (SEC-HIGH, TASK-63/F2). Cost and latency are therefore linear
|
|
@@ -1527,9 +1537,20 @@ def run_llm_batch(
|
|
|
1527
1537
|
findings: List[Dict] = []
|
|
1528
1538
|
evaluated: List[str] = []
|
|
1529
1539
|
unusable: List[str] = []
|
|
1540
|
+
out_of_time: List[str] = []
|
|
1541
|
+
deadline = (
|
|
1542
|
+
time.monotonic() + pass_timeout_s if pass_timeout_s is not None else None
|
|
1543
|
+
)
|
|
1530
1544
|
for t in targets:
|
|
1531
1545
|
adr_id = t["adr_id"]
|
|
1532
|
-
|
|
1546
|
+
call_timeout = timeout_s
|
|
1547
|
+
if deadline is not None:
|
|
1548
|
+
remaining = deadline - time.monotonic()
|
|
1549
|
+
if remaining <= 0:
|
|
1550
|
+
out_of_time.append(adr_id)
|
|
1551
|
+
continue
|
|
1552
|
+
call_timeout = min(timeout_s, remaining)
|
|
1553
|
+
outcome = _run_llm_single(t, diff_text, resolved, call_timeout)
|
|
1533
1554
|
if outcome is None:
|
|
1534
1555
|
# One unusable call costs THIS ADR's verdict and nothing else.
|
|
1535
1556
|
# Discarding the pass threw away true positives: a VIOLATION
|
|
@@ -1555,19 +1576,35 @@ def run_llm_batch(
|
|
|
1555
1576
|
"severity": "violation",
|
|
1556
1577
|
}
|
|
1557
1578
|
)
|
|
1579
|
+
if out_of_time:
|
|
1580
|
+
print(
|
|
1581
|
+
f"[adr-judge] WARN: LLM pass deadline of {pass_timeout_s:g}s reached; "
|
|
1582
|
+
f"{len(out_of_time)} ADR(s) not judged. Raise "
|
|
1583
|
+
f"judge.llm_pass_timeout_seconds in .adr-kit.json if commits "
|
|
1584
|
+
f"routinely need more.",
|
|
1585
|
+
file=sys.stderr,
|
|
1586
|
+
)
|
|
1558
1587
|
if attestation is not None:
|
|
1559
1588
|
attestation["evaluated"] = evaluated
|
|
1560
|
-
if unusable:
|
|
1589
|
+
if unusable or out_of_time:
|
|
1561
1590
|
attestation["degraded"] = True
|
|
1591
|
+
parts = []
|
|
1592
|
+
if unusable:
|
|
1593
|
+
parts.append(f"no usable verdict for {', '.join(unusable)}")
|
|
1594
|
+
if out_of_time:
|
|
1595
|
+
parts.append(
|
|
1596
|
+
f"pass deadline reached before {', '.join(out_of_time)}"
|
|
1597
|
+
)
|
|
1562
1598
|
attestation["degraded_reason"] = (
|
|
1563
|
-
|
|
1599
|
+
"; ".join(parts)
|
|
1600
|
+
+ "; "
|
|
1564
1601
|
+ (
|
|
1565
1602
|
"no ADR was judged in this pass"
|
|
1566
1603
|
if not evaluated
|
|
1567
1604
|
else f"{len(evaluated)} of {len(targets)} ADR(s) still judged"
|
|
1568
1605
|
)
|
|
1569
1606
|
)
|
|
1570
|
-
if unusable and not evaluated:
|
|
1607
|
+
if (unusable or out_of_time) and not evaluated:
|
|
1571
1608
|
# Nothing came back at all: keep the documented "None means the LLM
|
|
1572
1609
|
# pass produced nothing" contract that the unavailable-backend path
|
|
1573
1610
|
# above already uses, so callers need no new case.
|
|
@@ -2012,6 +2049,11 @@ def build_config_report(
|
|
|
2012
2049
|
int(judge_cfg.get("llm_timeout_seconds", DEFAULT_LLM_TIMEOUT_S)),
|
|
2013
2050
|
"project" if "llm_timeout_seconds" in judge_cfg else "default",
|
|
2014
2051
|
),
|
|
2052
|
+
_entry(
|
|
2053
|
+
"judge.llm_pass_timeout_seconds",
|
|
2054
|
+
int(judge_cfg.get("llm_pass_timeout_seconds", DEFAULT_LLM_PASS_TIMEOUT_S)),
|
|
2055
|
+
"project" if "llm_pass_timeout_seconds" in judge_cfg else "default",
|
|
2056
|
+
),
|
|
2015
2057
|
_entry(
|
|
2016
2058
|
"judge.advisory_only",
|
|
2017
2059
|
bool(judge_cfg.get("advisory_only", False)),
|
|
@@ -2209,6 +2251,72 @@ def _register_git_exclude(adr_dir: Path, name: str) -> None:
|
|
|
2209
2251
|
return
|
|
2210
2252
|
|
|
2211
2253
|
|
|
2254
|
+
SCOPE_CHECK_LIMITS = (
|
|
2255
|
+
"A resolving scope is not proof that the decision is implemented: the "
|
|
2256
|
+
"check cannot see a call compiled out for one target, or a decision whose "
|
|
2257
|
+
"prose names more cases than any rule does. Those belong to review."
|
|
2258
|
+
)
|
|
2259
|
+
|
|
2260
|
+
|
|
2261
|
+
def tracked_paths(repo_root: Path) -> Optional[List[str]]:
|
|
2262
|
+
"""Every path git tracks under repo_root, or None when git cannot say."""
|
|
2263
|
+
try:
|
|
2264
|
+
result = subprocess.run(
|
|
2265
|
+
["git", "-C", str(repo_root), "ls-files", "-z"],
|
|
2266
|
+
capture_output=True,
|
|
2267
|
+
stdin=subprocess.DEVNULL,
|
|
2268
|
+
timeout=60,
|
|
2269
|
+
)
|
|
2270
|
+
except (OSError, subprocess.SubprocessError):
|
|
2271
|
+
return None
|
|
2272
|
+
if result.returncode != 0:
|
|
2273
|
+
return None
|
|
2274
|
+
return [p for p in result.stdout.decode("utf-8", "replace").split("\0") if p]
|
|
2275
|
+
|
|
2276
|
+
|
|
2277
|
+
def scope_check(
|
|
2278
|
+
adrs: List[Tuple[str, Path, str]], paths: List[str]
|
|
2279
|
+
) -> Dict:
|
|
2280
|
+
"""Name every Enforcement rule of an Accepted ADR that is checked against nothing.
|
|
2281
|
+
|
|
2282
|
+
A rule whose `path_glob` matches no tracked file can never fire, so every
|
|
2283
|
+
gate that asks "was it violated?" answers green for as long as the glob
|
|
2284
|
+
and the code disagree about where the code lives (TASK-204). This is the
|
|
2285
|
+
deterministic slice of "is the decision implemented where it says it
|
|
2286
|
+
applies"; the rest is semantic, and `limits` says so in every report.
|
|
2287
|
+
"""
|
|
2288
|
+
findings: List[Dict] = []
|
|
2289
|
+
checked = 0
|
|
2290
|
+
for adr_id, adr_path, body in adrs:
|
|
2291
|
+
if (adr_status(body) or "").lower() != "accepted":
|
|
2292
|
+
continue
|
|
2293
|
+
enforcement = parse_enforcement(body, adr_path)
|
|
2294
|
+
if not enforcement or validate_enforcement(enforcement):
|
|
2295
|
+
continue
|
|
2296
|
+
for kind in ("forbid_pattern", "forbid_import", "require_pattern"):
|
|
2297
|
+
for rule in enforcement.get(kind, []) or []:
|
|
2298
|
+
glob = (rule or {}).get("path_glob")
|
|
2299
|
+
if not glob:
|
|
2300
|
+
continue
|
|
2301
|
+
checked += 1
|
|
2302
|
+
if any(path_matches(path, glob) for path in paths):
|
|
2303
|
+
continue
|
|
2304
|
+
findings.append(
|
|
2305
|
+
{
|
|
2306
|
+
"adr": adr_id,
|
|
2307
|
+
"rule": kind,
|
|
2308
|
+
"path_glob": glob,
|
|
2309
|
+
"severity": "advisory",
|
|
2310
|
+
"message": (
|
|
2311
|
+
f"{kind} path_glob {glob!r} matches no tracked file, "
|
|
2312
|
+
f"so this rule is checked against nothing; point it "
|
|
2313
|
+
f"at where the code lives, or retire it"
|
|
2314
|
+
),
|
|
2315
|
+
}
|
|
2316
|
+
)
|
|
2317
|
+
return {"rules_checked": checked, "findings": findings, "limits": SCOPE_CHECK_LIMITS}
|
|
2318
|
+
|
|
2319
|
+
|
|
2212
2320
|
def collect_adrs(
|
|
2213
2321
|
adr_dir: Path, dry_run_target: Optional[str] = None
|
|
2214
2322
|
) -> List[Tuple[str, Path, str]]:
|
|
@@ -2388,6 +2496,13 @@ def main() -> int:
|
|
|
2388
2496
|
"the command, not from committed config. Tests inject a fake binary "
|
|
2389
2497
|
"here.",
|
|
2390
2498
|
)
|
|
2499
|
+
p.add_argument(
|
|
2500
|
+
"--check-scope",
|
|
2501
|
+
action="store_true",
|
|
2502
|
+
help="Report every Enforcement rule of an Accepted ADR whose path_glob "
|
|
2503
|
+
"matches no tracked file, then exit 0. Such a rule can never fire. "
|
|
2504
|
+
"Read-only and advisory; pair with --json.",
|
|
2505
|
+
)
|
|
2391
2506
|
p.add_argument(
|
|
2392
2507
|
"--show-config",
|
|
2393
2508
|
action="store_true",
|
|
@@ -2526,6 +2641,9 @@ def main() -> int:
|
|
|
2526
2641
|
if args.llm_timeout is not None
|
|
2527
2642
|
else judge_cfg.get("llm_timeout_seconds", DEFAULT_LLM_TIMEOUT_S)
|
|
2528
2643
|
)
|
|
2644
|
+
llm_pass_timeout_s = int(
|
|
2645
|
+
judge_cfg.get("llm_pass_timeout_seconds", DEFAULT_LLM_PASS_TIMEOUT_S)
|
|
2646
|
+
)
|
|
2529
2647
|
|
|
2530
2648
|
repo_root = Path(args.repo_root).resolve() if args.repo_root else Path.cwd()
|
|
2531
2649
|
|
|
@@ -2542,6 +2660,29 @@ def main() -> int:
|
|
|
2542
2660
|
)
|
|
2543
2661
|
return 0
|
|
2544
2662
|
|
|
2663
|
+
if args.check_scope:
|
|
2664
|
+
paths = tracked_paths(repo_root)
|
|
2665
|
+
if paths is None:
|
|
2666
|
+
print(
|
|
2667
|
+
"[adr-judge] scope check needs a git repository; "
|
|
2668
|
+
f"`git ls-files` failed under {repo_root}",
|
|
2669
|
+
file=sys.stderr,
|
|
2670
|
+
)
|
|
2671
|
+
return 2
|
|
2672
|
+
report = scope_check(collect_adrs(adr_dir), paths)
|
|
2673
|
+
if args.json:
|
|
2674
|
+
json.dump(report, sys.stdout, indent=2)
|
|
2675
|
+
sys.stdout.write("\n")
|
|
2676
|
+
else:
|
|
2677
|
+
print(
|
|
2678
|
+
f"[adr-judge] scope check: {report['rules_checked']} rule "
|
|
2679
|
+
f"glob(s), {len(report['findings'])} resolve to no tracked file"
|
|
2680
|
+
)
|
|
2681
|
+
for finding in report["findings"]:
|
|
2682
|
+
print(f" ADVISORY {finding['adr']}: {finding['message']}")
|
|
2683
|
+
print(f" note: {report['limits']}")
|
|
2684
|
+
return 0
|
|
2685
|
+
|
|
2545
2686
|
if args.show_config:
|
|
2546
2687
|
report = build_config_report(
|
|
2547
2688
|
config_path, adr_dir, judge_cfg, local_cfg, llm_backend,
|
|
@@ -2718,6 +2859,7 @@ def main() -> int:
|
|
|
2718
2859
|
llm_backend,
|
|
2719
2860
|
llm_timeout_s,
|
|
2720
2861
|
attestation=llm_attestation,
|
|
2862
|
+
pass_timeout_s=llm_pass_timeout_s,
|
|
2721
2863
|
)
|
|
2722
2864
|
profiler.stop_llm()
|
|
2723
2865
|
if llm_findings is not None:
|
package/bin/adr-judge-precommit
CHANGED
|
@@ -25,6 +25,7 @@ Usage (direct smoke-test, cwd = a git repository):
|
|
|
25
25
|
|
|
26
26
|
from __future__ import annotations
|
|
27
27
|
|
|
28
|
+
import os
|
|
28
29
|
import subprocess
|
|
29
30
|
import sys
|
|
30
31
|
from pathlib import Path
|
|
@@ -68,18 +69,35 @@ def main() -> int:
|
|
|
68
69
|
|
|
69
70
|
staged_diff = diff_proc.stdout # bytes
|
|
70
71
|
|
|
71
|
-
# Step 2: pipe the diff into adr-judge.
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
72
|
+
# Step 2: pipe the diff into adr-judge, within a ceiling. adr-judge bounds
|
|
73
|
+
# its own LLM pass (judge.llm_pass_timeout_seconds); this is the backstop
|
|
74
|
+
# for a judge that never returns at all, which used to hold the commit
|
|
75
|
+
# without limit (TASK-210).
|
|
76
|
+
try:
|
|
77
|
+
timeout_s = float(os.environ.get("ADR_KIT_JUDGE_TIMEOUT_S", "900"))
|
|
78
|
+
except ValueError:
|
|
79
|
+
timeout_s = 900.0
|
|
80
|
+
try:
|
|
81
|
+
judge_proc = subprocess.run(
|
|
82
|
+
[
|
|
83
|
+
sys.executable,
|
|
84
|
+
str(_ADR_JUDGE),
|
|
85
|
+
"--diff", "-",
|
|
86
|
+
"--adr-dir", "docs/adr/",
|
|
87
|
+
"--repo-root", str(Path.cwd()),
|
|
88
|
+
"--snapshot", "staged",
|
|
89
|
+
],
|
|
90
|
+
input=staged_diff,
|
|
91
|
+
timeout=timeout_s,
|
|
92
|
+
)
|
|
93
|
+
except subprocess.TimeoutExpired:
|
|
94
|
+
print(
|
|
95
|
+
f"[adr-judge-precommit] ERROR: adr-judge timed out after "
|
|
96
|
+
f"{timeout_s:g}s. Retry with ADR_KIT_NO_LLM=1 to run the "
|
|
97
|
+
f"declarative pass only, or raise ADR_KIT_JUDGE_TIMEOUT_S.",
|
|
98
|
+
file=sys.stderr,
|
|
99
|
+
)
|
|
100
|
+
return 2
|
|
83
101
|
return judge_proc.returncode
|
|
84
102
|
|
|
85
103
|
|