chore: add mutation testing with Stryker (per-package CI gates)

.github/workflows/auto-ratchet.yml

@@ -0,0 +1,114 @@
+name: Auto-ratchet thresholds
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/*/src/**'
+      - 'stryker.config.mjs'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  ratchet:
+    name: Check & ratchet
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build all packages
+        run: pnpm -r build
+
+      - name: Run mutation for all packages
+        run: pnpm mutation || true
+
+      - name: Update baseline scores (merge, don't overwrite)
+        run: |
+          node -e "
+            import { PACKAGES } from './stryker.config.mjs';
+            import { readFileSync, writeFileSync } from 'fs';
+            let existing = {};
+            try { existing = JSON.parse(readFileSync('quality-baseline.json','utf8')); } catch {}
+            const baseline = { ...existing };
+            for (const pkg of PACKAGES) {
+              const prev = existing[pkg] || {};
+              let coverage = prev.coverage ?? null;
+              let mutation = prev.mutation ?? null;
+              try {
+                coverage = JSON.parse(readFileSync('packages/' + pkg + '/coverage/coverage-summary.json','utf8')).total.lines.pct;
+              } catch {}
+              try {
+                const r = JSON.parse(readFileSync('reports/mutation/' + pkg + '.json','utf8'));
+                const t = Object.values(r.files).reduce((a,f)=>{a.k+=f.mutants.filter(m=>m.status==='Killed').length;a.t+=f.mutants.length;return a},{k:0,t:0});
+                mutation = parseFloat((t.t?t.k/t.t*100:0).toFixed(2));
+              } catch {}
+              baseline[pkg] = { coverage, mutation };
+            }
+            writeFileSync('quality-baseline.json', JSON.stringify(baseline, null, 2) + '\n');
+          " --input-type=module
+
+      - name: Try auto-ratchet
+        id: ratchet
+        run: |
+          if node scripts/auto-ratchet.mjs; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open PR with updated baseline and thresholds
+        if: steps.ratchet.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="auto-ratchet/$(date +%Y%m%d)-$(git rev-parse --short HEAD)"
+          git checkout -b "$branch"
+          git add stryker.config.mjs quality-baseline.json
+          git commit -m "chore: auto-ratchet mutation thresholds and update baseline"
+          git push origin "$branch"
+          gh pr create \
+            --base main \
+            --head "$branch" \
+            --title "chore: auto-ratchet mutation thresholds" \
+            --body "Mutation scores have improved beyond their thresholds by more than 5 points. This PR bumps the thresholds to lock in the gains and updates the quality baseline."
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Open PR with updated baseline only
+        if: steps.ratchet.outputs.changed != 'true'
+        run: |
+          if git diff --quiet quality-baseline.json; then
+            echo "No baseline changes"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="quality-baseline/$(date +%Y%m%d)-$(git rev-parse --short HEAD)"
+          git checkout -b "$branch"
+          git add quality-baseline.json
+          git commit -m "chore: update quality baseline scores"
+          git push origin "$branch"
+          gh pr create \
+            --base main \
+            --head "$branch" \
+            --title "chore: update quality baseline scores" \
+            --body "Post-merge quality baseline update. No threshold changes."
+        env:
+          GH_TOKEN: ${{ github.token }}

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
   workflow_dispatch:
 
-# Minimal permissions — CI only needs to read code
+# Minimal permissions -- CI only needs to read code
 permissions:
   contents: read
 

.github/workflows/mutation.yml

@@ -0,0 +1,205 @@
+name: Quality
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  quality:
+    name: quality / ${{ matrix.package }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [adapter-claude, sdk, mcp-server, cli, sidecar]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build all packages
+        run: pnpm -r build
+
+      - name: Run tests with coverage
+        continue-on-error: true
+        working-directory: packages/${{ matrix.package }}
+        run: npx vitest run --coverage --coverage.reporter=json-summary --coverage.reportsDirectory=coverage
+
+      - name: Restore Stryker incremental cache
+        uses: actions/cache@v4
+        with:
+          path: .stryker-tmp/${{ matrix.package }}-incremental.json
+          key: stryker-${{ matrix.package }}-${{ hashFiles(format('packages/{0}/src/**', matrix.package), 'stryker.config.mjs') }}
+          restore-keys: |
+            stryker-${{ matrix.package }}-
+
+      - name: Run Stryker
+        id: stryker-run
+        run: |
+          if pnpm mutation ${{ matrix.package }}; then
+            echo "failed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "failed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Annotate surviving mutants on PR diff
+        if: always()
+        run: node scripts/annotate-survivors.mjs reports/mutation/${{ matrix.package }}.json || true
+
+      - name: Extract mutation score
+        if: always()
+        id: stryker
+        run: |
+          file="reports/mutation/${{ matrix.package }}.json"
+          if [ -f "$file" ]; then
+            score=$(node -e "const r=JSON.parse(require('fs').readFileSync('$file','utf8'));const t=Object.values(r.files).reduce((a,f)=>{a.k+=f.mutants.filter(m=>m.status==='Killed').length;a.t+=f.mutants.length;return a},{k:0,t:0});console.log((t.t?t.k/t.t*100:0).toFixed(2))")
+            echo "score=${score}" >> "$GITHUB_OUTPUT"
+          else
+            echo "score=N/A" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extract coverage percentage
+        if: always()
+        id: coverage
+        run: |
+          file="packages/${{ matrix.package }}/coverage/coverage-summary.json"
+          if [ -f "$file" ]; then
+            pct=$(node -e "const s=JSON.parse(require('fs').readFileSync('$file','utf8'));console.log(s.total.lines.pct)")
+            echo "lines=${pct}" >> "$GITHUB_OUTPUT"
+          else
+            echo "lines=N/A" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Write score artifact
+        if: always()
+        run: |
+          mkdir -p .quality-scores
+          echo '{"package":"${{ matrix.package }}","coverage":"${{ steps.coverage.outputs.lines }}","mutation":"${{ steps.stryker.outputs.score }}"}' > .quality-scores/${{ matrix.package }}.json
+
+      - name: Upload scores
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quality-score-${{ matrix.package }}
+          path: .quality-scores/${{ matrix.package }}.json
+
+      - name: Upload Stryker HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report-${{ matrix.package }}
+          path: reports/mutation/${{ matrix.package }}.html
+          retention-days: 14
+
+      - name: Enforce mutation threshold
+        if: steps.stryker-run.outputs.failed == 'true'
+        run: |
+          echo "Mutation score below threshold for ${{ matrix.package }}"
+          exit 1
+
+  comment:
+    name: PR Comment
+    needs: quality
+    if: always() && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (for baseline file)
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          sparse-checkout: quality-baseline.json
+          sparse-checkout-cone-mode: false
+
+      - name: Download all score artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: quality-score-*
+          merge-multiple: true
+          path: scores
+
+      - name: Build and post comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            // Load baseline from main (may not exist yet)
+            let baseline = {};
+            try { baseline = JSON.parse(fs.readFileSync('quality-baseline.json', 'utf8')); } catch {}
+
+            const files = fs.readdirSync('scores').filter(f => f.endsWith('.json'));
+            const rows = files
+              .map(f => JSON.parse(fs.readFileSync(`scores/${f}`, 'utf8')))
+              .sort((a, b) => a.package.localeCompare(b.package))
+              .map(r => {
+                const base = baseline[r.package] || {};
+                const fmtDelta = (cur, prev) => {
+                  if (cur === 'N/A' || prev == null) return '';
+                  const d = (parseFloat(cur) - prev).toFixed(1);
+                  if (d > 0) return ` (+${d})`;
+                  if (d < 0) return ` (${d})`;
+                  return '';
+                };
+                const cov = r.coverage === 'N/A' ? 'N/A' : r.coverage + '%' + fmtDelta(r.coverage, base.coverage);
+                const mut = r.mutation === 'N/A' ? 'N/A' : r.mutation + '%' + fmtDelta(r.mutation, base.mutation);
+                return `| ${r.package} | ${cov} | ${mut} |`;
+              })
+              .join('\n');
+
+            const body = [
+              '## Quality Report',
+              '',
+              '| Package | Line Coverage | Mutation Score |',
+              '|---------|-------------|----------------|',
+              rows,
+              '',
+              '> Coverage = % of lines your tests touch. Mutation = % of code changes your tests catch.',
+              '> Deltas shown vs `main` baseline. Mutation reports available as workflow artifacts.',
+            ].join('\n');
+
+            const marker = '<!-- quality-report -->';
+            const fullBody = marker + '\n' + body;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.find(c => c.body?.includes(marker));
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: fullBody,
+              });
+            }

.gitignore

@@ -59,6 +59,10 @@ packages/sdk-python/.venv/
 # ── Worktrees ─────────────────────────────────────────────────────────────────
 .worktrees/
 
+# ── Stryker (mutation testing) ────────────────────────────────────────────────
+.stryker-tmp/
+reports/mutation/
+
 # ── Misc ──────────────────────────────────────────────────────────────────────
 *.ots
 commit.txt