tdd-enforcer 0.1.9 → 0.2.1

package/adapters/pi/helpers.test.ts

@@ -44,7 +44,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("returns missing state.json when rules exists but state missing", () => {
+  it("auto-creates state.json when missing (default RED disabled)", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -53,12 +53,15 @@ describe("loadTddState", () => {
         "utf-8",
       );
       const result = loadTddState(dir);
-      expect(result.ok).toBe(false);
-      expect(result.reason).toContain("state.json");
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state.enabled).toBe(false);
+        expect(result.state.current).toBe("red");
+      }
     });
   });
 
-  it("returns invalid state.json error for malformed JSON", () => {
+  it("auto-creates state.json when corrupted (recovers to default)", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -68,8 +71,11 @@ describe("loadTddState", () => {
       );
       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/state.json");
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state.enabled).toBe(false);
+        expect(result.state.current).toBe("red");
+      }
     });
   });
 
@@ -92,7 +98,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("returns disabled error when state.json has enabled: false", () => {
+  it("returns ok when state.json has enabled: false (callers check enabled)", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -106,8 +112,11 @@ describe("loadTddState", () => {
         "utf-8",
       );
       const result = loadTddState(dir);
-      expect(result.ok).toBe(false);
-      expect(result.reason).toContain("TDD is not enabled");
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state.enabled).toBe(false);
+        expect(result.state.current).toBe("red");
+      }
     });
   });
 
