tdd-enforcer 0.2.7 → 0.2.9

package/adapters/pi/hooks.ts

@@ -120,7 +120,7 @@ export async function handleToolCall(
 		return {
 			block: true,
 			reason:
-				"TDD: Config files are locked. No bypassing TDD allowed. If bypassing is justified, ask the user: turn TDD off (/tdd:off), reset (/tdd:reset), or change phase via /tdd commands.",
+				"TDD: Config files are locked. No bypassing TDD allowed. If bypassing is justified, ask the user: turn TDD off (/tdd:off), reset (/tdd:reset), or change phase via /tdd commands.\n\nIf TDD reverts too much of your progress, reduce the scope of each TDD cycle to minimise lost progress.",
 		};
 	}
 
@@ -267,6 +267,9 @@ function formatWarning(
 		.join("");
 	let warning = `\n\n⛔ ${phase.toUpperCase()}: reverted locked files modified by bash:`;
 	for (const f of cmdViolations) warning += `\n  - ${f}`;
+	if (cmdViolations.some((f) => f.startsWith(".pi/tdd/"))) {
+		warning += `\n\nIf TDD reverts too much of your progress, reduce the scope of each TDD cycle to minimise lost progress.`;
+	}
 	if (cmdAllowed.length > 0) {
 		warning += `\n\nAllowed changes retained:`;
 		for (const f of cmdAllowed) warning += `\n  - ${f}`;

package/adapters/pi/index.test.ts

@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
+	handleBeforeAgentStart,
+	handleTddJump,
 	handleTddOff,
 	handleTddOn,
 	handleTddReset,
@@ -310,3 +312,195 @@ describe("handleTddReset", () => {
 		expect(ctx.notifications[0].type).toBe("error");
 	});
 });
+
+// ── handleTddJump ───────────────────────────────────────────────────────────
+
+describe("handleTddJump", () => {
+	let mockLoadTddState: ReturnType<typeof vi.fn>;
+	let mockSnapshot: ReturnType<typeof vi.fn>;
+	let mockSavePhaseState: ReturnType<typeof vi.fn>;
+	let mockTddLog: ReturnType<typeof vi.fn>;
+
+	function makeDeps(overrides = {}) {
+		return {
+			loadTddState: mockLoadTddState,
+			snapshot: mockSnapshot,
+			savePhaseState: mockSavePhaseState,
+			tddLog: mockTddLog,
+			...overrides,
+		};
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLoadTddState = vi.fn();
+		mockSnapshot = vi.fn().mockReturnValue("snap123");
+		mockSavePhaseState = vi.fn();
+		mockTddLog = vi.fn();
+	});
+
+	function tddOk(overrides?: { current?: string; enabled?: boolean }) {
+		return {
+			ok: true as const,
+			state: {
+				enabled: overrides?.enabled ?? true,
+				current: overrides?.current ?? "red",
+			},
+			config,
+		};
+	}
+
+	it("shows error when TDD not setup", async () => {
+		mockLoadTddState.mockReturnValue({ ok: false, reason: "Missing .pi/tdd/" });
+		const ctx = makeCtx();
+		await handleTddJump("green", ctx, makeDeps());
+		expect(ctx.notifications[0].message).toContain("Missing");
+		expect(ctx.notifications[0].type).toBe("error");
+		expect(mockSavePhaseState).not.toHaveBeenCalled();
+	});
+
+	it("notifies no-op when already in target phase", async () => {
+		mockLoadTddState.mockReturnValue(tddOk({ current: "green" }));
+		const ctx = makeCtx();
+		await handleTddJump("green", ctx, makeDeps());
+		expect(ctx.notifications[0].message).toContain("already in GREEN");
+		expect(ctx.notifications[0].type).toBe("info");
+		expect(mockSnapshot).not.toHaveBeenCalled();
+		expect(mockSavePhaseState).not.toHaveBeenCalled();
+	});
+
+	it("snapshots, auto-enables, jumps phase, notifies", async () => {
+		mockLoadTddState.mockReturnValue(tddOk({ current: "red", enabled: true }));
+		const ctx = makeCtx();
+		await handleTddJump("green", ctx, makeDeps());
+
+		expect(mockSnapshot).toHaveBeenCalledWith("/test", "red");
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "green",
+		});
+		expect(ctx.notifications[0].message).toContain("Skipped to GREEN phase");
+		expect(ctx.notifications[0].type).toBe("info");
+	});
+
+	it("auto-enables when TDD disabled", async () => {
+		mockLoadTddState.mockReturnValue(tddOk({ current: "red", enabled: false }));
+		const ctx = makeCtx();
+		await handleTddJump("green", ctx, makeDeps());
+
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "green",
+		});
+		expect(ctx.notifications[0].message).toContain("Skipped to GREEN phase");
+	});
+
+	it("works for refactor from green", async () => {
+		mockLoadTddState.mockReturnValue(tddOk({ current: "green" }));
+		const ctx = makeCtx();
+		await handleTddJump("refactor", ctx, makeDeps());
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "refactor",
+		});
+		expect(ctx.notifications[0].message).toContain("Skipped to REFACTOR phase");
+	});
+
+	it("works for red from green", async () => {
+		mockLoadTddState.mockReturnValue(tddOk({ current: "green" }));
+		const ctx = makeCtx();
+		await handleTddJump("red", ctx, makeDeps());
+		expect(mockSavePhaseState).toHaveBeenCalledWith("/test", {
+			enabled: true,
+			current: "red",
+		});
+		expect(ctx.notifications[0].message).toContain("Skipped to RED phase");
+	});
+});
+
+// ── handleBeforeAgentStart ──────────────────────────────────────────────────
+
+describe("handleBeforeAgentStart", () => {
+	let mockLoadTddState: ReturnType<typeof vi.fn>;
+
+	function makeDeps(overrides = {}) {
+		return {
+			loadTddState: mockLoadTddState,
+			...overrides,
+		};
+	}
+
+	function makeEvent(): {
+		systemPromptOptions: { promptGuidelines: string[] };
+	} {
+		return { systemPromptOptions: { promptGuidelines: [] } };
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLoadTddState = vi.fn();
+	});
+
+	it("pushes guidelines when TDD enabled", async () => {
+		mockLoadTddState.mockReturnValue({
+			ok: true,
+			state: { enabled: true, current: "red" },
+			config: {
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		});
+		const event = makeEvent();
+		await handleBeforeAgentStart(
+			event as any,
+			{ cwd: "/test" } as any,
+			makeDeps(),
+		);
+		expect(event.systemPromptOptions.promptGuidelines).toHaveLength(3);
+		expect(event.systemPromptOptions.promptGuidelines[0]).toContain(
+			"locked files will be blocked",
+		);
+		expect(event.systemPromptOptions.promptGuidelines[1]).toContain(
+			"next_tdd_phase",
+		);
+		expect(event.systemPromptOptions.promptGuidelines[2]).toContain(
+			"cycle so reverting is cheap",
+		);
+	});
+
+	it("does not push guidelines when TDD not setup", async () => {
+		mockLoadTddState.mockReturnValue({
+			ok: false,
+			reason: "Missing .pi/tdd/",
+		});
+		const event = makeEvent();
+		await handleBeforeAgentStart(
+			event as any,
+			{ cwd: "/test" } as any,
+			makeDeps(),
+		);
+		expect(event.systemPromptOptions.promptGuidelines).toHaveLength(0);
+	});
+
+	it("does not push guidelines when TDD disabled", async () => {
+		mockLoadTddState.mockReturnValue({
+			ok: true,
+			state: { enabled: false, current: "red" },
+			config: {
+				blockedInRed: [],
+				blockedInGreen: [],
+				testCommands: [],
+				timeoutSeconds: 30,
+			},
+		});
+		const event = makeEvent();
+		await handleBeforeAgentStart(
+			event as any,
+			{ cwd: "/test" } as any,
+			makeDeps(),
+		);
+		expect(event.systemPromptOptions.promptGuidelines).toHaveLength(0);
+	});
+});

package/adapters/pi/index.ts

@@ -148,6 +148,77 @@ export async function handleTddStatus(
 	);
 }
 
+export async function handleBeforeAgentStart(
+	event: {
+		systemPromptOptions: { promptGuidelines: string[] };
+	},
+	ctx: { cwd: string },
+	deps: {
+		loadTddState: typeof loadTddState;
+	},
+): Promise<void> {
+	const tdd = deps.loadTddState(ctx.cwd);
+	if (!tdd.ok || !tdd.state.enabled) return;
+
+	event.systemPromptOptions.promptGuidelines.push(
+		"You are working under TDD enforcement. Each phase restricts which files you can modify — locked files will be blocked automatically.",
+		"Use `next_tdd_phase` to advance through the cycle, `previous_tdd_phase` to revert a phase, `tdd_status` to check current phase and blocked file rules.",
+		"Minimise the scope of each TDD cycle so reverting is cheap.",
+	);
+}
+
+export async function handleTddJump(
+	phase: "red" | "green" | "refactor",
+	ctx: ExtensionContext,
+	deps: {
+		loadTddState: typeof loadTddState;
+		snapshot: typeof snapshot;
+		savePhaseState: typeof savePhaseState;
+		tddLog: typeof tddLog;
+	} = {
+		loadTddState,
+		snapshot,
+		savePhaseState,
+		tddLog,
+	},
+): Promise<void> {
+	const root = ctx.cwd;
+	const tddDir = join(root, ".pi", "tdd");
+
+	const setup = deps.loadTddState(root);
+	if (!setup.ok) {
+		deps.tddLog(tddDir, "WARN", `tdd:${phase}: setup invalid`, {
+			reason: setup.reason,
+		});
+		ctx.ui.notify(setup.reason, "error");
+		return;
+	}
+
+	const { state } = setup;
+
+	if (state.current === phase) {
+		deps.tddLog(tddDir, "INFO", `tdd:${phase}: already in ${phase}`, {
+			phase,
+		});
+		ctx.ui.notify(`TDD: already in ${phase.toUpperCase()} phase.`, "info");
+		return;
+	}
+
+	// Snapshot the current phase's work before jumping
+	deps.snapshot(root, state.current);
+	deps.tddLog(tddDir, "INFO", `tdd:${phase}: snapshot taken`, {
+		from: state.current,
+	});
+
+	// Auto-enable if disabled, set phase
+	state.enabled = true;
+	state.current = phase;
+	deps.savePhaseState(root, state);
+
+	deps.tddLog(tddDir, "INFO", `tdd:${phase}: jumped`);
+	ctx.ui.notify(`Skipped to ${phase.toUpperCase()} phase.`, "info");
+}
+
 export async function handleTddReset(
 	ctx: ExtensionContext,
 	deps: {
@@ -239,6 +310,20 @@ export default function (pi: ExtensionAPI) {
 			handleTddReset(ctx, { ...defaultDeps, resetGit }),
 	});
 
+	for (const phase of ["red", "green", "refactor"] as const) {
+		pi.registerCommand(`tdd:${phase}`, {
+			description:
+				`Skip to ${phase.toUpperCase()} phase. ` +
+				"Snapshot working tree, auto-enable TDD, set phase. No gate checks.",
+			handler: (_args: string, ctx: ExtensionContext) =>
+				handleTddJump(phase, ctx, defaultDeps),
+		});
+	}
+
 	registerTools(pi);
 	registerHooks(pi);
+
+	pi.on("before_agent_start", (event, ctx) =>
+		handleBeforeAgentStart(event, ctx, { loadTddState }),
+	);
 }

package/adapters/pi/prompts.ts

@@ -11,7 +11,8 @@ export function getNudgePrompt(phase: Phase, config: Config): string {
 				`Blocked files: ${redBlock}\n` +
 				"All other files are free to modify. Call `next_tdd_phase` to proceed to GREEN.\n" +
 				"Think about what could go wrong and test for it — don't just verify the happy path, " +
-				"cover unhappy paths and edge cases too. Keep cycles small so reverting is cheap."
+				"cover unhappy paths and edge cases too.\n" +
+				"Minimise the scope of each TDD cycle so reverting is cheap."
 			);
 		case "green":
 			return (

package/adapters/pi/tools.test.ts

@@ -72,24 +72,26 @@ describe("executeNextPhase", () => {
 		mockAsyncExec.mockResolvedValue({ stdout: "", stderr: "" });
 	});
 
-	it("returns config error when TDD not setup", async () => {
+	it("throws when TDD not setup", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: false,
 			reason:
 				"Missing .pi/tdd/ directory. See the tdd-enforcer skill to learn how to set up TDD configs.",
 		});
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("Missing .pi/tdd/");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("Missing .pi/tdd/");
 	});
 
-	it("returns disabled message when TDD disabled", async () => {
+	it("throws when TDD disabled", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: false, current: "red" },
 			config: CONFIG,
 		});
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("not enabled");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("not enabled");
 	});
 
 	it("blocks when allowlist violations exist", async () => {
@@ -99,9 +101,9 @@ describe("executeNextPhase", () => {
 			config: CONFIG,
 		});
 		mockGetDisallowedChanges.mockReturnValue(["src/violation.ts"]);
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("BLOCKED");
-		expect(result.content[0].text).toContain("src/violation.ts");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("BLOCKED");
 	});
 
 	it("blocks red→green when tests pass (need failing test)", async () => {
@@ -115,9 +117,9 @@ describe("executeNextPhase", () => {
 			message:
 				"Tests passed. Add a failing test before transitioning to GREEN.",
 		});
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("Add a failing test");
-		expect(result.content[0].text).toContain("GREEN");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("Add a failing test");
 	});
 
 	it("blocks green→refactor when tests fail", async () => {
@@ -130,9 +132,24 @@ describe("executeNextPhase", () => {
 			passed: false,
 			message: "Tests failed. Fix them before transitioning to REFACTOR.",
 		});
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("failed");
+	});
+
+	it("result text has leading newline for spacing", async () => {
+		mockLoadTddState.mockReturnValue({
+			ok: true,
+			state: { enabled: true, current: "red" },
+			config: CONFIG,
+		});
+		mockCheckGate.mockResolvedValue({
+			passed: true,
+			message: "Tests fail — proceed to GREEN.",
+		});
+		mockGetNudgePrompt.mockReturnValue("content");
 		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("failed");
-		expect(result.content[0].text).toContain("REFACTOR");
+		expect(result.content[0].text.startsWith("\n")).toBe(true);
 	});
 
 	it("advances red→green when tests fail", async () => {
@@ -185,9 +202,9 @@ describe("executeNextPhase", () => {
 			passed: false,
 			message: "Tests failed. Fix them before transitioning to RED.",
 		});
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("failed");
-		expect(result.content[0].text).toContain("RED");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("failed");
 		expect(mockSavePhaseState).not.toHaveBeenCalled();
 	});
 
@@ -251,57 +268,49 @@ describe("executePreviousPhase", () => {
 		mockHasParent.mockReturnValue(true);
 	});
 
-	it("returns config error when TDD not setup", async () => {
+	it("throws when TDD not setup", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: false,
 			reason: "Missing .pi/tdd/ directory.",
 		});
-		const result = await executePreviousPhase(
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result.content[0].text).toContain("Missing .pi/tdd/");
+		await expect(
+			executePreviousPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("Missing .pi/tdd/");
 	});
 
-	it("returns disabled message when TDD disabled", async () => {
+	it("throws when TDD disabled", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: false, current: "red" },
 			config: CONFIG,
 		});
-		const result = await executePreviousPhase(
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result.content[0].text).toContain("not enabled");
+		await expect(
+			executePreviousPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("not enabled");
 	});
 
-	it("returns no-parent message when only init commit exists", async () => {
+	it("throws when no parent commit", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: true, current: "red" },
 			config: CONFIG,
 		});
 		mockHasParent.mockReturnValue(false);
-		const result = await executePreviousPhase(
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result.content[0].text).toContain("No previous phase");
+		await expect(
+			executePreviousPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("No previous phase");
 	});
 
-	it("returns error when HEAD message is not a TDD snapshot", async () => {
+	it("throws when HEAD message is not a TDD snapshot", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: true, current: "red" },
 			config: CONFIG,
 		});
 		mockHeadMessage.mockReturnValue("garbage");
