peaks-loop 3.0.0

package/dist/src/shared/json-schema-mini.js

@@ -0,0 +1,113 @@
+function joinPath(parent, segment) {
+    if (parent === '/') {
+        return `/${segment}`;
+    }
+    return `${parent}/${segment}`;
+}
+function typeOf(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (Number.isInteger(value)) {
+        return 'integer';
+    }
+    return typeof value;
+}
+function matchesType(value, expected) {
+    if (expected === 'integer') {
+        return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value);
+    }
+    if (expected === 'number') {
+        return typeof value === 'number' && Number.isFinite(value);
+    }
+    if (expected === 'array') {
+        return Array.isArray(value);
+    }
+    if (expected === 'null') {
+        return value === null;
+    }
+    if (expected === 'object') {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+    return typeof value === expected;
+}
+function validateNode(value, schema, path, errors) {
+    if (Array.isArray(schema.oneOf)) {
+        const branches = schema.oneOf;
+        const branchErrors = [];
+        let matched = false;
+        for (const branch of branches) {
+            const sink = [];
+            validateNode(value, branch, path, sink);
+            if (sink.length === 0) {
+                matched = true;
+                break;
+            }
+            branchErrors.push(sink);
+        }
+        if (!matched) {
+            const detail = branchErrors.map((sink) => sink.map((issue) => issue.message).join(' / ')).join(' | ');
+            errors.push({ path, message: `does not match any oneOf branch (${detail})` });
+        }
+        return;
+    }
+    const expectedType = typeof schema.type === 'string' ? schema.type : null;
+    if (expectedType !== null && !matchesType(value, expectedType)) {
+        errors.push({ path, message: `expected type ${expectedType}, got ${typeOf(value)}` });
+        return;
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            errors.push({ path, message: `string shorter than minLength ${schema.minLength}` });
+        }
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value)) {
+            errors.push({ path, message: `string does not match pattern ${schema.pattern}` });
+        }
+        if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+            errors.push({ path, message: `value ${JSON.stringify(value)} is not in enum` });
+        }
+        return;
+    }
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum) {
+            errors.push({ path, message: `number below minimum ${schema.minimum}` });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (schema.items !== undefined) {
+            const itemSchema = schema.items;
+            value.forEach((entry, index) => {
+                validateNode(entry, itemSchema, joinPath(path, index), errors);
+            });
+        }
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (!Object.prototype.hasOwnProperty.call(record, key)) {
+                    errors.push({ path, message: `missing required property: ${key}` });
+                }
+            }
+        }
+        const properties = schema.properties;
+        if (properties !== null && typeof properties === 'object' && !Array.isArray(properties)) {
+            const propertyMap = properties;
+            for (const [key, child] of Object.entries(propertyMap)) {
+                if (Object.prototype.hasOwnProperty.call(record, key)) {
+                    validateNode(record[key], child, joinPath(path, key), errors);
+                }
+            }
+        }
+    }
+}
+export function validateAgainstSchema(value, schema) {
+    const errors = [];
+    validateNode(value, schema, '/', errors);
+    return { valid: errors.length === 0, errors };
+}

package/dist/src/shared/path-safety.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Path-safety helpers for peaks-cli artifact paths.
+ *
+ * Extracted after the v2.19.0 change-id root removal. The change-id
+ * axis was eliminated entirely; the remaining helper utilities are
+ * path-traversal / absolute-path / drive-path / UNC-path guards plus
+ * a path-containment check used by writer code.
+ *
+ * Used by services that need a "is this user-supplied path safe?"
+ * check without bringing in the change-id axis.
+ */
+export declare function isUnsafePathInput(input: string): boolean;
+export declare function isUnsafeArtifactPath(path: string): boolean;
+declare function normalizeArtifactPath(input: string): string;
+export { normalizeArtifactPath as _normalizeArtifactPath };
+/**
+ * Path-containment check. Returns true when `path` equals `artifactRoot`
+ * or starts with `<artifactRoot>/`. Used by workspace reconcile to
+ * verify on-disk paths stay inside the artifact workspace.
+ */
+export declare function isPathInsideArtifactRoot(path: string, artifactRoot: string): boolean;

package/dist/src/shared/path-safety.js

