peaks-cli 1.3.7 → 1.3.9

package/dist/src/services/session/platform-fallbacks.js

@@ -0,0 +1,35 @@
+/**
+ * PLATFORM_FALLBACKS — the Level 3 fallback table for caller-id resolution.
+ *
+ * Slice 020 (D3): when neither `--caller-id` nor `PEAKS_CALLER_ID` is
+ * set, the resolver walks this table top-to-bottom and takes the
+ * first non-empty entry. Today there is exactly one entry: Claude
+ * Code (`CLAUDE_CODE_SESSION_ID`).
+ *
+ * To add a new platform (Cursor, Windsurf, peaks-ide, etc.):
+ *
+ *   1. Add a new entry below.
+ *   2. Bump the contract doc's A5 acceptance criterion
+ *      (`.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`).
+ *   3. Add a regression test that asserts the new entry resolves
+ *      correctly under D4 priority.
+ *
+ * The contract's A5 test (`tests/unit/services/session/caller-id-resolution.test.ts`)
+ * asserts `PLATFORM_FALLBACKS.length === 1`; adding a new entry will
+ * fail that test, forcing the contract bump.
+ *
+ * Adding an entry does NOT require code changes to read points
+ * (statusline, doctor, sc, session-info) — they all call the same
+ * resolver. Each entry is a one-line additive change.
+ */
+export const PLATFORM_FALLBACKS = [
+    {
+        envVar: 'CLAUDE_CODE_SESSION_ID',
+        description: 'Claude Code session id',
+        addedIn: '1.3.7'
+    }
+    // Future entries (do NOT add without bumping the contract's A5):
+    // { envVar: 'CURSOR_SESSION_ID', description: 'Cursor session id', addedIn: 'TBD' },
+    // { envVar: 'WINDSURF_SESSION_ID', description: 'Windsurf session id', addedIn: 'TBD' },
+    // { envVar: 'PEAKS_IDE_SESSION_ID', description: 'peaks-ide session id', addedIn: 'TBD' },
+];

