@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

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

@@ -797,9 +797,11 @@ test("stuck-loop: empty ring on a freshly constructed orchestrator advances norm
   assert.equal(result.kind, "advanced");
 });
 
-test("stuck-loop: partial fill of mixed units does not block", async (t) => {
+test("stuck-loop: distinct units making forward progress do not block", async (t) => {
+  // Healthy forward progress visits new units every advance — no key repeats,
+  // so no oscillation/repeat rule fires even once the window is full.
   let i = 0;
-  const sequence = ["M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B"];
+  const sequence = ["M001/S01/A", "M001/S01/B", "M001/S01/C", "M001/S01/D", "M001/S01/E", "M001/S01/F"];
   const f = makeFixture({
     dispatch: () => ({ action: "dispatch", unitType: "execute-task", unitId: sequence[i++ % sequence.length], prompt: "p" }),
   });
@@ -811,6 +813,43 @@ test("stuck-loop: partial fill of mixed units does not block", async (t) => {
   }
 });
 
+test("stuck-loop #1225: two-unit oscillation blocks once the window saturates", async (t) => {
+  // Reproduces the execute-task ↔ complete-slice loop: a slice gate keeps
+  // reopening the same task, so two keys alternate forever. Neither key ever
+  // saturates the window on its own, so the old matchingCount>=SIZE gate never
+  // consulted detect-stuck and the loop ran until an external kill. The window
+  // still fills, so detect-stuck's oscillation/repeat rules must now fire.
+  let i = 0;
+  const sequence: Array<{ unitType: string; unitId: string }> = [
+    { unitType: "execute-task", unitId: "M001/S01/T01" },
+    { unitType: "complete-slice", unitId: "M001/S01" },
+  ];
+  const f = makeFixture({
+    dispatch: () => {
+      const next = sequence[i++ % sequence.length];
+      return { action: "dispatch", unitType: next.unitType, unitId: next.unitId, prompt: "p" };
+    },
+  });
+  t.after(() => f.cleanup());
+
+  let blocked: Awaited<ReturnType<typeof f.orchestrator.advance>> | undefined;
+  for (let round = 0; round < STUCK_WINDOW_SIZE; round++) {
+    const result = await f.orchestrator.advance();
+    if (result.kind === "blocked") {
+      blocked = result;
+      break;
+    }
+  }
+
+  assert.ok(blocked, "oscillation must be detected once the window saturates");
+  if (!blocked || blocked.kind !== "blocked") return;
+  assert.equal(blocked.action, "stop");
+  assert.ok(
+    blocked.reason.startsWith("stuck-loop:"),
+    `expected stuck-loop verdict, got: ${blocked.reason}`,
+  );
+});
+
 test("stuck-loop: ring saturated with same unit blocks with action 'stop' and stuck-loop reason", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());

package/src/resources/extensions/gsd/tests/auto-post-unit-artifact-diagnostic.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
@@ -8,6 +8,7 @@ import {
   maybeWriteParallelResearchCostSpikeBlocker,
 } from "../auto-post-unit.ts";
 import { resolveExpectedArtifactPath } from "../auto-recovery.ts";
+import { _clearGsdRootCache, clearPathCache } from "../paths.ts";
 
 test("missing execute-task artifact includes completion contract and completion-tool hint", () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-artifact-diag-"));
@@ -56,3 +57,49 @@ test("parallel research cost spike writes durable PARALLEL-BLOCKER", () => {
     rmSync(base, { recursive: true, force: true });
   }
 });
+
+// ── #1238: symlinked project root must not produce a ../ path walk ────────────
+//
+// On WSL (and any layout where the project root is reached through a symlink),
+// artifact resolution canonicalizes through gsdRoot (realpathSync), so the
+// resolved artifact path lives under the REAL root while `basePath` is still the
+// symlink. Before the fix, relative(symlinkBase, realArtifactPath) walked up out
+// of the symlink (../../…/home/…) and the diagnostic reported that broken path as
+// "not found on disk". Normalizing basePath to its real path first keeps the
+// displayed path anchored at the real .gsd root.
+
+test("symlinked project root yields a clean .gsd-relative artifact path, not a ../ walk (#1238)", () => {
+  const realRoot = realpathSync(mkdtempSync(join(tmpdir(), "gsd-symlink-real-")));
+  const linkParent = realpathSync(mkdtempSync(join(tmpdir(), "gsd-symlink-link-")));
+  const linkRoot = join(linkParent, "project");
+  try {
+    // Content-bearing legacy milestone dir so plan-milestone resolves the
+    // canonical (realpath) ROADMAP path under realRoot/.gsd/milestones/M001/.
+    const milestoneDir = join(realRoot, ".gsd", "milestones", "M001");
+    mkdirSync(milestoneDir, { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+    // The ROADMAP intentionally does not exist — this hits the "not found on
+    // disk" branch, the exact symptom in #1238.
+    symlinkSync(realRoot, linkRoot);
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const msg = _describeArtifactVerificationFailureForTest("plan-milestone", "M001", linkRoot);
+
+    assert.match(msg, /was not found on disk after unit execution/);
+    // The displayed path must be anchored at the real .gsd root, not a broken
+    // parent-walk out of the symlinked base.
+    assert.doesNotMatch(msg, /\.\.[/\\]/, "must not contain a ../ walk out of the symlinked base");
+    assert.match(
+      msg,
+      /\.gsd[/\\]milestones[/\\]M001[/\\]M001-ROADMAP\.md/,
+      "must show the clean .gsd-relative ROADMAP path",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(linkParent, { recursive: true, force: true });
+    rmSync(realRoot, { recursive: true, force: true });
+  }
+});

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

@@ -299,6 +299,63 @@ test("refreshRecoveryDbForArtifact treats missing execute-task DB rows as fatal
   });
 });
 
+test("refreshRecoveryDbForArtifact promotes an open execute-task DB row when artifacts are verified on disk (#1204)", () => {
+  const dir = makeTmpProject();
+  insertTask({
+    milestoneId: "M001",
+    sliceId: "S01",
+    id: "T01",
+    title: "Stuck Task",
+    status: "pending",
+  });
+  const sliceDir = join(dir, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+    "# S01 Plan",
+    "",
+    "- [ ] **T01: Implement feature** `est:1h`",
+    "",
+  ].join("\n"));
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01", dir);
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete");
+  const planContent = readFileSync(join(sliceDir, "S01-PLAN.md"), "utf-8");
+  assert.ok(planContent.includes("[x] **T01:"), "plan checkbox should be re-rendered to [x]");
+  const events = readEvents(join(dir, ".gsd", "event-log.jsonl"));
+  assert.ok(
+    events.some((e) => e.cmd === "complete-task" && e.trigger_reason === "stuck-artifact-recovery"),
+    "a complete-task recovery event should be appended",
+  );
+});
+
+test("refreshRecoveryDbForArtifact still appends the recovery event when the plan checkbox sync throws after DB promotion (#1221)", () => {
+  const dir = makeTmpProject();
+  insertTask({
+    milestoneId: "M001",
+    sliceId: "S01",
+    id: "T01",
+    title: "Stuck Task",
+    status: "pending",
+  });
+  const sliceDir = join(dir, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+  // Make the expected plan path a directory so the best-effort checkbox
+  // rewrite (readFileSync) throws EISDIR after the DB row is already promoted.
+  mkdirSync(join(sliceDir, "S01-PLAN.md"), { recursive: true });
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01", dir);
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(getTask("M001", "S01", "T01")?.status, "complete");
+  const events = readEvents(join(dir, ".gsd", "event-log.jsonl"));
+  assert.ok(
+    events.some((e) => e.cmd === "complete-task" && e.trigger_reason === "stuck-artifact-recovery"),
+    "recovery event must still be appended even when the plan checkbox sync fails",
+  );
+});
+
 test("refreshRecoveryDbForArtifact closes complete-milestone DB row when artifacts exist but DB is stale (#5568)", async () => {
   const base = mkdtempSync(join(tmpdir(), "auto-recovery-complete-ms-"));
   mkdirSync(join(base, ".gsd"), { recursive: true });

package/src/resources/extensions/gsd/tests/auto-start-project-milestone-reconcile.test.ts

@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { closeDatabase, getAllMilestones, getMilestone, insertMilestone, isDbAvailable, openDatabase } from "../gsd-db.ts";
+import { _getAdapter, closeDatabase, getAllMilestones, getMilestone, insertMilestone, isDbAvailable, openDatabase } from "../gsd-db.ts";
 import { reconcileMergedMilestonesFromJournal, reconcileProjectMilestonesFromDisk } from "../auto-start.ts";
 import { emitWorktreeMerged } from "../worktree-telemetry.ts";
 
@@ -69,3 +69,31 @@ test("#5389: bootstrap reconciles PROJECT.md milestones that are missing from DB
     rmSync(base, { recursive: true, force: true });
   }
 });
+
+test("#1236: bootstrap merged-milestone reconciliation degrades to a warning instead of aborting when the DB is degraded", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-merged-reconcile-degraded-"));
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Merged Milestone", status: "active" });
+
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", conflict: false });
+
+    // Simulate a degraded DB: the connection stays "available" (isDbAvailable()
+    // remains true because the handle is non-null), but the milestones table is
+    // gone, so the reconciler's DB access throws partway through bootstrap.
+    _getAdapter()!.exec("DROP TABLE milestones");
+    assert.equal(isDbAvailable(), true);
+
+    // Regression (#1236): this reconciler was previously unguarded, so a
+    // degraded-DB failure threw and aborted the rest of `/gsd auto` bootstrap.
+    // It must now catch, warn, and return 0, matching its sibling
+    // reconcileProjectMilestonesFromDisk. Reaching the assertion proves it did
+    // not throw.
+    const closed = reconcileMergedMilestonesFromJournal(base);
+    assert.equal(closed, 0);
+  } finally {
+    if (isDbAvailable()) closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/auto-timeout-recovery-supervisor-inflight-guard.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Idle/hard timeout recovery honors the in-flight-tool guard (#1229 follow-up).
+ *
+ * `recoverTimedOutUnit` steers a still-running unit with `deliverAs: "steer"`
+ * and, before that, may swap the session model via
+ * `applySupervisorModelIfConfigured`. Swapping the model and triggering a turn
+ * while non-interactive tool calls are still open skips tool results and trips
+ * provider errors (#3512) — the same failure the soft wrap-up and continue-here
+ * timers guard against. This test pins that the idle and hard steering branches
+ * gate both the model swap and `triggerTurn` on `getInFlightToolCount() === 0`.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { recoverTimedOutUnit, type RecoveryContext } from "../auto-timeout-recovery.ts";
+import { clearGSDPreferencesCache } from "../preferences.ts";
+import {
+  markToolStart,
+  markToolEnd,
+  clearInFlightTools,
+} from "../auto-tool-tracking.ts";
+
+const SUPERVISOR_PREFS = [
+  "auto_supervisor:",
+  "  soft_timeout_minutes: 1",
+  "  idle_timeout_minutes: 100",
+  "  hard_timeout_minutes: 100",
+  "  model:",
+  "    model: supervisor-primary",
+  "    fallbacks: [supervisor-fb]",
+];
+
+interface Harness {
+  home: string;
+  base: string;
+  ctx: any;
+  pi: any;
+  rctx: RecoveryContext;
+  setModelCalls: unknown[][];
+  sendMessageCalls: unknown[][];
+}
+
+function makeHarness(): Harness {
+  const home = mkdtempSync(join(tmpdir(), "gsd-recovery-guard-home-"));
+  const base = mkdtempSync(join(tmpdir(), "gsd-recovery-guard-base-"));
+  process.env.GSD_HOME = home;
+  writeFileSync(join(home, "preferences.md"), ["---", ...SUPERVISOR_PREFS, "---", ""].join("\n"));
+  clearGSDPreferencesCache();
+
+  const setModelCalls: unknown[][] = [];
+  const sendMessageCalls: unknown[][] = [];
+
+  const ctx = {
+    ui: { notify: () => {} },
+    model: { provider: "anthropic" },
+    modelRegistry: {
+      getAvailable: () => [
+        { id: "supervisor-primary", provider: "anthropic" },
+        { id: "supervisor-fb", provider: "anthropic" },
+      ],
+    },
+  } as any;
+
+  const pi = {
+    sendMessage: (...args: unknown[]) => {
+      sendMessageCalls.push(args);
+    },
+    setModel: async (...args: unknown[]) => {
+      setModelCalls.push(args);
+      return true;
+    },
+    getThinkingLevel: () => "off",
+    setThinkingLevel: () => {},
+  } as any;
+
+  const rctx: RecoveryContext = {
+    basePath: base,
+    verbose: false,
+    currentUnitStartedAt: 1234,
+    unitRecoveryCount: new Map(),
+  };
+
+  return { home, base, ctx, pi, rctx, setModelCalls, sendMessageCalls };
+}
+
+function cleanup(h: Harness): void {
+  clearInFlightTools();
+  clearGSDPreferencesCache();
+  delete process.env.GSD_HOME;
+  rmSync(h.home, { recursive: true, force: true });
+  rmSync(h.base, { recursive: true, force: true });
+}
+
+// "discuss-project" resolves to a PROJECT.md that never exists in the temp base,
+// so recovery skips the "already on disk" shortcut and reaches the steering
+// branch with recoveryAttempts (0) < maxRecoveryAttempts.
+for (const reason of ["idle", "hard"] as const) {
+  test(`${reason} recovery skips the supervisor model swap while a tool is in flight`, async () => {
+    const h = makeHarness();
+    try {
+      markToolStart("call-1", true, "some_tool");
+
+      const outcome = await recoverTimedOutUnit(
+        h.ctx,
+        h.pi,
+        "discuss-project",
+        "P01",
+        reason,
+        h.rctx,
+      );
+
+      assert.equal(outcome, "recovered");
+      assert.equal(
+        h.setModelCalls.length,
+        0,
+        "model must NOT swap while a tool is in flight",
+      );
+      assert.equal(h.sendMessageCalls.length, 1, "steer message still sent (queued)");
+      const opts = h.sendMessageCalls[0][1] as { triggerTurn?: boolean; deliverAs?: string };
+      assert.equal(opts.triggerTurn, false, "turn is not triggered mid-tool-call");
+      assert.equal(opts.deliverAs, "steer");
+
+      markToolEnd("call-1");
+    } finally {
+      cleanup(h);
+    }
+  });
+
+  test(`${reason} recovery applies the supervisor model swap when no tools are in flight`, async () => {
+    const h = makeHarness();
+    try {
+      const outcome = await recoverTimedOutUnit(
+        h.ctx,
+        h.pi,
+        "discuss-project",
+        "P01",
+        reason,
+        h.rctx,
+      );
+
+      assert.equal(outcome, "recovered");
+      assert.equal(h.setModelCalls.length, 1, "model swaps to the supervisor model");
+      assert.deepEqual(
+        h.setModelCalls[0][0],
+        { id: "supervisor-primary", provider: "anthropic" },
+        "swaps to the configured supervisor primary",
+      );
+      assert.equal(h.sendMessageCalls.length, 1);
+      const opts = h.sendMessageCalls[0][1] as { triggerTurn?: boolean };
+      assert.equal(opts.triggerTurn, true, "turn is triggered when no tools are open");
+    } finally {
+      cleanup(h);
+    }
+  });
+}

package/src/resources/extensions/gsd/tests/codebase-generator.test.ts

@@ -697,6 +697,28 @@ test("ensureCodebaseMapFresh: does not rewrite expired metadata when fingerprint
   }
 });
 
+test("ensureCodebaseMapFresh: stays fresh when stored fileCount exceeds maxFiles", () => {
+  const base = makeTmpRepo();
+  try {
+    for (let i = 0; i < 10; i++) addFile(base, `file${i}.ts`);
+    ensureCodebaseMapFresh(base, { maxFiles: 5 }, { ttlMs: 0, force: true });
+
+    // Simulate a map written by an older version that recorded the full
+    // (untruncated) file count in its metadata rather than the capped count.
+    const original = readCodebaseMap(base);
+    assert.ok(original);
+    const fullCountContent = original.replace(/"fileCount":5\b/, '"fileCount":10');
+    writeCodebaseMap(base, fullCountContent);
+
+    const refreshed = ensureCodebaseMapFresh(base, { maxFiles: 5 }, { ttlMs: 0, force: true });
+    assert.equal(refreshed.status, "fresh");
+    // Timestamp must be preserved so the injected prompt stays byte-identical.
+    assert.equal(readCodebaseMap(base), fullCountContent);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("ensureCodebaseMapFresh: uses TTL cache before enumerating files", () => {
   const base = makeTmpRepo();
   try {

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

@@ -18,6 +18,7 @@ import { randomUUID } from "node:crypto";
 import { handleVerdict, parseValidationFile } from "../commands-verdict.ts";
 import { openDatabase, closeDatabase, _getAdapter, insertAssessment } from "../gsd-db.ts";
 import { invalidateStateCache } from "../state.ts";
+import { resolveMilestoneFile } from "../paths.ts";
 
 interface NotifyCall {
   message: string;
@@ -363,7 +364,8 @@ test("handleVerdict pass override works when validation only exists in DB", asyn
     const { ctx, calls } = makeMockCtx();
     await handleVerdict('pass --milestone M001 --rationale "reviewed and accepted"', ctx, base);
 
-    const validationPath = join(base, ".gsd", "phases", "01-m001", "01-VALIDATION.md");
+    const validationPath = resolveMilestoneFile(base, "M001", "VALIDATION");
+    assert.ok(validationPath, "DB-backed validation should be materialized to disk");
     const rewritten = readFileSync(validationPath, "utf-8");
     assert.match(rewritten, /^verdict: pass$/m, "DB-backed validation should be rewritten as pass");
     assert.match(rewritten, /reviewed and accepted/, "explicit rationale should be persisted");

package/src/resources/extensions/gsd/tests/compat-marker.test.ts

@@ -12,6 +12,7 @@ import {
   writeCompatMarker,
   normalizeForHash,
   computeProjectionSha,
+  pruneOrphanedProjectionEntries,
   EMPTY_MARKER,
   compatMarkerPath,
 } from "../compat/compat-marker.ts";
@@ -103,3 +104,87 @@ test("compatMarkerPath resolves under .gsd", () => {
   const base = makeTmpBase();
   assert.equal(compatMarkerPath(base), join(base, ".gsd", ".compat.json"));
 });
+
+test("pruneOrphanedProjectionEntries drops entries whose backing file is gone (#1257)", () => {
+  const base = makeTmpBase();
+  // Live projection: file exists on disk.
+  const liveRel = "phases/29-frontend-code-debt-cleanup/29-ROADMAP.md";
+  mkdirSync(join(base, ".gsd", "phases", "29-frontend-code-debt-cleanup"), { recursive: true });
+  writeFileSync(join(base, ".gsd", liveRel), "# M029\n", "utf-8");
+  // Phantom projection: directory was renamed, file no longer exists.
+  const ghostRel = "phases/29-new-milestone-m029/29-ROADMAP.md";
+
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-07-05T05:35:19.379Z",
+    projections: {
+      [liveRel]: { sha: "live000000000000", entities: ["M029"] },
+      [ghostRel]: { sha: "ghost00000000000", entities: ["M029"] },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const removed = pruneOrphanedProjectionEntries(base);
+  assert.equal(removed, 1);
+
+  const marker = readCompatMarker(base);
+  assert.ok(marker.projections[liveRel], "live projection must survive");
+  assert.equal(marker.projections[ghostRel], undefined, "phantom projection must be pruned");
+});
+
+test("pruneOrphanedProjectionEntries also prunes .planning projections/passthrough", () => {
+  const base = makeTmpBase();
+  mkdirSync(join(base, ".planning"), { recursive: true });
+  writeFileSync(join(base, ".planning", "ROADMAP.md"), "# roadmap\n", "utf-8");
+
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-07-05T05:35:19.379Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: {
+        "ROADMAP.md": { sha: "live000000000000", entities: [] },
+        "gone/PLAN.md": { sha: "ghost00000000000", entities: [] },
+      },
+      passthrough: {
+        "gone/PATTERNS.md": { sha: "ghost11111111111", entities: [] },
+      },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const removed = pruneOrphanedProjectionEntries(base);
+  assert.equal(removed, 2);
+
+  const marker = readCompatMarker(base);
+  assert.ok(marker.planning!.projections["ROADMAP.md"], "live planning projection must survive");
+  assert.equal(marker.planning!.projections["gone/PLAN.md"], undefined);
+  assert.equal(marker.planning!.passthrough["gone/PATTERNS.md"], undefined);
+});
+
+test("pruneOrphanedProjectionEntries is a no-op when nothing is orphaned", () => {
+  const base = makeTmpBase();
+  const rel = "phases/01-phase/01-01-PLAN.md";
+  mkdirSync(join(base, ".gsd", "phases", "01-phase"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# plan\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-07-05T05:35:19.379Z",
+    projections: { [rel]: { sha: "abc000000000000", entities: ["M001"] } },
+    piVersion: "1.4.0",
+  });
+
+  assert.equal(pruneOrphanedProjectionEntries(base), 0);
+});
+
+test("pruneOrphanedProjectionEntries returns 0 and writes nothing when marker is missing", () => {
+  const base = makeTmpBase();
+  assert.equal(pruneOrphanedProjectionEntries(base), 0);
+  const files = readdirSync(join(base, ".gsd"));
+  assert.ok(!files.includes(".compat.json"), "must not create a marker where none existed");
+});

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

@@ -422,6 +422,51 @@ console.log('\n=== complete-milestone: existing SUMMARY.md preserved (#4598) ===
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-milestone: flat-phase compatibility SUMMARY.md is not hidden
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-milestone: flat-phase legacy-named SUMMARY.md preserved (#4598) ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+  const basePath = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-flat-complete-milestone-'));
+  const phaseDir = path.join(basePath, '.gsd', 'phases', '01-test-milestone');
+  fs.mkdirSync(path.join(phaseDir, 'slices', 'S01', 'tasks'), { recursive: true });
+  seedCompletedMilestone({ basePath, validationVerdict: 'pass' });
+
+  // Flat-phase projects may still contain legacy-named compatibility files.
+  // The no-overwrite guard must preserve those richer summaries instead of
+  // generating a canonical sibling that later readers would prefer.
+  const summaryPath = path.join(phaseDir, 'M001-SUMMARY.md');
+  const canonicalSummaryPath = path.join(phaseDir, '01-SUMMARY.md');
+  const sentinel = '# M001: Pre-existing flat-phase richer summary\n\nDO NOT OVERWRITE ME\n';
+  fs.writeFileSync(summaryPath, sentinel, 'utf-8');
+
+  const result = await handleCompleteMilestone(makeValidParams(), basePath);
+  assertTrue(!('error' in result), 'completion should still succeed when flat-phase compatibility SUMMARY.md exists');
+  if (!('error' in result)) {
+    assertEq(
+      result.summaryPath,
+      fs.realpathSync(summaryPath),
+      'completion should report the preserved existing SUMMARY path',
+    );
+    assertEq(
+      fs.readFileSync(summaryPath, 'utf-8'),
+      sentinel,
+      'flat-phase compatibility SUMMARY.md must be preserved, not hidden by a canonical rewrite',
+    );
+    assertTrue(
+      !fs.existsSync(canonicalSummaryPath),
+      'completion must not create a canonical sibling over an existing compatibility summary',
+    );
+    assertEq(getMilestone('M001')!.status, 'complete', 'milestone should still be marked complete in DB');
+  }
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 
 report();

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

@@ -33,6 +33,45 @@ test("normalizeDbRows normalizes every row", () => {
   assert.deepEqual(normalizeDbRows([first, second]), [{ id: "S01" }, { id: "S02" }]);
 });
 
+test("createDbAdapter strips named-parameter key prefixes for provider compatibility", () => {
+  const received: unknown[][] = [];
+  const rawStatement = {
+    run: (...params: unknown[]) => {
+      received.push(params);
+      return { changes: 1 };
+    },
+    get: (...params: unknown[]) => {
+      received.push(params);
+      return undefined;
+    },
+    all: (...params: unknown[]) => {
+      received.push(params);
+      return [];
+    },
+  };
+  const rawDb = {
+    exec: () => {},
+    prepare: () => rawStatement,
+    close: () => {},
+  };
+  const adapter = createDbAdapter(rawDb);
+  const stmt = adapter.prepare("INSERT INTO t (version, applied_at) VALUES (:version, :applied_at)");
+
+  stmt.run({ ":version": 1, "@name": "a", "$flag": true, bare: "kept" });
+  assert.deepEqual(received.pop(), [{ version: 1, name: "a", flag: true, bare: "kept" }]);
+
+  // Non-binding params pass through untouched: positional scalars, arrays,
+  // and binary blobs must not be treated as named-binding objects.
+  const blob = new Uint8Array([1, 2, 3]);
+  stmt.get("T01", blob);
+  const passthrough = received.pop() as unknown[];
+  assert.equal(passthrough[0], "T01");
+  assert.equal(passthrough[1], blob);
+
+  stmt.all({ plain: "unchanged" });
+  assert.deepEqual(received.pop(), [{ plain: "unchanged" }]);
+});
+
 test("createDbAdapter caches prepared statements and clears cache on close", () => {
   const calls: unknown[] = [];
   const rawStatement = {