peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -1,101 +0,0 @@
-/**
- * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
- * consumer-project `.claude/settings.local.json` file.
- *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-solo session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
- *
- * The template is a pure-data function (no filesystem, no clock) so
- * it can be unit-tested in isolation and so the on-disk file matches
- * the in-memory template byte-for-byte.
- *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
- *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
- *      for those paths, non-zero (deny → fall through to gate) for
- *      everything else.
- *
- * The previous `Bash` matcher (which whitelisted a fixed `peaks
- * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
- * [Fact-Forcing Gate] is an Edit/Write concern (it forces the LLM
- * to quote user instructions before any file write), and the Bash
- * matcher was emitting `process.exit(1)` with no stderr on every
- * non-peaks Bash call — a non-blocking "No stderr output" noise
- * decoration in the Claude Code UI even though the underlying tool
- * call still proceeded. Bash command enforcement is now owned by
- * `peaks gate enforce`, which `peaks hooks install` injects into the
- * consumer project's `.claude/settings.json` and which exits 0
- * silently for any command not guarded by a registered SOP gate.
- */
-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.
- *
- * History:
- *   1.0.0 — initial template with `Write|Edit|MultiEdit` and `Bash`
- *           matchers (slice 2.0.1-bug3-fact-forcing-bypass)
- *   1.1.0 — added `node -e "..."` wrapper contract
- *           (slice fix-claude-settings-template-hook-node-wrapper)
- *   1.2.0 — removed the `Bash` matcher; Edit/Write fact-forcing
- *           bypass is the only emit. Bash enforcement is owned by
- *           `peaks gate enforce` in `settings.json`.
- *   1.3.0 — added the v3.1.2 `Bash` PreToolUse matcher that runs
- *           `peaks solo gate-step-08 --project .` (Step 0.8 mechanical
- *           gate). The existing Write|Edit|MultiEdit matcher is
- *           preserved. The new matcher's exit code is the load-bearing
- *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
- */
-export declare const TEMPLATE_VERSION = "1.3.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;
-};
-type ClaudePreToolUseEntry = {
-    matcher: string;
-    hooks: ClaudeHookCommand[];
-};
-type ClaudeSettingsLocal = {
-    hooks: {
-        PreToolUse: ClaudePreToolUseEntry[];
-    };
-};
-/**
- * Build the full template object. The shape is the subset of Claude
- * Code's `.claude/settings.local.json` schema that PreToolUse hooks
- * need — we do not emit the `permissions` block because the fact-
- * forcing gate is a core feature that PreToolUse hooks can short-
- * circuit but that the `permissions` block cannot.
- *
- * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
- */
-export declare function buildClaudeSettingsLocalJson(): ClaudeSettingsLocal;
-export {};

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

