peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/skill/skill-scheduler.js

@@ -0,0 +1,53 @@
+/**
+ * G6 — skill-level heartbeat scheduler config.
+ *
+ * Slice 2026-06-07-sub-agent-dispatch-decouple (G6): the SKILL.md front
+ * matter for a Dispatcher (peaks-code / peaks-rd / peaks-qa) can opt
+ * into a non-default heartbeat interval by including a line like:
+ *
+ *   heartbeatIntervalSec: 15
+ *
+ * The default is 30 s (RL-13 empirical sweet spot). The poller
+ * cadence is fixed at 10 s (sub-agent 30 s / poller 10 s is the
+ * jitter-resistant offset).
+ *
+ * This module is a pure-key parser — it takes a SKILL.md body and
+ * returns the effective config. The Dispatcher's prompt template
+ * for sub-agents is then responsible for inlining the chosen value
+ * into the sub-agent prompt so that the LLM knows how often to
+ * call `peaks sub-agent heartbeat`.
+ *
+ * Note: the heartbeat *cadence* the LLM uses is enforced socially
+ * (via the prompt), not via any hook. R-1 / R-8 boundary — LLM
+ * behaviour is not observable. The user has been explicit about
+ * this: "心跳是 sub-agent 主动写, peaks CLI 不观测 LLM 行为".
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_SEC = 30;
+export const MIN_HEARTBEAT_INTERVAL_SEC = 5;
+export const MAX_HEARTBEAT_INTERVAL_SEC = 600;
+/** Parse a SKILL.md body for a `heartbeatIntervalSec: <N>` line. */
+export function parseHeartbeatConfig(skillBody) {
+    const match = skillBody.match(/^\s*heartbeatIntervalSec\s*:\s*(\d+)\s*$/m);
+    if (!match) {
+        return { intervalSec: DEFAULT_HEARTBEAT_INTERVAL_SEC, source: 'default' };
+    }
+    const value = Number.parseInt(match[1], 10);
+    if (!Number.isInteger(value) || value < MIN_HEARTBEAT_INTERVAL_SEC || value > MAX_HEARTBEAT_INTERVAL_SEC) {
+        return { intervalSec: DEFAULT_HEARTBEAT_INTERVAL_SEC, source: 'default' };
+    }
+    return { intervalSec: value, source: 'skill-frontmatter' };
+}
+/**
+ * Build the heartbeat-instruction paragraph to inline in a sub-agent
+ * prompt. The LLM reads this and adjusts its `peaks sub-agent
+ * heartbeat` cadence accordingly.
+ */
+export function heartbeatInstructionParagraph(config) {
+    return (`While running, call ` +
+        `\`peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note "<text>"\` ` +
+        `at least every ${config.intervalSec} seconds (the Dispatcher expects ` +
+        `${config.intervalSec}s cadence; default 30s, your SKILL.md overrides to ${config.intervalSec}s). ` +
+        `On completion, call \`--status done --progress 100 --note "completed"\`. ` +
+        `On failure, \`--status failed\`. Do not skip heartbeats; the parent ` +
+        `Dispatcher uses them to keep the user informed during the wait.`);
+}

package/dist/services/skill/skill-search-service.d.ts

@@ -0,0 +1,93 @@
+/**
+ * peaks skill search — service-layer primitive for S0 of the
+ * 4.0.0-beta.5 peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * This service is the single source of truth for skill pool retrieval
+ * and is reused by the `peaks skill search` CLI. It is intentionally
+ * pure (synchronous frontmatter parse + substring scoring) so the
+ * dispatcher (`peaks-solo`, S1) can call it without paying for any
+ * async I/O during the triage decision flow.
+ *
+ * v1 scope (locked, see plan §"Match rules (v1)"):
+ *   - --query: case-insensitive substring match on description + triggers
+ *   - --tag:   case-insensitive exact match on `metadata.tags`
+ *   - --domain: exact match on `metadata.domain` (locked enum)
+ *   - All three compose with AND; at least one filter is required
+ *   - No match → `[]` (not error, not null)
+ *   - --limit truncates to the top N by matchScore desc
+ *
+ * Out of v1 scope (deferred, see plan §"Goal"): fuzzy / FTS5 / semantic
+ * matching, ML-based ranking, pagination, i18n, caching.
+ */
+import { z } from 'zod';
+import { skillsDir } from 'peaks-loop-shared/paths';
+export declare const SkillSearchInputSchema: z.ZodEffects<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodEnum<["code", "content", "doctor", "research", "triage", "sop", "audit", "final-review", "resume", "status", "test", "ide", "slice-decompose", "issue-fix-orchestrator", "perf-audit", "security-audit", "reviewer"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    includeInternal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    includeInternal: boolean;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    query?: string | undefined;
+    limit?: number | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    includeInternal?: boolean | undefined;
+}>, {
+    limit: number;
+    includeInternal: boolean;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    query?: string | undefined;
+    limit?: number | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    includeInternal?: boolean | undefined;
+}>;
+export type SkillSearchInput = z.input<typeof SkillSearchInputSchema>;
+export declare const SkillSearchResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    triggers: z.ZodArray<z.ZodString, "many">;
+    tags: z.ZodArray<z.ZodString, "many">;
+    domain: z.ZodString;
+    matchScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}>;
+export type SkillSearchResult = z.infer<typeof SkillSearchResultSchema>;
+/**
+ * Search the in-tree skill pool. Validates `input` against
+ * `SkillSearchInputSchema`; the schema's refine rejects empty input
+ * with a ZodError, which is the contract test U-7 / I-3 rely on.
+ *
+ * @param input  One of `query | tag | domain` is required.
+ *               All provided filters compose with AND.
+ * @returns      Matching skills sorted by matchScore desc, name asc.
+ *               Empty array (not error, not null) when nothing matches.
+ */
+export declare function searchSkills(rawInput: SkillSearchInput): Promise<SkillSearchResult[]>;
+export { skillsDir as __skillsDirForTests };

