gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

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

@@ -12,8 +12,10 @@
 import type { GSDState } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
 import type { UatType } from "./files.js";
+import type { MinimalModelRegistry } from "./context-budget.js";
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
-import { isDbAvailable, getMilestoneSlices, getPendingGates, markAllGatesOmitted, getMilestone } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getPendingGates, markAllGatesOmitted, getMilestone, updateMilestoneStatus } from "./gsd-db.js";
+import { isClosedStatus } from "./status-guards.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 
 import {
@@ -38,6 +40,7 @@ import {
   buildPlanMilestonePrompt,
   buildResearchSlicePrompt,
   buildPlanSlicePrompt,
+  buildRefineSlicePrompt,
   buildExecuteTaskPrompt,
   buildCompleteSlicePrompt,
   buildCompleteMilestonePrompt,
@@ -78,6 +81,11 @@ export interface DispatchContext {
   state: GSDState;
   prefs: GSDPreferences | undefined;
   session?: import("./auto/session.js").AutoSession;
+  structuredQuestionsAvailable?: "true" | "false";
+  /** Session model context window in tokens, forwarded to the budget engine's prompt builders. */
+  sessionContextWindow?: number;
+  /** Model registry forwarded to the budget engine so it can look up the configured executor model. */
+  modelRegistry?: MinimalModelRegistry;
 }
 
 export interface DispatchRule {
@@ -187,6 +195,25 @@ export function isVerificationNotApplicable(value: string): boolean {
 // ─── Rules ────────────────────────────────────────────────────────────────
 
 export const DISPATCH_RULES: DispatchRule[] = [
+  {
+    // ADR-011 Phase 2: pause-for-escalation must evaluate FIRST so phase-
+    // agnostic rules (rewrite-docs gate, UAT checks, reassess) cannot bypass
+    // the user's pending decision. Only fires for continueWithDefault=false
+    // escalations (those set escalation_pending=1); awaiting-review artifacts
+    // never enter the 'escalating-task' phase.
+    name: "escalating-task → pause-for-escalation",
+    match: async ({ state, mid }) => {
+      if (state.phase !== "escalating-task") return null;
+      if (!state.activeSlice) return missingSliceStop(mid, state.phase);
+      return {
+        action: "stop",
+        reason:
+          state.nextAction ||
+          `${mid}: task escalation awaits user resolution. Run /gsd escalate list to see pending items.`,
+        level: "info",
+      };
+    },
+  },
   {
     name: "rewrite-docs (override gate)",
     match: async ({ mid, midTitle, state, basePath, session }) => {
@@ -331,19 +358,24 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "needs-discussion → discuss-milestone",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
       if (state.phase !== "needs-discussion") return null;
       return {
         action: "dispatch",
         unitType: "discuss-milestone",
         unitId: mid,
-        prompt: await buildDiscussMilestonePrompt(mid, midTitle, basePath),
+        prompt: await buildDiscussMilestonePrompt(
+          mid,
+          midTitle,
+          basePath,
+          structuredQuestionsAvailable,
+        ),
       };
     },
   },
   {
     name: "pre-planning (no context) → discuss-milestone",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
       if (state.phase !== "pre-planning") return null;
       const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
       const hasContext = !!(contextFile && (await loadFile(contextFile)));
@@ -352,7 +384,12 @@ export const DISPATCH_RULES: DispatchRule[] = [
         action: "dispatch",
         unitType: "discuss-milestone",
         unitId: mid,
-        prompt: await buildDiscussMilestonePrompt(mid, midTitle, basePath),
+        prompt: await buildDiscussMilestonePrompt(
+          mid,
+          midTitle,
+          basePath,
+          structuredQuestionsAvailable,
+        ),
       };
     },
   },
@@ -420,6 +457,12 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // Only dispatch parallel if 2+ slices are ready
       if (researchReadySlices.length < 2) return null;
 
+      // #4414: If a previous parallel-research attempt escalated to a blocker
+      // placeholder, skip this rule and fall through to per-slice research
+      // (or other rules) rather than re-dispatching the same failing unit.
+      const parallelBlocker = resolveMilestoneFile(basePath, mid, "PARALLEL-BLOCKER");
+      if (parallelBlocker) return null;
+
       return {
         action: "dispatch",
         unitType: "research-slice",
@@ -468,9 +511,64 @@ export const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    // ADR-011: sketch-then-refine. When `refining` phase fires, expand the
+    // sketch into a full plan using the prior slice's SUMMARY and the current
+    // codebase. If the user flipped `progressive_planning` off mid-milestone
+    // while a slice is still `is_sketch=1`, fall through to a standard
+    // plan-slice so the loop doesn't dead-end.
+    //
+    // Note on the flag-OFF downgrade: plan-slice does not explicitly clear
+    // `is_sketch`. After it writes PLAN.md, the auto-heal in state.ts's
+    // `deriveStateFromDb` (via `autoHealSketchFlags`) flips the flag on the
+    // next iteration. That implicit coupling is the sole mechanism that
+    // reconciles `is_sketch=1` on the plan-slice path — do not remove the
+    // auto-heal without either adding an explicit `setSliceSketchFlag(..., false)`
+    // call here or doing so inside the plan-slice tool handler.
+    name: "refining → refine-slice",
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
+      if (state.phase !== "refining") return null;
+      if (!state.activeSlice) return missingSliceStop(mid, state.phase);
+      const sid = state.activeSlice.id;
+      const sTitle = state.activeSlice.title;
+      const progressiveOn = prefs?.phases?.progressive_planning === true;
+      if (!progressiveOn) {
+        // Graceful downgrade: treat the sketch as a normal slice needing a plan,
+        // but forward the stored sketch_scope as a SOFT hint so the scope
+        // signal isn't silently lost. The planner may expand beyond it.
+        let softScopeHint = "";
+        try {
+          const { isDbAvailable, getSlice } = await import("./gsd-db.js");
+          if (isDbAvailable()) {
+            softScopeHint = getSlice(mid, sid)?.sketch_scope ?? "";
+          }
+        } catch {
+          softScopeHint = "";
+        }
+        return {
+          action: "dispatch",
+          unitType: "plan-slice",
+          unitId: `${mid}/${sid}`,
+          prompt: await buildPlanSlicePrompt(
+            mid, midTitle, sid, sTitle, basePath, undefined,
+            { ...(softScopeHint ? { softScopeHint } : {}), sessionContextWindow, modelRegistry },
+          ),
+        };
+      }
+      return {
+        action: "dispatch",
+        unitType: "refine-slice",
+        unitId: `${mid}/${sid}`,
+        prompt: await buildRefineSlicePrompt(
+          mid, midTitle, sid, sTitle, basePath, undefined,
+          { sessionContextWindow, modelRegistry },
+        ),
+      };
+    },
+  },
   {
     name: "planning → plan-slice",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "planning") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -485,6 +583,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
           sid,
           sTitle,
           basePath,
+          undefined,
+          { sessionContextWindow, modelRegistry },
         ),
       };
     },
