peaks-loop 4.0.51 → 4.0.52

package/dist/services/doctor/doctor-service/checks/codegraph-exclude-integrity.js

@@ -30,8 +30,23 @@ import { inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent } fro
 const CHECK_ID = 'capability:codegraph-exclude-integrity';
 /** How many rules / offending files the message names before eliding. */
 const MAX_NAMED = 5;
-function defaultProbe() {
-    const projectRoot = process.cwd();
+/**
+ * 2026-09-17 — `projectRoot` is the doctor's resolved L3 root, NOT
+ * `process.cwd()`. Same defect as the sibling `codegraph-index-integrity`
+ * probe (see its note): with `projectRootResolver` injected, every other
+ * check inspected the caller's root while this one inspected the operator's
+ * checkout, so its verdict depended on which repository you ran the doctor
+ * in. This one is read-only — it reads `.codegraph/config.json` and
+ * `git ls-files`, never the sqlite index — so unlike its sibling it did not
+ * also materialise `-shm`/`-wal` sidecars; the wrong-root defect was the
+ * same either way.
+ */
+function defaultProbe(projectRoot) {
+    // An unresolved root is not a project — see the sibling probe's note: a
+    // relative lookup here would resolve against `cwd` and inspect the
+    // operator's checkout.
+    if (projectRoot.length === 0)
+        return null;
     // No config → codegraph was never initialized here, so no exclude
     // list is in play and there is nothing to report.
     return isCodegraphExcludeConfigPresent(projectRoot)
@@ -48,8 +63,8 @@ function renderGapMessage(excludedTrackedCount, trackedSourceCount, rulesToRemov
     const elidedFiles = violations.length > MAX_NAMED ? `; … (+${violations.length - MAX_NAMED})` : '';
     return `codegraph index is incomplete: ${excludedTrackedCount} of ${trackedSourceCount} tracked source files are blocked by ${rulesToRemove.length} exclude rule(s) [${namedRules}${elidedRules}]. Blocked: ${namedFiles}${elidedFiles}. Run \`peaks codegraph repair-exclude --project <root>\` to drop them and rebuild the index.`;
 }
-function run({ options }) {
-    const probe = options.codegraphIntegrityProbe ?? defaultProbe;
+function run({ options, resolvedL3Root }) {
+    const probe = options.codegraphIntegrityProbe ?? (() => defaultProbe(resolvedL3Root));
     let report;
     try {
         report = probe();

package/dist/services/doctor/doctor-service/checks/codegraph-index-integrity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Check: codegraph index integrity (`capability:codegraph-index-integrity`).
+ *
+ * The third codegraph check, and the one that stops `[OK]` from being a
+ * self-consistency assertion:
+ *   - `capability:codegraph` answers "is upstream resolvable";
+ *   - `capability:codegraph-exclude-integrity` answers "do the `exclude`
+ *     rules drop tracked files";
+ *   - this one answers "does the INDEX ITSELF cover the repository" —
+ *     files the extractor supports that `include` never admitted, and rows
+ *     the index still holds for paths that are gone.
+ *
+ * Why the exclude gate structurally cannot answer it: that gate runs the
+ * `include` filter FIRST and reconciles `exclude` against the survivors, so
+ * a file dropped by `include` is not "a tracked source file" as far as it is
+ * concerned; and it never reads the index at all, so dead rows are invisible
+ * to it. Both defects were present while `peaks codegraph status` printed
+ * `[OK] Index is up to date`.
+ *
+ * Read-only by construction — it consumes the same read-only inspector
+ * `peaks codegraph status` gates on. It never writes `.codegraph/config.json`
+ * and never invokes the upstream binary.
+ *
+ * Failure posture:
+ *   - codegraph not initialized in the inspected root (no
+ *     `.codegraph/codegraph.db`) → `ok: true`; there is no index to be
+ *     incomplete or stale, and a fresh clone must not fail the doctor.
+ *   - a confirmed gap on either axis → `ok: false`. ADVISORY by default
+ *     (`severity: 'warning'`, the doctor exit code is left alone), and
+ *     blocking (no severity tag) when the project opts in with
+ *     `PEAKS_CODEGRAPH_INDEX_STRICT=1` — the user's option C decision.
+ *     The finding is `ok: false` either way; only its severity moves.
+ *   - could not evaluate (not a git work tree, missing/malformed config,
+ *     unreadable index) → `ok: false, severity: 'warning'` so the doctor
+ *     reports the blind spot without flipping the exit code on an
+ *     unrelated failure. Kept non-blocking in BOTH modes: "could not
+ *     evaluate" is not a finding about the project, and it is
+ *     distinguishable from the `ok: true` "covers the repository"
+ *     verdict by its `ok` value.
+ *
+ * R12-2 — the partial collapse that remains, stated rather than implied:
+ * this branch and the advisory `gap` branch below BOTH emit `ok: false`
+ * with `severity: 'warning'`, and `DoctorCheck` has no third field, so in
+ * the doctor envelope they are separated by message text alone. Not fixed,
+ * deliberately: the shape is legacy (`runDoctor` compatibility is a
+ * stated constraint), neither state is `ok: true` — so the invariant that
+ * a non-measurement may never read as "verified clean" holds — and in the
+ * mode where they are collapsed neither state moves the exit code.
+ * Under `PEAKS_CODEGRAPH_INDEX_STRICT=1` they ARE separated in the
+ * machine fields: the advisory `gap` branch drops its tag, this one keeps
+ * it. Pinned by the "(severity policy)" and "(unevaluable)" tests.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/codegraph-index-integrity.js

@@ -0,0 +1,151 @@
+/**
+ * Check: codegraph index integrity (`capability:codegraph-index-integrity`).
+ *
+ * The third codegraph check, and the one that stops `[OK]` from being a
+ * self-consistency assertion:
+ *   - `capability:codegraph` answers "is upstream resolvable";
+ *   - `capability:codegraph-exclude-integrity` answers "do the `exclude`
+ *     rules drop tracked files";
+ *   - this one answers "does the INDEX ITSELF cover the repository" —
+ *     files the extractor supports that `include` never admitted, and rows
+ *     the index still holds for paths that are gone.
+ *
+ * Why the exclude gate structurally cannot answer it: that gate runs the
+ * `include` filter FIRST and reconciles `exclude` against the survivors, so
+ * a file dropped by `include` is not "a tracked source file" as far as it is
+ * concerned; and it never reads the index at all, so dead rows are invisible
+ * to it. Both defects were present while `peaks codegraph status` printed
+ * `[OK] Index is up to date`.
+ *
+ * Read-only by construction — it consumes the same read-only inspector
+ * `peaks codegraph status` gates on. It never writes `.codegraph/config.json`
+ * and never invokes the upstream binary.
+ *
+ * Failure posture:
+ *   - codegraph not initialized in the inspected root (no
+ *     `.codegraph/codegraph.db`) → `ok: true`; there is no index to be
+ *     incomplete or stale, and a fresh clone must not fail the doctor.
+ *   - a confirmed gap on either axis → `ok: false`. ADVISORY by default
+ *     (`severity: 'warning'`, the doctor exit code is left alone), and
+ *     blocking (no severity tag) when the project opts in with
+ *     `PEAKS_CODEGRAPH_INDEX_STRICT=1` — the user's option C decision.
+ *     The finding is `ok: false` either way; only its severity moves.
+ *   - could not evaluate (not a git work tree, missing/malformed config,
+ *     unreadable index) → `ok: false, severity: 'warning'` so the doctor
+ *     reports the blind spot without flipping the exit code on an
+ *     unrelated failure. Kept non-blocking in BOTH modes: "could not
+ *     evaluate" is not a finding about the project, and it is
+ *     distinguishable from the `ok: true` "covers the repository"
+ *     verdict by its `ok` value.
+ *
+ * R12-2 — the partial collapse that remains, stated rather than implied:
+ * this branch and the advisory `gap` branch below BOTH emit `ok: false`
+ * with `severity: 'warning'`, and `DoctorCheck` has no third field, so in
+ * the doctor envelope they are separated by message text alone. Not fixed,
+ * deliberately: the shape is legacy (`runDoctor` compatibility is a
+ * stated constraint), neither state is `ok: true` — so the invariant that
+ * a non-measurement may never read as "verified clean" holds — and in the
+ * mode where they are collapsed neither state moves the exit code.
+ * Under `PEAKS_CODEGRAPH_INDEX_STRICT=1` they ARE separated in the
+ * machine fields: the advisory `gap` branch drops its tag, this one keeps
+ * it. Pinned by the "(severity policy)" and "(unevaluable)" tests.
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { isCodegraphInitialized } from '../../../codegraph/codegraph-service.js';
+import { CODEGRAPH_INDEX_STRICT_ENV_VAR, CODEGRAPH_REPAIR_INDEX_COMMAND, inspectCodegraphIndexIntegrity, isCodegraphIndexStrictMode } from '../../../codegraph/codegraph-index-integrity.js';
+const CHECK_ID = 'capability:codegraph-index-integrity';
+/** How many offending paths the message names per axis before eliding. */
+const MAX_NAMED = 5;
+function elide(paths) {
+    const named = paths.slice(0, MAX_NAMED).join(', ');
+    return paths.length > MAX_NAMED ? `${named}, … (+${paths.length - MAX_NAMED})` : named;
+}
+/**
+ * 2026-09-17 — `projectRoot` is the doctor's resolved L3 root, NOT
+ * `process.cwd()`. It used to read `process.cwd()`, which is a different
+ * thing from the root the rest of the doctor was pointed at: a caller that
+ * injects `projectRootResolver` (e.g.
+ * `tests/unit/doctor/doctor-exit-code-warn-only.test.ts`) got every other
+ * check aimed at its temp root while THIS one opened the operator's real
+ * `.codegraph/codegraph.db`. Opening that database materialises its
+ * `-shm`/`-wal` sidecars, so a unit run mutated the operator's checkout and
+ * the check's result depended on which repository you happened to run it
+ * in. Every other L3 check reads `resolvedL3Root` from `DoctorContext`;
+ * this one now does too.
+ */
+function defaultProbe(projectRoot) {
+    // An unresolved root is not a project. It must NOT fall through to a
+    // relative lookup (`join('', '.codegraph', …)` resolves against `cwd`),
+    // because that fallback IS the defect this signature was changed to close:
+    // a caller that never resolved a root would silently inspect the operator's
+    // checkout. `runDoctor` always resolves one; only a hand-built test context
+    // can pass ''.
+    if (projectRoot.length === 0)
+        return null;
+    // No index → nothing to be incomplete or stale.
+    return isCodegraphInitialized(projectRoot) ? inspectCodegraphIndexIntegrity(projectRoot) : null;
+}
+function renderGapMessage(includeGap, admittedTrackedCount, trackedSourceCount, deadRows, indexedFileCount) {
+    const parts = [];
+    if (includeGap.length > 0) {
+        parts.push(`${includeGap.length} of ${trackedSourceCount} extractor-supported tracked file(s) are not admitted by the config's include globs (admitted: ${admittedTrackedCount}) [${elide(includeGap)}]`);
+    }
+    if (deadRows.length > 0) {
+        parts.push(`${deadRows.length} of ${indexedFileCount} indexed file(s) are gone from disk [${elide(deadRows)}]`);
+    }
+    return `codegraph index does not cover the repository: ${parts.join('; ')}.`;
+}
+// The remediation clause, in both modes. Naming the command is the
+// slice-002 half of slice-001's design decision 4 (which deliberately named
+// none while none existed); the command name is a shared constant, so this
+// message cannot drift from the CLI surface it points at.
+function remediation() {
+    return `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`;
+}
+function run({ options, resolvedL3Root }) {
+    const probe = options.codegraphIndexIntegrityProbe ?? (() => defaultProbe(resolvedL3Root));
+    const strict = isCodegraphIndexStrictMode();
+    let report;
+    try {
+        report = probe();
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `codegraph index integrity could not be evaluated: ${getErrorMessage(error)}`
+            }];
+    }
+    if (report === null) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: 'codegraph is not initialized in this project (no .codegraph/codegraph.db); there is no index to be incomplete or stale'
+            }];
+    }
+    if (!report.gap) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `codegraph index covers the repository (${report.admittedTrackedCount} extractor-supported tracked file(s) admitted, ${report.indexedFileCount} indexed row(s), none stale)`
+            }];
+    }
+    const gapMessage = renderGapMessage(report.includeGap, report.admittedTrackedCount, report.trackedSourceCount, report.deadRows, report.indexedFileCount);
+    // Option C: advisory by default, blocking on opt-in. `ok: false` in both
+    // modes — the finding is reported either way; only `severity` (and with
+    // it the doctor exit code) moves. The advisory suffix is the discovery
+    // path for the switch, so an operator who wants blocking is told how.
+    return strict
+        ? [{ id: CHECK_ID, ok: false, message: `${gapMessage} ${remediation()}` }]
+        : [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `${gapMessage} ${remediation()} Advisory: set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make this blocking.`
+            }];
+}
+export const check = {
+    name: 'codegraph-index-integrity',
+    run
+};

