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

package/dist/services/share/run-state-contract.js

@@ -0,0 +1,138 @@
+/**
+ * run-state-contract.ts — locked read-only shape for the desktop
+ * client (spec §7A.3 / §10 RL-9).
+ *
+ * The desktop client observes an in-flight bee through a single
+ * JSON file. This module locks the shape so the desktop can render
+ * progress without holding a lock on the asset:
+ *
+ *   {
+ *     bee_id:                    string,
+ *     status:                    "running" | "paused" | "done" | "failed" | "blocked",
+ *     current_step:              string,
+ *     started_at:                ISO8601 string,
+ *     updated_at:                ISO8601 string,
+ *     last_evaluator_verdict:    string | null,
+ *     last_user_choice:          string | null
+ *   }
+ *
+ * Hard rules (spec §7A.3):
+ *   - The contract is read-only for the desktop client. Only the
+ *     running bee (and peaks CLI) may write it.
+ *   - The shape is locked — adding a field is a schema-version
+ *     bump; removing or renaming a field is a breaking change.
+ *
+ * This module exposes:
+ *   - A Zod schema (`RunStateContractSchema`) that validates the
+ *     shape with strict rules (no extra keys, exact enum for
+ *     status).
+ *   - A type alias (`RunStateContract`).
+ *   - A constructor-like factory (for testing / fixtures).
+ *
+ * It does NOT expose any mutation helpers — there are no setters,
+ * because the contract is read-only at the desktop. The running
+ * bee writes the file via the existing dispatch flow; the desktop
+ * client reads via a separate channel.
+ */
+import { z } from "zod";
+/* ---------------------------------------------------------------------- */
+/* Shape contract                                                            */
+/* ---------------------------------------------------------------------- */
+/**
+ * The five status values an in-flight bee may report. The
+ * desktop-client UI renders the status badge; only the running bee
+ * transitions between them.
+ */
+export const RUN_STATE_STATUSES = [
+    "running",
+    "paused",
+    "done",
+    "failed",
+    "blocked",
+];
+/**
+ * RunStateContract — the locked read-only shape (spec §7A.3).
+ *
+ * Notes:
+ *   - `bee_id`, `current_step`: non-empty NL strings.
+ *   - `started_at`, `updated_at`: ISO8601; updated_at >= started_at
+ *     is the caller's job (the schema does not check ordering
+ *     because a clock skew between the dispatcher and the receiver
+ *     is a transient runtime issue, not a shape invariant).
+ *   - `last_evaluator_verdict`: optional NL string; null when no
+ *     evaluator has fired yet.
+ *   - `last_user_choice`: optional NL choice summary; null when
+ *     the user has not made a pick yet.
+ *
+ * `.strict()` rejects unknown keys — adding a field is a
+ * schema-version bump, not a quiet extension.
+ */
+export const RunStateContractSchema = z
+    .object({
+    /** Stable bee id (kebab-case). */
+    bee_id: z.string().min(1).max(64),
+    /** Current run status (running / paused / done / failed / blocked). */
+    status: z.enum(RUN_STATE_STATUSES),
+    /** Current step name; NL short label. */
+    current_step: z.string().min(1).max(256),
+    /** ISO8601 timestamp the run started. */
+    started_at: z.string().datetime(),
+    /** ISO8601 timestamp of the latest update. */
+    updated_at: z.string().datetime(),
+    /** NL summary of the latest evaluator verdict (or null when none). */
+    last_evaluator_verdict: z.string().max(4000).nullable(),
+    /** NL summary of the latest user choice (or null when none). */
+    last_user_choice: z.string().max(4000).nullable(),
+})
+    .strict();
+/* ---------------------------------------------------------------------- */
+/* Validation helpers (read-only at the surface)                              */
+/* ---------------------------------------------------------------------- */
+/**
+ * Strict-parse an unknown value as a RunStateContract. Throws
+ * `ZodError` on failure. The desktop client uses this at the read
+ * boundary; the running bee writes the file via the existing
+ * dispatch flow (separate write path).
+ */
+export function parseRunStateContract(input) {
+    return RunStateContractSchema.parse(input);
+}
+/**
+ * Safe-parse twin — same Result-like envelope shape used elsewhere.
+ */
+export function safeParseRunStateContract(input) {
+    const r = RunStateContractSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, contract: r.data };
+    return {
+        ok: false,
+        findings: r.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        })),
+    };
+}
+/* ---------------------------------------------------------------------- */
+/* Server-side writer (used by the dispatch flow)                            */
+/* ---------------------------------------------------------------------- */
+/**
+ * Server-side factory used by the dispatch flow to write the file.
+ * This helper is exported for testing purposes; the desktop client
+ * is read-only and SHOULD NOT call this.
+ *
+ * The function returns a brand-new `RunStateContract` value; it
+ * does NOT mutate any external state. Persistence is the caller's
+ * responsibility (the dispatch flow writes a JSON file at a
+ * well-known path under `.peaks/_runtime/<sid>/<role>/`).
+ */
+export function buildRunState(args) {
+    return RunStateContractSchema.parse({
+        bee_id: args.bee_id,
+        status: args.status,
+        current_step: args.current_step,
+        started_at: args.started_at,
+        updated_at: args.updated_at,
+        last_evaluator_verdict: args.last_evaluator_verdict ?? null,
+        last_user_choice: args.last_user_choice ?? null,
+    });
+}

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" | "doctor" | "test" | "content" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "doctor" | "test" | "content" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "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" | "doctor" | "test" | "content" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "doctor" | "test" | "content" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "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));