init mutation-testing skill (#140)

* init mutation-testing skill

* fix metadata

* init codex symlink

* polish according to review feedback

---------

Co-authored-by: Dan Guido <dan@trailofbits.com>

Author: bohendo

.claude-plugin/marketplace.json

@@ -145,6 +145,17 @@
       },
       "source": "./plugins/entry-point-analyzer"
     },
+    {
+      "name": "mutation-testing",
+      "version": "1.0.0",
+      "description": "Configures mewt or muton mutation testing campaigns — scopes targets, tunes timeouts, and optimizes long-running runs. Use when the user mentions mewt, muton, mutation testing, or wants to configure or optimize a mutation testing campaign.",
+      "author": {
+        "name": "Trail of Bits",
+        "email": "opensource@trailofbits.com",
+        "url": "https://github.com/trailofbits"
+      },
+      "source": "./plugins/mutation-testing"
+    },
     {
       "name": "property-based-testing",
       "description": "Property-based testing guidance for multiple languages and smart contracts",

.codex/skills/mutation-testing

@@ -0,0 +1 @@
+../../plugins/mutation-testing/skills/mutation-testing

CODEOWNERS

@@ -23,6 +23,7 @@
 /plugins/insecure-defaults/ @dariushoule @dguido
 /plugins/let-fate-decide/ @tob-scott-a @dguido
 /plugins/modern-python/ @Ninja3047 @dguido
+/plugins/mutation-testing/ @bohendo @dguido
 /plugins/property-based-testing/ @hbrodin @dguido
 /plugins/seatbelt-sandboxer/ @smichaels-tob @dguido
 /plugins/skill-improver/ @GrosQuildu @dguido

README.md

@@ -80,6 +80,7 @@ cd /path/to/parent  # e.g., if repo is at ~/projects/skills, be in ~/projects
 | Plugin | Description |
 |--------|-------------|
 | [constant-time-analysis](plugins/constant-time-analysis/) | Detect compiler-induced timing side-channels in cryptographic code |
+| [mutation-testing](plugins/mutation-testing/) | Configure mewt/muton mutation testing campaigns — scope targets, tune timeouts, optimize long runs |
 | [property-based-testing](plugins/property-based-testing/) | Property-based testing guidance for multiple languages and smart contracts |
 | [spec-to-code-compliance](plugins/spec-to-code-compliance/) | Specification-to-code compliance checker for blockchain audits |
 | [zeroize-audit](plugins/zeroize-audit/) | Detect missing or compiler-eliminated zeroization of secrets in C/C++ and Rust |

plugins/mutation-testing/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "mutation-testing",
+  "version": "1.0.0",
+  "description": "Configures mewt or muton mutation testing campaigns — scopes targets, tunes timeouts, and optimizes long-running runs. Use when the user mentions mewt, muton, mutation testing, or wants to configure or optimize a mutation testing campaign.",
+  "author": {
+    "name": "Trail of Bits",
+    "email": "opensource@trailofbits.com",
+    "url": "https://github.com/trailofbits"
+  }
+}

plugins/mutation-testing/README.md

