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

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 ## [Unreleased]
 
+## 4.0.0-beta.4 — 2026-07-08
+
+Loop Engineering crystallization is now the product surface. The 4.0.0-beta.3 line shipped the framework; this release ships the post-run crystallization engine, the Darwin-style ratchet, the bundle share / desktop extension surface, and the karpathy-engineered red-line set that locks them together. Every durable-change entry is gated on a real, completed run; every evolution round is gated on an independent-context evaluation.
+
+### Added — Loop Engineering Asset layer (§4.1, AC-1/AC-2/AC-3)
+
+- **`loop_release` table** — `src/services/skillhub/migrations/002-loop-release.sql`. Schema version pinned to `peaks.loop/1` via CHECK constraint. Indexes on `lifecycle_status` and `scenario`. Non-breaking: 4.x `bee_release` rows continue to read.
+- **`loop_bee_relation` table** — `src/services/skillhub/migrations/003-loop-bee-relation.sql`. Schema version `peaks.loop-bee-relation/1`. Roles: `main` / `supporting` / `candidate` / `retired`. Partial UNIQUE index `WHERE role='main'` enforces at most one main bee per loop at the storage layer (defense in depth; the service layer also enforces it).
+- **Schema for the four-loop + dual-asset model** — Zod schemas in `src/services/loop/loop-release-types.ts` and `src/services/loop/loop-bee-relation-types.ts` mirror the §4.1 / §4.6 row shapes and refuse to parse rows whose `schema_version` is not the fixed literal.
+
+### Added — Post-run crystallization flow (§5, AC-4 / AC-5 / AC-6 / AC-7)
+
+- **`crystallization_event` table** — `src/services/skillhub/migrations/006-crystallization-event.sql`. Schema version `peaks.crystallization/1`. Carries the 4-section evidence brief inline; FKs to optional created/updated loop_release / bee_release.
+- **`CrystallizationService`** — `src/services/crystallization/crystallization-service.ts`. Pre-run gate: `task_status='completed'` AND `gates_passed=true` AND `evidence_collected=true` (Zod literal enforcement + service-layer re-assertion). Atomic single-transaction write of loop_release + bee_release header + bee_manifest + loop_bee_relation(main) + crystallization_event(brief inline).
+- **`peaks asset crystallize`** CLI — `src/cli/commands/asset-commands.ts`. Required options: `--brief-what-happened`, `--brief-why-it-matters`, `--brief-what-learned`, `--brief-what-action`. A partial brief is rejected with `MISSING_BRIEF_SECTION` and exit 1 (RL-7).
+- **`peaks asset dispose` / `peaks asset status`** — cross-asset dispose (trace_only / retain / destroy) and lifecycle status dashboard.
+
+### Added — Darwin-style ratchet (§6, AC-8 / AC-9 / AC-10 / AC-11)
+
+- **`evolution_evaluation` table** — `src/services/skillhub/migrations/005-evolution-evaluation.sql`. Schema version `peaks.evolution/1`. Carries `target_kind`, `target_release_id`, `optimization_dimensions_json` (length-1 enforced at service layer), `target_count=1` (CHECK), `author_id`, `evaluator_id`, `skeptic_id` (three independent agents), `verdict` ∈ {`keep`, `revert`, `needs-user-decision`}, `user_confirmation_pointer`, `brief_pointer`, and the four-section brief projection.
+- **`EvolutionService`** — `src/services/evolution/evolution-service.ts`. Hard rules: single object (AC-8) + single optimization dimension (AC-8) + author ≠ evaluator ≠ skeptic (AC-10/AC-12/AC-14) + score_delta >= score_delta_min for `keep` (AC-11, default 1.0) + user_confirmation_pointer required for `keep` (AC-15).
+- **`peaks evolution propose / evaluate / revert / mark-keep / status`** CLI — `src/cli/commands/evolution-commands.ts`. Each error path emits a stable wire-format code (`EVOLUTION_MULTI_OBJECT` / `EVOLUTION_MULTI_DIMENSION` / `EVOLUTION_SELF_SCORE` / `EVOLUTION_DELTA_BELOW_THRESHOLD` / `EVOLUTION_MISSING_USER_CONFIRMATION`).
+- **Independent-evaluator runner** — `src/services/evolution/independent-evaluator-runner.ts`. Frozen `EvaluationPackage` containing only `target_kind / target_release_id / optimization_dimension / before_snapshot / after_snapshot / diff / rubric / red_lines / source_traces` — no author session, no author reasoning, no recommendation framing (AC-12 / AC-13).
+- **Regression-skeptic runner** — `src/services/evolution/regression-skeptic-runner.ts`. A SEPARATE agent that emits `driftRisks / overfitRisks / safetyRegressionRisks` plus an optional `blocker` (which forces `verdict='revert'`).
+
+### Added — Karpathy-engineered red-line set (AC-21 / AC-22 / AC-23)
+
+- **`.peaks/standards/loop-engineering-guidelines.md`** — the single source of truth for the 10 red lines RL-0..RL-9, each in the four-section karpathy form (Failure modes / Rewrite / Self-check / Out-of-scope). Co-equal karpathy × darwin layers (RL-0).
+- **`peaks standards lint --category loop-engineering`** — `src/services/standards/loop-engineering-lint.ts`. Parses the guideline file and asserts every red line has all four sections, fails closed otherwise.
+- **`peaks skill lint --category loop-engineering-readiness --path <skill-dir>`** — `src/services/standards/loop-engineering-readiness-lint.ts` + `src/cli/commands/skill-loop-engineering-readiness-commands.ts`. Asserts a peaks-* SKILL.md (a) references `.peaks/standards/loop-engineering-guidelines.md`, (b) does not introduce a CLI verb the user is meant to type, (c) does not introduce a JSON / manifest hand-authoring surface. Alias verb: `peaks skill ready --category loop-engineering-readiness --path <skill-dir>`.
+- **Unit guard** — `tests/unit/standards/loop-engineering-guidelines.test.ts` enforces the four-section shape for every red line in the file.
+- **peaks-code domain boundary (RL-8)** — `skills/peaks-code/SKILL.md` self-declares as the code-domain long-task loop engineering orchestrator and is NOT a general-purpose orchestrator. Cross-domain peaks-* skills (peaks-content, peaks-issue-fix-orchestrator) import the shared guideline file and pass the readiness lint.
+
+### Added — Bundle share + desktop extension surface (§7A, AC-24 / AC-25 / AC-26)
+
+- **Share / desktop fields** — `src/services/skillhub/migrations/004-loop-bee-extension.sql`. Adds `shareable / share_excluded_paths / desktop_visible / export_bundle_format` to `loop_release`, and `shareable / desktop_visible` to `bee_release`. `export_bundle_format` is pinned to `peaks.bundle/1` via CHECK constraint. Non-breaking: every new column has a DEFAULT.
+- **Bundle writer** — `src/services/share/bundle-writer.ts`. Writes a `peaks.bundle/1` tar.gz with `manifest.json`, `relations.json`, `evidence_briefs/*.json`, content-addressed `blobs/<sha256>`, and `EVALUATION_REQUIRED.md`. Hard block: `shareable=false` throws `BundleNotShareableError(SHARE_BUNDLE_ERROR_CODES.NOT_SHAREABLE)` BEFORE any tarball work, for both loop and bee kinds.
+- **Bundle reader** — `src/services/share/bundle-reader.ts`. Hard blocks: `format_version_major != 1` is rejected (AC-25); `schema_versions` mismatch is rejected; the imported release ALWAYS lands as `candidate` (AC-25 / §10 RL-9). The bundle carries an `EVALUATION_REQUIRED.md` marker telling the receiver to run an independent evaluation before any durable change.
+- **`peaks loop export` / `peaks loop import`** — `src/cli/commands/loop-commands.ts`. Existing 14.x `peaks loop *` subcommands are preserved; M7 only ADDS export / import.
+- **`peaks bee export` / `peaks bee import`** — `src/cli/commands/share-commands.ts`. Same hard-block semantics.
+- **Receiver-side integration test** — `tests/integration/share-bundle-roundtrip.test.ts` asserts the round-trip lands as `candidate` (AC-25), that `shareable=false` blocks the export at the CLI layer, and that without an `evolution_evaluation` row the receiver has no path to `stable` (AC-26).
+
+### Added — SkillHub expansion (5 new tables / non-breaking)
+
+The 6+ relation table layout is preserved. 5 new tables added under `.peaks/_runtime/<sessionId>/`:
+- `loop_release` (002)
+- `loop_bee_relation` (003)
+- loop↔bee share / desktop extension columns (004)
+- `evolution_evaluation` (005)
+- `crystallization_event` (006)
+
+Migration is non-breaking: every new column has a DEFAULT and the new tables sit alongside the existing 4.x schema.
+
+### Added — New CLI verbs (spec §7.4)
+
+- `peaks loop init / list / show / search / recent / export / import`
+- `peaks asset crystallize / dispose / status`
+- `peaks evolution propose / evaluate / revert / mark-keep / status`
+- `peaks skill lint --category loop-engineering-readiness --path <skill-dir>`
+- `peaks skill ready --category loop-engineering-readiness --path <skill-dir>` (alias)
+
+### Changed
+
+- **`peaks workflow *`** is reframed as the execution trace surface (per spec §7.6 demotion); it remains functional. The user-facing verb is "replay this run", not "create a new asset".
+- **peaks-maker skill** is narratively repositioned to "Loop crystallizer + Bee creator + Evolution gatekeeper" (per spec §7.5); only the SKILL.md and memory references are re-narrated, the `id` is preserved.
+
+### Verification (4.0.0-beta.4)
+
+- `tsc --noEmit` zero errors
+- `peaks standards lint --category loop-engineering` parses all 10 red lines + 4 sections each (lint passes)
+- `pnpm vitest run tests/unit/{standards,crystallization,evolution,share}/` — 13 files / 154 unit tests pass
+- `pnpm vitest run tests/integration/{share-bundle-roundtrip,dogfood-loop-engineering-crystallization,asset-crystallize-cli,evolution-cli,skill-loop-engineering-readiness-cli}.test.ts` — 5 files / 26 integration tests pass
+- M8 dogfood (`tests/integration/dogfood-loop-engineering-crystallization.test.ts`) crystallizes the M0..M7 work into a real loop + bee + relation + event in 644ms (defense in depth: the release crystallizes itself)
+
+### Migration
+
+- 4.x `bee_release` rows continue to read. No data migration required.
+- The 5 new tables are added via non-destructive `CREATE TABLE IF NOT EXISTS` migrations.
+- The `bundle-writer / bundle-reader` pair is additive; existing `peaks skill sediment export / import` remains as an alias for one release cycle, then deprecates.
+- The peaks-code SKILL.md is unchanged from 4.0.0-beta.3 — no `peaks-solo` migration needed for users already on beta.2 or later.
+
 ## 4.0.0-beta.2 — 2026-07-07
 
 ### Renamed

