peaks-cli 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.4] — 2026-06-13 (hotfix)
+
+### Fixed
+
+- **PreToolUse hook `command` field was bare JavaScript source, not a
+  `node -e "..."` one-liner.** `peaks workspace init` writes
+  `.claude/settings.local.json` containing two PreToolUse hooks (one
+  for `Bash`, one for `Write|Edit|MultiEdit`) whose `command` field
+  was the inner JS payload without the `node -e "..."` wrapper.
+  Claude Code executes the `command` field as a shell string, so
+  bash saw literal `const c=process.argv[1]...` and tripped
+  `syntax error near unexpected token`. Net effect on every 2.0.3
+  install on Windows + macOS + Linux:
+  - Every Bash tool call (peaks CLI or otherwise) was rejected.
+  - Every Write / Edit / MultiEdit call was rejected.
+  - The [Fact-Forcing Gate] bypass that `peaks workspace init` was
+    supposed to install was therefore self-defeating — the bypass
+    broke the gate itself, and the gate could not be reached to fix
+    it.
+  Recovery required the user to delete `.claude/settings.local.json`
+  manually (losing the bypass permanently) or hand-patch the
+  `command` field (drift vs the template).
+  The fix wraps both builders' JS payloads in a real shell-evaluable
+  `node -e "<js>"` form via a new `wrapAsNodeOneLiner` helper in
+  `src/services/workspace/claude-settings-template.ts`. Inner `"`
+  are escaped to `\"`; backslashes pass through unchanged so regex
+  literals like `/\.peaks\//` still match correctly. `process.argv[1]`
+  is the correct slot under `-e` per Node.js docs
+  (https://nodejs.org/api/process.html#processargv) — consistent
+  across Windows, macOS, and Linux. The docstring is reconciled
+  with the implementation (the previous docstring incorrectly said
+  `argv[2]`).
+
+  Regression tests cover:
+  - `buildBashHookCommand()` and `buildWriteHookCommand()` return
+    `node -e "..."` form.
+  - Inner `"` are escaped to `\"`.
+  - Spawning the wrapped command with `peaks workspace init --project . --json`
+    exits 0; with `npm install foo` exits non-zero.
+  - Spawning the Write hook with `.peaks/_runtime/...` and
+    `.peaks/<changeId>/...` paths exits 0; with `src/...`,
+    `package.json`, `.peaks/_archive/...` exits non-zero.
+  - The existing workspace-init round-trip test (case A/B/C) still
+    passes with the wrapper.
+
+---
+
 ## [2.0.3] — 2026-06-13
 
 ### Fixed

package/dist/src/cli/commands/upgrade-commands.js

@@ -1,5 +1,8 @@
 import { runUpgrade } from '../../services/upgrade/upgrade-service.js';
 import { detect1xProjectState } from '../../services/upgrade/1x-detector-service.js';
+import { initWorkspace } from '../../services/workspace/workspace-service.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from '../../shared/result.js';
 export function registerUpgradeCommands(program, io) {
@@ -9,7 +12,8 @@ export function registerUpgradeCommands(program, io) {
         .option('--to <version>', 'target version (only "2.0" supported)', '2.0')
         .option('--project <path>', 'project root to upgrade (default: cwd)')
         .option('--auto', 'non-interactive: accept soft-fail on any sub-step (used by the postinstall hook)')
-        .option('--detect-1x', 'read-only probe: returns the 1.x state as JSON (no file writes); consumed by peaks-solo Step 0.55 to gate the AskUserQuestion')).action((options) => {
+        .option('--detect-1x', 'read-only probe: returns the 1.x state as JSON (no file writes); consumed by peaks-solo Step 0.55 to gate the AskUserQuestion')
+        .option('--apply-init', 'slice 4 (slice 2026-06-13-selfheal-claude-settings-template): run initWorkspace so the drift-driven self-heal fires on the consumer-project .claude/settings.local.json and the offline .peaks/.claude-settings-template.json. Idempotent. Use after a peaks-cli version bump if you do not otherwise re-run init. Mutually exclusive with --detect-1x.')).action(async (options) => {
         const projectRoot = options.project ?? process.cwd();
         // Branch 1: --detect-1x (read-only probe)
         if (options.detect1x === true) {
@@ -32,7 +36,65 @@ export function registerUpgradeCommands(program, io) {
             }
             return;
         }
-        // Branch 2: the umbrella (existing behavior)
+        // Branch 2: --apply-init (slice 4 — slice 2026-06-13-selfheal-claude-settings-template).
+        //
+        // The drift-driven self-heal inside initWorkspace only fires when
+        // the user invokes init. After a peaks-cli version bump, users who
+        // never re-run init are stuck with stale templates until they do.
+        // This flag is the post-bump escape hatch: it triggers init for them.
+        //
+        // We do NOT pass --session-id (the CLI auto-generates / reuses an
+        // existing binding). We do NOT pass --no-claude-hooks (the goal is to
+        // bring the project to the current peaks-cli baseline, including the
+        // consumer-project hook).
+        if (options.applyInit === true) {
+            try {
+                const canonicalRoot = resolveCanonicalProjectRoot(projectRoot);
+                // Match the workspace-init CLI's pattern: resolve the session id
+                // (auto-generate / reuse binding / rotate on outer-mismatch)
+                // BEFORE calling initWorkspace. initWorkspace itself validates
+                // the session id and does NOT auto-generate, so we have to do
+                // the rotation-aware resolution here.
+                const sessionResolution = await ensureSessionWithRotation(canonicalRoot, {
+                    skipRotateOnOuterMismatch: false
+                });
+                const result = await initWorkspace({
+                    projectRoot: canonicalRoot,
+                    sessionId: sessionResolution.sessionId,
+                    allowSessionRebind: false
+                });
+                const nextActions = [];
+                // Surface the same self-heal messaging that workspace-init uses.
+                if (result.claudeSettings.offlineTemplate.action === 'refreshed') {
+                    nextActions.push(`Self-healed .peaks/.claude-settings-template.json (action: refreshed) — ` +
+                        'the offline recovery anchor now matches the current peaks-cli template.');
+                    nextActions.push('⚠️  If you had manually edited .peaks/.claude-settings-template.json, ' +
+                        'those edits have been overwritten by the self-heal.');
+                }
+                else if (result.claudeSettings.offlineTemplate.action === 'written') {
+                    nextActions.push('Wrote .peaks/.claude-settings-template.json (action: written) — ' +
+                        'the offline recovery anchor is now in place.');
+                }
+                if (result.claudeSettings.action === 'refreshed') {
+                    nextActions.push(`Refreshed .claude/settings.local.json (action: refreshed) — ` +
+                        'the consumer-project hook now matches the current peaks-cli template. ' +
+                        'Restart Claude Code so the hooks take effect.');
+                }
+                else if (result.claudeSettings.action === 'written') {
+                    nextActions.push('Wrote .claude/settings.local.json (action: written) — ' +
+                        'the [Fact-Forcing Gate] bypass is now in effect. Restart Claude Code so the hooks take effect.');
+                }
+                const envelope = ok('upgrade.apply-init', result, [], nextActions);
+                printResult(io, envelope, options.json);
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                printResult(io, fail('upgrade.apply-init', 'APPLY_INIT_FAILED', message, { applied: false }, [message]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        // Branch 3: the umbrella (existing behavior)
         try {
             const result = runUpgrade({ projectRoot, auto: options.auto === true });
             const nextActions = [...result.nextActions];

package/dist/src/cli/commands/workspace-commands.js

@@ -217,6 +217,34 @@ export function registerWorkspaceCommands(program, io) {
                     'again without --no-claude-hooks, or drop the contents of ' +
                     '`.peaks/.claude-settings-template.json` into `.claude/settings.local.json` manually.');
             }
+            // Slice 2026-06-13-selfheal-claude-settings-template: surface
+            // the self-heal outcome for the offline
+            // `.peaks/.claude-settings-template.json` copy. When the offline
+            // file was refreshed (i.e. the previous peaks-cli release left
+            // a stale version without the `node -e "..."` wrapper), the user
+            // benefits from seeing that the manual-recovery anchor now
+            // points at the corrected template. We surface `written` and
+            // `refreshed` as the actionable events; `already-current` is
+            // silent (same rationale as the consumer-project no-op above).
+            //
+            // The `refreshed` nextAction also carries a loud warning that any
+            // MANUAL EDITS the user made to the offline template have been
+            // overwritten — drift detection cannot tell stale-from-prior-release
+            // apart from user-customised, so we surface the warning unconditionally
+            // to make sure anyone who customised sees the prompt.
+            if (report.claudeSettings.offlineTemplate.action === 'refreshed') {
+                nextActions.push(`Self-healed .peaks/.claude-settings-template.json (action: refreshed) — ` +
+                    'the offline recovery anchor now matches the current peaks-cli template. ' +
+                    'No action required; future manual recoveries will copy the corrected wrapper.');
+                nextActions.push('⚠️  If you had manually edited .peaks/.claude-settings-template.json, ' +
+                    'those edits have been overwritten by the self-heal. ' +
+                    'Re-apply your custom matchers / commands on top of the freshly-written template, ' +
+                    'or open an issue if your customisation is a recurring need (the team may promote it to the canonical template).');
+            }
+            else if (report.claudeSettings.offlineTemplate.action === 'written') {
+                nextActions.push(`Wrote .peaks/.claude-settings-template.json (action: written) — ` +
+                    'the offline recovery anchor is now in place for future manual recoveries.');
+            }
             // First-time hooks install decision. Sticky-marker at
             // .peaks/.peaks-init-hooks-decision.json records the user's answer
             // (or the auto-decision) so subsequent inits for new sessions in the

package/dist/src/services/workspace/claude-settings-template.d.ts

@@ -29,6 +29,32 @@
  * canonical list.
  */
 export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.json";
+/**
+ * Informational version of the offline template shape. Bumped when the
+ * template's hooks tree (matchers, allow-list content, wrapper format)
+ * changes in a way that should trigger a refresh of stale on-disk
+ * copies. The comparator (`templateContentMatches`) is the source of
+ * truth for refresh decisions — this constant exists so a developer
+ * reading the diff can correlate a template change with a deliberate
+ * bump. Future work may write a version-marker file to short-circuit
+ * the comparator; for now the constant is informational only.
+ */
+export declare const TEMPLATE_VERSION = "1.1.0";
+/**
+ * Compare two serialized template strings for semantic equivalence.
+ *
+ * Returns `true` iff both strings parse to objects whose
+ * `hooks.PreToolUse` arrays are structurally identical (same length;
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ *
+ * Returns `false` on any `JSON.parse` error, shape mismatch, or
+ * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
+ * the result — the comparison is on the parsed AST, not on bytes.
+ *
+ * This is the comparator `initWorkspace` uses to decide whether to
+ * refresh a stale `.peaks/.claude-settings-template.json` on disk.
+ */
+export declare function templateContentMatches(generated: string, onDisk: string): boolean;
 type ClaudeHookCommand = {
     type: 'command';
     command: string;

package/dist/src/services/workspace/claude-settings-template.js

@@ -52,10 +52,127 @@ const PEAKS_SUBCOMMAND_ALLOWLIST = [
     'upgrade'
 ];
 /**
- * Build the Bash matcher command. The command is a node -e one-liner
- * that reads its candidate command string from argv[2] and exits 0
- * iff the command starts with `peaks <whitelisted-subcommand> ` (or
- * is exactly `peaks <whitelisted-subcommand>` with no trailing args).
+ * Informational version of the offline template shape. Bumped when the
+ * template's hooks tree (matchers, allow-list content, wrapper format)
+ * changes in a way that should trigger a refresh of stale on-disk
+ * copies. The comparator (`templateContentMatches`) is the source of
+ * truth for refresh decisions — this constant exists so a developer
+ * reading the diff can correlate a template change with a deliberate
+ * bump. Future work may write a version-marker file to short-circuit
+ * the comparator; for now the constant is informational only.
+ */
+export const TEMPLATE_VERSION = '1.1.0';
+/**
+ * Compare two serialized template strings for semantic equivalence.
+ *
+ * Returns `true` iff both strings parse to objects whose
+ * `hooks.PreToolUse` arrays are structurally identical (same length;
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ *
+ * Returns `false` on any `JSON.parse` error, shape mismatch, or
+ * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
+ * the result — the comparison is on the parsed AST, not on bytes.
+ *
+ * This is the comparator `initWorkspace` uses to decide whether to
+ * refresh a stale `.peaks/.claude-settings-template.json` on disk.
+ */
+export function templateContentMatches(generated, onDisk) {
+    let parsedGenerated;
+    let parsedOnDisk;
+    try {
+        parsedGenerated = JSON.parse(generated);
+    }
+    catch {
+        return false;
+    }
+    try {
+        parsedOnDisk = JSON.parse(onDisk);
+    }
+    catch {
+        return false;
+    }
+    if (!isTemplateShape(parsedGenerated) || !isTemplateShape(parsedOnDisk)) {
+        return false;
+    }
+    const generatedEntries = parsedGenerated.hooks.PreToolUse;
+    const onDiskEntries = parsedOnDisk.hooks.PreToolUse;
+    if (generatedEntries.length !== onDiskEntries.length) {
+        return false;
+    }
+    for (let i = 0; i < generatedEntries.length; i += 1) {
+        const a = generatedEntries[i];
+        const b = onDiskEntries[i];
+        if (a.matcher !== b.matcher) {
+            return false;
+        }
+        if (!sameHooksArray(a.hooks, b.hooks)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isTemplateShape(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    if (typeof candidate.hooks !== 'object' || candidate.hooks === null) {
+        return false;
+    }
+    const hooksObj = candidate.hooks;
+    return Array.isArray(hooksObj.PreToolUse);
+}
+function sameHooksArray(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        const ha = a[i];
+        const hb = b[i];
+        if (ha.type !== hb.type || ha.command !== hb.command) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Wrap an inner JavaScript payload as a shell-evaluable `node -e "..."`
+ * one-liner. The returned string is what Claude Code writes verbatim
+ * into `.claude/settings.local.json` under the `command` field. Per
+ * Node.js docs (https://nodejs.org/api/process.html#processargv), when
+ * using `-e` there is no script-file slot, so `process.argv[1]` is the
+ * first user-passed extra argument. This is consistent across Windows,
+ * macOS, and Linux.
+ *
+ * Every `"` character in the inner JS must be JSON-escaped as `\\"`
+ * so that the surrounding wrapper `node -e "..."` parses correctly:
+ * the shell sees the escape and passes a literal `"` to Node. A
+ * single missed escape closes the wrapper early and the entire hook
+ * regresses to the bash-syntax-error class of bug.
+ *
+ * @param js Inner JavaScript payload. Must be a single statement or a
+ *           sequence of statements joined with `;`. The wrapper does
+ *           not insert any `;` between the payload and the closing
+ *           `"` because Node accepts a trailing expression with `;`
+ *           already terminated by the payload itself.
+ */
+function wrapAsNodeOneLiner(js) {
+    // Only `"` needs JSON-escaping: the wrapper uses double quotes, so an
+    // unescaped inner `"` would close the wrapper prematurely. Backslashes
+    // do NOT need escaping here — bash inside a `"..."` wrapper reduces
+    // `\\` to `\`, so any `\X` in the inner JS reaches Node as `\X`,
+    // which is what regex literals like `/\.peaks\//` need. Adding a
+    // second `\\` → `\\` pass would double-escape backslashes and break
+    // every regex literal the inner JS contains.
+    const escaped = js.replace(/"/g, '\\"');
+    return `node -e "${escaped}"`;
+}
+/**
+ * Build the Bash matcher command. The command is a `node -e "..."`
+ * one-liner that reads its candidate command string from `argv[1]`
+ * and exits 0 iff the command starts with
+ * `peaks <whitelisted-subcommand> ` (or is exactly
+ * `peaks <whitelisted-subcommand>` with no trailing args).
  *
  * The list is serialised as a JSON array literal embedded in the
  * command string so we avoid regex special-character pitfalls and
@@ -63,15 +180,17 @@ const PEAKS_SUBCOMMAND_ALLOWLIST = [
  */
 function buildBashHookCommand() {
     const allowlistLiteral = JSON.stringify(PEAKS_SUBCOMMAND_ALLOWLIST);
-    // The command reads process.argv[2] (the tool-call command string),
-    // checks it starts with `peaks `, splits on whitespace, and looks
-    // up the second token in the allowlist. Exit 0 = allow, exit 1 =
-    // deny (so the gate fires for non-peaks commands).
-    return ('const c=process.argv[1]||"";' +
+    // The command reads process.argv[1] (the tool-call command string
+    // passed by Claude Code), checks it starts with `peaks `, splits on
+    // whitespace, and looks up the second token in the allowlist. Exit
+    // 0 = allow, exit 1 = deny (so the gate fires for non-peaks
+    // commands).
+    const js = 'const c=process.argv[1]||"";' +
         'if(!c.startsWith("peaks "))process.exit(1);' +
         'const sub=c.slice(6).trim().split(/\\s+/)[0];' +
         `if(${allowlistLiteral}.indexOf(sub)===-1)process.exit(1);` +
-        'process.exit(0)');
+        'process.exit(0)';
+    return wrapAsNodeOneLiner(js);
 }
 /**
  * Build the Write|Edit|MultiEdit matcher command. The command reads
@@ -91,12 +210,14 @@ function buildWriteHookCommand() {
     // Path-matching: allow when the path contains `.peaks/_runtime/`
     // OR when the second `.peaks/` segment starts with anything that
     // looks like a change-id (kebab-case slug). Exit 0 for allow, exit
-    // 1 for deny.
-    return ('const p=process.argv[1]||"";' +
+    // 1 for deny. The candidate path arrives on `process.argv[1]` per
+    // Node.js argv layout under `-e` (cross-platform consistent).
+    const js = 'const p=process.argv[1]||"";' +
         'if(p.includes(".peaks/_runtime/"))process.exit(0);' +
         'const m=p.match(/\\.peaks\\/([a-z0-9][a-z0-9.-]*)\\//);' +
         'if(m&&m[1]&&m[1]!=="_runtime"&&m[1]!=="_dogfood"&&m[1]!=="_sub_agents"&&m[1]!=="_archive"&&m[1]!=="memory"&&m[1]!=="issues"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
-        'process.exit(1)');
+        'process.exit(1)';
+    return wrapAsNodeOneLiner(js);
 }
 /**
  * Build the full template object. The shape is the subset of Claude

package/dist/src/services/workspace/workspace-service.d.ts

@@ -46,10 +46,26 @@ export type WorkspaceInitReport = {
      *   - skipped:        the caller passed noClaudeHooks=true
      * The LLM and the user both see this in the JSON envelope so they
      * can decide whether the bypass is in effect.
+     *
+     * Slice 2026-06-13-selfheal-claude-settings-template: adds the
+     * `offlineTemplate` sub-field, which describes the self-heal action
+     * taken on the offline `.peaks/.claude-settings-template.json` copy.
+     * The offline copy is ALWAYS written/checked (regardless of
+     * noClaudeHooks) because it is the manual-recovery anchor — see
+     * `skills/peaks-solo/references/anchoring-and-session-info.md`.
+     *   - written:        the file did not exist; it was created
+     *   - refreshed:      the file existed but its parsed hooks tree
+     *                     diverged from the current `buildClaudeSettingsLocalJson()`;
+     *                     it was rewritten
+     *   - already-current: the file already matched; no rewrite needed
      */
     claudeSettings: {
         action: 'written' | 'refreshed' | 'already-current' | 'skipped';
         path: string;
+        offlineTemplate: {
+            action: 'written' | 'refreshed' | 'already-current';
+            path: string;
+        };
     };
 };
 export declare class InvalidSessionIdError extends Error {

package/dist/src/services/workspace/workspace-service.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
 import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
 import { setCurrentChangeId } from '../../shared/change-id.js';
-import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME } from './claude-settings-template.js';
+import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
 const PROHIBITED_SUFFIXES = ['session', 'work', 'task', 'test', 'temp', 'tmp'];
 // Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
@@ -192,6 +192,13 @@ const PEAKS_GITIGNORE_SNIPPET = [
     '# Consumer-project .claude/settings.local.json: written by `peaks workspace init`',
     '# to bypass Claude Code [Fact-Forcing Gate] for .peaks/** writes. Local-only.',
     '.claude/settings.local.json',
+    '# Offline template copy (.peaks/.claude-settings-template.json): written by',
+    '# `peaks workspace init` as a manual-recovery anchor. The source-of-truth is',
+    '# peaks-cli\'s own `buildClaudeSettingsLocalJson()` — NOT this committed copy.',
+    '# Gitignored so the init flow\'s drift-driven refresh does not show up as',
+    '# "modified" in `git status` on every release bump. Recovery path: re-run',
+    '# `peaks workspace init` to regenerate; or copy from peaks-cli source.',
+    '.peaks/.claude-settings-template.json',
     PEAKS_GITIGNORE_FOOTER,
     ''
 ].join('\n');
@@ -213,18 +220,29 @@ const PEAKS_GITIGNORE_SNIPPET = [
  * `.claude/settings.local.json` manually. The recovery path is
  * documented in
  * `skills/peaks-solo/references/anchoring-and-session-info.md`.
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: the offline copy
+ * is now ALSO drift-checked (via `templateContentMatches`) so stale
+ * on-disk copies from earlier peaks-cli releases (which lacked the
+ * `node -e "..."` wrapper) get refreshed automatically on the next
+ * init. The action taken on the offline copy is surfaced in
+ * `claudeSettings.offlineTemplate.action`.
  */
 async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks) {
     const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
     const settingsPath = join(projectRoot, settingsRel);
     const template = buildClaudeSettingsLocalJson();
     const serialized = JSON.stringify(template, null, 2) + '\n';
-    // Always drop a copy of the template under .peaks/ so the
-    // --no-claude-hooks recovery flow has a known source-of-truth on
-    // disk. The file is gitignored by the snippet below.
-    await writeOfflineTemplateCopy(projectRoot, serialized);
+    // Always drop (or self-heal) a copy of the template under .peaks/
+    // so the --no-claude-hooks recovery flow has a known source-of-truth
+    // on disk. The file is gitignored by the snippet below.
+    const offlineAction = await writeOfflineTemplateCopy(projectRoot, serialized);
+    const offlineTemplate = {
+        action: offlineAction,
+        path: '.peaks/.claude-settings-template.json'
+    };
     if (noClaudeHooks) {
-        return { action: 'skipped', path: settingsRel };
+        return { action: 'skipped', path: settingsRel, offlineTemplate };
     }
     // Best-effort: ensure .claude/ exists, then write the file. We do
     // not assertSafeSettingsPath here (the .claude/ dir is local to
@@ -257,20 +275,62 @@ async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks) {
     // settings file. The snippet is appended only when the header is
     // missing, so subsequent inits do not double-append.
     await upsertPeaksGitignoreSnippet(projectRoot);
-    return { action, path: settingsRel };
+    return { action, path: settingsRel, offlineTemplate };
 }
 /**
  * Always write (or refresh) a copy of the template at
  * `.peaks/.claude-settings-template.json` so the user has a known
- * source-of-truth on disk for the manual recovery flow. This file is
- * tracked in git (not gitignored) because it is the recovery anchor
- * — if the consumer needs to re-create their .claude/settings.local.json
- * they can copy this file verbatim.
+ * source-of-truth on disk for the manual recovery flow. The file is
+ * GITIGNORED (added to `.peaks/.gitignore` by
+ * `upsertPeaksGitignoreSnippet`) — the source-of-truth lives in
+ * peaks-cli's own `buildClaudeSettingsLocalJson()`, NOT in any
+ * committed copy. Gitignoring it ensures the init flow's drift-driven
+ * refresh does not show up as "modified" in `git status` on every
+ * peaks-cli release bump.
+ *
+ * Recovery path for users who need to re-create their
+ * `.claude/settings.local.json`: re-run `peaks workspace init`
+ * (the file is regenerated); or copy the template straight from
+ * peaks-cli source (`src/services/workspace/claude-settings-template.ts`).
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: drift-check via
+ * `templateContentMatches` BEFORE writing. If the on-disk copy's
+ * parsed hooks tree matches the current `buildClaudeSettingsLocalJson()`
+ * output, the write is skipped (`already-current`). If the file is
+ * missing, it is written (`written`). If it exists but has drifted
+ * (e.g. an earlier release's template without the `node -e "..."`
+ * wrapper, or a user-customised copy), it is rewritten (`refreshed`).
+ * The CLI caller surfaces a warning when `refreshed` because manual
+ * edits the user may have made would be overwritten.
+ *
+ * Returns the action taken so the caller can surface it in the
+ * envelope. Read failures are treated as drift so a malformed
+ * on-disk file always self-heals on the next init.
  */
 async function writeOfflineTemplateCopy(projectRoot, serialized) {
     const copyPath = join(projectRoot, '.peaks', '.claude-settings-template.json');
     await mkdir(join(projectRoot, '.peaks'), { recursive: true });
-    await writeFile(copyPath, serialized, 'utf8');
+    let action = 'written';
+    if (existsSync(copyPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(copyPath, 'utf8');
+            if (templateContentMatches(serialized, existing)) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as drift so the file self-heals.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(copyPath, serialized, 'utf8');
+    }
+    return action;
 }
 /**
  * Append the peaks-managed `.claude/settings.local.json` snippet to

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "2.0.3";
+export declare const CLI_VERSION = "2.0.5";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "2.0.3";
+export const CLI_VERSION = "2.0.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/references/anchoring-and-session-info.md

@@ -31,4 +31,32 @@ If the bypass is not in effect (e.g. `.claude/` was read-only, or the user passe
 
 **Anti-bail-out rule for the gate:** Do NOT skip Step 0 because the gate fired. The gate is a Claude Code core feature that peaks-cli cannot modify directly; peaks-cli can only sidestep it via the hook allow-list. If the gate still blocks Step 0 after the bypass is in effect, the user has a misconfigured `.claude/settings.json` upstream — surface that as a separate `AskUserQuestion` ("Your `.claude/settings.json` is overriding the local allow-list. May peaks-cli delete the local file and regenerate it?") rather than skipping Step 0.
 
-`presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
+`presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
+
+## Step 0.6 — Heal stale templates after a peaks-cli version bump
+
+> Slice 2026-06-13-selfheal-claude-settings-template. Read when the envelope's `claudeSettings.offlineTemplate.action === 'refreshed'` OR when the user just bumped peaks-cli and you suspect the consumer project's templates are out of date.
+
+**Why this step exists:** peaks-cli releases can change `buildClaudeSettingsLocalJson()` — the source-of-truth function for the consumer-project `.claude/settings.local.json` and the offline `.peaks/.claude-settings-template.json`. When that function changes (e.g. the `node -e "..."` wrapper added in commit `9551c52`), existing on-disk copies from previous peaks-cli releases become **stale** and can break Claude Code's [Fact-Forcing Gate] bypass. The drift-driven self-heal inside `initWorkspace` (added in this slice) catches the drift and refreshes both files automatically on the next init. This step is the **user-visible surfacing** of that heal.
+
+**Three trigger paths bring the project to the current peaks-cli baseline:**
+
+1. **Normal workflow (auto):** any `peaks-solo` invocation → Step 0 anchor → `peaks workspace init` → drift check → self-heal if needed. This is the default path; users typically do NOT need to do anything explicit.
+2. **Manual init (idempotent):** `peaks workspace init --project <repo> --json` — same drift check, same self-heal. Safe to re-run any number of times.
+3. **Post-upgrade escape hatch:** `peaks upgrade --apply-init --project <repo> --json` — slice 4 (this slice). For users who upgrade peaks-cli but do not invoke `peaks-solo` after the bump (e.g. they installed 2.0.5 today but their next `peaks-solo` session is next week). The flag triggers `initWorkspace` directly.
+
+**NextActions surfaced after Step 0 when self-heal fires:**
+
+- `claudeSettings.offlineTemplate.action === 'refreshed'` → nextAction: "Self-healed `.peaks/.claude-settings-template.json` (action: refreshed) — the offline recovery anchor now matches the current peaks-cli template."
+- Same → warning nextAction: "⚠️ If you had manually edited `.peaks/.claude-settings-template.json`, those edits have been overwritten by the self-heal. Re-apply your custom matchers / commands on top of the freshly-written template, or open an issue if your customisation is a recurring need (the team may promote it to the canonical template)."
+- `claudeSettings.offlineTemplate.action === 'written'` → nextAction: "Wrote `.peaks/.claude-settings-template.json` (action: written) — the offline recovery anchor is now in place for future manual recoveries."
+- `claudeSettings.action === 'refreshed'` (consumer-project file) → nextAction: "Materialized `.claude/settings.local.json` (action: refreshed) — the [Fact-Forcing Gate] is bypassed for tool calls inside .peaks/\*\*. Restart Claude Code so the hooks take effect."
+- `claudeSettings.action === 'already-current'` → silent (no nextAction) — the bypass is already in effect and matches the current release; do not spam the nextAction list on every init.
+
+**When to surface `--apply-init` to the user (LLM-only guidance):**
+
+- When the user just upgraded peaks-cli (e.g. they ran `npm i -g peaks-cli@latest` between sessions) AND the Step 0 init envelope shows `offlineTemplate.action === 'refreshed'`, do NOT prompt for `--apply-init` — the heal already happened.
+- When the user reports a stuck [Fact-Forcing Gate] that survives Step 0 (i.e. `peaks workspace init` ran without throwing but `Bash` / `Write` calls still get blocked), surface `peaks upgrade --apply-init --project <repo>` as a manual fallback. The flag is idempotent — safe to re-run.
+- When the user's project has NO `.peaks/_runtime/` at all (i.e. they never ran init), do NOT recommend `--apply-init` first; recommend `peaks workspace init` instead. `--apply-init` works on first-time projects too, but `init` is the canonical entry point and produces a richer envelope.
+
+**Anti-bail-out rule:** do NOT silently swallow the warning nextAction about manual-edits-overwritten. If the user customised `.peaks/.claude-settings-template.json` and the self-heal wiped their changes, that is data loss from their perspective — surface it. The loud ⚠️ is a feature, not noise.