peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,307 @@
+/**
+ * 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 { 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 { 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 { createHeadroomFetcher } from '../../services/context/headroom-fetcher.js';
+// Plan 2 / Task 8 — consume MUT.sig from peaks-mut into verdict envelope.
+import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
+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;
+        }
+    });
+    // rid-012 (2026-07-27) — screenshot archive.
+    // 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';
+            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);
+        }
+    });
+}

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

@@ -0,0 +1,39 @@
+/**
+ * v2.15.0 follow-up — G15: release / hotfix CLI.
+ *
+ *   - `peaks release plan <version>`            — start a new release
+ *   - `peaks release canary --percent <10|50>`   — advance to canary stage
+ *   - `peaks release promote`                   — promote to 100% + start watch
+ *   - `peaks release watch`                     — show watch window status
+ *   - `peaks release rollback`                  — emergency rollback
+ *   - `peaks release hotfix <version>`          — start a hotfix (forces
+ *                                                  rollback of any active
+ *                                                  release; skips 'planned'
+ *                                                  stage)
+ *
+ * State machine: planned → canary-10 → canary-50 → promoted → watching → done
+ * Side branches: → rolled-back (from any pre-done stage), → hotfixed (from watching).
+ *
+ * Real deployment (k8s rollout, LB config, monitoring integration) is
+ * OUT OF SCOPE for this slice.
+ */
+import type { Command } from 'commander';
+import { isReleaseStage } from '../../services/release/release-state.js';
+import { type LayerResult } from '../../services/release/version-precheck-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function executeCanaryAction(opts: {
+    percent: string;
+    note?: string;
+    project?: string;
+    json?: boolean;
+}, io: ProgramIO, projectRoot: string): {
+    ok: boolean;
+    payload: Readonly<Record<string, unknown>>;
+    status: 'PRECHECK_BLOCKER' | 'INVALID_PERCENT' | 'INVALID_TRANSITION' | 'OK';
+    blockerLayer?: {
+        name: string;
+        result: LayerResult;
+    };
+};
+export declare function registerReleaseCommands(program: Command, io: ProgramIO): void;
+export { isReleaseStage };

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

