peaks-loop 3.0.0

package/dist/src/services/migration/v2-10-to-v2-11-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration service.
+ *
+ * Scans pre-v2.11.0 sessions for `rd/tech-doc.md` files and tags each
+ * with a deprecation banner (Karpathy §3 surgical: text-only, no file
+ * moves). Idempotent: re-running produces no diff on a previously-
+ * migrated repo.
+ *
+ * === Why text-only (no move / no prune) ===
+ *
+ * v2.11.0 introduces the immutable peaks-prd handoff at
+ * `.peaks/_runtime/<sid>/prd/handoff.md` as the source of truth. The
+ * old `rd/tech-doc.md` is no longer required by any CLI gate, but the
+ * historical content still has audit value. Removing it silently would
+ * lose the diff; renaming would orphan any external reference (e.g.,
+ * commit messages, blog posts). The least-risky path is: tag in place
+ * with a banner; let the user decide when/whether to prune in a future
+ * slice.
+ *
+ * === Banner shape (locked) ===
+ *
+ * The banner is prepended (NOT wrapped) — keeps existing body intact,
+ * Git blame still works for the original content lines.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ */
+import { type MigrationEntry, type MigrationPlan, type MigrationResult, type MigrationReason } from './v2-10-to-v2-11-types.js';
+export declare function enumerateTechDocs(projectRoot: string): ReadonlyArray<{
+    readonly sessionId: string;
+    readonly filePath: string;
+}>;
+export declare function planV2ToV11Migration(projectRoot: string): MigrationPlan;
+export declare function applyV2ToV11Migration(plan: MigrationPlan): MigrationResult;
+export interface DryRunResult {
+    readonly plan: MigrationPlan;
+    readonly applied: false;
+    readonly writtenCount: 0;
+    readonly errors: ReadonlyArray<{
+        readonly path: string;
+        readonly message: string;
+    }>;
+}
+export declare function dryRunV2ToV11Migration(projectRoot: string): DryRunResult;
+export type { MigrationEntry, MigrationPlan, MigrationReason, MigrationResult };

package/dist/src/services/migration/v2-10-to-v2-11-service.js

