peaks-loop 4.0.54 → 4.1.0

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

@@ -1,14 +1,14 @@
 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 { 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 { codegraphRefreshNotice, refreshCodegraphAfterSlice } from '../../services/codegraph/codegraph-autorefresh.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { isUnsafePathInput } from '../../shared/path-safety.js';
 /**
@@ -21,12 +21,14 @@ export function buildRequestListSummary(items) {
     const view = {
         view: 'summary',
         count: items.length,
-        items: boundedNames(items.map((i) => `${i.role}/${i.requestId} (${i.state})`)),
+        items: boundedNames(items.map((i) => `${i.role}/${i.requestId} (${i.state})`))
     };
     return fitSummaryToBytes(view);
 }
 export function registerRequestCommands(program, io) {
-    const request = program.command('request').description('Manage per-request Peaks role artifacts (PRD / UI / RD / QA)');
+    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)')
@@ -49,7 +51,10 @@ export function registerRequestCommands(program, io) {
             // 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);
+                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;
             }
@@ -106,7 +111,9 @@ export function registerRequestCommands(program, io) {
         .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 };
+            const listOptions = {
+                projectRoot: options.project
+            };
             if (options.sessionId !== undefined) {
                 listOptions.sessionId = options.sessionId;
             }
@@ -116,9 +123,7 @@ export function registerRequestCommands(program, io) {
             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 };
+            const data = options.summary === true ? buildRequestListSummary(items) : { count: items.length, items };
             printResult(io, ok('request.list', data), options.json);
         }
         catch (error) {
@@ -152,17 +157,11 @@ export function registerRequestCommands(program, io) {
             }
             // 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 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;
+            const payload = transformed === result ? { ...result, format } : transformed;
             printResult(io, ok('request.show', payload), options.json);
         }
         catch (error) {
@@ -204,8 +203,11 @@ export function registerRequestCommands(program, io) {
                     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);
+            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;
             }
@@ -215,7 +217,9 @@ export function registerRequestCommands(program, io) {
                 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);
+                        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;
                     }
@@ -270,7 +274,10 @@ export function registerRequestCommands(program, io) {
                 }
                 const existing = await showForType(showTypeOptions);
                 if (existing !== null) {
-                    transitionOptions.typeSanityCheck = { projectRoot: options.project, declaredType: existing.requestType };
+                    transitionOptions.typeSanityCheck = {
+                        projectRoot: options.project,
+                        declaredType: existing.requestType
+                    };
                 }
             }
             const result = await transitionRequestArtifact(transitionOptions);
@@ -307,9 +314,7 @@ export function registerRequestCommands(program, io) {
                         sessionId: result.sessionId,
                         transitionKey: `${role}:${newState}`
                     });
-                    preCompact = hook.triggered
-                        ? ok('request.transition.preCompact', hook)
-                        : null;
+                    preCompact = hook.triggered ? ok('request.transition.preCompact', hook) : null;
                 }
                 catch {
                     // The hook is best-effort; never block the transition.
@@ -320,7 +325,11 @@ export function registerRequestCommands(program, io) {
                 }
                 catch {
                     // The refresh is best-effort; never block the transition.
-                    codegraphRefresh = { refreshed: false, reason: 'unavailable', note: 'auto codegraph refresh failed after 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
@@ -371,7 +380,9 @@ export function registerRequestCommands(program, io) {
             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
+                        `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)`
                     ]
@@ -414,7 +425,11 @@ export function registerRequestCommands(program, io) {
                 return;
             }
             if (error instanceof TypeSanityViolationError) {
-                printResult(io, fail('request.transition', error.code, error.message, { declaredType: error.declaredType, suggestedTypes: error.suggestedTypes, rationale: error.rationale }, [
+                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);
@@ -422,8 +437,8 @@ export function registerRequestCommands(program, io) {
                 return;
             }
             if (error instanceof FileSizeViolationError) {
-                printResult(io, fail('request.transition', error.code, error.message, { violations: error.violations, threshold: error.threshold }, [
-                    ...error.violations.map((v) => `Split ${v.file} (${v.lines} lines) into smaller modules (< ${error.threshold} lines)`),
+                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;
@@ -482,7 +497,9 @@ export function registerRequestCommands(program, io) {
         .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 max = options.maxCycles !== undefined && /^\d+$/.test(options.maxCycles)
+                ? Number(options.maxCycles)
+                : 3;
             const statusOptions = {
                 projectRoot: options.project,
                 requestId,

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

@@ -4,7 +4,7 @@
  * 800-line cap. Behaviour-preserving verbatim move.
  */
 import { InvalidArgumentError } from 'commander';
-import { allowedStatesForRole, isRequestType, VALID_REQUEST_TYPES, } from '../../services/artifacts/request-artifact-service.js';
+import { allowedStatesForRole, isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/request-artifact-service.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 /**
  * Per-artifact default format. Only PRD and tech-doc are user-review

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

@@ -1,12 +1,19 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export interface RetrospectiveSearchCommandOptions {
-    query: string;
-    type?: string;
-    outcome?: string;
-    limit?: number;
-    project?: string;
-    json?: boolean;
-}
-export declare function runRetrospectiveSearch(io: ProgramIO, options: RetrospectiveSearchCommandOptions): void;
+/**
+ * `peaks retrospective` command group.
+ *
+ * C wave 4 split (leaf `c4w1-cli-c`): the index / show / search
+ * subcommands moved VERBATIM into `retrospective-index-command.ts`,
+ * `retrospective-show-command.ts` and `retrospective-search-command.ts`,
+ * and their repeated project-root resolution into
+ * `retrospective-project-root.ts`. This file keeps the group registration
+ * plus the public surface — `registerRetrospectiveCommands` (the name
+ * `_register.ts` imports), `runRetrospectiveSearch` and
+ * `RetrospectiveSearchCommandOptions` are all still importable from this
+ * path. Subcommands register in the same order as before (index, show,
+ * search), so `--help` output is unchanged.
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export { runRetrospectiveSearch } from './retrospective-search-command.js';
+export type { RetrospectiveSearchCommandOptions } from './retrospective-search-command.js';
 export declare function registerRetrospectiveCommands(program: Command, io: ProgramIO): void;

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

@@ -1,175 +1,26 @@
-import { join } from 'node:path';
-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 { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
-import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-const VALID_RETRO_TYPES = ['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore'];
-const VALID_RETRO_OUTCOMES = ['shipped', 'blocked', 'in-flight', 'cancelled'];
-export function runRetrospectiveSearch(io, options) {
-    const projectRoot = options.project !== undefined
-        ? resolveCanonicalProjectRoot(options.project)
-        : (findProjectRoot(process.cwd()) ?? process.cwd());
-    const typeFilter = options.type !== undefined && VALID_RETRO_TYPES.includes(options.type)
-        ? options.type
-        : undefined;
-    const outcomeFilter = options.outcome !== undefined && VALID_RETRO_OUTCOMES.includes(options.outcome)
-        ? options.outcome
-        : undefined;
-    try {
-        const matches = searchRetrospective({
-            query: options.query,
-            projectRoot,
-            ...(typeFilter !== undefined ? { type: typeFilter } : {}),
-            ...(outcomeFilter !== undefined ? { outcome: outcomeFilter } : {}),
-            ...(options.limit !== undefined ? { limit: options.limit } : {}),
-        });
-        printResult(io, ok('retrospective.search', {
-            query: options.query,
-            total: matches.length,
-            matches,
-            warnings: [],
-        }, []), options.json);
-    }
-    catch (error) {
-        const message = getErrorMessage(error);
-        const code = error.code ?? 'RETROSPECTIVE_SEARCH_FAILED';
-        const suggestions = [];
-        if (code === 'INDEX_MISSING') {
-            suggestions.push('Build a retrospective index.json in .peaks/retrospective/');
-        }
-        if (code === 'EMPTY_QUERY') {
-            suggestions.push('Use `peaks retrospective index` to list all entries');
-        }
-        printResult(io, fail('retrospective.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
-        process.exitCode = 1;
-    }
-}
+/**
+ * `peaks retrospective` command group.
+ *
+ * C wave 4 split (leaf `c4w1-cli-c`): the index / show / search
+ * subcommands moved VERBATIM into `retrospective-index-command.ts`,
+ * `retrospective-show-command.ts` and `retrospective-search-command.ts`,
+ * and their repeated project-root resolution into
+ * `retrospective-project-root.ts`. This file keeps the group registration
+ * plus the public surface — `registerRetrospectiveCommands` (the name
+ * `_register.ts` imports), `runRetrospectiveSearch` and
+ * `RetrospectiveSearchCommandOptions` are all still importable from this
+ * path. Subcommands register in the same order as before (index, show,
+ * search), so `--help` output is unchanged.
+ */
+import { registerRetrospectiveIndexCommand } from './retrospective-index-command.js';
+import { registerRetrospectiveSearchCommand } from './retrospective-search-command.js';
+import { registerRetrospectiveShowCommand } from './retrospective-show-command.js';
+export { runRetrospectiveSearch } from './retrospective-search-command.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). Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/retrospective/picked.json.')
-        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
-        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (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];
-            let picked = null;
-            let pickedOutputPath = null;
-            let fzfVersion = null;
-            if (options.pick === true) {
-                const outputPath = join(projectRoot, '.peaks', 'retrospective', 'picked.json');
-                const byId = new Map(result.entries.map((e) => [e.id, e]));
-                const pickResult = await pickFromList({
-                    items: result.entries,
-                    formatLine: (e) => `${e.id} | ${e.type} | ${e.title} | ${e.outcome}`,
-                    parseLine: (line) => {
-                        const parts = line.split('|').map((p) => p.trim());
-                        if (parts.length < 1)
-                            return null;
-                        const id = parts[0];
-                        if (id === undefined || id.length === 0)
-                            return null;
-                        return byId.get(id) ?? null;
-                    },
-                    outputPath,
-                    meta: { totalCandidates: result.totalCount, source: result.source },
-                    ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
-                    projectRoot,
-                    multi: true,
-                    prompt: 'retrospective> '
-                });
-                picked = [...pickResult.picked];
-                pickedOutputPath = pickResult.outputPath;
-                fzfVersion = pickResult.fzfVersion;
-            }
-            printResult(io, ok('retrospective.index', {
-                indexPath: result.indexPath,
-                source: result.source,
-                total: result.totalCount,
-                entries: result.entries,
-                ...(options.pick === true ? { picked, pickedOutputPath, fzfVersion } : {})
-            }, warnings), options.json);
-        }
-        catch (error) {
-            const msg = getErrorMessage(error);
-            const isFzfError = /brew install fzf|apt-get install fzf|older than required/.test(msg);
-            if (isFzfError)
-                process.exitCode = 127;
-            else
-                process.exitCode = 1;
-            printResult(io, fail('retrospective.index', isFzfError ? 'FZF_UNAVAILABLE' : 'RETROSPECTIVE_INDEX_FAILED', msg, { projectRoot }, isFzfError
-                ? ['Install fzf (brew install fzf or apt-get install fzf) or run without --pick to list entries as JSON.']
-                : ['Check the project path and .peaks/retrospective/index.json']), options.json);
-        }
-    });
-    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('Build a retrospective index.json in .peaks/retrospective/');
-                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('Restore the missing artifact at the path listed under missingArtifacts');
-                }
-                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('search <query>')
-        .description('Fuzzy-search the retrospective index (deterministic, local, zero-token). Default --limit 6.')
-        .option('--type <type>', `filter by retrospective type (one of: ${VALID_RETRO_TYPES.join(', ')})`)
-        .option('--outcome <outcome>', `filter by retrospective outcome (one of: ${VALID_RETRO_OUTCOMES.join(', ')})`)
-        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
-        runRetrospectiveSearch(io, {
-            query,
-            ...(options.type !== undefined ? { type: options.type } : {}),
-            ...(options.outcome !== undefined ? { outcome: options.outcome } : {}),
-            ...(options.limit !== undefined ? { limit: options.limit } : {}),
-            ...(options.project !== undefined ? { project: options.project } : {}),
-            ...(options.json !== undefined ? { json: options.json } : {}),
-        });
-    });
+    const retrospective = program
+        .command('retrospective')
+        .description('Read the peaks retrospective index (R3: index.json, not the legacy <id>/ MD tree)');
+    registerRetrospectiveIndexCommand(retrospective, io);
+    registerRetrospectiveShowCommand(retrospective, io);
+    registerRetrospectiveSearchCommand(retrospective, io);
 }

