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

package/dist/resources/extensions/gsd/auto-verification.js

@@ -18,9 +18,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";
-function isInfraVerificationFailure(stderr) {
-    return /\b(ENOENT|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN|spawn\s+\S+\s+ENOENT|command not found)\b/i.test(stderr);
-}
+import { decideVerificationVerdict } from "./verification-verdict.js";
 /**
  * Post-unit guard for `validate-milestone` units (#4094).
  *
@@ -128,7 +126,7 @@ async function countIncompleteSlices(basePath, milestoneId) {
 /**
  * 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
  */
@@ -178,6 +176,10 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 process.stderr.write(`  [${w.severity}] ${w.name}: ${w.title}\n`);
             }
         }
+        const verdict = decideVerificationVerdict(s.currentUnit.type, result);
+        if (!verdict.passed) {
+            result.passed = false;
+        }
         if (uokFlags.gates) {
             const gateRunner = new UokGateRunner();
             gateRunner.register({
@@ -190,10 +192,12 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                         : "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),
                 }),
             });
             await gateRunner.run("verification-gate", {
@@ -251,7 +255,11 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                     }
                     else {
                         const nextAttempt = attempt + 1;
-                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, nextAttempt, maxRetries);
+                        const includeRetryMetadata = !result.passed &&
+                            verdict.retryable &&
+                            autoFixEnabled &&
+                            nextAttempt <= maxRetries;
+                        writeVerificationJSON(result, tasksDir, tid, s.currentUnit.id, includeRetryMetadata ? nextAttempt : undefined, includeRetryMetadata ? maxRetries : undefined);
                     }
                 }
             }
@@ -259,18 +267,6 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
                 logWarning("engine", `verification-evidence write error: ${evidenceErr.message}`);
             }
         }
-        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;
         let postExecBlockingFailure = false;
@@ -430,6 +426,15 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             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.
@@ -445,7 +450,7 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
             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
@@ -475,9 +480,10 @@ export async function runPostUnitVerification(vctx, pauseAuto) {
         }
     }
     catch (err) {
-        // Gate errors are non-fatal
         logWarning("engine", `verification-gate error: ${err.message}`);
-        return "continue";
+        ctx.ui.notify(`Verification gate errored before producing an authoritative verdict: ${err.message}`, "error");
+        await pauseAuto(ctx, pi);
+        return "pause";
     }
 }
 /**

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -204,6 +204,52 @@ function gitRemoteExists(basePath, remote) {
         return false;
     }
 }
+function findRegularMergeChangedPaths(basePath, milestoneBranch, mainBranch) {
+    const changedPaths = new Set();
+    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, milestoneId) {
     const gsdDir = gsdRoot(basePath);
     // Phase C pt 2: auto.lock removed from this list — the file is gone
@@ -1482,6 +1528,56 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             });
         }
     }
+    // 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/dist/resources/extensions/gsd/auto.js

@@ -92,6 +92,7 @@ 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 { WorktreeLifecycle, } from "./worktree-lifecycle.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { reorderForCaching } from "./prompt-ordering.js";
@@ -711,13 +712,11 @@ export async function cleanupAfterLoopExit(ctx) {
         }
         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();
@@ -725,12 +724,6 @@ export async function cleanupAfterLoopExit(ctx) {
         catch (err) {
             logWarning("engine", `restore project root failed: ${err instanceof Error ? err.message : String(err)}`, { 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) {
         const result = await rerootCommandSession(s.cmdCtx, s.originalBasePath);
@@ -1001,8 +994,8 @@ export async function stopAuto(ctx, pi, reason, options = {}) {
             }
         }
         // ── 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();
@@ -1010,13 +1003,6 @@ export async function stopAuto(ctx, pi, reason, options = {}) {
             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.
         // mergeAndExit restores process.cwd(), but AgentSession has already captured
@@ -1385,6 +1371,66 @@ export function buildWorktreeLifecycleDeps() {
 function buildLifecycle() {
     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, pi, dispatchBasePath) {
+    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;
+            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.
  *
@@ -1392,7 +1438,7 @@ function buildLifecycle() {
  * no behavior changes to the existing auto loop. It provides a concrete seam
  * the next refactor steps can adopt incrementally.
  */
-export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
+export function createWiredAutoOrchestrationModule(ctx, pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
     const flowId = `auto-orchestrator-${Date.now()}`;
     let seq = 0;
     const deps = {
@@ -1416,30 +1462,7 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
                 };
             },
         },
-        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);
@@ -1488,12 +1511,26 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
             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") {
@@ -1561,6 +1598,45 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
                 }
             },
         },
+        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/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -18,6 +18,9 @@ const MAX_NETWORK_RETRIES = 2;
 function isObjectRecord(value) {
     return !!value && typeof value === "object";
 }
+export function _hasEmptyAgentEndContent(content) {
+    return content == null || (Array.isArray(content) && content.length === 0);
+}
 /**
  * Cap on auto-resume attempts for sustained transient-provider errors.
  *
@@ -246,7 +249,7 @@ export async function handleAgentEnd(pi, event, ctx) {
         // 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) {
             // Non-fatal: treat as a normal agent end so the loop can continue

package/dist/resources/extensions/gsd/bootstrap/subagent-input.js

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

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -3,6 +3,7 @@ import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkS
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 import { getIsolationMode } from "../preferences.js";
+import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 /**
@@ -58,6 +59,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)/;
 function createEmptyWriteGateState() {
     return {
         verifiedDepthMilestones: new Set(),
@@ -642,6 +644,9 @@ function blockReason(unitType, mode, what) {
  *                    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.
@@ -673,7 +678,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         // Unknown tool in read-only mode — block by default.
         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_"))
@@ -681,7 +686,8 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     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
@@ -718,6 +724,14 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
     }
     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 {