peaks-loop 4.0.51 → 4.0.53

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/prd/handoff-gate-evidence.d.ts

@@ -0,0 +1 @@
+export declare function readHandoffGateEvidence(filePath: string): Promise<readonly string[] | null>;

package/dist/services/prd/handoff-gate-evidence.js

@@ -0,0 +1,77 @@
+// src/services/prd/handoff-gate-evidence.ts
+//
+// AC-5 of slice 2026-09-17-4-0-51-cleanup: the handoff's frontmatter
+// carries a `gateEvidence: string[]` field naming the gate names whose
+// `gateEvidence` is asserted by this handoff. Pre-S2, the field was
+// written into the frontmatter (by `initHandoff`) but NO consumer in
+// `src/` ever READ it back — the field was prose, not data.
+//
+// This module is the SOLE reader for that field. It is a stand-alone
+// reader (not a member of `handoff-service.ts`) so that the
+// `HandoffFrontmatter` type stays a pure-data shape and this consumer
+// can be added independently without disturbing every existing
+// parse-and-validate path.
+//
+// Returns:
+//   - `string[]`  — the gate names declared in the frontmatter
+//   - `null`      — the file is missing, the frontmatter is malformed,
+//                   the field is absent, or the field is not an array
+//                   of strings. Callers MUST treat null as "no claim"
+//                   and not as a failure.
+//
+// The reader is intentionally permissive (returns null instead of
+// throwing) because a malformed frontmatter is the caller's signal to
+// surface the failure to the operator, not the reader's signal to
+// throw inside the gate pipeline.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+function parseGateEvidenceFrontmatter(raw) {
+    // Frontmatter is the `---`-fenced YAML block at the top of the file.
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return { gateEvidence: null };
+    const yamlBody = match[1] ?? '';
+    let parsed;
+    try {
+        parsed = parseYaml(yamlBody);
+    }
+    catch (_error) {
+        // reader is permissive by design: malformed YAML → no claim (not throw)
+        void _error;
+        return { gateEvidence: null };
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return { gateEvidence: null };
+    const gateEvidence = parsed['gateEvidence'];
+    if (!Array.isArray(gateEvidence))
+        return { gateEvidence: null };
+    return { gateEvidence };
+}
+export async function readHandoffGateEvidence(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch (_error) {
+        // reader is permissive by design: missing file → no claim (not throw)
+        void _error;
+        return null;
+    }
+    try {
+        const { gateEvidence } = parseGateEvidenceFrontmatter(raw);
+        if (gateEvidence === null)
+            return null;
+        // Filter to strings only — a non-string element (number/boolean/
+        // null) is treated as "not a gate name" rather than as an error.
+        const strings = gateEvidence.filter((item) => typeof item === 'string');
+        return strings.length > 0 ? strings : null;
+    }
+    catch (_error) {
+        // reader is permissive by design: unexpected parse failure → no claim
+        void _error;
+        return null;
+    }
+}

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

