@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.5457a158

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

@@ -0,0 +1,425 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Registry — the single declaration point for what a Unit type is (ADR-033).
+//
+// One Unit Descriptor per Unit type. The previously independent tables —
+// `KNOWN_UNIT_TYPES`/`UnitType` (unit-context-manifest.ts), `UNIT_TOOL_CONTRACTS`
+// (unit-tool-contracts.ts), the scope-class Sets (auto-unit-tool-scope.ts), and
+// the unit→phase switch (preferences-models.ts) — are derived views over this
+// registry. Import paths stay stable: each former home re-exports its view
+// (the `gsd-db.ts` barrel discipline).
+//
+// Behaviour-neutral by construction. The registry preserves the asymmetries the
+// old tables had drifted into, explicitly instead of accidentally:
+//   - `discuss-slice` and `execute-task-simple` had tool contracts and scope-Set
+//     membership but were absent from `KNOWN_UNIT_TYPES` → declared here as
+//     `kind: "variant"` (excluded from the derived `KNOWN_UNIT_TYPES`/`UnitType`).
+//   - `triage-captures` and `quick-task` had manifests but no tool contract and
+//     no phase routing → `toolContract: null`, `phaseChain: null`.
+// The parity test (tests/unit-registry.test.ts) pins every derived view to the
+// pre-registry values.
+//
+// Not yet declared here (remaining ADR-033 steps): the manifest data
+// (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
+// against the registry's `UnitType`) and prompt-template association (still
+// implicit in auto-prompts.ts builders).
+
+import type { CanonicalWorkflowToolName } from "@opengsd/contracts";
+import type { GSDModelPhaseKey } from "./preferences-types.js";
+import type { WorkflowMcpAdapterToolName } from "./workflow-tool-surface.js";
+
+// ─── Declaration vocabulary ───────────────────────────────────────────────
+
+/** Workflow-surface names a Unit contract may reference. Drift from WORKFLOW_TOOL_CONTRACTS fails typecheck. */
+export type UnitWorkflowToolName = CanonicalWorkflowToolName | WorkflowMcpAdapterToolName;
+
+export type UnitGsdToolName = UnitWorkflowToolName | "subagent";
+
+export interface UnitToolSurfaceContract {
+  allowedGsdTools: readonly UnitGsdToolName[];
+  requiredWorkflowTools: readonly UnitWorkflowToolName[];
+  forbiddenGsdTools?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Scope class drives the tool-scoping Sets:
+ *   - "execute-task"  — source-writing execution units; members of both the
+ *                       execute-task Set and the section-close gate Set.
+ *   - "section-close" — units that close quality gates by writing summary
+ *                       sections (gsd_save_gate_result is soft-blocked).
+ *   - "standard"      — everything else.
+ */
+export type UnitScopeClass = "execute-task" | "section-close" | "standard";
+
+export interface UnitDescriptor {
+  /** "variant" types are dispatchable but excluded from KNOWN_UNIT_TYPES/UnitType. */
+  readonly kind: "primary" | "variant";
+  readonly scopeClass: UnitScopeClass;
+  /**
+   * Ordered phase-bucket fallback chain for model/thinking resolution
+   * (ADR-026), most-specific first. `null` = no phase routing (the unit
+   * resolves against session defaults).
+   */
+  readonly phaseChain: readonly GSDModelPhaseKey[] | null;
+  /** `null` = the unit has no scoped gsd-tool contract. */
+  readonly toolContract: UnitToolSurfaceContract | null;
+}
+
+// ─── Shared tool-name constants (used by registry rows) ──────────────────
+
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+  "gsd_uat_exec",
+  "gsd_uat_result_save",
+  "gsd_resume",
+  "gsd_milestone_status",
+  "gsd_journal_query",
+] as const;
+
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+  "find",
+  "glob",
+  "grep",
+  "ls",
+  "read",
+] as const;
+
+export const RUN_UAT_BROWSER_TOOL_NAMES = [
+  "browser_navigate",
+  "browser_click",
+  "browser_type",
+  "browser_fill_form",
+  "browser_click_ref",
+  "browser_fill_ref",
+  "browser_wait_for",
+  "browser_assert",
+  "browser_verify",
+  "browser_screenshot",
+  "browser_snapshot_refs",
+  "browser_find",
+  "browser_get_console_logs",
+  "browser_get_network_logs",
+  "browser_evaluate",
+  "browser_reload",
+  "browser_batch",
+  "browser_act",
+] as const;
+
+// ─── The registry ─────────────────────────────────────────────────────────
+
+export const UNIT_REGISTRY = {
+  "research-milestone": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["research"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_summary_save"],
+    },
+  },
+  "plan-milestone": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["planning"],
+    toolContract: {
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_plan_milestone",
+        "gsd_plan_slice",
+        "gsd_decision_save",
+        "gsd_requirement_update",
+      ],
+      requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+    },
+  },
+  "discuss-milestone": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: [
+        "gsd_summary_save",
+        "gsd_decision_save",
+        "gsd_requirement_save",
+        "gsd_requirement_update",
+        "gsd_plan_milestone",
+        "gsd_milestone_generate_id",
+      ],
+      requiredWorkflowTools: [
+        "ask_user_questions",
+        "gsd_summary_save",
+        "gsd_requirement_save",
+        "gsd_requirement_update",
+        "gsd_plan_milestone",
+        "gsd_milestone_generate_id",
+      ],
+    },
+  },
+  "discuss-slice": {
+    kind: "variant",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+    },
+  },
+  "validate-milestone": {
+    kind: "primary",
+    scopeClass: "section-close",
+    phaseChain: ["validation", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+      requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+    },
+  },
+  "complete-milestone": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["completion"],
+    toolContract: {
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_requirement_update",
+        "gsd_summary_save",
+        "gsd_complete_milestone",
+        "subagent",
+      ],
+      requiredWorkflowTools: [
+        "gsd_milestone_status",
+        "gsd_requirement_update",
+        "gsd_summary_save",
+        "gsd_complete_milestone",
+      ],
+    },
+  },
+  "research-slice": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["research"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_summary_save"],
+    },
+  },
+  "plan-slice": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+    },
+  },
+  "refine-slice": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_plan_slice"],
+    },
+  },
+  "replan-slice": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_replan_slice"],
+    },
+  },
+  "complete-slice": {
+    kind: "primary",
+    scopeClass: "section-close",
+    phaseChain: ["completion"],
+    toolContract: {
+      allowedGsdTools: [
+        "gsd_slice_complete",
+        "gsd_task_reopen",
+        "gsd_replan_slice",
+        "gsd_decision_save",
+        "gsd_requirement_update",
+        "gsd_summary_save",
+        "subagent",
+      ],
+      requiredWorkflowTools: [
+        "gsd_slice_complete",
+        "gsd_task_reopen",
+        "gsd_replan_slice",
+        "gsd_requirement_update",
+        "gsd_summary_save",
+      ],
+      forbiddenGsdTools: {
+        gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+      },
+    },
+  },
+  "reassess-roadmap": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["validation", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+      requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+    },
+  },
+  "execute-task": {
+    kind: "primary",
+    scopeClass: "execute-task",
+    phaseChain: ["execution"],
+    toolContract: {
+      allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_task_complete"],
+    },
+  },
+  "execute-task-simple": {
+    kind: "variant",
+    scopeClass: "execute-task",
+    phaseChain: ["execution_simple", "execution"],
+    toolContract: {
+      allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_task_complete"],
+    },
+  },
+  "reactive-execute": {
+    kind: "primary",
+    scopeClass: "execute-task",
+    phaseChain: ["execution"],
+    toolContract: {
+      allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
+    },
+  },
+  "run-uat": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["uat", "completion"],
+    toolContract: {
+      allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
+      requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
+      forbiddenGsdTools: {
+        gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
+        gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
+        gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
+      },
+    },
+  },
+  "gate-evaluate": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["validation", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_save_gate_result"],
+      requiredWorkflowTools: ["gsd_save_gate_result"],
+    },
+  },
+  "rewrite-docs": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["validation", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: [],
+    },
+  },
+  // Sidecar units (triage, quick-task) — manifests exist, but no scoped tool
+  // contract and no phase routing (today's behaviour, preserved explicitly).
+  "triage-captures": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: null,
+    toolContract: null,
+  },
+  "quick-task": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: null,
+    toolContract: null,
+  },
+  // Deep planning mode (project-level) units
+  "workflow-preferences": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save"],
+      requiredWorkflowTools: [],
+    },
+  },
+  "discuss-project": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+      requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+    },
+  },
+  "discuss-requirements": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
+      requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
+    },
+  },
+  "research-decision": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["discuss", "planning"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save"],
+      requiredWorkflowTools: ["ask_user_questions"],
+    },
+  },
+  "research-project": {
+    kind: "primary",
+    scopeClass: "standard",
+    phaseChain: ["research"],
+    toolContract: {
+      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      requiredWorkflowTools: [],
+    },
+  },
+} as const satisfies Record<string, UnitDescriptor>;
+
+// ─── Derived types and views ──────────────────────────────────────────────
+
+/** Every dispatchable unit type, including variants. */
+export type UnitTypeOrVariant = keyof typeof UNIT_REGISTRY;
+
+type PrimaryUnitKeys = {
+  [K in UnitTypeOrVariant]: (typeof UNIT_REGISTRY)[K]["kind"] extends "primary" ? K : never;
+}[UnitTypeOrVariant];
+
+/**
+ * The manifest-strict unit-type union — every type with a `UNIT_MANIFESTS`
+ * entry. Variants are excluded, exactly as the old hand-maintained
+ * `KNOWN_UNIT_TYPES` excluded them.
+ */
+export type UnitType = PrimaryUnitKeys;
+
+const ALL_UNIT_KEYS = Object.keys(UNIT_REGISTRY) as UnitTypeOrVariant[];
+
+export const KNOWN_UNIT_TYPES: readonly UnitType[] = Object.freeze(
+  ALL_UNIT_KEYS.filter((t): t is UnitType => UNIT_REGISTRY[t].kind === "primary"),
+);
+
+export const EXECUTE_TASK_UNIT_TYPES: ReadonlySet<string> = new Set(
+  ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass === "execute-task"),
+);
+
+// Execute-task units close gates via summary sections too, so the section-close
+// gate Set is every non-"standard" scope class.
+export const SECTION_CLOSE_GATE_UNIT_TYPES: ReadonlySet<string> = new Set(
+  ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass !== "standard"),
+);
+
+export function getUnitDescriptor(unitType: string): UnitDescriptor | undefined {
+  return (UNIT_REGISTRY as Record<string, UnitDescriptor>)[unitType];
+}
+
+/** Phase-bucket fallback chain for a unit type, or null when the registry has no routing for it. */
+export function getUnitPhaseChain(unitType: string): readonly GSDModelPhaseKey[] | null {
+  return getUnitDescriptor(unitType)?.phaseChain ?? null;
+}

