peaks-loop 4.0.0-beta → 4.0.0-beta.3

package/dist/src/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/src/services/signal/cancel-handler.js

@@ -1,7 +1,7 @@
 /**
  * Slice #009 / G5 RL-9 — user cancel must dispose in-flight dispatch records.
  *
- * When Solo's main loop receives SIGINT (Ctrl-C) or the user runs
+ * When Code's main loop receives SIGINT (Ctrl-C) or the user runs
  * `peaks workflow cancel --rid <rid>`, the loop MUST mark in-flight
  * dispatch records as `outcome: "cancelled"` + `disposed: true` +
  * `disposedAt: now()` BEFORE exiting.
@@ -10,8 +10,8 @@
  * `completedAt: null`. Those are the ones that the LLM got a toolCall
  * for but did not (yet) confirm completion.
  *
- * This module is the helper Solo calls. The wiring (signal listener,
- * cancel command side-effect) is the Solo main loop's responsibility;
+ * This module is the helper Code calls. The wiring (signal listener,
+ * cancel command side-effect) is the Code main loop's responsibility;
  * this module is the pure data operation.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';

package/dist/src/services/skill/resume-detector.js

@@ -1,5 +1,5 @@
 /**
- * Peaks-Loop Solo Step 0.7 — Resume-mode detector.
+ * Peaks-Loop Code Step 0.7 — Resume-mode detector.
  *
  * Mirrors the classification table in
  * `skills/peaks-code/SKILL.md` "Peaks-Loop Step 0.7: Detect unfinished work

package/dist/src/services/skillhub/release-import.js

@@ -36,9 +36,14 @@ export function importRelease({ db, blobsDir, inPath, asName, }) {
         mkdirSync(dest, { recursive: true });
         writeFileSync(join(dest, f.sha256), readFileSync(join(stageDir, "blobs", f.sha256)));
     }
-    // Re-insert rows: pick a new release id, mirror payload rows
+    // Re-insert rows: pick a new release id, mirror payload rows.
+    // M3 / spec §4.2: the new `shareable` and `desktop_visible` columns
+    // are written with their spec defaults (true). Future import
+    // payloads may carry these explicitly (M7 bundle format); until
+    // then M3 keeps defaulting on the insert path so existing call
+    // sites stay source-compatible.
     const tx = db.transaction(() => {
-        const ins = db.prepare(`INSERT INTO bee_release (bee_name, version, source, archived_at, archived_by, user_intent_raw, description, parent_version, changelog) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?)`);
+        const ins = db.prepare(`INSERT INTO bee_release (bee_name, version, source, archived_at, archived_by, user_intent_raw, description, parent_version, changelog, shareable, desktop_visible) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, 1, 1)`);
         const id = ins.run(beeName, payload.version, new Date().toISOString(), null, null, null, null).lastInsertRowid;
         db.prepare(`INSERT OR REPLACE INTO bee_release_pointer (bee_name, latest_version, released_at) VALUES (?, ?, ?)`).run(beeName, payload.version, new Date().toISOString());
         for (const m of payload.manifestRows) {

package/dist/src/services/skillhub/release-retain.js

@@ -51,7 +51,12 @@ function checkOverflow({ table, col }, value) {
 export function retainRelease({ db, blobsDir, scratchDir, manifest, version: explicitVersion, parentVersion, changelog, }) {
     const version = explicitVersion ?? "0.1.0";
     const tx = db.transaction(() => {
-        const ins = db.prepare(`INSERT INTO bee_release (bee_name, version, source, archived_at, archived_by, user_intent_raw, description, parent_version, changelog) VALUES (?, ?, 'user', ?, ?, ?, ?, ?, ?)`);
+        // M3 / spec §4.2: `shareable` and `desktop_visible` are written
+        // with their spec defaults (true). M7 will add a CLI flag to
+        // override on retain; M3 keeps the defaulting on the insert path
+        // so existing call sites stay source-compatible. The two new
+        // columns were added by migration 004-loop-bee-extension.sql.
+        const ins = db.prepare(`INSERT INTO bee_release (bee_name, version, source, archived_at, archived_by, user_intent_raw, description, parent_version, changelog, shareable, desktop_visible) VALUES (?, ?, 'user', ?, ?, ?, ?, ?, ?, 1, 1)`);
         const info = ins.run(manifest.name, version, new Date().toISOString(), "llm", null, manifest.description, parentVersion ?? null, changelog ?? null);
         const id = info.lastInsertRowid;
         db.prepare(`INSERT OR REPLACE INTO bee_release_pointer (bee_name, latest_version, released_at) VALUES (?, ?, ?)`).run(manifest.name, version, new Date().toISOString());

package/dist/src/services/skillhub/sqlite-store.js

@@ -30,7 +30,23 @@ export function openStateDb(path) {
         const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql")).sort();
         for (const f of files) {
             const sql = readFileSync(join(migrationsDir, f), "utf-8");
-            db.exec(sql);
+            try {
+                db.exec(sql);
+            }
+            catch (err) {
+                // Tolerate idempotent re-runs of `ALTER TABLE ... ADD COLUMN`
+                // migrations (e.g. 004-loop-bee-extension). The migration
+                // files themselves are NOT idempotent (SQLite has no
+                // `ALTER TABLE ADD COLUMN IF NOT EXISTS`); the runner is
+                // made idempotent here so the same state.db can be opened
+                // by multiple CLI processes within one workflow.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("duplicate column name") ||
+                    msg.includes("already exists")) {
+                    continue;
+                }
+                throw err;
+            }
         }
     }
     return db;

package/dist/src/services/skillhub/types.d.ts

@@ -9,6 +9,16 @@ export interface BeeReleaseRow {
     description: string | null;
     parent_version: string | null;
     changelog: string | null;
+    /**
+     * M3 / spec §4.2: `shareable` defaults to true (1 in SQLite).
+     * Enforced at the export CLI layer in M7; M3 only adds the column.
+     */
+    shareable: 0 | 1;
+    /**
+     * M3 / spec §4.2: `desktop_visible` defaults to true (1 in SQLite).
+     * Desktop visibility is a UI accelerator filter; M7 reads this.
+     */
+    desktop_visible: 0 | 1;
 }
 export interface BeeReleasePointerRow {
     bee_name: string;

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -86,7 +86,7 @@ export declare function getSkillPresence(projectRootOverride?: string): SkillPre
  *
  *   - `'no-presence'`            — there is no presence file on disk.
  *     Not strictly "stale", but callers (peaks-code Step 1, `peaks
- *     solo should-pause --step step-1-mode-select`) want to treat
+ *     code should-pause --step step-1-mode-select`) want to treat
  *     this case as "no opinion yet — must ask". Surfaced as
  *     `stale: true` with reason `'no-presence'` so the ask path is
  *     uniform.

package/dist/src/services/standards/loop-engineering-lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Loop Engineering guidelines linter (M0).
+ *
+ * Pure function: takes the raw markdown text of
+ * `.peaks/standards/loop-engineering-guidelines.md` and returns either
+ * `{ ok: true, redLines: [...] }` or `{ ok: false, findings: [...] }`.
+ *
+ * The four required sections per red line (karpathy-style form) are:
+ *   - Failure modes
+ *   - Rewrite
+ *   - Self-check
+ *   - Out-of-scope
+ *
+ * Each red line is identified by a heading like `## RL-0 — ...`.
+ *
+ * The lint intentionally does NOT touch any application-level code; it
+ * only parses the guideline file. The peaks CLI command
+ * `peaks standards lint --category loop-engineering` (registered in M0's
+ * plan) will read this file from disk and call this function.
+ */
+export declare const EXPECTED_RED_LINE_IDS: readonly ["RL-0", "RL-1", "RL-2", "RL-3", "RL-4", "RL-5", "RL-6", "RL-7", "RL-8", "RL-9"];
+export type RedLineId = (typeof EXPECTED_RED_LINE_IDS)[number];
+export declare const REQUIRED_SECTIONS: readonly ["Failure modes", "Rewrite", "Self-check", "Out-of-scope"];
+export type RedLineSection = (typeof REQUIRED_SECTIONS)[number];
+export interface RedLineReport {
+    id: RedLineId;
+    title: string;
+    sections: Partial<Record<RedLineSection, string>>;
+}
+export type LintResult = {
+    ok: true;
+    redLines: RedLineReport[];
+} | {
+    ok: false;
+    findings: string[];
+    redLines: RedLineReport[];
+};
+export declare function lintLoopEngineeringGuidelines(raw: string): LintResult;

package/dist/src/services/standards/loop-engineering-lint.js

@@ -0,0 +1,101 @@
+/**
+ * Loop Engineering guidelines linter (M0).
+ *
+ * Pure function: takes the raw markdown text of
+ * `.peaks/standards/loop-engineering-guidelines.md` and returns either
+ * `{ ok: true, redLines: [...] }` or `{ ok: false, findings: [...] }`.
+ *
+ * The four required sections per red line (karpathy-style form) are:
+ *   - Failure modes
+ *   - Rewrite
+ *   - Self-check
+ *   - Out-of-scope
+ *
+ * Each red line is identified by a heading like `## RL-0 — ...`.
+ *
+ * The lint intentionally does NOT touch any application-level code; it
+ * only parses the guideline file. The peaks CLI command
+ * `peaks standards lint --category loop-engineering` (registered in M0's
+ * plan) will read this file from disk and call this function.
+ */
+export const EXPECTED_RED_LINE_IDS = [
+    'RL-0',
+    'RL-1',
+    'RL-2',
+    'RL-3',
+    'RL-4',
+    'RL-5',
+    'RL-6',
+    'RL-7',
+    'RL-8',
+    'RL-9',
+];
+export const REQUIRED_SECTIONS = [
+    'Failure modes',
+    'Rewrite',
+    'Self-check',
+    'Out-of-scope',
+];
+const RED_LINE_HEADING = /^##\s+(RL-\d+)\s+[—-]\s+(.+?)\s*$/gm;
+const SECTION_HEADING = /^##\s+(Failure modes|Rewrite|Self-check|Out-of-scope)\s*$/gm;
+export function lintLoopEngineeringGuidelines(raw) {
+    const findings = [];
+    if (!raw || raw.trim().length === 0) {
+        return { ok: false, findings: ['guideline file is empty'], redLines: [] };
+    }
+    const redLines = parseRedLines(raw);
+    if (redLines.length === 0) {
+        findings.push('no red line headings (`## RL-N — ...`) found');
+    }
+    for (const id of EXPECTED_RED_LINE_IDS) {
+        const rl = redLines.find((r) => r.id === id);
+        if (!rl) {
+            findings.push(`missing red line: ${id}`);
+            continue;
+        }
+        for (const section of REQUIRED_SECTIONS) {
+            if (!rl.sections[section] || rl.sections[section].trim().length === 0) {
+                findings.push(`${id} is missing section "${section}"`);
+            }
+        }
+    }
+    if (findings.length > 0) {
+        return { ok: false, findings, redLines };
+    }
+    return { ok: true, redLines };
+}
+function parseRedLines(raw) {
+    const headingRegex = new RegExp(RED_LINE_HEADING.source, RED_LINE_HEADING.flags);
+    const sectionRegex = new RegExp(SECTION_HEADING.source, SECTION_HEADING.flags);
+    const headings = [];
+    let m;
+    while ((m = headingRegex.exec(raw)) !== null) {
+        headings.push({ id: m[1] ?? '', title: m[2] ?? '', start: m.index + m[0].length, end: raw.length });
+    }
+    for (let i = 0; i < headings.length - 1; i++) {
+        headings[i].end = headings[i + 1].start;
+    }
+    if (headings.length > 0) {
+        headings[headings.length - 1].end = raw.length;
+    }
+    return headings.map((h) => {
+        const body = raw.slice(h.start, h.end);
+        const sections = {};
+        const sectionMatches = [];
+        let sm;
+        while ((sm = sectionRegex.exec(body)) !== null) {
+            sectionMatches.push({ name: sm[1], start: sm.index + sm[0].length });
+        }
+        for (let i = 0; i < sectionMatches.length; i++) {
+            const start = sectionMatches[i].start;
+            const end = i + 1 < sectionMatches.length ? sectionMatches[i + 1].start - sectionMatches[i].start : body.length - start;
+            const text = body.slice(start, start + end);
+            sections[sectionMatches[i].name] = text;
+        }
+        return {
+            id: h.id,
+            title: h.title,
+            sections,
+        };
+    });
+}

package/dist/src/services/standards/loop-engineering-readiness-lint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Loop Engineering Readiness linter (M6 — peak-spec §7.5 + §8.4).
+ *
+ * Pure function: takes the raw markdown text of a peaks-* SKILL.md
+ * file and returns either
+ *   { ok: true, findings: [] }
+ * or
+ *   { ok: false, findings: string[] }.
+ *
+ * The lint asserts three structural properties the spec binds every
+ * Loop-Engineering-participating peaks-* skill to:
+ *
+ *   1. The skill references the shared guideline file
+ *      `.peaks/standards/loop-engineering-guidelines.md` (or its
+ *      alias `.peaks/standards/loop-engineering-guidelines.md`).
+ *      Reference may appear anywhere in the body — code fence,
+ *      plain prose, or list item — as long as the literal token is
+ *      present.
+ *
+ *   2. The skill does NOT introduce a CLI verb that bypasses the
+ *      LLM-coordinated model. We flag lines that look like
+ *      "Run `peaks <verb>` to …" where `<verb>` is not in the
+ *      allowlist of LLM-owned sediment / asset / evolution verbs.
+ *      The user types NL; the LLM runs the CLI on the user's behalf
+ *      (RL-1 / Human-NL-Choice-Only).
+ *
+ *   3. The skill does NOT introduce a JSON / manifest
+ *      hand-authoring surface. We flag lines containing phrases
+ *      like "Edit the manifest", "write the JSON", "fill the JSON
+ *      file", etc., when they are not part of an explicit allowlist
+ *      (allowlist only references; never an instructional phrase).
+ *
+ * Each finding is a single line of the form:
+ *   "<rule>: <offending excerpt>"
+ * so a downstream CLI can render it directly without further
+ * parsing.
+ *
+ * The lint intentionally does NOT touch any application-level
+ * code; it only parses a SKILL.md text. The peaks CLI command
+ * `peaks skill lint --category loop-engineering-readiness
+ *   --path <skill-dir>`
+ * (registered in src/cli/commands/skill-loop-engineering-readiness.ts)
+ * reads the SKILL.md from disk and calls this function.
+ *
+ * Per RL-1 / Human-NL-Choice-Only and
+ * `.peaks/memory/two-forms-only-rule.md`, the user only ever picks
+ * via AskUserQuestion or describes in NL; the LLM runs the CLI.
+ * This lint is what stops a future peaks-* skill from regressing
+ * that rule at the textual layer.
+ */
+export type LintFinding = string;
+export type ReadinessLintResult = {
+    ok: true;
+    findings: [];
+} | {
+    ok: false;
+    findings: LintFinding[];
+};
+/**
+ * The shared guideline file that every Loop-Engineering-participating
+ * peaks-* skill must reference. Both the canonical path and the
+ * common alias are accepted.
+ *
+ * The alias is intentionally identical to the canonical path here:
+ * the spec sometimes renders it as
+ *   `.peaks/standards/loop-engineering-guidelines.md`
+ * with a slash prefix and sometimes without. We accept both.
+ */
+export declare const LOOP_ENGINEERING_GUIDELINE_PATHS: readonly [".peaks/standards/loop-engineering-guidelines.md"];
+/**
+ * The allowlist of CLI verbs that a peaks-* SKILL.md may legitimately
+ * instruct an LLM to invoke on the user's behalf. These are the
+ * sediment / asset / evolution surface verbs introduced in
+ * 2026-07-07-loop-engineering-crystallization-design §7.4 plus the
+ * 18-verb sediment pool from 2026-07-04-peaks-maker-dynamic-skill-
+ * sediment-design §4.2.
+ *
+ * Any other `peaks <verb>` token that appears in the form
+ *   "Run `peaks <verb>` to …"
+ * is treated as a CLI-verb-bypass attempt and flagged.
+ */
+export declare const ALLOWED_CLI_VERBS: Set<string>;
+/**
+ * Phrases that constitute a JSON / manifest hand-authoring surface.
+ * If a SKILL.md instructs the user to perform one of these actions,
+ * it violates RL-1 / Human-NL-Choice-Only and is flagged.
+ *
+ * Each entry is a lowercase substring matched against each line of
+ * the SKILL.md. The match is case-insensitive; the surrounding
+ * `<verb>` placeholders in the original spec are matched literally.
+ */
+export declare const JSON_HAND_AUTHORING_PHRASES: ReadonlyArray<string>;
+/**
+ * Phrases that explicitly reference a JSON / manifest surface but
+ * in an ALLOWED way — e.g. "the manifest is written by the CLI" or
+ * "see manifest schema for details". A line that contains one of
+ * these allowlisted phrases is NOT flagged even if it contains a
+ * JSON-hand-authoring phrase elsewhere on the same line.
+ *
+ * The allowlist is intentionally narrow; it must mention either
+ * the CLI as the writer OR a schema reference, NOT an instructional
+ * verb targeting the user.
+ */
+export declare const JSON_REFERENCE_ALLOWLIST: ReadonlyArray<string>;
+/**
+ * Lint a SKILL.md text for Loop Engineering readiness.
+ *
+ * @param skillMdText raw markdown text of a peaks-* SKILL.md
+ * @returns a ReadinessLintResult
+ */
+export declare function lintSkillLoopEngineeringReadiness(skillMdText: string): ReadinessLintResult;