@@ -0,0 +1,323 @@
+/**
+ * v2.15.0 follow-up — G15: release / hotfix CLI.
+ *
+ *   - `peaks release plan <version>`            — start a new release
+ *   - `peaks release canary --percent <10|50>`   — advance to canary stage
+ *   - `peaks release promote`                   — promote to 100% + start watch
+ *   - `peaks release watch`                     — show watch window status
+ *   - `peaks release rollback`                  — emergency rollback
+ *   - `peaks release hotfix <version>`          — start a hotfix (forces
+ *                                                  rollback of any active
+ *                                                  release; skips 'planned'
+ *                                                  stage)
+ *
+ * State machine: planned → canary-10 → canary-50 → promoted → watching → done
+ * Side branches: → rolled-back (from any pre-done stage), → hotfixed (from watching).
+ *
+ * Real deployment (k8s rollout, LB config, monitoring integration) is
+ * OUT OF SCOPE for this slice.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { hotfixRelease, isReleaseStage, planRelease, readReleaseState, rollbackRelease, transitionRelease, watchWindow, writeReleaseState } from '../../services/release/release-state.js';
+import { runAllLayers } from '../../services/release/version-precheck-service.js';
+import { runChangesetHardGate } from '../../services/changeset/changeset-check-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const CANARY_PERCENTS = {
+    10: 'canary-10',
+    50: 'canary-50'
+};
+// rid-010 — extracted canary action handler so AC-8 can drive the canary
+// precheck-guard via direct function call (not via program.parseAsync with a
+// mocked service). Returns the result envelope for the caller to print.
+export function executeCanaryAction(opts, io, projectRoot) {
+    // rid-010 — precheck guard (Layer A or Layer B blocker refuses canary).
+    // rid-011 — changeset hard gate runs inline in the canary closure BEFORE
+    // this function is called (step 0 short-circuits with CHANGESET_BLOCKED).
+    // Layers C/D default warning → do not block canary; --strict upgrade would
+    // be a separate flag (out of scope for rid-011).
+    // Layers C/D default warning → do not block canary; --strict upgrade would
+    // be a separate flag (out of scope for rid-010).
+    const precheck = runAllLayers({ projectRoot, strict: false });
+    const blockerEntry = Object.entries(precheck.layers).find(([, l]) => l.status === 'blocker');
+    if (blockerEntry !== undefined) {
+        const [name, result] = blockerEntry;
+        return {
+            ok: false,
+            status: 'PRECHECK_BLOCKER',
+            blockerLayer: { name, result },
+            payload: {
+                projectRoot,
+                precheckSnapshotAt: precheck.snapshotAt,
+                layer: name,
+                message: result.message,
+                remediation: result.remediation
+            }
+        };
+    }
+    const percent = Number.parseInt(opts.percent, 10);
+    if (percent !== 10 && percent !== 50) {
+        return {
+            ok: false,
+            status: 'INVALID_PERCENT',
+            payload: { projectRoot, got: opts.percent }
+        };
+    }
+    const state = readReleaseState(projectRoot);
+    const targetStage = CANARY_PERCENTS[percent];
+    const result = transitionRelease(state, targetStage, opts.note);
+    if ('error' in result) {
+        return {
+            ok: false,
+            status: 'INVALID_TRANSITION',
+            payload: { projectRoot, error: result.error }
+        };
+    }
+    writeReleaseState(projectRoot, result.state);
+    return {
+        ok: true,
+        status: 'OK',
+        payload: {
+            projectRoot,
+            percent,
+            currentStage: targetStage,
+            nextAction: percent === 10
+                ? 'peaks release canary --percent 50'
+                : 'peaks release promote'
+        }
+    };
+}
+export function registerReleaseCommands(program, io) {
+    const release = program
+        .command('release')
+        .description('v2.15.0 follow-up G15: canary → promote → watch → done / hotfix state machine.');
+    // 1. plan
+    addJsonOption(release
+        .command('plan <version>')
+        .description('Start a new release. Stores the version in the canary pipeline state. ' +
+        'Fails when there is already an active release in any non-terminal stage.')
+        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readReleaseState(projectRoot);
+        const result = planRelease(state, version);
+        if ('error' in result) {
+            printResult(io, fail('release.plan', 'CONFLICT', result.error, { projectRoot }, [
+                'Run `peaks release rollback` or `peaks release hotfix` to clear the active release.'
+            ]), opts.json ?? false);
+            return;
+        }
+        writeReleaseState(projectRoot, result.state);
+        printResult(io, ok('release.plan', {
+            projectRoot,
+            version: result.record.version,
+            currentStage: result.record.currentStage
+        }, [], [
+            'Run `peaks release canary --percent 10` to begin the canary phase.'
+        ]), opts.json ?? false);
+    });
+    // 2. canary — rid-010 wires precheck as the first step via executeCanaryAction
+    addJsonOption(release
+        .command('canary')
+        .description('Advance the active release to a canary stage. Two percent values supported: ' +
+        '10 (first canary, requires stage=planned) and 50 (second canary, requires ' +
+        'stage=canary-10). Runs `peaks release precheck` first and refuses with ' +
+        'PRECHECK_BLOCKER if any blocker layer (rootVsShared or tagCollision) fails.')
+        .requiredOption('--percent <10|50>', 'canary percent (10 or 50)')
+        .option('--note <text>', 'optional note for the stage transition')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        // rid-011 — changeset hard gate (step 0).
+        const gate = runChangesetHardGate(projectRoot);
+        if (gate.state === 'staged-present') {
+            process.exitCode = 1;
+            printResult(io, fail('release.canary', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing canary`, { projectRoot, state: gate.state, stagedFiles: [...gate.stagedFiles], snapshotAt: gate.snapshotAt }, [`Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`]), opts.json ?? false);
+            return;
+        }
+        const result = executeCanaryAction(opts, io, projectRoot);
+        if (result.status === 'PRECHECK_BLOCKER') {
+            const layer = result.blockerLayer;
+            printResult(io, fail('release.canary', 'PRECHECK_BLOCKER', `precheck blocker on layer '${layer?.name ?? 'unknown'}': ${layer?.result.message ?? ''}`, result.payload, [
+                `Run 'peaks release precheck --project ${projectRoot}' for the full 4-layer envelope.`,
+                `Run 'peaks release precheck --strict' to also surface warning-layer issues.`,
+                `Remediation: ${layer?.result.remediation ?? ''}`
+            ]), opts.json ?? false);
+            return;
+        }
+        if (result.status === 'INVALID_PERCENT') {
+            printResult(io, fail('release.canary', 'INVALID_PERCENT', `--percent must be 10 or 50 (got "${opts.percent}")`, result.payload, []), opts.json ?? false);
+            return;
+        }
+        if (result.status === 'INVALID_TRANSITION') {
+            printResult(io, fail('release.canary', 'INVALID_TRANSITION', String(result.payload['error'] ?? ''), result.payload, []), opts.json ?? false);
+            return;
+        }
+        printResult(io, ok('release.canary', result.payload, [], []), opts.json ?? false);
+    });
+    // 3. promote
+    addJsonOption(release
+        .command('promote')
+        .description('Promote the canary to 100% (full release). Requires stage=canary-50. ' +
+        'Records the promoted-at timestamp and starts the 24h watch window.')
+        .option('--note <text>', 'optional note')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readReleaseState(projectRoot);
+        const result = transitionRelease(state, 'promoted', opts.note);
+        if ('error' in result) {
+            printResult(io, fail('release.promote', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        writeReleaseState(projectRoot, result.state);
+        printResult(io, ok('release.promote', {
+            projectRoot,
+            currentStage: 'promoted',
+            promotedAt: result.state.active?.promotedAt
+        }, [], [
+            'Watch window started. Run `peaks release watch` to check progress; `peaks release rollback` for emergency.'
+        ]), opts.json ?? false);
+    });
+    // 4. watch
+    addJsonOption(release
+        .command('watch')
+        .description('Show the watch window status for the current promoted release. ' +
+        '24h window from promoted-at. After the window, run `peaks release done` ' +
+        'to mark the release complete.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readReleaseState(projectRoot);
+        if (state.active === null) {
+            printResult(io, fail('release.watch', 'NO_ACTIVE', 'no active release to watch', { projectRoot }, [
+                'Run `peaks release plan <version>` to start one.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const win = watchWindow(state.active);
+        const readyForDone = win.percentComplete >= 1.0;
+        printResult(io, ok('release.watch', {
+            projectRoot,
+            version: state.active.version,
+            currentStage: state.active.currentStage,
+            window: {
+                elapsedMs: win.elapsedMs,
+                remainingMs: win.remainingMs,
+                windowMs: win.windowMs,
+                percentComplete: Math.round(win.percentComplete * 100) / 100
+            },
+            readyForDone
+        }, readyForDone
+            ? ['Watch window complete. Run `peaks release done` to mark the release done.']
+            : []), opts.json ?? false);
+    });
+    // 5. done (implicit helper; not in original spec but useful)
+    addJsonOption(release
+        .command('done')
+        .description('Mark the active release as done. Requires the watch window to be ' +
+        'complete (24h after promoted-at).')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readReleaseState(projectRoot);
+        if (state.active === null) {
+            printResult(io, fail('release.done', 'NO_ACTIVE', 'no active release', { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        if (state.active.currentStage !== 'watching') {
+            printResult(io, fail('release.done', 'INVALID_STAGE', `must be in 'watching' stage to mark done (current: ${state.active.currentStage})`, { projectRoot }, [
+                'Run `peaks release watch` to check progress; transition requires the watch window to complete.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const win = watchWindow(state.active);
+        if (win.percentComplete < 1.0) {
+            printResult(io, fail('release.done', 'WATCH_INCOMPLETE', `watch window not yet complete (${Math.round(win.percentComplete * 100)}% elapsed)`, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        const result = transitionRelease(state, 'done');
+        if ('error' in result) {
+            printResult(io, fail('release.done', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        // Move to history.
+        const finalRecord = result.state.active;
+        const newState = { version: 1, active: null, history: [...result.state.history, finalRecord] };
+        writeReleaseState(projectRoot, newState);
+        printResult(io, ok('release.done', {
+            projectRoot,
+            version: finalRecord.version,
+            doneAt: finalRecord.doneAt
+        }, [], []), opts.json ?? false);
+    });
+    // 6. rollback
+    addJsonOption(release
+        .command('rollback')
+        .description('Emergency rollback of the active release. Moves the active release to ' +
+        'the history with currentStage=rolled-back. Available from any ' +
+        'pre-done stage.')
+        .option('--note <text>', 'optional rollback reason')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readReleaseState(projectRoot);
+        const result = rollbackRelease(state, opts.note);
+        if ('error' in result) {
+            printResult(io, fail('release.rollback', 'INVALID_TRANSITION', result.error, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        writeReleaseState(projectRoot, result.state);
+        printResult(io, ok('release.rollback', {
+            projectRoot,
+            rolledBack: result.record.version,
+            finalStage: result.record.currentStage
+        }, [], [
+            'Run `peaks release hotfix <version>` to start a hotfix on the previous release.'
+        ]), opts.json ?? false);
+    });
+    // 7. hotfix
+    addJsonOption(release
+        .command('hotfix <version>')
+        .description('Start a hotfix release. Forces a rollback of any active release, ' +
+        'skips the `planned` stage, and starts the new release at canary-10. ' +
+        'Use this for紧急修复 — minimal ceremony, no full prd ceremony.')
+        .option('--note <text>', 'optional hotfix note')
+        .option('--project <path>', 'project root (default: cwd)')).action((version, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        // rid-011 — changeset hard gate (step 0). No --skip-changeset-check override.
+        const changesetGate = runChangesetHardGate(projectRoot);
+        if (changesetGate.state === 'staged-present') {
+            process.exitCode = 1;
+            printResult(io, fail('release.hotfix', 'CHANGESET_BLOCKED', `${changesetGate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to start hotfix`, { projectRoot, stagedFiles: [...changesetGate.stagedFiles], snapshotAt: changesetGate.snapshotAt }, [`Drain pending changesets (coordinating LLM: drain via the standard changeset consumption path), then re-run \`peaks changeset check --project ${projectRoot}\` to confirm clean state.`]), opts.json ?? false);
+            return;
+        }
+        const state = readReleaseState(projectRoot);
+        const result = hotfixRelease(state, version, opts.note);
+        if ('error' in result) {
+            printResult(io, fail('release.hotfix', 'HOTFIX_FAILED', result.error, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        writeReleaseState(projectRoot, result.state);
+        printResult(io, ok('release.hotfix', {
+            projectRoot,
+            version: result.record.version,
+            currentStage: result.record.currentStage
+        }, [], [
+            'Hotfix started at canary-10. Run `peaks release canary --percent 50` to advance.'
+        ]), opts.json ?? false);
+    });
+    // 8. precheck — rid-010 (Phase 4 slice 1) — 4-layer version precheck.
+    addJsonOption(release
+        .command('precheck')
+        .description('Run the 4-layer version precheck (rootVsShared / tagCollision / ' +
+        'changesetStaged / workspaceLockstep). Layer A+B are blockers by default; ' +
+        'Layer C+D are warnings unless --strict is passed (CI parity mode). ' +
+        'Shared with publish.yml gate-cli-version step §(A).')
+        .option('--strict', 'treat warnings as blockers (CI parity mode)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const envelope = runAllLayers({ projectRoot, strict: opts.strict === true });
+        process.exitCode = envelope.ok ? 0 : 1;
+        const warningLines = envelope.overall === 'warning'
+            ? ['Warning layers reported but did not block. Re-run with --strict to upgrade.']
+            : [];
+        printResult(io, ok('release.precheck', envelope, [], warningLines), opts.json ?? false);
+    });
+}
+// Re-export for tests / external consumers.
+export { isReleaseStage };