@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,443 @@
1
+ """adr_index_core: the ADR index generator, separated from its CLI.
2
+
3
+ `bin/adr-index` was both the renderer and the command. That was fine while the
4
+ only caller was the command line, and it stopped being fine when the guardian
5
+ needed to answer one question at SessionStart -- *is the committed index still
6
+ what the generator would produce?* -- without spawning a subprocess, which its
7
+ own contract forbids.
8
+
9
+ So the rendering and comparison live here, importable like every other
10
+ ``adr_*.py`` sibling, and ``bin/adr-index`` is the thin argument-parsing shell
11
+ over it. Nothing about the output changed in the move; the generator is still
12
+ the single source of truth for all three artefacts (README block, ADR-INDEX.md,
13
+ ADR-INDEX.json).
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import importlib.machinery
19
+ import importlib.util
20
+ import io
21
+ import json
22
+ import re
23
+ import sys
24
+ from pathlib import Path
25
+ from typing import Dict, List, Optional
26
+
27
+ _BIN_DIR = Path(__file__).resolve().parent
28
+
29
+
30
+ def _load_sibling(name: str):
31
+ """Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
32
+
33
+ SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
34
+ of the standard library for every import, so a module committed next to
35
+ this script executed as code -- and it re-added the very directory
36
+ CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
37
+ sys.modules under their bare name, so the plain `from adr_* import ...`
38
+ statements below (and the lazy ones inside functions) resolve from the
39
+ cache instead of the path. bin/adr-judge carries the full rationale.
40
+ """
41
+ cached = sys.modules.get(name)
42
+ if cached is not None:
43
+ return cached
44
+ loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
45
+ spec = importlib.util.spec_from_loader(name, loader)
46
+ module = importlib.util.module_from_spec(spec)
47
+ sys.modules[name] = module
48
+ loader.exec_module(module)
49
+ return module
50
+
51
+
52
+ # Dependency order: adr_catalog imports adr_format and adr_schema.
53
+ _load_sibling("adr_format")
54
+ _load_sibling("adr_schema")
55
+ _load_sibling("adr_catalog")
56
+
57
+ from adr_catalog import (
58
+ build_graph_document,
59
+ discover_adr_files,
60
+ enforcement_globs as catalog_enforcement_globs,
61
+ load_adr_records,
62
+ )
63
+
64
+
65
+ BEGIN = "<!-- adr-kit-index:begin -->"
66
+ END = "<!-- adr-kit-index:end -->"
67
+
68
+ TITLE_RE = re.compile(r"^#\s+ADR-\d+[:\s]\s*(.+)$", re.MULTILINE)
69
+ DECISION_SECTION_RE = re.compile(
70
+ r"^##\s+Decision(.*?)(?=^##|\Z)", re.IGNORECASE | re.MULTILINE | re.DOTALL
71
+ )
72
+
73
+
74
+ def _ensure_utf8_streams() -> None:
75
+ for stream_name in ("stdout", "stderr"):
76
+ stream = getattr(sys, stream_name, None)
77
+ if stream is None:
78
+ continue
79
+ buffer = getattr(stream, "buffer", None)
80
+ if buffer is None:
81
+ continue
82
+ try:
83
+ setattr(
84
+ sys,
85
+ stream_name,
86
+ io.TextIOWrapper(buffer, encoding="utf-8", newline="\n"),
87
+ )
88
+ except (AttributeError, ValueError):
89
+ pass
90
+
91
+
92
+ def enforcement_globs(text: str) -> List[str]:
93
+ """Return all path_glob strings from the ADR's Enforcement block."""
94
+ return catalog_enforcement_globs(text)
95
+
96
+
97
+ def discover_files(adr_dir: Path) -> List[Path]:
98
+ return discover_adr_files(adr_dir)
99
+
100
+
101
+ def load_index(adr_dir: Path) -> List[Dict]:
102
+ """Load every ADR in adr_dir as a context-index row. One read per file."""
103
+ return load_adr_records(adr_dir)
104
+
105
+
106
+ def _escape_cell(value: str) -> str:
107
+ return value.replace("|", "\\|").replace("\n", " ").strip()
108
+
109
+
110
+ def render_markdown(rows: List[Dict]) -> str:
111
+ lines = [
112
+ "<!-- Generated by bin/adr-index. Do not edit by hand; regenerate with: bin/adr-index -o docs/adr/ADR-INDEX.md -->",
113
+ "",
114
+ "# ADR Index",
115
+ "",
116
+ "One row per Architecture Decision Record. Scope is the Enforcement "
117
+ "`path_glob` set that governs where the decision applies; only "
118
+ "`Accepted` ADRs are injected at edit time (ADR-004).",
119
+ "",
120
+ "| ADR | Status | Scope | Decision |",
121
+ "| --- | --- | --- | --- |",
122
+ ]
123
+ for row in rows:
124
+ scope = ", ".join(f"`{glob}`" for glob in row["scope"]) if row["scope"] else "-"
125
+ decision = _escape_cell(row["decision"]) or "-"
126
+ lines.append(
127
+ f"| {row['adr_id']} | {row['status']} | {scope} | {decision} |"
128
+ )
129
+ if not rows:
130
+ lines.append("| _(none)_ | | | |")
131
+ return "\n".join(lines) + "\n"
132
+
133
+
134
+ def render_context_json(rows: List[Dict]) -> str:
135
+ payload = [
136
+ {
137
+ "adr_id": row["adr_id"],
138
+ "title": row["title"],
139
+ "status": row["status"],
140
+ "format": row["format"],
141
+ "scope": row["scope"],
142
+ "decision": row["decision"],
143
+ "path": row["path"],
144
+ }
145
+ for row in rows
146
+ ]
147
+ return json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
148
+
149
+
150
+ def render_graph_json(rows: List[Dict]) -> str:
151
+ return json.dumps(
152
+ build_graph_document(rows),
153
+ indent=2,
154
+ ensure_ascii=False,
155
+ ) + "\n"
156
+
157
+
158
+ def _find_adr_dir(explicit: Optional[str]) -> Optional[Path]:
159
+ if explicit:
160
+ path = Path(explicit)
161
+ return path if path.is_dir() else None
162
+ for candidate in (Path("docs/adr"), Path("adr"), Path(".")):
163
+ if candidate.is_dir() and discover_files(candidate):
164
+ return candidate
165
+ return None
166
+
167
+
168
+ def _readme_record(record: Dict) -> Dict:
169
+ return {
170
+ "id": record["adr_id"],
171
+ "title": record["title"],
172
+ "status": record["status"],
173
+ "date": record["date"],
174
+ "supersedes": record["supersedes"],
175
+ "superseded_by": record["superseded_by"],
176
+ "file": record["path"],
177
+ }
178
+
179
+
180
+ def _supersession_note(record: Dict) -> str:
181
+ notes: List[str] = []
182
+ if record.get("superseded_by"):
183
+ notes.append(f"Superseded by {record['superseded_by']}")
184
+ supersedes = record.get("supersedes") or []
185
+ if supersedes:
186
+ notes.append("Supersedes " + ", ".join(supersedes))
187
+ return "; ".join(notes) if notes else "-"
188
+
189
+
190
+ def render_generated_readme_block(records: List[Dict], issues: List[str]) -> str:
191
+ status_counts: Dict[str, int] = {}
192
+ for record in records:
193
+ status_counts[record["status"]] = status_counts.get(record["status"], 0) + 1
194
+
195
+ lines = [
196
+ BEGIN,
197
+ "## ADR Index",
198
+ "",
199
+ "Generated by `bin/adr-index`. Do not edit between the sentinels.",
200
+ "",
201
+ "### Summary",
202
+ "",
203
+ "| Metric | Count |",
204
+ "| --- | ---: |",
205
+ f"| Total ADRs | {len(records)} |",
206
+ ]
207
+ for status, count in sorted(status_counts.items()):
208
+ lines.append(f"| {status} | {count} |")
209
+ lines.extend(
210
+ [
211
+ f"| Duplicate IDs | {len(issues)} |",
212
+ "",
213
+ "### Decisions",
214
+ "",
215
+ "| ADR | Title | Status | Date | Supersession | File |",
216
+ "| --- | --- | --- | --- | --- | --- |",
217
+ ]
218
+ )
219
+ for record in records:
220
+ lines.append(
221
+ "| "
222
+ + " | ".join(
223
+ [
224
+ _escape_cell(record["id"]),
225
+ _escape_cell(record["title"]),
226
+ _escape_cell(record["status"]),
227
+ _escape_cell(record["date"] or "-"),
228
+ _escape_cell(_supersession_note(record)),
229
+ _escape_cell(record["file"]),
230
+ ]
231
+ )
232
+ + " |"
233
+ )
234
+ if issues:
235
+ lines.extend(["", "### Index Issues", ""])
236
+ lines.extend(f"- {issue}" for issue in issues)
237
+ lines.append(END)
238
+ lines.append("")
239
+ return "\n".join(lines)
240
+
241
+
242
+ def default_readme(block: str) -> str:
243
+ return "\n".join(
244
+ [
245
+ "# Architecture Decision Records",
246
+ "",
247
+ "This README contains the generated local ADR index.",
248
+ "",
249
+ block.rstrip(),
250
+ "",
251
+ ]
252
+ )
253
+
254
+
255
+ def update_readme(existing: Optional[str], block: str) -> str:
256
+ if existing is None:
257
+ return default_readme(block)
258
+ if BEGIN in existing and END in existing:
259
+ before, rest = existing.split(BEGIN, 1)
260
+ _old, after = rest.split(END, 1)
261
+ return before.rstrip() + "\n\n" + block.rstrip() + after
262
+ return existing.rstrip() + "\n\n" + block.rstrip() + "\n"
263
+
264
+
265
+ def build_readme_payload(adr_dir: Path, readme: Path) -> Dict:
266
+ index_rows = load_index(adr_dir)
267
+ records = [_readme_record(record) for record in index_rows]
268
+ grouped: Dict[str, List[str]] = {}
269
+ for record in records:
270
+ grouped.setdefault(record["id"], []).append(record["file"])
271
+ issues = [
272
+ f"{adr_id} appears in multiple files: {', '.join(files)}"
273
+ for adr_id, files in sorted(grouped.items())
274
+ if len(files) > 1
275
+ ]
276
+ block = render_generated_readme_block(records, issues)
277
+ existing = readme.read_text(encoding="utf-8") if readme.exists() else None
278
+ desired_readme = update_readme(existing, block)
279
+ markdown_path = adr_dir / "ADR-INDEX.md"
280
+ json_path = adr_dir / "ADR-INDEX.json"
281
+ desired_markdown = render_markdown(index_rows)
282
+ desired_json = render_graph_json(index_rows)
283
+ current_markdown = (
284
+ markdown_path.read_text(encoding="utf-8") if markdown_path.exists() else None
285
+ )
286
+ current_json = json_path.read_text(encoding="utf-8") if json_path.exists() else None
287
+ readme_changed = existing != desired_readme
288
+ markdown_changed = current_markdown != desired_markdown
289
+ json_changed = current_json != desired_json
290
+ return {
291
+ "adr_dir": str(adr_dir),
292
+ "readme": str(readme),
293
+ "context_markdown": str(markdown_path),
294
+ "context_json": str(json_path),
295
+ "summary": {
296
+ "total": len(records),
297
+ "duplicates": len(issues),
298
+ "changed": readme_changed or markdown_changed or json_changed,
299
+ "readme_changed": readme_changed,
300
+ "context_markdown_changed": markdown_changed,
301
+ "context_json_changed": json_changed,
302
+ },
303
+ "issues": issues,
304
+ "records": records,
305
+ "_desired_readme": desired_readme,
306
+ "_desired_markdown": desired_markdown,
307
+ "_desired_json": desired_json,
308
+ }
309
+
310
+
311
+ def render_readme_text(payload: Dict, check: bool) -> str:
312
+ summary = payload["summary"]
313
+ lines = [
314
+ f"adr-index {'check' if check else 'write'}: {payload['readme']}",
315
+ f"ADRs: {summary['total']}; duplicates: {summary['duplicates']}; changed: {summary['changed']}",
316
+ "Artifacts: "
317
+ f"README={summary['readme_changed']}; "
318
+ f"Markdown={summary['context_markdown_changed']}; "
319
+ f"JSON={summary['context_json_changed']}",
320
+ ]
321
+ for issue in payload["issues"]:
322
+ lines.append(f" issue: {issue}")
323
+ return "\n".join(lines)
324
+
325
+
326
+ INDEX_ARTIFACTS = ("README.md", "ADR-INDEX.md", "ADR-INDEX.json")
327
+
328
+
329
+ def stale_index_artifacts(adr_dir: Path) -> List[str]:
330
+ """Which generated index artefacts no longer match the ADRs, if any.
331
+
332
+ Returns the artefact filenames that would change if the generator ran now.
333
+ An empty list means the committed index tells the truth.
334
+
335
+ Callers on a hook budget should gate this behind ``index_probably_fresh``:
336
+ this function reads and re-renders every ADR, which is cheap on a normal
337
+ set and not free on a large one.
338
+ """
339
+ if not adr_dir.is_dir() or not discover_adr_files(adr_dir):
340
+ # No ADRs means no index to be stale about. Reporting three missing
341
+ # artefacts in a project that has not written its first decision yet is
342
+ # a false alarm, and a false alarm is how a check gets ignored.
343
+ return []
344
+ try:
345
+ payload = build_readme_payload(adr_dir, adr_dir / "README.md")
346
+ except (OSError, ValueError):
347
+ # A generator that cannot run is not evidence of a stale index. Say
348
+ # nothing rather than nudge about a failure the user cannot act on.
349
+ return []
350
+ desired = {
351
+ "README.md": payload.pop("_desired_readme"),
352
+ "ADR-INDEX.md": payload.pop("_desired_markdown"),
353
+ "ADR-INDEX.json": payload.pop("_desired_json"),
354
+ }
355
+ stale: List[str] = []
356
+ for name, want in desired.items():
357
+ path = adr_dir / name
358
+ try:
359
+ have = path.read_text(encoding="utf-8")
360
+ except OSError:
361
+ stale.append(name)
362
+ continue
363
+ if have != want:
364
+ stale.append(name)
365
+ return stale
366
+
367
+
368
+ def index_probably_fresh(adr_dir: Path) -> bool:
369
+ """Cheap mtime precondition: no ADR is newer than every index artefact.
370
+
371
+ True means "skip the full render" for an advisory nudge. It is deliberately
372
+ NOT proof of freshness -- a hand-edited ADR-INDEX.md is newer than every
373
+ ADR and still wrong, and a checkout can give every file the same timestamp.
374
+ Use it to avoid work, never to certify a result. The real answer is
375
+ ``stale_index_artifacts``, and CI runs that one unconditionally.
376
+ """
377
+ if not adr_dir.is_dir():
378
+ return True
379
+ try:
380
+ newest_adr = max(
381
+ (path.stat().st_mtime for path in discover_adr_files(adr_dir)),
382
+ default=None,
383
+ )
384
+ if newest_adr is None:
385
+ return True
386
+ oldest_index = min(
387
+ (adr_dir / name).stat().st_mtime for name in INDEX_ARTIFACTS
388
+ )
389
+ except OSError:
390
+ return False
391
+ return oldest_index >= newest_adr
392
+
393
+
394
+ # Measured on this repository, 2026-08-05: a full in-process render of 29 ADRs
395
+ # costs ~84 ms median, about 4.7 ms per ADR, against a 2.8 ms freshness probe.
396
+ # Through a subprocess the same work costs ~302 ms, which is why ADR-021 requires
397
+ # in-process regeneration rather than spawning the generator.
398
+ MS_PER_ADR_RENDER = 4.7
399
+ RENDER_FIXED_COST_MS = 50.0
400
+
401
+
402
+ def projected_render_ms(adr_dir: Path) -> float:
403
+ """What a full regeneration of this directory is likely to cost.
404
+
405
+ Deliberately a projection from a count rather than a trial run: the point is
406
+ to decide whether to start, and a measurement that had to render first would
407
+ have already spent the budget it exists to protect.
408
+ """
409
+ try:
410
+ count = sum(1 for _ in discover_adr_files(adr_dir))
411
+ except OSError:
412
+ return float("inf")
413
+ return RENDER_FIXED_COST_MS + count * MS_PER_ADR_RENDER
414
+
415
+
416
+ def regenerate_index(adr_dir: Path, readme: Optional[Path] = None) -> List[str]:
417
+ """Rewrite the generated index artefacts in place. Returns what changed.
418
+
419
+ The write half of `bin/adr-index`, without the process. ADR-021 needs this
420
+ callable from the hook: spawning the generator costs ~302 ms against ~84 ms
421
+ in-process, and the events that may regenerate carry a budget that cannot
422
+ hold the difference.
423
+
424
+ Raises rather than guessing when the ADR set has issues the generator cannot
425
+ resolve -- the caller is a fail-open hook and decides what to do with that.
426
+ """
427
+ payload = build_readme_payload(adr_dir, readme or (adr_dir / "README.md"))
428
+ desired_readme = payload.pop("_desired_readme")
429
+ desired_markdown = payload.pop("_desired_markdown")
430
+ desired_json = payload.pop("_desired_json")
431
+ if payload["issues"]:
432
+ raise ValueError("; ".join(str(issue) for issue in payload["issues"]))
433
+
434
+ target_readme = readme or (adr_dir / "README.md")
435
+ adr_dir.mkdir(parents=True, exist_ok=True)
436
+ target_readme.parent.mkdir(parents=True, exist_ok=True)
437
+ target_readme.write_text(desired_readme, encoding="utf-8")
438
+ (adr_dir / "ADR-INDEX.md").write_text(desired_markdown, encoding="utf-8")
439
+ (adr_dir / "ADR-INDEX.json").write_text(desired_json, encoding="utf-8")
440
+ # `summary["changed"]` is a boolean in the CLI's payload, not a list of
441
+ # names. Report which artefacts this call rewrote rather than passing that
442
+ # flag through as if it were the answer.
443
+ return list(INDEX_ARTIFACTS) if payload["summary"].get("changed") else []