package/dist/services/skill/skill-search-service.js

@@ -0,0 +1,232 @@
+/**
+ * peaks skill search — service-layer primitive for S0 of the
+ * 4.0.0-beta.5 peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * This service is the single source of truth for skill pool retrieval
+ * and is reused by the `peaks skill search` CLI. It is intentionally
+ * pure (synchronous frontmatter parse + substring scoring) so the
+ * dispatcher (`peaks-solo`, S1) can call it without paying for any
+ * async I/O during the triage decision flow.
+ *
+ * v1 scope (locked, see plan §"Match rules (v1)"):
+ *   - --query: case-insensitive substring match on description + triggers
+ *   - --tag:   case-insensitive exact match on `metadata.tags`
+ *   - --domain: exact match on `metadata.domain` (locked enum)
+ *   - All three compose with AND; at least one filter is required
+ *   - No match → `[]` (not error, not null)
+ *   - --limit truncates to the top N by matchScore desc
+ *
+ * Out of v1 scope (deferred, see plan §"Goal"): fuzzy / FTS5 / semantic
+ * matching, ML-based ranking, pagination, i18n, caching.
+ */
+import { z } from 'zod';
+import { listSkills } from '../skills/skill-registry.js';
+import { parseFrontmatter } from '../../shared/frontmatter.js';
+import { readText } from 'peaks-loop-shared/fs';
+import { skillsDir } from 'peaks-loop-shared/paths';
+const SKILL_DOMAINS = [
+    'code',
+    'content',
+    'doctor',
+    'research',
+    'triage',
+    'sop',
+    'audit',
+    'final-review',
+    'resume',
+    'status',
+    'test',
+    'ide',
+    'slice-decompose',
+    'issue-fix-orchestrator',
+    'perf-audit',
+    'security-audit',
+    'reviewer'
+];
+export const SkillSearchInputSchema = z
+    .object({
+    query: z.string().min(1).max(500).optional(),
+    tag: z.string().min(1).max(100).optional(),
+    domain: z.enum(SKILL_DOMAINS).optional(),
+    limit: z.number().int().min(1).max(100).optional().default(20),
+    includeInternal: z.boolean().optional().default(false)
+})
+    .refine((v) => v.query !== undefined || v.tag !== undefined || v.domain !== undefined, { message: 'At least one of --query / --tag / --domain is required' });
+export const SkillSearchResultSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    triggers: z.array(z.string()),
+    tags: z.array(z.string()),
+    domain: z.string(),
+    matchScore: z.number().min(0).max(1)
+});
+/**
+ * Extract trigger phrases from a skill description. The convention is
+ * `Triggers on \`/x\`, "y", "z".` at the end of the description
+ * (or anywhere within). v1 parses quoted/back-tick tokens after the
+ * "Triggers on" marker. When the marker is missing, the trigger set
+ * is empty (description-only matching still works).
+ */
+function extractTriggers(description) {
+    const lower = description.toLowerCase();
+    const marker = 'triggers on';
+    const idx = lower.indexOf(marker);
+    if (idx === -1)
+        return [];
+    const after = description.slice(idx + marker.length);
+    // Stop at the first period that ends the trigger clause.
+    // Heuristic: take everything up to the next `.` that is followed by
+    // whitespace + capital letter, or end-of-string.
+    const stopMatch = /\.\s+[A-Z]|\.\s*$/.exec(after);
+    const clause = stopMatch ? after.slice(0, stopMatch.index + 1) : after;
+    // Extract every quoted/back-tick token.
+    const tokenRegex = /[`"']([^`"']+)[`"']/g;
+    const out = [];
+    let m;
+    while ((m = tokenRegex.exec(clause)) !== null) {
+        if (m[1] !== undefined)
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * Parse metadata tags / domain from the raw SKILL.md frontmatter.
+ * `parseFrontmatter()` flattens nested YAML mapping into dotted keys,
+ * so `metadata.tags: a, b` becomes a single string we split on `, `.
+ * The existing `skill-registry` already calls `parseFrontmatter` but
+ * does not surface the metadata block, so we re-parse the file.
+ *
+ * R8 mitigation: if the file is missing, malformed, or unreadable we
+ * return empty tags + domain so the search itself can still proceed
+ * with description-only matching. The malformed-file warning is
+ * already emitted by the registry layer (`loadSkillRegistry`'s
+ * `failures[]` channel); this function is best-effort metadata.
+ */
+async function parseMetadata(skillPath) {
+    try {
+        const raw = await readText(skillPath);
+        const fm = parseFrontmatter(raw);
+        const tagsRaw = fm['metadata.tags'] ?? '';
+        const tags = tagsRaw
+            .split(',')
+            .map((t) => t.trim())
+            .filter((t) => t.length > 0);
+        const domain = (fm['metadata.domain'] ?? '').trim();
+        return { tags, domain };
+    }
+    catch {
+        return { tags: [], domain: '' };
+    }
+}
+async function loadEnrichedSkills() {
+    const skills = await listSkills();
+    return Promise.all(skills.map(async (s) => {
+        const meta = await parseMetadata(s.skillPath);
+        return {
+            name: s.name,
+            description: s.description,
+            triggers: extractTriggers(s.description),
+            tags: meta.tags,
+            domain: meta.domain,
+            skillPath: s.skillPath,
+            ...(s.visibility !== undefined ? { visibility: s.visibility } : {})
+        };
+    }));
+}
+/**
+ * Substring match score for a single (skill, query) pair.
+ *
+ * matchScore = 0.5 * (query_hits_in_description / description_length_words)
+ *            + 0.5 * (query_hits_in_triggers / triggers_count)
+ *            clamped to [0, 1]
+ *
+ * "hits" = number of occurrences of the query substring (lowercased)
+ * in the lowercased target. Length is normalized as word count (so a
+ * 1-word description that matches returns the full 0.5 contribution).
+ */
+function scoreQuery(query, description, triggers) {
+    const q = query.toLowerCase();
+    const desc = description.toLowerCase();
+    const descHits = countOccurrences(desc, q);
+    const descWords = Math.max(1, desc.split(/\s+/).filter((w) => w.length > 0).length);
+    const descContribution = Math.min(1, descHits / descWords);
+    const triggersJoined = triggers.map((t) => t.toLowerCase()).join(' | ');
+    const trigHits = countOccurrences(triggersJoined, q);
+    const trigCount = Math.max(1, triggers.length);
+    const trigContribution = Math.min(1, trigHits / trigCount);
+    const raw = 0.5 * descContribution + 0.5 * trigContribution;
+    // Clamp to [0, 1] and round to 4 decimals to keep envelope tidy.
+    return Math.round(Math.max(0, Math.min(1, raw)) * 10_000) / 10_000;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let pos = 0;
+    while (pos <= haystack.length) {
+        const next = haystack.indexOf(needle, pos);
+        if (next === -1)
+            break;
+        count += 1;
+        pos = next + needle.length;
+    }
+    return count;
+}
+/**
+ * Search the in-tree skill pool. Validates `input` against
+ * `SkillSearchInputSchema`; the schema's refine rejects empty input
+ * with a ZodError, which is the contract test U-7 / I-3 rely on.
+ *
+ * @param input  One of `query | tag | domain` is required.
+ *               All provided filters compose with AND.
+ * @returns      Matching skills sorted by matchScore desc, name asc.
+ *               Empty array (not error, not null) when nothing matches.
+ */
+export async function searchSkills(rawInput) {
+    const input = SkillSearchInputSchema.parse(rawInput);
+    const skills = await loadEnrichedSkills();
+    const filtered = skills.filter((skill) => {
+        if (!input.includeInternal && skill.visibility === 'internal')
+            return false;
+        if (input.tag !== undefined) {
+            const wanted = input.tag.toLowerCase();
+            const has = skill.tags.some((t) => t.toLowerCase() === wanted);
+            if (!has)
+                return false;
+        }
+        if (input.domain !== undefined) {
+            if (skill.domain.toLowerCase() !== input.domain.toLowerCase())
+                return false;
+        }
+        if (input.query !== undefined) {
+            const q = input.query.toLowerCase();
+            const inDesc = skill.description.toLowerCase().includes(q);
+            const inTrig = skill.triggers.some((t) => t.toLowerCase().includes(q));
+            if (!inDesc && !inTrig)
+                return false;
+        }
+        return true;
+    });
+    const scored = filtered.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+        triggers: skill.triggers,
+        tags: skill.tags,
+        domain: skill.domain,
+        matchScore: input.query !== undefined
+            ? scoreQuery(input.query, skill.description, skill.triggers)
+            : 1
+    }));
+    scored.sort((a, b) => {
+        if (b.matchScore !== a.matchScore)
+            return b.matchScore - a.matchScore;
+        return a.name.localeCompare(b.name);
+    });
+    return scored.slice(0, input.limit);
+}
+// Re-export `skillsDir` only for tests that want to assert on-disk I/O
+// behavior end-to-end. Not part of the public CLI surface.
+export { skillsDir as __skillsDirForTests };

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);