peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/workflow/workflow-spec.js

@@ -0,0 +1,431 @@
+/**
+ * peaks-workflow v3.0.0 — Slice A.1 + Slice B.1
+ *
+ * Schema for `.peaks/workflows/<id>.yaml` (text + git, reviewable per ADR
+ * 0007 v2 concern #1). Workflows are the WHO/HOW/WITH-WHAT layer; SOPs
+ * remain the WHAT layer (gate definitions). Workflows reference SOPs
+ * for their gates — never duplicate gate logic.
+ *
+ * The schema is intentionally narrow on v3.0.0:
+ *  - phases[] (ordered or grouped for parallelism)
+ *  - gates[] (sop-id references — the leaf primitive)
+ *  - evaluators[] (native evaluator types the runtime can call directly
+ *    without LLM scheduling)
+ *  - contextSnapshot (files + scope the LLM/worker should preload)
+ *  - budget (token + wall + cycle caps)
+ *
+ * Karpathy §2 Simplicity First: no external framework, no DSL, no new
+ * IO. Pure types + a single `parseWorkflowYaml` / `lintWorkflowSpec`
+ * pair. Anything more elaborate (e.g. conditionals on outputs) belongs
+ * in a future minor.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+const VALID_EVALUATORS = new Set([
+    'karpathy',
+    'code-review',
+    'security-review',
+    'perf-baseline',
+    'verdict-aggregate',
+    'monotonic-improvement',
+    'impact-scan',
+    'smoke-run',
+    'canary-watch'
+]);
+const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Parse a raw yaml string into a workflow spec. Pure (no IO), throws on
+ *  unparseable input. Use `lintWorkflowSpec` after parsing for semantic checks. */
+export function parseWorkflowYaml(raw, expectedId) {
+    // Minimal hand-rolled YAML loader — we control the schema and want zero
+    // new deps. The shape is flat-ish: nested objects only via indentation.
+    // Indentation depth = 2 spaces (matches the default-fullauto-md.yaml we ship).
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new Error('workflow yaml: input is empty');
+    }
+    const lines = raw.split(/\r?\n/);
+    // First non-blank line should be `schemaVersion: 1`. Detect blank-header
+    // tolerance: skip leading blanks/comments.
+    const root = {};
+    let i = 0;
+    while (i < lines.length && (lines[i]?.trim() === '' || lines[i]?.trim().startsWith('#')))
+        i++;
+    // Strip a leading `---` document marker (YAML frontmatter) if present.
+    if (lines[i]?.trim() === '---')
+        i++;
+    const stack = [{ kind: 'object', container: root, key: '__root__' }];
+    function pushChild(parent, childKey, child) {
+        if (parent.kind === 'object') {
+            parent.container[childKey] = child;
+        }
+    }
+    for (; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#'))
+            continue;
+        const indent = leadingSpaces(line);
+        const trimmed = line.trim();
+        // Pop the stack to the correct depth.
+        // indent 0 → root only; indent 2 → 1 deep; indent 4 → 2 deep; etc.
+        while (stack.length > 1) {
+            const top = stack[stack.length - 1];
+            const expectedIndent = (stack.length - 1) * 2;
+            if (indent <= expectedIndent - 2) {
+                stack.pop();
+            }
+            else {
+                break;
+            }
+            void top;
+        }
+        const top = stack[stack.length - 1];
+        if (indent === 0 && trimmed.endsWith(':')) {
+            // New top-level key — open a child container.
+            const key = trimmed.slice(0, -1);
+            const peek = (lines[i + 1] ?? '').trim();
+            if (peek.startsWith('- ') || peek === '-') {
+                const arr = [];
+                pushChild(top, key, arr);
+                stack.push({ kind: 'array', container: arr, key });
+            }
+            else {
+                const obj = {};
+                pushChild(top, key, obj);
+                stack.push({ kind: 'object', container: obj, key });
+            }
+            continue;
+        }
+        if (indent === 0 && trimmed.includes(':')) {
+            const key = trimmed.split(':')[0] ?? '';
+            const value = trimmed.split(':').slice(1).join(':').trim();
+            pushChild(top, key, parseScalar(value));
+            continue;
+        }
+        if (top.kind === 'array' && trimmed.startsWith('- ')) {
+            // Array item — peek next line for nested-key continuation.
+            const itemText = trimmed.slice(2);
+            // Detect: `- files:` (nested array) or `- id: foo` (inline object) or
+            // `- src/foo` (scalar).
+            const nextLine = (lines[i + 1] ?? '').trim();
+            const nextIndent = leadingSpaces(lines[i + 1] ?? '');
+            if (itemText.endsWith(':') && (nextLine.startsWith('- ') || nextLine === '-') && nextIndent > indent) {
+                // Nested array under object.
+                const obj = {};
+                const childKey = itemText.slice(0, -1);
+                obj['__pendingArrayKey'] = childKey;
+                top.container.push(obj);
+                // We push a new frame so subsequent `- ` lines belong to the inner array.
+                stack.push({ kind: 'array', container: top.container, key: childKey });
+                // Replace top's last item with the placeholder object — but we
+                // actually need a separate child array. Simpler: convert the
+                // last pushed object into { [childKey]: [] } and push the array
+                // as a new frame.
+                const arr = [];
+                const placeholder = { [childKey]: arr };
+                top.container.pop();
+                top.container.push(placeholder);
+                // Replace the top frame's container with the new array.
+                stack[stack.length - 1] = { kind: 'array', container: arr, key: childKey };
+            }
+            else if (itemText.includes(':')) {
+                // Inline object.
+                const obj = {};
+                const inlineParts = itemText.split(':');
+                obj[inlineParts[0] ?? ''] = parseScalar((inlineParts.slice(1).join(':')).trim());
+                top.container.push(obj);
+                stack.push({ kind: 'object', container: obj, key: inlineParts[0] ?? '' });
+            }
+            else {
+                top.container.push(parseScalar(itemText));
+            }
+            continue;
+        }
+        if (top.kind === 'array' && trimmed.includes(':') && !trimmed.startsWith('- ')) {
+            // Continuation of the last array object.
+            const lastItem = top.container[top.container.length - 1];
+            if (lastItem !== undefined && lastItem !== null && typeof lastItem === 'object' && !Array.isArray(lastItem)) {
+                const parts = trimmed.split(':');
+                const key = parts[0] ?? '';
+                const value = parts.slice(1).join(':').trim();
+                lastItem[key] = parseScalar(value);
+            }
+            continue;
+        }
+        if (top.kind === 'object' && trimmed.includes(':')) {
+            const parts = trimmed.split(':');
+            const key = parts[0] ?? '';
+            const value = parts.slice(1).join(':').trim();
+            const peek = (lines[i + 1] ?? '').trim();
+            const nextIndent = leadingSpaces(lines[i + 1] ?? '');
+            if (value === '' && (peek.startsWith('- ') || peek === '-') && nextIndent > indent) {
+                // Nested array under this object key.
+                const arr = [];
+                top.container[key] = arr;
+                stack.push({ kind: 'array', container: arr, key });
+            }
+            else if (value === '|' || value === '>') {
+                // Block scalar (literal / folded) — accumulate lines at indent > key.
+                const blockLines = [];
+                const blockIndent = indent + 2;
+                let j = i + 1;
+                while (j < lines.length) {
+                    const bl = lines[j] ?? '';
+                    if (bl.trim() === '') {
+                        blockLines.push('');
+                        j++;
+                        continue;
+                    }
+                    if (leadingSpaces(bl) < blockIndent && bl.trim() !== '')
+                        break;
+                    blockLines.push(bl.slice(blockIndent));
+                    j++;
+                }
+                const joined = value === '|' ? blockLines.join('\n') : blockLines.join(' ');
+                top.container[key] = joined.replace(/\n+$/, '').trim();
+                i = j - 1;
+            }
+            else {
+                top.container[key] = parseScalar(value);
+            }
+            continue;
+        }
+    }
+    // Build the typed spec.
+    return buildSpec(root, expectedId);
+}
+function buildSpec(root, expectedId) {
+    const id = stringField(root, 'id', expectedId);
+    if (id !== expectedId) {
+        throw new Error(`workflow yaml: id "${id}" does not match filename "${expectedId}"`);
+    }
+    const schemaVersion = numberField(root, 'schemaVersion', 1);
+    if (schemaVersion !== 1) {
+        throw new Error(`workflow yaml: unsupported schemaVersion ${schemaVersion} (expected 1)`);
+    }
+    const phasesRaw = arrayField(root, 'phases');
+    const gatesRaw = arrayField(root, 'gates');
+    const evaluatorsRaw = arrayField(root, 'evaluators');
+    const snapshotRaw = objectField(root, 'contextSnapshot');
+    const budgetRaw = objectField(root, 'budget');
+    const phases = phasesRaw.map((p) => buildPhase(p));
+    const gates = gatesRaw.map((g) => buildGate(g));
+    const evaluators = evaluatorsRaw.map((e) => buildEvaluator(e));
+    const contextSnapshot = {
+        files: stringArrayField(snapshotRaw, 'files'),
+        memory: stringArrayField(snapshotRaw, 'memory')
+    };
+    const budget = {
+        ...(budgetRaw['tokens'] !== undefined ? { tokens: numberField(budgetRaw, 'tokens') } : {}),
+        ...(budgetRaw['wallSeconds'] !== undefined ? { wallSeconds: numberField(budgetRaw, 'wallSeconds') } : {}),
+        ...(budgetRaw['cycles'] !== undefined ? { cycles: numberField(budgetRaw, 'cycles') } : {})
+    };
+    return {
+        schemaVersion: 1,
+        id,
+        label: stringField(root, 'label', id),
+        description: stringField(root, 'description', ''),
+        phases,
+        gates,
+        evaluators,
+        contextSnapshot,
+        budget
+    };
+}
+function buildPhase(raw) {
+    const obj = objectField({ phase: raw }, 'phase');
+    const id = stringField(obj, 'id');
+    if (!ID_PATTERN.test(id)) {
+        throw new Error(`workflow phase id "${id}" must match ${ID_PATTERN.source}`);
+    }
+    const role = stringField(obj, 'role');
+    if (!role.startsWith('peaks-')) {
+        throw new Error(`workflow phase "${id}" role "${role}" must start with "peaks-"`);
+    }
+    const gatesRaw = obj['gates'];
+    const gates = Array.isArray(gatesRaw) ? gatesRaw.map((g) => String(g)) : [];
+    const outputRaw = obj['outputContract'];
+    const outputContract = Array.isArray(outputRaw) ? outputRaw.map((g) => String(g)) : [];
+    const dependsOnRaw = obj['dependsOn'];
+    const dependsOn = Array.isArray(dependsOnRaw) ? dependsOnRaw.map((g) => String(g)) : undefined;
+    const parallelGroup = typeof obj['parallelGroup'] === 'string' ? obj['parallelGroup'] : undefined;
+    return {
+        id,
+        role,
+        promptTemplate: stringField(obj, 'promptTemplate'),
+        gates,
+        outputContract,
+        ...(dependsOn !== undefined ? { dependsOn } : {}),
+        ...(parallelGroup !== undefined ? { parallelGroup } : {})
+    };
+}
+function buildGate(raw) {
+    const obj = objectField({ gate: raw }, 'gate');
+    const id = stringField(obj, 'id');
+    const sopId = stringField(obj, 'sopId');
+    const description = typeof obj['description'] === 'string' ? obj['description'] : undefined;
+    return {
+        id,
+        sopId,
+        ...(description !== undefined ? { description } : {})
+    };
+}
+function buildEvaluator(raw) {
+    const obj = objectField({ evaluator: raw }, 'evaluator');
+    const typeRaw = stringField(obj, 'type');
+    if (!VALID_EVALUATORS.has(typeRaw)) {
+        throw new Error(`workflow evaluator type "${typeRaw}" is not a native evaluator (allowed: ${[...VALID_EVALUATORS].join(', ')})`);
+    }
+    const type = typeRaw;
+    const gate = typeof obj['gate'] === 'string' ? obj['gate'] : undefined;
+    const scope = typeof obj['scope'] === 'string' ? obj['scope'] : undefined;
+    const threshold = typeof obj['threshold'] === 'string' ? obj['threshold'] : undefined;
+    return {
+        type,
+        ...(gate !== undefined ? { gate } : {}),
+        ...(scope !== undefined ? { scope } : {}),
+        ...(threshold !== undefined ? { threshold } : {})
+    };
+}
+/** Lint a parsed spec — returns a report with semantic errors / warnings. */
+export function lintWorkflowSpec(spec) {
+    const errors = [];
+    const warnings = [];
+    // Phase ids must be unique.
+    const seen = new Set();
+    for (const phase of spec.phases) {
+        if (seen.has(phase.id))
+            errors.push(`duplicate phase id "${phase.id}"`);
+        seen.add(phase.id);
+    }
+    // Gate references in phases must exist in the gates list (or be a known
+    // built-in like "Gate B3").
+    const gateIds = new Set(spec.gates.map((g) => g.id));
+    for (const phase of spec.phases) {
+        for (const gateRef of phase.gates) {
+            if (!gateIds.has(gateRef) && !gateRef.startsWith('Gate ')) {
+                warnings.push(`phase "${phase.id}" references unknown gate "${gateRef}" (not in gates[] and not a built-in "Gate …" label)`);
+            }
+        }
+    }
+    // Evaluator gates must match a gate id when present.
+    for (const ev of spec.evaluators) {
+        if (ev.gate !== undefined && !gateIds.has(ev.gate) && !ev.gate.startsWith('Gate ')) {
+            warnings.push(`evaluator "${ev.type}" references unknown gate "${ev.gate}"`);
+        }
+    }
+    // dependsOn references must resolve.
+    const phaseIds = new Set(spec.phases.map((p) => p.id));
+    for (const phase of spec.phases) {
+        if (phase.dependsOn !== undefined) {
+            for (const dep of phase.dependsOn) {
+                if (!phaseIds.has(dep))
+                    errors.push(`phase "${phase.id}" depends on missing phase "${dep}"`);
+            }
+        }
+    }
+    // Parallel groups must contain ≥2 phases.
+    const groupCounts = new Map();
+    for (const phase of spec.phases) {
+        if (phase.parallelGroup !== undefined) {
+            groupCounts.set(phase.parallelGroup, (groupCounts.get(phase.parallelGroup) ?? 0) + 1);
+        }
+    }
+    for (const [group, count] of groupCounts) {
+        if (count < 2)
+            warnings.push(`parallelGroup "${group}" has only ${count} phase(s); parallelism requires ≥2`);
+    }
+    // Budget sanity.
+    if (spec.budget.cycles !== undefined && spec.budget.cycles < 1) {
+        errors.push(`budget.cycles must be ≥1 when set (got ${spec.budget.cycles})`);
+    }
+    if (spec.budget.tokens !== undefined && spec.budget.tokens < 1) {
+        errors.push(`budget.tokens must be ≥1 when set (got ${spec.budget.tokens})`);
+    }
+    if (spec.budget.wallSeconds !== undefined && spec.budget.wallSeconds < 1) {
+        errors.push(`budget.wallSeconds must be ≥1 when set (got ${spec.budget.wallSeconds})`);
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        normalizedSpec: spec
+    };
+}
+// ─── yaml helper primitives ─────────────────────────────────────────────
+function leadingSpaces(line) {
+    let n = 0;
+    for (const ch of line) {
+        if (ch === ' ')
+            n++;
+        else
+            break;
+    }
+    return n;
+}
+function parseScalar(raw) {
+    if (raw === '')
+        return '';
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (raw === 'null' || raw === '~')
+        return null;
+    // Inline array form `[a, b, c]`
+    if (raw.startsWith('[') && raw.endsWith(']')) {
+        const inner = raw.slice(1, -1).trim();
+        if (inner === '')
+            return [];
+        return inner.split(',').map((s) => parseScalar(s.trim()));
+    }
+    // Strip optional surrounding quotes.
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    // Number?
+    if (/^-?\d+$/.test(raw))
+        return parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw))
+        return parseFloat(raw);
+    return raw;
+}
+function stringField(obj, key, fallback) {
+    const v = obj[key];
+    if (typeof v === 'string')
+        return v;
+    if (fallback !== undefined)
+        return fallback;
+    throw new Error(`workflow yaml: missing required string field "${key}"`);
+}
+function numberField(obj, key, fallback) {
+    const v = obj[key];
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (fallback !== undefined)
+        return fallback;
+    throw new Error(`workflow yaml: missing required number field "${key}"`);
+}
+function arrayField(obj, key) {
+    const v = obj[key];
+    if (v === undefined)
+        return [];
+    if (!Array.isArray(v))
+        throw new Error(`workflow yaml: field "${key}" must be an array`);
+    return v;
+}
+function objectField(obj, key) {
+    const v = obj[key];
+    if (v === undefined)
+        return {};
+    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+        throw new Error(`workflow yaml: field "${key}" must be an object`);
+    }
+    return v;
+}
+function stringArrayField(obj, key) {
+    const v = obj[key];
+    if (v === undefined)
+        return [];
+    if (!Array.isArray(v))
+        throw new Error(`workflow yaml: field "${key}" must be an array of strings`);
+    return v.map((s) => String(s));
+}

