peaks-cli 1.4.1 → 2.0.0

package/dist/src/cli/commands/core-artifact-commands.js

@@ -6,10 +6,12 @@ import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProje
 import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../services/standards/project-standards-service.js';
 import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../services/standards/ide-aware-standards-service.js';
 import { migrateStandards } from '../../services/standards/migrate-service.js';
+import { migrateClaudeRules } from '../../services/standards/migrate-claude-rules-service.js';
 import { listProfiles } from '../../services/profiles/profile-service.js';
 import { planProxyTest } from '../../services/proxy/proxy-service.js';
 import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
+import { runSkillSync, SYNC_PLATFORMS } from '../../services/skills/sync-service.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
 import { detectPresenceMarker } from '../../services/hooks/presence-marker-detector.js';
@@ -88,6 +90,42 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // Slice #12 final piece (per spec §9 line 1105):
+    // `peaks skills sync 8 平台分发`. Idempotent: re-running is a
+    // no-op when the symlinks are already correct.
+    addJsonOption(skill
+        .command('sync')
+        .description(`Sync the peaks-* skill family to one or all of the 8 supported LLM-CLI platforms (${SYNC_PLATFORMS.join(', ')}). Idempotent.`)
+        .option('--platform <id>', `sync only one platform (default: --all). Valid: ${SYNC_PLATFORMS.join(', ')}`)
+        .option('--all', 'sync all 8 platforms (default if --platform is omitted)')
+        .option('--dry-run', 'do not write; emit the same shape with applied=false')
+        .option('--project <path>', 'project root (default: cwd)')).action(async (options) => {
+        try {
+            const projectRoot = options.project ?? process.cwd();
+            const platforms = options.platform !== undefined ? [options.platform] : undefined;
+            const result = await runSkillSync({
+                projectRoot,
+                ...(platforms !== undefined ? { platforms } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+            });
+            const envelope = ok('skill.sync', result, [], [
+                `syncedCount: ${result.syncedCount}/${result.perPlatform.length} platforms`,
+                `totalInstalled: ${result.totalInstalled} skill symlinks`,
+                result.failedCount > 0
+                    ? `failedCount: ${result.failedCount} (run \`peaks skill status\` for details)`
+                    : 'no failures',
+            ]);
+            printResult(io, envelope, options.json);
+            if (result.failedCount > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('skill.sync', 'SKILL_SYNC_FAILED', message, { applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
     addJsonOption(skill
         .command('runbook <name>')
         .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
@@ -463,10 +501,30 @@ export function registerCoreAndArtifactCommands(program, io) {
     });
     addJsonOption(standards
         .command('migrate')
-        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write.')
+        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ (slice 2026-06-12-standards-migrate-claude-rules).')
         .option('--project <path>', 'target project root')
-        .option('--apply', 'rewrite the legacy block in place; default is dry-run')).action((options) => {
+        .option('--apply', 'rewrite the legacy block in place; default is dry-run')
+        .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/ (used by `peaks upgrade --to 2.0`)')).action((options) => {
         const projectRoot = options.project ?? process.cwd();
+        if (options.fromClaudeRules === true) {
+            try {
+                const result = migrateClaudeRules({ projectRoot, apply: options.apply === true });
+                printResult(io, ok('standards.migrate', result.data, [], [...result.data.nextActions]), options.json);
+            }
+            catch (error) {
+                printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), {
+                    backupPath: null,
+                    thinnedFiles: [],
+                    scaffoldedFiles: [],
+                    preservedFiles: [],
+                    wouldChange: false,
+                    applied: false,
+                    nextActions: [],
+                }, [getErrorMessage(error)]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
         try {
             const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
             printResult(io, ok('standards.migrate', result.data, [], result.data.nextActions), options.json);
@@ -519,6 +577,27 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(memory
+        .command('search <query>')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        // Lazy import avoids a top-of-file import cycle (memory-commands.ts
+        // imports services that the rest of this file may also touch).
+        void import('./memory-commands.js').then(({ runMemorySearch }) => {
+            runMemorySearch(io, {
+                query,
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.search', 'MEMORY_SEARCH_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
     const proxy = program.command('proxy').description('Manage proxy settings');
     addJsonOption(proxy
         .command('test')

package/dist/src/cli/commands/hook-handle.js

@@ -2,6 +2,10 @@ import { addJsonOption, printResult } from '../cli-helpers.js';
 import { detectIdeFromContext, parseAdapterStdin, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
 import { buildCanonicalHook, formatDecisionResponse } from '../../services/ide/hook-protocol.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
+import { evaluateSoloCodeBan } from '../../services/audit/enforcers/solo-code-ban.js';
+import { isRootWrite } from '../../services/audit/enforcers/no-root-pollution.js';
+import { checkLoginGate } from '../../services/audit/enforcers/login-gate.js';
+import { resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
 import { fail, ok } from '../../shared/result.js';
 /**
  * Read the hook payload. `PEAKS_HOOK_STDIN` is a test seam (same convention as
@@ -77,6 +81,21 @@ export function registerHookHandleCommand(program, io) {
             // Dispatch by toolName. For slice #1+, we only handle Bash. Task tool sub-agent dispatch goes through `peaks sub-agent dispatch` (slice #009) and does not need a hook entry.
             // Other tools: allow (no-op; future events will be added here).
             if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
+                // L2.1 P0 #1: solo-code-ban. Deny `git commit` / `git apply` from peaks-* skills
+                // BEFORE the SOP gate runs. The active skill is read from the per-caller
+                // active-skill file (see active-skill-resolver.ts).
+                const activeSkill = resolveActiveSkillForCaller(projectRoot);
+                if (activeSkill.skill !== null) {
+                    const soloDecision = evaluateSoloCodeBan({ skill: activeSkill.skill, command: fallbackCommand });
+                    if (soloDecision.denied) {
+                        const formatted = formatDecisionResponse(ide, 'deny', soloDecision.reason);
+                        io.stdout(formatted.stdout);
+                        if (options.json === true) {
+                            io.stderr(JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: soloDecision.reason, enforcer: 'solo-code-ban' })));
+                        }
+                        return;
+                    }
+                }
                 // Lazy import to avoid circular: peaks gate enforce logic
                 const { enforceBashCommand } = await import('../../services/sop/gate-enforce-service.js');
                 const decision = await enforceBashCommand(projectRoot, fallbackCommand);
@@ -89,6 +108,37 @@ export function registerHookHandleCommand(program, io) {
                     return;
                 }
             }
+            // L2.2 P1 #1: login-gate. After solo-code-ban + gate-enforce pass,
+            // flag destructive patterns (uninstall, force-push, --force, --hard,
+            // rm -rf) so the LLM gets a soft warning (still allow). The user
+            // gets the warning via the warn channel; the command proceeds.
+            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string') {
+                const gate = checkLoginGate({ command: fallbackCommand });
+                if (gate.destructive) {
+                    io.stderr(`warning: login-gate: destructive command detected (pattern: ${gate.matchedPattern}). Confirm with the user before proceeding.`);
+                }
+            }
+            // L2.1 P0 #2: no-root-pollution. Deny Write/Edit to files outside the
+            // root allowlist. file_path is read from toolInput.file_path (Claude
+            // and most IDEs use the same shape). When the field is missing or the
+            // path is not at depth 1, the enforcer allows (no-op).
+            if (hook.toolName === 'Write' || hook.toolName === 'Edit' || hook.toolName === 'MultiEdit' || hook.toolName === 'Create') {
+                const filePath = pluckString(parsed, ['tool_input', 'file_path'])
+                    ?? pluckString(parsed, ['toolInput', 'file_path'])
+                    ?? pluckString(parsed, ['tool_input', 'path'])
+                    ?? pluckString(parsed, ['toolInput', 'path']);
+                if (typeof filePath === 'string' && filePath.trim().length > 0) {
+                    const rootCheck = isRootWrite({ projectRoot, filePath });
+                    if (!rootCheck.allowed) {
+                        const formatted = formatDecisionResponse(ide, 'deny', rootCheck.denyReason);
+                        io.stdout(formatted.stdout);
+                        if (options.json === true) {
+                            io.stderr(JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: rootCheck.denyReason, enforcer: 'no-root-pollution' })));
+                        }
+                        return;
+                    }
+                }
+            }
             const allow = formatDecisionResponse(ide, 'allow');
             io.stdout(allow.stdout);
             if (options.json === true) {

package/dist/src/cli/commands/loop-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Slice #14, ships 5 sub-features:
+ *
+ *   14.1 peaks loop distill          — extract patterns from past sessions
+ *                                       (delegates to peaks memory extract)
+ *   14.2 peaks loop preflight        — pre-run sanity checks (placeholder)
+ *   14.3 peaks loop detect-pattern   — find repeating patterns (placeholder)
+ *   14.4 peaks loop check-consistency — verify state consistency (placeholder)
+ *   14.5 peaks goal compose          — autonomous goal composition (placeholder;
+ *                                       requires IDE adapter goalCommand capability
+ *                                       per Slice #0.7)
+ *
+ * The 4 placeholders emit a clear nextActions list; the LLM-side UX
+ * layer composes the actual runtime today.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,128 @@
+/**
+ * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Slice #14, ships 5 sub-features:
+ *
+ *   14.1 peaks loop distill          — extract patterns from past sessions
+ *                                       (delegates to peaks memory extract)
+ *   14.2 peaks loop preflight        — pre-run sanity checks (placeholder)
+ *   14.3 peaks loop detect-pattern   — find repeating patterns (placeholder)
+ *   14.4 peaks loop check-consistency — verify state consistency (placeholder)
+ *   14.5 peaks goal compose          — autonomous goal composition (placeholder;
+ *                                       requires IDE adapter goalCommand capability
+ *                                       per Slice #0.7)
+ *
+ * The 4 placeholders emit a clear nextActions list; the LLM-side UX
+ * layer composes the actual runtime today.
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerLoopCommands(program, io) {
+    // 14.5 peaks goal compose — registered as a TOP-LEVEL command (not under
+    // `peaks loop`) because IDE adapters expose it as `goalCommand`.
+    // The sub-agent dispatch path consumes it; the slice 0.7 hermes +
+    // openclaw adapters will thread it through.
+    addJsonOption(program
+        .command('goal')
+        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--goal <text>', 'the high-level goal to compose')).action(async (options) => {
+        try {
+            printResult(io, ok('goal.compose', {
+                project: options.project,
+                goal: options.goal,
+                status: 'placeholder',
+                nextSteps: [
+                    'The composed goal is consumed by peaks sub-agent dispatch.',
+                    'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.',
+                ],
+            }, [], [
+                'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop *
+    const loop = program.command('loop').description('Slice #14: L4 Agent Loop sub-features (distill / preflight / detect-pattern / check-consistency)');
+    // 14.1 distill
+    addJsonOption(loop.command('distill')
+        .description('14.1: distill patterns from past sessions into .peaks/memory/ (delegates to peaks memory extract)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write extracted memories to .peaks/memory/ (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const apply = options.apply === true;
+            // Delegate to the existing peaks memory extract CLI via dynamic
+            // import (avoids circular); the LLM-side UX layer composes the
+            // two commands.
+            const { execFileSync } = await import('node:child_process');
+            const args = ['memory', 'extract', '--project', options.project];
+            if (apply)
+                args.push('--apply');
+            const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
+                cwd: options.project,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).toString('utf-8');
+            printResult(io, ok('loop.distill', {
+                project: options.project,
+                apply,
+                delegateStdout: stdout.slice(0, 200),
+            }, [], [
+                apply ? 'peaks memory extract --apply was invoked' : 'peaks memory extract dry-run was invoked',
+                'A future slice will inline the memory extract (not via execFileSync).',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('loop.distill', 'LOOP_DISTILL_FAILED', getErrorMessage(error), { project: options.project }, ['Verify the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // 14.2 preflight
+    addJsonOption(loop.command('preflight')
+        .description('14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.preflight', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
+                'A future slice will inline the preflight checks (not just placeholder).',
+            ],
+        }, [], [
+            'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.',
+        ]), options.json);
+    });
+    // 14.3 detect-pattern
+    addJsonOption(loop.command('detect-pattern')
+        .description('14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.detect-pattern', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
+                'A future slice will rank by frequency + LLM confidence.',
+            ],
+        }, [], [
+            'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.',
+        ]), options.json);
+    });
+    // 14.4 check-consistency
+    addJsonOption(loop.command('check-consistency')
+        .description('14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.check-consistency', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
+                'A future slice will report drift with severity (warn / fail).',
+            ],
+        }, [], [
+            'loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.',
+        ]), options.json);
+    });
+}

package/dist/src/cli/commands/memory-commands.d.ts

@@ -0,0 +1,13 @@
+import { type ProgramIO } from '../cli-helpers.js';
+export interface MemorySearchCommandOptions {
+    query: string;
+    kind?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export declare function runMemorySearch(io: ProgramIO, options: MemorySearchCommandOptions): void;

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

@@ -0,0 +1,60 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_KINDS = [
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson',
+];
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export function runMemorySearch(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
+        ? options.kind
+        : undefined;
+    // When the user passes --kind but the value isn't in the valid set,
+    // we silently pass `undefined` so the search returns the full set;
+    // that's friendlier than a hard error and matches the spec's
+    // "invalid kind -> empty matches" semantic for the filter path.
+    // (For the loader unit test we exercise the explicit-invalid path
+    // directly; here the CLI side is forgiving.)
+    try {
+        const matches = searchMemory({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: [],
+        }, []), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_SEARCH_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks memory extract --apply` to build the index from memory/*.md files');
+        }
+        if (code === 'EMPTY_QUERY') {
+            suggestions.push('Use `peaks memory index` to list all entries');
+        }
+        printResult(io, fail('memory.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}

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

@@ -5,6 +5,8 @@ import { renderOpenSpecChange } from '../../services/openspec/openspec-render-se
 import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
 import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
 import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
+import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
+import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
@@ -197,4 +199,39 @@ export function registerOpenSpecCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(openspec
+        .command('from-doctor')
+        .description('Slice L3.3: generate an OpenSpec change draft (proposal.md) from a peaks doctor finding')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--check-id <id>', 'the doctor check id to draft from (e.g. L3:l3-memory-health)')).action(async (options) => {
+        try {
+            const report = await runDoctor();
+            const finding = report.checks.find((c) => c.id === options.checkId);
+            if (finding === undefined) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_NOT_FOUND', `No doctor check with id "${options.checkId}"`, { availableIds: report.checks.map((c) => c.id) }, ['Run peaks doctor --json to list available check ids']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (finding.ok) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_ALREADY_PASSING', `Doctor check "${options.checkId}" is already passing; nothing to draft`, { checkId: options.checkId }, ['Pick a failing check from peaks doctor --json']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const doctorFinding = {
+                id: finding.id,
+                rule: finding.rule ?? finding.id,
+                detail: finding.message,
+                severity: 'fail',
+            };
+            const result = proposeFromDoctor({ projectRoot: options.project, finding: doctorFinding });
+            printResult(io, ok('openspec.from-doctor', result, [], [
+                `draft proposal written to ${result.proposalPath}`,
+                'Review + edit the draft, then run `peaks openspec validate <id>`',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.from-doctor', 'OPENSPEC_FROM_DOCTOR_FAILED', getErrorMessage(error), { projectRoot: options.project, checkId: options.checkId }, ['Verify the project path and the check id']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/src/cli/commands/preferences-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerPreferencesCommands(program: Command): void;

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

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadPreferences, preferencesPath, savePreferences, } from '../../services/preferences/preferences-service.js';
+const ALLOWED_KEYS = new Set([
+    'economyMode',
+    'swarmMode',
+    'uaPrompt',
+    'agentShieldPrompt',
+    'classifyConservatism',
+    'classifyRules',
+    'headroom',
+    'swarmSpeculative',
+    'loopAutonomousEnabled',
+]);
+export function registerPreferencesCommands(program) {
+    const prefs = program
+        .command('preferences')
+        .description('Manage project-local preferences (`.peaks/preferences.json`)');
+    prefs
+        .command('get')
+        .description('Get a preference value (from override or default)')
+        .requiredOption('--key <key>', 'preference key')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            const all = loadPreferences(opts.project);
+            const value = all[opts.key];
+            const filePath = preferencesPath(opts.project);
+            // Spec bug fix: use the top-level existsSync import (the spec's
+            // `await import('node:fs')` would not compile inside a non-async action).
+            // Source is 'override' only when the key is explicitly present in
+            // the on-disk file (not merely when the file exists, since reset()
+            // may leave the file with other keys still overridden).
+            let source = 'default';
+            if (existsSync(filePath)) {
+                try {
+                    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+                    if (Object.prototype.hasOwnProperty.call(raw, opts.key)) {
+                        source = 'override';
+                    }
+                }
+                catch {
+                    // Corrupt file: report the merged value but fall back to 'default'
+                    // source to avoid claiming an override that cannot be parsed.
+                    source = 'default';
+                }
+            }
+            // Stable ordering: source is computed, value reflects merged state.
+            const envelope = {
+                ok: true,
+                data: { key: opts.key, value, source },
+            };
+            process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+    prefs
+        .command('set')
+        .description('Override a preference value (writes to .peaks/preferences.json)')
+        .requiredOption('--key <key>', 'preference key')
+        .requiredOption('--value <value>', 'value (parsed as JSON, or string if not JSON)')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            let parsed = opts.value;
+            try {
+                parsed = JSON.parse(opts.value);
+            }
+            catch {
+                // Not valid JSON — keep the raw string.
+            }
+            const merged = savePreferences(opts.project, {
+                [opts.key]: parsed,
+            });
+            const envelope = {
+                ok: true,
+                data: {
+                    key: opts.key,
+                    value: merged[opts.key],
+                },
+            };
+            process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+    prefs
+        .command('reset')
+        .description('Remove the override for a key (falls back to default)')
+        .requiredOption('--key <key>', 'preference key')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            const filePath = preferencesPath(opts.project);
+            // Read raw on-disk state (not the merged view) so removing a key
+            // truly removes the override, instead of savePreferences re-inserting
+            // the default value. If no file exists, there is nothing to reset.
+            if (!existsSync(filePath)) {
+                const envelope = {
+                    ok: true,
+                    data: { key: opts.key, removed: false, reason: 'no-override-file' },
+                };
+                process.stdout.write(JSON.stringify(envelope) + '\n');
+                return;
+            }
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(filePath, 'utf8'));
+            }
+            catch (err) {
+                throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+            }
+            const hadKey = Object.prototype.hasOwnProperty.call(raw, opts.key);
+            if (hadKey) {
+                delete raw[opts.key];
+                mkdirSync(dirname(filePath), { recursive: true });
+                writeFileSync(filePath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+            }
+            const envelope = {
+                ok: true,
+                data: { key: opts.key, removed: hadKey },
+            };
+            process.stdout.write(JSON.stringify(envelope) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+}

package/dist/src/cli/commands/retrospective-commands.d.ts

@@ -1,3 +1,12 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+export interface RetrospectiveSearchCommandOptions {
+    query: string;
+    type?: string;
+    outcome?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+export declare function runRetrospectiveSearch(io: ProgramIO, options: RetrospectiveSearchCommandOptions): void;
 export declare function registerRetrospectiveCommands(program: Command, io: ProgramIO): void;