tdd-enforcer 0.3.4 → 0.3.6

package/README.md

@@ -0,0 +1,169 @@
+# tdd-enforcer
+
+**Lock files per TDD phase. Gate transitions on test outcomes.**
+
+[![CI](https://github.com/Cyclone1070/tdd-enforcer/actions/workflows/ci.yml/badge.svg)](https://github.com/Cyclone1070/tdd-enforcer/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/tdd-enforcer.svg)](https://www.npmjs.com/package/tdd-enforcer)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Phase-locked file access** — prevents the agent from modifying test files in GREEN and implementation files in RED. Everything is open in REFACTOR
+- **Guards all file-modifying tools** — `write`, `edit`, and `bash` are all intercepted. All invalid modifications are blocked.
+- **Automatic transition gates** — advancing to the next phase requires tests to fail (RED→GREEN) or pass (GREEN→REFACTOR, REFACTOR→RED). Misconfigured or broken transitions are rejected
+- **Safe rollback** — if the previous phase's work was wrong, reverting discards all current changes and restores the exact working tree from before that phase
+- **Stays out of your way** — TDD enforcement is opt-in (`/tdd:on`). Disable anytime with `/tdd:off` to unlock all files
+- **Version-controlled config** — `.pi/tdd/rules.json` lives in your repo alongside the code, so the whole team shares the same rules
+
+---
+
+## Setup
+
+### 1. Install
+
+```bash
+pi install npm:tdd-enforcer
+```
+
+### 2. Ask the agent to set up TDD
+
+Tell the agent to configure TDD for your project, using the `tdd-enforcer` skill to create `.pi/tdd/rules.json` with the right file globs and test commands for your stack.
+
+### 3. Enable TDD
+
+Once configured, run:
+
+```
+/tdd:on
+```
+
+### Config reference
+
+`.pi/tdd/rules.json` fields (created by the agent, not manually):
+
+| Field | Description |
+|-------|-------------|
+| `blockedInRed` | Globs the agent **cannot** touch in RED phase (implementation files) |
+| `blockedInGreen` | Globs the agent **cannot** touch in GREEN phase (test files) |
+| `!` prefix | Exclusion: carves out subsets from a block (e.g. co-located test files) |
+| `testCommands` | Commands run in parallel for gate checks. Exit 0 = pass, non-zero = block. Use `&&` inside a single entry to chain dependent steps |
+| `timeoutSeconds` | Test timeout per command (default: 120) |
+
+---
+
+## Usage
+
+### User commands
+
+| Command | Description |
+|---------|-------------|
+| `/tdd:on` | Enable TDD enforcement |
+| `/tdd:off` | Disable TDD enforcement, all files become free |
+| `/tdd:status` | Show phase, blocked globs, test commands |
+| `/tdd:reset` | **Destructive**: nukes all snapshot history, resets to RED (disabled) |
+| `/tdd:red`, `/tdd:green`, `/tdd:refactor` | Skip to a given phase (auto-enables, no gate checks) |
+
+### Agent tools
+
+| Tool | When to use | Effect |
+|------|-------------|--------|
+| `next_tdd_phase` | Current phase work is complete | Runs allowlist check + gate test, snapshots state, advances phase|
+| `previous_tdd_phase` | Previous phase work was wrong | **Discards all current-phase changes**, restores working tree to previous snapshot |
+| `tdd_status` | Check current enforcement state | Returns phase, blocked globs, test commands |
+
+---
+
+## How it works
+
+Uses a **private git repository** at `.pi/tdd/.git/` (separate from your project's real git history) to detect locked-file changes, revert invalid modifications, and track state across phase transitions.
+
+```
+                 tests fail                  tests pass
+     ┌──────┐    (gate check)    ┌────────┐  (gate check)   ┌──────────┐
+     │ RED  │ ──────────────────▶│ GREEN  │ ───────────────▶│ REFACTOR │
+     │(test)│                    │ (impl) │                 │(cleanup) │
+     └──────┘                    └────────┘                 └──────────┘
+        ▲                                                        │
+        └────────────────────────────────────────────────────────┘
+                                tests pass
+```
+
+Every phase transition runs two validations before advancing:
+
+1. **Allowlist check** — scans working tree changes against the phase's blocked globs. If any locked file has been modified, the transition is rejected with the violating paths listed
+2. **Gate check** — runs `testCommands` in parallel. The required outcome depends on the transition:
+   - RED→GREEN: all commands must fail (a passing test suite means there's no failing test to justify moving to GREEN)
+   - GREEN→REFACTOR: all commands must pass
+   - REFACTOR→RED: all commands must pass
+
+If both checks pass, the working tree is snapshotted and the phase advances.
+
+### File-level enforcement
+
+When TDD is active, every `write`, `edit`, and `bash` tool call is intercepted:
+
+- **`write` / `edit`** — the target file path is checked against the current phase's blocked globs before the tool executes. Locked file writes are blocked with an error message
+- **`bash`** — the working tree is stashed before the command runs. After it finishes, the diff is compared against the stash to find what changed. Any locked-file modifications are automatically reverted, and the command output is amended with a warning listing the violations
+
+This means the agent can attempt any change — enforcement happens transparently at the tool layer.
+
+### Rollback mechanics
+
+Each phase transition creates a labeled commit in a private git repository at `.pi/tdd/.git/`. Calling `previous_tdd_phase`:
+
+1. Confirms HEAD is a TDD snapshot (commit message starts with `tdd: {phase}`)
+2. Hard-resets the working tree to discard uncommitted changes
+3. Soft-resets HEAD~1 to pop the snapshot
+4. Sets the phase back
+
+Since TDD owns its own git repo, rollback doesn't touch the project's real git history at all.
+
+### State recovery
+
+If `state.json` is missing or corrupted, the extension recovers by reading the last TDD commit message from `.pi/tdd/.git/`. The label (`tdd: red`, `tdd: green`, etc.) determines the current phase. If no TDD commits exist, it defaults to disabled in RED.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+### Project structure
+
+```
+tdd-enforcer/
+├── engine/                  # Framework-agnostic core
+│   ├── types.ts             # Phase, Config, Transition types
+│   ├── config.ts            # Load & validate rules.json
+│   ├── state.ts             # Load/save/recover phase state
+│   ├── enforce.ts           # Glob-based file allowlist checks
+│   ├── transition.ts        # Gate checks (test failure/pass per transition)
+│   ├── orchestrate.ts       # advancePhase / revertPhase orchestration
+│   ├── git.ts               # Private git repo for snapshots & diff
+│   ├── log.ts               # Append-only log with line cap
+│   └── prompts.ts           # Phase-specific agent nudges
+├── adapters/
+│   └── pi/                  # pi extension adapter
+│       ├── index.ts         # Extension entry: commands (tdd:on/off/status/reset/jump)
+│       ├── hooks.ts         # Intercept write/edit/bash tool calls & results
+│       └── tools.ts         # Agent tools: next_tdd_phase, previous_tdd_phase, tdd_status
+├── skills/
+│   └── tdd-enforcer/
+│       └── SKILL.md         # Agent instructions for TDD workflows
+└── package.json
+```
+
+- `engine/` — pure logic, zero pi dependencies. Testable in isolation
+- `adapters/pi/` — pi-specific wiring: commands, hooks, agent tools
+- `skills/tdd-enforcer/` — agent instructions consumed at runtime
+
+---
+
+## License
+
+[MIT](LICENSE)

package/adapters/pi/index.test.ts

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
-	handleBeforeAgentStart,
 	handleTddJump,
 	handleTddOff,
 	handleTddOn,
@@ -418,80 +417,4 @@ describe("handleTddJump", () => {
 	});
 });
 
-// ── handleBeforeAgentStart ──────────────────────────────────────────────────
 
-describe("handleBeforeAgentStart", () => {
-	let mockLoadTddState: ReturnType<typeof vi.fn>;
-
-	function makeDeps(overrides = {}) {
-		return {
-			loadTddState: mockLoadTddState,
-			...overrides,
-		};
-	}
-
-	function _makeEvent(): { systemPrompt: string } {
-		return { systemPrompt: "" };
-	}
-
-	beforeEach(() => {
-		vi.clearAllMocks();
-		mockLoadTddState = vi.fn();
-	});
-
-	it("returns instructions when TDD enabled", async () => {
-		mockLoadTddState.mockReturnValue({
-			ok: true,
-			state: { enabled: true, current: "red" },
-			config: {
-				blockedInRed: [],
-				blockedInGreen: [],
-				testCommands: [],
-				timeoutSeconds: 30,
-			},
-		});
-		const result = await handleBeforeAgentStart(
-			{ systemPrompt: "" } as any,
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result).toBeDefined();
-		expect(result?.systemPrompt).toContain("TDD enforcement");
-		expect(result?.systemPrompt).toContain("locked files will be blocked");
-		expect(result?.systemPrompt).toContain("cycle so reverting is cheap");
-		expect(result?.systemPrompt).not.toContain("next_tdd_phase");
-	});
-
-	it("returns undefined when TDD not setup", async () => {
-		mockLoadTddState.mockReturnValue({
-			ok: false,
-			reason: "Missing .pi/tdd/",
-		});
-		const result = await handleBeforeAgentStart(
-			{ systemPrompt: "" } as any,
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result).toBeUndefined();
-	});
-
-	it("returns disabled message when TDD was disabled", async () => {
-		mockLoadTddState.mockReturnValue({
-			ok: true,
-			state: { enabled: false, current: "red" },
-			config: {
-				blockedInRed: [],
-				blockedInGreen: [],
-				testCommands: [],
-				timeoutSeconds: 30,
-			},
-		});
-		const result = await handleBeforeAgentStart(
-			{ systemPrompt: "" } as any,
-			{ cwd: "/test" } as any,
-			makeDeps(),
-		);
-		expect(result).toBeDefined();
-		expect(result?.systemPrompt).toContain("was disabled");
-	});
-});

package/adapters/pi/index.ts

@@ -152,30 +152,6 @@ export async function handleTddStatus(
 	);
 }
 
-export async function handleBeforeAgentStart(
-	event: { systemPrompt: string },
-	ctx: { cwd: string },
-	deps: {
-		loadTddState: typeof loadTddState;
-	},
-): Promise<{ systemPrompt: string } | undefined> {
-	const tdd = deps.loadTddState(ctx.cwd);
-	if (!tdd.ok) return;
-
-	if (tdd.state.enabled) {
-		return {
-			systemPrompt:
-				event.systemPrompt +
-				"\n\nYou are working under TDD enforcement. Each phase restricts which files you can modify — locked files will be blocked automatically.\n" +
-				"Minimise the scope of each TDD cycle so reverting is cheap.",
-		};
-	}
-	return {
-		systemPrompt:
-			event.systemPrompt +
-			"\n\nTDD enforcement was disabled. File restrictions are no longer enforced.",
-	};
-}
 
 export async function handleTddJump(
 	phase: "red" | "green" | "refactor",
@@ -332,8 +308,4 @@ export default function (pi: ExtensionAPI) {
 
 	registerTools(pi);
 	registerHooks(pi);
-
-	pi.on("before_agent_start", (event, ctx) =>
-		handleBeforeAgentStart(event, ctx, { loadTddState }),
-	);
 }

package/adapters/pi/tools.test.ts

@@ -172,6 +172,25 @@ describe("executeNextPhase", () => {
 		});
 	});
 
