@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,644 @@
1
+ #!/usr/bin/env python3
2
+ """adr-migrate: plan or apply safe ADR metadata and profile migrations.
3
+
4
+ Migration preserves decision prose and invariant sections. For recognizable
5
+ legacy filenames it can also normalize the H1 and supported profile extensions
6
+ so the reported rename produces a strict-lintable ADR.
7
+
8
+ Usage:
9
+ adr-migrate # migrate docs/adr/
10
+ adr-migrate docs/decisions/ # migrate a directory
11
+ adr-migrate docs/adr/ADR-001-x.md # migrate one file
12
+ adr-migrate --plan docs/adr/ # detect formats; never write
13
+ adr-migrate --check docs/adr/ # exit 1 when any file needs migration
14
+ adr-migrate --dry-run --format json docs/adr/
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import argparse
20
+ import importlib.machinery
21
+ import importlib.util
22
+ import json
23
+ import re
24
+ import sys
25
+ from pathlib import Path
26
+ from typing import Dict, List
27
+
28
+ _BIN_DIR = Path(__file__).resolve().parent
29
+
30
+
31
+ def _load_sibling(name: str):
32
+ """Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
33
+
34
+ SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
35
+ of the standard library for every import, so a module committed next to
36
+ this script executed as code -- and it re-added the very directory
37
+ CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
38
+ sys.modules under their bare name, so the plain `from adr_* import ...`
39
+ statements below (and the lazy ones inside functions) resolve from the
40
+ cache instead of the path. bin/adr-judge carries the full rationale.
41
+ """
42
+ cached = sys.modules.get(name)
43
+ if cached is not None:
44
+ return cached
45
+ loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
46
+ spec = importlib.util.spec_from_loader(name, loader)
47
+ module = importlib.util.module_from_spec(spec)
48
+ sys.modules[name] = module
49
+ loader.exec_module(module)
50
+ return module
51
+
52
+
53
+ # Dependency order: adr_catalog imports adr_format and adr_schema.
54
+ _load_sibling("adr_format")
55
+ _load_sibling("adr_schema")
56
+ _load_sibling("adr_catalog")
57
+
58
+ from adr_format import (
59
+ AdrFormatError,
60
+ classify_format,
61
+ convert_profile,
62
+ is_migration_candidate,
63
+ migration_notice,
64
+ normalize_profile,
65
+ )
66
+ from adr_schema import migrate_text
67
+ from adr_catalog import load_adr_record
68
+
69
+
70
+ ADR_FILE_RE = re.compile(r"(?i)^ADR-\d{1,4}-.*\.md$")
71
+ SUGGESTION_STOP_WORDS = {
72
+ "adopt",
73
+ "and",
74
+ "for",
75
+ "from",
76
+ "into",
77
+ "the",
78
+ "use",
79
+ "with",
80
+ }
81
+
82
+
83
+ def discover_files(target: Path) -> List[Path]:
84
+ if target.is_file():
85
+ return [target]
86
+ if not target.is_dir():
87
+ return []
88
+ return sorted(
89
+ (path for path in target.glob("ADR-*.md") if ADR_FILE_RE.match(path.name)),
90
+ key=lambda p: p.name.lower(),
91
+ )
92
+
93
+
94
+ def discover_plan_files(target: Path) -> List[Path]:
95
+ """Find canonical and recognizable legacy ADR files for read-only planning."""
96
+ if target.is_file():
97
+ return [target]
98
+ if not target.is_dir():
99
+ return []
100
+ candidates: List[Path] = []
101
+ for path in sorted(target.glob("*.md"), key=lambda p: p.name.lower()):
102
+ try:
103
+ text = path.read_text(encoding="utf-8", errors="replace")
104
+ except OSError:
105
+ if ADR_FILE_RE.match(path.name):
106
+ candidates.append(path)
107
+ continue
108
+ if is_migration_candidate(path, text):
109
+ candidates.append(path)
110
+ return candidates
111
+
112
+
113
+ def plan_file(path: Path) -> Dict:
114
+ try:
115
+ before = path.read_text(encoding="utf-8", errors="replace")
116
+ except OSError as exc:
117
+ notice = {
118
+ "file": str(path),
119
+ "detected_format": "unknown",
120
+ "supported": False,
121
+ "deterministic": False,
122
+ "action": "guided-migration",
123
+ "message": f"Could not read ADR: {exc}",
124
+ "preview_command": None,
125
+ "apply_command": None,
126
+ "guided_command": None,
127
+ "rename_to": None,
128
+ "metadata_change": False,
129
+ "metadata_issues": [str(exc)],
130
+ "writes_automatically": False,
131
+ }
132
+ return {
133
+ "file": str(path),
134
+ "detected_format": "unknown",
135
+ "notice": notice,
136
+ }
137
+ _after, changed, issues = migrate_text(before, path)
138
+ return {
139
+ "file": str(path),
140
+ "detected_format": classify_format(before),
141
+ "notice": migration_notice(
142
+ before,
143
+ path,
144
+ metadata_changed=changed,
145
+ metadata_issues=issues,
146
+ migrate_command=str(Path(__file__).resolve()),
147
+ ),
148
+ }
149
+
150
+
151
+ def migrate_file(
152
+ path: Path,
153
+ write: bool,
154
+ to_profile: str | None = None,
155
+ from_profile: str | None = None,
156
+ ) -> Dict:
157
+ try:
158
+ before = path.read_text(encoding="utf-8")
159
+ except OSError as exc:
160
+ return {
161
+ "file": str(path),
162
+ "changed": False,
163
+ "ok": False,
164
+ "issues": [str(exc)],
165
+ }
166
+
167
+ after, changed, issues = migrate_text(before, path)
168
+ detected_source = None
169
+ if not issues and to_profile is not None:
170
+ try:
171
+ after, detected_source = convert_profile(
172
+ after, to_profile, source=from_profile
173
+ )
174
+ changed = after != before
175
+ except AdrFormatError as exc:
176
+ issues = [str(exc)]
177
+ if not issues and changed and write:
178
+ try:
179
+ path.write_text(after, encoding="utf-8")
180
+ except OSError as exc:
181
+ return {
182
+ "file": str(path),
183
+ "changed": False,
184
+ "ok": False,
185
+ "issues": [str(exc)],
186
+ }
187
+
188
+ return {
189
+ "file": str(path),
190
+ "changed": changed,
191
+ "ok": not issues,
192
+ "issues": issues,
193
+ "source_profile": detected_source,
194
+ "target_profile": to_profile,
195
+ }
196
+
197
+
198
+ def render_text(target: Path, results: List[Dict], check: bool, dry_run: bool) -> str:
199
+ changed = [r for r in results if r["changed"]]
200
+ failed = [r for r in results if not r["ok"]]
201
+ mode = "check" if check else ("dry-run" if dry_run else "write")
202
+ lines = [
203
+ f"adr-migrate {mode}: {target}",
204
+ f"Files: {len(results)}; changed: {len(changed)}; failed: {len(failed)}",
205
+ ]
206
+ for result in results:
207
+ if result["changed"]:
208
+ prefix = "needs migration" if check or dry_run else "migrated"
209
+ lines.append(f" {prefix}: {result['file']}")
210
+ if result["issues"]:
211
+ lines.append(f" failed: {result['file']}")
212
+ for issue in result["issues"]:
213
+ lines.append(f" {issue}")
214
+ if not results:
215
+ lines.append("No ADR files found.")
216
+ return "\n".join(lines)
217
+
218
+
219
+ def render_plan_text(target: Path, scanned: List[Dict]) -> str:
220
+ notices = [item["notice"] for item in scanned if item["notice"] is not None]
221
+ deterministic = [item for item in notices if item["deterministic"]]
222
+ guided = [item for item in notices if not item["deterministic"]]
223
+ formats: Dict[str, int] = {}
224
+ for item in scanned:
225
+ profile = item["detected_format"]
226
+ formats[profile] = formats.get(profile, 0) + 1
227
+
228
+ lines = [
229
+ f"adr-migrate plan: {target}",
230
+ (
231
+ f"Files scanned: {len(scanned)}; notices: {len(notices)}; "
232
+ f"deterministic: {len(deterministic)}; guided: {len(guided)}"
233
+ ),
234
+ ]
235
+ if formats:
236
+ lines.append(
237
+ "Detected formats: "
238
+ + ", ".join(f"{name}={formats[name]}" for name in sorted(formats))
239
+ )
240
+ for notice in notices:
241
+ mode = "deterministic" if notice["deterministic"] else "guided"
242
+ lines.append(
243
+ f" {notice['detected_format']} ({mode}): {notice['file']}"
244
+ )
245
+ lines.append(f" {notice['message']}")
246
+ if notice.get("preview_command"):
247
+ lines.append(f" preview: {notice['preview_command']}")
248
+ if notice.get("rename_to"):
249
+ lines.append(
250
+ " after approved migration, rename to: "
251
+ + notice["rename_to"]
252
+ )
253
+ if notice.get("guided_command"):
254
+ lines.append(f" next: {notice['guided_command']}")
255
+ if not notices:
256
+ lines.append("No migration notices.")
257
+ lines.append("No files changed. Migration is never automatic.")
258
+ return "\n".join(lines)
259
+
260
+
261
+ def suggest_retrieval_file(path: Path) -> Dict:
262
+ """Derive review-only retrieval candidates from existing ADR evidence."""
263
+ try:
264
+ record = load_adr_record(path)
265
+ except (OSError, UnicodeError, ValueError) as exc:
266
+ return {
267
+ "file": str(path),
268
+ "ok": False,
269
+ "issues": [str(exc)],
270
+ "requires_human_approval": True,
271
+ "writes_automatically": False,
272
+ }
273
+ title_topics = [
274
+ token
275
+ for token in re.findall(r"[A-Za-z0-9][A-Za-z0-9_.-]{2,}", record["title"])
276
+ if token.casefold() not in SUGGESTION_STOP_WORDS
277
+ ][:8]
278
+ path_components = []
279
+ symbol_candidates = []
280
+ for pointer in record.get("verified_in", []):
281
+ path_part, separator, symbol = pointer.partition(":")
282
+ if separator and symbol and not re.match(r"^[A-Za-z]$", path_part):
283
+ symbol_candidates.append(symbol)
284
+ parts = Path(path_part.replace("\\", "/")).parts
285
+ if parts:
286
+ path_components.append(parts[0])
287
+ for pattern in record.get("scope", []):
288
+ parts = Path(pattern.replace("\\", "/")).parts
289
+ if parts and not parts[0].startswith("*"):
290
+ path_components.append(parts[0])
291
+ existing = {
292
+ field: list(record.get(field, []))
293
+ for field in ("topics", "aliases", "components", "symbols")
294
+ }
295
+ contract = record.get("decision_contract", {})
296
+ has_contract = any(contract.get(key) for key in contract)
297
+ candidates = {
298
+ "topics": existing["topics"] or sorted(
299
+ set(title_topics), key=lambda value: (value.casefold(), value)
300
+ ),
301
+ "aliases": existing["aliases"],
302
+ "components": existing["components"] or sorted(
303
+ set(path_components), key=lambda value: (value.casefold(), value)
304
+ )[:8],
305
+ "symbols": existing["symbols"] or sorted(
306
+ set(symbol_candidates), key=lambda value: (value.casefold(), value)
307
+ )[:8],
308
+ "context_scope": record.get("context_scope", "selective"),
309
+ }
310
+ decision_contract = contract if has_contract else {
311
+ "must": [record["decision"]] if record.get("decision") else [],
312
+ "must_not": [],
313
+ "exceptions": [],
314
+ "verification": [
315
+ *(
316
+ [f"Run the named gate: {record['gate']}"]
317
+ if record.get("gate")
318
+ else []
319
+ ),
320
+ *[f"Verify: {pointer}" for pointer in record.get("verified_in", [])[:8]],
321
+ ],
322
+ }
323
+ return {
324
+ "file": str(path),
325
+ "adr_id": record["adr_id"],
326
+ "ok": True,
327
+ "status": record["status"],
328
+ "binding": record["binding"],
329
+ "existing": {**existing, "decision_contract": contract},
330
+ "suggested": {
331
+ **candidates,
332
+ "decision_contract": decision_contract,
333
+ },
334
+ "source_evidence": {
335
+ "title": record["title"],
336
+ "decision_summary": record["decision"],
337
+ "scope": record["scope"],
338
+ "verified_in": record["verified_in"],
339
+ "gate": record["gate"],
340
+ },
341
+ "requires_human_approval": True,
342
+ "writes_automatically": False,
343
+ "warning": (
344
+ "Candidates are derived from existing text and paths; a human must "
345
+ "confirm meaning before editing the ADR."
346
+ ),
347
+ }
348
+
349
+
350
+ def render_retrieval_suggestions(target: Path, results: List[Dict]) -> str:
351
+ lines = [
352
+ f"adr-migrate retrieval dry-run: {target}",
353
+ f"Files: {len(results)}; suggestions: {sum(item.get('ok', False) for item in results)}",
354
+ ]
355
+ for item in results:
356
+ if not item.get("ok"):
357
+ lines.append(f" failed: {item['file']}: {item.get('issues', [])}")
358
+ continue
359
+ suggested = item["suggested"]
360
+ lines.append(f" {item['adr_id']}: {item['file']}")
361
+ lines.append(f" topics: {suggested['topics']}")
362
+ lines.append(f" components: {suggested['components']}")
363
+ lines.append(f" symbols: {suggested['symbols']}")
364
+ lines.append(
365
+ " Decision Contract candidate items: "
366
+ + str(sum(len(values) for values in suggested["decision_contract"].values()))
367
+ )
368
+ lines.append("No files changed. Every candidate requires human approval.")
369
+ return "\n".join(lines)
370
+
371
+
372
+ def main(argv: List[str] | None = None) -> int:
373
+ parser = argparse.ArgumentParser(
374
+ prog="adr-migrate",
375
+ description="Add canonical adr-kit frontmatter to ADR files.",
376
+ )
377
+ parser.add_argument(
378
+ "path",
379
+ nargs="?",
380
+ default="docs/adr",
381
+ help="ADR file or directory (default: docs/adr)",
382
+ )
383
+ parser.add_argument(
384
+ "--check",
385
+ action="store_true",
386
+ help="do not write; exit 1 if any ADR needs migration",
387
+ )
388
+ parser.add_argument(
389
+ "--plan",
390
+ action="store_true",
391
+ help="detect supported and legacy formats; report migration advice; never write",
392
+ )
393
+ parser.add_argument(
394
+ "--dry-run",
395
+ action="store_true",
396
+ help="do not write; report what would change",
397
+ )
398
+ parser.add_argument(
399
+ "--format",
400
+ choices=["text", "json"],
401
+ default="text",
402
+ help="output format (default: text)",
403
+ )
404
+ parser.add_argument(
405
+ "--to-profile",
406
+ choices=["madr", "nygard", "canonical"],
407
+ default=None,
408
+ help="also convert supported body headings to this profile",
409
+ )
410
+ parser.add_argument(
411
+ "--from-profile",
412
+ choices=["madr", "nygard", "canonical"],
413
+ default=None,
414
+ help="explicit source profile for an unknown or hybrid document",
415
+ )
416
+ parser.add_argument(
417
+ "--suggest-retrieval",
418
+ action="store_true",
419
+ help=(
420
+ "with --dry-run, suggest selective metadata and Decision Contract "
421
+ "candidates from existing ADR evidence; never writes"
422
+ ),
423
+ )
424
+ parser.add_argument(
425
+ "--enable-llm-judge",
426
+ action="store_true",
427
+ help=(
428
+ "opt-out migration for the LLM judge: drop the legacy "
429
+ "llm_judge:false from every Accepted ADR so the true default "
430
+ "applies. An ADR with no Enforcement rules has no scope to narrow "
431
+ "with, so it is marked no-code-surface instead of becoming a call "
432
+ "on every commit; override that per ADR with --force-enable."
433
+ ),
434
+ )
435
+ parser.add_argument(
436
+ "--except",
437
+ dest="opt_out",
438
+ default="",
439
+ metavar="ADR-002,ADR-004",
440
+ help="with --enable-llm-judge: ADRs to opt out; needs --reason",
441
+ )
442
+ parser.add_argument(
443
+ "--force-enable",
444
+ dest="force_enable",
445
+ default="",
446
+ metavar="ADR-014",
447
+ help=(
448
+ "with --enable-llm-judge: enable a rule-less ADR anyway, "
449
+ "accepting one model call on every commit until it declares a scope"
450
+ ),
451
+ )
452
+ parser.add_argument(
453
+ "--reason",
454
+ default="",
455
+ help="with --except: why the LLM pass stays off, recorded in the ADR",
456
+ )
457
+ args = parser.parse_args(argv)
458
+
459
+ if args.enable_llm_judge and (
460
+ args.plan or args.check or args.to_profile or args.from_profile
461
+ or args.suggest_retrieval
462
+ ):
463
+ parser.error(
464
+ "--enable-llm-judge cannot be combined with --plan, --check, "
465
+ "--to-profile, --from-profile, or --suggest-retrieval"
466
+ )
467
+ if (args.opt_out or args.force_enable or args.reason) and not args.enable_llm_judge:
468
+ parser.error(
469
+ "--except, --force-enable and --reason require --enable-llm-judge"
470
+ )
471
+
472
+ if args.plan and (
473
+ args.check or args.dry_run or args.to_profile or args.from_profile
474
+ or args.suggest_retrieval
475
+ ):
476
+ parser.error(
477
+ "--plan cannot be combined with --check, --dry-run, "
478
+ "--to-profile, or --from-profile"
479
+ )
480
+ if args.suggest_retrieval and (
481
+ not args.dry_run
482
+ or args.check
483
+ or args.to_profile
484
+ or args.from_profile
485
+ ):
486
+ parser.error(
487
+ "--suggest-retrieval requires --dry-run and cannot be combined "
488
+ "with --check, --to-profile, or --from-profile"
489
+ )
490
+
491
+ target = Path(args.path)
492
+ if args.enable_llm_judge:
493
+ migration = _load_sibling("adr_llm_judge_migration")
494
+ adr_dir = target if target.is_dir() else target.parent
495
+ split = lambda raw: [p.strip() for p in raw.split(",") if p.strip()]
496
+ try:
497
+ result = migration.apply(
498
+ adr_dir,
499
+ opt_out_ids=split(args.opt_out),
500
+ force_enable_ids=split(args.force_enable),
501
+ opt_out_reason=args.reason,
502
+ dry_run=args.dry_run,
503
+ )
504
+ except ValueError as exc:
505
+ print(f"[adr-migrate] ERROR: {exc}", file=sys.stderr)
506
+ return 2
507
+ if args.format == "json":
508
+ print(json.dumps(result, indent=2, ensure_ascii=False))
509
+ else:
510
+ verb = "would enable" if args.dry_run else "enabled"
511
+ print(f"LLM judge {verb}: {len(result['enabled'])} ADR(s)")
512
+ for row in result["enabled"]:
513
+ note = " (no scope declared: judged on every commit)" if row["unbounded_scope"] else ""
514
+ print(f" + {row['adr']} ({row['rules']} rule(s)){note}")
515
+ if result["opted_out"]:
516
+ verb = "would stay off" if args.dry_run else "left off"
517
+ print(f"LLM judge {verb}: {len(result['opted_out'])} ADR(s)")
518
+ for row in result["opted_out"]:
519
+ print(f" - {row['adr']}: {row['reason']}")
520
+ if not result["enabled"] and not result["opted_out"]:
521
+ print("Nothing to change; every ADR already carries a decision.")
522
+ # The whole-set cost picture, not just this run's delta. On an
523
+ # upgraded repository the already-enabled ADRs dominate, and every
524
+ # unscoped one costs an isolated model call per commit (TASK-63),
525
+ # so the delta alone reads as cost-free when the pass is anything
526
+ # but: one operator accepted a "0 unbounded" dry-run on a set that
527
+ # ended at 64 unscoped of 68 judged, at ~20 s per call.
528
+ summary = result.get("summary") or {}
529
+ judged = summary.get("judged_after", 0)
530
+ unbounded = summary.get("unbounded_after", 0)
531
+ tense = "would judge" if args.dry_run else "judges"
532
+ print(
533
+ f"LLM pass after this migration {tense}: {judged} ADR(s), "
534
+ f"{unbounded} without any path_glob"
535
+ )
536
+ if unbounded:
537
+ print(
538
+ " An unscoped ADR is in scope on EVERY commit, one "
539
+ "isolated call each. Narrow them with path_glob rules, or "
540
+ "run the LLM pass on a cadence (guardian llm tier) instead "
541
+ "of per commit."
542
+ )
543
+ return 0
544
+
545
+ if args.plan:
546
+ scanned = [plan_file(path) for path in discover_plan_files(target)]
547
+ notices = [
548
+ item["notice"] for item in scanned if item["notice"] is not None
549
+ ]
550
+ deterministic = [item for item in notices if item["deterministic"]]
551
+ guided = [item for item in notices if not item["deterministic"]]
552
+ formats: Dict[str, int] = {}
553
+ for item in scanned:
554
+ profile = item["detected_format"]
555
+ formats[profile] = formats.get(profile, 0) + 1
556
+ payload = {
557
+ "target": str(target),
558
+ "mode": "plan",
559
+ "read_only": True,
560
+ "summary": {
561
+ "total": len(scanned),
562
+ "notices": len(notices),
563
+ "deterministic": len(deterministic),
564
+ "guided": len(guided),
565
+ "formats": formats,
566
+ },
567
+ "files": notices,
568
+ }
569
+ if args.format == "json":
570
+ print(json.dumps(payload, indent=2))
571
+ else:
572
+ print(render_plan_text(target, scanned))
573
+ return 0
574
+
575
+ if args.suggest_retrieval:
576
+ results = [
577
+ suggest_retrieval_file(path)
578
+ for path in discover_files(target)
579
+ ]
580
+ payload = {
581
+ "target": str(target),
582
+ "mode": "retrieval-suggestions",
583
+ "read_only": True,
584
+ "requires_human_approval": True,
585
+ "writes_automatically": False,
586
+ "summary": {
587
+ "total": len(results),
588
+ "suggestions": sum(item.get("ok", False) for item in results),
589
+ "failed": sum(not item.get("ok", False) for item in results),
590
+ },
591
+ "files": results,
592
+ }
593
+ if args.format == "json":
594
+ print(json.dumps(payload, indent=2))
595
+ else:
596
+ print(render_retrieval_suggestions(target, results))
597
+ return 2 if payload["summary"]["failed"] else 0
598
+
599
+ files = discover_files(target)
600
+ write = not args.check and not args.dry_run
601
+ try:
602
+ to_profile = (
603
+ normalize_profile(args.to_profile) if args.to_profile else None
604
+ )
605
+ except AdrFormatError as exc:
606
+ print(f"adr-migrate: {exc}", file=sys.stderr)
607
+ return 2
608
+ results = [
609
+ migrate_file(
610
+ path,
611
+ write=write,
612
+ to_profile=to_profile,
613
+ from_profile=args.from_profile,
614
+ )
615
+ for path in files
616
+ ]
617
+
618
+ failed = [r for r in results if not r["ok"]]
619
+ changed = [r for r in results if r["changed"]]
620
+ payload = {
621
+ "target": str(target),
622
+ "mode": "check" if args.check else ("dry-run" if args.dry_run else "write"),
623
+ "summary": {
624
+ "total": len(results),
625
+ "changed": len(changed),
626
+ "failed": len(failed),
627
+ },
628
+ "files": results,
629
+ }
630
+
631
+ if args.format == "json":
632
+ print(json.dumps(payload, indent=2))
633
+ else:
634
+ print(render_text(target, results, check=args.check, dry_run=args.dry_run))
635
+
636
+ if failed:
637
+ return 2
638
+ if args.check and changed:
639
+ return 1
640
+ return 0
641
+
642
+
643
+ if __name__ == "__main__":
644
+ sys.exit(main())