@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,674 @@
1
+ """adr_quality_core: the four-gate ADR quality scorer, separated from its CLI.
2
+
3
+ `bin/adr-quality` was both the scorer and the command, and that made the scorer
4
+ unreachable. Readiness computed its own "quality" from three booleans -- is
5
+ there decision text, is there a verified_in, are the open questions closed --
6
+ while the real weighted scorer sat behind a command line that only
7
+ `accept --auto` ever invoked. So a vague ADR and a sharp one were queued for
8
+ grilling identically, and the evaluator that could have told them apart was
9
+ never asked.
10
+
11
+ Moving the scoring here makes it importable, which is what puts it on a shipped
12
+ path: readiness reads it in-process, the guardian queue ranks on it, and
13
+ `bin/adr-quality` becomes the rendering shell it always should have been.
14
+ Nothing about the scores changed in the move.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import importlib.machinery
20
+ import importlib.util
21
+ import json
22
+ import re
23
+ import sys
24
+ from dataclasses import dataclass
25
+ from pathlib import Path
26
+ from typing import Dict, List, Optional
27
+
28
+ _BIN_DIR = Path(__file__).resolve().parent
29
+
30
+
31
+ def _load_sibling(name: str):
32
+ """Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
33
+
34
+ SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
35
+ of the standard library for every import, so a module committed next to
36
+ this script executed as code -- and it re-added the very directory
37
+ CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
38
+ sys.modules under their bare name, so the plain `from adr_* import ...`
39
+ statements below (and the lazy ones inside functions) resolve from the
40
+ cache instead of the path. bin/adr-judge carries the full rationale.
41
+ """
42
+ cached = sys.modules.get(name)
43
+ if cached is not None:
44
+ return cached
45
+ loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
46
+ spec = importlib.util.spec_from_loader(name, loader)
47
+ module = importlib.util.module_from_spec(spec)
48
+ sys.modules[name] = module
49
+ loader.exec_module(module)
50
+ return module
51
+
52
+
53
+ _load_sibling("adr_format")
54
+
55
+ from adr_format import detect_profile, required_headings, section_text
56
+
57
+
58
+ REQUIRED_SECTIONS = [
59
+ "## Status",
60
+ "## Context",
61
+ "## Decision",
62
+ "## Alternatives Considered",
63
+ "## Consequences",
64
+ "## Related Decisions",
65
+ "## References",
66
+ ]
67
+
68
+ VALID_STATUSES = {
69
+ "proposed", "accepted", "deprecated", "superseded", "amended",
70
+ }
71
+
72
+ ADR_ID_RE = re.compile(r"(?i)^ADR-(\d{1,4})-")
73
+ ADR_REF_RE = re.compile(r"\bADR-(\d{3})\b", re.IGNORECASE)
74
+ METRICS_RE = re.compile(r"\d+\s*(ms|MB|GB|KB|%|req|s|hours?)\b")
75
+ FILE_LINE_RE = re.compile(r"[\w./]+:\d+")
76
+ EXTERNAL_LINK_RE = re.compile(r"https?://")
77
+ # Unified vague-words set; identical to bin/adr-lint's check_quality_gate().
78
+ VAGUE_WORDS_RE = re.compile(
79
+ r"\b(appropriate|somehow|maybe|possibly|might|could|"
80
+ r"should\s+consider|might\s+consider)\b",
81
+ re.IGNORECASE,
82
+ )
83
+
84
+ # Precompiled section-heading patterns: one regex per required section, used
85
+ # for both presence checks (gate_completeness) and slicing (_section_text).
86
+ _SECTION_PRESENCE_RE: Dict[str, re.Pattern] = {
87
+ section: re.compile(r"^" + re.escape(section) + r"\b", re.MULTILINE)
88
+ for section in REQUIRED_SECTIONS
89
+ }
90
+ _SECTION_BODY_RE: Dict[str, re.Pattern] = {
91
+ section: re.compile(
92
+ r"^" + re.escape(section) + r"\s*$\n(.*?)(?=\n##\s+|\Z)",
93
+ re.MULTILINE | re.DOTALL,
94
+ )
95
+ for section in REQUIRED_SECTIONS
96
+ }
97
+
98
+ # Acronym scanning (gate_clarity).
99
+ _ACRO_RE = re.compile(r"\b([A-Z]{2,})\b")
100
+ _ACRO_DEFINED_RE = re.compile(
101
+ r"\b([A-Z]{2,})\b\s*(?:\(|stands\s+for|means\b|\:)"
102
+ )
103
+
104
+
105
+ # ---------------------------------------------------------------------------
106
+ # Structured quality issues
107
+ # ---------------------------------------------------------------------------
108
+
109
+ ISSUE_MESSAGES: Dict[str, str] = {
110
+ "MISSING_SECTION": "Required section missing: {detail}",
111
+ "DECISION_TOO_SHORT":
112
+ "Decision section too short ({detail} chars, minimum 100)",
113
+ "TOO_FEW_ALTERNATIVES":
114
+ "Too few alternatives considered ({detail} found, minimum 2)",
115
+ "CONSEQUENCES_EMPTY": "Consequences section is empty",
116
+ "NO_REFERENCES": "References section is empty or contains only 'None'",
117
+ "NO_MEASUREMENTS":
118
+ "No quantitative measurements found (e.g., '50 ms', '10 MB', '30%')",
119
+ "NO_EXTERNAL_LINK":
120
+ "No external links found in the document; add https:// references",
121
+ "NO_FILE_LINE_REF":
122
+ "No file:line references found (e.g., 'src/main.py:42')",
123
+ "VAGUE_LANGUAGE": "Decision section uses vague language: {detail}",
124
+ "NO_TITLE": "No ADR title heading found (expected '# ADR-NNN Title')",
125
+ "ACRONYM_UNEXPLAINED": "More than 3 undefined acronyms: {detail}",
126
+ "CONTEXT_TOO_SHORT":
127
+ "Context section too short ({detail} chars, minimum 50)",
128
+ "NO_RELATED_DECISIONS":
129
+ "Related Decisions is empty or 'None'; reference related ADRs "
130
+ "(or explain why there are none)",
131
+ "ORPHAN_RELATED_ID": "Referenced ADRs do not exist: {detail}",
132
+ "INVALID_STATUS":
133
+ "Status section has no valid status value "
134
+ "(expected one of: {detail})",
135
+ }
136
+
137
+ # Severity ordering for triage display (lower = more severe).
138
+ SEVERITY_ORDER: Dict[str, int] = {"high": 0, "medium": 1, "low": 2}
139
+
140
+
141
+ @dataclass
142
+ class QualityIssue:
143
+ """Structured issue produced by a quality gate.
144
+
145
+ ``code`` is a stable machine-readable identifier (see ISSUE_MESSAGES);
146
+ ``detail`` is free-form context interpolated into the human message.
147
+ """
148
+
149
+ code: str
150
+ detail: str = ""
151
+ severity: str = "medium" # "high" | "medium" | "low"
152
+
153
+ def message(self) -> str:
154
+ template = ISSUE_MESSAGES.get(self.code, self.code)
155
+ try:
156
+ return template.format(detail=self.detail)
157
+ except (KeyError, IndexError):
158
+ return template
159
+
160
+ def to_dict(self) -> Dict:
161
+ return {
162
+ "code": self.code,
163
+ "detail": self.detail,
164
+ "severity": self.severity,
165
+ "message": self.message(),
166
+ }
167
+
168
+
169
+ def _section_text(content: str, heading: str) -> str:
170
+ """Extract text of a markdown section (up to the next ## heading or EOF)."""
171
+ role = {
172
+ "## Status": "status",
173
+ "## Context": "context",
174
+ "## Decision": "decision",
175
+ "## Alternatives Considered": "alternatives",
176
+ "## Consequences": "consequences",
177
+ "## Related Decisions": "related",
178
+ "## References": "references",
179
+ }.get(heading)
180
+ if role:
181
+ return section_text(content, role)
182
+ pat = _SECTION_BODY_RE.get(heading)
183
+ if pat is None:
184
+ # Fallback for any heading not in REQUIRED_SECTIONS.
185
+ pat = re.compile(
186
+ r"^" + re.escape(heading) + r"\s*$\n(.*?)(?=\n##\s+|\Z)",
187
+ re.MULTILINE | re.DOTALL,
188
+ )
189
+ m = pat.search(content)
190
+ return m.group(1) if m else ""
191
+
192
+
193
+ def gate_completeness(content: str) -> Dict:
194
+ """Gate 1: Completeness (0.0-1.0).
195
+
196
+ Checks:
197
+ - All 7 required sections present (each missing: -1/7)
198
+ - ## Decision section > 100 chars (else: -0.1)
199
+ - ## Alternatives Considered contains >= 2 bullet/heading items (else: -0.15)
200
+ - ## Consequences section present and not empty (else: -0.1)
201
+
202
+ Returns: {score: float, issues: List[QualityIssue], checks: Dict[str, bool]}
203
+ """
204
+ issues: List[QualityIssue] = []
205
+ checks: Dict[str, bool] = {}
206
+
207
+ # Check all required sections present
208
+ missing_sections = []
209
+ profile = detect_profile(content)
210
+ effective_sections = (
211
+ required_headings(profile)
212
+ if profile in {"madr", "nygard", "canonical"}
213
+ else REQUIRED_SECTIONS
214
+ )
215
+ for section in effective_sections:
216
+ pattern = _SECTION_PRESENCE_RE.get(section) or re.compile(
217
+ r"^" + re.escape(section) + r"\b", re.MULTILINE
218
+ )
219
+ present = bool(pattern.search(content))
220
+ checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = present
221
+ if not present:
222
+ missing_sections.append(section)
223
+
224
+ score = 1.0
225
+ n_missing = len(missing_sections)
226
+ if n_missing > 0:
227
+ score -= n_missing / 7.0
228
+ missing_names = ", ".join(s.replace("## ", "") for s in missing_sections)
229
+ issues.append(QualityIssue(
230
+ code="MISSING_SECTION",
231
+ detail=missing_names,
232
+ severity="high",
233
+ ))
234
+
235
+ # Check Decision section length
236
+ decision_text = _section_text(content, "## Decision")
237
+ decision_len = len(decision_text.strip())
238
+ decision_long_enough = decision_len > 100
239
+ checks["decision_length_ok"] = decision_long_enough
240
+ if not decision_long_enough:
241
+ score -= 0.1
242
+ issues.append(QualityIssue(
243
+ code="DECISION_TOO_SHORT",
244
+ detail=str(decision_len),
245
+ severity="medium",
246
+ ))
247
+
248
+ # Check Alternatives Considered has >= 2 items
249
+ alternatives_text = _section_text(content, "## Alternatives Considered")
250
+ list_items = re.findall(r"^[-*]\s+\S", alternatives_text, re.MULTILINE)
251
+ heading_items = re.findall(r"^###\s+\S", alternatives_text, re.MULTILINE)
252
+ total_alternatives = len(list_items) + len(heading_items)
253
+ enough_alternatives = total_alternatives >= 2
254
+ checks["alternatives_count_ok"] = enough_alternatives
255
+ if not enough_alternatives:
256
+ score -= 0.15
257
+ issues.append(QualityIssue(
258
+ code="TOO_FEW_ALTERNATIVES",
259
+ detail=str(total_alternatives),
260
+ severity="medium",
261
+ ))
262
+
263
+ # Check Consequences present and not empty
264
+ consequences_text = _section_text(content, "## Consequences")
265
+ consequences_ok = bool(consequences_text.strip())
266
+ checks["consequences_not_empty"] = consequences_ok
267
+ if not consequences_ok:
268
+ score -= 0.1
269
+ issues.append(QualityIssue(
270
+ code="CONSEQUENCES_EMPTY",
271
+ severity="high",
272
+ ))
273
+
274
+ score = max(0.0, min(1.0, score))
275
+ return {"score": score, "issues": issues, "checks": checks}
276
+
277
+
278
+ def gate_evidence(content: str) -> Dict:
279
+ """Gate 2: Evidence (0.0-1.0).
280
+
281
+ Checks:
282
+ - ## References section contains >= 1 non-'None' entry: +0.4
283
+ - Number/measurement present (regex r'\\d+\\s*(ms|MB|GB|KB|%|req|s|hours?)'): +0.3
284
+ - External link present (http:// or https://): +0.2
285
+ - file:line reference present: +0.1
286
+
287
+ Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
288
+ """
289
+ issues: List[QualityIssue] = []
290
+ checks: Dict[str, bool] = {}
291
+
292
+ # Check References section has at least 1 non-None entry
293
+ refs_text = _section_text(content, "## References")
294
+ refs_lines = [
295
+ ln.strip() for ln in refs_text.splitlines()
296
+ if ln.strip() and ln.strip().lower() not in ("none.", "none", "-")
297
+ ]
298
+ has_references = bool(refs_lines)
299
+ checks["references_present"] = has_references
300
+ score = 0.0
301
+ if has_references:
302
+ score += 0.4
303
+ else:
304
+ issues.append(QualityIssue(code="NO_REFERENCES", severity="high"))
305
+
306
+ # Check for metrics/measurements in the whole document
307
+ has_metrics = bool(METRICS_RE.search(content))
308
+ checks["metrics_present"] = has_metrics
309
+ if has_metrics:
310
+ score += 0.3
311
+ else:
312
+ issues.append(QualityIssue(code="NO_MEASUREMENTS", severity="low"))
313
+
314
+ # Check for external links
315
+ has_external_link = bool(EXTERNAL_LINK_RE.search(content))
316
+ checks["external_link_present"] = has_external_link
317
+ if has_external_link:
318
+ score += 0.2
319
+ else:
320
+ issues.append(QualityIssue(code="NO_EXTERNAL_LINK", severity="low"))
321
+
322
+ # Check for file:line references
323
+ has_file_line = bool(FILE_LINE_RE.search(content))
324
+ checks["file_line_reference_present"] = has_file_line
325
+ if has_file_line:
326
+ score += 0.1
327
+ else:
328
+ issues.append(QualityIssue(code="NO_FILE_LINE_REF", severity="low"))
329
+
330
+ score = max(0.0, min(1.0, score))
331
+ return {"score": score, "issues": issues, "checks": checks}
332
+
333
+
334
+ def gate_clarity(content: str) -> Dict:
335
+ """Gate 3: Clarity (0.0-1.0).
336
+
337
+ Checks:
338
+ - ## Decision section has no vague language ('might', 'maybe', 'possibly',
339
+ 'could', 'should consider'): vague_words check
340
+ - ADR has a title (# ADR-NNN title present): +0.3
341
+ - Acronyms defined: check if all-caps words (>=2 letters) appear at least once
342
+ with a definition pattern. If > 3 undefined acronyms: -0.2
343
+ - ## Context section > 50 chars: +0.2
344
+
345
+ Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
346
+ """
347
+ issues: List[QualityIssue] = []
348
+ checks: Dict[str, bool] = {}
349
+
350
+ score = 0.5 # base score
351
+
352
+ # Check Decision section for vague language
353
+ decision_text = _section_text(content, "## Decision")
354
+ has_vague = bool(VAGUE_WORDS_RE.search(decision_text))
355
+ checks["no_vague_language"] = not has_vague
356
+ if has_vague:
357
+ vague_found = VAGUE_WORDS_RE.findall(decision_text)
358
+ issues.append(QualityIssue(
359
+ code="VAGUE_LANGUAGE",
360
+ detail=", ".join(repr(w) for w in vague_found[:5]),
361
+ severity="medium",
362
+ ))
363
+ score -= 0.15
364
+
365
+ # Check ADR has a title heading
366
+ has_title = bool(re.search(r"^#\s+ADR-\d+", content, re.MULTILINE | re.IGNORECASE))
367
+ checks["has_title"] = has_title
368
+ if has_title:
369
+ score += 0.3
370
+ else:
371
+ issues.append(QualityIssue(code="NO_TITLE", severity="high"))
372
+
373
+ # Check acronyms are defined (all-caps words >= 2 letters).
374
+ # Stopwords that are definitely not acronyms.
375
+ acro_stopwords = frozenset({
376
+ "OK", "TO", "BY", "AS", "IS", "ON", "OR", "AN", "AT", "IN", "OF",
377
+ "IF", "DO", "NO", "SO", "UP", "US", "WE", "MY", "IT",
378
+ "ADR", "ID", # ADR is always defined in the context of this tool
379
+ })
380
+ # Words followed by definition patterns: '(', 'stands for', 'means', ':'
381
+ defined_acros = {m.group(1) for m in _ACRO_DEFINED_RE.finditer(content)}
382
+
383
+ undefined_acros = set()
384
+ for m in _ACRO_RE.finditer(content):
385
+ acro = m.group(1)
386
+ if acro not in acro_stopwords and acro not in defined_acros:
387
+ undefined_acros.add(acro)
388
+
389
+ acros_ok = len(undefined_acros) <= 3
390
+ checks["acronyms_defined"] = acros_ok
391
+ if not acros_ok:
392
+ score -= 0.2
393
+ issues.append(QualityIssue(
394
+ code="ACRONYM_UNEXPLAINED",
395
+ detail=", ".join(sorted(undefined_acros)[:5]),
396
+ severity="low",
397
+ ))
398
+
399
+ # Check Context section > 50 chars
400
+ context_text = _section_text(content, "## Context")
401
+ context_len = len(context_text.strip())
402
+ context_ok = context_len > 50
403
+ checks["context_sufficient"] = context_ok
404
+ if context_ok:
405
+ score += 0.2
406
+ else:
407
+ issues.append(QualityIssue(
408
+ code="CONTEXT_TOO_SHORT",
409
+ detail=str(context_len),
410
+ severity="medium",
411
+ ))
412
+
413
+ score = max(0.0, min(1.0, score))
414
+ return {"score": score, "issues": issues, "checks": checks}
415
+
416
+
417
+ def gate_consistency(content: str, adr_dir: Optional[Path] = None) -> Dict:
418
+ """Gate 4: Consistency (0.0-1.0).
419
+
420
+ Checks:
421
+ - ## Related Decisions section not empty (not just 'None.'): +0.4
422
+ - If adr_dir given: check if mentioned ADR-NNN numbers exist: +0.3
423
+ - ## Status section contains a valid status value: +0.3
424
+
425
+ Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
426
+ """
427
+ issues: List[QualityIssue] = []
428
+ checks: Dict[str, bool] = {}
429
+
430
+ score = 0.0
431
+
432
+ # Check Related Decisions not empty
433
+ related_text = _section_text(content, "## Related Decisions")
434
+ related_lines = [
435
+ ln.strip() for ln in related_text.splitlines()
436
+ if ln.strip() and ln.strip().lower() not in ("none.", "none", "-")
437
+ ]
438
+ has_related = bool(related_lines)
439
+ checks["related_decisions_present"] = has_related
440
+ if has_related:
441
+ score += 0.4
442
+ else:
443
+ issues.append(QualityIssue(
444
+ code="NO_RELATED_DECISIONS",
445
+ severity="medium",
446
+ ))
447
+
448
+ # Check if mentioned ADR references exist in adr_dir
449
+ mentioned_adrs = set(ADR_REF_RE.findall(content))
450
+ if adr_dir and adr_dir.is_dir() and mentioned_adrs:
451
+ existing_nums = set()
452
+ for f in adr_dir.glob("ADR-*.md"):
453
+ m = re.match(r"(?i)ADR-(\d+)-", f.name)
454
+ if m:
455
+ existing_nums.add(int(m.group(1)))
456
+ missing_refs = [
457
+ f"ADR-{num}" for num in sorted(mentioned_adrs)
458
+ if int(num) not in existing_nums
459
+ ]
460
+ refs_valid = not missing_refs
461
+ checks["referenced_adrs_exist"] = refs_valid
462
+ if refs_valid:
463
+ score += 0.3
464
+ else:
465
+ issues.append(QualityIssue(
466
+ code="ORPHAN_RELATED_ID",
467
+ detail=", ".join(missing_refs),
468
+ severity="high",
469
+ ))
470
+ elif mentioned_adrs:
471
+ # ADR references found but can't verify — give partial credit
472
+ checks["referenced_adrs_exist"] = True
473
+ score += 0.3
474
+ else:
475
+ checks["referenced_adrs_exist"] = False
476
+ # No ADR references mentioned — don't add to score if no related decisions
477
+ if has_related:
478
+ score += 0.3
479
+
480
+ # Check Status section for a valid status value
481
+ status_text = _section_text(content, "## Status")
482
+ status_match = re.search(r"\b([A-Za-z]+)\b", status_text)
483
+ has_valid_status = False
484
+ if status_match:
485
+ status_word = status_match.group(1).lower()
486
+ has_valid_status = status_word in VALID_STATUSES
487
+ checks["valid_status"] = has_valid_status
488
+ if has_valid_status:
489
+ score += 0.3
490
+ else:
491
+ issues.append(QualityIssue(
492
+ code="INVALID_STATUS",
493
+ detail=", ".join(sorted(VALID_STATUSES)),
494
+ severity="high",
495
+ ))
496
+
497
+ score = max(0.0, min(1.0, score))
498
+ return {"score": score, "issues": issues, "checks": checks}
499
+
500
+
501
+ def _grade(overall: float) -> str:
502
+ if overall >= 0.85:
503
+ return "A"
504
+ if overall >= 0.70:
505
+ return "B"
506
+ if overall >= 0.55:
507
+ return "C"
508
+ return "D"
509
+
510
+
511
+ def _extract_adr_id(adr_path: Path) -> str:
512
+ m = ADR_ID_RE.match(adr_path.name)
513
+ if m:
514
+ return f"ADR-{int(m.group(1)):03d}"
515
+ return adr_path.stem
516
+
517
+
518
+ # Per-code recommendation strings. Driven by the structured issue code rather
519
+ # than human-text matching, so wording changes don't silently break behaviour.
520
+ _RECOMMENDATIONS_BY_CODE: Dict[str, str] = {
521
+ "MISSING_SECTION": "Add the missing required sections listed above",
522
+ "DECISION_TOO_SHORT":
523
+ "Expand ## Decision to > 100 characters explaining the rationale",
524
+ "TOO_FEW_ALTERNATIVES":
525
+ "Add at least 2 alternatives in ## Alternatives Considered "
526
+ "(including 'do nothing')",
527
+ "CONSEQUENCES_EMPTY":
528
+ "Fill in ## Consequences with benefits, trade-offs, and risks",
529
+ "NO_REFERENCES":
530
+ "Add at least one entry to ## References (issue, file, or external link)",
531
+ "NO_MEASUREMENTS":
532
+ "Add measurements to ## Consequences (e.g., '50 ms', '10 MB', '30%')",
533
+ "NO_EXTERNAL_LINK": "Add at least one https:// link in ## References",
534
+ "NO_FILE_LINE_REF":
535
+ "Add a file:line reference (e.g., 'src/main.py:42') in ## References",
536
+ "VAGUE_LANGUAGE":
537
+ "Replace vague language in ## Decision with a concrete, "
538
+ "declarative statement",
539
+ "NO_TITLE": "Add a title heading '# ADR-NNN Title' as the first line",
540
+ "ACRONYM_UNEXPLAINED":
541
+ "Define acronyms on first use, e.g., 'REST (Representational "
542
+ "State Transfer)'",
543
+ "CONTEXT_TOO_SHORT":
544
+ "Expand ## Context to > 50 chars; explain the problem and constraints",
545
+ "NO_RELATED_DECISIONS":
546
+ "Reference related ADRs in ## Related Decisions "
547
+ "(or state 'None' with explanation)",
548
+ "ORPHAN_RELATED_ID":
549
+ "Verify that referenced ADR numbers exist in the docs/adr/ directory",
550
+ "INVALID_STATUS":
551
+ "Set a valid status in ## Status: Proposed, Accepted, Deprecated, "
552
+ "Superseded, or Amended",
553
+ }
554
+
555
+
556
+ def _recommendations_from_issues(issues: List[QualityIssue]) -> List[str]:
557
+ """Generate concrete action items from structured issue codes."""
558
+ recs: List[str] = []
559
+ for issue in issues:
560
+ rec = _RECOMMENDATIONS_BY_CODE.get(issue.code)
561
+ if rec is None:
562
+ recs.append(issue.message())
563
+ else:
564
+ recs.append(rec)
565
+ return recs
566
+
567
+
568
+ def score_adr_quality(content: str, adr_path: Path) -> Dict:
569
+ """Calculate composite quality score.
570
+
571
+ Returns:
572
+ {
573
+ "overall": float, # weighted: completeness*0.4 + evidence*0.2 + clarity*0.2 + consistency*0.2
574
+ "gates": {
575
+ "completeness": {"score": float, "issues": [...], "checks": {...}},
576
+ "evidence": {"score": float, "issues": [...], "checks": {...}},
577
+ "clarity": {"score": float, "issues": [...], "checks": {...}},
578
+ "consistency": {"score": float, "issues": [...], "checks": {...}},
579
+ },
580
+ "issues": List[str], # all issues combined, sorted by severity
581
+ "recommendations": List[str], # concrete action items
582
+ "grade": str, # "A" (>=0.85), "B" (>=0.70), "C" (>=0.55), "D" (<0.55)
583
+ }
584
+ """
585
+ adr_dir = adr_path.parent if adr_path.parent.is_dir() else None
586
+
587
+ comp = gate_completeness(content)
588
+ evid = gate_evidence(content)
589
+ clar = gate_clarity(content)
590
+ cons = gate_consistency(content, adr_dir)
591
+
592
+ overall = (
593
+ comp["score"] * 0.4
594
+ + evid["score"] * 0.2
595
+ + clar["score"] * 0.2
596
+ + cons["score"] * 0.2
597
+ )
598
+ overall = max(0.0, min(1.0, round(overall, 4)))
599
+
600
+ # Single-pass triage: collect all QualityIssues across the four gates,
601
+ # then sort by severity (high -> medium -> low). The previous 12-way
602
+ # comprehension was O(4 * 3 * n) and re-evaluated _severity_label
603
+ # repeatedly; this is O(n log n) with a tiny constant.
604
+ all_issues: List[QualityIssue] = [
605
+ issue
606
+ for gate_result in (comp, evid, clar, cons)
607
+ for issue in gate_result["issues"]
608
+ ]
609
+ all_issues.sort(key=lambda i: SEVERITY_ORDER.get(i.severity, 99))
610
+
611
+ return {
612
+ "overall": overall,
613
+ "grade": _grade(overall),
614
+ "gates": {
615
+ "completeness": comp,
616
+ "evidence": evid,
617
+ "clarity": clar,
618
+ "consistency": cons,
619
+ },
620
+ "issues": all_issues,
621
+ "recommendations": _recommendations_from_issues(all_issues),
622
+ }
623
+
624
+
625
+ # The threshold `bin/adr-quality` has always exited 1 below. Named here so the
626
+ # queue and the readiness report agree with the command rather than each
627
+ # carrying their own number.
628
+ QUALITY_THRESHOLD = 0.70
629
+
630
+
631
+ def score_path(path: Path) -> Optional[Dict]:
632
+ """Score one ADR file. None when it cannot be read -- never raises.
633
+
634
+ Callers on a queue or a hook path must not fail because one record is
635
+ unreadable; adr-lint is what reports a malformed ADR.
636
+ """
637
+ try:
638
+ content = path.read_text(encoding="utf-8", errors="replace")
639
+ except OSError:
640
+ return None
641
+ try:
642
+ return score_adr_quality(content, path)
643
+ except (ValueError, KeyError, re.error):
644
+ return None
645
+
646
+
647
+ def score_directory(adr_dir: Path, statuses: Optional[List[str]] = None) -> Dict[str, Dict]:
648
+ """Score every ADR in a directory, keyed by ADR id.
649
+
650
+ `statuses`, when given, restricts the scan -- the guardian evaluates
651
+ Accepted records on its own cadence so quality decay stays visible instead
652
+ of frozen at the moment of acceptance.
653
+ """
654
+ _load_sibling("adr_schema")
655
+ _load_sibling("adr_catalog")
656
+ from adr_catalog import adr_status, discover_adr_files
657
+
658
+ wanted = {status.casefold() for status in statuses} if statuses else None
659
+ scores: Dict[str, Dict] = {}
660
+ for path in discover_adr_files(adr_dir):
661
+ try:
662
+ content = path.read_text(encoding="utf-8", errors="replace")
663
+ except OSError:
664
+ continue
665
+ if wanted is not None:
666
+ status = (adr_status(content) or "").strip().casefold()
667
+ if status not in wanted:
668
+ continue
669
+ try:
670
+ result = score_adr_quality(content, path)
671
+ except (ValueError, KeyError, re.error):
672
+ continue
673
+ scores[_extract_adr_id(path)] = result
674
+ return scores