gsd-pi 2.82.0-dev.725028083 → 2.82.0-dev.9d5798940

package/src/resources/extensions/gsd/auto-verification.ts

@@ -40,6 +40,7 @@ import { join } from "node:path";
 import { resolveUokFlags } from "./uok/flags.js";
 import { UokGateRunner } from "./uok/gate-runner.js";
 import { verificationRetryKey } from "./auto/verification-retry-policy.js";
+import { decideVerificationVerdict } from "./verification-verdict.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -49,12 +50,6 @@ export interface VerificationContext {
 
 export type VerificationResult = "continue" | "retry" | "pause";
 
-function isInfraVerificationFailure(stderr: string): boolean {
-  return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(
-    stderr,
-  );
-}
-
 /**
  * Post-unit guard for `validate-milestone` units (#4094).
  *
@@ -196,7 +191,7 @@ async function countIncompleteSlices(basePath: string, milestoneId: string): Pro
 /**
  * Run the verification gate for the current execute-task unit.
  * Returns:
- * - "continue" — gate passed (or no checks configured), proceed normally
+ * - "continue" — host-owned verification passed, proceed normally
  * - "retry" — gate failed with retries remaining, s.pendingVerificationRetry set for loop re-iteration
  * - "pause" — gate failed with retries exhausted, pauseAuto already called
  */
@@ -260,6 +255,11 @@ export async function runPostUnitVerification(
       }
     }
 
+    const verdict = decideVerificationVerdict(s.currentUnit.type, result);
+    if (!verdict.passed) {
+      result.passed = false;
+    }
+
     if (uokFlags.gates) {
       const gateRunner = new UokGateRunner();
       gateRunner.register({
@@ -272,10 +272,12 @@ export async function runPostUnitVerification(
             : "verification",
           rationale: result.passed
             ? "verification checks passed"
-            : "verification checks failed",
+            : verdict.reason === "no-host-checks"
+              ? "no runnable host-owned verification checks discovered"
+              : "verification checks failed",
           findings: result.passed
             ? ""
-            : formatFailureContext(result),
+            : verdict.failureContext || formatFailureContext(result),
         }),
       });
 
@@ -343,13 +345,18 @@ export async function runPostUnitVerification(
             writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id);
           } else {
             const nextAttempt = attempt + 1;
+            const includeRetryMetadata =
+              !result.passed &&
+              verdict.retryable &&
+              autoFixEnabled &&
+              nextAttempt <= maxRetries;
             writeVerificationJSON(
               result,
               tasksDir,
               tid,
               s.currentUnit.id,
-              nextAttempt,
-              maxRetries,
+              includeRetryMetadata ? nextAttempt : undefined,
+              includeRetryMetadata ? maxRetries : undefined,
             );
           }
         }
@@ -358,26 +365,6 @@ export async function runPostUnitVerification(
       }
     }
 
-    const advisoryFailure =
-      !result.passed &&
-      (result.discoverySource === "package-json" ||
-        result.checks.some((check) =>
-          isInfraVerificationFailure(check.stderr),
-        ));
-
-    if (advisoryFailure) {
-      s.verificationRetryCount.delete(retryKey);
-      s.verificationRetryFailureHashes.delete(retryKey);
-      s.pendingVerificationRetry = null;
-      ctx.ui.notify(
-        result.discoverySource === "package-json"
-          ? "Verification failed in auto-discovered package.json checks — treating as advisory."
-          : "Verification failed due to infrastructure/runtime environment issues — treating as advisory.",
-        "warning",
-      );
-      return "continue";
-    }
-
     // ── Post-execution checks (run after main verification passes for execute-task units) ──
     let postExecChecks: PostExecutionCheckJSON[] | undefined;
     let postExecBlockingFailure = false;
