@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.74e8dd1

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

@@ -0,0 +1,167 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
+
+export type ToolPresentationSurface = "provider-tools" | "claude-code-sdk" | "mcp" | "hybrid";
+
+export interface ToolPresentationModel {
+  provider?: string;
+  api?: string;
+  id?: string;
+}
+
+export interface ToolPresentationPlan {
+  phase: string;
+  surface: ToolPresentationSurface;
+  model?: ToolPresentationModel;
+  allowedToolNames: string[];
+  presentedToolNames: string[];
+  blockedToolNames: Array<{ name: string; reason: string }>;
+  aliases: Array<{ requested: string; canonical: string }>;
+  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",
+  "gsd_exec",
+  "gsd_summary_save",
+  "gsd_save_gate_result",
+  "search-the-web",
+  "WebSearch",
+  "Bash",
+  "Write",
+  "Edit",
+  "mcp__gsd-workflow__*",
+] as const;
+
+export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
+  "Read",
+  "Glob",
+  "Grep",
+] as const;
+
+const WORKFLOW_ALIAS_TO_CANONICAL: Record<string, string> = {
+  gsd_save_decision: "gsd_decision_save",
+  gsd_update_requirement: "gsd_requirement_update",
+  gsd_save_requirement: "gsd_requirement_save",
+  gsd_save_summary: "gsd_summary_save",
+  gsd_generate_milestone_id: "gsd_milestone_generate_id",
+  gsd_milestone_plan: "gsd_plan_milestone",
+  gsd_slice_plan: "gsd_plan_slice",
+  gsd_task_plan: "gsd_plan_task",
+  gsd_slice_replan: "gsd_replan_slice",
+  gsd_complete_slice: "gsd_slice_complete",
+  gsd_milestone_complete: "gsd_complete_milestone",
+  gsd_milestone_validate: "gsd_validate_milestone",
+  gsd_roadmap_reassess: "gsd_reassess_roadmap",
+  gsd_complete_task: "gsd_task_complete",
+  gsd_reopen_task: "gsd_task_reopen",
+  gsd_reopen_slice: "gsd_slice_reopen",
+  gsd_reopen_milestone: "gsd_milestone_reopen",
+};
+
+export function canonicalWorkflowToolName(toolName: string): string {
+  const mcp = parseMcpToolName(toolName);
+  const baseName = mcp?.tool ?? toolName;
+  return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+}
+
+export function parseMcpToolName(toolName: string): { server: string; tool: string } | null {
+  if (!toolName.startsWith("mcp__")) return null;
+  const toolSeparator = toolName.indexOf("__", "mcp__".length);
+  if (toolSeparator < 0) return null;
+  return {
+    server: toolName.slice("mcp__".length, toolSeparator),
+    tool: toolName.slice(toolSeparator + 2),
+  };
+}
+
+export function toWorkflowMcpToolName(serverName: string, toolName: string): string {
+  return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+}
+
+function dedupe(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
+
+function addBlockedTool(
+  blocked: ToolPresentationPlan["blockedToolNames"],
+  name: string,
+  reason: string,
+): void {
+  if (!blocked.some((entry) => entry.name === name)) {
+    blocked.push({ name, reason });
+  }
+}
+
+export function buildRunUatCanonicalToolNames(options: { includeBrowserTools?: readonly string[] } = {}): string[] {
+  return dedupe([
+    ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+    ...(options.includeBrowserTools ?? []),
+  ]);
+}
+
+export function resolveToolPresentationPlan(options: {
+  phase: string;
+  surface: ToolPresentationSurface;
+  model?: ToolPresentationModel;
+  workflowMcpServerName?: string | null;
+  requestedToolNames?: readonly string[];
+  availableToolNames?: readonly string[];
+  includeBrowserTools?: readonly string[];
+}): ToolPresentationPlan {
+  const requested = options.requestedToolNames ?? (
+    options.phase === "run-uat"
+      ? buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools })
+      : []
+  );
+  const available = new Set(options.availableToolNames ?? requested);
+  const aliases: ToolPresentationPlan["aliases"] = [];
+  const blockedToolNames: ToolPresentationPlan["blockedToolNames"] = [];
+  const allowed: string[] = [];
+
+  for (const name of requested) {
+    const canonical = canonicalWorkflowToolName(name);
+    if (canonical !== name) aliases.push({ requested: name, canonical });
+    if (!available.has(name) && !available.has(canonical)) {
+      addBlockedTool(blockedToolNames, canonical, "not registered or provider-incompatible");
+      continue;
+    }
+    allowed.push(canonical);
+  }
+
+  const allowedToolNames = dedupe(allowed);
+  const workflowServerName = options.workflowMcpServerName || "gsd-workflow";
+  const presentedToolNames = options.surface === "claude-code-sdk" || options.surface === "mcp"
+    ? allowedToolNames.map((name) =>
+        name.startsWith("gsd_") || name === "ask_user_questions"
+          ? toWorkflowMcpToolName(workflowServerName, name)
+          : name
+      )
+    : allowedToolNames;
+
+  if (options.phase === "run-uat") {
+    for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
+      addBlockedTool(blockedToolNames, forbidden, "forbidden during run-uat");
+    }
+  }
+
+  return {
+    phase: options.phase,
+    surface: options.surface,
+    model: options.model,
+    allowedToolNames,
+    presentedToolNames,
+    blockedToolNames,
+    aliases,
+    diagnostics: [],
+  };
+}

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -20,6 +20,7 @@ export interface ExecToolParams {
   cmd?: unknown;
   code?: unknown;
   purpose?: string;
+  metadata?: Record<string, unknown>;
   timeout_ms?: number;
 }
 
