/**
 * 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+)/im,
		);
		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 ────────────────────────────────────────────────────

/**
 * TP-196 / #462 — Discovery safeguard for `.DONE` authority drift.
 *
 * Discovery has no access to persisted segment state, so it cannot make a
 * hard `.DONE` vs. segment-frontier authority decision (that lives in the
 * monitor/resume guards). What it CAN do cheaply is detect the most common
 * symptom of a stale or premature `.DONE`: a `.DONE` file exists alongside
 * a STATUS.md that still has unchecked checkboxes. When that pattern is
 * found, emit a one-line `console.warn` so operators see the inconsistency
 * during scan. Behaviour of `scanAreaForTasks` is unchanged — the task is
 * still skipped — this is a doctor-style warning only.
 *
 * Returns `true` when the safeguard issued a warning (used by tests).
 */
export function checkDoneAuthoritySafeguard(
	taskFolder: string,
	logger: (msg: string) => void = console.warn,
): boolean {
	const statusPath = join(taskFolder, "STATUS.md");
	if (!existsSync(statusPath)) return false;
	let content: string;
	try {
		content = readFileSync(statusPath, "utf-8");
	} catch {
		return false;
	}
	// Look for any unchecked checkbox `- [ ]` on its own line.
	const hasUnchecked = /^\s*-\s*\[\s\]\s+/m.test(content);
	if (!hasUnchecked) return false;
	logger(
		`[discovery] WARN: .DONE present in ${taskFolder} but STATUS.md contains unchecked checkboxes — possible stale/premature .DONE (#462 safeguard).`,
	);
	return true;
}

/**
 * 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).
		// TP-196 / #462: doctor-style safeguard — if .DONE coexists with
		// unchecked checkboxes in STATUS.md, warn so operators can investigate
		// before the task is silently treated as complete.
		if (existsSync(join(entryPath, ".DONE"))) {
			checkDoneAuthoritySafeguard(entryPath);
			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");
}