gsd-pi 2.80.0-dev.cf9433f56 → 2.80.0-dev.d4fc28e6b

package/src/resources/extensions/gsd/workflow-protocol.ts

@@ -0,0 +1,160 @@
+// Project/App: GSD-2
+// File Purpose: Shared capped workflow protocol and doctor-heal prompt payload helpers.
+
+const DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 4_000;
+const MIN_WORKFLOW_PROTOCOL_EXCERPT_CHARS = 1_000;
+const DEFAULT_DOCTOR_SUMMARY_CHARS = 2_400;
+const DEFAULT_DOCTOR_ISSUE_CHARS = 300;
+const DEFAULT_DOCTOR_MAX_ISSUES = 12;
+const DEFAULT_DOCTOR_ISSUES_CHARS = 4_000;
+
+export function buildWorkflowProtocolExcerpt(
+  workflow: string,
+  workflowPath: string,
+  opts: { maxChars?: number } = {},
+): string {
+  const limit = opts.maxChars ?? getWorkflowProtocolExcerptLimit();
+  const trimmed = workflow.trim();
+  const excerpt = buildPrioritizedWorkflowExcerpt(trimmed, limit);
+  const truncated = trimmed.length > limit;
+  const lines = [
+    "## GSD Workflow Protocol Excerpt",
+    `Source: \`${workflowPath}\``,
+    "",
+    excerpt,
+  ];
+  if (truncated) {
+    lines.push(
+      "",
+      "[Workflow Protocol Truncated]",
+      "The full workflow protocol remains available at the source path above. Read it only if this excerpt lacks a rule required for the dispatched task.",
+    );
+  }
+  return lines.join("\n");
+}
+
+export function buildWorkflowDispatchContent(opts: {
+  workflow: string;
+  workflowPath: string;
+  task: string;
+  maxProtocolChars?: number;
+}): string {
+  return [
+    "Read the following GSD workflow protocol excerpt and execute exactly. Use the source path for a full protocol read only if the excerpt lacks a required rule.",
+    "",
+    buildWorkflowProtocolExcerpt(opts.workflow, opts.workflowPath, { maxChars: opts.maxProtocolChars }),
+    "",
+    "## Your Task",
+    "",
+    opts.task.trim(),
+  ].join("\n");
+}
+
+export function buildDoctorHealSummary(reportText: string, opts: { maxChars?: number } = {}): string {
+  const limit = opts.maxChars ?? DEFAULT_DOCTOR_SUMMARY_CHARS;
+  const lines = reportText.split(/\r?\n/).map((line) => line.trimEnd());
+  const summaryLines = lines.filter((line) =>
+    line.length > 0 && (
+      /^#/.test(line) ||
+      /^(scope|status|summary|checks?|errors?|warnings?|fixes?|issues?)\b/i.test(line) ||
+      /doctor/i.test(line)
+    ),
+  );
+  const selected = summaryLines.length > 0 ? summaryLines : lines.filter((line) => line.trim()).slice(0, 24);
+  return capText(selected.join("\n"), limit, "Full doctor report is available in the command output; use the structured issue list below for repairs.");
+}
+
+export function buildDoctorHealIssuePayload(
+  structuredIssues: string,
+  opts: { maxIssues?: number; maxIssueChars?: number; maxChars?: number } = {},
+): string {
+  const maxIssues = opts.maxIssues ?? DEFAULT_DOCTOR_MAX_ISSUES;
+  const maxIssueChars = opts.maxIssueChars ?? DEFAULT_DOCTOR_ISSUE_CHARS;
+  const maxChars = opts.maxChars ?? DEFAULT_DOCTOR_ISSUES_CHARS;
+  const blocks = splitIssueBlocks(structuredIssues);
+  const topBlocks = blocks.slice(0, maxIssues).map((block) =>
+    capText(block, maxIssueChars, "Issue details truncated; inspect the relevant artifact before editing."),
+  );
+  if (blocks.length > maxIssues) {
+    topBlocks.push(`[${blocks.length - maxIssues} additional actionable issue(s) omitted from prompt. Re-run /gsd doctor heal after this repair pass.]`);
+  }
+  return capText(topBlocks.join("\n\n"), maxChars, "Structured issue list truncated; repair top actionable issues first and re-run doctor heal.");
+}
+
+function getWorkflowProtocolExcerptLimit(): number {
+  const raw = process.env.PI_GSD_WORKFLOW_PROTOCOL_MAX_CHARS;
+  if (!raw) return DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < MIN_WORKFLOW_PROTOCOL_EXCERPT_CHARS) {
+    return DEFAULT_WORKFLOW_PROTOCOL_EXCERPT_CHARS;
+  }
+  return Math.floor(parsed);
+}
+
+function buildPrioritizedWorkflowExcerpt(workflow: string, limit: number): string {
+  if (workflow.length <= limit) return workflow;
+  const sections = splitMarkdownSections(workflow);
+  const wanted = [
+    /^# /,
+    /^## Quick Start\b/i,
+    /^## The Hierarchy\b/i,
+    /^## The Phases\b/i,
+    /^### Phase 4: Execute\b/i,
+    /^### Phase 5: Verify\b/i,
+    /^### Observable Truths\b/i,
+    /^### Artifacts\b/i,
+    /^### Key Links\b/i,
+    /^### Phase 6: Summarize\b/i,
+    /^### Phase 7: Advance\b/i,
+  ];
+  const selected: string[] = [];
+  const used = new Set<number>();
+  for (const pattern of wanted) {
+    const index = sections.findIndex((section, sectionIndex) =>
+      !used.has(sectionIndex) && pattern.test(section.heading),
+    );
+    if (index >= 0) {
+      used.add(index);
+      selected.push(sections[index].text);
+    }
+  }
+  const body = selected.length > 0 ? selected.join("\n\n") : workflow;
+  return capText(body, limit, "Workflow protocol excerpt capped; read the source path for omitted details.");
+}
+
+function splitMarkdownSections(markdown: string): Array<{ heading: string; text: string }> {
+  const lines = markdown.split(/\r?\n/);
+  const sections: Array<{ heading: string; text: string }> = [];
+  let currentHeading = lines[0]?.startsWith("#") ? lines[0] : "# Preamble";
+  let current: string[] = [];
+  for (const line of lines) {
+    if (/^#{1,3}\s+/.test(line) && current.length > 0) {
+      sections.push({ heading: currentHeading, text: current.join("\n").trim() });
+      currentHeading = line;
+      current = [line];
+      continue;
+    }
+    if (/^#{1,3}\s+/.test(line)) currentHeading = line;
+    current.push(line);
+  }
+  if (current.length > 0) {
+    sections.push({ heading: currentHeading, text: current.join("\n").trim() });
+  }
+  return sections.filter((section) => section.text.length > 0);
+}
+
+function splitIssueBlocks(structuredIssues: string): string[] {
+  const trimmed = structuredIssues.trim();
+  if (!trimmed) return ["No structured issue details were provided."];
+  const split = trimmed.split(/\n(?=(?:#{2,6}\s+|\d+\.\s+|- \*\*|- \[[ x]\]))/i)
+    .map((block) => block.trim())
+    .filter(Boolean);
+  return split.length > 0 ? split : [trimmed];
+}
+
+function capText(text: string, limit: number, notice: string): string {
+  if (text.length <= limit) return text;
+  const suffix = `\n\n[Truncated]\n${notice}`;
+  const headBudget = Math.max(0, limit - suffix.length);
+  return `${text.slice(0, headBudget).trimEnd()}${suffix}`;
+}

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

@@ -40,6 +40,16 @@ function isSamePath(a: string, b: string): boolean {
   return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
 
+class UserNotifiedError extends Error {
+  readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "UserNotifiedError";
+    this.cause = cause;
+  }
+}
+
 // ─── Dependency Interface ──────────────────────────────────────────────────
 
 export interface WorktreeResolverDeps {
@@ -71,6 +81,13 @@ export interface WorktreeResolverDeps {
     milestoneId: string,
   ) => void;
   getCurrentBranch: (basePath: string) => string;
+  /**
+   * Force-checkout the named branch in `basePath`. Required by `_mergeBranchMode`
+   * when it discovers the working tree is not on the milestone branch — preflight
+   * stash + later operations may have switched HEAD to main, and silently skipping
+   * the merge would strand the milestone's commits.
+   */
+  checkoutBranch: (basePath: string, branch: string) => void;
   autoWorktreeBranch: (milestoneId: string) => string;
   resolveMilestoneFile: (
     basePath: string,
@@ -824,16 +841,41 @@ export class WorktreeResolver {
       const milestoneBranch = this.deps.autoWorktreeBranch(milestoneId);
 
       if (currentBranch !== milestoneBranch) {
+        // #5538-followup: previous behavior was to silently `return false`
+        // when HEAD wasn't on the milestone branch — that let the loop
+        // advance with the milestone's commits stranded on the branch (the
+        // exact failure mode reported in the test12345 repro). Attempt
+        // recovery by force-checking-out the milestone branch; if the
+        // checkout fails, throw so the caller pauses auto-mode and the user
+        // sees the failure instead of a silent merge skip.
         debugLog("WorktreeResolver", {
           action: "mergeAndExit",
           milestoneId,
           mode: "branch",
-          skipped: true,
-          reason: "not-on-milestone-branch",
+          recovery: "checkout-milestone-branch",
           currentBranch,
           milestoneBranch,
         });
-        return false;
+        try {
+          this.deps.checkoutBranch(this.s.basePath, milestoneBranch);
+        } catch (checkoutErr) {
+          const checkoutMsg = checkoutErr instanceof Error ? checkoutErr.message : String(checkoutErr);
+          ctx.notify(
+            `Cannot merge milestone ${milestoneId}: working tree is on ${currentBranch} and checkout to ${milestoneBranch} failed (${checkoutMsg}). Resolve manually and run /gsd auto to resume.`,
+            "error",
+          );
+          throw new UserNotifiedError(checkoutMsg, checkoutErr);
+        }
+
+        const reverify = this.deps.getCurrentBranch(this.s.basePath);
+        if (reverify !== milestoneBranch) {
+          const reverifyMsg = `branch checkout to ${milestoneBranch} reported success but current branch is ${reverify}`;
+          ctx.notify(
+            `Cannot merge milestone ${milestoneId}: ${reverifyMsg}. Resolve manually and run /gsd auto to resume.`,
+            "error",
+          );
+          throw new UserNotifiedError(reverifyMsg);
+        }
       }
 
       const roadmapPath = this.deps.resolveMilestoneFile(
@@ -890,7 +932,9 @@ export class WorktreeResolver {
         result: "error",
         error: msg,
       });
-      ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      if (!(err instanceof UserNotifiedError)) {
+        ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      }
       // Re-throw all errors so callers can apply their own recovery logic (#4380).
       throw err;
     }
@@ -918,6 +962,7 @@ export class WorktreeResolver {
     try {
       this.mergeAndExit(currentMilestoneId, ctx);
     } catch (err) {
+      if (err instanceof UserNotifiedError) throw err;
       // mergeAndExit emits a warning and restores state when it fails during
       // merge/cleanup. But if it throws before recovery runs (e.g., in
       // validateMilestoneId or emitJournalEvent), basePath won't be restored

package/src/resources/extensions/gsd/tests/phases-merge-error-stops-auto.test.ts

@@ -1,97 +0,0 @@
-/**
- * phases-merge-error-stops-auto.test.ts — Regression test for #2766.
- *
- * When mergeAndExit throws a non-MergeConflictError, the auto loop must
- * stop instead of continuing with unmerged work. This test verifies that
- * all catch blocks in auto/phases.ts that handle mergeAndExit errors
- * call stopAuto and return { action: "break" } for non-conflict errors.
- */
-
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, report } = createTestContext();
-
-const phasesPath = join(import.meta.dirname, "..", "auto", "phases.ts");
-const phasesSrc = readFileSync(phasesPath, "utf-8");
-
-console.log("\n=== #2766: Non-MergeConflictError stops auto mode ===");
-
-// ── Test 1: every mergeAndExit call site has a catch (mergeErr) block ──
-
-// Count all mergeAndExit catch blocks by finding "} catch (mergeErr)" patterns
-const mergeAndExitCallCount = [...phasesSrc.matchAll(/\.mergeAndExit\(/g)].length;
-const mergeErrCatchCount = [...phasesSrc.matchAll(/\} catch \(mergeErr\)/g)].length;
-assertTrue(
-  mergeErrCatchCount === mergeAndExitCallCount && mergeAndExitCallCount > 0,
-  `every mergeAndExit call site has a catch (mergeErr) block (calls=${mergeAndExitCallCount}, catches=${mergeErrCatchCount})`,
-);
-
-// ── Test 2: Every mergeErr catch block handles non-MergeConflictError ───
-
-// Find each catch block and verify it has the non-conflict error handling pattern
-const catchPattern = /\} catch \(mergeErr\) \{/g;
-let match;
-let blocksWithNonConflictHandling = 0;
-let blocksTotal = 0;
-
-while ((match = catchPattern.exec(phasesSrc)) !== null) {
-  blocksTotal++;
-  // Look at the ~800 chars after the catch to find both the MergeConflictError
-  // instanceof check AND the non-conflict handling
-  const afterCatch = phasesSrc.slice(match.index, match.index + 1200);
-
-  const hasInstanceofCheck = afterCatch.includes("instanceof MergeConflictError");
-  const hasNonConflictStop = afterCatch.includes('reason: "merge-failed"');
-  const hasStopAuto = afterCatch.includes("stopAuto");
-  const hasLogError = afterCatch.includes("logError");
-
-  if (hasInstanceofCheck && hasNonConflictStop && hasStopAuto && hasLogError) {
-    blocksWithNonConflictHandling++;
-  }
-}
-
-assertTrue(
-  blocksWithNonConflictHandling === blocksTotal && blocksTotal >= 3,
-  `all ${blocksTotal} mergeAndExit catch blocks stop auto on non-conflict errors (${blocksWithNonConflictHandling}/${blocksTotal})`,
-);
-
-// ── Test 3: Non-conflict handler returns break (does not continue) ──────
-
-// Verify the pattern: after the MergeConflictError instanceof block,
-// the non-conflict path returns { action: "break", reason: "merge-failed" }
-const mergeFailedReasons = [...phasesSrc.matchAll(/reason: "merge-failed"/g)].length;
-assertTrue(
-  mergeFailedReasons >= 3,
-  `all catch blocks return reason: "merge-failed" (found ${mergeFailedReasons}, expected >= 3)`,
-);
-
-// ── Test 4: Non-conflict handler notifies user ──────────────────────────
-
-// Each non-conflict block should call ctx.ui.notify with error severity
-const notifyErrorPattern = /Merge failed:.*Resolve and run \/gsd auto to resume/g;
-const notifyCount = [...phasesSrc.matchAll(notifyErrorPattern)].length;
-assertTrue(
-  notifyCount >= 3,
-  `all catch blocks notify user about merge failure (found ${notifyCount}, expected >= 3)`,
-);
-
-// ── Test 5: logError replaces logWarning for non-conflict merge errors ──
-
-// The old code used logWarning — verify logError is used instead
-const logWarningMergePattern = /logWarning\(.*Milestone merge failed with non-conflict error/g;
-const logWarningCount = [...phasesSrc.matchAll(logWarningMergePattern)].length;
-assertTrue(
-  logWarningCount === 0,
-  "logWarning is no longer used for non-conflict merge errors (replaced by logError)",
-);
-
-const logErrorMergePattern = /logError\(.*Milestone merge failed with non-conflict error/g;
-const logErrorCount = [...phasesSrc.matchAll(logErrorMergePattern)].length;
-assertTrue(
-  logErrorCount >= 3,
-  `logError is used for non-conflict merge errors (found ${logErrorCount}, expected >= 3)`,
-);
-
-report();