peaks-cli 1.3.8 → 1.3.9

package/dist/src/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/src/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 };

package/dist/src/shared/format-md-compact.d.ts

@@ -0,0 +1,32 @@
+/**
+ * format-md-compact — single source of truth for whitespace / decoration
+ * normalization across every CLI body-output path.
+ *
+ * Slice 023 (R3) — `peaks project memories:show`, `peaks retrospective show`,
+ * and `peaks request show` (per-artifact) all funnel their `body` field through
+ * this helper so the LLM-consumed output is free of blank-line padding,
+ * decorative `---` rules, and frontmatter `description:` field-name repeats
+ * while preserving every semantically meaningful construct (code fences,
+ * setext heading underlines, GFM table syntax, frontmatter, list indentation,
+ * inline emphasis, code spans).
+ *
+ * Pure function: no fs, no I/O. Easy to unit-test (see
+ * `tests/unit/shared/format-md-compact.test.ts`).
+ */
+export interface FormatMdCompactOptions {
+    /** Preserve code-fence (``` ... ```) and frontmatter (--- ... ---) content. Default true. */
+    preserveCodeBlocks?: boolean;
+    /** Preserve setext heading underlines (===, --- under a text line). Default true. */
+    preserveSetextHeadings?: boolean;
+    /** Preserve GFM table syntax (| ... | rows). Default true. */
+    preserveTables?: boolean;
+    /** Collapse 3+ blank lines to 1. Default true. */
+    collapseBlankLines?: boolean;
+    /** Strip trailing whitespace per line. Default true. */
+    stripTrailingWhitespace?: boolean;
+    /** Strip decorative `---` lines (lines surrounded by blanks OR trailing final line). Default true. */
+    stripDecorativeHorizontalRules?: boolean;
+    /** Strip frontmatter `description:` field-name repeat when same value already in body header. Default true. */
+    stripFrontmatterDescriptionRepeat?: boolean;
+}
+export declare function formatMdCompact(input: string, options?: FormatMdCompactOptions): string;

package/dist/src/shared/format-md-compact.js

