peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/release/version-precheck-service.js

@@ -0,0 +1,257 @@
+/**
+ * rid-010 — peaks release precheck (Phase 4 slice 1).
+ *
+ * Module path: src/services/release/version-precheck-service.ts
+ * Mirror of publish.yml gate-cli-version step §(A). The §(B) tarball-content gate
+ * (Layer 5 of the 5-layer root cause) stays CI-only — AC-7 grep test pins
+ * publish.yml so §(B) cannot drift silently.
+ *
+ * 4-layer version precheck mirroring publish.yml gate-cli-version step. Designed
+ * to run BEFORE `peaks release canary` so developers catch CLI_VERSION lag /
+ * tag collision / changeset staged / workspace drift without waiting for CI.
+ *
+ * Mirrors the §(A) on-disk gate from publish.yml. The §(B) tarball-content gate
+ * (Layer 5 of the 5-layer root cause) stays CI-only — AC-7 grep test pins
+ * publish.yml so §(B) cannot drift silently.
+ *
+ * Design contract:
+ *   - Pure functions. NO `process.exitCode` mutation here (cli-helpers owns it).
+ *   - All I/O parameterized via `projectRoot`.
+ *   - Layer A and B are blockers by default; C and D are warnings (--strict
+ *     upgrades them to blockers; hotfix path uses default warning).
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function upgrade(result, strict) {
+    if (strict === true && result.status === 'warning') {
+        return {
+            ...result,
+            status: 'blocker',
+            remediation: `${result.remediation} (strict mode: warning promoted to blocker)`
+        };
+    }
+    return result;
+}
+function readRootVersion(projectRoot) {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+    if (typeof pkg.version !== 'string' || !SEMVER_RE.test(pkg.version)) {
+        throw new Error(`invalid root package.json#version: ${JSON.stringify(pkg.version)}`);
+    }
+    return pkg.version;
+}
+function rollup(layers, strict) {
+    const statuses = Object.values(layers).map((l) => l.status);
+    if (statuses.includes('blocker')) {
+        return { ok: false, overall: 'blocker' };
+    }
+    if (statuses.includes('warning')) {
+        return { ok: true, overall: 'warning' };
+    }
+    return { ok: true, overall: 'ok' };
+}
+// ---------------------------------------------------------------------------
+// Layer A — rootVsShared (mirrors publish.yml §(A) on-disk gate only)
+// ---------------------------------------------------------------------------
+export function runRootVsShared(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const sharedDist = join(opts.projectRoot, 'packages', 'peaks-loop-shared', 'dist', 'version.js');
+    let sharedVersion = null;
+    let distExists = false;
+    try {
+        const raw = readFileSync(sharedDist, 'utf8');
+        const match = raw.match(/CLI_VERSION\s*=\s*"([^"]+)"/);
+        if (match && match[1] !== undefined) {
+            sharedVersion = match[1];
+        }
+        distExists = true;
+    }
+    catch {
+        distExists = false;
+    }
+    if (!distExists) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared/dist/version.js is missing at ${sharedDist}`,
+            remediation: 'run `pnpm --filter peaks-loop-shared build` to regenerate dist/version.js; ' +
+                'then re-run `peaks release precheck`',
+            observed: { rootVersion, sharedVersion: null }
+        };
+    }
+    if (sharedVersion === null) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared/dist/version.js does not contain a parseable CLI_VERSION`,
+            remediation: 'inspect packages/peaks-loop-shared/dist/version.js; ensure CLI_VERSION = "<semver>" is exported',
+            observed: { rootVersion, sharedVersion: null }
+        };
+    }
+    if (sharedVersion !== rootVersion) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop root version (${rootVersion}) does not match peaks-loop-shared/dist/version.js CLI_VERSION (${sharedVersion})`,
+            remediation: 'bump packages/peaks-loop-shared/package.json#version to match root package.json#version, ' +
+                'commit peaks-loop-shared@' +
+                rootVersion +
+                ', then re-run `peaks release precheck`',
+            observed: { rootVersion, sharedVersion }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `peaks-loop root version matches peaks-loop-shared/dist/version.js CLI_VERSION`,
+        remediation: '',
+        observed: { rootVersion, sharedVersion }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer B — tagCollision (CLI-only; not in publish.yml today)
+// ---------------------------------------------------------------------------
+export function runTagCollision(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const tagName = `v${rootVersion}`;
+    // Windows shell wrapping convention: 5 prior occurrences in tests/unit/release/.
+    const res = spawnSync('git', ['-C', opts.projectRoot, 'tag', '--list', tagName], {
+        shell: process.platform === 'win32',
+        encoding: 'utf8',
+        timeout: 5_000
+    });
+    if (res.error !== null && res.error !== undefined) {
+        return {
+            status: 'warning',
+            message: `git invocation failed; tag-collision layer skipped (${res.error.message})`,
+            remediation: 'ensure `git` is on PATH (Git Bash ships git at C:\\Program Files\\Git\\bin\\git.exe)',
+            observed: { tagName }
+        };
+    }
+    if (res.status !== 0) {
+        return {
+            status: 'warning',
+            message: `git tag --list exited with code ${res.status}; tag-collision layer skipped`,
+            remediation: 'inspect git configuration; precheck will defer to publish.yml gate for tag collision',
+            observed: { tagName, stderr: res.stderr }
+        };
+    }
+    const tagOutput = (res.stdout ?? '').trim();
+    if (tagOutput.includes(tagName)) {
+        return {
+            status: 'blocker',
+            message: `git tag ${tagName} already exists locally — publishing this version would fail at the registry step`,
+            remediation: `delete the existing tag: \`git tag -d ${tagName}\` (or use \`peaks release hotfix <next-version>\` for an out-of-band release)`,
+            observed: { tagName }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `git tag ${tagName} does not exist; safe to publish`,
+        remediation: '',
+        observed: { tagName }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer C — changesetStaged (mirrors publish.yml gate-changeset step)
+// ---------------------------------------------------------------------------
+export function runChangesetStaged(opts) {
+    const changesetDir = join(opts.projectRoot, '.changeset');
+    let files = [];
+    try {
+        files = readdirSync(changesetDir);
+    }
+    catch {
+        return {
+            status: 'ok',
+            message: '.changeset/ directory is absent — no changeset is staged',
+            remediation: '',
+            observed: { stagedFiles: [] }
+        };
+    }
+    const staged = files.filter((f) => f.endsWith('.md') && f !== 'README.md');
+    if (staged.length === 0) {
+        return {
+            status: 'ok',
+            message: '.changeset/ has no staged *.md files',
+            remediation: '',
+            observed: { stagedFiles: [] }
+        };
+    }
+    return {
+        status: 'warning',
+        message: `.changeset/ has ${staged.length} staged change(s): ${staged.join(', ')}`,
+        remediation: 'publish.yml gate-changeset will BLOCK publish with these staged files. ' +
+            'Either: (a) run `peaks changeset publish` to drain the staged changesets, ' +
+            '(b) move them out of .changeset/, or (c) re-run with --strict to enforce blocker exit here.',
+        observed: { stagedFiles: staged }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer D — workspaceLockstep (CLI-only; not in publish.yml today)
+// ---------------------------------------------------------------------------
+export function runWorkspaceLockstep(opts) {
+    const rootPkgRaw = readFileSync(join(opts.projectRoot, 'package.json'), 'utf8');
+    const rootPkg = JSON.parse(rootPkgRaw);
+    const allDeps = {
+        ...(rootPkg.dependencies ?? {}),
+        ...(rootPkg.devDependencies ?? {})
+    };
+    const sharedDep = allDeps['peaks-loop-shared'];
+    if (sharedDep === undefined) {
+        return {
+            status: 'blocker',
+            message: 'peaks-loop-shared is not declared in root dependencies',
+            remediation: 'add `"peaks-loop-shared": "workspace:*"` to root package.json#dependencies',
+            observed: { sharedDep: null }
+        };
+    }
+    if (sharedDep !== 'workspace:*') {
+        return {
+            status: 'warning',
+            message: `peaks-loop-shared is pinned to "${sharedDep}" instead of "workspace:*"`,
+            remediation: 'restore `"peaks-loop-shared": "workspace:*"` in root package.json to ensure ' +
+                'the local dev link is preserved; published semver-pin regressions cause the CLI_VERSION drift class.',
+            observed: { sharedDep }
+        };
+    }
+    const sharedPkgRaw = readFileSync(join(opts.projectRoot, 'packages', 'peaks-loop-shared', 'package.json'), 'utf8');
+    const sharedPkg = JSON.parse(sharedPkgRaw);
+    const sharedVersion = sharedPkg.version ?? '';
+    if (!SEMVER_RE.test(sharedVersion)) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared package.json#version is not a clean semver: "${sharedVersion}"`,
+            remediation: 'set packages/peaks-loop-shared/package.json#version to a clean semver (e.g. 0.0.18)',
+            observed: { sharedVersion }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `peaks-loop-shared is workspace-linked; shared version "${sharedVersion}" is clean semver`,
+        remediation: '',
+        observed: { sharedDep, sharedVersion }
+    };
+}
+// ---------------------------------------------------------------------------
+// runAllLayers — orchestrator
+// ---------------------------------------------------------------------------
+export function runAllLayers(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const strict = opts.strict === true;
+    const layers = {
+        rootVsShared: upgrade(runRootVsShared(opts), strict),
+        tagCollision: upgrade(runTagCollision(opts), strict),
+        changesetStaged: upgrade(runChangesetStaged(opts), strict),
+        workspaceLockstep: upgrade(runWorkspaceLockstep(opts), strict)
+    };
+    const rolled = rollup(layers, strict);
+    return {
+        ok: rolled.ok,
+        overall: rolled.overall,
+        rootVersion,
+        strict,
+        snapshotAt: new Date().toISOString(),
+        layers
+    };
+}

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