tdd-enforcer 0.2.2 → 0.2.5

package/engine/git.ts

@@ -4,6 +4,24 @@ import { join } from "node:path";
 
 const TDD_DIR = ".pi/tdd";
 
+export type GitDeps = {
+  execSync: (command: string, options?: ExecSyncOptions) => Buffer;
+  existsSync: (path: string) => boolean;
+  mkdirSync: (path: string, options?: { recursive?: boolean }) => void;
+  writeFileSync: (path: string, data: string, encoding: BufferEncoding) => void;
+  unlinkSync: (path: string) => void;
+  rmSync: (path: string, options?: { recursive?: boolean; force?: boolean }) => void;
+};
+
+const defaultDeps: GitDeps = {
+  execSync: execSync as (command: string, options?: ExecSyncOptions) => Buffer,
+  existsSync,
+  mkdirSync,
+  writeFileSync: writeFileSync as (path: string, data: string, encoding: BufferEncoding) => void,
+  unlinkSync,
+  rmSync,
+};
+
 function gitEnv(projectRoot: string): NodeJS.ProcessEnv {
   const gitDir = join(projectRoot, TDD_DIR, ".git");
   return {
@@ -12,116 +30,129 @@ function gitEnv(projectRoot: string): NodeJS.ProcessEnv {
   };
 }
 
-function gitExec(args: string, projectRoot: string, options?: ExecSyncOptions): string {
+function gitExec(args: string, projectRoot: string, deps: GitDeps, options?: ExecSyncOptions): string {
   const env = { ...process.env, ...gitEnv(projectRoot) };
-  return execSync(`git ${args}`, { ...options, env, encoding: "utf-8" } as ExecSyncOptions).toString();
+  return deps.execSync(`git ${args}`, { ...options, env, encoding: "utf-8" } as ExecSyncOptions).toString();
 }
 
-export function initGit(projectRoot: string): void {
+export function initGit(projectRoot: string, deps: GitDeps = defaultDeps): void {
   const tddPath = join(projectRoot, TDD_DIR);
   const gitDir = join(tddPath, ".git");
-  if (existsSync(gitDir)) return;
+  if (deps.existsSync(gitDir)) return;
 
-  mkdirSync(tddPath, { recursive: true });
-  gitExec(`init "${tddPath}"`, projectRoot, { stdio: "pipe" as const });
-  gitExec(`config core.worktree "${projectRoot}"`, projectRoot, { stdio: "pipe" as const });
-  gitExec(`config core.excludesFile "${join(tddPath, ".gitignore")}"`, projectRoot, { stdio: "pipe" as const });
+  deps.mkdirSync(tddPath, { recursive: true });
+  gitExec(`init "${tddPath}"`, projectRoot, deps, { stdio: "pipe" as const });
+  gitExec(`config core.worktree "${projectRoot}"`, projectRoot, deps, { stdio: "pipe" as const });
+  gitExec(`config core.excludesFile "${join(tddPath, ".gitignore")}"`, projectRoot, deps, { stdio: "pipe" as const });
 
   const gitignorePath = join(tddPath, ".gitignore");
-  if (!existsSync(gitignorePath)) {
-    writeFileSync(
+  if (!deps.existsSync(gitignorePath)) {
+    deps.writeFileSync(
       gitignorePath,
       ["node_modules/", ".pnpm-store/", ".next/", "dist/", "build/", ".cache/", "*.log", ".DS_Store", "Thumbs.db", ""].join("\n"),
       "utf-8",
     );
   }
 
-  gitExec("add -A", projectRoot, { stdio: "pipe" as const });
-  gitExec('commit --allow-empty -m "tdd: init"', projectRoot, { stdio: "pipe" as const });
+  gitExec("add -A", projectRoot, deps, { stdio: "pipe" as const });
+  stageFiles(projectRoot, [".pi/tdd/state.json", ".pi/tdd/rules.json", ".pi/tdd/.gitignore"], deps);
+  gitExec('commit --allow-empty -m "tdd: init"', projectRoot, deps, { stdio: "pipe" as const });
 }
 
 /** Destroy the private git repo and re-init from scratch. */
-export function resetGit(projectRoot: string): void {
+export function resetGit(projectRoot: string, deps: GitDeps = defaultDeps): void {
   const tddPath = join(projectRoot, TDD_DIR);
   const gitDir = join(tddPath, ".git");
-  if (existsSync(gitDir)) {
-    rmSync(gitDir, { recursive: true, force: true });
+  if (deps.existsSync(gitDir)) {
+    deps.rmSync(gitDir, { recursive: true, force: true });
   }
-  initGit(projectRoot);
+  initGit(projectRoot, deps);
 }
 
 /** Stage all + commit with --allow-empty so every phase transition has a labeled commit. */
-export function snapshot(projectRoot: string, phase: string): string {
-  gitExec("add -A", projectRoot, { stdio: "pipe" as const });
-  gitExec(`commit --allow-empty -m "tdd: ${phase}"`, projectRoot, { stdio: "pipe" as const });
-  return gitExec("rev-parse HEAD", projectRoot).trim();
+export function snapshot(projectRoot: string, phase: string, deps: GitDeps = defaultDeps): string {
+  gitExec("add -A", projectRoot, deps, { stdio: "pipe" as const });
+  stageFiles(projectRoot, [".pi/tdd/state.json", ".pi/tdd/rules.json", ".pi/tdd/.gitignore"], deps);
+  gitExec(`commit --allow-empty -m "tdd: ${phase}"`, projectRoot, deps, { stdio: "pipe" as const });
+  return gitExec("rev-parse HEAD", projectRoot, deps).trim();
 }
 
-export function modifiedFiles(projectRoot: string): string[] {
-  const out = gitExec("diff --name-only HEAD", projectRoot).trim();
+export function modifiedFiles(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec("diff --name-only HEAD", projectRoot, deps).trim();
   return out ? out.split("\n") : [];
 }
 
-export function untrackedFiles(projectRoot: string): string[] {
-  const out = gitExec("ls-files --others --exclude-standard", projectRoot).trim();
+export function untrackedFiles(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec("ls-files --others --exclude-standard", projectRoot, deps).trim();
   return out ? out.split("\n") : [];
 }
 
-export function changesSinceSnapshot(projectRoot: string): string[] {
-  return [...new Set([...modifiedFiles(projectRoot), ...untrackedFiles(projectRoot)])];
+export function changesSinceSnapshot(projectRoot: string, deps: GitDeps = defaultDeps): string[] {
+  return [...new Set([...modifiedFiles(projectRoot, deps), ...untrackedFiles(projectRoot, deps)])];
 }
 
-export function restoreFilesTo(projectRoot: string, files: string[], source?: string): void {
+export function restoreFilesTo(projectRoot: string, files: string[], source?: string, deps: GitDeps = defaultDeps): void {
   if (files.length === 0) return;
 
   // Separate tracked (git restore) from untracked (delete)
-  const tracked = gitExec("ls-files", projectRoot)
+  const tracked = gitExec("ls-files", projectRoot, deps)
     .trim()
     .split("\n")
     .filter(Boolean);
   const trackedSet = new Set(tracked);
 
   const trackedFiles = files.filter((f) => trackedSet.has(f));
-  const untrackedFiles = files.filter((f) => !trackedSet.has(f));
+  const untrackedFilesList = files.filter((f) => !trackedSet.has(f));
 
   if (trackedFiles.length > 0) {
     const escaped = trackedFiles.map((f) => `"${f}"`).join(" ");
     const sourceFlag = source ? `--source=${source} ` : "";
-    gitExec(`restore ${sourceFlag}--worktree -- ${escaped}`, projectRoot, { stdio: "pipe" as const });
+    gitExec(`restore ${sourceFlag}--worktree -- ${escaped}`, projectRoot, deps, { stdio: "pipe" as const });
   }
 
-  for (const f of untrackedFiles) {
+  for (const f of untrackedFilesList) {
     try {
-      unlinkSync(f);
+      deps.unlinkSync(f);
     } catch {
       // File may already be gone, ignore
     }
   }
 }
 
+/**
+ * Force-stage files in the private git repo, bypassing worktree .gitignore.
+ * Does not commit — call snapshot() or commit separately to persist.
+ */
+export function stageFiles(projectRoot: string, files: string[], deps: GitDeps = defaultDeps): void {
+  const existing = files.filter((f) => deps.existsSync(join(projectRoot, f)));
+  if (existing.length === 0) return;
+  const escaped = existing.map((f) => `"${f}"`).join(" ");
+  gitExec(`add -f ${escaped}`, projectRoot, deps, { stdio: "pipe" as const });
+}
+
 /**
  * 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");
+export function gitStashCreate(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  const hash = gitExec("stash create --include-untracked", projectRoot, deps).trim();
+  if (!hash) return "HEAD";
   return hash;
 }
 
-export function headHash(projectRoot: string): string {
-  return gitExec("rev-parse HEAD", projectRoot).trim();
+export function headHash(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  return gitExec("rev-parse HEAD", projectRoot, deps).trim();
 }
 
 /** Get the commit message of HEAD. */
-export function headMessage(projectRoot: string): string {
-  return gitExec("log -1 --format=%s HEAD", projectRoot).trim();
+export function headMessage(projectRoot: string, deps: GitDeps = defaultDeps): string {
+  return gitExec("log -1 --format=%s HEAD", projectRoot, deps).trim();
 }
 
 /** Check if HEAD has a parent commit (i.e. can go back one). */
-export function hasParent(projectRoot: string): boolean {
+export function hasParent(projectRoot: string, deps: GitDeps = defaultDeps): boolean {
   try {
-    gitExec("rev-parse HEAD~1", projectRoot);
+    gitExec("rev-parse HEAD~1", projectRoot, deps);
     return true;
   } catch {
     return false;
@@ -131,21 +162,21 @@ 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();
+export function changesSince(projectRoot: string, commitHash: string, deps: GitDeps = defaultDeps): string[] {
+  const out = gitExec(`diff --name-only ${commitHash} -- .`, projectRoot, deps).trim();
   const files = out ? out.split("\n") : [];
   // Also include untracked files
-  const untracked = untrackedFiles(projectRoot);
+  const untracked = untrackedFiles(projectRoot, deps);
   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 });
-  gitExec("clean -fd", projectRoot, { stdio: "pipe" as const });
+export function resetHard(projectRoot: string, deps: GitDeps = defaultDeps): void {
+  gitExec("reset --hard", projectRoot, deps, { stdio: "pipe" as const });
+  gitExec("clean -fd", projectRoot, deps, { stdio: "pipe" as const });
 }
 
 /** Soft reset — remove last commit, keep working tree content as unstaged. */
-export function undoLastCommit(projectRoot: string): void {
-  gitExec("reset --soft HEAD~1", projectRoot, { stdio: "pipe" as const });
+export function undoLastCommit(projectRoot: string, deps: GitDeps = defaultDeps): void {
+  gitExec("reset --soft HEAD~1", projectRoot, deps, { stdio: "pipe" as const });
 }

package/engine/index.ts

@@ -1,5 +1,5 @@
 export { isAllowed, disallowedFiles } from "./enforce.js";
-export { initGit, resetGit, snapshot, changesSinceSnapshot, changesSince, modifiedFiles, untrackedFiles, restoreFilesTo, gitStashCreate, headHash, headMessage, hasParent, resetHard, undoLastCommit } from "./git.js";
+export { initGit, resetGit, snapshot, changesSinceSnapshot, changesSince, modifiedFiles, untrackedFiles, restoreFilesTo, gitStashCreate, stageFiles, 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/transition.test.ts

@@ -1,10 +1,7 @@
-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 { nextPhase, checkGate, getDisallowedChanges } from "./transition.js";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { getDisallowedChanges, nextPhase, checkGate } from "./transition.js";
 import type { Config, TestRunner } from "./types.js";
-import { initGit, snapshot } from "./git.js";
+import picomatch from "picomatch";
 
 // ── Pure unit tests: nextPhase ──────────────────────────────────────────────
 
@@ -36,8 +33,8 @@ function makeRunner(passed: boolean): TestRunner {
 }
 
 const testConfig: Config = {
-  allowedRedPhaseFiles: [],
-  allowedGreenPhaseFiles: [],
+  blockedInRed: [],
+  blockedInGreen: [],
   testCommands: ["npm test"],
   timeoutSeconds: 30,
 };
@@ -124,81 +121,86 @@ describe("checkGate", () => {
   });
 });
 
-// ── Integration tests: getDisallowedChanges ──────────────────────────────────
-
-function withTempDir(fn: (dir: string) => void) {
-  const dir = join(tmpdir(), `tdd-transition-test-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  try {
-    fn(dir);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
+// ── Pure unit tests: getDisallowedChanges ────────────────────────────────────
 
 const denyConfig: Config = {
-  allowedRedPhaseFiles: ["tests/**/*.test.ts"],
-  allowedGreenPhaseFiles: ["src/**/*.ts"],
+  blockedInRed: ["src/**/*.ts"],
+  blockedInGreen: ["tests/**/*.test.ts"],
   testCommands: [],
   timeoutSeconds: 30,
 };
 
 describe("getDisallowedChanges", () => {
+  let mockChangesSinceSnapshot: ReturnType<typeof vi.fn>;
+  let mockDisallowedFiles: ReturnType<typeof vi.fn>;
+
+  function makeDeps(overrides = {}) {
+    return {
+      changesSinceSnapshot: mockChangesSinceSnapshot,
+      disallowedFiles: mockDisallowedFiles,
+      ...overrides,
+    };
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockChangesSinceSnapshot = vi.fn().mockReturnValue([]);
+    mockDisallowedFiles = vi.fn().mockReturnValue([]);
+  });
+
   it("returns empty for refactor phase regardless of git state", () => {
-    withTempDir((dir) => {
-      // No git at all — safe because refactor returns early
-      expect(getDisallowedChanges(dir, "refactor", denyConfig)).toEqual([]);
-    });
+    const result = getDisallowedChanges("/any", "refactor", denyConfig, makeDeps());
+    expect(result).toEqual([]);
+    expect(mockChangesSinceSnapshot).not.toHaveBeenCalled();
   });
 
   it("returns empty when no files changed", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      expect(getDisallowedChanges(dir, "red", denyConfig)).toEqual([]);
-    });
+    mockChangesSinceSnapshot.mockReturnValue([]);
+    const result = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(result).toEqual([]);
+    expect(mockChangesSinceSnapshot).toHaveBeenCalledWith("/test");
   });
 
   it("returns disallowed files in red phase", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      mkdirSync(join(dir, "src"), { recursive: true });
-      mkdirSync(join(dir, "tests"), { recursive: true });
-      writeFileSync(join(dir, "src", "main.ts"), "// impl", "utf-8");
-      writeFileSync(join(dir, "tests", "foo.test.ts"), "// test", "utf-8");
-      writeFileSync(join(dir, "README.md"), "// docs", "utf-8");
-      const violations = getDisallowedChanges(dir, "red", denyConfig);
-      expect(violations).toContain("src/main.ts");
-      expect(violations).not.toContain("tests/foo.test.ts");
-      expect(violations).not.toContain("README.md");
+    mockChangesSinceSnapshot.mockReturnValue(["src/main.ts", "tests/foo.test.ts", "README.md"]);
+    const matchBlockedInRed = picomatch(denyConfig.blockedInRed);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "red") {
+        return changed.filter((f: string) => matchBlockedInRed(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(violations).toContain("src/main.ts");
+    expect(violations).not.toContain("tests/foo.test.ts");
+    expect(violations).not.toContain("README.md");
   });
 
   it("returns disallowed files in green phase", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "green");
-      mkdirSync(join(dir, "tests"), { recursive: true });
-      mkdirSync(join(dir, "src"), { recursive: true });
-      writeFileSync(join(dir, "tests", "foo.test.ts"), "// test", "utf-8");
-      writeFileSync(join(dir, "src", "main.ts"), "// impl", "utf-8");
-      writeFileSync(join(dir, "package.json"), "{}", "utf-8");
-      const violations = getDisallowedChanges(dir, "green", denyConfig);
-      expect(violations).toContain("tests/foo.test.ts");
-      expect(violations).not.toContain("src/main.ts");
-      expect(violations).not.toContain("package.json");
+    mockChangesSinceSnapshot.mockReturnValue(["tests/foo.test.ts", "src/main.ts", "package.json"]);
+    const matchBlockedInGreen = picomatch(denyConfig.blockedInGreen);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "green") {
+        return changed.filter((f: string) => matchBlockedInGreen(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "green", denyConfig, makeDeps());
+    expect(violations).toContain("tests/foo.test.ts");
+    expect(violations).not.toContain("src/main.ts");
+    expect(violations).not.toContain("package.json");
   });
 
   it("catches untracked files, not just modified", () => {
-    withTempDir((dir) => {
-      initGit(dir);
-      snapshot(dir, "red");
-      mkdirSync(join(dir, "src"), { recursive: true });
-      writeFileSync(join(dir, "src", "new.ts"), "// brand new", "utf-8");
-      const violations = getDisallowedChanges(dir, "red", denyConfig);
-      expect(violations).toContain("src/new.ts");
+    mockChangesSinceSnapshot.mockReturnValue(["src/new.ts"]);
+    const matchBlockedInRed = picomatch(denyConfig.blockedInRed);
+    mockDisallowedFiles.mockImplementation((changed: string[], phase: string) => {
+      if (phase === "red") {
+        return changed.filter((f: string) => matchBlockedInRed(f));
+      }
+      return [];
     });
+    const violations = getDisallowedChanges("/test", "red", denyConfig, makeDeps());
+    expect(violations).toContain("src/new.ts");
   });
 });

package/engine/transition.ts

@@ -70,9 +70,16 @@ export function getDisallowedChanges(
   projectRoot: string,
   phase: Phase,
   config: Config,
+  deps: {
+    changesSinceSnapshot: typeof changesSinceSnapshot;
+    disallowedFiles: typeof disallowedFiles;
+  } = {
+    changesSinceSnapshot,
+    disallowedFiles,
+  },
 ): string[] {
   if (phase === "refactor") return [];
 
-  const changed = changesSinceSnapshot(projectRoot);
-  return disallowedFiles(changed, phase, config);
+  const changed = deps.changesSinceSnapshot(projectRoot);
+  return deps.disallowedFiles(changed, phase, config);
 }

package/engine/types.ts

@@ -6,8 +6,8 @@ export interface PhaseState {
 }
 
 export interface Config {
-  allowedRedPhaseFiles: string[];
-  allowedGreenPhaseFiles: string[];
+  blockedInRed: string[];
+  blockedInGreen: string[];
   testCommands: string[];
   timeoutSeconds: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdd-enforcer",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -9,6 +9,9 @@
     "picomatch": "^4.0.4"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.79.6",
+    "@types/node": "^25.9.3",
+    "typebox": "^1.2.16",
     "vitest": "^3"
   },
   "pi": {

package/skills/tdd-enforcer/SKILL.md

@@ -32,15 +32,16 @@ It locks files per phase — only test files in RED, only implementation files i
 
 ```json
 {
-  "allowedRedPhaseFiles": ["tests/**/*.test.ts"],
-  "allowedGreenPhaseFiles": ["src/**/*.ts"],
-  "testCommands": ["npm test"],
+  "blockedInRed":   ["src/**/*.ts", "lib/**/*.ts", "!src/**/*.test.ts"],
+  "blockedInGreen": ["**/*.test.ts", "**/*.spec.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)
+- `blockedInRed` — globs the agent **cannot** modify in RED phase (implementation files)
+- `blockedInGreen` — globs the agent **cannot** modify in GREEN phase (test files)
+- `!` exclusion prefix — optional, carves out subsets from a block list at init time. E.g. `!src/**/*.test.ts` excludes co-located test files from `blockedInRed` so the agent can write them in RED phase
 - `testCommands` — shell commands to run tests
 - `timeoutSeconds` — test timeout per command
 
@@ -51,31 +52,31 @@ It locks files per phase — only test files in RED, only implementation files i
 ## 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.
+Files matching `blockedInRed` are locked — everything else is free.
 
-### 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.
+Write failing tests for one feature at a time. Think about what could go wrong and test for it — don't just verify the happy path, cover unhappy paths and edge cases too. Keep cycles small so reverting is cheap and safe if assumptions turn out wrong.
 
-### REFACTOR
-All files are free to modify. Refactor without changing behaviour. Call `next_tdd_phase` once tests pass to start a new RED cycle.
+Call `next_tdd_phase` once tests fail.
 
----
+### GREEN
+Files matching `blockedInGreen` are locked — everything else is free.
 
-## Hard Rules
+Write the simplest code that makes the failing tests pass — nothing more. The tests are your spec; if they pass, you're done.
 
-- **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.
+If the RED phase tests were wrong, call `previous_tdd_phase` to go back and fix them before implementing. All current changes are lost, but that's better since the current changes was building on false assumptions. Don't be afraid to discard — clean slate beats patched code.
 
-  - 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).
+Call `next_tdd_phase` once all tests pass.
 
-- **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.
+### REFACTOR
+All files are free to modify. Refactor without changing behaviour.
+Call `next_tdd_phase` once tests pass to start a new RED cycle.
 
-- **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.
+## Hard Rules
 
-- **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.
+- **Never write to `.pi/tdd/`.** The extension owns that directory — writes are blocked and bash changes are reverted.
+- **Never run `/tdd:` commands yourself.** They're registered as user-only commands and won't work when you type them.
 
 ---
 
@@ -93,7 +94,7 @@ Also validates no locked files were modified. On success, records the current st
 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.
+Shows the current phase, blocked file globs per phase, and test commands.
 
 ---
 

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}