peaks-loop 4.0.50 → 4.0.52

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

@@ -27,7 +27,7 @@ import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { isInsidePath, resolveInputPath, stablePath, stableRealPath } from '../../../../shared/path-utils.js';
 import { renderMemoryFile, slugify } from '../parsers/frontmatter.js';
-import { extractStableProjectMemories, summarizeBackupResult, summarizeExtractResult } from '../parsers/markdown-pure.js';
+import { extractStableProjectMemoriesWithDiagnostics, summarizeBackupResult, summarizeExtractResult } from '../parsers/markdown-pure.js';
 import { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRoot, realPathOrThrow } from '../store/paths.js';
 import { assertSafeMemoryFileContent, writeNewFile } from '../store/atomic-write.js';
 import { generateMemoryIndexFile, readStoredMemoryNames } from './ranking.js';
@@ -35,11 +35,18 @@ import { listMarkdownFiles } from './search.js';
 export function createProjectMemoryExtractPlan(options) {
     const projectRoot = normalizeRoot(options.projectRoot);
     const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
-    const extractedMemories = options.artifactPaths.flatMap((artifactPath) => {
+    const extractedMemories = [];
+    const droppedBlocks = [];
+    for (const artifactPath of options.artifactPaths) {
         const safeArtifactPath = assertInsideProject(artifactPath, projectRoot);
         const relativeArtifactPath = relative(projectRoot, safeArtifactPath).replaceAll('\\', '/');
-        return extractStableProjectMemories(readFileSync(safeArtifactPath, 'utf8'), relativeArtifactPath);
-    }).sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
+        const extracted = extractStableProjectMemoriesWithDiagnostics(readFileSync(safeArtifactPath, 'utf8'), relativeArtifactPath);
+        // Push order + the sort below are the pre-existing ordering contract:
+        // artifacts in argument order, memories sorted by slug.
+        extractedMemories.push(...extracted.memories);
+        droppedBlocks.push(...extracted.dropped);
+    }
+    extractedMemories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
     const slugCounts = new Map();
     for (const memory of extractedMemories) {
         const slug = slugify(memory.title);
@@ -60,7 +67,8 @@ export function createProjectMemoryExtractPlan(options) {
         primaryMemoryDir,
         backupPolicy: 'project-memory-primary-artifact-backup',
         extractedMemories,
-        plannedWrites
+        plannedWrites,
+        droppedBlocks
     };
 }
 export function executeProjectMemoryExtract(options) {
@@ -177,22 +185,45 @@ export function extractSessionMemories(options) {
                 scannedFiles: 0,
                 extractedCount: 0,
                 writtenFiles: [],
-                updatedIndex: false
+                updatedIndex: false,
+                droppedBlocks: [],
+                scanFailures: []
             };
         }
         throw error;
     }
     const scannedFiles = listMarkdownFiles(sessionDir, { maxDepth: 6, skipDotfiles: true });
     const allExtracted = [];
+    // Symmetric with `createProjectMemoryExtractPlan`, which has reported the
+    // rejected blocks since M2. This path used to call the diagnostic-free
+    // projection, so a session handoff whose blocks were all malformed returned
+    // `extractedCount: 0` with nothing anywhere saying a block had been found.
+    const droppedBlocks = [];
+    const scanFailures = [];
     for (const filePath of scannedFiles) {
+        const relativePath = relative(projectRoot, filePath).replaceAll('\\', '/');
         try {
             const content = readFileSync(filePath, 'utf8');
-            const relativePath = relative(projectRoot, filePath).replaceAll('\\', '/');
-            const extracted = extractStableProjectMemories(content, relativePath);
-            allExtracted.push(...extracted);
+            const extracted = extractStableProjectMemoriesWithDiagnostics(content, relativePath);
+            allExtracted.push(...extracted.memories);
+            droppedBlocks.push(...extracted.dropped);
         }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            // skip unreadable files
+        catch (error) {
+            // G2 resolution for this site: this was a bare `catch {}` carrying the
+            // repo-wide G2 grace marker that `scripts/lint/silent-warning-detector.mjs`
+            // reads (anti-pattern #1, `empty-catch`). The throw is no longer
+            // swallowed — the file is named in the same `warnings` channel as the
+            // block drops, which is what the grace period was deferring, so the
+            // marker is gone from this line. Still non-fatal: one unreadable artifact
+            // must not abort the scan of the rest, so the catch keeps its control
+            // flow and only gains a channel.
+            //
+            // `relativePath` is computed above the `try` so the catch can name the
+            // file. That is safe rather than convenient: `path.relative` is pure
+            // string arithmetic on two already-validated absolute path strings and
+            // does not throw for them, so hoisting it cannot turn a path-join problem
+            // into a fatal error that the old swallow would have absorbed.
+            scanFailures.push({ file: relativePath, detail: error instanceof Error ? error.message : String(error) });
         }
     }
     if (allExtracted.length === 0) {
@@ -205,7 +236,9 @@ export function extractSessionMemories(options) {
             scannedFiles: scannedFiles.length,
             extractedCount: 0,
             writtenFiles: [],
-            updatedIndex: false
+            updatedIndex: false,
+            droppedBlocks,
+            scanFailures
         };
     }
     const slugCounts = new Map();
