peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/release/release-state.d.ts

@@ -0,0 +1,70 @@
+/**
+ * v2.15.0 follow-up — G15: release / hotfix state machine.
+ *
+ * Tracks a release through the canary → promote → watch → done
+ * pipeline. The actual deployment (k8s rollout, load balancer config,
+ * monitoring integration) is OUT OF SCOPE for this slice — this
+ * ships the state machine + dry-run hooks for the operator.
+ *
+ * Persistence: `.peaks/release-state.json` in the project root.
+ */
+export type ReleaseStage = 'planned' | 'canary-10' | 'canary-50' | 'promoted' | 'watching' | 'done' | 'rolled-back' | 'hotfixed';
+export declare function isValidStageTransition(from: ReleaseStage, to: ReleaseStage): boolean;
+export declare function isReleaseStage(value: string): value is ReleaseStage;
+export interface ReleaseRecord {
+    readonly version: string;
+    readonly currentStage: ReleaseStage;
+    readonly stageHistory: readonly {
+        readonly stage: ReleaseStage;
+        readonly at: string;
+        readonly note?: string;
+    }[];
+    readonly createdAt: string;
+    readonly promotedAt?: string;
+    readonly doneAt?: string;
+}
+export interface ReleaseState {
+    readonly version: 1;
+    /** Active release (the one being canary'd / watched). */
+    readonly active: ReleaseRecord | null;
+    /** History of completed / rolled-back / hotfixed releases. */
+    readonly history: readonly ReleaseRecord[];
+}
+export declare const EMPTY_RELEASE_STATE: ReleaseState;
+export declare function getReleaseStatePath(projectRoot: string): string;
+export declare function readReleaseState(projectRoot: string): ReleaseState;
+export declare function writeReleaseState(projectRoot: string, state: ReleaseState): void;
+/** Plan a new release. If there is an active release, fails. */
+export declare function planRelease(state: ReleaseState, version: string, now?: Date): {
+    state: ReleaseState;
+    record: ReleaseRecord;
+} | {
+    error: string;
+};
+/** Transition the active release to a new stage. */
+export declare function transitionRelease(state: ReleaseState, to: ReleaseStage, note?: string, now?: Date): {
+    state: ReleaseState;
+} | {
+    error: string;
+};
+/** Roll back the active release and move it to history. */
+export declare function rollbackRelease(state: ReleaseState, note?: string, now?: Date): {
+    state: ReleaseState;
+    record: ReleaseRecord;
+} | {
+    error: string;
+};
+/** Hotfix: create a new active release on a hotfix version. */
+export declare function hotfixRelease(state: ReleaseState, hotfixVersion: string, note?: string, now?: Date): {
+    state: ReleaseState;
+    record: ReleaseRecord;
+} | {
+    error: string;
+};
+/** Compute the watch window. */
+export declare function watchWindow(record: ReleaseRecord, now?: Date): {
+    elapsedMs: number;
+    remainingMs: number;
+    windowMs: number;
+    percentComplete: number;
+};

package/dist/services/release/release-state.js

