peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/dispatch-prompt-composition.js

@@ -0,0 +1,171 @@
+// The prompt `peaks sub-agent dispatch` hands a sub-agent: the adapter check, the
+// optional preflight blocks (memory / codegraph / UI library / fresh context /
+// context probe / session capsule), the isolation and must-ls-files blocks, and the
+// warning list the envelope carries.
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+import { DEFAULT_PREFERENCES } from '../../services/preferences/preferences-types.js';
+import { MemoryPreflightService, deriveMemoryQuery } from '../../services/context/memory-preflight-service.js';
+import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch-system-prompt.js';
+import { readSessionCapsule } from '../../services/dispatch/session-capsule.js';
+import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-library-dispatch-block.js';
+import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
+import { deprecatedReviewerWarnings } from './sub-agent-shared.js';
+import { buildIsolationBlock, buildMustLsFilesBlock } from './dispatch-prompt-blocks.js';
+// loadPreferences can throw on schema mismatch; we fall back to defaults
+// to avoid breaking the dispatch on a stale preferences.json file.
+function loadProjectPreferences(projectRoot) {
+    try {
+        return loadPreferences(projectRoot);
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // Keep default preferences.
+        return DEFAULT_PREFERENCES;
+    }
+}
+function rejectUnsupportedIde(io, ide, role, asJson) {
+    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 null;
+}
+// memory preflight block (or silently skip when unavailable) via the
+// pure-function builder.
+function loadMemoryBlock(projectRoot, projectPrefs, role, prompt) {
+    const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
+    // task at hand (role + first line of the brief), not the bare role.
+    return preflightService.fetchBlock(deriveMemoryQuery(role, prompt));
+}
+// codegraph preflight for RD planning. BEFORE the RD sub-agent's
+// prompt is composed, ensure the index exists (init + index best-effort
+// when `.codegraph/` is absent) and read a BOUNDED structure summary.
+// `rd` only — other roles keep the legacy prompt byte-identical.
+// Fail-soft: any failure degrades and dispatch proceeds. On failure the
+// preflight's NOTE — the upstream cause — travels as the same value as
+// the block, so the reason cannot be dropped while the block survives.
+// The old `block : null` dropped it, so every degraded dispatch read as success.
+async function loadCodegraphBlock(projectRoot, role) {
+    let codegraphBlock;
+    if (role === 'rd') {
+        try {
+            const { buildCodegraphPreflightBlock } = await import('../../services/codegraph/codegraph-preflight-service.js');
+            const preflight = await buildCodegraphPreflightBlock(projectRoot);
+            codegraphBlock = preflight.available ? preflight.block : preflight.note;
+        }
+        catch (error) {
+            codegraphBlock = `codegraph preflight threw: ${getErrorMessage(error)}`;
+        }
+    }
+    return codegraphBlock;
+}
+// component library (+ CSS framework + build tool) in the RD/UI
+// dispatch system prompt so the sub-agent prefers the library over
+// hand-rolled native DOM. Only injected for frontend-generating roles
+// (rd + ui) — qa/sc/txt/prd keep the legacy prompt byte-identical.
+// Fail-soft inside the wrapper: a detection error degrades to null.
+function loadProjectStackBlock(projectRoot, role) {
+    let projectStackBlock;
+    if (role === 'rd' || role === 'ui') {
+        projectStackBlock = computeUiLibraryDispatchBlock(projectRoot);
+    }
+    return projectStackBlock;
+}
+// Slice 2026-09-07-search-first-preflight: read the orchestrator-
+// synthesized fresh-context block for rd + prd dispatches. The block
+// was written to .peaks/_runtime/<sid>/fresh-context.md when the
+// preflight triggered; it carries ≤5 binding directives that hedge
+// model training-data lag. Fail-soft: a missing / unreadable file, or
+// a file without the `## Fresh context` heading, degrades to null so
+// the prompt stays byte-identical to the legacy shape. Other roles
+// (qa/sc/txt/ui) keep the legacy prompt unchanged.
+function loadFreshContextBlock(projectRoot, sid, role) {
+    let freshContextBlock;
+    if (role === 'rd' || role === 'prd') {
+        freshContextBlock = readFreshContextBlock(projectRoot, sid);
+    }
+    return freshContextBlock;
+}
+// authoritative context-fill probe before composing the
+// dispatch prompt. The probe is token-counted (IDE adapter's
+// `compact` env-var), not a byte estimate. The composer
+// prepends a `## Context window` block so the dispatched
+// sub-agent reads the actual ratio instead of guessing
+// from message length (char/4 estimates diverge by 2-4x
+// and have caused false "context too low" reports at 60%+
+// free).
+async function loadContextProbe(projectRoot, sid) {
+    let contextProbe = null;
+    try {
+        const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+        const outerSessionId = resolveOuterSessionId(projectRoot, sid);
+        contextProbe = readContextPercent({
+            projectRoot,
+            sessionId: sid,
+            outerSessionId,
+            env: process.env
+        });
+    }
+    catch {
+        // Probe is best-effort; the composer renders a
+        // "no probe available" hint instead of failing the
+        // dispatch.
+    }
+    return contextProbe;
+}
+async function composeMemoryAugmentedBody(input, projectPrefs) {
+    const { projectRoot, sid, rid, role, prompt } = input;
+    const memoryBlock = await loadMemoryBlock(projectRoot, projectPrefs, role, prompt);
+    const codegraphBlock = await loadCodegraphBlock(projectRoot, role);
+    const projectStackBlock = loadProjectStackBlock(projectRoot, role);
+    const freshContextBlock = loadFreshContextBlock(projectRoot, sid, role);
+    const contextProbe = await loadContextProbe(projectRoot, sid);
+    // capsule published by the orchestrator via `peaks sub-agent share`.
+    // Absent capsule → no pointer and no precedence line (byte-identical
+    // legacy prompt).
+    const capsuleRef = readSessionCapsule({ projectRoot, sid, rid });
+    return buildDispatchSystemPrompt({
+        taskTitle: role,
+        taskBody: prompt,
+        memoryBlock,
+        // unified Test Tool Detection injection for every role.
+        contextProbe,
+        // exactOptionalPropertyTypes: only set codegraphBlock when the rd
+        // preflight actually produced a value (null = attempted-unavailable,
+        // undefined = not requested → legacy prompt unchanged).
+        ...(codegraphBlock !== undefined ? { codegraphBlock } : {}),
+        // Same optionality contract for the project-stack block: set only
+        // when the rd/ui detection ran (null = no library → no block,
+        // undefined = non-frontend role → legacy prompt unchanged).
+        ...(projectStackBlock !== undefined ? { projectStackBlock } : {}),
+        // Same optionality contract for the fresh-context block: set only
+        // when the rd/prd read ran (null = no block on disk → no block,
+        // undefined = non-rd/prd role → legacy prompt unchanged).
+        ...(freshContextBlock !== undefined ? { freshContextBlock } : {}),
+        // §4: advisory session capsule pointer + precedence line.
+        ...(capsuleRef !== null
+            ? {
+                capsule: { batchId: capsuleRef.batchId, key: capsuleRef.key, bytes: capsuleRef.bytes }
+            }
+            : {})
+    });
+}
+export async function composeDispatchPrompt(io, input) {
+    const { projectRoot, role, options, isolationMode, leaseId, worktreePath, worktreeBranch, decision, asJson } = input;
+    const projectPrefs = loadProjectPreferences(projectRoot);
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    const adapter = getAdapter(ide);
+    if (!adapter.subAgentDispatcher.supportsRole(role)) {
+        return rejectUnsupportedIde(io, ide, role, asJson);
+    }
+    const memoryAugmentedBody = await composeMemoryAugmentedBody(input, projectPrefs);
+    const isolationBlock = buildIsolationBlock(isolationMode, leaseId, worktreePath, worktreeBranch);
+    const { mustLsFilesVerification, mustLsFilesBlock } = buildMustLsFilesBlock(options, projectRoot);
+    const effectivePrompt = `${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
+    // + rerouted here, never refused — rationale on the helper itself.
+    const warnings = [...decision.warnings, ...deprecatedReviewerWarnings(role)];
+    return { adapter, effectivePrompt, warnings, mustLsFilesVerification };
+}

package/dist/cli/commands/dispatch-record-write.d.ts

@@ -0,0 +1,24 @@
+import { noteDispatched } from '../../services/dispatch/batch-counter.js';
+import { type ArtifactMeta } from '../../services/context/artifact-meta.js';
+import { type SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+export interface WriteDispatchRecordInput {
+    options: DispatchOptions;
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    effectivePrompt: string;
+    toolCall: SubAgentToolCall;
+    batchId: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    /** The dispatch's warning list — this function appends to it, as the inline block did. */
+    warnings: string[];
+}
+export interface DispatchRecordWrite {
+    artifactMeta: ArtifactMeta | null;
+    dispatchRecordPath: string;
+    counter: ReturnType<typeof noteDispatched>;
+}
+export declare function writeDispatchRecord(input: WriteDispatchRecordInput): DispatchRecordWrite;

package/dist/cli/commands/dispatch-record-write.js

@@ -0,0 +1,96 @@
+// The `peaks sub-agent dispatch` record write: the optional G7 artifact meta, the graph
+// node binding, the dispatch record itself, and the batch counter.
+import { existsSync } from 'node:fs';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { noteDispatched } from '../../services/dispatch/batch-counter.js';
+import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { provisionDispatchNode } from '../../services/workflow/provision-dispatch-node.js';
+import { buildArtifactMeta } from '../../services/context/artifact-meta.js';
+import { assertSafeArtifactPath } from 'peaks-loop-shared-channel';
+// G7 — optional --write-artifact: build ArtifactMeta, attach to record.
+function resolveArtifactMeta(input) {
+    const { options, projectRoot, rid, role, warnings } = input;
+    let artifactMeta = null;
+    if (typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0) {
+        try {
+            assertSafeArtifactPath(options.writeArtifact, projectRoot);
+            if (!existsSync(options.writeArtifact)) {
+                warnings.push('ARTIFACT_NOT_FOUND');
+            }
+            else {
+                artifactMeta = buildArtifactMeta({
+                    path: options.writeArtifact,
+                    rid,
+                    role,
+                    idx: 1, // single dispatch, idx=1
+                    summary: null
+                });
+            }
+        }
+        catch (err) {
+            warnings.push(`ARTIFACT_PATH_INVALID: ${getErrorMessage(err)}`);
+        }
+    }
+    return artifactMeta;
+}
+// Slice 4.0.8 RD §4 D4c: bind this dispatch to a graph node. When the
+// caller names none, provision one — that is what collapses the
+// documented three-step ritual (create graph -> `peaks workflow node
+// prepare` -> dispatch) into a single call. Those three fields were
+// also never passed to the writer, so the record's graph binding was
+// always null and the writer's transition never fired: the feature was
+// inert, and only its precondition (the required flag) was real.
+function resolveGraphBinding(options, projectRoot, sid, role) {
+    if (typeof options.graphNode === 'string' && options.graphNode.length > 0) {
+        return {
+            nodeId: options.graphNode,
+            workflowId: options.workflowId ?? null,
+            graphRef: options.graphRef ?? null
+        };
+    }
+    const provisioned = provisionDispatchNode({
+        projectRoot,
+        sessionId: sid,
+        role,
+        workflowId: options.workflowId,
+        graphRef: options.graphRef
+    });
+    return {
+        nodeId: provisioned.nodeId,
+        workflowId: provisioned.workflowId,
+        graphRef: provisioned.graphRef
+    };
+}
+export function writeDispatchRecord(input) {
+    const { options, projectRoot, sid, rid, role, effectivePrompt, toolCall, batchId, isolationMode, leaseId, warnings } = input;
+    const artifactMeta = resolveArtifactMeta(input);
+    const graphBinding = resolveGraphBinding(options, projectRoot, sid, role);
+    const { path: dispatchRecordPath } = writeInitialDispatchRecord({
+        projectRoot,
+        sessionId: sid,
+        requestId: rid,
+        role,
+        prompt: effectivePrompt,
+        workflowId: graphBinding.workflowId,
+        graphNodeId: graphBinding.nodeId,
+        graphRef: graphBinding.graphRef,
+        toolCall,
+        batchId,
+        // lease id on the dispatch record so the finalize-time
+        // release hook (markCompleted / heartbeat --status done) can
+        // auto-fire `peaks worktree release` when the sub-agent
+        // completes. Null when --isolation was not requested.
+        leaseId,
+        // ISO timestamp when the isolation mode was set up. Null
+        // when --isolation was not requested. The dashboard reads
+        // this directly off the dispatch record to compute
+        // isolation duration without cross-referencing the
+        // metrics stream.
+        isolationStartedAt: isolationMode !== null ? new Date().toISOString() : null
+    });
+    const counter = noteDispatched(projectRoot, sid, batchId);
+    if (counter.warning) {
+        warnings.push(counter.warning.message);
+    }
+    return { artifactMeta, dispatchRecordPath, counter };
+}

package/dist/cli/commands/dispatch-tool-call.d.ts

@@ -0,0 +1,15 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { type SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+export interface BuildDispatchToolCallInput {
+    adapter: ReturnType<typeof getAdapter>;
+    role: string;
+    effectivePrompt: string;
+    rid: string;
+    sid: string;
+    projectRoot: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    asJson: boolean;
+}
+export declare function buildDispatchToolCall(io: ProgramIO, input: BuildDispatchToolCallInput): SubAgentToolCall | null;

package/dist/cli/commands/dispatch-tool-call.js

@@ -0,0 +1,128 @@
+// The tool call `peaks sub-agent dispatch` returns: built by the active adapter, then
+// stamped with the isolation lease, the provenance token, the Playwright profile env
+// and the observability event.
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { SubAgentNotSupportedError } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { emitObservabilityEvent, OBSERVABILITY_SUBAGENT_ROLES } from '../../services/observability/observability-service.js';
+import { createDispatchProvenanceToken, DISPATCH_PROVENANCE_ENV, writeDispatchProvenance } from '../../services/worktree/dispatch-provenance.js';
+import { playwrightProfilePaths } from '../../services/worktree/playwright-profile.js';
+function writeWorktreeProvenance(input) {
+    const { projectRoot, sid, rid, leaseId, provenanceToken } = input;
+    writeDispatchProvenance({
+        projectRoot,
+        record: {
+            schemaVersion: 1,
+            token: provenanceToken,
+            sessionId: sid,
+            requestId: rid,
+            leaseId,
+            isolation: 'worktree',
+            issuedAt: new Date().toISOString()
+        }
+    });
+}
+// Part 2.C: stamp the toolCall with `isolation` + a sub-agent
+// env block so adapters that surface it (Claude Code's Task
+// tool) propagate the lease id to the spawned process. The
+// env block is the canonical hook the PreToolUse gate reads
+// (gate-commands.ts: process.env.PEAKS_WORKTREE_LEASE_ID).
+function applyIsolationStamp(toolCall, input) {
+    const { projectRoot, sid, rid, isolationMode, leaseId } = input;
+    if (isolationMode !== null && leaseId !== null) {
+        const existingEnv = toolCall.args['env'] ?? {};
+        const provenanceToken = createDispatchProvenanceToken({
+            sessionId: sid,
+            requestId: rid,
+            leaseId
+        });
+        if (isolationMode === 'worktree') {
+            writeWorktreeProvenance({ projectRoot, sid, rid, leaseId, provenanceToken });
+        }
+        // two Playwright profile-isolation env vars so the sub-agent's
+        // browser MCP session lands in a deterministic
+        // `.peaks/_runtime/<sid>/pw-profiles/<dispatchId>/` directory
+        // (see src/services/worktree/playwright-profile.ts). Without
+        // these, concurrent dispatches share the user's default
+        // Chromium profile and corrupt cookies / localStorage.
+        const profile = playwrightProfilePaths({
+            projectRoot,
+            sessionId: sid,
+            dispatchId: rid
+        });
+        toolCall = {
+            ...toolCall,
+            args: {
+                ...toolCall.args,
+                isolation: isolationMode,
+                env: {
+                    ...existingEnv,
+                    PEAKS_WORKTREE_LEASE_ID: leaseId,
+                    PEAKS_PLAYWRIGHT_USER_DATA_DIR: profile.userDataDir,
+                    PEAKS_PLAYWRIGHT_PROFILE_NAME: profile.profileName,
+                    ...(isolationMode === 'worktree' ? { [DISPATCH_PROVENANCE_ENV]: provenanceToken } : {})
+                }
+            }
+        };
+    }
+    return toolCall;
+}
+// Slice C of v2.11.1 — observability hook #2/7. Fire-and-forget
+// per PRD Q4 (full-auto must never fail-loud). The
+// synchronous emit returns {written:false} on disk-full; we
+// deliberately swallow the result so dispatch contract is
+// unchanged. role is only included when it matches the schema's
+// known sub-agent role set; otherwise it's omitted (non-standard
+// roles like 'qa-business' would otherwise drop the event
+// through schema rejection).
+function emitDispatchObservability(input) {
+    const { adapter, role, effectivePrompt, sid, rid, projectRoot } = input;
+    const KNOWN_ROLES = new Set(OBSERVABILITY_SUBAGENT_ROLES);
+    const knownRole = KNOWN_ROLES.has(role)
+        ? role
+        : null;
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: new Date().toISOString(),
+        sessionId: sid,
+        category: 'dispatch',
+        ...(knownRole !== null ? { role: knownRole } : {}),
+        detail: {
+            requestId: rid,
+            ide: adapter.subAgentDispatcher.label,
+            promptBytes: effectivePrompt.length
+        }
+    }, { projectRoot });
+}
+function rejectUnsupportedAdapter(io, role, error, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', error.message, { role, toolCall: null, dispatchRecordPath: null }, ['Switch IDE or pick a role the current IDE supports.']), asJson);
+    process.exitCode = 1;
+    return null;
+}
+export function buildDispatchToolCall(io, input) {
+    const { adapter, role, effectivePrompt, rid, sid, projectRoot, isolationMode, leaseId, asJson } = input;
+    let toolCall;
+    try {
+        toolCall = adapter.subAgentDispatcher.buildToolCall({
+            role,
+            prompt: effectivePrompt,
+            requestId: rid,
+            sessionId: sid
+        });
+        toolCall = applyIsolationStamp(toolCall, {
+            projectRoot,
+            sid,
+            rid,
+            isolationMode,
+            leaseId
+        });
+        emitDispatchObservability({ adapter, role, effectivePrompt, sid, rid, projectRoot });
+    }
+    catch (error) {
+        if (error instanceof SubAgentNotSupportedError) {
+            return rejectUnsupportedAdapter(io, role, error, asJson);
+        }
+        throw error;
+    }
+    return toolCall;
+}

