@rvdbreemen/adr-kit-opencode 0.52.0 → 0.52.2

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 (82) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +861 -850
  3. package/bin/adr +0 -0
  4. package/bin/adr-audit +0 -0
  5. package/bin/adr-context +0 -0
  6. package/bin/adr-discover +0 -0
  7. package/bin/adr-doctor +0 -0
  8. package/bin/adr-generate-scripts +0 -0
  9. package/bin/adr-grill-signal +0 -0
  10. package/bin/adr-guardian +0 -0
  11. package/bin/adr-index +0 -0
  12. package/bin/adr-judge +0 -0
  13. package/bin/adr-judge-precommit +0 -0
  14. package/bin/adr-lint +0 -0
  15. package/bin/adr-mcp +0 -0
  16. package/bin/adr-migrate +0 -0
  17. package/bin/adr-quality +0 -0
  18. package/bin/adr-readiness +0 -0
  19. package/bin/adr-readiness-ci +0 -0
  20. package/bin/adr-related +0 -0
  21. package/bin/adr-renumber +254 -254
  22. package/bin/adr-retire +0 -0
  23. package/bin/adr-settings +0 -0
  24. package/bin/adr-status +0 -0
  25. package/bin/adr-suggest +0 -0
  26. package/bin/adr-watch +0 -0
  27. package/bin/bump-version +0 -0
  28. package/clients/workflows.json +229 -229
  29. package/hooks/__init__.py +1 -1
  30. package/hooks/adapters/__init__.py +13 -13
  31. package/hooks/adapters/claude.py +27 -27
  32. package/hooks/adapters/codex.py +26 -26
  33. package/hooks/adapters/copilot.py +11 -11
  34. package/hooks/adr-hook.py +128 -128
  35. package/hooks/adr_hook_core.py +843 -843
  36. package/hooks/adr_pr_guard.py +367 -367
  37. package/instructions/ADR-guide.md +48 -48
  38. package/instructions/adr.coding.md +82 -82
  39. package/instructions/adr.review.md +182 -182
  40. package/opencode/plugin.ts +1 -4
  41. package/package.json +5 -2
  42. package/schemas/adr-context-probes.schema.json +56 -56
  43. package/schemas/adr-enforcement.schema.json +57 -57
  44. package/schemas/adr-frontmatter.schema.json +144 -144
  45. package/schemas/adr-index.schema.json +276 -276
  46. package/schemas/adr-kit-config.schema.json +371 -371
  47. package/schemas/adr-readiness.schema.json +41 -41
  48. package/schemas/client-capabilities.schema.json +503 -503
  49. package/schemas/client-certification.schema.json +101 -101
  50. package/schemas/doctor-output.schema.json +92 -92
  51. package/skills/adr/SKILL.md +780 -780
  52. package/skills/audit/SKILL.md +103 -103
  53. package/skills/context/SKILL.md +77 -77
  54. package/skills/grill/SKILL.md +84 -84
  55. package/skills/grill/agents/openai.yaml +4 -4
  56. package/skills/guardian/SKILL.md +316 -316
  57. package/skills/init/SKILL.md +499 -499
  58. package/skills/install-hooks/SKILL.md +154 -154
  59. package/skills/judge/SKILL.md +168 -168
  60. package/skills/lint/SKILL.md +321 -321
  61. package/skills/migrate/SKILL.md +313 -313
  62. package/skills/related/SKILL.md +62 -62
  63. package/skills/retire/SKILL.md +41 -41
  64. package/skills/review/SKILL.md +167 -167
  65. package/skills/settings/SKILL.md +73 -73
  66. package/skills/setup/SKILL.md +128 -128
  67. package/skills/supersede/SKILL.md +136 -136
  68. package/skills/upgrade/SKILL.md +273 -273
  69. package/templates/adr-kit-guide.md +354 -354
  70. package/templates/adr-template.canonical.md +115 -115
  71. package/templates/adr-template.madr.md +131 -131
  72. package/templates/adr-template.md +131 -131
  73. package/templates/adr-template.nygard.md +111 -111
  74. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  75. package/templates/githooks/pre-commit +1 -1
  76. package/templates/github-workflows/adr-audit.yml +58 -58
  77. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  78. package/templates/github-workflows/adr-index-check.yml +30 -30
  79. package/templates/github-workflows/adr-judge.yml +31 -31
  80. package/templates/github-workflows/adr-readiness.yml +18 -18
  81. package/templates/validate_adr_template.py +38 -38
  82. package/templates/validate_adr_template.sh +74 -74
