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

package/src/resources/extensions/gsd/tests/write-gate.test.ts

@@ -340,6 +340,8 @@ test('write-gate: reopening a gate revokes its previous verified approval', () =
 // ═══════════════════════════════════════════════════════════════════════
 
 import {
+  applyAskUserQuestionsGateResult,
+  formatPendingAskUserQuestionsGateMessage,
   isGateQuestionId,
   shouldBlockPendingGate,
   shouldBlockPendingGateBash,
@@ -379,6 +381,83 @@ test('write-gate: pending gate lifecycle (set, get, clear)', () => {
   assert.strictEqual(getPendingGate(), null, 'clearDiscussionFlowState clears pending gate');
 });
 
+test('write-gate: applyAskUserQuestionsGateResult keeps cancelled pending gate waiting', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-waiting-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: { cancelled: true, interrupted: true },
+    });
+
+    assert.deepEqual(result, {
+      status: 'waiting',
+      pendingGateId: gateId,
+      interrupted: true,
+    });
+    assert.strictEqual(getPendingGate(base), gateId, 'cancelled question must leave gate pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'cancelled question must not verify depth');
+    assert.match(
+      formatPendingAskUserQuestionsGateMessage(gateId, true),
+      /Re-call ask_user_questions with the same gate question id/,
+    );
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: applyAskUserQuestionsGateResult verifies confirmed pending gate', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-verified-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+  const confirmLabel = 'Confirm depth (Recommended)';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: confirmLabel }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: {
+          answers: {
+            [gateId]: { selected: confirmLabel },
+          },
+        },
+      },
+    });
+
+    assert.deepEqual(result, {
+      status: 'verified',
+      gateId,
+      milestoneId: 'M001',
+    });
+    assert.strictEqual(getPendingGate(base), null, 'confirmed gate must clear pending state');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), true, 'confirmed gate must verify milestone depth');
+    assert.ok(
+      loadWriteGateSnapshot(base).verifiedApprovalGates?.includes(gateId) ?? false,
+      'confirmed gate must record verified approval',
+    );
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ─── Scenario 21: shouldBlockPendingGate blocks non-safe tools when gate is pending ──
 
 test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate', () => {
@@ -724,3 +803,45 @@ test('write-gate: resetWriteGateState persists through dangling .gsd symlink', (
     } catch { /* swallow */ }
   }
 });
