peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,24 @@
+// ---------------------------------------------------------------------------
+// Public facade for the project-memory-service split.
+//
+// Downstream callers (CLI commands, audit writers, presence service,
+// search services) import from `'../memory/project-memory-service.js'`. This
+// module re-exports every public function / type / constant from the
+// parsers/, store/, and index/ submodules, so the existing import path
+// keeps working unchanged.
+//
+// The 8-kind union, all result / plan types, and the index types live in
+// `./types.ts` and are re-exported here.
+// ---------------------------------------------------------------------------
+export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
+// Pure markdown helpers
+export { summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
+// Frontmatter parser + renderer
+export { parseBlock, parseStoredMemoryFile, renderMemoryFile, slugify } from './parsers/frontmatter.js';
+// Store: path safety + sensitive content
+export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
+export { assertSafeMemory, assertSafeMemoryFileContent, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';
+// Index: search / ranking / dispatch
+export { ensureMemoryBootstrap, emptyByKind, emptyIndex, listMarkdownFiles, readProjectMemories, readProjectMemoryBody } from './index/search.js';
+export { generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
+export { createProjectMemoryBackupPlan, createProjectMemoryExtractPlan, executeProjectMemoryBackup, executeProjectMemoryExtract, extractSessionMemories, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from './index/kind-dispatch.js';

package/dist/services/memory/project-memory-service/parsers/frontmatter.d.ts

@@ -0,0 +1,9 @@
+import type { ExtractedProjectMemory, ProjectMemoryKind, StoredProjectMemory } from '../types.js';
+export declare const VALID_MEMORY_KINDS: Set<ProjectMemoryKind>;
+/** Exported for guard tests + tooling that needs to enumerate the valid
+ *  set without duplicating the literal. Single source of truth. */
+export declare const VALID_PROJECT_MEMORY_KINDS: readonly ProjectMemoryKind[];
+export declare function slugify(title: string): string;
+export declare function parseBlock(block: string, sourceArtifact: string): ExtractedProjectMemory | null;
+export declare function renderMemoryFile(memory: ExtractedProjectMemory): string;
+export declare function parseStoredMemoryFile(content: string, filePath: string): StoredProjectMemory | null;

package/dist/services/memory/project-memory-service/parsers/frontmatter.js

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// Frontmatter parser + renderer for project memory files.
+//
+// Two surface shapes live here:
+//
+//   1. `parseBlock` / `renderMemoryFile` — extract-path side. We get raw
+//      markdown body content delimited by `<!-- peaks-memory:start -->` /
+//      `<!-- peaks-memory:end -->` markers with a YAML-ish header at the top
+//      (title, kind) and a `---` separator before the body.
+//
+//   2. `parseStoredMemoryFile` — read-path side. Files in `.peaks/memory/`
+//      are stored as standard YAML frontmatter (name / description /
+//      metadata.type / metadata.sourceArtifact) followed by the body.
+//
+// Both parsers share the 8-kind `VALID_MEMORY_KINDS` allow-list and the
+// `slugify` helper used to derive filenames from titles.
+// ---------------------------------------------------------------------------
+export const VALID_MEMORY_KINDS = new Set([
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson'
+]);
+/** Exported for guard tests + tooling that needs to enumerate the valid
+ *  set without duplicating the literal. Single source of truth. */
+export const VALID_PROJECT_MEMORY_KINDS = Array.from(VALID_MEMORY_KINDS);
+export function slugify(title) {
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug : 'project-memory';
+}
+export function parseBlock(block, sourceArtifact) {
+    const normalizedBlock = block.replace(/\r\n/g, '\n');
+    const separatorIndex = normalizedBlock.indexOf('\n---\n');
+    if (separatorIndex < 0)
+        return null;
+    const header = normalizedBlock.slice(0, separatorIndex).trim();
+    const body = normalizedBlock.slice(separatorIndex + '\n---\n'.length).trim();
+    const fields = new Map();
+    for (const line of header.split('\n')) {
+        const [key, ...valueParts] = line.split(':');
+        const normalizedKey = key?.trim();
+        const value = valueParts.join(':').trim();
+        if (normalizedKey && value) {
+            fields.set(normalizedKey, value);
+        }
+    }
+    const title = fields.get('title')?.trim();
+    const kind = fields.get('kind')?.trim();
+    if (!title || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+        return null;
+    return { title, kind, body, sourceArtifact };
+}
+export function renderMemoryFile(memory) {
+    const name = slugify(memory.title);
+    return [
+        '---',
+        `name: ${name}`,
+        `description: ${memory.title}`,
+        'metadata:',
+        `  type: ${memory.kind}`,
+        `  sourceArtifact: ${memory.sourceArtifact}`,
+        '---',
+        '',
+        memory.body,
+        ''
+    ].join('\n');
+}
+export function parseStoredMemoryFile(content, filePath) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return null;
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex < 0)
+        return null;
+    const frontmatter = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    let name;
+    let description;
+    let kind;
+    let sourceArtifact;
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('name:'))
+            name = line.slice('name:'.length).trim();
+        else if (line.startsWith('description:'))
+            description = line.slice('description:'.length).trim();
+        else if (line.startsWith('type:'))
+            kind = line.slice('type:'.length).trim();
+        else if (line.startsWith('sourceArtifact:'))
+            sourceArtifact = line.slice('sourceArtifact:'.length).trim();
+    }
+    if (!name || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+        return null;
+    return {
+        name,
+        title: description ?? name,
+        kind: kind,
+        sourceArtifact: sourceArtifact && sourceArtifact !== 'undefined' ? sourceArtifact : null,
+        body,
+        filePath
+    };
+}

package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts

@@ -0,0 +1,7 @@
+import type { ExtractedProjectMemory, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryExtractResult, ProjectMemoryExtractSummary } from '../types.js';
+export declare const START_MARKER = "<!-- peaks-memory:start -->";
+export declare const END_MARKER = "<!-- peaks-memory:end -->";
+export declare function summarizeMemoryBody(body: string): string;
+export declare function extractStableProjectMemories(content: string, sourceArtifact: string): ExtractedProjectMemory[];
+export declare function summarizeExtractResult(result: ProjectMemoryExtractResult): ProjectMemoryExtractSummary;
+export declare function summarizeBackupResult(result: ProjectMemoryBackupResult): ProjectMemoryBackupSummary;

package/dist/services/memory/project-memory-service/parsers/markdown-pure.js

@@ -0,0 +1,96 @@
+// ---------------------------------------------------------------------------
+// Pure (no-filesystem) markdown helpers used by the extract + summarize paths.
+//
+// Three concerns live here:
+//
+//   1. `extractStableProjectMemories` — top-level entry point called by
+//      `peaks memory extract --apply` / `--dry-run`. Walks an artifact's
+//      text, finds every `<!-- peaks-memory:start/end -->` block, and
+//      hands each one to the frontmatter parser. Sorted output is part of
+//      the contract (callers rely on deterministic order).
+//
+//   2. `summarizeMemoryBody` — deterministic one-sentence summary used to
+//      populate `MemoryIndexEntry.description`. No LLM call, just markdown
+//      strip + sentence selection + length truncation.
+//
+//   3. `summarizeExtractResult` / `summarizeBackupResult` — projector
+//      functions that take the rich extract / backup plan and trim it down
+//      to the small JSON-friendly shape consumed by the CLI layer.
+//
+// No filesystem imports. Pure functions only — easy to unit-test.
+// ---------------------------------------------------------------------------
+import { assertSafeMemory } from '../store/atomic-write.js';
+import { parseBlock, slugify } from './frontmatter.js';
+export const START_MARKER = '<!-- peaks-memory:start -->';
+export const END_MARKER = '<!-- peaks-memory:end -->';
+// Length bounds for index entry descriptions. The numbers were chosen when
+// summarizeMemoryBody was first introduced; locking them in as named
+// constants is a doc-as-code move so the truncation rule is no longer
+// "magic". Bump MAX_DESCRIPTION_LENGTH deliberately if downstream UIs grow.
+const MIN_BODY_SENTENCE_LENGTH = 20; // skip fragments shorter than this when picking a leading sentence
+const MAX_DESCRIPTION_LENGTH = 120; // hard cap on description length in the memory index entry
+const ELLIPSIS_RESERVE = 3; // length of the trailing "..." when truncating with an ellipsis
+export function summarizeMemoryBody(body) {
+    const cleaned = body
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/`{1,3}[^`]*`{1,3}/g, '')
+        .replace(/^\s*[-*+]\s+/gm, '')
+        .replace(/\n+/g, ' ')
+        .trim();
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > MIN_BODY_SENTENCE_LENGTH && !/^\[.+\]$/.test(s));
+    if (sentences.length === 0) {
+        return cleaned.slice(0, MAX_DESCRIPTION_LENGTH) || 'Project memory';
+    }
+    const first = sentences[0];
+    if (first.length <= MAX_DESCRIPTION_LENGTH) {
+        return first;
+    }
+    return first.slice(0, MAX_DESCRIPTION_LENGTH - ELLIPSIS_RESERVE) + '...';
+}
+export function extractStableProjectMemories(content, sourceArtifact) {
+    const memories = [];
+    let searchStart = 0;
+    while (searchStart < content.length) {
+        const start = content.indexOf(START_MARKER, searchStart);
+        if (start < 0)
+            break;
+        const bodyStart = start + START_MARKER.length;
+        const end = content.indexOf(END_MARKER, bodyStart);
+        if (end < 0)
+            break;
+        const memory = parseBlock(content.slice(bodyStart, end).trim(), sourceArtifact);
+        if (memory) {
+            assertSafeMemory(memory);
+            memories.push(memory);
+        }
+        searchStart = end + END_MARKER.length;
+    }
+    return memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
+}
+export function summarizeExtractResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupPolicy: result.backupPolicy,
+        extractedCount: result.extractedMemories.length,
+        plannedWrites: result.plannedWrites.map((write) => ({
+            filePath: write.filePath,
+            title: write.memory.title,
+            kind: write.memory.kind,
+            sourceArtifact: write.memory.sourceArtifact
+        })),
+        writtenFiles: result.writtenFiles
+    };
+}
+export function summarizeBackupResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        artifactWorkspacePath: result.artifactWorkspacePath,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupMemoryDir: result.backupMemoryDir,
+        plannedCopies: result.plannedCopies,
+        copiedFiles: result.copiedFiles
+    };
+}

package/dist/services/memory/project-memory-service/store/atomic-write.d.ts

@@ -0,0 +1,5 @@
+import type { ExtractedProjectMemory } from '../types.js';
+export declare function hasSensitiveMemoryContent(content: string): boolean;
+export declare function assertSafeMemory(memory: ExtractedProjectMemory): void;
+export declare function assertSafeMemoryFileContent(content: string): void;
+export declare function writeNewFile(path: string, content: string): void;

package/dist/services/memory/project-memory-service/store/atomic-write.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Sensitive-content + write helpers for the project memory store.
+//
+//   - `hasSensitiveMemoryContent` — pattern check for api keys, tokens,
+//     PEM private keys, JWTs, GitHub / GitLab tokens, AWS access keys. Used
+//     both by the extract path (`assertSafeMemory`) and the backup path
+//     (`assertSafeMemoryFileContent`).
+//   - `assertSafeMemory` — full safety gate applied during extraction.
+//     Combines title/body content scan + config-service secret check +
+//     sensitive-path check on the title.
+//   - `assertSafeMemoryFileContent` — lighter version for backup: just
+//     the content pattern scan, since the file already lives in
+//     `.peaks/memory/` and was authored through the normal pipeline.
+//   - `writeNewFile` — `O_EXCL` create-and-write via `openSync`. Atomic
+//     with respect to other writers (no overwrite), used both for fresh
+//     memory writes and (with the O_TRUNC variant inside `ranking.ts`)
+//     for index.json regeneration.
+// ---------------------------------------------------------------------------
+import { closeSync, constants, openSync, writeFileSync } from 'node:fs';
+import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../../../config/config-service.js';
+export function hasSensitiveMemoryContent(content) {
+    return /(?:api[_-]?key|token|secret|password|credential|bearer)\s*[:=]/i.test(content)
+        || /\bauthorization\s*:\s*bearer\s+\S+/i.test(content)
+        || /\bbearer\s+[A-Za-z0-9._~+/=-]{12,}\b/i.test(content)
+        || /\bsk-[A-Za-z0-9_-]{6,}\b/.test(content)
+        || /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/.test(content)
+        || /\bgithub_pat_[A-Za-z0-9_]{20,}\b/.test(content)
+        || /\bglpat-[A-Za-z0-9_-]{20,}\b/.test(content)
+        || /\bAKIA[0-9A-Z]{16}\b/.test(content)
+        || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)
+        || /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(content);
+}
+export function assertSafeMemory(memory) {
+    const content = `${memory.title}\n${memory.kind}\n${memory.body}`;
+    const metadata = { title: memory.title, kind: memory.kind, body: memory.body };
+    if (containsSensitiveConfigValue(metadata) || hasSensitiveMemoryContent(content)) {
+        throw new Error('Refusing to store sensitive memory content');
+    }
+    if (isSensitiveConfigPath(memory.title)) {
+        throw new Error('Refusing to store sensitive memory content');
+    }
+}
+export function assertSafeMemoryFileContent(content) {
+    if (hasSensitiveMemoryContent(content)) {
+        throw new Error('Refusing to back up sensitive memory content');
+    }
+}
+export function writeNewFile(path, content) {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        writeFileSync(fd, content, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/services/memory/project-memory-service/store/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function normalizeRoot(path: string): string;
+export declare function normalizeRealRoot(path: string): string;
+export declare function realPathOrThrow(path: string, errorMessage: string): string;
+export declare function resolveProjectPath(path: string, projectRoot: string): string;
+export declare function assertInsideProject(path: string, projectRoot: string): string;
+export declare function assertSafeProjectMemoryDir(projectRoot: string): string;
+export declare function safeRealpath(path: string): string | null;
+export declare function assertSafeSessionDir(projectRoot: string, sessionId: string): string;

package/dist/services/memory/project-memory-service/store/paths.js

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// Filesystem path safety helpers.
+//
+// All read/write paths in the project-memory-service flow through these
+// guards. The contract:
+//
+//   - `normalizeRoot` — collapses a caller-supplied project root into the
+//     canonical form the rest of the codebase expects (handles input-path
+//     quirks from the path-utils layer).
+//   - `realPathOrThrow` — refuses symlinks and missing paths. Throws with
+//     a stable message so callers can distinguish "missing" from "escape
+//     attempt".
+//   - `assertInsideProject` — confirms an artifact path resolves inside
+//     the project root after realpath, throwing the same kind of error
+//     message realPathOrThrow uses.
+//   - `assertSafeProjectMemoryDir` — confirms `.peaks/memory/` exists (or
+//     can be returned without creation) AND it is not a symlink and its
+//     realpath lives inside the project root. Returns the joined path.
+//   - `assertSafeSessionDir` — symmetric for `.peaks/_runtime/<sid>/`.
+//     Distinguishes benign "not found" (returns `SESSION_DIR_NOT_FOUND`
+//     sentinel message) from "escapes project root" (throws hard).
+//
+// All helpers are pure (no side effects other than throwing).
+// ---------------------------------------------------------------------------
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stableRealPath } from '../../../../shared/path-utils.js';
+import { getSessionDir } from '../../../session/getSessionDir.js';
+export function normalizeRoot(path) {
+    return resolveInputPath(path);
+}
+export function normalizeRealRoot(path) {
+    return stableRealPath(path);
+}
+export function realPathOrThrow(path, errorMessage) {
+    if (!existsSync(path)) {
+        throw new Error(errorMessage);
+    }
+    const stats = lstatSync(path);
+    if (stats.isSymbolicLink()) {
+        throw new Error(errorMessage);
+    }
+    return realpathSync(path);
+}
+export function resolveProjectPath(path, projectRoot) {
+    if (isWindowsAbsolutePath(path))
+        return normalizePath(path);
+    if (isAbsolute(path))
+        return resolve(path);
+    const resolvedPath = join(projectRoot, path);
+    return isWindowsAbsolutePath(projectRoot) ? normalizePath(resolvedPath) : resolve(resolvedPath);
+}
+export function assertInsideProject(path, projectRoot) {
+    const resolvedRoot = normalizeRoot(projectRoot);
+    const resolvedPath = resolveProjectPath(path, resolvedRoot);
+    const realProjectRoot = realPathOrThrow(resolvedRoot, 'Project root is not accessible');
+    const realArtifactPath = realPathOrThrow(resolvedPath, 'Artifact path must stay inside the project root');
+    if (!isInsidePath(realArtifactPath, realProjectRoot)) {
+        throw new Error('Artifact path must stay inside the project root');
+    }
+    return resolvedPath;
+}
+export function assertSafeProjectMemoryDir(projectRoot) {
+    const resolvedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const peaksDir = join(resolvedRoot, '.peaks');
+    if (existsSync(peaksDir) && lstatSync(peaksDir).isSymbolicLink()) {
+        throw new Error('Project memory directory must stay inside the project root');
+    }
+    const memoryDir = join(peaksDir, 'memory');
+    if (existsSync(memoryDir)) {
+        if (lstatSync(memoryDir).isSymbolicLink()) {
+            throw new Error('Project memory directory must stay inside the project root');
+        }
+        const realMemoryDir = realpathSync(memoryDir);
+        if (!isInsidePath(realMemoryDir, realRoot)) {
+            throw new Error('Project memory directory must stay inside the project root');
+        }
+        return memoryDir;
+    }
+    return memoryDir;
+}
+export function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function assertSafeSessionDir(projectRoot, sessionId) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const sessionDir = getSessionDir(normalizedRoot, sessionId);
+    if (!existsSync(sessionDir)) {
+        // Distinguish "not found" (caller will treat as no-op) from "escapes project
+        // root" (caller must surface a hard error). We probe by checking whether the
+        // joined path, after realpath, would still be inside the project root.
+        if (isAbsolute(getSessionDir(normalizedRoot, sessionId))) {
+            const realJoined = safeRealpath(getSessionDir(normalizedRoot, sessionId));
+            if (realJoined && !isInsidePath(realJoined, realRoot)) {
+                throw new Error('Session directory must stay inside the project root');
+            }
+        }
+        throw new Error('SESSION_DIR_NOT_FOUND');
+    }
+    const stats = lstatSync(sessionDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    const realSessionDir = realpathSync(sessionDir);
+    if (!isInsidePath(realSessionDir, realRoot)) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    return sessionDir;
+}

package/dist/services/memory/project-memory-service/types.d.ts

@@ -0,0 +1,128 @@
+export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module' | 'lesson';
+export type ExtractedProjectMemory = {
+    title: string;
+    kind: ProjectMemoryKind;
+    body: string;
+    sourceArtifact: string;
+};
+export type ProjectMemoryWrite = {
+    memory: ExtractedProjectMemory;
+    filePath: string;
+    content: string;
+};
+export type ProjectMemoryExtractPlan = {
+    apply: boolean;
+    projectRoot: string;
+    primaryMemoryDir: string;
+    backupPolicy: 'project-memory-primary-artifact-backup';
+    extractedMemories: ExtractedProjectMemory[];
+    plannedWrites: ProjectMemoryWrite[];
+};
+export type ProjectMemoryExtractResult = ProjectMemoryExtractPlan & {
+    writtenFiles: string[];
+};
+export type ProjectMemoryExtractSummary = {
+    apply: boolean;
+    projectRoot: string;
+    primaryMemoryDir: string;
+    backupPolicy: 'project-memory-primary-artifact-backup';
+    extractedCount: number;
+    plannedWrites: Array<{
+        filePath: string;
+        title: string;
+        kind: ProjectMemoryKind;
+        sourceArtifact: string;
+    }>;
+    writtenFiles: string[];
+};
+export type ProjectMemoryBackupSummary = {
+    apply: boolean;
+    projectRoot: string;
+    artifactWorkspacePath: string;
+    primaryMemoryDir: string;
+    backupMemoryDir: string;
+    plannedCopies: ProjectMemoryCopy[];
+    copiedFiles: string[];
+};
+export type ProjectMemoryCopy = {
+    sourcePath: string;
+    targetPath: string;
+};
+export type ProjectMemoryBackupPlan = {
+    apply: boolean;
+    projectRoot: string;
+    artifactWorkspacePath: string;
+    primaryMemoryDir: string;
+    backupMemoryDir: string;
+    plannedCopies: ProjectMemoryCopy[];
+};
+export type ProjectMemoryBackupResult = ProjectMemoryBackupPlan & {
+    copiedFiles: string[];
+};
+export type StoredProjectMemory = {
+    name: string;
+    title: string;
+    kind: ProjectMemoryKind;
+    sourceArtifact: string | null;
+    body: string;
+    filePath: string;
+};
+export type ProjectMemoryReadResult = {
+    projectRoot: string;
+    memoryDir: string;
+    total: number;
+    byKind: Record<ProjectMemoryKind, StoredProjectMemory[]>;
+    memories: StoredProjectMemory[];
+};
+export type MemoryIndexEntry = {
+    name: string;
+    kind: ProjectMemoryKind;
+    description: string;
+    sourcePath: string;
+    sourceArtifact: string | null;
+    updatedAt: string;
+};
+export type MemoryIndex = {
+    version: 1;
+    updatedAt: string;
+    hot: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+    warm: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+};
+export type ExtractSessionMemoriesOptions = {
+    projectRoot: string;
+    sessionId: string;
+    apply?: boolean;
+};
+export type ExtractSessionMemoriesResult = {
+    apply: boolean;
+    projectRoot: string;
+    sessionId: string;
+    primaryMemoryDir: string;
+    memoryIndexPath: string;
+    scannedFiles: number;
+    extractedCount: number;
+    writtenFiles: string[];
+    updatedIndex: boolean;
+};
+export type ProjectMemoryShowResult = {
+    projectRoot: string;
+    memoryDir: string;
+    name: string;
+    body: string;
+    filePath: string;
+    updatedAt: string | null;
+    kind: ProjectMemoryKind | null;
+    title: string;
+    /** Whether the on-disk body bytes are returned (true) or a compact form (false). */
+    pretty: boolean;
+};
+export type ExtractPlanOptions = {
+    projectRoot: string;
+    artifactPaths: string[];
+    apply?: boolean;
+};
+export type BackupPlanOptions = {
+    projectRoot: string;
+    artifactWorkspacePath: string;
+    apply?: boolean;
+};

package/dist/services/memory/project-memory-service/types.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+// Shared type definitions for the project-memory-service split.
+//
+// This module is the single home of every public type / interface that the
+// parsers/, store/, and index/ submodules exchange. Each submodule imports
+// from here, and the top-level `index.ts` re-exports them for back-compat
+// with downstream callers (CLI commands, audit writers, presence service).
+// ---------------------------------------------------------------------------
+export {};

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

@@ -0,0 +1 @@
+export * from './project-memory-service/index.js';

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

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// Thin back-compat shim.
+//
+// The original 1032-line project-memory-service.ts was split on 2026-07-26
+// (rid-003) into the `./project-memory-service/` submodule:
+//
+//   - parsers/frontmatter.ts          — YAML frontmatter parse + render
+//   - parsers/markdown-pure.ts        — extract / summarize (pure)
+//   - store/paths.ts                  — project-root + memory-dir safety
+//   - store/atomic-write.ts           — sensitive content + write helpers
+//   - index/search.ts                 — read-side enumeration + bootstrap
+//   - index/ranking.ts                — index.json generation + mtime guard
+//   - index/kind-dispatch.ts          — extract / backup / session dispatch
+//   - index.ts                        — public facade
+//
+// This file re-exports the entire facade so every existing import path
+// (`from '../memory/project-memory-service.js'`) keeps compiling and
+// behaving identically. New code should import from the submodule directly.
+// ---------------------------------------------------------------------------
+export * from './project-memory-service/index.js';

package/dist/services/migrate-skill-name/migrate.d.ts

@@ -0,0 +1,17 @@
+import type { MigrateResult } from './schema.js';
+export interface MigrateOpts {
+    projectRoot: string;
+    from: string;
+    to: string;
+    /** false = dry-run (default); true = write through. */
+    apply: boolean;
+}
+/** True iff `absPath` falls under any skip-path (substring match). */
+export declare function shouldSkip(projectRoot: string, absPath: string): boolean;
+/**
+ * Recursively walk a directory and return every `.json` / `.md`
+ * path. Missing root → empty list (the CLI reports scannedFiles:0,
+ * which is the truthful "nothing to look at" signal).
+ */
+export declare function walkRuntimeFiles(root: string): string[];
+export declare function migrateSkillName(opts: MigrateOpts): MigrateResult;