peaks-loop 4.0.34 → 4.0.36

package/dist/services/doctor/doctor-service/checks/l3-memory-health.js

@@ -1,6 +1,5 @@
 /**
- * Check: `.peaks/memory/index.json` is well-formed JSON
- * (`L3:l3-memory-health`).
+ * Checks for `.peaks/memory/` health (`L3:l3-memory-health` and siblings).
  *
  * Slice 2026-06-13-repair-pre-existing-test-failures: the
  * production MemoryIndex schema (see
@@ -11,12 +10,122 @@
  *
  * When no `.peaks/memory/index.json` exists yet, the check passes
  * (fresh project — no memories have been extracted).
+ *
+ * Slice 2026-09-09-memory-system-overhaul (D) extends the check with the
+ * drift findings the original version could not see. It used to report
+ * `ok: true` for "index.json is well-formed JSON; 100 hot + 131 warm" and
+ * never looked at coverage, orphans, or unclassified files. It now emits,
+ * in addition to the unchanged well-formed-JSON assertion:
+ *
+ *   - `L3:l3-memory-coverage`      — disk files vs indexed entries (warning
+ *                                    when the gap exceeds a small threshold)
+ *   - `L3:l3-memory-orphans`       — index entries whose `sourcePath` is gone
+ *                                    (error) + disk files absent from the
+ *                                    index (warning)
+ *   - `L3:l3-memory-unclassified`  — files with no resolvable kind (warning,
+ *                                    count + first N names)
+ *
+ * All three are read-only and fail-soft: an inspection error degrades to a
+ * single warning instead of throwing, and none of them change the id or the
+ * `ok` semantics of the original `L3:l3-memory-health` assertion.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { getErrorMessage } from 'peaks-loop-shared/result';
+import { listMarkdownFiles, MEMORY_MD_FILENAME, parseMemoryFrontmatter } from '../../../memory/project-memory-service/index.js';
+/** Warn when |disk - indexed| exceeds this. Small enough to catch real drift. */
+const COVERAGE_GAP_WARN_THRESHOLD = 2;
+/** How many offending names to inline before truncating the message. */
+const MAX_NAMES_IN_MESSAGE = 5;
+function countEntries(bucket) {
+    return Object.values(bucket ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+}
+function previewNames(names) {
+    const shown = names.slice(0, MAX_NAMES_IN_MESSAGE);
+    const suffix = names.length > shown.length ? ` (+${names.length - shown.length} more)` : '';
+    return shown.join(', ') + suffix;
+}
+function readIndexSourcePaths(indexPath) {
+    const parsed = JSON.parse(readFileSync(indexPath, 'utf8'));
+    const fromBucket = (bucket) => Object.values(bucket ?? {}).flatMap((arr) => (Array.isArray(arr) ? arr : []));
+    return [...fromBucket(parsed.hot), ...fromBucket(parsed.warm), ...(parsed.cold ?? [])];
+}
+function inspectDrift(memoryDir, memoryIndexPath, indexedCount) {
+    const checks = [];
+    const diskFiles = listMarkdownFiles(memoryDir).filter((filePath) => basename(filePath) !== MEMORY_MD_FILENAME);
+    // --- coverage ---------------------------------------------------------
+    const gap = diskFiles.length - indexedCount;
+    if (Math.abs(gap) > COVERAGE_GAP_WARN_THRESHOLD) {
+        const direction = gap > 0
+            ? `${gap} file(s) on disk are not in the index`
+            : `${-gap} index entr(ies) have no matching file`;
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: false,
+            severity: 'warning',
+            message: `Memory index coverage gap: ${diskFiles.length} file(s) on disk vs ${indexedCount} indexed — ${direction}. Run \`peaks memory reindex\` for the full drift report.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: true,
+            message: `Memory index coverage: ${diskFiles.length} file(s) on disk, ${indexedCount} indexed (within threshold ${COVERAGE_GAP_WARN_THRESHOLD})`
+        });
+    }
+    // --- orphans (both directions) ---------------------------------------
+    const missingSources = readIndexSourcePaths(memoryIndexPath)
+        .filter((entry) => typeof entry.sourcePath !== 'string' || entry.sourcePath.length === 0 || !existsSync(entry.sourcePath))
+        .map((entry) => entry.name ?? entry.sourcePath ?? '<unnamed>')
+        .sort((left, right) => left.localeCompare(right));
+    if (missingSources.length > 0) {
+        checks.push({
+            id: 'L3:l3-memory-orphans',
+            ok: false,
+            severity: 'error',
+            message: `${missingSources.length} index entr(ies) point at a missing sourcePath: ${previewNames(missingSources)}. Run \`peaks memory reindex\` to rebuild the index.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-orphans',
+            ok: true,
+            message: 'No memory index entries point at missing files'
+        });
+    }
+    // --- unclassified -----------------------------------------------------
+    const unclassified = [];
+    for (const filePath of diskFiles) {
+        try {
+            if (parseMemoryFrontmatter(readFileSync(filePath, 'utf8')).kind.kind === null) {
+                unclassified.push(basename(filePath, '.md'));
+            }
+        }
+        catch {
+            unclassified.push(`${basename(filePath, '.md')} (unreadable)`);
+        }
+    }
+    unclassified.sort((left, right) => left.localeCompare(right));
+    if (unclassified.length > 0) {
+        checks.push({
+            id: 'L3:l3-memory-unclassified',
+            ok: false,
+            severity: 'warning',
+            message: `${unclassified.length} memory file(s) have no resolvable kind (no metadata.type / kind / type): ${previewNames(unclassified)}. Add \`metadata.type\` then run \`peaks memory reindex\`.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-unclassified',
+            ok: true,
+            message: 'Every memory file on disk has a resolvable kind'
+        });
+    }
+    return checks;
+}
 function run({ resolvedL3Root }) {
-    const memoryIndexPath = join(resolvedL3Root, '.peaks/memory/index.json');
+    const memoryDir = join(resolvedL3Root, '.peaks/memory');
+    const memoryIndexPath = join(memoryDir, 'index.json');
     if (!existsSync(memoryIndexPath)) {
         return [{
                 id: 'L3:l3-memory-health',
@@ -24,32 +133,47 @@ function run({ resolvedL3Root }) {
                 message: 'No .peaks/memory/index.json yet (no memories extracted)'
             }];
     }
+    let parsed;
     try {
         const raw = readFileSync(memoryIndexPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        const schemaMarker = parsed.schema_version ?? parsed.version;
-        if (schemaMarker === undefined) {
-            return [{
-                    id: 'L3:l3-memory-health',
-                    ok: false,
-                    message: '.peaks/memory/index.json missing schema_version / version field'
-                }];
-        }
-        const hotCount = Object.values(parsed.hot ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
-        const warmCount = Object.values(parsed.warm ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+        parsed = JSON.parse(raw);
+    }
+    catch (parseError) {
         return [{
                 id: 'L3:l3-memory-health',
-                ok: true,
-                message: `.peaks/memory/index.json is well-formed JSON; version=${schemaMarker}; ${hotCount} hot + ${warmCount} warm memory entries`
+                ok: false,
+                message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
             }];
     }
-    catch (parseError) {
+    const schemaMarker = parsed.schema_version ?? parsed.version;
+    if (schemaMarker === undefined) {
         return [{
                 id: 'L3:l3-memory-health',
                 ok: false,
-                message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
+                message: '.peaks/memory/index.json missing schema_version / version field'
             }];
     }
+    const hotCount = countEntries(parsed.hot);
+    const warmCount = countEntries(parsed.warm);
+    const checks = [{
+            id: 'L3:l3-memory-health',
+            ok: true,
+            message: `.peaks/memory/index.json is well-formed JSON; version=${schemaMarker}; ${hotCount} hot + ${warmCount} warm memory entries`
+        }];
+    // Drift inspection is best-effort: a scan failure must not turn a
+    // well-formed index into a hard failure.
+    try {
+        checks.push(...inspectDrift(memoryDir, memoryIndexPath, hotCount + warmCount));
+    }
+    catch (error) {
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: true,
+            severity: 'warning',
+            message: `Memory drift inspection skipped: ${getErrorMessage(error)}`
+        });
+    }
+    return checks;
 }
 export const check = {
     name: 'l3-memory-health',

package/dist/services/ide/adapters/claude-code-adapter.d.ts

@@ -1,4 +1,14 @@
 import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export declare function resolveClaudeTranscriptPath(outerSessionId: string, projectsDir?: string): string | null;
 /**
  * Resolve the currently-active Claude Code model id from a runtime env map.
  * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or

package/dist/services/ide/adapters/claude-code-adapter.js

@@ -90,6 +90,20 @@ function findTranscriptJsonl(projectsDir, outerSessionId) {
     }
     return null;
 }
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * Exported (slice 2026-09-10-context-audit-and-discipline, Slice A) so
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export function resolveClaudeTranscriptPath(outerSessionId, projectsDir = join(homedir(), '.claude', 'projects')) {
+    if (typeof outerSessionId !== 'string' || outerSessionId.length === 0)
+        return null;
+    return findTranscriptJsonl(projectsDir, outerSessionId);
+}
 /** 1M-context window size in tokens (documented single choice: 1,000,000). */
 const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
 /** Safe-default (non-1M) context window size in tokens. */
@@ -483,7 +497,12 @@ export const CLAUDE_CODE_ADAPTER = {
         compactCommand: 'claude --compact',
         compactPathway: 'ide-native',
         postCompactDetectCommand: 'peaks code auto-compact --json',
-        readContextPercentFallback
+        readContextPercentFallback,
+        // Slice 2026-09-10-context-audit-and-discipline (Slice A): the vendor
+        // layout knowledge (`~/.claude/projects/**/<outerSessionId>.jsonl`)
+        // stays here; `peaks code context-audit` resolves it through the
+        // adapter registry, never by naming this adapter directly.
+        resolveTranscriptPath: (outerSessionId) => resolveClaudeTranscriptPath(outerSessionId),
     },
     // Slice #011: standards profile. Claude Code reads its constitution at
     // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror

package/dist/services/ide/ide-types.d.ts

@@ -217,6 +217,21 @@ export interface IdeCompactProfile {
      * Added in slice 2026-09-02-vendor-neutral-context-probe.
      */
     readonly readContextPercentFallback?: (input: ContextPercentFallbackInput) => ContextPercentProbe | null;
+    /**
+     * Optional locator for the IDE's per-session transcript file (jsonl),
+     * keyed by the OUTER (harness) session id. `peaks code context-audit`
+     * (slice 2026-09-10-context-audit-and-discipline, Slice A) uses it to
+     * group the session's tool results by tool + short input key, so the
+     * generic audit service never learns any vendor's on-disk layout.
+     *
+     * Returns the absolute path, or `null` when the transcript does not
+     * exist. Adapters MUST NOT throw on a missing file — the audit treats
+     * `null` as `available: false` and continues.
+     *
+     * Adapters that do not opt in simply omit the field; the audit then
+     * reports `transcript-locator-unavailable`.
+     */
+    readonly resolveTranscriptPath?: (outerSessionId: string) => string | null;
 }
 /**
  * Input the generic `readContextPercent` reader passes to an adapter's

package/dist/services/job/job-types.d.ts

@@ -6,8 +6,8 @@ export declare const SliceStateSchema: z.ZodObject<{
         pending: "pending";
         blocked: "blocked";
         failed: "failed";
-        skipped: "skipped";
         done: "done";
+        skipped: "skipped";
         "in-progress": "in-progress";
     }>;
     commitSha: z.ZodOptional<z.ZodString>;
@@ -48,8 +48,8 @@ export declare const JobStateSchema: z.ZodObject<{
             pending: "pending";
             blocked: "blocked";
             failed: "failed";
-            skipped: "skipped";
             done: "done";
+            skipped: "skipped";
             "in-progress": "in-progress";
         }>;
         commitSha: z.ZodOptional<z.ZodString>;
@@ -118,8 +118,8 @@ export declare const JobCheckpointInputSchema: z.ZodObject<{
     sliceId: z.ZodString;
     state: z.ZodEnum<{
         failed: "failed";
-        skipped: "skipped";
         done: "done";
+        skipped: "skipped";
     }>;
     commitSha: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;

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

@@ -0,0 +1,79 @@
+import type { ProjectMemoryKind } from './project-memory-service/types.js';
+export interface MemoryIngestOptions {
+    projectRoot: string;
+    /** Override the IDE-side source dir (defaults to `~/.claude/projects/<encoded>/memory`). */
+    sourceDir?: string;
+    /** Injectable home dir (tests); defaults to `os.homedir()`. */
+    homeDir?: string;
+    apply?: boolean;
+}
+export interface MemoryIngestImported {
+    name: string;
+    kind: ProjectMemoryKind;
+    sourcePath: string;
+    targetPath: string;
+}
+export interface MemoryIngestSkipped {
+    name: string;
+    sourcePath: string;
+    targetPath: string;
+}
+export interface MemoryIngestConflict {
+    name: string;
+    sourcePath: string;
+    targetPath: string;
+    reason: string;
+}
+export interface MemoryIngestNeedsClassification {
+    name: string;
+    sourcePath: string;
+    rawKind: string | null;
+    reason: string;
+}
+export interface MemoryIngestRefused {
+    name: string;
+    sourcePath: string;
+    reason: string;
+}
+export interface MemoryIngestReport {
+    apply: boolean;
+    projectRoot: string;
+    sourceDir: string;
+    sourceExists: boolean;
+    memoryDir: string;
+    scannedFiles: number;
+    imported: MemoryIngestImported[];
+    skippedIdentical: MemoryIngestSkipped[];
+    conflicts: MemoryIngestConflict[];
+    needsClassification: MemoryIngestNeedsClassification[];
+    refused: MemoryIngestRefused[];
+    writtenFiles: string[];
+    warnings: string[];
+}
+/**
+ * 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 declare function encodeIdeProjectDir(projectRoot: string): string;
+/** Default IDE-side memory dir for a project: `~/.claude/projects/<encoded>/memory`. */
+export declare function defaultIdeMemoryDir(projectRoot: string, homeDir?: string): string;
+/**
+ * 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 declare function renderNormalizedMemory(input: {
+    stem: string;
+    kind: ProjectMemoryKind;
+    frontmatter: string;
+    body: string;
+}): string;
+/**
+ * Import IDE-side memories into `.peaks/memory/`. Always returns the full
+ * envelope; `apply` only controls whether files are actually written.
+ */
+export declare function executeMemoryIngest(options: MemoryIngestOptions): MemoryIngestReport;

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