@@ -0,0 +1,54 @@
+/**
+ * Path-safety helpers for peaks-cli artifact paths.
+ *
+ * Extracted after the v2.19.0 change-id root removal. The change-id
+ * axis was eliminated entirely; the remaining helper utilities are
+ * path-traversal / absolute-path / drive-path / UNC-path guards plus
+ * a path-containment check used by writer code.
+ *
+ * Used by services that need a "is this user-supplied path safe?"
+ * check without bringing in the change-id axis.
+ */
+import { posix } from 'node:path';
+function normalizeForwardSlashes(input) {
+    return input.replace(/\\/g, '/');
+}
+function hasUnsafePathShape(input) {
+    const normalized = normalizeForwardSlashes(input);
+    if (input.includes('\\'))
+        return true;
+    if (!normalized || normalized === '.' || normalized === '..')
+        return true;
+    if (normalized.startsWith('/') || normalized.startsWith('//'))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    if (normalized.includes('://'))
+        return true;
+    if (/^[^@\s]+@[^:\s]+:.+/.test(normalized))
+        return true;
+    return normalized.split('/').some((segment) => segment.length === 0 || segment === '.' || segment === '..');
+}
+export function isUnsafePathInput(input) {
+    return hasUnsafePathShape(input);
+}
+export function isUnsafeArtifactPath(path) {
+    return isUnsafePathInput(path);
+}
+function normalizeArtifactPath(input) {
+    const normalized = posix.normalize(normalizeForwardSlashes(input));
+    return normalized.replace(/\/$/, '');
+}
+export { normalizeArtifactPath as _normalizeArtifactPath };
+/**
+ * Path-containment check. Returns true when `path` equals `artifactRoot`
+ * or starts with `<artifactRoot>/`. Used by workspace reconcile to
+ * verify on-disk paths stay inside the artifact workspace.
+ */
+export function isPathInsideArtifactRoot(path, artifactRoot) {
+    if (!path || !artifactRoot)
+        return false;
+    const normalizedPath = normalizeArtifactPath(path);
+    const normalizedRoot = normalizeArtifactPath(artifactRoot);
+    return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
+}

package/dist/src/shared/path-utils.d.ts

