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

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

@@ -1,271 +0,0 @@
-/**
- * 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')
-        .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;
-        }
-    });
-}

package/dist/src/cli/commands/sc-commands.js

@@ -1,45 +0,0 @@
-import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilityStatus, getScHelpText, recordCommitBoundary, validateArtifactRetention } from '../../services/sc/sc-service.js';
-import { ok } from '../../shared/result.js';
-import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
-export function registerSCCommands(program, io) {
-    const sc = program.command('sc').description('Source control and change traceability (peaks-sc integration)');
-    registerSCStatusCommands(sc, io);
-    registerSCArtifactCommands(sc, io);
-}
-function registerSCStatusCommands(sc, io) {
-    addJsonOption(sc.command('status').description('Show change traceability status')).action((options) => {
-        printResult(io, ok('sc.status', getChangeTraceabilityStatus()), options.json);
-    });
-    addJsonOption(sc.command('help').description('Show peaks-sc help text')).action((options) => {
-        const helpText = getScHelpText().join('\n');
-        if (options.json) {
-            printResult(io, ok('sc.help', { helpText }), options.json);
-        }
-        else {
-            io.stdout(helpText);
-        }
-    });
-}
-function registerSCArtifactCommands(sc, io) {
-    // Slice 2026-06-29-change-id-root-removal: `--change-id` is no
-    // longer accepted on `peaks sc impact`. The CLI surfaces a
-    // per-`(module, file)` impact report without a top-level
-    // change-id binding.
-    addJsonOption(sc.command('impact').description('Generate change impact artifact').option('--module <module>', 'affected module', multipleOption).option('--file <file>', 'affected file', multipleOption)).action((options) => {
-        const impactOptions = {
-            sessionId: '',
-            ...(options.module ? { affectedModules: options.module } : {}),
-            ...(options.file ? { affectedFiles: options.file } : {})
-        };
-        printResult(io, ok('sc.impact', createChangeImpact(impactOptions)), options.json);
-    });
-    addJsonOption(sc.command('retention').description('Create artifact retention report').requiredOption('--slice-id <id>', 'slice identifier').option('--prd <artifact>', 'PRD artifact path', multipleOption).option('--rd <artifact>', 'RD artifact path', multipleOption).option('--qa <artifact>', 'QA artifact path', multipleOption).option('--coverage <artifact>', 'coverage artifact path', multipleOption).option('--review <artifact>', 'review artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
-        printResult(io, ok('sc.retention', createArtifactRetentionReport({ sliceId: options.sliceId, ...(options.prd ? { prdArtifacts: options.prd } : {}), ...(options.rd ? { rdArtifacts: options.rd } : {}), ...(options.qa ? { qaArtifacts: options.qa } : {}), ...(options.coverage ? { coverageArtifacts: options.coverage } : {}), ...(options.review ? { reviewArtifacts: options.review } : {}), ...(options.code ? { codeChanges: options.code } : {}) })), options.json);
-    });
-    addJsonOption(sc.command('validate').description('Validate artifact retention for a slice').requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
-        printResult(io, ok('sc.validate', validateArtifactRetention(options.sliceId)), options.json);
-    });
-    addJsonOption(sc.command('boundary').description('Record retention boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
-        printResult(io, ok('sc.boundary', recordCommitBoundary({ sliceId: options.sliceId, ...(options.artifact ? { artifacts: options.artifact } : {}), ...(options.code ? { codeFiles: options.code } : {}) })), options.json);
-    });
-}

package/dist/src/cli/commands/security-audit-commands.js

@@ -1,132 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/security-audit-service.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
-function resolveEnvelope(envelopePath) {
-    if (envelopePath === undefined || envelopePath === '-') {
-        // Read from stdin
-        return readStdinSync();
-    }
-    try {
-        const raw = readFileSync(envelopePath, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`Failed to read envelope from ${envelopePath}: ${getErrorMessage(error)}`);
-    }
-}
-function readStdinSync() {
-    // Node 22: read stdin synchronously via fs.readFileSync(0, 'utf8').
-    // We use the file descriptor 0 convention.
-    try {
-        // Lazy import to avoid pulling readline at module load
-        const { readFileSync: rfs } = require('node:fs');
-        const raw = rfs(0, 'utf8');
-        if (raw.trim().length === 0) {
-            throw new Error('stdin was empty; expected JSON envelope on stdin or --envelope <path>');
-        }
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.startsWith('stdin was empty')) {
-            throw error;
-        }
-        throw new Error(`Failed to read envelope from stdin: ${getErrorMessage(error)}`);
-    }
-}
-export function registerSecurityAuditCommands(program, io) {
-    const securityAudit = program
-        .command('security-audit')
-        .description('Independent security audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level security-template.md, then writes a structured security-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). See skills/bee/peaks-security-audit/SKILL.md for the full workflow.');
-    addJsonOption(securityAudit
-        .command('detect')
-        .description('Read-only probe: returns the 5-state security-audit runtime as a JSON envelope (ready / handoff-missing / template-missing / dispatch-failed / envelope-malformed). The peaks-security-audit skill calls this first to decide whether to invoke `run`. Mirrors `peaks code-review detect-ocr` semantics.')
-        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
-        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
-        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
-        const projectRoot = options.project ?? process.cwd();
-        const sid = options.sid;
-        if (sid === undefined || sid.length === 0) {
-            printResult(io, fail('security-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const detect = detectSecurityAudit({
-                projectRoot,
-                sessionId: sid,
-            });
-            const envelope = detect.state === 'ready'
-                ? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
-                : fail('security-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]);
-            printResult(io, envelope, options.json);
-            if (detect.state !== 'ready') {
-                process.exitCode = 1;
-            }
-        }
-        catch (error) {
-            printResult(io, fail('security-audit.detect', 'DETECT_SECURITY_AUDIT_FAILED', getErrorMessage(error), {
-                state: 'detection-failed',
-                handoffPresent: false,
-                templatePresent: false,
-                warnings: [],
-                nextActions: [],
-            }, ['Re-run with --project <path> pointing at a known-good project root.']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(securityAudit
-        .command('run')
-        .description('Run the full security-audit pipeline: detect → read handoff + template → write audit artifact to `.peaks/_runtime/<sid>/audit/security-<rid>.md`. Reads the envelope JSON from --envelope <path> or stdin. The peaks-security-audit skill emits the envelope; this CLI validates the shape via isSecurityAuditEnvelope and writes the artifact. Exits 0 on success, 1 on any failure mode (detection, validation, or write).')
-        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
-        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
-        .option('--project <path>', 'project root (default: cwd)')
-        .option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')).action((options) => {
-        const projectRoot = options.project ?? process.cwd();
-        const sid = options.sid;
-        const rid = options.rid;
-        if (sid === undefined || sid.length === 0) {
-            printResult(io, fail('security-audit.run', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.run', {}, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        if (rid === undefined || rid.length === 0) {
-            printResult(io, fail('security-audit.run', 'RID_REQUIRED', 'request id (--rid) is required for security-audit.run', {}, ['Pass --rid <request-id> (e.g. 2026-06-27-v2-12-...)']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const envelopeValue = resolveEnvelope(options.envelope);
-            if (!isSecurityAuditEnvelope(envelopeValue)) {
-                printResult(io, fail('security-audit.run', 'ENVELOPE_MALFORMED', 'envelope failed isSecurityAuditEnvelope validation (expected { verdict, violations, summary })', { receivedType: typeof envelopeValue }, [
-                    'Verify the peaks-security-audit skill prompt matches the strict-shape contract.',
-                    'Re-emit the envelope; see skills/bee/peaks-security-audit/references/audit-protocol.md.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const result = runSecurityAudit({
-                projectRoot,
-                sessionId: sid,
-                rid,
-                generatedAt: new Date().toISOString(),
-                envelope: envelopeValue,
-            });
-            if (result.detect.state !== 'ready' || result.artifactPath === null) {
-                printResult(io, fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, ok('security-audit.run', {
-                detect: result.detect,
-                artifactPath: result.artifactPath,
-                violationsCount: result.violationsCount,
-                verdict: result.verdict,
-            }, [...result.detect.warnings], [...result.detect.nextActions]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('security-audit.run', 'RUN_SECURITY_AUDIT_FAILED', getErrorMessage(error), {}, ['Verify the envelope JSON is well-formed and matches the strict-shape contract.']), options.json);
-            process.exitCode = 1;
-        }
-    });
-}