peaks-loop 4.0.34 → 4.0.35

package/dist/services/memory/memory-ingest-service.js

@@ -0,0 +1,225 @@
+// ---------------------------------------------------------------------------
+// `peaks memory ingest` — pull memories written by the IDE-side agent into
+// the peaks-owned store.
+//
+// Slice 2026-09-09-memory-system-overhaul (A). Before this, "沉淀记忆" in a
+// peaks-code workflow landed in Claude Code's own per-project memory dir
+// (`~/.claude/projects/<hash>/memory/`) and never reached `.peaks/memory/`
+// — a split-brain write path with no single authority.
+//
+// Authority contract:
+//   - `.peaks/memory/` is the authoritative, peaks-owned store.
+//   - `~/.claude/**` is READ-ONLY. This module never writes there (same
+//     rule the project already applies to `~/.claude/agents/`). The only
+//     write targets are inside the project's `.peaks/memory/`.
+//   - The IDE-side memory dir is a session note, not the authority.
+//
+// Idempotency: identity is the filename stem. Re-running skips destination
+// files that are byte-identical; when the destination exists but differs it
+// is reported as a conflict and BOTH copies are left untouched (never
+// overwrite user content).
+//
+// Classification: a memory is imported only when its kind resolves through
+// the shared `resolveMemoryKind` rule (`metadata.type` → `kind:` → `type:`).
+// Files with no resolvable kind are reported as needing classification —
+// no type is invented silently.
+// ---------------------------------------------------------------------------
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { isInsidePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
+import { parseMemoryFrontmatter } from './project-memory-service/parsers/frontmatter.js';
+import { summarizeMemoryBody } from './project-memory-service/parsers/markdown-pure.js';
+import { assertSafeProjectMemoryDir, normalizeRoot } from './project-memory-service/store/paths.js';
+import { assertSafeMemoryFileContent, writeNewFile } from './project-memory-service/store/atomic-write.js';
+import { listMarkdownFiles } from './project-memory-service/index/search.js';
+/** `MEMORY.md` is the IDE's own generated index, not a memory source. */
+const IDE_INDEX_FILENAME = 'MEMORY.md';
+const RESERVED_TOP_LEVEL_KEYS = new Set(['name', 'description', 'metadata', 'type', 'kind']);
+const RESERVED_METADATA_KEYS = new Set(['type', 'kind', 'description']);
+/**
+ * Claude Code encodes a project cwd into its `~/.claude/projects/<name>/`
+ * directory by replacing every non-alphanumeric character with `-`
+ * (`D:\peaks-loop` → `D--peaks-loop`). Separator-agnostic, so the same
+ * encoding holds for POSIX paths.
+ */
+export function encodeIdeProjectDir(projectRoot) {
+    return projectRoot.replace(/[^A-Za-z0-9]/g, '-');
+}
+/** Default IDE-side memory dir for a project: `~/.claude/projects/<encoded>/memory`. */
+export function defaultIdeMemoryDir(projectRoot, homeDir) {
+    return join(homeDir ?? homedir(), '.claude', 'projects', encodeIdeProjectDir(projectRoot), 'memory');
+}
+function parseFrontmatterDoc(frontmatter) {
+    const top = [];
+    const metadata = [];
+    let inMetadata = false;
+    for (const rawLine of frontmatter.split('\n')) {
+        if (rawLine.trim() === '')
+            continue;
+        const indented = /^\s/.test(rawLine);
+        const line = rawLine.trim();
+        const separator = line.indexOf(':');
+        if (separator < 0)
+            continue;
+        const key = line.slice(0, separator).trim();
+        const value = line.slice(separator + 1).trim();
+        if (indented) {
+            if (inMetadata)
+                metadata.push([key, value]);
+            continue;
+        }
+        inMetadata = key === 'metadata';
+        if (!inMetadata)
+            top.push([key, value]);
+    }
+    return { top, metadata };
+}
+/**
+ * Rewrite a source file's frontmatter to the peaks contract: `name` pinned to
+ * the destination filename stem, and `metadata.type` set to the resolved
+ * kind. Non-contract keys (e.g. `originSessionId`, `modified`, `node_type`)
+ * are preserved verbatim so provenance survives the import; `type` / `kind`
+ * are consumed by the normalization and not duplicated.
+ */
+export function renderNormalizedMemory(input) {
+    const doc = parseFrontmatterDoc(input.frontmatter);
+    const topMap = new Map(doc.top);
+    const metaMap = new Map(doc.metadata);
+    const description = topMap.get('description')
+        ?? metaMap.get('description')
+        ?? summarizeMemoryBody(input.body);
+    const lines = ['---', `name: ${input.stem}`, `description: ${description}`];
+    for (const [key, value] of doc.top) {
+        if (RESERVED_TOP_LEVEL_KEYS.has(key))
+            continue;
+        lines.push(`${key}: ${value}`);
+    }
+    lines.push('metadata:');
+    lines.push(`  type: ${input.kind}`);
+    for (const [key, value] of doc.metadata) {
+        if (RESERVED_METADATA_KEYS.has(key))
+            continue;
+        lines.push(`  ${key}: ${value}`);
+    }
+    lines.push('---', '', input.body, '');
+    return lines.join('\n');
+}
+function emptyReport(overrides) {
+    return {
+        apply: false,
+        sourceExists: false,
+        scannedFiles: 0,
+        imported: [],
+        skippedIdentical: [],
+        conflicts: [],
+        needsClassification: [],
+        refused: [],
+        writtenFiles: [],
+        warnings: [],
+        ...overrides
+    };
+}
+/**
+ * Import IDE-side memories into `.peaks/memory/`. Always returns the full
+ * envelope; `apply` only controls whether files are actually written.
+ */
+export function executeMemoryIngest(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const apply = options.apply ?? false;
+    const sourceDir = options.sourceDir !== undefined
+        ? resolveInputPath(options.sourceDir)
+        : defaultIdeMemoryDir(projectRoot, options.homeDir);
+    if (!existsSync(sourceDir)) {
+        return emptyReport({
+            apply,
+            projectRoot,
+            sourceDir,
+            memoryDir,
+            warnings: [`No IDE-side memory directory at ${sourceDir}; nothing to ingest.`]
+        });
+    }
+    const report = emptyReport({ apply, projectRoot, sourceDir, memoryDir, sourceExists: true });
+    const sourceFiles = listMarkdownFiles(sourceDir);
+    const indexFiles = sourceFiles.filter((filePath) => basename(filePath) === IDE_INDEX_FILENAME);
+    if (indexFiles.length > 0) {
+        report.warnings.push(`Skipped ${indexFiles.length} IDE-side index file(s) named ${IDE_INDEX_FILENAME} (generated by the IDE, not a memory).`);
+    }
+    const memoryFiles = sourceFiles.filter((filePath) => basename(filePath) !== IDE_INDEX_FILENAME);
+    report.scannedFiles = memoryFiles.length;
+    // Only materialise the destination directory once we know there is at
+    // least one candidate and we are actually applying.
+    if (apply && memoryFiles.length > 0) {
+        mkdirSync(memoryDir, { recursive: true });
+    }
+    const stableMemoryDir = existsSync(memoryDir) ? stableRealPath(memoryDir) : null;
+    for (const sourcePath of memoryFiles) {
+        const stem = basename(sourcePath, '.md');
+        let content;
+        try {
+            content = readFileSync(sourcePath, 'utf8');
+        }
+        catch {
+            report.refused.push({ name: stem, sourcePath, reason: 'source file could not be read' });
+            continue;
+        }
+        const parsed = parseMemoryFrontmatter(content);
+        const kind = parsed.kind.kind;
+        if (kind === null) {
+            report.needsClassification.push({
+                name: parsed.name ?? stem,
+                sourcePath,
+                rawKind: parsed.kind.rawKind,
+                reason: parsed.kind.rawKind === null
+                    ? 'no metadata.type / kind / type field in frontmatter'
+                    : `unrecognized kind value: ${parsed.kind.rawKind}`
+            });
+            continue;
+        }
+        const normalized = renderNormalizedMemory({ stem, kind, frontmatter: parsed.frontmatter, body: parsed.body });
+        // Never import secrets into the peaks store. Fail-soft: report, skip.
+        try {
+            assertSafeMemoryFileContent(normalized);
+        }
+        catch {
+            report.refused.push({ name: stem, sourcePath, reason: 'refused: sensitive content pattern' });
+            continue;
+        }
+        const targetPath = join(memoryDir, `${stem}.md`);
+        const entry = { name: stem, kind, sourcePath, targetPath };
+        if (existsSync(targetPath)) {
+            let existing;
+            try {
+                existing = readFileSync(targetPath, 'utf8');
+            }
+            catch {
+                report.conflicts.push({ name: stem, sourcePath, targetPath, reason: 'destination exists but could not be read' });
+                continue;
+            }
+            if (existing === normalized) {
+                report.skippedIdentical.push({ name: stem, sourcePath, targetPath });
+            }
+            else {
+                report.conflicts.push({ name: stem, sourcePath, targetPath, reason: 'destination exists with different content; both copies left untouched' });
+            }
+            continue;
+        }
+        if (!apply) {
+            report.imported.push(entry);
+            continue;
+        }
+        // Defence in depth: the write target must resolve inside the project's
+        // `.peaks/memory/`. This is the guard that makes "never write to
+        // ~/.claude/**" structural rather than a convention.
+        const stableTargetPath = stablePath(resolveInputPath(targetPath));
+        if (stableMemoryDir === null || !isInsidePath(stableTargetPath, stableMemoryDir)) {
+            report.refused.push({ name: stem, sourcePath, reason: 'refused: target path escapes the project memory directory' });
+            continue;
+        }
+        writeNewFile(targetPath, normalized);
+        report.imported.push(entry);
+        report.writtenFiles.push(targetPath);
+    }
+    return report;
+}

package/dist/services/memory/memory-rotate-service.d.ts

@@ -0,0 +1,88 @@
+/** User override 2026-09-10: the policy's 12-month window is now 6 months. */
+export declare const MEMORY_ROTATION_RETENTION_MONTHS = 6;
+export declare const MEMORY_ROTATION_ARCHIVED_DIRNAME = "archived";
+/** Default reference-grep roots, relative to the project root. */
+export declare const MEMORY_ROTATION_REFERENCE_ROOTS: readonly ["src", "skills"];
+export type MemoryRotationTier = 'A' | 'B' | 'C' | 'D';
+export type MemoryRotationAction = 'archive' | 'delete-candidate';
+export interface MemoryRotationCandidate {
+    name: string;
+    filePath: string;
+    tier: MemoryRotationTier;
+    tierReason: string;
+    action: MemoryRotationAction;
+    reason: string;
+    ageDays: number;
+    ageBasis: 'frontmatter' | 'mtime';
+}
+export interface MemoryRotationExcluded {
+    name: string;
+    filePath: string;
+    tier: MemoryRotationTier;
+    reason: string;
+}
+export interface MemoryRotationReport {
+    apply: boolean;
+    projectRoot: string;
+    memoryDir: string;
+    archivedDir: string;
+    retentionMonths: number;
+    referenceRoots: string[];
+    /** Every memory file on disk, bucketed by resolved tier. */
+    tierCounts: Record<MemoryRotationTier, number>;
+    /** Concrete actionable list: tier-C archives + tier-D delete-candidates. */
+    candidates: MemoryRotationCandidate[];
+    /** Paths actually moved into `archived/` (apply only). */
+    archived: string[];
+    /** Candidates dropped by a safety gate, each with the reason. */
+    excluded: MemoryRotationExcluded[];
+    /** True when `--apply` declined to act. */
+    refused: boolean;
+    refusalReasons: string[];
+    /** Safety-gate failures that block `--apply` (e.g. unverifiable grep root). */
+    gateFailures: string[];
+    warnings: string[];
+}
+export interface MemoryRotateOptions {
+    projectRoot: string;
+    apply?: boolean;
+    /** Override the retention window (months). Defaults to 6. */
+    retentionMonths?: number;
+    /** Override the reference-grep roots (tests). Defaults to `<root>/src`, `<root>/skills`. */
+    referenceRoots?: string[];
+    /** Injectable clock (tests). */
+    now?: Date;
+}
+/**
+ * Read an explicit tier from raw frontmatter. Accepts nested
+ * `metadata.tier:` and top-level `tier:`; first valid value wins.
+ */
+export declare function readExplicitTier(frontmatter: string): MemoryRotationTier | null;
+/**
+ * Resolve the age of a memory. Prefers a frontmatter `updatedAt:` /
+ * `updated:` / `modified:` ISO date; falls back to file mtime. Returns the
+ * basis so the report can state which was used.
+ */
+export declare function resolveMemoryAge(frontmatter: string, filePath: string): {
+    date: Date;
+    basis: 'frontmatter' | 'mtime';
+};
+/**
+ * Whether a memory is pinned in the generated `MEMORY.md` index. Pinning is
+ * substring-based on the filename stem: the generated index links every
+ * entry as `[<name>](<file>.md)`, so a stem hit means the entry is surfaced.
+ */
+export declare function isPinnedInMemoryIndex(memoryIndexText: string, stem: string): boolean;
+/**
+ * Reference grep: does any file under the given roots mention the memory's
+ * filename stem? Returns the matching absolute paths (sorted, deduped).
+ * A missing root is NOT silently a pass — the caller turns that into a gate
+ * failure so `--apply` refuses rather than archiving an unverified memory.
+ */
+export declare function findReferenceHits(stem: string, roots: readonly string[]): string[];
+/**
+ * Plan (and with `apply: true`, perform) a tier-driven rotation pass.
+ * Always returns the full envelope; `apply` only controls whether tier-C
+ * archives are moved.
+ */
+export declare function executeMemoryRotate(options: MemoryRotateOptions): MemoryRotationReport;

package/dist/services/memory/memory-rotate-service.js

@@ -0,0 +1,373 @@
+// ---------------------------------------------------------------------------
+// `peaks memory rotate` — tier-driven retention for `.peaks/memory/`.
+//
+// Implements the mechanism prescribed by
+// `.peaks/memory/2026-07-24-sediment-pruning-policy.md` (tier 1: archive
+// only, never hard-delete). The policy shipped without a mechanism; this
+// service is that mechanism.
+//
+// Retention: 6 months (user override 2026-09-10 — the policy's original 12
+// months is superseded). See `MEMORY_ROTATION_RETENTION_MONTHS`.
+//
+// Tier assignment (first match wins):
+//   1. explicit `metadata.tier: A|B|C|D` (or top-level `tier:`) — wins.
+//   2. file already under `archived/`                        → D
+//   3. pinned in `MEMORY.md` (the policy's authoritative
+//      tier reference)                                       → B
+//   4. kind in {rule, convention, project-rule}              → A
+//   5. kind in {decision, reference, feedback, module,
+//               bug, investigation, technical-pattern}       → B
+//   6. everything else (retrospective-shaped, incl. no kind) → C
+//
+// Actions:
+//   - Tier C, older than the retention window, not pinned → archive (move
+//     into `.peaks/memory/archived/`). Age basis is frontmatter
+//     `updatedAt:` / `updated:` / `modified:` when parseable, else file
+//     mtime; every candidate reports which basis was used.
+//   - Tier D, not pinned → reported as a delete-candidate ONLY. Never
+//     deleted, even with `--apply` (tier-1 decision).
+//
+// Safety gates (all mandatory):
+//   - Tier A/B are never selected — an internal assertion turns a violation
+//     into a hard refusal rather than an archive.
+//   - Every candidate must pass a reference grep against `src/` + `skills/`;
+//     any hit excludes it with the referencing path.
+//   - `--apply` refuses when the candidate list is empty or any gate fails.
+//   - Dry-run is the default; nothing is written without `--apply`.
+//
+// Reads are fail-soft per file (an unreadable memory is reported, not
+// dropped). Writes are rename-only and never overwrite an existing archive.
+// ---------------------------------------------------------------------------
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { basename, join, relative, sep } from 'node:path';
+import { isInsidePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
+import { parseMemoryFrontmatter } from './project-memory-service/parsers/frontmatter.js';
+import { MEMORY_MD_FILENAME } from './project-memory-service/index/reindex.js';
+import { listMarkdownFiles } from './project-memory-service/index/search.js';
+import { assertSafeProjectMemoryDir, normalizeRoot } from './project-memory-service/store/paths.js';
+/** User override 2026-09-10: the policy's 12-month window is now 6 months. */
+export const MEMORY_ROTATION_RETENTION_MONTHS = 6;
+export const MEMORY_ROTATION_ARCHIVED_DIRNAME = 'archived';
+/** Default reference-grep roots, relative to the project root. */
+export const MEMORY_ROTATION_REFERENCE_ROOTS = ['src', 'skills'];
+/** Tier A — operational contracts. Never selected for rotation. */
+const TIER_A_KINDS = new Set(['rule', 'convention', 'project-rule']);
+/** Tier B — descriptive governance. Never selected for rotation. */
+const TIER_B_KINDS = new Set([
+    'decision',
+    'reference',
+    'feedback',
+    'module',
+    'bug',
+    'investigation',
+    'technical-pattern'
+]);
+const EXPLICIT_TIERS = new Set(['A', 'B', 'C', 'D']);
+/** Files we are willing to read during the reference grep. */
+const REFERENCE_SCAN_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.md', '.json', '.yaml', '.yml', '.txt'
+]);
+const REFERENCE_SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo'
+]);
+/** Bound the reference grep so a pathological tree cannot hang the command. */
+const REFERENCE_SCAN_MAX_FILES = 20_000;
+function isTier(value) {
+    return EXPLICIT_TIERS.has(value);
+}
+/**
+ * Read an explicit tier from raw frontmatter. Accepts nested
+ * `metadata.tier:` and top-level `tier:`; first valid value wins.
+ */
+export function readExplicitTier(frontmatter) {
+    let inMetadata = false;
+    for (const rawLine of frontmatter.split('\n')) {
+        const indented = /^\s/.test(rawLine);
+        const line = rawLine.trim();
+        if (!indented)
+            inMetadata = line === 'metadata:';
+        if (!line.startsWith('tier:'))
+            continue;
+        if (indented && !inMetadata)
+            continue; // nested tier must sit under `metadata:`
+        const value = line.slice('tier:'.length).trim().toUpperCase();
+        if (isTier(value))
+            return value;
+    }
+    return null;
+}
+/**
+ * Resolve the age of a memory. Prefers a frontmatter `updatedAt:` /
+ * `updated:` / `modified:` ISO date; falls back to file mtime. Returns the
+ * basis so the report can state which was used.
+ */
+export function resolveMemoryAge(frontmatter, filePath) {
+    for (const key of ['updatedAt', 'updated', 'modified']) {
+        const match = new RegExp(`^\\s*${key}:\\s*(\\S+)`, 'm').exec(frontmatter);
+        const raw = match?.[1];
+        if (raw === undefined)
+            continue;
+        const candidate = new Date(raw.slice(0, 10));
+        if (!Number.isNaN(candidate.getTime()))
+            return { date: candidate, basis: 'frontmatter' };
+    }
+    try {
+        return { date: statSync(filePath).mtime, basis: 'mtime' };
+    }
+    catch {
+        return { date: new Date(0), basis: 'mtime' };
+    }
+}
+/**
+ * Whether a memory is pinned in the generated `MEMORY.md` index. Pinning is
+ * substring-based on the filename stem: the generated index links every
+ * entry as `[<name>](<file>.md)`, so a stem hit means the entry is surfaced.
+ */
+export function isPinnedInMemoryIndex(memoryIndexText, stem) {
+    return stem.length > 0 && memoryIndexText.includes(stem);
+}
+/**
+ * Reference grep: does any file under the given roots mention the memory's
+ * filename stem? Returns the matching absolute paths (sorted, deduped).
+ * A missing root is NOT silently a pass — the caller turns that into a gate
+ * failure so `--apply` refuses rather than archiving an unverified memory.
+ */
+export function findReferenceHits(stem, roots) {
+    const hits = [];
+    if (stem.length === 0)
+        return hits;
+    const stack = [...roots];
+    let scanned = 0;
+    while (stack.length > 0 && scanned < REFERENCE_SCAN_MAX_FILES) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const entryPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (REFERENCE_SCAN_SKIP_DIRS.has(entry.name))
+                    continue;
+                stack.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const dotIndex = entry.name.lastIndexOf('.');
+            if (dotIndex < 0 || !REFERENCE_SCAN_EXTENSIONS.has(entry.name.slice(dotIndex)))
+                continue;
+            if (++scanned > REFERENCE_SCAN_MAX_FILES)
+                break;
+            try {
+                if (readFileSync(entryPath, 'utf8').includes(stem))
+                    hits.push(entryPath);
+            }
+            catch {
+                // Unreadable file: cannot prove absence, cannot prove presence.
+                // Treat as a hit so the candidate is excluded (fail-safe).
+                hits.push(entryPath);
+            }
+        }
+    }
+    return hits.sort((left, right) => left.localeCompare(right));
+}
+function resolveTier(input) {
+    if (input.explicitTier !== null) {
+        return { tier: input.explicitTier, reason: `explicit metadata.tier: ${input.explicitTier}` };
+    }
+    if (input.underArchived) {
+        return { tier: 'D', reason: 'already under archived/' };
+    }
+    // Pinning is the policy's authoritative tier reference (§2), so it wins
+    // over the kind heuristic. Pinned files are tier B — never selected.
+    if (input.pinned) {
+        return { tier: 'B', reason: 'pinned in MEMORY.md index' };
+    }
+    if (input.kind !== null && TIER_A_KINDS.has(input.kind)) {
+        return { tier: 'A', reason: `kind '${input.kind}' is an operational contract` };
+    }
+    if (input.kind !== null && TIER_B_KINDS.has(input.kind)) {
+        return { tier: 'B', reason: `kind '${input.kind}' is descriptive governance` };
+    }
+    if (input.kind !== null) {
+        return { tier: 'C', reason: `kind '${input.kind}' is retrospective-shaped` };
+    }
+    return { tier: 'C', reason: 'no resolvable kind; treated as retrospective (C)' };
+}
+function emptyTierCounts() {
+    return { A: 0, B: 0, C: 0, D: 0 };
+}
+/**
+ * Plan (and with `apply: true`, perform) a tier-driven rotation pass.
+ * Always returns the full envelope; `apply` only controls whether tier-C
+ * archives are moved.
+ */
+export function executeMemoryRotate(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const apply = options.apply ?? false;
+    const retentionMonths = options.retentionMonths ?? MEMORY_ROTATION_RETENTION_MONTHS;
+    const memoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const archivedDir = join(memoryDir, MEMORY_ROTATION_ARCHIVED_DIRNAME);
+    const now = options.now ?? new Date();
+    const referenceRoots = options.referenceRoots
+        ?? MEMORY_ROTATION_REFERENCE_ROOTS.map((root) => join(projectRoot, root));
+    const report = {
+        apply,
+        projectRoot,
+        memoryDir,
+        archivedDir,
+        retentionMonths,
+        referenceRoots,
+        tierCounts: emptyTierCounts(),
+        candidates: [],
+        archived: [],
+        excluded: [],
+        refused: false,
+        refusalReasons: [],
+        gateFailures: [],
+        warnings: []
+    };
+    const memoryIndexPath = join(memoryDir, MEMORY_MD_FILENAME);
+    let memoryIndexText = '';
+    if (existsSync(memoryIndexPath)) {
+        try {
+            memoryIndexText = readFileSync(memoryIndexPath, 'utf8');
+        }
+        catch {
+            report.warnings.push(`Could not read ${MEMORY_MD_FILENAME}; pinning cannot be detected.`);
+        }
+    }
+    else {
+        report.warnings.push(`No ${MEMORY_MD_FILENAME} found; no memory is treated as pinned.`);
+    }
+    const stableMemoryDir = existsSync(memoryDir) ? stableRealPath(memoryDir) : null;
+    const archivedPrefix = `${archivedDir}${sep}`;
+    const cutoff = new Date(now);
+    cutoff.setMonth(cutoff.getMonth() - retentionMonths);
+    const diskFiles = listMarkdownFiles(memoryDir).filter((filePath) => basename(filePath) !== MEMORY_MD_FILENAME);
+    for (const filePath of diskFiles) {
+        const stem = basename(filePath, '.md');
+        let content;
+        try {
+            content = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            report.excluded.push({ name: stem, filePath, tier: 'C', reason: 'file could not be read' });
+            continue;
+        }
+        const parsed = parseMemoryFrontmatter(content);
+        const kind = parsed.kind.kind;
+        const underArchived = filePath.startsWith(archivedPrefix);
+        const pinned = isPinnedInMemoryIndex(memoryIndexText, stem);
+        const explicitTier = readExplicitTier(parsed.frontmatter);
+        const { tier, reason: tierReason } = resolveTier({ explicitTier, underArchived, pinned, kind });
+        report.tierCounts[tier] += 1;
+        // Safety gate 1: tier A/B are never selected. Pinned files are reported
+        // (the interesting case); unpinned A/B files are simply not candidates.
+        if (tier === 'A' || tier === 'B') {
+            if (pinned) {
+                report.excluded.push({ name: parsed.name ?? stem, filePath, tier, reason: 'pinned in MEMORY.md index' });
+            }
+            continue;
+        }
+        const { date, basis } = resolveMemoryAge(parsed.frontmatter, filePath);
+        const ageDays = Math.max(0, Math.floor((now.getTime() - date.getTime()) / 86_400_000));
+        if (tier === 'D') {
+            // Report-only: never deleted, even with --apply (tier-1 decision).
+            report.candidates.push({
+                name: parsed.name ?? stem,
+                filePath,
+                tier,
+                tierReason,
+                action: 'delete-candidate',
+                reason: 'tier D (ephemeral/archived) — reported as a delete-candidate only; peaks never deletes',
+                ageDays,
+                ageBasis: basis
+            });
+            continue;
+        }
+        // Tier C from here on.
+        if (date.getTime() >= cutoff.getTime()) {
+            continue; // within the retention window — not a candidate yet
+        }
+        if (pinned) {
+            report.excluded.push({ name: parsed.name ?? stem, filePath, tier, reason: 'pinned in MEMORY.md index' });
+            continue;
+        }
+        const hits = findReferenceHits(stem, referenceRoots);
+        if (hits.length > 0) {
+            const preview = hits.slice(0, 2).map((hit) => relative(projectRoot, hit).replaceAll('\\', '/')).join(', ');
+            report.excluded.push({
+                name: parsed.name ?? stem,
+                filePath,
+                tier,
+                reason: `referenced by ${hits.length} file(s) (${preview}${hits.length > 2 ? ', …' : ''})`
+            });
+            continue;
+        }
+        report.candidates.push({
+            name: parsed.name ?? stem,
+            filePath,
+            tier,
+            tierReason,
+            action: 'archive',
+            reason: `tier C, ${ageDays} days old (${basis}) > ${retentionMonths}-month retention`,
+            ageDays,
+            ageBasis: basis
+        });
+    }
+    // Safety gate 2: every reference root must be verifiable before applying.
+    for (const root of referenceRoots) {
+        if (!existsSync(root)) {
+            report.gateFailures.push(`reference-grep root not found: ${root}`);
+        }
+    }
+    const archiveCandidates = report.candidates.filter((candidate) => candidate.action === 'archive');
+    if (apply) {
+        if (report.candidates.length === 0) {
+            report.refused = true;
+            report.refusalReasons.push('no rotation candidates; refusing to apply an empty plan');
+        }
+        if (report.gateFailures.length > 0) {
+            report.refused = true;
+            report.refusalReasons.push(...report.gateFailures);
+        }
+        if (!report.refused && archiveCandidates.length > 0) {
+            mkdirSync(archivedDir, { recursive: true });
+            const stableArchivedDir = stableRealPath(archivedDir);
+            for (const candidate of archiveCandidates) {
+                const source = stablePath(resolveInputPath(candidate.filePath));
+                if (stableMemoryDir === null || !isInsidePath(source, stableMemoryDir)) {
+                    report.gateFailures.push(`candidate escapes the memory directory: ${candidate.filePath}`);
+                    report.refused = true;
+                    report.refusalReasons.push(`candidate escapes the memory directory: ${candidate.filePath}`);
+                    break;
+                }
+                const destination = join(archivedDir, basename(candidate.filePath));
+                const stableDestination = stablePath(resolveInputPath(destination));
+                if (!isInsidePath(stableDestination, stableArchivedDir)) {
+                    report.gateFailures.push(`archive destination escapes archived/: ${destination}`);
+                    report.refused = true;
+                    report.refusalReasons.push(`archive destination escapes archived/: ${destination}`);
+                    break;
+                }
+                if (existsSync(destination)) {
+                    report.excluded.push({
+                        name: candidate.name,
+                        filePath: candidate.filePath,
+                        tier: candidate.tier,
+                        reason: `archive destination already exists: ${basename(destination)}`
+                    });
+                    continue;
+                }
+                renameSync(candidate.filePath, destination);
+                report.archived.push(destination);
+            }
+        }
+    }
+    return report;
+}