+	it("blocks on timeout with timeout message from checkGate", async () => {
+		mockLoadTddState.mockReturnValue({
+			ok: true,
+			state: { enabled: true, current: "red" },
+			config: CONFIG,
+		});
+		mockCheckGate.mockResolvedValue({
+			passed: false,
+			timeout: true,
+			message:
+				"Tests timed out after 30s. The test command may have hung or an operation may be blocking.",
+		});
+		await expect(
+			executeNextPhase({ cwd: "/test" } as any, makeDeps()),
+		).rejects.toThrow("timed out");
+		expect(mockSnapshot).not.toHaveBeenCalled();
+		expect(mockSavePhaseState).not.toHaveBeenCalled();
+	});
+
 	it("advances green→refactor when tests pass", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,

package/adapters/pi/tools.ts

@@ -126,14 +126,29 @@ export async function executeNextPhase(
 						cwd: root,
 						timeout: timeout * 1000,
 					});
-					return { command: cmd, passed: true };
-				} catch {
-					return { command: cmd, passed: false };
+					return { command: cmd, passed: true, timedOut: false } as const;
+				} catch (err) {
+					const timedOut = (err as any)?.killed === true;
+					return {
+						command: cmd,
+						passed: false,
+						timedOut,
+					} as const;
 				}
 			}),
 		);
 
