@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -24,6 +24,7 @@ import { fileURLToPath } from "node:url";
 
 import { autoSession } from "../auto-runtime-state.ts";
 import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { _resetPreferenceDiagnosticNotificationsForTests } from "../preferences-diagnostics.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SOURCE = readFileSync(
@@ -485,3 +486,82 @@ test("session_start and session_switch apply disabled model provider policy from
     "session_switch should re-read preferences for the switched project/session context",
   );
 });
+
+test("session_start surfaces malformed preference diagnostics through visible notifications", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-session-pref-diagnostics-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  const tempGsdHome = join(dir, "home");
+  mkdirSync(tempGsdHome, { recursive: true });
+
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(dir);
+  _resetPreferenceDiagnosticNotificationsForTests();
+  t.after(() => {
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    _resetPreferenceDiagnosticNotificationsForTests();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  });
+
+  writeFileSync(
+    join(dir, ".gsd", "PREFERENCES.md"),
+    [
+      "---",
+      "version: 1",
+      "models:",
+      "  validation:",
+      "    openrouter/deepseek/deepseek-v4-pro",
+      "    thinking: high",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
+  const pi = {
+    on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
+      handlers.set(event, handler);
+    },
+  } as any;
+  const ctx = {
+    hasUI: true,
+    ui: {
+      notify: (message: string, level?: string) => notifications.push({ message, level }),
+      setStatus: () => {},
+      setFooter: () => {},
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+      setWidget: () => {},
+    },
+    sessionManager: { getSessionId: () => null },
+    model: null,
+    setCompactionThresholdOverride: () => {},
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+      getProviderAuthMode: () => undefined,
+      isProviderRequestReady: () => false,
+    },
+  };
+
+  registerHooks(pi, []);
+
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler must be registered");
+  await sessionStart!({}, ctx);
+
+  const diagnostic = notifications.find((notification) =>
+    notification.message.includes("GSD project preferences error"),
+  );
+  assert.equal(diagnostic?.level, "error");
+  assert.match(diagnostic?.message ?? "", /could not be parsed/);
+  assert.match(diagnostic?.message ?? "", /line 5, column 5/);
+  assert.match(diagnostic?.message ?? "", /Preferences from this file were ignored/);
+});

package/src/resources/extensions/gsd/tests/session-switch-clears-pending-autostart.test.ts

