gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

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

@@ -42,6 +42,7 @@ An honest "this is straightforward, here's the pattern to follow" is more valuab
 
 Research what this slice needs. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach.
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements this slice owns or supports. Research should target these requirements — surfacing risks, unknowns, and implementation constraints that could affect whether the slice actually delivers them.
+0a. Call `memory_query` with keywords from the slice title and scope. Prior slices may have captured architecture notes, conventions, or gotchas in subsystems you're about to explore — pulling them now prevents re-discovering known constraints.
 1. {{skillActivation}} Reference specific rules from loaded skills in your findings where they inform the implementation approach.
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.

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
@@ -499,7 +501,7 @@ async function handleAllSlicesDone(basePath, activeMilestone, registry, requirem
     const validationContent = validationFile ? await loadFile(validationFile) : null;
     const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
     const verdict = validationContent ? extractVerdict(validationContent) : undefined;
-    if (!validationTerminal || verdict === 'needs-remediation') {
+    if (!validationTerminal) {
         return {
             activeMilestone, activeSlice: null, activeTask: null,
             phase: 'validating-milestone',
@@ -509,6 +511,23 @@ async function handleAllSlicesDone(basePath, activeMilestone, registry, requirem
             progress: { milestones: milestoneProgress, slices: sliceProgress },
         };
     }
+    // All roadmap slices are done (enforced by caller) and verdict is
+    // needs-remediation — remediation cannot progress without new slices.
+    // Return blocked instead of re-dispatching validate-milestone (#4506).
+    if (verdict === 'needs-remediation') {
+        return {
+            activeMilestone, activeSlice: null, activeTask: null,
+            phase: 'blocked',
+            recentDecisions: [],
+            blockers: [
+                `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+                    `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+            ],
+            nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+            registry, requirements,
+            progress: { milestones: milestoneProgress, slices: sliceProgress },
+        };
+    }
     return {
         activeMilestone, activeSlice: null, activeTask: null,
         phase: 'completing-milestone',
@@ -710,7 +729,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 +755,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 +850,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) {
@@ -1234,9 +1295,11 @@ export async function _deriveStateImpl(basePath) {
             done: activeRoadmap.slices.length,
             total: activeRoadmap.slices.length,
         };
-        // Force re-validation when verdict is needs-remediation — remediation slices
-        // may have completed since the stale validation was written (#3596).
-        if (!validationTerminal || verdict === 'needs-remediation') {
+        // Force re-validation when VALIDATION.md is absent or non-terminal —
+        // remediation slices may have completed since the stale validation was
+        // written (#3596). But needs-remediation with all slices done is a dead
+        // end — return blocked to avoid an infinite dispatch loop (#4506).
+        if (!validationTerminal) {
             return {
                 activeMilestone,
                 activeSlice: null,
@@ -1253,6 +1316,26 @@ export async function _deriveStateImpl(basePath) {
                 },
             };
         }
+        if (verdict === 'needs-remediation') {
+            return {
+                activeMilestone,
+                activeSlice: null,
+                activeTask: null,
+                phase: 'blocked',
+                recentDecisions: [],
+                blockers: [
+                    `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+                        `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+                ],
+                nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+                registry,
+                requirements,
+                progress: {
+                    milestones: milestoneProgress,
+                    slices: sliceProgress,
+                },
+            };
+        }
         return {
             activeMilestone,
             activeSlice: null,

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();