peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/workflow/workflow-autonomous-service.js

@@ -0,0 +1,306 @@
+import { join } from 'node:path';
+// Slice 2026-06-29-change-id-root-removal: `validateChangeIdOrThrow`
+// was removed with the change-id axis. Path-safety helpers now live
+// at `shared/path-safety.ts` if this module ever needs them.
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+import { getLocalArtifactPath, hasValidArtifactWorkspace } from '../artifacts/workspace-service.js';
+import { createCapabilityMapPlan } from '../recommendations/capability-map-service.js';
+import { createRdSwarmPlan } from '../rd/rd-service.js';
+import { createWorkflowRouterPlan } from './workflow-router-service.js';
+// Re-export the resume validation surface so external callers (CLI,
+// tests) keep importing from this module unchanged. The helpers
+// (`getResumeRequiredArtifacts`, `getResumeArtifactsStatus`,
+// `createResumePlan`) live in the sibling
+// `workflow-autonomous-resume-helpers.ts` module — see v2.18.3
+// file-split for the rationale. Function signatures and behaviour
+// are unchanged (verbatim move).
+import { getResumeRequiredArtifacts, getResumeArtifactsStatus, createResumePlan } from './workflow-autonomous-resume-helpers.js';
+export { getResumeRequiredArtifacts, getResumeArtifactsStatus, createResumePlan } from './workflow-autonomous-resume-helpers.js';
+const AUTONOMOUS_CONSTRAINTS = Object.freeze([
+    'dry-run-only',
+    'do-not-launch-workers',
+    'do-not-install-capabilities',
+    'do-not-mutate-claude-settings',
+    'do-not-mutate-target-repo',
+    'artifact-backed-resume-required',
+    'evidence-before-resume'
+]);
+const RESUME_ARTIFACTS_MISSING_NEXT_ACTIONS = Object.freeze([
+    'Persist autonomous goal package, RD plan, checkpoint, validation evidence, and resume instructions before autonomous resume.'
+]);
+const RESUME_ARTIFACTS_INVALID_NEXT_ACTIONS = Object.freeze([
+    'Refresh autonomous resume artifacts with matching change ids, valid JSON state, and passed validation evidence before autonomous resume.'
+]);
+function normalizeGoal(goal) {
+    const normalized = goal.trim();
+    if (!normalized) {
+        throw new Error('Goal must be non-empty');
+    }
+    return normalized;
+}
+function resolveArtifactWorkspacePath(request) {
+    return request.artifactWorkspacePath ?? (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
+}
+function hasArtifactWorkspace(request, artifactWorkspacePath) {
+    return !!request.workspace && !!artifactWorkspacePath && hasValidArtifactWorkspace(request.workspace, artifactWorkspacePath);
+}
+function createGoalPackage(sessionId, goal) {
+    return {
+        sessionId,
+        goal,
+        nonGoals: [
+            'Change product behavior without explicit approval.',
+            'Install MCP servers, hooks, agents, or router configuration during dry-run planning.',
+            'Store API keys or provider credentials in Peaks artifacts.'
+        ],
+        preservedBehavior: [
+            'Existing product behavior remains stable unless the accepted goal explicitly changes it.',
+            'Existing repository source files are not mutated by dry-run planning.',
+            'Intermediate artifacts remain outside the target repository source tree.'
+        ],
+        acceptanceCriteria: [
+            'A resumable autonomous RD plan exists with checkpoints, worker queue, and validation evidence requirements.',
+            'Curated capabilities from docs/accessRepo.md and docs/mcpServer.md are considered before custom implementation.',
+            'Resume after compact verifies checkpoints and evidence before continuing.',
+            'All execution remains dry-run until explicitly approved.'
+        ],
+        doneCondition: `The ${sessionId} autonomous plan is complete when all acceptance criteria pass, the worker queue is empty or blocked with next actions, and validation evidence is recorded.`,
+        resumeCondition: `Resume ${sessionId} only after checkpoint artifacts, worker queue state, and validation evidence requirements have been verified.`,
+        riskNotes: [
+            'Claude Code /goal is session-scoped and cannot be the only durable state source.',
+            'External capabilities may require installation, credentials, network access, or settings changes.',
+            'Large swarms need conflict groups and reducer evidence to avoid unsafe parallel edits.'
+        ]
+    };
+}
+const CAPABILITY_SURFACES = ['skill', 'mcp', 'plugin', 'expert'];
+function createCapabilitySurfaceSummary() {
+    return {
+        skill: 0,
+        mcp: 0,
+        plugin: 0,
+        expert: 0
+    };
+}
+function getCapabilitySurface(itemType) {
+    if (itemType === 'skill')
+        return 'skill';
+    if (itemType === 'mcp')
+        return 'mcp';
+    if (itemType === 'agent')
+        return 'expert';
+    return 'plugin';
+}
+function getCapabilityTrustLevel(sourceId) {
+    if (sourceId === 'skills/*/SKILL.md' || sourceId === 'local-peaks-skills') {
+        return 'local';
+    }
+    if (sourceId.startsWith('everything-claude-code')
+        || sourceId.startsWith('ruflo-')
+        || sourceId === 'superpowers'
+        || sourceId === 'openspec'
+        || sourceId === 'gstack'
+        || sourceId === 'impeccable'
+        || sourceId === 'andrej-karpathy-skills'
+        || sourceId === 'mattpocock-skills') {
+        return 'user-curated';
+    }
+    return 'third-party';
+}
+function getCapabilityPurpose(item) {
+    switch (item.category) {
+        case 'browser-validation':
+        case 'browser-debug':
+        case 'design-context':
+        case 'code-search':
+        case 'database-inspection':
+        case 'browser-agent':
+        case 'docs-lookup':
+        case 'design-source':
+        case 'code-review':
+        case 'security-review':
+        case 'coding-standards':
+        case 'worker-guidance':
+        case 'memory':
+        case 'context-management':
+        case 'ui-components':
+        case 'spec-workflow':
+        case 'repo-intelligence':
+        case 'openspec':
+        case 'workflow-methodology':
+        case 'workflow-reference':
+        case 'workflow-guidance':
+        case 'product-guidance':
+        case 'design-reference':
+        case 'ui-reference':
+        case 'engineering-guidance':
+        case 'typescript-guidance':
+        case 'quality-guidance':
+        case 'skill-pack':
+        case 'external-skill':
+        case 'design-critique':
+        case 'design-guidance':
+        case 'cloud-skill-pack':
+            return item.category;
+        default:
+            return item.itemType === 'mcp' ? 'docs-lookup' : 'workflow-guidance';
+    }
+}
+function getCapabilityActivation(status, itemType) {
+    switch (status) {
+        case 'available':
+            return 'available';
+        case 'installable':
+            return itemType === 'mcp' ? 'needs-credentials' : 'needs-install';
+        case 'disabled':
+            return 'not-active';
+        case 'unknown':
+        default:
+            return itemType === 'mcp' ? 'needs-credentials' : 'not-active';
+    }
+}
+function createCapabilityPlan(request) {
+    const catalogPlan = createCapabilityMapPlan({ installedCapabilityIds: request.workspace?.installedCapabilityIds ?? [] });
+    const surfaceSummary = createCapabilitySurfaceSummary();
+    const candidates = catalogPlan.items.map((item) => {
+        const surface = getCapabilitySurface(item.itemType);
+        const availability = catalogPlan.availability.find((availability) => availability.capabilityId === item.capabilityId);
+        surfaceSummary[surface] += 1;
+        return {
+            id: item.capabilityId,
+            source: item.sourceId,
+            purpose: getCapabilityPurpose(item),
+            surface,
+            kind: surface,
+            sourceType: item.itemType,
+            trustLevel: getCapabilityTrustLevel(item.sourceId),
+            activation: getCapabilityActivation(availability?.status ?? 'unknown', item.itemType),
+            risk: [item.riskLevel]
+        };
+    });
+    candidates.push({
+        id: 'local-peaks-skills',
+        source: 'skills/*/SKILL.md',
+        purpose: 'workflow-methodology',
+        surface: 'skill',
+        kind: 'skill',
+        sourceType: 'skill',
+        trustLevel: 'local',
+        activation: 'available',
+        risk: ['local-skill-boundary-misuse']
+    });
+    surfaceSummary.skill += 1;
+    return {
+        sources: uniqueStrings(['docs/accessRepo.md', 'docs/mcpServer.md', 'skills/*/SKILL.md', ...catalogPlan.sources.map((source) => source.sourceId)]),
+        policy: [
+            'reuse-curated-capabilities-before-custom-build',
+            'plan-capability-use-before-activation',
+            'require-explicit-approval-for-install-credentials-network-or-settings-mutation'
+        ],
+        candidates,
+        surfaces: [...CAPABILITY_SURFACES],
+        surfaceSummary
+    };
+}
+function createMvpPackage(request, routePlan, rdPlan, capabilityPlan, ready) {
+    return {
+        mode: request.mode,
+        codeMode: routePlan.codeMode,
+        executionMode: 'preview',
+        dryRun: true,
+        routePolicy: routePlan.routePolicy,
+        rdWaveNames: rdPlan.waves.map((wave) => wave.name),
+        capabilitySurfaces: [...capabilityPlan.surfaces],
+        capabilityCountBySurface: { ...capabilityPlan.surfaceSummary },
+        ready
+    };
+}
+function createGoalCommand(goalPackage) {
+    return {
+        command: `/goal ${goalPackage.doneCondition}`,
+        durable: false,
+        reason: 'Claude Code /goal can help continue across turns in the current session, but Peaks artifacts remain the durable state.'
+    };
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+export function createAutonomousWorkflowPlan(request) {
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // no structural validation gate fires here.
+    const goal = normalizeGoal(request.goal);
+    const maxWorkers = request.maxWorkers ?? 40;
+    const artifactWorkspacePath = resolveArtifactWorkspacePath(request);
+    const memoryBackupPath = artifactWorkspacePath ? join(artifactWorkspacePath, '.peaks', 'memory-backups', 'project-memory-primary') : null;
+    const sharedWorkspaceOptions = {
+        ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
+        ...(request.workspace ? { workspace: request.workspace } : {})
+    };
+    const goalPackage = createGoalPackage(request.sessionId, goal);
+    const available = hasArtifactWorkspace(request, artifactWorkspacePath);
+    const routePlan = createWorkflowRouterPlan({
+        mode: request.mode,
+        ...(request.codeMode !== undefined ? { codeMode: request.codeMode } : {}),
+        sessionId: request.sessionId,
+        goal,
+        maxWorkers,
+        dryRun: true,
+        ...(request.config ? { config: request.config } : {}),
+        ...sharedWorkspaceOptions
+    });
+    const rdPlan = createRdSwarmPlan({
+        skill: 'rd',
+        sessionId: request.sessionId,
+        goal,
+        maxWorkers,
+        dryRun: true,
+        ...(request.config?.swarmMode !== undefined ? { swarmMode: request.config.swarmMode } : {}),
+        executionModelId: routePlan.modeStatus.executionModelId,
+        ...sharedWorkspaceOptions
+    });
+    const requiredArtifacts = getResumeRequiredArtifacts(request.sessionId);
+    const resumeArtifactsStatus = available && artifactWorkspacePath
+        ? getResumeArtifactsStatus(artifactWorkspacePath, requiredArtifacts, request.sessionId, goal)
+        : 'missing';
+    const blockedReasons = uniqueStrings([
+        ...routePlan.blockedReasons,
+        ...rdPlan.blockedReasons,
+        ...(available ? [] : ['artifact-workspace-unavailable']),
+        ...(resumeArtifactsStatus === 'missing' ? ['resume-artifacts-missing'] : []),
+        ...(resumeArtifactsStatus === 'invalid' ? ['resume-artifacts-invalid'] : [])
+    ]);
+    const ready = available && blockedReasons.length === 0;
+    const capabilityPlan = createCapabilityPlan(request);
+    const mvpPackage = createMvpPackage(request, routePlan, rdPlan, capabilityPlan, ready);
+    return {
+        available: ready,
+        behavior: ready ? 'ready' : 'preview',
+        sessionId: request.sessionId,
+        goal,
+        mode: request.mode,
+        dryRun: true,
+        goalPackage,
+        goalCommand: createGoalCommand(goalPackage),
+        capabilityPlan,
+        storagePlan: {
+            scope: 'user-local',
+            artifactWorkspacePath: artifactWorkspacePath ?? null,
+            memoryBackupPath: memoryBackupPath ?? null
+        },
+        routePlan,
+        modelAssignments: routePlan.modelAssignments,
+        rdPlan,
+        resumePlan: createResumePlan(request.sessionId, ready),
+        mvpPackage,
+        constraints: [...AUTONOMOUS_CONSTRAINTS],
+        blockedReasons,
+        nextActions: available
+            ? uniqueStrings([
+                ...routePlan.nextActions,
+                ...rdPlan.nextActions,
+                ...(resumeArtifactsStatus === 'missing' ? RESUME_ARTIFACTS_MISSING_NEXT_ACTIONS : []),
+                ...(resumeArtifactsStatus === 'invalid' ? RESUME_ARTIFACTS_INVALID_NEXT_ACTIONS : [])
+            ])
+            : [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+    };
+}

package/dist/services/workflow/workflow-autonomous-types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * peaks-workflow — public type declarations for autonomous workflow planning.
+ *
+ * Pure type module. No runtime helpers, no constants. The slimmed
+ * `workflow-autonomous-service.ts` re-exports the types so existing
+ * import paths compile unchanged (rid-006 split).
+ *
+ * Per PRD EC-1, this module is consumed by both
+ * `workflow-autonomous-service.ts` and
+ * `workflow-autonomous-resume-helpers.ts` via `import type`. Importing
+ * this types-only module breaks the existing
+ * resume-helpers ↔ autonomous-service runtime cycle (both modules
+ * previously re-exported `AutonomousResumePlan` from each other).
+ *
+ * File budget: ≤ 400 lines (rid-006 split).
+ */
+import type { CapabilityItemType } from '../recommendations/recommendation-types.js';
+import type { ModelProviderConfig, WorkspaceConfig } from '../config/config-types.js';
+import type { RdPlanResult } from '../rd/rd-service.js';
+import type { CodeMode, WorkflowMode, WorkflowRouterPlan } from './workflow-router-service.js';
+export type CapabilitySurface = 'skill' | 'mcp' | 'plugin' | 'expert';
+export type CapabilityPurpose = 'code-review' | 'security-review' | 'coding-standards' | 'docs-lookup' | 'browser-validation' | 'browser-debug' | 'design-context' | 'design-source' | 'code-search' | 'database-inspection' | 'browser-agent' | 'worker-guidance' | 'memory' | 'context-management' | 'ui-components' | 'spec-workflow' | 'repo-intelligence' | 'openspec' | 'workflow-methodology' | 'workflow-reference' | 'workflow-guidance' | 'product-guidance' | 'design-reference' | 'ui-reference' | 'engineering-guidance' | 'typescript-guidance' | 'quality-guidance' | 'skill-pack' | 'external-skill' | 'design-critique' | 'design-guidance' | 'cloud-skill-pack';
+export type CapabilityActivation = 'available' | 'needs-install' | 'needs-credentials' | 'not-active';
+export type CapabilityTrustLevel = 'local' | 'user-curated' | 'third-party';
+export type CapabilityCandidate = {
+    readonly id: string;
+    readonly source: string;
+    readonly purpose: CapabilityPurpose;
+    readonly surface: CapabilitySurface;
+    readonly kind: CapabilitySurface;
+    readonly sourceType: CapabilityItemType;
+    readonly trustLevel: CapabilityTrustLevel;
+    readonly activation: CapabilityActivation;
+    readonly risk: readonly string[];
+};
+export type AutonomousWorkflowRequest = {
+    readonly mode: WorkflowMode;
+    readonly codeMode?: CodeMode;
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly maxWorkers?: number;
+    readonly dryRun: true;
+    readonly artifactWorkspacePath?: string;
+    readonly workspace?: WorkspaceConfig;
+    readonly config?: {
+        readonly economyMode?: boolean;
+        readonly swarmMode?: boolean;
+        readonly providers?: ModelProviderConfig;
+    };
+};
+export type AutonomousGoalPackage = {
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly nonGoals: readonly string[];
+    readonly preservedBehavior: readonly string[];
+    readonly acceptanceCriteria: readonly string[];
+    readonly doneCondition: string;
+    readonly resumeCondition: string;
+    readonly riskNotes: readonly string[];
+};
+export type AutonomousCapabilityPlan = {
+    readonly sources: readonly string[];
+    readonly policy: readonly string[];
+    readonly candidates: readonly CapabilityCandidate[];
+    readonly surfaces: readonly CapabilitySurface[];
+    readonly surfaceSummary: Record<CapabilitySurface, number>;
+};
+export type AutonomousResumePlan = {
+    readonly status: 'preview' | 'ready';
+    readonly checkpoints: readonly string[];
+    readonly requiredArtifacts: readonly string[];
+    readonly resumeInstructions: string;
+};
+export type AutonomousGoalCommand = {
+    readonly command: string;
+    readonly durable: false;
+    readonly reason: string;
+};
+export type AutonomousStoragePlan = {
+    readonly scope: 'user-local';
+    readonly artifactWorkspacePath: string | null;
+    readonly memoryBackupPath: string | null;
+};
+export type AutonomousMvpPackage = {
+    readonly mode: WorkflowMode;
+    readonly codeMode: CodeMode | undefined;
+    readonly executionMode: 'preview';
+    readonly dryRun: true;
+    readonly routePolicy: WorkflowRouterPlan['routePolicy'];
+    readonly rdWaveNames: readonly string[];
+    readonly capabilitySurfaces: readonly CapabilitySurface[];
+    readonly capabilityCountBySurface: Record<CapabilitySurface, number>;
+    readonly ready: boolean;
+};
+export type AutonomousWorkflowPlan = {
+    readonly available: boolean;
+    readonly behavior: 'preview' | 'ready';
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly mode: WorkflowMode;
+    readonly dryRun: true;
+    readonly goalPackage: AutonomousGoalPackage;
+    readonly goalCommand: AutonomousGoalCommand;
+    readonly capabilityPlan: AutonomousCapabilityPlan;
+    readonly storagePlan: AutonomousStoragePlan;
+    readonly routePlan: WorkflowRouterPlan;
+    readonly modelAssignments: WorkflowRouterPlan['modelAssignments'];
+    readonly rdPlan: RdPlanResult;
+    readonly resumePlan: AutonomousResumePlan;
+    readonly mvpPackage: AutonomousMvpPackage;
+    readonly constraints: readonly string[];
+    readonly blockedReasons: readonly string[];
+    readonly nextActions: readonly string[];
+};

package/dist/services/workflow/workflow-autonomous-types.js

@@ -0,0 +1,21 @@
+/**
+ * peaks-workflow — public type declarations for autonomous workflow planning.
+ *
+ * Pure type module. No runtime helpers, no constants. The slimmed
+ * `workflow-autonomous-service.ts` re-exports the types so existing
+ * import paths compile unchanged (rid-006 split).
+ *
+ * Per PRD EC-1, this module is consumed by both
+ * `workflow-autonomous-service.ts` and
+ * `workflow-autonomous-resume-helpers.ts` via `import type`. Importing
+ * this types-only module breaks the existing
+ * resume-helpers ↔ autonomous-service runtime cycle (both modules
+ * previously re-exported `AutonomousResumePlan` from each other).
+ *
+ * File budget: ≤ 400 lines (rid-006 split).
+ */
+export {};
+// Note: `CapabilityAvailabilityStatus` is referenced by the orchestrator's
+// helper functions. It is imported (not re-exported) from the
+// recommendation-types module — keep this types module pure to the
+// declarations originally declared in `workflow-autonomous-service.ts`.

package/dist/services/workflow/workflow-loader.d.ts

@@ -0,0 +1,63 @@
+import { type WorkflowSpec, type WorkflowLintReport } from './workflow-spec.js';
+export type ResolvedWorkflowSource = {
+    kind: 'project';
+    path: string;
+} | {
+    kind: 'global';
+    path: string;
+} | {
+    kind: 'bundled';
+    path: string;
+} | {
+    kind: 'missing';
+};
+export interface ResolvedWorkflow {
+    readonly source: ResolvedWorkflowSource;
+    readonly spec: WorkflowSpec;
+    readonly lint: WorkflowLintReport;
+}
+/** Try the project → global → bundled fallback chain and parse + lint. */
+export declare function resolveWorkflow(projectRoot: string, id: string): ResolvedWorkflow;
+/** Render the plan-graph for a resolved workflow (used by `peaks workflow plan`). */
+export interface WorkflowPlanGraph {
+    readonly id: string;
+    readonly label: string;
+    readonly phases: ReadonlyArray<{
+        readonly id: string;
+        readonly role: string;
+        readonly gates: readonly string[];
+        readonly parallelGroup: string | null;
+        readonly dependsOn: readonly string[];
+    }>;
+    readonly parallelGroups: ReadonlyArray<{
+        readonly id: string;
+        readonly phaseIds: readonly string[];
+    }>;
+    readonly evaluators: ReadonlyArray<{
+        readonly type: string;
+        readonly gate: string | null;
+        readonly scope: string | null;
+    }>;
+    readonly budget: {
+        readonly tokens: number | null;
+        readonly wallSeconds: number | null;
+        readonly cycles: number | null;
+    };
+    readonly source: ResolvedWorkflowSource;
+}
+export declare function planWorkflow(spec: WorkflowSpec, source: ResolvedWorkflowSource): WorkflowPlanGraph;
+/** Run a workflow — deterministic step ordering for the runtime. */
+export interface WorkflowRunStep {
+    readonly phaseId: string;
+    readonly role: string;
+    readonly status: 'pending' | 'ready' | 'running' | 'completed' | 'failed' | 'skipped';
+    readonly dependsOn: readonly string[];
+    readonly parallelGroup: string | null;
+}
+export interface WorkflowRunPlan {
+    readonly id: string;
+    readonly steps: readonly WorkflowRunStep[];
+    /** Topological order, with parallel groups flattened to a single "ready" set. */
+    readonly order: readonly string[];
+}
+export declare function planWorkflowRun(spec: WorkflowSpec): WorkflowRunPlan;

package/dist/services/workflow/workflow-loader.js

@@ -0,0 +1,168 @@
+/**
+ * peaks-workflow v3.0.0 — Slice A.2
+ *
+ * Loader + resolver for `.peaks/workflows/<id>.yaml` (project) or
+ * `~/.peaks/workflows/<id>.yaml` (global, takes precedence when no
+ * project-local match). Mirrors ADR 0007 v2 concern #3: cross-project
+ * composition with project override.
+ *
+ * Resolved locations (first wins):
+ *   1. <projectRoot>/.peaks/workflows/<id>.yaml
+ *   2. <projectRoot>/.peaks/workflows/<id>.yml
+ *   3. ~/.peaks/workflows/<id>.yaml
+ *   4. ~/.peaks/workflows/<id>.yml
+ *
+ * The bundled default workflow lives at
+ * `<repo>/templates/workflows/default-fullauto-md.yaml` (git-tracked) — the
+ * default for v3.0.0 unless the project overrides it.
+ *
+ * Karpathy §2: single file, no IO beyond fs, no new deps.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseWorkflowYaml, lintWorkflowSpec } from './workflow-spec.js';
+/** Built-in default workflows shipped with peaks-loop (git-tracked). */
+const BUNDLED_WORKFLOWS = new Set(['default-fullauto-md', 'loop-with-quality-md']);
+/** Try the project → global → bundled fallback chain and parse + lint. */
+export function resolveWorkflow(projectRoot, id) {
+    const candidates = [
+        { kind: 'project', path: join(projectRoot, '.peaks', 'workflows', `${id}.yaml`) },
+        { kind: 'project', path: join(projectRoot, '.peaks', 'workflows', `${id}.yml`) },
+        { kind: 'global', path: join(homedir(), '.peaks', 'workflows', `${id}.yaml`) },
+        { kind: 'global', path: join(homedir(), '.peaks', 'workflows', `${id}.yml`) }
+    ];
+    for (const cand of candidates) {
+        if (!existsSync(cand.path))
+            continue;
+        const raw = readFileSync(cand.path, 'utf8');
+        const spec = parseWorkflowYaml(raw, id);
+        const lint = lintWorkflowSpec(spec);
+        return { source: cand, spec, lint };
+    }
+    if (BUNDLED_WORKFLOWS.has(id)) {
+        const bundledPath = bundledWorkflowPath(projectRoot, id);
+        if (existsSync(bundledPath)) {
+            const raw = readFileSync(bundledPath, 'utf8');
+            const spec = parseWorkflowYaml(raw, id);
+            const lint = lintWorkflowSpec(spec);
+            return { source: { kind: 'bundled', path: bundledPath }, spec, lint };
+        }
+    }
+    // Surface as missing — caller can choose to fail or fall back to the LLM-driven path.
+    return {
+        source: { kind: 'missing' },
+        spec: emptySpec(id),
+        lint: { ok: false, errors: [`workflow "${id}" not found in project, global, or bundled locations`], warnings: [] }
+    };
+}
+export function planWorkflow(spec, source) {
+    // Detect parallel groups (groups with ≥2 phases).
+    const groupMap = new Map();
+    for (const phase of spec.phases) {
+        if (phase.parallelGroup !== undefined) {
+            const arr = groupMap.get(phase.parallelGroup) ?? [];
+            arr.push(phase.id);
+            groupMap.set(phase.parallelGroup, arr);
+        }
+    }
+    const parallelGroups = [...groupMap.entries()]
+        .filter(([, phaseIds]) => phaseIds.length >= 2)
+        .map(([id, phaseIds]) => ({ id, phaseIds }));
+    return {
+        id: spec.id,
+        label: spec.label,
+        phases: spec.phases.map((p) => ({
+            id: p.id,
+            role: p.role,
+            gates: p.gates,
+            parallelGroup: p.parallelGroup ?? null,
+            dependsOn: p.dependsOn ?? []
+        })),
+        parallelGroups,
+        evaluators: spec.evaluators.map((e) => ({
+            type: e.type,
+            gate: e.gate ?? null,
+            scope: e.scope ?? null
+        })),
+        budget: {
+            tokens: spec.budget.tokens ?? null,
+            wallSeconds: spec.budget.wallSeconds ?? null,
+            cycles: spec.budget.cycles ?? null
+        },
+        source
+    };
+}
+/** Internal: bundled workflow path (relative to project root). The CLI layer
+ *  resolves the project root via `findProjectRoot`. */
+function bundledWorkflowPath(projectRoot, id) {
+    // Repo layout: bundled default workflows ship at
+    // <projectRoot>/templates/workflows/<id>.yaml (git-tracked). Project
+    // overrides still live at <projectRoot>/.peaks/workflows/<id>.yaml.
+    return join(projectRoot, 'templates', 'workflows', `${id}.yaml`);
+}
+export function planWorkflowRun(spec) {
+    const steps = spec.phases.map((p) => ({
+        phaseId: p.id,
+        role: p.role,
+        status: p.dependsOn === undefined || p.dependsOn.length === 0 ? 'ready' : 'pending',
+        dependsOn: p.dependsOn ?? [],
+        parallelGroup: p.parallelGroup ?? null
+    }));
+    // Build dependency-respecting order. Pure data — the runtime applies
+    // effects, this function only computes the sequence.
+    const completed = new Set();
+    const order = [];
+    const remaining = new Map(steps.map((s) => [s.phaseId, s]));
+    while (remaining.size > 0) {
+        const ready = [...remaining.values()].filter((s) => s.dependsOn.every((d) => completed.has(d)));
+        if (ready.length === 0) {
+            // Cycle or missing dep — emit remaining in declaration order to
+            // avoid infinite loop; lint should have caught this earlier.
+            const fallback = remaining.values().next().value;
+            if (fallback === undefined)
+                break;
+            order.push(fallback.phaseId);
+            completed.add(fallback.phaseId);
+            remaining.delete(fallback.phaseId);
+            continue;
+        }
+        // Parallel-group siblings are emitted in a single batch in declaration order.
+        const emittedIds = new Set();
+        for (const step of ready) {
+            if (emittedIds.has(step.phaseId))
+                continue;
+            if (step.parallelGroup !== null) {
+                const siblings = ready.filter((s) => s.parallelGroup === step.parallelGroup);
+                for (const sib of siblings) {
+                    if (emittedIds.has(sib.phaseId))
+                        continue;
+                    order.push(sib.phaseId);
+                    emittedIds.add(sib.phaseId);
+                    completed.add(sib.phaseId);
+                    remaining.delete(sib.phaseId);
+                }
+            }
+            else {
+                order.push(step.phaseId);
+                emittedIds.add(step.phaseId);
+                completed.add(step.phaseId);
+                remaining.delete(step.phaseId);
+            }
+        }
+    }
+    return { id: spec.id, steps, order };
+}
+function emptySpec(id) {
+    return {
+        schemaVersion: 1,
+        id,
+        label: id,
+        description: '',
+        phases: [],
+        gates: [],
+        evaluators: [],
+        contextSnapshot: { files: [], memory: [] },
+        budget: {}
+    };
+}