peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/cli/commands/_cli-error-envelope.js

@@ -0,0 +1,50 @@
+// Slice 015 — single source of truth for translating a thrown error from
+// the service layer (createRdSwarmPlan, createTechPlan, etc.) into a CLI
+// envelope code + user-facing nextActions.
+//
+// Lives under src/cli/commands/ (private to the CLI surface; underscore
+// prefix marks it as not-an-exported-CLI-subcommand per the project
+// convention). Used by every CLI handler that wraps a service call in a
+// try/catch — currently the four catches in workflow-commands.ts.
+//
+// Pre-slice behavior: all four catches emitted a fixed `INVALID_GOAL`
+// envelope code, regardless of the actual error class. Provider-config
+// failures (`ProviderNotConfiguredError`) were silently re-labelled as
+// "invalid goal", hiding real config issues behind a misleading hint.
+//
+// Post-slice behavior: the helper routes errors into one of three envelope
+// codes based on the runtime error class/message. The CLI catch sites
+// become data-only — they call the helper, then format the envelope.
+import { ProviderNotConfiguredError } from '../../services/config/model-routing.js';
+// Slice 015 risk A: goal-validation uses a substring match on the error
+// message thrown by `validatePlanningInput`. If validatePlanningInput's
+// message wording changes in a future slice, this branch silently
+// degrades into INTERNAL_ERROR. Mitigated by the helper's unit test
+// pinning the literal substring.
+// Slice 015 — match the goal-validation throw message. The current
+// `validatePlanningInput` literal is `"Goal must be non-empty"` (capital
+// G, "non-empty" with hyphen). The regex tolerates common wording
+// variations (`must be non-empty`, `must not be empty`, case-insensitive)
+// so a future message tweak still routes correctly; the unit test below
+// pins the *current* literal substring so any wording change fails loudly.
+const GOAL_VALIDATION_MESSAGE_RE = /goal.{0,4}(must be non-empty|must not be empty)/i;
+/**
+ * Map a thrown error into an envelope code + nextActions hint. Pure
+ * function — no IO, no state. Safe to call from any CLI handler.
+ *
+ * @param error - any value that may have been thrown (we only inspect
+ *                `.message` for goal-validation; everything else is
+ *                routed by class).
+ */
+export function mapServiceError(error) {
+    if (error instanceof ProviderNotConfiguredError) {
+        return {
+            code: 'INVALID_PROVIDERS',
+            nextActions: ['Configure provider model: peaks config provider <id> set --model <id>'],
+        };
+    }
+    if (error instanceof Error && GOAL_VALIDATION_MESSAGE_RE.test(error.message)) {
+        return { code: 'INVALID_GOAL', nextActions: ['Use a non-empty goal'] };
+    }
+    return { code: 'INTERNAL_ERROR', nextActions: ['See errorId for trace'] };
+}