@@ -1,254 +0,0 @@
-/**
- * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
- * consumer-project `.claude/settings.local.json` file.
- *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-solo session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
- *
- * The template is a pure-data function (no filesystem, no clock) so
- * it can be unit-tested in isolation and so the on-disk file matches
- * the in-memory template byte-for-byte.
- *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
- *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
- *      for those paths, non-zero (deny → fall through to gate) for
- *      everything else.
- *
- * The previous `Bash` matcher (which whitelisted a fixed `peaks
- * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
- * [Fact-Forcing Gate] is an Edit/Write concern (it forces the LLM
- * to quote user instructions before any file write), and the Bash
- * matcher was emitting `process.exit(1)` with no stderr on every
- * non-peaks Bash call — a non-blocking "No stderr output" noise
- * decoration in the Claude Code UI even though the underlying tool
- * call still proceeded. Bash command enforcement is now owned by
- * `peaks gate enforce`, which `peaks hooks install` injects into the
- * consumer project's `.claude/settings.json` and which exits 0
- * silently for any command not guarded by a registered SOP gate.
- */
-export 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.
- *
- * History:
- *   1.0.0 — initial template with `Write|Edit|MultiEdit` and `Bash`
- *           matchers (slice 2.0.1-bug3-fact-forcing-bypass)
- *   1.1.0 — added `node -e "..."` wrapper contract
- *           (slice fix-claude-settings-template-hook-node-wrapper)
- *   1.2.0 — removed the `Bash` matcher; Edit/Write fact-forcing
- *           bypass is the only emit. Bash enforcement is owned by
- *           `peaks gate enforce` in `settings.json`.
- *   1.3.0 — added the v3.1.2 `Bash` PreToolUse matcher that runs
- *           `peaks solo gate-step-08 --project .` (Step 0.8 mechanical
- *           gate). The existing Write|Edit|MultiEdit matcher is
- *           preserved. The new matcher's exit code is the load-bearing
- *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
- */
-export const TEMPLATE_VERSION = '1.3.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 Write|Edit|MultiEdit matcher command. The command reads
- * the candidate file path from argv[2] and exits 0 iff the path
- * contains `.peaks/_runtime/` or `.peaks/_runtime/<sessionId>/` (the change-id
- * segment is the next path component after `.peaks/`). All other
- * paths exit 1 so the gate fires normally.
- *
- * The matcher is intentionally narrow: it only fires for tools that
- * take a `file_path` (Write/Edit/MultiEdit) and for the Bash
- * subcommand allow-list. It does NOT silently allow arbitrary paths
- * under `.peaks/_runtime/<sessionId>/` — only those matching the documented
- * pattern. Future slice work can broaden the allow-list if the
- * peaks-solo workflow needs more paths.
- */
-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. 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]!=="memory"&&m[1]!=="sops"&&m[1]!=="retrospective"&&m[1]!=="project-scan"&&m[1]!=="perf-baseline")process.exit(0);' +
-        'process.exit(1)';
-    return wrapAsNodeOneLiner(js);
-}
-/**
- * Build the full template object. The shape is the subset of Claude
- * Code's `.claude/settings.local.json` schema that PreToolUse hooks
- * need — we do not emit the `permissions` block because the fact-
- * forcing gate is a core feature that PreToolUse hooks can short-
- * circuit but that the `permissions` block cannot.
- *
- * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
- */
-export function buildClaudeSettingsLocalJson() {
-    return {
-        hooks: {
-            PreToolUse: [
-                {
-                    matcher: 'Write|Edit|MultiEdit',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildWriteHookCommand()
-                        }
-                    ]
-                },
-                {
-                    // v3.1.2 Step 0.8 — Mechanical PreToolUse gate. Runs
-                    // `peaks solo gate-step-08 --project .` before every Bash
-                    // tool call. Exit 0 = allow (with structured stdout
-                    // describing the decision + optional `Next: slice #N+1 of
-                    // M (<currentSlice>)` line when progress.json exists). Exit
-                    // 2 = block (stderr contains the BLOCKED: ... reason).
-                    // The existing Write|Edit|MultiEdit matcher is preserved.
-                    matcher: 'Bash',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildBashGateStep08Command()
-                        }
-                    ]
-                }
-            ]
-        }
-    };
-}
-/**
- * v3.1.2: build the Bash matcher command that runs `peaks solo
- * gate-step-08`. We invoke the CLI directly (not via `node -e "..."`)
- * because the CLI is the only legitimate source of the structured
- * decision + Next: slice context. Exit code is the load-bearing
- * signal — 0 = allow, 2 = block. The hook installer is idempotent:
- * `templateContentMatches` compares the parsed matcher entries, so
- * re-running `peaks workspace init` on a project that already has the
- * Bash hook is a no-op (already-current).
- */
-function buildBashGateStep08Command() {
-    // The hook receives the tool call on stdin. We ignore stdin and
-    // delegate entirely to `peaks solo gate-step-08`, which reads
-    // .peaks/_runtime/<sessionId>/job-shape.json and last-prompt.txt.
-    // `${CLAUDE_PROJECT_DIR}` resolves to the consumer project's root
-    // (Claude Code's standard convention).
-    return 'peaks solo gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
-}

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

@@ -1,45 +0,0 @@
-/**
- * Workspace Service -- consumer `.claude/settings.local.json` materialization.
- *
- * v2.18.3 file-split: this module is the extracted sub-tree of the
- * pre-split `workspace-service.ts`. It hosts the 3 helpers
- * (`materializeClaudeSettingsLocal`, `writeOfflineTemplateCopy`,
- * `upsertPeaksGitignoreSnippet`) plus the `PEAKS_GITIGNORE_*`
- * constants. The high-level `initWorkspace` orchestrator lives in
- * the parent module and calls into this sibling. Function signatures
- * and behaviour are unchanged (verbatim move).
- */
-/**
- * Materialize the consumer-project `.claude/settings.local.json` and
- * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
- * `claudeSettings` descriptor that the caller surfaces in the JSON
- * envelope.
- *
- * The function is idempotent: re-running on an already-materialized
- * project is a no-op (the file is rewritten only when its content
- * diverges from the current peaks-loop release's template, which
- * keeps the consumer up to date as the template evolves).
- *
- * Even when the caller passes `noClaudeHooks: true`, the function
- * still writes a copy of the template at
- * `.peaks/.claude-settings-template.json` so the user has an offline
- * recovery path: copy the file contents into
- * `.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-loop 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`.
- */
-export declare function materializeClaudeSettingsLocal(projectRoot: string, noClaudeHooks: boolean): Promise<{
-    action: 'written' | 'refreshed' | 'already-current' | 'skipped';
-    path: string;
-    offlineTemplate: {
-        action: 'written' | 'refreshed' | 'already-current';
-        path: string;
-    };
-}>;

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

