peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/qa-commands.js

@@ -1,324 +1,26 @@
 /**
+ * `peaks qa run` — the peaks-qa slice surface, and `peaks qa archive-screenshots`
+ * — the Contract 1 remediation. The verbs live beside this file:
  *
- * `peaks qa run` — runs a peaks-qa slice for the active project.
+ *   `qa-run-command.ts`                 the slice action (I/O + envelope)
+ *   `qa-run-slice.ts`                   the pure gate list it drives
+ *   `qa-run-options.ts`                 the `--no-X` flag contract
+ *   `qa-context-prestep.ts`              Plan 1 / Task 9 context build
+ *   `qa-archive-screenshots-command.ts` the stray-screenshot sweep
  *
- * The slice is the user-facing surface for the QA gate family
- * (functional / security / browser E2E). The browser-E2E gate
- * specifically is what the restart-loop detector guards. The
- * detector is wired into the slice here:
- *
- *   1. We construct a `BrowserRestartDetector` (configurable via
- *      `--max-browser-restarts` / `--no-restart-detector`).
- *   2. We construct a `BrowserEventLogger` that writes the
- *      per-slice JSONL log to
- *      `.peaks/_runtime/<session-id>/qa/browser-events.jsonl`.
- *   3. The slice entry exposes `runQaSlice` so tests can
- *      feed a synthetic event log and assert the diagnostic.
- *
- * CLI surface (PRD G5 + AC4/AC5/AC6):
- *   peaks qa run --project <X> [--no-browser] [--max-browser-restarts N]
- *                       [--no-restart-detector] [--session-id <sid>] [--json]
- *
- * `--no-browser` (G5) skips the browser E2E gate entirely. The
- * resulting gate list marks the browser gate as `status: skipped`
- * with reason `--no-browser`. This is a slice-level opt-out for
- * backend-only or already-covered-by-unit-tests work.
- */
-import { join, resolve } from 'node:path';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { archiveScreenshots } from '../../services/qa/screenshot-archive-service.js';
-import { isUnsafePathInput } from '../../shared/path-safety.js';
-import { getSessionId } from '../../services/session/session-manager.js';
-import { BrowserRestartDetector } from '../../services/qa/browser-restart-detector.js';
-import { BrowserEventLogger } from '../../services/qa/browser-event-logger.js';
-import { BROWSER_REUSE_HINT } from '../../services/qa/browser-reuse-hint.js';
-// Plan 1 / Task 9 — auto-build peaks-context before peaks-qa runs.
-import { buildContext } from '../../services/context/context-builder.js';
-// Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
-import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
-// Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
-import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
-function buildDocFetcher(sid) {
-    return createDocCacheFetcher({
-        cacheDir: `.peaks/_runtime/${sid}/doc-cache`
-        // remoteFetcher wired in a future slice.
-    });
-}
-async function ensureContextForQa(goal, project, sid) {
-    const out = `.peaks/_runtime/${sid}/context.json`;
-    try {
-        await buildContext({
-            goal,
-            project,
-            audience: 'peaks-qa',
-            depsMode: 'locked',
-            docBudgetTokens: 8000,
-            out,
-            fetcher: buildDocFetcher(sid)
-        });
-    }
-    catch (error) {
-        // Plan 1 / Task 9 — context is a pre-step, not a precondition.
-        // Task 11 will upgrade this to a hard precondition once the qa
-        // slice actually consumes context.json.
-        const message = error instanceof Error ? error.message : 'unknown context build failure';
-        process.stderr.write(`[peaks-context] qa pre-step skipped: ${message}\n`);
-    }
-}
-export const DEFAULT_MAX_BROWSER_RESTARTS = 3;
-export function runQaSlice(input) {
-    // Sid axis: this is the join for `qa/browser-events.jsonl`. The `qa gate run`
-    // action guards before calling in, but the function is exported for tests and
-    // states its own contract at the join.
-    if (isUnsafePathInput(input.sessionId)) {
-        throw new Error(`Invalid session id: ${input.sessionId} (must be a single path segment)`);
-    }
-    const detector = new BrowserRestartDetector({
-        maxRestarts: input.maxRestarts,
-        enabled: input.detectorEnabled
-    });
-    const logPath = join(input.project, '.peaks', '_runtime', input.sessionId, 'qa', 'browser-events.jsonl');
-    const logger = new BrowserEventLogger({ filePath: logPath });
-    let pendingCloseTs = null;
-    // PRD AC4 + P1: when browser E2E is off, the detector must NOT
-    // record events at all (otherwise a user passing both
-    // --no-browser AND a hot detector would see spurious
-    // detectorTriggered=true and exit code 2).
-    if (input.browserEnabled) {
-        for (const ev of input.events) {
-            detector.record(ev);
-            if (ev.tool === 'browser_close') {
-                pendingCloseTs = ev.ts;
-            }
-            else if (ev.tool === 'browser_navigate' && pendingCloseTs !== null) {
-                const closeMs = Date.parse(pendingCloseTs);
-                const navMs = Date.parse(ev.ts);
-                logger.append({
-                    kind: 'spurious_restart',
-                    ts: ev.ts,
-                    sessionId: input.sessionId,
-                    closeTs: pendingCloseTs,
-                    navigateTs: ev.ts,
-                    deltaMs: navMs - closeMs
-                });
-                pendingCloseTs = null;
-            }
-            else if (ev.tool === 'browser_navigate') {
-                pendingCloseTs = null;
-            }
-        }
-    }
-    const browserGate = input.browserEnabled
-        ? detector.shouldHalt()
-            ? { name: 'browser-e2e', status: 'failed', reason: detector.diagnostic() }
-            : { name: 'browser-e2e', status: 'passed' }
-        : { name: 'browser-e2e', status: 'skipped', reason: '--no-browser' };
-    // Plan 2 / Task 8 — MUT.sig gate.
-    // Gate semantics (per spec lines 1292-1341):
-    //   - `skipped` when peaks-mut was not run (no report) OR --no-mutation
-    //   - `passed`  when the report's `thresholds.passed` is true
-    //   - `failed`  when the report's `thresholds.passed` is false
-    // "Skipped" is NOT a failure — the gate is a no-op so existing
-    // sessions that have not yet adopted peaks-mut keep passing.
-    const mutationGate = !input.mutationEnabled
-        ? { name: 'mutation', status: 'skipped', reason: '--no-mutation' }
-        : input.mutationReport === null
-            ? { name: 'mutation', status: 'skipped', reason: 'peaks mut not run' }
-            : input.mutationReport.thresholds.passed
-                ? {
-                    name: 'mutation',
-                    status: 'passed',
-                    mutSig: input.mutationReport.sha256
-                }
-                : {
-                    name: 'mutation',
-                    status: 'failed',
-                    reason: deriveMutationFailureReason(input.mutationReport),
-                    mutSig: input.mutationReport.sha256
-                };
-    const gates = [
-        { name: 'functional', status: 'passed' },
-        { name: 'security', status: 'passed' },
-        browserGate,
-        mutationGate
-    ];
-    return {
-        sessionId: input.sessionId,
-        project: input.project,
-        browserEnabled: input.browserEnabled,
-        gates,
-        detectorTriggered: detector.shouldHalt(),
-        ...(detector.shouldHalt() ? { diagnostic: detector.diagnostic() } : {}),
-        subAgentPromptHint: BROWSER_REUSE_HINT,
-        // Surface MUT.sig ONLY when the gate is actually evaluated
-        // (mutation enabled AND a report was loaded). --no-mutation or
-        // missing report -> undefined, so downstream consumers cannot
-        // mistake a skipped gate for a chain-trail anchor.
-        ...(input.mutationEnabled && input.mutationReport !== null
-            ? { mutSig: input.mutationReport.sha256 }
-            : {})
-    };
-}
-/**
- * Plan 2 / Task 8 — pure helper that explains WHY the mutation gate
- * failed. Used only when the report's `thresholds.passed` is false.
- * Reads the threshold block from the report itself (already
- * CLI-computed by `buildMutReport`) so the message matches what
- * peaks-mut's CLI surface prints.
+ * This module owns only the `qa` parent (hidden) and the registrar order, and
+ * re-exports every symbol it used to define so existing importers need no edit.
  */
