gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.2203010a0

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -78,6 +78,18 @@ Apply these when decomposing and ordering slices:
 - **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
 - **Right-size the decomposition.** Match slice count to actual complexity. If the work is small enough to build and verify in one pass, it's one slice — don't split it into three just because you can identify sub-steps. Multiple requirements can share a single slice. Conversely, don't cram genuinely independent capabilities into one slice just to keep the count low. Let the work dictate the structure.
 
+## Progressive Planning (ADR-011)
+
+If the preference `phases.progressive_planning` is enabled and the roadmap has **2 or more slices**, you SHOULD plan S01 in full detail and S02+ as sketches. Plan S02+ full only when the slice is trivially determined (pure boilerplate that cannot meaningfully change based on what S01 ships).
+
+A **sketch slice** has the same roadmap entry as today (title, risk, depends, demo line) plus a `sketchScope` of 2–3 sentences describing the scope boundary. Do NOT attempt to decompose it into tasks during this unit — provide a one-sentence `goal` (the tool schema requires it; keep it at the same level of detail as the roadmap demo line) and leave `successCriteria`, `proofLevel`, `integrationClosure`, `observabilityImpact` blank (or provide them if genuinely known). When the prior slice completes, a separate `refine-slice` unit will expand the sketch into a full plan using the real codebase state and the prior slice SUMMARY.
+
+**To mark a slice as a sketch in the `gsd_plan_milestone` tool call:** set `isSketch: true` and `sketchScope: "<2-3 sentence scope>"` on that slice entry.
+
+S01 is never a sketch — it must always be fully decomposed in this unit.
+
+If the preference is off, ignore this section and plan every slice in full detail as you would normally.
+
 ## Single-Slice Fast Path
 
 If the roadmap has only one slice, also plan the slice and its tasks inline during this unit — don't leave them for a separate planning session.

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -0,0 +1,69 @@
+You are executing GSD auto-mode.
+
+## UNIT: Refine Slice {{sliceId}} ("{{sliceTitle}}") — Milestone {{milestoneId}}
+
+## Working Directory
+
+Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
+This unit **expands an approved sketch into a full plan**. It is not a blank-sheet planning pass — the sketch's scope is the authoritative boundary, and the prior slice's real outcomes are the authoritative context. Your job is to produce a detailed plan that fits inside the sketch while reflecting what actually shipped in earlier slices.
+
+All relevant context has been preloaded below — start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+### Dependency Slice Summaries
+
+Pay particular attention to **Forward Intelligence** sections — they contain hard-won knowledge about what's fragile, what assumptions changed, and what this slice should watch out for. These summaries are the single most important input to refinement: the sketch was written before these slices shipped, so your plan MUST reconcile against what they actually built.
+
+{{dependencySummaries}}
+
+## Your Role in the Pipeline
+
+### Respect the Sketch Scope
+
+The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.
+
+### Reconcile Against Reality
+
+Before decomposing:
+
+1. Read the prior slice SUMMARY files that were inlined above. Note any interface shifts, file-layout changes, or discovered constraints.
+2. Use `rg`, `find`, and targeted reads to confirm the current codebase state for files the sketch references. If an assumed module/type/API has moved or changed shape, your plan must reflect that.
+3. If prior slices flagged fragility or known issues relevant to this slice, fold them into task verification.
+
+### Source Files
+
+{{sourceFilePaths}}
+
+If slice research exists (inlined above), trust those findings and skip redundant exploration.
+
+After you finish, **executor agents** implement each task in isolated fresh context windows. They see only their task plan, the slice plan excerpt, and compressed summaries of prior tasks. Everything an executor needs must be in the task plan itself — file paths, specific steps, expected inputs and outputs.
+
+Narrate your decomposition reasoning in complete sentences. Explain what the sketch promised, what prior slices changed, and how those two inputs shape the decomposition. Keep narration proportional to the work.
+
+**Right-size the plan.** If the slice is simple enough to be 1 task, plan 1 task. Don't fill in sections with "None" — omit them entirely.
+
+{{executorContextConstraints}}
+
+Then:
+0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the sketch says this slice owns or supports. Every owned requirement needs at least one task that directly advances it.
+1. Read the templates:
+   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
+   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
+2. {{skillActivation}} Record the installed skills you expect executors to use in each task plan's `skills_used` frontmatter.
+3. Define slice-level verification — the objective stopping condition. Plan real test files with real assertions; for simple slices, executable commands are fine.
+4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
+5. Decompose the slice into tasks that fit one context window each. Every task must have Why / Files / Do / Verify / Done-when, plus a task plan with description, steps, must-haves, verification, inputs (backtick-wrapped paths), and expected output (backtick-wrapped paths).
+6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
+7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should actually be true. Every must-have maps to at least one task. Inputs and Expected Output are backtick-wrapped file paths.
+8. If refinement produced structural decisions that diverge from the sketch, append them to `.gsd/DECISIONS.md`.
+9. {{commitInstruction}}
+
+The slice directory and tasks/ subdirectory already exist. Do NOT mkdir.
+
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. Document assumptions in the plan.
+
+**You MUST call `gsd_plan_slice` to persist the planning state before finishing.** After it returns successfully, the pipeline will automatically clear the sketch flag on the next state derivation (the on-disk PLAN file is the signal).
+
+When done, say: "Slice {{sliceId}} refined."

