taskplane 0.22.8 → 0.22.9

package/extensions/taskplane/discovery.ts

@@ -6,7 +6,7 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "
 import { join, dirname, basename, resolve } from "path";
 
 import { FATAL_DISCOVERY_CODES } from "./types.ts";
-import type { DiscoveryError, DiscoveryResult, ParsedTask, TaskArea, WorkspaceConfig } from "./types.ts";
+import type { DiscoveryError, DiscoveryResult, ParsedTask, PromptSegmentDagMetadata, TaskArea, WorkspaceConfig } from "./types.ts";
 
 // ── PROMPT.md Parsing ────────────────────────────────────────────────
 
@@ -56,6 +56,301 @@ export function normalizeDependencyReference(raw: string): string {
 	return parsed.areaName ? `${parsed.areaName}/${parsed.taskId}` : parsed.taskId;
 }
 
+const SEGMENT_REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+function normalizeSegmentRepoToken(raw: string): string {
+	let token = raw.trim();
+	token = token.replace(/^`(.+)`$/, "$1").trim();
+	token = token.replace(/^\*\*(.+)\*\*$/, "$1").trim();
+	return token.toLowerCase();
+}
+
+interface ParsedSegmentDagBody {
+	metadata: PromptSegmentDagMetadata | null;
+	error: DiscoveryError | null;
+}
+
+/**
+ * Parse optional explicit segment DAG metadata from `## Segment DAG`.
+ *
+ * Supported v1 syntax:
+ *
+ * ## Segment DAG
+ * Repos:
+ * - api
+ * - web-client
+ * Edges:
+ * - api -> web-client
+ *
+ * Notes:
+ * - `Repos:` / `Edges:` keys accept markdown decoration (`**Repos:**`) and whitespace.
+ * - Repo IDs are normalized to lowercase and validated against routing repo ID rules.
+ * - Unknown edge endpoints (not present in explicit repo list) fail fast.
+ * - Self-edges and cycles fail fast with `SEGMENT_DAG_INVALID`.
+ */
+function parseSegmentDagMetadata(
+	content: string,
+	taskId: string,
+	promptPath: string,
+): ParsedSegmentDagBody {
+	const headerMatch = content.match(/^##\s+Segment DAG\s*$/im);
+	if (!headerMatch || headerMatch.index === undefined) {
+		return { metadata: null, error: null };
+	}
+
+	const headerIndex = headerMatch.index;
+	const afterHeaderIndex = content.indexOf("\n", headerIndex);
+	if (afterHeaderIndex === -1) {
+		return { metadata: null, error: null };
+	}
+
+	const rest = content.slice(afterHeaderIndex + 1);
+	const nextBoundary = rest.search(/^##\s|^---/m);
+	const body = nextBoundary !== -1 ? rest.slice(0, nextBoundary) : rest;
+
+	const repoIds: string[] = [];
+	const repoSet = new Set<string>();
+	const edgePairs = new Set<string>();
+	const edges: Array<{ fromRepoId: string; toRepoId: string }> = [];
+	const baseLine = content.slice(0, afterHeaderIndex + 1).split(/\r?\n/).length;
+
+	let mode: "repos" | "edges" | null = null;
+	const lines = body.split(/\r?\n/);
+
+	for (let i = 0; i < lines.length; i++) {
+		const rawLine = lines[i];
+		const trimmed = rawLine.trim();
+		if (!trimmed) continue;
+
+		if (/^\*?\*?Repos:?\*?\*?\s*$/i.test(trimmed)) {
+			mode = "repos";
+			continue;
+		}
+		if (/^\*?\*?Edges:?\*?\*?\s*$/i.test(trimmed)) {
+			mode = "edges";
+			continue;
+		}
+
+		if (!mode) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_DAG_INVALID",
+					message:
+						`Task ${taskId} has malformed ## Segment DAG metadata at line ${baseLine + i}: ` +
+						`expected a Repos: or Edges: subsection header before entries.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+
+		const bulletMatch = rawLine.match(/^\s*[-*]\s+(.+)$/);
+		if (!bulletMatch) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_DAG_INVALID",
+					message:
+						`Task ${taskId} has malformed ## Segment DAG metadata at line ${baseLine + i}: ` +
+						`expected a bullet entry ("- ...").`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+
+		const entry = bulletMatch[1].trim();
+		if (!entry) continue;
+
+		if (mode === "repos") {
+			if (entry.includes("->")) {
+				return {
+					metadata: null,
+					error: {
+						code: "SEGMENT_DAG_INVALID",
+						message:
+							`Task ${taskId} has malformed ## Segment DAG metadata at line ${baseLine + i}: ` +
+							`repo list entries must be a single repo ID.`,
+						taskId,
+						taskPath: promptPath,
+					},
+				};
+			}
+			const repoId = normalizeSegmentRepoToken(entry);
+			if (!SEGMENT_REPO_ID_PATTERN.test(repoId)) {
+				return {
+					metadata: null,
+					error: {
+						code: "SEGMENT_DAG_INVALID",
+						message:
+							`Task ${taskId} has invalid repo ID "${entry}" in ## Segment DAG at line ${baseLine + i}. ` +
+							`Repo IDs must match /^[a-z0-9][a-z0-9-]*$/.`,
+						taskId,
+						taskPath: promptPath,
+					},
+				};
+			}
+			if (!repoSet.has(repoId)) {
+				repoSet.add(repoId);
+				repoIds.push(repoId);
+			}
+			continue;
+		}
+
+		const edgeMatch = entry.match(/^(.+?)\s*->\s*(.+)$/);
+		if (!edgeMatch) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_DAG_INVALID",
+					message:
+						`Task ${taskId} has malformed edge "${entry}" in ## Segment DAG at line ${baseLine + i}. ` +
+						`Expected format: <repo-a> -> <repo-b>.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+
+		const fromRepoId = normalizeSegmentRepoToken(edgeMatch[1]);
+		const toRepoId = normalizeSegmentRepoToken(edgeMatch[2]);
+		if (!SEGMENT_REPO_ID_PATTERN.test(fromRepoId) || !SEGMENT_REPO_ID_PATTERN.test(toRepoId)) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_DAG_INVALID",
+					message:
+						`Task ${taskId} has malformed edge "${entry}" in ## Segment DAG at line ${baseLine + i}. ` +
+						`Repo IDs must match /^[a-z0-9][a-z0-9-]*$/.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+		if (fromRepoId === toRepoId) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_DAG_INVALID",
+					message:
+						`Task ${taskId} has self-edge "${fromRepoId} -> ${toRepoId}" in ## Segment DAG at line ${baseLine + i}.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+
+		const edgeKey = `${fromRepoId}->${toRepoId}`;
+		if (!edgePairs.has(edgeKey)) {
+			edgePairs.add(edgeKey);
+			edges.push({ fromRepoId, toRepoId });
+		}
+	}
+
+	if (repoIds.length === 0 && edges.length === 0) {
+		return { metadata: null, error: null };
+	}
+
+	for (const edge of edges) {
+		if (!repoSet.has(edge.fromRepoId)) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_REPO_UNKNOWN",
+					message:
+						`Task ${taskId} has edge endpoint repo "${edge.fromRepoId}" in ## Segment DAG that is not declared in Repos:.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+		if (!repoSet.has(edge.toRepoId)) {
+			return {
+				metadata: null,
+				error: {
+					code: "SEGMENT_REPO_UNKNOWN",
+					message:
+						`Task ${taskId} has edge endpoint repo "${edge.toRepoId}" in ## Segment DAG that is not declared in Repos:.`,
+					taskId,
+					taskPath: promptPath,
+				},
+			};
+		}
+	}
+
+	const sortedEdges = [...edges].sort((a, b) => {
+		if (a.fromRepoId !== b.fromRepoId) return a.fromRepoId.localeCompare(b.fromRepoId);
+		return a.toRepoId.localeCompare(b.toRepoId);
+	});
+
+	const adjacency = new Map<string, string[]>();
+	for (const repoId of repoIds) {
+		adjacency.set(repoId, []);
+	}
+	for (const edge of sortedEdges) {
+		adjacency.get(edge.fromRepoId)!.push(edge.toRepoId);
+	}
+	for (const neighbors of adjacency.values()) {
+		neighbors.sort();
+	}
+
+	const visited = new Set<string>();
+	const stack = new Set<string>();
+	const path: string[] = [];
+	let cycle: string[] | null = null;
+
+	function dfs(repoId: string): void {
+		if (cycle) return;
+		visited.add(repoId);
+		stack.add(repoId);
+		path.push(repoId);
+
+		const neighbors = adjacency.get(repoId) || [];
+		for (const next of neighbors) {
+			if (cycle) return;
+			if (!visited.has(next)) {
+				dfs(next);
+				continue;
+			}
+			if (stack.has(next)) {
+				const start = path.indexOf(next);
+				cycle = [...path.slice(start), next];
+				return;
+			}
+		}
+
+		path.pop();
+		stack.delete(repoId);
+	}
+
+	for (const repoId of [...repoIds].sort()) {
+		if (!visited.has(repoId)) dfs(repoId);
+		if (cycle) break;
+	}
+
+	if (cycle) {
+		return {
+			metadata: null,
+			error: {
+				code: "SEGMENT_DAG_INVALID",
+				message:
+					`Task ${taskId} has cyclic ## Segment DAG metadata: ${cycle.join(" -> ")}.`,
+				taskId,
+				taskPath: promptPath,
+			},
+		};
+	}
+
+	return {
+		metadata: {
+			repoIds,
+			edges: sortedEdges,
+		},
+		error: null,
+	};
+}
+
 /**
  * Parse a PROMPT.md file and extract orchestrator-relevant metadata.
  *
@@ -255,6 +550,16 @@ export function parsePromptForOrchestrator(
 		}
 	}
 
+	// ── Extract optional explicit segment DAG metadata ──────────
+	const segmentDagResult = parseSegmentDagMetadata(content, taskId, resolve(promptPath));
+	if (segmentDagResult.error) {
+		return {
+			task: null,
+			error: segmentDagResult.error,
+		};
+	}
+	const explicitSegmentDag = segmentDagResult.metadata;
+
 	return {
 		task: {
 			taskId,
@@ -268,6 +573,7 @@ export function parsePromptForOrchestrator(
 			areaName,
 			status: "pending",
 			...(promptRepoId ? { promptRepoId } : {}),
+			...(explicitSegmentDag ? { explicitSegmentDag } : {}),
 		},
 		error: null,
 	};
@@ -893,6 +1199,22 @@ export function resolveTaskRouting(
 	const strictMode = workspaceConfig.routing.strict === true;
 
 	for (const task of discovery.pending.values()) {
+		// ── Explicit segment DAG repo validation (workspace IDs) ─
+		if (task.explicitSegmentDag) {
+			const unknownRepos = task.explicitSegmentDag.repoIds.filter((repoId) => !validRepoIds.has(repoId));
+			if (unknownRepos.length > 0) {
+				errors.push({
+					code: "SEGMENT_REPO_UNKNOWN",
+					message:
+						`Task ${task.taskId} declares unknown repo ID(s) in ## Segment DAG: ${unknownRepos.join(", ")}. ` +
+						`Known repos: ${[...validRepoIds.keys()].join(", ")}`,
+					taskId: task.taskId,
+					taskPath: task.promptPath,
+				});
+				continue;
+			}
+		}
+
 		// ── Strict mode enforcement ──────────────────────────────
 		// When strict routing is enabled, every task MUST declare an
 		// explicit execution target in PROMPT.md. Area-level and

package/extensions/taskplane/types.ts

@@ -60,6 +60,26 @@ export interface OrchestratorConfig {
 	};
 }
 
+/** Stable segment identifier: `<taskId>::<repoId>` */
+export type SegmentId = `${string}::${string}`;
+
+/** How an intra-task segment edge was produced (for observability/debugging). */
+export type SegmentEdgeProvenance = "explicit" | "inferred";
+
+/** Repo-scoped edge parsed from optional `## Segment DAG` prompt metadata. */
+export interface PromptSegmentDagEdge {
+	fromRepoId: string;
+	toRepoId: string;
+}
+
+/** Optional explicit segment metadata parsed from PROMPT.md. */
+export interface PromptSegmentDagMetadata {
+	/** Repo IDs participating in this task's segment graph, first-seen order. */
+	repoIds: string[];
+	/** Directed repo-level edges, sorted by `fromRepoId` then `toRepoId`. */
+	edges: PromptSegmentDagEdge[];
+}
+
 /** A parsed task from PROMPT.md, enriched for orchestrator use */
 export interface ParsedTask {
 	taskId: string;
@@ -76,8 +96,61 @@ export interface ParsedTask {
 	promptRepoId?: string;
 	/** Resolved repo ID after routing precedence (workspace mode only). Undefined in repo mode. */
 	resolvedRepoId?: string;
+	/** Optional explicit segment DAG metadata from `## Segment DAG`. */
+	explicitSegmentDag?: PromptSegmentDagMetadata;
+}
+
+/** Build a stable segment ID from task + repo identity (`<taskId>::<repoId>`). */
+export function buildSegmentId(taskId: string, repoId: string): SegmentId {
+	return `${taskId}::${repoId}` as SegmentId;
+}
+
+/** One repo-scoped segment node for a task. */
+export interface TaskSegmentNode {
+	segmentId: SegmentId;
+	taskId: string;
+	repoId: string;
+	/**
+	 * Deterministic segment order within a task (0-indexed).
+	 * Stable tie-break: repoId lexical order.
+	 */
+	order: number;
 }
 
+/** Directed edge between two segment nodes in the same task. */
+export interface TaskSegmentEdge {
+	fromSegmentId: SegmentId;
+	toSegmentId: SegmentId;
+	provenance: SegmentEdgeProvenance;
+	/** Optional explanation of why this edge exists (debug/telemetry aid). */
+	reason?: string;
+}
+
+/**
+ * Deterministic segment plan for one task.
+ *
+ * Ordering contract:
+ * - `segments`: sorted by `order`, then `repoId`
+ * - `edges`: sorted by `fromSegmentId`, then `toSegmentId`
+ */
+export interface TaskSegmentPlan {
+	taskId: string;
+	segments: TaskSegmentNode[];
+	edges: TaskSegmentEdge[];
+	/**
+	 * explicit-dag: parsed from prompt metadata
+	 * inferred-sequential: deterministic fallback inference
+	 * repo-singleton: repo mode fallback (`resolvedRepoId ?? "default"`)
+	 */
+	mode: "explicit-dag" | "inferred-sequential" | "repo-singleton";
+}
+
+/**
+ * TaskId-keyed segment plans.
+ * Iteration order must be deterministic: sort task IDs lexicographically.
+ */
+export type TaskSegmentPlanMap = Map<string, TaskSegmentPlan>;
+
 /** A wave: a group of tasks whose dependencies are all satisfied */
 export interface WaveAssignment {
 	waveNumber: number;
@@ -403,7 +476,9 @@ export interface DiscoveryError {
 		| "DEP_SOURCE_FALLBACK"
 		| "TASK_REPO_UNRESOLVED"
 		| "TASK_REPO_UNKNOWN"
-		| "TASK_ROUTING_STRICT";
+		| "TASK_ROUTING_STRICT"
+		| "SEGMENT_DAG_INVALID"
+		| "SEGMENT_REPO_UNKNOWN";
 	message: string;
 	taskPath?: string;
 	taskId?: string;
@@ -425,6 +500,8 @@ export const FATAL_DISCOVERY_CODES: ReadonlyArray<DiscoveryError["code"]> = [
 	"TASK_REPO_UNRESOLVED",
 	"TASK_REPO_UNKNOWN",
 	"TASK_ROUTING_STRICT",
+	"SEGMENT_DAG_INVALID",
+	"SEGMENT_REPO_UNKNOWN",
 ] as const;
 
 /** Result of the full discovery pipeline */
@@ -457,6 +534,8 @@ export interface GraphValidationResult {
 export interface WaveComputationResult {
 	waves: WaveAssignment[];
 	errors: DiscoveryError[];
+	/** Optional task→segment planning map (TP-080, additive contract). */
+	segmentPlans?: TaskSegmentPlanMap;
 }
 
 

package/extensions/taskplane/waves.ts

@@ -6,8 +6,8 @@ import { join } from "path";
 
 import { parseDependencyReference } from "./discovery.ts";
 import { resolveOperatorId } from "./naming.ts";
-import { AllocationError, getTaskDurationMinutes } from "./types.ts";
-import type { AllocatedLane, AllocatedTask, AllocateLanesResult, AllocationErrorCode, DependencyGraph, DiscoveryError, GraphValidationResult, LaneAssignment, OrchestratorConfig, ParsedTask, WaveAssignment, WaveComputationResult, WorkspaceConfig, WorktreeInfo } from "./types.ts";
+import { AllocationError, buildSegmentId, getTaskDurationMinutes } from "./types.ts";
+import type { AllocatedLane, AllocatedTask, AllocateLanesResult, AllocationErrorCode, DependencyGraph, DiscoveryError, GraphValidationResult, LaneAssignment, OrchestratorConfig, ParsedTask, TaskSegmentPlan, TaskSegmentPlanMap, WaveAssignment, WaveComputationResult, WorkspaceConfig, WorktreeInfo } from "./types.ts";
 import { getCurrentBranch } from "./git.ts";
 import { ensureLaneWorktrees, removeAllWorktrees, removeWorktree } from "./worktree.ts";
 
@@ -606,6 +606,196 @@ export function resolveBaseBranch(
 }
 
 
+// ── Segment Planning (TP-080) ───────────────────────────────────────
+
+const SEGMENT_REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const INFERRED_LINEAR_REASON = "inferred:first-appearance-linear-chain";
+
+function normalizeRepoIdCandidate(raw: string): string | null {
+	const candidate = raw.trim().toLowerCase();
+	if (!SEGMENT_REPO_ID_PATTERN.test(candidate)) return null;
+	return candidate;
+}
+
+function collectKnownRepoIds(pending: Map<string, ParsedTask>): Set<string> {
+	const known = new Set<string>();
+	for (const task of pending.values()) {
+		if (task.resolvedRepoId) {
+			const repoId = normalizeRepoIdCandidate(task.resolvedRepoId);
+			if (repoId) known.add(repoId);
+		}
+		if (task.explicitSegmentDag) {
+			for (const repoIdRaw of task.explicitSegmentDag.repoIds) {
+				const repoId = normalizeRepoIdCandidate(repoIdRaw);
+				if (repoId) known.add(repoId);
+			}
+		}
+	}
+	return known;
+}
+
+function extractRepoPrefixFromFileScope(fileScopeEntry: string): string | null {
+	const normalized = fileScopeEntry.replace(/\\/g, "/").trim();
+	if (!normalized) return null;
+	const firstSegment = normalized.split("/")[0]?.trim();
+	if (!firstSegment) return null;
+	return normalizeRepoIdCandidate(firstSegment);
+}
+
+interface InferredRepoOrder {
+	repoIds: string[];
+	usedFallback: boolean;
+}
+
+/**
+ * Build deterministic repo ordering for inferred segment plans.
+ *
+ * Signal precedence:
+ * 1) file scope repo prefixes (first appearance)
+ * 2) dependency task repos (first appearance)
+ * 3) fallback to `resolvedRepoId`, then synthetic `default`
+ */
+export function inferTaskRepoOrder(
+	task: ParsedTask,
+	pending: Map<string, ParsedTask>,
+	knownRepoIds: Set<string>,
+): InferredRepoOrder {
+	const firstAppearance = new Map<string, number>();
+	let cursor = 0;
+
+	function record(repoIdRaw: string, requireKnown = false): string | null {
+		const repoId = normalizeRepoIdCandidate(repoIdRaw);
+		if (!repoId) return null;
+		if (requireKnown && knownRepoIds.size > 0 && !knownRepoIds.has(repoId)) return null;
+		if (!firstAppearance.has(repoId)) {
+			firstAppearance.set(repoId, cursor++);
+		}
+		return repoId;
+	}
+
+	let hasPrimarySignal = false;
+
+	for (const scopeEntry of task.fileScope) {
+		if (knownRepoIds.size === 0) {
+			// Repo-mode guard: without known workspace repo IDs, fileScope prefixes like
+			// "src/" or "lib/" are ambiguous and should not create synthetic segments.
+			continue;
+		}
+		const repoId = extractRepoPrefixFromFileScope(scopeEntry);
+		if (!repoId) continue;
+		if (record(repoId, true) !== null) {
+			hasPrimarySignal = true;
+		}
+	}
+
+	for (const depRaw of task.dependencies) {
+		const depId = parseDependencyReference(depRaw).taskId;
+		const depTask = pending.get(depId);
+		if (depTask?.resolvedRepoId && record(depTask.resolvedRepoId, true) !== null) {
+			hasPrimarySignal = true;
+		}
+	}
+
+	if (!hasPrimarySignal) {
+		const fallback = normalizeRepoIdCandidate(task.resolvedRepoId ?? "") || "default";
+		return {
+			repoIds: [fallback],
+			usedFallback: true,
+		};
+	}
+
+	if (task.resolvedRepoId) {
+		record(task.resolvedRepoId, true);
+	}
+
+	const repoIds = [...firstAppearance.entries()]
+		.sort((a, b) => {
+			if (a[1] !== b[1]) return a[1] - b[1];
+			return a[0].localeCompare(b[0]);
+		})
+		.map(([repoId]) => repoId);
+
+	return {
+		repoIds,
+		usedFallback: false,
+	};
+}
+
+function sortSegmentEdges<T extends { fromSegmentId: string; toSegmentId: string }>(
+	edges: T[],
+): T[] {
+	return [...edges].sort((a, b) => {
+		if (a.fromSegmentId !== b.fromSegmentId) return a.fromSegmentId.localeCompare(b.fromSegmentId);
+		return a.toSegmentId.localeCompare(b.toSegmentId);
+	});
+}
+
+function buildSegmentNodes(taskId: string, repoIds: string[]) {
+	const nodes = repoIds.map((repoId, order) => ({
+		segmentId: buildSegmentId(taskId, repoId),
+		taskId,
+		repoId,
+		order,
+	}));
+	return nodes.sort((a, b) => (a.order - b.order) || a.repoId.localeCompare(b.repoId));
+}
+
+export function buildSegmentPlanForTask(
+	task: ParsedTask,
+	pending: Map<string, ParsedTask>,
+	knownRepoIds: Set<string>,
+): TaskSegmentPlan {
+	if (task.explicitSegmentDag) {
+		const repoIds = [...task.explicitSegmentDag.repoIds];
+		const segments = buildSegmentNodes(task.taskId, repoIds);
+		const edges = sortSegmentEdges(
+			task.explicitSegmentDag.edges.map((edge) => ({
+				fromSegmentId: buildSegmentId(task.taskId, edge.fromRepoId),
+				toSegmentId: buildSegmentId(task.taskId, edge.toRepoId),
+				provenance: "explicit" as const,
+				reason: "prompt:segment-dag",
+			})),
+		);
+		return {
+			taskId: task.taskId,
+			segments,
+			edges,
+			mode: "explicit-dag",
+		};
+	}
+
+	const inferred = inferTaskRepoOrder(task, pending, knownRepoIds);
+	const segments = buildSegmentNodes(task.taskId, inferred.repoIds);
+	const edges = sortSegmentEdges(
+		segments.slice(0, -1).map((segment, idx) => ({
+			fromSegmentId: segment.segmentId,
+			toSegmentId: segments[idx + 1].segmentId,
+			provenance: "inferred" as const,
+			reason: INFERRED_LINEAR_REASON,
+		})),
+	);
+
+	return {
+		taskId: task.taskId,
+		segments,
+		edges,
+		mode: inferred.usedFallback ? "repo-singleton" : "inferred-sequential",
+	};
+}
+
+/** Build a deterministic taskId→segmentPlan map for the whole pending set. */
+export function buildTaskSegmentPlans(pending: Map<string, ParsedTask>): TaskSegmentPlanMap {
+	const knownRepoIds = collectKnownRepoIds(pending);
+	const plans: TaskSegmentPlanMap = new Map();
+	for (const taskId of [...pending.keys()].sort()) {
+		const task = pending.get(taskId);
+		if (!task) continue;
+		plans.set(taskId, buildSegmentPlanForTask(task, pending, knownRepoIds));
+	}
+	return plans;
+}
+
+
 // ── Lane Assignment ──────────────────────────────────────────────────
 
 /**
@@ -1181,6 +1371,9 @@ export function computeWaveAssignments(
 		return { waves: [], errors: waveErrors };
 	}
 
+	// Step 3.5: Build additive segment planning output (deterministic map)
+	const segmentPlans = buildTaskSegmentPlans(pending);
+
 	// Step 4: Assign tasks to lanes within each wave
 	const waveAssignments: WaveAssignment[] = [];
 	for (let i = 0; i < rawWaves.length; i++) {
@@ -1199,5 +1392,5 @@ export function computeWaveAssignments(
 		});
 	}
 
-	return { waves: waveAssignments, errors };
+	return { waves: waveAssignments, errors, segmentPlans };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.22.8",
+  "version": "0.22.9",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/task-merger.md

@@ -70,12 +70,11 @@ Use the source branch and merge message from the merge request.
 
 ### Step 4: Verification
 
-Run each verification command from the merge request. Typical commands:
+Run each verification command from the merge request's `## Verification Commands`
+section **exactly as written**. Do NOT substitute your own test commands — the
+merge request contains the project's actual test command.
 
-```bash
-npm test                           # Unit/integration checks
-npm run build                      # Build/compile checks
-```
+If the verification section is empty, skip verification and proceed with the merge.
 
 **If verification passes:** Write result with `status: "SUCCESS"` (or
 `"CONFLICT_RESOLVED"` if conflicts were auto-resolved).