@@ -0,0 +1,297 @@
+/**
+ * format-md-compact — single source of truth for whitespace / decoration
+ * normalization across every CLI body-output path.
+ *
+ * Slice 023 (R3) — `peaks project memories:show`, `peaks retrospective show`,
+ * and `peaks request show` (per-artifact) all funnel their `body` field through
+ * this helper so the LLM-consumed output is free of blank-line padding,
+ * decorative `---` rules, and frontmatter `description:` field-name repeats
+ * while preserving every semantically meaningful construct (code fences,
+ * setext heading underlines, GFM table syntax, frontmatter, list indentation,
+ * inline emphasis, code spans).
+ *
+ * Pure function: no fs, no I/O. Easy to unit-test (see
+ * `tests/unit/shared/format-md-compact.test.ts`).
+ */
+const FENCE_TRIPLE_BACKTICK = '```';
+const FENCE_TRIPLE_TILDE = '~~~';
+const FENCE_MARKER_RE = /^(```+|~~~+)/;
+const TABLE_ROW_RE = /^\s*\|.*\|\s*$/;
+const TABLE_ALIGN_ROW_RE = /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)+\|?\s*$/;
+const ATX_HEADING_RE = /^#{1,6}\s/;
+const HEADING_LINE_RE = /^\S/;
+const SETEXT_UNDERLINE_RE = /^=+\s*$|^-{2,}\s*$/;
+export function formatMdCompact(input, options = {}) {
+    if (input.length === 0)
+        return input;
+    const opts = {
+        preserveCodeBlocks: options.preserveCodeBlocks ?? true,
+        preserveSetextHeadings: options.preserveSetextHeadings ?? true,
+        preserveTables: options.preserveTables ?? true,
+        collapseBlankLines: options.collapseBlankLines ?? true,
+        stripTrailingWhitespace: options.stripTrailingWhitespace ?? true,
+        stripDecorativeHorizontalRules: options.stripDecorativeHorizontalRules ?? true,
+        stripFrontmatterDescriptionRepeat: options.stripFrontmatterDescriptionRepeat ?? true
+    };
+    // 1. Split frontmatter from body (if any). The YAML block lives between
+    //    the first line `---` and the second line `---`. We carry it through
+    //    unchanged.
+    const fm = splitFrontmatter(input);
+    const body = fm.body;
+    // 2. Walk the body line-by-line, applying the protected-zone rules.
+    const normalizedBody = normalizeBody(body, opts);
+    // 3. Optional frontmatter `description:` repeat strip. The body's
+    //    first ATX heading is compared to the frontmatter `description:`
+    //    value; if the description text repeats the heading, the leading
+    //    paragraph is dropped. Implemented as a one-shot post-pass.
+    const finalBody = opts.stripFrontmatterDescriptionRepeat
+        ? stripDescriptionRepeat(normalizedBody, fm.description)
+        : normalizedBody;
+    // 4. Re-assemble. The frontmatter stays verbatim; the body carries the
+    //    normalized text. Match the original layout: if the input had
+    //    frontmatter, output is `frontmatter + blank + body`; otherwise
+    //    the body is the whole output.
+    if (fm.raw === '') {
+        return finalBody;
+    }
+    return fm.raw + '\n' + finalBody;
+}
+function splitFrontmatter(input) {
+    // Normalize line endings so Windows \r\n doesn't confuse the leading-marker check.
+    const normalized = input.replace(/\r\n/g, '\n');
+    const lines = normalized.split('\n');
+    if (lines[0] !== '---') {
+        return { raw: '', description: null, body: normalized };
+    }
+    let closeIndex = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index] === '---') {
+            closeIndex = index;
+            break;
+        }
+    }
+    if (closeIndex < 0) {
+        return { raw: '', description: null, body: normalized };
+    }
+    const raw = lines.slice(0, closeIndex + 1).join('\n');
+    // Body = everything after the closing `---` (preserving one optional blank line).
+    const bodyLines = lines.slice(closeIndex + 1);
+    while (bodyLines.length > 0 && bodyLines[0] === '') {
+        bodyLines.shift();
+    }
+    const body = bodyLines.join('\n');
+    // Extract the `description:` field. Walk the YAML block; pull the value
+    // as a single-line string. Multi-line (`|`) or folded (`>`) scalars are
+    // joined with a single space — the description is a short summary, the
+    // exact whitespace inside the block scalar is not preserved.
+    const frontmatterLines = lines.slice(1, closeIndex);
+    const description = extractFrontmatterDescription(frontmatterLines);
+    return { raw, description, body };
+}
+function extractFrontmatterDescription(frontmatterLines) {
+    for (let index = 0; index < frontmatterLines.length; index += 1) {
+        const line = frontmatterLines[index] ?? '';
+        const match = line.match(/^description:\s*(.*)$/);
+        if (match === null)
+            continue;
+        const inline = (match[1] ?? '').trim();
+        if (inline === '|' || inline === '>') {
+            const collected = [];
+            for (let inner = index + 1; inner < frontmatterLines.length; inner += 1) {
+                const innerLine = frontmatterLines[inner] ?? '';
+                if (/^[A-Za-z0-9_-]+:/.test(innerLine))
+                    break;
+                collected.push(innerLine.replace(/^\s{2}/, ''));
+            }
+            return collected.join(' ').trim();
+        }
+        // Strip surrounding quotes if the value is a quoted scalar.
+        return inline.replace(/^['"]|['"]$/g, '');
+    }
+    return null;
+}
+function normalizeBody(body, opts) {
+    // Walk line-by-line, tracking the protected-zone flags and emitting a
+    // transformed line stream. We keep three flag bits:
+    //   insideFence:   toggled on ``` / ~~~ lines
+    //   insideFrontmatterYAML: handled by splitFrontmatter; body has none.
+    //   insideTable:   detected by leading-pipe; carried until first non-pipe
+    //                  line.
+    const lines = body.split('\n');
+    // 1. Pre-pass: compute the `setextUnderlined` markers so the decorative
+    //    `---` strip can know when a line is a setext H2 underline (semantic)
+    //    vs a decoration.
+    const setextUnderlined = computeSetextUnderlines(lines);
+    const protection = [];
+    let insideFence = false;
+    let insideTable = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (opts.preserveCodeBlocks && isFenceOpenLine(line) && !isFenceCloseLine(line, insideFence)) {
+            insideFence = !insideFence;
+            protection.push('fence');
+            continue;
+        }
+        if (insideFence) {
+            protection.push('fence');
+            continue;
+        }
+        if (opts.preserveSetextHeadings && setextUnderlined.has(index)) {
+            protection.push('setext');
+            continue;
+        }
+        if (opts.preserveTables && isTableLine(line)) {
+            // Entering / continuing a table — first row that looks like a table
+            // starts the table zone; the alignment row (|---|) is included.
+            insideTable = true;
+            protection.push('table');
+            continue;
+        }
+        if (insideTable && !isTableLine(line) && line.trim() !== '') {
+            insideTable = false;
+        }
+        if (insideTable) {
+            protection.push('table');
+            continue;
+        }
+        protection.push('plain');
+    }
+    // 3. Per-line transforms: strip trailing whitespace outside protected
+    //    zones; strip decorative `---` outside setext / table / fence zones.
+    const out = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const zone = protection[index] ?? 'plain';
+        let transformed = line;
+        if (zone !== 'fence' && opts.stripTrailingWhitespace) {
+            transformed = transformed.replace(/[ \t]+$/u, '');
+        }
+        if (zone !== 'fence' &&
+            zone !== 'setext' &&
+            zone !== 'table' &&
+            opts.stripDecorativeHorizontalRules) {
+            if (isDecorativeHorizontalRule(transformed)) {
+                // Mark for removal: push a sentinel. The blank-line collapse step
+                // will merge surrounding blanks.
+                transformed = '__PEAKS_HR_REMOVED__';
+            }
+        }
+        out.push(transformed);
+    }
+    // 4. Drop the sentinel lines (decorative `---` after classification).
+    let collapsed = out.filter((line) => line !== '__PEAKS_HR_REMOVED__');
+    // 5. Collapse 3+ consecutive blank lines into 1. Two blank lines
+    //    between two non-blank lines are also collapsed to 1 (matches PRD
+    //    R2's "decorative `---` is redundant" rule — the original visual
+    //    gap that surrounded the `---` collapses with it).
+    if (opts.collapseBlankLines) {
+        collapsed = collapseMultiBlanks(collapsed);
+    }
+    return collapsed.join('\n');
+}
+function isFenceOpenLine(line) {
+    return FENCE_MARKER_RE.test(line);
+}
+function isFenceCloseLine(line, insideFence) {
+    // The `isFenceOpenLine` already returned true for this line, so it
+    // starts with ``` or ~~~. A "close" line is one that opens a new fence
+    // of the *same* length. We approximate by treating any opener as a close
+    // when we are currently inside a fence.
+    return insideFence;
+}
+function isTableLine(line) {
+    return TABLE_ROW_RE.test(line) || TABLE_ALIGN_ROW_RE.test(line);
+}
+function computeSetextUnderlines(lines) {
+    // A `===` or `---` line is a setext heading underline ONLY when it sits
+    // directly under a non-blank, non-ATX text line (no blank line between
+    // them). The presence of a blank line between the text and the rule
+    // disqualifies it (a blank-separated `---` is decoration, not setext).
+    const result = new Set();
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (!SETEXT_UNDERLINE_RE.test(line))
+            continue;
+        const prev = lines[index - 1] ?? '';
+        if (prev === '')
+            continue;
+        if (ATX_HEADING_RE.test(prev))
+            continue;
+        if (!HEADING_LINE_RE.test(prev))
+            continue;
+        result.add(index);
+    }
+    return result;
+}
+function isDecorativeHorizontalRule(line) {
+    // A line that is exactly `---` (or any number of `-` chars) is a
+    // candidate horizontal rule. The caller has already excluded setext
+    // and table contexts via the `protection` array.
+    return /^-+$/.test(line);
+}
+function collapseMultiBlanks(lines) {
+    const result = [];
+    let blankRun = 0;
+    for (const line of lines) {
+        if (line === '') {
+            blankRun += 1;
+            // 1 blank line is the cap. Drop the rest.
+            if (blankRun <= 1) {
+                result.push(line);
+            }
+            continue;
+        }
+        blankRun = 0;
+        result.push(line);
+    }
+    return result;
+}
+function stripDescriptionRepeat(body, description) {
+    if (description === null || description.length === 0)
+        return body;
+    // Find the first ATX heading line. If it equals the frontmatter
+    // description text, drop it. Also drop a description-matching paragraph
+    // that immediately follows the heading (PRD's "frontmatter description
+    // already in body header" case). All other content is preserved.
+    const lines = body.split('\n');
+    if (lines.length === 0)
+        return body;
+    let firstHeadingIndex = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (line.trim() === '')
+            continue;
+        if (ATX_HEADING_RE.test(line)) {
+            firstHeadingIndex = index;
+        }
+        break;
+    }
+    if (firstHeadingIndex < 0)
+        return body;
+    const headingText = (lines[firstHeadingIndex] ?? '').replace(/^#{1,6}\s+/, '').trim();
+    if (headingText !== description)
+        return body;
+    // Walk past the heading, then past any blank lines, then past the
+    // matching description paragraph (if present). Anything after the
+    // description paragraph is the body we want to keep.
+    const tail = lines.slice(firstHeadingIndex + 1);
+    let cursor = 0;
+    // Skip blanks.
+    while (cursor < tail.length && (tail[cursor] ?? '') === '') {
+        cursor += 1;
+    }
+    // Read the first non-blank paragraph.
+    const paragraphStart = cursor;
+    while (cursor < tail.length && (tail[cursor] ?? '') !== '') {
+        cursor += 1;
+    }
+    const paragraph = tail.slice(paragraphStart, cursor);
+    if (paragraph.join(' ').trim() !== description) {
+        // The paragraph doesn't match the description — don't drop it.
+        cursor = paragraphStart;
+    }
+    const kept = tail.slice(cursor);
+    if (kept.length === 0)
+        return '';
+    return kept.join('\n');
+}