+
+// ─── Scenario 31: hydrate in-memory gate state from persisted snapshot (MCP subprocess) ──
+
+test('write-gate: getPendingGate hydrates from disk when workflow MCP verified gate in child process', () => {
+  const base = join(tmpdir(), `gsd-write-gate-mcp-hydrate-${randomUUID()}`);
+  const stateFilePath = join(base, '.gsd', 'runtime', 'write-gate-state.json');
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+  const gateId = 'depth_verification_M005_confirm';
+
+  try {
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = '1';
+    mkdirSync(join(base, '.gsd', 'runtime'), { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    writeFileSync(stateFilePath, JSON.stringify({
+      verifiedDepthMilestones: ['M005'],
+      verifiedApprovalGates: [gateId],
+      activeQueuePhase: false,
+      pendingGateId: null,
+    }, null, 2), 'utf-8');
+
+    assert.strictEqual(getPendingGate(base), null, 'stale in-memory pending must refresh from disk');
+    assert.strictEqual(isMilestoneDepthVerified('M005', base), true, 'verified milestone must hydrate from disk');
+    assert.deepEqual(loadWriteGateSnapshot(base), {
+      verifiedDepthMilestones: ['M005'],
+      verifiedApprovalGates: [gateId],
+      activeQueuePhase: false,
+      pendingGateId: null,
+    });
+  } finally {
+    if (originalEnv === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+    }
+    clearDiscussionFlowState(base);
+    try {
+      rmSync(base, { recursive: true, force: true });
+    } catch { /* swallow */ }
+  }
+});

package/src/resources/extensions/gsd/tool-contract.ts

@@ -4,8 +4,10 @@
 import {
   resolveManifest,
   type ArtifactKey,
+  type ComputedArtifactId,
   type ContextModePolicy,
   type ToolsPolicy,
+  type UnitContextManifest,
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
@@ -21,6 +23,7 @@ export interface UnitToolContract {
   requiredWorkflowTools: readonly string[];
   forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
+  promptContext: UnitPromptContextContract;
   validationRules: readonly string[];
   closeoutTools: readonly string[];
   sourceObservations: UnitSourceObservationContract;
@@ -31,6 +34,22 @@ export interface UnitToolContract {
   };
 }
 
+export interface UnitPromptContextContract {
+  unitType: string;
+  contextMode: ContextModePolicy;
+  toolsPolicy: ToolsPolicy;
+  obligations: readonly string[];
+  sourceObservations: UnitSourceObservationContract;
+  artifacts: {
+    inline: readonly ArtifactKey[];
+    excerpt: readonly ArtifactKey[];
+    onDemand: readonly ArtifactKey[];
+    computed: readonly ComputedArtifactId[];
+    prepend: readonly ComputedArtifactId[];
+  };
+  maxSystemPromptChars: number;
+}
+
 export type UnitSourceObservationContract =
   | { mode: "none" }
   | {
@@ -45,6 +64,22 @@ export type ToolContractResult =
   | { ok: true; contract: UnitToolContract }
   | { ok: false; reason: "unknown-unit-type" | "missing-closeout-tool"; detail: string };
 
+export type UnitContextContractResult =
+  | { ok: true; contract: UnitPromptContextContract }
+  | { ok: false; reason: "unknown-unit-type"; detail: string };
+
+export function compileUnitContextContract(unitType: string): UnitContextContractResult {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) {
+    return {
+      ok: false,
+      reason: "unknown-unit-type",
+      detail: `No Unit manifest is registered for ${unitType}`,
+    };
+  }
+  return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
+}
+
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
   const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -71,6 +106,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
+  const promptContext = buildPromptContextContract(unitType, manifest);
+
   return {
     ok: true,
     contract: {
@@ -79,10 +116,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
       forbiddenWorkflowTools,
-      promptObligations: [
-        `context-mode:${manifest.contextMode}`,
-        `tools-policy:${manifest.tools.mode}`,
-      ],
+      promptObligations: promptContext.obligations,
+      promptContext,
       validationRules: [
         "unit-manifest-present",
         "workflow-tool-surface-present",
@@ -90,16 +125,59 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
         ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
       ],
       closeoutTools,
-      sourceObservations: sourceObservationContractForUnit(unitType),
+      sourceObservations: promptContext.sourceObservations,
       artifacts: {
-        inline: manifest.artifacts.inline,
-        excerpt: manifest.artifacts.excerpt,
-        onDemand: manifest.artifacts.onDemand,
+        inline: promptContext.artifacts.inline,
+        excerpt: promptContext.artifacts.excerpt,
+        onDemand: promptContext.artifacts.onDemand,
       },
     },
   };
 }
 
+function buildPromptContextContract(
+  unitType: string,
+  manifest: UnitContextManifest,
+): UnitPromptContextContract {
+  const sourceObservations = sourceObservationContractForUnit(unitType);
+  return {
+    unitType,
+    contextMode: manifest.contextMode,
+    toolsPolicy: manifest.tools,
+    obligations: promptContextObligations(manifest, sourceObservations),
+    sourceObservations,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+    maxSystemPromptChars: manifest.maxSystemPromptChars,
+  };
+}
+
+function promptContextObligations(
+  manifest: UnitContextManifest,
+  sourceObservations: UnitSourceObservationContract,
+): string[] {
+  const obligations = [
+    `context-mode:${manifest.contextMode}`,
+    `tools-policy:${manifest.tools.mode}`,
+    artifactObligation("context-inline", manifest.artifacts.inline),
+    artifactObligation("context-excerpt", manifest.artifacts.excerpt),
+    artifactObligation("context-on-demand", manifest.artifacts.onDemand),
+  ];
+  if (sourceObservations.mode !== "none") {
+    obligations.push(`source-observations:${sourceObservations.mode}`);
+  }
+  return obligations;
+}
+
+function artifactObligation(label: string, artifacts: readonly ArtifactKey[]): string {
+  return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
+
 function sourceObservationContractForUnit(unitType: string): UnitSourceObservationContract {
   if (unitType !== "execute-task") return { mode: "none" };
   return {

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

@@ -7,7 +7,10 @@ import {
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -33,6 +36,7 @@ export interface ToolPresentationPlan {
   blockedToolNames: Array<{ name: string; reason: string }>;
   aliases: Array<{ requested: string; canonical: string }>;
   diagnostics: string[];
+  toolSurface: ToolSurfaceSnapshot;
 }
 
 export interface RunUatResultPresentation {
@@ -62,44 +66,14 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "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;
+  return canonicalWorkflowSurfaceToolName(toolName);
 }
 
-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 { parseMcpToolName } from "./mcp-tool-name.js";
 
 export function toWorkflowMcpToolName(serverName: string, toolName: string): string {
-  return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+  return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 
 function dedupe(values: readonly string[]): string[] {
@@ -212,6 +186,14 @@ export function resolveToolPresentationPlan(options: {
           : name
       )
     : allowedToolNames;
+  const toolSurface = createToolSurfaceSnapshot({
+    source: "presentation-plan",
+    phase: options.phase,
+    modelFacingToolNames: options.availableToolNames ?? requested,
+    registeredToolNames: options.availableToolNames ?? requested,
+    scopedToolNames: allowedToolNames,
+    presentedToolNames,
+  });
 
   if (options.phase === "run-uat") {
     for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
@@ -228,5 +210,6 @@ export function resolveToolPresentationPlan(options: {
     blockedToolNames,
     aliases,
     diagnostics: [],
+    toolSurface,
   };
 }

package/src/resources/extensions/gsd/tool-surface-snapshot.ts

@@ -0,0 +1,47 @@
+// Project/App: gsd-pi
+// File Purpose: Typed snapshots for model-facing, registered, scoped, and presented tool surfaces.
+
+export type ToolSurfaceSnapshotSource =
+  | "runtime-scope"
+  | "dispatch-scope"
+  | "provider-adjustment"
+  | "presentation-plan";
+
+export interface ToolSurfaceSnapshot {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames: string[];
+  registeredToolNames: string[];
+  scopedToolNames: string[];
+  presentedToolNames: string[];
+  capturedAt: number;
+}
+
+export interface ToolSurfaceSnapshotInput {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames?: readonly string[];
+  registeredToolNames?: readonly string[];
+  scopedToolNames?: readonly string[];
+  presentedToolNames?: readonly string[];
+  capturedAt?: number;
+}
+
+function dedupeToolNames(toolNames: readonly string[] | undefined): string[] {
+  return [...new Set(toolNames ?? [])];
+}
+
+export function createToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  return {
+    source: input.source,
+    unitType: input.unitType,
+    phase: input.phase,
+    modelFacingToolNames: dedupeToolNames(input.modelFacingToolNames),
+    registeredToolNames: dedupeToolNames(input.registeredToolNames),
+    scopedToolNames: dedupeToolNames(input.scopedToolNames),
+    presentedToolNames: dedupeToolNames(input.presentedToolNames),
+    capturedAt: input.capturedAt ?? Date.now(),
+  };
+}

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

@@ -15,20 +15,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteSliceParams } from "../types.js";
-import { isClosedStatus } from "../status-guards.js";
 import {
-  transaction,
-  insertMilestone,
-  insertSlice,
-  getSlice,
-  getSliceTasks,
-  getMilestone,
-  updateSliceStatus,
+  completeSliceCascade,
   setSliceSummaryMd,
   saveGateResult,
   getPendingGatesForTurn,
-  getMilestoneSlices,
-  updateMilestoneStatus,
 } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
@@ -371,60 +362,34 @@ export async function handleCompleteSlice(
     };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+  // ── Atomic completion cascade (guards + writes in one transaction) ───────
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
   let existingSummaryMd = "";
   let duplicateComplete = false;
 
-  transaction(() => {
-    // State machine preconditions (inside txn for atomicity).
-    // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
-    // Only block if they exist and are closed.
-    const milestone = getMilestone(params.milestoneId);
-    if (milestone && isClosedStatus(milestone.status)) {
-      guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
-      return;
-    }
-
-    const slice = getSlice(params.milestoneId, params.sliceId);
-    existingSummaryMd = slice?.full_summary_md?.trim() ?? "";
-    if (slice && isClosedStatus(slice.status)) {
-      duplicateComplete = true;
-      return;
-    }
-
-    // Verify all tasks are complete
-    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-    if (tasks.length === 0) {
-      guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
-      return;
-    }
-
-    const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
-    if (incompleteTasks.length > 0) {
-      const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
-      guardError = `incomplete tasks: ${incompleteIds}`;
-      return;
-    }
-
-    // All guards passed — perform writes. Preserve existing planning metadata:
-    // completion should not overwrite title/risk/depends/demo/sequence.
-    insertMilestone({ id: params.milestoneId, title: params.milestoneId });
-    if (!slice) {
-      insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceTitle || params.sliceId });
-    }
-    updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
-
-    const updatedSlices = getMilestoneSlices(params.milestoneId);
-    if (
-      milestone?.status === "planned" &&
-      updatedSlices.length > 0 &&
-      updatedSlices.every((s) => isClosedStatus(s.status))
-    ) {
-      updateMilestoneStatus(params.milestoneId, "active");
-    }
+  const outcome = completeSliceCascade(params.milestoneId, params.sliceId, {
+    sliceTitle: params.sliceTitle,
+    completedAt,
   });
+  if (outcome.ok) {
+    existingSummaryMd = outcome.existingSummaryMd;
+    duplicateComplete = outcome.duplicate;
+  } else {
+    switch (outcome.reason) {
+      case "milestone-closed":
+        guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${outcome.status})`;
+        break;
+      case "no-tasks":
+        guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
+        break;
+      case "incomplete-tasks": {
+        const incompleteIds = outcome.incomplete.map((t) => `${t.id} (status: ${t.status})`).join(", ");
+        guardError = `incomplete tasks: ${incompleteIds}`;
+        break;
+      }
+    }
+  }
 
   if (duplicateComplete) {
     const staleSummaryPath = sliceSummaryPath(

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

@@ -11,6 +11,7 @@ import {
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+import { findWorktreeSegment } from "../worktree-root.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -201,11 +202,10 @@ function normalizeScanPath(value: string): string {
 
 function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
   const normalizedBase = normalizeScanPath(baseDir);
-  const marker = "/.gsd/worktrees/";
-  const markerIndex = normalizedBase.indexOf(marker);
-  if (markerIndex <= 0) return null;
+  const segment = findWorktreeSegment(normalizedBase);
+  if (!segment || segment.gsdIdx <= 0) return null;
   return {
-    originalRoot: normalizedBase.slice(0, markerIndex),
+    originalRoot: normalizedBase.slice(0, segment.gsdIdx),
     worktreeRoot: normalizedBase,
   };
 }
@@ -297,7 +297,7 @@ function scriptReferencesOriginalRootFromWorktree(script: string, baseDir: strin
   const normalizedScript = script.replace(/\\/g, "/");
   return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
     const originalRootPattern = new RegExp(
-      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd/worktrees(?:/|$)))`,
+      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd(?:-worktrees|/worktrees)(?:/|$)))`,
     );
     return originalRootPattern.test(normalizedScript);
   });