@codewizard-dt/bootstrap 5.1.0 → 6.0.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/README.md +11 -3
- package/bin/cli.js +16 -0
- package/lib/hooks/README.md +124 -3
- package/lib/hooks/claude-settings-guard.js +8 -2
- package/lib/prompts/README.md +1 -1
- package/lib/prompts/migrate-wiki.md +7 -7
- package/lib/scripts/README.md +111 -10
- package/lib/scripts/bootstrap-prefs-tui.js +1222 -0
- package/lib/scripts/install-global.sh +137 -6
- package/lib/scripts/migrate-project.sh +52 -10
- package/lib/scripts/rename-wiki-ids.js +232 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +6 -6
- package/lib/scripts/templates/bootstrap-prefs-schema.json +11 -2
- package/lib/scripts/templates/settings-sandbox-unattended.json +36 -0
- package/lib/scripts/templates/settings-sandbox.json +7 -0
- package/lib/scripts/templates/wiki/conventions.md +12 -10
- package/lib/scripts/templates/wiki/dashboard.html +527 -23
- package/lib/scripts/templates/wiki/index.md +2 -2
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +1 -1
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -4
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +11 -9
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -4
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +8 -8
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +11 -3
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +7 -5
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +16 -8
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +3 -3
- package/lib/scripts/wiki-dashboard-server.js +98 -0
- package/lib/skills/README.md +27 -22
- package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +103 -0
- package/lib/skills/_shared/ID-RESOLUTION.md +142 -0
- package/lib/skills/_shared/SKILL-BOILERPLATE.md +50 -0
- package/lib/skills/adr-assess/SKILL.md +112 -0
- package/lib/skills/{decision-create → adr-create}/SKILL.md +27 -26
- package/lib/skills/adr-deprecate/SKILL.md +190 -0
- package/lib/skills/adr-extract/SKILL.md +255 -0
- package/lib/skills/{decision-finalize → adr-finalize}/SKILL.md +38 -38
- package/lib/skills/{decision-next → adr-next}/SKILL.md +20 -19
- package/lib/skills/{decision-walkthrough → adr-walkthrough}/SKILL.md +23 -29
- package/lib/skills/architecture-audit/SKILL.md +24 -3
- package/lib/skills/autopilot/SKILL.md +110 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +3 -3
- package/lib/skills/bug-close/SKILL.md +15 -26
- package/lib/skills/{bug-file → bug-create}/SKILL.md +25 -15
- package/lib/skills/bug-triage/SKILL.md +5 -19
- package/lib/skills/demo/SKILL.md +11 -11
- package/lib/skills/elevator-pitch/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +29 -87
- package/lib/skills/git-commit/SKILL.md +4 -4
- package/lib/skills/marp-slideshow/SKILL.md +2 -2
- package/lib/skills/port-feature/SKILL.md +28 -83
- package/lib/skills/power-mode/SKILL.md +42 -49
- package/lib/skills/prd-assess/SKILL.md +105 -0
- package/lib/skills/{req-compile → prd-compile}/SKILL.md +6 -13
- package/lib/skills/{req-create → prd-create}/SKILL.md +19 -19
- package/lib/skills/prd-deprecate/SKILL.md +173 -0
- package/lib/skills/{req-finalize → prd-finalize}/SKILL.md +20 -29
- package/lib/skills/primer/SKILL.md +2 -2
- package/lib/skills/research/SKILL.md +3 -3
- package/lib/skills/roadmap-assess/SKILL.md +20 -20
- package/lib/skills/roadmap-create/SKILL.md +23 -29
- package/lib/skills/roadmap-next/SKILL.md +16 -28
- package/lib/skills/security-audit/SKILL.md +3 -3
- package/lib/skills/tackle/SKILL.md +13 -15
- package/lib/skills/{task-audit → task-assess}/SKILL.md +34 -44
- package/lib/skills/task-close/SKILL.md +73 -0
- package/lib/skills/{task-add → task-create}/SKILL.md +44 -24
- package/lib/skills/uat-assess/SKILL.md +124 -0
- package/lib/skills/uat-auto/SKILL.md +9 -6
- package/lib/skills/uat-auto-plus/SKILL.md +2 -2
- package/lib/skills/{uat-generate → uat-create}/SKILL.md +10 -12
- package/lib/skills/uat-skip/SKILL.md +5 -9
- package/lib/skills/uat-walk/SKILL.md +2 -2
- package/lib/skills/uat-walk/UAT-CORE.md +29 -16
- package/lib/skills/update-docs/SKILL.md +1 -1
- package/lib/skills/usage-report/SKILL.md +52 -0
- package/lib/skills/usage-report/scripts/pricing.json +22 -0
- package/lib/skills/usage-report/scripts/usage-report.js +518 -0
- package/lib/skills/whats-next/SKILL.md +177 -0
- package/lib/skills/wiki-archive/SKILL.md +12 -23
- package/lib/skills/wiki-lint/SKILL.md +42 -5
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
- package/lib/skills/wiki-tidy/SKILL.md +6 -9
- package/package.json +1 -1
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +0 -10
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +0 -10
- package/lib/skills/req-extract-decisions/SKILL.md +0 -241
- package/lib/skills/req-retire/SKILL.md +0 -185
- package/lib/skills/req-update/SKILL.md +0 -265
- package/lib/skills/task-trash/SKILL.md +0 -115
- package/lib/skills/task-update/SKILL.md +0 -136
package/README.md
CHANGED
|
@@ -26,10 +26,12 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
26
26
|
|
|
27
27
|
- **Responsibility:** Routes `bootstrap <command>` and `npx @codewizard-dt/bootstrap <command>` invocations to the appropriate setup script.
|
|
28
28
|
- **Tech:** Node.js CommonJS, `child_process.execFileSync`
|
|
29
|
-
- **Inputs:** Commands such as `setup`, `update`, `install`, `migrate`, `typechecks`, and `
|
|
29
|
+
- **Inputs:** Commands such as `setup`, `update`, `install`, `migrate`, `typechecks`, `dashboard`, and `config`, plus optional extra arguments for migration, dashboard (port override), and config (`--get` / `--set` / `--unset` / `--list` passthrough, `--global` / `--project <dir>` scope) flows.
|
|
30
30
|
- **Outputs:** Executes the selected script with inherited stdio and propagates the script exit status.
|
|
31
31
|
- **Depends on:** Setup Scripts
|
|
32
32
|
|
|
33
|
+
`bootstrap config` (`npx @codewizard-dt/bootstrap config`) is the non-Claude-Code way to view and edit `bootstrap-prefs.json`: with no arguments it opens an interactive menu, and with `--get` / `--set <key> --value <v>` / `--unset` / `--list` it passes straight through for scripting. `/bootstrap-config` is the in-session equivalent; both front ends delegate to `lib/scripts/bootstrap-prefs.js`, so they always agree. It manages `bootstrap-prefs.json` only, not Claude Code's own `settings.json`.
|
|
34
|
+
|
|
33
35
|
#### Setup Scripts
|
|
34
36
|
|
|
35
37
|
- **Responsibility:** Coordinate project setup, updates, global installs, Serena bootstrapping, wiki migration, and strict type-checking setup.
|
|
@@ -64,10 +66,10 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
64
66
|
|
|
65
67
|
#### Wiki Scaffold Templates
|
|
66
68
|
|
|
67
|
-
- **Responsibility:** Defines the LLM Wiki directory structure, conventions, lifecycle specs, indexes, archive folders, and Claude guidance installed into target projects.
|
|
69
|
+
- **Responsibility:** Defines the LLM Wiki directory structure, conventions, lifecycle specs, indexes (Active/Closed sections for roadmaps, decisions and requirements), archive folders (tasks, UAT and bugs only), and Claude guidance installed into target projects.
|
|
68
70
|
- **Tech:** Markdown templates under `lib/scripts/templates/wiki/`, `CLAUDE.md` snippets, `.gitkeep` files
|
|
69
71
|
- **Inputs:** Target project path and `sync-wiki-scaffold.sh` copy policy.
|
|
70
|
-
- **Outputs:** `raw/`, `wiki/knowledge/`, `wiki/work/`, lifecycle files, family indexes, archive directories, `wiki/conventions.md`, `wiki/log.md`, and target-project `CLAUDE.md` additions.
|
|
72
|
+
- **Outputs:** `raw/`, `wiki/knowledge/`, `wiki/work/`, lifecycle files, family indexes, archive directories (tasks, UAT, bugs), `wiki/conventions.md`, `wiki/log.md`, and target-project `CLAUDE.md` additions.
|
|
71
73
|
- **Depends on:** Setup Scripts
|
|
72
74
|
|
|
73
75
|
#### Guide Stubs
|
|
@@ -341,8 +343,14 @@ node bin/cli.js setup
|
|
|
341
343
|
# Serves on http://localhost:4317 by default; pass a port to override
|
|
342
344
|
node bin/cli.js dashboard
|
|
343
345
|
node bin/cli.js dashboard 4400
|
|
346
|
+
|
|
347
|
+
# Edit bootstrap preferences from a plain terminal (no Claude Code session needed)
|
|
348
|
+
node bin/cli.js config
|
|
349
|
+
node bin/cli.js config --set <key> --value <value> --global
|
|
344
350
|
```
|
|
345
351
|
|
|
352
|
+
The dashboard also shows the local `/usage-report` rollup at `#/usage`, computed on demand from local transcripts and cached for 30 s.
|
|
353
|
+
|
|
346
354
|
The setup command writes to the current project and to `~/.claude/`, so run it from a disposable test repository when validating a release candidate.
|
|
347
355
|
|
|
348
356
|
### Deploy
|
package/bin/cli.js
CHANGED
|
@@ -6,6 +6,18 @@ const path = require('path');
|
|
|
6
6
|
const command = process.argv[2];
|
|
7
7
|
const extraArgs = process.argv.slice(3);
|
|
8
8
|
|
|
9
|
+
const PREFS_OPERATION_FLAGS = ['--get', '--set', '--unset', '--list', '--section-key'];
|
|
10
|
+
|
|
11
|
+
function configTarget(extraArgs) {
|
|
12
|
+
if (extraArgs.length === 0) {
|
|
13
|
+
return { script: 'bootstrap-prefs-tui.js', args: [] };
|
|
14
|
+
}
|
|
15
|
+
if (extraArgs.some((a) => PREFS_OPERATION_FLAGS.includes(a))) {
|
|
16
|
+
return { script: 'bootstrap-prefs.js', args: extraArgs };
|
|
17
|
+
}
|
|
18
|
+
return { script: 'bootstrap-prefs-tui.js', args: extraArgs };
|
|
19
|
+
}
|
|
20
|
+
|
|
9
21
|
const SCRIPTS = {
|
|
10
22
|
setup: { script: 'setup-project.sh', args: ['.'] },
|
|
11
23
|
update: { script: 'update-project.sh', args: ['.'] },
|
|
@@ -13,6 +25,7 @@ const SCRIPTS = {
|
|
|
13
25
|
migrate: { script: 'migrate-project.sh', args: ['.', ...extraArgs] },
|
|
14
26
|
typechecks: { script: 'setup-strict-typechecks.sh', args: extraArgs },
|
|
15
27
|
dashboard: { script: 'wiki-dashboard-server.js', args: ['.', ...extraArgs] },
|
|
28
|
+
config: configTarget(extraArgs),
|
|
16
29
|
};
|
|
17
30
|
|
|
18
31
|
if (!command || !SCRIPTS[command]) {
|
|
@@ -23,11 +36,14 @@ if (!command || !SCRIPTS[command]) {
|
|
|
23
36
|
console.error(' update Sync wiki scaffold and install skills globally');
|
|
24
37
|
console.error(' install Install skills globally into ~/.claude/skills/');
|
|
25
38
|
console.error(' migrate Migrate a legacy .docs/ project to the wiki structure (Claude-driven)');
|
|
39
|
+
console.error(' and rename DEC-/REQ- work items to ADR-/PRD- (deterministic)');
|
|
26
40
|
console.error(' Pass --dry-run to preview; runs on a fresh wiki-migration branch');
|
|
27
41
|
console.error(' typechecks Run strict typecheck setup via Claude (optional: language list)');
|
|
28
42
|
console.error(' e.g. bootstrap typechecks typescript python');
|
|
29
43
|
console.error(' dashboard Launch the live wiki/work dashboard in this project (Ctrl-C to stop)');
|
|
30
44
|
console.error(' Optional: pass a port number, e.g. bootstrap dashboard 4400');
|
|
45
|
+
console.error(' config View or change bootstrap preferences (interactive menu, no Claude Code needed)');
|
|
46
|
+
console.error(' Scripting: bootstrap config --get <key> | --set <key> --value <v> (--global | --project <dir>) | --unset <key> | --list');
|
|
31
47
|
process.exit(1);
|
|
32
48
|
}
|
|
33
49
|
|
package/lib/hooks/README.md
CHANGED
|
@@ -32,6 +32,122 @@ cannot enumerate — and it can return a **message** explaining the block, which
|
|
|
32
32
|
exiting 2 stops a call the rules would never see. Keep a matching `deny` entry
|
|
33
33
|
too — defence in depth, and the rules keep working if a hook ever fails to fire.
|
|
34
34
|
|
|
35
|
+
## Tier 3: sandbox
|
|
36
|
+
|
|
37
|
+
The controls stack in three tiers, and each one covers what the one above it
|
|
38
|
+
structurally cannot:
|
|
39
|
+
|
|
40
|
+
1. **Deny rules match spellings.** `Bash(rm -rf ~*)` stops that string and nothing
|
|
41
|
+
phrased differently.
|
|
42
|
+
2. **Hooks parse commands.** They read the actual command text, so they catch the
|
|
43
|
+
variants a pattern cannot enumerate — but only the *text*. No hook parses inside
|
|
44
|
+
a script file, so `node write-settings.js` reaches `~/.claude/settings.json`
|
|
45
|
+
even though `node -e`, a `>` redirect, and the `Edit` tool are all blocked (see
|
|
46
|
+
[`claude-settings-guard.js`](#claude-settings-guardjs) § Residual risk).
|
|
47
|
+
3. **The sandbox confines the process.** The OS enforces it on the running
|
|
48
|
+
process, not on the command's text, so a script file gets no special treatment.
|
|
49
|
+
Claude Code denies a sandboxed command write access to `settings.json` at every
|
|
50
|
+
scope and to the managed settings directory — a sandboxed agent cannot rewrite
|
|
51
|
+
its own policy.
|
|
52
|
+
|
|
53
|
+
**Status: shipped, runtime proof pending.** The configuration exists and its shape
|
|
54
|
+
is covered by tests, but the proof that a sandboxed `node <script>` write to
|
|
55
|
+
`settings.json` actually fails (and succeeds outside the sandbox, and holds under
|
|
56
|
+
`--dangerously-skip-permissions`) has **not** been run. It is deferred to the UAT of
|
|
57
|
+
TASK-031. Until that passes, treat the script-file gap as covered on paper, not as
|
|
58
|
+
verified closed.
|
|
59
|
+
|
|
60
|
+
**What shipped.** `lib/scripts/templates/settings-sandbox-unattended.json`, a
|
|
61
|
+
standalone settings file (`{"sandbox": {...}}`). `install-global.sh` (block "6b")
|
|
62
|
+
copies it to `~/.claude/templates/settings-sandbox-unattended.json` and does **not**
|
|
63
|
+
merge it into `settings.json`. It is applied per session, at the launcher of an
|
|
64
|
+
unattended run — the same place that passes `--dangerously-skip-permissions`:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
claude --settings ~/.claude/templates/settings-sandbox-unattended.json --dangerously-skip-permissions
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Subagents inherit the parent session's sandbox, so one flag covers every
|
|
71
|
+
`power-mode` child. A skill cannot turn the sandbox on — it is read by an
|
|
72
|
+
already-running session — so it must be on when the session starts. See
|
|
73
|
+
`lib/scripts/README.md` § Unattended-run sandbox profile for the install and
|
|
74
|
+
launcher details.
|
|
75
|
+
|
|
76
|
+
**Scope: unattended runs only, on purpose.** A user-scope `sandbox.enabled: true`
|
|
77
|
+
would sandbox every session, including the human's, and the installer
|
|
78
|
+
(`install-global.sh`, `setup`, `update`) and every nested-`claude` script
|
|
79
|
+
(`bootstrap-serena.sh`, `setup-strict-typechecks.sh`, `migrate-project.sh`) break
|
|
80
|
+
inside a sandboxed Bash by design. Those are exactly the runs a human drives, and
|
|
81
|
+
a sandboxed agent being unable to rewrite its own policy is the feature, not a
|
|
82
|
+
defect. So the profile is a per-session `--settings` file rather than a merged key.
|
|
83
|
+
It is also inert on a platform with no sandbox backend unless a launcher passes it.
|
|
84
|
+
|
|
85
|
+
**What the profile sets, and why:**
|
|
86
|
+
|
|
87
|
+
- `enabled` and `failIfUnavailable` — fail closed. Without the latter, Claude Code
|
|
88
|
+
warns and runs unsandboxed when the backend is missing.
|
|
89
|
+
- `allowUnsandboxedCommands: false` — the `dangerouslyDisableSandbox` escape is
|
|
90
|
+
ignored.
|
|
91
|
+
- `network.strictAllowlist: true` — without it, `bypassPermissions` opens every host
|
|
92
|
+
not on the allowlist, so `allowedDomains` would give no egress control at all.
|
|
93
|
+
Needs Claude Code v2.1.219 or later, and only takes effect from user, managed, or
|
|
94
|
+
`--settings` scope, which is why the profile is a `--settings` file.
|
|
95
|
+
- **No `excludedCommands`.** When any part of a compound command matches an
|
|
96
|
+
exclusion, the whole command runs unsandboxed, so `docker ps && node
|
|
97
|
+
write-settings.js` escapes entirely. A `docker *` exclusion would re-open the
|
|
98
|
+
script-file hole this tier exists to close.
|
|
99
|
+
- `network.allowLocalBinding` — the unattended workloads (`uat-auto-plus` dev
|
|
100
|
+
servers) bind localhost.
|
|
101
|
+
- `filesystem.denyRead` for `~/.ssh` and `~/.gnupg`, plus `credentials` deny entries
|
|
102
|
+
(files and environment variables), because the default read policy is the whole
|
|
103
|
+
machine.
|
|
104
|
+
- A small `network.allowedDomains` list (package registries and github.com).
|
|
105
|
+
Projects extend it; arrays merge across scopes.
|
|
106
|
+
|
|
107
|
+
**Coexistence with the opt-in starter.** `bootstrap install` can separately offer
|
|
108
|
+
the user-scope starter block (`settings-sandbox.json`, see `lib/scripts/README.md`
|
|
109
|
+
§ Sandbox scaffold notes), which *does* carry `docker *` exclusions. Arrays merge
|
|
110
|
+
across scopes, so a user who opted into the starter carries those `docker *`
|
|
111
|
+
entries into an unattended run, and a compound command matching one runs wholly
|
|
112
|
+
unsandboxed. The starter's docker trade is reasonable for interactive use; it is
|
|
113
|
+
the wrong trade for the run this profile exists for. Know which you have.
|
|
114
|
+
|
|
115
|
+
**The installer must run outside the sandbox.** Run `bootstrap install`, `setup`,
|
|
116
|
+
and `update` from a normal shell, never through a sandboxed session's Bash tool:
|
|
117
|
+
the sandbox denies writes under `~/.claude`, including `settings.json` at every
|
|
118
|
+
scope, and no `allowWrite` entry lifts that. The nested-`claude` scripts
|
|
119
|
+
(`bootstrap-serena.sh`, `setup-strict-typechecks.sh`, `migrate-project.sh`) fail
|
|
120
|
+
the same way when launched from a sandboxed Bash.
|
|
121
|
+
|
|
122
|
+
**Limits, stated plainly.** A reader who thinks the sandbox is total is worse off
|
|
123
|
+
than one who knows its edges.
|
|
124
|
+
|
|
125
|
+
- **Bash and its child processes only.** `Read`, `Edit`, and `Write`, Serena and
|
|
126
|
+
every other MCP server, and hooks all run outside the sandbox. The file-tool
|
|
127
|
+
guards ([`claude-settings-guard.js`](#claude-settings-guardjs),
|
|
128
|
+
[`protected-write-guard.js`](#protected-write-guardjs)) and the deny list stay
|
|
129
|
+
load-bearing; the sandbox does not replace them.
|
|
130
|
+
- **Credentials are readable by default** unless configured. The profile closes a
|
|
131
|
+
specific list of paths and variables, not everything on the machine.
|
|
132
|
+
- **The network proxy does not terminate TLS by default**, so domain fronting can
|
|
133
|
+
reach hosts that are not on the allowlist.
|
|
134
|
+
- **Not available everywhere.** macOS uses Seatbelt; Linux and WSL2 use bubblewrap
|
|
135
|
+
plus socat; native Windows and WSL1 are unsupported. It therefore cannot be a hard
|
|
136
|
+
requirement of this template.
|
|
137
|
+
- **Not sufficient on its own for fully unattended runs.** The Claude Code docs say
|
|
138
|
+
so themselves for bypass and auto modes and recommend a container or VM. This
|
|
139
|
+
profile narrows what a compromised agent can do on the host; it is not that.
|
|
140
|
+
- **Runtime behaviour is unproven** — see the status note above.
|
|
141
|
+
|
|
142
|
+
**The strict end of the range: managed settings.** A solo developer with `sudo` can
|
|
143
|
+
apply managed settings on macOS (`/Library/Application Support/ClaudeCode/`); this is
|
|
144
|
+
not MDM-only. Managed settings cannot be overridden by `--settings`. This is
|
|
145
|
+
documented as an option and **not shipped**. Three managed keys are recorded
|
|
146
|
+
footguns for this repo and are set nowhere: `disableBypassPermissionsMode` (breaks
|
|
147
|
+
`uat-auto-plus`, `power-mode`, `setup-strict-typechecks.sh`, and
|
|
148
|
+
`migrate-project.sh`), `allowManagedPermissionRulesOnly` (nullifies the whole deny
|
|
149
|
+
list), and `allowManagedHooksOnly` (disables every hook this repo installs).
|
|
150
|
+
|
|
35
151
|
## Commenting standard
|
|
36
152
|
|
|
37
153
|
**The repo-wide "no comments" default is suspended in `lib/hooks/`, and only
|
|
@@ -538,9 +654,14 @@ catches `node -e`, but a script written to disk and then executed is uncovered b
|
|
|
538
654
|
design.
|
|
539
655
|
|
|
540
656
|
So this is a guardrail, not a boundary: it closes the casual and accidental paths
|
|
541
|
-
— which is most of them — and raises the cost of the deliberate one. The
|
|
542
|
-
|
|
543
|
-
|
|
657
|
+
— which is most of them — and raises the cost of the deliberate one. The
|
|
658
|
+
containment for a compromised agent is OS-level sandboxing (`/sandbox`).
|
|
659
|
+
`bootstrap install` can now scaffold a minimal starter `sandbox` block on opt-in
|
|
660
|
+
(see `lib/scripts/README.md` § Sandbox scaffold notes), which by itself does not
|
|
661
|
+
close the script-file gap above. The profile built to close it is the shipped
|
|
662
|
+
unattended-run profile described in [Tier 3: sandbox](#tier-3-sandbox) — shipped,
|
|
663
|
+
runtime proof pending in the UAT of TASK-031, so not yet verified closed. Do not
|
|
664
|
+
read "unconditional" as "guaranteed".
|
|
544
665
|
|
|
545
666
|
**Not covered, deliberately:** project-level `.claude/settings.json` files (this
|
|
546
667
|
hook is scoped to the user-global `~/.claude/` tree); and writing a script
|
|
@@ -61,8 +61,14 @@
|
|
|
61
61
|
//
|
|
62
62
|
// So this is a guardrail, not a boundary: it closes the casual and accidental
|
|
63
63
|
// paths, which is most of them, and raises the cost of the deliberate one. The
|
|
64
|
-
//
|
|
65
|
-
//
|
|
64
|
+
// containment for the script-file path is Tier 3 (OS-level sandbox): shipped as
|
|
65
|
+
// lib/scripts/templates/settings-sandbox-unattended.json, applied per session
|
|
66
|
+
// with `claude --settings` on unattended runs. Its runtime proof is still
|
|
67
|
+
// pending (UAT of TASK-031), so treat the gap as covered on paper, not
|
|
68
|
+
// verified closed. See README.md § Tier 3: sandbox for the profile and its
|
|
69
|
+
// limits (Bash and children only — this hook and the deny list stay
|
|
70
|
+
// load-bearing for the file tools). Do not read the unconditional block as a
|
|
71
|
+
// guarantee.
|
|
66
72
|
//
|
|
67
73
|
// Known gaps, deliberate:
|
|
68
74
|
// - Project-level `.claude/settings.json` files are not guarded here; this
|
package/lib/prompts/README.md
CHANGED
|
@@ -4,7 +4,7 @@ Markdown prompt templates for setup steps that are too context-sensitive for a s
|
|
|
4
4
|
|
|
5
5
|
| Prompt | Driven by | Purpose |
|
|
6
6
|
|--------|-----------|---------|
|
|
7
|
-
| `migrate-wiki.md` | `lib/scripts/migrate-project.sh` | Drives the semantic conversion from a legacy `.docs/`-layout project to the LLM Wiki structure, after `sync-wiki-scaffold.sh` has already created the empty scaffold. Runs headlessly with only Bash/Read/Edit/Write (explicitly told not to look for Serena MCP tools). Hard rules: `git mv` every file before editing it (preserves history), never touch `raw/` or template-owned files (`wiki/conventions.md`, `lifecycle.md`), never move a file once it lands at its new path, and never commit — leaves everything staged for the user to review. Contains the full old-path → new-path mapping table (`.docs/tasks/` → `wiki/work/tasks/TASK-NNN`, `.docs/adr/` → `wiki/work/decisions/
|
|
7
|
+
| `migrate-wiki.md` | `lib/scripts/migrate-project.sh` | Drives the semantic conversion from a legacy `.docs/`-layout project to the LLM Wiki structure, after `sync-wiki-scaffold.sh` has already created the empty scaffold. Runs headlessly with only Bash/Read/Edit/Write (explicitly told not to look for Serena MCP tools). Hard rules: `git mv` every file before editing it (preserves history), never touch `raw/` or template-owned files (`wiki/conventions.md`, `lifecycle.md`), never move a file once it lands at its new path, and never commit — leaves everything staged for the user to review. Contains the full old-path → new-path mapping table (`.docs/tasks/` → `wiki/work/tasks/TASK-NNN`, `.docs/adr/` → `wiki/work/decisions/ADR-NNNN`, etc.) and the per-family status-inference rules. |
|
|
8
8
|
| `setup-strict-typechecks.md` | `lib/scripts/setup-strict-typechecks.sh` | Scans the repo for every language with a type-checking/linting story, researches current strict-mode conventions per language (TypeScript `strict` + `typescript-eslint` strictTypeChecked, Python `mypy --strict`, Go `staticcheck`/`vet`, Rust `deny(warnings)`/Clippy, …) via Context7/Brave Search, installs the required toolchain packages, and wires the config files plus a `make typecheck` target. Accepts an optional language list from the script's CLI args to scope the run. |
|
|
9
9
|
| `setup-design-system.md` | *(none — not currently invoked by any script)* | A generic prompt for wiring an arbitrary design system into a frontend app: migrate tokens/assets into `<APP_SRC_PATH>/design-system/`, wire the CSS import into the app entry point, then convert each prototype reference component into a typed production component driven entirely by CSS custom properties. Takes `<DESIGN_SYSTEM_PATH>`, `<APP_SRC_PATH>`, `<APP_ROUTES_PATH>`, and `<SKILL_NAME>` placeholders. Kept for manual reuse (`claude < setup-design-system.md` with placeholders filled in) when onboarding a design system other than the one `lib/skills/frontend-taste` already automates (house-style, from `~/code/house-style`). |
|
|
10
10
|
|
|
@@ -36,9 +36,9 @@ This prompt runs headlessly. **Only these tools are available:**
|
|
|
36
36
|
| `.docs/uat/skipped/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` | `skipped` |
|
|
37
37
|
| `.docs/uat/trashed/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` | `trashed` |
|
|
38
38
|
| `.docs/uat/screenshots/*` | `wiki/work/uat/screenshots/` | — (binary assets, just `git mv`) |
|
|
39
|
-
| `.docs/adr/NNNN-slug.md` and `.docs/adr/completed/NNNN-slug.md` | `wiki/work/decisions/
|
|
40
|
-
| `.docs/prd/NNN-slug.md` | `wiki/work/requirements/
|
|
41
|
-
| `.docs/prd/archived/NNN-slug.md` | `wiki/work/requirements/
|
|
39
|
+
| `.docs/adr/NNNN-slug.md` and `.docs/adr/completed/NNNN-slug.md` | `wiki/work/decisions/ADR-NNNN-slug.md` | no file-level status — each `## DM.` block keeps its own `Status` field verbatim |
|
|
40
|
+
| `.docs/prd/NNN-slug.md` | `wiki/work/requirements/PRD-NNN-slug.md` | from old frontmatter/body (`draft` or `approved`) |
|
|
41
|
+
| `.docs/prd/archived/NNN-slug.md` | `wiki/work/requirements/PRD-NNN-slug.md` | `retired` |
|
|
42
42
|
| `.docs/bugs/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `open` |
|
|
43
43
|
| `.docs/bugs/in-progress/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `in-progress` |
|
|
44
44
|
| `.docs/bugs/closed/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `closed` |
|
|
@@ -54,14 +54,14 @@ For every artifact file, in this order:
|
|
|
54
54
|
|
|
55
55
|
1. **`git mv`** to its new path (per the mapping table).
|
|
56
56
|
2. **Normalize frontmatter.** Add a YAML frontmatter block if missing; if one exists, update it in place, preserving any extra keys:
|
|
57
|
-
- `id:` — from the new filename prefix (e.g. `TASK-014`, `
|
|
57
|
+
- `id:` — from the new filename prefix (e.g. `TASK-014`, `ADR-0007`)
|
|
58
58
|
- `title:` — from the first H1 heading; fall back to a humanized filename slug
|
|
59
59
|
- `status:` — per the mapping table (decisions: no file-level status)
|
|
60
60
|
- `created:` / `updated:` — from `git log --follow --format=%ad --date=short -- <file>`; oldest commit date = created, newest = updated; fall back to today's date if no history
|
|
61
61
|
3. **Rewrite in-body links and references:**
|
|
62
62
|
- Relative artifact links in any form (`../tasks/NNN-slug.md`, `completed/NNN-slug.md`, `.docs/tasks/NNN-slug.md`, etc.) → the flat new path with the new ID-prefixed filename (e.g. `../tasks/TASK-014-slug.md` from a UAT file, `TASK-014-slug.md` from a sibling task)
|
|
63
|
-
- `**Implements**: ADR-NNNN#DM` → `implements::[[
|
|
64
|
-
- All other `ADR-NNNN` mentions → `
|
|
63
|
+
- `**Implements**: ADR-NNNN#DM` → `implements::[[ADR-NNNN#DM]]`
|
|
64
|
+
- All other `ADR-NNNN` mentions → unchanged (`ADR-NNNN` is the current decision ID form)
|
|
65
65
|
- `.uat.md` link suffixes → the new `UAT-NNN-slug.md` form
|
|
66
66
|
|
|
67
67
|
## Cross-links (UAT ↔ task)
|
|
@@ -82,7 +82,7 @@ If the same number exists in two source dirs of one family (e.g. `.docs/tasks/00
|
|
|
82
82
|
|
|
83
83
|
After all files have landed, build each `wiki/work/<family>/index.md` (replace the `_(none yet)_` placeholder) listing **only active items**, per each family's `lifecycle.md`:
|
|
84
84
|
|
|
85
|
-
- requirements: `draft`, `approved` · decisions: groups with ≥1 `proposed` block · roadmaps: `active` · tasks: `todo`, `in-progress` · uat: `pending`, `in-progress`, `failed` · bugs: `open`, `triaged`, `in-progress`
|
|
85
|
+
- requirements: `draft`, `approved` · decisions: groups with ≥1 `proposed` block · roadmaps: `active` · tasks: `todo`, `in-progress`, `pending-uat` · uat: `pending`, `in-progress`, `failed` · bugs: `open`, `triaged`, `in-progress`
|
|
86
86
|
|
|
87
87
|
Entry format is documented in each index stub. Non-active items are simply not listed — their files stay put.
|
|
88
88
|
|
package/lib/scripts/README.md
CHANGED
|
@@ -10,8 +10,8 @@ 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. |
|
|
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
|
|
14
|
-
| `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
|
|
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-*`; a listed name that ships again in `lib/skills/` is live and is never listed, prompted about, or pruned), 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 6b copies `templates/settings-sandbox-unattended.json` → `~/.claude/templates/settings-sandbox-unattended.json` (copy only, never merged — see [Unattended-run sandbox profile](#unattended-run-sandbox-profile)). 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. Step 7b (`configure_sandbox`, between steps 7 and 8 — no renumbering) is the opt-in Claude Code sandbox question — see [Sandbox scaffold notes](#sandbox-scaffold-notes); it is wrapped so a failure warns and continues, and the closing "Global setup complete" summary appends `+ sandbox` only when the step actually merged or confirmed the block. 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
|
+
| `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. Also renames already-migrated wiki work items from the pre-rename IDs (`DEC-NNNN` → `ADR-NNNN`, `REQ-NNNN` → `PRD-NNNN`) via `rename-wiki-ids.js` — this runs first, needs no legacy `.docs/`, and when there is nothing else to migrate the run ends there (no scaffold sync, no Claude call). `--dry-run` prints the file inventory and the rename plan and does not touch anything. |
|
|
15
15
|
| `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`. |
|
|
16
16
|
| `wiki-dashboard-server.js` | `dashboard` | Zero-dependency Node static file server (Node builtins only) that serves the live wiki dashboard client (`templates/wiki/dashboard.html`) at `/` and the project's `wiki/` tree read-only under `/wiki/*`, all with `no-store` cache headers so the polling client always sees current content. Runs in the foreground until Ctrl-C. Binds `http://localhost:4317` by default; pass a port to override (`bootstrap dashboard 4400`), and falls back to the next port (up to 10 tries) if the chosen one is in use. Unlike the other CLI scripts, this is Node, not Bash, and is long-running rather than one-shot. |
|
|
17
17
|
|
|
@@ -24,6 +24,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
24
24
|
| `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
|
|
25
25
|
| `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
|
|
26
26
|
| `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
|
|
27
|
+
| `rename-wiki-ids.js` | `migrate-project.sh` (invoked via `node`; `--count` and `--dry-run` for the preflight/preview) | Zero-dependency Node script that renames `DEC-NNNN` → `ADR-NNNN` (`wiki/work/decisions/`) and `REQ-NNNN` → `PRD-NNNN` (`wiki/work/requirements/`) in an existing wiki: renames the files (active + `archive/`; `git mv` when tracked, plain rename otherwise), rewrites every reference to a renamed ID in `wiki/**/*.md` (`id:`, `[[…]]` links with `#DM` anchors, typed links, link text and relative link targets), keeps the old ID as an alias on each renamed file, and appends one entry to `wiki/log.md`. Only IDs that belong to a renamed file are rewritten, so look-alike text (e.g. a PRD's own "REQ-1 … REQ-2" list) is left alone; existing log entries and `raw/` are never edited. Idempotent; exits 1 without changing anything if a target name already exists. Unlike `backfill-wiki-aliases.js`, failures are not swallowed — it is an explicit command. Renamed skill names mentioned in prose are not rewritten. |
|
|
27
28
|
| `backfill-wiki-aliases.js` | `lib.sh` (`run_project_sync`, unguarded — invoked via `node`, not direct exec) | Zero-dependency Node script that re-runs TASK-064's one-time sweep on every `setup`/`update`: scans every `wiki/work/<family>/` file (active + `archive/`, all 6 families) for one that carries `id:` but no `aliases:` yet, and inserts `aliases: [<id>]` immediately after the `id:` line. Idempotent and additive-only — a file that already has `aliases:` (inline or block-list form) is left completely untouched, never corrected or overwritten. Fixes drift (a hand-authored file, an older bootstrap checkout, a merge) that would otherwise leave a bare `[[TASK-NNN]]`-style wikilink dead in Obsidian — see `wiki/knowledge/sources/obsidian-alias-link-resolution.md` for why. Deliberately **out of scope: `wiki/knowledge/`** — a knowledge page's filename already equals its `id:` slug, so its wikilinks already resolve on Obsidian's plain filename match with no alias needed, and existing knowledge-page aliases are curated alternate names a script has no safe way to invent. Always exits 0 (same contract as `merge-settings-deny.js`/`merge-settings-hooks.js`) — warns and skips on anything unexpected rather than aborting the caller. |
|
|
28
29
|
| `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 every machine-local exclusion this script manages — the wiki/agent-state dirs AND the `.claude/bootstrap-prefs.*` files, whichever of its prompts get answered and in whichever order — is written under **one shared, generic sentinel** (`# bootstrap machine-local (autocomplete-visible)`) that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. The sentinel line itself is written proactively on every interactive run against a git repo, even if every exclude-affecting prompt is declined, so the anchor is always there regardless of which preferences got set; a project still carrying the old, separately-named pre-unification header is repaired onto the shared sentinel automatically. |
|
|
29
30
|
| `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. |
|
|
@@ -45,7 +46,7 @@ Static and semi-static assets copied or read by the scripts above — never exec
|
|
|
45
46
|
|
|
46
47
|
| Path | Read/copied by | Contents |
|
|
47
48
|
|------|-----------------|----------|
|
|
48
|
-
| `templates/wiki/` | `sync-wiki-scaffold.sh` | The empty wiki scaffold: `index.md`, `log.md`, `conventions.md`, and per-family `knowledge/`/`work/{tasks,uat,bugs,requirements,decisions,roadmaps}/` directories with `lifecycle.md`, `index.md
|
|
49
|
+
| `templates/wiki/` | `sync-wiki-scaffold.sh` | The empty wiki scaffold: `index.md`, `log.md`, `conventions.md`, and per-family `knowledge/`/`work/{tasks,uat,bugs,requirements,decisions,roadmaps}/` directories with `lifecycle.md`, `index.md` (`## Active` / `## Closed` sections for roadmaps, decisions and requirements, which close in place), `archive/index.md` (tasks, UAT and bugs only), and `.gitkeep` placeholders. |
|
|
49
50
|
| `templates/guides/stubs/` | `build-mcp-guide.sh` | Per-MCP-server markdown fragments (`serena.md`, `context7.md`, `brave-search.md`, `playwright.md`) plus `00-header.md` (the shared top-of-file rules), assembled into `wiki/guides/mcp-tools.md`. |
|
|
50
51
|
| `templates/CLAUDE-wiki.md` | `sync-wiki-scaffold.sh` | The `## LLM Wiki` schema section delivered into a target project's `CLAUDE.md` (copy-once, sentinel-guarded). |
|
|
51
52
|
| `templates/CLAUDE-env-safety.md` | `sync-wiki-scaffold.sh` | The `.env` read/write safety policy prepended to a target project's `CLAUDE.md` (copy-once, never duplicated). |
|
|
@@ -54,6 +55,8 @@ Static and semi-static assets copied or read by the scripts above — never exec
|
|
|
54
55
|
| `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
56
|
| `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). |
|
|
56
57
|
| `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. |
|
|
58
|
+
| `templates/settings-sandbox.json` | `install-global.sh` (step 7b, via `merge-settings-deny.js --set-key sandbox --set-value`) | The starter `sandbox` settings block, offered on opt-in only: `{"enabled": true, "excludedCommands": ["docker *", "docker-compose *"]}`. Deliberately minimal — no filesystem, network, or credentials policy. See [Sandbox scaffold notes](#sandbox-scaffold-notes). |
|
|
59
|
+
| `templates/settings-sandbox-unattended.json` | `install-global.sh` (step 6b — copied to `~/.claude/templates/`, **not** merged) | The stricter `sandbox` profile for unattended runs, a standalone settings file (`{"sandbox": {...}}`) applied per session with `claude --settings`. See [Unattended-run sandbox profile](#unattended-run-sandbox-profile). |
|
|
57
60
|
|
|
58
61
|
## Deny-list notes
|
|
59
62
|
|
|
@@ -69,7 +72,9 @@ Two structural limits, neither mode-dependent:
|
|
|
69
72
|
- **Deny matches a literal command spelling, not a capability.** `Bash(rm -rf ~*)`
|
|
70
73
|
does not stop `/bin/rm -rf ~`, and no deny rule can see inside `bash -c`,
|
|
71
74
|
`python -c`, or `node -e`. Blocking a *capability* needs a `PreToolUse` hook
|
|
72
|
-
(which parses the command) or the OS sandbox
|
|
75
|
+
(which parses the command) or the OS sandbox (opt-in — see
|
|
76
|
+
[Sandbox scaffold notes](#sandbox-scaffold-notes) and, for unattended runs,
|
|
77
|
+
[Unattended-run sandbox profile](#unattended-run-sandbox-profile)).
|
|
73
78
|
- **Deny rules cannot carry allowlist exceptions.** A broad deny blocks every
|
|
74
79
|
matching call even when a narrower `allow` rule also matches. So
|
|
75
80
|
`Bash(git stash:*)` also blocks read-only `git stash list`, and
|
|
@@ -115,7 +120,102 @@ inside this repo. The canonical flow there is to edit `lib/hooks/` and re-run
|
|
|
115
120
|
**Residual risk, accepted:** an agent working inside bootstrap-claude can still
|
|
116
121
|
self-grant permissions by editing global settings. That is the deliberate cost of
|
|
117
122
|
making this repo able to do its job — containment for that case is the OS sandbox
|
|
118
|
-
(`/sandbox`), not this layer.
|
|
123
|
+
(`/sandbox`), not this layer. `install-global.sh` can now scaffold a starter
|
|
124
|
+
sandbox block on opt-in (step 7b, see
|
|
125
|
+
[Sandbox scaffold notes](#sandbox-scaffold-notes)); that block is deliberately
|
|
126
|
+
minimal and does not by itself close this gap. The profile built to close it — for
|
|
127
|
+
unattended runs — ships as `templates/settings-sandbox-unattended.json` (see
|
|
128
|
+
[Unattended-run sandbox profile](#unattended-run-sandbox-profile)): shipped, runtime
|
|
129
|
+
proof pending in the UAT of TASK-031, so not yet verified closed.
|
|
130
|
+
|
|
131
|
+
## Sandbox scaffold notes
|
|
132
|
+
|
|
133
|
+
`install-global.sh` step 7b (`configure_sandbox`) offers to turn on Claude Code's
|
|
134
|
+
OS-level sandbox. It sits between step 7 (skill-preference batch) and step 8 (MCP
|
|
135
|
+
install); nothing was renumbered.
|
|
136
|
+
|
|
137
|
+
- **Tty-only.** A non-interactive run prints "Non-interactive terminal: skipping
|
|
138
|
+
the sandbox question." and writes nothing.
|
|
139
|
+
- **Asked only while `sandbox.scaffold` is unanswered.** The key is `global` scope,
|
|
140
|
+
`consumer: installer`, `askedBy: install-global.sh`, grammar `true | false`,
|
|
141
|
+
`default: null`. Choices are `[y]es` / `[n]o` / `[s]kip for now`: **no** records
|
|
142
|
+
`false` and is never re-asked; **skip** records nothing and is asked again on the
|
|
143
|
+
next sync.
|
|
144
|
+
- **Platform guard (on yes).** Native Windows shells (MINGW/MSYS/CYGWIN) are skipped
|
|
145
|
+
with a note. The sandbox needs macOS Seatbelt, or Linux/WSL2 with `bubblewrap` +
|
|
146
|
+
`socat`; the step warns if those are absent.
|
|
147
|
+
- **What it writes.** `templates/settings-sandbox.json` is merged into
|
|
148
|
+
`~/.claude/settings.json` via `merge-settings-deny.js --set-key sandbox --set-value`,
|
|
149
|
+
which never overwrites a pre-existing different `sandbox` key — it prints the
|
|
150
|
+
"already defines" warning and keeps the user's block. It then records
|
|
151
|
+
`sandbox.scaffold=true` and, when the key was newly set, prints a
|
|
152
|
+
restart-your-session reminder.
|
|
153
|
+
- **Failure is non-fatal.** The step is wrapped so a failure warns and continues.
|
|
154
|
+
|
|
155
|
+
**Sandboxing is incompatible with `docker` commands.** The template pre-lists
|
|
156
|
+
`docker *` and `docker-compose *` in `sandbox.excludedCommands` so those keep
|
|
157
|
+
working; `excludedCommands` is the escape hatch for any further tool that fails
|
|
158
|
+
under the sandbox — add it there. Entries use `Bash(...)` rule syntax, e.g.
|
|
159
|
+
`docker *`.
|
|
160
|
+
|
|
161
|
+
Scope is user settings only, and the template is deliberately minimal: it sets no
|
|
162
|
+
filesystem, network, or credentials policy. That policy, and the attempt to close
|
|
163
|
+
the script-file settings-write gap, live in the separate unattended-run profile
|
|
164
|
+
below, not in this step.
|
|
165
|
+
|
|
166
|
+
## Unattended-run sandbox profile
|
|
167
|
+
|
|
168
|
+
`templates/settings-sandbox-unattended.json` is a standalone settings file,
|
|
169
|
+
`{"sandbox": {...}}`, for the runs where `--dangerously-skip-permissions` is used
|
|
170
|
+
(`power-mode`, `uat-auto-plus`). It is stricter than the opt-in starter above and is
|
|
171
|
+
delivered differently: **copied, never merged.**
|
|
172
|
+
|
|
173
|
+
- **Install (step 6b).** `install-global.sh` copies it to
|
|
174
|
+
`~/.claude/templates/settings-sandbox-unattended.json` (same directory as the
|
|
175
|
+
preference schema from step 6) and prints the launcher command. A missing template
|
|
176
|
+
only warns. Nothing is written into `settings.json` at any scope, because a
|
|
177
|
+
user-scope `sandbox.enabled: true` would sandbox every session, including a
|
|
178
|
+
human's. The file is inert unless a launcher passes it, so it cannot affect
|
|
179
|
+
platforms with no sandbox backend.
|
|
180
|
+
- **Launcher.** Applied per session where the unattended run starts (tmux, CI, cron):
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
claude --settings ~/.claude/templates/settings-sandbox-unattended.json --dangerously-skip-permissions
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`--settings` writes no file, sits above user/project/local scope and below managed
|
|
187
|
+
scope, and is one of the scopes `network.strictAllowlist` is honored from.
|
|
188
|
+
Subagents inherit the parent session's sandbox. A skill cannot enable it — it must
|
|
189
|
+
be on when the session starts.
|
|
190
|
+
- **Contents.** `enabled`, `failIfUnavailable` (fail closed rather than warn and run
|
|
191
|
+
unsandboxed), `allowUnsandboxedCommands: false`, `network.strictAllowlist: true`
|
|
192
|
+
(needs Claude Code v2.1.219 or later; without it bypass mode opens unlisted
|
|
193
|
+
hosts), `network.allowLocalBinding`, `filesystem.denyRead` for `~/.ssh` and
|
|
194
|
+
`~/.gnupg`, `credentials` deny entries, and a small `allowedDomains` list that
|
|
195
|
+
projects extend (arrays merge across scopes). **No `excludedCommands`**: a compound
|
|
196
|
+
command matching any exclusion runs wholly unsandboxed, so a docker exclusion would
|
|
197
|
+
re-open the script-file hole the profile is for.
|
|
198
|
+
- **Coexistence with the starter.** The starter above carries `docker *` and
|
|
199
|
+
`docker-compose *` exclusions. Arrays merge across scopes, so a user who opted into
|
|
200
|
+
the starter carries those into an unattended run, and a compound command matching
|
|
201
|
+
one runs unsandboxed.
|
|
202
|
+
- **Run the installer outside the sandbox.** `bootstrap install`, `setup`, and
|
|
203
|
+
`update` must be run from a normal shell, never through a sandboxed session's Bash
|
|
204
|
+
tool: the sandbox denies `~/.claude` writes, including `settings.json` at every
|
|
205
|
+
scope, and `allowWrite` cannot lift that. The nested-`claude` scripts
|
|
206
|
+
(`bootstrap-serena.sh`, `setup-strict-typechecks.sh`, `migrate-project.sh`) fail
|
|
207
|
+
the same way from a sandboxed Bash.
|
|
208
|
+
- **Status.** Shipped; the runtime proof (a sandboxed `node <script>` write to
|
|
209
|
+
`settings.json` fails, succeeds outside, and holds under
|
|
210
|
+
`--dangerously-skip-permissions`) is **not yet done** and is deferred to the UAT of
|
|
211
|
+
TASK-031. That UAT must start the sandboxed session with
|
|
212
|
+
`CLAUDE_CONFIG_DIR=<scratch>/.claude`: protection follows the session's own config
|
|
213
|
+
directory, so a scratch `HOME` alone passes for the wrong reason.
|
|
214
|
+
|
|
215
|
+
Limits and rationale — Bash-and-children only, credentials readable by default, no
|
|
216
|
+
TLS termination, no native Windows or WSL1, the "not sufficient for fully unattended
|
|
217
|
+
runs" caveat, and the managed-settings option — are in
|
|
218
|
+
[`lib/hooks/README.md` § Tier 3: sandbox](../hooks/README.md#tier-3-sandbox).
|
|
119
219
|
|
|
120
220
|
## Preference helper notes
|
|
121
221
|
|
|
@@ -267,7 +367,7 @@ The shape contract for `templates/bootstrap-prefs-schema.json`. JSON cannot carr
|
|
|
267
367
|
comments, so the file itself must stay bare — no `$comment` header, no explanatory
|
|
268
368
|
keys — and everything a reader or a new consumer needs to know about its shape
|
|
269
369
|
lives here instead. What each individual key *does* is a separate question, and
|
|
270
|
-
it is answered by [The key registry — all
|
|
370
|
+
it is answered by [The key registry — all 26 entries](#the-key-registry--all-26-entries)
|
|
271
371
|
at the end of this section.
|
|
272
372
|
|
|
273
373
|
### Flat key → entry, and eight fields
|
|
@@ -359,7 +459,7 @@ the fact, via `/bootstrap-config`.
|
|
|
359
459
|
`/git-commit` does still prompt — but only once the key is already settled *to a
|
|
360
460
|
value that means "keep asking"* (`confirm` for `versionBump`, `ask` for
|
|
361
461
|
`autoPush`). That is a consumer honouring a stored answer, not the question being
|
|
362
|
-
asked. The same is true of the other three: `/research`, `/uat-
|
|
462
|
+
asked. The same is true of the other three: `/research`, `/uat-create`, and
|
|
363
463
|
`merge-gitignore.sh` each prompt in their key's `ask` state, and none of them is
|
|
364
464
|
named in `askedBy` either.
|
|
365
465
|
|
|
@@ -373,7 +473,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
|
|
|
373
473
|
`"install-global.sh, /git-commit"` fails the suite by construction. Where a
|
|
374
474
|
run-time prompt exists, it is documented in the key's `detail`.
|
|
375
475
|
|
|
376
|
-
### The key registry — all
|
|
476
|
+
### The key registry — all 26 entries
|
|
377
477
|
|
|
378
478
|
Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
|
|
379
479
|
`installer` first, then `skill` — which is the same grouping and the same order
|
|
@@ -382,7 +482,7 @@ schema's `default` field; `unset` in that column means `default: null`, i.e. the
|
|
|
382
482
|
key resolves to `unset` until it is answered. This table is transcribed from the
|
|
383
483
|
JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
384
484
|
|
|
385
|
-
#### `consumer: installer` —
|
|
485
|
+
#### `consumer: installer` — 18 entries, read by the setup/update scripts
|
|
386
486
|
|
|
387
487
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
388
488
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
@@ -403,6 +503,7 @@ JSON; if the two ever disagree, the JSON is right and this table is a bug.
|
|
|
403
503
|
| `obsidian.plugins` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install the bundled Obsidian plugin set (Dataview, Graph Link Types, Breadcrumbs, Front Matter Title, Alias Linker) |
|
|
404
504
|
| `obsidian.graphDefaults` | project | installer | `true \| false` | `unset` | `install-obsidian.sh` | Install default graph-view styling (`.obsidian/graph.json`) |
|
|
405
505
|
| `skills.pruneOrphans` | global | installer | `true \| false` | `unset` | `install-global.sh` | Delete stale skill folders in `~/.claude/skills/` left by the wiki rename |
|
|
506
|
+
| `sandbox.scaffold` | global | installer | `true \| false` | `unset` | `install-global.sh` | Whether `install-global.sh` merges the Claude Code sandbox block into `~/.claude/settings.json` |
|
|
406
507
|
|
|
407
508
|
The two **(pattern)** rows carry `"dynamic": true` and are key *families*, not
|
|
408
509
|
keys: they match one concrete key per optional guide and per titled `.gitignore`
|
|
@@ -422,7 +523,7 @@ above; `gitignore.section.*`'s deliberate one-value grammar is in
|
|
|
422
523
|
| `packageInstall.consent` | project | skill | `true \| false \| ask` | `false` | `/bootstrap-config` | Whether `package-install-consent.js` allows package-manager installs for this project |
|
|
423
524
|
| `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
|
|
424
525
|
| `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
|
|
425
|
-
| `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-
|
|
526
|
+
| `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-create` writes the unit tests it promotes out of UAT cases |
|
|
426
527
|
| `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
|
|
427
528
|
|
|
428
529
|
Seven of these eight are the entire `scope: either` population — a key that
|