@@ -0,0 +1,190 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration service.
+ *
+ * Scans pre-v2.11.0 sessions for `rd/tech-doc.md` files and tags each
+ * with a deprecation banner (Karpathy §3 surgical: text-only, no file
+ * moves). Idempotent: re-running produces no diff on a previously-
+ * migrated repo.
+ *
+ * === Why text-only (no move / no prune) ===
+ *
+ * v2.11.0 introduces the immutable peaks-prd handoff at
+ * `.peaks/_runtime/<sid>/prd/handoff.md` as the source of truth. The
+ * old `rd/tech-doc.md` is no longer required by any CLI gate, but the
+ * historical content still has audit value. Removing it silently would
+ * lose the diff; renaming would orphan any external reference (e.g.,
+ * commit messages, blog posts). The least-risky path is: tag in place
+ * with a banner; let the user decide when/whether to prune in a future
+ * slice.
+ *
+ * === Banner shape (locked) ===
+ *
+ * The banner is prepended (NOT wrapped) — keeps existing body intact,
+ * Git blame still works for the original content lines.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEPRECATION_BANNER } from './v2-10-to-v2-11-types.js';
+const SKIP_DIRS = new Set([
+    'memory',
+    'PROJECT.md',
+    'retrospective',
+    'scope',
+    '.peaks-init-hooks-decision.json',
+    'session.json',
+    '.session.json',
+    '_runtime',
+    '_sub_agents',
+    'change',
+    'caller',
+    'callers',
+    'sop-state',
+    'system',
+    'active-skill.json',
+    '.active-skill.json'
+]);
+const SESSION_DIR_RE = /^\d{4}-\d{2}-\d{2}-session-/;
+const TECH_DOC_MARKERS = ['## Architecture', '## Component', '## API', '## Dependencies'];
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function hasExistingFrontmatter(body) {
+    const lines = body.split(/\r?\n/).slice(0, 10);
+    return lines.some((line) => line.trim() === '---');
+}
+function looksLikeTechDoc(body) {
+    return TECH_DOC_MARKERS.some((marker) => body.includes(marker));
+}
+function isAlreadyDeprecated(body) {
+    return body.startsWith(DEPRECATION_BANNER);
+}
+function enumerateSessionDirs(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(peaksRoot)) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        if (entry.startsWith('.'))
+            continue;
+        if (SESSION_DIR_RE.test(entry))
+            out.push(entry);
+    }
+    return out;
+}
+function buildEntryForFile(sessionId, filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const body = readFileSync(filePath, 'utf8');
+    const fromHash = sha256(body);
+    if (isAlreadyDeprecated(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'already-deprecated',
+            skippedBytes: 0
+        };
+    }
+    if (hasExistingFrontmatter(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'not-a-tech-doc',
+            skippedBytes: 0
+        };
+    }
+    if (!looksLikeTechDoc(body)) {
+        return {
+            sessionId,
+            filePath,
+            fromHash,
+            toHash: fromHash,
+            reason: 'not-a-tech-doc',
+            skippedBytes: 0
+        };
+    }
+    const newBody = DEPRECATION_BANNER + body;
+    return {
+        sessionId,
+        filePath,
+        fromHash,
+        toHash: sha256(newBody),
+        reason: 'will-deprecate',
+        skippedBytes: 0
+    };
+}
+export function enumerateTechDocs(projectRoot) {
+    const out = [];
+    for (const sid of enumerateSessionDirs(projectRoot)) {
+        const filePath = join(projectRoot, '.peaks', sid, 'rd', 'tech-doc.md');
+        if (existsSync(filePath))
+            out.push({ sessionId: sid, filePath });
+    }
+    return out;
+}
+export function planV2ToV11Migration(projectRoot) {
+    const entries = [];
+    let willDeprecateCount = 0;
+    let alreadyDeprecatedCount = 0;
+    let notTechDocCount = 0;
+    for (const { sessionId, filePath } of enumerateTechDocs(projectRoot)) {
+        const entry = buildEntryForFile(sessionId, filePath);
+        if (entry === null)
+            continue;
+        entries.push(entry);
+        if (entry.reason === 'will-deprecate')
+            willDeprecateCount++;
+        else if (entry.reason === 'already-deprecated')
+            alreadyDeprecatedCount++;
+        else
+            notTechDocCount++;
+    }
+    return {
+        projectRoot,
+        entries,
+        willDeprecateCount,
+        alreadyDeprecatedCount,
+        notTechDocCount
+    };
+}
+export function applyV2ToV11Migration(plan) {
+    const errors = [];
+    let writtenCount = 0;
+    for (const entry of plan.entries) {
+        if (entry.reason !== 'will-deprecate')
+            continue;
+        try {
+            const body = readFileSync(entry.filePath, 'utf8');
+            const newBody = DEPRECATION_BANNER + body;
+            writeFileSync(entry.filePath, newBody, 'utf8');
+            writtenCount++;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push({ path: entry.filePath, message });
+        }
+    }
+    return {
+        plan,
+        applied: true,
+        writtenCount,
+        errors
+    };
+}
+export function dryRunV2ToV11Migration(projectRoot) {
+    const plan = planV2ToV11Migration(projectRoot);
+    return {
+        plan,
+        applied: false,
+        writtenCount: 0,
+        errors: []
+    };
+}