-		const failed = results.filter((r) => !r.passed);
+		const timedOut = results.filter((r) => r.timedOut);
+		const failed = results.filter((r) => !r.passed && !r.timedOut);
+
+		if (timedOut.length > 0) {
+			return {
+				passed: false,
+				timeout: true,
+				message: `Tests timed out after ${timeout}s:\n${timedOut.map((f) => `  - ${f.command}`).join("\n")}`,
+			};
+		}
+
 		if (failed.length > 0) {
 			return {
 				passed: false,

package/engine/transition.test.ts

@@ -25,10 +25,15 @@ describe("nextPhase", () => {
 
 // ── Pure unit tests: checkGate ──────────────────────────────────────────────
 
-function makeRunner(passed: boolean): TestRunner {
+function makeRunner(passed: boolean, timeout?: boolean): TestRunner {
 	return async (_cmds, _timeout) => ({
 		passed,
-		message: passed ? "all ok" : "tests failed",
+		timeout,
+		message: timeout
+			? "npm test: timed out"
+			: passed
+				? "all ok"
+				: "tests failed",
 	});
 }
 
@@ -52,6 +57,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to GREEN/i);
 		});
+
+		it("blocks on timeout — does not treat as test failure", async () => {
+			const r = await checkGate(
+				"red",
+				"green",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/proceed|fail/i);
+		});
 	});
 
 	describe("green → refactor (tests must pass)", () => {
@@ -76,6 +94,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to REFACTOR/i);
 		});
