omegon 0.6.0

package/extensions/cleave/workspace.ts

@@ -0,0 +1,861 @@
+/**
+ * cleave/workspace — Lightweight workspace management.
+ *
+ * Creates and manages workspace directories under ~/.pi/cleave/ containing:
+ * - state.json: serialized CleaveState
+ * - {n}-task.md: child task files
+ *
+ * Workspaces live outside the target repo to avoid polluting the working tree.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ChildPlan, CleaveState, SplitPlan } from "./types.ts";
+import type { OpenSpecContext } from "./openspec.ts";
+import { discoverGuardrails } from "./guardrails.ts";
+import type { GuardrailCheck } from "./guardrails.ts";
+
+// ─── Guardrail Section ─────────────────────────────────────────────────────
+
+/**
+ * Build a guardrail section for child task files.
+ *
+ * Discovers project guardrails (typecheck, lint, etc.) and generates
+ * a markdown section instructing the child to run them before reporting success.
+ *
+ * @param cwd - Project root directory to discover guardrails from
+ * @returns Markdown section string, or empty string if no guardrails found
+ */
+export function buildGuardrailSection(cwd: string): string {
+	const checks = discoverGuardrails(cwd);
+	if (checks.length === 0) return "";
+
+	const lines = [
+		"",
+		"## Project Guardrails",
+		"",
+		"Before reporting success, run these deterministic checks and fix any failures:",
+		"",
+	];
+
+	for (let i = 0; i < checks.length; i++) {
+		lines.push(`${i + 1}. **${checks[i].name}**: \`${checks[i].cmd}\``);
+	}
+
+	lines.push("");
+	lines.push("Include command output in the Verification section. If any check fails, fix the errors before completing your task.");
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+// ─── Skill Directives ──────────────────────────────────────────────────────
+
+/**
+ * A resolved skill directive — skill name and absolute path to its SKILL.md.
+ * Used to inject skill reading instructions into child task files.
+ */
+export interface SkillDirective {
+	skill: string;
+	path: string;
+}
+
+/** Base directory for all cleave workspaces. */
+const CLEAVE_HOME = join(homedir(), ".pi", "cleave");
+
+/**
+ * Generate a unique workspace directory path from a directive.
+ *
+ * Creates a human-readable path: ~/.pi/cleave/add-jwt-auth/
+ * Appends numeric suffix if collision: ~/.pi/cleave/add-jwt-auth-2/
+ */
+export function generateWorkspacePath(directive: string): string {
+	mkdirSync(CLEAVE_HOME, { recursive: true });
+
+	let slug = directive
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, "")
+		.replace(/[\s_]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+
+	if (slug.length > 40) slug = slug.slice(0, 40).replace(/-$/, "");
+	if (!slug) slug = "task";
+
+	let candidate = join(CLEAVE_HOME, slug);
+	if (!existsSync(candidate)) return candidate;
+
+	let counter = 2;
+	while (existsSync(join(CLEAVE_HOME, `${slug}-${counter}`))) counter++;
+	return join(CLEAVE_HOME, `${slug}-${counter}`);
+}
+
+/**
+ * Initialize a cleave workspace directory.
+ *
+ * Creates the workspace directory, state.json, and child task files.
+ * Workspace lives under ~/.pi/cleave/, not inside the target repo.
+ *
+ * @param resolvedSkills - Pre-resolved skill directives per child index.
+ *   Generated by resolveSkillPaths() from skills.ts.
+ */
+export function initWorkspace(
+	state: CleaveState,
+	plan: SplitPlan,
+	repoPath: string,
+	openspecContext?: OpenSpecContext | null,
+	resolvedSkills?: Map<number, SkillDirective[]>,
+): string {
+	const wsPath = generateWorkspacePath(state.directive);
+	mkdirSync(wsPath, { recursive: true });
+
+	state.workspacePath = wsPath;
+
+	// Write initial state
+	saveState(state);
+
+	// Pre-compute scenario assignments across all children (orphan detection)
+	const scenarioAssignments = matchScenariosToChildren(plan.children, openspecContext);
+
+	// Discover guardrails once, reuse for all children
+	const guardrailSection = buildGuardrailSection(repoPath);
+
+	// Generate child task files
+	for (let i = 0; i < plan.children.length; i++) {
+		const child = plan.children[i];
+		const childScenarios = scenarioAssignments.get(i) ?? [];
+		const childSkillDirectives = resolvedSkills?.get(i) ?? [];
+		const taskContent = generateTaskFile(i, child, plan.children, state.directive, openspecContext, childScenarios, childSkillDirectives, guardrailSection);
+		writeFileSync(join(wsPath, `${i}-task.md`), taskContent, "utf-8");
+	}
+
+	return wsPath;
+}
+
+/** Persist CleaveState to workspace/state.json */
+export function saveState(state: CleaveState): void {
+	if (!state.workspacePath) throw new Error("Cannot save state: workspacePath not set");
+	const statePath = join(state.workspacePath, "state.json");
+	writeFileSync(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+
+/** Load CleaveState from workspace/state.json */
+export function loadState(workspacePath: string): CleaveState {
+	const statePath = join(workspacePath, "state.json");
+	if (!existsSync(statePath)) {
+		throw new Error(`State file not found: ${statePath}`);
+	}
+	return JSON.parse(readFileSync(statePath, "utf-8"));
+}
+
+/**
+ * Scan ~/.pi/cleave/ for workspaces whose phase is still "dispatch" — i.e.
+ * runs that were interrupted before the harvest/merge phase completed.
+ *
+ * If `repoPath` is provided only runs matching that repo are returned.
+ * Results are sorted newest-first by `createdAt`.
+ */
+export function findIncompleteRuns(repoPath?: string): CleaveState[] {
+	if (!existsSync(CLEAVE_HOME)) return [];
+	const entries = readdirSync(CLEAVE_HOME, { withFileTypes: true });
+	const results: CleaveState[] = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const statePath = join(CLEAVE_HOME, entry.name, "state.json");
+		if (!existsSync(statePath)) continue;
+		try {
+			const state: CleaveState = JSON.parse(readFileSync(statePath, "utf-8"));
+			if (state.phase !== "dispatch" && state.phase !== "harvest") continue;
+			if (repoPath && state.repoPath !== repoPath) continue;
+			results.push(state);
+		} catch {
+			// Corrupt state — skip
+		}
+	}
+	results.sort((a, b) => (b.createdAt ?? "").localeCompare(a.createdAt ?? ""));
+	return results;
+}
+
+/**
+ * Generate a child task markdown file.
+ *
+ * Slim template that the child agent reads to understand its mission.
+ * Includes optional Specialist Skills section (D2: directive injection)
+ * that instructs the child to read SKILL.md files for domain guidance.
+ */
+export function generateTaskFile(
+	taskId: number,
+	child: ChildPlan,
+	allChildren: ChildPlan[],
+	rootDirective: string,
+	openspecContext?: OpenSpecContext | null,
+	assignedScenarios?: AssignedScenario[],
+	skillDirectives?: SkillDirective[],
+	guardrailSection?: string,
+): string {
+	const siblingRefs = allChildren
+		.filter((_, i) => i !== taskId)
+		.map((c, i) => `${i >= taskId ? i + 1 : i}:${c.label}`)
+		.join(", ");
+
+	const scopeList = child.scope.length > 0
+		? child.scope.map((s) => `- \`${s}\``).join("\n")
+		: "- (entire scope defined by description)";
+
+	const depsNote = child.dependsOn.length > 0
+		? `**Depends on:** ${child.dependsOn.join(", ")}`
+		: "**Depends on:** none (independent)";
+
+	// Build optional skill section
+	const skillSection = buildSkillSection(skillDirectives);
+
+	// Build optional OpenSpec design context section
+	const designSection = buildDesignSection(child, openspecContext, assignedScenarios);
+
+	return `---
+task_id: ${taskId}
+label: ${child.label}
+siblings: [${siblingRefs}]
+---
+
+# Task ${taskId}: ${child.label}
+
+## Root Directive
+
+> ${rootDirective}
+
+## Mission
+
+${child.description}
+
+## Scope
+
+${scopeList}
+
+${depsNote}
+${skillSection}${designSection}${guardrailSection ?? ""}
+## Contract
+
+1. Only work on files within your scope
+2. Update the Result section below when done
+3. Commit your work with clear messages — do not push
+4. If the task is too complex, set status to NEEDS_DECOMPOSITION
+
+## Result
+
+**Status:** PENDING
+
+**Summary:**
+
+**Artifacts:**
+
+**Decisions Made:**
+
+**Assumptions:**
+
+**Interfaces Published:**
+
+**Verification:**
+- Command: \`\`
+- Output:
+- Edge cases:
+`;
+}
+
+/**
+ * Build the Specialist Skills section for a child task file.
+ *
+ * Per design D2: "Child prompt gets 'Before starting, read these skill files: ...'
+ * with paths. Skills are 200+ lines — inlining would bloat prompts."
+ *
+ * Returns empty string if no skills to inject.
+ */
+export function buildSkillSection(skillDirectives?: SkillDirective[]): string {
+	if (!skillDirectives || skillDirectives.length === 0) return "";
+
+	const lines = [
+		"",
+		"## Specialist Skills",
+		"",
+		"Before starting, read these skill files for domain-specific guidance:",
+		"",
+	];
+
+	for (const sd of skillDirectives) {
+		lines.push(`- **${sd.skill}**: \`${sd.path}\``);
+	}
+
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+// ─── Scenario Matching ──────────────────────────────────────────────────────
+
+export interface AssignedScenario {
+	domain: string;
+	requirement: string;
+	scenarios: string[];
+	/** Whether this was auto-injected as an orphan */
+	crossCutting: boolean;
+}
+
+/**
+ * Match spec scenarios to children using 3-tier priority:
+ * 1. Annotation match — child's specDomains (from <!-- specs: ... -->) includes the scenario domain
+ * 2. Scope match — child's file scope includes files referenced in the scenario
+ * 3. Word-overlap fallback — shared words between child description and scenario text
+ *
+ * Any scenario matching zero children is auto-injected into the best candidate
+ * with a cross-cutting marker.
+ *
+ * Returns a Map from child index to its assigned scenarios.
+ */
+export function matchScenariosToChildren(
+	children: ChildPlan[],
+	ctx?: OpenSpecContext | null,
+): Map<number, AssignedScenario[]> {
+	const result = new Map<number, AssignedScenario[]>();
+	for (let i = 0; i < children.length; i++) result.set(i, []);
+
+	if (!ctx || ctx.specScenarios.length === 0) return result;
+
+	for (const ss of ctx.specScenarios) {
+		const assigned = assignScenario(ss, children);
+
+		if (assigned.length > 0) {
+			// Matched via annotation, scope, or word overlap
+			for (const idx of assigned) {
+				result.get(idx)!.push({
+					domain: ss.domain,
+					requirement: ss.requirement,
+					scenarios: ss.scenarios,
+					crossCutting: false,
+				});
+			}
+		} else {
+			// Orphan — auto-inject into best candidate
+			const target = findOrphanTarget(ss, children);
+			result.get(target)!.push({
+				domain: ss.domain,
+				requirement: ss.requirement,
+				scenarios: ss.scenarios,
+				crossCutting: true,
+			});
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Assign a scenario to children using 3-tier priority.
+ * Returns array of child indices (may be multiple for annotation matches).
+ */
+function assignScenario(
+	ss: { domain: string; requirement: string; scenarios: string[] },
+	children: ChildPlan[],
+): number[] {
+	// Tier 1: Annotation match — child declared this spec domain
+	const annotationMatches = children
+		.map((c, i) => ({ idx: i, child: c }))
+		.filter(({ child }) =>
+			child.specDomains.some((d) => domainMatches(d, ss.domain)),
+		)
+		.map(({ idx }) => idx);
+
+	if (annotationMatches.length > 0) return annotationMatches;
+
+	// Tier 2: Scope match — scenario text references files in child's scope
+	const scenarioText = `${ss.requirement} ${ss.scenarios.join(" ")}`.toLowerCase();
+	const scopeMatches: number[] = [];
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		if (child.scope.length === 0) continue;
+		const hasMatch = child.scope.some((s) => {
+			const scopeClean = s.replace(/\*+/g, "").replace(/\/$/, "").toLowerCase();
+			const scopeParts = scopeClean.split("/");
+			const filename = scopeParts[scopeParts.length - 1];
+			if (filename.length <= 3) return false;
+			// Require word-boundary match to avoid "utils.py" matching "utility"
+			const pattern = new RegExp(`\\b${filename.replace(/\./g, "\\.")}\\b`);
+			return pattern.test(scenarioText);
+		});
+		if (hasMatch) scopeMatches.push(i);
+	}
+
+	if (scopeMatches.length > 0) return scopeMatches;
+
+	// Tier 3: Word-overlap fallback
+	const specText = `${ss.domain} ${ss.requirement}`.toLowerCase();
+	const specWords = specText.split(/\s+/).filter((w) => w.length > 3);
+
+	let bestIdx = -1;
+	let bestScore = 0;
+	for (let i = 0; i < children.length; i++) {
+		const childText = `${children[i].label} ${children[i].description}`.toLowerCase();
+		const score = specWords.filter((w) => childText.includes(w)).length;
+		if (score > bestScore) {
+			bestScore = score;
+			bestIdx = i;
+		}
+	}
+
+	return bestIdx >= 0 && bestScore > 0 ? [bestIdx] : [];
+}
+
+/**
+ * Find the best injection target for an orphan scenario.
+ * Priority: scope match on When clause → word overlap → last child.
+ */
+function findOrphanTarget(
+	ss: { domain: string; requirement: string; scenarios: string[] },
+	children: ChildPlan[],
+): number {
+	// Try to extract function/file references from When clauses
+	const whenText = ss.scenarios
+		.join("\n")
+		.split("\n")
+		.filter((l) => /^\s*when\s/i.test(l))
+		.join(" ")
+		.toLowerCase();
+
+	// Check which child's scope contains referenced files/functions
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		if (child.scope.length === 0) continue;
+		const hasMatch = child.scope.some((s) => {
+			const filename = s.replace(/\*+/g, "").split("/").pop()?.toLowerCase() ?? "";
+			return filename.length > 3 && whenText.includes(filename);
+		});
+		if (hasMatch) return i;
+	}
+
+	// Word overlap fallback
+	const scenarioText = `${ss.domain} ${ss.requirement}`.toLowerCase();
+	const words = scenarioText.split(/\s+/).filter((w) => w.length > 3);
+
+	let bestIdx = children.length - 1; // default: last child
+	let bestScore = 0;
+	for (let i = 0; i < children.length; i++) {
+		const childText = `${children[i].label} ${children[i].description}`.toLowerCase();
+		const score = words.filter((w) => childText.includes(w)).length;
+		if (score > bestScore) {
+			bestScore = score;
+			bestIdx = i;
+		}
+	}
+
+	return bestIdx;
+}
+
+/**
+ * Check if an annotation domain matches a scenario domain.
+ * Matches exact or parent/child relationships using path segments:
+ *   "relay" matches "relay/rbac" (parent of scenario domain)
+ *   "relay/rbac" matches "relay" (child of scenario domain)
+ *   "relay" does NOT match "relay-admin" (different segment)
+ */
+function domainMatches(annotationDomain: string, scenarioDomain: string): boolean {
+	if (annotationDomain === scenarioDomain) return true;
+	// Annotation is parent: "relay" matches scenario "relay/rbac"
+	if (scenarioDomain.startsWith(annotationDomain + "/")) return true;
+	// Annotation is child: "relay/rbac" matches scenario "relay"
+	if (annotationDomain.startsWith(scenarioDomain + "/")) return true;
+	return false;
+}
+
+// ─── Design Section Builder ─────────────────────────────────────────────────
+
+/**
+ * Build the optional "Design Context" section for a child task file.
+ *
+ * Uses pre-computed scenario assignments (from matchScenariosToChildren)
+ * instead of per-child heuristic matching.
+ */
+function buildDesignSection(
+	child: ChildPlan,
+	ctx?: OpenSpecContext | null,
+	assignedScenarios?: AssignedScenario[],
+): string {
+	if (!ctx) return "";
+
+	const sections: string[] = [];
+
+	// Architecture decisions — all decisions apply to all children
+	if (ctx.decisions.length > 0) {
+		sections.push(
+			"### Architecture Decisions",
+			"",
+			"Follow these design decisions from the project's design.md:",
+			"",
+			...ctx.decisions.map((d) => `- ${d}`),
+		);
+	}
+
+	// File changes relevant to this child
+	if (ctx.fileChanges.length > 0) {
+		const childLabelWords = child.label.replace(/-/g, " ").split(" ");
+		const childDescLower = child.description.toLowerCase();
+
+		const relevant = ctx.fileChanges.filter((fc) => {
+			const fpLower = fc.path.toLowerCase();
+			const pathParts = fpLower.split("/");
+			return (
+				childLabelWords.some((w) => w.length > 2 && pathParts.some((p) => p.includes(w))) ||
+				childDescLower.includes(fpLower) ||
+				child.scope.some((s) => fpLower.startsWith(s.replace(/\*+/g, "")))
+			);
+		});
+
+		if (relevant.length > 0) {
+			sections.push(
+				"### File Changes (from design.md)",
+				"",
+				"These specific file changes are planned for this task:",
+				"",
+				...relevant.map((fc) => `- \`${fc.path}\` (${fc.action})`),
+			);
+		}
+	}
+
+	// Spec scenarios from pre-computed assignments
+	if (assignedScenarios && assignedScenarios.length > 0) {
+		const regular = assignedScenarios.filter((s) => !s.crossCutting);
+		const crossCutting = assignedScenarios.filter((s) => s.crossCutting);
+
+		if (regular.length > 0) {
+			sections.push(
+				"### Acceptance Criteria (from specs)",
+				"",
+				"Your implementation should satisfy these spec scenarios:",
+				"",
+			);
+			for (const ss of regular) {
+				sections.push(`**${ss.domain} → ${ss.requirement}**`);
+				for (const scenario of ss.scenarios) {
+					const scenarioLines = scenario.split("\n").map((l) => `  ${l}`);
+					sections.push(...scenarioLines);
+				}
+				sections.push("");
+			}
+		}
+
+		if (crossCutting.length > 0) {
+			sections.push(
+				"### ⚠️ CROSS-CUTTING Acceptance Criteria",
+				"",
+				"These scenarios were not directly assigned to any task group but affect your scope.",
+				"Ensure your implementation does not break them, and wire any enforcement logic they require:",
+				"",
+			);
+			for (const ss of crossCutting) {
+				sections.push(`**⚠️ ${ss.domain} → ${ss.requirement}**`);
+				for (const scenario of ss.scenarios) {
+					const scenarioLines = scenario.split("\n").map((l) => `  ${l}`);
+					sections.push(...scenarioLines);
+				}
+				sections.push("");
+			}
+		}
+	}
+
+	if (sections.length === 0) return "";
+	return "\n## Design Context\n\n" + sections.join("\n") + "\n\n";
+}
+
+export type DirtyPathClass = "related" | "unrelated" | "unknown" | "volatile";
+export type DirtyPathConfidence = "high" | "medium" | "low";
+
+export interface ClassifiedDirtyPath {
+	path: string;
+	classification: DirtyPathClass;
+	confidence: DirtyPathConfidence;
+	reason: string;
+	includedInCheckpoint: boolean;
+}
+
+export interface DirtyTreeClassification {
+	files: ClassifiedDirtyPath[];
+	related: ClassifiedDirtyPath[];
+	unrelated: ClassifiedDirtyPath[];
+	unknown: ClassifiedDirtyPath[];
+	volatile: ClassifiedDirtyPath[];
+	checkpointFiles: string[];
+}
+
+export interface CheckpointPlanPreview {
+	files: string[];
+	message: string | null;
+	requiresApproval: true;
+	excluded: ClassifiedDirtyPath[];
+}
+
+export interface DirtyTreeClassificationOptions {
+	changeName?: string | null;
+	openspecContext?: OpenSpecContext | null;
+	volatileAllowlist?: string[];
+}
+
+export const DEFAULT_VOLATILE_ALLOWLIST = [".pi/memory/facts.jsonl"];
+
+/**
+ * Classify dirty-tree paths for preflight UX.
+ *
+ * Confidence is intentionally conservative:
+ * - volatile allowlist and OpenSpec lifecycle artifacts → high
+ * - design.md file scope matches → medium
+ * - everything else defaults to unrelated/unknown and is excluded from checkpoint
+ */
+export function classifyDirtyPaths(
+	paths: string[],
+	options: DirtyTreeClassificationOptions = {},
+): DirtyTreeClassification {
+	const knownRelated = collectKnownRelatedPaths(options.openspecContext);
+	const volatileAllowlist = (options.volatileAllowlist ?? DEFAULT_VOLATILE_ALLOWLIST)
+		.map(normalizePath);
+
+	const files = dedupePaths(paths).map((rawPath) => {
+		const path = normalizePath(rawPath);
+
+		if (matchesAnyPath(path, volatileAllowlist)) {
+			return {
+				path,
+				classification: "volatile" as const,
+				confidence: "high" as const,
+				reason: "matches volatile allowlist",
+				includedInCheckpoint: false,
+			};
+		}
+
+		if (matchesKnownRelatedPath(path, knownRelated.exact, knownRelated.prefixes)) {
+			return {
+				path,
+				classification: "related" as const,
+				confidence: "high" as const,
+				reason: "matches active OpenSpec change artifacts or design file scope",
+				includedInCheckpoint: true,
+			};
+		}
+
+		const scopedMatch = matchDesignScopedPath(path, options.openspecContext);
+		if (scopedMatch.matched) {
+			return {
+				path,
+				classification: "related" as const,
+				confidence: scopedMatch.confidence,
+				reason: scopedMatch.reason,
+				includedInCheckpoint: scopedMatch.confidence !== "low",
+			};
+		}
+
+		if (options.openspecContext) {
+			const unrelatedReason = findUnrelatedReason(path, options.openspecContext);
+			if (unrelatedReason) {
+				return {
+					path,
+					classification: "unrelated" as const,
+					confidence: "medium" as const,
+					reason: unrelatedReason,
+					includedInCheckpoint: false,
+				};
+			}
+
+			return {
+				path,
+				classification: "unknown" as const,
+				confidence: "low" as const,
+				reason: "outside active change scope and not on volatile allowlist",
+				includedInCheckpoint: false,
+			};
+		}
+
+		return {
+			path,
+			classification: "unknown" as const,
+			confidence: "low" as const,
+			reason: "generic preflight fallback without OpenSpec context",
+			includedInCheckpoint: false,
+		};
+	});
+
+	return {
+		files,
+		related: files.filter((f) => f.classification === "related"),
+		unrelated: files.filter((f) => f.classification === "unrelated"),
+		unknown: files.filter((f) => f.classification === "unknown"),
+		volatile: files.filter((f) => f.classification === "volatile"),
+		checkpointFiles: files.filter((f) => f.includedInCheckpoint).map((f) => f.path),
+	};
+}
+
+/**
+ * Prepare an operator-approved checkpoint plan without mutating git state.
+ */
+export function buildCheckpointPlan(
+	classification: DirtyTreeClassification,
+	options: DirtyTreeClassificationOptions = {},
+): CheckpointPlanPreview {
+	const files = classification.checkpointFiles;
+	return {
+		files,
+		message: files.length > 0 ? suggestCheckpointCommitMessage(files, options.changeName, options.openspecContext) : null,
+		requiresApproval: true,
+		excluded: classification.files.filter((f) => !f.includedInCheckpoint),
+	};
+}
+
+/**
+ * Suggest a conventional checkpoint commit message scoped to the active change.
+ */
+export function suggestCheckpointCommitMessage(
+	relatedFiles: string[],
+	changeName?: string | null,
+	openspecContext?: OpenSpecContext | null,
+): string {
+	const scope = deriveCheckpointScope(relatedFiles, changeName, openspecContext);
+	const summary = deriveCheckpointSummary(relatedFiles, changeName, openspecContext);
+	return `chore(${scope}): checkpoint ${summary}`;
+}
+
+function collectKnownRelatedPaths(ctx?: OpenSpecContext | null): { exact: Set<string>; prefixes: string[] } {
+	const exact = new Set<string>();
+	const prefixes: string[] = [];
+	if (!ctx) return { exact, prefixes };
+
+	for (const fileChange of ctx.fileChanges) {
+		exact.add(normalizePath(fileChange.path));
+	}
+
+	const normalizedChangePath = normalizePath(ctx.changePath);
+	const openspecIdx = normalizedChangePath.indexOf("openspec/changes/");
+	if (openspecIdx >= 0) {
+		prefixes.push(normalizedChangePath.slice(openspecIdx));
+	}
+
+	const changeSlug = openspecIdx >= 0
+		? normalizedChangePath.slice(openspecIdx + "openspec/changes/".length).split("/")[0]
+		: normalizedChangePath.split("/").pop() ?? "";
+	if (changeSlug) {
+		prefixes.push(`openspec/changes/${changeSlug}`);
+	}
+
+	return { exact, prefixes: dedupePaths(prefixes) };
+}
+
+function matchDesignScopedPath(
+	path: string,
+	ctx?: OpenSpecContext | null,
+): { matched: boolean; confidence: DirtyPathConfidence; reason: string } {
+	if (!ctx) return { matched: false, confidence: "low", reason: "" };
+
+	for (const fileChange of ctx.fileChanges) {
+		const target = normalizePath(fileChange.path);
+		if (path === target) {
+			return {
+				matched: true,
+				confidence: "high",
+				reason: "exact match for design.md file scope entry",
+			};
+		}
+
+		const prefix = stripGlob(target);
+		if (prefix.length > 0 && (path === prefix || path.startsWith(prefix + "/"))) {
+			return {
+				matched: true,
+				confidence: prefix === target ? "medium" : "low",
+				reason: prefix === target
+					? "matches design.md file scope path"
+					: "falls under a broad design.md file scope prefix",
+			};
+		}
+	}
+
+	return { matched: false, confidence: "low", reason: "" };
+}
+
+function findUnrelatedReason(path: string, ctx: OpenSpecContext): string | null {
+	const knownRelated = collectKnownRelatedPaths(ctx);
+	if (path.startsWith("openspec/changes/") && !matchesKnownRelatedPath(path, knownRelated.exact, knownRelated.prefixes)) {
+		return "belongs to a different OpenSpec change than the active checkpoint scope";
+	}
+	return null;
+}
+
+function deriveCheckpointScope(
+	relatedFiles: string[],
+	changeName?: string | null,
+	openspecContext?: OpenSpecContext | null,
+): string {
+	const rawScope = changeName
+		?? normalizePath(openspecContext?.changePath ?? "").split("/").pop()
+		?? relatedFiles[0]?.split("/")[0]
+		?? "cleave";
+	const cleaned = rawScope
+		.toLowerCase()
+		.replace(/^cleave-/, "")
+		.replace(/^feature-/, "")
+		.replace(/[^\x00-\x7F]/g, "")
+		.replace(/[^a-z0-9/-]+/g, "-")
+		.replace(/\//g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+	return cleaned || "cleave";
+}
+
+function deriveCheckpointSummary(
+	relatedFiles: string[],
+	changeName?: string | null,
+	openspecContext?: OpenSpecContext | null,
+): string {
+	const source = changeName
+		?? normalizePath(openspecContext?.changePath ?? "").split("/").pop()
+		?? relatedFiles[0]?.split("/").pop()
+		?? "work";
+	return source
+		.toLowerCase()
+		.replace(/^cleave-/, "")
+		.replace(/\.[a-z0-9]+$/i, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim() || "work";
+}
+
+function matchesKnownRelatedPath(path: string, exact: Set<string>, prefixes: string[]): boolean {
+	if (exact.has(path)) return true;
+	return prefixes.some((prefix) => path === prefix || path.startsWith(prefix + "/"));
+}
+
+function matchesAnyPath(path: string, candidates: string[]): boolean {
+	return candidates.some((candidate) => path === candidate || path.startsWith(candidate + "/"));
+}
+
+function stripGlob(path: string): string {
+	return path
+		.replace(/\*\*?/g, "")
+		.replace(/\/+/g, "/")
+		.replace(/\/$/, "");
+}
+
+function normalizePath(path: string): string {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/").replace(/\/$/, "");
+}
+
+function dedupePaths(paths: string[]): string[] {
+	return [...new Set(paths.map(normalizePath).filter(Boolean))];
+}
+
+/**
+ * Read all task files from a workspace and return their contents.
+ */
+export function readTaskFiles(workspacePath: string): Map<number, string> {
+	const tasks = new Map<number, string>();
+	let i = 0;
+	while (true) {
+		const taskPath = join(workspacePath, `${i}-task.md`);
+		if (!existsSync(taskPath)) break;
+		tasks.set(i, readFileSync(taskPath, "utf-8"));
+		i++;
+	}
+	return tasks;
+}