peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/cli/commands/core/skill-command.js

@@ -0,0 +1,300 @@
+import { runDoctor } from '../../../services/doctor/doctor-service.js';
+import { listSkills } from '../../../services/skills/skill-registry.js';
+import { runSkillSync, SYNC_PLATFORMS } from '../../../services/skills/sync-service.js';
+import { inspectSkillRunbook } from '../../../services/skills/skill-runbook-service.js';
+import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat, checkStalePresence } from '../../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../../services/hooks/presence-marker-detector.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { generateProjectContext } from '../../../services/memory/project-context-service.js';
+import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+// Slice S0 (4.0.0-beta.5 peaks-solo dispatcher release):
+// `peaks skill search` is the CLI primitive that feeds the
+// peaks-solo dispatcher (S1). Adding a single import + register call
+// here keeps the change surgical and leaves all existing skill
+// subcommands (list / doctor / sync / runbook / presence / heartbeat)
+// untouched. See
+// docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+// and the S0 plan under docs/superpowers/plans/.
+import { registerSkillSearchCommand } from '../skill-search-commands.js';
+export function registerSkillCommand(program, io) {
+    const skill = program.command('skill').description('Manage Peaks skills');
+    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md')).action(async (options) => {
+        const skills = await listSkills();
+        if (options.json === true) {
+            printResult(io, ok('skill.list', { skills }), true);
+        }
+        else {
+            const sorted = [...skills].sort((a, b) => {
+                // Slice S0 (4.0.0-beta.5): peaks-solo is the dispatcher (front
+                // door) — list it FIRST so users discover the dispatcher before
+                // any specific leaf. Followed by peaks-sop (current default
+                // runbook showcase) and peaks-code (canonical code-domain
+                // orchestrator); everything else falls back to alphabetical.
+                if (a.name === 'peaks-solo')
+                    return -1;
+                if (b.name === 'peaks-solo')
+                    return 1;
+                if (a.name === 'peaks-sop')
+                    return -1;
+                if (b.name === 'peaks-sop')
+                    return 1;
+                if (a.name === 'peaks-code')
+                    return -1;
+                if (b.name === 'peaks-code')
+                    return 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (const skill of sorted) {
+                io.stdout(`  ${skill.name.padEnd(14)}${skill.description}`);
+            }
+            io.stdout(`\n  Invoke any skill by typing its name in conversation (e.g. \`peaks-sop\`).`);
+        }
+    });
+    addJsonOption(skill.command('doctor').description('Run skill-related doctor checks')).action(async (options) => {
+        const report = await runDoctor();
+        const skillChecks = report.checks.filter((check) => check.id.startsWith('skill'));
+        const failed = skillChecks.filter((check) => !check.ok).length;
+        if (options.json === true) {
+            printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), true);
+        }
+        else {
+            for (const check of skillChecks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            io.stdout(`\n  ${skillChecks.length - failed} passed, ${failed} failed`);
+            if (failed > 0) {
+                io.stderr('\nOne or more skill checks failed.');
+            }
+        }
+        if (failed > 0) {
+            process.exitCode = 1;
+        }
+    });
+    // Slice #12 final piece (per spec §9 line 1105):
+    // `peaks skills sync 8 平台分发`. Idempotent: re-running is a
+    // no-op when the symlinks are already correct.
+    addJsonOption(skill
+        .command('sync')
+        .description(`Sync the peaks-* skill family to one or all of the 8 supported LLM-CLI platforms (${SYNC_PLATFORMS.join(', ')}). Idempotent.`)
+        .option('--platform <id>', `sync only one platform (default: --all). Valid: ${SYNC_PLATFORMS.join(', ')}`)
+        .option('--all', 'sync all 8 platforms (default if --platform is omitted)')
+        .option('--dry-run', 'do not write; emit the same shape with applied=false')
+        .option('--project <path>', 'project root (default: cwd)')).action(async (options) => {
+        try {
+            const projectRoot = options.project ?? process.cwd();
+            const platforms = options.platform !== undefined ? [options.platform] : undefined;
+            const result = await runSkillSync({
+                projectRoot,
+                ...(platforms !== undefined ? { platforms } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+            });
+            const envelope = ok('skill.sync', result, [], [
+                `syncedCount: ${result.syncedCount}/${result.perPlatform.length} platforms`,
+                `totalInstalled: ${result.totalInstalled} skill symlinks`,
+                result.failedCount > 0
+                    ? `failedCount: ${result.failedCount} (run \`peaks skill status\` for details)`
+                    : 'no failures',
+            ]);
+            printResult(io, envelope, options.json);
+            if (result.failedCount > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('skill.sync', 'SKILL_SYNC_FAILED', message, { applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(skill
+        .command('runbook <name>')
+        .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
+        try {
+            const inspection = await inspectSkillRunbook(name);
+            const result = inspection.ok
+                ? ok('skill.runbook', inspection)
+                : fail('skill.runbook', inspection.hasRunbook ? 'SKILL_RUNBOOK_APPLY_UNGATED' : 'SKILL_RUNBOOK_MISSING', inspection.hasRunbook
+                    ? `Skill ${inspection.name} has ${inspection.destructiveApplyLines.length} destructive --apply command(s) without an authorization/dry-run note`
+                    : `Skill ${inspection.name} is missing a ## Default runbook section`, inspection, inspection.hasRunbook
+                    ? ['Add an authorization or --dry-run note next to destructive --apply lines in the runbook section']
+                    : ['Add a `## Default runbook` section to the skill SKILL.md']);
+            printResult(io, result, options.json);
+            if (!inspection.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('skill.runbook', 'SKILL_NOT_FOUND', getErrorMessage(error), { name }), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(skill
+        .command('presence')
+        .description('Show the currently active Peaks skill (alias: presence:get)')
+        .option('--check-stale', 'slice 002 (v2.15.0): also report whether the recorded outer session id still matches the current one. Default false (back-compat).')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const presence = getSkillPresence(options.project);
+        if (presence === null) {
+            printResult(io, ok('skill.presence', { active: false }), options.json);
+            return;
+        }
+        if (options.checkStale === true) {
+            // Slice 002 (v2.15.0) AC-1: pair the read with a staleness
+            // check so callers (peaks-code Step 1, statusline) get both
+            // pieces of info from a single CLI invocation. The presence
+            // is returned UNCHANGED — `--check-stale` is a read-only flag,
+            // not a clear.
+            const staleness = checkStalePresence({ projectRootOverride: options.project });
+            printResult(io, ok('skill.presence', {
+                active: true,
+                ...presence,
+                stale: staleness.stale,
+                staleReason: staleness.reason,
+                currentOuterSessionId: staleness.currentOuterSessionId,
+                recordedOuterSessionId: staleness.recordedOuterSessionId
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.presence', { active: true, ...presence }), options.json);
+    });
+    addJsonOption(skill
+        .command('presence:set <name>')
+        .description('Set the currently active Peaks skill for session-wide visibility')
+        .option('--mode <mode>', 'execution mode')
+        .option('--gate <gate>', 'current gate')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((name, options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
+            printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, swarm, strict)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, swarm, or strict']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const presence = setSkillPresence(name, options.mode, options.gate, options.project);
+        // As of slice 003-2026-06-06-session-layout-canonicalize we do NOT
+        // call `ensureSession` here. The CLI wrapper previously spawned a
+        // new session on every presence call, which made the canonical
+        // session binding drift (the LLM saw the session id change every
+        // turn). The presence now reuses the session bound at
+        // `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json`
+        // during the back-compat window). If no session is bound, the
+        // presence still writes the active-skill marker — downstream code
+        // can `peaks workspace init` separately to create the session.
+        //
+        // Session metadata is updated when a session is bound (read-only
+        // path: `getSessionId`). We do not auto-spawn a session.
+        const boundSessionId = getSessionId(projectRoot);
+        if (boundSessionId !== null) {
+            setSessionMeta(projectRoot, boundSessionId, {
+                skill: name,
+                ...(options.mode ? { mode: options.mode } : {}),
+                ...(options.gate ? { gate: options.gate } : {})
+            });
+        }
+        printResult(io, ok('skill.presence:set', { active: true, ...presence }), options.json);
+    });
+    addJsonOption(skill
+        .command('presence:clear')
+        .description('Clear the active Peaks skill presence indicator and update project context')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const removed = clearSkillPresence(options.project);
+        // Auto-update project context so future sessions have up-to-date history.
+        // Slice 2026-07-15-project-scan-bootstrap: generateProjectContext now also
+        // bootstraps `.peaks/project-scan/` (idempotent). Await the async
+        // signature; failure is still non-fatal so we don't block the clear.
+        try {
+            await generateProjectContext(projectRoot);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // non-fatal: context update failure should not block presence clear
+        }
+        printResult(io, ok('skill.presence:clear', { active: false, removed, projectContextUpdated: true }), options.json);
+    });
+    // Slice 002 (v2.15.0) — AC-1: presence staleness detector.
+    // peaks-code Step 1 (and `peaks code should-pause --step
+    // step-1-mode-select`) calls this to decide whether the recorded
+    // `mode` field can be trusted or whether the LLM must AskUserQuestion.
+    addJsonOption(skill
+        .command('presence:check-stale')
+        .description('Slice 002 (v2.15.0) AC-1: report whether the recorded presence outer session id still matches the current outer session id. ' +
+        'Returns { stale: boolean, reason: "outer-session-mismatch" | "no-presence" | null }. ' +
+        'Pure read-only — does NOT clear the presence (use `peaks skill presence:clear` for that).')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--current-outer <id>', 'override the current outer session id (test seam; default: read from PEAKS_OUTER_SESSION_ID / CLAUDE_CODE_SESSION_ID)')).action((options) => {
+        // v2.15.0 slice 002 repair: do NOT pass `currentOuter: undefined`
+        // when the user omits the flag. The service-layer branch
+        // `'currentOuter' in opts` returns true for an explicit
+        // `undefined` (the key exists on the spread object literal),
+        // which would skip the env-var fallback and pin `current =
+        // undefined` — always reading the presence as stale. Build a
+        // sparse opts object so the service can fall back to
+        // `getCurrentOuterSessionId()` (reads PEAKS_OUTER_SESSION_ID /
+        // CLAUDE_CODE_SESSION_ID).
+        const checkOpts = options.project !== undefined ? { projectRootOverride: options.project } : {};
+        if (options.currentOuter !== undefined) {
+            checkOpts.currentOuter = options.currentOuter;
+        }
+        const result = checkStalePresence(checkOpts);
+        // Always emit `currentOuterSessionId` in the JSON envelope (even
+        // when undefined → ''), per slice 002 AC-1 contract: downstream
+        // tooling (statusline, sub-agent dispatch) reads the field by
+        // name, never by `data.currentOuterSessionId ?? ''`. JSON.stringify
+        // drops `undefined` properties, so we coerce to '' before
+        // wrapping in the envelope.
+        const data = {
+            stale: result.stale,
+            reason: result.reason,
+            presence: result.presence,
+            currentOuterSessionId: result.currentOuterSessionId ?? '',
+            recordedOuterSessionId: result.recordedOuterSessionId ?? ''
+        };
+        printResult(io, ok('skill.presence:check-stale', data), options.json);
+    });
+    addJsonOption(skill
+        .command('heartbeat')
+        .description('Show the heartbeat status of the active Peaks skill')).action((options) => {
+        const presence = getSkillPresence();
+        if (presence === null) {
+            printResult(io, ok('skill.heartbeat', { active: false, heartbeat: 'none' }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.heartbeat', {
+            active: true,
+            skill: presence.skill,
+            gate: presence.gate ?? null,
+            lastHeartbeat: presence.lastHeartbeat ?? presence.setAt,
+            setAt: presence.setAt
+        }), options.json);
+    });
+    addJsonOption(skill
+        .command('heartbeat:touch')
+        .description('Update the heartbeat timestamp (called by the LLM each turn to confirm peaks skill context is alive)')).action((options) => {
+        const updated = touchSkillHeartbeat();
+        if (updated === null) {
+            printResult(io, ok('skill.heartbeat:touch', { active: false, heartbeat: 'none' }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.heartbeat:touch', {
+            active: true,
+            skill: updated.skill,
+            lastHeartbeat: updated.lastHeartbeat
+        }), options.json);
+    });
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description('Detect whether the latest assistant message lost the Peaks-Loop status header while a peaks skill is still active (slice 028 detection primitive).')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const message = options.message ?? '';
+        const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+        printResult(io, ok('skill.detect-marker-loss', result), options.json);
+    });
+    // Slice S0 — register `peaks skill search`. Sibling subcommand to
+    // list / runbook / presence; preserves the existing surface
+    // (HC-10 — 老入口保留).
+    registerSkillSearchCommand(program, io);
+}

package/dist/cli/commands/dispatch-from-dag.js

@@ -0,0 +1,251 @@
+/**
+ * `peaks sub-agent dispatch --from-dag <file>` — slice 2026-06-23-audit-3rd #7.
+ *
+ * Pulled out of `dispatch-commands.ts` to honor the 800-line file cap
+ * (Karpathy #2 Simplicity First). The single-dispatch action stays in
+ * `dispatch-commands.ts`; the DAG-dispatch path lives here because the
+ * two paths share no logic — the warm-path single dispatch does NOT
+ * load slice-dag / dag-orchestrator / contract-store (slice 9 perf),
+ * while the --from-dag codepath loads all three on first call.
+ *
+ * 2.7.0 slice-dag-dispatcher MVP: read a SliceDag from a file and run
+ * it through `runDag`. The orchestrator's `runSlice` is a thin wrapper
+ * that emits the per-IDE `buildToolCall` envelope for each topological
+ * level.
+ *
+ * 1.2 MVP scope: this dispatches the FIRST topological level synchronously
+ * (returns the dispatch specs); subsequent levels are not surfaced in
+ * the CLI envelope because the LLM-side runner must actually execute
+ * each `buildToolCall` and write the resulting contract before level 2+
+ * can be safely auto-advanced. The LLM re-invokes
+ * `peaks sub-agent dispatch --from-dag <file> --batch-id <id>` after
+ * writing level-1 contracts, which causes runDag to plan level 2+ with
+ * the level-1 ancestor contracts spliced into their dispatch prompts.
+ *
+ * Internally, runDag DOES iterate all levels so its join-barrier +
+ * cancel-on-fail path is exercised end-to-end during the MVP emit; only
+ * the CLI envelope is filtered to level-1 toolCalls (see `firstLevelIds`).
+ */
+import { randomUUID } from 'node:crypto';
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+export async function runDispatchFromDag(role, options, asJson, io) {
+    if (!options.fromDag)
+        return;
+    const projectRoot = options.project ?? process.cwd();
+    // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
+    // Auto-resolve sid from .peaks/_runtime/session.json before falling back.
+    const sid = options.sessionId
+        ?? process.env.PEAKS_SESSION_ID
+        ?? getCurrentSessionId(projectRoot)
+        ?? 'unknown-sid';
+    const rid = options.requestId ?? 'unknown-rid';
+    const batchId = options.batchId ?? randomUUID();
+    // Slice 9 (dispatch CLI latency): the --from-dag codepath loads three
+    // heavy modules (slice-dag, dag-orchestrator, contract-store) that
+    // transitively import 10+ more services. They are NOT touched by the
+    // warm-path single-dispatch action, so we lazy-load them here only
+    // when --from-dag is actually requested. The dynamic-import promise
+    // resolves on first call, then ESM caches the module for subsequent
+    // calls in the same process.
+    const [{ readFileSync }, sliceDagMod, dagOrchestratorMod, contractStoreMod] = await Promise.all([
+        import('node:fs'),
+        import('../../services/dispatch/slice-dag.js'),
+        import('../../services/code/dag-orchestrator.js'),
+        import('../../services/dispatch/contract-store.js')
+    ]);
+    const { validateDag, topologicalLevels, isSliceComplexity } = sliceDagMod;
+    const { runLayeredDag } = dagOrchestratorMod;
+    const { listContracts, hashContract } = contractStoreMod;
+    let dag;
+    try {
+        const raw = readFileSync(options.fromDag, 'utf8');
+        const parsed = JSON.parse(raw);
+        validateDag(parsed);
+        dag = parsed;
+    }
+    catch (err) {
+        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `failed to read or validate DAG from ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
+            'Check the JSON file at the given path; the DAG must have {nodes, edges} and pass validateDag().'
+        ]), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    // MVP (1.2): the orchestrator iterates topological levels + join
+    // barrier + cancel-on-fail end-to-end. The CLI's runner returns `done`
+    // for every leaf (so runDag's cancel-on-fail path is exercised when a
+    // leaf actually fails); the CLI envelope filters `emittedToolCalls` to
+    // the first level only (see `firstLevelIds`). The LLM-side runner
+    // re-invokes `--from-dag` for level 2+ after writing level-1
+    // contracts via `peaks contract write`.
+    let levelArr;
+    try {
+        levelArr = topologicalLevels(dag);
+    }
+    catch (err) {
+        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `topologicalLevels failed for ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
+            'The DAG passed validateDag() but topologicalLevels threw (likely a cycle that slipped past validateDag, or a runtime invariant).',
+            'Inspect the DAG file with the editor and re-invoke dispatch. (No peaks scan dag CLI ships in 2.7.0; if you need a programmatic DAG validator, import validateDag / topologicalLevels from src/services/dispatch/slice-dag.ts directly.)'
+        ]), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    // Read upstream contracts so downstream-level prompts (when re-invoked
+    // for level 2+) get auto-injected ancestors via `formatContractInjection`.
+    // At level-1 emit time, contracts is empty (no ancestors yet); the
+    // injection matters when the LLM re-invokes for level 2+ after writing
+    // level-1 contracts via `writeContract`.
+    const existingContracts = listContracts(projectRoot, sid);
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    const adapter = getAdapter(ide);
+    const dispatcher = adapter.subAgentDispatcher;
+    if (!dispatcher.supportsRole(role)) {
+        printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, [
+            'Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.'
+        ]), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    // Track per-level emissions so the CLI envelope can expose ONLY the
+    // first topological level to the LLM (matching MVP 1.2 semantics: LLM
+    // executes level-1 toolCalls, writes contracts via `peaks contract
+    // write`, then re-invokes `--from-dag` for level 2+). Level-2+ leaves
+    // still flow through runDag's join-barrier — their toolCalls are
+    // generated internally so the orchestrator's happy path is exercised
+    // end-to-end, but they are NOT surfaced in the CLI envelope (the LLM
+    // sees them only after re-invoking with fresh level-1 contracts).
+    const firstLevelIds = new Set(levelArr[0] ?? []);
+    const emittedToolCalls = [];
+    const emittedSliceIds = [];
+    // CLI runner: emit the per-slice `buildToolCall` envelope, then return
+    // `done` with an empty `publicSurface` placeholder. The orchestrator
+    // treats the slice as "CLI-emitted, awaiting LLM-side execution" and
+    // advances to the next topological level (or breaks on failure). The
+    // placeholder surface is intentionally empty: the real public surface
+    // arrives later via `peaks contract write` from the LLM-side runner,
+    // and overwrites the CLI placeholder contract written by `noopWriter`.
+    // Why not `cancelled`? Returning `cancelled` here short-circuits
+    // runDag's join-barrier + cancel-on-fail path — the orchestrator
+    // breaks out after the first level with a cancellation, which hides
+    // the real cancel-on-fail semantics from the test suite (and from any
+    // future caller that wants to use `runDag` end-to-end from the CLI).
+    // Returning `done` exercises the full happy path; cancel-on-fail
+    // semantics will be covered when 1.3 lands real per-IDE await.
+    const cliRunner = async (spec) => {
+        const toolCall = dispatcher.buildToolCall({
+            role: spec.role,
+            prompt: spec.prompt,
+            requestId: rid,
+            sessionId: sid
+        });
+        if (firstLevelIds.has(spec.sliceId)) {
+            emittedToolCalls.push(toolCall);
+            emittedSliceIds.push(spec.sliceId);
+        }
+        return {
+            status: 'done',
+            publicSurface: {
+                exports: [],
+                types: [],
+                publicSignatures: []
+            }
+        };
+    };
+    // CLI noop writer — the orchestrator collects a `SliceContract` per
+    // emitted toolCall so downstream re-invocations (level 2+) can splice
+    // ancestor contracts via `formatContractInjection`. We don't write to
+    // disk here (the LLM-side runner does that via `peaks contract write`
+    // after each toolCall resolves), but the returned placeholder MUST be
+    // shape-valid: the `contractHash` field has to be a real SHA-256 hex
+    // string so formatContractInjection + downstream validators don't
+    // reject the placeholder. The placeholder hash is computed from the
+    // slice identity only (`sliceId|sessionId`) — it's deterministic,
+    // stable, and collision-free for the MVP run, but obviously does NOT
+    // represent the slice's actual public surface. The LLM-side runner's
+    // `peaks contract write` call will overwrite this with a content-based
+    // hash once the slice finishes.
+    const noopWriter = (sliceId, _publicSurface) => {
+        const partial = {
+            sliceId,
+            sessionId: sid,
+            exports: [],
+            types: [],
+            publicSignatures: []
+        };
+        return {
+            sliceId,
+            sessionId: sid,
+            completedAt: new Date(0).toISOString(), // epoch sentinel = "placeholder, not yet finished"
+            exports: [],
+            types: [],
+            publicSignatures: [],
+            contractHash: hashContract(partial)
+        };
+    };
+    // runLayeredDag IS in the path: validates the DAG, iterates all
+    // topological levels (foundation/upstreamSync slices prioritized within
+    // each level by `topologicalLevels`), runs the join barrier after
+    // each level, and triggers cancel-on-fail rollback if any leaf
+    // returns `failed` (or `cancelled`, once 1.3 lands). The CLI
+    // envelope below filters `emittedToolCalls` / `emittedSliceIds` to
+    // the first level — see the `firstLevelIds` filter inside `cliRunner`.
+    try {
+        await runLayeredDag(dag, {
+            projectRoot,
+            sessionId: sid,
+            existingContracts,
+            runSlice: cliRunner,
+            writeContractFn: noopWriter
+        });
+    }
+    catch (err) {
+        // runLayeredDag throws DagPlanError for plan-level failures (e.g.
+        // cycle slipping past validateDag). Surface it as INVALID_DAG so
+        // the CLI envelope has a clear failure code, not a generic
+        // DISPATCH_ERROR.
+        printResult(io, fail('sub-agent.dispatch', 'INVALID_DAG', `runLayeredDag failed for ${options.fromDag}: ${err.message}`, { role, toolCall: null, dispatchRecordPath: null }, [
+            'runLayeredDag threw DagPlanError; the DAG passed validateDag() but failed at topologicalLevels or contractStore dispatch.',
+            'Inspect the DAG file and re-run.'
+        ]), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, ok('sub-agent.dispatch', {
+        // Slice 2026-06-23-audit-4th #E1: envelopeVersion marker
+        envelopeVersion: '2.1.0',
+        role,
+        ide: dispatcher.label,
+        fromDag: options.fromDag,
+        batchId,
+        dispatchCount: emittedSliceIds.length,
+        levelsTotal: levelArr.length,
+        firstLevel: emittedSliceIds,
+        toolCalls: emittedToolCalls,
+        existingContractCount: existingContracts.length,
+        // v2.15.0 follow-up — G12/G11/G2: per-slice metadata (foundation /
+        // upstreamSync / complexity) for downstream scheduling decisions.
+        sliceMeta: emittedSliceIds.map((id) => {
+            const node = dag.nodes.find((n) => n.id === id);
+            return {
+                id,
+                foundation: node?.foundation === true,
+                upstreamSync: node?.upstreamSync === true,
+                complexity: node?.complexity !== undefined && isSliceComplexity(node.complexity)
+                    ? node.complexity
+                    : null
+            };
+        }),
+        nextActions: [
+            'Execute each toolCall in your IDE; on completion, write the slice contract to .peaks/_runtime/<sid>/dispatch/contracts/<slice-id>.json.',
+            'Re-invoke `peaks sub-agent dispatch --from-dag <file>` with the same batch-id to advance to the next level once all current-level slices have written contracts.'
+        ]
+    }, [], [
+        'MVP (1.2) plans the first level via runLayeredDag orchestrator (cancel-on-fail path active); the LLM drives subsequent levels by re-invoking this command after contract writes.',
+        existingContracts.length > 0
+            ? `Injected ${existingContracts.length} upstream contract(s) into downstream-level prompts via formatContractInjection.`
+            : 'No upstream contracts found; first-level prompts have empty ancestor blocks.'
+    ]), asJson);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * peaks evolution * CLI — M4 / spec §4.4 / §6 / §7.4
+ *
+ * Adds the Darwin-style ratchet CLI surface:
+ *
+ *   peaks evolution propose --target <kind:id> --dimension <name> \
+ *     --before-score <n> --after-score <n> [--delta-min <n>] \
+ *     --author <id> [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution evaluate --proposal <id> \
+ *     --evaluator <id> --skeptic <id> \
+ *     --evaluator-score <n> [--refute-paragraph <text>] \
+ *     [--risk-tag <tag>]... [--brief-pointer <path>] [--project <root>] [--json]
+ *   peaks evolution revert --proposal <id> [--user-confirmation <ptr>] [--project <root>] [--json]
+ *   peaks evolution status [--target <kind:id>] [--project <root>] [--json]
+ *
+ * Each verb prints a structured JSON envelope (`printResult` with
+ * `asJson=true`). The CLI is a thin shim around EvolutionService +
+ * the two runner modules. Author / evaluator / skeptic identities
+ * are LLM-supplied; the user is NEVER asked to type them.
+ *
+ * Defense in depth: the EvolutionService enforces the ratchet
+ * rules (AC-8 / AC-10 / AC-11); the CLI only translates flags
+ * into the service payload.
+ */
+import { Command } from "commander";
+import { type ProgramIO } from "../cli-helpers.js";
+export declare function registerEvolutionCommands(program: Command, io: ProgramIO): void;