@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/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
- def unresolved_open_questions(text: str) -> List[str]:
365
- """Return stable unresolved items from the optional Open Questions role."""
366
- section = section_text(text, "open_questions")
367
- if not section:
368
- return []
369
- questions: List[str] = []
370
- for raw_line in section.splitlines():
371
- line = raw_line.strip()
372
- if not line or line.startswith(("```", "<!--", "-->")):
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
- normalized = re.sub(r"^\s*[-*+]\s+", "", line).strip()
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 re.match(r"^\[[xX]\]\s+", normalized):
399
+ if not stripped:
400
+ previous_blank = True
382
401
  continue
383
- if re.match(r"^(?:answered|resolved)\s*:", normalized, re.IGNORECASE):
402
+ if stripped.startswith(("<!--", "-->")):
384
403
  continue
385
- unchecked = re.match(r"^\[\s\]\s+(.+)$", normalized)
386
- if unchecked:
387
- candidate = unchecked.group(1)
388
- elif re.match(r"^[-*+]\s+", line) or normalized.endswith("?"):
389
- candidate = normalized
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
- continue
392
- candidate = re.sub(r"[`*_]", "", candidate)
393
- candidate = re.sub(r"\s+", " ", candidate).strip()
394
- if candidate:
395
- questions.append(candidate)
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 raw_line in section.splitlines():
428
- line = raw_line.strip()
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
- found[question] = found.get(question, False) or answered
494
+ question = item["question"]
495
+ found[question] = found.get(question, False) or item["answered"]
451
496
  return found
452
497
 
453
498
 
@@ -828,6 +873,95 @@ def has_role_heading(text: str, profile: str, role: str) -> bool:
828
873
  return any(item.casefold() == expected for item in h2_headings(text))
829
874
 
830
875
 
876
+ # Matched on the marker rather than the exact sentence, so a reworded placeholder
877
+ # still counts, and anchored to a list item or line start so prose that merely
878
+ # mentions a TODO further down the section does not mask a real gap.
879
+ _PLACEHOLDER_LINE_RE = re.compile(r"^\s*(?:[-*+]\s*)?TODO\b", re.IGNORECASE)
880
+ # Two writers, two spellings: `bin/adr-migrate` emits a `- TODO:` list item and
881
+ # the `/adr-kit:migrate` skill emits an HTML comment. `bin/adr-lint` already
882
+ # strips comments before it counts alternatives, and `tests/test_adr_policy.py`
883
+ # pins the two as equivalent, so honouring only one of them made this the odd
884
+ # reader out. A comment is never content a reader sees, whatever it says.
885
+ _HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
886
+
887
+ SECTION_EMPTY = "empty"
888
+ SECTION_PLACEHOLDER = "placeholder"
889
+
890
+
891
+ def _unwritten_required_sections(text: str, profile: str) -> List[tuple]:
892
+ """(heading, kind) for each required heading nobody has written yet.
893
+
894
+ The kinds differ in who is owed what. An empty heading fails completeness in
895
+ `bin/adr-lint`, so acceptance already refuses it. A placeholder does not, by
896
+ decision: an imported record must not fail a blocking gate on arrival. Only
897
+ a caller that can tell the two apart can say something true about either.
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."""
904
+ normalized = normalize_profile(profile)
905
+ unwritten: List[tuple] = []
906
+ for role in PROFILE_REQUIRED_ROLES[normalized]:
907
+ title = heading(normalized, role)
908
+ match = re.search(
909
+ r"^##\s+" + re.escape(title) + r"\s*$", text, re.MULTILINE
910
+ )
911
+ if match is None:
912
+ continue
913
+ rest = text[match.end():]
914
+ nxt = re.search(r"^##\s", rest, re.MULTILINE)
915
+ body = rest[: nxt.start()] if nxt else rest
916
+ visible = [
917
+ ln for ln in _HTML_COMMENT_RE.sub("", body).splitlines() if ln.strip()
918
+ ]
919
+ if visible and not all(_PLACEHOLDER_LINE_RE.match(ln) for ln in visible):
920
+ continue
921
+ if not visible and not body.strip():
922
+ unwritten.append((role, title, SECTION_EMPTY))
923
+ else:
924
+ unwritten.append((role, title, SECTION_PLACEHOLDER))
925
+ return unwritten
926
+
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
+
939
+ def unfilled_required_sections(text: str, profile: str) -> List[str]:
940
+ """Required headings present in `text` that nobody has actually written yet.
941
+
942
+ Covers the empty section and the placeholder section alike, because
943
+ `_append_missing_role` writes the latter: a heading whose body still says
944
+ TODO is a hole the migration opened, not content. Callers use this to tell
945
+ an operator that a migrated record is unfinished, which the write itself
946
+ otherwise does silently.
947
+ """
948
+ return [title for title, _ in _unwritten_required_sections(text, profile)]
949
+
950
+
951
+ def placeholder_required_sections(text: str, profile: str) -> List[str]:
952
+ """Required headings holding an adr-kit placeholder instead of an answer.
953
+
954
+ The narrower half of `unfilled_required_sections`, for the caller that must
955
+ not confuse the two: an empty heading is already refused at acceptance, a
956
+ placeholder is deliberately not, so only this set is news to anyone.
957
+ """
958
+ return [
959
+ title
960
+ for title, kind in _unwritten_required_sections(text, profile)
961
+ if kind == SECTION_PLACEHOLDER
962
+ ]
963
+
964
+
831
965
  def _append_missing_role(text: str, profile: str, role: str) -> str:
