peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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-business-review-commands.d.ts

@@ -0,0 +1,17 @@
+/**
+ * v2.15.0 follow-up — G5: QA business-perspective review CLI.
+ *
+ *   - `peaks qa business-review <request-id>`        — show the 6-item
+ *                                                    business checklist
+ *   - `peaks qa business-score <rid> --item --score` — record a single
+ *                                                    item score (1-5)
+ *   - `peaks qa business-accept <rid>`              — mark accepted
+ *   - `peaks qa business-reject <rid> --reason`     — mark rejected
+ *
+ * The 12 Gaps positioning memory: QA business layer (user reviews
+ * 6 product items) is decoupled from QA technical layer (AI
+ * auto-decides coverage / P99 / security).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerQaBusinessReviewCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,148 @@
+/**
+ * v2.15.0 follow-up — G5: QA business-perspective review CLI.
+ *
+ *   - `peaks qa business-review <request-id>`        — show the 6-item
+ *                                                    business checklist
+ *   - `peaks qa business-score <rid> --item --score` — record a single
+ *                                                    item score (1-5)
+ *   - `peaks qa business-accept <rid>`              — mark accepted
+ *   - `peaks qa business-reject <rid> --reason`     — mark rejected
+ *
+ * The 12 Gaps positioning memory: QA business layer (user reviews
+ * 6 product items) is decoupled from QA technical layer (AI
+ * auto-decides coverage / P99 / security).
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { acceptQaReview, buildEmptyQaReview, deriveQaDecision, QA_BUSINESS_ITEMS, readQaReview, rejectQaReview, scoreQaItem, writeQaReview } from '../../services/qa/qa-business-review-state.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerQaBusinessReviewCommands(program, io) {
+    // G5 commands registered as TOP-LEVEL commands prefixed with `qa-business-`
+    // to avoid colliding with the existing `peaks qa` role commands
+    // (registered by qa-commands.ts, used for qa subcommands on qa artifacts).
+    // See similar approach in user-touchpoint-commands.ts.
+    // 1. business-review
+    addJsonOption(program
+        .command('qa-business-review <request-id>')
+        .description('Show the 6-item business checklist for a request (the 12 Gaps ' +
+        'QA perspective). If no review exists, a new one is created ' +
+        '(pending state).')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: cwd)')).action((requestId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        let review = readQaReview(projectRoot, sessionId, requestId);
+        if (review === null) {
+            review = buildEmptyQaReview(requestId, sessionId);
+            writeQaReview(projectRoot, review);
+        }
+        const scoredCount = review.items.filter((it) => it.score !== null).length;
+        const avg = review.items.filter((it) => it.score !== null).length === 0
+            ? null
+            : review.items.reduce((s, it) => s + (it.score ?? 0), 0) / scoredCount;
+        printResult(io, ok('qa.business-review', {
+            sessionId,
+            requestId,
+            decision: review.decision,
+            derivedDecision: deriveQaDecision(review),
+            items: review.items,
+            scoredCount,
+            averageScore: avg
+        }, review.decision === 'pending' ? [
+            `Score each item with: peaks qa business-score <rid> --item <id> --score <1-5>`,
+            'When all items are scored, run: peaks qa business-accept <rid>'
+        ] : [], review.decision === 'rejected' ? [
+            `Rejected: ${review.rejectionReason ?? '(no reason)'}`
+        ] : []), opts.json ?? false);
+    });
+    // 2. business-score
+    addJsonOption(program
+        .command('qa-business-score <request-id>')
+        .description('Record a single business item score (1-5). Threshold: avg >= 3 ' +
+        'AND no item <= 2 → accepted; otherwise rejected.')
+        .requiredOption('--item <id>', `item id (${QA_BUSINESS_ITEMS.map((i) => i.id).join(' | ')})`)
+        .requiredOption('--score <1-5>', 'score (1-5)')
+        .option('--note <text>', 'optional note')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')).action((requestId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const score = Number.parseInt(opts.score, 10);
+        if (Number.isNaN(score) || score < 1 || score > 5) {
+            printResult(io, fail('qa.business-score', 'INVALID_SCORE', `--score must be 1-5 (got "${opts.score}")`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        let review = readQaReview(projectRoot, sessionId, requestId);
+        if (review === null) {
+            review = buildEmptyQaReview(requestId, sessionId);
+        }
+        const validIds = QA_BUSINESS_ITEMS.map((i) => i.id);
+        if (!validIds.includes(opts.item)) {
+            printResult(io, fail('qa.business-score', 'UNKNOWN_ITEM', `unknown item "${opts.item}" (valid: ${validIds.join(', ')})`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = scoreQaItem(review, opts.item, score, opts.note);
+        writeQaReview(projectRoot, next);
+        printResult(io, ok('qa.business-score', {
+            sessionId,
+            requestId,
+            item: opts.item,
+            score,
+            derivedDecision: deriveQaDecision(next)
+        }, [], [
+            deriveQaDecision(next) === 'accepted'
+                ? 'All items now average >= 3. Run `peaks qa business-accept` to confirm.'
+                : 'Score recorded. Continue scoring other items.'
+        ]), opts.json ?? false);
+    });
+    // 3. business-accept
+    addJsonOption(program
+        .command('qa-business-accept <request-id>')
+        .description('Mark the QA business review as accepted (derived decision must be "accepted").')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')).action((requestId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const review = readQaReview(projectRoot, sessionId, requestId);
+        if (review === null) {
+            printResult(io, fail('qa.business-accept', 'NO_REVIEW', `no review found for request "${requestId}"`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const derived = deriveQaDecision(review);
+        if (derived !== 'accepted') {
+            printResult(io, fail('qa.business-accept', 'CANNOT_ACCEPT', `derived decision is "${derived}" — cannot accept`, { projectRoot, review }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = acceptQaReview(review);
+        writeQaReview(projectRoot, next);
+        printResult(io, ok('qa.business-accept', { sessionId, requestId, decision: 'accepted', updatedAt: next.updatedAt }, [], [
+            'QA business layer accepted. Proceed to final review.'
+        ]), opts.json ?? false);
+    });
+    // 4. business-reject
+    addJsonOption(program
+        .command('qa-business-reject <request-id>')
+        .description('Mark the QA business review as rejected with a reason. Back to RD repair-loop.')
+        .requiredOption('--reason <text>', 'rejection reason (required)')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')).action((requestId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const review = readQaReview(projectRoot, sessionId, requestId);
+        if (review === null) {
+            printResult(io, fail('qa.business-reject', 'NO_REVIEW', `no review found for request "${requestId}"`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = rejectQaReview(review, opts.reason);
+        writeQaReview(projectRoot, next);
+        printResult(io, ok('qa.business-reject', { sessionId, requestId, decision: 'rejected', reason: opts.reason, updatedAt: next.updatedAt }, [], [
+            'QA business layer rejected. Hand back to RD repair-loop.'
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,94 @@
+/**
+ * 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 { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
+import type { MutReportJson } from '../../services/mut/types.js';
+export type QaRunOptions = {
+    project: string;
+    browser?: boolean;
+    restartDetector?: boolean;
+    maxBrowserRestarts?: string;
+    sessionId?: string;
+    json?: boolean;
+    mutation?: boolean;
+};
+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 declare const DEFAULT_MAX_BROWSER_RESTARTS = 3;
+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 function runQaSlice(input: RunQaSliceInput): QaRunResult;
+/**
+ * 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;
+};
+export declare function registerQaCommands(program: Command, io: ProgramIO): void;