gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/src/resources/extensions/gsd/tests/auto-retry-mcp-churn-fixes.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Regression tests for PR #4288 — auto-retry bug, .mcp.json churn, and MCP
+ * worktree routing fixes.
+ *
+ * Covers four source-file changes:
+ *   1. src/resources/extensions/gsd/safety/evidence-collector.ts (functional)
+ *   2. src/resources/extensions/gsd/bootstrap/register-hooks.ts (source shape)
+ *   3. src/resources/extensions/gsd/auto-recovery.ts (source shape)
+ *   4. packages/mcp-server/src/workflow-tools.ts (source shape)
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  resetEvidence,
+  getEvidence,
+  recordToolCall,
+  recordToolResult,
+  type BashEvidence,
+} from "../safety/evidence-collector.js";
+
+// ─── 1. evidence-collector: functional ─────────────────────────────────────
+
+describe("evidence-collector: toolCallId-based matching (A-3)", () => {
+  beforeEach(() => {
+    resetEvidence();
+  });
+
+  it("records bash calls with their toolCallId at dispatch time", () => {
+    recordToolCall("tc-1", "bash", { command: "ls -la" });
+    recordToolCall("tc-2", "bash", { command: "git status" });
+
+    const entries = getEvidence();
+    assert.equal(entries.length, 2);
+    assert.equal(entries[0].toolCallId, "tc-1");
+    assert.equal(entries[1].toolCallId, "tc-2");
+  });
+
+  it("matches results to the correct entry by toolCallId, not insertion order", () => {
+    // Simulate two parallel bash calls dispatched in order tc-1, tc-2.
+    recordToolCall("tc-1", "bash", { command: "slow-thing" });
+    recordToolCall("tc-2", "bash", { command: "fast-thing" });
+
+    // Results arrive out of order: tc-2 first (fast), then tc-1 (slow).
+    // With the old empty-string-matching strategy, tc-2's result would be
+    // stapled to tc-1's entry because findLastUnresolved scanned backwards
+    // for empty ids. Now we match by id directly.
+    recordToolResult("tc-2", "bash", "Command exited with code 0\nfast-output", false);
+    recordToolResult("tc-1", "bash", "Command exited with code 1\nslow-failure", true);
+
+    const entries = getEvidence() as readonly BashEvidence[];
+    const tc1 = entries.find(e => e.toolCallId === "tc-1") as BashEvidence | undefined;
+    const tc2 = entries.find(e => e.toolCallId === "tc-2") as BashEvidence | undefined;
+
+    assert.ok(tc1, "tc-1 entry must exist");
+    assert.ok(tc2, "tc-2 entry must exist");
+
+    // The original command stays attached to the entry it was recorded with,
+    // and the result matches the id it was reported for.
+    assert.equal(tc1.command, "slow-thing");
+    assert.equal(tc1.exitCode, 1);
+    assert.ok(tc1.outputSnippet.includes("slow-failure"));
+
+    assert.equal(tc2.command, "fast-thing");
+    assert.equal(tc2.exitCode, 0);
+    assert.ok(tc2.outputSnippet.includes("fast-output"));
+  });
+
+  it("ignores results with unknown toolCallIds rather than corrupting nearby entries", () => {
+    recordToolCall("tc-1", "bash", { command: "real" });
+    recordToolResult("tc-UNKNOWN", "bash", "Command exited with code 0\n", false);
+
+    const entries = getEvidence() as readonly BashEvidence[];
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].toolCallId, "tc-1");
+    // tc-1 must be untouched — no result was reported for it.
+    assert.equal(entries[0].exitCode, -1);
+    assert.equal(entries[0].outputSnippet, "");
+  });
+
+  it("records write/edit entries with their toolCallId", () => {
+    recordToolCall("tc-write", "write", { file_path: "/tmp/a.md" });
+    recordToolCall("tc-edit", "edit", { file_path: "/tmp/b.md" });
+
+    const entries = getEvidence();
+    assert.equal(entries.length, 2);
+    assert.equal(entries[0].kind, "write");
+    assert.equal(entries[0].toolCallId, "tc-write");
+    assert.equal(entries[1].kind, "edit");
+    assert.equal(entries[1].toolCallId, "tc-edit");
+  });
+});
+
+// ─── 2. register-hooks: MCP auto-prep gated inside auto-worktrees (A-1) ────
+
+describe("register-hooks: skip prepareWorkflowMcpForProject inside auto-worktrees (A-1)", () => {
+  const src = readFileSync(
+    resolve(process.cwd(), "src", "resources", "extensions", "gsd", "bootstrap", "register-hooks.ts"),
+    "utf-8",
+  );
+
+  it("session_start hook is gated on isInAutoWorktree", () => {
+    const idx = src.indexOf('pi.on("session_start"');
+    assert.ok(idx !== -1, "session_start handler must exist");
+    const block = src.slice(idx, idx + 2500);
+    assert.ok(
+      block.includes("isInAutoWorktree"),
+      "session_start must consult isInAutoWorktree before preparing MCP",
+    );
+    assert.ok(
+      block.includes("prepareWorkflowMcpForProject"),
+      "session_start still prepares MCP for non-worktree paths",
+    );
+  });
+
+  it("session_switch hook is gated on isInAutoWorktree", () => {
+    const idx = src.indexOf('pi.on("session_switch"');
+    assert.ok(idx !== -1, "session_switch handler must exist");
+    const block = src.slice(idx, idx + 2500);
+    assert.ok(
+      block.includes("isInAutoWorktree"),
+      "session_switch must consult isInAutoWorktree before preparing MCP",
+    );
+  });
+
+  it("tool_call hook forwards event.toolCallId into safetyRecordToolCall (A-3)", () => {
+    // Find the call site (skip the import line by looking for the opening paren).
+    const idx = src.indexOf("safetyRecordToolCall(");
+    assert.ok(idx !== -1, "safetyRecordToolCall call must exist");
+    const line = src.slice(idx, src.indexOf("\n", idx));
+    assert.ok(
+      line.includes("event.toolCallId"),
+      "safetyRecordToolCall must receive event.toolCallId as the first argument",
+    );
+  });
+});
+
+// ─── 3. auto-recovery: verify-fail instrumentation ─────────────────────────
+
+describe("verifyExpectedArtifact: verify-fail exit-point logging (Phase B diag)", () => {
+  const src = readFileSync(
+    resolve(process.cwd(), "src", "resources", "extensions", "gsd", "auto-recovery.ts"),
+    "utf-8",
+  );
+
+  it("logs a verify-fail warning on the null-absPath exit", () => {
+    assert.ok(
+      src.includes('verify-fail ${unitType} ${unitId}: resolveExpectedArtifactPath returned null'),
+      "null-absPath branch must emit a diagnostic line",
+    );
+  });
+
+  it("logs a verify-fail warning on the existsSync-false exit", () => {
+    assert.ok(
+      src.includes("verify-fail ${unitType} ${unitId}: existsSync false"),
+      "existsSync-false branch must emit a diagnostic line",
+    );
+  });
+
+  it("logs a verify-fail warning on the plan-slice no-task-entry exit", () => {
+    assert.ok(
+      src.includes("verify-fail ${unitType} ${unitId}: plan has no task checkbox/heading"),
+      "plan-slice no-task branch must emit a diagnostic line",
+    );
+  });
+
+  it("plan-slice task-plan-files check fails fast on missing tasks dir (hardening)", () => {
+    // The original check silently passed when resolveTasksDir returned null.
+    // The new check returns false with a diagnostic, which is correct — if
+    // the tool successfully planned tasks, the tasks/ dir must exist.
+    const idx = src.indexOf('verify-fail ${unitType} ${unitId}: resolveTasksDir returned null');
+    assert.ok(
+      idx !== -1,
+      "resolveTasksDir-null branch must emit a diagnostic and return false",
+    );
+  });
+});
+
+// ─── 4. workflow-tools (mcp-server): guard + optional projectDir + routing ─
+
+describe("mcp-server workflow-tools: projectDir routing (Phase B root cause)", () => {
+  const src = readFileSync(
+    resolve(process.cwd(), "packages", "mcp-server", "src", "workflow-tools.ts"),
+    "utf-8",
+  );
+
+  it("projectDirParam is optional and documents the default", () => {
+    const idx = src.indexOf("const projectDirParam");
+    assert.ok(idx !== -1, "projectDirParam definition must exist");
+    const block = src.slice(idx, idx + 600);
+    assert.ok(
+      block.includes(".optional()"),
+      "projectDirParam must be optional so the agent stops deliberating",
+    );
+    assert.ok(
+      /Omit this field/i.test(block),
+      "description must tell the agent to omit the field",
+    );
+  });
+
+  it("parseWorkflowArgs defaults projectDir to process.cwd() when omitted", () => {
+    const idx = src.indexOf("function parseWorkflowArgs");
+    assert.ok(idx !== -1, "parseWorkflowArgs must exist");
+    const block = src.slice(idx, idx + 1500);
+    assert.ok(
+      block.includes("parsed.projectDir ?? process.cwd()"),
+      "parseWorkflowArgs must fall back to process.cwd() when projectDir is omitted",
+    );
+  });
+
+  it("validateProjectDir accepts external-state worktree paths via .gsd symlink target", () => {
+    const idx = src.indexOf("function validateProjectDir");
+    assert.ok(idx !== -1, "validateProjectDir must exist");
+    const block = src.slice(idx, idx + 2500);
+    assert.ok(
+      block.includes("resolveExternalStateRoot"),
+      "validateProjectDir must consult resolveExternalStateRoot for external-state layouts",
+    );
+
+    const helperIdx = src.indexOf("function resolveExternalStateRoot");
+    assert.ok(helperIdx !== -1, "resolveExternalStateRoot helper must exist");
+    const helperBlock = src.slice(helperIdx, helperIdx + 600);
+    assert.ok(
+      helperBlock.includes("realpathSync"),
+      "resolveExternalStateRoot must use realpathSync to follow the symlink",
+    );
+    assert.ok(
+      /join\([^)]*\.gsd/.test(helperBlock),
+      "resolveExternalStateRoot must resolve <allowedRoot>/.gsd",
+    );
+  });
+
+  it("parseWorkflowArgs routes tool writes to the active worktree when one exists", () => {
+    // This is the Phase B root-cause fix: when the tool call is scoped to a
+    // milestone that has an auto-worktree at <projectRoot>/.gsd/worktrees/<MID>/,
+    // tool writes must go to the worktree .gsd rather than the shared project .gsd.
+    const parseIdx = src.indexOf("function parseWorkflowArgs");
+    const parseBlock = src.slice(parseIdx, parseIdx + 2500);
+    assert.ok(
+      parseBlock.includes("resolveActiveWorktreeBasePath"),
+      "parseWorkflowArgs must consult resolveActiveWorktreeBasePath",
+    );
+    assert.ok(
+      parseBlock.includes("extractMilestoneId"),
+      "parseWorkflowArgs must extract the milestoneId to locate the worktree",
+    );
+  });
+
+  it("resolveActiveWorktreeBasePath checks .git presence to avoid hijacking stray directories", () => {
+    const idx = src.indexOf("function resolveActiveWorktreeBasePath");
+    assert.ok(idx !== -1, "resolveActiveWorktreeBasePath helper must exist");
+    const block = src.slice(idx, idx + 1200);
+    assert.ok(
+      block.includes('existsSync(join(wtPath, ".git"))'),
+      "resolveActiveWorktreeBasePath must verify a .git file exists in the worktree",
+    );
+  });
+
+  it("extractMilestoneId handles camelCase, snake_case, and short aliases", () => {
+    const idx = src.indexOf("function extractMilestoneId");
+    assert.ok(idx !== -1, "extractMilestoneId helper must exist");
+    const block = src.slice(idx, idx + 600);
+    assert.ok(block.includes("milestoneId"), "must check milestoneId");
+    assert.ok(block.includes("milestone_id"), "must check milestone_id");
+    assert.ok(block.includes("mid"), "must check mid");
+  });
+});

