peaks-loop 4.0.54 → 4.1.1

package/dist/services/workflow/workflow-presence-lifecycle.js

@@ -11,9 +11,9 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { TERMINAL_REASONS, } from './workflow-graph-types.js';
-import { emptyGraph, readGraph, writeGraph, validateGraph, graphPathFor, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_TERMINAL_REASON_INVALID, } from './workflow-graph-store.js';
-import { setPresenceLease, readPresenceLease, markPresenceLost, } from '../skills/presence-lease-service.js';
+import { TERMINAL_REASONS } from './workflow-graph-types.js';
+import { emptyGraph, readGraph, writeGraph, validateGraph, graphPathFor, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_TERMINAL_REASON_INVALID } from './workflow-graph-store.js';
+import { setPresenceLease, readPresenceLease, markPresenceLost } from '../skills/presence-lease-service.js';
 function lifeError(code, message, extra = {}) {
     const err = new Error(message);
     err.name = 'TerminalizeError';
@@ -31,7 +31,7 @@ export async function initWorkflow(input) {
     const graph = emptyGraph({
         workflowId,
         rootSkill: input.skill,
-        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {})
     });
     validateGraph(graph);
     // Phase 1: write graph first.
@@ -41,7 +41,7 @@ export async function initWorkflow(input) {
         graphRef,
         workflowId,
         graph,
-        holder: `initWorkflow:${input.callerId}`,
+        holder: `initWorkflow:${input.callerId}`
     });
     // Phase 2: write lease + index.
     const setResult = setPresenceLease({
@@ -53,7 +53,7 @@ export async function initWorkflow(input) {
         skill: input.skill,
         ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
         depth: input.depth ?? 0,
-        ...(input.now ? { now: input.now } : {}),
+        ...(input.now ? { now: input.now } : {})
     });
     const events = [
         {
@@ -63,8 +63,8 @@ export async function initWorkflow(input) {
             sessionId: input.sessionId,
             callerId: input.callerId,
             workflowId,
-            graphRef,
-        },
+            graphRef
+        }
     ];
     return {
         workflowId,
@@ -72,7 +72,7 @@ export async function initWorkflow(input) {
         graph,
         lease: setResult.lease,
         index: setResult.index,
-        events,
+        events
     };
 }
 /* ---------- Terminalize ---------- */
@@ -88,7 +88,7 @@ export async function terminalizeWorkflow(input) {
             projectRoot: input.projectRoot,
             sessionId: input.sessionId,
             graphRef: input.graphRef,
-            workflowId: input.workflowId,
+            workflowId: input.workflowId
         });
         // Phase 2: check unconsumed envelopes (RD §4 terminalize contract).
         if (input.requireConsumed === true) {
@@ -99,9 +99,7 @@ export async function terminalizeWorkflow(input) {
         }
         // Phase 3: transition the terminal node to terminalized / lost.
         const targetStatus = input.reason === 'success' || input.reason === 'aborted' ? 'terminalized' : 'lost';
-        const updatedNodes = graph.nodes.map((n) => n.kind === 'terminal'
-            ? { ...n, status: targetStatus }
-            : n);
+        const updatedNodes = graph.nodes.map((n) => n.kind === 'terminal' ? { ...n, status: targetStatus } : n);
         const updatedGraph = { ...graph, nodes: updatedNodes };
         validateGraph(updatedGraph);
         // Phase 4: write the updated graph atomically.
@@ -111,7 +109,7 @@ export async function terminalizeWorkflow(input) {
             graphRef: input.graphRef,
             workflowId: input.workflowId,
             graph: updatedGraph,
-            holder: `terminalize:${input.callerId}`,
+            holder: `terminalize:${input.callerId}`
         });
         // Phase 5: mark the lease lost/terminalized. This will throw on
         // EACCES / ENOSPC — caught at the boundary so we can emit
