peaks-loop 4.0.0-beta.11 → 4.0.0-beta.14

package/CHANGELOG.md

@@ -2,9 +2,71 @@
 
 ## [Unreleased]
 
-## 4.0.0-beta.11 — 2026-07-16
+## 4.0.0-beta.14 — 2026-07-16
 
-### Status: RELEASED (release of `4.0.0-beta.10` contract; same source tree)
+### Status: RELEASED (D-019: copy-templates.mjs + package.json files[])
+
+> **This release fixes D-019 (full end-to-end)**:
+>
+> 1. `scripts/copy-templates.mjs` now copies
+>    `src/services/skillhub/migrations/*.sql` into `dist/services/skillhub/migrations/`.
+> 2. `package.json` `"files"` whitelist now includes `dist/**/*.sql`
+>    (previously the whitelist was `dist/**/*.js | .d.ts | .md` only,
+>    so the migrations were filtered out of the npm tarball even
+>    after being copied to `dist/`).
+>
+> Without this fix, the published `peaks-loop` tarball shipped without
+> the SkillHub SQLite schema, breaking any downstream consumer's first
+> `peaks skill sediment <verb>` with `no such table: bee_release`.
+>
+> **Verdict**: `pnpm build` copies 6 migrations; tarball includes them.
+> In-process vitest tests were always green (they use tsx + source tree
+> directly, not `dist/`), so no test count change. Combined with
+> 4.0.0-beta.13's D-018 path fix, the published tarball is now
+> correct end-to-end.
+
+## 4.0.0-beta.13 — 2026-07-16
+
+### Status: RELEASED (D-018: state.db path relocation)
+
+> **This release fixes the SQLite `state.db` location** to match the
+> original peaks-loop design contract: `PEAKS_HOME/.peaks/skills/state.db`
+> (PEAKS_HOME defaults to `~/.peaks`). Previously, the code resolved
+> `home` to `process.cwd()` when invoked from a project root, producing
+> `<project>/.peaks/state.db` — wrong location for loop engineering
+> + bee sediment data.
+>
+> **Fix**: `src/cli/commands/sediment-commands.ts:664-665` now uses
+> `peaksHome()` from `src/services/sop/sop-paths.ts:29` (which honors
+> `PEAKS_HOME` override for test isolation). The downstream
+> `resolveStateDbPath({ home })` (in `src/services/sediment/pool-paths.ts:15`)
+> already correctly returned `{home}/.peaks/skills/state.db`; only the
+> `home` resolution was broken.
+>
+> **Side bug found but out of scope**: `src/services/skillhub/migrations/*.sql`
+> is not copied to `dist/` by `scripts/copy-templates.mjs`. This is a
+> pre-existing build-config issue separate from D-018. Tracked as
+> follow-up; tests still pass because the tests use vitest + tsx
+> (which sees the source tree directly), but the published
+> `peaks-loop@4.0.0-beta.13` will hit `no such table: bee_release` until
+> a D-019 follow-up adds `.sql` to the copy-templates extensions.
+>
+> **Verdict**: 27/27 AC PASS (beta.12 verdict preserved; D-018 is
+> architecture fix, no AC change). Old `<peaks-loop>/.peaks/state.db`
+> discarded (beta phase, single user).
+
+## 4.0.0-beta.12 — 2026-07-16
+
+### Status: RELEASED (follow-up to `4.0.0-beta.11`; D-013 wrapper exit-code fix)
+
+> **This CHANGELOG entry documents the D-013 follow-up release.
+> Same source tree as `4.0.0-beta.11`; pure fix for the wrapper
+> exit-code bug that previously caused `peaks <unknown>` and
+> `peaks <unknown> --help` to exit 0 with the help banner.
+>
+> **Verdict**: All 4 regression paths now exit 1 with a
+> `COMMAND_NOT_FOUND` JSON envelope. ice-cola baseline 27/27 PASS
+> (AC3.9/AC3.10 now functionally correct).
 
 > **This CHANGELOG entry documents the SHIPPED 4.0.0-beta.11.
 > It is the post-implementation release of the 4.0.0-beta.10 contract

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

