Follow-up #461: Add Stryker mutation testing + per-file OSINT coverage thresholds + dedicated osint-qa CI job

[pethers]

📋 Task Overview

Follow-up to closed issue #461 / PR #474. The OSINT QA contract suite landed (tests/integration/osint/contract.test.ts — envelope, no-silent-zero, determinism), INTEGRATION_TESTING.md and CONTRIBUTING.md were updated, and ARCHITECTURE.md now links the suite. However, three deliverables from the original #461 acceptance criteria did not ship:

1. Mutation testing baseline (Stryker, ≥70 % mutation score on the 15 OSINT tool files) — package.json has no test:mutation script; no stryker.config.json exists. Code search confirms Stryker is only mentioned aspirationally in FUTURE_WORKFLOWS.md.
2. Per-file coverage thresholds (≥90 % for OSINT tools, ≥95 % for DOCEO-touching files) — vitest.config.ts only enforces the global lines: 80; there is no coverage.thresholds.perFile entry.
3. Dedicated CI job for the OSINT QA harness — neither osint-qa.yml nor an extension of test-and-report.yml runs the contract suite as a discrete job; it executes inside the general integration test pass without isolated reporting.

The contract test suite alone catches structural violations but cannot detect logic regressions in scoring/anomaly methodology — exactly the kind of regressions the seven companion correctness PRs (#467, #469, #472, #473, #476, #477, #479) introduced surface area for. Mutation testing + tight per-file thresholds close that gap.

🎯 Objectives

• Add Stryker (@stryker-mutator/core, @stryker-mutator/vitest-runner) as a dev dependency.
• stryker.config.json scoped to the 15 OSINT tool files + their shared utilities (src/utils/votingBaseline.ts, src/utils/graphAlgorithms.ts, src/utils/networkVotingSimilarity.ts, src/utils/effectivenessAggregator.ts, src/utils/lifecycleStatistics.ts, src/utils/doceoMepAggregator.ts, src/utils/politicalGroupNormalization.ts).
• Initial mutation-score threshold informational (thresholds: { high: 80, low: 60, break: null }); promote break: 70 once one green run is observed on main.
• npm run test:mutation script and matching osint-mutation job in CI.
• Extend vitest.config.ts with coverage.thresholds.perFile entries:
  • src/tools/{the 14 non-DOCEO OSINT tools}.ts → { lines: 90, branches: 85, functions: 90, statements: 90 }.
  • src/tools/assessMepInfluence.ts, src/tools/detectVotingAnomalies.ts, src/tools/sentimentTracker.ts, src/tools/networkAnalysis.ts, src/tools/analyzeCoalitionDynamics.ts (DOCEO-touching) → { lines: 95, branches: 90, functions: 95, statements: 95 }.
• Extract the contract suite into its own CI job (osint-qa) so failures are visibly attributed and golden-snapshot drift surfaces in PR checks.
• Make the mutation job non-blocking initially (status check required: false), then promote in a follow-up PR after baseline stability is observed.

📦 Deliverables

• package.json — new devDependencies, test:mutation script, version bump in release-notes not required (CI-only change).
• stryker.config.json at repo root scoped per above.
• vitest.config.ts extended with per-file thresholds and an opt-in --changed-files mode for fast PR runs.
• .github/workflows/osint-qa.yml (or extension of test-and-report.yml) with three sequential jobs: osint-contract, osint-coverage, osint-mutation (the last marked continue-on-error: true for the first 30 days).
• CONTRIBUTING.md — section explaining how to run the mutation suite locally and what surviving-mutant categories are acceptable (e.g. log-string mutants).
• INTEGRATION_TESTING.md — appendix on mutation-testing scope and exclusions.

🔒 Security & Compliance

• Supply Chain: Stryker packages must pass the existing npm run test:licenses allow-list (MIT/Apache-2.0/BSD/ISC) — verify before adding.
• CI Resource Bound: scope must keep total mutation runtime under 15 minutes; use --concurrency 4 and exclude *.test.ts.
• ISMS Reference: A.8.29 (Security testing in development & acceptance), A.8.34 (Protection during audit testing).
• Compliance: ISO 27001, SLSA Level 3 (provenance covers test artefacts).

🏗️ Technical Approach

• Run gh-advisory-database against the two Stryker packages before adding to lockfile.
• Scope Stryker mutate glob to the 15 OSINT tool files and 7 shared utilities; ignorePatterns for tests and generated.
• vitest-runner keeps the existing test infrastructure with no per-test fork overhead.
• Per-file coverage uses Vitest 3's thresholds.perFile map syntax; CI prints offenders in a digestible table.
• The new workflow uses actions/setup-node with the pinned SHA pattern from test-and-report.yml.

🧪 Testing Requirements

• Mutation run on main completes with score ≥60 % (baseline) before the threshold is bumped.
• Per-file coverage gate fails CI when any OSINT tool drops below its assigned threshold.
• osint-qa workflow visible as a discrete check on every PR touching src/tools/ or src/utils/votingBaseline.ts/graphAlgorithms.ts/etc.
• Test runtime budget: contract ≤2 min, coverage ≤3 min, mutation ≤15 min.

📚 Documentation Updates

• CONTRIBUTING.md — mutation testing instructions.
• INTEGRATION_TESTING.md — OSINT QA appendix.
• WORKFLOWS.md — new osint-qa workflow entry.
• ARCHITECTURE.md — reference to mutation testing as the test-quality enforcement point.

🤖 Recommended Agent

Agent: hack23-test-specialist (with hack23-devops-engineer for the CI workflow wiring)
Rationale: This is a pure QA-infrastructure task — mutation testing scope, Vitest threshold configuration, and CI job extraction map directly onto the test-specialist's remit; DevOps owns the workflow file.

🔗 Related Issues

• Closed parent: OSINT QA: Add cross-tool contract tests, golden snapshots, and no-silent-zero policy for all 15 OSINT tools #461 (PR Add registry-driven OSINT contract suite with no-silent-zero and determinism guards #474).
• Protected work: PRs OSINT: Replace placeholder voting statistics in assess_mep_influence with DOCEO RCV data #467, Replace heuristic stage progression in monitor_legislative_pipeline with lifecycle-driven analysis #469, Wire analyze_committee_activity workload to real EP data via resilient fan-out #472, Compute real legislative effectiveness metrics from EP procedures, adopted texts, plenary documents, and questions; fix monitor_legislative_pipeline cold-cache flake #473, OSINT: DOCEO-backed voting anomaly detection with z-score baselines #476, OSINT: voting-similarity edges, depth-bounded BFS, and weighted centrality in network_analysis #477, Make sentiment_tracker timeframe functional with DOCEO cohesion-driven scoring #479 (seven OSINT correctness/completeness PRs landed without mutation-test protection).
• Related config: vitest.config.ts:thresholds, tests/integration/osint/contract.test.ts.

📌 ISMS References

• Hack23/ISMS-PUBLIC Secure Development Policy §4.4 (Testing), §4.5 (Quality Assurance).
• ISO 27001 Annex A.8.29 (Security testing), A.8.34 (Audit protection).
• CIS Controls v8.1 Control 16 (Application Software Security).
• EU CRA — verifiable testing evidence for product correctness.