@rvdbreemen/adr-kit-opencode 0.59.1 → 0.61.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 +115 -39
- 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 +186 -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/omp/extension.ts +365 -0
- package/opencode/plugin.ts +95 -14
- package/package.json +7 -1
- package/schemas/adr-kit-config.schema.json +7 -2
- package/scripts/client_generation.py +2 -5
- package/scripts/client_generation_artifacts.py +16 -2
- package/scripts/client_generation_model.py +9 -0
- package/scripts/release_phases.py +7 -7
- package/skills/adr/SKILL.md +2 -0
- package/skills/audit/SKILL.md +2 -0
- package/skills/context/SKILL.md +2 -0
- package/skills/grill/SKILL.md +2 -0
- package/skills/guardian/SKILL.md +8 -4
- package/skills/init/SKILL.md +34 -11
- package/skills/install-hooks/SKILL.md +12 -9
- package/skills/judge/SKILL.md +8 -3
- package/skills/lint/SKILL.md +4 -1
- package/skills/migrate/SKILL.md +2 -0
- package/skills/related/SKILL.md +4 -1
- package/skills/retire/SKILL.md +2 -0
- package/skills/review/SKILL.md +4 -1
- package/skills/settings/SKILL.md +2 -0
- package/skills/setup/SKILL.md +4 -1
- package/skills/supersede/SKILL.md +4 -1
- package/skills/upgrade/SKILL.md +24 -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.61.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Robert van den Breemen",
|
|
7
7
|
"url": "https://github.com/rvdbreemen"
|
package/README.md
CHANGED
|
@@ -25,8 +25,8 @@ while the agent works, the governing decision is delivered *before* a file is
|
|
|
25
25
|
edited, every commit is checked against declarative rules with `file:line`
|
|
26
26
|
citations, and a guardian watches for decisions that have drifted out of date.
|
|
27
27
|
One toolkit covers the whole lifecycle (capture, enforce, maintain, retire)
|
|
28
|
-
across Claude Code, OpenAI Codex, the standalone GitHub Copilot CLI,
|
|
29
|
-
|
|
28
|
+
across Claude Code, OpenAI Codex, the standalone GitHub Copilot CLI, OpenCode,
|
|
29
|
+
and OMP (oh-my-pi); see [Supported clients](#supported-clients).
|
|
30
30
|
|
|
31
31
|
**For the agent, it removes the guessing.** Instead of reading every ADR, or
|
|
32
32
|
none, it queries a generated index and gets a ranked, explained shortlist for
|
|
@@ -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,12 @@ patch releases, is in [CHANGELOG.md](CHANGELOG.md).
|
|
|
100
102
|
|
|
101
103
|
| Version | What landed | Why it matters |
|
|
102
104
|
| --- | --- | --- |
|
|
105
|
+
| **0.61.0** | Native [OMP](docs/clients/omp.md) (oh-my-pi) support: `omp/extension.ts` maps OMP's session, prompt, edit, shell, subagent and compaction events onto the shared hook and records `omp-cli` as the judge host ([ADR-050](docs/adr/ADR-050-certify-omp-as-a-fourth-native-client-through-a-thin-extension.md), which accepts OMP as the fourth certified client; certification follows in 0.62.0). Skills and the ADR generator reply in the user's language. | OMP previously ran none of ADR Kit's hooks and broke ten skills on a missing plugin root; a plain `omp plugin install` now gets the full lifecycle. A [Supported clients](#supported-clients) table now says which clients are certified and which are not. |
|
|
106
|
+
| **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. |
|
|
107
|
+
| **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
108
|
| **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
109
|
| **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. |
|
|
110
|
+
| **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
111
|
| **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
112
|
| **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
113
|
| **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. |
|
|
@@ -132,18 +138,32 @@ ADRs are the established answer: short markdown files in your repo that record t
|
|
|
132
138
|
|
|
133
139
|
And because decisions age, a periodic guardian flags drift between code and decisions, retirement candidates, and decisions that were made but never recorded.
|
|
134
140
|
|
|
135
|
-
###
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
[docs/clients/
|
|
146
|
-
|
|
141
|
+
### Supported clients
|
|
142
|
+
|
|
143
|
+
All clients run the same deterministic Python engines, the same 17 workflows
|
|
144
|
+
and the same key-free seven-tool MCP server. They differ in how ADR Kit is
|
|
145
|
+
delivered and how much of it is certified:
|
|
146
|
+
|
|
147
|
+
| Client | Support level | Install | Lifecycle hooks | Details |
|
|
148
|
+
|---|---|---|---|---|
|
|
149
|
+
| Claude Code CLI | Certified | `install-agent-envs.py` or `/plugin install` | Session, prompt, edit, plan exit, shell, subagent, compaction | [docs/clients/claude.md](docs/clients/claude.md) |
|
|
150
|
+
| OpenAI Codex CLI | Certified | `install-agent-envs.py` or `codex plugin add` | Session, prompt, edit, shell, subagent, compaction | [docs/clients/codex.md](docs/clients/codex.md) |
|
|
151
|
+
| GitHub Copilot CLI (standalone) | Certified | `install-agent-envs.py` or `copilot plugin install` | Session, prompt, post-edit | [docs/clients/copilot.md](docs/clients/copilot.md) |
|
|
152
|
+
| OpenCode | Native package, not certified | `opencode.json` plugin entry | Prompt, edit, shell, compaction | [docs/clients/opencode.md](docs/clients/opencode.md) |
|
|
153
|
+
| OMP (oh-my-pi) | Native extension; certification in progress (v0.62.0) | `omp plugin install` from this marketplace | Session, prompt, edit, shell, subagent, compaction | [docs/clients/omp.md](docs/clients/omp.md) |
|
|
154
|
+
| Any other MCP or Agent Skills client | Portable fallback | Manual: MCP server, skills, project guidance | None | [INSTALL.md](INSTALL.md#portable-fallback) |
|
|
155
|
+
|
|
156
|
+
**Certified** means the client is in `clients/capabilities.json`, the
|
|
157
|
+
automatic installer and `adr-doctor` manage it, and the release gate checks it
|
|
158
|
+
against recorded native evidence; the generated
|
|
159
|
+
[client support matrix](docs/client-support.md) is that view (ADR-010,
|
|
160
|
+
ADR-048). **Native, not certified** means a thin adapter for the client's own
|
|
161
|
+
plugin API is shipped and tested with its own focused tests, but the client
|
|
162
|
+
is not in the installer, the doctor or the certification gate (ADR-039). OMP
|
|
163
|
+
is accepted as the fourth certified client (ADR-050) and ships natively now;
|
|
164
|
+
it is claimed as certified once its registry entry and native evidence land.
|
|
165
|
+
Every client, and a commit with no agent at all, gets the same pre-commit and
|
|
166
|
+
CI floor.
|
|
147
167
|
|
|
148
168
|
Lifecycle behavior is quiet-by-default: routine successful hooks print
|
|
149
169
|
nothing, relevant ADR context still reaches the agent, and actionable warnings
|
|
@@ -207,12 +227,11 @@ python scripts/setup-project.py --project-root /path/to/project
|
|
|
207
227
|
```
|
|
208
228
|
|
|
209
229
|
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.
|
|
230
|
+
pinned operation, per-client opt-outs, and doctor repair/check-only policy.
|
|
231
|
+
Which model judges is not a setting: the LLM passes use your coding agent's own
|
|
232
|
+
CLI, or a command you choose on your own machine (see
|
|
233
|
+
[LLM passes](#llm-passes-on-your-agents-model-by-default-local-by-choice)). No
|
|
234
|
+
model runs in a hook hot path.
|
|
216
235
|
|
|
217
236
|
### Claude Code
|
|
218
237
|
|
|
@@ -271,7 +290,7 @@ copilot mcp list
|
|
|
271
290
|
This targets `@github/copilot` invoked as `copilot`, not `gh copilot` or VS
|
|
272
291
|
Code agent mode. The separate `copilot/` distribution follows GitHub's
|
|
273
292
|
[Copilot plugin contract](https://docs.github.com/en/copilot/concepts/agents/about-plugins)
|
|
274
|
-
and installs
|
|
293
|
+
and installs 17 skills plus the same key-free MCP server.
|
|
275
294
|
Open `/skills` inside Copilot CLI to discover ADR Kit workflows. Its lower-camel
|
|
276
295
|
hook package supplies proactive session/task context and PostToolUse; pre-commit
|
|
277
296
|
remains the edit-enforcement backstop.
|
|
@@ -292,7 +311,7 @@ project. Start a new Copilot session or run `/mcp reload` in the current one.
|
|
|
292
311
|
Agents should use these native update commands instead of editing the installed
|
|
293
312
|
`.mcp.json` or replacing `${PLUGIN_ROOT}` with a machine-specific path.
|
|
294
313
|
|
|
295
|
-
### OpenCode
|
|
314
|
+
### OpenCode (native, not certified)
|
|
296
315
|
|
|
297
316
|
OpenCode is supported through a separate native plugin package. It uses the
|
|
298
317
|
same deterministic Python engines and seven-tool MCP server as the certified
|
|
@@ -314,7 +333,7 @@ For another project, use the published package:
|
|
|
314
333
|
```json
|
|
315
334
|
{
|
|
316
335
|
"$schema": "https://opencode.ai/config.json",
|
|
317
|
-
"plugin": ["@rvdbreemen/adr-kit-opencode@0.
|
|
336
|
+
"plugin": ["@rvdbreemen/adr-kit-opencode@0.61.0"]
|
|
318
337
|
}
|
|
319
338
|
```
|
|
320
339
|
|
|
@@ -346,6 +365,25 @@ three-client support matrix, and the three-client native certification gate.
|
|
|
346
365
|
See [OpenCode support](docs/clients/opencode.md) for options, manual MCP
|
|
347
366
|
registration, and the tested support boundary.
|
|
348
367
|
|
|
368
|
+
### OMP (native; certification in progress)
|
|
369
|
+
|
|
370
|
+
OMP installs ADR Kit from the same marketplace as Claude Code:
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
omp plugin marketplace add rvdbreemen/adr-kit
|
|
374
|
+
omp plugin install adr-kit@rvdbreemen-adr-kit
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Start a new session, then run `/skill:init` once per project. OMP reads the
|
|
378
|
+
skills, the `adr-generator` agent and the MCP server from the plugin, and loads
|
|
379
|
+
a thin extension (`omp/extension.ts`) that maps OMP's session, prompt, tool,
|
|
380
|
+
subagent and compaction events onto `hooks/adr-hook.py`, exports
|
|
381
|
+
`ADR_KIT_ROOT` for the skills, and records `omp-cli` as the judge host.
|
|
382
|
+
Workflows are skills, invoked as `/skill:<name>`. ADR-050 makes OMP the fourth
|
|
383
|
+
certified client; until its registry entry and native evidence land in
|
|
384
|
+
v0.62.0, the installer and `adr-doctor` do not manage it yet. See
|
|
385
|
+
[OMP support](docs/clients/omp.md).
|
|
386
|
+
|
|
349
387
|
### Portable Agent Skills and MCP clients
|
|
350
388
|
|
|
351
389
|
[INSTALL.md](INSTALL.md) documents the native plugin layouts and portable
|
|
@@ -416,7 +454,7 @@ Three layers, each with a clear path:
|
|
|
416
454
|
|
|
417
455
|
### Maintain the decision log (decisions age; the kit notices)
|
|
418
456
|
|
|
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
|
|
457
|
+
- **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
458
|
- **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
459
|
- **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
460
|
- **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 +462,7 @@ Three layers, each with a clear path:
|
|
|
424
462
|
- **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
463
|
- **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
464
|
- **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
|
|
465
|
+
- **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
466
|
- **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
467
|
- **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
468
|
- **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 +648,12 @@ All configuration lives in one optional file: `docs/adr/.adr-kit.json` (annotate
|
|
|
610
648
|
role parsing.
|
|
611
649
|
- Per-file markers for one-off grandfathering: `<!-- adr-kit-lint: skip -->`, `skip <gate>[, ...]`, or `advisory` anywhere in an ADR.
|
|
612
650
|
|
|
613
|
-
### LLM passes:
|
|
651
|
+
### LLM passes: on your agent's model by default, local by choice
|
|
614
652
|
|
|
615
653
|
```json
|
|
616
654
|
{
|
|
617
|
-
"judge": { "llm_enabled":
|
|
618
|
-
"suggest": { "enabled":
|
|
655
|
+
"judge": { "llm_enabled": true, "llm_timeout_seconds": 120, "llm_pass_timeout_seconds": 600 },
|
|
656
|
+
"suggest": { "enabled": true },
|
|
619
657
|
"guardian": {
|
|
620
658
|
"enabled": true,
|
|
621
659
|
"drift_stale_days": 1,
|
|
@@ -627,11 +665,49 @@ All configuration lives in one optional file: `docs/adr/.adr-kit.json` (annotate
|
|
|
627
665
|
}
|
|
628
666
|
```
|
|
629
667
|
|
|
630
|
-
- The pre-commit hook's declarative pass is always on and free.
|
|
668
|
+
- The pre-commit hook's declarative pass is always on and free.
|
|
669
|
+
- 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.
|
|
670
|
+
- 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
671
|
- `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).
|
|
672
|
+
- 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
673
|
- `watch` tunes the in-flight nudges; `cooldown_hours: 0` disables the cooldown, `enabled: false` silences the watcher.
|
|
634
674
|
|
|
675
|
+
#### Working locally (opt-in)
|
|
676
|
+
|
|
677
|
+
You can keep every diff on your own machine. There are two ways to do that.
|
|
678
|
+
|
|
679
|
+
**No model at all.** Export `ADR_KIT_NO_LLM=1`: it stops every pass that
|
|
680
|
+
calls a model (the judge, `adr-suggest` and `adr-substance`). For a whole
|
|
681
|
+
project, set `judge.llm_enabled`, `suggest.enabled` and `guardian.llm_enabled`
|
|
682
|
+
to `false` in `.adr-kit.json`; for your machine only, set them with
|
|
683
|
+
`adr-settings --set <switch>=false --local`. Enforcement is then fully deterministic and runs offline: the
|
|
684
|
+
declarative rules, `adr-lint`, readiness and the MCP tools never call a model.
|
|
685
|
+
|
|
686
|
+
**A local model.** Point the LLM passes at any command that reads the prompt
|
|
687
|
+
on stdin and writes the answer to stdout. A local runtime such as
|
|
688
|
+
[Ollama](https://ollama.com) works out of the box:
|
|
689
|
+
|
|
690
|
+
```bash
|
|
691
|
+
export ADR_KIT_LLM_CMD="ollama run qwen3.5:4b --think=false"
|
|
692
|
+
```
|
|
693
|
+
|
|
694
|
+
- **Scope.** The override applies to the judge, the missing-decision nudge
|
|
695
|
+
(`adr-suggest`) and the guardian's substance check (`adr-substance`). It
|
|
696
|
+
outranks the recorded host client. Use `--llm-cmd` instead for a single run.
|
|
697
|
+
- **Where it can be set.** Only per machine, as an environment variable or a
|
|
698
|
+
flag. `.adr-kit.json` is committed, so it can select a backend but never
|
|
699
|
+
introduce a command (ADR-025): `llm_cmd` and `llm_model` keys are refused.
|
|
700
|
+
- **Diagnostics.** `ADR_KIT_DEBUG=1` shows a failing command's stderr.
|
|
701
|
+
|
|
702
|
+
Expect a small local model to be slower and less consistent than your agent's
|
|
703
|
+
model. In a test on this repository, `qwen3.5:4b` gave a usable verdict for
|
|
704
|
+
4 of 7 ADRs once thinking was disabled, and for 2 of 7 with it on. The other
|
|
705
|
+
verdicts degraded to the declarative result, as designed: an answer the judge
|
|
706
|
+
cannot parse costs you a check rather than blocking the commit. A clear but
|
|
707
|
+
wrong `VIOLATION` does block, so read a small model's findings critically, or
|
|
708
|
+
set `judge.advisory_only: true` while you evaluate one. A larger model, or
|
|
709
|
+
raising `judge.llm_timeout_seconds`, narrows the gap.
|
|
710
|
+
|
|
635
711
|
State lives in `docs/adr/.adr-kit-state.json`: gitignored, per-machine, atomic writes, safe across parallel sessions.
|
|
636
712
|
|
|
637
713
|
## CI integration
|
|
@@ -645,7 +721,7 @@ directly after a full-history checkout:
|
|
|
645
721
|
- uses: actions/checkout@v4
|
|
646
722
|
with:
|
|
647
723
|
fetch-depth: 0
|
|
648
|
-
- uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@
|
|
724
|
+
- uses: rvdbreemen/adr-kit/.github/actions/adr-readiness@v0.61.0
|
|
649
725
|
with:
|
|
650
726
|
adr-dir: docs/adr
|
|
651
727
|
```
|
|
@@ -673,7 +749,7 @@ jobs:
|
|
|
673
749
|
- uses: actions/checkout@v4
|
|
674
750
|
with:
|
|
675
751
|
fetch-depth: 0 # both sides of the diff must be available
|
|
676
|
-
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.
|
|
752
|
+
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.61.0
|
|
677
753
|
with:
|
|
678
754
|
adr-dir: docs/adr/
|
|
679
755
|
```
|
|
@@ -687,7 +763,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
|
|
|
687
763
|
```yaml
|
|
688
764
|
repos:
|
|
689
765
|
- repo: https://github.com/rvdbreemen/adr-kit
|
|
690
|
-
rev: v0.
|
|
766
|
+
rev: v0.61.0
|
|
691
767
|
hooks:
|
|
692
768
|
- id: adr-judge
|
|
693
769
|
```
|
|
@@ -771,7 +847,7 @@ the same notices; none of them applies a migration. See the
|
|
|
771
847
|
|
|
772
848
|
**Does enforcement need an API key?**
|
|
773
849
|
|
|
774
|
-
No. The default enforcement path (pre-commit hook, CI action, pre-commit framework, MCP server) is fully declarative and key-free.
|
|
850
|
+
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
851
|
|
|
776
852
|
**My team has parallel agents creating ADRs. What about number collisions?**
|
|
777
853
|
|
|
@@ -795,7 +871,7 @@ A plain ADR template gives you a markdown file with sections to fill in. What `a
|
|
|
795
871
|
| Acceptance bar | "fill it in" | four named verification gates before Proposed flips to Accepted |
|
|
796
872
|
| Finding the relevant decision | read the folder, or do not | query a generated index; ranked, explained, authority-aware shortlist |
|
|
797
873
|
| While coding | absent | context injection per task plus in-flight file nudges |
|
|
798
|
-
| Enforcement | absent | declarative rules vs every commit and PR, key-free;
|
|
874
|
+
| Enforcement | absent | declarative rules vs every commit and PR, key-free; LLM judge on your agent's own model, or a local one |
|
|
799
875
|
| Aging | absent | guardian (drift, missing, stale), retirement audit, trend history, coverage KPI |
|
|
800
876
|
| Team workflows | absent | CI sweeps with tracking issue, collision-safe numbering, audited overrides, guided supersession |
|
|
801
877
|
| Tool integration | none | Claude Code, OpenAI Codex, GitHub Copilot CLI, and OpenCode integrations plus a 7-tool MCP server |
|
|
@@ -811,8 +887,8 @@ adr-kit/
|
|
|
811
887
|
├── agents/ # adr-generator subagent
|
|
812
888
|
├── hooks/ # hook config, shared fail-open runtime, per-client adapters
|
|
813
889
|
├── clients/ # canonical workflow/capability registry the client payloads generate from
|
|
814
|
-
├── codex/ # generated Codex plugin:
|
|
815
|
-
├── copilot/ # generated Copilot CLI plugin:
|
|
890
|
+
├── codex/ # generated Codex plugin: 17 skills, hooks, MCP, packaged engines
|
|
891
|
+
├── copilot/ # generated Copilot CLI plugin: 17 skills, hooks, MCP, engines
|
|
816
892
|
├── opencode/ # native OpenCode TypeScript adapter over shared engines
|
|
817
893
|
├── package.json # npm-style OpenCode plugin metadata
|
|
818
894
|
├── 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", "omp-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)
|