@codewizard-dt/bootstrap 2.17.0 → 2.18.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 (39) hide show
  1. package/lib/hooks/README.md +94 -3
  2. package/lib/hooks/absolute-path-guard.js +5 -0
  3. package/lib/hooks/claude-settings-guard.js +5 -0
  4. package/lib/hooks/env-content-read-guard.js +13 -3
  5. package/lib/hooks/env-file-guard.js +42 -0
  6. package/lib/hooks/interpreter-indirection-guard.js +7 -0
  7. package/lib/hooks/lib/command-parse.js +8 -0
  8. package/lib/hooks/lib/serena-languages.js +94 -1
  9. package/lib/hooks/lib/serena.js +228 -0
  10. package/lib/hooks/mv-absolute-path-block.js +84 -3
  11. package/lib/hooks/package-install-consent.js +11 -0
  12. package/lib/hooks/protected-write-guard.js +7 -0
  13. package/lib/hooks/serena-bash-grep-block.js +507 -44
  14. package/lib/hooks/serena-first-glob-guard.js +65 -20
  15. package/lib/hooks/serena-first-guard.js +98 -2
  16. package/lib/hooks/serena-first-read-guard.js +92 -2
  17. package/lib/hooks/serena-pre-delegation.js +123 -0
  18. package/lib/hooks/serena-write-guard.js +56 -3
  19. package/lib/scripts/README.md +296 -1
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +147 -18
  22. package/lib/scripts/install-mcps.sh +102 -14
  23. package/lib/scripts/lib.sh +581 -11
  24. package/lib/scripts/merge-gitignore.sh +201 -15
  25. package/lib/scripts/sync-wiki-scaffold.sh +33 -4
  26. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  27. package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
  28. package/lib/scripts/update-project.sh +42 -9
  29. package/lib/skills/README.md +2 -1
  30. package/lib/skills/bootstrap-config/SKILL.md +154 -0
  31. package/lib/skills/git-commit/SKILL.md +54 -1
  32. package/lib/skills/research/SKILL.md +34 -3
  33. package/lib/skills/simplify/SKILL.md +1 -1
  34. package/lib/skills/uat-auto/SKILL.md +9 -4
  35. package/lib/skills/uat-auto-plus/SKILL.md +6 -6
  36. package/lib/skills/uat-generate/SKILL.md +30 -3
  37. package/lib/skills/uat-walk/UAT-CORE.md +41 -6
  38. package/lib/skills/wiki-query/SKILL.md +48 -8
  39. package/package.json +1 -1
@@ -1,9 +1,25 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
- // serena-write-guard.js — PreToolUse hook (matcher: Write)
5
- // Blocks Write on existing code files. New files (no fs path yet) are allowed through.
6
- // Allowlist: markdown, JSON, YAML, config files, test files, and known exempt paths.
4
+ /**
5
+ * serena-write-guard.js — PreToolUse / Write
6
+ *
7
+ * Blocks: Write on an EXISTING in-project code file, where a whole-file write
8
+ * would clobber symbolic content Serena indexes. New files pass straight
9
+ * through. Allowlist: markdown, JSON, YAML, config files, test files, and
10
+ * the known exempt paths in lib/serena.js.
11
+ * Why a hook: the verdict turns on a filesystem fact — does the target already
12
+ * exist — that no settings.json pattern can consult. A path rule would have
13
+ * to deny both the create and the overwrite, or neither.
14
+ * Fails: open — unparseable stdin, an empty path, an out-of-project path, or
15
+ * `health.should_enforce === false` all pass the Write through.
16
+ * False positives: a deliberate full-file regeneration of an existing code
17
+ * file (codegen output, a rewrite from scratch) — escape hatch: use the
18
+ * Serena call printed in the block message, or delete the file first so the
19
+ * new-file path applies.
20
+ * See README.md § "Serena-first enforcement hooks (ported from
21
+ * `claude-code-lsp-enforcement-kit`)" for the full rationale.
22
+ */
7
23
 
