peaks-loop 4.0.28 → 4.0.30

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 4.0.30 — 2026-09-07 (搜索优先 preflight + 超行文件拆分 + CLI 漂移修复)
+
+**Highlights**:
+
+1. **搜索优先 preflight（fresh-context）** — 编排层新增信号触发的「先搜再答」：`peaks fresh-context preflight` 做确定性信号扫描，命中则搜 Context7+WebSearch，合成 ≤5 条「绑定指令」（用 X / 别用 Y / 因为 Z）注入 PRD/RD 派发提示词，对冲模型训练数据 2 个月滞后。带权威框架 + 全局 kill-switch + fail-soft 降级 + job 内缓存。
+
+2. **9 个超行文件拆分** — `src/` 全部源文件降至 ≤800 行（Karpathy §2 红线）：dispatch-record-writer 1376→774、dispatch-commands 961→752、worktree-auth-commands 1032→312、slice-decompose-service 1014→765、auto-compact-orchestrator 999→756、hooks-settings-service 875→642、skill-statusline-renderer 873→646、project-standards-service 862→644、reconcile-service 861→649、request-commands 806→712。
+
+3. **CLI 漂移修复** — 修复 request-id 大小写敏感（buildNumberedFilename 小写化 slug vs lookup case-sensitive）与子代理覆盖 session 绑定两个 bug；补全 `peaks sub-agent dispatch` 强制 `--graph-node` 的文档。
+
+4. **`peaks evidence generate`** — 一键生成 slice 的 11 个证据工件，收敛编排仪式开销。
+
+5. **UI 组件库优先注入** — RD/UI 派发提示词直接注入检测到的组件库（`## Project stack` 块），前端开发优先用已装组件库而非原生 DOM。
+
+## 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/_register.js

@@ -19,10 +19,12 @@ import { registerDocCommands } from './doc-commands.js';
 import { registerE2EVerifyCommand } from './e2e-verify.js';
 import { registerEccCommands } from './ecc-commands.js';
 import { registerEvolutionCommands } from './evolution-commands.js';
+import { registerEvidenceCommands } from './evidence-commands.js';
 import { registerFeedbackCommands } from './feedback-commands.js';
 import { registerFinalReviewCommands } from './final-review-commands.js';
 import { registerFixtureCommands } from './fixture-commands.js';
 import { registerForkCommands } from './fork-commands.js';
+import { registerFreshContextCommands } from './fresh-context-commands.js';
 import { registerGateCommands } from './gate-commands.js';
 import { registerClassifyCommands, registerContractCommands } from './governance-classify-contract-commands.js';
 import { registerHookHandleCommand } from './hook-handle.js';
