# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with the laundromatic repository.

## Project Overview

**Laundromatic** is a red team / adversarial testing toolkit for deepfake detection benchmarking. It applies anti-forensic transformations to images, audio, and video to test the robustness of detection systems.

**This is legitimate security research software** supporting:
- UK Home Office Deepfake Detection Challenge (C581.2)
- Detection system vendor benchmarking
- Security research and red team exercises

## Tech Stack

- **Python**: 3.12+
- **Package Manager**: UV (not pip, not Poetry)
- **CLI Framework**: Typer
- **Code Quality**: ruff (lint + format), mypy (strict)
- **Testing**: pytest with pytest-cov
- **CI/CD**: GitHub Actions

## Project Structure

```
laundromatic/              # repo root
├── laundromatic/          # package (flat layout, no src/)
│   ├── __init__.py
│   ├── py.typed
│   ├── cli/               # Typer CLI
│   │   ├── __init__.py
│   │   ├── __main__.py
│   │   ├── image.py
│   │   ├── audio.py
│   │   ├── video.py
│   │   └── batch.py
│   ├── transforms/
│   │   ├── image/         # 15 image transforms
│   │   ├── audio/         # 11 audio transforms
│   │   └── video/         # 4 video transforms
│   ├── utils/
│   └── io/
├── tests/
├── docs/
├── pyproject.toml
└── uv.lock
```

## Key Commands

```bash
# Install dependencies
uv sync

# Run CLI
uv run laundromatic --help
uv run laundromatic image blur input.jpg output.jpg
uv run laundromatic batch transform ./input ./output --percent 30

# Code quality
uv run ruff check .
uv run ruff format .
uv run mypy .

# Testing
uv run pytest
uv run pytest -v --cov

# Pre-commit
uv run pre-commit install
uv run pre-commit run --all-files
```

## Development Conventions

### Do
- Use UV for all Python operations
- Run `uv run ruff check . --fix` before committing
- Follow the story specifications in the planning docs
- Keep functions typed with complete type hints
- Write docstrings in Google style

### Don't
- Use pip directly - use `uv run pip` or `uv sync`
- Create Poetry files - use pyproject.toml with UV
- Add features beyond story scope
- Commit without running ruff and tests
- Use `git commit` unless explicitly asked

## CLI Structure

```
laundromatic
├── image          # Image transforms
│   ├── blur
│   ├── noise
│   ├── compress
│   └── ...
├── audio          # Audio transforms
│   ├── compress
│   ├── noise
│   └── ...
├── video          # Video transforms
│   ├── blur
│   ├── compress
│   └── ...
└── batch          # Batch operations
    ├── transform
    └── sample
```

## Migration Context

This codebase is being migrated from `/Users/john/code/ace/c581/c581-benchmarking/antiforensics/`.

**Planning Documents**:
- Stories: `/Users/john/code/ace/c581/c581-benchmarking/notes/2026-01-22-laundromatic/stories.md`
- Context prompts: `/Users/john/code/ace/c581/c581-benchmarking/notes/2026-01-22-laundromatic/context-prompts.md`

**Import Path Changes**:
```python
# OLD
from antiforensics.transforms.image import blur

# NEW
from laundromatic.transforms.image import blur
```

## Reference Repository

For Python project patterns (pyproject.toml, CI, pre-commit), reference:
`/Users/john/code/ace/c766/c766-seacover-core`

## Testing Strategy

- Smoke tests: Verify transforms don't crash
- Unit tests: Test individual functions
- CLI tests: Use Typer's CliRunner
- Coverage target: 80% (Phase 1), 90% (Phase 4)

```python
# Example test pattern
@pytest.mark.parametrize("transform", ["blur", "noise", "compress"])
def test_image_transform_smoke(transform, sample_image, tmp_path):
    ...
```

## Important Notes

1. **Flat layout**: Package code in `laundromatic/` at repo root (not src-layout)
2. **Entry point**: `laundromatic = "laundromatic.cli:app"` in pyproject.toml
3. **Type hints**: Required on all public functions (mypy strict)
4. **Docstrings**: Google style, required for public API
5. **British English**: Use -ise, -our, -re spellings throughout
