@oisincoveney/pipeline 2.2.0 → 2.3.0

package/dist/{schedule/planner.js → planning/generate.js}

@@ -3,20 +3,22 @@ import { validatePipelineConfig } from "../config/validate.js";
 import "../config.js";
 import { createRunnerLaunchPlan, runLaunchPlan } from "../runner.js";
 import { normalizeRunnerOutput } from "../runner-output.js";
-import { compileWorkflowPlan } from "../workflow-planner.js";
-import { loadBacklogPlanningContext } from "./backlog-context.js";
-import { baselineScheduleArtifact } from "./baseline.js";
-import { addGeneratedImplementationCoverage } from "./passes/coverage.js";
-import { canonicalizeGeneratedScheduleIds } from "./passes/ids.js";
-import { SCHEDULE_PASS_ORDER } from "./passes/index.js";
-import { applyNodeCatalogModelFallbacks } from "./passes/models.js";
-import { namespaceScheduleWorkflows } from "./passes/references.js";
-import { plannerPrompt, plannerRepairPrompt } from "./prompts.js";
+import { loadBacklogPlanningContext } from "../schedule/backlog-context.js";
+import { baselineScheduleArtifact } from "../schedule/baseline.js";
+import { dependentsByNeed, flattenNodes, hasReachableDependent } from "./graph.js";
+import { isCoverageNode, isImplementationNode } from "../schedule/scheduling-roles.js";
+import { addGeneratedImplementationCoverage } from "../schedule/passes/coverage.js";
+import { canonicalizeGeneratedScheduleIds } from "../schedule/passes/ids.js";
+import { SCHEDULE_PASS_ORDER } from "../schedule/passes/index.js";
+import { applyNodeCatalogModelFallbacks } from "../schedule/passes/models.js";
+import { namespaceScheduleWorkflows } from "../schedule/passes/references.js";
+import { plannerPrompt, plannerRepairPrompt } from "../schedule/prompts.js";
+import { compileWorkflowPlan } from "./compile.js";
 import { parseDocument, stringify } from "yaml";
 import { z } from "zod";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-//#region src/schedule/planner.ts
+//#region src/planning/generate.ts
 const SCHEDULE_KIND = "pipeline-schedule";
 const ID_RE = /^[a-z][a-z0-9-]*$/;
 const SCHEDULE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
