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

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

@@ -1,70 +0,0 @@
-/**
- * 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/src/services/release/release-state.js

@@ -1,140 +0,0 @@
-/**
- * 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/src/services/retrospective/retrospective-index.d.ts

@@ -1,37 +0,0 @@
-/**
- * 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/src/services/retrospective/retrospective-index.js

@@ -1,110 +0,0 @@
-/**
- * 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/src/services/retrospective/retrospective-search-service.d.ts

@@ -1,55 +0,0 @@
-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/src/services/retrospective/retrospective-search-service.js

@@ -1,107 +0,0 @@
-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/src/services/retrospective/retrospective-show.d.ts

@@ -1,40 +0,0 @@
-/**
- * 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/src/services/retrospective/retrospective-show.js

@@ -1,109 +0,0 @@
-/**
- * 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 };