tdd-enforcer 0.2.7 → 0.2.8

package/adapters/pi/index.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
+	handleTddJump,
 	handleTddOff,
 	handleTddOn,
 	handleTddReset,
@@ -310,3 +311,108 @@ 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");
+	});
+});

package/adapters/pi/index.ts

@@ -148,6 +148,58 @@ export async function handleTddStatus(
 	);
 }
 
+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 +291,16 @@ 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);
 }

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" +
+				"Keep cycles small 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,9 @@ describe("executeNextPhase", () => {
 			passed: false,
 			message: "Tests failed. Fix them before transitioning to REFACTOR.",
 		});
-		const result = await executeNextPhase({ cwd: "/test" } as any, makeDeps());
-		expect(result.content[0].text).toContain("failed");
-		expect(result.content[0].text).toContain("REFACTOR");
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("failed");
 	});
 
 	it("advances red→green when tests fail", async () => {
@@ -185,9 +187,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 +253,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 +357,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
@@ -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", {
@@ -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;

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.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"
+		]
+	}
 }