@@ -572,6 +559,17 @@ export async function runPostUnitVerification(
       s.verificationRetryFailureHashes.delete(retryKey);
       s.pendingVerificationRetry = null;
       return "continue";
+    } else if (verdict.reason === "no-host-checks") {
+      s.verificationRetryCount.delete(retryKey);
+      s.verificationRetryFailureHashes.delete(retryKey);
+      s.pendingVerificationRetry = null;
+      ctx.ui.notify(
+        "Verification gate FAILED — no runnable host-owned verification checks were discovered. Pausing for human review.",
+        "error",
+      );
+      process.stderr.write(`verification-gate: ${verdict.failureContext}\n`);
+      await pauseAuto(ctx, pi);
+      return "pause";
     } else if (postExecBlockingFailure) {
       // Post-execution failures are cross-task consistency issues — retrying the same task won't fix them.
       // Skip retry and pause immediately for human review.
@@ -589,7 +587,7 @@ export async function runPostUnitVerification(
       s.verificationRetryCount.set(retryKey, nextAttempt);
       s.pendingVerificationRetry = {
         unitId: s.currentUnit.id,
-        failureContext: formatFailureContext(result),
+        failureContext: verdict.failureContext || formatFailureContext(result),
         attempt: nextAttempt,
       };
       const failedCmds = result.checks
@@ -623,9 +621,13 @@ export async function runPostUnitVerification(
       return "pause";
     }
   } catch (err) {
-    // Gate errors are non-fatal
     logWarning("engine", `verification-gate error: ${(err as Error).message}`);
-    return "continue";
+    ctx.ui.notify(
+      `Verification gate errored before producing an authoritative verdict: ${(err as Error).message}`,
+      "error",
+    );
+    await pauseAuto(ctx, pi);
+    return "pause";
   }
 }
 

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

@@ -282,6 +282,50 @@ function gitRemoteExists(basePath: string, remote: string): boolean {
   }
 }
 
