@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0

package/src/resources/extensions/gsd/tests/file-change-validator.test.ts

@@ -116,6 +116,46 @@ test("effectiveFileChangeAllowlist keeps .gitignore auditable when management is
   assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], false), ["docs/**"]);
 });
 
+test("validateFileChanges excludes .gsd-backups/ migration snapshots from unexpected-change warnings", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const backupFile = join(
+    base,
+    ".gsd-backups",
+    "migrate-1782703701330",
+    "M010",
+    "slices",
+    "S01",
+    "S01-ASSESSMENT.md",
+  );
+  mkdirSync(join(base, "src"), { recursive: true });
+  mkdirSync(join(backupFile, ".."), { recursive: true });
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+
+  writeFileSync(join(base, "src", "app.ts"), "initial\n");
+  writeFileSync(backupFile, "legacy assessment\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "initial");
+
+  writeFileSync(join(base, "src", "app.ts"), "updated\n");
+  writeFileSync(backupFile, "legacy assessment touched\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "task commit");
+
+  const audit = validateFileChanges(base, ["src/app.ts"], []);
+  assert.ok(audit, "audit should be produced");
+  assert.deepEqual(audit!.unexpectedFiles, [], ".gsd-backups/ must not trigger warnings");
+  assert.equal(
+    audit!.violations.filter(v => v.severity === "warning").length,
+    0,
+    "no warnings when only source and migration backup files changed",
+  );
+});
+
 test("GSD-managed .gitignore edit swept into a task commit is not flagged", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/flat-phase-migration.test.ts

@@ -2,12 +2,16 @@
 // File Purpose: Tests the one-time migration from nested to flat-phase layout.
 import test, { afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, readFileSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { migrateToFlatPhase, needsFlatPhaseMigration } from "../flat-phase-migration.ts";
+import {
+  migrateToFlatPhase,
+  needsFlatPhaseMigration,
+  pruneStaleFlatPhaseBackups,
+} from "../flat-phase-migration.ts";
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
 
 const tmpDirs: string[] = [];
@@ -112,3 +116,34 @@ test("migrateToFlatPhase preserves slice sidecar artifacts and skips recovery pl
     "recovery placeholder PLAN should not be promoted when no DB tasks can render a real plan",
   );
 });
+
+test("pruneStaleFlatPhaseBackups removes migrate-* dirs older than retention window", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+
+  const backupRoot = join(base, ".gsd-backups");
+  assert.ok(existsSync(backupRoot), "backup should exist immediately after migration");
+
+  const staleDir = join(backupRoot, "migrate-stale");
+  mkdirSync(staleDir, { recursive: true });
+  writeFileSync(join(staleDir, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(staleDir, staleDate, staleDate);
+
+  const removed = pruneStaleFlatPhaseBackups(base);
+  assert.equal(removed, 1, "stale migrate-* dir should be pruned");
+  assert.equal(existsSync(staleDir), false, "stale backup dir should be gone");
+  assert.ok(existsSync(backupRoot), "fresh migration backup should remain");
+});
+
+test("pruneStaleFlatPhaseBackups is a no-op while flat-phase migration is still needed", () => {
+  const base = makeTmp();
+  const backupRoot = join(base, ".gsd-backups", "migrate-stale");
+  mkdirSync(backupRoot, { recursive: true });
+  writeFileSync(join(backupRoot, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(backupRoot, staleDate, staleDate);
+
+  assert.equal(pruneStaleFlatPhaseBackups(base), 0, "must not prune while migration is pending");
+  assert.ok(existsSync(backupRoot), "backup must remain until migration completes");
+});

package/src/resources/extensions/gsd/tests/gitignore-bg-shell-runtime.test.ts

@@ -40,6 +40,10 @@ describe('ensureGitignore writes .bg-shell/ baseline (#4902)', () => {
         lines.has('.bg-shell/'),
         `.gitignore should include .bg-shell/. Got:\n${ignore}`,
       );
+      assert.ok(
+        lines.has('.gsd-backups/'),
+        `.gitignore should include .gsd-backups/. Got:\n${ignore}`,
+      );
     } finally {
       cleanup(dir);
     }

package/src/resources/extensions/gsd/tests/integration/git-service.test.ts

@@ -294,12 +294,13 @@ describe('git-service', async () => {
 
   assert.deepStrictEqual(
     RUNTIME_EXCLUSION_PATHS.length,
-    17,
-    "exactly 17 runtime exclusion paths"
+    18,
+    "exactly 18 runtime exclusion paths"
   );
 
   const expectedPaths = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -1623,11 +1624,13 @@ process.exit(result.status ?? 0);
     // Create and track runtime files (simulates pre-.gitignore state)
     mkdirSync(join(repo, ".gsd", "activity"), { recursive: true });
     mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+    mkdirSync(join(repo, ".gsd-backups", "migrate-old"), { recursive: true });
     writeFileSync(join(repo, ".gsd", "completed-units.json"), '["u1"]');
     writeFileSync(join(repo, ".gsd", "metrics.json"), '{}');
     writeFileSync(join(repo, ".gsd", "STATE.md"), "# State");
     writeFileSync(join(repo, ".gsd", "activity", "log.jsonl"), "{}");
     writeFileSync(join(repo, ".gsd", "runtime", "data.json"), "{}");
+    writeFileSync(join(repo, ".gsd-backups", "migrate-old", "marker.txt"), "backup");
     writeFileSync(join(repo, "src.ts"), "code");
     runGit(repo, ["add", "-A"]);
     runGit(repo, ["commit", "-m", "init"]);
@@ -1636,6 +1639,8 @@ process.exit(result.status ?? 0);
     const trackedBefore = run("git ls-files .gsd/", repo);
     assert.ok(trackedBefore.includes("completed-units.json"), "untrack: precondition — completed-units tracked");
     assert.ok(trackedBefore.includes("metrics.json"), "untrack: precondition — metrics tracked");
+    const backupTrackedBefore = run("git ls-files .gsd-backups/", repo);
+    assert.ok(backupTrackedBefore.includes("marker.txt"), "untrack: precondition — migration backup tracked");
 
     // Run untrackRuntimeFiles
     untrackRuntimeFiles(repo);
@@ -1643,6 +1648,8 @@ process.exit(result.status ?? 0);
     // Runtime files should be removed from the index
     const trackedAfter = run("git ls-files .gsd/", repo);
     assert.deepStrictEqual(trackedAfter, "", "untrack: all runtime files removed from index");
+    const backupTrackedAfter = run("git ls-files .gsd-backups/", repo);
+    assert.deepStrictEqual(backupTrackedAfter, "", "untrack: migration backups removed from index");
 
     // Non-runtime files remain tracked
     const srcTracked = run("git ls-files src.ts", repo);
@@ -1653,6 +1660,8 @@ process.exit(result.status ?? 0);
       "untrack: completed-units.json still on disk");
     assert.ok(existsSync(join(repo, ".gsd", "metrics.json")),
       "untrack: metrics.json still on disk");
+    assert.ok(existsSync(join(repo, ".gsd-backups", "migrate-old", "marker.txt")),
+      "untrack: migration backup still on disk");
 
     // Idempotent — running again doesn't error
     untrackRuntimeFiles(repo);

package/src/resources/extensions/gsd/tests/json-persistence-atomic.test.ts

@@ -19,6 +19,7 @@ import { tmpdir } from "node:os";
 
 import {
   saveJsonFile,
+  saveJsonFileCompact,
   loadJsonFile,
   writeJsonFileAtomic,
 } from "../json-persistence.ts";
@@ -56,6 +57,37 @@ test("saveJsonFile creates file with valid JSON content", () => {
   }
 });
 
+test("saveJsonFile keeps pretty-printed output for human-readable state", () => {
+  const dir = makeTempDir();
+  const filePath = join(dir, "pretty.json");
+
+  try {
+    const data = { foo: "bar", nested: { count: 42 } };
+    saveJsonFile(filePath, data);
+
+    const content = readFileSync(filePath, "utf-8");
+    assert.equal(content, JSON.stringify(data, null, 2) + "\n");
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("saveJsonFileCompact writes valid compact JSON content", () => {
+  const dir = makeTempDir();
+  const filePath = join(dir, "compact.json");
+
+  try {
+    const data = { foo: "bar", nested: { count: 42 } };
+    saveJsonFileCompact(filePath, data);
+
+    const content = readFileSync(filePath, "utf-8");
+    assert.equal(content, JSON.stringify(data) + "\n");
+    assert.deepEqual(JSON.parse(content), data);
+  } finally {
+    cleanup(dir);
+  }
+});
+
 test("saveJsonFile does not leave .tmp files on success", () => {
   const dir = makeTempDir();
   const filePath = join(dir, "clean.json");
@@ -72,6 +104,21 @@ test("saveJsonFile does not leave .tmp files on success", () => {
   }
 });
 
+test("saveJsonFileCompact does not leave .tmp files on success", () => {
+  const dir = makeTempDir();
+  const filePath = join(dir, "compact-clean.json");
+
+  try {
+    saveJsonFileCompact(filePath, { test: true });
+
+    const files = readdirSync(dir);
+    const tmpFiles = files.filter(f => f.includes(".tmp"));
+    assert.equal(tmpFiles.length, 0, `Unexpected .tmp files: ${tmpFiles.join(", ")}`);
+  } finally {
+    cleanup(dir);
+  }
+});
+
 test("saveJsonFile creates parent directories", () => {
   const dir = makeTempDir();
   const filePath = join(dir, "deep", "nested", "data.json");

package/src/resources/extensions/gsd/tests/knowledge-backfill-projection.test.ts

@@ -161,6 +161,41 @@ test("backfill is idempotent — second run on the same file is a no-op", () =>
   }
 });
 
+test("backfill skips a knowledge row whose memory insert throws and continues later rows", () => {
+  const base = makeTmpBase();
+  try {
+    writeKnowledgeMd(base, FIXTURE);
+
+    const adapter = _getAdapter();
+    assert.ok(adapter);
+    adapter.exec(`
+      CREATE TRIGGER fail_p002_memory_insert
+      BEFORE INSERT ON memories
+      WHEN json_extract(NEW.structured_fields, '$.sourceKnowledgeId') = 'P002'
+      BEGIN
+        SELECT RAISE(ABORT, 'poison knowledge P002');
+      END
+    `);
+
+    const written = backfillKnowledgeToMemories(base);
+    assert.equal(written, 2, "one poisoned row should not abort the batch");
+
+    const rows = adapter
+      .prepare(
+        "SELECT structured_fields FROM memories WHERE structured_fields LIKE '%\"sourceKnowledgeId\":\"%' ORDER BY seq",
+      )
+      .all() as Array<{ structured_fields: string }>;
+
+    assert.deepEqual(
+      rows.map((row) => JSON.parse(row.structured_fields).sourceKnowledgeId),
+      ["P001", "L001"],
+      "rows after the poisoned knowledge entry should still be migrated",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("backfill returns 0 when KNOWLEDGE.md is absent", () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/memory-store.test.ts

@@ -5,6 +5,9 @@ import {
   SCHEMA_VERSION,
   _getAdapter,
 } from '../gsd-db.ts';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
 import {
   _resetLogs,
   peekLogs,
@@ -22,6 +25,7 @@ import {
   markUnitProcessed,
   decayStaleMemories,
   enforceMemoryCap,
+  queryMemoriesRanked,
   applyMemoryActions,
   formatMemoriesForPrompt,
 } from '../memory-store.ts';
@@ -29,6 +33,16 @@ import type { MemoryAction } from '../memory-store.ts';
 import { describe, test, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-memory-store-test-'));
+  return path.join(dir, 'test.db');
+}
+
+function cleanupDbPath(dbPath: string): void {
+  closeDatabase();
+  fs.rmSync(path.dirname(dbPath), { recursive: true, force: true });
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // memory-store: fallback when DB not open
 // ═══════════════════════════════════════════════════════════════════════════
@@ -366,6 +380,40 @@ test('memory-store: schema includes memories table', () => {
   closeDatabase();
 });
 
+test('memory-store: reopening rebuilds FTS index for pre-FTS memories', () => {
+  const dbPath = tempDbPath();
+  try {
+    openDatabase(dbPath);
+    const id = createMemory({ category: 'gotcha', content: 'pre FTS auth memory must become searchable' });
+    assert.equal(id, 'MEM001');
+
+    const adapter = _getAdapter()!;
+    const fts = adapter.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+    if (!fts) return;
+
+    adapter.exec('DROP TRIGGER IF EXISTS memories_ai');
+    adapter.exec('DROP TRIGGER IF EXISTS memories_ad');
+    adapter.exec('DROP TRIGGER IF EXISTS memories_au');
+    adapter.exec('DROP TABLE IF EXISTS memories_fts');
+    adapter.prepare(
+      "DELETE FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = 'memories_fts_rebuilt_at'",
+    ).run();
+    closeDatabase();
+
+    openDatabase(dbPath);
+    const reopened = _getAdapter()!;
+    const marker = reopened.prepare(
+      "SELECT value_json FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = 'memories_fts_rebuilt_at'",
+    ).get();
+    assert.ok(marker, 'FTS rebuild marker should be set after reopening');
+
+    const hits = queryMemoriesRanked({ query: 'auth', k: 5 }).map((hit) => hit.memory.id);
+    assert.deepEqual(hits, ['MEM001']);
+  } finally {
+    cleanupDbPath(dbPath);
+  }
+});
+
 // ═══════════════════════════════════════════════════════════════════════════
 // regression #4967 — createMemory must not silently swallow SQL errors
 // ═══════════════════════════════════════════════════════════════════════════

package/src/resources/extensions/gsd/tests/merge-closeout-consistency-gate.test.ts

@@ -9,7 +9,15 @@ import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
 import { mergeMilestoneToMain } from "../auto-worktree.ts";
-import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
+import { checkCloseoutConsistencyGate } from "../closeout-consistency-gate.ts";
+import {
+  closeDatabase,
+  insertAssessment,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
 
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
@@ -61,3 +69,25 @@ test("mergeMilestoneToMain blocks when project DB closeout is still open", () =>
     if (existsSync(repo)) rmSync(repo, { recursive: true, force: true });
   }
 });
+
+test("closeout consistency treats deferred slices as inactive", () => {
+  try {
+    assert.equal(openDatabase(":memory:"), true);
+    insertMilestone({ id: "M001", title: "Milestone One", status: "complete" });
+    insertSlice({ milestoneId: "M001", id: "S01", title: "Done", status: "complete" });
+    insertTask({ milestoneId: "M001", sliceId: "S01", id: "T01", title: "Done", status: "complete" });
+    insertSlice({ milestoneId: "M001", id: "S02", title: "Deferred", status: "deferred" });
+    insertTask({ milestoneId: "M001", sliceId: "S02", id: "T02", title: "Deferred", status: "pending" });
+    insertAssessment({
+      path: "milestones/M001/M001-VALIDATION.md",
+      milestoneId: "M001",
+      status: "pass",
+      scope: "milestone-validation",
+      fullContent: "verdict: pass",
+    });
+
+    assert.deepEqual(checkCloseoutConsistencyGate("M001"), { ok: true });
+  } finally {
+    closeDatabase();
+  }
+});

package/src/resources/extensions/gsd/tests/metrics-prune-cache-invalidation.test.ts

@@ -112,6 +112,12 @@ describe("pruneMetricsLedger: invalidates scoped ledger cache", () => {
     // 3. Prune to keepCount=2 — should evict 3 old units from disk AND clear scopedLedgers.
     const removed = pruneMetricsLedger(tmpDir, 2);
     assert.equal(removed, 3, "pruneMetricsLedger should report 3 removed units");
+    const prunedRaw = readFileSync(metricsPath(tmpDir), "utf-8");
+    assert.equal(
+      prunedRaw,
+      JSON.stringify(JSON.parse(prunedRaw)) + "\n",
+      "pruneMetricsLedger should persist compact metrics.json",
+    );
 
     // 4. Snapshot a new unit via scope. This exercises the lazy-reload path
     //    (scopedLedgers was cleared by prune) and writes the result to disk.

package/src/resources/extensions/gsd/tests/metrics.test.ts

@@ -259,6 +259,7 @@ test("initMetrics creates ledger, snapshotUnitMetrics persists across resets", (
     // Verify file content
     const raw = readFileSync(join(tmpBase, ".gsd", "metrics.json"), "utf-8");
     const parsed: MetricsLedger = JSON.parse(raw);
+    assert.equal(raw, JSON.stringify(parsed) + "\n", "metrics.json should be serialized compactly");
     assert.equal(parsed.version, 1);
     assert.equal(parsed.units.length, 1);
 

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

@@ -7,7 +7,10 @@ import {
   existsSync,
   mkdirSync,
   realpathSync,
+  readFileSync,
 } from "node:fs";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -116,6 +119,60 @@ describe("migrate-external worktree guard (#2970)", () => {
   });
 });
 
+describe("migrateToExternalState copy failure rollback (#1047)", () => {
+  test("restores .gsd when a source entry fails to copy", () => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-migrate-copy-fail-")));
+    const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-state-copy-fail-")));
+    const previousStateDir = process.env.GSD_STATE_DIR;
+    const previousProjectId = process.env.GSD_PROJECT_ID;
+    const originalCpSync = fs.cpSync;
+    process.env.GSD_STATE_DIR = stateDir;
+    process.env.GSD_PROJECT_ID = "copy-fail";
+
+    try {
+      run("git init -b main", base);
+      mkdirSync(join(base, ".gsd"), { recursive: true });
+      writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "# prefs\n", "utf-8");
+      writeFileSync(join(base, ".gsd", "gsd.db"), "state", "utf-8");
+      const failingSource = join(base, ".gsd.migrating", "gsd.db");
+      fs.cpSync = ((...args: Parameters<typeof fs.cpSync>) => {
+        const src = args[0];
+        if (String(src) === failingSource) {
+          const error = new Error("simulated copy failure") as NodeJS.ErrnoException;
+          error.code = "EACCES";
+          throw error;
+        }
+        return originalCpSync(...args);
+      }) as typeof fs.cpSync;
+      syncBuiltinESMExports();
+
+      const result = migrateToExternalState(base);
+
+      assert.equal(result.migrated, false, "copy failure must fail the migration");
+      assert.match(result.error ?? "", /Migration copy failed/);
+      assert.ok(existsSync(join(base, ".gsd", "gsd.db")), "source .gsd must be restored");
+      assert.equal(readFileSync(join(base, ".gsd", "PREFERENCES.md"), "utf-8"), "# prefs\n");
+      assert.ok(!existsSync(join(base, ".gsd.migrating")), "backup staging dir must not remain after restore");
+      assert.ok(!existsSync(join(stateDir, "projects", "copy-fail", "gsd.db")), "failed file must not be reported as migrated");
+    } finally {
+      fs.cpSync = originalCpSync;
+      syncBuiltinESMExports();
+      if (previousStateDir === undefined) {
+        delete process.env.GSD_STATE_DIR;
+      } else {
+        process.env.GSD_STATE_DIR = previousStateDir;
+      }
+      if (previousProjectId === undefined) {
+        delete process.env.GSD_PROJECT_ID;
+      } else {
+        process.env.GSD_PROJECT_ID = previousProjectId;
+      }
+      rmSync(base, { recursive: true, force: true });
+      rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+});
+
 // Regression tests for #5571 — recoverFailedMigration handles orphaned .gsd.migrating
 describe("recoverFailedMigration (#5571)", () => {
   test("returns false when .gsd.migrating does not exist", () => {

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

@@ -429,3 +429,73 @@ test("rebuildMarkdownProjectionsFromDb realigns markdown when DB holds extra row
     cleanup(base);
   }
 });
+
+test("rebuildMarkdownProjectionsFromDb realigns markdown for numeric milestone IDs", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory({ projectContent: "# P\n", decisionsContent: "", requirements: [], milestones: [] }, base);
+    assert.equal(await ensureDbOpen(base), true);
+    insertMilestone({ id: "15", title: "Numeric milestone", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "15",
+      title: "Numeric slice",
+      status: "pending",
+      risk: "medium",
+      depends: [],
+      demo: "d",
+      sequence: 1,
+    });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "15",
+      title: "Numeric task",
+      status: "pending",
+    });
+
+    const before = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(before.recoveryCommand, "/gsd rebuild markdown");
+
+    const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.ts");
+    const rebuild = await rebuildMarkdownProjectionsFromDb(base);
+    assert.ok(rebuild.rendered > 0, "expected markdown projections to render");
+
+    const after = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(after.action, "none");
+    assert.equal(after.reason, "in-sync");
+    assert.deepEqual(after.markdown, { milestones: 1, slices: 1, tasks: 1 });
+    assert.deepEqual(after.beforeDb, { milestones: 1, slices: 1, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("rebuildMarkdownProjectionsFromDb realigns markdown for planned zero-slice milestones", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory({ projectContent: "# P\n", decisionsContent: "", requirements: [], milestones: [] }, base);
+    assert.equal(await ensureDbOpen(base), true);
+    insertMilestone({
+      id: "M016",
+      title: "Queued milestone",
+      status: "queued",
+      planning: { vision: "Defined but not sliced yet" },
+    });
+
+    const before = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(before.recoveryCommand, "/gsd rebuild markdown");
+
+    const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.ts");
+    const rebuild = await rebuildMarkdownProjectionsFromDb(base);
+    assert.ok(rebuild.rendered > 0, "expected markdown projections to render");
+
+    const after = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(after.action, "none");
+    assert.equal(after.reason, "in-sync");
+    assert.deepEqual(after.markdown, { milestones: 1, slices: 0, tasks: 0 });
+    assert.deepEqual(after.beforeDb, { milestones: 1, slices: 0, tasks: 0 });
+  } finally {
+    cleanup(base);
+  }
+});