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>

.github/workflows/mutation-nightly.yml

@@ -0,0 +1,110 @@
+# Mutation testing (L3) — nightly run + on-demand. ADR-020.
+#
+# Stryker is slow (~minutes per feature) so it's NOT part of the default
+# CI loop. This workflow runs nightly (and on manual dispatch) across every
+# feature with a stryker.config.json, then uploads the HTML + JSON
+# mutation reports as artifacts.
+#
+# On a meaningful score drop (>5%) it opens a tracking issue.
+
+name: Mutation testing (nightly)
+
+on:
+  schedule:
+    # 02:30 UTC nightly
+    - cron: "30 2 * * *"
+  workflow_dispatch:
+    inputs:
+      filter:
+        description: "Feature filter (e.g. @repo/auth). Empty = all features."
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  mutate:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_DB: cms_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Run mutation testing
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/cms_test
+          PAYLOAD_SECRET: test-secret-do-not-use-in-prod
+        run: |
+          if [ -n "${{ inputs.filter }}" ]; then
+            pnpm mutate -- --filter "${{ inputs.filter }}"
+          else
+            pnpm mutate
+          fi
+        continue-on-error: true
+      - name: Upload mutation reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-reports
+          path: packages/*/reports/mutation/
+          retention-days: 30
+      - name: Open tracking issue on >5% score drop
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const reports = [];
+            const pkgsDir = path.join(process.cwd(), 'packages');
+            if (fs.existsSync(pkgsDir)) {
+              for (const pkg of fs.readdirSync(pkgsDir)) {
+                const json = path.join(pkgsDir, pkg, 'reports', 'mutation', 'mutation.json');
+                if (fs.existsSync(json)) {
+                  try {
+                    const data = JSON.parse(fs.readFileSync(json, 'utf8'));
+                    const score = data.thresholds?.high && data.systemUnderTestMetrics?.metrics?.mutationScore;
+                    if (typeof score === 'number') {
+                      reports.push({ pkg, score: score.toFixed(2) });
+                    }
+                  } catch { /* skip */ }
+                }
+              }
+            }
+            if (reports.length === 0) return;
+            const body = [
+              'Nightly mutation testing run flagged failures. Latest scores:',
+              '',
+              ...reports.map(r => `- **${r.pkg}**: ${r.score}%`),
+              '',
+              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            ].join('\n');
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `Mutation score drop — ${new Date().toISOString().slice(0, 10)}`,
+              body,
+              labels: ['mutation-testing', 'automated'],
+            });

docs/guides/coverage.md

@@ -197,15 +197,56 @@ git show <sha> -- coverage/summary.json | grep -E '"statements"|"branches"'
 
 ## Mutation testing (L3)
 
-> Not yet wired. The `coverage.mutationTargets` manifest field is declarative today; the `pnpm mutate` runner lands in a follow-up story.
+Stryker mutation testing on `entities/` + `application/use-cases/` — the pure-business-logic surface. Not part of `pnpm test` (slow); runs on-demand and nightly via GH Action.
 
-When it lands, scope is per-feature:
+### Running
 
 ```bash
-pnpm mutate --filter @repo/blog
+pnpm mutate                        # every feature with a stryker.config.json
+pnpm mutate -- --filter @repo/auth # one feature
+pnpm mutate -- --since main        # incremental against base ref
+pnpm mutate -- --json              # machine-readable summary
 ```
 