@@ -0,0 +1,43 @@
+# Mutation Testing — Campaign Configuration (mewt/muton)
+
+Helps configure [mewt](https://github.com/trailofbits/mewt) or [muton](https://github.com/trailofbits/muton) mutation testing campaigns — scoping targets, tuning timeouts, and optimizing long-running runs so you can execute `mewt run` or `muton run` with confidence.
+
+> **Note**: muton and mewt share identical interfaces but target different languages — mewt for general-purpose languages, muton for TON smart contracts (Tact, Tolk, FunC). All commands and configuration patterns in this plugin apply to both tools. File names change accordingly: `mewt.toml` → `muton.toml`, `mewt.sqlite` → `muton.sqlite`.
+
+## What It Does
+
+Walks through a 5-phase configuration workflow:
+
+1. **Initialize and validate targets** — run `mewt init`, review auto-generated config, fix include/ignore patterns
+2. **Generate mutants and assess scope** — count mutants, time the test command, estimate campaign duration
+3. **Decide on optimization** — choose between full run, targeted components, high/medium severity only, or two-phase campaign
+4. **Validate test command and timeout** — verify the command works; set manual timeout for recompilation-heavy languages (Solidity/Foundry, heavy C++)
+5. **Final validation checklist** — confirm config, mutant count, target selection, and timeout before running
+
+## When to Use
+
+- Setting up a new mutation testing campaign
+- Optimizing a campaign that would take too long to run
+- Diagnosing why no mutants are generated or why the test command fails
+
+## Prerequisites
+
+- [mewt](https://github.com/trailofbits/mewt) v3.0.0+ or [muton](https://github.com/trailofbits/muton) v3.0.0+ installed
+- A test suite runnable from the command line
+- Source code in a supported language:
+  - **mewt**: Rust, Solidity, Go, TypeScript, JavaScript
+  - **muton**: Tact, Tolk, FunC (TON smart contract languages)
+
+## Example Usage
+
+```
+User: "Help me set up mewt for this Solidity project"
+User: "Configure muton for this FunC codebase"
+User: "My mewt campaign would take 30 hours — how do I optimize it?"
+→ Guides through configuration, scope assessment, and optimization
+```
+
+## References
+
+- [mewt GitHub Repository](https://github.com/trailofbits/mewt)
+- [Use mutation testing to find the bugs your tests don't catch](https://blog.trailofbits.com/2025/09/18/use-mutation-testing-to-find-the-bugs-your-tests-dont-catch/) — Trail of Bits blog post

plugins/mutation-testing/skills/mutation-testing/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mutation-testing
+description: "Configures mewt or muton mutation testing campaigns — scopes targets, tunes timeouts, and optimizes long-running runs. Use when the user mentions mewt, muton, mutation testing, or wants to configure or optimize a mutation testing campaign."
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+---
+
+# Mutation Testing — Campaign Configuration (mewt/muton)
+
+> **Note**: muton and mewt share identical interfaces but target different languages — mewt for general-purpose languages (Rust, Solidity, Go, TypeScript, JavaScript), muton for TON smart contracts (Tact, Tolk, FunC). All examples use `mewt` commands, but they work exactly the same with `muton`. File names change accordingly: `mewt.toml` → `muton.toml`, `mewt.sqlite` → `muton.sqlite`.
+
+## When to Use
+
+Use this skill when the user:
+- Mentions "mewt", "muton", or "mutation testing"
+- Needs to configure or optimize a mutation testing campaign
+- Wants to run `mewt run` and needs help getting set up first
+
+## When NOT to Use
+
+Do not use this skill when the user:
+- Wants to analyze or report on completed campaign results
+- Asks about tests or coverage without mentioning mutation testing
+
+---
+
+## Quick Start
+
+Load [workflows/configuration.md](workflows/configuration.md) — a 5-phase guide from `mewt init` to a validated, ready-to-run campaign.
+
+**General question or unfamiliar command?**
+Run `mewt --help` or `mewt <subcommand> --help`, then assist.
+
+---
+
+## Reference Index
+
+| File | Content |
+|------|---------|
+| [workflows/configuration.md](workflows/configuration.md) | 5-phase guide: init, scope, optimize, validate, run |
+| [references/optimization-strategies.md](references/optimization-strategies.md) | Per-file targeting, two-phase campaigns, mutation type filtering |
+
+---
+
+## Essential Commands
+
+```bash
+# Initialize and mutate
+mewt init                    # Create mewt.toml and mewt.sqlite
+mewt mutate [paths]          # Generate mutants without running tests
+mewt run [paths]             # Run the full campaign
+
+# Inspect configuration and scope
+mewt print config            # View effective configuration
+mewt print targets           # Table of all targeted files
+mewt print mutations --language [lang]  # Available mutation types
+mewt status                  # Mutant count and per-file breakdown
+
+# Investigate specific mutants
+mewt print mutants --target [path]   # All mutants for a file
+mewt print mutants --severity high   # Filter by severity
+mewt print mutant --id [id]          # View mutated code diff
+mewt test --ids [ids]                # Re-test specific mutants
+```
+
+---
+
+## What Results Mean
+
+- **Caught/TestFail**: Tests detected the mutation (good)
+- **Uncaught**: Mutation survived — indicates untested logic
+- **Timeout**: Tests took too long, inconclusive
+- **Skipped**: A more severe mutant already failed on the same line