@@ -1,194 +0,0 @@
-/**
- * Workspace Service -- consumer `.claude/settings.local.json` materialization.
- *
- * v2.18.3 file-split: this module is the extracted sub-tree of the
- * pre-split `workspace-service.ts`. It hosts the 3 helpers
- * (`materializeClaudeSettingsLocal`, `writeOfflineTemplateCopy`,
- * `upsertPeaksGitignoreSnippet`) plus the `PEAKS_GITIGNORE_*`
- * constants. The high-level `initWorkspace` orchestrator lives in
- * the parent module and calls into this sibling. Function signatures
- * and behaviour are unchanged (verbatim move).
- */
-import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
-/**
- * The peaks-managed snippet appended to the consumer project's
- * `.peaks/.gitignore` so the local-only settings file never lands
- * in a commit. Marked with a managed-by header so we can detect (and
- * not double-append) on subsequent inits.
- */
-const PEAKS_GITIGNORE_HEADER = '# >>> peaks-loop managed snippet (slice 2.0.1-bug3) — do not edit by hand';
-const PEAKS_GITIGNORE_FOOTER = '# <<< peaks-loop managed snippet';
-const PEAKS_GITIGNORE_SNIPPET = [
-    PEAKS_GITIGNORE_HEADER,
-    '# 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-loop\'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-loop source.',
-    '.peaks/.claude-settings-template.json',
-    PEAKS_GITIGNORE_FOOTER,
-    ''
-].join('\n');
-/**
- * Materialize the consumer-project `.claude/settings.local.json` and
- * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
- * `claudeSettings` descriptor that the caller surfaces in the JSON
- * envelope.
- *
- * The function is idempotent: re-running on an already-materialized
- * project is a no-op (the file is rewritten only when its content
- * diverges from the current peaks-loop release's template, which
- * keeps the consumer up to date as the template evolves).
- *
- * Even when the caller passes `noClaudeHooks: true`, the function
- * still writes a copy of the template at
- * `.peaks/.claude-settings-template.json` so the user has an offline
- * recovery path: copy the file contents into
- * `.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-loop 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`.
- */
-export 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 (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, offlineTemplate };
-    }
-    // Best-effort: ensure .claude/ exists, then write the file. We do
-    // not assertSafeSettingsPath here (the .claude/ dir is local to
-    // the consumer and we trust it on first init; the existing
-    // hooks-settings-service applies the safety check for the Bash
-    // gate-enforce path).
-    await mkdir(join(projectRoot, '.claude'), { recursive: true });
-    let action = 'written';
-    if (existsSync(settingsPath)) {
-        try {
-            const { readFile } = await import('node:fs/promises');
-            const existing = await readFile(settingsPath, 'utf8');
-            if (existing === serialized) {
-                action = 'already-current';
-            }
-            else {
-                action = 'refreshed';
-            }
-        }
-        catch {
-            // Treat any read failure as "needs refresh" so the consumer
-            // always ends up with a valid template on disk.
-            action = 'refreshed';
-        }
-    }
-    if (action !== 'already-current') {
-        await writeFile(settingsPath, serialized, 'utf8');
-    }
-    // Ensure the consumer's .peaks/.gitignore covers the local-only
-    // 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, 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. The file is
- * GITIGNORED (added to `.peaks/.gitignore` by
- * `upsertPeaksGitignoreSnippet`) — the source-of-truth lives in
- * peaks-loop'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-loop 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-loop 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 });
-    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
- * the consumer project's `.peaks/.gitignore`. Preserves any user-
- * managed entries above the snippet. Idempotent: re-running on a
- * project that already has the snippet is a no-op.
- */
-async function upsertPeaksGitignoreSnippet(projectRoot) {
-    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
-    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
-    let existing = '';
-    if (existsSync(gitignorePath)) {
-        try {
-            const { readFile } = await import('node:fs/promises');
-            existing = await readFile(gitignorePath, 'utf8');
-        }
-        catch {
-            existing = '';
-        }
-    }
-    if (existing.includes(PEAKS_GITIGNORE_HEADER)) {
-        return;
-    }
-    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-    const next = existing + separator + (existing.length > 0 ? '\n' : '') + PEAKS_GITIGNORE_SNIPPET;
-    await writeFile(gitignorePath, next, 'utf8');
-}