pi-dev-team 0.2.0

package/skills/stryker-xunit-v2-shim/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: stryker-xunit-v2-shim
+description: Build a xunit.v2 Stryker shim so Stryker.NET produces a valid mutation score for a xunit.v3 test project. Stryker.NET cannot observe mutant kills through xunit.v3 (it runs on the Microsoft Testing Platform), so a normal run reports a false near-zero score with almost every mutant reported Survived. Use this BEFORE running Stryker whenever the target .NET test project references xunit.v3 — including when mutation is enabled via /test-improve or /mutation-testing, or you are about to run dotnet-stryker — and as a rescue when a run already reported ~0% or everything Survived or the user says the score looks suspiciously low. When Stryker and xunit.v3 both appear, build the shim first.
+role: worker
+user-invocable: true
+---
+
+# Stryker xunit.v2 Shim
+
+Role: worker. Builds measurement scaffolding and does not modify the tests it
+measures.
+
+## Why this exists
+
+Stryker.NET (through at least 4.15/4.16) **cannot observe mutant kills through
+xunit.v3**. xunit.v3 runs on the Microsoft Testing Platform (MTP), and Stryker's
+per-test coverage/kill mapping doesn't work across it (stryker-net issues 3237,
+3629, 3094). The run completes and the initial test pass even succeeds, so the
+failure is **silent** — the only symptom is the score: near-zero, with almost
+every mutant reported *Survived* (e.g. `0.13% — 3 killed / 7,685 survived`). That
+is the **observation-failure signature**, not a real result.
+
+The fix is a **shim**: a second test project that recompiles the *same test source
+files* under xunit.v2 (classic VSTest), which Stryker observes correctly. No test
+is rewritten — the shim **links** the existing `.cs` files, so there is one source
+of truth. Stryker is then run **from the shim directory** in project mode.
+
+[`references/shim-howto.md`](references/shim-howto.md) has the full reference build
+and any edge case not covered here.
+
+## Version scope — this whole skill is a < 5.0.0 workaround
+
+Everything below applies to **Stryker.NET < 5.0.0**. Starting at **5.0.0**
+([stryker-net#3752](https://github.com/stryker-mutator/stryker-net/issues/3752)),
+`-t mtp` + `coverage-analysis: perTest` observes mutant kills through xunit.v3
+directly — no shim, no v3-only-construct porting, no operator gate. See
+[`csharp-stryker-net.md`](../mutation-testing/references/languages/csharp-stryker-net.md)
+for the >= 5.0.0 command and its `concurrency: 1` caveat
+([stryker-net#3832](https://github.com/stryker-mutator/stryker-net/issues/3832),
+tracked for removal in [#2192](https://github.com/bdfinst/agentic-dev-team/issues/2192)).
+`stryker_xunit_shim_guard.py` detects the installed version
+(`hooks/mutation_adapters/stryker_net.py::stryker_net_version()`) and
+silent-passes on >= 5.0.0 — this skill's Step 1a operator gate is never
+reached on a known >= 5.0.0 install. An undetermined version fails closed to
+the < 5.0.0 behavior this skill documents.
+
+## Scope — one path, not the only one
+
+The shim is the path that keeps the **mutant-kill loop** viable on xunit.v3 **below 5.0.0**, because it restores per-test coverage (fast covering-subset per mutant). It is not mandatory for every xunit.v3 run. Within `mutation-kill` the shim-first feasibility gate ([#1158](https://github.com/bdfinst/agentic-dev-team/issues/1158)) decides per run: build the shim and probe under `perTest`; if per-test capture works and a round fits the budget, enter the loop; otherwise **degrade** to the no-shim floor — the real v3 suite via `-t mtp` + `coverage-analysis: off` (a real but slow, whole-suite-per-mutant single advisory pass; see [`csharp-stryker-net.md`](../mutation-testing/references/languages/csharp-stryker-net.md)). Before building, [`xunit_v3_feature_detector.py`](../mutation-testing/scripts/xunit_v3_feature_detector.py) classifies the shim-breaking v3-only constructs for the always-ask operator gate in Step 1a — enforced by the guard hook, which stays blocked until the operator's choice is recorded ([#1791](https://github.com/bdfinst/agentic-dev-team/issues/1791)). On `exclude`, the guard passes their selections to `generate_shim.py --compile-exclude` itself.
+
+## When to build it
+
+Detection is one check: a test `.csproj` contains `Include="xunit.v3"`. Build the
+shim **proactively, before the first Stryker run** — because the failure is silent
+(the run succeeds and the score is bogus), waiting for the symptom wastes a full,
+possibly hours-long run. As a backstop the `stryker_xunit_shim_guard.py` PreToolUse
+hook auto-scaffolds the shim (and reports what it wrote) when you run
+`dotnet-stryker` against a xunit.v3 project whose sources are clean, then blocks so
+you re-run from the shim dir; when the sources are **not** clean it presents the
+Step 1a operator gate instead of scaffolding. Build proactively rather than relying
+on the interception. (The guard **exempts** an explicit `-t mtp` run — the no-shim floor — so it is not forced into a shim; see the Scope section.) Within `mutation-kill` the feasibility gate may still degrade to that floor after the shim is built and probed.
+
+One precondition decides whether the shim is cheap: source compatibility with
+xunit.v2. `[Fact]`, `[Theory]`, `[InlineData]`, `TheoryData<>`, `MemberData`,
+`ClassData`, and `Assert.*` are source-identical between v2 and v3, so a plain
+suite ports in minutes. `AutoFixture.Xunit3` `[AutoData]`/`[InlineAutoData]` are
+**not** v2-compatible. The Step 1 scope probe quantifies how much of that a suite
+has; when there is any, Step 1a's operator gate decides what to do about it —
+"say so and stop" is not yours to choose, it is one of four options the operator
+picks between.
+
+## Canonical invocations — copy these, don't improvise
+
+Every command below is written to run **from the repository root** unless it says
+otherwise. Guessing at the working directory or at a flag that doesn't exist is
+the single biggest source of retried commands here ([#1777](https://github.com/bdfinst/agentic-dev-team/issues/1777)), so paste these and
+substitute only `<TestProject>`.
+
+```bash
+# Detect (repo root) — a test .csproj referencing xunit.v3 is the whole check
+git grep -l 'Include="xunit.v3"' -- '*.csproj'
+
+# Scope probe (repo root) — every hit is a file the operator gate will ask about
+git grep -n 'AutoFixture.Xunit3\|\[AutoData\|InlineAutoData\|AutoMoqData\|MemberAutoData' -- '*.cs'
+git grep -n 'TestContext\|Assert.Skip\|Assert.Multiple\|Assert.Equivalent\|ValueTask InitializeAsync' -- '*.cs'
+
+# Green baseline (repo root) — expect the SAME test count as the real project, 0 failed
+dotnet build tests/<TestProject>.Mutation -c Release
+dotnet test  tests/<TestProject>.Mutation -c Release --no-build
+
+# Mutation run — the ONLY correct form: from the shim dir, no arguments
+cd tests/<TestProject>.Mutation
+dotnet-stryker
+
+# No-shim floor (from the REAL test project dir) — set "coverage-analysis": "off"
+# in stryker-config.json first; it is config-file-only, there is no CLI flag
+cd tests/<TestProject>
+dotnet-stryker -t mtp
+```
+
+Three invocations that look right, fail, and get retried:
+
+| Don't | Do instead | Why |
+|---|---|---|
+| `dotnet-stryker` at the repo root | `cd tests/<TestProject>.Mutation && dotnet-stryker` | A root run auto-detects the `.sln`, enters solution mode, and binds to the real xunit.v3 project → false ~0% |
+| `dotnet-stryker --solution ../../App.sln` (or a `SolutionPath` in the shim's config) | omit it entirely — `test-projects` in the shim's `stryker-config.json` is the selection | With both set Stryker enumerates the solution and prefers the v3 project over the shim (the SolutionPath trap, [#557](https://github.com/bdfinst/agentic-dev-team/issues/557)) |
+| `dotnet-stryker --coverage-analysis off` | set `"coverage-analysis"` in `stryker-config.json` | `coverage-analysis` is **config-file-only** in Stryker.NET 4.15 — there is no CLI flag, so the run dies on an unknown option |
+
+Shim *selection* is not a command-line argument at all: it is the cwd having no
+`.sln` (project mode) plus the `test-projects` entry the generator wrote. If a
+run reports the observation-failure signature from a shim directory, check those
+two before reaching for a flag.
+
+## Workflow
+
+### Read before editing
+
+Before editing an artifact this workflow has already produced, read it first — each of these only exists once the workflow has reached the step that creates it, so don't expect all three on the proactive, before-the-first-run path:
+
+- the mutant-survivors report (`StrykerOutput/<timestamp>/reports/mutation-report.json`) — once a Stryker run has completed
+- the shim config (`stryker-config.json`) — once Step 2 has created it
+- the step files (the shim's linked test source files) — once they exist on disk
+
+**Converged-state check.** Compare each file's current content against the
+target state described in the step you're about to run before editing it.
+If a file already matches its target state, skip re-editing it — do not
+overwrite a file that has already converged.
+
+### Step 1 — Scope probe (decide whether the shim is cheap)
+
+Run against the branch under test to find v3-only usage that would need porting:
+
+```bash
+# v3-incompatible attribute usage in test sources
+git grep -l "AutoFixture.Xunit3\|\[AutoData\|InlineAutoData\|AutoMoqData\|MemberAutoData" -- 'tests/**/*.cs'
+# other v3-only APIs
+git grep -l "TestContext\|Assert.Skip\|Assert.Multiple\|IAsyncLifetime\|Assert.Equivalent" -- 'tests/**/*.cs'
+```
+
+Each hit is a file the operator gate below will ask about. **Zero hits → the shim
+builds unattended, proceed to Step 2.** Any hits → Step 1a; do not decide for the
+operator, and in particular do not quietly conclude the approach "isn't a good
+fit" — that is one of four options, and it is theirs to pick.
+
+### Step 1a — Operator gate (always-ask; you cannot skip it)
+
+When the probe finds shim-breaking constructs, the operator chooses how to
+proceed. This is enforced, not advisory: `stryker_xunit_shim_guard.py` blocks
+every `dotnet-stryker` invocation against that project until a choice is
+**recorded**, so paraphrasing the gate or picking on the operator's behalf does
+not get the run through ([#1791](https://github.com/bdfinst/agentic-dev-team/issues/1791)).
+
+The block body is the question, already assembled: the per-construct breakdown
+from [`xunit_v3_feature_detector.py`](../mutation-testing/scripts/xunit_v3_feature_detector.py) (which construct, translatable or
+not, coverage-bearing or neutral, with file and line), the four options with
+their tradeoffs, and the exact `record` command carrying this blocker set's
+fingerprint. Present the four options to the operator with `AskUserQuestion`,
+then run the printed command verbatim — the fingerprint is per-blocker-set, so
+don't reuse one from an earlier run.
+
+| Choice | What happens next |
+|---|---|
+| `port` | Rewrite the flagged constructs to v2-compatible forms (Step 3). The guard auto-scaffolds once the sources are clean. |
+| `exclude` | The guard scaffolds with `--compile-exclude` on the flagged files. They stay **unmeasured** — their mutants report as survivors. |
+| `skip` | Deactivate just the offending tests, then re-run. Clears the gate **only** where the deactivation removes the construct itself (`[Fact(Explicit = true)]` → `[Fact(Skip = "…")]`); a construct in a test body or on a data attribute stays in the source the shim compiles, so those need `port` or `exclude`. Undo at teardown. |
+| `degrade` | Skip the shim; run the no-shim floor (`-t mtp`, `coverage-analysis: off`) for one slow advisory pass. Only relevant below 5.0.0 — this whole gate is bypassed on a known >= 5.0.0 install (see Version scope above). |
+
+The fingerprint is **mandatory** — it is what scopes a decision to the blockers
+the operator actually saw. Add a new blocking file after they answered and the
+gate **re-asks**. A reply matching none of the four is re-asked with the same
+four; never default or guess.
+
+### Step 2 — Scaffold the shim project
+
+Use the bundled script — it reads the real test `.csproj` and writes the shim
+`.csproj` (mirroring every non-xunit `PackageReference` verbatim, swapping in the
+xunit.v2 stack, setting `RootNamespace`/`AssemblyName`, adding the linked-`Compile`
+glob and the product `ProjectReference`) plus a `stryker-config.json`:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/stryker-xunit-v2-shim/scripts/generate_shim.py" tests/<TestProject>/<TestProject>.csproj \
+  --mutate-exclude '**/gRPC/**/*.cs' --mutate-exclude '**/Caching/**/*.cs'
+```
+
+It creates `tests/<TestProject>.Mutation/` beside the real project. Pass
+`--mutate-exclude` for each product folder that's genuinely out of mutation scope
+(generated code, gRPC stubs, etc.); omit if none.
+
+Why these choices matter, so you can fix the file by hand if the script's
+heuristics miss something in an unusual `.csproj`:
+
+- **`RootNamespace` must equal the real project's root namespace** — the linked
+  sources resolve the same types, so a mismatch breaks compilation.
+- **`AssemblyName` must differ** (`.Mutation`) so both projects coexist.
+- **Non-xunit package versions must match exactly** — a version drift causes
+  compile errors in the linked sources.
+- **Keep the shim out of the `.sln`** (see Step 4 — this is what forces project
+  mode). Do not `dotnet sln add` it.
+
+### Step 3 — Port v3-only constructs (only files Step 1 flagged)
+
+Rewrite v3-only APIs to behavior-equivalent v2-compatible forms, **in the real
+test project's sources** (the shim links those same files, so one edit satisfies
+both). Verify each replacement still compiles under v3 too.
+
+| v3-only | v2-compatible replacement |
+|---|---|
+| `TestContext.Current.CancellationToken` | `CancellationToken.None` (token was never cancelled for a passing test) |
+| `[AutoData]` / `[InlineAutoData]` | manual `new Fixture()` in the body, or `[Theory]` + `[InlineData]` — heavier; avoid the shim if pervasive |
+| `Assert.Skip(...)` | `[Fact(Skip="…")]` or a guard-and-return |
+
+### Step 3a — Grant internals access
+
+If the product exposes internals to the real test assembly via
+`InternalsVisibleTo`, add the shim assembly too (its tests exercise `internal`
+types):
+
+```csharp
+[assembly: System.Runtime.CompilerServices.InternalsVisibleTo("<TestProject>.Mutation")]
+```
+
+### Step 4 — Run Stryker FROM the shim directory (the critical part)
+
+```bash
+cd tests/<TestProject>.Mutation
+dotnet-stryker
+```
+
+**This directory choice is the whole game.** A bare `dotnet-stryker` at repo root
+auto-detects the single `.sln`, enters **solution mode**, ignores test-project
+selection, and binds to the real xunit.v3 project → false ~0%. Running from a
+directory with **no `.sln`** forces **project mode**: Stryker uses the shim in the
+cwd and finds the product through its `ProjectReference`. The `stryker-config.json`
+the script wrote (with `coverage-analysis: perTest` and `additional-timeout:
+30000`) lives beside the shim; perTest mode is required for kill observation and
+the raised timeout keeps slow mutants from being scored as timeouts.
+
+### Step 5 — Validate BEFORE the full run
+
+A full run can take hours; a wrong harness wastes all of it. Two gates:
+
+1. **Green baseline** — the shim builds and every test passes:
+   ```bash
+   dotnet build tests/<TestProject>.Mutation -c Release
+   dotnet test  tests/<TestProject>.Mutation -c Release --no-build
+   # expect the SAME test count as the real project, 0 failed
+   ```
+2. **Kills register** — temporarily scope `mutate` to one small, well-covered file
+   and run Stryker from the shim dir. Expect a **non-zero** score with real kills.
+   If this scoped run is still ~0%, the harness is wrong — **do not launch the full
+   run**; recheck the directory (Step 4) and the shim references.
+
+### Step 6 — Launch the full run, then sanity-check
+
+Widen `mutate` back to the full scope and launch. A full Stryker run is
+long-running — start it in the background and watch it (a Monitor plus a periodic
+status check), rather than blocking on it. If the periodic check is a scheduled
+wake-up, follow the calling contract in
+[`knowledge/long-run-waiting.md`](../../knowledge/long-run-waiting.md) — a
+wake-up armed without its replay instruction schedules nothing.
+
+Before recording any score, **reject the observation-failure signature**: a
+near-zero score with almost everything *Survived* means it bound to the v3 project
+again — rerun from the shim dir. A healthy run kills the majority of covered
+mutants. Output lands at
+`StrykerOutput/<timestamp>/reports/mutation-report.{html,json}`.
+
+## Teardown
+
+The shim, its `stryker-config.json`, the `InternalsVisibleTo` line, and any v3→v2
+source ports are **measurement scaffolding**. If you were measuring a throwaway
+branch/worktree, discard it. If the shim lives in the repo, keep it **out of the
+`.sln` and out of CI test discovery** so it never runs as a normal suite and never
+double-counts.

package/skills/stryker-xunit-v2-shim/references/shim-howto.md

@@ -0,0 +1,256 @@
+# Building a xunit.v2 Stryker shim for a xunit.v3 test project
+
+How to make Stryker.NET produce a valid mutation score for a project whose real
+test suite is **xunit.v3**. This is the full reference behind the
+`stryker-xunit-v2-shim` skill; read it when an edge case isn't covered by
+`SKILL.md`.
+
+---
+
+## 1. Why the shim exists
+
+Stryker.NET (through at least 4.15/4.16) **cannot observe mutant kills through
+xunit.v3.** xunit.v3 runs on the Microsoft Testing Platform (MTP), and Stryker's
+per-test coverage/kill mapping does not work across it (stryker-net issues
+3237, 3629, 3094). Symptom: the run completes but nearly every mutant is reported
+*Survived*, e.g. **0.13% (3 killed / 7,685 survived)** — the *observation-failure
+signature*. The initial test run passes and coverage filters even fire, so the
+failure is silent unless you sanity-check the score.
+
+The fix is a **shim**: a second test project that recompiles the *same test
+source files* under **xunit.v2** (classic VSTest), which Stryker observes
+correctly. No test is rewritten — the shim links the existing `.cs` files.
+
+**Precondition that makes this cheap:** the test sources must be
+source-compatible with xunit.v2. `[Fact]`, `[Theory]`, `[InlineData]`,
+`TheoryData<>`, `MemberData`, `ClassData`, and `Assert.*` are all source-identical
+between v2 and v3. Only genuinely v3-only constructs need porting (see step 4).
+AutoFixture.Xunit3 `[AutoData]`/`[InlineAutoData]` attributes are **not**
+v2-compatible; if the suite uses them heavily, this approach needs more work.
+
+---
+
+## 2. When to build / use it
+
+Trigger conditions (all true):
+
+- The target test project references `xunit.v3` (check its `.csproj`).
+- You need a Stryker mutation score for it.
+- The test sources are mostly plain xunit (grep confirms few/no `[AutoData]`,
+  `AutoFixture.Xunit3`, `TestContext`, `Assert.Skip`, `Assert.Multiple`,
+  `IAsyncLifetime` usages).
+
+Quick scope probe (run against the branch under test):
+
+```bash
+# v3-incompatible attribute usage in test .cs sources
+git grep -l "AutoFixture.Xunit3\|\[AutoData\|InlineAutoData\|AutoMoqData\|MemberAutoData" -- 'tests/**/*.cs'
+# other v3-only APIs
+git grep -l "TestContext\|Assert.Skip\|Assert.Multiple\|IAsyncLifetime\|Assert.Equivalent" -- 'tests/**/*.cs'
+```
+
+Each hit is a file the operator gate asks about. Zero hits → this is a ~10-minute
+unattended job.
+
+### 2a. The operator gate, recorded (#1791)
+
+Any hit means the operator picks between `port`, `exclude`, `skip`, and
+`degrade`, and `stryker_xunit_shim_guard.py` blocks every `dotnet-stryker` run
+against that project until the choice is recorded. The guard's block body prints
+the classified breakdown, the four tradeoffs, and the exact command to run —
+including the fingerprint of *this* blocker set. Its shape:
+
+```bash
+sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" \
+   "$CLAUDE_PLUGIN_ROOT/hooks/lib/xunit_v3_operator_gate.py" record \
+   --project <TestProject> --choice exclude --fingerprint <from-the-block-body>
+```
+
+Prefer the command the guard printed (absolute paths, correct fingerprint) over
+retyping this. `--fingerprint` is **required** — it is what scopes a decision to
+the blockers the operator actually saw. Omitting it is rejected outright rather
+than writing a blanket record that would silently cover blockers added later;
+reuse a stale one and the gate re-asks. Add `--file <path>` per flagged file and
+`--note "<why>"` to leave the rationale in the record. `check --project
+<TestProject>` prints the stored decision and exits non-zero when there is none.
+
+Recorded decisions live in `.claude/metrics/xunit-v3-shim-decisions.json` —
+no path override (#1870 dropped `DEV_TEAM_XUNIT3_SHIM_DECISION_FILE`
+entirely). Both the write and every later honor of a recorded decision emit a
+`boundary-events.jsonl` entry, so a self-recorded choice stays visible in the
+audit stream.
+
+---
+
+## 3. Build the shim project
+
+Create `tests/<TestProject>.Mutation/<TestProject>.Mutation.csproj` next to the
+real test project. It has **no `.cs` of its own** — it links the real project's
+sources. (The bundled [`generate_shim.py`](../scripts/generate_shim.py) writes this
+for you; the template below is what it emits and what to hand-fix for an unusual
+`.csproj`.)
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- xunit.v2 shim of <TestProject> for Stryker.NET.
+       Delete once stryker-net fixes MTP mutation observation
+       (issues 3237, 3629, 3094). -->
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>          <!-- match the test project's TFM -->
+    <IsPackable>false</IsPackable>
+    <RootNamespace><TestProject></RootNamespace>        <!-- SAME namespace as the real project -->
+    <AssemblyName><TestProject>.Mutation</AssemblyName> <!-- distinct assembly name -->
+    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
+    <NoWarn>$(NoWarn);IDE0028;RCS1163;CS8032;NU1701</NoWarn>
+    <GenerateProgramFile>true</GenerateProgramFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Mirror EVERY non-xunit package from the real test project at the SAME
+         versions (AutoFixture, Moq, assertion lib, Grpc.Core.Testing, any
+         private/internal deps). Swap the xunit stack for v2: -->
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <!-- Do NOT reference xunit.v3 or AutoFixture.Xunit3 here. -->
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\<Product>\<Product>.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Link the real test project's sources; exclude build output. -->
+    <Compile Include="..\<TestProject>\**\*.cs"
+             Exclude="..\<TestProject>\obj\**\*.cs;..\<TestProject>\bin\**\*.cs">
+      <Link>Linked\%(RecursiveDir)%(FileName)%(Extension)</Link>
+    </Compile>
+  </ItemGroup>
+
+</Project>
+```
+
+Key points:
+
+- **`RootNamespace` must equal the real project's root namespace** so linked
+  sources resolve the same types.
+- **`AssemblyName` must differ** (`.Mutation`) so both projects can coexist.
+- **Mirror non-xunit package versions exactly** — a version drift causes compile
+  errors in the linked sources.
+- Do **not** add the shim to the `.sln` (see step 5 for why).
+
+### 3a. Grant internals access
+
+If the product uses `InternalsVisibleTo` for the real test assembly, add the shim
+assembly too (the shim tests exercise `internal` types):
+
+```csharp
+[assembly: System.Runtime.CompilerServices.InternalsVisibleTo("<TestProject>.Mutation")]
+```
+
+---
+
+## 4. Port v3-only constructs (only the files step 2 flagged)
+
+Rewrite v3-only APIs to v2-compatible, behavior-equivalent forms. Common cases:
+
+| v3-only | v2-compatible replacement | Notes |
+|---|---|---|
+| `TestContext.Current.CancellationToken` | `CancellationToken.None` | Equivalent for passing tests; the token was never cancelled |
+| `[AutoData]` / `[InlineAutoData]` (AutoFixture.Xunit3) | manual `new Fixture()` in the test body, or convert to `[Fact]`/`[Theory]+[InlineData]` | Heavier; avoid this shim if pervasive |
+| `Assert.Skip(...)` | `[Fact(Skip="…")]` or guard-and-return | |
+
+Port **in the real test project's source** — the shim links those same files, so
+one edit satisfies both. Verify the replacement still compiles under v3 too
+(`CancellationToken.None` does).
+
+---
+
+## 5. Invoke Stryker against the shim (the critical part)
+
+**Run `dotnet-stryker` FROM the shim's project directory**, with a
+`stryker-config.json` beside it:
+
+```bash
+cd tests/<TestProject>.Mutation
+dotnet-stryker
+```
+
+Why this and not a bare run at repo root:
+
+- The repo root has a single `.sln` that does **not** contain the shim. A bare
+  `dotnet-stryker` at root **auto-detects the `.sln`, enters solution mode,
+  ignores `test-projects`, and binds to the real xunit.v3 project** → false ~0%.
+- Running from a directory with **no `.sln`** forces **project mode**: Stryker
+  uses the test project in the cwd (the shim) and finds the product via its
+  `ProjectReference`.
+
+`stryker-config.json` (place in the shim directory):
+
+```json
+{
+  "stryker-config": {
+    "mutate": ["**/*.cs", "!obj/**/*.cs", "!**/gRPC/**/*.cs", "!**/Caching/**/*.cs"],
+    "mutation-level": "Standard",
+    "coverage-analysis": "perTest",
+    "additional-timeout": 30000,
+    "target-framework": "net10.0",
+    "reporters": ["html", "json", "progress"],
+    "thresholds": { "high": 80, "low": 60, "break": 0 }
+  }
+}
+```
+
+(Adjust the `mutate` excludes to the product's own out-of-scope folders.)
+
+---
+
+## 6. Validate BEFORE the full run
+
+A full run can take hours; a wrong harness wastes all of it. Two gates:
+
+1. **Green baseline** — the shim must build and all tests pass:
+   ```bash
+   dotnet build tests/<TestProject>.Mutation/<TestProject>.Mutation.csproj -c Release
+   dotnet test  tests/<TestProject>.Mutation/<TestProject>.Mutation.csproj -c Release --no-build
+   # expect the same test count as the real project, 0 failed
+   ```
+2. **Kills register** — scope `mutate` to one small, well-covered file and run
+   Stryker from the shim dir. Expect a *non-zero* score with real kills:
+   ```json
+   { "stryker-config": { "mutate": ["**/Extensions/DecimalExtensions.cs"],
+       "coverage-analysis": "perTest", "reporters": ["json","progress"] } }
+   ```
+   A healthy scoped run produces real kills (e.g. **5 killed / 4 survived →
+   55.56%**) — proof observation works. If this scoped run shows ~0%, the harness
+   is still wrong; do **not** launch the full run.
+
+Then widen `mutate` to the full scope and launch the full run in the background,
+with periodic status monitoring rather than blocking on it.
+
+---
+
+## 7. Sanity-check the result
+
+Before recording any score, reject the observation-failure signature: a
+near-zero score with almost everything *Survived* means the run bound to the v3
+project — rerun from the shim dir. A healthy run kills the majority of covered
+mutants (a real example from this technique: **57.44%**, 4,419 killed / 2,209
+survived / 1 timeout of 6,629 tested).
+
+Output lives at `StrykerOutput/<timestamp>/reports/mutation-report.{html,json}`.
+
+---
+
+## 8. Teardown
+
+The shim, its `stryker-config.json`, the `InternalsVisibleTo` line, and any v3→v2
+source ports are **measurement scaffolding**. If measuring a branch you won't
+merge (e.g. a worktree baseline), discard the worktree. If the shim is meant to
+live in the repo, keep it out of the `.sln` and out of CI test discovery so it
+isn't run as a normal suite.