package/dist/resources/extensions/gsd/prompts/scan.md

@@ -0,0 +1,79 @@
+You are performing a focused codebase scan.
+
+## Scan Parameters
+
+- **Focus:** {{focus}}
+- **Documents to produce:** {{documents}}
+- **Output directory:** `{{outputDir}}`
+
+## Working Directory
+
+`{{workingDirectory}}`
+
+## Instructions
+
+1. Explore the codebase to understand its structure, technology choices, and patterns
+2. For each document listed above, produce a well-structured Markdown file in `{{outputDir}}/`
+3. Use the document schemas below as a guide for each output file
+
+For this scan, only these documents are relevant: **{{documents}}**. Refer only to those schemas below and ignore the rest.
+
+### Document Schemas
+
+**STACK.md** — Technology stack overview
+- Languages, runtimes, and versions
+- Key frameworks and libraries (with versions where visible)
+- Build tools and bundlers
+- Package manager
+
+**INTEGRATIONS.md** — External dependencies and integrations
+- Third-party APIs and services
+- Database systems
+- Authentication providers
+- Infrastructure and deployment platforms
+- Communication services (email, messaging, etc.)
+
+**ARCHITECTURE.md** — Architectural patterns and design decisions
+- Overall architecture style (monolith, microservices, monorepo, etc.)
+- Core data flow
+- Key design patterns in use
+- Module/package boundaries
+
+**STRUCTURE.md** — Directory and code organization
+- Top-level directory layout with purpose
+- Source code organization
+- Test organization
+- Configuration file locations
+
+**CONVENTIONS.md** — Coding conventions and standards
+- Naming conventions (files, functions, variables)
+- Code style and formatting rules
+- Import/export patterns
+- Error handling patterns
+- TypeScript/language-specific conventions
+
+**TESTING.md** — Testing patterns and practices
+- Test framework(s) in use
+- Test file naming and location conventions
+- Test helper and fixture patterns
+- Coverage requirements (if any)
+- How to run tests
+
+**CONCERNS.md** — Technical debt and risks
+- Known areas of technical debt
+- Fragile or high-risk code areas
+- Missing test coverage
+- Outdated dependencies
+- Performance bottlenecks
+- Security considerations
+
+## Rules
+
+- Write only the documents listed in **Documents to produce** — do not generate extra files
+- Each document must be a clean, standalone Markdown file starting with a `# Heading`
+- Be factual: report what you observe in the code, not what might be ideal
+- Keep each document focused and scannable — use headers, bullet points, and code snippets
+- Do NOT modify any source files
+- After writing all documents, summarize what was produced (file names and line counts)
+
+{{skillActivation}}

package/dist/resources/extensions/gsd/prompts/workflow-oneshot.md

