@codewizard-dt/bootstrap 6.0.0 → 6.1.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/LICENSE.md +105 -0
- package/README.md +12 -0
- package/lib/scripts/README.md +4 -3
- package/lib/scripts/bootstrap-prefs.js +25 -2
- package/lib/scripts/git-prefs.js +123 -0
- package/lib/scripts/install-global.sh +3 -0
- package/lib/scripts/merge-gitignore.sh +11 -5
- package/lib/scripts/migrate-project.sh +1 -1
- package/lib/scripts/rename-wiki-ids.js +2 -2
- package/lib/scripts/sync-wiki-scaffold.sh +5 -11
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/guides/stubs/serena.md +4 -1
- package/lib/scripts/templates/settings-deny.json +1 -1
- package/lib/scripts/templates/wiki/conventions.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
- package/lib/skills/README.md +2 -1
- package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
- package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
- package/lib/skills/_shared/LOG-APPEND.md +34 -0
- package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
- package/lib/skills/adr-create/SKILL.md +2 -2
- package/lib/skills/adr-deprecate/SKILL.md +1 -1
- package/lib/skills/adr-extract/SKILL.md +1 -1
- package/lib/skills/adr-finalize/SKILL.md +2 -1
- package/lib/skills/autopilot/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +1 -1
- package/lib/skills/bug-triage/SKILL.md +1 -1
- package/lib/skills/git-commit/SKILL.md +18 -27
- package/lib/skills/prd-create/SKILL.md +2 -2
- package/lib/skills/prd-deprecate/SKILL.md +1 -1
- package/lib/skills/prd-finalize/SKILL.md +1 -1
- package/lib/skills/socratic-qa/SKILL.md +163 -0
- package/lib/skills/task-create/SKILL.md +1 -1
- package/lib/skills/uat-create/SKILL.md +1 -1
- package/lib/skills/uat-skip/SKILL.md +19 -29
- package/lib/skills/uat-walk/UAT-CORE.md +1 -1
- package/lib/skills/wiki-archive/SKILL.md +1 -1
- package/lib/skills/wiki-ingest/SKILL.md +1 -1
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
- package/lib/skills/wiki-tidy/SKILL.md +5 -12
- package/package.json +3 -3
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
|
@@ -448,4 +448,16 @@ Useful first places to inspect:
|
|
|
448
448
|
- **`playwright endpoint not answering` (macOS):** The launchd agent `com.bootstrap-claude.playwright-mcp` should be serving `http://127.0.0.1:8931/mcp` (overridable via `PLAYWRIGHT_MCP_PORT`). Inspect it with `launchctl print gui/$(id -u)/com.bootstrap-claude.playwright-mcp` and check `~/Library/Logs/playwright-mcp.log`. Over SSH there is no GUI session for the agent to bootstrap into — log into the Mac GUI once, then re-run `bootstrap update`.
|
|
449
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.
|
|
450
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.
|
|
451
|
+
- **Claude Code keeps recommending an LSP plugin:** A dialog titled "LSP plugin recommendation" can appear after Claude edits a file. Claude Code offers a matching plugin whenever the language server's binary is on `PATH`, independent of project configuration. This repo mandates Serena as the code-intelligence surface (`CLAUDE.md` § MCP Tool Requirements), and installing a native plugin would duplicate the language server — see [ADR-0002](wiki/work/decisions/ADR-0002-serena-first-vs-native-lsp-plugins.md). Choose **Disable all LSP recommendations** (or **Never for this plugin** to silence one language); the choice is tracked in `~/.claude.json`, so it applies across projects rather than just the current one. If you ignore the dialog five times, Claude Code stops recommending plugins on its own, as if you had chosen **Disable all LSP recommendations**. The installer does not change this setting for you.
|
|
451
452
|
- **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.
|
|
453
|
+
|
|
454
|
+
## License
|
|
455
|
+
|
|
456
|
+
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.
|
|
457
|
+
|
|
458
|
+
In plain terms:
|
|
459
|
+
- **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.
|
|
460
|
+
- **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.
|
|
461
|
+
- **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`.
|
|
462
|
+
|
|
463
|
+
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/lib/scripts/README.md
CHANGED
|
@@ -21,15 +21,16 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
21
21
|
|--------|---------|---------|
|
|
22
22
|
| `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: `install-global.sh --skip-mcps` first — hooks/skills/deny-list/hooks-wiring/fileSuggestion, offline-safe — then the guarded interactive MCP install, wiki scaffold, gitignore, the wiki-alias backfill, Obsidian, MCP-tools guide, Serena bootstrap), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
|
|
23
23
|
| `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). Playwright has a dedicated conflict flow: registered as `playwright` (user scope) by default; when a project ships its own `playwright`, a git-tracked `.mcp.json` is never modified (interactive options: register ours as `playwright-shared` + disable the project entry machine-locally via `disabledMcpjsonServers` in `.claude/settings.local.json` / register alongside / skip), while a machine-local registration can be replaced or kept (ours then uses the alternate name). Non-interactive conflicts are left untouched with a hint. |
|
|
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,
|
|
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.local.md` by default** (machine-local; a missing `CLAUDE.md` is no longer created for it, and `merge-gitignore.sh` adds `CLAUDE.local.md` to `.git/info/exclude`) — when a `CLAUDE.md` already exists without the schema, interactive runs may opt into appending to it instead (default answer: no → `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
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. |
|
|
28
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. |
|
|
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
|
+
| `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; **default answer Yes**, `[Y/n]`) to keep `.serena/`/`raw/`/`wiki/` — plus `CLAUDE.local.md` when present — 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. |
|
|
30
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. |
|
|
31
31
|
| `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
|
|
32
|
-
| `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list.
|
|
32
|
+
| `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Six operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--get-many <k1,k2,...>` (several keys resolved in one process and printed as one JSON object — one node startup instead of N; each key resolves exactly as `--get` would), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`), and `--set` also refuses to write into a layer the key's `scope` forbids (`--target` stays exempt); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
|
|
33
|
+
| `git-prefs.js` | `install-global.sh` (step 6 copies it to `~/.claude/git-prefs.js`, beside `bootstrap-prefs.js`), the `/git-commit` skill | One-call context for `/git-commit`: prints `## repo` (root, branch, upstream), `## prefs` (the three `gitCommit.*` keys, resolved via a single `bootstrap-prefs.js --get-many` against the repo root), `## manifests` (every version-bearing `package.json` / `pyproject.toml` / `Cargo.toml` / `setup.cfg` / `VERSION` / `version.txt` with its current version, `.gitignore` respected), `## status`, `## log` and `## diff`. Replaces ~8 separate shell calls. Exits 1 only outside a git repo; a missing prefs helper degrades every key to `unset`. |
|
|
33
34
|
|
|
34
35
|
## Standalone infra scripts (not wired to the CLI)
|
|
35
36
|
|
|
@@ -29,12 +29,18 @@
|
|
|
29
29
|
//
|
|
30
30
|
// Usage:
|
|
31
31
|
// bootstrap-prefs.js --get <key> [--project <dir>] [--global] [--target <path>]
|
|
32
|
+
// bootstrap-prefs.js --get-many <k1,k2,...> [--project <dir>] [--global] [--target <path>]
|
|
32
33
|
// bootstrap-prefs.js --set <key> --value <v> (--global | --project <dir> | --target <path>)
|
|
33
34
|
// bootstrap-prefs.js --unset <key> (--global | --project <dir> | --target <path>)
|
|
34
35
|
// bootstrap-prefs.js --list [--project <dir>] [--target <path>]
|
|
35
36
|
// bootstrap-prefs.js --section-key <title>
|
|
36
37
|
// ... plus [--schema <path>] on any of the above.
|
|
37
38
|
//
|
|
39
|
+
// --get-many resolves several keys in one process and prints one JSON object
|
|
40
|
+
// {"<key>": "<value or the literal word unset>", ...}. Each key resolves
|
|
41
|
+
// exactly as --get would; it exists so a caller needing N preferences pays for
|
|
42
|
+
// one node startup, not N.
|
|
43
|
+
//
|
|
38
44
|
// --global / --project <dir> are semantic LAYER SELECTORS.
|
|
39
45
|
// --target <path> is an explicit single file, bypassing layer resolution. It
|
|
40
46
|
// is the test seam (the repo's established name for one) and doubles as the
|
|
@@ -64,7 +70,8 @@ const path = require('path');
|
|
|
64
70
|
const USAGE = [
|
|
65
71
|
'Usage:',
|
|
66
72
|
' bootstrap-prefs.js --get <key> [--project <dir>] [--global] [--target <path>]',
|
|
67
|
-
' bootstrap-prefs.js --
|
|
73
|
+
' bootstrap-prefs.js --get-many <k1,k2,...> [--project <dir>] [--global] [--target <path>]',
|
|
74
|
+
' bootstrap-prefs.js --set <key> --value <v> (--global | --project <dir> | --target <path>)',
|
|
68
75
|
' bootstrap-prefs.js --unset <key> (--global | --project <dir> | --target <path>)',
|
|
69
76
|
' bootstrap-prefs.js --list [--project <dir>] [--target <path>]',
|
|
70
77
|
' bootstrap-prefs.js --section-key <title>',
|
|
@@ -73,6 +80,7 @@ const USAGE = [
|
|
|
73
80
|
|
|
74
81
|
const FLAGS_WITH_OPERAND = new Set([
|
|
75
82
|
'--get',
|
|
83
|
+
'--get-many',
|
|
76
84
|
'--set',
|
|
77
85
|
'--unset',
|
|
78
86
|
'--value',
|
|
@@ -132,6 +140,9 @@ function parseArgs(argv) {
|
|
|
132
140
|
if (arg === '--get') {
|
|
133
141
|
setOp('get');
|
|
134
142
|
opts.key = argv[++i];
|
|
143
|
+
} else if (arg === '--get-many') {
|
|
144
|
+
setOp('get-many');
|
|
145
|
+
opts.key = argv[++i];
|
|
135
146
|
} else if (arg === '--set') {
|
|
136
147
|
setOp('set');
|
|
137
148
|
opts.key = argv[++i];
|
|
@@ -159,7 +170,7 @@ function parseArgs(argv) {
|
|
|
159
170
|
}
|
|
160
171
|
|
|
161
172
|
if (opts.op === null) {
|
|
162
|
-
usageError('one of --get, --set, --unset, --list, --section-key is required');
|
|
173
|
+
usageError('one of --get, --get-many, --set, --unset, --list, --section-key is required');
|
|
163
174
|
}
|
|
164
175
|
if (opts.value !== null && opts.op !== 'set') {
|
|
165
176
|
usageError('--value is only valid with --set');
|
|
@@ -590,6 +601,18 @@ if (opts.op === 'get') {
|
|
|
590
601
|
process.exit(0);
|
|
591
602
|
}
|
|
592
603
|
|
|
604
|
+
if (opts.op === 'get-many') {
|
|
605
|
+
const keys = opts.key.split(',').map((k) => k.trim()).filter((k) => k.length > 0);
|
|
606
|
+
if (keys.length === 0) usageError('--get-many requires at least one key');
|
|
607
|
+
const out = {};
|
|
608
|
+
for (const key of keys) {
|
|
609
|
+
const { value, layer } = resolve(key, lookupSchema(schema, key), opts);
|
|
610
|
+
out[key] = layer === 'unset' ? 'unset' : formatValue(value);
|
|
611
|
+
}
|
|
612
|
+
console.log(JSON.stringify(out));
|
|
613
|
+
process.exit(0);
|
|
614
|
+
}
|
|
615
|
+
|
|
593
616
|
if (opts.op === 'list') {
|
|
594
617
|
const consulted = [];
|
|
595
618
|
if (opts.target !== null) {
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// One-call context for /git-commit: repo facts, the three gitCommit.* preferences,
|
|
3
|
+
// and the version manifests, printed as plain `## section` blocks. Replaces ~8
|
|
4
|
+
// separate shell calls (rev-parse, 3 pref reads, status, diff, log, manifest find).
|
|
5
|
+
//
|
|
6
|
+
// Usage: git-prefs.js (run from anywhere inside the repo)
|
|
7
|
+
//
|
|
8
|
+
// Exit 1 only when the caller is wrong (not inside a git repo). Everything else
|
|
9
|
+
// degrades — a missing prefs helper reads as `unset`, an empty repo has an empty
|
|
10
|
+
// log/diff — so it can never block a commit.
|
|
11
|
+
//
|
|
12
|
+
// Resolves bootstrap-prefs.js beside itself: both are installed to ~/.claude/.
|
|
13
|
+
|
|
14
|
+
'use strict';
|
|
15
|
+
|
|
16
|
+
const fs = require('fs');
|
|
17
|
+
const path = require('path');
|
|
18
|
+
const { spawnSync } = require('child_process');
|
|
19
|
+
|
|
20
|
+
const PREF_KEYS = ['gitCommit.versionBump', 'gitCommit.autoPush', 'gitCommit.lint'];
|
|
21
|
+
const MANIFEST_NAMES = new Set(['package.json', 'pyproject.toml', 'Cargo.toml', 'setup.cfg', 'VERSION', 'version.txt']);
|
|
22
|
+
const TOML_SECTIONS = {
|
|
23
|
+
'pyproject.toml': ['project', 'tool.poetry'],
|
|
24
|
+
'Cargo.toml': ['package'],
|
|
25
|
+
'setup.cfg': ['metadata'],
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
function git(args, cwd) {
|
|
29
|
+
const res = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
|
|
30
|
+
return { ok: res.status === 0, out: res.stdout || '' };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function readPrefs(root) {
|
|
34
|
+
const unset = Object.fromEntries(PREF_KEYS.map((k) => [k, 'unset']));
|
|
35
|
+
const res = spawnSync(
|
|
36
|
+
process.execPath,
|
|
37
|
+
[path.join(__dirname, 'bootstrap-prefs.js'), '--get-many', PREF_KEYS.join(','), '--project', root],
|
|
38
|
+
{ encoding: 'utf8' }
|
|
39
|
+
);
|
|
40
|
+
if (res.status !== 0) return unset;
|
|
41
|
+
try {
|
|
42
|
+
return { ...unset, ...JSON.parse(res.stdout) };
|
|
43
|
+
} catch (_) {
|
|
44
|
+
return unset;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function tomlVersion(text, sections) {
|
|
49
|
+
let current = null;
|
|
50
|
+
for (const line of text.split('\n')) {
|
|
51
|
+
const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
|
|
52
|
+
if (header) {
|
|
53
|
+
current = header[1].trim();
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
if (current !== null && sections.includes(current)) {
|
|
57
|
+
const m = line.match(/^\s*version\s*[=:]\s*["']?([^"'\s#]+)/);
|
|
58
|
+
if (m) return m[1];
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function manifestVersion(file, text) {
|
|
65
|
+
const name = path.basename(file);
|
|
66
|
+
if (name === 'package.json') {
|
|
67
|
+
try {
|
|
68
|
+
const v = JSON.parse(text).version;
|
|
69
|
+
return typeof v === 'string' ? v : null;
|
|
70
|
+
} catch (_) {
|
|
71
|
+
return null;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
if (name === 'VERSION' || name === 'version.txt') {
|
|
75
|
+
const first = text.split('\n')[0].trim();
|
|
76
|
+
return first === '' ? null : first;
|
|
77
|
+
}
|
|
78
|
+
return tomlVersion(text, TOML_SECTIONS[name]);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// ls-files (tracked + untracked-not-ignored) instead of walking the tree: it
|
|
82
|
+
// honours .gitignore, so node_modules and build output never need a prune list.
|
|
83
|
+
function findManifests(root) {
|
|
84
|
+
const listed = git(['ls-files', '-co', '--exclude-standard', '-z'], root).out.split('\0');
|
|
85
|
+
const found = [];
|
|
86
|
+
for (const rel of listed) {
|
|
87
|
+
if (!MANIFEST_NAMES.has(path.basename(rel))) continue;
|
|
88
|
+
let text;
|
|
89
|
+
try {
|
|
90
|
+
text = fs.readFileSync(path.join(root, rel), 'utf8');
|
|
91
|
+
} catch (_) {
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
const version = manifestVersion(rel, text);
|
|
95
|
+
if (version !== null) found.push({ file: rel, version });
|
|
96
|
+
}
|
|
97
|
+
return found;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const top = git(['rev-parse', '--show-toplevel'], process.cwd());
|
|
101
|
+
if (!top.ok) {
|
|
102
|
+
console.error('Error: git-prefs.js must run inside a git repository — no repo root found from the current directory.');
|
|
103
|
+
process.exit(1);
|
|
104
|
+
}
|
|
105
|
+
const root = top.out.trim();
|
|
106
|
+
|
|
107
|
+
const branch = git(['branch', '--show-current'], root).out.trim();
|
|
108
|
+
const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], root);
|
|
109
|
+
const prefs = readPrefs(root);
|
|
110
|
+
const manifests = findManifests(root);
|
|
111
|
+
|
|
112
|
+
const section = (title, body) => `## ${title}\n${body.replace(/\n+$/, '')}\n`;
|
|
113
|
+
|
|
114
|
+
const parts = [
|
|
115
|
+
section('repo', [`root: ${root}`, `branch: ${branch || '(detached HEAD)'}`, `upstream: ${upstream.ok ? upstream.out.trim() : '(none)'}`].join('\n')),
|
|
116
|
+
section('prefs', PREF_KEYS.map((k) => `${k}=${prefs[k]}`).join('\n')),
|
|
117
|
+
section('manifests', manifests.length === 0 ? '(none)' : manifests.map((m) => `${m.file} ${m.version}`).join('\n')),
|
|
118
|
+
section('status', git(['status', '--short'], root).out || '(clean)'),
|
|
119
|
+
section('log', git(['log', '--oneline', '-10'], root).out || '(no commits)'),
|
|
120
|
+
section('diff', git(['diff', 'HEAD'], root).out || '(no tracked changes)'),
|
|
121
|
+
];
|
|
122
|
+
|
|
123
|
+
process.stdout.write(parts.join('\n'));
|
|
@@ -157,7 +157,10 @@ if [ -f "$SCRIPT_DIR/bootstrap-prefs.js" ] && [ -f "$SCRIPT_DIR/templates/bootst
|
|
|
157
157
|
mkdir -p "$HOME/.claude/templates"
|
|
158
158
|
cp "$SCRIPT_DIR/bootstrap-prefs.js" "$HOME/.claude/bootstrap-prefs.js"
|
|
159
159
|
cp "$SCRIPT_DIR/templates/bootstrap-prefs-schema.json" "$HOME/.claude/templates/bootstrap-prefs-schema.json"
|
|
160
|
+
# git-prefs.js shells out to bootstrap-prefs.js beside itself, so it must land in the same directory.
|
|
161
|
+
[ -f "$SCRIPT_DIR/git-prefs.js" ] && cp "$SCRIPT_DIR/git-prefs.js" "$HOME/.claude/git-prefs.js"
|
|
160
162
|
echo " Installed. Skills read preferences with: node ~/.claude/bootstrap-prefs.js --get <key> --project ."
|
|
163
|
+
echo " /git-commit reads repo state + its preferences in one call: node ~/.claude/git-prefs.js"
|
|
161
164
|
else
|
|
162
165
|
echo "Warning: bootstrap-prefs.js or its schema not found — skills will read every preference as unset (today's behavior)." >&2
|
|
163
166
|
fi
|
|
@@ -270,7 +270,7 @@ LEGACY_PREFS_SENTINEL="# bootstrap preferences (machine-local)"
|
|
|
270
270
|
# Every path bootstrap ever excludes here, in the fixed order they're packed
|
|
271
271
|
# into the block when present. Each is independently optional — the block can
|
|
272
272
|
# hold anywhere from zero of these (the proactive empty case) to all five.
|
|
273
|
-
KNOWN_EXCLUDE_PATHS=(".serena/" "raw/" "wiki/" ".claude/bootstrap-prefs.json" ".claude/bootstrap-prefs.README.md")
|
|
273
|
+
KNOWN_EXCLUDE_PATHS=(".serena/" "raw/" "wiki/" "CLAUDE.local.md" ".claude/bootstrap-prefs.json" ".claude/bootstrap-prefs.README.md")
|
|
274
274
|
|
|
275
275
|
# Set by exclude_ensure_paths after every call: 1 if the file's content changed,
|
|
276
276
|
# 0 if it was already exactly the desired shape (byte-identical, left untouched
|
|
@@ -415,9 +415,15 @@ exclude_ensure_sentinel() {
|
|
|
415
415
|
if [ -d "$PROJECT_DIR/.git" ]; then
|
|
416
416
|
exclude_ensure_sentinel "$GIT_EXCLUDE"
|
|
417
417
|
|
|
418
|
+
exclude_targets=(".serena/" "raw/" "wiki/")
|
|
419
|
+
# The wiki agent instructions live in CLAUDE.local.md by default
|
|
420
|
+
# (sync-wiki-scaffold.sh) — machine-local, so it joins the same exclude block.
|
|
421
|
+
if [ -f "$PROJECT_DIR/CLAUDE.local.md" ]; then
|
|
422
|
+
exclude_targets+=("CLAUDE.local.md")
|
|
423
|
+
fi
|
|
418
424
|
exclude_missing=0
|
|
419
425
|
exclude_added=""
|
|
420
|
-
for p in "
|
|
426
|
+
for p in "${exclude_targets[@]}"; do
|
|
421
427
|
if [ -f "$GIT_EXCLUDE" ] && grep -qFx -- "$p" "$GIT_EXCLUDE"; then
|
|
422
428
|
continue
|
|
423
429
|
fi
|
|
@@ -437,8 +443,8 @@ if [ -d "$PROJECT_DIR/.git" ]; then
|
|
|
437
443
|
# never disable another.
|
|
438
444
|
if [ "$(prefs_get gitignore.infoExclude "$PROJECT_DIR")" = "false" ]; then
|
|
439
445
|
echo " .git/info/exclude: skipped (remembered answer gitignore.infoExclude=false — change with /bootstrap-config)."
|
|
440
|
-
elif prompt_yn " Add .serena/, raw/,
|
|
441
|
-
if exclude_apply "$GIT_EXCLUDE" "
|
|
446
|
+
elif prompt_yn " Add .serena/, raw/, wiki/ (and CLAUDE.local.md if present) to git's local ignore list (.git/info/exclude, this machine only)? [Y/n]: "; then
|
|
447
|
+
if exclude_apply "$GIT_EXCLUDE" "${exclude_targets[@]}"; then
|
|
442
448
|
printf '%s' "$exclude_added"
|
|
443
449
|
echo " Note: this protects only this clone — teammates opt in by running 'npx @codewizard-dt/bootstrap update' themselves."
|
|
444
450
|
fi
|
|
@@ -452,7 +458,7 @@ if [ -d "$PROJECT_DIR/.git" ]; then
|
|
|
452
458
|
# a decline refuses newly hiding paths, not repairing a sentinel.
|
|
453
459
|
# exclude_apply is a byte-identical no-op when the block is already
|
|
454
460
|
# canonical, so EXCLUDE_CHANGED gates the message.
|
|
455
|
-
if exclude_apply "$GIT_EXCLUDE" "
|
|
461
|
+
if exclude_apply "$GIT_EXCLUDE" "${exclude_targets[@]}" && [ "$EXCLUDE_CHANGED" -eq 1 ]; then
|
|
456
462
|
echo " .git/info/exclude: reordered .serena/, raw/, wiki/ under the bootstrap sentinel (git unchanged; restores @-autocomplete)"
|
|
457
463
|
fi
|
|
458
464
|
fi
|
|
@@ -162,14 +162,14 @@ function main(argv) {
|
|
|
162
162
|
return 1;
|
|
163
163
|
}
|
|
164
164
|
if (!fs.existsSync(path.join(projectDir, 'wiki'))) {
|
|
165
|
-
if (countOnly) console.log(0);
|
|
165
|
+
if (countOnly) console.log('0');
|
|
166
166
|
else console.log(' wiki/ not found — nothing to rename.');
|
|
167
167
|
return 0;
|
|
168
168
|
}
|
|
169
169
|
|
|
170
170
|
const { files, idMap } = buildPlan(projectDir);
|
|
171
171
|
if (countOnly) {
|
|
172
|
-
console.log(files.length);
|
|
172
|
+
console.log(String(files.length));
|
|
173
173
|
return 0;
|
|
174
174
|
}
|
|
175
175
|
if (idMap.size === 0) {
|
|
@@ -182,17 +182,11 @@ if [ -f "$CLAUDE_TEMPLATE" ]; then
|
|
|
182
182
|
elif [ -f "$TARGET_LOCAL" ] && grep -q '^## LLM Wiki' "$TARGET_LOCAL"; then
|
|
183
183
|
SCHEMA_FILE="$TARGET_LOCAL"
|
|
184
184
|
echo "CLAUDE.local.md already has the LLM Wiki schema section, skipping."
|
|
185
|
-
elif [ ! -f "$TARGET_CLAUDE" ]; then
|
|
186
|
-
{
|
|
187
|
-
echo "# CLAUDE.md"
|
|
188
|
-
echo ""
|
|
189
|
-
echo "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository."
|
|
190
|
-
echo ""
|
|
191
|
-
cat "$CLAUDE_TEMPLATE"
|
|
192
|
-
} > "$TARGET_CLAUDE"
|
|
193
|
-
echo "CLAUDE.md created with the LLM Wiki schema section."
|
|
194
185
|
else
|
|
195
|
-
|
|
186
|
+
# Default is CLAUDE.local.md (machine-local; merge-gitignore.sh adds it to
|
|
187
|
+
# .git/info/exclude). Only an existing CLAUDE.md can be opted into, and only
|
|
188
|
+
# interactively — a missing CLAUDE.md is never created just for the schema.
|
|
189
|
+
if [ -f "$TARGET_CLAUDE" ] && [ "$INTERACTIVE" = true ] && prompt_yn " Existing CLAUDE.md found. Append the LLM Wiki schema to it? [y/N] (no = write CLAUDE.local.md instead): "; then
|
|
196
190
|
{
|
|
197
191
|
echo ""
|
|
198
192
|
echo "---"
|
|
@@ -218,7 +212,7 @@ if [ -f "$CLAUDE_TEMPLATE" ]; then
|
|
|
218
212
|
cat "$CLAUDE_TEMPLATE"
|
|
219
213
|
} >> "$TARGET_LOCAL"
|
|
220
214
|
fi
|
|
221
|
-
echo "LLM Wiki schema section written to CLAUDE.local.md (CLAUDE.md left untouched)."
|
|
215
|
+
echo "LLM Wiki schema section written to CLAUDE.local.md (CLAUDE.md left untouched; merge-gitignore.sh excludes it from git)."
|
|
222
216
|
fi
|
|
223
217
|
fi
|
|
224
218
|
fi
|
|
@@ -49,7 +49,7 @@ Keep the two from duplicating or contradicting each other: project-specific stat
|
|
|
49
49
|
| `/wiki-query <question>` | Answer from the wiki with citations; auto-ingest relevant un-ingested `raw/` sources when coverage is missing; offer to file valuable synthesis back as a new page |
|
|
50
50
|
| `/wiki-lint` | Health-check — contradictions, orphan pages, stale claims, index drift, never-ingested raw sources |
|
|
51
51
|
| `/wiki-archive [family]` | Batch-move terminal tasks, UAT and bugs into `<family>/archive/`; update `archive/index.md` and log the operation (roadmaps, decisions and requirements close in place and are never archived) |
|
|
52
|
-
| `/wiki-rotate-log` | Rotate `wiki/log.md` to a timestamped archive file when it
|
|
52
|
+
| `/wiki-rotate-log` | Rotate `wiki/log.md` to a timestamped archive file when it reaches 200 lines (forced, not a nudge); create a fresh `log.md` with an archive pointer |
|
|
53
53
|
| `/wiki-tidy` | One-shot cleanup — lint, archive terminal tasks/UAT/bugs, then rotate log if overgrown; phases run in sequence with user confirmation |
|
|
54
54
|
|
|
55
55
|
### CRITICAL wiki rules
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"scope": "project",
|
|
49
49
|
"consumer": "installer",
|
|
50
50
|
"summary": "Add .serena/, raw/, and wiki/ to git's local ignore list via .git/info/exclude",
|
|
51
|
-
"detail": "Asked by merge-gitignore.sh:
|
|
51
|
+
"detail": "Asked by merge-gitignore.sh:446 (default answer Yes — a bare Enter accepts) when one or more of .serena/, raw/, wiki/ are not yet excluded. true writes them under the bootstrap sentinel in .git/info/exclude — machine-local, never committed, and unlike .gitignore it does not blind Serena or ripgrep-class walkers; the installed fileSuggestion script restores @-autocomplete for those paths. false leaves git tracking them here; teammates opt in separately by running update themselves. This is INDEPENDENT of the .gitignore section pass governed by gitignore.offerSectionUpdates: declining or disabling sections never disables the info/exclude mechanism, and a pure sentinel repair (all three already excluded elsewhere in the file) runs with no prompt at all regardless of this key. See also prefs.gitTracking, which decides how git treats the preferences file itself — a different question from these three directories.",
|
|
52
52
|
"values": "true | false",
|
|
53
53
|
"default": null,
|
|
54
54
|
"askedBy": "merge-gitignore.sh"
|
|
@@ -103,6 +103,9 @@ Serena provides two editing approaches:
|
|
|
103
103
|
| `search_for_pattern` | Regex search across files | `substring_pattern`, `relative_path`, `paths_include_glob` |
|
|
104
104
|
| `list_dir` | List directory contents | `relative_path`, `recursive` |
|
|
105
105
|
| `find_file` | Find files by name/mask | `file_mask`, `relative_path` |
|
|
106
|
+
| `get_diagnostics_for_file` | Errors/warnings for one file (run after edits) | `relative_path` |
|
|
107
|
+
|
|
108
|
+
`get_diagnostics_for_file` is pull-based: unlike native LSP plugins it is not pushed after each edit, so call it yourself after editing. If no language server is enabled for the file type in `.serena/project.yml`, it returns a benign decline (the "cannot extract symbols" class) rather than an error to fix.
|
|
106
109
|
|
|
107
110
|
**Symbolic editing** (use when replacing entire symbols):
|
|
108
111
|
|
|
@@ -132,7 +135,7 @@ Serena provides two editing approaches:
|
|
|
132
135
|
### Workflow
|
|
133
136
|
|
|
134
137
|
```
|
|
135
|
-
1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. find_referencing_symbols
|
|
138
|
+
1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. get_diagnostics_for_file → 5. find_referencing_symbols
|
|
136
139
|
```
|
|
137
140
|
|
|
138
141
|
### Choosing Edit Mode
|
|
@@ -93,7 +93,7 @@ Archiving is a periodic **maintenance operation**, not part of the close/done wo
|
|
|
93
93
|
|
|
94
94
|
## 6. Log rotation
|
|
95
95
|
|
|
96
|
-
`wiki/log.md` is append-only. When it
|
|
96
|
+
`wiki/log.md` is append-only. When it reaches **200 lines**, `/wiki-rotate-log` rotates it automatically — forced, never asked:
|
|
97
97
|
|
|
98
98
|
1. Rename `wiki/log.md` → `wiki/log-<timestamp>.md`, where `<timestamp>` is `YYYY_MM_DD_HHMMSS` (to the second, so filenames never collide across rotations)
|
|
99
99
|
2. Create a fresh `wiki/log.md` with an archive-pointer header: `> Archives: [2026_06_14_153012](log-2026_06_14_153012.md) · [2025_12_31_092455](log-2025_12_31_092455.md)`
|
|
@@ -25,7 +25,7 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
25
25
|
| `uat` | no | link to the matching `../uat/UAT-NNNN-slug.md` |
|
|
26
26
|
| `tags` | no | discovery only |
|
|
27
27
|
|
|
28
|
-
**Dependency fields.** `depends_on`, `blocks`, and `parallel_safe_with` are YAML arrays of `TASK-NNNN` IDs (`[]` when empty) and are the **sole authoritative, machine-read** encoding of task dependencies (per
|
|
28
|
+
**Dependency fields.** `depends_on`, `blocks`, and `parallel_safe_with` are YAML arrays of `TASK-NNNN` IDs (`[]` when empty) and are the **sole authoritative, machine-read** encoding of task dependencies (per ADR-0001#D4).
|
|
29
29
|
Edges should be symmetric: if A lists B in `blocks`, B lists A in `depends_on` — tooling flags asymmetry and never auto-corrects it.
|
|
30
30
|
A body `depends_on::[[TASK-NNNN]]` / `blocks::[[TASK-NNNN]]` typed-link line under the H1 is an optional mirror for graph views (Obsidian/Breadcrumbs) and is never read by tooling.
|
|
31
31
|
The legacy `> **Depends on**:` blockquote and `## Dependencies` body headings are not part of the schema.
|
package/lib/skills/README.md
CHANGED
|
@@ -12,7 +12,7 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
12
12
|
| `wiki-query` | Answer a question from the wiki with citations; auto-ingest relevant un-ingested `raw/` sources when coverage is missing; offer to file the answer back as a new page |
|
|
13
13
|
| `wiki-lint` | Health-check the wiki — contradictions, stale claims, orphan pages, missing concept pages, missing cross-references, never-ingested raw sources |
|
|
14
14
|
| `wiki-archive` | Batch-move terminal tasks, UAT and bugs into `<family>/archive/`, update `archive/index.md`, log the operation (roadmaps, decisions and requirements close in place and are never archived) |
|
|
15
|
-
| `wiki-rotate-log` | Rotate `wiki/log.md` into a timestamped archive file once it
|
|
15
|
+
| `wiki-rotate-log` | Rotate `wiki/log.md` into a timestamped archive file once it reaches 200 lines — forced, not a nudge |
|
|
16
16
|
| `wiki-tidy` | One-shot cleanup: lint, archive terminal tasks/UAT/bugs, rotate the log if overgrown — phases confirmed in sequence |
|
|
17
17
|
|
|
18
18
|
## Requirements
|
|
@@ -123,6 +123,7 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
123
123
|
| Skill | Purpose |
|
|
124
124
|
|-------|---------|
|
|
125
125
|
| `research` | Deep research on a topic — codebase analysis, library docs, web search — writes the report plus primary sources to `raw/research/<slug>/` |
|
|
126
|
+
| `socratic-qa` | Interrogate the user with an exhaustive Socratic question loop until no doubts remain about the task, then play back a Shared Understanding Summary for confirmation before any work starts |
|
|
126
127
|
| `research-company` | Comprehensive company research — mission, operations, leadership, products/services, ~5 years of recent news |
|
|
127
128
|
| `company-align` | Analyse project–company fit against researched company context; surface gaps, strengths, and talking points |
|
|
128
129
|
|
|
@@ -17,7 +17,7 @@ The mechanic for archiving one terminal work item in the `tasks`, `uat`, or `bug
|
|
|
17
17
|
2. **Move the file.** `Bash`, `git mv` only: `git mv wiki/work/<family>/<file>.md wiki/work/<family>/archive/<file>.md`. `git mv` (not plain `mv`) preserves history. `archive/` already exists — do not create it.
|
|
18
18
|
3. **Remove the active-index row.** `Read` `wiki/work/<family>/index.md`, then `Edit` to remove the item's row. If the row is already absent, note it and continue.
|
|
19
19
|
4. **Append the archive-index row.** `Read` `wiki/work/<family>/archive/index.md`, then `Edit` to append one row in the four-column format below, using the item's `id` and `title` from its frontmatter and today's date.
|
|
20
|
-
5. **Append the log entry.** Unless `log` is `skip`,
|
|
20
|
+
5. **Append the log entry.** Unless `log` is `skip`, follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to the caller's `log` text, or the default entry below (forces a rotation first if `wiki/log.md` is at or over threshold — never a question).
|
|
21
21
|
|
|
22
22
|
## Row and log formats
|
|
23
23
|
|
|
@@ -74,7 +74,7 @@ For `roadmaps`, `decisions`, and `requirements`, a finished item **stays where i
|
|
|
74
74
|
|
|
75
75
|
1. **Verify and set the status.** `Read` `wiki/work/<family>/lifecycle.md` and confirm `terminal_status` is a terminal value for the family. `Read` `file`. If its `status:` is already terminal, do not touch the file's content and go to step 2. Otherwise `Edit` once: set `status: <terminal_status>` and bump `updated:` to today's date. Decisions carry a per-block `Status:` instead of a file `status:`; the decision skills set it themselves before calling this step.
|
|
76
76
|
2. **Move the index row.** `Read` `wiki/work/<family>/index.md`, then `Edit` to remove the item's row from `## Active` and add it under `## Closed`, in numeric-ID order. If `## Closed` is missing, create it at the end of the file. If the row is already in `## Closed`, only update its trailing segment; if it is absent from `## Active`, note it and continue.
|
|
77
|
-
3. **Append the log entry.** `
|
|
77
|
+
3. **Append the log entry.** Unless the caller writes its own entry (`log: skip`), follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] close | <ID> — <terminal_status>, closed in place`.
|
|
78
78
|
|
|
79
79
|
### Row format
|
|
80
80
|
|
|
@@ -105,8 +105,8 @@ Every filename below was verified to exist in this repo.
|
|
|
105
105
|
| 4 Bare number | roadmaps | `11` | `wiki/work/roadmaps/ROADMAP-011-build-bootstrap-prefs-tui.md` — legacy 3-digit fallback after `ROADMAP-0011-*.md` misses |
|
|
106
106
|
| 4 Bare number | bugs | `6` | `wiki/work/bugs/BUG-0006-mv-guard-segment-split-omits-pipe.md` |
|
|
107
107
|
| 4 Bare number | uat | `87` | `wiki/work/uat/UAT-0087-bug-close-clustering-offers-regression-task.md` |
|
|
108
|
-
| 2 Full ID + `#DM` | decisions | `DEC-0001#D2` | legacy-prefix input; suffix `#D2` split off; the
|
|
109
|
-
| 2 Full ID + `#DM` | decisions | `ADR-0001#D2` | same integer, so it resolves to that same `
|
|
108
|
+
| 2 Full ID + `#DM` | decisions | `DEC-0001#D2` | legacy-prefix input; suffix `#D2` split off; the number selects the file, so the `ADR` mask `ADR-0001-*.md` matches the migrated `wiki/work/decisions/archive/ADR-0001-wiki-cross-family-linking-schema.md` (scope `active+archive` — this decision is archived; its aliases keep `DEC-0001`); in an unmigrated project the `ADR` masks match nothing and the legacy mask `DEC-0001-*.md` matches instead; caller gets `D2` back separately |
|
|
109
|
+
| 2 Full ID + `#DM` | decisions | `ADR-0001#D2` | same integer, so it resolves to that same `ADR-0001-wiki-cross-family-linking-schema.md` file (the migration keeps the number; before migration the file is `DEC-0001-*.md`); caller gets `D2` back separately |
|
|
110
110
|
| 2 Full ID + `#DM` | decisions | `ADR-0002#D1` | a new-item input: mask `ADR-0002-*.md` matches the file `adr-create` writes as `ADR-0002-<group-slug>.md` (no such file exists in this repo yet); caller gets `D1` back separately |
|
|
111
111
|
| 4 Bare number | requirements | `3` | no requirement files exist in this repo yet; would try `PRD-0003-*.md`, `PRD-003-*.md`, `REQ-0003-*.md`, then `REQ-003-*.md` |
|
|
112
112
|
| 2 Legacy prefix | requirements | `REQ-0003` | legacy input; same integer, so it resolves to `PRD-0003-*` after migration, or to `REQ-0003-*` before it (no such files exist in this repo yet) |
|