package/src/resources/extensions/gsd/tests/auto-warning-noise-regression.test.ts

@@ -0,0 +1,117 @@
+// GSD Extension — Regression tests for auto-mode warning noise (PR #4294)
+//
+// Three independent bug fixes, three regression tests:
+//
+//   1. auto-model-selection.ts — buildFlatRateContext detached
+//      getProviderAuthMode from its receiver, losing `this` and throwing
+//      "Cannot read properties of undefined (reading 'registeredProviders')".
+//      Runtime test: pass a registry whose method actually uses `this` and
+//      verify the returned authMode survives (proves the method is called
+//      with correct binding).
+//
+//   2. auto-worktree.ts — isSamePath logged every error as a warning,
+//      including ENOENT when a worktree's .gsd dir hadn't been created yet.
+//      Source-check test: the catch block must short-circuit on ENOENT
+//      before hitting logWarning. Follows the same style as
+//      copy-planning-artifacts-samepath.test.ts.
+//
+//   3. guided-flow.ts — checkAutoStartAfterDiscuss unconditionally tried
+//      to unlink DISCUSSION-MANIFEST.json and warned on ENOENT even when
+//      the milestone never had a discussion phase. Source-check test:
+//      the unlink must be guarded with existsSync, matching the
+//      CONTEXT-DRAFT.md cleanup pattern two lines above.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { buildFlatRateContext } from "../auto-model-selection.ts";
+
+// ─── Bug 2: this-binding regression ─────────────────────────────────────
+
+test("buildFlatRateContext invokes getProviderAuthMode with correct `this`", () => {
+  // Mimics ModelRegistry: getProviderAuthMode reads from an instance field.
+  // Detaching the method to a local variable would break this — the old code
+  // did `const fn = ctx.modelRegistry.getProviderAuthMode; fn(provider)`,
+  // which called the method with `this === undefined` and threw.
+  const providerData = new Map<string, string>([
+    ["claude-code", "externalCli"],
+    ["anthropic", "apiKey"],
+  ]);
+  const registry = {
+    _providers: providerData,
+    getProviderAuthMode(provider: string): string {
+      // Access via `this` — fails loudly if the method was called unbound.
+      const map = this._providers;
+      return map.get(provider) ?? "apiKey";
+    },
+  };
+
+  const ctx = buildFlatRateContext("claude-code", { modelRegistry: registry });
+  assert.equal(
+    ctx.authMode,
+    "externalCli",
+    "authMode should be extracted when getProviderAuthMode is called as a method",
+  );
+
+  const ctx2 = buildFlatRateContext("anthropic", { modelRegistry: registry });
+  assert.equal(ctx2.authMode, "apiKey");
+});
+
+// ─── Bug 1: isSamePath source check ─────────────────────────────────────
+
+test("isSamePath short-circuits ENOENT before logging a warning", () => {
+  const srcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+  const src = readFileSync(srcPath, "utf-8");
+
+  const fnIdx = src.indexOf("function isSamePath");
+  assert.ok(fnIdx !== -1, "isSamePath function exists");
+
+  // Grab the function body (enough to cover the catch block).
+  const fnBody = src.slice(fnIdx, fnIdx + 600);
+
+  const catchIdx = fnBody.indexOf("catch");
+  assert.ok(catchIdx !== -1, "isSamePath has a catch block");
+
+  const enoentIdx = fnBody.indexOf("ENOENT", catchIdx);
+  const warnIdx = fnBody.indexOf("logWarning", catchIdx);
+
+  assert.ok(enoentIdx !== -1, "catch block must handle ENOENT explicitly");
+  assert.ok(warnIdx !== -1, "catch block still warns on non-ENOENT errors");
+  assert.ok(
+    enoentIdx < warnIdx,
+    "ENOENT early-return must precede the logWarning call",
+  );
+});
+
+// ─── Bug 3: guided-flow manifest unlink source check ────────────────────
+
+test("checkAutoStartAfterDiscuss guards DISCUSSION-MANIFEST.json unlink with existsSync", () => {
+  const srcPath = join(import.meta.dirname, "..", "guided-flow.ts");
+  const src = readFileSync(srcPath, "utf-8");
+
+  const fnIdx = src.indexOf("function checkAutoStartAfterDiscuss");
+  assert.ok(fnIdx !== -1, "checkAutoStartAfterDiscuss function exists");
+
+  // Locate the manifest cleanup comment and its surrounding block.
+  const cleanupIdx = src.indexOf(
+    "remove discussion manifest after auto-start",
+    fnIdx,
+  );
+  assert.ok(cleanupIdx !== -1, "manifest cleanup block still exists");
+
+  // Everything from the comment to a short distance below should contain
+  // the existsSync guard before the unlinkSync call.
+  const block = src.slice(cleanupIdx, cleanupIdx + 400);
+
+  const existsIdx = block.indexOf("existsSync(manifestPath)");
+  const unlinkIdx = block.indexOf("unlinkSync(manifestPath)");
+
+  assert.ok(existsIdx !== -1, "manifest unlink must be guarded by existsSync");
+  assert.ok(unlinkIdx !== -1, "manifest unlink still happens when file exists");
+  assert.ok(
+    existsIdx < unlinkIdx,
+    "existsSync guard must precede the unlinkSync call",
+  );
+});

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -15,6 +15,9 @@ const autoSrc = readFileSync(autoPath, "utf-8");
 const runUnitPath = join(import.meta.dirname, "..", "auto", "run-unit.ts");
 const runUnitSrc = readFileSync(runUnitPath, "utf-8");
 
