gsd-pi 2.75.0 → 2.76.0

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/memory-tools.ts

@@ -0,0 +1,380 @@
+// GSD Memory Tools — Phase 1 executors for capture_thought, memory_query, gsd_graph
+//
+// These executors back the three memory-layer tools the LLM can call at any
+// point in a session. They build on the existing `memory-store.ts` layer
+// (SQLite memories table) and degrade gracefully when the DB is unavailable.
+//
+// Phase 1 scope:
+//   - capture_thought → create a memory with the caller-supplied category/content
+//   - memory_query    → keyword-filtered, score-ranked listing of active memories
+//   - gsd_graph       → returns a memory and its supersedes edges only (Phase 4 adds memory_relations)
+
+import { _getAdapter, isDbAvailable } from "../gsd-db.js";
+import {
+  createMemory,
+  getActiveMemoriesRanked,
+  queryMemoriesRanked,
+  reinforceMemory,
+} from "../memory-store.js";
+import type { Memory, RankedMemory } from "../memory-store.js";
+import { traverseGraph } from "../memory-relations.js";
+
+// ─── Shared result shape (matches tools/workflow-tool-executors.ts) ─────────
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+function dbUnavailable(operation: string): ToolExecutionResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: "Error: GSD database is not available. Memory tools require an initialized .gsd/ project.",
+      },
+    ],
+    details: { operation, error: "db_unavailable" },
+    isError: true,
+  };
+}
+
+// ─── capture_thought ────────────────────────────────────────────────────────
+
+export interface MemoryCaptureParams {
+  category: string;
+  content: string;
+  confidence?: number;
+  tags?: string[];
+  scope?: string;
+}
+
+const VALID_CATEGORIES = new Set([
+  "architecture",
+  "convention",
+  "gotcha",
+  "preference",
+  "environment",
+  "pattern",
+]);
+
+export function executeMemoryCapture(params: MemoryCaptureParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("memory_capture");
+
+  const category = (params.category ?? "").trim().toLowerCase();
+  const content = (params.content ?? "").trim();
+  if (!category || !content) {
+    return {
+      content: [{ type: "text", text: "Error: category and content are required." }],
+      details: { operation: "memory_capture", error: "missing_fields" },
+      isError: true,
+    };
+  }
+  if (!VALID_CATEGORIES.has(category)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: invalid category "${category}". Must be one of: ${[...VALID_CATEGORIES].join(", ")}.`,
+        },
+      ],
+      details: { operation: "memory_capture", error: "invalid_category" },
+      isError: true,
+    };
+  }
+  const confidence = clampConfidence(params.confidence);
+  const scope = normalizeScope(params.scope);
+  const tags = normalizeTags(params.tags);
+
+  const id = createMemory({ category, content, confidence, scope, tags });
+  if (!id) {
+    return {
+      content: [{ type: "text", text: "Error: failed to create memory." }],
+      details: { operation: "memory_capture", error: "create_failed" },
+      isError: true,
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: `Captured ${id} (${category}): ${content}` }],
+    details: { operation: "memory_capture", id, category, confidence, scope, tags },
+  };
+}
+
+function normalizeScope(value: unknown): string {
+  if (typeof value !== "string") return "project";
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? "project" : trimmed;
+}
+
+function normalizeTags(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((t): t is string => typeof t === "string" && t.trim().length > 0).slice(0, 10);
+}
+
+function clampConfidence(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0.8;
+  if (value < 0.1) return 0.1;
+  if (value > 0.99) return 0.99;
+  return value;
+}
+
+// ─── memory_query ───────────────────────────────────────────────────────────
+
+export interface MemoryQueryParams {
+  query: string;
+  k?: number;
+  category?: string;
+  scope?: string;
+  tag?: string;
+  include_superseded?: boolean;
+  reinforce_hits?: boolean;
+}
+
+export interface MemoryQueryHit {
+  id: string;
+  category: string;
+  content: string;
+  confidence: number;
+  hit_count: number;
+  score: number;
+  reason: "keyword" | "semantic" | "both" | "ranked";
+  keyword_rank: number | null;
+  semantic_rank: number | null;
+}
+
+export function executeMemoryQuery(params: MemoryQueryParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("memory_query");
+
+  const query = (params.query ?? "").trim();
+  const k = clampTopK(params.k, 10);
+  const includeSuperseded = params.include_superseded === true;
+  const category = params.category?.trim().toLowerCase() || undefined;
+  const scopeFilter = params.scope?.trim() || undefined;
+  const tagFilter = params.tag?.trim().toLowerCase() || undefined;
+
+  try {
+    let ranked: RankedMemory[] = [];
+    if (query) {
+      ranked = queryMemoriesRanked({
+        query,
+        k,
+        category,
+        scope: scopeFilter,
+        tag: tagFilter,
+        include_superseded: includeSuperseded,
+      });
+    } else {
+      const candidates: Memory[] = includeSuperseded
+        ? includeSupersededMemories(getActiveMemoriesRanked(200))
+        : getActiveMemoriesRanked(200);
+      ranked = candidates
+        .filter((m) => {
+          if (category && m.category.toLowerCase() !== category) return false;
+          if (scopeFilter && m.scope !== scopeFilter) return false;
+          if (tagFilter && !m.tags.map((t) => t.toLowerCase()).includes(tagFilter)) return false;
+          return true;
+        })
+        .slice(0, k)
+        .map((memory) => ({
+          memory,
+          score: memory.confidence * (1 + memory.hit_count * 0.1),
+          keywordRank: null,
+          semanticRank: null,
+          confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
+          reason: "ranked" as const,
+        }));
+    }
+
+    const hits: MemoryQueryHit[] = ranked.map((r) => ({
+      id: r.memory.id,
+      category: r.memory.category,
+      content: r.memory.content,
+      confidence: r.memory.confidence,
+      hit_count: r.memory.hit_count,
+      score: r.score,
+      reason: r.reason,
+      keyword_rank: r.keywordRank,
+      semantic_rank: r.semanticRank,
+    }));
+
+    if (params.reinforce_hits) {
+      for (const h of hits) reinforceMemory(h.id);
+    }
+
+    const summary = hits.length === 0
+      ? "No matching memories."
+      : hits.map((h) => `- [${h.id}] (${h.category}) ${h.content}`).join("\n");
+
+    return {
+      content: [{ type: "text", text: summary }],
+      details: {
+        operation: "memory_query",
+        query,
+        k,
+        returned: hits.length,
+        hits,
+      },
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: memory query failed: ${(err as Error).message}` }],
+      details: { operation: "memory_query", error: (err as Error).message },
+      isError: true,
+    };
+  }
+}
+
+function clampTopK(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < 1) return 1;
+  if (value > 50) return 50;
+  return Math.floor(value);
+}
+
+function includeSupersededMemories(rankedActive: Memory[]): Memory[] {
+  const adapter = _getAdapter();
+  if (!adapter) return rankedActive;
+  try {
+    const rows = adapter.prepare("SELECT * FROM memories").all();
+    return rows.map((row) => {
+      let tags: string[] = [];
+      if (typeof row["tags"] === "string") {
+        try {
+          const parsed = JSON.parse(row["tags"] as string);
+          if (Array.isArray(parsed)) tags = parsed.filter((t): t is string => typeof t === "string");
+        } catch {
+          /* leave empty */
+        }
+      }
+      return {
+        seq: row["seq"] as number,
+        id: row["id"] as string,
+        category: row["category"] as string,
+        content: row["content"] as string,
+        confidence: row["confidence"] as number,
+        source_unit_type: (row["source_unit_type"] as string) ?? null,
+        source_unit_id: (row["source_unit_id"] as string) ?? null,
+        created_at: row["created_at"] as string,
+        updated_at: row["updated_at"] as string,
+        superseded_by: (row["superseded_by"] as string) ?? null,
+        hit_count: row["hit_count"] as number,
+        scope: (row["scope"] as string) ?? "project",
+        tags,
+      };
+    });
+  } catch {
+    return rankedActive;
+  }
+}
+
+// ─── gsd_graph ──────────────────────────────────────────────────────────────
+
+export interface GsdGraphParams {
+  mode: "build" | "query";
+  memoryId?: string;
+  depth?: number;
+  rel?: string;
+}
+
+export interface GraphNode {
+  id: string;
+  category: string;
+  content: string;
+  confidence: number;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  rel: string;
+  confidence: number;
+}
+
+export function executeGsdGraph(params: GsdGraphParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("gsd_graph");
+
+  if (params.mode === "build") {
+    // The extractor emits LINK actions incrementally (Phase 4). There is no
+    // batch rebuild step to run today — ingest artifacts via `/gsd memory
+    // extract <SRC-...>` and the next extraction turn will add edges.
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "gsd_graph build acknowledged. Graph edges are populated incrementally by memory " +
+            "extraction (including LINK actions). Use `/gsd memory extract <SRC-...>` to trigger " +
+            "extraction against a specific ingested source.",
+        },
+      ],
+      details: { operation: "gsd_graph", mode: "build", built: 0 },
+    };
+  }
+
+  if (params.mode !== "query") {
+    return {
+      content: [{ type: "text", text: `Error: unknown mode "${params.mode}". Must be "build" or "query".` }],
+      details: { operation: "gsd_graph", error: "invalid_mode" },
+      isError: true,
+    };
+  }
+
+  const memoryId = params.memoryId?.trim();
+  if (!memoryId) {
+    return {
+      content: [{ type: "text", text: "Error: memoryId is required for mode=query." }],
+      details: { operation: "gsd_graph", error: "missing_memory_id" },
+      isError: true,
+    };
+  }
+
+  try {
+    const graph = traverseGraph(memoryId, clampDepth(params.depth));
+    const rel = params.rel?.trim().toLowerCase() || null;
+    const edges = rel ? graph.edges.filter((e) => e.rel === rel) : graph.edges;
+    const relevantIds = new Set<string>([memoryId]);
+    for (const e of edges) {
+      relevantIds.add(e.from);
+      relevantIds.add(e.to);
+    }
+    const nodes = graph.nodes.filter((n) => relevantIds.has(n.id));
+
+    if (nodes.length === 0) {
+      return {
+        content: [{ type: "text", text: `No memory found with id ${memoryId}.` }],
+        details: { operation: "gsd_graph", mode: "query", memoryId, nodes: [], edges: [] },
+      };
+    }
+
+    const summary = [
+      `Memory ${memoryId} — ${nodes.length} node(s), ${edges.length} edge(s).`,
+      ...nodes.map((n) => `  [${n.id}] (${n.category}) ${n.content}`),
+      ...edges.map((e) => `  ${e.from} --${e.rel}-> ${e.to}`),
+    ].join("\n");
+    return {
+      content: [{ type: "text", text: summary }],
+      details: {
+        operation: "gsd_graph",
+        mode: "query",
+        memoryId,
+        nodes: nodes.map((n) => ({ id: n.id, category: n.category, content: n.content })),
+        edges: edges.map((e) => ({ from: e.from, to: e.to, rel: e.rel })),
+      },
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: graph query failed: ${(err as Error).message}` }],
+      details: { operation: "gsd_graph", error: (err as Error).message },
+      isError: true,
+    };
+  }
+}
+
+function clampDepth(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 1;
+  if (value < 0) return 0;
+  if (value > 5) return 5;
+  return Math.floor(value);
+}

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,