package/dist/src/shared/stale-policy.d.ts

@@ -0,0 +1,67 @@
+/**
+ * stale-policy — pure helper for stale detection and filtering on memory
+ * and (future) retrospective entries.
+ *
+ * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
+ * and the underlying `readMemoryIndex` load path). The retrospective index
+ * loader shares the same shape (`updatedAt: string`) and will be wired to
+ * the same helper in a future slice.
+ *
+ * Behavior:
+ *   - `isStale(updatedAt)` returns true when (now - updatedAt) >
+ *     thresholdDays * 86_400_000. Strict greater-than: a 30-day-old
+ *     entry is NOT stale.
+ *   - `applyStalePolicy(entries)` adds `stale: boolean` and
+ *     `ageDays: number` to every entry (computed at CLI load time, never
+ *     persisted to source `.md` files) and filters out entries where
+ *     `stale === true` unless `includeStale: true` is passed.
+ *   - Missing `updatedAt` is treated as fresh (`stale: false`,
+ *     `ageDays: 0`); we never throw, so older index.json entries that
+ *     lack the field stay loadable.
+ */
+export interface StalePolicyOptions {
+    /** Reference clock (ms since epoch). Defaults to Date.now(). Injected for testability. */
+    now?: number;
+    /** Threshold in days. Default 30. */
+    thresholdDays?: number;
+    /** When true, keep stale entries in the returned array (with `stale: true` set). Default false. */
+    includeStale?: boolean;
+}
+export interface StaleAnnotated<T> {
+    stale: boolean;
+    ageDays: number;
+}
+export type StaleAnnotatedEntry<T> = T & StaleAnnotated<T>;
+export interface StalePolicyResult<T> {
+    /** Filtered array, with stale entries removed (unless includeStale=true). */
+    entries: StaleAnnotatedEntry<T>[];
+    /** Count of entries dropped as stale. */
+    droppedCount: number;
+    /** Total count before filtering. */
+    totalCount: number;
+}
+export declare const DAY_MS = 86400000;
+export declare const DEFAULT_STALE_DAYS = 30;
+/**
+ * Returns true when the entry is older than `thresholdDays`. Strict
+ * greater-than: an entry exactly at the threshold is NOT stale.
+ *
+ * A missing or unparseable `updatedAt` is treated as fresh (false). This
+ * is the "defensive — older index.json entries may lack the field" rule
+ * from PRD R4.
+ */
+export declare function isStale(updatedAt: string | undefined | null, options?: StalePolicyOptions): boolean;
+/**
+ * Age in days between `updatedAt` and `now` (default Date.now()).
+ * Returns 0 for a missing / unparseable `updatedAt`.
+ */
+export declare function ageInDays(updatedAt: string | undefined | null, now?: number): number;
+/**
+ * Apply the stale policy to a list of entries. Each entry is augmented
+ * with `stale: boolean` and `ageDays: number` (immutably — a fresh
+ * object is returned per entry). Stale entries are dropped from
+ * `entries` unless `includeStale: true` is passed.
+ */
+export declare function applyStalePolicy<T extends {
+    updatedAt?: string | null;
+}>(entries: T[], options?: StalePolicyOptions): StalePolicyResult<T>;