+const registerHooksPath = join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts");
+const registerHooksSrc = readFileSync(registerHooksPath, "utf-8");
+
 describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () => {
   test("soft timeout wrapup gates triggerTurn on getInFlightToolCount() === 0", () => {
     // The soft timeout sendMessage must NOT use a hardcoded `triggerTurn: true`.
@@ -70,6 +73,42 @@ describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () =>
   });
 });
 
+describe("#4276: pending/skipped tools stay visible to auto-mode hooks", () => {
+  test("tool_call handler marks GSD tools in-flight before execution_start", () => {
+    const startMarker = 'pi.on("tool_call", async (event, ctx) => {';
+    const endMarker = 'pi.on("tool_result", async (event) => {';
+    const toolCallSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(toolCallSection.length > 0, "Could not locate tool_call handler section");
+    assert.ok(
+      toolCallSection.includes("markToolStart(event.toolCallId, event.toolName)"),
+      "tool_call handler must mark tools pending before tool_execution_start fires",
+    );
+  });
+
+  test("tool_result handler clears pending tools and records queued-skip errors", () => {
+    const startMarker = 'pi.on("tool_result", async (event) => {';
+    const endMarker = 'pi.on("tool_execution_start", async (event) => {';
+    const toolResultSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(toolResultSection.length > 0, "Could not locate tool_result handler section");
+    assert.ok(
+      toolResultSection.includes("markToolEnd(event.toolCallId)"),
+      "tool_result handler must clear pending tool tracking even when execution hooks never fire",
+    );
+    assert.ok(
+      toolResultSection.includes("recordToolInvocationError(event.toolName, errorText)"),
+      "tool_result handler must surface queued-skip errors for GSD tools",
+    );
+  });
+});
+
 describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", () => {
   test("stopAuto calls clearQueue()", () => {
     // stopAuto must flush queued messages to prevent late async_job_result

package/src/resources/extensions/gsd/tests/autocomplete-regressions-1675.test.ts

@@ -44,6 +44,14 @@ test("/gsd description includes discuss", () => {
   );
 });
 
+test("/gsd description includes debug", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  assert.ok(gsd.description.includes("debug"), "description should include debug");
+});
+
 test("/gsd next completions include --debug", () => {
   const pi = createMockPi();
   registerGSDCommand(pi as any);
@@ -54,6 +62,18 @@ test("/gsd next completions include --debug", () => {
   assert.ok(debug, "next --debug should appear in completions");
 });
 
+test("/gsd debug completions include list|status|continue|--diagnose", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  const completions = gsd.getArgumentCompletions("debug ");
+  const values = completions.map((c: any) => c.value);
+  for (const expected of ["debug list", "debug status", "debug continue", "debug --diagnose"]) {
+    assert.ok(values.includes(expected), `missing completion: ${expected}`);
+  }
+});
+
 test("/gsd widget completions include full|small|min|off", () => {
   const pi = createMockPi();
   registerGSDCommand(pi as any);
@@ -66,6 +86,25 @@ test("/gsd widget completions include full|small|min|off", () => {
   }
 });
 
+test("/gsd logs completions still include debug after adding /gsd debug", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  const completions = gsd.getArgumentCompletions("logs ");
+  const values = completions.map((c: any) => c.value);
+  assert.ok(values.includes("logs debug"), "logs debug completion should remain available");
+});
+
+test("/gsd help full includes /gsd debug command", async () => {
+  const ctx = createMockCtx();
+
+  await handleGSDCommand("help full", ctx as any, {} as any);
+
+  const helpText = ctx.notifications.map((n) => n.message).join("\n");
+  assert.match(helpText, /\/gsd debug\s+Create\/list\/continue persistent debug sessions/);
+});
+
 test("bare /gsd skip shows usage and does not fall through to unknown-command warning", async () => {
   const ctx = createMockCtx();
 

package/src/resources/extensions/gsd/tests/cold-resume-db-reopen.test.ts

@@ -25,8 +25,12 @@ console.log("\n=== resume path refreshes resources and opens DB before rebuildSt
 const resumeSectionStart = autoSrc.indexOf("if (s.paused) {", autoSrc.indexOf("// If resuming from paused state"));
 assertTrue(resumeSectionStart > 0, "auto.ts has the paused-session resume block");
 
-const resumeSectionEnd = autoSrc.indexOf("await autoLoop(", resumeSectionStart);
-assertTrue(resumeSectionEnd > resumeSectionStart, "resume block reaches autoLoop");
+const resumeSectionEndCandidates = [
+  autoSrc.indexOf("await runAutoLoopWithUok(", resumeSectionStart),
+  autoSrc.indexOf("await autoLoop(", resumeSectionStart),
+].filter((idx) => idx > resumeSectionStart);
+const resumeSectionEnd = resumeSectionEndCandidates.length > 0 ? Math.min(...resumeSectionEndCandidates) : -1;
+assertTrue(resumeSectionEnd > resumeSectionStart, "resume block reaches the dispatch loop");
 
 const resumeSection = autoSrc.slice(resumeSectionStart, resumeSectionEnd);
 

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

@@ -0,0 +1,158 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-backlog-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function backlogPath(base: string): string {
+  return join(base, ".gsd", "BACKLOG.md");
+}
+
+function writeBacklog(base: string, content: string): void {
+  writeFileSync(backlogPath(base), content, "utf-8");
+}
+
+function readBacklog(base: string): string {
+  return readFileSync(backlogPath(base), "utf-8");
+}
+
+// Test the parsing/writing logic inline since the handler requires runtime context
+
+interface BacklogItem {
+  id: string;
+  title: string;
+  done: boolean;
+  note: string;
+}
+
+function parseBacklog(content: string): BacklogItem[] {
+  const items: BacklogItem[] = [];
+  for (const line of content.split("\n")) {
+    const match = line.match(/^- \[([ x])\] (999\.\d+) — (.+?)(?:\s*\((.+)\))?$/);
+    if (match) {
+      items.push({
+        id: match[2],
+        title: match[3].trim(),
+        done: match[1] === "x",
+        note: match[4] ?? "",
+      });
+    }
+  }
+  return items;
+}
+
+function formatBacklog(items: BacklogItem[]): string {
+  const lines = ["# Backlog\n"];
+  for (const item of items) {
+    const check = item.done ? "x" : " ";
+    const note = item.note ? ` (${item.note})` : "";
+    lines.push(`- [${check}] ${item.id} — ${item.title}${note}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+test("backlog: parse empty file returns empty array", () => {
+  const items = parseBacklog("");
+  assert.equal(items.length, 0);
+});
+
+test("backlog: parse valid entries", () => {
+  const content = `# Backlog
+
+- [ ] 999.1 — OAuth support (added 2026-03-23)
+- [x] 999.2 — Rate limiting (promoted 2026-03-24)
+- [ ] 999.3 — Dark mode`;
+
+  const items = parseBacklog(content);
+  assert.equal(items.length, 3);
+  assert.equal(items[0].id, "999.1");
+  assert.equal(items[0].title, "OAuth support");
+  assert.equal(items[0].done, false);
+  assert.equal(items[0].note, "added 2026-03-23");
+
+  assert.equal(items[1].id, "999.2");
+  assert.equal(items[1].done, true);
+  assert.equal(items[1].note, "promoted 2026-03-24");
+
+  assert.equal(items[2].id, "999.3");
+  assert.equal(items[2].title, "Dark mode");
+  assert.equal(items[2].note, "");
+});
+
+test("backlog: format roundtrips correctly", () => {
+  const items: BacklogItem[] = [
+    { id: "999.1", title: "OAuth support", done: false, note: "added 2026-03-23" },
+    { id: "999.2", title: "Rate limiting", done: true, note: "promoted 2026-03-24" },
+  ];
+
+  const formatted = formatBacklog(items);
+  const parsed = parseBacklog(formatted);
+
+  assert.equal(parsed.length, 2);
+  assert.equal(parsed[0].id, "999.1");
+  assert.equal(parsed[0].title, "OAuth support");
+  assert.equal(parsed[1].done, true);
+});
+
+test("backlog: write and read from disk", () => {
+  const base = makeTmpBase();
+  try {
+    const items: BacklogItem[] = [
+      { id: "999.1", title: "Test item", done: false, note: "added 2026-03-23" },
+    ];
+    writeBacklog(base, formatBacklog(items));
+
+    assert.ok(existsSync(backlogPath(base)));
+    const content = readBacklog(base);
+    assert.ok(content.includes("999.1"));
+    assert.ok(content.includes("Test item"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("backlog: next ID increments correctly", () => {
+  const items: BacklogItem[] = [
+    { id: "999.1", title: "First", done: false, note: "" },
+    { id: "999.2", title: "Second", done: false, note: "" },
+    { id: "999.5", title: "Fifth", done: false, note: "" },
+  ];
+
+  let maxNum = 0;
+  for (const item of items) {
+    const match = item.id.match(/^999\.(\d+)$/);
+    if (match) {
+      const num = parseInt(match[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+  }
+  const nextId = `999.${maxNum + 1}`;
+  assert.equal(nextId, "999.6");
+});
+
+test("backlog: empty backlog returns no items", () => {
+  const base = makeTmpBase();
+  try {
+    // No BACKLOG.md exists
+    assert.ok(!existsSync(backlogPath(base)));
+    // Would return empty array
+  } finally {
+    cleanup(base);
+  }
+});