@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,323 @@
1
+ #!/usr/bin/env python3
2
+ """Certify deterministic ADR Grilling paths against their latency budgets."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import platform
9
+ import statistics
10
+ import subprocess
11
+ import sys
12
+ import tempfile
13
+ import time
14
+ from datetime import date
15
+ from pathlib import Path
16
+
17
+ ROOT = Path(__file__).resolve().parents[1]
18
+ BIN = ROOT / "bin"
19
+ sys.path.insert(0, str(BIN))
20
+
21
+ from adr_readiness import build_readiness_report # noqa: E402
22
+ from adr_schema import render_frontmatter # noqa: E402
23
+
24
+
25
+ def _fixture(root: Path, count: int = 50) -> Path:
26
+ adr_dir = root / "docs" / "adr"
27
+ adr_dir.mkdir(parents=True)
28
+ (root / "src").mkdir()
29
+ for number in range(1, count + 1):
30
+ path = f"src/component-{number:03d}.py"
31
+ (root / path).write_text("VALUE = 1\n", encoding="utf-8")
32
+ metadata = {
33
+ "id": f"ADR-{number:03d}",
34
+ "title": f"Decision {number}",
35
+ "status": "Proposed",
36
+ "date": "2026-07-20",
37
+ "binding": False,
38
+ "gate": None,
39
+ "documents_shipped": number % 3 == 0,
40
+ "verified_in": [path],
41
+ "supersedes": [],
42
+ "superseded_by": None,
43
+ "format": "madr",
44
+ }
45
+ body = (
46
+ f"# ADR-{number:03d} Decision {number}\n\n"
47
+ "## Status\n\nProposed, 2026-07-20.\n\n"
48
+ "## Context and Problem Statement\n\nA stable choice is required.\n\n"
49
+ "## Decision Drivers\n\n* Determinism.\n\n"
50
+ "## Considered Options\n\n* Local.\n* Hosted.\n\n"
51
+ "## Decision Outcome\n\nChosen option: **Local**, because it is bounded.\n\n"
52
+ "## Consequences\n\nThe local implementation must be maintained.\n\n"
53
+ "## Open Questions\n\nNone.\n\n"
54
+ "## Related Decisions\n\n* None.\n\n"
55
+ f"## References\n\n* {path}:1\n"
56
+ )
57
+ (adr_dir / f"ADR-{number:03d}-decision-{number}.md").write_text(
58
+ render_frontmatter(metadata) + body, encoding="utf-8"
59
+ )
60
+ return adr_dir
61
+
62
+
63
+ def _measure(operation, samples: int) -> dict[str, float | int]:
64
+ operation()
65
+ values = []
66
+ for _ in range(samples):
67
+ started = time.perf_counter_ns()
68
+ operation()
69
+ values.append((time.perf_counter_ns() - started) / 1_000_000)
70
+ ordered = sorted(values)
71
+ p95_index = max(0, min(len(ordered) - 1, int(len(ordered) * 0.95) - 1))
72
+ return {
73
+ "samples": samples,
74
+ "median_ms": round(statistics.median(ordered), 3),
75
+ "p50_ms": round(statistics.median(ordered), 3),
76
+ "p95_ms": round(ordered[p95_index], 3),
77
+ "max_ms": round(max(ordered), 3),
78
+ }
79
+
80
+
81
+ def _run(command: list[str], cwd: Path, *, input_text: str | None = None) -> bytes:
82
+ result = subprocess.run(
83
+ command,
84
+ cwd=cwd,
85
+ input=input_text,
86
+ capture_output=True,
87
+ text=True,
88
+ encoding="utf-8",
89
+ timeout=10,
90
+ )
91
+ if result.returncode != 0:
92
+ raise RuntimeError(result.stderr or result.stdout)
93
+ return result.stdout.encode("utf-8")
94
+
95
+
96
+ def benchmark(samples: int) -> dict:
97
+ with tempfile.TemporaryDirectory(prefix="adr-grilling-benchmark-") as raw:
98
+ root = Path(raw)
99
+ adr_dir = _fixture(root)
100
+ changed = [f"src/change-{index:03d}.py" for index in range(500)]
101
+ source = "\n".join(f"implements ADR-{number:03d}" for number in range(1, 51))
102
+ for index, path in enumerate(changed):
103
+ (root / path).write_text(f"VALUE = {index}\n", encoding="utf-8")
104
+ _run(["git", "init"], root)
105
+ _run(["git", "config", "user.email", "benchmark@example.com"], root)
106
+ _run(["git", "config", "user.name", "ADR Kit Benchmark"], root)
107
+ _run(["git", "add", "."], root)
108
+ _run(["git", "commit", "-m", "benchmark base"], root)
109
+ base = _run(["git", "rev-parse", "HEAD"], root).decode().strip()
110
+ for index, path in enumerate(changed):
111
+ adr_number = (index % 50) + 1
112
+ (root / path).write_text(
113
+ f"VALUE = {index + 1} # implements ADR-{adr_number:03d}\n",
114
+ encoding="utf-8",
115
+ )
116
+ _run(["git", "add", "src"], root)
117
+ _run(["git", "commit", "-m", "benchmark head"], root)
118
+ head = _run(["git", "rev-parse", "HEAD"], root).decode().strip()
119
+
120
+ core = lambda: build_readiness_report( # noqa: E731
121
+ adr_dir, evaluated_on=date(2026, 7, 20), all_proposed=True
122
+ )
123
+ linkage = lambda: build_readiness_report( # noqa: E731
124
+ adr_dir,
125
+ evaluated_on=date(2026, 7, 20),
126
+ all_proposed=True,
127
+ changed_paths=changed,
128
+ source_text=source,
129
+ )
130
+ single_cli = lambda: _run( # noqa: E731
131
+ [
132
+ sys.executable,
133
+ str(BIN / "adr-readiness"),
134
+ "ADR-001",
135
+ "--repo-root",
136
+ str(root),
137
+ "--today",
138
+ "2026-07-20",
139
+ "--format",
140
+ "json",
141
+ ],
142
+ root,
143
+ )
144
+ all_cli = lambda: _run( # noqa: E731
145
+ [
146
+ sys.executable,
147
+ str(BIN / "adr-readiness"),
148
+ "--all-proposed",
149
+ "--repo-root",
150
+ str(root),
151
+ "--today",
152
+ "2026-07-20",
153
+ "--format",
154
+ "json",
155
+ ],
156
+ root,
157
+ )
158
+ status_cli = lambda: _run( # noqa: E731
159
+ [
160
+ sys.executable,
161
+ str(BIN / "adr-status"),
162
+ "--adr-dir",
163
+ str(adr_dir),
164
+ "--format",
165
+ "json",
166
+ ],
167
+ root,
168
+ )
169
+ context_cli = lambda: _run( # noqa: E731
170
+ [
171
+ sys.executable,
172
+ str(BIN / "adr-context"),
173
+ "--adr-dir",
174
+ str(adr_dir),
175
+ "--format",
176
+ "json",
177
+ "local decision",
178
+ ],
179
+ root,
180
+ )
181
+
182
+ def ci_action() -> bytes:
183
+ result = subprocess.run(
184
+ [
185
+ sys.executable,
186
+ str(BIN / "adr-readiness-ci"),
187
+ "--repo-root",
188
+ str(root),
189
+ "--base",
190
+ base,
191
+ "--head",
192
+ head,
193
+ "--today",
194
+ "2026-07-20",
195
+ ],
196
+ cwd=root,
197
+ capture_output=True,
198
+ text=True,
199
+ encoding="utf-8",
200
+ timeout=10,
201
+ )
202
+ if result.returncode not in (0, 1):
203
+ raise RuntimeError(result.stderr or result.stdout)
204
+ return result.stdout.encode("utf-8")
205
+ request = json.dumps(
206
+ {
207
+ "jsonrpc": "2.0",
208
+ "id": 1,
209
+ "method": "tools/call",
210
+ "params": {
211
+ "name": "adr_readiness",
212
+ "arguments": {
213
+ "all_proposed": True,
214
+ "today": "2026-07-20",
215
+ },
216
+ },
217
+ }
218
+ )
219
+ server = subprocess.Popen(
220
+ [
221
+ sys.executable,
222
+ str(BIN / "adr-mcp"),
223
+ "--root",
224
+ str(root),
225
+ ],
226
+ cwd=root,
227
+ stdin=subprocess.PIPE,
228
+ stdout=subprocess.PIPE,
229
+ stderr=subprocess.DEVNULL,
230
+ text=True,
231
+ encoding="utf-8",
232
+ )
233
+
234
+ def mcp() -> str:
235
+ assert server.stdin is not None and server.stdout is not None
236
+ server.stdin.write(request + "\n")
237
+ server.stdin.flush()
238
+ line = server.stdout.readline()
239
+ if not line:
240
+ raise RuntimeError("adr-mcp closed before returning a response")
241
+ payload = json.loads(line)
242
+ if "error" in payload:
243
+ raise RuntimeError(str(payload["error"]))
244
+ return line
245
+
246
+ try:
247
+ measurements = {
248
+ "core_50_adrs": _measure(core, samples),
249
+ "linkage_500_paths_50_adrs": _measure(linkage, samples),
250
+ "single_adr_cli": _measure(single_cli, samples),
251
+ "all_proposed_cli": _measure(all_cli, samples),
252
+ "mcp_all_proposed": _measure(mcp, samples),
253
+ "baseline_adr_status": _measure(status_cli, samples),
254
+ "baseline_adr_context": _measure(context_cli, samples),
255
+ "ci_action_500_paths_50_adrs": _measure(ci_action, samples),
256
+ }
257
+ finally:
258
+ if server.stdin is not None:
259
+ server.stdin.close()
260
+ server.wait(timeout=5)
261
+ measurements["mcp_all_proposed"]["adapter_overhead_ms"] = round(
262
+ float(measurements["mcp_all_proposed"]["p95_ms"])
263
+ - float(measurements["all_proposed_cli"]["p95_ms"]),
264
+ 3,
265
+ )
266
+ budgets = {
267
+ "core_50_adrs": 100,
268
+ "linkage_500_paths_50_adrs": 250,
269
+ "single_adr_cli": 500,
270
+ "all_proposed_cli": 1000,
271
+ "ci_action_500_paths_50_adrs": 5000,
272
+ }
273
+ results = {
274
+ name: {
275
+ "budget_p95_ms": budget,
276
+ "passed": float(measurements[name]["p95_ms"]) <= budget,
277
+ }
278
+ for name, budget in budgets.items()
279
+ }
280
+ results["all_proposed_hard"] = {
281
+ "budget_max_ms": 2000,
282
+ "passed": float(measurements["all_proposed_cli"]["max_ms"]) <= 2000,
283
+ }
284
+ results["linkage_hard"] = {
285
+ "budget_max_ms": 1000,
286
+ "passed": float(
287
+ measurements["linkage_500_paths_50_adrs"]["max_ms"]
288
+ )
289
+ <= 1000,
290
+ }
291
+ results["mcp_overhead"] = {
292
+ "budget_ms": 100,
293
+ "passed": float(
294
+ measurements["mcp_all_proposed"]["adapter_overhead_ms"]
295
+ )
296
+ <= 100,
297
+ }
298
+ return {
299
+ "schema_version": 1,
300
+ "environment": {
301
+ "platform": platform.platform(),
302
+ "python": platform.python_version(),
303
+ },
304
+ "fixture": {"adrs": 50, "changed_paths": 500},
305
+ "measurements": measurements,
306
+ "results": results,
307
+ "passed": all(item["passed"] for item in results.values()),
308
+ }
309
+
310
+
311
+ def main() -> int:
312
+ parser = argparse.ArgumentParser(description=__doc__)
313
+ parser.add_argument("--samples", type=int, default=30)
314
+ args = parser.parse_args()
315
+ if args.samples < 1:
316
+ parser.error("--samples must be positive")
317
+ report = benchmark(args.samples)
318
+ print(json.dumps(report, indent=2, sort_keys=True))
319
+ return 0 if report["passed"] else 1
320
+
321
+
322
+ if __name__ == "__main__":
323
+ raise SystemExit(main())
@@ -0,0 +1,178 @@
1
+ #!/usr/bin/env python3
2
+ """Measure clean and warm deterministic client generation."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import math
9
+ import os
10
+ import statistics
11
+ import subprocess
12
+ import sys
13
+ import tempfile
14
+ import time
15
+ import tracemalloc
16
+ from pathlib import Path
17
+
18
+ ROOT = Path(__file__).resolve().parent.parent
19
+ BUILD = ROOT / "scripts" / "build-client-adapters.py"
20
+ BASELINE = json.loads(
21
+ (ROOT / "packaging" / "client-generation-baseline.json").read_text(
22
+ encoding="utf-8"
23
+ )
24
+ )
25
+ BASELINE_P95_MS = BASELINE["p95_ms"]
26
+ sys.path.insert(0, str(ROOT / "scripts"))
27
+ from client_generation import generate # noqa: E402
28
+
29
+
30
+ def percentile(values: list[float], fraction: float) -> float:
31
+ return sorted(values)[max(0, math.ceil(fraction * len(values)) - 1)]
32
+
33
+
34
+ def invoke(output: Path, check: bool, timeout: float) -> tuple[float, dict]:
35
+ command = [
36
+ sys.executable,
37
+ str(BUILD),
38
+ "--root",
39
+ str(ROOT),
40
+ "--output-root",
41
+ str(output),
42
+ "--format",
43
+ "json",
44
+ ]
45
+ if check:
46
+ command.append("--check")
47
+ started = time.perf_counter()
48
+ result = subprocess.run(
49
+ command, capture_output=True, text=True, encoding="utf-8", timeout=timeout
50
+ )
51
+ elapsed = (time.perf_counter() - started) * 1000
52
+ if result.returncode:
53
+ raise RuntimeError(result.stdout + result.stderr)
54
+ return elapsed, json.loads(result.stdout)
55
+
56
+
57
+ def summarize(samples: list[tuple[float, dict]], state: str) -> dict:
58
+ elapsed = [sample[0] for sample in samples]
59
+ stats = [sample[1]["stats"] for sample in samples]
60
+ return {
61
+ "state": state,
62
+ "sample_count": len(samples),
63
+ "process_startup_included": state == "clean-full",
64
+ "elapsed_ms": {
65
+ "p50": round(statistics.median(elapsed), 3),
66
+ "p95": round(percentile(elapsed, 0.95), 3),
67
+ "max": round(max(elapsed), 3),
68
+ },
69
+ "files_read": max(item["files_read"] for item in stats),
70
+ "bytes_read": max(item["bytes_read"] for item in stats),
71
+ "files_written": max(item["files_written"] for item in stats),
72
+ "bytes_written": max(item["bytes_written"] for item in stats),
73
+ }
74
+
75
+
76
+ def invoke_warm(output: Path) -> tuple[float, dict]:
77
+ started = time.perf_counter()
78
+ stats, drift = generate(ROOT, output, check=False)
79
+ elapsed = (time.perf_counter() - started) * 1000
80
+ if drift:
81
+ raise RuntimeError("warm generation unexpectedly drifted")
82
+ return elapsed, {"stats": stats.as_dict()}
83
+
84
+
85
+ def startup_calibration(samples: int) -> dict:
86
+ values = []
87
+ for _ in range(samples):
88
+ started = time.perf_counter()
89
+ subprocess.run([sys.executable, "-c", "pass"], check=True)
90
+ values.append((time.perf_counter() - started) * 1000)
91
+ return {
92
+ "sample_count": samples,
93
+ "p50_ms": round(statistics.median(values), 3),
94
+ "p95_ms": round(percentile(values, 0.95), 3),
95
+ }
96
+
97
+
98
+ def main(argv: list[str] | None = None) -> int:
99
+ parser = argparse.ArgumentParser()
100
+ parser.add_argument("--samples", type=int, default=11)
101
+ parser.add_argument(
102
+ "--output",
103
+ type=Path,
104
+ default=ROOT / "packaging" / "client-generation-benchmark.json",
105
+ )
106
+ args = parser.parse_args(argv)
107
+ if args.samples < 5:
108
+ parser.error("--samples must be at least 5")
109
+
110
+ clean_samples: list[tuple[float, dict]] = []
111
+ warm_samples: list[tuple[float, dict]] = []
112
+ with tempfile.TemporaryDirectory(prefix="adr-kit-generation-") as temporary:
113
+ workspace = Path(temporary)
114
+ for index in range(args.samples):
115
+ clean_samples.append(invoke(workspace / f"clean-{index:03d}", False, 5.0))
116
+ warm_root = workspace / "warm"
117
+ invoke(warm_root, False, 5.0)
118
+ for _ in range(args.samples):
119
+ warm_samples.append(invoke_warm(warm_root))
120
+ tracemalloc.start()
121
+ invoke_warm(warm_root)
122
+ _, peak = tracemalloc.get_traced_memory()
123
+ tracemalloc.stop()
124
+
125
+ clean = summarize(clean_samples, "clean-full")
126
+ warm = summarize(warm_samples, "warm-unchanged")
127
+ regressions = [
128
+ name
129
+ for name, result in (("clean", clean), ("warm", warm))
130
+ if result["elapsed_ms"]["p95"] > BASELINE_P95_MS[name] * 1.2
131
+ ]
132
+ passed = (
133
+ clean["elapsed_ms"]["p50"] <= 1000
134
+ and clean["elapsed_ms"]["p95"] <= 2000
135
+ and clean["elapsed_ms"]["max"] <= 5000
136
+ and warm["elapsed_ms"]["p50"] <= 150
137
+ and warm["elapsed_ms"]["p95"] <= 500
138
+ and warm["elapsed_ms"]["max"] <= 1000
139
+ and warm["files_written"] == 0
140
+ and not regressions
141
+ )
142
+ evidence = {
143
+ "schema_version": 1,
144
+ "platform": {
145
+ "os": os.name,
146
+ "python": sys.version.split()[0],
147
+ "reference": "windows-native" if os.name == "nt" else "best-effort",
148
+ },
149
+ "methodology": {
150
+ "generator": "scripts/build-client-adapters.py",
151
+ "generator_count": 1,
152
+ "cache": "disposable stat-keyed hot path; byte validation on cache miss",
153
+ "cold_state": "new empty output root per sample",
154
+ "warm_state": "persistent Python host, stat-validated fingerprint no-op",
155
+ "warm_process_startup": "amortized once per persistent agent or release host",
156
+ "hard_timeouts_ms": {"clean": 5000, "warm": 1000},
157
+ },
158
+ "standalone_python_startup": startup_calibration(args.samples),
159
+ "approved_baseline_p95_ms": BASELINE_P95_MS,
160
+ "regression_threshold_percent": BASELINE["regression_threshold_percent"],
161
+ "peak_memory_bytes": peak,
162
+ "clean": clean,
163
+ "warm": warm,
164
+ "regressions": regressions,
165
+ "passed": passed,
166
+ }
167
+ args.output.parent.mkdir(parents=True, exist_ok=True)
168
+ payload = json.dumps(evidence, indent=2, sort_keys=True) + "\n"
169
+ if not args.output.exists() or args.output.read_text(encoding="utf-8") != payload:
170
+ temporary = args.output.with_suffix(args.output.suffix + ".tmp")
171
+ temporary.write_text(payload, encoding="utf-8", newline="\n")
172
+ os.replace(temporary, args.output)
173
+ print(json.dumps(evidence, sort_keys=True))
174
+ return 0 if passed else 1
175
+
176
+
177
+ if __name__ == "__main__":
178
+ raise SystemExit(main())
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env python3
2
+ """Generate or drift-check the three supported ADR Kit client adapters."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import re
9
+ import sys
10
+ import time
11
+ from pathlib import Path
12
+
13
+ from client_generation import GenerationError, generate
14
+ from client_certification import support_matrix, validate
15
+ from client_evidence import CertificationError, assemble_native_bundle, write_bundle
16
+
17
+
18
+ def main(argv: list[str] | None = None) -> int:
19
+ parser = argparse.ArgumentParser()
20
+ parser.add_argument("--check", action="store_true", help="fail when generated files drift")
21
+ parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parent.parent)
22
+ parser.add_argument("--output-root", type=Path)
23
+ parser.add_argument("--format", choices=("human", "json"), default="human")
24
+ parser.add_argument("--certify", type=Path)
25
+ parser.add_argument("--candidate-commit")
26
+ parser.add_argument("--release-candidate", action="store_true")
27
+ parser.add_argument("--support-output", type=Path)
28
+ parser.add_argument(
29
+ "--assemble-native-evidence",
30
+ type=Path,
31
+ metavar="DIRECTORY",
32
+ help="assemble DIRECTORY/{claude,codex,copilot}/windows-native.json",
33
+ )
34
+ parser.add_argument("--evidence-output", type=Path)
35
+ args = parser.parse_args(argv)
36
+ if args.assemble_native_evidence:
37
+ if not args.candidate_commit or not args.evidence_output:
38
+ parser.error(
39
+ "--assemble-native-evidence requires --candidate-commit and "
40
+ "--evidence-output"
41
+ )
42
+ try:
43
+ bundle = assemble_native_bundle(
44
+ args.assemble_native_evidence,
45
+ args.root.resolve(),
46
+ args.candidate_commit,
47
+ )
48
+ matched = write_bundle(args.evidence_output, bundle, args.check)
49
+ except (CertificationError, OSError) as exc:
50
+ result = {"passed": False, "errors": [str(exc)]}
51
+ print(
52
+ json.dumps(result, sort_keys=True)
53
+ if args.format == "json"
54
+ else f"native evidence assembly failed: {exc}"
55
+ )
56
+ return 1
57
+ result = {
58
+ "passed": matched,
59
+ "check": args.check,
60
+ "candidate_commit": args.candidate_commit,
61
+ "output": str(args.evidence_output),
62
+ "errors": [] if matched else ["assembled evidence bundle drift"],
63
+ }
64
+ print(
65
+ json.dumps(result, sort_keys=True)
66
+ if args.format == "json"
67
+ else (
68
+ "Native evidence bundle "
69
+ + ("validated" if args.check else "assembled")
70
+ )
71
+ )
72
+ return 0 if matched else 1
73
+ if args.certify:
74
+ if not args.candidate_commit:
75
+ parser.error("--certify requires --candidate-commit")
76
+ if not re.fullmatch(
77
+ r"[0-9a-fA-F]{7,64}|simulated-[a-z0-9-]+", args.candidate_commit
78
+ ):
79
+ parser.error("candidate commit must be a commit hash or simulated fixture id")
80
+ try:
81
+ bundle = json.loads(args.certify.read_text(encoding="utf-8"))
82
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
83
+ print(f"certification bundle error: {exc}", file=sys.stderr)
84
+ return 2
85
+ errors = validate(bundle, args.candidate_commit, args.release_candidate, 30)
86
+ if args.support_output and not errors:
87
+ payload = support_matrix(bundle)
88
+ if args.check:
89
+ if (
90
+ not args.support_output.is_file()
91
+ or args.support_output.read_text(encoding="utf-8") != payload
92
+ ):
93
+ errors.append("generated support matrix drift")
94
+ else:
95
+ args.support_output.parent.mkdir(parents=True, exist_ok=True)
96
+ if (
97
+ not args.support_output.is_file()
98
+ or args.support_output.read_text(encoding="utf-8") != payload
99
+ ):
100
+ args.support_output.write_text(
101
+ payload, encoding="utf-8", newline="\n"
102
+ )
103
+ result = {
104
+ "passed": not errors,
105
+ "release_candidate": args.release_candidate,
106
+ "errors": errors,
107
+ }
108
+ print(
109
+ json.dumps(result, sort_keys=True)
110
+ if args.format == "json"
111
+ else ("\n".join(errors) if errors else "Three-client certification gate passed")
112
+ )
113
+ return 1 if errors else 0
114
+ started = time.perf_counter_ns()
115
+ try:
116
+ stats, drift = generate(args.root, args.output_root, args.check)
117
+ except (GenerationError, OSError) as exc:
118
+ print(f"client adapter generation failed: {exc}", file=sys.stderr)
119
+ return 2
120
+ result = {
121
+ "status": "drift" if drift else "clean",
122
+ "check": args.check,
123
+ "drift": drift,
124
+ "stats": stats.as_dict(),
125
+ "elapsed_ms": round((time.perf_counter_ns() - started) / 1_000_000, 3),
126
+ }
127
+ if args.format == "json":
128
+ print(json.dumps(result, sort_keys=True))
129
+ elif drift and args.check:
130
+ print("Client adapter drift: " + ", ".join(drift))
131
+ print("Run: python scripts/build-client-adapters.py")
132
+ else:
133
+ action = "Validated" if args.check else "Generated"
134
+ print(f"{action} three client adapters; changed={len(drift)}, written={stats.files_written}")
135
+ return 1 if args.check and drift else 0
136
+
137
+
138
+ if __name__ == "__main__":
139
+ raise SystemExit(main())