@@ -135,7 +144,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("heals missing git repo automatically", () => {
+  it("auto-creates git repo when missing", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -155,12 +164,12 @@ describe("loadTddState", () => {
       const result = loadTddState(dir);
       expect(result.ok).toBe(true);
 
-      // Git should now exist
+      // Git should now exist — loadTddState heals it
       expect(existsSync(gitDir)).toBe(true);
     });
   });
 
-  it("handles multiple calls without error (existing git is reused)", () => {
+  it("handles multiple calls without error", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -182,7 +191,7 @@ describe("loadTddState", () => {
     });
   });
 
-  it("passes through the state.json validation error for invalid current phase", () => {
+  it("recovers from invalid current phase in state.json (auto-creates default)", () => {
     withTempDir((dir) => {
       mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
       writeFileSync(
@@ -196,8 +205,11 @@ describe("loadTddState", () => {
         "utf-8",
       );
       const result = loadTddState(dir);
-      expect(result.ok).toBe(false);
-      expect(result.reason).toContain("Invalid .pi/tdd/state.json");
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state.enabled).toBe(false);
+        expect(result.state.current).toBe("red");
+      }
     });
   });
 });

package/adapters/pi/helpers.ts

@@ -1,52 +1,64 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { loadPhaseState, loadConfig, initGit } from "../../engine/index.js";
-import type { PhaseState, Config } from "../../engine/types.js";
+import { loadPhaseState, savePhaseState, loadConfig, headMessage, nextPhase, initGit } from "../../engine/index.js";
+import type { PhaseState, Config, Phase } from "../../engine/types.js";
 
 export type TddLoadResult =
   | { ok: true; state: PhaseState; config: Config }
   | { ok: false; reason: string };
 
+/**
+ * Recover state.json from private git HEAD, or create default.
+ * Returns the state (does not save to disk — caller does that).
+ */
+function recoverState(root: string, tddDir: string): PhaseState {
+  const gitDir = join(tddDir, ".git");
+  if (existsSync(gitDir)) {
+    try {
+      const msg = headMessage(root);
+      const m = msg.match(/^tdd: (red|green|refactor|init)$/);
+      if (m) {
+        const headPhase = m[1] as Phase;
+        if (headPhase === "init") {
+          return { enabled: false, current: "red" };
+        }
+        const next = nextPhase(headPhase);
+        return { enabled: true, current: next ?? "red" };
+      }
+    } catch {
+      // No commits or bad HEAD — fall through to default
+    }
+  }
+  return { enabled: false, current: "red" };
+}
+
 /**
  * Load TDD state + config in one go.
- * Returns ok:true with state and config when everything is valid and ready.
+ * Auto-creates state.json from private git HEAD when missing or corrupted.
+ * Returns ok:true with state and config when rules.json is valid.
  * Returns ok:false with a specific reason string otherwise.
+ *
+ * Callers must check state.enabled themselves if they need active enforcement.
  */
 export function loadTddState(root: string): TddLoadResult {
   const tddDir = join(root, ".pi", "tdd");
   if (!existsSync(tddDir)) {
-    return { ok: false, reason: "Missing .pi/tdd/ directory. See the tdd-init skill to learn how to set up TDD configs." };
+    return { ok: false, reason: "Missing .pi/tdd/ directory. See the tdd-enforcer skill to learn how to set up TDD configs." };
   }
 
   const rulesPath = join(tddDir, "rules.json");
   if (!existsSync(rulesPath)) {
-    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, "state.json");
-  if (!existsSync(phasePath)) {
-    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/state.json: ${(e as Error).message}` };
+    return { ok: false, reason: "Missing .pi/tdd/rules.json. See the tdd-enforcer skill to learn how to set up TDD configs." };
   }
 
   let config: Config;
   try {
     config = loadConfig(root);
   } catch (e) {
-    return { ok: false, reason: `Invalid .pi/tdd/rules.json: ${(e as Error).message}` };
+    return { ok: false, reason: `Invalid .pi/tdd/rules.json: ${(e as Error).message}. See the tdd-enforcer skill.` };
   }
 
-  if (!state.enabled) {
-    return { ok: false, reason: "TDD is not enabled. Run /tdd:on to enable it." };
-  }
-
-  // Heal git if missing
+  // Init git if missing — required for state recovery and all consumers
   const gitDir = join(tddDir, ".git");
   if (!existsSync(gitDir)) {
     try {
@@ -56,5 +68,20 @@ export function loadTddState(root: string): TddLoadResult {
     }
   }
 
+  // Auto-create state.json if missing or corrupted
+  const phasePath = join(tddDir, "state.json");
+  let state: PhaseState | undefined;
+  if (existsSync(phasePath)) {
+    try {
+      state = loadPhaseState(root);
+    } catch {
+      // Corrupted — recover below
+    }
+  }
+  if (!state) {
+    state = recoverState(root, tddDir);
+    savePhaseState(root, state);
+  }
+
   return { ok: true, state, config };
 }

package/adapters/pi/hooks.ts

@@ -67,6 +67,16 @@ export function registerHooks(pi: ExtensionAPI): void {
 
     // Patterns in rules.json are relative to repo root; convert absolute path
     const relPath = relative(root, filePath);
+
+    // Never allow writes to .pi/tdd/ when TDD is active
+    if (relPath.startsWith(".pi/tdd/")) {
+      tddLog(tddDir, "INFO", "tool_call: blocked .pi/tdd/ file", { toolName, relPath });
+      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.",
+      };
+    }
+
     const allowed = isAllowed(relPath, phase, config);
     tddLog(tddDir, "DEBUG", "tool_call: check", { toolName, relPath, phase, allowed });
 
@@ -111,10 +121,6 @@ export function registerHooks(pi: ExtensionAPI): void {
 
     const { state, config } = tdd;
     const phase = state.current;
-    if (phase === "refactor") {
-      tddLog(tddDir, "DEBUG", "tool_result: refactor phase, no check");
-      return;
-    }
 
     // Diff against pre-bash stash — only changes from THIS command
     const changed = changesSince(root, stashHash);
@@ -124,7 +130,22 @@ export function registerHooks(pi: ExtensionAPI): void {
       return;
     }
 
-    const cmdViolations = changed.filter((f) => !isAllowed(f, phase, config));
+    // Config files (.pi/tdd/) are always violations when TDD is active
+    const tddViolations = changed.filter((f) => f.startsWith(".pi/tdd/"));
+
+    if (phase === "refactor") {
+      // In refactor, only .pi/tdd/ files are violations
+      if (tddViolations.length === 0) {
+        tddLog(tddDir, "DEBUG", "tool_result: refactor phase, no TDD dir violations");
+        return;
+      }
+    }
+
+    const phaseViolations =
+      phase === "refactor" ? [] : changed.filter((f) => !isAllowed(f, phase, config));
+
+    const cmdViolations = [...new Set([...tddViolations, ...phaseViolations])];
+
     if (cmdViolations.length === 0) {
       tddLog(tddDir, "DEBUG", "tool_result: no violations among changed files", {
         changed,
@@ -140,8 +161,10 @@ export function registerHooks(pi: ExtensionAPI): void {
     // 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));
+    // Find remaining allowed changes from this command (exclude .pi/tdd/)
+    const cmdAllowed = changed.filter(
+      (f) => isAllowed(f, phase, config) && !f.startsWith(".pi/tdd/"),
+    );
 
     const existingText = event.content.map((c) => ("text" in c ? c.text : "")).join("");
     let warning = `\n\n⛔ ${phase.toUpperCase()}: reverted locked files modified by bash:`;

package/adapters/pi/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { loadPhaseState, loadConfig, savePhaseState, initGit, resetGit, snapshot } from "../../engine/index.js";
+import { savePhaseState, resetGit, snapshot } from "../../engine/index.js";
 import { registerTools } from "./tools.js";
 import { registerHooks } from "./hooks.js";
 import { loadTddState } from "./helpers.js";
@@ -16,46 +16,14 @@ export default function (pi: ExtensionAPI) {
 
       tddLog(tddDir, "INFO", "tdd:on: starting");
 
-      if (!existsSync(tddDir)) {
-        tddLog(tddDir, "WARN", "tdd:on: missing .pi/tdd/ directory");
-        ctx.ui.notify("Missing .pi/tdd/ directory. See the tdd-init skill to learn how to set up TDD configs.", "error");
+      const setup = loadTddState(root);
+      if (!setup.ok) {
+        tddLog(tddDir, "WARN", "tdd:on: setup invalid", { reason: setup.reason });
+        ctx.ui.notify(setup.reason, "error");
         return;
       }
 
-      const rulesPath = join(tddDir, "rules.json");
-      if (!existsSync(rulesPath)) {
-        tddLog(tddDir, "WARN", "tdd:on: missing rules.json");
-        ctx.ui.notify("Missing .pi/tdd/rules.json. See the tdd-init skill to learn how to set up TDD configs.", "error");
-        return;
-      }
-
-      const phasePath = join(tddDir, "state.json");
-      if (!existsSync(phasePath)) {
-        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;
-      }
-
-      let state;
-      try {
-        state = loadPhaseState(root);
-      } catch (e) {
-        tddLog(tddDir, "WARN", "tdd:on: invalid state.json", {
-          error: (e as Error).message,
-        });
-        ctx.ui.notify("Invalid .pi/tdd/state.json. Fix or delete it, then run /tdd:on again.", "error");
-        return;
-      }
-
-      try {
-        loadConfig(root);
-      } catch (e) {
-        tddLog(tddDir, "WARN", "tdd:on: invalid rules.json", {
-          error: (e as Error).message,
-        });
-        ctx.ui.notify("Invalid .pi/tdd/rules.json. Fix or delete it, then run /tdd:on again.", "error");
-        return;
-      }
+      const { state } = setup;
 
       if (state.enabled) {
         tddLog(tddDir, "INFO", "tdd:on: already enabled", {
@@ -65,21 +33,6 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      if (!existsSync(join(tddDir, ".git", "HEAD"))) {
-        try {
-          initGit(root);
-          tddLog(tddDir, "INFO", "tdd:on: git initialised");
-        } catch (e) {
-          tddLog(tddDir, "ERROR", "tdd:on: git init failed", {
-            error: (e as Error).message,
-          });
-          ctx.ui.notify("Failed to initialise private git repo.", "error");
-          return;
-        }
-      } else {
-        tddLog(tddDir, "DEBUG", "tdd:on: git repo already exists");
-      }
-
       // Snapshot working tree so stale baseline doesn't nuke user changes
       snapshot(root, state.current);
       tddLog(tddDir, "INFO", "tdd:on: snapshot taken", {
@@ -101,17 +54,15 @@ export default function (pi: ExtensionAPI) {
       const root = ctx.cwd;
       const tddDir = join(root, ".pi", "tdd");
 
-      let state;
-      try {
-        state = loadPhaseState(root);
-      } catch (e) {
-        tddLog(tddDir, "WARN", "tdd:off: invalid state.json", {
-          error: (e as Error).message,
-        });
-        ctx.ui.notify("Invalid .pi/tdd/state.json. Fix or delete it, then run /tdd:off again.", "error");
+      const setup = loadTddState(root);
+      if (!setup.ok) {
+        tddLog(tddDir, "WARN", "tdd:off: setup invalid", { reason: setup.reason });
+        ctx.ui.notify(setup.reason, "error");
         return;
       }
 
+      const { state } = setup;
+
       if (!state.enabled) {
         tddLog(tddDir, "INFO", "tdd:off: already disabled");
         ctx.ui.notify("TDD already disabled", "info");
@@ -135,7 +86,7 @@ export default function (pi: ExtensionAPI) {
       const result = loadTddState(root);
 
       if (!result.ok) {
-        tddLog(tddDir, "WARN", "tdd:status: TDD not active", {
+        tddLog(tddDir, "WARN", "tdd:status: setup invalid", {
           reason: result.reason,
         });
         ctx.ui.notify(`TDD: ${result.reason}`, "error");
@@ -143,17 +94,19 @@ export default function (pi: ExtensionAPI) {
       }
 
       const { state, config } = result;
+      const enabledStr = state.enabled ? "enabled" : "disabled";
       const phaseStr = state.current.toUpperCase();
       const redGlobs = config.allowedRedPhaseFiles.join(", ") || "(none)";
       const greenGlobs = config.allowedGreenPhaseFiles.join(", ") || "(none)";
       const commands = config.testCommands.join(", ") || "(none)";
 
       tddLog(tddDir, "INFO", "tdd:status: queried", {
+        enabled: state.enabled,
         phase: state.current,
       });
 
       ctx.ui.notify(
-        `TDD enforcer enabled\n` +
+        `TDD enforcer ${enabledStr}\n` +
         `Current phase: ${phaseStr}\n` +
         `Test files: ${redGlobs}\n` +
         `Impl files: ${greenGlobs}\n` +
@@ -173,9 +126,10 @@ export default function (pi: ExtensionAPI) {
 
       tddLog(tddDir, "INFO", "tdd:reset: starting");
 
-      if (!existsSync(tddDir)) {
-        tddLog(tddDir, "WARN", "tdd:reset: missing .pi/tdd/ directory");
-        ctx.ui.notify("No .pi/tdd/ directory found — nothing to reset.", "error");
+      const setup = loadTddState(root);
+      if (!setup.ok) {
+        tddLog(tddDir, "WARN", "tdd:reset: setup invalid", { reason: setup.reason });
+        ctx.ui.notify(setup.reason, "error");
         return;
       }
 

package/adapters/pi/prompts.ts

@@ -8,13 +8,17 @@ export function getNudgePrompt(phase: Phase, config: Config, matchedFiles?: stri
     case "red":
       return (
         `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."
+        "Only these files can be modified. Once tests fail, call `next_tdd_phase` to proceed to GREEN.\n" +
+        "Keep this cycle small. Write tests for one feature at a time. " +
+        "Cover happy path, edge cases, and unhappy paths before advancing to GREEN."
       );
     case "green":
       return (
         `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."
+        "Call `next_tdd_phase` to proceed to REFACTOR.\n" +
+        "If the RED phase tests were wrong, call `previous_tdd_phase` to go back and fix them. " +
+        "Don't be afraid to discard — clean slate beats patched code."
       );
     case "refactor":
       return (

package/adapters/pi/tools.ts

@@ -37,6 +37,10 @@ export function registerTools(pi: ExtensionAPI): void {
         tddLog(tddDir, "WARN", "next_tdd_phase: TDD not active", { reason: tdd.reason });
         return { content: [{ type: "text", text: `TDD: ${tdd.reason}` }], details: {} };
       }
+      if (!tdd.state.enabled) {
+        tddLog(tddDir, "WARN", "next_tdd_phase: TDD disabled");
+        return { content: [{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." }], details: {} };
+      }
 
       const { state, config } = tdd;
       const from = state.current;
@@ -124,8 +128,9 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "previous_tdd_phase",
     label: "Previous TDD Phase",
     description:
-      "WARNING: Destroys ALL uncommitted changes and pops the last snapshot commit. " +
-      "Working tree keeps the popped commit's content as unstaged changes.",
+      "WARNING: Discards ALL changes made in the current phase and reverts the working tree " +
+      "to what it was when the last phase ended. Use when the previous phase's work was wrong " +
+      "and this phase cannot proceed.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const root = ctx.cwd;
@@ -137,6 +142,10 @@ export function registerTools(pi: ExtensionAPI): void {
         });
         return { content: [{ type: "text", text: `TDD: ${tdd.reason}` }], details: {} };
       }
+      if (!tdd.state.enabled) {
+        tddLog(tddDir, "WARN", "previous_tdd_phase: TDD disabled");
+        return { content: [{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." }], details: {} };
+      }
 
       const { state } = tdd;
 
@@ -223,6 +232,10 @@ export function registerTools(pi: ExtensionAPI): void {
         });
         return { content: [{ type: "text", text: `TDD: ${result.reason}` }], details: {} };
       }
+      if (!result.state.enabled) {
+        tddLog(tddDir, "WARN", "tdd_status: TDD disabled");
+        return { content: [{ type: "text", text: "TDD is not enabled. Run /tdd:on to enable it." }], details: {} };
+      }
 
       const { state, config } = result;
       const phaseStr = state.current.toUpperCase();

package/behaviour.md

@@ -0,0 +1,146 @@
+# TDD Enforcer — Behaviour Spec
+
+## Entry Gate (all surfaces)
+
+Every surface (commands, hooks, tools) hits this first:
+
+```
+1. .pi/tdd/ exists?
+   NO  ──► error: "Missing .pi/tdd/. See the tdd-enforcer skill."
+
+2. rules.json exists and parses?
+   NO  ──► error: "Missing/invalid rules.json. See the tdd-enforcer skill."
+
+3. state.json exists and parses?
+   YES ──► use it
+   NO  ──► auto-create from git HEAD commit message.
+            If no git repo: create { enabled: false, current: "red" }.
+```
+
+After this gate, every surface has `state` + `config`. Then branches on `state.enabled`.
+
+---
+
+## Commands (user only)
+
+| Command | Gate check | After gate |
+|---------|-----------|------------|
+| `tdd:on` | Setup valid? | If `enabled` → error "already on". Init git (if missing), snapshot, set `enabled: true`. |
+| `tdd:off` | Setup valid? | If `disabled` → error "already off". Set `enabled: false`. |
+| `tdd:status` | Setup valid? | Show state + config regardless of `enabled`. |
+| `tdd:reset` | Setup valid? | Nuke private git, re-init, snapshot, set `enabled: false`. |
+| `tdd:red` / `tdd:green` / `tdd:refactor` | Setup valid? | If `disabled` → error "not enabled". Set `current` to target phase. |
+
+All errors reference the tdd-enforcer skill.
+
+---
+
+## Hooks (agent — automatic)
+
+| Hook | Gate + enabled | Behaviour |
+|------|---------------|-----------|
+| `tool_call` (write/edit) | Setup broken → pass through. Disabled → pass through. **Enabled** → block if `relPath` starts with `.pi/tdd/` OR phase-locked. | |
+| `tool_result` (bash) | Setup broken → pass through. Disabled → pass through. **Enabled** → revert if path starts with `.pi/tdd/` OR phase-locked. RETOOL revert paths to `.pi/tdd/` prefix check. | |
+
+---
+
+## Tools (agent — callable)
+
+| Tool | Gate + enabled | Behaviour |
+|------|---------------|-----------|
+| `next_tdd_phase` | Disabled → error. Enabled → run gate + snapshot + transition. | |
+| `previous_tdd_phase` | Disabled → error. Enabled → revert to previous snapshot. | |
+| `tdd_status` | Disabled → error. Enabled → show state + config. | |
+
+---
+
+## Flow Diagrams
+
+### Initial Setup Flow
+
+```
+User creates .pi/tdd/rules.json
+       │
+       ▼
+User runs /tdd:on
+       │
+       ▼
+Gate: .pi/tdd/ exists? ──NO──► error (agent creates it)
+       │
+      YES
+       │
+       ▼
+Gate: rules.json exists? ──NO──► error (agent creates it)
+       │
+      YES
+       │
+       ▼
+Gate: rules.json valid? ──NO──► error (agent fixes it)
+       │
+      YES
+       │
+       ▼
+Gate: state.json exists? ──NO──► auto-create
+       │
+      YES/auto-created
+       │
+       ▼
+Init git (if missing) ──► snapshot ──► enabled: true
+       │
+       ▼
+TDD active — RED phase, enforcement on
+```
+
+### Phase Cycle Flow
+
+```
+RED: write tests
+  │  tests fail? ──NO──► "Tests passed. Add a failing test before transitioning."
+  │ YES
+  ├─► next_tdd_phase ──► GREEN
+  │
+GREEN: implement features
+  │  tests pass? ──NO──► "Tests failed. Fix them before transitioning."
+  │ YES
+  ├─► next_tdd_phase ──► REFACTOR
+  │
+REFACTOR: refactor freely
+  │  tests pass? ──NO──► "Tests failed. Fix them before transitioning."
+  │ YES
+  ├─► next_tdd_phase ──► RED (new cycle)
+```
+
+### Bash Enforcement Flow
+
+```
+Agent runs bash command
+       │
+       ▼
+tool_call hook: stash pre-command state
+       │
+       ▼
+Bash executes (modifies files)
+       │
+       ▼
+tool_result hook: diff against stash
+       │
+       ▼
+For each changed file:
+  ├── path starts with ".pi/tdd/"? ──YES──► revert, flag as violation
+  ├── locked in current phase? ──YES──► revert, flag as violation
+  └── no violations ──► keep changes
+       │
+       ▼
+Return warning listing reverted vs retained files
+```
+
+---
+
+## Protection Summary
+
+| Surface | `.pi/tdd/` locked? | Phase-locked files? |
+|---------|-------------------|-------------------|
+| write/edit (TDD enabled) | ✅ Block | ✅ Block |
+| write/edit (TDD disabled) | ❌ Free | ❌ Free |
+| bash (TDD enabled) | ✅ Reverted | ✅ Reverted |
+| bash (TDD disabled) | ❌ Free | ❌ Free |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdd-enforcer",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -14,6 +14,9 @@
   "pi": {
     "extensions": [
       "./adapters/pi/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/tdd-enforcer/SKILL.md

@@ -0,0 +1,97 @@
+# TDD Enforcer Skill
+
+This extension enforces the **Red-Green-Refactor** cycle of TDD.
+
+It locks files per phase — only test files in RED, only implementation files in GREEN, everything allowed in REFACTOR. The entire `.pi/tdd/` directory is locked when TDD is active.
+
+---
+
+## What the Agent Controls vs What the User Controls
+
+| Action | Who |
+|--------|-----|
+| Create `.pi/tdd/rules.json` with file patterns and test commands | **Agent** |
+| Run `/tdd:on` to enable enforcement | **User** |
+| Run `/tdd:off` to disable enforcement | **User** |
+| Run `/tdd:reset` to nuke all recorded state and start fresh | **User** |
+| Run `/tdd:status` to check state and config | **User** |
+| Call `next_tdd_phase` to advance through the cycle | **Agent** |
+| Call `previous_tdd_phase` to roll back when previous phase work was wrong | **Agent** |
+| Call `tdd_status` to check enforcement status | **Agent** |
+
+---
+
+## Setup
+
+1. **Agent** creates `.pi/tdd/rules.json` with these fields:
+
+```json
+{
+  "allowedRedPhaseFiles": ["tests/**/*.test.ts"],
+  "allowedGreenPhaseFiles": ["src/**/*.ts"],
+  "testCommands": ["npm test"],
+  "timeoutSeconds": 30
+}
+```
+
+- `allowedRedPhaseFiles` — globs the agent can create/modify in RED phase (tests)
+- `allowedGreenPhaseFiles` — globs the agent can create/modify in GREEN phase (implementation)
+- `testCommands` — shell commands to run tests
+- `timeoutSeconds` — test timeout per command
+
+2. **User** runs `/tdd:on` to enable enforcement.
+
+---
+
+## Phase Rules
+
+### RED
+Write failing tests matching `allowedRedPhaseFiles` patterns. Files matching `allowedGreenPhaseFiles` are locked. Files matching neither set are always free. Call `next_tdd_phase` once tests fail.
+
+### GREEN
+Implement features matching `allowedGreenPhaseFiles` patterns. Test files from `allowedRedPhaseFiles` are locked. Files matching neither set are always free. Call `next_tdd_phase` once tests pass.
+
+### REFACTOR
+All files are free to modify. Refactor without changing behaviour. Call `next_tdd_phase` once tests pass to start a new RED cycle.
+
+---
+
+## Hard Rules
+
+- **Never bypass TDD.** If TDD blocks a change, it's because you're in the wrong phase or the file isn't allowed in this phase. The solution is always to work within the rules, not around them.
+
+  - Need to change a locked file? Either advance through the cycle (`next_tdd_phase`) or roll back to fix earlier work (`previous_tdd_phase`).
+  - Wrong assumptions about the task? Roll back with `previous_tdd_phase`, the phase restarts clean.
+  - Fundamentally blocked? Ask the user to run the appropriate `/tdd:` command (change phase, disable, or reset).
+
+- **Never write to `.pi/tdd/`.** The extension owns that directory — writes are blocked and bash changes are reverted. Any change you make there is ignored or overwritten.
+
+- **Never run `/tdd:` commands yourself.** They're registered as user-only commands. They won't work when you type them.
+
+- **Don't be afraid to discard.** If the previous phase work was wrong, all current-phase changes are built on false assumptions. Prefer a clean slate — call `previous_tdd_phase` and redo it properly.
+
+- **Keep cycles small but tests comprehensive.** Write tests for one feature at a time. Cover happy path, edge cases, and unhappy paths before moving to GREEN. Small cycles mean less to lose if assumptions turn out wrong. Reverting becomes cheap and safe.
+
+---
+
+## Agent Tools
+
+### `next_tdd_phase`
+Runs transition gate checks. Fails if:
+- RED→GREEN: tests don't fail (must have a failing test)
+- GREEN→REFACTOR: tests fail (must pass)
+- REFACTOR→RED: tests fail (must pass)
+
+Also validates no locked files were modified. On success, records the current state and advances the phase.
+
+### `previous_tdd_phase`
+Use when the previous phase's work was wrong and the current phase cannot proceed because of it. Rolls back to the previous phase so that work can be redone correctly. All changes made in the current phase are lost.
+
+### `tdd_status`
+Shows the current phase, allowed file globs, and test commands.
+
+---
+
+## TDD is OFF — Enforcement is Suspended
+
+When TDD is disabled (`/tdd:off`), all files are free to modify. The hooks pass through and no blocks or reverts occur. To re-enable, ask the user to run `/tdd:on`.