gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.6b9da3e

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -16,6 +16,8 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 {{inlinedContext}}
 
+{{skillActivation}}
+
 ## Validation Steps
 
 1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion.
@@ -25,47 +27,15 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 5. Determine a verdict:
    - `pass` — all criteria met, all slices delivered, no gaps
    - `needs-attention` — minor gaps that do not block completion (document them)
-   - `needs-remediation` — material gaps found; add remediation slices to the roadmap
-
-## Output
-
-Write `{{validationPath}}` with this structure:
-
-```markdown
----
-verdict: <pass|needs-attention|needs-remediation>
-remediation_round: {{remediationRound}}
----
-
-# Milestone Validation: {{milestoneId}}
+   - `needs-remediation` — material gaps found; remediation slices must be added to the roadmap
 
-## Success Criteria Checklist
-- [x] Criterion 1 — evidence: ...
-- [ ] Criterion 2 — gap: ...
+## Persist Validation
 
-## Slice Delivery Audit
-| Slice | Claimed | Delivered | Status |
-|-------|---------|-----------|--------|
-| S01   | ...     | ...       | pass   |
-
-## Cross-Slice Integration
-(any boundary mismatches)
-
-## Requirement Coverage
-(any unaddressed requirements)
-
-## Verdict Rationale
-(why this verdict was chosen)
-
-## Remediation Plan
-(only if verdict is needs-remediation — list new slices to add to the roadmap)
-```
+**Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` (if verdict is `needs-remediation`). The tool writes the validation to the DB and renders VALIDATION.md to disk.
 
 If verdict is `needs-remediation`:
-- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
-- These slices will be planned and executed before validation re-runs
-
-**You MUST write `{{validationPath}}` before finishing.**
+- After calling `gsd_validate_milestone`, use `gsd_reassess_roadmap` to add remediation slices. Pass `milestoneId`, a synthetic `completedSliceId` (e.g. "VALIDATION"), `verdict: "roadmap-adjusted"`, `assessment` text, and `sliceChanges` with the new slices in the `added` array. The tool persists the changes to the DB and re-renders ROADMAP.md.
+- These remediation slices will be planned and executed before validation re-runs.
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
 

package/src/resources/extensions/gsd/provider-error-pause.ts

@@ -19,6 +19,11 @@ export function classifyProviderError(errorMsg: string): {
   const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
   const isServerError = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i.test(errorMsg);
 
+  // Connection/process errors — transient, auto-resume after brief backoff (#2309).
+  // These indicate the process was killed, the connection was reset, or a network
+  // blip occurred. They are NOT permanent failures.
+  const isConnectionError = /terminated|connection.?reset|connection.?refused|other side closed|fetch failed|network.?(?:is\s+)?unavailable|ECONNREFUSED|ECONNRESET|EPIPE/i.test(errorMsg);
+
   // Permanent errors — never auto-resume
   const isPermanent = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i.test(errorMsg);
 
@@ -37,6 +42,10 @@ export function classifyProviderError(errorMsg: string): {
     return { isTransient: true, isRateLimit: false, suggestedDelayMs: 30_000 }; // 30s for server errors
   }
 
+  if (isConnectionError) {
+    return { isTransient: true, isRateLimit: false, suggestedDelayMs: 15_000 }; // 15s for connection errors
+  }
+
   // Unknown error — treat as permanent (user reviews)
   return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
 }

package/src/resources/extensions/gsd/repo-identity.ts

@@ -104,16 +104,17 @@ export function readRepoMeta(externalPath: string): RepoMeta | null {
  * Returns true when ALL of:
  *   1. basePath is inside a git repo (git rev-parse succeeds)
  *   2. The resolved git root is a proper ancestor of basePath
- *   3. There is no `.gsd` directory at the git root (the parent project
- *      has not been initialised with GSD)
+ *   3. There is no *project* `.gsd` directory at the git root or any
+ *      intermediate ancestor (the parent project has not been
+ *      initialised with GSD)
  *
  * When true, the caller should run `git init` at basePath so that
  * `repoIdentity()` produces a hash unique to this directory, preventing
  * cross-project state leaks (#1639).
  *
- * When the git root already has `.gsd`, the directory is a legitimate
- * subdirectory of an existing GSD project — `cd src/ && /gsd` should
- * still load the parent project's milestones.
+ * When the git root already has a project `.gsd`, the directory is a
+ * legitimate subdirectory of an existing GSD project — `cd src/ && /gsd`
+ * should still load the parent project's milestones.
  */
 export function isInheritedRepo(basePath: string): boolean {
   try {
@@ -124,12 +125,12 @@ export function isInheritedRepo(basePath: string): boolean {
 
     // The git root is a proper ancestor. Check whether it already has .gsd
     // (i.e. the parent project was initialised with GSD).
-    if (existsSync(join(root, ".gsd"))) return false;
+    if (isProjectGsd(join(root, ".gsd"))) return false;
 
     // Also walk up from basePath to the git root checking for .gsd
     let dir = normalizedBase;
     while (dir !== normalizedRoot && dir !== dirname(dir)) {
-      if (existsSync(join(dir, ".gsd"))) return false;
+      if (isProjectGsd(join(dir, ".gsd"))) return false;
       dir = dirname(dir);
     }
 
@@ -139,6 +140,44 @@ export function isInheritedRepo(basePath: string): boolean {
   }
 }
 
+/**
+ * Distinguish a *project* `.gsd` from the global `~/.gsd` state directory.
+ *
+ * A project `.gsd` is either:
+ *   - A symlink to an external state directory (normal post-migration layout)
+ *   - A legacy real directory that is NOT the global GSD home
+ *
+ * When the user's home directory is itself a git repo (e.g. dotfile managers),
+ * `~/.gsd` exists but is the global state directory — not a project `.gsd`.
+ * Treating it as a project `.gsd` would cause isInheritedRepo() to wrongly
+ * conclude that subdirectories are part of the home "project" (#2393).
+ */
+function isProjectGsd(gsdPath: string): boolean {
+  if (!existsSync(gsdPath)) return false;
+
+  try {
+    const stat = lstatSync(gsdPath);
+
+    // Symlinks are always project .gsd (created by ensureGsdSymlink).
+    if (stat.isSymbolicLink()) return true;
+
+    // For real directories, check that this isn't the global GSD home.
+    // Recompute gsdHome dynamically so env overrides (GSD_HOME) are
+    // picked up at call time, not just at module load time.
+    if (stat.isDirectory()) {
+      const currentGsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+      const normalizedGsdPath = canonicalizeExistingPath(gsdPath);
+      const normalizedGsdHome = canonicalizeExistingPath(currentGsdHome);
+      if (normalizedGsdPath === normalizedGsdHome) return false;
+      return true;
+    }
+  } catch {
+    // lstat failed — treat as no .gsd present
+  }
+
+  return false;
+}
+
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/rethink.ts

@@ -0,0 +1,154 @@
+/**
+ * GSD Rethink — Conversational project reorganization.
+ *
+ * Collects a snapshot of all milestones (status, dependencies, slice progress,
+ * queue order) and dispatches a prompt that turns Claude into a reorganization
+ * assistant. Claude can then reorder, park, unpark, discard, or add milestones
+ * through conversation.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync } from "node:fs";
+
+import { isAutoActive } from "./auto.js";
+import { deriveState } from "./state.js";
+import { gsdRoot } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
+import { loadQueueOrder, validateQueueOrder } from "./queue-order.js";
+import { isParked, getParkedReason } from "./milestone-actions.js";
+import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { buildExistingMilestonesContext } from "./guided-flow-queue.js";
+import { loadPrompt } from "./prompt-loader.js";
+
+// ─── Entry Point ──────────────────────────────────────────────────────────────
+
+export async function handleRethink(
+  _args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (isAutoActive()) {
+    ctx.ui.notify("Cannot rethink while auto-mode is active. Stop auto-mode first.", "error");
+    return;
+  }
+
+  const basePath = process.cwd();
+  const root = gsdRoot(basePath);
+  if (!existsSync(root)) {
+    ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");
+    return;
+  }
+
+  ctx.ui.notify("Building project snapshot for rethink...", "info");
+
+  const state = await deriveState(basePath);
+  const milestoneIds = findMilestoneIds(basePath);
+
+  if (milestoneIds.length === 0) {
+    ctx.ui.notify("No milestones exist yet. Nothing to rethink.", "warning");
+    return;
+  }
+
+  const queueOrder = loadQueueOrder(basePath);
+  const rethinkData = buildRethinkData(basePath, milestoneIds, state, queueOrder);
+  const existingMilestonesContext = await buildExistingMilestonesContext(basePath, milestoneIds, state);
+
+  const content = loadPrompt("rethink", {
+    rethinkData,
+    existingMilestonesContext,
+  });
+
+  pi.sendMessage(
+    { customType: "gsd-rethink", content, display: false },
+    { triggerTurn: true },
+  );
+}
+
+// ─── Data Builder ─────────────────────────────────────────────────────────────
+
+function buildRethinkData(
+  basePath: string,
+  milestoneIds: string[],
+  state: Awaited<ReturnType<typeof deriveState>>,
+  queueOrder: string[] | null,
+): string {
+  const lines: string[] = [];
+  const dbAvailable = isDbAvailable();
+
+  // ── Summary stats ───────────────────────────────────────────────────
+  const counts = { complete: 0, active: 0, pending: 0, parked: 0 };
+  for (const entry of state.registry) {
+    if (entry.status in counts) counts[entry.status as keyof typeof counts]++;
+  }
+
+  lines.push("### Summary");
+  lines.push(`${counts.complete} complete, ${counts.active} active, ${counts.pending} pending, ${counts.parked} parked — ${milestoneIds.length} total`);
+  lines.push(`Queue order source: ${queueOrder ? "explicit QUEUE-ORDER.json" : "default numeric (by ID)"}`);
+  if (state.activeMilestone) {
+    lines.push(`Active milestone: ${state.activeMilestone}`);
+  }
+  lines.push("");
+
+  // ── Milestone table ─────────────────────────────────────────────────
+  lines.push("### Execution Order");
+  lines.push("");
+  lines.push("| # | ID | Title | Status | Dependencies | Slices |");
+  lines.push("|---|-----|-------|--------|--------------|--------|");
+
+  for (let i = 0; i < milestoneIds.length; i++) {
+    const mid = milestoneIds[i];
+    const entry = state.registry.find(m => m.id === mid);
+    const title = entry?.title ?? mid;
+    const status = entry?.status ?? "unknown";
+    const deps = entry?.dependsOn?.length ? entry.dependsOn.join(", ") : "—";
+
+    let sliceInfo = "—";
+    if (dbAvailable && status !== "complete") {
+      const slices = getMilestoneSlices(mid);
+      if (slices.length > 0) {
+        const done = slices.filter(s => s.status === "complete").length;
+        sliceInfo = `${done}/${slices.length} complete`;
+      }
+    }
+
+    // Add parked reason if applicable
+    let statusDisplay = status;
+    if (status === "parked") {
+      const reason = getParkedReason(basePath, mid);
+      if (reason) statusDisplay = `parked (${reason})`;
+    }
+
+    lines.push(`| ${i + 1} | ${mid} | ${title} | ${statusDisplay} | ${deps} | ${sliceInfo} |`);
+  }
+
+  // ── Dependency validation ───────────────────────────────────────────
+  const pendingIds = milestoneIds.filter(mid => {
+    const entry = state.registry.find(m => m.id === mid);
+    return entry?.status !== "complete";
+  });
+
+  const completedIds = new Set(
+    state.registry.filter(m => m.status === "complete").map(m => m.id),
+  );
+
+  const depsMap = new Map<string, string[]>();
+  for (const entry of state.registry) {
+    if (entry.dependsOn?.length) {
+      depsMap.set(entry.id, entry.dependsOn);
+    }
+  }
+
+  if (pendingIds.length > 0 && depsMap.size > 0) {
+    const validation = validateQueueOrder(pendingIds, depsMap, completedIds);
+
+    if (validation.violations.length > 0) {
+      lines.push("");
+      lines.push("### Dependency Issues");
+      for (const v of validation.violations) {
+        lines.push(`- **${v.type}**: ${v.message}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/resources/extensions/gsd/state.ts