@@ -0,0 +1,13 @@
+import { type Platform } from './platform.js';
+export declare const SEP: "\\" | "/";
+export declare function normalizePath(p: string): string;
+export declare function pathsEqual(a: string, b: string): boolean;
+export declare function localPath(p: string, targetPlatform?: Platform): string;
+export declare function getTempDir(options?: {
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function isInsidePath(childPath: string, parentPath: string): boolean;
+export declare function isWindowsAbsolutePath(path: string): boolean;
+export declare function resolveInputPath(path: string): string;
+export declare function stableRealPath(path: string): string;
+export declare function stablePath(path: string): string;

package/dist/src/shared/path-utils.js

@@ -0,0 +1,56 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, parse, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { platform } from './platform.js';
+export const SEP = sep;
+const localPathConverters = {
+    win32: (p) => p.replace(/\//g, '\\'),
+    darwin: (p) => p,
+    linux: (p) => p
+};
+export function normalizePath(p) {
+    return p.replace(/\\/g, '/');
+}
+export function pathsEqual(a, b) {
+    return normalizePath(a) === normalizePath(b);
+}
+export function localPath(p, targetPlatform = platform) {
+    return localPathConverters[targetPlatform](p);
+}
+export function getTempDir(options) {
+    const env = options?.env ?? process.env;
+    if (env.TEMP)
+        return env.TEMP;
+    if (env.TMP)
+        return env.TMP;
+    return tmpdir();
+}
+export function isInsidePath(childPath, parentPath) {
+    const relativePath = relative(parentPath, childPath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+export function isWindowsAbsolutePath(path) {
+    return /^[A-Za-z]:[\\/]/.test(path);
+}
+export function resolveInputPath(path) {
+    return isWindowsAbsolutePath(path) ? normalizePath(path) : resolve(path);
+}
+export function stableRealPath(path) {
+    return realpathSync(resolveInputPath(path));
+}
+export function stablePath(path) {
+    const resolvedPath = resolveInputPath(path);
+    if (existsSync(resolvedPath)) {
+        return stableRealPath(resolvedPath);
+    }
+    const parsedPath = parse(resolvedPath);
+    const missingSegments = [];
+    let currentPath = resolvedPath;
+    while (!existsSync(currentPath) && currentPath !== parsedPath.root) {
+        const parsedCurrent = parse(currentPath);
+        missingSegments.unshift(parsedCurrent.base);
+        currentPath = parsedCurrent.dir;
+    }
+    const realExistingPath = existsSync(currentPath) ? stableRealPath(currentPath) : parsedPath.root;
+    return resolve(realExistingPath, ...missingSegments);
+}

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

@@ -0,0 +1,6 @@
+export declare const repoRoot: string;
+export declare const skillsDir: string;
+export declare const schemasDir: string;
+export declare const templatesDir: string;
+export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt", "peaks-sop"];
+export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json", "library-breaking-changes.schema.json"];

package/dist/src/shared/paths.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function findRepoRoot(startPath) {
+    let currentPath = startPath;
+    while (currentPath !== dirname(currentPath)) {
+        if (existsSync(resolve(currentPath, 'package.json')) && existsSync(resolve(currentPath, 'skills'))) {
+            return currentPath;
+        }
+        currentPath = dirname(currentPath);
+    }
+    throw new Error(`Unable to locate Peaks repository root from ${startPath}`);
+}
+const currentFile = fileURLToPath(import.meta.url);
+export const repoRoot = findRepoRoot(dirname(currentFile));
+export const skillsDir = resolve(repoRoot, 'skills');
+export const schemasDir = resolve(repoRoot, 'schemas');
+export const templatesDir = resolve(repoRoot, 'templates');
+export const requiredSkillNames = [
+    'peaks-solo',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-txt',
+    'peaks-sop'
+];
+export const requiredSchemaFiles = [
+    'artifact-manifest.schema.json',
+    'context-capsule.schema.json',
+    'approval-record.schema.json',
+    'change-impact.schema.json',
+    'refactor-slice-spec.schema.json',
+    'artifact-retention-report.schema.json',
+    'capability-source.schema.json',
+    'capability-item.schema.json',
+    'capability-availability.schema.json',
+    'recommendation-plan.schema.json',
+    'artifact-workspace.schema.json',
+    'mcp-server.schema.json',
+    'mcp-install-spec.schema.json',
+    'mcp-install-plan.schema.json',
+    'mcp-apply-result.schema.json',
+    'openspec-change-summary.schema.json',
+    'openspec-render-request.schema.json',
+    'openspec-validation-result.schema.json',
+    'doctor-report.schema.json',
+    'library-breaking-changes.schema.json'
+];

package/dist/src/shared/planner-response.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared response types for planner commands.
+ * These types ensure consistent error/status reporting across
+ * tech and RD swarm dry-run planner commands.
+ */
+export type WorkspaceUnavailableBehavior = 'preview' | 'blocked';
+export type ArtifactWorkspaceUnavailableResponse = {
+    available: false;
+    behavior: WorkspaceUnavailableBehavior;
+    reason: string;
+    nextActions: readonly string[];
+};
+export type ArtifactWorkspaceAvailableResponse<T> = {
+    available: true;
+    data: T;
+};
+export type ArtifactWorkspaceResponse<T> = ArtifactWorkspaceUnavailableResponse | ArtifactWorkspaceAvailableResponse<T>;
+export declare const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS: readonly string[];
+export declare function makeUnavailableResponse(behavior: WorkspaceUnavailableBehavior, reason: string): ArtifactWorkspaceUnavailableResponse;
+export declare function makeAvailableResponse<T>(data: T): ArtifactWorkspaceAvailableResponse<T>;
+export declare function isUnavailableResponse<T>(resp: ArtifactWorkspaceResponse<T>): resp is ArtifactWorkspaceUnavailableResponse;

package/dist/src/shared/planner-response.js

@@ -0,0 +1,26 @@
+/**
+ * Shared response types for planner commands.
+ * These types ensure consistent error/status reporting across
+ * tech and RD swarm dry-run planner commands.
+ */
+export const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS = Object.freeze([
+    'Configure a Peaks artifact workspace in your workspace config.',
+    'See peaks artifacts workspace --help for setup instructions.',
+]);
+export function makeUnavailableResponse(behavior, reason) {
+    return {
+        available: false,
+        behavior,
+        reason,
+        nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+    };
+}
+export function makeAvailableResponse(data) {
+    return {
+        available: true,
+        data,
+    };
+}
+export function isUnavailableResponse(resp) {
+    return resp.available === false;
+}

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

@@ -0,0 +1,6 @@
+export type Platform = 'win32' | 'darwin' | 'linux';
+export declare function detectPlatform(currentPlatform?: NodeJS.Platform): Platform;
+export declare const platform: Platform;
+export declare const isWindows: boolean;
+export declare const isMac: boolean;
+export declare const isLinux: boolean;

package/dist/src/shared/platform.js

@@ -0,0 +1,11 @@
+export function detectPlatform(currentPlatform = process.platform) {
+    if (currentPlatform === 'win32')
+        return 'win32';
+    if (currentPlatform === 'darwin')
+        return 'darwin';
+    return 'linux';
+}
+export const platform = detectPlatform();
+export const isWindows = platform === 'win32';
+export const isMac = platform === 'darwin';
+export const isLinux = platform === 'linux';

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

@@ -0,0 +1,5 @@
+export type ExecCommandOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv | undefined;
+};
+export declare function execCommand(command: string, args: string[], options?: ExecCommandOptions): Promise<string>;

package/dist/src/shared/process.js

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+export async function execCommand(command, args, options) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { cwd: options?.cwd, env: options?.env }, (error, stdout) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(stdout.trim());
+        });
+    });
+}

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

