@rvdbreemen/adr-kit-opencode 0.52.2 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.52.2",
4
+ "version": "0.53.0",
5
5
  "author": {
6
6
  "name": "Robert van den Breemen",
7
7
  "url": "https://github.com/rvdbreemen"
package/README.md CHANGED
@@ -307,12 +307,12 @@ configured:
307
307
  }
308
308
  ```
309
309
 
310
- For another project, use the published package for v0.52.2:
310
+ For another project, use the published package for v0.52.0:
311
311
 
312
312
  ```json
313
313
  {
314
314
  "$schema": "https://opencode.ai/config.json",
315
- "plugin": ["@rvdbreemen/adr-kit-opencode@0.52.2"]
315
+ "plugin": ["@rvdbreemen/adr-kit-opencode@0.52.0"]
316
316
  }
317
317
  ```
318
318
 
@@ -434,7 +434,7 @@ Three layers, each with a clear path:
434
434
  A deliberately thin MCP server (stdio, newline-delimited JSON-RPC 2.0, Python
435
435
  stdlib only, zero dependencies) that exposes the guardrails to Claude Code,
436
436
  OpenAI Codex, GitHub Copilot CLI, or another compatible local stdio MCP
437
- client. Five tools, all key-free:
437
+ client. Seven tools, all key-free:
438
438
 
439
439
  | Tool | Arguments | Wraps |
440
440
  | --- | --- | --- |
@@ -443,6 +443,8 @@ client. Five tools, all key-free:
443
443
  | `adr_status` | none | `adr-status --format json` |
444
444
  | `adr_quality` | `adr_id?` (string) | `adr-quality --format json` per ADR |
445
445
  | `adr_readiness` | `adr_id?`, `all_proposed?`, `changed_paths?`, `source_text?`, `today?` | shared read-only readiness model |
446
+ | `adr_lint` | `strict?` (boolean) | `adr-lint --format json` |
447
+ | `adr_related` | `adr_id` (string) | `adr-related --format json` |
446
448
 
447
449
  ```bash
448
450
  # Claude Code
@@ -462,10 +464,12 @@ For another stdio client, place the following in its MCP configuration:
462
464
  }
463
465
  ```
464
466
 
465
- Why only five tools? Contrast is the feature: adr-kit ships the smallest
467
+ Why only seven tools? Contrast is the feature: adr-kit ships the smallest
466
468
  surface that carries the guardrails and readiness facts, and nothing that needs
467
- an API key. Grilling itself stays in the client session so an engineer or
468
- architect remains part of the decision.
469
+ an API key. ADR-040 records the admission criterion — read-only, deterministic
470
+ and key-free, agent-query-shaped, and covering a development-cycle step no
471
+ exposed tool already covers. Grilling itself stays in the client session so an
472
+ engineer or architect remains part of the decision.
469
473
 
470
474
  ## Slash commands
471
475
 
@@ -665,7 +669,7 @@ jobs:
665
669
  - uses: actions/checkout@v4
666
670
  with:
667
671
  fetch-depth: 0 # both sides of the diff must be available
668
- - uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.52.2
672
+ - uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.53.0
669
673
  with:
670
674
  adr-dir: docs/adr/
671
675
  ```
@@ -679,7 +683,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
679
683
  ```yaml
680
684
  repos:
681
685
  - repo: https://github.com/rvdbreemen/adr-kit
682
- rev: v0.52.2
686
+ rev: v0.53.0
683
687
  hooks:
684
688
  - id: adr-judge
685
689
  ```
package/bin/adr-mcp CHANGED
@@ -26,7 +26,7 @@ the same answer. That is deliberate - the spec forbids relying on prior
26
26
  requests over the same connection to establish context. See ADR-016 and
27
27
  docs/research/2026-07-29-mcp-2026-07-28-revision.md.
28
28
 
29
- Exposes exactly 5 tools, each a subprocess call into a sibling bin/ script:
29
+ Exposes exactly 7 tools, each a subprocess call into a sibling bin/ script:
30
30
 
31
31
  adr_context {query, limit?, paths?, components?, symbols?, topics?,
32
32
  statuses?, authorities?, include_history?, strict_index?}
@@ -37,6 +37,12 @@ Exposes exactly 5 tools, each a subprocess call into a sibling bin/ script:
37
37
  adr_quality {adr_id?} -> bin/adr-quality --format json per ADR
38
38
  adr_readiness {adr_id?, all_proposed?, base?, head?, today?}
39
39
  -> bin/adr-readiness --format json