package/dist/cli/commands/retrospective-index-command.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `peaks retrospective index` — the index command (list + optional fzf
+ * multi-select), hoisted out of `retrospective-commands.ts` so that file
+ * clears the 300 raw-line cap.
+ *
+ * Identical control flow: same project-root resolution, same
+ * `loadRetrospectiveIndex` call, same warning normalization, the same
+ * `options.pick === true` gate in the same position, the same envelope
+ * field order, the same exit codes (127 for an fzf problem, 1 otherwise),
+ * the same two suggestion texts, and the same single catch — which moved
+ * WITH its handler and still reports the failure (no swallow, so the
+ * silent-warning counters are untouched). The fzf selection block became
+ * one helper and the failure envelope another, so no function here is
+ * over `max-lines-per-function` or `complexity`; nothing else was
+ * rewritten.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RetrospectiveIndexCommandOptions {
+    pick?: boolean;
+    fzfBin?: string;
+    project?: string;
+    json?: boolean;
+}
+export declare function runRetrospectiveIndexAction(io: ProgramIO, options: RetrospectiveIndexCommandOptions): Promise<void>;
+export declare function registerRetrospectiveIndexCommand(retrospective: Command, io: ProgramIO): void;

package/dist/cli/commands/retrospective-index-command.js

@@ -0,0 +1,99 @@
+/**
+ * `peaks retrospective index` — the index command (list + optional fzf
+ * multi-select), hoisted out of `retrospective-commands.ts` so that file
+ * clears the 300 raw-line cap.
+ *
+ * Identical control flow: same project-root resolution, same
+ * `loadRetrospectiveIndex` call, same warning normalization, the same
+ * `options.pick === true` gate in the same position, the same envelope
+ * field order, the same exit codes (127 for an fzf problem, 1 otherwise),
+ * the same two suggestion texts, and the same single catch — which moved
+ * WITH its handler and still reports the failure (no swallow, so the
+ * silent-warning counters are untouched). The fzf selection block became
+ * one helper and the failure envelope another, so no function here is
+ * over `max-lines-per-function` or `complexity`; nothing else was
+ * rewritten.
+ */
+import { join } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
+import { loadRetrospectiveIndex } from '../../services/retrospective/retrospective-index.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { resolveRetrospectiveProjectRoot } from './retrospective-project-root.js';
+async function pickRetrospectiveEntries(projectRoot, result, fzfBin) {
+    const outputPath = join(projectRoot, '.peaks', 'retrospective', 'picked.json');
+    const byId = new Map(result.entries.map((e) => [e.id, e]));
+    const pickResult = await pickFromList({
+        items: result.entries,
+        formatLine: (e) => `${e.id} | ${e.type} | ${e.title} | ${e.outcome}`,
+        parseLine: (line) => {
+            const parts = line.split('|').map((p) => p.trim());
+            if (parts.length < 1)
+                return null;
+            const id = parts[0];
+            if (id === undefined || id.length === 0)
+                return null;
+            return byId.get(id) ?? null;
+        },
+        outputPath,
+        meta: { totalCandidates: result.totalCount, source: result.source },
+        ...(fzfBin !== undefined ? { fzfBin } : {}),
+        projectRoot,
+        multi: true,
+        prompt: 'retrospective> '
+    });
+    return {
+        picked: [...pickResult.picked],
+        pickedOutputPath: pickResult.outputPath,
+        fzfVersion: pickResult.fzfVersion
+    };
+}
+function printIndexFailure(io, options, projectRoot, error) {
+    const msg = getErrorMessage(error);
+    const isFzfError = /brew install fzf|apt-get install fzf|older than required/.test(msg);
+    if (isFzfError)
+        process.exitCode = 127;
+    else
+        process.exitCode = 1;
+    printResult(io, fail('retrospective.index', isFzfError ? 'FZF_UNAVAILABLE' : 'RETROSPECTIVE_INDEX_FAILED', msg, { projectRoot }, isFzfError
+        ? [
+            'Install fzf (brew install fzf or apt-get install fzf) or run without --pick to list entries as JSON.'
+        ]
+        : ['Check the project path and .peaks/retrospective/index.json']), options.json);
+}
+export async function runRetrospectiveIndexAction(io, options) {
+    const projectRoot = resolveRetrospectiveProjectRoot(options.project);
+    try {
+        const result = loadRetrospectiveIndex(projectRoot);
+        const warnings = result.warning === null ? [] : [result.warning];
+        let picked = null;
+        let pickedOutputPath = null;
+        let fzfVersion = null;
+        if (options.pick === true) {
+            const pick = await pickRetrospectiveEntries(projectRoot, result, options.fzfBin);
+            picked = pick.picked;
+            pickedOutputPath = pick.pickedOutputPath;
+            fzfVersion = pick.fzfVersion;
+        }
+        printResult(io, ok('retrospective.index', {
+            indexPath: result.indexPath,
+            source: result.source,
+            total: result.totalCount,
+            entries: result.entries,
+            ...(options.pick === true ? { picked, pickedOutputPath, fzfVersion } : {})
+        }, warnings), options.json);
+    }
+    catch (error) {
+        printIndexFailure(io, options, projectRoot, error);
+    }
+}
+export function registerRetrospectiveIndexCommand(retrospective, io) {
+    addJsonOption(retrospective
+        .command('index')
+        .description('List all retrospective entries from .peaks/retrospective/index.json (R3: replaces the per-workflow MD dirs). Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/retrospective/picked.json.')
+        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
+        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (options) => {
+        await runRetrospectiveIndexAction(io, options);
+    });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Project-root resolution shared by the three `peaks retrospective`
+ * subcommands — hoisted VERBATIM from `retrospective-commands.ts`, where
+ * the same four-line expression was written out three times (search,
+ * index, show). Same branch order, same predicates: an explicit
+ * `--project` is canonicalised, otherwise the discovered project root,
+ * otherwise cwd.
+ */
+export declare function resolveRetrospectiveProjectRoot(project: string | undefined): string;

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

@@ -0,0 +1,15 @@
+/**
+ * Project-root resolution shared by the three `peaks retrospective`
+ * subcommands — hoisted VERBATIM from `retrospective-commands.ts`, where
+ * the same four-line expression was written out three times (search,
+ * index, show). Same branch order, same predicates: an explicit
+ * `--project` is canonicalised, otherwise the discovered project root,
+ * otherwise cwd.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+export function resolveRetrospectiveProjectRoot(project) {
+    return project !== undefined
+        ? resolveCanonicalProjectRoot(project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+}

package/dist/cli/commands/retrospective-search-command.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `peaks retrospective search` — the search command, hoisted out of
+ * `retrospective-commands.ts` so that file clears the 300 raw-line cap.
+ *
+ * Identical control flow: same filter predicates (in the same order), the
+ * same optional-spread into `searchRetrospective`, the same envelope
+ * fields, the same suggestion texts, the same `process.exitCode = 1`, and
+ * the same catch shape (the failure is reported, never swallowed). The
+ * filter checks and the failure envelope were split into single-purpose
+ * helpers so no function here carries a `max-lines-per-function` or
+ * `complexity` finding; nothing else was rewritten.
+ *
+ * `runRetrospectiveSearch` and `RetrospectiveSearchCommandOptions` stay
+ * importable from `retrospective-commands.js` (public surface unchanged).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RetrospectiveSearchCommandOptions {
+    query: string;
+    type?: string;
+    outcome?: string;
+    limit?: number;
+    project?: string;
+    json?: boolean;
+}
+export declare function runRetrospectiveSearch(io: ProgramIO, options: RetrospectiveSearchCommandOptions): void;
+export declare function registerRetrospectiveSearchCommand(retrospective: Command, io: ProgramIO): void;