package/dist/src/shared/stale-policy.js

@@ -0,0 +1,85 @@
+/**
+ * stale-policy — pure helper for stale detection and filtering on memory
+ * and (future) retrospective entries.
+ *
+ * Slice 023 (R3) applies this to memory only (`peaks project memories:show`
+ * and the underlying `readMemoryIndex` load path). The retrospective index
+ * loader shares the same shape (`updatedAt: string`) and will be wired to
+ * the same helper in a future slice.
+ *
+ * Behavior:
+ *   - `isStale(updatedAt)` returns true when (now - updatedAt) >
+ *     thresholdDays * 86_400_000. Strict greater-than: a 30-day-old
+ *     entry is NOT stale.
+ *   - `applyStalePolicy(entries)` adds `stale: boolean` and
+ *     `ageDays: number` to every entry (computed at CLI load time, never
+ *     persisted to source `.md` files) and filters out entries where
+ *     `stale === true` unless `includeStale: true` is passed.
+ *   - Missing `updatedAt` is treated as fresh (`stale: false`,
+ *     `ageDays: 0`); we never throw, so older index.json entries that
+ *     lack the field stay loadable.
+ */
+export const DAY_MS = 86_400_000;
+export const DEFAULT_STALE_DAYS = 30;
+/**
+ * Returns true when the entry is older than `thresholdDays`. Strict
+ * greater-than: an entry exactly at the threshold is NOT stale.
+ *
+ * A missing or unparseable `updatedAt` is treated as fresh (false). This
+ * is the "defensive — older index.json entries may lack the field" rule
+ * from PRD R4.
+ */
+export function isStale(updatedAt, options = {}) {
+    const parsed = parseUpdatedAt(updatedAt);
+    if (parsed === null)
+        return false;
+    const now = options.now ?? Date.now();
+    const thresholdDays = options.thresholdDays ?? DEFAULT_STALE_DAYS;
+    return now - parsed > thresholdDays * DAY_MS;
+}
+/**
+ * Age in days between `updatedAt` and `now` (default Date.now()).
+ * Returns 0 for a missing / unparseable `updatedAt`.
+ */
+export function ageInDays(updatedAt, now = Date.now()) {
+    const parsed = parseUpdatedAt(updatedAt);
+    if (parsed === null)
+        return 0;
+    return Math.max(0, Math.floor((now - parsed) / DAY_MS));
+}
+/**
+ * Apply the stale policy to a list of entries. Each entry is augmented
+ * with `stale: boolean` and `ageDays: number` (immutably — a fresh
+ * object is returned per entry). Stale entries are dropped from
+ * `entries` unless `includeStale: true` is passed.
+ */
+export function applyStalePolicy(entries, options = {}) {
+    const now = options.now ?? Date.now();
+    const thresholdDays = options.thresholdDays ?? DEFAULT_STALE_DAYS;
+    const includeStale = options.includeStale ?? false;
+    const annotated = entries.map((entry) => {
+        const parsed = parseUpdatedAt(entry.updatedAt ?? null);
+        if (parsed === null) {
+            return { ...entry, stale: false, ageDays: 0 };
+        }
+        const stale = now - parsed > thresholdDays * DAY_MS;
+        const ageDays = Math.max(0, Math.floor((now - parsed) / DAY_MS));
+        return { ...entry, stale, ageDays };
+    });
+    const filtered = includeStale
+        ? annotated
+        : annotated.filter((entry) => !entry.stale);
+    return {
+        entries: filtered,
+        droppedCount: annotated.length - filtered.length,
+        totalCount: annotated.length
+    };
+}
+function parseUpdatedAt(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        return null;
+    return parsed;
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.8";
+export declare const CLI_VERSION = "1.3.9";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.8";
+export const CLI_VERSION = "1.3.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",