pi-plans 0.3.2 → 0.3.3

package/tests/ask-choice.test.ts

@@ -262,3 +262,116 @@ describe("ask_choice panel fitting", () => {
 		assert.ok(totalLines < rows - STATUS_BAR_HEIGHT - PANEL_SAFETY_MARGIN);
 	});
 });
+
+describe("ask_choice checkpoint question lifecycle (I-003)", () => {
+	it("records pending before the panel opens and the answer before it returns", async () => {
+		const { spawnSync } = await import("node:child_process");
+		const { initState, startRun } = await import("../src/state.ts");
+		const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-ask-cp-"));
+		try {
+			spawnSync("git", ["init"], { cwd: workdir });
+			initState(workdir);
+			const { run } = startRun(workdir, { topic: "askcp", skill: "plan-small", requestText: "t" });
+			createCheckpoint(workdir, { runId: run.run_id, originWorkdir: workdir, workdir });
+
+			let pendingDuringPanel: unknown = null;
+			const tool = loadTool();
+			const ctx = makeCtx({
+				select: async (_question, labels) => {
+					pendingDuringPanel = loadCheckpoint(workdir, run.run_id);
+					return labels[0];
+				},
+			});
+			const result = await tool.execute("t1", {
+				question: "Scope ok?",
+				options: OPTIONS,
+				workdir,
+				questionId: "scope-confirm",
+				purpose: "scope",
+			}, undefined, undefined, ctx);
+			assert.match(result.content[0].text, /User selected: 1/);
+
+			// During the panel: the pending question is already durable.
+			const during = pendingDuringPanel as { status: string; checkpoint?: { pendingQuestion: unknown } };
+			assert.equal(during.status, "ok");
+			assert.ok(during.checkpoint?.pendingQuestion, "pending recorded before display");
+
+			// After the answer: cleared + answered with source user.
+			const after = loadCheckpoint(workdir, run.run_id);
+			assert.equal(after.status, "ok");
+			if (after.status === "ok") {
+				assert.equal(after.checkpoint.pendingQuestion, null);
+				assert.equal(after.checkpoint.answeredQuestions.length, 1);
+				assert.equal(after.checkpoint.answeredQuestions[0]?.questionId, "scope-confirm");
+				assert.equal(after.checkpoint.answeredQuestions[0]?.source, "user");
+			}
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+
+	it("keeps the pending question when the user cancels", async () => {
+		const { spawnSync } = await import("node:child_process");
+		const { initState, startRun } = await import("../src/state.ts");
+		const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-ask-cancel-"));
+		try {
+			spawnSync("git", ["init"], { cwd: workdir });
+			initState(workdir);
+			const { run } = startRun(workdir, { topic: "askcancel", skill: "plan-small", requestText: "t" });
+			createCheckpoint(workdir, { runId: run.run_id, originWorkdir: workdir, workdir });
+			const tool = loadTool();
+			const ctx = makeCtx({ select: async () => undefined });
+			const result = await tool.execute("t1", {
+				question: "Scope ok?",
+				options: OPTIONS,
+				workdir,
+				questionId: "scope-confirm",
+			}, undefined, undefined, ctx);
+			assert.match(result.content[0].text, /cancelled/i);
+			const loaded = loadCheckpoint(workdir, run.run_id);
+			if (loaded.status === "ok") {
+				assert.ok(loaded.checkpoint.pendingQuestion, "cancelled question stays pending for resume");
+				assert.equal(loaded.checkpoint.answeredQuestions.length, 0);
+			}
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+
+	it("skips checkpoint writes without questionId or without a checkpoint", async () => {
+		const { spawnSync } = await import("node:child_process");
+		const { initState, startRun } = await import("../src/state.ts");
+		const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-ask-skip-"));
+		try {
+			spawnSync("git", ["init"], { cwd: workdir });
+			initState(workdir);
+			const withCp = startRun(workdir, { topic: "withcp", skill: "plan-small", requestText: "t" }).run;
+			createCheckpoint(workdir, { runId: withCp.run_id, originWorkdir: workdir, workdir });
+			const noCp = startRun(workdir, { topic: "nocp", skill: "plan-small", requestText: "t" }).run;
+
+			const tool = loadTool();
+			const ctx = makeCtx({ select: async (_question, labels) => labels[0] });
+			// No questionId → no checkpoint mutation.
+			await tool.execute("t1", { question: "Q?", options: OPTIONS, workdir }, undefined, undefined, ctx);
+			let loaded = loadCheckpoint(workdir, withCp.run_id);
+			if (loaded.status === "ok") {
+				assert.equal(loaded.checkpoint.pendingQuestion, null);
+				assert.equal(loaded.checkpoint.answeredQuestions.length, 0);
+			}
+			// questionId but the active run has no checkpoint → silent skip.
+			const result = await tool.execute("t2", {
+				question: "Q?",
+				options: OPTIONS,
+				workdir,
+				questionId: "q-no-cp",
+			}, undefined, undefined, ctx);
+			assert.match(result.content[0].text, /User selected/);
+			assert.equal(loadCheckpoint(workdir, noCp.run_id).status, "missing");
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+});

package/tests/compaction.test.ts

@@ -10,6 +10,7 @@ import {
 	DEFAULT_VCC_SETTINGS,
 	loadVccSettings,
 	parseCompactionInstructions,
+	PLANNING_PREPLAN_COMPACT_HINT,
 	PI_VCC_COMPACT_INSTRUCTION,
 	scaffoldVccSettings,
 	shouldScheduleAutoContinue,
@@ -386,3 +387,41 @@ describe("pi-vcc compaction", () => {
 		}
 	});
 });
+describe("pre-plan compaction settings and hint", () => {
+	let tmpRoot: string;
+
+	before(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-preplan-vcc-"));
+	});
+
+	after(() => {
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("parses the pre-plan compaction hint as an internal pi-plans instruction", () => {
+		assert.equal(DEFAULT_VCC_SETTINGS.prePlanCompact, true);
+		assert.deepEqual(parseCompactionInstructions(PLANNING_PREPLAN_COMPACT_HINT), {
+			isPiVcc: false,
+			isInternalPiPlans: true,
+			keepUserTurns: 1,
+			keepUserTurnsExplicit: false,
+			followUpPrompt: null,
+		});
+	});
+
+	it("fills a missing prePlanCompact key and honors an explicit false", () => {
+		const stateRoot = path.join(tmpRoot, "state");
+		fs.mkdirSync(stateRoot, { recursive: true });
+		fs.writeFileSync(vccSettingsPath(stateRoot), JSON.stringify({ debug: true }), "utf8");
+		scaffoldVccSettings(stateRoot);
+		assert.deepEqual(loadVccSettings(stateRoot), { ...DEFAULT_VCC_SETTINGS, debug: true });
+
+		fs.writeFileSync(
+			vccSettingsPath(stateRoot),
+			JSON.stringify({ ...DEFAULT_VCC_SETTINGS, prePlanCompact: false }),
+			"utf8",
+		);
+		scaffoldVccSettings(stateRoot);
+		assert.equal(loadVccSettings(stateRoot).prePlanCompact, false);
+	});
+});

package/tests/exec.test.ts

@@ -15,6 +15,7 @@ import {
 	completeExecution,
 	consumePendingExecutionFlush,
 	consumePlanningCompactionResumeGuard,
+	consumePrePlanCompactPending,
 	drainExecutionFlush,
 	executionContextMessage,
 	filterExecutionResumeMessages,
@@ -31,11 +32,15 @@ import {
 	handlePlanningCompact,
 	handlePlanningCompactFailed,
 	isExecutionComplete,
+	markPrePlanCompactPending,
 	PLANNING_PLAN_WRITTEN_CUSTOM_TYPE,
+	PLANNING_PREPLAN_COMPACT_HINT,
+	PLANNING_PREPLAN_RESUME_CUSTOM_TYPE,
 	PLANNING_RUN_START_CUSTOM_TYPE,
 	refreshPlanningCompactionCooldown,
 	requestPlanningCompaction,
 	restoreFromSession,
+	sendPrePlanCompactResume,
 	shouldTriggerPlanningCompaction,
 	startExecution,
 	recordExecutionTurn,
@@ -43,6 +48,7 @@ import {
 	stopExecution,
 	updateStatusWidget,
 } from "../src/exec.ts";
+import { buildPiPlansVccCompaction, loadVccSettings } from "../src/compaction.ts";
 import type { CheckItem } from "../src/plan.ts";
 import { initState, setGraphEnabled, setRunStatus, startRun } from "../src/state.ts";
 
@@ -1464,3 +1470,247 @@ describe("amelioration termination prompt", () => {
 		assert.match(AMELIORATION_PROMPT_TEXT, /How should the implementation-review loop terminate\?/);
 	});
 });
+
+describe("checkpoint-backed execution restore (I-005)", () => {
+	it("startExecution records approval (plan digest + HEAD) and progress in the checkpoint", async () => {
+		const { loadExecutionFromCheckpoint } = await import("../src/exec.ts");
+		const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+		const { resetRunBindingForTests } = await import("../src/run-context.ts");
+		resetRunBindingForTests();
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-exec-cp-"));
+		try {
+			const { spawnSync } = await import("node:child_process");
+			spawnSync("git", ["init"], { cwd: workdir });
+			spawnSync("git", ["config", "user.email", "t@e.com"], { cwd: workdir });
+			spawnSync("git", ["config", "user.name", "T"], { cwd: workdir });
+			initState(workdir);
+			const { run } = startRun(workdir, { topic: "exec-cp", skill: "plan-normal", requestText: "t" });
+			createCheckpoint(workdir, { runId: run.run_id, originWorkdir: workdir, workdir });
+			const artifactDir = run.artifact_dir;
+			fs.mkdirSync(artifactDir, { recursive: true });
+			const planPath = path.join(artifactDir, "PLAN_v1.md");
+			fs.writeFileSync(
+				planPath,
+				"# Plan\n\n## Verifier Checklist\n\n- [ ] `VC-001` covers `I-001`; pass condition: x.\n- [ ] `VC-002` covers `I-002`; pass condition: y.\n",
+				"utf8",
+			);
+			spawnSync("git", ["add", "-A"], { cwd: workdir });
+			spawnSync("git", ["commit", "-m", "init"], { cwd: workdir });
+
+			const harness = makeHarness(workdir);
+			const items: CheckItem[] = [
+				{ id: "VC-001", text: "covers I-001", done: false },
+				{ id: "VC-002", text: "covers I-002", done: false },
+			];
+			await startExecution(harness.pi, harness.ctx, planPath, items);
+
+			const loaded = loadCheckpoint(workdir, run.run_id);
+			assert.equal(loaded.status, "ok");
+			if (loaded.status === "ok") {
+				assert.equal(loaded.checkpoint.phase, "executing");
+				const approval = loaded.checkpoint.execution?.approval;
+				assert.ok(approval, "approval recorded");
+				assert.match(approval!.headAtApproval ?? "", /^[0-9a-f]{40}$/, "HEAD at approval");
+				assert.equal(approval!.plan.path, planPath);
+			}
+
+			// Progress lands in the checkpoint.
+			applyDoneMarkers("[DONE:VC-001]");
+			recordExecutionTurn(harness.pi, harness.ctx, ["VC-001"], { input: 5, output: 2 });
+			const afterProgress = loadCheckpoint(workdir, run.run_id);
+			if (afterProgress.status === "ok") {
+				assert.deepEqual(afterProgress.checkpoint.execution?.doneVcIds, ["VC-001"]);
+				assert.equal(afterProgress.checkpoint.execution?.usage.inToks, 5);
+			}
+
+			// Cross-session restore: fresh harness (new session), load from checkpoint.
+			resetRunBindingForTests();
+			const harness2 = makeHarness(workdir);
+			const restore = loadExecutionFromCheckpoint(harness2.pi, harness2.ctx, run.run_id);
+			assert.equal(restore.status, "loaded");
+			assert.deepEqual(restore.doneVcIds, ["VC-001"]);
+			assert.equal(restore.reverifyAll, false, "same HEAD keeps verified VCs");
+			assert.equal(getExecution()?.items.find((item) => item.id === "VC-001")?.done, true);
+			// F-002: an immediate session snapshot was appended.
+			const snapshots = harness2.recorded.entries.filter((entry) => entry.customType === "pi-plans-exec");
+			assert.ok(snapshots.length >= 1, "session snapshot written on load");
+
+			// Stop keeps progress with pausedReason (D-008).
+			await stopExecution(harness2.pi, harness2.ctx, "stopped by user");
+			const stopped = loadCheckpoint(workdir, run.run_id);
+			if (stopped.status === "ok") {
+				assert.equal(stopped.checkpoint.execution?.pausedReason, "stopped by user");
+				assert.deepEqual(stopped.checkpoint.execution?.doneVcIds, ["VC-001"]);
+			}
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+
+	it("HEAD change after approval keeps authorization but re-verifies VCs (D-011)", async () => {
+		const { loadExecutionFromCheckpoint } = await import("../src/exec.ts");
+		const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+		const { resetRunBindingForTests } = await import("../src/run-context.ts");
+		resetRunBindingForTests();
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-exec-head-"));
+		try {
+			const { spawnSync } = await import("node:child_process");
+			spawnSync("git", ["init"], { cwd: workdir });
+			spawnSync("git", ["config", "user.email", "t@e.com"], { cwd: workdir });
+			spawnSync("git", ["config", "user.name", "T"], { cwd: workdir });
+			initState(workdir);
+			const { run } = startRun(workdir, { topic: "exec-head", skill: "plan-normal", requestText: "t" });
+			createCheckpoint(workdir, { runId: run.run_id, originWorkdir: workdir, workdir });
+			fs.mkdirSync(run.artifact_dir, { recursive: true });
+			const planPath = path.join(run.artifact_dir, "PLAN_v1.md");
+			fs.writeFileSync(
+				planPath,
+				"# Plan\n\n## Verifier Checklist\n\n- [ ] `VC-001` covers `I-001`; pass condition: x.\n",
+				"utf8",
+			);
+			spawnSync("git", ["add", "-A"], { cwd: workdir });
+			spawnSync("git", ["commit", "-m", "one"], { cwd: workdir });
+
+			const harness = makeHarness(workdir);
+			await startExecution(harness.pi, harness.ctx, planPath, [
+				{ id: "VC-001", text: "covers I-001", done: false },
+			]);
+			applyDoneMarkers("[DONE:VC-001]");
+			recordExecutionTurn(harness.pi, harness.ctx, ["VC-001"]);
+
+			// Simulate a branch switch / reset under the unchanged plan.
+			spawnSync("git", ["commit", "--allow-empty", "-m", "two"], { cwd: workdir });
+
+			resetRunBindingForTests();
+			const harness2 = makeHarness(workdir);
+			const restore = loadExecutionFromCheckpoint(harness2.pi, harness2.ctx, run.run_id);
+			assert.equal(restore.status, "loaded");
+			assert.deepEqual(restore.doneVcIds, ["VC-001"], "historical evidence kept");
+			assert.equal(restore.reverifyAll, true, "HEAD change forces re-verification");
+			assert.equal(getExecution()?.items[0]?.done, false, "old VC not auto-passed");
+			// Authorization survives.
+			const cp = loadCheckpoint(workdir, run.run_id);
+			if (cp.status === "ok") {
+				assert.ok(cp.checkpoint.execution?.approval, "authorization kept");
+				assert.equal(cp.checkpoint.execution?.reverifyAll, true);
+			}
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("pre-plan compaction (start-run trigger)", () => {
+	let tmpRoot: string;
+	let counter = 0;
+
+	before(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-preplan-"));
+	});
+
+	after(() => {
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	async function preplanHarness() {
+		const piPlansExtension = (await import("../index.ts")).default;
+		const harness = makeHarness(path.join(tmpRoot, `ws-${++counter}`));
+		fs.mkdirSync(harness.ctx.cwd, { recursive: true });
+		piPlansExtension(harness.pi as never);
+		return harness;
+	}
+
+	it("routes the pre-plan hint through the planning VCC path for a fresh run", () => {
+		// Pure-builder assertion (order-independent): the getExecution() gate on
+		// buildPlanningCompactionResult is covered by the planning-hook tests.
+		const workdir = path.join(tmpRoot, `hint-${++counter}`);
+		fs.mkdirSync(workdir, { recursive: true });
+		initState(workdir);
+		const { run } = startRun(workdir, { topic: "preplan hint", skill: "plan-normal", requestText: "x" });
+		const built = buildPiPlansVccCompaction({
+			branchEntries: compactableBranchEntries(),
+			preparation: makePreparation("manual", null),
+			customInstructions: PLANNING_PREPLAN_COMPACT_HINT,
+			reason: "manual",
+			willRetry: false,
+			settings: loadVccSettings(path.join(workdir, ".git", "pi_plans")),
+			phaseContext: { phase: "planning", runId: run.run_id, artifactDir: run.artifact_dir },
+		});
+		assert.equal(built.kind, "compaction", "pre-plan hint must produce a VCC compaction, not a cancel/fallback");
+		if (built.kind !== "compaction") return;
+		assert.equal((built.compaction.details as { compactor: string }).compactor, "pi-vcc");
+		assert.equal((built.compaction.details as { phase: string }).phase, "planning");
+		assert.match(built.compaction.summary, /\[Session Goal\]/);
+	});
+
+	it("marks and consumes the pending flag exactly once", () => {
+		const harness = makeHarness(path.join(tmpRoot, `flag-${++counter}`));
+		assert.equal(consumePrePlanCompactPending(harness.ctx), null);
+		markPrePlanCompactPending(harness.ctx, "run-1");
+		assert.deepEqual(consumePrePlanCompactPending(harness.ctx), { runId: "run-1" });
+		assert.equal(consumePrePlanCompactPending(harness.ctx), null);
+	});
+
+	it("compacts once from the plans tool_result and resumes exactly once on success", async () => {
+		const harness = await preplanHarness();
+		const { ctx, recorded, emit } = harness;
+		markPrePlanCompactPending(ctx, "run-a");
+
+		// Non-plans tool results never consume the pending flag.
+		await emit("tool_result", { type: "tool_result", toolName: "edit", input: { path: "x" }, isError: false });
+		assert.equal(recorded.compacts?.length ?? 0, 0);
+		assert.equal(recorded.messages.length, 0);
+
+		await emit("tool_result", { type: "tool_result", toolName: "plans", input: { action: "start-run" }, isError: false });
+		assert.equal(recorded.compacts?.length, 1);
+		assert.equal(recorded.compacts?.[0]?.customInstructions, PLANNING_PREPLAN_COMPACT_HINT);
+		assert.equal(recorded.messages.length, 0, "no resume before the compaction settles");
+
+		recorded.compacts?.[0]?.onComplete?.({} as never);
+		assert.equal(recorded.messages.length, 1);
+		assert.equal(recorded.messages[0]?.customType, PLANNING_PREPLAN_RESUME_CUSTOM_TYPE);
+		assert.equal(recorded.messages[0]?.content, "Continue planning.");
+		assert.equal((recorded.messages[0] as { display?: boolean }).display, false);
+		assert.equal((recorded.messages[0] as { options?: { triggerTurn?: boolean } }).options?.triggerTurn, true);
+
+		// Pending flag consumed: a second plans result neither compacts nor resumes.
+		await emit("tool_result", { type: "tool_result", toolName: "plans", input: { action: "record-decision" }, isError: false });
+		assert.equal(recorded.compacts?.length, 1);
+		recorded.compacts?.[0]?.onComplete?.({} as never);
+		assert.equal(recorded.messages.length, 1);
+	});
+
+	it("resumes exactly once with an info notice when compaction fails", async () => {
+		const harness = await preplanHarness();
+		const { ctx, recorded } = harness;
+		(ctx as { compact?: unknown }).compact = (options: { onError?: (error: Error) => void }) => {
+			options.onError?.(new Error("Nothing to compact (session too small)"));
+		};
+		markPrePlanCompactPending(ctx, "run-b");
+		await harness.emit("tool_result", { type: "tool_result", toolName: "plans", input: { action: "start-run" }, isError: false });
+		assert.equal(recorded.messages.length, 1, "resume exactly once despite the failure");
+		assert.equal(recorded.messages[0]?.customType, PLANNING_PREPLAN_RESUME_CUSTOM_TYPE);
+		assert.deepEqual(recorded.notifies.at(-1), {
+			message: "pi-plans: pre-plan compaction skipped; continuing planning.",
+			severity: "info",
+		});
+	});
+
+	it("skips silently and still resumes when ctx.compact is unavailable (older Pi)", async () => {
+		const harness = await preplanHarness();
+		(harness.ctx as { compact?: unknown }).compact = undefined;
+		markPrePlanCompactPending(harness.ctx, "run-c");
+		await harness.emit("tool_result", { type: "tool_result", toolName: "plans", input: { action: "start-run" }, isError: false });
+		assert.equal(harness.recorded.messages.length, 1);
+		assert.equal(harness.recorded.messages[0]?.customType, PLANNING_PREPLAN_RESUME_CUSTOM_TYPE);
+	});
+
+	it("filters the pre-plan resume message out of the model context payload", () => {
+		const messages = [
+			{ customType: "user", content: "real prompt" },
+			{ customType: PLANNING_PREPLAN_RESUME_CUSTOM_TYPE, content: "Continue planning." },
+			{ customType: "assistant", content: "ok" },
+		];
+		assert.equal(filterPlanningResumeMessages(messages).length, 2);
+	});
+});

package/tests/guard.test.ts

@@ -94,3 +94,49 @@ describe("planning write guard", () => {
 		assert.equal(planningWriteBlockReason({ workdir, toolName: "write", rawPath: "src/main.ts" }), null);
 	});
 });
+
+describe("session-bound guard run (I-002)", () => {
+	it("activeRunId overrides the shared pointer; null falls back", () => {
+		const workdir = path.join(tmpRoot, "repo-bound");
+		fs.mkdirSync(workdir);
+		initState(workdir);
+		const first = startRun(workdir, { topic: "first run", skill: "plan-small", requestText: "x" }).run;
+		const second = startRun(workdir, { topic: "second run", skill: "plan-small", requestText: "x" }).run;
+
+		// Shared pointer names `second`; this session works on `first`.
+		const bound = planningWriteBlockReason({
+			workdir,
+			toolName: "write",
+			rawPath: path.relative(workdir, path.join(first.artifact_dir, "PLAN_v1.md")),
+			activeRunId: first.run_id,
+		});
+		assert.equal(bound, null, "bound run artifacts stay writable");
+
+		// The other run's artifacts are NOT writable for the bound session.
+		const other = planningWriteBlockReason({
+			workdir,
+			toolName: "write",
+			rawPath: path.relative(workdir, path.join(second.artifact_dir, "PLAN_v1.md")),
+			activeRunId: first.run_id,
+		});
+		assert.ok(other);
+
+		// null = no session binding → legacy shared-pointer behavior.
+		const shared = planningWriteBlockReason({
+			workdir,
+			toolName: "write",
+			rawPath: path.relative(workdir, path.join(first.artifact_dir, "PLAN_v1.md")),
+			activeRunId: null,
+		});
+		assert.ok(shared, "shared pointer names second; first is not writable");
+
+		// A binding to a missing run falls back to the shared pointer.
+		const vanished = planningWriteBlockReason({
+			workdir,
+			toolName: "write",
+			rawPath: path.relative(workdir, path.join(second.artifact_dir, "PLAN_v1.md")),
+			activeRunId: "20990101T000000Z-gone",
+		});
+		assert.equal(vanished, null);
+	});
+});

package/tests/plans.test.ts

@@ -1,7 +1,9 @@
 /** Tests for the plans tool source wiring. */
 
 import * as assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
 import { describe, it } from "node:test";
@@ -45,3 +47,72 @@ describe("plans tool source", () => {
 		assert.match(source, /"reviewer", "criticizer", "ref-analyst"/);
 	});
 });
+
+describe("record-checkpoint transitions (I-003)", () => {
+	it("records plan identity and rejects forged terminal states", async () => {
+		const { recordCheckpointTransition } = await import("../tools/plans.ts");
+		const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-rcp-"));
+		try {
+			spawnSync("git", ["init"], { cwd: workdir });
+			const { initState, startRun } = await import("../src/state.ts");
+			initState(workdir);
+			const { run } = startRun(workdir, { topic: "rcp", skill: "plan-normal", requestText: "t" });
+			const { createCheckpoint, loadCheckpoint } = await import("../src/workflow-state.ts");
+			createCheckpoint(workdir, { runId: run.run_id, originWorkdir: workdir, workdir });
+			const ctx = { sessionManager: { id: "s" } };
+
+			// plan-written records the exact file identity.
+			const planPath = path.join(run.artifact_dir, "PLAN_v1.md");
+			fs.mkdirSync(run.artifact_dir, { recursive: true });
+			fs.writeFileSync(planPath, "# plan body", "utf8");
+			const updated = recordCheckpointTransition(ctx, workdir, run.run_id, {
+				transition: "plan-written",
+				planPath,
+			});
+			assert.equal(updated.plan?.version, 1);
+			assert.equal(updated.plan?.sha256.length, 64);
+			const loaded = loadCheckpoint(workdir, run.run_id);
+			assert.equal(loaded.status, "ok");
+			assert.equal(loaded.checkpoint.plan?.path, planPath);
+
+			// completed without evidence is rejected (F-004).
+			assert.throws(
+				() => recordCheckpointTransition(ctx, workdir, run.run_id, { transition: "completed" }),
+				/evidence/,
+			);
+			// completed from the planning phase is rejected even with evidence.
+			assert.throws(
+				() => recordCheckpointTransition(ctx, workdir, run.run_id, { transition: "completed", evidence: "done" }),
+				/cannot complete from phase/,
+			);
+			// planPath is required.
+			assert.throws(
+				() => recordCheckpointTransition(ctx, workdir, run.run_id, { transition: "plan-written" }),
+				/planPath/,
+			);
+		} finally {
+			fs.rmSync(workdir, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("pre-plan compaction wiring", () => {
+	it("start-run marks pre-plan compaction pending under settings and execution guards", () => {
+		const source = readPlansSource();
+		assert.match(source, /import \{ getExecution, markPrePlanCompactPending \} from "\.\.\/src\/exec\.ts";/);
+		assert.match(source, /import \{ loadVccSettings, scaffoldVccSettings \} from "\.\.\/src\/compaction\.ts";/);
+		assert.match(source, /const prePlanStateRoot = resolveStateRootOrNull\(workdir\);/);
+		assert.match(source, /if \(prePlanStateRoot && !getExecution\(\)\) \{/);
+		assert.match(source, /scaffoldVccSettings\(prePlanStateRoot\);/);
+		assert.match(source, /loadVccSettings\(prePlanStateRoot\)\.prePlanCompact/);
+		assert.match(source, /markPrePlanCompactPending\(ctx, result\.run\.run_id\);/);
+	});
+
+	it("index.ts consumes the pending flag from the plans tool_result hook", () => {
+		const source = fs.readFileSync(path.join(ROOT, "index.ts"), "utf8");
+		assert.match(source, /consumePrePlanCompactPending/);
+		assert.match(source, /customInstructions: PLANNING_PREPLAN_COMPACT_HINT/);
+		assert.match(source, /sendPrePlanCompactResume\(pi\)/);
+		assert.match(source, /pre-plan compaction skipped; continuing planning\./);
+	});
+});