gsd-pi 2.37.1-dev.d3ace49 → 2.38.0-dev.96dc7fb

package/src/resources/extensions/gsd/tests/doctor-enhancements.test.ts

@@ -0,0 +1,266 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runGSDDoctor } from "../doctor.js";
+import { formatDoctorReportJson } from "../doctor-format.js";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeBase(): { base: string; gsd: string; mDir: string } {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-enh-"));
+  const gsd = join(base, ".gsd");
+  const mDir = join(gsd, "milestones", "M001");
+  mkdirSync(join(mDir, "slices"), { recursive: true });
+  return { base, gsd, mDir };
+}
+
+function writeRoadmap(mDir: string, content: string): void {
+  writeFileSync(join(mDir, "M001-ROADMAP.md"), content);
+}
+
+function writeSlice(mDir: string, sliceId: string, planContent: string): string {
+  const sDir = join(mDir, "slices", sliceId);
+  const tDir = join(sDir, "tasks");
+  mkdirSync(tDir, { recursive: true });
+  writeFileSync(join(sDir, `${sliceId}-PLAN.md`), planContent);
+  return sDir;
+}
+
+async function main(): Promise<void> {
+  // ── 1. Circular dependency detection ──────────────────────────────────────
+  console.log("\n=== circular dependency detection ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Circular Test\n\n## Slices\n- [ ] **S01: Slice A** \`risk:low\` \`depends:[S02]\`\n  > After this: done\n- [ ] **S02: Slice B** \`risk:low\` \`depends:[S01]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice A\n\n**Goal:** A\n**Demo:** A\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+    writeSlice(mDir, "S02", "# S02: Slice B\n\n**Goal:** B\n**Demo:** B\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "circular_slice_dependency"),
+      "detects circular dependency S01 → S02 → S01",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 2. Duplicate task IDs ──────────────────────────────────────────────────
+  console.log("\n=== duplicate task IDs ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Dup Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: First** `est:10m`\n  Task one.\n- [ ] **T01: Duplicate** `est:10m`\n  Task dup.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "duplicate_task_id"),
+      "detects duplicate task ID T01",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 3. Orphaned slice directory ──────────────────────────────────────────
+  console.log("\n=== orphaned slice directory ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Orphan Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+    // Create an extra slice directory not in roadmap
+    mkdirSync(join(mDir, "slices", "S99"), { recursive: true });
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "orphaned_slice_directory" && i.message.includes("S99")),
+      "detects orphaned slice directory S99",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 4. Task file not in plan ───────────────────────────────────────────────
+  console.log("\n=== task file not in plan ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Extra Task Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    const sDir = writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [x] **T01: Task** `est:10m`\n  Done.\n");
+    // T01 summary (matches plan)
+    writeFileSync(join(sDir, "tasks", "T01-SUMMARY.md"), "---\nstatus: done\n---\n# T01\nDone.\n");
+    // T99 summary (NOT in plan)
+    writeFileSync(join(sDir, "tasks", "T99-SUMMARY.md"), "---\nstatus: done\n---\n# T99\nExtra.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "task_file_not_in_plan" && i.message.includes("T99")),
+      "detects task summary T99 not in plan",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 5. Stale REPLAN file ────────────────────────────────────────────────────
+  console.log("\n=== stale REPLAN detection ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Replan Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    const sDir = writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [x] **T01: Task** `est:10m`\n  Done.\n");
+    writeFileSync(join(sDir, "tasks", "T01-SUMMARY.md"), "---\nstatus: done\ncompleted_at: 2026-01-01T00:00:00Z\n---\n# T01\nDone.\n");
+    // Add a REPLAN file even though all tasks are done
+    writeFileSync(join(sDir, "S01-REPLAN.md"), "# S01 REPLAN\nSomething changed.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "stale_replan_file"),
+      "detects stale REPLAN when all tasks are done",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 6. Metrics ledger corrupt ───────────────────────────────────────────────
+  console.log("\n=== metrics ledger corrupt ===");
+  {
+    const { base, gsd, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Metrics Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+    // Write invalid metrics.json
+    writeFileSync(join(gsd, "metrics.json"), '{"version":2,"data":[]}');
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "metrics_ledger_corrupt"),
+      "detects corrupt metrics ledger (version != 1)",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 7. Large planning file ──────────────────────────────────────────────────
+  console.log("\n=== large planning file ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Large File Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    const sDir = writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+    // Write a 101KB .md file
+    const bigContent = "# Big File\n" + "x".repeat(101 * 1024);
+    writeFileSync(join(sDir, "BIGFILE.md"), bigContent);
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "large_planning_file"),
+      "detects large planning file over 100KB",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 8. Future timestamp ─────────────────────────────────────────────────────
+  console.log("\n=== future timestamp ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Timestamp Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    const sDir = writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [x] **T01: Task** `est:10m`\n  Done.\n");
+    // completed_at is 2 days in the future
+    const futureDate = new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString();
+    writeFileSync(
+      join(sDir, "tasks", "T01-SUMMARY.md"),
+      `---\nstatus: done\ncompleted_at: ${futureDate}\n---\n# T01\nDone.\n`,
+    );
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(
+      result.issues.some(i => i.code === "future_timestamp"),
+      "detects future completed_at timestamp",
+    );
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 9. JSON output format ───────────────────────────────────────────────────
+  console.log("\n=== JSON output format ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: JSON Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    const json = formatDoctorReportJson(result);
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      parsed = null;
+    }
+
+    assertTrue(parsed !== null, "formatDoctorReportJson produces valid JSON");
+    assertTrue(typeof (parsed as Record<string, unknown>)?.ok === "boolean", "JSON has ok field");
+    assertTrue(Array.isArray((parsed as Record<string, unknown>)?.issues), "JSON has issues array");
+    assertTrue(Array.isArray((parsed as Record<string, unknown>)?.fixesApplied), "JSON has fixesApplied array");
+    assertTrue(typeof (parsed as Record<string, unknown>)?.generatedAt === "string", "JSON has generatedAt field");
+    assertTrue(typeof (parsed as Record<string, unknown>)?.summary === "object", "JSON has summary object");
+
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 10. Dry-run mode ────────────────────────────────────────────────────────
+  console.log("\n=== dry-run mode ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Dry Run Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    const sDir = writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [x] **T01: Task** `est:10m`\n  Done.\n");
+
+    const result = await runGSDDoctor(base, { fix: true, dryRun: true });
+    // In dry-run mode, no actual files should be created
+    assertTrue(!existsSync(join(sDir, "S01-SUMMARY.md")), "dry-run does not create slice summary");
+    assertTrue(
+      result.fixesApplied.some(f => f.startsWith("[dry-run]")),
+      "dry-run mode reports would-fix entries",
+    );
+
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 11. Per-check timing ─────────────────────────────────────────────────────
+  console.log("\n=== per-check timing ===");
+  {
+    const { base, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: Timing Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+
+    const result = await runGSDDoctor(base, { fix: false });
+    assertTrue(result.timing !== undefined, "report includes timing");
+    assertTrue(typeof result.timing?.git === "number", "timing.git is a number");
+    assertTrue(typeof result.timing?.runtime === "number", "timing.runtime is a number");
+    assertTrue(typeof result.timing?.environment === "number", "timing.environment is a number");
+    assertTrue(typeof result.timing?.gsdState === "number", "timing.gsdState is a number");
+
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  // ── 12. Doctor history ───────────────────────────────────────────────────────
+  console.log("\n=== doctor history ===");
+  {
+    const { base, gsd, mDir } = makeBase();
+    writeRoadmap(mDir, `# M001: History Test\n\n## Slices\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+    writeSlice(mDir, "S01", "# S01: Slice\n\n**Goal:** G\n**Demo:** D\n\n## Tasks\n- [ ] **T01: Task** `est:10m`\n  Pending.\n");
+
+    await runGSDDoctor(base, { fix: false });
+
+    const historyPath = join(gsd, "doctor-history.jsonl");
+    assertTrue(existsSync(historyPath), "doctor-history.jsonl is created after run");
+
+    const { readDoctorHistory } = await import("../doctor.js");
+    const history = await readDoctorHistory(base);
+    assertTrue(history.length >= 1, "history has at least one entry");
+    assertTrue(typeof history[0]?.ts === "string", "history entry has ts field");
+    assertTrue(typeof history[0]?.ok === "boolean", "history entry has ok field");
+    assertTrue(typeof history[0]?.errors === "number", "history entry has errors count");
+    assertTrue(Array.isArray(history[0]?.codes), "history entry has codes array");
+
+    rmSync(base, { recursive: true, force: true });
+  }
+
+  report();
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

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

@@ -11,6 +11,7 @@ import {
   getMainBranch,
   getSliceBranchName,
   parseSliceBranch,
+  resolveProjectRoot,
   setActiveMilestoneId,
   SLICE_BRANCH_RE,
 } from "../worktree.ts";
@@ -165,6 +166,52 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ── detectWorktreeName: symlink-resolved paths ───────────────────────────
+  console.log("\n=== detectWorktreeName (symlink-resolved paths) ===");
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
+    "M001",
+    "detects milestone in symlink-resolved path",
+  );
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/abc123/worktrees/M002/subdir"),
+    "M002",
+    "detects milestone with trailing subdir in symlink-resolved path",
+  );
+  assertEq(
+    detectWorktreeName("/Users/fran/.gsd/projects/abc123"),
+    null,
+    "returns null for project root without worktrees segment",
+  );
+  assertEq(
+    detectWorktreeName("/foo/.gsd/worktrees/M001"),
+    "M001",
+    "still detects direct layout path",
+  );
+
+  // ── resolveProjectRoot: symlink-resolved paths ──────────────────────────
+  console.log("\n=== resolveProjectRoot (symlink-resolved paths) ===");
+  assertEq(
+    resolveProjectRoot("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
+    "/Users/fran",
+    "resolves to user home for symlink-resolved path",
+  );
+  assertEq(
+    resolveProjectRoot("/foo/.gsd/worktrees/M001"),
+    "/foo",
+    "still resolves direct layout path",
+  );
+  assertEq(
+    resolveProjectRoot("/some/repo"),
+    "/some/repo",
+    "returns unchanged for non-worktree path",
+  );
+  assertEq(
+    resolveProjectRoot("/data/.gsd/projects/deadbeef/worktrees/M003/nested"),
+    "/data",
+    "resolves correctly with nested subdirs after worktree name",
+  );
+
   rmSync(base, { recursive: true, force: true });
   report();
 }

package/src/resources/extensions/gsd/worktree.ts

@@ -67,40 +67,60 @@ export function captureIntegrationBranch(basePath: string, milestoneId: string,
 
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
 
+/**
+ * Find the worktrees segment in a path, supporting both direct
+ * (`/.gsd/worktrees/`) and symlink-resolved (`/.gsd/projects/<hash>/worktrees/`)
+ * layouts.  When `.gsd` is a symlink to `~/.gsd/projects/<hash>`, resolved
+ * paths contain the intermediate `projects/<hash>/` segment that the old
+ * single-marker check missed.
+ */
+function findWorktreeSegment(normalizedPath: string): { gsdIdx: number; afterWorktrees: number } | null {
+  // Direct layout: /.gsd/worktrees/<name>
+  const directMarker = "/.gsd/worktrees/";
+  const idx = normalizedPath.indexOf(directMarker);
+  if (idx !== -1) {
+    return { gsdIdx: idx, afterWorktrees: idx + directMarker.length };
+  }
+  // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/<name>
+  const symlinkRe = /\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//;
+  const match = normalizedPath.match(symlinkRe);
+  if (match && match.index !== undefined) {
+    return { gsdIdx: match.index, afterWorktrees: match.index + match[0].length };
+  }
+  return null;
+}
+
 /**
  * Detect the active worktree name from the current working directory.
  * Returns null if not inside a GSD worktree (.gsd/worktrees/<name>/).
  */
 export function detectWorktreeName(basePath: string): string | null {
   const normalizedPath = basePath.replaceAll("\\", "/");
-  const marker = "/.gsd/worktrees/";
-  const idx = normalizedPath.indexOf(marker);
-  if (idx === -1) return null;
-  const afterMarker = normalizedPath.slice(idx + marker.length);
+  const seg = findWorktreeSegment(normalizedPath);
+  if (!seg) return null;
+  const afterMarker = normalizedPath.slice(seg.afterWorktrees);
   const name = afterMarker.split("/")[0];
   return name || null;
 }
 
 /**
  * Resolve the project root from a path that may be inside a worktree.
- * If the path contains `/.gsd/worktrees/<name>/`, returns the portion
- * before `/.gsd/`. Otherwise returns the input unchanged.
+ * If the path contains a worktrees segment, returns the portion before
+ * `/.gsd/`. Otherwise returns the input unchanged.
  *
  * Use this in commands that call `process.cwd()` to ensure they always
  * operate against the real project root, not a worktree subdirectory.
  */
 export function resolveProjectRoot(basePath: string): string {
   const normalizedPath = basePath.replaceAll("\\", "/");
-  const marker = "/.gsd/worktrees/";
-  const idx = normalizedPath.indexOf(marker);
-  if (idx === -1) return basePath;
-  // Return the original path up to the .gsd/ marker (un-normalized)
-  // Account for potential OS-specific separators
+  const seg = findWorktreeSegment(normalizedPath);
+  if (!seg) return basePath;
+  // Return the original path up to the /.gsd/ boundary
   const sep = basePath.includes("\\") ? "\\" : "/";
-  const markerOs = `${sep}.gsd${sep}worktrees${sep}`;
-  const idxOs = basePath.indexOf(markerOs);
-  if (idxOs !== -1) return basePath.slice(0, idxOs);
-  return basePath.slice(0, idx);
+  const gsdMarker = `${sep}.gsd${sep}`;
+  const gsdIdx = basePath.indexOf(gsdMarker);
+  if (gsdIdx !== -1) return basePath.slice(0, gsdIdx);
+  return basePath.slice(0, seg.gsdIdx);
 }
 
 /**

package/src/resources/extensions/subagent/index.ts

@@ -452,7 +452,7 @@ async function runSingleAgent(
 
 async function runSingleAgentInCmuxSplit(
 	cmuxClient: CmuxClient,
-	direction: "right" | "down",
+	directionOrSurfaceId: "right" | "down" | string,
 	defaultCwd: string,
 	agents: AgentConfig[],
 	agentName: string,
@@ -503,7 +503,12 @@ async function runSingleAgentInCmuxSplit(
 		const stdoutPath = path.join(tmpOutputDir, "stdout.jsonl");
 		const stderrPath = path.join(tmpOutputDir, "stderr.log");
 		const exitPath = path.join(tmpOutputDir, "exit.code");
-		const cmuxSurfaceId = await cmuxClient.createSplit(direction);
+		// Accept either a pre-created surface ID or a direction to create a new split
+		const isDirection = directionOrSurfaceId === "right" || directionOrSurfaceId === "down"
+			|| directionOrSurfaceId === "left" || directionOrSurfaceId === "up";
+		const cmuxSurfaceId = isDirection
+			? await cmuxClient.createSplit(directionOrSurfaceId as "right" | "down" | "left" | "up")
+			: directionOrSurfaceId;
 		if (!cmuxSurfaceId) {
 			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
 		}
@@ -806,12 +811,16 @@ export default function (pi: ExtensionAPI) {
 				const MAX_RETRIES = 1; // Retry failed tasks once
 				const batchId = crypto.randomUUID();
 				const batchSize = params.tasks.length;
+				// Pre-create a grid layout for cmux splits so agents get a clean tiled arrangement
+				const gridSurfaces = cmuxSplitsEnabled
+					? await cmuxClient.createGridLayout(Math.min(batchSize, MAX_CONCURRENCY))
+					: [];
 				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
 					const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
 					const runTask = () => cmuxSplitsEnabled
 						? runSingleAgentInCmuxSplit(
 							cmuxClient,
-							index % 2 === 0 ? "right" : "down",
+							gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"),
 							ctx.cwd,
 							agents,
 							t.agent,