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

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

@@ -289,10 +289,17 @@ export class CmuxClient {
   }
 
   async createSplit(direction: "right" | "down" | "left" | "up"): Promise<string | null> {
+    return this.createSplitFrom(this.config.surfaceId, direction);
+  }
+
+  async createSplitFrom(
+    sourceSurfaceId: string | undefined,
+    direction: "right" | "down" | "left" | "up",
+  ): Promise<string | null> {
     if (!this.config.splits) return null;
     const before = new Set(await this.listSurfaceIds());
     const args = ["new-split", direction];
-    const scopedArgs = this.appendSurface(this.appendWorkspace(args), this.config.surfaceId);
+    const scopedArgs = this.appendSurface(this.appendWorkspace(args), sourceSurfaceId);
     await this.runAsync(scopedArgs);
     const after = await this.listSurfaceIds();
     for (const id of after) {
@@ -301,6 +308,55 @@ export class CmuxClient {
     return null;
   }
 
+  /**
+   * Create a grid of surfaces for parallel agent execution.
+   *
+   * Layout strategy (gsd stays in the original surface):
+   *   1 agent:  [gsd | A]
+   *   2 agents: [gsd | A]
+   *             [    | B]
+   *   3 agents: [gsd | A]
+   *             [ C  | B]
+   *   4 agents: [gsd | A]
+   *             [ C  | B]  (D splits from B downward)
+   *             [    | D]
+   *
+   * Returns surface IDs in order, or empty array on failure.
+   */
+  async createGridLayout(count: number): Promise<string[]> {
+    if (!this.config.splits || count <= 0) return [];
+    const surfaces: string[] = [];
+
+    // First split: create right column from the gsd surface
+    const rightCol = await this.createSplitFrom(this.config.surfaceId, "right");
+    if (!rightCol) return [];
+    surfaces.push(rightCol);
+    if (count === 1) return surfaces;
+
+    // Second split: split right column down → bottom-right
+    const bottomRight = await this.createSplitFrom(rightCol, "down");
+    if (!bottomRight) return surfaces;
+    surfaces.push(bottomRight);
+    if (count === 2) return surfaces;
+
+    // Third split: split gsd surface down → bottom-left
+    const bottomLeft = await this.createSplitFrom(this.config.surfaceId, "down");
+    if (!bottomLeft) return surfaces;
+    surfaces.push(bottomLeft);
+    if (count === 3) return surfaces;
+
+    // Fourth+: split subsequent surfaces down from the last created
+    let lastSurface = bottomRight;
+    for (let i = 3; i < count; i++) {
+      const next = await this.createSplitFrom(lastSurface, "down");
+      if (!next) break;
+      surfaces.push(next);
+      lastSurface = next;
+    }
+
+    return surfaces;
+  }
+
   async sendSurface(surfaceId: string, text: string): Promise<boolean> {
     const payload = text.endsWith("\n") ? text : `${text}\n`;
     const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);

package/src/resources/extensions/gsd/auto-loop.ts

@@ -787,7 +787,7 @@ export async function autoLoop(
           (m: { status: string }) =>
             m.status !== "complete" && m.status !== "parked",
         );
-        if (incomplete.length === 0) {
+        if (incomplete.length === 0 && state.registry.length > 0) {
           // All milestones complete — merge milestone branch before stopping
           if (s.currentMilestoneId) {
             deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
@@ -804,6 +804,18 @@ export async function autoLoop(
             "success",
           );
           await deps.stopAuto(ctx, pi, "All milestones complete");
+        } else if (incomplete.length === 0 && state.registry.length === 0) {
+          // Empty registry — no milestones visible, likely a path resolution bug
+          const diag = `basePath=${s.basePath}, phase=${state.phase}`;
+          ctx.ui.notify(
+            `No milestones visible in current scope. Possible path resolution issue.\n   Diagnostic: ${diag}`,
+            "error",
+          );
+          await deps.stopAuto(
+            ctx,
+            pi,
+            `No milestones found — check basePath resolution`,
+          );
         } else if (state.phase === "blocked") {
           const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
           await deps.stopAuto(ctx, pi, blockerMsg);

package/src/resources/extensions/gsd/auto-start.ts

@@ -429,10 +429,16 @@ export async function bootstrapAutoSession(
     s.originalBasePath = base;
 
     const isUnderGsdWorktrees = (p: string): boolean => {
+      // Direct layout: /.gsd/worktrees/
       const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
       if (p.includes(marker)) return true;
       const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
-      return p.endsWith(worktreesSuffix);
+      if (p.endsWith(worktreesSuffix)) return true;
+      // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+      const symlinkRe = new RegExp(
+        `\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees(?:\\${pathSep}|$)`,
+      );
+      return symlinkRe.test(p);
     };
 
     if (

package/src/resources/extensions/gsd/auto-worktree-sync.ts

@@ -153,9 +153,18 @@ export function checkResourcesStale(
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base: string): string {
-  const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-  const idx = base.indexOf(marker);
-  if (idx === -1) return base;
+  // Direct layout: /.gsd/worktrees/
+  const directMarker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
+  let idx = base.indexOf(directMarker);
+  if (idx === -1) {
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+    const symlinkRe = new RegExp(
+      `\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees\\${pathSep}`,
+    );
+    const match = base.match(symlinkRe);
+    if (!match || match.index === undefined) return base;
+    idx = match.index;
+  }
 
   // base is inside .gsd/worktrees/<something> — extract the project root
   const projectRoot = base.slice(0, idx);

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

@@ -59,8 +59,17 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  */
 export function resolveCapturesPath(basePath: string): string {
   const resolved = resolve(basePath);
+  // Direct layout: /.gsd/worktrees/
   const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  const idx = resolved.indexOf(worktreeMarker);
+  let idx = resolved.indexOf(worktreeMarker);
+  if (idx === -1) {
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
+    const symlinkRe = new RegExp(
+      `\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`,
+    );
+    const match = resolved.match(symlinkRe);
+    if (match && match.index !== undefined) idx = match.index;
+  }
   if (idx !== -1) {
     // basePath is inside a worktree — resolve to project root
     const projectRoot = resolved.slice(0, idx);

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -15,6 +15,7 @@ import { appendOverride, appendKnowledge } from "./files.js";
 import {
   formatDoctorIssuesForPrompt,
   formatDoctorReport,
+  formatDoctorReportJson,
   runGSDDoctor,
   selectDoctorScope,
   filterDoctorIssues,
@@ -43,16 +44,30 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined,
 
 export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const trimmed = args.trim();
-  const parts = trimmed ? trimmed.split(/\s+/) : [];
+  // Extract flags before positional parsing
+  const jsonMode = trimmed.includes("--json");
+  const dryRun = trimmed.includes("--dry-run");
+  const includeBuild = trimmed.includes("--build");
+  const includeTests = trimmed.includes("--test");
+  const stripped = trimmed.replace(/--json|--dry-run|--build|--test/g, "").trim();
+  const parts = stripped ? stripped.split(/\s+/) : [];
   const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor";
   const requestedScope = mode === "doctor" ? parts[0] : parts[1];
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
   const report = await runGSDDoctor(projectRoot(), {
-    fix: mode === "fix" || mode === "heal",
+    fix: mode === "fix" || mode === "heal" || dryRun,
+    dryRun,
     scope: effectiveScope,
+    includeBuild,
+    includeTests,
   });
 
+  if (jsonMode) {
+    ctx.ui.notify(formatDoctorReportJson(report), "info");
+    return;
+  }
+
   const reportText = formatDoctorReport(report, {
     scope: effectiveScope,
     includeWarnings: mode === "audit",

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

@@ -159,7 +159,7 @@ async function guardRemoteSession(
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|update",
+    description: "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|capture|triage|dispatch|history|undo|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -210,7 +210,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "templates", desc: "List available workflow templates" },
         { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
       ];
+      const hasTrailingSpace = prefix.endsWith(" ");
       const parts = prefix.trim().split(/\s+/);
+      if (hasTrailingSpace && parts.length >= 1) {
+        parts.push("");
+      }
 
       if (parts.length <= 1) {
         return subcommands
@@ -509,6 +513,10 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           { cmd: "fix", desc: "Auto-fix detected issues" },
           { cmd: "heal", desc: "AI-driven deep healing" },
           { cmd: "audit", desc: "Run health audit without fixing" },
+          { cmd: "--dry-run", desc: "Show what --fix would change without applying" },
+          { cmd: "--json", desc: "Output report as JSON (CI/tooling friendly)" },
+          { cmd: "--build", desc: "Include slow build health check (npm run build)" },
+          { cmd: "--test", desc: "Include slow test health check (npm test)" },
         ];
 
         if (parts.length <= 2) {
@@ -536,6 +544,18 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((p) => ({ value: `dispatch ${p.cmd}`, label: p.cmd, description: p.desc }));
       }
 
+      if (parts[0] === "rate" && parts.length <= 2) {
+        const tierPrefix = parts[1] ?? "";
+        const tiers = [
+          { cmd: "over", desc: "Model was overqualified for this task" },
+          { cmd: "ok", desc: "Model was appropriate for this task" },
+          { cmd: "under", desc: "Model was underqualified for this task" },
+        ];
+        return tiers
+          .filter((t) => t.cmd.startsWith(tierPrefix))
+          .map((t) => ({ value: `rate ${t.cmd}`, label: t.cmd, description: t.desc }));
+      }
+
       return [];
     },
 

package/src/resources/extensions/gsd/doctor-checks.ts

@@ -657,6 +657,81 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — external state check failed
   }
+
+  // ── Metrics ledger integrity ───────────────────────────────────────────
+  try {
+    const metricsPath = join(root, "metrics.json");
+    if (existsSync(metricsPath)) {
+      try {
+        const raw = readFileSync(metricsPath, "utf-8");
+        const ledger = JSON.parse(raw);
+        if (ledger.version !== 1 || !Array.isArray(ledger.units)) {
+          issues.push({
+            severity: "warning",
+            code: "metrics_ledger_corrupt",
+            scope: "project",
+            unitId: "project",
+            message: "metrics.json has an unexpected structure (version !== 1 or units is not an array) — metrics data may be unreliable",
+            file: ".gsd/metrics.json",
+            fixable: false,
+          });
+        }
+      } catch {
+        issues.push({
+          severity: "warning",
+          code: "metrics_ledger_corrupt",
+          scope: "project",
+          unitId: "project",
+          message: "metrics.json is not valid JSON — metrics data may be corrupt",
+          file: ".gsd/metrics.json",
+          fixable: false,
+        });
+      }
+    }
+  } catch {
+    // Non-fatal — metrics check failed
+  }
+
+  // ── Large planning file detection ──────────────────────────────────────
+  // Files over 100KB can cause LLM context pressure. Report the worst offenders.
+  try {
+    const MAX_FILE_BYTES = 100 * 1024; // 100KB
+    const milestonesPath = milestonesDir(basePath);
+    if (existsSync(milestonesPath)) {
+      const largeFiles: Array<{ path: string; sizeKB: number }> = [];
+      function scanForLargeFiles(dir: string, depth = 0): void {
+        if (depth > 6) return;
+        try {
+          for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            try {
+              const s = statSync(full);
+              if (s.isDirectory()) { scanForLargeFiles(full, depth + 1); continue; }
+              if (entry.endsWith(".md") && s.size > MAX_FILE_BYTES) {
+                largeFiles.push({ path: full.replace(basePath + "/", ""), sizeKB: Math.round(s.size / 1024) });
+              }
+            } catch { /* skip entry */ }
+          }
+        } catch { /* skip dir */ }
+      }
+      scanForLargeFiles(milestonesPath);
+      if (largeFiles.length > 0) {
+        largeFiles.sort((a, b) => b.sizeKB - a.sizeKB);
+        const worst = largeFiles[0]!;
+        issues.push({
+          severity: "warning",
+          code: "large_planning_file",
+          scope: "project",
+          unitId: "project",
+          message: `${largeFiles.length} planning file(s) exceed 100KB — largest: ${worst.path} (${worst.sizeKB}KB). Large files cause LLM context pressure.`,
+          file: worst.path,
+          fixable: false,
+        });
+      }
+    }
+  } catch {
+    // Non-fatal — large file scan failed
+  }
 }
 
 /**

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -407,6 +407,63 @@ function checkGitRemote(basePath: string): EnvironmentCheckResult | null {
   return { name: "git_remote", status: "ok", message: "Git remote reachable" };
 }
 
+/**
+ * Check if the project build passes (opt-in slow check, use --build flag).
+ * Runs npm run build and reports failure as env_build.
+ */
+function checkBuildHealth(basePath: string): EnvironmentCheckResult | null {
+  const pkgPath = join(basePath, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const buildScript = pkg.scripts?.build;
+    if (!buildScript) return null;
+
+    const result = tryExec("npm run build 2>&1", basePath);
+    if (result === null) {
+      return {
+        name: "build",
+        status: "error",
+        message: "Build failed — npm run build exited non-zero",
+        detail: "Fix build errors before dispatching work",
+      };
+    }
+    return { name: "build", status: "ok", message: "Build passes" };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if tests pass (opt-in slow check, use --test flag).
+ * Runs npm test and reports failures as env_test.
+ */
+function checkTestHealth(basePath: string): EnvironmentCheckResult | null {
+  const pkgPath = join(basePath, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const testScript = pkg.scripts?.test;
+    // Skip if no test script or the default placeholder
+    if (!testScript || testScript.includes("no test specified")) return null;
+
+    const result = tryExec("npm test 2>&1", basePath);
+    if (result === null) {
+      return {
+        name: "test",
+        status: "warning",
+        message: "Tests failing — npm test exited non-zero",
+        detail: "Fix failing tests before shipping",
+      };
+    }
+    return { name: "test", status: "ok", message: "Tests pass" };
+  } catch {
+    return null;
+  }
+}
+
 // ── Public API ─────────────────────────────────────────────────────────────
 
 /**
@@ -454,6 +511,26 @@ export function runFullEnvironmentChecks(basePath: string): EnvironmentCheckResu
   return results;
 }
 
+/**
+ * Run slow opt-in checks (build and/or test).
+ * These are never run on the pre-dispatch gate — only on explicit /gsd doctor --build/--test.
+ */
+export function runSlowEnvironmentChecks(
+  basePath: string,
+  options?: { includeBuild?: boolean; includeTests?: boolean },
+): EnvironmentCheckResult[] {
+  const results: EnvironmentCheckResult[] = [];
+  if (options?.includeBuild) {
+    const buildCheck = checkBuildHealth(basePath);
+    if (buildCheck) results.push(buildCheck);
+  }
+  if (options?.includeTests) {
+    const testCheck = checkTestHealth(basePath);
+    if (testCheck) results.push(testCheck);
+  }
+  return results;
+}
+
 /**
  * Convert environment check results to DoctorIssue format for the doctor pipeline.
  */
@@ -477,12 +554,16 @@ export function environmentResultsToDoctorIssues(results: EnvironmentCheckResult
 export async function checkEnvironmentHealth(
   basePath: string,
   issues: DoctorIssue[],
-  options?: { includeRemote?: boolean },
+  options?: { includeRemote?: boolean; includeBuild?: boolean; includeTests?: boolean },
 ): Promise<void> {
   const results = options?.includeRemote
     ? runFullEnvironmentChecks(basePath)
     : runEnvironmentChecks(basePath);
 
+  if (options?.includeBuild || options?.includeTests) {
+    results.push(...runSlowEnvironmentChecks(basePath, options));
+  }
+
   issues.push(...environmentResultsToDoctorIssues(results));
 }
 

package/src/resources/extensions/gsd/doctor-format.ts

@@ -76,3 +76,23 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
     return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
   }).join("\n");
 }
+
+/**
+ * Serialize a doctor report to JSON — suitable for CI/tooling integration.
+ * Usage: /gsd doctor --json
+ */
+export function formatDoctorReportJson(report: DoctorReport): string {
+  return JSON.stringify(
+    {
+      ok: report.ok,
+      basePath: report.basePath,
+      generatedAt: new Date().toISOString(),
+      summary: summarizeDoctorIssues(report.issues),
+      issues: report.issues,
+      fixesApplied: report.fixesApplied,
+      ...(report.timing ? { timing: report.timing } : {}),
+    },
+    null,
+    2,
+  );
+}

package/src/resources/extensions/gsd/doctor-types.ts

@@ -53,7 +53,20 @@ export type DoctorIssueCode =
   | "stranded_lock_directory"
   // Git / worktree integrity checks
   | "integration_branch_missing"
-  | "worktree_directory_orphaned";
+  | "worktree_directory_orphaned"
+  // GSD state structural checks
+  | "circular_slice_dependency"
+  | "orphaned_slice_directory"
+  | "duplicate_task_id"
+  | "task_file_not_in_plan"
+  | "stale_replan_file"
+  | "future_timestamp"
+  // Runtime data integrity
+  | "metrics_ledger_corrupt"
+  | "large_planning_file"
+  // Slow environment checks (opt-in via --build / --test flags)
+  | "env_build"
+  | "env_test";
 
 /**
  * Issue codes that represent expected completion-transition states.
@@ -83,6 +96,8 @@ export interface DoctorReport {
   basePath: string;
   issues: DoctorIssue[];
   fixesApplied: string[];
+  /** Per-domain check durations in milliseconds. Present on explicit /gsd doctor runs. */
+  timing?: { git: number; runtime: number; environment: number; gsdState: number };
 }
 
 export interface DoctorSummary {