@rvdbreemen/adr-kit-opencode 0.52.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 +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
package/bin/adr_llm.py
ADDED
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
"""Shared LLM backend registry for adr-kit's model-calling entry points.
|
|
2
|
+
|
|
3
|
+
ADR-017 replaced a pinned vendor CLI with a named enum resolving to a code-side
|
|
4
|
+
command table. `bin/adr-judge` shipped that table under TASK-59; `bin/adr-suggest`
|
|
5
|
+
kept its own default command vector naming one vendor and one pinned model tag,
|
|
6
|
+
and kept honouring `suggest.llm_cmd` / `judge.llm_cmd` (TASK-72), so the
|
|
7
|
+
guarantee "repository-tracked configuration may never introduce a command" held
|
|
8
|
+
for one entry point and not the other.
|
|
9
|
+
|
|
10
|
+
This module is that table, extracted so there is exactly one of it. A second
|
|
11
|
+
registry that drifts from the first is worse than the single violation it would
|
|
12
|
+
have replaced: it puts the rule in two places and lets them disagree silently.
|
|
13
|
+
|
|
14
|
+
Both importers reach it through their own `_load_sibling`, so no sys.path entry
|
|
15
|
+
is created and nothing committed next to these scripts can shadow it.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import json
|
|
21
|
+
import os
|
|
22
|
+
import re
|
|
23
|
+
import shlex
|
|
24
|
+
import shutil
|
|
25
|
+
import subprocess
|
|
26
|
+
import sys
|
|
27
|
+
from typing import Dict, List, Optional, Tuple
|
|
28
|
+
|
|
29
|
+
# Which entry point is running, used only as the warning prefix. A plain module
|
|
30
|
+
# global rather than a parameter threaded through three factories and four
|
|
31
|
+
# backend classes: exactly one entry point runs per process, so there is no
|
|
32
|
+
# second value for it to be wrong about. Importers assign it at load time.
|
|
33
|
+
TOOL = "adr-kit"
|
|
34
|
+
|
|
35
|
+
# ---------- backend registry (ADR-017) ----------
|
|
36
|
+
#
|
|
37
|
+
# The judge used to hard-code one vendor CLI and one pinned model tag. Two
|
|
38
|
+
# things were wrong with that shape. A user working in a different agent got a
|
|
39
|
+
# judge that did not match the assistant they were actually using, and the
|
|
40
|
+
# pinned tag was a vendor decision adr-kit had no standing to make on their
|
|
41
|
+
# behalf. ADR-017 replaces it with a named enum resolving to THIS table.
|
|
42
|
+
#
|
|
43
|
+
# The registry is code-side on purpose. .adr-kit.json is committed, so anyone
|
|
44
|
+
# with commit access authors it; it may select among backends the operator has
|
|
45
|
+
# enabled, but it may never introduce a binary, an endpoint, or a credential.
|
|
46
|
+
# Because the table lives here and config carries only an enum value, that
|
|
47
|
+
# property is structural rather than guarded: there is no argument vector in
|
|
48
|
+
# any configuration file, tracked or not, for a check to have to refuse.
|
|
49
|
+
|
|
50
|
+
BACKEND_HOST = "host"
|
|
51
|
+
BACKEND_NAMES = (BACKEND_HOST,)
|
|
52
|
+
DEFAULT_BACKEND = BACKEND_HOST
|
|
53
|
+
|
|
54
|
+
# Non-interactive entry point of each certified client (ADR-010), verified
|
|
55
|
+
# 2026-07-30 against the installed binaries: claude 2.1.220, codex-cli 0.145.0,
|
|
56
|
+
# GitHub Copilot CLI 1.0.71. Deliberately NO model flag in any row -- each CLI
|
|
57
|
+
# then resolves whatever model its own user configured, which is the entire
|
|
58
|
+
# point of the host backend.
|
|
59
|
+
HOST_COMMANDS = {
|
|
60
|
+
"claude-code-cli": ["claude", "-p"],
|
|
61
|
+
"codex-cli": ["codex", "exec"],
|
|
62
|
+
"github-copilot-cli": ["copilot", "-p"],
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
# Machine-local, gitignored sibling of .adr-kit.json. Neither entry point can
|
|
66
|
+
# detect which client it runs in -- a `git commit` is client-agnostic, it
|
|
67
|
+
# happens whether or not any agent is running -- so the installer records the
|
|
68
|
+
# client here at install time, when it is known with certainty because the
|
|
69
|
+
# operator named it. ADR-017 rejects probing PATH: on a machine with all three
|
|
70
|
+
# CLIs installed the probe order would silently decide which vendor receives
|
|
71
|
+
# the repository diff, and that is a privacy decision made by accident.
|
|
72
|
+
LOCAL_CONFIG_NAME = ".adr-kit.local.json"
|
|
73
|
+
|
|
74
|
+
# Config keys that would carry a credential. docs/adr/.adr-kit.json is
|
|
75
|
+
# committed, so a key written there is a published key. The schema already
|
|
76
|
+
# refuses unknown properties, but "unknown property" does not tell an author
|
|
77
|
+
# what to do instead, and a leaked credential is worth an error that names the
|
|
78
|
+
# environment variable by hand.
|
|
79
|
+
# Anchored on the WHOLE key, not a substring: `inject.max_tokens` is a real
|
|
80
|
+
# setting and a substring match on "token" would refuse a valid config with a
|
|
81
|
+
# security error, which is the most expensive kind of false positive there is.
|
|
82
|
+
# Hence `_token` but not `_tokens`.
|
|
83
|
+
_CREDENTIAL_KEY_RE = re.compile(
|
|
84
|
+
r"(?i)^(.*_)?(api_?key|key|secrets?|token|password|passwd|credentials?"
|
|
85
|
+
r"|bearer|authorization)$"
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
def _warn(message: str) -> None:
|
|
89
|
+
print(f"[{TOOL}] WARN: {message}", file=sys.stderr)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _split_cmd(cmd_str: str) -> List[str]:
|
|
93
|
+
"""Split a shell command string into a token list, Windows-path-safe.
|
|
94
|
+
|
|
95
|
+
shlex.split uses POSIX mode by default, which treats backslashes as escape
|
|
96
|
+
characters. On Windows this mangles paths like C:\\Users\\... -> C:Users...
|
|
97
|
+
before shutil.which ever sees them. Using posix=False preserves backslashes;
|
|
98
|
+
we strip surrounding quote pairs that posix=False would otherwise keep.
|
|
99
|
+
"""
|
|
100
|
+
tokens = shlex.split(cmd_str, posix=(sys.platform != "win32"))
|
|
101
|
+
if sys.platform == "win32":
|
|
102
|
+
stripped = []
|
|
103
|
+
for t in tokens:
|
|
104
|
+
if len(t) >= 2 and ((t[0] == '"' and t[-1] == '"') or (t[0] == "'" and t[-1] == "'")):
|
|
105
|
+
t = t[1:-1]
|
|
106
|
+
stripped.append(t)
|
|
107
|
+
return stripped
|
|
108
|
+
return tokens
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class LLMBackend:
|
|
112
|
+
"""One way of getting a verdict out of a model.
|
|
113
|
+
|
|
114
|
+
Three failure taxonomies live behind this interface -- process spawn, HTTP
|
|
115
|
+
status, and daemon availability -- and ADR-017 requires all three to map to
|
|
116
|
+
the same outcome: degrade to declarative-only, never block. So `judge`
|
|
117
|
+
returns None for every fault rather than raising, and `unavailable_reason`
|
|
118
|
+
reports what can be known before spending anything.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
kind = ""
|
|
122
|
+
|
|
123
|
+
def describe(self) -> str:
|
|
124
|
+
raise NotImplementedError
|
|
125
|
+
|
|
126
|
+
def unavailable_reason(self) -> Optional[str]:
|
|
127
|
+
"""Why this backend cannot run, checked before the first call."""
|
|
128
|
+
return None
|
|
129
|
+
|
|
130
|
+
def judge(self, prompt: str, timeout_s: int, adr_id: str) -> Optional[str]:
|
|
131
|
+
"""Return the model's raw response text, or None to degrade.
|
|
132
|
+
|
|
133
|
+
`adr_id` labels the call in warnings. adr-judge passes the ADR under
|
|
134
|
+
review; adr-suggest has no ADR yet and passes its own label.
|
|
135
|
+
"""
|
|
136
|
+
raise NotImplementedError
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
class SubprocessBackend(LLMBackend):
|
|
140
|
+
"""Spawn a client CLI, feed it the prompt on stdin, read stdout.
|
|
141
|
+
|
|
142
|
+
Backs both the `host` backend and the operator overrides (--llm-cmd,
|
|
143
|
+
ADR_KIT_LLM_CMD), because those differ in where the vector came from, not
|
|
144
|
+
in how it is run.
|
|
145
|
+
"""
|
|
146
|
+
|
|
147
|
+
kind = BACKEND_HOST
|
|
148
|
+
|
|
149
|
+
def __init__(self, cmd: List[str], source: str, client: Optional[str] = None):
|
|
150
|
+
self.cmd = list(cmd)
|
|
151
|
+
self.source = source
|
|
152
|
+
self.client = client
|
|
153
|
+
|
|
154
|
+
def describe(self) -> str:
|
|
155
|
+
label = self.client or "operator override"
|
|
156
|
+
return f"{self.kind} ({label}): {' '.join(self.cmd)}"
|
|
157
|
+
|
|
158
|
+
def unavailable_reason(self) -> Optional[str]:
|
|
159
|
+
if not self.cmd:
|
|
160
|
+
return "no host command was resolved"
|
|
161
|
+
if shutil.which(self.cmd[0]) is None:
|
|
162
|
+
return (
|
|
163
|
+
f"{self.cmd[0]!r} is not on PATH; install the client CLI or "
|
|
164
|
+
f"choose another judge.backend"
|
|
165
|
+
)
|
|
166
|
+
return None
|
|
167
|
+
|
|
168
|
+
def judge(self, prompt: str, timeout_s: int, adr_id: str) -> Optional[str]:
|
|
169
|
+
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
|
+
)
|
|
178
|
+
except subprocess.TimeoutExpired:
|
|
179
|
+
_warn(
|
|
180
|
+
f"LLM call timed out after {timeout_s}s on {adr_id}; skipping "
|
|
181
|
+
f"LLM pass. Increase judge.llm_timeout_seconds in .adr-kit.json "
|
|
182
|
+
f"if commits routinely exceed this."
|
|
183
|
+
)
|
|
184
|
+
return None
|
|
185
|
+
except OSError as e:
|
|
186
|
+
# A command that cannot be spawned at all (CreateProcess/execvp
|
|
187
|
+
# failure) must degrade like every other tooling fault, not escape
|
|
188
|
+
# as an uncaught exception and exit 1 -- that would read as
|
|
189
|
+
# "violation".
|
|
190
|
+
_warn(
|
|
191
|
+
f"LLM command could not be started "
|
|
192
|
+
f"({e.__class__.__name__}); skipping LLM pass."
|
|
193
|
+
)
|
|
194
|
+
return None
|
|
195
|
+
if result.returncode != 0:
|
|
196
|
+
# SEC-LOW: don't leak stderr (may contain tokens, paths, prompts)
|
|
197
|
+
# by default. Operators opt in to the full payload via ADR_KIT_DEBUG.
|
|
198
|
+
if os.environ.get("ADR_KIT_DEBUG"):
|
|
199
|
+
_warn(
|
|
200
|
+
f"LLM command exited {result.returncode} on {adr_id}: "
|
|
201
|
+
f"{result.stderr.strip()[:200]!r}; skipping LLM pass."
|
|
202
|
+
)
|
|
203
|
+
else:
|
|
204
|
+
_warn("LLM call failed. Rerun with ADR_KIT_DEBUG=1 for details.")
|
|
205
|
+
return None
|
|
206
|
+
return result.stdout
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _host_backend(
|
|
210
|
+
judge_cfg: Dict, local_cfg: Dict, warnings: List[str]
|
|
211
|
+
) -> Optional[SubprocessBackend]:
|
|
212
|
+
"""Build the host backend from the installer-written client id.
|
|
213
|
+
|
|
214
|
+
Returns None when no client was recorded. ADR-017: "If no host command was
|
|
215
|
+
written (adr-kit used outside a client install), the judge degrades to
|
|
216
|
+
declarative-only with one warning. It does not guess."
|
|
217
|
+
"""
|
|
218
|
+
client = (local_cfg.get("judge") or {}).get("host_client")
|
|
219
|
+
if not client:
|
|
220
|
+
warnings.append(
|
|
221
|
+
f"judge.backend is 'host' but no client was recorded in "
|
|
222
|
+
f"{LOCAL_CONFIG_NAME}; the LLM pass will not run. Register one with "
|
|
223
|
+
f"`adr-judge --set-backend host --host-client "
|
|
224
|
+
f"<{'|'.join(HOST_COMMANDS)}>` or via /adr-kit:init."
|
|
225
|
+
)
|
|
226
|
+
return None
|
|
227
|
+
if client not in HOST_COMMANDS:
|
|
228
|
+
warnings.append(
|
|
229
|
+
f"{LOCAL_CONFIG_NAME} names unknown host client {client!r}; "
|
|
230
|
+
f"expected one of {sorted(HOST_COMMANDS)}. The LLM pass will not run."
|
|
231
|
+
)
|
|
232
|
+
return None
|
|
233
|
+
return SubprocessBackend(HOST_COMMANDS[client], source="local", client=client)
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
# THE registry ADR-017 names. A dict rather than an if-chain because the whole
|
|
237
|
+
# security argument rests on config selecting a KEY here and never supplying a
|
|
238
|
+
# value: judge.backend is looked up in this table or refused, so committed
|
|
239
|
+
# configuration has no path to a command, an argument vector, an endpoint or a
|
|
240
|
+
# credential. Every endpoint and every command lives on this side of the line.
|
|
241
|
+
BACKENDS = {
|
|
242
|
+
BACKEND_HOST: _host_backend,
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def resolve_llm_backend(
|
|
247
|
+
judge_cfg: Dict,
|
|
248
|
+
local_cfg: Dict,
|
|
249
|
+
cli_cmd: Optional[str],
|
|
250
|
+
env: Dict[str, str],
|
|
251
|
+
) -> Tuple[Optional[LLMBackend], List[str]]:
|
|
252
|
+
"""Pick the backend for this run and collect anything the user should know.
|
|
253
|
+
|
|
254
|
+
Precedence, highest first: --llm-cmd, ADR_KIT_LLM_CMD, judge.backend. The
|
|
255
|
+
first two are operator-controlled and therefore unrestricted; the third is
|
|
256
|
+
a key looked up in the code-side BACKENDS table and can introduce nothing.
|
|
257
|
+
|
|
258
|
+
Warnings are returned rather than printed so --show-config can render them
|
|
259
|
+
without a judging run, and so the caller controls ordering.
|
|
260
|
+
|
|
261
|
+
Both entry points resolve from `judge.*`: the backend is which model the
|
|
262
|
+
project talks to, not which tool is asking, and a parallel `suggest.backend`
|
|
263
|
+
would be a second place for the same answer to live.
|
|
264
|
+
"""
|
|
265
|
+
# Repo-tracked command and model keys are refused at config validation
|
|
266
|
+
# (adr_config.REMOVED_KEYS, ADR-036), so a validated cfg cannot carry one.
|
|
267
|
+
warnings: List[str] = []
|
|
268
|
+
|
|
269
|
+
if cli_cmd:
|
|
270
|
+
return SubprocessBackend(_split_cmd(cli_cmd), source="flag"), warnings
|
|
271
|
+
if env.get("ADR_KIT_LLM_CMD"):
|
|
272
|
+
return (
|
|
273
|
+
SubprocessBackend(_split_cmd(env["ADR_KIT_LLM_CMD"]), source="env"),
|
|
274
|
+
warnings,
|
|
275
|
+
)
|
|
276
|
+
|
|
277
|
+
name = str(judge_cfg.get("backend", DEFAULT_BACKEND))
|
|
278
|
+
factory = BACKENDS.get(name)
|
|
279
|
+
if factory is None:
|
|
280
|
+
if name in ("openrouter", "ollama", "openai-compatible"):
|
|
281
|
+
# Retired names get the precise sentence, not a generic enum error:
|
|
282
|
+
# a project that selected one of these made a valid choice once,
|
|
283
|
+
# and deserves to read what replaced it (ADR-036).
|
|
284
|
+
warnings.append(
|
|
285
|
+
f"judge.backend={name!r} was retired by ADR-036: the judge runs "
|
|
286
|
+
f"on the host client's own model. Remove the key to use the "
|
|
287
|
+
f"host backend, or use ADR_KIT_LLM_CMD / --llm-cmd for an "
|
|
288
|
+
f"operator-controlled override. The LLM pass will not run."
|
|
289
|
+
)
|
|
290
|
+
else:
|
|
291
|
+
warnings.append(
|
|
292
|
+
f"judge.backend={name!r} is not one of {list(BACKEND_NAMES)}; "
|
|
293
|
+
f"the LLM pass will not run."
|
|
294
|
+
)
|
|
295
|
+
return None, warnings
|
|
296
|
+
return factory(judge_cfg, local_cfg, warnings), warnings
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
def find_credential_keys(config: object, path: str = "$") -> List[str]:
|
|
300
|
+
"""Return dotted paths of every credential-shaped key in a config document."""
|
|
301
|
+
found: List[str] = []
|
|
302
|
+
if isinstance(config, dict):
|
|
303
|
+
for key, value in config.items():
|
|
304
|
+
child = f"{path}.{key}"
|
|
305
|
+
if isinstance(key, str) and _CREDENTIAL_KEY_RE.match(key.replace("-", "_")):
|
|
306
|
+
found.append(child)
|
|
307
|
+
found.extend(find_credential_keys(value, child))
|
|
308
|
+
elif isinstance(config, list):
|
|
309
|
+
for index, item in enumerate(config):
|
|
310
|
+
found.extend(find_credential_keys(item, f"{path}[{index}]"))
|
|
311
|
+
return found
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
def credential_refusal_message(path, offenders: List[str]) -> str:
|
|
315
|
+
"""The sentence a published credential earns, shared by both entry points.
|
|
316
|
+
|
|
317
|
+
The message has to be identical wherever it is raised: a user who fixes
|
|
318
|
+
the file because adr-judge told them to must not meet a differently-worded
|
|
319
|
+
version of the same problem from adr-suggest a second later. No backend
|
|
320
|
+
needs a credential any more (ADR-036), which makes a key in this file
|
|
321
|
+
doubly wrong: published, and useless.
|
|
322
|
+
"""
|
|
323
|
+
return (
|
|
324
|
+
f"{path}: refusing to read a credential from configuration "
|
|
325
|
+
f"({', '.join(offenders)}). This file is committed, so a key "
|
|
326
|
+
f"written here is a published key -- and no adr-kit backend takes "
|
|
327
|
+
f"one (ADR-036): the judge runs through the host client's own CLI, "
|
|
328
|
+
f"which carries its own authentication. Delete that key from the "
|
|
329
|
+
f"file BY HAND; no adr-kit command can do it for you, because every "
|
|
330
|
+
f"entry point (including --set-backend) refuses to load the file "
|
|
331
|
+
f"while the key is in it. Then rotate the key: it is already in "
|
|
332
|
+
f"your git history."
|
|
333
|
+
)
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
"""Enable the LLM judge on existing ADRs, opt-out style.
|
|
2
|
+
|
|
3
|
+
`llm_judge` defaults to TRUE as of TASK-74, so an Enforcement block that says
|
|
4
|
+
nothing about it opts in. Existing ADRs are the problem this module solves:
|
|
5
|
+
they were authored under the old default and carry an explicit
|
|
6
|
+
``"llm_judge": false`` that is indistinguishable from a deliberate refusal.
|
|
7
|
+
|
|
8
|
+
The distinction is a reason. A bare ``false`` is treated as a leftover and
|
|
9
|
+
proposed for enabling; a ``false`` with ``llm_judge_reason`` is a decision
|
|
10
|
+
somebody made on purpose and is left alone, on this run and every later one.
|
|
11
|
+
That is the whole memory mechanism -- it lives in the ADR, not in a state file
|
|
12
|
+
that a fresh clone would lose.
|
|
13
|
+
|
|
14
|
+
The module is deterministic and does no prompting. The interactive part
|
|
15
|
+
belongs to the upgrade skill, which shows the user each Decision and its
|
|
16
|
+
current block and then calls this code with explicit opt-outs. Same split as
|
|
17
|
+
ADR-011: a deterministic engine, a human-gated conversation on top.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import json
|
|
23
|
+
import re
|
|
24
|
+
import sys
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Dict, List, Optional, Sequence, Tuple
|
|
27
|
+
|
|
28
|
+
ENFORCEMENT_FENCE_RE = re.compile(
|
|
29
|
+
r"(^##\s+Enforcement\s*$\n+.*?```json\s*\n)(.*?)(\n```)",
|
|
30
|
+
re.IGNORECASE | re.MULTILINE | re.DOTALL,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
NO_CODE_SURFACE_REASON = (
|
|
34
|
+
"no code surface: this decision governs process or documentation, "
|
|
35
|
+
"so there is no diff for a model to judge it against"
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
# What a scan can conclude about one ADR.
|
|
39
|
+
STATE_ENABLED = "enabled" # llm_judge true or absent -- already opted in
|
|
40
|
+
STATE_LEGACY_OFF = "legacy-off" # bare false: propose enabling
|
|
41
|
+
STATE_OPTED_OUT = "opted-out" # false + reason: remembered refusal
|
|
42
|
+
STATE_NO_BLOCK = "no-enforcement-block"
|
|
43
|
+
STATE_UNPARSEABLE = "unparseable-enforcement-block"
|
|
44
|
+
STATE_NOT_ACCEPTED = "not-accepted"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _adr_id(path: Path) -> str:
|
|
48
|
+
match = re.match(r"(?i)(ADR-\d{1,4})", path.name)
|
|
49
|
+
return match.group(1).upper() if match else path.stem
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _status_word(text: str) -> Optional[str]:
|
|
53
|
+
"""Delegate to the one cross-tool status reader.
|
|
54
|
+
|
|
55
|
+
Writing a second status heuristic here would be a quiet way to disagree
|
|
56
|
+
with the judge about which ADRs are Accepted -- and this module decides
|
|
57
|
+
which ADRs the judge will be asked to enforce. One reader, one answer.
|
|
58
|
+
"""
|
|
59
|
+
import importlib.machinery
|
|
60
|
+
import importlib.util
|
|
61
|
+
|
|
62
|
+
here = Path(__file__).resolve().parent
|
|
63
|
+
|
|
64
|
+
def load(name: str):
|
|
65
|
+
cached = sys.modules.get(name)
|
|
66
|
+
if cached is not None:
|
|
67
|
+
return cached
|
|
68
|
+
loader = importlib.machinery.SourceFileLoader(name, str(here / f"{name}.py"))
|
|
69
|
+
spec = importlib.util.spec_from_loader(name, loader)
|
|
70
|
+
module = importlib.util.module_from_spec(spec)
|
|
71
|
+
sys.modules[name] = module
|
|
72
|
+
loader.exec_module(module)
|
|
73
|
+
return module
|
|
74
|
+
|
|
75
|
+
# Dependency order, same as bin/adr-migrate: adr_catalog imports both.
|
|
76
|
+
load("adr_format")
|
|
77
|
+
load("adr_schema")
|
|
78
|
+
return load("adr_catalog").adr_status(text)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def read_enforcement(text: str) -> Tuple[Optional[Dict], Optional[str]]:
|
|
82
|
+
"""Return (block, error). Both None-able: no block is not an error."""
|
|
83
|
+
match = ENFORCEMENT_FENCE_RE.search(text)
|
|
84
|
+
if not match:
|
|
85
|
+
return None, None
|
|
86
|
+
try:
|
|
87
|
+
data = json.loads(match.group(2))
|
|
88
|
+
except json.JSONDecodeError as exc:
|
|
89
|
+
return None, f"{exc.msg} at line {exc.lineno}"
|
|
90
|
+
if not isinstance(data, dict):
|
|
91
|
+
return None, "Enforcement block is not a JSON object"
|
|
92
|
+
return data, None
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def rule_count(block: Dict) -> int:
|
|
96
|
+
return sum(
|
|
97
|
+
len(block.get(kind, []) or [])
|
|
98
|
+
for kind in ("forbid_pattern", "forbid_import", "require_pattern")
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def has_unbounded_scope(block: Dict) -> bool:
|
|
103
|
+
"""True when nothing narrows this ADR, so judging it costs a call per commit."""
|
|
104
|
+
saw_rule = False
|
|
105
|
+
for kind in ("forbid_pattern", "forbid_import", "require_pattern"):
|
|
106
|
+
for rule in block.get(kind, []) or []:
|
|
107
|
+
saw_rule = True
|
|
108
|
+
if not (rule or {}).get("path_glob"):
|
|
109
|
+
return True
|
|
110
|
+
return not saw_rule
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def classify(path: Path) -> Dict:
|
|
114
|
+
"""Read one ADR and decide what the upgrade should propose for it."""
|
|
115
|
+
text = path.read_text(encoding="utf-8", errors="replace")
|
|
116
|
+
row: Dict = {
|
|
117
|
+
"adr": _adr_id(path),
|
|
118
|
+
"path": str(path),
|
|
119
|
+
"status": _status_word(text),
|
|
120
|
+
"state": STATE_NO_BLOCK,
|
|
121
|
+
"rules": 0,
|
|
122
|
+
"unbounded_scope": False,
|
|
123
|
+
"reason": None,
|
|
124
|
+
"proposal": "none",
|
|
125
|
+
}
|
|
126
|
+
if (row["status"] or "").lower() != "accepted":
|
|
127
|
+
row["state"] = STATE_NOT_ACCEPTED
|
|
128
|
+
return row
|
|
129
|
+
block, error = read_enforcement(text)
|
|
130
|
+
if error is not None:
|
|
131
|
+
row["state"] = STATE_UNPARSEABLE
|
|
132
|
+
row["reason"] = error
|
|
133
|
+
return row
|
|
134
|
+
if block is None:
|
|
135
|
+
return row
|
|
136
|
+
row["rules"] = rule_count(block)
|
|
137
|
+
row["unbounded_scope"] = has_unbounded_scope(block)
|
|
138
|
+
reason = block.get("llm_judge_reason")
|
|
139
|
+
if block.get("llm_judge", True):
|
|
140
|
+
row["state"] = STATE_ENABLED
|
|
141
|
+
return row
|
|
142
|
+
if isinstance(reason, str) and reason.strip():
|
|
143
|
+
row["state"] = STATE_OPTED_OUT
|
|
144
|
+
row["reason"] = reason
|
|
145
|
+
return row
|
|
146
|
+
row["state"] = STATE_LEGACY_OFF
|
|
147
|
+
# A rule-less block has no boundary, so enabling it means a call on every
|
|
148
|
+
# commit. Say so in the proposal rather than in a footnote nobody reads.
|
|
149
|
+
row["proposal"] = "mark-no-code-surface" if row["rules"] == 0 else "enable"
|
|
150
|
+
return row
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def scan(adr_dir: Path) -> List[Dict]:
|
|
154
|
+
files = sorted(
|
|
155
|
+
(p for p in adr_dir.glob("ADR-*.md") if re.match(r"(?i)ADR-\d", p.name)),
|
|
156
|
+
key=lambda p: p.name.lower(),
|
|
157
|
+
)
|
|
158
|
+
return [classify(p) for p in files]
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _rewrite_block(text: str, mutate) -> Optional[str]:
|
|
162
|
+
"""Apply mutate(block) to the Enforcement JSON, preserving the surroundings."""
|
|
163
|
+
match = ENFORCEMENT_FENCE_RE.search(text)
|
|
164
|
+
if not match:
|
|
165
|
+
return None
|
|
166
|
+
try:
|
|
167
|
+
block = json.loads(match.group(2))
|
|
168
|
+
except json.JSONDecodeError:
|
|
169
|
+
return None
|
|
170
|
+
if not isinstance(block, dict):
|
|
171
|
+
return None
|
|
172
|
+
changed = mutate(block)
|
|
173
|
+
if not changed:
|
|
174
|
+
return None
|
|
175
|
+
body = json.dumps(block, indent=2, ensure_ascii=False)
|
|
176
|
+
return text[: match.start(2)] + body + text[match.end(2) :]
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def enable(path: Path) -> bool:
|
|
180
|
+
"""Drop an unreasoned llm_judge:false so the true default applies."""
|
|
181
|
+
|
|
182
|
+
def mutate(block: Dict) -> bool:
|
|
183
|
+
if block.get("llm_judge", True):
|
|
184
|
+
return False
|
|
185
|
+
if isinstance(block.get("llm_judge_reason"), str) and block["llm_judge_reason"].strip():
|
|
186
|
+
return False
|
|
187
|
+
# Remove rather than write true: absent means the default, and the
|
|
188
|
+
# default is what this change is about. One fewer thing to re-flip if
|
|
189
|
+
# the default ever moves again.
|
|
190
|
+
block.pop("llm_judge", None)
|
|
191
|
+
return True
|
|
192
|
+
|
|
193
|
+
new = _rewrite_block(path.read_text(encoding="utf-8"), mutate)
|
|
194
|
+
if new is None:
|
|
195
|
+
return False
|
|
196
|
+
path.write_text(new, encoding="utf-8")
|
|
197
|
+
return True
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def opt_out(path: Path, reason: str) -> bool:
|
|
201
|
+
"""Record a deliberate refusal that later upgrades must respect."""
|
|
202
|
+
reason = (reason or "").strip()
|
|
203
|
+
if not reason:
|
|
204
|
+
raise ValueError("an opt-out needs a reason; a bare false is not remembered")
|
|
205
|
+
|
|
206
|
+
def mutate(block: Dict) -> bool:
|
|
207
|
+
if block.get("llm_judge") is False and block.get("llm_judge_reason") == reason:
|
|
208
|
+
return False
|
|
209
|
+
block["llm_judge"] = False
|
|
210
|
+
block["llm_judge_reason"] = reason
|
|
211
|
+
return True
|
|
212
|
+
|
|
213
|
+
new = _rewrite_block(path.read_text(encoding="utf-8"), mutate)
|
|
214
|
+
if new is None:
|
|
215
|
+
return False
|
|
216
|
+
path.write_text(new, encoding="utf-8")
|
|
217
|
+
return True
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def apply(
|
|
221
|
+
adr_dir: Path,
|
|
222
|
+
*,
|
|
223
|
+
opt_out_ids: Sequence[str] = (),
|
|
224
|
+
no_code_surface_ids: Sequence[str] = (),
|
|
225
|
+
force_enable_ids: Sequence[str] = (),
|
|
226
|
+
opt_out_reason: str = "",
|
|
227
|
+
dry_run: bool = False,
|
|
228
|
+
) -> Dict:
|
|
229
|
+
"""Enable every eligible ADR except the ones the user declined.
|
|
230
|
+
|
|
231
|
+
Opt-out is the default posture: an ADR the caller does not name gets the
|
|
232
|
+
LLM pass. Naming an ADR in ``opt_out_ids`` or ``no_code_surface_ids``
|
|
233
|
+
writes a reasoned false instead, which later runs leave alone.
|
|
234
|
+
|
|
235
|
+
One exception to plain opt-out, and it is the reason this function is not
|
|
236
|
+
a one-liner: an Enforcement block with NO rules has no scope to narrow
|
|
237
|
+
with, so enabling it buys a model call on every commit for a decision that
|
|
238
|
+
may have no code surface at all. Those are marked no-code-surface instead.
|
|
239
|
+
``force_enable_ids`` overrides that per ADR, for the case where the
|
|
240
|
+
decision really is code-governing and the author simply has not written
|
|
241
|
+
the rules yet -- and then the cost is what the user asked for.
|
|
242
|
+
"""
|
|
243
|
+
declined = {i.upper() for i in opt_out_ids}
|
|
244
|
+
no_surface = {i.upper() for i in no_code_surface_ids}
|
|
245
|
+
overlap = declined & no_surface
|
|
246
|
+
if overlap:
|
|
247
|
+
raise ValueError(
|
|
248
|
+
f"{sorted(overlap)} named as both a plain opt-out and no-code-surface"
|
|
249
|
+
)
|
|
250
|
+
if declined and not opt_out_reason.strip():
|
|
251
|
+
raise ValueError("--except needs --reason so the opt-out is self-explaining")
|
|
252
|
+
|
|
253
|
+
forced = {i.upper() for i in force_enable_ids}
|
|
254
|
+
rows = scan(adr_dir)
|
|
255
|
+
result: Dict = {"enabled": [], "opted_out": [], "unchanged": [], "dry_run": dry_run}
|
|
256
|
+
# The set the judge will actually evaluate once this migration lands. The
|
|
257
|
+
# per-row lists above only show what THIS run changes, and that framing has
|
|
258
|
+
# misled an operator before: a dry-run reading "6 enabled, 0 unbounded" on a
|
|
259
|
+
# repository that already carried 58 enabled unscoped ADRs looks cost-free,
|
|
260
|
+
# while the post-migration pass makes one isolated model call per unscoped
|
|
261
|
+
# ADR on every commit. The totals answer the question the operator is
|
|
262
|
+
# actually asking: what will judging cost after I accept this?
|
|
263
|
+
judged_after = 0
|
|
264
|
+
unbounded_after = 0
|
|
265
|
+
|
|
266
|
+
def count_judged(row: Dict) -> None:
|
|
267
|
+
nonlocal judged_after, unbounded_after
|
|
268
|
+
judged_after += 1
|
|
269
|
+
if row["unbounded_scope"]:
|
|
270
|
+
unbounded_after += 1
|
|
271
|
+
|
|
272
|
+
for row in rows:
|
|
273
|
+
adr, path = row["adr"], Path(row["path"])
|
|
274
|
+
if (
|
|
275
|
+
row["proposal"] == "mark-no-code-surface"
|
|
276
|
+
and adr not in forced
|
|
277
|
+
and adr not in declined
|
|
278
|
+
):
|
|
279
|
+
if not dry_run:
|
|
280
|
+
opt_out(path, NO_CODE_SURFACE_REASON)
|
|
281
|
+
result["opted_out"].append(
|
|
282
|
+
{"adr": adr, "reason": NO_CODE_SURFACE_REASON, "proposed": True}
|
|
283
|
+
)
|
|
284
|
+
continue
|
|
285
|
+
if adr in no_surface:
|
|
286
|
+
if not dry_run:
|
|
287
|
+
opt_out(path, NO_CODE_SURFACE_REASON)
|
|
288
|
+
result["opted_out"].append({"adr": adr, "reason": NO_CODE_SURFACE_REASON})
|
|
289
|
+
continue
|
|
290
|
+
if adr in declined:
|
|
291
|
+
if not dry_run:
|
|
292
|
+
opt_out(path, opt_out_reason.strip())
|
|
293
|
+
result["opted_out"].append({"adr": adr, "reason": opt_out_reason.strip()})
|
|
294
|
+
continue
|
|
295
|
+
if row["state"] == STATE_LEGACY_OFF:
|
|
296
|
+
if not dry_run:
|
|
297
|
+
enable(path)
|
|
298
|
+
result["enabled"].append(
|
|
299
|
+
{
|
|
300
|
+
"adr": adr,
|
|
301
|
+
"rules": row["rules"],
|
|
302
|
+
"unbounded_scope": row["unbounded_scope"],
|
|
303
|
+
}
|
|
304
|
+
)
|
|
305
|
+
count_judged(row)
|
|
306
|
+
continue
|
|
307
|
+
if row["state"] == STATE_ENABLED:
|
|
308
|
+
count_judged(row)
|
|
309
|
+
result["unchanged"].append({"adr": adr, "state": row["state"]})
|
|
310
|
+
result["summary"] = {
|
|
311
|
+
"judged_after": judged_after,
|
|
312
|
+
"unbounded_after": unbounded_after,
|
|
313
|
+
}
|
|
314
|
+
return result
|