tdd-enforcer 0.1.0

package/DESIGN.md

@@ -0,0 +1,184 @@
+# TDD Enforcer — pi Extension Design
+
+## Concept
+
+A pi extension that enforces the Red-Green-Refactor TDD cycle by:
+- Tracking current phase (RED / GREEN / REFACTOR)
+- Restricting which files the agent can modify per phase
+- Running tests on phase transitions to enforce red/green gate
+- Nudging the agent with phase-appropriate prompts
+
+## Tools
+
+### `next_tdd_phase`
+
+Advances the cycle:
+
+```
+RED ──(tests fail)──► GREEN ──(tests pass)──► REFACTOR ──(tests pass)──► RED
+```
+
+### `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.
+
+---
+
+## Phase Rules
+
+| Phase | `allowedRedPhaseFiles` | `allowedGreenPhaseFiles` | Everything else |
+|-------|----------------------|------------------------|-----------------|
+| RED | ✅ Allowed | ❌ Locked | ✅ Free |
+| GREEN | ❌ Locked | ✅ Allowed | ✅ Free |
+| REFACTOR | ✅ Allowed | ✅ Allowed | ✅ Free |
+
+### Transition Gates
+
+- **RED → GREEN**: Tests must **fail**. If tests pass, tool returns error — agent must break a test first.
+- **GREEN → REFACTOR**: Tests must **pass** (all exit codes zero).
+- **REFACTOR → RED**: Tests must **pass** (all exit codes zero).
+
+### Nudging Prompts
+
+Each successful transition returns a message guiding the agent:
+
+- **→ RED**: *"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."* (list matched files)
+- **→ GREEN**: *"You are now in **GREEN** phase. Files matching `allowedRedPhaseFiles` are locked. Implement features in `allowedGreenPhaseFiles` to make tests pass. Call `next_tdd_phase` to proceed to REFACTOR."*
+- **→ REFACTOR**: *"You are now in **REFACTOR** phase. Both `allowedRedPhaseFiles` and `allowedGreenPhaseFiles` are free to modify. Refactor without changing behavior. Call `next_tdd_phase` to start a new RED cycle."*
+
+---
+
+## File Enforcement: Private Git + `tool_call` Fast-Feedback
+
+### Source of truth: private git repo
+
+A separate git repository at `.pi/tdd/.git/` that tracks the project root as its working tree. The user's `.git/` is never touched.
+
+```
+.pi/tdd/
+├── .gitignore           # private git — excludes file patterns from snapshots
+├── phase.json           # {current: "red", stack: ["s1","s2","s3"]}
+├── rules.json           # user config
+└── .git/                # private git — init with --git-dir
+```
+
+**Setup:** `git init` with `--git-dir=.pi/tdd/.git --work-tree=<project-root>`.
+
+**On phase entry (snapshot):**
+`git add -A && git commit -m "tdd: <phase> <ts>"` — captures entire working tree state.
+
+**On `next_tdd_phase` / `previous_tdd_phase` (allowlist check):**
+- `git diff --name-only HEAD` against previous snapshot commit
+- Cross-reference each changed file against phase allowlist
+- Violations → BLOCK with list of disallowed files
+- Also check for untracked files (`git ls-files --others --exclude-standard`)
+
+**On `previous_tdd_phase` (revert):**
+- `git restore --source=<prev-commit> --worktree -- .` — restores project to exact prior snapshot
+- Pop the stack in `phase.json`
+
+### Benefits of private git
+
+- Catches ALL modifications — write, edit, bash, sed, python, C, anything — because it diffs the working tree, not tool calls
+- Cross-platform (git is everywhere)
+- No shell parsing, no fragile regexes, no edge cases
+- Zero interference with user's git — different `.git/`, no shared refs, no hooks, no global config
+- `.pi/tdd/` is disposable — user can nuke it anytime
+- Free diff, merge, partial restore, binary handling — no custom engine to write
+
+### Fast feedback: per-tool enforcement
+
+The transition-time check catches everything, but it's wasteful to let the agent work on wrong files for a full phase. We enforce per-tool:
+
+#### `write` / `edit` — pre-execution block
+
+The file path is a direct parameter. In `tool_call`:
+- If path is disallowed in current phase → `{ block: true, reason: "..." }`
+- Otherwise → allow
+
+#### `bash` — post-execution detect-and-revert
+
+Bash can modify files indirectly (redirects, `sed -i`, scripts, compilers). Parsing command strings to predict targets is fragile. Instead:
+
+1. **Let bash run** — no pre-check
+2. **In `tool_result`:** `git diff --name-only HEAD` + `git ls-files --others --exclude-standard` to get all changes since phase snapshot
+3. For each file: if it's disallowed in current phase → `git restore <filepath>` and append warning
+
+No in-memory tracking needed. The check is the same for every file regardless of how it was modified — write/edit changes that passed pre-check naturally match the allowed globs, violations get reverted.
+
+#### Why not regex bash parsing?
+
+Everyone else does it (pi-proof, pi-superteam, tdd-guard). It's fragile — misses `$(dynamic paths)`, glob expansion, scripts calling other scripts, piped commands, heredocs with variables. Our git-based post-check catches everything regex misses, with zero false negatives.
+
+Regex pre-check is optional (could catch obvious cases for better UX) but the git post-check is the reliable enforcer.
+
+---
+
+### `.gitignore`
+
+The private git's work-tree is the project root, so it respects the project's `.gitignore` automatically — no copy needed, no separate file needed.
+
+If the user wants to exclude additional files from TDD snapshots only, they can create `.pi/tdd/.gitignore` with those patterns. Git checks `.gitignore` starting from the work-tree root, so a file there is picked up naturally.
+
+---
+
+## Config: `.pi/tdd/rules.json`
+
+```json
+{
+  "allowedRedPhaseFiles": ["tests/**/*.test.ts", "specs/**/*.spec.ts"],
+  "allowedGreenPhaseFiles": ["src/**/*.ts"],
+  "testCommands": ["npm run test:unit", "npm run test:integration"],
+  "timeoutSeconds": 120
+}
+```
+
+- `allowedRedPhaseFiles`: Glob patterns for files allowed in RED phase (typically test files).
+- `allowedGreenPhaseFiles`: Glob patterns for files allowed in GREEN phase (typically implementation files).
+- Files matching neither set are free in all phases.
+- `testCommands`: `string` (shell-chained with `&&` for sequential) or `string[]` (run in parallel). Must be non-interactive.
+- `timeoutSeconds`: Per-command timeout. Extension passes it as pi's `bash` tool timeout param, so we don't rely on system `timeout` binary.
+
+---
+
+
+
+---
+
+## Phase State Persistence
+
+Stored in `.pi/tdd/phase.json`:
+
+```json
+{
+  "current": "green",
+  "enabled": true,
+  "stack": ["commit-hash-1", "commit-hash-2", "commit-hash-3"]
+}
+```
+
+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.
+
+---
+
+## Open Questions
+
+### Initial state
+
+How does a project start?
+
+- **Auto RED**: Start in RED unconditionally. If tests already pass, agent sees a warning that there's no failing test yet — it needs to write one or break one.
+- **Auto-detect**: Run tests on startup. If failing → RED. If passing → GREEN (agent is already in the "make it pass" phase).
+- **Prompt**: Ask the user what phase to start in.
+
+### Enabling/disabling
+
+Should we have `/tdd:on` and `/tdd:off` commands to toggle without unloading the extension?
+
+### Config location
+
+Only `.pi/tdd/rules.json` in project root? Or support nested configs?
+
+### Multiple projects / monorepos
+
+If the project root has sub-projects with different test commands, does rules.json support multiple entries keyed by directory?