+function findRegularMergeChangedPaths(basePath: string, milestoneBranch: string, mainBranch: string): Set<string> {
+  const changedPaths = new Set<string>();
+  let mergeLog = "";
+  try {
+    mergeLog = execFileSync("git", ["rev-list", "--merges", "--parents", mainBranch], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+  } catch (err) {
+    logWarning("worktree", `regular merge lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    return changedPaths;
+  }
+
+  for (const line of mergeLog.split("\n").filter(Boolean)) {
+    const [mergeCommit, firstParent, ...otherParents] = line.split(" ");
+    if (!mergeCommit || !firstParent || otherParents.length === 0) continue;
+    const mergedMilestone = otherParents.some((parent) => {
+      try {
+        return nativeIsAncestor(basePath, milestoneBranch, parent);
+      } catch {
+        return false;
+      }
+    });
+    if (!mergedMilestone) continue;
+
+    try {
+      const output = execFileSync("git", ["diff", "--name-only", firstParent, mergeCommit], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim();
+      for (const path of output.split("\n").filter(Boolean)) {
+        if (!path.startsWith(".gsd/")) changedPaths.add(path);
+      }
+    } catch (err) {
+      logWarning("worktree", `regular merge diff lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return changedPaths;
+  }
+
+  return changedPaths;
+}
+
 function clearProjectRootStateFiles(basePath: string, milestoneId: string): void {
   const gsdDir = gsdRoot(basePath);
   // Phase C pt 2: auto.lock removed from this list — the file is gone
@@ -1739,6 +1783,66 @@ export function mergeMilestoneToMain(
     }
   }
 
+  // Already regular-merged milestones can skip the squash path and proceed to cleanup (#5831).
+  if (nativeIsAncestor(originalBasePath_, milestoneBranch, mainBranch)) {
+    const codeChanges = nativeDiffNumstat(
+      originalBasePath_,
+      mainBranch,
+      milestoneBranch,
+    ).filter((entry) => !entry.path.startsWith(".gsd/"));
+    if (codeChanges.length > 0) {
+      const regularMergeChangedPaths = findRegularMergeChangedPaths(
+        originalBasePath_,
+        milestoneBranch,
+        mainBranch,
+      );
+      const unanchoredCodeChanges = codeChanges.filter((entry) =>
+        regularMergeChangedPaths.has(entry.path)
+      );
+      if (unanchoredCodeChanges.length > 0) {
+        process.chdir(previousCwd);
+        throw new GSDError(
+          GSD_GIT_ERROR,
+          `Milestone branch "${milestoneBranch}" is reachable from "${mainBranch}" ` +
+            `but has ${unanchoredCodeChanges.length} milestone-touched code file(s) not on current "${mainBranch}". ` +
+            `Aborting worktree teardown to prevent data loss.`,
+        );
+      }
+    }
+    debugLog("mergeMilestoneToMain", {
+      action: "skip-squash-already-merged",
+      milestoneId,
+      milestoneBranch,
+      mainBranch,
+    });
+    try {
+      clearProjectRootStateFiles(originalBasePath_, milestoneId);
+    } catch (err) {
+      logWarning("worktree", `clearProjectRootStateFiles failed during already-merged cleanup: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+      removeWorktree(originalBasePath_, milestoneId, {
+        branch: milestoneBranch,
+        deleteBranch: false,
+      });
+    } catch (err) {
+      logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+      nativeBranchDelete(originalBasePath_, milestoneBranch);
+    } catch (err) {
+      logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    setActiveWorkspace(null);
+    nudgeGitBranchCache(previousCwd);
+    try {
+      process.chdir(originalBasePath_);
+    } catch (err) {
+      logWarning("worktree", `chdir to project root after already-merged cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+  }
+
   // 7. Shelter queued milestone directories before the squash merge (#2505).
   // The milestone branch may contain copies of queued milestone dirs (via
   // copyPlanningArtifacts), so `git merge --squash` rejects when those same

package/src/resources/extensions/gsd/auto.ts

@@ -240,12 +240,14 @@ import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
 import { createAutoOrchestrator } from "./auto/orchestrator.js";
-import type { AutoOrchestrationModule, AutoOrchestratorDeps } from "./auto/contracts.js";
+import type { AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
 import { reconcileBeforeDispatch } from "./state-reconciliation.js";
 import { compileUnitToolContract } from "./tool-contract.js";
 import { createWorktreeSafetyModule } from "./worktree-safety.js";
 import { resolveManifest } from "./unit-context-manifest.js";
 import { classifyFailure } from "./recovery-classification.js";
+import { supportsStructuredQuestions } from "./workflow-mcp.js";
+import type { MinimalModelRegistry } from "./context-budget.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -1048,13 +1050,11 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
     initHealthWidget(ctx);
   }
 
-  // ADR-016 phase 3 (#5693): the stop-path basePath restore routes through
-  // `Lifecycle.restoreToProjectRoot()`, the sole owner of `s.basePath`
-  // mutation. The verb assigns `s.basePath` before any throwable work
-  // (rebuildGitService, cache invalidation), so a thrown error still leaves
-  // basePath restored — no fallback assignment needed at the call site.
-  // The chdir stays here because `restoreToProjectRoot` is a pure
-  // session-state mutation.
+  // ADR-016 phase 3 (#5693): the stop-path basePath restore + chdir routes
+  // through `Lifecycle.restoreToProjectRoot()`, the sole owner of both
+  // `s.basePath` mutation and the paired `process.chdir` for auto-loop
+  // transitions. The verb assigns `s.basePath` before any throwable work, so
+  // a thrown error still leaves basePath restored.
   if (s.originalBasePath) {
     try {
       buildLifecycle().restoreToProjectRoot();
@@ -1065,11 +1065,6 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
         { file: "auto.ts" },
       );
     }
-    try {
-      process.chdir(s.originalBasePath);
-    } catch (err) {
-      logWarning("engine", `basePath restore/chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-    }
   }
 
   if (s.originalBasePath && s.cmdCtx) {
@@ -1384,20 +1379,14 @@ export async function stopAuto(
     }
 
     // ── Step 7: Restore basePath and chdir (ADR-016 phase 3, #5693) ──
-    // `restoreToProjectRoot` assigns s.basePath before any throwable work;
-    // no fallback assignment is needed at the call site.
+    // `restoreToProjectRoot` owns both s.basePath restore and process.chdir;
+    // no paired chdir is needed at the call site.
     if (s.originalBasePath) {
       try {
         buildLifecycle().restoreToProjectRoot();
       } catch (e) {
         debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
       }
-      try {
-        process.chdir(s.basePath);
-      } catch (err) {
-        /* best-effort */
-        logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-      }
     }
 
     // Re-root the active command session/tool runtime after worktree teardown.
@@ -1792,6 +1781,75 @@ function buildLifecycle(): WorktreeLifecycle {
   return new WorktreeLifecycle(s, buildWorktreeLifecycleDeps());
 }
 
+/**
+ * Build the production `DispatchAdapter` used by `createWiredAutoOrchestrationModule`.
+ *
+ * Exported so tests can verify parity with `runDispatch`'s `resolveDispatch` call —
+ * the wired adapter must derive `structuredQuestionsAvailable`, `sessionContextWindow`,
+ * `sessionProvider`, and `modelRegistry` the same way phases.ts:runDispatch does.
+ */
+export function createWiredDispatchAdapter(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  dispatchBasePath: string,
+): DispatchAdapter {
+  return {
+    async decideNextUnit(input) {
+      const state = input.stateSnapshot;
+      const active = state.activeMilestone;
+      if (!active) return null;
+
+      const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+
+      // Derive session-derived dispatch inputs the same way phases.ts:runDispatch does
+      // (#5789). Prefer caller-supplied values when present so test harnesses and
+      // alternative wirings can inject deterministic snapshots; otherwise pull from
+      // the captured pi/ctx references.
+      const sessionProvider = input.sessionProvider ?? ctx.model?.provider;
+      const sessionContextWindow = input.sessionContextWindow ?? ctx.model?.contextWindow;
+      const modelRegistry = input.modelRegistry ?? (ctx.modelRegistry as MinimalModelRegistry | undefined);
+      const authMode =
+        sessionProvider && typeof ctx.modelRegistry?.getProviderAuthMode === "function"
+          ? ctx.modelRegistry.getProviderAuthMode(sessionProvider)
+          : undefined;
+      const activeTools = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+      // Mirrors runDispatch: deep-planning keeps approval gates in plain chat
+      // because structured questions can be cancelled outside the chat turn on
+      // some transports.
+      const structuredQuestionsAvailable =
+        input.structuredQuestionsAvailable ??
+        (prefs?.planning_depth === "deep"
+          ? "false"
+          : supportsStructuredQuestions(activeTools, {
+              authMode,
+              baseUrl: ctx.model?.baseUrl,
+            })
+            ? "true"
+            : "false");
+
+      const action = await resolveDispatch({
+        basePath: dispatchBasePath,
+        mid: active.id,
+        midTitle: active.title,
+        state,
+        prefs,
+        structuredQuestionsAvailable,
+        sessionContextWindow,
+        sessionProvider,
+        modelRegistry,
+      });
+
+      if (action.action !== "dispatch") return null;
+      return {
+        unitType: action.unitType,
+        unitId: action.unitId,
+        reason: action.matchedRule ?? "dispatch",
+        preconditions: [],
+      };
+    },
+  };
+}
+
 /**
  * Thin entry glue for the new Auto Orchestration module.
  *
@@ -1801,7 +1859,7 @@ function buildLifecycle(): WorktreeLifecycle {
  */
 export function createWiredAutoOrchestrationModule(
   ctx: ExtensionContext,
-  _pi: ExtensionAPI,
+  pi: ExtensionAPI,
   dispatchBasePath: string,
   runtimeBasePath = resolveProjectRoot(dispatchBasePath),
 ): AutoOrchestrationModule {
@@ -1830,30 +1888,7 @@ export function createWiredAutoOrchestrationModule(
         };
       },
     },
-    dispatch: {
-      async decideNextUnit(input) {
-        const state = input.stateSnapshot;
-        const active = state.activeMilestone;
-        if (!active) return null;
-
-        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
-        const action = await resolveDispatch({
-          basePath: dispatchBasePath,
-          mid: active.id,
-          midTitle: active.title,
-          state,
-          prefs,
-        });
-
-        if (action.action !== "dispatch") return null;
-        return {
-          unitType: action.unitType,
-          unitId: action.unitId,
-          reason: action.matchedRule ?? "dispatch",
-          preconditions: [],
-        };
-      },
-    },
+    dispatch: createWiredDispatchAdapter(ctx, pi, dispatchBasePath),
     recovery: {
       async classifyAndRecover(input) {
         const recovery = classifyFailure(input);
@@ -1902,12 +1937,25 @@ export function createWiredAutoOrchestrationModule(
       async cleanupOnStop() {},
     },
     health: {
+      checkResourcesStale() {
+        return checkResourcesStale(s.resourceVersionOnStart);
+      },
       async preAdvanceGate() {
-        const gate = await preDispatchHealthGate(dispatchBasePath);
-        return {
-          allow: gate.proceed,
-          reason: gate.reason,
-        };
+        try {
+          const gate = await preDispatchHealthGate(dispatchBasePath);
+          if (gate.proceed) {
+            return {
+              kind: "pass",
+              fixesApplied: gate.fixesApplied,
+            };
+          }
+          return {
+            kind: "fail",
+            reason: gate.reason ?? "Pre-dispatch health check failed — run /gsd doctor for details.",
+          };
+        } catch (error) {
+          return { kind: "threw", error };
+        }
       },
       async postAdvanceRecord(result) {
         if (result.kind === "error") {
@@ -1975,6 +2023,43 @@ export function createWiredAutoOrchestrationModule(
         }
       },
     },
+    uokGate: {
+      async emit(input) {
+        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+        const uokFlags = resolveUokFlags(prefs);
+        if (!uokFlags.gates) return;
+        const milestoneId = input.milestoneId ?? s.currentMilestoneId ?? undefined;
+        try {
+          const { UokGateRunner } = await import("./uok/gate-runner.js");
+          const runner = new UokGateRunner();
+          runner.register({
+            id: input.gateId,
+            type: input.gateType,
+            execute: async () => ({
+              outcome: input.outcome,
+              failureClass: input.failureClass,
+              rationale: input.rationale,
+              findings: input.findings ?? "",
+            }),
+          });
+          await runner.run(input.gateId, {
+            basePath: dispatchBasePath,
+            traceId: `pre-dispatch:${flowId}`,
+            turnId: `orch-${seq}`,
+            milestoneId,
+            unitType: "pre-dispatch",
+            unitId: `orch-${seq}`,
+          });
+        } catch (err) {
+          logWarning("engine", `uok gate emit failed: ${getErrorMessage(err)}`, {
+            file: "auto.ts",
+            gateId: input.gateId,
+            gateType: input.gateType,
+            ...(milestoneId ? { milestoneId } : {}),
+          });
+        }
+      },
+    },
   };
 
   return createAutoOrchestrator(deps);

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -48,6 +48,11 @@ const MAX_NETWORK_RETRIES = 2;
 function isObjectRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object";
 }
+
+export function _hasEmptyAgentEndContent(content: unknown): boolean {
+  return content == null || (Array.isArray(content) && content.length === 0);
+}
+
 /**
  * Cap on auto-resume attempts for sustained transient-provider errors.
  *
@@ -310,7 +315,7 @@ export async function handleAgentEnd(
     // that carry error context — e.g. errorMessage field or non-empty content
     // indicating a mid-stream failure. (#2695)
     const content = "content" in lastMsg ? lastMsg.content : undefined;
-    const hasEmptyContent = Array.isArray(content) && content.length === 0;
+    const hasEmptyContent = _hasEmptyAgentEndContent(content);
     const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
 
     if (hasEmptyContent && !hasErrorMessage) {

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -1,20 +1,30 @@
 export function extractSubagentAgentClasses(input: unknown): string[] {
   if (!input || typeof input !== "object") return [];
 
-  const record = input as Record<string, unknown>;
   const agentClasses: string[] = [];
+  const visited = new WeakSet<object>();
   const addAgentClass = (value: unknown): void => {
     if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
   };
-  const addFromItems = (value: unknown): void => {
+
+  const visitItems = (value: unknown): void => {
     if (!Array.isArray(value)) return;
     for (const item of value) {
-      if (item && typeof item === "object") addAgentClass((item as Record<string, unknown>).agent);
+      visit(item);
     }
   };
 
-  addAgentClass(record.agent);
-  addFromItems(record.tasks);
-  addFromItems(record.chain);
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== "object") return;
+    if (visited.has(value)) return;
+    visited.add(value);
+    const record = value as Record<string, unknown>;
+    addAgentClass(record.agent);
+    visitItems(record.tasks);
+    visitItems(record.chain);
+    visitItems(record.parallel);
+  };
+
+  visit(input);
   return agentClasses;
 }

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

@@ -5,7 +5,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 
 import { getIsolationMode } from "../preferences.js";
-import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
@@ -65,6 +65,7 @@ const QUEUE_SAFE_TOOLS = new Set([
  *   true / false        — shell no-ops / test exit codes
  */
 const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
+const BASH_VERIFICATION_RE = /^\s*(npm\s+(run\s+(build|test|test:\w+|lint|lint:\w+|typecheck|type-check|verify|ci|validate)\b|test\b)|pnpm\s+(build|test|lint|typecheck|verify)\b|yarn\s+(build|test|lint|typecheck|verify)\b|vitest\b|jest\b|go\s+test\b)/;
 
 interface InMemoryWriteGateState {
   verifiedDepthMilestones: Set<string>;
@@ -767,6 +768,9 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
+ *   - "verification"
+ *                  → allows Bash for project verification commands, but keeps
+ *                    writes restricted to .gsd/ and blocks subagent dispatch.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -804,14 +808,15 @@ export function shouldBlockPlanningUnit(
     return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
   }
 
-  // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
+  // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
   if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
   if (tool.startsWith("gsd_")) return { block: false };
 
   if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
     if (policy.mode === "planning-dispatch") {
       const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
-      const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+      const dispatchContract = compileSubagentPermissionContract(policy);
+      const allowedSubagents = dispatchContract.allowedSubagents;
       const allowed = new Set(allowedSubagents);
       // When agentClasses is undefined, the caller has not been updated to extract
       // agent identities yet. Block and warn so stale callers surface in telemetry
@@ -861,6 +866,17 @@ export function shouldBlockPlanningUnit(
   }
 
   if (tool === "bash") {
+    if (policy.mode === "verification") {
+      if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
+      return {
+        block: true,
+        reason: blockReason(
+          unitType,
+          policy.mode,
+          `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+        ),
+      };
+    }
     if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
     return {
       block: true,