peaks-loop 4.0.34 → 4.0.36

package/dist/services/context/summary-view.js

@@ -0,0 +1,114 @@
+/**
+ * `--summary` — bounded, additive views of large CLI envelopes.
+ *
+ * Slice 2026-09-10-context-audit-and-discipline (Slice B, part 1).
+ *
+ * Rationale (measured, session 2026-09-07-session-245530): dumping a full
+ * `peaks memory reindex --json` array four times cost ≈ 160 KB ≈ 40K tokens
+ * of orchestrator context — roughly 4% of a 1M window for ONE command
+ * repeated. The default envelopes stay exactly as they are (back-compat);
+ * `--summary` is an OPT-IN view that keeps counts + names-of-first-N and
+ * drops the per-entry bodies, which remain on disk and are re-readable with
+ * the full command. No information is destroyed — only the in-context copy
+ * shrinks.
+ *
+ * Byte bound: every summary object is passed through `fitSummaryToBytes`,
+ * which shrinks string arrays (longest first) until the JSON serialization is
+ * ≤ `SUMMARY_DATA_MAX_BYTES` (2 KB minus a small envelope reserve, so the
+ * PRINTED envelope stays ≤ `SUMMARY_MAX_BYTES`). Scalars are never touched,
+ * so counts and paths stay exact.
+ */
+/** Hard ceiling for the PRINTED `--summary` envelope, in UTF-8 bytes. */
+export const SUMMARY_MAX_BYTES = 2048;
+/**
+ * Reserve for the envelope wrapper (`ok`/`command`/`warnings`/`nextActions`/
+ * error fields) that the CLI adds around `data`. The builders cap `data` at
+ * `SUMMARY_DATA_MAX_BYTES` so the whole printed envelope stays ≤ 2 KB.
+ */
+export const SUMMARY_ENVELOPE_RESERVE_BYTES = 512;
+/** Cap applied to the summary `data` object itself (pretty-printed size). */
+export const SUMMARY_DATA_MAX_BYTES = SUMMARY_MAX_BYTES - SUMMARY_ENVELOPE_RESERVE_BYTES;
+/** Per-name character cap — a name is a label, not a document. */
+export const SUMMARY_NAME_MAX_CHARS = 120;
+/** How many names each command asks for before the byte fitter trims. */
+export const SUMMARY_INITIAL_NAMES = 40;
+function clipName(name, maxChars) {
+    const collapsed = name.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars - 1)}…`;
+}
+/**
+ * Build a `{count, names}` view. `count` is always the full length; `names`
+ * carries the first `SUMMARY_INITIAL_NAMES` (clipped) entries — the byte
+ * fitter may trim further.
+ */
+export function boundedNames(names) {
+    return {
+        count: names.length,
+        names: names.slice(0, SUMMARY_INITIAL_NAMES).map((n) => clipName(n, SUMMARY_NAME_MAX_CHARS)),
+    };
+}
+/**
+ * Size of the value AS PRINTED — `printResult` serializes with `null, 2`, so
+ * the bound must be measured on the pretty form, not the compact one.
+ */
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value, null, 2) ?? '', 'utf8');
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/** Collect every array (with its key path) nested in `node`. */
+function collectArrays(node, path, out) {
+    if (Array.isArray(node)) {
+        out.push({ path, array: node });
+        return;
+    }
+    if (typeof node !== 'object' || node === null)
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        collectArrays(value, path === '' ? key : `${path}.${key}`, out);
+    }
+}
+/**
+ * Shrink `data` (in place on a clone) until its JSON form fits `maxBytes`.
+ *
+ * Algorithm: repeatedly find the LONGEST nested array and drop its last
+ * element. Scalars are never modified, so `count` fields stay truthful; the
+ * `names` arrays simply show fewer names. Returns the input unchanged when it
+ * already fits or when there is no array left to trim.
+ */
+export function fitSummaryToBytes(data, maxBytes = SUMMARY_DATA_MAX_BYTES) {
+    let out;
+    try {
+        out = structuredClone(data);
+    }
+    catch {
+        try {
+            out = JSON.parse(JSON.stringify(data));
+        }
+        catch {
+            return data; // not serializable — leave the caller's object alone
+        }
+    }
+    // Each iteration removes one element, so the bound is the total element
+    // count — a cheap upper limit that can never spin forever.
+    for (let guard = 0; guard < 100_000; guard++) {
+        if (byteLength(out) <= maxBytes)
+            return out;
+        const arrays = [];
+        collectArrays(out, '', arrays);
+        let longest = null;
+        for (const candidate of arrays) {
+            if (candidate.array.length === 0)
+                continue;
+            if (longest === null || candidate.array.length > longest.array.length)
+                longest = candidate;
+        }
+        if (longest === null)
+            return out; // nothing left to shrink
+        longest.array.pop();
+    }
+    return out;
+}

package/dist/services/dispatch/file-overlap-wave-planner.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §3 — file-overlap-aware
+ * parallel scheduling.
+ *
+ * Problem: fan-out is mandatory, but the orchestrator serializes whenever
+ * two slices touch the same file (observed 2026-09-07: two slices both
+ * edited `src/cli/commands/code-runtime-commands.ts`, forcing a wait).
+ * Topological DAG levels do not know about files, so a "parallel" level can
+ * still contain a write/write conflict.
+ *
+ * Solution: a pure planner over slice descriptors `{ id, files[] }` that
+ * returns WAVES. Every slice in a wave has a file set pairwise disjoint
+ * from every other slice in that wave. A slice whose files collide with an
+ * earlier wave is deferred to a later wave, and the plan records WHICH file
+ * collided with WHICH already-scheduled slice — so the caller can explain
+ * the serialization instead of silently waiting.
+ *
+ * Pure: no I/O, no clock, deterministic for a given input.
+ *
+ * Relationship to `planDispatchWaves` (dag-orchestrator.ts): that planner
+ * chunks a topological level by `maxConcurrency` only. This planner is
+ * orthogonal — it refines a level (or any slice set) by file overlap. The
+ * `--from-dag` path uses this one additively (see `firstLevelWaves` in the
+ * dispatch envelope); the topological scheduler itself is unchanged.
+ */
+/** One unit of work and the files it is expected to touch. */
+export interface SliceFileDescriptor {
+    readonly id: string;
+    readonly files: readonly string[];
+}
+/** Why a slice did not land in the first wave it was considered for. */
+export interface WaveDeferral {
+    readonly id: string;
+    /** Wave the slice was placed in. */
+    readonly waveIndex: number;
+    /** The file that collided. */
+    readonly collidingFile: string;
+    /** The slice already scheduled in an earlier wave that holds that file. */
+    readonly collidedWith: string;
+    /** Human-readable one-liner (stable wording). */
+    readonly reason: string;
+}
+export interface FileOverlapWave {
+    readonly waveIndex: number;
+    /** Slice ids in input order. */
+    readonly slices: readonly string[];
+    /** Union of the wave's files, sorted. */
+    readonly files: readonly string[];
+    /** Deferrals resolved INTO this wave. */
+    readonly deferred: readonly WaveDeferral[];
+}
+export interface FileOverlapWavePlan {
+    readonly waves: readonly FileOverlapWave[];
+    /** Slice ids that appeared more than once; only the first is scheduled. */
+    readonly duplicateIds: readonly string[];
+    /** Number of distinct slices scheduled. */
+    readonly sliceCount: number;
+}
+/**
+ * Plan waves such that no two slices in the same wave share a file.
+ *
+ * Greedy, input-order stable: each slice goes into the earliest existing
+ * wave whose files are disjoint from its own; otherwise a new wave is
+ * opened. A slice with no files never collides.
+ *
+ * Duplicate ids: the FIRST descriptor wins; later ones are reported in
+ * `duplicateIds` and not scheduled (scheduling the same slice twice would
+ * double-dispatch it).
+ */
+export declare function planFileOverlapWaves(slices: readonly SliceFileDescriptor[]): FileOverlapWavePlan;

package/dist/services/dispatch/file-overlap-wave-planner.js

@@ -0,0 +1,119 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §3 — file-overlap-aware
+ * parallel scheduling.
+ *
+ * Problem: fan-out is mandatory, but the orchestrator serializes whenever
+ * two slices touch the same file (observed 2026-09-07: two slices both
+ * edited `src/cli/commands/code-runtime-commands.ts`, forcing a wait).
+ * Topological DAG levels do not know about files, so a "parallel" level can
+ * still contain a write/write conflict.
+ *
+ * Solution: a pure planner over slice descriptors `{ id, files[] }` that
+ * returns WAVES. Every slice in a wave has a file set pairwise disjoint
+ * from every other slice in that wave. A slice whose files collide with an
+ * earlier wave is deferred to a later wave, and the plan records WHICH file
+ * collided with WHICH already-scheduled slice — so the caller can explain
+ * the serialization instead of silently waiting.
+ *
+ * Pure: no I/O, no clock, deterministic for a given input.
+ *
+ * Relationship to `planDispatchWaves` (dag-orchestrator.ts): that planner
+ * chunks a topological level by `maxConcurrency` only. This planner is
+ * orthogonal — it refines a level (or any slice set) by file overlap. The
+ * `--from-dag` path uses this one additively (see `firstLevelWaves` in the
+ * dispatch envelope); the topological scheduler itself is unchanged.
+ */
+/**
+ * Plan waves such that no two slices in the same wave share a file.
+ *
+ * Greedy, input-order stable: each slice goes into the earliest existing
+ * wave whose files are disjoint from its own; otherwise a new wave is
+ * opened. A slice with no files never collides.
+ *
+ * Duplicate ids: the FIRST descriptor wins; later ones are reported in
+ * `duplicateIds` and not scheduled (scheduling the same slice twice would
+ * double-dispatch it).
+ */
+export function planFileOverlapWaves(slices) {
+    const duplicateIds = [];
+    const seenIds = new Set();
+    const ordered = [];
+    for (const slice of slices) {
+        if (typeof slice?.id !== 'string' || slice.id.length === 0)
+            continue;
+        if (seenIds.has(slice.id)) {
+            duplicateIds.push(slice.id);
+            continue;
+        }
+        seenIds.add(slice.id);
+        ordered.push({ id: slice.id, files: normalizeFiles(slice.files) });
+    }
+    const waves = [];
+    for (const slice of ordered) {
+        // First wave whose file set is disjoint from this slice's.
+        let placedAt = -1;
+        let collision = null;
+        for (let w = 0; w < waves.length; w += 1) {
+            const wave = waves[w];
+            if (wave === undefined)
+                continue;
+            let hit = null;
+            for (const file of slice.files) {
+                const owner = wave.owner.get(file);
+                if (owner !== undefined) {
+                    hit = { file, withSlice: owner };
+                    break;
+                }
+            }
+            if (hit === null) {
+                placedAt = w;
+                break;
+            }
+            // Remember the FIRST collision (earliest wave) for the reason string.
+            if (collision === null) {
+                collision = { file: hit.file, withSlice: hit.withSlice, waveIndex: w };
+            }
+        }
+        if (placedAt === -1) {
+            placedAt = waves.length;
+            waves.push({ slices: [], files: new Set(), owner: new Map(), deferred: [] });
+        }
+        const target = waves[placedAt];
+        if (target === undefined)
+            continue; // unreachable; satisfies strict TS
+        target.slices.push(slice.id);
+        for (const file of slice.files) {
+            target.files.add(file);
+            target.owner.set(file, slice.id);
+        }
+        if (collision !== null && placedAt > 0) {
+            target.deferred.push({
+                id: slice.id,
+                waveIndex: placedAt,
+                collidingFile: collision.file,
+                collidedWith: collision.withSlice,
+                reason: `deferred to wave ${placedAt}: file "${collision.file}" already scheduled in wave ${collision.waveIndex} by slice "${collision.withSlice}"`
+            });
+        }
+    }
+    return {
+        waves: waves.map((w, index) => ({
+            waveIndex: index,
+            slices: w.slices,
+            files: [...w.files].sort(),
+            deferred: w.deferred
+        })),
+        duplicateIds,
+        sliceCount: ordered.length
+    };
+}
+function normalizeFiles(files) {
+    if (!Array.isArray(files))
+        return [];
+    const set = new Set();
+    for (const f of files) {
+        if (typeof f === 'string' && f.length > 0)
+            set.add(f);
+    }
+    return [...set].sort();
+}

package/dist/services/dispatch/session-capsule.d.ts

@@ -0,0 +1,23 @@
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export declare const SESSION_CAPSULE_BATCH_ID = "session-capsule";
+/** Reserved key inside that channel. */
+export declare const SESSION_CAPSULE_KEY = "orchestrator.capsule";
+export interface SessionCapsuleRef {
+    readonly batchId: string;
+    readonly key: string;
+    /** Byte size of the published value (for the pointer line). */
+    readonly bytes: number;
+    /** ISO8601 timestamp of the last write. */
+    readonly updatedAt: string;
+}
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export declare function readSessionCapsule(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+}): SessionCapsuleRef | null;

package/dist/services/dispatch/session-capsule.js

@@ -0,0 +1,56 @@
+/**
+ * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule reader.
+ *
+ * The orchestrator publishes already-known background ONCE per session
+ * through the existing G8.4 channel:
+ *
+ *   peaks sub-agent share \
+ *     --batch session-capsule \
+ *     --key orchestrator.capsule \
+ *     --value '{"rootCauses":[...],"decisions":[...],"fileMap":{...}}'
+ *
+ * Dispatch prompts then carry a one-line `shared-read` pointer instead of
+ * re-explaining that background in every task spec.
+ *
+ * QUALITY GUARD: the capsule is ADVISORY BACKGROUND ONLY. Nothing a
+ * sub-agent must ACT on may live only in the capsule — the task spec is
+ * authoritative and wins on conflict. The precedence sentence is rendered
+ * by `renderCapsulePointer` in build-dispatch-system-prompt.ts and is not
+ * optional when the pointer is emitted.
+ *
+ * This module only READS. Publishing is the orchestrator's job through the
+ * already-shipped `peaks sub-agent share` primitive — no new write path.
+ */
+import { readSharedChannel } from 'peaks-loop-shared-channel';
+/** Reserved batch id for the session capsule (matches the channel path pattern). */
+export const SESSION_CAPSULE_BATCH_ID = 'session-capsule';
+/** Reserved key inside that channel. */
+export const SESSION_CAPSULE_KEY = 'orchestrator.capsule';
+/**
+ * Read the session capsule, if one was published. Returns `null` when the
+ * channel is absent, empty, or unreadable — the dispatch prompt then
+ * renders neither the pointer nor the precedence line (byte-identical to
+ * the pre-slice shape).
+ */
+export function readSessionCapsule(opts) {
+    try {
+        const channel = readSharedChannel({
+            projectRoot: opts.projectRoot,
+            sid: opts.sid,
+            rid: opts.rid,
+            batchId: SESSION_CAPSULE_BATCH_ID
+        });
+        const entry = channel.entries[SESSION_CAPSULE_KEY];
+        if (entry === undefined)
+            return null;
+        return {
+            batchId: SESSION_CAPSULE_BATCH_ID,
+            key: SESSION_CAPSULE_KEY,
+            bytes: entry.valueSize,
+            updatedAt: entry.at
+        };
+    }
+    catch {
+        return null; // fail-soft: a missing capsule never blocks a dispatch
+    }
+}

package/dist/services/dispatch/slice-dag.d.ts

@@ -31,6 +31,15 @@ export interface SliceNode {
      * (complex = user-attended, simple/trivial = overnight). Optional.
      */
     readonly complexity?: SliceComplexity;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §3: files this slice is
+     * expected to touch. When EVERY node of a topological level declares
+     * `files`, `--from-dag` emits a file-overlap wave plan (`firstLevelWaves`)
+     * so the LLM can fan the level out without serializing on a shared file.
+     * Optional and additive: absent → DAG hash and dispatch behavior are
+     * byte-identical to before this slice.
+     */
+    readonly files?: readonly string[];
 }
 export interface DependsOn {
     readonly from: string;

package/dist/services/dispatch/slice-dag.js

@@ -103,6 +103,11 @@ export function validateDag(dag) {
         if (n.complexity !== undefined && !isSliceComplexity(n.complexity)) {
             throw new InvalidSliceDagError(`node ${n.id} complexity must be one of ${SLICE_COMPLEXITIES.join('|')} when present`);
         }
+        // Slice 2026-09-10 §3: optional file list. Only shape-checked when
+        // present so pre-existing DAGs stay valid.
+        if (n.files !== undefined && (!Array.isArray(n.files) || n.files.some((f) => typeof f !== 'string' || f.length === 0))) {
+            throw new InvalidSliceDagError(`node ${n.id} files must be an array of non-empty strings when present`);
+        }
     }
     // v2.15.0 follow-up — G12 defensive rule: foundation slice can only
     // depend on another foundation slice. Business depending on foundation
@@ -219,7 +224,10 @@ export function serializeDag(dag) {
         // (only when present, preserving hash stability for old DAGs).
         ...(n.foundation !== undefined ? { foundation: n.foundation } : {}),
         ...(n.upstreamSync !== undefined ? { upstreamSync: n.upstreamSync } : {}),
-        ...(n.complexity !== undefined ? { complexity: n.complexity } : {})
+        ...(n.complexity !== undefined ? { complexity: n.complexity } : {}),
+        // Slice 2026-09-10 §3: only present when declared, so the hash of a
+        // file-less DAG is unchanged.
+        ...(n.files !== undefined ? { files: [...n.files] } : {})
     }));
     const edges = [...dag.edges]
         .sort((a, b) => {

package/dist/services/dispatch/test-tool-detection.d.ts

@@ -26,8 +26,19 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
-export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\n## Test Scope (mandatory)\n\nThe dispatched test command MUST be **scoped** to a single file or pattern. An unscoped `./node_modules/.bin/vitest run` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:\n\n- **scoped**    \u2192 `./node_modules/.bin/vitest run tests/unit/foo.test.ts` (or any explicit file/pattern)\n- **intentional full run** \u2192 prefix with the explicit opt-in token `PEAKS_FULL_TEST=1` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.\n- **refused**   \u2192 bare `./node_modules/.bin/vitest run` (no argument after `run`) without the opt-in token.\n\n`pnpm test` / `pnpm test:unit` / `pnpm test:cli` / `pnpm test:integration` and any repo-defined `test*` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern; a bare `./node_modules/.bin/vitest run` is **refused** unless you prefix the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification).\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

package/dist/services/dispatch/test-tool-detection.js

@@ -26,26 +26,27 @@
  *  "remove the redundancy" of a test-tool-detection instruction because
  *  the dispatch CLI always prepends it. This is a guarantee, not a
  *  suggestion.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): ONE block for EVERY role. The
+ * runner-table EXAMPLES were dropped — they were never rules, and
+ * `package.json#scripts.test` is the source of truth at run time — while
+ * the one missing real rule is stated inline: PB-5, i.e. repo-defined
+ * `test` / `test:*` scripts are the human/LLM direct path and are NOT
+ * gated by the scope rule. The soft fallback ("only as a last resort, ask
+ * the user before assuming a runner") and the Windows-aware note on
+ * `peaks test <file>` are RETAINED — they are quality guidance, not
+ * examples. No role split remains, so every role receives a byte-identical
+ * block.
  */
 export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
 
-Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
-
-- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
-- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
-- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
+Read \`package.json#scripts.test\` for the project's framework and use the project-local runner — do NOT invoke \`npx <runner>\`. If unsure, run \`peaks test --json\` first. Only as a last resort, ask the user before assuming a runner. \`peaks test <file>\` already resolves the local binary for you (Windows-aware).
 
 ## Test Scope (mandatory)
 
-The dispatched test command MUST be **scoped** to a single file or pattern. An unscoped \`./node_modules/.bin/vitest run\` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:
-
-- **scoped**    → \`./node_modules/.bin/vitest run tests/unit/foo.test.ts\` (or any explicit file/pattern)
-- **intentional full run** → prefix with the explicit opt-in token \`PEAKS_FULL_TEST=1\` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.
-- **refused**   → bare \`./node_modules/.bin/vitest run\` (no argument after \`run\`) without the opt-in token.
-
-\`pnpm test\` / \`pnpm test:unit\` / \`pnpm test:cli\` / \`pnpm test:integration\` and any repo-defined \`test*\` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).
+Any test command MUST be **scoped** to a single file or pattern; a bare \`./node_modules/.bin/vitest run\` is **refused** unless you prefix the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification).
 
-If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
+Repo-defined \`test\` / \`test:*\` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).`;
 /**
  * Pure helper that returns the block. Exists as a function (not just an
  * exported constant) so future variants can take a runtime parameter

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

@@ -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,6 +10,24 @@
  *
  * 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 type { DoctorCheckPlugin } from '../types.js';
 export declare const check: DoctorCheckPlugin;