@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.
Files changed (44) hide show
  1. package/LICENSE.md +105 -0
  2. package/README.md +12 -0
  3. package/lib/scripts/README.md +4 -3
  4. package/lib/scripts/bootstrap-prefs.js +25 -2
  5. package/lib/scripts/git-prefs.js +123 -0
  6. package/lib/scripts/install-global.sh +3 -0
  7. package/lib/scripts/merge-gitignore.sh +11 -5
  8. package/lib/scripts/migrate-project.sh +1 -1
  9. package/lib/scripts/rename-wiki-ids.js +2 -2
  10. package/lib/scripts/sync-wiki-scaffold.sh +5 -11
  11. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  12. package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
  13. package/lib/scripts/templates/guides/stubs/serena.md +4 -1
  14. package/lib/scripts/templates/settings-deny.json +1 -1
  15. package/lib/scripts/templates/wiki/conventions.md +1 -1
  16. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
  17. package/lib/skills/README.md +2 -1
  18. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
  19. package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
  20. package/lib/skills/_shared/LOG-APPEND.md +34 -0
  21. package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
  22. package/lib/skills/adr-create/SKILL.md +2 -2
  23. package/lib/skills/adr-deprecate/SKILL.md +1 -1
  24. package/lib/skills/adr-extract/SKILL.md +1 -1
  25. package/lib/skills/adr-finalize/SKILL.md +2 -1
  26. package/lib/skills/autopilot/SKILL.md +1 -1
  27. package/lib/skills/bug-assess/SKILL.md +1 -1
  28. package/lib/skills/bug-triage/SKILL.md +1 -1
  29. package/lib/skills/git-commit/SKILL.md +18 -27
  30. package/lib/skills/prd-create/SKILL.md +2 -2
  31. package/lib/skills/prd-deprecate/SKILL.md +1 -1
  32. package/lib/skills/prd-finalize/SKILL.md +1 -1
  33. package/lib/skills/socratic-qa/SKILL.md +163 -0
  34. package/lib/skills/task-create/SKILL.md +1 -1
  35. package/lib/skills/uat-create/SKILL.md +1 -1
  36. package/lib/skills/uat-skip/SKILL.md +19 -29
  37. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  38. package/lib/skills/wiki-archive/SKILL.md +1 -1
  39. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  40. package/lib/skills/wiki-lint/SKILL.md +1 -1
  41. package/lib/skills/wiki-query/SKILL.md +1 -1
  42. package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
  43. package/lib/skills/wiki-tidy/SKILL.md +5 -12
  44. 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).
@@ -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, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
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. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`), 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). |
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 --set <key> --value <v> (--global | --project <dir> | --target <path>)',
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 ".serena/" "raw/" "wiki/"; do
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/, and wiki/ to git's local ignore list (.git/info/exclude, this machine only)? [y/N]: "; then
441
- if exclude_apply "$GIT_EXCLUDE" ".serena/" "raw/" "wiki/"; then
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" ".serena/" "raw/" "wiki/" && [ "$EXCLUDE_CHANGED" -eq 1 ]; then
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
@@ -40,7 +40,7 @@ fi
40
40
 
41
41
  PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
42
42
  shift
43
- EXTRA_CONTEXT="${*}"
43
+ EXTRA_CONTEXT="$*"
44
44
 
45
45
  # --- Preflight 1: legacy content must exist -------------------------------
46
46
  LEGACY_FAMILIES=(tasks uat adr prd bugs roadmaps)
@@ -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
- if [ "$INTERACTIVE" = true ] && prompt_yn " Existing CLAUDE.md found. Append the LLM Wiki schema to it? [y/N] (no = write CLAUDE.local.md instead): "; then
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 exceeds ~500 lines; create a fresh `log.md` with an archive pointer |
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:440 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.",
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
@@ -75,7 +75,7 @@
75
75
  "Bash(rm -rf /Volumes*)",
76
76
  "Bash(git * --force*)",
77
77
  "Bash(git push * +*)",
78
- "Bash(git push * :*)",
78
+ "Bash(git push *)",
79
79
  "Bash(git push --mirror*)",
80
80
  "Bash(git push --delete*)",
81
81
  "Bash(git filter-branch*)",
@@ -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 grows past **~500 lines**, rotate it with `/wiki-rotate-log`:
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 DEC-0001#D4).
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.
@@ -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 exceeds ~500 lines |
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`, `Read` `wiki/log.md`, then `Edit` to append the caller's `log` text, or the default entry.
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.** `Read` `wiki/log.md`, then `Edit` to append `## [YYYY-MM-DD] close | <ID> — <terminal_status>, closed in place`, unless the caller writes its own entry (`log: skip`).
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 `ADR` masks (`ADR-0001-*.md`, `ADR-001-*.md`) match nothing, then the legacy mask `DEC-0001-*.md` matches `wiki/work/decisions/archive/DEC-0001-wiki-cross-family-linking-schema.md` (scope `active+archive` — this decision is archived); caller gets `D2` back separately |
109
- | 2 Full ID + `#DM` | decisions | `ADR-0001#D2` | same integer, so it resolves to that same `DEC-0001-wiki-cross-family-linking-schema.md` file before migration, and to `ADR-0001-*.md` after it (the migration keeps the number); caller gets `D2` back separately |
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) |