# muhar

> muhar is a mutation-testing harness: it plants named faults in source files, proves each edit landed, runs your test suite, and reports CAUGHT, NOT_CAUGHT or COULD_NOT_MUTATE per fault. A run whose baseline is red or whose positive control is not caught is discarded with exit 2, never reported as clean.

Every page below has a plain-Markdown twin at the same path with a .md extension. The spec file format has a JSON Schema at https://muhar.assay.guide/schema/spec.v1.json.

## Start

- [Overview](https://muhar.assay.guide/index.md): muhar plants named faults in your source, proves each edit landed on disk, runs your test suite, and reports CAUGHT, NOT_CAUGHT or COULD_NOT_MUTATE per fault. A broken harness exits 2 and is never reported as clean.
- [Install](https://muhar.assay.guide/install.md): Install muhar from a release bundle with checksum verification, build it from source with Go 1.25 or later, or run it without installing. Requirements per platform.
- [Worked example](https://muhar.assay.guide/getting-started.md): From an empty directory to a NOT_CAUGHT guard, the test that fixes it, and the runs muhar refuses to trust. Every output on this page was captured from a real run.

## Reference

- [Concepts](https://muhar.assay.guide/concepts.md): Guard, mutation, positive control, baseline, the three verdicts, the proven-landed guarantee, and why exit status 2 is never a clean result.
- [Spec reference](https://muhar.assay.guide/spec.md): Every field of the muhar mutation spec JSON, how file paths resolve, exact-match and first-occurrence semantics, line endings, validation errors and the COULD_NOT_MUTATE reasons.
- [CLI reference](https://muhar.assay.guide/cli.md): muhar's flags (-spec, -j, -shard), the -j 0 cap and why, the shard partition, what goes to stdout and stderr, and the environment the suite runs in.
- [Output and exit codes](https://muhar.assay.guide/output.md): The exact format of every line muhar prints on stdout, the HARNESS BROKEN reasons, the exit status table, and a shell gate that fails on a broken harness, a missing test or a mutation that did not land.

## Guides

- [How a run works](https://muhar.assay.guide/internals.md): What muhar does step by step — spec checks, the per-run Go build cache, baseline and control, planting and proving each edit, worker copies and go.mod replace handling, signals and cleanup, timeouts, and what a run costs.
- [Writing good mutants](https://muhar.assay.guide/writing-mutants.md): How to choose guards, write a control that proves the harness, pick old text that survives edits, and write mutants for Go, JSON configuration, shell scripts and YAML workflows.
- [CI integration](https://muhar.assay.guide/ci.md): Run muhar as a CI gate - install a pinned release, fail on any non-zero exit, grep the Totals line, split a spec across sharded matrix legs, size -j for the runner, and keep the report as an artifact.

## Context

- [Comparison](https://muhar.assay.guide/comparison.md): How muhar compares with Gremlins, go-mutesting, Stryker, PIT, mutmut and cargo-mutants - what each does better, what muhar does differently, and when to use which.
- [FAQ](https://muhar.assay.guide/faq.md): Answers to common questions about muhar - exit codes, COULD_NOT_MUTATE, non-compiling mutants, interrupted runs, parallel runs, non-Go projects, and use by AI agents.
- [Roadmap](https://muhar.assay.guide/roadmap.md): What is planned for muhar and not shipped yet - faster runs, coverage-guided test selection, a one-line install, a reusable CI action, an unviable verdict and per-mutant timeout, diff-scoped runs - and the known issues being fixed.

## Optional

- [Spec JSON Schema](https://muhar.assay.guide/schema/spec.v1.json): machine-readable shape of a mutations.json spec file
- [Source code](https://github.com/medici-finance/assay/tree/main/tools/desk/cmd/muhar): the muhar command in the medici-finance/assay repository
- [assay.guide](https://assay.guide/): the Assay methodology muhar ships with