package/README-en.md

@@ -7,16 +7,29 @@
 [![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
 <p align="center">
-  <video src="./examples/video-demo/preview/peaks-loop-demo-en.mp4" controls muted playsinline preload="metadata" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);"></video>
+  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.mp4">
+    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/en-closing-960.png" alt="peaks-loop demo (click to play)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
+  </a>
+  <br>
+  <sub>👆 click the image to play the 60s demo</sub>
 </p>
 
 ## What it is
 
 ### Loop engineering, engineered
 
-### peaks-loop is your AI tactical squad — on call 24/7, summon them
+**peaks-loop is your Loop Engineering crystallization system — not a workflow tool.** It crystallizes Loop Engineering assets out of real, completed work, and only evolves them through verified improvements. You operate the system through natural language and choices; every structured action is performed by the LLM on your behalf.
 
-It packs engineering gates, orchestration, replay into your local AI CLI. Install it, say one sentence, it runs the whole flow end-to-end and hands it back.
+The product is governed by a four-layer asset model and a karpathy × darwin dual-discipline, both of which are non-negotiable:
+
+- **Four-layer asset model**: Loop Engineering Asset (the method system, first-class) + Bee Asset (the executable body, first-class) + Workflow Trace (execution trace — evidence only, never the durable asset) + Evolution Evaluation (anti-drift gate, mandatory for any change).
+- **karpathy × darwin dual discipline**: karpathy engineers every rule (failure modes + imperative→declarative rewrite + self-check + out-of-scope); darwin verifies every improvement (single object + single dimension + independent-context evaluator + ratchet). The two layers are co-equal partners — neither is a subset of the other. See `.peaks/standards/loop-engineering-guidelines.md` and the upstream references `multica-ai/andrej-karpathy-skills` and `alchaincyf/darwin-skill`.
+- **Post-run crystallization**: `loop_release` and `bee_release` are only written after a real task completes; pre-run is always scratch. Four triggers are supported, with `user_explicit` ranked highest.
+- **Human-NL-Choice-Only**: you speak or pick; the LLM runs the CLI. Hand-authoring JSON / manifests / form fields is forbidden.
+
+### peaks-code is the code-domain entry — and only the code-domain entry
+
+`peaks-code` is the code-domain long-task loop engineering orchestrator — it runs the long chain (PRD, RD, QA, UI, SC, TXT) and is the role you'll talk to most. It is **not a general-purpose orchestrator** — research, content, product, and other domains are independent `peaks-*` skills that reuse the same Loop Engineering guidelines. See the Loop Engineering design `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8, and the sediment design `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`.
 
 Summon them, they handle the work. Stand them down when it's done. **No skipped steps. No half-finished hand-offs.** No new AI CLI to learn — it sits on top of Claude Code, Codex, or Copilot you already run.
 

package/README.md

@@ -7,16 +7,29 @@
 [![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
 <p align="center">
-  <video src="./examples/video-demo/preview/peaks-loop-demo.mp4" controls muted playsinline preload="metadata" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);"></video>
+  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">
+    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/zh-closing-960.png" alt="peaks-loop demo (点击播放)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
+  </a>
+  <br>
+  <sub>👆 点击图片播放 60s 演示</sub>
 </p>
 
 ## 它是什么
 
 ### loop engineering 的工程实现
 
-### peaks-loop 就是你的 AI 战术小队,24 小时待命,随时接活
+**peaks-loop 是你的 Loop Engineering 结晶系统 —— 不是工作流工具。** 它从真实完成的工作里把 loop engineering 资产结晶出来,只通过被验证的改进让它们进化。你只用自然语言和选择操作系统,所有结构化操作由 LLM 代办。
 
-它把一套工程门禁、编排、回放都装进你本地的 AI CLI 里,装好之后,你说一句话,它替你把整套流程跑完再交还给你。
+产品遵循四层资产模型与 karpathy × darwin 双层纪律,两者缺一不可:
+
+- **四层资产模型**:Loop Engineering 资产(方法体系,一等公民)+ Bee 资产(可执行体,一等公民)+ Workflow Trace(执行轨迹,只作证据,不作资产)+ Evolution Evaluation(反漂移闸门,变更必经)。
+- **karpathy × darwin 双层纪律**:karpathy 工程化每一条规则(failure modes + imperative→declarative rewrite + self-check + out-of-scope);darwin 校验每一次改进(单对象 + 单维度 + 独立上下文评估 + ratchet 防回退)。两层是平行的伙伴,谁都不是谁的子集 —— 详见 `.peaks/standards/loop-engineering-guidelines.md` 与上游参考 `multica-ai/andrej-karpathy-skills`、`alchaincyf/darwin-skill`。
+- **post-run crystallization**:`loop_release` 与 `bee_release` 只在一次真实任务跑完后才写入;pre-run 永远是 scratch。沉淀触发支持四种,user explicit 优先级最高。
+- **Human-NL-Choice-Only**:你只说话或选择,LLM 替你跑 CLI;禁止手写 JSON / manifest / form field。
+
+### peaks-code 是 code-domain 唯一的入口
+
+`peaks-code` 是 loop engineering 在 **代码域** 的长任务编排器,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。它**不是通用编排器** —— 研究 / 内容 / 产品等其他域各自是独立的 `peaks-*` 技能,复用同一份 Loop Engineering 准则。详见 Loop Engineering 设计 `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8,以及 sediment 设计 `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`。
 
 召之即来,事完收队,**不跳步,不半截扔给你**。它不是新发明一个 AI CLI,而是架在你已有的 Claude Code / Codex / Copilot 之上,把它们都调成同一支团队,只对你这一个开发者的口味。
 

package/dist/src/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/src/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/src/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;