@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -19,9 +19,10 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -48,13 +49,21 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import {
+  claimMilestoneLease,
+  releaseMilestoneLease,
+  getMilestoneLease,
+  refreshMilestoneLease,
+  milestoneLeaseTtlSeconds,
+} from "../db/milestone-leases.js";
 export type {
   UatCheckResultInput,
   UatEvidenceRef,
@@ -105,6 +114,24 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function milestoneLeaseConflictResult(
+  milestoneId: string,
+  byWorker: string,
+  expiresAt: string,
+): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+    details: {
+      operation: "plan_milestone",
+      error: "milestone_lease_conflict",
+      milestoneId,
+      byWorker,
+      expiresAt,
+    },
+    isError: true,
+  };
+}
+
 export interface SummarySaveParams {
   milestone_id?: string;
   slice_id?: string;
@@ -1244,7 +1271,48 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  let workerId: string | null = null;
+  let acquiredToken: number | null = null;
+  let leaseRefreshTimer: ReturnType<typeof setInterval> | undefined;
   try {
+    // Re-read at the gate so a peer-created milestone is not treated as fresh.
+    const milestoneExists = getMilestone(params.milestoneId) !== null;
+    if (milestoneExists) {
+      const heldLease = getMilestoneLease(params.milestoneId);
+      if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+        const holder = getAutoWorker(heldLease.worker_id);
+        // Let the one-shot claim path recover stale same-process worker rows.
+        const projectRoot = normalizeRealPath(basePath);
+        const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+        const holderIsOneShotReentrantPeer = !isAutoActive()
+          && !!holder
+          && holder.host === hostname()
+          && holder.pid === process.pid
+          && holder.project_root_realpath === projectRoot;
+        if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+          return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+        }
+      }
+    }
+
+    // Fresh creation cannot claim a lease because the FK row does not exist.
+    // In-process auto already owns its lease; re-claiming would bump its token.
+    if (!isAutoActive() && milestoneExists) {
+      workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+      const lease = claimMilestoneLease(workerId, params.milestoneId);
+      if (!lease.ok) {
+        return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+      }
+      acquiredToken = lease.token;
+
+      const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+      leaseRefreshTimer = setInterval(() => {
+        if (acquiredToken !== null && workerId !== null) {
+          refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+      }, leaseRefreshMs);
+    }
+
     const result = await handlePlanMilestone(params, basePath);
     if ("error" in result) {
       return {
@@ -1270,6 +1338,17 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  finally {
+    if (leaseRefreshTimer !== undefined) {
+      clearInterval(leaseRefreshTimer);
+    }
+    if (workerId !== null && acquiredToken !== null) {
+      releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+    }
+    if (workerId !== null) {
+      markWorkerStopping(workerId);
+    }
+  }
 }
 
 export async function executePlanSlice(

package/src/resources/extensions/gsd/uat-policy.ts

@@ -1,7 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
-import { extractUatType } from "./files.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
+import { extractUatType, UAT_TYPE_KEYWORDS } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
@@ -27,19 +28,14 @@ export interface UatModePolicy {
 
 export interface UatContentPolicy {
   declaredType: UatType;
+  /** False when no parseable `UAT mode:` declaration exists and declaredType defaulted to artifact-driven. */
+  modeDeclared: boolean;
   effectiveType: UatType;
   browserRequired: boolean;
   shouldDispatchByDefault: boolean;
 }
 
-export const UAT_TYPES: readonly UatType[] = [
-  "artifact-driven",
-  "browser-executable",
-  "runtime-executable",
-  "live-runtime",
-  "mixed",
-  "human-experience",
-] as const;
+export const UAT_TYPES: readonly UatType[] = UAT_TYPE_KEYWORDS;
 
 export const UAT_MODE_POLICIES: Readonly<Record<UatType, UatModePolicy>> = {
   "artifact-driven": {
@@ -88,26 +84,76 @@ export function getDeclaredUatType(content: string): UatType {
   return extractUatType(content) ?? "artifact-driven";
 }
 
-export function classifyUatContent(content: string): UatContentPolicy {
-  const declaredType = getDeclaredUatType(content);
-  const browserRequired = hasBrowserRequiredText(content);
-  const effectiveType = declaredType === "artifact-driven" && browserRequired
+/** Self-contained browser UAT harnesses that manage server lifecycle internally. */
+const SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE =
+  /\b(?:npm run test:uat|node\s+(?:--check\s+\S+\s+&&\s+)*tests\/browser\/search-uat\.mjs|npx playwright test(?:\s+\S+)?)\b/i;
+
+export function hasSelfContainedRuntimeUatCommand(content: string): boolean {
+  return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+
+function resolveEffectiveUatTypeFromPolicy(
+  declaredType: UatType,
+  browserRequired: boolean,
+  content: string,
+): UatType {
+  let effectiveType = declaredType === "artifact-driven" && browserRequired
     ? "browser-executable"
     : declaredType;
 
+  // M006/S01 regression: specs often declare browser-executable with localhost
+  // preconditions while the Evidence section names a runtime harness such as
+  // `npm run test:uat`. Interactive browser_* checks then race a fixed port
+  // against the script's own ephemeral server — run the harness instead.
+  if (
+    effectiveType === "browser-executable" &&
+    hasSelfContainedRuntimeUatCommand(content)
+  ) {
+    effectiveType = "runtime-executable";
+  }
+
+  return effectiveType;
+}
+
+export function classifyUatContent(content: string): UatContentPolicy {
+  return classifyUatContentForRun(content);
+}
+
+/**
+ * Classify UAT mode for run-uat dispatch. Supplemental context (slice summary,
+ * verification excerpts) can name a self-contained harness even when the UAT
+ * file only documents a separate server command such as `npm run test:server`.
+ */
+export function classifyUatContentForRun(content: string, supplementalContext = ""): UatContentPolicy {
+  const parsedType = extractUatType(content);
+  const declaredType = parsedType ?? "artifact-driven";
+  const browserRequired = hasBrowserRequiredText(content);
+  const combinedForHarness = supplementalContext.trim()
+    ? `${content}\n\n${supplementalContext}`
+    : content;
+  const effectiveType = resolveEffectiveUatTypeFromPolicy(
+    declaredType,
+    browserRequired,
+    combinedForHarness,
+  );
+
   return {
     declaredType,
+    modeDeclared: parsedType !== undefined,
     effectiveType,
     browserRequired,
     shouldDispatchByDefault: effectiveType !== "artifact-driven" || browserRequired,
   };
 }
 
-export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
-  const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy: UatContentPolicy): boolean {
   return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
 
+export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
+  return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
+
 export function resolveEffectiveUatType(content: string): UatType {
   return classifyUatContent(content).effectiveType;
 }
@@ -126,7 +172,7 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
 export function isUatBrowserToolName(toolName: string): boolean {
   const parsed = parseMcpToolName(toolName);
   const canonicalName = parsed?.toolName ?? toolName;
-  if (canonicalName.startsWith("browser_")) return true;
+  if (hasBrowserContractPrefix(canonicalName)) return true;
   return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 

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

@@ -13,7 +13,7 @@ import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveTaskFile, buildTaskFileName, buildSliceFileName } from "./paths.js";
 import { sendDesktopNotification } from "./notifications.js";
-import { getTask, getSlice, getSliceTasks, updateTaskStatus, updateSliceStatus } from "./gsd-db.js";
+import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
 
 /**
@@ -330,12 +330,16 @@ export async function handleResetSlice(
     return;
   }
 
-  // Reset all tasks
-  let tasksReset = 0;
+  // Reset all task statuses to "pending" and the slice to "active" in one
+  // atomic commit (DB is source of truth). Previously a per-task updateTaskStatus
+  // loop + a separate updateSliceStatus, which could leave a partial reset if
+  // interrupted mid-loop.
+  resetSliceCascade(mid, sid);
+
+  // Delete task summary files — projection cleanup, separate from the DB reset.
+  const tasksReset = tasks.length;
   let summariesDeleted = 0;
   for (const t of tasks) {
-    updateTaskStatus(mid, sid, t.id, "pending");
-    tasksReset++;
     const summaryPath = resolveTaskFile(basePath, mid, sid, t.id, "SUMMARY");
     if (summaryPath && existsSync(summaryPath)) {
       unlinkSync(summaryPath);
@@ -343,9 +347,6 @@ export async function handleResetSlice(
     }
   }
 
-  // Reset slice status
-  updateSliceStatus(mid, sid, "active");
-
   // Delete slice summary and UAT files
   let sliceFilesDeleted = 0;
   const slicePath = resolveSlicePath(basePath, mid, sid);

package/src/resources/extensions/gsd/unit-closeout.ts

@@ -0,0 +1,201 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Closeout module — durable completion pipeline behind one seam (ADR-032).
+//
+// `closeUnit` owns what makes a Unit's completion durable. This pass ships the
+// **Interactive Closeout adapter** path: commit the work and compute the
+// Closeout Git Verdict, failing closed (loudly) instead of silently when a
+// non-`none` `git.isolation` preference was never honoured by the session.
+// Motivating failure (2026-06-10): an interactive session under
+// `git.isolation: worktree` completed a milestone with every source file
+// untracked on the integration branch — no commit, no merge, no warning.
+//
+// The interactive adapter only fires on milestone boundaries — the durability
+// gap is the milestone close, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` itself stays general
+// over all boundaries for the pending Auto Closeout adapter re-seat.
+//
+// The auto loop keeps its existing closeout pipeline for now (the Auto
+// Closeout adapter re-seat is the documented next step in ADR-032); the
+// interactive trigger in bootstrap/register-hooks.ts is a no-op while
+// `isAutoActive()`, so auto-mode behaviour is untouched.
+//
+// Re-entrancy is naturally safe: a re-fired completion commits an already-clean
+// tree, which yields `nothing-to-commit`, and `appendNotification` carries its
+// own dedup window — so `closeUnit` keeps no result cache of its own.
+
+import { appendNotification, type NotifySeverity } from "./notification-store.js";
+import { readStringField } from "./auto-unit-tool-scope.js";
+import { MILESTONE_BRANCH_PREFIX } from "./branch-patterns.js";
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { getIsolationMode } from "./preferences.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { logWarning } from "./workflow-logger.js";
+
+export type CloseoutBoundary = "task" | "slice" | "milestone";
+export type CloseoutOutcome = "complete" | "failed" | "skipped";
+
+/**
+ * What git state the closeout found and did.
+ *
+ * - `committed`           — work committed on the current branch (expected under
+ *                           `isolation: none`, and for task/slice boundaries).
+ * - `nothing-to-commit`   — working tree was already clean.
+ * - `milestone-branch`    — milestone boundary closed on a `milestone/<MID>`
+ *                           branch; the merge stays owned by worktree tooling.
+ * - `isolation-bypassed`  — milestone boundary closed outside a milestone
+ *                           worktree/branch while `git.isolation` is
+ *                           `worktree`/`branch`: committed where the work sits
+ *                           and surfaced a Needs Attention notice instead of
+ *                           completing silently.
+ * - `commit-failed`       — the commit attempt threw; surfaced, never thrown.
+ */
+export type CloseoutGitVerdict =
+  | "committed"
+  | "nothing-to-commit"
+  | "milestone-branch"
+  | "isolation-bypassed"
+  | "commit-failed";
+
+export interface UnitCloseoutRequest {
+  basePath: string;
+  unitType: string;
+  /** "M001" | "M001/S01" | "M001/S01/T01" */
+  unitId: string;
+  boundary: CloseoutBoundary;
+  outcome: CloseoutOutcome;
+}
+
+export interface UnitCloseoutResult {
+  gitVerdict: CloseoutGitVerdict;
+  commitMessage: string | null;
+  /** The user-facing Needs Attention / status notice, when one was emitted. */
+  notice?: string;
+}
+
+/** Seam for tests; production callers use the defaults. */
+export interface UnitCloseoutDeps {
+  isolationMode(basePath: string): "none" | "worktree" | "branch";
+  currentBranch(basePath: string): string | null;
+  commit(basePath: string, unitType: string, unitId: string): string | null;
+  notify(message: string, severity: NotifySeverity): void;
+}
+
+const defaultDeps: UnitCloseoutDeps = {
+  isolationMode: (basePath) => getIsolationMode(basePath),
+  currentBranch: (basePath) => {
+    try {
+      return nativeGetCurrentBranch(basePath);
+    } catch {
+      return null;
+    }
+  },
+  commit: (basePath, unitType, unitId) => autoCommitCurrentBranch(basePath, unitType, unitId),
+  notify: (message, severity) => appendNotification(message, severity),
+};
+
+export function closeUnit(request: UnitCloseoutRequest, deps: UnitCloseoutDeps = defaultDeps): UnitCloseoutResult {
+  let commitMessage: string | null = null;
+  let gitVerdict: CloseoutGitVerdict;
+  let notice: string | undefined;
+
+  try {
+    commitMessage = deps.commit(request.basePath, request.unitType, request.unitId);
+    gitVerdict = commitMessage === null ? "nothing-to-commit" : "committed";
+  } catch (err) {
+    gitVerdict = "commit-failed";
+    notice = `Unit closeout commit failed for ${request.unitId}: ${err instanceof Error ? err.message : String(err)}`;
+    logWarning("engine", notice);
+    deps.notify(notice, "error");
+  }
+
+  if (request.boundary === "milestone" && gitVerdict !== "commit-failed") {
+    const isolation = deps.isolationMode(request.basePath);
+    if (isolation !== "none") {
+      const branch = deps.currentBranch(request.basePath);
+      if (branch?.startsWith(MILESTONE_BRANCH_PREFIX)) {
+        gitVerdict = "milestone-branch";
+        notice =
+          `Milestone ${request.unitId} completed on ${branch}. ` +
+          `Merge it to the integration branch with the worktree tooling (/gsd worktree merge).`;
+        deps.notify(notice, "info");
+      } else {
+        gitVerdict = "isolation-bypassed";
+        notice =
+          `Needs attention: milestone ${request.unitId} completed outside a milestone worktree/branch ` +
+          `while git.isolation is "${isolation}" — the isolation preference was not honoured this session. ` +
+          (commitMessage
+            ? `Work was committed directly on "${branch ?? "the current branch"}".`
+            : `The working tree had nothing left to commit on "${branch ?? "the current branch"}".`);
+        logWarning("engine", notice);
+        deps.notify(notice, "warning");
+      }
+    }
+  }
+
+  return { gitVerdict, commitMessage, notice };
+}
+
+// ─── Interactive Closeout adapter (tool-observation trigger) ─────────────
+
+// Canonical closeout tool → boundary. Aliases are canonicalized by the hook.
+// Only the milestone boundary is wired interactively: it is the durability gap
+// that motivated ADR-032, and committing at every task/slice would sweep a
+// developer's unrelated working-tree changes. `closeUnit` still handles every
+// boundary for the pending Auto Closeout adapter re-seat.
+const CLOSEOUT_TOOL_BOUNDARIES: Record<string, CloseoutBoundary> = {
+  gsd_complete_milestone: "milestone",
+};
+
+// Commit attribution uses the canonical unit types so interactive closeout
+// commits carry the same GSD-Unit evidence trailers the verification prompts
+// look for.
+const BOUNDARY_UNIT_TYPES: Record<CloseoutBoundary, string> = {
+  task: "execute-task",
+  slice: "complete-slice",
+  milestone: "complete-milestone",
+};
+
+export function isUnitCloseoutTool(canonicalToolName: string): boolean {
+  return canonicalToolName in CLOSEOUT_TOOL_BOUNDARIES;
+}
+
+function readId(input: unknown, camel: string, snake: string): string | undefined {
+  const value = readStringField(input, camel, snake);
+  return value && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Interactive Closeout adapter entry, called from the host's tool-observation
+ * hook for successful closeout tool calls when auto-mode is NOT active.
+ * Returns null when the tool input doesn't identify a unit.
+ */
+export function runInteractiveUnitCloseout(
+  args: { basePath: string; canonicalToolName: string; input: unknown },
+  deps: UnitCloseoutDeps = defaultDeps,
+): UnitCloseoutResult | null {
+  const boundary = CLOSEOUT_TOOL_BOUNDARIES[args.canonicalToolName];
+  if (!boundary) return null;
+
+  const milestoneId = readId(args.input, "milestoneId", "milestone_id");
+  if (!milestoneId) return null;
+  const sliceId = readId(args.input, "sliceId", "slice_id");
+  const taskId = readId(args.input, "taskId", "task_id");
+
+  let unitId = milestoneId;
+  if (boundary !== "milestone") {
+    if (!sliceId) return null;
+    unitId = boundary === "slice" ? `${milestoneId}/${sliceId}` : `${milestoneId}/${sliceId}/${taskId ?? ""}`;
+    if (boundary === "task" && !taskId) return null;
+  }
+
+  return closeUnit(
+    {
+      basePath: args.basePath,
+      unitType: BOUNDARY_UNIT_TYPES[boundary],
+      unitId,
+      boundary,
+      outcome: "complete",
+    },
+    deps,
+  );
+}

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

@@ -43,8 +43,10 @@ import {
   type ComputedArtifactId,
   type ComputedArtifactRegistry,
   type ContextModePolicy,
+  type ToolsPolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 import type { UnitPromptContextContract } from "./tool-contract.js";
 
 /**
@@ -133,6 +135,16 @@ 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> = {
+  "run-uat":
+    "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+};
+
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
  * types, disabled config, and explicit `contextMode: "none"` all omit the
@@ -147,7 +159,8 @@ 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];
+  const guidance =
+    CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
     return `Context Mode (${lane} lane): ${guidance}`;
   }
@@ -160,6 +173,103 @@ export function composeContextModeInstructions(
   ].join("\n");
 }
 
+// ─── Tool surface hardening ───────────────────────────────────────────────
+//
+// Upfront guidance for units whose runtime tool surface is narrower than the
+// default Claude/native set. Prevents wasted turns on tools that are blocked
+// by the write gate or Claude Code SDK allowlists (run-uat gsd_exec/Bash).
+
+export interface ComposeToolSurfaceInstructionOptions {
+  readonly renderMode: ContextModeRenderMode;
+}
+
+const TOOL_SURFACE_GUIDANCE_BY_UNIT: Record<string, string> = {
+  "run-uat":
+    "Do not call `gsd_exec`, `Bash`, `Write`, or `Edit` — they are unavailable in this unit. Run every automated check through `gsd_uat_exec` with the appropriate `intent`. For browser UAT modes, use `browser_*` tools when presented; if browser automation fails, record the failure honestly and use `gsd_uat_exec` for the best objective substitute.",
+  "complete-slice":
+    "Run slice-level verification through `gsd_exec` (or MCP-scoped `mcp__…__gsd_exec`), not direct `bash`. Capture learnings through `gsd_capture_thought` (or MCP-scoped `mcp__…__gsd_capture_thought`), not bare `capture_thought`, when workflow MCP tools are presented. Do not call `gsd_uat_result_save` — run-uat owns persisted UAT assessment. On verification failure, do not edit user source files in this unit.",
+  "gate-evaluate":
+    "Dispatch only **tester** subagents via `subagent`. Persist each gate with `gsd_save_gate_result`. Do not use `ToolSearch` — it is not available.",
+  "reactive-execute":
+    "Dispatch only **worker** subagents via `subagent`. Do not call `gsd_task_complete` from this parent batch — each worker owns its task completion. If a failed task left no summary, call `gsd_summary_save` with `blocker_discovered: true`.",
+  "execute-task":
+    "Complete only this task via `gsd_task_complete`. Do not call `gsd_slice_complete`, `gsd_validate_milestone`, or `gsd_complete_milestone` — the orchestrator owns phase transitions.",
+  "validate-milestone":
+    "Dispatch reviewer subagents in parallel, then persist the verdict via `gsd_validate_milestone`. Do not query `.gsd/gsd.db` directly — use `gsd_milestone_status` and inlined context.",
+  "complete-milestone":
+    "Persist completion only through `gsd_complete_milestone` after verification passes. Do not query `.gsd/gsd.db` directly. Do not write `.gsd/PROJECT.md` or `.gsd/REQUIREMENTS.md` by hand — use `gsd_summary_save` and `gsd_requirement_update`.",
+  "replan-slice":
+    "Persist replans through `gsd_replan_slice` only. Do not edit `PLAN.md` or task plans directly.",
+  "plan-slice":
+    "Persist planning through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner** for reconnaissance — not implementation agents. Do not edit user source files outside `.gsd/**`.",
+  "refine-slice":
+    "Persist refinements through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner**. Do not edit user source files outside `.gsd/**`.",
+  "plan-milestone":
+    "Persist milestone planning through `gsd_plan_milestone` / `gsd_plan_slice`. Do not edit user source files outside `.gsd/**`.",
+  "research-slice":
+    "Dispatch subagents only to **scout** or **planner** for reconnaissance. Do not edit user source files outside `.gsd/**`.",
+};
+
+function guidanceForToolsPolicy(policy: ToolsPolicy): string | null {
+  switch (policy.mode) {
+    case "planning":
+      return "Writes are restricted to `.gsd/**` under the working directory — do not edit user source files. `bash` is limited to read-only investigation commands. Do not dispatch subagents. For human elicitation, use workflow MCP `ask_user_questions` when available — not native `AskUserQuestion`.";
+    case "planning-dispatch": {
+      const agents = policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ");
+      return `Writes are restricted to \`.gsd/**\`. Dispatch subagents only to: ${agents}. Do not edit user source files.`;
+    }
+    case "docs":
+      return "Writes are restricted to `.gsd/**` and project documentation paths (`docs/`, `README*`, `CHANGELOG.md`, root `*.md`). Do not edit application source.";
+    case "verification": {
+      const subagentLine = policy.allowedSubagents?.length
+        ? ` Dispatch subagents only to: ${policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ")}.`
+        : " Do not dispatch subagents.";
+      return `\`bash\` is limited to build/test verification commands. Writes restricted to \`.gsd/**\`.${subagentLine}`;
+    }
+    default:
+      return null;
+  }
+}
+
+function formatForbiddenWorkflowToolsLine(
+  unitType: string,
+  unitGuidance: string | undefined,
+): string | null {
+  const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools;
+  if (!forbidden) return null;
+  const names = Object.keys(forbidden).filter((name) => !unitGuidance?.includes(`\`${name}\``));
+  if (names.length === 0) return null;
+  return `Do not call ${names.map((name) => `\`${name}\``).join(", ")} in this unit.`;
+}
+
+/**
+ * Render upfront tool-surface guidance for a unit type. Unknown units and
+ * unrestricted (`tools.mode: "all"`) units omit the block unless they have
+ * unit-specific closeout guidance registered above.
+ */
+export function composeToolSurfaceInstructions(
+  unitType: string,
+  opts: ComposeToolSurfaceInstructionOptions,
+): string {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) return "";
+
+  const unitGuidance = TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
+  const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(manifest.tools);
+  const forbiddenLine = formatForbiddenWorkflowToolsLine(unitType, unitGuidance);
+  const parts = [unitGuidance, policyGuidance, forbiddenLine].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+  if (parts.length === 0) return "";
+
+  const body = parts.join(" ");
+  if (opts.renderMode === "nested") {
+    return `Tool surface: ${body}`;
+  }
+
+  return ["## Tool Surface", "", body].join("\n");
+}
+
 // ─── v2 surface (#4924) ───────────────────────────────────────────────────
 
 /**

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

@@ -343,35 +343,11 @@ const TOOLS_DOCS: ToolsPolicy = {
  * enumerates these against `UNIT_MANIFESTS` to catch manifest drift when
  * a new unit type lands.
  */
-export const KNOWN_UNIT_TYPES = [
-  "research-milestone",
-  "plan-milestone",
-  "discuss-milestone",
-  "validate-milestone",
-  "complete-milestone",
-  "research-slice",
-  "plan-slice",
-  "refine-slice",
-  "replan-slice",
-  "complete-slice",
-  "reassess-roadmap",
-  "execute-task",
-  "reactive-execute",
-  "run-uat",
-  "gate-evaluate",
-  "rewrite-docs",
-  // Sidecar units (triage, quick-task)
-  "triage-captures",
-  "quick-task",
-  // Deep planning mode (project-level) units
-  "workflow-preferences",
-  "discuss-project",
-  "discuss-requirements",
-  "research-decision",
-  "research-project",
-] as const;
+// Unit-type vocabulary is owned by the Unit Registry (ADR-033); re-exported
+// here so established import paths keep working.
+import { KNOWN_UNIT_TYPES, type UnitType } from "./unit-registry.js";
 
-export type UnitType = typeof KNOWN_UNIT_TYPES[number];
+export { KNOWN_UNIT_TYPES, type UnitType };
 
 export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
   // ─── Milestone-scoped ────────────────────────────────────────────────