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

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

@@ -0,0 +1,169 @@
+/**
+ * peaks bee * CLI — M7 (spec §7A.2 / §10 RL-9 / AC-24 / AC-25 / AC-26).
+ *
+ * Adds:
+ *   peaks bee export --bee <id> --out <path.tar.gz>
+ *   peaks bee import --in <path.tar.gz> [--as <bee-name>]
+ *
+ * The bee-side counterparts of the loop-side `peaks loop export /
+ * import`. Same hard rules:
+ *
+ *   - source `shareable=false` blocks export at the CLI layer.
+ *   - bundle lands as `candidate`; promotion to `stable` requires
+ *     an `evolution_evaluation` row with an independent
+ *     `evaluator_id` (see `peaks evolution evaluate`).
+ *
+ * The bee bundle captures the bee's inline manifest/segment/file/change
+ * rows so the receiver can re-materialize the full bee + any
+ * loop↔bee relations that referenced it + any evidence briefs that
+ * touched it.
+ *
+ * The `peaks skill sediment export / import` alias lives in
+ * `src/cli/commands/skill-sediment.ts` for one release cycle.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError, } from '../../services/share/bundle-writer.js';
+import { readBundle, BundleMajorVersionMismatchError, BundleSchemaVersionsMismatchError, BundleImportToStableForbiddenError, BundleMalformedError, } from '../../services/share/bundle-reader.js';
+export function registerBeeCommands(program, io) {
+    // Reuse the existing `bee` parent if one is registered; the
+    // add-a-new-subcommand-check-for-existing-top-level-first rule.
+    const existing = program.commands.find((c) => c.name() === 'bee');
+    const bee = existing ?? program
+        .command('bee')
+        .description('M7: peaks bee export / import (spec §7A.2 / §10 RL-9)');
+    // ---------- peaks bee export ----------
+    addJsonOption(bee
+        .command('export')
+        .description("M7: export a bee_release as a peaks.bundle/1 tarball (spec §7A.2). Refuses to export when shareable=false.")
+        .requiredOption('--bee <id>', 'bee_release numeric id (use `peaks asset status --bee <name>` to find the id)')
+        .requiredOption('--out <path>', 'output .tar.gz path')
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
+        const asJson = options.json === true;
+        const beeId = Number(options.bee);
+        if (!Number.isInteger(beeId) || beeId <= 0) {
+            printResult(io, fail('bee.export', 'INVALID_BEE_ID', `--bee must be a positive integer (got '${options.bee}')`, { bee: options.bee }, [
+                'Re-run with --bee <numeric-id>.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        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 result = writeBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    kind: 'bee',
+                    id: beeId,
+                    outPath: options.out,
+                });
+                printResult(io, ok('bee.export', {
+                    outPath: result.outPath,
+                    kind: result.kind,
+                    assetId: result.assetId,
+                    importedAs: 'candidate',
+                }, [], [
+                    `Receiver must run \`peaks bee import --in ${result.outPath}\` to land this bundle, then run an independent evolution_evaluation before any promote.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleNotShareableError) {
+                printResult(io, fail('bee.export', error.code, error.message, { bee: options.bee }, [
+                    'Set shareable=true on the bee_release row, or stop sharing.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleAssetNotFoundError) {
+                printResult(io, fail('bee.export', error.code, error.message, { bee: options.bee }, [
+                    'Verify the bee id with `peaks asset status --bee <name>`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('bee.export', 'BEE_EXPORT_FAILED', getErrorMessage(error), { bee: options.bee }, ['Verify --bee id and --out path.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+    // ---------- peaks bee import ----------
+    addJsonOption(bee
+        .command('import')
+        .description('M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / AC-25 / AC-26).')
+        .requiredOption('--in <path>', 'input .tar.gz path')
+        .option('--as <name>', 'optional rename for the bee name when landing')
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
+        const asJson = options.json === true;
+        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 result = readBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    inPath: options.in,
+                    ...(options.as !== undefined ? { asName: options.as } : {}),
+                });
+                printResult(io, ok('bee.import', {
+                    assetId: result.assetId,
+                    kind: result.kind,
+                    importedAs: result.importedAs,
+                    warnings: result.warnings,
+                    evidenceBriefCount: result.evidenceBriefCount,
+                }, result.warnings, [
+                    `Run an independent evaluation against this release before promoting; peaks bee promote refuses without an evolution_evaluation row.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleMajorVersionMismatchError) {
+                printResult(io, fail('bee.import', error.code, error.message, { receivedMajor: error.receivedMajor }, [
+                    'Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleSchemaVersionsMismatchError) {
+                printResult(io, fail('bee.import', error.code, error.message, {}, [
+                    'Source bundle did not declare the canonical schema versions; refuse the bundle.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleImportToStableForbiddenError) {
+                printResult(io, fail('bee.import', error.code, error.message, {}, [
+                    'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleMalformedError) {
+                printResult(io, fail('bee.import', error.code, error.message, { inPath: options.in }, [
+                    'Re-export from the source via `peaks bee export`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('bee.import', 'BEE_IMPORT_FAILED', getErrorMessage(error), { inPath: options.in }, ['Verify the bundle path and integrity.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,27 @@
+/**
+ * peaks evolution * CLI — M4 / spec §4.4 / §6 / §7.4
+ *
+ * Adds the Darwin-style ratchet CLI surface:
+ *
+ *   peaks evolution propose --target <kind:id> --dimension <name> \
+ *     --before-score <n> --after-score <n> [--delta-min <n>] \
+ *     --author <id> [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution evaluate --proposal <id> \
+ *     --evaluator <id> --skeptic <id> \
+ *     --evaluator-score <n> [--refute-paragraph <text>] \
+ *     [--risk-tag <tag>]... [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution revert --proposal <id> [--user-confirmation <ptr>] [--project <root>] [--json]
+ *   peaks evolution status [--target <kind:id>] [--project <root>] [--json]
+ *
+ * Each verb prints a structured JSON envelope (`printResult` with
+ * `asJson=true`). The CLI is a thin shim around EvolutionService +
+ * the two runner modules. Author / evaluator / skeptic identities
+ * are LLM-supplied; the user is NEVER asked to type them.
+ *
+ * Defense in depth: the EvolutionService enforces the ratchet
+ * rules (AC-8 / AC-10 / AC-11); the CLI only translates flags
+ * into the service payload.
+ */
+import { Command } from "commander";
+import { type ProgramIO } from "../cli-helpers.js";
+export declare function registerEvolutionCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,393 @@
+/**
+ * peaks evolution * CLI — M4 / spec §4.4 / §6 / §7.4
+ *
+ * Adds the Darwin-style ratchet CLI surface:
+ *
+ *   peaks evolution propose --target <kind:id> --dimension <name> \
+ *     --before-score <n> --after-score <n> [--delta-min <n>] \
+ *     --author <id> [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution evaluate --proposal <id> \
+ *     --evaluator <id> --skeptic <id> \
+ *     --evaluator-score <n> [--refute-paragraph <text>] \
+ *     [--risk-tag <tag>]... [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution revert --proposal <id> [--user-confirmation <ptr>] [--project <root>] [--json]
+ *   peaks evolution status [--target <kind:id>] [--project <root>] [--json]
+ *
+ * Each verb prints a structured JSON envelope (`printResult` with
+ * `asJson=true`). The CLI is a thin shim around EvolutionService +
+ * the two runner modules. Author / evaluator / skeptic identities
+ * are LLM-supplied; the user is NEVER asked to type them.
+ *
+ * Defense in depth: the EvolutionService enforces the ratchet
+ * rules (AC-8 / AC-10 / AC-11); the CLI only translates flags
+ * into the service payload.
+ */
+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 "../../shared/result.js";
+/**
+ * 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 };
+}
+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-
+    // top-level-first rule requires this guard.
+    const existing = program.commands.find((c) => c.name() === "evolution");
+    const evolution = existing ?? 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;
+        }
+    });
+    // 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/src/cli/commands/loop-commands.d.ts

@@ -1,20 +1,26 @@
 /**
- * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
+ * peaks loop * CLI (Slice #14 + M7 add).
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §5.4
- * Slice #14, ships 5 sub-features:
+ * Slices:
+ *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
+ *     detect-pattern / check-consistency / peaks goal compose.
  *
- *   14.1 peaks loop distill          — extract patterns from past sessions
- *                                       (delegates to peaks memory extract)
- *   14.2 peaks loop preflight        — pre-run sanity checks (placeholder)
- *   14.3 peaks loop detect-pattern   — find repeating patterns (placeholder)
- *   14.4 peaks loop check-consistency — verify state consistency (placeholder)
- *   14.5 peaks goal compose          — autonomous goal composition (placeholder;
- *                                       requires IDE adapter goalCommand capability
- *                                       per Slice #0.7)
+ *   M7 (2026-07-07 spec §7A.2):
+ *     peaks loop export --loop <id> --out <path.tar.gz>
+ *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
  *
- * The 4 placeholders emit a clear nextActions list; the LLM-side UX
- * layer composes the actual runtime today.
+ * `peaks loop export` reads the source loop_release + relations +
+ * related bees + evidence briefs and emits a `peaks.bundle/1`
+ * tar.gz. Hard-blocks when the source has `shareable=false`.
+ *
+ * `peaks loop import` extracts a bundle, validates
+ * format_version_major=1, and lands the release as `candidate`
+ * (mandatory landing status per spec §7A.2). The receiver must run
+ * an independent evaluation before promoting to `stable`.
+ *
+ * The existing 14.x commands are kept under the same `loop` parent;
+ * M7 only ADDs export / import — it does not modify the existing
+ * surface.
  */
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';