40
+ adr_lint {strict?} -> bin/adr-lint --format json
41
+ adr_related {adr_id} -> bin/adr-related --format json
42
+
43
+ Admission is governed by ADR-040: a CLI joins this surface only when it is
44
+ read-only, deterministic and key-free, agent-query-shaped, and covers an
45
+ agent-guide cycle step no exposed tool already covers.
40
46
 
41
47
  adr-suggest is intentionally NOT exposed: it is an LLM-only advisory (its
42
48
  deterministic part is just a docs-only skip filter), and this server stays
@@ -112,9 +118,10 @@ MODERN_CACHE_SCOPE = "public"
112
118
 
113
119
  MODERN_INSTRUCTIONS = (
114
120
  "adr-kit: read-only Architecture Decision Record tooling. Call tools/list "
115
- "for the five deterministic, key-free tools (adr_context, adr_judge, "
116
- "adr_status, adr_quality, adr_readiness). Every tool accepts optional "
117
- "project_root and adr_dir arguments to select the active workspace."
121
+ "for the seven deterministic, key-free tools (adr_context, adr_judge, "
122
+ "adr_status, adr_quality, adr_readiness, adr_lint, adr_related). Every "
123
+ "tool accepts optional project_root and adr_dir arguments to select the "
124
+ "active workspace."
118
125
  )
119
126
 
120
127
  # Per-tool subprocess timeout. The wrapped CLIs are regex-only and fast;
@@ -331,6 +338,46 @@ TOOL_DEFINITIONS: List[Dict[str, Any]] = [
331
338
  },
332
339
  },
333
340
  },
341
+ {
342
+ "name": "adr_lint",
343
+ "description": (
344
+ "Lint the ADR set against the deterministic verification gates. "
345
+ "Read-only, key-free. Returns the adr-lint JSON report and exit "
346
+ "status (0 = clean, 1 = failing findings)."
347
+ ),
348
+ "inputSchema": {
349
+ "type": "object",
350
+ "properties": {
351
+ "strict": {
352
+ "type": "boolean",
353
+ "description": (
354
+ "CI governance mode: enable the schema gate and make "
355
+ "findings FAIL. False by default."
356
+ ),
357
+ },
358
+ **WORKSPACE_PROPERTIES,
359
+ },
360
+ },
361
+ },
362
+ {
363
+ "name": "adr_related",
364
+ "description": (
365
+ "Show the dependency graph (inbound + outbound edges) for one "
366
+ "ADR: related decisions, supersession links, mentions, and "
367
+ "dangling references. Read-only, deterministic. Returns JSON."
368
+ ),
369
+ "inputSchema": {
370
+ "type": "object",
371
+ "properties": {
372
+ "adr_id": {
373
+ "type": "string",
374
+ "description": "ADR identifier such as 'ADR-007', 'adr-7' or '7'.",
375
+ },
376
+ **WORKSPACE_PROPERTIES,
377
+ },
378
+ "required": ["adr_id"],
379
+ },
380
+ },
334
381
  ]
335
382
 
336
383
 
@@ -678,12 +725,57 @@ def tool_adr_readiness(
678
725
  return _text_result(_parse_json_or_raw(out))
679
726
 
680
727
 
728
+ def tool_adr_lint(arguments: Dict[str, Any], root: Path, adr_dir: Path) -> Dict[str, Any]:
729
+ try:
730
+ root, adr_dir = _call_paths(arguments, root, adr_dir)
731
+ except ValueError as exc:
732
+ return _text_result(f"adr_lint: {exc}", is_error=True)
733
+ strict = arguments.get("strict", False)
734
+ if not isinstance(strict, bool):
735
+ return _text_result("adr_lint: 'strict' must be a boolean", is_error=True)
736
+ args = ["--format", "json", "--repo-root", str(root)]
737
+ if strict:
738
+ args.append("--strict")
739
+ args.append(str(adr_dir))
740
+ rc, out, err = run_cli("adr-lint", args, root)
741
+ if rc == 2:
742
+ return _text_result(
743
+ f"adr-lint exited 2 (config/input error): {err.strip() or out.strip()}",
744
+ is_error=True,
745
+ )
746
+ # rc 0 (clean) and rc 1 (failing findings) are both valid lint outcomes.
747
+ payload = {"exit_code": rc, "verdict": "findings" if rc == 1 else "ok",
748
+ "result": _parse_json_or_raw(out)}
749
+ return _text_result(payload)
750
+
751
+
752
+ def tool_adr_related(arguments: Dict[str, Any], root: Path, adr_dir: Path) -> Dict[str, Any]:
753
+ try:
754
+ root, adr_dir = _call_paths(arguments, root, adr_dir)
755
+ except ValueError as exc:
756
+ return _text_result(f"adr_related: {exc}", is_error=True)
757
+ adr_id = arguments.get("adr_id")
758
+ if not isinstance(adr_id, str) or not adr_id.strip():
759
+ return _text_result(
760
+ "adr_related: 'adr_id' must be a non-empty string", is_error=True
761
+ )
762
+ args = ["--format", "json", "--adr-dir", str(adr_dir), adr_id]
763
+ rc, out, err = run_cli("adr-related", args, root)
764
+ if rc != 0:
765
+ return _text_result(
766
+ f"adr-related exited {rc}: {err.strip() or out.strip()}", is_error=True
767
+ )
768
+ return _text_result(_parse_json_or_raw(out))
769
+
770
+
681
771
  TOOL_HANDLERS = {
682
772
  "adr_context": tool_adr_context,
683
773
  "adr_judge": tool_adr_judge,
684
774
  "adr_status": tool_adr_status,
685
775
  "adr_quality": tool_adr_quality,
686
776
  "adr_readiness": tool_adr_readiness,
777
+ "adr_lint": tool_adr_lint,
778
+ "adr_related": tool_adr_related,
687
779
  }
688
780
 
689
781
 
@@ -110,6 +110,8 @@ def _mcp_deep(root: Path, plugin_root: Path) -> dict:
110
110
  "adr_status",
111
111
  "adr_quality",
112
112
  "adr_readiness",
113
+ "adr_lint",
114
+ "adr_related",
113
115
  } == tools