@@ -125,7 +123,7 @@ export async function terminalizeWorkflow(input) {
             status: targetStatus === 'terminalized' ? 'terminalized' : 'lost',
             reason: input.reason,
             ...(input.now ? { now: input.now } : {}),
-            expectedCallerId: input.callerId,
+            expectedCallerId: input.callerId
         });
         // Phase 6: emit exactly one terminalized observability event.
         events.push({
@@ -136,14 +134,14 @@ export async function terminalizeWorkflow(input) {
             callerId: input.callerId,
             workflowId: input.workflowId,
             graphRef: input.graphRef,
-            terminalReason: input.reason,
+            terminalReason: input.reason
         });
         successEventCount = 1;
         return {
             lease,
             graph: updatedGraph,
             events,
-            indexCleared: true,
+            indexCleared: true
         };
     }
     catch (err) {
@@ -156,7 +154,7 @@ export async function terminalizeWorkflow(input) {
         const message = err.message ?? 'terminalize failed';
         throw lifeError(PEAKS_TERMINALIZE_ATOMICITY_FAILED, message, {
             successEventCount,
-            consistent: true,
+            consistent: true
         });
     }
 }
@@ -167,7 +165,7 @@ export function readWorkflowLease(projectRoot, sessionId, callerId, workflowId)
         sessionId,
         callerId,
         workflowId,
-        graphRef: `graphs/${workflowId}.json`,
+        graphRef: `graphs/${workflowId}.json`
     });
 }
 /* ---------- Helper for tests: probe whether a graph file exists ---------- */
@@ -176,7 +174,7 @@ export function graphFileExists(projectRoot, sessionId, workflowId) {
         projectRoot,
         sessionId,
         graphRef: `graphs/${workflowId}.json`,
-        workflowId,
+        workflowId
     });
     return existsSync(path);
 }
