@codewizard-dt/bootstrap 3.0.1 → 3.2.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.
@@ -0,0 +1,26 @@
1
+ name: Docker Fresh-Machine Harness
2
+
3
+ on:
4
+ pull_request:
5
+ paths:
6
+ - "test/docker/fresh-machine/**"
7
+ - "lib/scripts/**"
8
+
9
+ jobs:
10
+ fresh-machine:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - name: Checkout repo
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Build fresh-machine image
17
+ run: docker build -t bootstrap-claude-fresh-machine test/docker/fresh-machine
18
+
19
+ - name: Run setup mode
20
+ run: ./test/docker/fresh-machine/run.sh setup
21
+
22
+ - name: Run update mode
23
+ run: ./test/docker/fresh-machine/run.sh update
24
+
25
+ # TASK-071 (stale mode) and TASK-072 (idempotency check) are still `status: todo` —
26
+ # add their run.sh modes as additional steps here once those tasks land.
@@ -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. 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. |
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 seven `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`. |
@@ -39,6 +39,7 @@ These are **not** referenced by `bin/cli.js` or by any other script — they're
39
39
  |--------|---------|
40
40
  | `setup-runner.sh` | Generalized GitHub Actions self-hosted runner installer. Run as root on a target droplet: `RUNNER_TOKEN=<token> REPO_URL=<url> bash setup-runner.sh`. Registers the runner, installs it as a service, and configures GHCR login. |
41
41
  | `startup.sh` | One-shot droplet bootstrap: updates apt, installs zsh/curl/make, and installs Docker + the Compose plugin from Docker's official apt repo. Typically run once before `setup-runner.sh` on a fresh VM. |
42
+ | [`test/docker/fresh-machine/`](../../test/docker/fresh-machine/README.md) | Docker-based harness that emulates running `setup`/`update` on a completely fresh machine with no prior Claude Code infrastructure. `./run.sh [shell\|setup\|update]`. |
42
43
 
43
44
  ## `templates/`
44
45
 
@@ -344,10 +345,10 @@ after an older version touches it, and the user can see what was kept.
344
345
 
345
346
  ### Why every `consumer: skill` key says `install-global.sh`
346
347
 
347
- All five `consumer: skill` keys name `install-global.sh` as their `askedBy`,
348
+ All seven `consumer: skill` keys name `install-global.sh` as their `askedBy`,
348
349
  including `gitCommit.versionBump` and `gitCommit.autoPush` — which named
349
350
  `/git-commit` until this was settled. The field records the **settling** prompt:
350
- the one site that writes the answer. For all five keys that site is
351
+ the one site that writes the answer. For all seven keys that site is
351
352
  `install-global.sh`'s step 7 sync pass, which asks each unanswered key once, in a
352
353
  batch, at global scope.
353
354
 
@@ -368,7 +369,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
368
369
  `"install-global.sh, /git-commit"` fails the suite by construction. Where a
369
370
  run-time prompt exists, it is documented in the key's `detail`.
370
371
 
371
- ### The key registry — all 23 entries
372
+ ### The key registry — all 24 entries
372
373
 
373
374
  Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
374
375
  `installer` first, then `skill` — which is the same grouping and the same order
@@ -407,12 +408,13 @@ Unicode-aware slug rule for `gitignore.section.*` are in
407
408
  above; `gitignore.section.*`'s deliberate one-value grammar is in