@@ -0,0 +1,140 @@
+/**
+ * v2.15.0 follow-up — G15: release / hotfix state machine.
+ *
+ * Tracks a release through the canary → promote → watch → done
+ * pipeline. The actual deployment (k8s rollout, load balancer config,
+ * monitoring integration) is OUT OF SCOPE for this slice — this
+ * ships the state machine + dry-run hooks for the operator.
+ *
+ * Persistence: `.peaks/release-state.json` in the project root.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** Valid stage transitions. */
+const VALID_TRANSITIONS = {
+    'planned': ['canary-10', 'rolled-back'],
+    'canary-10': ['canary-50', 'rolled-back'],
+    'canary-50': ['promoted', 'rolled-back'],
+    'promoted': ['watching', 'rolled-back'],
+    'watching': ['done', 'rolled-back', 'hotfixed'],
+    'done': [],
+    'rolled-back': ['hotfixed', 'planned'],
+    'hotfixed': ['watching', 'rolled-back']
+};
+export function isValidStageTransition(from, to) {
+    return VALID_TRANSITIONS[from].includes(to);
+}
+export function isReleaseStage(value) {
+    return Object.prototype.hasOwnProperty.call(VALID_TRANSITIONS, value);
+}
+export const EMPTY_RELEASE_STATE = { version: 1, active: null, history: [] };
+const STATE_FILE = '.peaks/release-state.json';
+export function getReleaseStatePath(projectRoot) {
+    return resolve(projectRoot, STATE_FILE);
+}
+export function readReleaseState(projectRoot) {
+    const path = getReleaseStatePath(projectRoot);
+    if (!existsSync(path))
+        return EMPTY_RELEASE_STATE;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return EMPTY_RELEASE_STATE;
+        return {
+            version: 1,
+            active: parsed.active ?? null,
+            history: Array.isArray(parsed.history) ? parsed.history : []
+        };
+    }
+    catch {
+        return EMPTY_RELEASE_STATE;
+    }
+}
+export function writeReleaseState(projectRoot, state) {
+    const path = getReleaseStatePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+}
+/** Plan a new release. If there is an active release, fails. */
+export function planRelease(state, version, now = new Date()) {
+    if (state.active !== null) {
+        return { error: `an active release is already in stage "${state.active.currentStage}"` };
+    }
+    const record = {
+        version,
+        currentStage: 'planned',
+        stageHistory: [{ stage: 'planned', at: now.toISOString() }],
+        createdAt: now.toISOString()
+    };
+    return { state: { ...state, active: record }, record };
+}
+/** Transition the active release to a new stage. */
+export function transitionRelease(state, to, note, now = new Date()) {
+    if (state.active === null)
+        return { error: 'no active release' };
+    const from = state.active.currentStage;
+    if (!isValidStageTransition(from, to)) {
+        return { error: `invalid transition: ${from} → ${to} (allowed from ${from}: ${VALID_TRANSITIONS[from].join(', ') || 'none'})` };
+    }
+    const stageHistory = [...state.active.stageHistory, { stage: to, at: now.toISOString(), ...(note !== undefined ? { note } : {}) }];
+    const promoted = to === 'promoted'
+        ? { ...state.active, currentStage: to, stageHistory, promotedAt: now.toISOString() }
+        : { ...state.active, currentStage: to, stageHistory };
+    const done = to === 'done'
+        ? { ...promoted, doneAt: now.toISOString() }
+        : promoted;
+    return { state: { ...state, active: done } };
+}
+/** Roll back the active release and move it to history. */
+export function rollbackRelease(state, note, now = new Date()) {
+    if (state.active === null)
+        return { error: 'no active release' };
+    const from = state.active.currentStage;
+    if (!isValidStageTransition(from, 'rolled-back')) {
+        return { error: `cannot rollback from ${from}` };
+    }
+    const newEntry = { stage: 'rolled-back', at: now.toISOString(), ...(note !== undefined ? { note } : {}) };
+    const stageHistory = [...state.active.stageHistory, newEntry];
+    const record = { ...state.active, currentStage: 'rolled-back', stageHistory };
+    return { state: { version: 1, active: null, history: [...state.history, record] }, record };
+}
+/** Hotfix: create a new active release on a hotfix version. */
+export function hotfixRelease(state, hotfixVersion, note, now = new Date()) {
+    // If there's an active release, first roll it back (forced).
+    let currentState = state;
+    let priorRecord = null;
+    if (state.active !== null) {
+        const rb = rollbackRelease(state, 'auto-rollback for hotfix', now);
+        if ('record' in rb) {
+            currentState = rb.state;
+            priorRecord = rb.record;
+        }
+    }
+    // Plan the hotfix release directly into 'canary-10' (skip 'planned').
+    const record = {
+        version: hotfixVersion,
+        currentStage: 'canary-10',
+        stageHistory: [
+            { stage: 'canary-10', at: now.toISOString(), ...(note !== undefined ? { note } : {}) }
+        ],
+        createdAt: now.toISOString()
+    };
+    return { state: { ...currentState, active: record }, record, ...(priorRecord !== null ? { rolledBack: priorRecord } : {}) };
+}
+/** Compute the watch window. */
+export function watchWindow(record, now = new Date()) {
+    const WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
+    if (record.promotedAt === undefined) {
+        return { elapsedMs: 0, remainingMs: WINDOW_MS, windowMs: WINDOW_MS, percentComplete: 0 };
+    }
+    const start = new Date(record.promotedAt).getTime();
+    const elapsed = Math.max(0, now.getTime() - start);
+    const remaining = Math.max(0, WINDOW_MS - elapsed);
+    return {
+        elapsedMs: elapsed,
+        remainingMs: remaining,
+        windowMs: WINDOW_MS,
+        percentComplete: Math.min(1, elapsed / WINDOW_MS)
+    };
+}

