peaks-loop 4.1.2 → 4.1.4

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

@@ -1,263 +1,81 @@
 /**
  * peaks loop * CLI (Slice #14 + M7 add).
  *
- * Slices:
  *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
- *     detect-pattern / check-consistency / peaks goal compose.
+ *     detect-pattern / check-consistency, plus `peaks goal compose`.
  *
- *   M7 (2026-07-07 spec §7A.2):
- *     peaks loop export --loop <id> --out <path.tar.gz>
- *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
+ *   M7 (2026-07-07 spec §7A.2): `peaks loop export --loop <id> --out <p.tar.gz>`
+ *     and `peaks loop import --in <p.tar.gz> [--as <loop-id>]`. `export` reads
+ *     the loop_release + relations + bees + evidence briefs and hard-blocks on
+ *     `shareable=false`; `import` validates `format_version_major=1` and lands
+ *     the release as `candidate` (spec §7A.2) — the receiver must run an
+ *     independent evaluation before promoting to `stable`. M7 only ADDs these
+ *     two verbs; the existing 14.x surface is not modified.
  *
- * `peaks loop export` reads the source loop_release + relations +
- * related bees + evidence briefs and emits a `peaks.bundle/1`
- * tar.gz. Hard-blocks when the source has `shareable=false`.
- *
- * `peaks loop import` extracts a bundle, validates
- * format_version_major=1, and lands the release as `candidate`
- * (mandatory landing status per spec §7A.2). The receiver must run
- * an independent evaluation before promoting to `stable`.
- *
- * The existing 14.x commands are kept under the same `loop` parent;
- * M7 only ADDs export / import — it does not modify the existing
- * surface.
+ * This module owns the `loop` parent, the registrar order, and `distill` — the
+ * one verb that spawns a child process, kept here so the `node:child_process`
+ * import stays on the module `tests/unit/spawn-windows-hide-guard.test.ts`
+ * pins it to. Every other verb lives beside this file, one module per verb.
  */