package/dist/src/services/session/resolve-caller-id.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CallerIdError } from './caller-id-types.js';
+export { CallerIdError };
+export interface ResolveCallerIdOptions {
+    /**
+     * The `--caller-id <id>` flag value (per-invocation override).
+     * D4 priority level 1: flag wins.
+     */
+    flagValue?: string;
+    /**
+     * Override for the `PEAKS_CALLER_ID` environment variable. D4
+     * priority level 2: env wins. Defaults to `process.env.PEAKS_CALLER_ID`.
+     * The override exists so tests can run without mutating process.env.
+     */
+    envOverride?: string;
+    /**
+     * The env object to read. Defaults to `process.env`. Exists so
+     * tests can drive Level 3 (platform fallback) without mutating
+     * process.env.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export declare function resolveCallerId(opts?: ResolveCallerIdOptions): string;

package/dist/src/services/session/resolve-caller-id.js

@@ -0,0 +1,88 @@
+/**
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ *
+ * `resolveCallerId` is the single source of truth for "who is calling
+ * the CLI". The resolver applies D4 priority (flag > env > platform
+ * fallback > reject) and validates the winner against D1's regex;
+ * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ *
+ * The function is synchronous and pure. It does NOT touch the
+ * filesystem, does NOT read any caller binding file, and does NOT
+ * mutate state. The caller (a CLI command, a service, a test) decides
+ * what to do with the resolved id.
+ *
+ * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
+ * for the freeze-in contract (D1-D7).
+ */
+import { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';
+import { PLATFORM_FALLBACKS } from './platform-fallbacks.js';
+// Re-export for CLI consumers (avoids a second import line).
+export { CallerIdError };
+/**
+ * Check whether `value` looks like a callerId (non-empty, matches D1).
+ * Returns the trimmed value if so, undefined otherwise. Does not throw.
+ */
+function isNonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Read a single platform-fallback env var from `env`. Returns the
+ * non-empty trimmed value or `undefined`. Logs nothing.
+ */
+function readPlatformFallback(env) {
+    for (let i = 0; i < PLATFORM_FALLBACKS.length; i++) {
+        const candidate = env[PLATFORM_FALLBACKS[i].envVar];
+        if (isNonEmpty(candidate)) {
+            return { value: candidate, index: i };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate `value` against D1's regex. Returns the value on success,
+ * throws `CallerIdError` (EX_DATAERR, exit 65) on failure.
+ */
+function validateCallerId(value, source) {
+    if (!CALLER_ID_REGEX.test(value)) {
+        throw new CallerIdError('EX_DATAERR', source, `Invalid caller id "${value}" (source: ${source}). callerId must match ^[a-zA-Z0-9._-]{1,200}$.`, value);
+    }
+    return value;
+}
+/**
+ * Resolve the calling process's callerId per D1-D5.
+ *
+ * D4 priority (strict, no merge):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
+ *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
+ *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
+ *
+ * On success: returns the resolved id (matches D1's regex, validated).
+ * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
+ * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ *
+ * @example
+ *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
+ *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ */
+export function resolveCallerId(opts = {}) {
+    const env = opts.env ?? process.env;
+    // D4 level 1: flag value
+    if (isNonEmpty(opts.flagValue)) {
+        return validateCallerId(opts.flagValue, 'flag');
+    }
+    // D4 level 2: env var
+    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : env.PEAKS_CALLER_ID;
+    if (isNonEmpty(envValue)) {
+        return validateCallerId(envValue, 'env');
+    }
+    // D4 level 3: PLATFORM_FALLBACKS table (top-to-bottom)
+    const fallback = readPlatformFallback(env);
+    if (fallback !== undefined) {
+        return validateCallerId(fallback.value, 'fallback');
+    }
+    // D4 level 4: D2 fires — no callerId available
+    throw new CallerIdError('EX_USAGE', 'none', 'No caller id available. Set PEAKS_CALLER_ID or pass --caller-id.');
+}

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -43,6 +43,17 @@ export type SkillPresence = {
     lastHeartbeat?: string;
 };
 export declare function exportSkillPresence(projectRootOverride?: string): string;
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export declare function setSkillPresenceForCaller(projectRootOverride: string, callerId: string, peakSessionId: string, skill: string, mode?: string, gate?: string): SkillPresence;
 export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
 export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
 export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;

package/dist/src/services/skills/skill-presence-service.js

@@ -160,6 +160,65 @@ function getPreviousOuterSessionId(projectRootOverride) {
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
 }
+// ============================================================================
+// Slice 020 — caller-keyed active-skill marker (D6).
+// ============================================================================
+//
+// Today's per-project active-skill marker (`.peaks/_runtime/active-skill.json`)
+// races when multiple Claude Code windows (or different platforms) drive the
+// same project concurrently. Slice 020 introduces a per-caller file at
+// `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Two callers
+// bound to the same peak session never clobber each other.
+//
+// The single-file marker is RETAINED for one minor release as read-only
+// back-compat (M1, M4). The new write path is `setSkillPresenceForCaller`;
+// the legacy `setSkillPresence` is now a thin wrapper that synthesises a
+// legacy callerId from `process.env.CLAUDE_CODE_SESSION_ID` (or
+// `projectRoot` for the truly-anonymous case) and delegates.
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSessionId, skill, mode, gate) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const now = new Date().toISOString();
+    const presence = {
+        skill,
+        ...(validatedMode ? { mode: validatedMode } : {}),
+        ...(gate ? { gate } : {}),
+        ...(peakSessionId ? { sessionId: peakSessionId } : {}),
+        ...(callerId ? { outerSessionId: callerId } : {}),
+        setAt: now,
+        lastHeartbeat: now
+    };
+    const presencePath = getActiveSkillFileForCallerPath(resolveProjectRoot(projectRootOverride), peakSessionId, callerId);
+    const presenceDir = dirname(presencePath);
+    if (!existsSync(presenceDir)) {
+        mkdirSync(presenceDir, { recursive: true });
+    }
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: bring the memory store into existence for
+    // fresh projects. Same fail-open contract as the legacy path.
+    ensureMemoryBootstrap(resolveProjectRoot(projectRootOverride));
+    return presence;
+}
+/**
+ * Compute the per-caller active-skill file path. Re-exported for test
+ * ergonomics; canonical path lives in
+ * `src/services/session/caller-binding-service.ts` but inlined here to
+ * avoid a circular import (`caller-binding-service` reads
+ * `skill-presence-service` for the `setCallerBinding` integration in
+ * future slices; the inverse import would deadlock).
+ */
+function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
+    return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
+}
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);

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