@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.
- package/lib/hooks/README.md +94 -3
- package/lib/hooks/absolute-path-guard.js +5 -0
- package/lib/hooks/claude-settings-guard.js +5 -0
- package/lib/hooks/env-content-read-guard.js +13 -3
- package/lib/hooks/env-file-guard.js +42 -0
- package/lib/hooks/interpreter-indirection-guard.js +7 -0
- package/lib/hooks/lib/command-parse.js +8 -0
- package/lib/hooks/lib/serena-languages.js +94 -1
- package/lib/hooks/lib/serena.js +228 -0
- package/lib/hooks/mv-absolute-path-block.js +84 -3
- package/lib/hooks/package-install-consent.js +11 -0
- package/lib/hooks/protected-write-guard.js +7 -0
- package/lib/hooks/serena-bash-grep-block.js +507 -44
- package/lib/hooks/serena-first-glob-guard.js +65 -20
- package/lib/hooks/serena-first-guard.js +98 -2
- package/lib/hooks/serena-first-read-guard.js +92 -2
- package/lib/hooks/serena-pre-delegation.js +123 -0
- package/lib/hooks/serena-write-guard.js +56 -3
- package/lib/scripts/README.md +296 -1
- package/lib/scripts/bootstrap-prefs.js +734 -0
- package/lib/scripts/install-global.sh +147 -18
- package/lib/scripts/install-mcps.sh +102 -14
- package/lib/scripts/lib.sh +581 -11
- package/lib/scripts/merge-gitignore.sh +201 -15
- package/lib/scripts/sync-wiki-scaffold.sh +33 -4
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
- package/lib/scripts/update-project.sh +42 -9
- package/lib/skills/README.md +2 -1
- package/lib/skills/bootstrap-config/SKILL.md +154 -0
- package/lib/skills/git-commit/SKILL.md +54 -1
- package/lib/skills/research/SKILL.md +34 -3
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/uat-auto/SKILL.md +9 -4
- package/lib/skills/uat-auto-plus/SKILL.md +6 -6
- package/lib/skills/uat-generate/SKILL.md +30 -3
- package/lib/skills/uat-walk/UAT-CORE.md +41 -6
- package/lib/skills/wiki-query/SKILL.md +48 -8
- package/package.json +1 -1
|
@@ -1,9 +1,25 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
'use strict';
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
});
|
package/lib/scripts/README.md
CHANGED
|
@@ -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.
|