@@ -0,0 +1,108 @@
+// gsd-pi — A fresh conversation (/clear, /new) must clear pending auto-start.
+//
+// The discuss→auto handoff entry lives in-memory and is consumed on agent_end
+// of the live interview. Once the milestone CONTEXT artifact is saved, the
+// guided-flow staleness heuristic (which requires the CONTEXT file to be
+// absent) can never fire — so a discussion interrupted by /clear left an
+// immortal entry and every subsequent /gsd dead-ended on "Discussion already
+// in progress — answer the question above" with no question above.
+//
+// session_switch with reason "new" means the conversation that contained the
+// interview is gone; the entry must go with it. Reason "resume" restores the
+// interview transcript, so the entry must survive.
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import {
+  setPendingAutoStart,
+  clearPendingAutoStart,
+  _getPendingAutoStart,
+} from "../pending-auto-start.ts";
+
+function makeProjectDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-session-switch-pas-"));
+  const milestoneDir = join(dir, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  // The post-CONTEXT state that made the entry immortal before the fix.
+  writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# M001 Context\n");
+  return dir;
+}
+
+function fakeCtx(base: string): any {
+  return {
+    cwd: base,
+    ui: {
+      notify: () => undefined,
+      setWidget: () => undefined,
+      setStatus: () => undefined,
+    },
+  };
+}
+
+function armPendingAutoStart(base: string): void {
+  setPendingAutoStart(base, {
+    basePath: base,
+    milestoneId: "M001",
+    ctx: { ui: { notify: () => undefined } } as any,
+    pi: { sendMessage: () => undefined } as any,
+  });
+}
+
+describe("session_switch clears pending auto-start on conversation reset", () => {
+  let base: string;
+  const handlers = new Map<string, Function>();
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    base = makeProjectDir();
+    handlers.clear();
+    registerHooks({ on(event: string, handler: Function) { handlers.set(event, handler); } } as any, []);
+  });
+
+  afterEach(() => {
+    clearPendingAutoStart();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  async function fireSessionSwitch(reason: "new" | "resume"): Promise<void> {
+    const handler = handlers.get("session_switch");
+    assert.ok(handler, "session_switch handler should be registered");
+    try {
+      await handler({ type: "session_switch", reason, previousSessionFile: undefined }, fakeCtx(base));
+    } catch {
+      // The handler also performs session plumbing (MCP prep, service tier
+      // sync) that may throw against the minimal fake ctx. Pending auto-start
+      // is cleared before that plumbing runs, so the assertions below remain
+      // valid either way.
+    }
+  }
+
+  it('reason "new" (/clear, /new) drops the entry even after CONTEXT was saved', async () => {
+    armPendingAutoStart(base);
+    assert.ok(_getPendingAutoStart(base), "entry should be armed");
+
+    await fireSessionSwitch("new");
+
+    assert.equal(
+      _getPendingAutoStart(base),
+      null,
+      "a fresh conversation destroyed the interview — the handoff entry must not outlive it",
+    );
+  });
+
+  it('reason "resume" keeps the entry (the interview transcript is restored)', async () => {
+    armPendingAutoStart(base);
+
+    await fireSessionSwitch("resume");
+
+    assert.ok(
+      _getPendingAutoStart(base),
+      "resuming restores the interview — the in-flight handoff must survive",
+    );
+  });
+});

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

@@ -24,10 +24,24 @@ import { join, relative } from "node:path";
 
 const gsdDir = join(process.cwd(), "src/resources/extensions/gsd");
 
-const ALLOWLIST = new Set([
-  "gsd-db.ts",
-  "unit-ownership.ts",
-]);
+// The single-writer invariant is enforced on a directory layer, not a single
+// filename. Write SQL may live only in:
+//   - db/engine.ts — connection lifecycle, schema/migrations (DDL), and the
+//     BEGIN/COMMIT transaction primitives. The shared handle every writer reads.
+//   - db/writers/**.ts — the Single Writer Layer: one cohesive write subsystem
+//     per file (hierarchy, memory, gates, escalation, reconcile, manifest,
+//     legacy-import, cascades).
+//   - gsd-db.ts — the barrel that re-exports the layer (still holds wrappers
+//     mid-migration).
+//   - unit-ownership.ts — a separate .gsd/unit-claims.db, intentionally outside.
+// db/queries.ts is explicitly NOT allowed write SQL (asserted separately below).
+function isSingleWriterFile(rel: string): boolean {
+  const norm = rel.split("\\").join("/");
+  if (norm === "gsd-db.ts" || norm === "unit-ownership.ts") return true;
+  if (norm === "db/engine.ts") return true;
+  if (norm.startsWith("db/writers/") && norm.endsWith(".ts")) return true;
+  return false;
+}
 
 /** Walk the gsd extension dir and return all .ts files outside tests/. */
 function walkTsFiles(root: string): string[] {
@@ -74,6 +88,29 @@ const PREPARE_WRITE_RE = /\.prepare\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|R
 
 // Match .exec("... INSERT|UPDATE|DELETE|REPLACE ...") or raw BEGIN/COMMIT/ROLLBACK.
 const EXEC_WRITE_RE = /\.exec\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE|BEGIN|COMMIT|ROLLBACK)\b/i;
