gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

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

@@ -23,8 +23,10 @@ import {
 import {
   markDepthVerified,
   isMilestoneDepthVerified,
+  markApprovalGateVerified,
   shouldBlockContextArtifactSave,
   shouldBlockContextArtifactSaveInSnapshot,
+  shouldBlockRootArtifactSaveInSnapshot,
   clearDiscussionFlowState,
   resetWriteGateState,
   loadWriteGateSnapshot,
@@ -220,6 +222,112 @@ test('write-gate: gsd_summary_save only blocks final milestone CONTEXT writes',
   clearDiscussionFlowState();
 });
 
+test('write-gate: root PROJECT/REQUIREMENTS final saves block behind pending approval gate', () => {
+  const snapshot = {
+    verifiedDepthMilestones: [],
+    verifiedApprovalGates: [],
+    activeQueuePhase: false,
+    pendingGateId: 'depth_verification_requirements_confirm',
+  };
+
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(snapshot, 'REQUIREMENTS').block,
+    true,
+    'final REQUIREMENTS.md must wait for approval',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(snapshot, 'PROJECT').block,
+    true,
+    'final PROJECT.md must wait for approval',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(snapshot, 'REQUIREMENTS-DRAFT').block,
+    false,
+    'draft requirements can still be saved',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot({ ...snapshot, pendingGateId: null }, 'REQUIREMENTS').block,
+    false,
+    'no pending approval gate means final root artifacts can save',
+  );
+});
+
+test('write-gate: deep root PROJECT/REQUIREMENTS final saves require verified approval', () => {
+  const snapshot = {
+    verifiedDepthMilestones: [],
+    verifiedApprovalGates: [],
+    activeQueuePhase: false,
+    pendingGateId: null,
+  };
+
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      snapshot,
+      'PROJECT',
+      { requireVerifiedApproval: true },
+    ).block,
+    true,
+    'deep PROJECT save is fail-closed without verified project approval',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      { ...snapshot, verifiedApprovalGates: ['depth_verification_project_confirm'] },
+      'PROJECT',
+      { requireVerifiedApproval: true },
+    ).block,
+    false,
+    'verified project approval unlocks PROJECT',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      { ...snapshot, verifiedApprovalGates: ['depth_verification_project_confirm'] },
+      'REQUIREMENTS',
+      { requireVerifiedApproval: true },
+    ).block,
+    true,
+    'project approval does not unlock REQUIREMENTS',
+  );
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      { ...snapshot, verifiedApprovalGates: ['depth_verification_requirements_confirm'] },
+      'REQUIREMENTS',
+      { requireVerifiedApproval: true },
+    ).block,
+    false,
+    'verified requirements approval unlocks REQUIREMENTS',
+  );
+});
+
+test('write-gate: reopening a gate revokes its previous verified approval', () => {
+  clearDiscussionFlowState();
+
+  markApprovalGateVerified('depth_verification_project_confirm');
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      loadWriteGateSnapshot(),
+      'PROJECT',
+      { requireVerifiedApproval: true },
+    ).block,
+    false,
+    'precondition: verified approval unlocks the final project artifact',
+  );
+
+  setPendingGate('depth_verification_project_confirm');
+  clearPendingGate();
+
+  assert.strictEqual(
+    shouldBlockRootArtifactSaveInSnapshot(
+      loadWriteGateSnapshot(),
+      'PROJECT',
+      { requireVerifiedApproval: true },
+    ).block,
+    true,
+    'a re-asked gate must require a fresh approval',
+  );
+
+  clearDiscussionFlowState();
+});
+
 // ═══════════════════════════════════════════════════════════════════════
 // Discussion gate enforcement tests (pending gate mechanism)
 // ═══════════════════════════════════════════════════════════════════════
@@ -286,19 +394,19 @@ test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate',
   clearDiscussionFlowState();
 });
 
-// ─── Scenario 22: shouldBlockPendingGate allows safe tools when gate is pending ──
+// ─── Scenario 22: shouldBlockPendingGate allows only re-asking when gate is pending ──
 
