@rvdbreemen/adr-kit-opencode 0.52.0 → 0.53.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 (83) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +865 -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 +96 -4
  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/adr_doctor_probes.py +2 -0
  28. package/bin/bump-version +0 -0
  29. package/clients/workflows.json +229 -229
  30. package/hooks/__init__.py +1 -1
  31. package/hooks/adapters/__init__.py +13 -13
  32. package/hooks/adapters/claude.py +27 -27
  33. package/hooks/adapters/codex.py +26 -26
  34. package/hooks/adapters/copilot.py +11 -11
  35. package/hooks/adr-hook.py +128 -128
  36. package/hooks/adr_hook_core.py +843 -843
  37. package/hooks/adr_pr_guard.py +367 -367
  38. package/instructions/ADR-guide.md +101 -48
  39. package/instructions/adr.coding.md +82 -82
  40. package/instructions/adr.review.md +182 -182
  41. package/opencode/plugin.ts +1 -4
  42. package/package.json +5 -2
  43. package/schemas/adr-context-probes.schema.json +56 -56
  44. package/schemas/adr-enforcement.schema.json +57 -57
  45. package/schemas/adr-frontmatter.schema.json +144 -144
  46. package/schemas/adr-index.schema.json +276 -276
  47. package/schemas/adr-kit-config.schema.json +371 -371
  48. package/schemas/adr-readiness.schema.json +41 -41
  49. package/schemas/client-capabilities.schema.json +503 -503
  50. package/schemas/client-certification.schema.json +101 -101
  51. package/schemas/doctor-output.schema.json +92 -92
  52. package/skills/adr/SKILL.md +780 -780
  53. package/skills/audit/SKILL.md +103 -103
  54. package/skills/context/SKILL.md +77 -77
  55. package/skills/grill/SKILL.md +84 -84
  56. package/skills/grill/agents/openai.yaml +4 -4
  57. package/skills/guardian/SKILL.md +316 -316
  58. package/skills/init/SKILL.md +499 -499
  59. package/skills/install-hooks/SKILL.md +154 -154
  60. package/skills/judge/SKILL.md +168 -168
  61. package/skills/lint/SKILL.md +321 -321
  62. package/skills/migrate/SKILL.md +313 -313
  63. package/skills/related/SKILL.md +62 -62
  64. package/skills/retire/SKILL.md +41 -41
  65. package/skills/review/SKILL.md +167 -167
  66. package/skills/settings/SKILL.md +73 -73
  67. package/skills/setup/SKILL.md +128 -128
  68. package/skills/supersede/SKILL.md +136 -136
  69. package/skills/upgrade/SKILL.md +273 -273
  70. package/templates/adr-kit-guide.md +354 -354
  71. package/templates/adr-template.canonical.md +115 -115
  72. package/templates/adr-template.madr.md +131 -131
  73. package/templates/adr-template.md +131 -131
  74. package/templates/adr-template.nygard.md +111 -111
  75. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  76. package/templates/githooks/pre-commit +1 -1
  77. package/templates/github-workflows/adr-audit.yml +58 -58
  78. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  79. package/templates/github-workflows/adr-index-check.yml +30 -30
  80. package/templates/github-workflows/adr-judge.yml +31 -31
  81. package/templates/github-workflows/adr-readiness.yml +18 -18
  82. package/templates/validate_adr_template.py +38 -38
  83. package/templates/validate_adr_template.sh +74 -74
