tdd-enforcer 0.1.5 → 0.1.7

package/DESIGN.md

@@ -20,7 +20,7 @@ RED ──(tests fail)──► GREEN ──(tests pass)──► REFACTOR ─
 
 ### `previous_tdd_phase`
 
-Reverts to the previous snapshot. Pops the phase stack, restores working tree to exact prior state. No gate checks — just revert. Must have clear warning in the tool schema that this will revert all changes in the current state.
+Reverts to the previous snapshot by parsing the phase label from the last git snapshot commit. Restores working tree to exact prior state. No gate checks — just revert. Must have clear warning in the tool schema that this will revert all changes in the current state.
 
 ---
 
@@ -57,7 +57,7 @@ A separate git repository at `.pi/tdd/.git/` that tracks the project root as its
 ```
 .pi/tdd/
 ├── .gitignore           # private git — excludes file patterns from snapshots
-├── phase.json           # {current: "red", stack: ["s1","s2","s3"]}
+├── state.json           # {current: "red", enabled: true}
 ├── rules.json           # user config
 └── .git/                # private git — init with --git-dir
 ```
@@ -75,7 +75,7 @@ A separate git repository at `.pi/tdd/.git/` that tracks the project root as its
 
 **On `previous_tdd_phase` (revert):**
 - `git restore --source=<prev-commit> --worktree -- .` — restores project to exact prior snapshot
-- Pop the stack in `phase.json`
+- Pop the last snapshot commit in the private git repo
 
 ### Benefits of private git
 
@@ -147,17 +147,16 @@ If the user wants to exclude additional files from TDD snapshots only, they can
 
 ## Phase State Persistence
 
-Stored in `.pi/tdd/phase.json`:
+Stored in `.pi/tdd/state.json`:
 
 ```json
 {
   "current": "green",
-  "enabled": true,
-  "stack": ["commit-hash-1", "commit-hash-2", "commit-hash-3"]
+  "enabled": true
 }
 ```
 
-The git commit hashes anchor each snapshot. `previous_tdd_phase` restores to the parent of the latest commit and pops the stack. Survives session restarts and extension reloads.
+The snapshot history lives in the private git repo's commit log — no explicit stack array needed. `previous_tdd_phase` reads the phase label from the HEAD commit message and restores to the parent. Survives session restarts and extension reloads.
 
 ---
 

package/adapters/pi/helpers.test.ts

@@ -44,7 +44,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("returns missing phase.json when rules exists but phase missing", () => {
+  it("returns missing state.json when rules exists but state missing", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -54,11 +54,11 @@ describe("loadTddState", () => {
       );
       const result = loadTddState(dir);
       expect(result.ok).toBe(false);
-      expect(result.reason).toContain("phase.json");
+      expect(result.reason).toContain("state.json");
     });
   });
 
-  it("returns invalid phase.json error for malformed JSON", () => {
+  it("returns invalid state.json error for malformed JSON", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -66,10 +66,10 @@ describe("loadTddState", () => {
         JSON.stringify(validRules),
         "utf-8",
       );
-      writeFileSync(join(dir, ".pi", "tdd", "phase.json"), "not json", "utf-8");
+      writeFileSync(join(dir, ".pi", "tdd", "state.json"), "not json", "utf-8");
       const result = loadTddState(dir);
       expect(result.ok).toBe(false);
-      expect(result.reason).toContain("Invalid .pi/tdd/phase.json");
+      expect(result.reason).toContain("Invalid .pi/tdd/state.json");
     });
   });
 
@@ -82,7 +82,7 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify(validPhase),
         "utf-8",
       );
@@ -92,7 +92,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("returns disabled error when phase.json has enabled: false", () => {
+  it("returns disabled error when state.json has enabled: false", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -101,7 +101,7 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify({ enabled: false, current: "red" }),
         "utf-8",
       );
@@ -120,7 +120,7 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify(validPhase),
         "utf-8",
       );
@@ -144,7 +144,7 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify(validPhase),
         "utf-8",
       );
@@ -169,7 +169,7 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify(validPhase),
         "utf-8",
       );
