@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,14 +1,18 @@
 // gsd-pi - Write gate runtime persistence and policy guards.
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
 import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
+import { loadJsonFileOrNull } from "../json-persistence.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { worktreesDirs } from "../worktree-placement.js";
+import { evaluateGateAnswer } from "../consent-verdict.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -122,17 +126,20 @@ const GATE_SAFE_TOOLS = new Set([
   "ask_user_questions",
 ]);
 
-export function canonicalToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
+/**
+ * Which process wrote a snapshot. Two processes share the snapshot file:
+ * the extension host ("host") and the workflow MCP child ("child"), which
+ * dynamically imports this same compiled module in its own process.
+ */
+export type WriteGateWriter = "host" | "child";
 
 export interface WriteGateSnapshot {
   verifiedDepthMilestones: string[];
   verifiedApprovalGates?: string[];
   activeQueuePhase: boolean;
   pendingGateId: string | null;
+  /** Tag of the process that produced this snapshot (diagnostic only). */
+  writer?: WriteGateWriter;
 }
 
 /**
@@ -176,12 +183,11 @@ function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSn
   };
 }
 
-function persistWriteGateSnapshot(basePath: string): void {
-  if (!shouldPersistWriteGateSnapshot()) return;
+function writeSnapshotFileAtomic(basePath: string, snapshot: WriteGateSnapshot): void {
   const path = writeGateSnapshotPath(basePath);
   ensureWriteGateSnapshotDirectory(basePath);
   const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(basePath), null, 2), "utf-8");
+  writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf-8");
   try {
     renameSync(tempPath, path);
   } catch (err: unknown) {
@@ -196,6 +202,18 @@ function persistWriteGateSnapshot(basePath: string): void {
   }
 }
 
+/**
+ * Persist the current in-memory state for `basePath`, stamped with the
+ * writer provenance tag. Callers (mutateWriteGateState / childMutate) are
+ * responsible for first reconciling in-memory content against the disk
+ * snapshot — the read-merge-write sequence is synchronous, so a concurrent
+ * writer's update is folded in by that unconditional pre-persist read.
+ */
+function persistWriteGateSnapshot(basePath: string, writer: WriteGateWriter): void {
+  if (!shouldPersistWriteGateSnapshot()) return;
+  writeSnapshotFileAtomic(basePath, { ...currentWriteGateSnapshot(basePath), writer });
+}
+
 function clearPersistedWriteGateSnapshot(basePath: string): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
@@ -219,6 +237,7 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
     verifiedApprovalGates: [...new Set(verifiedGates)].sort(),
     activeQueuePhase: record.activeQueuePhase === true,
     pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
+    ...(record.writer === "host" || record.writer === "child" ? { writer: record.writer } : {}),
   };
 }
 
@@ -229,6 +248,18 @@ const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   pendingGateId: null,
 };
 
+/**
+ * Read the snapshot file as it exists on disk. Returns null when the file
+ * is missing or unparseable (no in-memory fallback — callers decide).
+ */
+function readDiskSnapshot(basePath: string): WriteGateSnapshot | null {
+  const raw = loadJsonFileOrNull(
+    writeGateSnapshotPath(basePath),
+    (data): data is Record<string, unknown> => typeof data === "object" && data !== null,
+  );
+  return raw === null ? null : normalizeWriteGateSnapshot(raw);
+}
+
 export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
   if (!existsSync(path)) {
@@ -238,13 +269,118 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
     if (shouldPersistWriteGateSnapshot()) return EMPTY_SNAPSHOT;
     return currentWriteGateSnapshot(basePath);
   }
