peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/slice-decompose-command.js

@@ -0,0 +1,123 @@
+import { mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { decomposeSlices } from '../../services/slice/slice-decompose-service.js';
+import { decomposeSlicesWithBenchmark } from '../../services/slice/slice-benchmark-service.js';
+import { decompose as multiPassDecompose } from '../../services/slice/multi-pass-orchestrator.js';
+import { writeResult as writeSchemaResult } from '../../services/slice/schema-router.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { readPrdBody, writeBenchmarkArtifact, writeDecompositionFile } from './slice-decompose-artifacts.js';
+const DECOMPOSE_DESCRIPTION = 'Run the 6-stage slice-decomposition algorithm on a PRD. ' +
+    'Inputs: PRD body + peaks codegraph (project analysis is codegraph-first; structural import edges are the fallback). ' +
+    'Outputs: .peaks/sc/slice-decomposition/<rid>.json with critical-path, ' +
+    'parallel-batches, and per-slice work estimates. ' +
+    'Algorithm is fzf-free. Replay vs hand-derived 2.1.0 dry-run: +-10% on p50. ' +
+    'Pass --benchmark to also emit a SliceBenchmark envelope (totalMs, codegraphQueries, ' +
+    'p50ConfidenceDistribution, outputJsonBytes) and persist it under ' +
+    '.peaks/_runtime/<sid>/benchmarks/<rid>.benchmark.json for cross-version comparison.';
+const DECOMPOSE_PROJECT_HELP = 'target project root';
+const DECOMPOSE_REFRESH_HELP = 're-run `peaks codegraph index` before reading';
+const DECOMPOSE_BENCHMARK_HELP = 'record per-run metrics and attach to the result envelope (2.1.1 algorithm optimization comparison)';
+const DECOMPOSE_GRANULARITY_HELP = 'service | file | both | auto. Default "both" keeps the v1 6-stage path; service / file / auto enable v2 multi-pass decomposition (peaks-loop 2.9+) and emit a DecompositionResultV2 envelope via SchemaRouter';
+const DECOMPOSE_FAILED_HINTS = [
+    'Verify codegraph is initialised (npx codegraph init && npx codegraph index), the rid is correct, and the PRD body is non-empty'
+];
+function isValidGranularity(value) {
+    return value === 'service' || value === 'file' || value === 'both' || value === 'auto';
+}
+function failInvalidGranularity(io, rid, options, granularity) {
+    printResult(io, fail('slice.decompose', 'SLICE_DECOMPOSE_FAILED', `Invalid --granularity '${granularity}'.`, { rid, projectRoot: options.project }, [
+        `--granularity accepts one of: service, file, both, auto`,
+        `Default (omit the flag or pass "both") keeps the existing v1 path.`,
+        `Non-default values (service / file / auto) enable v2 multi-pass decomposition (peaks-loop 2.9+).`
+    ]), options.json ?? false);
+    process.exitCode = 1;
+}
+async function runDecomposeV2(ctx, granularity) {
+    const { rid, prdMarkdown, projectRoot, options, io } = ctx;
+    const v2Result = await multiPassDecompose(rid, prdMarkdown, projectRoot, {
+        ...(options.refresh ? { refresh: true } : {}),
+        granularity
+    });
+    const outDir = join(projectRoot, '.peaks', 'sc', 'slice-decomposition');
+    if (!existsSync(outDir)) {
+        mkdirSync(outDir, { recursive: true });
+    }
+    const outPath = join(outDir, `${rid}.json`);
+    writeSchemaResult(outPath, v2Result);
+    const nextActions = [
+        `Decomposition (v2) written to ${outPath}`,
+        `peaks slice pick/plan: v2 schemas require SchemaRouter-aware consumers (peaks-loop 2.9+).`
+    ];
+    printResult(io, ok('slice.decompose', { ...v2Result, outputPath: outPath }, [], nextActions), options.json ?? false);
+}
+function benchmarkNextAction(rid, benchmark, projectRoot) {
+    const benchPath = writeBenchmarkArtifact(rid, benchmark, projectRoot);
+    return (`Benchmark: totalMs=${benchmark.totalMs} codegraphQueries=${benchmark.codegraphQueries} ` +
+        `p50Conf={low:${benchmark.p50ConfidenceDistribution.low},mid:${benchmark.p50ConfidenceDistribution.mid},high:${benchmark.p50ConfidenceDistribution.high}} ` +
+        `outputJsonBytes=${benchmark.outputJsonBytes}. Persisted to ${benchPath}`);
+}
+async function runDecomposeV1(ctx) {
+    const { rid, prdMarkdown, projectRoot, options, io } = ctx;
+    let result;
+    let benchmark = null;
+    if (options.benchmark === true) {
+        const out = await decomposeSlicesWithBenchmark(rid, prdMarkdown, projectRoot, {
+            ...(options.refresh ? { refresh: true } : {})
+        });
+        result = out.result;
+        benchmark = out.benchmark;
+    }
+    else {
+        result = await decomposeSlices(rid, prdMarkdown, projectRoot, {
+            ...(options.refresh ? { refresh: true } : {})
+        });
+    }
+    const outPath = writeDecompositionFile(rid, result, projectRoot);
+    const nextActions = [
+        `Decomposition written to ${outPath}`,
+        `Next: peaks slice pick ${rid}  (requires fzf >= 0.38)`,
+        `Or manually craft -picked.json from the JSON output, then peaks slice plan ${rid}`
+    ];
+    if (result.pickHint) {
+        nextActions.push(result.pickHint);
+    }
+    if (benchmark !== null) {
+        nextActions.push(benchmarkNextAction(rid, benchmark, projectRoot));
+    }
+    printResult(io, ok('slice.decompose', { ...result, outputPath: outPath, ...(benchmark !== null ? { benchmark } : {}) }, [], nextActions), options.json ?? false);
+}
+async function runSliceDecompose(rid, options, io) {
+    // Validate --granularity BEFORE any I/O so invalid values fail fast with a
+    // nextActions hint listing the four allowed strings.
+    const granularity = options.granularity ?? 'both';
+    if (!isValidGranularity(granularity)) {
+        failInvalidGranularity(io, rid, options, granularity);
+        return;
+    }
+    try {
+        const projectRoot = resolveCanonicalProjectRoot(options.project);
+        const prdMarkdown = readPrdBody(rid, projectRoot);
+        const ctx = { rid, prdMarkdown, projectRoot, options, io };
+        // Non-default granularity takes the v2 path; default ("both") keeps v1.
+        if (granularity !== 'both') {
+            await runDecomposeV2(ctx, granularity);
+            return;
+        }
+        await runDecomposeV1(ctx);
+    }
+    catch (error) {
+        printResult(io, fail('slice.decompose', 'SLICE_DECOMPOSE_FAILED', getErrorMessage(error), { rid, projectRoot: options.project }, DECOMPOSE_FAILED_HINTS), options.json ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerSliceDecomposeCommand(slice, io) {
+    addJsonOption(slice
+        .command('decompose <rid>')
+        .description(DECOMPOSE_DESCRIPTION)
+        .option('--project <path>', DECOMPOSE_PROJECT_HELP, '.')
+        .option('--refresh', DECOMPOSE_REFRESH_HELP, false)
+        .option('--benchmark', DECOMPOSE_BENCHMARK_HELP, false)
+        .option('--granularity <value>', DECOMPOSE_GRANULARITY_HELP, 'both')).action((rid, options) => runSliceDecompose(rid, options, io));
+}

package/dist/cli/commands/slice-list-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSliceListCommand(slice: Command, io: ProgramIO): void;

package/dist/cli/commands/slice-list-commands.js

@@ -0,0 +1,182 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * PRD-002b slice 2 — extract CLI listing-pagination + table-format
+ * constants. Values are bytewise-identical to the original literals.
+ */
+const SLICE_LIST_DEFAULT_LIMIT = 50;
+const SLICE_LIST_MAX_LIMIT = 500;
+const SLICE_LIST_RID_COL_WIDTH = 34;
+const SLICE_LIST_MTIME_COL_WIDTH = 22;
+const SLICE_LIST_SIZE_COL_WIDTH = 8;
+const SLICE_LIST_PICKED_COL_WIDTH = 6;
+const SLICE_LIST_SEPARATOR_WIDTH = 76;
+const LIST_DESCRIPTION = 'List slice decomposition artifacts under .peaks/sc/slice-decomposition/. ' +
+    'Returns one row per distinct rid with mtime, sizeBytes, pickedPath, and isStale ' +
+    '(mtime > 30d). Use --stale-only to filter, --rid <substring> to narrow, ' +
+    '--limit <n> to cap. To remove stale entries, use `peaks slice cleanup` (separate slice).';
+const LIST_PROJECT_HELP = 'target project root';
+const LIST_LIMIT_HELP = 'cap result count (default 50, max 500)';
+const LIST_STALE_ONLY_HELP = 'only include rids older than the stale threshold';
+const LIST_RID_HELP = 'case-insensitive substring filter on rid';
+/**
+ * Stale threshold for slice decomposition artifacts. Matches the default
+ * recorded in .peaks/memory/ for follow-up). If that slice ships with a
+ * different default, both must update here.
+ */
+// eslint-disable-next-line no-magic-numbers -- canonical 30-day-in-ms math
+const STALE_THRESHOLD_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Enumerate every slice decomposition artifact under
+ * `.peaks/sc/slice-decomposition/`. Returns one row per distinct rid.
+ * Missing directory is treated as empty (returns []), matching the
+ * "fresh peaks repo" UX (AC5+AC6).
+ *
+ * Sorted by mtime descending so the most recent rid is first (AC3).
+ */
+function listDecompositions(projectRoot) {
+    const dir = join(projectRoot, '.peaks', 'sc', 'slice-decomposition');
+    if (!existsSync(dir))
+        return [];
+    const nowMs = Date.now();
+    const byRid = new Map();
+    for (const entry of readdirSync(dir)) {
+        // Skip non-matching files (e.g., stray .DS_Store)
+        if (!entry.endsWith('.json'))
+            continue;
+        let rid;
+        let isPicked;
+        if (entry.endsWith('-picked.json')) {
+            rid = entry.slice(0, -'-picked.json'.length);
+            isPicked = true;
+        }
+        else {
+            rid = entry.slice(0, -'.json'.length);
+            isPicked = false;
+        }
+        const absPath = join(dir, entry);
+        const st = statSync(absPath);
+        const existing = byRid.get(rid);
+        if (isPicked) {
+            // Picked file is supplementary; only fill in pickedPath on the existing row
+            if (existing) {
+                byRid.set(rid, { ...existing, pickedPath: absPath });
+            }
+            else {
+                // -picked.json without a corresponding <rid>.json: still surface it
+                byRid.set(rid, {
+                    rid,
+                    decompositionPath: '',
+                    pickedPath: absPath,
+                    mtime: st.mtime.toISOString(),
+                    sizeBytes: 0,
+                    isStale: nowMs - st.mtime.getTime() > STALE_THRESHOLD_MS
+                });
+            }
+            continue;
+        }
+        byRid.set(rid, {
+            rid,
+            decompositionPath: absPath,
+            pickedPath: existing?.pickedPath ?? null,
+            mtime: st.mtime.toISOString(),
+            sizeBytes: st.size,
+            isStale: nowMs - st.mtime.getTime() > STALE_THRESHOLD_MS
+        });
+    }
+    return Array.from(byRid.values()).sort((a, b) => a.mtime < b.mtime ? 1 : a.mtime > b.mtime ? -1 : 0);
+}
+function filterDecompositions(all, options) {
+    let filtered = all;
+    const ridSub = (options.rid ?? '').toLowerCase();
+    if (ridSub.length > 0) {
+        filtered = filtered.filter((row) => row.rid.toLowerCase().includes(ridSub));
+    }
+    if (options.staleOnly === true) {
+        filtered = filtered.filter((row) => row.isStale);
+    }
+    return filtered;
+}
+function sliceListNextActions(page, truncated, limit) {
+    const nextActions = [];
+    if (truncated) {
+        nextActions.push(`Result truncated to ${limit} rows; pass --limit <n> to see more.`);
+    }
+    if (page.some((r) => r.isStale)) {
+        nextActions.push('Some entries are stale (>30d). Use `peaks slice cleanup` to remove them.');
+    }
+    return nextActions;
+}
+function printSliceListJson(io, page, ctx) {
+    printResult(io, ok('slice.ls', {
+        rids: page,
+        truncated: ctx.truncated,
+        totalBeforeFilter: ctx.filteredCount,
+        totalScanned: ctx.allCount
+    }, [], sliceListNextActions(page, ctx.truncated, ctx.limit)), true);
+}
+function printSliceListTable(io, page, ctx) {
+    const lines = [];
+    lines.push('RID'.padEnd(SLICE_LIST_RID_COL_WIDTH) +
+        'MTIME'.padEnd(SLICE_LIST_MTIME_COL_WIDTH) +
+        'SIZE'.padEnd(SLICE_LIST_SIZE_COL_WIDTH) +
+        'PICKED'.padEnd(SLICE_LIST_PICKED_COL_WIDTH) +
+        'STALE');
+    lines.push('-'.repeat(SLICE_LIST_SEPARATOR_WIDTH));
+    for (const r of page) {
+        lines.push(r.rid.padEnd(SLICE_LIST_RID_COL_WIDTH) +
+            r.mtime.padEnd(SLICE_LIST_MTIME_COL_WIDTH) +
+            String(r.sizeBytes).padEnd(SLICE_LIST_SIZE_COL_WIDTH) +
+            (r.pickedPath ? 'yes' : 'no').padEnd(SLICE_LIST_PICKED_COL_WIDTH) +
+            (r.isStale ? 'yes' : 'no'));
+    }
+    if (ctx.truncated) {
+        lines.push(`... (${ctx.filteredCount - ctx.limit} more, --limit to see more)`);
+    }
+    if (page.length === 0) {
+        lines.push('(no slice decompositions found)');
+    }
+    process.stdout.write(lines.join('\n') + '\n');
+}
+function runSliceList(options, io) {
+    try {
+        const projectRoot = resolveCanonicalProjectRoot(options.project);
+        const limit = Math.max(1, Math.min(SLICE_LIST_MAX_LIMIT, options.limit ?? SLICE_LIST_DEFAULT_LIMIT));
+        const all = listDecompositions(projectRoot);
+        const filtered = filterDecompositions(all, options);
+        const truncated = filtered.length > limit;
+        const page = filtered.slice(0, limit);
+        const ctx = {
+            truncated,
+            filteredCount: filtered.length,
+            allCount: all.length,
+            limit
+        };
+        if (options.json === true) {
+            printSliceListJson(io, page, ctx);
+            return;
+        }
+        printSliceListTable(io, page, ctx);
+    }
+    catch (error) {
+        printResult(io, fail('slice.ls', 'SLICE_LS_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+            'Verify the project path is a peaks repo and .peaks/sc/slice-decomposition/ exists or can be created'
+        ]), options.json ?? false);
+        process.exitCode = 1;
+    }
+}
+// Read-only listing of every decomposition artifact under
+// .peaks/sc/slice-decomposition/. Used by operators to see what's
+// accumulated; companion to a future `peaks slice cleanup` subcommand.
+export function registerSliceListCommand(slice, io) {
+    addJsonOption(slice
+        .command('ls')
+        .description(LIST_DESCRIPTION)
+        .option('--project <path>', LIST_PROJECT_HELP, '.')
+        .option('--limit <n>', LIST_LIMIT_HELP, (v) => parseInt(v, 10), SLICE_LIST_DEFAULT_LIMIT)
+        .option('--stale-only', LIST_STALE_ONLY_HELP, false)
+        .option('--rid <substring>', LIST_RID_HELP, '')).action((options) => runSliceList(options, io));
+}

package/dist/cli/commands/slice-pick-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSlicePickCommand(slice: Command, io: ProgramIO): void;

package/dist/cli/commands/slice-pick-command.js

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { pickSlicesInteractive } from '../../services/slice/slice-pick-service.js';
+import { readResult as readDecompositionResult } from '../../services/slice/schema-router.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const PICK_DESCRIPTION = 'Interactively select which candidate slices to ship, via fzf. ' +
+    'Reads .peaks/sc/slice-decomposition/<rid>.json, ' +
+    'spawns fzf --multi, parses selection, writes -picked.json. ' +
+    'Requires fzf >= 0.38. Algorithm is fzf-free; this is the only fzf dependency.';
+const PICK_PROJECT_HELP = 'target project root';
+const PICK_PREVIEW_HELP = 'render side-by-side preview window in fzf';
+const PICK_FZF_BIN_HELP = 'override fzf binary path (default: fzf on PATH)';
+async function runSlicePick(rid, options, io) {
+    try {
+        const projectRoot = resolveCanonicalProjectRoot(options.project);
+        const decompPath = join(projectRoot, '.peaks', 'sc', 'slice-decomposition', `${rid}.json`);
+        if (!existsSync(decompPath)) {
+            throw new Error(`decomposition not found at ${decompPath}. ` + `Run \`peaks slice decompose ${rid}\` first.`);
+        }
+        const parsed = readDecompositionResult(decompPath);
+        if ('schemaVersion' in parsed) {
+            throw new Error(`decomposition at ${decompPath} is a v2 envelope (schemaVersion: 'v2'). ` +
+                `peaks slice pick supports v1 only in peaks-loop 2.9.0. ` +
+                `Re-run \`peaks slice decompose ${rid}\` without --granularity to get a v1 file, ` +
+                `or upgrade peaks-loop when v2 pick lands.`);
+        }
+        const decomposition = parsed;
+        const result = await pickSlicesInteractive(rid, decomposition, projectRoot, {
+            ...(options.preview !== undefined ? { preview: options.preview } : {}),
+            ...(options.fzfBin ? { fzfBin: options.fzfBin } : {})
+        });
+        const nextActions = [
+            `Picked ${result.picked.length} slice(s); written to ${result.outputPath}`,
+            `Next: peaks slice plan ${rid}  (--apply to call peaks request init for each chosen slice)`
+        ];
+        printResult(io, ok('slice.pick', result, [], nextActions), options.json ?? false);
+    }
+    catch (error) {
+        const msg = getErrorMessage(error);
+        if (/brew install fzf|apt-get install fzf|older than required/.test(msg)) {
+            process.exitCode = 127;
+        }
+        else {
+            process.exitCode = 1;
+        }
+        printResult(io, fail('slice.pick', 'SLICE_PICK_FAILED', msg, { rid, projectRoot: options.project }, [
+            'Verify the decomposition file exists, fzf >= 0.38 is on PATH, and the rid is correct'
+        ]), options.json ?? false);
+    }
+}
+export function registerSlicePickCommand(slice, io) {
+    addJsonOption(slice
+        .command('pick <rid>')
+        .description(PICK_DESCRIPTION)
+        .option('--project <path>', PICK_PROJECT_HELP, '.')
+        .option('--preview', PICK_PREVIEW_HELP, false)
+        .option('--fzf-bin <path>', PICK_FZF_BIN_HELP, 'fzf')).action((rid, options) => runSlicePick(rid, options, io));
+}

package/dist/cli/commands/slice-plan-command.d.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+interface PickedEnvelope {
+    readonly rid: string;
+    readonly picked: readonly {
+        readonly rid: string;
+        readonly files: readonly string[];
+        readonly label: string;
+    }[];
+}
+/**
+ * Validate a -picked.json envelope. Throws a CLI-friendly Error on any
+ * shape violation; the catch in the slice.plan action converts it to
+ * a fail() envelope with `code: 'PICKED_ENVELOPE_INVALID'`.
+ *
+ * Schema:
+ *   { rid: string; picked: Array<{ rid, files: string[], label }> }
+ *
+ * Rejects: missing rid, missing/invalid picked array, picked[i] missing
+ * rid / files / label, picked[i].files empty.
+ */
+export declare function parsePickedFile(pickedPath: string): PickedEnvelope;
+export declare function registerSlicePlanCommand(slice: Command, io: ProgramIO): void;
+export {};

package/dist/cli/commands/slice-plan-command.js

@@ -0,0 +1,111 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const PLAN_DESCRIPTION = 'Apply a picked batch: read -picked.json, call `peaks request init` for each chosen slice ' +
+    'with --depends-on edges from the decomposition. Dry-run by default; pass --apply to ' +
+    'actually create rids.';
+const PLAN_PROJECT_HELP = 'target project root';
+const PLAN_APPLY_HELP = 'actually call peaks request init (default: dry-run only)';
+const PLAN_PICKED_MISSING_HINT = 'Verify the picked file exists, the rid is correct, and peaks request init is available';
+const PLAN_PICKED_ENVELOPE_TOO_LONG = 'Verify the -picked.json envelope matches the schema: { rid: string, picked: Array<{ rid, files: string[], label }> }';
+/**
+ * Validate a -picked.json envelope. Throws a CLI-friendly Error on any
+ * shape violation; the catch in the slice.plan action converts it to
+ * a fail() envelope with `code: 'PICKED_ENVELOPE_INVALID'`.
+ *
+ * Schema:
+ *   { rid: string; picked: Array<{ rid, files: string[], label }> }
+ *
+ * Rejects: missing rid, missing/invalid picked array, picked[i] missing
+ * rid / files / label, picked[i].files empty.
+ */
+export function parsePickedFile(pickedPath) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(pickedPath, 'utf8'));
+    }
+    catch (err) {
+        // JSON.parse errors are always Error-shaped (SyntaxError extends Error),
+        // so the cast is safe; we only need `.message`.
+        throw new Error(`picked envelope at ${pickedPath} is not valid JSON: ${err.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        throw new Error(`picked envelope at ${pickedPath} must be a JSON object, got ${typeof raw}`);
+    }
+    const obj = raw;
+    if (typeof obj.rid !== 'string' || obj.rid.length === 0) {
+        throw new Error(`picked envelope at ${pickedPath} is missing required string field 'rid'`);
+    }
+    if (!Array.isArray(obj.picked)) {
+        throw new Error(`picked envelope at ${pickedPath} is missing required array field 'picked'`);
+    }
+    const picked = obj.picked.map((item, idx) => {
+        if (typeof item !== 'object' || item === null) {
+            throw new Error(`picked[${idx}] must be an object, got ${typeof item}`);
+        }
+        const it = item;
+        if (typeof it.rid !== 'string' || it.rid.length === 0) {
+            throw new Error(`picked[${idx}] is missing required string field 'rid'`);
+        }
+        if (!Array.isArray(it.files) || it.files.length === 0) {
+            throw new Error(`picked[${idx}] is missing or has empty required array field 'files'`);
+        }
+        if (!it.files.every((f) => typeof f === 'string')) {
+            throw new Error(`picked[${idx}].files must contain only strings`);
+        }
+        if (typeof it.label !== 'string' || it.label.length === 0) {
+            throw new Error(`picked[${idx}] is missing required string field 'label'`);
+        }
+        return { rid: it.rid, files: it.files, label: it.label };
+    });
+    return { rid: obj.rid, picked };
+}
+function buildPlanEntries(rid, picked) {
+    return picked.picked.map((slice, idx) => ({
+        newRid: `${rid}-${idx + 1}-${slice.rid}`,
+        type: 'feat',
+        dependsOn: idx === 0 ? [] : [picked.picked[idx - 1].rid],
+        files: slice.files,
+        label: slice.label,
+        applied: false
+    }));
+}
+function slicePlanNextActions(picked, options) {
+    return [
+        `Planned ${picked.picked.length} new rids from ${picked.picked.length} picked slices`,
+        options.apply
+            ? 'Apply mode: would call peaks request init for each (v1.1: wire to spawn child)'
+            : 'Dry-run: pass --apply to actually create the rids (v1.1: wire to peaks request init spawn)'
+    ];
+}
+function printSlicePlanFailure(io, options, target, error) {
+    const msg = getErrorMessage(error);
+    const isEnvelopeError = msg.startsWith('picked envelope at');
+    printResult(io, fail('slice.plan', isEnvelopeError ? 'PICKED_ENVELOPE_INVALID' : 'SLICE_PLAN_FAILED', msg, { rid: target.rid, projectRoot: options.project, pickedPath: target.pickedPath }, isEnvelopeError ? [PLAN_PICKED_ENVELOPE_TOO_LONG] : [PLAN_PICKED_MISSING_HINT]), options.json ?? false);
+    process.exitCode = 1;
+}
+function runSlicePlan(rid, options, io) {
+    const projectRoot = resolveCanonicalProjectRoot(options.project);
+    const pickedPath = join(projectRoot, '.peaks', 'sc', 'slice-decomposition', `${rid}-picked.json`);
+    try {
+        if (!existsSync(pickedPath)) {
+            throw new Error(`picked file not found at ${pickedPath}. ` +
+                `Run \`peaks slice pick ${rid}\` first, or manually craft the file.`);
+        }
+        const picked = parsePickedFile(pickedPath);
+        const plan = buildPlanEntries(rid, picked);
+        printResult(io, ok('slice.plan', { parentRid: rid, plan, apply: options.apply ?? false }, [], slicePlanNextActions(picked, options)), options.json ?? false);
+    }
+    catch (error) {
+        printSlicePlanFailure(io, options, { rid, projectRoot, pickedPath }, error);
+    }
+}
+export function registerSlicePlanCommand(slice, io) {
+    addJsonOption(slice
+        .command('plan <rid>')
+        .description(PLAN_DESCRIPTION)
+        .option('--project <path>', PLAN_PROJECT_HELP, '.')
+        .option('--apply', PLAN_APPLY_HELP, false)).action((rid, options) => runSlicePlan(rid, options, io));
+}

package/dist/cli/commands/workflow-commands.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `peaks refactor | tech | workflow | route | autonomous | swarm | recommend`
+ * planning surface.
+ *
+ * This module is the registrar: each family owns its own file, and the two helpers
+ * they share live in `workflow-plan-helpers.ts`. The `peaks workflow` parent is
+ * created by the planning family and handed back, so the gate family attaches to
+ * the same group instead of creating a second one.
+ */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerWorkflowCommands(program: Command, io: ProgramIO): void;