8
24
  const fs = require('fs');
9
25
  const {
@@ -20,6 +36,14 @@ process.stdin.on('end', () => {
20
36
 
21
37
  if (data.tool_name !== 'Write') process.exit(0);
22
38
 
39
+ // ORDERING: health check → path extraction → out-of-project → allowlist →
40
+ // existence. This is a cost ordering, not a correctness one — unlike the read
41
+ // guard there is no state ladder here to deadlock, so no step can trap the
42
+ // agent by running late. Each step is cheaper and more total than the next,
43
+ // and existsSync is the only filesystem call in the file: keeping it last
44
+ // means the majority of Write calls (markdown, JSON, config, tests) are
45
+ // decided without touching the disk at all.
46
+ //
23
47
  // Fail-open: skip enforcement when Serena is unhealthy for this project.
24
48
  if (!shouldEnforceSerena(readStateFile(getStateFilePath()))) process.exit(0);
25
49
 
@@ -31,9 +55,23 @@ process.stdin.on('end', () => {
31
55
  // Enforcement is scoped to the project root — Serena can't reach outside it.
32
56
  if (isOutsideProject(filePath)) process.exit(0);
33
57
 
58
+ // allowMarkdown: true — .md / .mdx are ALWAYS exempt from write enforcement,
59
+ // overriding isAllowedPath's language-aware branch even in a project that has
60
+ // markdown enabled as a Serena language. Note the read guard passes the
61
+ // opposite flag (enforceMarkdown: true): reading docs should route through
62
+ // Serena so the agent orients before it reads, but authoring them through a
63
+ // symbol-editing tool buys nothing.
34
64
  if (isAllowedPath(filePath, { allowMarkdown: true })) process.exit(0);
35
65
 
36
66
  // New files have no symbols to preserve — native Write is the right tool.
67
+ // The guard exists because Write REPLACES a file wholesale, destroying both
68
+ // the symbol structure Serena indexes and any content the agent did not
69
+ // re-type. A path that does not exist yet has neither, so there is nothing to
70
+ // clobber and Serena's create_text_file offers nothing native Write does not.
71
+ // fs.existsSync is racy in principle — the file could appear between this
72
+ // check and the Write — but the cost of losing that race is one missed
73
+ // guidance nudge. Serena-first is agent guidance, not a security boundary,
74
+ // so the race does not justify an open/O_EXCL dance.
37
75
  if (!fs.existsSync(filePath)) process.exit(0);
38
76
 
39
77
  // --- BLOCKED (file exists — Write would clobber symbolic content) ---
@@ -54,5 +92,20 @@ process.stdin.on('end', () => {
54
92
  reason,
55
93
  })));
56
94
 
95
+ // exit(2) comes LAST, after both writes, because process.exit() terminates
96
+ // immediately — anything emitted after it is simply lost, so the structured
97
+ // envelope on stdout and the human-readable message on stderr have to be
98
+ // handed over first.
99
+ //
100
+ // It is also belt-and-braces: the `decision: 'block'` envelope above blocks
101
+ // the call on its own (that is the only signal serena-first-guard.js sends),
102
+ // and exit code 2 blocks independently. Nothing in the repo records why this
103
+ // hook emits both signals while its siblings emit one.
104
+ //
105
+ // SUSPECTED DEFECT, deliberately not fixed here: on POSIX, stdout/stderr to a
106
+ // pipe are asynchronous, so process.exit() immediately after a console.log
107
+ // can truncate the payload. serena-first-read-guard.js's emitBlock has the
108
+ // same shape. Exit code 2 would still block, but the reason text could be
109
+ // lost — which is the part that tells the agent what to do instead.
57
110
  process.exit(2);
58
111
  });
@@ -10,7 +10,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
10
10
  |--------|---------------------|---------------|
11
11
  | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
12
  | `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
13
- | `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. MCPs install **last** — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
13
+ | `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Then step 6 installs the preference helper — `bootstrap-prefs.js` → `~/.claude/bootstrap-prefs.js` and `templates/bootstrap-prefs-schema.json` → `~/.claude/templates/bootstrap-prefs-schema.json`, the layout that lets a skill read a preference with no `--schema` flag (see [Preference helper notes](#preference-helper-notes)); a missing helper or schema warns and continues. Step 7 then settles the five `consumer: skill` preferences that have never been answered — asked once, in a batch, at global scope, gated on a tty as a whole, so a non-interactive run prints one note and writes no answers and no preferences file. MCPs install **last** (step 8) — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
14
14
  | `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
15
15
  | `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
16
16
  | `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
@@ -28,6 +28,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
28
28
  | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
29
29
  | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
30
30
  | `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
31
+ | `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
31
32
 
32
33
  ## Standalone infra scripts (not wired to the CLI)
33
34
 
@@ -51,6 +52,7 @@ Static and semi-static assets copied or read by the scripts above — never exec
51
52
  | `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
52
53
  | `templates/file-suggestion.sh` | `install-global.sh` | The `fileSuggestion` `@`-autocomplete picker, copied to `~/.claude/file-suggestion.sh`. Reads the picker's stdin JSON `query` with `sed` (no `jq`), lists the project from `rg --files` (falling back to `git ls-files`, then `find`), and re-includes the paths under the `# bootstrap wiki & agent state (machine-local)` sentinel in `.git/info/exclude` — so bootstrap's hidden dirs are suggestible again while a user's other `info/exclude` entries stay hidden. Always exits 0. |
53
54
  | `templates/settings-deny.json` | `merge-settings-deny.js` | The canonical `permissions.deny` list (bare JSON array of rule strings). Covers **both** `Bash(...)` command patterns (destructive disk/system commands, `sudo`, permission footguns, git working-tree/history protections, macOS persistence, credential exfiltration, fetch-and-execute) **and** file-tool path patterns — `Edit(...)` / `Read(...)` — protecting Claude Code's own settings and hooks, shell profiles, git config, and credential stores. Audited against the Claude Code permission-rule docs; merged additively into `~/.claude/settings.json` on every `install`/`setup`/`update`. See [Deny-list notes](#deny-list-notes) for the enforcement model and known costs. |
55
+ | `templates/bootstrap-prefs-schema.json` | `bootstrap-prefs.js` (resolved by default as `<its own dir>/templates/bootstrap-prefs-schema.json`, no flag needed), `install-global.sh` (step 6 copies it to `~/.claude/templates/`; step 7's sync pass reads it to decide which keys are still unanswered), the installer prompt sites (`install-mcps.sh`, `merge-gitignore.sh`, `sync-wiki-scaffold.sh`, `update-project.sh`, `lib.sh`), `/bootstrap-config` | The canonical registry of every bootstrap preference key — a flat JSON object mapping a dotted key to an entry that describes it (`scope`, `consumer`, `summary`, `detail`, `values`, `default`, `askedBy`, optional `dynamic`). One file, several readers, so adding or renaming a preference is a one-file change and the surfaces cannot drift apart — the same "template owns the canonical data" model as the two settings templates above. Pure data: JSON carries no comments, so the file stays bare (no `$comment` keys, no trailing commas, `JSON.parse`-able with zero preprocessing) and its rules live in [Preference-schema notes](#preference-schema-notes). |
54
56
  | `templates/settings-hooks.json` | `merge-settings-hooks.js` | The canonical hook wiring — a bare hooks-value object (the value of the settings `hooks` key, not a full settings file) covering 4 events (`SessionStart`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the 18 hook scripts in `lib/hooks/*.js`. The single source of truth for the wiring merged into `~/.claude/settings.json` on every `install`/`setup`/`update`; each block's matcher is load-bearing (see `lib/hooks/README.md`), which is why the wiring ships as a template instead of being hand-pasted. |
55
57
 
56
58
  ## Deny-list notes
@@ -114,3 +116,296 @@ inside this repo. The canonical flow there is to edit `lib/hooks/` and re-run
114
116
  self-grant permissions by editing global settings. That is the deliberate cost of
115
117
  making this repo able to do its job — containment for that case is the OS sandbox
116
118
  (`/sandbox`), not this layer.
119
+
120
+ ## Preference helper notes
121
+
122
+ How `bootstrap-prefs.js` behaves at run time. The schema's *shape* contract is
123
+ the next section down; this one is what a caller — a prompt site, a skill, or
124
+ `/bootstrap-config` — has to know to use the store correctly.
125
+
126
+ ### Two values files, and project wins per key
127
+
128
+ | Layer | Path |
129
+ |-------|------|
130
+ | global | `~/.claude/bootstrap-prefs.json` |
131
+ | project | `<project>/.claude/bootstrap-prefs.json` |
132
+
133
+ Both are flat JSON objects mapping a dotted key to a value — the same flat shape
134
+ as the schema, so lookup is symmetric on both sides.
135
+
136
+ Resolution is `project → global → schema default → unset`, and it is
137
+ **scope-constrained**: `resolve()` only walks the layers a key's `scope` permits.
138
+ A `global`-scope key never reads the project file (honouring it would make a
139
+ machine-wide answer overridable per checkout) and a `project`-scope key never
140
+ reads the global one. Only `either` keys consult both.
141
+
142
+ `--get` resolves across layers **by default** — that is deliberate, not a flag:
143
+ forgetting a flag and silently getting `unset` would cause exactly the re-prompt
144
+ this store exists to remove. But the *project* layer can only be consulted if you
145
+ say where the project is: `--get`/`--list` read `<project>/.claude/` only when
146
+ `--project <dir>` is passed. Omit it and you get the global layer alone, which is
147
+ why `--list` ends with a line saying which layers it actually consulted.
148
+
149
+ `--target <path>` bypasses layer resolution entirely and reads or writes exactly
150
+ one file. It is the test seam, and doubles as the escape hatch for touching a
151
+ single layer by path.
152
+
153
+ ### The four-state model
154
+
155
+ Every key is in exactly one of four states, and the distinction between the last
156
+ three is the whole point of the subsystem.
157
+
158
+ | State | Representation | Meaning |
159
+ |-------|----------------|---------|
160
+ | `unset` | **absent from both values files** | Never answered. The prompt should still fire. |
161
+ | a settled value | the key holds `true`, `"auto"`, `"shared"`, … | Answered. Never re-asked. |
162
+ | `false` | the key holds `false` | A remembered **decline** — a settled answer, not an absence. |
163
+ | `ask` | the key holds `"ask"` | *"Keep prompting me; do not persist the answer."* |
164
+
165
+ - **Absence is the entire representation of `unset`.** `null` is never written and
166
+ the string `"unset"` is never stored; `--set <key> --value unset` (or `null`)
167
+ exits 1 and points at `--unset`. Deleting a key is how you re-open a question,
168
+ and `--unset` is the only supported way to do it.
169
+ - **`false` is not `unset`.** This is the state that fixes ROADMAP-005's original
170
+ complaint: stickiness used to come from side effects (a thing existing on disk),
171
+ which is one-directional — accepting stopped the prompt, declining did not, so
172
+ every run re-asked the questions the user had already said no to.
173
+ - **`ask` is itself a stored answer.** The key is settled; what it settles on is
174
+ "prompt every time". A stored `ask` is therefore never re-offered by the
175
+ settling pass — re-prompting *for* a decision the user already made would be the
176
+ same bug in a different costume.
177
+ - **Grammar exception:** `gitCommit.versionBump` expresses its ask state as
178
+ **`confirm`**, inside its own `auto | confirm | never` grammar. It has
179
+ deliberately no separate `ask` value, and offering one is a hard failure —
180
+ `--set gitCommit.versionBump --value ask` exits 1.
181
+
182
+ ### The installed layout is what makes skill keys readable
183
+
184
+ `install-global.sh` step 6 installs two files:
185
+
186
+ ```
187
+ ~/.claude/bootstrap-prefs.js
188
+ ~/.claude/templates/bootstrap-prefs-schema.json
189
+ ```
190
+
191
+ The schema goes to `~/.claude/templates/`, not beside the helper, because
192
+ `bootstrap-prefs.js` resolves its schema as **`<its own directory>/templates/bootstrap-prefs-schema.json`**
193
+ (`bootstrap-prefs.js:111`). Preserving that relative layout is the entire point:
194
+ the installed copy works with **no `--schema` flag**, so a skill running in an
195
+ arbitrary project — one that is almost never a bootstrap checkout — still gets
196
+ validation, defaults, and descriptions. That is what makes the `consumer: skill`
197
+ keys readable at all:
198
+
199
+ ```
200
+ node ~/.claude/bootstrap-prefs.js --get gitCommit.autoPush --project .
201
+ ```
202
+
203
+ A flattened copy would silently drop validation *and* defaults, and a dropped
204
+ default turns an unanswered key from "the documented default" into `unset` at
205
+ every call site. `--schema <path>` exists only for a non-default schema — chiefly
206
+ a test seam. A missing or malformed schema is a warning, never a crash: `--get`
207
+ still resolves from the files and `--set` still writes.
208
+
209
+ The installer scripts do **not** use the installed copy — `lib.sh` resolves
210
+ `bootstrap-prefs.js` from its own directory at source time, so a `setup`/`update`
211
+ run always uses the checkout's helper and the checkout's schema.
212
+
213
+ ### The generated companion is output, never input
214
+
215
+ Every successful `--set`/`--unset` — including a no-op set, since the schema may
216
+ have changed since the last one — rewrites `bootstrap-prefs.README.md` beside the
217
+ values file: the same directory, the same layer. It is **generated output; hand
218
+ edits are overwritten without warning.** Edit the values file, or run
219
+ `/bootstrap-config`.
220
+
221
+ It groups its tables `installer` then `skill`, the same order and the same
222
+ grouping `--list` uses and the same order as the registry table below, so all
223
+ three surfaces read alike. Its `## Unrecognized keys` section is the
224
+ forward-compatibility surface: a key present in a values file but absent from the
225
+ schema is never dropped, it round-trips a read-modify-write untouched, and it is
226
+ listed there with the reason it was not explained.
227
+
228
+ ### No preference key ever holds a secret
229
+
230
+ No API key, token, or password belongs in a values file or in the schema — the
231
+ same warning the generated companion carries in its header. The Brave Search API
232
+ key, for instance, is baked into the MCP container's env; `mcp.braveSearch`
233
+ records only whether to install the server. Treat this as a rule when adding a
234
+ key: if the answer to a question is a credential, the question does not belong in
235
+ this store.
236
+
237
+ ### Known gap: `--set` enforces a key's grammar but not its scope
238
+
239
+ `--set` validates the *value* against the schema's `values` string, but does not
240
+ check that the chosen layer is one the key's `scope` permits. So a `global`-scope
241
+ key can be written into a project values file, where `resolve()` will never
242
+ consult it — the write succeeds, prints a success line, and has no effect. Filed
243
+ as [`BUG-0009`](../../wiki/work/bugs/BUG-0009-set-writes-scope-inert-key-silently.md);
244
+ known, not intended. Today the *only* surface that reveals it is the generated
245
+ companion's `## Unrecognized keys` section, which lists such a key with
246
+ `scope is ... — this layer never consults it, so it has no effect here`.
247
+
248
+ ## Preference-schema notes
249
+
250
+ The shape contract for `templates/bootstrap-prefs-schema.json`. JSON cannot carry
251
+ comments, so the file itself must stay bare — no `$comment` header, no explanatory
252
+ keys — and everything a reader or a new consumer needs to know about its shape
253
+ lives here instead. What each individual key *does* is a separate question, and
254
+ it is answered by [The key registry — all 19 entries](#the-key-registry--all-19-entries)
255
+ at the end of this section.
256
+
257
+ ### Flat key → entry, and eight fields
258
+
259
+ A single flat top-level object: dotted key → entry object. Deliberately **not**
260
+ nested by scope or consumer — `scope` is a *property* of an entry, not a path to
261
+ it, and nesting would force a reader to already know a key's scope before it could
262
+ look the key up. Flat also mirrors the values files
263
+ (`~/.claude/bootstrap-prefs.json` and `<project>/.claude/bootstrap-prefs.json`),
264
+ which are flat dotted-key objects, so lookup is symmetric on both sides.
265
+
266
+ | Field | Type | Meaning |
267
+ |-------|------|---------|
268
+ | `scope` | `"global"` \| `"project"` \| `"either"` | Which values file(s) may hold the key. Only `either` consults both (project wins); `global` and `project` keys are looked up in exactly one file. |
269
+ | `consumer` | `"installer"` \| `"skill"` | Who asks and who reads. `installer` keys are asked in situ by the script that owns the prompt; `skill` keys change what a slash command does. |
270
+ | `summary` | string | One line — used for `--list`, the generated README table, and the prompt option label. |
271
+ | `detail` | string | Prose consequence of each value: what changes on disk or in behavior. |
272
+ | `values` | string | Human-readable value grammar, e.g. `"true \| false"` or `"auto \| confirm \| never"`. A **display** string; a validator is derived from it by splitting on `\|` and trimming. |
273
+ | `default` | JSON value or `null` | What a resolving read returns when neither values file holds the key. `null` means "no default; the key resolves to `unset`". |
274
+ | `askedBy` | string | The script or slash command that owns the **settling** prompt — the one place that writes the answer, e.g. `"install-mcps.sh"`. Exactly one owner: either a bare filename that must exist in `lib/scripts/`, or a `/slash-command` that must have a `lib/skills/<name>/SKILL.md` (both enforced by `test/bootstrap-prefs.test.js`), so a compound value like `"install-global.sh, /git-commit"` is not legal. Run-time prompts that a key's own `ask`/`confirm` state triggers inside a consumer are **not** listed here — they live in `detail`. See [Why every `consumer: skill` key says `install-global.sh`](#why-every-consumer-skill-key-says-install-globalsh). |
275
+ | `dynamic` | `true`, optional | The only optional field. Marks a wildcard key pattern — see below. |
276
+
277
+ ### Lookup is exact-match first, wildcard second
278
+
279
+ Two prompt families generate one key per item at run time and cannot be
280
+ enumerated ahead of time, so they get wildcard entries carrying `"dynamic": true`:
281
+ `guides.*` (one per `OPTIONAL_GUIDES` entry in `sync-wiki-scaffold.sh`, keyed by
282
+ the exact entry text including any extension) and `gitignore.section.*` (one per
283
+ titled section of `templates/gitignore`). A wildcard key is a single trailing `*`
284
+ segment — nothing fancier. Lookup tries an exact key first and only then falls
285
+ back to a pattern, so adding an exact `guides.evals-framework.md` entry later
286
+ overrides the pattern with no code change.
287
+
288
+ **Slug rule for `gitignore.section.*`** — stated here because the key has to be
289
+ derivable identically by the shell and by the JS reader: lowercase the section's
290
+ banner title, replace every run of non-alphanumeric characters with a single `-`,
291
+ then strip leading and trailing `-`. So `Node / TypeScript / JavaScript` becomes
292
+ `gitignore.section.node-typescript-javascript`. Treat "non-alphanumeric"
293
+ **Unicode-aware**, not as `[^a-z0-9]` over bytes: one section title today contains
294
+ an em dash, and a bytewise match turns that one character into three dashes before
295
+ the collapse step.
296
+
297
+ ### `gitignore.section.*` has a one-value grammar, on purpose
298
+
299
+ That entry's `values` is the literal string `"false"` — one legal value, no
300
+ `true`. It is the design, not a typo, and must not be widened. `merge-gitignore.sh`
301
+ guarantees that *nothing is ever added to a project's `.gitignore` without asking*
302
+ (`merge-gitignore.sh:11`); a remembered **yes** would silently append lines on a
303
+ later run and break that. So only declines are recorded. An accepted section is
304
+ never stored, which is also why a section that gains new lines in a later template
305
+ version is still offered by title next run instead of being appended silently.
306
+
307
+ The rule is specific to add/skip gates. Keys that pick among behaviors —
308
+ `prefs.gitTracking`, `gitCommit.versionBump`, `gitignore.offerSectionUpdates` — are
309
+ recorded in every direction and are genuinely asked once.
310
+
311
+ ### `default` is metadata and is never written to a values file
312
+
313
+ `default` describes what an *unanswered* key resolves to. It is never serialized
314
+ into `~/.claude/bootstrap-prefs.json` or a project's values file. The four-state
315
+ model depends on absence *being* `unset`: writing a default into the file would
316
+ convert an unanswered question into a settled answer and permanently suppress the
317
+ prompt that was supposed to ask it.
318
+
319
+ ### An unrecognized key round-trips unchanged
320
+
321
+ A key present in a values file but absent from this schema is **never silently
322
+ dropped**. It survives a read-modify-write untouched and is listed under
323
+ "unrecognized" in the generated `bootstrap-prefs.README.md` beside the values file.
324
+ This is the forward-compatibility guarantee: a values file written by a newer
325
+ bootstrap — one that knows keys this schema has not heard of yet — stays intact
326
+ after an older version touches it, and the user can see what was kept.
327
+
328
+ ### Why every `consumer: skill` key says `install-global.sh`
329
+
330
+ All five `consumer: skill` keys name `install-global.sh` as their `askedBy`,
331
+ including `gitCommit.versionBump` and `gitCommit.autoPush` — which named
332
+ `/git-commit` until this was settled. The field records the **settling** prompt:
333
+ the one site that writes the answer. For all five keys that site is
334
+ `install-global.sh`'s step 7 sync pass, which asks each unanswered key once, in a
335
+ batch, at global scope.
336
+
337
+ `/git-commit` does still prompt — but only once the key is already settled *to a
338
+ value that means "keep asking"* (`confirm` for `versionBump`, `ask` for
339
+ `autoPush`). That is a consumer honouring a stored answer, not the question being
340
+ asked. The same is true of the other three: `/research`, `/uat-generate`, and
341
+ `merge-gitignore.sh` each prompt in their key's `ask` state, and none of them is
342
+ named in `askedBy` either.
343
+
344
+ The practical test is `--unset`: re-open one of these keys and the question comes
345
+ back on the next `install-global.sh` run. It does **not** come back inside
346
+ `/git-commit`, which would simply fall through to the schema default and act.
347
+ Pointing a user at `/git-commit` to re-answer a question `/git-commit` will not
348
+ ask is the defect the old value encoded. Naming both was considered and is not
349
+ available: `test/bootstrap-prefs.test.js` requires `askedBy` to resolve to one
350
+ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
351
+ `"install-global.sh, /git-commit"` fails the suite by construction. Where a
352
+ run-time prompt exists, it is documented in the key's `detail`.
353
+
354
+ ### The key registry — all 19 entries
355
+
356
+ Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
357
+ `installer` first, then `skill` — which is the same grouping and the same order
358
+ `--list` and the generated `bootstrap-prefs.README.md` use. `Default` is the
359
+ schema's `default` field; `unset` in that column means `default: null`, i.e. the
360
+ key resolves to `unset` until it is answered. This table is transcribed from the
361
+ JSON; if the two ever disagree, the JSON is right and this table is a bug.
362
+
363
+ #### `consumer: installer` — 14 entries, read by the setup/update scripts
364
+
365
+ | Key | Scope | Consumer | Values | Default | Asked by | What it does |
366
+ |-----|-------|----------|--------|---------|----------|--------------|
367
+ | `mcp.serenaMigrate` | project | installer | `true \| false` | `unset` | `install-mcps.sh` | Move a project-scope Serena registration out of this repo's `.mcp.json` |
368
+ | `mcp.serena` | project | installer | `true \| false` | `unset` | `install-mcps.sh` | Register Serena at local scope for this project |
369
+ | `mcp.playwrightConflict` | project | installer | `shared \| alongside \| skip` | `unset` | `install-mcps.sh` | How to resolve a committed `.mcp.json` that already registers its own playwright server |
370
+ | `mcp.playwrightReplace` | project | installer | `true \| false` | `unset` | `install-mcps.sh` | Replace an existing machine-local Playwright registration with the bootstrap shared server |
371
+ | `update.legacyDocsAck` | project | installer | `true \| false` | `unset` | `update-project.sh` | Continue `update` even though a legacy `.docs/` directory was detected |
372
+ | `gitignore.infoExclude` | project | installer | `true \| false` | `unset` | `merge-gitignore.sh` | Keep `.serena/`, `raw/`, and `wiki/` out of git on this machine via `.git/info/exclude` |
373
+ | `prefs.gitTracking` | project | installer | `gitignore \| exclude \| neither` | `unset` | `merge-gitignore.sh` | How git should treat `.claude/bootstrap-prefs.json` and `bootstrap-prefs.README.md` |
374
+ | `guides.*` **(pattern)** | project | installer | `true \| false` | `unset` | `sync-wiki-scaffold.sh` | Install a specific optional guide into `wiki/guides/` |
375
+ | `gitignore.section.*` **(pattern)** | project | installer | `false` | `unset` | `merge-gitignore.sh` | Permanently decline one titled `.gitignore` template section |
376
+ | `mcp.braveSearch` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Brave Search MCP globally for web research |
377
+ | `mcp.context7` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Context7 MCP for library documentation lookups |
378
+ | `mcp.context7Scope` | global | installer | `user \| project` | `unset` | `lib.sh` | Registration scope for the Context7 MCP |
379
+ | `mcp.playwright` | global | installer | `true \| false` | `unset` | `install-mcps.sh` | Install the Playwright MCP for browser automation and UI testing |
380
+ | `skills.pruneOrphans` | global | installer | `true \| false` | `unset` | `install-global.sh` | Delete stale skill folders in `~/.claude/skills/` left by the wiki rename |
381
+
382
+ The two **(pattern)** rows carry `"dynamic": true` and are key *families*, not
383
+ keys: they match one concrete key per optional guide and per titled `.gitignore`
384
+ section respectively. Their matching rule, the `guides.*` naming, and the
385
+ Unicode-aware slug rule for `gitignore.section.*` are in
386
+ [Lookup is exact-match first, wildcard second](#lookup-is-exact-match-first-wildcard-second)
387
+ above; `gitignore.section.*`'s deliberate one-value grammar is in
388
+ [the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
389
+
390
+ #### `consumer: skill` — 5 entries, read by slash commands at run time
391
+
392
+ | Key | Scope | Consumer | Values | Default | Asked by | What it does |
393
+ |-----|-------|----------|--------|---------|----------|--------------|
394
+ | `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
395
+ | `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
396
+ | `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
397
+ | `uatGenerate.promoteTests` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/uat-generate` promotes UAT checks into repeatable tests under `test/` |
398
+ | `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
399
+
400
+ These five are the entire `scope: either` population and the entire
401
+ `consumer: skill` population — the two sets coincide, because a key that changes
402
+ what a slash command does is exactly the kind of key a user may want to answer
403
+ once machine-wide and then override in one checkout.
404
+
405
+ **Every `installer` key has `default: null`; every `skill` key carries a real
406
+ default.** That asymmetry has a consequence worth stating: `prefs_get` alone
407
+ cannot detect "unanswered" for a skill key, because an unanswered one resolves to
408
+ its default and reads as settled. That is why `install-global.sh`'s step 7 sync
409
+ pass uses `prefs_stored_global` — a stored-vs-default check — instead. A
410
+ `prefs_get`-based check there would ask nothing, forever, while looking like it
411
+ worked.