@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,154 +1,154 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: install-hooks
|
|
3
|
-
description: "Install or remove ADR Kit's deterministic pre-commit gate. Use for ADR hooks, pre-commit enforcement, or uninstalling the owned git hook."
|
|
4
|
-
argument-hint: "[--uninstall]"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
allowed-tools: [Read, Write, Edit, Bash]
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# adr-kit install-hooks
|
|
10
|
-
|
|
11
|
-
This is the **hooks** mode of `/adr-kit:setup` (spec R19: one entry point,
|
|
12
|
-
four modes). Invoked directly or via `/adr-kit:setup hooks`, the procedure
|
|
13
|
-
is identical -- this file owns it.
|
|
14
|
-
|
|
15
|
-
Use `$ARGUMENTS` only for `--uninstall`; empty means install. Reject all other
|
|
16
|
-
arguments.
|
|
17
|
-
|
|
18
|
-
You install or uninstall the adr-kit pre-commit hook in the project the user is currently in (`pwd` should be the project root).
|
|
19
|
-
|
|
20
|
-
## Default behaviour: install
|
|
21
|
-
|
|
22
|
-
### Step 1 — Resolve the plugin's hook template
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
26
|
-
TEMPLATE="$ADR_KIT/templates/githooks/pre-commit"
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
If `$TEMPLATE` does not exist or is empty, exit with an error: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
|
|
30
|
-
|
|
31
|
-
### Step 2 — Detect existing hooks
|
|
32
|
-
|
|
33
|
-
Three cases:
|
|
34
|
-
|
|
35
|
-
- **No `.githooks/pre-commit`.** Mkdir `.githooks/`, copy the template, `chmod +x`, set `core.hooksPath`. Done.
|
|
36
|
-
- **Existing `.githooks/pre-commit` is byte-identical to the template.** No-op. Tell the user it's already installed.
|
|
37
|
-
- **Existing `.githooks/pre-commit` differs.** Read both. Show the user the existing content (truncated to first 30 lines). Ask:
|
|
38
|
-
- `prepend adr-kit before existing` — write a wrapper script that calls adr-kit then `exec`s the original. Save the original as `.githooks/pre-commit.adr-kit-saved`.
|
|
39
|
-
- `replace` — overwrite. Save the old hook as `.githooks/pre-commit.backup-<timestamp>` for safety.
|
|
40
|
-
- `abort` — do nothing.
|
|
41
|
-
Apply the user's choice.
|
|
42
|
-
|
|
43
|
-
### Step 3 — Activate
|
|
44
|
-
|
|
45
|
-
Run `git config core.hooksPath .githooks`. Confirm with `git config --get core.hooksPath`. If the project already has `core.hooksPath` set to a different directory, do NOT overwrite — tell the user, ask whether to change the config or to symlink the hook into the existing hooks dir.
|
|
46
|
-
|
|
47
|
-
### Step 4 — Confirm
|
|
48
|
-
|
|
49
|
-
Print:
|
|
50
|
-
|
|
51
|
-
```
|
|
52
|
-
Pre-commit ADR judge installed.
|
|
53
|
-
- hook: .githooks/pre-commit (mode 755)
|
|
54
|
-
- core.hooksPath: .githooks
|
|
55
|
-
- disable a single commit: ADR_KIT_HOOK_DISABLE=1 git commit ...
|
|
56
|
-
- remove permanently: /adr-kit:install-hooks --uninstall
|
|
57
|
-
- LLM pass is opt-in (off by default). Enable per-project: judge.llm_enabled:true in docs/adr/.adr-kit.json. Enable one commit: ADR_KIT_LLM=1 git commit ...
|
|
58
|
-
- ADR-suggest is opt-in too: suggest.enabled:true, or ADR_KIT_SUGGEST=1 for one commit.
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Uninstall behaviour: `--uninstall`
|
|
62
|
-
|
|
63
|
-
When invoked as `/adr-kit:install-hooks --uninstall`:
|
|
64
|
-
|
|
65
|
-
1. Read `.githooks/pre-commit`. Verify it is the adr-kit hook (look for the line `# adr-kit pre-commit hook` near the top). If it is NOT the adr-kit hook, refuse — tell the user the hook in place isn't ours and we won't touch it.
|
|
66
|
-
2. Three paths:
|
|
67
|
-
- **No saved original** (`.githooks/pre-commit.adr-kit-saved` does not exist). Remove `.githooks/pre-commit`. If `.githooks/` is now empty, remove it too. Run `git config --unset core.hooksPath`.
|
|
68
|
-
- **Saved original exists.** Restore: rename `.githooks/pre-commit.adr-kit-saved` → `.githooks/pre-commit`. Leave `core.hooksPath` set to `.githooks`.
|
|
69
|
-
- **`.githooks/pre-commit.backup-<timestamp>` exists** (from a prior `replace` install). Tell the user the backup is there and ask whether to restore that instead. Apply choice.
|
|
70
|
-
3. Confirm with one line: `Pre-commit ADR judge uninstalled. (restored prior hook | removed .githooks/ | unset core.hooksPath)`
|
|
71
|
-
|
|
72
|
-
## Guardian (SessionStart) hook — project-scoped install
|
|
73
|
-
|
|
74
|
-
The ADR Guardian has **two registration paths** (spec §7):
|
|
75
|
-
|
|
76
|
-
- **Plugin-level (default, frictionless):** The adr-kit plugin declares a `SessionStart` hook in its manifest. It auto-registers in every Claude Code session when the plugin is enabled globally, and self-guards (exits silently when no `docs/adr/` with ADRs is present). This is the recommended path.
|
|
77
|
-
- **Project-scoped (explicit):** Adds the guardian's `SessionStart` entry directly to the project's `.claude/settings.json`. Contained to this project only. Use when the user wants explicit per-project control or does not enable the plugin globally.
|
|
78
|
-
|
|
79
|
-
### Adding the project-scoped guardian hook
|
|
80
|
-
|
|
81
|
-
When the user asks to add the guardian hook to the project's `.claude/settings.json`:
|
|
82
|
-
|
|
83
|
-
1. Read `.claude/settings.json` (create it as `{}` if missing).
|
|
84
|
-
2. Check if `hooks.SessionStart` already contains an entry whose `command` contains the string `adr-guardian`. If yes: print "Already installed" and stop.
|
|
85
|
-
3. If no SessionStart array exists: create it. Parse the JSON structurally — never do text substitution on a JSON file.
|
|
86
|
-
4. Append the following hook object to `hooks.SessionStart[0].hooks` (create the array path if absent):
|
|
87
|
-
|
|
88
|
-
```json
|
|
89
|
-
{
|
|
90
|
-
"type": "command",
|
|
91
|
-
"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",
|
|
92
|
-
"timeout": 10
|
|
93
|
-
}
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
5. Write the updated JSON back. The existing `SessionStart` hooks (if any) are **preserved byte-for-byte** — only the new entry is appended.
|
|
97
|
-
6. Confirm: "Guardian hook added to .claude/settings.json. It will fire at the next session start."
|
|
98
|
-
|
|
99
|
-
### Removing the project-scoped guardian hook
|
|
100
|
-
|
|
101
|
-
When the user asks to remove the guardian hook from `.claude/settings.json`:
|
|
102
|
-
|
|
103
|
-
1. Read `.claude/settings.json`. Parse as JSON.
|
|
104
|
-
2. Find entries in `hooks.SessionStart[*].hooks[*]` whose `command` contains `adr-guardian`. If none found: print "Guardian hook not found in .claude/settings.json" and stop.
|
|
105
|
-
3. Remove exactly those entries. Leave all sibling hooks untouched.
|
|
106
|
-
4. If the containing `hooks` array becomes empty after removal, remove the empty array (but keep the parent `SessionStart` entry if other entries exist in other groups).
|
|
107
|
-
5. Write the updated JSON back.
|
|
108
|
-
6. Confirm: "Guardian hook removed from .claude/settings.json."
|
|
109
|
-
|
|
110
|
-
**Safety invariant:** Never remove or modify any hook entry that does not contain `adr-guardian` in its `command`. This is the cozempic lesson — a remove that also clobbers unrelated hooks is worse than not removing at all.
|
|
111
|
-
|
|
112
|
-
### Adding .adr-kit-state.json to .gitignore
|
|
113
|
-
|
|
114
|
-
After adding the guardian hook (project-scoped or as part of `/adr-kit:init`):
|
|
115
|
-
|
|
116
|
-
```bash
|
|
117
|
-
echo "docs/adr/.adr-kit-state.json" >> .gitignore
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
Verify it is not already present first (idempotent). The state file is per-machine and must never be committed.
|
|
121
|
-
|
|
122
|
-
## CI gates — offer the shipped workflow templates
|
|
123
|
-
|
|
124
|
-
The git hook judges one commit. Two gates that a hook cannot cover ship as
|
|
125
|
-
copyable workflows in `templates/github-workflows/`; offer them, do not install
|
|
126
|
-
them silently, because a workflow file is the project's business:
|
|
127
|
-
|
|
128
|
-
- **`adr-judge.yml`** — judges the whole branch on every pull request. This is
|
|
129
|
-
what the reviewer is actually being asked to accept, and it uses the CI-sized
|
|
130
|
-
diff budget so raising it never weakens the commit-time gate.
|
|
131
|
-
- **`adr-readiness.yml`** — refuses to merge implementation that is linked to a
|
|
132
|
-
Proposed decision nobody accepted.
|
|
133
|
-
- **`adr-guardian-audit.yml`** — the weekly staleness sweep, reported into one
|
|
134
|
-
tracking issue.
|
|
135
|
-
- **`adr-index-check.yml`** — fails when the generated indexes no longer match
|
|
136
|
-
the ADRs. The commit hook can only warn about this, because it reads the
|
|
137
|
-
worktree while the commit is the staged snapshot; CI checks out the commit
|
|
138
|
-
itself, so it is the only place the block is honest.
|
|
139
|
-
|
|
140
|
-
Copy on request into `.github/workflows/`, and tell the user the checkout must
|
|
141
|
-
use `fetch-depth: 0` or the diff has only one side.
|
|
142
|
-
|
|
143
|
-
Note for Claude Code users: the branch is also judged *before* the pull request
|
|
144
|
-
exists, by the pre-tool guard on `gh pr create`. The workflow remains worth
|
|
145
|
-
installing anyway - it covers pushes from a laptop, a different client, and
|
|
146
|
-
anyone not working through an agent at all.
|
|
147
|
-
|
|
148
|
-
## Constraints
|
|
149
|
-
|
|
150
|
-
- **Never silently overwrite a pre-existing user hook.** Always detect, show, ask.
|
|
151
|
-
- **Set `core.hooksPath` only when needed.** If the user already has it pointing at a custom dir, propose a symlink rather than redirecting their config.
|
|
152
|
-
- **Idempotent in both directions.** Re-running install when already installed is a no-op. Re-running uninstall when nothing is installed is a no-op (with a warning).
|
|
153
|
-
- **`chmod +x`** the hook after writing — without the executable bit, git silently ignores it.
|
|
154
|
-
- **Do not commit the hook.** The hook lives in `.githooks/`, which the project may or may not have in `.gitignore`. Don't add it to git here; the user decides whether to track it.
|
|
1
|
+
---
|
|
2
|
+
name: install-hooks
|
|
3
|
+
description: "Install or remove ADR Kit's deterministic pre-commit gate. Use for ADR hooks, pre-commit enforcement, or uninstalling the owned git hook."
|
|
4
|
+
argument-hint: "[--uninstall]"
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
allowed-tools: [Read, Write, Edit, Bash]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# adr-kit install-hooks
|
|
10
|
+
|
|
11
|
+
This is the **hooks** mode of `/adr-kit:setup` (spec R19: one entry point,
|
|
12
|
+
four modes). Invoked directly or via `/adr-kit:setup hooks`, the procedure
|
|
13
|
+
is identical -- this file owns it.
|
|
14
|
+
|
|
15
|
+
Use `$ARGUMENTS` only for `--uninstall`; empty means install. Reject all other
|
|
16
|
+
arguments.
|
|
17
|
+
|
|
18
|
+
You install or uninstall the adr-kit pre-commit hook in the project the user is currently in (`pwd` should be the project root).
|
|
19
|
+
|
|
20
|
+
## Default behaviour: install
|
|
21
|
+
|
|
22
|
+
### Step 1 — Resolve the plugin's hook template
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
26
|
+
TEMPLATE="$ADR_KIT/templates/githooks/pre-commit"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
If `$TEMPLATE` does not exist or is empty, exit with an error: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
|
|
30
|
+
|
|
31
|
+
### Step 2 — Detect existing hooks
|
|
32
|
+
|
|
33
|
+
Three cases:
|
|
34
|
+
|
|
35
|
+
- **No `.githooks/pre-commit`.** Mkdir `.githooks/`, copy the template, `chmod +x`, set `core.hooksPath`. Done.
|
|
36
|
+
- **Existing `.githooks/pre-commit` is byte-identical to the template.** No-op. Tell the user it's already installed.
|
|
37
|
+
- **Existing `.githooks/pre-commit` differs.** Read both. Show the user the existing content (truncated to first 30 lines). Ask:
|
|
38
|
+
- `prepend adr-kit before existing` — write a wrapper script that calls adr-kit then `exec`s the original. Save the original as `.githooks/pre-commit.adr-kit-saved`.
|
|
39
|
+
- `replace` — overwrite. Save the old hook as `.githooks/pre-commit.backup-<timestamp>` for safety.
|
|
40
|
+
- `abort` — do nothing.
|
|
41
|
+
Apply the user's choice.
|
|
42
|
+
|
|
43
|
+
### Step 3 — Activate
|
|
44
|
+
|
|
45
|
+
Run `git config core.hooksPath .githooks`. Confirm with `git config --get core.hooksPath`. If the project already has `core.hooksPath` set to a different directory, do NOT overwrite — tell the user, ask whether to change the config or to symlink the hook into the existing hooks dir.
|
|
46
|
+
|
|
47
|
+
### Step 4 — Confirm
|
|
48
|
+
|
|
49
|
+
Print:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
Pre-commit ADR judge installed.
|
|
53
|
+
- hook: .githooks/pre-commit (mode 755)
|
|
54
|
+
- core.hooksPath: .githooks
|
|
55
|
+
- disable a single commit: ADR_KIT_HOOK_DISABLE=1 git commit ...
|
|
56
|
+
- remove permanently: /adr-kit:install-hooks --uninstall
|
|
57
|
+
- LLM pass is opt-in (off by default). Enable per-project: judge.llm_enabled:true in docs/adr/.adr-kit.json. Enable one commit: ADR_KIT_LLM=1 git commit ...
|
|
58
|
+
- ADR-suggest is opt-in too: suggest.enabled:true, or ADR_KIT_SUGGEST=1 for one commit.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Uninstall behaviour: `--uninstall`
|
|
62
|
+
|
|
63
|
+
When invoked as `/adr-kit:install-hooks --uninstall`:
|
|
64
|
+
|
|
65
|
+
1. Read `.githooks/pre-commit`. Verify it is the adr-kit hook (look for the line `# adr-kit pre-commit hook` near the top). If it is NOT the adr-kit hook, refuse — tell the user the hook in place isn't ours and we won't touch it.
|
|
66
|
+
2. Three paths:
|
|
67
|
+
- **No saved original** (`.githooks/pre-commit.adr-kit-saved` does not exist). Remove `.githooks/pre-commit`. If `.githooks/` is now empty, remove it too. Run `git config --unset core.hooksPath`.
|
|
68
|
+
- **Saved original exists.** Restore: rename `.githooks/pre-commit.adr-kit-saved` → `.githooks/pre-commit`. Leave `core.hooksPath` set to `.githooks`.
|
|
69
|
+
- **`.githooks/pre-commit.backup-<timestamp>` exists** (from a prior `replace` install). Tell the user the backup is there and ask whether to restore that instead. Apply choice.
|
|
70
|
+
3. Confirm with one line: `Pre-commit ADR judge uninstalled. (restored prior hook | removed .githooks/ | unset core.hooksPath)`
|
|
71
|
+
|
|
72
|
+
## Guardian (SessionStart) hook — project-scoped install
|
|
73
|
+
|
|
74
|
+
The ADR Guardian has **two registration paths** (spec §7):
|
|
75
|
+
|
|
76
|
+
- **Plugin-level (default, frictionless):** The adr-kit plugin declares a `SessionStart` hook in its manifest. It auto-registers in every Claude Code session when the plugin is enabled globally, and self-guards (exits silently when no `docs/adr/` with ADRs is present). This is the recommended path.
|
|
77
|
+
- **Project-scoped (explicit):** Adds the guardian's `SessionStart` entry directly to the project's `.claude/settings.json`. Contained to this project only. Use when the user wants explicit per-project control or does not enable the plugin globally.
|
|
78
|
+
|
|
79
|
+
### Adding the project-scoped guardian hook
|
|
80
|
+
|
|
81
|
+
When the user asks to add the guardian hook to the project's `.claude/settings.json`:
|
|
82
|
+
|
|
83
|
+
1. Read `.claude/settings.json` (create it as `{}` if missing).
|
|
84
|
+
2. Check if `hooks.SessionStart` already contains an entry whose `command` contains the string `adr-guardian`. If yes: print "Already installed" and stop.
|
|
85
|
+
3. If no SessionStart array exists: create it. Parse the JSON structurally — never do text substitution on a JSON file.
|
|
86
|
+
4. Append the following hook object to `hooks.SessionStart[0].hooks` (create the array path if absent):
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"type": "command",
|
|
91
|
+
"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",
|
|
92
|
+
"timeout": 10
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
5. Write the updated JSON back. The existing `SessionStart` hooks (if any) are **preserved byte-for-byte** — only the new entry is appended.
|
|
97
|
+
6. Confirm: "Guardian hook added to .claude/settings.json. It will fire at the next session start."
|
|
98
|
+
|
|
99
|
+
### Removing the project-scoped guardian hook
|
|
100
|
+
|
|
101
|
+
When the user asks to remove the guardian hook from `.claude/settings.json`:
|
|
102
|
+
|
|
103
|
+
1. Read `.claude/settings.json`. Parse as JSON.
|
|
104
|
+
2. Find entries in `hooks.SessionStart[*].hooks[*]` whose `command` contains `adr-guardian`. If none found: print "Guardian hook not found in .claude/settings.json" and stop.
|
|
105
|
+
3. Remove exactly those entries. Leave all sibling hooks untouched.
|
|
106
|
+
4. If the containing `hooks` array becomes empty after removal, remove the empty array (but keep the parent `SessionStart` entry if other entries exist in other groups).
|
|
107
|
+
5. Write the updated JSON back.
|
|
108
|
+
6. Confirm: "Guardian hook removed from .claude/settings.json."
|
|
109
|
+
|
|
110
|
+
**Safety invariant:** Never remove or modify any hook entry that does not contain `adr-guardian` in its `command`. This is the cozempic lesson — a remove that also clobbers unrelated hooks is worse than not removing at all.
|
|
111
|
+
|
|
112
|
+
### Adding .adr-kit-state.json to .gitignore
|
|
113
|
+
|
|
114
|
+
After adding the guardian hook (project-scoped or as part of `/adr-kit:init`):
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
echo "docs/adr/.adr-kit-state.json" >> .gitignore
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Verify it is not already present first (idempotent). The state file is per-machine and must never be committed.
|
|
121
|
+
|
|
122
|
+
## CI gates — offer the shipped workflow templates
|
|
123
|
+
|
|
124
|
+
The git hook judges one commit. Two gates that a hook cannot cover ship as
|
|
125
|
+
copyable workflows in `templates/github-workflows/`; offer them, do not install
|
|
126
|
+
them silently, because a workflow file is the project's business:
|
|
127
|
+
|
|
128
|
+
- **`adr-judge.yml`** — judges the whole branch on every pull request. This is
|
|
129
|
+
what the reviewer is actually being asked to accept, and it uses the CI-sized
|
|
130
|
+
diff budget so raising it never weakens the commit-time gate.
|
|
131
|
+
- **`adr-readiness.yml`** — refuses to merge implementation that is linked to a
|
|
132
|
+
Proposed decision nobody accepted.
|
|
133
|
+
- **`adr-guardian-audit.yml`** — the weekly staleness sweep, reported into one
|
|
134
|
+
tracking issue.
|
|
135
|
+
- **`adr-index-check.yml`** — fails when the generated indexes no longer match
|
|
136
|
+
the ADRs. The commit hook can only warn about this, because it reads the
|
|
137
|
+
worktree while the commit is the staged snapshot; CI checks out the commit
|
|
138
|
+
itself, so it is the only place the block is honest.
|
|
139
|
+
|
|
140
|
+
Copy on request into `.github/workflows/`, and tell the user the checkout must
|
|
141
|
+
use `fetch-depth: 0` or the diff has only one side.
|
|
142
|
+
|
|
143
|
+
Note for Claude Code users: the branch is also judged *before* the pull request
|
|
144
|
+
exists, by the pre-tool guard on `gh pr create`. The workflow remains worth
|
|
145
|
+
installing anyway - it covers pushes from a laptop, a different client, and
|
|
146
|
+
anyone not working through an agent at all.
|
|
147
|
+
|
|
148
|
+
## Constraints
|
|
149
|
+
|
|
150
|
+
- **Never silently overwrite a pre-existing user hook.** Always detect, show, ask.
|
|
151
|
+
- **Set `core.hooksPath` only when needed.** If the user already has it pointing at a custom dir, propose a symlink rather than redirecting their config.
|
|
152
|
+
- **Idempotent in both directions.** Re-running install when already installed is a no-op. Re-running uninstall when nothing is installed is a no-op (with a warning).
|
|
153
|
+
- **`chmod +x`** the hook after writing — without the executable bit, git silently ignores it.
|
|
154
|
+
- **Do not commit the hook.** The hook lives in `.githooks/`, which the project may or may not have in `.gitignore`. Don't add it to git here; the user decides whether to track it.
|