package/dist/services/retrospective/retrospective-index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * retrospective-index — load `.peaks/retrospective/index.json`, parse to
+ * `RetrospectiveEntry[]`, return the index envelope.
+ *
+ * Slice 023 (R3). Pure read on the hot path: a single `fs.readFile` of
+ * the index, no MD-tree fallback. The migration script (G9) is the only
+ * writer; this loader is read-only.
+ */
+export type RetrospectiveType = 'refactor' | 'feature' | 'bugfix' | 'config' | 'docs' | 'chore';
+export type RetrospectiveOutcome = 'shipped' | 'blocked' | 'in-flight' | 'cancelled';
+export interface RetrospectiveEntry {
+    id: string;
+    sessionId: string;
+    sliceId?: string;
+    type: RetrospectiveType;
+    title: string;
+    summary: string;
+    outcome: RetrospectiveOutcome;
+    keyDecisions: string[];
+    lessonsLearned: number;
+    artifactPaths: string[];
+    updatedAt: string;
+}
+export interface RetrospectiveIndex {
+    version: 1;
+    updatedAt: string;
+    entries: RetrospectiveEntry[];
+}
+export interface RetrospectiveIndexResult {
+    projectRoot: string;
+    indexPath: string;
+    entries: RetrospectiveEntry[];
+    totalCount: number;
+    source: 'index.json' | null;
+    warning: string | null;
+}
+export declare function loadRetrospectiveIndex(projectRoot: string): RetrospectiveIndexResult;

package/dist/services/retrospective/retrospective-index.js

