@rvdbreemen/adr-kit-opencode 0.57.0 → 0.59.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.
@@ -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.57.0",
4
+ "version": "0.59.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.57.0"]
317
+ "plugin": ["@rvdbreemen/adr-kit-opencode@0.59.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.57.0
676
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.59.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.57.0
690
+ rev: v0.59.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,
@@ -133,8 +137,19 @@ def load_adr(path: Path) -> Tuple[Dict, str]:
133
137
 
134
138
 
135
139
  def _atomic_write_text(path: Path, text: str) -> None:
136
- """Write one file through a unique same-directory temporary and replace."""
140
+ """Write one file through a unique same-directory temporary and replace.
141
+
142
+ An existing file keeps its line endings. Every reader here goes through
143
+ read_text, which turns CRLF into "\\n", so writing the text back as-is
144
+ rewrote a CRLF record as LF and made one answered question look like a
145
+ whole-file change on a Windows checkout (TASK-213).
146
+ """
137
147
  path.parent.mkdir(parents=True, exist_ok=True)
148
+ try:
149
+ if b"\r\n" in path.read_bytes()[:4096]:
150
+ text = text.replace("\r\n", "\n").replace("\n", "\r\n")
151
+ except OSError:
152
+ pass
138
153
  temp_path: Path | None = None
139
154
  try:
140
155
  with tempfile.NamedTemporaryFile(
@@ -625,7 +640,18 @@ def _auto_accept_config(args, adr_dir: Path) -> Tuple[str, float]:
625
640
 
626
641
 
627
642
  def _run_json_tool(command: List[str]) -> Tuple[int, Dict]:
628
- result = subprocess.run(command, capture_output=True, text=True)
643
+ try:
644
+ result = subprocess.run(
645
+ command,
646
+ capture_output=True,
647
+ text=True,
648
+ stdin=subprocess.DEVNULL,
649
+ timeout=LIFECYCLE_TOOL_TIMEOUT_S,
650
+ )
651
+ except subprocess.TimeoutExpired as exc:
652
+ raise AdrLifecycleError(
653
+ f"tool timed out after {LIFECYCLE_TOOL_TIMEOUT_S:g}s: {' '.join(command)}"
654
+ ) from exc
629
655
  if result.returncode != 0 and not result.stdout.strip():
630
656
  # A non-zero exit with no stdout is a crash, not a gate verdict: the
631
657
  # tool never reached its JSON writer. Surface stderr instead of
@@ -935,25 +961,32 @@ def command_answer(args) -> List[str]:
935
961
  start, end, section = _open_questions_section(body)
936
962
 
937
963
  lines = section.splitlines()
964
+ # A question is an item, not a line: a wrapped question or one with nested
965
+ # bullets is answered once, after its last line (TASK-194).
938
966
  unresolved = [
939
- (index, line)
940
- for index, line in enumerate(lines)
941
- if re.match(r"^\s*[-*+]\s*(?:\[\s\]\s+)?\S", line)
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"}
967
+ item
968
+ for item in open_question_items(section)
969
+ if item["is_question"] and not item["answered"] and item["question"]
945
970
  ]
946
971
  if not unresolved:
947
972
  raise AdrLifecycleError(f"{adr_id} has no unresolved question to answer")
948
973
 
949
974
  target = _select_question(unresolved, args.question)
950
- index, line = target
951
- question_text = re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", line).strip()
975
+ question_text = target["text"]
952
976
  changed_by = resolve_signer(adr_dir, args.changed_by)
953
- lines[index] = (
954
- f"- [x] {question_text} — **Answered {args.date} by {changed_by}:** "
955
- f"{str(args.answer).strip()}"
977
+ marker = (
978
+ f"— **Answered {args.date} by {changed_by}:** {str(args.answer).strip()}"
956
979
  )
980
+ first = lines[target["start"]]
981
+ if re.match(r"^\s*[-*+]\s", first):
982
+ first_text = re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", first).strip()
983
+ else:
984
+ first_text = first.strip()
985
+ if target["start"] == target["end"]:
986
+ lines[target["start"]] = f"- [x] {first_text} {marker}"
987
+ else:
988
+ lines[target["start"]] = f"- [x] {first_text}"
989
+ lines.insert(target["end"] + 1, f" {marker}")
957
990
 
958
991
  # splitlines() drops the section's trailing newline; putting it back is what
959
992
  # keeps the blank line before the next heading, and a heading that loses its
@@ -962,19 +995,26 @@ def command_answer(args) -> List[str]:
962
995
  body = body[:start] + rewritten + body[end:]
963
996
  _commit_lifecycle_changes(adr_dir, [(path, render_frontmatter(data) + body)])
964
997
  return [
965
- f"answered in {path.name}: {question_text[:70]}",
998
+ f"answered in {path.name}: {_shorten(question_text, 100)}",
966
999
  "the question and its answer stay in the record; acceptance is no longer blocked by it",
967
1000
  ]
968
1001
 
969
1002
 
970
- def _select_question(unresolved: List[Tuple[int, str]], wanted: Optional[str]):
1003
+ def _shorten(text: str, limit: int) -> str:
1004
+ """`text` whole, or cut at the last word boundary before `limit` plus " ..."."""
1005
+ if len(text) <= limit:
1006
+ return text
1007
+ cut = text[:limit].rsplit(" ", 1)[0]
1008
+ return f"{cut} ..."
1009
+
1010
+
1011
+ def _select_question(unresolved: List[Dict], wanted: Optional[str]):
971
1012
  """Pick the question to answer: the only one, an index, or a substring."""
972
1013
  if wanted is None:
973
1014
  if len(unresolved) > 1:
974
1015
  listing = "; ".join(
975
- f"{position}: "
976
- + re.sub(r"^\s*[-*+]\s*(?:\[\s\]\s+)?", "", line).strip()[:60]
977
- for position, (_index, line) in enumerate(unresolved, 1)
1016
+ f"{position}: {_shorten(item['text'], 60)}"
1017
+ for position, item in enumerate(unresolved, 1)
978
1018
  )
979
1019
  raise AdrLifecycleError(
980
1020
  f"{len(unresolved)} unresolved questions; name one with "
@@ -991,7 +1031,7 @@ def _select_question(unresolved: List[Tuple[int, str]], wanted: Optional[str]):
991
1031
  return unresolved[position - 1]
992
1032
 
993
1033
  needle = str(wanted).casefold()
994
- matches = [item for item in unresolved if needle in item[1].casefold()]
1034
+ matches = [item for item in unresolved if needle in item["text"].casefold()]
995
1035
  if not matches:
996
1036
  raise AdrLifecycleError(f"no unresolved question matches {wanted!r}")
997
1037
  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(lint: Dict, judge: Dict, mode: str, code: int) -> str:
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
- outcome = _run_llm_single(t, diff_text, resolved, timeout_s)
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
- f"no usable verdict for {', '.join(unusable)}; "
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:
@@ -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
- judge_proc = subprocess.run(
73
- [
74
- sys.executable,
75
- str(_ADR_JUDGE),
76
- "--diff", "-",
77
- "--adr-dir", "docs/adr/",
78
- "--repo-root", str(Path.cwd()),
79
- "--snapshot", "staged",
80
- ],
81
- input=staged_diff,
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