package/dist/src/services/migration/v2-10-to-v2-11-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration types.
+ *
+ * The migration codemod scans pre-v2.11.0 sessions for `rd/tech-doc.md`
+ * files and prepends a YAML banner marking them as deprecated. Files
+ * move (physically) is out of scope per Karpathy §3 surgical changes;
+ * the immutable peaks-prd handoff at `prd/handoff.md` is the new
+ * source of truth, but old files coexist.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ *
+ * The banner shape is fixed; if a file already carries a `---` frontmatter,
+ * the migration skips it (set `reason: 'not-a-tech-doc'`) to avoid clobbering
+ * user-authored content.
+ */
+export type MigrationReason = 'will-deprecate' | 'already-deprecated' | 'not-a-tech-doc';
+export interface MigrationEntry {
+    readonly sessionId: string;
+    readonly filePath: string;
+    readonly fromHash: string;
+    readonly toHash: string;
+    readonly reason: MigrationReason;
+    readonly skippedBytes: number;
+}
+export interface MigrationPlan {
+    readonly projectRoot: string;
+    readonly entries: ReadonlyArray<MigrationEntry>;
+    readonly willDeprecateCount: number;
+    readonly alreadyDeprecatedCount: number;
+    readonly notTechDocCount: number;
+}
+export interface MigrationResult {
+    readonly plan: MigrationPlan;
+    readonly applied: boolean;
+    readonly writtenCount: number;
+    readonly errors: ReadonlyArray<{
+        readonly path: string;
+        readonly message: string;
+    }>;
+}
+export declare const DEPRECATION_BANNER: string;

package/dist/src/services/migration/v2-10-to-v2-11-types.js

@@ -0,0 +1,23 @@
+/**
+ * v2.11.0 — Group E (Tier 8) migration types.
+ *
+ * The migration codemod scans pre-v2.11.0 sessions for `rd/tech-doc.md`
+ * files and prepends a YAML banner marking them as deprecated. Files
+ * move (physically) is out of scope per Karpathy §3 surgical changes;
+ * the immutable peaks-prd handoff at `prd/handoff.md` is the new
+ * source of truth, but old files coexist.
+ *
+ * === Source: peaks-rd/references/writing-handoff-frontmatter.md §"v2.11.0" ===
+ *
+ * The banner shape is fixed; if a file already carries a `---` frontmatter,
+ * the migration skips it (set `reason: 'not-a-tech-doc'`) to avoid clobbering
+ * user-authored content.
+ */
+export const DEPRECATION_BANNER = [
+    '---',
+    'deprecated: historical',
+    'deprecatedBy: v2.11.0',
+    'replacedBy: peaks-prd handoff at .peaks/_runtime/<sessionId>/prd/handoff.md',
+    '---',
+    ''
+].join('\n');

package/dist/src/services/mode/bypass-tracker.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_BYPASSES_PER_SESSION = 3;
+export declare function getBypassCount(sessionRoot: string): number;
+export declare function recordBypass(sessionRoot: string): number;
+export declare function isBypassLimitReached(sessionRoot: string): boolean;

