refactor: Rename TDD intent terminology to declaration across codebase

Rename internal state names (red_intent → writing_tests, green_intent →
making_tests_pass) and update all user-facing messages, documentation,
and tests to use "declaration" instead of "intent".

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cadamsdotcom

CLAUDE.md

@@ -198,12 +198,12 @@ Remember: A test that fails for the wrong reason teaches you nothing about the c
 3. Can existing e2e tests be enhanced to cover this work instead of writing new ones?
 4. Can planned e2e tests be unit/integration/component tests instead?
 
-**Red Intent Honesty:**
+**Honest Test Declarations:**
 
-- **Red intent must describe expected failure.** If you're adding tests that will pass immediately, use `--skip-red` on the Green intent instead. Don't log a Red intent for tests you expect to pass.
+- **The writing-tests declaration must describe expected failure.** If you're adding tests that will pass immediately, use `--skip-red` on the making-tests-pass declaration instead. Don't start writing tests for tests you expect to pass.
 - **Guard tests (assert unchanged behavior):** When writing tests that expect existing/default behavior to continue (e.g., "blocked stays blocked", "no-op when absent"), these can't fail during a natural Red phase. Use `--skip-red --reason=adding-coverage` for these, even when they're part of a larger feature. Don't bundle them into a Red cycle where they'll pass immediately.
 - Do NOT use `--skip-red` to avoid TDD, even if you already have e2e coverage.
-- The TDD guard enforces that `tdd_log green` requires a preceding Red cycle (Red intent -> failing test -> Green intent). The `--skip-red` flag is the escape hatch for changes that genuinely don't need a failing test first.
+- The TDD guard enforces that `tdd_log green` requires a preceding Red cycle (writing tests -> failing test -> making tests pass). The `--skip-red` flag is the escape hatch for changes that genuinely don't need a failing test first.
 
 **Using --skip-red (requires --reason):**
 
@@ -238,7 +238,7 @@ The TDD log file name and full usage examples are provided automatically at sess
 
 **Overriding TDD State:**
 
-You can force the TDD state into any other state by logging a Red or Green intent by running tdd_log with your desired arguments as normal. Your override will be logged for later review. Useful if you get stuck in the wrong TDD state (e.g., you logged the wrong expectation or made a mistake).
+You can force the TDD state into any other state by logging a Red or Green declaration via tdd_log with your desired arguments as normal. Your override will be logged for later review. Useful if you get stuck in the wrong TDD state (e.g., you logged the wrong expectation or made a mistake).
 
 ### Unit Test Performance & Timeouts
 

docs-site/docs/tdd-guard.md

@@ -10,7 +10,7 @@ The TDD Guard is a state machine enforced through Claude Code hooks. It ensures
 The guard maintains four states:
 
 ```
-initial ──→ red_intent ──→ red ──→ green_intent ──→ initial
+initial ──→ writing_tests ──→ red ──→ making_tests_pass ──→ initial
    │            │                       │
    │         (write       (tests      (edit prod
    │          test)        fail)       files)
@@ -19,12 +19,12 @@ initial ──→ red_intent ──→ red ──→ green_intent ──→ init
                  (tests pass)
 ```
 
-| State          | Meaning                                       | Allowed Actions               |
-| -------------- | --------------------------------------------- | ----------------------------- |
-| `initial`      | No active TDD cycle                           | Log Red intent only           |
-| `red_intent`   | Agent declared what test should fail          | Edit test files only          |
-| `red`          | Test ran and failed (as expected)             | Log Green intent only         |
-| `green_intent` | Agent declared what to change and which files | Edit declared prod files only |
+| State               | Meaning                                       | Allowed Actions               |
+| ------------------- | --------------------------------------------- | ----------------------------- |
+| `initial`           | No active TDD cycle                           | Log Red declaration only      |
+| `writing_tests`     | Agent declared what test should fail          | Edit test files only          |
+| `red`               | Test ran and failed (as expected)             | Log Green declaration only    |
+| `making_tests_pass` | Agent declared what to change and which files | Edit declared prod files only |
 
 When tests pass after a Green phase, the state returns to `initial`.
 