package/dist/services/workflow/workflow-state-store.d.ts

@@ -0,0 +1,27 @@
+export type WorkflowSkipState = {
+    rid: string;
+    skippedGates: string[];
+    skipReason: string;
+    skipAppliedAt: string;
+    skipAppliedBy: string;
+    callerKind: 'human' | 'llm' | 'script';
+};
+/**
+ * Read the skip-state for a rid, or `null` if no state file exists or
+ * the file is malformed. The caller is expected to treat `null` as
+ * "no skip applied; evaluate all gates normally".
+ */
+export declare function readSkipState(projectRoot: string, sessionId: string, rid: string): WorkflowSkipState | null;
+/**
+ * Write (or overwrite) the skip-state for a rid. Returns the absolute
+ * path to the file that was written. Caller is responsible for
+ * surfacing this in the envelope as `persistedTo`.
+ */
+export declare function writeSkipState(projectRoot: string, sessionId: string, state: WorkflowSkipState): string;
+/**
+ * Delete the skip-state file for a rid. Idempotent: missing file is
+ * a no-op (returns false). Used by `peaks workflow unskip` (v2) and
+ * by the rollback path of `applySkip` if the caller passes
+ * `--dry-run` and we want to clean up any preview state.
+ */
+export declare function deleteSkipState(projectRoot: string, sessionId: string, rid: string): boolean;

