# Design 1: The Mutation Farmer

## Purpose
The Mutation Farmer is a defensive agent designed to answer the question: "Who tests the testers?" It proactively measures the quality of the test suite by purposefully introducing subtle bugs ("mutants") into the codebase and verifying that the existing tests fail ("kill" the mutant). If a mutant survives (tests pass despite the bug), the agent flags the test gap or autonomously writes a new test case to catch it.

## Loop Structure
1.  **Surveillance:** Watch for changes in the codebase (git diff).
2.  **Analysis:** Parse changed files to identify testable units (functions, classes).
3.  **Mutant Generation:** Create temporary copies of the code with specific mutations:
    *   Invert logic (`if a > b` $\to$ `if a <= b`)
    *   Change constants (`return 200` $\to$ `return 500`)
    *   Drop function calls
4.  **Trial:** Run the relevant test suite against the mutant.
5.  **Verdict:**
    *   *Mutant Killed (Test Failed):* Good. Discard mutant.
    *   *Mutant Survived (Test Passed):* Bad. The test suite is weak.
6.  **Remediation:**
    *   Store the "Surviving Mutant" in Memory.
    *   Attempt to generate a new test case that targets the specific mutation.
    *   Verify the new test kills the mutant.
    *   Propose the new test to the user.

## Tool Usage
*   **filesystem:** Read source code; create temporary mutant files; write new test files.
*   **grep/ripgrep:** Find usage of functions to determine impact radius.
*   **shell:** Execute test runners (e.g., `pytest`, `npm test`); manage git branches for clean cleanup.
*   **memory:** Store a "Mutation Score" for each module; track "Hard-to-Kill" mutants to avoid re-generating the same ones repeatedly.

## Memory Architecture
*   **Nodes:** `Module`, `Test`, `Mutant`
*   **Relations:**
    *   `(Test) KILLS (Mutant)`
    *   `(Mutant) SURVIVES_IN (Module)`
    *   `(Module) HAS_SCORE (Float)`
*   **Persistence:** The graph allows the agent to prioritize "weak" modules that have high mutation survival rates over time.

## Failure Modes
*   **Infinite Loops:** A mutation might cause the code to hang (e.g., `i++` $\to$ `i--`). **Recovery:** Strict timeouts on all test runs.
*   **False Positives:** Mutating a cosmetic string might not break logic. **Recovery:** Use AST-based mutation rather than regex to avoid strings/comments.
*   **Resource Exhaustion:** Running tests 1000x for 1000 mutants is slow. **Recovery:** Use "Extreme Mutation" (only mutate 1 random line per run) or "Targeted Mutation" (only mutate lines changed in the last commit).

## Human Touchpoints
*   **PR Comments:** The agent posts "Surviving Mutants" as comments on Pull Requests.
*   **Approval:** Human must approve any *new* tests generated by the agent.