@@ -48,6 +48,7 @@ import {
   getSliceTasks,
   getReplanHistory,
   getSlice,
+  insertMilestone,
   type MilestoneRow,
   type SliceRow,
   type TaskRow,
@@ -257,7 +258,46 @@ function isStatusDone(status: string): boolean {
 export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   const requirements = parseRequirementCounts(await loadFile(resolveGsdRootFile(basePath, "REQUIREMENTS")));
 
-  const allMilestones = getAllMilestones();
+  let allMilestones = getAllMilestones();
+
+  // Incremental disk→DB sync: milestone directories created outside the DB
+  // write path (via /gsd queue, manual mkdir, or complete-milestone writing the
+  // next CONTEXT.md) are never inserted by the initial migration guard in
+  // auto-start.ts because that guard only runs when gsd.db doesn't exist yet.
+  // Reconcile here so deriveStateFromDb never silently misses queued milestones.
+  // insertMilestone uses INSERT OR IGNORE, so this is safe to call every time.
+  const dbIdSet = new Set(allMilestones.map(m => m.id));
+  const diskIds = findMilestoneIds(basePath);
+  let synced = false;
+  for (const diskId of diskIds) {
+    if (!dbIdSet.has(diskId) && !isGhostMilestone(basePath, diskId)) {
+      insertMilestone({ id: diskId, status: 'active' });
+      synced = true;
+    }
+  }
+  if (synced) allMilestones = getAllMilestones();
+
+  // Reconcile: discover milestones that exist on disk but are missing from
+  // the DB. This happens when milestones were created before the DB migration
+  // or were manually added to the filesystem. Without this, disk-only
+  // milestones are invisible after migration (#2416).
+  const dbMilestoneIds = new Set(allMilestones.map(m => m.id));
+  const diskMilestoneIds = findMilestoneIds(basePath);
+  for (const diskId of diskMilestoneIds) {
+    if (!dbMilestoneIds.has(diskId)) {
+      // Synthesize a minimal MilestoneRow for the disk-only milestone.
+      // Title and status will be resolved from disk files in the loop below.
+      allMilestones.push({
+        id: diskId,
+        title: diskId,
+        status: 'active',
+        depends_on: [] as string[],
+        created_at: new Date().toISOString(),
+      } as MilestoneRow);
+    }
+  }
+  // Re-sort so milestones are in canonical order after injection
+  allMilestones.sort((a, b) => milestoneIdSort(a.id, b.id));
 
   // Parallel worker isolation: when locked, filter to just the locked milestone
   const milestoneLock = process.env.GSD_MILESTONE_LOCK;

package/src/resources/extensions/gsd/tests/auto-pr-bugs.test.ts

@@ -0,0 +1,88 @@
+/**
+ * auto-pr-bugs.test.ts — Regression tests for #2302.
+ *
+ * Three interacting bugs prevented auto_pr from ever creating a PR:
+ * 1. auto_pr was gated on `pushed` (which requires auto_push)
+ * 2. Milestone branch was not pushed to remote before PR creation
+ * 3. createDraftPR in git-service.ts lacked --head/--base parameters
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Bug 1: auto_pr should not depend on auto_push / pushed flag ────────────
+
+const autoWorktreeSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+const autoWorktreeSrc = readFileSync(autoWorktreeSrcPath, "utf-8");
+
+test("#2302 bug 1: auto_pr condition should not require pushed flag", () => {
+  // Find the auto_pr block in mergeMilestoneToMain
+  const autoPrIdx = autoWorktreeSrc.indexOf("auto_pr");
+  assert.ok(autoPrIdx !== -1, "auto_pr reference exists in auto-worktree.ts");
+
+  // Get context around the auto_pr check
+  const lineStart = autoWorktreeSrc.lastIndexOf("\n", autoPrIdx) + 1;
+  const lineEnd = autoWorktreeSrc.indexOf("\n", autoPrIdx);
+  const autoPrLine = autoWorktreeSrc.slice(lineStart, lineEnd);
+
+  // The condition should NOT include `&& pushed`
+  assert.ok(
+    !autoPrLine.includes("&& pushed"),
+    "auto_pr condition should not be gated on pushed flag (auto_push dependency)",
+  );
+});
+
+// ─── Bug 2: phases.ts should not duplicate PR creation ──────────────────────
+
+const phasesSrcPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const phasesSrc = readFileSync(phasesSrcPath, "utf-8");
+
+test("#2302 bug 2: phases.ts should not call createDraftPR (handled by mergeMilestoneToMain)", () => {
+  // After fix, phases.ts should not import or call createDraftPR because
+  // PR creation is handled inside mergeMilestoneToMain in auto-worktree.ts
+  const createDraftPRCalls = phasesSrc.match(/createDraftPR\(/g) || [];
+
+  assert.equal(
+    createDraftPRCalls.length,
+    0,
+    "phases.ts should not call createDraftPR — it's handled by mergeMilestoneToMain",
+  );
+});
+
+// ─── Bug 3: createDraftPR should accept head and base branch parameters ─────
+
+const gitServiceSrcPath = join(import.meta.dirname, "..", "git-service.ts");
+const gitServiceSrc = readFileSync(gitServiceSrcPath, "utf-8");
+
+test("#2302 bug 3: createDraftPR should accept head and base branch parameters", () => {
+  // Find the createDraftPR function signature
+  const fnIdx = gitServiceSrc.indexOf("function createDraftPR");
+  assert.ok(fnIdx !== -1, "createDraftPR function exists");
+
+  // Get the function signature (up to the closing paren)
+  const sigEnd = gitServiceSrc.indexOf(")", fnIdx);
+  const signature = gitServiceSrc.slice(fnIdx, sigEnd);
+
+  // Should have head and base parameters
+  assert.ok(
+    signature.includes("head") || signature.includes("branch"),
+    "createDraftPR should accept a head/branch parameter",
+  );
+});
+
+test("#2302 bug 3: createDraftPR should pass --head and --base to gh pr create", () => {
+  const fnIdx = gitServiceSrc.indexOf("function createDraftPR");
+  const fnEnd = gitServiceSrc.indexOf("\n}", fnIdx);
+  const fnBody = gitServiceSrc.slice(fnIdx, fnEnd);
+
+  assert.ok(
+    fnBody.includes("--head"),
+    "createDraftPR should pass --head to gh pr create",
+  );
+  assert.ok(
+    fnBody.includes("--base"),
+    "createDraftPR should pass --base to gh pr create",
+  );
+});

package/src/resources/extensions/gsd/tests/completed-units-metrics-sync.test.ts

@@ -0,0 +1,114 @@
+/**
+ * completed-units-metrics-sync.test.ts — Regression tests for #2313.
+ *
+ * 1. completed-units.json should be archived (not wiped) on milestone transition
+ * 2. metrics.json should be in the worktree → project root sync file list
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, existsSync, cpSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ─── Bug 1: completed-units.json should be archived, not wiped ─────────────
+
+const phasesSrcPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const phasesSrc = readFileSync(phasesSrcPath, "utf-8");
+
+test("#2313: completed-units.json should not be blindly wiped to [] on milestone transition", () => {
+  // The milestone transition block should NOT write an empty array to completed-units.json
+  // without first archiving the existing data. Look for the archive/rename pattern.
+  const transitionIdx = phasesSrc.indexOf("Milestone transition");
+  assert.ok(transitionIdx !== -1, "Milestone transition section exists");
+
+  // Find the completed-units handling block
+  const completedUnitsIdx = phasesSrc.indexOf("completed-units", transitionIdx);
+  assert.ok(completedUnitsIdx !== -1, "completed-units handling exists in transition");
+
+  // Get a window around the completed-units handling (1200 chars to
+  // accommodate CRLF line endings on Windows which inflate byte offsets).
+  const windowStart = Math.max(0, completedUnitsIdx - 300);
+  const windowEnd = Math.min(phasesSrc.length, completedUnitsIdx + 900);
+  const window = phasesSrc.slice(windowStart, windowEnd).toLowerCase();
+
+  // Should archive/rename the old file before resetting
+  const hasArchive = window.includes("archive") ||
+    window.includes("rename") ||
+    window.includes("cpsync") ||
+    window.includes("safecopy") ||
+    window.includes("completed-units-");
+
+  assert.ok(
+    hasArchive,
+    "completed-units.json should be archived before reset during milestone transition",
+  );
+});
+
+// ─── Bug 2: metrics.json should be in the sync file lists ──────────────────
+
+test("#2313: syncStateToProjectRoot should sync metrics.json", () => {
+  const syncSrcPath = join(import.meta.dirname, "..", "auto-worktree-sync.ts");
+  const syncSrc = readFileSync(syncSrcPath, "utf-8");
+
+  // syncStateToProjectRoot should copy metrics.json from worktree to project root
+  assert.ok(
+    syncSrc.includes("metrics.json"),
+    "auto-worktree-sync.ts should reference metrics.json for sync",
+  );
+});
+
+test("#2313: syncWorktreeStateBack should include metrics.json in root files list", () => {
+  const autoWorktreeSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+  const autoWorktreeSrc = readFileSync(autoWorktreeSrcPath, "utf-8");
+
+  // Find the rootFiles array in syncWorktreeStateBack
+  const syncBackIdx = autoWorktreeSrc.indexOf("syncWorktreeStateBack");
+  assert.ok(syncBackIdx !== -1, "syncWorktreeStateBack exists");
+
+  const rootFilesIdx = autoWorktreeSrc.indexOf("rootFiles", syncBackIdx);
+  assert.ok(rootFilesIdx !== -1, "rootFiles list exists in syncWorktreeStateBack");
+
+  // Get the rootFiles array content
+  const arrayStart = autoWorktreeSrc.indexOf("[", rootFilesIdx);
+  const arrayEnd = autoWorktreeSrc.indexOf("]", arrayStart);
+  const rootFilesBlock = autoWorktreeSrc.slice(arrayStart, arrayEnd);
+
+  assert.ok(
+    rootFilesBlock.includes("metrics.json"),
+    "metrics.json should be in syncWorktreeStateBack rootFiles list",
+  );
+});
+
+// ─── Functional test: completed-units archive ────────────────────────────────
+
+test("#2313: functional — completed-units archive creates milestone-specific file", () => {
+  const tmpBase = mkdtempSync(join(tmpdir(), "gsd-completed-units-"));
+  const gsdDir = join(tmpBase, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  // Simulate existing completed-units.json with data
+  const existing = [
+    { type: "task", id: "T01" },
+    { type: "slice", id: "S01" },
+  ];
+  const completedKeysPath = join(gsdDir, "completed-units.json");
+  writeFileSync(completedKeysPath, JSON.stringify(existing, null, 2));
+
+  // Simulate the archive behavior: copy to milestone-specific file
+  const milestoneId = "M001";
+  const archivePath = join(gsdDir, `completed-units-${milestoneId}.json`);
+  cpSync(completedKeysPath, archivePath);
+
+  // Reset the main file
+  writeFileSync(completedKeysPath, JSON.stringify([], null, 2));
+
+  // Verify archive exists with original data
+  assert.ok(existsSync(archivePath), "archive file should exist");
+  const archived = JSON.parse(readFileSync(archivePath, "utf-8"));
+  assert.deepEqual(archived, existing, "archived data should match original");
+
+  // Verify main file is reset
+  const current = JSON.parse(readFileSync(completedKeysPath, "utf-8"));
+  assert.deepEqual(current, [], "current completed-units should be empty after transition");
+});

package/src/resources/extensions/gsd/tests/db-writer.test.ts

@@ -483,6 +483,85 @@ describe('db-writer', () => {
     }
   });
 
+  test('saveArtifactToDb — shrinkage guard preserves larger existing file', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      const fullContent = '# Full Research\n\n' + 'x'.repeat(20000) + '\n';
+      const abbreviatedContent = '# Summary\n\nShort version.\n';
+
+      // Pre-create the file with full content (simulating a prior `write` tool call)
+      const relPath = 'milestones/M001/M001-RESEARCH.md';
+      const filePath = path.join(tmpDir, '.gsd', relPath);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, fullContent);
+
+      // Call saveArtifactToDb with abbreviated content — should trigger shrinkage guard
+      await saveArtifactToDb({
+        path: relPath,
+        artifact_type: 'RESEARCH',
+        content: abbreviatedContent,
+        milestone_id: 'M001',
+      }, tmpDir);
+
+      // Disk file should be preserved (not overwritten)
+      assert.deepStrictEqual(
+        fs.readFileSync(filePath, 'utf-8'),
+        fullContent,
+        'disk file preserved — shrinkage guard prevented overwrite',
+      );
+
+      // DB should contain the full disk content, not the abbreviated content
+      const adapter = _getAdapter();
+      const row = adapter!
+        .prepare('SELECT full_content FROM artifacts WHERE path = ?')
+        .get(relPath);
+      assert.deepStrictEqual(
+        row!['full_content'],
+        fullContent,
+        'DB stores the richer disk content instead of abbreviated content',
+      );
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
+  test('saveArtifactToDb — allows overwrite when new content is similar size', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      const oldContent = '# Summary v1\n\nOriginal content here.\n';
+      const newContent = '# Summary v2\n\nUpdated content here with more details.\n';
+
+      const relPath = 'milestones/M001/M001-SUMMARY.md';
+      const filePath = path.join(tmpDir, '.gsd', relPath);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, oldContent);
+
+      await saveArtifactToDb({
+        path: relPath,
+        artifact_type: 'SUMMARY',
+        content: newContent,
+        milestone_id: 'M001',
+      }, tmpDir);
+
+      // Disk file should be updated (new content is >=50% of old size)
+      assert.deepStrictEqual(
+        fs.readFileSync(filePath, 'utf-8'),
+        newContent,
+        'disk file updated when new content is similar size',
+      );
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // Full Round-Trip: DB → Markdown → Parse → Compare
   // ═══════════════════════════════════════════════════════════════════════════