@@ -0,0 +1,26 @@
+# Oneshot Workflow: {{displayName}}
+
+You are running a **oneshot** workflow called `{{name}}`. Oneshot workflows are
+prompt-only — there is no STATE.json, no phase tracking, no artifact directory,
+and no resume mechanism. Just execute the instructions below and return.
+
+## User Arguments
+
+`{{userArgs}}`
+
+(If empty, use sensible defaults from the workflow body.)
+
+## Workflow Instructions
+
+{{body}}
+
+## Execution Rules
+
+1. **No scaffolding.** Do not create `.gsd/workflows/` directories, STATE.json
+   files, or run directories unless the instructions explicitly tell you to
+   write a specific artifact.
+2. **No branch switching.** Work on the current branch.
+3. **Be concise.** Oneshot workflows produce a single focused output (a report,
+   a summary, a code change, a PR comment) — finish in this turn.
+4. **Ask only when blocked.** If the instructions need information you can't
+   discover, ask one clear question. Otherwise proceed.

package/dist/resources/extensions/gsd/python-resolver.js

@@ -0,0 +1,70 @@
+/**
+ * Cross-platform Python interpreter resolver.
+ *
+ * Provides utilities to detect the available Python interpreter on the current
+ * system and to normalize shell commands that reference `python`/`python3` so
+ * that they use whichever interpreter is actually installed.
+ *
+ * On Windows the canonical names differ (`py -3`, `python`, `python3`), so
+ * hard-coded `python3` invocations fail with exit 127. This module detects the
+ * working interpreter once (cached for the process lifetime) and rewrites
+ * commands accordingly.
+ *
+ * @module python-resolver
+ */
+import { spawnSync } from "node:child_process";
+/** Cached result of `detectPythonExecutable`. `undefined` means not yet probed. */
+let cached;
+/**
+ * Returns the first working Python invocation on this system, or `null` if no
+ * Python interpreter is found.
+ *
+ * Probe order:
+ * - Windows: `py -3` → `python` → `python3`
+ * - All other platforms: `python3` → `python`
+ *
+ * The result is cached for the lifetime of the process to avoid repeated
+ * `spawnSync` calls.
+ */
+export function detectPythonExecutable() {
+    if (cached !== undefined)
+        return cached;
+    const candidates = process.platform === "win32"
+        ? ["py -3", "python", "python3"]
+        : ["python3", "python"];
+    for (const candidate of candidates) {
+        const [bin, ...args] = candidate.split(" ");
+        const r = spawnSync(bin, [...args, "--version"], { stdio: "ignore" });
+        if (!r.error && r.status === 0) {
+            cached = candidate;
+            return candidate;
+        }
+    }
+    cached = null;
+    return null;
+}
+/**
+ * Rewrites a shell command string so that leading `python`/`python3`/`py`
+ * tokens at command boundaries are replaced with the interpreter returned by
+ * `detectPythonExecutable`.
+ *
+ * Only tokens at command boundaries (start of string, or after `&&`, `||`,
+ * `;`) are rewritten — mid-string occurrences (e.g. file paths containing
+ * "python") are left intact.
+ *
+ * When no Python interpreter is detected, the command is returned unchanged so
+ * that the caller receives a meaningful "command not found" error rather than a
+ * silent no-op.
+ *
+ * @param command - The shell command string to normalize.
+ * @returns The command with Python interpreter tokens rewritten, or the
+ *   original command if no rewrite is needed.
+ */
+export function normalizePythonCommand(command) {
+    const executable = detectPythonExecutable();
+    if (!executable)
+        return command;
+    // Split on common shell separators to handle compound commands.
+    // We reconstruct the string preserving the original separators.
+    return command.replace(/(^\s*|(?:&&|\|\||;)\s*)(?:python3?|py(?:\s+-\d+)?)(?=\s|$)/g, (_match, pre) => `${pre}${executable}`);
+}

package/dist/resources/extensions/gsd/run-manager.js

@@ -15,8 +15,9 @@
 import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { stringify } from "yaml";
-import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { loadDefinition, loadDefinitionFromFile, substituteParams } from "./definition-loader.js";
 import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+import { resolvePlugin } from "./workflow-plugins.js";
 // ─── Constants ───────────────────────────────────────────────────────────
 const RUNS_DIR = "workflow-runs";
 const DEFS_DIR = "workflow-defs";
