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

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/complete-slice.ts

@@ -217,7 +217,7 @@ ${params.narrative}
 
 ## Verification
 
-${params.verification}
+${params.verification ?? ""}
 
 ## Requirements Advanced
 
@@ -440,6 +440,19 @@ export async function handleCompleteSlice(
       const parsed = parseRequirementSection(existingSummaryMd, "Requirements Invalidated or Re-scoped", "what");
       if (parsed.length > 0) effectiveParams.requirementsInvalidated = parsed as Array<{ id: string; what: string }>;
     }
+    if (effectiveParams.verification === undefined) {
+      const headingLine = "## Verification\n\n";
+      const start = existingSummaryMd.indexOf(headingLine);
+      if (start !== -1) {
+        const contentStart = start + headingLine.length;
+        const nextHeading = existingSummaryMd.indexOf("\n\n## ", contentStart);
+        const prior = nextHeading === -1
+          ? existingSummaryMd.slice(contentStart)
+          : existingSummaryMd.slice(contentStart, nextHeading);
+        const trimmed = prior.trim();
+        if (trimmed) effectiveParams.verification = trimmed;
+      }
+    }
   }
 
   // Render summary markdown

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 
-import type { CompleteTaskParams } from "../types.js";
+import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
 import { isClosedStatus } from "../status-guards.js";
 import {
   transaction,
@@ -48,6 +48,14 @@ export interface CompleteTaskResult {
   sliceId: string;
   milestoneId: string;
   summaryPath: string;
+  escalation?: {
+    artifactPath: string;
+    question: string;
+    options: EscalationArtifact["options"];
+    recommendation: string;
+    recommendationRationale: string;
+    continueWithDefault: boolean;
+  };
   /**
    * True when this call re-completed an already-closed task from a turn that
    * had been superseded by timeout recovery or cancellation. The underlying
@@ -407,9 +415,18 @@ export async function handleCompleteTask(
   // overwrite it; gate rows are UPSERT-keyed per task and will also be
   // overwritten. This restores the invariant that deriveState() sees a
   // consistent "task not done" view so the loop re-dispatches the task.
+  let escalationMetadata: CompleteTaskResult["escalation"] | undefined;
   if (validatedEscalationArtifact) {
     try {
-      writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+      const escalationPath = writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+      escalationMetadata = {
+        artifactPath: escalationPath,
+        question: validatedEscalationArtifact.question,
+        options: validatedEscalationArtifact.options,
+        recommendation: validatedEscalationArtifact.recommendation,
+        recommendationRationale: validatedEscalationArtifact.recommendationRationale,
+        continueWithDefault: validatedEscalationArtifact.continueWithDefault,
+      };
     } catch (escalationErr) {
       const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(escalationErr as Error).message}`;
       logWarning("tool", msg);
@@ -477,6 +494,7 @@ export async function handleCompleteTask(
     sliceId: params.sliceId,
     milestoneId: params.milestoneId,
     summaryPath,
+    ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
     ...(projectionStale ? { stale: true } : {}),
   };
 }

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;

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

@@ -78,18 +78,10 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-async function collectPersistedBrowserEvidence(basePath: string, milestoneId: string): Promise<string> {
-  const chunks: string[] = [];
-  for (const slice of getMilestoneSlices(milestoneId)) {
-    const artifactPath = `milestones/${milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-
-    const assessmentPath = resolveSliceFile(basePath, milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-  }
-  return chunks.join("\n\n");
+function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
+  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
+  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
+  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
 }
 
 async function browserEvidenceGateRequiresAttention(
@@ -114,7 +106,38 @@ async function browserEvidenceGateRequiresAttention(
   ]);
   if (!hasBrowserRequiredText(requirementText)) return false;
 
-  const persistedEvidence = await collectPersistedBrowserEvidence(basePath, params.milestoneId);
+  // Collect per-slice evidence so the runtime bypass is checked independently
+  // for each slice. Concatenating all slices before checking would allow runtime
+  // evidence from one slice to cover another slice's browser requirements.
+  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
+  for (const slice of slices) {
+    const chunks: string[] = [];
+    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+    const artifact = getArtifact(artifactPath);
+    if (artifact?.full_content) chunks.push(artifact.full_content);
+    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+    if (assessmentContent) chunks.push(assessmentContent);
+    sliceEvidencePairs.push({
+      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+      evidenceText: chunks.join("\n\n"),
+    });
+  }
+  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
+
+  // Runtime bypass: each slice whose own requirement text has browser-observable
+  // criteria must have its own runtime-executable UAT evidence. When no individual
+  // slice has slice-level browser requirements (e.g., they come from milestone-level
+  // fields only), fall back to checking whether any slice has runtime evidence.
+  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
+    hasBrowserRequiredText(s.sliceRequirementText),
+  );
+  const runtimeBypasses =
+    browserRequiringSlices.length > 0
+      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
+      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
+  if (runtimeBypasses) return false;
+
   const validationEvidence = compactTextParts([
     params.successCriteriaChecklist,
     params.verificationClasses,
@@ -184,14 +207,22 @@ export async function handleValidateMilestone(
   const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
   if (requiredClasses.length > 0) {
     const verificationClasses = params.verificationClasses ?? "";
-    const missingClass = requiredClasses.find(
+    const missingClasses = requiredClasses.filter(
       (className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses),
     );
-    if (missingClass) {
+    if (missingClasses.length === 1) {
+      const missingClass = missingClasses[0];
       return {
         error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
       };
     }
+    if (missingClasses.length > 1) {
+      const quotedClasses = missingClasses.map((className) => `"${className}"`).join(", ");
+      const plannedClasses = missingClasses.map((className) => className.toLowerCase()).join(", ");
+      return {
+        error: `verificationClasses must include canonical rows ${quotedClasses} because this milestone planned ${plannedClasses} verification`,
+      };
+    }
   }
 
   const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);