peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,138 @@
+import { EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { runIndependentEvaluator } from '../../services/evolution/independent-evaluator-runner.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { collectRepeatable, isScoreInRange, proposalNotFoundFailure, reportFailure, reportIntegrityFailure, scoreRangeFailure, withEvolutionDbAsync } from './evolution-command-shared.js';
+const 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'.";
+/** The `svc.score(...)` argument object, built from the CLI flags. */
+function evaluateScoreArgs(options, evaluatorResult) {
+    return {
+        evaluator_id: options.evaluator,
+        skeptic_id: options.skeptic,
+        evaluator_result: evaluatorResult,
+        skeptic_result: {
+            driftRisks: [],
+            overfitRisks: [],
+            safetyRegressionRisks: []
+        },
+        ...(options.briefPointer !== undefined ? { brief_pointer: options.briefPointer } : {})
+    };
+}
+/** The `nextActions` the final verdict implies (unchanged wording). */
+function evaluateNextActions(evaluation) {
+    if (evaluation.verdict === 'needs-user-decision') {
+        return [
+            `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\`.`
+        ];
+    }
+    if (evaluation.verdict === 'revert') {
+        return [
+            'Proposal reverted. Investigate the skeptic blocker or the score delta below threshold.'
+        ];
+    }
+    return [
+        'Proposal kept. The target asset remains unchanged on disk; full promotion lands in a later slice.'
+    ];
+}
+/** The `ok(...)` `data` payload for a completed evaluation. */
+function evaluateEnvelopeData(evaluation) {
+    return {
+        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: evaluateNextActions(evaluation)
+    };
+}
+/** Print the evaluate failure envelope for `err` and set exit code 1. */
+function reportEvaluateFailure(io, err, options) {
+    if (err instanceof EvolutionIntegrityError) {
+        reportIntegrityFailure({
+            io,
+            command: 'evolution.evaluate',
+            error: err,
+            nextActions: [
+                'Re-shape per spec §6: evaluator and skeptic MUST be separate from the author; the score delta MUST be >= score_delta_min for keep.'
+            ],
+            asJson: options.json
+        });
+        return;
+    }
+    reportFailure({
+        io,
+        command: 'evolution.evaluate',
+        code: 'EVOLUTION_EVALUATE_FAILED',
+        error: err,
+        data: { proposalId: options.proposal },
+        nextActions: ['Verify the proposal id and the evaluator / skeptic ids.'],
+        asJson: options.json
+    });
+}
+/** The service-side half of the `evaluate` action, inside the open DB scope. */
+async function evaluateWithinService(svc, options, score, io) {
+    const evaluation = svc.read(options.proposal);
+    if (!evaluation) {
+        printResult(io, proposalNotFoundFailure('evolution.evaluate', 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(evaluation.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 scored = svc.score(options.proposal, evaluateScoreArgs(options, evaluatorResult));
+    printResult(io, ok('evolution.evaluate', evaluateEnvelopeData(scored), [], []), options.json);
+    if (scored.verdict === 'revert')
+        process.exitCode = 1;
+}
+/** The `evaluate` action body. */
+export async function runEvaluate(options, io) {
+    try {
+        const score = Number(options.evaluatorScore);
+        if (!isScoreInRange(score)) {
+            printResult(io, scoreRangeFailure({
+                command: 'evolution.evaluate',
+                code: 'EVOLUTION_INVALID_EVALUATOR_SCORE',
+                label: 'evaluator-score',
+                flag: '--evaluator-score',
+                key: 'evaluatorScore',
+                raw: options.evaluatorScore
+            }), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        await withEvolutionDbAsync(options.project, (svc) => evaluateWithinService(svc, options, score, io));
+    }
+    catch (err) {
+        reportEvaluateFailure(io, err, options);
+    }
+}
+/** Register `peaks evolution evaluate` on the `evolution` parent. */
+export function registerEvaluateCommand(evolution, io) {
+    addJsonOption(evolution
+        .command('evaluate')
+        .description(EVALUATE_DESCRIPTION)
+        .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((options) => runEvaluate(options, io));
+}

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

@@ -0,0 +1,23 @@
+/**
+ * `peaks evolution propose` — M4 / spec §4.4 / §6.1 #5. Split out of
+ * `evolution-commands.ts`: the option surface, the envelope keys 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 `propose` action. */
+export interface ProposeOptions {
+    target: string;
+    dimension: string;
+    beforeScore: string;
+    afterScore: string;
+    deltaMin: string;
+    author: string;
+    briefPointer?: string;
+    project?: string;
+    json?: boolean;
+}
+/** The `propose` action body. */
+export declare function runPropose(options: ProposeOptions, io: ProgramIO): void;
+/** Register `peaks evolution propose` on the `evolution` parent. */
+export declare function registerProposeCommand(evolution: Command, io: ProgramIO): void;

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

@@ -0,0 +1,145 @@
+import { EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { deltaMinFailure, invalidTargetFailure, isScoreInRange, parseTargetFlag, reportFailure, reportIntegrityFailure, scoreRangeFailure, withEvolutionDb } from './evolution-command-shared.js';
+const 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.";
+/**
+ * Validate `--target`, `--before-score`, `--after-score` and
+ * `--delta-min` in that order, returning the first failure envelope
+ * the original action would have printed.
+ */
+function preparePropose(options) {
+    const target = parseTargetFlag(options.target);
+    if (!target)
+        return { ok: false, failure: invalidTargetFailure('evolution.propose', options.target) };
+    const before = Number(options.beforeScore);
+    if (!isScoreInRange(before)) {
+        return {
+            ok: false,
+            failure: scoreRangeFailure({
+                command: 'evolution.propose',
+                code: 'EVOLUTION_INVALID_BEFORE_SCORE',
+                label: 'before_score',
+                flag: '--before-score',
+                key: 'beforeScore',
+                raw: options.beforeScore
+            })
+        };
+    }
+    const after = Number(options.afterScore);
+    if (!isScoreInRange(after)) {
+        return {
+            ok: false,
+            failure: scoreRangeFailure({
+                command: 'evolution.propose',
+                code: 'EVOLUTION_INVALID_AFTER_SCORE',
+                label: 'after_score',
+                flag: '--after-score',
+                key: 'afterScore',
+                raw: options.afterScore
+            })
+        };
+    }
+    const deltaMin = Number(options.deltaMin);
+    if (!Number.isFinite(deltaMin) || deltaMin < 0) {
+        return { ok: false, failure: deltaMinFailure('evolution.propose', options.deltaMin) };
+    }
+    return { ok: true, target, before, after, deltaMin };
+}
+/** The `EvolutionProposalInput` the service receives. */
+function proposeInput(prep, options) {
+    return {
+        target_kind: prep.target.kind,
+        target_release_id: prep.target.id,
+        optimization_dimension: options.dimension,
+        before_snapshot: {},
+        after_snapshot: { after_score: prep.after },
+        diff: {},
+        before_score: prep.before,
+        after_score: prep.after,
+        score_delta_min: prep.deltaMin,
+        author_id: options.author,
+        single_object: true,
+        single_optimization_dimension: true,
+        rubric: {},
+        red_lines: [],
+        source_traces: []
+    };
+}
+/** The `ok(...)` `data` payload for a freshly created proposal. */
+function proposeEnvelopeData(proposal, options) {
+    return {
+        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.`
+        ]
+    };
+}
+/** Print the propose failure envelope for `err` and set exit code 1. */
+function reportProposeFailure(io, err, options) {
+    if (err instanceof EvolutionIntegrityError) {
+        reportIntegrityFailure({
+            io,
+            command: 'evolution.propose',
+            error: err,
+            nextActions: [
+                '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.'
+            ],
+            asJson: options.json
+        });
+        return;
+    }
+    reportFailure({
+        io,
+        command: 'evolution.propose',
+        code: 'EVOLUTION_PROPOSE_FAILED',
+        error: err,
+        data: {},
+        nextActions: ['Verify the target flag and dimension.'],
+        asJson: options.json
+    });
+}
+/** The `propose` action body. */
+export function runPropose(options, io) {
+    try {
+        const prep = preparePropose(options);
+        if (!prep.ok) {
+            printResult(io, prep.failure, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const input = proposeInput(prep, options);
+        const proposal = withEvolutionDb(options.project, (svc) => svc.createProposal(input));
+        printResult(io, ok('evolution.propose', proposeEnvelopeData(proposal, options), [], []), options.json);
+    }
+    catch (err) {
+        reportProposeFailure(io, err, options);
+    }
+}
+/** Register `peaks evolution propose` on the `evolution` parent. */
+export function registerProposeCommand(evolution, io) {
+    addJsonOption(evolution
+        .command('propose')
+        .description(PROPOSE_DESCRIPTION)
+        .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) => runPropose(options, io));
+}

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

@@ -0,0 +1,17 @@
+/**
+ * `peaks evolution status` — M4 / spec §4.4. Split out of
+ * `evolution-commands.ts`: the option surface, the envelope 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 `status` action. */
+export interface StatusOptions {
+    target: string;
+    project?: string;
+    json?: boolean;
+}
+/** The `status` action body. */
+export declare function runStatus(options: StatusOptions, io: ProgramIO): void;
+/** Register `peaks evolution status` on the `evolution` parent. */
+export declare function registerStatusCommand(evolution: Command, io: ProgramIO): void;

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

@@ -0,0 +1,41 @@
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { invalidTargetFailure, parseTargetFlag, reportFailure, withEvolutionDb } from './evolution-command-shared.js';
+const STATUS_DESCRIPTION = 'M4: read the status snapshot for a target (counts of evaluations by verdict + latest evaluation id).';
+/** The `{ target_kind, target_release_id }` argument `svc.status` takes. */
+function statusTarget(target) {
+    return { target_kind: target.kind, target_release_id: target.id };
+}
+/** The `status` action body. */
+export function runStatus(options, io) {
+    try {
+        const target = parseTargetFlag(options.target);
+        if (!target) {
+            printResult(io, invalidTargetFailure('evolution.status', options.target), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const targetArg = statusTarget(target);
+        const status = withEvolutionDb(options.project, (svc) => svc.status(targetArg));
+        printResult(io, ok('evolution.status', status, [], []), options.json);
+    }
+    catch (err) {
+        reportFailure({
+            io,
+            command: 'evolution.status',
+            code: 'EVOLUTION_STATUS_FAILED',
+            error: err,
+            data: { target: options.target },
+            nextActions: ['Verify the target flag.'],
+            asJson: options.json
+        });
+    }
+}
+/** Register `peaks evolution status` on the `evolution` parent. */
+export function registerStatusCommand(evolution, io) {
+    addJsonOption(evolution
+        .command('status')
+        .description(STATUS_DESCRIPTION)
+        .requiredOption('--target <kind:id>', "target asset, e.g. 'loop:loop-onboarding-research'")
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => runStatus(options, io));
+}

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

@@ -0,0 +1,30 @@
+/**
+ * `peaks evolution mark-keep` + `peaks evolution revert` — the two
+ * explicit-verdict verbs (spec §6.1 #8). Split out of
+ * `evolution-commands.ts`: the option surfaces, the envelope keys 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 `mark-keep` action. */
+export interface MarkKeepOptions {
+    proposal: string;
+    userConfirmation: string;
+    project?: string;
+    json?: boolean;
+}
+/** The `--options` Commander hands to the `revert` action. */
+export interface RevertOptions {
+    proposal: string;
+    userConfirmation?: string;
+    project?: string;
+    json?: boolean;
+}
+/** The `mark-keep` action body. */
+export declare function runMarkKeep(options: MarkKeepOptions, io: ProgramIO): void;
+/** The `revert` action body. */
+export declare function runRevert(options: RevertOptions, io: ProgramIO): void;
+/** Register `peaks evolution mark-keep` on the `evolution` parent. */
+export declare function registerMarkKeepCommand(evolution: Command, io: ProgramIO): void;
+/** Register `peaks evolution revert` on the `evolution` parent. */
+export declare function registerRevertCommand(evolution: Command, io: ProgramIO): void;

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

@@ -0,0 +1,100 @@
+import { EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { proposalNotFoundFailure, reportFailure, reportIntegrityFailure, withEvolutionDb } from './evolution-command-shared.js';
+const MARK_KEEP_DESCRIPTION = 'M4: explicit user-confirmed `keep` verdict. Requires --user-confirmation <ptr> and a score_delta >= score_delta_min (AC-11/AC-15).';
+const REVERT_DESCRIPTION = 'M4: revert a proposal (universal recovery; spec §6.1 #8). Always allowed; the user may supply --user-confirmation for audit.';
+/** Print the mark-keep failure envelope for `err` and set exit code 1. */
+function reportMarkKeepFailure(io, err, options) {
+    if (err instanceof EvolutionIntegrityError) {
+        reportIntegrityFailure({
+            io,
+            command: 'evolution.mark-keep',
+            error: err,
+            nextActions: ['Re-shape the proposal or the score so score_delta >= score_delta_min.'],
+            asJson: options.json
+        });
+        return;
+    }
+    reportFailure({
+        io,
+        command: 'evolution.mark-keep',
+        code: 'EVOLUTION_MARK_KEEP_FAILED',
+        error: err,
+        data: { proposalId: options.proposal },
+        nextActions: ['Verify the proposal id.'],
+        asJson: options.json
+    });
+}
+/** The `ok(...)` `data` payload for a confirmed `keep`. */
+function markKeepEnvelopeData(updated) {
+    return {
+        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
+    };
+}
+/** The `mark-keep` action body. */
+export function runMarkKeep(options, io) {
+    try {
+        const updated = withEvolutionDb(options.project, (svc) => svc.markVerdict(options.proposal, 'keep', options.userConfirmation));
+        if (!updated) {
+            printResult(io, proposalNotFoundFailure('evolution.mark-keep', options.proposal, [
+                'Verify the proposal id.'
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('evolution.mark-keep', markKeepEnvelopeData(updated), [], []), options.json);
+    }
+    catch (err) {
+        reportMarkKeepFailure(io, err, options);
+    }
+}
+/** The `revert` action body. */
+export function runRevert(options, io) {
+    try {
+        const updated = withEvolutionDb(options.project, (svc) => svc.revert(options.proposal, options.userConfirmation));
+        if (!updated) {
+            printResult(io, proposalNotFoundFailure('evolution.revert', 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);
+    }
+    catch (err) {
+        reportFailure({
+            io,
+            command: 'evolution.revert',
+            code: 'EVOLUTION_REVERT_FAILED',
+            error: err,
+            data: { proposalId: options.proposal },
+            nextActions: ['Verify the proposal id.'],
+            asJson: options.json
+        });
+    }
+}
+/** Register `peaks evolution mark-keep` on the `evolution` parent. */
+export function registerMarkKeepCommand(evolution, io) {
+    addJsonOption(evolution
+        .command('mark-keep')
+        .description(MARK_KEEP_DESCRIPTION)
+        .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) => runMarkKeep(options, io));
+}
+/** Register `peaks evolution revert` on the `evolution` parent. */
+export function registerRevertCommand(evolution, io) {
+    addJsonOption(evolution
+        .command('revert')
+        .description(REVERT_DESCRIPTION)
+        .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) => runRevert(options, io));
+}

package/dist/cli/commands/final-review-command-envelopes.d.ts

@@ -0,0 +1,44 @@
+import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/** The two inputs a refusal envelope names, plus why it was refused. */
+export type PrepareRefusal = {
+    readonly rid: string;
+    readonly code: string;
+    readonly message: string;
+    readonly sessionId: string;
+    readonly auditGoalPath: string;
+    readonly nextActions: string[];
+};
+/** Print one refusal envelope and mark the process failed. */
+export declare function emitPrepareFailure(io: ProgramIO, json: boolean | undefined, refusal: PrepareRefusal, missingEnv?: readonly string[]): void;
+/** Where a resolved run reads its audit goal from. */
+export type PrepareGoalPath = {
+    readonly sessionId: string;
+    readonly auditGoalPath: string;
+};
+/**
+ * Stub path: surface a structured "scaffold ready" envelope.
+ *
+ * The service is NOT called here — the stub runner answers the audit-goal
+ * shape, not the 4-dim review shape, so running it through
+ * `prepareFinalReview()` would only manufacture a malformed review. The
+ * envelope confirms the route is wired end-to-end and reports the audit-goal
+ * path the service WOULD read.
+ */
+export declare function emitStubEnvelope(io: ProgramIO, rid: string, goal: PrepareGoalPath, json: boolean | undefined): void;
+/** The success envelope of a real-provider run. */
+export declare function emitReviewEnvelope(io: ProgramIO, result: {
+    readonly rid: string;
+    readonly goal: PrepareGoalPath;
+    readonly model: string;
+    readonly review: FinalReviewOutput;
+    readonly json: boolean | undefined;
+}): void;
+/**
+ * Map a thrown error to the CLI's error code. The LLM-layer errors already
+ * carry codes precise enough to act on (`LLM_CREDENTIAL_MISSING`,
+ * `LLM_REQUEST_FAILED`, …), so they are passed through rather than flattened
+ * into one opaque failure.
+ */
+export declare function finalReviewErrorCode(error: unknown): string;
+export declare function finalReviewNextActions(code: string): string[];

package/dist/cli/commands/final-review-command-envelopes.js

@@ -0,0 +1,100 @@
+// src/cli/commands/final-review-command-envelopes.ts
+//
+// Every envelope `peaks prepare-final-review` can print, and the error-code
+// mapping behind the failure one. Split out of `final-review-commands.ts`; the
+// codes, messages, data fields and next-action strings are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { IncompleteFinalReviewError } from '../../services/final-review/final-review-service.js';
+import { LlmBindingError, LlmRequestError } from '../../services/llm/anthropic-runner.js';
+import { printResult } from '../cli-helpers.js';
+import { emptyFinalReviewData } from './final-review-command-shared.js';
+/** Print one refusal envelope and mark the process failed. */
+export function emitPrepareFailure(io, json, refusal, missingEnv) {
+    printResult(io, fail('final-review.prepare', refusal.code, refusal.message, emptyFinalReviewData(refusal.rid, refusal.sessionId, refusal.auditGoalPath, missingEnv), refusal.nextActions), json ?? false);
+    process.exitCode = 1;
+}
+/**
+ * Stub path: surface a structured "scaffold ready" envelope.
+ *
+ * The service is NOT called here — the stub runner answers the audit-goal
+ * shape, not the 4-dim review shape, so running it through
+ * `prepareFinalReview()` would only manufacture a malformed review. The
+ * envelope confirms the route is wired end-to-end and reports the audit-goal
+ * path the service WOULD read.
+ */
+export function emitStubEnvelope(io, rid, goal, json) {
+    const data = {
+        status: 'scaffold-only',
+        rid,
+        sessionId: goal.sessionId,
+        auditGoalPath: goal.auditGoalPath,
+        serviceWired: true,
+        providerBinding: 'stub'
+    };
+    const envelope = ok('final-review.prepare', data, [], [
+        'Stub provider: no 4-dim review was performed. This envelope only proves the route is wired and reachable.',
+        `Audit-goal file is present at: ${goal.auditGoalPath}`,
+        'Re-run with `--llm-provider anthropic` to produce a real review.'
+    ]);
+    printResult(io, envelope, json ?? false);
+}
+/** The success envelope of a real-provider run. */
+export function emitReviewEnvelope(io, result) {
+    const { rid, goal, model, review, json } = result;
+    const data = {
+        status: 'review-complete',
+        rid,
+        sessionId: goal.sessionId,
+        auditGoalPath: goal.auditGoalPath,
+        serviceWired: true,
+        providerBinding: 'anthropic-messages-api',
+        model,
+        review
+    };
+    const envelope = ok('final-review.prepare', data, review.allPass
+        ? []
+        : [
+            `Dimensions needing human attention: ${review.needsAttention.join(', ') || 'none flagged'}.`
+        ], [
+        `4-dim review produced by anthropic-messages-api (model: ${model}).`,
+        `allPass: ${String(review.allPass)}.`
+    ]);
+    printResult(io, envelope, json ?? false);
+}
+/**
+ * Map a thrown error to the CLI's error code. The LLM-layer errors already
+ * carry codes precise enough to act on (`LLM_CREDENTIAL_MISSING`,
+ * `LLM_REQUEST_FAILED`, …), so they are passed through rather than flattened
+ * into one opaque failure.
+ */
+export function finalReviewErrorCode(error) {
+    if (error instanceof LlmBindingError ||
+        error instanceof LlmRequestError ||
+        error instanceof IncompleteFinalReviewError) {
+        return error.code;
+    }
+    return 'FINAL_REVIEW_FAILED';
+}
+export function finalReviewNextActions(code) {
+    switch (code) {
+        case 'LLM_CREDENTIAL_MISSING':
+            return [
+                'Export ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) in the environment that launches peaks, then re-run.',
+                'For an offline scaffold instead of a review, re-run with `--llm-provider stub` — it performs NO review.'
+            ];
+        case 'LLM_MODEL_MISSING':
+            return [
+                'Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.'
+            ];
+        case 'LLM_REQUEST_FAILED':
+            return [
+                'Check ANTHROPIC_BASE_URL and network reachability, then re-run — a transport failure produces no review.'
+            ];
+        case 'INCOMPLETE_FINAL_REVIEW':
+            return [
+                'The LLM reply was not valid JSON or omitted a required dimension; re-run so the gate is never read as complete.'
+            ];
+        default:
+            return ['Re-run with `--llm-provider stub` to validate the CLI route without a real LLM.'];
+    }
+}