[akurkar07]

Summary

Documents the M4 mutant catalogue as it actually exists on main and adds an acceptance test so family coverage cannot silently regress.

• docs/methodology.md: new ## Controlled defect injection section (the README section moved here under Docs: Restructure the README into status, quickstart and links to the V1 design spec #96's 300-line README rule). It defines "operator" as a defect family realised by curated mutant directories, gives the 10-family table with a Committed mutants column (task/id per family; heat1d planned via M4-Heat: Add boundary, discretisation and stability mutants for heat1d #90), and replaces the old "three checks" + property-test sentence with the four checks validate_reference/validate_mutant actually enforce.
• docs/experiment-authoring.md "Add a mutation": MutationDefinition manifest field table (M4-Registry: Define the mutant manifest and discover every task's mutants #85), operator definition, numbered four checks (M4-Validation: Prove each mutant passes public tests and fails its declared scientific gate #86), scripts/validate_mutants.py usage and fail-closed behaviour (M4-CI: Make validate_mutants.py validate every mutant and fail closed #88), and a note on what to update when adding a mutant.
• README.md: the status row now says 11 package mutants cover all 10 families and links the catalogue; the "does not provide yet" line says heat1d only (kepler gained mutants in M4-Kepler: Add unit-error and non-conservative mutants for the two-body task #172).
• tests/acceptance/test_mutation_coverage.py: uses discover_mutants(Path("tasks")) to assert that every MutationFamily has a package mutant. INFEASIBLE_FAMILIES is an explicit, commented, currently empty exception dict whose entries must cite an issue. Two more checks: a test fails if an exempted family gains a mutant, and every package mutant must appear in the experiment-authoring catalogue table.
• CHANGELOG.md: Unreleased entry.

Closes #93

Proposed milestone description (maintainer edit, M4)

Mutation registry, 10 defect families realised as curated per-task mutants, validation pipeline. Each mutant passes the task's public tests and fails its declared scientific gate.

Acceptance criteria

• docs/experiment-authoring.md "Add a mutation" documents the M4-Registry: Define the mutant manifest and discover every task's mutants #85 manifest fields, the operator definition, the four M4-Validation: Prove each mutant passes public tests and fails its declared scientific gate #86 checks and scripts/validate_mutants.py (M4-CI: Make validate_mutants.py validate every mutant and fail closed #88). Checked against schema.MutationDefinition, mutations/validation.py, the Task Validation workflow and the Makefile.
• The controlled defect injection section says 10 families and has a committed-mutants column ("planned" for heat1d). The property-test sentence is replaced with the real checks. The section lives in docs/methodology.md because Docs: Restructure the README into status, quickstart and links to the V1 design spec #96 moved it out of the README, and the README status line was kept consistent.
• tests/acceptance/test_mutation_coverage.py passes. Negative check: temporarily removing wave1d/unstable-time-recurrence made the stability_error case fail with the uncovered-family message.
• git grep -n "9 defect\|9 operators" returns nothing.
• uv run pytest -q passes (see below).

Note: heat1d mutants (#90) are still open. All 10 families are already covered by oscillator, kepler and wave1d mutants, so this does not block the issue.

Test output

• uv run pytest tests/acceptance/test_mutation_coverage.py tests/unit/test_docs_index.py -q: 15 passed
• uv run pytest -q: 619 passed, 3 skipped (Docker-backed tests ran)
• Task suites: oscillator 19 passed, kepler 20 passed, heat1d 20 passed, wave1d 23 passed
• uv run ruff check .: clean. uv run ruff format --check src tests tasks scripts: 128 files already formatted. uv run mypy src: no issues in 32 source files.

Written by Devin