package/dist/cli/commands/doctor/invoke-from-code.js

@@ -3,7 +3,6 @@
  * Contract surface for peaks-code Step 11 → peaks-doctor bridge.
  * Writes proposal stub to .peaks/_runtime/<sid>/doctor/proposal.md.
  * Real LLM call is delegated to peaks-doctor (Phase D Task 24 detail).
- * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.6
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';

package/dist/cli/commands/e2e-verify.d.ts

@@ -1,7 +1,6 @@
 /**
  * e2e-verify — `peaks e2e verify --slice <rid>` CLI for the merged slice.
  *
- * Slice 2026-08-01-subagent-merge-and-e2e (Task 10). The parent session
  * calls this command once after the merge-back step. The CLI delegates
  * to `runE2EVerify`, which uses the e2e-fixtures reader
  * (`src/services/dispatch/e2e-fixtures.ts`) to enumerate the fixtures

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

@@ -10,7 +10,6 @@
  * `repository.url` is `git+https://github.com/affaan-m/ECC.git`).
  *
  *   - `peaks ecc install` — land/refresh the copy. Idempotent; prunes agents the
- *     installed package no longer ships.
  *   - `peaks ecc status` — package version + what landed and when.
  *   - `peaks ecc ls` — the roster with declared name + description (D-009
  *     fallback to filename + first body line when frontmatter is malformed).

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

@@ -0,0 +1,78 @@
+import { EvolutionService, type EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { type EvolutionTargetKind } from '../../services/evolution/evolution-types.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+/** A parsed `--target <kind:id>` flag. */
+export interface EvolutionTarget {
+    kind: EvolutionTargetKind;
+    id: string;
+}
+/**
+ * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
+ * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS
+ * union.
+ */
+export declare function parseTargetFlag(raw: string): EvolutionTarget | null;
+/** The shared `--target` parse failure envelope (`propose` + `status`). */
+export declare function invalidTargetFailure(command: string, target: string): ResultEnvelope<{
+    target: string;
+}>;
+/** The shared "no such proposal" failure envelope. */
+export declare function proposalNotFoundFailure(command: string, proposalId: string, nextActions: string[]): ResultEnvelope<{
+    proposalId: string;
+}>;
+/**
+ * Helper: collect repeatable `--risk-tag` values into an array.
+ * Commander's `collect` is not always available; we read
+ * `previous` from the default value.
+ */
+export declare function collectRepeatable(value: string, previous: string[]): string[];
+/** Upper bound of the 0..10 score scale used by proposal + evaluator scores. */
+export declare const SCORE_SCALE_MAX = 10;
+/** True when `value` is a finite number on the 0..10 score scale. */
+export declare function isScoreInRange(value: number): boolean;
+/** Inputs for {@link scoreRangeFailure}. */
+export interface ScoreRangeFailureArgs {
+    command: string;
+    code: string;
+    /** Message label, e.g. `before_score`. */
+    label: string;
+    /** CLI flag named in the hint, e.g. `--before-score`. */
+    flag: string;
+    /** `data` key carrying the raw value, e.g. `beforeScore`. */
+    key: string;
+    /** The raw, unparsed flag value. */
+    raw: string;
+}
+/** The shared "[0, 10] finite number" validation failure envelope. */
+export declare function scoreRangeFailure(args: ScoreRangeFailureArgs): ResultEnvelope<Record<string, string>>;
+/** The `--delta-min` validation failure envelope. */
+export declare function deltaMinFailure(command: string, raw: string): ResultEnvelope<Record<string, string>>;
+/** Run `body` against a fresh EvolutionService, closing the DB after. */
+export declare function withEvolutionDb<T>(project: string | undefined, body: (svc: EvolutionService) => T): T;
+/** `await`-friendly sibling of {@link withEvolutionDb}. */
+export declare function withEvolutionDbAsync<T>(project: string | undefined, body: (svc: EvolutionService) => Promise<T>): Promise<T>;
+/** Params for {@link reportIntegrityFailure}. */
+export interface IntegrityFailureReport {
+    io: ProgramIO;
+    command: string;
+    error: EvolutionIntegrityError;
+    nextActions: string[];
+    /** `options.json` — the caller's `--json` flag, possibly absent. */
+    asJson?: boolean | undefined;
+}
+/** Print an `EvolutionIntegrityError` envelope and set exit code 1. */
+export declare function reportIntegrityFailure(report: IntegrityFailureReport): void;
+/** Params for {@link reportFailure}. */
+export interface CommandFailureReport {
+    io: ProgramIO;
+    command: string;
+    code: string;
+    error: unknown;
+    data: Record<string, unknown>;
+    nextActions: string[];
+    /** `options.json` — the caller's `--json` flag, possibly absent. */
+    asJson?: boolean | undefined;
+}
+/** Print a generic `<command>_FAILED` envelope and set exit code 1. */
+export declare function reportFailure(report: CommandFailureReport): void;

