peaks-cli 1.3.8 → 1.4.0

package/dist/src/services/workflow/plan-trigger-detector.js

@@ -0,0 +1,142 @@
+/**
+ * `peaks workflow plan detect-trigger` — slice 025 (Security + Perf
+ * Plan/Result split).
+ *
+ * Compares the current project state (filesystem + package.json) to the
+ * last-refresh fingerprint and returns whether a plan refresh is
+ * warranted. Five trigger rules, locked decision 1 excludes
+ * devDependencies.
+ *
+ * The slice's "diff" is supplied as a `SliceDiff` object; when not
+ * supplied, the detector scans the project directly (the same scan the
+ * refresh plan performs).
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok } from '../../shared/result.js';
+/** F-1 (slice 025 security): canonical request-id shape. */
+export const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SENSITIVE_SERVICE_DIRS = ['auth', 'security', 'secrets', 'payments', 'filesystem'];
+function readPackageJson(projectRoot) {
+    const path = join(projectRoot, 'package.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isAuthFile(path) {
+    return /auth.*\.ts$|\.ts$/i.test(path) && /auth/i.test(path);
+}
+function isHotPathFile(path) {
+    return /router\.ts$|commands\/.*-commands\.ts$/i.test(path);
+}
+function isSensitiveServiceFile(path) {
+    if (!/^src\/services\/(auth|security|secrets|payments|filesystem)\//.test(path))
+        return false;
+    return /\.ts$/.test(path);
+}
+function freshScan(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    const newFiles = [];
+    const root = join(projectRoot, 'src');
+    if (existsSync(root)) {
+        const stack = [root];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                continue;
+            let entries;
+            try {
+                entries = readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === 'dist')
+                    continue;
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                    // For the purposes of trigger detection, every TS file is a
+                    // candidate; the gate logic decides which class it falls into.
+                    newFiles.push(full);
+                }
+            }
+        }
+    }
+    return {
+        packageJson: {
+            dependencies: { added: Object.keys(pkg?.dependencies ?? {}), removed: [], changed: [] },
+            optionalDependencies: { added: Object.keys(pkg?.optionalDependencies ?? {}), removed: [], changed: [] },
+            devDependencies: { added: Object.keys(pkg?.devDependencies ?? {}), removed: [], changed: [] }
+        },
+        newFiles: newFiles.sort(),
+        changedFiles: []
+    };
+}
+function anyAddedDeps(diff) {
+    const dep = diff.packageJson?.dependencies?.added ?? [];
+    const opt = diff.packageJson?.optionalDependencies?.added ?? [];
+    return dep.length > 0 || opt.length > 0;
+}
+function findNewAuthFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isAuthFile(f))
+            return f;
+    }
+    return null;
+}
+function findNewSensitiveServiceFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isSensitiveServiceFile(f))
+            return f;
+    }
+    return null;
+}
+function findNewHotPathFile(diff) {
+    for (const f of diff.newFiles ?? []) {
+        if (isHotPathFile(f))
+            return f;
+    }
+    return null;
+}
+export function detectTrigger(args) {
+    // F-1 (slice 025 security): reject traversal/separator payloads at
+    // the service boundary so every caller (CLI, skill, integration test)
+    // gets the same rejection shape.
+    if (!REQUEST_ID_PATTERN.test(args.rid)) {
+        return fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', {
+            triggered: false,
+            reason: 'no-triggering-change'
+        });
+    }
+    if (args.manualOverride === true) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'manual-override' });
+    }
+    const diff = args.diff ?? freshScan(args.project);
+    // Rule 1: new top-level dependency in `dependencies` or `optionalDependencies`
+    // (devDependencies explicitly excluded per locked decision 1).
+    if (anyAddedDeps(diff)) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'new-dependency' });
+    }
+    // Rule 2: new file under src/services/{auth,security,secrets,payments,filesystem}/
+    if (findNewSensitiveServiceFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'auth-surface-added' });
+    }
+    // Rule 3: new *auth*.ts file anywhere in src/
+    if (findNewAuthFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'auth-surface-added' });
+    }
+    // Rule 4: new endpoint / route registration
+    if (findNewHotPathFile(diff) !== null) {
+        return ok('workflow.plan.detect-trigger', { triggered: true, reason: 'hot-path-added' });
+    }
+    return ok('workflow.plan.detect-trigger', { triggered: false, reason: 'no-triggering-change' });
+}

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.4.0";

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "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",
@@ -46,8 +46,9 @@
     "pretest": "node ./scripts/sync-version.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
     "pretest:coverage": "node ./scripts/pretest-coverage.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/"
   },
   "engines": {
     "node": ">=20.0.0"

package/schemas/doctor-report.schema.json

@@ -13,8 +13,8 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build):[A-Za-z0-9][A-Za-z0-9._-]*$",
-            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency)."
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }