peaks-cli 1.3.7 → 1.3.9

package/dist/src/cli/commands/core-artifact-commands.js

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { createArtifactInitPlan, getArtifactStatus, createGuidedArtifactSetup } from '../../services/artifacts/artifact-service.js';
 import { getArtifactWorkspaceStatus, planArtifactSync } from '../../services/artifacts/workspace-service.js';
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../services/memory/project-memory-service.js';
@@ -206,26 +208,129 @@ export function registerCoreAndArtifactCommands(program, io) {
     });
     addJsonOption(session
         .command('info [sessionId]')
-        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive).')
-        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')).action(async (sessionId, options) => {
-        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-        // Slice 007 — sub-agent session sharing. A sub-agent that does
-        // not know the parent's sid reads it from the binding via
-        // `peaks session info --active`. The call uses the
-        // canonicalize-on-read path so a stored "projectRoot: '.'" and a
-        // caller-passed absolute realpath both resolve to the same
-        // binding. Without this primitive the sub-agent has no way to
-        // discover the parent sid short of scanning the filesystem.
+        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive). Slice 021: --active is the SOLE authoritative way to look up the active session id; the on-disk file path is internal and must NOT be `cat`-ed directly.')
+        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd). Slice 021: lets sub-agents skip the cwd heuristic and look up the binding for a specific repo.')
+        // Slice 020 — caller-keyed session binding. The --caller-id flag
+        // overrides the per-process PEAKS_CALLER_ID env var and the
+        // PLATFORM_FALLBACKS table (D4 priority). The resolved callerId is
+        // surfaced in the JSON envelope so callers can confirm what was
+        // resolved without re-deriving it.
+        .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). When set, the response envelope includes the resolved callerId.')).action(async (sessionId, options) => {
+        // Slice 021: --project wins; otherwise the git-root / cwd fallback
+        // (matches the pre-021 behaviour so the existing slice-020 / slice-007
+        // sub-agent flow keeps working unchanged).
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        // Slice 020 — resolve the callerId up front when the flag was passed.
+        // We use `resolveCallerId` for D1/D5 validation; an invalid flag
+        // throws CallerIdError (D5 → exit 65). A missing flag and no env
+        // and no fallback also throws (D2 → exit 64). The resolved id is
+        // surfaced in the envelope so the caller can audit.
+        if (options.callerId !== undefined) {
+            const { resolveCallerId, CallerIdError } = await import('../../services/session/resolve-caller-id.js');
+            let callerId;
+            try {
+                callerId = resolveCallerId({ flagValue: options.callerId });
+            }
+            catch (error) {
+                if (error instanceof CallerIdError) {
+                    const code = error.code === 'EX_USAGE' ? 64 : 65;
+                    printResult(io, fail('session.info', '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;
+            }
+            // Surface the resolved id in the envelope. When --active is also
+            // passed, look up the binding for this callerId; otherwise
+            // just emit the resolved id so the caller knows what was used.
+            if (options.active === true) {
+                const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+                const { getCallerBinding } = await import('../../services/session/caller-binding-service.js');
+                const activeSid = getSessionIdCanonical(projectRoot);
+                const callerBinding = getCallerBinding(projectRoot, callerId);
+                // Slice 021: source is the enum that the unified --active primitive
+                // reports. Callers / migration tooling can detect pre-migration trees
+                // by inspecting `source === 'legacy'`.
+                const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                    ? 'canonical'
+                    : 'legacy';
+                printResult(io, ok('session.info', {
+                    active: true,
+                    sessionId: activeSid,
+                    callerId,
+                    callerBindingPeakSessionId: callerBinding?.peakSessionId ?? null,
+                    source: bindingSource
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('session.info', { callerId, note: '--caller-id resolved; pass --active to also look up the bound peak session' }), options.json);
+            return;
+        }
+        // Slice 007 + slice 021 — sub-agent session sharing. A sub-agent that
+        // does not know the parent's sid reads it from the binding via
+        // `peaks session info --active`. Slice 021 turned this into the
+        // SOLE authoritative discovery primitive: it composes on
+        // getSessionIdCanonical (canonicalize-on-read; handles the stored
+        // "projectRoot: '.'" vs caller-passed absolute realpath mismatch
+        // that the F22 fix addressed) AND falls through to getSessionId
+        // (strict-equality) for callers on the original contract. NEITHER
+        // path may call ensureSession() — that would side-effect-create a
+        // fresh binding on miss, erasing the "no active session" signal
+        // sub-agents rely on.
         if (options.active === true) {
             // Import lazily to avoid a cycle with workspace-commands.
-            const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
-            const activeSid = getSessionIdCanonical(projectRoot);
+            const { getSessionIdCanonical, getSessionId } = await import('../../services/session/session-manager.js');
+            // 1. Canonicalize-on-read first.
+            let activeSid = getSessionIdCanonical(projectRoot);
+            // 2. Fall through to the strict-equality reader if the canonical
+            //    miss is a projectRoot-form mismatch (e.g. the binding was
+            //    written with the absolute realpath but the caller's form
+            //    normalizes differently). The 2-read fan-out mirrors the
+            //    fallback ensureSession() uses.
+            if (activeSid === null) {
+                activeSid = getSessionId(projectRoot);
+            }
             if (activeSid === null) {
-                printResult(io, fail('session.info', 'NO_ACTIVE_BINDING', 'No canonical session binding at .peaks/_runtime/session.json', { projectRoot }, ['Run `peaks workspace init` or `peaks skill presence:set` to anchor a session']), options.json);
+                // 3. No binding at all — fail loudly, NO crash, NO side-effect,
+                //    exit 1, message must point at `peaks workspace init`
+                //    (the canonical "first action" command, not the legacy
+                //    "or `peaks skill presence:set`" hedge that the pre-021
+                //    wording used — presence:set would also need a binding to
+                //    resolve the parent sid, so it's not actually a bootstrap
+                //    path).
+                printResult(io, fail('session.info', 'NO_ACTIVE_SESSION', 'No session bound. Run `peaks workspace init --project <repo> --json` to bind one.', { projectRoot }, [`peaks workspace init --project ${projectRoot} --json`]), options.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('session.info', { active: true, sessionId: activeSid, source: '.peaks/_runtime/session.json' }), options.json);
+            // 4. Determine the on-disk source so callers (and future
+            //    migration tooling) can detect pre-migration trees. The
+            //    canonical file is preferred when both exist (slice 005
+            //    contract).
+            const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                ? 'canonical'
+                : 'legacy';
+            // Slice 021: when only the legacy back-compat path is present,
+            // surface a warning so callers (and humans tailing the JSON)
+            // see "this tree has not been reconciled to the canonical
+            // home yet". The warning is informational; the binding is
+            // still valid for one minor release (slice 005 / 006
+            // contract). `warnings` is a top-level envelope field, not a
+            // data field, so it goes through ok()'s 3rd positional arg.
+            const legacyWarnings = bindingSource === 'legacy'
+                ? ['Read from legacy back-compat path .peaks/.session.json. Run `peaks workspace reconcile --apply` to migrate to the canonical home (.peaks/_runtime/session.json).']
+                : [];
+            printResult(io, ok('session.info', {
+                active: true,
+                sessionId: activeSid,
+                bindingPath: bindingSource === 'canonical'
+                    ? join(projectRoot, '.peaks', '_runtime', 'session.json')
+                    : join(projectRoot, '.peaks', '.session.json'),
+                projectRoot,
+                source: bindingSource
+            }, legacyWarnings), options.json);
             return;
         }
         if (sessionId === undefined) {

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

@@ -1,6 +1,8 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
 import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { extractSessionMemories, readMemoryIndex, readProjectMemories } from '../../services/memory/project-memory-service.js';
+import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
@@ -158,4 +160,59 @@ export function registerProjectCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // --- Show one project memory's body (R3: default = compact) ---
+    addJsonOption(project
+        .command('memories:show <name>')
+        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
+        .option('--include-stale', 'include stale entries (the default excludes them)')
+        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => {
+        try {
+            const memory = readProjectMemoryBody(options.project, name);
+            if (memory === null) {
+                printResult(io, fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: options.project }, ['Run `peaks project memories --json` to see available names']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Compute the stale decision. R4: stale is computed at CLI load time
+            // only; the source `.md` file is never modified.
+            const updatedAt = memory.updatedAt;
+            const thresholdDays = options.staleDays !== undefined && Number.isFinite(options.staleDays) && options.staleDays > 0
+                ? options.staleDays
+                : DEFAULT_STALE_DAYS;
+            const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
+                thresholdDays,
+                includeStale: options.includeStale === true
+            });
+            if (policy.entries.length === 0) {
+                const ageDays = policy.entries.length === 0 && policy.droppedCount > 0
+                    ? applyStalePolicy([{ name: memory.name, updatedAt }], { thresholdDays, includeStale: true }).entries[0]?.ageDays ?? 0
+                    : 0;
+                printResult(io, fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, ['Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const ageDays = policy.entries[0]?.ageDays ?? 0;
+            const isStale = policy.entries[0]?.stale ?? false;
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
+            printResult(io, ok('project.memories:show', {
+                name: memory.name,
+                title: memory.title,
+                kind: memory.kind,
+                sourcePath: memory.filePath,
+                updatedAt,
+                ageDays,
+                stale: isStale,
+                body,
+                format,
+                bodyBytes: Buffer.byteLength(body, 'utf8')
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -5,7 +5,82 @@ import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '..
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from '../../shared/result.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * Per-artifact default format. Only PRD and tech-doc are user-review
+ * surfaces; all other RD/QA/TXT artifacts default to compact. The
+ * `--pretty` / `--compact` flags override uniformly. See tech-doc
+ * §1.3.
+ */
+const DEFAULT_FORMAT_BY_ARTIFACT = {
+    prd: 'pretty',
+    'tech-doc': 'pretty',
+    'code-review': 'compact',
+    'security-review': 'compact',
+    'perf-baseline': 'compact',
+    'bug-analysis': 'compact',
+    'test-cases': 'compact',
+    'test-reports': 'compact',
+    'security-findings': 'compact',
+    'performance-findings': 'compact',
+    handoff: 'compact'
+};
+function resolveDefaultFormat(artifactName) {
+    return DEFAULT_FORMAT_BY_ARTIFACT[artifactName] ?? 'compact';
+}
+function applyPerArtifactFormat(envelope, override) {
+    if (override === null || envelope === null || typeof envelope !== 'object')
+        return envelope;
+    // The service returns `{ id, sessionId, role, body, ... }` for a
+    // single-artifact show. The per-artifact `body` field is the only
+    // thing that changes; we attach a `format` field to surface the
+    // choice to the caller. Slice 023 (R3) AC6 / AC7.
+    const obj = envelope;
+    if (typeof obj.body === 'string') {
+        return {
+            ...obj,
+            body: override === 'compact' ? formatMdCompact(obj.body) : obj.body,
+            format: override
+        };
+    }
+    return envelope;
+}
+/**
+ * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
+ * The service returns the path of the artifact in `path`; the role +
+ * filename stem gives us the artifact name. Falls back to the role
+ * itself when no `path` field is present.
+ */
+function inferArtifactName(envelope, role) {
+    if (envelope === null || typeof envelope !== 'object')
+        return role;
+    const obj = envelope;
+    const pathField = typeof obj.path === 'string' ? obj.path : '';
+    // Path looks like `.peaks/_runtime/<sid>/<role>/requests/<file>.md`.
+    // The role is the second-to-last directory; the file stem is the
+    // last segment. For RD role, the artifact is one of {code-review,
+    // security-review, perf-baseline, bug-analysis, tech-doc}; the file
+    // stem usually carries the artifact name (e.g. `tech-doc.md`,
+    // `code-review-002.md`). We strip the trailing `-<digits>` suffix
+    // when present.
+    const stem = pathField.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? '';
+    if (stem.length > 0) {
+        // Try the stem verbatim first.
+        if (DEFAULT_FORMAT_BY_ARTIFACT[stem] !== undefined)
+            return stem;
+        // Strip a trailing -<digits> (e.g. code-review-002 -> code-review).
+        const trimmed = stem.replace(/-\d+$/, '');
+        if (DEFAULT_FORMAT_BY_ARTIFACT[trimmed] !== undefined)
+            return trimmed;
+        // Last-ditch: match by prefix.
+        for (const key of Object.keys(DEFAULT_FORMAT_BY_ARTIFACT)) {
+            if (stem.startsWith(key))
+                return key;
+        }
+    }
+    return role;
+}
 const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
 function parseRole(value) {
     if (!VALID_ROLES.includes(value)) {
@@ -36,7 +111,12 @@ export function registerRequestCommands(program, io) {
         .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)).action(async (options) => {
+        .option('--type <type>', `request type (${VALID_REQUEST_TYPES.join(' | ')}); default: feature`, parseRequestType)
+        // Slice 020 — caller-keyed session binding. Per-invocation override
+        // (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 {
             const serviceOptions = {
                 role: options.role,
@@ -57,6 +137,31 @@ export function registerRequestCommands(program, io) {
             if (options.type !== undefined) {
                 serviceOptions.requestType = options.type;
             }
+            // Slice 020.1 — resolve the callerId via D4 priority (flag > env >
+            // 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);
         }
@@ -89,11 +194,13 @@ export function registerRequestCommands(program, io) {
     });
     addJsonOption(request
         .command('show')
-        .description('Show a single per-request artifact, optionally scoped to a session')
+        .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')).action(async (requestId, options) => {
+        .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,
@@ -109,7 +216,20 @@ export function registerRequestCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('request.show', result), options.json);
+            // 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);

package/dist/src/cli/commands/retrospective-commands.d.ts

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

package/dist/src/cli/commands/retrospective-commands.js

@@ -0,0 +1,113 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { loadRetrospectiveIndex } from '../../services/retrospective/retrospective-index.js';
+import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
+import { migrateRetrospectiveFromMd } from '../../services/retrospective/migrate-from-md.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerRetrospectiveCommands(program, io) {
+    const retrospective = program.command('retrospective').description('Read the peaks retrospective index (R3: index.json, not the legacy <id>/ MD tree)');
+    addJsonOption(retrospective
+        .command('index')
+        .description('List all retrospective entries from .peaks/retrospective/index.json (R3: replaces the per-workflow MD dirs)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const result = loadRetrospectiveIndex(projectRoot);
+            const warnings = result.warning === null ? [] : [result.warning];
+            printResult(io, ok('retrospective.index', {
+                indexPath: result.indexPath,
+                source: result.source,
+                total: result.totalCount,
+                entries: result.entries
+            }, warnings), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.index', 'RETROSPECTIVE_INDEX_FAILED', getErrorMessage(error), { projectRoot }, ['Check the project path and .peaks/retrospective/index.json']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(retrospective
+        .command('show <id>')
+        .description('Show one retrospective entry by id. Default format is `compact` (LLM-primary); pass --pretty to get the disk / re-hydrated pretty form.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--pretty', 'return the pretty form (re-hydrated from source artifacts); overrides the compact default')).action((id, options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const result = showRetrospective({ projectRoot, id, format });
+            if (!result.ok) {
+                const suggestions = [];
+                if (result.code === 'INDEX_MISSING')
+                    suggestions.push('Run `peaks retrospective migrate --apply` to build the index');
+                if (result.code === 'NOT_FOUND')
+                    suggestions.push('Run `peaks retrospective index --json` to see available ids');
+                if (result.code === 'ARTIFACT_MISSING' || result.missingArtifacts !== undefined) {
+                    suggestions.push('Re-hydrate from the legacy archive at .peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz');
+                }
+                printResult(io, fail('retrospective.show', result.code, result.message, { id, projectRoot, ...(result.missingArtifacts !== undefined ? { missingArtifacts: result.missingArtifacts } : {}) }, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('retrospective.show', {
+                id: result.entry.id,
+                sessionId: result.entry.sessionId,
+                sliceId: result.entry.sliceId ?? null,
+                type: result.entry.type,
+                title: result.entry.title,
+                summary: result.entry.summary,
+                outcome: result.entry.outcome,
+                keyDecisions: result.entry.keyDecisions,
+                lessonsLearned: result.entry.lessonsLearned,
+                artifactPaths: result.entry.artifactPaths,
+                updatedAt: result.entry.updatedAt,
+                body: result.body,
+                format: result.format
+            }, result.warnings), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.show', 'RETROSPECTIVE_SHOW_FAILED', getErrorMessage(error), { id, projectRoot }, ['Check the project path and id']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(retrospective
+        .command('migrate')
+        .description('One-time migration from per-workflow .peaks/retrospective/<id>/*.md dirs to a single .peaks/retrospective/index.json + .peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz archive. Dry-run by default; --apply is destructive.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--apply', 'write the index.json + archive + delete legacy MDs (default: dry-run preview)')
+        .option('--include-failed', 'include malformed MDs as best-effort entries; default is to skip + warn')
+        .option('--expected-entries <n>', 'override the default expected entry count (88) for the no-op check', (value) => Number(value))).action((options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const result = migrateRetrospectiveFromMd({
+                projectRoot,
+                apply: options.apply === true,
+                includeFailed: options.includeFailed === true,
+                ...(options.expectedEntries !== undefined && Number.isFinite(options.expectedEntries) ? { expectedEntries: options.expectedEntries } : {})
+            });
+            const exitCode = result.status === 'failed' ? 1 : 0;
+            printResult(io, ok('retrospective.migrate', {
+                status: result.status,
+                indexPath: result.indexPath,
+                archivePath: result.archivePath,
+                totalLegacyDirs: result.totalLegacyDirs,
+                totalLegacyMds: result.totalLegacyMds,
+                parsedEntries: result.parsedEntries,
+                failedEntries: result.failedEntries,
+                archiveVerified: result.archiveVerified
+            }, result.warnings), options.json);
+            if (exitCode !== 0)
+                process.exitCode = exitCode;
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.migrate', 'RETROSPECTIVE_MIGRATE_FAILED', getErrorMessage(error), { projectRoot }, ['Check the project path and .peaks/retrospective/ directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/program.js

@@ -14,6 +14,7 @@ import { registerPerfCommands } from './commands/perf-commands.js';
 // surfaced via `peaks sub-agent dispatch|heartbeat|share`.
 import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
+import { registerRetrospectiveCommands } from './commands/retrospective-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
 import { registerSliceCommands } from './commands/slice-commands.js';
@@ -90,6 +91,7 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerPerfCommands(program, io);
     registerProjectCommands(program, io);
     registerRequestCommands(program, io);
+    registerRetrospectiveCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
     registerSliceCommands(program, io);

package/dist/src/services/artifacts/request-artifact-service.d.ts

@@ -17,6 +17,16 @@ export type CreateRequestArtifactOptions = {
     apply?: boolean;
     requestType?: RequestType;
     clock?: () => string;
+    /**
+     * Slice 020 — caller-keyed session binding. The callerId that initiated
+     * this artifact creation (resolved via `resolveCallerId` by the CLI).
+     * Recorded in the JSON envelope and on the artifact body's frontmatter
+     * so a future reader knows which caller produced it. The caller-keyed
+     * binding file itself is at `.peaks/_runtime/callers/<callerId>.json`;
+     * the per-caller active-skill marker is at
+     * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6).
+     */
+    callerId?: string;
 };
 export type CreateRequestArtifactResult = {
     role: RequestArtifactRole;
@@ -25,6 +35,12 @@ export type CreateRequestArtifactResult = {
     path: string;
     content: string;
     applied: boolean;
+    /**
+     * Slice 020 — caller-keyed session binding. The resolved callerId
+     * (D4 priority: flag > env > platform fallback) when --caller-id
+     * was passed. Omitted from the result when no callerId was set.
+     */
+    callerId?: string;
 };
 export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
 export type RequestArtifactSummary = {

package/dist/src/services/artifacts/request-artifact-service.js

@@ -374,7 +374,15 @@ export async function createRequestArtifact(options) {
     const path = join(requestsDir, filename);
     const content = renderTemplate(options.role, options.requestId, changeId, sessionId, timestamp, requestType);
     if (options.apply !== true) {
-        return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: false };
+        return {
+            role: options.role,
+            requestId: options.requestId,
+            sessionId,
+            path,
+            content,
+            applied: false,
+            ...(options.callerId !== undefined ? { callerId: options.callerId } : {})
+        };
     }
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
@@ -390,7 +398,15 @@ export async function createRequestArtifact(options) {
             await writeFile(initiatedPath, '', 'utf8');
         }
     }
-    return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: true };
+    return {
+        role: options.role,
+        requestId: options.requestId,
+        sessionId,
+        path,
+        content,
+        applied: true,
+        ...(options.callerId !== undefined ? { callerId: options.callerId } : {})
+    };
 }
 function extractMetadata(markdown) {
     let state = 'unknown';

package/dist/src/services/memory/project-memory-service.d.ts

@@ -142,4 +142,23 @@ export declare function summarizeProjectMemoryBackupResult(result: ProjectMemory
  */
 export declare function ensureMemoryBootstrap(projectRoot: string): boolean;
 export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
+export interface ProjectMemoryShowResult {
+    projectRoot: string;
+    memoryDir: string;
+    name: string;
+    body: string;
+    filePath: string;
+    updatedAt: string | null;
+    kind: ProjectMemoryKind | null;
+    title: string;
+    /** Whether the on-disk body bytes are returned (true) or a compact form (false). */
+    pretty: boolean;
+}
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export declare function readProjectMemoryBody(projectRoot: string, name: string): ProjectMemoryShowResult | null;
 export {};