@rvdbreemen/adr-kit-opencode 0.52.0 → 0.52.2

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 (82) hide show
  1. package/.claude-plugin/plugin.json +29 -29
  2. package/README.md +861 -850
  3. package/bin/adr +0 -0
  4. package/bin/adr-audit +0 -0
  5. package/bin/adr-context +0 -0
  6. package/bin/adr-discover +0 -0
  7. package/bin/adr-doctor +0 -0
  8. package/bin/adr-generate-scripts +0 -0
  9. package/bin/adr-grill-signal +0 -0
  10. package/bin/adr-guardian +0 -0
  11. package/bin/adr-index +0 -0
  12. package/bin/adr-judge +0 -0
  13. package/bin/adr-judge-precommit +0 -0
  14. package/bin/adr-lint +0 -0
  15. package/bin/adr-mcp +0 -0
  16. package/bin/adr-migrate +0 -0
  17. package/bin/adr-quality +0 -0
  18. package/bin/adr-readiness +0 -0
  19. package/bin/adr-readiness-ci +0 -0
  20. package/bin/adr-related +0 -0
  21. package/bin/adr-renumber +254 -254
  22. package/bin/adr-retire +0 -0
  23. package/bin/adr-settings +0 -0
  24. package/bin/adr-status +0 -0
  25. package/bin/adr-suggest +0 -0
  26. package/bin/adr-watch +0 -0
  27. package/bin/bump-version +0 -0
  28. package/clients/workflows.json +229 -229
  29. package/hooks/__init__.py +1 -1
  30. package/hooks/adapters/__init__.py +13 -13
  31. package/hooks/adapters/claude.py +27 -27
  32. package/hooks/adapters/codex.py +26 -26
  33. package/hooks/adapters/copilot.py +11 -11
  34. package/hooks/adr-hook.py +128 -128
  35. package/hooks/adr_hook_core.py +843 -843
  36. package/hooks/adr_pr_guard.py +367 -367
  37. package/instructions/ADR-guide.md +48 -48
  38. package/instructions/adr.coding.md +82 -82
  39. package/instructions/adr.review.md +182 -182
  40. package/opencode/plugin.ts +1 -4
  41. package/package.json +5 -2
  42. package/schemas/adr-context-probes.schema.json +56 -56
  43. package/schemas/adr-enforcement.schema.json +57 -57
  44. package/schemas/adr-frontmatter.schema.json +144 -144
  45. package/schemas/adr-index.schema.json +276 -276
  46. package/schemas/adr-kit-config.schema.json +371 -371
  47. package/schemas/adr-readiness.schema.json +41 -41
  48. package/schemas/client-capabilities.schema.json +503 -503
  49. package/schemas/client-certification.schema.json +101 -101
  50. package/schemas/doctor-output.schema.json +92 -92
  51. package/skills/adr/SKILL.md +780 -780
  52. package/skills/audit/SKILL.md +103 -103
  53. package/skills/context/SKILL.md +77 -77
  54. package/skills/grill/SKILL.md +84 -84
  55. package/skills/grill/agents/openai.yaml +4 -4
  56. package/skills/guardian/SKILL.md +316 -316
  57. package/skills/init/SKILL.md +499 -499
  58. package/skills/install-hooks/SKILL.md +154 -154
  59. package/skills/judge/SKILL.md +168 -168
  60. package/skills/lint/SKILL.md +321 -321
  61. package/skills/migrate/SKILL.md +313 -313
  62. package/skills/related/SKILL.md +62 -62
  63. package/skills/retire/SKILL.md +41 -41
  64. package/skills/review/SKILL.md +167 -167
  65. package/skills/settings/SKILL.md +73 -73
  66. package/skills/setup/SKILL.md +128 -128
  67. package/skills/supersede/SKILL.md +136 -136
  68. package/skills/upgrade/SKILL.md +273 -273
  69. package/templates/adr-kit-guide.md +354 -354
  70. package/templates/adr-template.canonical.md +115 -115
  71. package/templates/adr-template.madr.md +131 -131
  72. package/templates/adr-template.md +131 -131
  73. package/templates/adr-template.nygard.md +111 -111
  74. package/templates/cc-settings/guardian-hook-entry.json +9 -9
  75. package/templates/githooks/pre-commit +1 -1
  76. package/templates/github-workflows/adr-audit.yml +58 -58
  77. package/templates/github-workflows/adr-guardian-audit.yml +133 -133
  78. package/templates/github-workflows/adr-index-check.yml +30 -30
  79. package/templates/github-workflows/adr-judge.yml +31 -31
  80. package/templates/github-workflows/adr-readiness.yml +18 -18
  81. package/templates/validate_adr_template.py +38 -38
  82. package/templates/validate_adr_template.sh +74 -74