package/dist/services/workspace/runtime-layout.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+/**
+ * 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 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 const RUNTIME_SYSTEM_ENTRIES = [
+    {
+        name: 'change',
+        kind: 'dir',
+        purpose: 'change-id routing root for reviewable artifacts (workflow/artifact-paths.ts, prd/prd-blocks-checker.ts, workspace/reconcile-service.ts)'
+    },
+    {
+        name: 'callers',
+        kind: 'dir',
+        purpose: 'per-caller binding files `.peaks/_runtime/callers/<callerId>.json` (session/caller-binding-service.ts)'
+    },
+    {
+        name: 'benchmarks',
+        kind: 'dir',
+        purpose: '`peaks slice benchmark` artifacts `<rid>.benchmark.json` (cli/commands/slice-commands.ts)'
+    },
+    {
+        name: 'prd',
+        kind: 'dir',
+        purpose: 'read-only PRD artifact root `.peaks/_runtime/prd/requests/<rid>.md` (prd/prd-blocks-checker.ts); the writer lives outside this repo, the check tolerates it'
+    },
+    {
+        name: 'playwright-userdata',
+        kind: 'dir',
+        purpose: 'per-terminal browser profile dirs (cli/commands/playwright-commands.ts)'
+    },
+    {
+        name: 'playwright-sessions',
+        kind: 'dir',
+        purpose: 'playwright session records `<terminalId>.json` (cli/commands/playwright-commands.ts)'
+    },
+    {
+        name: 'test-cache',
+        kind: 'dir',
+        purpose: 'per-test fingerprint cache (cli/commands/test-commands.ts)'
+    },
+    {
+        name: 'sop-state',
+        kind: 'dir',
+        purpose: 'SOP state migrated from `.peaks/sop-state/` (cli/commands/workspace/reconcile-command.ts)'
+    },
+    {
+        name: RUNTIME_SESSIONLESS_SCOPE,
+        kind: 'dir',
+        purpose: 'capability-audit output for session-less runs `.peaks/_runtime/_audit/capability-audit/*.json` (cli/commands/baseline-commands.ts)'
+    },
+    {
+        name: 'session.json',
+        kind: 'file',
+        purpose: 'project-global session binding (session/session-binding-service.ts)'
+    },
+    {
+        name: 'active-skill.json',
+        kind: 'file',
+        purpose: 'active-skill presence marker (skills/skill-presence-service.ts)'
+    },
+    {
+        name: 'generated-artifacts.json',
+        kind: 'file',
+        purpose: 'stamp describing which generated artifacts exist on this machine, so a refresh can tell "stale" from "never generated" (services/workspace/generated-artifacts-stamp.ts)'
+    },
+    {
+        name: '.outer-session-cache.json',
+        kind: 'file',
+        purpose: 'outer (IDE) session cache for CLI sub-processes (cli/commands/outer-cache-commands.ts, session/session-binding-bridge.ts)'
+    },
+    {
+        name: '.rebuild-binding.lock',
+        kind: 'file',
+        purpose: 'binding-store rebuild lock (session/binding-store.ts)'
+    }
+];
+/**
+ * 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 const RUNTIME_SYSTEM_SUBDIRS = new Set(RUNTIME_SYSTEM_ENTRIES.filter((entry) => entry.kind === 'dir').map((entry) => entry.name));

package/dist/services/workspace/workspace-claude-settings-materializer.js

@@ -163,6 +163,20 @@ const PEAKS_GITIGNORE_SNIPPET = [
     '# Both patterns below are PROJECT-ROOT-relative, so this snippet must land',
     '# in the root .gitignore — see `upsertPeaksGitignoreSnippet`.',
     '.peaks/.claude-settings-template.json',
+    '# Codegraph rollback copy (A3, 2026-09-17). Every `peaks codegraph init` /',
+    '# `repair-exclude` / `repair-index` / pre-dispatch preflight / post-slice',
+    '# auto-refresh copies `.codegraph/config.json` here before rewriting it, so',
+    '# this file is LOCAL CHURN: a committed one is silently replaced by the next',
+    '# repair. Upstream\'s own `.codegraph/.gitignore` does not cover it (it names',
+    '# *.db / *.db-wal / *.db-shm, cache/, *.log and .dirty only) and `.codegraph/`',
+    '# is NOT ignored wholesale downstream, so without this line a consumer project',
+    '# commits a file peaks-loop rewrites under it.',
+    '#',
+    '# ONLY the backup, never `config.json` itself: upstream deliberately keeps',
+    '# that config committable (it is a project\'s include/exclude policy, and',
+    '# committing it is how a team shares it), so ignoring it would hide a file',
+    '# people mean to commit. A rollback copy is the opposite kind of file.',
+    '.codegraph/config.json.bak',
     PEAKS_GITIGNORE_FOOTER,
     ''
 ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.51",
+  "version": "4.0.53",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.36",
-    "peaks-loop-mut": "0.1.49",
-    "peaks-loop-shared": "0.0.85",
-    "peaks-loop-shared-channel": "0.0.53"
+    "peaks-loop-shared": "0.0.87",
+    "peaks-loop-internal-runtime": "0.0.38",
+    "peaks-loop-mut": "0.1.51",
+    "peaks-loop-shared-channel": "0.0.55"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -128,7 +128,7 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs && node ./scripts/write-dist-stamp.mjs",
     "prepublish": "node ./scripts/sync-version.mjs",
     "postinstall": "node ./scripts/install-skills.mjs",
     "predev": "node ./scripts/sync-version.mjs",

package/scripts/clean-dist.mjs

@@ -10,9 +10,21 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 // packages/*/dist. Rationale: tsc's incremental-build cache
 // compares files by mtime + size, and a stale dist that
 // survived from a previous build can cause tsc to skip the
-// emission of newly-added src/*.ts (Bug-04 lineage — see
-// tests/unit/scripts/sync-version-invalidation.test.ts for
-// the regression pin on version.ts specifically).
+// emission of newly-added src/*.ts (Bug-04 lineage).
+//
+// E2 (rid 2026-09-17-cli-output-and-stale-refs) — the citation that
+// stood here named a regression pin on version.ts that was deleted
+// in `f17aa377` ("delete 559 legacy unit tests"), and, like the one
+// in `sync-version.mjs`, it was written without backticks so the
+// citation-integrity guard could not see it. Corrected: the pin on
+// the version.ts OUTPUT now lives in the lockstep tests (see
+// `sync-version.mjs` for both names and for what they read).
+//
+// Recorded, not hidden: this wipe itself has no direct pin — no
+// test executes this script, so nothing asserts that a stale
+// packages/*/dist is gone before tsc runs. The `dist-freshness.mjs`
+// module reasons FROM this wipe (it is why a dist mtime can be read
+// as the build time) but does not test it.
 //
 // The wider wipe is safe because:
 //   - watch.mjs only watches src/, schemas/, skills/ — it