peaks-loop 4.0.29 → 4.0.31

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.0.31 — 2026-09-08 (codegraph auto-refresh 悬空 marker 修复)
+
+**Highlights**:
+
+1. **codegraph 自动刷新失效修复** — 根因：`peaks workspace init` auto-stake 只写 `.peaks-loop-marker` 不跑上游 `codegraph init`，留下无 `codegraph.db` 的悬空 `.codegraph/`；下游把"有 marker"误判为"已初始化"，post-slice 自动刷新跑 `index` 静默失败（"CodeGraph not initialized"）。
+
+   - 新增 `isCodegraphInitialized()` 按 `.codegraph/codegraph.db` 判真实初始化（对齐上游 `isInitialized`）。
+   - `workspace init` auto-stake 改为真跑上游 `codegraph init`（快、离线安全）。
+   - auto-refresh / preflight 发现悬空 marker（有 marker 无 db）时自愈：先 `init` 再 `index`。
+   - init guard 对"marker 有但 db 无"返回 `fresh`，`peaks codegraph init` 可重跑恢复。
+
+   验证：scoped 51 测试 + codegraph/workspace 73 测试全过，tsc 干净，现场自测从悬空态成功建出 `codegraph.db`。
+
+## 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):

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')
@@ -391,6 +394,28 @@ export function registerDispatchCommand(parent, io) {
                     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
@@ -424,7 +449,15 @@ export function registerDispatchCommand(parent, io) {
                 // exactOptionalPropertyTypes: only set codegraphBlock when the rd
                 // preflight actually produced a value (null = attempted-unavailable,
                 // undefined = not requested → legacy prompt unchanged).
-                ...(codegraphBlock !== undefined ? { codegraphBlock } : {})
+                ...(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
@@ -701,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/request-commands.js

@@ -1,5 +1,6 @@
 import { InvalidArgumentError } from 'commander';
-import { allowedStatesForRole, createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError, VALID_REQUEST_TYPES, isRequestType } from '../../services/artifacts/request-artifact-service.js';
+import { createRequestArtifact, listRequestArtifacts, showRequestArtifact, transitionRequestArtifact, PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError, VALID_REQUEST_TYPES } from '../../services/artifacts/request-artifact-service.js';
+import { applyPerArtifactFormat, inferArtifactName, parseRequestType, parseRole, parseStateForRole, resolveDefaultFormat, VALID_ROLES, } from './request-format-helpers.js';
 import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
 import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
 import { lintRequestArtifact } from '../../services/artifacts/artifact-lint-service.js';
@@ -7,102 +8,7 @@ import { getRepairCycleStatus } from '../../services/artifacts/repair-cycle-serv
 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';
-/**
- * Per-artifact default format. Only PRD and tech-doc are user-review
- * surfaces; all other RD/QA/TXT artifacts default to compact. The
- * `--pretty` / `--compact` flags override uniformly. See tech-doc
- * §1.3.
- */
-const DEFAULT_FORMAT_BY_ARTIFACT = {
-    prd: 'pretty',
-    'tech-doc': 'pretty',
-    'code-review': 'compact',
-    'security-review': 'compact',
-    'perf-baseline': 'compact',
-    'bug-analysis': 'compact',
-    'test-cases': 'compact',
-    'test-reports': 'compact',
-    'security-findings': 'compact',
-    'performance-findings': 'compact',
-    handoff: 'compact'
-};
-function resolveDefaultFormat(artifactName) {
-    return DEFAULT_FORMAT_BY_ARTIFACT[artifactName] ?? 'compact';
-}
-function applyPerArtifactFormat(envelope, override) {
-    if (override === null || envelope === null || typeof envelope !== 'object')
-        return envelope;
-    // The service returns `{ id, sessionId, role, body, ... }` for a
-    // single-artifact show. The per-artifact `body` field is the only
-    // thing that changes; we attach a `format` field to surface the
-    // choice to the caller. Slice 023 (R3) AC6 / AC7.
-    const obj = envelope;
-    if (typeof obj.body === 'string') {
-        return {
-            ...obj,
-            body: override === 'compact' ? formatMdCompact(obj.body) : obj.body,
-            format: override
-        };
-    }
-    return envelope;
-}
-/**
- * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
- * The service returns the path of the artifact in `path`; the role +
- * filename stem gives us the artifact name. Falls back to the role
- * itself when no `path` field is present.
- */
-function inferArtifactName(envelope, role) {
-    if (envelope === null || typeof envelope !== 'object')
-        return role;
-    const obj = envelope;
-    const pathField = typeof obj.path === 'string' ? obj.path : '';
-    // Path looks like `.peaks/_runtime/<sid>/<role>/requests/<file>.md`.
-    // The role is the second-to-last directory; the file stem is the
-    // last segment. For RD role, the artifact is one of {code-review,
-    // security-review, perf-baseline, bug-analysis, tech-doc}; the file
-    // stem usually carries the artifact name (e.g. `tech-doc.md`,
-    // `code-review-002.md`). We strip the trailing `-<digits>` suffix
-    // when present.
-    const stem = pathField.split(/[\\/]/).pop()?.replace(/\.md$/, '') ?? '';
-    if (stem.length > 0) {
-        // Try the stem verbatim first.
-        if (DEFAULT_FORMAT_BY_ARTIFACT[stem] !== undefined)
-            return stem;
-        // Strip a trailing -<digits> (e.g. code-review-002 -> code-review).
-        const trimmed = stem.replace(/-\d+$/, '');
-        if (DEFAULT_FORMAT_BY_ARTIFACT[trimmed] !== undefined)
-            return trimmed;
-        // Last-ditch: match by prefix.
-        for (const key of Object.keys(DEFAULT_FORMAT_BY_ARTIFACT)) {
-            if (stem.startsWith(key))
-                return key;
-        }
-    }
-    return role;
-}
-const VALID_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
-function parseRole(value) {
-    if (!VALID_ROLES.includes(value)) {
-        throw new InvalidArgumentError(`must be one of ${VALID_ROLES.join(', ')}`);
-    }
-    return value;
-}
-function parseStateForRole(role, value) {
-    const allowed = allowedStatesForRole(role);
-    if (!allowed.includes(value)) {
-        throw new InvalidArgumentError(`must be one of ${allowed.join(', ')} for role ${role}`);
-    }
-    return value;
-}
-function parseRequestType(value) {
-    if (!isRequestType(value)) {
-        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
-    }
-    return value;
-}
 export function registerRequestCommands(program, io) {
     const request = program.command('request').description('Manage per-request Peaks role artifacts (PRD / UI / RD / QA)');
     addJsonOption(request

package/dist/cli/commands/request-format-helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Format / parse helpers extracted from `request-commands.ts`
+ * (slice 2026-09-06-split-batch-b) so the command file stays under the
+ * 800-line cap. Behaviour-preserving verbatim move.
+ */
+import { type RequestArtifactRole, type RequestArtifactState, type RequestType } from '../../services/artifacts/request-artifact-service.js';
+export declare function resolveDefaultFormat(artifactName: string): 'compact' | 'pretty';
+export declare function applyPerArtifactFormat(envelope: unknown, override: 'pretty' | 'compact' | null): unknown;
+/**
+ * Map a request-artifact envelope to a `DEFAULT_FORMAT_BY_ARTIFACT` key.
+ * The service returns the path of the artifact in `path`; the role +
+ * filename stem gives us the artifact name. Falls back to the role
+ * itself when no `path` field is present.
+ */
+export declare function inferArtifactName(envelope: unknown, role: string): string;
+export declare const VALID_ROLES: ReadonlyArray<RequestArtifactRole>;
+export declare function parseRole(value: string): RequestArtifactRole;
+export declare function parseStateForRole(role: RequestArtifactRole, value: string): RequestArtifactState;
+export declare function parseRequestType(value: string): RequestType;