peaks-loop 4.0.28 → 4.0.29

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 4.0.29 — 2026-09-03 (codegraph 生命周期闭环 — pre-read + auto-refresh)
+
+**3 atomic commits from session 2026-09-03-session-d49394** (user feedback #3):
+
+- `7b9fe627` feat(codegraph): auto-refresh index after slice completion (CLI-internal trigger)
+- `b6599b56` feat(codegraph): preflight project structure into RD dispatch prompts
+- `dfbd229e` docs(memory): sediment codegraph lifecycle closure (pre-read + auto-refresh)
+
+**Highlights**:
+
+1. **slice/request 完成后自动刷新 codegraph** — `job checkpoint --state done` / `request transition --state qa-handoff` 成功后自动 `peaks codegraph index`。CLI-internal 触发（vendor-neutral、不可绕过、恰在 slice 边界 fire 一次），best-effort fail-silent（codegraph 失败不阻塞 checkpoint）。16 个新 BDD 测试。
+
+2. **RD 规划前强制读 codegraph 结构** — peaks-code dispatch RD 前 preflight：确保 index（无则 init+index，fresh 则跳过，foreign-schema fail-soft）+ 读有界 `codegraph files --json` 结构（cap 40 dirs / 12 root files）渲染 `## Codegraph structure` 块注入 RD prompt。codegraph 不可用 → 优雅降级 note，dispatch 照常。13 个新 BDD 测试。
+
+3. 闭环成型：规划前 pre-read（Slice B）→ 实现 → 完成后 auto-refresh（Slice A）→ 下一 slice 读到新图。
+
 ## 4.0.28 — 2026-09-03 (codegraph 目录回根 + env-first 1M 窗口识别)
 
 **3 atomic commits from session 2026-09-03-session-d49394** (user feedback batch):

package/dist/cli/commands/dispatch-commands.js

@@ -371,6 +371,26 @@ export function registerDispatchCommand(parent, io) {
             // pure-function builder.
             const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
             const memoryBlock = await preflightService.fetchBlock(role);
+            // Slice 2026-09-03-codegraph-preread (Option A): pre-dispatch
+            // codegraph preflight for RD planning. BEFORE the RD sub-agent's
+            // prompt is composed, ensure the codegraph index exists (init +
+            // index best-effort when `.codegraph/` is absent; skip when already
+            // fresh) and read a BOUNDED project-structure summary. The block is
+            // only requested for the `rd` role — other roles keep the legacy
+            // prompt byte-identical. Fail-soft: any codegraph failure degrades
+            // to a null block (builder renders the "codegraph unavailable" note)
+            // and the dispatch proceeds; we never hard-block RD dispatch here.
+            let codegraphBlock;
+            if (role === 'rd') {
+                try {
+                    const { buildCodegraphPreflightBlock } = await import('../../services/codegraph/codegraph-preflight-service.js');
+                    const preflight = await buildCodegraphPreflightBlock(projectRoot);
+                    codegraphBlock = preflight.available ? preflight.block : null;
+                }
+                catch {
+                    codegraphBlock = null; // fail-soft: never block RD dispatch
+                }
+            }
             // Slice 2026-07-29-context-evaluation-accuracy: capture the
             // authoritative context-fill probe before composing the
             // dispatch prompt. The probe is token-counted (IDE adapter's
@@ -400,7 +420,11 @@ export function registerDispatchCommand(parent, io) {
                 taskTitle: role,
                 taskBody: options.prompt,
                 memoryBlock,
-                contextProbe
+                contextProbe,
+                // exactOptionalPropertyTypes: only set codegraphBlock when the rd
+                // preflight actually produced a value (null = attempted-unavailable,
+                // undefined = not requested → legacy prompt unchanged).
+                ...(codegraphBlock !== undefined ? { codegraphBlock } : {})
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
             // block so the sub-agent sees the lease id + worktree path. The block

package/dist/cli/commands/job-commands.js

@@ -13,6 +13,7 @@ import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } fr
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { buildCostCheckEnvelope, runKarpathyCostCheck, } from '../../services/karpathy-cost/karpathy-cost-check-service.js';
 import { read24hState } from '../../services/24h-mode/store.js';
+import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 function projectRoot(opts) {
     // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
     return opts.project ?? process.cwd();
@@ -172,6 +173,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         const jobRoot = resolveJobStateRoot(opts);
         const store = new JobStateStore(jobRoot.rootDir);
         const orch = new JobOrchestrator(store);
+        // 2026-09-03-codegraph-autorefresh: set on --state done so the ok
+        // envelope carries a non-blocking `codegraph` result; null for
+        // failed/skipped (no slice-complete boundary).
+        let codegraph = null;
         if (parsed.data.state === 'done') {
             await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
             // v3.1.2: after each --state done, mirror slice progress to
@@ -188,6 +193,14 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
                 lastCommitSha: parsed.data.commitSha ?? null,
                 updatedAt: new Date().toISOString()
             });
+            // Auto codegraph refresh at the slice-complete boundary. Best-effort
+            // and fail-silent: a refresh failure must never fail the checkpoint.
+            try {
+                codegraph = await refreshCodegraphAfterSlice(project);
+            }
+            catch (e) {
+                codegraph = { refreshed: false, reason: 'unavailable', note: `auto codegraph refresh failed: ${e instanceof Error ? e.message : String(e)}` };
+            }
         }
         else if (parsed.data.state === 'skipped') {
             await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
@@ -195,7 +208,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         else {
             await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
         }
-        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state, codegraph }), opts);
     });
     addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
     job