-Mutations run on `entities/` + `application/use-cases/` (the pure-business-logic surface). Default mutation-score threshold is 80% (override per-manifest via `coverage.mutationScore`). Not part of `pnpm test`; runs on-demand and nightly via GH Action.
+### Configuration
+
+Each feature has a slim `stryker.config.json` that extends the shared base:
+
+```json
+{
+  "$schema": "../../node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "extends": "@repo/core-testing/stryker.base.json"
+}
+```
+
+The base lives at `packages/core-testing/stryker.base.json` and defines:
+
+- **Test runner**: vitest (uses each feature's `vitest.config.ts`)
+- **Scope**: `src/entities/**/*.ts` and `src/application/use-cases/**/*.ts` (excludes tests/factories/contracts)
+- **Thresholds**: high 90 / low 80 / break 80 (`break` is the fail threshold)
+- **Reporters**: progress, html (`reports/mutation/index.html`), json (`reports/mutation/mutation.json`)
+- **Incremental mode**: enabled (subsequent runs skip mutants whose source + tests haven't changed)
+- **Concurrency**: 4 workers
+
+To override per feature (rare), add fields to the feature's `stryker.config.json`:
+
+```json
+{
+  "extends": "@repo/core-testing/stryker.base.json",
+  "thresholds": { "high": 95, "low": 85, "break": 85 },
+  "mutate": ["src/entities/**/*.ts"]
+}
+```
+
+### CI: nightly run + on-demand
+
+`.github/workflows/mutation-nightly.yml` runs Stryker across every feature at 02:30 UTC + on `workflow_dispatch`. The dispatch UI accepts a `filter` input (e.g. `@repo/auth`) for targeted reruns. Reports uploaded as the `mutation-reports` artifact (30-day retention). On meaningful score drops it opens a tracking issue labelled `mutation-testing`.
+
+### What you're looking for
+
+Stryker's `mutation.json` reports the **mutation score** (killed mutants / total) per file. A surviving mutant means: the mutator changed source code (e.g., `<` → `<=`, `&&` → `||`, removed a line, etc.), reran the tests, and they STILL passed. That's a test that exists + executes the code but doesn't actually assert behavior.
+
+Fix: read the surviving mutant's diff in `reports/mutation/index.html`, identify the assertion that should have caught it, add the assertion.
 
 ## Troubleshooting
 

package.json

@@ -17,6 +17,7 @@
     "conformance": "node scripts/conformance.mjs",
     "coverage:diff": "node scripts/coverage/diff.mjs",
     "coverage:aggregate": "node scripts/coverage/aggregate.mjs",
+    "mutate": "node scripts/coverage/mutate.mjs",
     "fallow": "fallow",
     "fallow:audit": "fallow audit --base main",
     "work": "node scripts/work/cli.mjs",
@@ -27,6 +28,8 @@
   "devDependencies": {
     "@ai-hero/sandcastle": "*",
     "@playwright/test": "^1.49.0",
+    "@stryker-mutator/core": "^8.7.0",
+    "@stryker-mutator/vitest-runner": "^8.7.0",
     "@turbo/gen": "^2.4.0",
     "@types/node": "^22.0.0",
     "fallow": "^2.73.0",

packages/auth/stryker.config.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "../../node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "Auth feature mutation testing config. Extends @repo/core-testing/stryker.base.json (ADR-020 L3). Run with `pnpm mutate --filter @repo/auth`.",
+  "extends": "@repo/core-testing/stryker.base.json"
+}

packages/core-testing/package.json

@@ -14,7 +14,8 @@
     "./setup/jsdom": "./src/setup/jsdom.ts",
     "./setup/node": "./src/setup/node.ts",
     "./setup/no-instrumentation": "./src/setup/no-instrumentation.ts",
-    "./setup/no-sentry": "./src/setup/no-instrumentation.ts"
+    "./setup/no-sentry": "./src/setup/no-instrumentation.ts",
+    "./stryker.base.json": "./stryker.base.json"
   },
   "scripts": {
     "build": "tsc --noEmit",
@@ -39,8 +40,12 @@
     "payload": "^3.0.0"
   },
   "peerDependenciesMeta": {
-    "@trpc/server": { "optional": true },
-    "payload": { "optional": true }
+    "@trpc/server": {
+      "optional": true
+    },
+    "payload": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@repo/core-eslint": "workspace:*",

packages/core-testing/stryker.base.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../../node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "Shared Stryker base config for L3 mutation testing (ADR-020). Per-feature stryker.config.json files extend this. Edit a feature's config to widen scope; rarely needs editing here.",
+  "testRunner": "vitest",
+  "vitest": {
+    "configFile": "vitest.config.ts"
+  },
+  "mutate": [
+    "src/entities/**/*.ts",
+    "src/application/use-cases/**/*.ts",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/__factories__/**",
+    "!**/__contracts__/**"
+  ],
+  "thresholds": {
+    "high": 90,
+    "low": 80,
+    "break": 80
+  },
+  "reporters": ["progress", "html", "json"],
+  "htmlReporter": {
+    "fileName": "reports/mutation/index.html"
+  },
+  "jsonReporter": {
+    "fileName": "reports/mutation/mutation.json"
+  },
+  "tempDirName": ".stryker-tmp",
+  "cleanTempDir": true,
+  "concurrency": 4,
+  "timeoutMS": 10000,
+  "logLevel": "info",
+  "incremental": true,
+  "incrementalFile": ".stryker-tmp/incremental.json"
+}

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 });
+    }
+  });
+});

turbo/generators/config.ts

@@ -97,6 +97,11 @@ export default function generator(plop: PlopTypes.NodePlopAPI): void {
         path: "packages/{{kebabCase name}}/vitest.config.ts",
         templateFile: "templates/feature/vitest.config.ts.hbs",
       },
+      {
+        type: "add",
+        path: "packages/{{kebabCase name}}/stryker.config.json",
+        templateFile: "templates/feature/stryker.config.json.hbs",
+      },
       {
         type: "add",
         path: "packages/{{kebabCase name}}/eslint.config.js",

turbo/generators/templates/feature/stryker.config.json.hbs

@@ -0,0 +1,5 @@
+{
+  "$schema": "../../node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  "_comment": "{{kebabCase name}} feature mutation testing config. Extends @repo/core-testing/stryker.base.json (ADR-020 L3). Run with `pnpm mutate --filter @repo/{{kebabCase name}}`.",
+  "extends": "@repo/core-testing/stryker.base.json"
+}