-  try {
-    return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
-  } catch {
-    return currentWriteGateSnapshot(basePath);
+  const disk = readDiskSnapshot(basePath);
+  return disk ?? currentWriteGateSnapshot(basePath);
+}
+
+/**
+ * Reconcile a disk snapshot into the in-memory state. This is THE merge
+ * rule for the two-process seam:
+ *
+ *   - verifications are a grow-only union: a milestone/gate verified by
+ *     either process is never lost to a stale write from the other;
+ *   - activeQueuePhase and pendingGateId take the disk value (last writer
+ *     wins — matches the long-standing refresh semantics, and keeps
+ *     "delete the snapshot file to clear the HARD BLOCK" working);
+ *   - verified wins over pending: if the merged verified sets already cover
+ *     the pending gate (gate id verified, or its depth milestone verified),
+ *     the pending re-arm is dropped. This generalizes the ad-hoc re-arm
+ *     guard that previously protected only the tool_execution_start window.
+ */
+function mergeSnapshotIntoState(state: InMemoryWriteGateState, disk: WriteGateSnapshot): void {
+  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(milestone);
+  for (const gate of disk.verifiedApprovalGates ?? []) state.verifiedApprovalGates.add(gate);
+  state.activeQueuePhase = disk.activeQueuePhase;
+  state.pendingGateId = disk.pendingGateId;
+  dropVerifiedPendingGate(state);
+}
+
+/** Verified-on-disk wins over a pending re-arm (see mergeSnapshotIntoState). */
+function dropVerifiedPendingGate(state: InMemoryWriteGateState): void {
+  const pending = state.pendingGateId;
+  if (!pending) return;
+  const milestoneId = extractDepthVerificationMilestoneId(pending);
+  if (
+    state.verifiedApprovalGates.has(pending) ||
+    (milestoneId !== null && state.verifiedDepthMilestones.has(milestoneId))
+  ) {
+    state.pendingGateId = null;
   }
 }
 
