peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

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

@@ -0,0 +1,526 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveWorkflow, planWorkflow, planWorkflowRun } from '../../services/workflow/workflow-loader.js';
+import { dispatchEvaluator } from '../../services/loop/evaluator-dispatcher.js';
+import { DEFAULT_MONOTONIC_THRESHOLD } from '../../services/loop/monotonic-guard.js';
+import { runMonotonicCheck, resolveMonotonicContext } from '../../services/loop/monotonic-runner.js';
+import { resolveLoopSpec, persistSpec, buildSpec, lintLoopSpec, lintSpecFile, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from '../../services/loop/spec-service.js';
+import { runLoop, resolveRunContext } from '../../services/loop/run-driver.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const VALID_EVALUATORS = new Set([
+    'karpathy',
+    'code-review',
+    'security-review',
+    'perf-baseline',
+    'verdict-aggregate',
+    'monotonic-improvement',
+    'impact-scan',
+    'smoke-run',
+    'canary-watch'
+]);
+export function registerWorkflowEvalCommands(program, io) {
+    // Reuse the existing `workflow` and `loop` parents created by
+    // `registerWorkflowCommands` / `registerLoopCommands` (program-level
+    // command conflicts would otherwise throw per Commander's
+    // add-a-new-subcommand-check-for-existing-top-level-first rule).
+    const existingWorkflow = program.commands.find((c) => c.name() === 'workflow');
+    const existingLoop = program.commands.find((c) => c.name() === 'loop');
+    const workflow = existingWorkflow ?? program.command('workflow').description('Workflow primitive (run / plan / lint)');
+    const loop = existingLoop ?? program.command('loop').description('Loop primitive (eval)');
+    // peaks workflow run <id>
+    addJsonOption(workflow
+        .command('run')
+        .description('Slice A.3: replay a captured workflow (.peaks/workflows/<id>.yaml) deterministically. Returns the run-plan order + per-phase status without re-deriving the phase plan.')
+        .argument('<id>', 'workflow id (matches .peaks/workflows/<id>.yaml)')
+        .requiredOption('--session <sid>', 'session id (from peaks workspace init)')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const resolved = resolveWorkflow(projectRoot, id);
+            if (resolved.source.kind === 'missing') {
+                printResult(io, fail('workflow.run', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!resolved.lint.ok) {
+                printResult(io, fail('workflow.run', 'WORKFLOW_LINT_FAILED', `workflow "${id}" has ${resolved.lint.errors.length} lint error(s): ${resolved.lint.errors.join('; ')}`, resolved.lint, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const runPlan = planWorkflowRun(resolved.spec);
+            printResult(io, ok('workflow.run', {
+                sessionId: options.session,
+                workflow: { id: resolved.spec.id, label: resolved.spec.label, source: resolved.source },
+                runPlan,
+                lintWarnings: resolved.lint.warnings
+            }, [], [`Run \`peaks workflow plan ${id} --session ${options.session} --json\` to preview the graph.`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('workflow.run', 'WORKFLOW_RUN_FAILED', getErrorMessage(error), { sessionId: options.session }, ['Verify the workflow id and session binding.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks workflow graph <id>  (dry-run graph render)
+    // Renamed from `plan` to `graph` to avoid collision with the existing
+    // `peaks workflow plan <read|refresh|detect-trigger>` family registered
+    // by workflow-plan-commands.ts (slice 025).
+    addJsonOption(workflow
+        .command('graph')
+        .description('Slice A.3 dry-run: render the workflow graph (phases + parallel groups + evaluators + budget). No phase is executed.')
+        .argument('<id>', 'workflow id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const resolved = resolveWorkflow(projectRoot, id);
+            if (resolved.source.kind === 'missing') {
+                printResult(io, fail('workflow.graph', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`Create .peaks/workflows/${id}.yaml or use the bundled default-fullauto-md.`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!resolved.lint.ok) {
+                printResult(io, fail('workflow.graph', 'WORKFLOW_LINT_FAILED', `workflow "${id}" has ${resolved.lint.errors.length} lint error(s): ${resolved.lint.errors.join('; ')}`, resolved.lint, [`peaks workflow lint ${id} --session ${options.session} --json`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const graph = planWorkflow(resolved.spec, resolved.source);
+            printResult(io, ok('workflow.graph', {
+                sessionId: options.session,
+                graph,
+                lintWarnings: resolved.lint.warnings
+            }, [], [`Run \`peaks workflow run ${id} --session ${options.session} --json\` to materialize the run-plan order.`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('workflow.graph', 'WORKFLOW_GRAPH_FAILED', getErrorMessage(error), { sessionId: options.session }, ['Verify the workflow id and session binding.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks workflow lint <id>
+    addJsonOption(workflow
+        .command('lint')
+        .description('Slice A.3: validate a workflow spec (phases / gates / evaluators / parallel groups / budget).')
+        .argument('<id>', 'workflow id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')).action((id, options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const resolved = resolveWorkflow(projectRoot, id);
+            if (resolved.source.kind === 'missing') {
+                printResult(io, fail('workflow.lint', 'WORKFLOW_NOT_FOUND', `workflow "${id}" not found`, { sessionId: options.session }, [`Create .peaks/workflows/${id}.yaml`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('workflow.lint', {
+                sessionId: options.session,
+                source: resolved.source,
+                lint: resolved.lint
+            }, [], []), options.json);
+            if (!resolved.lint.ok)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('workflow.lint', 'WORKFLOW_LINT_FAILED', getErrorMessage(error), { sessionId: options.session }, ['Verify the workflow file syntax.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop eval <rid> --evaluator <name>
+    addJsonOption(loop
+        .command('eval')
+        .description('Slice B.2: invoke a native evaluator directly. The runtime calls the evaluator (no LLM scheduling) and returns a verdict envelope compatible with peaks verdict aggregate. Pass --capture-score to also persist the score row to .peaks/_runtime/<sid>/loop/<rid>/cycles/cycle-N.json (P0 closure: this is the score the run-driver reads back).')
+        .argument('<rid>', 'request id (e.g. 2026-06-30-...)')
+        .requiredOption('--evaluator <name>', `evaluator: ${[...VALID_EVALUATORS].join(', ')}`)
+        .option('--session <sid>', 'session id (required by --evaluator monotonic-improvement; also required by --capture-score)')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--scope <scope>', 'optional scope expression (forwarded to the evaluator)')
+        .option('--threshold <threshold>', 'optional SLA threshold (evaluator-specific)')
+        .option('--capture-score', 'persist the verdict score to .peaks/_runtime/<sid>/loop/<rid>/cycles/cycle-N.json (requires --session); adds data.score', false)).action((rid, options) => {
+        try {
+            if (!VALID_EVALUATORS.has(options.evaluator)) {
+                printResult(io, fail('loop.eval', 'UNKNOWN_EVALUATOR', `evaluator "${options.evaluator}" is not a native evaluator (allowed: ${[...VALID_EVALUATORS].join(', ')})`, { rid }, [`Use one of: ${[...VALID_EVALUATORS].join(', ')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const envelope = dispatchEvaluator(options.evaluator, {
+                projectRoot,
+                rid,
+                ...(options.session !== undefined ? { sessionId: options.session } : {}),
+                ...(options.scope !== undefined ? { scope: options.scope } : {}),
+                ...(options.threshold !== undefined ? { threshold: options.threshold } : {})
+            });
+            const verdict = envelope.gateAction;
+            const exitCode = envelope.gateAction === 'block' ? 1 : 0;
+            // --capture-score path: persist a single-row cycle-N.json to
+            // the run-driver's cycles dir. Mirrors the scoring convention
+            // of monotonic-guard (pass=1.0, warn=0.5, block=0.0; degraded=0.25).
+            let capture = null;
+            if (options.captureScore === true) {
+                if (options.session === undefined || options.session.length === 0) {
+                    printResult(io, fail('loop.eval', 'CAPTURE_SCORE_NEEDS_SESSION', '--capture-score requires --session <sid>', { rid }, ['Pass --session <sid> alongside --capture-score.']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                const score = envelope.degraded ? 0.25 : (envelope.gateAction === 'pass' ? 1.0 : envelope.gateAction === 'warn' ? 0.5 : 0.0);
+                const dir = join(projectRoot, '.peaks', '_runtime', options.session, 'loop', rid, 'cycles');
+                const n = nextEvalCaptureIndex(projectRoot, options.session, rid);
+                const path = join(dir, `cycle-${n}.json`);
+                try {
+                    mkdirSync(dir, { recursive: true });
+                    writeFileSync(path, JSON.stringify({
+                        cycle: n,
+                        rid,
+                        sid: options.session,
+                        persistedAt: new Date().toISOString(),
+                        scores: [{
+                                evaluator: envelope.kind,
+                                score,
+                                gateAction: envelope.gateAction,
+                                degraded: envelope.degraded,
+                                observedAt: new Date().toISOString()
+                            }]
+                    }), 'utf8');
+                    capture = { score, persistedAt: path };
+                }
+                catch {
+                    capture = { score, persistedAt: null };
+                }
+            }
+            printResult(io, ok('loop.eval', {
+                rid,
+                evaluator: envelope.kind,
+                verdict,
+                passed: envelope.passed,
+                violations: envelope.violations,
+                summary: envelope.summary,
+                wallSeconds: envelope.wallSeconds,
+                degraded: envelope.degraded,
+                ...(capture !== null ? { score: capture.score, capture } : {})
+            }, [], envelope.degraded
+                ? ['Evaluator ran in degraded mode (peaks CLI unavailable). Verify the verdict by running `peaks verdict aggregate --from-rid ' + rid + '`.',
+                    'Re-run on a fully-installed peaks-loop environment for a real verdict.']
+                : [`Verifier verdict-aggregate can consume this envelope via \`peaks verdict aggregate --from-rid ${rid}\`.`]), options.json);
+            process.exitCode = exitCode;
+        }
+        catch (error) {
+            printResult(io, fail('loop.eval', 'LOOP_EVAL_FAILED', getErrorMessage(error), { rid, evaluator: options.evaluator }, ['Verify the rid and evaluator name.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop check-monotonic <rid>
+    // Slice C: compare adjacent cycles' per-evaluator scores; reject
+    // score regression > threshold with `MONOTONICITY_VIOLATION`.
+    addJsonOption(loop
+        .command('check-monotonic')
+        .description('Slice C.2: compare adjacent cycles of evaluator scores for a rid. Reject (exit 1) when an evaluator score regresses beyond the configured threshold.')
+        .argument('<rid>', 'request id (e.g. 2026-06-30-...)')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--threshold <threshold>', `maximum allowed score regression on the 0..1 scale (default: ${DEFAULT_MONOTONIC_THRESHOLD} = 5%)`)
+        .option('--no-persist', 'skip persisting the current cycle score rows to disk')).action((rid, options) => {
+        try {
+            const { projectRoot, sid } = resolveMonotonicContext({ ...(options.project !== undefined ? { project: options.project } : {}), session: options.session, rid });
+            const persist = options.persist !== false;
+            const thresholdNum = options.threshold !== undefined ? Number(options.threshold) : DEFAULT_MONOTONIC_THRESHOLD;
+            if (options.threshold !== undefined && (!Number.isFinite(thresholdNum) || thresholdNum < 0 || thresholdNum > 1)) {
+                printResult(io, fail('loop.check-monotonic', 'INVALID_THRESHOLD', `threshold must be a finite number in [0,1] (got "${options.threshold}")`, { rid }, [`Pass --threshold ${DEFAULT_MONOTONIC_THRESHOLD} (default) or any number in [0,1].`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = runMonotonicCheck({
+                projectRoot,
+                sid,
+                rid,
+                threshold: thresholdNum,
+                persist
+            });
+            const exitCode = result.report.monotonicityViolation ? 1 : 0;
+            printResult(io, ok('loop.check-monotonic', {
+                rid,
+                sessionId: sid,
+                projectRoot,
+                currentCycle: result.currentCycle,
+                previousCycle: result.previousCycle,
+                persistedAt: result.persistedAt,
+                rows: result.rows,
+                threshold: result.report.threshold,
+                status: result.report.status,
+                code: result.report.code,
+                monotonicityViolation: result.report.monotonicityViolation,
+                regressions: result.report.regressions,
+                reason: result.report.reason
+            }, [], result.report.monotonicityViolation
+                ? ['Investigate which evaluator regressed most and the previous cycle threshold.', `Inspect ${result.persistedAt ?? 'the persisted cycle row at .peaks/_runtime/<sid>/loop/<rid>/cycle-N.json'}.`]
+                : (result.report.status === 'skip'
+                    ? ['Cycle is the first run or incomparable; monotonicity guard is a no-op.', 'A future cycle will surface a violation if any evaluator regresses.']
+                    : ['All evaluators held or improved.', `Verifier verdict-aggregate can consume this envelope via \`peaks verdict aggregate --from-rid ${rid}\`.`])), options.json);
+            process.exitCode = exitCode;
+        }
+        catch (error) {
+            printResult(io, fail('loop.check-monotonic', 'LOOP_CHECK_MONOTONIC_FAILED', getErrorMessage(error), { rid }, ['Verify the rid and session binding.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop spec <rid> — Slice E.2: read or bootstrap the
+    // project-level `.peaks/_runtime/<sid>/loop/<rid>/spec.yaml`. When
+    // `--bootstrap` is set, a default spec is written; otherwise the
+    // existing spec is read (or `{kind:'missing'}` is returned).
+    const spec = loop.command('spec')
+        .description('Slice E.2: read or bootstrap the spec for a rid. Defaults to read; pass --bootstrap to write a default spec.');
+    addJsonOption(spec
+        .command('show')
+        .description('Slice E.2: print the resolved spec for a rid.')
+        .argument('<rid>', 'request id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')).action((rid, options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const resolved = resolveLoopSpec(projectRoot, options.session, rid);
+            if (resolved.spec === null) {
+                printResult(io, fail('loop.spec.show', 'SPEC_NOT_FOUND', `no spec.yaml at ${resolved.origin && resolved.origin.kind === 'missing' ? `.peaks/_runtime/${options.session}/loop/${rid}/spec.yaml` : 'unknown'}`, { rid, sessionId: options.session }, [
+                    `Create one via \`peaks loop spec bootstrap ${rid} --session ${options.session} --project ${projectRoot}\`.`
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const report = lintLoopSpec(resolved.spec);
+            printResult(io, ok('loop.spec.show', {
+                rid,
+                sessionId: options.session,
+                projectRoot,
+                origin: resolved.origin,
+                spec: resolved.spec,
+                lint: { ok: report.ok, errors: report.errors, warnings: report.warnings }
+            }, [], [
+                `Edit \`${typeof resolved.origin === 'object' && resolved.origin.kind === 'project' ? resolved.origin.path : '<spec>'}\` and re-run \`peaks loop spec lint <file>\`.`
+            ]), options.json);
+            if (!report.ok)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('loop.spec.show', 'LOOP_SPEC_SHOW_FAILED', getErrorMessage(error), { rid }, ['Verify the rid and session binding.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(spec
+        .command('bootstrap')
+        .description('Slice E.2: write a default spec.yaml for a rid at `.peaks/_runtime/<sid>/loop/<rid>/spec.yaml`. Refuses to overwrite an existing spec without --force (P1 from dogfood audit: bootstrap is destructive on re-run).')
+        .argument('<rid>', 'request id')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--strategy <strategy>', `termination strategy (manual|max-cycles|${MONOTONIC_TERMINATION})`, MONOTONIC_TERMINATION)
+        .option('--max-cycles <n>', `max-cycles (only when strategy=max-cycles; default ${DEFAULT_MAX_CYCLES})`, String(DEFAULT_MAX_CYCLES))
+        .option('--force', 'overwrite an existing spec.yaml (without --force, bootstrap refuses with SPEC_EXISTS_NEEDS_FORCE)', false)).action((rid, options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const path = specPath(projectRoot, options.session, rid);
+            // P1二次保护:spec.yaml 已存在且未带 --force → SPEC_EXISTS_NEEDS_FORCE
+            if (existsSync(path) && options.force !== true) {
+                printResult(io, fail('loop.spec.bootstrap', 'SPEC_EXISTS_NEEDS_FORCE', `spec.yaml already exists at ${path}; re-run with --force to overwrite`, { rid, sessionId: options.session, path }, [
+                    `Re-run with \`peaks loop spec bootstrap ${rid} --session ${options.session} --force\` to overwrite.`,
+                    `Or edit \`${path}\` directly.`
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const strategyRaw = options.strategy;
+            const strategy = (strategyRaw === 'max-cycles' || strategyRaw === MONOTONIC_TERMINATION || strategyRaw === 'manual') ? strategyRaw : MONOTONIC_TERMINATION;
+            const termination = strategy === 'max-cycles'
+                ? { strategy, maxCycles: Math.max(1, Math.floor(Number(options.maxCycles) || DEFAULT_MAX_CYCLES)) }
+                : { strategy };
+            const evaluators = [
+                { kind: 'karpathy', gate: 'Gate B3', scope: 'src/' },
+                { kind: 'code-review', gate: 'Gate B3', scope: 'src/' },
+                { kind: 'security-review', gate: 'Gate B4', scope: 'src/' },
+                { kind: 'perf-baseline', gate: 'Gate B4', scope: 'src/' },
+                { kind: 'monotonic-improvement', gate: 'Gate D1' }
+            ];
+            const sla = [
+                { evaluator: 'karpathy', maxScore: 0.7 },
+                { evaluator: 'code-review', maxScore: 0.7 },
+                { evaluator: 'security-review', maxScore: 0.7 },
+                { evaluator: 'perf-baseline', maxScore: 0.7 },
+                { evaluator: 'monotonic-improvement', maxScore: 0.5 }
+            ];
+            const specObj = buildSpec({ rid, evaluators, sla, termination }, rid);
+            const report = lintLoopSpec(specObj);
+            if (!report.ok) {
+                printResult(io, fail('loop.spec.bootstrap', 'SPEC_LINT_FAILED', report.errors.join('; '), { rid, report }, ['Verify the strategy flag.']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const writtenPath = persistSpec(projectRoot, options.session, specObj);
+            printResult(io, ok('loop.spec.bootstrap', {
+                rid,
+                sessionId: options.session,
+                projectRoot,
+                path: writtenPath,
+                spec: specObj,
+                lint: { ok: report.ok, errors: report.errors, warnings: report.warnings },
+                overwritten: options.force === true && existsSync(writtenPath)
+            }, [], [
+                `Run \`peaks loop spec lint ${writtenPath}\` to re-validate.`,
+                `Then run \`peaks loop run ${rid} --session ${options.session}\` to execute the loop.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('loop.spec.bootstrap', 'LOOP_SPEC_BOOTSTRAP_FAILED', getErrorMessage(error), { rid }, ['Verify the rid, session, and strategy flag.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(spec
+        .command('lint')
+        .description('Slice E.2: schema-validate a spec.yaml file (path required).')
+        .argument('<file>', 'path to spec.yaml')
+        .option('--rid <rid>', 'override the rid embedded in the spec (default: inferred from path)')).action((file, options) => {
+        try {
+            const result = lintSpecFile(file, options.rid);
+            if (result.spec === null) {
+                printResult(io, fail('loop.spec.lint', 'SPEC_LINT_FAILED', result.report.errors.join('; '), { file, raw: result.raw.slice(0, 200) }, ['Verify the file path and YAML syntax.']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('loop.spec.lint', {
+                file,
+                spec: result.spec,
+                lint: { ok: result.report.ok, errors: result.report.errors, warnings: result.report.warnings }
+            }, [], []), options.json);
+            if (!result.report.ok)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('loop.spec.lint', 'LOOP_SPEC_LINT_FAILED', getErrorMessage(error), { file }, ['Verify the file path and rid flag.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop run <rid> — Slice F.1 (P0 closure): the closed-loop
+    // driver that actually consumes `termination.strategy` (previously
+    // declared-and-validated but never consumed — dogfood audit #2).
+    addJsonOption(loop
+        .command('run')
+        .description(`Slice F.1: drive the closed loop for <rid> per .peaks/_runtime/<sid>/loop/<rid>/spec.yaml. Consumes termination.strategy (${MONOTONIC_TERMINATION} | max-cycles | manual); aborts on MONOTONICITY_VIOLATION.`)
+        .argument('<rid>', 'request id (e.g. 2026-06-30-...)')
+        .requiredOption('--session <sid>', 'session id')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--strategy <strategy>', `override termination.strategy (allowed: ${MONOTONIC_TERMINATION}, max-cycles, manual)`)
+        .option('--max-cycles <n>', `override termination.maxCycles (default ${DEFAULT_MAX_CYCLES})`)
+        .option('--threshold <t>', 'monotonic threshold (0..1); default 0.05')
+        .option('--no-persist', 'skip writing cycle-N.json + summary to disk')).action((rid, options) => {
+        try {
+            const { projectRoot, sid, rid: r2 } = resolveRunContext({ ...(options.project !== undefined ? { project: options.project } : {}), session: options.session, rid });
+            const threshold = options.threshold !== undefined ? Number(options.threshold) : undefined;
+            if (threshold !== undefined && (!Number.isFinite(threshold) || threshold < 0 || threshold > 1)) {
+                printResult(io, fail('loop.run', 'INVALID_THRESHOLD', `threshold must be finite in [0,1] (got "${options.threshold}")`, { rid: r2 }, [`Pass --threshold 0.05 (default) or any number in [0,1].`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const maxCycles = options.maxCycles !== undefined ? Math.max(1, Math.floor(Number(options.maxCycles) || DEFAULT_MAX_CYCLES)) : undefined;
+            const strategyOverride = options.strategy;
+            const result = runLoop({
+                projectRoot,
+                sid,
+                rid: r2,
+                ...(threshold !== undefined ? { threshold } : {}),
+                ...(maxCycles !== undefined ? { maxCyclesOverride: maxCycles } : {}),
+                ...(strategyOverride !== undefined ? { strategyOverride } : {}),
+                persist: options.persist !== false
+            });
+            const exitCode = mapRunDriverCodeToExit(result.code);
+            const finalReportCode = result.finalReport?.code ?? null;
+            printResult(io, result.ok
+                ? ok('loop.run', {
+                    rid: r2,
+                    sessionId: sid,
+                    projectRoot,
+                    code: result.code,
+                    strategy: result.strategy,
+                    maxCycles: result.maxCycles,
+                    cycles: result.cycles.map((c) => ({
+                        cycle: c.cycle,
+                        rows: c.rows,
+                        persistedAt: c.persistedAt,
+                        monotonicReport: c.monotonicReport
+                    })),
+                    finalReport: result.finalReport,
+                    finalReportCode,
+                    summary: result.summary
+                }, [], result.code === 'RUN_OK'
+                    ? [`Loop completed ${result.summary.totalCycles} cycle(s) with ${result.summary.regressionCount} regression(s).`]
+                    : [`Run driver exited with ${result.code}: ${result.message}`])
+                : fail('loop.run', result.code, result.message, {
+                    rid: r2,
+                    sessionId: sid,
+                    projectRoot,
+                    code: result.code,
+                    strategy: result.strategy,
+                    maxCycles: result.maxCycles,
+                    cycles: result.cycles,
+                    finalReport: result.finalReport,
+                    finalReportCode,
+                    summary: result.summary
+                }, nextActionsForCode(result.code, r2, sid, result.summary)), options.json);
+            process.exitCode = exitCode;
+        }
+        catch (error) {
+            printResult(io, fail('loop.run', 'RUN_FAILED', getErrorMessage(error), { rid }, ['Verify the rid and session binding.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+/** Test seam: pick the next cycle-N.json number for capture-score
+ *  writes. The run-driver also writes to the same dir; the next
+ *  index = max(prior)+1, or 1. */
+function nextEvalCaptureIndex(projectRoot, sid, rid) {
+    const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');
+    if (!existsSync(dir))
+        return 1;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return 1;
+    }
+    let best = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const n = parseInt(m[1] ?? '0', 10);
+        if (best === null || n > best)
+            best = n;
+    }
+    return (best ?? 0) + 1;
+}
+/** Map a run-driver code to a process exit code. */
+function mapRunDriverCodeToExit(code) {
+    if (code === 'RUN_OK' || code === 'RUN_OK_REGRESSION')
+        return 0;
+    return 1;
+}
+function nextActionsForCode(code, rid, sid, summary) {
+    switch (code) {
+        case 'SPEC_NOT_FOUND':
+            return [`Create a spec with \`peaks loop spec bootstrap ${rid} --session ${sid}\`.`];
+        case 'SPEC_INVALID':
+            return [`Re-run \`peaks loop spec lint <path>\` to see the schema errors.`];
+        case 'UNKNOWN_TERMINATION_STRATEGY':
+            return [`Edit the spec.yaml and set termination.strategy to one of: ${MONOTONIC_TERMINATION}, max-cycles, manual.`];
+        case 'MONOTONICITY_VIOLATION':
+            return [
+                'Inspect the regression rows in the cycles output and the previous cycle row at .peaks/_runtime/' + sid + '/loop/' + rid + '/cycles/.',
+                'Fix the regression in the next iteration and re-run.'
+            ];
+        case 'LOCKED':
+            return ['Wait for the in-flight loop run to complete, or pick a different rid.'];
+        case 'RUN_OK_REGRESSION':
+            return ['A regression was observed; the run captured it for operator review.'];
+        case 'RUN_OK':
+            return [`Loop completed ${summary.totalCycles} cycle(s); ${summary.regressionCount} regression(s).`];
+        default:
+            return ['Inspect the run-driver output above.'];
+    }
+}

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

@@ -0,0 +1,129 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
+import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { join } from 'node:path';
+const VALID_KINDS = [
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson',
+];
+export async function runMemoryList(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    try {
+        const snapshot = loadMemoryIndex(projectRoot);
+        const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
+            ? options.kind
+            : undefined;
+        const entries = kindFilter === undefined
+            ? snapshot.entries
+            : snapshot.entries.filter((e) => e.kind === kindFilter);
+        const warnings = [];
+        let pickedEntries = entries;
+        let pickedOutputPath = null;
+        let fzfVersion = null;
+        if (options.pick === true) {
+            const outputPath = join(projectRoot, '.peaks', 'memory', 'picked.json');
+            const byName = new Map(entries.map((e) => [e.name, e]));
+            const result = await pickFromList({
+                items: entries,
+                formatLine: (entry) => `${entry.name} | ${entry.kind} | ${entry.description.slice(0, 60)}`,
+                parseLine: (line) => {
+                    const parts = line.split('|').map((p) => p.trim());
+                    if (parts.length < 1)
+                        return null;
+                    const name = parts[0];
+                    if (name === undefined || name.length === 0)
+                        return null;
+                    return byName.get(name) ?? null;
+                },
+                outputPath,
+                meta: { kindFilter: kindFilter ?? null, totalCandidates: entries.length },
+                ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
+                projectRoot,
+                multi: true,
+                prompt: 'memory> '
+            });
+            pickedEntries = [...result.picked];
+            pickedOutputPath = result.outputPath;
+            fzfVersion = result.fzfVersion;
+        }
+        const nextActions = [];
+        if (pickedOutputPath !== null) {
+            nextActions.push(`Picked ${pickedEntries.length} entr(ies); written to ${pickedOutputPath}`);
+        }
+        if (entries.length === 0) {
+            nextActions.push('No entries match; run `peaks memory extract` to build the index from memory/*.md files.');
+        }
+        printResult(io, ok('memory.list', {
+            indexPath: snapshot.indexPath,
+            version: snapshot.version,
+            updatedAt: snapshot.updatedAt,
+            total: entries.length,
+            kindFilter: kindFilter ?? null,
+            entries,
+            ...(options.pick === true ? { picked: pickedEntries, pickedOutputPath, fzfVersion } : {})
+        }, warnings, nextActions), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_LIST_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks memory extract` to build the index from memory/*.md files');
+        }
+        printResult(io, fail('memory.list', code, message, { projectRoot }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export async 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;
+    try {
+        const out = await searchMemoryWithResults({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
+        }, {
+            ...(options.compressResults === true ? { compressResults: true } : {})
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: out.matches.length,
+            matches: out.matches,
+            ...(out.compressedResults !== null ? { compressedResults: out.compressedResults } : {}),
+            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;
+    }
+}