408
409
  [the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
409
410
 
410
- #### `consumer: skill` — 6 entries, read by slash commands at run time
411
+ #### `consumer: skill` — 7 entries, read by slash commands at run time
411
412
 
412
413
  | Key | Scope | Consumer | Values | Default | Asked by | What it does |
413
414
  |-----|-------|----------|--------|---------|----------|--------------|
414
415
  | `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
415
416
  | `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
417
+ | `gitCommit.lint` | either | skill | `true \| false` | `false` | `install-global.sh` | Whether `/git-commit` runs the /lint fix-cycle before committing |
416
418
  | `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
417
419
  | `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
418
420
  | `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-generate` writes the unit tests it promotes out of UAT cases |
@@ -173,7 +173,7 @@ echo ""
173
173
  # mechanism exists to remove.
174
174
  #
175
175
  # GLOBAL SCOPE. install-global.sh takes no project path, so it cannot know
176
- # which checkout the user means. All five keys are `scope: either`, so the
176
+ # which checkout the user means. All seven keys are `scope: either`, so the
177
177
  # answer recorded here is the machine-wide default and a project file can
178
178
  # still override it per checkout later.
179
179
  #
@@ -183,7 +183,7 @@ echo ""
183
183
  # One CI run must never bake a permanent answer into a user's store.
184
184
  PREFS_ASKED=0
185
185
 
186
- # <key> <question> — the yes/no/ask shape shared by four of the five keys.
186
+ # <key> <question> — the yes/no/ask shape shared by four of the seven keys.
187
187
  # `skip` is the resolved value for a bare Enter or EOF and records nothing, so
188
188
  # an accidental keystroke leaves the question open instead of settling it.
189
189
  settle_skill_pref() {
@@ -232,6 +232,18 @@ else
232
232
 
233
233
  settle_skill_pref gitCommit.autoPush \
234
234
  "Should /git-commit push the current branch after committing? (Default no — this turns a local action into a published one. It never creates a branch either way.)"
235
+ # gitCommit.lint's grammar is true|false only (no `ask`), so it can't use settle_skill_pref's generic yes/no/ask/skip shape.
236
+ if ! prefs_stored_global gitCommit.lint; then
237
+ echo ""
238
+ echo " Should /git-commit run the /lint fix-cycle before committing? (Default no — linting is opt-in, so a fresh install never lints without you saying yes.)"
239
+ LINT_ANSWER="$(prompt_letter_choice skip " [y]es / [n]o / [s]kip for now: " yes no skip)"
240
+ case "$LINT_ANSWER" in
241
+ yes) prefs_set gitCommit.lint --global true ; echo " gitCommit.lint = true" ;;
242
+ no) prefs_set gitCommit.lint --global false ; echo " gitCommit.lint = false" ;;
243
+ *) echo " gitCommit.lint left unanswered — today's behavior (no lint) is unchanged, and you will be asked again next sync." ;;
244
+ esac
245
+ PREFS_ASKED=$(( PREFS_ASKED + 1 ))
246
+ fi
235
247
  settle_skill_pref research.persistToRaw \
236
248
  "Should /research save its report and sources to raw/research/ by default? (Findings always appear in the reply; this governs the file write only, and you can still decline any single report.)"
237
249
  settle_skill_pref research.autoIngest \
@@ -245,23 +245,198 @@ _enable_obsidian_plugin() {
245
245
  ' "$vault_dir" "$id" || true
246
246
  }
247
247
 
