peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/evolution-command-shared.d.ts

@@ -0,0 +1,78 @@
+import { EvolutionService, type EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { type EvolutionTargetKind } from '../../services/evolution/evolution-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+/** A parsed `--target <kind:id>` flag. */
+export interface EvolutionTarget {
+    kind: EvolutionTargetKind;
+    id: string;
+}
+/**
+ * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
+ * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS
+ * union.
+ */
+export declare function parseTargetFlag(raw: string): EvolutionTarget | null;
+/** The shared `--target` parse failure envelope (`propose` + `status`). */
+export declare function invalidTargetFailure(command: string, target: string): ResultEnvelope<{
+    target: string;
+}>;
+/** The shared "no such proposal" failure envelope. */
+export declare function proposalNotFoundFailure(command: string, proposalId: string, nextActions: string[]): ResultEnvelope<{
+    proposalId: string;
+}>;
+/**
+ * Helper: collect repeatable `--risk-tag` values into an array.
+ * Commander's `collect` is not always available; we read
+ * `previous` from the default value.
+ */
+export declare function collectRepeatable(value: string, previous: string[]): string[];
+/** Upper bound of the 0..10 score scale used by proposal + evaluator scores. */
+export declare const SCORE_SCALE_MAX = 10;
+/** True when `value` is a finite number on the 0..10 score scale. */
+export declare function isScoreInRange(value: number): boolean;
+/** Inputs for {@link scoreRangeFailure}. */
+export interface ScoreRangeFailureArgs {
+    command: string;
+    code: string;
+    /** Message label, e.g. `before_score`. */
+    label: string;
+    /** CLI flag named in the hint, e.g. `--before-score`. */
+    flag: string;
+    /** `data` key carrying the raw value, e.g. `beforeScore`. */
+    key: string;
+    /** The raw, unparsed flag value. */
+    raw: string;
+}
+/** The shared "[0, 10] finite number" validation failure envelope. */
+export declare function scoreRangeFailure(args: ScoreRangeFailureArgs): ResultEnvelope<Record<string, string>>;
+/** The `--delta-min` validation failure envelope. */
+export declare function deltaMinFailure(command: string, raw: string): ResultEnvelope<Record<string, string>>;
+/** Run `body` against a fresh EvolutionService, closing the DB after. */
+export declare function withEvolutionDb<T>(project: string | undefined, body: (svc: EvolutionService) => T): T;
+/** `await`-friendly sibling of {@link withEvolutionDb}. */
+export declare function withEvolutionDbAsync<T>(project: string | undefined, body: (svc: EvolutionService) => Promise<T>): Promise<T>;
+/** Params for {@link reportIntegrityFailure}. */
+export interface IntegrityFailureReport {
+    io: ProgramIO;
+    command: string;
+    error: EvolutionIntegrityError;
+    nextActions: string[];
+    /** `options.json` — the caller's `--json` flag, possibly absent. */
+    asJson?: boolean | undefined;
+}
+/** Print an `EvolutionIntegrityError` envelope and set exit code 1. */
+export declare function reportIntegrityFailure(report: IntegrityFailureReport): void;
+/** Params for {@link reportFailure}. */
+export interface CommandFailureReport {
+    io: ProgramIO;
+    command: string;
+    code: string;
+    error: unknown;
+    data: Record<string, unknown>;
+    nextActions: string[];
+    /** `options.json` — the caller's `--json` flag, possibly absent. */
+    asJson?: boolean | undefined;
+}
+/** Print a generic `<command>_FAILED` envelope and set exit code 1. */
+export declare function reportFailure(report: CommandFailureReport): void;

package/dist/cli/commands/evolution-command-shared.js

@@ -0,0 +1,107 @@
+/**
+ * Shared helpers for the `peaks evolution *` subcommand modules
+ * (propose / evaluate / mark-keep / revert / status). Split out of
+ * `evolution-commands.ts` in the size-debt batch: every command name,
+ * option, envelope key, error code and exit-code site is unchanged.
+ *
+ * Nothing here holds module-level mutable state: each helper takes
+ * parameters and returns a value, and the DB helpers own the
+ * open/close pair so callers never see a half-closed handle.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { EvolutionService } from '../../services/evolution/evolution-service.js';
+import { EVOLUTION_TARGET_KINDS } from '../../services/evolution/evolution-types.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+/**
+ * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
+ * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS
+ * union.
+ */
+export function parseTargetFlag(raw) {
+    const idx = raw.indexOf(':');
+    if (idx <= 0 || idx === raw.length - 1)
+        return null;
+    const kind = raw.slice(0, idx);
+    const id = raw.slice(idx + 1);
+    if (!EVOLUTION_TARGET_KINDS.includes(kind))
+        return null;
+    return { kind: kind, id };
+}
+/** The shared `--target` parse failure envelope (`propose` + `status`). */
+export function invalidTargetFailure(command, target) {
+    return fail(command, 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']);
+}
+/** The shared "no such proposal" failure envelope. */
+export function proposalNotFoundFailure(command, proposalId, nextActions) {
+    return fail(command, 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${proposalId}' not found`, { proposalId }, nextActions);
+}
+/**
+ * Helper: collect repeatable `--risk-tag` values into an array.
+ * Commander's `collect` is not always available; we read
+ * `previous` from the default value.
+ */
+export function collectRepeatable(value, previous) {
+    if (Array.isArray(previous))
+        return [...previous, value];
+    return [value];
+}
+/** Upper bound of the 0..10 score scale used by proposal + evaluator scores. */
+export const SCORE_SCALE_MAX = 10;
+/** True when `value` is a finite number on the 0..10 score scale. */
+export function isScoreInRange(value) {
+    return Number.isFinite(value) && value >= 0 && value <= SCORE_SCALE_MAX;
+}
+/** The shared "[0, 10] finite number" validation failure envelope. */
+export function scoreRangeFailure(args) {
+    return fail(args.command, args.code, `${args.label} must be a finite number in [0, 10] (got "${args.raw}")`, { [args.key]: args.raw }, [`Pass a numeric ${args.flag} in [0, 10].`]);
+}
+/** The `--delta-min` validation failure envelope. */
+export function deltaMinFailure(command, raw) {
+    return fail(command, 'EVOLUTION_INVALID_DELTA_MIN', `delta_min must be a finite number >= 0 (got "${raw}")`, { deltaMin: raw }, ['Pass a numeric --delta-min >= 0 (default 1.0).']);
+}
+/**
+ * Resolve the project root, bootstrap an empty `.peaks/` dir when it
+ * is missing (so tests do not need a full peaks project) and open the
+ * state DB.
+ */
+function openEvolutionDb(project) {
+    const projectRoot = project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    if (!existsSync(join(projectRoot, '.peaks'))) {
+        mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+    }
+    return openStateDb(join(projectRoot, '.peaks', 'state.db'));
+}
+/** Run `body` against a fresh EvolutionService, closing the DB after. */
+export function withEvolutionDb(project, body) {
+    const db = openEvolutionDb(project);
+    try {
+        return body(new EvolutionService(db));
+    }
+    finally {
+        db.close();
+    }
+}
+/** `await`-friendly sibling of {@link withEvolutionDb}. */
+export async function withEvolutionDbAsync(project, body) {
+    const db = openEvolutionDb(project);
+    try {
+        return await body(new EvolutionService(db));
+    }
+    finally {
+        db.close();
+    }
+}
+/** Print an `EvolutionIntegrityError` envelope and set exit code 1. */
+export function reportIntegrityFailure(report) {
+    printResult(report.io, fail(report.command, report.error.code, report.error.message, { findings: report.error.findings }, report.nextActions), report.asJson);
+    process.exitCode = 1;
+}
+/** Print a generic `<command>_FAILED` envelope and set exit code 1. */
+export function reportFailure(report) {
+    printResult(report.io, fail(report.command, report.code, getErrorMessage(report.error), report.data, report.nextActions), report.asJson);
+    process.exitCode = 1;
+}

package/dist/cli/commands/evolution-commands.d.ts

@@ -20,7 +20,17 @@
  *
  * Defense in depth: the EvolutionService enforces the ratchet
  * into the service payload.
+ *
+ * Size-debt split: each verb's registration and action body now lives
+ * in its own sibling module — `evolution-propose-command.ts`,
+ * `evolution-evaluate-command.ts`, `evolution-verdict-commands.ts`
+ * (mark-keep + revert) and `evolution-status-command.ts` — over the
+ * shared parse / validate / DB / failure helpers in
+ * `evolution-command-shared.ts`. This file keeps the parent and the
+ * delegation only; every command name, option, envelope key, error
+ * code and exit-code site is unchanged.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
+export type { EvolutionTarget } from './evolution-command-shared.js';
 export declare function registerEvolutionCommands(program: Command, io: ProgramIO): void;

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

@@ -20,31 +20,21 @@
  *
  * Defense in depth: the EvolutionService enforces the ratchet
  * into the service payload.
+ *
+ * Size-debt split: each verb's registration and action body now lives
+ * in its own sibling module — `evolution-propose-command.ts`,
+ * `evolution-evaluate-command.ts`, `evolution-verdict-commands.ts`
+ * (mark-keep + revert) and `evolution-status-command.ts` — over the
+ * shared parse / validate / DB / failure helpers in
+ * `evolution-command-shared.ts`. This file keeps the parent and the
+ * delegation only; every command name, option, envelope key, error
+ * code and exit-code site is unchanged.
  */
-import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { openStateDb } from '../../services/skillhub/sqlite-store.js';
-import { EvolutionService, EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
-import { EVOLUTION_TARGET_KINDS } from '../../services/evolution/evolution-types.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { runIndependentEvaluator } from '../../services/evolution/independent-evaluator-runner.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-/**
- * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
- * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS
- * union.
- */
-function parseTargetFlag(raw) {
-    const idx = raw.indexOf(':');
-    if (idx <= 0 || idx === raw.length - 1)
-        return null;
-    const kind = raw.slice(0, idx);
-    const id = raw.slice(idx + 1);
-    if (!EVOLUTION_TARGET_KINDS.includes(kind))
-        return null;
-    return { kind: kind, id };
-}
+import { dirname } from 'node:path';
+import { registerEvaluateCommand } from './evolution-evaluate-command.js';
+import { registerProposeCommand } from './evolution-propose-command.js';
+import { registerStatusCommand } from './evolution-status-command.js';
+import { registerMarkKeepCommand, registerRevertCommand } from './evolution-verdict-commands.js';
 export function registerEvolutionCommands(program, io) {
     // Reuse the existing `evolution` parent if one is registered;
     // otherwise create it. The add-a-new-subcommand-check-for-existing-
@@ -54,333 +44,12 @@ export function registerEvolutionCommands(program, io) {
         program
             .command('evolution')
             .description('Darwin-style ratchet: propose / evaluate / revert / status (spec §6)');
-    // peaks evolution propose
-    addJsonOption(evolution
-        .command('propose')
-        .description("M4: persist a new evolution proposal. Enforces AC-8 (single object + single dimension). The proposal's verdict starts at 'needs-user-decision' until the scoring + skeptic step lands.")
-        .requiredOption('--target <kind:id>', "target asset, e.g. 'loop:loop-onboarding-research' or 'bee:42'")
-        .requiredOption('--dimension <name>', "single optimization dimension (e.g. 'clarity')")
-        .requiredOption('--before-score <n>', 'score on the 0..10 scale BEFORE the change')
-        .requiredOption('--after-score <n>', 'score on the 0..10 scale AFTER the change (LLM-claimed)')
-        .option('--delta-min <n>', `minimum score delta for promotion (default: 1.0; spec §6.1 #5)`, '1.0')
-        .requiredOption('--author <id>', 'author agent id (the LLM proposing the change)')
-        .option('--brief-pointer <ptr>', 'pointer to the evidence brief used in the recommendation (spec §4.7 / §4.4)')
-        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
-        try {
-            const target = parseTargetFlag(options.target);
-            if (!target) {
-                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target: options.target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const before = Number(options.beforeScore);
-            const after = Number(options.afterScore);
-            const deltaMin = Number(options.deltaMin);
-            if (!Number.isFinite(before) || before < 0 || before > 10) {
-                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_BEFORE_SCORE', `before_score must be a finite number in [0, 10] (got "${options.beforeScore}")`, { beforeScore: options.beforeScore }, ['Pass a numeric --before-score in [0, 10].']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (!Number.isFinite(after) || after < 0 || after > 10) {
-                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_AFTER_SCORE', `after_score must be a finite number in [0, 10] (got "${options.afterScore}")`, { afterScore: options.afterScore }, ['Pass a numeric --after-score in [0, 10].']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (!Number.isFinite(deltaMin) || deltaMin < 0) {
-                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_DELTA_MIN', `delta_min must be a finite number >= 0 (got "${options.deltaMin}")`, { deltaMin: options.deltaMin }, ['Pass a numeric --delta-min >= 0 (default 1.0).']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                // The CLI is allowed to bootstrap an empty .peaks dir so
-                // tests do not need a full peaks project.
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const svc = new EvolutionService(db);
-                const input = {
-                    target_kind: target.kind,
-                    target_release_id: target.id,
-                    optimization_dimension: options.dimension,
-                    before_snapshot: {},
-                    after_snapshot: { after_score: after },
-                    diff: {},
-                    before_score: before,
-                    after_score: after,
-                    score_delta_min: deltaMin,
-                    author_id: options.author,
-                    single_object: true,
-                    single_optimization_dimension: true,
-                    rubric: {},
-                    red_lines: [],
-                    source_traces: []
-                };
-                const proposal = svc.createProposal(input);
-                printResult(io, ok('evolution.propose', {
-                    proposal: {
-                        id: proposal.id,
-                        target_kind: proposal.target_kind,
-                        target_release_id: proposal.target_release_id,
-                        optimization_dimension: proposal.optimization_dimension,
-                        before_score: proposal.before_score,
-                        after_score: proposal.after_score,
-                        score_delta: proposal.score_delta,
-                        score_delta_min: proposal.score_delta_min,
-                        author_id: proposal.author_id,
-                        verdict: 'needs-user-decision',
-                        ...(options.briefPointer !== undefined
-                            ? { brief_pointer: options.briefPointer }
-                            : {})
-                    },
-                    nextActions: [
-                        `Run \`peaks evolution evaluate --proposal ${proposal.id} --evaluator <id> --skeptic <id> --evaluator-score <n> --json\` to score the proposal.`
-                    ]
-                }, [], []), options.json);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (err) {
-            if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail('evolution.propose', err.code, err.message, { findings: err.findings }, [
-                    'Re-shape the proposal per spec §6: single object, single dimension, separate scorer.',
-                    'If you intended a multi-object change, split it into multiple rounds.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('evolution.propose', 'EVOLUTION_PROPOSE_FAILED', getErrorMessage(err), {}, [
-                'Verify the target flag and dimension.'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // peaks evolution evaluate
-    addJsonOption(evolution
-        .command('evaluate')
-        .description("M4: score a proposal with an independent evaluator (AC-12/AC-13) and a regression skeptic (AC-14). The result is the FINAL verdict: 'keep' (after user confirmation), 'revert' (skeptic blocker or score delta below threshold), or 'needs-user-decision'.")
-        .requiredOption('--proposal <id>', 'proposal id returned by `peaks evolution propose`')
-        .requiredOption('--evaluator <id>', 'independent scorer id (MUST differ from --author; AC-10)')
-        .requiredOption('--skeptic <id>', 'regression skeptic id (MUST differ from --evaluator and --author; AC-12/AC-14)')
-        .requiredOption('--evaluator-score <n>', "the independent scorer's score on the 0..10 scale (LLM-derived; NOT the author's after_score)")
-        .option('--refute-paragraph <text>', "the independent scorer's one-paragraph refute (LLM-authored)", '')
-        .option('--risk-tag <tag>', 'add a risk tag emitted by the evaluator (repeatable)', collectRepeatable, [])
-        .option('--brief-pointer <ptr>', 'pointer to the evidence brief (spec §4.7 / §4.4)')
-        .option('--project <path>', 'project root (default: cwd)')).action(async (options) => {
-        try {
-            const score = Number(options.evaluatorScore);
-            if (!Number.isFinite(score) || score < 0 || score > 10) {
-                printResult(io, fail('evolution.evaluate', 'EVOLUTION_INVALID_EVALUATOR_SCORE', `evaluator-score must be a finite number in [0, 10] (got "${options.evaluatorScore}")`, { evaluatorScore: options.evaluatorScore }, ['Pass a numeric --evaluator-score in [0, 10].']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const svc = new EvolutionService(db);
-                const proposal = svc.read(options.proposal);
-                if (!proposal) {
-                    printResult(io, fail('evolution.evaluate', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id and that you have run `peaks evolution propose` first.']), options.json);
-                    process.exitCode = 1;
-                    return;
-                }
-                // The CLI runs the deterministic LLM stubs (no live LLM in
-                // M4). Real LLM wiring lands in M5.
-                const evaluatorResult = await runIndependentEvaluator(proposal.proposal);
-                // Force the CLI-supplied --evaluator-score to be the
-                // final score; the LLM stub's score is informational.
-                evaluatorResult.score = score;
-                if (options.refuteParagraph && options.refuteParagraph.length > 0) {
-                    evaluatorResult.refuteParagraph = options.refuteParagraph;
-                }
-                if (Array.isArray(options.riskTag) && options.riskTag.length > 0) {
-                    evaluatorResult.riskTags = [...evaluatorResult.riskTags, ...options.riskTag];
-                }
-                const evaluation = svc.score(options.proposal, {
-                    evaluator_id: options.evaluator,
-                    skeptic_id: options.skeptic,
-                    evaluator_result: evaluatorResult,
-                    skeptic_result: {
-                        driftRisks: [],
-                        overfitRisks: [],
-                        safetyRegressionRisks: []
-                    },
-                    ...(options.briefPointer !== undefined ? { brief_pointer: options.briefPointer } : {})
-                });
-                printResult(io, ok('evolution.evaluate', {
-                    proposalId: evaluation.id,
-                    verdict: evaluation.verdict,
-                    evaluator_id: evaluation.evaluator_id,
-                    skeptic_id: evaluation.skeptic_id,
-                    evaluator_result: evaluation.evaluator_result,
-                    skeptic_result: evaluation.skeptic_result,
-                    score_delta: evaluation.proposal.score_delta,
-                    score_delta_min: evaluation.proposal.score_delta_min,
-                    after_score: evaluation.proposal.after_score,
-                    nextActions: evaluation.verdict === 'needs-user-decision'
-                        ? [
-                            `User confirmation required. Run \`peaks evolution mark-keep --proposal ${evaluation.id} --user-confirmation <ptr> --json\` after the user picks "keep", OR \`peaks evolution revert --proposal ${evaluation.id} --json\`.`
-                        ]
-                        : evaluation.verdict === 'revert'
-                            ? [
-                                'Proposal reverted. Investigate the skeptic blocker or the score delta below threshold.'
-                            ]
-                            : [
-                                'Proposal kept. The target asset remains unchanged on disk; full promotion lands in a later slice.'
-                            ]
-                }, [], []), options.json);
-                if (evaluation.verdict === 'revert')
-                    process.exitCode = 1;
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (err) {
-            if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail('evolution.evaluate', err.code, err.message, { findings: err.findings }, [
-                    'Re-shape per spec §6: evaluator and skeptic MUST be separate from the author; the score delta MUST be >= score_delta_min for keep.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('evolution.evaluate', 'EVOLUTION_EVALUATE_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id and the evaluator / skeptic ids.']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // peaks evolution mark-keep — explicit user confirmation.
-    addJsonOption(evolution
-        .command('mark-keep')
-        .description('M4: explicit user-confirmed `keep` verdict. Requires --user-confirmation <ptr> and a score_delta >= score_delta_min (AC-11/AC-15).')
-        .requiredOption('--proposal <id>', 'proposal id')
-        .option('--user-confirmation <ptr>', 'pointer to the user choice record (AC-15) — omit to surface the EVOLUTION_MISSING_USER_CONFIRMATION service-layer error')
-        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
-        try {
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const svc = new EvolutionService(db);
-                const updated = svc.markVerdict(options.proposal, 'keep', options.userConfirmation);
-                if (!updated) {
-                    printResult(io, fail('evolution.mark-keep', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
-                    process.exitCode = 1;
-                    return;
-                }
-                printResult(io, ok('evolution.mark-keep', {
-                    proposalId: updated.id,
-                    verdict: updated.verdict,
-                    user_confirmation_pointer: updated.user_confirmation_pointer ?? null,
-                    score_delta: updated.proposal.score_delta,
-                    score_delta_min: updated.proposal.score_delta_min
-                }, [], []), options.json);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (err) {
-            if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail('evolution.mark-keep', err.code, err.message, { findings: err.findings }, [
-                    'Re-shape the proposal or the score so score_delta >= score_delta_min.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('evolution.mark-keep', 'EVOLUTION_MARK_KEEP_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // peaks evolution revert
-    addJsonOption(evolution
-        .command('revert')
-        .description('M4: revert a proposal (universal recovery; spec §6.1 #8). Always allowed; the user may supply --user-confirmation for audit.')
-        .requiredOption('--proposal <id>', 'proposal id')
-        .option('--user-confirmation <ptr>', 'optional pointer to the user choice record')
-        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
-        try {
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const svc = new EvolutionService(db);
-                const updated = svc.revert(options.proposal, options.userConfirmation);
-                if (!updated) {
-                    printResult(io, fail('evolution.revert', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
-                    process.exitCode = 1;
-                    return;
-                }
-                printResult(io, ok('evolution.revert', {
-                    proposalId: updated.id,
-                    verdict: updated.verdict,
-                    user_confirmation_pointer: updated.user_confirmation_pointer ?? null
-                }, [], []), options.json);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (err) {
-            printResult(io, fail('evolution.revert', 'EVOLUTION_REVERT_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // peaks evolution status
-    addJsonOption(evolution
-        .command('status')
-        .description('M4: read the status snapshot for a target (counts of evaluations by verdict + latest evaluation id).')
-        .requiredOption('--target <kind:id>', "target asset, e.g. 'loop:loop-onboarding-research'")
-        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
-        try {
-            const target = parseTargetFlag(options.target);
-            if (!target) {
-                printResult(io, fail('evolution.status', 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target: options.target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const svc = new EvolutionService(db);
-                const status = svc.status({
-                    target_kind: target.kind,
-                    target_release_id: target.id
-                });
-                printResult(io, ok('evolution.status', status, [], []), options.json);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (err) {
-            printResult(io, fail('evolution.status', 'EVOLUTION_STATUS_FAILED', getErrorMessage(err), { target: options.target }, ['Verify the target flag.']), options.json);
-            process.exitCode = 1;
-        }
-    });
+    registerProposeCommand(evolution, io);
+    registerEvaluateCommand(evolution, io);
+    registerMarkKeepCommand(evolution, io);
+    registerRevertCommand(evolution, io);
+    registerStatusCommand(evolution, io);
     // Suppress unused-var warnings for the dirname import; it is
     // reserved for the M5 path-pointer materialization.
     void dirname;
 }
-/**
- * Helper: collect repeatable `--risk-tag` values into an array.
- * Commander's `collect` is not always available; we read
- * `previous` from the default value.
- */
-function collectRepeatable(value, previous) {
-    if (Array.isArray(previous))
-        return [...previous, value];
-    return [value];
-}

package/dist/cli/commands/evolution-evaluate-command.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `peaks evolution evaluate` — M4 / spec §6 / §7.4.
+ * Split out of `evolution-commands.ts`: the option surface, the
+ * envelope keys, the error codes and the exit-code sites are
+ * unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/** The `--options` Commander hands to the `evaluate` action. */
+export interface EvaluateOptions {
+    proposal: string;
+    evaluator: string;
+    skeptic: string;
+    evaluatorScore: string;
+    refuteParagraph?: string;
+    riskTag: string[];
+    briefPointer?: string;
+    project?: string;
+    json?: boolean;
+}
+/** The `evaluate` action body. */
+export declare function runEvaluate(options: EvaluateOptions, io: ProgramIO): Promise<void>;
+/** Register `peaks evolution evaluate` on the `evolution` parent. */
+export declare function registerEvaluateCommand(evolution: Command, io: ProgramIO): void;