@rvdbreemen/adr-kit-opencode 0.52.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 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: "ADR-NNN"
|
|
3
|
+
title: "Short Imperative Title"
|
|
4
|
+
status: "Proposed"
|
|
5
|
+
date: "YYYY-MM-DD"
|
|
6
|
+
binding: false
|
|
7
|
+
gate: null
|
|
8
|
+
documents_shipped: false
|
|
9
|
+
verified_in: []
|
|
10
|
+
supersedes: []
|
|
11
|
+
superseded_by: null
|
|
12
|
+
format: "madr"
|
|
13
|
+
topics: []
|
|
14
|
+
aliases: []
|
|
15
|
+
components: []
|
|
16
|
+
symbols: []
|
|
17
|
+
context_scope: "selective"
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
<!-- markdownlint-disable MD025 -->
|
|
21
|
+
|
|
22
|
+
# ADR-NNN Short Imperative Title
|
|
23
|
+
|
|
24
|
+
## Status
|
|
25
|
+
|
|
26
|
+
Proposed, YYYY-MM-DD.
|
|
27
|
+
|
|
28
|
+
## Status History
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
status_history:
|
|
32
|
+
- date: YYYY-MM-DD
|
|
33
|
+
status: Proposed
|
|
34
|
+
changed_by: user@example.com
|
|
35
|
+
reason: Initial proposal
|
|
36
|
+
changed_via: adr-kit
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Context and Problem Statement
|
|
40
|
+
|
|
41
|
+
State the problem, constraints, and concrete evidence.
|
|
42
|
+
|
|
43
|
+
## Decision Drivers
|
|
44
|
+
|
|
45
|
+
* Driver one.
|
|
46
|
+
* Driver two.
|
|
47
|
+
|
|
48
|
+
## Considered Options
|
|
49
|
+
|
|
50
|
+
* Option A.
|
|
51
|
+
* Option B.
|
|
52
|
+
* Do nothing, when it is a realistic option.
|
|
53
|
+
|
|
54
|
+
## Decision Outcome
|
|
55
|
+
|
|
56
|
+
Chosen option: **Option A**, because state the decisive rationale.
|
|
57
|
+
|
|
58
|
+
### Confirmation
|
|
59
|
+
|
|
60
|
+
State how implementation of the decision will be verified.
|
|
61
|
+
|
|
62
|
+
## Decision Contract
|
|
63
|
+
|
|
64
|
+
### Must
|
|
65
|
+
|
|
66
|
+
* State required implementation constraints.
|
|
67
|
+
|
|
68
|
+
### Must Not
|
|
69
|
+
|
|
70
|
+
* State prohibited implementation choices.
|
|
71
|
+
|
|
72
|
+
### Exceptions
|
|
73
|
+
|
|
74
|
+
* State explicit exceptions, or `None`.
|
|
75
|
+
|
|
76
|
+
### Verification
|
|
77
|
+
|
|
78
|
+
* Name the test, command, or source anchor that verifies this decision.
|
|
79
|
+
|
|
80
|
+
## Consequences
|
|
81
|
+
|
|
82
|
+
### Positive
|
|
83
|
+
|
|
84
|
+
* Expected benefit.
|
|
85
|
+
|
|
86
|
+
### Negative
|
|
87
|
+
|
|
88
|
+
* Accepted cost or risk and its mitigation.
|
|
89
|
+
|
|
90
|
+
## Pros and Cons of the Options
|
|
91
|
+
|
|
92
|
+
### Option A
|
|
93
|
+
|
|
94
|
+
* Good, because ...
|
|
95
|
+
* Bad, because ...
|
|
96
|
+
|
|
97
|
+
### Option B
|
|
98
|
+
|
|
99
|
+
* Good, because ...
|
|
100
|
+
* Bad, because ...
|
|
101
|
+
|
|
102
|
+
## Open Questions
|
|
103
|
+
|
|
104
|
+
List unresolved human decisions as unchecked tasks. Accepted ADRs must have no
|
|
105
|
+
unresolved items.
|
|
106
|
+
|
|
107
|
+
Answer them with `bin/adr answer`, which rewrites an item as
|
|
108
|
+
`- [x] <question> — **Answered <date> by <signer>:** <answer>`. A checked item
|
|
109
|
+
is resolved, so it no longer blocks acceptance and stays in the record. Do not
|
|
110
|
+
delete an answered question: the reasoning is what a future reader needs in
|
|
111
|
+
order to re-evaluate the decision.
|
|
112
|
+
|
|
113
|
+
## Related Decisions
|
|
114
|
+
|
|
115
|
+
* None.
|
|
116
|
+
|
|
117
|
+
## References
|
|
118
|
+
|
|
119
|
+
* Add at least one verifiable local or external reference.
|
|
120
|
+
|
|
121
|
+
## Enforcement
|
|
122
|
+
|
|
123
|
+
Delete this optional section when the decision has no machine-checkable surface.
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"forbid_pattern": [],
|
|
128
|
+
"forbid_import": [],
|
|
129
|
+
"require_pattern": []
|
|
130
|
+
}
|
|
131
|
+
```
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: "ADR-NNN"
|
|
3
|
+
title: "Short Imperative Title"
|
|
4
|
+
status: "Proposed"
|
|
5
|
+
date: "YYYY-MM-DD"
|
|
6
|
+
binding: false
|
|
7
|
+
gate: null
|
|
8
|
+
documents_shipped: false
|
|
9
|
+
verified_in: []
|
|
10
|
+
supersedes: []
|
|
11
|
+
superseded_by: null
|
|
12
|
+
format: "nygard"
|
|
13
|
+
topics: []
|
|
14
|
+
aliases: []
|
|
15
|
+
components: []
|
|
16
|
+
symbols: []
|
|
17
|
+
context_scope: "selective"
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
<!-- markdownlint-disable MD025 -->
|
|
21
|
+
|
|
22
|
+
# ADR-NNN Short Imperative Title
|
|
23
|
+
|
|
24
|
+
## Status
|
|
25
|
+
|
|
26
|
+
Proposed, YYYY-MM-DD.
|
|
27
|
+
|
|
28
|
+
## Status History
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
status_history:
|
|
32
|
+
- date: YYYY-MM-DD
|
|
33
|
+
status: Proposed
|
|
34
|
+
changed_by: user@example.com
|
|
35
|
+
reason: Initial proposal
|
|
36
|
+
changed_via: adr-kit
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Context
|
|
40
|
+
|
|
41
|
+
Describe the forces at play in value-neutral language with concrete evidence.
|
|
42
|
+
|
|
43
|
+
## Decision
|
|
44
|
+
|
|
45
|
+
State the response to those forces in active voice: "We will ...".
|
|
46
|
+
|
|
47
|
+
## Decision Contract
|
|
48
|
+
|
|
49
|
+
### Must
|
|
50
|
+
|
|
51
|
+
- State required implementation constraints.
|
|
52
|
+
|
|
53
|
+
### Must Not
|
|
54
|
+
|
|
55
|
+
- State prohibited implementation choices.
|
|
56
|
+
|
|
57
|
+
### Exceptions
|
|
58
|
+
|
|
59
|
+
- State explicit exceptions, or `None`.
|
|
60
|
+
|
|
61
|
+
### Verification
|
|
62
|
+
|
|
63
|
+
- Name the test, command, or source anchor that verifies this decision.
|
|
64
|
+
|
|
65
|
+
## Consequences
|
|
66
|
+
|
|
67
|
+
**Positive:**
|
|
68
|
+
|
|
69
|
+
- Expected benefit.
|
|
70
|
+
|
|
71
|
+
**Negative:**
|
|
72
|
+
|
|
73
|
+
- Accepted cost or risk and its mitigation.
|
|
74
|
+
|
|
75
|
+
## Alternatives Considered
|
|
76
|
+
|
|
77
|
+
adr-kit extension for deterministic completeness:
|
|
78
|
+
|
|
79
|
+
- **Alternative A.** Rejection reason.
|
|
80
|
+
- **Alternative B.** Rejection reason.
|
|
81
|
+
|
|
82
|
+
## Open Questions
|
|
83
|
+
|
|
84
|
+
List unresolved human decisions as unchecked tasks. Accepted ADRs must have no
|
|
85
|
+
unresolved items.
|
|
86
|
+
|
|
87
|
+
Answer them with `bin/adr answer`, which rewrites an item as
|
|
88
|
+
`- [x] <question> — **Answered <date> by <signer>:** <answer>`. A checked item
|
|
89
|
+
is resolved, so it no longer blocks acceptance and stays in the record. Do not
|
|
90
|
+
delete an answered question: the reasoning is what a future reader needs in
|
|
91
|
+
order to re-evaluate the decision.
|
|
92
|
+
|
|
93
|
+
## Related Decisions
|
|
94
|
+
|
|
95
|
+
- None.
|
|
96
|
+
|
|
97
|
+
## References
|
|
98
|
+
|
|
99
|
+
- Add at least one verifiable local or external reference.
|
|
100
|
+
|
|
101
|
+
## Enforcement
|
|
102
|
+
|
|
103
|
+
Delete this optional adr-kit extension when no machine-checkable rule applies.
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"forbid_pattern": [],
|
|
108
|
+
"forbid_import": [],
|
|
109
|
+
"require_pattern": []
|
|
110
|
+
}
|
|
111
|
+
```
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": "ADR Guardian SessionStart hook entry for .claude/settings.json",
|
|
3
|
+
"_note": "Add this entry under hooks.SessionStart[0].hooks[] in the project's .claude/settings.json.",
|
|
4
|
+
"_remove_marker": "adr-guardian-session-start",
|
|
5
|
+
"_wrapper_version": "0.52.0",
|
|
6
|
+
"type": "command",
|
|
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
|
+
"timeout": 10
|
|
9
|
+
}
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# adr-kit pre-commit hook (template; copied to project's .githooks/pre-commit by /adr-kit:install-hooks).
|
|
3
|
+
#
|
|
4
|
+
# Resolves the latest installed adr-kit version from the native Claude Code,
|
|
5
|
+
# Codex, or Copilot CLI plugin caches so upgrades don't require re-running
|
|
6
|
+
# install-hooks. Degrades gracefully when every cache is missing — the hook
|
|
7
|
+
# never blocks a commit because of tooling drift.
|
|
8
|
+
#
|
|
9
|
+
# As of v0.43.0 the per-commit LLM pass is ON BY DEFAULT (ADR-017) and runs on
|
|
10
|
+
# the host agent's own model -- no model is pinned. Each ADR with
|
|
11
|
+
# `"llm_judge": true` gets its own isolated call; they are never batched.
|
|
12
|
+
# The declarative regex/glob Enforcement pass is always-on and free.
|
|
13
|
+
# Nothing is spent until an author sets llm_judge:true on an ADR.
|
|
14
|
+
# Turn it off project-wide: set judge.llm_enabled:false in docs/adr/.adr-kit.json
|
|
15
|
+
# Turn it off per commit: ADR_KIT_NO_LLM=1 git commit ...
|
|
16
|
+
# Record the host client: python bin/adr-judge --set-backend host --host-client <id>
|
|
17
|
+
# On-demand LLM review: /adr-kit:judge (in a Claude Code session)
|
|
18
|
+
#
|
|
19
|
+
# As of v0.17.0 a flock concurrency guard serializes the heavy LLM passes so
|
|
20
|
+
# rapid or parallel commits do not fan out concurrent `claude -p` processes.
|
|
21
|
+
# Under lock contention the declarative pass still runs; LLM passes are suppressed.
|
|
22
|
+
#
|
|
23
|
+
# As of v0.14.1 the hook measures adr-judge wall-clock time and warns (non-blocking)
|
|
24
|
+
# when execution exceeds 5000ms. Uses `date +%s%3N`; falls back to perl on macOS.
|
|
25
|
+
#
|
|
26
|
+
# As of v0.16.0 the hook also runs `adr-suggest` (advisory, on by default as of
|
|
27
|
+
# ADR-035): it detects whether the staged diff introduces a NEW architectural
|
|
28
|
+
# decision not covered by an ADR and prints a one-line nudge. This NEVER blocks
|
|
29
|
+
# the commit.
|
|
30
|
+
# Disable per-commit: ADR_KIT_SUGGEST_DISABLE=1 git commit ...
|
|
31
|
+
# Disable project-wide: set suggest.enabled:false in docs/adr/.adr-kit.json
|
|
32
|
+
#
|
|
33
|
+
# Override ONE ADR's FAIL (audited): a reasoned override downgrades violations
|
|
34
|
+
# of a single named ADR to loud warnings for this commit only. The override is
|
|
35
|
+
# appended to the gitignored log docs/adr/.adr-kit-overrides.jsonl and the
|
|
36
|
+
# commit message SHOULD carry a matching 'ADR-Override: ADR-NNN <reason>'
|
|
37
|
+
# trailer (reconcile later with `adr-judge --audit-overrides`). An empty
|
|
38
|
+
# reason is refused. Violations of other ADRs still block.
|
|
39
|
+
# ADR_KIT_OVERRIDE="ADR-003: hotfix for incident 42" git commit ...
|
|
40
|
+
#
|
|
41
|
+
# Disable LLM pass per commit: ADR_KIT_NO_LLM=1 git commit ...
|
|
42
|
+
# Force LLM pass on per commit: ADR_KIT_LLM=1 git commit ...
|
|
43
|
+
# Force suggest on per commit: ADR_KIT_SUGGEST=1 git commit ...
|
|
44
|
+
# Disable ADR-suggestion nudge: ADR_KIT_SUGGEST_DISABLE=1 git commit ...
|
|
45
|
+
# Disable hook entirely: ADR_KIT_HOOK_DISABLE=1 git commit ...
|
|
46
|
+
# Remove permanently: /adr-kit:install-hooks --uninstall (in a Claude Code session)
|
|
47
|
+
|
|
48
|
+
set -e
|
|
49
|
+
|
|
50
|
+
# Wrapper version stamp (v0.27.0+). The engines below self-upgrade (they
|
|
51
|
+
# resolve the newest plugin cache version per commit), but THIS copied script
|
|
52
|
+
# freezes at install time. adr-guardian compares this stamp against the
|
|
53
|
+
# installed plugin version and nudges /adr-kit:upgrade when the wrapper lags.
|
|
54
|
+
# Maintained by scripts/bump-version.py; do not edit by hand.
|
|
55
|
+
ADR_KIT_WRAPPER_VERSION="0.52.0"
|
|
56
|
+
|
|
57
|
+
if [ "${ADR_KIT_HOOK_DISABLE:-0}" = "1" ]; then
|
|
58
|
+
echo "[adr-kit] hook disabled for this commit (ADR_KIT_HOOK_DISABLE=1)" >&2
|
|
59
|
+
exit 0
|
|
60
|
+
fi
|
|
61
|
+
|
|
62
|
+
# Verify Python 3 is available — adr-judge is a Python 3 script.
|
|
63
|
+
_PYTHON3=""
|
|
64
|
+
for _cmd in python3 python py; do
|
|
65
|
+
if command -v "$_cmd" >/dev/null 2>&1; then
|
|
66
|
+
_ver=$("$_cmd" --version 2>&1 | grep -oE '[0-9]+\.[0-9]+' | head -1)
|
|
67
|
+
_major=$(echo "$_ver" | cut -d. -f1)
|
|
68
|
+
if [ "${_major:-0}" -ge 3 ] 2>/dev/null; then
|
|
69
|
+
_PYTHON3="$_cmd"
|
|
70
|
+
break
|
|
71
|
+
fi
|
|
72
|
+
fi
|
|
73
|
+
done
|
|
74
|
+
|
|
75
|
+
if [ -z "$_PYTHON3" ]; then
|
|
76
|
+
echo "[adr-kit] ERROR: Python 3 not found. adr-judge requires Python 3.10+." >&2
|
|
77
|
+
echo "[adr-kit] Install Python: https://www.python.org/downloads/" >&2
|
|
78
|
+
echo "[adr-kit] On macOS: brew install python3" >&2
|
|
79
|
+
echo "[adr-kit] On Windows: winget install Python.Python.3.12" >&2
|
|
80
|
+
echo "[adr-kit] Skipping ADR check for this commit." >&2
|
|
81
|
+
exit 0
|
|
82
|
+
fi
|
|
83
|
+
|
|
84
|
+
ADR_JUDGE=""
|
|
85
|
+
ADR_SUGGEST=""
|
|
86
|
+
ADR_GRILL_SIGNAL=""
|
|
87
|
+
_plugin_roots=()
|
|
88
|
+
shopt -s nullglob
|
|
89
|
+
_plugin_roots+=(
|
|
90
|
+
"${HOME}/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit"/*
|
|
91
|
+
"${CODEX_HOME:-${HOME}/.codex}/plugins/cache/rvdbreemen-adr-kit-codex/adr-kit"/*
|
|
92
|
+
)
|
|
93
|
+
shopt -u nullglob
|
|
94
|
+
_copilot_root="${COPILOT_HOME:-${HOME}/.copilot}/installed-plugins/rvdbreemen-adr-kit-copilot/adr-kit"
|
|
95
|
+
if [ -d "$_copilot_root" ]; then
|
|
96
|
+
_plugin_roots+=("$_copilot_root")
|
|
97
|
+
fi
|
|
98
|
+
|
|
99
|
+
# A checkout of ADR Kit itself is a candidate too, so the repository is judged
|
|
100
|
+
# by the engine it currently ships rather than by an older installed release.
|
|
101
|
+
# It competes on manifest version like any other root, so an installed plugin
|
|
102
|
+
# still wins when the checkout is behind.
|
|
103
|
+
_self_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
|
|
104
|
+
if [ -n "$_self_root" ] && [ -f "$_self_root/bin/adr-judge" ] &&
|
|
105
|
+
[ -f "$_self_root/.claude-plugin/plugin.json" ]; then
|
|
106
|
+
_plugin_roots+=("$_self_root")
|
|
107
|
+
fi
|
|
108
|
+
|
|
109
|
+
# Select the highest manifest version, independently of which client owns the
|
|
110
|
+
# cache. Python is already required by the engines and keeps JSON parsing
|
|
111
|
+
# robust without jq or shell regexes.
|
|
112
|
+
_best_version="0.0.0"
|
|
113
|
+
for _plugin_root in "${_plugin_roots[@]}"; do
|
|
114
|
+
[ -f "$_plugin_root/bin/adr-judge" ] || continue
|
|
115
|
+
_manifest=""
|
|
116
|
+
for _candidate_manifest in \
|
|
117
|
+
"$_plugin_root/.claude-plugin/plugin.json" \
|
|
118
|
+
"$_plugin_root/.codex-plugin/plugin.json" \
|
|
119
|
+
"$_plugin_root/plugin.json"; do
|
|
120
|
+
if [ -f "$_candidate_manifest" ]; then
|
|
121
|
+
_manifest="$_candidate_manifest"
|
|
122
|
+
break
|
|
123
|
+
fi
|
|
124
|
+
done
|
|
125
|
+
[ -n "$_manifest" ] || continue
|
|
126
|
+
_candidate_version=$(
|
|
127
|
+
"$_PYTHON3" -c \
|
|
128
|
+
'import json,sys; print(json.load(open(sys.argv[1], encoding="utf-8")).get("version", "0.0.0"))' \
|
|
129
|
+
"$_manifest" 2>/dev/null
|
|
130
|
+
) || _candidate_version="0.0.0"
|
|
131
|
+
_newest=$(printf '%s\n%s\n' "$_best_version" "$_candidate_version" | sort -V | tail -1)
|
|
132
|
+
if [ "$_newest" = "$_candidate_version" ]; then
|
|
133
|
+
_best_version="$_candidate_version"
|
|
134
|
+
ADR_JUDGE="$_plugin_root/bin/adr-judge"
|
|
135
|
+
if [ -f "$_plugin_root/bin/adr-suggest" ]; then
|
|
136
|
+
ADR_SUGGEST="$_plugin_root/bin/adr-suggest"
|
|
137
|
+
else
|
|
138
|
+
ADR_SUGGEST=""
|
|
139
|
+
fi
|
|
140
|
+
if [ -f "$_plugin_root/bin/adr-grill-signal" ]; then
|
|
141
|
+
ADR_GRILL_SIGNAL="$_plugin_root/bin/adr-grill-signal"
|
|
142
|
+
else
|
|
143
|
+
ADR_GRILL_SIGNAL=""
|
|
144
|
+
fi
|
|
145
|
+
fi
|
|
146
|
+
done
|
|
147
|
+
|
|
148
|
+
if [ -z "$ADR_JUDGE" ] || [ ! -f "$ADR_JUDGE" ]; then
|
|
149
|
+
echo "[adr-kit] adr-judge binary not found in plugin cache; skipping pre-commit ADR check." >&2
|
|
150
|
+
echo "[adr-kit] Re-install ADR Kit for Claude Code, Codex, or Copilot CLI." >&2
|
|
151
|
+
exit 0
|
|
152
|
+
fi
|
|
153
|
+
|
|
154
|
+
ROOT=$(git rev-parse --show-toplevel)
|
|
155
|
+
# Skip when there are no staged changes — cheaper than buffering the full diff just to test emptiness.
|
|
156
|
+
if [ -z "$(git diff --cached --name-only)" ]; then
|
|
157
|
+
exit 0
|
|
158
|
+
fi
|
|
159
|
+
|
|
160
|
+
# Concurrency guard: serialize the heavy LLM passes so rapid or parallel commits
|
|
161
|
+
# don't fan out concurrent `claude -p` processes. We take a non-blocking advisory
|
|
162
|
+
# lock; if another adr-judge already holds it, we keep the cheap declarative pass
|
|
163
|
+
# but suppress the LLM passes for THIS commit (via ADR_KIT_NO_LLM). The lockfile
|
|
164
|
+
# lives under .git/ so it's never committed. flock is absent on bare Windows
|
|
165
|
+
# cmd.exe; there we degrade to no-lock (same behaviour as before).
|
|
166
|
+
_NO_LLM_OVERRIDE=""
|
|
167
|
+
if command -v flock >/dev/null 2>&1; then
|
|
168
|
+
exec 9>"$ROOT/.git/adr-kit-judge.lock" 2>/dev/null || true
|
|
169
|
+
if ! flock -n 9 2>/dev/null; then
|
|
170
|
+
echo "[adr-kit] another ADR judge is running; declarative-only for this commit (LLM gate skipped)." >&2
|
|
171
|
+
_NO_LLM_OVERRIDE=1
|
|
172
|
+
fi
|
|
173
|
+
fi
|
|
174
|
+
|
|
175
|
+
# Portable millisecond timestamp: `date +%s%3N` works on Linux/Git-Bash/WSL.
|
|
176
|
+
# On macOS the GNU %3N extension is absent, so we fall back to perl.
|
|
177
|
+
_ms_now() {
|
|
178
|
+
local t
|
|
179
|
+
t=$(date +%s%3N 2>/dev/null)
|
|
180
|
+
# Reject empty or non-numeric results (macOS BSD date returns literal "%3N").
|
|
181
|
+
case "$t" in
|
|
182
|
+
''|*[!0-9]*) t=$(perl -e 'print int(time()*1000)') ;;
|
|
183
|
+
esac
|
|
184
|
+
printf '%s' "$t"
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
# Performance budget: judge.pre_commit_timeout_ms.
|
|
188
|
+
#
|
|
189
|
+
# The budget is a project decision and lives in the same docs/adr/.adr-kit.json
|
|
190
|
+
# the judge is pointed at below. This wrapper is a repo-tracked file a hand can
|
|
191
|
+
# edit, so the value is validated rather than trusted -- the shape
|
|
192
|
+
# hooks/adr_pr_guard.py applies to runner_timeout_sec.
|
|
193
|
+
#
|
|
194
|
+
# absent -> 5000 ms, the schema default
|
|
195
|
+
# 0 -> warning off, matching bin/adr-judge's own reading of 0
|
|
196
|
+
# 1..3600000 -> used as given
|
|
197
|
+
# anything else -> refused, named on stderr, 5000 ms
|
|
198
|
+
#
|
|
199
|
+
# The ceiling is an hour rather than something tighter because
|
|
200
|
+
# judge.llm_timeout_seconds defaults to 120 s and bounds ONE call, with one call
|
|
201
|
+
# per llm_judge:true ADR. A ten-ADR project has a legitimate twenty-minute
|
|
202
|
+
# commit; a lower ceiling would refuse a correct configuration.
|
|
203
|
+
_ADR_KIT_MAX_BUDGET_MS=3600000
|
|
204
|
+
_BUDGET_READ=$(
|
|
205
|
+
"$_PYTHON3" -c 'import json,sys
|
|
206
|
+
state, budget, warn = "absent", "5000", "1"
|
|
207
|
+
try:
|
|
208
|
+
judge = json.load(open(sys.argv[1], encoding="utf-8"))["judge"]
|
|
209
|
+
except Exception:
|
|
210
|
+
judge = {}
|
|
211
|
+
if isinstance(judge, dict):
|
|
212
|
+
if judge.get("warn_on_exceed", True) is False:
|
|
213
|
+
warn = "0"
|
|
214
|
+
if "pre_commit_timeout_ms" in judge:
|
|
215
|
+
value = judge["pre_commit_timeout_ms"]
|
|
216
|
+
if (isinstance(value, bool) or not isinstance(value, int)
|
|
217
|
+
or not 0 <= value <= int(sys.argv[2])):
|
|
218
|
+
state = "invalid"
|
|
219
|
+
else:
|
|
220
|
+
state, budget = "ok", str(value)
|
|
221
|
+
print(state, budget, warn)' "$ROOT/docs/adr/.adr-kit.json" "$_ADR_KIT_MAX_BUDGET_MS" 2>/dev/null
|
|
222
|
+
) || _BUDGET_READ=""
|
|
223
|
+
_BUDGET_STATE=$(printf '%s' "$_BUDGET_READ" | cut -d' ' -f1)
|
|
224
|
+
_BUDGET_MS=$(printf '%s' "$_BUDGET_READ" | cut -d' ' -f2)
|
|
225
|
+
_WARN_ON_EXCEED=$(printf '%s' "$_BUDGET_READ" | cut -d' ' -f3)
|
|
226
|
+
case "$_BUDGET_STATE" in
|
|
227
|
+
ok|absent) ;;
|
|
228
|
+
invalid)
|
|
229
|
+
echo "[adr-kit] WARN: judge.pre_commit_timeout_ms is not an integer from 0 to ${_ADR_KIT_MAX_BUDGET_MS}; using ${_BUDGET_MS}ms." >&2
|
|
230
|
+
;;
|
|
231
|
+
*) _BUDGET_MS=5000; _WARN_ON_EXCEED=1 ;;
|
|
232
|
+
esac
|
|
233
|
+
|
|
234
|
+
# Run the judge.
|
|
235
|
+
# - declarative pass: always-on; fast, regex-only, exits non-zero on violation
|
|
236
|
+
# - LLM pass (default on): one isolated call per llm_judge:true ADR, on the
|
|
237
|
+
# host client the installer recorded (ADR-036);
|
|
238
|
+
# disabled by ADR_KIT_NO_LLM=1 or judge.llm_enabled:false;
|
|
239
|
+
# suppressed under lock contention (_NO_LLM_OVERRIDE)
|
|
240
|
+
# Exit codes:
|
|
241
|
+
# 0 no violations (advisory entries are non-blocking)
|
|
242
|
+
# 1 at least one violation (declarative or LLM)
|
|
243
|
+
# 2 config or runtime error
|
|
244
|
+
_LLM_FLAG=""
|
|
245
|
+
[ "${ADR_KIT_LLM:-0}" = "1" ] && _LLM_FLAG="--llm"
|
|
246
|
+
_T0=$(_ms_now)
|
|
247
|
+
# `set -e` is lifted around the judge call. Without this, a non-zero exit from
|
|
248
|
+
# the command substitution would abort the hook immediately, so every line
|
|
249
|
+
# below -- including the violation report -- would never run and the commit
|
|
250
|
+
# would be blocked with no explanation at all.
|
|
251
|
+
set +e
|
|
252
|
+
# The lock override forces the LLM pass off; otherwise the operator's own
|
|
253
|
+
# ADR_KIT_NO_LLM stands. Hard-coding 0 as the fallback silently discarded the
|
|
254
|
+
# opt-out this hook advertises in its own header and in its slow-commit
|
|
255
|
+
# warning, which matters now that a configured backend makes that pass cost
|
|
256
|
+
# one model call per in-scope ADR.
|
|
257
|
+
ADR_OUT=$(git diff --cached --unified=0 | ADR_KIT_NO_LLM="${_NO_LLM_OVERRIDE:-${ADR_KIT_NO_LLM:-0}}" "$ADR_JUDGE" --diff - --adr-dir "$ROOT/docs/adr/" --repo-root "$ROOT" --snapshot staged $_LLM_FLAG 2>&1)
|
|
258
|
+
ADR_EXIT=$?
|
|
259
|
+
set -e
|
|
260
|
+
_T1=$(_ms_now)
|
|
261
|
+
# Suppress per-ADR llm_judge advisory lines: they repeat once per ADR with llm_judge:true
|
|
262
|
+
# and become very noisy on projects with many ADRs. Violations and the summary line
|
|
263
|
+
# (e.g. "[adr-judge] OK 0 violations, 57 advisory") are preserved.
|
|
264
|
+
printf '%s\n' "$ADR_OUT" | grep -avE "^ ADVISORY |^[[:space:]]+ADR has llm_judge:true" >&2 || true
|
|
265
|
+
# Performance warning (non-blocking): alert when adr-judge exceeds the budget
|
|
266
|
+
# judge.pre_commit_timeout_ms declares. 0 turns it off; so does warn_on_exceed:false.
|
|
267
|
+
_ELAPSED=$(( _T1 - _T0 ))
|
|
268
|
+
if [ "$_WARN_ON_EXCEED" = "1" ] && [ "${_BUDGET_MS:-0}" -gt 0 ] 2>/dev/null && [ "$_ELAPSED" -gt "$_BUDGET_MS" ] 2>/dev/null; then
|
|
269
|
+
echo "[adr-kit] WARN: pre-commit hook took ${_ELAPSED}ms (threshold: ${_BUDGET_MS}ms from judge.pre_commit_timeout_ms). Consider ADR_KIT_NO_LLM=1 for faster commits." >&2
|
|
270
|
+
fi
|
|
271
|
+
# Exit 2 means the judge could not run at all (bad config, engine mismatch).
|
|
272
|
+
# Name that explicitly: a blocked commit with only tool output is hard to read.
|
|
273
|
+
if [ "$ADR_EXIT" -eq 2 ]; then
|
|
274
|
+
echo "[adr-kit] adr-judge could not run (exit 2: config or runtime error)." >&2
|
|
275
|
+
echo "[adr-kit] Engine: $ADR_JUDGE (manifest version $_best_version)." >&2
|
|
276
|
+
echo "[adr-kit] Commit with ADR_KIT_HOOK_DISABLE=1 to bypass this check." >&2
|
|
277
|
+
fi
|
|
278
|
+
[ "$ADR_EXIT" -ne 0 ] && exit "$ADR_EXIT"
|
|
279
|
+
|
|
280
|
+
# --- Generated-index freshness (advisory) --------------------------------------
|
|
281
|
+
# The lifecycle CLI regenerates README.md, ADR-INDEX.md and ADR-INDEX.json inside
|
|
282
|
+
# its own transaction, so anything written through `bin/adr` keeps them true. An
|
|
283
|
+
# ADR edited by hand -- or written straight to disk by a coding agent -- does not,
|
|
284
|
+
# and a stale index is exactly the artefact every other tool reads first.
|
|
285
|
+
#
|
|
286
|
+
# Advisory, not blocking, and the reason is not politeness: `adr-index --check`
|
|
287
|
+
# reads the WORKTREE, while this commit is the staged snapshot. On a partial
|
|
288
|
+
# commit those differ, so a block here could refuse a correct commit over a file
|
|
289
|
+
# the author deliberately left unstaged. CI checks out the commit itself, where
|
|
290
|
+
# worktree and commit are the same thing, and blocks there (adr-index-check.yml).
|
|
291
|
+
if [ -n "$ADR_JUDGE" ] && git diff --cached --name-only | grep -qE '(^|/)docs/adr/ADR-[0-9]+.*\.md$'; then
|
|
292
|
+
_ADR_INDEX="$(dirname "$ADR_JUDGE")/adr-index"
|
|
293
|
+
if [ -f "$_ADR_INDEX" ]; then
|
|
294
|
+
if ! "$_PYTHON3" "$_ADR_INDEX" "$ROOT/docs/adr" --check >/dev/null 2>&1; then
|
|
295
|
+
echo "[adr-kit] WARN: the generated ADR indexes are stale in your worktree." >&2
|
|
296
|
+
echo "[adr-kit] Run: $_PYTHON3 $_ADR_INDEX $ROOT/docs/adr then stage the result." >&2
|
|
297
|
+
echo "[adr-kit] CI blocks on this; the hook only warns (it reads the worktree, not the index)." >&2
|
|
298
|
+
fi
|
|
299
|
+
fi
|
|
300
|
+
fi
|
|
301
|
+
|
|
302
|
+
# Bounded, index-only ADR grilling advisories. This is a single fail-open
|
|
303
|
+
# subprocess: no readiness sweep, per-ADR subprocess loop, model, network, or
|
|
304
|
+
# provider credential. adr-judge above remains the only local blocking path.
|
|
305
|
+
if [ -n "$ADR_GRILL_SIGNAL" ] && [ -f "$ADR_GRILL_SIGNAL" ]; then
|
|
306
|
+
GRILL_OUT=$(
|
|
307
|
+
"$_PYTHON3" "$ADR_GRILL_SIGNAL" \
|
|
308
|
+
--staged --repo-root "$ROOT" --shell posix --format human 2>/dev/null || true
|
|
309
|
+
)
|
|
310
|
+
printf '%s\n' "$GRILL_OUT" | grep -aE "^\[adr-grill\] (STRONG|ADVISORY) " >&2 || true
|
|
311
|
+
fi
|
|
312
|
+
|
|
313
|
+
# --- Advisory ADR-suggestion pass (adr-suggest, v0.16.0+; on by default) ------
|
|
314
|
+
# Distinct from adr-judge above: adr-judge ENFORCES existing ADRs and can block
|
|
315
|
+
# the commit. adr-suggest only DETECTS whether the diff introduces a NEW
|
|
316
|
+
# architectural decision not yet covered by any ADR, and prints a one-line
|
|
317
|
+
# nudge. It NEVER blocks — its exit status is swallowed with `|| true`.
|
|
318
|
+
#
|
|
319
|
+
# On by default since ADR-035, on the same terms ADR-017 set for the judge.
|
|
320
|
+
# Switch it off with ADR_KIT_SUGGEST_DISABLE=1 (per-commit) or
|
|
321
|
+
# suggest.enabled:false in .adr-kit.json (per-project); adr-suggest honours both
|
|
322
|
+
# itself, so the switch holds on every path that runs it, not only this hook.
|
|
323
|
+
# It also self-skips when no backend resolves or the diff carries no code.
|
|
324
|
+
# Suppressed under lock contention.
|
|
325
|
+
if [ "${ADR_KIT_SUGGEST_DISABLE:-0}" != "1" ] && [ "${_NO_LLM_OVERRIDE:-0}" != "1" ] && [ -n "$ADR_SUGGEST" ] && [ -x "$ADR_SUGGEST" ]; then
|
|
326
|
+
# Derive the suggest bound from the same budget the judge warning uses, so the
|
|
327
|
+
# advisory pass cannot outlast what this hook declares it may cost. Floor of
|
|
328
|
+
# 10 s: a budget of 0 disables the WARN, it does not mean "no time at all".
|
|
329
|
+
_SUGGEST_TIMEOUT_S=$(( ${_BUDGET_MS:-5000} / 1000 ))
|
|
330
|
+
[ "$_SUGGEST_TIMEOUT_S" -lt 10 ] && _SUGGEST_TIMEOUT_S=10
|
|
331
|
+
SUGGEST_OUT=$(git diff --cached --unified=0 | "$ADR_SUGGEST" --diff - --adr-dir "$ROOT/docs/adr/" --llm-timeout "$_SUGGEST_TIMEOUT_S" 2>&1 || true)
|
|
332
|
+
# Only surface the actual suggestion lines; the "(skipped: ...)" / "LLM
|
|
333
|
+
# unavailable" notes are noise on commits that don't introduce a decision.
|
|
334
|
+
printf '%s\n' "$SUGGEST_OUT" | grep -aE "^\[adr-suggest\] (This change| )" >&2 || true
|
|
335
|
+
fi
|
|
336
|
+
|
|
337
|
+
exit 0
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Whole-codebase ADR audit.
|
|
2
|
+
#
|
|
3
|
+
# The per-diff gates answer "does this change violate a decision?". None of them
|
|
4
|
+
# answers "does the code as it stands today obey the decisions as they stand
|
|
5
|
+
# today", because a rule added after a file was written has never been applied to
|
|
6
|
+
# that file. This workflow asks that question on a cadence.
|
|
7
|
+
#
|
|
8
|
+
# Mechanically it is a diff against the empty tree, so every line reads as added
|
|
9
|
+
# and forbid rules reach the whole repository. That diff is large by
|
|
10
|
+
# construction, which is what the separate budget is for.
|
|
11
|
+
#
|
|
12
|
+
# Report-only by design: it opens or updates one issue and never fails the run.
|
|
13
|
+
# A weekly sweep that turns the default branch red for a pre-existing violation
|
|
14
|
+
# teaches people to ignore it.
|
|
15
|
+
name: adr-audit
|
|
16
|
+
|
|
17
|
+
on:
|
|
18
|
+
schedule:
|
|
19
|
+
- cron: "0 6 * * 1"
|
|
20
|
+
workflow_dispatch:
|
|
21
|
+
|
|
22
|
+
permissions:
|
|
23
|
+
contents: read
|
|
24
|
+
issues: write
|
|
25
|
+
|
|
26
|
+
jobs:
|
|
27
|
+
audit:
|
|
28
|
+
name: whole-codebase audit
|
|
29
|
+
runs-on: ubuntu-latest
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
with:
|
|
33
|
+
fetch-depth: 0
|
|
34
|
+
|
|
35
|
+
- uses: actions/setup-python@v5
|
|
36
|
+
with:
|
|
37
|
+
python-version: '3.11'
|
|
38
|
+
|
|
39
|
+
- name: Audit the decisions and the code
|
|
40
|
+
id: audit
|
|
41
|
+
run: |
|
|
42
|
+
set +e
|
|
43
|
+
python bin/adr-audit --whole-codebase --gates all --format text \
|
|
44
|
+
> "$RUNNER_TEMP/audit.txt" 2>&1
|
|
45
|
+
echo "exit_code=$?" >> "$GITHUB_OUTPUT"
|
|
46
|
+
set -e
|
|
47
|
+
cat "$RUNNER_TEMP/audit.txt"
|
|
48
|
+
|
|
49
|
+
- name: Explain the verdict
|
|
50
|
+
run: |
|
|
51
|
+
case "${{ steps.audit.outputs.exit_code }}" in
|
|
52
|
+
0) echo "On course." ;;
|
|
53
|
+
1) echo "The code violates an Accepted ADR. Owner: whoever wrote the code." ;;
|
|
54
|
+
3) echo "The ADR set fails its own gates. Owner: whoever wrote the records." ;;
|
|
55
|
+
4) echo "Both: the code violates an ADR and the records fail their gates." ;;
|
|
56
|
+
2) echo "The audit could not run. Owner: whoever installed it." ;;
|
|
57
|
+
*) echo "Unrecognised exit code." ;;
|
|
58
|
+
esac
|