114
116
  and called
115
117
  )
@@ -4,31 +4,84 @@
4
4
  # ADR Kit agent guide
5
5
 
6
6
  Architecture decisions live in `docs/adr/`. Read the source ADR before treating
7
- a generated summary as binding.
7
+ a generated summary as binding. This guide is written so an agent can operate
8
+ adr-kit autonomously: every step names the tool to call, what comes back, and
9
+ how to react. Steps marked **human-gated** must never be performed without an
10
+ explicit human decision.
11
+
12
+ ## Tool surface
13
+
14
+ Every step below is callable two ways. Shell-less clients use the MCP tools;
15
+ clients with a shell may use the CLI directly. Both delegate to the same
16
+ deterministic engines, so results are identical.
17
+
18
+ | Phase | MCP tool | CLI equivalent | Mutates? |
19
+ | --- | --- | --- | --- |
20
+ | Find governing ADRs | `adr_context` | `bin/adr-context --format json` | no |
21
+ | Follow ADR graph links | `adr_related` | `bin/adr-related --format json` | no |
22
+ | Judge a diff | `adr_judge` | `bin/adr-judge --json` | no |
23
+ | Lint the ADR set | `adr_lint` | `bin/adr-lint --format json` | no |
24
+ | Score ADR quality | `adr_quality` | `bin/adr-quality --format json` | no |
25
+ | Check lifecycle readiness | `adr_readiness` | `bin/adr-readiness --format json` | no |
26
+ | Repository health | `adr_status` | `bin/adr-status --format json` | no |
27
+ | Create / edit / accept ADRs | — (deliberately absent) | `bin/adr new`, `answer`, `relate`, ... | yes |
28
+
29
+ The MCP server is read-only by design (ADR-011, ADR-040): no MCP tool can
30
+ create, edit, accept, or index an ADR. Lifecycle mutation always goes through
31
+ the CLI, and acceptance always goes through a human.
8
32
 
9
33
  ## Before implementation
10
34
 
11
- 1. Query the task with `adr-kit:context` or `bin/adr-context`.
12
- 2. Read the returned Accepted ADRs.
13
- 3. If the work introduces or changes a long-lived decision, use `adr-kit:adr`
14
- and keep the new record Proposed until a human accepts it.
35
+ 1. Query the task with `adr_context` (MCP) or `bin/adr-context`. Pass the task
36
+ description as `query`; add `paths` for the files you expect to touch.
37
+ 2. Read every returned Accepted ADR at the source, and call `adr_related` on
38
+ each id you rely on to see supersession, related decisions, and dangling
39
+ links. A superseded ADR is history, not guidance: follow the successor.
40
+ 3. If the work introduces or changes a long-lived decision, create a Proposed
41
+ record with `bin/adr new` (or `adr-kit:adr`) before writing the code.
42
+ **Human-gated:** the record stays Proposed until a human accepts it; never
43
+ run `bin/adr accept` on your own initiative.
15
44
 
16
45
  ## During implementation
17
46
 
18
47
  - Treat hook-provided ADR context as advisory steering. Hooks fail open.
19
48
  - Treat deterministic pre-commit enforcement as the blocking floor.
20
49
  - Never rewrite an Accepted ADR. Create a Proposed successor and use the
