@opengsd/gsd-pi 1.6.0 → 1.7.0-dev.30c4ec2f

package/src/resources/extensions/gsd/md-importer.ts

@@ -810,8 +810,13 @@ export function migrateHierarchyToDb(basePath: string): {
       }
       counts.slices++;
 
-      // Insert tasks from parsed plan
-      if (!plan) continue;
+      // Insert tasks from parsed plan.
+      // Sketch slices carry only a stub PLAN until refined; do not seed DB
+      // tasks from a placeholder <tasks> block (would falsely flip
+      // planning -> executing before the slice is decomposed). Once the
+      // `[sketch]` badge is removed by a real plan-slice, tasks import
+      // normally on the next pass. (#1286)
+      if (!plan || sliceEntry.isSketch) continue;
 
       for (const taskEntry of plan.tasks) {
         // Per K002: use 'complete' not 'done'

package/src/resources/extensions/gsd/migrate/planning-writer.ts

@@ -11,6 +11,7 @@ import { join, relative } from "node:path";
 
 import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
 import { saveFile } from "../files.js";
+import { isClosedStatus } from "../status-guards.js";
 import type { PlanningLayout } from "../compat/compat-marker.js";
 import {
   applyPlanningProjectionWrites,
@@ -104,7 +105,7 @@ function formatPlanningPlan(
   phaseNum: number,
   planNum: number,
   title: string,
-  tasks: Array<{ id: string; title: string; estimate?: string }>,
+  tasks: Array<{ id: string; title: string; estimate?: string; done?: boolean }>,
 ): string {
   const lines: string[] = [];
   lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
@@ -115,7 +116,11 @@ function formatPlanningPlan(
   lines.push("<tasks>");
   for (const t of tasks) {
     const est = t.estimate ? ` _(${t.estimate})_` : "";
-    lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+    // Render the checkbox from the task's DB status so a DB→.planning
+    // projection preserves completion. Hardcoding `[ ]` here silently reset
+    // every completed historical task to unchecked on each reconcile (#1276).
+    const box = t.done ? "[x]" : "[ ]";
+    lines.push(`- ${box} **${t.id}**: ${t.title}${est}`);
   }
   lines.push("</tasks>");
   lines.push("");
@@ -173,7 +178,7 @@ export async function writePlanningDirectory(
 
       const tasks = getSliceTasks(milestone.id, slice.id);
       const isDone =
-        tasks.length > 0 && tasks.every((t) => t.status === "complete");
+        tasks.length > 0 && tasks.every((t) => isClosedStatus(t.status));
       roadmapEntries.push({
         number: phaseNum,
         title: slice.title || slice.id,
@@ -204,6 +209,7 @@ export async function writePlanningDirectory(
                 id: task.id,
                 title: task.title || task.id,
                 estimate: task.estimate || undefined,
+                done: isClosedStatus(task.status),
               },
             ]),
           );

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -169,6 +169,9 @@ export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
 
     for (const slice of roadmap.slices) {
       scan.slices.add(`${milestoneId}/${slice.id}`);
+      // Sketch slices carry only a stub PLAN until refined; match migrateHierarchyToDb
+      // and do not count placeholder tasks from the <tasks> block (#1286).
+      if (slice.isSketch) continue;
       const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
       if (!planPath || !existsSync(planPath)) continue;
       const plan = parsePlan(readFileSync(planPath, "utf-8"));

package/src/resources/extensions/gsd/reopen-reason.ts

@@ -0,0 +1,109 @@
+// Project/App: gsd-pi
+// File Purpose: Persist a reopened task's failure diagnosis and inject it into the re-dispatched execute-task prompt.
+// GSD Extension — follow-up to #1225 (#1272)
+//
+// When complete-slice's gate reopens a task via gsd_task_reopen, the operator
+// supplies a `reason` explaining exactly what the full-suite gate caught and
+// how to fix it. That reason previously only landed in the workflow event log
+// (audit trail) and never reached the re-dispatched executor, so the executor
+// re-ran the original (green) verify and re-completed the task without touching
+// the regression. This module is the "inject unresolved context into the next
+// dispatch" mechanism for reopen reasons — a lightweight, file-based sibling of
+// escalation.js#claimOverrideForInjection, keyed by (milestone, slice, task).
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { logWarning } from "./workflow-logger.js";
+
+interface ReopenReasonArtifact {
+  version: 1;
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  reason: string;
+  createdAt: string;
+}
+
+/**
+ * Canonical reopen-reason artifact path, parallel to T##-SUMMARY.md and
+ * T##-ESCALATION.json:
+ *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-REOPEN.json
+ * Flat-phase: the artifact sits directly in the phase dir. Legacy layouts
+ * without a tasks/ subdir return null (caller degrades gracefully).
+ */
+export function reopenReasonArtifactPath(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+): string | null {
+  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (tDir) return join(tDir, `${taskId}-REOPEN.json`);
+  if (existsSync(legacyMilestonesDir(basePath))) return null;
+  const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!phaseDir) return null;
+  return join(phaseDir, `${taskId}-REOPEN.json`);
+}
+
+/**
+ * Persist the reopen reason so the next execute-task dispatch can surface it.
+ * A no-op when the reason is empty or the artifact path cannot be resolved —
+ * reopen itself must still succeed even if we cannot attach context.
+ */
+export function writeReopenReason(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string, reason: string,
+): void {
+  const trimmed = reason.trim();
+  if (!trimmed) return;
+  const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+  if (!path) {
+    logWarning("tool", `reopen-reason: cannot resolve artifact path for ${milestoneId}/${sliceId}/${taskId}; reopen reason not attached to next dispatch`);
+    return;
+  }
+  const artifact: ReopenReasonArtifact = {
+    version: 1,
+    milestoneId, sliceId, taskId,
+    reason: trimmed,
+    createdAt: new Date().toISOString(),
+  };
+  mkdirSync(join(path, ".."), { recursive: true });
+  atomicWriteSync(path, JSON.stringify(artifact, null, 2));
+}
+
+/**
+ * If a reopen reason is pending for this task, claim it (one-shot: the artifact
+ * is deleted on read) and return the markdown block to prepend to the executor's
+ * prompt. Returns null when nothing is pending or the artifact is malformed.
+ */
+export function claimReopenReasonForInjection(
+  basePath: string, milestoneId: string, sliceId: string, taskId: string,
+): { injectionBlock: string } | null {
+  const path = reopenReasonArtifactPath(basePath, milestoneId, sliceId, taskId);
+  if (!path || !existsSync(path)) return null;
+  let art: ReopenReasonArtifact | null = null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<ReopenReasonArtifact>;
+    if (parsed && parsed.version === 1 && typeof parsed.reason === "string" && parsed.reason.trim()) {
+      art = parsed as ReopenReasonArtifact;
+    }
+  } catch {
+    art = null;
+  }
+  // Claim (delete) regardless of validity so a malformed artifact doesn't
+  // wedge every future dispatch of this task.
+  try { unlinkSync(path); } catch { /* already gone */ }
+  if (!art) return null;
+  return { injectionBlock: formatReopenReasonBlock(art) };
+}
+
+function formatReopenReasonBlock(art: ReopenReasonArtifact): string {
+  return [
+    `## Reopened — Reason (from ${art.taskId})`,
+    "",
+    "This task was previously marked complete but a downstream gate (e.g. complete-slice's full-suite run) reopened it. The verify command in your task plan passed in isolation — it did **not** catch the regression below. Do **not** call `gsd_task_complete` until you have reproduced and fixed exactly what this diagnosis describes, then re-run the specific failing command it names (not just the original scoped verify).",
+    "",
+    "**Diagnosis / fix instructions from the gate:**",
+    "",
+    art.reason.trim(),
+  ].join("\n");
+}

package/src/resources/extensions/gsd/session-status-io.ts

@@ -48,6 +48,11 @@ const PARALLEL_DIR = "parallel";
 const STATUS_SUFFIX = ".status.json";
 const SIGNAL_SUFFIX = ".signal.json";
 const DEFAULT_STALE_TIMEOUT_MS = 30_000;
+// How long a paused worker waits for the coordinator to lift the pause before
+// it degrades to in-process serialization (#1273). Kept below the stale
+// timeout so the wait never races the coordinator's liveness detection.
+const DEFAULT_RESUME_WAIT_MS = 10_000;
+const DEFAULT_RESUME_POLL_MS = 250;
 
 function isSessionStatus(data: unknown): data is SessionStatus {
   return data !== null && typeof data === "object" && "milestoneId" in data && "pid" in data;
@@ -143,6 +148,35 @@ export function consumeSignal(basePath: string, milestoneId: string): SignalMess
   return msg;
 }
 
+/**
+ * Wait for a coordinator to lift a `pause` on a worker by sending `resume`
+ * (or `stop`). Polls the signal file until one of those arrives or the timeout
+ * elapses. Intervening `pause`/`rebase` signals are consumed and ignored so a
+ * repeated pause doesn't reset the wait.
+ *
+ * A worker's `pause` is only ever lifted by the interactive/dashboard resumer;
+ * unattended `gsd headless auto` owns no resumer, so callers use the `"timeout"`
+ * result to degrade to in-process serialization instead of stranding the worker
+ * at a terminal pause it cannot resume (#1273).
+ */
+export async function awaitWorkerResume(
+  basePath: string,
+  milestoneId: string,
+  opts: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<"resume" | "stop" | "timeout"> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_RESUME_WAIT_MS;
+  const pollMs = opts.pollMs ?? DEFAULT_RESUME_POLL_MS;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const msg = consumeSignal(basePath, milestoneId);
+    if (msg?.signal === "resume") return "resume";
+    if (msg?.signal === "stop") return "stop";
+    if (Date.now() >= deadline) return "timeout";
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 // ─── Stale Detection ───────────────────────────────────────────────────────
 
 /** Check whether a session is stale (PID dead or heartbeat timed out). */

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -7,8 +7,8 @@
 
 import { existsSync } from "node:fs";
 
-import { getMilestone, isDbAvailable } from "../../gsd-db.js";
-import { findMilestoneIds } from "../../milestone-ids.js";
+import { getAllMilestones, getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { findMilestoneIds, parseMilestoneId } from "../../milestone-ids.js";
 import { resolveMilestoneFile, resolveMilestonePath } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -29,6 +29,26 @@ function milestoneHasContent(basePath: string, milestoneId: string): boolean {
   );
 }
 
+/**
+ * A directory extracted to a bare `M{NNN}` id is not unregistered when the
+ * milestone is actually registered under a `unique_milestone_ids` suffixed id
+ * (`M{NNN}-<suffix>`) for the same sequence number. The flat-phase extractor in
+ * `milestone-ids` cannot recover the suffix from a descriptive slug (e.g.
+ * `07-v40fmq-m007-...-footer-system`), so it falls through to the bare `M007`.
+ * Probing the DB for a suffixed row on that sequence resolves the directory to
+ * its registered identity instead of firing a false-positive drift (issue
+ * #1281).
+ */
+function hasRegisteredSuffixedVariant(milestoneId: string): boolean {
+  const { suffix, num } = parseMilestoneId(milestoneId);
+  // Only bare, well-formed `M{NNN}` ids can be ambiguous with a suffixed row.
+  if (suffix || num === 0) return false;
+  return getAllMilestones().some((m) => {
+    const parsed = parseMilestoneId(m.id);
+    return parsed.num === num && parsed.suffix !== undefined;
+  });
+}
+
 export function detectUnregisteredMilestoneDrift(
   _state: GSDState,
   ctx: DriftContext,
@@ -38,6 +58,7 @@ export function detectUnregisteredMilestoneDrift(
   const drifts: UnregisteredMilestoneDrift[] = [];
   for (const milestoneId of findMilestoneIds(ctx.basePath)) {
     if (getMilestone(milestoneId)) continue;
+    if (hasRegisteredSuffixedVariant(milestoneId)) continue;
     if (!milestoneHasContent(ctx.basePath, milestoneId)) continue;
     drifts.push({ kind: "unregistered-milestone", milestoneId });
   }
@@ -45,35 +66,61 @@ export function detectUnregisteredMilestoneDrift(
 }
 
 /**
- * Repair intentionally fails closed. The project-root DB is authoritative at
- * runtime; markdown-only milestones must be reconciled through an explicit,
- * operator-controlled action so operators opt into changing canonical state.
- *
- * The hint deliberately leads with the *targeted*, non-destructive options. The
- * common cause of this drift is a directory left under an old ID after a
- * `unique_milestone_ids` rename, where the right fix is to rename (move) the
- * directory — not a full DB reimport. `/gsd recover --confirm` is a destructive
- * clear-and-reimport of the entire DB and is offered only as a last resort, so
- * users do not reach for it expecting a targeted repair (see issue #826).
+ * The recovery hint deliberately leads with the *targeted*, non-destructive
+ * options. The common cause of this drift is a directory left under an old ID
+ * after a `unique_milestone_ids` rename, where the right fix is to rename (move)
+ * the directory — not a full DB reimport. `/gsd recover --confirm` is a
+ * destructive clear-and-reimport of the entire DB and is offered only as a last
+ * resort, so users do not reach for it expecting a targeted repair (see issue
+ * #826).
  */
-export function repairUnregisteredMilestone(
+function unregisteredMilestoneGuidance(
   record: UnregisteredMilestoneDrift,
   ctx: DriftContext,
-): void {
+): string {
   const dir = resolveMilestonePath(ctx.basePath, record.milestoneId);
   const dirHint = dir ?? `the .gsd directory for ${record.milestoneId}`;
-  throw new Error(
+  return (
     `Milestone ${record.milestoneId} exists only as markdown projection ` +
-      "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
-      "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
-      `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
-      `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
-      "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones.",
+    "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
+    "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
+    `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
+    `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
+    "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones."
   );
 }
 
+/**
+ * Terminal blocker for an unregistered milestone. The project-root DB is
+ * authoritative at runtime; markdown-only milestones must be reconciled through
+ * an explicit, operator-controlled action so operators opt into changing
+ * canonical state. Exposing this as a `blocker` (matching the `artifact-db`
+ * convention) surfaces the drift as a pause-with-hint that gates dispatch,
+ * instead of a guaranteed repair throw that escalates auto-mode health to red
+ * (see issue #1281).
+ */
+export function describeUnregisteredMilestoneBlocker(
+  record: UnregisteredMilestoneDrift,
+  ctx: DriftContext,
+): string {
+  return unregisteredMilestoneGuidance(record, ctx);
+}
+
+/**
+ * Repair intentionally fails closed. Retained as a defensive fallback for the
+ * reconciliation engine; in practice `blocker` short-circuits this drift into a
+ * non-fatal pause before repair is ever attempted.
+ */
+export function repairUnregisteredMilestone(
+  record: UnregisteredMilestoneDrift,
+  ctx: DriftContext,
+): void {
+  throw new Error(unregisteredMilestoneGuidance(record, ctx));
+}
+
 export const unregisteredMilestoneHandler: DriftHandler<UnregisteredMilestoneDrift> = {
   kind: "unregistered-milestone",
   detect: detectUnregisteredMilestoneDrift,
+  blocker: describeUnregisteredMilestoneBlocker,
   repair: repairUnregisteredMilestone,
 };

package/src/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.ts

@@ -8,13 +8,14 @@
 //      sketch slices to plan-slice, which writes PLAN.md but leaves
 //      is_sketch=1 — the next reconciliation pass clears it.
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 import {
   getSketchedSliceIds,
   isDbAvailable,
   setSliceSketchFlag,
 } from "../../gsd-db.js";
+import { parsePlan } from "../../parsers-legacy.js";
 import { resolveSliceFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -31,13 +32,54 @@ export function detectStaleSketchFlags(
 
   const sliceIds = getSketchedSliceIds(mid);
   return sliceIds
-    .filter((sid) => {
-      const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
-      return planPath !== null && existsSync(planPath);
-    })
+    .filter((sid) => sketchIsPlanned(ctx.basePath, mid, sid))
     .map((sid) => ({ kind: "stale-sketch-flag" as const, mid, sid }));
 }
 
+/**
+ * True when a task title is a synthetic placeholder emitted by a projection
+ * round-trip rather than a real, refined task. `migrate/transformer.buildTaskTitle`
+ * produces two shapes when a plan was never decomposed:
+ *   - `Plan NN`            (fallback when phase/plan frontmatter is absent)
+ *   - `${phase} ${plan}`   (e.g. `00 01`, `00 03b`, `29-auth-system 01`)
+ * Neither carries genuine planning intent, so both must be treated as stubs.
+ */
+function isPlaceholderTaskTitle(title: string): boolean {
+  const t = title.trim();
+  if (/^Plan\s+\d+[a-z]*$/i.test(t)) return true;
+  // buildTaskTitle returns `${phase} ${plan}` when frontmatter has both fields.
+  // Phase slugs are digit-led (e.g. `00`, `29-auth-system`); require that so
+  // legitimate titles like `Step 1` are not misclassified as stubs.
+  return /^\d[\w-]*\s+\d+[a-z]*$/i.test(t);
+}
+
+/**
+ * A sketch slice counts as "planned" (so its is_sketch flag may be cleared)
+ * only when it has a *real* plan on disk — not merely any PLAN file.
+ *
+ * File existence alone (#1287) is too weak: a stub/placeholder PLAN, a
+ * crash-leftover, or a projection round-trip that emits synthetic placeholder
+ * task titles (migrate/transformer.buildTaskTitle) all satisfy existsSync yet
+ * were never actually refined. Clearing the flag for one strips the `refining`
+ * guard in phase derivation and lets a phantom task drive dispatch.
+ *
+ * A legitimate plan-slice always decomposes into >= 1 genuine task, so require
+ * at least one non-placeholder task. This is strictly stricter than the old
+ * existence check — the documented crash-recovery scenarios (a real plan-slice
+ * that wrote its tasks) still clear, a bare stub no longer does.
+ */
+function sketchIsPlanned(basePath: string, mid: string, sid: string): boolean {
+  const planPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+  if (planPath === null || !existsSync(planPath)) return false;
+  try {
+    const plan = parsePlan(readFileSync(planPath, "utf-8"));
+    return plan.tasks.some((t) => !isPlaceholderTaskTitle(t.title));
+  } catch {
+    // A PLAN we cannot parse is not a trustworthy "planning done" signal.
+    return false;
+  }
+}
+
 export function repairStaleSketchFlag(record: SketchFlagDrift): void {
   setSliceSketchFlag(record.mid, record.sid, false);
 }

package/src/resources/extensions/gsd/tests/browser-daemon-auto-prep.test.ts

@@ -4,6 +4,8 @@ import assert from "node:assert/strict";
 import {
   prepareBrowserDaemonForUat,
   shouldWarmBrowserDaemonForUat,
+  stopBrowserDaemon,
+  teardownWarmedBrowserDaemons,
 } from "../browser-daemon-auto-prep.ts";
 import { commitBrowserEngineResolution } from "../../browser-tools/engine/selection.ts";
 import { resolveGsdBrowserCliAvailability } from "../../shared/gsd-browser-cli.ts";
@@ -142,3 +144,27 @@ test("prepareBrowserDaemonForUat returns actionable error when daemon start fail
 
   assert.match(error ?? "", /gsd-browser daemon failed to start/i);
 });
+
+test("stopBrowserDaemon reports failure when the gsd-browser CLI is missing", () => {
+  const result = stopBrowserDaemon("/tmp/example-project", {
+    env: { GSD_BROWSER_MCP_COMMAND: "/definitely/missing/gsd-browser" },
+  });
+
+  assert.equal(result.ok, false);
+});
+
+test("teardownWarmedBrowserDaemons is a no-op when nothing was warmed", () => {
+  // A failed warm-up must not register a project root for teardown.
+  prepareBrowserDaemonForUat({
+    uatType: "browser-executable",
+    sessionProvider: "claude-code",
+    sessionAuthMode: "externalCli",
+    projectRoot: "/tmp/example-project",
+    env: {
+      ...GSD_BROWSER_ENGINE,
+      GSD_BROWSER_MCP_COMMAND: "/definitely/missing/gsd-browser",
+    },
+  });
+
+  assert.deepEqual(teardownWarmedBrowserDaemons(), []);
+});

package/src/resources/extensions/gsd/tests/db-authority-regression.test.ts

@@ -17,7 +17,7 @@ import {
   openDatabase,
 } from "../gsd-db.ts";
 import { migrateHierarchyToDb } from "../md-importer.ts";
-import { checkMarkdownHierarchyAgainstDb } from "../migration-auto-check.ts";
+import { checkMarkdownHierarchyAgainstDb, countMarkdownHierarchy } from "../migration-auto-check.ts";
 import { queryDecisions } from "../context-store.ts";
 import { deriveStateFromDb, invalidateStateCache } from "../state.ts";
 import type { Requirement } from "../types.ts";
@@ -206,3 +206,78 @@ test("explicit markdown import remains opt-in and is not run by startup mismatch
   assert.equal(getAllMilestones().length, 1);
   assert.equal(getSliceTasks("M001", "S01").length, 1);
 });
+
+// #1286: migrateHierarchyToDb skips a `[sketch]` slice's stub PLAN tasks, so
+// scanMarkdownHierarchy must skip counting them too. Otherwise the markdown
+// scan claims task rows the DB authoritatively omits, and the startup drift
+// check perpetually reports recovery-required / recommends
+// `/gsd recover --confirm` — which re-skips the stub tasks and never converges.
+test("sketch slice stub tasks are not treated as markdown/DB drift", async (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const sketchSliceDir = join(milestoneDir, "slices", "S01");
+  const realSliceDir = join(milestoneDir, "slices", "S02");
+  mkdirSync(sketchSliceDir, { recursive: true });
+  mkdirSync(realSliceDir, { recursive: true });
+
+  // S01 is a sketch (badge before risk, per ADR-011 render); S02 is refined.
+  writeFileSync(
+    join(milestoneDir, "M001-ROADMAP.md"),
+    [
+      "# M001: Sketch Drift",
+      "",
+      "**Vision:** Sketch stub tasks must not count as drift",
+      "",
+      "## Slices",
+      "- [ ] **S01: Sketch Slice** `[sketch]` `risk:low` `depends:[]`",
+      "  > After this: Sketch decomposed.",
+      "",
+      "- [ ] **S02: Real Slice** `risk:low` `depends:[]`",
+      "  > After this: Real work done.",
+      "",
+    ].join("\n"),
+  );
+  // The sketch slice still carries a stub PLAN with a placeholder <tasks> block.
+  writeFileSync(
+    join(sketchSliceDir, "S01-PLAN.md"),
+    [
+      "# S01: Sketch Slice",
+      "",
+      "**Goal:** Placeholder.",
+      "",
+      "## Tasks",
+      "- [ ] **T01: Plan 01**",
+      "  Stub placeholder task.",
+      "",
+    ].join("\n"),
+  );
+  writeFileSync(
+    join(realSliceDir, "S02-PLAN.md"),
+    [
+      "# S02: Real Slice",
+      "",
+      "**Goal:** Real work.",
+      "",
+      "## Tasks",
+      "- [ ] **T01: Task** `est:5m`",
+      "",
+    ].join("\n"),
+  );
+
+  openProjectDb(base);
+  // The importer seeds S02's task but skips S01's stub (1 task total).
+  const imported = migrateHierarchyToDb(base);
+  assert.deepEqual(imported, { milestones: 1, slices: 2, tasks: 1 });
+  assert.equal(getSliceTasks("M001", "S01").length, 0, "sketch slice seeds no tasks");
+  assert.equal(getSliceTasks("M001", "S02").length, 1, "real slice seeds its task");
+
+  // The markdown scan must mirror the importer: the sketch stub task is not
+  // counted, so markdown (1 task) matches the DB (1 task) and the check is
+  // in-sync rather than recommending a recover that would never converge.
+  assert.deepEqual(countMarkdownHierarchy(base), { milestones: 1, slices: 2, tasks: 1 });
+  const check = await checkMarkdownHierarchyAgainstDb(base);
+  assert.equal(check.action, "none", "sketch stub tasks must not be flagged as drift");
+  assert.equal(check.reason, "in-sync");
+});

package/src/resources/extensions/gsd/tests/doctor-history-public-api.test.ts

@@ -0,0 +1,25 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { readDoctorHistory, runGSDDoctor, type DoctorHistoryEntry } from "../doctor.ts";
+
+test("doctor.ts preserves readDoctorHistory public API and records doctor runs", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-history-api-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const report = await runGSDDoctor(base, { fix: false });
+  const history: DoctorHistoryEntry[] = await readDoctorHistory(base, 1);
+
+  assert.equal(history.length, 1);
+  assert.equal(history[0].ok, report.ok);
+  assert.equal(history[0].errors, report.issues.filter(issue => issue.severity === "error").length);
+  assert.equal(history[0].warnings, report.issues.filter(issue => issue.severity === "warning").length);
+  assert.equal(history[0].fixes, 0);
+  assert.ok(Array.isArray(history[0].codes));
+  assert.equal(typeof history[0].summary, "string");
+});

package/src/resources/extensions/gsd/tests/migrate-hierarchy.test.ts

@@ -427,3 +427,56 @@ test('migrate-hier: demo text extracted', () => {
     }
 });
 
+  // ─── Test (i): Sketch slice stub tasks are not seeded (#1286) ─────────
+
+test('migrate-hier: sketch slice stub PLAN tasks are not imported', () => {
+    const base = createFixtureBase();
+    try {
+      // S01 is a sketch (badge before risk, per ADR-011 render); its PLAN is a
+      // stub with a placeholder <tasks> block. S02 is a real, refined slice.
+      const roadmap = `# M001: Test Milestone
+
+**Vision:** Sketch slices must not seed DB tasks.
+
+## Slices
+
+- [ ] **S01: Sketch Slice** \`[sketch]\` \`risk:low\` \`depends:[]\`
+  > After this: Sketch decomposed.
+
+- [ ] **S02: Real Slice** \`risk:low\` \`depends:[]\`
+  > After this: Real work done.
+`;
+      const sketchPlan = `# S01: Sketch Slice
+
+**Goal:** Placeholder.
+
+## Tasks
+
+- [ ] **T01: Plan 01**
+  Stub placeholder task.
+`;
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', roadmap);
+      writeFile(base, 'milestones/M001/slices/S01/S01-PLAN.md', sketchPlan);
+      writeFile(base, 'milestones/M001/slices/S02/S02-PLAN.md', PLAN_S02_1_TASK);
+
+      openDatabase(':memory:');
+      const counts = migrateHierarchyToDb(base);
+
+      const slices = getMilestoneSlices('M001');
+      assert.deepStrictEqual(slices.length, 2, 'sketch: 2 slices inserted');
+      assert.deepStrictEqual(slices[0]!.is_sketch, 1, 'sketch: S01 preserves is_sketch flag');
+
+      const s01Tasks = getSliceTasks('M001', 'S01');
+      assert.deepStrictEqual(s01Tasks.length, 0, 'sketch: no stub tasks seeded for sketch slice S01');
+
+      const s02Tasks = getSliceTasks('M001', 'S02');
+      assert.deepStrictEqual(s02Tasks.length, 1, 'sketch: real slice S02 still imports its task');
+      assert.deepStrictEqual(counts.tasks, 1, 'sketch: only the non-sketch slice contributes tasks');
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+});
+