@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.
- package/.claude-plugin/plugin.json +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
package/bin/adr-migrate
ADDED
|
@@ -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())
|