248
+ # _graph_defaults_node <template> <graph_file> <fingerprint_file> <mode> <decisions_json>
249
+ # Shared plan/apply logic: plan lists diverged keys needing a decision (no writes); apply resolves them via <decisions_json> and writes graph.json + fingerprint sidecar (changed files only). Template keys come from the packaged template's own Object.keys(), never hardcoded.
250
+ _graph_defaults_node() {
251
+ node -e '
252
+ const fs = require("fs");
253
+ const crypto = require("crypto");
254
+
255
+ const [templatePath, graphFile, fingerprintFile, mode, decisionsRaw] = process.argv.slice(1);
256
+
257
+ const hashOf = (v) => crypto.createHash("sha256").update(JSON.stringify(v)).digest("hex");
258
+
259
+ let template;
260
+ try {
261
+ template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
262
+ } catch (e) {
263
+ console.error(" WARNING: could not read/parse the packaged graph.json template — skipping graph defaults.");
264
+ process.exit(0);
265
+ }
266
+ const templateKeys = Object.keys(template);
267
+
268
+ let existing = {};
269
+ if (fs.existsSync(graphFile)) {
270
+ try {
271
+ existing = JSON.parse(fs.readFileSync(graphFile, "utf8"));
272
+ } catch (e) {
273
+ console.error(" WARNING: could not parse existing graph.json — treating it as empty.");
274
+ existing = {};
275
+ }
276
+ }
277
+
278
+ let fingerprint = {};
279
+ if (fs.existsSync(fingerprintFile)) {
280
+ try {
281
+ const raw = JSON.parse(fs.readFileSync(fingerprintFile, "utf8"));
282
+ if (raw && typeof raw === "object" && !Array.isArray(raw)) fingerprint = raw;
283
+ else throw new Error("unexpected shape");
284
+ } catch (e) {
285
+ console.error(" WARNING: could not parse .graph-defaults-fingerprint.json — treating it as empty.");
286
+ fingerprint = {};
287
+ }
288
+ }
289
+
290
+ let decisions = {};
291
+ if (decisionsRaw) {
292
+ try {
293
+ decisions = JSON.parse(decisionsRaw);
294
+ } catch (e) {
295
+ decisions = {};
296
+ }
297
+ }
298
+
299
+ const merged = Object.assign({}, existing);
300
+ const newFingerprint = {};
301
+ const pending = [];
302
+ const added = [];
303
+ const refreshed = [];
304
+ const unchanged = [];
305
+ const kept = [];
306
+
307
+ for (const key of templateKeys) {
308
+ const templateValue = template[key];
309
+ const templateHash = hashOf(templateValue);
310
+ const hasKey = Object.prototype.hasOwnProperty.call(existing, key);
311
+ const fp = fingerprint[key] && typeof fingerprint[key] === "object" ? fingerprint[key] : {};
312
+
313
+ if (!hasKey) {
314
+ // Case 1: key absent from the existing file.
315
+ merged[key] = templateValue;
316
+ newFingerprint[key] = { offeredHash: templateHash };
317
+ added.push(key);
318
+ continue;
319
+ }
320
+
321
+ const fileHash = hashOf(existing[key]);
322
+
323
+ if (fp.offeredHash && fileHash === fp.offeredHash) {
324
+ // Case 2: file still holds exactly what we last delivered.
325
+ merged[key] = templateValue;
326
+ newFingerprint[key] = { offeredHash: templateHash };
327
+ (fileHash === templateHash ? unchanged : refreshed).push(key);
328
+ continue;
329
+ }
330
+
331
+ if (!fp.offeredHash && fileHash === templateHash) {
332
+ // Case 3, unmodified branch: no sidecar yet, but the file already
333
+ // matches todays template — bootstrap the fingerprint silently.
334
+ merged[key] = templateValue;
335
+ newFingerprint[key] = { offeredHash: templateHash };
336
+ unchanged.push(key);
337
+ continue;
338
+ }
339
+
340
+ // Case 4 (including the bootstrapped-diverged branch of case 3): the
341
+ // file has diverged from what we last offered.
342
+ if (fp.declinedHash && templateHash === fp.declinedHash) {
343
+ // Already declined exactly this template value — stay sticky.
344
+ merged[key] = existing[key];
345
+ newFingerprint[key] = fp;
346
+ kept.push(key);
347
+ continue;
348
+ }
349
+
350
+ if (mode === "plan") {
351
+ pending.push(key);
352
+ continue;
353
+ }
354
+
355
+ if (Object.prototype.hasOwnProperty.call(decisions, key)) {
356
+ if (decisions[key] === true) {
357
+ merged[key] = templateValue;
358
+ newFingerprint[key] = { offeredHash: templateHash };
359
+ refreshed.push(key);
360
+ } else {
361
+ merged[key] = existing[key];
362
+ newFingerprint[key] = Object.assign({}, fp, { declinedHash: templateHash });
363
+ kept.push(key);
364
+ }
365
+ } else {
366
+ // Non-interactive, or a plan-only pass with no decision supplied:
367
+ // leave the file untouched and record nothing, so a later
368
+ // interactive run still offers this key.
369
+ merged[key] = existing[key];
370
+ if (fp.offeredHash) newFingerprint[key] = { offeredHash: fp.offeredHash };
371
+ kept.push(key);
372
+ }
373
+ }
374
+
375
+ if (mode === "plan") {
376
+ for (const key of pending) console.log(key);
377
+ process.exit(0);
378
+ }
379
+
380
+ const graphStr = JSON.stringify(merged, null, 2) + "\n";
381
+ const fingerprintStr = JSON.stringify(newFingerprint, null, 2) + "\n";
382
+ const existingGraphStr = fs.existsSync(graphFile) ? fs.readFileSync(graphFile, "utf8") : null;
383
+ const existingFingerprintStr = fs.existsSync(fingerprintFile) ? fs.readFileSync(fingerprintFile, "utf8") : null;
384
+
385
+ if (graphStr !== existingGraphStr) {
386
+ const tmp = graphFile + ".tmp-" + process.pid;
387
+ fs.writeFileSync(tmp, graphStr);
388
+ fs.renameSync(tmp, graphFile);
389
+ }
390
+ if (fingerprintStr !== existingFingerprintStr) {
391
+ const tmp = fingerprintFile + ".tmp-" + process.pid;
392
+ fs.writeFileSync(tmp, fingerprintStr);
393
+ fs.renameSync(tmp, fingerprintFile);
394
+ }
395
+
396
+ const parts = [];
397
+ if (added.length) parts.push(added.length + " added");
398
+ if (refreshed.length) parts.push(refreshed.length + " refreshed");
399
+ if (unchanged.length) parts.push(unchanged.length + " unchanged");
400
+ if (kept.length) parts.push(kept.length + " kept (your customization)");
401
+ console.log(" graph.json: " + (parts.length ? parts.join(", ") : "no changes") + ".");
402
+ ' "$1" "$2" "$3" "$4" "$5"
403
+ }
404
+
405
+ # _install_obsidian_graph_defaults <vault_dir>
406
+ # Per-key sticky refresh (TASK-067) via a fingerprint sidecar, replacing the old whole-file write-if-absent check — never silently clobbers a genuinely user-diverged key. See _graph_defaults_node for the decision table.
248
407
  _install_obsidian_graph_defaults() {
249
408
  local vault_dir="$1"
409
+ local template="$SCRIPT_DIR/templates/obsidian/graph.json"
410
+ local graph_file="$vault_dir/.obsidian/graph.json"
411
+ local fingerprint_file="$vault_dir/.obsidian/.graph-defaults-fingerprint.json"
250
412
 
251
413
  if ! mkdir -p "$vault_dir/.obsidian"; then
252
414
  echo " WARNING: failed to create $vault_dir/.obsidian — skipping graph defaults." >&2
253
415
  return
254
416
  fi
255
417
 
256
- if [ -f "$vault_dir/.obsidian/graph.json" ]; then
257
- echo " .obsidian/graph.json already present — leaving your customization in place, skipping."
258
- return 0
259
- fi
418
+ local decisions="{}"
419
+ if [ "$INTERACTIVE" = true ]; then
420
+ local pending=() key
421
+ while IFS= read -r key; do
422
+ [ -n "$key" ] && pending+=("$key")
423
+ done < <(_graph_defaults_node "$template" "$graph_file" "$fingerprint_file" plan "{}")
260
424
 
261
- if ! cp "$SCRIPT_DIR/templates/obsidian/graph.json" "$vault_dir/.obsidian/graph.json"; then
262
- echo " WARNING: failed to install graph defaults — skipping." >&2
263
- return
425
+ if [ "${#pending[@]}" -gt 0 ]; then
426
+ local parts=() answer
427
+ for key in "${pending[@]}"; do
428
+ if prompt_yn " graph.json key '$key' differs from your saved customization — update to the new default? [y/N]: "; then
429
+ answer=true
430
+ else
431
+ answer=false
432
+ fi
433
+ parts+=("\"$key\":$answer")
434
+ done
435
+ decisions="{$(IFS=,; echo "${parts[*]}")}"
436
+ fi
264
437
  fi
438
+
439
+ _graph_defaults_node "$template" "$graph_file" "$fingerprint_file" apply "$decisions"
265
440
  }
