peaks-cli 1.3.8 → 1.3.9

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

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

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

@@ -5,7 +5,82 @@ import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '..
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from '../../shared/result.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * Per-artifact default format. Only PRD and tech-doc are user-review
+ * surfaces; all other RD/QA/TXT artifacts default to compact. The
+ * `--pretty` / `--compact` flags override uniformly. See tech-doc
+ * §1.3.
+ */
+const DEFAULT_FORMAT_BY_ARTIFACT = {
+    prd: 'pretty',
+    'tech-doc': 'pretty',
+    'code-review': 'compact',
+    'security-review': 'compact',
+    'perf-baseline': 'compact',
+    'bug-analysis': 'compact',
+    'test-cases': 'compact',
+    'test-reports': 'compact',
+    'security-findings': 'compact',
+    'performance-findings': 'compact',
+    handoff: 'compact'
+};
+function resolveDefaultFormat(artifactName) {
+    return DEFAULT_FORMAT_BY_ARTIFACT[artifactName] ?? 'compact';
+}
+function applyPerArtifactFormat(envelope, override) {
+    if (override === null || envelope === null || typeof envelope !== 'object')
+        return envelope;
+    // The service returns `{ id, sessionId, role, body, ... }` for a
+    // single-artifact show. The per-artifact `body` field is the only
+    // thing that changes; we attach a `format` field to surface the
+    // choice to the caller. Slice 023 (R3) AC6 / AC7.
+    const obj = envelope;
+    if (typeof obj.body === 'string') {
+        return {
+            ...obj,
+            body: override === 'compact' ? formatMdCompact(obj.body) : obj.body,
+            format: override
+        };
+    }
+    return envelope;
+}
+/**
+ * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
+ * The service returns the path of the artifact in `path`; the role +
+ * filename stem gives us the artifact name. Falls back to the role
+ * itself when no `path` field is present.
+ */
+function inferArtifactName(envelope, role) {
+    if (envelope === null || typeof envelope !== 'object')
+        return role;
+    const obj = envelope;
+    const pathField = typeof obj.path === 'string' ? obj.path : '';
+    // Path looks like `.peaks/_runtime/<sid>/<role>/requests/<file>.md`.
+    // The role is the second-to-last directory; the file stem is the
+    // last segment. For RD role, the artifact is one of {code-review,
+    // security-review, perf-baseline, bug-analysis, tech-doc}; the file
+    // stem usually carries the artifact name (e.g. `tech-doc.md`,
+    // `code-review-002.md`). We strip the trailing `-<digits>` suffix
+    // when present.
+    const stem = pathField.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? '';
+    if (stem.length > 0) {
+        // Try the stem verbatim first.
+        if (DEFAULT_FORMAT_BY_ARTIFACT[stem] !== undefined)
+            return stem;
+        // Strip a trailing -<digits> (e.g. code-review-002 -> code-review).
+        const trimmed = stem.replace(/-\d+$/, '');
+        if (DEFAULT_FORMAT_BY_ARTIFACT[trimmed] !== undefined)
+            return trimmed;
+        // Last-ditch: match by prefix.
+        for (const key of Object.keys(DEFAULT_FORMAT_BY_ARTIFACT)) {
+            if (stem.startsWith(key))
+                return key;
+        }
+    }
+    return role;
+}
 const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
 function parseRole(value) {
     if (!VALID_ROLES.includes(value)) {
@@ -119,11 +194,13 @@ export function registerRequestCommands(program, io) {
     });
     addJsonOption(request
         .command('show')
-        .description('Show a single per-request artifact, optionally scoped to a session')
+        .description('Show a single per-request artifact, optionally scoped to a session. R3: default body format is per-artifact (PRD/tech-doc pretty; everything else compact); pass --pretty or --compact to override uniformly.')
         .argument('<request-id>', 'request id, e.g. 2026-05-23-add-foo')
         .requiredOption('--role <role>', `target role (${VALID_ROLES.join(' | ')})`, parseRole)
         .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <session>', 'restrict to a specific session id')).action(async (requestId, options) => {
+        .option('--session-id <session>', 'restrict to a specific session id')
+        .option('--pretty', 'force the body to render pretty (overrides the per-artifact default)')
+        .option('--compact', 'force the body to render compact (overrides the per-artifact default)')).action(async (requestId, options) => {
         try {
             const showOptions = {
                 projectRoot: options.project,
@@ -139,7 +216,20 @@ export function registerRequestCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('request.show', result), options.json);
+            // R3: pick the per-artifact default format and apply the override
+            // if either flag is set. Last-flag-wins if both are passed.
+            const override = options.compact === true
+                ? 'compact'
+                : options.pretty === true
+                    ? 'pretty'
+                    : null;
+            const artifactName = inferArtifactName(result, options.role);
+            const format = override ?? resolveDefaultFormat(artifactName);
+            const transformed = applyPerArtifactFormat(result, override ?? format);
+            const payload = transformed === result
+                ? { ...result, format }
+                : transformed;
+            printResult(io, ok('request.show', payload), options.json);
         }
         catch (error) {
             printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);

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

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

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

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

package/dist/src/cli/program.js

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

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

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

package/dist/src/services/memory/project-memory-service.js

@@ -779,3 +779,36 @@ export function readProjectMemories(projectRoot) {
         memories
     };
 }
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export function readProjectMemoryBody(projectRoot, name) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        if (basename(filePath, '.md') !== name)
+            continue;
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed === null)
+            continue;
+        const updatedAt = readMemoryFileMtime(filePath);
+        return {
+            projectRoot: normalizedRoot,
+            memoryDir,
+            name: parsed.name,
+            body: parsed.body,
+            filePath,
+            updatedAt,
+            kind: parsed.kind,
+            title: parsed.title,
+            pretty: true
+        };
+    }
+    return null;
+}

package/dist/src/services/retrospective/migrate-from-md.d.ts

@@ -0,0 +1,37 @@
+/**
+ * migrate-from-md — one-time migration from `.peaks/retrospective/<id>/*.md`
+ * per-workflow MD dirs to a single `.peaks/retrospective/index.json` plus a
+ * `.peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz` archive.
+ *
+ * Slice 023 (R3) G9. Idempotent: re-run is a no-op when `index.json` has
+ * 88 entries with matching `updatedAt`.
+ *
+ * The legacy MDs in this repo use a *bullet-list* metadata format (no YAML
+ * frontmatter). The fields we need are extracted from the leading bullet
+ * block: `session:`, `rid:`, `type:`, `sliceId:`, plus the first `# Title`
+ * heading.
+ */
+export interface MigrateOptions {
+    projectRoot: string;
+    apply?: boolean;
+    includeFailed?: boolean;
+    expectedEntries?: number;
+}
+export interface MigrateResult {
+    apply: boolean;
+    projectRoot: string;
+    indexPath: string;
+    archivePath: string | null;
+    sourceDir: string;
+    totalLegacyDirs: number;
+    totalLegacyMds: number;
+    parsedEntries: number;
+    failedEntries: Array<{
+        id: string;
+        reason: string;
+    }>;
+    archiveVerified: boolean;
+    status: 'applied' | 'no-op' | 'partial' | 'failed';
+    warnings: string[];
+}
+export declare function migrateRetrospectiveFromMd(options: MigrateOptions): MigrateResult;