@rvdbreemen/adr-kit-opencode 0.56.0 → 0.58.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +5 -3
- package/bin/adr +79 -20
- package/bin/adr-audit +41 -2
- package/bin/adr-judge +146 -4
- package/bin/adr-judge-precommit +30 -12
- package/bin/adr-lint +136 -20
- package/bin/adr-migrate +48 -0
- package/bin/adr-substance +310 -0
- package/bin/adr_format.py +183 -49
- package/bin/adr_guardian_queue.py +15 -1
- package/bin/adr_llm.py +68 -8
- package/bin/adr_quality_core.py +19 -2
- package/bin/adr_readiness.py +62 -1
- package/instructions/ADR-guide.md +1 -1
- package/package.json +1 -1
- package/schemas/adr-kit-config.schema.json +6 -0
- package/schemas/adr-readiness.schema.json +1 -0
- package/scripts/build-client-adapters.py +20 -1
- package/scripts/check-changelog-sections.py +198 -0
- package/scripts/release.py +171 -0
- package/scripts/release_npm.py +117 -0
- package/scripts/release_phases.py +331 -0
- package/scripts/release_shell.py +124 -0
- package/skills/guardian/SKILL.md +21 -0
- package/skills/review/SKILL.md +18 -0
- package/templates/adr-kit-guide.md +7 -2
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
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
|
|
|
@@ -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
|
-
|
|
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 =
|
|
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_quality_core.py
CHANGED
|
@@ -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
|
-
|
|
221
|
-
|
|
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
|
package/bin/adr_readiness.py
CHANGED
|
@@ -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,
|
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:
|