@@ -1,73 +1,73 @@
1
- ---
2
- name: settings
3
- description: "Show and change adr-kit settings: LLM backend, judge-by-default, hooks, the status-history signer, guardian cadence. Use to inspect where a value comes from or to change one."
4
- argument-hint: "[key] [value]"
5
- disable-model-invocation: true
6
- allowed-tools: [Read, Bash]
7
- ---
8
-
9
- # adr-kit settings
10
-
11
- `$ARGUMENTS` may name a key to show, or a `key=value` to set. Empty shows
12
- everything with its provenance.
13
-
14
- One place for every knob. Before this existed a user changed settings in three
15
- disjoint places and one text editor, and two things were simply unreachable:
16
- `judge.llm_enabled` could be switched on by a shipped writer but never off, and
17
- the status-history signer had nowhere to live that anyone would find.
18
-
19
- ## Show
20
-
21
- ```bash
22
- python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr
23
- ```
24
-
25
- Every row carries its **provenance** — project, machine-local, default, or an
26
- environment override. That is the column that answers the question a settings
27
- screen exists for: not "what is this set to" but "why is it set to that".
28
-
29
- Add `--all` for every key the schema knows, `--format json` for a machine
30
- reading, `--list` for just the key names.
31
-
32
- ## Change
33
-
34
- ```bash
35
- python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --set judge.llm_enabled=false
36
- python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --unset guardian.enabled
37
- ```
38
-
39
- Values are typed against the schema before they land: `--set guardian.enabled=maybe`
40
- is refused rather than stored as a truthy string, and a refused write leaves no
41
- file behind.
42
-
43
- ## Which file a setting lands in, and why it matters
44
-
45
- | Scope | File | Contains |
46
- |---|---|---|
47
- | project | `docs/adr/.adr-kit.json` (tracked) | team decisions: judge behaviour, guardian cadence, retrieval limits |
48
- | machine-local | `docs/adr/.adr-kit.local.json` (gitignored) | personal or machine facts: `lifecycle.signer`, `judge.host_client` |
49
-
50
- The command routes each write itself and says where it landed. The split is not
51
- bookkeeping: a signer written to the tracked file would put one person's name on
52
- every teammate's acceptance, which is a false attribution rather than a missing
53
- one. And a host client is a fact about one machine, not a decision about the
54
- project.
55
-
56
- ## Settings that live elsewhere on purpose
57
-
58
- - **The signer** can also be set through `bin/adr signer --set "User: <name>"`,
59
- which additionally offers `git config user.name` as a proposal and can audit
60
- existing history for entries with no human actor.
61
- - **Hook installation** is `/adr-kit:install-hooks`, because installing a hook
62
- writes files outside the config and needs its own consent.
63
- - **The LLM backend** can also be set through `adr-judge --set-backend`, which
64
- validates the choice against the live registry.
65
-
66
- This command shows all of them; where another surface does more than write a
67
- value, it says so rather than duplicating the work.
68
-
69
- ## What is never shown
70
-
71
- A credential is reported as a boolean about the environment — whether a key is
72
- present, never the key. A settings screen needs to know that the environment is
73
- configured; it does not need the secret to say so.
1
+ ---
2
+ name: settings
3
+ description: "Show and change adr-kit settings: LLM backend, judge-by-default, hooks, the status-history signer, guardian cadence. Use to inspect where a value comes from or to change one."
4
+ argument-hint: "[key] [value]"
5
+ disable-model-invocation: true
6
+ allowed-tools: [Read, Bash]
7
+ ---
8
+
9
+ # adr-kit settings
10
+
11
+ `$ARGUMENTS` may name a key to show, or a `key=value` to set. Empty shows
12
+ everything with its provenance.
13
+
14
+ One place for every knob. Before this existed a user changed settings in three
15
+ disjoint places and one text editor, and two things were simply unreachable:
16
+ `judge.llm_enabled` could be switched on by a shipped writer but never off, and
17
+ the status-history signer had nowhere to live that anyone would find.
18
+
19
+ ## Show
20
+
21
+ ```bash
22
+ python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr
23
+ ```
24
+
25
+ Every row carries its **provenance** — project, machine-local, default, or an
26
+ environment override. That is the column that answers the question a settings
27
+ screen exists for: not "what is this set to" but "why is it set to that".
28
+
29
+ Add `--all` for every key the schema knows, `--format json` for a machine
30
+ reading, `--list` for just the key names.
31
+
32
+ ## Change
33
+
34
+ ```bash
35
+ python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --set judge.llm_enabled=false
36
+ python3 "$ADR_KIT/bin/adr-settings" --adr-dir docs/adr --unset guardian.enabled
37
+ ```
38
+
39
+ Values are typed against the schema before they land: `--set guardian.enabled=maybe`
40
+ is refused rather than stored as a truthy string, and a refused write leaves no
41
+ file behind.
42
+
43
+ ## Which file a setting lands in, and why it matters
44
+
45
+ | Scope | File | Contains |
46
+ |---|---|---|
47
+ | project | `docs/adr/.adr-kit.json` (tracked) | team decisions: judge behaviour, guardian cadence, retrieval limits |
48
+ | machine-local | `docs/adr/.adr-kit.local.json` (gitignored) | personal or machine facts: `lifecycle.signer`, `judge.host_client` |
49
+
50
+ The command routes each write itself and says where it landed. The split is not
51
+ bookkeeping: a signer written to the tracked file would put one person's name on
52
+ every teammate's acceptance, which is a false attribution rather than a missing
53
+ one. And a host client is a fact about one machine, not a decision about the
54
+ project.
55
+
56
+ ## Settings that live elsewhere on purpose
57
+
58
+ - **The signer** can also be set through `bin/adr signer --set "User: <name>"`,
59
+ which additionally offers `git config user.name` as a proposal and can audit
60
+ existing history for entries with no human actor.
61
+ - **Hook installation** is `/adr-kit:install-hooks`, because installing a hook
62
+ writes files outside the config and needs its own consent.
63
+ - **The LLM backend** can also be set through `adr-judge --set-backend`, which
64
+ validates the choice against the live registry.
65
+
66
+ This command shows all of them; where another surface does more than write a
67
+ value, it says so rather than duplicating the work.
68
+
69
+ ## What is never shown
70
+
71
+ A credential is reported as a boolean about the environment — whether a key is
72
+ present, never the key. A settings screen needs to know that the environment is
73
+ configured; it does not need the secret to say so.
@@ -1,128 +1,128 @@
1
- ---
2
- name: setup
3
- description: "The one entry point for installing ADR Kit in a project (R19). Modes: register (default), adopt (audit + propose ADRs, /adr-kit:init), hooks (/adr-kit:install-hooks), upgrade (/adr-kit:upgrade)."
4
- argument-hint: "[adopt|hooks|upgrade]"
5
- disable-model-invocation: true
6
- allowed-tools: [Read, Write, Edit, Bash]
7
- ---
8
-
9
- # adr-kit setup
10
-
11
- Setting up ADR Kit is one deterministic act (spec R19) with four modes. An
12
- empty `$ARGUMENTS` runs the default **register** mode below. A mode name
13
- routes to the procedure that owns it -- follow that skill file and nothing
14
- else; each is a mode of this entry point, not a separate product:
15
-
16
- | `$ARGUMENTS` | Mode | Procedure |
17
- |---|---|---|
18
- | *(empty)* | **register** -- write the managed guidance layout | this file, below |
19
- | `adopt` | audit the codebase and propose ADRs, then register | `skills/init/SKILL.md` (`/adr-kit:init`) |
20
- | `hooks` | install or remove the pre-commit gate only | `skills/install-hooks/SKILL.md` (`/adr-kit:install-hooks`) |
21
- | `upgrade` | refresh copied artifacts, migrate a v0.11 footprint | `skills/upgrade/SKILL.md` (`/adr-kit:upgrade`) |
22
-
23
- Reject any other argument instead of guessing a mode.
24
-
25
- You are running the one-time project setup for the adr-kit plugin (register
26
- mode). Your job is to:
27
-
28
- 1. Write the project's instruction layout with `scripts/setup-project.py`, which owns every file in it.
29
- 2. Leave everything outside its managed markers byte-exact.
30
-
31
- This is the lightweight counterpart to `/adr-kit:init`. Use `setup` when the user has an existing project, already understands their architecture, and just wants the kit registered. Use `init` when the user wants the kit to also audit the codebase and propose ADRs.
32
-
33
- ## Backwards compatibility (v0.11 footprint)
34
-
35
- A project that ran v0.11 `/adr-kit:setup` has an inline `## ADR Kit Rules` section in `CLAUDE.md`. This skill detects that footprint and leaves it untouched — telling the user to run `/adr-kit:upgrade` to migrate to the v0.12 marker-bracketed stub + external guide layout. **Do not silently rewrite a v0.11 footprint.** The upgrade skill exists for that explicit migration.
36
-
37
- ## Steps
38
-
39
- 1. **Resolve the plugin path.**
40
-
41
- ```bash
42
- ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
43
- ```
44
-
45
- If empty, abort: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
46
-
47
- 2. **Check for a v0.11 footprint first.** Read `CLAUDE.md` if it exists. If it
48
- carries an inline `## ADR Kit Rules` section, stop and tell the user:
49
- `Detected v0.11 ADR Kit Rules section in CLAUDE.md at line <N>. Run
50
- /adr-kit:upgrade to migrate. /adr-kit:setup is leaving the v0.11 footprint
51
- untouched.` Exit without changes. A v0.11 footprint requires an explicit
52
- migration; this command never performs one silently.
53
-
54
- 3. **Run the writer.** Do not hand-write the instruction block or the guide.
55
- `scripts/setup-project.py` owns the layout, and it is the only thing that
56
- knows all of it: `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
57
- and `.adr-kit/ADR-guide.md`. Prose in this skill describing an older layout is
58
- how the three clients drifted apart in the first place -- Codex and Copilot
59
- delegated here while this file still wrote a guide under `.claude/` and a
60
- stub block that `scripts/project_setup.py` classifies as legacy.
61
-
62
- Preview first, then apply:
63
-
64
- ```bash
65
- python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root . --dry-run
66
- python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root .
67
- ```
68
-
69
- The command is idempotent: re-running it on a current project changes
70
- nothing. It writes only inside its managed markers, so user content around
71
- them stays byte-exact, and it never touches `.adr-kit/ADR-guide.local.md`.
72
-
73
- `--client` also accepts `codex-cli` and `github-copilot-cli`, and `--clients`
74
- takes a comma-separated list when a project uses more than one.
75
-
76
- 4. **Report what it did.** The command prints one line per change. Relay them,
77
- and say plainly when there was nothing to do -- a no-op is the expected
78
- outcome of a second run, not a failure.
79
-
80
- ## Constraints
81
-
82
- - **Two coordinated writes.** v0.12 setup writes both the stub AND the guide file. Either-or is incomplete.
83
- - **Never silently migrate v0.11.** A v0.11 footprint requires explicit `/adr-kit:upgrade`. Leave v0.11 alone here.
84
- - **Idempotent.** Re-running on a v0.12 project where everything is current is a no-op.
85
- - **Read before write.** Preview with `--dry-run` before applying; the writer reads every file it touches.
86
- - **Preserve surrounding content.** Only the marker-bracketed stub and the guide file may be touched. Everything else stays byte-exact.
87
- - **No em dashes** in any text the skill writes (per adr-kit style).
88
-
89
- ## When the user is in the wrong directory
90
-
91
- If `pwd` lacks all of `CLAUDE.md`, `.git/`, and a recognisable project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `platformio.ini`, etc.), stop and ask: `I do not see a project root here (no CLAUDE.md, no .git, no manifest). Confirm you want to set up adr-kit in <pwd>?` Do not silently create files in unexpected locations.
92
-
93
- ## Cross-references
94
-
95
- - `/adr-kit:setup adopt` (alias `/adr-kit:init`) — full bootstrap including audit and hook installation.
96
- - `/adr-kit:setup upgrade` (alias `/adr-kit:upgrade`) — migrate v0.11 → v0.12 footprint without re-auditing.
97
- - `/adr-kit:setup hooks` (alias `/adr-kit:install-hooks`) — install the pre-commit hook independently.
98
-
99
- ## Step 4c — The signer: propose, never assume
100
-
101
- Every lifecycle command writes a Status History entry naming who decided, and it
102
- refuses to sign on the user's behalf. That refusal is right, and it should not be
103
- the user's first experience of the tool.
104
-
105
- ```bash
106
- python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
107
- ```
108
-
109
- Read-only: it finds candidates and writes nothing. It looks at the signed-in
110
- GitHub account (`gh api user`, when the CLI is available) and at
111
- `git config user.name`, ranks them, and shows each with its source — a proposal
112
- the user cannot trace is one they cannot judge, and this value lands in an
113
- immutable history.
114
-
115
- - **Candidates found** — show them and ask which to adopt, or let the user type a
116
- different name. Then write it:
117
- `python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
118
- - **Already configured** — say so and move on. Do not overwrite it.
119
- - **Nothing found** — the GitHub CLI is absent or signed out and git names nobody
120
- usable. Ask for the name outright rather than guessing.
121
-
122
- **Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
123
- `runner`, a bare `user`: those are configured values that name a machine, and
124
- R8 asks for evidence of which *human* accepted a decision.
125
-
126
- The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
127
- because writing one person's name into the tracked config would sign every
128
- teammate's acceptances. Each machine, container and CI runner needs its own.
1
+ ---
2
+ name: setup
3
+ description: "The one entry point for installing ADR Kit in a project (R19). Modes: register (default), adopt (audit + propose ADRs, /adr-kit:init), hooks (/adr-kit:install-hooks), upgrade (/adr-kit:upgrade)."
4
+ argument-hint: "[adopt|hooks|upgrade]"
5
+ disable-model-invocation: true
6
+ allowed-tools: [Read, Write, Edit, Bash]
7
+ ---
8
+
9
+ # adr-kit setup
10
+
11
+ Setting up ADR Kit is one deterministic act (spec R19) with four modes. An
12
+ empty `$ARGUMENTS` runs the default **register** mode below. A mode name
13
+ routes to the procedure that owns it -- follow that skill file and nothing
14
+ else; each is a mode of this entry point, not a separate product:
15
+
16
+ | `$ARGUMENTS` | Mode | Procedure |
17
+ |---|---|---|
18
+ | *(empty)* | **register** -- write the managed guidance layout | this file, below |
19
+ | `adopt` | audit the codebase and propose ADRs, then register | `skills/init/SKILL.md` (`/adr-kit:init`) |
20
+ | `hooks` | install or remove the pre-commit gate only | `skills/install-hooks/SKILL.md` (`/adr-kit:install-hooks`) |
21
+ | `upgrade` | refresh copied artifacts, migrate a v0.11 footprint | `skills/upgrade/SKILL.md` (`/adr-kit:upgrade`) |
22
+
23
+ Reject any other argument instead of guessing a mode.
24
+
25
+ You are running the one-time project setup for the adr-kit plugin (register
26
+ mode). Your job is to:
27
+
28
+ 1. Write the project's instruction layout with `scripts/setup-project.py`, which owns every file in it.
29
+ 2. Leave everything outside its managed markers byte-exact.
30
+
31
+ This is the lightweight counterpart to `/adr-kit:init`. Use `setup` when the user has an existing project, already understands their architecture, and just wants the kit registered. Use `init` when the user wants the kit to also audit the codebase and propose ADRs.
32
+
33
+ ## Backwards compatibility (v0.11 footprint)
34
+
35
+ A project that ran v0.11 `/adr-kit:setup` has an inline `## ADR Kit Rules` section in `CLAUDE.md`. This skill detects that footprint and leaves it untouched — telling the user to run `/adr-kit:upgrade` to migrate to the v0.12 marker-bracketed stub + external guide layout. **Do not silently rewrite a v0.11 footprint.** The upgrade skill exists for that explicit migration.
36
+
37
+ ## Steps
38
+
39
+ 1. **Resolve the plugin path.**
40
+
41
+ ```bash
42
+ ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
43
+ ```
44
+
45
+ If empty, abort: the plugin install is broken; tell the user to reinstall via `/plugin install adr-kit@rvdbreemen-adr-kit`.
46
+
47
+ 2. **Check for a v0.11 footprint first.** Read `CLAUDE.md` if it exists. If it
48
+ carries an inline `## ADR Kit Rules` section, stop and tell the user:
49
+ `Detected v0.11 ADR Kit Rules section in CLAUDE.md at line <N>. Run
50
+ /adr-kit:upgrade to migrate. /adr-kit:setup is leaving the v0.11 footprint
51
+ untouched.` Exit without changes. A v0.11 footprint requires an explicit
52
+ migration; this command never performs one silently.
53
+
54
+ 3. **Run the writer.** Do not hand-write the instruction block or the guide.
55
+ `scripts/setup-project.py` owns the layout, and it is the only thing that
56
+ knows all of it: `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
57
+ and `.adr-kit/ADR-guide.md`. Prose in this skill describing an older layout is
58
+ how the three clients drifted apart in the first place -- Codex and Copilot
59
+ delegated here while this file still wrote a guide under `.claude/` and a
60
+ stub block that `scripts/project_setup.py` classifies as legacy.
61
+
62
+ Preview first, then apply:
63
+
64
+ ```bash
65
+ python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root . --dry-run
66
+ python3 "$ADR_KIT/scripts/setup-project.py" --client claude-code-cli --project-root .
67
+ ```
68
+
69
+ The command is idempotent: re-running it on a current project changes
70
+ nothing. It writes only inside its managed markers, so user content around
71
+ them stays byte-exact, and it never touches `.adr-kit/ADR-guide.local.md`.
72
+
73
+ `--client` also accepts `codex-cli` and `github-copilot-cli`, and `--clients`
74
+ takes a comma-separated list when a project uses more than one.
75
+
76
+ 4. **Report what it did.** The command prints one line per change. Relay them,
77
+ and say plainly when there was nothing to do -- a no-op is the expected
78
+ outcome of a second run, not a failure.
79
+
80
+ ## Constraints
81
+
82
+ - **Two coordinated writes.** v0.12 setup writes both the stub AND the guide file. Either-or is incomplete.
83
+ - **Never silently migrate v0.11.** A v0.11 footprint requires explicit `/adr-kit:upgrade`. Leave v0.11 alone here.
84
+ - **Idempotent.** Re-running on a v0.12 project where everything is current is a no-op.
85
+ - **Read before write.** Preview with `--dry-run` before applying; the writer reads every file it touches.
86
+ - **Preserve surrounding content.** Only the marker-bracketed stub and the guide file may be touched. Everything else stays byte-exact.
87
+ - **No em dashes** in any text the skill writes (per adr-kit style).
88
+
89
+ ## When the user is in the wrong directory
90
+
91
+ If `pwd` lacks all of `CLAUDE.md`, `.git/`, and a recognisable project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `platformio.ini`, etc.), stop and ask: `I do not see a project root here (no CLAUDE.md, no .git, no manifest). Confirm you want to set up adr-kit in <pwd>?` Do not silently create files in unexpected locations.
92
+
93
+ ## Cross-references
94
+
95
+ - `/adr-kit:setup adopt` (alias `/adr-kit:init`) — full bootstrap including audit and hook installation.
96
+ - `/adr-kit:setup upgrade` (alias `/adr-kit:upgrade`) — migrate v0.11 → v0.12 footprint without re-auditing.
97
+ - `/adr-kit:setup hooks` (alias `/adr-kit:install-hooks`) — install the pre-commit hook independently.
98
+
99
+ ## Step 4c — The signer: propose, never assume
100
+
101
+ Every lifecycle command writes a Status History entry naming who decided, and it
102
+ refuses to sign on the user's behalf. That refusal is right, and it should not be
103
+ the user's first experience of the tool.
104
+
105
+ ```bash
106
+ python3 "$ADR_KIT/bin/adr" signer --suggest --adr-dir docs/adr
107
+ ```
108
+
109
+ Read-only: it finds candidates and writes nothing. It looks at the signed-in
110
+ GitHub account (`gh api user`, when the CLI is available) and at
111
+ `git config user.name`, ranks them, and shows each with its source — a proposal
112
+ the user cannot trace is one they cannot judge, and this value lands in an
113
+ immutable history.
114
+
115
+ - **Candidates found** — show them and ask which to adopt, or let the user type a
116
+ different name. Then write it:
117
+ `python3 "$ADR_KIT/bin/adr" signer --set "User: <chosen>"`.
118
+ - **Already configured** — say so and move on. Do not overwrite it.
119
+ - **Nothing found** — the GitHub CLI is absent or signed out and git names nobody
120
+ usable. Ask for the name outright rather than guessing.
121
+
122
+ **Bot and CI identities are deliberately not offered.** `github-actions[bot]`,
123
+ `runner`, a bare `user`: those are configured values that name a machine, and
124
+ R8 asks for evidence of which *human* accepted a decision.
125
+
126
+ The value is machine-local by design (`docs/adr/.adr-kit.local.json`, gitignored)
127
+ because writing one person's name into the tracked config would sign every
128
+ teammate's acceptances. Each machine, container and CI runner needs its own.