peaks-loop 4.0.34 → 4.0.36

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

package/dist/services/memory/project-memory-service/index/ranking.d.ts

@@ -1,6 +1,14 @@
 import type { MemoryIndex } from '../types.js';
 export declare function readMemoryFileMtime(filePath: string): string;
 export declare function readStoredMemoryNames(memoryDir: string): Set<string>;
-export declare function generateMemoryIndexFile(projectRoot: string, memoryDir: string, indexPath: string): void;
+/**
+ * Build the hot/warm index object from the current `.peaks/memory/` contents
+ * without touching disk. Pure read + in-memory assembly; `generateMemoryIndexFile`
+ * serializes the result. Exposed so `peaks memory reindex` can reuse the exact
+ * same entry construction for its counts + `MEMORY.md` regeneration instead of
+ * duplicating it.
+ */
+export declare function buildMemoryIndex(projectRoot: string): MemoryIndex;
+export declare function generateMemoryIndexFile(projectRoot: string, memoryDir: string, indexPath: string, prebuilt?: MemoryIndex): void;
 export declare function readExistingIndex(indexPath: string): MemoryIndex | null;
 export declare function readMemoryIndex(projectRoot: string): MemoryIndex | null;

package/dist/services/memory/project-memory-service/index/ranking.js

@@ -4,9 +4,9 @@
 // The memory index is the always-available summary of every memory in
 // `.peaks/memory/`. This module owns its write path:
 //
-//   - `HOT_KINDS` — the kinds whose full body is kept in the index
-//     (`feedback`, `decision`, `rule`, `convention`, `module`, `lesson`).
-//     Anything not in `HOT_KINDS` lands in `warm` with the same shape.
+//   - `HOT_KINDS` — the kinds whose full body is kept in the index,
+//     derived from `MEMORY_KIND_TIER` in `../types.ts`. Anything not in
+//     `HOT_KINDS` lands in `warm` with the same shape.
 //   - `readMemoryFileMtime` / `readStoredMemoryNames` — small stat /
 //     filename helpers used by the index generator and by the slug-
 //     collision idempotency check.
@@ -22,12 +22,13 @@
 // ---------------------------------------------------------------------------
 import { closeSync, constants, existsSync, openSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS } from '../types.js';
 import { parseStoredMemoryFile } from '../parsers/frontmatter.js';
 import { summarizeMemoryBody } from '../parsers/markdown-pure.js';
 import { assertSafeProjectMemoryDir, normalizeRoot } from '../store/paths.js';
 import { ensureMemoryBootstrap, listMarkdownFiles, readProjectMemories } from './search.js';