package/dist/services/doctor/doctor-service/checks/l3-orphan-sessions.js

@@ -18,16 +18,16 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getErrorMessage } from 'peaks-loop-shared/result';
-/**
- * Canonical system subdirs that intentionally live under
- * `.peaks/_runtime/` and must NOT be flagged as orphan sessions.
- *
- * `change/` is the routing target for change-id reviewable
- * artifacts per F3 audit-p1. Adding a new entry here requires
- * also updating `RUNTIME_SYSTEM_SUBDIRS_DOC` in the comments
- * below so the next maintainer knows why each entry is listed.
- */
-const RUNTIME_SYSTEM_SUBDIRS = new Set(['change']);
+import { RUNTIME_SYSTEM_SUBDIRS } from '../../../workspace/runtime-layout.js';
+// The exclude-list moved to `src/services/workspace/runtime-layout.ts`.
+// It is imported above, not re-declared here: the local literal
+// (`new Set(['change'])`) had already drifted — `callers/` is a designed
+// location written by `caller-binding-service.ts` and was never added, so
+// this check reported `4 orphan session(s) …: callers, cli, unknown-sid, x`
+// and `peaks doctor` exited 1 on a clean workspace, permanently.
+// `tests/unit/workspace/runtime-layout-drift-guard.test.ts` now fails when
+// the code writes a `.peaks/_runtime/` child the registry does not know, so
+// the set can no longer drift silently.
 function run({ resolvedL3Root, isValidSessionId }) {
     try {
         const runtimeDir = join(resolvedL3Root, '.peaks/_runtime');

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -43,6 +43,7 @@ import { check as statuslineInstall } from './checks/statusline-install.js';
 import { check as statuslineRuntime } from './checks/statusline-runtime.js';
 import { check as codegraphCapability } from './checks/codegraph-capability.js';
 import { check as codegraphExcludeIntegrity } from './checks/codegraph-exclude-integrity.js';
+import { check as codegraphIndexIntegrity } from './checks/codegraph-index-integrity.js';
 import { check as distSourceVersion } from './checks/dist-source-version.js';
 import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
@@ -72,6 +73,7 @@ export const PLUGINS = [
     statuslineRuntime, // id "statusline:runtime"
     codegraphCapability, // id "capability:codegraph"
     codegraphExcludeIntegrity, // id "capability:codegraph-exclude-integrity"
+    codegraphIndexIntegrity, // id "capability:codegraph-index-integrity"
     distSourceVersion, // id "build:dist-version-matches-source"
     multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"

package/dist/services/doctor/doctor-service/types.d.ts

@@ -94,6 +94,23 @@ export type CodegraphExcludeIntegrityProbe = {
         readonly matchedRule: string;
     }[];
 };
+/**
+ * Structural shape of the codegraph index-integrity report the
+ * `capability:codegraph-index-integrity` check gates on. Declared
+ * structurally (rather than imported from the codegraph service) to
+ * keep this type module dependency-free — the default probe returns a
+ * `CodegraphIndexIntegrityReport`, which is assignable here.
+ */
+export type CodegraphIndexIntegrityProbe = {
+    readonly gap: boolean;
+    readonly trackedSourceCount: number;
+    readonly admittedTrackedCount: number;
+    /** Class ① — extractor-supported tracked files `include` does not admit. */
+    readonly includeGap: readonly string[];
+    readonly indexedFileCount: number;
+    /** Class ② — index rows whose path is gone from disk. */
+    readonly deadRows: readonly string[];
+};
 export type DistVersionComparison = {
     dist: string | null;
     source: string;
@@ -256,6 +273,14 @@ export type DoctorOptions = {
      * and reported as a non-blocking warning.
      */
     codegraphIntegrityProbe?: () => CodegraphExcludeIntegrityProbe | null;
+    /**
+     * Optional override for the `capability:codegraph-index-integrity`
+     * check. Returns the report, or `null` when codegraph is not
+     * initialized in the inspected root (no index to inspect). When
+     * omitted, the check inspects `process.cwd()`. Throwing is allowed
+     * and reported as a non-blocking warning.
+     */
+    codegraphIndexIntegrityProbe?: () => CodegraphIndexIntegrityProbe | null;
     skillPresenceProbe?: () => DoctorSkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
     statusLineInstalledProbe?: () => boolean;

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;