@opengsd/gsd-pi 1.1.1-dev.9f86580 → 1.1.1-dev.b2556262

package/src/resources/extensions/gsd/preferences-models.ts

@@ -19,6 +19,9 @@ import type {
   GSDPreferences,
   GSDModelConfigV2,
   GSDPhaseModelConfig,
+  GSDThinkingLevel,
+  GSDModelPhaseKey,
+  GSDThinkingConfig,
   ResolvedModelConfig,
   AutoSupervisorConfig,
 } from "./preferences-types.js";
@@ -37,82 +40,103 @@ export function resolveModelForUnit(unitType: string): string | undefined {
 }
 
 /**
- * Resolve model and fallbacks for a given auto-mode unit type.
- * Returns the primary model and ordered fallbacks, or undefined if not configured.
+ * Ordered phase-bucket chain a unit type resolves against, most-specific
+ * first. The first chain entry with a configured value wins; later entries
+ * are siblings the unit falls back to (e.g. `discuss → planning`).
  *
- * Supports both legacy string format and extended object format:
- * - Legacy: `planning: claude-opus-4-6`
- * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
+ * Single source of truth for the unit-type → phase mapping, shared by model
+ * resolution (`resolveModelWithFallbacksForUnit`) and thinking resolution
+ * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
-export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedModelConfig | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
-  const models = prefs?.preferences?.models;
-  if (!models) return undefined;
-  const m = models as GSDModelConfigV2;
-
-  let phaseConfig: string | GSDPhaseModelConfig | undefined;
+export function phaseChainForUnit(unitType: string): GSDModelPhaseKey[] | undefined {
   switch (unitType) {
     case "research-milestone":
     case "research-slice":
-      phaseConfig = m.research;
-      break;
+    // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
+    // and fans out research subagents. Routes to the research bucket.
+    case "research-project":
+      return ["research"];
     case "plan-milestone":
     case "plan-slice":
     case "refine-slice":
     case "replan-slice":
-      phaseConfig = m.planning;
-      break;
+      return ["planning"];
+    // Deep-mode project-level discussion units route to the same model bucket
+    // as milestone-level discussion (interactive interview style). Workflow
+    // preferences and research-decision are tiny ask_user_questions style units
+    // that share the discuss bucket because they are conversational. All fall
+    // back to planning when no `discuss` bucket is set.
     case "discuss-milestone":
     case "discuss-slice":
-    // Deep-mode project-level discussion units route to the same model
-    // bucket as milestone-level discussion (interactive interview style).
     case "discuss-project":
     case "discuss-requirements":
-    // Workflow preferences and research-decision are tiny ask_user_questions
-    // style units; they share the discuss bucket because they are
-    // conversational rather than research/execution. Falling back to planning
-    // when no `discuss` bucket is set keeps parity with the milestone units.
     case "workflow-preferences":
     case "research-decision":
-      phaseConfig = m.discuss ?? m.planning;
-      break;
-    // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
-    // and fans out research subagents. Routes to the research bucket so it
-    // gets the research-tier model when one is configured.
-    case "research-project":
-      phaseConfig = m.research;
-      break;
+      return ["discuss", "planning"];
     case "execute-task":
     case "reactive-execute":
-      phaseConfig = m.execution;
-      break;
+      return ["execution"];
     case "execute-task-simple":
-      phaseConfig = m.execution_simple ?? m.execution;
-      break;
+      return ["execution_simple", "execution"];
     case "complete-slice":
     case "complete-milestone":
     case "worktree-merge":
-      phaseConfig = m.completion;
-      break;
+      return ["completion"];
     case "run-uat":
-      phaseConfig = m.uat ?? m.completion;
-      break;
+      return ["uat", "completion"];
     case "reassess-roadmap":
     case "rewrite-docs":
     case "gate-evaluate":
     case "validate-milestone":
-      phaseConfig = m.validation ?? m.planning;
-      break;
+      return ["validation", "planning"];
     default:
       // Subagent unit types (e.g., "subagent", "subagent/scout")
       if (unitType === "subagent" || unitType.startsWith("subagent/")) {
-        phaseConfig = m.subagent;
-        break;
+        return ["subagent"];
       }
       return undefined;
   }
+}
 
-  if (!phaseConfig) return undefined;
+/**
+ * Find the phase bucket whose `models` entry wins the chain for a unit, plus
+ * that entry. Returns undefined when no phase in the chain is configured.
+ */
+function resolveWinningPhase(
+  models: GSDModelConfigV2 | undefined,
+  chain: GSDModelPhaseKey[],
+): { phase: GSDModelPhaseKey; config: string | GSDPhaseModelConfig } | undefined {
+  if (!models) return undefined;
+  for (const key of chain) {
+    const config = models[key];
+    // Falsy check (not `!= null`) so an empty-string model is treated as
+    // unconfigured and the chain falls through — matches the pre-refactor
+    // switch, which bailed via `if (!phaseConfig)`.
+    if (!config) continue;
+    // An object entry only "wins" if it provides a usable model. A model-less
+    // object (e.g. `{ provider: x }`, or `{}` left after stripping an invalid
+    // `thinking`) must not shadow sibling fallback or yield `{ primary: undefined }`.
+    if (typeof config === "object" && !config.model) continue;
+    return { phase: key, config };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve model and fallbacks for a given auto-mode unit type.
+ * Returns the primary model and ordered fallbacks, or undefined if not configured.
+ *
+ * Supports both legacy string format and extended object format:
+ * - Legacy: `planning: claude-opus-4-6`
+ * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
+ */
+export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedModelConfig | undefined {
+  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+  const chain = phaseChainForUnit(unitType);
+  if (!chain) return undefined;
+  const winner = resolveWinningPhase(prefs?.preferences?.models as GSDModelConfigV2 | undefined, chain);
+  if (!winner) return undefined;
+  const phaseConfig = winner.config;
 
   // Normalize: string -> { model, fallbacks: [] }
   if (typeof phaseConfig === "string") {
@@ -131,6 +155,51 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
   };
 }
 
+/**
+ * Resolve the explicitly configured reasoning effort for a unit type (ADR-026).
+ *
+ * Thinking travels with the model. The chain is walked most-specific-first up to
+ * and including the phase whose model won; at each level inline
+ * `models.<phase>.thinking` is preferred, then the same phase's `thinking` block
+ * entry. This means:
+ * - a more-specific block key (`thinking.execution_simple`) surfaces even when
+ *   the model only resolves on a less-specific sibling (`models.execution`);
+ * - inline thinking is honored even on a model-less `models.<phase>` entry
+ *   (e.g. `{ thinking: "high" }` with no `model`);
+ * - a unit that claimed its own model bucket never borrows a *less*-specific
+ *   sibling's thinking (the walk stops at the winning phase).
+ * When no model is configured anywhere in the chain, the walk spans the full
+ * chain so inline thinking and the `thinking` block both resolve on their own
+ * sibling chain.
+ *
+ * Returns undefined when nothing explicit is configured — the dispatch path
+ * then falls back to the session/default level and applies the code-writing
+ * floor. Session level, defaults, the floor, and capability clamping are NOT
+ * applied here.
+ */
+export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel | undefined {
+  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] })?.preferences;
+  if (!prefs) return undefined;
+  const chain = phaseChainForUnit(unitType);
+  if (!chain) return undefined;
+
+  const models = prefs.models as GSDModelConfigV2 | undefined;
+  const block = prefs.thinking as GSDThinkingConfig | undefined;
+
+  // Walk most-specific-first, up to and including the winning model phase (or
+  // the full chain when no model is configured), checking inline then block.
+  const winner = resolveWinningPhase(models, chain);
+  const limit = winner ? chain.indexOf(winner.phase) + 1 : chain.length;
+  for (let i = 0; i < limit; i++) {
+    const key = chain[i];
+    const entry = models?.[key];
+    if (typeof entry === "object" && entry?.thinking) return entry.thinking; // inline (incl. model-less)
+    const blockLevel = block?.[key];
+    if (blockLevel) return blockLevel;                                       // block
+  }
+  return undefined;
+}
+
 /**
  * Resolve the default session model from GSD preferences.
  *

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

@@ -99,6 +99,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "skill_rules",
   "custom_instructions",
   "models",
+  "thinking",
   "skill_discovery",
   "skill_staleness_days",
   "auto_supervisor",
@@ -198,6 +199,28 @@ export interface GSDSkillRule {
   avoid?: string[];
 }
 
+/**
+ * Reasoning effort levels. Mirrors `ThinkingLevel` in `@gsd/pi-agent-core`;
+ * declared locally so preference parsing/validation does not import the agent
+ * core package. `xhigh` is only honored by models whose `thinkingLevelMap`
+ * advertises it — unsupported levels are clamped at dispatch (ADR-026).
+ */
+export type GSDThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** The nine model-routing phase buckets. */
+export const GSD_MODEL_PHASE_KEYS = [
+  "research",
+  "planning",
+  "discuss",
+  "execution",
+  "execution_simple",
+  "completion",
+  "validation",
+  "subagent",
+  "uat",
+] as const;
+export type GSDModelPhaseKey = (typeof GSD_MODEL_PHASE_KEYS)[number];
+
 /**
  * Model configuration for a single phase.
  * Supports primary model with optional fallbacks for resilience.
@@ -209,8 +232,22 @@ export interface GSDPhaseModelConfig {
   provider?: string;
   /** Fallback models to try in order if primary fails (e.g., rate limits, credits exhausted) */
   fallbacks?: string[];