package/dist/cli/commands/evolution-command-shared.js

@@ -0,0 +1,107 @@
+/**
+ * Shared helpers for the `peaks evolution *` subcommand modules
+ * (propose / evaluate / mark-keep / revert / status). Split out of
+ * `evolution-commands.ts` in the size-debt batch: every command name,
+ * option, envelope key, error code and exit-code site is unchanged.
+ *
+ * Nothing here holds module-level mutable state: each helper takes
+ * parameters and returns a value, and the DB helpers own the
+ * open/close pair so callers never see a half-closed handle.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { EvolutionService } from '../../services/evolution/evolution-service.js';
+import { EVOLUTION_TARGET_KINDS } from '../../services/evolution/evolution-types.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+/**
+ * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
+ * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS
+ * union.
+ */
+export function parseTargetFlag(raw) {
+    const idx = raw.indexOf(':');
+    if (idx <= 0 || idx === raw.length - 1)
+        return null;
+    const kind = raw.slice(0, idx);
+    const id = raw.slice(idx + 1);
+    if (!EVOLUTION_TARGET_KINDS.includes(kind))
+        return null;
+    return { kind: kind, id };
+}
+/** The shared `--target` parse failure envelope (`propose` + `status`). */
+export function invalidTargetFailure(command, target) {
+    return fail(command, 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']);
+}
+/** The shared "no such proposal" failure envelope. */
+export function proposalNotFoundFailure(command, proposalId, nextActions) {
+    return fail(command, 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${proposalId}' not found`, { proposalId }, nextActions);
+}
+/**
+ * Helper: collect repeatable `--risk-tag` values into an array.
+ * Commander's `collect` is not always available; we read
+ * `previous` from the default value.
+ */
+export function collectRepeatable(value, previous) {
+    if (Array.isArray(previous))
+        return [...previous, value];
+    return [value];
+}
+/** Upper bound of the 0..10 score scale used by proposal + evaluator scores. */
+export const SCORE_SCALE_MAX = 10;
+/** True when `value` is a finite number on the 0..10 score scale. */
+export function isScoreInRange(value) {
+    return Number.isFinite(value) && value >= 0 && value <= SCORE_SCALE_MAX;
+}
+/** The shared "[0, 10] finite number" validation failure envelope. */
+export function scoreRangeFailure(args) {
+    return fail(args.command, args.code, `${args.label} must be a finite number in [0, 10] (got "${args.raw}")`, { [args.key]: args.raw }, [`Pass a numeric ${args.flag} in [0, 10].`]);
+}
+/** The `--delta-min` validation failure envelope. */
+export function deltaMinFailure(command, raw) {
+    return fail(command, 'EVOLUTION_INVALID_DELTA_MIN', `delta_min must be a finite number >= 0 (got "${raw}")`, { deltaMin: raw }, ['Pass a numeric --delta-min >= 0 (default 1.0).']);
+}
+/**
+ * Resolve the project root, bootstrap an empty `.peaks/` dir when it
+ * is missing (so tests do not need a full peaks project) and open the
+ * state DB.
+ */
+function openEvolutionDb(project) {
+    const projectRoot = project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    if (!existsSync(join(projectRoot, '.peaks'))) {
+        mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+    }
+    return openStateDb(join(projectRoot, '.peaks', 'state.db'));
+}
+/** Run `body` against a fresh EvolutionService, closing the DB after. */
+export function withEvolutionDb(project, body) {
+    const db = openEvolutionDb(project);
+    try {
+        return body(new EvolutionService(db));
+    }
+    finally {
+        db.close();
+    }
+}
+/** `await`-friendly sibling of {@link withEvolutionDb}. */
+export async function withEvolutionDbAsync(project, body) {
+    const db = openEvolutionDb(project);
+    try {
+        return await body(new EvolutionService(db));
+    }
+    finally {
+        db.close();
+    }
+}
+/** Print an `EvolutionIntegrityError` envelope and set exit code 1. */
+export function reportIntegrityFailure(report) {
+    printResult(report.io, fail(report.command, report.error.code, report.error.message, { findings: report.error.findings }, report.nextActions), report.asJson);
+    process.exitCode = 1;
+}
+/** Print a generic `<command>_FAILED` envelope and set exit code 1. */
+export function reportFailure(report) {
+    printResult(report.io, fail(report.command, report.code, getErrorMessage(report.error), report.data, report.nextActions), report.asJson);
+    process.exitCode = 1;
+}