@windyroad/tdd 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,71 @@
+# @windyroad/tdd
+
+**TDD state machine enforcement for Claude Code.** Forces the Red-Green-Refactor cycle so your AI agent writes tests before implementation -- every time.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+AI agents love to jump straight to implementation. This plugin stops that. It enforces a strict TDD state machine:
+
+```
+IDLE ──> RED ──> GREEN ──> RED (next test)
+                   │
+                   └──> Refactor (staying GREEN)
+```
+
+- **IDLE** -- No test written yet. Implementation file edits are blocked.
+- **RED** -- A failing test exists. Implementation edits are allowed.
+- **GREEN** -- Tests pass. You can refactor or write a new failing test.
+- **BLOCKED** -- Test runner error or timeout. Fix the setup before continuing.
+
+The agent must write a failing test first. There are no shortcuts.
+
+## Install
+
+```bash
+npx @windyroad/tdd
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin activates automatically. On first use in a project without a test framework, it directs you to set one up:
+
+```
+/wr-tdd:setup-tests
+```
+
+This examines your codebase, recommends a test runner, configures `package.json`, and creates an example test.
+
+Once active, the workflow is enforced on every edit:
+
+1. Write a test file (`*.test.ts`, `*.spec.ts`, etc.) that describes the desired behaviour
+2. The test must fail (RED state) -- proving the test is meaningful
+3. Write the minimum implementation to make it pass (GREEN state)
+4. Refactor while keeping tests green
+5. Repeat
+
+Test files and config/doc files are always writable regardless of state.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `tdd-inject.sh` | Every prompt | Injects the current TDD state into the prompt |
+| `tdd-enforce-edit.sh` | Edit or Write | Blocks implementation edits in IDLE or BLOCKED state |
+| `tdd-post-write.sh` | After edit | Runs tests and transitions the state machine |
+| `tdd-setup-marker.sh` | Skill completes | Marks test setup as done |
+| `tdd-reset.sh` | Session end | Resets the TDD state |
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/tdd --update
+npx @windyroad/tdd --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/bin/install.mjs

@@ -4,7 +4,7 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
 
 const PLUGIN = "wr-tdd";
 const DEPS = [];
@@ -20,6 +20,7 @@ TDD state machine enforcement (Red-Green-Refactor cycle)
 Options:
   --update     Update this plugin and its skills
   --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
   --dry-run    Show what would be done without executing
   --help, -h   Show this help
 `);
@@ -38,5 +39,5 @@ if (flags.uninstall) {
 } else if (flags.update) {
   utils.updatePackage(PLUGIN);
 } else {
-  utils.installPackage(PLUGIN, { deps: DEPS });
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

package/hooks/hooks.json

@@ -7,7 +7,8 @@
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-enforce-edit.sh" }] }
     ],
     "PostToolUse": [
-      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-post-write.sh" }] }
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-post-write.sh" }] },
+      { "matcher": "Skill", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-setup-marker.sh" }] }
     ],
     "Stop": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-reset.sh" }] }

package/hooks/lib/tdd-gate.sh

@@ -1,9 +1,10 @@
 #!/bin/bash
 # TDD Gate - shared library for TDD enforcement hooks.
 # Sourced by tdd-inject.sh, tdd-enforce-edit.sh, tdd-post-write.sh, tdd-reset.sh.
-# Provides: tdd_classify_file, tdd_read_state, tdd_write_state, tdd_run_tests,
-#           tdd_add_test_file, tdd_get_test_files, tdd_cleanup, tdd_has_test_script,
-#           tdd_deny_json
+# Provides: tdd_classify_file, tdd_read_state, tdd_write_state, tdd_run_test_file,
+#           tdd_add_test_file, tdd_get_test_files, tdd_find_test_for_impl,
+#           tdd_read_state_for_impl, tdd_get_all_states, tdd_cleanup,
+#           tdd_has_test_script, tdd_deny_json
 
 # --- Configuration ---
 TDD_TEST_CMD="${TDD_TEST_CMD:-npm test --}"
@@ -27,8 +28,8 @@ tdd_classify_file() {
 
   # Exempt files (not gated)
   case "$FILE_PATH" in
-    # Config files
-    *.config.*|*.json|*.yml|*.yaml) echo "exempt"; return ;;
+    # Config and setup files (test infrastructure)
+    *.config.*|*.setup.*|*.json|*.yml|*.yaml) echo "exempt"; return ;;
     # Module configs (*.mjs, *.cjs are config when at root or named as config)
     *.mjs|*.cjs) echo "exempt"; return ;;
     # Styles
