gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -49,6 +49,7 @@ function makeDeps(
     loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
     invalidateAllCaches: () => {},
     captureIntegrationBranch: () => {},
+    enterBranchModeForMilestone: () => {},
     ...overrides,
   };
   return deps;
@@ -127,7 +128,7 @@ describe("worktree journal events", () => {
 
   test("enterMilestone emits worktree-skip when isolation disabled", () => {
     const s = makeSession({ basePath: tmp, originalBasePath: tmp });
-    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false });
+    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false, getIsolationMode: () => "none" });
     const resolver = new WorktreeResolver(s, deps);
 
     resolver.enterMilestone("M001", makeNotifyCtx());

package/src/resources/extensions/gsd/tests/worktree-resolver.test.ts

@@ -145,6 +145,9 @@ function makeDeps(
         args: [basePath, mid],
       });
     },
+    enterBranchModeForMilestone: (basePath: string, milestoneId: string) => {
+      calls.push({ fn: "enterBranchModeForMilestone", args: [basePath, milestoneId] });
+    },
     ...overrides,
   };
 
@@ -252,10 +255,10 @@ test("enterMilestone enters existing worktree instead of creating", () => {
   assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
 });
 
-test("enterMilestone is no-op when shouldUseWorktreeIsolation is false", () => {
+test("enterMilestone is no-op when isolation mode is none", () => {
   const s = makeSession();
   const deps = makeDeps({
-    shouldUseWorktreeIsolation: () => false,
+    getIsolationMode: () => "none",
   });
   const ctx = makeNotifyCtx();
   const resolver = new WorktreeResolver(s, deps);
@@ -265,6 +268,7 @@ test("enterMilestone is no-op when shouldUseWorktreeIsolation is false", () => {
   assert.equal(s.basePath, "/project"); // unchanged
   assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
   assert.equal(findCalls(deps.calls, "enterAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 0);
 });
 
 test("enterMilestone does NOT update basePath on creation failure", () => {
@@ -309,6 +313,77 @@ test("enterMilestone uses originalBasePath as base for worktree ops", () => {
   assert.equal(createdFrom, "/project"); // uses originalBasePath, not current basePath
 });
 
+// ─── enterMilestone Tests (branch mode) ──────────────────────────────────────
+
+test("enterMilestone in branch mode calls enterBranchModeForMilestone and rebuilds GitService", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  // Branch mode: no worktree created, basePath unchanged
+  assert.equal(s.basePath, "/project");
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 1);
+  assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "enterAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "GitServiceImpl").length, 1);
+  assert.ok(ctx.messages.some((m) => m.level === "info" && m.msg.includes("milestone/M001")));
+});
+
+test("enterMilestone in branch mode uses originalBasePath as base", () => {
+  const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  let calledWith = "";
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+    enterBranchModeForMilestone: (basePath: string, _mid: string) => {
+      calledWith = basePath;
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(calledWith, "/project");
+});
+
+test("enterMilestone in branch mode degrades isolation on failure", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+    enterBranchModeForMilestone: () => {
+      throw new Error("checkout failed");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(s.basePath, "/project"); // unchanged
+  assert.ok(s.isolationDegraded);
+  assert.ok(ctx.messages.some((m) => m.level === "warning" && m.msg.includes("checkout failed")));
+});
+
+test("enterMilestone branch mode is skipped when isolationDegraded", () => {
+  const s = makeSession();
+  s.isolationDegraded = true;
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 0);
+  assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
+});
+
 // ─── exitMilestone Tests ─────────────────────────────────────────────────────
 
 test("exitMilestone commits, tears down, and resets basePath", () => {

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -37,6 +37,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";
 
 export interface CompleteTaskResult {
   taskId: string;
@@ -111,6 +113,11 @@ function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskR
     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,
   };
 }
 
@@ -153,6 +160,39 @@ export async function handleCompleteTask(
   const completedAt = new Date().toISOString();
   let guardError: string | null = 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: ReturnType<typeof buildEscalationArtifact> | null = 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 as Error).message}`,
+        };
+      }
+    }
+  }
+
   transaction(() => {
     // State machine preconditions (inside txn for atomicity).
     // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
@@ -299,6 +339,53 @@ export async function handleCompleteTask(
     );
   }
 
+  // ── 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 as Error).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 as Error).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();

package/src/resources/extensions/gsd/tools/plan-milestone.ts

@@ -25,10 +25,18 @@ export interface PlanMilestoneSliceInput {
   depends: string[];
   demo: string;
   goal: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   successCriteria: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   proofLevel: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   integrationClosure: string;
+  /** Required when isSketch is false/absent; may be empty for sketch slices (ADR-011). */
   observabilityImpact: string;
+  /** ADR-011: when true, this slice is a sketch awaiting refine-slice expansion. */
+  isSketch?: boolean;
+  /** ADR-011: 2–3 sentence scope boundary, required when isSketch is true. */
+  sketchScope?: string;
 }
 
 export interface PlanMilestoneParams {
@@ -125,6 +133,16 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     const proofLevel = obj.proofLevel;
     const integrationClosure = obj.integrationClosure;
     const observabilityImpact = obj.observabilityImpact;
+    const isSketchRaw = obj.isSketch;
+    const sketchScopeRaw = obj.sketchScope;
+    // ADR-011: preserve the 3-valued semantics of isSketch (true / false / absent).
+    // Callers that omit isSketch must receive `undefined` here so `insertSlice`'s
+    // ON CONFLICT clause preserves any existing is_sketch on the row rather than
+    // silently overwriting a legitimate sketch to non-sketch.
+    const isSketch: boolean | undefined =
+      isSketchRaw === true ? true
+      : isSketchRaw === false ? false
+      : undefined;
 
     if (!isNonEmptyString(sliceId)) throw new Error(`slices[${index}].sliceId must be a non-empty string`);
     if (seen.has(sliceId)) throw new Error(`slices[${index}].sliceId must be unique`);
@@ -136,10 +154,18 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     }
     if (!isNonEmptyString(demo)) throw new Error(`slices[${index}].demo must be a non-empty string`);
     if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`);
-    if (!isNonEmptyString(successCriteria)) throw new Error(`slices[${index}].successCriteria must be a non-empty string`);
-    if (!isNonEmptyString(proofLevel)) throw new Error(`slices[${index}].proofLevel must be a non-empty string`);
-    if (!isNonEmptyString(integrationClosure)) throw new Error(`slices[${index}].integrationClosure must be a non-empty string`);
-    if (!isNonEmptyString(observabilityImpact)) throw new Error(`slices[${index}].observabilityImpact must be a non-empty string`);
+
+    // ADR-011: sketch slices may defer the heavyweight planning fields to refine-slice.
+    if (isSketch === true) {
+      if (!isNonEmptyString(sketchScopeRaw)) {
+        throw new Error(`slices[${index}].sketchScope must be a non-empty string when isSketch is true`);
+      }
+    } else {
+      if (!isNonEmptyString(successCriteria)) throw new Error(`slices[${index}].successCriteria must be a non-empty string`);
+      if (!isNonEmptyString(proofLevel)) throw new Error(`slices[${index}].proofLevel must be a non-empty string`);
+      if (!isNonEmptyString(integrationClosure)) throw new Error(`slices[${index}].integrationClosure must be a non-empty string`);
+      if (!isNonEmptyString(observabilityImpact)) throw new Error(`slices[${index}].observabilityImpact must be a non-empty string`);
+    }
 
     return {
       sliceId,
@@ -148,10 +174,14 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
       depends,
       demo,
       goal,
-      successCriteria,
-      proofLevel,
-      integrationClosure,
-      observabilityImpact,
+      successCriteria: isNonEmptyString(successCriteria) ? successCriteria : "",
+      proofLevel: isNonEmptyString(proofLevel) ? proofLevel : "",
+      integrationClosure: isNonEmptyString(integrationClosure) ? integrationClosure : "",
+      observabilityImpact: isNonEmptyString(observabilityImpact) ? observabilityImpact : "",
+      isSketch,
+      // Only carry the sketch scope through if the caller explicitly provided it
+      // — preserves ON CONFLICT semantics for re-plans that omit the field.
+      sketchScope: sketchScopeRaw === undefined ? undefined : (isNonEmptyString(sketchScopeRaw) ? sketchScopeRaw : ""),
     };
   });
 }
@@ -274,6 +304,10 @@ export async function handlePlanMilestone(
           depends: slice.depends,
           demo: slice.demo,
           sequence: i + 1, // Preserve agent-ordered sequence (#3356)
+          // ADR-011: pass undefined through so ON CONFLICT preserves existing values
+          // when the caller omitted the fields on a re-plan.
+          isSketch: slice.isSketch,
+          sketchScope: slice.sketchScope,
         });
         upsertSlicePlanning(params.milestoneId, slice.sliceId, {
           goal: slice.goal,

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -1,5 +1,5 @@
 import { clearParseCache } from "../files.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
 import {
   transaction,
@@ -9,6 +9,7 @@ import {
   upsertSlicePlanning,
   upsertTaskPlanning,
   insertGateRow,
+  updateSliceStatus,
 } from "../gsd-db.js";
 import type { GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
@@ -166,6 +167,10 @@ export async function handlePlanSlice(
         return;
       }
 
+      if (isDeferredStatus(parentSlice.status)) {
+        updateSliceStatus(params.milestoneId, params.sliceId, "pending");
+      }
+
       upsertSlicePlanning(params.milestoneId, params.sliceId, {
         goal: params.goal,
         successCriteria: params.successCriteria,

package/src/resources/extensions/gsd/types.ts

@@ -11,6 +11,7 @@ export type Phase =
   | "discussing"
   | "researching"
   | "planning"
+  | "refining"
   | "evaluating-gates"
   | "executing"
   | "verifying"
@@ -19,6 +20,7 @@ export type Phase =
   | "validating-milestone"
   | "completing-milestone"
   | "replanning-slice"
+  | "escalating-task"
   | "complete"
   | "paused"
   | "blocked";
@@ -350,6 +352,51 @@ export interface PhaseSkipPreferences {
   reassess_after_slice?: boolean;
   /** When true, auto-mode pauses before each slice for discussion (#789). */
   require_slice_discussion?: boolean;
+  /** ADR-011 Phase 2: when true, executors may escalate task-level ambiguity via T##-ESCALATION.json. */
+  mid_execution_escalation?: boolean;
+  /** ADR-011 Phase 1: when true, plan S01 in full and S02+ as sketches refined just-in-time. */
+  progressive_planning?: boolean;
+}
+
+// ─── ADR-011 Phase 2 Escalation ──────────────────────────────────────────
+
+export interface EscalationOption {
+  /** Short identifier, e.g. "A", "B". Used as the `choice` value in `/gsd escalate resolve <taskId> <id>`. */
+  id: string;
+  /** One-line label for the option. */
+  label: string;
+  /** 1-2 sentence description of the tradeoffs of this option. */
+  tradeoffs: string;
+}
+
+export interface EscalationArtifact {
+  /** Schema version for the artifact file — bumps if we change the shape. */
+  version: 1;
+  taskId: string;
+  sliceId: string;
+  milestoneId: string;
+  /** The question the executor needs the user to resolve. */
+  question: string;
+  /** 2-4 options the user can choose between. */
+  options: EscalationOption[];
+  /** Which option the executor recommends (references `options[].id`). */
+  recommendation: string;
+  /** Why the executor recommends that option (1-2 sentences). */
+  recommendationRationale: string;
+  /**
+   * When true, the executor proceeds with the recommendation as the answer
+   * and the loop continues. User's later choice becomes a carry-forward
+   * override for the NEXT task. When false, auto-mode pauses until the
+   * user resolves via `/gsd escalate resolve`.
+   */
+  continueWithDefault: boolean;
+  createdAt: string;
+  /** Populated by `/gsd escalate resolve`. */
+  respondedAt?: string;
+  /** User's choice — either an option id, "accept" (use recommendation), or "reject-blocker". */
+  userChoice?: string;
+  /** Optional free-text rationale from the user. */
+  userRationale?: string;
 }
 
 export interface NotificationPreferences {
@@ -435,6 +482,7 @@ export interface Decision {
   rationale: string; // why this choice
   revisable: string; // whether/when revisable
   made_by: DecisionMadeBy; // who made the decision: human, agent, or collaborative
+  source?: string; // ADR-011 P2: origin — "discussion" (default) | "planning" | "escalation"
   superseded_by: string | null; // ID of superseding decision, or null
 }
 
@@ -542,6 +590,20 @@ export interface CompleteTaskParams {
   knownIssues?: string;
   /** @optional — defaults to false when omitted */
   blockerDiscovered?: boolean;
+  /**
+   * ADR-011 Phase 2 — optional escalation payload. When populated, the executor
+   * is asking the user to resolve an ambiguity. If `continueWithDefault: true`
+   * the task still completes (using the recommendation) but an artifact is
+   * written for later user review. If false, auto-mode pauses.
+   * @optional
+   */
+  escalation?: {
+    question: string;
+    options: EscalationOption[];
+    recommendation: string;
+    recommendationRationale: string;
+    continueWithDefault: boolean;
+  };
   /** @optional — defaults to [] when omitted by models with limited tool-calling */
   verificationEvidence?: Array<{
     command: string;

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -14,6 +14,7 @@ export type UnitRuntimePhase =
   | "dispatched"
   | "wrapup-warning-sent"
   | "timeout"
+  | "finalize-timeout"
   | "recovered"
   | "finalized"
   | "paused"

package/src/resources/extensions/gsd/uok/contracts.ts

@@ -113,7 +113,8 @@ export type UokNodeKind =
   | "subagent"
   | "team-worker"
   | "verification"
-  | "reprocess";
+  | "reprocess"
+  | "refine";
 
 export interface UokGraphNode {
   id: string;

package/src/resources/extensions/gsd/uok/flags.ts

@@ -28,14 +28,14 @@ export function resolveUokFlags(prefs: GSDPreferences | undefined): UokFlags {
   return {
     enabled: enabledByPreference && !legacyFallback,
     legacyFallback,
-    gates: uok?.gates?.enabled === true,
-    modelPolicy: uok?.model_policy?.enabled === true,
-    executionGraph: uok?.execution_graph?.enabled === true,
-    gitops: uok?.gitops?.enabled === true,
-    gitopsTurnAction: uok?.gitops?.turn_action ?? "status-only",
+    gates: uok?.gates?.enabled ?? true,
+    modelPolicy: uok?.model_policy?.enabled ?? true,
+    executionGraph: uok?.execution_graph?.enabled ?? true,
+    gitops: uok?.gitops?.enabled ?? true,
+    gitopsTurnAction: uok?.gitops?.turn_action ?? "commit",
     gitopsTurnPush: uok?.gitops?.turn_push === true,
-    auditUnified: uok?.audit_unified?.enabled === true,
-    planV2: uok?.plan_v2?.enabled === true,
+    auditUnified: uok?.audit_unified?.enabled ?? true,
+    planV2: uok?.plan_v2?.enabled ?? true,
   };
 }
 

package/src/resources/extensions/gsd/uok/kernel.ts

@@ -15,6 +15,12 @@ interface RunAutoLoopWithUokArgs {
   pi: ExtensionAPI;
   s: AutoSession;
   deps: LoopDeps;
+  runKernelLoop: (
+    ctx: ExtensionContext,
+    pi: ExtensionAPI,
+    s: AutoSession,
+    deps: LoopDeps,
+  ) => Promise<void>;
   runLegacyLoop: (
     ctx: ExtensionContext,
     pi: ExtensionAPI,
@@ -36,13 +42,15 @@ function writeParityEvent(basePath: string, event: Record<string, unknown>): voi
   }
 }
 
-function resolveKernelPathLabel(flags: ReturnType<typeof resolveUokFlags>): "uok-wrapper" | "legacy-wrapper" | "legacy-fallback" {
+function resolveKernelPathLabel(
+  flags: ReturnType<typeof resolveUokFlags>,
+): "uok-kernel" | "legacy-wrapper" | "legacy-fallback" {
   if (flags.legacyFallback) return "legacy-fallback";
-  return flags.enabled ? "uok-wrapper" : "legacy-wrapper";
+  return flags.enabled ? "uok-kernel" : "legacy-wrapper";
 }
 
 export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<void> {
-  const { ctx, pi, s, deps, runLegacyLoop } = args;
+  const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
   const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
   const flags = resolveUokFlags(prefs);
   setUnifiedAuditEnabled(flags.auditUnified);
@@ -83,7 +91,11 @@ export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<
     : deps;
 
   try {
-    await runLegacyLoop(ctx, pi, s, decoratedDeps);
+    if (flags.enabled) {
+      await runKernelLoop(ctx, pi, s, decoratedDeps);
+    } else {
+      await runLegacyLoop(ctx, pi, s, deps);
+    }
     writeParityEvent(s.basePath, {
       ts: new Date().toISOString(),
       path: resolveKernelPathLabel(flags),

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

@@ -0,0 +1,106 @@
+/**
+ * workflow-dispatch.ts — Shared dispatchers for workflow plugins.
+ *
+ * Called by both `/gsd start <template>` (existing markdown path) and
+ * `/gsd workflow <name>` (new direct dispatch). Keeps the prompt-build
+ * logic in one place so md template behavior stays consistent.
+ */
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { readFileSync } from "node:fs";
+
+import { loadPrompt } from "./prompt-loader.js";
+import type { WorkflowPlugin } from "./workflow-plugins.js";
+
+// ─── Oneshot dispatch ────────────────────────────────────────────────────
+
+/**
+ * Strip the `<template_meta>` block from markdown content so it's not
+ * repeated in the prompt body.
+ */
+function stripTemplateMeta(content: string): string {
+  return content.replace(/<template_meta>[\s\S]*?<\/template_meta>\s*/, "");
+}
+
+/**
+ * For a oneshot YAML plugin, extract the single-step prompt.
+ * For multi-step YAML defined as oneshot, concatenate step prompts.
+ */
+function extractYamlOneshotPrompt(yamlContent: string): string {
+  // Simple: just include the raw YAML so the model can follow it.
+  // This keeps the oneshot format flexible without re-parsing.
+  return `\`\`\`yaml\n${yamlContent}\n\`\`\``;
+}
+
+/**
+ * Dispatch a oneshot workflow: load the prompt, inject the body, send.
+ * No STATE.json, no branch switch, no auto-loop.
+ */
+export function dispatchOneshot(
+  plugin: WorkflowPlugin,
+  pi: ExtensionAPI,
+  userArgs: string,
+): void {
+  const raw = readFileSync(plugin.path, "utf-8");
+  const body = plugin.format === "yaml"
+    ? extractYamlOneshotPrompt(raw)
+    : stripTemplateMeta(raw);
+
+  const prompt = loadPrompt("workflow-oneshot", {
+    name: plugin.name,
+    displayName: plugin.meta.displayName,
+    body,
+    userArgs: userArgs || "(none)",
+  });
+
+  pi.sendMessage(
+    { customType: "gsd-workflow-oneshot", content: prompt, display: false },
+    { triggerTurn: true },
+  );
+}
+
+// ─── Markdown-phase dispatch ─────────────────────────────────────────────
+
+export interface MarkdownPhaseDispatchOptions {
+  templateId: string;
+  templateName: string;
+  templateDescription: string;
+  phases: string[];
+  complexity: string;
+  artifactDir: string;
+  branch: string;
+  description: string;
+  issueRef: string;
+  date: string;
+  workflowContent: string;
+}
+
+/**
+ * Build and dispatch the `workflow-start.md` prompt for a markdown-phase plugin.
+ * Returns the prompt that was sent (useful for tests).
+ */
+export function dispatchMarkdownPhase(
+  opts: MarkdownPhaseDispatchOptions,
+  pi: ExtensionAPI,
+): string {
+  const prompt = loadPrompt("workflow-start", {
+    templateId: opts.templateId,
+    templateName: opts.templateName,
+    templateDescription: opts.templateDescription,
+    phases: opts.phases.join(" → "),
+    complexity: opts.complexity,
+    artifactDir: opts.artifactDir || "(none)",
+    branch: opts.branch,
+    description: opts.description || "(none provided)",
+    issueRef: opts.issueRef || "(none)",
+    date: opts.date,
+    workflowContent: opts.workflowContent,
+  });
+
+  pi.sendMessage(
+    { customType: "gsd-workflow-template", content: prompt, display: false },
+    { triggerTurn: true },
+  );
+
+  return prompt;
+}