832
966
  placeholders = {
833
967
  "drivers": "- TODO: capture the decision drivers.",
@@ -47,6 +47,7 @@ def rank_proposed(report: dict) -> list[dict]:
47
47
  linked = bool(isinstance(link, dict) and link.get("linked"))
48
48
  shipped = bool(item.get("documents_shipped"))
49
49
  ready = item.get("classification") == "ready-for-confirmation"
50
+ needs_human = item.get("classification") == "needs-human-input"
50
51
  open_questions = bool(item.get("open_questions"))
51
52
  age_days = _age_days(item, evaluated_on)
52
53
  quality = item.get("quality", {})
@@ -67,7 +68,14 @@ def rank_proposed(report: dict) -> list[dict]:
67
68
  # Proposed ADR that is sharp, unlinked, unshipped, not ready and asking
68
69
  # nothing has no work attached to it, and listing it teaches the reader
69
70
  # to skim the queue.
70
- signals = (linked, shipped, ready, open_questions, below_threshold)
71
+ # `needs_human` is here because the classification it names is the one
72
+ # that used to be `ready-for-confirmation`. A record whose References
73
+ # hold only a migration placeholder is unlinked, unshipped, above the
74
+ # quality threshold and asks no open question, so `ready` was its only
75
+ # signal; reporting the placeholder honestly would otherwise drop it out
76
+ # of the queue and make it LESS visible than saying nothing. Measured on
77
+ # ADR-042 with a placeholder: 0 candidates without this line.
78
+ signals = (linked, shipped, ready, open_questions, below_threshold, needs_human)
71
79
  if not any(signals):
72
80
  continue
73
81
 
@@ -80,6 +88,11 @@ def rank_proposed(report: dict) -> list[dict]:
80
88
  reasons.append("ready for confirmation")
81
89
  if open_questions:
82
90
  reasons.append("open human questions")
91
+ if needs_human and not open_questions:
92
+ # Before the unconditional age entry on purpose: the SessionStart
93
+ # block prints reasons[:2] and the auto-grill handoff reasons[:3],
94
+ # so a reason appended after it never reaches a human.
95
+ reasons.append("human input needed")
83
96
  if below_threshold:
84
97
  reasons.append(f"quality {quality_score:.3f} below {threshold:.2f}")
85
98
  reasons.append(f"age {age_days} days")
@@ -98,6 +111,7 @@ def rank_proposed(report: dict) -> list[dict]:
98
111
  -int(shipped),
99
112
  -int(ready),
100
113
  -int(open_questions),
114
+ -int(needs_human),
101
115
  -int(below_threshold),
102
116
  -age_days,
103
117
  quality_score,
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 = subprocess.run(
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 "
@@ -190,6 +190,15 @@ def _section_text(content: str, heading: str) -> str:
190
190
  return m.group(1) if m else ""
191
191
 
192
192
 
193
+ # Same rule as bin/adr-lint: a heading with nothing under it is a hole, not a
194
+ # section. Emptiness only. A migration placeholder counts as content here by
195
+ # decision, not by oversight: an imported record must not fail a blocking gate
196
+ # on arrival (test_adr_policy.py, test_migration_discovery.py). adr-migrate
197
+ # reports the placeholders it wrote instead, which informs without refusing.
198
+ def _is_unfilled(body: str) -> bool:
199
+ return not any(ln.strip() for ln in body.splitlines())
200
+
201
+
193
202
  def gate_completeness(content: str) -> Dict:
194
203
  """Gate 1: Completeness (0.0-1.0).
195
204
 
@@ -216,9 +225,17 @@ def gate_completeness(content: str) -> Dict:
216
225
  pattern = _SECTION_PRESENCE_RE.get(section) or re.compile(
217
226
  r"^" + re.escape(section) + r"\b", re.MULTILINE
218
227
  )
228
+ # A heading with nothing under it is not a section (TASK-198). This loop
229
+ # used to test presence alone, while three checks further down already
230
+ # measured emptiness for Decision, Alternatives and Consequences. That
231
+ # split meant References or Related Decisions could be hollow and still
232
+ # score full marks here, and `adr accept --quality-threshold` reads this
233
+ # score. The placeholder case counts too: it is what adr-migrate writes
234
+ # into a heading it has to add.
219
235
  present = bool(pattern.search(content))
220
- checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = present
221
- if not present:
236
+ filled = present and not _is_unfilled(_section_text(content, section))
237
+ checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = filled
238
+ if not filled:
222
239
  missing_sections.append(section)
223
240
 
224
241
  score = 1.0
@@ -9,7 +9,7 @@ from pathlib import Path
9
9
  from typing import Dict, List, Optional, Sequence
10
10
 
11
11
  from adr_catalog import build_relationships, load_adr_records, normalize_adr_id
12
- from adr_format import all_open_questions
12
+ from adr_format import AdrFormatError, all_open_questions, placeholder_required_sections
13
13
  from adr_quality_core import QUALITY_THRESHOLD, score_path
14
14
 
15
15
 
@@ -85,6 +85,7 @@ FINDING_CODES = (
85
85
  "FORMAT_UNKNOWN",
86
86
  "FRONTMATTER_MALFORMED",
87
87
  "OPEN_QUESTION",
88
+ "SECTION_PLACEHOLDER_ONLY",
88
89
  "STATUS_UNKNOWN",
89
90
  "SUPERSESSION_STATE_INCONSISTENT",
90
91
  "VERIFIED_IN_CHANGED",
@@ -252,6 +253,62 @@ def _mechanical_findings(record: Dict) -> List[Dict[str, str]]:
252
253
  return sorted(findings, key=lambda item: item["code"])
253
254
 
254
255
 
256
+ def _record_path(record: Dict, adr_dir: Optional[Path] = None) -> Optional[Path]:
257
+ """Resolve a record's bare filename against the ADR directory, or None.
258
+
259
+ Records reach readiness with `path` set to a filename and no directory, and
260
+ the test suite passes records whose file does not exist at all. Both are
261
+ normal, so this answers "no path" rather than raising.
262
+ """
263
+ raw = record.get("path")
264
+ if not raw:
265
+ return None
266
+ path = Path(str(raw))
267
+ if not path.is_absolute() and adr_dir is not None and not path.exists():
268
+ path = Path(adr_dir) / path.name
269
+ return path if path.is_file() else None
270
+
271
+
272
+ def _placeholder_findings(
273
+ record: Dict, adr_dir: Optional[Path] = None
274
+ ) -> List[Dict[str, str]]:
275
+ """Required sections holding an adr-kit placeholder instead of an answer.
276
+
277
+ A migrated record reaches acceptance with `- TODO: add verifiable
278
+ references.` under `## References` and nothing refuses it: the completeness
279
+ gate treats a placeholder as content by decision, because an imported record
280
+ must not fail a blocking gate on arrival. The record then classifies
281
+ `ready-for-confirmation`, which is a lie about a record nobody has finished
282
+ writing. Saying so here reaches the operator before `adr accept` freezes it,
283
+ and readiness has no power to block, which is the point.
284
+
285
+ Empty sections are deliberately not reported: `bin/adr-lint` already fails
286
+ completeness on those, so acceptance refuses them without help.
287
+ """
288
+ path = _record_path(record, adr_dir)
289
+ if path is None:
290
+ return []
291
+ try:
292
+ text = path.read_text(encoding="utf-8", errors="replace")
293
+ except OSError:
294
+ return []
295
+ try:
296
+ sections = placeholder_required_sections(text, str(record.get("format", "")))
297
+ except AdrFormatError:
298
+ # 'hybrid' and 'unknown' are legal values of record["format"], and
299
+ # neither resolves to a required-section list. Nothing to say, and
300
+ # raising here would be invisible: bin/adr-guardian swallows the
301
+ # exception and returns 0, so the queue would just go stale.
302
+ return []
303
+ return [
304
+ {
305
+ "code": "SECTION_PLACEHOLDER_ONLY",
306
+ "message": f"## {title} holds a migration placeholder, not an answer.",
307
+ }
308
+ for title in sorted(sections)
309
+ ]
310
+
311
+
255
312
  def _classification(
256
313
  record: Dict,
257
314
  mechanical: Sequence[Dict[str, str]],
@@ -293,6 +350,7 @@ def readiness_for_record(
293
350
  }
294
351
  for question in record.get("open_questions", [])
295
352
  ]
353
+ human.extend(_placeholder_findings(record, adr_dir))
296
354
  # Three booleans used to stand in for quality here, which meant a vague ADR
297
355
  # and a sharp one scored identically as long as both had a decision line and
298
356
  # a verified_in. The real weighted scorer existed the whole time behind
@@ -347,6 +405,9 @@ def readiness_for_record(
347
405
  "title": record["title"],
348
406
  "path": normalize_path(str(record["path"])),
349
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"),
350
411
  "format": record["format"],
351
412
  "evaluated_on": evaluated_on.isoformat(),
352
413
  "classification": classification,
@@ -1,4 +1,4 @@
1
- <!-- adr-kit-guide v0.35.0 -->
1
+ <!-- adr-kit-guide v0.58.0 -->
2
2
  <!-- Generated ADR Kit guidance. Local additions belong in .adr-kit/ADR-guide.local.md. -->
3
3
 
4
4
  # ADR Kit agent guide
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rvdbreemen/adr-kit-opencode",
3
- "version": "0.56.0",
3
+ "version": "0.58.0",
4
4
  "description": "Native OpenCode plugin for ADR Kit, backed by the shared deterministic Python engines.",
5
5
  "type": "module",
6
6
  "main": "./opencode/plugin.ts",
@@ -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.",
@@ -23,6 +23,7 @@
23
23
  "implementation_link", "next_command"
24
24
  ],
25
25
  "properties": {
26
+ "date": {"type": ["string", "null"]},
26
27
  "classification": {
27
28
  "enum": [
28
29
  "not-an-adr",
@@ -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
- errors = validate(bundle, args.candidate_commit, args.release_candidate, 30)
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: