tdd-enforcer 0.2.8 → 0.3.0

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,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
+	handleBeforeAgentStart,
 	handleTddJump,
 	handleTddOff,
 	handleTddOn,
@@ -416,3 +417,82 @@ describe("handleTddJump", () => {
 		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(): { systemPrompt: string } {
+		return { systemPrompt: "" };
+	}
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLoadTddState = vi.fn();
+	});
+
+	it("appends TDD instructions 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.systemPrompt).toContain("TDD enforcement");
+		expect(event.systemPrompt).toContain("locked files will be blocked");
+		expect(event.systemPrompt).toContain("cycle so reverting is cheap");
+		expect(event.systemPrompt).not.toContain("next_tdd_phase");
+	});
+
+	it("does not modify systemPrompt 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.systemPrompt).toBe("");
+	});
+
+	it("appends disabled message when TDD was 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.systemPrompt).toContain("was disabled");
+	});
+});

package/adapters/pi/index.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import type {
-	ExtensionAPI,
-	ExtensionContext,
+    ExtensionAPI,
+    ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { resetGit, savePhaseState, snapshot } from "../../engine/index.js";
 import { loadTddState } from "./helpers.js";
@@ -10,297 +10,321 @@ import { tddLog } from "./log.js";
 import { registerTools } from "./tools.js";
 
 export async function handleTddOn(
-	ctx: ExtensionContext,
-	deps: {
-		loadTddState: typeof loadTddState;
-		snapshot: typeof snapshot;
-		savePhaseState: typeof savePhaseState;
-		tddLog: typeof tddLog;
-	} = {
-		loadTddState,
-		snapshot,
-		savePhaseState,
-		tddLog,
-	},
+    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");
-
-	deps.tddLog(tddDir, "INFO", "tdd:on: starting");
-
-	const setup = deps.loadTddState(root);
-	if (!setup.ok) {
-		deps.tddLog(tddDir, "WARN", "tdd:on: setup invalid", {
-			reason: setup.reason,
-		});
-		ctx.ui.notify(setup.reason, "error");
-		return;
-	}
-
-	const { state } = setup;
-
-	if (state.enabled) {
-		deps.tddLog(tddDir, "INFO", "tdd:on: already enabled", {
-			phase: state.current,
-		});
-		ctx.ui.notify(
-			`TDD already enabled — ${state.current.toUpperCase()} phase`,
-			"info",
-		);
-		return;
-	}
-
-	// Snapshot working tree so stale baseline doesn't nuke user changes
-	deps.snapshot(root, state.current);
-	deps.tddLog(tddDir, "INFO", "tdd:on: snapshot taken", {
-		phase: state.current,
-	});
-
-	state.enabled = true;
-	deps.savePhaseState(root, state);
-	deps.tddLog(tddDir, "INFO", "tdd:on: enabled", {
-		phase: state.current,
-	});
-	ctx.ui.notify(`TDD enabled — ${state.current.toUpperCase()} phase`, "info");
+    const root = ctx.cwd;
+    const tddDir = join(root, ".pi", "tdd");
+
+    deps.tddLog(tddDir, "INFO", "tdd:on: starting");
+
+    const setup = deps.loadTddState(root);
+    if (!setup.ok) {
+        deps.tddLog(tddDir, "WARN", "tdd:on: setup invalid", {
+            reason: setup.reason,
+        });
+        ctx.ui.notify(setup.reason, "error");
+        return;
+    }
+
+    const { state } = setup;
+
+    if (state.enabled) {
+        deps.tddLog(tddDir, "INFO", "tdd:on: already enabled", {
+            phase: state.current,
+        });
+        ctx.ui.notify(
+            `TDD already enabled — ${state.current.toUpperCase()} phase`,
+            "info",
+        );
+        return;
+    }
+
+    // Snapshot working tree so stale baseline doesn't nuke user changes
+    deps.snapshot(root, state.current);
+    deps.tddLog(tddDir, "INFO", "tdd:on: snapshot taken", {
+        phase: state.current,
+    });
+
+    state.enabled = true;
+    deps.savePhaseState(root, state);
+    deps.tddLog(tddDir, "INFO", "tdd:on: enabled", {
+        phase: state.current,
+    });
+    ctx.ui.notify(`TDD enabled — ${state.current.toUpperCase()} phase`, "info");
 }
 
 export async function handleTddOff(
-	ctx: ExtensionContext,
-	deps: {
-		loadTddState: typeof loadTddState;
-		savePhaseState: typeof savePhaseState;
-		tddLog: typeof tddLog;
-	} = {
-		loadTddState,
-		savePhaseState,
-		tddLog,
-	},
+    ctx: ExtensionContext,
+    deps: {
+        loadTddState: typeof loadTddState;
+        savePhaseState: typeof savePhaseState;
+        tddLog: typeof tddLog;
+    } = {
+            loadTddState,
+            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:off: setup invalid", {
-			reason: setup.reason,
-		});
-		ctx.ui.notify(setup.reason, "error");
-		return;
-	}
-
-	const { state } = setup;
-
-	if (!state.enabled) {
-		deps.tddLog(tddDir, "INFO", "tdd:off: already disabled");
-		ctx.ui.notify("TDD already disabled", "info");
-		return;
-	}
-
-	state.enabled = false;
-	deps.savePhaseState(root, state);
-	deps.tddLog(tddDir, "INFO", "tdd:off: disabled", {
-		was: state.current,
-	});
-	ctx.ui.notify("TDD disabled", "info");
+    const root = ctx.cwd;
+    const tddDir = join(root, ".pi", "tdd");
+
+    const setup = deps.loadTddState(root);
+    if (!setup.ok) {
+        deps.tddLog(tddDir, "WARN", "tdd:off: setup invalid", {
+            reason: setup.reason,
+        });
+        ctx.ui.notify(setup.reason, "error");
+        return;
+    }
+
+    const { state } = setup;
+
+    if (!state.enabled) {
+        deps.tddLog(tddDir, "INFO", "tdd:off: already disabled");
+        ctx.ui.notify("TDD already disabled", "info");
+        return;
+    }
+
+    state.enabled = false;
+    deps.savePhaseState(root, state);
+    deps.tddLog(tddDir, "INFO", "tdd:off: disabled", {
+        was: state.current,
+    });
+    ctx.ui.notify("TDD disabled", "info");
 }
 
 export async function handleTddStatus(
-	ctx: ExtensionContext,
-	deps: {
-		loadTddState: typeof loadTddState;
-		tddLog: typeof tddLog;
-	} = {
-		loadTddState,
-		tddLog,
-	},
+    ctx: ExtensionContext,
+    deps: {
+        loadTddState: typeof loadTddState;
+        tddLog: typeof tddLog;
+    } = {
+            loadTddState,
+            tddLog,
+        },
 ): Promise<void> {
-	const root = ctx.cwd;
-	const tddDir = join(root, ".pi", "tdd");
-	const result = deps.loadTddState(root);
-
-	if (!result.ok) {
-		deps.tddLog(tddDir, "WARN", "tdd:status: setup invalid", {
-			reason: result.reason,
-		});
-		ctx.ui.notify(`TDD: ${result.reason}`, "error");
-		return;
-	}
-
-	const { state, config } = result;
-	const enabledStr = state.enabled ? "enabled" : "disabled";
-	const phaseStr = state.current.toUpperCase();
-	const redBlk = config.blockedInRed.join(", ") || "(none)";
-	const greenBlk = config.blockedInGreen.join(", ") || "(none)";
-	const commands = config.testCommands.join(", ") || "(none)";
-
-	deps.tddLog(tddDir, "INFO", "tdd:status: queried", {
-		enabled: state.enabled,
-		phase: state.current,
-	});
-
-	ctx.ui.notify(
-		`TDD enforcer ${enabledStr}\n` +
-			`Current phase: ${phaseStr}\n` +
-			`Blocked in RED: ${redBlk}\n` +
-			`Blocked in GREEN: ${greenBlk}\n` +
-			`Test commands: ${commands}`,
-		"info",
-	);
+    const root = ctx.cwd;
+    const tddDir = join(root, ".pi", "tdd");
+    const result = deps.loadTddState(root);
+
+    if (!result.ok) {
+        deps.tddLog(tddDir, "WARN", "tdd:status: setup invalid", {
+            reason: result.reason,
+        });
+        ctx.ui.notify(`TDD: ${result.reason}`, "error");
+        return;
+    }
+
+    const { state, config } = result;
+    const enabledStr = state.enabled ? "enabled" : "disabled";
+    const phaseStr = state.current.toUpperCase();
+    const redBlk = config.blockedInRed.join(", ") || "(none)";
+    const greenBlk = config.blockedInGreen.join(", ") || "(none)";
+    const commands = config.testCommands.join(", ") || "(none)";
+
+    deps.tddLog(tddDir, "INFO", "tdd:status: queried", {
+        enabled: state.enabled,
+        phase: state.current,
+    });
+
+    ctx.ui.notify(
+        `TDD enforcer ${enabledStr}\n` +
+        `Current phase: ${phaseStr}\n` +
+        `Blocked in RED: ${redBlk}\n` +
+        `Blocked in GREEN: ${greenBlk}\n` +
+        `Test commands: ${commands}`,
+        "info",
+    );
+}
+
+export async function handleBeforeAgentStart(
+    event: { systemPrompt: string },
+    ctx: { cwd: string },
+    deps: {
+        loadTddState: typeof loadTddState;
+    },
+): Promise<void> {
+    const tdd = deps.loadTddState(ctx.cwd);
+    if (!tdd.ok) return;
+
+    if (tdd.state.enabled) {
+        event.systemPrompt +=
+            "\n\nYou are working under TDD enforcement. Each phase restricts which files you can modify — locked files will be blocked automatically.\n" +
+            "Minimise the scope of each TDD cycle so reverting is cheap.";
+    } else {
+        event.systemPrompt +=
+            "\n\nTDD enforcement was disabled. File restrictions are no longer enforced.";
+    }
 }
 
 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,
-	},
+    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");
+    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: {
-		loadTddState: typeof loadTddState;
-		resetGit: typeof resetGit;
-		snapshot: typeof snapshot;
-		savePhaseState: typeof savePhaseState;
-		tddLog: typeof tddLog;
-	} = {
-		loadTddState,
-		resetGit,
-		snapshot,
-		savePhaseState,
-		tddLog,
-	},
+    ctx: ExtensionContext,
+    deps: {
+        loadTddState: typeof loadTddState;
+        resetGit: typeof resetGit;
+        snapshot: typeof snapshot;
+        savePhaseState: typeof savePhaseState;
+        tddLog: typeof tddLog;
+    } = {
+            loadTddState,
+            resetGit,
+            snapshot,
+            savePhaseState,
+            tddLog,
+        },
 ): Promise<void> {
-	const root = ctx.cwd;
-	const tddDir = join(root, ".pi", "tdd");
-
-	deps.tddLog(tddDir, "INFO", "tdd:reset: starting");
-
-	const setup = deps.loadTddState(root);
-	if (!setup.ok) {
-		deps.tddLog(tddDir, "WARN", "tdd:reset: setup invalid", {
-			reason: setup.reason,
-		});
-		ctx.ui.notify(setup.reason, "error");
-		return;
-	}
-
-	// Nuke git history and re-init
-	try {
-		deps.resetGit(root);
-		deps.tddLog(tddDir, "INFO", "tdd:reset: git reset and re-initialised");
-	} catch (e) {
-		deps.tddLog(tddDir, "ERROR", "tdd:reset: git reset failed", {
-			error: (e as Error).message,
-		});
-		ctx.ui.notify("Failed to reset private git repo.", "error");
-		return;
-	}
-
-	// Snapshot current working tree
-	deps.snapshot(root, "red");
-	deps.tddLog(tddDir, "INFO", "tdd:reset: snapshot taken");
-
-	// Reset state to RED (disabled, user must run /tdd:on)
-	deps.savePhaseState(root, { enabled: false, current: "red" });
-	deps.tddLog(tddDir, "INFO", "tdd:reset: complete");
-
-	ctx.ui.notify(
-		"TDD snapshot history reset. Run /tdd:on to re-enable enforcement.",
-		"warning",
-	);
+    const root = ctx.cwd;
+    const tddDir = join(root, ".pi", "tdd");
+
+    deps.tddLog(tddDir, "INFO", "tdd:reset: starting");
+
+    const setup = deps.loadTddState(root);
+    if (!setup.ok) {
+        deps.tddLog(tddDir, "WARN", "tdd:reset: setup invalid", {
+            reason: setup.reason,
+        });
+        ctx.ui.notify(setup.reason, "error");
+        return;
+    }
+
+    // Nuke git history and re-init
+    try {
+        deps.resetGit(root);
+        deps.tddLog(tddDir, "INFO", "tdd:reset: git reset and re-initialised");
+    } catch (e) {
+        deps.tddLog(tddDir, "ERROR", "tdd:reset: git reset failed", {
+            error: (e as Error).message,
+        });
+        ctx.ui.notify("Failed to reset private git repo.", "error");
+        return;
+    }
+
+    // Snapshot current working tree
+    deps.snapshot(root, "red");
+    deps.tddLog(tddDir, "INFO", "tdd:reset: snapshot taken");
+
+    // Reset state to RED (disabled, user must run /tdd:on)
+    deps.savePhaseState(root, { enabled: false, current: "red" });
+    deps.tddLog(tddDir, "INFO", "tdd:reset: complete");
+
+    ctx.ui.notify(
+        "TDD snapshot history reset. Run /tdd:on to re-enable enforcement.",
+        "warning",
+    );
 }
 
 export default function (pi: ExtensionAPI) {
-	const defaultDeps = {
-		loadTddState,
-		snapshot,
-		savePhaseState,
-		tddLog,
-		resetGit,
-	};
-
-	pi.registerCommand("tdd:on", {
-		description: "Enable TDD enforcement",
-		handler: (_args: string, ctx: ExtensionContext) =>
-			handleTddOn(ctx, defaultDeps),
-	});
-
-	pi.registerCommand("tdd:off", {
-		description: "Disable TDD enforcement",
-		handler: (_args: string, ctx: ExtensionContext) =>
-			handleTddOff(ctx, defaultDeps),
-	});
-
-	pi.registerCommand("tdd:status", {
-		description: "Show TDD enforcement status",
-		handler: (_args: string, ctx: ExtensionContext) =>
-			handleTddStatus(ctx, defaultDeps),
-	});
-
-	pi.registerCommand("tdd:reset", {
-		description:
-			"WARNING: Destroys ALL TDD snapshot history and resets to RED phase. " +
-			"Working tree is preserved. Run /tdd:on to re-enable after reset.",
-		handler: (_args: string, ctx: ExtensionContext) =>
-			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);
+    const defaultDeps = {
+        loadTddState,
+        snapshot,
+        savePhaseState,
+        tddLog,
+        resetGit,
+    };
+
+    pi.registerCommand("tdd:on", {
+        description: "Enable TDD enforcement",
+        handler: (_args: string, ctx: ExtensionContext) =>
+            handleTddOn(ctx, defaultDeps),
+    });
+
+    pi.registerCommand("tdd:off", {
+        description: "Disable TDD enforcement",
+        handler: (_args: string, ctx: ExtensionContext) =>
+            handleTddOff(ctx, defaultDeps),
+    });
+
+    pi.registerCommand("tdd:status", {
+        description: "Show TDD enforcement status",
+        handler: (_args: string, ctx: ExtensionContext) =>
+            handleTddStatus(ctx, defaultDeps),
+    });
+
+    pi.registerCommand("tdd:reset", {
+        description:
+            "WARNING: Destroys ALL TDD snapshot history and resets to RED phase. " +
+            "Working tree is preserved. Run /tdd:on to re-enable after reset.",
+        handler: (_args: string, ctx: ExtensionContext) =>
+            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

@@ -12,7 +12,7 @@ export function getNudgePrompt(phase: Phase, config: Config): string {
 				"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.\n" +
-				"Keep cycles small so reverting is cheap."
+				"Minimise the scope of each TDD cycle so reverting is cheap."
 			);
 		case "green":
 			return (

package/adapters/pi/tools.test.ts

@@ -137,6 +137,21 @@ describe("executeNextPhase", () => {
 		).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.startsWith("\n")).toBe(true);
+	});
+
 	it("advances red→green when tests fail", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,

package/adapters/pi/tools.ts

@@ -178,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: {},
 	};
 }
@@ -266,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: {},
@@ -312,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.8",
-	"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.3.0",
+    "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.