@rvdbreemen/adr-kit-opencode 0.59.1 → 0.60.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 (41) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +66 -24
  3. package/bin/adr-context +2 -1
  4. package/bin/adr-doctor +1 -1
  5. package/bin/adr-guardian +10 -1
  6. package/bin/adr-judge +12 -57
  7. package/bin/adr-settings +59 -8
  8. package/bin/adr-substance +15 -0
  9. package/bin/adr-suggest +8 -3
  10. package/bin/adr_config.py +33 -0
  11. package/bin/adr_doctor_checks.py +9 -3
  12. package/bin/adr_doctor_core.py +4 -4
  13. package/bin/adr_doctor_probes.py +100 -13
  14. package/bin/adr_llm.py +178 -3
  15. package/bin/adr_readiness.py +17 -1
  16. package/clients/workflows.json +10 -7
  17. package/hooks/adr_hook_core.py +176 -28
  18. package/instructions/ADR-guide.md +1 -1
  19. package/opencode/plugin.ts +52 -10
  20. package/package.json +1 -1
  21. package/schemas/adr-kit-config.schema.json +7 -2
  22. package/scripts/client_generation.py +2 -5
  23. package/scripts/client_generation_artifacts.py +13 -2
  24. package/scripts/client_generation_model.py +4 -0
  25. package/scripts/release_phases.py +7 -7
  26. package/skills/guardian/SKILL.md +6 -4
  27. package/skills/init/SKILL.md +32 -11
  28. package/skills/install-hooks/SKILL.md +10 -9
  29. package/skills/judge/SKILL.md +6 -3
  30. package/skills/lint/SKILL.md +2 -1
  31. package/skills/related/SKILL.md +2 -1
  32. package/skills/review/SKILL.md +2 -1
  33. package/skills/setup/SKILL.md +2 -1
  34. package/skills/supersede/SKILL.md +2 -1
  35. package/skills/upgrade/SKILL.md +22 -3
  36. package/templates/adr-kit-guide.md +3 -3
  37. package/templates/cc-settings/guardian-hook-entry.json +2 -2
  38. package/templates/githooks/pre-commit +37 -9
  39. package/templates/github-workflows/adr-index-check.yml +1 -1
  40. package/templates/github-workflows/adr-judge.yml +1 -1
  41. package/templates/github-workflows/adr-readiness.yml +1 -1
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "adr-kit",
3
3
  "description": "Architecture Decision Record toolkit for AI coding agents: bootstrap, multi-format authoring, bounded deterministic enforcement, lifecycle workflows, context injection, generated graph indexes, and local health checks.",