-function deriveMutationFailureReason(report) {
-    const t = report.thresholds;
-    const fragments = [];
-    if (report.mutation.killRate < t.mutationKillRateMin) {
-        fragments.push(`mutation kill rate ${report.mutation.killRate.toFixed(2)} < ${t.mutationKillRateMin.toFixed(2)}`);
-    }
-    if (report.assertions.weakRate > t.weakAssertionRateMax) {
-        fragments.push(`weak assertion rate ${report.assertions.weakRate.toFixed(2)} > ${t.weakAssertionRateMax.toFixed(2)}`);
-    }
-    if (fragments.length === 0) {
-        return `mutation thresholds failed (MUT.sig=${report.sha256})`;
-    }
-    return `${fragments.join('; ')} (MUT.sig=${report.sha256})`;
-}
-function resolveMaxRestarts(raw) {
-    if (raw === undefined)
-        return DEFAULT_MAX_BROWSER_RESTARTS;
-    const n = Number.parseInt(raw, 10);
-    if (Number.isNaN(n) || n < 1) {
-        return DEFAULT_MAX_BROWSER_RESTARTS;
-    }
-    return n;
-}
-/**
- * Commander 12.x sets `options.X = false` for `--no-X` (POSITIVE form),
- * not `options.noX = true`. Reads use the positive form; the default is
- * `true` and the boolean form is `false` only when the user passes `--no-X`.
- *
- * Exported for unit testing the parser contract in isolation from
- * the rest of the action handler.
- */
-export function readQaRunOptions(options) {
-    return {
-        browserEnabled: options.browser !== false,
-        detectorEnabled: options.restartDetector !== false,
-        maxRestarts: resolveMaxRestarts(options.maxBrowserRestarts),
-        mutationEnabled: options.mutation !== false
-    };
-}
+import { registerQaArchiveScreenshotsCommand } from './qa-archive-screenshots-command.js';
+import { registerQaRunCommand } from './qa-run-command.js';
 export function registerQaCommands(program, io) {
     const qa = program
         .command('qa', { hidden: true })
         .description('peaks-qa slice: run QA gates (functional / security / browser E2E / mutation) for the active project');
-    addJsonOption(qa
-        .command('run')
-        .description('Run the peaks-qa slice (PRD 2026-06-16-playwright-restart-loop; Plan 2 mut gate)')
-        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')
-        .option('--session-id <sid>', 'session id; defaults to "ad-hoc" for one-shot runs', 'ad-hoc')
-        .option('--no-browser', 'skip the browser E2E gate entirely (PRD G5 / AC4)')
-        .option('--max-browser-restarts <n>', 'halt threshold for close->navigate pairs in this slice (default 3, PRD AC5)', String(DEFAULT_MAX_BROWSER_RESTARTS))
-        .option('--no-restart-detector', 'disable the restart-loop detector escape hatch (PRD AC6)')
-        // Plan 2 / Task 8 — MUT.sig gate opt-out (mirrors --no-browser).
-        .option('--no-mutation', 'skip the mutation gate even if .peaks/_runtime/<sid>/mut/mut-report.json exists')).action(async (options) => {
-        try {
-            const { browserEnabled, detectorEnabled, maxRestarts, mutationEnabled } = readQaRunOptions(options);
-            // Plan 1 / Task 9 — pre-build peaks-context before peaks-qa runs.
-            // Goal is audience-scoped doc retrieval only; pass a placeholder
-            // when the user did not supply one.
-            const qaProject = options.project;
-            const qaSid = options.sessionId ?? 'ad-hoc';
-            // Sid axis. `--session-id` reaches three consumers below — the context
-            // pre-build, `loadMutReport`, and `runQaSlice`'s
-            // `qa/browser-events.jsonl` join — so one guard at resolution covers all
-            // three. (`peaks qa archive-screenshots` has its own, separate join.)
-            if (isUnsafePathInput(qaSid)) {
-                printResult(io, fail('qa.gate', 'INVALID_SESSION_ID', `Invalid session id: ${qaSid} (must be a single path segment)`, { provided: qaSid }, ['Pass a session id that is a single path segment']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            await ensureContextForQa('qa gate run', qaProject, qaSid);
-            // Plan 2 / Task 8 — load peaks-mut's report (MUT.sig) if present.
-            // Returns null when peaks-mut was not run; the gate treats that
-            // as `skipped`, never as `failed`. loadMutReport itself never
-            // throws (per its docstring) so this is safe in the action.
-            const mutationReport = mutationEnabled ? await loadMutReport(qaSid) : null;
-            // Production slice: no synthetic events to feed; in real
-            // dogfood the LLM tool dispatcher would push events into the
-            // detector. Here we record an empty event log so the
-            // gate-list shape is stable for downstream parsers.
-            const result = runQaSlice({
-                project: options.project,
-                sessionId: options.sessionId ?? 'ad-hoc',
-                browserEnabled,
-                maxRestarts,
-                detectorEnabled,
-                events: [],
-                mutationReport,
-                mutationEnabled
-            });
-            const mutationGate = result.gates.find((g) => g.name === 'mutation');
-            const mutationFailed = mutationGate?.status === 'failed';
-            const nextActions = result.detectorTriggered
-                ? [
-                    'Stop the slice and inspect the diagnostic above',
-                    'Re-run with --no-restart-detector if the close/reopen was intentional',
-                    'See .peaks/memory/playwright-restart-loop-2026-06-16.md'
-                ]
-                : mutationFailed
-                    ? [
-                        'Re-run peaks mut and address the threshold breaches (see reason)',
-                        'Re-run with --no-mutation to bypass the gate for this slice',
-                        `mut-report path: ${mutReportPath(qaSid)}`
-                    ]
-                    : browserEnabled
-                        ? ['No action required; browser gate passed']
-                        : ['Browser E2E skipped; run without --no-browser when the slice needs E2E'];
-            printResult(io, ok('qa.run', result, [], nextActions), options.json);
-            if (result.detectorTriggered || mutationFailed) {
-                process.exitCode = 2;
-            }
-        }
-        catch (error) {
-            printResult(io, fail('qa.run', 'QA_RUN_FAILED', error instanceof Error ? error.message : 'Unknown error', { project: options.project }, ['Check the project path and rerun']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // Enforces peaks-qa SKILL.md "Hard contracts for browser validation"
-    // Contract 1: every Playwright `browser_take_screenshot` MUST land under
-    // `.peaks/_runtime/<sessionId>/qa/screenshots/`, not at the project root.
-    // When the LLM forgets to pass `filename`, Playwright MCP scatters
-    // `.png` files at the repo top level. This subcommand is the
-    // remediation: scan `--source` (default: project root) and move stray
-    // screenshots into `.peaks/_runtime/<session-id>/qa/screenshots/`.
-    addJsonOption(qa
-        .command('archive-screenshots')
-        .description('Move stray Playwright screenshots (.png/.jpg/.jpeg) from the ' +
-        'project root into .peaks/_runtime/<session-id>/qa/screenshots/. ' +
-        'Enforces peaks-qa SKILL.md Contract 1.')
-        .option('--source <dir>', 'directory to scan for stray screenshots (default: project root)', '.')
-        .option('--project <path>', 'project root (default: cwd)', '.')
-        .option('--session-id <sid>', 'target session id; defaults to the active session', '')).action((options) => {
-        try {
-            const projectRoot = resolve(options.project);
-            const sid = options.sessionId?.trim() || getSessionId(projectRoot) || 'ad-hoc';
-            // Sid axis. Guarded after resolution so the flag value and the session
-            // binding are both covered. `archiveScreenshots` cannot do this itself:
-            // it only ever sees a fully-resolved `targetDir`.
-            if (isUnsafePathInput(sid)) {
-                throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
-            }
-            const targetDir = join(projectRoot, '.peaks', '_runtime', sid, 'qa', 'screenshots');
-            const envelope = archiveScreenshots({ sourceDir: options.source, targetDir });
-            printResult(io, ok('qa.archive-screenshots', envelope, [], envelope.moved.length === 0
-                ? ['No stray screenshots found in ' + envelope.scannedSource]
-                : [
-                    `Moved ${envelope.moved.length} file(s) to ${envelope.targetDir}`,
-                    'Re-run peaks qa run to verify the gate passes'
-                ]), options.json);
-        }
-        catch (error) {
-            process.exitCode = 1;
-            printResult(io, fail('qa.archive-screenshots', 'ARCHIVE_FAILED', error instanceof Error ? error.message : 'Unknown error', { project: options.project, source: options.source }, ['Verify the source dir exists and is readable']), options.json);
-        }
-    });
+    registerQaRunCommand(qa, io);
+    registerQaArchiveScreenshotsCommand(qa, io);
 }
+// Re-export for tests / external consumers; the implementations moved to the
+// modules above with the split.
+export { readQaRunOptions } from './qa-run-options.js';
+export { DEFAULT_MAX_BROWSER_RESTARTS, runQaSlice } from './qa-run-slice.js';

package/dist/cli/commands/qa-context-prestep.d.ts

@@ -0,0 +1 @@
+export declare function ensureContextForQa(goal: string, project: string, sid: string): Promise<void>;

package/dist/cli/commands/qa-context-prestep.js

@@ -0,0 +1,34 @@
+// src/cli/commands/qa-context-prestep.ts
+//
+// Plan 1 / Task 9 — the peaks-context build that runs BEFORE a peaks-qa slice.
+// Extracted from `qa-commands.ts`; the cache dir, the token budget and the
+// never-block contract are unchanged.
+import { buildContext } from '../../services/context/context-builder.js';
+import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.js';
+function buildDocFetcher(sid) {
+    return createDocCacheFetcher({
+        cacheDir: `.peaks/_runtime/${sid}/doc-cache`
+        // remoteFetcher wired in a future slice.
+    });
+}
+export async function ensureContextForQa(goal, project, sid) {
+    const out = `.peaks/_runtime/${sid}/context.json`;
+    try {
+        await buildContext({
+            goal,
+            project,
+            audience: 'peaks-qa',
+            depsMode: 'locked',
+            docBudgetTokens: 8000,
+            out,
+            fetcher: buildDocFetcher(sid)
+        });
+    }
+    catch (error) {
+        // Plan 1 / Task 9 — context is a pre-step, not a precondition.
+        // Task 11 will upgrade this to a hard precondition once the qa
+        // slice actually consumes context.json.
+        const message = error instanceof Error ? error.message : 'unknown context build failure';
+        process.stderr.write(`[peaks-context] qa pre-step skipped: ${message}\n`);
+    }
+}

package/dist/cli/commands/qa-run-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerQaRunCommand(qa: Command, io: ProgramIO): void;

package/dist/cli/commands/qa-run-command.js

@@ -0,0 +1,105 @@
+// src/cli/commands/qa-run-command.ts
+//
+// `peaks qa run` — the peaks-qa slice (functional / security / browser E2E /
+// mutation gates) for the active project. Extracted from `qa-commands.ts`:
+//
+//   1. `--no-browser` (G5) skips the browser E2E gate entirely; the resulting
+//      gate list marks it `status: skipped`, reason `--no-browser`. This is a
+//      slice-level opt-out for backend-only or already-covered-by-unit-tests
+//      work.
+//   2. Plan 2 / Task 8 — `loadMutReport` supplies the MUT.sig gate; a missing
+//      report is `skipped`, never `failed`.
+//   3. The LLM tool dispatcher would push browser events into the detector in
+//      real dogfood; here the slice records an empty event log so the gate-list
+//      shape stays stable for downstream parsers.
+//
+// The registered name, description, options, envelope and exit codes are
+// unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ensureContextForQa } from './qa-context-prestep.js';
+import { readQaRunOptions } from './qa-run-options.js';
+import { DEFAULT_MAX_BROWSER_RESTARTS, runQaSlice } from './qa-run-slice.js';
+export function registerQaRunCommand(qa, io) {
+    addJsonOption(qaRunCommand(qa)).action((options) => runQaRun(io, options));
+}
+/** The `run` verb's description and its six options, verbatim. */
+function qaRunCommand(qa) {
+    return (qa
+        .command('run')
+        .description('Run the peaks-qa slice (PRD 2026-06-16-playwright-restart-loop; Plan 2 mut gate)')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')
+        .option('--session-id <sid>', 'session id; defaults to "ad-hoc" for one-shot runs', 'ad-hoc')
+        .option('--no-browser', 'skip the browser E2E gate entirely (PRD G5 / AC4)')
+        .option('--max-browser-restarts <n>', 'halt threshold for close->navigate pairs in this slice (default 3, PRD AC5)', String(DEFAULT_MAX_BROWSER_RESTARTS))
+        .option('--no-restart-detector', 'disable the restart-loop detector escape hatch (PRD AC6)')
+        // Plan 2 / Task 8 — MUT.sig gate opt-out (mirrors --no-browser).
+        .option('--no-mutation', 'skip the mutation gate even if .peaks/_runtime/<sid>/mut/mut-report.json exists'));
+}
+async function runQaRun(io, options) {
+    try {
+        const { browserEnabled, detectorEnabled, maxRestarts, mutationEnabled } = readQaRunOptions(options);
+        const qaSid = options.sessionId ?? 'ad-hoc';
+        // Sid axis. `--session-id` reaches three consumers below — the context
+        // pre-build, `loadMutReport`, and `runQaSlice`'s
+        // `qa/browser-events.jsonl` join — so one guard at resolution covers all
+        // three. (`peaks qa archive-screenshots` has its own, separate join.)
+        if (isUnsafePathInput(qaSid)) {
+            printResult(io, unsafeSessionEnvelope(qaSid), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // Plan 1 / Task 9 — pre-build peaks-context before peaks-qa runs.
+        // Goal is audience-scoped doc retrieval only; pass a placeholder
+        // when the user did not supply one.
+        await ensureContextForQa('qa gate run', options.project, qaSid);
+        const mutationReport = mutationEnabled
+            ? await loadMutReport(qaSid)
+            : null;
+        const result = runQaSlice({
+            project: options.project,
+            sessionId: qaSid,
+            browserEnabled,
+            maxRestarts,
+            detectorEnabled,
+            events: [],
+            mutationReport,
+            mutationEnabled
+        });
+        const mutationFailed = result.gates.find((g) => g.name === 'mutation')?.status === 'failed';
+        printResult(io, ok('qa.run', result, [], qaRunNextActions({ result, browserEnabled, mutationFailed, qaSid })), options.json);
+        if (result.detectorTriggered || mutationFailed) {
+            process.exitCode = 2;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('qa.run', 'QA_RUN_FAILED', error instanceof Error ? error.message : 'Unknown error', { project: options.project }, ['Check the project path and rerun']), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The refusal for a `--session-id` that is not a single path segment. */
+function unsafeSessionEnvelope(qaSid) {
+    return fail('qa.gate', 'INVALID_SESSION_ID', `Invalid session id: ${qaSid} (must be a single path segment)`, { provided: qaSid }, ['Pass a session id that is a single path segment']);
+}
+/** What the caller should do next, by the gate that decided the slice's outcome. */
+function qaRunNextActions(input) {
+    if (input.result.detectorTriggered) {
+        return [
+            'Stop the slice and inspect the diagnostic above',
+            'Re-run with --no-restart-detector if the close/reopen was intentional',
+            'See .peaks/memory/playwright-restart-loop-2026-06-16.md'
+        ];
+    }
+    if (input.mutationFailed) {
+        return [
+            'Re-run peaks mut and address the threshold breaches (see reason)',
+            'Re-run with --no-mutation to bypass the gate for this slice',
+            `mut-report path: ${mutReportPath(input.qaSid)}`
+        ];
+    }
+    return input.browserEnabled
+        ? ['No action required; browser gate passed']
+        : ['Browser E2E skipped; run without --no-browser when the slice needs E2E'];
+}

package/dist/cli/commands/qa-run-options.d.ts

@@ -0,0 +1,23 @@
+export type QaRunOptions = {
+    project: string;
+    browser?: boolean;
+    restartDetector?: boolean;
+    maxBrowserRestarts?: string;
+    sessionId?: string;
+    json?: boolean;
+    mutation?: boolean;
+};
+/**
+ * Commander 12.x sets `options.X = false` for `--no-X` (POSITIVE form),
+ * not `options.noX = true`. Reads use the positive form; the default is
+ * `true` and the boolean form is `false` only when the user passes `--no-X`.
+ *
+ * Exported for unit testing the parser contract in isolation from
+ * the rest of the action handler.
+ */
+export declare function readQaRunOptions(options: QaRunOptions): {
+    readonly browserEnabled: boolean;
+    readonly detectorEnabled: boolean;
+    readonly maxRestarts: number;
+    readonly mutationEnabled: boolean;
+};

package/dist/cli/commands/qa-run-options.js

@@ -0,0 +1,31 @@
+// src/cli/commands/qa-run-options.ts
+//
+// The `peaks qa run` flag contract, parsed in isolation from the action handler
+// so unit tests can assert it without a project on disk. Extracted from
+// `qa-commands.ts`; every default and every reading is unchanged.
+import { DEFAULT_MAX_BROWSER_RESTARTS } from './qa-run-slice.js';
+function resolveMaxRestarts(raw) {
+    if (raw === undefined)
+        return DEFAULT_MAX_BROWSER_RESTARTS;
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n < 1) {
+        return DEFAULT_MAX_BROWSER_RESTARTS;
+    }
+    return n;
+}
+/**
+ * Commander 12.x sets `options.X = false` for `--no-X` (POSITIVE form),
+ * not `options.noX = true`. Reads use the positive form; the default is
+ * `true` and the boolean form is `false` only when the user passes `--no-X`.
+ *
+ * Exported for unit testing the parser contract in isolation from
+ * the rest of the action handler.
+ */
+export function readQaRunOptions(options) {
+    return {
+        browserEnabled: options.browser !== false,
+        detectorEnabled: options.restartDetector !== false,
+        maxRestarts: resolveMaxRestarts(options.maxBrowserRestarts),
+        mutationEnabled: options.mutation !== false
+    };
+}

package/dist/cli/commands/qa-run-slice.d.ts

@@ -0,0 +1,41 @@
+import type { MutReportJson } from 'peaks-loop-mut';
+import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
+export type QaGateStatus = {
+    readonly name: string;
+    readonly status: 'passed' | 'skipped' | 'failed';
+    readonly reason?: string;
+    /**
+     * Plan 2 / Task 8 — when the gate consumes an artifact with a
+     * deterministic signature, this field carries that signature for
+     * downstream audit-trail consumers. Currently set only on the
+     * `mutation` gate to MUT.sig (the `sha256` of mut-report.json).
+     */
+    readonly mutSig?: string;
+};
+export type QaRunResult = {
+    readonly sessionId: string;
+    readonly project: string;
+    readonly browserEnabled: boolean;
+    readonly gates: readonly QaGateStatus[];
+    readonly detectorTriggered: boolean;
+    readonly diagnostic?: string;
+    readonly subAgentPromptHint: string;
+    /**
+     * Plan 2 / Task 8 — MUT.sig when peaks-mut ran in this session.
+     * Undefined when peaks-mut was not run (no mut-report.json) or
+     * the user passed --no-mutation.
+     */
+    readonly mutSig?: string;
+};
+export type RunQaSliceInput = {
+    readonly project: string;
+    readonly sessionId: string;
+    readonly browserEnabled: boolean;
+    readonly maxRestarts: number;
+    readonly detectorEnabled: boolean;
+    readonly events: readonly BrowserEvent[];
+    readonly mutationReport: MutReportJson | null;
+    readonly mutationEnabled: boolean;
+};
+export declare const DEFAULT_MAX_BROWSER_RESTARTS = 3;
+export declare function runQaSlice(input: RunQaSliceInput): QaRunResult;