@@ -27,6 +27,7 @@
 import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { join, basename } from "node:path";
 import { SYSTEM_PATH_FORBIDDEN, assertNotSystemPath, resolveSegmentsDir, resolveStateDbPath, resolveBlobsDir, resolveUserBeesDir, resolveUserBeeDir, } from "../../services/sediment/pool-paths.js";
+import { peaksHome } from "../../services/sop/sop-paths.js";
 import { writeBeeManifest } from "../../services/sediment/pool-write.js";
 import { readPool } from "../../services/sediment/pool-read.js";
 import { rebuildIndexFromFs } from "../../services/sediment/pool-rebuild-index.js";
@@ -636,7 +637,15 @@ export function registerSedimentCommands(program, io) {
         .command("sediment <args...>")
         .description("Sediment pool operations (LLM-coordinated; see peaks-maker skill)")
         .action(async (args) => {
-        const home = process.env.HOME ?? process.env.USERPROFILE ?? process.cwd();
+        // D-018: peaks-loop's `state.db` (loop engineering + bee sediment pool)
+        // lives at PEAKS_HOME-based path, NOT under the project root. The
+        // original `process.env.HOME ?? USERPROFILE ?? process.cwd()` would
+        // resolve `home` to cwd when invoked from a project (e.g.
+        // `peaks skill sediment list` from peaks-loop/), producing
+        // `<project>/.peaks/state.db` — wrong. Per design contract
+        // (peaks-maker SKILL.md §22 + sop-paths.ts §29), the canonical
+        // home is `~/.peaks` (or PEAKS_HOME override for test isolation).
+        const home = peaksHome();
         const r = await runSediment(args, { home });
         // Delegate the JSON rendering AND the process.exitCode side-effect
         // to the shared CLI shim helper (Critical #1 fix). The library

package/dist/cli/index.js

@@ -1,18 +1,70 @@
 import { CommanderError } from 'commander';
 import { createProgram } from './program.js';
 import { getErrorMessage } from '../shared/result.js';
+// D-013 wrapper exit-code fix (PART 2): Commander's `--help` short-circuit
+// fires BEFORE `commander.unknownCommand` is raised, so `peaks xxx --help`
+// (where `xxx` is not a registered command) prints the help banner and
+// exits 0 instead of 1. Detect this case BEFORE Commander runs by scanning
+// `process.argv` for a non-option positional token. If present AND
+// `--help` is also present, the user asked for help on an unknown command
+// — emit `COMMAND_NOT_FOUND` envelope + exit 1.
+//
+// This pre-check is intentionally conservative: only fires when BOTH a
+// positional token AND `--help`/`-h` are present. Bare `--help` (no
+// positional) is legitimate help → exit 0. Positional without `--help`
+// is handled by the root `.action()` in `program.ts`.
+const argv = process.argv.slice(2);
+const hasHelp = argv.some((arg) => arg === '--help' || arg === '-h');
+const firstPositional = argv.find((arg) => !arg.startsWith('-'));
+if (hasHelp && firstPositional !== undefined) {
+    // Defer the check by 0ms so Commander's own help handler runs first
+    // (it will print help text + try to exit 0). We then override.
+    setImmediate(() => {
+        console.error(JSON.stringify({
+            ok: false,
+            command: 'cli',
+            code: 'COMMAND_NOT_FOUND',
+            message: `Unknown command: ${firstPositional}. Run \`peaks --help\` for available commands.`,
+            data: { argv: firstPositional, combinedWithHelp: true },
+            warnings: [],
+            nextActions: ['Run `peaks --help` to list available commands.']
+        }, null, 2));
+        process.exit(1);
+    });
+}
 createProgram().parseAsync(process.argv).catch((error) => {
     if (error instanceof CommanderError && error.code === 'commander.version') {
         return;
     }
-    // exitOverride() also throws for help; suppress those — the text already went
-    // to stdout/stderr, the error envelope confuses newcomers. --help is success
-    // (exit 0); a bad command/option is an error (exit 1).
+    // D-013 wrapper exit-code fix: distinguish "bare `peaks --help` /
+    // `peaks help <cmd>`" (legitimate help, exit 0) from
+    // "`peaks <unknown> --help`" (user typed a non-existent command,
+    // even if they added --help, the command itself is invalid → exit 1).
+    // Commander only emits `commander.helpDisplayed` for the LEGITIMATE
+    // help path (bare `--help` or a registered subcommand's help). For
+    // unknown commands, Commander throws `commander.unknownCommand`
+    // BEFORE the help text is rendered, so we route that case to the
+    // unknownCommand branch below. This preserves the historical behavior
+    // for valid help while fixing the unknown-command exit code.
     if (error instanceof CommanderError) {
         if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
             return;
         }
         if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
+            // Emit a `COMMAND_NOT_FOUND` JSON envelope for the unknown-command
+            // path. The error text already went to stderr via Commander's
+            // default handler; we add a structured envelope for LLM-side
+            // consumers (Human-NL-Choice-Only: don't tell the human to type
+            // a CLI verb — say what the LLM can coordinate).
+            console.error(JSON.stringify({
+                ok: false,
+                command: 'cli',
+                code: 'COMMAND_NOT_FOUND',
+                message: getErrorMessage(error),
+                data: {},
+                warnings: [],
+                nextActions: ['Run `peaks --help` to list available commands.']
+            }, null, 2));
             process.exitCode = 1;
             return;
         }

package/dist/cli/program.js

@@ -207,6 +207,40 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
         }
     })
         .action(() => {
+        // D-013 wrapper exit-code fix: when the user typed a command token but
+        // it didn't match any registered subcommand, exit non-zero with a JSON
+        // `COMMAND_NOT_FOUND` envelope. Without this check, Commander's root
+        // `.action()` runs whenever no subcommand matches (including unknown
+        // commands) and prints the help banner with exit 0 — which violates
+        // the PRD AC3.9/AC3.10 contract for `peaks agent run/list` and any
+        // other deleted/hidden command.
+        //
+        // Detection: use `program.args` (Commander's parsed argv) for the
+        // first non-option token. If it's present and Commander didn't route
+        // to a subcommand (we got here, so it didn't), the user typed an
+        // unknown command. Exit 1. `program.args` works correctly under both
+        // `parseAsync(['node', 'peaks', ...])` (real CLI) and direct in-process
+        // calls (vitest integration tests), unlike `process.argv` which is
+        // the test runner's argv.
+        //
+        // --help and --version bypass this path entirely (handled below).
+        const firstNonOption = program.args.find((arg) => !arg.startsWith('-'));
+        if (firstNonOption !== undefined) {
+            // Commander reached this `.action()` despite a positional token,
+            // which means the token was NOT routed to any subcommand. This is
+            // the unknown-command path. Emit a JSON envelope + exit 1.
+            io.stdout(JSON.stringify({
+                ok: false,
+                command: 'cli',
+                code: 'COMMAND_NOT_FOUND',
+                message: `Unknown command: ${firstNonOption}. Run \`peaks --help\` for available commands.`,
+                data: { argv: firstNonOption },
+                warnings: [],
+                nextActions: ['Run `peaks --help` to list available commands.']
+            }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
         const opts = program.opts();
         if (opts.V || opts.version) {
             // AC1: write the peaks-loop start log line BEFORE printing the

package/dist/services/skillhub/migrations/001-initial.sql

@@ -0,0 +1,71 @@
+-- 001-initial.sql: spec §3.3.1 — decomposed 6-table schema.
+-- Manifest fields are first-class columns. Files are content-addressed in `blobs/` sidecar (not in this DB).
+
+CREATE TABLE IF NOT EXISTS bee_release (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  bee_name        TEXT NOT NULL,
+  version         TEXT NOT NULL,
+  source          TEXT NOT NULL CHECK (source IN ('user')),
+  archived_at     TEXT NOT NULL,
+  archived_by     TEXT NOT NULL,
+  user_intent_raw TEXT,
+  description     TEXT,
+  parent_version  TEXT,
+  changelog       TEXT,
+  UNIQUE(bee_name, version)
+);
+
+CREATE TABLE IF NOT EXISTS bee_release_pointer (
+  bee_name        TEXT PRIMARY KEY,
+  latest_version  TEXT NOT NULL,
+  released_at     TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS bee_manifest (
+  release_id          INTEGER PRIMARY KEY REFERENCES bee_release(id) ON DELETE CASCADE,
+  schema_version      TEXT NOT NULL,
+  description         TEXT NOT NULL,
+  segments_json       TEXT NOT NULL,        -- segment NAMES only; small JSON array
+  entrypoint_preamble TEXT,
+  promotion           TEXT NOT NULL,
+  min_cycles          INTEGER,
+  requires_human      INTEGER NOT NULL,
+  requires_smoke      INTEGER NOT NULL,
+  retire_on_misses    INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS bee_segment_ref (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  release_id      INTEGER NOT NULL REFERENCES bee_release(id) ON DELETE CASCADE,
+  segment_name    TEXT NOT NULL,
+  inputs_json     TEXT,
+  outputs_json    TEXT,
+  side_effects    TEXT,
+  UNIQUE(release_id, segment_name)
+);
+
+CREATE TABLE IF NOT EXISTS bee_file (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  release_id      INTEGER NOT NULL REFERENCES bee_release(id) ON DELETE CASCADE,
+  owner_kind      TEXT NOT NULL CHECK (owner_kind IN ('bee','segment')),
+  owner_name      TEXT NOT NULL,
+  path            TEXT NOT NULL,
+  kind            TEXT NOT NULL CHECK (kind IN ('markdown','script','reference','binary','other')),
+  size_bytes      INTEGER NOT NULL,
+  sha256          TEXT NOT NULL,
+  blob_path       TEXT NOT NULL,
+  UNIQUE(release_id, owner_kind, owner_name, path)
+);
+
+CREATE TABLE IF NOT EXISTS bee_change (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  release_id      INTEGER NOT NULL REFERENCES bee_release(id) ON DELETE CASCADE,
+  change_kind     TEXT NOT NULL,
+  target_kind     TEXT NOT NULL,
+  target_name     TEXT NOT NULL,
+  detail          TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_bee_release_name_archived_at ON bee_release(bee_name, archived_at DESC);
+CREATE INDEX IF NOT EXISTS idx_bee_segment_ref_release ON bee_segment_ref(release_id);
+CREATE INDEX IF NOT EXISTS idx_bee_file_release_owner ON bee_file(release_id, owner_kind, owner_name);

package/dist/services/skillhub/migrations/002-loop-release.sql

@@ -0,0 +1,32 @@
+-- 002-loop-release.sql — M1 / spec §4.1 / §7.2
+-- Adds the `loop_release` table for the Loop Engineering Asset layer.
+-- Non-breaking: this migration does NOT touch any 4.x `bee_release`
+-- column. The new table lives alongside the existing 6-table skillhub
+-- schema (see 001-initial.sql). Indexes:
+--   - lifecycle_status: for `peaks loop list --status <status>` filters.
+--   - scenario:         for `peaks loop search --query <q>` (LIKE-based
+--                       full-text in M1; FTS5 promotion deferred to a
+--                       later slice).
+-- Schema versioning: every new table carries `schema_version`.
+
+CREATE TABLE IF NOT EXISTS loop_release (
+  id                       TEXT PRIMARY KEY,
+  name                     TEXT NOT NULL,
+  scenario                 TEXT NOT NULL,
+  trigger_policy           TEXT NOT NULL,
+  success_criteria_json    TEXT NOT NULL,   -- JSON array of strings
+  interaction_policy       TEXT NOT NULL,
+  feedback_policy          TEXT NOT NULL,
+  evolution_policy         TEXT NOT NULL,
+  evaluator_policy_json    TEXT NOT NULL,   -- JSON array of strings
+  linked_bees_json         TEXT NOT NULL DEFAULT '[]',
+  run_history_json         TEXT NOT NULL DEFAULT '[]',
+  crystallization_evidence_json TEXT NOT NULL DEFAULT '[]',
+  lifecycle_status         TEXT NOT NULL CHECK (lifecycle_status IN ('candidate','stable','retired')),
+  version                  TEXT NOT NULL,
+  schema_version           TEXT NOT NULL CHECK (schema_version = 'peaks.loop/1'),
+  archived_at              TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_loop_release_lifecycle_status ON loop_release(lifecycle_status);
+CREATE INDEX IF NOT EXISTS idx_loop_release_scenario ON loop_release(scenario);

package/dist/services/skillhub/migrations/003-loop-bee-relation.sql

@@ -0,0 +1,35 @@
+-- 003-loop-bee-relation.sql — M2 / spec §4.6 / §7.2
+-- Adds the `loop_bee_relation` table for the Loop↔Bee coupling layer.
+-- Non-breaking: this migration does NOT touch any 4.x `bee_release`
+-- column. The new table lives alongside the existing skillhub schema
+-- (see 001-initial.sql, 002-loop-release.sql).
+--
+-- Constraints:
+--   - FK to loop_release(id) and bee_release(id) — referential integrity.
+--   - UNIQUE(loop_release_id, bee_release_id) — no duplicate relations.
+--   - Partial UNIQUE index WHERE role='main' — at most one main bee per
+--     loop at the storage layer (defense in depth; the service layer
+--     adds a friendlier error path).
+--   - role CHECK constraint enforces the four-value union.
+--   - schema_version column carries 'peaks.loop-bee-relation/1'.
+--
+-- The "no relation to a retired loop" rule is NOT a DB-level constraint
+-- (cross-table policy; needs richer error reporting). It is enforced in
+-- the LoopBeeRelationService layer.
+
+CREATE TABLE IF NOT EXISTS loop_bee_relation (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  loop_release_id   TEXT NOT NULL REFERENCES loop_release(id) ON DELETE CASCADE,
+  bee_release_id    INTEGER NOT NULL REFERENCES bee_release(id) ON DELETE CASCADE,
+  role              TEXT NOT NULL CHECK (role IN ('main','supporting','candidate','retired')),
+  reason            TEXT NOT NULL,
+  schema_version    TEXT NOT NULL CHECK (schema_version = 'peaks.loop-bee-relation/1'),
+  created_at        TEXT NOT NULL,
+  UNIQUE(loop_release_id, bee_release_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_loop_id ON loop_bee_relation(loop_release_id);
+CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_bee_id ON loop_bee_relation(bee_release_id);
+CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_loop_role ON loop_bee_relation(loop_release_id, role);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_loop_bee_relation_one_main_per_loop
+  ON loop_bee_relation(loop_release_id) WHERE role = 'main';

package/dist/services/skillhub/migrations/004-loop-bee-extension.sql

@@ -0,0 +1,65 @@
+-- 004-loop-bee-extension.sql — M3 / spec §4.1 / §4.2 / §7A
+-- Adds the share / desktop extension fields to `loop_release` and
+-- `bee_release`. The migration is non-breaking: every new column has
+-- a DEFAULT, so existing 4.x rows continue to read cleanly with the
+-- spec values applied. M3 writes the SCHEMA only — `shareable=false`
+-- is NOT enforced anywhere yet; full export / desktop enforcement
+-- lands in M7 (see plan m3-bee-release-extension.md).
+--
+-- AC-3: this migration does NOT modify any pre-existing `bee_release`
+-- column. The only changes to `bee_release` are two new columns
+-- appended at the end of the table:
+--
+--   - shareable         BOOLEAN  (default true)
+--   - desktop_visible   BOOLEAN  (default true)
+--
+-- All other 4.x `bee_release` columns keep their definitions from
+-- 001-initial.sql.
+--
+-- For `loop_release` we add four new columns:
+--
+--   - shareable              BOOLEAN  (default true)
+--   - share_excluded_paths   TEXT     (default '[]'  — JSON array)
+--   - desktop_visible        BOOLEAN  (default true)
+--   - export_bundle_format   TEXT     (default 'peaks.bundle/1')
+--
+-- Notes on the column choices:
+--   - share_excluded_paths is TEXT (JSON-encoded array). Matches the
+--     existing `loop_release` style (success_criteria_json, etc.);
+--     parsing happens at the store / Zod boundary, not at SQLite.
+--   - export_bundle_format is a TEXT constant. The CHECK constraint
+--     below pins the column to 'peaks.bundle/1' — there is no other
+--     valid value in this schema version. M7 may relax this when a
+--     v2 format lands; until then the constant is hard-pinned.
+--   - DEFAULT 1 / 0 covers both columns for SQLite (no native
+--     BOOLEAN — the JS layer normalizes to boolean on read).
+--   - The CHECK constraints on `shareable` and `desktop_visible`
+--     accept only 0/1 (SQLite's BOOLEAN idiom). The Zod schema on
+--     read coerces 0/1 to true/false.
+--
+-- Defense in depth: defaults are set both here (storage) and in the
+-- Zod schema (parse boundary) so an in-memory object created from a
+-- pre-M3 snapshot still parses after the migration runs.
+
+ALTER TABLE loop_release
+  ADD COLUMN shareable INTEGER NOT NULL DEFAULT 1
+    CHECK (shareable IN (0, 1));
+
+ALTER TABLE loop_release
+  ADD COLUMN share_excluded_paths TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE loop_release
+  ADD COLUMN desktop_visible INTEGER NOT NULL DEFAULT 1
+    CHECK (desktop_visible IN (0, 1));
+
+ALTER TABLE loop_release
+  ADD COLUMN export_bundle_format TEXT NOT NULL DEFAULT 'peaks.bundle/1'
+    CHECK (export_bundle_format = 'peaks.bundle/1');
+
+ALTER TABLE bee_release
+  ADD COLUMN shareable INTEGER NOT NULL DEFAULT 1
+    CHECK (shareable IN (0, 1));
+
+ALTER TABLE bee_release
+  ADD COLUMN desktop_visible INTEGER NOT NULL DEFAULT 1
+    CHECK (desktop_visible IN (0, 1));

package/dist/services/skillhub/migrations/005-evolution-evaluation.sql

@@ -0,0 +1,81 @@
+-- 005-evolution-evaluation.sql — M4 / spec §4.4 / §6
+-- Adds the `evolution_evaluation` table for the Darwin-style ratchet
+-- evaluation layer. Non-breaking: this migration does NOT touch any
+-- pre-existing table. The new table lives alongside the existing
+-- skillhub schema (see 001-initial.sql, 002-loop-release.sql,
+-- 003-loop-bee-relation.sql, 004-loop-bee-extension.sql).
+--
+-- The table stores the durable evidence of an evolution round:
+--   - target_kind / target_release_id / single_optimization_dimension
+--     (AC-8: single editable asset + single dimension per round).
+--   - before_score / after_score / score_delta_min / score_delta
+--     (AC-11: numeric delta; promotion blocked when delta < delta_min).
+--   - author_id / evaluator_id / skeptic_id
+--     (AC-10: author != scorer; the regression skeptic is a SEPARATE
+--     agent, not the same as the independent evaluator).
+--   - verdict (keep / revert / needs-user-decision).
+--   - user_confirmation_pointer / brief_pointer
+--     (spec §4.4: pointers, not inlined big JSON BLOBs).
+--
+-- Schema versioning: every new table carries `schema_version`
+-- pinned to the literal `peaks.evolution/1` via CHECK constraint.
+--
+-- All JSON-shaped payloads (diff, brief_pointer, source_traces_json)
+-- are stored as TEXT and parsed at the store / Zod boundary — same
+-- convention as the existing tables; no big JSON BLOB at the SQLite
+-- layer.
+
+CREATE TABLE IF NOT EXISTS evolution_evaluation (
+  id                          TEXT PRIMARY KEY,
+  target_kind                 TEXT NOT NULL CHECK (target_kind IN ('loop','bee','policy','gate','evaluator')),
+  target_release_id           TEXT NOT NULL,
+  -- The M4 spec requires exactly one optimization dimension per round.
+  -- The TEXT column carries the dimension name; the service layer
+  -- (EvolutionService) enforces `dimensions.length === 1` on input.
+  -- A JSON array is used here only so future schema versions can
+  -- relax the single-dimension rule without a column-rename
+  -- migration; for now the array is always exactly length 1.
+  optimization_dimensions_json TEXT NOT NULL,
+  -- AC-8: target_count must be exactly 1. Stored as INTEGER for
+  -- explicit service-layer enforcement; CHECK pins it to 1 in this
+  -- schema version (a future multi-target table would relax this).
+  target_count                INTEGER NOT NULL DEFAULT 1 CHECK (target_count = 1),
+  before_snapshot_json        TEXT NOT NULL DEFAULT '{}',
+  after_snapshot_json         TEXT NOT NULL DEFAULT '{}',
+  diff_json                   TEXT NOT NULL DEFAULT '{}',
+  before_score                REAL NOT NULL,
+  after_score                 REAL NOT NULL,
+  score_delta_min             REAL NOT NULL DEFAULT 1.0 CHECK (score_delta_min >= 0),
+  score_delta                 REAL NOT NULL,
+  author_id                   TEXT NOT NULL,
+  evaluator_id                TEXT NOT NULL,
+  skeptic_id                  TEXT NOT NULL,
+  -- Verdict is the FINAL aggregation result; `needs-user-decision`
+  -- is the default after the scoring + skeptic step.
+  verdict                     TEXT NOT NULL CHECK (verdict IN ('keep','revert','needs-user-decision')),
+  -- Pointer columns (NOT inlined JSON): user_confirmation_pointer and
+  -- brief_pointer are spec §4.4 fields. We keep them as TEXT paths /
+  -- ids so the table stays small and queryable.
+  user_confirmation_pointer   TEXT,
+  brief_pointer               TEXT,
+  -- Audit columns: rubric + red_lines + source_traces are
+  -- JSON-encoded TEXT — same convention as the other tables.
+  rubric_json                 TEXT NOT NULL DEFAULT '{}',
+  red_lines_json              TEXT NOT NULL DEFAULT '[]',
+  source_traces_json          TEXT NOT NULL DEFAULT '[]',
+  schema_version              TEXT NOT NULL CHECK (schema_version = 'peaks.evolution/1'),
+  created_at                  TEXT NOT NULL,
+  -- Defense in depth: the author MUST NOT equal the evaluator.
+  -- Cross-column CHECK rejected by older SQLite versions; we let the
+  -- service layer enforce this so the constraint stays portable.
+  CHECK (length(id) > 0)
+);
+
+CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_target
+  ON evolution_evaluation(target_kind, target_release_id);
+CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_verdict
+  ON evolution_evaluation(verdict);
+CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_author
+  ON evolution_evaluation(author_id);
+CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_evaluator
+  ON evolution_evaluation(evaluator_id);

package/dist/services/skillhub/migrations/006-crystallization-event.sql

@@ -0,0 +1,92 @@
+-- 006-crystallization-event.sql — M5 / spec §4.5 / §4.7 / §5 / §7.2
+-- Adds the `crystallization_event` table for the post-run
+-- crystallization layer. Non-breaking: this migration does NOT
+-- touch any pre-existing table. The new table lives alongside the
+-- existing skillhub schema (see 001-initial.sql, 002-loop-release.sql,
+-- 003-loop-bee-relation.sql, 004-loop-bee-extension.sql,
+-- 005-evolution-evaluation.sql).
+--
+-- The table stores the durable evidence of a crystallization event:
+--   - trigger                          (user_explicit | llm_suggested |
+--                                       success_default_prompt |
+--                                       similar_task_recurrence)
+--   - evidence_brief                   (JSON: 4 sections)
+--       * what_happened                (1-2 sentence factual account)
+--       * why_it_matters               (1-2 sentence explanation)
+--       * what_learned                 (1-2 sentence learning)
+--       * what_action                  (1 sentence recommended action)
+--   - source_trace_pointers            (JSON array of workflow trace ids)
+--   - evaluator_summary                (short NL summary from scorers)
+--   - user_decision_summary            (NL account of the user choice)
+--   - created_loop_release_id          (FK to loop_release, optional)
+--   - updated_loop_release_id          (FK to loop_release, optional)
+--   - created_bee_release_id           (FK to bee_release, optional)
+--   - updated_bee_release_id           (FK to bee_release, optional)
+--   - lifecycle_status                 (candidate | stable | retired;
+--                                       the EVENT's status, distinct
+--                                       from the loop_release status).
+--
+-- The four-section brief (spec §4.7 / §10 RL-7) is required at the
+-- service layer; the DB stores whatever JSON the service persists. A
+-- schema-version bump can introduce a CHECK shape constraint on the
+-- brief in a future migration; the service layer is the authoritative
+-- guard today.
+--
+-- Schema versioning: every new table carries `schema_version` pinned
+-- to the literal `peaks.crystallization/1` via CHECK constraint.
+--
+-- All JSON-shaped payloads (brief, source_trace_pointers, bullets)
+-- are stored as TEXT and parsed at the store / Zod boundary —
+-- same convention as the existing tables; no big JSON BLOB at the
+-- SQLite layer.
+
+CREATE TABLE IF NOT EXISTS crystallization_event (
+  id                          TEXT PRIMARY KEY,
+  trigger                     TEXT NOT NULL CHECK (trigger IN (
+                                'user_explicit',
+                                'llm_suggested',
+                                'success_default_prompt',
+                                'similar_task_recurrence'
+                              )),
+  -- The 4-section brief. The shape guard (all four sections present)
+  -- is enforced at the service layer (CrystallizationService); the
+  -- DB stores whatever the service persists. See spec §4.7 / §10 RL-7.
+  evidence_brief_json         TEXT NOT NULL,
+  evidence_bullets_json       TEXT NOT NULL DEFAULT '[]',
+  source_trace_pointers_json  TEXT NOT NULL DEFAULT '[]',
+  evaluator_summary           TEXT NOT NULL DEFAULT '',
+  user_decision_summary       TEXT NOT NULL DEFAULT '',
+  created_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+  updated_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+  created_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+  updated_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+  -- The EVENT's lifecycle (independent of any created/updated asset).
+  -- 'candidate' after crystallization; 'stable' after user-confirmed
+  -- promotion; 'retired' after explicit dispose. Mirrors the loop
+  -- status union (spec §4.1) without a 1:1 identity — these are
+  -- orthogonal lifecycles.
+  lifecycle_status            TEXT NOT NULL DEFAULT 'candidate'
+                                CHECK (lifecycle_status IN ('candidate','stable','retired')),
+  schema_version              TEXT NOT NULL CHECK (schema_version = 'peaks.crystallization/1'),
+  created_at                  TEXT NOT NULL,
+  CHECK (length(id) > 0),
+  -- Defense in depth on the brief shape: at least one of the four
+  -- keys must be present in the JSON object. SQLite JSON1 (>= 3.38)
+  -- supports json_extract; we keep the check loose (length > 2 to
+  -- rule out '{}') so older SQLite still accepts the row, and rely
+  -- on the service-layer guard for the strict 4-section rule.
+  CHECK (length(evidence_brief_json) >= 2)
+);
+
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_loop
+  ON crystallization_event(created_loop_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_loop
+  ON crystallization_event(updated_loop_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_bee
+  ON crystallization_event(created_bee_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_bee
+  ON crystallization_event(updated_bee_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_lifecycle
+  ON crystallization_event(lifecycle_status);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_at
+  ON crystallization_event(created_at);

package/dist/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "4.0.0-beta.11";
+export declare const CLI_VERSION = "4.0.0-beta.14";

package/dist/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "4.0.0-beta.11";
+export const CLI_VERSION = "4.0.0-beta.14";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.11",
+  "version": "4.0.0-beta.14",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.md",
+    "dist/**/*.sql",
     "scripts/clean-dist.mjs",
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",

package/scripts/copy-templates.mjs

@@ -9,6 +9,15 @@
  * therefore only get the dynamically-generated `project-scan.md` and
  * the 4 audit/business templates would silently be missing.
  *
+ * D-019 (2026-07-16): also copy the SkillHub SQLite migrations
+ * (`src/services/skillhub/migrations/*.sql`) into dist/. Without this,
+ * the published `peaks-loop` tarball ships an empty
+ * `dist/services/skillhub/migrations/` and `openStateDb()` opens a
+ * schema-less database, breaking any `peaks skill sediment <verb>`
+ * on a fresh consumer install. Vitest tests still pass because they
+ * use tsx + the source tree directly, but downstream npm consumers
+ * see `no such table: bee_release` on the very first command.
+ *
  * Idempotent: safe to run multiple times. Run after `tsc` in `build`.
  */
 import { copyFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
@@ -44,6 +53,13 @@ const targets = [
     src: join(packageRoot, 'src/services/workspace/templates/project-scan'),
     dest: join(packageRoot, 'dist/services/workspace/templates/project-scan'),
     extensions: ['.md']
+  },
+  {
+    // D-019: SkillHub SQLite migrations must reach the published tarball
+    // so `openStateDb()` can apply the schema on first run.
+    src: join(packageRoot, 'src/services/skillhub/migrations'),
+    dest: join(packageRoot, 'dist/services/skillhub/migrations'),
+    extensions: ['.sql']
   }
 ];