+const DB_WORKSPACE_MECHANICS = new Set([
+  "backupDatabaseSnapshot",
+  "checkpointDatabase",
+  "closeAllDatabases",
+  "closeDatabase",
+  "closeDatabaseByWorkspace",
+  "getDbPath",
+  "getDbProvider",
+  "getDbStatus",
+  "openDatabase",
+  "openDatabaseByScope",
+  "openDatabaseByWorkspace",
+  "refreshOpenDatabaseFromDisk",
+  "vacuumDatabase",
+  "wasDbOpenAttempted",
+]);
+
+function importNames(specifierBlock: string): string[] {
+  return specifierBlock
+    .split(",")
+    .map((name) => name.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim() ?? "")
+    .filter(Boolean);
+}
 
 test("no module outside gsd-db.ts issues raw write SQL against the engine DB", () => {
   const files = walkTsFiles(gsdDir);
@@ -83,8 +120,7 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
 
   for (const abs of files) {
     const rel = relative(gsdDir, abs);
-    const base = rel.split("/").pop()!;
-    if (ALLOWLIST.has(base)) continue;
+    if (isSingleWriterFile(rel)) continue;
 
     let content: string;
     try {
@@ -131,6 +167,30 @@ test("no module outside gsd-db.ts issues raw write SQL against the engine DB", (
   }
 });
 
+test("db/queries.ts (the Query Module) is read-only — contains no write SQL", () => {
+  // The read seam is separate from the single-writer layer. queries.ts holds
+  // SELECT-only wrappers so read-only callers depend on a read seam, not the
+  // write surface. (test 1 above also forbids this, since queries.ts is not in
+  // db/writers/ — this is the explicit, positive statement of intent.)
+  const queriesPath = join(gsdDir, "db", "queries.ts");
+  const content = readFileSync(queriesPath, "utf-8");
+  const lines = content.split("\n");
+  const violations: Violation[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = PREPARE_WRITE_RE.exec(line) ?? EXEC_WRITE_RE.exec(line);
+    if (m) {
+      violations.push({ file: "db/queries.ts", line: i + 1, snippet: line.trim(), kind: m[1].toUpperCase() });
+    }
+  }
+  assert.equal(
+    violations.length,
+    0,
+    `db/queries.ts must contain no write SQL — move write wrappers to db/writers/:\n` +
+      violations.map((v) => `  db/queries.ts:${v.line} [${v.kind}] — ${v.snippet}`).join("\n"),
+  );
+});
+
 test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   // Positive assertion — fail loudly if the module layout changes so this
   // structural test can't silently become a no-op.
@@ -166,6 +226,84 @@ test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   }
 });
 