package/dist/cli/commands/request-commands.js

@@ -6,6 +6,7 @@ import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-serv
 import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
+import { refreshCodegraphAfterSlice, } from '../../services/codegraph/codegraph-autorefresh.js';
 import { formatMdCompact } from '../../shared/format-md-compact.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 /**
@@ -353,6 +354,10 @@ export function registerRequestCommands(program, io) {
             // unchanged — the existing auto-compact orchestrator continues to
             // refuse dispatch at ratio ≥ 0.95.
             let preCompact = null;
+            // 2026-09-03-codegraph-autorefresh: auto codegraph re-index on the
+            // RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
+            // otherwise. Best-effort and fail-silent — never blocks the transition.
+            let codegraphRefresh = null;
             if (role === 'rd' && newState === 'qa-handoff') {
                 try {
                     const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
@@ -369,6 +374,13 @@ export function registerRequestCommands(program, io) {
                     // The hook is best-effort; never block the transition.
                     preCompact = null;
                 }
+                try {
+                    codegraphRefresh = await refreshCodegraphAfterSlice(options.project);
+                }
+                catch {
+                    // The refresh is best-effort; never block the transition.
+                    codegraphRefresh = { refreshed: false, reason: 'unavailable', note: 'auto codegraph refresh failed after transition' };
+                }
             }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
@@ -410,7 +422,7 @@ export function registerRequestCommands(program, io) {
             // transition is not a slice boundary), preCompact is null and
             // we emit a `preCompactCheckpoint: null` field so LLM callers
             // can branch on it without re-deriving zone membership.
-            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null }, preCompact !== null
+            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null, codegraphRefresh }, preCompact !== null
                 ? [
                     `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
                         ? String(preCompact.data.ratio)

package/dist/services/codegraph/codegraph-autorefresh.d.ts

@@ -0,0 +1,22 @@
+import { type CodegraphProcessRunner } from './codegraph-service.js';
+export type CodegraphAutorefreshResult = {
+    refreshed: true;
+} | {
+    refreshed: false;
+    reason: 'no-codegraph-dir' | 'index-failed' | 'unavailable';
+    note: string;
+};
+/**
+ * True when `<projectRoot>/.codegraph/` exists and is a directory.
+ * Pure fs probe; never throws.
+ */
+export declare function isCodegraphPresent(projectRoot: string): boolean;
+/**
+ * Run a best-effort `codegraph index` refresh for `projectRoot` after a
+ * slice-complete boundary. NEVER throws — every failure path returns a
+ * non-refreshed result so the caller keeps its ok envelope.
+ *
+ * The optional `runner` is a test seam mirroring
+ * `CodegraphProcessRunner`; when omitted the real process runner is used.
+ */
+export declare function refreshCodegraphAfterSlice(projectRoot: string, runner?: CodegraphProcessRunner): Promise<CodegraphAutorefreshResult>;

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -0,0 +1,91 @@
+// src/services/codegraph/codegraph-autorefresh.ts
+//
+// Slice 2026-09-03-codegraph-autorefresh — Option 1: CLI-internal
+// auto codegraph refresh at the slice-complete boundary.
+//
+// `peaks codegraph index` is incremental + idempotent, so re-running it
+// after a slice that changed code is cheap and safe. Rather than rely on
+// the orchestrator LLM to remember the prose rule in
+// `skills/peaks-code/references/codegraph-orchestration.md` ("MUST
+// proactively run `peaks codegraph index --project <path>` after each
+// slice"), the checkpoint/transition command itself triggers the refresh
+// right before it returns its ok envelope. This is the vendor-neutral
+// CLI-internal form of "hook on slice-complete": it is un-bypassable
+// (fires even when the LLM dispatches the command through any IDE / no
+// hook install surface needed), fires exactly once at the true slice
+// boundary, and needs no IDE hook plumbing.
+//
+// The refresh is best-effort and FAIL-SILENT — it never throws and never
+// blocks the checkpoint/transition ok envelope:
+//   - No `<projectRoot>/.codegraph/` directory → skip (codegraph was
+//     never initialized for this project; `peaks codegraph init` is a
+//     one-time setup the orchestrator owns).
+//   - The upstream index exits non-zero → return `index-failed` with a
+//     human-readable note.
+//   - Any unexpected error → return `unavailable` with a note.
+//
+// We deliberately do NOT auto-init: `codegraph init` can prompt / take a
+// long time on first run, which would make the background side-effect
+// block the slice boundary. Projects that want auto-refresh first run
+// `peaks codegraph init` once (per the orchestration doc).
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, executeCodegraphInvocation, } from './codegraph-service.js';
+/**
+ * True when `<projectRoot>/.codegraph/` exists and is a directory.
+ * Pure fs probe; never throws.
+ */
+export function isCodegraphPresent(projectRoot) {
+    try {
+        return statSync(join(projectRoot, CODEGRAPH_DIR_NAME)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstMeaningfulLine(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 'no upstream output';
+    const first = trimmed.split(/\r?\n/)[0];
+    return first !== undefined ? first.slice(0, 200) : 'no upstream output';
+}
+/**
+ * Run a best-effort `codegraph index` refresh for `projectRoot` after a
+ * slice-complete boundary. NEVER throws — every failure path returns a
+ * non-refreshed result so the caller keeps its ok envelope.
+ *
+ * The optional `runner` is a test seam mirroring
+ * `CodegraphProcessRunner`; when omitted the real process runner is used.
+ */
+export async function refreshCodegraphAfterSlice(projectRoot, runner) {
+    if (!isCodegraphPresent(projectRoot)) {
+        return {
+            refreshed: false,
+            reason: 'no-codegraph-dir',
+            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
+        };
+    }
+    try {
+        const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
+        const result = await executeCodegraphInvocation(invocation, runner);
+        if (result.exitCode !== 0) {
+            return {
+                refreshed: false,
+                reason: 'index-failed',
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+            };
+        }
+        return { refreshed: true };
+    }
+    catch (error) {
+        return {
+            refreshed: false,
+            reason: 'unavailable',
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}`,
+        };
+    }
+}

