pi-plan-task 1.1.0 → 3.0.1

package/extensions/integration.test.ts

@@ -0,0 +1,232 @@
+import assert from "node:assert/strict";
+import { mkdir, 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 planTaskExtension from "./index.ts";
+import { draftPlanFilePath, draftTaskFilePath, planDir, planFilePath, projectConfigPath, taskFilePath } from "./paths.ts";
+import { initialState, loadState, saveState, structureHash, transition, updateTaskState } from "./state.ts";
+import type { PlanState } from "./types.ts";
+
+const TASK = `# Tasks\n\n- [ ] 1. A\n- [ ] 2. B\n\n## Task 1: A\n\n**Description:** A\n**Acceptance criteria:** A\n**Verification:** A\n\n## Task 2: B\n\n**Description:** B\n**Acceptance criteria:** B\n**Verification:** B\n`;
+
+async function harness() {
+	const root = await mkdtemp(join(tmpdir(), "pi-plan-task-integration-"));
+	const cwd = join(root, "project");
+	const agentDir = join(root, "agent");
+	await mkdir(cwd, { recursive: true });
+	const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	const commands = new Map<string, any>();
+	const handlers = new Map<string, any>();
+	let tool: any;
+	const notifications: string[] = [];
+	const sent: string[] = [];
+	let newSessionCancelled = true;
+	const api: any = {
+		registerCommand(name: string, definition: any) { commands.set(name, definition); },
+		registerTool(definition: any) { tool = definition; },
+		on(name: string, handler: any) { handlers.set(name, handler); },
+		getActiveTools() { return []; },
+		setActiveTools() {},
+		getAllTools() { return [{ name: "ask_user_question" }]; },
+		events: { emit() {} },
+		sendUserMessage(message: string) { sent.push(message); },
+		exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+	};
+	await planTaskExtension(api);
+	const ctx: any = {
+		cwd, hasUI: false, mode: "print",
+		ui: {
+			notify(message: string) { notifications.push(message); },
+			setStatus() {}, setWidget() {},
+			theme: { fg: (_name: string, text: string) => text },
+			confirm: async () => true, input: async () => "feedback", select: async () => undefined,
+		},
+		sessionManager: { getSessionFile: () => join(root, "session.jsonl") },
+		newSession: async (options: any) => {
+			if (newSessionCancelled) return { cancelled: true };
+			await options?.withSession?.({ sendUserMessage: async (message: string) => { sent.push(message); } });
+			return { cancelled: false };
+		},
+	};
+	return {
+		root, cwd, ctx, commands, handlers, get tool() { return tool; }, notifications, sent,
+		setNewSessionCancelled(value: boolean) { newSessionCancelled = value; },
+		async close() { if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR; else process.env.PI_CODING_AGENT_DIR = previousAgentDir; await rm(root, { recursive: true, force: true }); },
+	};
+}
+
+async function writeWorkflow(cwd: string, status: PlanState["status"], task = TASK): Promise<PlanState> {
+	await mkdir(planDir(cwd), { recursive: true });
+	const plan = "# Plan";
+	await writeFile(planFilePath(cwd), plan, "utf8");
+	await writeFile(taskFilePath(cwd), task, "utf8");
+	let state = transition(initialState(), "planning");
+	state = transition(state, "ready");
+	state = { ...state, tasks: { "1": { status: "pending" }, "2": { status: "pending" } } };
+	if (status === "approved" || status === "executing") {
+		state = { ...transition(state, "approved"), approvedStructureHash: structureHash(plan, task) };
+		if (status === "executing") state = { ...transition(state, "executing"), currentTaskId: 1 };
+	}
+	await saveState(cwd, state);
+	return state;
+}
+
+describe("extension command integration", () => {
+	it("does not let ready-state rework bypass approval", async () => {
+		const h = await harness();
+		try {
+			const checked = TASK.replace("- [ ] 1. A", "- [x] 1. A");
+			let state = await writeWorkflow(h.cwd, "ready", checked);
+			state = updateTaskState(state, 1, "verified", { verification: "passed" });
+			await saveState(h.cwd, state);
+			await h.commands.get("tasks").handler("rework 1", h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "ready");
+			assert.match(await readFile(taskFilePath(h.cwd), "utf8"), /- \[x\] 1\. A/);
+		} finally { await h.close(); }
+	});
+
+	it("revokes approval when plan structure changes", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "approved");
+			await writeFile(planFilePath(h.cwd), "# Changed", "utf8");
+			await h.commands.get("build").handler("", h.ctx);
+			const state = await loadState(h.cwd);
+			assert.equal(state?.status, "ready");
+			assert.equal(state?.approvedStructureHash, undefined);
+		} finally { await h.close(); }
+	});
+
+	it("rejects wrong task ids and applies complete then verify", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "executing");
+			await assert.rejects(() => h.tool.execute("call", { action: "complete", id: 2 }, undefined, undefined, h.ctx), /Only current task 1/);
+			assert.doesNotMatch(await readFile(taskFilePath(h.cwd), "utf8"), /\[x\]/);
+			await h.tool.execute("call", { action: "complete", id: 1 }, undefined, undefined, h.ctx);
+			assert.equal((await loadState(h.cwd))?.tasks?.["1"]?.status, "implementation-complete");
+			assert.doesNotMatch(await readFile(taskFilePath(h.cwd), "utf8"), /\[x\] 1/);
+			await h.tool.execute("call", { action: "verify", id: 1, reason: "tests passed" }, undefined, undefined, h.ctx);
+			assert.equal((await loadState(h.cwd))?.tasks?.["1"]?.status, "verified");
+			assert.match(await readFile(taskFilePath(h.cwd), "utf8"), /\[x\] 1/);
+		} finally { await h.close(); }
+	});
+
+	it("keeps initial new-session cancellation approved", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "approved");
+			await h.commands.get("build").handler("new", h.ctx);
+			const state = await loadState(h.cwd);
+			assert.equal(state?.status, "approved");
+			assert.equal(state?.continueMode, undefined);
+		} finally { await h.close(); }
+	});
+
+	it("hands off all-new approval and all-fresh through public build commands", async () => {
+		const allNew = await harness();
+		try {
+			await writeWorkflow(allNew.cwd, "approved");
+			allNew.setNewSessionCancelled(false);
+			await allNew.commands.get("build").handler("all new --approval", allNew.ctx);
+			const state = await loadState(allNew.cwd);
+			assert.equal(state?.continueMode, "all-new");
+			assert.equal(state?.approvalEachTask, true);
+			assert.equal(allNew.sent.includes("/build"), true);
+		} finally { await allNew.close(); }
+		const fresh = await harness();
+		try {
+			await writeWorkflow(fresh.cwd, "approved");
+			fresh.setNewSessionCancelled(false);
+			await fresh.commands.get("build").handler("all fresh", fresh.ctx);
+			assert.equal(fresh.sent.includes("/build all"), true);
+		} finally { await fresh.close(); }
+	});
+
+	it("external mode refuses local build", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "approved");
+			await mkdir(join(h.cwd, ".pi"), { recursive: true });
+			await writeFile(projectConfigPath(h.cwd), JSON.stringify({ executionMode: "external" }), "utf8");
+			await h.commands.get("build").handler("", h.ctx);
+			assert.equal(h.notifications.some((message) => message.includes("External execution mode")), true);
+			assert.equal((await loadState(h.cwd))?.status, "approved");
+		} finally { await h.close(); }
+	});
+
+	it("runs plan draft submission and approval through the three-command surface", async () => {
+		const h = await harness();
+		try {
+			await h.commands.get("plan").handler("Add A", h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "planning");
+			await writeFile(draftPlanFilePath(h.cwd), "# Plan", "utf8");
+			await writeFile(draftTaskFilePath(h.cwd), TASK, "utf8");
+			await h.handlers.get("agent_settled")({}, h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "ready");
+			assert.equal(await readFile(planFilePath(h.cwd), "utf8"), "# Plan");
+			await h.commands.get("plan").handler("approve current", h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "executing");
+			assert.equal(h.sent.some((message) => message.includes("Execute planned task 1")), true);
+		} finally { await h.close(); }
+	});
+
+	it("blocks and unblocks only the current task with reasons", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "executing");
+			await assert.rejects(() => h.tool.execute("call", { action: "block", id: 1, reason: "" }, undefined, undefined, h.ctx), /non-empty block reason/);
+			await h.tool.execute("call", { action: "block", id: 1, reason: "dependency" }, undefined, undefined, h.ctx);
+			assert.equal((await loadState(h.cwd))?.tasks?.["1"]?.status, "blocked");
+			await h.tool.execute("call", { action: "unblock", id: 1 }, undefined, undefined, h.ctx);
+			assert.equal((await loadState(h.cwd))?.tasks?.["1"]?.status, "pending");
+		} finally { await h.close(); }
+	});
+
+	it("restores executing framing on session start", async () => {
+		const h = await harness();
+		try {
+			await writeWorkflow(h.cwd, "executing");
+			await h.handlers.get("session_start")({}, h.ctx);
+			const injection = await h.handlers.get("before_agent_start")({}, h.ctx);
+			assert.equal(injection?.message?.details?.phase, "build");
+			assert.equal(injection?.message?.details?.taskId, 1);
+		} finally { await h.close(); }
+	});
+
+	it("supports revision, rejection, task review, and successful cascading rework", async () => {
+		const h = await harness();
+		try {
+			h.ctx.hasUI = true;
+			await writeWorkflow(h.cwd, "approved");
+			await h.commands.get("plan").handler("revise", h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "planning");
+			assert.equal(h.sent.some((message) => message.includes("Revise the current draft")), true);
+			await writeFile(draftPlanFilePath(h.cwd), "# Revised", "utf8");
+			await writeFile(draftTaskFilePath(h.cwd), TASK, "utf8");
+			await h.handlers.get("agent_settled")({}, h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "ready");
+			await h.commands.get("plan").handler("reject more detail", h.ctx);
+			assert.equal((await loadState(h.cwd))?.status, "planning");
+			assert.equal(h.sent.some((message) => message.includes("review feedback")), true);
+			await h.commands.get("tasks").handler("review 1", h.ctx);
+			assert.equal(h.notifications.some((message) => message.includes("Task 1: A")), true);
+		} finally { await h.close(); }
+		const rework = await harness();
+		try {
+			const checked = TASK.replace("- [ ] 1. A", "- [x] 1. A").replace("- [ ] 2. B", "- [x] 2. B");
+			let state = await writeWorkflow(rework.cwd, "executing", checked);
+			state = updateTaskState(state, 1, "verified", { verification: "one" });
+			state = updateTaskState(state, 2, "verified", { verification: "two" });
+			await saveState(rework.cwd, state);
+			await rework.commands.get("tasks").handler("rework 1", rework.ctx);
+			const next = await loadState(rework.cwd);
+			assert.equal(next?.status, "ready");
+			assert.equal(next?.approvedStructureHash, undefined);
+			assert.doesNotMatch(await readFile(taskFilePath(rework.cwd), "utf8"), /\[x\]/);
+		} finally { await rework.close(); }
+	});
+
+});

