gsd-pi 2.82.0 → 3.0.0

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd-build/mcp-server",
-  "version": "2.82.0",
+  "version": "3.0.0",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
   "gsd": {
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@gsd-build/contracts": "^2.80.0",
-    "@gsd-build/rpc-client": "^2.82.0",
+    "@gsd-build/rpc-client": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.0.0"
   },

package/packages/mcp-server/src/workflow-tools-parity.test.ts

@@ -0,0 +1,244 @@
+// ADR-008 validation criterion #3 — behavior-parity lock-in for gsd_task_complete.
+//
+// ADR-008 §1 ("One handler layer, multiple transports") is shipped: both
+// native (`db-tools.ts`) and MCP (`workflow-tools.ts`) registrations wrap the
+// same `executeTaskComplete` from `workflow-tool-executors.ts`. This test
+// guards the equivalence so a future executor refactor cannot silently drift
+// the two transports apart.
+//
+// Strategy: run the same completion against two equivalent fresh basePaths,
+// one via the native path (direct call to the shared executor — which is
+// faithfully what `db-tools.ts:670-674` does after `resolveCtxCwd`) and one
+// via the MCP path (`registerWorkflowTools` + tool.handler). Snapshot DB row,
+// summary file content, and journal events for each. Assert equivalence
+// modulo expected diffs (timestamps).
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  closeDatabase,
+  getTask,
+} from "../../../src/resources/extensions/gsd/gsd-db.ts";
+import { executeTaskComplete } from "../../../src/resources/extensions/gsd/tools/workflow-tool-executors.ts";
+import { registerWorkflowTools } from "./workflow-tools.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-mcp-parity-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function seedMilestoneAndSlice(base: string): void {
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+    "# S01\n\n- [ ] **T01: Demo** `est:5m`\n",
+    "utf-8",
+  );
+}
+
+function cleanup(base: string): void {
+  try {
+    closeDatabase();
+  } catch {
+    // swallow
+  }
+  try {
+    rmSync(base, { recursive: true, force: true });
+  } catch {
+    // swallow
+  }
+}
+
+function makeMockServer() {
+  const tools: Array<{
+    name: string;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+  }> = [];
+  return {
+    tools,
+    tool(
+      name: string,
+      _description: string,
+      _params: Record<string, unknown>,
+      handler: (args: Record<string, unknown>) => Promise<unknown>,
+    ) {
+      tools.push({ name, handler });
+    },
+  };
+}
+
+interface SnapshotShape {
+  /** SUMMARY.md content, trimmed, with ISO timestamps replaced by a sentinel. */
+  summary: string;
+  /** Task row, with volatile fields (timestamps, derived ids) elided. */
+  taskRow: Record<string, unknown>;
+  /** Journal events for this completion, with timestamps and ids normalized. */
+  journalEvents: Array<{ cmd: string; params: Record<string, unknown>; actor: string }>;
+}
+
+const ISO_TIMESTAMP_RE = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z/g;
+
+function normalizeTimestamps(text: string): string {
+  return text.replace(ISO_TIMESTAMP_RE, "<NORMALIZED-TS>");
+}
+
+function normalizeParams(params: Record<string, unknown>): Record<string, unknown> {
+  // Recursively replace ISO timestamps in any string value so the deep-equal
+  // doesn't fail on `ts`/`completed_at` style fields nested in the payload.
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(params)) {
+    if (typeof v === "string") {
+      out[k] = normalizeTimestamps(v);
+    } else if (Array.isArray(v)) {
+      out[k] = v.map((item) =>
+        typeof item === "string"
+          ? normalizeTimestamps(item)
+          : item && typeof item === "object"
+            ? normalizeParams(item as Record<string, unknown>)
+            : item,
+      );
+    } else if (v !== null && typeof v === "object") {
+      out[k] = normalizeParams(v as Record<string, unknown>);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function snapshotState(base: string, milestoneId: string, sliceId: string, taskId: string): SnapshotShape {
+  const summaryPath = join(base, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks", `${taskId}-SUMMARY.md`);
+  assert.ok(existsSync(summaryPath), `summary file must exist at ${summaryPath}`);
+  const summary = normalizeTimestamps(readFileSync(summaryPath, "utf-8").trim());
+
+  const row = getTask(milestoneId, sliceId, taskId);
+  assert.ok(row, "task row must exist in DB after completion");
+  // Recursively normalize ISO timestamps in the row (the SQLite row uses
+  // snake_case `completed_at` and embeds another ISO timestamp inside the
+  // string field `full_summary_md`). Recursive normalization is simpler and
+  // more robust than maintaining an elision list.
+  const taskRow = normalizeParams(row as Record<string, unknown>);
+  assert.equal(taskRow.status, "complete", "task status must be 'complete' after completion");
+
+  const journalPath = join(base, ".gsd", "event-log.jsonl");
+  const journalEvents: SnapshotShape["journalEvents"] = [];
+  if (existsSync(journalPath)) {
+    const lines = readFileSync(journalPath, "utf-8")
+      .split("\n")
+      .filter((l) => l.length > 0);
+    for (const line of lines) {
+      try {
+        const evt = JSON.parse(line) as { cmd: string; params: Record<string, unknown>; actor: string };
+        if (evt.cmd === "complete-task" || evt.cmd === "complete_task") {
+          // Normalize cmd to canonical hyphen form, and elide ISO timestamps
+          // in the payload so the wall-clock skew between the two runs doesn't
+          // produce a spurious diff.
+          journalEvents.push({
+            cmd: "complete-task",
+            params: normalizeParams(evt.params),
+            actor: evt.actor,
+          });
+        }
+      } catch {
+        // Skip corrupted lines — non-fatal for parity comparison.
+      }
+    }
+  }
+
+  return { summary, taskRow, journalEvents };
+}
+
+const COMPLETION_ARGS = {
+  taskId: "T01",
+  sliceId: "S01",
+  milestoneId: "M001",
+  oneLiner: "Completed the demo task",
+  narrative: "Did the work described in the plan. Verified by running the test suite.",
+  verification: "npm test — all passing",
+  deviations: "None.",
+  knownIssues: "None.",
+  keyFiles: ["src/demo.ts"],
+  keyDecisions: ["Used Option A from the plan."],
+};
+
+describe("ADR-008 parity: gsd_task_complete native vs MCP", () => {
+  it("native and MCP produce equivalent DB row, summary, and journal event", async () => {
+    let baseNative = "";
+    let baseMcp = "";
+    try {
+      // ─── Native path ─────────────────────────────────────────────────
+      // The native wrapper in db-tools.ts:670-674 is:
+      //   const taskCompleteExecute = async (_tcid, params, ...) => {
+      //     const { executeTaskComplete } = await loadWorkflowExecutors();
+      //     return executeTaskComplete(params, resolveCtxCwd(_ctx));
+      //   };
+      // Calling executeTaskComplete directly with a basePath is the same
+      // post-resolution call shape.
+      baseNative = makeTmpBase();
+      seedMilestoneAndSlice(baseNative);
+      const nativeResult = await executeTaskComplete(COMPLETION_ARGS, baseNative);
+      assert.ok(!nativeResult.isError, "native completion must succeed");
+
+      const snapshotNative = snapshotState(baseNative, "M001", "S01", "T01");
+      closeDatabase();
+
+      // ─── MCP path ────────────────────────────────────────────────────
+      baseMcp = makeTmpBase();
+      seedMilestoneAndSlice(baseMcp);
+
+      const server = makeMockServer();
+      registerWorkflowTools(server as Parameters<typeof registerWorkflowTools>[0]);
+      const taskTool = server.tools.find((t) => t.name === "gsd_task_complete");
+      assert.ok(taskTool, "gsd_task_complete must be registered on the MCP surface");
+
+      const mcpResult = await taskTool.handler({ projectDir: baseMcp, ...COMPLETION_ARGS });
+      assert.ok(!mcpResult.isError, "mcp completion must succeed");
+
+      const snapshotMcp = snapshotState(baseMcp, "M001", "S01", "T01");
+
+      // ─── Compare ─────────────────────────────────────────────────────
+      assert.equal(
+        snapshotNative.summary,
+        snapshotMcp.summary,
+        "SUMMARY.md content must be byte-equal between native and MCP completions",
+      );
+
+      assert.deepEqual(
+        snapshotNative.taskRow,
+        snapshotMcp.taskRow,
+        "tasks DB row (modulo volatile timestamps and ids) must be equal",
+      );
+
+      // Journal event count must match (1 complete-task event per completion).
+      assert.equal(
+        snapshotNative.journalEvents.length,
+        snapshotMcp.journalEvents.length,
+        "both transports must emit the same number of complete-task journal events",
+      );
+
+      // Each journal event's params must match (these encode the completion
+      // payload; cmd is normalized and actor must align).
+      for (let i = 0; i < snapshotNative.journalEvents.length; i++) {
+        assert.equal(
+          snapshotNative.journalEvents[i].actor,
+          snapshotMcp.journalEvents[i].actor,
+          `journal event #${i} actor must match between native and MCP`,
+        );
+        assert.deepEqual(
+          snapshotNative.journalEvents[i].params,
+          snapshotMcp.journalEvents[i].params,
+          `journal event #${i} params must match between native and MCP`,
+        );
+      }
+    } finally {
+      if (baseNative) cleanup(baseNative);
+      if (baseMcp) cleanup(baseMcp);
+    }
+  });
+});

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests packaged workflow tools exposed by the GSD MCP server.
+
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
@@ -96,6 +99,22 @@ describe("workflow MCP tools", () => {
     assert.deepEqual(server.tools.map((t) => t.name), [...WORKFLOW_TOOL_NAMES]);
   });
 
+  it("registers task reopen in the workflow MCP tool surface", () => {
+    const server = makeMockServer();
+    registerWorkflowTools(server as any);
+
+    const toolNames = server.tools.map((t) => t.name);
+    assert.ok(toolNames.includes("gsd_task_reopen"));
+    assert.ok(toolNames.includes("gsd_reopen_task"));
+
+    const taskReopen = server.tools.find((t) => t.name === "gsd_task_reopen");
+    assert.ok(taskReopen);
+    assert.ok("milestoneId" in taskReopen.params);
+    assert.ok("sliceId" in taskReopen.params);
+    assert.ok("taskId" in taskReopen.params);
+    assert.ok("reason" in taskReopen.params);
+  });
+
   it("prefers source TypeScript before compiled dist fallbacks", () => {
     assert.deepEqual(
       _buildImportCandidates("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js"),
@@ -645,6 +664,9 @@ export const executeValidateMilestone = noop;
 export const executeReassessRoadmap = noop;
 export const executeSaveGateResult = noop;
 export const executeSummarySave = noop;
+export const executeTaskReopen = noop;
+export const executeSliceReopen = noop;
+export const executeMilestoneReopen = noop;
 
 export const executeTaskComplete = async (params, projectDir) => {
   const capturePath = process.env.GSD_TEST_TASK_COMPLETE_CAPTURE_PATH;
@@ -820,7 +842,7 @@ export const executeTaskComplete = async (params, projectDir) => {
             estimate: "15m",
             files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"],
             verify: "node --test",
-            inputs: ["ROADMAP.md"],
+            inputs: [".gsd/milestones/M001/M001-ROADMAP.md"],
             expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"],
           },
         ],

package/packages/mcp-server/src/workflow-tools.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Registers packaged workflow tools exposed by the GSD MCP server.
+
 /**
  * Workflow MCP tools — exposes the core GSD mutation/read handlers over MCP.
  */
@@ -228,6 +231,36 @@ type WorkflowToolExecutors = {
     },
     basePath?: string,
   ) => Promise<unknown>;
+  executeTaskReopen: (
+    params: {
+      taskId: string;
+      sliceId: string;
+      milestoneId: string;
+      reason?: string;
+      actorName?: string;
+      triggerReason?: string;
+    },
+    basePath?: string,
+  ) => Promise<unknown>;
+  executeSliceReopen: (
+    params: {
+      sliceId: string;
+      milestoneId: string;
+      reason?: string;
+      actorName?: string;
+      triggerReason?: string;
+    },
+    basePath?: string,
+  ) => Promise<unknown>;
+  executeMilestoneReopen: (
+    params: {
+      milestoneId: string;
+      reason?: string;
+      actorName?: string;
+      triggerReason?: string;
+    },
+    basePath?: string,
+  ) => Promise<unknown>;
 };
 
 type WorkflowWriteGateModule = {
@@ -478,6 +511,9 @@ function isWorkflowToolExecutors(value: unknown): value is WorkflowToolExecutors
     "executeSaveGateResult",
     "executeSummarySave",
     "executeTaskComplete",
+    "executeTaskReopen",
+    "executeSliceReopen",
+    "executeMilestoneReopen",
   ];
 
   return Array.isArray(record.SUPPORTED_SUMMARY_ARTIFACT_TYPES) &&
@@ -835,6 +871,39 @@ async function handleTaskComplete(
   );
 }
 
+async function handleTaskReopen(
+  projectDir: string,
+  args: Omit<z.infer<typeof taskReopenSchema>, "projectDir">,
+): Promise<unknown> {
+  await enforceWorkflowWriteGate("gsd_task_reopen", projectDir, args.milestoneId);
+  const { executeTaskReopen } = await getWorkflowToolExecutors();
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeTaskReopen(args, projectDir)),
+  );
+}
+
+async function handleSliceReopen(
+  projectDir: string,
+  args: Omit<z.infer<typeof sliceReopenSchema>, "projectDir">,
+): Promise<unknown> {
+  await enforceWorkflowWriteGate("gsd_slice_reopen", projectDir, args.milestoneId);
+  const { executeSliceReopen } = await getWorkflowToolExecutors();
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeSliceReopen(args, projectDir)),
+  );
+}
+
+async function handleMilestoneReopen(
+  projectDir: string,
+  args: Omit<z.infer<typeof milestoneReopenSchema>, "projectDir">,
+): Promise<unknown> {
+  await enforceWorkflowWriteGate("gsd_milestone_reopen", projectDir, args.milestoneId);
+  const { executeMilestoneReopen } = await getWorkflowToolExecutors();
+  return adaptExecutorResult(
+    await runSerializedWorkflowOperation(() => executeMilestoneReopen(args, projectDir)),
+  );
+}
+
 async function handleSliceComplete(
   projectDir: string,
   args: z.infer<typeof sliceCompleteSchema>,
@@ -1384,6 +1453,36 @@ const taskCompleteParams = {
 };
 const taskCompleteSchema = z.object(taskCompleteParams);
 
+const taskReopenParams = {
+  projectDir: projectDirParam,
+  taskId: nonEmptyString("taskId").describe("Task ID (e.g. T01)"),
+  sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+  milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+  reason: z.string().optional().describe("Why the task is being reopened"),
+  actorName: z.string().optional().describe("Caller-provided actor identity for audit trail"),
+  triggerReason: z.string().optional().describe("Caller-provided reason this action was triggered"),
+};
+const taskReopenSchema = z.object(taskReopenParams);
+
+const sliceReopenParams = {
+  projectDir: projectDirParam,
+  sliceId: nonEmptyString("sliceId").describe("Slice ID (e.g. S01)"),
+  milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+  reason: z.string().optional().describe("Why the slice is being reopened"),
+  actorName: z.string().optional().describe("Caller-provided actor identity for audit trail"),
+  triggerReason: z.string().optional().describe("Caller-provided reason this action was triggered"),
+};
+const sliceReopenSchema = z.object(sliceReopenParams);
+
+const milestoneReopenParams = {
+  projectDir: projectDirParam,
+  milestoneId: nonEmptyString("milestoneId").describe("Milestone ID (e.g. M001)"),
+  reason: z.string().optional().describe("Why the milestone is being reopened"),
+  actorName: z.string().optional().describe("Caller-provided actor identity for audit trail"),
+  triggerReason: z.string().optional().describe("Caller-provided reason this action was triggered"),
+};
+const milestoneReopenSchema = z.object(milestoneReopenParams);
+
 const milestoneStatusParams = {
   projectDir: projectDirParam,
   milestoneId: z.string().describe("Milestone ID to query (e.g. M001)"),
@@ -1851,6 +1950,75 @@ export function registerWorkflowTools(realServer: McpToolServer): void {
     },
   );
 
+  server.tool(
+    "gsd_task_reopen",
+    "Reset a completed task back to pending so it can be re-done.",
+    taskReopenParams,
+    async (args: Record<string, unknown>) => {
+      const parsed = parseWorkflowArgs(taskReopenSchema, args);
+      const { projectDir, ...taskArgs } = parsed;
+      return handleTaskReopen(projectDir, taskArgs);
+    },
+  );
+
+  server.tool(
+    "gsd_reopen_task",
+    "Alias for gsd_task_reopen. Reset a completed task back to pending so it can be re-done.",
+    taskReopenParams,
+    async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_reopen_task", "gsd_task_reopen");
+      const parsed = parseWorkflowArgs(taskReopenSchema, args);
+      const { projectDir, ...taskArgs } = parsed;
+      return handleTaskReopen(projectDir, taskArgs);
+    },
+  );
+
+  server.tool(
+    "gsd_slice_reopen",
+    "Reset a completed slice back to in_progress and reset its tasks to pending.",
+    sliceReopenParams,
+    async (args: Record<string, unknown>) => {
+      const parsed = parseWorkflowArgs(sliceReopenSchema, args);
+      const { projectDir, ...sliceArgs } = parsed;
+      return handleSliceReopen(projectDir, sliceArgs);
+    },
+  );
+
+  server.tool(
+    "gsd_reopen_slice",
+    "Alias for gsd_slice_reopen. Reset a completed slice back to in_progress and reset its tasks to pending.",
+    sliceReopenParams,
+    async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_reopen_slice", "gsd_slice_reopen");
+      const parsed = parseWorkflowArgs(sliceReopenSchema, args);
+      const { projectDir, ...sliceArgs } = parsed;
+      return handleSliceReopen(projectDir, sliceArgs);
+    },
+  );
+
+  server.tool(
+    "gsd_milestone_reopen",
+    "Reset a closed milestone back to active and reset its slices/tasks for rework.",
+    milestoneReopenParams,
+    async (args: Record<string, unknown>) => {
+      const parsed = parseWorkflowArgs(milestoneReopenSchema, args);
+      const { projectDir, ...milestoneArgs } = parsed;
+      return handleMilestoneReopen(projectDir, milestoneArgs);
+    },
+  );
+
+  server.tool(
+    "gsd_reopen_milestone",
+    "Alias for gsd_milestone_reopen. Reset a closed milestone back to active and reset its slices/tasks for rework.",
+    milestoneReopenParams,
+    async (args: Record<string, unknown>) => {
+      logAliasUsage("gsd_reopen_milestone", "gsd_milestone_reopen");
+      const parsed = parseWorkflowArgs(milestoneReopenSchema, args);
+      const { projectDir, ...milestoneArgs } = parsed;
+      return handleMilestoneReopen(projectDir, milestoneArgs);
+    },
+  );
+
   server.tool(
     "gsd_milestone_status",
     "Read the current status of a milestone and all its slices from the GSD database.",