peaks-loop 4.0.54 → 4.1.0

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

@@ -5,7 +5,10 @@ import { PolyrepoService } from '../../services/polyrepo/polyrepo-service.js';
 function parseChildren(raw) {
     if (raw === undefined || raw.length === 0)
         return undefined;
-    return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
 }
 function resolveRoot(explicit) {
     if (explicit !== undefined && explicit.length > 0)
@@ -28,9 +31,7 @@ export function registerPolyrepoCommands(program, io) {
             const root = resolveRoot(options.root);
             const svc = new PolyrepoService();
             const children = parseChildren(options.children);
-            const result = children === undefined
-                ? svc.init({ root })
-                : svc.init({ root, children });
+            const result = children === undefined ? svc.init({ root }) : svc.init({ root, children });
             printResult(io, ok('polyrepo.init', {
                 root: result.manifest.root,
                 detectedAt: result.manifest.detectedAt,
@@ -44,7 +45,9 @@ export function registerPolyrepoCommands(program, io) {
             ]), options.json);
         }
         catch (error) {
-            printResult(io, fail('polyrepo.init', 'POLYREPO_INIT_FAILED', getErrorMessage(error), {}, ['Verify --root exists and is a directory']), options.json);
+            printResult(io, fail('polyrepo.init', 'POLYREPO_INIT_FAILED', getErrorMessage(error), {}, [
+                'Verify --root exists and is a directory'
+            ]), options.json);
             process.exitCode = 1;
         }
     });
