TDD Validation Engine
Relevant source files
The following files were used as context for generating this wiki page:
- src/validation/prompts/rules.ts
- src/validation/validator.ts
- src/validation/context/context.ts
- src/validation/prompts/file-types.ts
- src/validation/prompts/operations/edit.ts
- src/validation/prompts/operations/write.ts
- src/validation/prompts/operations/multi-edit.ts
- src/validation/prompts/response.ts
- src/validation/prompts/system-prompt.ts
The TDD Validation Engine is the core decision-making component of TDD Guard. Its primary purpose is to intercept and analyze file operations (Write, Edit, MultiEdit) initiated by an AI agent to ensure they strictly adhere to Test-Driven Development (TDD) principles. By analyzing the relationship between proposed code changes and existing test results, the engine can block operations that skip testing phases or over-implement logic.
Sources: src/validation/prompts/system-prompt.ts:1-12, CLAUDE.md:4-12
Architecture and Core Logic
The engine operates by constructing a high-level "Dynamic Context" that combines specialized TDD rules, operation-specific analysis instructions, and the current state of the codebase (including test output and todo lists). This context is then processed by an AI model client to reach a validation decision.
Data Flow Overview
The following diagram illustrates how the validation engine processes a tool execution request:
The flow starts with a tool operation which is enriched with project context before being evaluated against TDD rules.
Sources: src/validation/context/context.ts:25-150, src/validation/validator.ts:1-20
Key Components
| Component | Description |
|---|---|
validator | The main entry point that sends context to the AI model and parses the JSON response. |
generateDynamicContext | Orchestrates the assembly of system prompts, TDD rules, and operation-specific data. |
IModelClient | The interface for the AI model (e.g., Claude) used to perform the qualitative TDD analysis. |
ValidationResult | The output structure containing a decision ("block" or null) and a reason. |
Sources: src/validation/validator.ts:10-40, src/validation/context/context.ts:25-40, src/validation/prompts/response.ts:1-10
Validation Ruleset
The engine enforces the Red-Green-Refactor cycle through a set of strict rules defined in the prompt system.
The Red-Green-Refactor Cycle
- Red Phase: Only one failing test is allowed at a time. Adding a single test is always valid, even without prior test output.
- Green Phase: Minimal code must be written to address the specific failure. Anticipatory coding is forbidden.
- Refactor Phase: Improving structure is allowed only when all relevant tests are green.
Sources: src/validation/prompts/rules.ts:3-25
Core Violations
The engine is specifically tuned to detect the following breaches of TDD discipline:
- Multiple Test Addition: Adding more than one new test in a single operation.
- Over-Implementation: Adding methods, logic, or error handling not yet required by a failing test.
- Premature Implementation: Modifying implementation files before a test has been written and seen to fail.
- Refactoring with Failures: Attempting to clean up code while tests are still failing.
Sources: src/validation/prompts/rules.ts:27-44, src/validation/prompts/operations/edit.ts:10-30
Operation Analysis
The engine applies different logic based on the type of file operation being performed.
Edit and MultiEdit Operations
For edits, the engine compares the "Old Content" against the "New Content" to count new test declarations (test(, it(, describe(). In MultiEdit operations, the engine tracks cumulative changes across multiple edits to ensure the total number of new tests does not exceed one.
Sources: src/validation/prompts/operations/edit.ts:10-25, src/validation/prompts/operations/multi-edit.ts:10-25
Implementation File Rules
The engine correlates implementation changes with the specific type of test failure captured in the context:
| Test Failure | Allowed Implementation | Source |
|---|---|---|
| "X is not defined" | Create empty class/function stub only | src/validation/prompts/file-types.ts:23 |
| "X is not a function" | Add method stub only | src/validation/prompts/file-types.ts:25 |
| Assertion Error | Implement minimal logic to pass | src/validation/prompts/file-types.ts:26 |
| No Test Output | No implementation allowed | src/validation/prompts/file-types.ts:27 |
Sequence of Validation
The sequence diagram below shows the interaction between the validator and the prompt system during a request:
This diagram represents the internal workflow from the moment a hook triggers until a block/allow decision is returned.
Sources: src/validation/validator.ts:10-25, src/validation/context/context.test.ts:193-210
Summary of Decisions
When a violation is detected, the engine must return a "block" decision. The response includes a reason that identifies the violation, explains the TDD principle at stake, and provides actionable next steps for the agent. If the operation is compliant or if there is insufficient information (e.g., first test file creation), the decision is null.