@codewizard-dt/bootstrap 6.0.1 → 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 (41) hide show
  1. package/README.md +1 -0
  2. package/lib/scripts/README.md +4 -3
  3. package/lib/scripts/bootstrap-prefs.js +25 -2
  4. package/lib/scripts/git-prefs.js +123 -0
  5. package/lib/scripts/install-global.sh +3 -0
  6. package/lib/scripts/merge-gitignore.sh +11 -5
  7. package/lib/scripts/rename-wiki-ids.js +2 -2
  8. package/lib/scripts/sync-wiki-scaffold.sh +5 -11
  9. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  10. package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
  11. package/lib/scripts/templates/guides/stubs/serena.md +4 -1
  12. package/lib/scripts/templates/wiki/conventions.md +1 -1
  13. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +1 -1
  14. package/lib/skills/README.md +2 -1
  15. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +2 -2
  16. package/lib/skills/_shared/ID-RESOLUTION.md +2 -2
  17. package/lib/skills/_shared/LOG-APPEND.md +34 -0
  18. package/lib/skills/_shared/SKILL-BOILERPLATE.md +1 -1
  19. package/lib/skills/adr-create/SKILL.md +2 -2
  20. package/lib/skills/adr-deprecate/SKILL.md +1 -1
  21. package/lib/skills/adr-extract/SKILL.md +1 -1
  22. package/lib/skills/adr-finalize/SKILL.md +2 -1
  23. package/lib/skills/autopilot/SKILL.md +1 -1
  24. package/lib/skills/bug-assess/SKILL.md +1 -1
  25. package/lib/skills/bug-triage/SKILL.md +1 -1
  26. package/lib/skills/git-commit/SKILL.md +18 -27
  27. package/lib/skills/prd-create/SKILL.md +2 -2
  28. package/lib/skills/prd-deprecate/SKILL.md +1 -1
  29. package/lib/skills/prd-finalize/SKILL.md +1 -1
  30. package/lib/skills/socratic-qa/SKILL.md +163 -0
  31. package/lib/skills/task-create/SKILL.md +1 -1
  32. package/lib/skills/uat-create/SKILL.md +1 -1
  33. package/lib/skills/uat-skip/SKILL.md +19 -29
  34. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  35. package/lib/skills/wiki-archive/SKILL.md +1 -1
  36. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  37. package/lib/skills/wiki-lint/SKILL.md +1 -1
  38. package/lib/skills/wiki-query/SKILL.md +1 -1
  39. package/lib/skills/wiki-rotate-log/SKILL.md +14 -24
  40. package/lib/skills/wiki-tidy/SKILL.md +5 -12
  41. package/package.json +1 -1
package/README.md CHANGED
@@ -448,6 +448,7 @@ 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.
452
453
 
453
454
  ## License
