@rvdbreemen/adr-kit-opencode 0.52.0 → 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.
- package/.claude-plugin/plugin.json +29 -29
- package/README.md +865 -850
- package/bin/adr +0 -0
- package/bin/adr-audit +0 -0
- package/bin/adr-context +0 -0
- package/bin/adr-discover +0 -0
- package/bin/adr-doctor +0 -0
- package/bin/adr-generate-scripts +0 -0
- package/bin/adr-grill-signal +0 -0
- package/bin/adr-guardian +0 -0
- package/bin/adr-index +0 -0
- package/bin/adr-judge +0 -0
- package/bin/adr-judge-precommit +0 -0
- package/bin/adr-lint +0 -0
- package/bin/adr-mcp +96 -4
- package/bin/adr-migrate +0 -0
- package/bin/adr-quality +0 -0
- package/bin/adr-readiness +0 -0
- package/bin/adr-readiness-ci +0 -0
- package/bin/adr-related +0 -0
- package/bin/adr-renumber +254 -254
- package/bin/adr-retire +0 -0
- package/bin/adr-settings +0 -0
- package/bin/adr-status +0 -0
- package/bin/adr-suggest +0 -0
- package/bin/adr-watch +0 -0
- package/bin/adr_doctor_probes.py +2 -0
- package/bin/bump-version +0 -0
- package/clients/workflows.json +229 -229
- package/hooks/__init__.py +1 -1
- package/hooks/adapters/__init__.py +13 -13
- package/hooks/adapters/claude.py +27 -27
- package/hooks/adapters/codex.py +26 -26
- package/hooks/adapters/copilot.py +11 -11
- package/hooks/adr-hook.py +128 -128
- package/hooks/adr_hook_core.py +843 -843
- package/hooks/adr_pr_guard.py +367 -367
- package/instructions/ADR-guide.md +101 -48
- package/instructions/adr.coding.md +82 -82
- package/instructions/adr.review.md +182 -182
- package/opencode/plugin.ts +1 -4
- package/package.json +5 -2
- package/schemas/adr-context-probes.schema.json +56 -56
- package/schemas/adr-enforcement.schema.json +57 -57
- package/schemas/adr-frontmatter.schema.json +144 -144
- package/schemas/adr-index.schema.json +276 -276
- package/schemas/adr-kit-config.schema.json +371 -371
- package/schemas/adr-readiness.schema.json +41 -41
- package/schemas/client-capabilities.schema.json +503 -503
- package/schemas/client-certification.schema.json +101 -101
- package/schemas/doctor-output.schema.json +92 -92
- package/skills/adr/SKILL.md +780 -780
- package/skills/audit/SKILL.md +103 -103
- package/skills/context/SKILL.md +77 -77
- package/skills/grill/SKILL.md +84 -84
- package/skills/grill/agents/openai.yaml +4 -4
- package/skills/guardian/SKILL.md +316 -316
- package/skills/init/SKILL.md +499 -499
- package/skills/install-hooks/SKILL.md +154 -154
- package/skills/judge/SKILL.md +168 -168
- package/skills/lint/SKILL.md +321 -321
- package/skills/migrate/SKILL.md +313 -313
- package/skills/related/SKILL.md +62 -62
- package/skills/retire/SKILL.md +41 -41
- package/skills/review/SKILL.md +167 -167
- package/skills/settings/SKILL.md +73 -73
- package/skills/setup/SKILL.md +128 -128
- package/skills/supersede/SKILL.md +136 -136
- package/skills/upgrade/SKILL.md +273 -273
- package/templates/adr-kit-guide.md +354 -354
- package/templates/adr-template.canonical.md +115 -115
- package/templates/adr-template.madr.md +131 -131
- package/templates/adr-template.md +131 -131
- package/templates/adr-template.nygard.md +111 -111
- package/templates/cc-settings/guardian-hook-entry.json +9 -9
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-audit.yml +58 -58
- package/templates/github-workflows/adr-guardian-audit.yml +133 -133
- package/templates/github-workflows/adr-index-check.yml +30 -30
- package/templates/github-workflows/adr-judge.yml +31 -31
- package/templates/github-workflows/adr-readiness.yml +18 -18
- package/templates/validate_adr_template.py +38 -38
- package/templates/validate_adr_template.sh +74 -74
|
@@ -1,182 +1,182 @@
|
|
|
1
|
-
# ADR Checks for Code Review
|
|
2
|
-
|
|
3
|
-
When you are reviewing a PR or a diff, run these seven checks for ADR compliance. The canonical guide is `docs/adr/README.md`; the comprehensive skill is `SKILL.md`. Check 7 was added in adr-kit v0.12.0 alongside the declarative Enforcement-block engine in `bin/adr-judge`.
|
|
4
|
-
|
|
5
|
-
## Check 1: ADR exists for architecturally significant changes
|
|
6
|
-
|
|
7
|
-
If the diff touches any of:
|
|
8
|
-
|
|
9
|
-
- **Architecture**: service or module boundaries, deployment, integration patterns
|
|
10
|
-
- **Non-functional requirements**: security, availability, performance, privacy, resilience
|
|
11
|
-
- **Interfaces and contracts**: API behaviour, message topics, RPC contracts, breaking changes
|
|
12
|
-
- **Dependencies**: new frameworks or libraries with broad impact
|
|
13
|
-
- **Build and tooling**: build system, CI gates, development workflow
|
|
14
|
-
|
|
15
|
-
then there should be a linked ADR.
|
|
16
|
-
|
|
17
|
-
**Action if missing:**
|
|
18
|
-
|
|
19
|
-
- Request an ADR. Be specific about which decision should be captured.
|
|
20
|
-
- Suggest the `adr-generator` subagent for fast scaffolding.
|
|
21
|
-
|
|
22
|
-
## Check 2: ADR is properly linked
|
|
23
|
-
|
|
24
|
-
Verify the PR description includes:
|
|
25
|
-
|
|
26
|
-
- A path to the ADR: `docs/adr/ADR-XXX-title.md`
|
|
27
|
-
- A clear explanation of how the diff relates to the ADR
|
|
28
|
-
- If implementing a `Proposed` ADR, check whether the Status should flip to `Accepted` in this PR
|
|
29
|
-
|
|
30
|
-
**Action if link is missing or unclear:**
|
|
31
|
-
|
|
32
|
-
- Request the ADR link in the PR description.
|
|
33
|
-
- Ask for one sentence connecting the code change to the ADR's decision.
|
|
34
|
-
|
|
35
|
-
## Check 3: No ADR violations
|
|
36
|
-
|
|
37
|
-
Check whether the diff violates an `Accepted` ADR:
|
|
38
|
-
|
|
39
|
-
- Cross-reference `docs/adr/README.md` for relevant ADRs to the touched files
|
|
40
|
-
- Check ADR-specific compliance for ADRs that include enforcement rules
|
|
41
|
-
- Verify the change follows patterns established by `Accepted` ADRs
|
|
42
|
-
|
|
43
|
-
**Action if violation found:**
|
|
44
|
-
|
|
45
|
-
- *Option 1*: request alignment with the existing ADR.
|
|
46
|
-
- *Option 2*: request a new superseding ADR if the decision needs to change.
|
|
47
|
-
- Always explain *why* the change conflicts with the documented decision.
|
|
48
|
-
|
|
49
|
-
## Check 4: Supersession is correct
|
|
50
|
-
|
|
51
|
-
If the PR supersedes an existing ADR:
|
|
52
|
-
|
|
53
|
-
- Verify the new ADR includes a `## Related Decisions` entry "Supersedes ADR-XXX"
|
|
54
|
-
- Verify the old ADR's Status line is updated to `Superseded by ADR-YYY` and its `## Status History` has a matching appended transition
|
|
55
|
-
- Verify the supersession rationale appears in the new ADR (not the old one)
|
|
56
|
-
- Verify the old ADR's content (context, decision, alternatives, consequences) and earlier history entries are **not modified**. Only the Status line and one appended transition may change.
|
|
57
|
-
|
|
58
|
-
**Action if supersession is incorrect:**
|
|
59
|
-
|
|
60
|
-
- Request proper supersession linking.
|
|
61
|
-
- If the old ADR's content was edited, request a revert of that part.
|
|
62
|
-
|
|
63
|
-
## Check 5: ADR quality (the four verification gates)
|
|
64
|
-
|
|
65
|
-
Apply the four named gates from `SKILL.md`:
|
|
66
|
-
|
|
67
|
-
- **Completeness gate**: problem stated, decision unambiguous, 2+ alternatives with rejection reasoning, consequences in both directions, risks named with mitigations.
|
|
68
|
-
- **Evidence gate**: bare adjectives replaced with measurements; constraint claims anchored to a source; code references include `file:line`; external claims linked.
|
|
69
|
-
- **Clarity gate**: acronyms defined on first use, technical concepts explained when load-bearing, decision explainable in one paragraph at the top.
|
|
70
|
-
- **Consistency gate**: no conflict with another `Accepted` ADR (or explicit supersede), cross-references present, terminology matches other ADRs, ADR number sequential.
|
|
71
|
-
|
|
72
|
-
**Action if a gate fails:**
|
|
73
|
-
|
|
74
|
-
- Cite the failing gate by name: "This ADR fails the Evidence gate. Please add a measurement to back the 'reduces fragmentation' claim."
|
|
75
|
-
- Suggest a fix.
|
|
76
|
-
- Reference an existing ADR in the project as a positive example, if available.
|
|
77
|
-
|
|
78
|
-
## Check 6: Legacy non-compliance
|
|
79
|
-
|
|
80
|
-
If existing code does not comply with a *new* ADR:
|
|
81
|
-
|
|
82
|
-
- Acknowledge the legacy non-compliance explicitly.
|
|
83
|
-
- Request a remediation plan: an incremental cleanup, a tech-debt issue with a target version, or an explicit "out of scope for this PR" note.
|
|
84
|
-
- Do not block the ADR adoption itself due to legacy issues.
|
|
85
|
-
- Ensure the *new* code in this PR complies.
|
|
86
|
-
|
|
87
|
-
## Check 7: Enforcement block (v0.12+)
|
|
88
|
-
|
|
89
|
-
Every new `Accepted` ADR with a code surface SHOULD include an `## Enforcement` section so the pre-commit hook can guard the boundary. Three acceptable patterns:
|
|
90
|
-
|
|
91
|
-
- **Declarative rules.** A fenced JSON block with `forbid_pattern` / `forbid_import` / `require_pattern` arrays. `bin/adr-judge` runs them deterministically on the staged diff at commit time. Preferred when the rule is mechanically expressible — fastest path, no LLM round-trip.
|
|
92
|
-
- **`"llm_judge": true`.** Free-form ADRs whose rules cannot be expressed as regex but are still code-relevant. The pre-commit hook batches all `llm_judge` ADRs into ONE Claude Sonnet call and blocks the commit on `VIOLATION` when the LLM pass is active. As of v0.17.0 the LLM pass is opt-in (off by default); enable via `judge.llm_enabled:true` in `.adr-kit.json`, or `ADR_KIT_LLM=1` for a single commit. `/adr-kit:judge` always runs the LLM pass on demand regardless of that setting. Falls back to declarative-only when the `claude` CLI is missing — never blocks on tooling drift. Cost shape when enabled: ~$0.10–0.30 per commit on Sonnet 4.6 with prompt caching.
|
|
93
|
-
- **Section omitted.** ADRs with no code surface (governance, process, organisational decisions). The judge skips them silently. The PR author should explain in the ADR body *why* the rule isn't mechanically expressible.
|
|
94
|
-
|
|
95
|
-
**Action if missing on a code-touching ADR:**
|
|
96
|
-
|
|
97
|
-
- Request an Enforcement block. Suggest one of the three patterns based on the rule's shape.
|
|
98
|
-
- Reference an existing ADR in the project that already has a good declarative block, if available.
|
|
99
|
-
- Reject "we'll add it later" — adding the block is part of the original Definition of Done. Without it, drift is silent.
|
|
100
|
-
|
|
101
|
-
## Review-comment templates
|
|
102
|
-
|
|
103
|
-
### Missing ADR
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
This change introduces a new caching pattern, which affects architecture.
|
|
107
|
-
Please create an ADR documenting:
|
|
108
|
-
- Why caching is needed (context, constraints)
|
|
109
|
-
- Cache options considered (Redis, Memcached, in-memory)
|
|
110
|
-
- Chosen approach and rationale
|
|
111
|
-
- Consequences (performance gains, memory and complexity costs)
|
|
112
|
-
|
|
113
|
-
The adr-generator subagent can scaffold this. See SKILL.md for the template.
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### ADR violation
|
|
117
|
-
|
|
118
|
-
```
|
|
119
|
-
This change uses pattern X in performance-critical code, which violates
|
|
120
|
-
ADR-NNN (Title). Two options:
|
|
121
|
-
|
|
122
|
-
1. Refactor to follow ADR-NNN's pattern.
|
|
123
|
-
2. Write a superseding ADR if the decision needs to change.
|
|
124
|
-
|
|
125
|
-
ADR-NNN: docs/adr/ADR-NNN-title.md
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### Supersession issue
|
|
129
|
-
|
|
130
|
-
```
|
|
131
|
-
This ADR supersedes ADR-OLD but ADR-OLD has not been updated.
|
|
132
|
-
|
|
133
|
-
Please:
|
|
134
|
-
1. Update ADR-OLD Status line to "Superseded by ADR-NEW".
|
|
135
|
-
2. Confirm ADR-OLD's content (context, decision, alternatives, consequences)
|
|
136
|
-
is unchanged. ADR immutability is the rule; only the Status line moves.
|
|
137
|
-
3. Cross-reference both ADRs in their `## Related Decisions` sections.
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### Verification gate failure
|
|
141
|
-
|
|
142
|
-
```
|
|
143
|
-
This ADR's Evidence gate fails. Two specific spots:
|
|
144
|
-
|
|
145
|
-
1. "Improves performance" (line N): replace with a measurement
|
|
146
|
-
("reduces request latency from X to Y") or a benchmark reference.
|
|
147
|
-
2. "Memory constraint requires this" (line M): cite where (datasheet,
|
|
148
|
-
measured, vendor doc) and how much.
|
|
149
|
-
|
|
150
|
-
ADR-NNN in this repo is a good positive reference for the Evidence gate.
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
### Missing Enforcement block
|
|
154
|
-
|
|
155
|
-
```
|
|
156
|
-
This ADR has a clear code surface (touches src/X, governs Y) but no
|
|
157
|
-
## Enforcement section. Without one, the pre-commit hook can't guard
|
|
158
|
-
the boundary and silent drift will accumulate.
|
|
159
|
-
|
|
160
|
-
Please add one of the three patterns:
|
|
161
|
-
|
|
162
|
-
- Declarative rules in a fenced JSON block (forbid_pattern, forbid_import,
|
|
163
|
-
require_pattern). Preferred if the rule can be expressed as regex/glob.
|
|
164
|
-
- `"llm_judge": true` — for nuanced rules that need a model's judgement.
|
|
165
|
-
Deep review still happens via /adr-kit:judge in a Claude Code session.
|
|
166
|
-
- Omit the section AND add a one-line explanation in the ADR body for
|
|
167
|
-
why the rule has no code surface (governance / process / etc.).
|
|
168
|
-
|
|
169
|
-
Schema: schemas/adr-enforcement.schema.json
|
|
170
|
-
Reference example: ADR-NNN in this repo.
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## Definition of Done for review
|
|
174
|
-
|
|
175
|
-
- [ ] Architecturally significant changes have a linked ADR
|
|
176
|
-
- [ ] ADR link is in the PR description
|
|
177
|
-
- [ ] No `Accepted` ADR is violated, or a superseding ADR is in place
|
|
178
|
-
- [ ] Supersession chain is correct
|
|
179
|
-
- [ ] All four verification gates pass on the ADR
|
|
180
|
-
- [ ] Legacy non-compliance, if any, has a remediation plan
|
|
181
|
-
- [ ] Code comments at non-obvious enforcement sites point at the ADR
|
|
182
|
-
- [ ] New `Accepted` ADRs with a code surface include an `## Enforcement` block (declarative rules OR `"llm_judge": true` OR explicit "no code surface" note)
|
|
1
|
+
# ADR Checks for Code Review
|
|
2
|
+
|
|
3
|
+
When you are reviewing a PR or a diff, run these seven checks for ADR compliance. The canonical guide is `docs/adr/README.md`; the comprehensive skill is `SKILL.md`. Check 7 was added in adr-kit v0.12.0 alongside the declarative Enforcement-block engine in `bin/adr-judge`.
|
|
4
|
+
|
|
5
|
+
## Check 1: ADR exists for architecturally significant changes
|
|
6
|
+
|
|
7
|
+
If the diff touches any of:
|
|
8
|
+
|
|
9
|
+
- **Architecture**: service or module boundaries, deployment, integration patterns
|
|
10
|
+
- **Non-functional requirements**: security, availability, performance, privacy, resilience
|
|
11
|
+
- **Interfaces and contracts**: API behaviour, message topics, RPC contracts, breaking changes
|
|
12
|
+
- **Dependencies**: new frameworks or libraries with broad impact
|
|
13
|
+
- **Build and tooling**: build system, CI gates, development workflow
|
|
14
|
+
|
|
15
|
+
then there should be a linked ADR.
|
|
16
|
+
|
|
17
|
+
**Action if missing:**
|
|
18
|
+
|
|
19
|
+
- Request an ADR. Be specific about which decision should be captured.
|
|
20
|
+
- Suggest the `adr-generator` subagent for fast scaffolding.
|
|
21
|
+
|
|
22
|
+
## Check 2: ADR is properly linked
|
|
23
|
+
|
|
24
|
+
Verify the PR description includes:
|
|
25
|
+
|
|
26
|
+
- A path to the ADR: `docs/adr/ADR-XXX-title.md`
|
|
27
|
+
- A clear explanation of how the diff relates to the ADR
|
|
28
|
+
- If implementing a `Proposed` ADR, check whether the Status should flip to `Accepted` in this PR
|
|
29
|
+
|
|
30
|
+
**Action if link is missing or unclear:**
|
|
31
|
+
|
|
32
|
+
- Request the ADR link in the PR description.
|
|
33
|
+
- Ask for one sentence connecting the code change to the ADR's decision.
|
|
34
|
+
|
|
35
|
+
## Check 3: No ADR violations
|
|
36
|
+
|
|
37
|
+
Check whether the diff violates an `Accepted` ADR:
|
|
38
|
+
|
|
39
|
+
- Cross-reference `docs/adr/README.md` for relevant ADRs to the touched files
|
|
40
|
+
- Check ADR-specific compliance for ADRs that include enforcement rules
|
|
41
|
+
- Verify the change follows patterns established by `Accepted` ADRs
|
|
42
|
+
|
|
43
|
+
**Action if violation found:**
|
|
44
|
+
|
|
45
|
+
- *Option 1*: request alignment with the existing ADR.
|
|
46
|
+
- *Option 2*: request a new superseding ADR if the decision needs to change.
|
|
47
|
+
- Always explain *why* the change conflicts with the documented decision.
|
|
48
|
+
|
|
49
|
+
## Check 4: Supersession is correct
|
|
50
|
+
|
|
51
|
+
If the PR supersedes an existing ADR:
|
|
52
|
+
|
|
53
|
+
- Verify the new ADR includes a `## Related Decisions` entry "Supersedes ADR-XXX"
|
|
54
|
+
- Verify the old ADR's Status line is updated to `Superseded by ADR-YYY` and its `## Status History` has a matching appended transition
|
|
55
|
+
- Verify the supersession rationale appears in the new ADR (not the old one)
|
|
56
|
+
- Verify the old ADR's content (context, decision, alternatives, consequences) and earlier history entries are **not modified**. Only the Status line and one appended transition may change.
|
|
57
|
+
|
|
58
|
+
**Action if supersession is incorrect:**
|
|
59
|
+
|
|
60
|
+
- Request proper supersession linking.
|
|
61
|
+
- If the old ADR's content was edited, request a revert of that part.
|
|
62
|
+
|
|
63
|
+
## Check 5: ADR quality (the four verification gates)
|
|
64
|
+
|
|
65
|
+
Apply the four named gates from `SKILL.md`:
|
|
66
|
+
|
|
67
|
+
- **Completeness gate**: problem stated, decision unambiguous, 2+ alternatives with rejection reasoning, consequences in both directions, risks named with mitigations.
|
|
68
|
+
- **Evidence gate**: bare adjectives replaced with measurements; constraint claims anchored to a source; code references include `file:line`; external claims linked.
|
|
69
|
+
- **Clarity gate**: acronyms defined on first use, technical concepts explained when load-bearing, decision explainable in one paragraph at the top.
|
|
70
|
+
- **Consistency gate**: no conflict with another `Accepted` ADR (or explicit supersede), cross-references present, terminology matches other ADRs, ADR number sequential.
|
|
71
|
+
|
|
72
|
+
**Action if a gate fails:**
|
|
73
|
+
|
|
74
|
+
- Cite the failing gate by name: "This ADR fails the Evidence gate. Please add a measurement to back the 'reduces fragmentation' claim."
|
|
75
|
+
- Suggest a fix.
|
|
76
|
+
- Reference an existing ADR in the project as a positive example, if available.
|
|
77
|
+
|
|
78
|
+
## Check 6: Legacy non-compliance
|
|
79
|
+
|
|
80
|
+
If existing code does not comply with a *new* ADR:
|
|
81
|
+
|
|
82
|
+
- Acknowledge the legacy non-compliance explicitly.
|
|
83
|
+
- Request a remediation plan: an incremental cleanup, a tech-debt issue with a target version, or an explicit "out of scope for this PR" note.
|
|
84
|
+
- Do not block the ADR adoption itself due to legacy issues.
|
|
85
|
+
- Ensure the *new* code in this PR complies.
|
|
86
|
+
|
|
87
|
+
## Check 7: Enforcement block (v0.12+)
|
|
88
|
+
|
|
89
|
+
Every new `Accepted` ADR with a code surface SHOULD include an `## Enforcement` section so the pre-commit hook can guard the boundary. Three acceptable patterns:
|
|
90
|
+
|
|
91
|
+
- **Declarative rules.** A fenced JSON block with `forbid_pattern` / `forbid_import` / `require_pattern` arrays. `bin/adr-judge` runs them deterministically on the staged diff at commit time. Preferred when the rule is mechanically expressible — fastest path, no LLM round-trip.
|
|
92
|
+
- **`"llm_judge": true`.** Free-form ADRs whose rules cannot be expressed as regex but are still code-relevant. The pre-commit hook batches all `llm_judge` ADRs into ONE Claude Sonnet call and blocks the commit on `VIOLATION` when the LLM pass is active. As of v0.17.0 the LLM pass is opt-in (off by default); enable via `judge.llm_enabled:true` in `.adr-kit.json`, or `ADR_KIT_LLM=1` for a single commit. `/adr-kit:judge` always runs the LLM pass on demand regardless of that setting. Falls back to declarative-only when the `claude` CLI is missing — never blocks on tooling drift. Cost shape when enabled: ~$0.10–0.30 per commit on Sonnet 4.6 with prompt caching.
|
|
93
|
+
- **Section omitted.** ADRs with no code surface (governance, process, organisational decisions). The judge skips them silently. The PR author should explain in the ADR body *why* the rule isn't mechanically expressible.
|
|
94
|
+
|
|
95
|
+
**Action if missing on a code-touching ADR:**
|
|
96
|
+
|
|
97
|
+
- Request an Enforcement block. Suggest one of the three patterns based on the rule's shape.
|
|
98
|
+
- Reference an existing ADR in the project that already has a good declarative block, if available.
|
|
99
|
+
- Reject "we'll add it later" — adding the block is part of the original Definition of Done. Without it, drift is silent.
|
|
100
|
+
|
|
101
|
+
## Review-comment templates
|
|
102
|
+
|
|
103
|
+
### Missing ADR
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
This change introduces a new caching pattern, which affects architecture.
|
|
107
|
+
Please create an ADR documenting:
|
|
108
|
+
- Why caching is needed (context, constraints)
|
|
109
|
+
- Cache options considered (Redis, Memcached, in-memory)
|
|
110
|
+
- Chosen approach and rationale
|
|
111
|
+
- Consequences (performance gains, memory and complexity costs)
|
|
112
|
+
|
|
113
|
+
The adr-generator subagent can scaffold this. See SKILL.md for the template.
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### ADR violation
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
This change uses pattern X in performance-critical code, which violates
|
|
120
|
+
ADR-NNN (Title). Two options:
|
|
121
|
+
|
|
122
|
+
1. Refactor to follow ADR-NNN's pattern.
|
|
123
|
+
2. Write a superseding ADR if the decision needs to change.
|
|
124
|
+
|
|
125
|
+
ADR-NNN: docs/adr/ADR-NNN-title.md
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Supersession issue
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
This ADR supersedes ADR-OLD but ADR-OLD has not been updated.
|
|
132
|
+
|
|
133
|
+
Please:
|
|
134
|
+
1. Update ADR-OLD Status line to "Superseded by ADR-NEW".
|
|
135
|
+
2. Confirm ADR-OLD's content (context, decision, alternatives, consequences)
|
|
136
|
+
is unchanged. ADR immutability is the rule; only the Status line moves.
|
|
137
|
+
3. Cross-reference both ADRs in their `## Related Decisions` sections.
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Verification gate failure
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
This ADR's Evidence gate fails. Two specific spots:
|
|
144
|
+
|
|
145
|
+
1. "Improves performance" (line N): replace with a measurement
|
|
146
|
+
("reduces request latency from X to Y") or a benchmark reference.
|
|
147
|
+
2. "Memory constraint requires this" (line M): cite where (datasheet,
|
|
148
|
+
measured, vendor doc) and how much.
|
|
149
|
+
|
|
150
|
+
ADR-NNN in this repo is a good positive reference for the Evidence gate.
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Missing Enforcement block
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
This ADR has a clear code surface (touches src/X, governs Y) but no
|
|
157
|
+
## Enforcement section. Without one, the pre-commit hook can't guard
|
|
158
|
+
the boundary and silent drift will accumulate.
|
|
159
|
+
|
|
160
|
+
Please add one of the three patterns:
|
|
161
|
+
|
|
162
|
+
- Declarative rules in a fenced JSON block (forbid_pattern, forbid_import,
|
|
163
|
+
require_pattern). Preferred if the rule can be expressed as regex/glob.
|
|
164
|
+
- `"llm_judge": true` — for nuanced rules that need a model's judgement.
|
|
165
|
+
Deep review still happens via /adr-kit:judge in a Claude Code session.
|
|
166
|
+
- Omit the section AND add a one-line explanation in the ADR body for
|
|
167
|
+
why the rule has no code surface (governance / process / etc.).
|
|
168
|
+
|
|
169
|
+
Schema: schemas/adr-enforcement.schema.json
|
|
170
|
+
Reference example: ADR-NNN in this repo.
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Definition of Done for review
|
|
174
|
+
|
|
175
|
+
- [ ] Architecturally significant changes have a linked ADR
|
|
176
|
+
- [ ] ADR link is in the PR description
|
|
177
|
+
- [ ] No `Accepted` ADR is violated, or a superseding ADR is in place
|
|
178
|
+
- [ ] Supersession chain is correct
|
|
179
|
+
- [ ] All four verification gates pass on the ADR
|
|
180
|
+
- [ ] Legacy non-compliance, if any, has a remediation plan
|
|
181
|
+
- [ ] Code comments at non-obvious enforcement sites point at the ADR
|
|
182
|
+
- [ ] New `Accepted` ADRs with a code surface include an `## Enforcement` block (declarative rules OR `"llm_judge": true` OR explicit "no code surface" note)
|
package/opencode/plugin.ts
CHANGED
|
@@ -293,10 +293,7 @@ export default async function AdrKitOpenCodePlugin(
|
|
|
293
293
|
if (options.references !== false && existsSync(join(input.directory, "docs", "adr"))) {
|
|
294
294
|
config.references ||= {}
|
|
295
295
|
if (!config.references["adr-decisions"]) {
|
|
296
|
-
config.references["adr-decisions"] =
|
|
297
|
-
path: join(input.directory, "docs", "adr"),
|
|
298
|
-
description: "Architecture Decision Records. Read returned Markdown before applying a decision.",
|
|
299
|
-
}
|
|
296
|
+
config.references["adr-decisions"] = join(input.directory, "docs", "adr")
|
|
300
297
|
}
|
|
301
298
|
}
|
|
302
299
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rvdbreemen/adr-kit-opencode",
|
|
3
|
-
"version": "0.
|
|
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",
|
|
7
7
|
"license": "MIT",
|
|
8
|
-
"repository":
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/rvdbreemen/adr-kit.git"
|
|
11
|
+
},
|
|
9
12
|
"homepage": "https://github.com/rvdbreemen/adr-kit",
|
|
10
13
|
"keywords": [
|
|
11
14
|
"opencode",
|
|
@@ -1,56 +1,56 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://adr-kit.dev/schemas/adr-context-probes.schema.json",
|
|
4
|
-
"title": "ADR Kit selective-context retrieval probes",
|
|
5
|
-
"type": "object",
|
|
6
|
-
"additionalProperties": false,
|
|
7
|
-
"required": ["schema_version", "probes"],
|
|
8
|
-
"properties": {
|
|
9
|
-
"$schema": {"type": "string"},
|
|
10
|
-
"schema_version": {"const": 1},
|
|
11
|
-
"probes": {
|
|
12
|
-
"type": "array",
|
|
13
|
-
"maxItems": 100,
|
|
14
|
-
"items": {"$ref": "#/$defs/probe"}
|
|
15
|
-
}
|
|
16
|
-
},
|
|
17
|
-
"$defs": {
|
|
18
|
-
"strings": {
|
|
19
|
-
"type": "array",
|
|
20
|
-
"maxItems": 32,
|
|
21
|
-
"uniqueItems": true,
|
|
22
|
-
"items": {"type": "string", "minLength": 1, "maxLength": 240}
|
|
23
|
-
},
|
|
24
|
-
"adrIds": {
|
|
25
|
-
"type": "array",
|
|
26
|
-
"maxItems": 20,
|
|
27
|
-
"uniqueItems": true,
|
|
28
|
-
"items": {"type": "string", "pattern": "^ADR-[0-9]{3,4}$"}
|
|
29
|
-
},
|
|
30
|
-
"probe": {
|
|
31
|
-
"type": "object",
|
|
32
|
-
"additionalProperties": false,
|
|
33
|
-
"required": ["id", "query", "expect"],
|
|
34
|
-
"properties": {
|
|
35
|
-
"id": {
|
|
36
|
-
"type": "string",
|
|
37
|
-
"pattern": "^[a-z][a-z0-9-]{0,79}$"
|
|
38
|
-
},
|
|
39
|
-
"query": {"type": "string", "minLength": 1, "maxLength": 1000},
|
|
40
|
-
"paths": {"$ref": "#/$defs/strings"},
|
|
41
|
-
"components": {"$ref": "#/$defs/strings"},
|
|
42
|
-
"symbols": {"$ref": "#/$defs/strings"},
|
|
43
|
-
"topics": {"$ref": "#/$defs/strings"},
|
|
44
|
-
"limit": {"type": "integer", "minimum": 1, "maximum": 20, "default": 3},
|
|
45
|
-
"expect": {
|
|
46
|
-
"type": "object",
|
|
47
|
-
"additionalProperties": false,
|
|
48
|
-
"properties": {
|
|
49
|
-
"include": {"$ref": "#/$defs/adrIds"},
|
|
50
|
-
"exclude": {"$ref": "#/$defs/adrIds"}
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
}
|
|
56
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://adr-kit.dev/schemas/adr-context-probes.schema.json",
|
|
4
|
+
"title": "ADR Kit selective-context retrieval probes",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["schema_version", "probes"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"$schema": {"type": "string"},
|
|
10
|
+
"schema_version": {"const": 1},
|
|
11
|
+
"probes": {
|
|
12
|
+
"type": "array",
|
|
13
|
+
"maxItems": 100,
|
|
14
|
+
"items": {"$ref": "#/$defs/probe"}
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"$defs": {
|
|
18
|
+
"strings": {
|
|
19
|
+
"type": "array",
|
|
20
|
+
"maxItems": 32,
|
|
21
|
+
"uniqueItems": true,
|
|
22
|
+
"items": {"type": "string", "minLength": 1, "maxLength": 240}
|
|
23
|
+
},
|
|
24
|
+
"adrIds": {
|
|
25
|
+
"type": "array",
|
|
26
|
+
"maxItems": 20,
|
|
27
|
+
"uniqueItems": true,
|
|
28
|
+
"items": {"type": "string", "pattern": "^ADR-[0-9]{3,4}$"}
|
|
29
|
+
},
|
|
30
|
+
"probe": {
|
|
31
|
+
"type": "object",
|
|
32
|
+
"additionalProperties": false,
|
|
33
|
+
"required": ["id", "query", "expect"],
|
|
34
|
+
"properties": {
|
|
35
|
+
"id": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"pattern": "^[a-z][a-z0-9-]{0,79}$"
|
|
38
|
+
},
|
|
39
|
+
"query": {"type": "string", "minLength": 1, "maxLength": 1000},
|
|
40
|
+
"paths": {"$ref": "#/$defs/strings"},
|
|
41
|
+
"components": {"$ref": "#/$defs/strings"},
|
|
42
|
+
"symbols": {"$ref": "#/$defs/strings"},
|
|
43
|
+
"topics": {"$ref": "#/$defs/strings"},
|
|
44
|
+
"limit": {"type": "integer", "minimum": 1, "maximum": 20, "default": 3},
|
|
45
|
+
"expect": {
|
|
46
|
+
"type": "object",
|
|
47
|
+
"additionalProperties": false,
|
|
48
|
+
"properties": {
|
|
49
|
+
"include": {"$ref": "#/$defs/adrIds"},
|
|
50
|
+
"exclude": {"$ref": "#/$defs/adrIds"}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
@@ -1,57 +1,57 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
-
"title": "ADR Enforcement Block Schema (v0.14.0+)",
|
|
4
|
-
"type": "object",
|
|
5
|
-
"properties": {
|
|
6
|
-
"forbid_pattern": {
|
|
7
|
-
"type": "array",
|
|
8
|
-
"items": {
|
|
9
|
-
"type": "object",
|
|
10
|
-
"properties": {
|
|
11
|
-
"pattern": { "type": "string", "minLength": 1 },
|
|
12
|
-
"path_glob": { "type": "string" },
|
|
13
|
-
"message": { "type": "string" }
|
|
14
|
-
},
|
|
15
|
-
"required": ["pattern"],
|
|
16
|
-
"additionalProperties": false
|
|
17
|
-
}
|
|
18
|
-
},
|
|
19
|
-
"forbid_import": {
|
|
20
|
-
"type": "array",
|
|
21
|
-
"items": {
|
|
22
|
-
"type": "object",
|
|
23
|
-
"properties": {
|
|
24
|
-
"pattern": { "type": "string", "minLength": 1 },
|
|
25
|
-
"path_glob": { "type": "string" },
|
|
26
|
-
"message": { "type": "string" }
|
|
27
|
-
},
|
|
28
|
-
"required": ["pattern"],
|
|
29
|
-
"additionalProperties": false
|
|
30
|
-
}
|
|
31
|
-
},
|
|
32
|
-
"require_pattern": {
|
|
33
|
-
"type": "array",
|
|
34
|
-
"items": {
|
|
35
|
-
"type": "object",
|
|
36
|
-
"properties": {
|
|
37
|
-
"pattern": { "type": "string", "minLength": 1 },
|
|
38
|
-
"path_glob": { "type": "string" },
|
|
39
|
-
"message": { "type": "string" }
|
|
40
|
-
},
|
|
41
|
-
"required": ["pattern"],
|
|
42
|
-
"additionalProperties": false
|
|
43
|
-
}
|
|
44
|
-
},
|
|
45
|
-
"llm_judge": {
|
|
46
|
-
"type": "boolean",
|
|
47
|
-
"default": true,
|
|
48
|
-
"description": "Whether the LLM pass evaluates the staged diff against this ADR's Decision text. DEFAULT TRUE as of TASK-74: an Enforcement block that omits the key opts in, and only an explicit false opts out. The previous opt-in default failed silently -- a pass that was on by default with an empty population judged nothing while looking active. Cost is bounded by scope, not by this flag: an ADR is only judged when the diff touches a file matching its rules' path_glob set. An Enforcement block that declares no rules, or a rule without a path_glob, has no boundary to narrow with and is therefore judged on EVERY commit; prefer marking such a decision as having no code surface."
|
|
49
|
-
},
|
|
50
|
-
"llm_judge_reason": {
|
|
51
|
-
"type": "string",
|
|
52
|
-
"minLength": 1,
|
|
53
|
-
"description": "Why the LLM pass is off for this ADR. Only meaningful together with llm_judge:false. Since the default flipped to true, a bare false is ambiguous -- it may be a deliberate opt-out or a leftover from when false was the default. A reason makes the opt-out durable: the upgrade re-proposes a bare false and leaves a reasoned one alone. Typical value: 'no code surface -- this decision governs the release process, not code'."
|
|
54
|
-
}
|
|
55
|
-
},
|
|
56
|
-
"additionalProperties": false
|
|
57
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"title": "ADR Enforcement Block Schema (v0.14.0+)",
|
|
4
|
+
"type": "object",
|
|
5
|
+
"properties": {
|
|
6
|
+
"forbid_pattern": {
|
|
7
|
+
"type": "array",
|
|
8
|
+
"items": {
|
|
9
|
+
"type": "object",
|
|
10
|
+
"properties": {
|
|
11
|
+
"pattern": { "type": "string", "minLength": 1 },
|
|
12
|
+
"path_glob": { "type": "string" },
|
|
13
|
+
"message": { "type": "string" }
|
|
14
|
+
},
|
|
15
|
+
"required": ["pattern"],
|
|
16
|
+
"additionalProperties": false
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
"forbid_import": {
|
|
20
|
+
"type": "array",
|
|
21
|
+
"items": {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"properties": {
|
|
24
|
+
"pattern": { "type": "string", "minLength": 1 },
|
|
25
|
+
"path_glob": { "type": "string" },
|
|
26
|
+
"message": { "type": "string" }
|
|
27
|
+
},
|
|
28
|
+
"required": ["pattern"],
|
|
29
|
+
"additionalProperties": false
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"require_pattern": {
|
|
33
|
+
"type": "array",
|
|
34
|
+
"items": {
|
|
35
|
+
"type": "object",
|
|
36
|
+
"properties": {
|
|
37
|
+
"pattern": { "type": "string", "minLength": 1 },
|
|
38
|
+
"path_glob": { "type": "string" },
|
|
39
|
+
"message": { "type": "string" }
|
|
40
|
+
},
|
|
41
|
+
"required": ["pattern"],
|
|
42
|
+
"additionalProperties": false
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
"llm_judge": {
|
|
46
|
+
"type": "boolean",
|
|
47
|
+
"default": true,
|
|
48
|
+
"description": "Whether the LLM pass evaluates the staged diff against this ADR's Decision text. DEFAULT TRUE as of TASK-74: an Enforcement block that omits the key opts in, and only an explicit false opts out. The previous opt-in default failed silently -- a pass that was on by default with an empty population judged nothing while looking active. Cost is bounded by scope, not by this flag: an ADR is only judged when the diff touches a file matching its rules' path_glob set. An Enforcement block that declares no rules, or a rule without a path_glob, has no boundary to narrow with and is therefore judged on EVERY commit; prefer marking such a decision as having no code surface."
|
|
49
|
+
},
|
|
50
|
+
"llm_judge_reason": {
|
|
51
|
+
"type": "string",
|
|
52
|
+
"minLength": 1,
|
|
53
|
+
"description": "Why the LLM pass is off for this ADR. Only meaningful together with llm_judge:false. Since the default flipped to true, a bare false is ambiguous -- it may be a deliberate opt-out or a leftover from when false was the default. A reason makes the opt-out durable: the upgrade re-proposes a bare false and leaves a reasoned one alone. Typical value: 'no code surface -- this decision governs the release process, not code'."
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"additionalProperties": false
|
|
57
|
+
}
|