@@ -0,0 +1,110 @@
+/**
+ * retrospective-index — load `.peaks/retrospective/index.json`, parse to
+ * `RetrospectiveEntry[]`, return the index envelope.
+ *
+ * Slice 023 (R3). Pure read on the hot path: a single `fs.readFile` of
+ * the index, no MD-tree fallback. The migration script (G9) is the only
+ * writer; this loader is read-only.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const VALID_TYPES = new Set(['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore']);
+const VALID_OUTCOMES = new Set(['shipped', 'blocked', 'in-flight', 'cancelled']);
+export function loadRetrospectiveIndex(projectRoot) {
+    const resolvedRoot = resolve(projectRoot);
+    const indexPath = join(resolvedRoot, '.peaks', 'retrospective', 'index.json');
+    if (!existsSync(indexPath)) {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: 'no retrospective index; run `peaks retrospective migrate --apply` to build one from legacy MDs'
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(indexPath, 'utf8');
+    }
+    catch {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: `failed to read retrospective index at ${indexPath}`
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            projectRoot: resolvedRoot,
+            indexPath,
+            entries: [],
+            totalCount: 0,
+            source: null,
+            warning: `retrospective index at ${indexPath} is not valid JSON`
+        };
+    }
+    const entries = extractEntries(parsed);
+    const sorted = [...entries].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return {
+        projectRoot: resolvedRoot,
+        indexPath,
+        entries: sorted,
+        totalCount: sorted.length,
+        source: 'index.json',
+        warning: null
+    };
+}
+function extractEntries(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const obj = parsed;
+    if (!Array.isArray(obj.entries))
+        return [];
+    const result = [];
+    for (const candidate of obj.entries) {
+        if (!isRetrospectiveEntry(candidate))
+            continue;
+        result.push(candidate);
+    }
+    return result;
+}
+function isRetrospectiveEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (typeof v.id !== 'string' || v.id.length === 0)
+        return false;
+    if (typeof v.sessionId !== 'string')
+        return false;
+    if (typeof v.type !== 'string' || !VALID_TYPES.has(v.type))
+        return false;
+    if (typeof v.title !== 'string')
+        return false;
+    if (typeof v.summary !== 'string')
+        return false;
+    if (typeof v.outcome !== 'string' || !VALID_OUTCOMES.has(v.outcome))
+        return false;
+    if (!Array.isArray(v.keyDecisions))
+        return false;
+    if (!v.keyDecisions.every((decision) => typeof decision === 'string'))
+        return false;
+    if (typeof v.lessonsLearned !== 'number' || !Number.isInteger(v.lessonsLearned) || v.lessonsLearned < 0)
+        return false;
+    if (!Array.isArray(v.artifactPaths))
+        return false;
+    if (!v.artifactPaths.every((p) => typeof p === 'string'))
+        return false;
+    if (typeof v.updatedAt !== 'string')
+        return false;
+    if (v.sliceId !== undefined && typeof v.sliceId !== 'string')
+        return false;
+    return true;
+}

package/dist/services/retrospective/retrospective-search-service.d.ts

@@ -0,0 +1,55 @@
+export type { RetrospectiveType, RetrospectiveOutcome, RetrospectiveEntry } from './retrospective-index.js';
+import type { RetrospectiveType, RetrospectiveOutcome } from './retrospective-index.js';
+/**
+ * Input to `searchRetrospective`. `projectRoot` defaults to `process.cwd()`.
+ * `query` is required and non-empty. `type` and `outcome` are optional
+ * structured filters that compose with AND.
+ */
+export interface RetrospectiveSearchInput {
+    query: string;
+    projectRoot?: string;
+    limit?: number;
+    type?: RetrospectiveType;
+    outcome?: RetrospectiveOutcome;
+}
+/**
+ * One hit returned by `searchRetrospective`. The `artifactPaths` are
+ * preserved so the LLM can follow up with `peaks retrospective show
+ * <id>` (or read the artifact directly).
+ */
+export interface RetrospectiveSearchResult {
+    id: string;
+    sessionId: string;
+    type: RetrospectiveType;
+    title: string;
+    summary: string;
+    outcome: RetrospectiveOutcome;
+    artifactPaths: string[];
+    score: number;
+    positions: number[];
+}
+/**
+ * Run the generic fuzzy kernel against the on-disk retrospective index.
+ * Searchable text is `title + " " + summary` per spec §Component Details.
+ * `--type` and `--outcome` filters compose with AND before the kernel
+ * runs (cheaper to filter, then fuzzy on a smaller set).
+ */
+export declare function searchRetrospective(input: RetrospectiveSearchInput): RetrospectiveSearchResult[];
+export interface CompressedRetrospectiveResultsEnvelope {
+    readonly mode: 'balanced' | 'aggressive' | 'conservative';
+    readonly originalSize: number;
+    readonly compressedSize: number;
+    readonly compressionRatio: number;
+    readonly compressedText: string;
+    readonly warning: string | null;
+}
+export interface RetrospectiveSearchWithResults {
+    readonly matches: RetrospectiveSearchResult[];
+    readonly compressedResults: CompressedRetrospectiveResultsEnvelope | null;
+}
+export interface RetrospectiveSearchOptions {
+    /** When true, compress joined match text via headroom-ai. Falls back
+     *  silently to the structured `matches` array on failure. */
+    readonly compressResults?: boolean;
+}
+export declare function searchRetrospectiveWithResults(input: RetrospectiveSearchInput, options?: RetrospectiveSearchOptions): Promise<RetrospectiveSearchWithResults>;

