@codewizard-dt/bootstrap 5.3.0 → 6.0.1
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/LICENSE.md +105 -0
- package/README.md +22 -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 +53 -11
- 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-deny.json +1 -1
- 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 +9 -9
- 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 +26 -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 +1 -1
- 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 +13 -27
- package/lib/skills/{bug-file → bug-create}/SKILL.md +10 -14
- package/lib/skills/bug-triage/SKILL.md +5 -19
- package/lib/skills/demo/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +3 -3
- package/lib/skills/git-commit/SKILL.md +4 -4
- package/lib/skills/port-feature/SKILL.md +3 -3
- 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 +19 -29
- package/lib/skills/roadmap-next/SKILL.md +16 -28
- package/lib/skills/security-audit/SKILL.md +1 -1
- 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 +25 -24
- package/lib/skills/uat-assess/SKILL.md +124 -0
- package/lib/skills/uat-auto/SKILL.md +9 -7
- 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 +23 -13
- 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 +3 -3
- 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/LICENSE.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Functional Source License, Version 1.1, ALv2 Future License
|
|
2
|
+
|
|
3
|
+
## Abbreviation
|
|
4
|
+
|
|
5
|
+
FSL-1.1-ALv2
|
|
6
|
+
|
|
7
|
+
## Notice
|
|
8
|
+
|
|
9
|
+
Copyright 2026 David Taylor
|
|
10
|
+
|
|
11
|
+
## Terms and Conditions
|
|
12
|
+
|
|
13
|
+
### Licensor ("We")
|
|
14
|
+
|
|
15
|
+
The party offering the Software under these Terms and Conditions.
|
|
16
|
+
|
|
17
|
+
### The Software
|
|
18
|
+
|
|
19
|
+
The "Software" is each version of the software that we make available under
|
|
20
|
+
these Terms and Conditions, as indicated by our inclusion of these Terms and
|
|
21
|
+
Conditions with the Software.
|
|
22
|
+
|
|
23
|
+
### License Grant
|
|
24
|
+
|
|
25
|
+
Subject to your compliance with this License Grant and the Patents,
|
|
26
|
+
Redistribution and Trademark clauses below, we hereby grant you the right to
|
|
27
|
+
use, copy, modify, create derivative works, publicly perform, publicly display
|
|
28
|
+
and redistribute the Software for any Permitted Purpose identified below.
|
|
29
|
+
|
|
30
|
+
### Permitted Purpose
|
|
31
|
+
|
|
32
|
+
A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
|
|
33
|
+
means making the Software available to others in a commercial product or
|
|
34
|
+
service that:
|
|
35
|
+
|
|
36
|
+
1. substitutes for the Software;
|
|
37
|
+
|
|
38
|
+
2. substitutes for any other product or service we offer using the Software
|
|
39
|
+
that exists as of the date we make the Software available; or
|
|
40
|
+
|
|
41
|
+
3. offers the same or substantially similar functionality as the Software.
|
|
42
|
+
|
|
43
|
+
Permitted Purposes specifically include using the Software:
|
|
44
|
+
|
|
45
|
+
1. for your internal use and access;
|
|
46
|
+
|
|
47
|
+
2. for non-commercial education;
|
|
48
|
+
|
|
49
|
+
3. for non-commercial research; and
|
|
50
|
+
|
|
51
|
+
4. in connection with professional services that you provide to a licensee
|
|
52
|
+
using the Software in accordance with these Terms and Conditions.
|
|
53
|
+
|
|
54
|
+
### Patents
|
|
55
|
+
|
|
56
|
+
To the extent your use for a Permitted Purpose would necessarily infringe our
|
|
57
|
+
patents, the license grant above includes a license under our patents. If you
|
|
58
|
+
make a claim against any party that the Software infringes or contributes to
|
|
59
|
+
the infringement of any patent, then your patent license to the Software ends
|
|
60
|
+
immediately.
|
|
61
|
+
|
|
62
|
+
### Redistribution
|
|
63
|
+
|
|
64
|
+
The Terms and Conditions apply to all copies, modifications and derivatives of
|
|
65
|
+
the Software.
|
|
66
|
+
|
|
67
|
+
If you redistribute any copies, modifications or derivatives of the Software,
|
|
68
|
+
you must include a copy of or a link to these Terms and Conditions and not
|
|
69
|
+
remove any copyright notices provided in or with the Software.
|
|
70
|
+
|
|
71
|
+
### Disclaimer
|
|
72
|
+
|
|
73
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
|
|
74
|
+
IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
|
|
75
|
+
PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
|
|
76
|
+
|
|
77
|
+
IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
|
|
78
|
+
SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
|
|
79
|
+
EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
|
|
80
|
+
|
|
81
|
+
### Trademarks
|
|
82
|
+
|
|
83
|
+
Except for displaying the License Details and identifying us as the origin of
|
|
84
|
+
the Software, you have no right under these Terms and Conditions to use our
|
|
85
|
+
trademarks, trade names, service marks or product names.
|
|
86
|
+
|
|
87
|
+
## Grant of Future License
|
|
88
|
+
|
|
89
|
+
We hereby irrevocably grant you an additional license to use the Software under
|
|
90
|
+
the Apache License, Version 2.0 that is effective on the second anniversary of
|
|
91
|
+
the date we make the Software available. On or after that date, you may use the
|
|
92
|
+
Software under the Apache License, Version 2.0, in which case the following
|
|
93
|
+
will apply:
|
|
94
|
+
|
|
95
|
+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
|
96
|
+
this file except in compliance with the License.
|
|
97
|
+
|
|
98
|
+
You may obtain a copy of the License at
|
|
99
|
+
|
|
100
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
101
|
+
|
|
102
|
+
Unless required to in writing, software distributed
|
|
103
|
+
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
|
|
104
|
+
CONDITIONS OF ANY KIND, either express or implied. See the License for the
|
|
105
|
+
specific language governing permissions and limitations under the License.
|
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
|
|
@@ -441,3 +449,14 @@ Useful first places to inspect:
|
|
|
441
449
|
- **Context7 installs without authenticated access:** Set `CONTEXT7_API_KEY` if authenticated Context7 access is required; otherwise the script can register Context7 without the header.
|
|
442
450
|
- **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`. The `permissions.deny` list is the exception: `install-global.sh` merges the canonical deny list from `lib/scripts/templates/settings-deny.json` into `~/.claude/settings.json` automatically (additive-only — your own entries are never removed or reordered). Deleting a canonical entry locally means it gets re-added on the next `install`/`setup`/`update` run; that re-convergence is the point of a canonical list.
|
|
443
451
|
- **npm package points at unexpected repository metadata:** Check `package.json` `repository`, `homepage`, and `bugs` fields before publishing; they are independent of the local git remote.
|
|
452
|
+
|
|
453
|
+
## License
|
|
454
|
+
|
|
455
|
+
This project is licensed under the **Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2)** — see [`LICENSE.md`](LICENSE.md) for the full text.
|
|
456
|
+
|
|
457
|
+
In plain terms:
|
|
458
|
+
- **Free for essentially everything** — installing and using this tool in your own projects (the normal `npx @codewizard-dt/bootstrap` workflow), modifying it, redistributing it, using it internally at a company, using it in non-commercial education or research, and using it while providing paid professional services to a client who is themselves complying with this license.
|
|
459
|
+
- **Not permitted:** repackaging this project (as-is or modified) into a commercial product or service that substitutes for it, for an existing CodeWizard product/service, or that offers substantially the same functionality — in short, rebranding and reselling it as a competing offering.
|
|
460
|
+
- **It doesn't stay restricted forever.** Each released version automatically becomes available under the **Apache License, Version 2.0** two years after its release date, per the "Grant of Future License" in `LICENSE.md`.
|
|
461
|
+
|
|
462
|
+
The license governs the *code*. It does not grant any right to the project's name, branding, or any trademarks — see [`TRADEMARK.md`](TRADEMARK.md).
|
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
|
|