peaks-loop 4.1.2 → 4.1.3

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

@@ -1,524 +1,19 @@
-import { InvalidArgumentError } from 'commander';
-import { createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError, VALID_REQUEST_TYPES } from '../../services/artifacts/request-artifact-service.js';
-import { boundedNames, fitSummaryToBytes } from '../../services/context/summary-view.js';
-import { applyPerArtifactFormat, inferArtifactName, parseRequestType, parseRole, parseStateForRole, resolveDefaultFormat, VALID_ROLES } from './request-format-helpers.js';
-import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
-import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
-import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
-import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
-import { codegraphRefreshNotice, refreshCodegraphAfterSlice } from '../../services/codegraph/codegraph-autorefresh.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { isUnsafePathInput } from '../../shared/path-safety.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 function buildRequestListSummary(items) {
-    const view = {
-        view: 'summary',
-        count: items.length,
-        items: boundedNames(items.map((i) => `${i.role}/${i.requestId} (${i.state})`))
-    };
-    return fitSummaryToBytes(view);
-}
+import { registerRequestInitCommand } from './request-init-command.js';
+import { registerRequestListCommand } from './request-list-command.js';
+import { registerRequestShowCommand } from './request-show-command.js';
+import { registerRequestTransitionCommand } from './request-transition-command.js';
+import { registerRequestLintCommand } from './request-lint-command.js';
+import { registerRequestRepairStatusCommand } from './request-repair-status-command.js';
+// Published import path preserved: `tests/unit/services/context/summary-view.test.ts`
+// imports `buildRequestListSummary` from here.
+export { buildRequestListSummary } from './request-list-command.js';
+const REQUEST_DESCRIPTION = 'Manage per-request Peaks role artifacts (PRD / UI / RD / QA)';
 export function registerRequestCommands(program, io) {
-    const request = program
-        .command('request')
-        .description('Manage per-request Peaks role artifacts (PRD / UI / RD / QA)');
-    addJsonOption(request
-        .command('init')
-        .description('Create the per-request artifact template for a Peaks role (dry-run by default)')
-        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
-        .requiredOption('--id <request-id>', '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.')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'override the default date-stamped session id')
-        .option('--apply', 'write the artifact file (default: preview only)')
-        .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>', '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.')).action(async (options) => {
-        try {
-            // 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`.
-            if (options.sessionId === undefined || options.sessionId.trim().length === 0) {
-                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;
-                return;
-            }
-            const serviceOptions = {
-                role: options.role,
-                requestId: options.id,
-                projectRoot: options.project
-            };
-            serviceOptions.sessionId = options.sessionId;
-            if (options.apply === true) {
-                serviceOptions.apply = true;
-            }
-            if (options.type !== undefined) {
-                serviceOptions.requestType = options.type;
-            }
-            // platform fallback > reject). 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.
-            const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
-            try {
-                const callerId = resolveCallerId(options.callerId !== undefined ? { flagValue: options.callerId } : {});
-                serviceOptions.callerId = 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 }, [
-                        '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)'
-                    ]), options.json);
-                    process.exitCode = code;
-                    return;
-                }
-                throw error;
-            }
-            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;
-        }
-    });
-    addJsonOption(request
-        .command('list')
-        .description('List per-request artifacts under a project workspace')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'limit to a specific session id')
-        .option('--role <role>', `limit to a single role (${VALID_ROLES.join(' | ')})`, parseRole)
-        .option('--summary', 'emit counts + names-of-first-N only (≤ 2 KB) instead of the full item array; the default envelope is unchanged')).action(async (options) => {
-        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;
-        }
-    });
-    addJsonOption(request
-        .command('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.')
-        .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
-        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')
-        .option('--pretty', 'force the body to render pretty (overrides the per-artifact default)')
-        .option('--compact', 'force the body to render compact (overrides the per-artifact default)')).action(async (requestId, options) => {
-        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) {
-                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;
-                return;
-            }
-            // 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);
-            const payload = transformed === result ? { ...result, format } : transformed;
-            printResult(io, ok('request.show', payload), 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;
-        }
-    });
-    addJsonOption(request
-        .command('transition')
-        .description('Move a per-request artifact to a new state defined by its role state machine')
-        .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
-        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
-        .requiredOption('--state <state>', 'new state name; allowed values depend on role')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')
-        .option('--reason <text>', 'reason appended as a transition note; required when --allow-incomplete is set')
-        .option('--allow-incomplete', 'bypass artifact prerequisite checks; requires --reason and records the bypass in the artifact')
-        .option('--confirm', 'skip the confirmation gate (for non-interactive / LLM contexts)')
-        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')).action(async (requestId, options) => {
-        try {
-            const role = options.role;
-            const newState = parseStateForRole(role, options.state);
-            // Resolve the artifact's real session up front. Falling back to a literal
-            // 'default' (the previous behavior) points the bypass counter at a
-            // non-existent .peaks/default/ dir and crashes with ENOENT, so when
-            // --session-id is omitted we look the artifact up to find its session.
-            let resolvedSessionId = options.sessionId;
-            // Sid axis: either arm of `resolvedSessionId` can be a caller-supplied
-            // `--session-id`, and it is joined into the bypass-counter root below.
-            if (resolvedSessionId !== undefined && isUnsafePathInput(resolvedSessionId)) {
-                printResult(io, fail('request.transition', 'INVALID_SESSION_ID', `Invalid session id: ${resolvedSessionId} (must be a single path segment)`, { provided: resolvedSessionId }, ['Pass a session id that is a single path segment']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (resolvedSessionId === undefined) {
-                const { showRequestArtifact: showForSession } = await import('../../services/artifacts/request-artifact-service.js');
-                const located = await showForSession({ projectRoot: options.project, role, requestId });
-                if (located !== null) {
-                    resolvedSessionId = located.sessionId;
-                }
-            }
-            if (options.allowIncomplete === true &&
-                (options.reason === undefined || options.reason.trim().length === 0)) {
-                printResult(io, fail('request.transition', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why prerequisites are skipped', { role, requestId }, [
-                    'Add --reason "<short justification>" or remove --allow-incomplete and produce the missing artifacts'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            // Restrict --allow-incomplete in assisted/strict modes: require --confirm
-            if (options.allowIncomplete === true && options.forceConfirm !== true) {
-                const { getSkillPresence } = await import('../../services/skills/skill-presence-service.js');
-                const presence = getSkillPresence(options.project);
-                if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
-                    if (options.confirm !== true) {
-                        printResult(io, fail('request.transition', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { role, requestId, mode: presence.mode }, [
-                            'Ask the user via AskUserQuestion whether to proceed, then re-run with --confirm if they approve.'
-                        ]), options.json);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    // 2.7.1 fix: bypass-count must live under the canonical session
-                    // home `.peaks/_runtime/<sid>/`, NOT `.peaks/_runtime/<sid>/`. The legacy
-                    // path landed `.bypass-count.json` at the project root and was
-                    // ignored only by `.gitignore`, not by the runtime — a
-                    // back-compat reader on the root would never see it. The
-                    // canonical home is the same one `peaks session info --active`
-                    // resolves from `_runtime/session.json`, so all session-scoped
-                    // state (artifacts + bypass counter) now lives in one tree.
-                    const sessionRoot = (await import('node:path')).join(options.project, '.peaks', '_runtime', resolvedSessionId ?? 'default');
-                    if (isBypassLimitReached(sessionRoot)) {
-                        printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role, requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Produce the missing artifacts instead of bypassing.']), options.json);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    recordBypass(sessionRoot);
-                }
-            }
-            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;
-            }
-            // Type sanity check for PRD handoff
-            if (role === 'prd' && newState === 'handed-off') {
-                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
-                    };
-                }
-            }
-            const result = await transitionRequestArtifact(transitionOptions);
-            if (result === null) {
-                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;
-                return;
-            }
-            // hook. 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 (slice
-            let preCompact = null;
-            // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
-            // otherwise. Best-effort and fail-silent — never blocks the transition.
-            let codegraphRefresh = null;
-            // A2 (2026-09-17): the human-visible half of the refresh outcome. null
-            // when the refresh succeeded or when no codegraph store was in use.
-            let codegraphWarning = null;
-            if (role === 'rd' && newState === 'qa-handoff') {
-                try {
-                    const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
-                    const hook = maybePreCompactCheckpoint({
-                        projectRoot: options.project,
-                        sessionId: result.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(options.project);
-                }
-                catch {
-                    // The refresh is best-effort; never block the transition.
-                    codegraphRefresh = {
-                        refreshed: false,
-                        reason: 'unavailable',
-                        note: 'auto codegraph refresh failed after transition'
-                    };
-                }
-                // 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.
-                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.
-            if (role === 'prd' && newState === 'handed-off' && options.sessionId !== undefined) {
-                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'}`);
-                }
-                printResult(io, ok('request.transition', { ...result, handoffAutoRegen, bestPracticeScanTrigger: bpsTrigger }, notes), options.json);
-                return;
-            }
-            // checkpoint signal into the final response envelope. When the
-            // hook did not trigger (zone is not pre-compact OR the
-            // transition is not a slice boundary), preCompact is null and
-            // we emit a `preCompactCheckpoint: null` field so LLM callers
-            // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, [
-                ...(preCompact !== null
-                    ? [
-                        `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' &&
-                            preCompact.data !== null &&
-                            'ratio' in preCompact.data
-                            ? String(preCompact.data.ratio)
-                            : 'unknown'} (zone=pre-compact)`
-                    ]
-                    : []),
-                ...(codegraphWarning === null ? [] : [codegraphWarning])
-            ]), options.json);
-        }
-        catch (error) {
-            if (error instanceof InvalidArgumentError) {
-                throw error;
-            }
-            if (error instanceof PrerequisitesNotSatisfiedError) {
-                // 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;
-                return;
-            }
-            if (error instanceof LintGateError) {
-                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;
-                return;
-            }
-            if (error instanceof TypeSanityViolationError) {
-                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;
-                return;
-            }
-            if (error instanceof FileSizeViolationError) {
-                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;
-                return;
-            }
-            if (error instanceof ConfirmationRequiredError) {
-                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;
-                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;
-        }
-    });
-    addJsonOption(request
-        .command('lint')
-        .description('Scan a request artifact body for unfilled placeholders (<...>, TBD, bare bullets) before declaring it complete')
-        .argument('<request-id>', 'request id')
-        .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')).action(async (requestId, options) => {
-        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) {
-                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;
-                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;
-        }
-    });
-    addJsonOption(request
-        .command('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')
-        .argument('<request-id>', 'request id')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')
-        .option('--max-cycles <n>', 'override the default max cycle cap (default 3)')).action(async (requestId, options) => {
-        try {
-            const max = options.maxCycles !== undefined && /^\d+$/.test(options.maxCycles)
-                ? Number(options.maxCycles)
-                : 3;
-            const statusOptions = {
-                projectRoot: options.project,
-                requestId,
-                maxCycles: max
-            };
-            if (options.sessionId !== undefined) {
-                statusOptions.sessionId = options.sessionId;
-            }
-            const report = await getRepairCycleStatus(statusOptions);
-            if (report === null) {
-                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;
-                return;
-            }
-            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.`);
-            }
-            printResult(io, ok('request.repair-status', report, [], nextActions), 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;
-        }
-    });
+    const request = program.command('request').description(REQUEST_DESCRIPTION);
+    registerRequestInitCommand(request, io);
+    registerRequestListCommand(request, io);
+    registerRequestShowCommand(request, io);
+    registerRequestTransitionCommand(request, io);
+    registerRequestLintCommand(request, io);
+    registerRequestRepairStatusCommand(request, io);
 }

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

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

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));
+}