@windyroad/tdd 0.1.4 → 0.2.0-preview.29

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 --}"
@@ -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,7 +273,9 @@ 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}"

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"
@@ -38,25 +39,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)"
@@ -25,49 +25,60 @@ 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/test/tdd-gate.bats

@@ -106,23 +106,46 @@ teardown() {
   rm -rf "$tmpdir"
 }
 
-# --- tdd state ---
+# --- Per-test-file state ---
 
-@test "read_state: returns IDLE when no state file" {
-  result=$(tdd_read_state "$TEST_SESSION")
+@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" {
-  tdd_write_state "$TEST_SESSION" "RED"
-  result=$(tdd_read_state "$TEST_SESSION")
+@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 "cleanup removes state files" {
-  tdd_write_state "$TEST_SESSION" "GREEN"
+@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")
+
+  result=$(tdd_read_state "$TEST_SESSION" "src/Hero.test.tsx")
+  [ "$result" = "IDLE" ]
+  result=$(tdd_read_state "$TEST_SESSION" "src/Countdown.test.tsx")
   [ "$result" = "IDLE" ]
 }
 
@@ -131,3 +154,123 @@ teardown() {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/tdd",
-  "version": "0.1.4",
+  "version": "0.2.0-preview.29",
   "description": "TDD state machine enforcement (Red-Green-Refactor cycle)",
   "bin": {
     "windyroad-tdd": "./bin/install.mjs"