tdd-enforcer 0.3.1 → 0.3.3

package/adapters/pi/helpers.ts

@@ -38,9 +38,6 @@ function recoverState(
 				if (label === "init") {
 					return { enabled: false, current: "red" };
 				}
-				if (label !== "red" && label !== "green" && label !== "refactor") {
-					return { enabled: false, current: "red" };
-				}
 				const next = deps.nextPhase(label);
 				return { enabled: true, current: next ?? "red" };
 			}

package/adapters/pi/tools.test.ts

@@ -382,15 +382,20 @@ describe("executeTddStatus", () => {
 		).rejects.toThrow("Missing .pi/tdd/");
 	});
 
-	it("throws when TDD disabled", async () => {
+	it("returns status details when TDD disabled", async () => {
 		mockLoadTddState.mockReturnValue({
 			ok: true,
 			state: { enabled: false, current: "red" },
 			config: CONFIG,
 		});
-		await expect(
-			executeTddStatus({ cwd: "/test" } as any, makeDeps()),
-		).rejects.toThrow("not enabled");
+		const result = await executeTddStatus({ cwd: "/test" } as any, makeDeps());
+		expect(result.content[0].text).toContain("disabled");
+		expect(result.content[0].text).toContain("RED");
+		expect(result.content[0].text).toContain("tests/**/*.test.ts");
+		expect(result.content[0].text).toContain("src/**/*.ts");
+		expect(result.details).toBeDefined();
+		expect(result.details?.enabled).toBe(false);
+		expect(result.details?.phase).toBe("red");
 	});
 
 	it("returns status details when TDD enabled", async () => {

package/adapters/pi/tools.ts

@@ -292,18 +292,15 @@ export async function executeTddStatus(
 		});
 		throw new Error(`TDD: ${result.reason}`);
 	}
-	if (!result.state.enabled) {
-		deps.tddLog(tddDir, "WARN", "tdd_status: TDD disabled");
-		throw new Error("TDD is not enabled. Run /tdd:on to enable it.");
-	}
-
 	const { state, config } = result;
+	const enabledStr = state.enabled ? "enabled" : "disabled";
 	const phaseStr = state.current.toUpperCase();
 	const redBlk = config.blockedInRed.join(", ") || "(none)";
 	const greenBlk = config.blockedInGreen.join(", ") || "(none)";
 	const commands = config.testCommands.join(", ") || "(none)";
 
 	deps.tddLog(tddDir, "INFO", "tdd_status: queried", {
+		enabled: state.enabled,
 		phase: state.current,
 	});
 
@@ -312,7 +309,7 @@ export async function executeTddStatus(
 			{
 				type: "text",
 				text:
-					`\nTDD enforcer enabled\n` +
+					`\nTDD enforcer ${enabledStr}\n` +
 					`Current phase: ${phaseStr}\n` +
 					`Blocked in RED: ${redBlk}\n` +
 					`Blocked in GREEN: ${greenBlk}\n` +
@@ -320,7 +317,7 @@ export async function executeTddStatus(
 			},
 		],
 		details: {
-			enabled: true,
+			enabled: state.enabled,
 			phase: state.current,
 			blockedInRed: config.blockedInRed,
 			blockedInGreen: config.blockedInGreen,

package/engine/config.test.ts

@@ -61,6 +61,24 @@ describe("loadConfig", () => {
 		});
 	});
 
+	it("defaults timeoutSeconds to 120 when omitted", () => {
+		withTempDir((dir) => {
+			const tddDir = join(dir, ".pi", "tdd");
+			mkdirSync(tddDir, { recursive: true });
+			writeFileSync(
+				join(tddDir, "rules.json"),
+				JSON.stringify({
+					blockedInRed: ["tests/**/*.test.ts"],
+					blockedInGreen: ["src/**/*.ts"],
+					testCommands: ["npm test"],
+				}),
+				"utf-8",
+			);
+			const config = loadConfig(dir);
+			expect(config.timeoutSeconds).toBe(120);
+		});
+	});
+
 	describe("validation — throws on invalid content", () => {
 		it("throws when blockedInRed is not an array", () => {
 			withTempDir((dir) => {
@@ -172,5 +190,56 @@ describe("loadConfig", () => {
 				expect(() => loadConfig(dir)).toThrow();
 			});
 		});
+
+		it("throws when blockedInRed contains non-strings", () => {
+			withTempDir((dir) => {
+				const tddDir = join(dir, ".pi", "tdd");
+				mkdirSync(tddDir, { recursive: true });
+				writeFileSync(
+					join(tddDir, "rules.json"),
+					JSON.stringify({
+						blockedInRed: [123],
+						blockedInGreen: ["src/**/*.ts"],
+						testCommands: ["npm test"],
+					}),
+					"utf-8",
+				);
+				expect(() => loadConfig(dir)).toThrow();
+			});
+		});
+
+		it("throws when blockedInGreen contains non-strings", () => {
+			withTempDir((dir) => {
+				const tddDir = join(dir, ".pi", "tdd");
+				mkdirSync(tddDir, { recursive: true });
+				writeFileSync(
+					join(tddDir, "rules.json"),
+					JSON.stringify({
+						blockedInRed: ["tests/**/*.test.ts"],
+						blockedInGreen: [null],
+						testCommands: ["npm test"],
+					}),
+					"utf-8",
+				);
+				expect(() => loadConfig(dir)).toThrow();
+			});
+		});
+
+		it("throws when testCommands contains non-strings", () => {
+			withTempDir((dir) => {
+				const tddDir = join(dir, ".pi", "tdd");
+				mkdirSync(tddDir, { recursive: true });
+				writeFileSync(
+					join(tddDir, "rules.json"),
+					JSON.stringify({
+						blockedInRed: ["tests/**/*.test.ts"],
+						blockedInGreen: ["src/**/*.ts"],
+						testCommands: ["npm test", 456],
+					}),
+					"utf-8",
+				);
+				expect(() => loadConfig(dir)).toThrow();
+			});
+		});
 	});
 });

package/engine/config.ts

@@ -16,15 +16,24 @@ export function loadConfig(projectRoot: string): Config {
 	if (!Array.isArray(parsed.blockedInRed) || parsed.blockedInRed.length === 0) {
 		throw new Error("rules.json: blockedInRed must be a non-empty array");
 	}
+	if (!parsed.blockedInRed.every((p: unknown) => typeof p === "string")) {
+		throw new Error("rules.json: blockedInRed must contain only strings");
+	}
 	if (
 		!Array.isArray(parsed.blockedInGreen) ||
 		parsed.blockedInGreen.length === 0
 	) {
 		throw new Error("rules.json: blockedInGreen must be a non-empty array");
 	}
+	if (!parsed.blockedInGreen.every((p: unknown) => typeof p === "string")) {
+		throw new Error("rules.json: blockedInGreen must contain only strings");
+	}
 	if (!Array.isArray(parsed.testCommands) || parsed.testCommands.length === 0) {
 		throw new Error("rules.json: testCommands must be a non-empty array");
 	}
+	if (!parsed.testCommands.every((p: unknown) => typeof p === "string")) {
+		throw new Error("rules.json: testCommands must contain only strings");
+	}
 
 	return {
 		blockedInRed: parsed.blockedInRed,

package/package.json

@@ -1,9 +1,8 @@
 {
 	"name": "tdd-enforcer",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"type": "module",
 	"scripts": {
-		"fmt": "biome format --write .",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"test": "vitest run"

package/skills/tdd-enforcer/SKILL.md

@@ -42,8 +42,10 @@ It locks files per phase — only test files in RED, only implementation files i
 - `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
+- `testCommands` — determines if a phase transition passes. Exit 0 passes, non-zero blocks. **Runs in parallel** — all entries are started concurrently. Use `&&` inside a single string entry to chain multiple commands in one step (e.g. `"npm run build && npm test"`). Do not rely on array ordering for dependency chains; put dependent commands in the same string entry with `&&`.
+
+  **Prefer auto-fix commands** that apply fixes (formatting, linting, etc.) before reporting remaining violations. Without auto-fix, formatting or lint issues in phase-locked files (e.g. test files in GREEN) will block the gate with no way to fix them — forcing `previous_tdd_phase` and losing all progress. Auto-fix commands avoid this deadlock by fixing locked files before the check runs.
+- `timeoutSeconds` — test timeout per command (default: 120)
 
 2. **User** runs `/tdd:on` to enable enforcement.
 

package/DESIGN.md

@@ -1,183 +0,0 @@
-# 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 by parsing the phase label from the last git snapshot commit. Restores working tree to exact prior state. No gate checks — just revert. Must have clear warning in the tool schema that this will revert all changes in the current state.
-
----
-
-## 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
-├── state.json           # {current: "red", enabled: true}
-├── 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 last snapshot commit in the private git repo
-
-### 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/state.json`:
-
-```json
-{
-  "current": "green",
-  "enabled": true
-}
-```
-
-The snapshot history lives in the private git repo's commit log — no explicit stack array needed. `previous_tdd_phase` reads the phase label from the HEAD commit message and restores to the parent. Survives session restarts and extension reloads.
-
----
-
-## 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/behaviour.md

@@ -1,175 +0,0 @@
-# TDD Enforcer — Behaviour Spec
-
-## Entry Gate — `loadTddState(root)` (all surfaces)
-
-Every surface (commands, hooks, tools) hits this first:
-
-```
-loadTddState(root):
-   │
-   ├── .pi/tdd/ exists?       NO → "Missing .pi/tdd/. See the tdd-enforcer skill."
-   │
-   ├── rules.json exists?     NO → "Missing .pi/tdd/rules.json. See the tdd-enforcer skill."
-   │
-   ├── rules.json valid?      NO → "Invalid .pi/tdd/rules.json. See the tdd-enforcer skill."
-   │
-   ├── .pi/tdd/.git/ exists?  NO → initGit(root)
-   │                              FAIL → "Failed to initialise private git repo."
-   │
-   ├── state.json exists?     NO → recoverState()
-   │   │
-   │   └── recoverState():
-   │       ├── .git exists? + headMessage readable?
-   │       │   ├── "tdd: init"        → { enabled: false, current: "red" }
-   │       │   ├── "tdd: red"         → { enabled: true,  current: "green" }
-   │       │   ├── "tdd: green"       → { enabled: true,  current: "refactor" }
-   │       │   ├── "tdd: refactor"    → { enabled: true,  current: "red" }
-   │       │   └── no match / error   → { enabled: false, current: "red" }
-   │       └── no .git / no commits   → { enabled: false, current: "red" }
-   │
-   ├── state.json valid?       NO → recoverState() (same as above)
-   │
-   └── return { ok: true, state, config }
-```
-
-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` | Setup valid? | If already in RED → no-op. Snapshot working tree, auto-enable if disabled, set `current: "red"`. Notify "Skipped to RED phase". |
-| `tdd:green` | Setup valid? | If already in GREEN → no-op. Snapshot working tree, auto-enable if disabled, set `current: "green"`. Notify "Skipped to GREEN phase". |
-| `tdd:refactor` | Setup valid? | If already in REFACTOR → no-op. Snapshot working tree, auto-enable if disabled, set `current: "refactor"`. Notify "Skipped to REFACTOR phase". |
-
-All errors reference the tdd-enforcer skill.
-
-### Phase Jump Commands — Usage
-
-These let the user skip phases they don't need for small changes:
-
-| Scenario | Command | Why |
-|----------|---------|-----|
-| "This is just an implementation change, no test needed" | `/tdd:green` | Skip RED, go straight to GREEN. Test files stay locked, implementation files unlocked. |
-| "This is just cleanup, not new behaviour" | `/tdd:refactor` | Skip RED + GREEN. All files unlocked. |
-| "Done refactoring, start next cycle" | `/tdd:red` | Same as `next_tdd_phase` from REFACTOR but direct — no gate check needed. |
-
-Unlike `next_tdd_phase`, these commands do NOT run transition gate checks. The user is explicitly choosing to skip a phase — they own the consequences.
-
----
-
-## 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 |