peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/workflow/workflow-router-service.js

@@ -0,0 +1,233 @@
+import { getConfiguredExecutionModelId, getStrongestModelId } from '../config/model-routing.js';
+import { getLocalArtifactPath } from '../artifacts/workspace-service.js';
+import { createRdSwarmPlan } from '../rd/rd-service.js';
+import { createTechPlan, getTechStatus } from '../tech/tech-service.js';
+// Slice 2026-06-29-change-id-root-removal: `validateChangeIdOrThrow`
+// was removed with the change-id axis. Path-safety helpers now live
+// at `shared/path-safety.ts` if this module ever needs them.
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+const WORKFLOW_CONSTRAINTS = Object.freeze([
+    'dry-run-only',
+    'requires-swarm-execution-for-rd-and-qa-when-enabled',
+    'execution-model-from-config-providers',
+    'do-not-launch-agents',
+    'do-not-write-artifacts',
+    'do-not-mutate-target-repo'
+]);
+const EXECUTION_STAGES = ['coding-execution', 'unit-test-execution'];
+const GUIDED_DECISION_STAGES = ['product-direction', 'design-direction'];
+const GOVERNED_DECISION_STAGES = ['product-direction', 'design-direction', 'tech-direction', 'tech-review'];
+export function isWorkflowMode(mode) {
+    return mode === 'code' || mode === 'team';
+}
+function assertSupportedMode(mode) {
+    if (!isWorkflowMode(mode)) {
+        throw new Error('Unsupported workflow mode');
+    }
+}
+function normalizeGoal(goal) {
+    const normalized = goal.trim();
+    if (!normalized) {
+        throw new Error('Goal must be non-empty');
+    }
+    return normalized;
+}
+function assertCodeModeAllowed(mode, codeMode) {
+    if (mode !== 'code' && codeMode !== undefined) {
+        throw new Error('codeMode requires code workflow mode');
+    }
+}
+function step(input, executionModelId, strongestModelId) {
+    const modelRole = EXECUTION_STAGES.includes(input.stage) ? 'execution' : 'strongest';
+    return {
+        ...input,
+        modelRole,
+        modelId: modelRole === 'execution' ? executionModelId : strongestModelId,
+        dryRunOnly: true,
+        invokesAgents: false,
+        writesArtifacts: false
+    };
+}
+export function isCodeMode(value) {
+    return value === 'full-auto' || value === 'guided' || value === 'rnd';
+}
+function getDecisionProfileSummary(mode, codeMode) {
+    if (mode === 'team') {
+        return 'Team mode keeps product and design governance on a human-controlled path while RD execution follows recommended defaults.';
+    }
+    if (codeMode === 'guided') {
+        return 'Guided mode keeps the user in the decision loop for the early recommended defaults, while later execution remains bounded by the routing plan.';
+    }
+    if (codeMode === 'rnd') {
+        return 'R&D mode asks for technical confirmation up front, then applies recommended defaults for implementation, testing, review, and safety checks.';
+    }
+    return 'Full-auto mode applies recommended defaults for product, design, and tech decisions, then runs the engineering pipeline end to end under routing gates.';
+}
+function annotateSteps(steps, codeMode) {
+    const decisionStages = codeMode === 'guided'
+        ? GUIDED_DECISION_STAGES
+        : GOVERNED_DECISION_STAGES;
+    return steps.map((currentStep) => {
+        const isDecisionStage = decisionStages.includes(currentStep.stage);
+        const reasonPrefix = isDecisionStage
+            ? `[${codeMode}] decision stage`
+            : '[routed] execution stage';
+        return {
+            ...currentStep,
+            reason: `${reasonPrefix}: ${currentStep.reason}`
+        };
+    });
+}
+function createSoloSteps(executionModelId, strongestModelId) {
+    return [
+        step({ id: 'code-product-direction', stage: 'product-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Product direction needs strong judgment before execution work is delegated.', dependsOn: [] }, executionModelId, strongestModelId),
+        step({ id: 'code-design-direction', stage: 'design-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Design direction uses the recommended default before cheaper implementation work.', dependsOn: ['code-product-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Technical boundaries and approval gates use the recommended default with high-confidence planning.', dependsOn: ['code-design-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Tech artifacts and gate decisions require strong review and a recommended default path.', dependsOn: ['code-tech-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'code-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'RD task decomposition and acceptance criteria use the recommended default before execution delegation.', dependsOn: ['code-tech-review'] }, executionModelId, strongestModelId),
+        step({ id: 'code-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionModelId === strongestModelId ? 'top-tier' : 'mid-tier', reason: `Coding and routine refactoring must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-rd-planning'] }, executionModelId, strongestModelId),
+        step({ id: 'code-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionModelId === strongestModelId ? 'top-tier' : 'mid-tier', reason: `Unit test authoring and focused test runs must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-coding-execution'] }, executionModelId, strongestModelId),
+        step({ id: 'code-quality-review', stage: 'quality-review', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Reducer and final quality gates need strong synthesis and risk review.', dependsOn: ['code-unit-test-execution'] }, executionModelId, strongestModelId)
+    ];
+}
+function createSoloStepsForMode(codeMode, executionModelId, strongestModelId) {
+    return annotateSteps(createSoloSteps(executionModelId, strongestModelId), codeMode);
+}
+function createTeamSteps(executionModelId, strongestModelId) {
+    return [
+        step({ id: 'team-product-direction', stage: 'product-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team product direction should stay on the governed planning path.', dependsOn: [] }, executionModelId, strongestModelId),
+        step({ id: 'team-design-direction', stage: 'design-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team design direction should preserve reviewability and accountability.', dependsOn: ['team-product-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team technical plans should remain strongly governed before RD execution.', dependsOn: ['team-design-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team tech approval requires strong review before execution.', dependsOn: ['team-tech-direction'] }, executionModelId, strongestModelId),
+        step({ id: 'team-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD task decomposition remains on the governed strongest-model path.', dependsOn: ['team-tech-review'] }, executionModelId, strongestModelId),
+        step({ id: 'team-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionModelId === strongestModelId ? 'top-tier' : 'mid-tier', reason: `Bounded coding tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-rd-planning'] }, executionModelId, strongestModelId),
+        step({ id: 'team-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionModelId === strongestModelId ? 'top-tier' : 'mid-tier', reason: `Unit-test tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-coding-execution'] }, executionModelId, strongestModelId),
+        step({ id: 'team-quality-review', stage: 'quality-review', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD outputs still need reducer and quality review gates.', dependsOn: ['team-unit-test-execution'] }, executionModelId, strongestModelId)
+    ];
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function createModelRouting(steps, executionModelId, strongestModelId) {
+    return {
+        strongestModel: {
+            modelId: strongestModelId,
+            uses: steps.filter((step) => step.modelRole === 'strongest').map((step) => step.stage)
+        },
+        executionModel: {
+            modelId: executionModelId,
+            uses: steps.filter((step) => step.modelRole === 'execution').map((step) => step.stage)
+        }
+    };
+}
+function createModelAssignments(steps) {
+    return steps.map((step) => ({
+        stage: step.stage,
+        owner: step.owner,
+        modelTier: step.modelTier,
+        modelRole: step.modelRole,
+        modelId: step.modelId
+    }));
+}
+function getTechPlanBlockedReasons(techPlan) {
+    return techPlan.available ? techPlan.blockedReasons : techPlan.preview.blockedReasons;
+}
+function getTechPlanNextActions(techPlan) {
+    return [...techPlan.nextActions];
+}
+function createModeStatus(economyMode, swarmMode, executionModelId, executionModelSource, strongestModelId) {
+    const economySummary = economyMode
+        ? `Economy mode enabled: code worker and test worker strictly use ${executionModelId} from config providers.`
+        : `Economy mode disabled: code worker and test worker use ${strongestModelId}, matching planner/reviewer.`;
+    const swarmSummary = swarmMode
+        ? 'Swarm mode enabled: peaks-rd coding, unit-test, and peaks-qa quality work must be represented as swarm worker tasks.'
+        : 'Swarm mode disabled: swarm worker graph generation is bypassed.';
+    return {
+        economyModeEnabled: economyMode,
+        swarmModeEnabled: swarmMode,
+        executionModelId,
+        executionModelSource,
+        summary: `${economySummary} ${swarmSummary}`
+    };
+}
+function getCodeMode(mode, codeMode) {
+    if (mode !== 'code') {
+        return undefined;
+    }
+    if (codeMode === undefined) {
+        return 'full-auto';
+    }
+    if (!isCodeMode(codeMode)) {
+        throw new Error('Unsupported code mode');
+    }
+    return codeMode;
+}
+export function createWorkflowRouterPlan(request) {
+    assertSupportedMode(request.mode);
+    assertCodeModeAllowed(request.mode, request.codeMode);
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // no structural validation gate fires here.
+    const goal = normalizeGoal(request.goal);
+    const maxWorkers = request.maxWorkers ?? 40;
+    // Slice 2.0.1-bug1 round 3: project policy defaults. The slim 2.0.1 DEFAULT_CONFIG
+    // no longer carries economyMode / swarmMode (those moved to per-project preferences),
+    // so we cannot fall back to `DEFAULT_CONFIG.economyMode` / `swarmMode` here. Both
+    // flags are project-policy opt-outs: the absence of an explicit `false` means
+    // "enabled" (matches the pre-2.0.1 implicit default).
+    const economyMode = request.config?.economyMode ?? true;
+    const swarmMode = request.config?.swarmMode ?? true;
+    // Pre-2.0.1 DEFAULT_CONFIG carried an implicit `minimax-2.7` provider
+    // for test fixtures that did not pass `config.providers`. The slim
+    // DEFAULT_CONFIG removed that field, so we re-supply it here only when
+    // the caller did not pass any providers at all. An explicit empty
+    // object (`config: { providers: {} }`) still surfaces the "must be
+    // configured" error from `getConfiguredExecutionModelId`.
+    const effectiveProviders = request.config?.providers ?? { minimax: { model: 'minimax-2.7' } };
+    // Slice 2026-07-09 add-zcode-adapter (A.3): the strongest
+    // planner/reviewer model is now resolved via `getStrongestModelId`,
+    // which reads `config.model` (if present) or falls back to the
+    // env-var-overridable default. This decouples the strongest-model
+    // pick from any specific vendor constant.
+    const strongestModelId = getStrongestModelId(request.config);
+    const executionModelId = economyMode !== false ? getConfiguredExecutionModelId(effectiveProviders) : strongestModelId;
+    const modeStatus = createModeStatus(economyMode, swarmMode, executionModelId, economyMode ? 'config.providers' : 'planner-reviewer-strongest-model', strongestModelId);
+    const codeMode = getCodeMode(request.mode, request.codeMode);
+    const decisionProfile = getDecisionProfileSummary(request.mode, codeMode);
+    const artifactWorkspacePath = request.artifactWorkspacePath ?? (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
+    const sharedWorkspaceOptions = {
+        ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
+        ...(request.workspace ? { workspace: request.workspace } : {})
+    };
+    const techStatus = getTechStatus({ sessionId: request.sessionId, ...sharedWorkspaceOptions });
+    const techPlan = createTechPlan({ sessionId: request.sessionId, goal, swarm: swarmMode, dryRun: true, ...sharedWorkspaceOptions });
+    const rdPlan = createRdSwarmPlan({ skill: 'rd', sessionId: request.sessionId, goal, maxWorkers, swarmMode, executionModelId, dryRun: true, ...sharedWorkspaceOptions });
+    const steps = codeMode ? createSoloStepsForMode(codeMode, executionModelId, strongestModelId) : createTeamSteps(executionModelId, strongestModelId);
+    const blockedReasons = uniqueStrings([
+        ...techStatus.blockedReasons,
+        ...getTechPlanBlockedReasons(techPlan),
+        ...rdPlan.blockedReasons
+    ]);
+    const nextActions = blockedReasons.includes('artifact-workspace-unavailable')
+        ? [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+        : uniqueStrings([...techStatus.nextActions, ...getTechPlanNextActions(techPlan), ...rdPlan.nextActions]);
+    return {
+        sessionId: request.sessionId,
+        goal,
+        mode: request.mode,
+        ...(codeMode ? { codeMode } : {}),
+        executionMode: 'autonomous',
+        decisionProfile,
+        dryRun: true,
+        routePolicy: request.mode === 'code' ? 'code-broad-multi-model' : 'team-rd-limited-multi-model',
+        modelRouting: createModelRouting(steps, executionModelId, strongestModelId),
+        modelAssignments: createModelAssignments(steps),
+        modeStatus,
+        techStatus,
+        techPlan,
+        rdPlan,
+        steps,
+        blockedReasons,
+        nextActions,
+        constraints: [...WORKFLOW_CONSTRAINTS]
+    };
+}

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

@@ -0,0 +1,101 @@
+/**
+ * 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-code 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 code 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/services/workspace/claude-settings-template.js

@@ -0,0 +1,254 @@
+/**
+ * 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-code 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 code 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-code 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 code 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 code
+ * 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 code 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 code gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
+}