@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

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

@@ -1,9 +1,11 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
+import { parseMcpToolName } from "./mcp-tool-name.js";
 
 export type { UatType } from "./files.js";
 
@@ -122,31 +124,39 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
   return isUatType(uatType) && UAT_MODE_POLICIES[uatType].browserTools;
 }
 
-function canonicalPresentedToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
-
 export function isUatBrowserToolName(toolName: string): boolean {
-  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: readonly string[] | undefined): boolean {
   return Array.isArray(activeTools) && activeTools.some(isUatBrowserToolName);
 }
 
+export function resolveUatBrowserToolSurface(options: {
+  activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
+}): readonly string[] | undefined {
+  const surfaces = [options.activeTools, options.registeredTools].filter(Array.isArray);
+  if (surfaces.length === 0) return undefined;
+  return [...new Set(surfaces.flat())];
+}
+
 export function getUatBrowserToolSupportError(options: {
   uatType: UatType;
   activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
   milestoneId: string;
   sliceId: string;
 }): string | null {
   if (!uatTypeIncludesBrowser(options.uatType)) return null;
-  if (!Array.isArray(options.activeTools)) return null;
-  if (hasUatBrowserToolSurface(options.activeTools)) return null;
+  const toolSurface = resolveUatBrowserToolSurface(options);
+  if (!toolSurface) return null;
+  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: UatType | undefined): boolean {

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

@@ -103,7 +103,7 @@ function mergeBlockedTools(
 ): UatPresentationInput["blockedTools"] {
   const merged = new Map<string, { name: string; reason: string }>();
   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()];
 }
@@ -299,22 +299,18 @@ function quoteToolNames(toolNames: readonly string[]): string {
 }
 
 function validateCanonicalPresentation(params: UatResultSaveParams): string | null {
-  const aliasHints: Record<string, string> = {
-    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: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
-    const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
-    const canonical = aliasHints[baseName];
-    if (canonical) errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${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)
+      canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)
     ),
   );
   const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter(
@@ -329,11 +325,11 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
   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: string[] = [];
   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);
     }
@@ -346,7 +342,7 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
 
   const blockedCanonical = new Set(
     params.presentation.blockedTools.map((entry) =>
-      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)
+      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name)
     ),
   );
   const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter(

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

@@ -45,6 +45,7 @@ import {
   type ContextModePolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import type { UnitPromptContextContract } from "./tool-contract.js";
 
 /**
  * Async function mapping an artifact key to its inlined-content string,
@@ -132,6 +133,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
@@ -146,7 +157,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}`;
   }
@@ -195,8 +207,32 @@ export interface ComposedUnitContext {
   readonly inline: string;
 }
 
+export type UnitContextBlockMode = "prepend" | "inline" | "excerpt" | "computed";
+
+export interface ComposedUnitContextBlock {
+  readonly key: string;
+  readonly mode: UnitContextBlockMode;
+  readonly body: string;
+}
+
+export interface ComposedContractedUnitContext extends ComposedUnitContext {
+  readonly blocks: readonly ComposedUnitContextBlock[];
+  readonly onDemand: readonly ArtifactKey[];
+}
+
 const SECTION_SEPARATOR = "\n\n---\n\n";
 
+interface UnitContextCompositionContract {
+  readonly unitType: string;
+  readonly artifacts: {
+    readonly inline: readonly ArtifactKey[];
+    readonly excerpt: readonly ArtifactKey[];
+    readonly onDemand: readonly ArtifactKey[];
+    readonly computed: readonly ComputedArtifactId[];
+    readonly prepend: readonly ComputedArtifactId[];
+  };
+}
+
 /**
  * Compose all manifest-declared context for a unit type using the v2
  * surface. Walks `prepend` first (computed-only), then the `inline` list
@@ -220,36 +256,73 @@ export async function composeUnitContext(
   const manifest: UnitContextManifest | null = 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: UnitPromptContextContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  return composeDeclaredUnitContext(contract, opts);
+}
+
+async function composeDeclaredUnitContext(
+  contract: UnitContextCompositionContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  // 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: ComposeUnitContextOptions = {
     ...opts,
-    base: { ...opts.base, unitType },
+    base: { ...opts.base, unitType: contract.unitType },
   };
 
-  const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
-  const inlineBlocks: string[] = [];
+  const prependBlocks = await runComputedBlocks(
+    contract.artifacts.prepend,
+    normalizedOpts,
+    "prepend",
+  );
+  const inlineBlocks: ComposedUnitContextBlock[] = [];
 
-  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,
   };
 }
 
@@ -258,10 +331,11 @@ export async function composeUnitContext(
  * Missing registry entries (manifest declares the id but caller didn't
  * register it) are skipped silently — see composeUnitContext rationale.
  */
-async function runComputed(
+async function runComputedBlocks(
   ids: readonly ComputedArtifactId[],
   opts: ComposeUnitContextOptions,
-): Promise<string[]> {
+  mode: Extract<UnitContextBlockMode, "prepend" | "computed">,
+): Promise<ComposedUnitContextBlock[]> {
   if (ids.length === 0 || !opts.computed) return [];
   // Type safety lives at the registration boundary (caller-supplied
   // `computed` is typed against ComputedArtifactInputs[K] per id). Inside
@@ -274,12 +348,14 @@ async function runComputed(
     inputs: unknown;
   };
   const registry = opts.computed as Record<string, AnyEntry | undefined>;
-  const out: string[] = [];
+  const out: ComposedUnitContextBlock[] = [];
   for (const id of ids) {
     const entry = registry[id];
     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/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 ────────────────────────────────────────────────