@@ -60,9 +63,7 @@ export function registerPolyrepoCommands(program, io) {
             const svc = new PolyrepoService();
             const result = svc.status(root);
             if (!result.manifestExists) {
-                printResult(io, ok('polyrepo.status', { ...result, initialized: false }, [], [
-                    'No polyrepo manifest found. Run `peaks polyrepo init [--children <list>]` first.'
-                ]), options.json);
+                printResult(io, ok('polyrepo.status', { ...result, initialized: false }, [], ['No polyrepo manifest found. Run `peaks polyrepo init [--children <list>]` first.']), options.json);
                 return;
             }
             printResult(io, ok('polyrepo.status', { ...result, initialized: true }, [], [
@@ -94,17 +95,13 @@ export function registerPolyrepoCommands(program, io) {
             const rid = options.rid ?? '';
             const role = options.role;
             if (role !== 'prd' && role !== 'rd' && role !== 'qa') {
-                printResult(io, fail('polyrepo.dispatch', 'INVALID_ROLE', `--role must be prd | rd | qa (got "${role}")`, {}, [
-                    'Re-run with --role prd (or rd / qa).'
-                ]), options.json);
+                printResult(io, fail('polyrepo.dispatch', 'INVALID_ROLE', `--role must be prd | rd | qa (got "${role}")`, {}, ['Re-run with --role prd (or rd / qa).']), options.json);
                 process.exitCode = 1;
                 return;
             }
             const artifact = options.artifact ?? '';
             if (!existsSync(artifact)) {
-                printResult(io, fail('polyrepo.dispatch', 'ARTIFACT_NOT_FOUND', `source artifact does not exist: ${artifact}`, {}, [
-                    'Verify the path or pass an absolute path.'
-                ]), options.json);
+                printResult(io, fail('polyrepo.dispatch', 'ARTIFACT_NOT_FOUND', `source artifact does not exist: ${artifact}`, {}, ['Verify the path or pass an absolute path.']), options.json);
                 process.exitCode = 1;
                 return;
             }
@@ -113,21 +110,26 @@ export function registerPolyrepoCommands(program, io) {
             const svc = new PolyrepoService();
             const status = svc.status(root);
             if (!status.manifestExists) {
-                printResult(io, fail('polyrepo.dispatch', 'NO_MANIFEST', `no polyrepo manifest at ${root}/.peaks/polyrepo.json`, {}, [
-                    'Run `peaks polyrepo init` first.'
-                ]), options.json);
+                printResult(io, fail('polyrepo.dispatch', 'NO_MANIFEST', `no polyrepo manifest at ${root}/.peaks/polyrepo.json`, {}, ['Run `peaks polyrepo init` first.']), options.json);
                 process.exitCode = 1;
                 return;
             }
             let targets;
             if (options.to !== undefined && options.to.length > 0) {
-                targets = options.to.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+                targets = options.to
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
             }
             else {
                 targets = status.children.map((c) => c.id);
             }
             const result = svc.dispatch(root, {
-                sid, rid, targets, role, artifactPath: artifact
+                sid,
+                rid,
+                targets,
+                role,
+                artifactPath: artifact
             });
             const allOk = result.perChild.every((c) => c.ok);
             printResult(io, ok('polyrepo.dispatch', {

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

@@ -24,9 +24,7 @@ export function registerPrdBlocksCommands(program, io) {
     const prd = program.commands.find((c) => c.name() === 'prd');
     if (prd === undefined) {
         // Fallback: create if missing. Should never trigger in normal startup.
-        program
-            .command('prd')
-            .description('v2.15.0 follow-up G3: PRD design-quality gates.');
+        program.command('prd').description('v2.15.0 follow-up G3: PRD design-quality gates.');
     }
     const target = prd ?? program.commands.find((c) => c.name() === 'prd');
     addJsonOption(target

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

@@ -13,6 +13,6 @@
  * `services/handoff/` is a separate slice-025 layout (different
  * schema) and is intentionally not exposed here.
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerPrdCommands(program: Command, io: ProgramIO): void;

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

@@ -41,7 +41,9 @@ 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)');
+    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')
@@ -69,7 +71,7 @@ export function registerPrdCommands(program, io) {
             const gateEvidence = await deriveGateEvidenceForRequest({
                 projectRoot,
                 sessionId: options.sid,
-                requestId: options.rid,
+                requestId: options.rid
             });
             const handoff = initHandoff({
                 requestId: options.rid,
@@ -79,7 +81,7 @@ export function registerPrdCommands(program, io) {
                 goals: splitCsv(options.goals),
                 acceptanceCriteria: splitCsv(options.ac),
                 preservedBehavior: splitCsv(options.preserve),
-                ...(gateEvidence === undefined ? {} : { gateEvidence }),
+                ...(gateEvidence === undefined ? {} : { gateEvidence })
             });
             if (options.apply !== true) {
                 printResult(io, ok('prd.handoff.init', {
@@ -118,7 +120,9 @@ export function registerPrdCommands(program, io) {
         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);
+                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;
             }

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

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { loadPreferences, migratePreferences, preferencesPath, savePreferences, } from '../../services/preferences/preferences-service.js';
+import { loadPreferences, migratePreferences, preferencesPath, savePreferences } from '../../services/preferences/preferences-service.js';
 const ALLOWED_KEYS = new Set([
     'economyMode',
     'swarmMode',
@@ -9,7 +9,7 @@ const ALLOWED_KEYS = new Set([
     'classifyConservatism',
     'classifyRules',
     'swarmSpeculative',
-    'loopAutonomousEnabled',
+    'loopAutonomousEnabled'
 ]);
 /**
  * Stable, sorted list of allowed preference keys. Used in error messages
@@ -71,7 +71,7 @@ export function registerPreferencesCommands(program) {
             // Stable ordering: source is computed, value reflects merged state.
             const envelope = {
                 ok: true,
-                data: { key: opts.key, value, source },
+                data: { key: opts.key, value, source }
             };
             process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
         }
@@ -96,18 +96,19 @@ export function registerPreferencesCommands(program) {
             try {
                 parsed = JSON.parse(opts.value);
             }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            catch {
+                // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                 // Not valid JSON — keep the raw string.
             }
             const merged = savePreferences(opts.project, {
-                [opts.key]: parsed,
+                [opts.key]: parsed
             });
             const envelope = {
                 ok: true,
                 data: {
                     key: opts.key,
-                    value: merged[opts.key],
-                },
+                    value: merged[opts.key]
+                }
             };
             process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
         }
@@ -134,7 +135,7 @@ export function registerPreferencesCommands(program) {
             if (!existsSync(filePath)) {
                 const envelope = {
                     ok: true,
-                    data: { key: opts.key, removed: false, reason: 'no-override-file' },
+                    data: { key: opts.key, removed: false, reason: 'no-override-file' }
                 };
                 process.stdout.write(JSON.stringify(envelope) + '\n');
                 return;
@@ -161,7 +162,7 @@ export function registerPreferencesCommands(program) {
             }
             const envelope = {
                 ok: true,
-                data: { key: opts.key, removed: hadKey },
+                data: { key: opts.key, removed: hadKey }
             };
             process.stdout.write(JSON.stringify(envelope) + '\n');
         }
@@ -202,9 +203,9 @@ export function registerPreferencesCommands(program) {
                     written: result.written,
                     migrated: result.migrated
                 },
-                warnings: result.written ? [] : [
-                    'Dry-run only — re-run with --apply to write the migrated file.'
-                ]
+                warnings: result.written
+                    ? []
+                    : ['Dry-run only — re-run with --apply to write the migrated file.']
             };
             process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
         }

package/dist/cli/commands/primer-command.js

@@ -83,8 +83,7 @@ export async function runPrimerAction(opts, io) {
     // src/services/session/session-binding-bridge.ts:461-527).
     // NOT the invented `runRotationCheck` from cycle-2 RD.
     const rotation = await ensureSessionWithRotation(projectRoot);
-    const rotationOccurred = rotation.previousSessionId !== null
-        && rotation.rotationReason === 'outer-session-mismatch';
+    const rotationOccurred = rotation.previousSessionId !== null && rotation.rotationReason === 'outer-session-mismatch';
     let clearOutcome = null;
     if (rotationOccurred) {
         // VERIFIED single-options-object signature (see
@@ -96,8 +95,7 @@ export async function runPrimerAction(opts, io) {
         // itself).
         clearOutcome = clearStalePresenceOnRotation({
             projectRootOverride: projectRoot,
-            currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID
-                ?? process.env.CLAUDE_CODE_SESSION_ID,
+            currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID ?? process.env.CLAUDE_CODE_SESSION_ID,
             rotatedOutSessionId: rotation.previousSessionId
         });
     }
@@ -153,7 +151,9 @@ export function registerPrimerCommand(program, io) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            printResult(io, fail('session.primer', 'PRIMER_FAILED', message, { project: opts.project }, ['Verify the project path exists, is writable, and is canonical']), opts.json);
+            printResult(io, fail('session.primer', 'PRIMER_FAILED', message, { project: opts.project }, [
+                'Verify the project path exists, is writable, and is canonical'
+            ]), opts.json);
             process.exitCode = 1;
         }
     });

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

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

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

@@ -9,7 +9,9 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
 const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
 export function registerProjectCommands(program, io) {
-    const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
+    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 / capabilities for a project')
@@ -34,12 +36,16 @@ export function registerProjectCommands(program, io) {
                 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);
+                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);
+                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;
             }
@@ -62,7 +68,11 @@ export function registerProjectCommands(program, io) {
                     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);
+                printResult(io, ok('project.context', {
+                    exists: true,
+                    path: `${options.project}/.peaks/PROJECT.md`,
+                    content
+                }), options.json);
                 return;
             }
             const result = await generateProjectContext(options.project);
@@ -136,7 +146,10 @@ export function registerProjectCommands(program, io) {
         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);
+                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);
@@ -194,7 +207,9 @@ export function registerProjectCommands(program, io) {
             // 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
+            const thresholdDays = options.staleDays !== undefined &&
+                Number.isFinite(options.staleDays) &&
+                options.staleDays > 0
                 ? options.staleDays
                 : DEFAULT_STALE_DAYS;
             const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
@@ -203,9 +218,14 @@ export function registerProjectCommands(program, io) {
             });
             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
+                    ? (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);
+                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;
             }
@@ -240,7 +260,11 @@ export function registerProjectCommands(program, io) {
         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);
+                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

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

@@ -49,12 +49,14 @@ export function registerQaBusinessReviewCommands(program, io) {
             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);
+        }, 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
@@ -120,9 +122,7 @@ export function registerQaBusinessReviewCommands(program, io) {
         }
         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);
+        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
@@ -141,8 +141,12 @@ export function registerQaBusinessReviewCommands(program, io) {
         }
         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);
+        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

@@ -25,7 +25,7 @@
  * 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 { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
 import { type MutReportJson } from 'peaks-loop-mut';

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

@@ -42,7 +42,7 @@ import { createDocCacheFetcher } from '../../services/context/doc-cache-fetcher.
 import { loadMutReport, mutReportPath } from 'peaks-loop-mut';
 function buildDocFetcher(sid) {
     return createDocCacheFetcher({
-        cacheDir: `.peaks/_runtime/${sid}/doc-cache`,
+        cacheDir: `.peaks/_runtime/${sid}/doc-cache`
         // remoteFetcher wired in a future slice.
     });
 }
@@ -56,7 +56,7 @@ async function ensureContextForQa(goal, project, sid) {
             depsMode: 'locked',
             docBudgetTokens: 8000,
             out,
-            fetcher: buildDocFetcher(sid),
+            fetcher: buildDocFetcher(sid)
         });
     }
     catch (error) {
@@ -242,9 +242,7 @@ export function registerQaCommands(program, io) {
             // 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;
+            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

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

@@ -12,7 +12,9 @@
  *                                                  stage)
  *
  * State machine: planned → canary-10 → canary-50 → promoted → watching → done
- * Side branches: → rolled-back (from any pre-done stage), → hotfixed (from watching).
+ * Side branches: → rolled-back (from any pre-done stage). A hotfix is an ENTRY
+ * POINT into that pipeline, not a stage: `hotfix <version>` rolls the active
+ * release back and starts the hotfix version at canary-10 (see `hotfixRelease`).
  *
  * Real deployment (k8s rollout, LB config, monitoring integration) is
  * OUT OF SCOPE for this slice.

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

@@ -12,7 +12,9 @@
  *                                                  stage)
  *
  * State machine: planned → canary-10 → canary-50 → promoted → watching → done
- * Side branches: → rolled-back (from any pre-done stage), → hotfixed (from watching).
+ * Side branches: → rolled-back (from any pre-done stage). A hotfix is an ENTRY
+ * POINT into that pipeline, not a stage: `hotfix <version>` rolls the active
+ * release back and starts the hotfix version at canary-10 (see `hotfixRelease`).
  *
  * Real deployment (k8s rollout, LB config, monitoring integration) is
  * OUT OF SCOPE for this slice.
@@ -81,9 +83,7 @@ export function executeCanaryAction(opts, io, projectRoot) {
             projectRoot,
             percent,
             currentStage: targetStage,
-            nextAction: percent === 10
-                ? 'peaks release canary --percent 50'
-                : 'peaks release promote'
+            nextAction: percent === 10 ? 'peaks release canary --percent 50' : 'peaks release promote'
         }
     };
 }
@@ -111,9 +111,7 @@ export function registerReleaseCommands(program, io) {
             projectRoot,
             version: result.record.version,
             currentStage: result.record.currentStage
-        }, [], [
-            'Run `peaks release canary --percent 10` to begin the canary phase.'
-        ]), opts.json ?? false);
+        }, [], ['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
@@ -130,7 +128,14 @@ export function registerReleaseCommands(program, io) {
         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);
+            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);
@@ -220,12 +225,12 @@ export function registerReleaseCommands(program, io) {
             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;
-        }
+        // No stage guard here: `watching` is unreachable (nothing ever calls
+        // transitionRelease(state, 'watching')), so the real precondition is the
+        // watch window itself — the same thing this command's description
+        // documents ("Requires the watch window to be complete"). The stage
+        // table (`promoted → watching → done`) stays as the declared design, but
+        // `promoted` may now reach `done` directly.
         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);
@@ -238,7 +243,11 @@ export function registerReleaseCommands(program, io) {
         }
         // Move to history.
         const finalRecord = result.state.active;
-        const newState = { version: 1, active: null, history: [...result.state.history, finalRecord] };
+        const newState = {
+            version: 1,
+            active: null,
+            history: [...result.state.history, finalRecord]
+        };
         writeReleaseState(projectRoot, newState);
         printResult(io, ok('release.done', {
             projectRoot,
@@ -266,9 +275,7 @@ export function registerReleaseCommands(program, io) {
             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);
+        }, [], ['Run `peaks release hotfix <version>` to start a hotfix on the previous release.']), opts.json ?? false);
     });
     // 7. hotfix
     addJsonOption(release
@@ -283,7 +290,13 @@ export function registerReleaseCommands(program, io) {
         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);
+            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);
@@ -297,9 +310,7 @@ export function registerReleaseCommands(program, io) {
             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);
+        }, [], ['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