peaks-cli 1.4.2 → 2.0.1

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

@@ -0,0 +1,381 @@
+/**
+ * peaks upgrade --to 2.0 — umbrella service for the 1.x → 2.0
+ * migration.
+ *
+ * Per the "one-key completion" + "minimal-user-operation" tenets
+ * (2026-06-11), the typical upgrade path is:
+ *
+ *   $ npm i -g peaks-cli@2.0   # postinstall does everything
+ *
+ * OR (postinstall skipped / manual fallback):
+ *
+ *   $ peaks upgrade --to 2.0
+ *
+ * The umbrella orchestrates 7 sub-commands:
+ *   1. config migrate       (already ships as `peaks config migrate`)
+ *   2. standards migrate    (`peaks standards migrate --from-claude-rules`)
+ *   3. memory extract       (already ships as `peaks memory extract`)
+ *   4. hooks install        (already ships as `peaks hooks install`)
+ *   5. skill sync           (this session, `peaks skill sync --all`)
+ *   6. audit verify         (already ships as `peaks audit red-lines`)
+ *   7. write upgrade record (in-process, .peaks/memory/upgrade-2.0-*.md)
+ *
+ * Each sub-step is a thin shell-out to the existing CLI; the
+ * umbrella's only in-process work is the audit and the upgrade
+ * record write. Sub-step failures are SOFT (logged + nextActions
+ * populated) so the umbrella never blocks a successful partial
+ * upgrade.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runRedLinesAudit } from '../audit/red-lines-service.js';
+import { savePreferences } from '../preferences/preferences-service.js';
+import { migrateGitignoreFile } from './gitignore-migrate-service.js';
+const STEPS = [
+    { name: 'config-migrate', args: (p) => ['config', 'migrate', '--project', p, '--apply', '--json'] },
+    { name: 'standards-migrate', args: (p) => ['standards', 'migrate', '--from-claude-rules', '--project', p, '--apply', '--json'] },
+    // memory extract is special: its --artifact takes literal file
+    // paths (memory-service rejects glob patterns via realpathSync).
+    // The umbrella expands the three documented patterns
+    // (skills/**/SKILL.md, CLAUDE.md, .claude/rules/**/*.md) on disk
+    // and passes the resulting literal list. See runUpgrade's special
+    // case below for the args resolution; the args function here is
+    // a placeholder so the STEPS table stays uniform.
+    { name: 'memory-extract', args: (p) => ['memory', 'extract', '--project', p, '--json'] },
+    { name: 'hooks-install', args: (p) => ['hooks', 'install', '--project', p, '--json'] },
+    { name: 'skill-sync', args: (p) => ['skill', 'sync', '--all', '--project', p, '--json'] },
+    { name: 'audit-verify', args: (p) => ['audit', 'red-lines', '--project', p, '--json'] },
+];
+/**
+ * Walk `<root>` recursively and collect every file whose basename
+ * matches `predicate`. Returns absolute paths.
+ *
+ * Mirrors `readMarkdownFilesRecursive` in
+ * src/services/standards/migrate-claude-rules-service.ts so the
+ * umbrella does not pull a new glob dependency (Node 20+ engine
+ * constraint — `fs.globSync` requires Node 22+).
+ */
+function collectFilesRecursive(root, predicate) {
+    if (!existsSync(root))
+        return [];
+    const stat = statSync(root);
+    if (stat.isFile()) {
+        return predicate(root.split(/[\\/]/).pop() ?? '') ? [root] : [];
+    }
+    if (!stat.isDirectory())
+        return [];
+    const out = [];
+    for (const entry of readdirSync(root)) {
+        const child = join(root, entry);
+        let childStat;
+        try {
+            childStat = statSync(child);
+        }
+        catch {
+            continue;
+        }
+        if (childStat.isFile()) {
+            if (predicate(entry))
+                out.push(child);
+        }
+        else if (childStat.isDirectory()) {
+            out.push(...collectFilesRecursive(child, predicate));
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the three documented memory-extract artifact patterns
+ * against a real project tree. Returns project-relative paths
+ * (memory-service joins them with --project root) so the
+ * realpathSync inside memory-service's assertInsideProject
+ * succeeds.
+ *
+ * Patterns:
+ *   - skills/[asterisk][asterisk]/SKILL.md       (project-root convention)
+ *   - .claude/skills/[asterisk][asterisk]/SKILL.md (Claude-Code consumer convention; ice-cola)
+ *   - CLAUDE.md
+ *   - .claude/rules/[asterisk][asterisk]/[asterisk].md
+ *
+ * Returns an empty list when none of the roots exist. The
+ * caller marks the step skipped in that case.
+ */
+function expandMemoryArtifacts(projectRoot) {
+    const out = [];
+    // skills/**/SKILL.md (peaks-cli repo convention)
+    const skillFiles = collectFilesRecursive(join(projectRoot, 'skills'), (name) => name === 'SKILL.md');
+    for (const abs of skillFiles) {
+        out.push(relative(projectRoot, abs));
+    }
+    // .claude/skills/**/SKILL.md (Claude-Code consumer convention;
+    // surfaced by ice-cola dogfood 2026-06-12 — the 1.x install
+    // landed skills under .claude/skills/, not <root>/skills/)
+    const claudeSkillFiles = collectFilesRecursive(join(projectRoot, '.claude', 'skills'), (name) => name === 'SKILL.md');
+    for (const abs of claudeSkillFiles) {
+        out.push(relative(projectRoot, abs));
+    }
+    // CLAUDE.md (literal)
+    const claudeMd = join(projectRoot, 'CLAUDE.md');
+    if (existsSync(claudeMd) && statSync(claudeMd).isFile()) {
+        out.push('CLAUDE.md');
+    }
+    // .claude/rules/**/*.md
+    const claudeRules = collectFilesRecursive(join(projectRoot, '.claude', 'rules'), (name) => name.endsWith('.md'));
+    for (const abs of claudeRules) {
+        out.push(relative(projectRoot, abs));
+    }
+    return out;
+}
+function read1xVersion(cwd) {
+    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';
+    if (home.length === 0)
+        return null;
+    const global = join(home, '.peaks', 'config.json');
+    if (!existsSync(global))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(global, 'utf8'));
+        if (typeof raw.version === 'string')
+            return raw.version;
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function runStep(peaksBin, name, args, timeoutMs = 60_000) {
+    const start = Date.now();
+    // The global `peaks` shim is a `/bin/sh` symlink script (the
+    // npm install postinstall creates `peaks` → `peaks.sh` on
+    // Windows). cmd.exe (the default Windows shell) cannot run
+    // `.sh` scripts directly, so the shim fails with "unknown
+    // command 'migrate'" etc. The fix: prefer the local node
+    // binary + the peaks.js script path. The umbrella resolves
+    // the script path at startup; only falls back to `peaks` if
+    // no script path is available (Unix-only).
+    let command;
+    let spawnArgs;
+    if (peaksBin.includes('\\') || peaksBin.includes('/')) {
+        // peaksBin is a real path (e.g. /c/.../bin/peaks.js);
+        // invoke directly via node.
+        command = process.execPath;
+        spawnArgs = [peaksBin, ...args];
+    }
+    else {
+        // peaksBin is just "peaks" — best-effort shell exec.
+        command = peaksBin;
+        spawnArgs = args;
+    }
+    try {
+        const result = spawnSync(command, spawnArgs, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+        return {
+            name,
+            status: result.status === 0 ? 'pass' : 'fail',
+            exitCode: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name,
+            status: 'fail',
+            exitCode: null,
+            stdout: '',
+            stderr: message,
+            durationMs: Date.now() - start,
+        };
+    }
+}
+function writeUpgradeRecord(projectRoot, result) {
+    try {
+        const memoryDir = join(projectRoot, '.peaks', 'memory');
+        mkdirSync(memoryDir, { recursive: true });
+        const date = new Date().toISOString().slice(0, 10);
+        const file = join(memoryDir, `upgrade-2.0-${date}.md`);
+        const lines = [];
+        lines.push(`# Upgrade to peaks-cli 2.0 — ${date}`);
+        lines.push('');
+        lines.push(`> Auto-generated by \`peaks upgrade --to 2.0${result.applied ? ' --auto' : ''}\`.`);
+        lines.push(`> Per the "one-key completion" + "minimal-user-operation" tenets.`);
+        lines.push('');
+        if (result.fromVersion !== null) {
+            lines.push(`**From version**: ${result.fromVersion}`);
+        }
+        lines.push(`**To version**: 2.0.0`);
+        lines.push(`**Project root**: \`${result.projectRoot}\``);
+        lines.push('');
+        lines.push('## Sub-step results');
+        lines.push('');
+        lines.push('| step | status | exitCode | durationMs |');
+        lines.push('|------|--------|----------|------------|');
+        for (const step of result.steps) {
+            lines.push(`| ${step.name} | ${step.status} | ${step.exitCode ?? 'n/a'} | ${step.durationMs} |`);
+        }
+        lines.push('');
+        if (result.auditBefore !== null || result.auditAfter !== null) {
+            lines.push('## Audit snapshot');
+            lines.push('');
+            if (result.auditBefore !== null) {
+                lines.push(`- Before: totalRedLines=${result.auditBefore.totalRedLines}, cliBacked=${result.auditBefore.cliBacked}`);
+            }
+            if (result.auditAfter !== null) {
+                lines.push(`- After:  totalRedLines=${result.auditAfter.totalRedLines}, cliBacked=${result.auditAfter.cliBacked}`);
+            }
+            lines.push('');
+        }
+        lines.push('## Next actions');
+        lines.push('');
+        for (const a of result.nextActions) {
+            lines.push(`- ${a}`);
+        }
+        writeFileSync(file, lines.join('\n') + '\n', 'utf8');
+        return file;
+    }
+    catch (err) {
+        process.stderr.write(`peaks upgrade: failed to write upgrade record: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+export function runUpgrade(input) {
+    // Resolve the peaks binary. Default: the peaks.js script
+    // co-located with this compiled module (the user just installed
+    // peaks-cli globally, but the global `peaks` shim is a .sh
+    // script that cmd.exe can't run on Windows). Falling back
+    // to just "peaks" lets the umbrella work when invoked from
+    // a Unix-style environment that can run the shim directly.
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Walk up from the compiled location to find bin/peaks.js.
+    // The compiled service lives at dist/src/services/upgrade/upgrade-service.js;
+    // bin/peaks.js is at the peaks-cli root.
+    const peaksBin = input.peaksBin ??
+        resolve(here, '..', '..', '..', '..', 'bin', 'peaks.js');
+    const fallbackPeaks = 'peaks';
+    const resolvedPeaksBin = existsSync(peaksBin) ? peaksBin : fallbackPeaks;
+    const fromVersion = read1xVersion(input.projectRoot);
+    const steps = [];
+    const warnings = [];
+    const nextActions = [];
+    // Ensure .peaks/preferences.json exists. This is the file the
+    // 1.x detector keys off — without it, `peaks upgrade --detect-1x`
+    // keeps returning isOneX=true after a successful upgrade and the
+    // user gets stuck in a re-prompt loop. savePreferences with an
+    // empty override merges with DEFAULT_PREFERENCES and writes; if
+    // the file already exists the user's values are preserved.
+    // Real bug surfaced by ice-cola dogfood 2026-06-12.
+    try {
+        savePreferences(input.projectRoot, {});
+    }
+    catch (err) {
+        warnings.push(`ensure-preferences failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Migrate .gitignore so 2.0 tracked artifacts
+    // (.peaks/standards/, .peaks/memory/*.md durable memories,
+    // .peaks/PROJECT.md) aren't silently hidden by a 1.x wholesale
+    // `/.peaks/` ignore rule. Real bug surfaced by ice-cola dogfood
+    // 2026-06-12: every consumer artifact was being dropped from git
+    // status. Service is idempotent + creates a timestamped backup
+    // before any write.
+    try {
+        const giResult = migrateGitignoreFile({ projectRoot: input.projectRoot, apply: true });
+        if (giResult.changed && giResult.appliedWrite && giResult.backupPath !== null) {
+            nextActions.push(`Updated .gitignore — removed stale wholesale .peaks rule(s): ${giResult.removedRules.join(', ')}. Backup at ${giResult.backupPath}.`);
+        }
+        else if (giResult.missing) {
+            warnings.push('gitignore-migrate skipped: project has no .gitignore');
+        }
+    }
+    catch (err) {
+        warnings.push(`gitignore-migrate failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Audit BEFORE the upgrade (baseline)
+    let auditBefore = null;
+    try {
+        const r = runRedLinesAudit({ projectRoot: input.projectRoot });
+        auditBefore = { totalRedLines: r.audit.totalRedLines, cliBacked: r.audit.cliBacked };
+    }
+    catch (err) {
+        warnings.push(`audit-before failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Run the 6 sub-steps
+    for (const step of STEPS) {
+        if (step.name === 'memory-extract') {
+            // Special case: expand the three glob patterns to literal
+            // paths before spawning. memory-service rejects literal
+            // '**' in artifact paths (assertInsideProject's realpathSync
+            // throws ENOENT) and refuses to run without --artifact.
+            const artifacts = expandMemoryArtifacts(input.projectRoot);
+            if (artifacts.length === 0) {
+                steps.push({
+                    name: 'memory-extract',
+                    status: 'skipped',
+                    exitCode: null,
+                    stdout: '',
+                    stderr: 'no skills/, CLAUDE.md, or .claude/rules/ artifacts found in the project',
+                    durationMs: 0,
+                });
+                continue;
+            }
+            const args = ['memory', 'extract', '--project', input.projectRoot, '--artifact', ...artifacts, '--apply', '--json'];
+            const r = runStep(resolvedPeaksBin, 'memory-extract', args);
+            steps.push(r);
+            if (r.status === 'fail') {
+                warnings.push(`memory-extract failed: ${r.stderr.slice(0, 200)}`);
+            }
+            continue;
+        }
+        const args = step.args(input.projectRoot);
+        const r = runStep(resolvedPeaksBin, step.name, args);
+        steps.push(r);
+        if (r.status === 'fail') {
+            warnings.push(`${step.name} failed: ${r.stderr.slice(0, 200)}`);
+        }
+    }
+    // Audit AFTER the upgrade (verify)
+    let auditAfter = null;
+    try {
+        const r = runRedLinesAudit({ projectRoot: input.projectRoot });
+        auditAfter = { totalRedLines: r.audit.totalRedLines, cliBacked: r.audit.cliBacked };
+    }
+    catch (err) {
+        warnings.push(`audit-after failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const passedCount = steps.filter((s) => s.status === 'pass').length;
+    const failedCount = steps.filter((s) => s.status === 'fail').length;
+    const skippedCount = steps.filter((s) => s.status === 'skipped').length;
+    const applied = failedCount === 0;
+    if (failedCount > 0) {
+        nextActions.push(`${failedCount} sub-step(s) failed. Run \`peaks upgrade --to 2.0\` again to retry the failed steps.`);
+    }
+    if (input.auto !== true) {
+        nextActions.push('Run `peaks audit red-lines --project .` to verify the L2 catalog is healthy.');
+    }
+    nextActions.push('See `docs/UPGRADING-2.0.md` for the manual fallback if this auto-upgrade fails.');
+    // Write the upgrade record (always, even on partial failure —
+    // the user gets a forensic artifact either way)
+    const partial = {
+        applied,
+        fromVersion,
+        toVersion: '2.0.0',
+        projectRoot: input.projectRoot,
+        steps,
+        passedCount,
+        failedCount,
+        skippedCount,
+        auditBefore,
+        auditAfter,
+        upgradeRecordPath: null,
+        nextActions,
+        warnings,
+    };
+    const upgradeRecordPath = writeUpgradeRecord(input.projectRoot, partial);
+    return { ...partial, upgradeRecordPath };
+}

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

@@ -1,4 +1,3 @@
-import { DEFAULT_CONFIG } from '../config/config-types.js';
 import { getConfiguredExecutionModelId, STRONGEST_MODEL_ID } from '../config/model-routing.js';
 import { getLocalArtifactPath } from '../artifacts/workspace-service.js';
 import { createRdSwarmPlan } from '../rd/rd-service.js';
@@ -167,9 +166,21 @@ export function createWorkflowRouterPlan(request) {
     validateChangeIdOrThrow(request.changeId);
     const goal = normalizeGoal(request.goal);
     const maxWorkers = request.maxWorkers ?? 40;
-    const economyMode = request.config?.economyMode ?? DEFAULT_CONFIG.economyMode;
-    const swarmMode = request.config?.swarmMode ?? DEFAULT_CONFIG.swarmMode;
-    const executionModelId = economyMode ? getConfiguredExecutionModelId(request.config?.providers) : STRONGEST_MODEL_ID;
+    // 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' } };
+    const executionModelId = economyMode !== false ? getConfiguredExecutionModelId(effectiveProviders) : STRONGEST_MODEL_ID;
     const modeStatus = createModeStatus(economyMode, swarmMode, executionModelId, economyMode ? 'config.providers' : 'planner-reviewer-strongest-model');
     const soloMode = getSoloMode(request.mode, request.soloMode);
     const decisionProfile = getDecisionProfileSummary(request.mode, soloMode);

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

@@ -0,0 +1,53 @@
+/**
+ * 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 or
+ * commands 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.
+ *
+ * Two matchers are emitted:
+ *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
+ *      `.peaks/_runtime/` and `.peaks/<changeId>/`. Exits 0 (allow)
+ *      for those paths, non-zero (deny → fall through to gate) for
+ *      everything else.
+ *   2. `Bash` — a node one-liner that allows command strings starting
+ *      with `peaks ` (whitelisted subcommand prefix). Exits 0 for
+ *      `peaks <subcommand> ...`, non-zero otherwise.
+ *
+ * The Bash allow-list is conservative: it whitelists the documented
+ * peaks subcommands the skill family invokes during Step 0 (workspace,
+ * skill presence, request, session, scan, sub-agent, gate, standards,
+ * hooks, statusline). See peaks-solo/references/runbook.md for the
+ * canonical list.
+ */
+export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.json";
+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.
+ */
+export declare function buildClaudeSettingsLocalJson(): ClaudeSettingsLocal;
+export {};

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

@@ -0,0 +1,133 @@
+/**
+ * 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 or
+ * commands 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.
+ *
+ * Two matchers are emitted:
+ *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
+ *      `.peaks/_runtime/` and `.peaks/<changeId>/`. Exits 0 (allow)
+ *      for those paths, non-zero (deny → fall through to gate) for
+ *      everything else.
+ *   2. `Bash` — a node one-liner that allows command strings starting
+ *      with `peaks ` (whitelisted subcommand prefix). Exits 0 for
+ *      `peaks <subcommand> ...`, non-zero otherwise.
+ *
+ * The Bash allow-list is conservative: it whitelists the documented
+ * peaks subcommands the skill family invokes during Step 0 (workspace,
+ * skill presence, request, session, scan, sub-agent, gate, standards,
+ * hooks, statusline). See peaks-solo/references/runbook.md for the
+ * canonical list.
+ */
+export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
+/**
+ * Subcommand allow-list for the Bash matcher. The matcher allows any
+ * command that starts with `peaks <subcommand>` for one of these
+ * subcommands. Keep this list in sync with peaks-solo/references/runbook.md.
+ */
+const PEAKS_SUBCOMMAND_ALLOWLIST = [
+    'workspace',
+    'skill',
+    'request',
+    'session',
+    'scan',
+    'sub-agent',
+    'gate',
+    'standards',
+    'hooks',
+    'statusline',
+    'memory',
+    'openspec',
+    'workflow',
+    'doctor',
+    '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).
+ *
+ * The list is serialised as a JSON array literal embedded in the
+ * command string so we avoid regex special-character pitfalls and
+ * keep the allow-list declarative.
+ */
+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]||"";' +
+        '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)');
+}
+/**
+ * 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/<changeId>/` (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/<changeId>/` — 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.
+    return ('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)');
+}
+/**
+ * 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.
+ */
+export function buildClaudeSettingsLocalJson() {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: 'Write|Edit|MultiEdit',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: buildWriteHookCommand()
+                        }
+                    ]
+                },
+                {
+                    matcher: 'Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: buildBashHookCommand()
+                        }
+                    ]
+                }
+            ]
+        }
+    };
+}

