@opengsd/gsd-pi 1.1.1-dev.a5a2de8 → 1.1.1-dev.b2556262

package/src/resources/extensions/gsd/guided-flow.ts

@@ -1158,7 +1158,10 @@ async function dispatchWorkflow(
             ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
             : undefined,
         baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+        // Guided flow starts the MCP workflow server as part of dispatch, so the
+        // parent session's activeTools doesn't include MCP tools yet. The MCP
+        // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+        // here — not whether MCP tools are pre-registered in the parent session.
       },
     );
     if (compatibilityError) {

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -12,7 +12,7 @@
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { createRequire } from "node:module";
 import {
   getAllMilestones,
@@ -21,7 +21,6 @@ import {
   getSliceTasks,
   getTask,
   getSlice,
-  getArtifact,
   insertArtifact,
   getGateResults,
 } from "./gsd-db.js";
@@ -109,22 +108,6 @@ function sanitizeInlineRoadmapText(value: string | null | undefined): string {
     .trim();
 }
 
-/**
- * Load artifact content from the DB. Markdown projections are not authoritative
- * during runtime; when the artifact row is missing, callers regenerate from DB
- * rows instead of patching disk fallback content and storing it back.
- */
-function loadArtifactContent(
-  artifactPath: string,
-): string | null {
-  const artifact = getArtifact(artifactPath);
-  if (artifact && artifact.full_content) {
-    return artifact.full_content;
-  }
-
-  return null;
-}
-
 function resolveRoadmapProjectionPath(basePath: string, milestoneId: string): string {
   const projectionMilestonesDir = join(gsdProjectionRoot(basePath), "milestones");
   const milestoneDirName = resolveDir(projectionMilestonesDir, milestoneId) ?? milestoneId;
@@ -397,6 +380,7 @@ export async function renderPlanFromDb(
   basePath: string,
   milestoneId: string,
   sliceId: string,
+  outputPath?: string,
 ): Promise<{ planPath: string; taskPlanPaths: string[]; content: string }> {
   const slice = getSlice(milestoneId, sliceId);
   if (!slice) {
@@ -408,9 +392,16 @@ export async function renderPlanFromDb(
     throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
   }
 
-  const slicePath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  mkdirSync(slicePath, { recursive: true });
-  const absPath = join(slicePath, `${sliceId}-PLAN.md`);
+  const defaultPlanPath = join(
+    gsdProjectionRoot(basePath),
+    "milestones",
+    milestoneId,
+    "slices",
+    sliceId,
+    `${sliceId}-PLAN.md`,
+  );
+  const absPath = outputPath ?? defaultPlanPath;
+  mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
   const sliceGates = getGateResults(milestoneId, sliceId, "slice");
   const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
@@ -510,8 +501,14 @@ export async function renderRoadmapCheckboxes(
 /**
  * Render plan checkbox states from DB.
  *
- * For each task in the slice, sets [x] if status === 'done',
- * [ ] otherwise. Bidirectional.
+ * Compatibility wrapper for legacy callers that used to patch plan checkboxes
+ * in-place. Plans are now fully regenerated from DB rows (mirroring
+ * renderRoadmapCheckboxes) so the projection always reflects the complete
+ * current task set and statuses. The previous regex-patch approach reused the
+ * cached PLAN artifact as the render input, which silently dropped tasks added
+ * to the DB after the artifact was first written — producing a lossy
+ * projection (the 4S/0T-vs-5S/13T drift class). The artifacts table is an
+ * output sink, never a render input.
  *
  * @returns true if the plan was written, false on skip/error
  */
@@ -519,6 +516,7 @@ export async function renderPlanCheckboxes(
   basePath: string,
   milestoneId: string,
   sliceId: string,
+  outputPath?: string,
 ): Promise<boolean> {
   const tasks = getSliceTasks(milestoneId, sliceId);
   if (tasks.length === 0) {
@@ -528,48 +526,7 @@ export async function renderPlanCheckboxes(
     return false;
   }
 
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
-  const artifactPath = absPath ? toArtifactPath(absPath, basePath) : null;
-
-  let content: string | null = null;
-  if (artifactPath) {
-    content = loadArtifactContent(artifactPath);
-  }
-
-  if (!content) {
-    await renderPlanFromDb(basePath, milestoneId, sliceId);
-    return true;
-  }
-
-  // Apply checkbox patches for each task
-  let updated = content;
-  for (const task of tasks) {
-    const isDone = isClosedStatus(task.status);
-    const tid = task.id;
-
-    if (isDone) {
-      // Set [x]
-      updated = updated.replace(
-        new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
-        `$1[x] **${tid}:`,
-      );
-    } else {
-      // Set [ ]
-      updated = updated.replace(
-        new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${tid}:`, "mi"),
-        `$1[ ] **${tid}:`,
-      );
-    }
-  }
-
-  if (!absPath) return false;
-
-  await writeAndStore(absPath, artifactPath!, updated, {
-    artifact_type: "PLAN",
-    milestone_id: milestoneId,
-    slice_id: sliceId,
-  });
-
+  await renderPlanFromDb(basePath, milestoneId, sliceId, outputPath);
   return true;
 }
 
@@ -747,6 +704,18 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
     }
   }
 
+  // Re-project root DECISIONS.md from the authoritative decision records so a
+  // full DB → markdown re-projection (recover, rebuild) also heals decisions
+  // drift — e.g. a worktree merge that accepted one branch's DECISIONS.md while
+  // the DB holds the union of both branches' decisions.
+  try {
+    const { regenerateDecisionsMarkdown } = await import("./db-writer.js");
+    await regenerateDecisionsMarkdown(basePath);
+    result.rendered++;
+  } catch (err) {
+    result.errors.push(`decisions: ${(err as Error).message}`);
+  }
+
   return result;
 }
 
@@ -832,7 +801,16 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
           for (const task of tasks) {
             const isDoneInDb = isClosedStatus(task.status);
             const planTask = parsed.tasks.find((t: { id: string }) => t.id === task.id);
-            if (!planTask) continue;
+            if (!planTask) {
+              // DB has a task the plan markdown lacks: the projection is
+              // lossy (e.g. tasks added after the PLAN artifact was first
+              // written). Flag it so the plan is re-rendered from DB rows.
+              stale.push({
+                path: planPath,
+                reason: `${task.id} exists in DB but is missing in plan`,
+              });
+              continue;
+            }
 
             if (isDoneInDb && !planTask.done) {
               stale.push({

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

@@ -4,7 +4,7 @@
 //
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import type { Decision, Requirement } from './types.js';
 import {
@@ -16,6 +16,7 @@ import {
   insertTask,
   openDatabase,
   transaction,
+  updateMilestoneStatus,
   updateSliceStatus,
   _getAdapter,
 } from './gsd-db.js';
@@ -38,6 +39,27 @@ import { logWarning } from './workflow-logger.js';
 
 const VALID_MADE_BY = new Set(['human', 'agent', 'collaborative']);
 
+const IMPORT_COMPLETE_STATUSES = new Set(['complete', 'done']);
+
+/**
+ * Completion timestamp for an entity imported as complete: the SUMMARY.md mtime
+ * when one exists (deterministic, matches the completion drift handler), else
+ * the import time. Crucially this never returns null, so a complete entity is
+ * never left with completed_at=null — which would otherwise be permanent,
+ * undetectable drift when no SUMMARY file is present.
+ */
+function importCompletionTimestamp(summaryPath: string | null): string {
+  if (summaryPath && existsSync(summaryPath)) {
+    try {
+      return statSync(summaryPath).mtime.toISOString();
+    } catch (err) {
+      // Fall through to import time.
+      logWarning('projection', `summary mtime read failed for ${summaryPath}: ${(err as Error).message}`);
+    }
+  }
+  return new Date().toISOString();
+}
+
 /**
  * Parse a DECISIONS.md markdown table into Decision objects (without seq).
  * Detects `(amends DXXX)` in the Decision column to build supersession info.
@@ -587,6 +609,14 @@ export function migrateHierarchyToDb(basePath: string): {
         boundaryMapMarkdown: boundaryMapSection,
       },
     });
+    // insertMilestone never sets completed_at; backfill it now for milestones
+    // imported as complete so the DB is internally coherent immediately after
+    // import (rather than relying on a later reconciliation pass that can't even
+    // see the drift when no SUMMARY file exists).
+    if (IMPORT_COMPLETE_STATUSES.has(milestoneStatus)) {
+      const summaryPath = resolveMilestoneFile(basePath, milestoneId, 'SUMMARY');
+      updateMilestoneStatus(milestoneId, milestoneStatus, importCompletionTimestamp(summaryPath));
+    }
     counts.milestones++;
 
     // Parse roadmap for slices
@@ -614,10 +644,22 @@ export function migrateHierarchyToDb(basePath: string): {
         depends: sliceEntry.depends,
         demo: sliceEntry.demo,
         sequence: si + 1, // Preserve roadmap parse order (#3356)
+        isSketch: sliceEntry.isSketch ?? false, // ADR-011: preserve the `[sketch]` flag on re-import
         planning: {
           goal: plan?.goal ?? '',
         },
       });
+      // insertSlice never sets completed_at; backfill it for slices imported as
+      // complete (same rationale as milestones above).
+      if (IMPORT_COMPLETE_STATUSES.has(sliceStatus)) {
+        const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceEntry.id, 'SUMMARY');
+        updateSliceStatus(
+          milestoneId,
+          sliceEntry.id,
+          sliceStatus,
+          importCompletionTimestamp(sliceSummary),
+        );
+      }
       counts.slices++;
 
       // Insert tasks from parsed plan
@@ -674,7 +716,12 @@ export function migrateHierarchyToDb(basePath: string): {
         });
         if (allTasksDone && hasSliceSummary) {
           if (_getAdapter()) {
-            updateSliceStatus(milestoneId, sliceEntry.id, 'complete');
+            updateSliceStatus(
+              milestoneId,
+              sliceEntry.id,
+              'complete',
+              importCompletionTimestamp(sliceSummaryPath),
+            );
             process.stderr.write(
               `gsd-migrate: ${milestoneId}/${sliceEntry.id} all tasks + slice summary complete — upgrading slice to complete\n`,
             );

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

@@ -23,7 +23,7 @@ export interface HierarchyCounts {
 
 export interface MigrationAutoCheckResult {
   action: "none" | "recovery-required";
-  reason: "no-markdown" | "in-sync" | "db-empty" | "count-mismatch";
+  reason: "no-markdown" | "in-sync" | "db-empty" | "count-mismatch" | "markdown-missing";
   markdown: HierarchyCounts;
   beforeDb: HierarchyCounts;
   afterDb: HierarchyCounts;
@@ -31,71 +31,146 @@ export interface MigrationAutoCheckResult {
   message?: string;
 }
 
+interface HierarchyScan {
+  counts: HierarchyCounts;
+  // Fully-qualified identities: milestone "M001", slice "M001/S01",
+  // task "M001/S01/T01". Used to detect drift the cardinalities miss (a
+  // deleted+added pair nets to the same counts but is real divergence).
+  milestones: Set<string>;
+  slices: Set<string>;
+  tasks: Set<string>;
+}
+
 function zeroCounts(): HierarchyCounts {
   return { milestones: 0, slices: 0, tasks: 0 };
 }
 
+function emptyScan(): HierarchyScan {
+  return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+}
+
 function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
   return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
 }
 
-export function countMarkdownHierarchy(basePath: string): HierarchyCounts {
+function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const value of a) if (!b.has(value)) return false;
+  return true;
+}
+
+function scanIdentitiesMatch(a: HierarchyScan, b: HierarchyScan): boolean {
+  return (
+    setsEqual(a.milestones, b.milestones) &&
+    setsEqual(a.slices, b.slices) &&
+    setsEqual(a.tasks, b.tasks)
+  );
+}
+
+/** True if any element of `a` is absent from `b`. */
+function hasExtra(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  for (const value of a) if (!b.has(value)) return true;
+  return false;
+}
+
+function scanHasExtraIdentities(a: HierarchyScan, b: HierarchyScan): boolean {
+  return (
+    hasExtra(a.milestones, b.milestones) ||
+    hasExtra(a.slices, b.slices) ||
+    hasExtra(a.tasks, b.tasks)
+  );
+}
+
+/**
+ * True when the DB holds any milestone/slice/task identity the markdown lacks —
+ * i.e. a `/gsd recover --confirm` (markdown → DB) would DELETE authoritative DB
+ * rows. This is identity-based, so it catches equal-count divergence (e.g. DB
+ * slice `S99` vs markdown `S01`) that a cardinality-only check misses. Used by
+ * the recover data-loss guard.
+ */
+export function recoverWouldDeleteDbRows(basePath: string): boolean {
+  return scanHasExtraIdentities(scanDbHierarchy(), scanMarkdownHierarchy(basePath));
+}
+
+export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
   const root = milestonesDir(basePath);
-  if (!existsSync(root)) return zeroCounts();
+  if (!existsSync(root)) return emptyScan();
 
-  const counts = zeroCounts();
+  const scan = emptyScan();
   for (const entry of readdirSync(root, { withFileTypes: true })) {
     if (!entry.isDirectory() || !/^M\d+/.test(entry.name)) continue;
-    counts.milestones++;
-
-    const roadmapPath = resolveMilestoneFile(basePath, entry.name, "ROADMAP");
+    // Use the CANONICAL milestone id (e.g. "M001" or "M001-a1b2c3"), matching
+    // scanDbHierarchy's milestone.id — not the raw directory name, which may
+    // carry a legacy descriptor (e.g. "M001-some-descriptor"). The canonical id
+    // both keys the identity sets AND resolves files correctly: resolveFile's
+    // prefix/legacy-pattern matching handles the descriptor dir either way.
+    const milestoneId = entry.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/)?.[1] ?? entry.name;
+    scan.counts.milestones++;
+    scan.milestones.add(milestoneId);
+
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     if (!roadmapPath || !existsSync(roadmapPath)) continue;
 
     const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    counts.slices += roadmap.slices.length;
+    scan.counts.slices += roadmap.slices.length;
 
     for (const slice of roadmap.slices) {
-      const planPath = resolveSliceFile(basePath, entry.name, slice.id, "PLAN");
+      scan.slices.add(`${milestoneId}/${slice.id}`);
+      const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
       if (!planPath || !existsSync(planPath)) continue;
       const plan = parsePlan(readFileSync(planPath, "utf-8"));
-      counts.tasks += plan.tasks.length;
+      scan.counts.tasks += plan.tasks.length;
+      for (const task of plan.tasks) {
+        scan.tasks.add(`${milestoneId}/${slice.id}/${task.id}`);
+      }
     }
   }
 
-  return counts;
+  return scan;
 }
 
-export function countDbHierarchy(): HierarchyCounts {
-  if (!isDbAvailable()) return zeroCounts();
-  const counts = zeroCounts();
+export function scanDbHierarchy(): HierarchyScan {
+  if (!isDbAvailable()) return emptyScan();
+  const scan = emptyScan();
   const milestones = getAllMilestones();
-  counts.milestones = milestones.length;
+  scan.counts.milestones = milestones.length;
 
   for (const milestone of milestones) {
+    scan.milestones.add(milestone.id);
     const slices = getMilestoneSlices(milestone.id);
-    counts.slices += slices.length;
+    scan.counts.slices += slices.length;
     for (const slice of slices) {
-      counts.tasks += getSliceTasks(milestone.id, slice.id).length;
+      scan.slices.add(`${milestone.id}/${slice.id}`);
+      const tasks = getSliceTasks(milestone.id, slice.id);
+      scan.counts.tasks += tasks.length;
+      for (const task of tasks) {
+        scan.tasks.add(`${milestone.id}/${slice.id}/${task.id}`);
+      }
     }
   }
 
-  return counts;
+  return scan;
+}
+
+export function countMarkdownHierarchy(basePath: string): HierarchyCounts {
+  return scanMarkdownHierarchy(basePath).counts;
+}
+
+export function countDbHierarchy(): HierarchyCounts {
+  return scanDbHierarchy().counts;
 }
 
 export async function checkMarkdownHierarchyAgainstDb(
   basePath: string,
 ): Promise<MigrationAutoCheckResult> {
-  const markdown = countMarkdownHierarchy(basePath);
-  if (sameCounts(markdown, zeroCounts())) {
-    return {
-      action: "none",
-      reason: "no-markdown",
-      markdown,
-      beforeDb: zeroCounts(),
-      afterDb: zeroCounts(),
-    };
-  }
-
+  const markdownScan = scanMarkdownHierarchy(basePath);
+  const markdown = markdownScan.counts;
+
+  // Always open the DB before deciding. An empty markdown tree does NOT imply
+  // an empty project — the DB may hold authoritative rows whose markdown was
+  // lost, which is itself recoverable drift. The previous early return here
+  // skipped the DB entirely and silently hid a populated-DB/empty-markdown
+  // project.
   const opened = await ensureDbOpen(basePath);
   if (!opened || !isDbAvailable()) {
     throw new Error(`failed to open or create the GSD database at ${basePath}`);
@@ -106,12 +181,58 @@ export async function checkMarkdownHierarchyAgainstDb(
   // warn from a stale long-lived SQLite handle.
   refreshOpenDatabaseFromDisk();
 
-  const beforeDb = countDbHierarchy();
-  if (sameCounts(markdown, beforeDb)) {
+  const dbScan = scanDbHierarchy();
+  const beforeDb = dbScan.counts;
+
+  const markdownEmpty = sameCounts(markdown, zeroCounts());
+  const dbEmpty = sameCounts(beforeDb, zeroCounts());
+
+  // Genuinely empty project: nothing on disk, nothing in the DB.
+  if (markdownEmpty && dbEmpty) {
+    return { action: "none", reason: "no-markdown", markdown, beforeDb, afterDb: beforeDb };
+  }
+
+  // In sync only when both cardinalities AND identities agree. Identity
+  // comparison catches drift the counts miss (e.g. a slice deleted from the DB
+  // and a different one added nets to the same count but is real divergence,
+  // and a missing PLAN.md vs DB tasks shows up as a task-identity gap).
+  if (sameCounts(markdown, beforeDb) && scanIdentitiesMatch(markdownScan, dbScan)) {
     return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
   }
 
-  const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
+  // Choose the SAFE repair direction by IDENTITY, not cardinality. Recover
+  // imports markdown → DB and DELETES any DB row markdown lacks, so it must
+  // never be recommended when the DB holds identities the markdown is missing —
+  // including equal-count divergence (DB `S99` vs markdown `S01`), which a
+  // count-only check would wrongly route to recover. Whenever the DB holds rows
+  // markdown lacks, the correct repair is to re-project from the DB (rebuild).
+  const dbHasExtra = scanHasExtraIdentities(dbScan, markdownScan);
+
+  const countsLine =
+    `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
+    `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). `;
+
+  // The DB holds rows markdown lacks (richer, identity-diverged, or markdown
+  // entirely missing): re-project from the DB. Recover here would destroy data.
+  if (dbHasExtra) {
+    return {
+      action: "recovery-required",
+      reason: markdownEmpty ? "markdown-missing" : "count-mismatch",
+      markdown,
+      beforeDb,
+      afterDb: beforeDb,
+      recoveryCommand: "/gsd rebuild markdown",
+      message:
+        countsLine +
+        "The DB holds rows the markdown lacks, so the markdown projection is stale. " +
+        "Run `/gsd rebuild markdown` to re-project from the authoritative DB. " +
+        "Do NOT run `/gsd recover --confirm` here — it would delete the extra DB rows.",
+    };
+  }
+
+  // DB is empty (or markdown is strictly richer): markdown is the surviving
+  // source to import.
+  const reason = dbEmpty ? "db-empty" : "count-mismatch";
   return {
     action: "recovery-required",
     reason,
@@ -120,8 +241,7 @@ export async function checkMarkdownHierarchyAgainstDb(
     afterDb: beforeDb,
     recoveryCommand: "/gsd recover --confirm",
     message:
-      `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
-      `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). ` +
+      countsLine +
       "Runtime startup will not import markdown automatically; run `/gsd recover --confirm` if markdown should repopulate the database.",
   };
 }

package/src/resources/extensions/gsd/parsers-legacy.ts

@@ -60,11 +60,31 @@ export function parseRoadmap(content: string): Roadmap {
   return cachedParse(content, 'roadmap', _parseRoadmapImpl);
 }
 
+/**
+ * ADR-011: the roadmap renderer writes a `[sketch]` badge for sketch slices,
+ * but the native parser does not surface it. Re-scan the markdown and set
+ * isSketch on the matching slice so the flag survives a markdown → DB re-import
+ * (e.g. /gsd recover) instead of being silently dropped.
+ */
+function applySketchFlags(roadmap: Roadmap, content: string): void {
+  const sketchIds = new Set<string>();
+  for (const line of content.split("\n")) {
+    if (!/\[sketch\]/i.test(line)) continue;
+    const m = line.match(/\*\*([\w.]+):/);
+    if (m) sketchIds.add(m[1]!);
+  }
+  if (sketchIds.size === 0) return;
+  for (const slice of roadmap.slices) {
+    if (sketchIds.has(slice.id)) slice.isSketch = true;
+  }
+}
+
 function _parseRoadmapImpl(content: string): Roadmap {
   const stopTimer = debugTime("parse-roadmap");
   // Try native parser first for better performance
   const nativeResult = nativeParseRoadmap(content);
   if (nativeResult) {
+    applySketchFlags(nativeResult, content);
     stopTimer({ native: true, slices: nativeResult.slices.length, boundaryEntries: nativeResult.boundaryMap.length });
     debugCount("parseRoadmapCalls");
     return nativeResult;