266
441
 
267
442
  # ---------------------------------------------------------------------------
@@ -140,7 +140,7 @@
140
140
  "scope": "project",
141
141
  "consumer": "installer",
142
142
  "summary": "Install default graph-view styling (.obsidian/graph.json)",
143
- "detail": "Asked by install-obsidian.sh. true installs and refreshes .obsidian/graph.json with default graph-view styling if the file is absent; false means the installer stops offering it until the key is changed or removed via /bootstrap-config. This preference is independent of obsidian.plugins — accepting or declining one has no effect on the other. The file lives inside this project's own .obsidian/ directory, which is why this key is project scope, matching obsidian.plugins's scope choice.",
143
+ "detail": "Asked by install-obsidian.sh. true installs .obsidian/graph.json and thereafter keeps it refreshed per template key (search, colorGroups, and the boilerplate display-flag keys) via a sidecar fingerprint file, .obsidian/.graph-defaults-fingerprint.json: a key untouched since the last delivery is silently refreshed to the current template value, a key the user has diverged from gets a one-time interactive prompt asking whether to update it to the new default (a decline is sticky and not re-asked until that key's template value itself changes again), and non-interactive runs never prompt and never record a decline. Force/layout keys (centerStrength, repelStrength, etc.) are never part of the template and are always left untouched regardless of this key. false means the installer stops offering the feature at all until the key is changed or removed via /bootstrap-config. This preference is independent of obsidian.plugins — accepting or declining one has no effect on the other. The file lives inside this project's own .obsidian/ directory, which is why this key is project scope, matching obsidian.plugins's scope choice.",
144
144
  "values": "true | false",