@@ -33,6 +34,44 @@ export interface ExecToolDeps {
   generateId?: () => string;
 }
 
+export type UatExecIntent =
+  | "uat-artifact-check"
+  | "uat-runtime-check"
+  | "uat-browser-check"
+  | "uat-service-start"
+  | "uat-log-inspection";
+
+export interface UatExecToolParams extends ExecToolParams {
+  milestoneId?: unknown;
+  sliceId?: unknown;
+  checkId?: unknown;
+  intent?: unknown;
+  expected?: unknown;
+}
+
+const UAT_EXEC_INTENTS: readonly UatExecIntent[] = [
+  "uat-artifact-check",
+  "uat-runtime-check",
+  "uat-browser-check",
+  "uat-service-start",
+  "uat-log-inspection",
+] as const;
+
+const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
+  artifact: "uat-artifact-check",
+  "artifact-driven": "uat-artifact-check",
+  runtime: "uat-runtime-check",
+  "runtime-executable": "uat-runtime-check",
+  "live-runtime": "uat-runtime-check",
+  browser: "uat-browser-check",
+  "browser-executable": "uat-browser-check",
+  service: "uat-service-start",
+  "service-start": "uat-service-start",
+  log: "uat-log-inspection",
+  logs: "uat-log-inspection",
+  "log-inspection": "uat-log-inspection",
+};
+
 export function buildExecOptions(
   baseDir: string,
   cfg: ContextModeConfig | undefined,
@@ -112,6 +151,39 @@ function normalizeScript(params: ExecToolParams): string | ToolExecutionResult {
   return paramError("script is required and must be a non-empty string");
 }
 
+function normalizeRequiredString(value: unknown, field: string): string | ToolExecutionResult {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return paramError(`${field} is required and must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function normalizeUatIntent(value: unknown): UatExecIntent | ToolExecutionResult {
+  if (typeof value !== "string") {
+    return paramError(`intent is required and must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+  }
+  const normalized = value.trim().toLowerCase();
+  if ((UAT_EXEC_INTENTS as readonly string[]).includes(normalized)) return normalized as UatExecIntent;
+  const alias = UAT_EXEC_INTENT_ALIASES[normalized];
+  if (alias) return alias;
+  return paramError(`invalid intent "${value}" — must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+}
+
+function rejectUatScript(script: string): string | null {
+  const patterns: Array<{ re: RegExp; reason: string }> = [
+    { re: /\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|remove|update|upgrade)\b/i, reason: "package dependency mutation is not allowed during UAT" },
+    { re: /\b(?:pip|pip3|python\s+-m\s+pip)\s+install\b/i, reason: "package dependency mutation is not allowed during UAT" },
+    { re: /\bgit\s+(?:add|commit|push|reset|checkout|switch|merge|rebase|clean|rm|mv|tag|branch)\b/i, reason: "git mutations are not allowed during UAT" },
+    { re: /\brm\s+-[^\n\r;|&]*r[^\n\r;|&]*f\b/i, reason: "destructive filesystem cleanup is not allowed during UAT" },
+    { re: /\b(?:env|printenv)\b(?:\s|$)/i, reason: "dumping environment variables is not allowed during UAT" },
+    { re: /\bcat\s+\.env(?:\b|\.|$)/i, reason: "reading credential files is not allowed during UAT" },
+  ];
+  for (const pattern of patterns) {
+    if (pattern.re.test(script)) return pattern.reason;
+  }
+  return null;
+}
+
 function isToolExecutionResult(value: unknown): value is ToolExecutionResult {
   return typeof value === "object" && value !== null && Array.isArray((value as { content?: unknown }).content);
 }
@@ -266,6 +338,7 @@ export async function executeGsdExec(
         runtime,
         script,
         ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+        ...(params.metadata && typeof params.metadata === "object" ? { metadata: params.metadata } : {}),
         ...(typeof params.timeout_ms === "number" ? { timeout_ms: params.timeout_ms } : {}),
       },
       opts,
@@ -281,6 +354,63 @@ export async function executeGsdExec(
   }
 }
 
+export async function executeUatExec(
+  params: UatExecToolParams,
+  deps: ExecToolDeps,
+): Promise<ToolExecutionResult> {
+  const milestoneId = normalizeRequiredString(params.milestoneId, "milestoneId");
+  if (isToolExecutionResult(milestoneId)) return milestoneId;
+  const sliceId = normalizeRequiredString(params.sliceId, "sliceId");
+  if (isToolExecutionResult(sliceId)) return sliceId;
+  const checkId = normalizeRequiredString(params.checkId, "checkId");
+  if (isToolExecutionResult(checkId)) return checkId;
+  const intent = normalizeUatIntent(params.intent);
+  if (isToolExecutionResult(intent)) return intent;
+  const script = normalizeScript(params);
+  if (isToolExecutionResult(script)) return script;
+  const rejected = rejectUatScript(script);
+  if (rejected) {
+    return {
+      content: [{ type: "text", text: `Error: gsd_uat_exec blocked command — ${rejected}` }],
+      details: { operation: "gsd_uat_exec", error: "uat_exec_policy_block", reason: rejected },
+      isError: true,
+    };
+  }
+
+  const result = await executeGsdExec(
+    {
+      ...params,
+      script,
+      purpose: typeof params.purpose === "string" && params.purpose.trim().length > 0
+        ? params.purpose
+        : `UAT ${milestoneId}/${sliceId}/${checkId} (${intent})`,
+      metadata: {
+        kind: "uat_exec",
+        milestoneId,
+        sliceId,
+        checkId,
+        intent,
+        ...(typeof params.expected === "string" && params.expected.trim().length > 0
+          ? { expected: params.expected.trim() }
+          : {}),
+      },
+    },
+    deps,
+  );
+  const details = result.details ?? {};
+  return {
+    ...result,
+    details: {
+      ...details,
+      operation: "gsd_uat_exec",
+      milestoneId,
+      sliceId,
+      checkId,
+      intent,
+    },
+  };
+}
+
 function formatResult(result: ExecSandboxResult): ToolExecutionResult {
   const headerLines = [
     `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -355,15 +355,9 @@ export async function handlePlanSlice(
         deleteTask(params.milestoneId, params.sliceId, taskId);
       }
 
+      const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
       for (const task of params.tasks) {
-        insertTask({
-          id: task.taskId,
-          sliceId: params.sliceId,
-          milestoneId: params.milestoneId,
-          title: task.title,
-          status: "pending",
-        });
-        upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, {
+        const planning = {
           title: task.title,
           description: task.description,
           estimate: task.estimate,
@@ -374,7 +368,18 @@ export async function handlePlanSlice(
           observabilityImpact: task.observabilityImpact ?? "",
           fullPlanMd: task.fullPlanMd,
           targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
-        });
+        };
+        const existingTask = existingTaskById.get(task.taskId);
+        if (!existingTask || !isClosedStatus(existingTask.status)) {
+          insertTask({
+            id: task.taskId,
+            sliceId: params.sliceId,
+            milestoneId: params.milestoneId,
+            title: task.title,
+            status: "pending",
+          });
+        }
+        upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
       }
 
       // Seed quality gate rows inside the transaction — all-or-nothing with

package/src/resources/extensions/gsd/tools/reopen-milestone.ts

@@ -13,7 +13,7 @@ import {
   getMilestone,
   getMilestoneSlices,
   getSliceTasks,
-  updateMilestoneStatus,
+  reopenMilestoneStatus,
   updateSliceStatus,
   updateTaskStatus,
   transaction,
@@ -69,7 +69,7 @@ export async function handleReopenMilestone(
       return;
     }
 
-    updateMilestoneStatus(params.milestoneId, "active", null);
+    reopenMilestoneStatus(params.milestoneId);
 
     const slices = getMilestoneSlices(params.milestoneId);
     slicesResetCount = slices.length;