@opengsd/gsd-pi 1.3.0-dev.72e3af2a → 1.3.0-dev.738160b9

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/orphan-stash-audit.test.ts

@@ -1,6 +1,7 @@
 // gsd-pi + src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts
-// Regression: orphaned gsd-preflight-stash entries from completed milestones
-// must be auto-applied at startup so the user's pre-merge work returns.
+// Regression coverage for orphaned gsd-preflight-stash entries from completed
+// milestones: safe startup recovery for untracked work, manual warnings for
+// tracked or dirty-tree cases that would silently mutate user state.
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
@@ -37,6 +38,13 @@ function pushPreflightStash(repo: string, milestoneId: string, fileName: string,
   return marker;
 }
 
+function pushTrackedPreflightStash(repo: string, milestoneId: string, fileName: string, content: string): string {
+  writeFileSync(join(repo, fileName), content);
+  const marker = `gsd-preflight-stash:${milestoneId}:42:1700000000000:tracked`;
+  git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
+  return marker;
+}
+
 describe("auditOrphanedPreflightStashes", () => {
   let repo: string;
 
@@ -83,6 +91,23 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(list, /gsd-preflight-stash:M002:/);
   });
 
+  test("does not auto-apply a tracked orphan preflight stash onto a clean working tree", () => {
+    pushTrackedPreflightStash(repo, "M006", "seed.txt", "seed\ntracked pre-merge work\n");
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /stash modifies tracked files/);
+    assert.match(result.warnings[0], /git stash apply stash@\{\d+\}/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M006:/);
+  });
+
   test("ignores stashes whose milestone is not complete", () => {
     pushPreflightStash(repo, "M003", "wip.txt", "still-working\n");
 
@@ -115,23 +140,25 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(result.warnings[0], /db unavailable/);
   });
 
-  test("collects a warning when stash apply fails (conflicting working tree)", () => {
-    // Push a stash containing a change to seed.txt; then dirty seed.txt with
-    // a conflicting modification before the audit runs so apply fails.
+  test("collects a warning instead of applying when the working tree is not clean", () => {
+    // Push a stash containing a change to seed.txt; then dirty seed.txt before
+    // the audit runs. Startup recovery must leave the tree untouched and ask
+    // the user to apply the retained backup stash manually.
     writeFileSync(join(repo, "seed.txt"), "stashed\n");
     const marker = `gsd-preflight-stash:M005:42:1700:zz`;
     git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
 
-    // Dirty the working tree so apply will conflict.
     writeFileSync(join(repo, "seed.txt"), "conflicting modification\n");
 
     const result = auditOrphanedPreflightStashes(repo, () => true);
 
     assert.equal(result.applied.length, 0);
     assert.equal(result.warnings.length, 1);
-    assert.match(result.warnings[0], /Could not apply orphaned preflight stash/);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
     assert.match(result.warnings[0], /M005/);
     assert.match(result.warnings[0], /git stash apply/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "conflicting modification\n");
 
     const list = git(repo, "stash", "list");
     assert.match(list, /gsd-preflight-stash:M005:/);
@@ -169,6 +196,63 @@ describe("auditOrphanedPreflightStashes", () => {
       "second run must NOT warn — files are already restored from first run",
     );
   });
+
+  test("warns instead of silently skipping when only some stash untracked files were restored", () => {
+    // Cursor Bugbot caught: isAlreadyRestoredUntrackedStatus treated a dirty
+    // tree as fully restored when every *current* untracked path appeared in
+    // the stash, without requiring every *stash* untracked path to be present.
+    // A partial restore (only some files recovered) was misread as the
+    // idempotent steady state, so the audit no-oped and the remaining pre-merge
+    // files stayed missing with no warning.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+    writeFileSync(join(repo, "second.txt"), "second\n");
+    const marker = `gsd-preflight-stash:M007:42:1700000000000:partial`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    // Both files are stashed away.
+    assert.equal(existsSync(join(repo, "first.txt")), false);
+    assert.equal(existsSync(join(repo, "second.txt")), false);
+
+    // Simulate a partial restore: only first.txt came back; second.txt is still
+    // missing from the working tree.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    // Must NOT be treated as already-restored: second.txt is still missing, so
+    // the audit must surface a manual-recovery warning rather than no-op.
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1, "partial restore must warn, not silently no-op");
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
+    assert.match(result.warnings[0], /M007/);
+    assert.match(result.warnings[0], /git stash apply/);
+
+    // The stash entry must remain so the user can recover second.txt manually.
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M007:/);
+  });
+
+  test("fully restored multi-file untracked stash stays a silent no-op", () => {
+    // Guards the other direction of the set-equality fix: when EVERY stash
+    // untracked file is present in the working tree, the genuine idempotent
+    // steady state must still be recognized and skipped without warning, even
+    // when the stash captured more than one file.
+    writeFileSync(join(repo, "alpha.txt"), "alpha\n");
+    writeFileSync(join(repo, "beta.txt"), "beta\n");
+    const marker = `gsd-preflight-stash:M008:42:1700000000000:multi`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    const first = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(first.applied.length, 1, "first run applies both files");
+    assert.equal(first.warnings.length, 0);
+    assert.equal(existsSync(join(repo, "alpha.txt")), true);
+    assert.equal(existsSync(join(repo, "beta.txt")), true);
+
+    const second = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(second.applied.length, 0, "second run skips");
+    assert.equal(second.warnings.length, 0, "fully restored multi-file stash must not warn");
+  });
 });
 
 test("_isAlreadyRestoredApplyError detects the git stash apply already-exists error", () => {

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

@@ -58,6 +58,8 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  // diagnostics-only: compares PLAN.md task checkboxes against DB status
+  "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces
   "gsd/workspace-index.ts",
   "gsd/visualizer-data.ts",

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -94,6 +94,16 @@ test("plan-slice prompt: absence checks use negated quiet searches", () => {
   assert.ok(result.includes("count commands exit 1 when they find zero matches"));
 });
 
+test("plan-slice prompt: npm package existence rule is stated during generation", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("reference only packages that exist on the public npm registry"));
+  assert.ok(result.includes("remove or correct any package name that is not real"));
+  // The post-unit pre-execution gate parses package names from require/import
+  // patterns too, not just install commands, so the rule must cover that scope.
+  assert.ok(result.includes("require('...')"));
+  assert.ok(result.includes("import ... from '...'"));
+});
+
 test("plan-slice prompt: footer references gsd_plan_slice tool, not direct write", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
   assert.ok(

package/src/resources/extensions/gsd/tests/plan-slice.test.ts

@@ -8,6 +8,7 @@ import { tmpdir } from 'node:os';
 
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getSlice, getSliceTasks, getTask, getGateResults, updateTaskStatus } from '../gsd-db.ts';
 import { handlePlanSlice } from '../tools/plan-slice.ts';
+import { handlePlanTask } from '../tools/plan-task.ts';
 import { parsePlan } from '../parsers-legacy.ts';
 import { deriveState, invalidateStateCache } from '../state.ts';
 
@@ -511,15 +512,113 @@ test('handlePlanSlice leaves omitted enrichment fields empty instead of renderin
   }
 });
 
