peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## [Unreleased]
 
+## 4.0.0-beta.9 — 2026-07-15
+
+### Fixed — `npm install peaks-loop` runtime path layout
+
+`4.0.0-beta.8` shipped a tarball where `bin/peaks.js` imported
+`'../dist/src/cli/index.js'`, but tsc actually emitted the runtime
+files at `dist/cli/index.js` (rootDir walked past `src/` because of
+cross-folder imports like `src/services/hooks/output.ts → ../../cli/`).
+Downstream `npm i -g peaks-loop` then `peaks -v` failed with
+`ERR_MODULE_NOT_FOUND: .../dist/src/cli/index.js`. The 4 audit/business
+templates also failed to enter the tarball because `package.json#files[]`
+whitelisted `dist/src/**/*.js` / `.d.ts` but never `.md`.
+
+This release:
+
+- `bin/peaks.js` import: `'../dist/src/cli/index.js'` → `'../dist/cli/index.js'`.
+- `scripts/copy-templates.mjs` dest: `dist/src/services/...` →
+  `dist/services/...` so the bundled templates land where the runtime
+  `import.meta.url` resolver expects them.
+- `package.json#files[]`: prefixes shifted from `dist/src/` to `dist/`,
+  plus a new `dist/**/*.md` entry so the 4 templates bundled by
+  `copy-templates.mjs` actually ship.
+- `tsconfig.build.json` (introduced in beta.8) confirmed correct — it
+  is the build-time emit that controls the dist tree shape.
+
+End-to-end smoke after the fix (local):
+
+```
+$ npm pack                                  # 30 MB tarball
+$ npm install ./peaks-loop-4.0.0-beta.9.tgz --prefix /tmp/test
+$ peaks --version                           # → "4.0.0-beta.9"
+$ peaks workspace init --project /tmp/fresh  # → templatesBooted: 5
+```
+
+`.peaks/project-scan/{project-scan.md, business-knowledge.md,
+security-template.md, perf-template.md, audit-output-schema.md}`
+all present after a fresh workspace init.
+
+### Notes
+
+- 4.0.0-beta.8 is left in place on npm as a known-broken release.
+  Consumers who already pinned `peaks-loop@4.0.0-beta.8` should bump
+  to `4.0.0-beta.9`.
+- Beta.9 contains everything beta.8 advertised plus the path fix.
+
 ## 4.0.0-beta.8 — 2026-07-15
 
 ### Added — project-scan bootstrap (slice 2026-07-15)

package/bin/peaks.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/src/cli/index.js';
+import '../dist/cli/index.js';