@@ -42,38 +43,57 @@ function deriveStatus(graph) {
     return "pending";
 }
 // ─── Public API ──────────────────────────────────────────────────────────
+/**
+ * Create a run directory from an explicit definition file path.
+ * Preferred over `createRun` when the caller has already resolved the file
+ * (e.g. via the plugin resolver).
+ */
+export function createRunFromDefinition(basePath, defName, definitionFile, overrides) {
+    const rawDef = loadDefinitionFromFile(definitionFile);
+    const def = overrides
+        ? substituteParams(rawDef, overrides)
+        : substituteParams(rawDef);
+    const timestamp = makeTimestamp();
+    const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+    mkdirSync(runDir, { recursive: true });
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+    const graph = initializeGraph(def);
+    writeGraph(runDir, graph);
+    if (overrides && Object.keys(overrides).length > 0) {
+        writeFileSync(join(runDir, "PARAMS.json"), JSON.stringify(overrides, null, 2), "utf-8");
+    }
+    return runDir;
+}
 /**
  * Create a new isolated run directory for a workflow definition.
  *
- * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
- * 2. Applies parameter substitution if overrides are provided
- * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
- * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ * Resolution order:
+ *   1. Plugin resolver (project → global → bundled), YAML format only.
+ *   2. Legacy `.gsd/workflow-defs/<defName>.yaml`.
  *
- * @param basePath — project root directory
- * @param defName — definition filename (without .yaml extension)
- * @param overrides — optional parameter overrides (merged with definition defaults)
- * @returns Full path to the created run directory
- * @throws Error if the definition file doesn't exist or is invalid
+ * Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/` containing
+ * DEFINITION.yaml (frozen), GRAPH.yaml (initialized), and optional PARAMS.json.
+ *
+ * @throws Error if no matching definition is found anywhere.
  */
 export function createRun(basePath, defName, overrides) {
+    // Try the unified plugin resolver first — honors project/global overrides.
+    const plugin = resolvePlugin(basePath, defName);
+    if (plugin && plugin.format === "yaml") {
+        return createRunFromDefinition(basePath, defName, plugin.path, overrides);
+    }
+    // Fall back to legacy `.gsd/workflow-defs/<defName>.yaml`.
     const defsDir = join(basePath, ".gsd", DEFS_DIR);
-    // Load and validate the definition
     const rawDef = loadDefinition(defsDir, defName);
-    // Apply parameter substitution if overrides provided
     const def = overrides
         ? substituteParams(rawDef, overrides)
-        : substituteParams(rawDef); // still resolve default params if any
-    // Create the run directory
+        : substituteParams(rawDef);
     const timestamp = makeTimestamp();
     const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
     mkdirSync(runDir, { recursive: true });
-    // Freeze the definition as DEFINITION.yaml
     writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
-    // Initialize and write GRAPH.yaml
     const graph = initializeGraph(def);
     writeGraph(runDir, graph);
-    // Write PARAMS.json if overrides were provided
     if (overrides && Object.keys(overrides).length > 0) {
         writeFileSync(join(runDir, "PARAMS.json"), JSON.stringify(overrides, null, 2), "utf-8");
     }

package/dist/resources/extensions/gsd/setup-catalog.js

@@ -0,0 +1,75 @@
+// GSD — Setup catalog (single source of truth for onboarding steps + provider sub-views)
+//
+// Re-exports filtered views over PROVIDER_REGISTRY (key-manager.ts) and owns the
+// canonical ONBOARDING_STEPS list. Consumers (CLI wizard, /gsd setup hub,
+// onboarding handler, web alignment) all read from here so adding a step or
+// provider lands in one place. Keep this module thin: no behavior beyond
+// filters + lookup helpers, so it stays cycle-safe even though it depends on
+// key-manager for the provider catalog.
+import { PROVIDER_REGISTRY } from "./key-manager.js";
+/**
+ * Canonical ordered list of onboarding steps.
+ *
+ * To add a new step:
+ *   1. Append here (or insert at the right position).
+ *   2. Bump FLOW_VERSION in onboarding-state.ts so existing users get re-prompted.
+ *   3. Wire its CLI runner in src/onboarding.ts (and handlers/onboarding.ts for --step).
+ */
+export const ONBOARDING_STEPS = [
+    { id: "llm", label: "LLM provider & auth", required: true, hint: "Sign in or paste an API key" },
+    { id: "model", label: "Default model", required: false, hint: "Pick a default model for the chosen provider" },
+    { id: "search", label: "Web search provider", required: false, hint: "Brave, Tavily, or Anthropic built-in" },
+    { id: "remote", label: "Remote questions", required: false, hint: "Discord / Slack / Telegram notifications" },
+    { id: "tool-keys", label: "Tool API keys", required: false, hint: "Context7, Jina, Groq voice, etc." },
+    { id: "prefs", label: "Global preferences", required: false, hint: "Mode, profile, notifications" },
+    { id: "skills", label: "Skills install", required: false, hint: "Browse and install skill plugins" },
+    { id: "doctor", label: "Validate setup", required: false, hint: "Run provider doctor checks" },
+    { id: "project", label: "Project init", required: false, hint: "Bootstrap .gsd/ in this repo" },
+];
+const STEP_INDEX = new Map(ONBOARDING_STEPS.map((s, i) => [s.id, i]));
+export function getStep(id) {
+    const idx = STEP_INDEX.get(id);
+    return idx === undefined ? undefined : ONBOARDING_STEPS[idx];
+}
+export function isValidStepId(id) {
+    return STEP_INDEX.has(id);
+}
+/**
+ * Given a possibly-stale resume point, return the nearest next step that is
+ * still defined in the catalog. Falls back to the first step.
+ */
+export function nearestResumeStep(lastResumePoint, completedSteps) {
+    const completed = new Set(completedSteps);
+    // First incomplete step at or after the lastResumePoint
+    let startIdx = 0;
+    if (lastResumePoint && STEP_INDEX.has(lastResumePoint)) {
+        startIdx = STEP_INDEX.get(lastResumePoint) ?? 0;
+    }
+    for (let i = startIdx; i < ONBOARDING_STEPS.length; i++) {
+        if (!completed.has(ONBOARDING_STEPS[i].id))
+            return ONBOARDING_STEPS[i].id;
+    }
+    // Everything from the resume point is complete — try from the start
+    for (const step of ONBOARDING_STEPS) {
+        if (!completed.has(step.id))
+            return step.id;
+    }
+    return ONBOARDING_STEPS[0].id;
+}
+// ─── Provider catalog views ───────────────────────────────────────────────────
+export function getLlmProviders() {
+    return PROVIDER_REGISTRY.filter(p => p.category === "llm");
+}
+export function getToolProviders() {
+    return PROVIDER_REGISTRY.filter(p => p.category === "tool");
+}
+export function getSearchProviders() {
+    return PROVIDER_REGISTRY.filter(p => p.category === "search");
+}
+export function getRemoteProviders() {
+    return PROVIDER_REGISTRY.filter(p => p.category === "remote");
+}
+/** Provider IDs that count as "the user has an LLM configured" for shouldRunOnboarding. */
+export function getLlmProviderIds() {
+    return Array.from(new Set([...getLlmProviders().map(p => p.id), "claude-code"]));
+}

package/dist/resources/extensions/gsd/state.js

@@ -13,7 +13,9 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { debugCount, debugTime } from './debug-logger.js';
 import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
-import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, insertSlice, insertTask, updateSliceStatus, updateTaskStatus, getPendingGateCountForTurn, } from './gsd-db.js';
+import { loadEffectiveGSDPreferences } from './preferences.js';
+import { detectPendingEscalation } from './escalation.js';
+import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, insertSlice, insertTask, updateSliceStatus, updateTaskStatus, getPendingGateCountForTurn, autoHealSketchFlags, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
  * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY).  These appear when
