peaks-loop 4.1.1 → 4.1.3

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

@@ -0,0 +1,168 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { dispatchEvaluator } from '../../services/loop/evaluator-dispatcher.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';
+import { loopCommandParent } from './loop-eval-parents.js';
+import { nextEvalCaptureIndex } from './loop-eval-capture-index.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 registerLoopEvalCommand(program, io) {
+    const loop = loopCommandParent(program);
+    // 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) => runLoopEval(rid, options, io));
+}
+function evalUnknownEvaluatorFailure(rid, evaluator) {
+    return fail('loop.eval', 'UNKNOWN_EVALUATOR', `evaluator "${evaluator}" is not a native evaluator (allowed: ${[...VALID_EVALUATORS].join(', ')})`, { rid }, [`Use one of: ${[...VALID_EVALUATORS].join(', ')}`]);
+}
+function evalMissingSessionFailure(rid) {
+    return fail('loop.eval', 'CAPTURE_SCORE_NEEDS_SESSION', '--capture-score requires --session <sid>', { rid }, ['Pass --session <sid> alongside --capture-score.']);
+}
+function evalCapturePathFailure(rid, sid) {
+    if (isUnsafePathInput(sid)) {
+        return fail('loop.eval', 'INVALID_SESSION_ID', `Invalid session id: ${sid} (must be a single path segment)`, { provided: sid }, ['Pass a session id that is a single path segment']);
+    }
+    if (isUnsafePathInput(rid)) {
+        return fail('loop.eval', 'INVALID_REQUEST_ID', `Invalid request id: ${rid} (must be a single path segment)`, { provided: rid }, ['Pass a request id that is a single path segment']);
+    }
+    return null;
+}
+function reportEvalFailure(io, failure, asJson) {
+    printResult(io, failure, asJson);
+    process.exitCode = 1;
+}
+function reportLoopEvalFailure(io, error, data, asJson) {
+    printResult(io, fail('loop.eval', 'LOOP_EVAL_FAILED', getErrorMessage(error), data, [
+        'Verify the rid and evaluator name.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function captureEvalScore(rid, sid, projectRoot, envelope) {
+    const score = envelope.degraded
+        ? 0.25
+        : envelope.gateAction === 'pass'
+            ? 1.0
+            : envelope.gateAction === 'warn'
+                ? 0.5
+                : 0.0;
+    const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');
+    const n = nextEvalCaptureIndex(projectRoot, sid, rid);
+    const path = join(dir, `cycle-${n}.json`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(path, JSON.stringify({
+            cycle: n,
+            rid,
+            sid,
+            persistedAt: new Date().toISOString(),
+            scores: [
+                {
+                    evaluator: envelope.kind,
+                    score,
+                    gateAction: envelope.gateAction,
+                    degraded: envelope.degraded,
+                    observedAt: new Date().toISOString()
+                }
+            ]
+        }), 'utf8');
+        return { score, persistedAt: path };
+    }
+    catch {
+        return { score, persistedAt: null };
+    }
+}
+function evalResultData(rid, envelope, capture) {
+    return {
+        rid,
+        evaluator: envelope.kind,
+        verdict: envelope.gateAction,
+        passed: envelope.passed,
+        violations: envelope.violations,
+        summary: envelope.summary,
+        wallSeconds: envelope.wallSeconds,
+        degraded: envelope.degraded,
+        ...(capture !== null ? { score: capture.score, capture } : {})
+    };
+}
+function evalNextActions(rid, envelope) {
+    return 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}\`.`
+        ];
+}
+function runLoopEval(rid, options, io) {
+    try {
+        if (!VALID_EVALUATORS.has(options.evaluator)) {
+            const failure = evalUnknownEvaluatorFailure(rid, options.evaluator);
+            printResult(io, failure, 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 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) {
+            // Sid axis AND rid axis — the join below takes TWO ids, not one.
+            // covers "the whole `--capture-score` write path". The security audit of
+            // the `--session` guard passed and the `rid` slot escaped:
+            // `peaks loop eval '../../../../…/EVILCYC' --capture-score --session
+            // <legal>` created `<projectRoot>/../EVILCYC/cycles/cycle-1.json` under
+            // an `ok: true` envelope. The rid is the CLI positional and has no pinned
+            // format, so the segment check is the control for that axis.
+            const sid = options.session;
+            if (sid === undefined || sid.length === 0) {
+                reportEvalFailure(io, evalMissingSessionFailure(rid), options.json);
+                return;
+            }
+            const pathFailure = evalCapturePathFailure(rid, sid);
+            if (pathFailure !== null) {
+                reportEvalFailure(io, pathFailure, options.json);
+                return;
+            }
+            capture = captureEvalScore(rid, sid, projectRoot, envelope);
+        }
+        const data = evalResultData(rid, envelope, capture);
+        const actions = evalNextActions(rid, envelope);
+        printResult(io, ok('loop.eval', data, [], actions), options.json);
+        process.exitCode = exitCode;
+    }
+    catch (error) {
+        reportLoopEvalFailure(io, error, { rid, evaluator: options.evaluator }, options.json);
+    }
+}

package/dist/cli/commands/loop-eval-monotonic-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopCheckMonotonicCommand(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,90 @@
+import { DEFAULT_MONOTONIC_THRESHOLD } from '../../services/loop/monotonic-guard.js';
+import { runMonotonicCheck, resolveMonotonicContext } from '../../services/loop/monotonic-runner.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { loopCommandParent } from './loop-eval-parents.js';
+export function registerLoopCheckMonotonicCommand(program, io) {
+    const loop = loopCommandParent(program);
+    // 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) => runCheckMonotonic(rid, options, io));
+}
+function reportMonotonicFailure(io, error, rid, asJson) {
+    printResult(io, fail('loop.check-monotonic', 'LOOP_CHECK_MONOTONIC_FAILED', getErrorMessage(error), { rid }, [
+        'Verify the rid and session binding.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function monotonicResultData(rid, sid, projectRoot, result) {
+    return {
+        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
+    };
+}
+function monotonicNextActions(rid, result) {
+    return 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}\`.`
+            ];
+}
+function runCheckMonotonic(rid, options, io) {
+    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;
+        const data = monotonicResultData(rid, sid, projectRoot, result);
+        const actions = monotonicNextActions(rid, result);
+        printResult(io, ok('loop.check-monotonic', data, [], actions), options.json);
+        process.exitCode = exitCode;
+    }
+    catch (error) {
+        reportMonotonicFailure(io, error, rid, options.json);
+    }
+}

package/dist/cli/commands/loop-eval-parents.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+/** The `peaks workflow` parent, or a newly created one. */
+export declare function workflowCommandParent(program: Command): Command;
+/** The `peaks loop` parent, or a newly created one. */
+export declare function loopCommandParent(program: Command): Command;
+/** The `peaks loop spec` parent, or a newly created one. */
+export declare function loopSpecParent(program: Command): Command;

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

@@ -0,0 +1,20 @@
+/** The `peaks workflow` parent, or a newly created one. */
+export function workflowCommandParent(program) {
+    const existingWorkflow = program.commands.find((c) => c.name() === 'workflow');
+    return (existingWorkflow ??
+        program.command('workflow').description('Workflow primitive (run / plan / lint)'));
+}
+/** The `peaks loop` parent, or a newly created one. */
+export function loopCommandParent(program) {
+    const existingLoop = program.commands.find((c) => c.name() === 'loop');
+    return existingLoop ?? program.command('loop').description('Loop primitive (eval)');
+}
+/** The `peaks loop spec` parent, or a newly created one. */
+export function loopSpecParent(program) {
+    const loop = loopCommandParent(program);
+    const existingSpec = loop.commands.find((c) => c.name() === 'spec');
+    return (existingSpec ??
+        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.'));
+}

package/dist/cli/commands/loop-eval-run-code.d.ts

@@ -0,0 +1,7 @@
+/** Map a run-driver code to a process exit code. */
+export declare function mapRunDriverCodeToExit(code: string): number;
+export declare function nextActionsForCode(code: string, rid: string, sid: string, summary: {
+    reachedMaxCycles: boolean;
+    regressionCount: number;
+    totalCycles: number;
+}): string[];

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

@@ -0,0 +1,40 @@
+// The `peaks loop run` result presenter: the run-driver's terminal code mapped to a
+// process exit code, and to the prose a caller reads after a failed run.
+import { MONOTONIC_TERMINATION } from '../../services/loop/spec-service.js';
+/** Map a run-driver code to a process exit code. */
+export function mapRunDriverCodeToExit(code) {
+    if (code === 'RUN_OK' || code === 'RUN_OK_REGRESSION')
+        return 0;
+    return 1;
+}
+export 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/loop-eval-run-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopRunCommand(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,113 @@
+import { 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 { loopCommandParent } from './loop-eval-parents.js';
+import { mapRunDriverCodeToExit, nextActionsForCode } from './loop-eval-run-code.js';
+export function registerLoopRunCommand(program, io) {
+    const loop = loopCommandParent(program);
+    // 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) => runLoopDriver(rid, options, io));
+}
+function reportLoopRunFailure(io, error, rid, asJson) {
+    printResult(io, fail('loop.run', 'RUN_FAILED', getErrorMessage(error), { rid }, [
+        'Verify the rid and session binding.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function loopRunInvalidThresholdFailure(rid, threshold) {
+    return fail('loop.run', 'INVALID_THRESHOLD', `threshold must be finite in [0,1] (got "${threshold}")`, { rid }, [`Pass --threshold 0.05 (default) or any number in [0,1].`]);
+}
+function loopRunOkData(result, rid, sid, projectRoot) {
+    return {
+        rid,
+        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: result.finalReport?.code ?? null,
+        summary: result.summary
+    };
+}
+function loopRunFailData(result, rid, sid, projectRoot) {
+    return {
+        rid,
+        sessionId: sid,
+        projectRoot,
+        code: result.code,
+        strategy: result.strategy,
+        maxCycles: result.maxCycles,
+        cycles: result.cycles,
+        finalReport: result.finalReport,
+        finalReportCode: result.finalReport?.code ?? null,
+        summary: result.summary
+    };
+}
+function loopRunNextActions(result) {
+    return 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}`];
+}
+function loopRunEnvelope(result, rid, sid, projectRoot) {
+    return result.ok
+        ? ok('loop.run', loopRunOkData(result, rid, sid, projectRoot), [], loopRunNextActions(result))
+        : fail('loop.run', result.code, result.message, loopRunFailData(result, rid, sid, projectRoot), nextActionsForCode(result.code, rid, sid, result.summary));
+}
+function runLoopDriver(rid, options, io) {
+    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)) {
+            const failure = loopRunInvalidThresholdFailure(r2, options.threshold);
+            printResult(io, failure, 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 envelope = loopRunEnvelope(result, r2, sid, projectRoot);
+        printResult(io, envelope, options.json);
+        process.exitCode = exitCode;
+    }
+    catch (error) {
+        reportLoopRunFailure(io, error, rid, options.json);
+    }
+}

package/dist/cli/commands/loop-eval-spec-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopSpecCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { resolveLoopSpec, persistSpec, buildSpec, lintLoopSpec, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from '../../services/loop/spec-service.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';
+import { loopSpecParent } from './loop-eval-parents.js';
+export function registerLoopSpecCommands(program, io) {
+    // 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 = loopSpecParent(program);
+    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) => runLoopSpecShow(rid, options, io));
+    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) => runLoopSpecBootstrap(rid, options, io));
+}
+function reportLoopSpecShowFailure(io, error, rid, asJson) {
+    printResult(io, fail('loop.spec.show', 'LOOP_SPEC_SHOW_FAILED', getErrorMessage(error), { rid }, [
+        'Verify the rid and session binding.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function runLoopSpecShow(rid, options, io) {
+    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) {
+        reportLoopSpecShowFailure(io, error, rid, options.json);
+    }
+}
+function resolveBootstrapTermination(options) {
+    const strategyRaw = options.strategy;
+    const strategy = strategyRaw === 'max-cycles' ||
+        strategyRaw === MONOTONIC_TERMINATION ||
+        strategyRaw === 'manual'
+        ? strategyRaw
+        : MONOTONIC_TERMINATION;
+    return strategy === 'max-cycles'
+        ? {
+            strategy,
+            maxCycles: Math.max(1, Math.floor(Number(options.maxCycles) || DEFAULT_MAX_CYCLES))
+        }
+        : { strategy };
+}
+function defaultSpecEvaluators() {
+    return [
+        { 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' }
+    ];
+}
+function defaultSpecSla() {
+    return [
+        { 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 }
+    ];
+}
+function specExistsFailure(rid, sessionId, path) {
+    return fail('loop.spec.bootstrap', 'SPEC_EXISTS_NEEDS_FORCE', `spec.yaml already exists at ${path}; re-run with --force to overwrite`, { rid, sessionId, path }, [
+        `Re-run with \`peaks loop spec bootstrap ${rid} --session ${sessionId} --force\` to overwrite.`,
+        `Or edit \`${path}\` directly.`
+    ]);
+}
+function specLintFailure(rid, report) {
+    return fail('loop.spec.bootstrap', 'SPEC_LINT_FAILED', report.errors.join('; '), { rid, report }, ['Verify the strategy flag.']);
+}
+function specBootstrapData(context, specObj, report) {
+    return {
+        rid: context.rid,
+        sessionId: context.sessionId,
+        projectRoot: context.projectRoot,
+        path: context.path,
+        spec: specObj,
+        lint: { ok: report.ok, errors: report.errors, warnings: report.warnings },
+        overwritten: context.force === true && existsSync(context.path)
+    };
+}
+function specBootstrapActions(rid, sessionId, writtenPath) {
+    return [
+        `Run \`peaks loop spec lint ${writtenPath}\` to re-validate.`,
+        `Then run \`peaks loop run ${rid} --session ${sessionId}\` to execute the loop.`
+    ];
+}
+function reportLoopSpecBootstrapFailure(io, error, rid, asJson) {
+    printResult(io, fail('loop.spec.bootstrap', 'LOOP_SPEC_BOOTSTRAP_FAILED', getErrorMessage(error), { rid }, [
+        'Verify the rid, session, and strategy flag.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function runLoopSpecBootstrap(rid, options, io) {
+    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) {
+            const failure = specExistsFailure(rid, options.session, path);
+            printResult(io, failure, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const termination = resolveBootstrapTermination(options);
+        const evaluators = defaultSpecEvaluators();
+        const sla = defaultSpecSla();
+        const specObj = buildSpec({ rid, evaluators, sla, termination }, rid);
+        const report = lintLoopSpec(specObj);
+        if (!report.ok) {
+            const failure = specLintFailure(rid, report);
+            printResult(io, failure, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const writtenPath = persistSpec(projectRoot, options.session, specObj);
+        const writeCtx = {
+            rid,
+            sessionId: options.session,
+            projectRoot,
+            path: writtenPath,
+            ...(options.force !== undefined ? { force: options.force } : {})
+        };
+        const data = specBootstrapData(writeCtx, specObj, report);
+        const actions = specBootstrapActions(rid, options.session, writtenPath);
+        printResult(io, ok('loop.spec.bootstrap', data, [], actions), options.json);
+    }
+    catch (error) {
+        reportLoopSpecBootstrapFailure(io, error, rid, options.json);
+    }
+}

package/dist/cli/commands/loop-eval-spec-lint-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopSpecLintCommand(program: Command, io: ProgramIO): void;