package/dist/services/codegraph/codegraph-preflight-service.d.ts

@@ -0,0 +1,53 @@
+import { type CodegraphProcessRunner } from './codegraph-service.js';
+export type CodegraphPreflightResult = {
+    available: true;
+    block: string;
+    fileCount: number;
+    truncated: boolean;
+} | {
+    available: false;
+    note: string;
+};
+/** Cap for the directory histogram in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+export interface CodegraphStructureFileEntry {
+    readonly path: string;
+}
+export interface CodegraphStructureRenderOptions {
+    readonly maxDirs?: number;
+    readonly maxRootFiles?: number;
+}
+export interface CodegraphStructureSummary {
+    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
+    block: string;
+    total: number;
+    truncated: boolean;
+}
+/**
+ * Pure renderer: turn the codegraph `files --json` payload into a bounded
+ * `## Codegraph structure` block. Files are aggregated into a directory
+ * histogram (immediate parent dir; bare root files bucket separately),
+ * sorted by file count descending then name ascending, and capped at
+ * `maxDirs` rows / `maxRootFiles` root entries. Exported separately so the
+ * bounded-output contract is unit-testable without a filesystem.
+ */
+export declare function renderCodegraphStructureBlock(files: readonly CodegraphStructureFileEntry[], options?: CodegraphStructureRenderOptions): CodegraphStructureSummary;
+/**
+ * Pre-dispatch codegraph preflight. Returns a `## Codegraph structure`
+ * block when the index is (or becomes) readable; otherwise an
+ * `{ available: false, note }` result. NEVER throws — the caller must be
+ * able to degrade gracefully on every failure path.
+ *
+ * Behavior matrix (acceptance criteria):
+ * - `.codegraph/` absent  → init + index (best-effort), then read.
+ * - `.codegraph/` present with peaks-loop marker → skip init/index
+ *   (fresh), read directly. No redundant re-index on every dispatch.
+ * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
+ *   never clobber a foreign store.
+ *
+ * The optional `runner` mirrors `CodegraphProcessRunner` and is the ONLY
+ * injected boundary (tests fake the upstream binary).
+ */
+export declare function buildCodegraphPreflightBlock(projectRoot: string, runner?: CodegraphProcessRunner): Promise<CodegraphPreflightResult>;

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -0,0 +1,226 @@
+// src/services/codegraph/codegraph-preflight-service.ts
+//
+// Slice 2026-09-03-codegraph-preread (Option A) — pre-dispatch codegraph
+// preflight for RD planning. peaks-code's RD dispatch path calls
+// `buildCodegraphPreflightBlock` BEFORE composing the RD sub-agent prompt
+// (src/cli/commands/dispatch-commands.ts) so the RD plans against the real
+// module/file topology in the codegraph index, not LLM memory.
+//
+// The service does three things, all best-effort and fail-soft (it NEVER
+// throws — every failure returns `{ available: false, note }` so the caller
+// degrades to a "codegraph unavailable — proceeding on project-scan only"
+// note and dispatch proceeds):
+//
+//   1. Ensure the schema exists: when `<projectRoot>/.codegraph/` is
+//      absent, run `codegraph init` + `codegraph index` (best-effort).
+//   2. Skip-when-fresh: when `.codegraph/` already carries the
+//      peaks-loop marker, do NOT re-init / re-index on every dispatch
+//      (index is incremental; the sibling rid-2026-09-03-codegraph-autorefresh
+//      owns post-slice refresh). A foreign-schema `.codegraph/` is never
+//      clobbered — we fail-soft instead.
+//   3. Read a BOUNDED project-structure summary from the index
+//      (`codegraph files --json`) and render it as a `## Codegraph
+//      structure` markdown block.
+//
+// Bounded-output contract: the rendered block never exceeds a safe prompt
+// budget. The pure renderer `renderCodegraphStructureBlock` caps the
+// directory histogram at CODEGRAPH_STRUCTURE_MAX_DIRS rows and the root-file
+// listing at CODEGRAPH_STRUCTURE_MAX_ROOT_FILES entries; anything beyond
+// those caps is summarized with a "… and N more" line and a `truncated: true`
+// flag. Documented caps:
+//   - CODEGRAPH_STRUCTURE_MAX_DIRS        = 40  directory rows
+//   - CODEGRAPH_STRUCTURE_MAX_ROOT_FILES  = 12  bare root files
+import { mkdirSync } from 'node:fs';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker, } from './codegraph-service.js';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+/** Cap for the directory histogram in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+function normalizeCodegraphPath(path) {
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+/**
+ * Pure renderer: turn the codegraph `files --json` payload into a bounded
+ * `## Codegraph structure` block. Files are aggregated into a directory
+ * histogram (immediate parent dir; bare root files bucket separately),
+ * sorted by file count descending then name ascending, and capped at
+ * `maxDirs` rows / `maxRootFiles` root entries. Exported separately so the
+ * bounded-output contract is unit-testable without a filesystem.
+ */
+export function renderCodegraphStructureBlock(files, options = {}) {
+    const maxDirs = options.maxDirs ?? CODEGRAPH_STRUCTURE_MAX_DIRS;
+    const maxRootFiles = options.maxRootFiles ?? CODEGRAPH_STRUCTURE_MAX_ROOT_FILES;
+    const dirCounts = new Map();
+    const rootFiles = [];
+    let total = 0;
+    for (const file of files) {
+        const raw = normalizeCodegraphPath(file.path).replace(/\\/g, '/');
+        if (raw.length === 0)
+            continue;
+        total += 1;
+        const slash = raw.lastIndexOf('/');
+        if (slash === -1) {
+            rootFiles.push(raw);
+            continue;
+        }
+        const dir = raw.slice(0, slash);
+        dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+    }
+    const sortedDirs = [...dirCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const shownDirs = sortedDirs.slice(0, maxDirs);
+    const truncatedDirs = sortedDirs.length > maxDirs;
+    const sortedRoot = [...rootFiles].sort((a, b) => a.localeCompare(b));
+    const shownRoot = sortedRoot.slice(0, maxRootFiles);
+    const truncatedRoot = sortedRoot.length > maxRootFiles;
+    const lines = ['## Codegraph structure', ''];
+    lines.push(total === 0
+        ? 'No files are indexed yet. Run `peaks codegraph index` before dispatching planning work for symbol-accurate structure.'
+        : `${total} file${total === 1 ? '' : 's'} indexed in the codegraph index:`);
+    for (const [dir, count] of shownDirs) {
+        lines.push(`- \`${dir}/\` — ${count} file${count === 1 ? '' : 's'}`);
+    }
+    if (truncatedDirs) {
+        lines.push(`- … and ${sortedDirs.length - maxDirs} more director${sortedDirs.length - maxDirs === 1 ? 'y' : 'ies'}`);
+    }
+    if (sortedRoot.length > 0) {
+        lines.push(`- (root) — ${shownRoot.map((f) => `\`${f}\``).join(', ')}${truncatedRoot ? ' …' : ''}`);
+    }
+    const block = lines.join('\n').replace(/\s+$/, '') + '\n\n';
+    return { block, total, truncated: truncatedDirs || truncatedRoot };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstMeaningfulLine(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 'no upstream output';
+    const first = trimmed.split(/\r?\n/)[0];
+    return first !== undefined ? first.slice(0, 200) : 'no upstream output';
+}
+function parseFilesPayload(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            const entries = parsed
+                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
+                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
+                .filter((entry) => entry.path.length > 0);
+            return { ok: true, entries };
+        }
+        // JSON but not an array — not the shape we expect.
+        return { ok: false, entries: [] };
+    }
+    catch {
+        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
+        return { ok: false, entries: [] };
+    }
+}
+async function readStructure(projectRoot, runner) {
+    let result;
+    try {
+        const invocation = createCodegraphInvocation({ subcommand: 'files', project: projectRoot, json: true });
+        result = await executeCodegraphInvocation(invocation, runner);
+    }
+    catch (error) {
+        return { available: false, note: `codegraph files unavailable: ${errorMessage(error)}` };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            available: false,
+            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+        };
+    }
+    const { ok, entries } = parseFilesPayload(result.stdout);
+    if (!ok) {
+        return {
+            available: false,
+            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            available: false,
+            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    const summary = renderCodegraphStructureBlock(entries);
+    return {
+        available: true,
+        block: summary.block,
+        fileCount: summary.total,
+        truncated: summary.truncated,
+    };
+}
+/**
+ * Pre-dispatch codegraph preflight. Returns a `## Codegraph structure`
+ * block when the index is (or becomes) readable; otherwise an
+ * `{ available: false, note }` result. NEVER throws — the caller must be
+ * able to degrade gracefully on every failure path.
+ *
+ * Behavior matrix (acceptance criteria):
+ * - `.codegraph/` absent  → init + index (best-effort), then read.
+ * - `.codegraph/` present with peaks-loop marker → skip init/index
+ *   (fresh), read directly. No redundant re-index on every dispatch.
+ * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
+ *   never clobber a foreign store.
+ *
+ * The optional `runner` mirrors `CodegraphProcessRunner` and is the ONLY
+ * injected boundary (tests fake the upstream binary).
+ */
+export async function buildCodegraphPreflightBlock(projectRoot, runner) {
+    const processRunner = runner ?? defaultCodegraphProcessRunner;
+    const guard = defaultCodegraphInitGuard(projectRoot);
+    if (guard.status === 'conflict-foreign-schema') {
+        return {
+            available: false,
+            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`,
+        };
+    }
+    if (guard.status === 'fresh') {
+        // 1. init (best-effort). Upstream creates the `.codegraph/` dir; we
+        //    stamp the peaks-loop marker afterwards so the NEXT dispatch hits
+        //    the noop (skip-when-fresh) branch.
+        try {
+            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), processRunner);
+            if (initResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                };
+            }
+            try {
+                // Upstream init creates `.codegraph/`; mkdir is a no-op in the real
+                // path and lets the marker write succeed even when the runner is
+                // faked (tests). Best-effort: failure must not undo the init.
+                mkdirSync(guard.codegraphDir, { recursive: true });
+                writeCodegraphMarker(guard.codegraphDir);
+            }
+            catch {
+                // Best-effort: a marker-write failure must not undo the init.
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph init unavailable: ${errorMessage(error)}` };
+        }
+        // 2. index (best-effort).
+        try {
+            const indexResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true }), processRunner);
+            if (indexResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`,
+                };
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph index unavailable: ${errorMessage(error)}` };
+        }
+    }
+    // guard.status === 'noop-already-peaks-loop' (or we just initialized):
+    // the schema exists — do NOT re-index, go straight to the bounded read.
+    return readStructure(projectRoot, processRunner);
+}

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -28,6 +28,20 @@ export interface DispatchPromptInput {
      * a byte-counted estimate.
      */
     contextProbe?: ContextPercentProbe | null;
+    /**
+     * Slice 2026-09-03-codegraph-preread (Option A): pre-composed
+     * `## Codegraph structure` markdown block, read from the codegraph
+     * index BEFORE the RD sub-agent's task body is composed so the RD
+     * plans against real module/file topology, not LLM memory.
+     *
+     * - `undefined` → no codegraph block (legacy callers unchanged).
+     * - `null` → codegraph was attempted but is unavailable; the composer
+     *   renders a fixed "codegraph unavailable — proceeding on project-scan
+     *   only" note (fail-soft; never hard-blocks a dispatch).
+     * - `string` → the block, rendered verbatim between the context window
+     *   and the memory/task content.
+     */
+    codegraphBlock?: string | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
@@ -88,6 +102,10 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -99,3 +117,11 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * refusal is in scope before any task-specific prose arrives.
  */
 export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): string;
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export declare const CODEGRAPH_UNAVAILABLE_BLOCK = "## Codegraph structure\n\ncodegraph unavailable \u2014 proceeding on project-scan only.\n";

