peaks-loop 4.1.2 → 4.1.3

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 {};

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

@@ -0,0 +1,115 @@
+// Split out of `request-commands.ts`: the two
+// best-effort hooks attached to a completed `peaks request transition` — the
+// rd→qa pre-compact checkpoint + codegraph refresh, and the prd→handed-off
+// handoff auto-regen envelope.
+import { ok } from 'peaks-loop-shared/result';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice } from '../../services/codegraph/codegraph-autorefresh.js';
+import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
+const NO_HOOKS = {
+    preCompact: null,
+    codegraphRefresh: null,
+    codegraphWarning: null
+};
+/**
+ * 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 async function collectQaHandoffHooks(role, newState, sessionId, project) {
+    if (role !== 'rd' || newState !== 'qa-handoff')
+        return NO_HOOKS;
+    let preCompact = null;
+    let codegraphRefresh = null;
+    try {
+        const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
+        const hook = maybePreCompactCheckpoint({
+            projectRoot: project,
+            sessionId,
+            transitionKey: `${role}:${newState}`
+        });
+        preCompact = hook.triggered ? ok('request.transition.preCompact', hook) : null;
+    }
+    catch {
+        // The hook is best-effort; never block the transition.
+        preCompact = null;
+    }
+    try {
+        codegraphRefresh = await refreshCodegraphAfterSlice(project);
+    }
+    catch {
+        // The refresh is best-effort; never block the transition.
+        codegraphRefresh = {
+            refreshed: false,
+            reason: 'unavailable',
+            note: 'auto codegraph refresh failed after transition'
+        };
+    }
+    return {
+        preCompact,
+        codegraphRefresh,
+        codegraphWarning: codegraphRefreshNotice(codegraphRefresh)
+    };
+}
+/**
+ * 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 async function buildPrdHandoffResult(ctx) {
+    const { role, newState, requestId, options, result } = ctx;
+    if (role !== 'prd' || newState !== 'handed-off' || options.sessionId === undefined) {
+        return null;
+    }
+    const { autoRegenPrdHandoff } = await import('../../services/prd/handoff-auto-regen.js');
+    const regen = await autoRegenPrdHandoff({
+        projectRoot: options.project,
+        sessionId: result.sessionId,
+        requestId,
+        role: 'prd'
+    });
+    const bpsTrigger = await triggerBestPracticeScan({
+        projectRoot: options.project,
+        sessionId: result.sessionId,
+        requestId
+    });
+    const handoffAutoRegen = regen.status === 'created'
+        ? { status: 'created', path: regen.path, sha256: regen.sha256 }
+        : regen.status === 'skipped-exists'
+            ? { status: 'skipped-exists', path: regen.path }
+            : { status: 'failed', reason: regen.reason };
+    const notes = [];
+    if (regen.status === 'failed') {
+        notes.push(`prd handoff auto-regen failed: ${regen.reason}`);
+    }
+    if (bpsTrigger.status === 'failed') {
+        notes.push(`best-practice-scan auto-trigger failed: ${bpsTrigger.reason ?? 'unknown'}`);
+    }
+    return ok('request.transition', { ...result, handoffAutoRegen, bestPracticeScanTrigger: bpsTrigger }, notes);
+}
+/**
+ * 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 function preCompactNote(preCompact) {
+    if (preCompact === null)
+        return null;
+    const ratio = typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
+        ? String(preCompact.data.ratio)
+        : 'unknown';
+    return `Pre-compact checkpoint written at ratio=${ratio} (zone=pre-compact)`;
+}

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

@@ -0,0 +1,10 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type RequestArtifactRole } from '../../services/artifacts/request-artifact-service.js';
+import type { RequestTransitionOptions } from './request-command-options.js';
+export type TransitionPreflight = {
+    proceed: true;
+    resolvedSessionId: string | undefined;
+} | {
+    proceed: false;
+};
+export declare function runTransitionPreflight(io: ProgramIO, requestId: string, role: RequestArtifactRole, options: RequestTransitionOptions): Promise<TransitionPreflight>;