package/src/resources/extensions/gsd/unit-tool-contracts.ts

@@ -1,198 +1,33 @@
 // Project/App: gsd-pi
-// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
-
-export interface UnitToolSurfaceContract {
-  allowedGsdTools: readonly string[];
-  requiredWorkflowTools: readonly string[];
-  forbiddenGsdTools?: Readonly<Record<string, string>>;
-}
-
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-  "gsd_uat_exec",
-  "gsd_uat_result_save",
-  "gsd_resume",
-  "gsd_milestone_status",
-  "gsd_journal_query",
-] as const;
-
-export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
-  "find",
-  "glob",
-  "grep",
-  "ls",
-  "read",
-] as const;
-
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-  "browser_navigate",
-  "browser_click",
-  "browser_type",
-  "browser_fill_form",
-  "browser_click_ref",
-  "browser_fill_ref",
-  "browser_wait_for",
-  "browser_assert",
-  "browser_verify",
-  "browser_screenshot",
-  "browser_snapshot_refs",
-  "browser_find",
-  "browser_get_console_logs",
-  "browser_get_network_logs",
-  "browser_evaluate",
-  "browser_reload",
-  "browser_batch",
-  "browser_act",
-] as const;
+// File Purpose: Unit-to-tool contract views derived from the Unit Registry (ADR-033).
+//
+// The contract data lives in unit-registry.ts (one Unit Descriptor per unit
+// type). This file keeps the established import surface: the derived
+// `UNIT_TOOL_CONTRACTS` table and its accessor functions are unchanged for
+// consumers.
+
+import {
+  UNIT_REGISTRY,
+  type UnitToolSurfaceContract,
+  type UnitWorkflowToolName,
+} from "./unit-registry.js";
+
+export {
+  RUN_UAT_WORKFLOW_TOOL_NAMES,
+  RUN_UAT_READ_ONLY_TOOL_NAMES,
+  RUN_UAT_BROWSER_TOOL_NAMES,
+  type UnitToolSurfaceContract,
+  type UnitWorkflowToolName,
+  type UnitGsdToolName,
+} from "./unit-registry.js";
 
 export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
 