@@ -117,6 +119,8 @@ const REGISTRATIONS = [
     ['skill-loop-engineering-readiness-commands', registerSkillLoopEngineeringReadinessCommands],
     ['loop-commands', registerLoopCommands], ['loop-eval-commands', registerWorkflowEvalCommands],
     ['evolution-commands', registerEvolutionCommands], ['asset-commands', registerAssetCommands],
+    ['evidence-commands', registerEvidenceCommands],
+    ['fresh-context-commands', registerFreshContextCommands],
     ['bee-commands', registerBeeCommands], ['ecc-commands', registerEccCommands],
     ['baseline-commands', registerBaselineCommands],
     ['upgrade-commands', registerUpgradeCommands], ['code-review-commands', registerCodeReviewCommands],

package/dist/cli/commands/dispatch-commands.d.ts

@@ -2,45 +2,9 @@ import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerDispatchCommand(parent: Command, io: ProgramIO): void;
 /**
- * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
- * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
- * `git ls-files <glob>` against `projectRoot` and returns the matching
- * tracked file paths (relative to projectRoot). Empty array when no
- * files match (e.g. untracked new file, wrong glob, not a git repo).
- *
- * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
- * is "the file the sub-agent claims to have written must ACTUALLY be
- * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
- * would happily return untracked-but-on-disk files (false-positive
- * for the fake-green gate).
- *
- * Failure modes (best-effort, never throws):
- *  - git not on PATH → empty array (`ENOENT` swallowed)
- *  - not a git repo → empty array (git exits non-zero)
- *  - glob matches zero tracked files → empty array
- *
- * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
- * The export is intentional — the helper has zero side effects and
- * keeps the dispatch action handler small.
+ * 2.7.0 slice-dag-dispatcher MVP — see `dispatch-from-dag.ts`.
+ * The function was pulled out of this file in slice 2026-06-23-audit-3rd
+ * #7 to honor the 800-line file cap and isolate the three heavy
+ * module loads (slice-dag / dag-orchestrator / contract-store) to the
+ * --from-dag codepath only.
  */
-export declare function runGitLsFiles(projectRoot: string, glob: string): readonly string[];
-/**
- * `dispatchSubAgent` is the thin programmatic wrapper the integration
- * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
- * It enforces --graph-node required BEFORE any record write so a
- * caller can't bypass the CLI's requiredOption guard. Throws a typed
- * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
- */
-export declare function dispatchSubAgent(input: {
-    projectRoot: string;
-    role: string;
-    prompt: string;
-    sessionId?: string;
-    graphNode?: string;
-    workflowId?: string;
-    graphRef?: string;
-}): Promise<{
-    role: string;
-    toolCall: unknown;
-    dispatchRecordPath: string | null;
-}>;

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

@@ -16,7 +16,6 @@
  */
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { spawn as childProcessSpawn } from 'node:child_process';
 import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { detectInstalledIde } from '../../services/ide/ide-detector.js';
@@ -39,7 +38,11 @@ import { runDispatchFromDag } from './dispatch-from-dag.js';
 import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
 import { MemoryPreflightService } from '../../services/context/memory-preflight-service.js';
 import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch-system-prompt.js';
+import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-library-dispatch-block.js';
+import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
 import { createDispatchProvenanceToken, DISPATCH_PROVENANCE_ENV, writeDispatchProvenance, } from '../../services/worktree/dispatch-provenance.js';
+import { spawnWorktreeLease, spawnContainerLease } from '../../services/dispatch/isolation-lease.js';
+import { runGitLsFiles } from '../../services/dispatch/dispatch-sub-agent.js';
 export function registerDispatchCommand(parent, io) {
     addJsonOption(parent
         .command('dispatch')
@@ -371,6 +374,48 @@ 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-09-06-ui-lib-dispatch-priority: surface the detected
+            // component library (+ CSS framework + build tool) in the RD/UI
+            // dispatch system prompt so the sub-agent prefers the library over
+            // hand-rolled native DOM. Only injected for frontend-generating roles
+            // (rd + ui) — qa/sc/txt/prd keep the legacy prompt byte-identical.
+            // Fail-soft inside the wrapper: a detection error degrades to null.
+            let projectStackBlock;
+            if (role === 'rd' || role === 'ui') {
+                projectStackBlock = computeUiLibraryDispatchBlock(projectRoot);
+            }
+            // Slice 2026-09-07-search-first-preflight: read the orchestrator-
+            // synthesized fresh-context block for rd + prd dispatches. The block
+            // was written to .peaks/_runtime/<sid>/fresh-context.md when the
+            // preflight triggered; it carries ≤5 binding directives that hedge
+            // model training-data lag. Fail-soft: a missing / unreadable file, or
+            // a file without the `## Fresh context` heading, degrades to null so
+            // the prompt stays byte-identical to the legacy shape. Other roles
+            // (qa/sc/txt/ui) keep the legacy prompt unchanged.
+            let freshContextBlock;
+            if (role === 'rd' || role === 'prd') {
+                freshContextBlock = readFreshContextBlock(projectRoot, sid);
+            }
             // 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 +445,19 @@ 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 } : {}),
+                // Same optionality contract for the project-stack block: set only
+                // when the rd/ui detection ran (null = no library → no block,
+                // undefined = non-frontend role → legacy prompt unchanged).
+                ...(projectStackBlock !== undefined ? { projectStackBlock } : {}),
+                // Same optionality contract for the fresh-context block: set only
+                // when the rd/prd read ran (null = no block on disk → no block,
+                // undefined = non-rd/prd role → legacy prompt unchanged).
+                ...(freshContextBlock !== undefined ? { freshContextBlock } : {})
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
             // block so the sub-agent sees the lease id + worktree path. The block
@@ -677,186 +734,3 @@ export function registerDispatchCommand(parent, io) {
  * module loads (slice-dag / dag-orchestrator / contract-store) to the
  * --from-dag codepath only.
  */
-/**
- * Part 2.C (slice 2026-07-29-worktree-l2-extended) — spawn a worktree
- * lease by shelling out to `peaks worktree spawn` (avoid re-implementing
- * the lease-write + git-worktree-add sequence in this file). The CLI
- * does the lease write, the git worktree add, AND the error handling;
- * we just parse the JSON envelope and surface the leaseId + path.
- *
- * Throws on spawn failure; the caller converts the error to a
- * ISOLATION_SPAWN_FAILED envelope. Synchronous wait is acceptable: the
- * dispatch is already async, the lease is a few hundred ms of FS work,
- * and we need the leaseId before we build the dispatch record.
- */
-function spawnWorktreeLease(args) {
-    return new Promise((resolve, reject) => {
-        const child = childProcessSpawn(process.execPath, [
-            // The compiled CLI lives in dist/cli/peaks.js. We pass the entry
-            // through node so the test suite (which also runs on the same
-            // process) and the production binary share the same path. When
-            // the binary is invoked as `peaks`, the package bin stub does
-            // this for us; here we explicitly use process.execPath + the
-            // resolved entry to avoid PATH surprises.
-            process.argv[1] ?? '',
-            'worktree', 'spawn',
-            '--rid', args.rid,
-            '--role', args.role,
-            '--purpose', args.purpose,
-            '--project', args.projectRoot,
-            '--session', args.sessionId,
-            '--json'
-        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
-        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
-        child.on('error', (err) => reject(new Error(`worktree spawn subprocess failed: ${err.message}`)));
-        child.on('close', (code) => {
-            if (code !== 0) {
-                reject(new Error(`peaks worktree spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
-                return;
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(stdout);
-            }
-            catch (err) {
-                reject(new Error(`peaks worktree spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
-                return;
-            }
-            if (typeof parsed !== 'object' || parsed === null) {
-                reject(new Error('peaks worktree spawn envelope is not an object'));
-                return;
-            }
-            const env = parsed;
-            if (env.ok !== true || !env.data?.lease) {
-                reject(new Error(`peaks worktree spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
-                return;
-            }
-            resolve({
-                leaseId: env.data.lease.leaseId,
-                path: env.data.lease.path,
-                branch: env.data.lease.branch,
-                expiresAt: env.data.lease.expiresAt
-            });
-            // Part 47: unref via setImmediate so the close handler
-            // finishes first and Node's stdio 'end' events drain the
-            // stdout/stderr buffers before the parent releases the
-            // child handle. Without this microtask defer, the unref
-            // races the buffered stdout close and the test receives
-            // an empty JSON envelope.
-            setImmediate(() => { child.unref(); });
-        });
-    });
-}
-/**
- * Slice 2026-07-29-worktree-l2-extended Part 12: container
- * isolation bridge. Shells out to `peaks container spawn` to
- * run `docker run` + write the container lease. Returns the
- * leaseId the dispatch record needs to persist. The shape is
- * a subset of the spawnWorktreeLease return (just leaseId);
- * we do not need the path/branch/expiresAt for the container
- * path because the envelope surfaces a different set of
- * fields (image + containerId; see container-lease.ts).
- */
-function spawnContainerLease(args) {
-    return new Promise((resolve, reject) => {
-        const child = childProcessSpawn(process.execPath, [
-            process.argv[1] ?? '',
-            'container', 'spawn',
-            '--rid', args.rid,
-            '--role', args.role,
-            '--purpose', args.purpose,
-            '--project', args.projectRoot,
-            '--session', args.sessionId,
-            '--json'
-        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
-        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
-        child.on('error', (err) => reject(new Error(`container spawn subprocess failed: ${err.message}`)));
-        child.on('close', (code) => {
-            if (code !== 0) {
-                reject(new Error(`peaks container spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
-                return;
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(stdout);
-            }
-            catch (err) {
-                reject(new Error(`peaks container spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
-                return;
-            }
-            if (typeof parsed !== 'object' || parsed === null) {
-                reject(new Error('peaks container spawn envelope is not an object'));
-                return;
-            }
-            const env = parsed;
-            if (env.ok !== true || !env.data?.lease) {
-                reject(new Error(`peaks container spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
-                return;
-            }
-            resolve({ leaseId: env.data.lease.leaseId });
-        });
-        // See spawnWorktreeLease above for the rationale.
-        child.unref();
-    });
-}
-/**
- * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
- * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
- * `git ls-files <glob>` against `projectRoot` and returns the matching
- * tracked file paths (relative to projectRoot). Empty array when no
- * files match (e.g. untracked new file, wrong glob, not a git repo).
- *
- * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
- * is "the file the sub-agent claims to have written must ACTUALLY be
- * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
- * would happily return untracked-but-on-disk files (false-positive
- * for the fake-green gate).
- *
- * Failure modes (best-effort, never throws):
- *  - git not on PATH → empty array (`ENOENT` swallowed)
- *  - not a git repo → empty array (git exits non-zero)
- *  - glob matches zero tracked files → empty array
- *
- * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
- * The export is intentional — the helper has zero side effects and
- * keeps the dispatch action handler small.
- */
-export function runGitLsFiles(projectRoot, glob) {
-    try {
-        const { execFileSync } = require('node:child_process');
-        const stdout = execFileSync('git', ['ls-files', '--', glob], { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
-        return stdout.split('\n').filter((line) => line.length > 0);
-    }
-    catch {
-        return [];
-    }
-}
-/* ---------- Slice 4.0.8 RD §4 D4c: programmatic dispatcher ---------- */
-/**
- * `dispatchSubAgent` is the thin programmatic wrapper the integration
- * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
- * It enforces --graph-node required BEFORE any record write so a
- * caller can't bypass the CLI's requiredOption guard. Throws a typed
- * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
- */
-export async function dispatchSubAgent(input) {
-    if (typeof input.graphNode !== 'string' || input.graphNode.length === 0) {
-        const err = new Error('PEAKS_GRAPH_NODE_REQUIRED: --graph-node is required (RD §4 D4c)');
-        err.code = 'PEAKS_GRAPH_NODE_REQUIRED';
-        throw err;
-    }
-    // The integration test only checks the rejection path; the success
-    // path is exercised by the existing CLI command. Return a minimal
-    // stub so any future programmatic caller has a stable surface.
-    return {
-        role: input.role,
-        toolCall: null,
-        dispatchRecordPath: null,
-    };
-}

package/dist/cli/commands/evidence-commands.d.ts

@@ -0,0 +1,12 @@
+/**
+ * peaks evidence * CLI surface — mechanical per-slice evidence generation.
+ *
+ * `peaks evidence generate` writes the ~11 per-slice evidence artifacts under
+ * `.peaks/_runtime/<sid>/` so the orchestrator no longer hand-writes them for
+ * a mechanical file-split (or similar) slice. The body builders live in
+ * `services/evidence/evidence-generator.ts`; this module only wires the
+ * Commander surface + project/session resolution + JSON envelope.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerEvidenceCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,43 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { generateEvidence, parseFiles, parseLineCounts } from '../../services/evidence/evidence-generator.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+export function registerEvidenceCommands(program, io) {
+    const evidence = program.command('evidence').description('Generate per-slice evidence artifacts for mechanical slices');
+    addJsonOption(evidence
+        .command('generate')
+        .description('Write the ~11 rd/qa/audit/prd evidence artifacts for a mechanical file-split slice under .peaks/_runtime/<sid>/')
+        .requiredOption('--rid <rid>', 'request id (e.g. 2026-09-06-split-dispatch-commands)')
+        .requiredOption('--title <title>', 'one-line description of the slice')
+        .requiredOption('--files <list>', 'comma-separated changed file paths')
+        .requiredOption('--line-counts <list>', 'semicolon-separated file=lines pairs (e.g. "f=120;g=300")')
+        .option('--session-id <sid>', 'session id; defaults to the project-bound session')).action(async (options) => {
+        try {
+            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+            const sessionId = options.sessionId ?? getSessionId(projectRoot);
+            if (sessionId === null || sessionId === undefined || sessionId.length === 0) {
+                printResult(io, fail('evidence.generate', 'SESSION_NOT_BOUND', 'No --session-id was provided and no peaks session is bound for this project.', { projectRoot }, ['Pass --session-id <sid>, or run `peaks workspace init` first so a session directory exists.']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const files = parseFiles(options.files ?? '');
+            const lineCounts = parseLineCounts(options.lineCounts ?? '');
+            const result = await generateEvidence({
+                projectRoot,
+                rid: options.rid ?? '',
+                title: options.title ?? '',
+                files,
+                lineCounts,
+                sessionId
+            });
+            printResult(io, ok('evidence.generate', result, [], [
+                `Wrote ${result.writtenFiles.length} evidence files under ${result.sessionRoot}`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('evidence.generate', 'EVIDENCE_GENERATE_FAILED', getErrorMessage(error), {}, ['Verify the target project is writable.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/fresh-context-commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `peaks fresh-context preflight` CLI — deterministic trigger scan for the
+ * search-first preflight (slice 2026-09-07-search-first-preflight).
+ *
+ * This command is the shared, deterministic surface every peaks-* orchestrator
+ * calls at orchestration-start, BEFORE the first planning action, to decide
+ * whether to search fresh context (Context7 → WebSearch) and synthesize binding
+ * directives. The actual search + synthesis is done by the LLM per the shared
+ * `skills/peaks-code/references/fresh-context-preflight.md`; this command only
+ * runs the pure trigger scan (`services/fresh-context/trigger-scan.ts`) and the
+ * kill-switch read (`services/fresh-context/config.ts`).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerFreshContextCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/fresh-context-commands.js

@@ -0,0 +1,24 @@
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { scanFreshContextTrigger } from '../../services/fresh-context/trigger-scan.js';
+import { isFreshContextEnabled } from '../../services/fresh-context/config.js';
+export function registerFreshContextCommands(program, io) {
+    const freshContext = program
+        .command('fresh-context')
+        .description('Search-first preflight for the orchestration layer (hedge training-data lag)');
+    addJsonOption(freshContext
+        .command('preflight')
+        .description('Deterministic signal scan: report whether the prompt triggers a fresh-context search')
+        .requiredOption('--prompt <text>', 'the user request text to scan for trigger keywords')
+        .option('--project <root>', 'target project root (accepted for surface parity; the scan is text + config only)')).action((options) => {
+        try {
+            const enabled = isFreshContextEnabled();
+            const result = scanFreshContextTrigger(options.prompt ?? '', enabled);
+            printResult(io, ok('fresh-context.preflight', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('fresh-context.preflight', 'PREFLIGHT_FAILED', getErrorMessage(error), {}, ['Verify ~/.peaks/config.json is valid JSON']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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