@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
|
@@ -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())
|