@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
@@ -0,0 +1,280 @@
1
+ """Shared, stdlib-only validation for adr-kit project configuration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from pathlib import Path
8
+ from typing import Any, Dict, List
9
+
10
+
11
+ class ConfigValidationError(ValueError):
12
+ """Raised when .adr-kit.json is malformed or violates its schema."""
13
+
14
+
15
+ # Keys the schema once declared and no code ever read. Removing them outright
16
+ # would fail every existing config that sets one, so they are accepted and
17
+ # ignored instead: the value never took effect, and breaking the file over a
18
+ # setting that was already inert would be a worse trade than a warning.
19
+ # A caller that wants to surface them uses retired_keys_present().
20
+ RETIRED_KEYS: Dict[str, str] = {
21
+ "$.judge.llm_timeout_ms": (
22
+ "never read; judge.llm_timeout_seconds is the timeout that applies"
23
+ ),
24
+ "$.judge.pre_push_timeout_ms": (
25
+ "never read; adr-kit ships no pre-push hook for it to bound"
26
+ ),
27
+ "$.policy.regex_compile_checks": (
28
+ "never read; adr-lint always compiles Enforcement patterns"
29
+ ),
30
+ "$.policy.pattern_warnings": (
31
+ "never read; adr-lint always emits anti-pattern advisories"
32
+ ),
33
+ "$.context.weights": (
34
+ "never read; the index-first scorer replaced weighted signals in v0.40.0"
35
+ ),
36
+ "$.context.weights.exact_keyword": "part of the retired context.weights block",
37
+ "$.context.weights.domain_tag": "part of the retired context.weights block",
38
+ "$.context.weights.related_decisions": (
39
+ "part of the retired context.weights block"
40
+ ),
41
+ "$.context.weights.acceptance_status": (
42
+ "part of the retired context.weights block"
43
+ ),
44
+ "$.context.weights.recency": "part of the retired context.weights block",
45
+ }
46
+
47
+ # Keys that DID something and no longer do (ADR-036). Unlike RETIRED_KEYS,
48
+ # these are refused rather than ignored: a config naming one made a real
49
+ # choice once - a backend, a model, a command - and silently dropping that
50
+ # choice would be the exact drift the kit exists to prevent. Each entry is
51
+ # the sentence "unknown property" cannot say: what replaced the key.
52
+ REMOVED_KEYS: Dict[str, str] = {
53
+ "$.judge.openrouter_model": (
54
+ "the openrouter backend was retired by ADR-036; the judge runs on the "
55
+ "host client's own model. Remove the key; operators can override per "
56
+ "run with ADR_KIT_LLM_CMD / --llm-cmd."
57
+ ),
58
+ "$.judge.ollama_model": (
59
+ "the ollama backend was retired by ADR-036; the judge runs on the "
60
+ "host client's own model. Remove the key; operators can override per "
61
+ "run with ADR_KIT_LLM_CMD / --llm-cmd."
62
+ ),
63
+ "$.judge.openai_model": (
64
+ "the openai-compatible backend was retired by ADR-036; the judge runs "
65
+ "on the host client's own model. Remove the key; operators can "
66
+ "override per run with ADR_KIT_LLM_CMD / --llm-cmd."
67
+ ),
68
+ "$.judge.llm_cmd": (
69
+ "ignored since ADR-017 and removed by ADR-036: repository-tracked "
70
+ "configuration may never supply a command. Remove the key; operators "
71
+ "use ADR_KIT_LLM_CMD / --llm-cmd."
72
+ ),
73
+ "$.judge.llm_model": (
74
+ "ignored since ADR-017 and removed by ADR-036: the host backend "
75
+ "passes no model flag, so each CLI resolves the model its own user "
76
+ "configured. Remove the key."
77
+ ),
78
+ "$.judge.llm_default": (
79
+ "removed by ADR-036; judge.llm_enabled is the per-commit switch. "
80
+ "Remove the key."
81
+ ),
82
+ "$.suggest.llm_cmd": (
83
+ "ignored since ADR-017 and removed by ADR-036: repository-tracked "
84
+ "configuration may never supply a command. Remove the key; operators "
85
+ "use ADR_KIT_LLM_CMD / --llm-cmd."
86
+ ),
87
+ "$.suggest.llm_model": (
88
+ "ignored since ADR-017 and removed by ADR-036: adr-suggest resolves "
89
+ "the same host backend as the judge. Remove the key."
90
+ ),
91
+ }
92
+
93
+
94
+ def retired_keys_present(config: Any) -> List[str]:
95
+ """Return the dotted paths of retired keys this config still sets.
96
+
97
+ Callers print these as a warning. The values are inert either way.
98
+ """
99
+ found: List[str] = []
100
+
101
+ def walk(value: Any, path: str) -> None:
102
+ if not isinstance(value, dict):
103
+ return
104
+ for key, item in value.items():
105
+ child = _path(path, str(key))
106
+ if child in RETIRED_KEYS:
107
+ found.append(child)
108
+ continue
109
+ walk(item, child)
110
+
111
+ walk(config, "$")
112
+ return sorted(found)
113
+
114
+
115
+ def _type_matches(value: Any, expected: str) -> bool:
116
+ if expected == "object":
117
+ return isinstance(value, dict)
118
+ if expected == "array":
119
+ return isinstance(value, list)
120
+ if expected == "string":
121
+ return isinstance(value, str)
122
+ if expected == "boolean":
123
+ return isinstance(value, bool)
124
+ if expected == "integer":
125
+ return isinstance(value, int) and not isinstance(value, bool)
126
+ if expected == "number":
127
+ return isinstance(value, (int, float)) and not isinstance(value, bool)
128
+ if expected == "null":
129
+ return value is None
130
+ return True
131
+
132
+
133
+ def _path(parent: str, key: str) -> str:
134
+ if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
135
+ return f"{parent}.{key}"
136
+ return f"{parent}[{json.dumps(key, ensure_ascii=False)}]"
137
+
138
+
139
+ def _validate(value: Any, schema: Dict[str, Any], path: str) -> List[str]:
140
+ issues: List[str] = []
141
+
142
+ if "oneOf" in schema:
143
+ matches = [
144
+ candidate
145
+ for candidate in schema["oneOf"]
146
+ if not _validate(value, candidate, path)
147
+ ]
148
+ if len(matches) != 1:
149
+ issues.append(f"{path}: must match exactly one allowed schema")
150
+ return issues
151
+
152
+ expected = schema.get("type")
153
+ if isinstance(expected, str) and not _type_matches(value, expected):
154
+ issues.append(f"{path}: expected {expected}, got {type(value).__name__}")
155
+ return issues
156
+
157
+ if "enum" in schema and value not in schema["enum"]:
158
+ issues.append(
159
+ f"{path}: must be one of {', '.join(repr(item) for item in schema['enum'])}"
160
+ )
161
+
162
+ if isinstance(value, str):
163
+ min_length = schema.get("minLength")
164
+ if isinstance(min_length, int) and len(value) < min_length:
165
+ issues.append(f"{path}: must contain at least {min_length} character(s)")
166
+ pattern = schema.get("pattern")
167
+ if isinstance(pattern, str) and re.search(pattern, value) is None:
168
+ issues.append(f"{path}: does not match required pattern {pattern!r}")
169
+
170
+ if isinstance(value, list):
171
+ min_items = schema.get("minItems")
172
+ if isinstance(min_items, int) and len(value) < min_items:
173
+ issues.append(f"{path}: must contain at least {min_items} item(s)")
174
+ item_schema = schema.get("items")
175
+ if isinstance(item_schema, dict):
176
+ for index, item in enumerate(value):
177
+ issues.extend(_validate(item, item_schema, f"{path}[{index}]"))
178
+
179
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
180
+ minimum = schema.get("minimum")
181
+ maximum = schema.get("maximum")
182
+ if isinstance(minimum, (int, float)) and value < minimum:
183
+ issues.append(f"{path}: must be >= {minimum}")
184
+ if isinstance(maximum, (int, float)) and value > maximum:
185
+ issues.append(f"{path}: must be <= {maximum}")
186
+
187
+ if isinstance(value, dict):
188
+ properties = schema.get("properties", {})
189
+ pattern_properties = schema.get("patternProperties", {})
190
+ required = schema.get("required", [])
191
+ for key in required:
192
+ if key not in value:
193
+ issues.append(f"{_path(path, key)}: required property is missing")
194
+ for key, item in value.items():
195
+ child_path = _path(path, str(key))
196
+ if key in properties:
197
+ issues.extend(_validate(item, properties[key], child_path))
198
+ continue
199
+ matching = [
200
+ child_schema
201
+ for pattern, child_schema in pattern_properties.items()
202
+ if re.search(pattern, str(key))
203
+ ]
204
+ if matching:
205
+ for child_schema in matching:
206
+ issues.extend(_validate(item, child_schema, child_path))
207
+ continue
208
+ if child_path in RETIRED_KEYS:
209
+ continue
210
+ if child_path in REMOVED_KEYS:
211
+ issues.append(f"{child_path}: {REMOVED_KEYS[child_path]}")
212
+ continue
213
+ additional = schema.get("additionalProperties", True)
214
+ if additional is False:
215
+ issues.append(f"{child_path}: unknown property")
216
+ elif isinstance(additional, dict):
217
+ issues.extend(_validate(item, additional, child_path))
218
+
219
+ return issues
220
+
221
+
222
+ def validate_project_config(config: Any, schema_path: Path) -> Dict[str, Any]:
223
+ """Validate config against the checked-in schema and return it as a dict."""
224
+ try:
225
+ schema = json.loads(schema_path.read_text(encoding="utf-8"))
226
+ except (OSError, json.JSONDecodeError) as exc:
227
+ raise ConfigValidationError(
228
+ f"cannot load configuration schema {schema_path}: {exc}"
229
+ ) from exc
230
+ issues = _validate(config, schema, "$")
231
+ if issues:
232
+ raise ConfigValidationError("; ".join(issues))
233
+ return config
234
+
235
+
236
+ def load_project_config(path: Path, schema_path: Path) -> Dict[str, Any]:
237
+ """Read and validate one .adr-kit.json file; missing files mean defaults."""
238
+ if not path.exists():
239
+ return {}
240
+ try:
241
+ config = json.loads(path.read_text(encoding="utf-8"))
242
+ except OSError as exc:
243
+ raise ConfigValidationError(f"cannot read {path}: {exc}") from exc
244
+ except json.JSONDecodeError as exc:
245
+ raise ConfigValidationError(
246
+ f"{path}: invalid JSON ({exc.msg} at line {exc.lineno})"
247
+ ) from exc
248
+ try:
249
+ return validate_project_config(config, schema_path)
250
+ except ConfigValidationError as exc:
251
+ raise ConfigValidationError(f"{path}: schema validation failed: {exc}") from exc
252
+
253
+
254
+ DEFAULT_CONFIG_SCHEMA = (
255
+ Path(__file__).resolve().parent.parent / "schemas" / "adr-kit-config.schema.json"
256
+ )
257
+
258
+
259
+ def load_validated_config(path: Path | None) -> Dict[str, Any]:
260
+ """Read and schema-validate .adr-kit.json against the shipped schema.
261
+
262
+ Callers that need their own error type catch ConfigValidationError and
263
+ re-raise. A missing path or file yields defaults.
264
+ """
265
+ if path is None:
266
+ return {}
267
+ return load_project_config(path, DEFAULT_CONFIG_SCHEMA)
268
+
269
+
270
+ def load_json_config(path: Path) -> Dict[str, Any]:
271
+ """Read a JSON config object tolerantly; anything unusable yields {}.
272
+
273
+ The fail-open reader used by the advisory hook entry points, where a broken
274
+ config must never interrupt an edit or a session start.
275
+ """
276
+ try:
277
+ data = json.loads(path.read_text(encoding="utf-8"))
278
+ except (OSError, json.JSONDecodeError):
279
+ return {}
280
+ return data if isinstance(data, dict) else {}
@@ -0,0 +1,407 @@
1
+ """Fast client checks, bounded deep probes, and enumerated safe repairs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import shutil
7
+ import sys
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from adr_doctor_models import check, client_root, generated_tree_owner
12
+ from adr_settings import (
13
+ SettingsError,
14
+ resolve_settings,
15
+ )
16
+ from clients.installer.contracts import CLIENT_IDS
17
+ from clients.installer.detection import detect_clients
18
+ # client_generation is deliberately NOT imported here. It is the generator's own
19
+ # source and is not mirrored into a client tree, so a module-scope import would
20
+ # kill bin/adr-doctor at import time in codex/ and copilot/ -- the same shape as
21
+ # the v0.44.1 outage. _generated_check imports it lazily, behind a check that a
22
+ # mirror never passes.
23
+ from project_setup import (
24
+ SetupError,
25
+ apply_changes,
26
+ collect_changes,
27
+ validate_markers,
28
+ )
29
+
30
+ HOOK_EVENTS = {
31
+ "claude": {
32
+ "SessionStart",
33
+ "UserPromptSubmit",
34
+ "PreToolUse",
35
+ "PostToolUse",
36
+ "SubagentStart",
37
+ "PreCompact",
38
+ },
39
+ "codex": {
40
+ "SessionStart",
41
+ "UserPromptSubmit",
42
+ "PreToolUse",
43
+ "PostToolUse",
44
+ "SubagentStart",
45
+ "PreCompact",
46
+ },
47
+ "copilot": {"sessionStart", "userPromptSubmitted", "postToolUse"},
48
+ }
49
+
50
+
51
+ def resolve_launcher_target(
52
+ plugin_root: Path, command: str, args: list[str]
53
+ ) -> tuple[str | None, list[str]]:
54
+ expanded = [
55
+ value.replace("${PLUGIN_ROOT}", str(plugin_root))
56
+ .replace("${CLAUDE_PLUGIN_ROOT}", str(plugin_root))
57
+ for value in args
58
+ ]
59
+ command_path = Path(command).expanduser()
60
+ resolved_command = (
61
+ str(command_path.resolve())
62
+ if command_path.is_absolute()
63
+ else shutil.which(command)
64
+ )
65
+ targets = []
66
+ for value in expanded:
67
+ candidate = Path(value)
68
+ if not candidate.is_absolute() and value.startswith("."):
69
+ candidate = plugin_root / candidate
70
+ if candidate.suffix in {"", ".py", ".cmd", ".sh"} and (
71
+ "/" in value or "\\" in value
72
+ ):
73
+ targets.append(str(candidate.resolve()))
74
+ return resolved_command, targets
75
+
76
+
77
+ def check_mcp_launcher(
78
+ plugin_root: Path, client: str, *, required: bool
79
+ ) -> dict[str, Any]:
80
+ root = client_root(plugin_root, client)
81
+ if root is None:
82
+ return check(
83
+ "mcp-launcher", client=client, status="unsupported", required=False,
84
+ summary=f"{client} is not installed in this generated client tree",
85
+ )
86
+ config_path = root / ".mcp.json"
87
+ if not config_path.is_file():
88
+ return check(
89
+ "mcp-launcher", client=client, status="failed", required=required,
90
+ summary=f"missing owned MCP manifest {config_path}",
91
+ actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
92
+ )
93
+ try:
94
+ server = json.loads(config_path.read_text(encoding="utf-8"))[
95
+ "mcpServers"
96
+ ]["adr-kit"]
97
+ command, args = server["command"], server["args"]
98
+ if not isinstance(command, str) or not isinstance(args, list):
99
+ raise TypeError("command/args")
100
+ except (OSError, UnicodeError, json.JSONDecodeError, KeyError, TypeError) as exc:
101
+ return check(
102
+ "mcp-launcher", client=client, status="failed", required=required,
103
+ summary=f"invalid owned MCP manifest {config_path}: {exc}",
104
+ actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
105
+ )
106
+ resolved, targets = resolve_launcher_target(root, command, args)
107
+ missing = [target for target in targets if not Path(target).is_file()]
108
+ if resolved is None or missing:
109
+ return check(
110
+ "mcp-launcher", client=client, status="stale", required=required,
111
+ summary="MCP launcher resolves to a missing command or removed payload",
112
+ evidence=[
113
+ {
114
+ "path": str(config_path),
115
+ "command": command,
116
+ "resolved_command": resolved,
117
+ "missing_targets": missing,
118
+ }
119
+ ],
120
+ actions=[
121
+ {
122
+ "command": (
123
+ f"{sys.executable} scripts/install-agent-envs.py "
124
+ f"--clients {client}"
125
+ )
126
+ }
127
+ ],
128
+ )
129
+ return check(
130
+ "mcp-launcher", client=client, status="healthy", required=required,
131
+ summary="MCP command and payload target resolve",
132
+ evidence=[
133
+ {
134
+ "path": str(config_path),
135
+ "resolved_command": resolved,
136
+ "targets": targets,
137
+ }
138
+ ],
139
+ )
140
+
141
+
142
+ def check_hook_package(plugin_root: Path, client: str) -> dict[str, Any]:
143
+ root = client_root(plugin_root, client)
144
+ if root is None:
145
+ return check(
146
+ "hook-package", client=client, status="unsupported", required=False,
147
+ summary=f"{client} is not installed in this generated client tree",
148
+ )
149
+ config_path = (
150
+ root / "hooks" / "hooks.json"
151
+ if client != "copilot"
152
+ else root / "hooks.json"
153
+ )
154
+ try:
155
+ payload = json.loads(config_path.read_text(encoding="utf-8"))
156
+ hooks = payload["hooks"]
157
+ if not isinstance(hooks, dict) or set(hooks) != HOOK_EVENTS[client]:
158
+ raise ValueError("event set differs from the certified contract")
159
+ handlers = [
160
+ handler
161
+ for groups in hooks.values()
162
+ for group in groups
163
+ for handler in (
164
+ group.get("hooks", []) if client != "copilot" else [group]
165
+ )
166
+ ]
167
+ if not handlers:
168
+ raise ValueError("no command handlers")
169
+ if client == "copilot":
170
+ if any(
171
+ not isinstance(handler.get("bash"), str)
172
+ or not isinstance(handler.get("powershell"), str)
173
+ for handler in handlers
174
+ ):
175
+ raise ValueError("missing bash or PowerShell command")
176
+ elif any(handler.get("type") != "command" for handler in handlers):
177
+ raise ValueError("non-command handler")
178
+ except (
179
+ OSError,
180
+ UnicodeError,
181
+ json.JSONDecodeError,
182
+ KeyError,
183
+ TypeError,
184
+ ValueError,
185
+ ) as exc:
186
+ return check(
187
+ "hook-package",
188
+ client=client,
189
+ status="failed",
190
+ required=False,
191
+ summary=f"broken native hook package: {config_path}: {exc}",
192
+ actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
193
+ )
194
+ runtime = root / "hooks" / "adr-hook.py"
195
+ native = root / "hooks" / "bin" / "windows-x64" / "adr-hook.exe"
196
+ wrapper = root / "hooks" / "run-hook.cmd"
197
+ required_files = [runtime, native]
198
+ if client != "copilot":
199
+ required_files.append(wrapper)
200
+ missing = [str(path) for path in required_files if not path.is_file()]
201
+ if missing:
202
+ return check(
203
+ "hook-package",
204
+ client=client,
205
+ status="failed",
206
+ required=False,
207
+ summary="native hook config points at a missing runtime",
208
+ evidence=[{"missing": missing}],
209
+ actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
210
+ )
211
+ return check(
212
+ "hook-package",
213
+ client=client,
214
+ status="healthy",
215
+ required=False,
216
+ summary="native hook shape and Windows/POSIX launchers resolve",
217
+ evidence=[{"path": str(config_path), "events": sorted(hooks)}],
218
+ )
219
+
220
+
221
+ def _generated_check(plugin_root: Path, check_only: bool) -> tuple[dict, list[dict]]:
222
+ # A generated tree holds no canonical inputs to diff against, so there is
223
+ # nothing here to be stale. Returning before the import matters twice: the
224
+ # generator's source is not mirrored, and in repair mode generate() would
225
+ # otherwise write into the very tree it is inspecting.
226
+ if generated_tree_owner(plugin_root) is not None:
227
+ return check(
228
+ "generated-adapters", status="unsupported", required=False,
229
+ summary="generated client tree carries no canonical inputs to diff",
230
+ actions=[{
231
+ "detail": (
232
+ "Run adr-doctor from the ADR Kit payload root to check "
233
+ "adapter drift."
234
+ )
235
+ }],
236
+ ), []
237
+ from client_generation import GenerationError, generate # not mirrored
238
+ try:
239
+ _stats, drift = generate(plugin_root, check=True)
240
+ except (GenerationError, OSError) as exc:
241
+ return check(
242
+ "generated-adapters", status="failed",
243
+ summary=f"generated artifact check failed: {exc}",
244
+ ), []
245
+ if not drift:
246
+ return check(
247
+ "generated-adapters", status="healthy",
248
+ summary="generated client artifacts match canonical inputs",
249
+ ), []
250
+ if check_only:
251
+ return check(
252
+ "generated-adapters", status="stale",
253
+ summary="generated client artifacts drifted",
254
+ actions=[{
255
+ "command": (
256
+ f"{sys.executable} "
257
+ f"{plugin_root / 'scripts' / 'build-client-adapters.py'}"
258
+ )
259
+ }],
260
+ ), []
261
+ try:
262
+ generate(plugin_root, check=False)
263
+ except (GenerationError, OSError) as exc:
264
+ return check(
265
+ "generated-adapters", status="failed",
266
+ summary=f"safe regeneration failed: {exc}",
267
+ ), []
268
+ evidence = {"kind": "generated-adapters", "path": str(plugin_root)}
269
+ return check(
270
+ "generated-adapters", status="repaired",
271
+ summary="regenerated owned client artifacts",
272
+ repairs=[evidence],
273
+ ), [evidence]
274
+
275
+
276
+ def _guidance_check(root: Path) -> dict:
277
+ guide = root / ".adr-kit" / "ADR-guide.md"
278
+ problems = []
279
+ for relative in ("AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"):
280
+ path = root / relative
281
+ if not path.is_file():
282
+ continue
283
+ try:
284
+ validate_markers(path.read_text(encoding="utf-8-sig"), path)
285
+ except (OSError, UnicodeError, SetupError) as exc:
286
+ problems.append(str(exc))
287
+ if problems:
288
+ return check(
289
+ "project-guidance", status="failed",
290
+ summary="managed instruction markers are malformed",
291
+ evidence=[{"problems": problems}],
292
+ actions=[{"command": "python scripts/setup-project.py --dry-run"}],
293
+ )
294
+ if not guide.is_file():
295
+ return check(
296
+ "project-guidance", status="degraded", required=False,
297
+ summary="project has no generated ADR guide",
298
+ actions=[{"command": "python scripts/setup-project.py"}],
299
+ )
300
+ return check(
301
+ "project-guidance", status="healthy",
302
+ summary="guide and managed instruction markers are structurally valid",
303
+ evidence=[{"path": str(guide)}],
304
+ )
305
+
306
+
307
+ def run_client_checks(
308
+ root: Path,
309
+ plugin_root: Path,
310
+ *,
311
+ global_settings: Path | None,
312
+ check_only: bool,
313
+ allow_fix: bool,
314
+ ) -> tuple[list[dict], list[dict]]:
315
+ checks, repairs = [], []
316
+ generated, generated_repairs = _generated_check(plugin_root, check_only)
317
+ checks.append(generated)
318
+ repairs.extend(generated_repairs)
319
+ try:
320
+ settings = resolve_settings(root, global_path=global_settings)["values"]
321
+ checks.append(check(
322
+ "settings", status="healthy",
323
+ summary="global/project settings parsed with known keys",
324
+ ))
325
+ except SettingsError as exc:
326
+ settings = None
327
+ checks.append(check(
328
+ "settings", status="failed", summary=str(exc),
329
+ actions=[{"detail": "Correct the named ADR Kit settings file."}],
330
+ ))
331
+ guidance = _guidance_check(root)
332
+ checks.append(guidance)
333
+ integration_required = (root / ".adr-kit" / "ADR-guide.md").is_file()
334
+ detected = detect_clients()
335
+ for name in CLIENT_IDS:
336
+ enabled = settings["clients"][name]["enabled"] if settings else None
337
+ if enabled is False:
338
+ checks.append(check(
339
+ "native-client", client=name, status="disabled", required=False,
340
+ summary="client disabled by effective settings",
341
+ ))
342
+ continue
343
+ client = detected.get(name)
344
+ checks.append(check(
345
+ "native-client", client=name,
346
+ status="healthy" if client else "unsupported",
347
+ required=False,
348
+ summary=(
349
+ f"detected {client.version} at {client.executable}"
350
+ if client else "native CLI not installed"
351
+ ),
352
+ evidence=[{"version": client.version, "path": client.executable}] if client else [],
353
+ ))
354
+ checks.append(
355
+ check_mcp_launcher(
356
+ plugin_root, name, required=integration_required
357
+ )
358
+ )
359
+ checks.append(check_hook_package(plugin_root, name))
360
+ if allow_fix and guidance["status"] in {
361
+ "degraded",
362
+ "failed",
363
+ }:
364
+ selected = [
365
+ name for name in CLIENT_IDS
366
+ if name in detected
367
+ and settings
368
+ and settings["clients"][name]["enabled"] is not False
369
+ ]
370
+ try:
371
+ changes, configure = collect_changes(
372
+ root,
373
+ plugin_root,
374
+ selected,
375
+ pre_commit_enabled=bool(
376
+ settings and settings["pre_commit"]["enabled"]
377
+ ),
378
+ )
379
+ apply_changes(root, changes, configure_hooks_path=configure)
380
+ for change in changes:
381
+ repair = {
382
+ "kind": change.action,
383
+ "path": str(change.path),
384
+ }
385
+ repairs.append(repair)
386
+ if changes:
387
+ checks.append(check(
388
+ "project-guidance-fix",
389
+ status="repaired",
390
+ summary="backed up and converged ADR Kit-owned project guidance",
391
+ repairs=repairs[-len(changes):],
392
+ actions=[
393
+ {
394
+ "detail": (
395
+ f"Restore backups under "
396
+ f"{root / '.adr-kit' / 'backups'} if needed."
397
+ )
398
+ }
399
+ ],
400
+ ))
401
+ except SetupError as exc:
402
+ checks.append(check(
403
+ "project-guidance-fix",
404
+ status="failed",
405
+ summary=f"managed repair stopped safely: {exc}",
406
+ ))
407
+ return checks, repairs