@rvdbreemen/adr-kit-opencode 0.59.1 → 0.61.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 +115 -39
- package/bin/adr-context +2 -1
- package/bin/adr-doctor +1 -1
- package/bin/adr-guardian +10 -1
- package/bin/adr-judge +12 -57
- package/bin/adr-settings +59 -8
- package/bin/adr-substance +15 -0
- package/bin/adr-suggest +8 -3
- package/bin/adr_config.py +33 -0
- package/bin/adr_doctor_checks.py +9 -3
- package/bin/adr_doctor_core.py +4 -4
- package/bin/adr_doctor_probes.py +100 -13
- package/bin/adr_llm.py +186 -3
- package/bin/adr_readiness.py +17 -1
- package/clients/workflows.json +10 -7
- package/hooks/adr_hook_core.py +176 -28
- package/instructions/ADR-guide.md +1 -1
- package/omp/extension.ts +365 -0
- package/opencode/plugin.ts +95 -14
- package/package.json +7 -1
- package/schemas/adr-kit-config.schema.json +7 -2
- package/scripts/client_generation.py +2 -5
- package/scripts/client_generation_artifacts.py +16 -2
- package/scripts/client_generation_model.py +9 -0
- package/scripts/release_phases.py +7 -7
- package/skills/adr/SKILL.md +2 -0
- package/skills/audit/SKILL.md +2 -0
- package/skills/context/SKILL.md +2 -0
- package/skills/grill/SKILL.md +2 -0
- package/skills/guardian/SKILL.md +8 -4
- package/skills/init/SKILL.md +34 -11
- package/skills/install-hooks/SKILL.md +12 -9
- package/skills/judge/SKILL.md +8 -3
- package/skills/lint/SKILL.md +4 -1
- package/skills/migrate/SKILL.md +2 -0
- package/skills/related/SKILL.md +4 -1
- package/skills/retire/SKILL.md +2 -0
- package/skills/review/SKILL.md +4 -1
- package/skills/settings/SKILL.md +2 -0
- package/skills/setup/SKILL.md +4 -1
- package/skills/supersede/SKILL.md +4 -1
- package/skills/upgrade/SKILL.md +24 -3
- package/templates/adr-kit-guide.md +3 -3
- package/templates/cc-settings/guardian-hook-entry.json +2 -2
- package/templates/githooks/pre-commit +37 -9
- package/templates/github-workflows/adr-index-check.yml +1 -1
- package/templates/github-workflows/adr-judge.yml +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
package/bin/adr-suggest
CHANGED
|
@@ -657,8 +657,9 @@ def main() -> int:
|
|
|
657
657
|
"--llm-timeout",
|
|
658
658
|
type=int,
|
|
659
659
|
default=None,
|
|
660
|
-
help="Per-call timeout for the LLM pass in seconds. Default
|
|
661
|
-
"suggest.llm_timeout_seconds
|
|
660
|
+
help="Per-call timeout for the LLM pass in seconds. Default: "
|
|
661
|
+
"suggest.llm_timeout_seconds, then judge.llm_timeout_seconds in .adr-kit.json, "
|
|
662
|
+
"then 30.",
|
|
662
663
|
)
|
|
663
664
|
p.add_argument(
|
|
664
665
|
"--json",
|
|
@@ -676,7 +677,11 @@ def main() -> int:
|
|
|
676
677
|
try:
|
|
677
678
|
adr_dir = Path(args.adr_dir).resolve()
|
|
678
679
|
config_path = Path(args.config) if args.config else (adr_dir / ".adr-kit.json")
|
|
679
|
-
|
|
680
|
+
# This machine's suggest.enabled wins over the team's (TASK-233): an
|
|
681
|
+
# "off" answered at init or upgrade lives in the gitignored file.
|
|
682
|
+
cfg = _adr_config.apply_machine_overrides(
|
|
683
|
+
load_config(config_path), load_local_config(adr_dir)
|
|
684
|
+
)
|
|
680
685
|
|
|
681
686
|
# Default ON (ADR-035), on the same terms ADR-017 set for the judge:
|
|
682
687
|
# one shared backend registry, the host CLI's own model, no pin. The
|
package/bin/adr_config.py
CHANGED
|
@@ -278,3 +278,36 @@ def load_json_config(path: Path) -> Dict[str, Any]:
|
|
|
278
278
|
except (OSError, json.JSONDecodeError):
|
|
279
279
|
return {}
|
|
280
280
|
return data if isinstance(data, dict) else {}
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
# The LLM switches a machine may override (TASK-233, ADR-049). An "off" answer
|
|
284
|
+
# at init or upgrade is one person's choice, so it lives in the gitignored
|
|
285
|
+
# .adr-kit.local.json and must not switch the layers off for the whole team
|
|
286
|
+
# (ADR-025). Only these booleans cross over: a machine file cannot retune
|
|
287
|
+
# budgets, scopes or anything else the team decided.
|
|
288
|
+
MACHINE_OVERRIDABLE = (
|
|
289
|
+
("judge", "llm_enabled"),
|
|
290
|
+
("suggest", "enabled"),
|
|
291
|
+
("guardian", "llm_enabled"),
|
|
292
|
+
("guardian", "llm_autorun"),
|
|
293
|
+
)
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def apply_machine_overrides(cfg: Dict[str, Any], local: Dict[str, Any]) -> Dict[str, Any]:
|
|
297
|
+
"""A copy of the project config with this machine's LLM switches applied."""
|
|
298
|
+
merged = {key: (dict(value) if isinstance(value, dict) else value) for key, value in (cfg or {}).items()}
|
|
299
|
+
for block, key in MACHINE_OVERRIDABLE:
|
|
300
|
+
local_block = (local or {}).get(block)
|
|
301
|
+
if not isinstance(local_block, dict) or not isinstance(local_block.get(key), bool):
|
|
302
|
+
continue
|
|
303
|
+
target = merged.get(block)
|
|
304
|
+
target = dict(target) if isinstance(target, dict) else {}
|
|
305
|
+
target[key] = local_block[key]
|
|
306
|
+
merged[block] = target
|
|
307
|
+
return merged
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def machine_override_source(local: Dict[str, Any], block: str, key: str) -> bool:
|
|
311
|
+
"""True when this machine's file sets one of the overridable switches."""
|
|
312
|
+
local_block = (local or {}).get(block)
|
|
313
|
+
return isinstance(local_block, dict) and isinstance(local_block.get(key), bool) and (block, key) in MACHINE_OVERRIDABLE
|
package/bin/adr_doctor_checks.py
CHANGED
|
@@ -50,7 +50,8 @@ HOOK_EVENTS = {
|
|
|
50
50
|
|
|
51
51
|
def resolve_launcher_target(
|
|
52
52
|
plugin_root: Path, command: str, args: list[str]
|
|
53
|
-
) -> tuple[str | None, list[str]]:
|
|
53
|
+
) -> tuple[str | None, list[str], list[str]]:
|
|
54
|
+
"""The resolved command, the payload files it runs, and the whole argv."""
|
|
54
55
|
expanded = [
|
|
55
56
|
value.replace("${PLUGIN_ROOT}", str(plugin_root))
|
|
56
57
|
.replace("${CLAUDE_PLUGIN_ROOT}", str(plugin_root))
|
|
@@ -63,6 +64,7 @@ def resolve_launcher_target(
|
|
|
63
64
|
else shutil.which(command)
|
|
64
65
|
)
|
|
65
66
|
targets = []
|
|
67
|
+
argv = [resolved_command or command]
|
|
66
68
|
for value in expanded:
|
|
67
69
|
candidate = Path(value)
|
|
68
70
|
if not candidate.is_absolute() and value.startswith("."):
|
|
@@ -71,7 +73,10 @@ def resolve_launcher_target(
|
|
|
71
73
|
"/" in value or "\\" in value
|
|
72
74
|
):
|
|
73
75
|
targets.append(str(candidate.resolve()))
|
|
74
|
-
|
|
76
|
+
argv.append(targets[-1])
|
|
77
|
+
else:
|
|
78
|
+
argv.append(value)
|
|
79
|
+
return resolved_command, targets, argv
|
|
75
80
|
|
|
76
81
|
|
|
77
82
|
def check_mcp_launcher(
|
|
@@ -103,7 +108,7 @@ def check_mcp_launcher(
|
|
|
103
108
|
summary=f"invalid owned MCP manifest {config_path}: {exc}",
|
|
104
109
|
actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
|
|
105
110
|
)
|
|
106
|
-
resolved, targets = resolve_launcher_target(root, command, args)
|
|
111
|
+
resolved, targets, argv = resolve_launcher_target(root, command, args)
|
|
107
112
|
missing = [target for target in targets if not Path(target).is_file()]
|
|
108
113
|
if resolved is None or missing:
|
|
109
114
|
return check(
|
|
@@ -134,6 +139,7 @@ def check_mcp_launcher(
|
|
|
134
139
|
"path": str(config_path),
|
|
135
140
|
"resolved_command": resolved,
|
|
136
141
|
"targets": targets,
|
|
142
|
+
"argv": argv,
|
|
137
143
|
}
|
|
138
144
|
],
|
|
139
145
|
)
|
package/bin/adr_doctor_core.py
CHANGED
|
@@ -183,9 +183,9 @@ def gate_findings_from_lint(lint_payload: Dict) -> List[Dict]:
|
|
|
183
183
|
return findings
|
|
184
184
|
|
|
185
185
|
|
|
186
|
-
def
|
|
186
|
+
def run_discover(repo_root: Path, discover_script: Path) -> Dict:
|
|
187
187
|
result = subprocess.run(
|
|
188
|
-
[sys.executable, str(
|
|
188
|
+
[sys.executable, str(discover_script), "--root", str(repo_root)],
|
|
189
189
|
capture_output=True,
|
|
190
190
|
text=True,
|
|
191
191
|
)
|
|
@@ -213,7 +213,7 @@ def run_doctor(args) -> Dict:
|
|
|
213
213
|
bin_dir = Path(__file__).resolve().parent
|
|
214
214
|
index_script = bin_dir / "adr-index"
|
|
215
215
|
lint_script = bin_dir / "adr-lint"
|
|
216
|
-
|
|
216
|
+
discover_script = bin_dir / "adr-discover"
|
|
217
217
|
|
|
218
218
|
if args.fix_index:
|
|
219
219
|
subprocess.run([sys.executable, str(index_script), str(adr_dir)], capture_output=True, text=True)
|
|
@@ -277,7 +277,7 @@ def run_doctor(args) -> Dict:
|
|
|
277
277
|
"reason": None,
|
|
278
278
|
}
|
|
279
279
|
if material_drift:
|
|
280
|
-
audit_payload =
|
|
280
|
+
audit_payload = run_discover(repo_root, discover_script)
|
|
281
281
|
audit_payload["reason"] = "material_drift"
|
|
282
282
|
|
|
283
283
|
return {
|
package/bin/adr_doctor_probes.py
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
5
|
import json
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
6
8
|
import subprocess
|
|
7
|
-
import sys
|
|
8
9
|
from pathlib import Path
|
|
9
10
|
|
|
10
11
|
from adr_doctor_models import benchmark_extension, check
|
|
@@ -29,6 +30,44 @@ def _command(values: list[str], *, cwd: Path, timeout: float) -> subprocess.Comp
|
|
|
29
30
|
)
|
|
30
31
|
|
|
31
32
|
|
|
33
|
+
# Codex runs a plugin's hooks only after the user reviews them with /hooks, and
|
|
34
|
+
# records each hook it trusts as a table in config.toml (observed with 0.162.1):
|
|
35
|
+
# [hooks.state."adr-kit@<marketplace>:hooks/hooks.json:<event>:<group>:<handler>"]
|
|
36
|
+
# trusted_hash = "sha256:..."
|
|
37
|
+
# Before that review there is no such table. Read with patterns rather than
|
|
38
|
+
# tomllib, which is 3.11+ against a floor of 3.10.
|
|
39
|
+
_TOML_TABLE = re.compile(r"^[ \t]*\[([^\[\]\n]+)\][ \t]*$", re.MULTILINE)
|
|
40
|
+
_CODEX_ADR_KIT_HOOK = re.compile(
|
|
41
|
+
r'hooks\.state\."adr-kit@[^":]+:hooks/hooks\.json:([a-z_]+):\d+:\d+"'
|
|
42
|
+
)
|
|
43
|
+
_TRUSTED_HASH = re.compile(
|
|
44
|
+
r'^[ \t]*trusted_hash[ \t]*=[ \t]*"sha256:[0-9a-f]+"', re.MULTILINE
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _codex_trusted_hooks() -> list[str]:
|
|
49
|
+
"""The ADR Kit hook events this user's Codex has trusted, sorted.
|
|
50
|
+
|
|
51
|
+
The file says whether a review happened, not whether the hooks still match
|
|
52
|
+
it: a hook an update changed needs a new review, and only the app-server's
|
|
53
|
+
experimental hooks/list can tell that apart.
|
|
54
|
+
"""
|
|
55
|
+
home = os.environ.get("CODEX_HOME")
|
|
56
|
+
config = (Path(home) if home else Path.home() / ".codex") / "config.toml"
|
|
57
|
+
try:
|
|
58
|
+
text = config.read_text(encoding="utf-8")
|
|
59
|
+
except (OSError, UnicodeError):
|
|
60
|
+
return []
|
|
61
|
+
tables = list(_TOML_TABLE.finditer(text))
|
|
62
|
+
events = set()
|
|
63
|
+
for index, table in enumerate(tables):
|
|
64
|
+
hook = _CODEX_ADR_KIT_HOOK.fullmatch(table.group(1).strip())
|
|
65
|
+
end = tables[index + 1].start() if index + 1 < len(tables) else len(text)
|
|
66
|
+
if hook and _TRUSTED_HASH.search(text, table.end(), end):
|
|
67
|
+
events.add(hook.group(1))
|
|
68
|
+
return sorted(events)
|
|
69
|
+
|
|
70
|
+
|
|
32
71
|
def _native_deep(root: Path, name: str, executable: str) -> dict:
|
|
33
72
|
command = (
|
|
34
73
|
[executable, "plugin", "list", "--json"]
|
|
@@ -42,25 +81,45 @@ def _native_deep(root: Path, name: str, executable: str) -> dict:
|
|
|
42
81
|
"native-registration", client=name, status="failed",
|
|
43
82
|
summary=f"native list probe failed: {exc}",
|
|
44
83
|
)
|
|
84
|
+
# No client prints its trust state in this listing. Looking for the words
|
|
85
|
+
# "trust" or "review" in it found Codex's untrusted hooks never, and found
|
|
86
|
+
# any plugin whose id or path carries one, such as code-review.
|
|
45
87
|
output = (result.stdout + result.stderr).lower()
|
|
46
|
-
if
|
|
47
|
-
status = "trust-pending"
|
|
48
|
-
elif result.returncode:
|
|
88
|
+
if result.returncode:
|
|
49
89
|
status = "failed"
|
|
50
90
|
elif "adr-kit" not in output:
|
|
51
91
|
status = "stale"
|
|
52
92
|
else:
|
|
53
93
|
status = "healthy"
|
|
94
|
+
evidence = {"command": command, "returncode": result.returncode}
|
|
95
|
+
actions = (
|
|
96
|
+
[{"detail": f"Review or reinstall ADR Kit in {name}."}]
|
|
97
|
+
if status != "healthy" else []
|
|
98
|
+
)
|
|
99
|
+
summary = f"bounded native plugin-list probe returned {status}"
|
|
100
|
+
if name == "codex" and status == "healthy":
|
|
101
|
+
evidence["trusted_hooks"] = _codex_trusted_hooks()
|
|
102
|
+
if not evidence["trusted_hooks"]:
|
|
103
|
+
status = "trust-pending"
|
|
104
|
+
summary = "Codex has not trusted ADR Kit's hooks, so none of them runs"
|
|
105
|
+
actions = [{"detail": (
|
|
106
|
+
"Open Codex and review ADR Kit's hooks with /hooks. Codex runs "
|
|
107
|
+
"a plugin's hooks only after that review, and asks again when "
|
|
108
|
+
"an update changes them."
|
|
109
|
+
)}]
|
|
54
110
|
return check(
|
|
55
111
|
"native-registration", client=name, status=status,
|
|
56
|
-
summary=
|
|
57
|
-
evidence=[{"command": command, "returncode": result.returncode}],
|
|
58
|
-
actions=[{"detail": f"Review or reinstall ADR Kit in {name}."}]
|
|
59
|
-
if status != "healthy" else [],
|
|
112
|
+
summary=summary, evidence=[evidence], actions=actions,
|
|
60
113
|
)
|
|
61
114
|
|
|
62
115
|
|
|
63
|
-
def _mcp_deep(root: Path,
|
|
116
|
+
def _mcp_deep(root: Path, argv: list[str], *, client: str, required: bool = True) -> dict:
|
|
117
|
+
"""Initialize, list and call the server the way the client starts it.
|
|
118
|
+
|
|
119
|
+
`argv` is the client's registered command as the launcher check resolved
|
|
120
|
+
it. This probe used to start bin/adr-mcp with the doctor's own interpreter,
|
|
121
|
+
so it said healthy for a server the client could not start (DEF-33).
|
|
122
|
+
"""
|
|
64
123
|
messages = [
|
|
65
124
|
{
|
|
66
125
|
"jsonrpc": "2.0",
|
|
@@ -86,7 +145,7 @@ def _mcp_deep(root: Path, plugin_root: Path) -> dict:
|
|
|
86
145
|
]
|
|
87
146
|
try:
|
|
88
147
|
result = subprocess.run(
|
|
89
|
-
|
|
148
|
+
argv,
|
|
90
149
|
input="\n".join(json.dumps(item) for item in messages) + "\n",
|
|
91
150
|
cwd=str(root),
|
|
92
151
|
capture_output=True,
|
|
@@ -123,17 +182,20 @@ def _mcp_deep(root: Path, plugin_root: Path) -> dict:
|
|
|
123
182
|
TypeError,
|
|
124
183
|
) as exc:
|
|
125
184
|
return check(
|
|
126
|
-
"mcp-live", status="failed",
|
|
185
|
+
"mcp-live", client=client, status="failed", required=required,
|
|
127
186
|
summary=f"MCP initialize/list/call probe failed: {exc}",
|
|
187
|
+
evidence=[{"argv": argv}],
|
|
128
188
|
actions=[{"detail": "Run adr-doctor --deep after reinstalling ADR Kit."}],
|
|
129
189
|
)
|
|
130
190
|
return check(
|
|
131
|
-
"mcp-live", status="healthy" if healthy else "failed",
|
|
191
|
+
"mcp-live", client=client, status="healthy" if healthy else "failed",
|
|
192
|
+
required=required,
|
|
132
193
|
summary=(
|
|
133
194
|
"MCP initialize, tools/list, and adr_status call passed"
|
|
134
195
|
if healthy else "MCP handshake returned an incomplete result"
|
|
135
196
|
),
|
|
136
197
|
evidence=[{
|
|
198
|
+
"argv": argv,
|
|
137
199
|
"returncode": result.returncode,
|
|
138
200
|
"tools": sorted(tools),
|
|
139
201
|
"call_ok": called,
|
|
@@ -141,6 +203,31 @@ def _mcp_deep(root: Path, plugin_root: Path) -> dict:
|
|
|
141
203
|
)
|
|
142
204
|
|
|
143
205
|
|
|
206
|
+
def _registered_mcp_live(root: Path, checks: list[dict]) -> list[dict]:
|
|
207
|
+
"""One live check per client whose MCP launcher the doctor examined."""
|
|
208
|
+
live = []
|
|
209
|
+
for item in checks:
|
|
210
|
+
if item.get("id") != "mcp-launcher" or item.get("status") == "unsupported":
|
|
211
|
+
continue
|
|
212
|
+
client, required = item["client"], item["required"]
|
|
213
|
+
evidence = (item.get("evidence") or [{}])[0]
|
|
214
|
+
argv = evidence.get("argv") if item.get("status") == "healthy" else None
|
|
215
|
+
if argv:
|
|
216
|
+
live.append(_mcp_deep(root, argv, client=client, required=required))
|
|
217
|
+
continue
|
|
218
|
+
command = evidence.get("command", "the registered command")
|
|
219
|
+
live.append(check(
|
|
220
|
+
"mcp-live", client=client, status="failed", required=required,
|
|
221
|
+
summary=(
|
|
222
|
+
f"{client} cannot start the MCP server: {command} does not "
|
|
223
|
+
"resolve, or the payload it runs is missing"
|
|
224
|
+
),
|
|
225
|
+
evidence=[{"command": command}],
|
|
226
|
+
actions=item.get("actions") or [],
|
|
227
|
+
))
|
|
228
|
+
return live
|
|
229
|
+
|
|
230
|
+
|
|
144
231
|
def run_deep_extensions(
|
|
145
232
|
root: Path,
|
|
146
233
|
plugin_root: Path,
|
|
@@ -153,7 +240,7 @@ def run_deep_extensions(
|
|
|
153
240
|
_native_deep(root, name, client.executable)
|
|
154
241
|
for name, client in detect_clients().items()
|
|
155
242
|
]
|
|
156
|
-
extensions.
|
|
243
|
+
extensions.extend(_registered_mcp_live(root, checks))
|
|
157
244
|
# The harness reads plugin_root/tests/fixtures/hooks/reference-corpus.json,
|
|
158
245
|
# and `tests` is a forbidden segment in the public payload -- so the fixture
|
|
159
246
|
# is absent from EVERY installed payload, not only from a generated client
|
package/bin/adr_llm.py
CHANGED
|
@@ -58,10 +58,24 @@ DEFAULT_BACKEND = BACKEND_HOST
|
|
|
58
58
|
# GitHub Copilot CLI 1.0.71. Deliberately NO model flag in any row -- each CLI
|
|
59
59
|
# then resolves whatever model its own user configured, which is the entire
|
|
60
60
|
# point of the host backend.
|
|
61
|
+
#
|
|
62
|
+
# OpenCode (1.18.28, verified 2026-10-06) reads the prompt on stdin and writes
|
|
63
|
+
# the answer to stdout. `--pure` skips external plugins: run inside a project
|
|
64
|
+
# with adr-kit's own OpenCode plugin, a judging call would otherwise trigger
|
|
65
|
+
# that plugin's hooks. It is a host here, not a certified client (ADR-039).
|
|
66
|
+
#
|
|
67
|
+
# OMP (18.12.5, verified 2026-10-21) reads the prompt on stdin in print mode
|
|
68
|
+
# and writes only the answer to stdout. `--no-extensions` keeps adr-kit's own
|
|
69
|
+
# OMP extension from firing inside a judging call, `--no-session` keeps the
|
|
70
|
+
# call out of the user's session list, and `--no-tools` keeps the judge a pure
|
|
71
|
+
# text answer. ADR-050 makes OMP a certified client; certification lands in
|
|
72
|
+
# v0.62.0.
|
|
61
73
|
HOST_COMMANDS = {
|
|
62
74
|
"claude-code-cli": ["claude", "-p"],
|
|
63
75
|
"codex-cli": ["codex", "exec"],
|
|
64
76
|
"github-copilot-cli": ["copilot", "-p"],
|
|
77
|
+
"opencode-cli": ["opencode", "run", "--pure"],
|
|
78
|
+
"omp-cli": ["omp", "-p", "--no-extensions", "--no-session", "--no-tools"],
|
|
65
79
|
}
|
|
66
80
|
|
|
67
81
|
# Machine-local, gitignored sibling of .adr-kit.json. Neither entry point can
|
|
@@ -184,6 +198,13 @@ def run_cli(cmd: List[str], input_text: str, timeout_s: float) -> subprocess.Com
|
|
|
184
198
|
`subprocess.TimeoutExpired` on timeout, like `subprocess.run`.
|
|
185
199
|
"""
|
|
186
200
|
session = {"start_new_session": True} if os.name != "nt" else {}
|
|
201
|
+
# Resolve the name the way a shell would. On Windows an npm-installed CLI
|
|
202
|
+
# (codex, copilot, opencode) is a `<name>.cmd` shim that CreateProcess only
|
|
203
|
+
# finds by its full path, so the bare name failed with FileNotFoundError and
|
|
204
|
+
# the LLM pass degraded silently (TASK-233).
|
|
205
|
+
resolved = shutil.which(cmd[0]) if cmd else None
|
|
206
|
+
if resolved:
|
|
207
|
+
cmd = [resolved, *cmd[1:]]
|
|
187
208
|
with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
|
|
188
209
|
proc = subprocess.Popen(
|
|
189
210
|
cmd, stdin=subprocess.PIPE, stdout=out, stderr=err, **session
|
|
@@ -311,9 +332,13 @@ def resolve_llm_backend(
|
|
|
311
332
|
) -> Tuple[Optional[LLMBackend], List[str]]:
|
|
312
333
|
"""Pick the backend for this run and collect anything the user should know.
|
|
313
334
|
|
|
314
|
-
Precedence, highest first: --llm-cmd,
|
|
315
|
-
|
|
316
|
-
|
|
335
|
+
Precedence, highest first: ADR_KIT_NO_LLM=1 (no backend at all), --llm-cmd,
|
|
336
|
+
ADR_KIT_LLM_CMD, judge.backend. The switch is checked here, not in each
|
|
337
|
+
caller, so it holds for every pass that calls a model: the judge, the
|
|
338
|
+
suggestion pass and the substance check (TASK-221). --llm-cmd and
|
|
339
|
+
ADR_KIT_LLM_CMD are operator-controlled and therefore unrestricted;
|
|
340
|
+
judge.backend is a key looked up in the code-side BACKENDS table and can
|
|
341
|
+
introduce nothing.
|
|
317
342
|
|
|
318
343
|
Warnings are returned rather than printed so --show-config can render them
|
|
319
344
|
without a judging run, and so the caller controls ordering.
|
|
@@ -326,6 +351,9 @@ def resolve_llm_backend(
|
|
|
326
351
|
# (adr_config.REMOVED_KEYS, ADR-036), so a validated cfg cannot carry one.
|
|
327
352
|
warnings: List[str] = []
|
|
328
353
|
|
|
354
|
+
if env.get("ADR_KIT_NO_LLM") == "1":
|
|
355
|
+
warnings.append("ADR_KIT_NO_LLM=1: no model is called; the LLM pass is skipped.")
|
|
356
|
+
return None, warnings
|
|
329
357
|
if cli_cmd:
|
|
330
358
|
return SubprocessBackend(_split_cmd(cli_cmd), source="flag"), warnings
|
|
331
359
|
if env.get("ADR_KIT_LLM_CMD"):
|
|
@@ -391,3 +419,158 @@ def credential_refusal_message(path, offenders: List[str]) -> str:
|
|
|
391
419
|
f"while the key is in it. Then rotate the key: it is already in "
|
|
392
420
|
f"your git history."
|
|
393
421
|
)
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
# ---------- the machine-local judge config (ADR-025, ADR-049) ----------
|
|
425
|
+
#
|
|
426
|
+
# One writer for the gitignored companion of .adr-kit.json, shared by
|
|
427
|
+
# `adr-judge --set-backend/--record-host-client` and the SessionStart hook, so
|
|
428
|
+
# both write atomically and both keep the file out of version control the same
|
|
429
|
+
# way.
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
def atomic_write_json(path, document: Dict) -> None:
|
|
433
|
+
from pathlib import Path
|
|
434
|
+
|
|
435
|
+
path = Path(path)
|
|
436
|
+
payload = json.dumps(document, indent=2, sort_keys=True) + "\n"
|
|
437
|
+
temporary = path.with_name(f".{path.name}.tmp")
|
|
438
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
439
|
+
with open(temporary, "w", encoding="utf-8", newline="\n") as out:
|
|
440
|
+
out.write(payload)
|
|
441
|
+
out.flush()
|
|
442
|
+
os.fsync(out.fileno())
|
|
443
|
+
os.replace(temporary, path)
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def register_git_exclude(adr_dir, name: str) -> None:
|
|
447
|
+
"""Best-effort .git/info/exclude entry for a machine-local file.
|
|
448
|
+
|
|
449
|
+
.gitignore is committed and belongs to the project; .git/info/exclude is
|
|
450
|
+
per-clone and belongs to this machine, which is the right scope for a file
|
|
451
|
+
that records one operator's client choice. Every failure is silent: a
|
|
452
|
+
missing exclude entry is untidy, not unsafe.
|
|
453
|
+
"""
|
|
454
|
+
from pathlib import Path
|
|
455
|
+
|
|
456
|
+
adr_dir = Path(adr_dir)
|
|
457
|
+
try:
|
|
458
|
+
located = _locate_git(adr_dir)
|
|
459
|
+
if located is None:
|
|
460
|
+
return
|
|
461
|
+
work_tree, common_dir = located
|
|
462
|
+
exclude = common_dir / "info" / "exclude"
|
|
463
|
+
entry = (adr_dir / name).resolve()
|
|
464
|
+
try:
|
|
465
|
+
relative = entry.relative_to(work_tree).as_posix()
|
|
466
|
+
except ValueError:
|
|
467
|
+
relative = name
|
|
468
|
+
existing = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
|
|
469
|
+
if relative in existing.splitlines():
|
|
470
|
+
return
|
|
471
|
+
exclude.parent.mkdir(parents=True, exist_ok=True)
|
|
472
|
+
with open(exclude, "a", encoding="utf-8", newline="\n") as out:
|
|
473
|
+
out.write(("" if existing.endswith("\n") or not existing else "\n") + relative + "\n")
|
|
474
|
+
except (OSError, subprocess.SubprocessError, ValueError):
|
|
475
|
+
return None
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
def _locate_git(start):
|
|
479
|
+
"""(work tree, common git dir) for `start`, found by walking up; or None.
|
|
480
|
+
|
|
481
|
+
No `git` subprocess: the SessionStart hook writes through this and has a
|
|
482
|
+
1000 ms budget (ADR-030), which one process spawn on a cold Windows machine
|
|
483
|
+
can eat. A `.git` directory is the common dir itself; a `.git` file (a linked
|
|
484
|
+
worktree) points at its own git dir, whose `commondir` names the shared one,
|
|
485
|
+
and info/exclude lives there.
|
|
486
|
+
"""
|
|
487
|
+
from pathlib import Path
|
|
488
|
+
|
|
489
|
+
current = Path(start).resolve()
|
|
490
|
+
for candidate in (current, *current.parents):
|
|
491
|
+
dot_git = candidate / ".git"
|
|
492
|
+
if dot_git.is_dir():
|
|
493
|
+
return candidate, dot_git
|
|
494
|
+
if dot_git.is_file():
|
|
495
|
+
text = dot_git.read_text(encoding="utf-8", errors="replace").strip()
|
|
496
|
+
if not text.startswith("gitdir:"):
|
|
497
|
+
return None
|
|
498
|
+
git_dir = Path(text[len("gitdir:"):].strip())
|
|
499
|
+
if not git_dir.is_absolute():
|
|
500
|
+
git_dir = (candidate / git_dir).resolve()
|
|
501
|
+
common_file = git_dir / "commondir"
|
|
502
|
+
if common_file.is_file():
|
|
503
|
+
common = Path(common_file.read_text(encoding="utf-8").strip())
|
|
504
|
+
git_dir = common if common.is_absolute() else (git_dir / common).resolve()
|
|
505
|
+
return candidate, git_dir
|
|
506
|
+
return None
|
|
507
|
+
|
|
508
|
+
|
|
509
|
+
def _read_json_object(path) -> Optional[Dict]:
|
|
510
|
+
"""The object in `path`, {} when the file is absent, None when unusable."""
|
|
511
|
+
from pathlib import Path
|
|
512
|
+
|
|
513
|
+
path = Path(path)
|
|
514
|
+
if not path.exists():
|
|
515
|
+
return {}
|
|
516
|
+
try:
|
|
517
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
518
|
+
except (OSError, UnicodeError, json.JSONDecodeError):
|
|
519
|
+
return None
|
|
520
|
+
return data if isinstance(data, dict) else None
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
def write_local_value(adr_dir, block: str, key: str, value):
|
|
524
|
+
"""Record one `block.key` value machine-locally, atomically, and untracked."""
|
|
525
|
+
from pathlib import Path
|
|
526
|
+
|
|
527
|
+
path = Path(adr_dir) / LOCAL_CONFIG_NAME
|
|
528
|
+
document = _read_json_object(path) or {}
|
|
529
|
+
section = document.get(block)
|
|
530
|
+
if not isinstance(section, dict):
|
|
531
|
+
section = {}
|
|
532
|
+
section[key] = value
|
|
533
|
+
document[block] = section
|
|
534
|
+
atomic_write_json(path, document)
|
|
535
|
+
register_git_exclude(adr_dir, LOCAL_CONFIG_NAME)
|
|
536
|
+
return path
|
|
537
|
+
|
|
538
|
+
|
|
539
|
+
def write_local_judge_value(adr_dir, key: str, value: str):
|
|
540
|
+
"""Record one judge value machine-locally, atomically, and keep it untracked."""
|
|
541
|
+
return write_local_value(adr_dir, "judge", key, value)
|
|
542
|
+
|
|
543
|
+
|
|
544
|
+
def record_host_client_if_absent(adr_dir, client: str) -> Optional[str]:
|
|
545
|
+
"""Record `client` as the judge host when nothing has been decided yet.
|
|
546
|
+
|
|
547
|
+
ADR-049: a default install should leave the LLM passes able to run, and the
|
|
548
|
+
common install route (a client's own plugin install) never runs the
|
|
549
|
+
installer that used to record the host. The session knows which client it
|
|
550
|
+
runs in, so the first session records it. Returns the recorded id, or None
|
|
551
|
+
when it wrote nothing:
|
|
552
|
+
|
|
553
|
+
* the client has no host command (an id outside `HOST_COMMANDS`);
|
|
554
|
+
* the project switched the pass off (`judge.llm_enabled: false`);
|
|
555
|
+
* a host client is already recorded -- a person's choice is never replaced;
|
|
556
|
+
* either config file exists but cannot be read -- never clobber it.
|
|
557
|
+
"""
|
|
558
|
+
from pathlib import Path
|
|
559
|
+
|
|
560
|
+
if client not in HOST_COMMANDS:
|
|
561
|
+
return None
|
|
562
|
+
adr_dir = Path(adr_dir)
|
|
563
|
+
tracked = _read_json_object(adr_dir / ".adr-kit.json")
|
|
564
|
+
local = _read_json_object(adr_dir / LOCAL_CONFIG_NAME)
|
|
565
|
+
if tracked is None or local is None:
|
|
566
|
+
return None
|
|
567
|
+
tracked_judge = tracked.get("judge") if isinstance(tracked.get("judge"), dict) else {}
|
|
568
|
+
local_judge = local.get("judge") if isinstance(local.get("judge"), dict) else {}
|
|
569
|
+
# The effective switch: this machine's value wins over the team's (TASK-233).
|
|
570
|
+
enabled = local_judge.get("llm_enabled", tracked_judge.get("llm_enabled", True))
|
|
571
|
+
if enabled is False:
|
|
572
|
+
return None
|
|
573
|
+
if local_judge.get("host_client"):
|
|
574
|
+
return None
|
|
575
|
+
write_local_judge_value(adr_dir, "host_client", client)
|
|
576
|
+
return client
|
package/bin/adr_readiness.py
CHANGED
|
@@ -253,6 +253,14 @@ def _mechanical_findings(record: Dict) -> List[Dict[str, str]]:
|
|
|
253
253
|
return sorted(findings, key=lambda item: item["code"])
|
|
254
254
|
|
|
255
255
|
|
|
256
|
+
def _supersession_inconsistent(record: Dict, mechanical: Sequence[Dict[str, str]]) -> bool:
|
|
257
|
+
"""True when a record's supersession state still needs a person to settle it."""
|
|
258
|
+
if any(item.get("code") == "SUPERSESSION_STATE_INCONSISTENT" for item in mechanical):
|
|
259
|
+
return True
|
|
260
|
+
status = str(record.get("status", "")).casefold()
|
|
261
|
+
return status == "superseded" and not record.get("superseded_by")
|
|
262
|
+
|
|
263
|
+
|
|
256
264
|
def _record_path(record: Dict, adr_dir: Optional[Path] = None) -> Optional[Path]:
|
|
257
265
|
"""Resolve a record's bare filename against the ADR directory, or None.
|
|
258
266
|
|
|
@@ -400,6 +408,14 @@ def readiness_for_record(
|
|
|
400
408
|
"ready-for-confirmation": f"/adr-kit:grill {record['adr_id']}",
|
|
401
409
|
"supersession-required": f"/adr-kit:grill --revalidate {record['adr_id']}",
|
|
402
410
|
}
|
|
411
|
+
next_command = next_commands.get(classification)
|
|
412
|
+
# ADR-011 fixes the seven classes, so a finished supersession keeps its
|
|
413
|
+
# label; it just has nothing left to do. Revalidation is suggested only
|
|
414
|
+
# where status and successor disagree (TASK-234).
|
|
415
|
+
if classification == "supersession-required" and not _supersession_inconsistent(
|
|
416
|
+
record, mechanical
|
|
417
|
+
):
|
|
418
|
+
next_command = None
|
|
403
419
|
return {
|
|
404
420
|
"adr_id": record["adr_id"],
|
|
405
421
|
"title": record["title"],
|
|
@@ -430,7 +446,7 @@ def readiness_for_record(
|
|
|
430
446
|
),
|
|
431
447
|
"implementation_link": link,
|
|
432
448
|
"related_adrs": related,
|
|
433
|
-
"next_command":
|
|
449
|
+
"next_command": next_command,
|
|
434
450
|
}
|
|
435
451
|
|
|
436
452
|
|