peaks-loop 4.0.0-beta → 4.0.0-beta.11

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

@@ -0,0 +1,143 @@
+/**
+ * peaks prd handoff CLI — v2.11.0 (Tier 3 in
+ * `v2-11-rd-techdoc-removal-and-runtime-friction`).
+ *
+ * Wires `services/prd/handoff-service.ts` to the command surface:
+ *
+ *   peaks prd handoff init   — produce + write a sha256-locked handoff
+ *   peaks prd handoff verify — re-read + recompute hash; report
+ *   peaks prd handoff show   — print the raw handoff markdown
+ *
+ * Help text MUST NOT reference the legacy `peaks prd write-handoff`
+ * subcommand (AC-1 in the v2.11.0 PRD). The legacy service module at
+ * `services/handoff/` is a separate slice-025 layout (different
+ * schema) and is intentionally not exposed here.
+ */
+import { readFile } from 'node:fs/promises';
+import { initHandoff, readHandoff, showHandoff, verifyHandoff, writeHandoff } from '../../services/prd/handoff-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** Split a comma-separated string into a trimmed, non-empty list.
+ *  Empty / undefined input → empty array. */
+function splitCsv(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Resolve the `--body` argument: if it starts with `@`, read the
+ *  referenced file as UTF-8; otherwise treat as a literal string. */
+async function resolveBody(bodyArg) {
+    if (bodyArg.startsWith('@')) {
+        const filePath = bodyArg.slice(1);
+        return readFile(filePath, 'utf8');
+    }
+    return bodyArg;
+}
+export function registerPrdCommands(program, io) {
+    const prd = program
+        .command('prd', { hidden: true })
+        .description('peaks-prd role: artifact + handoff primitives');
+    const handoff = prd.command('handoff').description('Write / verify / show the immutable PRD handoff (sha256-locked, schemaVersion: 2)');
+    // peaks prd handoff init
+    addJsonOption(handoff
+        .command('init')
+        .description('Initialize an immutable handoff: sha256(body) → frontmatter → write to .peaks/_runtime/<sid>/prd/handoff.md')
+        .requiredOption('--rid <request-id>', 'request id (e.g. 001-v2-11-cc-group-b)')
+        .requiredOption('--sid <session-id>', 'session id (e.g. 2026-06-26-session-a28d69)')
+        .requiredOption('--body <body>', 'handoff body markdown, or @<file> to read from disk')
+        .option('--goals <ids>', 'comma-separated goal ids (e.g. G1,G2,G3)')
+        .option('--ac <ids>', 'comma-separated acceptance-criteria ids (e.g. AC-1,AC-2)')
+        .option('--preserve <ids>', 'comma-separated preserved-behavior ids (e.g. P1,P12)')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--apply', 'actually write the file (default is dry-run preview)')).action(async (options) => {
+        try {
+            const body = await resolveBody(options.body);
+            const projectRoot = options.project ?? process.cwd();
+            const writtenAt = new Date().toISOString();
+            const handoff = initHandoff({
+                requestId: options.rid,
+                sessionId: options.sid,
+                body,
+                writtenAt,
+                goals: splitCsv(options.goals),
+                acceptanceCriteria: splitCsv(options.ac),
+                preservedBehavior: splitCsv(options.preserve),
+            });
+            if (options.apply !== true) {
+                printResult(io, ok('prd.handoff.init', {
+                    dryRun: true,
+                    requestId: handoff.frontmatter.requestId,
+                    sessionId: handoff.frontmatter.sessionId,
+                    schemaVersion: handoff.frontmatter.schemaVersion,
+                    handoffHash: handoff.frontmatter.handoffHash,
+                    handoffPath: handoff.frontmatter.handoffPath,
+                    bodyBytes: Buffer.byteLength(body, 'utf8'),
+                    goals: handoff.frontmatter.goals,
+                    acceptanceCriteria: handoff.frontmatter.acceptanceCriteria,
+                    preservedBehavior: handoff.frontmatter.preservedBehavior
+                }), options.json);
+                return;
+            }
+            const written = await writeHandoff(handoff, projectRoot);
+            printResult(io, ok('prd.handoff.init', {
+                applied: true,
+                path: written.path,
+                hash: written.hash,
+                requestId: handoff.frontmatter.requestId,
+                sessionId: handoff.frontmatter.sessionId
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('prd.handoff.init', 'HANDOFF_INIT_FAILED', getErrorMessage(error), { rid: options.rid, sid: options.sid }, ['Check --body syntax (@<file> or literal) and re-run']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks prd handoff verify
+    addJsonOption(handoff
+        .command('verify')
+        .description('Re-read a handoff file and re-compute the sha256; report ok or reason')
+        .requiredOption('--path <file>', 'absolute path to the handoff file')).action(async (options) => {
+        try {
+            const probe = await verifyHandoff(options.path);
+            if (!probe.ok) {
+                printResult(io, fail('prd.handoff.verify', 'HANDOFF_VERIFY_FAILED', probe.reason ?? 'unknown', probe, ['Re-init the handoff with `peaks prd handoff init --apply` to restore integrity']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('prd.handoff.verify', { ok: true, hash: probe.actualHash, path: options.path }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('prd.handoff.verify', 'HANDOFF_VERIFY_FAILED', getErrorMessage(error), { path: options.path }, ['Check the path and ensure the file is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks prd handoff show
+    addJsonOption(handoff
+        .command('show')
+        .description('Print the raw handoff markdown (frontmatter + body) for human display')
+        .requiredOption('--path <file>', 'absolute path to the handoff file')).action(async (options) => {
+        try {
+            const content = await showHandoff(options.path);
+            const handoff = await readHandoff(options.path);
+            if (options.json === true) {
+                printResult(io, ok('prd.handoff.show', {
+                    path: options.path,
+                    frontmatter: handoff.frontmatter,
+                    bodyBytes: Buffer.byteLength(content, 'utf8'),
+                    body: content
+                }), true);
+                return;
+            }
+            io.stdout(content);
+            if (!content.endsWith('\n'))
+                io.stdout('\n');
+        }
+        catch (error) {
+            printResult(io, fail('prd.handoff.show', 'HANDOFF_SHOW_FAILED', getErrorMessage(error), { path: options.path }, ['Check the path and ensure the file is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,253 @@
+import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
+import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
+import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerProjectCommands(program, io) {
+    const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
+    addJsonOption(project
+        .command('dashboard')
+        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / Understand Anything / capabilities for a project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--strict', 'ok follows the doctor aggregate (legacy semantics). Default: workspace-only (ok tracks the runbook health)', false)).action(async (options) => {
+        try {
+            const dashboard = await loadProjectDashboard({
+                projectRoot: options.project,
+                okPolicy: options.strict === true ? 'strict' : 'workspace-only'
+            });
+            if (!dashboard.runbookHealth.ok) {
+                const suggestions = [
+                    dashboard.runbookHealth.missingRunbook.length > 0
+                        ? `Add a ## Default runbook section to: ${dashboard.runbookHealth.missingRunbook.join(', ')}`
+                        : null,
+                    dashboard.runbookHealth.applyNoteFailed.length > 0
+                        ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${dashboard.runbookHealth.applyNoteFailed.join(', ')}`
+                        : null
+                ].filter((line) => line !== null);
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${dashboard.runbookHealth.healthy}/${dashboard.runbookHealth.required} healthy`, dashboard, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (dashboard.skillPresence.active && !dashboard.skillPresence.fresh) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_STALE_SKILL_PRESENCE', `Active Peaks skill presence ${dashboard.skillPresence.skill ?? '<unknown>'} is stale (set ${dashboard.skillPresence.setAt ?? '<unknown>'})`, dashboard, ['Run `peaks skill presence:clear` if the role has ended, or `peaks skill presence:set <skill>` to refresh it']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!dashboard.doctor.ok && options.strict === true) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_STRICT_FAIL', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed) — --strict mode requires the doctor aggregate to pass`, dashboard, ['Run `peaks doctor --json` and resolve the failing checks, or drop --strict to use the workspace-only policy']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('project.dashboard', dashboard), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(project
+        .command('context')
+        .description('Generate or read persistent project context for cross-session Peaks understanding. Generates BOTH `.peaks/PROJECT.md` (session history) AND `.peaks/project-scan/project-scan.md` (tech stack + archetypes) — see `peaks workspace init` for the full 5-template boot (G4b/AC9).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--read', 'read existing PROJECT.md without regenerating')).action(async (options) => {
+        try {
+            if (options.read) {
+                const content = readProjectContext(options.project);
+                if (content === null) {
+                    printResult(io, ok('project.context', { exists: false, path: `${options.project}/.peaks/PROJECT.md` }), options.json);
+                    return;
+                }
+                printResult(io, ok('project.context', { exists: true, path: `${options.project}/.peaks/PROJECT.md`, content }), options.json);
+                return;
+            }
+            const result = await generateProjectContext(options.project);
+            printResult(io, ok('project.context', {
+                path: result.path,
+                sessionCount: result.sessionCount,
+                content: result.content,
+                // Slice 2026-07-15-project-scan-bootstrap (G1 + G2): the
+                // context command also bootstraps the project-scan tree.
+                // The envelope surfaces write counts + duration so the LLM
+                // (and the user) see what landed.
+                projectScan: result.projectScan
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.context', 'PROJECT_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Extract memories from a session's artifacts into .peaks/memory ---
+    addJsonOption(project
+        .command('memories:extract')
+        .description('Scan a session artifact directory and extract <!-- peaks-memory:start --> blocks into .peaks/memory/')
+        .requiredOption('--session-id <id>', 'session id (e.g. 2026-05-29-session-89ff35)')
+        .requiredOption('--project <path>', 'target project root')
+        // Slice #015: drop the `--dry-run true` default. With the default
+        // set to true, `options.dryRun === true && options.apply === true`
+        // fired on every `--apply` call (because dryRun was true by
+        // default), permanently breaking `--apply`. `--dry-run` is now
+        // opt-in; the mutual-exclusion check below is correct without a
+        // special-case.
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into .peaks/memory/')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('project.memories:extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', { sessionId: options.sessionId, projectRoot: options.project }, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = extractSessionMemories({
+                projectRoot: options.project,
+                sessionId: options.sessionId,
+                apply: options.apply === true
+            });
+            printResult(io, ok('project.memories:extract', {
+                scannedFiles: result.scannedFiles,
+                extractedCount: result.extractedCount,
+                writtenFiles: result.writtenFiles,
+                memoryDir: result.primaryMemoryDir,
+                indexUpdated: result.updatedIndex
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Read memory index (lightweight, always-safe to load) ---
+    addJsonOption(project
+        .command('memory-index')
+        .description('Read the memory index — lightweight hot/warm分层 view of all project memories')
+        .requiredOption('--project <path>', 'target project root')).action((options) => {
+        try {
+            const index = readMemoryIndex(options.project);
+            if (!index) {
+                printResult(io, ok('project.memory-index', { exists: false, message: 'No memory index found. Run `peaks project memories:extract` first.' }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memory-index', { exists: true, index }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memory-index', 'MEMORY_INDEX_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
+    addJsonOption(project
+        .command('memories')
+        .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
+        try {
+            const result = readProjectMemories(options.project);
+            if (options.kind) {
+                const memories = result.memories.filter((memory) => memory.kind === options.kind);
+                printResult(io, ok('project.memories', {
+                    memoryDir: result.memoryDir,
+                    kind: options.kind,
+                    total: memories.length,
+                    memories
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memories', {
+                memoryDir: result.memoryDir,
+                total: result.total,
+                byKind: result.byKind,
+                memories: result.memories
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories', 'PROJECT_MEMORIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Show one project memory's body (R3: default = compact) ---
+    addJsonOption(project
+        .command('memories:show <name>')
+        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
+        .option('--include-stale', 'include stale entries (the default excludes them)')
+        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => {
+        try {
+            const memory = readProjectMemoryBody(options.project, name);
+            if (memory === null) {
+                printResult(io, fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: options.project }, ['Run `peaks project memories --json` to see available names']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Compute the stale decision. R4: stale is computed at CLI load time
+            // only; the source `.md` file is never modified.
+            const updatedAt = memory.updatedAt;
+            const thresholdDays = options.staleDays !== undefined && Number.isFinite(options.staleDays) && options.staleDays > 0
+                ? options.staleDays
+                : DEFAULT_STALE_DAYS;
+            const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
+                thresholdDays,
+                includeStale: options.includeStale === true
+            });
+            if (policy.entries.length === 0) {
+                const ageDays = policy.entries.length === 0 && policy.droppedCount > 0
+                    ? applyStalePolicy([{ name: memory.name, updatedAt }], { thresholdDays, includeStale: true }).entries[0]?.ageDays ?? 0
+                    : 0;
+                printResult(io, fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, ['Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const ageDays = policy.entries[0]?.ageDays ?? 0;
+            const isStale = policy.entries[0]?.stale ?? false;
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
+            printResult(io, ok('project.memories:show', {
+                name: memory.name,
+                title: memory.title,
+                kind: memory.kind,
+                sourcePath: memory.filePath,
+                updatedAt,
+                ageDays,
+                stale: isStale,
+                body,
+                format,
+                bodyBytes: Buffer.byteLength(body, 'utf8')
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Read business-knowledge sediment (v2.11.0 Group B — D3) ---
+    addJsonOption(project
+        .command('knowledge')
+        .description('Read .peaks/project-scan/business-knowledge.md (the schema-sedimented concept table). LLM-consumable; use --filter for a concept substring.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--filter <glob>', 'substring filter on the concept name (case-insensitive)')).action(async (options) => {
+        try {
+            const knowledge = await readBusinessKnowledge(options.project);
+            if (knowledge === null) {
+                printResult(io, ok('project.knowledge', { exists: false, projectRoot: options.project, path: `${options.project}/.peaks/project-scan/business-knowledge.md` }), options.json);
+                return;
+            }
+            const concepts = options.filter
+                ? knowledge.concepts.filter((c) => c.concept.toLowerCase().includes(options.filter.toLowerCase()))
+                : knowledge.concepts;
+            printResult(io, ok('project.knowledge', {
+                exists: true,
+                schemaVersion: knowledge.schemaVersion,
+                total: knowledge.concepts.length,
+                matched: concepts.length,
+                filter: options.filter ?? null,
+                concepts
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.knowledge', 'PROJECT_KNOWLEDGE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/project-scan directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,271 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G1, G2, G4, G5, G6.
+ *
+ * `peaks qa run` — runs a peaks-qa slice for the active project.
+ *
+ * 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 } from 'node:path';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.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 { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
+// Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
+import { loadMutReport, mutReportPath } from '../../services/mut/index.js';
+function buildHeadroomFetcher(sid) {
+    return createHeadroomFetcher({
+        cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
+        // remoteFetcher wired in a future slice (headroom-ai programmatic API).
+    });
+}
+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: buildHeadroomFetcher(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) {
+    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.
+ */
+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
+    };
+}
+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';
+            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;
+        }
+    });
+}