4
- "version": "0.59.1",
4
+ "version": "0.60.0",
5
5
  "author": {
6
6
  "name": "Robert van den Breemen",
7
7
  "url": "https://github.com/rvdbreemen"
package/README.md CHANGED
@@ -44,8 +44,10 @@ which are ready to retire, so the decision log stays worth reading instead of
44
44
  becoming another folder of dead markdown.
45
45
 
46
46
  The engines are deterministic, stdlib-only Python 3.10+: no build step, no
47
- service, no API key on any default path. LLM passes exist, are opt-in, cost
48
- nothing until you enable them, and never run in a hook hot path.
47
+ service, no API key on any default path. The LLM passes run on the model of
48
+ the coding agent you already use, never in a hook hot path, and can be switched
49
+ off or pointed at a model on your own machine; see
50
+ [LLM passes](#llm-passes-on-your-agents-model-by-default-local-by-choice).
49
51
 
50
52
  <img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/c99f81eb-6424-4463-8c1d-4aa8a017aa61" />
51
53
 
@@ -100,8 +102,11 @@ patch releases, is in [CHANGELOG.md](CHANGELOG.md).
100
102
 
101
103
  | Version | What landed | Why it matters |
102
104
  | --- | --- | --- |
105
+ | **0.58.0** | `adr-substance` asks the host model, in the guardian's LLM tier, whether each written section of a Proposed ADR actually says something. `adr-judge --check-scope` names every Enforcement rule of an Accepted ADR whose `path_glob` matches no tracked file, and the judge's LLM pass gets a ceiling it keeps (`judge.llm_pass_timeout_seconds`, default 600). | The deterministic gates stop at markers: "TBD" or three vacuous sentences read as written to them. A rule whose scope matches nothing guards nothing, and a commit no longer waits without end on a slow host CLI. |
106
+ | **0.57.0** | One command drives a release: `python scripts/release.py X.Y.Z` runs every step of [docs/RELEASING.md](docs/RELEASING.md), and `release-publish.yml` creates the tag from the merged `main` commit ([ADR-042](docs/adr/ADR-042-drive-the-release-from-the-maintainer-s-machine-and-create-the-tag-from-the-merge.md)). | A hand-typed tag on the wrong commit destroyed `v0.55.0`; the tag is now derived from the merge, the driver is safe to re-run, and only the npm approval is left to a person. |
103
107
  | **0.55.1** | [ADR-029](docs/adr/ADR-029-retire-the-native-hook-binary-rather-than-maintain-a-second-retrieval-engine.md) is carried out: the committed `adr-hook.exe`, its Rust sources, the dispatcher branch that preferred it and the `ADR_KIT_NATIVE_HOOK` opt-in are gone from all three client trees, so Python is the only hook host on every platform. `adr-mcp` now rejects malformed JSON-RPC frames instead of answering them. | The binary was measurably wrong, not merely untested: against the Python oracle it returned one of four governing ADRs on an edit event, and the parity test that should have caught it read a constant out of the Rust source instead of running the build. One retrieval engine means the hook answers what the CLI answers. On the MCP side, a server that answers a malformed frame hides a client defect the client cannot see in its own logs. |
104
108
  | **0.54.0** | Automatic interactive ADR grilling ([ADR-041](docs/adr/ADR-041-automatically-hand-off-unfinished-proposed-adrs-to-interactive-grilling.md)) hands one unfinished Proposed decision to the native grill workflow at the next user-visible prompt. `/adr-kit:upgrade` materializes `grill.auto_start: true` while preserving explicit opt-outs. | Incomplete decisions reach the human while their implementation context is still available, without starting interviews in CI, pre-commit, background, or unattended lifecycle paths. |
109
+ | **0.53.0** | The MCP server gains `adr_lint` and `adr_related`, for seven read-only deterministic tools; [ADR-040](docs/adr/ADR-040-grow-the-mcp-tool-surface-only-with-read-only-deterministic-cycle-tools.md) records the admission rule. | An agent can lint the decision set and walk its dependency graph without shelling out, and the tool surface grows only with tools that cannot change anything. |
105
110
  | **0.52.0** | Native [OpenCode](docs/clients/opencode.md) support through a separate TypeScript plugin, backed by the shared deterministic engines and MCP server ([ADR-039](docs/adr/ADR-039-add-a-native-opencode-plugin-without-expanding-the-certified-cli-gate.md)). The certified Claude Code, Codex, and Copilot CLI registry and release gate remain unchanged. | OpenCode gets its documented native configuration, skills, commands, context, compaction, edit, shell, and MCP integration without weakening the existing certification boundary. |
106
111
  | **0.48.0** | Retrieval is lexical scoring over the generated index plus one-hop graph neighbours, and the LLM judge runs on the CLI you are already signed in to ([ADR-036](docs/adr/ADR-036-retire-the-vector-layer-and-run-the-judge-on-the-host-model-only.md)): the vector subsystem, `bin/adr-embed` and the openrouter/ollama/openai backends are gone, and eight retired config keys now fail validation by name. The guardian records a verdict per ADR and prints it as the sweep lands ([ADR-037](docs/adr/ADR-037-keep-per-adr-judge-verdicts-in-the-advisory-per-machine-guardian-state.md)). | Two subsystems were carrying their own credentials, install paths and failure modes to answer questions the index already answers. A sweep is also long enough to be interrupted, so a per-sweep timestamp discarded everything it had established; per-ADR verdicts keep it. |
107
112
  | **0.44.0** | `/adr-kit:audit` answers "are we still on course?" by linting the decisions and judging the code in one run, over a diff or the whole codebase (the init scanner is now `bin/adr-discover`). A local precomputed vector layer for retrieval ([ADR-018](docs/adr/ADR-018-add-a-local-precomputed-vector-layer-for-adr-retrieval.md), retired in 0.48.0 by ADR-036), `adr relate` writing a cross-reference on both sides at once, `adr answer` keeping a grilling question with its answer, a configurable signer, `/adr-kit:settings`, and a pre-PR branch guard. | A clean judge over vague ADRs proves nothing, and a sharp ADR set nobody checks the code against is documentation rather than governance. Whole-codebase mode reaches files no recent diff touched, which is where a rule added after the code was written has never applied. |
@@ -207,12 +212,11 @@ python scripts/setup-project.py --project-root /path/to/project
207
212
  ```
208
213
 
209
214
  Settings also cover verified stable updates, trigger/frequency, offline and
210
- pinned operation, per-client opt-outs, doctor repair/check-only policy, and
211
- local versus paid/cloud judgment. No provider or model tag is a fallback
212
- default. `--probe-models` performs a bounded local identity check without
213
- invoking a model; zero or multiple candidates remain visibly unavailable or
214
- ambiguous. Paid/cloud judgment remains explicit opt-in, and no model runs in a
215
- hook hot path.
215
+ pinned operation, per-client opt-outs, and doctor repair/check-only policy.
216
+ Which model judges is not a setting: the LLM passes use your coding agent's own
217
+ CLI, or a command you choose on your own machine (see
218
+ [LLM passes](#llm-passes-on-your-agents-model-by-default-local-by-choice)). No
219
+ model runs in a hook hot path.
216
220
 
217
221
  ### Claude Code
218
222
 
@@ -271,7 +275,7 @@ copilot mcp list
271
275
  This targets `@github/copilot` invoked as `copilot`, not `gh copilot` or VS
272
276
  Code agent mode. The separate `copilot/` distribution follows GitHub's
273
277
  [Copilot plugin contract](https://docs.github.com/en/copilot/concepts/agents/about-plugins)
274
- and installs 15 skills plus the same key-free MCP server.
278
+ and installs 17 skills plus the same key-free MCP server.
275
279
  Open `/skills` inside Copilot CLI to discover ADR Kit workflows. Its lower-camel
276
280
  hook package supplies proactive session/task context and PostToolUse; pre-commit
277
281
  remains the edit-enforcement backstop.
@@ -314,7 +318,7 @@ For another project, use the published package:
314
318
  ```json
315
319
  {
316
320
  "$schema": "https://opencode.ai/config.json",
317
- "plugin": ["@rvdbreemen/adr-kit-opencode@0.59.1"]
321
+ "plugin": ["@rvdbreemen/adr-kit-opencode@0.60.0"]
318
322
  }
319
323
  ```
320
324
 
@@ -416,7 +420,7 @@ Three layers, each with a clear path:
416
420
 
417
421
  ### Maintain the decision log (decisions age; the kit notices)
418
422
 
419
- - **The Guardian (`bin/adr-guardian`, `/adr-kit:guardian`)**: a session-start staleness detector with two tiers. The cheap tier (daily, free) checks for code drift against Enforcement rules, retirement candidates, lint health, and refreshes a bounded Proposed-ADR work queue. SessionStart reads only that local 24-hour cache and offers at most three next actions; it never scans or starts an interview in the hook. The LLM tier (bi-weekly, asks before spending) hunts for missing ADRs and runs the full model-reviewed audit. Findings get mixed responses by type: drift is surfaced loudly with file:line, missing decisions are offered for authoring, stale ADRs get a retirement draft for review. Never runs in the background, never spends without asking.
423
+ - **The Guardian (`bin/adr-guardian`, `/adr-kit:guardian`)**: a session-start staleness detector with two tiers. The cheap tier (daily, free) checks for code drift against Enforcement rules, retirement candidates, lint health, and refreshes a bounded Proposed-ADR work queue. SessionStart offers at most three next actions from that local 24-hour cache; the plugin hook only reads it. When the project-scoped guardian hook (`/adr-kit:install-hooks`) is installed, `adr-guardian check` rebuilds a missing or expired cache in-process from the ADR files (no model, no spawn) for the next read. It never starts an interview in the hook. The LLM tier (bi-weekly, asks before spending) hunts for missing ADRs and runs the full model-reviewed audit. Findings get mixed responses by type: drift is surfaced loudly with file:line, missing decisions are offered for authoring, stale ADRs get a retirement draft for review. Never runs in the background, never spends without asking.
420
424
  - **Team mode (v0.22.0+)**: a weekly CI cron sweep maintains a single "ADR guardian audit" tracking issue (created on findings, updated, closed when clean) so the whole team sees ADR health, not just whoever opened a session today. Copy `templates/github-workflows/adr-guardian-audit.yml` into your repo.
421
425
  - **Trend history (v0.29.0+)**: every sweep appends to a 52-entry trend log, and the nudge shows the delta: `trend: drift 2 -> 0, retire 1 -> 2, coverage 40% -> 45%`. A KPI with memory, not a snapshot.
422
426
  - **Sections that say nothing (v0.58.0+)**: in the LLM tier, `bin/adr-substance` asks the model whether each written section of a Proposed ADR answers its heading, and reports "TBD", "see above" and generic prose with the author's own words quoted. One call per Proposed ADR, counted in the cost prompt; advisory only.
@@ -424,7 +428,7 @@ Three layers, each with a clear path:
424
428
  - **Health dashboard (`adr-audit status`)**: totals, status breakdown, average age, enforcement health, retirement candidates, retrieval probe results, Accepted-binding metadata completeness, and the **Enforcement coverage percentage** of your Accepted ADRs. JSON, markdown, or table.
425
429
  - **Quality scoring (`adr-audit quality`)**: grades every ADR A to D across the four gates (Completeness 40%, Evidence 20%, Clarity 20%, Consistency 20%), with per-gate issue codes. Exits 1 below grade B, so you can gate CI on ADR quality.
426
430
  - **Generated index refresh (`bin/adr-index docs/adr/`)**: atomically rebuilds the sentinel-owned `docs/adr/README.md` block plus `ADR-INDEX.md` and `ADR-INDEX.json`. `--check` exits non-zero when any generated view is missing or stale, or duplicate ADR ids exist. Use `--format graph --adr-dir docs/adr` to inspect the graph without writing.
427
- - **Local doctor (`adr-audit doctor`)**: fast mode checks ADR/index state, retrieval probes and metadata completeness, settings, generated artifacts, managed guidance, Claude/Codex/Copilot identity, MCP launchers, and cached model health without login or model invocation. Probe failures block; metadata completeness is advisory unless configured strict. Default mode repairs only deterministic ADR Kit-owned drift; `--check` is read-only, `--fix` permits backed-up managed rewrites, and `--deep` adds bounded native, MCP, and local-model probes. See [troubleshooting](TROUBLESHOOTING.md).
431
+ - **Local doctor (`adr-audit doctor`)**: fast mode checks ADR/index state, retrieval probes and metadata completeness, settings, generated artifacts, managed guidance, Claude/Codex/Copilot identity, and MCP launchers without login or model invocation. Probe failures block; metadata completeness is advisory unless configured strict. Default mode repairs only deterministic ADR Kit-owned drift; `--check` is read-only, `--fix` permits backed-up managed rewrites, and `--deep` adds bounded native, MCP, and local-model probes. See [troubleshooting](TROUBLESHOOTING.md).
428
432
  - **Lifecycle commands (`bin/adr`, v0.32.0+)**: local `propose`, `accept`, `supersede`, `reject`, and `document` commands update frontmatter, the Status section, append-only Status History, reciprocal supersession links, and then refresh the generated README index.
429
433
  - **After-the-fact acceptance (`bin/adr document` + `bin/adr accept --auto`)**: mark already-shipped behavior with `documents_shipped:true` and local `verified_in` pointers, then verify strict lint, quality, and human readiness. The default `assist` mode reports eligibility without mutating; acceptance requires `--confirm` after the engineer reviews the packet. Existing projects that intentionally require the legacy automatic transition can explicitly configure `lifecycle.auto_accept.mode: "auto"`.
430
434
  - **Retirement audit (`/adr-kit:retire`, `bin/adr-retire`)**: ranks Accepted ADRs for retirement using four deterministic signals (status age, technology removal, supersession, policy drift). Read-only; a recommendation always needs a human.
@@ -610,12 +614,12 @@ All configuration lives in one optional file: `docs/adr/.adr-kit.json` (annotate
610
614
  role parsing.
611
615
  - Per-file markers for one-off grandfathering: `<!-- adr-kit-lint: skip -->`, `skip <gate>[, ...]`, or `advisory` anywhere in an ADR.
612
616
 
613
- ### LLM passes: always opt-in, never surprise cost
617
+ ### LLM passes: on your agent's model by default, local by choice
614
618
 
615
619
  ```json
616
620
  {
617
- "judge": { "llm_enabled": false, "llm_model": "claude-sonnet-4-6", "llm_timeout_seconds": 120 },
618
- "suggest": { "enabled": false },
621
+ "judge": { "llm_enabled": true, "llm_timeout_seconds": 120, "llm_pass_timeout_seconds": 600 },
622
+ "suggest": { "enabled": true },
619
623
  "guardian": {
620
624
  "enabled": true,
621
625
  "drift_stale_days": 1,
@@ -627,11 +631,49 @@ All configuration lives in one optional file: `docs/adr/.adr-kit.json` (annotate
627
631
  }
628
632
  ```
629
633
 
630
- - The pre-commit hook's declarative pass is always on and free. The LLM judge pass is opt-in (`judge.llm_enabled`, or `ADR_KIT_LLM=1` per commit; `ADR_KIT_NO_LLM=1` to suppress). A flock guard serializes LLM passes across parallel commits.
634
+ - The pre-commit hook's declarative pass is always on and free.
635
+ - The LLM judge pass is **on by default** (`judge.llm_enabled: true`), and runs on the coding assistant the plugin is installed in. The first session in a project records that client as the judge's host (Claude Code, Codex, Copilot CLI or OpenCode; a recorded choice is never replaced), and the next prompt asks you once whether to keep each LLM layer on or turn it off for your machine (ADR-049); `/adr-kit:init` and `/adr-kit:upgrade` ask the same per layer. The pass runs through that client's own CLI (`claude -p`, `codex exec`, `copilot -p` or `opencode run`, ADR-036), on your existing subscription: no API key, no adr-kit service. Your staged diff and the governing ADRs go to that client's model, one isolated call per ADR whose `llm_judge: true` scope the diff touches, so a commit can take a minute or more. Each call is capped by `judge.llm_timeout_seconds` and the whole pass by `judge.llm_pass_timeout_seconds`. A clear `VIOLATION` verdict blocks the commit like a declarative one (set `judge.advisory_only: true` to report instead); an answer the judge cannot parse degrades to the declarative result instead of blocking.
636
+ - Turn it off for one commit with `ADR_KIT_NO_LLM=1`, for your machine with `adr-settings --set judge.llm_enabled=false --local` (the gitignored `.adr-kit.local.json`; your teammates keep it on), or for the whole project with `judge.llm_enabled: false` in `.adr-kit.json`. A flock guard serializes LLM passes across parallel commits.
631
637
  - `suggest.enabled` defaults to `true` (ADR-035): the advisory missing-decision nudge runs on the same terms as the judge, resolving through the shared backend registry with no pinned model. It never blocks and silently skips on any failure. Set `suggest.enabled: false` to switch it off per project, or export `ADR_KIT_SUGGEST_DISABLE=1` for a single run; `ADR_KIT_SUGGEST=1` still re-enables it per commit for a project that has set it false.
632
- - The guardian's cheap tier is free and daily; the LLM tier is bi-weekly and always asks first unless you set `llm_autorun: true` (not recommended; see ADR-001 in this repo).
638
+ - The guardian's cheap tier is free and daily; the LLM tier is bi-weekly and always asks first unless you set `llm_autorun: true` (not recommended; see ADR-001 in this repo). `guardian.llm_enabled: false` switches the LLM tier off entirely.
633
639
  - `watch` tunes the in-flight nudges; `cooldown_hours: 0` disables the cooldown, `enabled: false` silences the watcher.
634
640
 
641
+ #### Working locally (opt-in)
642
+
643
+ You can keep every diff on your own machine. There are two ways to do that.
644
+
645
+ **No model at all.** Export `ADR_KIT_NO_LLM=1`: it stops every pass that
646
+ calls a model (the judge, `adr-suggest` and `adr-substance`). For a whole
647
+ project, set `judge.llm_enabled`, `suggest.enabled` and `guardian.llm_enabled`
648
+ to `false` in `.adr-kit.json`; for your machine only, set them with
649
+ `adr-settings --set <switch>=false --local`. Enforcement is then fully deterministic and runs offline: the
650
+ declarative rules, `adr-lint`, readiness and the MCP tools never call a model.
651
+
652
+ **A local model.** Point the LLM passes at any command that reads the prompt
653
+ on stdin and writes the answer to stdout. A local runtime such as
654
+ [Ollama](https://ollama.com) works out of the box:
655
+
656
+ ```bash
657
+ export ADR_KIT_LLM_CMD="ollama run qwen3.5:4b --think=false"
658
+ ```
659
+
660
+ - **Scope.** The override applies to the judge, the missing-decision nudge
661
+ (`adr-suggest`) and the guardian's substance check (`adr-substance`). It
662
+ outranks the recorded host client. Use `--llm-cmd` instead for a single run.
663
+ - **Where it can be set.** Only per machine, as an environment variable or a
664
+ flag. `.adr-kit.json` is committed, so it can select a backend but never
665
+ introduce a command (ADR-025): `llm_cmd` and `llm_model` keys are refused.
666
+ - **Diagnostics.** `ADR_KIT_DEBUG=1` shows a failing command's stderr.
667
+
668
+ Expect a small local model to be slower and less consistent than your agent's
669
+ model. In a test on this repository, `qwen3.5:4b` gave a usable verdict for
670
+ 4 of 7 ADRs once thinking was disabled, and for 2 of 7 with it on. The other
671
+ verdicts degraded to the declarative result, as designed: an answer the judge
672
+ cannot parse costs you a check rather than blocking the commit. A clear but
673
+ wrong `VIOLATION` does block, so read a small model's findings critically, or
674
+ set `judge.advisory_only: true` while you evaluate one. A larger model, or
675
+ raising `judge.llm_timeout_seconds`, narrows the gap.
676
+
635
677
  State lives in `docs/adr/.adr-kit-state.json`: gitignored, per-machine, atomic writes, safe across parallel sessions.
636
678
 
637
679
  ## CI integration
@@ -645,7 +687,7 @@ directly after a full-history checkout:
645
687
  - uses: actions/checkout@v4
646
688
  with:
647
689
  fetch-depth: 0
648
- - uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@main
690
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@v0.60.0
649
691
  with:
650
692
  adr-dir: docs/adr
651
693
  ```
@@ -673,7 +715,7 @@ jobs:
673
715
  - uses: actions/checkout@v4
674
716
  with:
675
717
  fetch-depth: 0 # both sides of the diff must be available
676
- - uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.59.1
718
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.60.0
677
719
  with:
678
720
  adr-dir: docs/adr/
679
721
  ```
@@ -687,7 +729,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
687
729
  ```yaml
688
730
  repos:
689
731
  - repo: https://github.com/rvdbreemen/adr-kit
690
- rev: v0.59.1
732
+ rev: v0.60.0
691
733
  hooks:
692
734
  - id: adr-judge
693
735
  ```
@@ -771,7 +813,7 @@ the same notices; none of them applies a migration. See the
771
813
 
772
814
  **Does enforcement need an API key?**
773
815
 
774
- No. The default enforcement path (pre-commit hook, CI action, pre-commit framework, MCP server) is fully declarative and key-free. Only the explicitly opt-in LLM passes shell out to the `claude` CLI, and those degrade to a skip, never a block, when it is absent.
816
+ No. The default enforcement path (pre-commit hook, CI action, pre-commit framework, MCP server) is fully declarative and key-free. The LLM passes are on by default where a host client is recorded and shell out to that agent's own CLI (`claude -p`, `codex exec`, `copilot -p` or `opencode run --pure`, ADR-036), which carries its own authentication; they degrade to a skip, never a block, when it is absent. Switch them off with `ADR_KIT_NO_LLM=1` or `judge.llm_enabled: false`, or point them at a local model with `ADR_KIT_LLM_CMD` (see [LLM passes](#llm-passes-on-your-agents-model-by-default-local-by-choice)).
775
817
 
776
818
  **My team has parallel agents creating ADRs. What about number collisions?**
777
819
 
@@ -795,7 +837,7 @@ A plain ADR template gives you a markdown file with sections to fill in. What `a
795
837
  | Acceptance bar | "fill it in" | four named verification gates before Proposed flips to Accepted |
796
838
  | Finding the relevant decision | read the folder, or do not | query a generated index; ranked, explained, authority-aware shortlist |
797
839
  | While coding | absent | context injection per task plus in-flight file nudges |
798
- | Enforcement | absent | declarative rules vs every commit and PR, key-free; opt-in LLM judge |
840
+ | Enforcement | absent | declarative rules vs every commit and PR, key-free; LLM judge on your agent's own model, or a local one |
799
841
  | Aging | absent | guardian (drift, missing, stale), retirement audit, trend history, coverage KPI |
800
842
  | Team workflows | absent | CI sweeps with tracking issue, collision-safe numbering, audited overrides, guided supersession |
801
843
  | Tool integration | none | Claude Code, OpenAI Codex, GitHub Copilot CLI, and OpenCode integrations plus a 7-tool MCP server |
@@ -811,8 +853,8 @@ adr-kit/
811
853
  ├── agents/ # adr-generator subagent
812
854
  ├── hooks/ # hook config, shared fail-open runtime, per-client adapters
813
855
  ├── clients/ # canonical workflow/capability registry the client payloads generate from
814
- ├── codex/ # generated Codex plugin: 15 skills, hooks, MCP, packaged engines
815
- ├── copilot/ # generated Copilot CLI plugin: 15 skills, hooks, MCP, engines
856
+ ├── codex/ # generated Codex plugin: 17 skills, hooks, MCP, packaged engines
857
+ ├── copilot/ # generated Copilot CLI plugin: 17 skills, hooks, MCP, engines
816
858
  ├── opencode/ # native OpenCode TypeScript adapter over shared engines
817
859
  ├── package.json # npm-style OpenCode plugin metadata
818
860
  ├── opencode.json # repository-local OpenCode plugin registration
package/bin/adr-context CHANGED
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env python3
2
2
  """adr-context: find relevant ADRs for a given task query.
3
3
 
4
- Uses heuristic scoring with 5 weighted signals. Returns top N ranked ADRs.
4
+ Scores the generated index's weighted metadata fields (adr_query.FIELD_WEIGHTS).
5
+ Returns top N ranked ADRs.
5
6
 
6
7
  Usage:
7
8
  adr-context "cache invalidation strategy"
package/bin/adr-doctor CHANGED
@@ -120,7 +120,7 @@ def _parser() -> argparse.ArgumentParser:
120
120
  parser.add_argument("--format", choices=("text", "human", "json"), default="text")
121
121
  parser.add_argument("--check", action="store_true", help="Diagnose without repair.")
122
122
  parser.add_argument("--fix", action="store_true", help="Permit backed-up managed rewrites.")
123
- parser.add_argument("--deep", action="store_true", help="Run bounded native, MCP, and model probes.")
123
+ parser.add_argument("--deep", action="store_true", help="Run bounded native-registration, MCP and hook-latency probes.")
124
124
  parser.add_argument("--fix-index", action="store_true", help=argparse.SUPPRESS)
125
125
  return parser
126
126
 
package/bin/adr-guardian CHANGED
@@ -101,6 +101,7 @@ _load_sibling("adr_state")
101
101
  _load_sibling("adr_guardian_queue")
102
102
 
103
103
  from adr_config import load_json_config as _load_config
104
+ from adr_config import apply_machine_overrides as _apply_machine_overrides
104
105
  from adr_state import find_project_adr_dir as _find_adr_dir
105
106
  from adr_state import load_state, update_state
106
107
  from adr_guardian_queue import (
@@ -188,6 +189,7 @@ def _guardian_config(cfg: Dict) -> Dict:
188
189
  "llm_stale_days": 14,
189
190
  "nudge_cooldown_hours": 24,
190
191
  "llm_autorun": False,
192
+ "llm_enabled": True,
191
193
  }
192
194
  guardian = cfg.get("guardian") or {}
193
195
  merged = {**defaults, **guardian}
@@ -520,6 +522,10 @@ def _compute_due_tiers(
520
522
 
521
523
  cheap_due = cheap_days is None or cheap_days >= drift_stale_days
522
524
  llm_due = llm_days is None or llm_days >= llm_stale_days
525
+ if gcfg.get("llm_enabled") is False:
526
+ # Switched off for the project or this machine (TASK-233): the LLM tier
527
+ # is never due, so the nudge never asks for it.
528
+ return cheap_due, False
523
529
 
524
530
  # ADR-037: a recorded per-ADR violation keeps the llm tier due regardless
525
531
  # of how fresh the tier timestamp is. The tier goes quiet only when a
@@ -769,7 +775,10 @@ def cmd_check(args: argparse.Namespace) -> int:
769
775
  state_path = adr_dir / ".adr-kit-state.json"
770
776
  config_path = adr_dir / ".adr-kit.json"
771
777
 
772
- cfg = _load_config(config_path)
778
+ # This machine's LLM switches win over the team's (TASK-233).
779
+ cfg = _apply_machine_overrides(
780
+ _load_config(config_path), _load_config(adr_dir / ".adr-kit.local.json")
781
+ )
773
782
  gcfg = _guardian_config(cfg)
774
783
 
775
784
  # Respect guardian.enabled (default True).
package/bin/adr-judge CHANGED
@@ -2032,7 +2032,9 @@ def build_config_report(
2032
2032
  _entry(
2033
2033
  "judge.llm_enabled",
2034
2034
  bool(judge_cfg.get("llm_enabled", True)),
2035
- "project" if "llm_enabled" in judge_cfg else "default",
2035
+ "machine-local"
2036
+ if _adr_config.machine_override_source(local_cfg, "judge", "llm_enabled")
2037
+ else ("project" if "llm_enabled" in judge_cfg else "default"),
2036
2038
  ),
2037
2039
  _entry(
2038
2040
  "judge.backend",
@@ -2187,18 +2189,10 @@ def write_local_judge_value(adr_dir: Path, key: str, value: str) -> Path:
2187
2189
 
2188
2190
  The tracked config may select a backend; it may never introduce an endpoint
2189
2191
  or a credential, because anyone with commit access writes it. A host client
2190
- and a base URL are both facts about this machine.
2192
+ is a fact about this machine. The writer lives in adr_llm so the
2193
+ SessionStart hook writes the file the same way (ADR-049).
2191
2194
  """
2192
- path = adr_dir / LOCAL_CONFIG_NAME
2193
- document = _adr_config.load_json_config(path)
2194
- judge_block = document.get("judge")
2195
- if not isinstance(judge_block, dict):
2196
- judge_block = {}
2197
- judge_block[key] = value
2198
- document["judge"] = judge_block
2199
- _atomic_write_json(path, document)
2200
- _register_git_exclude(adr_dir, LOCAL_CONFIG_NAME)
2201
- return path
2195
+ return Path(_adr_llm.write_local_judge_value(adr_dir, key, value))
2202
2196
 
2203
2197
 
2204
2198
  def write_local_host_client(adr_dir: Path, client: str) -> Path:
@@ -2206,49 +2200,8 @@ def write_local_host_client(adr_dir: Path, client: str) -> Path:
2206
2200
  return write_local_judge_value(adr_dir, "host_client", client)
2207
2201
 
2208
2202
 
2209
- def _atomic_write_json(path: Path, document: Dict) -> None:
2210
- payload = json.dumps(document, indent=2, sort_keys=True) + "\n"
2211
- temporary = path.with_name(f".{path.name}.tmp")
2212
- path.parent.mkdir(parents=True, exist_ok=True)
2213
- with open(temporary, "w", encoding="utf-8", newline="\n") as out:
2214
- out.write(payload)
2215
- out.flush()
2216
- os.fsync(out.fileno())
2217
- os.replace(temporary, path)
2218
-
2219
-
2220
- def _register_git_exclude(adr_dir: Path, name: str) -> None:
2221
- """Best-effort .git/info/exclude entry, mirroring the override log.
2222
-
2223
- .gitignore is committed and belongs to the project; .git/info/exclude is
2224
- per-clone and belongs to this machine, which is the right scope for a file
2225
- that records one operator's client choice. Every failure is silent: a
2226
- missing exclude entry is untidy, not unsafe.
2227
- """
2228
- try:
2229
- result = subprocess.run(
2230
- ["git", "-C", str(adr_dir), "rev-parse", "--git-dir"],
2231
- capture_output=True, text=True, timeout=5,
2232
- )
2233
- if result.returncode != 0:
2234
- return
2235
- git_dir = Path(result.stdout.strip())
2236
- if not git_dir.is_absolute():
2237
- git_dir = (adr_dir / git_dir).resolve()
2238
- exclude = git_dir / "info" / "exclude"
2239
- entry = (adr_dir / name).resolve()
2240
- try:
2241
- relative = entry.relative_to(git_dir.parent.resolve()).as_posix()
2242
- except ValueError:
2243
- relative = name
2244
- existing = exclude.read_text(encoding="utf-8") if exclude.exists() else ""
2245
- if relative in existing.splitlines():
2246
- return
2247
- exclude.parent.mkdir(parents=True, exist_ok=True)
2248
- with open(exclude, "a", encoding="utf-8", newline="\n") as out:
2249
- out.write(("" if existing.endswith("\n") or not existing else "\n") + relative + "\n")
2250
- except (OSError, subprocess.SubprocessError, ValueError):
2251
- return
2203
+ _atomic_write_json = _adr_llm.atomic_write_json
2204
+ _register_git_exclude = _adr_llm.register_git_exclude
2252
2205
 
2253
2206
 
2254
2207
  SCOPE_CHECK_LIMITS = (
@@ -2592,7 +2545,10 @@ def main() -> int:
2592
2545
  adr_dir = Path(args.adr_dir).resolve()
2593
2546
  config_path = Path(args.config) if args.config else (adr_dir / ".adr-kit.json")
2594
2547
  cfg = load_config(config_path)
2595
- judge_cfg = cfg.get("judge") or {}
2548
+ local_cfg = load_local_config(adr_dir)
2549
+ # This machine's LLM switch wins over the team's (TASK-233, ADR-025):
2550
+ # an "off" answered at init or upgrade lives in the gitignored file.
2551
+ judge_cfg = _adr_config.apply_machine_overrides(cfg, local_cfg).get("judge") or {}
2596
2552
  skip_files = judge_cfg.get("skip_files") or []
2597
2553
  advisory_only = bool(judge_cfg.get("advisory_only", False))
2598
2554
  # Two workloads, two budgets. judge.max_diff_bytes is the commit-path
@@ -2631,7 +2587,6 @@ def main() -> int:
2631
2587
  or bool(judge_cfg.get("llm_enabled", True))
2632
2588
  ) and not env_no_llm
2633
2589
 
2634
- local_cfg = load_local_config(adr_dir)
2635
2590
  llm_backend, backend_warnings = resolve_llm_backend(
2636
2591
  judge_cfg, local_cfg, args.llm_cmd, dict(os.environ)
2637
2592
  )
package/bin/adr-settings CHANGED
@@ -44,6 +44,13 @@ LOCAL_CONFIG_NAME = ".adr-kit.local.json"
44
44
  # Settings that are personal or machine-specific. Everything else in the schema
45
45
  # is a team decision and belongs in the tracked file.
46
46
  LOCAL_KEYS: Dict[str, Dict[str, Any]] = {
47
+ "llm.confirmed": {
48
+ "type": "string",
49
+ "description": (
50
+ "The date this machine's user answered whether to keep the LLM layers "
51
+ "on (ADR-049). Until it is set, the session asks once a day."
52
+ ),
53
+ },
47
54
  "lifecycle.signer": {
48
55
  "type": "string",
49
56
  "description": (
@@ -53,7 +60,7 @@ LOCAL_KEYS: Dict[str, Dict[str, Any]] = {
53
60
  },
54
61
  "judge.host_client": {
55
62
  "type": "string",
56
- "enum": ["claude-code-cli", "codex-cli", "github-copilot-cli"],
63
+ "enum": ["claude-code-cli", "codex-cli", "github-copilot-cli", "opencode-cli"],
57
64
  "description": (
58
65
  "Which coding-client CLI answers the LLM pass. Machine-specific, and "
59
66
  "deliberately not probed from PATH: on a machine with all three "
@@ -80,6 +87,9 @@ SECRET_KEYS = {}
80
87
  # user actually turns.
81
88
  FEATURED = [
82
89
  "judge.llm_enabled",
90
+ "suggest.enabled",
91
+ "guardian.llm_enabled",
92
+ "guardian.llm_autorun",
83
93
  "judge.backend",
84
94
  "judge.max_diff_bytes",
85
95
  "judge.advisory_only",
@@ -314,7 +324,42 @@ def render_text(rows: List[Dict], adr_dir: Path) -> List[str]:
314
324
  return lines
315
325
 
316
326
 
317
- def apply_set(adr_dir: Path, schema: Dict, key: str, raw: str) -> List[str]:
327
+ def _load_sibling(name: str):
328
+ """Import bin/<name>.py by explicit path, without touching sys.path (TASK-62)."""
329
+ import importlib.machinery
330
+ import importlib.util
331
+
332
+ cached = sys.modules.get(name)
333
+ if cached is not None:
334
+ return cached
335
+ loader = importlib.machinery.SourceFileLoader(
336
+ name, str(Path(__file__).resolve().parent / f"{name}.py")
337
+ )
338
+ spec = importlib.util.spec_from_loader(name, loader)
339
+ module = importlib.util.module_from_spec(spec)
340
+ sys.modules[name] = module
341
+ loader.exec_module(module)
342
+ return module
343
+
344
+
345
+ def _machine_overridable(key: str) -> bool:
346
+ """The LLM switches one machine may set apart from the team (TASK-233)."""
347
+ return tuple(key.split(".", 1)) in _load_sibling("adr_config").MACHINE_OVERRIDABLE
348
+
349
+
350
+ def _target_name(key: str, local: bool) -> str:
351
+ if local and not is_local(key):
352
+ if not _machine_overridable(key):
353
+ raise SettingsError(
354
+ f"{key} is a team setting; --local accepts only the LLM switches "
355
+ "judge.llm_enabled, suggest.enabled, guardian.llm_enabled and "
356
+ "guardian.llm_autorun"
357
+ )
358
+ return LOCAL_CONFIG_NAME
359
+ return LOCAL_CONFIG_NAME if is_local(key) else PROJECT_CONFIG_NAME
360
+
361
+
362
+ def apply_set(adr_dir: Path, schema: Dict, key: str, raw: str, local: bool = False) -> List[str]:
318
363
  node = LOCAL_KEYS.get(key) or schema_node(schema, key)
319
364
  if node is None:
320
365
  raise SettingsError(
@@ -322,20 +367,20 @@ def apply_set(adr_dir: Path, schema: Dict, key: str, raw: str) -> List[str]:
322
367
  )
323
368
  value = coerce(raw, node)
324
369
  validate(key, value, node)
325
- target_name = LOCAL_CONFIG_NAME if is_local(key) else PROJECT_CONFIG_NAME
370
+ target_name = _target_name(key, local)
326
371
  path = adr_dir / target_name
327
372
  data = _read_json(path)
328
373
  _plant(data, key, value)
329
374
  _atomic_write(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
330
- scope = "machine-local, gitignored" if is_local(key) else "project, committed"
375
+ scope = "machine-local, gitignored" if target_name == LOCAL_CONFIG_NAME else "project, committed"
331
376
  return [f"{key} = {json.dumps(value)}", f"written to {path} ({scope})"]
332
377
 
333
378
 
334
- def apply_unset(adr_dir: Path, schema: Dict, key: str) -> List[str]:
379
+ def apply_unset(adr_dir: Path, schema: Dict, key: str, local: bool = False) -> List[str]:
335
380
  node = LOCAL_KEYS.get(key) or schema_node(schema, key)
336
381
  if node is None:
337
382
  raise SettingsError(f"unknown setting {key!r}")
338
- path = adr_dir / (LOCAL_CONFIG_NAME if is_local(key) else PROJECT_CONFIG_NAME)
383
+ path = adr_dir / _target_name(key, local)
339
384
  data = _read_json(path)
340
385
  if not _uproot(data, key):
341
386
  return [f"{key} was not set in {path}; nothing to do"]
@@ -354,6 +399,12 @@ def main(argv: Optional[List[str]] = None) -> int:
354
399
  parser.add_argument("--list", action="store_true", help="list every settable key and exit")
355
400
  parser.add_argument("--set", default=None, metavar="KEY=VALUE")
356
401
  parser.add_argument("--unset", default=None, metavar="KEY")
402
+ parser.add_argument(
403
+ "--local",
404
+ action="store_true",
405
+ help="with --set/--unset: write an LLM switch for this machine only, in the "
406
+ "gitignored .adr-kit.local.json, instead of for the whole team",
407
+ )
357
408
  args = parser.parse_args(argv)
358
409
 
359
410
  adr_dir = Path(args.adr_dir)
@@ -368,9 +419,9 @@ def main(argv: Optional[List[str]] = None) -> int:
368
419
  if "=" not in args.set:
369
420
  raise SettingsError("--set expects KEY=VALUE")
370
421
  key, raw = args.set.split("=", 1)
371
- lines = apply_set(adr_dir, schema, key.strip(), raw)
422
+ lines = apply_set(adr_dir, schema, key.strip(), raw, local=args.local)
372
423
  elif args.unset:
373
- lines = apply_unset(adr_dir, schema, args.unset.strip())
424
+ lines = apply_unset(adr_dir, schema, args.unset.strip(), local=args.local)
374
425
  else:
375
426
  keys = known_keys(schema) if args.all else FEATURED
376
427
  rows = describe(adr_dir, schema, keys, dict(os.environ))
package/bin/adr-substance CHANGED
@@ -250,6 +250,21 @@ def main(argv: Optional[List[str]] = None) -> int:
250
250
  )
251
251
  return 0
252
252
 
253
+ # The guardian's LLM tier can be switched off for the project or, from an
254
+ # init or upgrade answer, for this machine only (TASK-233).
255
+ cfg = _adr_config.apply_machine_overrides(cfg, local)
256
+ if (cfg.get("guardian") or {}).get("llm_enabled") is False:
257
+ message = "guardian.llm_enabled is false; no model is called"
258
+ if args.json:
259
+ json.dump(
260
+ {"checked": [], "findings": [], "unanswered": [p[0] for p in plan], "degraded": message},
261
+ sys.stdout, indent=2, ensure_ascii=False,
262
+ )
263
+ sys.stdout.write("\n")
264
+ else:
265
+ print(f"[adr-substance] skipped: {message}")
266
+ return 0
267
+
253
268
  judge_cfg = cfg.get("judge") or {}
254
269
  backend, warnings = _adr_llm.resolve_llm_backend(
255
270
  judge_cfg, local, args.llm_cmd, dict(os.environ)
package/bin/adr-suggest CHANGED
@@ -657,8 +657,9 @@ def main() -> int:
657
657
  "--llm-timeout",
658
658
  type=int,
659
659
  default=None,
660
- help="Per-call timeout for the LLM pass in seconds. Default 120 (or "
661
- "suggest.llm_timeout_seconds / judge.llm_timeout_seconds in .adr-kit.json).",
660
+ help="Per-call timeout for the LLM pass in seconds. Default: "
661
+ "suggest.llm_timeout_seconds, then judge.llm_timeout_seconds in .adr-kit.json, "
662
+ "then 30.",
662
663
  )
663
664
  p.add_argument(
664
665
  "--json",
@@ -676,7 +677,11 @@ def main() -> int:
676
677
  try:
677
678
  adr_dir = Path(args.adr_dir).resolve()
678
679
  config_path = Path(args.config) if args.config else (adr_dir / ".adr-kit.json")
679
- cfg = load_config(config_path)
680
+ # This machine's suggest.enabled wins over the team's (TASK-233): an
681
+ # "off" answered at init or upgrade lives in the gitignored file.
682
+ cfg = _adr_config.apply_machine_overrides(
683
+ load_config(config_path), load_local_config(adr_dir)
684
+ )
680
685
 
681
686
  # Default ON (ADR-035), on the same terms ADR-017 set for the judge:
682
687
  # one shared backend registry, the host CLI's own model, no pin. The
package/bin/adr_config.py CHANGED
@@ -278,3 +278,36 @@ def load_json_config(path: Path) -> Dict[str, Any]:
278
278
  except (OSError, json.JSONDecodeError):
279
279
  return {}
280
280
  return data if isinstance(data, dict) else {}
281
+
282
+
283
+ # The LLM switches a machine may override (TASK-233, ADR-049). An "off" answer
284
+ # at init or upgrade is one person's choice, so it lives in the gitignored
285
+ # .adr-kit.local.json and must not switch the layers off for the whole team
286
+ # (ADR-025). Only these booleans cross over: a machine file cannot retune
287
+ # budgets, scopes or anything else the team decided.
288
+ MACHINE_OVERRIDABLE = (
289
+ ("judge", "llm_enabled"),
290
+ ("suggest", "enabled"),
291
+ ("guardian", "llm_enabled"),
292
+ ("guardian", "llm_autorun"),
293
+ )
294
+
295
+
296
+ def apply_machine_overrides(cfg: Dict[str, Any], local: Dict[str, Any]) -> Dict[str, Any]:
297
+ """A copy of the project config with this machine's LLM switches applied."""
298
+ merged = {key: (dict(value) if isinstance(value, dict) else value) for key, value in (cfg or {}).items()}
299
+ for block, key in MACHINE_OVERRIDABLE:
300
+ local_block = (local or {}).get(block)
301
+ if not isinstance(local_block, dict) or not isinstance(local_block.get(key), bool):
302
+ continue
303
+ target = merged.get(block)
304
+ target = dict(target) if isinstance(target, dict) else {}
305
+ target[key] = local_block[key]
306
+ merged[block] = target
307
+ return merged
308
+
309
+
310
+ def machine_override_source(local: Dict[str, Any], block: str, key: str) -> bool:
311
+ """True when this machine's file sets one of the overridable switches."""
312
+ local_block = (local or {}).get(block)
313
+ return isinstance(local_block, dict) and isinstance(local_block.get(key), bool) and (block, key) in MACHINE_OVERRIDABLE