@@ -182,7 +182,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("passes through the phase.json validation error for invalid current phase", () => {
+  it("passes through the state.json validation error for invalid current phase", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -191,13 +191,13 @@ describe("loadTddState", () => {
         "utf-8",
       );
       writeFileSync(
-        join(dir, ".pi", "tdd", "phase.json"),
+        join(dir, ".pi", "tdd", "state.json"),
         JSON.stringify({ enabled: true, current: "blurple" }),
         "utf-8",
       );
       const result = loadTddState(dir);
       expect(result.ok).toBe(false);
-      expect(result.reason).toContain("Invalid .pi/tdd/phase.json");
+      expect(result.reason).toContain("Invalid .pi/tdd/state.json");
     });
   });
 });

package/adapters/pi/helpers.ts

@@ -23,16 +23,16 @@ export function loadTddState(root: string): TddLoadResult {
     return { ok: false, reason: "Missing .pi/tdd/rules.json. See the tdd-init skill to learn how to set up TDD configs." };
   }
 
-  const phasePath = join(tddDir, "phase.json");
+  const phasePath = join(tddDir, "state.json");
   if (!existsSync(phasePath)) {
-    return { ok: false, reason: "Missing .pi/tdd/phase.json. See the tdd-init skill to learn how to set up TDD configs." };
+    return { ok: false, reason: "Missing .pi/tdd/state.json. See the tdd-init skill to learn how to set up TDD configs." };
   }
 
   let state: PhaseState;
   try {
     state = loadPhaseState(root);
   } catch (e) {
-    return { ok: false, reason: `Invalid .pi/tdd/phase.json: ${(e as Error).message}` };
+    return { ok: false, reason: `Invalid .pi/tdd/state.json: ${(e as Error).message}` };
   }
 
   let config: Config;
@@ -43,7 +43,7 @@ export function loadTddState(root: string): TddLoadResult {
   }
 
   if (!state.enabled) {
-    return { ok: false, reason: "TDD is not enabled. Run /tdd to enable it." };
+    return { ok: false, reason: "TDD is not enabled. Run /tdd:on to enable it." };
   }
 
   // Heal git if missing

package/adapters/pi/hooks.ts

@@ -2,10 +2,13 @@ import { join, relative } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType, isBashToolResult } from "@earendil-works/pi-coding-agent";
 import { isAllowed } from "../../engine/enforce.js";
-import { changesSinceSnapshot } from "../../engine/git.js";
+import { changesSince, restoreFilesTo, gitStashCreate } from "../../engine/git.js";
 import { loadTddState } from "./helpers.js";
 import { tddLog } from "./log.js";
 