+function replaceStateFromSnapshot(state: InMemoryWriteGateState, snapshot: WriteGateSnapshot): void {
+  state.pendingGateId = snapshot.pendingGateId;
+  state.activeQueuePhase = snapshot.activeQueuePhase;
+  state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+  state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+}
+
+/**
+ * Reconcile the persisted write-gate snapshot into the in-process Map entry.
+ * The workflow MCP server runs in a child process and records depth
+ * verification there; without this refresh the extension host keeps stale
+ * pending-gate memory and `activateDeferredApprovalGate` can re-arm a gate
+ * that the subprocess already cleared on disk.
+ *
+ * Uses the union merge rule (mergeSnapshotIntoState) when a readable
+ * snapshot file exists; a missing or unparseable file is a full reset
+ * (replace with empty) so deleting the file still clears all gate state,
+ * and a corrupt file does not leave stale `pendingGateId` in memory for
+ * the next mutation to persist back.
+ *
+ * Returns the reconciled snapshot so callers that need to inspect it
+ * (e.g. re-arm guards) avoid a second disk read.
+ */
+export function refreshWriteGateStateFromDisk(basePath: string): WriteGateSnapshot {
+  if (!shouldPersistWriteGateSnapshot()) return currentWriteGateSnapshot(basePath);
+  const state = getWriteGateState(basePath);
+  const disk = readDiskSnapshot(basePath);
+  if (disk) {
+    mergeSnapshotIntoState(state, disk);
+  } else {
+    replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+  }
+  return currentWriteGateSnapshot(basePath);
+}
+
+/**
+ * Read-modify-write primitive for gate mutations. Reconciles the disk
+ * snapshot into memory (union merge), applies the mutation on top, then
+ * persists. The whole sequence is synchronous, so the reconcile read
+ * doubles as the pre-persist merge of concurrent writes — there is no
+ * version field; the read-merge-write is simply unconditional.
+ *
+ * The mutate callback sees the already-reconciled state, so policy checks
+ * (e.g. host setPending's verified-on-disk-wins guard) can live inside it
+ * without a second disk read. Returning `false` from the callback aborts:
+ * nothing is persisted and this function returns false.
+ *
+ * `reconcile: false` skips the disk merge — used for intentional full
+ * resets where re-unioning disk verifications would defeat the reset.
+ */
+function mutateWriteGateState(
+  basePath: string,
+  mutate: (state: InMemoryWriteGateState) => void | false,
+  opts?: { writer?: WriteGateWriter; reconcile?: boolean },
+): boolean {
+  const state = getWriteGateState(basePath);
+  if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
+    const disk = readDiskSnapshot(basePath);
+    if (disk) {
+      mergeSnapshotIntoState(state, disk);
+    } else {
+      // Missing OR unparseable on disk: treat as a full reset. Keeping
+      // stale in-memory state across a corrupt snapshot would persist it
+      // back on this very mutation and defeat the documented
+      // "delete the file to clear the HARD BLOCK gate" escape hatch.
+      replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+    }
+  }
+  if (mutate(state) === false) return false;
+  persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
+  return true;
+}
+
 export function isDepthVerified(basePath: string = process.cwd()): boolean {
   return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
@@ -257,6 +393,7 @@ export function isMilestoneDepthVerified(
   basePath: string = process.cwd(),
 ): boolean {
   if (!milestoneId) return false;
+  refreshWriteGateStateFromDisk(basePath);
   return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 
@@ -273,16 +410,17 @@ export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
 }
 
 export function setQueuePhaseActive(active: boolean, basePath: string): void {
-  getWriteGateState(basePath).activeQueuePhase = active;
-  persistWriteGateSnapshot(basePath);
+  mutateWriteGateState(basePath, (state) => {
+    state.activeQueuePhase = active;
+  });
 }
 
 export function resetWriteGateState(basePath: string): void {
-  const state = getWriteGateState(basePath);
-  state.verifiedDepthMilestones.clear();
-  state.verifiedApprovalGates.clear();
-  state.pendingGateId = null;
-  persistWriteGateSnapshot(basePath);
+  mutateWriteGateState(basePath, (state) => {
+    state.verifiedDepthMilestones.clear();
+    state.verifiedApprovalGates.clear();
+    state.pendingGateId = null;
+  }, { reconcile: false });
 }
 
 export function clearDiscussionFlowState(basePath: string): void {
@@ -290,16 +428,20 @@ export function clearDiscussionFlowState(basePath: string): void {
   clearPersistedWriteGateSnapshot(basePath);
 }
 
+/**
+ * Ambient (env-sniffed) export, reserved for the child's dynamic-import
+ * surface (packages/mcp-server) and module-internal use. Host-owned modules
+ * (register-hooks, auto-dispatch, …) must call
+ * hostWriteGateAdapter.markDepthVerified explicitly so a leaked
+ * GSD_WORKFLOW_* env variable cannot silently flip them to child semantics.
+ */
 export function markDepthVerified(milestoneId?: string | null, basePath: string = process.cwd()): void {
-  if (!milestoneId) return;
-  getWriteGateState(basePath).verifiedDepthMilestones.add(milestoneId);
-  persistWriteGateSnapshot(basePath);
+  defaultWriteGateAdapter().markDepthVerified(milestoneId, basePath);
 }
 
+/** Ambient export for the child's dynamic-import surface — see markDepthVerified. */
 export function markApprovalGateVerified(gateId?: string | null, basePath: string = process.cwd()): void {
-  if (!gateId) return;
-  getWriteGateState(basePath).verifiedApprovalGates.add(gateId);
-  persistWriteGateSnapshot(basePath);
+  defaultWriteGateAdapter().markApprovalGateVerified(gateId, basePath);
 }
 
 export function isApprovalGateVerifiedInSnapshot(
@@ -335,30 +477,174 @@ function extractContextMilestoneId(inputPath: string): string | null {
 }
 
 /**
- * Mark a gate as pending (called when ask_user_questions is invoked with a gate ID).
+ * Mark a gate as pending (called when ask_user_questions is invoked with a
+ * gate ID). Delegates to the process's default adapter: in the workflow MCP
+ * child the arm is unconditional (a fresh question intentionally revokes
+ * prior verification); in the host the adapter's verified-on-disk-wins
+ * guard applies and a suppressed arm returns false.
+ *
+ * Ambient (env-sniffed) export, reserved for the child's dynamic-import
+ * surface (packages/mcp-server). Host-owned modules must call
+ * hostWriteGateAdapter.setPending explicitly.
  */
-export function setPendingGate(gateId: string, basePath: string): void {
-  const state = getWriteGateState(basePath);
+export function setPendingGate(gateId: string, basePath: string): boolean {
+  return defaultWriteGateAdapter().setPending(gateId, basePath);
+}
+
+/** Arm `gateId` on a reconciled state, revoking its prior verification. */
+function armPendingGate(state: InMemoryWriteGateState, gateId: string): void {
   state.pendingGateId = gateId;
   state.verifiedApprovalGates.delete(gateId);
   const milestoneId = extractDepthVerificationMilestoneId(gateId);
   if (milestoneId) state.verifiedDepthMilestones.delete(milestoneId);
-  persistWriteGateSnapshot(basePath);
 }
 
 /**
  * Clear the pending gate (called when the user confirms).
+ * Ambient export for the child's dynamic-import surface — host-owned
+ * modules must call hostWriteGateAdapter.clearPending explicitly.
  */
 export function clearPendingGate(basePath: string): void {
-  getWriteGateState(basePath).pendingGateId = null;
-  persistWriteGateSnapshot(basePath);
+  defaultWriteGateAdapter().clearPending(basePath);
 }
 
 /**
  * Get the currently pending gate, if any.
+ * Ambient export for the child's dynamic-import surface — host-owned
+ * modules should prefer hostWriteGateAdapter.readState.
  */
 export function getPendingGate(basePath: string = process.cwd()): string | null {
-  return getWriteGateState(basePath).pendingGateId;
+  return defaultWriteGateAdapter().readState(basePath).pendingGateId;
+}
+
+// ─── Write-gate two-process seam ─────────────────────────────────────────────
+//
+// Two processes write .gsd/runtime/write-gate-state.json: the extension host
+// and the workflow MCP child (which dynamically imports this same compiled
+// module — see GSD_WORKFLOW_WRITE_GATE_MODULE in workflow-mcp.ts and
+// packages/mcp-server/src/server.ts). The adapters below name that seam:
+// every cross-process interleaving reduces to "host adapter op vs child
+// adapter op", which is deterministic given the merge rule documented on
+// mergeSnapshotIntoState plus the unconditional read-merge-write persist.
+
+export interface WriteGateStateAdapter {
+  readonly writer: WriteGateWriter;
+  /** Fresh (child) or disk-reconciled (host) view of gate state. */
+  readState(basePath: string): WriteGateSnapshot;
+  markDepthVerified(milestoneId: string | null | undefined, basePath: string): void;
+  markApprovalGateVerified(gateId: string | null | undefined, basePath: string): void;
+  /**
+   * Arm a pending gate. Returns false when the adapter's policy suppressed
+   * the arm (host: gate already verified on disk — verified wins over a
+   * stale re-arm). Child adapter always arms (a fresh question intentionally
+   * revokes prior verification).
+   */
+  setPending(gateId: string, basePath: string): boolean;
+  clearPending(basePath: string): void;
+}
+
+/**
+ * HOST adapter: in-memory state + reconcile-on-read. Disk verifications are
+ * never lost (union merge), and a gate verified on disk wins over an
+ * in-memory pending re-arm — setPending refuses to clobber a verification
+ * the child already recorded. This generalizes the ad-hoc re-arm guard that
+ * previously protected only the tool_execution_start window in
+ * register-hooks.ts.
+ */
+export const hostWriteGateAdapter: WriteGateStateAdapter = {
+  writer: "host",
+  readState(basePath: string): WriteGateSnapshot {
+    return refreshWriteGateStateFromDisk(basePath);
+  },
+  markDepthVerified(milestoneId, basePath): void {
+    if (!milestoneId) return;
+    mutateWriteGateState(basePath, (state) => {
+      state.verifiedDepthMilestones.add(milestoneId);
+    }, { writer: "host" });
+  },
+  markApprovalGateVerified(gateId, basePath): void {
+    if (!gateId) return;
+    mutateWriteGateState(basePath, (state) => {
+      state.verifiedApprovalGates.add(gateId);
+    }, { writer: "host" });
+  },
+  setPending(gateId: string, basePath: string): boolean {
+    // The verified-check runs inside the mutate callback so the single
+    // reconcile read in mutateWriteGateState serves both the guard and the
+    // pre-persist merge. A suppressed arm aborts without persisting.
+    return mutateWriteGateState(basePath, (state) => {
+      if (state.verifiedApprovalGates.has(gateId)) return false;
+      const milestoneId = extractDepthVerificationMilestoneId(gateId);
+      if (milestoneId && state.verifiedDepthMilestones.has(milestoneId)) return false;
+      armPendingGate(state, gateId);
+    }, { writer: "host" });
+  },
+  clearPending(basePath: string): void {
+    mutateWriteGateState(basePath, (state) => {
+      state.pendingGateId = null;
+    }, { writer: "host" });
+  },
+};
+
+/**
+ * CHILD adapter: write-through with always-fresh reads — load the disk
+ * snapshot, mutate, persist. No cross-turn in-memory state is trusted: the
+ * in-process Map entry is replaced from disk before every mutation so a
+ * long-lived MCP child never resurrects state the host has since changed.
+ */
+export const childWriteGateAdapter: WriteGateStateAdapter = {
+  writer: "child",
+  readState(basePath: string): WriteGateSnapshot {
+    return loadWriteGateSnapshot(basePath);
+  },
+  markDepthVerified(milestoneId, basePath): void {
+    if (!milestoneId) return;
+    childMutate(basePath, (state) => {
+      state.verifiedDepthMilestones.add(milestoneId);
+    });
+  },
+  markApprovalGateVerified(gateId, basePath): void {
+    if (!gateId) return;
+    childMutate(basePath, (state) => {
+      state.verifiedApprovalGates.add(gateId);
+    });
+  },
+  setPending(gateId: string, basePath: string): boolean {
+    childMutate(basePath, (state) => armPendingGate(state, gateId));
+    return true;
+  },
+  clearPending(basePath: string): void {
+    childMutate(basePath, (state) => {
+      state.pendingGateId = null;
+    });
+  },
+};
+
+function childMutate(basePath: string, mutate: (state: InMemoryWriteGateState) => void): void {
+  const state = getWriteGateState(basePath);
+  if (shouldPersistWriteGateSnapshot()) {
+    // Always-fresh: disk is the only truth for the child; discard any
+    // cross-turn in-memory residue before mutating.
+    replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
+  }
+  mutate(state);
+  persistWriteGateSnapshot(basePath, "child");
+}
+
+/**
+ * Which adapter the module-level convenience exports (markDepthVerified,
+ * setPendingGate, …) delegate to. The workflow MCP child is spawned with
+ * GSD_WORKFLOW_WRITE_GATE_MODULE / GSD_WORKFLOW_PROJECT_ROOT in its
+ * environment (workflow-mcp.ts), so when this module is dynamically imported
+ * inside that process the child adapter is selected automatically; the
+ * extension host process has neither variable and stays on the host adapter.
+ */
+export function defaultWriteGateWriter(env: NodeJS.ProcessEnv = process.env): WriteGateWriter {
+  return env.GSD_WORKFLOW_WRITE_GATE_MODULE || env.GSD_WORKFLOW_PROJECT_ROOT ? "child" : "host";
+}
+
+function defaultWriteGateAdapter(): WriteGateStateAdapter {
+  return defaultWriteGateWriter() === "child" ? childWriteGateAdapter : hostWriteGateAdapter;
 }
 
 /**
@@ -433,33 +719,139 @@ export function shouldBlockPendingGateBashInSnapshot(
   };
 }
 
+// The structural depth-confirmation validator lives in the consent-verdict
+// leaf (../consent-verdict.ts) so the write gate and the Consent Question
+// module share one verdict engine without an import cycle. Re-exported here
+// because the workflow MCP child loads this module by dist path and validates
+// the function is present (packages/mcp-server/src/server.ts).
+export { isDepthConfirmationAnswer } from "../consent-verdict.js";
+
+export interface AskUserQuestionsGateQuestion {
+  id?: unknown;
+  options?: Array<{ label?: string }>;
+}
+
+export interface AskUserQuestionsGateDetails {
+  cancelled?: boolean;
+  interrupted?: boolean;
+  response?: {
+    answers?: Record<string, { selected?: unknown } | undefined>;
+  } | null;
+}
+
+export type AskUserQuestionsGateResult =
+  | { status: "not-gate" }
+  | { status: "waiting"; pendingGateId: string; interrupted: boolean }
+  | { status: "verified"; gateId: string; milestoneId: string | null }
+  | { status: "declined"; gateId: string };
+
+function findGateQuestion(
+  questions: AskUserQuestionsGateQuestion[],
+  gateId: string,
+): AskUserQuestionsGateQuestion | undefined {
+  return questions.find((question) => question?.id === gateId);
+}
+
+function verifyAnsweredGate(
+  basePath: string,
+  question: AskUserQuestionsGateQuestion,
+  fallbackMilestoneId?: string | null,
+): AskUserQuestionsGateResult {
+  const gateId = typeof question.id === "string" ? question.id : "";
+  const milestoneId = extractDepthVerificationMilestoneId(gateId) ?? fallbackMilestoneId ?? null;
+  markApprovalGateVerified(gateId, basePath);
+  markDepthVerified(milestoneId, basePath);
+  clearPendingGate(basePath);
+  return { status: "verified", gateId, milestoneId };
+}
+
+/** Map an unresolved (non-verified) gate verdict to the caller-facing result. */
+function unresolvedGateResult(
+  verdict: "declined" | "waiting" | "cancelled",
+  gateId: string,
+  details: AskUserQuestionsGateDetails,
+): AskUserQuestionsGateResult {
+  if (verdict === "declined") return { status: "declined", gateId };
+  // "waiting" (and the unreachable post-cancel case): an empty selection is
+  // not an answer — keep the gate pending and make the caller pause.
+  return {
+    status: "waiting",
+    pendingGateId: gateId,
+    interrupted: details.interrupted === true,
+  };
+}
+
 /**
- * Check whether a depth_verification answer confirms the discussion is complete.
- * Uses structural validation: the selected answer must exactly match the first
- * option label from the question definition (the confirmation option by convention).
- * This rejects free-form "Other" text, decline options, and garbage input without
- * coupling to any specific label substring.
+ * Apply an ask_user_questions round to durable gate state. The per-question
+ * VERDICT comes from the consent-verdict leaf (evaluateGateAnswer) — the same
+ * engine the Consent Question module uses — so write-gate only owns the
+ * persistence/arming side effects:
  *
- * @param selected  The answer's selected value from details.response.answers[id].selected
- * @param options   The question's options array from event.input.questions[n].options
+ * - "verified" verdict → markApprovalGateVerified/markDepthVerified/clearPendingGate.
+ * - "declined" verdict → no state change; the gate (if armed) stays pending.
+ * - "waiting" verdict (empty/missing selection) → no state change; reported as
+ *   "waiting" so callers pause instead of proceeding (fail-closed; an empty
+ *   answer is never an answer).
  */
-export function isDepthConfirmationAnswer(
-  selected: unknown,
-  options?: Array<{ label?: string }>,
-): boolean {
-  const value = Array.isArray(selected) ? selected[0] : selected;
-  if (typeof value !== "string" || !value) return false;
-
-  // If options are available, structurally validate: selected must exactly match
-  // the first option (confirmation) label. Rejects free-form "Other" and decline options.
-  if (Array.isArray(options) && options.length > 0) {
-    const confirmLabel = options[0]?.label;
-    return typeof confirmLabel === "string" && value === confirmLabel;
+export function applyAskUserQuestionsGateResult(options: {
+  basePath: string;
+  questions: AskUserQuestionsGateQuestion[];
+  details: AskUserQuestionsGateDetails;
+  fallbackMilestoneId?: string | null;
+}): AskUserQuestionsGateResult {
+  const { basePath, questions, details, fallbackMilestoneId } = options;
+  const currentPendingGate = getPendingGate(basePath);
+  if (currentPendingGate) {
+    if (details.cancelled || !details.response) {
+      return {
+        status: "waiting",
+        pendingGateId: currentPendingGate,
+        interrupted: details.interrupted === true,
+      };
+    }
+
+    const pendingQuestion = findGateQuestion(questions, currentPendingGate);
+    if (pendingQuestion) {
+      const verdict = evaluateGateAnswer(pendingQuestion, details);
+      if (verdict === "verified") {
+        return verifyAnsweredGate(basePath, pendingQuestion, fallbackMilestoneId);
+      }
+      return unresolvedGateResult(verdict, currentPendingGate, details);
+    }
   }
 
-  // Fail-closed: no options means we cannot structurally validate the answer.
-  // Returning false prevents any free-form string from unlocking the gate.
-  return false;
+  if (details.cancelled || !details.response) return { status: "not-gate" };
+
+  for (const question of questions) {
+    if (typeof question.id !== "string" || !isGateQuestionId(question.id)) continue;
+    const verdict = evaluateGateAnswer(question, details);
+    if (verdict !== "verified") {
+      return unresolvedGateResult(verdict, question.id, details);
+    }
+    if (currentPendingGate && question.id !== currentPendingGate) {
+      // A different gate than the armed one was confirmed — the armed gate is
+      // still unresolved, so do not verify and let discussion continue.
+      return { status: "declined", gateId: currentPendingGate };
+    }
+    return verifyAnsweredGate(basePath, question, fallbackMilestoneId);
+  }
+
+  return { status: "not-gate" };
+}
+
+export function formatPendingAskUserQuestionsGateMessage(
+  pendingGateId: string,
+  interrupted: boolean,
+): string {
+  return [
+    `Waiting for depth confirmation on gate "${pendingGateId}".`,
+    interrupted
+      ? "The confirmation question was interrupted before a response was recorded."
+      : "No user response was received for the confirmation question.",
+    "Do not infer approval from earlier or prior messages.",
+    "Do not proceed, write files, save artifacts, or call other tools.",
+    `Re-call ask_user_questions with the same gate question id ("${pendingGateId}") and wait for the user's response.`,
+  ].join(" ");
 }
 
 export function shouldBlockContextWrite(
@@ -1034,10 +1426,12 @@ export function shouldBlockWorktreeWrite(
   const realTarget = realpathOrResolve(absTarget);
   const realRoot = realpathOrResolve(projectRoot);
   const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
-  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
 
-  // Allow writes inside the legitimate worktrees subtree.
-  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+  // Allow writes inside a legitimate worktrees subtree (canonical
+  // .gsd-worktrees/ or legacy .gsd/worktrees/).
+  for (const container of worktreesDirs(projectRoot)) {
+    if (isPathContained(realTarget, realpathOrResolve(container))) return { block: false };
+  }
 
   // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
   // starts with "worktrees" (the worktrees-extra prefix trick — case 4).

package/src/resources/extensions/gsd/branch-patterns.ts

@@ -14,3 +14,6 @@ export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 
 /** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
 export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;
+
+/** Auto-mode milestone branch prefix: milestone/<MID>. */
+export const MILESTONE_BRANCH_PREFIX = "milestone/";