package/adapters/pi/helpers.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect } from "vitest";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadTddState } from "./helpers.js";
+
+function withTempDir(fn: (dir: string) => void) {
+  const dir = join(tmpdir(), `tdd-helpers-test-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  try {
+    fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const validRules = {
+  allowedRedPhaseFiles: ["tests/**/*.test.ts"],
+  allowedGreenPhaseFiles: ["src/**/*.ts"],
+  testCommands: ["npm test"],
+  timeoutSeconds: 30,
+};
+
+const validPhase = {
+  enabled: true,
+  current: "red",
+};
+
+describe("loadTddState", () => {
+  it("returns missing dir error when .pi/tdd does not exist", () => {
+    withTempDir((dir) => {
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("Missing .pi/tdd/");
+    });
+  });
+
+  it("returns missing rules.json error when only dir exists", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("rules.json");
+    });
+  });
+
+  it("returns missing phase.json when rules exists but phase missing", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("phase.json");
+    });
+  });
+
+  it("returns invalid phase.json error for malformed JSON", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(join(dir, ".pi", "tdd", "phase.json"), "not json", "utf-8");
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("Invalid .pi/tdd/phase.json");
+    });
+  });
+
+  it("returns invalid rules.json error for malformed JSON", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        "not json",
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.json"),
+        JSON.stringify(validPhase),
+        "utf-8",
+      );
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("Invalid .pi/tdd/rules.json");
+    });
+  });
+
+  it("returns disabled error when phase.json has enabled: false", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.json"),
+        JSON.stringify({ enabled: false, current: "red" }),
+        "utf-8",
+      );
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(false);
+      expect(result.reason).toContain("TDD is not enabled");
+    });
+  });
+
+  it("returns ok with state and config when everything valid", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.json"),
+        JSON.stringify(validPhase),
+        "utf-8",
+      );
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.state.current).toBe("red");
+        expect(result.state.enabled).toBe(true);
+        expect(result.config.testCommands).toEqual(["npm test"]);
+        expect(result.config.allowedRedPhaseFiles).toEqual(["tests/**/*.test.ts"]);
+      }
+    });
+  });
+
+  it("heals missing git repo automatically", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.json"),
+        JSON.stringify(validPhase),
+        "utf-8",
+      );
+
+      const gitDir = join(dir, ".pi", "tdd", ".git");
+      expect(existsSync(gitDir)).toBe(false);
+
+      const result = loadTddState(dir);
+      expect(result.ok).toBe(true);
+
+      // Git should now exist
+      expect(existsSync(gitDir)).toBe(true);
+    });
+  });
+
+  it("handles multiple calls without error (existing git is reused)", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.json"),
+        JSON.stringify(validPhase),
+        "utf-8",
+      );
+
+      const r1 = loadTddState(dir);
+      expect(r1.ok).toBe(true);
+
+      const r2 = loadTddState(dir);
+      expect(r2.ok).toBe(true);
+    });
+  });
+
+  it("passes through the phase.json validation error for invalid current phase", () => {
+    withTempDir((dir) => {
+      mkdirSync(join(dir, ".pi", "tdd"), { recursive: true });
+      writeFileSync(
+        join(dir, ".pi", "tdd", "rules.json"),
+        JSON.stringify(validRules),
+        "utf-8",
+      );
+      writeFileSync(
+        join(dir, ".pi", "tdd", "phase.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");
+    });
+  });
+});

package/adapters/pi/helpers.ts

@@ -0,0 +1,60 @@
+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";
+
+export type TddLoadResult =
+  | { ok: true; state: PhaseState; config: Config }
+  | { ok: false; reason: string };
+
+/**
+ * Load TDD state + config in one go.
+ * Returns ok:true with state and config when everything is valid and ready.
+ * Returns ok:false with a specific reason string otherwise.
+ */
+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." };
+  }
+
+  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, "phase.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." };
+  }
+
+  let state: PhaseState;
+  try {
+    state = loadPhaseState(root);
+  } catch (e) {
+    return { ok: false, reason: `Invalid .pi/tdd/phase.json: ${(e as Error).message}` };
+  }
+
+  let config: Config;
+  try {
+    config = loadConfig(root);
+  } catch (e) {
+    return { ok: false, reason: `Invalid .pi/tdd/rules.json: ${(e as Error).message}` };
+  }
+
+  if (!state.enabled) {
+    return { ok: false, reason: "TDD is not enabled. Run /tdd to enable it." };
+  }
+
+  // Heal git if missing
+  const gitDir = join(tddDir, ".git");
+  if (!existsSync(gitDir)) {
+    try {
+      initGit(root);
+    } catch (e) {
+      return { ok: false, reason: `Failed to initialise private git repo: ${(e as Error).message}` };
+    }
+  }
+
+  return { ok: true, state, config };
+}

package/adapters/pi/hooks.ts

@@ -0,0 +1,59 @@
+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, restoreFiles } from "../../engine/git.js";
+import { loadTddState } from "./helpers.js";
+
+export function registerHooks(pi: ExtensionAPI): void {
+  pi.on("tool_call", async (event, ctx: ExtensionContext) => {
+    const root = ctx.cwd;
+    const tdd = loadTddState(root);
+    if (!tdd.ok) return;
+
+    const { state, config } = tdd;
+    const phase = state.current;
+
+    // write/edit pre-block
+    let filePath: string | undefined;
+    if (isToolCallEventType("write", event)) filePath = event.input.path;
+    else if (isToolCallEventType("edit", event)) filePath = event.input.path;
+    else return;
+
+    if (!filePath) return;
+
+    if (!isAllowed(filePath, phase, config)) {
+      return {
+        block: true,
+        reason: `TDD ${phase.toUpperCase()}: "${filePath}" is locked in this phase.`,
+      };
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx: ExtensionContext) => {
+    if (!isBashToolResult(event)) return;
+
+    const root = ctx.cwd;
+    const tdd = loadTddState(root);
+    if (!tdd.ok) return;
+
+    const { state, config } = tdd;
+    const phase = state.current;
+    if (phase === "refactor") return;
+
+    const changed = changesSinceSnapshot(root);
+    if (changed.length === 0) return;
+
+    const violations = changed.filter((f) => !isAllowed(f, phase, config));
+    if (violations.length === 0) return;
+
+    restoreFiles(root, violations);
+
+    const existingText = event.content.map((c) => ("text" in c ? c.text : "")).join("");
+    return {
+      content: [
+        { type: "text", text: existingText + `\n\n⚠️ TDD: Bash modified files locked in ${phase.toUpperCase()} phase. Reverted: ${violations.join(", ")}` },
+      ],
+    };
+  });
+
+}

package/adapters/pi/index.ts

@@ -0,0 +1,122 @@
+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 } from "../../engine/index.js";
+import { registerTools } from "./tools.js";
+import { registerHooks } from "./hooks.js";
+import { loadTddState } from "./helpers.js";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("tdd:on", {
+    description: "Enable TDD enforcement",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const root = ctx.cwd;
+      const tddDir = join(root, ".pi", "tdd");
+
+      if (!existsSync(tddDir)) {
+        ctx.ui.notify("Missing .pi/tdd/ directory. See the tdd-init skill to learn how to set up TDD configs.", "error");
+        return;
+      }
+
+      const rulesPath = join(tddDir, "rules.json");
+      if (!existsSync(rulesPath)) {
+        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, "phase.json");
+      if (!existsSync(phasePath)) {
+        ctx.ui.notify("Missing .pi/tdd/phase.json. See the tdd-init skill to learn how to set up TDD configs.", "error");
+        return;
+      }
+
+      let state;
+      try {
+        state = loadPhaseState(root);
+      } catch {
+        ctx.ui.notify("Invalid .pi/tdd/phase.json. Fix or delete it, then run /tdd:on again.", "error");
+        return;
+      }
+
+      try {
+        loadConfig(root);
+      } catch {
+        ctx.ui.notify("Invalid .pi/tdd/rules.json. Fix or delete it, then run /tdd:on again.", "error");
+        return;
+      }
+
+      if (state.enabled) {
+        ctx.ui.notify(`TDD already enabled — ${state.current.toUpperCase()} phase`, "info");
+        return;
+      }
+
+      if (!existsSync(join(tddDir, ".git", "HEAD"))) {
+        try {
+          initGit(root);
+        } catch {
+          ctx.ui.notify("Failed to initialise private git repo.", "error");
+          return;
+        }
+      }
+
+      state.enabled = true;
+      savePhaseState(root, state);
+      ctx.ui.notify(`TDD enabled — ${state.current.toUpperCase()} phase`, "info");
+    },
+  });
+
+  pi.registerCommand("tdd:off", {
+    description: "Disable TDD enforcement",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const root = ctx.cwd;
+
+      let state;
+      try {
+        state = loadPhaseState(root);
+      } catch {
+        ctx.ui.notify("Invalid .pi/tdd/phase.json. Fix or delete it, then run /tdd:off again.", "error");
+        return;
+      }
+
+      if (!state.enabled) {
+        ctx.ui.notify("TDD already disabled", "info");
+        return;
+      }
+
+      state.enabled = false;
+      savePhaseState(root, state);
+      ctx.ui.notify("TDD disabled", "info");
+    },
+  });
+
+  pi.registerCommand("tdd:status", {
+    description: "Show TDD enforcement status",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const root = ctx.cwd;
+      const result = loadTddState(root);
+
+      if (!result.ok) {
+        ctx.ui.notify(`TDD: ${result.reason}`, "error");
+        return;
+      }
+
+      const { state, config } = result;
+      const phaseStr = state.current.toUpperCase();
+      const redGlobs = config.allowedRedPhaseFiles.join(", ") || "(none)";
+      const greenGlobs = config.allowedGreenPhaseFiles.join(", ") || "(none)";
+      const commands = config.testCommands.join(", ") || "(none)";
+
+      ctx.ui.notify(
+        `TDD enforcer enabled\n` +
+        `Current phase: ${phaseStr}\n` +
+        `Test files: ${redGlobs}\n` +
+        `Impl files: ${greenGlobs}\n` +
+        `Test commands: ${commands}`,
+        "info"
+      );
+    },
+  });
+
+  registerTools(pi);
+  registerHooks(pi);
+}

package/adapters/pi/prompts.ts

@@ -0,0 +1,64 @@
+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 {
+  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)
+      );
+    case "green":
+      return (
+        "You are now in **GREEN** phase. Files matching `allowedRedPhaseFiles` are locked. " +
+        "Implement features in `allowedGreenPhaseFiles` to make tests pass. " +
+        "Call `next_tdd_phase` to proceed to REFACTOR."
+      );
+    case "refactor":
+      return (
+        "You are now in **REFACTOR** phase. Both test and implementation files are free to modify. " +
+        "Refactor without changing behavior. Call `next_tdd_phase` to start a new RED cycle."
+      );
+    default:
+      return "";
+  }
+}
+
+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."
+  );
+}