gsd-pi 2.82.0 → 3.0.0-dev.04f5ccf82

package/src/resources/extensions/gsd/memory-consolidation-scanner.ts

@@ -0,0 +1,277 @@
+// GSD-2 — ADR-013 Phase 6 preflight scanner.
+//
+// Read-only detection of rows in the legacy knowledge surfaces (decisions
+// table, `.gsd/KNOWLEDGE.md`) that lack a corresponding `memories` row.
+// Runs on session start (and on demand via doctor); never mutates state.
+//
+// The scanner exists so the destructive Phase 6 cutover (#5755) can prove
+// the migration is complete before any tables are dropped. Today's
+// `backfillDecisionsToMemories` writes a `structured_fields.sourceDecisionId`
+// marker on each migrated row; the scanner uses that marker for decisions
+// detection. A `sourceKnowledgeId` marker is reserved for the parallel
+// KNOWLEDGE.md backfill that Phase 6 will introduce — until that ships,
+// every KNOWLEDGE.md row is reported as unmigrated, which is the honest
+// state of the consolidation.
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { appendNotification } from "./notification-store.js";
+import { resolveGsdRootFile } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface KnowledgeSurfaceReport {
+  total: number;
+  migrated: number;
+  unmigrated: number;
+  byTable: { rules: number; patterns: number; lessons: number };
+  /** Up to 5 sample row IDs/content for diagnosing what's unmigrated. */
+  samples: Array<{ table: "rules" | "patterns" | "lessons"; id: string; row: string }>;
+}
+
+export interface DecisionsSurfaceReport {
+  total: number;
+  migrated: number;
+  unmigrated: number;
+  /** Up to 5 sample decision IDs with a short content excerpt. */
+  samples: Array<{ id: string; decision: string }>;
+}
+
+export interface ConsolidationGapReport {
+  decisions: DecisionsSurfaceReport;
+  knowledge: KnowledgeSurfaceReport;
+  /** Sum of unmigrated rows across both surfaces. Zero ⇒ clean preflight. */
+  totalGaps: number;
+  /** Human-readable single-line summary suitable for notifications + logs. */
+  summary: string;
+}
+
+// ─── KNOWLEDGE.md parsing ────────────────────────────────────────────────────
+
+const KNOWLEDGE_SECTIONS = [
+  { table: "rules" as const, heading: "## Rules", idPrefix: "K" },
+  { table: "patterns" as const, heading: "## Patterns", idPrefix: "P" },
+  { table: "lessons" as const, heading: "## Lessons Learned", idPrefix: "L" },
+];
+
+interface KnowledgeRow {
+  table: "rules" | "patterns" | "lessons";
+  id: string;
+  row: string;
+}
+
+/**
+ * Parse `.gsd/KNOWLEDGE.md` into rows, one per table entry. Skips the table
+ * header and separator lines; ignores rows from unrecognized sections.
+ *
+ * The format is locked in `files.ts:appendKnowledge` — three `## ` sections
+ * (Rules, Patterns, Lessons Learned), each a Markdown table. Row IDs are
+ * `K###` / `P###` / `L###`.
+ */
+export function parseKnowledgeRows(content: string): KnowledgeRow[] {
+  const rows: KnowledgeRow[] = [];
+  if (!content.trim()) return rows;
+
+  // Slice the content into sections by heading. The leading text before the
+  // first ## heading is intro prose — ignored.
+  const lines = content.split("\n");
+  let activeSection: typeof KNOWLEDGE_SECTIONS[number] | undefined;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("## ")) {
+      activeSection = KNOWLEDGE_SECTIONS.find((s) => s.heading === trimmed);
+      continue;
+    }
+    if (!activeSection) continue;
+    if (!trimmed.startsWith("|")) continue;
+
+    // Skip the table header rows: the column-titles line and the |---|---| separator.
+    // Real data rows start with `| <prefix>### |`.
+    const idMatch = new RegExp(`^\\|\\s*(${activeSection.idPrefix}\\d+)\\s*\\|`).exec(trimmed);
+    if (!idMatch) continue;
+
+    rows.push({
+      table: activeSection.table,
+      id: idMatch[1] ?? "",
+      row: trimmed,
+    });
+  }
+
+  return rows;
+}
+
+function knowledgeMdContent(basePath: string): string {
+  const path = resolveGsdRootFile(basePath, "KNOWLEDGE");
+  if (!existsSync(path)) return "";
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+// ─── DB queries ──────────────────────────────────────────────────────────────
+
+interface DecisionRow {
+  id: string;
+  decision: string;
+}
+
+function getActiveDecisions(): DecisionRow[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT id, decision FROM decisions WHERE superseded_by IS NULL",
+      )
+      .all() as Array<Record<string, unknown>>;
+    return rows
+      .map((row): DecisionRow => ({
+        id: String(row["id"] ?? ""),
+        decision: String(row["decision"] ?? ""),
+      }))
+      .filter((row) => row.id.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * True when a memory row has a `structured_fields` JSON payload containing
+ * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
+ * `backfillDecisionsToMemories` so the scanner is consistent with the
+ * backfill's idempotency check.
+ */
+function memoryHasSourceMarker(markerKey: string, value: string): boolean {
+  if (!isDbAvailable()) return false;
+  const adapter = _getAdapter();
+  if (!adapter) return false;
+  try {
+    const pattern = `%"${markerKey}":"${value}"%`;
+    const row = adapter
+      .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
+      .get({ ":pattern": pattern });
+    return row !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+const SAMPLE_LIMIT = 5;
+
+/**
+ * Scan the legacy knowledge surfaces and return a structured report of what's
+ * already in the `memories` table vs what's still unmigrated. Pure detection
+ * — no DB writes, no file writes, no notifications.
+ */
+export function scanConsolidationGaps(basePath: string): ConsolidationGapReport {
+  // ── Decisions ────────────────────────────────────────────────────────
+  const decisions = getActiveDecisions();
+  const decisionSamples: DecisionsSurfaceReport["samples"] = [];
+  let decisionMigrated = 0;
+  for (const decision of decisions) {
+    if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+      decisionMigrated += 1;
+      continue;
+    }
+    if (decisionSamples.length < SAMPLE_LIMIT) {
+      decisionSamples.push({
+        id: decision.id,
+        decision: decision.decision.length > 80 ? decision.decision.slice(0, 79) + "…" : decision.decision,
+      });
+    }
+  }
+
+  // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
+  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+  const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
+  const knowledgeSamples: KnowledgeSurfaceReport["samples"] = [];
+  let knowledgeMigrated = 0;
+  for (const row of knowledgeRows) {
+    knowledgeByTable[row.table] += 1;
+    // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
+    // KNOWLEDGE.md backfill. Until that path ships, this check returns
+    // false for every row, which is the honest state of the consolidation.
+    if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+      knowledgeMigrated += 1;
+      continue;
+    }
+    if (knowledgeSamples.length < SAMPLE_LIMIT) {
+      knowledgeSamples.push({
+        table: row.table,
+        id: row.id,
+        row: row.row.length > 100 ? row.row.slice(0, 99) + "…" : row.row,
+      });
+    }
+  }
+
+  const decisionsReport: DecisionsSurfaceReport = {
+    total: decisions.length,
+    migrated: decisionMigrated,
+    unmigrated: decisions.length - decisionMigrated,
+    samples: decisionSamples,
+  };
+  const knowledgeReport: KnowledgeSurfaceReport = {
+    total: knowledgeRows.length,
+    migrated: knowledgeMigrated,
+    unmigrated: knowledgeRows.length - knowledgeMigrated,
+    byTable: knowledgeByTable,
+    samples: knowledgeSamples,
+  };
+
+  const totalGaps = decisionsReport.unmigrated + knowledgeReport.unmigrated;
+
+  // Summary line is intentionally short so it fits in a single notification
+  // (notification-store truncates messages over 500 chars). Detail is
+  // accessible via getProviderSwitchStats-style callers, not embedded here.
+  const parts: string[] = [];
+  if (decisionsReport.unmigrated > 0) {
+    parts.push(`${decisionsReport.unmigrated} of ${decisionsReport.total} active decisions`);
+  }
+  if (knowledgeReport.unmigrated > 0) {
+    parts.push(`${knowledgeReport.unmigrated} of ${knowledgeReport.total} KNOWLEDGE.md rows`);
+  }
+  const summary =
+    parts.length === 0
+      ? "Memory consolidation: all decisions and KNOWLEDGE.md rows are in memories."
+      : `Memory consolidation: ${parts.join(" and ")} not yet in memories table. Run /doctor for details.`;
+
+  return { decisions: decisionsReport, knowledge: knowledgeReport, totalGaps, summary };
+}
+
+/**
+ * Run the scanner and emit a persistent notification + workflow-logger
+ * warning when gaps exist. Best-effort: never throws; a broken scanner
+ * cannot block agent startup.
+ *
+ * Returns the full {@link ConsolidationGapReport} regardless of whether gaps
+ * exist (including when `totalGaps === 0`). Returns `null` only when
+ * `scanConsolidationGaps` itself throws. `appendNotification` and
+ * `logWarning` are called only when `report.totalGaps > 0`.
+ *
+ * Idempotent at the surface: the notification store applies its own
+ * 30-second dedup window keyed on (severity, source, message), so repeated
+ * boots with identical gaps produce one notification, not a flood.
+ */
+export function reportConsolidationGaps(basePath: string): ConsolidationGapReport | null {
+  try {
+    const report = scanConsolidationGaps(basePath);
+    if (report.totalGaps === 0) return report;
+    appendNotification(report.summary, "warning", "workflow-logger");
+    logWarning("memory-consolidation", report.summary);
+    return report;
+  } catch (e) {
+    logWarning(
+      "memory-consolidation",
+      `scanner failed: ${(e as Error).message}`,
+    );
+    return null;
+  }
+}

package/src/resources/extensions/gsd/migrate/command.ts

@@ -34,6 +34,9 @@ export type MigrationImportCounts = ReturnType<typeof migrateFromMarkdown>;
 
 function assertMigrationImportMatchesPreview(imported: MigrationImportCounts, preview: MigrationPreview): void {
   const mismatches: string[] = [];
+  if (imported.decisions !== preview.decisions.total) {
+    mismatches.push(`decisions ${imported.decisions}/${preview.decisions.total}`);
+  }
   if (imported.hierarchy.milestones !== preview.milestoneCount) {
     mismatches.push(`milestones ${imported.hierarchy.milestones}/${preview.milestoneCount}`);
   }
@@ -73,6 +76,7 @@ export async function importWrittenMigrationToDb(
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview: MigrationPreview): string {
   const lines = [
+    `- Decisions: ${preview.decisions.total}`,
     `- Milestones: ${preview.milestoneCount}`,
     `- Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
     `- Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
@@ -179,6 +183,7 @@ export async function handleMigrate(
 
   // ── Build preview text ─────────────────────────────────────────────────────
   const lines: string[] = [
+    `Decisions: ${preview.decisions.total}`,
     `Milestones: ${preview.milestoneCount}`,
     `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
     `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,

package/src/resources/extensions/gsd/migrate/parsers.ts

@@ -67,6 +67,7 @@ function parsePhaseEntry(line: string): PlanningRoadmapEntry | null {
     let title = fmtPhaseColon[3].trim();
     // Strip trailing parentheticals, plan counts, and completion notes
     title = title.replace(/\s*\(\d+\/\d+\s+plans?\)/, '')
+                 .replace(/\s*[—–]\s+.*$/, '') // strip em/en-dash description suffix
                  .replace(/\s*--\s+.*$/, '')
                  .replace(/\s*-\s+.*$/, '')  // strip "- description" suffix
                  .replace(/\s*\(completed.*\)$/i, '')
@@ -95,6 +96,17 @@ function parsePhaseEntry(line: string): PlanningRoadmapEntry | null {
     };
   }
 
+  // Format 3: - ✅ v1.0 MVP — Phases 1-6
+  const fmtVersionPhases = stripped.match(/^-\s+([✅🚧])\s+v\d+(?:\.\d+)*\s+(.+?)\s*[—–]\s*Phases?\s+(\d+(?:\.\d+)?)(?:\s*-\s*\d+(?:\.\d+)?)?(?:\s+\(.*\))?\s*$/iu);
+  if (fmtVersionPhases) {
+    return {
+      number: parseFloat(fmtVersionPhases[3]),
+      title: fmtVersionPhases[2].trim(),
+      done: fmtVersionPhases[1] === '✅',
+      raw: line,
+    };
+  }
+
   return null;
 }
 
@@ -147,7 +159,14 @@ export function parseOldRoadmap(content: string): PlanningRoadmap {
     return result;
   }
 
-  // ─── Strategy 2: Detect ## heading-sectioned milestones ───
+  // ─── Strategy 2: Detect ## Milestones summary + ### vN.N subsections ───
+  const summaryMilestones = parseMilestoneSummaryFormat(lines);
+  if (summaryMilestones.length > 0) {
+    result.milestones = summaryMilestones;
+    return result;
+  }
+
+  // ─── Strategy 3: Detect ## heading-sectioned milestones ───
   const milestoneHeadingRegex = /^##\s+(.+)$/;
   const milestoneHeadings: { index: number; id: string; title: string }[] = [];
 
@@ -196,7 +215,7 @@ export function parseOldRoadmap(content: string): PlanningRoadmap {
       result.milestones.push(milestone);
     }
   } else {
-    // ─── Strategy 3: Flat format — just extract all phase checkbox lines ───
+    // ─── Strategy 4: Flat format — just extract all phase checkbox lines ───
     for (const line of lines) {
       const entry = parsePhaseEntry(line.trim());
       if (entry) {
@@ -259,6 +278,124 @@ function parseDetailsBlockMilestones(lines: string[]): PlanningRoadmapMilestone[
   return milestones;
 }
 
+/**
+ * Parse a `## Milestones` summary section paired with `### vN.N ... (Phases N-M)` subsections.
+ * Returns empty array if not detected.
+ */
+function parseMilestoneSummaryFormat(lines: string[]): PlanningRoadmapMilestone[] {
+  let milestoneSectionStart = -1;
+  let milestoneSectionEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Milestones?\s*$/i.test(lines[i].trim())) {
+      milestoneSectionStart = i + 1;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^##\s+/.test(lines[j])) {
+          milestoneSectionEnd = j;
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  if (milestoneSectionStart === -1) return [];
+
+  type MilestoneSummaryEntry = {
+    id: string;
+    title: string;
+    done: boolean;
+    phaseStart: number;
+    phaseEnd: number;
+  };
+
+  const summaryEntries: MilestoneSummaryEntry[] = [];
+  for (let i = milestoneSectionStart; i < milestoneSectionEnd; i++) {
+    const line = lines[i].trim();
+    if (!line.startsWith('-')) continue;
+    const stripped = line.replace(/\*\*/g, '');
+    const match = stripped.match(
+      /^-\s+\[([ xX])\]\s+(?:Phase\s+)?\d+(?:\.\d+)?\s*:\s*(v[\d.]+)\s+(.+?)(?:\s*[—–]\s*Phases?\s+(\d+(?:\.\d+)?)\s*-\s*(\d+(?:\.\d+)?))?(?:\s*\(.*\))?\s*$/
+    );
+    if (!match) continue;
+
+    const id = match[2];
+    const titleSuffix = match[3]
+      .replace(/\s*[—–]\s*Phases?\s+\d+(?:\.\d+)?\s*-\s*\d+(?:\.\d+)?.*$/, '')
+      .replace(/\s*\(.*\)\s*$/, '')
+      .trim();
+
+    summaryEntries.push({
+      id,
+      title: `${id} ${titleSuffix}`.trim(),
+      done: match[1].toLowerCase() === 'x',
+      phaseStart: match[4] ? parseFloat(match[4]) : 0,
+      phaseEnd: match[5] ? parseFloat(match[5]) : 0,
+    });
+  }
+
+  if (summaryEntries.length === 0) return [];
+
+  const subsectionPhases = new Map<string, PlanningRoadmapEntry[]>();
+  for (let i = 0; i < lines.length; i++) {
+    const headingMatch = lines[i].trim().match(/^###\s+(v[\d.]+)\s+(.+?)(?:\s*\(Phases?\s+[\d.]+\s*-\s*[\d.]+\))?\s*$/i);
+    if (!headingMatch) continue;
+
+    const id = headingMatch[1];
+    const phases: PlanningRoadmapEntry[] = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const sectionLine = lines[j].trim();
+      if (/^##\s+/.test(sectionLine) || /^###\s+/.test(sectionLine)) break;
+      const entry = parsePhaseEntry(sectionLine);
+      if (entry) phases.push(entry);
+    }
+
+    if (phases.length > 0) subsectionPhases.set(id, phases);
+  }
+
+  const milestones: PlanningRoadmapMilestone[] = [];
+  for (const entry of summaryEntries) {
+    const phases = subsectionPhases.get(entry.id);
+    if (phases && phases.length > 0) {
+      milestones.push({
+        id: entry.id,
+        title: entry.title,
+        collapsed: false,
+        phases,
+      });
+      continue;
+    }
+
+    if (entry.done && entry.phaseStart > 0 && entry.phaseEnd >= entry.phaseStart) {
+      const synthetic: PlanningRoadmapEntry[] = [];
+      for (let n = entry.phaseStart; n <= entry.phaseEnd; n += 1) {
+        synthetic.push({
+          number: n,
+          title: `Phase ${n}`,
+          done: true,
+          raw: `synthetic:${entry.id}:${n}`,
+        });
+      }
+      milestones.push({
+        id: entry.id,
+        title: entry.title,
+        collapsed: false,
+        phases: synthetic,
+      });
+      continue;
+    }
+
+    milestones.push({
+      id: entry.id,
+      title: entry.title,
+      collapsed: false,
+      phases: [],
+    });
+  }
+
+  return milestones;
+}
+
 // ─── Plan Parser (XML-in-Markdown) ─────────────────────────────────────────
 
 /** Strip surrounding quotes from YAML string values */

package/src/resources/extensions/gsd/migrate/preview.ts

@@ -4,6 +4,13 @@
 import type { GSDProject } from './types.js';
 import type { MigrationPreview } from './writer.js';
 
+function countCanonicalDecisionRows(content: string): number {
+  return content
+    .split('\n')
+    .filter((line) => /^\|\s*D\d+\s*\|/.test(line.trim()))
+    .length;
+}
+
 /**
  * Compute pre-write statistics from a GSDProject without performing I/O.
  * Used to show the user what a migration will produce before writing anything.
@@ -36,6 +43,9 @@ export function generatePreview(project: GSDProject): MigrationPreview {
   }
 
   return {
+    decisions: {
+      total: countCanonicalDecisionRows(project.decisionsContent),
+    },
     milestoneCount: project.milestones.length,
     totalSlices,
     totalTasks,

package/src/resources/extensions/gsd/migrate/transformer.ts

@@ -238,16 +238,53 @@ function normalizeStatus(status: string): 'active' | 'validated' | 'deferred' {
   return 'active';
 }
 
+function normalizeRequirementId(id: string): string | null {
+  const match = id.trim().match(/^R(\d+)$/i);
+  if (!match) return null;
+  return `R${match[1].padStart(3, '0')}`;
+}
+
 function mapRequirements(reqs: PlanningRequirement[]): GSDRequirement[] {
   let autoId = 0;
+  const reservedIds = new Set(
+    reqs
+      .map((req) => normalizeRequirementId(req.id))
+      .filter((id): id is string => id !== null),
+  );
+  const usedIds = new Set<string>();
+
+  function nextRequirementId(): string {
+    let id = '';
+    do {
+      autoId++;
+      id = padId('R', autoId, 3);
+    } while (usedIds.has(id) || reservedIds.has(id));
+    usedIds.add(id);
+    return id;
+  }
+
   return reqs.map((req) => {
-    autoId++;
+    const originalId = req.id.trim();
+    const canonicalId = normalizeRequirementId(originalId);
+    let id: string;
+    let description = req.description;
+
+    if (canonicalId && !usedIds.has(canonicalId)) {
+      id = canonicalId;
+      usedIds.add(id);
+    } else {
+      id = nextRequirementId();
+      if (originalId) {
+        description = `Legacy ID: ${originalId}\n\n${description}`;
+      }
+    }
+
     return {
-      id: req.id && req.id.trim() !== '' ? req.id : padId('R', autoId, 3),
+      id,
       title: req.title,
       class: 'core-capability',
       status: normalizeStatus(req.status),
-      description: req.description,
+      description,
       source: 'inferred',
       primarySlice: 'none yet',
     };
@@ -286,7 +323,24 @@ function deriveDecisions(parsed: PlanningProject): string {
     }
   }
   if (decisions.length === 0) return '';
-  return decisions.map((d) => `- ${d}`).join('\n');
+  const lines = [
+    '# Decisions Register',
+    '',
+    '<!-- Append-only. Never edit or remove existing rows.',
+    '     To reverse a decision, add a new row that supersedes it.',
+    '     Read this file at the start of any planning or research phase. -->',
+    '',
+    '| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |',
+    '|---|------|-------|----------|--------|-----------|------------|---------|',
+  ];
+
+  decisions.forEach((decision, index) => {
+    const id = padId('D', index + 1, 3);
+    const escaped = decision.replace(/\|/g, '\\|');
+    lines.push(`| ${id} | migration | migrated-summary | ${escaped} | ${escaped} | Migrated from legacy summary key-decisions | Yes | agent |`);
+  });
+
+  return lines.join('\n') + '\n';
 }
 
 // ─── Main Entry Point ──────────────────────────────────────────────────────

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

@@ -37,6 +37,9 @@ export interface WrittenFiles {
 
 /** Pre-write statistics computed from a GSDProject without I/O. */
 export interface MigrationPreview {
+  decisions: {
+    total: number;
+  };
   milestoneCount: number;
   totalSlices: number;
   totalTasks: number;
@@ -374,7 +377,17 @@ export function formatProject(content: string): string {
  */
 export function formatDecisions(content: string): string {
   if (!content || !content.trim()) {
-    return '# Decisions\n\n<!-- Append-only register of architectural and pattern decisions -->\n\n| ID | Decision | Rationale | Date |\n|----|----------|-----------|------|\n';
+    return [
+      '# Decisions Register',
+      '',
+      '<!-- Append-only. Never edit or remove existing rows.',
+      '     To reverse a decision, add a new row that supersedes it.',
+      '     Read this file at the start of any planning or research phase. -->',
+      '',
+      '| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |',
+      '|---|------|-------|----------|--------|-----------|------------|---------|',
+      '',
+    ].join('\n');
   }
   return content.endsWith('\n') ? content : content + '\n';
 }

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

@@ -2,21 +2,17 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
-  clearEngineHierarchy,
   getAllMilestones,
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
-  transaction,
 } from "./gsd-db.js";
-import { migrateHierarchyToDb } from "./md-importer.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import {
   milestonesDir,
   resolveMilestoneFile,
   resolveSliceFile,
 } from "./paths.js";
-import { invalidateStateCache } from "./state.js";
 
 export interface HierarchyCounts {
   milestones: number;
@@ -25,11 +21,13 @@ export interface HierarchyCounts {
 }
 
 export interface MigrationAutoCheckResult {
-  action: "none" | "imported";
+  action: "none" | "recovery-required";
   reason: "no-markdown" | "in-sync" | "db-empty" | "count-mismatch";
   markdown: HierarchyCounts;
   beforeDb: HierarchyCounts;
   afterDb: HierarchyCounts;
+  recoveryCommand?: string;
+  message?: string;
 }
 
 function zeroCounts(): HierarchyCounts {
@@ -83,7 +81,7 @@ export function countDbHierarchy(): HierarchyCounts {
   return counts;
 }
 
-export async function autoImportMarkdownHierarchyIfDbMismatch(
+export async function checkMarkdownHierarchyAgainstDb(
   basePath: string,
 ): Promise<MigrationAutoCheckResult> {
   const markdown = countMarkdownHierarchy(basePath);
@@ -108,22 +106,16 @@ export async function autoImportMarkdownHierarchyIfDbMismatch(
   }
 
   const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
-  const imported = transaction(() => {
-    clearEngineHierarchy();
-    return migrateHierarchyToDb(basePath);
-  });
-  invalidateStateCache();
-
-  const afterDb = {
-    milestones: imported.milestones,
-    slices: imported.slices,
-    tasks: imported.tasks,
+  return {
+    action: "recovery-required",
+    reason,
+    markdown,
+    beforeDb,
+    afterDb: beforeDb,
+    recoveryCommand: "gsd recover",
+    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). ` +
+      "Runtime startup will not import markdown automatically; run explicit GSD recovery if markdown should repopulate the database.",
   };
-  if (!sameCounts(markdown, afterDb)) {
-    throw new Error(
-      `migration auto-import verification failed: markdown ${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T, db ${afterDb.milestones}M/${afterDb.slices}S/${afterDb.tasks}T`,
-    );
-  }
-
-  return { action: "imported", reason, markdown, beforeDb, afterDb };
 }