package/dist/services/retrospective/retrospective-search-service.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fuzzyMatchWithKey } from '../fuzzy-matching/fuzzy-match-service.js';
+const DEFAULT_LIMIT = 6;
+/**
+ * Read `.peaks/retrospective/index.json` and return the entries.
+ * Throws structured errors with stable codes that the CLI converts
+ * to the peaks envelope.
+ */
+function readIndex(projectRoot) {
+    const resolvedRoot = resolve(projectRoot);
+    const indexPath = join(resolvedRoot, '.peaks', 'retrospective', 'index.json');
+    if (!existsSync(indexPath)) {
+        const err = new Error(`INDEX_MISSING: retrospective index not found at ${indexPath}`);
+        err.code = 'INDEX_MISSING';
+        throw err;
+    }
+    let raw;
+    try {
+        raw = readFileSync(indexPath, 'utf8');
+    }
+    catch (cause) {
+        const err = new Error(`INDEX_INVALID: failed to read retrospective index at ${indexPath}: ${cause.message}`);
+        err.code = 'INDEX_INVALID';
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        const err = new Error(`INDEX_INVALID: malformed retrospective index at ${indexPath}: ${cause.message}`);
+        err.code = 'INDEX_INVALID';
+        throw err;
+    }
+    const index = parsed;
+    return Array.isArray(index.entries) ? index.entries : [];
+}
+/**
+ * Run the generic fuzzy kernel against the on-disk retrospective index.
+ * Searchable text is `title + " " + summary` per spec §Component Details.
+ * `--type` and `--outcome` filters compose with AND before the kernel
+ * runs (cheaper to filter, then fuzzy on a smaller set).
+ */
+export function searchRetrospective(input) {
+    if (input.query === '') {
+        const err = new Error('EMPTY_QUERY: searchRetrospective requires a non-empty query (use `peaks retrospective index` to list all)');
+        err.code = 'EMPTY_QUERY';
+        throw err;
+    }
+    const projectRoot = input.projectRoot ?? process.cwd();
+    const limit = input.limit ?? DEFAULT_LIMIT;
+    let candidates = readIndex(projectRoot);
+    if (input.type !== undefined) {
+        candidates = candidates.filter((e) => e.type === input.type);
+    }
+    if (input.outcome !== undefined) {
+        candidates = candidates.filter((e) => e.outcome === input.outcome);
+    }
+    const matches = fuzzyMatchWithKey(input.query, candidates, { keyFn: (e) => `${e.title} ${e.summary}`, limit, caseSensitive: false });
+    return matches.map((m) => {
+        const entry = m.item;
+        return {
+            id: entry.id,
+            sessionId: entry.sessionId,
+            type: entry.type,
+            title: entry.title,
+            summary: entry.summary,
+            outcome: entry.outcome,
+            artifactPaths: entry.artifactPaths,
+            score: m.score,
+            positions: m.positions,
+        };
+    });
+}
+import { compressPrompt as compressPromptForRetro } from '../context/headroom-client.js';
+import { loadPreferences as loadPreferencesForRetro } from '../preferences/preferences-service.js';
+import { shouldCompressResults as shouldCompressResultsForRetro } from '../context/headroom-prefs.js';
+export async function searchRetrospectiveWithResults(input, options = {}) {
+    const matches = searchRetrospective(input);
+    if (options.compressResults !== true) {
+        return { matches, compressedResults: null };
+    }
+    const projectRoot = input.projectRoot ?? process.cwd();
+    const prefs = loadPreferencesForRetro(projectRoot).headroom;
+    const joinedText = matches.map((m) => `${m.title}: ${m.summary}`).join('\n');
+    const joinedBytes = Buffer.byteLength(joinedText, 'utf8');
+    const decision = shouldCompressResultsForRetro(prefs, joinedBytes, 'retrospectiveSearch');
+    if (!decision.compress) {
+        return { matches, compressedResults: null };
+    }
+    const result = await compressPromptForRetro(joinedText, decision.mode);
+    if (result.warning !== null || result.compressedPrompt === null) {
+        return { matches, compressedResults: null };
+    }
+    return {
+        matches,
+        compressedResults: {
+            mode: decision.mode,
+            originalSize: result.originalSize,
+            compressedSize: result.compressedSize,
+            compressionRatio: result.compressionRatio,
+            compressedText: result.compressedPrompt,
+            warning: result.warning
+        }
+    };
+}

package/dist/services/retrospective/retrospective-show.d.ts

@@ -0,0 +1,40 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { loadRetrospectiveIndex, type RetrospectiveEntry, type RetrospectiveIndexResult } from './retrospective-index.js';
+export type RetrospectiveFormat = 'compact' | 'pretty';
+export interface RetrospectiveShowOptions {
+    projectRoot: string;
+    id: string;
+    format?: RetrospectiveFormat;
+}
+export interface RetrospectiveShowSuccess {
+    ok: true;
+    projectRoot: string;
+    format: RetrospectiveFormat;
+    entry: RetrospectiveEntry;
+    body: string;
+    warnings: string[];
+}
+export interface RetrospectiveShowError {
+    ok: false;
+    code: 'NOT_FOUND' | 'INDEX_MISSING' | 'ARTIFACT_MISSING' | 'INVALID_REQUEST';
+    message: string;
+    hint?: string;
+    projectRoot: string;
+    missingArtifacts?: string[];
+}
+export type RetrospectiveShowResult = RetrospectiveShowSuccess | RetrospectiveShowError;
+export declare function showRetrospective(options: RetrospectiveShowOptions): RetrospectiveShowResult;
+export { loadRetrospectiveIndex };
+export type { RetrospectiveEntry, RetrospectiveIndexResult };

