@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,342 @@
1
+ """Existing ADR/index/lint/staleness health checks used by adr-doctor."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import os
8
+ import re
9
+ import subprocess
10
+ import sys
11
+ from datetime import date, datetime
12
+ from pathlib import Path
13
+ from typing import Dict, List, Optional
14
+
15
+ from adr_schema import parse_frontmatter, split_frontmatter
16
+ from adr_retrieval_health import run_retrieval_health
17
+
18
+
19
+ ADR_FILENAME_RE = re.compile(r"(?i)^ADR-(\d{1,4})-")
20
+ MATERIAL_DRIFT_TYPES = {"accepted_evidence_changed", "missing_gate"}
21
+
22
+
23
+ def _run_json(command: List[str]) -> tuple[int, Dict]:
24
+ result = subprocess.run(command, capture_output=True, text=True)
25
+ try:
26
+ payload = json.loads(result.stdout) if result.stdout.strip() else {}
27
+ except json.JSONDecodeError:
28
+ payload = {"_stdout": result.stdout, "_stderr": result.stderr}
29
+ return result.returncode, payload
30
+
31
+
32
+ def load_config(adr_dir: Path, explicit: Optional[str]) -> Dict:
33
+ candidates = []
34
+ if explicit:
35
+ candidates.append(Path(explicit))
36
+ candidates.extend([adr_dir / ".adr-kit.json", adr_dir.parent.parent / ".adr-kit.json"])
37
+ for path in candidates:
38
+ if path.exists():
39
+ return json.loads(path.read_text(encoding="utf-8"))
40
+ return {}
41
+
42
+
43
+ def discover_files(adr_dir: Path) -> List[Path]:
44
+ return sorted(adr_dir.glob("ADR-*.md"), key=lambda p: p.name.lower()) if adr_dir.is_dir() else []
45
+
46
+
47
+ def load_records(adr_dir: Path) -> List[Dict]:
48
+ records = []
49
+ for path in discover_files(adr_dir):
50
+ text = path.read_text(encoding="utf-8", errors="replace")
51
+ raw, _body = split_frontmatter(text)
52
+ if raw is None:
53
+ continue
54
+ data = parse_frontmatter(raw)
55
+ records.append({"path": path, "data": data, "body": _body})
56
+ return records
57
+
58
+
59
+ def _pointer_parts(pointer: str) -> tuple[Optional[Path], Optional[str]]:
60
+ if pointer.startswith("commit:"):
61
+ return None, None
62
+ path_part = pointer
63
+ symbol = None
64
+ if ":" in pointer and not re.match(r"^[A-Za-z]:[\\/]", pointer):
65
+ path_part, symbol = pointer.split(":", 1)
66
+ return Path(path_part), symbol.strip() if symbol else None
67
+
68
+
69
+ def pointer_resolves(pointer: str, repo_root: Path) -> bool:
70
+ if pointer.startswith("commit:"):
71
+ commit = pointer.split(":", 1)[1].strip()
72
+ if not commit:
73
+ return False
74
+ result = subprocess.run(
75
+ ["git", "-C", str(repo_root), "cat-file", "-e", f"{commit}^{{commit}}"],
76
+ capture_output=True,
77
+ text=True,
78
+ )
79
+ return result.returncode == 0
80
+ rel_path, symbol = _pointer_parts(pointer)
81
+ if rel_path is None:
82
+ return False
83
+ path = repo_root / rel_path
84
+ if not path.is_file():
85
+ return False
86
+ if symbol is None:
87
+ return True
88
+ return symbol in path.read_text(encoding="utf-8", errors="ignore")
89
+
90
+
91
+ def pointer_changed_after(pointer: str, repo_root: Path, accepted_on: date) -> bool:
92
+ rel_path, _symbol = _pointer_parts(pointer)
93
+ if rel_path is None:
94
+ return False
95
+ path = repo_root / rel_path
96
+ if not path.is_file():
97
+ return False
98
+ changed_on = datetime.fromtimestamp(os.path.getmtime(path)).date()
99
+ return changed_on > accepted_on
100
+
101
+
102
+ def latest_status_date(body: str, status: str) -> Optional[date]:
103
+ """Return the latest matching lifecycle-history date, if one exists."""
104
+ pending_date: Optional[date] = None
105
+ matches: List[date] = []
106
+ for line in body.splitlines():
107
+ stripped = line.strip()
108
+ if stripped.startswith("- date:"):
109
+ value = stripped.split(":", 1)[1].strip().strip("\"'")
110
+ try:
111
+ pending_date = date.fromisoformat(value)
112
+ except ValueError:
113
+ pending_date = None
114
+ elif pending_date is not None and stripped.startswith("status:"):
115
+ value = stripped.split(":", 1)[1].strip().strip("\"'")
116
+ if value == status:
117
+ matches.append(pending_date)
118
+ pending_date = None
119
+ return max(matches) if matches else None
120
+
121
+
122
+ def staleness_findings(records: List[Dict], repo_root: Path, stale_days: int) -> List[Dict]:
123
+ today = date.today()
124
+ findings: List[Dict] = []
125
+ for record in records:
126
+ data = record["data"]
127
+ adr_id = data.get("id", record["path"].stem)
128
+ status = data.get("status")
129
+ date_str = data.get("date")
130
+ adr_date = None
131
+ if date_str:
132
+ try:
133
+ adr_date = date.fromisoformat(date_str)
134
+ except ValueError:
135
+ adr_date = None
136
+ verified = data.get("verified_in", [])
137
+
138
+ if status == "Proposed":
139
+ if verified and all(pointer_resolves(pointer, repo_root) for pointer in verified):
140
+ findings.append({
141
+ "type": "shipped_but_proposed",
142
+ "adr_id": adr_id,
143
+ "file": record["path"].name,
144
+ "message": "Proposed ADR has resolving verified_in evidence",
145
+ })
146
+ if adr_date is not None and (today - adr_date).days > stale_days:
147
+ findings.append({
148
+ "type": "old_proposed",
149
+ "adr_id": adr_id,
150
+ "file": record["path"].name,
151
+ "message": f"Proposed ADR is older than {stale_days} days",
152
+ })
153
+
154
+ if status == "Accepted" and adr_date is not None and verified:
155
+ reviewed_on = latest_status_date(record.get("body", ""), "Accepted")
156
+ evidence_date = max(adr_date, reviewed_on) if reviewed_on else adr_date
157
+ changed = [
158
+ pointer for pointer in verified
159
+ if pointer_changed_after(pointer, repo_root, evidence_date)
160
+ ]
161
+ if changed:
162
+ findings.append({
163
+ "type": "accepted_evidence_changed",
164
+ "adr_id": adr_id,
165
+ "file": record["path"].name,
166
+ "message": "Accepted ADR evidence changed after acceptance",
167
+ "pointers": changed,
168
+ })
169
+ return findings
170
+
171
+
172
+ def gate_findings_from_lint(lint_payload: Dict) -> List[Dict]:
173
+ findings = []
174
+ for item in lint_payload.get("files", []):
175
+ for finding in item.get("findings", []):
176
+ if finding.get("gate") == "consistency" and "gate " in finding.get("summary", ""):
177
+ findings.append({
178
+ "type": "missing_gate",
179
+ "adr_id": f"ADR-{int(item.get('adr_num', 0)):03d}",
180
+ "file": item.get("file"),
181
+ "message": finding["summary"],
182
+ })
183
+ return findings
184
+
185
+
186
+ def run_audit(repo_root: Path, audit_script: Path) -> Dict:
187
+ result = subprocess.run(
188
+ [sys.executable, str(audit_script), "--root", str(repo_root)],
189
+ capture_output=True,
190
+ text=True,
191
+ )
192
+ try:
193
+ payload = json.loads(result.stdout) if result.stdout.strip() else {}
194
+ except json.JSONDecodeError:
195
+ payload = {"_stdout": result.stdout, "_stderr": result.stderr}
196
+ return {
197
+ "triggered": True,
198
+ "exit_code": result.returncode,
199
+ "candidate_count": int(payload.get("candidate_count", 0) or 0),
200
+ "candidates": payload.get("candidates", []),
201
+ "error": result.stderr.strip() if result.returncode != 0 else None,
202
+ }
203
+
204
+
205
+ def run_doctor(args) -> Dict:
206
+ adr_dir = Path(args.adr_dir)
207
+ repo_root = Path(args.repo_root).resolve() if args.repo_root else Path.cwd().resolve()
208
+ cfg = load_config(adr_dir, args.config)
209
+ stale_days = args.stale_days
210
+ if stale_days is None:
211
+ stale_days = int(cfg.get("doctor", {}).get("proposed_stale_days", 30))
212
+
213
+ bin_dir = Path(__file__).resolve().parent
214
+ index_script = bin_dir / "adr-index"
215
+ lint_script = bin_dir / "adr-lint"
216
+ audit_script = bin_dir / "adr-discover"
217
+
218
+ if args.fix_index:
219
+ subprocess.run([sys.executable, str(index_script), str(adr_dir)], capture_output=True, text=True)
220
+
221
+ index_code, index_payload = _run_json(
222
+ [sys.executable, str(index_script), "--check", "--format", "json", str(adr_dir)]
223
+ )
224
+ lint_code, lint_payload = _run_json(
225
+ [
226
+ sys.executable,
227
+ str(lint_script),
228
+ "--strict",
229
+ "--format",
230
+ "json",
231
+ "--repo-root",
232
+ str(repo_root),
233
+ str(adr_dir),
234
+ ]
235
+ )
236
+ records = load_records(adr_dir)
237
+ findings = staleness_findings(records, repo_root, stale_days)
238
+ findings.extend(gate_findings_from_lint(lint_payload))
239
+ retrieval = run_retrieval_health(adr_dir, config=cfg)
240
+ if retrieval.get("probe_error"):
241
+ findings.append(
242
+ {
243
+ "type": "retrieval_probe_config",
244
+ "adr_id": "ADR-SET",
245
+ "file": Path(retrieval["probe_file"]).name,
246
+ "message": retrieval["probe_error"],
247
+ }
248
+ )
249
+ for probe in retrieval.get("probes", {}).get("results", []):
250
+ if probe.get("status") == "fail":
251
+ findings.append(
252
+ {
253
+ "type": "retrieval_probe",
254
+ "adr_id": "ADR-SET",
255
+ "file": Path(retrieval["probe_file"]).name,
256
+ "message": (
257
+ f"probe {probe['id']} failed; missing={probe['missing']} "
258
+ f"unexpected={probe['unexpected']}"
259
+ ),
260
+ "probe": probe,
261
+ }
262
+ )
263
+ findings.extend(
264
+ item
265
+ for item in retrieval.get("metadata_findings", [])
266
+ if item.get("level") == "FAIL"
267
+ )
268
+ material_drift = [
269
+ finding for finding in findings
270
+ if finding.get("type") in MATERIAL_DRIFT_TYPES
271
+ ]
272
+ audit_payload = {
273
+ "triggered": False,
274
+ "exit_code": None,
275
+ "candidate_count": 0,
276
+ "candidates": [],
277
+ "reason": None,
278
+ }
279
+ if material_drift:
280
+ audit_payload = run_audit(repo_root, audit_script)
281
+ audit_payload["reason"] = "material_drift"
282
+
283
+ return {
284
+ "adr_dir": str(adr_dir),
285
+ "repo_root": str(repo_root),
286
+ "summary": {
287
+ "index_ok": index_code == 0,
288
+ "lint_ok": lint_code == 0,
289
+ "findings": len(findings),
290
+ "retrieval_status": retrieval["status"],
291
+ "retrieval_advisories": sum(
292
+ item.get("level") == "ADVISORY"
293
+ for item in retrieval.get("metadata_findings", [])
294
+ ),
295
+ "retrieval_probe_failures": retrieval.get("probes", {})
296
+ .get("summary", {})
297
+ .get("fail", 0),
298
+ },
299
+ "index": index_payload.get("summary", {}),
300
+ "lint": lint_payload.get("summary", {}),
301
+ "findings": findings,
302
+ "retrieval": retrieval,
303
+ "audit": audit_payload,
304
+ "exit_code": 1 if index_code != 0 or lint_code != 0 or findings else 0,
305
+ }
306
+
307
+
308
+ def render_text(payload: Dict) -> str:
309
+ lines = [
310
+ f"adr-doctor: {payload['adr_dir']}",
311
+ f"index_ok={payload['summary']['index_ok']} lint_ok={payload['summary']['lint_ok']} findings={payload['summary']['findings']}",
312
+ ]
313
+ for finding in payload["findings"]:
314
+ lines.append(f" {finding['type']}: {finding['adr_id']} {finding['message']}")
315
+ audit = payload.get("audit", {})
316
+ if audit.get("triggered"):
317
+ lines.append(
318
+ f"audit_triggered=True reason={audit.get('reason')} candidates={audit.get('candidate_count', 0)}"
319
+ )
320
+ return "\n".join(lines)
321
+
322
+
323
+ def main(argv: List[str] | None = None) -> int:
324
+ parser = argparse.ArgumentParser(prog="adr-doctor", description="Run local ADR health checks.")
325
+ parser.add_argument("adr_dir", nargs="?", default="docs/adr")
326
+ parser.add_argument("--repo-root", default=None)
327
+ parser.add_argument("--config", default=None)
328
+ parser.add_argument("--stale-days", type=int, default=None)
329
+ parser.add_argument("--fix-index", action="store_true", help="regenerate index before checking")
330
+ parser.add_argument("--format", choices=["text", "json"], default="text")
331
+ args = parser.parse_args(argv)
332
+
333
+ payload = run_doctor(args)
334
+ if args.format == "json":
335
+ print(json.dumps(payload, indent=2))
336
+ else:
337
+ print(render_text(payload))
338
+ return int(payload["exit_code"])
339
+
340
+
341
+ if __name__ == "__main__":
342
+ sys.exit(main())
@@ -0,0 +1,186 @@
1
+ """Versioned doctor output models and rendering."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ SCHEMA_VERSION = 1
9
+ FAILURE_STATUSES = {"failed", "stale"}
10
+ STATUS_ORDER = {
11
+ "failed": 8,
12
+ "stale": 7,
13
+ "trust-pending": 6,
14
+ "degraded": 5,
15
+ "repaired": 4,
16
+ "disabled": 3,
17
+ "unsupported": 2,
18
+ "healthy": 1,
19
+ }
20
+
21
+
22
+ def check(
23
+ check_id: str,
24
+ *,
25
+ status: str,
26
+ client: str = "common",
27
+ summary: str,
28
+ evidence: list[dict[str, Any]] | None = None,
29
+ repairs: list[dict[str, Any]] | None = None,
30
+ degradations: list[dict[str, Any]] | None = None,
31
+ actions: list[dict[str, Any]] | None = None,
32
+ required: bool = True,
33
+ extension: dict[str, Any] | None = None,
34
+ ) -> dict[str, Any]:
35
+ return {
36
+ "id": check_id,
37
+ "client": client,
38
+ "status": status,
39
+ "required": required,
40
+ "summary": summary,
41
+ "evidence": evidence or [],
42
+ "repairs": repairs or [],
43
+ "degradations": degradations or [],
44
+ "actions": actions or [],
45
+ "extension": extension,
46
+ }
47
+
48
+
49
+ def benchmark_extension(
50
+ *,
51
+ method_id: str,
52
+ state: str,
53
+ sample_count: int,
54
+ reference_fixture: str,
55
+ budget: dict[str, float | int],
56
+ measurements: dict[str, float | int | None] | None = None,
57
+ ) -> dict[str, Any]:
58
+ values = {"p50_ms": None, "p95_ms": None, "max_ms": None}
59
+ values.update(measurements or {})
60
+ return {
61
+ "contract_version": 1,
62
+ "kind": "latency-benchmark",
63
+ "method_id": method_id,
64
+ "state": state,
65
+ "sample_count": sample_count,
66
+ "reference_fixture": reference_fixture,
67
+ "measurements": values,
68
+ "budget": budget,
69
+ }
70
+
71
+
72
+ def build_report(
73
+ *,
74
+ root: Path,
75
+ mode: str,
76
+ adr: dict[str, Any],
77
+ checks: list[dict[str, Any]],
78
+ repairs: list[dict[str, Any]],
79
+ ) -> dict[str, Any]:
80
+ client_status = {}
81
+ for client in ("claude", "codex", "copilot"):
82
+ relevant = [item["status"] for item in checks if item["client"] == client]
83
+ client_status[client] = (
84
+ max(relevant, key=lambda value: STATUS_ORDER.get(value, 0))
85
+ if relevant
86
+ else "unsupported"
87
+ )
88
+ required_failures = [
89
+ item for item in checks
90
+ if item["required"] and item["status"] in FAILURE_STATUSES
91
+ ]
92
+ exit_code = 1 if adr.get("exit_code") or required_failures else 0
93
+ statuses = [item["status"] for item in checks]
94
+ if exit_code:
95
+ overall = "failed"
96
+ elif "degraded" in statuses or "trust-pending" in statuses:
97
+ overall = "degraded"
98
+ elif repairs or "repaired" in statuses:
99
+ overall = "repaired"
100
+ else:
101
+ overall = "healthy"
102
+ return {
103
+ "schema_version": SCHEMA_VERSION,
104
+ "mode": mode,
105
+ "root": str(root),
106
+ "overall_status": overall,
107
+ "clients": client_status,
108
+ "summary": {
109
+ "index_ok": adr.get("summary", {}).get("index_ok", False),
110
+ "lint_ok": adr.get("summary", {}).get("lint_ok", False),
111
+ "findings": adr.get("summary", {}).get("findings", 0),
112
+ "checks": len(checks),
113
+ "repairs": len(repairs),
114
+ "required_failures": len(required_failures),
115
+ "adr_findings": adr.get("summary", {}).get("findings", 0),
116
+ },
117
+ "checks": checks,
118
+ "repairs": repairs,
119
+ "adr": adr,
120
+ # Stable legacy fields retained for existing CI consumers.
121
+ "adr_dir": adr.get("adr_dir"),
122
+ "repo_root": adr.get("repo_root"),
123
+ "index": adr.get("index", {}),
124
+ "lint": adr.get("lint", {}),
125
+ "findings": adr.get("findings", []),
126
+ "audit": adr.get("audit", {}),
127
+ "exit_code": exit_code,
128
+ }
129
+
130
+
131
+ def render_human(report: dict[str, Any]) -> str:
132
+ lines = [
133
+ f"adr-doctor: {report['overall_status']} ({report['mode']})",
134
+ "clients: " + ", ".join(
135
+ f"{name}={status}" for name, status in report["clients"].items()
136
+ ),
137
+ (
138
+ f"checks={report['summary']['checks']} "
139
+ f"repairs={report['summary']['repairs']} "
140
+ f"adr_findings={report['summary']['adr_findings']}"
141
+ ),
142
+ ]
143
+ for item in report["checks"]:
144
+ lines.append(
145
+ f" {item['status']}: {item['client']}/{item['id']} "
146
+ f"{item['summary']}"
147
+ )
148
+ for action in item["actions"]:
149
+ lines.append(f" action: {action.get('command') or action.get('detail')}")
150
+ for repair in report["repairs"]:
151
+ lines.append(f" repaired: {repair['path']} ({repair['kind']})")
152
+ return "\n".join(lines)
153
+
154
+
155
+ def generated_tree_owner(plugin_root: Path) -> str | None:
156
+ """Which client this tree IS, when it is a generated client tree.
157
+
158
+ Positive identity, not "my import failed". A canonical payload root always
159
+ carries clients/workflows.json: it is the generator's own input, and the
160
+ public payload ships `clients` as a whole include_root, so an installed
161
+ payload has it at its root too. RUNTIME_SUPPORT_FILES deliberately never
162
+ mirrors it -- that absence is the marker read here, which is why mirroring
163
+ it later would silently stop the doctor degrading and start it hard-failing.
164
+ """
165
+ if (plugin_root / "clients" / "workflows.json").is_file():
166
+ return None
167
+ if (plugin_root / ".codex-plugin" / "plugin.json").is_file():
168
+ return "codex"
169
+ if (plugin_root / "plugin.json").is_file() and (plugin_root / "hooks.json").is_file():
170
+ return "copilot"
171
+ return None
172
+
173
+
174
+ def client_root(plugin_root: Path, client: str) -> Path | None:
175
+ """Where this client's owned config lives, or None if not installed here.
176
+
177
+ In a canonical payload root each client owns a subdirectory. In a generated
178
+ client tree there is only one client and it owns the root itself -- codex/
179
+ IS the plugin root for Codex, so codex/.mcp.json sits there and not at
180
+ codex/codex/.mcp.json. Assuming the canonical shape made the doctor report
181
+ six failures against paths that were never meant to exist.
182
+ """
183
+ owner = generated_tree_owner(plugin_root)
184
+ if owner is None:
185
+ return plugin_root if client == "claude" else plugin_root / client
186
+ return plugin_root if client == owner else None