package/dist/services/workflow/workflow-state-store.js

@@ -0,0 +1,95 @@
+/**
+ * Slice 2026-06-13-peaks-workflow-skip — workflow state store.
+ *
+ * Per-slice ephemeral runtime state, keyed by rid. Lives under
+ * `.peaks/_runtime/<sessionId>/workflow-state/<rid>.json` (gitignored
+ * alongside the rest of `.peaks/_runtime/`).
+ *
+ * Today only the skip-marker shape is persisted. Future workflow-edit
+ * primitives (e.g. `peaks workflow inject`, `peaks workflow unskip`)
+ * can extend the schema additively.
+ *
+ * Design:
+ *   - Synchronous read (the state file is tiny, < 200 bytes; not worth
+ *     an async I/O layer for it).
+ *   - Synchronous write (same rationale; the file is in the user's
+ *     own `.peaks/_runtime/` and the write is bounded by the
+ *     dispatcher that already has the file handle).
+ *   - Tolerate malformed JSON: returns null on parse error so the
+ *     caller can treat "no state" as "no skip applied" rather than
+ *     blowing up the workflow.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const STATE_FILE_NAME = 'workflow-state.json';
+function stateFilePath(projectRoot, sessionId, rid) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'workflow-state', `${rid}.json`);
+}
+/**
+ * Read the skip-state for a rid, or `null` if no state file exists or
+ * the file is malformed. The caller is expected to treat `null` as
+ * "no skip applied; evaluate all gates normally".
+ */
+export function readSkipState(projectRoot, sessionId, rid) {
+    const path = stateFilePath(projectRoot, sessionId, rid);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isWorkflowSkipState(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Write (or overwrite) the skip-state for a rid. Returns the absolute
+ * path to the file that was written. Caller is responsible for
+ * surfacing this in the envelope as `persistedTo`.
+ */
+export function writeSkipState(projectRoot, sessionId, state) {
+    const path = stateFilePath(projectRoot, sessionId, state.rid);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    return path;
+}
+/**
+ * Delete the skip-state file for a rid. Idempotent: missing file is
+ * a no-op (returns false). Used by `peaks workflow unskip` (v2) and
+ * by the rollback path of `applySkip` if the caller passes
+ * `--dry-run` and we want to clean up any preview state.
+ */
+export function deleteSkipState(projectRoot, sessionId, rid) {
+    const path = stateFilePath(projectRoot, sessionId, rid);
+    if (!existsSync(path)) {
+        return false;
+    }
+    unlinkSync(path);
+    return true;
+}
+function isWorkflowSkipState(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    if (typeof v.rid !== 'string')
+        return false;
+    if (!Array.isArray(v.skippedGates))
+        return false;
+    if (!v.skippedGates.every((g) => typeof g === 'string'))
+        return false;
+    if (typeof v.skipReason !== 'string')
+        return false;
+    if (typeof v.skipAppliedAt !== 'string')
+        return false;
+    if (typeof v.skipAppliedBy !== 'string')
+        return false;
+    if (v.callerKind !== 'human' && v.callerKind !== 'llm' && v.callerKind !== 'script')
+        return false;
+    return true;
+}

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 {};