gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/commands-worktree.ts

@@ -0,0 +1,383 @@
+// GSD-2 — In-TUI handler for /gsd worktree commands (list, merge, clean, remove).
+//
+// Mirrors the CLI subcommands in src/worktree-cli.ts but emits results via
+// ctx.ui.notify() instead of writing colored output to stderr. Reuses the
+// same extension modules (worktree-manager, native-git-bridge, etc.) so the
+// behavior is identical to the CLI surface.
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync } from "node:fs";
+
+import { projectRoot } from "./commands/context.js";
+import {
+  listWorktrees,
+  removeWorktree,
+  mergeWorktreeToMain,
+  diffWorktreeAll,
+  diffWorktreeNumstat,
+  worktreeBranchName,
+} from "./worktree-manager.js";
+import {
+  nativeHasChanges,
+  nativeDetectMainBranch,
+  nativeCommitCountBetween,
+} from "./native-git-bridge.js";
+import { inferCommitType } from "./git-service.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface WorktreeStatus {
+  name: string;
+  path: string;
+  branch: string;
+  exists: boolean;
+  filesChanged: number;
+  linesAdded: number;
+  linesRemoved: number;
+  uncommitted: boolean;
+  commits: number;
+}
+
+// ─── Status helper ─────────────────────────────────────────────────────────
+
+function getStatus(basePath: string, name: string, wtPath: string): WorktreeStatus {
+  const diff = diffWorktreeAll(basePath, name);
+  const numstat = diffWorktreeNumstat(basePath, name);
+  const filesChanged = diff.added.length + diff.modified.length + diff.removed.length;
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  for (const s of numstat) {
+    linesAdded += s.added;
+    linesRemoved += s.removed;
+  }
+
+  let uncommitted = false;
+  try {
+    uncommitted = existsSync(wtPath) && nativeHasChanges(wtPath);
+  } catch {
+    // native check failure → treat as clean for display purposes
+  }
+
+  let commits = 0;
+  try {
+    const main = nativeDetectMainBranch(basePath);
+    commits = nativeCommitCountBetween(basePath, main, worktreeBranchName(name));
+  } catch {
+    // commit count unavailable → leave at 0
+  }
+
+  return {
+    name,
+    path: wtPath,
+    branch: worktreeBranchName(name),
+    exists: existsSync(wtPath),
+    filesChanged,
+    linesAdded,
+    linesRemoved,
+    uncommitted,
+    commits,
+  };
+}
+
+// ─── Formatters (exported for tests) ────────────────────────────────────────
+
+export function formatWorktreeList(statuses: WorktreeStatus[]): string {
+  if (statuses.length === 0) {
+    return "No worktrees.\n\nCreate one from the CLI: gsd -w <name>";
+  }
+
+  const lines: string[] = [`Worktrees — ${statuses.length}`, ""];
+  for (const s of statuses) {
+    const badge = s.uncommitted
+      ? "(uncommitted)"
+      : s.filesChanged > 0
+        ? "(unmerged)"
+        : "(clean)";
+    lines.push(`  ${s.name} ${badge}`);
+    lines.push(`    branch  ${s.branch}`);
+    lines.push(`    path    ${s.path}`);
+    if (s.filesChanged > 0) {
+      lines.push(
+        `    diff    ${s.filesChanged} file${s.filesChanged === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved}, ${s.commits} commit${s.commits === 1 ? "" : "s"}`,
+      );
+    }
+    lines.push("");
+  }
+  lines.push("Commands:");
+  lines.push("  /gsd worktree merge <name>   Merge into main and clean up");
+  lines.push("  /gsd worktree remove <name>  Remove a worktree (--force to skip safety checks)");
+  lines.push("  /gsd worktree clean          Remove all merged/empty worktrees");
+  return lines.join("\n");
+}
+
+export function formatCleanKeepReason(status: WorktreeStatus): string {
+  if (!status.exists) {
+    return "directory missing — run 'git worktree prune' to unregister";
+  }
+
+  if (status.filesChanged > 0) {
+    return `${status.filesChanged} changed file${status.filesChanged === 1 ? "" : "s"}${status.uncommitted ? ", uncommitted" : ""}`;
+  }
+
+  return "uncommitted changes";
+}
+
+// ─── Subcommand: list ───────────────────────────────────────────────────────
+
+async function handleList(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path));
+  ctx.ui.notify(formatWorktreeList(statuses), "info");
+}
+
+// ─── Subcommand: merge ──────────────────────────────────────────────────────
+
+async function handleMerge(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  const trimmed = args.trim();
+
+  let target = trimmed;
+  if (!target) {
+    if (worktrees.length === 1) {
+      target = worktrees[0].name;
+    } else if (worktrees.length === 0) {
+      ctx.ui.notify("No worktrees to merge.", "info");
+      return;
+    } else {
+      const names = worktrees.map((w) => w.name).join(", ");
+      ctx.ui.notify(`Usage: /gsd worktree merge <name>\n\nWorktrees: ${names}`, "warning");
+      return;
+    }
+  }
+
+  const wt = worktrees.find((w) => w.name === target);
+  if (!wt) {
+    const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+    ctx.ui.notify(`Worktree "${target}" not found.\n\nAvailable: ${available}`, "error");
+    return;
+  }
+
+  const status = getStatus(basePath, target, wt.path);
+  if (status.filesChanged === 0 && !status.uncommitted) {
+    try {
+      removeWorktree(basePath, target, { deleteBranch: true });
+      ctx.ui.notify(`Removed empty worktree ${target}.`, "info");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(
+        `Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  if (status.uncommitted) {
+    try {
+      autoCommitCurrentBranch(wt.path, "worktree-merge", target);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(
+        [
+          `Auto-commit before merge failed: ${msg}`,
+          "",
+          `Commit or stash changes in ${wt.path}, then re-run /gsd worktree merge ${target}.`,
+        ].join("\n"),
+        "error",
+      );
+      return;
+    }
+  }
+
+  const commitType = inferCommitType(target);
+  const mainBranch = nativeDetectMainBranch(basePath);
+  const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
+
+  try {
+    mergeWorktreeToMain(basePath, target, commitMessage);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (err instanceof GSDError && err.code === GSD_GIT_ERROR) {
+      ctx.ui.notify(
+        `Merge requires the main branch to be checked out: ${msg}\n\nSwitch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then re-run /gsd worktree merge ${target}.`,
+        "error",
+      );
+    } else {
+      ctx.ui.notify(
+        `Merge failed: ${msg}\n\nResolve conflicts manually, then run /gsd worktree merge ${target} again.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  const successLines = [
+    `Merged ${target} → ${mainBranch}`,
+    `  ${status.filesChanged} file${status.filesChanged === 1 ? "" : "s"}, +${status.linesAdded} -${status.linesRemoved}`,
+    `  commit: ${commitMessage.split("\n")[0]}`,
+  ];
+
+  try {
+    removeWorktree(basePath, target, { deleteBranch: true });
+    ctx.ui.notify(successLines.join("\n"), "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const cleanupLines = [
+      ...successLines,
+      "",
+      `Cleanup failed after the merge succeeded: ${msg}`,
+      err instanceof GSDError && err.code === GSD_GIT_ERROR
+        ? `Switch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then remove the worktree manually with /gsd worktree remove ${target} --force.`
+        : `Remove the worktree manually with /gsd worktree remove ${target} --force, or run 'git worktree prune' to clean up dangling registrations.`,
+    ];
+    ctx.ui.notify(cleanupLines.join("\n"), "warning");
+  }
+}
+
+// ─── Subcommand: clean ──────────────────────────────────────────────────────
+
+async function handleClean(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const worktrees = listWorktrees(basePath);
+  if (worktrees.length === 0) {
+    ctx.ui.notify("No worktrees to clean.", "info");
+    return;
+  }
+
+  const removed: string[] = [];
+  const kept: string[] = [];
+  for (const wt of worktrees) {
+    const status = getStatus(basePath, wt.name, wt.path);
+    if (status.filesChanged === 0 && !status.uncommitted) {
+      try {
+        removeWorktree(basePath, wt.name, { deleteBranch: true });
+        removed.push(wt.name);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        kept.push(`${wt.name} (failed: ${msg})`);
+      }
+    } else {
+      const reason = formatCleanKeepReason(status);
+      kept.push(`${wt.name} (${reason})`);
+    }
+  }
+
+  const lines: string[] = [`Cleaned ${removed.length} worktree${removed.length === 1 ? "" : "s"}.`];
+  if (removed.length > 0) {
+    lines.push("", "Removed:");
+    for (const n of removed) lines.push(`  ✓ ${n}`);
+  }
+  if (kept.length > 0) {
+    lines.push("", "Kept:");
+    for (const n of kept) lines.push(`  ─ ${n}`);
+  }
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+// ─── Subcommand: remove ─────────────────────────────────────────────────────
+
+async function handleRemove(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = projectRoot();
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  const force = tokens.includes("--force");
+  const name = tokens.find((t) => t !== "--force");
+  if (!name) {
+    ctx.ui.notify("Usage: /gsd worktree remove <name> [--force]", "warning");
+    return;
+  }
+
+  const worktrees = listWorktrees(basePath);
+  const wt = worktrees.find((w) => w.name === name);
+  if (!wt) {
+    const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+    ctx.ui.notify(`Worktree "${name}" not found.\n\nAvailable: ${available}`, "error");
+    return;
+  }
+
+  const status = getStatus(basePath, name, wt.path);
+  if ((status.filesChanged > 0 || status.uncommitted) && !force) {
+    ctx.ui.notify(
+      [
+        `Worktree "${name}" has pending changes (${formatCleanKeepReason(status)}).`,
+        "",
+        `  Merge first:     /gsd worktree merge ${name}`,
+        `  Or force-remove: /gsd worktree remove ${name} --force`,
+      ].join("\n"),
+      "warning",
+    );
+    return;
+  }
+
+  try {
+    removeWorktree(basePath, name, { deleteBranch: true });
+    ctx.ui.notify(`Removed worktree ${name}.`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(
+      `Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`,
+      "error",
+    );
+  }
+}
+
+// ─── Help text ──────────────────────────────────────────────────────────────
+
+const HELP_TEXT = [
+  "Usage: /gsd worktree <command> [args]",
+  "",
+  "Commands:",
+  "  list                       Show all worktrees with status",
+  "  merge [name]               Merge a worktree into main, then remove it",
+  "  remove <name> [--force]    Remove a worktree (refuses unmerged changes without --force)",
+  "  clean                      Remove all merged/empty worktrees",
+  "",
+  "The -w flag (CLI only) creates/resumes worktrees on session start:",
+  "  gsd -w               Auto-name a new worktree, or resume the only active one",
+  "  gsd -w my-feature    Create or resume a named worktree",
+].join("\n");
+
+// ─── Dispatcher ─────────────────────────────────────────────────────────────
+
+export async function handleWorktree(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const trimmed = args.trim();
+  const lowered = trimmed.toLowerCase();
+
+  if (!lowered || lowered === "help" || lowered === "--help" || lowered === "-h") {
+    ctx.ui.notify(HELP_TEXT, "info");
+    return;
+  }
+
+  try {
+    if (lowered === "list" || lowered === "ls") {
+      await handleList(ctx);
+      return;
+    }
+    if (lowered === "merge" || lowered.startsWith("merge ")) {
+      await handleMerge(trimmed.replace(/^merge\s*/i, ""), ctx);
+      return;
+    }
+    if (lowered === "clean") {
+      await handleClean(ctx);
+      return;
+    }
+    if (
+      lowered === "remove" ||
+      lowered.startsWith("remove ") ||
+      lowered === "rm" ||
+      lowered.startsWith("rm ")
+    ) {
+      const stripped = trimmed.replace(/^(remove|rm)\s*/i, "");
+      await handleRemove(stripped, ctx);
+      return;
+    }
+
+    ctx.ui.notify(`Unknown worktree command: ${trimmed}\n\n${HELP_TEXT}`, "warning");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Worktree command failed: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -165,6 +165,12 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 
+- `reactive_execution`: controls automatic parallel task dispatch inside a slice. Reactive execution is enabled by default when omitted; set `enabled: false` to opt out. With default-on behavior, GSD only attempts a reactive batch when at least three ready tasks are available and the task-plan IO graph is non-ambiguous. If you set `enabled: true` explicitly, GSD uses the earlier opt-in threshold of two ready tasks. Keys:
+  - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
+  - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
+  - `isolation_mode`: `"same-tree"` — currently the only supported value.
+  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
   - `channel_id`: string or number — channel ID.

package/src/resources/extensions/gsd/doctor-providers.ts

@@ -17,6 +17,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
+import { getHomeDir } from "./home-dir.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -194,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = process.env.HOME ?? "~";
+  const home = getHomeDir();
   return [
     join(home, ".gsd", "agent", "models.json"),
     // Keep parity with custom-provider discovery during auto bootstrap.

package/src/resources/extensions/gsd/forensics.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { getHomeDir } from "./home-dir.js";
 
 import { extractTrace, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -244,7 +244,7 @@ export async function handleForensics(
   // when import.meta.url resolves to the npm-global install path (Windows).
   let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
   if (!existsSync(join(gsdSourceDir, "prompts"))) {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+    const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
     const fallback = join(gsdHome, "agent", "extensions", "gsd");
     if (existsSync(join(fallback, "prompts"))) gsdSourceDir = fallback;
   }
@@ -1299,10 +1299,15 @@ function formatReportForPrompt(report: ForensicReport): string {
 function redactForGitHub(text: string, basePath: string): string {
   let result = text;
 
+  // Build regex that matches both / and \ separator variants (Windows)
+  // Normalize to / first, escape for regex, then replace each / with [/\\]
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pathRe = (p: string) =>
+    new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
+
   // Replace absolute paths
-  result = result.replaceAll(basePath, ".");
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  if (home) result = result.replaceAll(home, "~");
+  result = result.replace(pathRe(basePath), ".");
+  result = result.replace(pathRe(getHomeDir()), "~");
 
   // Strip API key patterns
   result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");

package/src/resources/extensions/gsd/guided-flow.ts

@@ -25,6 +25,7 @@ import {
 } from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
+import { getHomeDir } from "./home-dir.js";
 import {
   gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
@@ -607,7 +608,7 @@ async function dispatchWorkflow(
     });
   }
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(

package/src/resources/extensions/gsd/home-dir.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform home directory resolution.
+ *
+ * `process.env.HOME` is not set on Windows (CMD/PowerShell).
+ * Falls back to USERPROFILE, then os.homedir(), then throws.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+
+export function getHomeDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  if (!home) {
+    throw new Error(
+      "Cannot resolve home directory. Set HOME or USERPROFILE environment variable.",
+    );
+  }
+  return home;
+}

package/src/resources/extensions/gsd/journal.ts

@@ -60,7 +60,10 @@ export type JournalEventType =
   | "canonical-root-redirect"
   // #4765 — slice-cadence collapse
   | "slice-merged"
-  | "milestone-resquash";
+  | "milestone-resquash"
+  // dispatch telemetry — measure agent/subagent invocation frequency and shape
+  | "subagent-invoked"
+  | "subagent-completed";
 
 /** A single structured event in the journal. */
 export interface JournalEntry {

package/src/resources/extensions/gsd/key-manager.ts

@@ -17,6 +17,7 @@ import { existsSync, statSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdirSync } from "node:fs";
 import { getErrorMessage } from "./error-utils.js";
+import { getHomeDir } from "./home-dir.js";
 
 // ─── Provider Registry ─────────────────────────────────────────────────────────
 
@@ -122,7 +123,7 @@ export function describeCredential(cred: AuthCredential): string {
  * Get the auth.json path.
  */
 export function getAuthPath(): string {
-  return join(process.env.HOME ?? "~", ".gsd", "agent", "auth.json");
+  return join(getHomeDir(), ".gsd", "agent", "auth.json");
 }
 
 /**

package/src/resources/extensions/gsd/migrate/command.ts

@@ -15,6 +15,7 @@ import { resolve, join, dirname } from "node:path";
 import { gsdRoot } from "../paths.js";
 import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/tui.js";
+import { getHomeDir } from "../home-dir.js";
 import {
   validatePlanningDirectory,
   parsePlanningDirectory,
@@ -85,9 +86,9 @@ export async function handleMigrate(
   // Default to cwd when no args given; expand ~ to HOME
   let rawPath = args.trim() || ".";
   if (rawPath.startsWith("~/")) {
-    rawPath = join(process.env.HOME ?? "~", rawPath.slice(2));
+    rawPath = join(getHomeDir(), rawPath.slice(2));
   } else if (rawPath === "~") {
-    rawPath = process.env.HOME ?? "~";
+    rawPath = getHomeDir();
   }
 
   let sourcePath = resolve(process.cwd(), rawPath);

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
+- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.

package/src/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
+- A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
+- You need current external information (library docs, API behavior) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

package/src/resources/extensions/gsd/tests/auto-session-encapsulation.test.ts

@@ -14,6 +14,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AutoSession } from "../auto/session.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
@@ -32,6 +33,20 @@ function getRuntimeStateTsSource(): string {
   return readFileSync(RUNTIME_STATE_TS_PATH, "utf-8");
 }
 
+test("AutoSession.lockBasePath uses GSD_PROJECT_ROOT for symlink-resolved worktrees", () => {
+  const savedProjectRoot = process.env.GSD_PROJECT_ROOT;
+  process.env.GSD_PROJECT_ROOT = "/real/project";
+  try {
+    const session = new AutoSession();
+    session.basePath = "/Users/dev/.gsd/projects/abc123/worktrees/M001/slices/S01";
+
+    assert.equal(session.lockBasePath, "/real/project");
+  } finally {
+    if (savedProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+    else process.env.GSD_PROJECT_ROOT = savedProjectRoot;
+  }
+});
+
 // ── Invariant 1: No module-level mutable variables in auto.ts ────────────────
 
 test("auto.ts has no module-level let declarations", () => {