-import { existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { openStateDb } from '../../services/skillhub/sqlite-store.js';
-import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError } from '../../services/share/bundle-writer.js';
-import { readBundle, BundleMajorVersionMismatchError, BundleSchemaVersionsMismatchError, BundleImportToStableForbiddenError, BundleMalformedError } from '../../services/share/bundle-reader.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { registerLoopExportCommand } from './loop-export-command.js';
+import { registerLoopGoalComposeCommand } from './loop-goal-compose-command.js';
+import { registerLoopImportCommand } from './loop-import-command.js';
+import { registerLoopPlaceholderCommands } from './loop-placeholder-commands.js';
 export function registerLoopCommands(program, io) {
-    // 14.5 peaks goal compose — registered as a TOP-LEVEL command (not under
-    // `peaks loop`) because IDE adapters expose it as `goalCommand`.
-    // The sub-agent dispatch path consumes it; the slice 0.7 hermes +
-    // openclaw adapters will thread it through.
-    addJsonOption(program
-        .command('goal')
-        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
-        .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--goal <text>', 'the high-level goal to compose')).action((options) => {
-        try {
-            printResult(io, ok('goal.compose', {
-                project: options.project,
-                goal: options.goal,
-                status: 'placeholder',
-                nextSteps: [
-                    'The composed goal is consumed by peaks sub-agent dispatch.',
-                    'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.'
-                ]
-            }, [], [
-                'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.'
-            ]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // peaks loop *
+    // 14.5 peaks goal compose — a TOP-LEVEL command (not under `peaks loop`),
+    // because IDE adapters expose it as `goalCommand`.
+    registerLoopGoalComposeCommand(program, io);
     const loop = program
         .command('loop')
         .description('Slice #14: L4 Agent Loop sub-features (distill / preflight / detect-pattern / check-consistency)');
-    // 14.1 distill
+    registerLoopDistillCommand(loop, io);
+    registerLoopPlaceholderCommands(loop, io);
+    registerLoopExportCommand(loop, io);
+    registerLoopImportCommand(loop, io);
+}
+/**
+ * 14.1 distill — delegate to `peaks memory extract` through a dynamic
+ * `node:child_process` import (no static import, so the command layer does not
+ * load `child_process` for verbs that never spawn). The LLM-side UX layer
+ * composes the two commands.
+ */
+function registerLoopDistillCommand(loop, io) {
     addJsonOption(loop
         .command('distill')
         .description('14.1: distill patterns from past sessions into .peaks/memory/ (delegates to peaks memory extract)')
         .requiredOption('--project <path>', 'target project root')
         .option('--apply', 'write extracted memories to .peaks/memory/ (default: dry-run preview)', false)).action(async (options) => {
         try {
-            const apply = options.apply === true;
-            // Delegate to the existing peaks memory extract CLI via dynamic
-            // import (avoids circular); the LLM-side UX layer composes the
-            // two commands.
-            const { execFileSync } = (await import('node:child_process'));
-            const args = ['memory', 'extract', '--project', options.project];
-            if (apply)
-                args.push('--apply');
-            const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
-                cwd: options.project,
-                stdio: ['ignore', 'pipe', 'ignore'],
-                windowsHide: true
-            }).toString('utf-8');
-            printResult(io, ok('loop.distill', {
-                project: options.project,
-                apply,
-                delegateStdout: stdout.slice(0, 200)
-            }, [], [
-                apply
-                    ? 'peaks memory extract --apply was invoked'
-                    : 'peaks memory extract dry-run was invoked',
-                'A future slice will inline the memory extract (not via execFileSync).'
-            ]), options.json);
+            printResult(io, ok('loop.distill', await extractMemoryViaDelegate(options), [], distillNextActions(options)), options.json);
         }
         catch (error) {
             printResult(io, fail('loop.distill', 'LOOP_DISTILL_FAILED', getErrorMessage(error), { project: options.project }, ['Verify the project path']), options.json);
             process.exitCode = 1;
         }
     });
-    // 14.2 preflight
-    addJsonOption(loop
-        .command('preflight')
-        .description('14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)')
-        .requiredOption('--project <path>', 'target project root')).action((options) => {
-        printResult(io, ok('loop.preflight', {
-            project: options.project,
-            status: 'placeholder',
-            nextSteps: [
-                'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
-                'A future slice will inline the preflight checks (not just placeholder).'
-            ]
-        }, [], [
-            'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.'
-        ]), options.json);
-    });
-    // 14.3 detect-pattern
-    addJsonOption(loop
-        .command('detect-pattern')
-        .description('14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)')
-        .requiredOption('--project <path>', 'target project root')).action((options) => {
-        printResult(io, ok('loop.detect-pattern', {
-            project: options.project,
-            status: 'placeholder',
-            nextSteps: [
-                'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
-                'A future slice will rank by frequency + LLM confidence.'
-            ]
-        }, [], [
-            'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.'
-        ]), options.json);
-    });
-    // 14.4 check-consistency
-    addJsonOption(loop
-        .command('check-consistency')
-        .description('14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)')
-        .requiredOption('--project <path>', 'target project root')).action((options) => {
-        printResult(io, ok('loop.check-consistency', {
-            project: options.project,
-            status: 'placeholder',
-            nextSteps: [
-                'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
-                'A future slice will report drift with severity (warn / fail).'
-            ]
-        }, [], ['loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.']), options.json);
-    });
-    // ---------- M7: peaks loop export / import (spec §7A.2) ----------
-    const LOOP_EXPORT_IMPORT_OPTS = (cmd) => cmd
-        .option('--project <path>', 'target project root (defaults to cwd)')
-        .option('--json', 'print machine-readable JSON envelope');
-    LOOP_EXPORT_IMPORT_OPTS(loop
-        .command('export')
-        .description('M7: export a loop_release as a peaks.bundle/1 tarball (spec §7A.2 / §10 RL-9). Refuses to export when shareable=false.')
-        .requiredOption('--loop <id>', 'loop_release id (kebab-case)')
-        .requiredOption('--out <path>', 'output .tar.gz path')).action((options) => {
-        const asJson = options.json === true;
-        try {
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const result = writeBundle({
-                    db,
-                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
-                    kind: 'loop',
-                    id: options.loop,
-                    outPath: options.out
-                });
-                printResult(io, ok('loop.export', {
-                    outPath: result.outPath,
-                    kind: result.kind,
-                    assetId: result.assetId,
-                    importedAs: 'candidate'
-                }, [], [
-                    `Receiver must run \`peaks loop import --in ${result.outPath}\` to land this bundle, then run an independent evolution_evaluation before any promote.`
-                ]), asJson);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (error) {
-            if (error instanceof BundleNotShareableError) {
-                printResult(io, fail('loop.export', error.code, error.message, { ok: false, loop: options.loop }, ['Set shareable=true on the loop_release row, or share via desktop_visible=false.']), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof BundleAssetNotFoundError) {
-                printResult(io, fail('loop.export', error.code, error.message, { ok: false, loop: options.loop }, ['Verify the loop id with `peaks asset status --loop <id>`.']), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('loop.export', 'LOOP_EXPORT_FAILED', getErrorMessage(error), { ok: false, loop: options.loop }, ['Verify --loop id and --out path.']), asJson);
-            process.exitCode = 1;
-        }
-    });
-    LOOP_EXPORT_IMPORT_OPTS(loop
-        .command('import')
-        .description('M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / §10 RL-9 / AC-25 / AC-26).')
-        .requiredOption('--in <path>', 'input .tar.gz path')
-        .option('--as <id>', 'optional rename for the loop id when landing')).action((options) => {
-        const asJson = options.json === true;
-        try {
-            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, '.peaks'))) {
-                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
-            }
-            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
-            try {
-                const result = readBundle({
-                    db,
-                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
-                    inPath: options.in,
-                    ...(options.as !== undefined ? { asName: options.as } : {})
-                });
-                printResult(io, ok('loop.import', {
-                    assetId: result.assetId,
-                    kind: result.kind,
-                    importedAs: result.importedAs,
-                    warnings: result.warnings,
-                    evidenceBriefCount: result.evidenceBriefCount
-                }, result.warnings, [
-                    `Run an independent evaluation against this release before promoting; peaks loop promote refuses without an evolution_evaluation row.`
-                ]), asJson);
-            }
-            finally {
-                db.close();
-            }
-        }
-        catch (error) {
-            if (error instanceof BundleMajorVersionMismatchError) {
-                printResult(io, fail('loop.import', error.code, error.message, { ok: false, receivedMajor: error.receivedMajor }, [
-                    'Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.'
-                ]), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof BundleSchemaVersionsMismatchError) {
-                printResult(io, fail('loop.import', error.code, error.message, { ok: false }, [
-                    'Source bundle did not declare the canonical schema versions; refuse the bundle.'
-                ]), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof BundleImportToStableForbiddenError) {
-                printResult(io, fail('loop.import', error.code, error.message, { ok: false }, [
-                    'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).'
-                ]), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof BundleMalformedError) {
-                printResult(io, fail('loop.import', error.code, error.message, { ok: false, inPath: options.in }, ['Re-export from the source via `peaks loop export`.']), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('loop.import', 'LOOP_IMPORT_FAILED', getErrorMessage(error), { ok: false, inPath: options.in }, ['Verify the bundle path and integrity.']), asJson);
-            process.exitCode = 1;
-        }
-    });
+}
+/** Spawn `peaks memory extract` and report the first 200 bytes of its stdout. */
+async function extractMemoryViaDelegate(options) {
+    const apply = options.apply === true;
+    const { execFileSync } = (await import('node:child_process'));
+    const args = ['memory', 'extract', '--project', options.project];
+    if (apply)
+        args.push('--apply');
+    const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
+        cwd: options.project,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        windowsHide: true
+    }).toString('utf-8');
+    return { project: options.project, apply, delegateStdout: stdout.slice(0, 200) };
+}
+/** The two sentences `loop.distill` tells the caller about what it just ran. */
+function distillNextActions(options) {
+    return [
+        options.apply === true
+            ? 'peaks memory extract --apply was invoked'
+            : 'peaks memory extract dry-run was invoked',
+        'A future slice will inline the memory extract (not via execFileSync).'
+    ];
 }

package/dist/cli/commands/loop-eval-capture-index.d.ts

@@ -0,0 +1,4 @@
+/** Test seam: pick the next cycle-N.json number for capture-score
+ *  writes. The run-driver also writes to the same dir; the next
+ *  index = max(prior)+1, or 1. */
+export declare function nextEvalCaptureIndex(projectRoot: string, sid: string, rid: string): number;

package/dist/cli/commands/loop-eval-capture-index.js

@@ -0,0 +1,44 @@
+// The cycle-file index seam for `--capture-score`. Pure path/IO plus its own path-safety
+// contract; it owns no command registration, which is why it lives outside the
+// registrar that calls it.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+/** Test seam: pick the next cycle-N.json number for capture-score
+ *  writes. The run-driver also writes to the same dir; the next
+ *  index = max(prior)+1, or 1. */
+export function nextEvalCaptureIndex(projectRoot, sid, rid) {
+    // BOTH id axes: this function is the join for the capture-score cycle dir.
+    // The action guards `options.session` and `rid` before calling in, but the
+    // seam is callable on its own, so the join states its own contract. The rid
+    // half was missing until 2026-09-14 (repair R1) — the same second-slot hole
+    // the action had, in the same file, one function below it.
+    if (isUnsafePathInput(sid)) {
+        throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
+    }
+    if (isUnsafePathInput(rid)) {
+        throw new Error(`Invalid request id: ${rid} (must be a single path segment)`);
+    }
+    const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');
+    if (!existsSync(dir))
+        return 1;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return 1;
+    }
+    let best = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const n = parseInt(m[1] ?? '0', 10);
+        if (best === null || n > best)
+            best = n;
+    }
+    return (best ?? 0) + 1;
+}

package/dist/cli/commands/loop-eval-commands.d.ts

@@ -3,18 +3,21 @@
  *
  * CLI surface for the workflow primitive + the loop evaluator dispatcher.
  *
- * New commands (added under the existing `peaks workflow` group and the
+ * Commands (added under the existing `peaks workflow` group and the
  * existing `peaks loop` group — never as new top-level commands, per the
  * peaks-loop add-a-new-subcommand-check-for-existing-top-level-first rule):
  *
  *   peaks workflow run <id> --session <sid> --project <repo> --json
- *   peaks workflow plan <id> --session <sid> --json   (dry-run)
+ *   peaks workflow graph <id> --session <sid> --json   (dry-run)
  *   peaks workflow lint <id> --session <sid> --json
  *   peaks loop eval <rid> --evaluator <name> [--project <repo>] [--json]
+ *   peaks loop check-monotonic <rid> --session <sid> [--json]
+ *   peaks loop spec show|bootstrap|lint ...
+ *   peaks loop run <rid> --session <sid> [--json]
  *
- * Karpathy §2: separate file from workflow-commands.ts to stay under
- * the 800-line budget.
+ * This module is the registrar only: each command family owns its own file, so a
+ * change to one family cannot make the others harder to edit.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerWorkflowEvalCommands(program: Command, io: ProgramIO): void;