@@ -248,6 +281,8 @@ export function extractSessionMemories(options) {
         scannedFiles: scannedFiles.length,
         extractedCount: allExtracted.length,
         writtenFiles,
-        updatedIndex: apply && writtenFiles.length > 0
+        updatedIndex: apply && writtenFiles.length > 0,
+        droppedBlocks,
+        scanFailures
     };
 }

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

@@ -1,8 +1,10 @@
-export type { BackupPlanOptions, ExtractedProjectMemory, MemoryKindTier, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
+export type { BackupPlanOptions, ExtractedProjectMemory, MemoryBlockDrop, MemoryBlockDropReason, MemoryBlockParse, MemoryKindTier, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
 export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
 export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
-export { summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
-export { parseBlock, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
+export { describeMemoryBlockDrops, describeSessionScanFailures, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
+export type { SessionScanFailure } from './types.js';
+export type { ExtractedMemoryBlocks } from './parsers/markdown-pure.js';
+export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
 export type { MemoryKindResolution, MemoryKindSource, MemoryNameResolution, MemoryNameSource, ParsedMemoryFrontmatter } from './parsers/frontmatter.js';
 export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
 export { assertSafeMemory, assertSafeMemoryFileContent, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';

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

@@ -14,9 +14,9 @@ export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
 // Canonical kind vocabulary + hot/warm tier map (slice E)
 export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
 // Pure markdown helpers
-export { summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
+export { describeMemoryBlockDrops, describeSessionScanFailures, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
 // Frontmatter parser + renderer
-export { parseBlock, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
+export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, 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';

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

@@ -1,4 +1,4 @@
-import type { ExtractedProjectMemory, ProjectMemoryKind, StoredProjectMemory } from '../types.js';
+import type { ExtractedProjectMemory, MemoryBlockParse, ProjectMemoryKind, StoredProjectMemory } from '../types.js';
 /** Accepted-kind set, derived from the canonical `PROJECT_MEMORY_KINDS`
  *  tuple so the parser cannot drift from the union type / tier map. */
 export declare const VALID_MEMORY_KINDS: ReadonlySet<ProjectMemoryKind>;
@@ -6,6 +6,20 @@ export declare const VALID_MEMORY_KINDS: ReadonlySet<ProjectMemoryKind>;
  *  set (CLI help text, `--kind` validation) without duplicating the literal. */
 export declare const VALID_PROJECT_MEMORY_KINDS: readonly ProjectMemoryKind[];
 export declare function slugify(title: string): string;
+/**
+ * Single implementation of the extract-path block parse. Returns a
+ * discriminated result so the caller can say WHY a found block was rejected.
+ *
+ * The precondition order mirrors the original combined `if` exactly
+ * (separator → title → kind present → kind valid → body non-empty), so the
+ * accepted set is bit-for-bit what it always was; only the explanation is new.
+ */
+export declare function parseBlockResult(block: string, sourceArtifact: string): MemoryBlockParse;
+/**
+ * `null`-on-failure projection of `parseBlockResult`. Kept because callers
+ * (and the parser's own contract) consume a plain nullable value; both views
+ * come from the one implementation above, so they cannot diverge.
+ */
 export declare function parseBlock(block: string, sourceArtifact: string): ExtractedProjectMemory | null;
 export declare function renderMemoryFile(memory: ExtractedProjectMemory): string;
 /**

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

@@ -31,11 +31,20 @@ 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) {
+/**
+ * Single implementation of the extract-path block parse. Returns a
+ * discriminated result so the caller can say WHY a found block was rejected.
+ *
+ * The precondition order mirrors the original combined `if` exactly
+ * (separator → title → kind present → kind valid → body non-empty), so the
+ * accepted set is bit-for-bit what it always was; only the explanation is new.
+ */
+export function parseBlockResult(block, sourceArtifact) {
     const normalizedBlock = block.replace(/\r\n/g, '\n');
     const separatorIndex = normalizedBlock.indexOf('\n---\n');
-    if (separatorIndex < 0)
-        return null;
+    if (separatorIndex < 0) {
+        return { ok: false, reason: 'missing-separator', detail: "block header is not followed by a '---' separator line" };
+    }
     const header = normalizedBlock.slice(0, separatorIndex).trim();
     const body = normalizedBlock.slice(separatorIndex + '\n---\n'.length).trim();
     const fields = new Map();
@@ -49,9 +58,28 @@ export function parseBlock(block, sourceArtifact) {
     }
     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 };
+    if (!title) {
+        return { ok: false, reason: 'missing-title', detail: "block header has no non-empty 'title:' field" };
+    }
+    if (!kind) {
+        return { ok: false, reason: 'missing-kind', detail: "block header has no non-empty 'kind:' field" };
+    }
+    if (!VALID_MEMORY_KINDS.has(kind)) {
+        return { ok: false, reason: 'unknown-kind', detail: `block declares kind '${kind}', which is not an accepted memory kind` };
+    }
+    if (body.length === 0) {
+        return { ok: false, reason: 'empty-body', detail: 'block body is empty' };
+    }
+    return { ok: true, memory: { title, kind, body, sourceArtifact } };
+}
+/**
+ * `null`-on-failure projection of `parseBlockResult`. Kept because callers
+ * (and the parser's own contract) consume a plain nullable value; both views
+ * come from the one implementation above, so they cannot diverge.
+ */
+export function parseBlock(block, sourceArtifact) {
+    const parsed = parseBlockResult(block, sourceArtifact);
+    return parsed.ok ? parsed.memory : null;
 }
 export function renderMemoryFile(memory) {
     const name = slugify(memory.title);

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

@@ -1,7 +1,33 @@
-import type { ExtractedProjectMemory, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryExtractResult, ProjectMemoryExtractSummary } from '../types.js';
+import type { ExtractedProjectMemory, MemoryBlockDrop, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, SessionScanFailure } 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;
+/** Extracted memories plus the blocks that were found and rejected. */
+export type ExtractedMemoryBlocks = {
+    memories: ExtractedProjectMemory[];
+    dropped: MemoryBlockDrop[];
+};
+/**
+ * Same scan as `extractStableProjectMemories`, but also reports the blocks
+ * that were found between the markers and rejected by the parser.
+ *
+ * `extractStableProjectMemories` is the `.memories` projection of this, so the
+ * extracted set is identical by construction — the diagnostics cannot change
+ * which blocks are accepted.
+ */
+export declare function extractStableProjectMemoriesWithDiagnostics(content: string, sourceArtifact: string): ExtractedMemoryBlocks;
 export declare function extractStableProjectMemories(content: string, sourceArtifact: string): ExtractedProjectMemory[];
+/**
+ * Render one warning line per rejected block, for the CLI envelope's
+ * `warnings` channel. `unknown-kind` additionally names the accepted
+ * vocabulary, because that is the failure whose remedy is a value change.
+ */
+export declare function describeMemoryBlockDrops(dropped: ReadonlyArray<MemoryBlockDrop>): string[];
+/**
+ * Render one warning line per session artifact that could not be read. The
+ * sibling of `describeMemoryBlockDrops`, for the failure one level coarser: a
+ * whole file that never yielded blocks at all.
+ */
+export declare function describeSessionScanFailures(failures: ReadonlyArray<SessionScanFailure>): string[];
 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

@@ -20,9 +20,32 @@
 // No filesystem imports. Pure functions only — easy to unit-test.
 // ---------------------------------------------------------------------------
 import { assertSafeMemory } from '../store/atomic-write.js';
-import { parseBlock, slugify } from './frontmatter.js';
+import { parseBlockResult, slugify, VALID_MEMORY_KINDS } from './frontmatter.js';
 export const START_MARKER = '<!-- peaks-memory:start -->';
 export const END_MARKER = '<!-- peaks-memory:end -->';
+/**
+ * A marker-shaped HTML comment: `<!--` then horizontal space then
+ * `peaks-memory:start` / `:end`, then anything up to the closing `-->`.
+ *
+ * This deliberately matches the exact markers TOO — the caller skips those by
+ * comparing against `START_MARKER` / `END_MARKER`, so the two literals stay the
+ * single source of truth instead of being re-spelled here.
+ *
+ * Anchoring on `peaks-memory:` immediately after the comment open is what keeps
+ * this from firing on prose: a comment that merely *mentions* the marker
+ * (`<!-- see the peaks-memory:start docs -->`) does not match, because the text
+ * after `<!--` is `see`, not `peaks-memory:`. Only an attempted marker matches.
+ */
+const MARKER_SHAPED_COMMENT = /<!--[ \t]*peaks-memory:(start|end)\b[^>]*-->/g;
+/**
+ * Why a marker-shaped comment was not usable, as a warning line. Names both the
+ * text that was found and the literal the locator wanted, because the whole
+ * failure is "these two differ in a way nothing told you about".
+ */
+function describeUnrecognizedMarker(found) {
+    const wanted = found.includes(':end') ? END_MARKER : START_MARKER;
+    return `found ${JSON.stringify(found)}, which is not the exact marker ${JSON.stringify(wanted)} — the locator searches for that literal, so any block this opens is never found`;
+}
 // 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
@@ -47,8 +70,21 @@ export function summarizeMemoryBody(body) {
     }
     return first.slice(0, MAX_DESCRIPTION_LENGTH - ELLIPSIS_RESERVE) + '...';
 }
-export function extractStableProjectMemories(content, sourceArtifact) {
+/**
+ * Same scan as `extractStableProjectMemories`, but also reports the blocks
+ * that were found between the markers and rejected by the parser.
+ *
+ * `extractStableProjectMemories` is the `.memories` projection of this, so the
+ * extracted set is identical by construction — the diagnostics cannot change
+ * which blocks are accepted.
+ */
+export function extractStableProjectMemoriesWithDiagnostics(content, sourceArtifact) {
     const memories = [];
+    // Kept as `{index, drop}` pairs so located-block drops and near-miss-marker
+    // drops can be reported in DOCUMENT order through one channel. The index is
+    // ordering metadata only — it never reaches the caller.
+    const drops = [];
+    const locatedRanges = [];
     let searchStart = 0;
     while (searchStart < content.length) {
         const start = content.indexOf(START_MARKER, searchStart);
@@ -58,14 +94,63 @@ export function extractStableProjectMemories(content, sourceArtifact) {
         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);
+        locatedRanges.push([start, end + END_MARKER.length]);
+        const parsed = parseBlockResult(content.slice(bodyStart, end).trim(), sourceArtifact);
+        if (parsed.ok) {
+            assertSafeMemory(parsed.memory);
+            memories.push(parsed.memory);
+        }
+        else {
+            drops.push({ index: start, drop: { sourceArtifact, reason: parsed.reason, detail: parsed.detail } });
         }
         searchStart = end + END_MARKER.length;
     }
-    return memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
+    // Near-miss markers. These are invisible to the loop above by construction —
+    // it navigates by exact `indexOf` — so before this pass an artifact written
+    // with, say, an attribute inside the marker reported `extractedCount: 0` with
+    // `warnings: []`, indistinguishable from an artifact that had no blocks at
+    // all. Nothing is extracted here: this pass only names what was not found.
+    //
+    // A near-miss INSIDE a located block's span is the block's own body text, not
+    // an attempted marker, so it is skipped rather than reported.
+    for (const match of content.matchAll(MARKER_SHAPED_COMMENT)) {
+        const found = match[0];
+        if (found === START_MARKER || found === END_MARKER)
+            continue;
+        const index = match.index ?? 0;
+        if (locatedRanges.some(([from, to]) => index >= from && index < to))
+            continue;
+        drops.push({ index, drop: { sourceArtifact, reason: 'unrecognized-marker', detail: describeUnrecognizedMarker(found) } });
+    }
+    drops.sort((left, right) => left.index - right.index);
+    return {
+        memories: memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title))),
+        dropped: drops.map((entry) => entry.drop)
+    };
+}
+export function extractStableProjectMemories(content, sourceArtifact) {
+    return extractStableProjectMemoriesWithDiagnostics(content, sourceArtifact).memories;
+}
+/**
+ * Render one warning line per rejected block, for the CLI envelope's
+ * `warnings` channel. `unknown-kind` additionally names the accepted
+ * vocabulary, because that is the failure whose remedy is a value change.
+ */
+export function describeMemoryBlockDrops(dropped) {
+    return dropped.map((drop) => {
+        const hint = drop.reason === 'unknown-kind'
+            ? ` Accepted kinds: ${[...VALID_MEMORY_KINDS].join(', ')}.`
+            : '';
+        return `Skipped a memory block in ${drop.sourceArtifact}: ${drop.detail}.${hint}`;
+    });
+}
+/**
+ * Render one warning line per session artifact that could not be read. The
+ * sibling of `describeMemoryBlockDrops`, for the failure one level coarser: a
+ * whole file that never yielded blocks at all.
+ */
+export function describeSessionScanFailures(failures) {
+    return failures.map((failure) => `Could not read the session artifact ${failure.file}: ${failure.detail}.`);
 }
 export function summarizeExtractResult(result) {
     return {

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

@@ -35,6 +35,50 @@ export type ExtractedProjectMemory = {
     body: string;
     sourceArtifact: string;
 };
+/**
+ * Why a `<!-- peaks-memory:start -->` block that was FOUND was not extracted.
+ *
+ * One value per precondition in `parseBlockResult` (the extract path's block
+ * parser), in evaluation order. Before this existed, every one of these
+ * conditions collapsed into a bare `null` and the caller reported nothing, so
+ * `extractedCount: N` was indistinguishable from "the block was never there".
+ * Naming the cause is the whole point: a memory block that disappears must say
+ * why it disappeared.
+ *
+ * Diagnostics only — this type does not change WHICH blocks are accepted.
+ */
+export type MemoryBlockDropReason = 'missing-separator' | 'missing-title' | 'missing-kind' | 'unknown-kind' | 'empty-body'
+/**
+ * NOT a `parseBlockResult` precondition — this one comes from the scanner.
+ * A marker-shaped comment that is not the exact literal the locator searches
+ * for. The block it opens is therefore never found: it is not "rejected",
+ * it is invisible. Reporting it is the whole point, because nothing else in
+ * the pipeline can see it.
+ */
+ | 'unrecognized-marker';
+/** A found-but-not-extracted memory block, with the precondition that failed. */
+export type MemoryBlockDrop = {
+    /** Artifact path the block was found in (project-relative when extracted). */
+    sourceArtifact: string;
+    reason: MemoryBlockDropReason;
+    /** Human-readable explanation of the failed precondition. */
+    detail: string;
+};
+/**
+ * Result of parsing one memory block, as a discriminated union.
+ *
+ * `parseBlock` is the `null`-on-failure projection of this; both are produced
+ * by the same single implementation so they cannot disagree about which blocks
+ * are accepted.
+ */
+export type MemoryBlockParse = {
+    ok: true;
+    memory: ExtractedProjectMemory;
+} | {
+    ok: false;
+    reason: MemoryBlockDropReason;
+    detail: string;
+};
 export type ProjectMemoryWrite = {
     memory: ExtractedProjectMemory;
     filePath: string;
@@ -47,6 +91,12 @@ export type ProjectMemoryExtractPlan = {
     backupPolicy: 'project-memory-primary-artifact-backup';
     extractedMemories: ExtractedProjectMemory[];
     plannedWrites: ProjectMemoryWrite[];
+    /**
+     * Blocks that were found between the markers but rejected by the parser.
+     * Reported to the user through the CLI envelope's `warnings` channel.
+     * Purely informational — this array does not influence extraction.
+     */
+    droppedBlocks: MemoryBlockDrop[];
 };
 export type ProjectMemoryExtractResult = ProjectMemoryExtractPlan & {
     writtenFiles: string[];
@@ -123,6 +173,22 @@ export type ExtractSessionMemoriesOptions = {
     sessionId: string;
     apply?: boolean;
 };
+/**
+ * A session artifact that could not be read at all, so its blocks were never
+ * even candidates.
+ *
+ * Distinct from `MemoryBlockDrop`: that one describes a BLOCK that was found and
+ * rejected, and needs the artifact to have been readable in the first place.
+ * Folding a whole-file read failure into it would make `sourceArtifact` mean two
+ * different things, so this rides its own field and is rendered by its own
+ * `describeSessionScanFailures`.
+ */
+export type SessionScanFailure = {
+    /** Project-relative path of the artifact that could not be read. */
+    file: string;
+    /** The underlying error message. Never invented; taken from the throw. */
+    detail: string;
+};
 export type ExtractSessionMemoriesResult = {
     apply: boolean;
     projectRoot: string;
@@ -133,6 +199,26 @@ export type ExtractSessionMemoriesResult = {
     extractedCount: number;
     writtenFiles: string[];
     updatedIndex: boolean;
+    /**
+     * Blocks that were FOUND between the markers in this session's artifacts but
+     * rejected by the parser. Same diagnostic contract as
+     * `ProjectMemoryExtractPlan.droppedBlocks` — the sibling `peaks memory
+     * extract` path has carried this since M2, and this one silently dropped
+     * them, so `extractedCount: 1` out of three blocks was indistinguishable
+     * from "there was one block".
+     *
+     * Purely informational: this array does not influence which blocks are
+     * extracted, and it adds no field to the CLI's `data` payload — the reasons
+     * ride the existing envelope `warnings` channel.
+     */
+    droppedBlocks: MemoryBlockDrop[];
+    /**
+     * Session artifacts that could not be read, so their blocks were never
+     * candidates. Previously swallowed by a bare `catch {}`; reported now through
+     * the same CLI `warnings` channel. Diagnostic only — an unreadable artifact
+     * is still not an error, and the scan is otherwise unchanged.
+     */
+    scanFailures: SessionScanFailure[];
 };
 export type ProjectMemoryShowResult = {
     projectRoot: string;

package/dist/services/slice/slice-check-types.d.ts

@@ -69,7 +69,7 @@ export type SliceCheckResult = {
 };
 export type SliceCheckOptions = {
     projectRoot: string;
-    /** When omitted, slice check inspects `.peaks/_runtime/current-change` to find the active rid. */
+    /** REQUIRED. The `.peaks/_runtime/current-change` binding file is gone (slice 2026-06-29-change-id-root-removal); when omitted, slice check throws rather than guessing. */
     rid?: string;
     /**
      * When true, re-run the 3-way review fan-out (peaks-rd's code-review +

package/dist/services/workspace/runtime-layout.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The canonical top-level layout of `.peaks/_runtime/`.
+ *
+ * WHY THIS MODULE EXISTS
+ *
+ * `.peaks/_runtime/` holds two populations whose names look identical:
+ *
+ *   1. SESSION DIRS — `<YYYY-MM-DD>-session-<hex>`, one per peaks session.
+ *      Anything else that *looks* like a session id but is not one is a
+ *      defect (a test that passed `--session-id x`, a typo, an old
+ *      `unknown-sid` bucket).
+ *   2. SYSTEM ENTRIES — dirs and files the code itself writes there on
+ *      purpose: `callers/`, `change/`, `benchmarks/`, `session.json`, …
+ *
+ * The doctor check `L3:l3-orphan-sessions` must flag (1) and tolerate (2),
+ * and the only thing that can tell them apart is a list of the system
+ * entries. That list used to live inside the check as a hand-maintained
+ * `new Set(['change'])` — and it had already drifted: `callers/` is a
+ * designed location (`caller-binding-service.ts` stores
+ * `.peaks/_runtime/callers/<callerId>.json`), was never added, and made
+ * `peaks doctor` exit non-zero on a clean workspace *permanently*
+ * (`4 orphan session(s) …: callers, cli, unknown-sid, x`). The check's own
+ * doc comment asked future maintainers to keep a *second* list — the prose
+ * `RUNTIME_SYSTEM_SUBDIRS_DOC` — in sync by hand. Prose cannot enforce
+ * itself, so the two lists diverged exactly as you would expect.
+ *
+ * WHY DERIVATION WAS REJECTED AND A REGISTRY IS THE SOURCE OF TRUTH
+ *
+ * A derivation would have to classify a bare name as "system" or "bogus"
+ * without a list. There is no signal to derive from: `callers` (system) and
+ * `x` (bogus) are the same shape — a lowercase word. The session-id regex
+ * separates them from `2026-09-16-session-5bcf09`, not from each other. So
+ * the alternatives were (a) keep a literal in the check, or (b) put the
+ * literal *and its consumers* in one place. This module is (b): the check
+ * imports the set instead of re-declaring it, and
+ * `tests/unit/workspace/runtime-layout-drift-guard.test.ts` parses `src/**`
+ * and fails when the code writes a `_runtime` child that is not registered
+ * here. The registry can no longer drift silently — it can only drift loudly,
+ * as a red test.
+ *
+ * The guard parses ASTs rather than grepping, because this repository
+ * documents the layout in prose constantly: `migrate-1-4-1-service.ts` has an
+ * array whose two adjacent string literals are `'_runtime', '_sub_agents'`
+ * (they are two *separate* SKIP entries), and `evidence-generator.ts`
+ * describes a past escape as `` `.peaks/_runtime/pwned.md` `` inside a
+ * comment. Both are false positives for a text scan and invisible to an AST
+ * walk. See `tests/unit/runtime/no-runtime-input-guard.test.ts` for the same
+ * decision made the same way.
+ */
+/**
+ * `dir` entries are scanned by `L3:l3-orphan-sessions` and must not be
+ * flagged. `file` entries are never flagged by that check — it only reads
+ * directories — and are registered so the drift guard can classify them and
+ * so this module stays an honest census of the tree rather than half of one.
+ */
+export type RuntimeEntryKind = 'dir' | 'file';
+export interface RuntimeSystemEntry {
+    /** The exact top-level name under `.peaks/_runtime/`. */
+    readonly name: string;
+    readonly kind: RuntimeEntryKind;
+    /** What writes it and why it is legitimate. */
+    readonly purpose: string;
+}
+/**
+ * Reserved top-level dir for session-less command output.
+ *
+ * `peaks baseline audit` runs with no bound session (it is the only scorer
+ * that can run inside the secretless OIDC publish gate), so it has no
+ * `<sid>` to write under. It used to pass the literal `'cli'` as its
+ * sessionId, which made `.peaks/_runtime/cli/capability-audit/*.json` look
+ * exactly like a session dir that failed validation — `peaks doctor` has
+ * been red on this repository ever since. The name is underscore-prefixed to
+ * match the tree's existing convention for "machinery, not a session"
+ * (`_runtime`, `_sub_agents`) and to make it impossible to mistake for a
+ * session id.
+ */
+export declare const RUNTIME_SESSIONLESS_SCOPE = "_audit";
+/**
+ * Every legitimate top-level entry under `.peaks/_runtime/`.
+ *
+ * This is the list `L3:l3-orphan-sessions` tolerates. Adding an entry that
+ * nothing writes is a red test (the drift guard's reverse direction); writing
+ * an entry that is not here is also a red test. Both directions are pinned in
+ * `tests/unit/workspace/runtime-layout-drift-guard.test.ts`.
+ */
+export declare const RUNTIME_SYSTEM_ENTRIES: readonly RuntimeSystemEntry[];
+/**
+ * The set `L3:l3-orphan-sessions` filters with. Derived from the registry
+ * above so the check and the census cannot disagree about the same name.
+ */
+export declare const RUNTIME_SYSTEM_SUBDIRS: ReadonlySet<string>;