@@ -42,14 +42,14 @@ def read_state(log_path: Path) -> str:
         if stripped.startswith("[test]") and stripped.endswith("— SUCCEEDED"):
             return "initial"
         if stripped.startswith("[test]") and "— FAILED" in stripped:
-            preceding = _find_preceding_intent(lines, len(lines) - 1 - i)
+            preceding = _find_preceding_declaration(lines, len(lines) - 1 - i)
             if preceding == "green":
-                return "green_intent"
+                return "making_tests_pass"
             return "red"
         if stripped.startswith("## Red"):
-            return "red_intent"
+            return "writing_tests"
         if stripped.startswith("## Green"):
-            return "green_intent"
+            return "making_tests_pass"
     return "initial"
 ```
 
@@ -58,22 +58,22 @@ def read_state(log_path: Path) -> str:
 Summary of state derivation rules:
 
 - `[test] ... — SUCCEEDED` → `initial`
-- `[test] ... — FAILED` after a `## Green` header → `green_intent` (test failed during Green)
+- `[test] ... — FAILED` after a `## Green` header → `making_tests_pass` (test failed during Green)
 - `[test] ... — FAILED` after a `## Red` header → `red` (test failed as expected)
-- `## Red ...` → `red_intent`
-- `## Green ...` → `green_intent`
+- `## Red ...` → `writing_tests`
+- `## Green ...` → `making_tests_pass`
 
 ## The CLI: `tdd_log`
 
 Agents interact with the TDD guard through [`scripts/tdd_log.py`](https://github.com/cadamsdotcom/CodeLeash/blob/main/scripts/tdd_log.py), invoked as:
 
 ```bash
-# Declare Red intent
+# Declare Red (writing-tests) phase
 uv run python -m scripts.tdd_log --log "tdd-abc123.log" red \
   --test "path/to/test_file" \
   --expects "test_name fails because ..."
 
-# Declare Green intent
+# Declare Green (making-tests-pass) phase
 uv run python -m scripts.tdd_log --log "tdd-abc123.log" green \
   --change "what you plan to do" \
   --file "path/to/file1.py" --file "path/to/file2.py"
@@ -88,12 +88,12 @@ uv run python -m scripts.tdd_log --log "tdd-abc123.log" green --skip-red \
 
 The `green` subcommand enforces prerequisites:
 
-- Without `--skip-red`: requires state to be `red` (test must have failed) or `green_intent` (re-logging)
+- Without `--skip-red`: requires state to be `red` (test must have failed) or `making_tests_pass` (re-logging)
 - With `--skip-red`: requires a `--reason` from `{refactoring, lint-only, adding-coverage}`
 
 ### Overrides
 
-Logging a Red or Green intent at any time overrides the current state. This is useful when the agent gets stuck in the wrong state. Overrides are recorded in the log for later review.
+Logging a Red or Green declaration at any time overrides the current state. This is useful when the agent gets stuck in the wrong state. Overrides are recorded in the log for later review.
 
 ## Pre-Edit Hook
 
@@ -124,14 +124,14 @@ PROD_PATTERNS = [
 
 ### Permission Table
 
-| State          | Test Files  | Prod Files                |
-| -------------- | ----------- | ------------------------- |
-| `initial`      | Blocked     | Blocked                   |
-| `red_intent`   | **Allowed** | Blocked                   |
-| `red`          | Blocked     | Blocked                   |
-| `green_intent` | Blocked\*   | Allowed (if in allowlist) |
+| State               | Test Files  | Prod Files                |
+| ------------------- | ----------- | ------------------------- |
+| `initial`           | Blocked     | Blocked                   |
+| `writing_tests`     | **Allowed** | Blocked                   |
+| `red`               | Blocked     | Blocked                   |
+| `making_tests_pass` | Blocked\*   | Allowed (if in allowlist) |
 
-\* Test files are allowed during `green_intent` only if the Green was logged with `--skip-red`.
+\* Test files are allowed during `making_tests_pass` only if the Green was logged with `--skip-red`.
 
 ### Green Allowlist
 
@@ -149,7 +149,7 @@ The [`scripts/tdd_post_bash.py`](https://github.com/cadamsdotcom/CodeLeash/blob/
 | `npm test*` or `npm run test*` | `test`             | Drives state transitions |
 | Everything else                | `bash`             | Logged, no state change  |
 
-Test commands tagged as `test` with `SUCCEEDED` status reset the state to `initial`. Test commands that `FAILED` during a Red phase confirm the state as `red`.
+Test commands tagged as `test` with `SUCCEEDED` status reset the state to `initial`. Test commands that `FAILED` during a writing-tests phase confirm the state as `red`.
 
 ### Example TDD Log
 

docs-site/src/pages/index.tsx

@@ -48,7 +48,7 @@ function StateStrip(): ReactNode {
         <span className={styles.stateArrow}>&rarr;</span>
         <span className={styles.stateLabel}>log red</span>
         <span className={styles.stateArrow}>&rarr;</span>
-        <span className={styles.stateNode}>red_intent</span>
+        <span className={styles.stateNode}>writing_tests</span>
         <span className={styles.stateArrow}>&rarr;</span>
         <span className={styles.stateLabel}>test fails</span>
         <span className={styles.stateArrow}>&rarr;</span>
@@ -59,7 +59,7 @@ function StateStrip(): ReactNode {
         <span className={styles.stateLabel}>log green</span>
         <span className={styles.stateArrow}>&rarr;</span>
         <span className={`${styles.stateNode} ${styles.stateNodeGreen}`}>
-          green_intent
+          making_tests_pass
         </span>
         <span className={styles.stateArrow}>&rarr;</span>
         <span className={styles.stateLabel}>tests pass</span>

scripts/tdd_common.py

@@ -34,14 +34,14 @@ def is_prod_file(rel_path: str) -> bool:
 
 STATES = {
     "initial": "initial",
-    "red_intent": "red_intent",
+    "writing_tests": "writing_tests",
     "red": "red",
-    "green_intent": "green_intent",
+    "making_tests_pass": "making_tests_pass",
 }
 
 
-def _find_preceding_intent(lines: list[str], before_index: int) -> str | None:
-    """Scan backwards from before_index to find the preceding Red/Green intent."""
+def _find_preceding_declaration(lines: list[str], before_index: int) -> str | None:
+    """Scan backwards from before_index to find the preceding Red/Green declaration."""
     for i in range(before_index - 1, -1, -1):
         stripped = lines[i].rstrip()
         if stripped.startswith("## Green"):
@@ -67,15 +67,15 @@ def read_state(log_path: Path) -> str:
         if stripped.startswith("[test]") and stripped.endswith("— SUCCEEDED"):
             return STATES["initial"]
         if stripped.startswith("[test]") and "— FAILED" in stripped:
-            # Look further back for the preceding intent
-            preceding = _find_preceding_intent(lines, len(lines) - 1 - i)
+            # Look further back for the preceding declaration
+            preceding = _find_preceding_declaration(lines, len(lines) - 1 - i)
             if preceding == "green":
-                return STATES["green_intent"]
+                return STATES["making_tests_pass"]
             return STATES["red"]
         if stripped.startswith("## Red"):
-            return STATES["red_intent"]
+            return STATES["writing_tests"]
         if stripped.startswith("## Green"):
-            return STATES["green_intent"]
+            return STATES["making_tests_pass"]
         # Skip other lines (Test:, Expects:, Change:, File:, [bash], [edit])
 
     return STATES["initial"]

scripts/tdd_log.py

@@ -1,4 +1,4 @@
-"""TDD Guard — CLI for writing Red/Green log entries.
+"""TDD Guard — CLI for writing Red/Green log declarations.
 
 Replaces fragile echo chains with a single script invocation.
 The --log flag specifies the log filename (resolved relative to project root).
@@ -67,25 +67,25 @@ def cmd_green(args: argparse.Namespace) -> int:
             return 1
 
     # Validate state: Green requires a preceding Red cycle (test must have failed)
-    if not skip_red and state not in ("red", "green_intent"):
-        if state == "red_intent":
+    if not skip_red and state not in ("red", "making_tests_pass"):
+        if state == "writing_tests":
             print(
                 "ERROR: Run your failing test(s) before logging Green.\n"
-                "You declared a Red intent but haven't seen test(s) fail "
-                "yet.",
+                "You declared a writing-tests phase but haven't seen "
+                "test(s) fail yet.",
                 file=sys.stderr,
             )
         else:
             print(
                 "ERROR: Cannot log Green without a preceding Red cycle.\n"
-                "Log a Red intent first, write failing test(s) or modify "
-                "existing test(s) to fail, then run them.",
+                "Start writing tests first, write failing test(s) or "
+                "modify existing test(s) to fail, then run them.",
                 file=sys.stderr,
             )
         return 1
 
     # Determine if this is an override
-    is_override = state != "initial" if skip_red else state == "green_intent"
+    is_override = state != "initial" if skip_red else state == "making_tests_pass"
 
     # Build phase label
     if skip_red:
@@ -116,11 +116,11 @@ def main() -> None:
     )
     sub = parser.add_subparsers(dest="phase", required=True)
 
-    red = sub.add_parser("red", help="Log Red phase intent")
+    red = sub.add_parser("red", help="Log Red phase declaration")
     red.add_argument("--test", required=True, help="Path to the test file")
     red.add_argument("--expects", required=True, help="What you expect to fail and why")
 
-    green = sub.add_parser("green", help="Log Green phase intent")
+    green = sub.add_parser("green", help="Log Green phase declaration")
     green.add_argument("--change", required=True, help="What you plan to change")
     green.add_argument(
         "--file", required=True, action="append", help="File(s) you will edit"

scripts/tdd_pre_edit.py

@@ -123,21 +123,21 @@ def warn_large_allowlist(allowed: set[str], threshold: int = 5) -> None:
 
 def blocked_initial(log_name: str) -> str:
     return f"""\
-BLOCKED: Red-Green-Refactor — log your Red intent first.
+BLOCKED: Red-Green-Refactor — log your Red declaration first.
 Run (fill in the placeholders):
 
   uv run python -m scripts.tdd_log --log "{log_name}" red --test "path/to/test_file" --expects "test_name fails because ..." """
 
 
-def blocked_red_intent_impl() -> str:
+def blocked_writing_tests_impl() -> str:
     return """\
-BLOCKED: You're in the Red phase — only test files can be edited.
+BLOCKED: You're in the writing-tests phase — only test files can be edited.
 Write your failing test, then run it."""
 
 
 def blocked_red(log_name: str) -> str:
     return f"""\
-BLOCKED: Red confirmed. Log your Green intent before editing.
+BLOCKED: Red confirmed. Log your Green declaration before editing.
 Run (fill in the placeholders):
 
   uv run python -m scripts.tdd_log --log "{log_name}" green --change "what you plan to do" --file "path/to/file1.py" --file "path/to/file2.py" """
@@ -146,7 +146,7 @@ def blocked_red(log_name: str) -> str:
 def blocked_test_in_green(log_name: str) -> str:
     return f"""\
 BLOCKED: Test edits are not allowed during Green.
-If you need to change your test, re-log your Red intent first:
+If you need to change your test, re-log your Red declaration first:
 
   uv run python -m scripts.tdd_log --log "{log_name}" red --test "path/to/test_file" --expects "test_name fails because ..." """
 
@@ -158,7 +158,7 @@ def blocked_green_not_listed(file_path: str, allowed: set[str], log_name: str) -
 Declared files:
 {listed}
 
-To add it, re-run your green intent including this file:
+To add it, re-run your Green declaration including this file:
   uv run python -m scripts.tdd_log --log "{log_name}" green --change "..." --file "{file_path}" """
 
 
@@ -187,14 +187,14 @@ def _check_agent_logs(file_path: str, rel_path: str, kind: str) -> bool:
         if _is_agent_log_finished(agent_log):
             continue
         agent_state = read_state(agent_log)
-        if agent_state == "green_intent":
+        if agent_state == "making_tests_pass":
             if kind == "test" and is_skip_red_green(agent_log):
                 return True
             if kind == "prod":
                 allowed = read_green_allowlist(agent_log)
                 if rel_path in allowed:
                     return True
-        elif agent_state == "red_intent" and kind == "test":
+        elif agent_state == "writing_tests" and kind == "test":
             return True
     return False
 
@@ -242,24 +242,24 @@ def main() -> None:
         sys.exit(0)
 
     # Permission table:
-    #   initial      → block all (test + prod)
-    #   red_intent   → test ok, prod blocked
-    #   red          → block all (test + prod)
-    #   green_intent → test blocked (unless skip-red), prod in allowlist
+    #   initial          → block all (test + prod)
+    #   writing_tests    → test ok, prod blocked
+    #   red              → block all (test + prod)
+    #   making_tests_pass → test blocked (unless skip-red), prod in allowlist
     if state == "initial":
         if _check_agent_logs(file_path, rel_path, kind):
             log_edit(log_path, file_path, kind, state, "ALLOWED(agent)")
             sys.exit(0)
         log_edit(log_path, file_path, kind, state, "BLOCKED")
         print(blocked_initial(log_name), file=sys.stderr)
         sys.exit(2)
-    elif state == "red_intent":
+    elif state == "writing_tests":
         if kind == "prod":
             if _check_agent_logs(file_path, rel_path, kind):
                 log_edit(log_path, file_path, kind, state, "ALLOWED(agent)")
                 sys.exit(0)
             log_edit(log_path, file_path, kind, state, "BLOCKED")
-            print(blocked_red_intent_impl(), file=sys.stderr)
+            print(blocked_writing_tests_impl(), file=sys.stderr)
             sys.exit(2)
         # test file → allowed
         log_edit(log_path, file_path, kind, state, "ALLOWED")
@@ -271,7 +271,7 @@ def main() -> None:
         log_edit(log_path, file_path, kind, state, "BLOCKED")
         print(blocked_red(log_name), file=sys.stderr)
         sys.exit(2)
-    elif state == "green_intent":
+    elif state == "making_tests_pass":
         if kind == "test":
             if is_skip_red_green(log_path):
                 log_edit(log_path, file_path, kind, state, "ALLOWED")

scripts/tdd_session_start.py

@@ -18,14 +18,14 @@ def main() -> None:
     print()
     print("TDD Red-Green-Refactor cycle:")
     print()
-    print("  1. Log Red intent (declare what test you expect to fail):")
+    print("  1. Start writing tests (declare what you expect to fail):")
     print(f'     uv run python -m scripts.tdd_log --log "{log}" red \\')
     print('       --test "path/to/test_file" \\')
     print('       --expects "test_name fails because ..."')
     print()
     print("  2. Write the failing test, then run it to confirm it fails.")
     print()
-    print("  3. Log Green intent (declare what you will change to make it pass):")
+    print("  3. Start making tests pass (declare what you will change):")
     print(f'     uv run python -m scripts.tdd_log --log "{log}" green \\')
     print('       --change "what you plan to do" \\')
     print('       --file "path/to/file1.py" --file "path/to/file2.py"')
@@ -37,7 +37,7 @@ def main() -> None:
     print('       --reason=refactoring --change "what you plan to do" \\')
     print('       --file "path/to/file.py"')
     print()
-    print("Files subject to TDD (edits blocked until Red/Green intent logged):")
+    print("Files subject to TDD (edits blocked until Red/Green declaration logged):")
     print("  Prod:  src/  app/  scripts/*.py  main.py  worker.py")
     print(
         "  Test:  *.test.{ts,tsx,js,jsx}  test_*.py  tests/  src/test-utils/  conftest.py"