gsd-pi 2.73.1-dev.d987996 → 2.74.0-dev.0306a2e

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -10,11 +10,14 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { GSDPreferences } from "./preferences.js";
 import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
 import type { ComplexityTier } from "./complexity-classifier.js";
-import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
+import { classifyUnitComplexity, extractTaskMetadata, tierLabel } from "./complexity-classifier.js";
 import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet, filterToolsForProvider } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
 import { getSessionModelOverride } from "./session-model-override.js";
+import { logWarning } from "./workflow-logger.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { applyModelPolicyFilter } from "./uok/model-policy.js";
 
 export interface ModelSelectionResult {
   /** Routing metadata for metrics recording */
@@ -25,9 +28,7 @@ export interface ModelSelectionResult {
 
 export function resolvePreferredModelConfig(
   unitType: string,
-  autoModeStartModel: { provider: string; id: string } | null,
-  /** When false, only return explicit per-phase model configs — do not
-   *  synthesize a routing ceiling from dynamic_routing.tier_models (#3962). */
+  autoModeStartModel: { provider: string; id: string; flatRateCtx?: FlatRateContext } | null,
   isAutoMode = true,
 ) {
   const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
@@ -41,7 +42,7 @@ export function resolvePreferredModelConfig(
   if (!routingConfig.enabled || !routingConfig.tier_models) return undefined;
 
   // Don't synthesize a routing config for flat-rate providers (#3453).
-  if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider)) return undefined;
+  if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx)) return undefined;
 
   const ceilingModel = routingConfig.tier_models.heavy
     ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