+// Correlates tool_call → tool_result for per-command bash diff
+const preBashStashes = new Map<string, string>();
+
 export function registerHooks(pi: ExtensionAPI): void {
   pi.on("tool_call", async (event, ctx: ExtensionContext) => {
     const root = ctx.cwd;
@@ -22,6 +25,24 @@ export function registerHooks(pi: ExtensionAPI): void {
     const { state, config } = tdd;
     const phase = state.current;
 
+    // Bash: stash pre-command state for per-command diff later
+    if ((event as any).toolName === "bash") {
+      try {
+        const hash = gitStashCreate(root);
+        preBashStashes.set(event.toolCallId, hash);
+        tddLog(tddDir, "DEBUG", "tool_call: bash pre-stash created", {
+          toolCallId: event.toolCallId,
+          hash,
+        });
+      } catch (e) {
+        tddLog(tddDir, "ERROR", "tool_call: bash pre-stash failed", {
+          toolCallId: event.toolCallId,
+          error: (e as Error).message,
+        });
+      }
+      return;
+    }
+
     let filePath: string | undefined;
     let toolName: string | undefined;
     if (isToolCallEventType("write", event)) {
@@ -69,6 +90,17 @@ export function registerHooks(pi: ExtensionAPI): void {
 
     const root = ctx.cwd;
     const tddDir = join(root, ".pi", "tdd");
+
+    // Get the pre-bash stash for this tool call
+    const stashHash = preBashStashes.get(event.toolCallId);
+    preBashStashes.delete(event.toolCallId);
+    if (!stashHash) {
+      tddLog(tddDir, "WARN", "tool_result: no pre-bash stash found", {
+        toolCallId: event.toolCallId,
+      });
+      return;
+    }
+
     const tdd = loadTddState(root);
     if (!tdd.ok) {
       tddLog(tddDir, "WARN", "tool_result: TDD not active, bash passes through", {
@@ -84,14 +116,16 @@ export function registerHooks(pi: ExtensionAPI): void {
       return;
     }
 
-    const changed = changesSinceSnapshot(root);
+    // Diff against pre-bash stash — only changes from THIS command
+    const changed = changesSince(root, stashHash);
+
     if (changed.length === 0) {
-      tddLog(tddDir, "DEBUG", "tool_result: no changes since snapshot");
+      tddLog(tddDir, "DEBUG", "tool_result: no changes in this bash command");
       return;
     }
 
-    const violations = changed.filter((f) => !isAllowed(f, phase, config));
-    if (violations.length === 0) {
+    const cmdViolations = changed.filter((f) => !isAllowed(f, phase, config));
+    if (cmdViolations.length === 0) {
       tddLog(tddDir, "DEBUG", "tool_result: no violations among changed files", {
         changed,
       });
@@ -100,20 +134,29 @@ export function registerHooks(pi: ExtensionAPI): void {
 
     tddLog(tddDir, "WARN", "tool_result: locked files modified by bash", {
       phase,
-      violations,
+      violations: cmdViolations,
     });
 
+    // Revert only this command's violations back to pre-bash state
+    restoreFilesTo(root, cmdViolations, stashHash);
+
+    // Find remaining allowed changes from this command
+    const cmdAllowed = changed.filter((f) => isAllowed(f, phase, config));
+
     const existingText = event.content.map((c) => ("text" in c ? c.text : "")).join("");
+    let warning = `\n\n⛔ ${phase.toUpperCase()}: reverted locked files modified by bash:`;
+    cmdViolations.forEach((f) => (warning += `\n  - ${f}`));
+    if (cmdAllowed.length > 0) {
+      warning += `\n\nAllowed changes retained:`;
+      cmdAllowed.forEach((f) => (warning += `\n  - ${f}`));
+    }
+
     return {
       isError: true,
       content: [
         {
           type: "text",
-          text:
-            existingText +
-            `\n\n⛔ ${phase.toUpperCase()}: bash modified locked files: ${violations.join(", ")}\n` +
-            `next_tdd_phase blocked until reverted. ` +
-            `Inspect with: cd .pi/tdd && git diff HEAD -- ${violations[0]}`,
+          text: existingText + warning,
         },
       ],
     };

package/adapters/pi/index.ts

@@ -29,10 +29,10 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      const phasePath = join(tddDir, "phase.json");
+      const phasePath = join(tddDir, "state.json");
       if (!existsSync(phasePath)) {
-        tddLog(tddDir, "WARN", "tdd:on: missing phase.json");
-        ctx.ui.notify("Missing .pi/tdd/phase.json. See the tdd-init skill to learn how to set up TDD configs.", "error");
+        tddLog(tddDir, "WARN", "tdd:on: missing state.json");
+        ctx.ui.notify("Missing .pi/tdd/state.json. See the tdd-init skill to learn how to set up TDD configs.", "error");
         return;
       }
 
@@ -40,10 +40,10 @@ export default function (pi: ExtensionAPI) {
       try {
         state = loadPhaseState(root);
       } catch (e) {
-        tddLog(tddDir, "WARN", "tdd:on: invalid phase.json", {
+        tddLog(tddDir, "WARN", "tdd:on: invalid state.json", {
           error: (e as Error).message,
         });
-        ctx.ui.notify("Invalid .pi/tdd/phase.json. Fix or delete it, then run /tdd:on again.", "error");
+        ctx.ui.notify("Invalid .pi/tdd/state.json. Fix or delete it, then run /tdd:on again.", "error");
         return;
       }
 
@@ -105,10 +105,10 @@ export default function (pi: ExtensionAPI) {
       try {
         state = loadPhaseState(root);
       } catch (e) {
-        tddLog(tddDir, "WARN", "tdd:off: invalid phase.json", {
+        tddLog(tddDir, "WARN", "tdd:off: invalid state.json", {
           error: (e as Error).message,
         });
-        ctx.ui.notify("Invalid .pi/tdd/phase.json. Fix or delete it, then run /tdd:off again.", "error");
+        ctx.ui.notify("Invalid .pi/tdd/state.json. Fix or delete it, then run /tdd:off again.", "error");
         return;
       }
 

package/adapters/pi/prompts.ts

@@ -1,22 +1,19 @@
 import type { Phase, Config } from "../../engine/types.js";
 
-function listMatched(files: string[]): string {
-  if (files.length === 0) return "";
-  return "\nMatched files: " + files.join(", ");
-}
-
 export function getNudgePrompt(phase: Phase, config: Config, matchedFiles?: string[]): string {
+  const redPatterns = (matchedFiles ?? config.allowedRedPhaseFiles).join(", ");
+  const greenPatterns = config.allowedGreenPhaseFiles.join(", ");
+
   switch (phase) {
     case "red":
       return (
-        "You are now in **RED** phase. Write failing tests matching `allowedRedPhaseFiles` patterns. " +
-        "Only these files can be modified. Once tests fail, call `next_tdd_phase` to proceed to GREEN." +
-        listMatched(matchedFiles ?? config.allowedRedPhaseFiles)
+        `You are now in **RED** phase. Write failing tests matching: ${redPatterns}\n` +
+        "Only these files can be modified. Once tests fail, call `next_tdd_phase` to proceed to GREEN."
       );
     case "green":
       return (
-        "You are now in **GREEN** phase. Files matching `allowedRedPhaseFiles` are locked. " +
-        "Implement features in `allowedGreenPhaseFiles` to make tests pass. " +
+        `You are now in **GREEN** phase. Test files (${redPatterns}) are locked.\n` +
+        `Implement features matching: ${greenPatterns}\n` +
         "Call `next_tdd_phase` to proceed to REFACTOR."
       );
     case "refactor":
@@ -29,36 +26,4 @@ export function getNudgePrompt(phase: Phase, config: Config, matchedFiles?: stri
   }
 }
 
-export function buildPhasePrompt(phase: Phase, config: Config): string {
-  const redPatterns = config.allowedRedPhaseFiles.join(", ") || "(none)";
-  const greenPatterns = config.allowedGreenPhaseFiles.join(", ") || "(none)";
-
-  let allowed: string;
-  let locked: string;
 
-  switch (phase) {
-    case "red":
-      allowed = `Test files (${redPatterns})`;
-      locked = `Implementation files (${greenPatterns})`;
-      break;
-    case "green":
-      allowed = `Implementation files (${greenPatterns})`;
-      locked = `Test files (${redPatterns})`;
-      break;
-    case "refactor":
-      return (
-        "**TDD phase: REFACTOR** — All files are free to modify. " +
-        "Do not change behavior. When done, call `next_tdd_phase`."
-      );
-    default:
-      return "";
-  }
-
-  return (
-    `**TDD phase: ${phase.toUpperCase()}**\n` +
-    `- Allowed: ${allowed}\n` +
-    `- Locked: ${locked}\n` +
-    "Files not matching either pattern are free to modify.\n" +
-    "Call `next_tdd_phase` to advance the cycle."
-  );
-}

package/adapters/pi/tools.ts

@@ -38,10 +38,6 @@ export function registerTools(pi: ExtensionAPI): void {
       const { state, config } = tdd;
       const from = state.current;
       const to = nextPhase(from);
-      if (!to) {
-        tddLog(tddDir, "WARN", "next_tdd_phase: no next phase", { from });
-        return { content: [{ type: "text", text: `No next phase from ${from}.` }], details: {} };
-      }
 
       tddLog(tddDir, "INFO", "next_tdd_phase: starting", { from, to });
 
@@ -59,7 +55,7 @@ export function registerTools(pi: ExtensionAPI): void {
               text:
                 `BLOCKED: files not allowed in ${from.toUpperCase()} phase:\n` +
                 violations.map((f) => `  - ${f}`).join("\n") +
-                "\nRevert or remove them before proceeding.",
+                `\nRevert or remove them before proceeding.\n\nInspect with: cd .pi/tdd && git diff HEAD -- ${violations[0]}`,
             },
           ],
           details: {},

package/engine/config.test.ts

@@ -121,5 +121,56 @@ describe("loadConfig", () => {
         expect(() => loadConfig(dir)).toThrow();
       });
     });
+
+    it("throws when allowedRedPhaseFiles is empty", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: [],
+            allowedGreenPhaseFiles: ["src/**/*.ts"],
+            testCommands: ["npm test"],
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+
+    it("throws when allowedGreenPhaseFiles is empty", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+            allowedGreenPhaseFiles: [],
+            testCommands: ["npm test"],
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
+
+    it("throws when testCommands is empty", () => {
+      withTempDir((dir) => {
+        const tddDir = join(dir, ".pi", "tdd");
+        mkdirSync(tddDir, { recursive: true });
+        writeFileSync(
+          join(tddDir, "rules.json"),
+          JSON.stringify({
+            allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+            allowedGreenPhaseFiles: ["src/**/*.ts"],
+            testCommands: [],
+          }),
+          "utf-8",
+        );
+        expect(() => loadConfig(dir)).toThrow();
+      });
+    });
   });
 });

package/engine/config.ts

@@ -13,14 +13,14 @@ export function loadConfig(projectRoot: string): Config {
   const raw = readFileSync(path, "utf-8");
   const parsed = JSON.parse(raw);
 
-  if (!Array.isArray(parsed.allowedRedPhaseFiles)) {
-    throw new Error("rules.json: allowedRedPhaseFiles must be an array");
+  if (!Array.isArray(parsed.allowedRedPhaseFiles) || parsed.allowedRedPhaseFiles.length === 0) {
+    throw new Error("rules.json: allowedRedPhaseFiles must be a non-empty array");
   }
-  if (!Array.isArray(parsed.allowedGreenPhaseFiles)) {
-    throw new Error("rules.json: allowedGreenPhaseFiles must be an array");
+  if (!Array.isArray(parsed.allowedGreenPhaseFiles) || parsed.allowedGreenPhaseFiles.length === 0) {
+    throw new Error("rules.json: allowedGreenPhaseFiles must be a non-empty array");
   }
-  if (!Array.isArray(parsed.testCommands)) {
-    throw new Error("rules.json: testCommands must be an array");
+  if (!Array.isArray(parsed.testCommands) || parsed.testCommands.length === 0) {
+    throw new Error("rules.json: testCommands must be a non-empty array");
   }
 
   return {

package/engine/git.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { initGit, snapshot, changesSinceSnapshot, modifiedFiles, untrackedFiles, restoreFiles, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
+import { initGit, snapshot, changesSinceSnapshot, modifiedFiles, untrackedFiles, restoreFilesTo, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
 
 let testDir: string;
 
@@ -56,11 +56,11 @@ describe("git operations", () => {
     expect(changes).toContain("another.ts");
   });
 
-  it("restoreFiles reverts specific files", () => {
+  it("restoreFilesTo reverts specific files", () => {
     writeFileSync(join(testDir, "src", "main.ts"), "// to be reverted", "utf-8");
     expect(modifiedFiles(testDir)).toContain("src/main.ts");
 
-    restoreFiles(testDir, ["src/main.ts"]);
+    restoreFilesTo(testDir, ["src/main.ts"]);
     expect(modifiedFiles(testDir)).not.toContain("src/main.ts");
   });
 
@@ -94,9 +94,9 @@ describe("git operations", () => {
     }
   });
 
-  it("restoreFiles does nothing when files list is empty", () => {
+  it("restoreFilesTo does nothing when files list is empty", () => {
     // Should not throw
-    expect(() => restoreFiles(testDir, [])).not.toThrow();
+    expect(() => restoreFilesTo(testDir, [])).not.toThrow();
   });
 });
 

package/engine/git.ts

@@ -61,7 +61,7 @@ export function changesSinceSnapshot(projectRoot: string): string[] {
   return [...new Set([...modifiedFiles(projectRoot), ...untrackedFiles(projectRoot)])];
 }
 
-export function restoreFiles(projectRoot: string, files: string[]): void {
+export function restoreFilesTo(projectRoot: string, files: string[], source?: string): void {
   if (files.length === 0) return;
 
   // Separate tracked (git restore) from untracked (delete)
@@ -76,7 +76,8 @@ export function restoreFiles(projectRoot: string, files: string[]): void {
 
   if (trackedFiles.length > 0) {
     const escaped = trackedFiles.map((f) => `"${f}"`).join(" ");
-    gitExec(`restore -- ${escaped}`, projectRoot, { stdio: "pipe" as const });
+    const sourceFlag = source ? `--source=${source} ` : "";
+    gitExec(`restore ${sourceFlag}--worktree -- ${escaped}`, projectRoot, { stdio: "pipe" as const });
   }
 
   for (const f of untrackedFiles) {
@@ -88,6 +89,16 @@ export function restoreFiles(projectRoot: string, files: string[]): void {
   }
 }
 
+/**
+ * Create a lightweight commit of the current working tree without touching the stash ref.
+ * Returns the commit hash. Used as a pre-bash baseline for per-command diff.
+ */
+export function gitStashCreate(projectRoot: string): string {
+  const hash = gitExec("stash create --include-untracked", projectRoot).trim();
+  if (!hash) throw new Error("git stash create returned empty hash");
+  return hash;
+}
+
 export function headHash(projectRoot: string): string {
   return gitExec("rev-parse HEAD", projectRoot).trim();
 }
@@ -107,6 +118,17 @@ export function hasParent(projectRoot: string): boolean {
   }
 }
 
+/**
+ * Get files changed since a specific commit (instead of HEAD).
+ */
+export function changesSince(projectRoot: string, commitHash: string): string[] {
+  const out = gitExec(`diff --name-only ${commitHash} -- .`, projectRoot).trim();
+  const files = out ? out.split("\n") : [];
+  // Also include untracked files
+  const untracked = untrackedFiles(projectRoot);
+  return [...new Set([...files, ...untracked])];
+}
+
 /** Hard reset — discard all uncommitted changes (tracked and untracked), keep HEAD. */
 export function resetHard(projectRoot: string): void {
   gitExec("reset --hard", projectRoot, { stdio: "pipe" as const });

package/engine/index.ts

@@ -1,5 +1,5 @@
 export { isAllowed, disallowedFiles } from "./enforce.js";
-export { initGit, snapshot, changesSinceSnapshot, modifiedFiles, untrackedFiles, restoreFiles, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
+export { initGit, snapshot, changesSinceSnapshot, changesSince, modifiedFiles, untrackedFiles, restoreFilesTo, gitStashCreate, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
 export { loadConfig } from "./config.js";
 export { loadPhaseState, savePhaseState } from "./state.js";
 export { nextPhase, checkGate, getDisallowedChanges } from "./transition.js";

package/engine/state.test.ts

@@ -21,12 +21,12 @@ describe("loadPhaseState", () => {
     });
   });
 
-  it("returns parsed state from phase.json", () => {
+  it("returns parsed state from state.json", () => {
     withTempDir((dir) => {
       const tddDir = join(dir, ".pi", "tdd");
       mkdirSync(tddDir, { recursive: true });
       writeFileSync(
-        join(tddDir, "phase.json"),
+        join(tddDir, "state.json"),
         JSON.stringify({ enabled: true, current: "green" }),
         "utf-8",
       );
@@ -41,7 +41,7 @@ describe("loadPhaseState", () => {
       const tddDir = join(dir, ".pi", "tdd");
       mkdirSync(tddDir, { recursive: true });
       writeFileSync(
-        join(tddDir, "phase.json"),
+        join(tddDir, "state.json"),
         JSON.stringify({ enabled: true, current: "blurple" }),
         "utf-8",
       );
@@ -54,7 +54,7 @@ describe("loadPhaseState", () => {
       const tddDir = join(dir, ".pi", "tdd");
       mkdirSync(tddDir, { recursive: true });
       writeFileSync(
-        join(tddDir, "phase.json"),
+        join(tddDir, "state.json"),
         JSON.stringify({ enabled: false, current: "off" }),
         "utf-8",
       );
@@ -66,14 +66,14 @@ describe("loadPhaseState", () => {
     withTempDir((dir) => {
       const tddDir = join(dir, ".pi", "tdd");
       mkdirSync(tddDir, { recursive: true });
-      writeFileSync(join(tddDir, "phase.json"), "not json{{{", "utf-8");
+      writeFileSync(join(tddDir, "state.json"), "not json{{{", "utf-8");
       expect(() => loadPhaseState(dir)).toThrow();
     });
   });
 });
 
 describe("savePhaseState", () => {
-  it("writes phase.json and can be read back", () => {
+  it("writes state.json and can be read back", () => {
     withTempDir((dir) => {
       savePhaseState(dir, { enabled: true, current: "refactor" });
       const state = loadPhaseState(dir);

package/engine/state.ts

@@ -6,7 +6,7 @@ const TDD_DIR = ".pi/tdd";
 const VALID_PHASES = new Set(["red", "green", "refactor"]);
 
 export function phaseStatePath(projectRoot: string): string {
-  return join(projectRoot, TDD_DIR, "phase.json");
+  return join(projectRoot, TDD_DIR, "state.json");
 }
 
 function ensureDir(path: string): void {
@@ -22,7 +22,7 @@ export function loadPhaseState(projectRoot: string): PhaseState {
   const parsed = JSON.parse(raw) as PhaseState;
 
   if (typeof parsed.current !== "string" || !VALID_PHASES.has(parsed.current)) {
-    throw new Error(`phase.json: invalid phase "${String(parsed.current)}". Must be red, green, or refactor.`);
+    throw new Error(`state.json: invalid phase "${String(parsed.current)}". Must be red, green, or refactor.`);
   }
 
   return {

package/engine/transition.test.ts

@@ -42,17 +42,7 @@ const testConfig: Config = {
   timeoutSeconds: 30,
 };
 
-const emptyConfig: Config = { ...testConfig, testCommands: [] };
-
 describe("checkGate", () => {
-  describe("empty test commands (gate skipped)", () => {
-    it("passes every transition when no test commands configured", async () => {
-      const r1 = await checkGate("red", "green", makeRunner(false), emptyConfig);
-      expect(r1.passed).toBe(true);
-      const r2 = await checkGate("red", "green", makeRunner(true), emptyConfig);
-      expect(r2.passed).toBe(true);
-    });
-  });
 
   describe("red → green (tests must fail)", () => {
     it("allows when tests fail", async () => {
@@ -64,7 +54,7 @@ describe("checkGate", () => {
     it("blocks when tests pass", async () => {
       const r = await checkGate("red", "green", makeRunner(true), testConfig);
       expect(r.passed).toBe(false);
-      expect(r.message).toMatch(/break a test/i);
+      expect(r.message).toMatch(/transitioning to GREEN/i);
     });
   });
 
@@ -78,7 +68,7 @@ describe("checkGate", () => {
     it("blocks when tests fail", async () => {
       const r = await checkGate("green", "refactor", makeRunner(false), testConfig);
       expect(r.passed).toBe(false);
-      expect(r.message).toMatch(/failing/i);
+      expect(r.message).toMatch(/transitioning to REFACTOR/i);
     });
   });
 
@@ -92,17 +82,10 @@ describe("checkGate", () => {
     it("blocks when tests fail", async () => {
       const r = await checkGate("refactor", "red", makeRunner(false), testConfig);
       expect(r.passed).toBe(false);
-      expect(r.message).toMatch(/failing/i);
+      expect(r.message).toMatch(/transitioning to RED/i);
     });
   });
 
-  describe("unknown transition", () => {
-    it("blocks with message containing the transition string", async () => {
-      const r = await checkGate("green", "red" as any, makeRunner(true), testConfig);
-      expect(r.passed).toBe(false);
-      expect(r.message).toContain("green→red");
-    });
-  });
 
   it("passes test commands to the runner", async () => {
     let captured: string[] | undefined;

package/engine/transition.ts

@@ -29,10 +29,6 @@ export async function checkGate(
   testRunner: TestRunner,
   config: Config,
 ): Promise<GateResult> {
-  if (config.testCommands.length === 0) {
-    return { passed: true, message: "No test commands configured — gate skipped." };
-  }
-
   const result = await testRunner(config.testCommands, config.timeoutSeconds);
 
   switch (`${from}→${to}` as Transition) {
@@ -40,23 +36,29 @@ export async function checkGate(
       if (result.passed) {
         return {
           passed: false,
-          message: "Tests pass. Break a test first before transitioning to GREEN.",
+          message: "Tests pass. Add a failing test before transitioning to GREEN.",
         };
       }
       return { passed: true, message: "Tests fail — proceed to GREEN." };
 
     case "green→refactor":
+      if (!result.passed) {
+        return {
+          passed: false,
+          message: "Tests fail. Fix them before transitioning to REFACTOR.",
+        };
+      }
+      return { passed: true, message: "All tests pass — proceeding." };
+
     case "refactor→red":
       if (!result.passed) {
         return {
           passed: false,
-          message: "Tests must pass before transitioning. Fix failing tests first.",
+          message: "Tests fail. Fix them before transitioning to RED.",
         };
       }
       return { passed: true, message: "All tests pass — proceeding." };
 
-    default:
-      return { passed: false, message: `Unknown transition: ${from}→${to}` };
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdd-enforcer",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "keywords": [
     "pi-package"