@opengsd/gsd-pi 1.7.0 → 1.8.1

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

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

@@ -420,6 +420,59 @@ test("migration auto-check still reports real drift with scratch dirs excluded f
   }
 });
 
+test("migration auto-check excludes sketch slice stub tasks from the markdown scan (#1286)", () => {
+  const base = makeBase();
+  try {
+    // S01 is a sketch (`[sketch]` badge): its PLAN is a stub carrying a
+    // placeholder <tasks> block until refinement. migrateHierarchyToDb skips
+    // seeding those stub tasks, so the markdown scan must skip them too — else
+    // the stub inflates the markdown count and reports false drift against a DB
+    // that (correctly) holds zero tasks for the sketch slice.
+    const roadmap = `# M001: Test Milestone
+
+**Vision:** Sketch slices must not inflate markdown task counts.
+
+## 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.
+`;
+    const realPlan = `# S02: Real Slice
+
+**Goal:** Real work.
+
+## Tasks
+
+- [ ] **T01: Real Task**
+  Real work.
+`;
+    const milestoneDir = join(base, ".gsd", "milestones", "M001");
+    mkdirSync(join(milestoneDir, "slices", "S01"), { recursive: true });
+    mkdirSync(join(milestoneDir, "slices", "S02"), { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-ROADMAP.md"), roadmap);
+    writeFileSync(join(milestoneDir, "slices", "S01", "S01-PLAN.md"), sketchPlan);
+    writeFileSync(join(milestoneDir, "slices", "S02", "S02-PLAN.md"), realPlan);
+
+    // Both slices count, but only the refined slice contributes a task; the
+    // sketch stub task is excluded, matching migrateHierarchyToDb.
+    assert.deepEqual(countMarkdownHierarchy(base), { milestones: 1, slices: 2, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("migration auto-check still compares a roadmapless milestone that HAS a DB row", async () => {
   const base = makeBase();
   try {

package/src/resources/extensions/gsd/tests/parsers-legacy-importers.test.ts

@@ -47,6 +47,9 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/migration-auto-check.ts",
   // drift detection: compares markdown projection against DB by design
   "gsd/state-reconciliation/drift/roadmap.ts",
+  // drift detection: reads PLAN.md tasks to distinguish a real plan from a
+  // stub before clearing a stale is_sketch flag (#1287)
+  "gsd/state-reconciliation/drift/sketch-flag.ts",
   // stale-render detection + render verification helpers over rendered output
   "gsd/markdown-renderer.ts",
   // pre-migration fallback: deriveState must work before the DB exists
@@ -58,6 +61,7 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  "gsd/doctor-state-checks.ts",
   // diagnostics-only: compares PLAN.md task checkboxes against DB status
   "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces

package/src/resources/extensions/gsd/tests/planning-writer.test.ts

@@ -8,7 +8,7 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { writePlanningDirectory } from "../migrate/planning-writer.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, updateTaskStatus } from "../gsd-db.ts";
 
 const tmpDirs: string[] = [];
 function makeTmp(): string {
@@ -65,6 +65,23 @@ test("writePlanningDirectory emits phase plan file with XML structure", async ()
   assert.match(plan, /<tasks>/);
 });
 
+test("writePlanningDirectory renders completed task checkboxes as [x] (#1276)", async () => {
+  const base = makeTmp();
+  updateTaskStatus("M001", "S01", "T01", "complete");
+  await writePlanningDirectory(base, "flat-phases");
+
+  const phaseDir = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)[0]!;
+  const planFile = readdirSync(join(base, ".planning", "phases", phaseDir))
+    .filter((f) => f.endsWith("PLAN.md"))[0]!;
+  const plan = readFileSync(join(base, ".planning", "phases", phaseDir, planFile), "utf-8");
+  assert.match(plan, /- \[x\] \*\*T01\*\*/, "completed task should project as [x], not [ ]");
+
+  const roadmap = readFileSync(join(base, ".planning", "ROADMAP.md"), "utf-8");
+  assert.match(roadmap, /- \[x\] 01 —/, "phase with all tasks complete should be [x] in ROADMAP");
+});
+
 test("writePlanningDirectory is idempotent: writing twice produces stable content", async () => {
   const base = makeTmp();
   await writePlanningDirectory(base, "flat-phases");

package/src/resources/extensions/gsd/tests/progressive-planning.test.ts

@@ -76,6 +76,21 @@ function writeS01Artifacts(base: string): void {
   writeFileSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), "# S01 Summary\n");
 }
 
+// A *real* decomposed PLAN (>= 1 genuine task). #1287: the stale-sketch-flag
+// detector requires a real plan — not a bare stub — before clearing is_sketch.
+function realPlanContent(sliceId: string): string {
+  return [
+    `# ${sliceId}: Feature`,
+    "",
+    "**Goal:** Ship the feature",
+    "",
+    "## Tasks",
+    "",
+    "- [ ] **T01: Build the feature** `est:1h`",
+    "",
+  ].join("\n");
+}
+
 function cleanup(base: string, originalCwd: string): void {
   try { closeDatabase(); } catch { /* noop */ }
   process.chdir(originalCwd);
@@ -185,7 +200,7 @@ test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispat
   writePreferences(base, "phases:\n  progressive_planning: true");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -252,7 +267,7 @@ test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN ex
   // Simulate plan-slice completion where PLAN exists but is_sketch was not flipped.
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -282,7 +297,7 @@ test("ADR-011: deriveState stays pure across worktree/canonical-root; healing be
   writePreferences(base, "phases:\n  skip_research: false");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   const worktreePath = join(base, "worker");
   mkdirSync(worktreePath, { recursive: true });