gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -0,0 +1,186 @@
+/**
+ * clean-root-preflight.test.ts — Regression tests for #2909.
+ *
+ * Tests that preflightCleanRoot warns + stashes on dirty trees,
+ * is a no-op on clean trees, and that postflightPopStash restores
+ * stashed changes after a merge.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { preflightCleanRoot, postflightPopStash } from "../clean-root-preflight.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-preflight-test-")));
+  run("git init", dir);
+  run("git config user.email test@example.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+// ── Clean tree: fast-path returns immediately without stashing ─────────────
+
+test("preflightCleanRoot — clean tree returns stashPushed=false and emits no notifications", () => {
+  const repo = createTempRepo();
+  try {
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M001", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, false, "stashPushed must be false for clean tree");
+    assert.equal(result.summary, "", "summary must be empty for clean tree");
+    assert.equal(notifications.length, 0, "no notifications on clean tree");
+
+    // Verify no stash was created
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "no stash entry on clean tree");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Dirty tree: warns, stashes, returns stashPushed=true ──────────────────
+
+test("preflightCleanRoot — dirty tree warns user and auto-stashes", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty an existing tracked file
+    writeFileSync(join(repo, "README.md"), "# locally modified\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M002", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true when tree was dirty");
+    assert.ok(result.summary.length > 0, "summary must be non-empty when stash was pushed");
+
+    // A warning notification must have been emitted before stashing
+    assert.ok(
+      notifications.some(n => n.level === "warning" && n.msg.includes("M002")),
+      "warning notification must mention the milestone ID",
+    );
+
+    // Working tree must now be clean (stash pushed)
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+
+    // The stash entry must exist
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash"), "stash entry must be named gsd-preflight-stash");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Untracked files are also stashed ─────────────────────────────────────
+
+test("preflightCleanRoot — untracked file triggers stash with --include-untracked", () => {
+  const repo = createTempRepo();
+  try {
+    // Add an untracked file
+    writeFileSync(join(repo, "untracked.ts"), "export const x = 1;\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M003", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true for untracked file");
+
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── postflightPopStash: restores stashed changes ──────────────────────────
+
+test("postflightPopStash — restores stashed changes and emits info notification", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty the working tree
+    writeFileSync(join(repo, "README.md"), "# stash me\n");
+
+    const preNotifications: Array<{ msg: string; level: string }> = [];
+    const preflight = preflightCleanRoot(repo, "M004", (msg, level) => {
+      preNotifications.push({ msg, level });
+    });
+    assert.equal(preflight.stashPushed, true, "preflight must have stashed");
+
+    // Simulate the merge (just a no-op commit here)
+    writeFileSync(join(repo, "merged.ts"), "export const merged = true;\n");
+    run("git add .", repo);
+    run('git commit -m "simulate merge"', repo);
+
+    const postNotifications: Array<{ msg: string; level: string }> = [];
+    postflightPopStash(repo, "M004", (msg, level) => {
+      postNotifications.push({ msg, level });
+    });
+
+    // The stashed README.md change must be restored
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# stash me\n", "stashed file must be restored");
+
+    // An info notification must have been emitted
+    assert.ok(
+      postNotifications.some(n => n.level === "info" && n.msg.includes("M004")),
+      "info notification must mention milestone ID after pop",
+    );
+
+    // Stash list must be empty
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "stash list must be empty after pop");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Round-trip: preflight + merge + postflight preserves changes ──────────
+
+test("preflight + merge + postflight round-trip preserves uncommitted changes", () => {
+  const repo = createTempRepo();
+  try {
+    const originalContent = "# my local work\n";
+    writeFileSync(join(repo, "README.md"), originalContent);
+
+    // Preflight: stash
+    const preflight = preflightCleanRoot(repo, "M005", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    // Merge: introduce a new file (no overlap with README.md)
+    writeFileSync(join(repo, "feature.ts"), "export const feature = true;\n");
+    run("git add feature.ts", repo);
+    run('git commit -m "feat: add feature"', repo);
+
+    // Postflight: pop stash
+    postflightPopStash(repo, "M005", () => {});
+
+    // README.md must still have our local content
+    const restored = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(restored.replace(/\r\n/g, "\n"), originalContent, "local changes must survive merge");
+
+    // feature.ts must also exist (the merge commit landed)
+    const featureContent = readFileSync(join(repo, "feature.ts"), "utf-8");
+    assert.ok(featureContent.includes("feature"), "merged feature must be present");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});

package/src/resources/extensions/gsd/tests/commands-extract-learnings.test.ts

@@ -245,7 +245,7 @@ describe("buildExtractLearningsPrompt", () => {
     assert.ok(result.includes("M001-VERIFICATION.md"));
   });
 
-  it("does NOT reference phantom capture_thought tool (regression for #4429)", () => {
+  it("references capture_thought as the memory-store mirror write (Option A' dual-write)", () => {
     const result = buildExtractLearningsPrompt({
       milestoneId: "M001",
       milestoneName: "Test Milestone",
@@ -260,8 +260,8 @@ describe("buildExtractLearningsPrompt", () => {
     });
 
     assert.ok(
-      !result.includes("capture_thought"),
-      "prompt must not advertise the non-existent capture_thought tool",
+      result.includes("capture_thought"),
+      "prompt must instruct the LLM to mirror durable insights into the memory store via capture_thought",
     );
   });
 
@@ -452,84 +452,84 @@ describe("buildExtractionStepsBlock", () => {
     assert.ok(block.includes("M042-ROADMAP.md"));
   });
 
-  it("points the LLM at .gsd/KNOWLEDGE.md for append", () => {
+  // ─── Removed by ADR-013 step 6 cutover ────────────────────────────────────
+  //
+  // The following nine tests asserted structural properties of the legacy
+  // KNOWLEDGE.md table scaffolding (Rules/Patterns/Lessons headers, P###/L###
+  // row templates, em-dash placeholders, append-only semantics, "missing file"
+  // template) and the gsd_save_decision call-out (parameter list, "never edit
+  // DECISIONS.md" prohibition). The cutover replaced both surfaces with
+  // capture_thought calls into the memories table; the extraction steps no
+  // longer reference KNOWLEDGE.md tables or gsd_save_decision at all, so each
+  // assertion is now structurally false.
+  //
+  // The replacement assertions ("removes the legacy KNOWLEDGE.md table append
+  // step", "removes the gsd_save_decision call", "requires structuredFields
+  // payload on architecture-category memories") below cover the inverse
+  // contract.
+  //
+  // Per ADR-013 cutover criterion: "No regression test in tests/ is silenced
+  // or removed without an explicit rationale comment in the diff." That
+  // criterion is satisfied by this comment block.
+
+  it("keeps Surprises milestone-local (not persisted to memory store, no MCP call)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes(".gsd/KNOWLEDGE.md"));
-  });
-
-  it("covers the missing-file case with the canonical KNOWLEDGE.md template", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("If the file does not exist yet, create it first"));
-    // Canonical column headers must be inlined so the LLM does not have to guess.
-    assert.ok(block.includes("| # | Scope | Rule | Why | Added |"));
-    assert.ok(block.includes("| # | Pattern | Where | Notes |"));
-    assert.ok(block.includes("| # | What Happened | Root Cause | Fix | Scope |"));
-  });
-
-  it("specifies the exact Patterns row format with milestone scope", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("| P<NNN>"));
-    assert.ok(block.includes(`| ${ctx.milestoneId} |`));
-  });
-
-  it("specifies the exact Lessons row format with milestone scope", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("| L<NNN>"));
-  });
-
-  it("enforces zero-padded three-digit IDs", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/zero[- ]pad/i.test(block));
-    assert.ok(block.includes("three digits") || block.includes("3 digits"));
-  });
-
-  it("instructs append-only behaviour (no edits to existing rows)", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("Append-only"));
-  });
-
-  it("uses em-dash as the placeholder for unknown column values", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("—"));
-    assert.ok(!block.includes("N/A"));
-  });
-
-  it("forbids modifications to the Rules table", () => {
-    const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/do not.*rules/i.test(block.toLowerCase()) || block.includes("Do NOT modify"));
-    assert.ok(block.includes("## Rules"));
+    assert.ok(block.includes("Surprises stay only in LEARNINGS.md"));
   });
 
-  it("routes Decisions through the gsd_save_decision MCP tool", () => {
+  it("enforces a deduplication rule across all persistence steps", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("gsd_save_decision"));
-    assert.ok(block.includes("`scope`"));
-    assert.ok(block.includes("`decision`"));
-    assert.ok(block.includes("`choice`"));
-    assert.ok(block.includes("`rationale`"));
-    assert.ok(block.includes("`made_by`"));
+    assert.ok(/deduplication/i.test(block) || /dedup/i.test(block));
+    assert.ok(/semantically equivalent/i.test(block));
+    assert.ok(/skip/i.test(block));
   });
 
-  it("forbids direct edits to DECISIONS.md (DB-authoritative)", () => {
+  it("instructs capture_thought as the sole persistence path for Patterns, Lessons, and Decisions (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/never edit.+decisions\.md/i.test(block));
+    // Each of the three persistence steps must call capture_thought.
+    const captureThoughtMatches = block.match(/capture_thought/g) ?? [];
+    assert.ok(
+      captureThoughtMatches.length >= 3,
+      `expected at least 3 capture_thought references (Patterns + Lessons + Decisions); got ${captureThoughtMatches.length}`,
+    );
+    // Required category vocabulary for the three captures.
+    assert.ok(/category:\s*"pattern"/.test(block), "Patterns must use category: \"pattern\"");
+    assert.ok(/category:\s*"gotcha"/.test(block), "Lessons must reference category: \"gotcha\"");
+    assert.ok(/category:\s*"architecture"/.test(block), "Decisions must use category: \"architecture\"");
+    // Milestone scope must be threaded through.
+    assert.ok(block.includes(`scope: "${ctx.milestoneId}"`), "capture_thought calls must scope to the milestone ID");
   });
 
-  it("keeps Surprises milestone-local (not in KNOWLEDGE.md, no tool call)", () => {
+  it("removes the legacy KNOWLEDGE.md table append step (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(block.includes("Surprises stay only in LEARNINGS.md"));
+    // ADR-013 Cutover: memories table is the single source of truth.
+    // KNOWLEDGE.md is no longer written by the extraction flow.
+    assert.ok(!block.includes("| # | Scope | Rule | Why | Added |"), "Rules table scaffolding must be removed");
+    assert.ok(!block.includes("| # | Pattern | Where | Notes |"), "Patterns table scaffolding must be removed");
+    assert.ok(!block.includes("| # | What Happened | Root Cause | Fix | Scope |"), "Lessons table scaffolding must be removed");
+    assert.ok(!/\| P<NNN>/.test(block), "Pattern row template must be removed");
+    assert.ok(!/\| L<NNN>/.test(block), "Lesson row template must be removed");
+    assert.ok(!block.includes(".gsd/KNOWLEDGE.md"), "extraction flow must not reference KNOWLEDGE.md as a write target");
   });
 
-  it("enforces a deduplication rule across all persistence steps", () => {
+  it("removes the gsd_save_decision call (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(/deduplication/i.test(block) || /dedup/i.test(block));
-    assert.ok(/semantically equivalent/i.test(block));
-    assert.ok(/skip/i.test(block));
+    // ADR-013 Cutover: decisions are now persisted via capture_thought with
+    // category=architecture and a structuredFields payload that preserves the
+    // gsd_save_decision schema. The legacy MCP tool is no longer called from
+    // the extraction flow.
+    assert.ok(!block.includes("gsd_save_decision"), "gsd_save_decision must no longer appear in extraction steps");
   });
 
-  it("does NOT reference the non-existent capture_thought tool (#4429 regression)", () => {
+  it("requires structuredFields payload on architecture-category memories (ADR-013 lossless projection)", () => {
     const block = buildExtractionStepsBlock(ctx);
-    assert.ok(!block.includes("capture_thought"));
+    // ADR-013 Cutover: architecture-category memories must carry structured
+    // fields so projection back to a human-visible decisions register stays
+    // lossless. The Decisions persistence step must instruct the LLM to set
+    // structuredFields with the original gsd_save_decision schema fields.
+    assert.ok(/structuredFields/.test(block), "Decisions persistence step must instruct structuredFields use");
+    assert.ok(/scope/i.test(block) && /decision/i.test(block) && /choice/i.test(block) && /rationale/i.test(block),
+      "structuredFields must enumerate the preserved decision fields");
   });
 
   it("does NOT reference the non-existent gsd_graph tool (#4429 regression)", () => {
@@ -614,7 +614,9 @@ describe("complete-milestone loadPrompt round-trip (#4429)", () => {
     // Placeholder must be gone — real content must be in.
     assert.ok(!rendered.includes("{{extractLearningsSteps}}"));
     assert.ok(rendered.includes("Structured Learnings Extraction"));
-    assert.ok(rendered.includes("gsd_save_decision"));
+    // ADR-013 cutover: gsd_save_decision is no longer in the rendered block;
+    // the new persistence path is capture_thought with structuredFields.
+    assert.ok(rendered.includes("capture_thought"));
     assert.ok(rendered.includes("M123"));
   });
 });

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -0,0 +1,123 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  buildSnapshot,
+  readCompactionSnapshot,
+  writeCompactionSnapshot,
+  DEFAULT_SNAPSHOT_BYTES,
+} from '../compaction-snapshot.ts';
+import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { createMemory } from '../memory-store.ts';
+import { executeResume } from '../tools/resume-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-snap-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+test('buildSnapshot: renders memories, exec history, and active context', () => {
+  const snap = buildSnapshot({
+    generatedAt: new Date('2026-04-20T12:00:00.000Z'),
+    activeContext: 'M001 / S01 / T01 — wire gsd_exec',
+    memories: [
+      { id: 'MEM001', category: 'gotcha', content: 'FTS5 needs Porter tokenizer', confidence: 0.9,
+        source_unit_type: null, source_unit_id: null, created_at: '', updated_at: '',
+        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null },
+    ],
+    execHistory: [
+      {
+        id: 'abc',
+        runtime: 'bash',
+        purpose: 'count TODOs',
+        started_at: '', finished_at: '', duration_ms: 10,
+        exit_code: 0, signal: null, timed_out: false,
+        stdout_bytes: 1, stderr_bytes: 0, stdout_truncated: false, stderr_truncated: false,
+        stdout_path: '/tmp/abc.stdout', stderr_path: '/tmp/abc.stderr', meta_path: '/tmp/abc.meta.json',
+      },
+    ],
+  });
+  assert.match(snap, /Active context/);
+  assert.match(snap, /M001 \/ S01 \/ T01/);
+  assert.match(snap, /FTS5 needs Porter tokenizer/);
+  assert.match(snap, /\[abc\] bash exit:0 — count TODOs/);
+});
+
+test('buildSnapshot: enforces the byte cap with a truncation marker', () => {
+  const longMemories = Array.from({ length: 50 }, (_v, i) => ({
+    id: `MEM${String(i).padStart(3, '0')}`,
+    category: 'gotcha',
+    content: 'x'.repeat(200),
+    confidence: 0.8,
+    source_unit_type: null,
+    source_unit_id: null,
+    created_at: '',
+    updated_at: '',
+    superseded_by: null,
+    hit_count: 0,
+    scope: 'project',
+    seq: i,
+    tags: [] as string[],
+    structured_fields: null,
+  }));
+  const snap = buildSnapshot(
+    { generatedAt: new Date(), memories: longMemories, execHistory: [] },
+    { maxBytes: 512, maxMemories: 50 },
+  );
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= 512, 'should respect cap');
+  assert.match(snap, /\[truncated\]/, 'should include truncation marker');
+});
+
+test('buildSnapshot: handles empty state with an explanatory placeholder', () => {
+  const snap = buildSnapshot({ generatedAt: new Date(), memories: [], execHistory: [] });
+  assert.match(snap, /_No durable memories/);
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= DEFAULT_SNAPSHOT_BYTES);
+});
+
+test('writeCompactionSnapshot + readCompactionSnapshot + executeResume: end-to-end', () => {
+  const base = freshBase();
+  try {
+    openDatabase(':memory:');
+    createMemory({ category: 'architecture', content: 'Single-writer DB through gsd-db.ts', confidence: 0.95 });
+    createMemory({ category: 'convention', content: 'Prefer typed helpers over raw SQL', confidence: 0.9 });
+
+    const out = writeCompactionSnapshot(base, { activeContext: 'M099 resume check' });
+    assert.ok(out.path.endsWith('last-snapshot.md'));
+    assert.ok(out.bytes > 0);
+    assert.equal(out.memories, 2);
+
+    const contents = readCompactionSnapshot(base);
+    assert.ok(contents);
+    assert.match(contents!, /Single-writer DB through gsd-db\.ts/);
+    assert.match(contents!, /M099 resume check/);
+
+    const tool = executeResume({}, { baseDir: base });
+    assert.ok(!tool.isError);
+    assert.equal(tool.details.found, true);
+    assert.match(tool.content[0].text, /Single-writer DB through gsd-db\.ts/);
+
+    // also verify the file content matches (without trailing newline)
+    const raw = readFileSync(out.path, 'utf-8');
+    assert.ok(raw.endsWith('\n'));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test('executeResume: reports friendly empty state when no snapshot exists', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base });
+    assert.equal(result.details.found, false);
+    assert.match(result.content[0].text, /No snapshot found/);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/complete-milestone-false-merge.test.ts

@@ -105,6 +105,21 @@ test("#4175: postUnitPreVerification pauses complete-milestone after retries exh
   );
 });
 
+test("#4658: postUnitPreVerification waits briefly for DB-close on complete-milestone before retrying", () => {
+  assert.ok(
+    /async function waitForMilestoneDbClose/.test(postUnitSrc),
+    "auto-post-unit should define a DB settle helper for complete-milestone",
+  );
+  assert.ok(
+    /setTimeout\(resolve,\s*COMPLETE_MILESTONE_DB_SETTLE_POLL_MS\)/.test(postUnitSrc),
+    "DB settle helper should poll with a bounded timeout window",
+  );
+  assert.ok(
+    /s\.currentUnit\.type\s*===\s*"complete-milestone"[\s\S]*waitForMilestoneDbClose/.test(postUnitSrc),
+    "complete-milestone path should invoke DB settle check before retry flow",
+  );
+});
+
 test("#4175: recoverTimedOutUnit pauses complete-milestone instead of writing a blocker placeholder", () => {
   // The complete-milestone pause branch must sit immediately above the
   // "retries exhausted" writeBlockerPlaceholder call so a failed

package/src/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -1,11 +1,14 @@
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { invalidateAllCaches } from '../cache.ts';
 import { parseUnitId } from "../unit-id.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { clearPathCache } from "../paths.ts";
+import { clearParseCache } from "../files.ts";
 
 // loadPrompt reads from ~/.gsd/agent/extensions/gsd/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
@@ -404,6 +407,63 @@ describe("complete-milestone", () => {
     }
   });
 
+  test("handleCompleteMilestone does not overwrite existing SUMMARY.md on re-dispatch (#4598)", async () => {
+    // This test verifies that when SUMMARY.md already exists (from a prior completion),
+    // re-calling handleCompleteMilestone does not overwrite it.
+    // Before the fix this test FAILS because the handler unconditionally writes SUMMARY.md.
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    const mid = "M001";
+    const dbPath = join(base, ".gsd", "gsd.db");
+    try {
+      // Set up DB with milestone and a complete slice + task
+      openDatabase(dbPath);
+      insertMilestone({ id: mid, title: "Test Milestone", status: "active" });
+      insertSlice({ id: "S01", milestoneId: mid, title: "Slice One", status: "complete" });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: mid, title: "Task One", status: "complete" });
+
+      // Pre-write an existing SUMMARY.md to simulate a prior completion
+      const milestoneDir = join(base, ".gsd", "milestones", mid);
+      mkdirSync(milestoneDir, { recursive: true });
+      const summaryPath = join(milestoneDir, `${mid}-SUMMARY.md`);
+      const originalContent = "original content — must not be overwritten";
+      writeFileSync(summaryPath, originalContent, "utf-8");
+
+      // Call handleCompleteMilestone — this is the re-dispatch scenario
+      const params = {
+        milestoneId: mid,
+        title: "Test Milestone",
+        oneLiner: "Re-dispatched",
+        narrative: "This is a re-dispatch",
+        successCriteriaResults: "Met",
+        definitionOfDoneResults: "Done",
+        requirementOutcomes: "Covered",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        verificationPassed: true,
+      };
+
+      const result = await handleCompleteMilestone(params, base);
+
+      // The call may return an error (milestone already complete) or success
+      // but in either case the SUMMARY.md must NOT be overwritten.
+      const actualContent = readFileSync(summaryPath, "utf-8");
+      assert.strictEqual(
+        actualContent,
+        originalContent,
+        "existing SUMMARY.md must not be overwritten on re-dispatch (#4598)",
+      );
+    } finally {
+      try { closeDatabase(); } catch { /* */ }
+      clearPathCache();
+      clearParseCache();
+      cleanup(base);
+    }
+  });
+
   test("deriveState completing-milestone integration", async () => {
     const { deriveState, isMilestoneComplete } = await import("../state.ts");
     const { invalidateAllCaches: invalidateAllCachesDynamic } = await import("../cache.ts");

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

@@ -125,9 +125,9 @@ console.log('\n=== complete-slice: schema v6 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v20 — memory system Phase 4 relations)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 20, 'schema version should be 20');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify slices table has full_summary_md and full_uat_md columns
   const cols = adapter.prepare("PRAGMA table_info(slices)").all();

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -109,9 +109,9 @@ console.log('\n=== complete-task: schema v5 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v20 — memory system Phase 4 relations)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 20, 'schema version should be 20');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify all 4 new tables exist
   const tables = adapter.prepare(

package/src/resources/extensions/gsd/tests/complexity-classifier.test.ts

@@ -21,9 +21,9 @@ test("tierOrdinal returns correct ordering", () => {
 
 // ─── Unit Type Classification ────────────────────────────────────────────────
 
-test("complete-slice classifies as light", () => {
+test("complete-slice classifies as standard", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake");
-  assert.equal(result.tier, "light");
+  assert.equal(result.tier, "standard");
 });
 
 test("run-uat classifies as light", () => {
@@ -145,7 +145,7 @@ test("budget pressure at 90% downgrades standard to light", () => {
   assert.equal(result.downgraded, true);
 });
 
-test("budget pressure at 90% downgrades light stays light", () => {
+test("budget pressure at 90% downgrades complete-slice standard to light", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake", 0.95);
   assert.equal(result.tier, "light");
 });

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -179,6 +179,8 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
+    preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
+    postflightPopStash: () => {},
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,