@@ -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
@@ -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
@@ -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) |
@@ -0,0 +1,34 @@
1
+ # LOG-APPEND — shared procedure for appending to wiki/log.md
2
+
3
+ The mechanic for appending one entry to `wiki/log.md` — check its size, **force-rotate first with no confirmation** when it has reached the threshold, then append — lives here once. Every `SKILL.md` that writes a log entry supplies only its entry text (see **Inputs**) and runs this procedure instead of a bare "`Read` `wiki/log.md`, then `Edit` to append." This is not a nudge: rotation at threshold is automatic and unconditional, never a question put to the user.
4
+
5
+ ## Inputs
6
+
7
+ | Input | Meaning |
8
+ |-------|---------|
9
+ | `entry` | The exact log entry text to append (the `## [YYYY-MM-DD] <op> \| <subject>` line plus its 1-3 sentence body), as defined by the calling skill. |
10
+
11
+ ## Procedure
12
+
13
+ 1. **Read** `wiki/log.md`. Count its total lines (this is the same `Read` the caller needs anyway to `Edit` it — never a second, separate read).
14
+ 2. **If the line count is 200 or more: rotate now, forced, no confirmation, no question asked.** Run the rotation mechanic exactly as `lib/skills/wiki-rotate-log/SKILL.md` Steps 2 and 4 define it (generate the timestamp, `git mv` the old log to `log-<timestamp>.md`, carry forward any `> Archives:` pointer, create a fresh `log.md` with the standard header and a `rotate` entry recording the forced rotation) — do not restate those steps here, follow them as written. This happens unconditionally at threshold; it is never skipped, deferred, or asked about.
15
+ 3. **Append `entry`.** `Edit` the (possibly just-rotated, now-current) `wiki/log.md` to add `entry` at the bottom. One `Edit` call.
16
+
17
+ ## CRITICAL rules
18
+
19
+ - **Rotation at threshold is forced, never optional.** No skill may ask the user "rotate now?" as part of a routine append — that question belongs only to a human directly invoking `/wiki-rotate-log` itself below threshold (an explicit early rotation request), never to this procedure.
20
+ - **The threshold is 200 lines**, defined once in `lib/skills/wiki-rotate-log/SKILL.md` — this doc reads that value from there rather than restating it, so the two can never drift apart.
21
+ - **Never truncate.** Rotation (when it fires) moves content to a timestamped archive file; nothing is deleted.
22
+ - **One `Edit` per entry.** Never `sed`, `awk`, or `echo >>` to append.
23
+ - A caller that needs to `skip` writing its own entry (because a batch/shared procedure already wrote one, e.g. `ARCHIVE-WORK-ITEM.md`'s `log: skip`) does not invoke this procedure at all for that call — nothing to append, nothing to rotate for.
24
+
25
+ ## Caller deltas
26
+
27
+ What each consumer passes as `entry`. Anything not listed here is the caller's own logic and stays in its `SKILL.md`.
28
+
29
+ | Consumer | `entry` |
30
+ |----------|---------|
31
+ | `task-create`, `adr-create`, `adr-finalize`, `adr-extract`, `adr-deprecate`, `prd-create`, `prd-finalize`, `prd-deprecate`, `uat-create`, `uat-skip`, `bug-triage`, `wiki-lint`, `wiki-query`, `wiki-archive`, `autopilot` | each skill's own documented entry format (unchanged — see that `SKILL.md`'s own log-entry section) |
32
+ | `bug-assess` | one combined entry for the whole pass, not one per bug |
33
+ | `_shared/ARCHIVE-WORK-ITEM.md`, `_shared/ARCHIVE-WORK-ITEM.md`'s in-place-close section | the caller's `log` input, or the shared doc's own default entry, unless `log: skip` |
34
+ | `uat-walk/UAT-CORE.md` Step 7 (shared by `uat-walk`, `uat-auto`, `uat-auto-plus`) | the Closure-procedure entry documented there |
@@ -23,7 +23,7 @@ The line stays inline because it is the instruction to read `mcp-tools.md`: hidi
23
23
 
24
24
  - Never use `sed`, `awk`, `perl -i`, `echo >>`, `cat <<EOF`, or any shell redirection to modify a markdown or config file.
25
25
  - Use `Read` then `Edit`: one `Edit` per change, even when there are many. Never `Write` to rewrite an existing file in full.
26
- - Appending to `wiki/log.md` or an index file is a `Read` then `Edit`, not `echo >>`.
26
+ - Appending to an index file is a `Read` then `Edit`, not `echo >>`. Appending to `wiki/log.md` specifically follows `lib/skills/_shared/LOG-APPEND.md` (forces a rotation first at threshold, never asks).
27
27
  - Bash is reserved for commands with no dedicated tool (for example `git mv`).
28
28
 
29
29
  See `wiki/guides/mcp-tools.md` "Common anti-patterns". Each violation triggers a permission prompt.
@@ -199,8 +199,8 @@ flowchart LR
199
199
  **Default to `proposed`** — create-time supersession is rare; `/adr-finalize` enforces it atomically.
200
200
  4. Don't delete/mutate existing index rows beyond what supersession requires (append-mostly).
201
201
 