@@ -58,17 +59,28 @@ tdd_classify_file() {
   echo "exempt"
 }
 
-# --- State Management ---
-# Marker files use session ID to isolate concurrent sessions
-_tdd_state_file() { echo "/tmp/tdd-state-${1}"; }
+# --- State Management (per-test-file) ---
+# State is stored per test file in a session-scoped directory.
+# Each test file gets its own state: IDLE, RED, GREEN, or BLOCKED.
+
+_tdd_state_dir() { echo "/tmp/tdd-state-${1}"; }
 _tdd_test_files_file() { echo "/tmp/tdd-test-files-${1}"; }
 _tdd_test_stdout_file() { echo "/tmp/tdd-test-stdout-${1}"; }
 
-# Read current state. Returns: IDLE, RED, GREEN, or BLOCKED
+# Encode a file path for use as a filename (replace / with __)
+_tdd_encode_path() {
+  echo "$1" | sed 's|/|__|g'
+}
+
+# Read state for a specific test file. Returns: IDLE, RED, GREEN, or BLOCKED
 tdd_read_state() {
   local SESSION_ID="$1"
-  local STATE_FILE
-  STATE_FILE=$(_tdd_state_file "$SESSION_ID")
+  local TEST_FILE="$2"
+  local STATE_DIR
+  STATE_DIR=$(_tdd_state_dir "$SESSION_ID")
+  local ENCODED
+  ENCODED=$(_tdd_encode_path "$TEST_FILE")
+  local STATE_FILE="${STATE_DIR}/${ENCODED}"
   if [ -f "$STATE_FILE" ]; then
     cat "$STATE_FILE"
   else
@@ -76,13 +88,17 @@ tdd_read_state() {
   fi
 }
 
-# Write state
+# Write state for a specific test file
 tdd_write_state() {
   local SESSION_ID="$1"
-  local NEW_STATE="$2"
-  local STATE_FILE
-  STATE_FILE=$(_tdd_state_file "$SESSION_ID")
-  echo "$NEW_STATE" > "$STATE_FILE"
+  local TEST_FILE="$2"
+  local NEW_STATE="$3"
+  local STATE_DIR
+  STATE_DIR=$(_tdd_state_dir "$SESSION_ID")
+  mkdir -p "$STATE_DIR"
+  local ENCODED
+  ENCODED=$(_tdd_encode_path "$TEST_FILE")
+  echo "$NEW_STATE" > "${STATE_DIR}/${ENCODED}"
 }
 
 # Track test files touched this session
@@ -108,31 +124,133 @@ tdd_get_test_files() {
   fi
 }
 
+# --- Impl-to-Test Association ---
+# Given an implementation file, find its associated test file from tracked tests.
+# Convention: Hero.tsx ↔ Hero.test.tsx or Hero.spec.tsx (same dir or __tests__/)
+# Returns the first matching tracked test file, or empty string if none.
+tdd_find_test_for_impl() {
+  local SESSION_ID="$1"
+  local IMPL_PATH="$2"
+  local DIR BASENAME STEM EXT
+  DIR=$(dirname "$IMPL_PATH")
+  BASENAME=$(basename "$IMPL_PATH")
+
+  # Strip extension to get stem (e.g., "Hero" from "Hero.tsx")
+  # Handle .ts, .tsx, .js, .jsx
+  case "$BASENAME" in
+    *.tsx) STEM="${BASENAME%.tsx}"; EXT="tsx" ;;
+    *.ts)  STEM="${BASENAME%.ts}";  EXT="ts" ;;
+    *.jsx) STEM="${BASENAME%.jsx}"; EXT="jsx" ;;
+    *.js)  STEM="${BASENAME%.js}";  EXT="js" ;;
+    *)     STEM="$BASENAME";       EXT="" ;;
+  esac
+
+  local TEST_FILES
+  TEST_FILES=$(tdd_get_test_files "$SESSION_ID")
+  if [ -z "$TEST_FILES" ]; then
+    echo ""
+    return
+  fi
+
+  # Check tracked test files for a match
+  # Priority: exact match in tracked files (any convention)
+  while IFS= read -r tracked; do
+    local tracked_dir tracked_base
+    tracked_dir=$(dirname "$tracked")
+    tracked_base=$(basename "$tracked")
+
+    # Same directory: Hero.test.tsx, Hero.spec.tsx, etc.
+    if [ "$tracked_dir" = "$DIR" ]; then
+      case "$tracked_base" in
+        "${STEM}.test."*|"${STEM}.spec."*) echo "$tracked"; return ;;
+      esac
+    fi
+
+    # __tests__ subdirectory: src/__tests__/Hero.test.tsx for src/Hero.tsx
+    if [ "$tracked_dir" = "${DIR}/__tests__" ]; then
+      case "$tracked_base" in
+        "${STEM}.test."*|"${STEM}.spec."*) echo "$tracked"; return ;;
+      esac
+    fi
+
+    # Parent __tests__: src/__tests__/Hero.test.tsx for src/components/Hero.tsx
+    # (only if dir contains __tests__)
+    case "$tracked" in
+      */__tests__/*)
+        case "$tracked_base" in
+          "${STEM}.test."*|"${STEM}.spec."*) echo "$tracked"; return ;;
+        esac
+        ;;
+    esac
+  done <<< "$TEST_FILES"
+
+  # No tracked test found
+  echo ""
+}
+
+# Suggest a test file path for an impl file using naming convention.
+# Used for user-facing messages (e.g., "write src/Hero.test.tsx first").
+tdd_suggest_test_path() {
+  local IMPL_PATH="$1"
+  local DIR BASENAME STEM EXT
+  DIR=$(dirname "$IMPL_PATH")
+  BASENAME=$(basename "$IMPL_PATH")
+  case "$BASENAME" in
+    *.tsx) STEM="${BASENAME%.tsx}"; EXT="tsx" ;;
+    *.ts)  STEM="${BASENAME%.ts}";  EXT="ts" ;;
+    *.jsx) STEM="${BASENAME%.jsx}"; EXT="jsx" ;;
+    *.js)  STEM="${BASENAME%.js}";  EXT="js" ;;
+    *)     echo ""; return ;;
+  esac
+  echo "${DIR}/${STEM}.test.${EXT}"
+}
+
+# Read state for an implementation file by looking up its associated test
+tdd_read_state_for_impl() {
+  local SESSION_ID="$1"
+  local IMPL_PATH="$2"
+  local TEST_FILE
+  TEST_FILE=$(tdd_find_test_for_impl "$SESSION_ID" "$IMPL_PATH")
+  if [ -z "$TEST_FILE" ]; then
+    echo "IDLE"
+    return
+  fi
+  tdd_read_state "$SESSION_ID" "$TEST_FILE"
+}
+
+# Get all tracked test files with their states (format: "path:STATE" per line)
+tdd_get_all_states() {
+  local SESSION_ID="$1"
+  local TEST_FILES
+  TEST_FILES=$(tdd_get_test_files "$SESSION_ID")
+  if [ -z "$TEST_FILES" ]; then
+    return
+  fi
+  while IFS= read -r test_file; do
+    local state
+    state=$(tdd_read_state "$SESSION_ID" "$test_file")
+    echo "${test_file}:${state}"
+  done <<< "$TEST_FILES"
+}
+
 # --- Test Runner ---
-# Runs tests for the session's tracked test files.
+# Runs a single test file.
 # Returns: 0=pass, 1=fail, 124=timeout, other=error
 # Saves stdout to marker file for debugging.
-tdd_run_tests() {
+tdd_run_test_file() {
   local SESSION_ID="$1"
+  local TEST_FILE="$2"
   local STDOUT_FILE
   STDOUT_FILE=$(_tdd_test_stdout_file "$SESSION_ID")
-  local TEST_FILES
-  TEST_FILES=$(tdd_get_test_files "$SESSION_ID")
 
-  if [ -z "$TEST_FILES" ]; then
-    echo "No test files tracked" > "$STDOUT_FILE"
-    return 0  # No tests to run = pass (no-op)
+  if [ -z "$TEST_FILE" ]; then
+    echo "No test file specified" > "$STDOUT_FILE"
+    return 0
   fi
 
-  # Build argument list from tracked test files
-  local ARGS=""
-  while IFS= read -r f; do
-    ARGS="$ARGS $f"
-  done <<< "$TEST_FILES"
-
-  # Run with timeout
+  # Run with timeout — only the specified test file
   local EXIT_CODE
-  timeout "$TDD_TEST_TIMEOUT" bash -c "$TDD_TEST_CMD $ARGS" > "$STDOUT_FILE" 2>&1
+  timeout "$TDD_TEST_TIMEOUT" bash -c "$TDD_TEST_CMD $TEST_FILE" > "$STDOUT_FILE" 2>&1
   EXIT_CODE=$?
 
   return $EXIT_CODE
@@ -155,9 +273,12 @@ tdd_has_test_script() {
 # --- Cleanup ---
 tdd_cleanup() {
   local SESSION_ID="$1"
-  rm -f "$(_tdd_state_file "$SESSION_ID")"
+  local STATE_DIR
+  STATE_DIR=$(_tdd_state_dir "$SESSION_ID")
+  rm -rf "$STATE_DIR"
   rm -f "$(_tdd_test_files_file "$SESSION_ID")"
   rm -f "$(_tdd_test_stdout_file "$SESSION_ID")"
+  rm -f "/tmp/tdd-setup-active-${SESSION_ID}"
 }
 
 # --- Deny Helper ---

package/hooks/tdd-enforce-edit.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # TDD - PreToolUse enforcement hook (Edit|Write)
-# Blocks implementation file edits unless state is RED or GREEN.
+# Blocks implementation file edits unless the associated test's state is RED or GREEN.
 # Test files and exempt files are always allowed.
+# Per-file state: a failing Countdown test does NOT block editing Hero.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/tdd-gate.sh"
@@ -15,16 +16,30 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
+# P004: Only gate files inside the project root.
+case "$FILE_PATH" in
+  /*)
+    case "$FILE_PATH" in
+      "$PWD"/*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
 # Classify first, then check test script (only impl files need gating)
 FILE_TYPE=$(tdd_classify_file "$FILE_PATH")
 if [ "$FILE_TYPE" != "impl" ]; then
   exit 0
 fi
 
-# If no test script configured, block and direct to create skill
+# If no test script configured, check if setup skill is running
 if ! tdd_has_test_script; then
+  # Allow edits if the setup skill is actively running (chicken-and-egg bypass)
+  if [ -n "$SESSION_ID" ] && [ -f "/tmp/tdd-setup-active-${SESSION_ID}" ]; then
+    exit 0
+  fi
   BASENAME=$(basename "$FILE_PATH")
-  tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' because no test script is configured in package.json. Run /wr-tdd:create to set up a test framework for this project. TDD enforcement requires a working test runner before implementation code can be written."
+  tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' because no test script is configured in package.json. Run /wr-tdd:setup-tests to set up a test framework for this project. TDD enforcement requires a working test runner before implementation code can be written."
   exit 0
 fi
 
@@ -34,25 +49,26 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Check state for implementation files
-STATE=$(tdd_read_state "$SESSION_ID")
+# Check state for THIS implementation file's associated test
+STATE=$(tdd_read_state_for_impl "$SESSION_ID" "$FILE_PATH")
 BASENAME=$(basename "$FILE_PATH")
+SUGGESTED_TEST=$(tdd_suggest_test_path "$FILE_PATH")
 
 case "$STATE" in
   RED|GREEN)
-    # Allowed: agent is in the TDD cycle
+    # Allowed: this file's test is in the TDD cycle
     exit 0
     ;;
   IDLE)
-    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- no tests written yet. TDD state is IDLE. You MUST write a failing test first (*.test.ts or *.spec.ts) before editing implementation files. The test should describe the behavior you want to implement."
+    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- no tests written for this file yet. TDD state is IDLE. Write a failing test first (e.g., ${SUGGESTED_TEST}) before editing this implementation file."
     exit 0
     ;;
   BLOCKED)
-    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- test runner is in error state. TDD state is BLOCKED. Fix the test setup first (check test configuration, fix syntax errors in test files, or verify the test command works)."
+    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- its test runner timed out. TDD state is BLOCKED. Fix the test setup for this file before continuing."
     exit 0
     ;;
   *)
-    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- unknown TDD state '${STATE}'. Write a failing test first."
+    tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' -- unknown TDD state '${STATE}'. Write a failing test first (e.g., ${SUGGESTED_TEST})."
     exit 0
     ;;
 esac

package/hooks/tdd-inject.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # TDD - UserPromptSubmit hook
-# Injects TDD instructions and current state into every prompt.
+# Injects TDD instructions and per-file state into every prompt.
 # Only active when a test script is configured in package.json.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -18,56 +18,67 @@ This project has NO test script configured in package.json. Implementation file
 edits (.ts, .tsx, .js, .jsx) are BLOCKED until testing is set up.
 
 If the user's task involves writing or editing implementation code, you MUST
-run /wr-tdd:create first to configure a test framework for this project.
+run /wr-tdd:setup-tests first to configure a test framework for this project.
 
 Test files, config files, docs, and styles are still writable.
 HOOK_OUTPUT
   exit 0
 fi
 
-STATE="IDLE"
+# Collect per-file states
+ALL_STATES=""
 if [ -n "$SESSION_ID" ]; then
-  STATE=$(tdd_read_state "$SESSION_ID")
+  ALL_STATES=$(tdd_get_all_states "$SESSION_ID")
 fi
 
-TEST_FILES=""
-if [ -n "$SESSION_ID" ]; then
-  TEST_FILES=$(tdd_get_test_files "$SESSION_ID")
+# Determine overall status for the header
+OVERALL="IDLE"
+if [ -n "$ALL_STATES" ]; then
+  if echo "$ALL_STATES" | grep -q ":BLOCKED$"; then
+    OVERALL="BLOCKED (some tests)"
+  elif echo "$ALL_STATES" | grep -q ":RED$"; then
+    OVERALL="RED (some tests failing)"
+  elif echo "$ALL_STATES" | grep -q ":GREEN$"; then
+    OVERALL="GREEN"
+  fi
 fi
 
 cat <<HOOK_OUTPUT
 INSTRUCTION: MANDATORY TDD ENFORCEMENT. YOU MUST FOLLOW THIS.
 
-This project enforces Red-Green-Refactor via hooks. Your current TDD state is: **${STATE}**
+This project enforces Red-Green-Refactor via hooks. Your current TDD state is: **${OVERALL}**
 
-STATE RULES:
+STATE RULES (per test file — each component has independent state):
 - IDLE: You MUST write a failing test FIRST before any implementation code.
-  Implementation file edits (.ts, .tsx, .js, .jsx) are BLOCKED until you write a test.
+  Implementation file edits (.ts, .tsx, .js, .jsx) are BLOCKED until you write a test for that file.
 - RED: Tests are failing. Write implementation code to make them pass.
-  Implementation file edits are ALLOWED.
+  Implementation file edits are ALLOWED for files whose associated test is RED.
 - GREEN: Tests are passing. You may refactor or write a new failing test.
-  Implementation file edits are ALLOWED.
-- BLOCKED: Test runner error or timeout. Fix the test setup before continuing.
-  Implementation file edits are BLOCKED.
+  Implementation file edits are ALLOWED for files whose associated test is GREEN.
+- BLOCKED: Test runner timed out. Fix the test setup before continuing.
+  Implementation file edits are BLOCKED for files whose associated test is BLOCKED.
 
 WORKFLOW:
-1. Write a test file (*.test.ts, *.spec.ts, etc.) that describes the desired behavior
+1. Write a test file (*.test.ts or *.spec.ts) that describes the desired behavior
 2. The test MUST fail (RED state) -- this proves the test is meaningful
 3. Write the minimum implementation to make the test pass (GREEN state)
 4. Refactor while keeping tests green
 5. Repeat for the next behavior
 
 IMPORTANT:
+- State is tracked PER TEST FILE — a failing Countdown test does NOT block editing Hero
 - Test files and config/doc/style files are ALWAYS writable regardless of state
-- Implementation files are ONLY writable in RED or GREEN states
-- The hook runs your tests automatically after every file write
+- Implementation files are ONLY writable when their associated test is RED or GREEN
+- The hook runs only the relevant test after each file write (not the full suite)
 - To refactor existing code, touch the relevant test file first to enter the cycle
 HOOK_OUTPUT
 
-if [ -n "$TEST_FILES" ]; then
+if [ -n "$ALL_STATES" ]; then
   echo ""
   echo "TRACKED TEST FILES THIS SESSION:"
-  echo "$TEST_FILES" | sed 's/^/  - /'
+  echo "$ALL_STATES" | while IFS=: read -r file state; do
+    echo "  - ${file} [${state}]"
+  done
 fi
 
 exit 0

package/hooks/tdd-post-write.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # TDD - PostToolUse hook (Edit|Write)
-# Runs tests after file writes and transitions state.
+# Runs only the relevant test after file writes and transitions per-file state.
 # Emits additionalContext with the current TDD state.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -28,45 +28,49 @@ if [ "$FILE_TYPE" = "exempt" ]; then
   exit 0
 fi
 
-# Track test files
+# Determine which test file to run
+TEST_FILE=""
+
 if [ "$FILE_TYPE" = "test" ]; then
+  # Written a test file — track it and run it
   tdd_add_test_file "$SESSION_ID" "$FILE_PATH"
+  TEST_FILE="$FILE_PATH"
+elif [ "$FILE_TYPE" = "impl" ]; then
+  # Written an impl file — find and run its associated test
+  TEST_FILE=$(tdd_find_test_for_impl "$SESSION_ID" "$FILE_PATH")
+fi
+
+# If no test file to run, nothing to do
+if [ -z "$TEST_FILE" ]; then
+  exit 0
 fi
 
-# Run tests
-tdd_run_tests "$SESSION_ID"
+# Run only the relevant test file
+tdd_run_test_file "$SESSION_ID" "$TEST_FILE"
 TEST_EXIT=$?
 
-# Read current state
-OLD_STATE=$(tdd_read_state "$SESSION_ID")
+# Read current state for this specific test file
+OLD_STATE=$(tdd_read_state "$SESSION_ID" "$TEST_FILE")
 
-# Transition state based on file type + test result
+# Transition state based on test result
+# Only timeout (124) → BLOCKED. All other failures → RED.
 NEW_STATE="$OLD_STATE"
 
 if [ $TEST_EXIT -eq 0 ]; then
   # Tests pass
   NEW_STATE="GREEN"
-elif [ $TEST_EXIT -eq 1 ]; then
-  # Tests fail
-  case "$FILE_TYPE" in
-    test)
-      NEW_STATE="RED"
-      ;;
-    impl)
-      case "$OLD_STATE" in
-        RED) NEW_STATE="RED" ;;    # still working
-        GREEN) NEW_STATE="RED" ;;  # broke something
-        *) NEW_STATE="RED" ;;
-      esac
-      ;;
-  esac
-else
-  # Timeout (124) or other error
+elif [ $TEST_EXIT -eq 124 ]; then
+  # Timeout — genuinely broken setup
   NEW_STATE="BLOCKED"
+else
+  # Tests fail (exit code 1, 2, or any other non-zero)
+  # This includes import errors, syntax errors, assertion failures.
+  # All of these are RED — the user should write impl to fix them.
+  NEW_STATE="RED"
 fi
 
-# Write new state
-tdd_write_state "$SESSION_ID" "$NEW_STATE"
+# Write new state for this specific test file
+tdd_write_state "$SESSION_ID" "$TEST_FILE" "$NEW_STATE"
 
 # Read last test output for context
 STDOUT_FILE="/tmp/tdd-test-stdout-${SESSION_ID}"
@@ -85,7 +89,8 @@ fi
 
 cat <<EOF
 TDD STATE UPDATE: ${TRANSITION}
-Current state: ${NEW_STATE}
+Test file: ${TEST_FILE}
+State: ${NEW_STATE}
 File written: ${FILE_PATH} (${FILE_TYPE})
 Test result: exit code ${TEST_EXIT}
 EOF
@@ -99,15 +104,15 @@ fi
 case "$NEW_STATE" in
   RED)
     echo ""
-    echo "ACTION: Tests are failing. Write implementation code to make them pass."
+    echo "ACTION: Tests are failing for ${TEST_FILE}. Write implementation code to make them pass."
     ;;
   GREEN)
     echo ""
-    echo "ACTION: Tests are passing. You may refactor or write a new failing test for the next behavior."
+    echo "ACTION: Tests are passing for ${TEST_FILE}. You may refactor or write a new failing test for the next behavior."
     ;;
   BLOCKED)
     echo ""
-    echo "ACTION: Test runner error (exit code ${TEST_EXIT}). Fix the test setup before continuing."
+    echo "ACTION: Test runner timed out for ${TEST_FILE} (exit code ${TEST_EXIT}). Fix the test setup before continuing."
     ;;
 esac
 

package/hooks/tdd-setup-marker.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# PostToolUse:Skill hook — sets a marker when /wr-tdd:setup-tests is invoked.
+# This marker allows tdd-enforce-edit.sh to permit edits during test setup,
+# avoiding the chicken-and-egg problem where the setup skill needs to write
+# .ts/.js files but the enforce hook blocks them.
+
+INPUT=$(cat)
+
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ] || [ -z "$SKILL_NAME" ]; then
+  exit 0
+fi
+
+# Match the TDD setup skill (handles both full and short names)
+case "$SKILL_NAME" in
+  *tdd*setup*|*setup*test*)
+    touch "/tmp/tdd-setup-active-${SESSION_ID}"
+    ;;
+esac
+
+exit 0

package/hooks/test/tdd-gate.bats

@@ -0,0 +1,276 @@
+#!/usr/bin/env bats
+
+# Tests for tdd-gate.sh shared library functions
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/tdd-gate.sh"
+  TEST_SESSION="test-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  tdd_cleanup "$TEST_SESSION" 2>/dev/null || true
+  rm -f "/tmp/tdd-setup-active-${TEST_SESSION}"
+}
+
+# --- tdd_classify_file ---
+
+@test "classify_file: .test.ts is test" {
+  result=$(tdd_classify_file "src/utils.test.ts")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: .spec.jsx is test" {
+  result=$(tdd_classify_file "src/App.spec.jsx")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: __tests__ directory is test" {
+  result=$(tdd_classify_file "src/__tests__/utils.ts")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: .config.ts is exempt" {
+  result=$(tdd_classify_file "vitest.config.ts")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .setup.ts is exempt" {
+  result=$(tdd_classify_file "vitest.setup.ts")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .json is exempt" {
+  result=$(tdd_classify_file "package.json")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .css is exempt" {
+  result=$(tdd_classify_file "src/styles.css")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .md is exempt" {
+  result=$(tdd_classify_file "README.md")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .sh is exempt" {
+  result=$(tdd_classify_file "scripts/build.sh")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .ts is impl" {
+  result=$(tdd_classify_file "src/utils.ts")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: .tsx is impl" {
+  result=$(tdd_classify_file "src/App.tsx")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: .js is impl" {
+  result=$(tdd_classify_file "src/index.js")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: unknown extension is exempt" {
+  result=$(tdd_classify_file "Dockerfile")
+  [ "$result" = "exempt" ]
+}
+
+# --- tdd_has_test_script ---
+
+@test "has_test_script: returns false when no package.json" {
+  cd "$(mktemp -d)"
+  run tdd_has_test_script
+  [ "$status" -ne 0 ]
+}
+
+@test "has_test_script: returns false for default npm test script" {
+  local tmpdir=$(mktemp -d)
+  echo '{"scripts":{"test":"echo \"Error: no test specified\" && exit 1"}}' > "$tmpdir/package.json"
+  cd "$tmpdir"
+  run tdd_has_test_script
+  [ "$status" -ne 0 ]
+  rm -rf "$tmpdir"
+}
+
+@test "has_test_script: returns true for real test script" {
+  local tmpdir=$(mktemp -d)
+  echo '{"scripts":{"test":"vitest"}}' > "$tmpdir/package.json"
+  cd "$tmpdir"
+  run tdd_has_test_script
+  [ "$status" -eq 0 ]
+  rm -rf "$tmpdir"
+}
+
+# --- Per-test-file state ---
+
+@test "read_state: returns IDLE when no state exists for test file" {
+  result=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  [ "$result" = "IDLE" ]
+}
+
+@test "write_state and read_state roundtrip for a specific test file" {
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "RED"
+  result=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  [ "$result" = "RED" ]
+}
+
+@test "per-file state: different test files have independent states" {
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "GREEN"
+  tdd_write_state "$TEST_SESSION" "src/Countdown.test.tsx" "RED"
+
+  hero_state=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  countdown_state=$(tdd_read_state "$TEST_SESSION" "src/Countdown.test.tsx")
+
+  [ "$hero_state" = "GREEN" ]
+  [ "$countdown_state" = "RED" ]
+}
+
+@test "per-file state: BLOCKED on one test does not affect another" {
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "GREEN"
+  tdd_write_state "$TEST_SESSION" "src/Countdown.test.tsx" "BLOCKED"
+
+  hero_state=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  [ "$hero_state" = "GREEN" ]
+}
+
+@test "cleanup removes all per-file state" {
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "RED"
+  tdd_write_state "$TEST_SESSION" "src/Countdown.test.tsx" "GREEN"
+  tdd_cleanup "$TEST_SESSION"
+
+  result=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  [ "$result" = "IDLE" ]
+  result=$(tdd_read_state "$TEST_SESSION" "src/Countdown.test.tsx")
+  [ "$result" = "IDLE" ]
+}
+
+@test "cleanup removes setup marker" {
+  touch "/tmp/tdd-setup-active-${TEST_SESSION}"
+  tdd_cleanup "$TEST_SESSION"
+  [ ! -f "/tmp/tdd-setup-active-${TEST_SESSION}" ]
+}
+
+# --- Test file tracking ---
+
+@test "add_test_file and get_test_files roundtrip" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  result=$(tdd_get_test_files "$TEST_SESSION")
+  [ "$result" = "src/Hero.test.tsx" ]
+}
+
+@test "add_test_file deduplicates" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  local count
+  count=$(tdd_get_test_files "$TEST_SESSION" | wc -l | tr -d ' ')
+  [ "$count" -eq 1 ]
+}
+
+# --- Impl-to-test association ---
+
+@test "find_test_for_impl: Hero.tsx associates with tracked Hero.test.tsx" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  result=$(tdd_find_test_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  [ "$result" = "src/Hero.test.tsx" ]
+}
+
+@test "find_test_for_impl: utils.ts associates with tracked utils.test.ts" {
+  tdd_add_test_file "$TEST_SESSION" "src/utils.test.ts"
+  result=$(tdd_find_test_for_impl "$TEST_SESSION" "src/utils.ts")
+  [ "$result" = "src/utils.test.ts" ]
+}
+
+@test "suggest_test_path: Hero.tsx suggests Hero.test.tsx" {
+  result=$(tdd_suggest_test_path "src/Hero.tsx")
+  [ "$result" = "src/Hero.test.tsx" ]
+}
+
+@test "suggest_test_path: utils.ts suggests utils.test.ts" {
+  result=$(tdd_suggest_test_path "src/utils.ts")
+  [ "$result" = "src/utils.test.ts" ]
+}
+
+@test "find_test_for_impl: prefers tracked .test over .spec" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.spec.tsx"
+  result=$(tdd_find_test_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  [ "$result" = "src/Hero.spec.tsx" ]
+}
+
+@test "find_test_for_impl: finds __tests__ variant when tracked" {
+  tdd_add_test_file "$TEST_SESSION" "src/__tests__/Hero.test.tsx"
+  result=$(tdd_find_test_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  [ "$result" = "src/__tests__/Hero.test.tsx" ]
+}
+
+@test "find_test_for_impl: returns empty when no test tracked" {
+  result=$(tdd_find_test_for_impl "$TEST_SESSION" "src/Unknown.tsx")
+  [ -z "$result" ]
+}
+
+# --- State for impl files (via association) ---
+
+@test "read_state_for_impl: returns IDLE when no associated test" {
+  result=$(tdd_read_state_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  [ "$result" = "IDLE" ]
+}
+
+@test "read_state_for_impl: returns associated test's state" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "RED"
+  result=$(tdd_read_state_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  [ "$result" = "RED" ]
+}
+
+@test "read_state_for_impl: Hero GREEN while Countdown BLOCKED" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  tdd_add_test_file "$TEST_SESSION" "src/Countdown.test.tsx"
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "GREEN"
+  tdd_write_state "$TEST_SESSION" "src/Countdown.test.tsx" "BLOCKED"
+
+  hero=$(tdd_read_state_for_impl "$TEST_SESSION" "src/Hero.tsx")
+  countdown=$(tdd_read_state_for_impl "$TEST_SESSION" "src/Countdown.tsx")
+
+  [ "$hero" = "GREEN" ]
+  [ "$countdown" = "BLOCKED" ]
+}
+
+# --- get_all_states ---
+
+@test "get_all_states: lists all test files with their states" {
+  tdd_add_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  tdd_add_test_file "$TEST_SESSION" "src/Countdown.test.tsx"
+  tdd_write_state "$TEST_SESSION" "src/Hero.test.tsx" "GREEN"
+  tdd_write_state "$TEST_SESSION" "src/Countdown.test.tsx" "RED"
+
+  result=$(tdd_get_all_states "$TEST_SESSION")
+  echo "$result" | grep -q "src/Hero.test.tsx:GREEN"
+  echo "$result" | grep -q "src/Countdown.test.tsx:RED"
+}
+
+# --- Scoped test runner ---
+
+@test "run_test_file: runs only the specified test file" {
+  local tmpdir=$(mktemp -d)
+  cd "$tmpdir"
+
+  TDD_TEST_CMD="echo"
+  tdd_run_test_file "$TEST_SESSION" "src/Hero.test.tsx"
+  local exit_code=$?
+  [ "$exit_code" -eq 0 ]
+
+  # The stdout file should contain just the one file path (from echo)
+  local stdout_file="/tmp/tdd-test-stdout-${TEST_SESSION}"
+  [ -f "$stdout_file" ]
+  grep -q "src/Hero.test.tsx" "$stdout_file"
+  # Should NOT contain any other test file
+  local line_count
+  line_count=$(wc -l < "$stdout_file" | tr -d ' ')
+  [ "$line_count" -eq 1 ]
+
+  rm -rf "$tmpdir"
+}

package/hooks/test/tdd-project-root.bats

@@ -0,0 +1,20 @@
+#!/usr/bin/env bats
+
+# P004: tdd-enforce-edit.sh project-root check.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/tdd-enforce-edit.sh"
+}
+
+run_hook_with_file() {
+  local file_path="$1"
+  local json="{\"tool_input\":{\"file_path\":\"${file_path}\"},\"session_id\":\"test-$$\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+@test "tdd project-root: absolute .ts outside project exits 0" {
+  run run_hook_with_file "/Users/other/project/src/foo.ts"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}

package/lib/install-utils.mjs

@@ -0,0 +1,143 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName);
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/tdd",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TDD state machine enforcement (Red-Green-Refactor cycle)",
   "bin": {
     "windyroad-tdd": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "lib/"
   ]
 }

package/skills/{wr:tdd → setup-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:tdd
+name: wr-tdd:setup-tests
 description: Set up a test framework for the project. Examines the codebase, recommends a test runner, configures package.json, and creates an example test.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---