@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.
Files changed (129) hide show
  1. package/.claude-plugin/plugin.json +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +850 -0
  4. package/bin/adr +1552 -0
  5. package/bin/adr-audit +454 -0
  6. package/bin/adr-context +584 -0
  7. package/bin/adr-discover +546 -0
  8. package/bin/adr-doctor +166 -0
  9. package/bin/adr-generate-scripts +421 -0
  10. package/bin/adr-grill-signal +131 -0
  11. package/bin/adr-guardian +1263 -0
  12. package/bin/adr-index +199 -0
  13. package/bin/adr-judge +2832 -0
  14. package/bin/adr-judge-precommit +87 -0
  15. package/bin/adr-lint +2087 -0
  16. package/bin/adr-mcp +1093 -0
  17. package/bin/adr-migrate +644 -0
  18. package/bin/adr-quality +275 -0
  19. package/bin/adr-readiness +211 -0
  20. package/bin/adr-readiness-ci +111 -0
  21. package/bin/adr-related +401 -0
  22. package/bin/adr-renumber +254 -0
  23. package/bin/adr-retire +467 -0
  24. package/bin/adr-settings +399 -0
  25. package/bin/adr-status +797 -0
  26. package/bin/adr-suggest +803 -0
  27. package/bin/adr-watch +674 -0
  28. package/bin/adr_catalog.py +536 -0
  29. package/bin/adr_config.py +280 -0
  30. package/bin/adr_doctor_checks.py +407 -0
  31. package/bin/adr_doctor_core.py +342 -0
  32. package/bin/adr_doctor_models.py +186 -0
  33. package/bin/adr_doctor_probes.py +216 -0
  34. package/bin/adr_format.py +786 -0
  35. package/bin/adr_grill_signal.py +123 -0
  36. package/bin/adr_guardian_queue.py +218 -0
  37. package/bin/adr_history_scan.py +278 -0
  38. package/bin/adr_index_core.py +443 -0
  39. package/bin/adr_llm.py +333 -0
  40. package/bin/adr_llm_judge_migration.py +314 -0
  41. package/bin/adr_quality_core.py +674 -0
  42. package/bin/adr_query.py +678 -0
  43. package/bin/adr_readiness.py +442 -0
  44. package/bin/adr_readiness_ci.py +123 -0
  45. package/bin/adr_regex.py +165 -0
  46. package/bin/adr_regex_worker.py +30 -0
  47. package/bin/adr_retrieval_health.py +385 -0
  48. package/bin/adr_schema.py +448 -0
  49. package/bin/adr_state.py +172 -0
  50. package/bin/bump-version +71 -0
  51. package/clients/workflows.json +229 -0
  52. package/hooks/__init__.py +1 -0
  53. package/hooks/adapters/__init__.py +13 -0
  54. package/hooks/adapters/claude.py +27 -0
  55. package/hooks/adapters/codex.py +26 -0
  56. package/hooks/adapters/copilot.py +11 -0
  57. package/hooks/adr-hook.py +128 -0
  58. package/hooks/adr_hook_core.py +843 -0
  59. package/hooks/adr_pr_guard.py +367 -0
  60. package/instructions/ADR-guide.md +48 -0
  61. package/instructions/adr.coding.md +82 -0
  62. package/instructions/adr.review.md +182 -0
  63. package/opencode/plugin.ts +451 -0
  64. package/package.json +41 -0
  65. package/schemas/adr-context-probes.schema.json +56 -0
  66. package/schemas/adr-enforcement.schema.json +57 -0
  67. package/schemas/adr-frontmatter.schema.json +144 -0
  68. package/schemas/adr-index.schema.json +276 -0
  69. package/schemas/adr-kit-config.schema.json +371 -0
  70. package/schemas/adr-readiness.schema.json +41 -0
  71. package/schemas/client-capabilities.schema.json +503 -0
  72. package/schemas/client-certification.schema.json +101 -0
  73. package/schemas/doctor-output.schema.json +92 -0
  74. package/schemas/marketplace.json.schema.json +70 -0
  75. package/schemas/plugin.json.schema.json +67 -0
  76. package/scripts/adr_settings.py +239 -0
  77. package/scripts/benchmark-adr-grilling.py +323 -0
  78. package/scripts/benchmark-client-generation.py +178 -0
  79. package/scripts/build-client-adapters.py +139 -0
  80. package/scripts/bump-version.py +304 -0
  81. package/scripts/check-branch-sync.py +243 -0
  82. package/scripts/check-release-version.py +81 -0
  83. package/scripts/client_certification.py +153 -0
  84. package/scripts/client_evidence.py +280 -0
  85. package/scripts/client_generation.py +288 -0
  86. package/scripts/client_generation_artifacts.py +351 -0
  87. package/scripts/client_generation_model.py +173 -0
  88. package/scripts/client_generation_state.py +260 -0
  89. package/scripts/client_support_matrix.py +360 -0
  90. package/scripts/install-agent-envs.py +300 -0
  91. package/scripts/probe-client-events.py +183 -0
  92. package/scripts/project_setup.py +379 -0
  93. package/scripts/refresh-otgw-corpus.py +219 -0
  94. package/scripts/settings.py +81 -0
  95. package/scripts/setup-project.py +205 -0
  96. package/scripts/sync-agent-plugins.py +17 -0
  97. package/scripts/version_sites.py +377 -0
  98. package/skills/adr/SKILL.md +780 -0
  99. package/skills/audit/SKILL.md +103 -0
  100. package/skills/context/SKILL.md +77 -0
  101. package/skills/grill/SKILL.md +84 -0
  102. package/skills/grill/agents/openai.yaml +4 -0
  103. package/skills/guardian/SKILL.md +316 -0
  104. package/skills/init/SKILL.md +499 -0
  105. package/skills/install-hooks/SKILL.md +154 -0
  106. package/skills/judge/SKILL.md +168 -0
  107. package/skills/lint/SKILL.md +321 -0
  108. package/skills/migrate/SKILL.md +313 -0
  109. package/skills/related/SKILL.md +62 -0
  110. package/skills/retire/SKILL.md +41 -0
  111. package/skills/review/SKILL.md +167 -0
  112. package/skills/settings/SKILL.md +73 -0
  113. package/skills/setup/SKILL.md +128 -0
  114. package/skills/supersede/SKILL.md +136 -0
  115. package/skills/upgrade/SKILL.md +273 -0
  116. package/templates/adr-kit-guide.md +354 -0
  117. package/templates/adr-template.canonical.md +115 -0
  118. package/templates/adr-template.madr.md +131 -0
  119. package/templates/adr-template.md +131 -0
  120. package/templates/adr-template.nygard.md +111 -0
  121. package/templates/cc-settings/guardian-hook-entry.json +9 -0
  122. package/templates/githooks/pre-commit +337 -0
  123. package/templates/github-workflows/adr-audit.yml +58 -0
  124. package/templates/github-workflows/adr-guardian-audit.yml +133 -0
  125. package/templates/github-workflows/adr-index-check.yml +30 -0
  126. package/templates/github-workflows/adr-judge.yml +31 -0
  127. package/templates/github-workflows/adr-readiness.yml +18 -0
  128. package/templates/validate_adr_template.py +38 -0
  129. 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