+  /**
+   * Reasoning effort for this phase (ADR-026). Travels with the model: an
+   * explicit value here bypasses the `execute-task` thinking floor and is
+   * capability-clamped to the resolved model at dispatch. Takes precedence
+   * over a same-phase entry in the separate `thinking` block.
+   */
+  thinking?: GSDThinkingLevel;
 }
 
+/**
+ * Separate per-phase reasoning-effort block (ADR-026). An alternative to
+ * inline `models.<phase>.thinking` that lets thinking be pinned without
+ * pinning a model. Same nine phase keys as `models`.
+ */
+export type GSDThinkingConfig = Partial<Record<GSDModelPhaseKey, GSDThinkingLevel>>;
+
 /**
  * Legacy model config -- simple string per phase.
  * Kept for backward compatibility; will be migrated to GSDModelConfigV2 on load.
@@ -372,6 +409,8 @@ export interface GSDPreferences {
   skill_rules?: GSDSkillRule[];
   custom_instructions?: string[];
   models?: GSDModelConfig | GSDModelConfigV2;
+  /** Per-phase reasoning effort, separate from `models` (ADR-026). */
+  thinking?: GSDThinkingConfig;
   skill_discovery?: SkillDiscoveryMode;
   skill_staleness_days?: number;  // Skills unused for N days get deprioritized (#599). 0 = disabled. Default: 60.
   auto_supervisor?: AutoSupervisorConfig;

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -12,18 +12,30 @@ import type { DynamicRoutingConfig } from "./model-router.js";
 import { isAbsolute } from "node:path";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