@@ -1,354 +1,354 @@
1
- <!-- adr-kit-guide v0.52.0 -->
2
- <!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
3
- <!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
4
-
5
- # ADR Kit Guide
6
-
7
- This project uses [adr-kit](https://github.com/rvdbreemen/adr-kit) to manage Architecture Decision Records. The kit ships:
8
-
9
- - a project-side guide (this file) referenced from `CLAUDE.md`,
10
- - a library of slash commands and a subagent for ADR authorship,
11
- - a pre-commit hook that catches code changes drifting outside accepted ADRs.
12
-
13
- ADR files live at `docs/adr/ADR-NNN-kebab-case-title.md`. They are versioned, immutable once accepted, and the durable record of *why* the codebase looks the way it does.
14
-
15
- ## Three operating modes
16
-
17
- | Mode | When | Entry point |
18
- |---|---|---|
19
- | **Init / bootstrap** | Once per project: scan source + docs, propose a starter ADR set, hook the kit into `CLAUDE.md`, install the pre-commit hook | `/adr-kit:init` |
20
- | **Per-commit verification** | Every `git commit`: declarative-rule check (always-on, free). The LLM judge for `llm_judge: true` ADRs is **on by default** as of v0.43.0 (ADR-017) and runs on the host agent's own model, with no model pinned. Falls back to declarative-only when the backend is unavailable | `.githooks/pre-commit` (auto) |
21
- | **On-demand invocation** | Mid-session: write or grill an ADR, judge a staged diff, supersede an existing decision | `/adr-kit:adr`, `/adr-kit:grill`, `/adr-kit:judge`, `adr-generator` subagent |
22
- | **Guardian (v0.18+)** | Periodic staleness detector at SessionStart; in-session model runs due health tiers | `bin/adr-guardian` (hook, free) + `/adr-kit:guardian` (sweep) |
23
-
24
- ## Slash commands
25
-
26
- | Command | Purpose | User-only? |
27
- |---|---|---|
28
- | `/adr-kit:init` | One-shot project bootstrap (audit codebase, generate ADRs, install hook). Combines `setup` + audit + `install-hooks`. | yes |
29
- | `/adr-kit:adr` | Author a single ADR (delegates to `adr-generator` subagent; runs four verification gates). | no — model can self-call |
30
- | `/adr-kit:grill` | Complete a Proposed ADR, reconstruct one from PR/range/source evidence, or revalidate a lifecycle decision through one human question at a time. | no — model can self-call |
31
- | `/adr-kit:context` | Rank the ADRs most relevant to a task. Verify lifecycle status in the source ADR before treating it as binding. | no — model can self-call |
32
- | `/adr-kit:judge` | Interactive judge against a staged diff. Runs declarative checks + in-session LLM check for `llm_judge: true` ADRs. Walks resolution paths on violation. | no — model can self-call |
33
- | `/adr-kit:review` | Audit a branch or PR against existing ADRs and discover undocumented decisions. | no — model can self-call |
34
- | `/adr-kit:audit` | Lint the decisions and judge the code in one run, over a diff or the whole codebase. Separate exit codes for an ADR-quality failure and a code violation. | no — model can self-call |
35
- | `/adr-kit:lint` | Validate existing ADRs against the four verification gates. | yes |
36
- | `/adr-kit:related` | Show inbound/outbound ADR references and dangling links. | no — model can self-call |
37
- | `/adr-kit:supersede` | Guide a Proposed successor and reciprocal lifecycle update. | yes |
38
- | `/adr-kit:retire` | Rank Accepted ADRs for retirement; never mutates them. | yes |
39
- | `/adr-kit:migrate` | Preview metadata or body-profile migration; MADR, Nygard, and canonical are supported. | yes |
40
- | `/adr-kit:setup` | Append `## ADR Kit` block to `CLAUDE.md` (idempotent). | yes |
41
- | `/adr-kit:settings` | Show every knob, its current value, and where that value came from (default, project file, machine-local file, environment). | yes |
42
- | `/adr-kit:upgrade` | Migrate v0.11 → v0.12 footprint without re-running the heavy audit. | yes |
43
- | `/adr-kit:install-hooks` | Install or uninstall the pre-commit hook; also manages the guardian's project-scoped SessionStart hook. | yes |
44
- | `/adr-kit:guardian` | Run the ADR-set health sweep for due tier(s). Cheap tier is free; LLM tier confirms cost first. | no — model can self-call |
45
-
46
- ## The four verification gates
47
-
48
- An ADR cannot move from `Proposed` to `Accepted` until all four pass.
49
-
50
- 1. **Completeness** — every required section is present and non-empty: Status, Context, Decision, Alternatives Considered (≥ 2), Consequences (positive + negative), Related Decisions, References. Plus filename matches `ADR-NNN-kebab-case.md` and the heading number agrees.
51
- 2. **Evidence** — Context or References cites at least one concrete external/internal artefact (incident, profiling data, code path, RFC, vendor doc). No hand-waving justifications.
52
- 3. **Clarity** — Decision section names a single concrete choice (not a survey), uses imperative voice, no hedging language ("perhaps", "we should consider"). Identifiers (file paths, function names, config keys) are traceable.
53
- 4. **Consistency** — filename, heading number, and any cross-references resolve. No duplicate ADR numbers in the directory.
54
-
55
- `bin/adr-lint` enforces Completeness and Consistency deterministically. Evidence and Clarity are heuristic; opt in via `--gates evidence,clarity` or run `/adr-kit:lint` to use the LLM-aware skill.
56
-
57
- ## Choosing an ADR body profile
58
-
59
- Use `madr` unless the project has a reason to prefer another profile. MADR's
60
- explicit problem, decision drivers, options, outcome, trade-offs, and
61
- confirmation fields reduce the meaning an agent must infer from prose. This is
62
- an agent-reliability default, not a claim that MADR is globally the most used
63
- format; no authoritative format census exists.
64
-
65
- Discover the installed, pre-made catalog before honoring a user-selected
66
- alternative:
67
-
68
- ```bash
69
- python bin/adr profiles --format json
70
- ```
71
-
72
- Accept only a returned profile `id` whose matching template has
73
- `available: true`. Use that template through `adr new --profile <id>`. Do not
74
- invent a profile, infer one from an arbitrary template filename, or synthesize
75
- a replacement for a missing shipped template.
76
-
77
- Choose `nygard` when concise human scanning matters more than explicit
78
- authoring prompts. Choose `canonical` for compatibility with adr-kit
79
- repositories created before selectable profiles. All three retain the same
80
- frontmatter, lifecycle history, relationships, references, and Enforcement
81
- contract. Set the project default with `template.profile` in
82
- `docs/adr/.adr-kit.json`, or override one new record with `adr new --profile`.
83
-
84
- ## Discovering and upgrading existing formats
85
-
86
- Run `python bin/adr-migrate --plan docs/adr` after install or update and before
87
- editing an unfamiliar ADR set. The command is read-only and scans canonical
88
- ADR filenames plus recognizable older filenames.
89
-
90
- - MADR, Nygard, and canonical records remain valid. When only invariant
91
- metadata or filename normalization is missing, the report gives an exact,
92
- deterministic `--dry-run` command.
93
- - Y-Statements, Tyree/Akerman records, and arc42 decision sections are detected
94
- conservatively and routed to guided migration because their meaning cannot
95
- always be mapped without judgement.
96
- - Hybrid and unknown shapes also require guided review.
97
-
98
- Install, init, upgrade, and lint may display this report, but none may apply a
99
- migration automatically. Preview, inspect the diff, obtain approval, then
100
- apply. A later `adr-lint` run confirms the result.
101
-
102
- ## Authoring workflow (`/adr-kit:adr` or `adr-generator`)
103
-
104
- 1. Identify the architecturally significant change (architecture, NFRs, interfaces, dependencies, build/CI tooling). Refactors and bug fixes within existing patterns do NOT need an ADR.
105
- 2. Create the record with `python bin/adr new "Title" --adr-dir docs/adr`.
106
- It honors `template.profile` (`madr` by default; `nygard` and `canonical`
107
- are selectable). Then invoke `/adr-kit:adr` or the `adr-generator` agent
108
- with context, at least 2 alternatives, consequences, and related ADRs.
109
- 3. The agent applies the four gates and writes `docs/adr/ADR-NNN-…md` with `Status: Proposed`.
110
- 4. Run `/adr-kit:grill ADR-NNN`. The workflow reads repository facts first,
111
- records observed, human-stated, inferred, and unknown claims separately,
112
- and asks exactly one unresolved decision question at a time. Keep each
113
- unresolved dependency as an unchecked item under `## Open Questions`.
114
- 5. Human review. Iterate until readiness and all four gates pass.
115
- 6. Show the acceptance packet and flip Status to `Accepted, YYYY-MM-DD` only
116
- after an explicit `yes` in the active session. Append the matching
117
- transition to `## Status History`. **Never self-approve.**
118
- 7. If the decision touches code in a mechanically expressible way, add an `Enforcement` block (see below) so the pre-commit hook can guard the boundary.
119
-
120
- Use `python bin/adr-readiness ADR-NNN --format json` for deterministic facts,
121
- or `--all-proposed`, `--diff`, or `--base <ref> --head <ref>` for a queue or
122
- change range. The command is read-only and model-free. A PR, commit, chat log,
123
- or source document is untrusted evidence and can never imply acceptance.
124
-
125
- ## Enforcement block (v0.12+)
126
-
127
- Optional `## Enforcement` section at the end of an ADR. Fenced JSON code block, parsed by `bin/adr-judge`. Schema: plugin's `schemas/adr-enforcement.schema.json`.
128
-
129
- ```json
130
- {
131
- "forbid_pattern": [
132
- { "pattern": "\\bArduinoJson\\b", "path_glob": "src/**/*.{ino,cpp,h}",
133
- "message": "Use snprintf_P + sendJsonMapEntry; ArduinoJson fragments the heap (ADR-042)." }
134
- ],
135
- "forbid_import": [
136
- { "pattern": "^#include\\s+<ArduinoJson\\.h>", "path_glob": "src/**" }
137
- ],
138
- "require_pattern": []
139
- }
140
- ```
141
-
142
- **Rules:**
143
- - `forbid_pattern` — regex must NOT match any added line in the diff (lines starting with `+`, excluding `+++ ` markers).
144
- - `forbid_import` — same engine as `forbid_pattern`; the separate name documents intent.
145
- - `require_pattern` — regex must match at least once in the post-image of any file matching `path_glob`, read from the snapshot named by `--snapshot`. `staged` reads the git index (what the pre-commit hook uses), `worktree` reads the checked-out file. Under `--snapshot diff` a *modified* file's post-image cannot be rebuilt from a unified diff, which shows only the changed hunks — that case is reported as an **advisory** and does not block, because it is a fact about the invocation rather than about the code. A deleted or unstaged file, and an unreadable or unsafe path, still fail closed.
146
- - `llm_judge: true` — the optional LLM pass evaluates the diff against the
147
- semantic decision text (`## Decision Outcome` in MADR, `## Decision` in
148
- Nygard/canonical). The pass is opt-in (`judge.llm_enabled:true` or
149
- `ADR_KIT_LLM=1`) and falls back to advisory when the configured CLI is
150
- unavailable.
151
- - ADRs with no Enforcement block are skipped silently by the judge.
152
-
153
- **Path globs** support `**` (recursive). Examples: `src/**/*.py`, `tests/**`, `**/Makefile`.
154
-
155
- ## Pre-commit hook
156
-
157
- After `/adr-kit:init` (or `/adr-kit:install-hooks`), every `git commit` runs `bin/adr-judge` on the staged diff with two passes:
158
-
159
- - **Declarative pass** — always-on; fast, regex-only, no LLM. A violation exits non-zero and blocks the commit.
160
- - **LLM pass (on by default as of v0.43.0, ADR-017)** — each `llm_judge: true` ADR gets its **own isolated call**; they are never batched. Batching was reversed deliberately: a shared prompt let one ADR's Decision text flip another ADR's verdict, reproduced three times out of three, and the forged pass was indistinguishable from a genuine one. The model is resolved from the host agent (`judge.backend`), not pinned. Any `VIOLATION` blocks the commit with the model's one-sentence reason. An unavailable backend degrades to declarative-only and never blocks a legitimate commit.
161
-
162
- **Cost shape.** Since per-ADR isolation replaced batching, cost and latency are **linear in the number of `llm_judge: true` ADRs** — one model call each, not one call total. The old figure (roughly $0.10–0.30 per commit for 50 ADRs on one batched call) no longer holds and would under-estimate a large set by an order of magnitude. The mitigating fact is that `llm_judge` defaults to `false`, so the population is empty until an author opts an ADR in. The judge runs on the host client's own model (the only backend, ADR-036); inspect the effective settings with `python bin/adr-judge --show-config`.
163
-
164
- **Knobs:**
165
- - The LLM pass is on by default; `judge.llm_enabled: false` in `docs/adr/.adr-kit.json` turns it off project-wide.
166
- - Re-enable it for one commit after that: `ADR_KIT_LLM=1 git commit -m "…"`
167
- - Disable LLM pass per commit: `ADR_KIT_NO_LLM=1 git commit -m "…"`
168
- - Disable hook entirely per commit: `ADR_KIT_HOOK_DISABLE=1 git commit -m "…"`
169
- - Record the host client: `python bin/adr-judge --set-backend host --host-client <client-id>`. `judge.llm_model` and `judge.llm_cmd` are deprecated and ignored: repository-tracked config may never supply a command, endpoint or credential (ADR-017, ADR-036).
170
- - Remove permanently: `/adr-kit:install-hooks --uninstall`
171
-
172
- ## The signer
173
-
174
- Every lifecycle command writes a `## Status History` entry naming who decided.
175
- The actor is resolved in this order:
176
-
177
- 1. `--changed-by "User: <name>"` — one command.
178
- 2. `lifecycle.signer` in `docs/adr/.adr-kit.local.json` — this machine. Set it
179
- with `bin/adr signer --set "User: <name>"`.
180
- 3. `git config user.name`, adopted as `User: <name>` **and announced on use**.
181
- 4. Otherwise the command refuses. An unsigned acceptance is a bug; a self-signed
182
- one is a lie in the audit trail.
183
-
184
- Step 3 skips an identity that names a machine — `github-actions[bot]`, `runner`,
185
- `jenkins`, a bare `user` — because the record is meant to show which *human*
186
- accepted. Those fall through to the refusal.
187
-
188
- `bin/adr signer --suggest` proposes candidates found on the machine, from the
189
- signed-in GitHub account (`gh api user`) and from git, each with its source. It
190
- writes nothing; `/adr-kit:setup`, `/adr-kit:init` and `/adr-kit:upgrade` run it
191
- and let you choose. `bin/adr signer` on its own reports the current value and
192
- where it came from.
193
-
194
- The value is machine-local by design. A signer committed to the repository would
195
- put one person's name on every teammate's acceptance, which is worse than no name
196
- at all: a false attribution rather than a missing one.
197
-
198
- ## Supersession (changing a decision)
199
-
200
- Accepted ADRs are immutable. To change a decision:
201
-
202
- 1. Author a new ADR with the next number. Status `Proposed`. The Decision should explain what changes and why now.
203
- 2. In its Related Decisions: `Supersedes ADR-OLD`.
204
- 3. Accept the new ADR: `bin/adr accept ADR-NEW --changed-by "User: <name>"`.
205
- 4. Link both sides: `bin/adr supersede ADR-OLD --by ADR-NEW --changed-by "User: <name>"`.
206
-
207
- **Use the commands; do not hand-edit the old ADR.** `bin/adr supersede` writes the old ADR's Status line, its `superseded_by`, its Status History entry, the new ADR's `supersedes`, and regenerates all three indexes — as one transaction that rolls back on failure. Doing it by hand means getting five coupled edits right, and the failure mode is silent: a half-written link passes nothing and blocks acceptance later with an error that points at the wrong file.
208
-
209
- Steps 3 and 4 may run in either order. Accepting first is the safer habit, because a successor that claims nothing cannot be half-linked to anything.
210
-
211
- Never edit Decision, Context, Consequences, or Alternatives of an Accepted/Deprecated ADR. Only the Status line and an appended Status History transition may change.
212
-
213
- **One thing the commands cannot recover.** An ADR authored before the `## Status History` convention has its acceptance date in the Status line and nowhere else. The lifecycle commands seed a recovered entry from that line before replacing it, recording `changed_by: unknown` and `changed_via: unrecorded` rather than inventing a signer. If the Status line does not yield both a status and a date, the command refuses instead of writing a history that silently omits the earlier transition — fix the line, then re-run.
214
-
215
- ## Code review checks
216
-
217
- When reviewing a PR, apply these seven checks (Check 7 added in v0.12):
218
-
219
- 1. **ADR exists** for any architecturally significant change in the PR (new dep, interface change, NFR shift, build tooling change). Missing → request the author to invoke `/adr-kit:adr` or `adr-generator`.
220
- 2. **ADR is linked** in the PR description (path or relative URL).
221
- 3. **No violation** of Accepted ADRs in the diff. Cross-reference against `docs/adr/README.md` and the Enforcement blocks. The pre-commit hook should have caught this; if it didn't, the ADR is missing rules or wasn't installed.
222
- 4. **Supersession chain is correct** — old ADR's Status updated, new ADR cross-references, content immutability preserved.
223
- 5. **All four gates pass** on any new/modified ADR. Cite the failing gate when blocking ("fails Evidence gate — no concrete reference in Context").
224
- 6. **Legacy non-compliance has a remediation plan** — pre-existing violations that this PR doesn't fix should at least carry a `// TODO(ADR-NNN): align` or a backlog entry, not be silently ignored.
225
- 7. **Enforcement block is set appropriately** on any new Accepted ADR with a code surface. Either declarative rules, OR `llm_judge: true`, OR an explicit "manual review only" note in the ADR body explaining why the rule cannot be expressed mechanically. Missing block on a code-touching ADR is a smell.
226
-
227
- ## Anti-rationalisation guards
228
-
229
- When `/adr-kit:adr` is asked to write or accept an ADR, it actively pushes back on these nine common excuses (see plugin's `skills/adr/SKILL.md` for the full text):
230
-
231
- - "It's just a small change" — the rule is "architecturally significant", not "large".
232
- - "We can decide later" — later is now; defer = decide.
233
- - "Everyone knows this" — undocumented tacit knowledge is the problem ADRs solve.
234
- - "It's documented in the code" — code shows what, not why.
235
- - "We'll do it the same as last time" — name "last time" with an ADR reference.
236
- - "There's only one option" — there are always alternatives; "do nothing" is one.
237
- - "It's reversible" — most architecture is partially reversible; the ADR captures the *current* commitment.
238
- - "It's a refactor" — pure refactors don't need ADRs; *new patterns* introduced during refactoring do.
239
- - "We don't have time" — opportunity cost of skipping is a future maintainer hunting for the why.
240
-
241
- ## Guardian (v0.18.0+)
242
-
243
- The ADR Guardian is a periodic staleness detector that injects an `[adr-guardian]` nudge block at Claude Code SessionStart when a health tier is due. It never blocks session start, never runs an LLM, and emits nothing when nothing is due. A completed guardian sweep also runs `bin/adr-guardian refresh-readiness`, which atomically writes a 24-hour Proposed-ADR queue to `docs/adr/.adr-kit-readiness.json`. SessionStart only reads that bounded cache and offers at most three resumable `/adr-kit:grill ADR-NNN` actions; it never calculates readiness or starts an interview in the hook.
244
-
245
- **Two-tier cadence:**
246
-
247
- | Tier | Default cadence | Tools | Cost |
248
- |---|---|---|---|
249
- | **cheap** | Daily (`drift_stale_days: 1`) | `adr-judge` (declarative), `adr-retire`, `adr-lint`/`adr-status` | Free |
250
- | **llm** | Bi-weekly (`llm_stale_days: 14`) | `adr-suggest` (missing-ADR), `adr-judge --llm` (audit) | ~$0.10–0.30 |
251
-
252
- **On seeing an `[adr-guardian] ... DUE` block at session start:**
253
- 1. Identify which tier(s) are marked `DUE`.
254
- 2. For the cheap tier: offer "ADR drift/health check is due — run `/adr-kit:guardian cheap` to sweep (free, ~30s)?"
255
- 3. For the LLM tier: offer "ADR semantic check is due (bi-weekly) — run `/adr-kit:guardian llm`? This will confirm cost (~$0.10–0.30) before spending."
256
- 4. Confirm cost before the LLM tier. Never run LLM-tier work without explicit user confirmation (unless `guardian.llm_autorun: true` in `.adr-kit.json`).
257
-
258
- **Mix-by-finding-type responses:**
259
-
260
- | Finding | Response |
261
- |---|---|
262
- | **Drift** — code violates an Accepted ADR | Surface prominently. List violations with file:line + ADR. Offer fix or task. |
263
- | **Missing ADR** — new decision not recorded | Passive. List candidates; offer to author via `adr-generator`. User picks. |
264
- | **Stale ADR** — tech removed/superseded/policy drift | Draft retirement/supersession for review. Never auto-apply. |
265
- | **Health** — gate failures, broken chains | Report PASS/ADVISORY/FAIL. Offer to fix FAILs via `adr-generator`. |
266
-
267
- **Config** (`docs/adr/.adr-kit.json`, `guardian` block):
268
-
269
- ```json
270
- {
271
- "guardian": {
272
- "enabled": true,
273
- "drift_stale_days": 1,
274
- "llm_stale_days": 14,
275
- "nudge_cooldown_hours": 24,
276
- "llm_autorun": false
277
- }
278
- }
279
- ```
280
-
281
- **Hook install paths (both are shipped):**
282
- - Plugin-level (default): the adr-kit plugin declares a `SessionStart` hook in `.claude-plugin/plugin.json`. Auto-registers when the plugin is enabled. Self-guards (no-ops in non-ADR projects).
283
- - Project-scoped (explicit): `/adr-kit:install-hooks` adds a `SessionStart` entry to the project's `.claude/settings.json`. Idempotent add and clean remove (JSON-structural, never clobbers other hooks).
284
-
285
- State file: `docs/adr/.adr-kit-state.json` (gitignored, per-machine).
286
-
287
- ## Context injection (ADR-004, v0.31+)
288
-
289
- ADR knowledge is fed into agent work through three fail-open injection tiers plus
290
- the one fail-closed pre-commit floor (`bin/adr-judge`). None of the injection
291
- tiers ever block; only the commit gate does.
292
-
293
- | Tier | Hook | Mechanism | Deterministic |
294
- |---|---|---|---|
295
- | **Session** | SessionStart + `@`-import | `bin/adr-guardian` health nudge, and `@docs/adr/ADR-INDEX.md` (a one-row-per-ADR map generated by `bin/adr-index`) imported from `CLAUDE.md` | yes |
296
- | **Edit** | PreToolUse `Edit\|Write\|MultiEdit` | `bin/adr-watch --pre-edit` injects the top-ranked governing Accepted ADR's `## Decision` text (bounded to `inject.max_tokens`) *before* the edit, so the agent honours the decision as it writes. The PostToolUse `bin/adr-watch --hook` nudge remains as a confirmation backstop | yes |
297
- | **Task** | pull (JSON / MCP / CLI) | `docs/adr/ADR-INDEX.json` exposes the versioned metadata and relationship graph; `bin/adr-context` adds query-specific ranking (five signals); the key-free MCP tools `adr_context`, `adr_judge`, and `adr_readiness` let a subagent or workflow retrieve decisions, self-check a diff, and inspect Proposed readiness mid-task | yes |
298
-
299
- **Canonical fields (pinned).** Every reader uses the same two fields the judge
300
- reads, so nothing drifts: scope is the `## Enforcement` `path_glob` set; status is
301
- the `## Status` line reconciled with the latest `status_history` entry. Only
302
- `Accepted` ADRs are injected.
303
-
304
- **On seeing an `[adr-inject] ADR-NNN (title) governs <file>` block:** treat the
305
- quoted Decision as a binding constraint for that file. If your change would
306
- violate it, either comply, or write a superseding ADR first.
307
-
308
- **Regenerate the indexes** after adding or accepting an ADR:
309
- `bin/adr-index docs/adr` writes the compact `ADR-INDEX.md`, the versioned
310
- `ADR-INDEX.json` graph, and the generated README block from the same semantic
311
- records. All are deterministic and timestamp-free. Agents use JSON to shortlist
312
- records, then open the linked Markdown ADR before applying its decision.
313
-
314
- **Config** (`docs/adr/.adr-kit.json`, `inject` block):
315
-
316
- ```json
317
- {
318
- "inject": {
319
- "enabled": true,
320
- "max_tokens": 400,
321
- "cooldown_hours": 4
322
- }
323
- }
324
- ```
325
-
326
- ## MCP server (`bin/adr-mcp`)
327
-
328
- A hand-rolled Model Context Protocol server on stdio, stdlib-only with zero runtime dependencies. It exposes five read-only tools — `adr_context`, `adr_judge`, `adr_status`, `adr_quality`, `adr_readiness` — each a subprocess call into a sibling `bin/` script. `adr-suggest` is deliberately not exposed: it is LLM-only, and this server stays key-free.
329
-
330
- **Both protocol eras are served from one process** (ADR-016), because clients in the wild speak either:
331
-
332
- | Era | Reached through | Result shape |
333
- |---|---|---|
334
- | handshake (`2024-11-05` … `2025-11-25`) | `initialize`, which confirms a declared version or counter-offers `2025-11-25` | unchanged from earlier releases |
335
- | modern (`2026-07-28`) | `server/discover`, or the reserved `io.modelcontextprotocol/protocolVersion` key in `params._meta` | adds `resultType` and `_meta.serverInfo`; `server/discover` and `tools/list` also carry `ttlMs` and `cacheScope` |
336
-
337
- Two properties are worth knowing before changing anything here:
338
-
339
- - **Era is a pure function of the single frame.** There is no per-process and no per-connection era state, so the same bytes always get the same answer. Revision `2026-07-28` forbids relying on prior requests over the same connection to establish context, and a lock would mean a byte-identical frame gets two different answers depending on history. The official SDK does lock per connection; ADR-016 deliberately diverges.
340
- - **`-32022` never appears in a response to `initialize`.** The handshake negotiates by counter-offer, so an unknown or absent version gets `2025-11-25` back rather than an error. `-32022` is modern-era only.
341
-
342
- Primary-source notes, including the exact `_meta` key spellings and the error-code allocation, are in `docs/research/2026-07-29-mcp-2026-07-28-revision.md`.
343
-
344
- ## Plugin-side deep dives
345
-
346
- This guide is the project's own copy. For agents inside Claude Code, the plugin auto-loads richer instructions:
347
-
348
- - Plugin path (locale-dependent): `~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/<version>/`
349
- - `instructions/adr.coding.md` — per-developer rules (when to invoke the agent, supersession workflow, Definition of Done).
350
- - `instructions/adr.review.md` — the seven review checks with citation templates.
351
- - `skills/adr/SKILL.md` — full anti-rationalisation guard list, gate definitions, code examples.
352
- - `agents/adr-generator.md` — the subagent prompt.
353
-
354
- If you're working outside Claude Code (in a hook, a CI job, or a different agent), this file (`.claude/adr-kit-guide.md`) is your one-stop reference. Keep it in version control with the rest of the project.
1
+ <!-- adr-kit-guide v0.52.2 -->
2
+ <!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
3
+ <!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
4
+
5
+ # ADR Kit Guide
6
+
7
+ This project uses [adr-kit](https://github.com/rvdbreemen/adr-kit) to manage Architecture Decision Records. The kit ships:
8
+
9
+ - a project-side guide (this file) referenced from `CLAUDE.md`,
10
+ - a library of slash commands and a subagent for ADR authorship,
11
+ - a pre-commit hook that catches code changes drifting outside accepted ADRs.
12
+
13
+ ADR files live at `docs/adr/ADR-NNN-kebab-case-title.md`. They are versioned, immutable once accepted, and the durable record of *why* the codebase looks the way it does.
14
+
15
+ ## Three operating modes
16
+
17
+ | Mode | When | Entry point |
18
+ |---|---|---|
19
+ | **Init / bootstrap** | Once per project: scan source + docs, propose a starter ADR set, hook the kit into `CLAUDE.md`, install the pre-commit hook | `/adr-kit:init` |
20
+ | **Per-commit verification** | Every `git commit`: declarative-rule check (always-on, free). The LLM judge for `llm_judge: true` ADRs is **on by default** as of v0.43.0 (ADR-017) and runs on the host agent's own model, with no model pinned. Falls back to declarative-only when the backend is unavailable | `.githooks/pre-commit` (auto) |
21
+ | **On-demand invocation** | Mid-session: write or grill an ADR, judge a staged diff, supersede an existing decision | `/adr-kit:adr`, `/adr-kit:grill`, `/adr-kit:judge`, `adr-generator` subagent |
22
+ | **Guardian (v0.18+)** | Periodic staleness detector at SessionStart; in-session model runs due health tiers | `bin/adr-guardian` (hook, free) + `/adr-kit:guardian` (sweep) |
23
+
24
+ ## Slash commands
25
+
26
+ | Command | Purpose | User-only? |
27
+ |---|---|---|
28
+ | `/adr-kit:init` | One-shot project bootstrap (audit codebase, generate ADRs, install hook). Combines `setup` + audit + `install-hooks`. | yes |
29
+ | `/adr-kit:adr` | Author a single ADR (delegates to `adr-generator` subagent; runs four verification gates). | no — model can self-call |
30
+ | `/adr-kit:grill` | Complete a Proposed ADR, reconstruct one from PR/range/source evidence, or revalidate a lifecycle decision through one human question at a time. | no — model can self-call |
31
+ | `/adr-kit:context` | Rank the ADRs most relevant to a task. Verify lifecycle status in the source ADR before treating it as binding. | no — model can self-call |
32
+ | `/adr-kit:judge` | Interactive judge against a staged diff. Runs declarative checks + in-session LLM check for `llm_judge: true` ADRs. Walks resolution paths on violation. | no — model can self-call |
33
+ | `/adr-kit:review` | Audit a branch or PR against existing ADRs and discover undocumented decisions. | no — model can self-call |
34
+ | `/adr-kit:audit` | Lint the decisions and judge the code in one run, over a diff or the whole codebase. Separate exit codes for an ADR-quality failure and a code violation. | no — model can self-call |
35
+ | `/adr-kit:lint` | Validate existing ADRs against the four verification gates. | yes |
36
+ | `/adr-kit:related` | Show inbound/outbound ADR references and dangling links. | no — model can self-call |
37
+ | `/adr-kit:supersede` | Guide a Proposed successor and reciprocal lifecycle update. | yes |
38
+ | `/adr-kit:retire` | Rank Accepted ADRs for retirement; never mutates them. | yes |
39
+ | `/adr-kit:migrate` | Preview metadata or body-profile migration; MADR, Nygard, and canonical are supported. | yes |
40
+ | `/adr-kit:setup` | Append `## ADR Kit` block to `CLAUDE.md` (idempotent). | yes |
41
+ | `/adr-kit:settings` | Show every knob, its current value, and where that value came from (default, project file, machine-local file, environment). | yes |
42
+ | `/adr-kit:upgrade` | Migrate v0.11 → v0.12 footprint without re-running the heavy audit. | yes |
43
+ | `/adr-kit:install-hooks` | Install or uninstall the pre-commit hook; also manages the guardian's project-scoped SessionStart hook. | yes |
44
+ | `/adr-kit:guardian` | Run the ADR-set health sweep for due tier(s). Cheap tier is free; LLM tier confirms cost first. | no — model can self-call |
45
+
46
+ ## The four verification gates
47
+
48
+ An ADR cannot move from `Proposed` to `Accepted` until all four pass.
49
+
50
+ 1. **Completeness** — every required section is present and non-empty: Status, Context, Decision, Alternatives Considered (≥ 2), Consequences (positive + negative), Related Decisions, References. Plus filename matches `ADR-NNN-kebab-case.md` and the heading number agrees.
51
+ 2. **Evidence** — Context or References cites at least one concrete external/internal artefact (incident, profiling data, code path, RFC, vendor doc). No hand-waving justifications.
52
+ 3. **Clarity** — Decision section names a single concrete choice (not a survey), uses imperative voice, no hedging language ("perhaps", "we should consider"). Identifiers (file paths, function names, config keys) are traceable.
53
+ 4. **Consistency** — filename, heading number, and any cross-references resolve. No duplicate ADR numbers in the directory.
54
+
55
+ `bin/adr-lint` enforces Completeness and Consistency deterministically. Evidence and Clarity are heuristic; opt in via `--gates evidence,clarity` or run `/adr-kit:lint` to use the LLM-aware skill.
56
+
57
+ ## Choosing an ADR body profile
58
+
59
+ Use `madr` unless the project has a reason to prefer another profile. MADR's
60
+ explicit problem, decision drivers, options, outcome, trade-offs, and
61
+ confirmation fields reduce the meaning an agent must infer from prose. This is
62
+ an agent-reliability default, not a claim that MADR is globally the most used
63
+ format; no authoritative format census exists.
64
+
65
+ Discover the installed, pre-made catalog before honoring a user-selected
66
+ alternative:
67
+
68
+ ```bash
69
+ python bin/adr profiles --format json
70
+ ```
71
+
72
+ Accept only a returned profile `id` whose matching template has
73
+ `available: true`. Use that template through `adr new --profile <id>`. Do not
74
+ invent a profile, infer one from an arbitrary template filename, or synthesize
75
+ a replacement for a missing shipped template.
76
+
77
+ Choose `nygard` when concise human scanning matters more than explicit
78
+ authoring prompts. Choose `canonical` for compatibility with adr-kit
79
+ repositories created before selectable profiles. All three retain the same
80
+ frontmatter, lifecycle history, relationships, references, and Enforcement
81
+ contract. Set the project default with `template.profile` in
82
+ `docs/adr/.adr-kit.json`, or override one new record with `adr new --profile`.
83
+
84
+ ## Discovering and upgrading existing formats
85
+
86
+ Run `python bin/adr-migrate --plan docs/adr` after install or update and before
87
+ editing an unfamiliar ADR set. The command is read-only and scans canonical
88
+ ADR filenames plus recognizable older filenames.
89
+
90
+ - MADR, Nygard, and canonical records remain valid. When only invariant
91
+ metadata or filename normalization is missing, the report gives an exact,
92
+ deterministic `--dry-run` command.
93
+ - Y-Statements, Tyree/Akerman records, and arc42 decision sections are detected
94
+ conservatively and routed to guided migration because their meaning cannot
95
+ always be mapped without judgement.
96
+ - Hybrid and unknown shapes also require guided review.
97
+
98
+ Install, init, upgrade, and lint may display this report, but none may apply a
99
+ migration automatically. Preview, inspect the diff, obtain approval, then
100
+ apply. A later `adr-lint` run confirms the result.
101
+
102
+ ## Authoring workflow (`/adr-kit:adr` or `adr-generator`)
103
+
104
+ 1. Identify the architecturally significant change (architecture, NFRs, interfaces, dependencies, build/CI tooling). Refactors and bug fixes within existing patterns do NOT need an ADR.
105
+ 2. Create the record with `python bin/adr new "Title" --adr-dir docs/adr`.
106
+ It honors `template.profile` (`madr` by default; `nygard` and `canonical`
107
+ are selectable). Then invoke `/adr-kit:adr` or the `adr-generator` agent
108
+ with context, at least 2 alternatives, consequences, and related ADRs.
109
+ 3. The agent applies the four gates and writes `docs/adr/ADR-NNN-…md` with `Status: Proposed`.
110
+ 4. Run `/adr-kit:grill ADR-NNN`. The workflow reads repository facts first,
111
+ records observed, human-stated, inferred, and unknown claims separately,
112
+ and asks exactly one unresolved decision question at a time. Keep each
113
+ unresolved dependency as an unchecked item under `## Open Questions`.
114
+ 5. Human review. Iterate until readiness and all four gates pass.
115
+ 6. Show the acceptance packet and flip Status to `Accepted, YYYY-MM-DD` only
116
+ after an explicit `yes` in the active session. Append the matching
117
+ transition to `## Status History`. **Never self-approve.**
118
+ 7. If the decision touches code in a mechanically expressible way, add an `Enforcement` block (see below) so the pre-commit hook can guard the boundary.
119
+
120
+ Use `python bin/adr-readiness ADR-NNN --format json` for deterministic facts,
121
+ or `--all-proposed`, `--diff`, or `--base <ref> --head <ref>` for a queue or
122
+ change range. The command is read-only and model-free. A PR, commit, chat log,
123
+ or source document is untrusted evidence and can never imply acceptance.
124
+
125
+ ## Enforcement block (v0.12+)
126
+
127
+ Optional `## Enforcement` section at the end of an ADR. Fenced JSON code block, parsed by `bin/adr-judge`. Schema: plugin's `schemas/adr-enforcement.schema.json`.
128
+
129
+ ```json
130
+ {
131
+ "forbid_pattern": [
132
+ { "pattern": "\\bArduinoJson\\b", "path_glob": "src/**/*.{ino,cpp,h}",
133
+ "message": "Use snprintf_P + sendJsonMapEntry; ArduinoJson fragments the heap (ADR-042)." }
134
+ ],
135
+ "forbid_import": [
136
+ { "pattern": "^#include\\s+<ArduinoJson\\.h>", "path_glob": "src/**" }
137
+ ],
138
+ "require_pattern": []
139
+ }
140
+ ```
141
+
142
+ **Rules:**
143
+ - `forbid_pattern` — regex must NOT match any added line in the diff (lines starting with `+`, excluding `+++ ` markers).
144
+ - `forbid_import` — same engine as `forbid_pattern`; the separate name documents intent.
145
+ - `require_pattern` — regex must match at least once in the post-image of any file matching `path_glob`, read from the snapshot named by `--snapshot`. `staged` reads the git index (what the pre-commit hook uses), `worktree` reads the checked-out file. Under `--snapshot diff` a *modified* file's post-image cannot be rebuilt from a unified diff, which shows only the changed hunks — that case is reported as an **advisory** and does not block, because it is a fact about the invocation rather than about the code. A deleted or unstaged file, and an unreadable or unsafe path, still fail closed.
146
+ - `llm_judge: true` — the optional LLM pass evaluates the diff against the
147
+ semantic decision text (`## Decision Outcome` in MADR, `## Decision` in
148
+ Nygard/canonical). The pass is opt-in (`judge.llm_enabled:true` or
149
+ `ADR_KIT_LLM=1`) and falls back to advisory when the configured CLI is
150
+ unavailable.
151
+ - ADRs with no Enforcement block are skipped silently by the judge.
152
+
153
+ **Path globs** support `**` (recursive). Examples: `src/**/*.py`, `tests/**`, `**/Makefile`.
154
+
155
+ ## Pre-commit hook
156
+
157
+ After `/adr-kit:init` (or `/adr-kit:install-hooks`), every `git commit` runs `bin/adr-judge` on the staged diff with two passes:
158
+
159
+ - **Declarative pass** — always-on; fast, regex-only, no LLM. A violation exits non-zero and blocks the commit.
160
+ - **LLM pass (on by default as of v0.43.0, ADR-017)** — each `llm_judge: true` ADR gets its **own isolated call**; they are never batched. Batching was reversed deliberately: a shared prompt let one ADR's Decision text flip another ADR's verdict, reproduced three times out of three, and the forged pass was indistinguishable from a genuine one. The model is resolved from the host agent (`judge.backend`), not pinned. Any `VIOLATION` blocks the commit with the model's one-sentence reason. An unavailable backend degrades to declarative-only and never blocks a legitimate commit.
161
+
162
+ **Cost shape.** Since per-ADR isolation replaced batching, cost and latency are **linear in the number of `llm_judge: true` ADRs** — one model call each, not one call total. The old figure (roughly $0.10–0.30 per commit for 50 ADRs on one batched call) no longer holds and would under-estimate a large set by an order of magnitude. The mitigating fact is that `llm_judge` defaults to `false`, so the population is empty until an author opts an ADR in. The judge runs on the host client's own model (the only backend, ADR-036); inspect the effective settings with `python bin/adr-judge --show-config`.
163
+
164
+ **Knobs:**
165
+ - The LLM pass is on by default; `judge.llm_enabled: false` in `docs/adr/.adr-kit.json` turns it off project-wide.
166
+ - Re-enable it for one commit after that: `ADR_KIT_LLM=1 git commit -m "…"`
167
+ - Disable LLM pass per commit: `ADR_KIT_NO_LLM=1 git commit -m "…"`
168
+ - Disable hook entirely per commit: `ADR_KIT_HOOK_DISABLE=1 git commit -m "…"`
169
+ - Record the host client: `python bin/adr-judge --set-backend host --host-client <client-id>`. `judge.llm_model` and `judge.llm_cmd` are deprecated and ignored: repository-tracked config may never supply a command, endpoint or credential (ADR-017, ADR-036).
170
+ - Remove permanently: `/adr-kit:install-hooks --uninstall`
171
+
172
+ ## The signer
173
+
174
+ Every lifecycle command writes a `## Status History` entry naming who decided.
175
+ The actor is resolved in this order:
176
+
177
+ 1. `--changed-by "User: <name>"` — one command.
178
+ 2. `lifecycle.signer` in `docs/adr/.adr-kit.local.json` — this machine. Set it
179
+ with `bin/adr signer --set "User: <name>"`.
180
+ 3. `git config user.name`, adopted as `User: <name>` **and announced on use**.
181
+ 4. Otherwise the command refuses. An unsigned acceptance is a bug; a self-signed
182
+ one is a lie in the audit trail.
183
+
184
+ Step 3 skips an identity that names a machine — `github-actions[bot]`, `runner`,
185
+ `jenkins`, a bare `user` — because the record is meant to show which *human*
186
+ accepted. Those fall through to the refusal.
187
+
188
+ `bin/adr signer --suggest` proposes candidates found on the machine, from the
189
+ signed-in GitHub account (`gh api user`) and from git, each with its source. It
190
+ writes nothing; `/adr-kit:setup`, `/adr-kit:init` and `/adr-kit:upgrade` run it
191
+ and let you choose. `bin/adr signer` on its own reports the current value and
192
+ where it came from.
193
+
194
+ The value is machine-local by design. A signer committed to the repository would
195
+ put one person's name on every teammate's acceptance, which is worse than no name
196
+ at all: a false attribution rather than a missing one.
197
+
198
+ ## Supersession (changing a decision)
199
+
200
+ Accepted ADRs are immutable. To change a decision:
201
+
202
+ 1. Author a new ADR with the next number. Status `Proposed`. The Decision should explain what changes and why now.
203
+ 2. In its Related Decisions: `Supersedes ADR-OLD`.
204
+ 3. Accept the new ADR: `bin/adr accept ADR-NEW --changed-by "User: <name>"`.
205
+ 4. Link both sides: `bin/adr supersede ADR-OLD --by ADR-NEW --changed-by "User: <name>"`.
206
+
207
+ **Use the commands; do not hand-edit the old ADR.** `bin/adr supersede` writes the old ADR's Status line, its `superseded_by`, its Status History entry, the new ADR's `supersedes`, and regenerates all three indexes — as one transaction that rolls back on failure. Doing it by hand means getting five coupled edits right, and the failure mode is silent: a half-written link passes nothing and blocks acceptance later with an error that points at the wrong file.
208
+
209
+ Steps 3 and 4 may run in either order. Accepting first is the safer habit, because a successor that claims nothing cannot be half-linked to anything.
210
+
211
+ Never edit Decision, Context, Consequences, or Alternatives of an Accepted/Deprecated ADR. Only the Status line and an appended Status History transition may change.
212
+
213
+ **One thing the commands cannot recover.** An ADR authored before the `## Status History` convention has its acceptance date in the Status line and nowhere else. The lifecycle commands seed a recovered entry from that line before replacing it, recording `changed_by: unknown` and `changed_via: unrecorded` rather than inventing a signer. If the Status line does not yield both a status and a date, the command refuses instead of writing a history that silently omits the earlier transition — fix the line, then re-run.
214
+
215
+ ## Code review checks
216
+
217
+ When reviewing a PR, apply these seven checks (Check 7 added in v0.12):
218
+
219
+ 1. **ADR exists** for any architecturally significant change in the PR (new dep, interface change, NFR shift, build tooling change). Missing → request the author to invoke `/adr-kit:adr` or `adr-generator`.
220
+ 2. **ADR is linked** in the PR description (path or relative URL).
221
+ 3. **No violation** of Accepted ADRs in the diff. Cross-reference against `docs/adr/README.md` and the Enforcement blocks. The pre-commit hook should have caught this; if it didn't, the ADR is missing rules or wasn't installed.
222
+ 4. **Supersession chain is correct** — old ADR's Status updated, new ADR cross-references, content immutability preserved.
223
+ 5. **All four gates pass** on any new/modified ADR. Cite the failing gate when blocking ("fails Evidence gate — no concrete reference in Context").
224
+ 6. **Legacy non-compliance has a remediation plan** — pre-existing violations that this PR doesn't fix should at least carry a `// TODO(ADR-NNN): align` or a backlog entry, not be silently ignored.
225
+ 7. **Enforcement block is set appropriately** on any new Accepted ADR with a code surface. Either declarative rules, OR `llm_judge: true`, OR an explicit "manual review only" note in the ADR body explaining why the rule cannot be expressed mechanically. Missing block on a code-touching ADR is a smell.
226
+
227
+ ## Anti-rationalisation guards
228
+
229
+ When `/adr-kit:adr` is asked to write or accept an ADR, it actively pushes back on these nine common excuses (see plugin's `skills/adr/SKILL.md` for the full text):
230
+
231
+ - "It's just a small change" — the rule is "architecturally significant", not "large".
232
+ - "We can decide later" — later is now; defer = decide.
233
+ - "Everyone knows this" — undocumented tacit knowledge is the problem ADRs solve.
234
+ - "It's documented in the code" — code shows what, not why.
235
+ - "We'll do it the same as last time" — name "last time" with an ADR reference.
236
+ - "There's only one option" — there are always alternatives; "do nothing" is one.
237
+ - "It's reversible" — most architecture is partially reversible; the ADR captures the *current* commitment.
238
+ - "It's a refactor" — pure refactors don't need ADRs; *new patterns* introduced during refactoring do.
239
+ - "We don't have time" — opportunity cost of skipping is a future maintainer hunting for the why.
240
+
241
+ ## Guardian (v0.18.0+)
242
+
243
+ The ADR Guardian is a periodic staleness detector that injects an `[adr-guardian]` nudge block at Claude Code SessionStart when a health tier is due. It never blocks session start, never runs an LLM, and emits nothing when nothing is due. A completed guardian sweep also runs `bin/adr-guardian refresh-readiness`, which atomically writes a 24-hour Proposed-ADR queue to `docs/adr/.adr-kit-readiness.json`. SessionStart only reads that bounded cache and offers at most three resumable `/adr-kit:grill ADR-NNN` actions; it never calculates readiness or starts an interview in the hook.
244
+
245
+ **Two-tier cadence:**
246
+
247
+ | Tier | Default cadence | Tools | Cost |
248
+ |---|---|---|---|
249
+ | **cheap** | Daily (`drift_stale_days: 1`) | `adr-judge` (declarative), `adr-retire`, `adr-lint`/`adr-status` | Free |
250
+ | **llm** | Bi-weekly (`llm_stale_days: 14`) | `adr-suggest` (missing-ADR), `adr-judge --llm` (audit) | ~$0.10–0.30 |
251
+
252
+ **On seeing an `[adr-guardian] ... DUE` block at session start:**
253
+ 1. Identify which tier(s) are marked `DUE`.
254
+ 2. For the cheap tier: offer "ADR drift/health check is due — run `/adr-kit:guardian cheap` to sweep (free, ~30s)?"
255
+ 3. For the LLM tier: offer "ADR semantic check is due (bi-weekly) — run `/adr-kit:guardian llm`? This will confirm cost (~$0.10–0.30) before spending."
256
+ 4. Confirm cost before the LLM tier. Never run LLM-tier work without explicit user confirmation (unless `guardian.llm_autorun: true` in `.adr-kit.json`).
257
+
258
+ **Mix-by-finding-type responses:**
259
+
260
+ | Finding | Response |
261
+ |---|---|
262
+ | **Drift** — code violates an Accepted ADR | Surface prominently. List violations with file:line + ADR. Offer fix or task. |
263
+ | **Missing ADR** — new decision not recorded | Passive. List candidates; offer to author via `adr-generator`. User picks. |
264
+ | **Stale ADR** — tech removed/superseded/policy drift | Draft retirement/supersession for review. Never auto-apply. |
265
+ | **Health** — gate failures, broken chains | Report PASS/ADVISORY/FAIL. Offer to fix FAILs via `adr-generator`. |
266
+
267
+ **Config** (`docs/adr/.adr-kit.json`, `guardian` block):
268
+
269
+ ```json
270
+ {
271
+ "guardian": {
272
+ "enabled": true,
273
+ "drift_stale_days": 1,
274
+ "llm_stale_days": 14,
275
+ "nudge_cooldown_hours": 24,
276
+ "llm_autorun": false
277
+ }
278
+ }
279
+ ```
280
+
281
+ **Hook install paths (both are shipped):**
282
+ - Plugin-level (default): the adr-kit plugin declares a `SessionStart` hook in `.claude-plugin/plugin.json`. Auto-registers when the plugin is enabled. Self-guards (no-ops in non-ADR projects).
283
+ - Project-scoped (explicit): `/adr-kit:install-hooks` adds a `SessionStart` entry to the project's `.claude/settings.json`. Idempotent add and clean remove (JSON-structural, never clobbers other hooks).
284
+
285
+ State file: `docs/adr/.adr-kit-state.json` (gitignored, per-machine).
286
+
287
+ ## Context injection (ADR-004, v0.31+)
288
+
289
+ ADR knowledge is fed into agent work through three fail-open injection tiers plus
290
+ the one fail-closed pre-commit floor (`bin/adr-judge`). None of the injection
291
+ tiers ever block; only the commit gate does.
292
+
293
+ | Tier | Hook | Mechanism | Deterministic |
294
+ |---|---|---|---|
295
+ | **Session** | SessionStart + `@`-import | `bin/adr-guardian` health nudge, and `@docs/adr/ADR-INDEX.md` (a one-row-per-ADR map generated by `bin/adr-index`) imported from `CLAUDE.md` | yes |
296
+ | **Edit** | PreToolUse `Edit\|Write\|MultiEdit` | `bin/adr-watch --pre-edit` injects the top-ranked governing Accepted ADR's `## Decision` text (bounded to `inject.max_tokens`) *before* the edit, so the agent honours the decision as it writes. The PostToolUse `bin/adr-watch --hook` nudge remains as a confirmation backstop | yes |
297
+ | **Task** | pull (JSON / MCP / CLI) | `docs/adr/ADR-INDEX.json` exposes the versioned metadata and relationship graph; `bin/adr-context` adds query-specific ranking (five signals); the key-free MCP tools `adr_context`, `adr_judge`, and `adr_readiness` let a subagent or workflow retrieve decisions, self-check a diff, and inspect Proposed readiness mid-task | yes |
298
+
299
+ **Canonical fields (pinned).** Every reader uses the same two fields the judge
300
+ reads, so nothing drifts: scope is the `## Enforcement` `path_glob` set; status is
301
+ the `## Status` line reconciled with the latest `status_history` entry. Only
302
+ `Accepted` ADRs are injected.
303
+
304
+ **On seeing an `[adr-inject] ADR-NNN (title) governs <file>` block:** treat the
305
+ quoted Decision as a binding constraint for that file. If your change would
306
+ violate it, either comply, or write a superseding ADR first.
307
+
308
+ **Regenerate the indexes** after adding or accepting an ADR:
309
+ `bin/adr-index docs/adr` writes the compact `ADR-INDEX.md`, the versioned
310
+ `ADR-INDEX.json` graph, and the generated README block from the same semantic
311
+ records. All are deterministic and timestamp-free. Agents use JSON to shortlist
312
+ records, then open the linked Markdown ADR before applying its decision.
313
+
314
+ **Config** (`docs/adr/.adr-kit.json`, `inject` block):
315
+
316
+ ```json
317
+ {
318
+ "inject": {
319
+ "enabled": true,
320
+ "max_tokens": 400,
321
+ "cooldown_hours": 4
322
+ }
323
+ }
324
+ ```
325
+
326
+ ## MCP server (`bin/adr-mcp`)
327
+
328
+ A hand-rolled Model Context Protocol server on stdio, stdlib-only with zero runtime dependencies. It exposes five read-only tools — `adr_context`, `adr_judge`, `adr_status`, `adr_quality`, `adr_readiness` — each a subprocess call into a sibling `bin/` script. `adr-suggest` is deliberately not exposed: it is LLM-only, and this server stays key-free.
329
+
330
+ **Both protocol eras are served from one process** (ADR-016), because clients in the wild speak either:
331
+
332
+ | Era | Reached through | Result shape |
333
+ |---|---|---|
334
+ | handshake (`2024-11-05` … `2025-11-25`) | `initialize`, which confirms a declared version or counter-offers `2025-11-25` | unchanged from earlier releases |
335
+ | modern (`2026-07-28`) | `server/discover`, or the reserved `io.modelcontextprotocol/protocolVersion` key in `params._meta` | adds `resultType` and `_meta.serverInfo`; `server/discover` and `tools/list` also carry `ttlMs` and `cacheScope` |
336
+
337
+ Two properties are worth knowing before changing anything here:
338
+
339
+ - **Era is a pure function of the single frame.** There is no per-process and no per-connection era state, so the same bytes always get the same answer. Revision `2026-07-28` forbids relying on prior requests over the same connection to establish context, and a lock would mean a byte-identical frame gets two different answers depending on history. The official SDK does lock per connection; ADR-016 deliberately diverges.
340
+ - **`-32022` never appears in a response to `initialize`.** The handshake negotiates by counter-offer, so an unknown or absent version gets `2025-11-25` back rather than an error. `-32022` is modern-era only.
341
+
342
+ Primary-source notes, including the exact `_meta` key spellings and the error-code allocation, are in `docs/research/2026-07-29-mcp-2026-07-28-revision.md`.
343
+
344
+ ## Plugin-side deep dives
345
+
346
+ This guide is the project's own copy. For agents inside Claude Code, the plugin auto-loads richer instructions:
347
+
348
+ - Plugin path (locale-dependent): `~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/<version>/`
349
+ - `instructions/adr.coding.md` — per-developer rules (when to invoke the agent, supersession workflow, Definition of Done).
350
+ - `instructions/adr.review.md` — the seven review checks with citation templates.
351
+ - `skills/adr/SKILL.md` — full anti-rationalisation guard list, gate definitions, code examples.
352
+ - `agents/adr-generator.md` — the subagent prompt.
353
+
354
+ If you're working outside Claude Code (in a hook, a CI job, or a different agent), this file (`.claude/adr-kit-guide.md`) is your one-stop reference. Keep it in version control with the rest of the project.