package/dist/cli/cli-helpers.d.ts

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from '../shared/result.js';
+import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
+import type { ConfigLayer } from '../services/config/config-service.js';
+import type { MiniMaxProviderSmokeResult } from '../services/providers/minimax-provider-service.js';
+import type { MiniMaxWorkerResult } from '../services/providers/minimax-worker-service.js';
+import type { RecommendationWorkflow } from '../services/recommendations/recommendation-service.js';
+export type ProgramIO = {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function printResult<T>(io: ProgramIO, result: ResultEnvelope<T>, asJson?: boolean): void;
+export declare function addJsonOption(command: Command): Command;
+export declare function failUnsupportedNonDryRun(io: ProgramIO, command: string, asJson?: boolean): void;
+/** CLI shim helper: render a `{ ok: boolean, error?, data? }` envelope
+ *  and set `process.exitCode = 1` on failure.
+ *
+ *  Library functions MUST return envelopes like `{ ok, error?, data? }`
+ *  and MUST NOT mutate `process.exitCode` themselves. The shim (the
+ *  Commander `.action()` callback in `register*Commands`) owns the
+ *  process-exit side-effect so the library can be re-used from non-CLI
+ *  contexts (vitest, programmatic dispatch, plugin loading).
+ *
+ *  Output format mirrors the existing `registerSedimentCommands` shim:
+ *  a JSON envelope on stdout (one line, parseable), nothing else.
+ */
+export interface CliEnvelope {
+    ok: boolean;
+    error?: string;
+    data?: unknown;
+}
+export declare function printCliEnvelope(io: ProgramIO, r: CliEnvelope): void;
+export declare function isRecommendationWorkflow(value: string): value is RecommendationWorkflow;
+export declare function isArtifactProvider(value: string): value is ArtifactProvider;
+export declare function isArtifactSetupStep(value: string): value is GuidedArtifactSetup['step'];
+export declare function isArtifactRepoSegment(value: string): boolean;
+export declare function isMiniMaxHttpsUrl(value: string): boolean;
+export declare function parseConfigLayer(value: string | undefined): ConfigLayer | undefined | null;
+export declare function printInvalidConfigLayer(io: ProgramIO, command: string, asJson?: boolean): void;
+export declare function multipleOption(value: string, previous: string[]): string[];
+export declare function summarizeMiniMaxSmokeResult(result: MiniMaxProviderSmokeResult): MiniMaxProviderSmokeResult;
+export declare function summarizeMiniMaxWorkerResult(result: MiniMaxWorkerResult): MiniMaxWorkerResult;
+export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/cli-helpers.js

@@ -0,0 +1,86 @@
+import { fail, getErrorMessage, ok, redactSensitiveErrorMessage } from '../shared/result.js';
+const MINIMAX_API_HOST = 'api.minimaxi.com';
+export function printResult(io, result, asJson = false) {
+    if (asJson) {
+        io.stdout(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.ok) {
+        io.stderr(`${result.code}: ${result.message}`);
+        for (const action of result.nextActions) {
+            io.stderr(`- ${action}`);
+        }
+        return;
+    }
+    io.stdout(JSON.stringify(result.data, null, 2));
+    for (const warning of result.warnings) {
+        io.stderr(`warning: ${warning}`);
+    }
+    for (const action of result.nextActions) {
+        io.stdout(`next: ${action}`);
+    }
+}
+export function addJsonOption(command) {
+    return command.option('--json', 'print machine-readable JSON envelope');
+}
+export function failUnsupportedNonDryRun(io, command, asJson) {
+    printResult(io, fail(command, 'UNSUPPORTED_NON_DRY_RUN', 'Only dry-run planning is supported', {}, ['Rerun with --dry-run or omit --no-dry-run']), asJson);
+    process.exitCode = 1;
+}
+export function printCliEnvelope(io, r) {
+    if (r.ok) {
+        io.stdout(JSON.stringify({ ok: true, data: r.data ?? null }));
+        return;
+    }
+    io.stdout(JSON.stringify({ ok: false, error: r.error }));
+    process.exitCode = 1;
+}
+export function isRecommendationWorkflow(value) {
+    return value === 'code-refactor' || value === 'product-refactor' || value === 'frontend-design';
+}
+export function isArtifactProvider(value) {
+    return value === 'github' || value === 'gitlab';
+}
+export function isArtifactSetupStep(value) {
+    return value === 'detect' || value === 'configure' || value === 'validate' || value === 'complete';
+}
+export function isArtifactRepoSegment(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
+}
+export function isMiniMaxHttpsUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseConfigLayer(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value === 'user' || value === 'project' ? value : null;
+}
+export function printInvalidConfigLayer(io, command, asJson) {
+    printResult(io, fail(command, 'INVALID_CONFIG_LAYER', 'Config layer must be user or project', {}, ['Use --layer user or --layer project']), asJson);
+    process.exitCode = 1;
+}
+export function multipleOption(value, previous) {
+    return [...(previous || []), value];
+}
+export function summarizeMiniMaxSmokeResult(result) {
+    return { ...result, responseText: null, summary: null };
+}
+export function summarizeMiniMaxWorkerResult(result) {
+    const provider = summarizeMiniMaxSmokeResult(result.provider);
+    return {
+        ...result,
+        provider,
+        reviewHandoff: {
+            model: result.reviewHandoff.model,
+            prompt: '[redacted]'
+        }
+    };
+}
+export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/commands/_cli-error-envelope.d.ts

@@ -0,0 +1,19 @@
+export type EnvelopeMapping = {
+    code: 'INVALID_GOAL';
+    nextActions: readonly string[];
+} | {
+    code: 'INVALID_PROVIDERS';
+    nextActions: readonly string[];
+} | {
+    code: 'INTERNAL_ERROR';
+    nextActions: readonly string[];
+};
+/**
+ * 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 declare function mapServiceError(error: unknown): EnvelopeMapping;

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/adapter-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `peaks skill adapter <verb>` — adapter selection + detection CLI.
+ *
+ * Slice 2026-07-04-cli-15a (Task 15a of the 18-verb plan). Two verbs:
+ *
+ *   list        — return the known adapter id list
+ *   set-active  — record which adapter is currently active
+ *
+ * Unknown verbs return an empty result so program.ts can render a
+ * NOT_FOUND envelope without throwing.
+ */
+import type { Command } from "commander";
+import type { ProgramIO } from "../cli-helpers.js";
+export interface AdapterResult {
+    adapters?: string[];
+    active?: string;
+}
+/** Dispatch an adapter verb. `home` is accepted for API symmetry
+ *  with runSediment, but the in-scope verbs don't read from disk yet. */
+export declare function runAdapter(argv: string[], { home: _home }: {
+    home: string;
+}): Promise<AdapterResult>;
+/** Register the `peaks skill adapter <verb>` subcommand group.
+ *
+ *  Matches the pattern used by sediment-commands.ts: the `skill`
+ *  parent command is reused when present, created lazily otherwise.
+ *  See src/cli/commands/workflow-plan-commands.ts:179 for the
+ *  precedent.
+ */
+export declare function registerAdapterCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,35 @@
+/** Dispatch an adapter verb. `home` is accepted for API symmetry
+ *  with runSediment, but the in-scope verbs don't read from disk yet. */
+export async function runAdapter(argv, { home: _home }) {
+    const verb = argv[0];
+    if (verb === "list") {
+        return { adapters: ["claude", "codex", "copilot"] };
+    }
+    if (verb === "set-active") {
+        const name = argv[1];
+        if (name === undefined)
+            return {};
+        return { active: name };
+    }
+    return {};
+}
+/** Register the `peaks skill adapter <verb>` subcommand group.
+ *
+ *  Matches the pattern used by sediment-commands.ts: the `skill`
+ *  parent command is reused when present, created lazily otherwise.
+ *  See src/cli/commands/workflow-plan-commands.ts:179 for the
+ *  precedent.
+ */
+export function registerAdapterCommands(program, io) {
+    const existingSkill = program.commands.find((c) => c.name() === "skill");
+    const skill = existingSkill ??
+        program.command("skill").description("Manage Peaks skills");
+    skill
+        .command("adapter <args...>")
+        .description("Adapter selection and detection")
+        .action(async (args) => {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.cwd();
+        const r = await runAdapter(args, { home });
+        io.stdout(JSON.stringify(r));
+    });
+}

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

@@ -0,0 +1,20 @@
+/**
+ * peaks agent * CLI surface — Slice: ECC 64 agents soft-optional
+ * integration (per spec §7.2 line 818).
+ *
+ * Registers the new `peaks agent` top-level command with two
+ * subcommands:
+ *   - `peaks agent run <name> [--target <path>]`  — shell out to
+ *     `npx ecc agent run <name> --target <path> --json` when ECC
+ *     is installed; soft-fail with the 4-option install prompt
+ *     when it isn't.
+ *   - `peaks agent list`                          — emit the 12
+ *     canonical ECC agents (the wrapper hardcodes the
+ *     most-used subset; the full 64-agent list is
+ *     discoverable at runtime via `npx ecc agent list`).
+ *
+ * The wrapper service is `src/services/agent/ecc-agent-service.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerAgentCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,48 @@
+import { runEccAgent, validateEccAgent, CANONICAL_ECC_AGENTS, } from '../../services/agent/ecc-agent-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerAgentCommands(program, io) {
+    const agent = program
+        .command('agent')
+        .description('Run an ECC agent (soft-optional per spec §7.2). 64 agents are npm-installable via npx ecc; peaks-loop shells out when ECC is installed and soft-fails with a 4-option install prompt when it is not. Native peaks-loop diagnostics still run via `peaks doctor scan`.');
+    addJsonOption(agent
+        .command('run <name>')
+        .description(`Run an ECC agent by name (e.g. 'security-reviewer', 'code-reviewer'). The canonical subprocess is \`npx ecc agent run <name> --target <path> --json\`.`)
+        .option('--target <path>', 'project root or file to analyze (default: cwd)')
+        .option('--enable', 'enable the ECC subprocess for this call (overrides default-off; soft-fails with the 4-option install prompt when ECC is missing)')).action(async (name, options) => {
+        const validationError = validateEccAgent(name);
+        if (validationError !== null) {
+            printResult(io, fail('agent.run', 'INVALID_AGENT_NAME', validationError, { agent: name }, [
+                'Use `peaks agent list` to see the canonical 12 agents',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const projectRoot = options.target ?? process.cwd();
+        try {
+            const result = runEccAgent({
+                agent: name,
+                projectRoot,
+                enableAgent: options.enable === true,
+            });
+            const data = { ...result, projectRoot };
+            const nextActions = [];
+            if (result.reason === 'flag-enabled-but-ecc-missing') {
+                nextActions.push('ECC not installed. Pick one of the four options below:', '  a) Install: run `npx ecc --help` to install, then re-run `peaks agent run`.', '  b) Skip this run: use the peaks-loop native diagnostic via `peaks doctor scan`.', '  c) Skip forever: run `peaks preferences set agentShieldEnabled false`.', '  d) Learn more: see docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §7.2.');
+            }
+            const envelope = ok('agent.run', data, [...result.warnings], nextActions);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('agent.run', 'AGENT_RUN_FAILED', message, { agent: name, projectRoot, spawned: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(agent
+        .command('list')
+        .description(`List the 12 canonical ECC agents (peaks-loop ships a static subset; the full 64 are ECC-discovered).`)).action((options) => {
+        const envelope = ok('agent.list', { agents: CANONICAL_ECC_AGENTS.map((a) => ({ name: a.name, description: a.description })) }, [], ['Run any agent with: `peaks agent run <name> --target <path>`']);
+        printResult(io, envelope, options.json);
+    });
+}

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;