pi-plan-task 1.1.0 → 4.0.0

package/extensions/task-ui.ts

@@ -0,0 +1,59 @@
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { formatProgress } from "./files.ts";
+import type { PlanState, TaskItem } from "./types.ts";
+
+export function formatTaskList(tasks: TaskItem[]): string {
+	if (tasks.length === 0) return "No tasks found in .plan_task/task.md.";
+	const lines = tasks.map((task) => `${task.done ? "[x]" : "[ ]"} ${task.id}. ${task.title}`);
+	return `Progress ${formatProgress(tasks)}\n${lines.join("\n")}`;
+}
+
+export function formatWorkflowStatus(state: PlanState | undefined, tasks: TaskItem[]): string {
+	return [
+		`Status: ${state?.status ?? "idle"}`,
+		`Approved hash: ${state?.approvedStructureHash ?? "none"}`,
+		`Work id: ${state?.workId ?? "none"}`,
+		`Current task: ${state?.currentTaskId ?? "none"}`,
+		formatTaskList(tasks),
+	].join("\n");
+}
+export class TaskListComponent {
+	private readonly tasks: TaskItem[];
+	private readonly status: string;
+	private readonly theme: { fg: (name: "accent" | "muted" | "dim" | "success" | "text", text: string) => string };
+	private readonly onClose: () => void;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(tasks: TaskItem[], theme: TaskListComponent["theme"], onClose: () => void, status = "idle") {
+		this.tasks = tasks;
+		this.status = status;
+		this.theme = theme;
+		this.onClose = onClose;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.onClose();
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines = ["", truncateToWidth(`  ${th.fg("accent", "Plan tasks")}  ${th.fg("muted", `${formatProgress(this.tasks)}  ${this.status}`)}`, width), ""];
+		if (this.tasks.length === 0) lines.push(truncateToWidth(`  ${th.fg("dim", "No tasks found. Run /plan first.")}`, width));
+		else for (const task of this.tasks) {
+			const check = task.done ? th.fg("success", "x") : th.fg("dim", " ");
+			const title = task.done ? th.fg("dim", task.title) : th.fg("text", task.title);
+			lines.push(truncateToWidth(`  [${check}] ${th.fg("accent", String(task.id))}. ${title}`, width));
+		}
+		lines.push("", truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width), "");
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/extensions/tool-policy.ts

@@ -0,0 +1,4 @@
+export const PLAN_TOOL_NAMES = ["read", "grep", "find", "ls", "rg", "plan_task", "ask_user_question"] as const;
+export const PLAN_TOOL_ALLOWLIST = new Set<string>(PLAN_TOOL_NAMES);
+export function filterPlanTools(names: readonly string[]): string[] { return names.filter((name) => PLAN_TOOL_ALLOWLIST.has(name)); }
+export function isAllowedPlanTool(name: string): boolean { return PLAN_TOOL_ALLOWLIST.has(name); }

package/extensions/tools.test.ts

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { addTools, removeAddedTools } from "./tools.ts";
+describe("tool deltas", () => {
+	it("only removes tools added by this extension", () => {
+		const delta = addTools(["other", "read"], ["read", "write"]);
+		assert.deepEqual(delta.added, ["write"]);
+		assert.deepEqual(removeAddedTools(["other", "read", "write", "new-runtime"], delta), ["other", "read", "new-runtime"]);
+	});
+});

package/extensions/tools.ts

@@ -0,0 +1,16 @@
+export interface ToolDelta {
+	before: string[];
+	added: string[];
+}
+
+export function addTools(current: readonly string[], required: readonly string[]): ToolDelta {
+	const before = [...current];
+	const existing = new Set(before);
+	const added = required.filter((name) => !existing.has(name));
+	return { before, added };
+}
+
+export function removeAddedTools(current: readonly string[], delta: ToolDelta): string[] {
+	const added = new Set(delta.added);
+	return current.filter((name) => !added.has(name));
+}

package/extensions/types.ts

@@ -1,5 +1,11 @@
+export type PlanStatus = "idle" | "planning" | "ready" | "approved" | "executing" | "blocked" | "completed";
+export type ActiveTaskStatus = "pending" | "implementation-complete";
+export type TaskStatus = ActiveTaskStatus | "verified" | "blocked";
+export type ExecutionMode = "automatic" | "external";
+
 export interface PlanTaskConfig {
 	planTools: string[];
+	executionMode: ExecutionMode;
 }
 
 export interface TaskItem {
@@ -9,18 +15,60 @@ export interface TaskItem {
 	body: string;
 }
 
-export interface TaskFile {
-	raw: string;
-	tasks: TaskItem[];
+export interface TaskFile { raw: string; tasks: TaskItem[]; }
+
+export interface TaskRuntimeState {
+	status: TaskStatus;
+	reason?: string;
+	blockedFrom?: ActiveTaskStatus;
+	startedAt?: string;
+	completedAt?: string;
+	verifiedAt?: string;
+	verification?: string;
+}
+
+export interface PlanState {
+	version: 2;
+	status: PlanStatus;
+	currentTaskId?: number;
+	workId?: string;
+	planningRequest?: string;
+	executionMode: ExecutionMode;
+	continueMode?: "single" | "all-here" | "all-new";
+	approvalEachTask?: boolean;
+	planningBaselineHash?: string;
+	draftStructureHash?: string;
+	approvedStructureHash?: string;
+	sessionFile?: string;
+	failureReason?: string;
+	updatedAt: string;
+	tasks?: Record<string, TaskRuntimeState>;
 }
 
-export const DEFAULT_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", "pwsh", "rg"] as const;
+export interface LegacyPlanState {
+	version?: 1;
+	status?: PlanStatus;
+	currentTaskId?: number;
+	workId?: string;
+	executionMode?: ExecutionMode;
+	continueMode?: "single" | "all-here" | "all-new";
+	approvalEachTask?: boolean;
+	planHash?: string;
+	sessionFile?: string;
+	failureReason?: string;
+	updatedAt?: string;
+	tasks?: Record<string, Partial<TaskRuntimeState> & { status?: string }>;
+}
 
+export const DEFAULT_PLAN_TOOLS = ["read", "grep", "find", "ls", "rg"] as const;
 export const DEFAULT_CONFIG: PlanTaskConfig = {
 	planTools: [...DEFAULT_PLAN_TOOLS],
+	executionMode: "automatic",
 };
-
 export const PLAN_DIR_NAME = ".plan_task";
 export const PLAN_FILE_NAME = "plan.md";
 export const TASK_FILE_NAME = "task.md";
+export const STATE_FILE_NAME = "state.json";
+export const HISTORY_DIR_NAME = "history";
+export const DRAFT_DIR_NAME = "draft";
 export const CONFIG_FILE_NAME = "plan_task.json";

package/extensions/validation.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseTaskMarkdown } from "./parse.ts";
+import { validatePlan } from "./review.ts";
+
+const VALID_TASK = `# Tasks
+
+- [ ] 1. A
+
+## Task 1: A
+
+**Description:** Do A.
+**Acceptance criteria:** A works.
+**Verification:** Run tests.
+`;
+
+describe("plan validation edge cases", () => {
+	it("rejects missing required sections", () => {
+		const task = "# Tasks\n\n- [ ] 1. A\n\n## Task 1: A\n";
+		const result = validatePlan("# Plan", task, parseTaskMarkdown(task));
+		assert.equal(result.valid, false);
+		assert.equal(result.errors.length, 3);
+	});
+	it("rejects empty plans", () => { assert.equal(validatePlan("", "", []).valid, false); });
+	it("rejects unnumbered checklists", () => {
+		const raw = VALID_TASK.replace("- [ ] 1. A", "- [ ] A");
+		assert.equal(validatePlan("# Plan", raw, parseTaskMarkdown(raw)).valid, false);
+	});
+	it("rejects star bullets and non-positive task ids", () => {
+		const star = VALID_TASK.replace("- [ ] 1. A", "* [ ] 1. A");
+		assert.equal(validatePlan("# Plan", star, parseTaskMarkdown(star)).valid, false);
+		const zero = VALID_TASK.replaceAll("1. A", "0. A").replaceAll("Task 1", "Task 0");
+		assert.throws(() => parseTaskMarkdown(zero), /positive integers/);
+	});
+	it("accepts a strict matching task contract", () => {
+		assert.equal(validatePlan("# Plan", VALID_TASK, parseTaskMarkdown(VALID_TASK)).valid, true);
+	});
+});

package/extensions/workflow-policy.test.ts

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { initialState, structureHash, transition, updateTaskState } from "./state.ts";
+import type { PlanState, TaskFile } from "./types.ts";
+import { assertApprovedStructure, completeCurrentTask, reworkFromTask, verifyCurrentTask, canCompleteTask, canReworkTask, canVerifyTask, classifyQueue } from "./workflow-policy.ts";
+
+const file: TaskFile = {
+	raw: "# Tasks\n\n- [ ] 1. A\n- [ ] 2. B\n",
+	tasks: [
+		{ id: 1, title: "A", done: false, body: "" },
+		{ id: 2, title: "B", done: false, body: "" },
+	],
+};
+
+function executing(): PlanState {
+	let state = transition(initialState(), "planning");
+	state = transition(state, "ready");
+	state = { ...transition(state, "approved"), approvedStructureHash: "hash" };
+	state = transition(state, "executing");
+	return { ...state, currentTaskId: 1, tasks: { "1": { status: "pending" }, "2": { status: "pending" } } };
+}
+
+describe("workflow policy", () => {
+	it("only completes the current executing task", () => {
+		assert.equal(canCompleteTask(executing(), file, 1).ok, true);
+		assert.equal(canCompleteTask(executing(), file, 2).ok, false);
+		assert.equal(canCompleteTask({ ...executing(), status: "ready" }, file, 1).ok, false);
+	});
+	it("requires implementation completion and evidence before verify", () => {
+		assert.equal(canVerifyTask(executing(), file, 1, "tests passed").ok, false);
+		const complete = updateTaskState(executing(), 1, "implementation-complete");
+		assert.equal(canVerifyTask(complete, file, 1, "").ok, false);
+		assert.equal(canVerifyTask(complete, file, 1, "tests passed").ok, true);
+	});
+	it("distinguishes blocked-only work from completion", () => {
+		const blocked = { ...executing(), tasks: { "1": { status: "blocked" as const, reason: "x" }, "2": { status: "blocked" as const, reason: "y" } } };
+		assert.deepEqual(classifyQueue(file, blocked), { kind: "all-remaining-blocked", taskIds: [1, 2] });
+		assert.deepEqual(classifyQueue({ ...file, tasks: file.tasks.map((task) => ({ ...task, done: true })) }, blocked), { kind: "all-complete" });
+	});
+	it("requires a verified completed task before rework", () => {
+		const doneFile = { ...file, tasks: [{ ...file.tasks[0]!, done: true }, file.tasks[1]!] };
+		assert.equal(canReworkTask(executing(), doneFile, 1).ok, false);
+		const verified = updateTaskState(executing(), 1, "verified", { verification: "ok" });
+		assert.equal(canReworkTask(verified, doneFile, 1).ok, true);
+	});
+	it("rejects structural changes but permits checkbox progress", () => {
+		const task = "# Tasks\n\n- [ ] 1. A\n";
+		const state = { ...executing(), approvedStructureHash: structureHash("# Plan", task) };
+		assert.doesNotThrow(() => assertApprovedStructure(state, "# Plan", task.replace("[ ]", "[x]"), structureHash));
+		assert.throws(() => assertApprovedStructure(state, "# Changed", task, structureHash), /changed after approval/);
+	});
+	it("applies complete then verify without checking early", () => {
+		const completed = completeCurrentTask(executing(), file, 1);
+		assert.equal(completed.ok, true);
+		if (!completed.ok) return;
+		assert.doesNotMatch(completed.value.task, /\[x\] 1/);
+		const verified = verifyCurrentTask(completed.value.state, { raw: completed.value.task, tasks: file.tasks }, 1, "tests passed");
+		assert.equal(verified.ok, true);
+		if (!verified.ok) return;
+		assert.match(verified.value.task, /\[x\] 1/);
+		assert.equal(verified.value.state.tasks?.["1"]?.status, "verified");
+	});
+	it("cascades rework and revokes approval", () => {
+		const doneFile: TaskFile = { raw: file.raw.replaceAll("[ ]", "[x]"), tasks: file.tasks.map((task) => ({ ...task, done: true })) };
+		let state = updateTaskState(executing(), 1, "verified", { verification: "one" });
+		state = updateTaskState(state, 2, "verified", { verification: "two" });
+		const reworked = reworkFromTask(state, doneFile, 1);
+		assert.equal(reworked.ok, true);
+		if (!reworked.ok) return;
+		assert.equal(reworked.value.state.status, "ready");
+		assert.equal(reworked.value.state.approvedStructureHash, undefined);
+		assert.equal(reworked.value.state.tasks?.["1"]?.status, "pending");
+		assert.equal(reworked.value.state.tasks?.["2"]?.status, "pending");
+		assert.doesNotMatch(reworked.value.task, /\[x\]/);
+	});
+});

package/extensions/workflow-policy.ts

@@ -0,0 +1,117 @@
+import { markTaskDoneInMarkdown, markTasksPendingFromMarkdown } from "./parse.ts";
+import { transition, updateTaskState } from "./state.ts";
+import type { PlanState, TaskFile, TaskItem, TaskRuntimeState } from "./types.ts";
+
+export type QueueDecision =
+	| { kind: "runnable"; task: TaskItem }
+	| { kind: "all-complete" }
+	| { kind: "all-remaining-blocked"; taskIds: number[] };
+
+export type PolicyResult<T> = { ok: true; value: T } | { ok: false; error: string };
+
+export function assertApprovedStructure(state: PlanState, plan: string, task: string, hash: (plan: string, task: string) => string): void {
+	if (!state.approvedStructureHash) throw new Error("Plan is not bound to an approved structure hash.");
+	if (hash(plan, task) !== state.approvedStructureHash) throw new Error("Plan files changed after approval; review and approve again.");
+}
+
+export function classifyQueue(file: TaskFile, state: PlanState): QueueDecision {
+	const remaining = file.tasks.filter((task) => !task.done);
+	if (remaining.length === 0) return { kind: "all-complete" };
+	const runnable = remaining.find((task) => state.tasks?.[String(task.id)]?.status !== "blocked");
+	if (runnable) return { kind: "runnable", task: runnable };
+	return { kind: "all-remaining-blocked", taskIds: remaining.map((task) => task.id) };
+}
+
+export function canCompleteTask(state: PlanState, file: TaskFile, id: number): PolicyResult<TaskItem> {
+	if (state.status !== "executing") return { ok: false, error: `Plan is not executing (status: ${state.status}).` };
+	if (state.currentTaskId !== id) return { ok: false, error: `Only current task ${state.currentTaskId ?? "none"} can be completed.` };
+	const task = file.tasks.find((item) => item.id === id);
+	if (!task) return { ok: false, error: `Task ${id} was not found.` };
+	if (task.done) return { ok: false, error: `Task ${id} is already verified.` };
+	const runtime = state.tasks?.[String(id)];
+	if (runtime && runtime.status !== "pending") return { ok: false, error: `Task ${id} cannot complete from ${runtime.status}.` };
+	return { ok: true, value: task };
+}
+
+export function canVerifyTask(state: PlanState, file: TaskFile, id: number, reason?: string): PolicyResult<TaskItem> {
+	if (!reason?.trim()) return { ok: false, error: "A non-empty verification result is required." };
+	if (state.status !== "executing") return { ok: false, error: `Plan is not executing (status: ${state.status}).` };
+	if (state.currentTaskId !== id) return { ok: false, error: `Only current task ${state.currentTaskId ?? "none"} can be verified.` };
+	const task = file.tasks.find((item) => item.id === id);
+	if (!task) return { ok: false, error: `Task ${id} was not found.` };
+	if (task.done) return { ok: false, error: `Task ${id} is already verified.` };
+	if (state.tasks?.[String(id)]?.status !== "implementation-complete") return { ok: false, error: `Task ${id} must be implementation-complete before verification.` };
+	return { ok: true, value: task };
+}
+
+export function canBlockTask(state: PlanState, file: TaskFile, id: number, reason?: string): PolicyResult<{ task: TaskItem; blockedFrom: "pending" | "implementation-complete" }> {
+	if (!reason?.trim()) return { ok: false, error: "A non-empty block reason is required." };
+	if (state.status !== "executing") return { ok: false, error: `Plan is not executing (status: ${state.status}).` };
+	if (state.currentTaskId !== id) return { ok: false, error: `Only current task ${state.currentTaskId ?? "none"} can be blocked.` };
+	const task = file.tasks.find((item) => item.id === id);
+	if (!task || task.done) return { ok: false, error: `Pending task ${id} was not found.` };
+	const status = state.tasks?.[String(id)]?.status ?? "pending";
+	if (status !== "pending" && status !== "implementation-complete") return { ok: false, error: `Task ${id} cannot be blocked from ${status}.` };
+	return { ok: true, value: { task, blockedFrom: status } };
+}
+
+export function canUnblockTask(state: PlanState, file: TaskFile, id: number): PolicyResult<TaskRuntimeState> {
+	if (!file.tasks.some((item) => item.id === id)) return { ok: false, error: `Task ${id} was not found.` };
+	const runtime = state.tasks?.[String(id)];
+	if (runtime?.status !== "blocked") return { ok: false, error: `Task ${id} is not blocked.` };
+	return { ok: true, value: runtime };
+}
+
+export function canReworkTask(state: PlanState, file: TaskFile, id: number): PolicyResult<TaskItem> {
+	if (!["completed", "executing", "blocked", "approved"].includes(state.status)) return { ok: false, error: `Plan cannot be reworked from ${state.status}.` };
+	const task = file.tasks.find((item) => item.id === id);
+	if (!task) return { ok: false, error: `Task ${id} was not found.` };
+	if (!task.done || state.tasks?.[String(id)]?.status !== "verified") return { ok: false, error: `Task ${id} must be verified before rework.` };
+	return { ok: true, value: task };
+}
+
+export interface WorkflowMutation { state: PlanState; task: string; }
+
+export function completeCurrentTask(state: PlanState, file: TaskFile, id: number): PolicyResult<WorkflowMutation> {
+	const allowed = canCompleteTask(state, file, id);
+	if (!allowed.ok) return allowed;
+	return { ok: true, value: { state: updateTaskState(state, id, "implementation-complete"), task: file.raw } };
+}
+
+export function verifyCurrentTask(state: PlanState, file: TaskFile, id: number, reason?: string): PolicyResult<WorkflowMutation> {
+	const allowed = canVerifyTask(state, file, id, reason);
+	if (!allowed.ok) return allowed;
+	return { ok: true, value: {
+		state: updateTaskState(state, id, "verified", { verification: reason!.trim(), reason: undefined, blockedFrom: undefined }),
+		task: markTaskDoneInMarkdown(file.raw, id),
+	} };
+}
+
+export function blockCurrentTask(state: PlanState, file: TaskFile, id: number, reason?: string): PolicyResult<WorkflowMutation> {
+	const allowed = canBlockTask(state, file, id, reason);
+	if (!allowed.ok) return allowed;
+	return { ok: true, value: {
+		state: updateTaskState(state, id, "blocked", { reason: reason!.trim(), blockedFrom: allowed.value.blockedFrom }),
+		task: file.raw,
+	} };
+}
+
+export function unblockTask(state: PlanState, file: TaskFile, id: number): PolicyResult<WorkflowMutation> {
+	const allowed = canUnblockTask(state, file, id);
+	if (!allowed.ok) return allowed;
+	const restored = allowed.value.blockedFrom ?? "pending";
+	const plan = state.status === "blocked" ? transition(state, "approved") : state;
+	return { ok: true, value: { state: updateTaskState(plan, id, restored, { reason: undefined, blockedFrom: undefined }), task: file.raw } };
+}
+
+export function reworkFromTask(state: PlanState, file: TaskFile, id: number): PolicyResult<WorkflowMutation> {
+	const allowed = canReworkTask(state, file, id);
+	if (!allowed.ok) return allowed;
+	const tasks = { ...(state.tasks ?? {}) };
+	for (const taskId of Object.keys(tasks).map(Number)) if (taskId >= id) tasks[String(taskId)] = { status: "pending" };
+	const ready = transition(state, "ready");
+	return { ok: true, value: {
+		state: { ...ready, tasks, currentTaskId: undefined, approvedStructureHash: undefined, continueMode: undefined, approvalEachTask: false, failureReason: `Task ${id} and dependent tasks reopened; approval required.` },
+		task: markTasksPendingFromMarkdown(file.raw, id),
+	} };
+}

package/extensions/workflow-store.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import { draftPlanFilePath, draftTaskFilePath, planDir, planFilePath, taskFilePath } from "./paths.ts";
+import { initialState, loadState, structureHash, transition, updateTaskState } from "./state.ts";
+import { commitDraft, initializeDraftWithState, mutateWorkflow, saveStateLocked } from "./workflow-store.ts";
+
+const TASK = `# Tasks\n\n- [ ] 1. A\n\n## Task 1: A\n\n**Description:** A\n**Acceptance criteria:** A\n**Verification:** A\n`;
+
+async function tempProject<T>(run: (cwd: string) => Promise<T>): Promise<T> {
+	const cwd = await mkdtemp(join(tmpdir(), "pi-plan-task-store-"));
+	try { return await run(cwd); } finally { await rm(cwd, { recursive: true, force: true }); }
+}
+
+describe("workflow store", () => {
+	it("ignores top-level checkbox progress in structure hashes", () => {
+		assert.equal(structureHash("# Plan", TASK), structureHash("# Plan", TASK.replace("[ ]", "[x]")));
+		assert.notEqual(structureHash("# Plan", TASK), structureHash("# Changed", TASK));
+		assert.notEqual(structureHash("# Plan", TASK), structureHash("# Plan", TASK.replace("Task 1: A", "Task 1: B")));
+	});
+	it("commits only validated draft content to current files", async () => tempProject(async (cwd) => {
+		let state = transition(initialState(), "planning");
+		await initializeDraftWithState(cwd, state);
+		await writeFile(draftPlanFilePath(cwd), "# New plan", "utf8");
+		await writeFile(draftTaskFilePath(cwd), TASK, "utf8");
+		state = transition(state, "ready");
+		const committed = await commitDraft(cwd, state);
+		assert.equal(await readFile(planFilePath(cwd), "utf8"), "# New plan");
+		assert.equal(await readFile(taskFilePath(cwd), "utf8"), TASK);
+		assert.equal(committed.draftStructureHash, structureHash("# New plan", TASK));
+	}));
+	it("serializes concurrent state updates without losing either task", async () => tempProject(async (cwd) => {
+		await writeFile(join(cwd, ".keep"), "", "utf8");
+		await import("node:fs/promises").then(({ mkdir }) => mkdir(planDir(cwd), { recursive: true }));
+		await writeFile(planFilePath(cwd), "# Plan", "utf8");
+		await writeFile(taskFilePath(cwd), TASK.replace("- [ ] 1. A", "- [ ] 1. A\n- [ ] 2. B"), "utf8");
+		await saveStateLocked(cwd, initialState());
+		await Promise.all([
+			mutateWorkflow(cwd, ({ state }) => ({ state: updateTaskState(state, 1, "pending") })),
+			mutateWorkflow(cwd, ({ state }) => ({ state: updateTaskState(state, 2, "pending") })),
+		]);
+		const state = await loadState(cwd);
+		assert.equal(state?.tasks?.["1"]?.status, "pending");
+		assert.equal(state?.tasks?.["2"]?.status, "pending");
+	}));
+});

package/extensions/workflow-store.ts

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { readOptionalFile } from "./files.ts";
+import { savePlanSnapshot } from "./history.ts";
+import { draftDir, draftPlanFilePath, draftTaskFilePath, planDir, planFilePath, stateFilePath, taskFilePath } from "./paths.ts";
+import { loadState, parsePlanState, saveState, structureHash } from "./state.ts";
+import type { PlanState } from "./types.ts";
+
+const queues = new Map<string, Promise<void>>();
+
+async function withProcessQueue<T>(cwd: string, operation: () => Promise<T>): Promise<T> {
+	const key = resolve(cwd);
+	const previous = queues.get(key) ?? Promise.resolve();
+	let release!: () => void;
+	const current = new Promise<void>((done) => { release = done; });
+	const chain = previous.then(() => current);
+	queues.set(key, chain);
+	await previous;
+	try { return await operation(); } finally {
+		release();
+		if (queues.get(key) === chain) queues.delete(key);
+	}
+}
+
+async function acquireDirectoryLock(cwd: string): Promise<() => Promise<void>> {
+	const lockPath = resolve(planDir(cwd), ".lock");
+	await mkdir(planDir(cwd), { recursive: true });
+	for (let attempt = 0; ; attempt++) {
+		try { await mkdir(lockPath); break; } catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			try {
+				if (Date.now() - (await stat(lockPath)).mtimeMs > 10 * 60 * 1000) {
+					await rm(lockPath, { recursive: true, force: true });
+					continue;
+				}
+			} catch { /* disappeared; retry */ }
+			if (attempt >= 200) throw new Error(`Timed out waiting for workflow lock: ${lockPath}`);
+			await new Promise((done) => setTimeout(done, 25));
+		}
+	}
+	return async () => rm(lockPath, { recursive: true, force: true });
+}
+
+export async function withWorkflowLock<T>(cwd: string, operation: () => Promise<T>): Promise<T> {
+	return withProcessQueue(cwd, async () => {
+		const release = await acquireDirectoryLock(cwd);
+		try { return await operation(); } finally { await release(); }
+	});
+}
+
+interface FileChange { path: string; content: string; }
+
+export async function writeFilesAtomically(changes: readonly FileChange[]): Promise<void> {
+	const transactionId = `${process.pid}.${randomUUID()}`;
+	const prepared: Array<FileChange & { temporary: string; backup: string; previous?: string }> = [];
+	try {
+		for (const change of changes) {
+			await mkdir(dirname(change.path), { recursive: true });
+			const previous = await readOptionalFile(change.path);
+			const temporary = `${change.path}.${transactionId}.tmp`;
+			const backup = `${change.path}.${transactionId}.bak`;
+			prepared.push({ ...change, temporary, backup, previous });
+			await writeFile(temporary, change.content, "utf8");
+		}
+	} catch (error) {
+		await Promise.all(prepared.map((item) => rm(item.temporary, { force: true }).catch(() => undefined)));
+		throw error;
+	}
+	let applied = 0;
+	try {
+		for (const item of prepared) {
+			if (item.previous !== undefined) await rename(item.path, item.backup);
+			await rename(item.temporary, item.path);
+			applied += 1;
+		}
+		await Promise.all(prepared.map((item) => rm(item.backup, { force: true }).catch(() => undefined)));
+	} catch (error) {
+		for (const item of [...prepared.slice(0, applied)].reverse()) {
+			await rm(item.path, { force: true }).catch(() => undefined);
+			if (item.previous !== undefined) await rename(item.backup, item.path).catch(() => undefined);
+		}
+		for (const item of prepared.slice(applied)) {
+			await rm(item.temporary, { force: true }).catch(() => undefined);
+			if (item.previous !== undefined) await rename(item.backup, item.path).catch(() => undefined);
+		}
+		throw error;
+	}
+}
+
+export async function readCurrentArtifacts(cwd: string): Promise<{ plan: string; task: string }> {
+	const plan = await readOptionalFile(planFilePath(cwd));
+	const task = await readOptionalFile(taskFilePath(cwd));
+	if (plan === undefined || task === undefined) throw new Error("Current plan.md and task.md are required.");
+	return { plan, task };
+}
+
+
+
+export async function initializeDraftWithState(cwd: string, state: PlanState, source?: { plan: string; task: string }): Promise<PlanState> {
+	return withWorkflowLock(cwd, async () => {
+		await rm(draftDir(cwd), { recursive: true, force: true });
+		await mkdir(draftDir(cwd), { recursive: true });
+		const validated = parsePlanState({ ...state, updatedAt: new Date().toISOString() });
+		await writeFilesAtomically([
+			{ path: draftPlanFilePath(cwd), content: source?.plan ?? "" },
+			{ path: draftTaskFilePath(cwd), content: source?.task ?? "" },
+			{ path: stateFilePath(cwd), content: `${JSON.stringify(validated, null, 2)}\n` },
+		]);
+		return validated;
+	});
+}
+
+export async function readDraftArtifacts(cwd: string): Promise<{ plan: string; task: string }> {
+	const plan = await readOptionalFile(draftPlanFilePath(cwd));
+	const task = await readOptionalFile(draftTaskFilePath(cwd));
+	if (plan === undefined || task === undefined) throw new Error("Draft plan.md and task.md are required.");
+	return { plan, task };
+}
+
+export async function commitDraft(cwd: string, nextState: PlanState, draftOverride?: { plan: string; task: string }): Promise<PlanState> {
+	return withWorkflowLock(cwd, async () => {
+		const draft = draftOverride ?? await readDraftArtifacts(cwd);
+		const oldPlan = (await readOptionalFile(planFilePath(cwd))) ?? "";
+		const oldTask = (await readOptionalFile(taskFilePath(cwd))) ?? "";
+		if (oldPlan || oldTask) await savePlanSnapshot(cwd, oldPlan, oldTask);
+		const committed = parsePlanState({ ...nextState, draftStructureHash: structureHash(draft.plan, draft.task), updatedAt: new Date().toISOString() });
+		await writeFilesAtomically([
+			{ path: planFilePath(cwd), content: draft.plan },
+			{ path: taskFilePath(cwd), content: draft.task },
+			{ path: stateFilePath(cwd), content: `${JSON.stringify({ ...committed, updatedAt: new Date().toISOString() }, null, 2)}\n` },
+		]);
+		await rm(draftDir(cwd), { recursive: true, force: true });
+		return committed;
+	});
+}
+
+export async function mutateWorkflow(
+	cwd: string,
+	mutation: (current: { state: PlanState; plan: string; task: string }) => Promise<{ state: PlanState; task?: string; plan?: string }> | { state: PlanState; task?: string; plan?: string },
+): Promise<{ state: PlanState; plan: string; task: string }> {
+	return withWorkflowLock(cwd, async () => {
+		const state = await loadState(cwd);
+		if (!state) throw new Error("No workflow state found.");
+		const { plan, task } = await readCurrentArtifacts(cwd);
+		const next = await mutation({ state, plan, task });
+		const validatedState = parsePlanState({ ...next.state, updatedAt: new Date().toISOString() });
+		const nextPlan = next.plan ?? plan;
+		const nextTask = next.task ?? task;
+		await writeFilesAtomically([
+			...(nextPlan !== plan ? [{ path: planFilePath(cwd), content: nextPlan }] : []),
+			...(nextTask !== task ? [{ path: taskFilePath(cwd), content: nextTask }] : []),
+			{ path: stateFilePath(cwd), content: `${JSON.stringify(validatedState, null, 2)}\n` },
+		]);
+		return { state: validatedState, plan: nextPlan, task: nextTask };
+	});
+}
+export async function loadStateLocked(cwd: string): Promise<PlanState | undefined> {
+	return withWorkflowLock(cwd, () => loadState(cwd));
+}
+
+
+export async function saveStateLocked(cwd: string, state: PlanState): Promise<void> {
+	await withWorkflowLock(cwd, () => saveState(cwd, state));
+}