202
- ## Step 7: Append to `wiki/log.md` (`Edit` only)
203
- `## [YYYY-MM-DD] adr-create | ADR-NNNN <Decision-Group Title>`
202
+ ## Step 7: Append to `wiki/log.md`
203
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] adr-create | ADR-NNNN <Decision-Group Title>`.
204
204
 
205
205
  ## Step 8: Cross-link from related artifacts
206
206
  For any decision prompted by an active task/feature, link both ways (Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene): in the source task file append `**Decision**: [[ADR-NNNN-slug|ADR-NNNN#DM: title]]`; in the decision's `### Links` list the source task path.
@@ -125,7 +125,7 @@ Use `Read` then `Edit`. If the row is absent, note it and continue.
125
125
 
126
126
  ### Step 6: Append to wiki/log.md
127
127
 
128
- Append one entry to `wiki/log.md`:
128
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
129
129
 
130
130
  ```
131
131
  ## [YYYY-MM-DD] adr-deprecated | ADR-NNNN#DM <title> — reason: <one-line summary of reason>
@@ -165,7 +165,7 @@ Rules for the row content:
165
165
 
166
166
  Also update the PRD's frontmatter `updated` to today's date. Both edits use `Read` + `Edit`.
167
167
 
168
- Append to `wiki/log.md` (re-read it immediately before editing) — both modes:
168
+ Follow `lib/skills/_shared/LOG-APPEND.md` — both modes — with `entry` set to:
169
169
 
170
170
  ```
171
171
  ## [YYYY-MM-DD] adr-extract | <PRD-NNNN or document path> <title> — N ASRs identified
@@ -135,7 +135,8 @@ The file is never moved: a cross-group `superseded` flip (Step 4.6) edits the su
135
135
 
136
136
  `Read` then `Edit` for all index edits.
137
137
 
138
- ## Step 7: Append log entry (`wiki/log.md`, `Edit` only)
138
+ ## Step 7: Append log entry
139
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
139
140
  - No supersession: `## [YYYY-MM-DD] adr-accepted | ADR-NNNN#DM <Decision Title>`
140
141
  - Supersession: `## [YYYY-MM-DD] adr-superseded | ADR-MMMM#DK superseded by ADR-NNNN#DM`
141
142
 
@@ -74,7 +74,7 @@ Reached only when `/whats-next` reported no open work at all.
74
74
 
75
75
  - Record the source in `## Notes` as a path (`raw/research/<slug>/index.md`). Set `derived_from:` only when a `wiki/knowledge/sources/` page for that report already exists; otherwise omit it.
76
76
  - The roadmap's own refusal rules still hold (vague Goal, missing Owner, zero items): if the report yields no concrete recommendation, write nothing and report `Autopilot: research produced no actionable recommendation — no roadmap created.`
77
- 4. **Log it.** Append `## [YYYY-MM-DD] roadmap | ROADMAP-NNNN <title>` plus one sentence — `created by /autopilot from raw/research/<slug>/` — to `wiki/log.md` (append-only; never edit an existing entry).
77
+ 4. **Log it.** Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to `## [YYYY-MM-DD] roadmap | ROADMAP-NNNN <title>` plus one sentence — `created by /autopilot from raw/research/<slug>/`.
78
78
  5. **Stop.** Do not call `/power-mode` in this tick. Research plus roadmap creation is already a long tick, and the next tick's Stage A finds the new roadmap's inline items and drives them.
79
79
 
80
80
  ## Report
@@ -42,7 +42,7 @@ For each confirmed bug, apply the updates per the Step 6/7 procedure in `lib/ski
42
42
 
43
43
  Outcomes this pass does **not** handle: starting work (`in-progress`) and rejection (`wontfix` / `duplicate` / `cannot-reproduce`). Those require the impact/workaround/resolution rigor of `/bug-triage` — never shortcut them here.
44
44
 
45
- Append **one** combined entry to `wiki/log.md` for the whole pass, not one per bug:
45
+ Follow `lib/skills/_shared/LOG-APPEND.md` with **one** combined `entry` for the whole pass, not one per bug:
46
46
 
47
47
  ```
48
48
  ## [YYYY-MM-DD] bug-assess | batch triage
@@ -105,7 +105,7 @@ For active outcomes (Start work / Defer), skip this step entirely — the file s
105
105
 
106
106
  ### Step 9: Append Log Entry
107
107
 
108
- Append to `wiki/log.md`:
108
+ Follow `lib/skills/_shared/LOG-APPEND.md` with `entry` set to:
109
109
 
110
110
  ```
111
111
  ## [YYYY-MM-DD] bug-triage | BUG-NNNN <title>