@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.fb12b103

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`. 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 ────────────────────────────────────────────────

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

@@ -0,0 +1,412 @@
+// 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 { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
+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;
+
+/**
+ * Browser tools presented to run-uat. A derived view of the Browser Automation
+ * Contract vocabulary (shared/browser-contract.ts) — the contract module is the
+ * only place browser tool names are declared.
+ */
+export const RUN_UAT_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
+
+// ─── 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;
+}