+
+		it("blocks on timeout with timeout message", async () => {
+			const r = await checkGate(
+				"green",
+				"refactor",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/fix them/i);
+		});
 	});
 
 	describe("refactor → red (tests must pass)", () => {
@@ -100,6 +131,19 @@ describe("checkGate", () => {
 			expect(r.passed).toBe(false);
 			expect(r.message).toMatch(/transitioning to RED/i);
 		});
+
+		it("blocks on timeout with timeout message", async () => {
+			const r = await checkGate(
+				"refactor",
+				"red",
+				makeRunner(false, true),
+				testConfig,
+			);
+			expect(r.passed).toBe(false);
+			expect(r.timeout).toBe(true);
+			expect(r.message).toMatch(/timed out/i);
+			expect(r.message).not.toMatch(/fix them/i);
+		});
 	});
 
 	it("passes test commands to the runner", async () => {

package/engine/transition.ts

@@ -13,6 +13,7 @@ export function nextPhase(current: Phase): Phase | null {
 export interface GateResult {
 	passed: boolean;
 	message: string;
+	timeout?: boolean;
 }
 
 export type TestRunner = (
@@ -34,6 +35,15 @@ export async function checkGate(
 ): Promise<GateResult> {
 	const result = await testRunner(config.testCommands, config.timeoutSeconds);
 
+	// Timeout blocks all transitions — don't suggest "fix tests"
+	if (result.timeout) {
+		return {
+			passed: false,
+			timeout: true,
+			message: `Tests timed out after ${config.timeoutSeconds}s. The test command may have hung or an operation may be blocking.`,
+		};
+	}
+
 	switch (`${from}→${to}` as Transition) {
 		case "red→green":
 			if (result.passed) {

package/package.json

@@ -1,31 +1,43 @@
 {
-	"name": "tdd-enforcer",
-	"version": "0.3.4",
-	"type": "module",
-	"scripts": {
-		"lint": "biome check .",
-		"lint:fix": "biome check --write .",
-		"test": "vitest run"
-	},
-	"keywords": [
-		"pi-package"
-	],
-	"dependencies": {
-		"picomatch": "^4.0.4"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.5.0",
-		"@earendil-works/pi-coding-agent": "^0.79.6",
-		"@types/node": "^25.9.3",
-		"typebox": "^1.2.16",
-		"vitest": "^3"
-	},
-	"pi": {
-		"extensions": [
-			"./adapters/pi/index.ts"
-		],
-		"skills": [
-			"./skills"
-		]
-	}
+    "name": "tdd-enforcer",
+    "version": "0.3.6",
+    "type": "module",
+    "description": "TDD enforcer extension for the pi coding agent — enforces Red-Green-Refactor phases with file access restrictions and transition gates",
+    "license": "MIT",
+    "author": "Cyclone1070 <hoangmai1070@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cyclone1070/tdd-enforcer.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Cyclone1070/tdd-enforcer/issues"
+    },
+    "homepage": "https://github.com/Cyclone1070/tdd-enforcer#readme",
+    "scripts": {
+        "check": "biome check --write . && vitest run",
+        "lint": "biome check .",
+        "lint:fix": "biome check --write .",
+        "test": "vitest run"
+    },
+    "keywords": [
+        "pi-package"
+    ],
+    "dependencies": {
+        "picomatch": "^4.0.4"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.5.0",
+        "@earendil-works/pi-coding-agent": "^0.79.6",
+        "@types/node": "^25.9.3",
+        "typebox": "^1.2.16",
+        "vitest": "^3"
+    },
+    "pi": {
+        "extensions": [
+            "./adapters/pi/index.ts"
+        ],
+        "skills": [
+            "./skills"
+        ]
+    }
 }