peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/request-init-command.js

@@ -0,0 +1,100 @@
+import { createRequestArtifact, VALID_REQUEST_TYPES } from '../../services/artifacts/request-artifact-service.js';
+import { parseRole, parseRequestType, VALID_ROLES } from './request-format-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const INIT_DESCRIPTION = 'Create the per-request artifact template for a Peaks role (dry-run by default)';
+const INIT_ID_HELP = 'request id, e.g. 2026-05-23-add-foo. With --apply, also pre-creates the canonical change-id scope dir at .peaks/_runtime/change/<id>/ so sub-agents never write .peaks/_runtime/<id>/ at top level.';
+const INIT_PROJECT_HELP = 'target project root';
+const INIT_SESSION_HELP = 'override the default date-stamped session id';
+const INIT_APPLY_HELP = 'write the artifact file (default: preview only)';
+const INIT_CALLER_ID_HELP = 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). The resolved callerId is stamped on the artifact body and surfaced in the response envelope.';
+const CALLER_ID_INVALID_HINTS = [
+    'Set --caller-id to a value matching ^[a-zA-Z0-9._-]{1,200}$',
+    'Or set PEAKS_CALLER_ID env var (or CLAUDE_CODE_SESSION_ID for Claude Code)'
+];
+function failInitSessionIdRequired(io, options) {
+    printResult(io, fail('request.init', 'SESSION_ID_REQUIRED', '--session-id is required: the CLI writes envelopes only to .peaks/_runtime/<sessionId>/... (one-axis layout)', { role: options.role, requestId: options.id }, ['Re-run with --session-id <sid>', 'Or run `peaks workspace init` to create a session first']), options.json);
+    process.exitCode = 1;
+}
+function buildInitServiceOptions(options, sessionId) {
+    // One-axis layout: --session-id is REQUIRED. The on-disk root
+    // is always `.peaks/_runtime/<sessionId>/<role>/...`. The user
+    // has forbidden the `.peaks/_runtime/<id>/` root layout — without an
+    // explicit session id, we cannot guarantee the artifact lands
+    // under `_runtime/`. See
+    // `.peaks/memory/2026-06-21-peaks-request-session-id-leaks-into-change-id.md`.
+    const serviceOptions = {
+        role: options.role,
+        requestId: options.id,
+        projectRoot: options.project
+    };
+    serviceOptions.sessionId = sessionId;
+    if (options.apply === true) {
+        serviceOptions.apply = true;
+    }
+    if (options.type !== undefined) {
+        serviceOptions.requestType = options.type;
+    }
+    return serviceOptions;
+}
+/**
+ * Resolve the caller id, or `null` when the refusal has already been printed
+ * and the exit code set. The CLI integration layer is the single entry point
+ * for the resolver; we do not pre-judge whether the caller passed a flag.
+ * D2 (no callerId available) and D5 (regex fail) both surface as
+ * `CALLER_ID_INVALID` with the inner `CallerIdError.source` propagated for
+ * caller-side audit. A non-`CallerIdError` propagates to the caller's catch.
+ */
+async function resolveInitCallerId(io, options) {
+    const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
+    try {
+        return resolveCallerId(options.callerId !== undefined ? { flagValue: options.callerId } : {});
+    }
+    catch (error) {
+        if (error instanceof CallerIdError) {
+            // D2 (EX_USAGE, exit 64) = nothing usable; D5 (EX_DATAERR, exit 65)
+            // = something was passed but did not match the D1 regex.
+            const code = error.code === 'EX_USAGE' ? 64 : 65;
+            printResult(io, fail('request.init', 'CALLER_ID_INVALID', error.message, { source: error.source }, [
+                ...CALLER_ID_INVALID_HINTS
+            ]), options.json);
+            process.exitCode = code;
+            return null;
+        }
+        throw error;
+    }
+}
+async function runRequestInit(options, io) {
+    try {
+        if (options.sessionId === undefined || options.sessionId.trim().length === 0) {
+            failInitSessionIdRequired(io, options);
+            return;
+        }
+        const serviceOptions = buildInitServiceOptions(options, options.sessionId);
+        const callerId = await resolveInitCallerId(io, options);
+        if (callerId === null)
+            return;
+        serviceOptions.callerId = callerId;
+        const result = await createRequestArtifact(serviceOptions);
+        printResult(io, ok('request.init', result, [], result.applied ? [] : [`Re-run with --apply to write ${result.path}`]), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('request.init', 'REQUEST_INIT_FAILED', getErrorMessage(error), { role: options.role, requestId: options.id }, ['Check role, request id, and project path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRequestInitCommand(request, io) {
+    addJsonOption(request
+        .command('init')
+        .description(INIT_DESCRIPTION)
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--id <request-id>', INIT_ID_HELP)
+        .requiredOption('--project <path>', INIT_PROJECT_HELP)
+        .option('--session-id <session>', INIT_SESSION_HELP)
+        .option('--apply', INIT_APPLY_HELP)
+        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)
+        // (D4 priority level 1). When set, the resolved callerId is surfaced
+        // in the JSON envelope; the on-disk artifact records it in the
+        // artifact body so future reads know which caller produced it.
+        .option('--caller-id <id>', INIT_CALLER_ID_HELP)).action((options) => runRequestInit(options, io));
+}

package/dist/cli/commands/request-lint-command.d.ts

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

package/dist/cli/commands/request-lint-command.js

@@ -0,0 +1,50 @@
+import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
+import { parseRole, VALID_ROLES } from './request-format-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const LINT_DESCRIPTION = 'Scan a request artifact body for unfilled placeholders (<...>, TBD, bare bullets) before declaring it complete';
+const LINT_REQUEST_ID_HELP = 'request id';
+const LINT_PROJECT_HELP = 'target project root';
+const LINT_SESSION_HELP = 'restrict to a specific session id';
+function failLintNotFound(io, options, requestId) {
+    printResult(io, fail('request.lint', 'REQUEST_NOT_FOUND', `No artifact found for role=${options.role} requestId=${requestId}`, { role: options.role, requestId }, ['Verify the request id, role, and session id']), options.json);
+    process.exitCode = 1;
+}
+async function runRequestLint(requestId, options, io) {
+    try {
+        const lintOptions = {
+            projectRoot: options.project,
+            role: options.role,
+            requestId
+        };
+        if (options.sessionId !== undefined) {
+            lintOptions.sessionId = options.sessionId;
+        }
+        const report = await lintRequestArtifact(lintOptions);
+        if (report === null) {
+            failLintNotFound(io, options, requestId);
+            return;
+        }
+        const nextActions = [];
+        if (!report.ok) {
+            nextActions.push(`Fix ${report.findings.filter((f) => f.severity === 'error').length} error finding(s) before transitioning this artifact.`);
+        }
+        printResult(io, ok('request.lint', report, [], nextActions), options.json);
+        if (!report.ok) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('request.lint', 'REQUEST_LINT_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Verify the artifact path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRequestLintCommand(request, io) {
+    addJsonOption(request
+        .command('lint')
+        .description(LINT_DESCRIPTION)
+        .argument('<request-id>', LINT_REQUEST_ID_HELP)
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--project <path>', LINT_PROJECT_HELP)
+        .option('--session-id <session>', LINT_SESSION_HELP)).action((requestId, options) => runRequestLint(requestId, options, io));
+}

package/dist/cli/commands/request-list-command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import { type RequestArtifactSummary } from '../../services/artifacts/request-artifact-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * `request list`. `count` is the true total; `names` carries
+ * `role/requestId (state)` labels for the first N entries. The full `items`
+ * array (with paths + timestamps) is one flag away — omit `--summary`.
+ */
+export declare function buildRequestListSummary(items: readonly RequestArtifactSummary[]): Record<string, unknown>;
+export declare function registerRequestListCommand(request: Command, io: ProgramIO): void;

package/dist/cli/commands/request-list-command.js

@@ -0,0 +1,53 @@
+import { listRequestArtifacts } from '../../services/artifacts/request-artifact-service.js';
+import { boundedNames, fitSummaryToBytes } from '../../services/context/summary-view.js';
+import { parseRole, VALID_ROLES } from './request-format-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const LIST_DESCRIPTION = 'List per-request artifacts under a project workspace';
+const LIST_PROJECT_HELP = 'target project root';
+const LIST_SESSION_HELP = 'limit to a specific session id';
+const LIST_SUMMARY_HELP = 'emit counts + names-of-first-N only (≤ 2 KB) instead of the full item array; the default envelope is unchanged';
+/**
+ * `request list`. `count` is the true total; `names` carries
+ * `role/requestId (state)` labels for the first N entries. The full `items`
+ * array (with paths + timestamps) is one flag away — omit `--summary`.
+ */
+export function buildRequestListSummary(items) {
+    const view = {
+        view: 'summary',
+        count: items.length,
+        items: boundedNames(items.map((i) => `${i.role}/${i.requestId} (${i.state})`))
+    };
+    return fitSummaryToBytes(view);
+}
+async function runRequestList(options, io) {
+    try {
+        const listOptions = {
+            projectRoot: options.project
+        };
+        if (options.sessionId !== undefined) {
+            listOptions.sessionId = options.sessionId;
+        }
+        if (options.role !== undefined) {
+            listOptions.role = options.role;
+        }
+        const items = await listRequestArtifacts(listOptions);
+        // Slice B: `--summary` is opt-in; the default `{count, items}` shape is
+        // byte-identical to before.
+        const data = options.summary === true ? buildRequestListSummary(items) : { count: items.length, items };
+        printResult(io, ok('request.list', data), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('request.list', 'REQUEST_LIST_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check project path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRequestListCommand(request, io) {
+    addJsonOption(request
+        .command('list')
+        .description(LIST_DESCRIPTION)
+        .requiredOption('--project <path>', LIST_PROJECT_HELP)
+        .option('--session-id <session>', LIST_SESSION_HELP)
+        .option('--role <role>', `limit to a single role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .option('--summary', LIST_SUMMARY_HELP)).action((options) => runRequestList(options, io));
+}

package/dist/cli/commands/request-repair-status-command.d.ts

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

package/dist/cli/commands/request-repair-status-command.js

@@ -0,0 +1,61 @@
+import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const REPAIR_STATUS_DESCRIPTION = 'Count RD↔QA repair cycles for a request from its RD artifact transition notes; reports cycle count and whether the 3-cycle cap is reached';
+const REPAIR_STATUS_REQUEST_ID_HELP = 'request id';
+const REPAIR_STATUS_PROJECT_HELP = 'target project root';
+const REPAIR_STATUS_SESSION_HELP = 'restrict to a specific session id';
+const REPAIR_STATUS_MAX_CYCLES_HELP = 'override the default max cycle cap (default 3)';
+function resolveRepairMaxCycles(options) {
+    return options.maxCycles !== undefined && /^\d+$/.test(options.maxCycles)
+        ? Number(options.maxCycles)
+        : 3;
+}
+function failRepairStatusNotFound(io, options, requestId) {
+    printResult(io, fail('request.repair-status', 'REQUEST_NOT_FOUND', `No RD artifact found for requestId=${requestId}`, { requestId }, ['Verify the request id and session id']), options.json);
+    process.exitCode = 1;
+}
+function repairStatusNextActions(report) {
+    const nextActions = [];
+    if (report.atCap) {
+        nextActions.push(`Repair cap reached (${report.cycleCount}/${report.maxCycles}). Emit a blocked TXT handoff and stop the loop.`);
+    }
+    else if (report.cycleCount > 0) {
+        nextActions.push(`${report.remaining} repair cycle(s) remaining before block.`);
+    }
+    return nextActions;
+}
+async function runRequestRepairStatus(requestId, options, io) {
+    try {
+        const statusOptions = {
+            projectRoot: options.project,
+            requestId,
+            maxCycles: resolveRepairMaxCycles(options)
+        };
+        if (options.sessionId !== undefined) {
+            statusOptions.sessionId = options.sessionId;
+        }
+        const report = await getRepairCycleStatus(statusOptions);
+        if (report === null) {
+            failRepairStatusNotFound(io, options, requestId);
+            return;
+        }
+        printResult(io, ok('request.repair-status', report, [], repairStatusNextActions(report)), options.json);
+        if (report.atCap) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('request.repair-status', 'REQUEST_REPAIR_STATUS_FAILED', getErrorMessage(error), { requestId }, ['Verify the artifact path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRequestRepairStatusCommand(request, io) {
+    addJsonOption(request
+        .command('repair-status')
+        .description(REPAIR_STATUS_DESCRIPTION)
+        .argument('<request-id>', REPAIR_STATUS_REQUEST_ID_HELP)
+        .requiredOption('--project <path>', REPAIR_STATUS_PROJECT_HELP)
+        .option('--session-id <session>', REPAIR_STATUS_SESSION_HELP)
+        .option('--max-cycles <n>', REPAIR_STATUS_MAX_CYCLES_HELP)).action((requestId, options) => runRequestRepairStatus(requestId, options, io));
+}

package/dist/cli/commands/request-show-command.d.ts

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

package/dist/cli/commands/request-show-command.js

@@ -0,0 +1,56 @@
+import { showRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { applyPerArtifactFormat, inferArtifactName, parseRole, resolveDefaultFormat, VALID_ROLES } from './request-format-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const SHOW_DESCRIPTION = 'Show a single per-request artifact, optionally scoped to a session. R3: default body format is per-artifact (PRD/tech-doc pretty; everything else compact); pass --pretty or --compact to override uniformly.';
+const SHOW_REQUEST_ID_HELP = 'request id, e.g. 2026-05-23-add-foo';
+const SHOW_PROJECT_HELP = 'target project root';
+const SHOW_SESSION_HELP = 'restrict to a specific session id';
+const SHOW_PRETTY_HELP = 'force the body to render pretty (overrides the per-artifact default)';
+const SHOW_COMPACT_HELP = 'force the body to render compact (overrides the per-artifact default)';
+function failShowNotFound(io, options, requestId) {
+    printResult(io, fail('request.show', 'REQUEST_NOT_FOUND', `No artifact found for role=${options.role} requestId=${requestId}`, { role: options.role, requestId }, ['Verify the request id, role, and session id']), options.json);
+    process.exitCode = 1;
+}
+function buildShowPayload(result, options) {
+    // R3: pick the per-artifact default format and apply the override
+    // if either flag is set. Last-flag-wins if both are passed.
+    const override = options.compact === true ? 'compact' : options.pretty === true ? 'pretty' : null;
+    const artifactName = inferArtifactName(result, options.role);
+    const format = override ?? resolveDefaultFormat(artifactName);
+    const transformed = applyPerArtifactFormat(result, override ?? format);
+    return transformed === result ? { ...result, format } : transformed;
+}
+async function runRequestShow(requestId, options, io) {
+    try {
+        const showOptions = {
+            projectRoot: options.project,
+            role: options.role,
+            requestId
+        };
+        if (options.sessionId !== undefined) {
+            showOptions.sessionId = options.sessionId;
+        }
+        const result = await showRequestArtifact(showOptions);
+        if (result === null) {
+            failShowNotFound(io, options, requestId);
+            return;
+        }
+        printResult(io, ok('request.show', buildShowPayload(result, options)), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRequestShowCommand(request, io) {
+    addJsonOption(request
+        .command('show')
+        .description(SHOW_DESCRIPTION)
+        .argument('<request-id>', SHOW_REQUEST_ID_HELP)
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--project <path>', SHOW_PROJECT_HELP)
+        .option('--session-id <session>', SHOW_SESSION_HELP)
+        .option('--pretty', SHOW_PRETTY_HELP)
+        .option('--compact', SHOW_COMPACT_HELP)).action((requestId, options) => runRequestShow(requestId, options, io));
+}

package/dist/cli/commands/request-transition-command.d.ts

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

package/dist/cli/commands/request-transition-command.js

@@ -0,0 +1,122 @@
+import { transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { parseRole, parseStateForRole, VALID_ROLES } from './request-format-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { runTransitionPreflight } from './request-transition-preflight.js';
+import { reportTransitionFailure } from './request-transition-failures.js';
+import { buildPrdHandoffResult, collectQaHandoffHooks, preCompactNote } from './request-transition-hooks.js';
+const TRANSITION_DESCRIPTION = 'Move a per-request artifact to a new state defined by its role state machine';
+const TRANSITION_REQUEST_ID_HELP = 'request id, e.g. 2026-05-23-add-foo';
+const TRANSITION_STATE_HELP = 'new state name; allowed values depend on role';
+const TRANSITION_PROJECT_HELP = 'target project root';
+const TRANSITION_SESSION_HELP = 'restrict to a specific session id';
+const TRANSITION_REASON_HELP = 'reason appended as a transition note; required when --allow-incomplete is set';
+const TRANSITION_ALLOW_INCOMPLETE_HELP = 'bypass artifact prerequisite checks; requires --reason and records the bypass in the artifact';
+const TRANSITION_CONFIRM_HELP = 'skip the confirmation gate (for non-interactive / LLM contexts)';
+const TRANSITION_FORCE_CONFIRM_HELP = 'bypass mode-enforced confirmation (use with caution)';
+function buildTransitionOptions(requestId, role, newState, options) {
+    const transitionOptions = {
+        role,
+        requestId,
+        projectRoot: options.project,
+        newState
+    };
+    if (options.sessionId !== undefined) {
+        transitionOptions.sessionId = options.sessionId;
+    }
+    if (options.reason !== undefined) {
+        transitionOptions.reason = options.reason;
+    }
+    if (options.allowIncomplete === true) {
+        transitionOptions.allowIncomplete = true;
+    }
+    if (options.confirm === true) {
+        transitionOptions.confirmed = true;
+    }
+    if (options.forceConfirm === true) {
+        transitionOptions.forceConfirm = true;
+    }
+    return transitionOptions;
+}
+/** Type sanity check for PRD handoff. */
+async function applyPrdTypeSanityCheck(transitionOptions, requestId, options) {
+    if (!(transitionOptions.role === 'prd' && transitionOptions.newState === 'handed-off'))
+        return;
+    const { showRequestArtifact: showForType } = await import('../../services/artifacts/request-artifact-service.js');
+    const showTypeOptions = {
+        projectRoot: options.project,
+        role: 'prd',
+        requestId
+    };
+    if (options.sessionId !== undefined) {
+        showTypeOptions.sessionId = options.sessionId;
+    }
+    const existing = await showForType(showTypeOptions);
+    if (existing !== null) {
+        transitionOptions.typeSanityCheck = {
+            projectRoot: options.project,
+            declaredType: existing.requestType
+        };
+    }
+}
+function failTransitionNotFound(io, options, role, requestId) {
+    printResult(io, fail('request.transition', 'REQUEST_NOT_FOUND', `No artifact found for role=${role} requestId=${requestId}`, { role, requestId }, ['Verify the request id, role, and session id']), options.json);
+    process.exitCode = 1;
+}
+function printTransitionResult(io, options, result, hooks) {
+    const note = preCompactNote(hooks.preCompact);
+    printResult(io, ok('request.transition', {
+        ...result,
+        preCompactCheckpoint: hooks.preCompact?.data ?? null,
+        codegraphRefresh: hooks.codegraphRefresh
+    }, [
+        ...(note === null ? [] : [note]),
+        ...(hooks.codegraphWarning === null ? [] : [hooks.codegraphWarning])
+    ]), options.json);
+}
+async function runRequestTransition(requestId, options, io) {
+    try {
+        const role = options.role;
+        const newState = parseStateForRole(role, options.state);
+        const preflight = await runTransitionPreflight(io, requestId, role, options);
+        if (!preflight.proceed)
+            return;
+        const transitionOptions = buildTransitionOptions(requestId, role, newState, options);
+        await applyPrdTypeSanityCheck(transitionOptions, requestId, options);
+        const result = await transitionRequestArtifact(transitionOptions);
+        if (result === null) {
+            failTransitionNotFound(io, options, role, requestId);
+            return;
+        }
+        const hooks = await collectQaHandoffHooks(role, newState, result.sessionId, options.project);
+        const handoff = await buildPrdHandoffResult({
+            role,
+            newState,
+            requestId,
+            options,
+            result
+        });
+        if (handoff !== null) {
+            printResult(io, handoff, options.json);
+            return;
+        }
+        printTransitionResult(io, options, result, hooks);
+    }
+    catch (error) {
+        reportTransitionFailure(io, options, requestId, error);
+    }
+}
+export function registerRequestTransitionCommand(request, io) {
+    addJsonOption(request
+        .command('transition')
+        .description(TRANSITION_DESCRIPTION)
+        .argument('<request-id>', TRANSITION_REQUEST_ID_HELP)
+        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
+        .requiredOption('--state <state>', TRANSITION_STATE_HELP)
+        .requiredOption('--project <path>', TRANSITION_PROJECT_HELP)
+        .option('--session-id <session>', TRANSITION_SESSION_HELP)
+        .option('--reason <text>', TRANSITION_REASON_HELP)
+        .option('--allow-incomplete', TRANSITION_ALLOW_INCOMPLETE_HELP)
+        .option('--confirm', TRANSITION_CONFIRM_HELP)
+        .option('--force-confirm', TRANSITION_FORCE_CONFIRM_HELP)).action((requestId, options) => runRequestTransition(requestId, options, io));
+}

package/dist/cli/commands/request-transition-failures.d.ts

@@ -0,0 +1,8 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { RequestTransitionOptions } from './request-command-options.js';
+/**
+ * Map a thrown transition error to its envelope. `InvalidArgumentError` is
+ * re-thrown: Commander raises it for an unparsable `--state`, and swallowing it
+ * here would report a usage error as a transition failure.
+ */
+export declare function reportTransitionFailure(io: ProgramIO, options: RequestTransitionOptions, requestId: string, error: unknown): void;

package/dist/cli/commands/request-transition-failures.js

@@ -0,0 +1,90 @@
+// Split out of `request-commands.ts`: the
+// typed failure arms of `peaks request transition`. Each branch is a
+// printer + exit-code pair, kept one per function so the dispatcher stays
+// readable and every branch keeps setting `process.exitCode = 1`.
+import { InvalidArgumentError } from 'commander';
+import { PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError } from '../../services/artifacts/request-artifact-service.js';
+import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
+import { fail } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+function reportPrerequisitesFailure(io, options, error) {
+    // The `warnings` list is surfaced inside the 1-minor-release back-compat
+    // window (e.g. MUT_REPORT) so the operator sees both the hard-blocked
+    // `missing` paths and the soft-blocked ones. `warnings` is always present
+    // (possibly empty) to keep the response shape stable.
+    printResult(io, fail('request.transition', error.code, error.message, {
+        role: error.role,
+        newState: error.newState,
+        sessionId: error.sessionId,
+        missing: error.missing,
+        warnings: error.warnings
+    }, [
+        ...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
+        ...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${w.path} — ${w.message}`),
+        'Once every required artifact exists, rerun this transition.',
+        'For exceptional cases (docs-only / config-only change), bypass with: --allow-incomplete --reason "<justification>"'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function reportLintGateFailure(io, options, error) {
+    printResult(io, fail('request.transition', error.code, error.message, { role: error.role, newState: error.newState, errorCount: error.errorCount }, [
+        'Fix lint errors in the artifact before transitioning.',
+        'Run `peaks request lint --role <role> --id <rid> --project <path>` to see details.',
+        'Or bypass with: --allow-incomplete --reason "<justification>"'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function reportTypeSanityFailure(io, options, error) {
+    printResult(io, fail('request.transition', error.code, error.message, {
+        declaredType: error.declaredType,
+        suggestedTypes: error.suggestedTypes,
+        rationale: error.rationale
+    }, [
+        `Re-classify the request — likely correct type: ${error.suggestedTypes.join(' | ')}`,
+        'Or, if the declared type is correct, surface the mismatch reason to the user.'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function reportFileSizeFailure(io, options, error) {
+    printResult(io, fail('request.transition', error.code, error.message, { violations: error.violations }, [
+        ...error.violations.map((v) => `Split ${v.file} (${v.lines} lines) below its ${v.cap}-line cap`),
+        'Or bypass with: --allow-incomplete --reason "<justification>"'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function reportConfirmationFailure(io, options, requestId, error) {
+    printResult(io, fail('request.transition', 'CONFIRMATION_REQUIRED', error.message, { role: options.role, requestId, transitionKey: error.transitionKey, mode: error.mode }, [...error.nextActions]), options.json);
+    process.exitCode = 1;
+}
+/**
+ * Map a thrown transition error to its envelope. `InvalidArgumentError` is
+ * re-thrown: Commander raises it for an unparsable `--state`, and swallowing it
+ * here would report a usage error as a transition failure.
+ */
+export function reportTransitionFailure(io, options, requestId, error) {
+    if (error instanceof InvalidArgumentError) {
+        throw error;
+    }
+    if (error instanceof PrerequisitesNotSatisfiedError) {
+        reportPrerequisitesFailure(io, options, error);
+        return;
+    }
+    if (error instanceof LintGateError) {
+        reportLintGateFailure(io, options, error);
+        return;
+    }
+    if (error instanceof TypeSanityViolationError) {
+        reportTypeSanityFailure(io, options, error);
+        return;
+    }
+    if (error instanceof FileSizeViolationError) {
+        reportFileSizeFailure(io, options, error);
+        return;
+    }
+    if (error instanceof ConfirmationRequiredError) {
+        reportConfirmationFailure(io, options, requestId, error);
+        return;
+    }
+    printResult(io, fail('request.transition', 'REQUEST_TRANSITION_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, state, and project path before retrying']), options.json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/request-transition-hooks.d.ts

@@ -0,0 +1,50 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+import type { RequestArtifactRole, RequestArtifactState, transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+import { type CodegraphAutorefreshResult } from '../../services/codegraph/codegraph-autorefresh.js';
+import type { RequestTransitionOptions } from './request-command-options.js';
+export type TransitionResult = NonNullable<Awaited<ReturnType<typeof transitionRequestArtifact>>>;
+export type TransitionHooks = {
+    preCompact: ResultEnvelope<unknown> | null;
+    codegraphRefresh: CodegraphAutorefreshResult | null;
+    codegraphWarning: string | null;
+};
+type PrdHandoffContext = {
+    role: RequestArtifactRole;
+    newState: RequestArtifactState;
+    requestId: string;
+    options: RequestTransitionOptions;
+    result: TransitionResult;
+};
+/**
+ * The RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
+ * otherwise. Best-effort and fail-silent — never blocks the transition.
+ *
+ * When transitioning across the RD → QA boundary (rd:qa-handoff), check the
+ * active session's context-fill ratio. If it is in the 0.85–0.95 pre-compact
+ * zone, write a checkpoint BEFORE the transition completes and attach
+ * `preCompactCheckpoint: true` to the response envelope. The LLM remains the
+ * decision-maker; this hook only surfaces the signal. At ratio ≥ 0.95 the
+ * auto-compact orchestrator ASKS the harness to compact and reports that it is
+ * waiting; it does not refuse anything, because peaks-loop has no executor for
+ * a running session and a refusal it cannot enforce only deadlocked the runner.
+ *
+ * A2 (2026-09-17): never BLOCKING is kept; never VISIBLE is not. A non-refresh
+ * while a codegraph store is in use becomes a warning line beside the
+ * transition's own notes. See `codegraphRefreshNotice` for why
+ * `no-codegraph-dir` stays silent.
+ */
+export declare function collectQaHandoffHooks(role: RequestArtifactRole, newState: RequestArtifactState, sessionId: string, project: string): Promise<TransitionHooks>;
+/**
+ * Only fires when the handoff is missing; existing handoffs are not
+ * overwritten. Post-step after peaks-prd's businessGoal artifact transitions to
+ * `handed-off` (the canonical "complete" state in the prd state machine). The
+ * trigger is fire-and-forget: failure NEVER blocks the transition.
+ */
+export declare function buildPrdHandoffResult(ctx: PrdHandoffContext): Promise<ResultEnvelope<unknown> | null>;
+/**
+ * The pre-compact signal rendered into the final envelope's `nextActions`.
+ * `null` when the hook did not trigger (zone is not pre-compact OR the
+ * transition is not a slice boundary).
+ */
+export declare function preCompactNote(preCompact: ResultEnvelope<unknown> | null): string | null;
+export {};