@@ -710,7 +712,13 @@ export async function deriveStateFromDb(basePath) {
     if (allSlicesDone) {
         return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
     }
-    const activeSliceContext = resolveSliceDependencies(activeMilestoneSlices);
+    // ADR-011 auto-heal: if a slice has a PLAN on disk but is still flagged is_sketch=1
+    // (e.g. a crash between plan-slice write and the sketch flip), reconcile before
+    // running phase derivation so the flag doesn't misroute state.
+    autoHealSketchFlags(activeMilestone.id, (sid) => !!resolveSliceFile(basePath, activeMilestone.id, sid, "PLAN"));
+    // Re-read slices after auto-heal so downstream reads see fresh is_sketch values.
+    const healedSlices = getMilestoneSlices(activeMilestone.id);
+    const activeSliceContext = resolveSliceDependencies(healedSlices);
     if (!activeSliceContext.activeSlice) {
         // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
         if (process.env.GSD_SLICE_LOCK) {
@@ -730,9 +738,23 @@ export async function deriveStateFromDb(basePath) {
             progress: { milestones: milestoneProgress, slices: sliceProgress },
         };
     }
-    const { activeSlice } = activeSliceContext;
+    const { activeSlice, activeSliceRow } = activeSliceContext;
     const planFile = resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "PLAN");
     if (!planFile) {
+        // ADR-011: sketch slices with progressive_planning enabled enter the
+        // `refining` phase — a refine-slice unit expands the sketch into a full plan
+        // before execution. When the flag is off, sketches are indistinguishable
+        // from a missing plan and fall through to the normal `planning` phase.
+        const progressive = loadEffectiveGSDPreferences()?.preferences?.phases?.progressive_planning === true;
+        if (progressive && activeSliceRow?.is_sketch === 1) {
+            return {
+                activeMilestone, activeSlice, activeTask: null,
+                phase: 'refining', recentDecisions: [], blockers: [],
+                nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
+                registry, requirements,
+                progress: { milestones: milestoneProgress, slices: sliceProgress },
+            };
+        }
         return {
             activeMilestone, activeSlice, activeTask: null,
             phase: 'planning', recentDecisions: [], blockers: [],
@@ -811,6 +833,28 @@ export async function deriveStateFromDb(basePath) {
             };
         }
     }
+    // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
+    // next task. `awaiting_review` tasks (continueWithDefault=true) are NOT
+    // surfaced here — they let the loop continue.
+    //
+    // We do NOT gate this on `phases.mid_execution_escalation` — creation of
+    // new escalations is gated at the write site (tools/complete-task.ts:315),
+    // but any escalation_pending row already persisted in the DB must be
+    // honored even if the user later toggles the flag off. Otherwise those
+    // rows would silently orphan, the loop would advance past the paused task,
+    // and the user's prior resolution never lands.
+    const escalatingTaskId = detectPendingEscalation(tasks, basePath);
+    if (escalatingTaskId) {
+        return {
+            activeMilestone, activeSlice, activeTask,
+            phase: 'escalating-task', recentDecisions: [],
+            blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
+            nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
+            activeWorkspace: undefined,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+        };
+    }
     if (!blockerTaskId) {
         const isTriggered = checkReplanTrigger(basePath, activeMilestone.id, activeSlice.id);
         if (isTriggered) {

package/dist/resources/extensions/gsd/templates/PREFERENCES.md

@@ -44,19 +44,19 @@ uok:
   legacy_fallback:
     enabled: false
   gates:
-    enabled: false
+    enabled: true
   model_policy:
-    enabled: false
+    enabled: true
   execution_graph:
-    enabled: false
+    enabled: true
   gitops:
-    enabled: false
-    turn_action: status-only
+    enabled: true
+    turn_action: commit
     turn_push: false
   audit_unified:
-    enabled: false
+    enabled: true
   plan_v2:
-    enabled: false
+    enabled: true
 auto_visualize:
 auto_report:
 parallel:

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -20,6 +20,8 @@ import { renderAllProjections, renderSummaryContent } from "../workflow-projecti
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
  * presence drives `pass` vs. `omitted`. Keep in lockstep with the gates
@@ -80,6 +82,11 @@ function paramsToTaskRow(params, completedAt) {
         observability_impact: "",
         full_plan_md: "",
         sequence: 0,
+        blocker_source: "",
+        escalation_pending: 0,
+        escalation_awaiting_review: 0,
+        escalation_artifact_path: null,
+        escalation_override_applied_at: null,
     };
 }
 /**
@@ -111,6 +118,39 @@ export async function handleCompleteTask(params, basePath) {
     // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
     const completedAt = new Date().toISOString();
     let guardError = null;
+    // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
+    // Building the artifact runs the full shape validation (2-4 options, unique
+    // ids, recommendation references a real id). If the payload is malformed
+    // we must reject the call before marking the task complete, writing
+    // SUMMARY.md, flipping the plan checkbox, or closing execute-task gates —
+    // otherwise a rejected payload would leave the task marked complete with
+    // no escalation recorded, and the loop would silently advance past it.
+    // The filesystem write happens later (after side effects) because that's
+    // the cheapest ordering and validation is where 99% of failures live.
+    let validatedEscalationArtifact = null;
+    let escalationWriteEnabled = false;
+    if (params.escalation) {
+        escalationWriteEnabled = loadEffectiveGSDPreferences()?.preferences?.phases?.mid_execution_escalation === true;
+        if (escalationWriteEnabled) {
+            try {
+                validatedEscalationArtifact = buildEscalationArtifact({
+                    taskId: params.taskId,
+                    sliceId: params.sliceId,
+                    milestoneId: params.milestoneId,
+                    question: params.escalation.question,
+                    options: params.escalation.options,
+                    recommendation: params.escalation.recommendation,
+                    recommendationRationale: params.escalation.recommendationRationale,
+                    continueWithDefault: params.escalation.continueWithDefault,
+                });
+            }
+            catch (validationErr) {
+                return {
+                    error: `complete-task escalation payload invalid for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${validationErr.message}`,
+                };
+            }
+        }
+    }
     transaction(() => {
         // State machine preconditions (inside txn for atomicity).
         // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
@@ -239,6 +279,46 @@ export async function handleCompleteTask(params, basePath) {
     catch (gateErr) {
         logWarning("tool", `complete-task gate close warning for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${gateErr.message}`);
     }
+    // ── ADR-011 Phase 2: write escalation artifact (opt-in) ────────────────
+    // Validation already happened BEFORE side effects — this block only
+    // performs the disk write for a pre-validated artifact. For
+    // continueWithDefault=false, a write failure here would otherwise leave
+    // the task marked complete with SUMMARY.md + closed gates but no
+    // escalation, which silently advances the loop past a pause the user
+    // asked for. We compensate by reverting the DB-level completion: set
+    // status back to 'pending' and delete the verification_evidence rows
+    // (same shape as the disk-render-failure rollback above). SUMMARY.md
+    // on disk is left in place because the next complete-task retry will
+    // overwrite it; gate rows are UPSERT-keyed per task and will also be
+    // overwritten. This restores the invariant that deriveState() sees a
+    // consistent "task not done" view so the loop re-dispatches the task.
+    if (validatedEscalationArtifact) {
+        try {
+            writeEscalationArtifact(basePath, validatedEscalationArtifact);
+        }
+        catch (escalationErr) {
+            const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${escalationErr.message}`;
+            logWarning("tool", msg);
+            if (validatedEscalationArtifact.continueWithDefault === false) {
+                // Compensating rollback: revert DB completion so the loop pauses on
+                // re-dispatch instead of silently advancing. Mirror the existing
+                // renderErr rollback (line ~261).
+                try {
+                    deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+                    updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+                    invalidateStateCache();
+                    logWarning("tool", `complete-task rolled back DB completion for ${params.milestoneId}/${params.sliceId}/${params.taskId} after escalation write failure; SUMMARY.md left on disk for retry.`);
+                }
+                catch (rollbackErr) {
+                    logWarning("tool", `complete-task rollback failed after escalation write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${rollbackErr.message}`);
+                }
+                return { error: msg };
+            }
+        }
+    }
+    else if (params.escalation && !escalationWriteEnabled) {
+        logWarning("tool", `complete-task received escalation payload but phases.mid_execution_escalation is not enabled; ignoring (${params.milestoneId}/${params.sliceId}/${params.taskId})`);
+    }
     // Invalidate all caches
     invalidateStateCache();
     clearPathCache();