@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.
Files changed (129) hide show
  1. package/.claude-plugin/plugin.json +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +850 -0
  4. package/bin/adr +1552 -0
  5. package/bin/adr-audit +454 -0
  6. package/bin/adr-context +584 -0
  7. package/bin/adr-discover +546 -0
  8. package/bin/adr-doctor +166 -0
  9. package/bin/adr-generate-scripts +421 -0
  10. package/bin/adr-grill-signal +131 -0
  11. package/bin/adr-guardian +1263 -0
  12. package/bin/adr-index +199 -0
  13. package/bin/adr-judge +2832 -0
  14. package/bin/adr-judge-precommit +87 -0
  15. package/bin/adr-lint +2087 -0
  16. package/bin/adr-mcp +1093 -0
  17. package/bin/adr-migrate +644 -0
  18. package/bin/adr-quality +275 -0
  19. package/bin/adr-readiness +211 -0
  20. package/bin/adr-readiness-ci +111 -0
  21. package/bin/adr-related +401 -0
  22. package/bin/adr-renumber +254 -0
  23. package/bin/adr-retire +467 -0
  24. package/bin/adr-settings +399 -0
  25. package/bin/adr-status +797 -0
  26. package/bin/adr-suggest +803 -0
  27. package/bin/adr-watch +674 -0
  28. package/bin/adr_catalog.py +536 -0
  29. package/bin/adr_config.py +280 -0
  30. package/bin/adr_doctor_checks.py +407 -0
  31. package/bin/adr_doctor_core.py +342 -0
  32. package/bin/adr_doctor_models.py +186 -0
  33. package/bin/adr_doctor_probes.py +216 -0
  34. package/bin/adr_format.py +786 -0
  35. package/bin/adr_grill_signal.py +123 -0
  36. package/bin/adr_guardian_queue.py +218 -0
  37. package/bin/adr_history_scan.py +278 -0
  38. package/bin/adr_index_core.py +443 -0
  39. package/bin/adr_llm.py +333 -0
  40. package/bin/adr_llm_judge_migration.py +314 -0
  41. package/bin/adr_quality_core.py +674 -0
  42. package/bin/adr_query.py +678 -0
  43. package/bin/adr_readiness.py +442 -0
  44. package/bin/adr_readiness_ci.py +123 -0
  45. package/bin/adr_regex.py +165 -0
  46. package/bin/adr_regex_worker.py +30 -0
  47. package/bin/adr_retrieval_health.py +385 -0
  48. package/bin/adr_schema.py +448 -0
  49. package/bin/adr_state.py +172 -0
  50. package/bin/bump-version +71 -0
  51. package/clients/workflows.json +229 -0
  52. package/hooks/__init__.py +1 -0
  53. package/hooks/adapters/__init__.py +13 -0
  54. package/hooks/adapters/claude.py +27 -0
  55. package/hooks/adapters/codex.py +26 -0
  56. package/hooks/adapters/copilot.py +11 -0
  57. package/hooks/adr-hook.py +128 -0
  58. package/hooks/adr_hook_core.py +843 -0
  59. package/hooks/adr_pr_guard.py +367 -0
  60. package/instructions/ADR-guide.md +48 -0
  61. package/instructions/adr.coding.md +82 -0
  62. package/instructions/adr.review.md +182 -0
  63. package/opencode/plugin.ts +451 -0
  64. package/package.json +41 -0
  65. package/schemas/adr-context-probes.schema.json +56 -0
  66. package/schemas/adr-enforcement.schema.json +57 -0
  67. package/schemas/adr-frontmatter.schema.json +144 -0
  68. package/schemas/adr-index.schema.json +276 -0
  69. package/schemas/adr-kit-config.schema.json +371 -0
  70. package/schemas/adr-readiness.schema.json +41 -0
  71. package/schemas/client-capabilities.schema.json +503 -0
  72. package/schemas/client-certification.schema.json +101 -0
  73. package/schemas/doctor-output.schema.json +92 -0
  74. package/schemas/marketplace.json.schema.json +70 -0
  75. package/schemas/plugin.json.schema.json +67 -0
  76. package/scripts/adr_settings.py +239 -0
  77. package/scripts/benchmark-adr-grilling.py +323 -0
  78. package/scripts/benchmark-client-generation.py +178 -0
  79. package/scripts/build-client-adapters.py +139 -0
  80. package/scripts/bump-version.py +304 -0
  81. package/scripts/check-branch-sync.py +243 -0
  82. package/scripts/check-release-version.py +81 -0
  83. package/scripts/client_certification.py +153 -0
  84. package/scripts/client_evidence.py +280 -0
  85. package/scripts/client_generation.py +288 -0
  86. package/scripts/client_generation_artifacts.py +351 -0
  87. package/scripts/client_generation_model.py +173 -0
  88. package/scripts/client_generation_state.py +260 -0
  89. package/scripts/client_support_matrix.py +360 -0
  90. package/scripts/install-agent-envs.py +300 -0
  91. package/scripts/probe-client-events.py +183 -0
  92. package/scripts/project_setup.py +379 -0
  93. package/scripts/refresh-otgw-corpus.py +219 -0
  94. package/scripts/settings.py +81 -0
  95. package/scripts/setup-project.py +205 -0
  96. package/scripts/sync-agent-plugins.py +17 -0
  97. package/scripts/version_sites.py +377 -0
  98. package/skills/adr/SKILL.md +780 -0
  99. package/skills/audit/SKILL.md +103 -0
  100. package/skills/context/SKILL.md +77 -0
  101. package/skills/grill/SKILL.md +84 -0
  102. package/skills/grill/agents/openai.yaml +4 -0
  103. package/skills/guardian/SKILL.md +316 -0
  104. package/skills/init/SKILL.md +499 -0
  105. package/skills/install-hooks/SKILL.md +154 -0
  106. package/skills/judge/SKILL.md +168 -0
  107. package/skills/lint/SKILL.md +321 -0
  108. package/skills/migrate/SKILL.md +313 -0
  109. package/skills/related/SKILL.md +62 -0
  110. package/skills/retire/SKILL.md +41 -0
  111. package/skills/review/SKILL.md +167 -0
  112. package/skills/settings/SKILL.md +73 -0
  113. package/skills/setup/SKILL.md +128 -0
  114. package/skills/supersede/SKILL.md +136 -0
  115. package/skills/upgrade/SKILL.md +273 -0
  116. package/templates/adr-kit-guide.md +354 -0
  117. package/templates/adr-template.canonical.md +115 -0
  118. package/templates/adr-template.madr.md +131 -0
  119. package/templates/adr-template.md +131 -0
  120. package/templates/adr-template.nygard.md +111 -0
  121. package/templates/cc-settings/guardian-hook-entry.json +9 -0
  122. package/templates/githooks/pre-commit +337 -0
  123. package/templates/github-workflows/adr-audit.yml +58 -0
  124. package/templates/github-workflows/adr-guardian-audit.yml +133 -0
  125. package/templates/github-workflows/adr-index-check.yml +30 -0
  126. package/templates/github-workflows/adr-judge.yml +31 -0
  127. package/templates/github-workflows/adr-readiness.yml +18 -0
  128. package/templates/validate_adr_template.py +38 -0
  129. 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