+test("DB Workspace Interface owns database open-state and maintenance calls", async () => {
+  const workspaceDb = await import("../db-workspace.js");
+
+  const expected = [
+    "backupWorkflowDatabaseSnapshot",
+    "checkpointWorkflowDatabase",
+    "closeAllWorkflowDatabases",
+    "closeWorkflowDatabase",
+    "closeWorkflowDatabaseByWorkspace",
+    "getWorkflowDatabasePath",
+    "getWorkflowDatabaseProvider",
+    "getWorkflowDatabaseStatus",
+    "isWorkflowDatabaseOpen",
+    "openExistingWorkflowDatabase",
+    "openWorkflowDatabase",
+    "openWorkflowDatabaseByScope",
+    "openWorkflowDatabaseByWorkspace",
+    "openWorkflowDatabasePath",
+    "refreshWorkflowDatabaseFromDisk",
+    "resolveProjectRootDbPath",
+    "resolveWorkflowDatabaseLocation",
+    "vacuumWorkflowDatabase",
+    "wasWorkflowDatabaseOpenAttempted",
+  ];
+
+  for (const name of expected) {
+    assert.ok(
+      typeof (workspaceDb as Record<string, unknown>)[name] === "function",
+      `db-workspace.ts must export ${name} as a function`,
+    );
+  }
+});
+
+test("production modules do not import DB open-state mechanics from gsd-db.ts", () => {
+  const files = walkTsFiles(gsdDir);
+  const violations: Violation[] = [];
+  const staticImportRe = /import\s*\{([\s\S]*?)\}\s*from\s*["'][^"']*gsd-db\.(?:js|ts)["']/g;
+  const dynamicImportRe = /(?:const|let)\s*\{([\s\S]*?)\}\s*=\s*await\s+import\(["'][^"']*gsd-db\.(?:js|ts)["']\)/g;
+
+  for (const abs of files) {
+    const rel = relative(gsdDir, abs);
+    if (rel === "gsd-db.ts" || rel === "db-workspace.ts") continue;
+
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      continue;
+    }
+
+    for (const re of [staticImportRe, dynamicImportRe]) {
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content)) !== null) {
+        const leaked = importNames(match[1] ?? "").filter((name) => DB_WORKSPACE_MECHANICS.has(name));
+        if (leaked.length === 0) continue;
+        violations.push({
+          file: rel,
+          line: content.slice(0, match.index).split("\n").length,
+          snippet: leaked.join(", "),
+          kind: "db-workspace-leak",
+        });
+      }
+    }
+  }
+
+  if (violations.length > 0) {
+    const lines = violations.map(
+      (v) => `  ${v.file}:${v.line} [${v.kind}] — ${v.snippet}`,
+    );
+    assert.fail(
+      `Found ${violations.length} DB open-state import(s) from gsd-db.ts:\n` +
+        lines.join("\n") +
+        "\n\nImport these through db-workspace.ts so gsd-db.ts stays the single-writer implementation, not the caller-facing DB Workspace Interface.",
+    );
+  }
+});
+
 test("the invariant test touches every .ts module under gsd/ (sanity check)", () => {
   const files = walkTsFiles(gsdDir);
   // Rough sanity: ensure we're not accidentally walking an empty tree
@@ -177,4 +315,3 @@ test("the invariant test touches every .ts module under gsd/ (sanity check)", ()
   assert.ok(rels.includes("memory-store.ts"), "walker must include memory-store.ts");
   assert.ok(rels.includes("workflow-manifest.ts"), "walker must include workflow-manifest.ts");
 });
-

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

@@ -74,6 +74,33 @@ describe("stale queued milestone selection (#3470)", () => {
     assert.equal(m070Entry!.status, "active", "M070 should be active in registry");
   });
 
+  test("queued milestone with roadmap projection but no DB slices stays deferred", async () => {
+    base = createFixtureBase();
+    openDatabase(":memory:");
+
+    // M068: queued shell with a stale ROADMAP projection, but no CONTEXT and no DB slices.
+    insertMilestone({ id: "M068", title: "Queued Roadmap Projection", status: "queued" });
+    writeFile(base, "milestones/M068/M068-ROADMAP.md", "# M068\n\n## Slices\n\n- [ ] **S99: Stale Slice**");
+
+    // M070: real active milestone — context, roadmap, slices, tasks
+    insertMilestone({ id: "M070", title: "Real Active", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M070", title: "Slice One", status: "active", risk: "low", depends: [] });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M070", title: "Task One", status: "pending" });
+
+    writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Real Active\n\nThis is the real milestone.");
+    writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070: Real Active\n\n## Slices\n\n- [ ] **S01: Slice One**");
+    writeFile(base, "milestones/M070/slices/S01/S01-PLAN.md", "# S01: Slice One\n\n## Tasks\n\n- [ ] **T01: Task One**");
+
+    invalidateStateCache();
+    const state = await deriveStateFromDb(base);
+
+    assert.equal(state.activeMilestone?.id, "M070", "ROADMAP-only queued milestone must not block active M070");
+
+    const m068Entry = state.registry.find((e: any) => e.id === "M068");
+    assert.ok(m068Entry, "M068 should still appear in registry");
+    assert.equal(m068Entry!.status, "pending", "M068 should stay pending without CONTEXT or DB slices");
+  });
+
   test("queued milestone WITH context file can still be selected as active", async () => {
     base = createFixtureBase();
     openDatabase(":memory:");

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

@@ -364,6 +364,7 @@ test("effective unit isolation follows degraded branch fallback", () => {
 
 test("discuss-to-auto handoff defaults to step mode unless explicitly disabled", () => {
   const guidedFlowSrc = readGsdFile("guided-flow.ts");
+  const discussionHandoffSrc = readGsdFile("discussion-handoff.ts");
   const workflowSrc = readGsdFile("commands/handlers/workflow.ts");
 
   assert.ok(
@@ -371,7 +372,7 @@ test("discuss-to-auto handoff defaults to step mode unless explicitly disabled",
     "guided-flow must not hardcode step: false on pending auto-start entries",
   );
   assert.match(
-    guidedFlowSrc,
+    discussionHandoffSrc,
     /scheduleAutoStartAfterIdle\(ctx, pi, basePath, false, \{ step: step \?\? true \}\)/,
     "checkAutoStartAfterDiscuss should default missing step flags to step mode",
   );

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -5,6 +5,8 @@ import {
   STATE_TRANSITION_MATRIX,
   findTransition,
   validateTransitionMatrix,
+  isLegalEdge,
+  IllegalPhaseTransitionError,
 } from "../state-transition-matrix.ts";
 
 test("state transition matrix covers required swarm hardening events", () => {
@@ -42,3 +44,37 @@ test("state transition matrix entries all have guard and reason codes", () => {
     assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
   }
 });
+
+// ─── ADR-030: Phase Transition Invariant ───────────────────────────────────
+
+test("isLegalEdge treats a self-edge as trivially legal", () => {
+  assert.equal(isLegalEdge("executing", "executing"), true);
+  assert.equal(isLegalEdge("planning", "planning"), true);
+});
+
+test("isLegalEdge accepts edges enumerated in the matrix", () => {
+  assert.equal(isLegalEdge("planning", "executing"), true);
+  assert.equal(isLegalEdge("executing", "summarizing"), true);
+  assert.equal(isLegalEdge("summarizing", "validating-milestone"), true);
+  assert.equal(isLegalEdge("completing-milestone", "complete"), true);
+});
+
+test("isLegalEdge honors the * wildcard rows (any -> blocked, any -> executing)", () => {
+  assert.equal(isLegalEdge("planning", "blocked"), true);
+  assert.equal(isLegalEdge("summarizing", "executing"), true);
+});
+
+test("isLegalEdge rejects an edge no matrix entry permits", () => {
+  // executing -> complete skips validation — exactly the illegal jump the
+  // invariant exists to catch.
+  assert.equal(isLegalEdge("executing", "complete"), false);
+  assert.equal(isLegalEdge("planning", "summarizing"), false);
+});
+
+test("IllegalPhaseTransitionError carries both endpoints and a descriptive message", () => {
+  const err = new IllegalPhaseTransitionError("executing", "complete");
+  assert.equal(err.from, "executing");
+  assert.equal(err.to, "complete");
+  assert.equal(err.name, "IllegalPhaseTransitionError");
+  assert.match(err.message, /executing -> complete/);
+});

package/src/resources/extensions/gsd/tests/status-guards.test.ts

@@ -9,7 +9,10 @@ import {
   isDeferredStatus,
   isInactiveStatus,
   isSkippedForDispatch,
+  toStatus,
+  RAW_CLOSED_STATUSES,
 } from '../status-guards.ts';
+import { TERMINAL_STATUS_SQL } from '../db/sql-constants.ts';
 
 test('isClosedStatus: "complete" returns true', () => {
   assert.equal(isClosedStatus('complete'), true);
@@ -95,3 +98,38 @@ test('isSkippedForDispatch does NOT skip pending/active/planned', () => {
     assert.equal(isSkippedForDispatch(s), false, `${s} should block dispatch ordering`);
   }
 });
+
+// ─── ADR-030: canonical Status vocabulary + normalization ──────────────────
+
+test('toStatus passes canonical values through unchanged', () => {
+  for (const s of ['pending', 'queued', 'active', 'parked', 'in_progress', 'blocked', 'complete', 'skipped', 'deferred']) {
+    assert.equal(toStatus(s), s, `${s} is canonical and should be returned verbatim`);
+  }
+});
+
+test('toStatus maps known aliases to canonical', () => {
+  assert.equal(toStatus('done'), 'complete');
+  assert.equal(toStatus('closed'), 'complete');
+  assert.equal(toStatus('planned'), 'pending');
+  assert.equal(toStatus('in-progress'), 'in_progress');
+});
+
+test('toStatus trims surrounding whitespace before matching', () => {
+  assert.equal(toStatus('  complete  '), 'complete');
+  assert.equal(toStatus(' done '), 'complete');
+});
+
+test('toStatus quarantines unknown values verbatim (tolerant read, no throw)', () => {
+  assert.equal(toStatus('weird-legacy-value'), 'weird-legacy-value');
+});
+
+test('RAW_CLOSED_STATUSES is the single source: every member is closed', () => {
+  for (const s of RAW_CLOSED_STATUSES) {
+    assert.equal(isClosedStatus(s), true, `${s} is in RAW_CLOSED_STATUSES so must be closed`);
+  }
+});
+
+test('TERMINAL_STATUS_SQL is derived from RAW_CLOSED_STATUSES and renders identically', () => {
+  assert.equal(TERMINAL_STATUS_SQL, "'complete', 'done', 'skipped', 'closed'");
+  assert.equal(TERMINAL_STATUS_SQL, RAW_CLOSED_STATUSES.map((s) => `'${s}'`).join(', '));
+});

package/src/resources/extensions/gsd/tests/tool-availability-audit.test.ts

@@ -141,6 +141,41 @@ for (const customType of ["gsd-discuss", "gsd-run"] as const) {
   });
 }
 
+for (const unitType of ["execute-task", "execute-task-simple", "reactive-execute"] as const) {
+  test(`${unitType}: resolves gsd_task_complete via alias gsd_complete_task when only alias is registered`, () => {
+    // Simulates the MCP transport registering gsd_complete_task (alias) instead of gsd_task_complete.
+    // adjust_tool_set strips aliases from providerCompatible, so gsd_complete_task is only present
+    // in registeredToolNames. resolveScopedToolNames must still surface it so the agent can complete tasks.
+    const base: string[] = [...FULL_REGISTERED_TOOLS];
+    const aliasOnlyRegistered = base
+      .filter((name) => name !== "gsd_task_complete")
+      .concat("gsd_complete_task");
+    const aliasStrippedActive = aliasOnlyRegistered.filter((name) => name !== "gsd_complete_task");
+
+    const result = buildMinimalAutoGsdToolSet(aliasStrippedActive, unitType, aliasOnlyRegistered);
+
+    assert.ok(
+      result.includes("gsd_task_complete") || result.includes("gsd_complete_task"),
+      `${unitType} missing gsd_task_complete / gsd_complete_task — agent cannot complete tasks`,
+    );
+  });
+
+  test(`${unitType}: alias does not duplicate canonical when both are in the active set`, () => {
+    // When both canonical and alias are registered/active, only the canonical should be surfaced.
+    const bothPresent: string[] = [...FULL_REGISTERED_TOOLS, "gsd_complete_task"];
+
+    const result = buildMinimalAutoGsdToolSet(bothPresent, unitType, bothPresent);
+
+    const hasCanonical = result.includes("gsd_task_complete");
+    const hasAlias = result.includes("gsd_complete_task");
+    assert.ok(hasCanonical || hasAlias, `${unitType} missing completion tool`);
+    assert.ok(
+      !(hasCanonical && hasAlias),
+      `${unitType} surfaces both gsd_task_complete and gsd_complete_task — alias should not duplicate canonical`,
+    );
+  });
+}
+
 test("discuss-milestone two-stage scoping matches adjust_tool_set request scope", () => {
   const activeTools = simulateDiscussAllowlistFilter(FULL_REGISTERED_TOOLS);
   const dispatchScoped = buildMinimalAutoGsdToolSet(