package/dist/services/context/build-dispatch-system-prompt.js

@@ -83,6 +83,10 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -94,12 +98,40 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
+    const codegraphText = renderCodegraphBlock(codegraphBlock);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${taskBody}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${taskBody}`;
+}
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export const CODEGRAPH_UNAVAILABLE_BLOCK = '## Codegraph structure\n\ncodegraph unavailable — proceeding on project-scan only.\n';
+/**
+ * Render the codegraph insertion for a dispatch prompt.
+ *
+ * - `undefined` → empty (the composer is byte-identical to the legacy
+ *   shape for callers that did not opt into a codegraph pre-read).
+ * - `null` → the fixed CODEGRAPH_UNAVAILABLE_BLOCK note.
+ * - `string` → the pre-composed block from the codegraph preflight
+ *   service, verbatim.
+ *
+ * Every non-empty variant is normalized to end on its own paragraph
+ * (`\n\n`) so the following block (project memory or task body) starts
+ * cleanly regardless of the caller's trailing newline habits.
+ */
+function renderCodegraphBlock(codegraphBlock) {
+    if (codegraphBlock === undefined)
+        return '';
+    const text = codegraphBlock === null ? CODEGRAPH_UNAVAILABLE_BLOCK : codegraphBlock;
+    return `${text.replace(/\s+$/, '')}\n\n`;
 }
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.28",
+  "version": "4.0.29",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.13",
-    "peaks-loop-mut": "0.1.26",
-    "peaks-loop-shared": "0.0.62",
-    "peaks-loop-shared-channel": "0.0.30"
+    "peaks-loop-internal-runtime": "0.0.14",
+    "peaks-loop-mut": "0.1.27",
+    "peaks-loop-shared-channel": "0.0.31",
+    "peaks-loop-shared": "0.0.63"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",