@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.965d1788

package/src/resources/extensions/gsd/tests/workspace-git-preflight.test.ts

@@ -3,9 +3,10 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
 
+import { GIT_NO_PROMPT_ENV } from "../git-constants.js";
 import { probeGitConflictState } from "../git-conflict-state.js";
 import { ensureWorkspaceGitReadyForPath } from "../workspace-git-preflight.js";
 import { isWorkspaceGitAllowedCommand } from "../workspace-git-guard.js";
@@ -50,6 +51,38 @@ function seedProductConflict(base: string): void {
   }
 }
 
+function installCountingGitShim(binDir: string, logPath: string): void {
+  const posixShim = join(binDir, "git");
+  writeFileSync(
+    posixShim,
+    [
+      "#!/bin/sh",
+      'printf "%s\\n" "$*" >> "$GSD_GIT_LOG"',
+      'PATH="$GSD_REAL_PATH"',
+      "export PATH",
+      'exec git "$@"',
+      "",
+    ].join("\n"),
+  );
+  chmodSync(posixShim, 0o755);
+
+  writeFileSync(
+    join(binDir, "git.cmd"),
+    [
+      "@echo off",
+      'echo %*>>"%GSD_GIT_LOG%"',
+      'set "PATH=%GSD_REAL_PATH%"',
+      "git %*",
+      "",
+    ].join("\r\n"),
+  );
+}
+
+function countGitShimInvocations(logPath: string): number {
+  if (!existsSync(logPath)) return 0;
+  return readFileSync(logPath, "utf-8").split(/\r?\n/).filter(Boolean).length;
+}
+
 test("probeGitConflictState reports clean repo", () => {
   const base = makeTempRepo("gsd-ws-git-clean-");
   try {
@@ -60,6 +93,122 @@ test("probeGitConflictState reports clean repo", () => {
   }
 });
 
+test("ensureWorkspaceGitReadyForPath caches clean target probes briefly", async () => {
+  const base = makeTempRepo("gsd-ws-git-clean-cache-");
+  const binDir = makeTempDir("gsd-ws-git-shim-");
+  const logPath = join(binDir, "git.log");
+  const originalProcessPath = process.env.PATH;
+  const originalEnvPath = GIT_NO_PROMPT_ENV.PATH;
+  const originalEnvGitLog = GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+  const originalEnvRealPath = GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+
+  try {
+    installCountingGitShim(binDir, logPath);
+    const shimmedPath = `${binDir}${delimiter}${originalProcessPath ?? ""}`;
+    process.env.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.GSD_GIT_LOG = logPath;
+    GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalProcessPath ?? "";
+
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+    const firstCount = countGitShimInvocations(logPath);
+    assert.equal(firstCount, 3, "first clean probe should run the existing conflict checks");
+
+    const second = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(second.ok, true);
+    assert.equal(
+      countGitShimInvocations(logPath),
+      firstCount,
+      "second clean probe within the cache window must not spawn git again",
+    );
+  } finally {
+    if (originalProcessPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalProcessPath;
+    if (originalEnvPath === undefined) delete GIT_NO_PROMPT_ENV.PATH;
+    else GIT_NO_PROMPT_ENV.PATH = originalEnvPath;
+    if (originalEnvGitLog === undefined) delete GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+    else GIT_NO_PROMPT_ENV.GSD_GIT_LOG = originalEnvGitLog;
+    if (originalEnvRealPath === undefined) delete GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+    else GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalEnvRealPath;
+    cleanup(binDir);
+    cleanup(base);
+  }
+});
+
+test("ensureWorkspaceGitReadyForPath detects merge state that appears after a clean probe", async () => {
+  const base = makeTempRepo("gsd-ws-git-cache-stale-");
+  const binDir = makeTempDir("gsd-ws-git-shim2-");
+  const logPath = join(binDir, "git2.log");
+  const originalProcessPath = process.env.PATH;
+  const originalEnvPath = GIT_NO_PROMPT_ENV.PATH;
+  const originalEnvGitLog = GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+  const originalEnvRealPath = GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+
+  try {
+    installCountingGitShim(binDir, logPath);
+    const shimmedPath = `${binDir}${delimiter}${originalProcessPath ?? ""}`;
+    process.env.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.GSD_GIT_LOG = logPath;
+    GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalProcessPath ?? "";
+
+    // First call — repo is clean, cache is populated.
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+    const afterFirstCount = countGitShimInvocations(logPath);
+    assert.ok(afterFirstCount > 0, "first probe must have called git");
+
+    // Introduce MERGE_HEAD to simulate merge state appearing mid-TTL window.
+    writeFileSync(join(base, ".git", "MERGE_HEAD"), "0000000000000000000000000000000000000000\n");
+
+    // Second call — cache should be bypassed because merge state markers are present.
+    await ensureWorkspaceGitReadyForPath(base);
+    const afterSecondCount = countGitShimInvocations(logPath);
+    assert.ok(
+      afterSecondCount > afterFirstCount,
+      "cache must be invalidated when merge state appears, causing a fresh git probe",
+    );
+  } finally {
+    if (originalProcessPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalProcessPath;
+    if (originalEnvPath === undefined) delete GIT_NO_PROMPT_ENV.PATH;
+    else GIT_NO_PROMPT_ENV.PATH = originalEnvPath;
+    if (originalEnvGitLog === undefined) delete GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+    else GIT_NO_PROMPT_ENV.GSD_GIT_LOG = originalEnvGitLog;
+    if (originalEnvRealPath === undefined) delete GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+    else GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalEnvRealPath;
+    cleanup(binDir);
+    cleanup(base);
+  }
+});
+
+test("ensureWorkspaceGitReadyForPath detects conflicts after a non-git folder becomes a repo", async () => {
+  const base = makeTempDir("gsd-ws-git-non-repo-cache-");
+  try {
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+
+    git(base, "init");
+    git(base, "config", "user.email", "test@test.com");
+    git(base, "config", "user.name", "Test");
+    git(base, "config", "core.autocrlf", "false");
+    writeFileSync(join(base, "README.md"), "# init\n");
+    git(base, "add", "-A");
+    git(base, "commit", "-m", "init");
+    git(base, "branch", "-M", "main");
+    seedProductConflict(base);
+
+    const second = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(second.ok, false);
+    if (second.ok) return;
+    assert.equal(second.severity, "product-conflicts");
+    assert.ok(second.conflictedPaths.includes("app.ts"));
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("ensureWorkspaceGitReadyForPath allows fresh non-git project setup folders", async () => {
   const base = makeTempDir("gsd-ws-git-non-repo-");
   try {

package/src/resources/extensions/gsd/tests/worktree-manager.test.ts

@@ -13,6 +13,7 @@ import {
   diffWorktreeNumstat,
   getWorktreeGSDDiff,
   getWorktreeLog,
+  mergeWorktreeToMain,
   worktreeBranchName,
   worktreePath,
   pruneEphemeralGhostWorktreeDirectories,
@@ -333,6 +334,44 @@ describe("getWorktreeLog", () => {
   });
 });
 
+// ─── mergeWorktreeToMain ─────────────────────────────────────────────────────
+
+describe("mergeWorktreeToMain", () => {
+  let base: string;
+  let wtPath: string;
+
+  beforeEach(() => {
+    base = makeBaseRepo();
+    wtPath = worktreePath(base, "M900");
+    mkdirSync(join(base, ".gsd-worktrees"), { recursive: true });
+    run(`git worktree add -b milestone/M900 "${wtPath}"`, base);
+  });
+
+  afterEach(() => { rmSync(base, { recursive: true, force: true }); });
+
+  test("cleans failed milestone squash state and deletes orphan branch", () => {
+    writeFileSync(join(wtPath, "README.md"), "# Milestone change\n", "utf-8");
+    run("git add README.md", wtPath);
+    run('git commit -m "feat: milestone change"', wtPath);
+
+    writeFileSync(join(base, "README.md"), "# Main change\n", "utf-8");
+    run("git add README.md", base);
+    run('git commit -m "feat: main change"', base);
+
+    assert.throws(
+      () => mergeWorktreeToMain(base, "M900", "feat: merge M900", "milestone/M900"),
+      /Merge conflicts detected/,
+    );
+
+    assert.equal(run("git status --porcelain", base), "", "failed squash cleanup should leave main clean");
+    assert.ok(!existsSync(wtPath), "failed milestone worktree should be removed");
+    assert.ok(
+      !run("git branch", base).includes("milestone/M900"),
+      "failed milestone branch should be deleted after worktree removal",
+    );
+  });
+});
+
 // ─── removeWorktree ───────────────────────────────────────────────────────────
 
 describe("removeWorktree", () => {

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -23,7 +23,7 @@ import {
 } from "../gsd-db.js";
 import { gsdProjectionRoot, clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { stripIdPrefix } from "../workflow-projections.js";
@@ -180,7 +180,7 @@ export async function handleCompleteMilestone(
       return;
     }
 
-    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
+    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status) && !isDeferredStatus(s.status));
     if (incompleteSlices.length > 0) {
       const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
       guardError = `incomplete slices: ${incompleteIds}`;
@@ -189,6 +189,7 @@ export async function handleCompleteMilestone(
 
     // Deep check: verify all tasks in all slices are complete
     for (const slice of slices) {
+      if (isDeferredStatus(slice.status)) continue;
       const tasks = getSliceTasks(params.milestoneId, slice.id);
       const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
       if (incompleteTasks.length > 0) {

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -30,7 +30,7 @@ import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import { renderMilestoneShellProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -540,7 +540,7 @@ export async function handleCompleteSlice(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
   }

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -6,11 +6,12 @@
  *
  * Validates inputs, writes task row and rendered SUMMARY.md to DB in a
  * transaction, then renders projections to disk and invalidates caches.
- * Projection write failures are reported as stale projections and do not roll
- * back committed DB state.
+ * If the critical task summary / plan projection write fails, the DB
+ * completion is compensated back to pending so DB state does not drift ahead
+ * of PLAN.md.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
@@ -29,6 +30,7 @@ import {
   saveGateResult,
   getPendingGatesForTurn,
 } from "../gsd-db.js";
+import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
@@ -36,8 +38,10 @@ import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderSummaryContent } from "../workflow-projections.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import {
+  renderMilestoneShellProjections,
+  renderSummaryContent,
+} from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -131,7 +135,7 @@ async function repairMissingTaskSummaryProjection(
   clearParseCache();
 
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+    await renderMilestoneShellProjections(artifactBasePath, taskRow.milestone_id);
   } catch (projErr) {
     logWarning("tool", `complete-task repair projection warning: ${(projErr as Error).message}`);
   }
@@ -267,6 +271,7 @@ export async function handleCompleteTask(
   let guardError: string | null = null;
   let summaryMd = "";
   let repairTaskSummaryRow: TaskRow | null = null;
+  const rollbackDbPath = getWorkflowDatabasePath();
 
   // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
   // Building the artifact runs the full shape validation (2-4 options, unique
@@ -423,8 +428,6 @@ export async function handleCompleteTask(
     return { error: guardError };
   }
 
-  let projectionStale = false;
-
   // Resolve and write summary to disk
   const summaryPath = taskSummaryPath(
     artifactBasePath,
@@ -438,12 +441,48 @@ export async function handleCompleteTask(
 
     // Toggle or regenerate the plan projection from DB. Missing projection
     // files are rebuilt by the renderer instead of being skipped.
-    await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!ensureWorkflowDbAtPath(rollbackDbPath)) {
+      throw new Error(`database unavailable before plan projection render for ${params.milestoneId}/${params.sliceId}`);
+    }
+    const wrotePlan = await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!wrotePlan) {
+      throw new Error(`plan projection write returned false for ${params.milestoneId}/${params.sliceId}`);
+    }
   } catch (renderErr) {
-    projectionStale = true;
-    logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; DB completion remains committed`, {
-      error: (renderErr as Error).message,
-    });
+    logWarning(
+      "projection",
+      `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}`,
+      { error: (renderErr as Error).message },
+    );
+    let rollbackSucceeded = false;
+    try {
+      ensureWorkflowDbAtPath(rollbackDbPath);
+      deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+      updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+      invalidateStateCache();
+      rollbackSucceeded = true;
+    } catch (rollbackErr) {
+      logWarning(
+        "projection",
+        `complete_task rollback failed after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(rollbackErr as Error).message}`,
+      );
+    }
+    try {
+      if (existsSync(summaryPath)) unlinkSync(summaryPath);
+    } catch (summaryErr) {
+      logWarning(
+        "projection",
+        `complete_task could not remove SUMMARY.md after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(summaryErr as Error).message}`,
+      );
+    }
+    // Clear path/parse caches regardless of rollback outcome so stale
+    // entries from the failed write attempt don't leak into subsequent calls.
+    clearPathCache();
+    clearParseCache();
+    const returnMsg = rollbackSucceeded
+      ? `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rolled completion back to pending`
+      : `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rollback also failed — task may remain complete with stale plan`;
+    return { error: returnMsg };
   }
 
   // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
@@ -569,7 +608,7 @@ export async function handleCompleteTask(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
   }
@@ -597,6 +636,5 @@ export async function handleCompleteTask(
     milestoneId: params.milestoneId,
     summaryPath,
     ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
-    ...(projectionStale ? { stale: true } : {}),
   };
 }

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

@@ -31,6 +31,7 @@ export interface ExecToolDeps {
   env?: NodeJS.ProcessEnv;
   now?: () => Date;
   generateId?: () => string;
+  signal?: AbortSignal;
 }
 
 export type UatExecIntent =
@@ -74,7 +75,7 @@ const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
 export function buildExecOptions(
   baseDir: string,
   cfg: ContextModeConfig | undefined,
-  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId" | "signal">,
 ): ExecSandboxOptions {
   const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
   const stdoutCap = clampNumber(
@@ -209,7 +210,7 @@ export async function executeGsdExec(
   const opts = buildExecOptions(
     deps.baseDir,
     deps.preferences?.context_mode,
-    { env: deps.env, now: deps.now, generateId: deps.generateId },
+    { env: deps.env, now: deps.now, generateId: deps.generateId, signal: deps.signal },
   );
   const run = deps.run ?? runExecSandbox;
 
@@ -308,6 +309,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      aborted: result.aborted === true,
       force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
@@ -318,13 +320,15 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       stderr_path: result.stderr_path,
       meta_path: result.meta_path,
     },
-    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+    isError: result.aborted === true || result.timed_out || result.signal !== null || result.exit_code !== 0,
   };
 }
 
 function formatExit(result: ExecSandboxResult): string {
   // force_resolved means a non-closing (D-state) child was force-resolved past its
   // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.aborted && result.force_resolved) return "aborted(force-killed)";
+  if (result.aborted) return "aborted";
   if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;

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

@@ -15,6 +15,7 @@ import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveSliceFile, resolveTa
 import { sendDesktopNotification } from "./notifications.js";
 import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
+import { UNIT_REGISTRY } from "./unit-registry.js";
 
 /**
  * Undo the last completed unit: revert git commits,
@@ -42,16 +43,20 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
     return;
   }
 
-  // Extract unit type and ID from the most recent activity log filename
-  // Format: <seq>-<unitType>-<unitId>.jsonl
-  const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
-  if (!match) {
+  // Extract unit type and ID from the most recent activity log filename.
+  // Both the unit type and the unit ID may contain hyphens, so anchor on the
+  // known unit-type vocabulary instead of guessing the unit-ID shape: a regex
+  // tuned to milestone-shaped IDs rejects project-level units whose IDs are
+  // symbolic (e.g. discuss-project uses PROJECT, workflow-preferences uses
+  // WORKFLOW-PREFS).
+  const parsed = parseActivityLogFilename(files[0]);
+  if (!parsed) {
     ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
     return;
   }
 
-  const unitType = match[1];
-  const unitId = match[2].replace(/-/g, "/");
+  const unitType = parsed.unitType;
+  const unitId = parsed.unitId.replace(/-/g, "/");
 
   if (!force) {
     ctx.ui.notify(
@@ -100,6 +105,11 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
   if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
     const [mid, sid, tid] = [milestone, slice, task];
     planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+    if (getTask(mid, sid, tid)) {
+      updateTaskStatus(mid, sid, tid, "pending");
+      await renderPlanCheckboxes(basePath, mid, sid);
+      planUpdated = true;
+    }
   }
 
   // 3. Try to revert git commits from activity log
@@ -379,6 +389,37 @@ export async function handleResetSlice(
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+// Known unit types sorted longest-first so a more specific type (e.g.
+// "execute-task-simple") matches before a prefix of it ("execute-task") when
+// splitting "<seq>-<unitType>-<unitId>.jsonl".
+const UNIT_TYPES_BY_LENGTH_DESC: readonly string[] = Object.keys(UNIT_REGISTRY).sort(
+  (a, b) => b.length - a.length,
+);
+
+/**
+ * Parse an activity-log filename of the form `<seq>-<unitType>-<unitId>.jsonl`
+ * (the format written by activity-log.ts). Both the unit type and the unit ID
+ * may contain hyphens, so we anchor on the known unit-type vocabulary rather
+ * than guessing the ID shape. This keeps non-milestone IDs (e.g. PROJECT,
+ * WORKFLOW-PREFS) parseable. Returns null when the name has no sequence prefix
+ * or does not start with a recognised unit type.
+ */
+export function parseActivityLogFilename(
+  filename: string,
+): { unitType: string; unitId: string } | null {
+  const seqMatch = filename.match(/^\d+-(.+)\.jsonl$/);
+  if (!seqMatch) return null;
+  const rest = seqMatch[1];
+  for (const unitType of UNIT_TYPES_BY_LENGTH_DESC) {
+    const prefix = `${unitType}-`;
+    if (rest.startsWith(prefix)) {
+      const unitId = rest.slice(prefix.length);
+      if (unitId.length > 0) return { unitType, unitId };
+    }
+  }
+  return null;
+}
+
 export function uncheckTaskInPlan(basePath: string, mid: string, sid: string, tid: string): boolean {
   const slicePath = resolveSlicePath(basePath, mid, sid);
   if (!slicePath) return false;

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

@@ -135,14 +135,38 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">,
     "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
 
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT: Record<string, string> = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "discuss-milestone":
+    "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+  "discuss-slice":
+    "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+  "discuss-project":
+    "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+  "discuss-requirements":
+    "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+  "replan-slice":
+    "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+  "reassess-roadmap":
+    "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
   "run-uat":
     "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+  "research-project":
+    "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+  "gate-evaluate":
+    "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "gate-evaluate":
+    "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 
 /**
@@ -160,7 +184,9 @@ export function composeContextModeInstructions(
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
   const guidance =
-    CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+    ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+    ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
     return `Context Mode (${lane} lane): ${guidance}`;
   }