@@ -0,0 +1,22 @@
+export type ResultEnvelope<T> = {
+    ok: boolean;
+    command: string;
+    data: T;
+    warnings: string[];
+    nextActions: string[];
+    code?: string;
+    message?: string;
+    /**
+     * Slice 2026-06-23-audit-4th #B3: opaque per-failure correlation
+     * id. Always present on `fail()` envelopes. Lets a user say
+     * "my last failure was errorId=X; show me the JSONL log lines
+     * tagged with X" without grepping on a code/message that may be
+     * repeated. Also written to the next writeLogEntry call (best-effort)
+     * by the caller so the log entry can be cross-referenced.
+     */
+    errorId?: string;
+};
+export declare function ok<T>(command: string, data: T, warnings?: string[], nextActions?: string[]): ResultEnvelope<T>;
+export declare function fail<T>(command: string, code: string, message: string, data: T, nextActions?: string[]): ResultEnvelope<T>;
+export declare function getErrorMessage(error: unknown): string;
+export declare function redactSensitiveErrorMessage(message: string): string;

package/dist/src/shared/result.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+export function ok(command, data, warnings = [], nextActions = []) {
+    return { ok: true, command, data, warnings, nextActions };
+}
+export function fail(command, code, message, data, nextActions = []) {
+    // Slice 2026-06-23-audit-4th #B3: mint a fresh errorId per failure.
+    // The id is opaque (uuid v4) and never reused; downstream log
+    // entries from the same code path can carry the same id for
+    // post-hoc correlation.
+    return {
+        ok: false,
+        command,
+        code,
+        message: redactSensitiveErrorMessage(message),
+        data,
+        warnings: [],
+        nextActions,
+        errorId: randomUUID()
+    };
+}
+const SENSITIVE_ERROR_PATTERNS = [
+    /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
+    /\b(?:api[\s_-]?key|token|password|secret)\s*[:=]\s*['\"]?[^\s'\"]{8,}/gi,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{20,}\b/g,
+    /\bghp_[0-9A-Za-z_]{20,}\b/g,
+    /\bgithub_pat_[0-9A-Za-z_]{20,}\b/g,
+    /\bglpat-[0-9A-Za-z_-]{20,}\b/g,
+    /\bxox[abprse]-[0-9A-Za-z-]{20,}\b/g,
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+    /(secret|token|password|api[-_ ]?key)/gi
+];
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'Unexpected error';
+}
+export function redactSensitiveErrorMessage(message) {
+    return SENSITIVE_ERROR_PATTERNS.reduce((redacted, pattern) => redacted.replace(pattern, '[redacted]'), message);
+}

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

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "3.0.0";

package/dist/src/shared/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = "3.0.0";