@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.a5a2de8

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -1,6 +1,18 @@
 // Project/App: gsd-pi
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
 
+import {
+  RUN_UAT_READ_ONLY_TOOL_NAMES,
+  RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+  RUN_UAT_WORKFLOW_TOOL_NAMES,
+} from "./unit-tool-contracts.js";
+
+export {
+  RUN_UAT_READ_ONLY_TOOL_NAMES,
+  RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+  RUN_UAT_WORKFLOW_TOOL_NAMES,
+} from "./unit-tool-contracts.js";
+
 export type ToolPresentationSurface = "provider-tools" | "claude-code-sdk" | "mcp" | "hybrid";
 
 export interface ToolPresentationModel {
@@ -20,14 +32,6 @@ export interface ToolPresentationPlan {
   diagnostics: 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_FORBIDDEN_TOOL_NAMES = [
   "edit",
   "write",
@@ -105,10 +109,36 @@ function addBlockedTool(
 export function buildRunUatCanonicalToolNames(options: { includeBrowserTools?: readonly string[] } = {}): string[] {
   return dedupe([
     ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+    ...RUN_UAT_READ_ONLY_TOOL_NAMES,
     ...(options.includeBrowserTools ?? []),
   ]);
 }
 
+export function buildRunUatResultPresentation(options: {
+  surface?: ToolPresentationSurface;
+  includeBrowserTools?: readonly string[];
+  presentedTools?: readonly string[];
+} = {}): {
+  surface: ToolPresentationSurface;
+  presentedTools: string[];
+  blockedTools: Array<{ name: string; reason: string }>;
+  toolPresentationPlanId: string;
+} {
+  const presentedTools = options.presentedTools
+    ? dedupe(options.presentedTools)
+    : buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools });
+  const blockedTools = RUN_UAT_FORBIDDEN_TOOL_NAMES
+    .filter((toolName) => !toolName.includes("*"))
+    .map((name) => ({ name, reason: "forbidden during run-uat" }));
+
+  return {
+    surface: options.surface ?? "mcp",
+    presentedTools,
+    blockedTools,
+    toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+  };
+}
+
 export function resolveToolPresentationPlan(options: {
   phase: string;
   surface: ToolPresentationSurface;

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

@@ -48,9 +48,11 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
 import {
+  buildRunUatResultPresentation,
   canonicalWorkflowToolName,
   parseMcpToolName,
   RUN_UAT_FORBIDDEN_TOOL_NAMES,
+  RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "../tool-presentation-plan.js";
 
@@ -90,7 +92,7 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   if (!snapshot.active || !snapshot.currentUnit) return null;
   if (snapshot.currentUnit.type === requiredUnitType) return null;
 
-  const error = `HARD BLOCK: ${operation} may only run from ${requiredUnitType}; active unit is ${snapshot.currentUnit.type}. The orchestrator owns phase transitions.`;
+  const error = `HARD BLOCK: Tool Contract failure: ${operation} may only run from ${requiredUnitType}; active unit is ${snapshot.currentUnit.type}. Fix unit-tool-contracts.ts or the active Unit prompt. The orchestrator owns phase transitions.`;
   return {
     content: [{ type: "text", text: error }],
     details: { operation, error },
@@ -178,7 +180,11 @@ export async function executeSummarySave(
   if (rootArtifactGuard.block) {
     return {
       content: [{ type: "text", text: `Error saving artifact: ${rootArtifactGuard.reason ?? "root artifact write blocked"}` }],
-      details: { operation: "save_summary", error: "root_artifact_write_blocked" },
+      details: {
+        operation: "save_summary",
+        error: "root_artifact_write_blocked",
+        displayReason: "Approval confirmation required before saving final project setup artifacts.",
+      },
       isError: true,
     };
   }
@@ -191,9 +197,13 @@ export async function executeSummarySave(
   if (contextGuard.block) {
     return {
       content: [{ type: "text", text: `Error saving artifact: ${contextGuard.reason ?? "context write blocked"}` }],
-      details: { operation: "save_summary", error: "context_write_blocked" },
-    isError: true,
-      };
+      details: {
+        operation: "save_summary",
+        error: "context_write_blocked",
+        displayReason: "Depth check required before writing milestone context.",
+      },
+      isError: true,
+    };
   }
   try {
     let relativePath: string;
@@ -441,6 +451,9 @@ export interface UatEvidenceRef {
   kind: "gsd_uat_exec" | "gsd_exec" | "screenshot" | "log" | "url" | "browser";
   ref: string;
   note?: string;
+  unitType?: string;
+  tool?: string;
+  executionId?: string;
 }
 
 export interface UatCheckResultInput {
@@ -1008,10 +1021,68 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+function mergeBlockedTools(
+  current: UatPresentationInput["blockedTools"] | undefined,
+  canonical: UatPresentationInput["blockedTools"],
+): 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);
+  }
+  return [...merged.values()];
+}
+
+function mergePresentedTools(current: readonly string[] | undefined, canonical: readonly string[]): string[] {
+  return [...new Set([...(current ?? []), ...canonical])];
+}
+
+function normalizeUatVerdict(params: UatResultSaveParams): UatResultSaveParams {
+  const raw = params as Partial<UatResultSaveParams> & Record<string, unknown>;
+  if (typeof raw.verdict === "string") {
+    return { ...params, verdict: raw.verdict.toUpperCase() as UatVerdict };
+  }
+  return params;
+}
+
+function supplyDefaultPresentation(params: UatResultSaveParams): UatResultSaveParams {
+  const raw = params as Partial<UatResultSaveParams> & Record<string, unknown>;
+  if (!raw.presentation) {
+    return { ...params, presentation: buildRunUatResultPresentation() };
+  }
+  return params;
+}
+
+function mergeCanonicalPresentation(params: UatResultSaveParams): UatResultSaveParams {
+  const canonicalPresentation = buildRunUatResultPresentation();
+  const providedPresentation = params.presentation as Partial<UatPresentationInput>;
+  return {
+    ...params,
+    presentation: {
+      ...providedPresentation,
+      surface: providedPresentation.surface ?? canonicalPresentation.surface,
+      presentedTools: mergePresentedTools(providedPresentation.presentedTools, canonicalPresentation.presentedTools),
+      blockedTools: mergeBlockedTools(providedPresentation.blockedTools, canonicalPresentation.blockedTools),
+      toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+    } as UatPresentationInput,
+  };
+}
+
+const VALID_UAT_TYPES: readonly UatType[] = [
+  "artifact-driven",
+  "browser-executable",
+  "runtime-executable",
+  "live-runtime",
+  "mixed",
+  "human-experience",
+];
+
 function ensureUatRequiredFields(params: UatResultSaveParams): string | null {
   if (!isNonEmptyString(params.milestoneId)) return "milestoneId is required";
   if (!isNonEmptyString(params.sliceId)) return "sliceId is required";
   if (!isNonEmptyString(params.uatType)) return "uatType is required";
+  if (!(VALID_UAT_TYPES as readonly string[]).includes(params.uatType)) {
+    return `uatType must be one of: ${VALID_UAT_TYPES.join(", ")}`;
+  }
   if (!["PASS", "FAIL", "PARTIAL"].includes(params.verdict)) return "verdict must be PASS, FAIL, or PARTIAL";
   if (!Array.isArray(params.checks) || params.checks.length === 0) return "checks must contain at least one UAT check";
   if (!params.presentation || !Array.isArray(params.presentation.presentedTools)) return "presentation.presentedTools is required";
@@ -1147,6 +1218,15 @@ function validateUatChecks(basePath: string, params: UatResultSaveParams): strin
   return null;
 }
 
+function validateFreshUatOwnedEvidence(params: UatResultSaveParams): string | null {
+  const hasFreshUatEvidence = params.checks.some((check) =>
+    (check.evidence ?? []).some((evidence) => evidence.kind === "gsd_uat_exec")
+  );
+  return hasFreshUatEvidence
+    ? null
+    : "UAT Assessment requires at least one fresh gsd_uat_exec evidence reference from run-uat";
+}
+
 function validateUatMode(params: UatResultSaveParams): string | null {
   const modes = new Set(params.checks.map((check) => check.mode));
   const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
@@ -1306,15 +1386,30 @@ export async function executeUatResultSave(
   params: UatResultSaveParams,
   basePath: string = process.cwd(),
 ): Promise<ToolExecutionResult> {
+  const unitGuard = blockIfWrongAutoUnit("run-uat", "save_uat_result");
+  if (unitGuard) return unitGuard;
+
+  // Phase 1: normalize verdict and supply the canonical presentation when none was provided.
+  params = normalizeUatVerdict(params);
+  params = supplyDefaultPresentation(params);
+
   const dbAvailable = await ensureDbOpen(basePath);
   if (!dbAvailable) return errorResult("save_uat_result", "GSD database is not available.", "db_unavailable");
 
+  // Phase 2: validate the submitted presentation before the canonical merge so that
+  // presentations missing required workflow tools are rejected rather than silently patched.
   const requiredError = ensureUatRequiredFields(params);
   if (requiredError) return errorResult("save_uat_result", requiredError, "invalid_params");
   const presentationError = validateCanonicalPresentation(params);
   if (presentationError) return errorResult("save_uat_result", presentationError, "alias_tool_name");
+
+  // Phase 3: merge in the canonical plan ID and read-only audit tools so the persisted
+  // artifact always carries the full audit surface even when the provider omitted them.
+  params = mergeCanonicalPresentation(params);
   const checkError = validateUatChecks(basePath, params);
   if (checkError) return errorResult("save_uat_result", checkError, "invalid_evidence");
+  const freshEvidenceError = validateFreshUatOwnedEvidence(params);
+  if (freshEvidenceError) return errorResult("save_uat_result", freshEvidenceError, "missing_fresh_uat_evidence");
   const modeError = validateUatMode(params);
   if (modeError) return errorResult("save_uat_result", modeError, "uat_mode_mismatch");
 

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

@@ -0,0 +1,186 @@
+// 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;
+
+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_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
+    requiredWorkflowTools: ["gsd_plan_milestone"],
+  },
+  "discuss-milestone": {
+    allowedGsdTools: [
+      "gsd_summary_save",
+      "gsd_decision_save",
+      "gsd_requirement_save",
+      "gsd_requirement_update",
+      "gsd_plan_milestone",
+      "gsd_milestone_generate_id",
+    ],
+    requiredWorkflowTools: [
+      "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: ["gsd_summary_save"],
+  },
+  "validate-milestone": {
+    allowedGsdTools: ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+    requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+  },
+  "complete-milestone": {
+    allowedGsdTools: ["gsd_complete_milestone", "subagent"],
+    requiredWorkflowTools: ["gsd_milestone_status", "gsd_complete_milestone"],
+  },
+  "research-slice": {
+    allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+    requiredWorkflowTools: ["gsd_summary_save"],
+  },
+  "plan-slice": {
+    allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+    requiredWorkflowTools: ["gsd_plan_slice"],
+  },
+  "refine-slice": {
+    allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+    requiredWorkflowTools: [],
+  },
+  "replan-slice": {
+    allowedGsdTools: ["gsd_replan_slice", "gsd_plan_task", "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",
+      "subagent",
+    ],
+    requiredWorkflowTools: ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"],
+    forbiddenGsdTools: {
+      gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+    },
+  },
+  "reassess-roadmap": {
+    allowedGsdTools: ["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_decision_save"],
+    requiredWorkflowTools: ["gsd_task_complete"],
+  },
+  "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 AUTO_UNIT_SCOPED_TOOLS: Record<string, readonly string[]> = Object.fromEntries(
+  Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]),
+);
+
+export function getUnitToolSurfaceContract(unitType: string): UnitToolSurfaceContract | undefined {
+  return UNIT_TOOL_CONTRACTS[unitType];
+}
+
+export function getRequiredWorkflowToolsForUnit(unitType: string): string[] {
+  return [...(UNIT_TOOL_CONTRACTS[unitType]?.requiredWorkflowTools ?? [])];
+}
+
+export function getForbiddenGsdToolReason(unitType: string, toolName: string): string | undefined {
+  return UNIT_TOOL_CONTRACTS[unitType]?.forbiddenGsdTools?.[toolName];
+}

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -2,7 +2,7 @@ import { execSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "./tool-presentation-plan.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 
 type WorkflowExecutorsModule = typeof import("./tools/workflow-tool-executors.js");
 
@@ -414,83 +414,11 @@ export function buildWorkflowMcpServers(
 }
 
 export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[] {
-  switch (unitType) {
-    case "discuss-project":
-      return ["ask_user_questions", "gsd_summary_save"];
-    case "discuss-requirements":
-      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
-    case "research-decision":
-      return ["ask_user_questions"];
-    case "discuss-milestone":
-      return [
-        "gsd_summary_save",
-        "gsd_requirement_save",
-        "gsd_requirement_update",
-        "gsd_plan_milestone",
-        "gsd_milestone_generate_id",
-      ];
-    case "discuss-slice":
-      return ["gsd_summary_save"];
-    case "research-milestone":
-    case "research-slice":
-      return ["gsd_summary_save"];
-    case "plan-milestone":
-      return ["gsd_plan_milestone"];
-    case "plan-slice":
-      return ["gsd_plan_slice"];
-    case "execute-task":
-      return ["gsd_task_complete"];
-    case "complete-slice":
-      return ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
-    default:
-      return [];
-  }
+  return getRequiredWorkflowToolsForUnit(unitType);
 }
 
 export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[] {
-  switch (unitType) {
-    case "discuss-project":
-      return ["ask_user_questions", "gsd_summary_save"];
-    case "discuss-requirements":
-      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
-    case "research-decision":
-      return ["ask_user_questions"];
-    case "discuss-milestone":
-      return [
-        "gsd_summary_save",
-        "gsd_requirement_save",
-        "gsd_requirement_update",
-        "gsd_plan_milestone",
-        "gsd_milestone_generate_id",
-      ];
-    case "research-milestone":
-    case "research-slice":
-      return ["gsd_summary_save"];
-    case "run-uat":
-      return [...RUN_UAT_WORKFLOW_TOOL_NAMES];
-    case "plan-milestone":
-      return ["gsd_plan_milestone"];
-    case "plan-slice":
-      return ["gsd_plan_slice"];
-    case "execute-task":
-    case "execute-task-simple":
-    case "reactive-execute":
-      return ["gsd_task_complete"];
-    case "complete-slice":
-      return ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
-    case "replan-slice":
-      return ["gsd_replan_slice"];
-    case "reassess-roadmap":
-      return ["gsd_milestone_status", "gsd_reassess_roadmap"];
-    case "gate-evaluate":
-      return ["gsd_save_gate_result"];
-    case "validate-milestone":
-      return ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"];
-    case "complete-milestone":
-      return ["gsd_milestone_status", "gsd_complete_milestone"];
-    default:
-      return [];
-  }
+  return getRequiredWorkflowToolsForUnit(unitType);
 }
 
 export function usesWorkflowMcpTransport(