@rvdbreemen/adr-kit-opencode 0.57.0 → 0.59.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 +5 -3
- package/bin/adr +59 -19
- package/bin/adr-audit +41 -2
- package/bin/adr-judge +146 -4
- package/bin/adr-judge-precommit +30 -12
- package/bin/adr-lint +96 -18
- package/bin/adr-migrate +25 -5
- package/bin/adr-retire +86 -2
- package/bin/adr-substance +310 -0
- package/bin/adr_doctor_checks.py +6 -1
- package/bin/adr_format.py +112 -51
- package/bin/adr_llm.py +68 -8
- package/bin/adr_readiness.py +3 -0
- package/instructions/ADR-guide.md +1 -1
- package/package.json +1 -1
- package/schemas/adr-kit-config.schema.json +6 -0
- package/schemas/adr-readiness.schema.json +1 -0
- package/scripts/build-client-adapters.py +20 -1
- package/scripts/release_phases.py +30 -6
- package/skills/guardian/SKILL.md +21 -0
- package/skills/lint/SKILL.md +18 -1
- package/skills/review/SKILL.md +18 -0
- package/templates/adr-kit-guide.md +1 -1
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
|
@@ -15,6 +15,12 @@ from client_certification import support_matrix, validate
|
|
|
15
15
|
from client_evidence import CertificationError, assemble_native_bundle, write_bundle
|
|
16
16
|
|
|
17
17
|
|
|
18
|
+
# ADR-010: release evidence older than this is stale. A simulated fixture has a
|
|
19
|
+
# fixed date, so the CI check that renders docs/client-support.md from it
|
|
20
|
+
# passes a wider window explicitly; release evidence cannot.
|
|
21
|
+
CERTIFICATION_MAX_AGE_DAYS = 30
|
|
22
|
+
|
|
23
|
+
|
|
18
24
|
def main(argv: list[str] | None = None) -> int:
|
|
19
25
|
parser = argparse.ArgumentParser()
|
|
20
26
|
parser.add_argument("--check", action="store_true", help="fail when generated files drift")
|
|
@@ -24,6 +30,15 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
24
30
|
parser.add_argument("--certify", type=Path)
|
|
25
31
|
parser.add_argument("--candidate-commit")
|
|
26
32
|
parser.add_argument("--release-candidate", action="store_true")
|
|
33
|
+
parser.add_argument(
|
|
34
|
+
"--max-age-days",
|
|
35
|
+
type=int,
|
|
36
|
+
default=CERTIFICATION_MAX_AGE_DAYS,
|
|
37
|
+
help=(
|
|
38
|
+
"oldest acceptable contract date for --certify; only a simulated "
|
|
39
|
+
"bundle may relax it, never --release-candidate evidence"
|
|
40
|
+
),
|
|
41
|
+
)
|
|
27
42
|
parser.add_argument("--support-output", type=Path)
|
|
28
43
|
parser.add_argument(
|
|
29
44
|
"--assemble-native-evidence",
|
|
@@ -82,7 +97,11 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
82
97
|
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
83
98
|
print(f"certification bundle error: {exc}", file=sys.stderr)
|
|
84
99
|
return 2
|
|
85
|
-
|
|
100
|
+
if args.release_candidate and args.max_age_days != CERTIFICATION_MAX_AGE_DAYS:
|
|
101
|
+
parser.error("--max-age-days cannot relax --release-candidate evidence")
|
|
102
|
+
errors = validate(
|
|
103
|
+
bundle, args.candidate_commit, args.release_candidate, args.max_age_days
|
|
104
|
+
)
|
|
86
105
|
if args.support_output and not errors:
|
|
87
106
|
payload = support_matrix(bundle)
|
|
88
107
|
if args.check:
|
|
@@ -56,14 +56,38 @@ def preflight_done(ctx: Context) -> bool:
|
|
|
56
56
|
return False # cheap, and its answer can change between runs
|
|
57
57
|
|
|
58
58
|
|
|
59
|
+
def _dirty_paths() -> List[str]:
|
|
60
|
+
paths = []
|
|
61
|
+
for line in git("status", "--porcelain")[1].splitlines():
|
|
62
|
+
if len(line) > 3:
|
|
63
|
+
paths.append(line[3:].split(" -> ")[-1].strip().strip('"'))
|
|
64
|
+
return paths
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _release_owned(path: str) -> bool:
|
|
68
|
+
"""A file prepare writes: a declared version site or a generated client tree."""
|
|
69
|
+
registry = json.loads((ROOT / "packaging" / "version-sites.json").read_text(encoding="utf-8"))
|
|
70
|
+
sites = {site["path"] for site in registry.get("sites", [])}
|
|
71
|
+
return path in sites or path.startswith(("codex/", "copilot/"))
|
|
72
|
+
|
|
73
|
+
|
|
59
74
|
def preflight(ctx: Context) -> List[str]:
|
|
60
75
|
notes = []
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
)
|
|
76
|
+
dirty = _dirty_paths()
|
|
77
|
+
if dirty:
|
|
78
|
+
# prepare leaves its bump uncommitted on purpose and asks for a re-run;
|
|
79
|
+
# refusing that tree made the re-run impossible (TASK-213). Accept it
|
|
80
|
+
# only once the version is written and every change is prepare's own.
|
|
81
|
+
stray = [path for path in dirty if not _release_owned(path)]
|
|
82
|
+
if stray or not _version_everywhere(ctx):
|
|
83
|
+
listed = "".join(f"\n {path}" for path in stray)
|
|
84
|
+
raise ReleaseError(
|
|
85
|
+
"the working tree has uncommitted changes. Commit or stash them "
|
|
86
|
+
"first: a release commit must contain the version bump and "
|
|
87
|
+
"nothing that happened to be lying around."
|
|
88
|
+
+ (f"\nNot written by the release:{listed}" if listed else "")
|
|
89
|
+
)
|
|
90
|
+
notes.append(f"continuing a prepared release: {len(dirty)} release file(s) changed")
|
|
67
91
|
code, out, _ = script("check-branch-sync.py")
|
|
68
92
|
if code == 1:
|
|
69
93
|
raise ReleaseError(
|
package/skills/guardian/SKILL.md
CHANGED
|
@@ -168,6 +168,11 @@ Enforcement coverage percent (from 2c) in the append-only trend log.
|
|
|
168
168
|
Estimated cost: ~$0.10–0.30. Run now? (y/N)
|
|
169
169
|
```
|
|
170
170
|
|
|
171
|
+
Before printing it, run `"$ADR_KIT/bin/adr-substance" --estimate` and add
|
|
172
|
+
its line to the prompt: the section-substance check in 3a-bis costs one more
|
|
173
|
+
model call per Proposed ADR with written sections, and the user is agreeing
|
|
174
|
+
to that number too.
|
|
175
|
+
|
|
171
176
|
And wait for an explicit `y` / `yes`. If the user says no (or presses Enter on the default), skip the LLM tier and stop at Step 4.
|
|
172
177
|
|
|
173
178
|
- If `guardian.llm_autorun` is `true`, proceed without asking (user opted in explicitly in config).
|
|
@@ -187,6 +192,22 @@ Read `/tmp/guardian-suggest.json`.
|
|
|
187
192
|
|
|
188
193
|
**Response (mix-by-finding-type: Missing ADR):** Passive. List candidates where `needs_adr=true` with `confidence >= medium`. Offer to author selected ones via the `adr-generator` subagent. User picks; never auto-create.
|
|
189
194
|
|
|
195
|
+
### 3a-bis. Written sections that say nothing (adr-substance)
|
|
196
|
+
|
|
197
|
+
The deterministic checks report a missing, empty or `- TODO:` section. They
|
|
198
|
+
cannot tell "TBD", "see above" or generic prose from an answer. This step asks
|
|
199
|
+
the model, one isolated call per Proposed ADR (TASK-203):
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
"$ADR_KIT/bin/adr-substance" --adr-dir docs/adr/ --json > /tmp/guardian-substance.json
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
**Response (advisory):** For each finding, show the ADR, the section and the
|
|
206
|
+
quoted text, and offer `/adr-kit:grill ADR-NNN` to answer it. Nothing blocks:
|
|
207
|
+
the exit code is always 0, `adr-lint` and `adr accept` are unaffected, and a
|
|
208
|
+
`degraded` field means the model gave no usable answer for the ADRs it names,
|
|
209
|
+
not that they are fine.
|
|
210
|
+
|
|
190
211
|
### 3b. Full audit (adr-judge with LLM pass, one ADR at a time)
|
|
191
212
|
|
|
192
213
|
The audit judges each ADR in an isolated call and stamps its verdict the moment
|
package/skills/lint/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: lint
|
|
|
3
3
|
description: "Lint ADRs against schema and four verification gates. Use for ADR lint, validation, status-history checks, or file-and-line findings. Read-only."
|
|
4
4
|
argument-hint: "[file or directory; defaults to docs/adr/]"
|
|
5
5
|
disable-model-invocation: true
|
|
6
|
-
allowed-tools: [Read, Glob, Grep]
|
|
6
|
+
allowed-tools: [Read, Bash, Glob, Grep]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# adr-kit lint
|
|
@@ -13,6 +13,23 @@ is empty.
|
|
|
13
13
|
|
|
14
14
|
You are running `/adr-kit:lint`. The user wants to know whether existing ADRs in their project pass the four verification gates that the main `adr` skill enforces and, for v0.14 ADRs, whether their status histories are intact. You read files; you do not modify them. You report.
|
|
15
15
|
|
|
16
|
+
## Run the deterministic CLI first
|
|
17
|
+
|
|
18
|
+
The gates below are implemented by `bin/adr-lint`; run it and report what it
|
|
19
|
+
finds, rather than re-deriving every verdict by reading files:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
23
|
+
python "$ADR_KIT/bin/adr-lint" --format json docs/adr/
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Pass the argument path instead of `docs/adr/` when one was given. Exit 0 is
|
|
27
|
+
clean, 1 means findings, 2 is a configuration or input error: relay its
|
|
28
|
+
message and stop. Use the gate descriptions below to explain each finding
|
|
29
|
+
and to judge what the CLI leaves to judgment (the heuristic Evidence and
|
|
30
|
+
Clarity calls); when the CLI cannot run at all, fall back to reading the
|
|
31
|
+
files yourself and say that you did.
|
|
32
|
+
|
|
16
33
|
The deterministic CLI also returns read-only migration notices. Report them
|
|
17
34
|
even when every canonical ADR passes. A notice may contain an exact
|
|
18
35
|
`adr-migrate --dry-run` command for a supported legacy file or a guided
|
package/skills/review/SKILL.md
CHANGED
|
@@ -82,6 +82,24 @@ For violations, offer the same three resolution paths as `/adr-kit:judge` (new A
|
|
|
82
82
|
|
|
83
83
|
If the user wants the semantic pass too, offer `--llm` as an explicit follow-up (costs money; same cost posture as `/adr-kit:judge`).
|
|
84
84
|
|
|
85
|
+
### 3b. Is the decision implemented where it says it applies?
|
|
86
|
+
|
|
87
|
+
The judge answers "was a rule violated?", which is green when the rule checks nothing. Run the deterministic half first:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
"$ADR_KIT/bin/adr-judge" --check-scope --adr-dir docs/adr/ \
|
|
91
|
+
--repo-root "$(git rev-parse --show-toplevel)"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Report each ADVISORY: an Enforcement `path_glob` that matches no tracked file can never fire.
|
|
95
|
+
|
|
96
|
+
Then check the half no tool can, for each Accepted ADR the range touches whose Decision enumerates cases or names targets:
|
|
97
|
+
|
|
98
|
+
- **Every enumerated case has code that tests it.** ADR-041 named five reasons a record is queue-eligible; the code tested one, and every check stayed green because each sentence of the ADR was true.
|
|
99
|
+
- **Every named target compiles the code path.** In one firmware project the mitigation call sat inside an `#if` that was 1 only on another board, so the target the ADR named never ran it. Look for preprocessor guards, feature flags and platform checks around the call sites.
|
|
100
|
+
|
|
101
|
+
Report a gap as an advisory finding with the ADR id, the case or target, and the file:line where it is missing. It does not block; it goes to the user like an enforcement finding.
|
|
102
|
+
|
|
85
103
|
## Step 4 - Discovery pass
|
|
86
104
|
|
|
87
105
|
Two signals, cheapest first.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- adr-kit-guide v0.
|
|
1
|
+
<!-- adr-kit-guide v0.59.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.
|
|
5
|
+
"_wrapper_version": "0.59.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.
|
|
55
|
+
ADR_KIT_WRAPPER_VERSION="0.59.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
|