peaks-loop 3.0.0

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

@@ -0,0 +1,156 @@
+import { existsSync } from 'node:fs';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+function resolveProjectRoot(scope, project) {
+    return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
+}
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks hooks
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+/**
+ * Slice #014: compute the per-IDE peaks hook entries for the install /
+ * dry-run RESPONSE SUMMARY. This is the *desired* shape (what the install
+ * WOULD write), not what is on disk. The status command uses a different
+ * helper (`readInstalledEntriesFromSettings`) that reads the actual
+ * settings.json.
+ *
+ * After slice #014 only the gate-enforce entry is ever installed
+ * (the legacy progress-start surface is gone). The summary mirrors
+ * the install shape so the JSON envelope doesn't claim a hook the
+ * service did not write.
+ */
+function listExpectedEntriesForIde(ide, _skipProgress = false) {
+    const adapter = getAdapter(ide);
+    if (ide === 'trae') {
+        return [{ matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' }];
+    }
+    return [{ matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' }];
+}
+export function registerHooksCommands(program, io) {
+    const hooks = program
+        .command('hooks')
+        .description("Manage the Peaks-managed hook entry in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae). Slice #014: the only installed entry is the gate-enforce hook (SOP gate). The legacy progress-start hook (auto-spawn sub-agent progress terminal) is no longer installed — sub-agent progress is now surfaced via the dispatch + heartbeat flow (`peaks sub-agent dispatch` / `peaks sub-agent heartbeat`). The IDE is auto-detected from env / cwd; override with --ide <id>.");
+    addJsonOption(hooks
+        .command('install')
+        .description(`Install the peaks-managed gate-enforce hook entry into the adapter's settings.json. Slice #014: only the gate-enforce entry is installed; the legacy progress-start entry is no longer installed. Idempotent: re-runs are no-ops. Project scope by default.`)
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', "target adapter id (claude-code | trae); default: auto-detect from env/cwd")
+        .option('--dry-run', 'show what would change without writing')
+        .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        const skipProgress = options.progress === false;
+        try {
+            if (options.dryRun === true) {
+                const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
+                const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
+                printResult(io, ok('hooks.install', {
+                    ...plan,
+                    ide,
+                    applied: false,
+                    dryRun: true,
+                    skipProgress,
+                    entries: dryRunEntries
+                }, [], [`would install ${dryRunEntries.length} peaks-managed hook entries`]), options.json);
+                return;
+            }
+            const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
+            // Slice #3: build the per-IDE entries summary from the actual installed
+            // entries, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+            // claude-code default). The user's JSON envelope must reflect the IDE
+            // they targeted. Slice #014: the install only emits the gate-enforce
+            // entry; the summary mirrors the install shape, NOT a hardcoded
+            // expected list.
+            const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
+            const nextActions = result.applied
+                ? [
+                    'Restart the IDE (or reload the workspace) so the hook entries take effect',
+                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
+                ]
+                : [];
+            printResult(io, ok('hooks.install', {
+                ...result,
+                ide,
+                dryRun: false,
+                skipProgress,
+                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+            }, [], nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false, skipProgress }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('uninstall')
+        .description("Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.")
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const result = removeHookInstall(scope, projectRoot, { ide });
+            printResult(io, ok('hooks.uninstall', { ...result, ide }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('status')
+        .description('Report which peaks-managed hook entries are installed.')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const status = readHookStatus(scope, projectRoot, { ide });
+            // Slice #014: read the ACTUAL on-disk entries (post-install shape),
+            // not the IDE-EXPECTED list. Pre-#014 `listInstalledEntriesForIde`
+            // returned the expected list and reported `entries: [Bash, Task]`
+            // even when the file only had `Bash`. The new helper reads the
+            // file and reports whatever peaks-managed entries are present,
+            // including any legacy progress-start entry that a pre-#014
+            // install left behind.
+            const settingsPath = status.settingsPath;
+            const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+            printResult(io, ok('hooks.status', {
+                ...status,
+                ide,
+                entries: readInstalledEntriesFromSettings(settings, ide)
+            }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,15 @@
+/**
+ * v2.15.0 follow-up — G13: impact scan CLI.
+ *
+ *   - `peaks impact scan`        — full impact report (changed files +
+ *                                  affected flows + must-check list)
+ *   - `peaks impact must-check`  — return just the must-check list
+ *                                  (for piping into smoke / release)
+ *
+ * Lightweight glob-based implementation (no AST, no type checking).
+ * Suitable for the "we don't have UT, give me a quick risk list"
+ * use case from the 12 Gaps memory.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerImpactCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,62 @@
+/**
+ * v2.15.0 follow-up — G13: impact scan CLI.
+ *
+ *   - `peaks impact scan`        — full impact report (changed files +
+ *                                  affected flows + must-check list)
+ *   - `peaks impact must-check`  — return just the must-check list
+ *                                  (for piping into smoke / release)
+ *
+ * Lightweight glob-based implementation (no AST, no type checking).
+ * Suitable for the "we don't have UT, give me a quick risk list"
+ * use case from the 12 Gaps memory.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { mustCheckFromReport, runImpactScan } from '../../services/impact/impact-scan-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerImpactCommands(program, io) {
+    const impact = program
+        .command('impact')
+        .description('v2.15.0 follow-up G13: lightweight impact scan (no AST, glob-based) for存量老项目无 UT 兜底.');
+    addJsonOption(impact
+        .command('scan')
+        .description('Scan the given changed files for impact: impacted files (siblings of changed), ' +
+        'affected business flows (configurable), and the must-check list (concrete ' +
+        'scenarios the user must verify before shipping). Pure local computation, no I/O.')
+        .requiredOption('--files <list>', 'comma-separated list of changed file paths (relative to project root)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('impact.scan', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = runImpactScan({ changedFiles: files });
+        printResult(io, ok('impact.scan', { projectRoot, report }, [], [...report.warnings]), opts.json ?? false);
+    });
+    addJsonOption(impact
+        .command('must-check')
+        .description('Return just the must-check list for a set of changed files. ' +
+        'Useful for piping into smoke / release verification flows. ' +
+        'Accepts the same --files flag as `peaks impact scan`.')
+        .requiredOption('--files <list>', 'comma-separated list of changed file paths')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('impact.must-check', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = runImpactScan({ changedFiles: files });
+        const items = mustCheckFromReport(report);
+        printResult(io, ok('impact.must-check', { projectRoot, count: items.length, items }, [], [
+            items.length === 0
+                ? 'No must-check items generated for the given changes.'
+                : 'Pipe into `peaks smoke add-path` to register these as regression paths.'
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-cli is applied
+ *     to a 存量老项目.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLegacyCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,32 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-cli is applied
+ *     to a 存量老项目.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { detectLegacy } from '../../services/legacy/legacy-detector.js';
+import { ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerLegacyCommands(program, io) {
+    addJsonOption(program
+        .command('legacy-detect')
+        .description('v2.15.0 follow-up G8: scan a directory for legacy smells (TODO/FIXME/HACK, ' +
+        'console.log, any-type, large files, ts-ignore). Returns a smell grade ' +
+        '(low / medium / high) and per-kind counts. Lightweight heuristics — ' +
+        'NOT a replacement for a real linter. Useful as a "where to start" ' +
+        'inventory when peaks-cli is applied to a legacy codebase.')
+        .option('--dir <path>', 'directory to scan (default: src)', 'src')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const report = detectLegacy(projectRoot, opts.dir);
+        printResult(io, ok('legacy-detect', { projectRoot, dir: opts.dir, report }, [], [
+            `Scanned ${report.scannedFiles} file(s). Smells: ${report.smells}.`,
+            report.smells === 'high'
+                ? 'Consider refactoring high-smell areas first.'
+                : 'Manageable technical debt.'
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLogCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,64 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { tailLog, listLogFiles } from '../../services/log/log-commands-service.js';
+import { getErrorMessage, printResult, addJsonOption } from '../cli-helpers.js';
+import { ok, fail } from '../../shared/result.js';
+export function registerLogCommands(program, io) {
+    const log = program
+        .command('log')
+        .description('Inspect the peaks-cli JSONL log directory (default: ~/.peaks/logs/)');
+    addJsonOption(log
+        .command('tail')
+        .description('Print the last 50 lines of today\'s peaks-cli log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.')
+        .option('--lines <n>', 'number of lines to show (default 50)', (value) => Number(value))
+        .option('--date <YYYY-MM-DD>', 'read the log for this UTC date instead of today (PRD AC2: PEAKS_LOG_DATE_OVERRIDE)')
+        // Slice 2026-06-23-audit-4th #B2: --batch filter for cross-run
+        // correlation. Without this, a user post-hoc cannot group the
+        // log lines for one batch (they interleave in the JSONL file).
+        .option('--batch <id>', 'filter entries by batchId (sub-agent dispatch / heartbeat / share)')).action((options) => {
+        try {
+            const requestedLines = options.lines ?? 50;
+            const safeLines = Number.isFinite(requestedLines) && requestedLines > 0 ? Math.floor(requestedLines) : 50;
+            const result = tailLog({
+                lines: safeLines,
+                ...(options.date !== undefined ? { dateOverride: options.date } : {}),
+                ...(options.batch !== undefined ? { batchId: options.batch } : {})
+            });
+            printResult(io, ok('log.tail', {
+                file: result.file,
+                total: result.total,
+                lines: safeLines,
+                ...(options.batch !== undefined ? { batch: options.batch, batchMatches: result.batchMatches ?? 0 } : {}),
+                entries: result.entries
+            }, []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('log.tail', 'LOG_TAIL_FAILED', getErrorMessage(error), {}, ['Check `peaks log ls` to see available log files']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(log
+        .command('ls')
+        .description('List peaks-loop-*.log files in ~/.peaks/logs/ (newest first).')).action((options) => {
+        const files = listLogFiles();
+        printResult(io, ok('log.ls', {
+            logDir: join(homedir(), '.peaks', 'logs'),
+            total: files.length,
+            files
+        }, []), options.json);
+    });
+}

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/loop-eval-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * peaks-workflow v3.0.0 — Slice A.3 + Slice B.2
+ *
+ * CLI surface for the workflow primitive + the loop evaluator dispatcher.
+ *
+ * New commands (added under the existing `peaks workflow` group and the
+ * existing `peaks loop` group — never as new top-level commands, per the
+ * peaks-cli add-a-new-subcommand-check-for-existing-top-level-first rule):
+ *
+ *   peaks workflow run <id> --session <sid> --project <repo> --json
+ *   peaks workflow plan <id> --session <sid> --json   (dry-run)
+ *   peaks workflow lint <id> --session <sid> --json
+ *   peaks loop eval <rid> --evaluator <name> [--project <repo>] [--json]
+ *
+ * Karpathy §2: separate file from workflow-commands.ts to stay under
+ * the 800-line budget.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowEvalCommands(program: Command, io: ProgramIO): void;