@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.
Files changed (49) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +115 -39
  3. package/bin/adr-context +2 -1
  4. package/bin/adr-doctor +1 -1
  5. package/bin/adr-guardian +10 -1
  6. package/bin/adr-judge +12 -57
  7. package/bin/adr-settings +59 -8
  8. package/bin/adr-substance +15 -0
  9. package/bin/adr-suggest +8 -3
  10. package/bin/adr_config.py +33 -0
  11. package/bin/adr_doctor_checks.py +9 -3
  12. package/bin/adr_doctor_core.py +4 -4
  13. package/bin/adr_doctor_probes.py +100 -13
  14. package/bin/adr_llm.py +186 -3
  15. package/bin/adr_readiness.py +17 -1
  16. package/clients/workflows.json +10 -7
  17. package/hooks/adr_hook_core.py +176 -28
  18. package/instructions/ADR-guide.md +1 -1
  19. package/omp/extension.ts +365 -0
  20. package/opencode/plugin.ts +95 -14
  21. package/package.json +7 -1
  22. package/schemas/adr-kit-config.schema.json +7 -2
  23. package/scripts/client_generation.py +2 -5
  24. package/scripts/client_generation_artifacts.py +16 -2
  25. package/scripts/client_generation_model.py +9 -0
  26. package/scripts/release_phases.py +7 -7
  27. package/skills/adr/SKILL.md +2 -0
  28. package/skills/audit/SKILL.md +2 -0
  29. package/skills/context/SKILL.md +2 -0
  30. package/skills/grill/SKILL.md +2 -0
  31. package/skills/guardian/SKILL.md +8 -4
  32. package/skills/init/SKILL.md +34 -11
  33. package/skills/install-hooks/SKILL.md +12 -9
  34. package/skills/judge/SKILL.md +8 -3
  35. package/skills/lint/SKILL.md +4 -1
  36. package/skills/migrate/SKILL.md +2 -0
  37. package/skills/related/SKILL.md +4 -1
  38. package/skills/retire/SKILL.md +2 -0
  39. package/skills/review/SKILL.md +4 -1
  40. package/skills/settings/SKILL.md +2 -0
  41. package/skills/setup/SKILL.md +4 -1
  42. package/skills/supersede/SKILL.md +4 -1
  43. package/skills/upgrade/SKILL.md +24 -3
  44. package/templates/adr-kit-guide.md +3 -3
  45. package/templates/cc-settings/guardian-hook-entry.json +2 -2
  46. package/templates/githooks/pre-commit +37 -9
  47. package/templates/github-workflows/adr-index-check.yml +1 -1
  48. package/templates/github-workflows/adr-judge.yml +1 -1
  49. 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 120 (or "
661
- "suggest.llm_timeout_seconds / judge.llm_timeout_seconds in .adr-kit.json).",
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
- cfg = load_config(config_path)
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
@@ -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
- return resolved_command, targets
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
  )
@@ -183,9 +183,9 @@ def gate_findings_from_lint(lint_payload: Dict) -> List[Dict]:
183
183
  return findings
184
184
 
185
185
 
186
- def run_audit(repo_root: Path, audit_script: Path) -> Dict:
186
+ def run_discover(repo_root: Path, discover_script: Path) -> Dict:
187
187
  result = subprocess.run(
188
- [sys.executable, str(audit_script), "--root", str(repo_root)],
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
- audit_script = bin_dir / "adr-discover"
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 = run_audit(repo_root, audit_script)
280
+ audit_payload = run_discover(repo_root, discover_script)
281
281
  audit_payload["reason"] = "material_drift"
282
282
 
283
283
  return {
@@ -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 "trust" in output or "review" in output:
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=f"bounded native plugin-list probe returned {status}",
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, plugin_root: Path) -> dict:
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
- [sys.executable, str(plugin_root / "bin" / "adr-mcp")],
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.append(_mcp_deep(root, plugin_root))
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, ADR_KIT_LLM_CMD, judge.backend. The
315
- first two are operator-controlled and therefore unrestricted; the third is
316
- a key looked up in the code-side BACKENDS table and can introduce nothing.
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
@@ -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": next_commands.get(classification),
449
+ "next_command": next_command,
434
450
  }
435
451
 
436
452