package/dist/services/retrospective/retrospective-show.js

@@ -0,0 +1,109 @@
+/**
+ * retrospective-show — load one retrospective entry by id, synthesize the
+ * body on-demand from `artifactPaths` (concatenate with `---` separator),
+ * apply `formatMdCompact` by default, return the JSON envelope.
+ *
+ * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
+ * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
+ * a referenced artifact is missing on disk, `show` returns a
+ * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.
+ *
+ * Stale policy is **not** applied to retrospective in this slice
+ * (per PRD G7 / R3 scope). The helper exists for a future slice.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { loadRetrospectiveIndex } from './retrospective-index.js';
+export function showRetrospective(options) {
+    if (typeof options.id !== 'string' || options.id.trim().length === 0) {
+        return {
+            ok: false,
+            code: 'INVALID_REQUEST',
+            message: 'retrospective show requires a non-empty <id> argument',
+            projectRoot: resolve(options.projectRoot)
+        };
+    }
+    const resolvedRoot = resolve(options.projectRoot);
+    const index = loadRetrospectiveIndex(resolvedRoot);
+    if (index.source === null) {
+        return {
+            ok: false,
+            code: 'INDEX_MISSING',
+            message: index.warning ?? `retrospective index not found at ${index.indexPath}`,
+            hint: 'run `peaks retrospective migrate --apply` to build the index',
+            projectRoot: resolvedRoot
+        };
+    }
+    const entry = index.entries.find((e) => e.id === options.id);
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: 'NOT_FOUND',
+            message: `retrospective entry not found: ${options.id}`,
+            hint: 'run `peaks retrospective index --json` to see available ids',
+            projectRoot: resolvedRoot
+        };
+    }
+    const format = options.format ?? 'compact';
+    const synthesis = synthesizeBody(entry, resolvedRoot);
+    const body = format === 'pretty' ? synthesis.body : formatMdCompact(synthesis.body);
+    const warnings = synthesis.warnings;
+    return {
+        ok: true,
+        projectRoot: resolvedRoot,
+        format,
+        entry,
+        body,
+        warnings
+    };
+}
+function synthesizeBody(entry, projectRoot) {
+    if (entry.artifactPaths.length === 0) {
+        return { body: renderEntryHeader(entry), warnings: ['entry has no artifactPaths; body is the index summary only'] };
+    }
+    const sections = [];
+    const warnings = [];
+    for (const relativePath of entry.artifactPaths) {
+        const absolutePath = join(projectRoot, relativePath);
+        if (!existsSync(absolutePath)) {
+            warnings.push(`artifact missing on disk: ${relativePath}`);
+            continue;
+        }
+        try {
+            const content = readFileSync(absolutePath, 'utf8');
+            sections.push(`## ${relativePath}\n\n${content}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`failed to read ${relativePath}: ${message}`);
+        }
+    }
+    const header = renderEntryHeader(entry);
+    const body = sections.length === 0
+        ? `${header}\n\n_No artifacts available; only the index summary is shown._`
+        : `${header}\n\n${sections.join('\n\n---\n\n')}`;
+    return { body, warnings };
+}
+function renderEntryHeader(entry) {
+    const lines = [
+        `# ${entry.title}`,
+        '',
+        `- id: ${entry.id}`,
+        `- session: ${entry.sessionId}`,
+        ...(entry.sliceId !== undefined ? [`- slice: ${entry.sliceId}`] : []),
+        `- type: ${entry.type}`,
+        `- outcome: ${entry.outcome}`,
+        `- updatedAt: ${entry.updatedAt}`,
+        `- lessonsLearned: ${entry.lessonsLearned}`,
+        ''
+    ];
+    if (entry.keyDecisions.length > 0) {
+        lines.push('## Key Decisions', '', ...entry.keyDecisions.map((decision) => `- ${decision}`), '');
+    }
+    if (entry.summary.length > 0) {
+        lines.push('## Summary', '', entry.summary, '');
+    }
+    return lines.join('\n');
+}
+export { loadRetrospectiveIndex };