-// Hot kinds: full body kept in index for always-available context
-const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module', 'lesson']);
+// Hot kinds: full body kept in index for always-available context.
+const HOT_KINDS = new Set(HOT_MEMORY_KINDS);
 export function readMemoryFileMtime(filePath) {
     try {
         return statSync(filePath).mtime.toISOString().slice(0, 10);
@@ -60,14 +61,22 @@ export function readStoredMemoryNames(memoryDir) {
     }
     return names;
 }
-export function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
+/**
+ * Build the hot/warm index object from the current `.peaks/memory/` contents
+ * without touching disk. Pure read + in-memory assembly; `generateMemoryIndexFile`
+ * serializes the result. Exposed so `peaks memory reindex` can reuse the exact
+ * same entry construction for its counts + `MEMORY.md` regeneration instead of
+ * duplicating it.
+ */
+export function buildMemoryIndex(projectRoot) {
     const memories = readProjectMemories(projectRoot);
-    const hot = {
-        feedback: [], decision: [], rule: [], convention: [], module: [], lesson: []
-    };
-    const warm = {
-        project: [], reference: []
-    };
+    // Full-shape hot/warm buckets, derived from the canonical tier map so a
+    // newly accepted kind cannot be silently absent from the index.
+    const hot = {};
+    const warm = {};
+    for (const kind of PROJECT_MEMORY_KINDS) {
+        (MEMORY_KIND_TIER[kind] === 'hot' ? hot : warm)[kind] = [];
+    }
     for (const memory of memories.memories) {
         const entry = {
             name: memory.name,
@@ -89,12 +98,15 @@ export function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
         if (arr)
             arr.sort((a, b) => a.name.localeCompare(b.name));
     }
-    const index = {
+    return {
         version: 1,
         updatedAt: new Date().toISOString(),
         hot: hot,
         warm: warm
     };
+}
+export function generateMemoryIndexFile(projectRoot, memoryDir, indexPath, prebuilt) {
+    const index = prebuilt ?? buildMemoryIndex(projectRoot);
     const fd = openSync(indexPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, 0o644);
     try {
         writeFileSync(fd, JSON.stringify(index, null, 2), 'utf8');

package/dist/services/memory/project-memory-service/index/reindex.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryIndex, ProjectMemoryKind } from '../types.js';
+/** Marker line that owns `MEMORY.md`. Anything above it is machine output. */
+export declare const MEMORY_MD_BANNER = "<!-- generated by `peaks memory reindex` \u2014 do not edit -->";
+/** `MEMORY.md` is the generated index itself — never a memory source. */
+export declare const MEMORY_MD_FILENAME = "MEMORY.md";
+/**
+ * Deterministic section order for the generated `MEMORY.md`: hot kinds
+ * first (mirrors `HOT_KINDS` in `ranking.ts`), warm kinds last. Derived
+ * from the insertion order of `MEMORY_KIND_TIER` so the vocabulary has
+ * exactly one definition.
+ */
+export declare const KIND_ORDER: readonly ProjectMemoryKind[];
+export interface ReindexUnclassified {
+    name: string;
+    filePath: string;
+    /** The first raw type/kind value found in the frontmatter (null when absent). */
+    rawKind: string | null;
+    reason: string;
+}
+export interface ReindexOrphanEntry {
+    name: string;
+    kind: string;
+    /** The `sourcePath` recorded in the previous index that no longer exists on disk. */
+    sourcePath: string;
+}
+/**
+ * Two or more different files resolve to the same memory name (after the
+ * `name:` → `title:` → filename-stem fallback chain). Reported, never
+ * resolved by overwriting: both files keep their own index entry, and the
+ * collision is surfaced so a human/LLM can rename one of them.
+ */
+export interface ReindexNameConflict {
+    name: string;
+    /** Every file that resolves to this name, sorted. Always length >= 2. */
+    filePaths: string[];
+}
+export interface MemoryReindexReport {
+    apply: boolean;
+    projectRoot: string;
+    memoryDir: string;
+    indexPath: string;
+    memoryMdPath: string;
+    /** Markdown files scanned (excludes the generated `MEMORY.md`). */
+    scannedFiles: number;
+    /** Files represented in the rebuilt index. */
+    indexed: number;
+    indexedByKind: Record<string, number>;
+    /** Files on disk with no resolvable kind — reported, never invented. */
+    unclassified: ReindexUnclassified[];
+    /** Distinct files that resolve to the same index name — reported, never overwritten. */
+    nameConflicts: ReindexNameConflict[];
+    /** Previous index entries whose `sourcePath` no longer exists (error-class drift). */
+    orphanIndex: ReindexOrphanEntry[];
+    /** Files on disk that the rebuilt index does not contain (warn-class drift). */
+    orphanDisk: string[];
+    memoryMd: {
+        path: string;
+        regenerated: boolean;
+    };
+    writtenFiles: string[];
+}
+export interface MemoryReindexOptions {
+    projectRoot: string;
+    apply?: boolean;
+}
+/**
+ * Render the human/LLM-facing `MEMORY.md` from a built index. Deterministic:
+ * kinds in `KIND_ORDER`, entries sorted by name, no timestamps.
+ */
+export declare function renderMemoryMarkdown(index: MemoryIndex, memoryDir: string): string;
+/**
+ * Rebuild `.peaks/memory/index.json` from disk and (on `--apply`) regenerate
+ * `MEMORY.md`. Always returns the drift report, even on a dry run.
+ */
+export declare function executeMemoryReindex(options: MemoryReindexOptions): MemoryReindexReport;