-		const result = await executePreviousPhase(
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result.content[0].text).toContain("not a TDD snapshot");
+		await expect(
+			executePreviousPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("not a TDD snapshot");
 	});
 
 	it("reverts to previous phase on success", async () => {
@@ -363,23 +372,25 @@ describe("executeTddStatus", () => {
 		mockTddLog = vi.fn();
 	});
 
-	it("returns config error when TDD not setup", async () => {
+	it("throws when TDD not setup", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: false,
 			reason: "Missing .pi/tdd/ directory.",
 		});
-		const result = await executeTddStatus({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("Missing .pi/tdd/");
+		await expect(
+			executeTddStatus({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("Missing .pi/tdd/");
 	});
 
-	it("returns disabled message when TDD disabled", async () => {
+	it("throws when TDD disabled", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: false, current: "red" },
 			config: CONFIG,
 		});
-		const result = await executeTddStatus({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("not enabled");
+		await expect(
+			executeTddStatus({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("not enabled");
 	});
 
 	it("returns status details when TDD enabled", async () => {

package/adapters/pi/tools.ts

@@ -102,19 +102,11 @@ export async function executeNextPhase(
 		deps.tddLog(tddDir, "WARN", "next_tdd_phase: TDD not active", {
 			reason: tdd.reason,
 		});
-		return {
-			content: [{ type: "text", text: `TDD: ${tdd.reason}` }],
-			details: {},
-		};
+		throw new Error(`TDD: ${tdd.reason}`);
 	}
 	if (!tdd.state.enabled) {
 		deps.tddLog(tddDir, "WARN", "next_tdd_phase: TDD disabled");
-		return {
-			content: [
-				{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." },
-			],
-			details: {},
-		};
+		throw new Error("TDD is not enabled. Run /tdd:on to enable it.");
 	}
 
 	const { state, config } = tdd;
@@ -130,18 +122,11 @@ export async function executeNextPhase(
 			from,
 			violations,
 		});
-		return {
-			content: [
-				{
-					type: "text",
-					text:
-						`BLOCKED: files not allowed in ${from.toUpperCase()} phase:\n` +
-						violations.map((f) => `  - ${f}`).join("\n") +
-						`\nRevert or remove them before proceeding.\n\nInspect with: cd .pi/tdd && git diff HEAD -- ${violations[0]}`,
-				},
-			],
-			details: {},
-		};
+		throw new Error(
+			`BLOCKED: files not allowed in ${from.toUpperCase()} phase:\n` +
+				violations.map((f) => `  - ${f}`).join("\n") +
+				`\nRevert or remove them before proceeding.\n\nInspect with: cd .pi/tdd && git diff HEAD -- ${violations[0]}`,
+		);
 	}
 
 	// 2. Gate check
@@ -176,7 +161,7 @@ export async function executeNextPhase(
 	});
 
 	if (!gate.passed) {
-		return { content: [{ type: "text", text: gate.message }], details: {} };
+		throw new Error(gate.message);
 	}
 
 	// 3. Snapshot — label with the phase the work was done in
@@ -193,7 +178,7 @@ export async function executeNextPhase(
 	deps.tddLog(tddDir, "INFO", "next_tdd_phase: complete", { from, to });
 
 	return {
-		content: [{ type: "text", text: deps.getNudgePrompt(to, config) }],
+		content: [{ type: "text", text: `\n${deps.getNudgePrompt(to, config)}` }],
 		details: {},
 	};
 }
@@ -214,19 +199,11 @@ export async function executePreviousPhase(
 		deps.tddLog(tddDir, "WARN", "previous_tdd_phase: TDD not active", {
 			reason: tdd.reason,
 		});
-		return {
-			content: [{ type: "text", text: `TDD: ${tdd.reason}` }],
-			details: {},
-		};
+		throw new Error(`TDD: ${tdd.reason}`);
 	}
 	if (!tdd.state.enabled) {
 		deps.tddLog(tddDir, "WARN", "previous_tdd_phase: TDD disabled");
-		return {
-			content: [
-				{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." },
-			],
-			details: {},
-		};
+		throw new Error("TDD is not enabled. Run /tdd:on to enable it.");
 	}
 
 	const { state } = tdd;
@@ -235,10 +212,7 @@ export async function executePreviousPhase(
 		deps.tddLog(tddDir, "WARN", "previous_tdd_phase: no parent commit", {
 			phase: state.current,
 		});
-		return {
-			content: [{ type: "text", text: "No previous phase to revert to." }],
-			details: {},
-		};
+		throw new Error("No previous phase to revert to.");
 	}
 
 	// Read phase from HEAD snapshot commit message (source of truth).
@@ -250,18 +224,11 @@ export async function executePreviousPhase(
 		deps.tddLog(tddDir, "ERROR", "previous_tdd_phase: invalid HEAD message", {
 			headMsg,
 		});
-		return {
-			content: [
-				{
-					type: "text",
-					text:
-						`HEAD commit "${headMsg}" is not a TDD snapshot. Cannot determine previous phase.\n` +
-						`The private git repo at .pi/tdd must not be manually modified. ` +
-						`Tampering with it will cause TDD state corruption.`,
-				},
-			],
-			details: {},
-		};
+		throw new Error(
+			`HEAD commit "${headMsg}" is not a TDD snapshot. Cannot determine previous phase.\n` +
+				`The private git repo at .pi/tdd must not be manually modified. ` +
+				`Tampering with it will cause TDD state corruption.`,
+		);
 	}
 	const label = phaseMatch[1];
 	if (label !== "red" && label !== "green" && label !== "refactor") {
@@ -269,15 +236,9 @@ export async function executePreviousPhase(
 			headMsg,
 			label,
 		});
-		return {
-			content: [
-				{
-					type: "text",
-					text: `HEAD commit "${headMsg}" has unexpected label. Cannot determine previous phase.`,
-				},
-			],
-			details: {},
-		};
+		throw new Error(
+			`HEAD commit "${headMsg}" has unexpected label. Cannot determine previous phase.`,
+		);
 	}
 	const prevPhase: Phase = label;
 	deps.tddLog(tddDir, "INFO", "previous_tdd_phase: reverting", {
@@ -305,7 +266,7 @@ export async function executePreviousPhase(
 		content: [
 			{
 				type: "text",
-				text: `Reverted to ${prevPhase.toUpperCase()}. Working tree has the previous snapshot content as unstaged changes.`,
+				text: `\nReverted to ${prevPhase.toUpperCase()}. Working tree has the previous snapshot content as unstaged changes.`,
 			},
 		],
 		details: {},
@@ -329,19 +290,11 @@ export async function executeTddStatus(
 		deps.tddLog(tddDir, "WARN", "tdd_status: TDD not active", {
 			reason: result.reason,
 		});
-		return {
-			content: [{ type: "text", text: `TDD: ${result.reason}` }],
-			details: {},
-		};
+		throw new Error(`TDD: ${result.reason}`);
 	}
 	if (!result.state.enabled) {
 		deps.tddLog(tddDir, "WARN", "tdd_status: TDD disabled");
-		return {
-			content: [
-				{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." },
-			],
-			details: {},
-		};
+		throw new Error("TDD is not enabled. Run /tdd:on to enable it.");
 	}
 
 	const { state, config } = result;
@@ -359,7 +312,7 @@ export async function executeTddStatus(
 			{
 				type: "text",
 				text:
-					`TDD enforcer enabled\n` +
+					`\nTDD enforcer enabled\n` +
 					`Current phase: ${phaseStr}\n` +
 					`Blocked in RED: ${redBlk}\n` +
 					`Blocked in GREEN: ${greenBlk}\n` +

package/package.json

@@ -1,32 +1,32 @@
 {
-    "name": "tdd-enforcer",
-    "version": "0.2.7",
-    "type": "module",
-    "scripts": {
-        "fmt": "biome format --write .",
-        "lint": "biome check .",
-        "lint:fix": "biome check --write .",
-        "test": "vitest run"
-    },
-    "keywords": [
-        "pi-package"
-    ],
-    "dependencies": {
-        "picomatch": "^4.0.4"
-    },
-    "devDependencies": {
-        "@biomejs/biome": "^2.5.0",
-        "@earendil-works/pi-coding-agent": "^0.79.6",
-        "@types/node": "^25.9.3",
-        "typebox": "^1.2.16",
-        "vitest": "^3"
-    },
-    "pi": {
-        "extensions": [
-            "./adapters/pi/index.ts"
-        ],
-        "skills": [
-            "./skills"
-        ]
-    }
+	"name": "tdd-enforcer",
+	"version": "0.2.9",
+	"type": "module",
+	"scripts": {
+		"fmt": "biome format --write .",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"test": "vitest run"
+	},
+	"keywords": [
+		"pi-package"
+	],
+	"dependencies": {
+		"picomatch": "^4.0.4"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@earendil-works/pi-coding-agent": "^0.79.6",
+		"@types/node": "^25.9.3",
+		"typebox": "^1.2.16",
+		"vitest": "^3"
+	},
+	"pi": {
+		"extensions": [
+			"./adapters/pi/index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	}
 }

package/skills/tdd-enforcer/SKILL.md

@@ -54,7 +54,7 @@ It locks files per phase — only test files in RED, only implementation files i
 ### RED
 Files matching `blockedInRed` are locked — everything else is free.
 
-Write failing tests for one feature at a time. Think about what could go wrong and test for it — don't just verify the happy path, cover unhappy paths and edge cases too. Keep cycles small so reverting is cheap and safe if assumptions turn out wrong.
+Write failing tests for one feature at a time. Think about what could go wrong and test for it — don't just verify the happy path, cover unhappy paths and edge cases too. Minimise the scope of each TDD cycle so reverting is cheap and safe if assumptions turn out wrong.
 
 Call `next_tdd_phase` once tests fail.