gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

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

@@ -0,0 +1,133 @@
+/**
+ * skip-slice handler — the core operation behind gsd_skip_slice.
+ *
+ * Marks a slice as skipped and cascades the skip to every non-closed task in
+ * that slice. Without the task cascade the deep-check in
+ * executeCompleteMilestone reports pending tasks inside the skipped slice and
+ * blocks milestone completion (see #4375).
+ *
+ * This function performs DB writes only. The MCP wrapper in
+ * bootstrap/db-tools.ts handles state-cache invalidation and STATE.md rebuild.
+ */
+
+import {
+  getSlice,
+  getSliceTasks,
+  isDbAvailable,
+  transaction,
+  updateSliceStatus,
+  updateTaskStatus,
+} from "../gsd-db.js";
+import { isClosedStatus } from "../status-guards.js";
+
+/**
+ * Input parameters for {@link handleSkipSlice}.
+ *
+ * - `milestoneId` / `sliceId` identify the target slice.
+ * - `reason` is a free-form note surfaced in the MCP response; optional
+ *   because the caller (e.g. rethink flow) may not have a structured reason.
+ */
+export interface SkipSliceParams {
+  milestoneId: string;
+  sliceId: string;
+  reason?: string;
+}
+
+/**
+ * Stable machine-readable error codes for {@link SkipSliceResult.error}.
+ * Keep in sync with the wrapper in bootstrap/db-tools.ts.
+ */
+export type SkipSliceErrorCode = "slice_not_found" | "already_complete";
+
+/**
+ * Result of a {@link handleSkipSlice} call.
+ *
+ * - `tasksSkipped` — count of tasks whose status was cascaded to "skipped".
+ *   Zero is a valid success (slice had no non-closed tasks).
+ * - `wasAlreadySkipped` — true when the slice was in "skipped" status on
+ *   entry; callers can use this to distinguish first-skip from re-skip.
+ * - `error` / `errorCode` — set together for recoverable validation failures
+ *   (unknown slice, slice already complete). Both absent on success. DB
+ *   errors propagate as thrown exceptions and should be caught by the caller.
+ */
+export interface SkipSliceResult {
+  milestoneId: string;
+  sliceId: string;
+  tasksSkipped: number;
+  wasAlreadySkipped: boolean;
+  reason?: string;
+  error?: string;
+  errorCode?: SkipSliceErrorCode;
+}
+
+/**
+ * Mark a slice as "skipped" and cascade the skip to every non-closed task in
+ * that slice. Runs as a single transaction so slice status and task statuses
+ * are always consistent.
+ *
+ * Behaviour summary:
+ * - Unknown slice → returns {@link SkipSliceResult} with `error`.
+ * - Slice already complete/done → returns `error` (cannot un-complete).
+ * - Slice already skipped → still cascades leftover non-closed tasks
+ *   (heals inconsistent historical state from projects that ran older
+ *   versions before the #4375 cascade fix).
+ * - Tasks in closed status (complete/done/skipped) are never downgraded.
+ */
+export function handleSkipSlice(params: SkipSliceParams): SkipSliceResult {
+  const base: SkipSliceResult = {
+    milestoneId: params.milestoneId,
+    sliceId: params.sliceId,
+    tasksSkipped: 0,
+    wasAlreadySkipped: false,
+    reason: params.reason,
+  };
+
+  // Fail loudly on a closed DB so a `null` from getSlice() inside the
+  // transaction unambiguously means "slice not found", never "DB unavailable".
+  // The MCP wrapper in bootstrap/db-tools.ts runs ensureDbOpen() before calling
+  // this helper; this guard protects direct callers (tests, future code).
+  if (!isDbAvailable()) {
+    throw new Error("handleSkipSlice: GSD database is not available");
+  }
+
+  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ────
+  let guardError: string | null = null;
+  let guardCode: SkipSliceErrorCode | null = null;
+  let wasAlreadySkipped = false;
+  let tasksSkipped = 0;
+
+  transaction(() => {
+    const slice = getSlice(params.milestoneId, params.sliceId);
+    if (!slice) {
+      guardError = `Slice ${params.sliceId} not found in milestone ${params.milestoneId}`;
+      guardCode = "slice_not_found";
+      return;
+    }
+    if (slice.status === "complete" || slice.status === "done") {
+      guardError = `Slice ${params.sliceId} is already complete — cannot skip.`;
+      guardCode = "already_complete";
+      return;
+    }
+
+    wasAlreadySkipped = slice.status === "skipped";
+    if (!wasAlreadySkipped) {
+      updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
+    }
+
+    // Cascade: mark every non-closed task as skipped so milestone completion
+    // doesn't trip the deep-task guard (#4375). Closed tasks (complete/done/
+    // skipped) are left untouched — we never downgrade.
+    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+    for (const task of tasks) {
+      if (!isClosedStatus(task.status)) {
+        updateTaskStatus(params.milestoneId, params.sliceId, task.id, "skipped");
+        tasksSkipped++;
+      }
+    }
+  });
+
+  if (guardError) {
+    return { ...base, error: guardError, errorCode: guardCode ?? undefined };
+  }
+  return { ...base, tasksSkipped, wasAlreadySkipped };
+}

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -10,6 +10,8 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { saveArtifactToDb } from "../db-writer.js";
+import { resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { unlinkSync } from "node:fs";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -103,6 +105,18 @@ export async function executeSummarySave(
       },
       basePath,
     );
+
+    if (params.artifact_type === "CONTEXT" && !params.task_id) {
+      try {
+        const draftFile = params.slice_id
+          ? resolveSliceFile(basePath, params.milestone_id, params.slice_id, "CONTEXT-DRAFT")
+          : resolveMilestoneFile(basePath, params.milestone_id, "CONTEXT-DRAFT");
+        if (draftFile) unlinkSync(draftFile);
+      } catch (e) {
+        logWarning("tool", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`);
+      }
+    }
+
     return {
       content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
       details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },

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/verification-gate.ts

@@ -9,6 +9,7 @@ import { join, basename } from "node:path";
 import type { AuditWarning, RuntimeError, VerificationCheck, VerificationResult } from "./types.js";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./constants.js";
 import { rewriteCommandWithRtk } from "../shared/rtk.js";
+import { normalizePythonCommand } from "./python-resolver.js";
 
 /** Maximum bytes of stdout/stderr to retain per command (10 KB). */
 const MAX_OUTPUT_BYTES = 10 * 1024;
@@ -258,7 +259,7 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
 
   for (const command of commands) {
     const start = Date.now();
-    const rewrittenCommand = rewriteCommandWithRtk(command);
+    const rewrittenCommand = normalizePythonCommand(rewriteCommandWithRtk(command));
     // Pass the command string as an argument to the shell explicitly
     // to avoid Node.js DEP0190 (spawnSync with shell: true and no args).
     const shellBin = process.platform === "win32" ? "cmd" : "sh";

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;
+}