irradiate 0.1.0__tar.gz

irradiate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Security audit
+        uses: rustsec/audit-check@v2.0.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+        continue-on-error: true
+
+      - name: Cache cargo target
+        uses: actions/cache@v4
+        with:
+          path: target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache fixture venv
+        uses: actions/cache@v4
+        with:
+          path: tests/fixtures/simple_project/.venv
+          key: ${{ runner.os }}-venv-${{ hashFiles('tests/fixtures/simple_project/pyproject.toml', 'tests/fixtures/simple_project/requirements*.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-venv-
+
+      - name: Set up fixture venv
+        run: cd tests/fixtures/simple_project && uv venv --python 3.12 --clear && uv pip install pytest
+
+      - name: cargo check + clippy
+        run: cargo check && cargo clippy -- -D warnings
+
+      - name: cargo test
+        run: cargo test
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+
+      - name: Generate coverage report
+        run: cargo llvm-cov --lcov --output-path lcov.info
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: lcov.info
+
+      - name: Run e2e tests
+        run: bash tests/e2e.sh
+
+      - name: Dogfood mutation score
+        run: |
+          cd tests/harness_tests
+          # venv is created by e2e.sh; install to be safe
+          if [ ! -d .venv ]; then uv venv --python 3.12 && uv pip install pytest; fi
+          ../../target/debug/irradiate run \
+            --paths-to-mutate ../../harness \
+            --tests-dir . \
+            --python .venv/bin/python3 \
+            --timeout-multiplier 5 \
+            --isolate 2>&1 | tee dogfood.txt || true
+          killed=$(grep -oP 'Killed:\s+\K\d+' dogfood.txt || echo 0)
+          total=$(grep -oP 'complete \(\K\d+' dogfood.txt || echo 0)
+          echo "Mutation score: ${killed} / ${total} mutants killed"
+          if [ "$total" -gt 0 ]; then
+            pct=$(( killed * 100 / total ))
+            echo "Score: ${pct}%"
+          fi
+          rm -rf mutants .irradiate

irradiate-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,94 @@
+name: Docs & Report
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"  # weekly Monday 6am UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+      - name: Build release
+        run: cargo build --release
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # --- Docs ---
+      - name: Install docs dependencies
+        run: uv pip install --system -r requirements-docs.txt
+
+      - name: Build docs
+        run: mkdocs build --strict || mkdocs build  # --strict may fail until all pages exist
+
+      # --- Report ---
+      - name: Set up fixture venv
+        run: cd tests/fixtures/simple_project && uv venv --python 3.12 --clear && uv pip install pytest
+
+      # Benchmarks are slow — only run on schedule and workflow_dispatch, not on every push.
+      # The report still generates with placeholder data when bench results are absent.
+      - name: Set up benchmark environment
+        if: github.event_name != 'push'
+        run: bash bench/setup.sh
+
+      - name: Run benchmark (synth target, 1 run)
+        if: github.event_name != 'push'
+        run: bash bench/compare.sh synth --runs 1
+
+      # Vendor tests: run irradiate on real open-source Python libraries.
+      # Skipped on push to keep CI fast; report shows placeholders when file is absent.
+      - name: Run vendor tests
+        if: github.event_name != 'push'
+        run: bash scripts/run_vendor_tests.sh -o vendor_results.json
+
+      # Generate the report into site/report/ so it's a subpath of the docs site
+      - name: Generate report
+        run: uv run --python 3.12 scripts/generate_report.py -o site/report/index.html --vendor-results vendor_results.json
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

irradiate-0.1.0/.github/workflows/fuzz.yml

@@ -0,0 +1,72 @@
+name: Nightly Fuzz
+on:
+  schedule:
+    - cron: '0 4 * * *'  # 4am UTC daily
+  workflow_dispatch: {}  # manual trigger
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [fuzz_mutate_file, fuzz_parse_param_names, fuzz_generate_trampoline]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+      - run: cargo install cargo-fuzz
+      - name: Seed corpus
+        run: |
+          mkdir -p fuzz/corpus/${{ matrix.target }}
+          # corpus seeds are committed in fuzz/corpus/<target>/
+      - name: Run fuzzer (5 minutes)
+        id: fuzz
+        continue-on-error: true
+        run: |
+          cargo fuzz run ${{ matrix.target }} fuzz/corpus/${{ matrix.target }} -- -max_total_time=300 2>&1 | tee fuzz_output.txt
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+      - name: Check for crash
+        if: steps.fuzz.outcome == 'failure'
+        run: |
+          CRASH_FILE=$(find fuzz/artifacts/${{ matrix.target }} -name "crash-*" -o -name "oom-*" 2>/dev/null | head -1)
+          if [ -n "$CRASH_FILE" ]; then
+            echo "CRASH_INPUT=$(base64 < "$CRASH_FILE")" >> $GITHUB_ENV
+            echo "CRASH_FILE=$CRASH_FILE" >> $GITHUB_ENV
+          fi
+      - name: File GH issue for crash
+        if: steps.fuzz.outcome == 'failure' && env.CRASH_FILE != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const output = fs.readFileSync('fuzz_output.txt', 'utf8').slice(-3000);
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `Fuzz crash: ${{ matrix.target }}`,
+              body: [
+                '## Nightly fuzz found a crash',
+                '',
+                `**Target:** \`${{ matrix.target }}\``,
+                `**Date:** ${new Date().toISOString()}`,
+                `**Crash input (base64):** \`${process.env.CRASH_INPUT}\``,
+                '',
+                '### Output (last 3000 chars)',
+                '```',
+                output,
+                '```',
+                '',
+                '### Reproducing',
+                '```bash',
+                `echo "${process.env.CRASH_INPUT}" | base64 -d > crash_input`,
+                `cargo +nightly fuzz run ${{ matrix.target }} crash_input`,
+                '```',
+              ].join('\n'),
+              labels: ['fuzz', 'bug'],
+            });
+      - name: Upload corpus
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: corpus-${{ matrix.target }}
+          path: fuzz/corpus/${{ matrix.target }}/
+          retention-days: 7

irradiate-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build wheels (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - runner: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - runner: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+          - runner: macos-14
+            target: aarch64-apple-darwin
+          - runner: macos-14
+            target: x86_64-apple-darwin
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: "2_28"
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist/
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, sdist]
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

irradiate-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# irradiate runtime
+.irradiate/
+
+# Generated mutants in test fixtures
+tests/fixtures/simple_project/mutants/
+tests/fixtures/simple_project/.irradiate/
+mutants*
+
+# Vendor smoke test repos and results (downloaded at runtime)
+tests/vendor_repos/
+
+# Vendor (reference only, cloned separately)
+/vendor/
+
+# Hive
+.worktrees/
+.hive/queen-state.md
+
+# OS
+.DS_Store
+*.swp
+*.swo
+watch_*
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# Fuzzing — ignore runtime-generated corpus (hex-named) and artifacts; keep seed_* files
+fuzz/corpus/*/[0-9a-f]*
+fuzz/corpus/*/*.options
+fuzz/artifacts/
+fuzz/target/
+
+# Benchmarks
+bench/results/
+bench/.venv/
+bench/corpora/
+bench/targets/*/.mutmut-cache
+
+# Generated docs artifacts
+docs/artifacts/
+
+# Docs build
+.venv-docs/
+site/
+
+# Generated report
+/report/
+
+# uv
+uv.lock

irradiate-0.1.0/.hive/.gitignore

@@ -0,0 +1,3 @@
+# Ephemeral queen session files (regenerated each session)
+queen-state.md
+queen-instructions.md

irradiate-0.1.0/.hive/project-context.md

@@ -0,0 +1,73 @@
+# Project Context — irradiate
+
+## Overview
+Mutation testing tool for Python, written in Rust — spiritual successor to mutmut. Parses Python source with libcst, generates mutant variants via trampoline code injection, then runs pytest workers over Unix sockets to classify each mutant as killed/survived.
+
+## Architecture
+- **mutation.rs** — Parse Python via libcst-native, walk the CST to collect mutation points (binop swap, compop swap, boolop swap, name/number/string/lambda mutations, method swaps, assignment mutations). Each `Mutation` carries byte-span offsets within the function source.
+- **trampoline.rs** — Name-mangle functions (mutmut convention: `x_func` / `xǁClassǁmethod`), generate orig + variant defs + lookup dict + trampoline wrapper that dispatches via `irradiate_harness.active_mutant`.
+- **codegen.rs** — File-level codegen: strip original function defs, prepend trampoline runtime, append all trampoline arrangements. Produces `MutatedFile` with source + mutant name list.
+- **pipeline.rs** — Full pipeline orchestration: discover .py files → mutate (rayon parallel) → write to `mutants/` dir → optional stats collection → optional forced-fail validation → dispatch to worker pool → write `.meta` results → print report. Also implements `results` and `show` subcommands.
+- **orchestrator.rs** — Tokio-based worker pool: spawn N Python processes, accept Unix socket connections, dispatch `Run` messages, collect `Result`/`Error` messages, recycle workers after N mutants, respawn crashed workers.
+- **harness/** — Embedded Python package (`irradiate_harness`): `__init__.py` (active_mutant global, hit recording), `worker.py` (pytest plugin that intercepts `pytest_runtestloop` for IPC-driven test execution), `stats_plugin.py` (coverage collection via `--irradiate-stats`).
+
+Data flow: CLI → `pipeline::run` → `codegen::mutate_file` (parallel via rayon) → write mutated sources to `mutants/` → `stats::collect_stats` (single pytest run in stats mode) → build `WorkItem` list with targeted test IDs → `orchestrator::run_worker_pool` (tokio, Unix sockets) → Python workers run pytest items directly → results written to `.meta` JSON files.
+
+## Key Files
+- `src/main.rs` — CLI entrypoint (clap), subcommands: `run`, `results`, `show`
+- `src/pipeline.rs` — Full pipeline: mutate → stats → validate → test → report (~600 lines, the big one)
+- `src/mutation.rs` — Mutation engine: CST walking, operator tables, byte-span tracking (~1100 lines with tests)
+- `src/trampoline.rs` — Trampoline codegen: name mangling, wrapper generation, runtime dispatch code
+- `src/codegen.rs` — File-level mutation: strip originals, inject trampolines
+- `src/orchestrator.rs` — Tokio worker pool: spawn, dispatch, recycle, respawn
+- `src/protocol.rs` — IPC message types: `OrchestratorMessage`, `WorkerMessage`, `MutantResult`, `MutantStatus`
+- `src/harness.rs` — Extract embedded Python harness to `.irradiate/harness/`
+- `src/config.rs` — Load `[tool.mutmut]` from pyproject.toml
+- `src/stats.rs` — Stats collection: run pytest in stats mode, load/query results
+- `harness/__init__.py` — Python runtime: `active_mutant` global, `ProgrammaticFailException`, hit recording
+- `harness/worker.py` — Pytest worker: Unix socket IPC, direct item execution via `runtestprotocol`
+- `harness/stats_plugin.py` — Pytest plugin for per-test function coverage
+- `tests/e2e.sh` — End-to-end test: build, run on fixture, verify killed/survived counts, test `--isolate` flag
+
+## Build & Test
+- **Language**: Rust 2021 edition + Python 3.12 (harness)
+- **Package manager**: Cargo (Rust), uv (Python fixtures)
+- **Build**: `cargo build`
+- **Test**: `cargo check && cargo clippy -- -D warnings && cargo test && bash tests/e2e.sh`
+- **Lint**: `cargo clippy -- -D warnings`
+- **Format**: `cargo fmt` (Rust), `uvx ruff format` with line-length=144 (Python)
+- **Type check**: N/A (no mypy/pyright configured for harness)
+- **Pre-commit**: N/A (manual: must run check + clippy + test before every commit per CLAUDE.md)
+- **Quirks**: E2E tests require `cd tests/fixtures && uv venv && uv pip install pytest`. The e2e.sh creates venvs automatically if missing. Python harness files are embedded via `include_str!` at compile time — edits to `harness/*.py` require `cargo build` to take effect. Unix socket paths use `/tmp` to avoid macOS 104-byte path limit.
+
+## Conventions
+- Mutation naming follows mutmut: `x_func` (top-level), `xǁClassǁmethod` (class methods), `__mutmut_orig`/`__mutmut_N` suffixes
+- Mutant keys are module-qualified: `module.x_func__mutmut_1`
+- Results stored as JSON `.meta` files in `mutants/<module_path>.py.meta`
+- Tests are inline `#[cfg(test)] mod tests` in each Rust source file — no separate test directory for Rust
+- Python harness uses `# pragma: no mutate` to skip self-mutation of critical functions
+- Error handling via `anyhow::Result` throughout; `tracing` for structured logging
+- IPC protocol is newline-delimited JSON over Unix domain sockets
+- snake_case everywhere (Rust convention); serde `rename_all = "snake_case"` for JSON
+- Decorated Python functions are skipped (not mutated)
+- `NEVER_MUTATE_FUNCTIONS`: `__getattribute__`, `__setattr__`, `__new__`
+
+## Dependencies & Integration
+- **libcst (1.8.6)** — Rust port of Python's libcst; used for parsing Python source into CST for mutation point discovery. No-default-features (native parser only).
+- **tokio** — Async runtime for worker pool orchestration, Unix socket communication
+- **rayon** — Parallel mutation generation across source files
+- **clap 4** — CLI argument parsing with derive macros
+- **serde/serde_json** — JSON serialization for IPC protocol and .meta result files
+- **toml** — Parse pyproject.toml for `[tool.mutmut]` config
+- **pytest** — Test runner (invoked as subprocess); worker.py uses `_pytest.runner.runtestprotocol` for direct item execution
+- **proptest** (dev) — Property-based testing for mutation engine
+
+## Gotchas
+- Byte-span offsets in `Mutation` are relative to the function source string, not the full file. The cursor advances monotonically to handle duplicate tokens (e.g., two `+` operators).
+- `codegen.rs` strips original functions by indent level — if a function has inner functions at the same indent, they may be incorrectly stripped.
+- Worker recycling (`worker_recycle_after`) is critical for long runs: pytest accumulates state that eventually causes failures if workers aren't respawned.
+- The `--isolate` flag runs each mutant in a fresh subprocess (slower but avoids all state leakage); e2e tests verify it produces identical results to worker pool mode.
+- Config reads `[tool.mutmut]` (not `[tool.irradiate]`) for backward compatibility with mutmut.
+- `PYTHONPATH` construction in `pipeline.rs` must include harness dir, mutants dir, and project source parent for correct import resolution.
+- Stats mode (`active_mutant = "stats"`) records which functions each test calls; this is used to build targeted test lists per mutant, dramatically reducing run time.
+- Forced-fail validation runs a single mutant with `active_mutant = "fail"` to verify the trampoline wiring works before the full run.

irradiate-0.1.0/.hive/queen-context.md

@@ -0,0 +1,35 @@
+# Queen Context
+
+Persistent project knowledge accumulated across queen sessions.
+Update this file with architectural decisions, gotchas, and patterns.
+
+## Architecture Decisions
+
+### Import model (2025-03-18)
+PYTHONPATH shadowing replaced with MutantFinder import hook (sys.meta_path). The hook runs before sys.path is consulted, eliminating all three prior bugs (partial mutation, pytest config interference, sys.path[0] cwd shadowing). PYTHONPATH is now just `harness_dir:source_parent`. The hook is installed in harness/__init__.py when IRRADIATE_MUTANTS_DIR env var is set.
+
+### Class method trampolining (2025-03-18)
+codegen.rs now tracks class context during line walk. For class methods, the wrapper stays inside the class body (indented), while mangled orig/variants/dict go to module level. generate_trampoline() in trampoline.rs returns TrampolineOutput { module_code, wrapper_code, mutant_keys }.
+
+### conftest.py skip (2025-03-18)
+conftest.py is never mutated (is_mutatable_python_file() rejects it) and the import hook skips it too. conftest contains test configuration/fixtures, not application logic.
+
+## Infrastructure State
+
+### What exists
+- CI: .github/workflows/ci.yml (audit, build, clippy, test, coverage, e2e)
+- Forced-fail validation in pipeline.rs (runs after clean validation)
+- Bench infrastructure: bench/compare.sh (5 configs), bench/summarize.py, bench/setup.sh
+- Bench targets: simple_project (~10 mutants), my_lib (~30 mutants) — both too small for meaningful perf comparison
+- Import hook Python tests: 47 tests in tests/harness_tests/ (all pass with correct venv)
+
+### Vendor repo pattern
+Follow pycfg-rs convention: scripts/bootstrap-vendors.sh does shallow clones into bench/corpora/ (gitignored). Each vendor needs its own venv. Bench target configs in bench/targets/<name>.sh export PROJECT_DIR, PATHS_TO_MUTATE, TESTS_DIR, PYTHON.
+
+## Gotchas for Workers
+
+- Python harness files are embedded via include_str! — edits to harness/*.py require cargo build to take effect
+- bench/.venv has mutmut installed from vendor/mutmut (editable install)
+- /usr/bin/time -l is macOS-specific; Linux uses different format
+- irradiate reads [tool.mutmut] from pyproject.toml (not [tool.irradiate]) for backward compat
+- Bench compare.sh uses process substitution for /usr/bin/time capture — bash-specific

irradiate-0.1.0/.hive.toml

@@ -0,0 +1,6 @@
+[project]
+name = "irradiate"
+
+[hive]
+backend = "claude"
+merge_queue_enabled = true

irradiate-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  - repo: local
+    hooks:
+      - id: cargo-check
+        name: cargo check
+        entry: cargo check
+        language: system
+        pass_filenames: false
+        types: [rust]
+
+      - id: cargo-clippy
+        name: cargo clippy
+        entry: cargo clippy -- -D warnings
+        language: system
+        pass_filenames: false
+        types: [rust]
+
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt -- --check
+        language: system
+        pass_filenames: false
+        types: [rust]
+
+      - id: ruff-check
+        name: ruff check
+        entry: uvx ruff check harness/
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: ruff-format
+        name: ruff format
+        entry: uvx ruff format --check harness/
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: cargo-test
+        name: cargo test
+        entry: cargo test
+        language: system
+        pass_filenames: false
+        types: [rust]
+        stages: [pre-push]

irradiate-0.1.0/CLAUDE.md

@@ -0,0 +1,102 @@
+# irradiate
+
+Mutation testing for Python, written in Rust. Spiritual successor to mutmut.
+
+## Reference implementation
+
+mutmut source is at `vendor/mutmut/` for reference. Key files:
+
+- `vendor/mutmut/src/mutmut/__main__.py` — runner, config, orchestration (66KB, the big one)
+- `vendor/mutmut/src/mutmut/file_mutation.py` — mutation generation engine (libcst-based)
+- `vendor/mutmut/src/mutmut/node_mutation.py` — 18+ mutation operators
+- `vendor/mutmut/src/mutmut/trampoline_templates.py` — trampoline code generation and runtime dispatch
+- `vendor/mutmut/src/mutmut/code_coverage.py` — coverage integration
+- `vendor/mutmut/src/mutmut/type_checking.py` — type checker integration
+- `vendor/mutmut/e2e_projects/` — test projects (my_lib, config, type_checking, etc.)
+
+### mutmut naming conventions (we follow loosely)
+
+- Top-level function `foo()` → mangled as `x_foo`
+- Class method `Class.foo()` → mangled as `xǁClassǁfoo` (Unicode separator `ǁ` U+01C1)
+- Mutant variants: `x_foo__mutmut_orig`, `x_foo__mutmut_1`, `x_foo__mutmut_2`, ...
+- Mutant keys: `module.x_foo__mutmut_1`
+- Metadata files: `mutants/path/to/file.py.meta`
+- Runtime control: `MUTANT_UNDER_TEST` env var (mutmut) / `irradiate_harness.active_mutant` global (irradiate)
+
+### mutmut exit codes
+
+- `0` → survived, `1`/`3` → killed, `5`/`33` → no tests, `34` → skipped
+- `36`/`24`/`152`/`255` → timeout, `37` → type check caught, `-11`/`-9` → segfault
+
+## Building and testing
+
+```bash
+# Build
+cargo build
+
+# Check + lint (must pass before every commit)
+cargo check && cargo clippy -- -D warnings
+
+# Run unit tests
+cargo test
+
+# Run e2e tests (once e2e.sh exists)
+bash tests/e2e.sh
+
+# Full verification
+cargo check && cargo clippy -- -D warnings && cargo test && bash tests/e2e.sh
+```
+
+## Python environment
+
+The integration tests need Python with pytest. Set up with:
+```bash
+cd tests/fixtures && uv venv && uv pip install pytest
+```
+
+## Git hooks
+
+Install pre-commit hooks with:
+```bash
+bash scripts/install-hooks.sh
+```
+
+The hook runs `cargo fmt --check`, `cargo clippy -- -D warnings`, and `cargo test` before every commit.
+
+## Commit guidelines
+
+- Run `cargo check && cargo clippy -- -D warnings && cargo test` before every commit
+- One logical change per commit
+- Keep commits small and incremental — commit after completing each module/feature
+- Do not note that PRs were authored by Claude Code
+
+## Project structure
+
+```
+irradiate/
+├── Cargo.toml
+├── CLAUDE.md
+├── src/
+│   ├── main.rs             # binary entrypoint
+│   ├── lib.rs              # library root
+│   ├── harness.rs          # extract embedded Python harness at runtime
+│   ├── orchestrator.rs     # tokio worker pool manager
+│   ├── protocol.rs         # IPC message types
+│   └── stats.rs            # stats collection
+├── harness/                # Python harness files (embedded via include_str!)
+│   ├── __init__.py         # irradiate_harness package (active_mutant global, etc.)
+│   ├── worker.py           # pytest worker process
+│   └── stats_plugin.py     # pytest plugin for stats collection
+├── tests/
+│   ├── worker_pool_integration.rs  # integration tests (real pytest workers)
+│   ├── fixtures/            # minimal Python projects for testing
+│   └── e2e.sh              # end-to-end test script
+├── vendor/
+│   └── mutmut/             # reference implementation (git clone, not modified)
+└── docs/
+    └── design.md           # architecture, design rationale, and execution model
+```
+
+## Design docs
+
+- `docs/design.md` — full architecture and design rationale