@@ -545,7 +645,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → reactive-execute (parallel dispatch)",
-    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return null; // fall through
 
@@ -636,6 +736,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
             selected,
             basePath,
             subagentModel,
+            { sessionContextWindow, modelRegistry },
           ),
         };
       } catch (err) {
@@ -647,7 +748,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task (recover missing task plan → plan-slice)",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -671,6 +772,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
             sid,
             sTitle,
             basePath,
+            undefined,
+            { sessionContextWindow, modelRegistry },
           ),
         };
       }
@@ -680,7 +783,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task",
-    match: async ({ state, mid, basePath }) => {
+    match: async ({ state, mid, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -699,6 +802,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           tid,
           tTitle,
           basePath,
+          { sessionContextWindow, modelRegistry },
         ),
       };
     },
@@ -755,6 +859,34 @@ export const DISPATCH_RULES: DispatchRule[] = [
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "completing-milestone") return null;
 
+      // Defense-in-depth (#4324): skip dispatch if the DB already marks
+      // this milestone as complete. Prevents re-enqueue when the legacy
+      // filesystem state-derivation path runs (e.g. transient DB
+      // unavailability) and produces a stale completing-milestone phase.
+      if (isDbAvailable()) {
+        const milestone = getMilestone(mid);
+        if (milestone && isClosedStatus(milestone.status)) {
+          return { action: "skip" };
+        }
+      }
+
+      // Reconciliation guard (#4324): when the SUMMARY file already exists
+      // on disk but the DB says the milestone is not complete, the DB is
+      // out of sync (e.g. journal reset, partial merge, crash recovery).
+      // Reconcile the DB status directly instead of re-dispatching the
+      // tool, which would overwrite the richer on-disk SUMMARY with a
+      // thinner regenerated version — causing silent data loss.
+      const existingSummary = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (existingSummary && isDbAvailable()) {
+        try {
+          updateMilestoneStatus(mid, "complete", new Date().toISOString());
+          logWarning("dispatch", `Milestone ${mid} has SUMMARY on disk but DB status was not complete — reconciled DB to complete (#4324)`);
+        } catch (err) {
+          logWarning("dispatch", `Failed to reconcile milestone ${mid} status: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { action: "skip" };
+      }
+
       // Safety guard (#2675): block completion when VALIDATION verdict is
       // needs-remediation. The state machine treats needs-remediation as
       // terminal (to prevent validate-milestone loops per #832), but

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

@@ -7,7 +7,7 @@
  * continue to work without changes.
  */
 
-export { autoLoop } from "./auto/loop.js";
+export { autoLoop, runUokKernelLoop, runLegacyAutoLoop } from "./auto/loop.js";
 export { isInfrastructureError, INFRA_ERROR_CODES } from "./auto/infra-errors.js";
 export { resolveAgentEnd, resolveAgentEndCancelled, isSessionSwitchInFlight, _resetPendingResolve, _setActiveSession } from "./auto/resolve.js";
 export { detectStuck } from "./auto/detect-stuck.js";

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

@@ -26,13 +26,24 @@ export interface ModelSelectionResult {
   appliedModel: Model<Api> | null;
 }
 
+export interface PreferredModelConfig {
+  primary: string;
+  fallbacks: string[];
+  source: "explicit" | "synthesized";
+}
+
 export function resolvePreferredModelConfig(
   unitType: string,
   autoModeStartModel: { provider: string; id: string; flatRateCtx?: FlatRateContext } | null,
   isAutoMode = true,
-) {
+): PreferredModelConfig | undefined {
   const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
-  if (explicitConfig) return explicitConfig;
+  if (explicitConfig) {
+    return {
+      ...explicitConfig,
+      source: "explicit",
+    };
+  }
 
   // In interactive mode, don't synthesize a routing-based model config.
   // The user's session model (/model) should be used as-is (#3962).
@@ -42,7 +53,15 @@ 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, autoModeStartModel.flatRateCtx)) return undefined;
+  // Users can opt into routing for flat-rate subscriptions (e.g. claude-code)
+  // via dynamic_routing.allow_flat_rate_providers (#4386).
+  if (
+    !routingConfig.allow_flat_rate_providers &&
+    autoModeStartModel &&
+    isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx)
+  ) {
+    return undefined;
+  }
 
   const ceilingModel = routingConfig.tier_models.heavy
     ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
@@ -51,6 +70,7 @@ export function resolvePreferredModelConfig(
   return {
     primary: ceilingModel,
     fallbacks: [],
+    source: "synthesized",
   };
 }
 
@@ -116,6 +136,11 @@ export async function selectAndApplyModel(
     if (prefs?.token_profile === "burn-max") {
       routingConfig.enabled = false;
     }
+    if (modelConfig.source === "explicit") {
+      // Explicit per-phase model preferences express hard user intent.
+      // Dynamic routing may only treat synthesized tier ceilings as downgradeable.
+      routingConfig.enabled = false;
+    }
     let effectiveModelConfig = modelConfig;
     let routingTierLabel = "";
     let routingEligibleModels = availableModels;
@@ -152,7 +177,10 @@ export async function selectAndApplyModel(
     // model provides no cost benefit — it only degrades quality.
     // Fail-closed: if primary model can't be resolved, fall back to
     // provider-level signals rather than allowing unwanted downgrades.
-    if (routingConfig.enabled) {
+    // Opt-in: dynamic_routing.allow_flat_rate_providers skips the bypass so
+    // claude-code subscribers can still get intelligent per-task selection
+    // across their subscription (#4386).
+    if (routingConfig.enabled && !routingConfig.allow_flat_rate_providers) {
       const primaryModel = resolveModelId(modelConfig.primary, routingEligibleModels, ctx.model?.provider);
       if (primaryModel) {
         const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);
@@ -194,7 +222,7 @@ export async function selectAndApplyModel(
           budgetPct,
           taskMetadataForPolicy,
         );
-        const availableModelIds = routingEligibleModels.map(m => m.id);
+        const availableModelIds = routingEligibleModels.map(m => `${m.provider}/${m.id}`);
 
         // Escalate tier on retry when escalate_on_failure is enabled (default: true)
         if (
@@ -275,6 +303,7 @@ export async function selectAndApplyModel(
           effectiveModelConfig = {
             primary: routingResult.modelId,
             fallbacks: routingResult.fallbacks,
+            source: modelConfig.source,
           };
           // Always notify on model downgrade — users should see when their
           // model selection is overridden, not just in verbose mode (#3962).
@@ -477,7 +506,9 @@ export function resolveModelId<T extends { id: string; provider: string }>(
     if (providerMatch) return providerMatch;
   }
 
-  // Prefer "anthropic" as the canonical provider for Anthropic models
+  // Prefer "anthropic" as the canonical provider for Anthropic models.
+  // Transport-specific tiebreaker (ADR-012): intentionally keys on provider,
+  // not api — we want the plain Anthropic transport when multiple are available.
   const anthropicMatch = candidates.find(m => m.provider === "anthropic");
   if (anthropicMatch) return anthropicMatch;
 

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

@@ -1,14 +1,14 @@
 /**
- * Post-unit processing for handleAgentEnd — auto-commit, doctor run,
+ * Post-unit processing for auto-loop — auto-commit, doctor run,
  * state rebuild, worktree sync, DB dual-write, hooks, triage, and
  * quick-task dispatch.
  *
- * Split into two functions called sequentially by handleAgentEnd with
+ * Split into two functions called sequentially by auto-loop with
  * the verification gate between them:
  *   1. postUnitPreVerification() — commit, doctor, state rebuild, worktree sync, artifact verification
  *   2. postUnitPostVerification() — DB dual-write, hooks, triage, quick-tasks
  *
- * Extracted from handleAgentEnd() in auto.ts.
+ * Extracted from the pre-loop agent_end handler in auto.ts.
  */
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
@@ -99,7 +99,7 @@ function enqueueSidecar(
  *  next actual task commit via `smartStage()`. */
 const LIFECYCLE_ONLY_UNITS = new Set([
   "research-milestone", "discuss-milestone", "discuss-slice", "plan-milestone",
-  "validate-milestone", "research-slice", "plan-slice",
+  "validate-milestone", "research-slice", "plan-slice", "refine-slice",
   "replan-slice", "complete-slice", "run-uat",
   "reassess-roadmap", "rewrite-docs",
 ]);
@@ -190,7 +190,7 @@ export function detectRogueFileWrites(
     if (!hasPlanningState) {
       rogues.push({ path: roadmapPath, unitType, unitId });
     }
-  } else if (unitType === "plan-slice" || unitType === "replan-slice") {
+  } else if (unitType === "plan-slice" || unitType === "refine-slice" || unitType === "replan-slice") {
     if (!mid || !sid) return [];
 
     const planPath = resolveSliceFile(basePath, mid, sid, "PLAN");
@@ -735,7 +735,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         try {
           const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
           if (mid && sid) {
-            const regenerated = regenerateIfMissing(s.basePath, mid, sid, "PLAN");
+            const regenerated = await regenerateIfMissing(s.basePath, mid, sid, "PLAN");
             if (regenerated) {
               // Re-check after regeneration
               triggerArtifactVerified = verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
@@ -1020,10 +1020,12 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
     }
   }
 
-  // ── Pre-execution checks (after plan-slice completes) ──
+  // ── Pre-execution checks (after plan-slice or ADR-011 refine-slice completes) ──
+  // Both emit the same PLAN.md + task artifacts via gsd_plan_slice, so the
+  // same structural validation applies to both.
   if (
     s.currentUnit &&
-    s.currentUnit.type === "plan-slice"
+    (s.currentUnit.type === "plan-slice" || s.currentUnit.type === "refine-slice")
   ) {
     const currentUnit = s.currentUnit;
     let preExecPauseNeeded = false;