peaks-loop 4.0.28 → 4.0.30

package/dist/services/workspace/reconcile-service.d.ts

@@ -108,78 +108,6 @@ export declare function syncChangeMarker(projectRoot: string, canonicalSessionId
     created: string | null;
     error: string | null;
 };
-/**
- * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
- *
- * Move the legacy runtime files at:
- *   - `.peaks/.session.json`
- *   - `.peaks/.active-skill.json`
- *   - `.peaks/sop-state/`
- * into their new canonical home at:
- *   - `.peaks/_runtime/session.json`
- *   - `.peaks/_runtime/active-skill.json`
- *   - `.peaks/_runtime/sop-state/`
- *
- * Behavior:
- *   - Idempotent: re-running on a tree that is already on the new
- *     layout produces `migratedFiles: []`.
- *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
- *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
- *     rename throws (e.g. cross-device move on Windows). Errors are
- *     collected per file and returned in the `errors` array so the
- *     reconcile envelope can surface them without blocking the rest of
- *     the migration.
- *   - Creates `.peaks/_runtime/` on demand if any of the old paths
- *     are present.
- *
- * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
- *   *old* relative paths (e.g. `.peaks/.session.json`) that were
- *   successfully moved, in move order. `errors` lists per-file
- *   failures with the old path and a human-readable message.
- */
-export declare function migrateOldRuntimeState(projectRoot: string): {
-    migratedFiles: string[];
-    errors: Array<{
-        path: string;
-        message: string;
-    }>;
-};
-/**
- * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
- *
- * Move the legacy per-session sub-agent state files at:
- *   - `.peaks/_runtime/<sid>/system/subagent-progress.json`
- *   - `.peaks/_runtime/<sid>/system/progress-spawn.json`
- * into the new canonical home at:
- *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
- *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
- *
- * Behavior:
- *   - Idempotent: re-running on a tree that is already on the new layout
- *     produces `migratedFiles: []`.
- *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
- *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
- *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
- *     subdir is only removed when it has zero other files, so a tree where
- *     the user had unrelated content in `system/` is left untouched.
- *   - New-path-wins: when both old and new files exist, the old file is
- *     removed (the new path is authoritative).
- *
- * Walks every discovered session — not just the canonical one — so a user
- * with 6 pre-migration sessions gets all of them migrated in one reconcile
- * pass.
- *
- * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
- *   relative paths (e.g. `.peaks/_runtime/<sid>/system/subagent-progress.json`) that
- *   were successfully moved. `errors` lists per-file failures.
- */
-export declare function migrateSubAgentState(projectRoot: string): {
-    migratedFiles: string[];
-    errors: Array<{
-        path: string;
-        message: string;
-    }>;
-};
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,

package/dist/services/workspace/reconcile-service.js

@@ -16,43 +16,12 @@
  * Pure hand-rolled; uses only node:fs, node:path, and the existing
  * session-manager helper for writing the binding. No new dependencies.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
+import { migrateOldRuntimeState, migrateSubAgentState } from './reconcile-migrate.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
 const META_FILE = 'session.json';
