gsd-pi 2.63.0 → 2.64.0-dev.05b8a94

package/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts

@@ -0,0 +1,349 @@
+/**
+ * tool-param-optionality — Verifies that enrichment/metadata parameters on
+ * planning and completion tools are optional, not required.
+ *
+ * Models with limited tool-calling capability (e.g. kimi-k2.5, glm-5-turbo)
+ * cannot reliably populate 20+ top-level parameters in a single tool call.
+ * This test ensures that only the core identification and content parameters
+ * are required, while enrichment arrays (patterns, requirements, files, etc.)
+ * are optional — so any model can call the tool successfully.
+ *
+ * See: https://github.com/gsd-build/gsd-2/issues/2771
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { registerDbTools } from "../bootstrap/db-tools.ts";
+import { Value } from "@sinclair/typebox/value";
+
+// ─── Mock PI ──────────────────────────────────────────────────────────────────
+
+function makeMockPi() {
+  const tools: any[] = [];
+  return {
+    registerTool: (tool: any) => tools.push(tool),
+    tools,
+  } as any;
+}
+
+const pi = makeMockPi();
+registerDbTools(pi);
+
+function getTool(name: string) {
+  return pi.tools.find((t: any) => t.name === name);
+}
+
+// ─── Helper: count required top-level properties ─────────────────────────────
+
+function getRequiredProps(tool: any): string[] {
+  const schema = tool.parameters;
+  return schema.required ?? [];
+}
+
+function getOptionalProps(tool: any): string[] {
+  const schema = tool.parameters;
+  const allProps = Object.keys(schema.properties ?? {});
+  const required = new Set(schema.required ?? []);
+  return allProps.filter((p: string) => !required.has(p));
+}
+
+// ─── gsd_slice_complete: enrichment arrays must be optional ──────────────────
+
+test("gsd_slice_complete — enrichment arrays are optional", () => {
+  const tool = getTool("gsd_slice_complete");
+  assert.ok(tool, "gsd_slice_complete must be registered");
+
+  const required = new Set(getRequiredProps(tool));
+
+  // Core identification and content fields MUST be required
+  const coreRequired = [
+    "sliceId",
+    "milestoneId",
+    "sliceTitle",
+    "oneLiner",
+    "narrative",
+    "verification",
+    "uatContent",
+  ];
+  for (const field of coreRequired) {
+    assert.ok(required.has(field), `core field "${field}" must be required`);
+  }
+
+  // Enrichment/metadata arrays MUST be optional
+  const enrichmentFields = [
+    "keyFiles",
+    "keyDecisions",
+    "patternsEstablished",
+    "observabilitySurfaces",
+    "provides",
+    "requirementsSurfaced",
+    "drillDownPaths",
+    "affects",
+    "requirementsAdvanced",
+    "requirementsValidated",
+    "requirementsInvalidated",
+    "filesModified",
+    "requires",
+    "deviations",
+    "knownLimitations",
+    "followUps",
+  ];
+  for (const field of enrichmentFields) {
+    assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`);
+  }
+});
+
+test("gsd_slice_complete — validates with only core params", () => {
+  const tool = getTool("gsd_slice_complete");
+  assert.ok(tool, "gsd_slice_complete must be registered");
+
+  const minimalParams = {
+    sliceId: "S01",
+    milestoneId: "M001",
+    sliceTitle: "Test slice",
+    oneLiner: "Did the thing",
+    narrative: "We did it step by step.",
+    verification: "Tests pass.",
+    uatContent: "## UAT\n- [x] Works",
+  };
+
+  // Should pass schema validation with only core params
+  const errors = [...Value.Errors(tool.parameters, minimalParams)];
+  assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`);
+});
+
+// ─── gsd_plan_milestone: enrichment arrays must be optional ──────────────────
+
+test("gsd_plan_milestone — enrichment arrays are optional", () => {
+  const tool = getTool("gsd_plan_milestone");
+  assert.ok(tool, "gsd_plan_milestone must be registered");
+
+  const required = new Set(getRequiredProps(tool));
+
+  // Core fields
+  const coreRequired = ["milestoneId", "title", "vision", "slices"];
+  for (const field of coreRequired) {
+    assert.ok(required.has(field), `core field "${field}" must be required`);
+  }
+
+  // Enrichment fields must be optional
+  const enrichmentFields = [
+    "successCriteria",
+    "keyRisks",
+    "proofStrategy",
+    "verificationContract",
+    "verificationIntegration",
+    "verificationOperational",
+    "verificationUat",
+    "definitionOfDone",
+    "requirementCoverage",
+    "boundaryMapMarkdown",
+  ];
+  for (const field of enrichmentFields) {
+    assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`);
+  }
+});
+
+test("gsd_plan_milestone — validates with only core params", () => {
+  const tool = getTool("gsd_plan_milestone");
+  assert.ok(tool, "gsd_plan_milestone must be registered");
+
+  const minimalParams = {
+    milestoneId: "M001",
+    title: "Test milestone",
+    vision: "Build the thing.",
+    slices: [
+      {
+        sliceId: "S01",
+        title: "First slice",
+        risk: "Low",
+        depends: [],
+        demo: "After this, X works",
+        goal: "Set up X",
+        successCriteria: "X is set up",
+        proofLevel: "unit-tests",
+        integrationClosure: "N/A",
+        observabilityImpact: "None",
+      },
+    ],
+  };
+
+  const errors = [...Value.Errors(tool.parameters, minimalParams)];
+  assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`);
+});
+
+// ─── gsd_task_complete: enrichment arrays must be optional ───────────────────
+
+test("gsd_task_complete — enrichment arrays are optional", () => {
+  const tool = getTool("gsd_task_complete");
+  assert.ok(tool, "gsd_task_complete must be registered");
+
+  const required = new Set(getRequiredProps(tool));
+
+  // Core fields
+  const coreRequired = [
+    "taskId",
+    "sliceId",
+    "milestoneId",
+    "oneLiner",
+    "narrative",
+    "verification",
+  ];
+  for (const field of coreRequired) {
+    assert.ok(required.has(field), `core field "${field}" must be required`);
+  }
+
+  // Enrichment fields must be optional
+  const enrichmentFields = [
+    "keyFiles",
+    "keyDecisions",
+    "deviations",
+    "knownIssues",
+    "blockerDiscovered",
+    "verificationEvidence",
+  ];
+  for (const field of enrichmentFields) {
+    assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`);
+  }
+});
+
+test("gsd_task_complete — validates with only core params", () => {
+  const tool = getTool("gsd_task_complete");
+  assert.ok(tool, "gsd_task_complete must be registered");
+
+  const minimalParams = {
+    taskId: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    oneLiner: "Implemented the feature",
+    narrative: "Created the module and wired it up.",
+    verification: "npm test passes.",
+  };
+
+  const errors = [...Value.Errors(tool.parameters, minimalParams)];
+  assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`);
+});
+
+// ─── gsd_complete_milestone: enrichment arrays must be optional ──────────────
+
+test("gsd_complete_milestone — enrichment arrays are optional", () => {
+  const tool = getTool("gsd_complete_milestone");
+  assert.ok(tool, "gsd_complete_milestone must be registered");
+
+  const required = new Set(getRequiredProps(tool));
+
+  // Core fields
+  const coreRequired = [
+    "milestoneId",
+    "title",
+    "oneLiner",
+    "narrative",
+    "verificationPassed",
+  ];
+  for (const field of coreRequired) {
+    assert.ok(required.has(field), `core field "${field}" must be required`);
+  }
+
+  // Enrichment fields must be optional
+  const enrichmentFields = [
+    "successCriteriaResults",
+    "definitionOfDoneResults",
+    "requirementOutcomes",
+    "keyDecisions",
+    "keyFiles",
+    "lessonsLearned",
+  ];
+  for (const field of enrichmentFields) {
+    assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`);
+  }
+});
+
+test("gsd_complete_milestone — validates with only core params", () => {
+  const tool = getTool("gsd_complete_milestone");
+  assert.ok(tool, "gsd_complete_milestone must be registered");
+
+  const minimalParams = {
+    milestoneId: "M001",
+    title: "Test milestone",
+    oneLiner: "Finished it.",
+    narrative: "All work completed.",
+    verificationPassed: true,
+  };
+
+  const errors = [...Value.Errors(tool.parameters, minimalParams)];
+  assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`);
+});
+
+// ─── gsd_plan_slice: enrichment fields must be optional ──────────────────────
+
+test("gsd_plan_slice — enrichment fields are optional", () => {
+  const tool = getTool("gsd_plan_slice");
+  assert.ok(tool, "gsd_plan_slice must be registered");
+
+  const required = new Set(getRequiredProps(tool));
+
+  // Core fields
+  const coreRequired = ["milestoneId", "sliceId", "goal", "tasks"];
+  for (const field of coreRequired) {
+    assert.ok(required.has(field), `core field "${field}" must be required`);
+  }
+
+  // Enrichment fields
+  const enrichmentFields = [
+    "successCriteria",
+    "proofLevel",
+    "integrationClosure",
+    "observabilityImpact",
+  ];
+  for (const field of enrichmentFields) {
+    assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`);
+  }
+});
+
+test("gsd_plan_slice — validates with only core params", () => {
+  const tool = getTool("gsd_plan_slice");
+  assert.ok(tool, "gsd_plan_slice must be registered");
+
+  const minimalParams = {
+    milestoneId: "M001",
+    sliceId: "S01",
+    goal: "Implement feature X",
+    tasks: [
+      {
+        taskId: "T01",
+        title: "Build X",
+        description: "Build the thing",
+        estimate: "2h",
+        files: ["src/x.ts"],
+        verify: "npm test",
+        inputs: [],
+        expectedOutput: ["src/x.ts"],
+      },
+    ],
+  };
+
+  const errors = [...Value.Errors(tool.parameters, minimalParams)];
+  assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`);
+});
+
+// ─── Required param count ceiling ────────────────────────────────────────────
+
+test("no planning/completion tool requires more than 10 top-level params", () => {
+  const heavyTools = [
+    "gsd_slice_complete",
+    "gsd_plan_milestone",
+    "gsd_task_complete",
+    "gsd_complete_milestone",
+    "gsd_plan_slice",
+  ];
+
+  for (const name of heavyTools) {
+    const tool = getTool(name);
+    assert.ok(tool, `${name} must be registered`);
+    const required = getRequiredProps(tool);
+    assert.ok(
+      required.length <= 10,
+      `${name} has ${required.length} required params (max 10) — required: ${required.join(", ")}`,
+    );
+  }
+});

package/src/resources/extensions/gsd/tests/unstructured-continue-context-injection.test.ts

@@ -0,0 +1,163 @@
+// GSD-2 — Regression test for #3615: unstructured "continue" must inject task context
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+/**
+ * Bug #3615: When a user types "continue" (or any bare text) to resume
+ * an in-progress session, buildGuidedExecuteContextInjection() only
+ * matched two hardcoded regex patterns (auto-dispatch and guided-resume).
+ * The function returned null for any other input, so no task context was
+ * injected — causing the agent to rebuild everything from scratch and
+ * burn ~86k tokens.
+ *
+ * This test verifies:
+ *   1. Structural: the fallback exists with phase + intent guards
+ *   2. Behavioral: RESUME_INTENT_PATTERNS matches expected prompts and
+ *      rejects non-resume prompts (control, help, diagnostic, etc.)
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const systemContextSource = readFileSync(
+  join(__dirname, "..", "bootstrap", "system-context.ts"),
+  "utf-8",
+);
+
+// ── Structural tests ────────────────────────────────────────────────
+
+describe("#3615 — structural: fallback exists with correct guards", () => {
+  const fnStart = systemContextSource.indexOf("async function buildGuidedExecuteContextInjection(");
+  assert.ok(fnStart >= 0, "should find buildGuidedExecuteContextInjection");
+  const fnEnd = systemContextSource.indexOf("\nasync function ", fnStart + 1);
+  const fnBody = fnEnd >= 0
+    ? systemContextSource.slice(fnStart, fnEnd)
+    : systemContextSource.slice(fnStart);
+
+  test("has a deriveState fallback after the two regex branches", () => {
+    const deriveStateCalls = fnBody.match(/deriveState\(basePath\)/g);
+    assert.ok(
+      deriveStateCalls && deriveStateCalls.length >= 2,
+      `expected >=2 deriveState(basePath) calls, got ${deriveStateCalls?.length ?? 0}`,
+    );
+  });
+
+  test("fallback is phase-gated to executing only", () => {
+    const afterFallback = fnBody.indexOf("// Fallback:");
+    assert.ok(afterFallback >= 0, "should have a fallback comment");
+    const fallbackSection = fnBody.slice(afterFallback);
+    assert.ok(
+      fallbackSection.includes('state.phase === "executing"'),
+      'fallback must be gated on state.phase === "executing"',
+    );
+  });
+
+  test("fallback is intent-gated via RESUME_INTENT_PATTERNS", () => {
+    const afterFallback = fnBody.indexOf("// Fallback:");
+    const fallbackSection = fnBody.slice(afterFallback);
+    assert.ok(
+      fallbackSection.includes("RESUME_INTENT_PATTERNS"),
+      "fallback must check RESUME_INTENT_PATTERNS before deriveState",
+    );
+  });
+
+  test("fallback calls buildTaskExecutionContextInjection with derived state", () => {
+    const afterFallback = fnBody.indexOf("// Fallback:");
+    const fallbackSection = fnBody.slice(afterFallback);
+    assert.ok(
+      fallbackSection.includes("buildTaskExecutionContextInjection") &&
+      fallbackSection.includes("state.activeMilestone.id") &&
+      fallbackSection.includes("state.activeSlice.id") &&
+      fallbackSection.includes("state.activeTask.id"),
+      "fallback must call buildTaskExecutionContextInjection with state-derived IDs",
+    );
+  });
+
+  test("only one return null at the end", () => {
+    const returnNulls = fnBody.match(/return null;/g);
+    assert.ok(
+      returnNulls && returnNulls.length === 1,
+      `expected exactly 1 'return null' (at end after fallback), got ${returnNulls?.length ?? 0}`,
+    );
+  });
+});
+
+// ── Behavioral tests: RESUME_INTENT_PATTERNS ────────────────────────
+
+describe("#3615 — behavioral: RESUME_INTENT_PATTERNS matches resume prompts", () => {
+  // Extract the regex from source so the test stays in sync
+  const patternMatch = systemContextSource.match(/const RESUME_INTENT_PATTERNS\s*=\s*\/(.+)\/;/);
+  assert.ok(patternMatch, "should find RESUME_INTENT_PATTERNS definition");
+  const pattern = new RegExp(patternMatch[1]);
+
+  // Helper: normalize prompt the same way the production code does
+  const normalize = (s: string) => s.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+
+  const shouldMatch = [
+    "continue",
+    "Continue",
+    "CONTINUE",
+    "continue.",
+    "continue!",
+    "resume",
+    "ok",
+    "OK",
+    "Ok!",
+    "go",
+    "go ahead",
+    "Go ahead.",
+    "proceed",
+    "keep going",
+    "carry on",
+    "next",
+    "yes",
+    "yeah",
+    "yep",
+    "sure",
+    "do it",
+    "let's go",
+    "pick up where you left off",
+    "  continue  ",  // whitespace padded
+  ];
+
+  const shouldNotMatch = [
+    "help",
+    "status",
+    "/gsd auto",
+    "/gsd stats",
+    "what's the plan?",
+    "show me the logs",
+    "abort",
+    "stop",
+    "cancel",
+    "replan this slice",
+    "I think we should change the approach",
+    "can you explain what you just did?",
+    "run the tests",
+    "check the build",
+    "Execute the next task: T01",
+    "what files were changed",
+    "",
+  ];
+
+  for (const prompt of shouldMatch) {
+    test(`matches resume prompt: "${prompt}"`, () => {
+      assert.ok(
+        pattern.test(normalize(prompt)),
+        `expected RESUME_INTENT_PATTERNS to match "${prompt}" (normalized: "${normalize(prompt)}")`,
+      );
+    });
+  }
+
+  for (const prompt of shouldNotMatch) {
+    test(`rejects non-resume prompt: "${prompt}"`, () => {
+      assert.ok(
+        !pattern.test(normalize(prompt)),
+        `expected RESUME_INTENT_PATTERNS to NOT match "${prompt}" (normalized: "${normalize(prompt)}")`,
+      );
+    });
+  }
+});

package/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts

@@ -9,7 +9,7 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -57,13 +57,20 @@ function hasRecognizedProjectFiles(basePath: string, existsSyncFn: (p: string) =
   return false;
 }
 
+/** Simulate the phases.ts Xcode-bundle detection (readdirSync suffix scan). */
+function hasXcodeBundle(basePath: string): boolean {
+  try {
+    return readdirSync(basePath).some((e) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"));
+  } catch { return false; }
+}
+
 import { existsSync } from "node:fs";
 
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 test("PROJECT_FILES is exported and contains expected multi-ecosystem entries", () => {
   assert.ok(Array.isArray(PROJECT_FILES), "PROJECT_FILES is an array");
-  assert.ok(PROJECT_FILES.length >= 17, `expected >= 17 entries, got ${PROJECT_FILES.length}`);
+  assert.ok(PROJECT_FILES.length >= 18, `expected >= 18 entries, got ${PROJECT_FILES.length}`);
   // Spot-check key ecosystems
   assert.ok(PROJECT_FILES.includes("Cargo.toml"), "includes Rust marker");
   assert.ok(PROJECT_FILES.includes("go.mod"), "includes Go marker");
@@ -140,3 +147,29 @@ describe("health check without git repo", () => {
     assert.ok(!wouldPassHealthCheck(dir, existsSync), "no-git directory should fail health check");
   });
 });
+
+describe("health check with xcodegen and Xcode bundles", () => {
+  let dir: string;
+  beforeEach(() => { dir = createGitRepo(); });
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  test("health check passes for xcodegen project (project.yml, no Package.swift)", () => {
+    writeFileSync(join(dir, "project.yml"), "name: MyApp\ntargets:\n  MyApp:\n    type: application\n");
+    assert.ok(wouldPassHealthCheck(dir, existsSync), "xcodegen project should pass health check");
+  });
+
+  // Regression for the real-world failure in #1882: an iOS project with a
+  // project-specific Xcode bundle (Sudokuxyz.xcodeproj/) was blocked because
+  // PROJECT_FILES only probes exact filenames, not suffix-based directory names.
+  test("Xcode bundle (*.xcodeproj) is not in PROJECT_FILES but detected by suffix scan", () => {
+    mkdirSync(join(dir, "Sudokuxyz.xcodeproj"), { recursive: true });
+    mkdirSync(join(dir, "Sources", "Sudokuxyz"), { recursive: true });
+    writeFileSync(join(dir, "Sources", "Sudokuxyz", "ContentView.swift"), "import SwiftUI\n");
+    // PROJECT_FILES uses exact names — cannot match project-specific bundle names
+    assert.ok(!hasRecognizedProjectFiles(dir, existsSync), "xcodeproj bundle must NOT be in PROJECT_FILES");
+    // The readdirSync suffix scan used in phases.ts detects it
+    assert.ok(hasXcodeBundle(dir), "readdirSync suffix scan detects .xcodeproj bundle");
+    // Health check passes regardless (only requires .git)
+    assert.ok(wouldPassHealthCheck(dir, existsSync), "Xcode bundle project should pass health check");
+  });
+});

package/src/resources/extensions/gsd/tests/worktree-health-monorepo.test.ts

@@ -0,0 +1,73 @@
+/**
+ * worktree-health-monorepo.test.ts — #2347
+ *
+ * The worktree health check in auto/phases.ts falsely rejects monorepos
+ * where package.json (or other project markers) is in a parent directory.
+ * This test verifies that the health check walks parent directories.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, report } = createTestContext();
+
+const srcPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const src = readFileSync(srcPath, "utf-8");
+
+console.log("\n=== #2347: Worktree health check supports monorepos ===");
+
+// ── Test 1: The health check region exists ──────────────────────────────
+
+const healthCheckIdx = src.indexOf("Worktree health check");
+assertTrue(healthCheckIdx > 0, "auto/phases.ts has worktree health check section");
+
+const healthCheckRegion = src.slice(healthCheckIdx, healthCheckIdx + 2000);
+
+// ── Test 2: The check walks parent directories for project markers ──────
+
+// The fix should check parent directories for project files, not just s.basePath.
+// Look for patterns like: walking up directories, dirname, parent, or a helper
+// function that checks ancestors.
+const checksParentDirs =
+  healthCheckRegion.includes("dirname") ||
+  healthCheckRegion.includes("parent") ||
+  healthCheckRegion.includes("ancestor") ||
+  healthCheckRegion.includes("walk") ||
+  // Or a helper function that's called with the base path
+  /hasProjectFileInAncestor|findProjectRoot|checkParent/i.test(healthCheckRegion);
+
+assertTrue(
+  checksParentDirs,
+  "Health check should walk parent directories for project markers (monorepo support) (#2347)",
+);
+
+// ── Test 3: The parent walk stops at a .git boundary ──────────────────
+
+// The parent directory walk must not escape the git repository root.
+// Without this guard, ancestor directories like ~ or /usr/local that
+// happen to contain package.json would cause false positive health checks.
+const hasGitBoundary = healthCheckRegion.includes('.git') &&
+  (healthCheckRegion.includes('break') || healthCheckRegion.includes('stop'));
+
+assertTrue(
+  hasGitBoundary,
+  "Parent directory walk must stop at .git repository boundary to prevent false positives",
+);
+
+// ── Test 4: The greenfield warning should only trigger when no parent has markers ─
+
+// The original code was:
+//   const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f)));
+// The fix should check parents too, so the greenfield warning only fires
+// when NO ancestor directory has project markers either.
+const hasParentCheck = healthCheckRegion.includes("parent") ||
+  healthCheckRegion.includes("dirname") ||
+  /ancestor|walk.*up/i.test(healthCheckRegion);
+
+assertTrue(
+  hasParentCheck,
+  "Greenfield check should consider parent directories before warning (#2347)",
+);
+
+report();

package/src/resources/extensions/gsd/tests/worktree-resolver.test.ts

@@ -550,6 +550,40 @@ test("mergeAndExit failure message tells user worktree and branch are preserved
   );
 });
 
+test("mergeAndExit failure message references /gsd dispatch complete-milestone, not /complete-milestone (#1891)", () => {
+  // Regression test: the failure notification previously told users to
+  // "retry /complete-milestone" — a command that does not exist. The correct
+  // recovery command is "/gsd dispatch complete-milestone".
+  const s = makeSession({
+    basePath: "/project/.gsd/worktrees/M001",
+    originalBasePath: "/project",
+  });
+  const deps = makeDeps({
+    isInAutoWorktree: () => true,
+    getIsolationMode: () => "worktree",
+    mergeMilestoneToMain: () => {
+      throw new Error("dirty working tree");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.mergeAndExit("M001", ctx);
+
+  const warning = ctx.messages.find((m) => m.level === "warning");
+  assert.ok(warning, "a warning message is emitted");
+  // Must reference the correct dispatch command
+  assert.ok(
+    warning!.msg.includes("/gsd dispatch complete-milestone"),
+    "warning references /gsd dispatch complete-milestone, not bare /complete-milestone",
+  );
+  // Must NOT contain the bare (incorrect) command without the dispatch prefix
+  assert.ok(
+    !warning!.msg.match(/retry\s+\/complete-milestone(?!\S)/),
+    "warning must not reference the non-existent /complete-milestone command",
+  );
+});
+
 // ─── mergeAndExit Tests (branch mode) ────────────────────────────────────────
 
 test("mergeAndExit in branch mode merges when on milestone branch", () => {