-export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
-  "research-milestone": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_summary_save"],
-  },
-  "plan-milestone": {
-    allowedGsdTools: [
-      "gsd_milestone_status",
-      "gsd_plan_milestone",
-      "gsd_plan_slice",
-      "gsd_decision_save",
-      "gsd_requirement_update",
-    ],
-    requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
-  },
-  "discuss-milestone": {
-    allowedGsdTools: [
-      "gsd_summary_save",
-      "gsd_decision_save",
-      "gsd_requirement_save",
-      "gsd_requirement_update",
-      "gsd_plan_milestone",
-      "gsd_milestone_generate_id",
-    ],
-    requiredWorkflowTools: [
-      "ask_user_questions",
-      "gsd_summary_save",
-      "gsd_requirement_save",
-      "gsd_requirement_update",
-      "gsd_plan_milestone",
-      "gsd_milestone_generate_id",
-    ],
-  },
-  "discuss-slice": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-  },
-  "validate-milestone": {
-    allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-    requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
-  },
-  "complete-milestone": {
-    allowedGsdTools: [
-      "gsd_milestone_status",
-      "gsd_requirement_update",
-      "gsd_summary_save",
-      "gsd_complete_milestone",
-      "subagent",
-    ],
-    requiredWorkflowTools: [
-      "gsd_milestone_status",
-      "gsd_requirement_update",
-      "gsd_summary_save",
-      "gsd_complete_milestone",
-    ],
-  },
-  "research-slice": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_summary_save"],
-  },
-  "plan-slice": {
-    allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
-  },
-  "refine-slice": {
-    allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_plan_slice"],
-  },
-  "replan-slice": {
-    allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_replan_slice"],
-  },
-  "complete-slice": {
-    allowedGsdTools: [
-      "gsd_slice_complete",
-      "gsd_task_reopen",
-      "gsd_replan_slice",
-      "gsd_decision_save",
-      "gsd_requirement_update",
-      "gsd_summary_save",
-      "subagent",
-    ],
-    requiredWorkflowTools: [
-      "gsd_slice_complete",
-      "gsd_task_reopen",
-      "gsd_replan_slice",
-      "gsd_requirement_update",
-      "gsd_summary_save",
-    ],
-    forbiddenGsdTools: {
-      gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
-    },
-  },
-  "reassess-roadmap": {
-    allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-    requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-  },
-  "execute-task": {
-    allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_task_complete"],
-  },
-  "execute-task-simple": {
-    allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_task_complete"],
-  },
-  "reactive-execute": {
-    allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
-  },
-  "run-uat": {
-    allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
-    requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
-    forbiddenGsdTools: {
-      gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
-      gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
-      gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
-    },
-  },
-  "gate-evaluate": {
-    allowedGsdTools: ["gsd_save_gate_result"],
-    requiredWorkflowTools: ["gsd_save_gate_result"],
-  },
-  "rewrite-docs": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: [],
-  },
-  "workflow-preferences": {
-    allowedGsdTools: ["gsd_summary_save"],
-    requiredWorkflowTools: [],
-  },
-  "discuss-project": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-    requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-  },
-  "discuss-requirements": {
-    allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
-    requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
-  },
-  "research-decision": {
-    allowedGsdTools: ["gsd_summary_save"],
-    requiredWorkflowTools: ["ask_user_questions"],
-  },
-  "research-project": {
-    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: [],
-  },
-};
+export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = Object.fromEntries(
+  Object.entries(UNIT_REGISTRY).flatMap(([unitType, descriptor]) =>
+    descriptor.toolContract ? [[unitType, descriptor.toolContract]] : [],
+  ),
+);
 
 export const AUTO_UNIT_SCOPED_TOOLS: Record<string, readonly string[]> = Object.fromEntries(
   Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]),
@@ -202,7 +37,7 @@ export function getUnitToolSurfaceContract(unitType: string): UnitToolSurfaceCon
   return UNIT_TOOL_CONTRACTS[unitType];
 }
 
-export function getRequiredWorkflowToolsForUnit(unitType: string): string[] {
+export function getRequiredWorkflowToolsForUnit(unitType: string): UnitWorkflowToolName[] {
   return [...(UNIT_TOOL_CONTRACTS[unitType]?.requiredWorkflowTools ?? [])];
 }
 

package/src/resources/extensions/gsd/workflow-tool-surface.ts

@@ -28,7 +28,7 @@ export const WORKFLOW_TOOL_ALIAS_PAIRS: readonly WorkflowToolAliasPair[] =
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL: Readonly<Record<string, string>> =
   Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
 
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_cancel",
   "gsd_captures",
   "ask_user_questions",
@@ -45,6 +45,9 @@ const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
   "gsd_status",
 ] as const;
 
+/** Session-orchestration tools exposed by the workflow MCP adapter alongside the contract tools. */
+export type WorkflowMcpAdapterToolName = (typeof WORKFLOW_MCP_ADAPTER_TOOL_NAMES)[number];
+
 export const WORKFLOW_TOOL_SURFACE_NAMES = [
   ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
   ...DB_WORKFLOW_TOOL_NAMES,