package/extensions/migration.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import { planDir, stateFilePath, taskFilePath } from "./paths.ts";
+import { loadState } from "./state.ts";
+
+async function tempProject<T>(run: (cwd: string) => Promise<T>): Promise<T> {
+	const cwd = await mkdtemp(join(tmpdir(), "pi-plan-task-migrate-"));
+	try { return await run(cwd); } finally { await rm(cwd, { recursive: true, force: true }); }
+}
+
+describe("state v1 migration", () => {
+	it("backs up v1 and requires old checked work to be verified again", async () => tempProject(async (cwd) => {
+		await mkdir(planDir(cwd), { recursive: true });
+		await writeFile(taskFilePath(cwd), "# Tasks\n\n- [x] 1. A\n- [x] 2. B\n", "utf8");
+		await writeFile(stateFilePath(cwd), JSON.stringify({
+			version: 1, status: "completed", executionMode: "automatic", updatedAt: "old",
+			tasks: { "1": { status: "implementation-complete" }, "2": { status: "verified", verification: "passed" } },
+		}), "utf8");
+		const state = await loadState(cwd);
+		assert.equal(state?.version, 2);
+		assert.equal(state?.status, "ready");
+		assert.equal(state?.tasks?.["1"]?.status, "implementation-complete");
+		assert.equal(state?.tasks?.["2"]?.status, "verified");
+		const task = await readFile(taskFilePath(cwd), "utf8");
+		assert.match(task, /- \[ \] 1\. A/);
+		assert.match(task, /- \[x\] 2\. B/);
+		const history = await readdir(join(planDir(cwd), "history"));
+		assert.equal(history.some((name) => name.startsWith("state-v1-")), true);
+		assert.equal(history.some((name) => name.startsWith("task-v1-")), true);
+	}));
+});

