feat(coverage): pnpm mutate (Stryker) + L3 implementation

Lands L3 of the agent-first coverage architecture (ADR-020) — the
mutation-testing layer. Stryker on entities + use-cases (the pure
business-logic surface) catches the third dimension of test quality:
tests that exist + execute the code but assert nothing.

Deps (root devDependencies):
  - @stryker-mutator/core ^8.7.0
  - @stryker-mutator/vitest-runner ^8.7.0

Shared base: packages/core-testing/stryker.base.json
  - testRunner: vitest (uses each feature's vitest.config.ts)
  - mutate: src/entities/** + src/application/use-cases/** (excludes
    tests, factories, contracts)
  - thresholds: high 90 / low 80 / break 80
  - reporters: progress + html + json (reports/mutation/{index.html,
    mutation.json})
  - incremental mode enabled, concurrency 4, timeout 10s
  - exposed via @repo/core-testing/stryker.base.json subpath export

Per-feature config: packages/auth/stryker.config.json
  - 4-line file that extends the shared base
  - Proof-of-concept; other features get a config when L0 unification
    closes their existing test gaps

Driver: scripts/coverage/mutate.mjs (zero-dep Node ESM)
  - discoverStrykerConfigs: walks packages/* and apps/* for
    stryker.config.json
  - Supports --filter <name>, --since <ref> (incremental), --json
  - Runs Stryker per-feature via node_modules/.bin/stryker run
  - Surfaces per-package pass/fail summary; exits 1 on any failure
  - Tests: scripts/coverage/mutate.test.mjs (3 tests, all green)

CI: .github/workflows/mutation-nightly.yml
  - Cron at 02:30 UTC + workflow_dispatch with filter input
  - Uploads reports/mutation/** as artifact (30-day retention)
  - On failure, opens a tracking issue labelled mutation-testing
  - permissions: contents: read, issues: write
  - 60-min timeout (Stryker is slow by design)

Generator: turbo gen feature now scaffolds stryker.config.json from
turbo/generators/templates/feature/stryker.config.json.hbs — new
features ship mutation-ready out of the box.

Guide: docs/guides/coverage.md L3 section fleshed out with run
syntax, config shape, base config inventory, CI behavior, and a
"what you're looking for" primer on mutation scores.

Lockfile churn: pnpm regenerated the lockfile for the new deps;
~5K-line net reduction is collateral (pnpm version drift) but
mechanical.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/coverage/mutate.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// scripts/coverage/mutate.mjs — L3 of the coverage architecture (ADR-020).
+//
+// Driver for Stryker mutation testing. Discovers every package with a
+// stryker.config.json, then runs Stryker per-feature with the feature's
+// vitest config + a narrowed mutate scope (entities + use-cases by default,
+// per the shared base config).
+//
+// Usage:
+//   pnpm mutate                            # run for every feature with a config
+//   pnpm mutate -- --filter @repo/auth     # run for one feature
+//   pnpm mutate -- --filter @repo/auth --since main  # incremental mode
+//   pnpm mutate -- --json                  # machine-readable summary only
+//
+// This runs Stryker as a child process, not via dynamic import — Stryker's
+// runtime expects to own the test process and our wrapping logic keeps the
+// integration simple. Stryker handles concurrency internally.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const STRYKER_BIN = "node_modules/.bin/stryker";
+
+/**
+ * Walk packages/* and apps/* for stryker.config.json files.
+ * Returns: [{ packageDir, packageName, configPath }]
+ */
+export function discoverStrykerConfigs(repoRoot) {
+  const out = [];
+  for (const root of ["packages", "apps"]) {
+    const dir = path.join(repoRoot, root);
+    if (!fs.existsSync(dir)) continue;
+    for (const pkg of fs.readdirSync(dir)) {
+      const configPath = path.join(dir, pkg, "stryker.config.json");
+      if (!fs.existsSync(configPath)) continue;
+      const pkgJsonPath = path.join(dir, pkg, "package.json");
+      let packageName = `${root}/${pkg}`;
+      if (fs.existsSync(pkgJsonPath)) {
+        try {
+          packageName =
+            JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")).name ??
+            packageName;
+        } catch {
+          // fall through
+        }
+      }
+      out.push({
+        packageDir: path.join(root, pkg),
+        packageName,
+        configPath,
+      });
+    }
+  }
+  return out.sort((a, b) => a.packageDir.localeCompare(b.packageDir));
+}
+
+function parseArgs(argv) {
+  const out = { filter: null, since: null, json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--filter") out.filter = argv[++i];
+    else if (a === "--since") out.since = argv[++i];
+    else if (a === "--json") out.json = true;
+    else if (a === "--help" || a === "-h") {
+      console.log(
+        "Usage: pnpm mutate [-- --filter <name>] [--since <ref>] [--json]",
+      );
+      process.exit(0);
+    }
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const repoRoot = process.cwd();
+  const all = discoverStrykerConfigs(repoRoot);
+
+  const targets = args.filter
+    ? all.filter(
+        (c) =>
+          c.packageName === args.filter || c.packageDir.endsWith(args.filter),
+      )
+    : all;
+
+  if (targets.length === 0) {
+    process.stderr.write(
+      `[mutate] No stryker.config.json found${args.filter ? ` matching ${args.filter}` : ""}.\n` +
+        `Each feature wanting L3 mutation needs a stryker.config.json. See docs/guides/coverage.md.\n`,
+    );
+    process.exit(args.filter ? 1 : 0);
+  }
+
+  const strykerBinAbs = path.join(repoRoot, STRYKER_BIN);
+  if (!fs.existsSync(strykerBinAbs)) {
+    process.stderr.write(
+      `[mutate] Stryker binary not found at ${STRYKER_BIN}. Run \`pnpm install\`.\n`,
+    );
+    process.exit(1);
+  }
+
+  const results = [];
+  for (const target of targets) {
+    if (!args.json) {
+      process.stderr.write(
+        `\n[mutate] === ${target.packageName} (${target.packageDir}) ===\n`,
+      );
+    }
+
+    const strykerArgs = ["run", target.configPath];
+    if (args.since) {
+      strykerArgs.push("--since", args.since);
+    }
+
+    const result = spawnSync(strykerBinAbs, strykerArgs, {
+      cwd: path.join(repoRoot, target.packageDir),
+      stdio: args.json ? "pipe" : "inherit",
+      env: { ...process.env, FORCE_COLOR: args.json ? "0" : "1" },
+    });
+
+    results.push({
+      package: target.packageName,
+      packageDir: target.packageDir,
+      exitCode: result.status,
+      status: result.status === 0 ? "pass" : "fail",
+    });
+
+    // If a feature fails, continue to next. Surface failures at the end so
+    // a single broken feature doesn't mask state for the others.
+  }
+
+  const anyFailed = results.some((r) => r.exitCode !== 0);
+
+  if (args.json) {
+    process.stdout.write(
+      JSON.stringify(
+        { status: anyFailed ? "fail" : "pass", results },
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    process.stderr.write("\n[mutate] Summary:\n");
+    for (const r of results) {
+      process.stderr.write(
+        `  ${r.status === "pass" ? "✓" : "✗"} ${r.package}\n`,
+      );
+    }
+  }
+
+  process.exit(anyFailed ? 1 : 0);
+}
+
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  main();
+}

scripts/coverage/mutate.test.mjs

@@ -0,0 +1,71 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { discoverStrykerConfigs } from "./mutate.mjs";
+
+describe("discoverStrykerConfigs", () => {
+  test("finds stryker.config.json under packages/* and apps/*", () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mutate-disc-"));
+    try {
+      fs.mkdirSync(path.join(tmpRoot, "packages", "p1"), { recursive: true });
+      fs.mkdirSync(path.join(tmpRoot, "apps", "a1"), { recursive: true });
+      fs.mkdirSync(path.join(tmpRoot, "packages", "no-stryker"), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(tmpRoot, "packages", "p1", "stryker.config.json"),
+        "{}",
+      );
+      fs.writeFileSync(
+        path.join(tmpRoot, "packages", "p1", "package.json"),
+        JSON.stringify({ name: "@repo/p1" }),
+      );
+      fs.writeFileSync(
+        path.join(tmpRoot, "apps", "a1", "stryker.config.json"),
+        "{}",
+      );
+      fs.writeFileSync(
+        path.join(tmpRoot, "apps", "a1", "package.json"),
+        JSON.stringify({ name: "@repo/a1" }),
+      );
+
+      const found = discoverStrykerConfigs(tmpRoot);
+      assert.equal(found.length, 2);
+      const names = found.map((f) => f.packageName).sort();
+      assert.deepEqual(names, ["@repo/a1", "@repo/p1"]);
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to packageDir when no package.json", () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mutate-disc2-"));
+    try {
+      fs.mkdirSync(path.join(tmpRoot, "packages", "no-pkg-json"), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(tmpRoot, "packages", "no-pkg-json", "stryker.config.json"),
+        "{}",
+      );
+
+      const found = discoverStrykerConfigs(tmpRoot);
+      assert.equal(found.length, 1);
+      assert.equal(found[0].packageName, "packages/no-pkg-json");
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("returns empty when nothing matches", () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mutate-disc3-"));
+    try {
+      const found = discoverStrykerConfigs(tmpRoot);
+      assert.deepEqual(found, []);
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+});