@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,399 @@
1
+ #!/usr/bin/env python3
2
+ """adr-settings: show and change every adr-kit knob from one place.
3
+
4
+ Before this existed a user changed settings in three disjoint places:
5
+ `adr-judge --set-backend` for the LLM backend, `/adr-kit:install-hooks` for
6
+ hooks, `bin/adr signer` for the actor, and a text editor for everything else.
7
+ Two failures followed from that split. `judge.llm_enabled` could be switched on
8
+ by a shipped writer but never off, and the signer had nowhere to live that a
9
+ user would find.
10
+
11
+ Two properties this command keeps visible rather than hiding.
12
+
13
+ **Provenance.** A value is worth little without knowing where it came from. Every
14
+ row says whether it is a project setting, a machine-local one, an environment
15
+ override, or the code default -- because "why is this on?" is the question a
16
+ settings screen exists to answer.
17
+
18
+ **Which file.** Repository-tracked settings in `docs/adr/.adr-kit.json` are team
19
+ decisions; machine-local ones in `.adr-kit.local.json` are personal, and the
20
+ difference matters. A signer written to the tracked file would put one person's
21
+ name on every teammate's acceptance. The command routes each write itself, and
22
+ says where it landed.
23
+
24
+ Never prints a secret. A credential is reported as a boolean about the
25
+ environment, which is the only part of it a settings screen needs.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import argparse
31
+ import json
32
+ import os
33
+ import re
34
+ import sys
35
+ import tempfile
36
+ from pathlib import Path
37
+ from typing import Any, Dict, List, Optional, Tuple
38
+
39
+ REPO_ROOT = Path(__file__).resolve().parent.parent
40
+ SCHEMA_PATH = REPO_ROOT / "schemas" / "adr-kit-config.schema.json"
41
+ PROJECT_CONFIG_NAME = ".adr-kit.json"
42
+ LOCAL_CONFIG_NAME = ".adr-kit.local.json"
43
+
44
+ # Settings that are personal or machine-specific. Everything else in the schema
45
+ # is a team decision and belongs in the tracked file.
46
+ LOCAL_KEYS: Dict[str, Dict[str, Any]] = {
47
+ "lifecycle.signer": {
48
+ "type": "string",
49
+ "description": (
50
+ "Who is recorded as the actor in Status History. Personal, so never "
51
+ "committed: a shared signer is a false attribution, not a shortcut."
52
+ ),
53
+ },
54
+ "judge.host_client": {
55
+ "type": "string",
56
+ "enum": ["claude-code-cli", "codex-cli", "github-copilot-cli"],
57
+ "description": (
58
+ "Which coding-client CLI answers the LLM pass. Machine-specific, and "
59
+ "deliberately not probed from PATH: on a machine with all three "
60
+ "installed, probe order would silently choose which vendor sees the "
61
+ "repository diff."
62
+ ),
63
+ },
64
+ }
65
+
66
+ # Environment variables that override or disable a setting at runtime. Reported
67
+ # so a user is never puzzled by a config value that is not taking effect.
68
+ ENV_OVERRIDES = {
69
+ "judge.llm_enabled": ("ADR_KIT_NO_LLM", "1 disables the LLM pass for one run"),
70
+ "judge.backend": ("ADR_KIT_LLM_CMD", "an explicit command bypasses the registry"),
71
+ }
72
+
73
+ # Keys whose value must never be rendered, mapped to the environment variable
74
+ # that can also supply them. The module docstring has always promised this;
75
+ # until now nothing implemented it, and `adr-settings --all` printed a stored
76
+ # API key back in full.
77
+ SECRET_KEYS = {}
78
+
79
+ # Keys worth surfacing by default. The schema holds more; these are the ones a
80
+ # user actually turns.
81
+ FEATURED = [
82
+ "judge.llm_enabled",
83
+ "judge.backend",
84
+ "judge.max_diff_bytes",
85
+ "judge.advisory_only",
86
+ "judge.llm_timeout_seconds",
87
+ "judge.pre_commit_timeout_ms",
88
+ "context.default_limit",
89
+ "context.min_score",
90
+ "context.strict_index",
91
+ "guardian.enabled",
92
+ "guardian.drift_stale_days",
93
+ "guardian.llm_stale_days",
94
+ "guardian.nudge_cooldown_hours",
95
+ "inject.enabled",
96
+ "watch.enabled",
97
+ "retirement.threshold_days",
98
+ "lifecycle.signer",
99
+ "judge.host_client",
100
+ ]
101
+
102
+
103
+ class SettingsError(Exception):
104
+ """Raised on an unknown key, an invalid value, or an unwritable config."""
105
+
106
+
107
+ def _atomic_write(path: Path, text: str) -> None:
108
+ path.parent.mkdir(parents=True, exist_ok=True)
109
+ handle = tempfile.NamedTemporaryFile(
110
+ mode="w", encoding="utf-8", newline="", dir=path.parent,
111
+ prefix=f".{path.name}.", suffix=".tmp", delete=False,
112
+ )
113
+ try:
114
+ with handle:
115
+ handle.write(text)
116
+ handle.flush()
117
+ os.fsync(handle.fileno())
118
+ os.replace(handle.name, path)
119
+ except BaseException:
120
+ Path(handle.name).unlink(missing_ok=True)
121
+ raise
122
+
123
+
124
+ def _read_json(path: Path) -> Dict:
125
+ try:
126
+ data = json.loads(path.read_text(encoding="utf-8"))
127
+ except (OSError, json.JSONDecodeError, ValueError):
128
+ return {}
129
+ return data if isinstance(data, dict) else {}
130
+
131
+
132
+ def load_schema() -> Dict:
133
+ return _read_json(SCHEMA_PATH)
134
+
135
+
136
+ def schema_node(schema: Dict, key: str) -> Optional[Dict]:
137
+ """Resolve a dotted key against the schema, or None when it is not tracked."""
138
+ node: Any = schema
139
+ for part in key.split("."):
140
+ props = (node or {}).get("properties") or {}
141
+ node = props.get(part)
142
+ if node is None:
143
+ return None
144
+ return node
145
+
146
+
147
+ def is_local(key: str) -> bool:
148
+ return key in LOCAL_KEYS
149
+
150
+
151
+ def known_keys(schema: Dict) -> List[str]:
152
+ keys: List[str] = []
153
+ for section, node in (schema.get("properties") or {}).items():
154
+ children = (node or {}).get("properties") or {}
155
+ if children:
156
+ keys.extend(f"{section}.{child}" for child in children)
157
+ else:
158
+ keys.append(section)
159
+ keys.extend(LOCAL_KEYS)
160
+ return sorted(set(keys))
161
+
162
+
163
+ def _dig(data: Dict, key: str) -> Tuple[bool, Any]:
164
+ node: Any = data
165
+ for part in key.split("."):
166
+ if not isinstance(node, dict) or part not in node:
167
+ return False, None
168
+ node = node[part]
169
+ return True, node
170
+
171
+
172
+ def _plant(data: Dict, key: str, value: Any) -> None:
173
+ parts = key.split(".")
174
+ node = data
175
+ for part in parts[:-1]:
176
+ child = node.get(part)
177
+ if not isinstance(child, dict):
178
+ child = {}
179
+ node[part] = child
180
+ node = child
181
+ node[parts[-1]] = value
182
+
183
+
184
+ def _uproot(data: Dict, key: str) -> bool:
185
+ parts = key.split(".")
186
+ node = data
187
+ for part in parts[:-1]:
188
+ child = node.get(part)
189
+ if not isinstance(child, dict):
190
+ return False
191
+ node = child
192
+ return node.pop(parts[-1], _MISSING) is not _MISSING
193
+
194
+
195
+ _MISSING = object()
196
+
197
+
198
+ def coerce(raw: str, node: Dict) -> Any:
199
+ """Turn a command-line string into the type the schema declares.
200
+
201
+ A settings command takes strings; a config file holds types. Coercing here
202
+ rather than writing the string means `--set guardian.enabled=false` does not
203
+ quietly store the truthy string "false".
204
+ """
205
+ declared = node.get("type") if node else None
206
+ text = raw.strip()
207
+ if declared == "boolean":
208
+ lowered = text.lower()
209
+ if lowered in {"true", "yes", "on", "1"}:
210
+ return True
211
+ if lowered in {"false", "no", "off", "0"}:
212
+ return False
213
+ raise SettingsError(f"expected a boolean, got {raw!r}")
214
+ if declared == "integer":
215
+ try:
216
+ return int(text)
217
+ except ValueError as exc:
218
+ raise SettingsError(f"expected an integer, got {raw!r}") from exc
219
+ if declared == "number":
220
+ try:
221
+ return float(text)
222
+ except ValueError as exc:
223
+ raise SettingsError(f"expected a number, got {raw!r}") from exc
224
+ if declared == "array":
225
+ return [part.strip() for part in text.split(",") if part.strip()]
226
+ return text
227
+
228
+
229
+ def validate(key: str, value: Any, node: Dict) -> None:
230
+ declared = node.get("type")
231
+ if declared == "boolean" and not isinstance(value, bool):
232
+ raise SettingsError(f"{key}: expected a boolean")
233
+ if declared == "integer" and not isinstance(value, int):
234
+ raise SettingsError(f"{key}: expected an integer")
235
+ if declared in {"number", "integer"} and isinstance(value, (int, float)):
236
+ if "minimum" in node and value < node["minimum"]:
237
+ raise SettingsError(f"{key}: minimum is {node['minimum']}")
238
+ if "maximum" in node and value > node["maximum"]:
239
+ raise SettingsError(f"{key}: maximum is {node['maximum']}")
240
+ allowed = node.get("enum")
241
+ if allowed and value not in allowed:
242
+ raise SettingsError(f"{key}: expected one of {allowed}, got {value!r}")
243
+ if declared == "string" and isinstance(value, str) and not value.strip():
244
+ raise SettingsError(f"{key}: expected a non-empty string")
245
+
246
+
247
+ def describe(adr_dir: Path, schema: Dict, keys: List[str], env: Dict[str, str]) -> List[Dict]:
248
+ project = _read_json(adr_dir / PROJECT_CONFIG_NAME)
249
+ local = _read_json(adr_dir / LOCAL_CONFIG_NAME)
250
+ rows: List[Dict] = []
251
+ for key in keys:
252
+ node = LOCAL_KEYS.get(key) or schema_node(schema, key) or {}
253
+ in_local, local_value = _dig(local, key)
254
+ in_project, project_value = _dig(project, key)
255
+ if in_local:
256
+ value, source = local_value, "machine-local"
257
+ elif in_project:
258
+ value, source = project_value, "project"
259
+ elif "default" in node:
260
+ value, source = node["default"], "default"
261
+ else:
262
+ value, source = None, "unset"
263
+ row = {
264
+ "key": key,
265
+ "value": value,
266
+ "source": source,
267
+ "scope": "machine-local" if is_local(key) else "project",
268
+ }
269
+ if key in SECRET_KEYS:
270
+ # A settings screen needs to answer "is a credential configured?",
271
+ # never "what is it". Echoing the value would put it in terminal
272
+ # scrollback, screenshots and pasted bug reports -- the file it came
273
+ # from is gitignored, but a terminal is not. The presence boolean is
274
+ # the whole of what a reader can act on.
275
+ row["value"] = "<set>" if _is_set(value) else None
276
+ row["secret"] = True
277
+ env_name = SECRET_KEYS[key]
278
+ if env_name:
279
+ row["env_present"] = bool(env.get(env_name))
280
+ row["env_var"] = env_name
281
+ override = ENV_OVERRIDES.get(key)
282
+ if override and env.get(override[0]):
283
+ row["env_override"] = f"{override[0]} is set: {override[1]}"
284
+ rows.append(row)
285
+ return rows
286
+
287
+
288
+ def _is_set(value: object) -> bool:
289
+ return bool(value) and str(value).strip() != ""
290
+
291
+
292
+ def render_text(rows: List[Dict], adr_dir: Path) -> List[str]:
293
+ width = max((len(row["key"]) for row in rows), default=0)
294
+ lines = [
295
+ f"Settings for {adr_dir}",
296
+ f" project file {adr_dir / PROJECT_CONFIG_NAME} (tracked, team decisions)",
297
+ f" machine-local {adr_dir / LOCAL_CONFIG_NAME} (gitignored, personal)",
298
+ "",
299
+ ]
300
+ for row in rows:
301
+ if row.get("secret"):
302
+ value = "<set>" if row["value"] else "(not set)"
303
+ elif row["value"] is None and row["source"] == "unset":
304
+ value = "(unset)"
305
+ else:
306
+ value = json.dumps(row["value"])
307
+ lines.append(f" {row['key']:<{width}} {value} [{row['source']}]")
308
+ if row.get("secret") and row.get("env_var"):
309
+ state = "set" if row.get("env_present") else "not set"
310
+ lines.append(f" {'':<{width}} {row['env_var']} is {state} in this environment")
311
+ if row.get("env_override"):
312
+ lines.append(f" {'':<{width}} !! {row['env_override']}")
313
+ return lines
314
+
315
+
316
+ def apply_set(adr_dir: Path, schema: Dict, key: str, raw: str) -> List[str]:
317
+ node = LOCAL_KEYS.get(key) or schema_node(schema, key)
318
+ if node is None:
319
+ raise SettingsError(
320
+ f"unknown setting {key!r}. Run --list to see every key this command knows."
321
+ )
322
+ value = coerce(raw, node)
323
+ validate(key, value, node)
324
+ target_name = LOCAL_CONFIG_NAME if is_local(key) else PROJECT_CONFIG_NAME
325
+ path = adr_dir / target_name
326
+ data = _read_json(path)
327
+ _plant(data, key, value)
328
+ _atomic_write(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
329
+ scope = "machine-local, gitignored" if is_local(key) else "project, committed"
330
+ return [f"{key} = {json.dumps(value)}", f"written to {path} ({scope})"]
331
+
332
+
333
+ def apply_unset(adr_dir: Path, schema: Dict, key: str) -> List[str]:
334
+ node = LOCAL_KEYS.get(key) or schema_node(schema, key)
335
+ if node is None:
336
+ raise SettingsError(f"unknown setting {key!r}")
337
+ path = adr_dir / (LOCAL_CONFIG_NAME if is_local(key) else PROJECT_CONFIG_NAME)
338
+ data = _read_json(path)
339
+ if not _uproot(data, key):
340
+ return [f"{key} was not set in {path}; nothing to do"]
341
+ _atomic_write(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
342
+ return [f"{key} unset; the code default applies again", f"updated {path}"]
343
+
344
+
345
+ def main(argv: Optional[List[str]] = None) -> int:
346
+ parser = argparse.ArgumentParser(
347
+ prog="adr-settings",
348
+ description="Show and change adr-kit settings, with provenance.",
349
+ )
350
+ parser.add_argument("--adr-dir", default="docs/adr", help="ADR directory")
351
+ parser.add_argument("--format", choices=["text", "json"], default="text")
352
+ parser.add_argument("--all", action="store_true", help="show every known key, not only the featured ones")
353
+ parser.add_argument("--list", action="store_true", help="list every settable key and exit")
354
+ parser.add_argument("--set", default=None, metavar="KEY=VALUE")
355
+ parser.add_argument("--unset", default=None, metavar="KEY")
356
+ args = parser.parse_args(argv)
357
+
358
+ adr_dir = Path(args.adr_dir)
359
+ schema = load_schema()
360
+
361
+ try:
362
+ if args.set and args.unset:
363
+ raise SettingsError("--set and --unset are mutually exclusive")
364
+ if args.list:
365
+ lines = known_keys(schema)
366
+ elif args.set:
367
+ if "=" not in args.set:
368
+ raise SettingsError("--set expects KEY=VALUE")
369
+ key, raw = args.set.split("=", 1)
370
+ lines = apply_set(adr_dir, schema, key.strip(), raw)
371
+ elif args.unset:
372
+ lines = apply_unset(adr_dir, schema, args.unset.strip())
373
+ else:
374
+ keys = known_keys(schema) if args.all else FEATURED
375
+ rows = describe(adr_dir, schema, keys, dict(os.environ))
376
+ if args.format == "json":
377
+ print(json.dumps({"adr_dir": str(adr_dir), "settings": rows}, indent=2, ensure_ascii=False))
378
+ return 0
379
+ lines = render_text(rows, adr_dir)
380
+ except SettingsError as exc:
381
+ print(f"adr-settings: {exc}", file=sys.stderr)
382
+ return 2
383
+
384
+ if args.format == "json" and not args.list:
385
+ print(json.dumps({"result": lines}, indent=2, ensure_ascii=False))
386
+ else:
387
+ for line in lines:
388
+ print(line)
389
+ return 0
390
+
391
+
392
+ if __name__ == "__main__":
393
+ if hasattr(sys.stdout, "reconfigure"):
394
+ try:
395
+ sys.stdout.reconfigure(encoding="utf-8")
396
+ sys.stderr.reconfigure(encoding="utf-8")
397
+ except (AttributeError, ValueError, OSError):
398
+ pass
399
+ raise SystemExit(main())