+import { getGateIdsForTurn } from "./gate-registry.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
   KNOWN_UNIT_LABELS,
+  GSD_MODEL_PHASE_KEYS,
 
   SKILL_ACTIONS,
   type WorkflowMode,
   type GSDPreferences,
   type GSDSkillRule,
+  type GSDThinkingLevel,
 } from "./preferences-types.js";
 
 const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
+const VALID_THINKING_LEVELS = new Set<GSDThinkingLevel>([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]);
+const KNOWN_MODEL_PHASE_KEYS = new Set<string>(GSD_MODEL_PHASE_KEYS);
 const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
   "commit",
   "snapshot",
@@ -37,6 +49,7 @@ const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
   "queue-slice",
   "pause",
 ]);
+const VALID_GATE_EVALUATE_SLICE_GATES = new Set<string>(getGateIdsForTurn("gate-evaluate"));
 
 export function validatePreferences(preferences: GSDPreferences): {
   preferences: GSDPreferences;
@@ -390,12 +403,66 @@ export function validatePreferences(preferences: GSDPreferences): {
   // ─── Models ─────────────────────────────────────────────────────────
   if (preferences.models !== undefined) {
     if (preferences.models && typeof preferences.models === "object") {
-      validated.models = preferences.models;
+      // Static check for inline per-phase thinking (ADR-026). The resolved
+      // model isn't known until dispatch, so capability is clamped there; here
+      // we warn on illegal level strings AND strip them, so a typo can't reach
+      // resolveThinkingLevelForUnit and be treated as explicit configuration.
+      const sanitizedModels: Record<string, unknown> = {};
+      for (const [phase, entry] of Object.entries(preferences.models as Record<string, unknown>)) {
+        if (entry && typeof entry === "object" && "thinking" in entry) {
+          const level = (entry as { thinking?: unknown }).thinking;
+          if (level !== undefined && !VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
+            warnings.push(
+              `models.${phase}.thinking "${String(level)}" is not a valid thinking level ` +
+              `(off, minimal, low, medium, high, xhigh) — ignored`,
+            );
+            const { thinking: _ignored, ...rest } = entry as Record<string, unknown>;
+            // If stripping the bad thinking leaves no usable model, drop the
+            // phase entirely rather than storing a hollow `{}` / `{ provider }`
+            // entry that resolveWinningPhase would otherwise treat as configured.
+            if (rest.model) {
+              sanitizedModels[phase] = rest;
+            }
+            continue;
+          }
+        }
+        sanitizedModels[phase] = entry;
+      }
+      validated.models = sanitizedModels as GSDPreferences["models"];
     } else {
       errors.push("models must be an object");
     }
   }
 
+  // ─── Thinking (separate per-phase block, ADR-026) ───────────────────
+  if (preferences.thinking !== undefined) {
+    if (preferences.thinking && typeof preferences.thinking === "object" && !Array.isArray(preferences.thinking)) {
+      const validatedThinking: Record<string, GSDThinkingLevel> = {};
+      for (const [phase, level] of Object.entries(preferences.thinking as Record<string, unknown>)) {
+        if (!KNOWN_MODEL_PHASE_KEYS.has(phase)) {
+          warnings.push(
+            `unknown thinking phase "${phase}" — must be one of: ` +
+            `${[...KNOWN_MODEL_PHASE_KEYS].join(", ")} — ignored`,
+          );
+          continue;
+        }
+        if (!VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
+          warnings.push(
+            `thinking.${phase} "${String(level)}" is not a valid thinking level ` +
+            `(off, minimal, low, medium, high, xhigh) — ignored`,
+          );
+          continue;
+        }
+        validatedThinking[phase] = level as GSDThinkingLevel;
+      }
+      if (Object.keys(validatedThinking).length > 0) {
+        validated.thinking = validatedThinking;
+      }
+    } else {
+      errors.push("thinking must be an object");
+    }
+  }
+
   // ─── Auto Supervisor ────────────────────────────────────────────────
   if (preferences.auto_supervisor !== undefined) {
     if (preferences.auto_supervisor && typeof preferences.auto_supervisor === "object") {
@@ -907,7 +974,14 @@ export function validatePreferences(preferences: GSDPreferences): {
       }
       if (ge.slice_gates !== undefined) {
         if (Array.isArray(ge.slice_gates) && ge.slice_gates.every((g: unknown) => typeof g === "string")) {
-          validGe.slice_gates = ge.slice_gates;
+          const invalid = ge.slice_gates.filter((g) => !VALID_GATE_EVALUATE_SLICE_GATES.has(g));
+          if (invalid.length === 0) {
+            validGe.slice_gates = ge.slice_gates;
+          } else {
+            errors.push(
+              `gate_evaluation.slice_gates must contain only gate-evaluate slice gates: ${[...VALID_GATE_EVALUATE_SLICE_GATES].join(", ")}`,
+            );
+          }
         } else {
           errors.push("gate_evaluation.slice_gates must be an array of strings");
         }

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

@@ -86,6 +86,8 @@ export function resolveSkillStalenessDays(basePath?: string): number {
 export {
   resolveModelForUnit,
   resolveModelWithFallbacksForUnit,
+  resolveThinkingLevelForUnit,
+  phaseChainForUnit,
   getNextFallbackModel,
   isTransientNetworkError,
   validateModelId,
@@ -437,6 +439,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     skill_rules: [...(base.skill_rules ?? []), ...(override.skill_rules ?? [])],
     custom_instructions: mergeStringLists(base.custom_instructions, override.custom_instructions),
     models: { ...(base.models ?? {}), ...(override.models ?? {}) },
+    thinking: (base.thinking || override.thinking)
+      ? { ...(base.thinking ?? {}), ...(override.thinking ?? {}) }
+      : undefined,
     skill_discovery: override.skill_discovery ?? base.skill_discovery,
     skill_staleness_days: override.skill_staleness_days ?? base.skill_staleness_days,
     auto_supervisor: { ...(base.auto_supervisor ?? {}), ...(override.auto_supervisor ?? {}) },

package/src/resources/extensions/gsd/prompts/gate-evaluate.md

@@ -38,7 +38,7 @@ You are evaluating **quality gates in parallel** for this slice. Each gate is an
 3. **Verify each gate wrote its result** by checking that `gsd_save_gate_result` was called for each gate ID.
    - Call it **directly** — do **not** use `ToolSearch` (it is not available in GSD).
    - Inside Claude Code use the active MCP-scoped workflow name for `gsd_save_gate_result`; otherwise use `gsd_save_gate_result`.
-   - Always pass all required fields (camelCase): `milestoneId`, `sliceId`, `gateId`, `verdict`, `rationale`. Never call with an empty `{}` object.
+   - Always pass all required fields (camelCase): `milestoneId`, `sliceId`, `gateId`, `verdict`, `rationale`, and `findings` (empty string if none). Never call with an empty `{}` object.
 4. **Report the batch outcome** — which gates passed, which flagged concerns, and which were omitted as not applicable.
 
 Gate agents may return `verdict: "omitted"` if the gate question is not applicable to this slice (e.g., no auth surface for Q3, no existing requirements touched for Q4). This is expected for simple slices.

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -44,7 +44,7 @@ If slice research is inlined, trust its architectural findings, but verify every
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, or tests — those belong only in `inputs`. If a task is a pure verification or test task that produces no new files, `expectedOutput` may be `[]` or limited to test-result artifacts (e.g. a log or assertion output). A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
+9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
 10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

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

@@ -64,7 +64,7 @@ Then:
 2. {{skillActivation}} Record the installed skills you expect executors to use in each task plan's `skills_used` frontmatter.
 3. Define slice-level verification: the objective stopping condition. Plan real test files with real assertions; for simple slices, executable commands are fine.
 4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
-5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`).
+5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks.
 6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
 7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task. Inputs and Expected Output are backtick-wrapped file paths.
 8. If refinement produced structural decisions that diverge from the sketch, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -193,7 +193,12 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
         ? expandDependencies(depsMatch[1]!.split(",").map(s => s.trim()))
         : [];
 
-      currentSlice = { id, title, risk, depends, done, demo: "" };
+      // ADR-011: the renderer writes a `[sketch]` badge for sketch slices.
+      // Parse it back so the is_sketch flag survives a markdown → DB re-import
+      // (e.g. /gsd recover); otherwise the flag was silently lost.
+      const isSketch = /\[sketch\]/i.test(rest);
+
+      currentSlice = { id, title, risk, depends, done, demo: "", isSketch };
       continue;
     }
 

package/src/resources/extensions/gsd/safety/content-validator.ts

@@ -11,7 +11,7 @@ import { logWarning } from "../workflow-logger.js";
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 export interface ContentViolation {
-  severity: "warning";
+  severity: "error" | "warning";
   reason: string;
 }
 
@@ -46,6 +46,9 @@ export function validateContent(
 
 type ContentValidatorFn = (content: string) => ContentViolation[];
 
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
+
 const VALIDATORS: Record<string, ContentValidatorFn> = {
   "plan-slice": validatePlanSlice,
   "plan-milestone": validatePlanMilestone,
@@ -55,10 +58,10 @@ function validatePlanSlice(content: string): ContentViolation[] {
   const violations: ContentViolation[] = [];
 
   // Must have at least 1 task entry — single-task slices are valid (#3649)
-  const taskCount = (content.match(/- \[[ x]\] \*\*T\d+/g) || []).length;
+  const taskCount = (content.match(TASK_MARKER_RE) || []).length;
   if (taskCount < 1) {
     violations.push({
-      severity: "warning",
+      severity: "error",
       reason: `Slice plan has ${taskCount} task(s) — expected at least 1`,
     });
   }
@@ -86,10 +89,10 @@ function validatePlanMilestone(content: string): ContentViolation[] {
   const violations: ContentViolation[] = [];
 
   // Must have at least 1 slice entry
-  const sliceCount = (content.match(/##\s+S\d+/g) || []).length;
+  const sliceCount = (content.match(SLICE_MARKER_RE) || []).length;
   if (sliceCount < 1) {
     violations.push({
-      severity: "warning",
+      severity: "error",
       reason: `Milestone roadmap has ${sliceCount} slice(s) — expected at least 1`,
     });
   }