-// Sub-agent state file basenames (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
-// The legacy location was `.peaks/_runtime/<sid>/system/<filename>`; the canonical new
-// location is `.peaks/_sub_agents/<sid>/<filename>`. `migrateSubAgentState`
-// moves the two files between these homes on every `reconcileWorkspace` run.
-const SUB_AGENT_MIGRATION_FILES = [
-    'subagent-progress.json',
-    'progress-spawn.json'
-];
-const SUB_AGENTS_DIR = '_sub_agents';
-// As of slice 2026-06-05-peaks-runtime-layer these old paths are the
-// back-compat read-only fallbacks; the canonical new home is
-// `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
-// location on disk. The leading dot is dropped when computing the
-// new basename (e.g. `.session.json` → `session.json`), so the new
-// layout is `.peaks/_runtime/{session.json,active-skill.json,sop-state/}`.
-const RUNTIME_OLD_PATHS = [
-    '.session.json',
-    '.active-skill.json',
-    'sop-state'
-];
-const RUNTIME_DIR = join('.peaks', '_runtime');
-/**
- * Map a legacy path basename (e.g. `.session.json`) to its canonical
- * new basename (e.g. `session.json`). The dot is dropped so the new
- * layer reads naturally. Directories pass through unchanged.
- */
-function runtimeNewBasename(oldBasename) {
-    if (oldBasename.startsWith('.') && oldBasename.length > 1) {
-        return oldBasename.slice(1);
-    }
-    return oldBasename;
-}
 /**
  * Walk the project root's `.peaks/` directory and return an entry per
  * session dir matching the standard naming pattern, sorted by name
@@ -394,192 +363,6 @@ export function syncChangeMarker(projectRoot, canonicalSessionId) {
     }
     return { removed, created, error };
 }
-/**
- * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
- *
- * Move the legacy runtime files at:
- *   - `.peaks/.session.json`
- *   - `.peaks/.active-skill.json`
- *   - `.peaks/sop-state/`
- * into their new canonical home at:
- *   - `.peaks/_runtime/session.json`
- *   - `.peaks/_runtime/active-skill.json`
- *   - `.peaks/_runtime/sop-state/`
- *
- * Behavior:
- *   - Idempotent: re-running on a tree that is already on the new
- *     layout produces `migratedFiles: []`.
- *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
- *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
- *     rename throws (e.g. cross-device move on Windows). Errors are
- *     collected per file and returned in the `errors` array so the
- *     reconcile envelope can surface them without blocking the rest of
- *     the migration.
- *   - Creates `.peaks/_runtime/` on demand if any of the old paths
- *     are present.
- *
- * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
- *   *old* relative paths (e.g. `.peaks/.session.json`) that were
- *   successfully moved, in move order. `errors` lists per-file
- *   failures with the old path and a human-readable message.
- */
-export function migrateOldRuntimeState(projectRoot) {
-    const root = resolve(projectRoot);
-    const peaksRoot = join(root, '.peaks');
-    const newDir = join(root, RUNTIME_DIR);
-    const migratedFiles = [];
-    const errors = [];
-    for (const rel of RUNTIME_OLD_PATHS) {
-        const oldPath = join(peaksRoot, rel);
-        if (!existsSync(oldPath))
-            continue;
-        // Skip if the corresponding new path already exists — we treat the
-        // new path as authoritative when both exist, so the old file would
-        // only be stale data.
-        const newPath = join(newDir, runtimeNewBasename(rel));
-        if (existsSync(newPath)) {
-            // Best-effort cleanup of the stale old file so a re-run stays
-            // idempotent and the tree converges on the new layout.
-            try {
-                rmSync(oldPath, { recursive: true, force: true });
-            }
-            catch (error) {
-                errors.push({
-                    path: rel,
-                    message: `Could not remove stale legacy file after migration: ${error instanceof Error ? error.message : String(error)}`
-                });
-            }
-            continue;
-        }
-        try {
-            // Ensure the new parent dir exists. `mkdirSync(dirname(newPath), { recursive: true })`
-            // covers both the file case (`.peaks/_runtime`) and the
-            // directory case (`.peaks/_runtime/sop-state`).
-            mkdirSync(dirname(newPath), { recursive: true });
-            try {
-                renameSync(oldPath, newPath);
-            }
-            catch (renameError) {
-                // Cross-device or locked-file fallback: copy + unlink.
-                const stat = lstatSync(oldPath);
-                if (stat.isDirectory()) {
-                    // Recursive copy for the sop-state dir.
-                    copyDirRecursiveSync(oldPath, newPath);
-                    rmSync(oldPath, { recursive: true, force: true });
-                }
-                else {
-                    copyFileSync(oldPath, newPath);
-                    unlinkSync(oldPath);
-                }
-            }
-            migratedFiles.push(join('.peaks', rel));
-        }
-        catch (error) {
-            errors.push({
-                path: rel,
-                message: error instanceof Error ? error.message : String(error)
-            });
-        }
-    }
-    return { migratedFiles, errors };
-}
-function copyDirRecursiveSync(src, dest) {
-    mkdirSync(dest, { recursive: true });
-    for (const name of readdirSync(src)) {
-        const childSrc = join(src, name);
-        const childDest = join(dest, name);
-        const stat = lstatSync(childSrc);
-        if (stat.isDirectory()) {
-            copyDirRecursiveSync(childSrc, childDest);
-        }
-        else {
-            copyFileSync(childSrc, childDest);
-        }
-    }
-}
-/**
- * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
- *
- * Move the legacy per-session sub-agent state files at:
- *   - `.peaks/_runtime/<sid>/system/subagent-progress.json`
- *   - `.peaks/_runtime/<sid>/system/progress-spawn.json`
- * into the new canonical home at:
- *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
- *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
- *
- * Behavior:
- *   - Idempotent: re-running on a tree that is already on the new layout
- *     produces `migratedFiles: []`.
- *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
- *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
- *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
- *     subdir is only removed when it has zero other files, so a tree where
- *     the user had unrelated content in `system/` is left untouched.
- *   - New-path-wins: when both old and new files exist, the old file is
- *     removed (the new path is authoritative).
- *
- * Walks every discovered session — not just the canonical one — so a user
- * with 6 pre-migration sessions gets all of them migrated in one reconcile
- * pass.
- *
- * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
- *   relative paths (e.g. `.peaks/_runtime/<sid>/system/subagent-progress.json`) that
- *   were successfully moved. `errors` lists per-file failures.
- */
-export function migrateSubAgentState(projectRoot) {
-    const root = resolve(projectRoot);
-    const newDir = join(root, '.peaks', SUB_AGENTS_DIR);
-    const migratedFiles = [];
-    const errors = [];
-    for (const session of discoverSessions(projectRoot)) {
-        const oldSystemDir = join(session.path, 'system');
-        if (!existsSync(oldSystemDir))
-            continue;
-        const newSessionDir = join(newDir, session.sessionId);
-        mkdirSync(newSessionDir, { recursive: true });
-        for (const fname of SUB_AGENT_MIGRATION_FILES) {
-            const oldPath = join(oldSystemDir, fname);
-            const newPath = join(newSessionDir, fname);
-            if (!existsSync(oldPath))
-                continue;
-            if (existsSync(newPath)) {
-                // New path is authoritative; remove stale old file.
-                try {
-                    rmSync(oldPath, { force: true });
-                }
-                catch { /* best effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                continue;
-            }
-            try {
-                try {
-                    renameSync(oldPath, newPath);
-                }
-                catch (renameError) {
-                    // Cross-device or locked-file fallback: copy + unlink.
-                    copyFileSync(oldPath, newPath);
-                    unlinkSync(oldPath);
-                }
-                migratedFiles.push(join('.peaks', session.sessionId, 'system', fname));
-            }
-            catch (error) {
-                errors.push({
-                    path: oldPath,
-                    message: error instanceof Error ? error.message : String(error)
-                });
-            }
-        }
-        // R-2 guard: only remove the legacy system/ dir when it has zero
-        // remaining files (the user might have unrelated content there).
-        try {
-            const remaining = readdirSync(oldSystemDir);
-            if (remaining.length === 0) {
-                rmdirSync(oldSystemDir);
-            }
-        }
-        catch { /* best effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-    }
-    return { migratedFiles, errors };
-}
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,

package/dist/services/workspace/workspace-service.js

@@ -2,7 +2,7 @@ import { mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDirectory } from 'peaks-loop-shared/fs';
-import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
+import { getSessionIdCanonical, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
 import { normalizePath } from '../../shared/path-utils.js';
 /**
  * Slice 2026-06-29-change-id-root-removal: list the immediate children of
@@ -257,7 +257,18 @@ export async function initWorkspace(options) {
     // a parallel session without closing the previous one. Refuse to bind —
     // this is the "strict" mode the user picked. The user must finish or delete
     // the existing session first.
-    const existingSessionId = getSessionId(options.projectRoot);
+    // Sub-agent session-rebind guard: read the existing binding via the
+    // canonicalize-on-read variant. A sub-agent re-running `peaks workspace
+    // init` may pass a project root whose spelling differs from the stored
+    // form (relative `"."`, symlink, separator/case variance on Windows).
+    // The strict `getSessionId` returns null on those spellings, which sent
+    // init down the "no prior binding → adopt" path and silently clobbered
+    // `.peaks/_runtime/session.json` with a phantom session, orphaning the
+    // parent's binding. `getSessionIdCanonical` resolves the stored form
+    // against the caller so a live parent binding is detected and the
+    // differing-id branch below refuses (or requires --allow-session-rebind)
+    // instead of silently overwriting.
+    const existingSessionId = getSessionIdCanonical(options.projectRoot);
     let previousSessionId = null;
     let bound = false;
     if (existingSessionId === null) {

package/dist/shared/incrementing-number.d.ts

@@ -11,6 +11,17 @@
  * @returns Next available number (1, 2, 3, ...)
  */
 export declare function getNextNumber(dirPath: string): number;
+/**
+ * Convert a human-readable description into the kebab-case slug used in
+ * numbered artifact filenames. Lowercases, collapses non-alphanumerics to
+ * `-`, trims leading/trailing dashes, and caps at `MAX_FILENAME_SLUG_LENGTH`.
+ *
+ * Exported separately so lookup paths (e.g. `request-artifact-service.ts`)
+ * can compute the SAME slug the writer produced and match on-disk filenames
+ * case-insensitively — the writer lowercases, so a mixed-case request id
+ * like `2026-09-06-split-batchA` lands as `...-split-batcha.md`.
+ */
+export declare function slugifyDescription(description: string): string;
 export declare function buildNumberedFilename(number: number, description: string): string;
 /**
  * Get the next numbered file path in a directory.

package/dist/shared/incrementing-number.js

@@ -44,13 +44,26 @@ export function getNextNumber(dirPath) {
 // the slug may be at most 248 chars (giving 4 + 248 + 3 = 255 total).
 const MAX_FILENAME_LENGTH = 255;
 const MAX_FILENAME_SLUG_LENGTH = MAX_FILENAME_LENGTH - 7;
-export function buildNumberedFilename(number, description) {
-    const padded = String(number).padStart(3, '0');
-    const slug = description
+/**
+ * Convert a human-readable description into the kebab-case slug used in
+ * numbered artifact filenames. Lowercases, collapses non-alphanumerics to
+ * `-`, trims leading/trailing dashes, and caps at `MAX_FILENAME_SLUG_LENGTH`.
+ *
+ * Exported separately so lookup paths (e.g. `request-artifact-service.ts`)
+ * can compute the SAME slug the writer produced and match on-disk filenames
+ * case-insensitively — the writer lowercases, so a mixed-case request id
+ * like `2026-09-06-split-batchA` lands as `...-split-batcha.md`.
+ */
+export function slugifyDescription(description) {
+    return description
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '')
         .slice(0, MAX_FILENAME_SLUG_LENGTH);
+}
+export function buildNumberedFilename(number, description) {
+    const padded = String(number).padStart(3, '0');
+    const slug = slugifyDescription(description);
     return `${padded}-${slug}.md`;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.28",
+  "version": "4.0.30",
   "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.15",
+    "peaks-loop-mut": "0.1.28",
+    "peaks-loop-shared": "0.0.64",
+    "peaks-loop-shared-channel": "0.0.32"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/peaks-code/SKILL.md

@@ -86,10 +86,10 @@ Two-layer enforcement — do NOT try to bypass either:
 STOP. Run:
 
 ```bash
-peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid> --json
+peaks sub-agent dispatch rd --prompt '<your task>' --graph-node <nid> --workflow-id <wid> --request-id <rid> --project . --batch-id <uuid> --json
 ```
 
-The RD sub-agent owns the actual `Edit`/`Write`/`MultiEdit` tool calls against source code. The orchestrator only emits the dispatch request.
+`--graph-node <nid>` is REQUIRED (RD §4 D4c). Prepare the node first: `peaks workflow init --skill peaks-code`, then `peaks workflow node prepare --workflow <wid> --node <nid> --kind dispatch`. The RD sub-agent owns the actual `Edit`/`Write`/`MultiEdit` tool calls against source code. The orchestrator only emits the dispatch request.
 
 **Anti-pattern:** directly calling `Edit`/`Write`/`MultiEdit` on `src/**` from the orchestrator session because "the change is tiny" / "it's just one line" / "the dispatch overhead is too high" / "the LLM feels confident". None of these override the Code-Gate; the probe + the hook both fail-closed.
 
@@ -139,6 +139,10 @@ Sub-agents MUST NOT use raw `git worktree add`. The only authorized path is `pea
 
 Full content extracted to **`references/startup-sequence.md`** (Steps 0 / 0.5-0.87 / 1 / 2 / 2.3 / 2.5 / N / N+1 / N+2 + sub-agent sharing + boundaries). Read that file in full at session start; the sequence is MANDATORY.
 
+## Peaks-Loop Fresh-context preflight (search-first, MANDATORY at orchestration-start)
+
+Before the first planning action, run `peaks fresh-context preflight --prompt "<user request>" --json`. If `data.triggered` is true, search Context7 (priority, ~30s timeout) then WebSearch (fallback), synthesize ≤5 binding directives (用 X / 别用 Y / 因为 Z), and write the `## Fresh context` block (with the 以下信息优先于训练知识，冲突时以此为准 framing line) to `.peaks/_runtime/<sessionId>/fresh-context.md` — the RD/PRD dispatch site injects it automatically. Fail-soft (search failure → no block, slice continues). Kill-switch: `peaks config set --key freshContext.enabled --value false`. → `references/fresh-context-preflight.md`.
+
 ## Peaks-Loop Step 0.8 — Job-shape detection (BLOCKING on LLM judgement)
 
 > **BLOCKING on LLM judgement.** Before Step 1 mode selection, Code MUST surface a Job-shape decision via `peaks code detect-job` and persist it to `.peaks/_runtime/<sessionId>/job-shape.json`. The CLI is a recorder + gate — the LLM makes the judgement; downstream steps call `read-job-shape` and refuse if missing. See `references/step-0-8-gate.md` for the full contract. Skipping `peaks code detect-job` blocks the workflow at the next `read-job-shape` call (`JOB_SHAPE_NOT_DECIDED`).

package/skills/peaks-code/references/fresh-context-preflight.md

@@ -0,0 +1,81 @@
+# Fresh-context preflight (search-first)
+
+> **Slice 2026-09-07-search-first-preflight.** Signal-triggered preflight that
+> runs at **orchestration-start, before the first planning action**, for every
+> peaks-* orchestrator (peaks-code, peaks-prd, peaks-rd, peaks-qa, … — not
+> peaks-code specific). It hedges against model training-data lag by searching
+> for fresh context and injecting binding directives into the PRD/RD dispatch.
+
+## When
+
+Run the deterministic trigger scan as the very first step of a workflow, on the
+user's raw request text:
+
+```text
+peaks fresh-context preflight --prompt "<user request>" --json
+```
+
+Read the `--json` envelope's `data` object:
+
+| field | meaning |
+|---|---|
+| `data.triggered` | `true` → run the search + synthesis below |
+| `data.forced` | `true` → the user explicitly asked for a live search (联网搜 / 查最新 / 搜一下) |
+| `data.signals` | the signal keywords that matched (升级 / 迁移 / 最新 / latest / new / 版本 / 兼容 / breaking / upgrade / migrate / 新框架 / 推荐库 / 选型) |
+| `data.enabled` | the `freshContext.enabled` kill-switch (false → no-op) |
+
+If `data.triggered` is `false` (no signal, or kill-switch off), **do nothing** —
+the workflow proceeds exactly as before (byte-identical dispatch prompts).
+
+## Search (only when `triggered: true`)
+
+1. **Context7** (priority, `@upstash/context7-mcp`, ~30s timeout).
+2. **WebSearch** fallback when Context7 returns empty / errors / times out.
+
+Both fail-soft: if Context7 times out AND WebSearch fails, the slice continues
+with **no block and no hard error** (acceptance criterion #8).
+
+## Synthesize (≤5 binding directives)
+
+From the search results, synthesize **≤5 binding directives**, each in the
+imperative form **"use X / do NOT use Y / because Z"** (用 X / 别用 Y / 因为 Z):
+
+```text
+- 用 React 19 的 `use()`（因为 18 的并发渲染 API 已过时）
+- 别用 `react-router-dom` v6 的 `Switch`（因为 v7 已移除，冲突时以此为准）
+```
+
+Keep it to **5 or fewer** lines. Filter SEO noise — only keep directives that
+change a decision the model would otherwise get wrong from training data.
+
+## Write the block
+
+Wrap the directives in a `## Fresh context` block with the authoritative
+framing line (M1), and write it to
+`.peaks/_runtime/<sessionId>/fresh-context.md`:
+
+```markdown
+## Fresh context
+
+以下信息优先于训练知识，冲突时以此为准。
+
+1. 用 X（因为 Z）
+2. 别用 Y（因为 Z）
+```
+
+The RD/PRD dispatch site auto-injects this block (after the project-stack
+block, before the memory/task content). No manual step is needed beyond
+writing the file.
+
+## Kill-switch
+
+`peaks config set --key freshContext.enabled --value false` disables the whole
+preflight (no search, no injection). The default is enabled (absent key →
+`true`).
+
+## RD planning note
+
+RD's planning artifact MUST record a "Fresh context 遵循" section listing which
+of the ≤5 directives the implementation followed (acceptance criterion #6).
+QA / code-review then verify the implemented version/API against the block
+(acceptance criterion #7).

package/skills/peaks-code/references/sub-agent-dispatch.md

@@ -39,9 +39,23 @@ stays IDE-agnostic.
 **Command**:
 
 ```
-peaks sub-agent dispatch <role> --prompt <text> [--request-id <rid>] [--session-id <sid>] [--project <repo>] [--batch-id <uuid>] --json
+peaks sub-agent dispatch <role> --prompt <text> --graph-node <nid> [--workflow-id <wid>] [--request-id <rid>] [--session-id <sid>] [--project <repo>] [--batch-id <uuid>] --json
 ```
 
+> **`--graph-node` is REQUIRED (RD §4 D4c, effective 4.0.8).** Every
+> single dispatch must bind to a prepared workflow graph node. Prepare
+> one first:
+>
+> ```
+> peaks workflow init --skill peaks-code                    # → returns <wid>
+> peaks workflow node prepare --workflow <wid> --node <nid> --kind dispatch
+> ```
+>
+> then dispatch with `--graph-node <nid> --workflow-id <wid>`. Omitting
+> `--graph-node` rejects with `PEAKS_GRAPH_NODE_REQUIRED`; a node that is
+> not prepared (or has the wrong kind) rejects with
+> `PEAKS_GRAPH_NODE_NOT_PREPARED` / `PEAKS_GRAPH_NODE_KIND_INVALID`.
+
 **Envelope** (AC-8) — **2.1.0** (slice 2026-06-23-audit-4th #E1):
 
 > **Audit-3rd #4 + audit-4th #E1**: the `data.prompt` field was
@@ -342,16 +356,20 @@ grown unboundedly without this fix).
 When writing a SKILL.md that fans out sub-agents:
 
 1. Use `peaks sub-agent dispatch <role>` (never `Task(...)`).
-2. Issue all dispatches in a single message; the LLM will fire all
+2. Prepare the graph node first (RD §4 D4c — `--graph-node` is required):
+   `peaks workflow init --skill peaks-code`, then
+   `peaks workflow node prepare --workflow <wid> --node <nid> --kind dispatch`.
+3. Issue all dispatches in a single message; the LLM will fire all
    returned toolCalls in parallel.
-3. Pass `--request-id` and `--session-id` (or omit and let the CLI
-   resolve the active session).
-4. The sub-agent prompt **must** include the heartbeat instruction
+4. Pass `--graph-node <nid> --workflow-id <wid>` on every dispatch, plus
+   `--request-id` and `--session-id` (or omit and let the CLI resolve the
+   active session).
+5. The sub-agent prompt **must** include the heartbeat instruction
    (30 s cadence; override via `heartbeatIntervalSec` if needed).
-5. After the fan-out returns, the Dispatcher reducer reads the
+6. After the fan-out returns, the Dispatcher reducer reads the
    dispatch record + the artifacts the sub-agents wrote, marks
    `disposed: true` on each record, and advances the state machine.
-6. The poller handles the 5-min stale case as a warning, never as a
+7. The poller handles the 5-min stale case as a warning, never as a
    failure. The user is the one who decides to cancel.
 
 ## Cross-reference
@@ -380,6 +398,7 @@ peaks sub-agent dispatch <role> \
             hand back prose.', plus the heartbeat instruction: 'While running, call
             peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note \"<text>\"
             at least every 30 seconds.'>" \
+  --graph-node <nid> --workflow-id <wid> \
   --request-id <rid> --session-id <session-id> --project <repo> --json
 ```
 
@@ -426,7 +445,7 @@ peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-
 
 ## Detached Mode (Phase A, slice 2026-08-10)
 
-`peaks sub-agent dispatch <role> --prompt <text> --request-id <rid> --mode detached --vendor claude|codex|copilot [--no-throttle --max-concurrent <N>] --json` spawns a real OS process independent of the orchestrator IDE session.
+`peaks sub-agent dispatch <role> --prompt <text> --graph-node <nid> --workflow-id <wid> --request-id <rid> --mode detached --vendor claude|codex|copilot [--no-throttle --max-concurrent <N>] --json` spawns a real OS process independent of the orchestrator IDE session. `--graph-node` remains required here (RD §4 D4c).
 
 - **Cross-platform spawn**: Windows uses `DETACHED_PROCESS` + `CREATE_NEW_PROCESS_GROUP`; POSIX uses `setsid` + `nohup`. Implementation: `packages/peaks-loop-internal-runtime/src/process-supervisor.ts`.
 - **Minimum-context prompt**: `PromptBuilder` emits a 5–8KB slice `{rid, role, vendor, files, refs}` plus the verbatim `<peaks-auto-compact>` marker. The forbidden marker `@@@ORCHESTRATOR_SESSION_HISTORY_BOUNDARY@@@` MUST NOT appear in any prompt (unit-tested; regression fails vitest).