@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.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +66 -24
- package/bin/adr-context +2 -1
- package/bin/adr-doctor +1 -1
- package/bin/adr-guardian +10 -1
- package/bin/adr-judge +12 -57
- package/bin/adr-settings +59 -8
- package/bin/adr-substance +15 -0
- package/bin/adr-suggest +8 -3
- package/bin/adr_config.py +33 -0
- package/bin/adr_doctor_checks.py +9 -3
- package/bin/adr_doctor_core.py +4 -4
- package/bin/adr_doctor_probes.py +100 -13
- package/bin/adr_llm.py +178 -3
- package/bin/adr_readiness.py +17 -1
- package/clients/workflows.json +10 -7
- package/hooks/adr_hook_core.py +176 -28
- package/instructions/ADR-guide.md +1 -1
- package/opencode/plugin.ts +52 -10
- package/package.json +1 -1
- package/schemas/adr-kit-config.schema.json +7 -2
- package/scripts/client_generation.py +2 -5
- package/scripts/client_generation_artifacts.py +13 -2
- package/scripts/client_generation_model.py +4 -0
- package/scripts/release_phases.py +7 -7
- package/skills/guardian/SKILL.md +6 -4
- package/skills/init/SKILL.md +32 -11
- package/skills/install-hooks/SKILL.md +10 -9
- package/skills/judge/SKILL.md +6 -3
- package/skills/lint/SKILL.md +2 -1
- package/skills/related/SKILL.md +2 -1
- package/skills/review/SKILL.md +2 -1
- package/skills/setup/SKILL.md +2 -1
- package/skills/supersede/SKILL.md +2 -1
- package/skills/upgrade/SKILL.md +22 -3
- package/templates/adr-kit-guide.md +3 -3
- package/templates/cc-settings/guardian-hook-entry.json +2 -2
- package/templates/githooks/pre-commit +37 -9
- package/templates/github-workflows/adr-index-check.yml +1 -1
- package/templates/github-workflows/adr-judge.yml +1 -1
- 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.
|
|
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
|
|
48
|
-
|
|
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
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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:
|
|
617
|
+
### LLM passes: on your agent's model by default, local by choice
|
|
614
618
|
|
|
615
619
|
```json
|
|
616
620
|
{
|
|
617
|
-
"judge": { "llm_enabled":
|
|
618
|
-
"suggest": { "enabled":
|
|
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.
|
|
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@
|
|
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.
|
|
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.
|
|
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.
|
|
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;
|
|
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:
|
|
815
|
-
├── copilot/ # generated Copilot CLI plugin:
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2210
|
-
|
|
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
|
-
|
|
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
|
|
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 =
|
|
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
|
|
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 / (
|
|
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
|
|
661
|
-
"suggest.llm_timeout_seconds
|
|
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
|
-
|
|
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
|