package/extensions/parse.ts

@@ -1,6 +1,7 @@
 import type { TaskItem } from "./types.ts";
 
-const NUMBERED_ITEM = /^[-*]\s+\[([ xX])\]\s+(\d+)\.\s+(.+)$/;
+export const NUMBERED_ITEM = /^-\s+\[([ xX])\]\s+(\d+)\.\s+(.+)$/;
+
 const PLAIN_ITEM = /^[-*]\s+\[([ xX])\]\s+(.+)$/;
 const TASK_HEADING = /^##\s+Task\s+(\d+)\b/i;
 
@@ -39,7 +40,7 @@ export function parseTaskMarkdown(raw: string): TaskItem[] {
 		const match = line.match(NUMBERED_ITEM);
 		if (!match) continue;
 		const id = Number(match[2]);
-		if (!Number.isFinite(id)) continue;
+		if (!Number.isInteger(id) || id <= 0) throw new Error("task.md task IDs must be positive integers");
 		numbered.push({
 			id,
 			title: match[3].trim(),
@@ -47,7 +48,13 @@ export function parseTaskMarkdown(raw: string): TaskItem[] {
 			body: extractBody(raw, id),
 		});
 	}
-	if (numbered.length > 0) return numbered;
+	if (numbered.length > 0) {
+		const ids = new Set(numbered.map((task) => task.id));
+		if (ids.size !== numbered.length) throw new Error("task.md contains duplicate task IDs");
+		const headingIds = [...raw.matchAll(/^##\s+Task\s+(\d+)\b/gim)].map((match) => Number(match[1]));
+		if (new Set(headingIds).size !== headingIds.length) throw new Error("task.md contains duplicate task headings");
+		return numbered;
+	}
 
 	const plain: TaskItem[] = [];
 	for (const line of checklist.split(/\r?\n/)) {
@@ -63,12 +70,24 @@ export function parseTaskMarkdown(raw: string): TaskItem[] {
 	}
 	return plain;
 }
+export function hasPendingTasks(raw: string, includeUnnumbered = false): boolean {
+	const lines = raw.split(/\r?\n/);
+	const firstTaskHeading = lines.findIndex((line) => TASK_HEADING.test(line));
+	const checklist = lines.slice(0, firstTaskHeading < 0 ? undefined : firstTaskHeading);
+	return checklist.some((line) => {
+		if (NUMBERED_ITEM.test(line)) return line.includes("[ ]");
+		return includeUnnumbered && /^[-*]\s+\[ \]\s+.+$/.test(line);
+	});
+}
 
 export function markTaskDoneInMarkdown(raw: string, id: number): string {
 	const lines = raw.split(/\r?\n/);
+	const checklistEnd = lines.findIndex((line) => TASK_HEADING.test(line));
+	const end = checklistEnd < 0 ? lines.length : checklistEnd;
 	let remaining = id;
 	let changed = false;
-	const next = lines.map((line) => {
+	const next = lines.map((line, index) => {
+		if (index >= end) return line;
 		const numbered = line.match(NUMBERED_ITEM);
 		if (numbered && Number(numbered[2]) === id && numbered[1] !== "x" && numbered[1] !== "X") {
 			changed = true;
@@ -86,3 +105,60 @@ export function markTaskDoneInMarkdown(raw: string, id: number): string {
 	});
 	return changed ? next.join("\n") : raw;
 }
+
+export function markTaskPendingInMarkdown(raw: string, id: number): string {
+	const lines = raw.split(/\r?\n/);
+	const checklistEnd = lines.findIndex((line) => TASK_HEADING.test(line));
+	const end = checklistEnd < 0 ? lines.length : checklistEnd;
+	let plainIndex = 0;
+	let changed = false;
+	const next = lines.map((line, index) => {
+		if (index >= end) return line;
+		const numbered = line.match(NUMBERED_ITEM);
+		if (numbered && Number(numbered[2]) === id && /[xX]/.test(numbered[1])) { changed = true; return line.replace(/\[[xX]\]/, "[ ]"); }
+		if (!numbered && PLAIN_ITEM.test(line)) { plainIndex += 1; if (plainIndex === id && /\[[xX]\]/.test(line)) { changed = true; return line.replace(/\[[xX]\]/, "[ ]"); } }
+		return line;
+	});
+	return changed ? next.join("\n") : raw;
+}
+
+export function normalizeTaskStructure(raw: string): string {
+	const lines = raw.split(/\r?\n/);
+	const firstHeading = lines.findIndex((line) => TASK_HEADING.test(line));
+	const end = firstHeading < 0 ? lines.length : firstHeading;
+	return lines.map((line, index) => {
+		if (index >= end) return line;
+		return NUMBERED_ITEM.test(line) ? line.replace(/\[[ xX]\]/, "[ ]") : line;
+	}).join("\n");
+}
+
+export function markTasksPendingFromMarkdown(raw: string, fromId: number): string {
+	const lines = raw.split(/\r?\n/);
+	const checklistEnd = lines.findIndex((line) => TASK_HEADING.test(line));
+	const end = checklistEnd < 0 ? lines.length : checklistEnd;
+	let plainIndex = 0;
+	let changed = false;
+	const next = lines.map((line, index) => {
+		if (index >= end) return line;
+		const numbered = line.match(NUMBERED_ITEM);
+		if (numbered && Number(numbered[2]) >= fromId && /[xX]/.test(numbered[1])) {
+			changed = true;
+			return line.replace(/\[[xX]\]/, "[ ]");
+		}
+		if (!numbered && PLAIN_ITEM.test(line)) {
+			plainIndex += 1;
+			if (plainIndex >= fromId && /\[[xX]\]/.test(line)) {
+				changed = true;
+				return line.replace(/\[[xX]\]/, "[ ]");
+			}
+		}
+		return line;
+	});
+	return changed ? next.join("\n") : raw;
+}
+
+export function hasStrictNumberedChecklist(raw: string): boolean {
+	const { checklist } = splitChecklist(raw);
+	const taskLines = checklist.split(/\r?\n/).filter((line) => /^[-*]\s+\[[ xX]\]\s+/.test(line));
+	return taskLines.length > 0 && taskLines.every((line) => NUMBERED_ITEM.test(line));
+}

package/extensions/paths.ts

@@ -1,39 +1,33 @@
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { lstatSync } from "node:fs";
 import { resolve } from "node:path";
-import { CONFIG_FILE_NAME, PLAN_DIR_NAME, PLAN_FILE_NAME, TASK_FILE_NAME } from "./types.ts";
-
-export function planDir(cwd: string): string {
-	return resolve(cwd, PLAN_DIR_NAME);
-}
-
-export function planFilePath(cwd: string): string {
-	return resolve(cwd, PLAN_DIR_NAME, PLAN_FILE_NAME);
-}
-
-export function taskFilePath(cwd: string): string {
-	return resolve(cwd, PLAN_DIR_NAME, TASK_FILE_NAME);
-}
-
-export function globalConfigPath(): string {
-	return resolve(getAgentDir(), CONFIG_FILE_NAME);
-}
-
-export function projectConfigPath(cwd: string): string {
-	return resolve(cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
-}
-
-export function samePath(a: string, b: string): boolean {
-	const left = resolve(a);
-	const right = resolve(b);
-	return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+import { CONFIG_FILE_NAME, DRAFT_DIR_NAME, HISTORY_DIR_NAME, PLAN_DIR_NAME, PLAN_FILE_NAME, STATE_FILE_NAME, TASK_FILE_NAME } from "./types.ts";
+
+export function planDir(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME); }
+export function planFilePath(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME, PLAN_FILE_NAME); }
+export function taskFilePath(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME, TASK_FILE_NAME); }
+export function stateFilePath(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME, STATE_FILE_NAME); }
+export function historyDir(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME, HISTORY_DIR_NAME); }
+export function draftDir(cwd: string): string { return resolve(cwd, PLAN_DIR_NAME, DRAFT_DIR_NAME); }
+export function draftPlanFilePath(cwd: string): string { return resolve(draftDir(cwd), PLAN_FILE_NAME); }
+export function draftTaskFilePath(cwd: string): string { return resolve(draftDir(cwd), TASK_FILE_NAME); }
+export function globalConfigPath(): string { return resolve(getAgentDir(), CONFIG_FILE_NAME); }
+export function projectConfigPath(cwd: string): string { return resolve(cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME); }
+export function samePath(a: string, b: string): boolean { const left = resolve(a), right = resolve(b); return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right; }
+export function stripAtPrefix(filePath: string): string { return filePath.startsWith("@") ? filePath.slice(1) : filePath; }
+
+function isSafeArtifact(cwd: string, absolute: string): boolean {
+	try {
+		if (lstatSync(planDir(cwd)).isSymbolicLink()) return false;
+		if (lstatSync(draftDir(cwd)).isSymbolicLink()) return false;
+		return !lstatSync(absolute).isSymbolicLink();
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ENOENT";
+	}
 }
 
 export function isPlanArtifactPath(cwd: string, filePath: string): boolean {
 	const absolute = resolve(cwd, stripAtPrefix(filePath));
-	return samePath(absolute, planFilePath(cwd)) || samePath(absolute, taskFilePath(cwd));
+	if (!samePath(absolute, draftPlanFilePath(cwd)) && !samePath(absolute, draftTaskFilePath(cwd))) return false;
+	return isSafeArtifact(cwd, absolute);
 }
-
-export function stripAtPrefix(filePath: string): string {
-	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
-}
-

package/extensions/planning-and-task-breakdown.md

@@ -24,8 +24,9 @@ Before writing any code, operate in read-only mode:
 - Identify existing patterns and conventions
 - Map dependencies between components
 - Note risks and unknowns
+- Resolve consequential user-answerable decisions before finalizing the plan; leave only non-blocking follow-ups in Open Questions
 
-**Do NOT write code during planning.** The output is a plan document saved to `.plan_task/plan.md` and a task list saved to `.plan_task/task.md`, not implementation.
+**Do NOT write code during planning.** The output is a plan document saved to `.plan_task/draft/plan.md` and a task list saved to `.plan_task/draft/task.md`, not implementation.
 
 ### Step 2: Identify the Dependency Graph
 
@@ -137,16 +138,16 @@ If a task is L or larger, it should be broken into smaller tasks. An agent perfo
 
 ## Output Files
 
-- **Plan document:** Save the implementation plan to `.plan_task/plan.md`. This is always a markdown file — design decisions, risks, and open questions don't map cleanly onto individual tracker issues.
-- **Task list:** Record each task in `.plan_task/task.md`.
+- **Plan document:** Save the implementation plan to `.plan_task/draft/plan.md`. This is always a markdown file — design decisions, risks, and open questions don't map cleanly onto individual tracker issues.
+- **Task list:** Record each task in `.plan_task/draft/task.md`.
 
 Create the `.plan_task/` directory if it does not exist.
 
-The checklist at the top of `.plan_task/task.md` is the source of truth for `/build`. Keep items in the form `- [ ] N. Title` so later sessions can resume.
+The checklist at the top of `.plan_task/draft/task.md` becomes the source of truth for `/build` after validation and submission. Keep items in the exact form `- [ ] N. Title` so later sessions can resume.
 
 After the checklist, write one `## Task [N]:` section per item using the Step 4 structure. Put `## Checkpoint:` sections after the tasks they cover, not in the top checklist.
 
-Example `.plan_task/task.md`:
+Example `.plan_task/draft/task.md`:
 
 ```markdown
 - [ ] 1. User can create an account
@@ -240,7 +241,7 @@ Example `.plan_task/task.md`:
 | [Risk] | [High/Med/Low] | [Strategy] |
 
 ## Open Questions
-- [Question needing human input]
+- [Optional non-blocking follow-up; resolve blocking decisions before writing the final plan]
 ```
 
 ## Parallelization Opportunities
@@ -263,7 +264,7 @@ When multiple agents or sessions are available:
 ## Red Flags
 
 - Starting implementation without a written task list
-- Writing tasks somewhere other than `.plan_task/task.md`
+- Writing tasks somewhere other than `.plan_task/draft/task.md`
 - Tasks that say "implement the feature" without acceptance criteria
 - No verification steps in the plan
 - All tasks are XL-sized
@@ -277,7 +278,7 @@ Before starting implementation, confirm:
 - [ ] Every task has acceptance criteria
 - [ ] Every task has a verification step
 - [ ] Task dependencies are identified and ordered correctly
-- [ ] Tasks are recorded in `.plan_task/task.md`
+- [ ] Tasks are recorded in `.plan_task/draft/task.md`
 - [ ] No task touches more than ~5 files
 - [ ] Checkpoints exist between major phases
 - [ ] The human has reviewed and approved the plan
@@ -285,3 +286,4 @@ Before starting implementation, confirm:
 ## See Also
 
 Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of any project-wide Definition of Done, the standing bar every task clears before it counts as done.
+

package/extensions/planning-method.test.ts

@@ -14,7 +14,20 @@ describe("loadPlanningMethod", () => {
 		assert.doesNotMatch(method, /^---/);
 		assert.doesNotMatch(method, /This skill/);
 		assert.doesNotMatch(method, /tasks\/todo\.md/);
-		assert.match(method, /\.plan_task\/plan\.md/);
-		assert.match(method, /\.plan_task\/task\.md/);
+		assert.match(method, /\.plan_task\/draft\/plan\.md/);
+		assert.match(method, /\.plan_task\/draft\/task\.md/);
+		assert.doesNotMatch(method, /`\.plan_task\/plan\.md`/);
+		assert.doesNotMatch(method, /`\.plan_task\/task\.md`/);
+		assert.match(method, /- \[ \] N\. Title/);
+		assert.match(method, /\*\*Description:\*\*/);
+		assert.match(method, /\*\*Acceptance criteria:\*\*/);
+		assert.match(method, /\*\*Verification:\*\*/);
+		assert.match(method, /\*\*Dependencies:\*\*/);
+		assert.match(method, /\*\*Files likely touched:\*\*/);
+		assert.match(method, /\*\*Estimated scope:\*\*/);
+		assert.match(method, /vertical slice/i);
+		assert.match(method, /Checkpoints exist between major phases/);
+		assert.match(method, /leave only non-blocking follow-ups in Open Questions/);
+		assert.doesNotMatch(method, /\[Question needing human input\]/);
 	});
 });

package/extensions/planning-method.ts

@@ -9,8 +9,10 @@ import { fileURLToPath } from "node:url";
  * root so later updates can be copied section-by-section from that file.
  *
  * Plan-task-only adaptations (do not copy these from the source blindly):
- * - Output paths are `.plan_task/plan.md` and `.plan_task/task.md`
- * - Checklist items must be `- [ ] N. Title`
+ * - Planning output paths are `.plan_task/draft/plan.md` and `.plan_task/draft/task.md`
+ * - Submitted plan/task files are never written directly in Plan mode
+ * - Checklist items must be `- [ ] N. Title` with unique positive IDs
+ * - Blocking questions are resolved before finalization; only non-blocking Open Questions remain
  * - No external tracker, no skill frontmatter, no definition-of-done.md link
  */
 export const PLANNING_METHOD_FILE = resolve(

package/extensions/policy.test.ts

@@ -0,0 +1,11 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isAllowedPlanTool } from "./tool-policy.ts";
+describe("plan policy", () => {
+	it("allows only read tools and coordination tools", () => {
+		assert.equal(isAllowedPlanTool("read"), true);
+		assert.equal(isAllowedPlanTool("bash"), false);
+		assert.equal(isAllowedPlanTool("write"), false);
+		assert.equal(isAllowedPlanTool("unknown"), false);
+	});
+});