@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,165 @@
1
+ """Killable, bounded regex evaluation for repository-authored policy."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import atexit
6
+ import json
7
+ import queue
8
+ import subprocess
9
+ import sys
10
+ import threading
11
+ from pathlib import Path
12
+ from typing import Optional
13
+
14
+
15
+ DEFAULT_REGEX_TIMEOUT_SECONDS = 1.0
16
+ DEFAULT_REGEX_INPUT_BYTES = 2 * 1024 * 1024
17
+ DEFAULT_REGEX_PATTERN_CHARS = 4096
18
+
19
+
20
+ class RegexEvaluationError(RuntimeError):
21
+ """Base error for a regex that could not be evaluated safely."""
22
+
23
+
24
+ class RegexTimeoutError(RegexEvaluationError):
25
+ """Raised when an isolated regex exceeds its wall-clock budget."""
26
+
27
+
28
+ class RegexBudgetError(RegexEvaluationError):
29
+ """Raised when regex pattern or input exceeds its deterministic budget."""
30
+
31
+
32
+ class RegexEvaluator:
33
+ """One persistent worker process, restarted after timeout or failure."""
34
+
35
+ def __init__(
36
+ self,
37
+ *,
38
+ timeout_seconds: float = DEFAULT_REGEX_TIMEOUT_SECONDS,
39
+ max_input_bytes: int = DEFAULT_REGEX_INPUT_BYTES,
40
+ max_pattern_chars: int = DEFAULT_REGEX_PATTERN_CHARS,
41
+ ) -> None:
42
+ self.timeout_seconds = timeout_seconds
43
+ self.max_input_bytes = max_input_bytes
44
+ self.max_pattern_chars = max_pattern_chars
45
+ self._process: Optional[subprocess.Popen[str]] = None
46
+ self._responses: "queue.Queue[Optional[str]]" = queue.Queue()
47
+
48
+ def _start(self) -> None:
49
+ worker = Path(__file__).resolve().with_name("adr_regex_worker.py")
50
+ self._responses = queue.Queue()
51
+ self._process = subprocess.Popen(
52
+ [sys.executable, str(worker)],
53
+ stdin=subprocess.PIPE,
54
+ stdout=subprocess.PIPE,
55
+ stderr=subprocess.DEVNULL,
56
+ text=True,
57
+ encoding="utf-8",
58
+ errors="replace",
59
+ bufsize=1,
60
+ )
61
+ assert self._process.stdout is not None
62
+ # Capture stdout and the response queue as locals so that if the
63
+ # evaluator is restarted (e.g. after a timeout), the old reader thread
64
+ # puts its sentinel None into the *old* queue rather than the new one.
65
+ _stdout = self._process.stdout
66
+ _responses: "queue.Queue[Optional[str]]" = self._responses
67
+
68
+ def _read() -> None:
69
+ for response in _stdout:
70
+ _responses.put(response)
71
+ _responses.put(None)
72
+
73
+ threading.Thread(target=_read, daemon=True).start()
74
+
75
+ def close(self) -> None:
76
+ process = self._process
77
+ self._process = None
78
+ if process is None:
79
+ return
80
+ if process.stdin is not None:
81
+ try:
82
+ process.stdin.close()
83
+ except OSError:
84
+ pass
85
+ try:
86
+ process.wait(timeout=0.2)
87
+ except subprocess.TimeoutExpired:
88
+ process.kill()
89
+ process.wait()
90
+
91
+ def _terminate(self) -> None:
92
+ process = self._process
93
+ self._process = None
94
+ if process is not None and process.poll() is None:
95
+ process.kill()
96
+ process.wait()
97
+
98
+ def search(self, pattern: str, text: str, flags: int = 0) -> bool:
99
+ if len(pattern) > self.max_pattern_chars:
100
+ raise RegexBudgetError(
101
+ f"pattern length {len(pattern)} exceeds {self.max_pattern_chars} characters"
102
+ )
103
+ input_bytes = len(text.encode("utf-8", errors="replace"))
104
+ if input_bytes > self.max_input_bytes:
105
+ raise RegexBudgetError(
106
+ f"input size {input_bytes} exceeds {self.max_input_bytes} bytes"
107
+ )
108
+ if self._process is None or self._process.poll() is not None:
109
+ self._start()
110
+ assert self._process is not None
111
+ assert self._process.stdin is not None
112
+ request = json.dumps(
113
+ {"pattern": pattern, "text": text, "flags": flags},
114
+ ensure_ascii=False,
115
+ separators=(",", ":"),
116
+ )
117
+ try:
118
+ self._process.stdin.write(request + "\n")
119
+ self._process.stdin.flush()
120
+ except (BrokenPipeError, OSError) as exc:
121
+ self._terminate()
122
+ raise RegexEvaluationError(f"isolated regex worker failed: {exc}") from exc
123
+ try:
124
+ response_line = self._responses.get(timeout=self.timeout_seconds)
125
+ except queue.Empty as exc:
126
+ self._terminate()
127
+ raise RegexTimeoutError(
128
+ f"regex exceeded {self.timeout_seconds:.3f}s wall-clock budget"
129
+ ) from exc
130
+ if response_line is None:
131
+ self._terminate()
132
+ raise RegexEvaluationError("isolated regex worker exited unexpectedly")
133
+ try:
134
+ response = json.loads(response_line)
135
+ except json.JSONDecodeError as exc:
136
+ self._terminate()
137
+ raise RegexEvaluationError(
138
+ "isolated regex worker returned invalid JSON"
139
+ ) from exc
140
+ if not response.get("ok"):
141
+ raise RegexEvaluationError(
142
+ f"isolated regex worker rejected pattern: {response.get('error', 'unknown error')}"
143
+ )
144
+ return bool(response.get("matched"))
145
+
146
+
147
+ _DEFAULT_EVALUATOR: Optional[RegexEvaluator] = None
148
+
149
+
150
+ def bounded_regex_search(pattern: str, text: str, flags: int = 0) -> bool:
151
+ """Search in an isolated process with fixed input and wall-clock budgets."""
152
+ global _DEFAULT_EVALUATOR
153
+ if _DEFAULT_EVALUATOR is None:
154
+ _DEFAULT_EVALUATOR = RegexEvaluator()
155
+ return _DEFAULT_EVALUATOR.search(pattern, text, flags)
156
+
157
+
158
+ def _close_default() -> None:
159
+ global _DEFAULT_EVALUATOR
160
+ if _DEFAULT_EVALUATOR is not None:
161
+ _DEFAULT_EVALUATOR.close()
162
+ _DEFAULT_EVALUATOR = None
163
+
164
+
165
+ atexit.register(_close_default)
@@ -0,0 +1,30 @@
1
+ #!/usr/bin/env python3
2
+ """Isolated regex worker for adr-kit policy evaluation.
3
+
4
+ The parent process owns all timeouts and can terminate this process if CPython's
5
+ backtracking regex engine becomes unresponsive.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import re
12
+ import sys
13
+
14
+
15
+ def main() -> int:
16
+ for line in sys.stdin:
17
+ try:
18
+ request = json.loads(line)
19
+ pattern = re.compile(request["pattern"], int(request.get("flags", 0)))
20
+ match = pattern.search(request["text"])
21
+ response = {"ok": True, "matched": match is not None}
22
+ except (KeyError, TypeError, ValueError, re.error) as exc:
23
+ response = {"ok": False, "error": str(exc)}
24
+ sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
25
+ sys.stdout.flush()
26
+ return 0
27
+
28
+
29
+ if __name__ == "__main__":
30
+ raise SystemExit(main())
@@ -0,0 +1,385 @@
1
+ """Read-only selective-context probes and retrieval metadata health."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from pathlib import Path
8
+ from typing import Dict, List, Optional, Sequence
9
+
10
+ from adr_query import IndexQueryError, load_index_graph, query_records
11
+
12
+ MAX_PROBES = 100
13
+ MAX_EXPECTATIONS = 20
14
+ DEFAULT_PROBE_FILE = "adr-context-probes.json"
15
+
16
+
17
+ class ProbeConfigError(ValueError):
18
+ """Raised when a project retrieval-probe file is malformed."""
19
+
20
+
21
+ def _string_array(
22
+ value: object,
23
+ field: str,
24
+ *,
25
+ maximum: int,
26
+ adr_ids: bool = False,
27
+ ) -> List[str]:
28
+ if not isinstance(value, list) or len(value) > maximum:
29
+ raise ProbeConfigError(f"{field} must be an array with at most {maximum} items")
30
+ result: List[str] = []
31
+ for item in value:
32
+ if not isinstance(item, str) or not item.strip() or len(item) > 240:
33
+ raise ProbeConfigError(f"{field} entries must be non-empty strings")
34
+ if adr_ids and not re.fullmatch(r"ADR-\d{3,4}", item):
35
+ raise ProbeConfigError(f"{field} contains invalid ADR id {item!r}")
36
+ result.append(item)
37
+ if len({item.casefold() for item in result}) != len(result):
38
+ raise ProbeConfigError(f"{field} entries must be unique")
39
+ return result
40
+
41
+
42
+ def load_probes(path: Path) -> Dict:
43
+ try:
44
+ payload = json.loads(path.read_text(encoding="utf-8"))
45
+ except (OSError, UnicodeError, json.JSONDecodeError) as exc:
46
+ raise ProbeConfigError(f"cannot read retrieval probes: {exc}") from exc
47
+ if not isinstance(payload, dict) or payload.get("schema_version") != 1:
48
+ raise ProbeConfigError("retrieval probes require schema_version 1")
49
+ allowed_root = {"$schema", "schema_version", "probes"}
50
+ if set(payload) - allowed_root:
51
+ raise ProbeConfigError(
52
+ "unknown retrieval-probe root field(s): "
53
+ + ", ".join(sorted(set(payload) - allowed_root))
54
+ )
55
+ probes = payload.get("probes")
56
+ if not isinstance(probes, list) or len(probes) > MAX_PROBES:
57
+ raise ProbeConfigError(f"probes must be an array with at most {MAX_PROBES} items")
58
+ ids = set()
59
+ normalized = []
60
+ allowed_probe = {
61
+ "id",
62
+ "query",
63
+ "paths",
64
+ "components",
65
+ "symbols",
66
+ "topics",
67
+ "limit",
68
+ "expect",
69
+ }
70
+ for raw in probes:
71
+ if not isinstance(raw, dict) or set(raw) - allowed_probe:
72
+ raise ProbeConfigError("each retrieval probe must be a known-field object")
73
+ probe_id = raw.get("id")
74
+ query = raw.get("query")
75
+ limit = raw.get("limit", 3)
76
+ expect = raw.get("expect")
77
+ if (
78
+ not isinstance(probe_id, str)
79
+ or not re.fullmatch(r"[a-z][a-z0-9-]{0,79}", probe_id)
80
+ or probe_id in ids
81
+ ):
82
+ raise ProbeConfigError(f"invalid or duplicate probe id {probe_id!r}")
83
+ if not isinstance(query, str) or not query.strip() or len(query) > 1000:
84
+ raise ProbeConfigError(f"{probe_id}: query must be a non-empty string")
85
+ if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 20:
86
+ raise ProbeConfigError(f"{probe_id}: limit must be between 1 and 20")
87
+ if (
88
+ not isinstance(expect, dict)
89
+ or set(expect) - {"include", "exclude"}
90
+ ):
91
+ raise ProbeConfigError(f"{probe_id}: expect must contain include/exclude")
92
+ include = _string_array(
93
+ expect.get("include", []),
94
+ f"{probe_id}.expect.include",
95
+ maximum=MAX_EXPECTATIONS,
96
+ adr_ids=True,
97
+ )
98
+ exclude = _string_array(
99
+ expect.get("exclude", []),
100
+ f"{probe_id}.expect.exclude",
101
+ maximum=MAX_EXPECTATIONS,
102
+ adr_ids=True,
103
+ )
104
+ if set(include) & set(exclude):
105
+ raise ProbeConfigError(f"{probe_id}: include and exclude overlap")
106
+ ids.add(probe_id)
107
+ normalized.append(
108
+ {
109
+ "id": probe_id,
110
+ "query": query.strip(),
111
+ "paths": _string_array(
112
+ raw.get("paths", []), f"{probe_id}.paths", maximum=32
113
+ ),
114
+ "components": _string_array(
115
+ raw.get("components", []), f"{probe_id}.components", maximum=32
116
+ ),
117
+ "symbols": _string_array(
118
+ raw.get("symbols", []), f"{probe_id}.symbols", maximum=32
119
+ ),
120
+ "topics": _string_array(
121
+ raw.get("topics", []), f"{probe_id}.topics", maximum=32
122
+ ),
123
+ "limit": limit,
124
+ "expect": {"include": include, "exclude": exclude},
125
+ }
126
+ )
127
+ return {"schema_version": 1, "probes": normalized}
128
+
129
+
130
+ def _metadata_findings(records: Sequence[Dict], strict: bool) -> List[Dict]:
131
+ findings = []
132
+ for record in records:
133
+ metadata = record.get("metadata", {})
134
+ if (
135
+ record.get("status") != "Accepted"
136
+ or not isinstance(metadata, dict)
137
+ or metadata.get("binding") is not True
138
+ ):
139
+ continue
140
+ contract = record.get("decision_contract", {})
141
+ has_contract = isinstance(contract, dict) and any(
142
+ isinstance(values, list) and any(str(value).strip() for value in values)
143
+ for values in contract.values()
144
+ )
145
+ has_selective_data = any(
146
+ isinstance(record.get(field), list) and record.get(field)
147
+ for field in ("topics", "aliases", "components", "symbols")
148
+ )
149
+ if (
150
+ record.get("context_scope") != "global"
151
+ and not has_selective_data
152
+ and not has_contract
153
+ ):
154
+ findings.append(
155
+ {
156
+ "type": "selective_context_metadata",
157
+ "level": "FAIL" if strict else "ADVISORY",
158
+ "adr_id": record.get("id"),
159
+ "file": record.get("path"),
160
+ "message": (
161
+ "Accepted binding ADR has no selective retrieval metadata; "
162
+ "add topics, aliases, components, symbols, a Decision Contract, "
163
+ "or explicitly mark context_scope: global"
164
+ ),
165
+ }
166
+ )
167
+ return findings
168
+
169
+
170
+ def evaluate_probes(
171
+ records: Sequence[Dict],
172
+ relationships: Sequence[Dict],
173
+ schema_version: int,
174
+ adr_dir: Path,
175
+ probes: Sequence[Dict],
176
+ ) -> Dict:
177
+ results = []
178
+ passed = 0
179
+ for probe in probes:
180
+ ranked = query_records(
181
+ records,
182
+ relationships,
183
+ probe["query"],
184
+ adr_dir,
185
+ limit=probe["limit"],
186
+ include_history=False,
187
+ paths=probe["paths"],
188
+ components=probe["components"],
189
+ symbols=probe["symbols"],
190
+ topics=probe["topics"],
191
+ source=f"index-v{schema_version}",
192
+ schema_version=schema_version,
193
+ )
194
+ actual = [
195
+ {
196
+ "rank": rank,
197
+ "adr_id": item["adr_id"],
198
+ "authority": item["authority"],
199
+ "role": item["role"],
200
+ "score": item["score"],
201
+ "matches": item["matches"],
202
+ }
203
+ for rank, item in enumerate(ranked, start=1)
204
+ ]
205
+ actual_ids = [item["adr_id"] for item in actual]
206
+ missing = [
207
+ adr_id
208
+ for adr_id in probe["expect"]["include"]
209
+ if adr_id not in actual_ids
210
+ ]
211
+ unexpected = [
212
+ adr_id
213
+ for adr_id in probe["expect"]["exclude"]
214
+ if adr_id in actual_ids
215
+ ]
216
+ historical = [
217
+ item["adr_id"]
218
+ for item in actual
219
+ if item["authority"] == "historical"
220
+ ]
221
+ ok = not missing and not unexpected and not historical
222
+ passed += int(ok)
223
+ results.append(
224
+ {
225
+ "id": probe["id"],
226
+ "status": "pass" if ok else "fail",
227
+ "query": probe["query"],
228
+ "inputs": {
229
+ "paths": probe["paths"],
230
+ "components": probe["components"],
231
+ "symbols": probe["symbols"],
232
+ "topics": probe["topics"],
233
+ "limit": probe["limit"],
234
+ },
235
+ "expected": probe["expect"],
236
+ "actual": actual,
237
+ "missing": missing,
238
+ "unexpected": unexpected,
239
+ "historical_leakage": historical,
240
+ }
241
+ )
242
+ return {
243
+ "configured": bool(probes),
244
+ "summary": {
245
+ "total": len(probes),
246
+ "pass": passed,
247
+ "fail": len(probes) - passed,
248
+ },
249
+ "results": results,
250
+ }
251
+
252
+
253
+ def _load_config(adr_dir: Path) -> Dict:
254
+ path = adr_dir / ".adr-kit.json"
255
+ if not path.is_file():
256
+ return {}
257
+ try:
258
+ payload = json.loads(path.read_text(encoding="utf-8"))
259
+ except (OSError, UnicodeError, json.JSONDecodeError):
260
+ return {}
261
+ return payload if isinstance(payload, dict) else {}
262
+
263
+
264
+ def run_retrieval_health(
265
+ adr_dir: Path,
266
+ *,
267
+ probe_path: Optional[Path] = None,
268
+ config: Optional[Dict] = None,
269
+ ) -> Dict:
270
+ cfg = config if isinstance(config, dict) else _load_config(adr_dir)
271
+ context_cfg = cfg.get("context", {}) if isinstance(cfg, dict) else {}
272
+ mode = context_cfg.get("retrieval_completeness", "advisory")
273
+ if mode not in {"off", "advisory", "strict"}:
274
+ mode = "advisory"
275
+ configured_path = probe_path or adr_dir / str(
276
+ context_cfg.get("probes_file", DEFAULT_PROBE_FILE)
277
+ )
278
+ configured_path = configured_path.resolve()
279
+ try:
280
+ configured_path.relative_to(adr_dir.resolve())
281
+ except ValueError:
282
+ return {
283
+ "status": "fail",
284
+ "source": None,
285
+ "schema_version": None,
286
+ "probe_file": configured_path.as_posix(),
287
+ "probe_error": "retrieval probe file must stay within the ADR directory",
288
+ "index_error": None,
289
+ "metadata_mode": mode,
290
+ "metadata_findings": [],
291
+ "probes": {
292
+ "configured": False,
293
+ "summary": {"total": 0, "pass": 0, "fail": 1},
294
+ "results": [],
295
+ },
296
+ }
297
+ try:
298
+ records, relationships, version = load_index_graph(adr_dir)
299
+ except IndexQueryError as exc:
300
+ return {
301
+ "status": "degraded",
302
+ "source": None,
303
+ "schema_version": None,
304
+ "probe_file": configured_path.as_posix(),
305
+ "index_error": str(exc),
306
+ "metadata_mode": mode,
307
+ "metadata_findings": [],
308
+ "probes": {
309
+ "configured": configured_path.is_file(),
310
+ "summary": {"total": 0, "pass": 0, "fail": 0},
311
+ "results": [],
312
+ },
313
+ }
314
+ try:
315
+ probe_payload = (
316
+ load_probes(configured_path)
317
+ if configured_path.is_file()
318
+ else {"schema_version": 1, "probes": []}
319
+ )
320
+ probes = evaluate_probes(
321
+ records,
322
+ relationships,
323
+ version,
324
+ adr_dir,
325
+ probe_payload["probes"],
326
+ )
327
+ probe_error = None
328
+ except ProbeConfigError as exc:
329
+ probes = {
330
+ "configured": True,
331
+ "summary": {"total": 0, "pass": 0, "fail": 1},
332
+ "results": [],
333
+ }
334
+ probe_error = str(exc)
335
+ metadata = [] if mode == "off" else _metadata_findings(records, mode == "strict")
336
+ failed = (
337
+ bool(probe_error)
338
+ or probes["summary"]["fail"] > 0
339
+ or any(item["level"] == "FAIL" for item in metadata)
340
+ )
341
+ return {
342
+ "status": "fail" if failed else "pass",
343
+ "source": f"index-v{version}",
344
+ "schema_version": version,
345
+ "probe_file": configured_path.as_posix(),
346
+ "probe_error": probe_error,
347
+ "index_error": None,
348
+ "metadata_mode": mode,
349
+ "metadata_findings": metadata,
350
+ "probes": probes,
351
+ }
352
+
353
+
354
+ def render_retrieval_health(payload: Dict) -> str:
355
+ probe_summary = payload["probes"]["summary"]
356
+ lines = [
357
+ "ADR selective-context health:",
358
+ f" status={payload['status']} source={payload.get('source') or 'unavailable'}",
359
+ (
360
+ " probes="
361
+ f"{probe_summary['pass']} pass/{probe_summary['fail']} fail/"
362
+ f"{probe_summary['total']} total"
363
+ ),
364
+ (
365
+ " retrieval_metadata="
366
+ f"{len(payload.get('metadata_findings', []))} finding(s) "
367
+ f"[{payload.get('metadata_mode', 'advisory')}]"
368
+ ),
369
+ ]
370
+ if payload.get("index_error"):
371
+ lines.append(f" index_error={payload['index_error']}")
372
+ if payload.get("probe_error"):
373
+ lines.append(f" probe_error={payload['probe_error']}")
374
+ for result in payload["probes"]["results"]:
375
+ if result["status"] == "fail":
376
+ actual = ", ".join(
377
+ f"{item['adr_id']}({item['authority']})"
378
+ for item in result["actual"]
379
+ ) or "none"
380
+ lines.append(
381
+ f" FAIL {result['id']}: query={result['query']!r}; "
382
+ f"missing={result['missing']}; unexpected={result['unexpected']}; "
383
+ f"actual={actual}"
384
+ )
385
+ return "\n".join(lines)