@@ -68,7 +69,7 @@ export async function selectAndApplyModel(
   basePath: string,
   prefs: GSDPreferences | undefined,
   verbose: boolean,
-  autoModeStartModel: { provider: string; id: string } | null,
+  autoModeStartModel: { provider: string; id: string; flatRateCtx?: FlatRateContext } | null,
   retryContext?: { isRetry: boolean; previousTier?: string },
   /** When false (interactive/guided-flow), skip dynamic routing and use the session model.
    *  Dynamic routing only applies in auto-mode where cost optimization is expected. (#3962) */
@@ -76,9 +77,21 @@ export async function selectAndApplyModel(
   /** Explicit /gsd model pin captured at bootstrap for long-running auto loops. */
   sessionModelOverride?: { provider: string; id: string } | null,
 ): Promise<ModelSelectionResult> {
+  const uokFlags = resolveUokFlags(prefs);
   const effectiveSessionModelOverride = sessionModelOverride === undefined
     ? getSessionModelOverride(ctx.sessionManager.getSessionId())
     : (sessionModelOverride ?? undefined);
+  // Enrich the start model with a flat-rate context up front so routing
+  // synthesis and the dispatch-time guard see the same signals (built-in
+  // list + user `flat_rate_providers` preference + externalCli auto-
+  // detection).  The dispatch-time primary-model check below builds its
+  // own per-provider context when it has a resolved primary model.
+  if (autoModeStartModel) {
+    autoModeStartModel = {
+      ...autoModeStartModel,
+      flatRateCtx: buildFlatRateContext(autoModeStartModel.provider, ctx, prefs),
+    };
+  }
   const modelConfig = effectiveSessionModelOverride
     ? undefined
     : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
@@ -87,6 +100,9 @@ export async function selectAndApplyModel(
 
   if (modelConfig) {
     const availableModels = ctx.modelRegistry.getAvailable();
+    const modelPolicyTraceId = `model:${ctx.sessionManager.getSessionId()}:${Date.now()}`;
+    const modelPolicyTurnId = `${unitType}:${unitId}`;
+    let policyAllowedModelKeys: Set<string> | null = null;
 
     // ─── Dynamic Model Routing ─────────────────────────────────────────
     // Dynamic routing (complexity-based downgrading) only applies in auto-mode.
@@ -96,8 +112,40 @@ export async function selectAndApplyModel(
     if (!isAutoMode) {
       routingConfig.enabled = false;
     }
+    // burn-max defaults to quality-first dispatch (no downgrade routing).
+    if (prefs?.token_profile === "burn-max") {
+      routingConfig.enabled = false;
+    }
     let effectiveModelConfig = modelConfig;
     let routingTierLabel = "";
+    let routingEligibleModels = availableModels;
+
+    const taskMetadataForPolicy = unitType === "execute-task"
+      ? extractTaskMetadata(unitId, basePath)
+      : undefined;
+
+    if (uokFlags.modelPolicy) {
+      const policy = applyModelPolicyFilter(
+        availableModels,
+        {
+          basePath,
+          traceId: modelPolicyTraceId,
+          turnId: modelPolicyTurnId,
+          unitType,
+          taskMetadata: taskMetadataForPolicy,
+          currentProvider: ctx.model?.provider,
+          allowCrossProvider: routingConfig.cross_provider !== false,
+          requiredTools: pi.getActiveTools(),
+        },
+      );
+      routingEligibleModels = policy.eligible;
+      policyAllowedModelKeys = new Set(
+        policy.eligible.map((m) => `${m.provider.toLowerCase()}/${m.id.toLowerCase()}`),
+      );
+      if (routingEligibleModels.length === 0) {
+        throw new Error(`Model policy denied all candidate models for ${unitType}/${unitId}`);
+      }
+    }
 
     // Disable routing for flat-rate providers like GitHub Copilot (#3453).
     // All models cost the same per request, so downgrading to a cheaper
@@ -105,14 +153,18 @@ export async function selectAndApplyModel(
     // Fail-closed: if primary model can't be resolved, fall back to
     // provider-level signals rather than allowing unwanted downgrades.
     if (routingConfig.enabled) {
-      const primaryModel = resolveModelId(modelConfig.primary, availableModels, ctx.model?.provider);
+      const primaryModel = resolveModelId(modelConfig.primary, routingEligibleModels, ctx.model?.provider);
       if (primaryModel) {
-        if (isFlatRateProvider(primaryModel.provider)) {
+        const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);
+        if (isFlatRateProvider(primaryModel.provider, primaryFlatRateCtx)) {
           routingConfig.enabled = false;
         }
       } else if (
-        (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider))
-        || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider))
+        (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx))
+        || (ctx.model?.provider && isFlatRateProvider(
+          ctx.model.provider,
+          buildFlatRateContext(ctx.model.provider, ctx, prefs),
+        ))
       ) {
         // Primary model unresolvable but provider signals indicate flat-rate —
         // disable routing to prevent quality degradation.
@@ -135,8 +187,14 @@ export async function selectAndApplyModel(
       const shouldClassify = !isHook || routingConfig.hooks !== false;
 
       if (shouldClassify) {
-        let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
-        const availableModelIds = availableModels.map(m => m.id);
+        let classification = classifyUnitComplexity(
+          unitType,
+          unitId,
+          basePath,
+          budgetPct,
+          taskMetadataForPolicy,
+        );
+        const availableModelIds = routingEligibleModels.map(m => m.id);
 
         // Escalate tier on retry when escalate_on_failure is enabled (default: true)
         if (
@@ -243,15 +301,28 @@ export async function selectAndApplyModel(
     }
 
     const modelsToTry = [effectiveModelConfig.primary, ...effectiveModelConfig.fallbacks];
+    let attemptedPolicyEligible = false;
 
     for (const modelId of modelsToTry) {
-      const model = resolveModelId(modelId, availableModels, ctx.model?.provider);
+      const resolutionPool = uokFlags.modelPolicy ? routingEligibleModels : availableModels;
+      const model = resolveModelId(modelId, resolutionPool, ctx.model?.provider);
 
       if (!model) {
         if (verbose) ctx.ui.notify(`Model ${modelId} not found, trying fallback.`, "info");
         continue;
       }
 
+      if (policyAllowedModelKeys) {
+        const key = `${model.provider.toLowerCase()}/${model.id.toLowerCase()}`;
+        if (!policyAllowedModelKeys.has(key)) {
+          if (verbose) {
+            ctx.ui.notify(`Model policy denied ${model.provider}/${model.id}; trying fallback.`, "warning");
+          }
+          continue;
+        }
+        attemptedPolicyEligible = true;
+      }
+
       // Warn if the ID is ambiguous across providers
       if (!modelId.includes("/")) {
         const providers = availableModels.filter(m => m.id === modelId).map(m => m.provider);
@@ -317,6 +388,10 @@ export async function selectAndApplyModel(
         }
       }
     }
+
+    if (uokFlags.modelPolicy && policyAllowedModelKeys && !attemptedPolicyEligible) {
+      throw new Error(`Model policy denied dispatch for ${unitType}/${unitId} before prompt send`);
+    }
   } else if (autoModeStartModel) {
     // No model preference for this unit type — re-apply the model captured
     // at auto-mode start to prevent bleed from shared global settings.json (#650).
@@ -416,8 +491,68 @@ export function resolveModelId<T extends { id: string; provider: string }>(
  * Uses case-insensitive matching with alias support to prevent fail-open on
  * provider naming variations (e.g. "copilot" vs "github-copilot").
  */
-const FLAT_RATE_PROVIDERS = new Set(["github-copilot", "copilot", "claude-code"]);
+const BUILTIN_FLAT_RATE = new Set(["github-copilot", "copilot", "claude-code"]);
 
-export function isFlatRateProvider(provider: string): boolean {
-  return FLAT_RATE_PROVIDERS.has(provider.toLowerCase());
+/**
+ * Optional context that lets callers extend flat-rate detection beyond the
+ * hard-coded built-in list.  Either signal on its own is enough to classify
+ * a provider as flat-rate.
+ */
+export interface FlatRateContext {
+  /**
+   * Auth mode for the specific provider being checked, as returned by
+   * `ctx.modelRegistry.getProviderAuthMode(provider)`.  Any provider that
+   * wraps a local CLI (externalCli) is, by definition, a flat-rate
+   * subscription wrapper — every request costs the same regardless of
+   * model, so dynamic routing only degrades quality.
+   */
+  authMode?: "apiKey" | "oauth" | "externalCli" | "none";
+  /**
+   * Case-insensitive list of extra provider IDs the user has declared as
+   * flat-rate via `preferences.flat_rate_providers`.  Used for private
+   * subscription-backed proxies and enterprise-gated deployments that the
+   * built-in list doesn't know about.
+   */
+  userFlatRate?: readonly string[];
+}
+
+export function isFlatRateProvider(provider: string, opts?: FlatRateContext): boolean {
+  const p = provider.toLowerCase();
+  if (BUILTIN_FLAT_RATE.has(p)) return true;
+  if (opts?.userFlatRate?.some(id => id.toLowerCase() === p)) return true;
+  if (opts?.authMode === "externalCli") return true;
+  return false;
+}
+
+/**
+ * Build a FlatRateContext for a given provider from live runtime state.
+ * Safe to call when ctx or prefs are undefined — missing pieces are
+ * treated as "no signal".
+ */
+export function buildFlatRateContext(
+  provider: string,
+  ctx?: { modelRegistry?: { getProviderAuthMode?: (p: string) => string } },
+  prefs?: { flat_rate_providers?: readonly string[] },
+): FlatRateContext {
+  let authMode: FlatRateContext["authMode"];
+  const getAuthMode = ctx?.modelRegistry?.getProviderAuthMode;
+  if (typeof getAuthMode === "function") {
+    try {
+      const mode = getAuthMode(provider);
+      if (mode === "apiKey" || mode === "oauth" || mode === "externalCli" || mode === "none") {
+        authMode = mode;
+      }
+    } catch (err) {
+      // Registry lookup failure must never break flat-rate detection —
+      // fall through with authMode undefined and surface the cause.
+      logWarning(
+        "dispatch",
+        `flat-rate auth-mode lookup failed for ${provider}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  return {
+    authMode,
+    userFlatRate: prefs?.flat_rate_providers,
+  };
 }

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -29,9 +29,10 @@ import { rebuildState } from "./doctor.js";
 import { parseUnitId } from "./unit-id.js";
 import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
 import {
-  autoCommitCurrentBranch,
+  runTurnGitAction,
   type TaskCommitContext,
-} from "./worktree.js";
+  type TurnGitActionMode,
+} from "./git-service.js";
 import {
   verifyExpectedArtifact,
   resolveExpectedArtifactPath,
@@ -66,6 +67,9 @@ import { getSliceTasks } from "./gsd-db.js";
 import { runPreExecutionChecks, type PreExecutionResult } from "./pre-execution-checks.js";
 import { writePreExecutionEvidence } from "./verification-evidence.js";
 import { ensureCodebaseMapFresh } from "./codebase-generator.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { UokGateRunner } from "./uok/gate-runner.js";
+import { writeTurnGitTransaction } from "./uok/gitops.js";
 
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
@@ -104,10 +108,12 @@ import {
   updateSliceProgressCache,
   unitVerb,
   hideFooter,
+  describeNextUnit,
 } from "./auto-dashboard.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { _resetHasChangesCache } from "./native-git-bridge.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
 
 // ─── Rogue File Detection ──────────────────────────────────────────────────
 
@@ -233,6 +239,18 @@ export function detectRogueFileWrites(
   return rogues;
 }
 
+export const STEP_COMPLETE_FALLBACK_MESSAGE =
+  "Step complete. Run /clear, then /gsd to continue (or /gsd auto to run continuously).";
+
+export function buildStepCompleteMessage(nextState: import("./types.js").GSDState): string {
+  if (nextState.phase === "complete") {
+    return "Step complete — milestone finished. Run /gsd status to review, or start the next milestone.";
+  }
+  const next = describeNextUnit(nextState);
+  return `Step complete. Next: ${next.label}\n`
+    + `Run /clear, then /gsd to continue (or /gsd auto to run continuously).`;
+}
+
 export interface PreVerificationOpts {
   skipSettleDelay?: boolean;
   skipWorktreeSync?: boolean;
@@ -249,6 +267,65 @@ export interface PostUnitContext {
   updateProgressWidget: (ctx: ExtensionContext, unitType: string, unitId: string, state: import("./types.js").GSDState) => void;
 }
 
+export async function autoCommitUnit(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  ctx?: ExtensionContext,
+): Promise<string | null> {
+  try {
+    let taskContext: TaskCommitContext | undefined;
+
+    if (unitType === "execute-task") {
+      const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+      if (mid && sid && tid) {
+        const summaryPath = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+        if (summaryPath) {
+          try {
+            const summaryContent = await loadFile(summaryPath);
+            if (summaryContent) {
+              const summary = parseSummary(summaryContent);
+              let ghIssueNumber: number | undefined;
+              try {
+                const { getTaskIssueNumberForCommit } = await import("../github-sync/sync.js");
+                ghIssueNumber = getTaskIssueNumberForCommit(basePath, mid, sid, tid) ?? undefined;
+              } catch (err) {
+                logWarning("engine", `GitHub issue lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+              }
+
+              taskContext = {
+                taskId: `${sid}/${tid}`,
+                taskTitle: summary.title?.replace(/^T\d+:\s*/, "") || tid,
+                oneLiner: summary.oneLiner || undefined,
+                keyFiles: summary.frontmatter.key_files?.filter(f => !f.includes("{{")) || undefined,
+                issueNumber: ghIssueNumber,
+              };
+            }
+          } catch (e) {
+            debugLog("postUnit", { phase: "task-summary-parse", error: String(e) });
+          }
+        }
+      }
+    }
+
+    _resetHasChangesCache();
+
+    if (LIFECYCLE_ONLY_UNITS.has(unitType)) {
+      return null;
+    }
+
+    const commitMsg = autoCommitCurrentBranch(basePath, unitType, unitId, taskContext);
+    if (commitMsg) {
+      ctx?.ui.notify(`Committed: ${commitMsg.split("\n")[0]}`, "info");
+    }
+    return commitMsg;
+  } catch (e) {
+    debugLog("postUnit", { phase: "auto-commit", error: String(e) });
+    ctx?.ui.notify(`Auto-commit failed: ${String(e).split("\n")[0]}`, "warning");
+    return null;
+  }
+}
+
 /**
  * Pre-verification processing: parallel worker signal check, cache invalidation,
  * auto-commit, doctor run, state rebuild, worktree sync, artifact verification.
@@ -285,13 +362,21 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
     await new Promise(r => setTimeout(r, 100));
   }
 
-  // Auto-commit
+  const prefs = loadEffectiveGSDPreferences()?.preferences;
+  const uokFlags = resolveUokFlags(prefs);
+
+  // Turn-level git action (commit | snapshot | status-only)
   if (s.currentUnit) {
     const unit = s.currentUnit;
+    const turnAction: TurnGitActionMode = uokFlags.gitops ? uokFlags.gitopsTurnAction : "commit";
+    const traceId = s.currentTraceId ?? `turn:${unit.startedAt}`;
+    const turnId = s.currentTurnId ?? `${unit.type}/${unit.id}/${unit.startedAt}`;
+    s.lastGitActionFailure = null;
+    s.lastGitActionStatus = null;
     try {
       let taskContext: TaskCommitContext | undefined;
 
-      if (s.currentUnit.type === "execute-task") {
+      if (turnAction === "commit" && s.currentUnit.type === "execute-task") {
         const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         if (mid && sid && tid) {
           const summaryPath = resolveTaskFile(s.basePath, mid, sid, tid, "SUMMARY");
@@ -332,18 +417,105 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       // `git worktree remove --force` during teardown.
       _resetHasChangesCache();
 
-      // Skip auto-commit for lifecycle-only units (#2553) — they only touch
-      // `.gsd/` internal state files. Those files are picked up by the next
-      // actual task commit via smartStage().
-      if (!LIFECYCLE_ONLY_UNITS.has(s.currentUnit.type)) {
-        const commitMsg = autoCommitCurrentBranch(s.basePath, s.currentUnit.type, s.currentUnit.id, taskContext);
-        if (commitMsg) {
-          ctx.ui.notify(`Committed: ${commitMsg.split("\n")[0]}`, "info");
+      const skipLifecycleCommit =
+        turnAction === "commit" && LIFECYCLE_ONLY_UNITS.has(s.currentUnit.type);
+
+      if (skipLifecycleCommit) {
+        debugLog("postUnit", {
+          phase: "git-action-skipped",
+          reason: "lifecycle-only-unit",
+          unitType: s.currentUnit.type,
+          unitId: s.currentUnit.id,
+        });
+      } else {
+        const gitResult = runTurnGitAction({
+          basePath: s.basePath,
+          action: turnAction,
+          unitType: s.currentUnit.type,
+          unitId: s.currentUnit.id,
+          taskContext,
+        });
+
+        if (uokFlags.gitops) {
+          writeTurnGitTransaction({
+            basePath: s.basePath,
+            traceId,
+            turnId,
+            unitType: unit.type,
+            unitId: unit.id,
+            stage: "publish",
+            action: turnAction,
+            push: uokFlags.gitopsTurnPush,
+            status: gitResult.status,
+            error: gitResult.error,
+            metadata: {
+              dirty: gitResult.dirty,
+              commitMessage: gitResult.commitMessage,
+              snapshotLabel: gitResult.snapshotLabel,
+            },
+          });
+        }
+
+        if (gitResult.status === "failed") {
+          s.lastGitActionFailure = gitResult.error ?? `git ${turnAction} failed`;
+          s.lastGitActionStatus = "failed";
+          if (uokFlags.gitops && uokFlags.gates) {
+            const parsed = parseUnitId(unit.id);
+            const gateRunner = new UokGateRunner();
+            gateRunner.register({
+              id: "closeout-git-action",
+              type: "closeout",
+              execute: async () => ({
+                outcome: "fail",
+                failureClass: "git",
+                rationale: `turn git action "${turnAction}" failed`,
+                findings: gitResult.error ?? "unknown git failure",
+              }),
+            });
+            await gateRunner.run("closeout-git-action", {
+              basePath: s.basePath,
+              traceId,
+              turnId,
+              milestoneId: parsed.milestone ?? undefined,
+              sliceId: parsed.slice ?? undefined,
+              taskId: parsed.task ?? undefined,
+              unitType: unit.type,
+              unitId: unit.id,
+            });
+          }
+
+          const failureMsg = `Git ${turnAction} failed: ${(gitResult.error ?? "unknown error").split("\n")[0]}`;
+          if (uokFlags.gitops) {
+            ctx.ui.notify(failureMsg, "error");
+            await pauseAuto(ctx, pi);
+            return "dispatched";
+          }
+          ctx.ui.notify(failureMsg, "warning");
+          debugLog("postUnit", {
+            phase: "git-action-failed-nonblocking",
+            action: turnAction,
+            error: gitResult.error ?? "unknown error",
+          });
+        }
+
+        s.lastGitActionStatus = "ok";
+
+        if (turnAction === "commit" && gitResult.commitMessage) {
+          ctx.ui.notify(`Committed: ${gitResult.commitMessage.split("\n")[0]}`, "info");
+        } else if (turnAction === "snapshot" && gitResult.snapshotLabel) {
+          ctx.ui.notify(`Snapshot recorded: ${gitResult.snapshotLabel}`, "info");
         }
       }
     } catch (e) {
-      debugLog("postUnit", { phase: "auto-commit", error: String(e) });
-      ctx.ui.notify(`Auto-commit failed: ${String(e).split("\n")[0]}`, "warning");
+      const message = e instanceof Error ? e.message : String(e);
+      s.lastGitActionFailure = message;
+      s.lastGitActionStatus = "failed";
+      debugLog("postUnit", { phase: "git-action", error: message, action: turnAction });
+      ctx.ui.notify(`Git ${turnAction} failed: ${message.split("\n")[0]}`, uokFlags.gitops ? "error" : "warning");
+      if (uokFlags.gitops) {
+        await pauseAuto(ctx, pi);
+        return "dispatched";
+      }
     }
 
     // GitHub sync (non-blocking, opt-in)
@@ -619,6 +791,30 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           s.verificationRetryCount.set(retryKey, attempt);
 
           if (attempt > MAX_VERIFICATION_RETRIES) {
+            // #4175: For complete-milestone, a blocker placeholder is harmful —
+            // the stub SUMMARY has no recovery value (milestone is terminal),
+            // it does not update DB status (so deriveState never advances),
+            // and it fools stopAuto's presence check into merging a milestone
+            // that was never legitimately completed. Pause auto-mode with a
+            // clear single failure signal and preserve the worktree branch.
+            if (s.currentUnit.type === "complete-milestone") {
+              debugLog("postUnit", {
+                phase: "artifact-verify-pause-complete-milestone",
+                unitType: s.currentUnit.type,
+                unitId: s.currentUnit.id,
+                attempt,
+                maxRetries: MAX_VERIFICATION_RETRIES,
+              });
+              s.verificationRetryCount.delete(retryKey);
+              s.pendingVerificationRetry = null;
+              ctx.ui.notify(
+                `Milestone ${s.currentUnit.id} verification failed after ${MAX_VERIFICATION_RETRIES} retries — worktree branch preserved. Re-run /gsd auto once blockers are resolved.`,
+                "error",
+              );
+              await pauseAuto(ctx, pi);
+              return "dispatched";
+            }
+
             // Retries exhausted — write a blocker placeholder so the pipeline
             // can advance past this stuck unit (#2653).
             debugLog("postUnit", {
@@ -829,11 +1025,13 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
     s.currentUnit &&
     s.currentUnit.type === "plan-slice"
   ) {
+    const currentUnit = s.currentUnit;
     let preExecPauseNeeded = false;
     await runSafely("postUnitPostVerification", "pre-execution-checks", async () => {
+      const prefs = loadEffectiveGSDPreferences()?.preferences;
+      const uokFlags = resolveUokFlags(prefs);
       try {
         // Check preferences — respect enhanced_verification and enhanced_verification_pre
-        const prefs = loadEffectiveGSDPreferences()?.preferences;
         const enhancedEnabled = prefs?.enhanced_verification !== false; // default true
         const preEnabled = prefs?.enhanced_verification_pre !== false;  // default true
 
@@ -847,7 +1045,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
         }
 
         // Parse the unit ID to get milestone/slice IDs
-        const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit!.id);
+        const { milestone: mid, slice: sid } = parseUnitId(currentUnit.id);
         if (!mid || !sid) {
           debugLog("postUnitPostVerification", {
             phase: "pre-execution-checks",
@@ -868,6 +1066,8 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
           return;
         }
 
+        const strictMode = prefs?.enhanced_verification_strict === true;
+
         // Run pre-execution checks
         const result: PreExecutionResult = await runPreExecutionChecks(tasks, s.basePath);
 
@@ -891,6 +1091,36 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
           writePreExecutionEvidence(result, slicePath, mid, sid);
         }
 
+        if (uokFlags.gates) {
+          const failedChecks = result.checks
+            .filter((check) => !check.passed)
+            .map((check) => `[${check.category}] ${check.target}: ${check.message}`);
+          const warnEscalated = result.status === "warn" && strictMode;
+          const blockingFailure = result.status === "fail" || warnEscalated;
+          const gateRunner = new UokGateRunner();
+          gateRunner.register({
+            id: "pre-execution-checks",
+            type: "input",
+            execute: async () => ({
+              outcome: blockingFailure ? "fail" : "pass",
+              failureClass: result.status === "fail" ? "input" : warnEscalated ? "policy" : "none",
+              rationale: blockingFailure
+                ? `pre-execution checks ${result.status}${warnEscalated ? " (strict)" : ""}`
+                : "pre-execution checks passed",
+              findings: failedChecks.join("\n"),
+            }),
+          });
+          await gateRunner.run("pre-execution-checks", {
+            basePath: s.basePath,
+            traceId: `pre-execution:${currentUnit.id}`,
+            turnId: currentUnit.id,
+            milestoneId: mid,
+            sliceId: sid,
+            unitType: currentUnit.type,
+            unitId: currentUnit.id,
+          });
+        }
+
         // Notify UI
         if (result.status === "fail") {
           const blockingCount = result.checks.filter(c => !c.passed && c.blocking).length;
@@ -929,6 +1159,29 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
           `Pre-execution checks error: ${errorMessage} — pausing for human review`,
           "error",
         );
+        if (uokFlags.gates && s.currentUnit) {
+          const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
+          const gateRunner = new UokGateRunner();
+          gateRunner.register({
+            id: "pre-execution-checks",
+            type: "input",
+            execute: async () => ({
+              outcome: "manual-attention",
+              failureClass: "manual-attention",
+              rationale: "pre-execution checks threw before completion",
+              findings: errorMessage,
+            }),
+          });
+          await gateRunner.run("pre-execution-checks", {
+            basePath: s.basePath,
+            traceId: `pre-execution:${s.currentUnit.id}`,
+            turnId: s.currentUnit.id,
+            milestoneId: mid ?? undefined,
+            sliceId: sid ?? undefined,
+            unitType: s.currentUnit.type,
+            unitId: s.currentUnit.id,
+          });
+        }
         preExecPauseNeeded = true;
       }
     });
@@ -1025,8 +1278,17 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
     }
   }
 
-  // Step mode → show wizard instead of dispatch
+  // Step mode → show wizard instead of dispatch.
+  // Without this notify(), /gsd in step mode finishes a unit and silently
+  // exits the loop, leaving the user with no hint to /clear and /gsd again.
   if (s.stepMode) {
+    try {
+      const nextState = await deriveState(s.basePath);
+      ctx.ui.notify(buildStepCompleteMessage(nextState), "info");
+    } catch (e) {
+      debugLog("postUnit", { phase: "step-wizard-notify", error: String(e) });
+      ctx.ui.notify(STEP_COMPLETE_FALLBACK_MESSAGE, "info");
+    }
     return "step-wizard";
   }