@@ -253,9 +255,9 @@ function unsafeParallelWorktreeIssues(config, artifact) {
 }
 function workflowNodeIssues(artifact, collectIssues) {
 	return Object.entries(artifact.workflows).flatMap(([workflowId, workflow]) => {
-		const nodes = workflow.nodes.flatMap(flattenWorkflowNode);
+		const nodes = flattenWorkflowNodes(workflow.nodes);
 		return collectIssues({
-			dependentsByNeed: workflowDependentsByNeed(nodes),
+			dependentsByNeed: dependentsByNeed(nodes),
 			nodes,
 			workflowId
 		});
@@ -267,20 +269,8 @@ function isWriteCapableParallelChild(config, node) {
 	if (node.kind === "parallel") return node.nodes.some((child) => isWriteCapableParallelChild(config, child));
 	return false;
 }
-function hasDownstreamDrainMerge(nodeId, dependentsByNeed) {
-	return hasReachableDependent(nodeId, dependentsByNeed, (node) => node.kind === "builtin" && node.builtin === "drain-merge");
-}
-function hasReachableDependent(nodeId, dependentsByNeed, matches) {
-	const queue = [...dependentsByNeed.get(nodeId) ?? []];
-	const seen = /* @__PURE__ */ new Set();
-	while (queue.length > 0) {
-		const node = queue.shift();
-		if (!node || seen.has(node.id)) continue;
-		seen.add(node.id);
-		if (matches(node)) return true;
-		queue.push(...dependentsByNeed.get(node.id) ?? []);
-	}
-	return false;
+function hasDownstreamDrainMerge(nodeId, index) {
+	return hasReachableDependent(nodeId, index, (node) => node.kind === "builtin" && node.builtin === "drain-merge");
 }
 function generatedRootWorkflowIssues(artifact) {
 	const workflowIds = Object.keys(artifact.workflows);
@@ -331,15 +321,15 @@ function workUnitDependencyIssues(config, artifact, workUnits) {
 	const workUnitIds = new Set(workUnits.map((unit) => unit.id));
 	const dependenciesByUnit = new Map(workUnits.map((unit) => [unit.id, (unit.dependencies ?? []).filter((id) => workUnitIds.has(id))]));
 	return Object.entries(artifact.workflows).flatMap(([workflowId, workflow]) => {
-		const nodes = workflow.nodes.flatMap(flattenWorkflowNode);
-		const dependentsByNeed = workflowDependentsByNeed(nodes);
+		const nodes = flattenWorkflowNodes(workflow.nodes);
+		const index = dependentsByNeed(nodes);
 		const nodesByWorkUnit = nodesByAssignedWorkUnit(nodes);
 		return nodes.filter((node) => isImplementationNode(config, node)).flatMap((node) => {
 			const dependentId = node.task_context?.id;
 			if (!dependentId) return [];
 			return (dependenciesByUnit.get(dependentId) ?? []).flatMap((prerequisiteId) => {
 				const prerequisiteNodes = nodesByWorkUnit.get(prerequisiteId) ?? [];
-				return prerequisiteNodes.some((source) => hasPathToNode(source.id, node.id, dependentsByNeed)) ? [] : [`work unit dependency edge missing in '${workflowId}': '${dependentId}' node '${node.id}' must depend on prerequisite '${prerequisiteId}' nodes ${prerequisiteNodes.map((prerequisite) => `'${prerequisite.id}'`).join(", ")}`];
+				return prerequisiteNodes.some((source) => hasReachableDependent(source.id, index, (candidate) => candidate.id === node.id)) ? [] : [`work unit dependency edge missing in '${workflowId}': '${dependentId}' node '${node.id}' must depend on prerequisite '${prerequisiteId}' nodes ${prerequisiteNodes.map((prerequisite) => `'${prerequisite.id}'`).join(", ")}`];
 			});
 		});
 	});
@@ -355,9 +345,6 @@ function nodesByAssignedWorkUnit(nodes) {
 	}
 	return grouped;
 }
-function hasPathToNode(sourceId, targetId, dependentsByNeed) {
-	return hasReachableDependent(sourceId, dependentsByNeed, (node) => node.id === targetId);
-}
 function unsupportedGeneratedBuiltinIssues(artifact) {
 	const allowed = new Set(SCHEDULE_BUILTINS);
 	return allWorkflowNodes(artifact.workflows).flatMap((node) => {
@@ -369,33 +356,14 @@ function unsupportedGeneratedBuiltinIssues(artifact) {
 function implementationCoverageIssues(config, artifact) {
 	return workflowNodeIssues(artifact, ({ dependentsByNeed, nodes, workflowId }) => nodes.filter((node) => isImplementationNode(config, node)).filter((node) => !hasDownstreamCoverage(config, node.id, dependentsByNeed)).map((node) => `implementation node '${workflowId}.${node.id}' is without downstream verification or review`));
 }
-function isImplementationNode(config, node) {
-	return hasSchedulingRole(config, node, "implementation");
-}
-function workflowDependentsByNeed(nodes) {
-	const dependentsByNeed = /* @__PURE__ */ new Map();
-	for (const node of nodes) for (const need of node.needs ?? []) {
-		const dependents = dependentsByNeed.get(need) ?? [];
-		dependents.push(node);
-		dependentsByNeed.set(need, dependents);
-	}
-	return dependentsByNeed;
-}
-function hasDownstreamCoverage(config, nodeId, dependentsByNeed) {
-	return hasReachableDependent(nodeId, dependentsByNeed, (node) => isCoverageNode(config, node));
-}
-function isCoverageNode(config, node) {
-	return hasSchedulingRole(config, node, "coverage");
-}
-function hasSchedulingRole(config, node, role) {
-	if (node.kind !== "agent") return false;
-	return config.profiles[node.profile]?.scheduling_roles?.includes(role) ?? false;
+function hasDownstreamCoverage(config, nodeId, index) {
+	return hasReachableDependent(nodeId, index, (node) => isCoverageNode(config, node));
 }
 function allWorkflowNodes(workflows) {
-	return Object.values(workflows).flatMap((workflow) => workflow.nodes.flatMap(flattenWorkflowNode));
+	return Object.values(workflows).flatMap((workflow) => flattenWorkflowNodes(workflow.nodes));
 }
-function flattenWorkflowNode(node) {
-	return node.kind === "parallel" ? [node, ...node.nodes.flatMap(flattenWorkflowNode)] : [node];
+function flattenWorkflowNodes(nodes) {
+	return flattenNodes(nodes, (node) => node.kind === "parallel" ? node.nodes : void 0);
 }
 //#endregion
 export { ScheduleArtifactError, compileScheduleArtifact, generateScheduleArtifact, parseScheduleArtifact, scheduleArtifactPath };

package/dist/planning/graph.js

@@ -0,0 +1,138 @@
+//#region src/planning/graph.ts
+/**
+* Depth-first flatten of a node tree into a flat list (parents before
+* children), using the caller-supplied accessor to descend into nested
+* containers (e.g. parallel children). Nodes without children are returned
+* as-is.
+*/
+function flattenNodes(nodes, childrenOf) {
+	return nodes.flatMap((node) => {
+		const children = childrenOf(node);
+		return children && children.length > 0 ? [node, ...flattenNodes(children, childrenOf)] : [node];
+	});
+}
+/**
+* Build an index mapping each `need` id to the (flat) nodes that declare it as a
+* dependency. The input is expected to already be flattened by the caller so
+* that the resulting index spans the whole graph.
+*/
+function dependentsByNeed(nodes) {
+	const index = /* @__PURE__ */ new Map();
+	for (const node of nodes) for (const need of node.needs ?? []) {
+		const dependents = index.get(need) ?? [];
+		dependents.push(node);
+		index.set(need, dependents);
+	}
+	return index;
+}
+/**
+* Breadth-first search over the dependents index to determine whether any node
+* transitively reachable downstream of `nodeId` satisfies `matches`. Cycle-safe
+* via a visited set.
+*/
+function hasReachableDependent(nodeId, index, matches) {
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [...index.get(nodeId) ?? []];
+	while (queue.length > 0) {
+		const node = queue.shift();
+		if (!node || visited.has(node.id)) continue;
+		visited.add(node.id);
+		if (matches(node)) return true;
+		queue.push(...index.get(node.id) ?? []);
+	}
+	return false;
+}
+/**
+* Recursively find a node by id within a node tree, descending into children
+* via the caller-supplied accessor. Returns `undefined` when absent.
+*/
+function findNode(nodes, nodeId, childrenOf) {
+	for (const node of nodes) {
+		if (node.id === nodeId) return node;
+		const child = findNode(childrenOf(node) ?? [], nodeId, childrenOf);
+		if (child) return child;
+	}
+}
+/**
+* Find all dependency cycles in a flat node list using an iterative DFS over the
+* dependents-by-need graph. Each cycle is returned once (canonicalized by its
+* member set) as the ordered list of node ids forming the loop. Only `needs`
+* that reference declared nodes participate, so callers can pass the full flat
+* node set without pre-filtering missing dependencies.
+*
+* The traversal is iterative (an explicit frame stack) rather than recursive so
+* that deep generated workflow chains cannot overflow the call stack.
+*/
+function findDependencyCycles(nodes) {
+	const nodeIds = new Set(nodes.map((node) => node.id));
+	const index = dependentsByNeed(nodes);
+	const adjacency = /* @__PURE__ */ new Map();
+	for (const node of nodes) adjacency.set(node.id, (index.get(node.id) ?? []).map((dependent) => dependent.id).filter((id) => nodeIds.has(id)));
+	const state = /* @__PURE__ */ new Map();
+	const path = [];
+	const pathIndex = /* @__PURE__ */ new Map();
+	const cycles = [];
+	const cycleKeys = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		if (state.has(node.id)) continue;
+		visitForCycles(node.id, {
+			adjacency,
+			cycleKeys,
+			cycles,
+			path,
+			pathIndex,
+			state
+		});
+	}
+	return cycles;
+}
+function visitForCycles(startId, visitState) {
+	const frames = [{
+		index: 0,
+		nodeId: startId
+	}];
+	markVisiting(startId, visitState);
+	while (frames.length > 0) {
+		const frame = frames.at(-1);
+		if (!frame) return;
+		const dependentId = (visitState.adjacency.get(frame.nodeId) ?? [])[frame.index];
+		if (!dependentId) {
+			markDone(frame.nodeId, visitState);
+			frames.pop();
+			continue;
+		}
+		frame.index += 1;
+		const dependentState = visitState.state.get(dependentId);
+		if (dependentState === "visiting") {
+			recordCycle(dependentId, visitState);
+			continue;
+		}
+		if (dependentState === "done") continue;
+		markVisiting(dependentId, visitState);
+		frames.push({
+			index: 0,
+			nodeId: dependentId
+		});
+	}
+}
+function markVisiting(nodeId, visitState) {
+	visitState.state.set(nodeId, "visiting");
+	visitState.pathIndex.set(nodeId, visitState.path.length);
+	visitState.path.push(nodeId);
+}
+function markDone(nodeId, visitState) {
+	visitState.state.set(nodeId, "done");
+	visitState.pathIndex.delete(nodeId);
+	visitState.path.pop();
+}
+function recordCycle(nodeId, visitState) {
+	const startIndex = visitState.pathIndex.get(nodeId);
+	if (startIndex === void 0) return;
+	const cycle = visitState.path.slice(startIndex);
+	const key = [...cycle].sort().join("\0");
+	if (visitState.cycleKeys.has(key)) return;
+	visitState.cycleKeys.add(key);
+	visitState.cycles.push(cycle);
+}
+//#endregion
+export { dependentsByNeed, findDependencyCycles, findNode, flattenNodes, hasReachableDependent };

package/dist/runner-command/lifecycle-context.js

@@ -1,9 +1,8 @@
-import { parseRunnerCommandPayload, resolveRunnerEventSinkAuthToken } from "../runner-command-contract.js";
 import { PIPELINE_CONFIG_PATH, PROFILES_CONFIG_PATH, RUNNERS_CONFIG_PATH } from "../config/defaults.js";
 import { loadPipelineConfig, parsePipelineConfigParts } from "../config/load.js";
 import "../config.js";
-import { compileScheduleArtifact, parseScheduleArtifact } from "../schedule/planner.js";
-import "../schedule-planner.js";
+import { compileScheduleArtifact, parseScheduleArtifact } from "../planning/generate.js";
+import { parseRunnerCommandPayload, resolveRunnerEventSinkAuthToken } from "../runner-command-contract.js";
 import { prepareRunnerGitWorkspace } from "../run-state/git-refs.js";
 import { createRunnerEventSink } from "../runner-event-sink.js";
 import { initialNodeStateStore } from "../runtime/node-state-store.js";

package/dist/runner-command/run.js

@@ -1,9 +1,8 @@
 import { readRunnerTaskDescriptor } from "./task-descriptor.js";
-import { RunnerCommandPayloadValidationError, parseRunnerCommandPayload, resolveRunnerEventSinkAuthToken } from "../runner-command-contract.js";
 import { loadPipelineConfig } from "../config/load.js";
 import "../config.js";
-import { compileScheduleArtifact, parseScheduleArtifact } from "../schedule/planner.js";
-import "../schedule-planner.js";
+import { compileScheduleArtifact, parseScheduleArtifact } from "../planning/generate.js";
+import { RunnerCommandPayloadValidationError, parseRunnerCommandPayload, resolveRunnerEventSinkAuthToken } from "../runner-command-contract.js";
 import { commitAndPushNodeRef, mergeDependencyRefs, prepareRunnerGitWorkspace } from "../run-state/git-refs.js";
 import { createRunnerEventSink } from "../runner-event-sink.js";
 import { findPlannedNode } from "../planned-node.js";

package/dist/runner.d.ts

@@ -2,6 +2,18 @@ import { PipelineConfig, RunnerType } from "./config/schemas.js";
 //#region src/runner.d.ts
 type Harness = "opencode";
 type AgentRole = "researcher" | "test-writer" | "code-writer" | "verifier";
+/**
+ * Agent-output boundary, layer 1 of 4 (PIPE-74 B3). `AgentResult` is the RAW
+ * terminal result of one runner subprocess/session: exit code, accumulated
+ * stdout/stderr, and execution metadata. It carries no parsing or semantic
+ * interpretation — downstream layers refine it:
+ *   1. {@link AgentResult}            — raw subprocess result (this type)
+ *   2. {@link RunnerOutputEvent}      — a live stream chunk during execution
+ *   3. RuntimeNormalizedOutput        — adapter-extracted text + evidence
+ *      (src/runtime/opencode-adapter.ts)
+ *   4. RuntimeStructuredOutput        — parsed + schema-validated output
+ *      (src/runtime/contracts/contracts.ts)
+ */
 interface AgentResult {
   argv?: string[];
   exitCode: number;
@@ -11,11 +23,26 @@ interface AgentResult {
   stdout: string;
   timedOut?: boolean;
 }
+/**
+ * Agent-output boundary, layer 2 of 4 (PIPE-74 B3). A single incremental chunk
+ * of a runner's live output stream, surfaced via
+ * {@link RunnerExecutionOptions.onOutput} while the subprocess is still
+ * running — distinct from {@link AgentResult}, which is the final accumulated
+ * result.
+ */
 interface RunnerOutputEvent {
   chunk: string;
   nodeId: string;
   stream: "stderr" | "stdout";
 }
+/**
+ * Lowest layer of the runtime-options stack (PIPE-74 B3): the per-invocation
+ * controls a runner executor needs — cancellation and live-output streaming.
+ * Widened by the runtime layers above it:
+ *   RunnerExecutionOptions (this type)
+ *     < PipelineRuntimeOptions (src/runtime/contracts/contracts.ts)
+ *     < ScheduledWorkflowTaskRuntimeOptions (src/pipeline-runtime.ts)
+ */
 interface RunnerExecutionOptions {
   onOutput?: (event: RunnerOutputEvent) => void;
   signal?: AbortSignal;

package/dist/runtime/context/context.js

@@ -1,7 +1,7 @@
 import { loadPipelineConfig } from "../../config/load.js";
 import "../../config.js";
 import { runLaunchPlan } from "../../runner.js";
-import { compileWorkflowPlan } from "../../workflow-planner.js";
+import { compileWorkflowPlan } from "../../planning/compile.js";
 import { createPublicRuntimeObservabilityEmitter } from "../events/events.js";
 import "../events/index.js";
 import { initialNodeStateStore } from "../node-state-store.js";

package/dist/runtime/contracts/contracts.d.ts

@@ -1,5 +1,5 @@
 import { HookEvent, PipelineConfig } from "../../config/schemas.js";
-import { PlannedWorkflowNode, WorkflowExecutionPlan } from "../../workflow-planner.js";
+import { PlannedWorkflowNode, WorkflowExecutionPlan } from "../../planning/compile.js";
 import { HookResult } from "../../hooks.js";
 import { AgentResult, RunnerExecutionOptions, RunnerLaunchPlan } from "../../runner.js";
 import { RuntimeActorDescriptor, RuntimeObservabilityEvent } from "../actor-ids.js";
@@ -44,6 +44,13 @@ interface RuntimeNodeResult {
   output: string;
   status: "failed" | "passed";
 }
+/**
+ * Agent-output boundary, layer 4 of 4 (PIPE-74 B3). The terminal, structured
+ * form of agent output: the layer-3 RuntimeNormalizedOutput text
+ * (src/runtime/opencode-adapter.ts) parsed into a typed `output` value and
+ * validated against the node's declared schema. This is what downstream nodes
+ * and gates consume.
+ */
 interface RuntimeStructuredOutput {
   attempt: number;
   format: "json" | "json_schema" | "jsonl";
@@ -228,6 +235,14 @@ type PipelineRuntimeEvent = {
   type: "workflow.finish";
   workflowId: string;
 });
+/**
+ * Middle layer of the runtime-options stack (PIPE-74 B3): everything needed to
+ * run one pipeline workflow from config — the config/entrypoint to run, the
+ * task, reporting, and the executor (whose per-call controls come from the
+ * layer below, {@link RunnerExecutionOptions} in src/runner.ts). Extended by
+ * ScheduledWorkflowTaskRuntimeOptions (src/pipeline-runtime.ts) for the
+ * single-node, schedule-driven execution path.
+ */
 interface PipelineRuntimeOptions {
   config?: PipelineConfig;
   entrypoint?: string;

package/dist/schedule/passes/coverage.js

@@ -1,12 +1,12 @@
+import { uniqueGeneratedId } from "../../strings.js";
+import { dependentsByNeed, hasReachableDependent } from "../../planning/graph.js";
+import { isCoverageNode, isImplementationNode } from "../scheduling-roles.js";
 //#region src/schedule/passes/coverage.ts
 const DEFAULT_GENERATED_COVERAGE_PROFILE_PREFERENCE = [
 	"moka-verifier",
 	"moka-acceptance-reviewer",
 	"moka-thermo-nuclear-reviewer"
 ];
-const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
-const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
-const STARTS_WITH_ALPHA_RE = /^[a-z]/;
 function addGeneratedImplementationCoverage(config, artifact) {
 	const coverageProfileId = generatedCoverageProfileId(config);
 	if (!coverageProfileId) return artifact;
@@ -26,8 +26,8 @@ function addNodeScopeImplementationCoverage(config, nodes, coverageProfileId) {
 		...node,
 		nodes: addNodeScopeImplementationCoverage(config, node.nodes, coverageProfileId)
 	} : node);
-	const dependentsByNeed = workflowDependentsByNeed(scopedNodes);
-	const uncovered = scopedNodes.filter((node) => isImplementationNode(config, node)).filter((node) => !hasDownstreamCoverage(config, node.id, dependentsByNeed));
+	const index = dependentsByNeed(scopedNodes);
+	const uncovered = scopedNodes.filter((node) => isImplementationNode(config, node)).filter((node) => !hasDownstreamCoverage(config, node.id, index));
 	if (uncovered.length === 0) return scopedNodes;
 	const coverageNodeId = uniqueGeneratedId("generated-coverage", new Set(scopedNodes.map((node) => node.id)), "generated-coverage");
 	return [...scopedNodes, {
@@ -82,52 +82,8 @@ function generatedCoverageGates(nodeId) {
 		}
 	];
 }
-function workflowDependentsByNeed(nodes) {
-	const dependentsByNeed = /* @__PURE__ */ new Map();
-	for (const node of nodes) for (const need of node.needs ?? []) {
-		const dependents = dependentsByNeed.get(need) ?? [];
-		dependents.push(node);
-		dependentsByNeed.set(need, dependents);
-	}
-	return dependentsByNeed;
-}
-function isImplementationNode(config, node) {
-	return hasSchedulingRole(config, node, "implementation");
-}
-function hasDownstreamCoverage(config, nodeId, dependentsByNeed) {
-	return hasReachableDependent(nodeId, dependentsByNeed, (node) => hasSchedulingRole(config, node, "coverage"));
-}
-function hasSchedulingRole(config, node, role) {
-	if (node.kind !== "agent") return false;
-	return config.profiles[node.profile]?.scheduling_roles?.includes(role) ?? false;
-}
-function hasReachableDependent(nodeId, dependentsByNeed, matches) {
-	const visited = /* @__PURE__ */ new Set();
-	const queue = [...dependentsByNeed.get(nodeId) ?? []];
-	while (queue.length > 0) {
-		const node = queue.shift();
-		if (!node || visited.has(node.id)) continue;
-		visited.add(node.id);
-		if (matches(node)) return true;
-		queue.push(...dependentsByNeed.get(node.id) ?? []);
-	}
-	return false;
-}
-function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
-	const base = generatedId(value, fallbackPrefix);
-	let candidate = base;
-	let suffix = 2;
-	while (usedIds.has(candidate)) {
-		candidate = `${base}-${suffix}`;
-		suffix += 1;
-	}
-	usedIds.add(candidate);
-	return candidate;
-}
-function generatedId(value, fallbackPrefix) {
-	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
-	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
-	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
+function hasDownstreamCoverage(config, nodeId, index) {
+	return hasReachableDependent(nodeId, index, (node) => isCoverageNode(config, node));
 }
 //#endregion
 export { addGeneratedImplementationCoverage };

package/dist/schedule/passes/ids.js

@@ -1,7 +1,6 @@
+import { uniqueGeneratedId } from "../../strings.js";
+import { flattenNodes } from "../../planning/graph.js";
 //#region src/schedule/passes/ids.ts
-const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
-const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
-const STARTS_WITH_ALPHA_RE = /^[a-z]/;
 function canonicalizeGeneratedScheduleIds(artifact) {
 	return {
 		...artifact,
@@ -11,7 +10,7 @@ function canonicalizeGeneratedScheduleIds(artifact) {
 function canonicalizeWorkflowNodeIds(workflow) {
 	const nodeIdMap = /* @__PURE__ */ new Map();
 	const usedNodeIds = /* @__PURE__ */ new Set();
-	for (const node of workflow.nodes.flatMap(flattenWorkflowNode)) nodeIdMap.set(node.id, uniqueGeneratedId(node.id, usedNodeIds, "node"));
+	for (const node of flattenNodes(workflow.nodes, (node) => node.kind === "parallel" ? node.nodes : void 0)) nodeIdMap.set(node.id, uniqueGeneratedId(node.id, usedNodeIds, "node"));
 	return {
 		...workflow,
 		nodes: workflow.nodes.map((node) => rewriteGeneratedWorkflowNodeIds(node, nodeIdMap))
@@ -28,24 +27,5 @@ function rewriteGeneratedWorkflowNodeIds(node, nodeIdMap) {
 		nodes: rewritten.nodes.map((child) => rewriteGeneratedWorkflowNodeIds(child, nodeIdMap))
 	} : rewritten;
 }
-function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
-	const base = generatedId(value, fallbackPrefix);
-	let candidate = base;
-	let suffix = 2;
-	while (usedIds.has(candidate)) {
-		candidate = `${base}-${suffix}`;
-		suffix += 1;
-	}
-	usedIds.add(candidate);
-	return candidate;
-}
-function generatedId(value, fallbackPrefix) {
-	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
-	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
-	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
-}
-function flattenWorkflowNode(node) {
-	return node.kind === "parallel" ? [node, ...node.nodes.flatMap(flattenWorkflowNode)] : [node];
-}
 //#endregion
 export { canonicalizeGeneratedScheduleIds };

package/dist/schedule/scheduling-roles.js

@@ -0,0 +1,19 @@
+//#region src/schedule/scheduling-roles.ts
+/**
+* Whether an agent node's profile declares the given scheduling role. Non-agent
+* nodes never carry scheduling roles. This is the single source of truth for the
+* implementation/coverage role policy used by schedule generation and
+* validation.
+*/
+function hasSchedulingRole(config, node, role) {
+	if (node.kind !== "agent") return false;
+	return config.profiles[node.profile]?.scheduling_roles?.includes(role) ?? false;
+}
+function isImplementationNode(config, node) {
+	return hasSchedulingRole(config, node, "implementation");
+}
+function isCoverageNode(config, node) {
+	return hasSchedulingRole(config, node, "coverage");
+}
+//#endregion
+export { isCoverageNode, isImplementationNode };

package/dist/strings.js

@@ -4,5 +4,34 @@ function uniqueStrings(values, options = {}) {
 	const unique = [...new Set(input)];
 	return options.sort ? unique.sort() : unique;
 }
+const GENERATED_ID_INVALID_CHARS_RE = /[^a-z0-9]+/g;
+const GENERATED_ID_TRIM_HYPHENS_RE = /^-+|-+$/g;
+const STARTS_WITH_ALPHA_RE = /^[a-z]/;
+/**
+* Slugify an arbitrary string into a workflow-safe id (lowercase, hyphenated).
+* When the slug does not begin with a letter it is prefixed with
+* `fallbackPrefix` so the result is always a valid node/workflow id.
+*/
+function generatedId(value, fallbackPrefix) {
+	const slug = value.trim().toLowerCase().replaceAll(GENERATED_ID_INVALID_CHARS_RE, "-").replaceAll(GENERATED_ID_TRIM_HYPHENS_RE, "");
+	if (STARTS_WITH_ALPHA_RE.test(slug)) return slug;
+	return slug ? `${fallbackPrefix}-${slug}` : fallbackPrefix;
+}
+/**
+* Slugify `value` to a generated id (see {@link generatedId}) and disambiguate
+* against `usedIds` by appending an incrementing numeric suffix. Mutates
+* `usedIds` to reserve the chosen id.
+*/
+function uniqueGeneratedId(value, usedIds, fallbackPrefix) {
+	const base = generatedId(value, fallbackPrefix);
+	let candidate = base;
+	let suffix = 2;
+	while (usedIds.has(candidate)) {
+		candidate = `${base}-${suffix}`;
+		suffix += 1;
+	}
+	usedIds.add(candidate);
+	return candidate;
+}
 //#endregion
-export { uniqueStrings };
+export { uniqueGeneratedId, uniqueStrings };

package/docs/config-architecture.md

@@ -320,6 +320,38 @@ the execution surface while Claude Code orchestrates. Unsupported runner or host
 mappings fail closed instead of doing instruction-only translation or generic
 worker substitution.
 
+## Planning: Compile And Generate
+
+Two distinct planning strategies turn config into an executable plan, and the
+module layout names the distinction (`src/planning/`):
+
+- `planning/compile.ts` — **deterministic DAG compilation**. `compileWorkflowPlan`
+  validates a workflow's nodes (duplicate ids, missing dependencies, group
+  references, cycles), normalizes group dependencies, and produces the
+  `WorkflowExecutionPlan` (graph, topological order, parallel batches). This is
+  the engine's mandatory front door: every execution path runs through it,
+  including AI-generated schedules. Exposed as the `./planner` package subpath.
+- `planning/generate.ts` — **optional AI decomposition**. `generateScheduleArtifact`
+  drives a planner profile to decompose a task into a schedule artifact, then
+  normalizes it through auditable passes (coverage → models → ids → references)
+  and finally feeds it back into `compileScheduleArtifact`, which merges the
+  generated workflows into config and calls `compileWorkflowPlan`. So generate
+  output is always an input to compile — never a substitute for it. Exposed as
+  the `./schedule` package subpath.
+
+Both layers share one policy-free traversal model, `planning/graph.ts`
+(`flattenNodes`, `dependentsByNeed`, `hasReachableDependent`, `findNode`,
+`findDependencyCycles`). Each caller supplies its own predicates and owns its
+error vocabulary, so config validation, deterministic compile, and AI-schedule
+validation reason over the same graph structure without sharing layer-specific
+policy. Schedule-specific support (artifact re-export barrel, baseline, prompts,
+the normalization passes, backlog context, scheduling-role policy) stays under
+`src/schedule/` and imports the artifact + generate API from `planning/generate`.
+
+The toposort uses `@dagrejs/graphlib` for the graph model but an iterative
+traversal for the topological sort, because graphlib's recursive topsort can
+overflow the call stack on deep generated workflow chains.
+
 ## Troubleshooting
 
 - Missing host resources: run `moka install-commands`; `moka run` loads the

package/docs/operator-guide.md

@@ -100,8 +100,8 @@ moka doctor --cluster momokaya-pipeline --kube-context momokaya
 `moka doctor --cluster` adds value-free runner-job preflight checks for the
 selected namespace, defaulting to `momokaya-pipeline`. It checks that expected
 Secret objects exist by name, ExternalSecrets and `ClusterSecretStore/openbao`
-report Ready status, the runner ServiceAccount has workflow RBAC, the Kueue
-LocalQueue is present, and Argo Workflow prerequisites are reachable. It does
+report Ready status, the runner ServiceAccount has workflow RBAC, and Argo
+Workflow prerequisites are reachable. It does
 not read, print, decode, diff, or validate Secret values.
 
 OpenBao and External Secrets Operator remain infrastructure-owned
@@ -160,7 +160,6 @@ momokaya:
     githubAuthSecretName: <github-auth-secret-name>
     imagePullSecretName: <image-pull-secret-name>
     opencodeAuthSecretName: <opencode-auth-secret-name>
-    queueName: <local-queue-name>
     serviceAccountName: <runner-service-account-name>
 ```
 

package/docs/pipeline-console-runner-contract.md

@@ -82,10 +82,9 @@ keep the console package dependency, console expected version, and runner image
 label version aligned. A future breaking payload change must increment the
 contract version and ship a compatibility plan.
 
-Console-created Jobs are labeled with `kueue.x-k8s.io/queue-name` and
-`pipeline.oisin.dev/project`, `pipeline.oisin.dev/run-id`,
-`pipeline.oisin.dev/source`, `pipeline.oisin.dev/task`, plus optional
-`pipeline.oisin.dev/requested-by`.
+Console-created Jobs are labeled with `pipeline.oisin.dev/project`,
+`pipeline.oisin.dev/run-id`, `pipeline.oisin.dev/source`,
+`pipeline.oisin.dev/task`, plus optional `pipeline.oisin.dev/requested-by`.
 
 ## Event Batches