@@ -1,316 +1,316 @@
1
- ---
2
- name: guardian
3
- description: "Check ADR health, drift, stale decisions, and lint. Use for ADR guardian, health sweep, stale ADRs, or an [adr-guardian] DUE notice."
4
- argument-hint: "[cheap | llm | all]"
5
- allowed-tools: [Read, Bash, Edit, Write, Task, Glob, Grep]
6
- ---
7
-
8
- # adr-kit guardian
9
-
10
- Use `$ARGUMENTS` as `cheap`, `llm`, or `all`; default to the due tier when it
11
- is empty. Never start paid or cloud judgment without explicit permission.
12
-
13
- You are running the ADR-set health sweep. Your job is to run whichever tier(s) are due (or were requested), surface findings using the mix-by-finding-type responses below, and stamp the state file when done.
14
-
15
- ## Before you start
16
-
17
- Resolve the plugin bin path (same resolver used in /adr-kit:judge and /adr-kit:init):
18
-
19
- ```bash
20
- ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1)
21
- ```
22
-
23
- If `ADR_KIT` is empty (plugin not installed), fall back to a local checkout:
24
-
25
- ```bash
26
- # try local checkout
27
- ADR_KIT=$(git rev-parse --show-toplevel 2>/dev/null)/
28
- ```
29
-
30
- Verify the guardian bin exists:
31
-
32
- ```bash
33
- ls "$ADR_KIT/bin/adr-guardian" 2>/dev/null || echo "guardian not found"
34
- ```
35
-
36
- ## Step 1 — Determine which tier(s) to run
37
-
38
- If invoked with an explicit argument (`cheap`, `llm`, or `all`), honour it.
39
-
40
- Otherwise, read the current state to determine due tiers:
41
-
42
- ```bash
43
- "$ADR_KIT/bin/adr-guardian" state
44
- ```
45
-
46
- Compute which tier is due based on `cheap_tier.last_run` vs `guardian.drift_stale_days` and `llm_tier.last_run` vs `guardian.llm_stale_days` (defaults: 1d cheap, 14d LLM). If neither is due, report "Both tiers are current — nothing to sweep" and stop.
47
-
48
- Read `docs/adr/.adr-kit.json` if it exists to get any custom `guardian.*` config.
49
-
50
- ## Step 2 — Cheap tier (drift + stale + lint)
51
-
52
- Run only when cheap tier is due or explicitly requested.
53
-
54
- ### 2a. Drift check (declarative, adr-judge)
55
-
56
- ```bash
57
- # HEAD~5 does not exist in a repo or shallow clone with fewer than 6 commits;
58
- # git then fails to stderr and pipes an EMPTY diff, which the judge passes with
59
- # exit 0 — a drift check that checked nothing. Fall back to the root commit.
60
- BASE=$(git rev-parse --verify -q HEAD~5 || git rev-list --max-parents=0 HEAD | tail -1)
61
- git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-judge" \
62
- --diff - \
63
- --adr-dir docs/adr/ \
64
- --repo-root "$(git rev-parse --show-toplevel)" \
65
- --snapshot worktree \
66
- --json > /tmp/guardian-drift.json 2>&1
67
- DRIFT_EXIT=$?
68
- ```
69
-
70
- Read `/tmp/guardian-drift.json`. Count violations and advisories.
71
-
72
- **Response (mix-by-finding-type: Drift):** Surface prominently. List each violation with file:line + ADR id. Offer to (a) fix the code, (b) write a new ADR covering the new pattern, or (c) supersede the violated ADR. Highest-priority finding type.
73
-
74
- ### 2b. Stale ADR detection (adr-retire)
75
-
76
- ```bash
77
- "$ADR_KIT/bin/adr-retire" \
78
- docs/adr/ \
79
- --format json > /tmp/guardian-retire.json 2>&1
80
- ```
81
-
82
- Read `/tmp/guardian-retire.json`. Collect the candidate set: extract the list of ADR ids flagged for retirement (candidates).
83
-
84
- **Change-based filtering:** Read `retire_seen` from the state file (`adr-guardian state`). Compare the fresh candidate set against `retire_seen`. Only surface candidates that are *new* (present in fresh set but not in `retire_seen`). This avoids daily nagging about the same stale ADRs. If all candidates are already in `retire_seen`, skip the retire response silently for this sweep.
85
-
86
- **Response (mix-by-finding-type: Stale ADR):** For each **new** retire candidate, draft a retirement/supersession skeleton for human review — never auto-apply. Show:
87
- - The ADR id and title.
88
- - The retirement signal (tech removed / superseded target missing / policy drift / age threshold).
89
- - A draft Status flip: `Deprecated, <today>` or `Superseded by ADR-NNN, <today>` (if a superseding ADR exists).
90
- - Ask the user to confirm or skip each.
91
-
92
- ### 2c. Health lint (adr-lint / adr-status)
93
-
94
- ```bash
95
- "$ADR_KIT/bin/adr-lint" docs/adr/ 2>&1 | tail -20
96
- "$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ 2>&1 | tail -5
97
- ```
98
-
99
- **Response (mix-by-finding-type: Health):** Emit a PASS/ADVISORY/FAIL summary. For FAILs: list the gate name and ADR, offer to fix via `/adr-kit:adr` (re-run the adr-generator subagent on that ADR).
100
-
101
- Also read the Enforcement coverage percent for the trend history:
102
-
103
- ```bash
104
- "$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ --format json > /tmp/guardian-status.json 2>&1
105
- ```
106
-
107
- Extract `summary.coverage_pct` from `/tmp/guardian-status.json`. You will pass it
108
- to the stamp call below so the trend log records coverage per sweep.
109
-
110
- ### 2c-ante. Quality decay of Accepted ADRs (adr-quality)
111
-
112
- ```bash
113
- "$ADR_KIT/bin/adr-quality" --adr-dir docs/adr --status Accepted 2>&1 | tail -20
114
- ```
115
-
116
- Quality is checked once, at acceptance, and then frozen. An ADR does not stay
117
- sharp on its own: the code moves, the references rot, the alternatives stop
118
- being the live ones. This is the only place that notices, and it is free — four
119
- deterministic gates, no model. Exit 1 means at least one Accepted record is
120
- below the threshold.
121
-
122
- **Response (mix-by-finding-type: Stale ADR):** name the record and its score.
123
- An Accepted body is immutable, so do **not** offer to rewrite it. The honest
124
- routes are a supersession (`/adr-kit:adr`) or a retirement, and a decayed score
125
- is a reason to ask whether the decision still holds — not proof that it does
126
- not. Never auto-apply either.
127
-
128
- ### 2c-bis. Generated-index freshness (adr-index)
129
-
130
- ```bash
131
- "$ADR_KIT/bin/adr-index" docs/adr/ --check 2>&1 | tail -5
132
- ```
133
-
134
- Exit 1 means `README.md`, `ADR-INDEX.md` or `ADR-INDEX.json` no longer matches
135
- the ADRs they are generated from. The lifecycle CLI regenerates all three inside
136
- its own transaction, so a stale index means an ADR was edited by hand or written
137
- straight to disk — the common case when a coding agent uses a Write tool.
138
-
139
- **Response (mix-by-finding-type: Health):** this one is safe to fix, because the
140
- files are generated rather than authored. Offer to run `bin/adr-index docs/adr`
141
- and show the diff. Do not fix it silently: the regenerated index is a commit the
142
- user has to make.
143
-
144
- ### 2d. Stamp cheap tier
145
-
146
- After completing 2a–2c, record the sweep. The `--retire-seen` argument must contain
147
- the full fresh candidate set (all ids, not just the new ones). The detector uses
148
- the stored set for the next session's change comparison. `--coverage` records the
149
- Enforcement coverage percent (from 2c) in the append-only trend log.
150
-
151
- ```bash
152
- "$ADR_KIT/bin/adr-guardian" stamp cheap \
153
- --violations <N_drift_violations> \
154
- --retire <N_retire_candidates> \
155
- --lint "<F>F/<A>A" \
156
- --coverage <coverage_pct_from_adr_status> \
157
- --retire-seen '<json_array_of_ALL_retire_candidate_ids>'
158
- ```
159
-
160
- ## Step 3 — LLM tier (suggest + audit) — ALWAYS confirm cost first
161
-
162
- **MANDATORY cost confirmation gate.** Before running this tier, read `docs/adr/.adr-kit.json`:
163
-
164
- - If `guardian.llm_autorun` is `false` (default), print:
165
-
166
- ```
167
- [adr-guardian] LLM tier: adr-suggest + full audit will invoke claude-sonnet-4-6.
168
- Estimated cost: ~$0.10–0.30. Run now? (y/N)
169
- ```
170
-
171
- And wait for an explicit `y` / `yes`. If the user says no (or presses Enter on the default), skip the LLM tier and stop at Step 4.
172
-
173
- - If `guardian.llm_autorun` is `true`, proceed without asking (user opted in explicitly in config).
174
-
175
- Run only when llm tier is due or explicitly requested (and user has confirmed cost).
176
-
177
- ### 3a. Missing-ADR detection (adr-suggest)
178
-
179
- ```bash
180
- git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-suggest" \
181
- --diff - \
182
- --adr-dir docs/adr/ \
183
- --json > /tmp/guardian-suggest.json 2>&1
184
- ```
185
-
186
- Read `/tmp/guardian-suggest.json`.
187
-
188
- **Response (mix-by-finding-type: Missing ADR):** Passive. List candidates where `needs_adr=true` with `confidence >= medium`. Offer to author selected ones via the `adr-generator` subagent. User picks; never auto-create.
189
-
190
- ### 3b. Full audit (adr-judge with LLM pass, one ADR at a time)
191
-
192
- The audit judges each ADR in an isolated call and stamps its verdict the moment
193
- it lands (ADR-037). A 68-ADR set at the measured 20-28 s per call runs ~25
194
- minutes; per-ADR stamping means an interruption keeps every verdict already
195
- reached, and per-ADR printing means the user can tell a long sweep from a hung
196
- one.
197
-
198
- First, resume-awareness: read `"$ADR_KIT/bin/adr-guardian" state` and collect
199
- `llm_tier.adrs`. Skip every ADR whose entry is younger than
200
- `guardian.llm_stale_days` with verdict `ok`. ADRs with a recorded `violation`
201
- are ALWAYS re-judged: that is how a fix clears them. Tell the user what is being
202
- skipped: `resuming: 41 of 68 fresh, 26 due, 1 violation to re-check`.
203
-
204
- Then derive the diff base ONCE, robustly. `HEAD~10` does not exist in a repo or
205
- shallow clone with fewer than 11 commits; git then fails to stderr and pipes an
206
- EMPTY diff, the judge exits 0, and the loop below would stamp every due ADR
207
- `ok` without judging anything — the same false completeness as the degradation
208
- case. Fall back to the root commit, and abort the sweep (stamping nothing) if
209
- even that yields nothing:
210
-
211
- ```bash
212
- BASE=$(git rev-parse --verify -q HEAD~10 || git rev-list --max-parents=0 HEAD | tail -1)
213
- ```
214
-
215
- Then loop over the due ADRs. For each:
216
-
217
- ```bash
218
- git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-judge" --diff - --adr-dir docs/adr/ --repo-root "$(git rev-parse --show-toplevel)" --snapshot worktree --llm --dry-run-enforcement ADR-NNN 2>&1
219
- ```
220
-
221
- Exit 0 is `ok`, exit 1 is `violation`; anything else (timeout, ADR not found)
222
- is NOT a verdict and must not be stamped.
223
-
224
- **Exit 0 alone is not proof the model judged.** The judge degrades to
225
- declarative-only when no backend is usable (missing host client, retired keys)
226
- and still exits 0, per its never-block contract — so a sweep with a broken
227
- backend would stamp every ADR `ok` without a single model call, exactly the
228
- false completeness ADR-037 forbids. Before mapping exit codes, check the
229
- captured output for a degradation marker (`DEGRADED to declarative-only`,
230
- `no LLM backend`, `LLM pass evaluated 0`): if present, stamp NOTHING, abort the
231
- sweep, and surface the backend problem with the judge's own fix-it line
232
- (`adr-judge --set-backend ...`). Print one line per ADR as it
233
- completes - id, verdict, elapsed seconds - then stamp immediately:
234
-
235
- ```bash
236
- "$ADR_KIT/bin/adr-guardian" stamp llm --adr ADR-NNN --verdict <ok|violation>
237
- ```
238
-
239
- Collect the violations for the summary. The sweep outcome is non-clean while
240
- any ADR carries a recorded `violation` - including ones recorded by an earlier
241
- sweep that this run did not reach. Same response per finding as Step 2a drift,
242
- but covering semantic violations not expressible as regex.
243
-
244
- ### 3c. Stamp LLM tier
245
-
246
- Only when every due ADR reached a verdict in step 3b: stamp the tier. A partial
247
- sweep skips this - the per-ADR stamps already preserve its work, and stamping
248
- the tier would claim a completeness the sweep did not deliver (ADR-037).
249
-
250
- If the cheap tier did not run in this sweep, read `summary.coverage_pct` from
251
- `"$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ --format json` and pass it via
252
- `--coverage` (when omitted, the trend entry carries the last known coverage).
253
-
254
- ```bash
255
- "$ADR_KIT/bin/adr-guardian" stamp llm \
256
- --suggest <N_suggest_hits> \
257
- --audit <N_audit_findings> \
258
- --coverage <coverage_pct_from_adr_status>
259
- ```
260
-
261
- ## Step 4 — Wrap-up
262
-
263
- Refresh the disposable Proposed decision queue after the deterministic sweep,
264
- outside SessionStart:
265
-
266
- ```bash
267
- "$ADR_KIT/bin/adr-guardian" refresh-readiness \
268
- --project-root "$(git rev-parse --show-toplevel)" --diff
269
- ```
270
-
271
- Then report at most the first three cached actions. The queue ranks active
272
- implementation links, shipped-but-Proposed records, ready-for-confirmation
273
- records, open human questions, age, and lowest quality in that order. Each
274
- action must use `/adr-kit:grill ADR-NNN`. The cache is derived, expiring,
275
- gitignored, safe to delete, and never authoritative for acceptance.
276
-
277
- Print a summary:
278
-
279
- ```
280
- [adr-guardian] sweep complete
281
- cheap tier: <X> drift violations · <R> retire candidates · <lint_summary>
282
- llm tier: <S> missing-ADR suggestions · <A> audit findings (or: skipped)
283
- → use /adr-kit:adr to author new ADRs, /adr-kit:judge for detailed resolution
284
- ```
285
-
286
- ## Constraints
287
-
288
- - **Never auto-apply ADR edits.** All stale/retire changes are drafts for human review.
289
- - **Never auto-create ADRs.** Missing-ADR suggestions are presented; user picks.
290
- - **Never skip the cost-confirm gate** when `llm_autorun: false`.
291
- - **Always stamp after each tier completes** so the next session's cooldown is correct.
292
- - **Model can self-call.** This skill is NOT `disable-model-invocation`. When the session model sees an `[adr-guardian] ... DUE` block injected at SessionStart, it should proactively offer to run the due tier via `/adr-kit:guardian`.
293
-
294
- ## Team mode
295
-
296
- The guardian has two complementary triggers; use both on team projects:
297
-
298
- - **SessionStart nudge (per developer).** The local hook plus this skill gives each developer a freshness signal on their own machine. The state file (`docs/adr/.adr-kit-state.json`) is gitignored, per-machine, advisory data: atomic writes keep it safe across parallel Claude Code sessions, and last-writer-wins is the accepted semantics.
299
- - **CI-cron sweep (shared team visibility).** A weekly GitHub Actions workflow (`.github/workflows/adr-guardian-audit.yml`; downstream copy-paste variant in `templates/github-workflows/adr-guardian-audit.yml`) runs the cheap tier only (lint + retire + status) and maintains a single "ADR guardian audit" tracking issue. Report-only: it never fails the build, never runs an LLM (ADR-001 posture), and needs no secrets beyond `GITHUB_TOKEN`.
300
-
301
- Both can coexist: the CI sweep does not read or write the local state file, and the local nudge cadence is unaffected by CI runs. The LLM tier remains local and opt-in only.
302
-
303
- ## SessionStart block handling (for in-session model)
304
-
305
- When the in-session model reads an `additionalContext` block starting with `[adr-guardian]`:
306
-
307
- When at least two sweeps have been stamped, the block also carries a one-line
308
- delta vs the previous sweep, e.g. `trend: drift 2 -> 0, retire 1 -> 2,
309
- coverage 40% -> 45%`. Use it to call out improving or degrading KPIs when
310
- offering the sweep.
311
-
312
- 1. Check which tier(s) are marked `DUE`.
313
- 2. For the **cheap** tier: offer immediately: "ADR drift/health check is due — run `/adr-kit:guardian cheap` to sweep (free, ~30s)?"
314
- 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."
315
- 4. If the user accepts either, invoke this skill with the appropriate argument.
316
- 5. Apply the mix-by-finding-type responses as documented above.
1
+ ---
2
+ name: guardian
3
+ description: "Check ADR health, drift, stale decisions, and lint. Use for ADR guardian, health sweep, stale ADRs, or an [adr-guardian] DUE notice."
4
+ argument-hint: "[cheap | llm | all]"
5
+ allowed-tools: [Read, Bash, Edit, Write, Task, Glob, Grep]
6
+ ---
7
+
8
+ # adr-kit guardian
9
+
10
+ Use `$ARGUMENTS` as `cheap`, `llm`, or `all`; default to the due tier when it
11
+ is empty. Never start paid or cloud judgment without explicit permission.
12
+
13
+ You are running the ADR-set health sweep. Your job is to run whichever tier(s) are due (or were requested), surface findings using the mix-by-finding-type responses below, and stamp the state file when done.
14
+
15
+ ## Before you start
16
+
17
+ Resolve the plugin bin path (same resolver used in /adr-kit:judge and /adr-kit:init):
18
+
19
+ ```bash
20
+ ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1)
21
+ ```
22
+
23
+ If `ADR_KIT` is empty (plugin not installed), fall back to a local checkout:
24
+
25
+ ```bash
26
+ # try local checkout
27
+ ADR_KIT=$(git rev-parse --show-toplevel 2>/dev/null)/
28
+ ```
29
+
30
+ Verify the guardian bin exists:
31
+
32
+ ```bash
33
+ ls "$ADR_KIT/bin/adr-guardian" 2>/dev/null || echo "guardian not found"
34
+ ```
35
+
36
+ ## Step 1 — Determine which tier(s) to run
37
+
38
+ If invoked with an explicit argument (`cheap`, `llm`, or `all`), honour it.
39
+
40
+ Otherwise, read the current state to determine due tiers:
41
+
42
+ ```bash
43
+ "$ADR_KIT/bin/adr-guardian" state
44
+ ```
45
+
46
+ Compute which tier is due based on `cheap_tier.last_run` vs `guardian.drift_stale_days` and `llm_tier.last_run` vs `guardian.llm_stale_days` (defaults: 1d cheap, 14d LLM). If neither is due, report "Both tiers are current — nothing to sweep" and stop.
47
+
48
+ Read `docs/adr/.adr-kit.json` if it exists to get any custom `guardian.*` config.
49
+
50
+ ## Step 2 — Cheap tier (drift + stale + lint)
51
+
52
+ Run only when cheap tier is due or explicitly requested.
53
+
54
+ ### 2a. Drift check (declarative, adr-judge)
55
+
56
+ ```bash
57
+ # HEAD~5 does not exist in a repo or shallow clone with fewer than 6 commits;
58
+ # git then fails to stderr and pipes an EMPTY diff, which the judge passes with
59
+ # exit 0 — a drift check that checked nothing. Fall back to the root commit.
60
+ BASE=$(git rev-parse --verify -q HEAD~5 || git rev-list --max-parents=0 HEAD | tail -1)
61
+ git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-judge" \
62
+ --diff - \
63
+ --adr-dir docs/adr/ \
64
+ --repo-root "$(git rev-parse --show-toplevel)" \
65
+ --snapshot worktree \
66
+ --json > /tmp/guardian-drift.json 2>&1
67
+ DRIFT_EXIT=$?
68
+ ```
69
+
70
+ Read `/tmp/guardian-drift.json`. Count violations and advisories.
71
+
72
+ **Response (mix-by-finding-type: Drift):** Surface prominently. List each violation with file:line + ADR id. Offer to (a) fix the code, (b) write a new ADR covering the new pattern, or (c) supersede the violated ADR. Highest-priority finding type.
73
+
74
+ ### 2b. Stale ADR detection (adr-retire)
75
+
76
+ ```bash
77
+ "$ADR_KIT/bin/adr-retire" \
78
+ docs/adr/ \
79
+ --format json > /tmp/guardian-retire.json 2>&1
80
+ ```
81
+
82
+ Read `/tmp/guardian-retire.json`. Collect the candidate set: extract the list of ADR ids flagged for retirement (candidates).
83
+
84
+ **Change-based filtering:** Read `retire_seen` from the state file (`adr-guardian state`). Compare the fresh candidate set against `retire_seen`. Only surface candidates that are *new* (present in fresh set but not in `retire_seen`). This avoids daily nagging about the same stale ADRs. If all candidates are already in `retire_seen`, skip the retire response silently for this sweep.
85
+
86
+ **Response (mix-by-finding-type: Stale ADR):** For each **new** retire candidate, draft a retirement/supersession skeleton for human review — never auto-apply. Show:
87
+ - The ADR id and title.
88
+ - The retirement signal (tech removed / superseded target missing / policy drift / age threshold).
89
+ - A draft Status flip: `Deprecated, <today>` or `Superseded by ADR-NNN, <today>` (if a superseding ADR exists).
90
+ - Ask the user to confirm or skip each.
91
+
92
+ ### 2c. Health lint (adr-lint / adr-status)
93
+
94
+ ```bash
95
+ "$ADR_KIT/bin/adr-lint" docs/adr/ 2>&1 | tail -20
96
+ "$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ 2>&1 | tail -5
97
+ ```
98
+
99
+ **Response (mix-by-finding-type: Health):** Emit a PASS/ADVISORY/FAIL summary. For FAILs: list the gate name and ADR, offer to fix via `/adr-kit:adr` (re-run the adr-generator subagent on that ADR).
100
+
101
+ Also read the Enforcement coverage percent for the trend history:
102
+
103
+ ```bash
104
+ "$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ --format json > /tmp/guardian-status.json 2>&1
105
+ ```
106
+
107
+ Extract `summary.coverage_pct` from `/tmp/guardian-status.json`. You will pass it
108
+ to the stamp call below so the trend log records coverage per sweep.
109
+
110
+ ### 2c-ante. Quality decay of Accepted ADRs (adr-quality)
111
+
112
+ ```bash
113
+ "$ADR_KIT/bin/adr-quality" --adr-dir docs/adr --status Accepted 2>&1 | tail -20
114
+ ```
115
+
116
+ Quality is checked once, at acceptance, and then frozen. An ADR does not stay
117
+ sharp on its own: the code moves, the references rot, the alternatives stop
118
+ being the live ones. This is the only place that notices, and it is free — four
119
+ deterministic gates, no model. Exit 1 means at least one Accepted record is
120
+ below the threshold.
121
+
122
+ **Response (mix-by-finding-type: Stale ADR):** name the record and its score.
123
+ An Accepted body is immutable, so do **not** offer to rewrite it. The honest
124
+ routes are a supersession (`/adr-kit:adr`) or a retirement, and a decayed score
125
+ is a reason to ask whether the decision still holds — not proof that it does
126
+ not. Never auto-apply either.
127
+
128
+ ### 2c-bis. Generated-index freshness (adr-index)
129
+
130
+ ```bash
131
+ "$ADR_KIT/bin/adr-index" docs/adr/ --check 2>&1 | tail -5
132
+ ```
133
+
134
+ Exit 1 means `README.md`, `ADR-INDEX.md` or `ADR-INDEX.json` no longer matches
135
+ the ADRs they are generated from. The lifecycle CLI regenerates all three inside
136
+ its own transaction, so a stale index means an ADR was edited by hand or written
137
+ straight to disk — the common case when a coding agent uses a Write tool.
138
+
139
+ **Response (mix-by-finding-type: Health):** this one is safe to fix, because the
140
+ files are generated rather than authored. Offer to run `bin/adr-index docs/adr`
141
+ and show the diff. Do not fix it silently: the regenerated index is a commit the
142
+ user has to make.
143
+
144
+ ### 2d. Stamp cheap tier
145
+
146
+ After completing 2a–2c, record the sweep. The `--retire-seen` argument must contain
147
+ the full fresh candidate set (all ids, not just the new ones). The detector uses
148
+ the stored set for the next session's change comparison. `--coverage` records the
149
+ Enforcement coverage percent (from 2c) in the append-only trend log.
150
+
151
+ ```bash
152
+ "$ADR_KIT/bin/adr-guardian" stamp cheap \
153
+ --violations <N_drift_violations> \
154
+ --retire <N_retire_candidates> \
155
+ --lint "<F>F/<A>A" \
156
+ --coverage <coverage_pct_from_adr_status> \
157
+ --retire-seen '<json_array_of_ALL_retire_candidate_ids>'
158
+ ```
159
+
160
+ ## Step 3 — LLM tier (suggest + audit) — ALWAYS confirm cost first
161
+
162
+ **MANDATORY cost confirmation gate.** Before running this tier, read `docs/adr/.adr-kit.json`:
163
+
164
+ - If `guardian.llm_autorun` is `false` (default), print:
165
+
166
+ ```
167
+ [adr-guardian] LLM tier: adr-suggest + full audit will invoke claude-sonnet-4-6.
168
+ Estimated cost: ~$0.10–0.30. Run now? (y/N)
169
+ ```
170
+
171
+ And wait for an explicit `y` / `yes`. If the user says no (or presses Enter on the default), skip the LLM tier and stop at Step 4.
172
+
173
+ - If `guardian.llm_autorun` is `true`, proceed without asking (user opted in explicitly in config).
174
+
175
+ Run only when llm tier is due or explicitly requested (and user has confirmed cost).
176
+
177
+ ### 3a. Missing-ADR detection (adr-suggest)
178
+
179
+ ```bash
180
+ git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-suggest" \
181
+ --diff - \
182
+ --adr-dir docs/adr/ \
183
+ --json > /tmp/guardian-suggest.json 2>&1
184
+ ```
185
+
186
+ Read `/tmp/guardian-suggest.json`.
187
+
188
+ **Response (mix-by-finding-type: Missing ADR):** Passive. List candidates where `needs_adr=true` with `confidence >= medium`. Offer to author selected ones via the `adr-generator` subagent. User picks; never auto-create.
189
+
190
+ ### 3b. Full audit (adr-judge with LLM pass, one ADR at a time)
191
+
192
+ The audit judges each ADR in an isolated call and stamps its verdict the moment
193
+ it lands (ADR-037). A 68-ADR set at the measured 20-28 s per call runs ~25
194
+ minutes; per-ADR stamping means an interruption keeps every verdict already
195
+ reached, and per-ADR printing means the user can tell a long sweep from a hung
196
+ one.
197
+
198
+ First, resume-awareness: read `"$ADR_KIT/bin/adr-guardian" state` and collect
199
+ `llm_tier.adrs`. Skip every ADR whose entry is younger than
200
+ `guardian.llm_stale_days` with verdict `ok`. ADRs with a recorded `violation`
201
+ are ALWAYS re-judged: that is how a fix clears them. Tell the user what is being
202
+ skipped: `resuming: 41 of 68 fresh, 26 due, 1 violation to re-check`.
203
+
204
+ Then derive the diff base ONCE, robustly. `HEAD~10` does not exist in a repo or
205
+ shallow clone with fewer than 11 commits; git then fails to stderr and pipes an
206
+ EMPTY diff, the judge exits 0, and the loop below would stamp every due ADR
207
+ `ok` without judging anything — the same false completeness as the degradation
208
+ case. Fall back to the root commit, and abort the sweep (stamping nothing) if
209
+ even that yields nothing:
210
+
211
+ ```bash
212
+ BASE=$(git rev-parse --verify -q HEAD~10 || git rev-list --max-parents=0 HEAD | tail -1)
213
+ ```
214
+
215
+ Then loop over the due ADRs. For each:
216
+
217
+ ```bash
218
+ git diff "$BASE" HEAD --unified=0 | "$ADR_KIT/bin/adr-judge" --diff - --adr-dir docs/adr/ --repo-root "$(git rev-parse --show-toplevel)" --snapshot worktree --llm --dry-run-enforcement ADR-NNN 2>&1
219
+ ```
220
+
221
+ Exit 0 is `ok`, exit 1 is `violation`; anything else (timeout, ADR not found)
222
+ is NOT a verdict and must not be stamped.
223
+
224
+ **Exit 0 alone is not proof the model judged.** The judge degrades to
225
+ declarative-only when no backend is usable (missing host client, retired keys)
226
+ and still exits 0, per its never-block contract — so a sweep with a broken
227
+ backend would stamp every ADR `ok` without a single model call, exactly the
228
+ false completeness ADR-037 forbids. Before mapping exit codes, check the
229
+ captured output for a degradation marker (`DEGRADED to declarative-only`,
230
+ `no LLM backend`, `LLM pass evaluated 0`): if present, stamp NOTHING, abort the
231
+ sweep, and surface the backend problem with the judge's own fix-it line
232
+ (`adr-judge --set-backend ...`). Print one line per ADR as it
233
+ completes - id, verdict, elapsed seconds - then stamp immediately:
234
+
235
+ ```bash
236
+ "$ADR_KIT/bin/adr-guardian" stamp llm --adr ADR-NNN --verdict <ok|violation>
237
+ ```
238
+
239
+ Collect the violations for the summary. The sweep outcome is non-clean while
240
+ any ADR carries a recorded `violation` - including ones recorded by an earlier
241
+ sweep that this run did not reach. Same response per finding as Step 2a drift,
242
+ but covering semantic violations not expressible as regex.
243
+
244
+ ### 3c. Stamp LLM tier
245
+
246
+ Only when every due ADR reached a verdict in step 3b: stamp the tier. A partial
247
+ sweep skips this - the per-ADR stamps already preserve its work, and stamping
248
+ the tier would claim a completeness the sweep did not deliver (ADR-037).
249
+
250
+ If the cheap tier did not run in this sweep, read `summary.coverage_pct` from
251
+ `"$ADR_KIT/bin/adr-status" --adr-dir docs/adr/ --format json` and pass it via
252
+ `--coverage` (when omitted, the trend entry carries the last known coverage).
253
+
254
+ ```bash
255
+ "$ADR_KIT/bin/adr-guardian" stamp llm \
256
+ --suggest <N_suggest_hits> \
257
+ --audit <N_audit_findings> \
258
+ --coverage <coverage_pct_from_adr_status>
259
+ ```
260
+
261
+ ## Step 4 — Wrap-up
262
+
263
+ Refresh the disposable Proposed decision queue after the deterministic sweep,
264
+ outside SessionStart:
265
+
266
+ ```bash
267
+ "$ADR_KIT/bin/adr-guardian" refresh-readiness \
268
+ --project-root "$(git rev-parse --show-toplevel)" --diff
269
+ ```
270
+
271
+ Then report at most the first three cached actions. The queue ranks active
272
+ implementation links, shipped-but-Proposed records, ready-for-confirmation
273
+ records, open human questions, age, and lowest quality in that order. Each
274
+ action must use `/adr-kit:grill ADR-NNN`. The cache is derived, expiring,
275
+ gitignored, safe to delete, and never authoritative for acceptance.
276
+
277
+ Print a summary:
278
+
279
+ ```
280
+ [adr-guardian] sweep complete
281
+ cheap tier: <X> drift violations · <R> retire candidates · <lint_summary>
282
+ llm tier: <S> missing-ADR suggestions · <A> audit findings (or: skipped)
283
+ → use /adr-kit:adr to author new ADRs, /adr-kit:judge for detailed resolution
284
+ ```
285
+
286
+ ## Constraints
287
+
288
+ - **Never auto-apply ADR edits.** All stale/retire changes are drafts for human review.
289
+ - **Never auto-create ADRs.** Missing-ADR suggestions are presented; user picks.
290
+ - **Never skip the cost-confirm gate** when `llm_autorun: false`.
291
+ - **Always stamp after each tier completes** so the next session's cooldown is correct.
292
+ - **Model can self-call.** This skill is NOT `disable-model-invocation`. When the session model sees an `[adr-guardian] ... DUE` block injected at SessionStart, it should proactively offer to run the due tier via `/adr-kit:guardian`.
293
+
294
+ ## Team mode
295
+
296
+ The guardian has two complementary triggers; use both on team projects:
297
+
298
+ - **SessionStart nudge (per developer).** The local hook plus this skill gives each developer a freshness signal on their own machine. The state file (`docs/adr/.adr-kit-state.json`) is gitignored, per-machine, advisory data: atomic writes keep it safe across parallel Claude Code sessions, and last-writer-wins is the accepted semantics.
299
+ - **CI-cron sweep (shared team visibility).** A weekly GitHub Actions workflow (`.github/workflows/adr-guardian-audit.yml`; downstream copy-paste variant in `templates/github-workflows/adr-guardian-audit.yml`) runs the cheap tier only (lint + retire + status) and maintains a single "ADR guardian audit" tracking issue. Report-only: it never fails the build, never runs an LLM (ADR-001 posture), and needs no secrets beyond `GITHUB_TOKEN`.
300
+
301
+ Both can coexist: the CI sweep does not read or write the local state file, and the local nudge cadence is unaffected by CI runs. The LLM tier remains local and opt-in only.
302
+
303
+ ## SessionStart block handling (for in-session model)
304
+
305
+ When the in-session model reads an `additionalContext` block starting with `[adr-guardian]`:
306
+
307
+ When at least two sweeps have been stamped, the block also carries a one-line
308
+ delta vs the previous sweep, e.g. `trend: drift 2 -> 0, retire 1 -> 2,
309
+ coverage 40% -> 45%`. Use it to call out improving or degrading KPIs when
310
+ offering the sweep.
311
+
312
+ 1. Check which tier(s) are marked `DUE`.
313
+ 2. For the **cheap** tier: offer immediately: "ADR drift/health check is due — run `/adr-kit:guardian cheap` to sweep (free, ~30s)?"
314
+ 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."
315
+ 4. If the user accepts either, invoke this skill with the appropriate argument.
316
+ 5. Apply the mix-by-finding-type responses as documented above.