gsd-pi 2.80.0-dev.0d763dc29 → 2.80.0-dev.2be7caf18

package/src/resources/extensions/gsd/tests/exec-history.test.ts

@@ -108,6 +108,21 @@ test('executeExecSearch: returns helpful empty-state message when no matches', (
   }
 });
 
+test('executeExecSearch: returns disabled error when context_mode.enabled=false', () => {
+  const base = freshBase();
+  try {
+    writeRun(base, 'should-not-surface', { stdout: 'hidden\n' });
+    const result = executeExecSearch(
+      { query: 'hidden' },
+      { baseDir: base, preferences: { context_mode: { enabled: false } } },
+    );
+    assert.equal(result.isError, true);
+    assert.equal((result.details as { error?: string }).error, 'context_mode_disabled');
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('executeExecSearch: includes stdout_path and preview in details', () => {
   const base = freshBase();
   try {

package/src/resources/extensions/gsd/tests/exec-sandbox.test.ts

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { EXEC_DEFAULTS, runExecSandbox, type ExecSandboxOptions } from '../exec-sandbox.ts';
 import { buildExecOptions, executeGsdExec } from '../tools/exec-tool.ts';
 import { isContextModeEnabled } from '../preferences-types.ts';
+import { validatePreferences } from '../preferences-validation.ts';
 
 function freshBase(): string {
   return mkdtempSync(join(tmpdir(), 'gsd-exec-test-'));
@@ -174,6 +175,52 @@ test('executeGsdExec: runs when enabled explicitly set to true', async () => {
   }
 });
 
+test('executeGsdExec: forwards custom exec_env_allowlist from preferences', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      {
+        runtime: 'bash',
+        script: 'printf "allowed=%s blocked=%s\\n" "$GSD_ALLOWED" "$GSD_BLOCKED"',
+      },
+      {
+        baseDir: base,
+        preferences: {
+          context_mode: {
+            enabled: true,
+            exec_env_allowlist: ['GSD_ALLOWED'],
+          },
+        },
+        env: {
+          PATH: '/usr/bin:/bin',
+          HOME: '/tmp',
+          GSD_ALLOWED: 'yes',
+          GSD_BLOCKED: 'no',
+        },
+      },
+    );
+    assert.ok(!result.isError);
+    assert.match(result.content[0].text, /allowed=yes blocked=/);
+    assert.doesNotMatch(result.content[0].text, /blocked=no/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeGsdExec: enforces per-call timeout override end-to-end', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: 'sleep 2', timeout_ms: 1 },
+      { baseDir: base, preferences: { context_mode: { enabled: true, exec_timeout_ms: 10_000 } } },
+    );
+    assert.equal(result.details.timed_out, true);
+    assert.equal(result.isError, true);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('executeGsdExec: rejects empty script', async () => {
   const base = freshBase();
   try {
@@ -188,6 +235,24 @@ test('executeGsdExec: rejects empty script', async () => {
   }
 });
 
+test('validatePreferences: rejects invalid context_mode preference values', () => {
+  const result = validatePreferences({
+    context_mode: {
+      enabled: 'false',
+      exec_timeout_ms: 999,
+      exec_stdout_cap_bytes: 1,
+      exec_digest_chars: -1,
+      exec_env_allowlist: ['GOOD_NAME', 'bad-name'],
+    },
+  } as any);
+  assert.ok(result.errors.length > 0);
+  assert.ok(result.errors.includes('context_mode.enabled must be a boolean'));
+  assert.ok(result.errors.includes('context_mode.exec_timeout_ms must be a number between 1000 and 600000'));
+  assert.ok(result.errors.includes('context_mode.exec_stdout_cap_bytes must be a number between 4096 and 16777216'));
+  assert.ok(result.errors.includes('context_mode.exec_digest_chars must be a number between 0 and 4000'));
+  assert.ok(result.errors.includes('context_mode.exec_env_allowlist must be an array of valid env var names'));
+});
+
 test('isContextModeEnabled: defaults to true; only explicit false disables', () => {
   assert.equal(isContextModeEnabled(undefined), true, 'undefined prefs → on');
   assert.equal(isContextModeEnabled(null), true, 'null prefs → on');

package/src/resources/extensions/gsd/tests/prompt-path-audit.test.ts

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const promptsDir = join(__dirname, "..", "prompts");
+
+test("prompt templates do not reference legacy milestone-root .gsd paths", () => {
+  const offenders: string[] = [];
+  for (const file of readdirSync(promptsDir)) {
+    if (!file.endsWith(".md")) continue;
+    const content = readFileSync(join(promptsDir, file), "utf-8");
+    const legacyPatterns = [
+      /\.gsd\/\{\{(?:milestoneId|mid)\}\}\//g,
+      /\.gsd\/<milestone-id>\//g,
+      /\.gsd\/<ID>\//g,
+    ];
+    for (const pattern of legacyPatterns) {
+      if (pattern.test(content)) {
+        offenders.push(`${file}: ${pattern.source}`);
+      }
+    }
+  }
+
+  assert.deepEqual(
+    offenders,
+    [],
+    "Milestone artifacts must use .gsd/milestones/<MID>/..., not legacy .gsd/<MID>/...",
+  );
+});
+
+test("quick task prompt delegates commit policy to quick.ts", () => {
+  const content = readFileSync(join(promptsDir, "quick-task.md"), "utf-8");
+  assert.match(content, /\{\{commitInstruction\}\}/);
+  assert.doesNotMatch(content, /Stage only relevant files/);
+});

package/src/resources/extensions/gsd/tests/quick-external-gsd.test.ts

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { buildQuickCommitInstruction } from "../quick.ts";
+
+function git(cwd: string, args: string[]): void {
+  const result = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+}
+
+test("quick task commit instruction does not ask agents to stage external .gsd quick files", { skip: process.platform === "win32" }, () => {
+  const tempRoot = realpathSync(mkdtempSync(join(tmpdir(), "gsd-quick-ext-")));
+  const repo = join(tempRoot, "repo");
+  const externalGsd = join(tempRoot, "state");
+  mkdirSync(repo);
+  mkdirSync(externalGsd);
+
+  const previousCwd = process.cwd();
+  try {
+    git(repo, ["init"]);
+    git(repo, ["config", "user.email", "test@example.com"]);
+    git(repo, ["config", "user.name", "Test User"]);
+    writeFileSync(join(repo, "README.md"), "# Test\n", "utf-8");
+    git(repo, ["add", "README.md"]);
+    git(repo, ["commit", "-m", "init"]);
+    symlinkSync(externalGsd, join(repo, ".gsd"), "dir");
+
+    const instruction = buildQuickCommitInstruction(repo, join(repo, ".gsd"));
+
+    assert.match(instruction, /do not stage or commit `\.gsd\/quick\/\.\.\.`/);
+    assert.match(instruction, /nothing in the project repo to commit/);
+    assert.match(instruction, /Write the quick summary file directly/);
+  } finally {
+    process.chdir(previousCwd);
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -96,6 +96,23 @@ test("auto bootstrap validates blocked directories before touching .gsd migratio
   );
 });
 
+test("fresh start registers the auto worker before bootstrap enters worktree flow (#5405)", () => {
+  const autoSrc = readGsdFile("auto.ts");
+  const startAutoIdx = autoSrc.indexOf("export async function startAuto(");
+  const startAutoBody = autoSrc.slice(startAutoIdx);
+
+  const preBootstrapRegisterIdx = startAutoBody.indexOf("registerAutoWorkerForSession(s, base);");
+  const bootstrapCallIdx = startAutoBody.indexOf("const ready = await bootstrapAutoSession(");
+
+  assert.ok(startAutoIdx > -1, "startAuto should exist");
+  assert.ok(preBootstrapRegisterIdx > -1, "startAuto should register worker before bootstrap");
+  assert.ok(bootstrapCallIdx > -1, "startAuto should call bootstrapAutoSession");
+  assert.ok(
+    preBootstrapRegisterIdx < bootstrapCallIdx,
+    "worker registration must happen before bootstrap so enterMilestone can claim milestone leases on first entry",
+  );
+});
+
 test("startAutoDetached reports failures asynchronously (#3733)", () => {
   const autoSrc = readGsdFile("auto.ts");
 

package/src/resources/extensions/gsd/tests/status-db-open.test.ts

@@ -44,4 +44,13 @@ describe('status opens DB before deriveState (#3691)', () => {
     assert.match(quickSrc, /getIsolationMode\(\)\s*!==\s*"none"/,
       'quick.ts should compare isolation mode against "none"');
   });
+
+  test('quick task prompt handles external .gsd without staging quick files', () => {
+    assert.match(quickSrc, /isExternalGsdRoot/,
+      'quick.ts should detect whether .gsd resolves outside the project repo');
+    assert.match(quickSrc, /do not stage or commit `\.gsd\/quick\/\.\.\.`/,
+      'external-state quick tasks must tell the agent not to stage .gsd/quick files');
+    assert.match(quickSrc, /nothing in the project repo to commit/,
+      'external-state quick tasks should allow summary-only work without a git commit');
+  });
 });

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -21,12 +21,18 @@ import type {
   ComputedArtifactRegistry,
   UnitContextManifest,
 } from "../unit-context-manifest.ts";
-import { UNIT_MANIFESTS } from "../unit-context-manifest.ts";
-import { buildReassessRoadmapPrompt } from "../auto-prompts.ts";
+import { KNOWN_UNIT_TYPES, UNIT_MANIFESTS } from "../unit-context-manifest.ts";
+import {
+  buildExecuteTaskPrompt,
+  buildGateEvaluatePrompt,
+  buildReassessRoadmapPrompt,
+  buildWorkflowPreferencesPrompt,
+} from "../auto-prompts.ts";
 import { invalidateAllCaches } from "../cache.ts";
 import {
   openDatabase,
   closeDatabase,
+  insertGateRow,
   insertMilestone,
   upsertMilestonePlanning,
   insertSlice,
@@ -121,7 +127,7 @@ test("Context Mode composer: standalone output starts with heading and includes
   assert.ok(out.startsWith("## Context Mode"));
   assert.match(out, /execution lane/i);
   assert.match(out, /`gsd_exec`/);
-  assert.match(out, /noisy commands/);
+  assert.match(out, /builds, tests, and diagnostics/);
   assert.match(out, /`gsd_exec_search`/);
   assert.match(out, /before reruns/);
   assert.match(out, /`gsd_resume`/);
@@ -136,7 +142,45 @@ test("Context Mode composer: nested output is compact single sentence", () => {
   assert.match(out, /`gsd_exec`/);
   assert.match(out, /`gsd_exec_search`/);
   assert.match(out, /`gsd_resume`/);
-  assert.ok(out.length < 180, `nested guidance should stay compact, got ${out.length} chars`);
+  assert.ok(out.length < 240, `nested guidance should stay compact, got ${out.length} chars`);
+});
+
+const laneLabelByMode: Record<string, string> = {
+  interview: "interview",
+  research: "research",
+  planning: "planning",
+  execution: "execution",
+  verification: "verification",
+  orchestration: "orchestration",
+  docs: "documentation",
+};
+
+test("Context Mode composer: every known eligible unit renders its configured lane and required tools", () => {
+  for (const unitType of KNOWN_UNIT_TYPES) {
+    const manifest = UNIT_MANIFESTS[unitType];
+    assert.ok(manifest, `missing manifest for ${unitType}`);
+    const out = composeContextModeInstructions(unitType, { enabled: true, renderMode: "standalone" });
+    if (manifest.contextMode === "none") {
+      assert.strictEqual(out, "", `${unitType} should not render Context Mode`);
+      continue;
+    }
+    assert.ok(out.startsWith("## Context Mode"), `${unitType} should render standalone Context Mode heading`);
+    assert.match(out, new RegExp(`Lane: \\*\\*${laneLabelByMode[manifest.contextMode]} lane\\*\\*\\.`, "i"));
+    assert.match(out, /`gsd_exec`/, `${unitType} should mention gsd_exec`);
+    assert.match(out, /`gsd_exec_search`/, `${unitType} should mention gsd_exec_search`);
+    assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
+  }
+});
+
+test("Context Mode composer: workflow-preferences and research-decision render no Context Mode block", () => {
+  assert.strictEqual(
+    composeContextModeInstructions("workflow-preferences", { enabled: true, renderMode: "standalone" }),
+    "",
+  );
+  assert.strictEqual(
+    composeContextModeInstructions("research-decision", { enabled: true, renderMode: "standalone" }),
+    "",
+  );
 });
 
 // ─── Integration: migrated buildReassessRoadmapPrompt ─────────────────────
@@ -220,6 +264,94 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
   assert.ok(!prompt.includes("Slice Context (from discussion)"));
 });
 
+test("Context Mode resume injection: eligible prompts include one bounded snapshot block above inlined context", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+  writeFileSync(
+    join(base, ".gsd", "last-snapshot.md"),
+    "# GSD context snapshot\n\nResume evidence.\n",
+    "utf-8",
+  );
+
+  const prompt = await buildReassessRoadmapPrompt("M001", "Test", "S01", base);
+
+  assert.equal(prompt.match(/## Context Snapshot/g)?.length, 1);
+  assert.match(prompt, /Source: `\.gsd\/last-snapshot\.md`/);
+  assert.match(prompt, /Resume evidence/);
+  assert.ok(prompt.indexOf("## Context Mode") < prompt.indexOf("## Context Snapshot"));
+  assert.ok(prompt.indexOf("## Context Snapshot") < prompt.indexOf("## Inlined Context"));
+});
+
+test("Context Mode resume injection: missing snapshot does not add an empty block", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildReassessRoadmapPrompt("M001", "Test", "S01", base);
+
+  assert.match(prompt, /## Context Mode/);
+  assert.doesNotMatch(prompt, /## Context Snapshot/);
+});
+
+test("Context Mode resume injection: disabled mode suppresses guidance and snapshot reads", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+  writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\ncontext_mode:\n  enabled: false\n---\n", "utf-8");
+  writeFileSync(join(base, ".gsd", "last-snapshot.md"), "# GSD context snapshot\n\nDo not inject.\n", "utf-8");
+
+  const prompt = await buildReassessRoadmapPrompt("M001", "Test", "S01", base);
+
+  assert.doesNotMatch(prompt, /## Context Mode/);
+  assert.doesNotMatch(prompt, /## Context Snapshot/);
+  assert.doesNotMatch(prompt, /Do not inject/);
+});
+
+test("Context Mode resume injection: none-mode units do not inject snapshots", async () => {
+  const base = makeFixtureBase();
+  try {
+    writeFileSync(join(base, ".gsd", "last-snapshot.md"), "# GSD context snapshot\n\nNo lane.\n", "utf-8");
+    const prompt = await buildWorkflowPreferencesPrompt(base);
+    assert.doesNotMatch(prompt, /## Context Mode/);
+    assert.doesNotMatch(prompt, /## Context Snapshot/);
+    assert.doesNotMatch(prompt, /No lane/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("Context Mode prompt suppression: disabled inlined, phase-anchor, and nested prompts omit Context Mode", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+  insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+  writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\ncontext_mode:\n  enabled: false\n---\n", "utf-8");
+  writeFileSync(join(base, ".gsd", "last-snapshot.md"), "# GSD context snapshot\n\nDo not inject.\n", "utf-8");
+
+  const inlinedPrompt = await buildReassessRoadmapPrompt("M001", "Test", "S01", base);
+  assert.doesNotMatch(inlinedPrompt, /## Context Mode|Context Mode \(|## Context Snapshot/);
+
+  const phaseAnchorPrompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
+  assert.doesNotMatch(phaseAnchorPrompt, /## Context Mode|Context Mode \(|## Context Snapshot/);
+
+  const nestedPrompt = await buildGateEvaluatePrompt("M001", "Test", "S01", "First", base);
+  assert.match(nestedPrompt, /Use this as the prompt for a `subagent` call/);
+  assert.doesNotMatch(nestedPrompt, /## Context Mode|Context Mode \(|## Context Snapshot/);
+});
+
 // ─── v2 surface (#4924) ───────────────────────────────────────────────────
 
 const fakeBase: BaseResolverContext = {

package/src/resources/extensions/gsd/tools/context-mode-tool-result.ts

@@ -0,0 +1,25 @@
+// Project/App: GSD-2
+// File Purpose: Shared Context Mode tool result helpers.
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export type ContextModeToolName = "gsd_exec" | "gsd_exec_search" | "gsd_resume";
+
+export function contextModeDisabledResult(operation: ContextModeToolName): ToolExecutionResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          `${operation} is disabled by \`context_mode.enabled: false\` in preferences. ` +
+          "Remove that override or set it to true to re-enable Context Mode tools.",
+      },
+    ],
+    details: { operation, error: "context_mode_disabled" },
+    isError: true,
+  };
+}

package/src/resources/extensions/gsd/tools/exec-search-tool.ts

@@ -4,6 +4,8 @@
 // re-discover past runs without re-executing. Read-only; no DB writes.
 
 import { searchExecHistory, type ExecSearchOptions } from "../exec-history.js";
+import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecSearchToolParams {
   query?: string;
@@ -12,16 +14,14 @@ export interface ExecSearchToolParams {
   limit?: number;
 }
 
-export interface ToolExecutionResult {
-  content: Array<{ type: "text"; text: string }>;
-  details: Record<string, unknown>;
-  isError?: boolean;
-}
-
 export function executeExecSearch(
   params: ExecSearchToolParams,
-  opts: { baseDir: string },
+  opts: { baseDir: string; preferences?: { context_mode?: ContextModeConfig } | null },
 ): ToolExecutionResult {
+  if (!isContextModeEnabled(opts.preferences)) {
+    return contextModeDisabledResult("gsd_exec_search");
+  }
+
   const searchOpts: ExecSearchOptions = {
     query: typeof params.query === "string" ? params.query : undefined,
     runtime: params.runtime,

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -12,6 +12,7 @@ import {
   type ExecSandboxResult,
 } from "../exec-sandbox.js";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
   runtime: ExecSandboxRequest["runtime"];
@@ -20,17 +21,12 @@ export interface ExecToolParams {
   timeout_ms?: number;
 }
 
-export interface ToolExecutionResult {
-  content: Array<{ type: "text"; text: string }>;
-  details: Record<string, unknown>;
-  isError?: boolean;
-}
-
 export interface ExecToolDeps {
   baseDir: string;
   preferences: { context_mode?: ContextModeConfig } | null;
   /** Optional override for testing. */
   run?: (req: ExecSandboxRequest, opts: ExecSandboxOptions) => Promise<ExecSandboxResult>;
+  env?: NodeJS.ProcessEnv;
   now?: () => Date;
   generateId?: () => string;
 }
@@ -77,21 +73,6 @@ function isEnabled(prefs: ExecToolDeps["preferences"]): boolean {
   return isContextModeEnabled(prefs);
 }
 
-function disabledResult(): ToolExecutionResult {
-  return {
-    content: [
-      {
-        type: "text",
-        text:
-          "gsd_exec is disabled by `context_mode.enabled: false` in preferences. Remove that " +
-          "override (or set it to true) to re-enable sandboxed tool-output execution.",
-      },
-    ],
-    details: { operation: "gsd_exec", error: "context_mode_disabled" },
-    isError: true,
-  };
-}
-
 function paramError(message: string): ToolExecutionResult {
   return {
     content: [{ type: "text", text: `Error: ${message}` }],
@@ -104,7 +85,7 @@ export async function executeGsdExec(
   params: ExecToolParams,
   deps: ExecToolDeps,
 ): Promise<ToolExecutionResult> {
-  if (!isEnabled(deps.preferences)) return disabledResult();
+  if (!isEnabled(deps.preferences)) return contextModeDisabledResult("gsd_exec");
 
   const runtime = params.runtime;
   if (runtime !== "bash" && runtime !== "node" && runtime !== "python") {
@@ -121,7 +102,7 @@ export async function executeGsdExec(
   const opts = buildExecOptions(
     deps.baseDir,
     deps.preferences?.context_mode,
-    { now: deps.now, generateId: deps.generateId },
+    { env: deps.env, now: deps.now, generateId: deps.generateId },
   );
   const run = deps.run ?? runExecSandbox;
 

package/src/resources/extensions/gsd/tools/resume-tool.ts

@@ -3,22 +3,22 @@
 // re-deriving project memory state.
 
 import { readCompactionSnapshot } from "../compaction-snapshot.js";
+import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ResumeToolParams {
   /** Ignored — reserved for future variant (e.g. dated snapshots). */
   _variant?: string;
 }
 
-export interface ToolExecutionResult {
-  content: Array<{ type: "text"; text: string }>;
-  details: Record<string, unknown>;
-  isError?: boolean;
-}
-
 export function executeResume(
   _params: ResumeToolParams,
-  opts: { baseDir: string },
+  opts: { baseDir: string; preferences?: { context_mode?: ContextModeConfig } | null },
 ): ToolExecutionResult {
+  if (!isContextModeEnabled(opts.preferences)) {
+    return contextModeDisabledResult("gsd_resume");
+  }
+
   const snapshot = readCompactionSnapshot(opts.baseDir);
   if (snapshot == null) {
     return {

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -112,8 +112,22 @@ const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, strin
   docs: "documentation",
 };
 
-const CONTEXT_MODE_GUIDANCE =
-  "Use `gsd_exec` for noisy commands, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.";
+const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">, string> = {
+  interview:
+    "Use `gsd_resume` to restore prior discussion, `gsd_exec` for noisy discovery, and `gsd_exec_search` before repeating scans.",
+  research:
+    "Use `gsd_exec` for noisy research scans, `gsd_exec_search` before reruns, and `gsd_resume` to restore prior findings.",
+  planning:
+    "Use `gsd_resume` for planning continuity, `gsd_exec` for noisy checks, and `gsd_exec_search` before rerunning diagnostics.",
+  execution:
+    "Use `gsd_exec` for builds, tests, and diagnostics, `gsd_exec_search` before reruns, and `gsd_resume` after compaction or resume.",
+  verification:
+    "Use `gsd_exec` for verification commands, `gsd_exec_search` to reuse prior evidence, and `gsd_resume` after compaction or resume.",
+  orchestration:
+    "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
+  docs:
+    "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
+};
 
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
@@ -129,15 +143,16 @@ export function composeContextModeInstructions(
   if (!manifest || manifest.contextMode === "none") return "";
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+  const guidance = CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
-    return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+    return `Context Mode (${lane} lane): ${guidance}`;
   }
 
   return [
     "## Context Mode",
     "",
     `Lane: **${lane} lane**.`,
-    CONTEXT_MODE_GUIDANCE,
+    guidance,
   ].join("\n");
 }