-test('write-gate: shouldBlockPendingGate allows read-only and ask_user_questions during pending gate', () => {
+test('write-gate: shouldBlockPendingGate blocks read-only tools and allows ask_user_questions during pending gate', () => {
   clearDiscussionFlowState();
   setPendingGate('depth_verification');
 
   // ask_user_questions is always safe (model needs to re-ask)
   assert.strictEqual(shouldBlockPendingGate('ask_user_questions', 'M001').block, false);
-  // read-only tools are safe
-  assert.strictEqual(shouldBlockPendingGate('read', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGate('grep', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGate('glob', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGate('ls', 'M001').block, false);
+  // read-only tools are blocked so the user-facing question remains visible
+  assert.strictEqual(shouldBlockPendingGate('read', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGate('grep', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGate('glob', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGate('ls', 'M001').block, true);
 
   clearDiscussionFlowState();
 });
@@ -329,16 +437,16 @@ test('write-gate: shouldBlockPendingGate blocks in queue mode when gate is pendi
   clearDiscussionFlowState();
 });
 
-// ─── Scenario 25: shouldBlockPendingGateBash allows read-only commands ──
+// ─── Scenario 25: shouldBlockPendingGateBash blocks read-only commands ──
 
-test('write-gate: shouldBlockPendingGateBash allows read-only commands during pending gate', () => {
+test('write-gate: shouldBlockPendingGateBash blocks read-only commands during pending gate', () => {
   clearDiscussionFlowState();
   setPendingGate('depth_verification');
 
-  assert.strictEqual(shouldBlockPendingGateBash('cat file.txt', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGateBash('git log --oneline', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGateBash('grep -r pattern .', 'M001').block, false);
-  assert.strictEqual(shouldBlockPendingGateBash('ls -la', 'M001').block, false);
+  assert.strictEqual(shouldBlockPendingGateBash('cat file.txt', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGateBash('git log --oneline', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGateBash('grep -r pattern .', 'M001').block, true);
+  assert.strictEqual(shouldBlockPendingGateBash('ls -la', 'M001').block, true);
 
   clearDiscussionFlowState();
 });

package/src/resources/extensions/gsd/token-counter.ts

@@ -1,7 +1,8 @@
-export type TokenProvider = "anthropic" | "openai" | "google" | "mistral" | "bedrock" | "unknown";
+export type TokenProvider = "anthropic" | "claude-code" | "openai" | "google" | "mistral" | "bedrock" | "unknown";
 
 const CHARS_PER_TOKEN_BY_PROVIDER: Record<TokenProvider, number> = {
 	anthropic: 3.5,
+	"claude-code": 3.5,
 	openai: 4.0,
 	google: 4.0,
 	mistral: 3.8,

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -1,7 +1,8 @@
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
-import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
+import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
 import {
+  getActiveRequirements,
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
@@ -9,7 +10,7 @@ import {
   saveGateResult,
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
-import { saveArtifactToDb } from "../db-writer.js";
+import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
 import { resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { unlinkSync } from "node:fs";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
@@ -29,8 +30,19 @@ import type { ValidateMilestoneParams } from "./validate-milestone.js";
 import { handleValidateMilestone } from "./validate-milestone.js";
 import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
-
-export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT"] as const;
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+
+export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
+  "SUMMARY",
+  "RESEARCH",
+  "CONTEXT",
+  "ASSESSMENT",
+  "CONTEXT-DRAFT",
+  "PROJECT",
+  "PROJECT-DRAFT",
+  "REQUIREMENTS",
+  "REQUIREMENTS-DRAFT",
+] as const;
 
 export function isSupportedSummaryArtifactType(
   artifactType: string,
@@ -38,6 +50,13 @@ export function isSupportedSummaryArtifactType(
   return (SUPPORTED_SUMMARY_ARTIFACT_TYPES as readonly string[]).includes(artifactType);
 }
 
+function isRootSummaryArtifactType(artifactType: string): boolean {
+  return artifactType === "PROJECT" ||
+    artifactType === "PROJECT-DRAFT" ||
+    artifactType === "REQUIREMENTS" ||
+    artifactType === "REQUIREMENTS-DRAFT";
+}
+
 export interface ToolExecutionResult {
   content: Array<{ type: "text"; text: string }>;
   details: Record<string, unknown>;
@@ -45,7 +64,7 @@ export interface ToolExecutionResult {
 }
 
 export interface SummarySaveParams {
-  milestone_id: string;
+  milestone_id?: string;
   slice_id?: string;
   task_id?: string;
   artifact_type: string;
@@ -71,8 +90,29 @@ export async function executeSummarySave(
     isError: true,
       };
   }
+  if (!isRootSummaryArtifactType(params.artifact_type) && !params.milestone_id) {
+    return {
+      content: [{ type: "text", text: `Error: milestone_id is required for artifact_type "${params.artifact_type}". Root-level artifacts must use PROJECT, PROJECT-DRAFT, REQUIREMENTS, or REQUIREMENTS-DRAFT.` }],
+      details: { operation: "save_summary", error: "missing_milestone_id" },
+      isError: true,
+    };
+  }
+  const writeGateSnapshot = loadWriteGateSnapshot(basePath);
+  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
+  const rootArtifactGuard = shouldBlockRootArtifactSaveInSnapshot(
+    writeGateSnapshot,
+    params.artifact_type,
+    { requireVerifiedApproval: prefs?.planning_depth === "deep" },
+  );
+  if (rootArtifactGuard.block) {
+    return {
+      content: [{ type: "text", text: `Error saving artifact: ${rootArtifactGuard.reason ?? "root artifact write blocked"}` }],
+      details: { operation: "save_summary", error: "root_artifact_write_blocked" },
+      isError: true,
+    };
+  }
   const contextGuard = shouldBlockContextArtifactSaveInSnapshot(
-    loadWriteGateSnapshot(basePath),
+    writeGateSnapshot,
     params.artifact_type,
     params.milestone_id ?? null,
     params.slice_id ?? null,
@@ -86,7 +126,15 @@ export async function executeSummarySave(
   }
   try {
     let relativePath: string;
-    if (params.task_id && params.slice_id) {
+    if (params.artifact_type === "PROJECT") {
+      relativePath = "PROJECT.md";
+    } else if (params.artifact_type === "PROJECT-DRAFT") {
+      relativePath = "PROJECT-DRAFT.md";
+    } else if (params.artifact_type === "REQUIREMENTS") {
+      relativePath = "REQUIREMENTS.md";
+    } else if (params.artifact_type === "REQUIREMENTS-DRAFT") {
+      relativePath = "REQUIREMENTS-DRAFT.md";
+    } else if (params.task_id && params.slice_id) {
       relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
     } else if (params.slice_id) {
       relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
@@ -94,14 +142,33 @@ export async function executeSummarySave(
       relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
     }
 
+    const activeRequirements = params.artifact_type === "REQUIREMENTS"
+      ? getActiveRequirements()
+      : null;
+    if (params.artifact_type === "REQUIREMENTS" && activeRequirements?.length === 0) {
+      return {
+        content: [{ type: "text", text: "Error: Cannot save REQUIREMENTS artifact — no active requirements found in the database. Call gsd_requirement_save for each requirement before calling gsd_summary_save(REQUIREMENTS)." }],
+        details: { operation: "save_summary", error: "no_active_requirements" },
+        isError: true,
+      };
+    }
+
+    const contentToSave = params.artifact_type === "REQUIREMENTS"
+      ? generateRequirementsMd(activeRequirements ?? [])
+      : params.content;
+    const contentSource = params.artifact_type === "REQUIREMENTS"
+      ? "requirements_table"
+      : "provided_content";
+    const isRootArtifact = isRootSummaryArtifactType(params.artifact_type);
+
     await saveArtifactToDb(
       {
         path: relativePath,
         artifact_type: params.artifact_type,
-        content: params.content,
-        milestone_id: params.milestone_id,
-        slice_id: params.slice_id,
-        task_id: params.task_id,
+        content: contentToSave,
+        milestone_id: isRootArtifact ? undefined : params.milestone_id,
+        slice_id: isRootArtifact ? undefined : params.slice_id,
+        task_id: isRootArtifact ? undefined : params.task_id,
       },
       basePath,
     );
@@ -109,8 +176,8 @@ export async function executeSummarySave(
     if (params.artifact_type === "CONTEXT" && !params.task_id) {
       try {
         const draftFile = params.slice_id
-          ? resolveSliceFile(basePath, params.milestone_id, params.slice_id, "CONTEXT-DRAFT")
-          : resolveMilestoneFile(basePath, params.milestone_id, "CONTEXT-DRAFT");
+          ? resolveSliceFile(basePath, params.milestone_id!, params.slice_id, "CONTEXT-DRAFT")
+          : resolveMilestoneFile(basePath, params.milestone_id!, "CONTEXT-DRAFT");
         if (draftFile) unlinkSync(draftFile);
       } catch (e) {
         logWarning("tool", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`);
@@ -119,7 +186,7 @@ export async function executeSummarySave(
 
     return {
       content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-      details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
+      details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type, content_source: contentSource },
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -325,6 +325,12 @@ export const KNOWN_UNIT_TYPES = [
   "run-uat",
   "gate-evaluate",
   "rewrite-docs",
+  // Deep planning mode (project-level) units
+  "workflow-preferences",
+  "discuss-project",
+  "discuss-requirements",
+  "research-decision",
+  "research-project",
 ] as const;
 
 export type UnitType = typeof KNOWN_UNIT_TYPES[number];
@@ -381,7 +387,11 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: validation is a verification-fan-out unit. It reads
+    // the milestone surface and dispatches reviewer/security/tester subagents
+    // to report findings without touching user source. Mirrors
+    // complete-milestone's policy. Write isolation to .gsd/ is preserved.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -590,6 +600,92 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     },
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
+
+  // ─── Deep planning mode (project-level) units ────────────────────────
+  // workflow-preferences: default-writing stage that records
+  // commit_policy / branch_model in PREFERENCES.md, defaults
+  // uat_dispatch/executor_class, and records the research decision. No project artifacts needed.
+  "workflow-preferences": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // discuss-project: PROJECT.md interview (deep mode only). Project-scoped
+  // discussion runs before any milestone exists, so milestone artifacts are
+  // not loaded. Keeps templates available for PROJECT.md scaffolding.
+  "discuss-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // discuss-requirements: REQUIREMENTS.md interview. PROJECT.md is the
+  // primary context input; templates carry the requirements format.
+  "discuss-requirements": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["project", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // research-decision: lightweight one-question yes/no unit. Writes a
+  // marker JSON; no project artifacts needed.
+  "research-decision": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // research-project: orchestrator that fans out 4 parallel scout subagents
+  // for project research (stack, features, architecture, pitfalls). Needs the
+  // planning-dispatch policy to dispatch them. PROJECT.md + REQUIREMENTS.md
+  // give the orchestrator the framing context.
+  "research-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: { mode: "planning-dispatch", allowedSubagents: ["scout"] },
+    artifacts: {
+      inline: ["project", "requirements", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
 };
 
 // ─── Lookup helper ────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -21,8 +21,10 @@ export function isExecutionEntryPhase(phase: Phase): boolean {
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
+  emptyGraph?: boolean;
   graphPath?: string;
   nodeCount?: number;
+  sliceCount?: number;
   clarifyRoundLimit?: number;
   researchSynthesized?: boolean;
   draftContextIncluded?: boolean;
@@ -73,6 +75,10 @@ export function isMissingFinalizedContextResult(result: PlanV2CompileResult): bo
   return !result.ok && result.finalizedContextIncluded === false;
 }
 
+export function isEmptyPlanV2GraphResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.emptyGraph === true;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -170,6 +176,7 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
     ok: true,
     graphPath: outPath,
     nodeCount: nodes.length,
+    sliceCount: slices.length,
     clarifyRoundLimit,
     researchSynthesized: output.pipeline.researchSynthesized,
     draftContextIncluded: output.pipeline.draftContextIncluded,
@@ -181,7 +188,18 @@ export function ensurePlanV2Graph(basePath: string, state: GSDState): PlanV2Comp
   const compiled = compileUnitGraphFromState(basePath, state);
   if (!compiled.ok) return compiled;
   if ((compiled.nodeCount ?? 0) <= 0) {
-    return { ok: false, reason: "compiled graph is empty" };
+    if (
+      (state.phase === "validating-milestone" || state.phase === "completing-milestone") &&
+      (compiled.sliceCount ?? 0) > 0
+    ) {
+      return compiled;
+    }
+    return {
+      ...compiled,
+      ok: false,
+      reason: "compiled graph is empty",
+      emptyGraph: true,
+    };
   }
   return compiled;
 }

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -0,0 +1,166 @@
+const USER_APPROVAL_UNIT_TYPES = new Set([
+  "discuss-project",
+  "discuss-requirements",
+  "discuss-milestone",
+  "research-decision",
+]);
+
+const REMOTE_QUESTION_FAILURE_RE =
+  /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
+
+const APPROVAL_WAIT_RE =
+  /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
+
+const APPROVAL_QUESTION_RE =
+  /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
+
+const APPROVAL_RIGHT_QUESTION_RE =
+  /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
+
+const APPROVAL_CHANGE_QUESTION_RE =
+  /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
+
+const RESEARCH_DECISION_QUESTION_RE =
+  /\b(?:research|skip)\b/i;
+
+function extractTextFromMessage(msg: unknown): string {
+  if (!msg || typeof msg !== "object") return "";
+  const content = (msg as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const typed = block as { type?: unknown; text?: unknown };
+    if (typed.type === "text" && typeof typed.text === "string") {
+      parts.push(typed.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+function lastAssistantText(messages: unknown[] | undefined): string {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== "object") continue;
+    if ((msg as { role?: unknown }).role !== "assistant") continue;
+    const text = extractTextFromMessage(msg).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+function anyMessageMatches(messages: unknown[] | undefined, pattern: RegExp): boolean {
+  if (!Array.isArray(messages)) return false;
+  return messages.some((msg) => {
+    if (!msg || typeof msg !== "object") return false;
+    if ((msg as { role?: unknown }).role === "user") return false;
+    return pattern.test(extractTextFromMessage(msg));
+  });
+}
+
+function hasApprovalQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (APPROVAL_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_RIGHT_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_CHANGE_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+function hasResearchDecisionQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (RESEARCH_DECISION_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+export function approvalGateIdForUnit(
+  unitType: string | undefined,
+  unitId?: string | null,
+): string | null {
+  if (!unitType) return null;
+  if (unitType === "discuss-project") return "depth_verification_project_confirm";
+  if (unitType === "discuss-requirements") return "depth_verification_requirements_confirm";
+  if (unitType === "research-decision") return "depth_verification_research_decision_confirm";
+  if (unitType === "discuss-milestone") {
+    const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
+      ? unitId
+      : "milestone";
+    return `depth_verification_${safeUnitId}_confirm`;
+  }
+  return null;
+}
+
+const CHANGE_REQUEST_RESPONSE_RE =
+  /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
+
+const APPROVAL_RESPONSE_RE =
+  /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
+
+const RESEARCH_DECISION_RESPONSE_RE =
+  /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
+
+export function isExplicitApprovalResponse(
+  input: string | undefined,
+  pendingGateId?: string | null,
+): boolean {
+  const text = input?.trim() ?? "";
+  if (!text) return false;
+  if (pendingGateId?.includes("research_decision")) {
+    return RESEARCH_DECISION_RESPONSE_RE.test(text);
+  }
+  if (CHANGE_REQUEST_RESPONSE_RE.test(text)) return false;
+  return APPROVAL_RESPONSE_RE.test(text);
+}
+
+export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.some((line) => line.endsWith("?"))) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function isAwaitingApprovalBoundary(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function shouldPauseForUserApprovalQuestion(
+  unitType: string | undefined,
+  messages: unknown[] | undefined,
+): boolean {
+  if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType)) return false;
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  if (unitType === "research-decision") return hasResearchDecisionQuestion(text);
+  return hasApprovalQuestion(text);
+}