21
- supersession lifecycle.
50
+ supersession lifecycle (`bin/adr supersede`, human-gated like acceptance).
22
51
  - Keep generated indexes and client artifacts deterministic; edit their
23
52
  canonical sources instead.
24
53
 
25
54
  ## Before completion
26
55
 
27
- 1. Run strict ADR lint and the relevant focused tests.
28
- 2. Regenerate `docs/adr/ADR-INDEX.md`, `docs/adr/ADR-INDEX.json`, and the
29
- generated README block after ADR changes.
30
- 3. Use `adr-kit:judge` or `bin/adr-judge` to check the staged diff.
31
- 4. Record the decision, evidence, and verification in the project task.
56
+ 1. Run `adr_lint` with `strict: true` (MCP) or `bin/adr-lint --strict`.
57
+ React: `verdict: ok` proceeds; `verdict: findings` lists failing files and
58
+ findings — fix the ADR content, never weaken the gate. Exit 2 is a config
59
+ error: report it, do not work around it.
60
+ 2. After ADR changes, regenerate `docs/adr/ADR-INDEX.md`,
61
+ `docs/adr/ADR-INDEX.json`, and the generated README block with
62
+ `bin/adr-index docs/adr` (CLI only; index generation mutates).
63
+ 3. Judge the staged diff with `adr_judge` (MCP, pass the unified diff) or
64
+ `bin/adr-judge`. React: `verdict: ok` proceeds; `verdict: violation` names
65
+ the ADR and rule per finding — change the code to comply, or propose a
66
+ successor ADR if the decision itself is wrong. Never commit past a
67
+ violation.
68
+ 4. For a Proposed ADR, check `adr_readiness`. React: `classification` tells
69
+ you what is missing (open questions, implementation links, quality). Fix
70
+ what is mechanical; leave acceptance to a human.
71
+ 5. Record the decision, evidence, and verification in the project task.
72
+
73
+ ## Human-gated actions
74
+
75
+ These require an explicit human decision, every time:
76
+
77
+ - `bin/adr accept` (and `--confirm`): acceptance writes a person's name into
78
+ an immutable status history (ADR-011, ADR-027).
79
+ - `bin/adr supersede`, `bin/adr reject`: same lifecycle authority.
80
+ - Choosing or changing the lifecycle signer (`bin/adr signer --set`).
81
+
82
+ Everything else in the tables above is safe for autonomous use: the read-only
83
+ tools always, and the mutating authoring commands (`new`, `answer`, `relate`,
84
+ `adr-index`) when the task itself calls for them.
32
85
 
33
86
  ## Ownership
34
87
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rvdbreemen/adr-kit-opencode",
3
- "version": "0.52.2",
3
+ "version": "0.53.0",
4
4
  "description": "Native OpenCode plugin for ADR Kit, backed by the shared deterministic Python engines.",
5
5
  "type": "module",
6
6
  "main": "./opencode/plugin.ts",
@@ -1,4 +1,4 @@
1
- <!-- adr-kit-guide v0.52.2 -->
1
+ <!-- adr-kit-guide v0.53.0 -->
2
2
  <!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
3
3
  <!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
4
4
 
@@ -2,7 +2,7 @@
2
2
  "_comment": "ADR Guardian SessionStart hook entry for .claude/settings.json",
3
3
  "_note": "Add this entry under hooks.SessionStart[0].hooks[] in the project's .claude/settings.json.",
4
4
  "_remove_marker": "adr-guardian-session-start",
5
- "_wrapper_version": "0.52.2",
5
+ "_wrapper_version": "0.53.0",
6
6
  "type": "command",
7
7
  "command": "ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1) && [ -n \"$ADR_KIT\" ] && _PY=$(command -v python3 || command -v python || command -v py) && [ -n \"$_PY\" ] && \"$_PY\" \"$ADR_KIT/bin/adr-guardian\" check 2>/dev/null || true",
8
8
  "timeout": 10
@@ -52,7 +52,7 @@ set -e
52
52
  # freezes at install time. adr-guardian compares this stamp against the
53
53
  # installed plugin version and nudges /adr-kit:upgrade when the wrapper lags.
54
54
  # Maintained by scripts/bump-version.py; do not edit by hand.
55
- ADR_KIT_WRAPPER_VERSION="0.52.2"
55
+ ADR_KIT_WRAPPER_VERSION="0.53.0"
56
56
 
57
57
  if [ "${ADR_KIT_HOOK_DISABLE:-0}" = "1" ]; then
58
58
  echo "[adr-kit] hook disabled for this commit (ADR_KIT_HOOK_DISABLE=1)" >&2