145
145
  "default": null,
146
146
  "askedBy": "install-obsidian.sh"
@@ -172,6 +172,15 @@
172
172
  "default": false,
173
173
  "askedBy": "install-global.sh"
174
174
  },
175
+ "gitCommit.lint": {
176
+ "scope": "either",
177
+ "consumer": "skill",
178
+ "summary": "Whether /git-commit runs the /lint fix-cycle before committing",
179
+ "detail": "true runs the full /lint workflow (all cycles until clean or issues are skipped) before assessing changes; false (and unset) skip it entirely — this is an opt-in, not an opt-out, so a fresh install never lints without the user having said yes. There is deliberately no 'ask' value: /git-commit never prompts about this per run, it only reads the stored answer.",
180
+ "values": "true | false",
181
+ "default": false,
182
+ "askedBy": "install-global.sh"
183
+ },
175
184
  "research.persistToRaw": {
176
185
  "scope": "either",
177
186
  "consumer": "skill",
@@ -112,7 +112,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
112
112
  5. When the chosen key has `consumer: skill`, print this heavier banner:
113
113
  > This is a **skill preference**. Changing it changes what a slash command actually does the next time it runs — not merely whether the installer asks you a question.
114
114
 
115
- Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
115
+ Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `gitCommit.lint`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
116
116
 
117
117
  ## Step E — Choose the value and the layer (edit mode)
118
118
 
@@ -10,28 +10,63 @@ user-invocable: true
10
10
 
11
11
  # git-commit
12
12
 
13
- ## Step 0: Read the two preferences that govern this skill
13
+ ## Step 0: Verify working directory, then read the three preferences that govern this skill
14
14
 
15
- Two stored preferences change what this command does. Read **both, once, before Step 1** — never mid-run, and never once per file:
15
+ ### Precondition: current directory must be the repo root
16
+
17
+ Before anything else, confirm the working directory is the repository root — every later step (`git status`/`git diff HEAD`, manifest Detection, the `--project .` preference reads below, and `git-commit`'s own `git add .`) assumes it. Running from a subdirectory would silently stage, diff, or bump only that subtree instead of the whole repo.
18
+
19
+ ```bash
20
+ cd "$(git rev-parse --show-toplevel)"
21
+ ```
22
+
23
+ If this fails (not inside a git repo at all), **STOP** and report: `/git-commit must run inside a git repository — no repo root found from the current directory.` Otherwise the working directory is now the repo root; proceed for the rest of this run without re-checking.
24
+
25
+ **Worktree-safe by construction**: `--show-toplevel` resolves to the current *worktree's own* root when run from inside a linked worktree, not the main checkout's — exactly the directory this run should operate in, so no worktree-specific branch is needed here. (Contrast with `--git-dir`/`--git-common-dir`, which resolve to the *shared* `.git` location across all worktrees — the right tool when code needs the common git directory instead, as in `file-suggestion.sh`'s worktree fix, but the wrong one here.)
26
+
27
+ ### Read the three preferences that govern this skill
28
+
29
+ Three stored preferences change what this command does. Read **all three, once, before Step 1** — never mid-run, and never once per file:
16
30
 
17
31
  ```bash
18
32
  node ~/.claude/bootstrap-prefs.js --get gitCommit.versionBump --project . 2>/dev/null || echo unset
19
33
  node ~/.claude/bootstrap-prefs.js --get gitCommit.autoPush --project . 2>/dev/null || echo unset
34
+ node ~/.claude/bootstrap-prefs.js --get gitCommit.lint --project . 2>/dev/null || echo unset
20
35
  ```
21
36
 
22
- `--project .` is required. Both keys are `scope: either`, so the answer resolves **project file → global file → schema default**; dropping the flag would read the machine-wide answer even in a repo that overrides it. If either command fails — bootstrap was never installed globally, or `node` is not on PATH — treat that answer as `unset`.
37
+ `--project .` is required. All three keys are `scope: either`, so the answer resolves **project file → global file → schema default**; dropping the flag would read the machine-wide answer even in a repo that overrides it. If any command fails — bootstrap was never installed globally, or `node` is not on PATH — treat that answer as `unset`.
38
+
39
+ `unset` means *nobody has ever been asked*. For `gitCommit.versionBump` and `gitCommit.autoPush` this keeps today's behavior; it never invents one. `gitCommit.lint` is the deliberate exception: it is opt-in by explicit design, so `unset` (and `false`) both mean **do not lint** — a fresh install must never lint before the user has said yes. Mention an `unset` key **once**, in the final report, never as a mid-run interruption.
40
+
41
+ ## Step 1: Run Lint Fix Cycles (gated on `gitCommit.lint`)
42
+
43
+ `gitCommit.lint` is `true | false`, default `false`, no `ask` value — read once in Step 0, never re-checked mid-run.
44
+
45
+ - **`true`**: run the `/lint` workflow to catch and fix any diagnostics:
46
+ 1. Execute the full `/lint` command (all cycles until clean or issues are skipped)
47
+ 2. If any fixes were applied, they will be included in the commit automatically
48
+ 3. If any issues were skipped (unfixable), warn the user before proceeding
49
+ - **`false` or `unset`**: skip this step entirely — do not invoke `/lint`. Note once in the final report when `unset`: `gitCommit.lint is unanswered — /git-commit does not lint by default. Set it with: node ~/.claude/bootstrap-prefs.js --set gitCommit.lint --value true --global` (or `false`).
50
+
51
+ ## Step 2: Condense Verbose Inline Comments
23
52
 
24
- `unset` means *nobody has ever been asked*. It always keeps today's behavior; it never invents one. Mention an `unset` key **once**, in the final report, never as a mid-run interruption.
53
+ Scan every line this commit **adds or modifies** for comments more verbose than necessary, and rewrite them to the shortest form that keeps the essential point — ideally one line.
25
54
 
26
- ## Step 1: Run Lint Fix Cycles
55
+ **Scope: diff-only, not whole-file.** Run `git diff HEAD` and look only at `+` lines. A comment already sitting untouched elsewhere in a file is out of scope — never touch a comment this commit did not add or modify.
27
56
 
28
- Before committing, run the `/lint` workflow to catch and fix any diagnostics:
57
+ **Never touch — leave exactly as-is:**
58
+ - **Structured documentation comments**, in any language: JSDoc/TSDoc (`/** ... */`, especially with `@param`/`@returns`/`@throws`/`@example`), Python docstrings (`"""..."""`/`'''...'''` directly under a `def`/`class`), Rust doc comments (`///`, `//!`), Go doc comments (the block directly above an exported declaration, starting with that declaration's own name), Java/C# Javadoc/XMLDoc blocks. These document an API's contract, not implementation rationale — condensing them destroys structure a doc generator or IDE tooltip depends on.
59
+ - **Repo-documented comment exceptions.** Before editing a file, check whether the target repo's own `CLAUDE.md` (nearest one up the directory tree) explicitly carves out a comment-density exception for that file or directory (e.g. this repo's own `CLAUDE.md`: `lib/hooks/*.js` carries inline rationale comments "by deliberate exception... do not strip them"). Skip any file covered by such an exception entirely.
60
+ - Comments already a single concise line.
29
61
 
30
- 1. Execute the full `/lint` command (all cycles until clean or issues are skipped)
31
- 2. If any fixes were applied, they will be included in the commit automatically
32
- 3. If any issues were skipped (unfixable), warn the user before proceeding
62
+ **Condense everything else:**
63
+ - If a comment restates what the code already makes obvious (the *what*) with no *why* — delete it entirely. Matches this repo's own default: "if removing the comment wouldn't confuse a future reader, don't write it."
64
+ - If it explains a genuinely non-obvious *why* (a workaround, a hidden constraint, a subtle invariant) but spans more lines or words than necessary, rewrite it to the single shortest sentence that preserves that reason.
65
+ - Preserve the comment's position (same line for a trailing comment, same location for a block comment) and its language's comment syntax — only the wording and line count change.
33
66
 
34
- ## Step 2: Assess Changes
67
+ Use `Edit` per file for every change — never `sed`/`awk`/shell rewrites.
68
+
69
+ ## Step 3: Assess Changes
35
70
 
36
71
  **Always run all three commands fresh.** Do not rely on session context, prior output, or anything produced earlier in the conversation — those reflect only a subset of what may have changed. The commit message must be based on the complete current working-tree state.
37
72
 
@@ -41,9 +76,26 @@ Run all three in parallel:
41
76
  - `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
42
77
  - `git log --oneline -10` — see recent commit history for context
43
78
 
44
- ## Step 3: Summarize Changes and Recommend Semver Bump
79
+ ## Step 4: Summarize Changes, and Recommend a Semver Bump Only If It Will Be Used
80
+
81
+ `gitCommit.versionBump` was already read in Step 0 — branch on it now, **before** doing any bump classification, so a `never` project never pays for reasoning it can't use.
82
+
83
+ ### If `gitCommit.versionBump` is `never`
84
+
85
+ No manifest will be touched and no prefix will be written (Step 5 skips straight through). Determining PATCH/MINOR/MAJOR would be pure wasted effort — skip the semver table entirely and print only:
86
+
87
+ ---
88
+
89
+ **Changes being committed:**
90
+ - <bullet list of what changed and why, derived from the diff>
91
+
92
+ ---
93
+
94
+ Then go directly to Step 6 (Commit) with a bare, unprefixed subject.
95
+
96
+ ### Otherwise (`auto`, `confirm`, or `unset`)
45
97
 
46
- Before touching any files or committing, output a summary block like this:
98
+ The bump classification is actually needed — either to write the prefix (`auto`/`unset`) or to ask about it (`confirm`, in Step 5). Output the full summary block:
47
99
 
48
100
  ---
49
101
 
@@ -64,9 +116,9 @@ Use these semver rules to determine the bump:
64
116
  | **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
65
117
  | **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
66
118
 
67
- Print the summary. What happens next is decided by `gitCommit.versionBump` from Step 0 — see the table in Step 4. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 4 where the manifest list is known.
119
+ Print the summary. What happens next is decided by the same `gitCommit.versionBump` value — see the table in Step 5. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 5 where the manifest list is known.
68
120
 
69
- ## Step 4: Bump Version in Project Files
121
+ ## Step 5: Bump Version in Project Files
70
122
 
71
123
  ### Gate: `gitCommit.versionBump`
72
124
 
@@ -77,7 +129,7 @@ Its grammar is `auto | confirm | never` — there is deliberately **no `ask` val
77
129
  | `auto` | Today's behavior. Detect every manifest and apply the bump to all of them, no confirmation. | **written** |
78
130
  | `confirm` — approved | Bump exactly as `auto` does. | **written** |
79
131
  | `confirm` — declined | Edit no manifest. | **omitted** |
80
- | `never` | Touch **no** version file at all. Skip straight to Step 5. | **omitted** |
132
+ | `never` | Touch **no** version file at all. Skip straight to Step 6. | **omitted** |
81
133
  | `unset` | Behave exactly as `auto` — that is today's behavior and an unanswered key must never change it. | **written** |
82
134
 
83
135
  `confirm` prints the suggested bump **and the full list of manifest files that would change**, then asks once with `AskUserQuestion` before editing anything. Ask **every run** and **never persist the answer** — the standing choice is "keep asking me", so recording a reply would destroy it.
@@ -97,7 +149,7 @@ Report lines, each at most once per run:
97
149
 
98
150
  Anything else stored under this key is a value from a newer bootstrap that this skill has no branch for: treat it as `unset`, and say which value you did not recognize.
99
151
 
100
- For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 5.
152
+ For `auto`, `confirm`-approved, and `unset`, continue below. For `never` and `confirm`-declined, go to Step 6.
101
153
 
102
154
  Find and update version numbers in project files.
103
155
 
@@ -118,7 +170,7 @@ Filter results:
118
170
 
119
171
  **There is no "root only" rule.** A manifest anywhere in the tree counts. Monorepo layouts with no root-level manifest are normal — update every package found.
120
172
 
121
- If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 5.
173
+ If **no files with a version field** are found anywhere in the repo, skip this step entirely and proceed to Step 6.
122
174
 
123
175
  ### Bumping rules
124
176
 
@@ -134,7 +186,7 @@ Pre-release tags (e.g. `1.0.0-beta.1`) — strip the pre-release suffix and appl
134
186
 
135
187
  Edit **every file** that contains a version using the Edit tool — do not stop at one. Then include all version-bump edits in the commit automatically (no separate commit needed).
136
188
 
137
- ## Step 5: Commit
189
+ ## Step 6: Commit
138
190
 
139
191
  ### ⛔ Never create a branch — commit on the current branch
140
192
 
@@ -144,7 +196,7 @@ Edit **every file** that contains a version using the Edit tool — do not stop
144
196
  - **ALWAYS use the `git-commit` bash alias.** Never use `git add` or `git commit` directly.
145
197
  - Always commit ALL files unless they are in `.gitignore`
146
198
  - Consider an appropriate commit message, let's call it `$message`
147
- - Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 4 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
199
+ - Prefix the subject with the bump type in brackets — `[patch]`, `[minor]`, or `[major]` — **only if Step 5 actually bumped a version**. If it did not (`never`, `confirm`-declined, or no manifest in the repo), the subject starts with the description and carries no bracket prefix
148
200
  - Run: `git-commit "$message"`
149
201
 
150
202
  ### ⛔ No agent attribution — the user is the sole author
@@ -166,7 +218,7 @@ git-commit "[patch] Single-line subject describing the change"
166
218
  git-commit "Single-line subject describing the change"
167
219
  ```
168
220
 
169
- That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 4 bumped a version.
221
+ That's it. One pair of double quotes. One line. One argument. The only difference between the two forms is whether Step 5 bumped a version.
170
222
 
171
223
  **❌ Forbidden — every one of these patterns triggers an approval prompt:**
172
224
 
@@ -225,13 +277,13 @@ If the change feels too complex to summarize in one line, **make the subject mor
225
277
  - ✅ `Allow standard tools for markdown editing; ban bash exploration commands` (no bump this run — the subject still carries its weight)
226
278
  - ❌ `Update commands` (too vague — and vague is vague with or without a prefix)
227
279
  - ❌ `[patch] Fix bug` (too vague)
228
- - ❌ `[patch] Fix the login redirect` **when Step 4 bumped nothing** (the prefix is false)
280
+ - ❌ `[patch] Fix the login redirect` **when Step 5 bumped nothing** (the prefix is false)
229
281
 
230
282
  Detailed reasoning, before/after examples, and rationale belong in **PR descriptions**, not in commit message bodies. The commit subject is the index entry; the PR is the encyclopedia.
231
283
 
232
- ## Step 6: Push (gated on `gitCommit.autoPush`)
284
+ ## Step 7: Push (gated on `gitCommit.autoPush`)
233
285
 
234
- Runs only after the commit in Step 5 succeeded. A failed commit means there is nothing to push.
286
+ Runs only after the commit in Step 6 succeeded. A failed commit means there is nothing to push.
235
287
 
236
288
  | Value | What to do |
237
289
  |-------|------------|
@@ -242,14 +294,14 @@ Runs only after the commit in Step 5 succeeded. A failed commit means there is n
242
294
 
243
295
  ### ⛔ The push is the plainest possible push
244
296
 
245
- - **The Step 5 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
297
+ - **The Step 6 branch rule is unchanged and still absolute.** Never run `git branch`, `git checkout -b`, or `git switch -c`. Pushing an existing branch is all this step ever does.
246
298
  - Never pass `--force`, `--force-with-lease`, `--set-upstream`/`-u`, `--all`, or `--tags`, and never name a different remote or refspec. Plain `git push`.
247
299
  - If the push fails for any reason — no upstream configured, no remote, rejected non-fast-forward, no credentials — **stop and report it**. The commit already succeeded and is safe; do not retry with extra flags, do not set an upstream, and do not attempt to reconcile with a pull or rebase.
248
300
 
249
- ## Step 7: Final report
301
+ ## Step 8: Final report
250
302
 
251
303
  One short report at the end. Include, in this order:
252
304
 
253
305
  1. The commit subject that was written.
254
- 2. Any of the once-only preference notes from Steps 4 and 6 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
306
+ 2. Any of the once-only preference notes from Steps 1, 5, and 7 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
255
307
  3. The push outcome (pushed / not pushed and why / push failed and how).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewizard-dt/bootstrap",
3
- "version": "3.0.1",
3
+ "version": "3.2.0",
4
4
  "description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
5
5
  "homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
6
6
  "bugs": {