taskplane 0.27.0 → 0.28.1

package/extensions/taskplane/discovery.ts

@@ -1,1508 +1,1818 @@
-/**
- * Task discovery, PROMPT.md parsing, dependency resolution
- * @module orch/discovery
- */
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "fs";
-import { join, dirname, basename, resolve } from "path";
-
-import { FATAL_DISCOVERY_CODES } from "./types.ts";
-import type { DiscoveryError, DiscoveryResult, ParsedTask, PromptSegmentDagMetadata, TaskArea, WorkspaceConfig } from "./types.ts";
-
-// ── PROMPT.md Parsing ────────────────────────────────────────────────
-
-/**
- * Extract the task ID from a folder name.
- * Convention: "TO-014-accrual-engine" → "TO-014"
- * Matches prefix-number patterns like "COMP-006", "TS-004", "TO-014".
- */
-export function extractTaskIdFromFolderName(folderName: string): string | null {
-	const match = folderName.match(/^([A-Z]+-\d+)/);
-	return match ? match[1] : null;
-}
-
-export interface DependencyRef {
-	raw: string;
-	taskId: string;
-	areaName?: string;
-}
-
-export function parseDependencyReference(raw: string): DependencyRef {
-	const trimmed = raw.trim();
-	const qualified = trimmed.match(/^([a-z0-9-]+)\/([A-Z]+-\d+)$/i);
-	if (qualified) {
-		return {
-			raw: trimmed,
-			areaName: qualified[1].toLowerCase(),
-			taskId: qualified[2].toUpperCase(),
-		};
-	}
-
-	const idOnly = trimmed.match(/^([A-Z]+-\d+)$/i);
-	if (idOnly) {
-		return {
-			raw: trimmed,
-			taskId: idOnly[1].toUpperCase(),
-		};
-	}
-
-	return {
-		raw: trimmed,
-		taskId: trimmed.toUpperCase(),
-	};
-}
-
-export function normalizeDependencyReference(raw: string): string {
-	const parsed = parseDependencyReference(raw);
-	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.
- *
- * Required fields (hard fail if missing):
- *   - Task ID: extracted from `# Task: XX-NNN - Name` heading OR from folder name
- *
- * Optional fields (defaults used if absent):
- *   - Dependencies: defaults to [] (no dependencies)
- *   - Review Level: defaults to 2
- *   - Size: defaults to "M"
- *   - File Scope: defaults to []
- *   - Task Name: defaults to folder name
- *
- * Dependency syntax accepted:
- *   - "**None**" or "None" → empty list
- *   - "**Requires:** COMP-005 ..." → ["COMP-005"]
- *   - "**Requires:** time-off/TO-014 ..." → ["time-off/TO-014"]
- *   - "- COMP-005 (description)" → ["COMP-005"]
- *   - "- **time-off/TO-014** — description" → ["time-off/TO-014"]
- *   - Multiple bullet points → multiple dependencies
- */
-export function parsePromptForOrchestrator(
-	promptPath: string,
-	taskFolder: string,
-	areaName: string,
-): { task: ParsedTask | null; error: DiscoveryError | null } {
-	const folderName = basename(taskFolder);
-	let content: string;
-
-	try {
-		content = readFileSync(promptPath, "utf-8");
-	} catch {
-		return {
-			task: null,
-			error: {
-				code: "PARSE_MALFORMED",
-				message: `Cannot read PROMPT.md: ${promptPath}`,
-				taskPath: promptPath,
-			},
-		};
-	}
-
-	// ── Extract task ID ──────────────────────────────────────────
-	// Try from heading first: "# Task: COMP-006 - Pay Bands Implementation"
-	let taskId: string | null = null;
-	let taskName = folderName;
-
-	const headingMatch = content.match(/^#\s+Task:\s+([A-Z]+-\d+)\s*[-—]\s*(.+)$/m);
-	if (headingMatch) {
-		taskId = headingMatch[1];
-		taskName = headingMatch[2].trim();
-	}
-
-	// Fallback: extract from folder name
-	if (!taskId) {
-		taskId = extractTaskIdFromFolderName(folderName);
-	}
-
-	if (!taskId) {
-		return {
-			task: null,
-			error: {
-				code: "PARSE_MISSING_ID",
-				message: `Cannot extract task ID from heading or folder name "${folderName}" in ${promptPath}`,
-				taskPath: promptPath,
-			},
-		};
-	}
-
-	// ── Extract review level ─────────────────────────────────────
-	// "## Review Level: 1 (Plan Only)" or "## Review Level: 2"
-	let reviewLevel = 2;
-	const reviewMatch = content.match(/^##\s+Review Level:\s*(\d+)/m);
-	if (reviewMatch) {
-		reviewLevel = parseInt(reviewMatch[1], 10);
-	}
-
-	// ── Extract size ─────────────────────────────────────────────
-	// "**Size:** M" (usually near top, after Created date)
-	let size = "M";
-	const sizeMatch = content.match(/\*\*Size:\*\*\s*([SMLsml])/);
-	if (sizeMatch) {
-		size = sizeMatch[1].toUpperCase();
-	}
-
-	// ── Extract dependencies ─────────────────────────────────────
-	const dependencies: string[] = [];
-	const depSectionMatch = content.match(
-		/^##\s+Dependencies\s*\n([\s\S]*?)(?=\n##\s|\n---|\n$)/m,
-	);
-
-	if (depSectionMatch) {
-		const depBody = depSectionMatch[1].trim();
-
-		// Check for "None" variants
-		if (!/\*?\*?None\*?\*?/i.test(depBody) && depBody.length > 0) {
-			// Pattern 1: "**Requires:** COMP-005 ..." or "**Requires:** time-off/TO-014 ..."
-			const requiresMatches = depBody.matchAll(
-				/\*?\*?Requires:?\*?\*?\s*((?:[a-z0-9-]+\/)?[A-Z]+-\d+)/gi,
-			);
-			for (const m of requiresMatches) {
-				const dep = normalizeDependencyReference(m[1]);
-				if (!dependencies.includes(dep)) dependencies.push(dep);
-			}
-
-			// Pattern 2: Bullet list "- COMP-005 ...", "- **time-off/TO-014** ..."
-			const bulletMatches = depBody.matchAll(
-				/^[\s-]*\*?\*?((?:[a-z0-9-]+\/)?[A-Z]+-\d+)\*?\*?/gim,
-			);
-			for (const m of bulletMatches) {
-				const dep = normalizeDependencyReference(m[1]);
-				if (!dependencies.includes(dep)) dependencies.push(dep);
-			}
-
-			// Pattern 3: Inline dependency references not caught above
-			if (dependencies.length === 0) {
-				const inlineMatches = depBody.matchAll(/\b((?:[a-z0-9-]+\/)?[A-Z]+-\d+)\b/gi);
-				for (const m of inlineMatches) {
-					const dep = parseDependencyReference(m[1]);
-					if (dep.taskId === taskId) continue; // Don't add self-references
-					const normalized = normalizeDependencyReference(m[1]);
-					if (!dependencies.includes(normalized)) {
-						dependencies.push(normalized);
-					}
-				}
-			}
-		}
-	}
-
-	// ── Extract execution target (repo ID) ──────────────────────
-	// Repo ID validation: lowercase alphanumeric + hyphens, starting with alnum
-	const REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
-
-	let promptRepoId: string | undefined;
-
-	// Priority 1: Section-based "## Execution Target" with "Repo: <id>" line
-	// Capture everything from section header to the next heading or --- divider.
-	// We avoid \n$ (which in multiline mode matches blank lines) by using a two-pass
-	// approach: find the section start, then slice to the next section boundary.
-	const execTargetHeaderIdx = content.search(/^##\s+Execution Target\s*$/m);
-	let execTargetSectionBody: string | null = null;
-	if (execTargetHeaderIdx !== -1) {
-		const afterHeader = content.indexOf("\n", execTargetHeaderIdx);
-		if (afterHeader !== -1) {
-			const rest = content.slice(afterHeader + 1);
-			const nextSectionMatch = rest.search(/^##\s|^---/m);
-			execTargetSectionBody = nextSectionMatch !== -1
-				? rest.slice(0, nextSectionMatch)
-				: rest;
-		}
-	}
-	if (execTargetSectionBody !== null) {
-		// Match "Repo: api" or "**Repo:** api" or "Workspace: api" with whitespace
-		const repoLineMatch = execTargetSectionBody.match(
-			/^\s*\*?\*?(?:Repo|Workspace):?\*?\*?\s+(\S+)/mi,
-		);
-		if (repoLineMatch) {
-			const candidate = repoLineMatch[1].trim().toLowerCase();
-			if (REPO_ID_PATTERN.test(candidate)) {
-				promptRepoId = candidate;
-			}
-		}
-	}
-
-	// Priority 2 (fallback): Inline "**Repo:** <id>" or "**Workspace:** <id>" anywhere in content
-	if (!promptRepoId) {
-		const inlineRepoMatch = content.match(
-			/^\*\*(?:Repo|Workspace):\*\*\s+(\S+)/m,
-		);
-		if (inlineRepoMatch) {
-			const candidate = inlineRepoMatch[1].trim().toLowerCase();
-			if (REPO_ID_PATTERN.test(candidate)) {
-				promptRepoId = candidate;
-			}
-		}
-	}
-
-	// ── Extract file scope ───────────────────────────────────────
-	const fileScope: string[] = [];
-	const fileScopeMatch = content.match(
-		/^##\s+File Scope\s*\n([\s\S]*?)(?=\n##\s|\n---|\n$)/m,
-	);
-
-	if (fileScopeMatch) {
-		const scopeBody = fileScopeMatch[1].trim();
-		const scopeLines = scopeBody.split("\n");
-		for (const line of scopeLines) {
-			// "- extensions/task-orchestrator.ts" or "- `api-service/src/health.js`"
-			let trimmed = line.replace(/^[\s-*]+/, "").trim();
-			// Strip inline backticks: `path/to/file` → path/to/file
-			if (trimmed.startsWith("`") && trimmed.endsWith("`")) {
-				trimmed = trimmed.slice(1, -1);
-			}
-			if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("```")) {
-				fileScope.push(trimmed);
-			}
-		}
-	}
-
-	// ── 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,
-			taskName,
-			reviewLevel,
-			size,
-			dependencies,
-			fileScope,
-			taskFolder: resolve(taskFolder),
-			promptPath: resolve(promptPath),
-			areaName,
-			status: "pending",
-			...(promptRepoId ? { promptRepoId } : {}),
-			...(explicitSegmentDag ? { explicitSegmentDag } : {}),
-		},
-		error: null,
-	};
-}
-
-
-// ── Area Scanning ────────────────────────────────────────────────────
-
-/**
- * Scan an area path for pending tasks.
- *
- * Lists immediate subdirectories only (no recursion).
- * Skips "archive" directories and folders with .DONE files.
- * Parses PROMPT.md in each remaining subdirectory.
- */
-export function scanAreaForTasks(
-	areaPath: string,
-	areaName: string,
-): { tasks: ParsedTask[]; errors: DiscoveryError[] } {
-	const tasks: ParsedTask[] = [];
-	const errors: DiscoveryError[] = [];
-
-	const resolvedPath = resolve(areaPath);
-	if (!existsSync(resolvedPath)) {
-		errors.push({
-			code: "SCAN_ERROR",
-			message: `Area path does not exist: ${resolvedPath}`,
-			taskPath: resolvedPath,
-		});
-		return { tasks, errors };
-	}
-
-	let entries: string[];
-	try {
-		entries = readdirSync(resolvedPath);
-	} catch {
-		errors.push({
-			code: "SCAN_ERROR",
-			message: `Cannot read area directory: ${resolvedPath}`,
-			taskPath: resolvedPath,
-		});
-		return { tasks, errors };
-	}
-
-	for (const entry of entries) {
-		// Skip archive directory
-		if (entry.toLowerCase() === "archive") continue;
-
-		const entryPath = join(resolvedPath, entry);
-
-		// Only process directories
-		try {
-			if (!statSync(entryPath).isDirectory()) continue;
-		} catch {
-			continue;
-		}
-
-		// Skip if .DONE exists (already complete)
-		if (existsSync(join(entryPath, ".DONE"))) continue;
-
-		// Skip if no PROMPT.md
-		const promptPath = join(entryPath, "PROMPT.md");
-		if (!existsSync(promptPath)) continue;
-
-		// Parse PROMPT.md
-		const result = parsePromptForOrchestrator(promptPath, entryPath, areaName);
-		if (result.error) {
-			errors.push(result.error);
-		}
-		if (result.task) {
-			tasks.push(result.task);
-		}
-	}
-
-	return { tasks, errors };
-}
-
-
-// ── Completed Task Set ───────────────────────────────────────────────
-
-/**
- * Build a set of completed task IDs by scanning:
- * 1. archive/ subdirectories for .DONE markers
- * 2. Active task folders that have .DONE files (caught during scanAreaForTasks skip)
- *
- * This set is used only for dependency resolution — completed tasks are never re-executed.
- */
-export function buildCompletedTaskSet(areaPaths: string[]): Set<string> {
-	const completed = new Set<string>();
-
-	for (const areaPath of areaPaths) {
-		const resolvedPath = resolve(areaPath);
-		if (!existsSync(resolvedPath)) continue;
-
-		let entries: string[];
-		try {
-			entries = readdirSync(resolvedPath);
-		} catch {
-			continue;
-		}
-
-		for (const entry of entries) {
-			const entryPath = join(resolvedPath, entry);
-
-			try {
-				if (!statSync(entryPath).isDirectory()) continue;
-			} catch {
-				continue;
-			}
-
-			if (entry.toLowerCase() === "archive") {
-				// Scan archive subdirectories for completed tasks
-				let archiveEntries: string[];
-				try {
-					archiveEntries = readdirSync(entryPath);
-				} catch {
-					continue;
-				}
-				for (const archiveEntry of archiveEntries) {
-					const archiveFolderPath = join(entryPath, archiveEntry);
-					try {
-						if (!statSync(archiveFolderPath).isDirectory()) continue;
-					} catch {
-						continue;
-					}
-					// Only treat archive tasks as complete when .DONE marker exists
-					if (!existsSync(join(archiveFolderPath, ".DONE"))) continue;
-					const taskId = extractTaskIdFromFolderName(archiveEntry);
-					if (taskId) {
-						completed.add(taskId);
-					}
-				}
-			} else {
-				// Active folder with .DONE = completed
-				if (existsSync(join(entryPath, ".DONE"))) {
-					const taskId = extractTaskIdFromFolderName(entry);
-					if (taskId) {
-						completed.add(taskId);
-					}
-				}
-			}
-		}
-	}
-
-	return completed;
-}
-
-
-// ── Argument Resolution ──────────────────────────────────────────────
-
-/**
- * Resolve command arguments into area scan paths and direct task folders.
- *
- * Accepts mixed arguments:
- *   - "all" → all areas from task_areas
- *   - area name → looked up in task_areas
- *   - directory path → used as-is
- *   - PROMPT.md path → single task (dirname used as task folder)
- */
-export function resolveArguments(
-	args: string,
-	taskAreas: Record<string, TaskArea>,
-	cwd: string,
-): { areaScanPaths: string[]; directTaskFolders: string[]; errors: DiscoveryError[] } {
-	const areaScanPaths: string[] = [];
-	const directTaskFolders: string[] = [];
-	const errors: DiscoveryError[] = [];
-
-	const tokens = args.trim().split(/\s+/).filter(Boolean);
-
-	for (const token of tokens) {
-		if (token.toLowerCase() === "all") {
-			// Expand to all areas
-			for (const area of Object.values(taskAreas)) {
-				const fullPath = resolve(cwd, area.path);
-				if (!areaScanPaths.includes(fullPath)) {
-					areaScanPaths.push(fullPath);
-				}
-			}
-		} else if (taskAreas[token]) {
-			// Known area name
-			const fullPath = resolve(cwd, taskAreas[token].path);
-			if (!areaScanPaths.includes(fullPath)) {
-				areaScanPaths.push(fullPath);
-			}
-		} else if (
-			token.endsWith("PROMPT.md") &&
-			existsSync(resolve(cwd, token))
-		) {
-			// Single PROMPT.md file
-			directTaskFolders.push(resolve(cwd, dirname(token)));
-		} else if (existsSync(resolve(cwd, token))) {
-			// Directory path
-			const fullPath = resolve(cwd, token);
-			try {
-				if (statSync(fullPath).isDirectory()) {
-					if (!areaScanPaths.includes(fullPath)) {
-						areaScanPaths.push(fullPath);
-					}
-				} else {
-					errors.push({
-						code: "UNKNOWN_ARG",
-						message: `Not a directory or PROMPT.md file: ${token}`,
-					});
-				}
-			} catch {
-				errors.push({
-					code: "UNKNOWN_ARG",
-					message: `Cannot stat path: ${token}`,
-				});
-			}
-		} else {
-			errors.push({
-				code: "UNKNOWN_ARG",
-				message: `Unknown area, path, or file: "${token}"`,
-			});
-		}
-	}
-
-	return { areaScanPaths, directTaskFolders, errors };
-}
-
-export interface DiscoveryOptions {
-	refreshDependencies?: boolean;
-	dependencySource?: "prompt" | "agent";
-	useDependencyCache?: boolean;
-	/** Workspace config for repo routing (null/undefined = repo mode, no routing). */
-	workspaceConfig?: WorkspaceConfig | null;
-}
-
-export interface DependencyCacheFile {
-	version: number;
-	generatedAt: string;
-	source: string;
-	tasks: Record<string, string[]>;
-}
-
-export function normalizePathForCompare(p: string): string {
-	return resolve(p).replace(/\\/g, "/").toLowerCase();
-}
-
-export function isPathWithin(childPath: string, parentPath: string): boolean {
-	const child = normalizePathForCompare(childPath);
-	const parent = normalizePathForCompare(parentPath);
-	return child === parent || child.startsWith(`${parent}/`);
-}
-
-export function dedupeAndNormalizeDeps(deps: string[]): string[] {
-	const seen = new Set<string>();
-	const out: string[] = [];
-	for (const dep of deps) {
-		const norm = normalizeDependencyReference(dep);
-		if (!norm || seen.has(norm)) continue;
-		seen.add(norm);
-		out.push(norm);
-	}
-	return out;
-}
-
-export function loadAreaDependencyCache(areaPath: string): DependencyCacheFile | null {
-	const cachePath = join(areaPath, "dependencies.json");
-	if (!existsSync(cachePath)) return null;
-	try {
-		const raw = readFileSync(cachePath, "utf-8");
-		const parsed = JSON.parse(raw) as DependencyCacheFile;
-		if (!parsed || typeof parsed !== "object" || !parsed.tasks) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-
-export function writeAreaDependencyCache(
-	areaPath: string,
-	pending: Map<string, ParsedTask>,
-	source: "prompt" | "agent",
-): void {
-	const tasks: Record<string, string[]> = {};
-	for (const task of pending.values()) {
-		if (!isPathWithin(task.taskFolder, areaPath)) continue;
-		tasks[task.taskId] = dedupeAndNormalizeDeps(task.dependencies);
-	}
-
-	const cachePath = join(areaPath, "dependencies.json");
-	const payload: DependencyCacheFile = {
-		version: 1,
-		generatedAt: new Date().toISOString(),
-		source,
-		tasks,
-	};
-
-	try {
-		// Keep deterministic formatting for easy diffs
-		const json = JSON.stringify(payload, null, 2);
-		writeFileSync(cachePath, `${json}\n`, "utf-8");
-	} catch {
-		// Non-fatal: discovery should still succeed without cache persistence
-	}
-}
-
-export function applyDependenciesFromCache(
-	discovery: DiscoveryResult,
-	areaScanPaths: string[],
-): { applied: boolean } {
-	let applied = false;
-	for (const areaPath of areaScanPaths) {
-		const cache = loadAreaDependencyCache(areaPath);
-		if (!cache) continue;
-		for (const task of discovery.pending.values()) {
-			if (!isPathWithin(task.taskFolder, areaPath)) continue;
-			const cachedDeps = cache.tasks[task.taskId];
-			if (!cachedDeps) continue;
-			task.dependencies = dedupeAndNormalizeDeps(cachedDeps);
-			applied = true;
-		}
-	}
-	return { applied };
-}
-
-
-// ── Task Registry ────────────────────────────────────────────────────
-
-/**
- * Build the full task registry: pending tasks + completed set.
- *
- * Enforces global uniqueness of task IDs across all areas.
- * If duplicates are found, returns a fail-fast error listing all collision locations.
- */
-export function buildTaskRegistry(
-	areaScanPaths: string[],
-	directTaskFolders: string[],
-	taskAreas: Record<string, TaskArea>,
-	cwd: string,
-): DiscoveryResult {
-	const pending = new Map<string, ParsedTask>();
-	const errors: DiscoveryError[] = [];
-
-	// Track all locations per task ID for duplicate detection
-	const idLocations = new Map<string, string[]>();
-
-	function trackId(taskId: string, location: string) {
-		const existing = idLocations.get(taskId) || [];
-		existing.push(location);
-		idLocations.set(taskId, existing);
-	}
-
-	// Resolve area names for scan paths
-	const areaNameByPath = new Map<string, string>();
-	for (const [name, area] of Object.entries(taskAreas)) {
-		areaNameByPath.set(resolve(cwd, area.path), name);
-	}
-
-	// 1. Scan area paths for pending tasks
-	for (const areaPath of areaScanPaths) {
-		const areaName = areaNameByPath.get(areaPath) || basename(areaPath);
-		const result = scanAreaForTasks(areaPath, areaName);
-		errors.push(...result.errors);
-
-		for (const task of result.tasks) {
-			trackId(task.taskId, task.promptPath);
-			pending.set(task.taskId, task);
-		}
-	}
-
-	// 2. Process direct task folders (single PROMPT.md files)
-	for (const taskFolder of directTaskFolders) {
-		const promptPath = join(taskFolder, "PROMPT.md");
-		if (!existsSync(promptPath)) {
-			errors.push({
-				code: "SCAN_ERROR",
-				message: `No PROMPT.md found in direct task folder: ${taskFolder}`,
-				taskPath: taskFolder,
-			});
-			continue;
-		}
-
-		// Try to determine area name from path
-		let areaName = "unknown";
-		for (const [name, area] of Object.entries(taskAreas)) {
-			const resolvedAreaPath = resolve(cwd, area.path);
-			if (taskFolder.startsWith(resolvedAreaPath)) {
-				areaName = name;
-				break;
-			}
-		}
-
-		// Skip if .DONE exists
-		if (existsSync(join(taskFolder, ".DONE"))) continue;
-
-		const result = parsePromptForOrchestrator(promptPath, taskFolder, areaName);
-		if (result.error) {
-			errors.push(result.error);
-		}
-		if (result.task) {
-			trackId(result.task.taskId, result.task.promptPath);
-			pending.set(result.task.taskId, result.task);
-		}
-	}
-
-	// 3. Build completed task set from all scanned areas
-	const completed = buildCompletedTaskSet(areaScanPaths);
-
-	// Also scan all task_areas for completed tasks (needed for cross-area dep resolution)
-	const allAreaPaths = Object.values(taskAreas).map((a) => resolve(cwd, a.path));
-	const globalCompleted = buildCompletedTaskSet(allAreaPaths);
-	for (const id of globalCompleted) {
-		completed.add(id);
-	}
-
-	// 4. Check for duplicate task IDs (global uniqueness enforcement)
-	for (const [taskId, locations] of idLocations) {
-		if (locations.length > 1) {
-			errors.push({
-				code: "DUPLICATE_ID",
-				message:
-					`Duplicate task ID "${taskId}" found in ${locations.length} locations:\n` +
-					locations.map((l) => `  - ${l}`).join("\n"),
-				taskId,
-			});
-		}
-	}
-
-	return { pending, completed, errors };
-}
-
-
-// ── Cross-Area Dependency Resolution ─────────────────────────────────
-
-/** Candidate match for a dependency reference found in task areas. */
-export interface DependencyCandidate {
-	areaName: string;
-	path: string;
-	status: "pending" | "complete";
-}
-
-export function findDependencyCandidates(
-	depRef: DependencyRef,
-	taskAreas: Record<string, TaskArea>,
-	cwd: string,
-): DependencyCandidate[] {
-	const candidates: DependencyCandidate[] = [];
-	const sortedAreas = Object.entries(taskAreas).sort((a, b) => a[0].localeCompare(b[0]));
-
-	for (const [areaName, area] of sortedAreas) {
-		if (depRef.areaName && depRef.areaName !== areaName.toLowerCase()) {
-			continue;
-		}
-
-		const areaPath = resolve(cwd, area.path);
-		if (!existsSync(areaPath)) continue;
-
-		let entries: string[];
-		try {
-			entries = readdirSync(areaPath);
-		} catch {
-			continue;
-		}
-
-		// Active tasks (skip archive)
-		for (const entry of entries) {
-			if (entry.toLowerCase() === "archive") continue;
-			const entryTaskId = extractTaskIdFromFolderName(entry);
-			if (entryTaskId !== depRef.taskId) continue;
-
-			const entryPath = join(areaPath, entry);
-			try {
-				if (!statSync(entryPath).isDirectory()) continue;
-			} catch {
-				continue;
-			}
-
-			candidates.push({
-				areaName,
-				path: entryPath,
-				status: existsSync(join(entryPath, ".DONE")) ? "complete" : "pending",
-			});
-		}
-
-		// Archived tasks (require .DONE marker)
-		const archivePath = join(areaPath, "archive");
-		if (!existsSync(archivePath)) continue;
-		try {
-			const archiveEntries = readdirSync(archivePath);
-			for (const archiveEntry of archiveEntries) {
-				const entryTaskId = extractTaskIdFromFolderName(archiveEntry);
-				if (entryTaskId !== depRef.taskId) continue;
-
-				const archiveTaskPath = join(archivePath, archiveEntry);
-				candidates.push({
-					areaName,
-					path: archiveTaskPath,
-					status: existsSync(join(archiveTaskPath, ".DONE")) ? "complete" : "pending",
-				});
-			}
-		} catch {
-			// Ignore archive read errors for discovery resilience
-		}
-	}
-
-	return candidates;
-}
-
-/**
- * Resolve dependencies for all pending tasks.
- *
- * Supports both dependency formats:
- * - TASK-ID (unqualified)
- * - area-name/TASK-ID (area-qualified)
- */
-export function resolveDependencies(
-	discovery: DiscoveryResult,
-	taskAreas: Record<string, TaskArea>,
-	cwd: string,
-): DiscoveryError[] {
-	const errors: DiscoveryError[] = [];
-
-	for (const [taskId, task] of discovery.pending) {
-		for (const depRaw of task.dependencies) {
-			const depRef = parseDependencyReference(depRaw);
-			const depId = depRef.taskId;
-
-			// Fast path for unqualified refs already in registry
-			if (!depRef.areaName) {
-				if (discovery.pending.has(depId)) continue;
-				if (discovery.completed.has(depId)) continue;
-			} else {
-				const pendingTask = discovery.pending.get(depId);
-				if (pendingTask && pendingTask.areaName.toLowerCase() === depRef.areaName) {
-					continue;
-				}
-			}
-
-			const candidates = findDependencyCandidates(depRef, taskAreas, cwd);
-
-			if (candidates.length === 0) {
-				errors.push({
-					code: "DEP_UNRESOLVED",
-					message: `${taskId} depends on ${depRaw} which does not exist in any task area`,
-					taskId,
-					taskPath: task.promptPath,
-				});
-				continue;
-			}
-
-			if (!depRef.areaName && candidates.length > 1) {
-				const options = candidates
-					.map((c) => `  - ${c.areaName}/${depId} [${c.status}] (${c.path})`)
-					.join("\n");
-				errors.push({
-					code: "DEP_AMBIGUOUS",
-					message:
-						`${taskId} depends on ${depId}, but multiple tasks match across areas. ` +
-						`Use an area-qualified dependency (area/${depId}).\n${options}`,
-					taskId,
-					taskPath: task.promptPath,
-				});
-				continue;
-			}
-
-			if (depRef.areaName && candidates.length > 1) {
-				const options = candidates
-					.map((c) => `  - ${c.areaName}/${depId} [${c.status}] (${c.path})`)
-					.join("\n");
-				errors.push({
-					code: "DEP_AMBIGUOUS",
-					message:
-						`${taskId} depends on ${depRaw}, but multiple matching task folders were found. ` +
-						`Resolve duplicate task IDs.\n${options}`,
-					taskId,
-					taskPath: task.promptPath,
-				});
-				continue;
-			}
-
-			const match = candidates[0];
-			if (match.status === "complete") {
-				discovery.completed.add(depId);
-				continue;
-			}
-
-			errors.push({
-				code: "DEP_PENDING",
-				message:
-					`${taskId} depends on ${depRaw} which is pending in "${match.areaName}". ` +
-					`Include that area: /orch ${match.areaName}`,
-				taskId,
-				taskPath: task.promptPath,
-			});
-		}
-	}
-
-	return errors;
-}
-
-
-// ── Task-to-Repo Routing ─────────────────────────────────────────────
-
-/** Repo ID validation: lowercase alphanumeric + hyphens, starting with alnum */
-const ROUTING_REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
-
-/**
- * Resolve the target repo for each discovered task using the routing
- * precedence chain:
- *
- *   1. `task.promptRepoId` — declared in PROMPT.md metadata
- *   2. `taskArea.repoId` — area-level config from task-runner.yaml
- *   3. `workspaceConfig.routing.defaultRepo` — workspace-level default
- *
- * Only applied in workspace mode (when `workspaceConfig` is provided).
- * In repo mode this function is never called.
- *
- * Returns an array of DiscoveryError for routing failures:
- *   - TASK_REPO_UNRESOLVED: no source provided a repo ID
- *   - TASK_REPO_UNKNOWN: resolved repo ID is not in workspace repos map
- */
-export function resolveTaskRouting(
-	discovery: DiscoveryResult,
-	taskAreas: Record<string, TaskArea>,
-	workspaceConfig: WorkspaceConfig,
-): DiscoveryError[] {
-	const errors: DiscoveryError[] = [];
-	const validRepoIds = workspaceConfig.repos;
-	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
-		// workspace-default fallbacks are NOT used for resolution.
-		if (strictMode && !task.promptRepoId) {
-			errors.push({
-				code: "TASK_ROUTING_STRICT",
-				message:
-					`Task ${task.taskId} has no explicit execution target, but strict routing is enabled ` +
-					`(routing.strict: true in workspace config). ` +
-					`Add an execution target to the task's PROMPT.md:\n` +
-					`\n` +
-					`  ## Execution Target\n` +
-					`\n` +
-					`  Repo: <repo-id>\n` +
-					`\n` +
-					`Available repos: ${[...validRepoIds.keys()].join(", ")}`,
-				taskId: task.taskId,
-				taskPath: task.promptPath,
-			});
-			continue;
-		}
-
-		// Precedence 1: prompt-declared repo
-		let resolvedId = task.promptRepoId;
-		let source = "prompt";
-
-		// Precedence 2: area-level repo
-		if (!resolvedId) {
-			const area = taskAreas[task.areaName];
-			if (area?.repoId) {
-				const candidate = area.repoId.trim().toLowerCase();
-				if (ROUTING_REPO_ID_PATTERN.test(candidate)) {
-					resolvedId = candidate;
-					source = "area";
-				}
-			}
-		}
-
-		// Precedence 3: file scope inference — match file path prefixes against
-		// known workspace repo IDs. If file scope entries like "web-client/src/..."
-		// start with a repo name, route the task to that repo.
-		if (!resolvedId && task.fileScope && task.fileScope.length > 0) {
-			const repoIds = [...validRepoIds.keys()];
-			const repoCounts = new Map<string, number>();
-			for (const filePath of task.fileScope) {
-				const normalized = filePath.replace(/\\/g, "/");
-				for (const repoId of repoIds) {
-					if (normalized.startsWith(repoId + "/") || normalized === repoId) {
-						repoCounts.set(repoId, (repoCounts.get(repoId) || 0) + 1);
-						break; // first matching repo wins for this path
-					}
-				}
-			}
-			// Use the repo with the most file scope matches (majority vote)
-			if (repoCounts.size === 1) {
-				resolvedId = repoCounts.keys().next().value!;
-				source = "file-scope";
-			} else if (repoCounts.size > 1) {
-				// Multiple repos in file scope — pick the one with most entries.
-				// (Future: #51 will handle multi-repo tasks properly)
-				let maxCount = 0;
-				for (const [repoId, count] of repoCounts) {
-					if (count > maxCount) {
-						maxCount = count;
-						resolvedId = repoId;
-					}
-				}
-				source = "file-scope";
-			}
-		}
-
-		// Precedence 4: workspace default repo
-		if (!resolvedId) {
-			resolvedId = workspaceConfig.routing.defaultRepo;
-			source = "default";
-		}
-
-		// Validate resolution
-		if (!resolvedId) {
-			errors.push({
-				code: "TASK_REPO_UNRESOLVED",
-				message:
-					`Task ${task.taskId} has no resolved repo. ` +
-					`Add file scope paths prefixed with the repo name (e.g., "web-client/src/..."), ` +
-					`set repo_id on area "${task.areaName}", ` +
-					`or set routing.default_repo in the workspace config.`,
-				taskId: task.taskId,
-				taskPath: task.promptPath,
-			});
-			continue;
-		}
-
-		if (!validRepoIds.has(resolvedId)) {
-			errors.push({
-				code: "TASK_REPO_UNKNOWN",
-				message:
-					`Task ${task.taskId} resolved to repo "${resolvedId}" (via ${source}), ` +
-					`but no repo with that ID exists in the workspace config. ` +
-					`Known repos: ${[...validRepoIds.keys()].join(", ")}`,
-				taskId: task.taskId,
-				taskPath: task.promptPath,
-			});
-			continue;
-		}
-
-		// Attach resolved repo to the task
-		task.resolvedRepoId = resolvedId;
-	}
-
-	return errors;
-}
-
-
-// ── Discovery Pipeline (Public) ──────────────────────────────────────
-
-/**
- * Run the full discovery pipeline:
- * 1. Resolve arguments to scan paths and direct task folders
- * 2. Build task registry (scan, parse, deduplicate)
- * 3. Resolve cross-area dependencies
- *
- * Returns a DiscoveryResult with pending tasks, completed set, and any errors.
- */
-export function runDiscovery(
-	args: string,
-	taskAreas: Record<string, TaskArea>,
-	cwd: string,
-	options: DiscoveryOptions = {},
-): DiscoveryResult {
-	const dependencySource = options.dependencySource ?? "prompt";
-	const useDependencyCache = options.useDependencyCache ?? false;
-	const refreshDependencies = options.refreshDependencies ?? false;
-
-	// Step 1: Resolve arguments
-	const resolved = resolveArguments(args, taskAreas, cwd);
-	if (resolved.errors.length > 0) {
-		return {
-			pending: new Map(),
-			completed: new Set(),
-			errors: resolved.errors,
-		};
-	}
-
-	if (resolved.areaScanPaths.length === 0 && resolved.directTaskFolders.length === 0) {
-		return {
-			pending: new Map(),
-			completed: new Set(),
-			errors: [
-				{
-					code: "UNKNOWN_ARG",
-					message: "No valid areas, paths, or PROMPT.md files found in arguments",
-				},
-			],
-		};
-	}
-
-	// Step 2: Build task registry (prompt-parsed dependencies as baseline)
-	const discovery = buildTaskRegistry(
-		resolved.areaScanPaths,
-		resolved.directTaskFolders,
-		taskAreas,
-		cwd,
-	);
-
-	// If we have duplicate ID errors, stop early (fail-fast)
-	const duplicateErrors = discovery.errors.filter((e) => e.code === "DUPLICATE_ID");
-	if (duplicateErrors.length > 0) {
-		return discovery;
-	}
-
-	// Step 3: Dependency source + cache policy
-	// TS-004 scaffold supports prompt parsing and cached dependency maps.
-	// Agent-based analysis is deferred to later tasks; when selected, we
-	// attempt cache first and fall back to prompt parsing if unavailable.
-	let effectiveDependencySource: "prompt" | "agent" = dependencySource;
-	if (useDependencyCache && !refreshDependencies) {
-		const { applied } = applyDependenciesFromCache(discovery, resolved.areaScanPaths);
-		if (dependencySource === "agent" && !applied) {
-			effectiveDependencySource = "prompt";
-			discovery.errors.push({
-				code: "DEP_SOURCE_FALLBACK",
-				message:
-					"dependencies.source=agent requested, but no dependency cache was found for " +
-					"the selected areas. Falling back to PROMPT.md dependencies.",
-			});
-		}
-	} else if (dependencySource === "agent") {
-		effectiveDependencySource = "prompt";
-		discovery.errors.push({
-			code: "DEP_SOURCE_FALLBACK",
-			message:
-				"dependencies.source=agent requested, but agent-based dependency analysis " +
-				"is not implemented in TS-004 scaffold. Falling back to PROMPT.md dependencies.",
-		});
-	}
-
-	// Step 4: Resolve cross-area dependencies using effective dependencies
-	const depErrors = resolveDependencies(discovery, taskAreas, cwd);
-	discovery.errors.push(...depErrors);
-
-	// Step 5: Persist cache (if enabled) for next run / non-refresh runs
-	if (useDependencyCache) {
-		for (const areaPath of resolved.areaScanPaths) {
-			writeAreaDependencyCache(areaPath, discovery.pending, effectiveDependencySource);
-		}
-	}
-
-	// Step 6: Task-to-repo routing (workspace mode only)
-	const workspaceConfig = options.workspaceConfig;
-	if (workspaceConfig && workspaceConfig.mode === "workspace") {
-		const routingErrors = resolveTaskRouting(discovery, taskAreas, workspaceConfig);
-		discovery.errors.push(...routingErrors);
-	}
-
-	return discovery;
-}
-
-/**
- * Format discovery results as a readable string for display.
- */
-export function formatDiscoveryResults(result: DiscoveryResult): string {
-	const lines: string[] = [];
-
-	// Summary
-	lines.push(`📋 Discovery Results`);
-	lines.push(`   Pending tasks:   ${result.pending.size}`);
-	lines.push(`   Completed tasks: ${result.completed.size}`);
-	lines.push("");
-
-	// List pending tasks grouped by area (deterministic: sorted by area name, then task ID)
-	if (result.pending.size > 0) {
-		const byArea = new Map<string, ParsedTask[]>();
-		for (const task of result.pending.values()) {
-			const existing = byArea.get(task.areaName) || [];
-			existing.push(task);
-			byArea.set(task.areaName, existing);
-		}
-
-		lines.push("Pending Tasks:");
-		const sortedAreas = [...byArea.entries()].sort((a, b) =>
-			a[0].localeCompare(b[0]),
-		);
-		for (const [area, tasks] of sortedAreas) {
-			lines.push(`  ${area}:`);
-			const sortedTasks = [...tasks].sort((a, b) =>
-				a.taskId.localeCompare(b.taskId),
-			);
-			for (const task of sortedTasks) {
-				const deps =
-					task.dependencies.length > 0
-						? ` → depends on: ${task.dependencies.join(", ")}`
-						: "";
-				const repo =
-					task.resolvedRepoId
-						? ` → repo: ${task.resolvedRepoId}`
-						: "";
-				lines.push(
-					`    ${task.taskId} [${task.size}] ${task.taskName}${deps}${repo}`,
-				);
-			}
-		}
-		lines.push("");
-	}
-
-	// Show errors
-	if (result.errors.length > 0) {
-		const fatalCodes = new Set<string>(FATAL_DISCOVERY_CODES);
-		const fatalErrors = result.errors.filter((e) => fatalCodes.has(e.code));
-		const warnings = result.errors.filter((e) => !fatalCodes.has(e.code));
-
-		if (fatalErrors.length > 0) {
-			lines.push("❌ Errors:");
-			for (const err of fatalErrors) {
-				lines.push(`  [${err.code}] ${err.message}`);
-			}
-			lines.push("");
-		}
-
-		if (warnings.length > 0) {
-			lines.push("⚠️  Warnings:");
-			for (const err of warnings) {
-				lines.push(`  [${err.code}] ${err.message}`);
-			}
-			lines.push("");
-		}
-	}
-
-	return lines.join("\n");
-}
-
+/**
+ * Task discovery, PROMPT.md parsing, dependency resolution
+ * @module orch/discovery
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join, dirname, basename, resolve } from "path";
+
+import { FATAL_DISCOVERY_CODES } from "./types.ts";
+import type { DiscoveryError, DiscoveryResult, ParsedTask, PromptSegmentDagMetadata, SegmentCheckboxGroup, StepSegmentMapping, TaskArea, WorkspaceConfig } from "./types.ts";
+
+// ── PROMPT.md Parsing ────────────────────────────────────────────────
+
+/**
+ * Extract the task ID from a folder name.
+ * Convention: "TO-014-accrual-engine" → "TO-014"
+ * Matches prefix-number patterns like "COMP-006", "TS-004", "TO-014".
+ */
+export function extractTaskIdFromFolderName(folderName: string): string | null {
+	const match = folderName.match(/^([A-Z]+-\d+)/);
+	return match ? match[1] : null;
+}
+
+export interface DependencyRef {
+	raw: string;
+	taskId: string;
+	areaName?: string;
+}
+
+export function parseDependencyReference(raw: string): DependencyRef {
+	const trimmed = raw.trim();
+	const qualified = trimmed.match(/^([a-z0-9-]+)\/([A-Z]+-\d+)$/i);
+	if (qualified) {
+		return {
+			raw: trimmed,
+			areaName: qualified[1].toLowerCase(),
+			taskId: qualified[2].toUpperCase(),
+		};
+	}
+
+	const idOnly = trimmed.match(/^([A-Z]+-\d+)$/i);
+	if (idOnly) {
+		return {
+			raw: trimmed,
+			taskId: idOnly[1].toUpperCase(),
+		};
+	}
+
+	return {
+		raw: trimmed,
+		taskId: trimmed.toUpperCase(),
+	};
+}
+
+export function normalizeDependencyReference(raw: string): string {
+	const parsed = parseDependencyReference(raw);
+	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,
+	};
+}
+
+// ── Step-Segment Mapping (Phase A) ───────────────────────────────────
+
+/**
+ * Sentinel repo ID used when the task's primary repo is not yet known at parse time.
+ * Replaced by the resolved repo during routing (resolveTaskRouting).
+ */
+export const SEGMENT_FALLBACK_REPO_PLACEHOLDER = "__primary__";
+
+/**
+ * Simple suggestion helper: find known repo IDs that share a prefix or
+ * have small edit distance from the unknown repo ID.
+ */
+function suggestRepoMatches(unknown: string, known: string[]): string[] {
+	const suggestions: string[] = [];
+	for (const k of known) {
+		// Prefix match (either direction)
+		if (k.startsWith(unknown) || unknown.startsWith(k)) {
+			suggestions.push(k);
+			continue;
+		}
+		// Simple overlap: share at least 3 chars of a common substring
+		const shorter = unknown.length < k.length ? unknown : k;
+		const longer = unknown.length < k.length ? k : unknown;
+		if (shorter.length >= 3 && longer.includes(shorter.slice(0, 3))) {
+			suggestions.push(k);
+		}
+	}
+	return suggestions;
+}
+
+interface StepSegmentParseResult {
+	mapping: StepSegmentMapping[];
+	/** True if at least one step had an explicit `#### Segment:` marker. */
+	hasExplicitMarkers: boolean;
+	warnings: DiscoveryError[];
+	errors: DiscoveryError[];
+}
+
+/**
+ * Parse `#### Segment: <repoId>` markers within `### Step N:` sections of a PROMPT.md.
+ *
+ * Builds a StepSegmentMapping[] that maps each step to its repo-scoped checkbox groups.
+ *
+ * Rules:
+ * - Checkboxes before any segment header (or in steps with no segment headers)
+ *   belong to the task's primary repoId (fallbackRepoId / packet repo).
+ * - A repoId may appear at most once within a step (duplicate → error).
+ * - Empty segments (header but no checkboxes) produce a warning.
+ * - Unknown repoIds are flagged as warnings (validation deferred to routing).
+ */
+export function parseStepSegmentMapping(
+	content: string,
+	taskId: string,
+	fallbackRepoId: string,
+): StepSegmentParseResult {
+	const mapping: StepSegmentMapping[] = [];
+	const warnings: DiscoveryError[] = [];
+	const errors: DiscoveryError[] = [];
+	let hasExplicitMarkers = false;
+
+	// Find ## Steps section
+	const stepsSectionMatch = content.match(/^##\s+Steps\s*$/im);
+	if (!stepsSectionMatch || stepsSectionMatch.index === undefined) {
+		return { mapping, hasExplicitMarkers, warnings, errors };
+	}
+
+	const stepsStart = stepsSectionMatch.index;
+	// Get body from ## Steps to next ## top-level section or --- divider
+	const afterStepsHeader = content.indexOf("\n", stepsStart);
+	if (afterStepsHeader === -1) {
+		return { mapping, hasExplicitMarkers, warnings, errors };
+	}
+	const rest = content.slice(afterStepsHeader + 1);
+	// Find the next top-level section (## but not ###) or --- divider
+	const nextSectionMatch = rest.search(/^##\s+[^#]|^---/m);
+	const stepsBody = nextSectionMatch !== -1 ? rest.slice(0, nextSectionMatch) : rest;
+
+	// Split into step sections by ### Step N: headers
+	const stepHeaderRegex = /^###\s+Step\s+(\d+):\s*(.+)$/gm;
+	const stepHeaders: { index: number; stepNumber: number; stepName: string }[] = [];
+	let match: RegExpExecArray | null;
+	while ((match = stepHeaderRegex.exec(stepsBody)) !== null) {
+		stepHeaders.push({
+			index: match.index,
+			stepNumber: parseInt(match[1], 10),
+			stepName: match[2].trim(),
+		});
+	}
+
+	if (stepHeaders.length === 0) {
+		return { mapping, hasExplicitMarkers, warnings, errors };
+	}
+
+	for (let i = 0; i < stepHeaders.length; i++) {
+		const header = stepHeaders[i];
+		const nextHeaderIndex = i + 1 < stepHeaders.length ? stepHeaders[i + 1].index : stepsBody.length;
+		const stepContent = stepsBody.slice(header.index, nextHeaderIndex);
+
+		// Parse segment groups within this step
+		const segmentHeaderRegex = /^####\s+Segment:\s*(.+)$/gm;
+		const segmentHeaders: { index: number; repoId: string; rawRepoId: string }[] = [];
+		let segMatch: RegExpExecArray | null;
+		while ((segMatch = segmentHeaderRegex.exec(stepContent)) !== null) {
+			const rawRepoId = segMatch[1].trim();
+			const repoId = normalizeSegmentRepoToken(rawRepoId);
+			segmentHeaders.push({
+				index: segMatch.index,
+				repoId,
+				rawRepoId,
+			});
+		}
+
+		const segments: SegmentCheckboxGroup[] = [];
+
+		if (segmentHeaders.length === 0) {
+			// No segment markers — all checkboxes belong to fallback repo
+			const checkboxes = extractCheckboxes(stepContent);
+			segments.push({ repoId: fallbackRepoId, checkboxes });
+			// Don't set hasExplicitMarkers — this is a fallback, not an explicit marker
+		} else {
+			hasExplicitMarkers = true;
+			// Check for checkboxes before the first segment header (pre-segment)
+			const preSegmentContent = stepContent.slice(0, segmentHeaders[0].index);
+			const preCheckboxes = extractCheckboxes(preSegmentContent);
+			if (preCheckboxes.length > 0) {
+				segments.push({ repoId: fallbackRepoId, checkboxes: preCheckboxes });
+			}
+
+			// Track seen repoIds for duplicate detection
+			// Include fallback repo if pre-segment checkboxes exist and it's a concrete ID
+			const seenRepoIds = new Set<string>();
+			if (preCheckboxes.length > 0 && fallbackRepoId !== SEGMENT_FALLBACK_REPO_PLACEHOLDER) {
+				seenRepoIds.add(fallbackRepoId);
+			}
+			let hasDuplicateError = false;
+
+			for (let j = 0; j < segmentHeaders.length; j++) {
+				const seg = segmentHeaders[j];
+
+				// Validate repo ID format (warning only — keep checkboxes for safety)
+				if (!SEGMENT_REPO_ID_PATTERN.test(seg.repoId)) {
+					warnings.push({
+						code: "SEGMENT_STEP_REPO_INVALID",
+						message:
+							`Task ${taskId} Step ${header.stepNumber} has invalid segment repo ID "${seg.rawRepoId}". ` +
+							`Repo IDs must match /^[a-z0-9][a-z0-9-]*$/.`,
+						taskId,
+					});
+					// Still extract checkboxes — don't drop work
+				}
+
+				// Check for duplicates
+				if (seenRepoIds.has(seg.repoId)) {
+					errors.push({
+						code: "SEGMENT_STEP_DUPLICATE_REPO",
+						message:
+							`Task ${taskId} Step ${header.stepNumber} has duplicate segment repo ID "${seg.repoId}". ` +
+							`A repoId may appear at most once within a step.`,
+						taskId,
+					});
+					hasDuplicateError = true;
+					continue;
+				}
+				seenRepoIds.add(seg.repoId);
+
+				const nextSegIndex = j + 1 < segmentHeaders.length ? segmentHeaders[j + 1].index : stepContent.length;
+				const segContent = stepContent.slice(seg.index, nextSegIndex);
+				const checkboxes = extractCheckboxes(segContent);
+
+				if (checkboxes.length === 0) {
+					warnings.push({
+						code: "SEGMENT_STEP_EMPTY",
+						message:
+							`Task ${taskId} Step ${header.stepNumber} has empty segment "${seg.repoId}" with no checkboxes.`,
+						taskId,
+					});
+				}
+
+				segments.push({ repoId: seg.repoId, checkboxes });
+			}
+
+			if (hasDuplicateError) {
+				// Still add what we collected, but errors are flagged
+			}
+		}
+
+		mapping.push({
+			stepNumber: header.stepNumber,
+			stepName: header.stepName,
+			segments,
+		});
+	}
+
+	return { mapping, hasExplicitMarkers, warnings, errors };
+}
+
+/**
+ * Extract checkbox text lines from a content block.
+ * Matches `- [ ] text` and `- [x] text` patterns.
+ */
+function extractCheckboxes(content: string): string[] {
+	const checkboxes: string[] = [];
+	const lines = content.split(/\r?\n/);
+	for (const line of lines) {
+		const match = line.match(/^\s*-\s+\[[ x]\]\s+(.+)$/);
+		if (match) {
+			checkboxes.push(match[1].trim());
+		}
+	}
+	return checkboxes;
+}
+
+/**
+ * Parse a PROMPT.md file and extract orchestrator-relevant metadata.
+ *
+ * Required fields (hard fail if missing):
+ *   - Task ID: extracted from `# Task: XX-NNN - Name` heading OR from folder name
+ *
+ * Optional fields (defaults used if absent):
+ *   - Dependencies: defaults to [] (no dependencies)
+ *   - Review Level: defaults to 2
+ *   - Size: defaults to "M"
+ *   - File Scope: defaults to []
+ *   - Task Name: defaults to folder name
+ *
+ * Dependency syntax accepted:
+ *   - "**None**" or "None" → empty list
+ *   - "**Requires:** COMP-005 ..." → ["COMP-005"]
+ *   - "**Requires:** time-off/TO-014 ..." → ["time-off/TO-014"]
+ *   - "- COMP-005 (description)" → ["COMP-005"]
+ *   - "- **time-off/TO-014** — description" → ["time-off/TO-014"]
+ *   - Multiple bullet points → multiple dependencies
+ */
+export function parsePromptForOrchestrator(
+	promptPath: string,
+	taskFolder: string,
+	areaName: string,
+): { task: ParsedTask | null; error: DiscoveryError | null; warnings?: DiscoveryError[] } {
+	const folderName = basename(taskFolder);
+	let content: string;
+
+	try {
+		content = readFileSync(promptPath, "utf-8");
+	} catch {
+		return {
+			task: null,
+			error: {
+				code: "PARSE_MALFORMED",
+				message: `Cannot read PROMPT.md: ${promptPath}`,
+				taskPath: promptPath,
+			},
+		};
+	}
+
+	// ── Extract task ID ──────────────────────────────────────────
+	// Try from heading first: "# Task: COMP-006 - Pay Bands Implementation"
+	let taskId: string | null = null;
+	let taskName = folderName;
+
+	const headingMatch = content.match(/^#\s+Task:\s+([A-Z]+-\d+)\s*[-—]\s*(.+)$/m);
+	if (headingMatch) {
+		taskId = headingMatch[1];
+		taskName = headingMatch[2].trim();
+	}
+
+	// Fallback: extract from folder name
+	if (!taskId) {
+		taskId = extractTaskIdFromFolderName(folderName);
+	}
+
+	if (!taskId) {
+		return {
+			task: null,
+			error: {
+				code: "PARSE_MISSING_ID",
+				message: `Cannot extract task ID from heading or folder name "${folderName}" in ${promptPath}`,
+				taskPath: promptPath,
+			},
+		};
+	}
+
+	// ── Extract review level ─────────────────────────────────────
+	// "## Review Level: 1 (Plan Only)" or "## Review Level: 2"
+	let reviewLevel = 2;
+	const reviewMatch = content.match(/^##\s+Review Level:\s*(\d+)/m);
+	if (reviewMatch) {
+		reviewLevel = parseInt(reviewMatch[1], 10);
+	}
+
+	// ── Extract size ─────────────────────────────────────────────
+	// "**Size:** M" (usually near top, after Created date)
+	let size = "M";
+	const sizeMatch = content.match(/\*\*Size:\*\*\s*([SMLsml])/);
+	if (sizeMatch) {
+		size = sizeMatch[1].toUpperCase();
+	}
+
+	// ── Extract dependencies ─────────────────────────────────────
+	const dependencies: string[] = [];
+	const depSectionMatch = content.match(
+		/^##\s+Dependencies\s*\n([\s\S]*?)(?=\n##\s|\n---|\n$)/m,
+	);
+
+	if (depSectionMatch) {
+		const depBody = depSectionMatch[1].trim();
+
+		// Check for "None" variants
+		if (!/\*?\*?None\*?\*?/i.test(depBody) && depBody.length > 0) {
+			// Pattern 1: "**Requires:** COMP-005 ..." or "**Task:** TO-014 ..."
+			const labeledMatches = depBody.matchAll(
+				/\*?\*?(?:Requires|Task):?\*?\*?\s*((?:[a-z0-9-]+\/)?[A-Z]+-\d+)/gi,
+			);
+			for (const m of labeledMatches) {
+				const dep = normalizeDependencyReference(m[1]);
+				if (!dependencies.includes(dep)) dependencies.push(dep);
+			}
+
+			// Pattern 2: Bullet list "- COMP-005 ...", "- **time-off/TO-014** ..."
+			const bulletMatches = depBody.matchAll(
+				/^[\s-]*\*?\*?((?:[a-z0-9-]+\/)?[A-Z]+-\d+)\*?\*?/gim,
+			);
+			for (const m of bulletMatches) {
+				const dep = normalizeDependencyReference(m[1]);
+				if (!dependencies.includes(dep)) dependencies.push(dep);
+			}
+
+			// Pattern 3: Inline dependency references not caught above
+			if (dependencies.length === 0) {
+				const inlineMatches = depBody.matchAll(/\b((?:[a-z0-9-]+\/)?[A-Z]+-\d+)\b/gi);
+				for (const m of inlineMatches) {
+					const dep = parseDependencyReference(m[1]);
+					if (dep.taskId === taskId) continue; // Don't add self-references
+					const normalized = normalizeDependencyReference(m[1]);
+					if (!dependencies.includes(normalized)) {
+						dependencies.push(normalized);
+					}
+				}
+			}
+		}
+	}
+
+	// ── Extract execution target (repo ID) ──────────────────────
+	// Repo ID validation: lowercase alphanumeric + hyphens, starting with alnum
+	const REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+	let promptRepoId: string | undefined;
+
+	// Priority 1: Section-based "## Execution Target" with "Repo: <id>" line
+	// Capture everything from section header to the next heading or --- divider.
+	// We avoid \n$ (which in multiline mode matches blank lines) by using a two-pass
+	// approach: find the section start, then slice to the next section boundary.
+	const execTargetHeaderIdx = content.search(/^##\s+Execution Target\s*$/m);
+	let execTargetSectionBody: string | null = null;
+	if (execTargetHeaderIdx !== -1) {
+		const afterHeader = content.indexOf("\n", execTargetHeaderIdx);
+		if (afterHeader !== -1) {
+			const rest = content.slice(afterHeader + 1);
+			const nextSectionMatch = rest.search(/^##\s|^---/m);
+			execTargetSectionBody = nextSectionMatch !== -1
+				? rest.slice(0, nextSectionMatch)
+				: rest;
+		}
+	}
+	if (execTargetSectionBody !== null) {
+		// Match "Repo: api" or "**Repo:** api" or "Workspace: api" with whitespace
+		const repoLineMatch = execTargetSectionBody.match(
+			/^\s*\*?\*?(?:Repo|Workspace):?\*?\*?\s+(\S+)/mi,
+		);
+		if (repoLineMatch) {
+			const candidate = repoLineMatch[1].trim().toLowerCase();
+			if (REPO_ID_PATTERN.test(candidate)) {
+				promptRepoId = candidate;
+			}
+		}
+	}
+
+	// Priority 2 (fallback): Inline "**Repo:** <id>" or "**Workspace:** <id>" anywhere in content
+	if (!promptRepoId) {
+		const inlineRepoMatch = content.match(
+			/^\*\*(?:Repo|Workspace):\*\*\s+(\S+)/m,
+		);
+		if (inlineRepoMatch) {
+			const candidate = inlineRepoMatch[1].trim().toLowerCase();
+			if (REPO_ID_PATTERN.test(candidate)) {
+				promptRepoId = candidate;
+			}
+		}
+	}
+
+	// ── Extract file scope ───────────────────────────────────────
+	const fileScope: string[] = [];
+	const fileScopeMatch = content.match(
+		/^##\s+File Scope\s*\n([\s\S]*?)(?=\n##\s|\n---|\n$)/m,
+	);
+
+	if (fileScopeMatch) {
+		const scopeBody = fileScopeMatch[1].trim();
+		const scopeLines = scopeBody.split("\n");
+		for (const line of scopeLines) {
+			// "- extensions/task-orchestrator.ts" or "- `api-service/src/health.js`"
+			let trimmed = line.replace(/^[\s-*]+/, "").trim();
+			// Strip inline backticks: `path/to/file` → path/to/file
+			if (trimmed.startsWith("`") && trimmed.endsWith("`")) {
+				trimmed = trimmed.slice(1, -1);
+			}
+			if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("```")) {
+				fileScope.push(trimmed);
+			}
+		}
+	}
+
+	// ── 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;
+
+	// ── Parse step-segment mapping (Phase A, TP-173) ────────
+	// Use promptRepoId as fallback; if not set, use a placeholder
+	// sentinel that resolveTaskRouting replaces with the actual resolved repo.
+	const segFallbackRepo = promptRepoId || SEGMENT_FALLBACK_REPO_PLACEHOLDER;
+	const stepSegResult = parseStepSegmentMapping(content, taskId, segFallbackRepo);
+
+	// Duplicate repoId in a step is a hard error — fail the task.
+	if (stepSegResult.errors.length > 0) {
+		return {
+			task: null,
+			error: stepSegResult.errors[0],
+		};
+	}
+
+	// Only populate stepSegmentMap when PROMPT.md has explicit #### Segment: markers.
+	// The parser produces fallback entries (repoId = primary repo) even without markers,
+	// but those should NOT trigger segment-scoped mode — they exist only for validation.
+	const stepSegmentMap = stepSegResult.hasExplicitMarkers ? stepSegResult.mapping : undefined;
+
+	return {
+		task: {
+			taskId,
+			taskName,
+			reviewLevel,
+			size,
+			dependencies,
+			fileScope,
+			taskFolder: resolve(taskFolder),
+			promptPath: resolve(promptPath),
+			areaName,
+			status: "pending",
+			...(promptRepoId ? { promptRepoId } : {}),
+			...(explicitSegmentDag ? { explicitSegmentDag } : {}),
+			...(stepSegmentMap ? { stepSegmentMap } : {}),
+		},
+		error: null,
+		warnings: stepSegResult.warnings,
+	};
+}
+
+
+// ── Area Scanning ────────────────────────────────────────────────────
+
+/**
+ * Scan an area path for pending tasks.
+ *
+ * Lists immediate subdirectories only (no recursion).
+ * Skips "archive" directories and folders with .DONE files.
+ * Parses PROMPT.md in each remaining subdirectory.
+ */
+export function scanAreaForTasks(
+	areaPath: string,
+	areaName: string,
+): { tasks: ParsedTask[]; errors: DiscoveryError[] } {
+	const tasks: ParsedTask[] = [];
+	const errors: DiscoveryError[] = [];
+
+	const resolvedPath = resolve(areaPath);
+	if (!existsSync(resolvedPath)) {
+		errors.push({
+			code: "SCAN_ERROR",
+			message: `Area path does not exist: ${resolvedPath}`,
+			taskPath: resolvedPath,
+		});
+		return { tasks, errors };
+	}
+
+	let entries: string[];
+	try {
+		entries = readdirSync(resolvedPath);
+	} catch {
+		errors.push({
+			code: "SCAN_ERROR",
+			message: `Cannot read area directory: ${resolvedPath}`,
+			taskPath: resolvedPath,
+		});
+		return { tasks, errors };
+	}
+
+	for (const entry of entries) {
+		// Skip archive directory
+		if (entry.toLowerCase() === "archive") continue;
+
+		const entryPath = join(resolvedPath, entry);
+
+		// Only process directories
+		try {
+			if (!statSync(entryPath).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+
+		// Skip if .DONE exists (already complete)
+		if (existsSync(join(entryPath, ".DONE"))) continue;
+
+		// Skip if no PROMPT.md
+		const promptPath = join(entryPath, "PROMPT.md");
+		if (!existsSync(promptPath)) continue;
+
+		// Parse PROMPT.md
+		const result = parsePromptForOrchestrator(promptPath, entryPath, areaName);
+		if (result.error) {
+			errors.push(result.error);
+		}
+		if (result.warnings) {
+			errors.push(...result.warnings);
+		}
+		if (result.task) {
+			tasks.push(result.task);
+		}
+	}
+
+	return { tasks, errors };
+}
+
+
+// ── Completed Task Set ───────────────────────────────────────────────
+
+/**
+ * Build a set of completed task IDs by scanning:
+ * 1. archive/ subdirectories for .DONE markers
+ * 2. Active task folders that have .DONE files (caught during scanAreaForTasks skip)
+ *
+ * This set is used only for dependency resolution — completed tasks are never re-executed.
+ */
+export function buildCompletedTaskSet(areaPaths: string[]): Set<string> {
+	const completed = new Set<string>();
+
+	for (const areaPath of areaPaths) {
+		const resolvedPath = resolve(areaPath);
+		if (!existsSync(resolvedPath)) continue;
+
+		let entries: string[];
+		try {
+			entries = readdirSync(resolvedPath);
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			const entryPath = join(resolvedPath, entry);
+
+			try {
+				if (!statSync(entryPath).isDirectory()) continue;
+			} catch {
+				continue;
+			}
+
+			if (entry.toLowerCase() === "archive") {
+				// Scan archive subdirectories for completed tasks
+				let archiveEntries: string[];
+				try {
+					archiveEntries = readdirSync(entryPath);
+				} catch {
+					continue;
+				}
+				for (const archiveEntry of archiveEntries) {
+					const archiveFolderPath = join(entryPath, archiveEntry);
+					try {
+						if (!statSync(archiveFolderPath).isDirectory()) continue;
+					} catch {
+						continue;
+					}
+					// Only treat archive tasks as complete when .DONE marker exists
+					if (!existsSync(join(archiveFolderPath, ".DONE"))) continue;
+					const taskId = extractTaskIdFromFolderName(archiveEntry);
+					if (taskId) {
+						completed.add(taskId);
+					}
+				}
+			} else {
+				// Active folder with .DONE = completed
+				if (existsSync(join(entryPath, ".DONE"))) {
+					const taskId = extractTaskIdFromFolderName(entry);
+					if (taskId) {
+						completed.add(taskId);
+					}
+				}
+			}
+		}
+	}
+
+	return completed;
+}
+
+
+// ── Argument Resolution ──────────────────────────────────────────────
+
+/**
+ * Resolve command arguments into area scan paths and direct task folders.
+ *
+ * Accepts mixed arguments:
+ *   - "all" → all areas from task_areas
+ *   - area name → looked up in task_areas
+ *   - directory path → used as-is
+ *   - PROMPT.md path → single task (dirname used as task folder)
+ */
+export function resolveArguments(
+	args: string,
+	taskAreas: Record<string, TaskArea>,
+	cwd: string,
+): { areaScanPaths: string[]; directTaskFolders: string[]; errors: DiscoveryError[] } {
+	const areaScanPaths: string[] = [];
+	const directTaskFolders: string[] = [];
+	const errors: DiscoveryError[] = [];
+
+	const tokens = args.trim().split(/\s+/).filter(Boolean);
+
+	for (const token of tokens) {
+		if (token.toLowerCase() === "all") {
+			// Expand to all areas
+			for (const area of Object.values(taskAreas)) {
+				const fullPath = resolve(cwd, area.path);
+				if (!areaScanPaths.includes(fullPath)) {
+					areaScanPaths.push(fullPath);
+				}
+			}
+		} else if (taskAreas[token]) {
+			// Known area name
+			const fullPath = resolve(cwd, taskAreas[token].path);
+			if (!areaScanPaths.includes(fullPath)) {
+				areaScanPaths.push(fullPath);
+			}
+		} else if (
+			token.endsWith("PROMPT.md") &&
+			existsSync(resolve(cwd, token))
+		) {
+			// Single PROMPT.md file
+			directTaskFolders.push(resolve(cwd, dirname(token)));
+		} else if (existsSync(resolve(cwd, token))) {
+			// Directory path
+			const fullPath = resolve(cwd, token);
+			try {
+				if (statSync(fullPath).isDirectory()) {
+					if (!areaScanPaths.includes(fullPath)) {
+						areaScanPaths.push(fullPath);
+					}
+				} else {
+					errors.push({
+						code: "UNKNOWN_ARG",
+						message: `Not a directory or PROMPT.md file: ${token}`,
+					});
+				}
+			} catch {
+				errors.push({
+					code: "UNKNOWN_ARG",
+					message: `Cannot stat path: ${token}`,
+				});
+			}
+		} else {
+			errors.push({
+				code: "UNKNOWN_ARG",
+				message: `Unknown area, path, or file: "${token}"`,
+			});
+		}
+	}
+
+	return { areaScanPaths, directTaskFolders, errors };
+}
+
+export interface DiscoveryOptions {
+	refreshDependencies?: boolean;
+	dependencySource?: "prompt" | "agent";
+	useDependencyCache?: boolean;
+	/** Workspace config for repo routing (null/undefined = repo mode, no routing). */
+	workspaceConfig?: WorkspaceConfig | null;
+}
+
+export interface DependencyCacheFile {
+	version: number;
+	generatedAt: string;
+	source: string;
+	tasks: Record<string, string[]>;
+}
+
+export function normalizePathForCompare(p: string): string {
+	return resolve(p).replace(/\\/g, "/").toLowerCase();
+}
+
+export function isPathWithin(childPath: string, parentPath: string): boolean {
+	const child = normalizePathForCompare(childPath);
+	const parent = normalizePathForCompare(parentPath);
+	return child === parent || child.startsWith(`${parent}/`);
+}
+
+export function dedupeAndNormalizeDeps(deps: string[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const dep of deps) {
+		const norm = normalizeDependencyReference(dep);
+		if (!norm || seen.has(norm)) continue;
+		seen.add(norm);
+		out.push(norm);
+	}
+	return out;
+}
+
+export function loadAreaDependencyCache(areaPath: string): DependencyCacheFile | null {
+	const cachePath = join(areaPath, "dependencies.json");
+	if (!existsSync(cachePath)) return null;
+	try {
+		const raw = readFileSync(cachePath, "utf-8");
+		const parsed = JSON.parse(raw) as DependencyCacheFile;
+		if (!parsed || typeof parsed !== "object" || !parsed.tasks) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+
+export function writeAreaDependencyCache(
+	areaPath: string,
+	pending: Map<string, ParsedTask>,
+	source: "prompt" | "agent",
+): void {
+	const tasks: Record<string, string[]> = {};
+	for (const task of pending.values()) {
+		if (!isPathWithin(task.taskFolder, areaPath)) continue;
+		tasks[task.taskId] = dedupeAndNormalizeDeps(task.dependencies);
+	}
+
+	const cachePath = join(areaPath, "dependencies.json");
+	const payload: DependencyCacheFile = {
+		version: 1,
+		generatedAt: new Date().toISOString(),
+		source,
+		tasks,
+	};
+
+	try {
+		// Keep deterministic formatting for easy diffs
+		const json = JSON.stringify(payload, null, 2);
+		writeFileSync(cachePath, `${json}\n`, "utf-8");
+	} catch {
+		// Non-fatal: discovery should still succeed without cache persistence
+	}
+}
+
+export function applyDependenciesFromCache(
+	discovery: DiscoveryResult,
+	areaScanPaths: string[],
+): { applied: boolean } {
+	let applied = false;
+	for (const areaPath of areaScanPaths) {
+		const cache = loadAreaDependencyCache(areaPath);
+		if (!cache) continue;
+		for (const task of discovery.pending.values()) {
+			if (!isPathWithin(task.taskFolder, areaPath)) continue;
+			const cachedDeps = cache.tasks[task.taskId];
+			if (!cachedDeps) continue;
+			task.dependencies = dedupeAndNormalizeDeps(cachedDeps);
+			applied = true;
+		}
+	}
+	return { applied };
+}
+
+
+// ── Task Registry ────────────────────────────────────────────────────
+
+/**
+ * Build the full task registry: pending tasks + completed set.
+ *
+ * Enforces global uniqueness of task IDs across all areas.
+ * If duplicates are found, returns a fail-fast error listing all collision locations.
+ */
+export function buildTaskRegistry(
+	areaScanPaths: string[],
+	directTaskFolders: string[],
+	taskAreas: Record<string, TaskArea>,
+	cwd: string,
+): DiscoveryResult {
+	const pending = new Map<string, ParsedTask>();
+	const errors: DiscoveryError[] = [];
+
+	// Track all locations per task ID for duplicate detection
+	const idLocations = new Map<string, string[]>();
+
+	function trackId(taskId: string, location: string) {
+		const existing = idLocations.get(taskId) || [];
+		existing.push(location);
+		idLocations.set(taskId, existing);
+	}
+
+	// Resolve area names for scan paths
+	const areaNameByPath = new Map<string, string>();
+	for (const [name, area] of Object.entries(taskAreas)) {
+		areaNameByPath.set(resolve(cwd, area.path), name);
+	}
+
+	// 1. Scan area paths for pending tasks
+	for (const areaPath of areaScanPaths) {
+		const areaName = areaNameByPath.get(areaPath) || basename(areaPath);
+		const result = scanAreaForTasks(areaPath, areaName);
+		errors.push(...result.errors);
+
+		for (const task of result.tasks) {
+			trackId(task.taskId, task.promptPath);
+			pending.set(task.taskId, task);
+		}
+	}
+
+	// 2. Process direct task folders (single PROMPT.md files)
+	for (const taskFolder of directTaskFolders) {
+		const promptPath = join(taskFolder, "PROMPT.md");
+		if (!existsSync(promptPath)) {
+			errors.push({
+				code: "SCAN_ERROR",
+				message: `No PROMPT.md found in direct task folder: ${taskFolder}`,
+				taskPath: taskFolder,
+			});
+			continue;
+		}
+
+		// Try to determine area name from path
+		let areaName = "unknown";
+		for (const [name, area] of Object.entries(taskAreas)) {
+			const resolvedAreaPath = resolve(cwd, area.path);
+			if (taskFolder.startsWith(resolvedAreaPath)) {
+				areaName = name;
+				break;
+			}
+		}
+
+		// Skip if .DONE exists
+		if (existsSync(join(taskFolder, ".DONE"))) continue;
+
+		const result = parsePromptForOrchestrator(promptPath, taskFolder, areaName);
+		if (result.error) {
+			errors.push(result.error);
+		}
+		if (result.warnings) {
+			errors.push(...result.warnings);
+		}
+		if (result.task) {
+			trackId(result.task.taskId, result.task.promptPath);
+			pending.set(result.task.taskId, result.task);
+		}
+	}
+
+	// 3. Build completed task set from all scanned areas
+	const completed = buildCompletedTaskSet(areaScanPaths);
+
+	// Also scan all task_areas for completed tasks (needed for cross-area dep resolution)
+	const allAreaPaths = Object.values(taskAreas).map((a) => resolve(cwd, a.path));
+	const globalCompleted = buildCompletedTaskSet(allAreaPaths);
+	for (const id of globalCompleted) {
+		completed.add(id);
+	}
+
+	// 4. Check for duplicate task IDs (global uniqueness enforcement)
+	for (const [taskId, locations] of idLocations) {
+		if (locations.length > 1) {
+			errors.push({
+				code: "DUPLICATE_ID",
+				message:
+					`Duplicate task ID "${taskId}" found in ${locations.length} locations:\n` +
+					locations.map((l) => `  - ${l}`).join("\n"),
+				taskId,
+			});
+		}
+	}
+
+	return { pending, completed, errors };
+}
+
+
+// ── Cross-Area Dependency Resolution ─────────────────────────────────
+
+/** Candidate match for a dependency reference found in task areas. */
+export interface DependencyCandidate {
+	areaName: string;
+	path: string;
+	status: "pending" | "complete";
+}
+
+export function findDependencyCandidates(
+	depRef: DependencyRef,
+	taskAreas: Record<string, TaskArea>,
+	cwd: string,
+): DependencyCandidate[] {
+	const candidates: DependencyCandidate[] = [];
+	const sortedAreas = Object.entries(taskAreas).sort((a, b) => a[0].localeCompare(b[0]));
+
+	for (const [areaName, area] of sortedAreas) {
+		if (depRef.areaName && depRef.areaName !== areaName.toLowerCase()) {
+			continue;
+		}
+
+		const areaPath = resolve(cwd, area.path);
+		if (!existsSync(areaPath)) continue;
+
+		let entries: string[];
+		try {
+			entries = readdirSync(areaPath);
+		} catch {
+			continue;
+		}
+
+		// Active tasks (skip archive)
+		for (const entry of entries) {
+			if (entry.toLowerCase() === "archive") continue;
+			const entryTaskId = extractTaskIdFromFolderName(entry);
+			if (entryTaskId !== depRef.taskId) continue;
+
+			const entryPath = join(areaPath, entry);
+			try {
+				if (!statSync(entryPath).isDirectory()) continue;
+			} catch {
+				continue;
+			}
+
+			candidates.push({
+				areaName,
+				path: entryPath,
+				status: existsSync(join(entryPath, ".DONE")) ? "complete" : "pending",
+			});
+		}
+
+		// Archived tasks (require .DONE marker)
+		const archivePath = join(areaPath, "archive");
+		if (!existsSync(archivePath)) continue;
+		try {
+			const archiveEntries = readdirSync(archivePath);
+			for (const archiveEntry of archiveEntries) {
+				const entryTaskId = extractTaskIdFromFolderName(archiveEntry);
+				if (entryTaskId !== depRef.taskId) continue;
+
+				const archiveTaskPath = join(archivePath, archiveEntry);
+				candidates.push({
+					areaName,
+					path: archiveTaskPath,
+					status: existsSync(join(archiveTaskPath, ".DONE")) ? "complete" : "pending",
+				});
+			}
+		} catch {
+			// Ignore archive read errors for discovery resilience
+		}
+	}
+
+	return candidates;
+}
+
+/**
+ * Resolve dependencies for all pending tasks.
+ *
+ * Supports both dependency formats:
+ * - TASK-ID (unqualified)
+ * - area-name/TASK-ID (area-qualified)
+ */
+export function resolveDependencies(
+	discovery: DiscoveryResult,
+	taskAreas: Record<string, TaskArea>,
+	cwd: string,
+): DiscoveryError[] {
+	const errors: DiscoveryError[] = [];
+
+	for (const [taskId, task] of discovery.pending) {
+		for (const depRaw of task.dependencies) {
+			const depRef = parseDependencyReference(depRaw);
+			const depId = depRef.taskId;
+
+			// Fast path for unqualified refs already in registry
+			if (!depRef.areaName) {
+				if (discovery.pending.has(depId)) continue;
+				if (discovery.completed.has(depId)) continue;
+			} else {
+				const pendingTask = discovery.pending.get(depId);
+				if (pendingTask && pendingTask.areaName.toLowerCase() === depRef.areaName) {
+					continue;
+				}
+			}
+
+			const candidates = findDependencyCandidates(depRef, taskAreas, cwd);
+
+			if (candidates.length === 0) {
+				errors.push({
+					code: "DEP_UNRESOLVED",
+					message: `${taskId} depends on ${depRaw} which does not exist in any task area`,
+					taskId,
+					taskPath: task.promptPath,
+				});
+				continue;
+			}
+
+			if (!depRef.areaName && candidates.length > 1) {
+				const options = candidates
+					.map((c) => `  - ${c.areaName}/${depId} [${c.status}] (${c.path})`)
+					.join("\n");
+				errors.push({
+					code: "DEP_AMBIGUOUS",
+					message:
+						`${taskId} depends on ${depId}, but multiple tasks match across areas. ` +
+						`Use an area-qualified dependency (area/${depId}).\n${options}`,
+					taskId,
+					taskPath: task.promptPath,
+				});
+				continue;
+			}
+
+			if (depRef.areaName && candidates.length > 1) {
+				const options = candidates
+					.map((c) => `  - ${c.areaName}/${depId} [${c.status}] (${c.path})`)
+					.join("\n");
+				errors.push({
+					code: "DEP_AMBIGUOUS",
+					message:
+						`${taskId} depends on ${depRaw}, but multiple matching task folders were found. ` +
+						`Resolve duplicate task IDs.\n${options}`,
+					taskId,
+					taskPath: task.promptPath,
+				});
+				continue;
+			}
+
+			const match = candidates[0];
+			if (match.status === "complete") {
+				discovery.completed.add(depId);
+				continue;
+			}
+
+			errors.push({
+				code: "DEP_PENDING",
+				message:
+					`${taskId} depends on ${depRaw} which is pending in "${match.areaName}". ` +
+					`Include that area: /orch ${match.areaName}`,
+				taskId,
+				taskPath: task.promptPath,
+			});
+		}
+	}
+
+	return errors;
+}
+
+
+// ── Task-to-Repo Routing ─────────────────────────────────────────────
+
+/** Repo ID validation: lowercase alphanumeric + hyphens, starting with alnum */
+const ROUTING_REPO_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Resolve the target repo for each discovered task using the routing
+ * precedence chain:
+ *
+ *   1. `task.promptRepoId` — declared in PROMPT.md metadata
+ *   2. `taskArea.repoId` — area-level config from task-runner.yaml
+ *   3. `workspaceConfig.routing.defaultRepo` — workspace-level default
+ *
+ * Only applied in workspace mode (when `workspaceConfig` is provided).
+ * In repo mode this function is never called.
+ *
+ * Returns an array of DiscoveryError for routing failures:
+ *   - TASK_REPO_UNRESOLVED: no source provided a repo ID
+ *   - TASK_REPO_UNKNOWN: resolved repo ID is not in workspace repos map
+ */
+export function resolveTaskRouting(
+	discovery: DiscoveryResult,
+	taskAreas: Record<string, TaskArea>,
+	workspaceConfig: WorkspaceConfig,
+): DiscoveryError[] {
+	const errors: DiscoveryError[] = [];
+	const validRepoIds = workspaceConfig.repos;
+	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
+		// workspace-default fallbacks are NOT used for resolution.
+		if (strictMode && !task.promptRepoId) {
+			errors.push({
+				code: "TASK_ROUTING_STRICT",
+				message:
+					`Task ${task.taskId} has no explicit execution target, but strict routing is enabled ` +
+					`(routing.strict: true in workspace config). ` +
+					`Add an execution target to the task's PROMPT.md:\n` +
+					`\n` +
+					`  ## Execution Target\n` +
+					`\n` +
+					`  Repo: <repo-id>\n` +
+					`\n` +
+					`Available repos: ${[...validRepoIds.keys()].join(", ")}`,
+				taskId: task.taskId,
+				taskPath: task.promptPath,
+			});
+			continue;
+		}
+
+		// Precedence 1: prompt-declared repo
+		let resolvedId = task.promptRepoId;
+		let source = "prompt";
+
+		// Precedence 2: area-level repo
+		if (!resolvedId) {
+			const area = taskAreas[task.areaName];
+			if (area?.repoId) {
+				const candidate = area.repoId.trim().toLowerCase();
+				if (ROUTING_REPO_ID_PATTERN.test(candidate)) {
+					resolvedId = candidate;
+					source = "area";
+				}
+			}
+		}
+
+		// Precedence 3: file scope inference — match file path prefixes against
+		// known workspace repo IDs. If file scope entries like "web-client/src/..."
+		// start with a repo name, route the task to that repo.
+		if (!resolvedId && task.fileScope && task.fileScope.length > 0) {
+			const repoIds = [...validRepoIds.keys()];
+			const repoCounts = new Map<string, number>();
+			for (const filePath of task.fileScope) {
+				const normalized = filePath.replace(/\\/g, "/");
+				for (const repoId of repoIds) {
+					if (normalized.startsWith(repoId + "/") || normalized === repoId) {
+						repoCounts.set(repoId, (repoCounts.get(repoId) || 0) + 1);
+						break; // first matching repo wins for this path
+					}
+				}
+			}
+			// Use the repo with the most file scope matches (majority vote)
+			if (repoCounts.size === 1) {
+				resolvedId = repoCounts.keys().next().value!;
+				source = "file-scope";
+			} else if (repoCounts.size > 1) {
+				// Multiple repos in file scope — pick the one with most entries.
+				// (Future: #51 will handle multi-repo tasks properly)
+				let maxCount = 0;
+				for (const [repoId, count] of repoCounts) {
+					if (count > maxCount) {
+						maxCount = count;
+						resolvedId = repoId;
+					}
+				}
+				source = "file-scope";
+			}
+		}
+
+		// Precedence 4: workspace default repo
+		if (!resolvedId) {
+			resolvedId = workspaceConfig.routing.defaultRepo;
+			source = "default";
+		}
+
+		// Validate resolution
+		if (!resolvedId) {
+			errors.push({
+				code: "TASK_REPO_UNRESOLVED",
+				message:
+					`Task ${task.taskId} has no resolved repo. ` +
+					`Add file scope paths prefixed with the repo name (e.g., "web-client/src/..."), ` +
+					`set repo_id on area "${task.areaName}", ` +
+					`or set routing.default_repo in the workspace config.`,
+				taskId: task.taskId,
+				taskPath: task.promptPath,
+			});
+			continue;
+		}
+
+		if (!validRepoIds.has(resolvedId)) {
+			errors.push({
+				code: "TASK_REPO_UNKNOWN",
+				message:
+					`Task ${task.taskId} resolved to repo "${resolvedId}" (via ${source}), ` +
+					`but no repo with that ID exists in the workspace config. ` +
+					`Known repos: ${[...validRepoIds.keys()].join(", ")}`,
+				taskId: task.taskId,
+				taskPath: task.promptPath,
+			});
+			continue;
+		}
+
+		// Attach resolved repo to the task
+		task.resolvedRepoId = resolvedId;
+
+		// ── Step-segment mapping: resolve placeholders and validate repo IDs (TP-173) ──
+		if (task.stepSegmentMap) {
+			const knownRepoList = [...validRepoIds.keys()].join(", ");
+			for (const step of task.stepSegmentMap) {
+				for (const seg of step.segments) {
+					// Replace placeholder with resolved primary repo
+					if (seg.repoId === SEGMENT_FALLBACK_REPO_PLACEHOLDER) {
+						seg.repoId = resolvedId;
+						continue;
+					}
+					// Validate explicit segment repoIds against workspace repos
+					if (!validRepoIds.has(seg.repoId)) {
+						const knownRepos = [...validRepoIds.keys()];
+						const suggestions = suggestRepoMatches(seg.repoId, knownRepos);
+						const suggestionHint = suggestions.length > 0
+							? ` Did you mean: ${suggestions.join(", ")}?`
+							: "";
+						errors.push({
+							code: "SEGMENT_STEP_REPO_INVALID",
+							message:
+								`Task ${task.taskId} Step ${step.stepNumber} has segment repo "${seg.repoId}" ` +
+								`which is not in the workspace config. Known repos: ${knownRepoList}.${suggestionHint}`,
+							taskId: task.taskId,
+							taskPath: task.promptPath,
+						});
+					}
+				}
+				// Duplicate detection for post-placeholder resolution is handled
+				// by the shared pass in runDiscovery() (Step 7).
+			}
+		}
+	}
+
+	return errors;
+}
+
+
+// ── Discovery Pipeline (Public) ──────────────────────────────────────
+
+/**
+ * Run the full discovery pipeline:
+ * 1. Resolve arguments to scan paths and direct task folders
+ * 2. Build task registry (scan, parse, deduplicate)
+ * 3. Resolve cross-area dependencies
+ *
+ * Returns a DiscoveryResult with pending tasks, completed set, and any errors.
+ */
+export function runDiscovery(
+	args: string,
+	taskAreas: Record<string, TaskArea>,
+	cwd: string,
+	options: DiscoveryOptions = {},
+): DiscoveryResult {
+	const dependencySource = options.dependencySource ?? "prompt";
+	const useDependencyCache = options.useDependencyCache ?? false;
+	const refreshDependencies = options.refreshDependencies ?? false;
+
+	// Step 1: Resolve arguments
+	const resolved = resolveArguments(args, taskAreas, cwd);
+	if (resolved.errors.length > 0) {
+		return {
+			pending: new Map(),
+			completed: new Set(),
+			errors: resolved.errors,
+		};
+	}
+
+	if (resolved.areaScanPaths.length === 0 && resolved.directTaskFolders.length === 0) {
+		return {
+			pending: new Map(),
+			completed: new Set(),
+			errors: [
+				{
+					code: "UNKNOWN_ARG",
+					message: "No valid areas, paths, or PROMPT.md files found in arguments",
+				},
+			],
+		};
+	}
+
+	// Step 2: Build task registry (prompt-parsed dependencies as baseline)
+	const discovery = buildTaskRegistry(
+		resolved.areaScanPaths,
+		resolved.directTaskFolders,
+		taskAreas,
+		cwd,
+	);
+
+	// If we have duplicate ID errors, stop early (fail-fast)
+	const duplicateErrors = discovery.errors.filter((e) => e.code === "DUPLICATE_ID");
+	if (duplicateErrors.length > 0) {
+		return discovery;
+	}
+
+	// Step 3: Dependency source + cache policy
+	// TS-004 scaffold supports prompt parsing and cached dependency maps.
+	// Agent-based analysis is deferred to later tasks; when selected, we
+	// attempt cache first and fall back to prompt parsing if unavailable.
+	let effectiveDependencySource: "prompt" | "agent" = dependencySource;
+	if (useDependencyCache && !refreshDependencies) {
+		const { applied } = applyDependenciesFromCache(discovery, resolved.areaScanPaths);
+		if (dependencySource === "agent" && !applied) {
+			effectiveDependencySource = "prompt";
+			discovery.errors.push({
+				code: "DEP_SOURCE_FALLBACK",
+				message:
+					"dependencies.source=agent requested, but no dependency cache was found for " +
+					"the selected areas. Falling back to PROMPT.md dependencies.",
+			});
+		}
+	} else if (dependencySource === "agent") {
+		effectiveDependencySource = "prompt";
+		discovery.errors.push({
+			code: "DEP_SOURCE_FALLBACK",
+			message:
+				"dependencies.source=agent requested, but agent-based dependency analysis " +
+				"is not implemented in TS-004 scaffold. Falling back to PROMPT.md dependencies.",
+		});
+	}
+
+	// Step 4: Resolve cross-area dependencies using effective dependencies
+	const depErrors = resolveDependencies(discovery, taskAreas, cwd);
+	discovery.errors.push(...depErrors);
+
+	// Step 5: Persist cache (if enabled) for next run / non-refresh runs
+	if (useDependencyCache) {
+		for (const areaPath of resolved.areaScanPaths) {
+			writeAreaDependencyCache(areaPath, discovery.pending, effectiveDependencySource);
+		}
+	}
+
+	// Step 6: Task-to-repo routing (workspace mode only)
+	const workspaceConfig = options.workspaceConfig;
+	if (workspaceConfig && workspaceConfig.mode === "workspace") {
+		const routingErrors = resolveTaskRouting(discovery, taskAreas, workspaceConfig);
+		discovery.errors.push(...routingErrors);
+	} else {
+		// Repo mode: resolve any placeholder fallback repo IDs to "default"
+		// (single-repo mode has no workspace routing, so the placeholder
+		// must be normalized here for backward compatibility).
+		for (const task of discovery.pending.values()) {
+			if (!task.stepSegmentMap) continue;
+			for (const step of task.stepSegmentMap) {
+				for (const seg of step.segments) {
+					if (seg.repoId === SEGMENT_FALLBACK_REPO_PLACEHOLDER) {
+						seg.repoId = "default";
+					}
+				}
+			}
+		}
+	}
+
+	// Step 7: Post-normalization duplicate segment detection (TP-173)
+	// After all placeholder resolution (workspace or repo mode), check each
+	// step for duplicate repoIds that may have emerged from placeholder → real ID.
+	for (const task of discovery.pending.values()) {
+		if (!task.stepSegmentMap) continue;
+		for (const step of task.stepSegmentMap) {
+			const stepRepoIds = step.segments.map(s => s.repoId);
+			const seen = new Set<string>();
+			for (const rid of stepRepoIds) {
+				if (seen.has(rid)) {
+					discovery.errors.push({
+						code: "SEGMENT_STEP_DUPLICATE_REPO",
+						message:
+							`Task ${task.taskId} Step ${step.stepNumber} has duplicate segment repo ID "${rid}" ` +
+							`(after resolving primary repo fallback). A repoId may appear at most once within a step.`,
+						taskId: task.taskId,
+						taskPath: task.promptPath,
+					});
+					break;
+				}
+				seen.add(rid);
+			}
+		}
+	}
+
+	return discovery;
+}
+
+/**
+ * Format discovery results as a readable string for display.
+ */
+export function formatDiscoveryResults(result: DiscoveryResult): string {
+	const lines: string[] = [];
+
+	// Summary
+	lines.push(`📋 Discovery Results`);
+	lines.push(`   Pending tasks:   ${result.pending.size}`);
+	lines.push(`   Completed tasks: ${result.completed.size}`);
+	lines.push("");
+
+	// List pending tasks grouped by area (deterministic: sorted by area name, then task ID)
+	if (result.pending.size > 0) {
+		const byArea = new Map<string, ParsedTask[]>();
+		for (const task of result.pending.values()) {
+			const existing = byArea.get(task.areaName) || [];
+			existing.push(task);
+			byArea.set(task.areaName, existing);
+		}
+
+		lines.push("Pending Tasks:");
+		const sortedAreas = [...byArea.entries()].sort((a, b) =>
+			a[0].localeCompare(b[0]),
+		);
+		for (const [area, tasks] of sortedAreas) {
+			lines.push(`  ${area}:`);
+			const sortedTasks = [...tasks].sort((a, b) =>
+				a.taskId.localeCompare(b.taskId),
+			);
+			for (const task of sortedTasks) {
+				const deps =
+					task.dependencies.length > 0
+						? ` → depends on: ${task.dependencies.join(", ")}`
+						: "";
+				const repo =
+					task.resolvedRepoId
+						? ` → repo: ${task.resolvedRepoId}`
+						: "";
+				lines.push(
+					`    ${task.taskId} [${task.size}] ${task.taskName}${deps}${repo}`,
+				);
+			}
+		}
+		lines.push("");
+	}
+
+	// Show errors
+	if (result.errors.length > 0) {
+		const fatalCodes = new Set<string>(FATAL_DISCOVERY_CODES);
+		const fatalErrors = result.errors.filter((e) => fatalCodes.has(e.code));
+		const warnings = result.errors.filter((e) => !fatalCodes.has(e.code));
+
+		if (fatalErrors.length > 0) {
+			lines.push("❌ Errors:");
+			for (const err of fatalErrors) {
+				lines.push(`  [${err.code}] ${err.message}`);
+			}
+			lines.push("");
+		}
+
+		if (warnings.length > 0) {
+			lines.push("⚠️  Warnings:");
+			for (const err of warnings) {
+				lines.push(`  [${err.code}] ${err.message}`);
+			}
+			lines.push("");
+		}
+	}
+
+	return lines.join("\n");
+}
+