@@ -185,7 +183,7 @@ export function readGraphFile(projectRoot, sessionId, workflowId) {
         projectRoot,
         sessionId,
         graphRef: `graphs/${workflowId}.json`,
-        workflowId,
+        workflowId
     });
     if (!existsSync(path)) {
         throw new Error(`graph not found: ${path}`);

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

@@ -15,8 +15,16 @@ const WORKFLOW_CONSTRAINTS = Object.freeze([
     'do-not-mutate-target-repo'
 ]);
 const EXECUTION_STAGES = ['coding-execution', 'unit-test-execution'];
-const GUIDED_DECISION_STAGES = ['product-direction', 'design-direction'];
-const GOVERNED_DECISION_STAGES = ['product-direction', 'design-direction', 'tech-direction', 'tech-review'];
+const GUIDED_DECISION_STAGES = [
+    'product-direction',
+    'design-direction'
+];
+const GOVERNED_DECISION_STAGES = [
+    'product-direction',
+    'design-direction',
+    'tech-direction',
+    'tech-review'
+];
 export function isWorkflowMode(mode) {
     return mode === 'code' || mode === 'team';
 }
@@ -64,9 +72,7 @@ function getDecisionProfileSummary(mode, codeMode) {
     return 'Full-auto mode applies recommended defaults for product, design, and tech decisions, then runs the engineering pipeline end to end under routing gates.';
 }
 function annotateSteps(steps, codeMode) {
-    const decisionStages = codeMode === 'guided'
-        ? GUIDED_DECISION_STAGES
-        : GOVERNED_DECISION_STAGES;
+    const decisionStages = codeMode === 'guided' ? GUIDED_DECISION_STAGES : GOVERNED_DECISION_STAGES;
     return steps.map((currentStep) => {
         const isDecisionStage = decisionStages.includes(currentStep.stage);
         const reasonPrefix = isDecisionStage
@@ -81,14 +87,70 @@ function annotateSteps(steps, codeMode) {
 function createSoloSteps(executionModelId, strongestModelId, economyMode) {
     const executionTier = economyMode === false ? 'top-tier' : 'mid-tier';
     return [
-        step({ id: 'code-product-direction', stage: 'product-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Product direction needs strong judgment before execution work is delegated.', dependsOn: [] }, executionModelId, strongestModelId),
-        step({ id: 'code-design-direction', stage: 'design-direction', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Design direction uses the recommended default before cheaper implementation work.', dependsOn: ['code-product-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'code-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Technical boundaries and approval gates use the recommended default with high-confidence planning.', dependsOn: ['code-design-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'code-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Tech artifacts and gate decisions require strong review and a recommended default path.', dependsOn: ['code-tech-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'code-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'RD task decomposition and acceptance criteria use the recommended default before execution delegation.', dependsOn: ['code-tech-review'] }, executionModelId, strongestModelId),
-        step({ id: 'code-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Coding and routine refactoring must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-rd-planning'] }, executionModelId, strongestModelId),
-        step({ id: 'code-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Unit test authoring and focused test runs must use the configured execution worker model ${executionModelId}.`, dependsOn: ['code-coding-execution'] }, executionModelId, strongestModelId),
-        step({ id: 'code-quality-review', stage: 'quality-review', owner: 'peaks-code', modelTier: 'top-tier', reason: 'Reducer and final quality gates need strong synthesis and risk review.', dependsOn: ['code-unit-test-execution'] }, executionModelId, strongestModelId)
+        step({
+            id: 'code-product-direction',
+            stage: 'product-direction',
+            owner: 'peaks-code',
+            modelTier: 'top-tier',
+            reason: 'Product direction needs strong judgment before execution work is delegated.',
+            dependsOn: []
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-design-direction',
+            stage: 'design-direction',
+            owner: 'peaks-code',
+            modelTier: 'top-tier',
+            reason: 'Design direction uses the recommended default before cheaper implementation work.',
+            dependsOn: ['code-product-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-tech-direction',
+            stage: 'tech-direction',
+            owner: 'peaks-tech',
+            modelTier: 'top-tier',
+            reason: 'Technical boundaries and approval gates use the recommended default with high-confidence planning.',
+            dependsOn: ['code-design-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-tech-review',
+            stage: 'tech-review',
+            owner: 'peaks-tech',
+            modelTier: 'top-tier',
+            reason: 'Tech artifacts and gate decisions require strong review and a recommended default path.',
+            dependsOn: ['code-tech-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-rd-planning',
+            stage: 'rd-planning',
+            owner: 'peaks-rd',
+            modelTier: 'top-tier',
+            reason: 'RD task decomposition and acceptance criteria use the recommended default before execution delegation.',
+            dependsOn: ['code-tech-review']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-coding-execution',
+            stage: 'coding-execution',
+            owner: 'peaks-rd',
+            modelTier: executionTier,
+            reason: `Coding and routine refactoring must use the configured execution worker model ${executionModelId}.`,
+            dependsOn: ['code-rd-planning']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-unit-test-execution',
+            stage: 'unit-test-execution',
+            owner: 'peaks-rd',
+            modelTier: executionTier,
+            reason: `Unit test authoring and focused test runs must use the configured execution worker model ${executionModelId}.`,
+            dependsOn: ['code-coding-execution']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'code-quality-review',
+            stage: 'quality-review',
+            owner: 'peaks-code',
+            modelTier: 'top-tier',
+            reason: 'Reducer and final quality gates need strong synthesis and risk review.',
+            dependsOn: ['code-unit-test-execution']
+        }, executionModelId, strongestModelId)
     ];
 }
 function createSoloStepsForMode(codeMode, executionModelId, strongestModelId, economyMode) {
@@ -97,14 +159,70 @@ function createSoloStepsForMode(codeMode, executionModelId, strongestModelId, ec
 function createTeamSteps(executionModelId, strongestModelId, economyMode) {
     const executionTier = economyMode === false ? 'top-tier' : 'mid-tier';
     return [
-        step({ id: 'team-product-direction', stage: 'product-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team product direction should stay on the governed planning path.', dependsOn: [] }, executionModelId, strongestModelId),
-        step({ id: 'team-design-direction', stage: 'design-direction', owner: 'human', modelTier: 'top-tier', reason: 'Team design direction should preserve reviewability and accountability.', dependsOn: ['team-product-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'team-tech-direction', stage: 'tech-direction', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team technical plans should remain strongly governed before RD execution.', dependsOn: ['team-design-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'team-tech-review', stage: 'tech-review', owner: 'peaks-tech', modelTier: 'top-tier', reason: 'Team tech approval requires strong review before execution.', dependsOn: ['team-tech-direction'] }, executionModelId, strongestModelId),
-        step({ id: 'team-rd-planning', stage: 'rd-planning', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD task decomposition remains on the governed strongest-model path.', dependsOn: ['team-tech-review'] }, executionModelId, strongestModelId),
-        step({ id: 'team-coding-execution', stage: 'coding-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Bounded coding tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-rd-planning'] }, executionModelId, strongestModelId),
-        step({ id: 'team-unit-test-execution', stage: 'unit-test-execution', owner: 'peaks-rd', modelTier: executionTier, reason: `Unit-test tasks must use the configured execution worker model ${executionModelId}.`, dependsOn: ['team-coding-execution'] }, executionModelId, strongestModelId),
-        step({ id: 'team-quality-review', stage: 'quality-review', owner: 'peaks-rd', modelTier: 'top-tier', reason: 'Team RD outputs still need reducer and quality review gates.', dependsOn: ['team-unit-test-execution'] }, executionModelId, strongestModelId)
+        step({
+            id: 'team-product-direction',
+            stage: 'product-direction',
+            owner: 'human',
+            modelTier: 'top-tier',
+            reason: 'Team product direction should stay on the governed planning path.',
+            dependsOn: []
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-design-direction',
+            stage: 'design-direction',
+            owner: 'human',
+            modelTier: 'top-tier',
+            reason: 'Team design direction should preserve reviewability and accountability.',
+            dependsOn: ['team-product-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-tech-direction',
+            stage: 'tech-direction',
+            owner: 'peaks-tech',
+            modelTier: 'top-tier',
+            reason: 'Team technical plans should remain strongly governed before RD execution.',
+            dependsOn: ['team-design-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-tech-review',
+            stage: 'tech-review',
+            owner: 'peaks-tech',
+            modelTier: 'top-tier',
+            reason: 'Team tech approval requires strong review before execution.',
+            dependsOn: ['team-tech-direction']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-rd-planning',
+            stage: 'rd-planning',
+            owner: 'peaks-rd',
+            modelTier: 'top-tier',
+            reason: 'Team RD task decomposition remains on the governed strongest-model path.',
+            dependsOn: ['team-tech-review']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-coding-execution',
+            stage: 'coding-execution',
+            owner: 'peaks-rd',
+            modelTier: executionTier,
+            reason: `Bounded coding tasks must use the configured execution worker model ${executionModelId}.`,
+            dependsOn: ['team-rd-planning']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-unit-test-execution',
+            stage: 'unit-test-execution',
+            owner: 'peaks-rd',
+            modelTier: executionTier,
+            reason: `Unit-test tasks must use the configured execution worker model ${executionModelId}.`,
+            dependsOn: ['team-coding-execution']
+        }, executionModelId, strongestModelId),
+        step({
+            id: 'team-quality-review',
+            stage: 'quality-review',
+            owner: 'peaks-rd',
+            modelTier: 'top-tier',
+            reason: 'Team RD outputs still need reducer and quality review gates.',
+            dependsOn: ['team-unit-test-execution']
+        }, executionModelId, strongestModelId)
     ];
 }
 function uniqueStrings(values) {
@@ -184,7 +302,9 @@ export function createWorkflowRouterPlan(request) {
     // providers at all. An explicit empty object (`config: { providers: {} }`)
     // still surfaces the "must be configured" error from
     // `getConfiguredExecutionModelId`.
-    const effectiveProviders = request.config?.providers ?? { anthropic: { model: 'claude-opus-4-7' } };
+    const effectiveProviders = request.config?.providers ?? {
+        anthropic: { model: 'claude-opus-4-7' }
+    };
     // Slice 2026-07-09 add-zcode-adapter (A.3): the strongest
     // planner/reviewer model is now resolved via `getStrongestModelId`,
     // which reads `config.model` (if present) or falls back to the
@@ -195,15 +315,33 @@ export function createWorkflowRouterPlan(request) {
     const modeStatus = createModeStatus(economyMode, swarmMode, executionModelId, economyMode ? 'config.providers' : 'planner-reviewer-strongest-model', strongestModelId);
     const codeMode = getCodeMode(request.mode, request.codeMode);
     const decisionProfile = getDecisionProfileSummary(request.mode, codeMode);
-    const artifactWorkspacePath = request.artifactWorkspacePath ?? (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
+    const artifactWorkspacePath = request.artifactWorkspacePath ??
+        (request.workspace ? getLocalArtifactPath(request.workspace) : undefined);
     const sharedWorkspaceOptions = {
         ...(artifactWorkspacePath ? { artifactWorkspacePath } : {}),
         ...(request.workspace ? { workspace: request.workspace } : {})
     };
     const techStatus = getTechStatus({ sessionId: request.sessionId, ...sharedWorkspaceOptions });
-    const techPlan = createTechPlan({ sessionId: request.sessionId, goal, swarm: swarmMode, dryRun: true, ...sharedWorkspaceOptions });
-    const rdPlan = createRdSwarmPlan({ skill: 'rd', sessionId: request.sessionId, goal, maxWorkers, swarmMode, executionModelId, dryRun: true, ...sharedWorkspaceOptions });
-    const steps = codeMode ? createSoloStepsForMode(codeMode, executionModelId, strongestModelId, economyMode) : createTeamSteps(executionModelId, strongestModelId, economyMode);
+    const techPlan = createTechPlan({
+        sessionId: request.sessionId,
+        goal,
+        swarm: swarmMode,
+        dryRun: true,
+        ...sharedWorkspaceOptions
+    });
+    const rdPlan = createRdSwarmPlan({
+        skill: 'rd',
+        sessionId: request.sessionId,
+        goal,
+        maxWorkers,
+        swarmMode,
+        executionModelId,
+        dryRun: true,
+        ...sharedWorkspaceOptions
+    });
+    const steps = codeMode
+        ? createSoloStepsForMode(codeMode, executionModelId, strongestModelId, economyMode)
+        : createTeamSteps(executionModelId, strongestModelId, economyMode);
     const blockedReasons = uniqueStrings([
         ...techStatus.blockedReasons,
         ...getTechPlanBlockedReasons(techPlan),
@@ -211,7 +349,11 @@ export function createWorkflowRouterPlan(request) {
     ]);
     const nextActions = blockedReasons.includes('artifact-workspace-unavailable')
         ? [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
-        : uniqueStrings([...techStatus.nextActions, ...getTechPlanNextActions(techPlan), ...rdPlan.nextActions]);
+        : uniqueStrings([
+            ...techStatus.nextActions,
+            ...getTechPlanNextActions(techPlan),
+            ...rdPlan.nextActions
+        ]);
     return {
         sessionId: request.sessionId,
         goal,

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

@@ -55,11 +55,17 @@ export function detectCallerKind(envCallerId) {
 export async function canSkipSlice(projectRoot, sessionId, args, currentState) {
     // Argument validation (no filesystem).
     if (args.reason.trim().length === 0) {
-        return { allowed: false, reason: 'skip requires --reason; what is the user-visible justification for this QA bypass?' };
+        return {
+            allowed: false,
+            reason: 'skip requires --reason; what is the user-visible justification for this QA bypass?'
+        };
     }
     const gates = parseGatesList(args.gatesRaw);
     if (gates.length === 0) {
-        return { allowed: false, reason: '--gates must list at least one gate name (e.g. "QA" or "QA,slice-check")' };
+        return {
+            allowed: false,
+            reason: '--gates must list at least one gate name (e.g. "QA" or "QA,slice-check")'
+        };
     }
     // Resolve caller kind.
     const callerKind = args.callerKind ?? 'human';
@@ -72,7 +78,10 @@ export async function canSkipSlice(projectRoot, sessionId, args, currentState) {
     try {
         const rdArtifact = await showRequestArtifact({ projectRoot, role: 'rd', requestId: args.rid });
         if (rdArtifact === null) {
-            return { allowed: false, reason: `RD request artifact not found for rid "${args.rid}"; cannot determine slice type` };
+            return {
+                allowed: false,
+                reason: `RD request artifact not found for rid "${args.rid}"; cannot determine slice type`
+            };
         }
         sliceType = rdArtifact.requestType;
     }
@@ -194,7 +203,8 @@ function resolveSkipAppliedBy() {
             return trimmed;
         }
     }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         // fall through
     }
     try {

package/dist/services/workflow/workflow-spec-builders.d.ts

@@ -0,0 +1,15 @@
+/**
+ * peaks-workflow v3.0.0 — private spec builders (wave-5 hoist).
+ *
+ * The six module-private top-level declarations that used to sit in
+ * `workflow-spec.ts` — `VALID_EVALUATORS`, `ID_PATTERN`, `buildSpec`,
+ * `buildPhase`, `buildGate`, `buildEvaluator` — moved here VERBATIM so the
+ * parser file stays under the 300-line cap. None of them was ever public,
+ * so no import path moves: `workflow-spec.ts` is still the only module
+ * callers import, and it calls `buildSpec` after parsing the raw YAML.
+ *
+ * Karpathy §2 Simplicity First: pure functions, no IO, no new deps.
+ */
+import type { WorkflowSpec } from './workflow-spec-types.js';
+declare function buildSpec(root: Record<string, unknown>, expectedId: string): WorkflowSpec;
+export { buildSpec };

package/dist/services/workflow/workflow-spec-builders.js

@@ -0,0 +1,121 @@
+/**
+ * peaks-workflow v3.0.0 — private spec builders (wave-5 hoist).
+ *
+ * The six module-private top-level declarations that used to sit in
+ * `workflow-spec.ts` — `VALID_EVALUATORS`, `ID_PATTERN`, `buildSpec`,
+ * `buildPhase`, `buildGate`, `buildEvaluator` — moved here VERBATIM so the
+ * parser file stays under the 300-line cap. None of them was ever public,
+ * so no import path moves: `workflow-spec.ts` is still the only module
+ * callers import, and it calls `buildSpec` after parsing the raw YAML.
+ *
+ * Karpathy §2 Simplicity First: pure functions, no IO, no new deps.
+ */
+import { arrayField, numberField, objectField, stringArrayField, stringField } from './workflow-spec-yaml.js';
+const VALID_EVALUATORS = new Set([
+    'karpathy',
+    'code-review',
+    'security-review',
+    'perf-baseline',
+    'verdict-aggregate',
+    'monotonic-improvement',
+    'impact-scan',
+    'smoke-run',
+    'canary-watch'
+]);
+const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+function buildSpec(root, expectedId) {
+    const id = stringField(root, 'id', expectedId);
+    if (id !== expectedId) {
+        throw new Error(`workflow yaml: id "${id}" does not match filename "${expectedId}"`);
+    }
+    const schemaVersion = numberField(root, 'schemaVersion', 1);
+    if (schemaVersion !== 1) {
+        throw new Error(`workflow yaml: unsupported schemaVersion ${schemaVersion} (expected 1)`);
+    }
+    const phasesRaw = arrayField(root, 'phases');
+    const gatesRaw = arrayField(root, 'gates');
+    const evaluatorsRaw = arrayField(root, 'evaluators');
+    const snapshotRaw = objectField(root, 'contextSnapshot');
+    const budgetRaw = objectField(root, 'budget');
+    const phases = phasesRaw.map((p) => buildPhase(p));
+    const gates = gatesRaw.map((g) => buildGate(g));
+    const evaluators = evaluatorsRaw.map((e) => buildEvaluator(e));
+    const contextSnapshot = {
+        files: stringArrayField(snapshotRaw, 'files'),
+        memory: stringArrayField(snapshotRaw, 'memory')
+    };
+    const budget = {
+        ...(budgetRaw['tokens'] !== undefined ? { tokens: numberField(budgetRaw, 'tokens') } : {}),
+        ...(budgetRaw['wallSeconds'] !== undefined
+            ? { wallSeconds: numberField(budgetRaw, 'wallSeconds') }
+            : {}),
+        ...(budgetRaw['cycles'] !== undefined ? { cycles: numberField(budgetRaw, 'cycles') } : {})
+    };
+    return {
+        schemaVersion: 1,
+        id,
+        label: stringField(root, 'label', id),
+        description: stringField(root, 'description', ''),
+        phases,
+        gates,
+        evaluators,
+        contextSnapshot,
+        budget
+    };
+}
+function buildPhase(raw) {
+    const obj = objectField({ phase: raw }, 'phase');
+    const id = stringField(obj, 'id');
+    if (!ID_PATTERN.test(id)) {
+        throw new Error(`workflow phase id "${id}" must match ${ID_PATTERN.source}`);
+    }
+    const role = stringField(obj, 'role');
+    if (!role.startsWith('peaks-')) {
+        throw new Error(`workflow phase "${id}" role "${role}" must start with "peaks-"`);
+    }
+    const gatesRaw = obj['gates'];
+    const gates = Array.isArray(gatesRaw) ? gatesRaw.map((g) => String(g)) : [];
+    const outputRaw = obj['outputContract'];
+    const outputContract = Array.isArray(outputRaw) ? outputRaw.map((g) => String(g)) : [];
+    const dependsOnRaw = obj['dependsOn'];
+    const dependsOn = Array.isArray(dependsOnRaw) ? dependsOnRaw.map((g) => String(g)) : undefined;
+    const parallelGroup = typeof obj['parallelGroup'] === 'string' ? obj['parallelGroup'] : undefined;
+    return {
+        id,
+        role,
+        promptTemplate: stringField(obj, 'promptTemplate'),
+        gates,
+        outputContract,
+        ...(dependsOn !== undefined ? { dependsOn } : {}),
+        ...(parallelGroup !== undefined ? { parallelGroup } : {})
+    };
+}
+function buildGate(raw) {
+    const obj = objectField({ gate: raw }, 'gate');
+    const id = stringField(obj, 'id');
+    const sopId = stringField(obj, 'sopId');
+    const description = typeof obj['description'] === 'string' ? obj['description'] : undefined;
+    return {
+        id,
+        sopId,
+        ...(description !== undefined ? { description } : {})
+    };
+}
+function buildEvaluator(raw) {
+    const obj = objectField({ evaluator: raw }, 'evaluator');
+    const typeRaw = stringField(obj, 'type');
+    if (!VALID_EVALUATORS.has(typeRaw)) {
+        throw new Error(`workflow evaluator type "${typeRaw}" is not a native evaluator (allowed: ${[...VALID_EVALUATORS].join(', ')})`);
+    }
+    const type = typeRaw;
+    const gate = typeof obj['gate'] === 'string' ? obj['gate'] : undefined;
+    const scope = typeof obj['scope'] === 'string' ? obj['scope'] : undefined;
+    const threshold = typeof obj['threshold'] === 'string' ? obj['threshold'] : undefined;
+    return {
+        type,
+        ...(gate !== undefined ? { gate } : {}),
+        ...(scope !== undefined ? { scope } : {}),
+        ...(threshold !== undefined ? { threshold } : {})
+    };
+}
+export { buildSpec };

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

@@ -19,14 +19,15 @@
  * pair. Anything more elaborate (e.g. conditionals on outputs) belongs
  * in a future minor.
  *
- * File budget: ≤ 400 lines (rid-006 split). This file now holds the
- * parser + private constants + private build helpers; types live in
+ * File budget: 300 raw lines (the cap decided by
+ * `src/services/scan/file-size-policy.ts`). This file holds the parser;
+ * the private constants and build helpers live in
+ * `workflow-spec-builders.ts` (wave-5 hoist); types live in
  * `workflow-spec-types.ts`; YAML field helpers live in
  * `workflow-spec-yaml.ts`; lint lives in `workflow-spec-lint.ts`.
- * The re-export shim at the bottom preserves the original public
- * surface so external callers (`workflow-loader.ts`,
- * `loop-eval-commands.ts`, `evaluator-dispatcher.ts`) compile
- * unchanged.
+ * The re-export shim at the bottom preserves the original public surface
+ * so external callers (`workflow-loader.ts`, `loop-eval-commands.ts`,
+ * `evaluator-dispatcher.ts`) compile unchanged.
  */
 import type { WorkflowSpec } from './workflow-spec-types.js';
 /** Parse a raw yaml string into a workflow spec. Pure (no IO), throws on