-test('handlePlanSlice rejects invalid payloads', async () => {
+test('handlePlanSlice accepts metadata-only payloads without deleting existing tasks', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
 
   try {
     seedParentSlice();
-    const result = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
-    assert.ok('error' in result);
-    assert.match(result.error, /validation failed: tasks must be a non-empty array/);
+    const first = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`);
+    assert.equal(getSliceTasks('M001', 'S02').length, 2);
+
+    const second = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist updated slice metadata before incremental tasks.',
+      successCriteria: '- Metadata renders before task planning',
+      proofLevel: 'unit',
+      integrationClosure: 'Task details follow through gsd_plan_task.',
+      observabilityImpact: 'Progress survives between tool calls.',
+    }, base);
+    assert.ok(!('error' in second), `unexpected error: ${'error' in second ? second.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist updated slice metadata before incremental tasks.');
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+
+    const third = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
+    assert.ok(!('error' in third), `unexpected error: ${'error' in third ? third.error : ''}`);
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice metadata-only on a fresh sketch slice keeps is_sketch set and renders no PLAN.md (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    // The incremental flow's first call carries metadata only (no tasks). It
+    // must NOT error (renderPlanFromDb throws on a task-less slice), and it must
+    // NOT clear the sketch flag — clearing it without a PLAN.md would leave the
+    // slice out of refining with no plan artifact, breaking sketch/plan signaling.
+    const result = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist slice metadata before any tasks exist.',
+    }, base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist slice metadata before any tasks exist.');
+    assert.equal(getSliceTasks('M001', 'S02').length, 0);
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 1, 'sketch flag must stay set until a task-bearing plan renders');
+
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(!existsSync(planPath), 'no PLAN.md should be rendered until the first task is planned');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.equal(after.phase, 'refining', 'a task-less sketch slice stays in refining');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask materializes the slice PLAN.md and clears the sketch flag on the incremental path (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    const sliceResult = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Incrementally planned slice.',
+      successCriteria: '- The slice plan is built up one task at a time',
+    }, base);
+    assert.ok(!('error' in sliceResult), `unexpected error: ${'error' in sliceResult ? sliceResult.error : ''}`);
+
+    const taskResult = await handlePlanTask({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      taskId: 'T01',
+      title: 'First incremental task',
+      description: 'Implement the first task added through gsd_plan_task.',
+      estimate: '30m',
+      files: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+      verify: 'node --test src/resources/extensions/gsd/tests/plan-task.test.ts',
+      inputs: ['src/resources/extensions/gsd/tools/plan-milestone.ts'],
+      expectedOutput: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+    }, base);
+    assert.ok(!('error' in taskResult), `unexpected error: ${'error' in taskResult ? taskResult.error : ''}`);
+
+    // The first incremental task materializes the canonical slice PLAN.md with
+    // the task present, and clears the sketch flag now that a plan exists.
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice PLAN.md should exist after the first task is planned');
+    const parsedPlan = parsePlan(readFileSync(planPath, 'utf-8'));
+    assert.equal(parsedPlan.goal, 'Incrementally planned slice.');
+    assert.equal(parsedPlan.tasks.length, 1);
+    assert.equal(parsedPlan.tasks[0]?.id, 'T01');
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 0, 'sketch flag must clear once the first task renders a plan');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.notEqual(after.phase, 'refining', 'a planned slice leaves refining');
   } finally {
     cleanup(base);
   }