package/dist/src/services/workspace/sid-naming-guard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SID naming guard. Enforces the "two-axis" convention from spec §0:
+ * session id: YYYY-MM-DD-session-<3-6 chars lowercase alnum>
+ * change id: kebab-case
+ *
+ * Spec §8.7 — bare forms (sid-3 / sid-h / sid-r / unknown-sid) are
+ * migrated to `_archive/invalid-sids/`, NOT tolerated.
+ */
+export declare const SID_FORMAT_DESCRIPTION = "<YYYY-MM-DD>-session-<3-6 chars lowercase alnum>, e.g. 2026-06-11-session-abc123";
+export declare function isValidSessionId(sid: string): boolean;
+export declare function isValidChangeId(cid: string): boolean;
+export declare function isBareSid(name: string): boolean;
+export declare function assertValidSessionId(sid: string): void;
+export declare function assertValidChangeId(cid: string): void;

package/dist/src/services/workspace/sid-naming-guard.js

@@ -0,0 +1,31 @@
+/**
+ * SID naming guard. Enforces the "two-axis" convention from spec §0:
+ * session id: YYYY-MM-DD-session-<3-6 chars lowercase alnum>
+ * change id: kebab-case
+ *
+ * Spec §8.7 — bare forms (sid-3 / sid-h / sid-r / unknown-sid) are
+ * migrated to `_archive/invalid-sids/`, NOT tolerated.
+ */
+export const SID_FORMAT_DESCRIPTION = '<YYYY-MM-DD>-session-<3-6 chars lowercase alnum>, e.g. 2026-06-11-session-abc123';
+const VALID_SID_REGEX = /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-session-[0-9a-z]{3,6}$/;
+const BARE_SID_REGEX = /^(sid-[a-z0-9]+|unknown-sid)$/;
+const VALID_CHANGE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function isValidSessionId(sid) {
+    return VALID_SID_REGEX.test(sid);
+}
+export function isValidChangeId(cid) {
+    return VALID_CHANGE_ID_REGEX.test(cid);
+}
+export function isBareSid(name) {
+    return BARE_SID_REGEX.test(name);
+}
+export function assertValidSessionId(sid) {
+    if (!isValidSessionId(sid)) {
+        throw new Error(`NAMING_INVALID: session id "${sid}" does not match required format ${SID_FORMAT_DESCRIPTION}`);
+    }
+}
+export function assertValidChangeId(cid) {
+    if (!isValidChangeId(cid)) {
+        throw new Error(`NAMING_INVALID: change id "${cid}" must be kebab-case (lowercase alnum and dashes only)`);
+    }
+}

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

@@ -0,0 +1,19 @@
+export interface ArchivePlan {
+    sid: string;
+    sourcePath: string;
+    targetPath: string;
+    sourceExists: boolean;
+}
+export interface ArchiveOptions {
+    sid: string;
+    apply: boolean;
+}
+export interface ArchiveResult {
+    moved: string[];
+    skipped: {
+        sid: string;
+        reason: string;
+    }[];
+}
+export declare function planArchive(projectRoot: string, sid: string): ArchivePlan;
+export declare function archiveSession(projectRoot: string, options: ArchiveOptions): ArchiveResult;