package/dist/cli/commands/adapter-commands-s2a.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `peaks adapter *` — vendor adapter registry CLI surface.
+ *
+ * Slice S2-a of RD-2 (2026-07-08 session). Two subcommands:
+ *
+ *   list     — list registered user adapters (persisted at
+ *              `.peaks/runtime/adapters.json`).
+ *   register — register a new adapter. Vendor verb strings live in
+ *              the binary the user picks, NOT in peaks-loop source.
+ *
+ * This file coexists with the older `adapter-commands.ts` (slice
+ * 2026-07-04-cli-15a) which exposes `peaks skill adapter <verb>` —
+ * a different surface for skill materialization (resolveScratchDir /
+ * materialize / publish). The two surfaces do NOT collide because
+ * one is `peaks skill adapter` and the other is `peaks adapter`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface AdapterListOptions {
+    json?: boolean;
+    project?: string;
+}
+export interface AdapterRegisterOptions {
+    json?: boolean;
+    id?: string;
+    /** Display name override (defaults to the id). */
+    name?: string;
+    binary?: string;
+    /** Repeated --arg values. */
+    arg?: string[];
+    force?: boolean;
+    project?: string;
+}
+export declare function registerAdapterS2ACommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/adapter-commands-s2a.js

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+import { registryFileFor } from './runtime-commands.js';
+function resolveProjectRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerAdapterS2ACommands(program, io) {
+    const adapter = program
+        .command('adapter')
+        .description('Vendor adapter registry (user-registered, persisted to .peaks/runtime/adapters.json)');
+    // -----------------------------------------------------------------
+    // 1. peaks adapter list [--json] [--project <root>]
+    // -----------------------------------------------------------------
+    addJsonOption(adapter
+        .command('list')
+        .description('List user-registered vendor adapters')
+        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const file = registryFileFor(projectRoot);
+            const reg = new AdapterRegistry();
+            if (existsSync(file))
+                reg.load(file);
+            const records = reg.list();
+            printResult(io, ok('adapter.list', { projectRoot, file, records, count: records.length }, [], [
+                records.length === 0
+                    ? 'No adapters registered yet. Run `peaks adapter register --id <vendor> --binary <cmd>` to add one.'
+                    : `Run \`peaks runtime compact --via <id>\` to invoke a registered adapter.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('adapter.list', 'ADAPTER_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks adapter register --id <id> --binary <cmd> [--arg <a>]... [--force]
+    // -----------------------------------------------------------------
+    addJsonOption(adapter
+        .command('register')
+        .description('Register a new vendor adapter; persists to .peaks/runtime/adapters.json')
+        .requiredOption('--id <id>', 'vendor adapter id (lowercase, e.g. my-cli)')
+        .option('--name <name>', 'human-readable display name (defaults to <id>)')
+        .requiredOption('--binary <cmd>', 'binary name to invoke for compact (e.g. my-cli)')
+        .option('--arg <value>', 'extra arg appended before --force (repeatable)', (value, previous = []) => [...previous, value])
+        .option('--force', 'overwrite an existing adapter with the same id')
+        .option('--project <path>', 'project root (defaults to cwd)')).action((options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const file = registryFileFor(projectRoot);
+            const reg = new AdapterRegistry();
+            if (existsSync(file))
+                reg.load(file);
+            const id = options.id ?? '';
+            const record = options.arg !== undefined
+                ? { id, displayName: options.name ?? id, binary: options.binary ?? '', args: options.arg }
+                : { id, displayName: options.name ?? id, binary: options.binary ?? '' };
+            let result;
+            try {
+                result = reg.register(record, { force: options.force === true });
+            }
+            catch (validationError) {
+                printResult(io, fail('adapter.register', 'INVALID_ADAPTER_RECORD', getErrorMessage(validationError), { id }, [
+                    'Use --id with /^[a-z0-9][a-z0-9._-]*$/, --binary as a binary name (no path separators).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            reg.persist(file);
+            const warnings = [];
+            if (!result.created && options.force !== true) {
+                warnings.push(`adapter "${id}" already registered; pass --force to overwrite`);
+            }
+            printResult(io, ok('adapter.register', {
+                projectRoot,
+                file,
+                adapter: result.record,
+                created: result.created
+            }, warnings, [
+                `Run \`peaks runtime compact --via ${id}\` to invoke it.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('adapter.register', 'ADAPTER_REGISTER_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,45 @@
+/**
+ * peaks asset * CLI — M5 / spec §5 / §7.4
+ *
+ * Adds the umbrella verbs for the post-run crystallization flow:
+ *
+ *   peaks asset crystallize --from-task <id> --loop-name <name> \
+ *     --loop-scenario <text> --bee-name <name> \
+ *     --bee-version <semver> --bee-description <text> \
+ *     --brief-what-happened <text> --brief-why-it-matters <text> \
+ *     --brief-what-learned <text> --brief-what-action <text> \
+ *     [--bee-relation-reason <text>] [--brief-bullet <bullet>]... \
+ *     [--source-trace <id>]... [--evaluator-summary <text>] \
+ *     [--user-decision-summary <text>] \
+ *     [--trigger <user_explicit|llm_suggested|success_default_prompt|similar_task_recurrence>] \
+ *     [--project <root>] [--json]
+ *   peaks asset dispose --crystallization-event <id> --mode <trace_only|retain|destroy> \
+ *     [--project <root>] [--json]
+ *   peaks asset status [--loop <id>] [--bee <name>] [--project <root>] [--json]
+ *
+ * The crystallize verb prints the 4-section brief in the
+ * user-facing recommendation; refuses to proceed if any brief
+ * section is missing (EvidenceBriefSchema.refine guard +
+ * CrystallizationService pre-run gate).
+ *
+ * The dispose verb handles trace-only / retain / destroy. trace_only
+ * retires the crystallization event but keeps the source trace;
+ * retain is a no-op on the asset (the user wants to keep it as
+ * evidence); destroy hard-retires both the event and (if the
+ * user opts in) the created/updated assets. The CLI defaults to
+ * trace-only disposal for safety.
+ *
+ * The status verb lists loop + bee lifecycle state plus any
+ * crystallization events that reference them.
+ *
+ * Each verb prints a structured JSON envelope (`printResult` with
+ * `asJson=true`). The user never types a JSON manifest / form
+ * field; the LLM runs the CLI on the user's behalf.
+ *
+ * Defense in depth: the CrystallizationService enforces the
+ * pre-run gate and the brief-section guard; the CLI only
+ * translates flags into the service payload.
+ */
+import { Command } from "commander";
+import { type ProgramIO } from "../cli-helpers.js";
+export declare function registerAssetCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,404 @@
+/**
+ * peaks asset * CLI — M5 / spec §5 / §7.4
+ *
+ * Adds the umbrella verbs for the post-run crystallization flow:
+ *
+ *   peaks asset crystallize --from-task <id> --loop-name <name> \
+ *     --loop-scenario <text> --bee-name <name> \
+ *     --bee-version <semver> --bee-description <text> \
+ *     --brief-what-happened <text> --brief-why-it-matters <text> \
+ *     --brief-what-learned <text> --brief-what-action <text> \
+ *     [--bee-relation-reason <text>] [--brief-bullet <bullet>]... \
+ *     [--source-trace <id>]... [--evaluator-summary <text>] \
+ *     [--user-decision-summary <text>] \
+ *     [--trigger <user_explicit|llm_suggested|success_default_prompt|similar_task_recurrence>] \
+ *     [--project <root>] [--json]
+ *   peaks asset dispose --crystallization-event <id> --mode <trace_only|retain|destroy> \
+ *     [--project <root>] [--json]
+ *   peaks asset status [--loop <id>] [--bee <name>] [--project <root>] [--json]
+ *
+ * The crystallize verb prints the 4-section brief in the
+ * user-facing recommendation; refuses to proceed if any brief
+ * section is missing (EvidenceBriefSchema.refine guard +
+ * CrystallizationService pre-run gate).
+ *
+ * The dispose verb handles trace-only / retain / destroy. trace_only
+ * retires the crystallization event but keeps the source trace;
+ * retain is a no-op on the asset (the user wants to keep it as
+ * evidence); destroy hard-retires both the event and (if the
+ * user opts in) the created/updated assets. The CLI defaults to
+ * trace-only disposal for safety.
+ *
+ * The status verb lists loop + bee lifecycle state plus any
+ * crystallization events that reference them.
+ *
+ * Each verb prints a structured JSON envelope (`printResult` with
+ * `asJson=true`). The user never types a JSON manifest / form
+ * field; the LLM runs the CLI on the user's behalf.
+ *
+ * Defense in depth: the CrystallizationService enforces the
+ * pre-run gate and the brief-section guard; the CLI only
+ * translates flags into the service payload.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { openStateDb } from "../../services/skillhub/sqlite-store.js";
+import { CrystallizationService, CrystallizationIntegrityError, } from "../../services/crystallization/crystallization-service.js";
+import { CRYSTALLIZATION_TRIGGERS, parseEvidenceBrief, } from "../../services/crystallization/crystallization-types.js";
+import { BriefSectionError, safeRenderRecommendationPayload, } from "../../services/crystallization/evidence-brief-builder.js";
+import { findProjectRoot } from "../../services/config/config-safety.js";
+import { addJsonOption, getErrorMessage, printResult } from "../cli-helpers.js";
+import { fail, ok } from "../../shared/result.js";
+function collectRepeatable(value, previous) {
+    if (Array.isArray(previous))
+        return [...previous, value];
+    return [value];
+}
+const DISPOSE_MODES = ["trace_only", "retain", "destroy"];
+function parseTriggerFlag(raw) {
+    return CRYSTALLIZATION_TRIGGERS.includes(raw)
+        ? raw
+        : null;
+}
+export function registerAssetCommands(program, io) {
+    // Reuse the existing `asset` parent if one is registered; the
+    // add-a-new-subcommand-check-for-existing-top-level-first rule
+    // requires this guard.
+    const existing = program.commands.find((c) => c.name() === "asset");
+    const asset = existing ?? program.command("asset").description("M5: cross-asset crystallization surface (crystallize / dispose / status — spec §5 / §7.4)");
+    // ---------- peaks asset crystallize ----------
+    addJsonOption(asset
+        .command("crystallize")
+        .description("M5: persist a new loop_release + main_bee_release + loop_bee_relation + crystallization_event in a single transaction. Enforces the pre-run gate (task_status=completed AND gates_passed=true AND evidence_collected=true; AC-4 / RL-2) and the brief-section guard (all 4 sections required; AC-15 / RL-7).")
+        .requiredOption("--from-task <id>", "the candidate task id (must be 'completed' with gates_passed + evidence_collected)")
+        .requiredOption("--loop-id <id>", "kebab-case loop id, e.g. loop-onboarding-research")
+        .requiredOption("--loop-name <name>", "NL display name")
+        .requiredOption("--loop-scenario <text>", "long-form scenario text (what real problem the loop solves)")
+        .requiredOption("--loop-trigger-policy <text>", "trigger policy (NL intent match)")
+        .requiredOption("--loop-interaction-policy <text>", "interaction policy (Human-NL-Choice-Only is the default)")
+        .requiredOption("--loop-feedback-policy <text>", "feedback policy (what feedback enters long-term memory)")
+        .requiredOption("--loop-evolution-policy <text>", "evolution policy (Darwin-style ratchet rules)")
+        .requiredOption("--loop-success-criterion <text>", "declarative success criterion (repeatable)", collectRepeatable, [])
+        .requiredOption("--loop-evaluator-policy <text>", "evaluator policy line (repeatable)", collectRepeatable, [])
+        .requiredOption("--loop-version <semver>", "loop version (e.g. 0.1.0)")
+        .requiredOption("--bee-name <name>", "main bee name (kebab-case)")
+        .requiredOption("--bee-version <semver>", "bee version (e.g. 0.1.0)")
+        .requiredOption("--bee-description <text>", "main bee description (manifest-level)")
+        .requiredOption("--bee-relation-reason <text>", "NL reason for the main bee relation")
+        .requiredOption("--brief-what-happened <text>", "brief section: what_happened (1-2 sentence factual account)")
+        .requiredOption("--brief-why-it-matters <text>", "brief section: why_it_matters (1-2 sentence explanation)")
+        .requiredOption("--brief-what-learned <text>", "brief section: what_learned (1-2 sentence learning)")
+        .requiredOption("--brief-what-action <text>", "brief section: what_action (1 sentence recommended action)")
+        .option("--brief-bullet <bullet>", "structured bullet supporting the brief (repeatable)", collectRepeatable, [])
+        .option("--source-trace <id>", "workflow trace id backing the brief (repeatable)", collectRepeatable, [])
+        .option("--evaluator-summary <text>", "evaluator one-liner (independent scorers)", "")
+        .option("--user-decision-summary <text>", "user decision summary (NL)", "")
+        .option("--bee-intent-raw <text>", "optional bee user_intent_raw")
+        .option("--bee-parent-version <semver>", "optional parent_version")
+        .option("--bee-changelog <text>", "optional changelog")
+        .option("--trigger <name>", `crystallization trigger (one of: ${CRYSTALLIZATION_TRIGGERS.join("|")})`, "user_explicit")
+        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        try {
+            const trigger = parseTriggerFlag(options.trigger);
+            if (!trigger) {
+                printResult(io, fail("asset.crystallize", "ASSET_INVALID_TRIGGER", `--trigger must be one of: ${CRYSTALLIZATION_TRIGGERS.join("|")}`, { trigger: options.trigger }, ["Pass a valid --trigger value."]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Build the brief from CLI flags and re-validate it through
+            // the canonical schema (so a partial brief is caught BEFORE
+            // any DB side effects fire).
+            const candidateBrief = {
+                what_happened: options.briefWhatHappened,
+                why_it_matters: options.briefWhyItMatters,
+                what_learned: options.briefWhatLearned,
+                what_action: options.briefWhatAction,
+            };
+            let brief;
+            try {
+                brief = parseEvidenceBrief(candidateBrief);
+            }
+            catch (err) {
+                if (err instanceof BriefSectionError) {
+                    printResult(io, fail("asset.crystallize", "MISSING_BRIEF_SECTION", err.message, { findings: [...err.findings], flagsProvided: Object.keys(candidateBrief) }, [
+                        "Pass ALL FOUR brief sections via --brief-what-happened / --brief-why-it-matters / --brief-what-learned / --brief-what-action.",
+                        "The CLI refuses to render a recommendation without a complete 4-section brief (spec §4.7 / RL-7).",
+                    ]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                throw err;
+            }
+            // Render the recommendation envelope up-front so the CLI can
+            // refuse to write if any brief section is missing. This is
+            // the same code path the crystallization service uses.
+            const recommendation = safeRenderRecommendationPayload({
+                brief,
+                bullets: options.briefBullet ?? [],
+                source_trace_pointers: options.sourceTrace ?? [],
+                evaluator_summary: {
+                    one_liner: options.evaluatorSummary ?? "",
+                    risk_tags: [],
+                },
+            });
+            if (!recommendation.ok) {
+                printResult(io, fail("asset.crystallize", recommendation.code ?? "MISSING_BRIEF_SECTION", "recommendation envelope rejected — brief is missing one of its 4 sections", { findings: recommendation.findings, briefProvided: candidateBrief }, [
+                    "Pass ALL FOUR brief sections via the matching CLI flags.",
+                    "Counts in --brief-bullet may support the brief; they do NOT replace it (spec §4.7 / RL-7).",
+                ]), 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 CrystallizationService(db);
+                const result = svc.crystallize({
+                    task: {
+                        task_id: options.fromTask,
+                        task_status: "completed",
+                        gates_passed: true,
+                        evidence_collected: true,
+                    },
+                    loop_input: {
+                        id: options.loopId,
+                        name: options.loopName,
+                        scenario: options.loopScenario,
+                        trigger_policy: options.loopTriggerPolicy,
+                        success_criteria: options.loopSuccessCriterion,
+                        interaction_policy: options.loopInteractionPolicy,
+                        feedback_policy: options.loopFeedbackPolicy,
+                        evolution_policy: options.loopEvolutionPolicy,
+                        evaluator_policy: options.loopEvaluatorPolicy,
+                        linked_bees: [],
+                        run_history: [],
+                        crystallization_evidence: [],
+                        lifecycle_status: "candidate",
+                        version: options.loopVersion,
+                    },
+                    bee_input: {
+                        bee_name: options.beeName,
+                        version: options.beeVersion,
+                        description: options.beeDescription,
+                        ...(options.beeIntentRaw !== undefined ? { user_intent_raw: options.beeIntentRaw } : {}),
+                        ...(options.beeParentVersion !== undefined ? { parent_version: options.beeParentVersion } : {}),
+                        ...(options.beeChangelog !== undefined ? { changelog: options.beeChangelog } : {}),
+                    },
+                    bee_relation_reason: options.beeRelationReason,
+                    evidence_brief: brief,
+                    evidence_bullets: options.briefBullet ?? [],
+                    source_trace_pointers: options.sourceTrace ?? [],
+                    ...(options.evaluatorSummary !== undefined ? { evaluator_summary: options.evaluatorSummary } : {}),
+                    ...(options.userDecisionSummary !== undefined ? { user_decision_summary: options.userDecisionSummary } : {}),
+                    trigger,
+                });
+                printResult(io, ok("asset.crystallize", {
+                    recommendation: {
+                        brief: recommendation.payload.brief,
+                        bullets: recommendation.payload.bullets,
+                        source_trace_pointers: recommendation.payload.source_trace_pointers,
+                        evaluator_summary: recommendation.payload.evaluator_summary,
+                    },
+                    result,
+                    nextActions: [
+                        `Run \`peaks loop show --loop ${result.loop_release_id}\` to inspect the new loop_release.`,
+                        `Run \`peaks asset dispose --crystallization-event ${result.crystallization_event_id} --mode trace_only\` to retire the event without touching the asset.`,
+                    ],
+                }, [], [
+                    "The CLI has surfaced a complete 4-section brief; the LLM should now drive the user through AskUserQuestion picks (spec §5.3).",
+                ]), options.json);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            if (err instanceof CrystallizationIntegrityError) {
+                printResult(io, fail("asset.crystallize", err.code, err.message, { findings: [...err.findings] }, [
+                    err.code === "CRYSTALLIZATION_PRE_RUN"
+                        ? "Re-shape the candidate task so task_status=completed AND gates_passed=true AND evidence_collected=true (spec §5 / RL-2)."
+                        : err.code === "MISSING_BRIEF_SECTION"
+                            ? "Pass ALL FOUR brief sections (RL-7); the CLI refuses to render a recommendation without them."
+                            : "Inspect the failure findings and re-shape the payload.",
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (err instanceof BriefSectionError) {
+                printResult(io, fail("asset.crystallize", "MISSING_BRIEF_SECTION", err.message, { findings: [...err.findings] }, ["Pass all 4 brief sections (RL-7)."]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail("asset.crystallize", "ASSET_CRYSTALLIZE_FAILED", getErrorMessage(err), {}, [
+                "Verify the brief flags and the loop/bee identifiers are valid.",
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // ---------- peaks asset dispose ----------
+    addJsonOption(asset
+        .command("dispose")
+        .description("M5: dispose a crystallization event. mode=trace_only retires the event but keeps the trace; mode=retain keeps both; mode=destroy retires the event and marks the created/updated assets retired.")
+        .requiredOption("--crystallization-event <id>", "the crystallization event id (returned by `peaks asset crystallize`)")
+        .requiredOption(`--mode <mode>`, `dispose mode (one of: ${DISPOSE_MODES.join("|")}; default: trace_only)`, "trace_only")
+        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        try {
+            if (!DISPOSE_MODES.includes(options.mode)) {
+                printResult(io, fail("asset.dispose", "ASSET_INVALID_MODE", `--mode must be one of: ${DISPOSE_MODES.join("|")}`, { mode: options.mode }, ["Pass --mode trace_only / retain / destroy."]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const mode = options.mode;
+            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 CrystallizationService(db);
+                const existing = svc.read(options.crystallizationEvent);
+                if (!existing) {
+                    printResult(io, fail("asset.dispose", "ASSET_EVENT_NOT_FOUND", `crystallization event '${options.crystallizationEvent}' not found`, { eventId: options.crystallizationEvent }, ["Verify the event id."]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                // trace_only → retire the event row; the source traces are
+                // untouched (workflow traces are immutable per spec §4.3).
+                // retain → no DB change; the user wants to keep the event
+                // as historical evidence.
+                // destroy → retire the event + retire the created/updated
+                // assets (no asset delete; retirement only).
+                if (mode === "retain") {
+                    printResult(io, ok("asset.dispose", {
+                        crystallization_event_id: existing.id,
+                        mode,
+                        lifecycle_status: existing.lifecycle_status,
+                        note: "no DB change; event retained as-is",
+                    }, [], [
+                        "Run `peaks asset status --loop <id>` to inspect the lifecycle state of the linked assets.",
+                    ]), options.json);
+                    return;
+                }
+                const updated = svc.updateStatus(existing.id, "retired");
+                if (mode === "destroy" && updated) {
+                    // Retire the created/updated loop_release rows as well.
+                    // We do NOT delete rows — retirement is a status flip
+                    // (spec §5.6).
+                    const retireLoop = db.prepare("UPDATE loop_release SET lifecycle_status = 'retired' WHERE id IN (?, ?)");
+                    const ids = [
+                        updated.created_loop_release_id ?? null,
+                        updated.updated_loop_release_id ?? null,
+                    ].filter((x) => x !== null);
+                    for (const id of ids) {
+                        retireLoop.run(id, id);
+                    }
+                }
+                printResult(io, ok("asset.dispose", {
+                    crystallization_event_id: existing.id,
+                    mode,
+                    lifecycle_status: updated?.lifecycle_status ?? "retired",
+                    retired_assets: mode === "destroy" ? "loop_release retired (no rows deleted)" : "none",
+                    nextActions: [
+                        "Run `peaks asset status` to confirm the lifecycle transition.",
+                    ],
+                }, [], []), options.json);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            printResult(io, fail("asset.dispose", "ASSET_DISPOSE_FAILED", getErrorMessage(err), { eventId: options.crystallizationEvent }, [
+                "Verify the event id and --mode flag.",
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // ---------- peaks asset status ----------
+    addJsonOption(asset
+        .command("status")
+        .description("M5: list loop + bee lifecycle state. With --loop, returns the loop + all linked bee_releases + all crystallization events referencing them.")
+        .option("--loop <id>", "filter by loop_release id")
+        .option("--bee <name>", "filter by bee_name")
+        .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 CrystallizationService(db);
+                let events = [];
+                if (options.loop) {
+                    events = [
+                        ...svc.list({ created_loop_release_id: options.loop }),
+                        ...svc.list({ updated_loop_release_id: options.loop }),
+                    ];
+                    // Deduplicate by id.
+                    const seen = new Set();
+                    events = events.filter((e) => {
+                        const key = e?.id ?? "";
+                        if (!key || seen.has(key))
+                            return false;
+                        seen.add(key);
+                        return true;
+                    });
+                }
+                else {
+                    events = svc.list();
+                }
+                // Companion queries: loop lifecycle counts + bee lifecycle
+                // counts. We compute from the DB so the CLI is the single
+                // source of truth.
+                const loopCounts = db
+                    .prepare("SELECT lifecycle_status, COUNT(*) AS n FROM loop_release GROUP BY lifecycle_status")
+                    .all()
+                    .reduce((acc, r) => {
+                    acc[r.lifecycle_status] = r.n;
+                    return acc;
+                }, {});
+                const beeCounts = db
+                    .prepare("SELECT bee_name, COUNT(*) AS n FROM bee_release GROUP BY bee_name ORDER BY bee_name ASC")
+                    .all()
+                    .filter((r) => options.bee === undefined || r.bee_name === options.bee);
+                printResult(io, ok("asset.status", {
+                    filters: {
+                        ...(options.loop !== undefined ? { loop: options.loop } : {}),
+                        ...(options.bee !== undefined ? { bee: options.bee } : {}),
+                    },
+                    crystallization_events: events.length,
+                    events: events.map((e) => ({
+                        id: e?.id,
+                        trigger: e?.trigger,
+                        lifecycle_status: e?.lifecycle_status,
+                        created_loop_release_id: e?.created_loop_release_id,
+                        created_bee_release_id: e?.created_bee_release_id,
+                        updated_loop_release_id: e?.updated_loop_release_id,
+                        updated_bee_release_id: e?.updated_bee_release_id,
+                        created_at: e?.created_at,
+                    })),
+                    loop_release_counts_by_lifecycle: loopCounts,
+                    bee_release_counts_by_name: beeCounts,
+                    nextActions: [
+                        options.loop
+                            ? `Run \`peaks loop show --loop ${options.loop}\` for the loop detail view.`
+                            : "Pass --loop <id> to drill into a specific loop's crystallization history.",
+                    ],
+                }, [], []), options.json);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            printResult(io, fail("asset.status", "ASSET_STATUS_FAILED", getErrorMessage(err), { loop: options.loop, bee: options.bee }, [
+                "Verify the loop / bee identifiers.",
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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 { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerBeeCommands(program: Command, io: ProgramIO): void;