@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/dist/resources/extensions/gsd/uat-policy.js

@@ -1,15 +1,10 @@
 // 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 { hasBrowserRequiredText } from "./browser-evidence.js";
-export const UAT_TYPES = [
-    "artifact-driven",
-    "browser-executable",
-    "runtime-executable",
-    "live-runtime",
-    "mixed",
-    "human-experience",
-];
+import { parseMcpToolName } from "./mcp-tool-name.js";
+export const UAT_TYPES = UAT_TYPE_KEYWORDS;
 export const UAT_MODE_POLICIES = {
     "artifact-driven": {
         browserTools: false,
@@ -54,23 +49,55 @@ export function isUatType(value) {
 export function getDeclaredUatType(content) {
     return extractUatType(content) ?? "artifact-driven";
 }
-export function classifyUatContent(content) {
-    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) {
+    return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+function resolveEffectiveUatTypeFromPolicy(declaredType, browserRequired, content) {
+    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) {
+    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, supplementalContext = "") {
+    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) {
-    const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy) {
     return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
+export function shouldEscalateArtifactUatToBrowser(content) {
+    return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
 export function resolveEffectiveUatType(content) {
     return classifyUatContent(content).effectiveType;
 }
@@ -80,26 +107,31 @@ export function shouldDispatchUatForContent(content, prefs) {
 export function uatTypeIncludesBrowser(uatType) {
     return isUatType(uatType) && UAT_MODE_POLICIES[uatType].browserTools;
 }
-function canonicalPresentedToolName(toolName) {
-    if (!toolName.startsWith("mcp__"))
-        return toolName;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
 export function isUatBrowserToolName(toolName) {
-    return canonicalPresentedToolName(toolName).startsWith("browser_");
+    const parsed = parseMcpToolName(toolName);
+    const canonicalName = parsed?.toolName ?? toolName;
+    if (hasBrowserContractPrefix(canonicalName))
+        return true;
+    return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 export function hasUatBrowserToolSurface(activeTools) {
     return Array.isArray(activeTools) && activeTools.some(isUatBrowserToolName);
 }
+export function resolveUatBrowserToolSurface(options) {
+    const surfaces = [options.activeTools, options.registeredTools].filter(Array.isArray);
+    if (surfaces.length === 0)
+        return undefined;
+    return [...new Set(surfaces.flat())];
+}
 export function getUatBrowserToolSupportError(options) {
     if (!uatTypeIncludesBrowser(options.uatType))
         return null;
-    if (!Array.isArray(options.activeTools))
+    const toolSurface = resolveUatBrowserToolSurface(options);
+    if (!toolSurface)
         return null;
-    if (hasUatBrowserToolSurface(options.activeTools))
+    if (hasUatBrowserToolSurface(toolSurface))
         return null;
-    return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the active tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
+    return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the run-uat tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
 }
 export function isPartialEligibleUatType(uatType) {
     return !!uatType && UAT_MODE_POLICIES[uatType].partialEligible;

package/dist/resources/extensions/gsd/uat-run.js

@@ -13,7 +13,7 @@ function isNonEmptyString(value) {
 function mergeBlockedTools(current, canonical) {
     const merged = new Map();
     for (const entry of [...(current ?? []), ...canonical]) {
-        merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name), entry);
+        merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name), entry);
     }
     return [...merged.values()];
 }
@@ -204,20 +204,15 @@ function quoteToolNames(toolNames) {
     return toolNames.map((toolName) => `"${toolName}"`).join(", ");
 }
 function validateCanonicalPresentation(params) {
-    const aliasHints = {
-        gsd_save_summary: "gsd_summary_save",
-        gsd_complete_task: "gsd_task_complete",
-        gsd_complete_slice: "gsd_slice_complete",
-        gsd_milestone_complete: "gsd_complete_milestone",
-    };
     const errors = [];
     for (const toolName of params.presentation.presentedTools) {
-        const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
-        const canonical = aliasHints[baseName];
-        if (canonical)
+        const baseName = parseMcpToolName(toolName)?.toolName ?? toolName;
+        const canonical = canonicalWorkflowToolName(baseName);
+        if (canonical !== baseName) {
             errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
+        }
     }
-    const presentedCanonical = new Set(params.presentation.presentedTools.map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
+    const presentedCanonical = new Set(params.presentation.presentedTools.map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)));
     const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter((requiredTool) => !presentedCanonical.has(requiredTool));
     if (missingRequiredTools.length === 1) {
         errors.push(`presentation is missing required UAT tool "${missingRequiredTools[0]}"`);
@@ -227,10 +222,10 @@ function validateCanonicalPresentation(params) {
     }
     const forbiddenCanonical = new Set(RUN_UAT_FORBIDDEN_TOOL_NAMES
         .filter((toolName) => !toolName.includes("*"))
-        .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
+        .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)));
     const forbiddenPresentedTools = [];
     for (const toolName of params.presentation.presentedTools) {
-        const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
+        const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName);
         if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
             forbiddenPresentedTools.push(toolName);
         }
@@ -241,7 +236,7 @@ function validateCanonicalPresentation(params) {
     else if (forbiddenPresentedTools.length > 1) {
         errors.push(`presentation includes forbidden run-uat tools ${quoteToolNames(forbiddenPresentedTools)}`);
     }
-    const blockedCanonical = new Set(params.presentation.blockedTools.map((entry) => canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)));
+    const blockedCanonical = new Set(params.presentation.blockedTools.map((entry) => canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name)));
     const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter((blockedTool) => !blockedCanonical.has(blockedTool));
     if (missingBlockedTools.length === 1) {
         errors.push(`presentation must record "${missingBlockedTools[0]}" as blocked during run-uat`);

package/dist/resources/extensions/gsd/undo.js

@@ -11,7 +11,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";
 /**
  * Undo the last completed unit: revert git commits,
@@ -275,20 +275,21 @@ export async function handleResetSlice(args, ctx, _pi, basePath) {
             `Run /gsd reset-slice ${rawId} --force to confirm.`, "warning");
         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);
             summariesDeleted++;
         }
     }
-    // Reset slice status
-    updateSliceStatus(mid, sid, "active");
     // Delete slice summary and UAT files
     let sliceFilesDeleted = 0;
     const slicePath = resolveSlicePath(basePath, mid, sid);

package/dist/resources/extensions/gsd/unit-closeout.js

@@ -0,0 +1,138 @@
+// 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 } 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";
+const defaultDeps = {
+    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, deps = defaultDeps) {
+    let commitMessage = null;
+    let gitVerdict;
+    let notice;
+    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 = {
+    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 = {
+    task: "execute-task",
+    slice: "complete-slice",
+    milestone: "complete-milestone",
+};
+export function isUnitCloseoutTool(canonicalToolName) {
+    return canonicalToolName in CLOSEOUT_TOOL_BOUNDARIES;
+}
+function readId(input, camel, snake) {
+    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, deps = defaultDeps) {
+    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/dist/resources/extensions/gsd/unit-context-composer.js

@@ -36,6 +36,7 @@
 // owned by the unit, not in the composer. Reviews must enforce this — it
 // is the difference between an orchestrator and a runaway DSL.
 import { resolveManifest, } from "./unit-context-manifest.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 /**
  * Produce the inlined-context portion of a unit's system prompt by
  * walking the manifest's `artifacts.inline` list in order and calling
@@ -91,6 +92,14 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE = {
     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.",
 };
+// 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 = {
+    "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
@@ -103,7 +112,7 @@ export function composeContextModeInstructions(unitType, opts) {
     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}`;
     }
@@ -114,6 +123,70 @@ export function composeContextModeInstructions(unitType, opts) {
         guidance,
     ].join("\n");
 }
+const TOOL_SURFACE_GUIDANCE_BY_UNIT = {
+    "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) {
+    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, unitGuidance) {
+    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, opts) {
+    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) => 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");
+}
 const SECTION_SEPARATOR = "\n\n---\n\n";
 /**
  * Compose all manifest-declared context for a unit type using the v2
@@ -135,37 +208,56 @@ export async function composeUnitContext(unitType, opts) {
     const manifest = resolveManifest(unitType);
     if (!manifest)
         return { prepend: "", inline: "" };
-    // Single-source `unitType`: the manifest is resolved against the
+    const composed = await composeDeclaredUnitContext({
+        unitType,
+        artifacts: {
+            inline: manifest.artifacts.inline,
+            excerpt: manifest.artifacts.excerpt,
+            onDemand: manifest.artifacts.onDemand,
+            computed: manifest.artifacts.computed ?? [],
+            prepend: manifest.prepend ?? [],
+        },
+    }, opts);
+    return {
+        prepend: composed.prepend,
+        inline: composed.inline,
+    };
+}
+export async function composeContractedUnitContext(contract, opts) {
+    return composeDeclaredUnitContext(contract, opts);
+}
+async function composeDeclaredUnitContext(contract, opts) {
+    // Single-source `unitType`: contract/manifest selection comes from the
     // function arg, but computed builders read it from `base.unitType`.
-    // If those ever diverge (caller passes one type to composeUnitContext
-    // but a different one in opts.base), the composer would silently
-    // mix one unit's manifest with another unit's computed context.
-    // Normalize here so the composer dispatches a consistent identity
-    // through to every builder.
+    // Normalize here so every builder sees the same Unit identity.
     const normalizedOpts = {
         ...opts,
-        base: { ...opts.base, unitType },
+        base: { ...opts.base, unitType: contract.unitType },
     };
-    const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+    const prependBlocks = await runComputedBlocks(contract.artifacts.prepend, normalizedOpts, "prepend");
     const inlineBlocks = [];
-    for (const key of manifest.artifacts.inline) {
+    for (const key of contract.artifacts.inline) {
         if (!normalizedOpts.resolveArtifact)
             break;
         const body = await normalizedOpts.resolveArtifact(key);
-        if (body && body.length > 0)
-            inlineBlocks.push(body);
+        if (body && body.length > 0) {
+            inlineBlocks.push({ key, mode: "inline", body });
+        }
     }
-    for (const key of manifest.artifacts.excerpt) {
+    for (const key of contract.artifacts.excerpt) {
         if (!normalizedOpts.resolveExcerpt)
             break;
         const body = await normalizedOpts.resolveExcerpt(key);
-        if (body && body.length > 0)
-            inlineBlocks.push(body);
+        if (body && body.length > 0) {
+            inlineBlocks.push({ key, mode: "excerpt", body });
+        }
     }
-    inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+    inlineBlocks.push(...await runComputedBlocks(contract.artifacts.computed, normalizedOpts, "computed"));
     return {
-        prepend: prependBlocks.join(SECTION_SEPARATOR),
-        inline: inlineBlocks.join(SECTION_SEPARATOR),
+        prepend: prependBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+        inline: inlineBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+        blocks: [...prependBlocks, ...inlineBlocks],
+        onDemand: contract.artifacts.onDemand,
     };
 }
 /**
@@ -173,7 +265,7 @@ export async function composeUnitContext(unitType, opts) {
  * Missing registry entries (manifest declares the id but caller didn't
  * register it) are skipped silently — see composeUnitContext rationale.
  */
-async function runComputed(ids, opts) {
+async function runComputedBlocks(ids, opts, mode) {
     if (ids.length === 0 || !opts.computed)
         return [];
     const registry = opts.computed;
@@ -183,8 +275,9 @@ async function runComputed(ids, opts) {
         if (!entry)
             continue;
         const body = await entry.build(entry.inputs, opts.base);
-        if (body && body.length > 0)
-            out.push(body);
+        if (body && body.length > 0) {
+            out.push({ key: id, mode, body });
+        }
     }
     return out;
 }

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -118,33 +118,10 @@ const TOOLS_DOCS = {
  * 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",
-];
+// Unit-type vocabulary is owned by the Unit Registry (ADR-033); re-exported
+// here so established import paths keep working.
+import { KNOWN_UNIT_TYPES } from "./unit-registry.js";
+export { KNOWN_UNIT_TYPES };
 export const UNIT_MANIFESTS = {
     // ─── Milestone-scoped ────────────────────────────────────────────────
     "research-milestone": {