@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,843 @@
1
+ """Deterministic, bounded ADR hook core. Read-only except for one narrow write.
2
+
3
+ This file was read-only, and said so here, until ADR-021. It now regenerates a
4
+ stale generated index on `session-start` and `user-prompt-submit` -- and only
5
+ those two, under a lock, only when the projected cost fits the event's declared
6
+ budget, and only ever writing the generated index artefacts. Everything else
7
+ still reads.
8
+
9
+ The exception is stated at the top rather than left to be discovered because the
10
+ read-only property is what makes this file safe to reason about: an edit-tier
11
+ hook fires before every single write a user makes, and a surprise write there is
12
+ not a thing anyone should have to find by grepping. See `refresh_index`.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import fnmatch
18
+ import json
19
+ import os
20
+ import re
21
+ import tempfile
22
+ import sys
23
+ from dataclasses import dataclass
24
+ from pathlib import Path
25
+ from typing import Any
26
+
27
+ _BIN_DIR = Path(__file__).resolve().parents[1] / "bin"
28
+ if str(_BIN_DIR) not in sys.path:
29
+ sys.path.insert(0, str(_BIN_DIR))
30
+
31
+ from adr_query import IndexQueryError, query_adr_context
32
+
33
+ MAX_INPUT_BYTES = 64 * 1024
34
+ MAX_PARENT_CHARS = 8 * 1024
35
+ MAX_CONTEXT_CHARS = 4 * 1024
36
+ # spec.md R5 asks for five relevant ADRs at the moment work begins. This was 3,
37
+ # and the documented knob (context.default_limit) never reached the hook, so a
38
+ # user who set 5 still got 3. Both are fixed: the default is five, and the
39
+ # project setting wins when it is present.
40
+ DEFAULT_MAX_RESULTS = 5
41
+ MAX_RESULTS = DEFAULT_MAX_RESULTS
42
+ QUEUE_CACHE_NAME = ".adr-kit-readiness.json"
43
+ QUEUE_MAX_BYTES = 256 * 1024
44
+ WRITE_TOOLS = {
45
+ "edit",
46
+ "multiedit",
47
+ "write",
48
+ "applypatch",
49
+ "create",
50
+ "notebookedit",
51
+ }
52
+ PLAN_EXIT_TOOLS = {"exitplanmode", "exitplan", "planexit"}
53
+
54
+ # Events this hook accepts and deliberately answers with nothing. Silence here
55
+ # is a decision, not an oversight, so each entry carries its reason: a future
56
+ # reader deciding whether to wire one of these up should inherit the argument
57
+ # rather than re-derive it.
58
+ NOOP_EVENTS = {
59
+ # The three end-of-work events. "Work finished -- were decisions made?" is a
60
+ # real question and this is where it would live, but answering it honestly
61
+ # means reading a whole session, which wants a model. Every hook here is
62
+ # deterministic, model-free and inside a 2 s budget (ADR-015); spending at
63
+ # session end would make this the first hook that costs money, on an event
64
+ # the user cannot see fire. Recorded as a deliberate silence in ADR-019.
65
+ "stop",
66
+ "subagentstop",
67
+ "sessionend",
68
+ # Not about the work at all. A permission dialog and a notification are UI
69
+ # moments; injecting ADR context into either would put architectural text
70
+ # where the user is answering an unrelated question.
71
+ "permissionrequest",
72
+ "notification",
73
+ # The user stopped the agent. Adding output to an interrupt is the one time
74
+ # nobody wants more text.
75
+ "interrupt",
76
+ # Compaction context is injected at PreCompact, while the transcript still
77
+ # exists. Afterwards there is nothing left to carry forward, so a second
78
+ # injection would be new context rather than preserved context.
79
+ "postcompact",
80
+ }
81
+ EVENT_ALIASES = {
82
+ "sessionstart": "SessionStart",
83
+ "userpromptsubmit": "UserPromptSubmit",
84
+ "userpromptsubmitted": "UserPromptSubmit",
85
+ "pretooluse": "PreToolUse",
86
+ "posttooluse": "PostToolUse",
87
+ "subagentstart": "SubagentStart",
88
+ "precompact": "PreCompact",
89
+ "stop": "Stop",
90
+ "subagentstop": "SubagentStop",
91
+ "sessionend": "SessionEnd",
92
+ "permissionrequest": "PermissionRequest",
93
+ "notification": "Notification",
94
+ "interrupt": "Interrupt",
95
+ "postcompact": "PostCompact",
96
+ }
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class Envelope:
101
+ client: str
102
+ client_version: str | None
103
+ event: str
104
+ session_id: str | None
105
+ agent_id: str | None
106
+ workspace: Path
107
+ tool_name: str | None
108
+ tool_input: dict[str, Any]
109
+ prompt: str | None
110
+ parent_context: str | None
111
+
112
+
113
+ def _bounded_text(value: object, limit: int) -> str | None:
114
+ if not isinstance(value, str):
115
+ return None
116
+ return value[:limit]
117
+
118
+
119
+ def _first(payload: dict, *keys: str) -> object:
120
+ for key in keys:
121
+ if key in payload:
122
+ return payload[key]
123
+ return None
124
+
125
+
126
+ def normalize(payload: dict[str, Any], client: str, event: str | None) -> Envelope:
127
+ native = event or _first(payload, "hook_event_name", "hookEventName", "event")
128
+ compact = re.sub(r"[^a-z]", "", str(native or "").lower())
129
+ normalized_event = EVENT_ALIASES.get(compact, str(native or "Unknown"))
130
+ workspace_raw = _first(payload, "cwd", "workspace", "workspace_root")
131
+ workspace = Path(str(workspace_raw or Path.cwd())).expanduser().resolve()
132
+ tool_input = _first(payload, "tool_input", "toolInput", "tool")
133
+ if not isinstance(tool_input, dict):
134
+ tool_input = {}
135
+ tool_name = _bounded_text(
136
+ _first(payload, "tool_name", "toolName", "tool_name_normalized"), 80
137
+ )
138
+ prompt = _bounded_text(
139
+ _first(payload, "prompt", "user_prompt", "userPrompt"), MAX_INPUT_BYTES // 2
140
+ )
141
+ parent = _bounded_text(
142
+ _first(payload, "parent_context", "parentContext", "adr_context"),
143
+ MAX_PARENT_CHARS,
144
+ )
145
+ return Envelope(
146
+ client=client,
147
+ client_version=_bounded_text(
148
+ _first(payload, "client_version", "version"), 80
149
+ ),
150
+ event=normalized_event,
151
+ session_id=_bounded_text(
152
+ _first(payload, "session_id", "sessionId"), 160
153
+ ),
154
+ agent_id=_bounded_text(
155
+ _first(payload, "agent_id", "agentId", "subagent_id"), 160
156
+ ),
157
+ workspace=workspace,
158
+ tool_name=tool_name,
159
+ tool_input=tool_input,
160
+ prompt=prompt,
161
+ parent_context=parent,
162
+ )
163
+
164
+
165
+ def parse_payload(raw: bytes, client: str, event: str | None = None) -> Envelope | None:
166
+ if len(raw) > MAX_INPUT_BYTES:
167
+ return None
168
+ try:
169
+ payload = json.loads(raw.decode("utf-8")) if raw.strip() else {}
170
+ except (UnicodeError, json.JSONDecodeError):
171
+ return None
172
+ if not isinstance(payload, dict) or payload.get("adr_kit_disabled") is True:
173
+ return None
174
+ return normalize(payload, client, event)
175
+
176
+
177
+ def duplicate_event(envelope: Envelope) -> bool:
178
+ """Best-effort cross-process dedupe in OS temp; failures stay fail-open."""
179
+ if not envelope.session_id:
180
+ return False
181
+ path_value = _first(
182
+ envelope.tool_input, "file_path", "filePath", "path", "notebook_path"
183
+ )
184
+ signature = json.dumps(
185
+ [
186
+ envelope.event,
187
+ envelope.tool_name,
188
+ path_value,
189
+ envelope.prompt,
190
+ envelope.agent_id,
191
+ ],
192
+ ensure_ascii=False,
193
+ separators=(",", ":"),
194
+ )
195
+ safe_session = re.sub(r"[^A-Za-z0-9._-]", "_", envelope.session_id)[:80]
196
+ state = Path(tempfile.gettempdir()) / f"adr-kit-hook-{safe_session}.seen"
197
+ try:
198
+ if state.is_file() and state.read_text(encoding="utf-8") == signature:
199
+ return True
200
+ temporary = state.with_suffix(f".{os.getpid()}.tmp")
201
+ temporary.write_text(signature, encoding="utf-8")
202
+ os.replace(temporary, state)
203
+ except OSError:
204
+ return False
205
+ return False
206
+
207
+
208
+ def _index_path(workspace: Path) -> Path | None:
209
+ candidates = (
210
+ workspace / "docs" / "adr" / "ADR-INDEX.json",
211
+ workspace / "adr" / "ADR-INDEX.json",
212
+ )
213
+ for path in candidates:
214
+ if path.is_file():
215
+ return path
216
+ return None
217
+
218
+
219
+ def load_index_records(workspace: Path) -> list[dict[str, Any]]:
220
+ path = _index_path(workspace)
221
+ if path is None or path.stat().st_size > 2 * 1024 * 1024:
222
+ return []
223
+ try:
224
+ payload = json.loads(path.read_text(encoding="utf-8"))
225
+ except (OSError, UnicodeError, json.JSONDecodeError):
226
+ return []
227
+ records = payload.get("adrs", []) if isinstance(payload, dict) else []
228
+ return [item for item in records if isinstance(item, dict)]
229
+
230
+
231
+ def load_records(workspace: Path) -> list[dict[str, Any]]:
232
+ return [
233
+ item for item in load_index_records(workspace) if item.get("status") == "Accepted"
234
+ ]
235
+
236
+
237
+ def load_queue_context(workspace: Path) -> str:
238
+ """Read the prepared Proposed queue only; missing/stale/corrupt fails open."""
239
+ path = workspace / "docs" / "adr" / QUEUE_CACHE_NAME
240
+ try:
241
+ if not path.is_file() or path.stat().st_size > QUEUE_MAX_BYTES:
242
+ return ""
243
+ payload = json.loads(path.read_text(encoding="utf-8"))
244
+ if not isinstance(payload, dict) or payload.get("schema_version") != 1:
245
+ return ""
246
+ from datetime import datetime, timezone
247
+
248
+ expires_at = datetime.fromisoformat(str(payload["expires_at"]))
249
+ if expires_at.tzinfo is None:
250
+ expires_at = expires_at.replace(tzinfo=timezone.utc)
251
+ if datetime.now(timezone.utc) >= expires_at.astimezone(timezone.utc):
252
+ return ""
253
+ except (OSError, UnicodeError, json.JSONDecodeError, KeyError, TypeError, ValueError):
254
+ return ""
255
+ lines = ["Proposed ADR decision queue (derived, non-authoritative):"]
256
+ count = 0
257
+ for item in payload.get("actions", []):
258
+ if not isinstance(item, dict):
259
+ continue
260
+ adr_id = str(item.get("adr_id", ""))
261
+ command = str(item.get("command", ""))
262
+ if not re.fullmatch(r"ADR-\d{3,4}", adr_id):
263
+ continue
264
+ if command != f"/adr-kit:grill {adr_id}":
265
+ continue
266
+ reasons = [
267
+ re.sub(r"[\r\n]+", " ", str(reason))[:160]
268
+ for reason in item.get("reasons", [])
269
+ if str(reason)
270
+ ][:2]
271
+ lines.append(f"- {adr_id}: {', '.join(reasons)} -> {command}")
272
+ count += 1
273
+ if count == MAX_RESULTS:
274
+ break
275
+ return "\n".join(lines)[:MAX_CONTEXT_CHARS] if count else ""
276
+
277
+
278
+ def _tokens(text: str) -> set[str]:
279
+ return {
280
+ token
281
+ for token in re.findall(r"[a-z0-9][a-z0-9._/-]{2,}", text.lower())
282
+ if token not in {"the", "and", "for", "with", "from", "this", "that"}
283
+ }
284
+
285
+
286
+ def _record_text(record: dict[str, Any]) -> str:
287
+ scope = record.get("scope", {})
288
+ globs = scope.get("path_globs", []) if isinstance(scope, dict) else []
289
+ return " ".join(
290
+ [
291
+ str(record.get("id", "")),
292
+ str(record.get("title", "")),
293
+ str(record.get("decision_summary", "")),
294
+ " ".join(str(value) for value in globs),
295
+ ]
296
+ )
297
+
298
+
299
+ def rank(records: list[dict[str, Any]], query: str) -> list[dict[str, Any]]:
300
+ query_tokens = _tokens(query)
301
+ scored = []
302
+ for record in records:
303
+ overlap = len(query_tokens & _tokens(_record_text(record)))
304
+ scored.append((overlap, str(record.get("id", "")), record))
305
+ scored.sort(key=lambda item: (-item[0], item[1]))
306
+ positive = [record for score, _id, record in scored if score > 0]
307
+ return (positive or [item[2] for item in scored])[:MAX_RESULTS]
308
+
309
+
310
+ def _project_config(workspace: Path) -> dict[str, Any]:
311
+ """The project config, or an empty one. Never raises; never blocks a hook."""
312
+ try:
313
+ raw = json.loads(
314
+ (workspace / "docs" / "adr" / ".adr-kit.json").read_text(encoding="utf-8")
315
+ )
316
+ except (OSError, ValueError):
317
+ return {}
318
+ return raw if isinstance(raw, dict) else {}
319
+
320
+
321
+ def _switched_off(workspace: Path, block: str) -> bool:
322
+ """Honour `inject.enabled` and `watch.enabled` from the project config.
323
+
324
+ Both keys shipped in `schemas/adr-kit-config.schema.json` describing exactly
325
+ this behaviour -- "when false, the PreToolUse injector never emits context
326
+ and the hook is a no-op for this project" -- and neither was read by anything
327
+ a hook reaches. `inject.enabled` had one reader, `bin/adr-watch`, which no
328
+ client's `hooks.json` invokes. So a user who turned injection off was told
329
+ the hook was now a no-op, and the injection kept firing.
330
+
331
+ `guardian.enabled` has worked this way since v0.18, so the pattern is the
332
+ kit's own rather than a new invention. Only an explicit `false` switches a
333
+ tier off: a missing key, a missing file and a malformed file all mean on,
334
+ because a settings surface must not be able to silence governance by being
335
+ unreadable.
336
+ """
337
+ block_config = _project_config(workspace).get(block)
338
+ if not isinstance(block_config, dict):
339
+ return False
340
+ return block_config.get("enabled") is False
341
+
342
+
343
+ def _configured_limit(workspace: Path) -> int:
344
+ """context.default_limit when set, else the default. Bounded and fail-soft.
345
+
346
+ Read here rather than threaded through, because the hook is the one caller
347
+ that used to ignore it. The bound keeps a typo from turning one prompt into
348
+ a context flood.
349
+ """
350
+ value = (_project_config(workspace).get("context") or {}).get("default_limit")
351
+ if isinstance(value, int) and 1 <= value <= 20:
352
+ return value
353
+ return DEFAULT_MAX_RESULTS
354
+
355
+ # Only these two may write. They carry a 500 ms budget; the edit-tier events
356
+ # carry far less and cannot hold a render at any realistic ADR count (ADR-021).
357
+ # R5: retrieval narrows, the model chooses. Appended after the candidate lists
358
+ # at prompt time; both hosts carry the same text and the parity test pins it.
359
+ PROMPT_SELECTION_INSTRUCTION = (
360
+ "These are retrieval candidates, not confirmed matches: apply "
361
+ "the ones that actually govern this work and ignore the rest."
362
+ )
363
+
364
+
365
+ def _prompt_candidates_context(parts: "list[str]") -> str:
366
+ """Join candidate sections and append the selection instruction, in budget.
367
+
368
+ The instruction is the one line that must never be lost: without it the
369
+ candidate list reads as settled relevance again. So its length is reserved
370
+ up front and the CANDIDATES are truncated to make room — appending first
371
+ and slicing afterwards cut the instruction precisely when the candidate
372
+ set was biggest. The native host mirrors this arithmetic.
373
+ """
374
+ candidates = "\n".join(parts)
375
+ room = MAX_CONTEXT_CHARS - len(PROMPT_SELECTION_INSTRUCTION) - 1
376
+ if len(candidates) > room:
377
+ candidates = candidates[:room]
378
+ return candidates + "\n" + PROMPT_SELECTION_INSTRUCTION
379
+
380
+
381
+ REFRESHING_EVENTS = {"SessionStart", "UserPromptSubmit"}
382
+
383
+ STALE_INDEX_MESSAGE = (
384
+ "The generated ADR index is stale, so ADR context is unavailable for this "
385
+ "step. Run `bin/adr-index docs/adr` to regenerate it."
386
+ )
387
+
388
+
389
+ def index_is_stale(workspace: Path) -> bool:
390
+ """Cheap precondition, ~2.8 ms measured, not a certification.
391
+
392
+ `index_probably_fresh` is an mtime comparison and says so in its own
393
+ docstring. Used here to avoid work, never to certify a result -- the caller
394
+ treats a false negative as "read what is there", which is what it would have
395
+ done anyway.
396
+ """
397
+ index = _index_path(workspace)
398
+ if index is None:
399
+ return False
400
+ try:
401
+ from adr_index_core import index_probably_fresh
402
+
403
+ return not index_probably_fresh(index.parent)
404
+ except (ImportError, OSError, ValueError):
405
+ return False
406
+
407
+
408
+ def refresh_index(workspace: Path, event: str) -> str:
409
+ """Regenerate a stale index in place, when this event may and can afford it.
410
+
411
+ Returns "" when nothing needed doing or the regeneration succeeded, and the
412
+ staleness message otherwise. The message matters more than the write: an
413
+ agent that gets silence from a stale index cannot tell it from "no ADR was
414
+ relevant", and that silence is the defect ADR-021 exists to remove.
415
+
416
+ Every failure path here returns the message rather than raising. This runs
417
+ inside a fail-open hook, and a governance tool that breaks a session is
418
+ worse than one that asks for a command to be run.
419
+ """
420
+ if not index_is_stale(workspace):
421
+ return ""
422
+ if event not in REFRESHING_EVENTS:
423
+ # The edit tier reads only. Rendering there would put a write on the
424
+ # path taken before every single edit.
425
+ return STALE_INDEX_MESSAGE
426
+
427
+ index = _index_path(workspace)
428
+ if index is None:
429
+ return STALE_INDEX_MESSAGE
430
+ adr_dir = index.parent
431
+
432
+ try:
433
+ from adr_index_core import projected_render_ms, regenerate_index
434
+ except ImportError:
435
+ return STALE_INDEX_MESSAGE
436
+
437
+ budget_ms = _event_budget_ms(event)
438
+ projected = projected_render_ms(adr_dir)
439
+ if projected > budget_ms:
440
+ # A large ADR set degrades to a nudge rather than to a timeout. The
441
+ # client kills the hook at its own bound, and a process killed mid-write
442
+ # is worse than one that never started.
443
+ return STALE_INDEX_MESSAGE
444
+
445
+ lock = adr_dir / ".adr-index.lock"
446
+ try:
447
+ # O_EXCL is the whole lock: whoever creates the file owns the render.
448
+ handle = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
449
+ except FileExistsError:
450
+ # Another session is rendering. Read what is there and continue -- ADR-021
451
+ # forbids waiting, because the loser would spend a budget it cannot
452
+ # recover on work someone else is already doing.
453
+ return STALE_INDEX_MESSAGE
454
+ except OSError:
455
+ return STALE_INDEX_MESSAGE
456
+
457
+ try:
458
+ os.close(handle)
459
+ regenerate_index(adr_dir)
460
+ return ""
461
+ except (OSError, ValueError, KeyError, TypeError):
462
+ return STALE_INDEX_MESSAGE
463
+ finally:
464
+ try:
465
+ lock.unlink()
466
+ except OSError:
467
+ pass
468
+
469
+
470
+ def _event_budget_ms(event: str) -> float:
471
+ """This event's declared budget, from the manifest the client enforces.
472
+
473
+ Read rather than hardcoded for the same reason the pull-request guard reads
474
+ its own: whoever changes the manifest changes this, and the two cannot drift
475
+ into disagreeing.
476
+ """
477
+ manifest = Path(__file__).resolve().parent / "manifest.json"
478
+ wanted = {"SessionStart": "session-start", "UserPromptSubmit": "user-prompt-submit"}
479
+ try:
480
+ events = json.loads(manifest.read_text(encoding="utf-8"))["events"]
481
+ return float(
482
+ next(
483
+ entry["latency"]["p50_ms"]
484
+ for entry in events
485
+ if entry.get("id") == wanted.get(event)
486
+ )
487
+ )
488
+ except (OSError, ValueError, KeyError, TypeError, StopIteration):
489
+ return 400.0
490
+
491
+
492
+ def _query(
493
+ workspace: Path,
494
+ query: str,
495
+ *,
496
+ path: str | None = None,
497
+ ) -> list[dict[str, Any]]:
498
+ """Rank the ADRs for this query, lexically over the generated index.
499
+
500
+ This file must not be able to reach a model or the network -- a test
501
+ asserts that by walking its imports (ADR-036 retired the one exception
502
+ ADR-020 had carved out for query embedding).
503
+ """
504
+ index = _index_path(workspace)
505
+ if index is None:
506
+ return []
507
+ limit = _configured_limit(workspace)
508
+ try:
509
+ outcome = query_adr_context(
510
+ query,
511
+ index.parent,
512
+ limit=limit,
513
+ strict_index=True,
514
+ include_history=False,
515
+ statuses=("Accepted", "Proposed"),
516
+ paths=(path,) if path else (),
517
+ )
518
+ except (IndexQueryError, OSError, UnicodeError, ValueError):
519
+ return []
520
+ return [
521
+ item
522
+ for item in outcome["results"]
523
+ if item.get("status") in {"Accepted", "Proposed"}
524
+ ][:limit]
525
+
526
+
527
+ def _safe_edit_path(envelope: Envelope) -> Path | None:
528
+ value = _first(
529
+ envelope.tool_input, "file_path", "filePath", "path", "notebook_path"
530
+ )
531
+ if not isinstance(value, str) or len(value) > 4096:
532
+ return None
533
+ candidate = Path(value).expanduser()
534
+ if not candidate.is_absolute():
535
+ candidate = envelope.workspace / candidate
536
+ resolved = candidate.resolve()
537
+ try:
538
+ resolved.relative_to(envelope.workspace)
539
+ except ValueError:
540
+ return None
541
+ return resolved
542
+
543
+
544
+ def _matching_path_records(
545
+ records: list[dict[str, Any]], workspace: Path, path: Path
546
+ ) -> list[dict[str, Any]]:
547
+ relative = path.relative_to(workspace).as_posix()
548
+ matches = []
549
+ for record in records:
550
+ scope = record.get("scope", {})
551
+ globs = scope.get("path_globs", []) if isinstance(scope, dict) else []
552
+ if any(fnmatch.fnmatchcase(relative, str(pattern)) for pattern in globs):
553
+ matches.append(record)
554
+ return matches or rank(records, relative)
555
+
556
+
557
+ def _render(records: list[dict[str, Any]], heading: str) -> str:
558
+ if not records:
559
+ return ""
560
+ lines = [heading]
561
+ for record in records[:MAX_RESULTS]:
562
+ raw_path = str(record.get("path", ""))
563
+ source = f"docs/adr/{Path(raw_path).name}"
564
+ adr_id = record.get("id") or record.get("adr_id")
565
+ lines.append(
566
+ f"- {adr_id}: {record.get('title')} — "
567
+ f"{record.get('decision_summary')} (source: {source})"
568
+ )
569
+ return "\n".join(lines)[:MAX_CONTEXT_CHARS]
570
+
571
+
572
+ def _client_grill(client: str, arguments: str) -> str:
573
+ prefix = {
574
+ "claude-code-cli": "/adr-kit:grill",
575
+ "codex-cli": "$adr-kit:grill",
576
+ "github-copilot-cli": "adr-kit:grill",
577
+ }.get(client, "adr-kit:grill")
578
+ return f"{prefix} {arguments}"
579
+
580
+
581
+ def _safe_source_argument(path: str) -> str | None:
582
+ if not re.fullmatch(r"[A-Za-z0-9_./\\ -]{1,4096}", path):
583
+ return None
584
+ return '"' + path.replace("\\", "/").replace('"', '\\"') + '"'
585
+
586
+
587
+ def _proposed_advisory(
588
+ proposed: list[dict[str, Any]],
589
+ relative: str,
590
+ client: str,
591
+ ) -> str:
592
+ linked = []
593
+ for record in proposed:
594
+ metadata = record.get("metadata", {})
595
+ verified = metadata.get("verified_in", []) if isinstance(metadata, dict) else []
596
+ scope = record.get("scope", {})
597
+ globs = scope.get("path_globs", []) if isinstance(scope, dict) else []
598
+ if any(
599
+ fnmatch.fnmatchcase(relative.casefold(), str(value).casefold())
600
+ or relative.casefold() == str(value).replace("\\", "/").casefold()
601
+ for value in list(verified) + list(globs)
602
+ ):
603
+ linked.append(record)
604
+ lines = []
605
+ for record in sorted(linked, key=lambda item: str(item.get("id", "")))[:MAX_RESULTS]:
606
+ adr_id = str(record.get("id", ""))
607
+ if re.fullmatch(r"ADR-\d{3,4}", adr_id):
608
+ lines.append(
609
+ f"Proposed ADR implementation link: {adr_id} -> "
610
+ f"{_client_grill(client, adr_id)}"
611
+ )
612
+ if not lines and re.search(
613
+ r"(^|/)(?:architecture|infra(?:structure)?|migrations?|schemas?|"
614
+ r"api|contracts?|config|deploy|security)(?:/|[-_.])|"
615
+ r"(^|/)(?:dockerfile|compose\.ya?ml|pyproject\.toml|package\.json|"
616
+ r"Cargo\.toml|go\.mod)$",
617
+ relative,
618
+ re.IGNORECASE,
619
+ ):
620
+ quoted = _safe_source_argument(relative)
621
+ if quoted:
622
+ lines.append(
623
+ "Possible durable architecture decision -> "
624
+ + _client_grill(client, f"--source {quoted}")
625
+ )
626
+ return "\n".join(lines)[:MAX_CONTEXT_CHARS]
627
+
628
+
629
+ def _plan_text(envelope: Envelope) -> str:
630
+ """The plan a plan-exit tool call carries, bounded like every other input."""
631
+ raw = _first(envelope.tool_input, "plan", "content", "text", "summary")
632
+ return (_bounded_text(raw, MAX_CONTEXT_CHARS) or "").strip()
633
+
634
+
635
+ #: Both lists must hit on one line before it counts as a candidate. Verb-only
636
+ #: matches every imperative bullet in any plan; noun-only matches prose that
637
+ #: merely mentions the architecture. Precision is the constraint: a nudge that
638
+ #: names noise teaches the reader to skip the nudge (spec B1: deterministic,
639
+ #: injection-only; the model reading the context does the actual judging).
640
+ _DECISION_VERBS = re.compile(
641
+ r"(?i)\b(add|adopt|introduce|switch|migrate|replace|choose|pick|drop|"
642
+ r"remove|rewrite|standardi[sz]e|upgrade|consolidate|split|pin|use)\b"
643
+ )
644
+ _DECISION_NOUNS = re.compile(
645
+ r"(?i)\b(dependenc\w+|librar\w+|framework|database|storage|cache|queue|"
646
+ r"protocol|api|interface|contract|schema|auth\w*|encryption|format|"
647
+ r"service|endpoint|runtime|package|backend|index|pipeline|architecture)\b"
648
+ )
649
+
650
+
651
+ def _plan_decision_candidates(plan: str, limit: int = 5) -> list[str]:
652
+ """Decision-shaped lines in the plan, found deterministically.
653
+
654
+ Named so the question below lands on something concrete: "does this plan
655
+ decide anything?" is easy to wave past, "this line looks like a decision"
656
+ is not. Bounded because the sixth candidate adds noise, not signal.
657
+ """
658
+ found: list[str] = []
659
+ for raw in plan.splitlines():
660
+ line = raw.strip().lstrip("-*#0123456789. ").strip()
661
+ if not line or len(line) > 240:
662
+ continue
663
+ if _DECISION_VERBS.search(line) and _DECISION_NOUNS.search(line):
664
+ found.append(line)
665
+ if len(found) >= limit:
666
+ break
667
+ return found
668
+
669
+
670
+ def _plan_decision_prompt(client: str) -> str:
671
+ """Ask the question this moment exists for.
672
+
673
+ Deliberately a question and not a gate. A hook that blocked here would teach
674
+ people to write an empty ADR to get past it, which is the failure mode that
675
+ produced six rule-less Enforcement blocks in this very repository.
676
+ """
677
+ return (
678
+ "Before leaving plan mode: does this plan make an architectural decision "
679
+ "no ADR records yet? A new dependency, an interface or contract change, a "
680
+ "shift in a non-functional requirement, or a new pattern all qualify. If "
681
+ "so, write it now with " + _client_grill(client, "") + " while the "
682
+ "reasoning is still in front of you; afterwards it becomes justification."
683
+ )
684
+
685
+ def evaluate(envelope: Envelope) -> tuple[str, str]:
686
+ """Refresh a stale index where the budget allows, then render the context.
687
+
688
+ An agent that writes docs/adr/ADR-NNN.md directly -- the common case in a
689
+ harness -- leaves the generated index stale. `query_adr_context` then raises
690
+ IndexQueryError, `_query` swallows it into an empty list, and ADR injection
691
+ goes dark for the rest of the session with no message at all. Silence is the
692
+ defect ADR-021 exists to remove: an empty answer reads exactly like "no ADR
693
+ was relevant".
694
+
695
+ Wrapped rather than inlined so every return path in the renderer carries the
696
+ notice. Missing one of them would reproduce the silence on exactly the
697
+ branch nobody thought about.
698
+ """
699
+ try:
700
+ notice = refresh_index(envelope.workspace, envelope.event)
701
+ except Exception: # noqa: BLE001 -- fail-open is this file's contract
702
+ notice = STALE_INDEX_MESSAGE
703
+
704
+ context, kind = _evaluate_context(envelope)
705
+ if not notice:
706
+ return context, kind
707
+ if not context:
708
+ return notice, "stale-index"
709
+ return "\n\n".join((notice, context))[:MAX_CONTEXT_CHARS], kind
710
+
711
+
712
+ def _evaluate_context(envelope: Envelope) -> tuple[str, str]:
713
+ """Render the context for this moment."""
714
+ compact_event = re.sub(r"[^a-z]", "", envelope.event.lower())
715
+ if compact_event in NOOP_EVENTS:
716
+ return "", "noop"
717
+ if envelope.event == "SubagentStart":
718
+ context = (envelope.parent_context or "")[:MAX_CONTEXT_CHARS]
719
+ return (context, "subagent") if context else ("", "noop")
720
+ if envelope.event == "PreCompact":
721
+ context = (envelope.parent_context or "")[:MAX_CONTEXT_CHARS]
722
+ return (context, "compact") if context else ("", "noop")
723
+
724
+ all_records = load_index_records(envelope.workspace)
725
+ records = [item for item in all_records if item.get("status") == "Accepted"]
726
+ proposed = [item for item in all_records if item.get("status") == "Proposed"]
727
+ if envelope.event == "SessionStart":
728
+ global_records = sorted(
729
+ (
730
+ item
731
+ for item in records
732
+ if item.get("context_scope") == "global"
733
+ ),
734
+ key=lambda item: str(item.get("id", "")),
735
+ )
736
+ parts = [
737
+ part
738
+ for part in (
739
+ _render(
740
+ global_records[:MAX_RESULTS],
741
+ "Global Accepted ADR orientation:",
742
+ ),
743
+ load_queue_context(envelope.workspace),
744
+ )
745
+ if part
746
+ ]
747
+ return ("\n\n".join(parts)[:MAX_CONTEXT_CHARS], "session") if parts else ("", "noop")
748
+ if not records and envelope.event not in {"PreToolUse", "PostToolUse"}:
749
+ return "", "noop"
750
+ if envelope.event == "UserPromptSubmit":
751
+ selected = _query(envelope.workspace, envelope.prompt or "")
752
+ governing = [item for item in selected if item.get("status") == "Accepted"]
753
+ advisory = [item for item in selected if item.get("status") == "Proposed"]
754
+ parts = [
755
+ part
756
+ for part in (
757
+ _render(governing, "Accepted ADR candidates for this prompt (retrieval-ranked):"),
758
+ _render(advisory, "Proposed ADR candidates for this prompt (advisory):"),
759
+ )
760
+ if part
761
+ ]
762
+ if not parts:
763
+ return "", "noop"
764
+ # R5: retrieval narrows, the model chooses. The old heading asserted
765
+ # relevance ("relevant to this prompt"), which read as a settled
766
+ # answer; candidates plus one selection instruction hand the final
767
+ # relevance call to the session model without spending a model call
768
+ # in the hook itself (ADR-036). The instruction's length is reserved
769
+ # in _prompt_candidates_context: append-then-slice cut it precisely
770
+ # when the candidate set was biggest.
771
+ return _prompt_candidates_context(parts), "prompt"
772
+ if envelope.event in {"PreToolUse", "PostToolUse"}:
773
+ tool = (envelope.tool_name or "").lower().replace("_", "")
774
+ if envelope.event == "PreToolUse" and tool in PLAN_EXIT_TOOLS:
775
+ # Leaving plan mode: the plan is complete and no code exists yet.
776
+ # Cheapest moment to notice a missing decision, and the only one
777
+ # where the answer can still shape the implementation instead of
778
+ # justifying it afterwards. Same contract as every other hook:
779
+ # deterministic, injection-only, model-free, never blocking.
780
+ plan = _plan_text(envelope)
781
+ if not plan:
782
+ return "", "noop"
783
+ selected = _query(envelope.workspace, plan)
784
+ governing = [item for item in selected if item.get("status") == "Accepted"]
785
+ advisory = [item for item in selected if item.get("status") == "Proposed"]
786
+ candidates = _plan_decision_candidates(plan)
787
+ named = (
788
+ "Decision-shaped lines in this plan - each either falls under "
789
+ "an ADR above or needs a new one:\n"
790
+ + "\n".join(f"- {line}" for line in candidates)
791
+ if candidates
792
+ else ""
793
+ )
794
+ parts = [
795
+ part
796
+ for part in (
797
+ _render(governing, "ADRs that govern this plan:"),
798
+ _render(advisory, "Advisory Proposed ADRs for this plan:"),
799
+ named,
800
+ _plan_decision_prompt(envelope.client),
801
+ )
802
+ if part
803
+ ]
804
+ joined = "\n".join(parts)[:MAX_CONTEXT_CHARS]
805
+ return (joined, "plan-exit") if parts else ("", "noop")
806
+ if tool not in WRITE_TOOLS:
807
+ return "", "noop"
808
+ # The edit tier is switchable per project, which is what the config
809
+ # schema has claimed since it shipped. PreToolUse is `inject`, PostToolUse
810
+ # is `watch`; they are separate because a team may want the pre-edit
811
+ # constraint without the post-edit backstop, or the reverse.
812
+ if _switched_off(
813
+ envelope.workspace,
814
+ "inject" if envelope.event == "PreToolUse" else "watch",
815
+ ):
816
+ return "", "noop"
817
+ path = _safe_edit_path(envelope)
818
+ if path is None:
819
+ return "", "noop"
820
+ relative = path.relative_to(envelope.workspace).as_posix()
821
+ selected = _query(envelope.workspace, relative, path=relative)
822
+ governing = [item for item in selected if item.get("status") == "Accepted"]
823
+ advisory = [item for item in selected if item.get("status") == "Proposed"]
824
+ heading = (
825
+ "Governing Accepted ADRs before this edit:"
826
+ if envelope.event == "PreToolUse"
827
+ else "Post-edit ADR backstop; verify this change against:"
828
+ )
829
+ context_parts = [
830
+ part
831
+ for part in (
832
+ _render(governing, heading),
833
+ _render(advisory, "Advisory Proposed ADRs for this edit:"),
834
+ _proposed_advisory(
835
+ proposed, relative, envelope.client
836
+ ),
837
+ )
838
+ if part
839
+ ]
840
+ return "\n".join(context_parts)[:MAX_CONTEXT_CHARS], (
841
+ "pre-edit" if envelope.event == "PreToolUse" else "post-edit"
842
+ )
843
+ return "", "noop"