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

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

@@ -0,0 +1,210 @@
+// 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_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: [
+      "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_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 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(
@@ -559,10 +487,9 @@ export function getWorkflowTransportSupportError(
   }
 
   const uniqueRequired = [...new Set(requiredTools)];
-  const piRuntimeRequired = uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
   const missing = (options.activeTools && options.activeTools.length > 0)
-    ? piRuntimeRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
-    : piRuntimeRequired;
+    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
   if (missing.length === 0) return null;
 
   if (options.activeTools && options.activeTools.length > 0) {

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -259,6 +259,38 @@ export function resolveCanonicalMilestoneRoot(
   return wtPath;
 }
 
+/**
+ * Build human-facing guidance for manually validating a milestone's work.
+ *
+ * When a milestone runs in a git worktree, its checkout lives under the hidden
+ * `.gsd/worktrees/<MID>/` path that a human can't easily discover. The UAT
+ * pause/handoff and the saved assessment use this to tell the human exactly
+ * where to `cd` to run or inspect the app before signing off on NEEDS-HUMAN
+ * checks, rather than leaving them to hunt for a buried path.
+ *
+ * Returns null when no milestone id is available.
+ */
+export function buildManualValidationGuidance(
+  basePath: string,
+  milestoneId: string,
+  opts: { uatPath?: string } = {},
+): string | null {
+  if (!milestoneId) return null;
+  const validationRoot = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const inWorktree = validationRoot.includes(`${sep}.gsd${sep}worktrees${sep}`);
+  const lines: string[] = [`Validate the work here: ${validationRoot}`];
+  if (inWorktree) {
+    lines.push(
+      "This milestone runs in a git worktree, so the code lives under the hidden " +
+        `\`.gsd/worktrees/\` path. Open it with: cd "${validationRoot}"`,
+    );
+  }
+  if (opts.uatPath) {
+    lines.push(`Follow the UAT checklist at: ${opts.uatPath}`);
+  }
+  return lines.join("\n");
+}
+
 // ─── Core Operations ───────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/worktree-reentry.ts

@@ -0,0 +1,103 @@
+// Project/App: gsd-pi
+// File Purpose: Deterministically re-enter the active milestone's worktree on a
+// cold start (after /quit + relaunch). Without this, Claude Code relaunches with
+// cwd at the project root, and a bare /gsd leaves the agent there — forcing it to
+// search the filesystem ("git worktree list", branch sniffing) to find its way
+// back into the worktree. The worktree path is fully derivable from state, so we
+// resolve and chdir into it directly instead.
+
+import { readdirSync } from "node:fs";
+
+import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
+import { getIsolationMode } from "./preferences.js";
+import { worktreesDir } from "./worktree-manager.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+
+interface LiveWorktree {
+  id: string;
+  path: string;
+}
+
+/**
+ * Enumerate the live (valid git) auto-worktrees under <projectRoot>/.gsd/worktrees/.
+ * Reuses getAutoWorktreePath's validation so stray directories are ignored.
+ */
+function liveMilestoneWorktrees(projectRoot: string): LiveWorktree[] {
+  let names: string[];
+  try {
+    names = readdirSync(worktreesDir(projectRoot));
+  } catch {
+    return [];
+  }
+  const live: LiveWorktree[] = [];
+  for (const id of names) {
+    const path = getAutoWorktreePath(projectRoot, id);
+    if (path) live.push({ id, path });
+  }
+  return live;
+}
+
+/**
+ * If we're sitting at the project root with worktree isolation enabled and the
+ * active milestone has a live worktree, chdir into it. No-op when already inside
+ * a worktree, when isolation is off, or when the target is ambiguous.
+ *
+ * Single live worktree → enter it (covers the common case without deriveState).
+ * Multiple live worktrees → disambiguate by the active milestone from state;
+ * if that can't be resolved unambiguously, do nothing.
+ *
+ * Best-effort: any failure resolves to a no-op so it can never block startup.
+ *
+ * @returns the worktree path entered, or null when nothing was done.
+ */
+export async function reenterActiveWorktreeIfNeeded(
+  basePath: string,
+  opts: { notify?: (message: string) => void } = {},
+): Promise<string | null> {
+  let projectRoot: string;
+  try {
+    projectRoot = resolveWorktreeProjectRoot(basePath);
+  } catch {
+    return null;
+  }
+
+  // Only worktree-isolation projects have worktrees to re-enter.
+  if (getIsolationMode(projectRoot) !== "worktree") return null;
+
+  // Already inside a worktree (warm session, or auto-mode already entered) —
+  // nothing to do.
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    return null;
+  }
+  if (isGsdWorktreePath(cwd)) return null;
+
+  const live = liveMilestoneWorktrees(projectRoot);
+  if (live.length === 0) return null;
+
+  let target: LiveWorktree | null = live.length === 1 ? live[0]! : null;
+  if (!target) {
+    // Multiple live worktrees — disambiguate by the active milestone.
+    try {
+      const { deriveState } = await import("./state.js");
+      const state = await deriveState(projectRoot);
+      const activeId = state.activeMilestone?.id;
+      target = activeId ? live.find((w) => w.id === activeId) ?? null : null;
+    } catch {
+      target = null;
+    }
+  }
+  if (!target) return null;
+
+  try {
+    const entered = enterAutoWorktree(projectRoot, target.id);
+    opts.notify?.(`Resumed in worktree for ${target.id}.`);
+    return entered;
+  } catch {
+    // Worktree vanished or chdir failed — leave cwd as-is, caller falls back to
+    // the project root.
+    return null;
+  }
+}

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -140,6 +140,10 @@ export function resolveGsdBrowserMcpLaunchConfig(
     : null;
   const sessionName =
     options.sessionName?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot, options.sessionSuffix);
+  // Stable per-project identity key (no per-session suffix) so the browser
+  // profile/cookies persist across pi sessions for the same project. gsd-browser
+  // rejects --identity-scope unless --identity-key is also supplied.
+  const identityKey = env.GSD_BROWSER_IDENTITY_KEY?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
   const command =
     explicitCommand
     || explicitCliPath
@@ -155,6 +159,8 @@ export function resolveGsdBrowserMcpLaunchConfig(
         sessionName,
         "--identity-scope",
         "project",
+        "--identity-key",
+        identityKey,
         "--identity-project",
         resolvedProjectRoot,
       ];