package/dist/src/services/mode/bypass-tracker.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const MAX_BYPASSES_PER_SESSION = 3;
+const BYPASS_FILE = '.bypass-count.json';
+function bypassFilePath(sessionRoot) {
+    return join(sessionRoot, BYPASS_FILE);
+}
+export function getBypassCount(sessionRoot) {
+    const filePath = bypassFilePath(sessionRoot);
+    if (!existsSync(filePath)) {
+        return 0;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.count === 'number' ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function recordBypass(sessionRoot) {
+    const current = getBypassCount(sessionRoot);
+    const next = current + 1;
+    const filePath = bypassFilePath(sessionRoot);
+    writeFileSync(filePath, JSON.stringify({ count: next }, null, 2), 'utf8');
+    return next;
+}
+export function isBypassLimitReached(sessionRoot) {
+    return getBypassCount(sessionRoot) >= MAX_BYPASSES_PER_SESSION;
+}

package/dist/src/services/mode/mode-enforcement.d.ts

@@ -0,0 +1,14 @@
+import { type SkillPresenceMode } from '../skills/skill-presence-service.js';
+type TransitionKey = `${string}:${string}`;
+export declare function requiresConfirmation(mode: SkillPresenceMode, transitionKey: TransitionKey): boolean;
+export type ConfirmationOptions = {
+    projectRoot: string;
+    transitionKey: TransitionKey;
+    confirmed?: boolean | undefined;
+    forceConfirm?: boolean | undefined;
+};
+export declare class ConfirmationRequiredError extends Error {
+    constructor(transitionKey: TransitionKey);
+}
+export declare function requireUserConfirmation(options: ConfirmationOptions): Promise<void>;
+export {};

package/dist/src/services/mode/mode-enforcement.js

@@ -0,0 +1,84 @@
+import * as readline from 'node:readline';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+const ASSISTED_CONFIRM_TRANSITIONS = new Set([
+    'prd:confirmed-by-user',
+    'rd:qa-handoff',
+    'qa:verdict-issued'
+]);
+export function requiresConfirmation(mode, transitionKey) {
+    if (mode === 'full-auto' || mode === 'swarm') {
+        return false;
+    }
+    if (mode === 'strict') {
+        return true;
+    }
+    // assisted: only specific transitions
+    return ASSISTED_CONFIRM_TRANSITIONS.has(transitionKey);
+}
+function describeTransition(transitionKey) {
+    const parts = transitionKey.split(':');
+    const role = parts[0] ?? 'unknown';
+    const state = parts[1] ?? 'unknown';
+    return `Transition ${role.toUpperCase()} → ${state}`;
+}
+export class ConfirmationRequiredError extends Error {
+    constructor(transitionKey) {
+        const description = describeTransition(transitionKey);
+        super(`Confirmation required for: ${description}\n` +
+            'Add --confirm to proceed non-interactively, or run in an interactive terminal.\n' +
+            'In assisted/strict mode, major workflow boundaries require explicit user approval.');
+        this.name = 'ConfirmationRequiredError';
+    }
+}
+export async function requireUserConfirmation(options) {
+    // Resolve presence from the project being operated on, not the process cwd.
+    const presence = getSkillPresence(options.projectRoot);
+    if (!presence?.mode) {
+        return;
+    }
+    const mode = presence.mode;
+    if (!requiresConfirmation(mode, options.transitionKey)) {
+        return;
+    }
+    // --confirm flag bypasses interactive prompt
+    if (options.confirmed) {
+        return;
+    }
+    // PEAKS_AUTO_CONFIRM=1 only works for full-auto/swarm (already returned above)
+    // For assisted/strict, env var is ignored unless --force-confirm is also set
+    if (process.env.PEAKS_AUTO_CONFIRM === '1') {
+        if (options.forceConfirm) {
+            console.error(// TODO(g2): legacy console.error without envelope — grace: 1 minor release (v2.14.0)
+            `[WARNING] --force-confirm used in ${mode} mode. ` +
+                'This bypasses user confirmation. Use with caution.');
+            return;
+        }
+        throw new ConfirmationRequiredError(options.transitionKey);
+    }
+    // --force-confirm without env var
+    if (options.forceConfirm) {
+        console.error(// TODO(g2): legacy console.error without envelope — grace: 1 minor release (v2.14.0)
+        `[WARNING] --force-confirm used in ${mode} mode. ` +
+            'This bypasses user confirmation. Use with caution.');
+        return;
+    }
+    // Interactive prompt
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    return new Promise((resolve, reject) => {
+        const description = describeTransition(options.transitionKey);
+        const prompt = `\n[CONFIRM] ${description}\nProceed? (y/N) `;
+        rl.question(prompt, (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes') {
+                resolve();
+            }
+            else {
+                reject(new ConfirmationRequiredError(options.transitionKey));
+            }
+        });
+    });
+}

package/dist/src/services/mut/assert-scanner.d.ts

@@ -0,0 +1,6 @@
+import type { AssertionsReport } from './types.js';
+export interface ScanInput {
+    readonly project: string;
+    readonly testFiles: ReadonlyArray<string>;
+}
+export declare function scanAssertions(input: ScanInput): Promise<AssertionsReport>;

package/dist/src/services/mut/assert-scanner.js

@@ -0,0 +1,116 @@
+/**
+ * Per spec §4.2 验收审计 + §7 阶段二 — 5-pattern weak-assertion AST scan.
+ *
+ * Hard constraints:
+ *   H6 (CLI裁决): every detection is regex/AST-based, not LLM-judged.
+ *   KISS: regex matchers on common expect() patterns. Production slice
+ *   would migrate to TypeScript Compiler API; v1 ships regex for speed.
+ *
+ * Weak patterns (5):
+ *   - toBeDefined()
+ *   - toBeTruthy()
+ *   - toEqual(x) where arg === receiver (toEqual-self)
+ *   - expect.anything()
+ *   - toBe(x) where arg === receiver (toBe-self)
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const WEAK_PATTERNS = [
+    { pattern: 'toBeDefined', regex: /\.toBeDefined\s*\(\s*\)/g },
+    { pattern: 'toBeTruthy', regex: /\.toBeTruthy\s*\(\s*\)/g },
+    { pattern: 'expect-anything', regex: /expect\.anything\s*\(\s*\)/g },
+    // Self-equality patterns require matched-pair parsing; handled below.
+];
+const TO_EQUAL_SELF = /\.toEqual\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g;
+const TO_BE_SELF = /\.toBe\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g;
+async function countAssertions(content) {
+    // Approximate: count expect(...).method( occurrences.
+    // Handle nested parens by finding expect( and matching to a balanced close.
+    let count = 0;
+    const re = /expect\s*\(/g;
+    for (const m of content.matchAll(re)) {
+        let depth = 1;
+        let i = (m.index ?? 0) + m[0].length;
+        while (i < content.length && depth > 0) {
+            const ch = content[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')')
+                depth--;
+            i++;
+        }
+        // After balanced expect(...), check for .method( pattern.
+        const tail = content.slice(i);
+        if (/^\s*\.\w+\s*\(/.test(tail)) {
+            count++;
+        }
+    }
+    return count;
+}
+function lineOf(content, offset) {
+    return content.slice(0, offset).split('\n').length;
+}
+export async function scanAssertions(input) {
+    let total = 0;
+    let weak = 0;
+    const byPattern = new Map();
+    for (const file of input.testFiles) {
+        const fullPath = join(input.project, file);
+        const content = await readFile(fullPath, 'utf8');
+        total += await countAssertions(content);
+        for (const { pattern, regex } of WEAK_PATTERNS) {
+            const matches = [...content.matchAll(regex)];
+            if (matches.length > 0) {
+                weak += matches.length;
+                const list = byPattern.get(pattern) ?? [];
+                for (const m of matches) {
+                    const idx = m.index ?? 0;
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                }
+                byPattern.set(pattern, list);
+            }
+        }
+        // toEqual-self: needs receiver extraction.
+        const eqSelf = [...content.matchAll(TO_EQUAL_SELF)];
+        for (const m of eqSelf) {
+            const receiverMatch = content.slice(0, m.index ?? 0).match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g);
+            if (receiverMatch && receiverMatch.length > 0) {
+                const lastReceiver = receiverMatch[receiverMatch.length - 1];
+                const receiverName = lastReceiver?.match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/)?.[1];
+                if (receiverName && receiverName === m[1]) {
+                    weak += 1;
+                    const idx = m.index ?? 0;
+                    const list = byPattern.get('toEqual-self') ?? [];
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                    byPattern.set('toEqual-self', list);
+                }
+            }
+        }
+        // toBe-self: same pattern.
+        const beSelf = [...content.matchAll(TO_BE_SELF)];
+        for (const m of beSelf) {
+            const receiverMatch = content.slice(0, m.index ?? 0).match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g);
+            if (receiverMatch && receiverMatch.length > 0) {
+                const lastReceiver = receiverMatch[receiverMatch.length - 1];
+                const receiverName = lastReceiver?.match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/)?.[1];
+                if (receiverName && receiverName === m[1]) {
+                    weak += 1;
+                    const idx = m.index ?? 0;
+                    const list = byPattern.get('toBe-self') ?? [];
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                    byPattern.set('toBe-self', list);
+                }
+            }
+        }
+    }
+    const weakPatterns = [];
+    for (const [pattern, examples] of byPattern.entries()) {
+        weakPatterns.push({ pattern, count: examples.length, examples });
+    }
+    return {
+        totalAssertions: total,
+        weakAssertions: weak,
+        weakRate: total === 0 ? 0 : weak / total,
+        weakPatterns,
+    };
+}

package/dist/src/services/mut/index.d.ts

@@ -0,0 +1,8 @@
+export { MutReportSchema } from './types.js';
+export { scanAssertions, type ScanInput } from './assert-scanner.js';
+export { runMutation, type RunMutationInput, type RunMutationOutput, type StrykerInvoker, type StrykerRawResult, } from './mut-runner.js';
+export { createProductionStrykerInvoker } from './production-stryker.js';
+export { buildMutReport, type BuildMutInput } from './report-builder.js';
+export { loadMutReport, mutReportPath, MUT_REPORT_RELATIVE_PATH } from './report-loader.js';
+export { DEFAULT_THRESHOLDS, evaluateThresholds, type Thresholds, type ThresholdEvaluation, type ThresholdViolation, type ThresholdViolationKind, } from './thresholds.js';
+export type { MutReportJson, MutationReport, AssertionsReport, WeakPattern, WeakPatternCount, Followup, } from './types.js';

package/dist/src/services/mut/index.js

@@ -0,0 +1,7 @@
+export { MutReportSchema } from './types.js';
+export { scanAssertions } from './assert-scanner.js';
+export { runMutation, } from './mut-runner.js';
+export { createProductionStrykerInvoker } from './production-stryker.js';
+export { buildMutReport } from './report-builder.js';
+export { loadMutReport, mutReportPath, MUT_REPORT_RELATIVE_PATH } from './report-loader.js';
+export { DEFAULT_THRESHOLDS, evaluateThresholds, } from './thresholds.js';

package/dist/src/services/mut/mut-runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per spec §4.2 验收审计 — Stryker wrapper for TS mutation testing.
+ *
+ * Hard constraints:
+ *   H6 (CLI裁决): invokeStryker is injected; production wires it to
+ *       @stryker-mutator/core programmatic API.
+ *   DRY: production implementation lives in this file; tests mock the
+ *       invokeStryker injection point.
+ *   KISS: keep the public surface narrow — input, invoker, output.
+ */
+import type { MutationReport } from './types.js';
+export interface StrykerRawResult {
+    readonly mutantsTotal: number;
+    readonly mutantsKilled: number;
+    readonly mutantsSurvived: number;
+    readonly mutantsTimeout: number;
+    readonly perFile: ReadonlyArray<{
+        readonly file: string;
+        readonly killRate: number;
+        readonly survived: ReadonlyArray<{
+            line: number;
+            mutation: string;
+            survivedBecause: string;
+        }>;
+    }>;
+}
+export type StrykerInvoker = (opts: {
+    project: string;
+    testFiles: ReadonlyArray<string>;
+}) => Promise<StrykerRawResult>;
+export interface RunMutationInput {
+    readonly project: string;
+    readonly testFiles: ReadonlyArray<string>;
+    readonly invokeStryker: StrykerInvoker;
+}
+export interface RunMutationOutput {
+    readonly mutation: MutationReport;
+}
+export declare function runMutation(input: RunMutationInput): Promise<RunMutationOutput>;

package/dist/src/services/mut/mut-runner.js

@@ -0,0 +1,29 @@
+export async function runMutation(input) {
+    let raw;
+    try {
+        raw = await input.invokeStryker({
+            project: input.project,
+            testFiles: input.testFiles,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Stryker invocation failed: ${message}`);
+    }
+    const killRate = raw.mutantsTotal === 0 ? 0 : raw.mutantsKilled / raw.mutantsTotal;
+    return {
+        mutation: {
+            tool: 'stryker',
+            mutantsTotal: raw.mutantsTotal,
+            mutantsKilled: raw.mutantsKilled,
+            mutantsSurvived: raw.mutantsSurvived,
+            mutantsTimeout: raw.mutantsTimeout,
+            killRate,
+            byFile: raw.perFile.map((f) => ({
+                file: f.file,
+                killRate: f.killRate,
+                survived: f.survived,
+            })),
+        },
+    };
+}

package/dist/src/services/mut/production-stryker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Production Stryker invoker. Uses @stryker-mutator/core programmatic API.
+ * Note: this is a thin wrapper — actual Stryker invocation requires the
+ * Stryker config in `stryker.conf.js` to live at the project root.
+ */
+import type { StrykerInvoker } from './mut-runner.js';
+export declare function createProductionStrykerInvoker(): StrykerInvoker;