gsd-pi 2.80.0-dev.42bd34838 → 2.80.0-dev.488219eb6

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,
@@ -459,19 +476,47 @@ export class WorktreeResolver {
         phase: "auto-commit-failed",
         error: err instanceof Error ? err.message : String(err),
       });
+      ctx.notify(
+        `Auto-commit before exiting ${milestoneId} failed: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`,
+        "warning",
+      );
+    }
+
+    if (this.s.originalBasePath) {
+      try {
+        process.chdir(this.s.originalBasePath);
+      } catch (err) {
+        debugLog("WorktreeResolver", {
+          action: "exitMilestone",
+          milestoneId,
+          phase: "pre-teardown-chdir-failed",
+          originalBasePath: this.s.originalBasePath,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        ctx.notify(
+          `Could not leave milestone worktree before cleanup: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`,
+          "warning",
+        );
+      }
     }
 
+    let teardownFailed = false;
     try {
       this.deps.teardownAutoWorktree(this.s.originalBasePath, milestoneId, {
         preserveBranch: opts?.preserveBranch ?? false,
       });
     } catch (err) {
+      teardownFailed = true;
       debugLog("WorktreeResolver", {
         action: "exitMilestone",
         milestoneId,
         phase: "teardown-failed",
         error: err instanceof Error ? err.message : String(err),
       });
+      ctx.notify(
+        `Worktree cleanup failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Branch ${this.deps.autoWorktreeBranch(milestoneId)} is preserved for recovery.`,
+        "warning",
+      );
     }
 
     this.restoreToProjectRoot();
@@ -481,7 +526,12 @@ export class WorktreeResolver {
       result: "done",
       basePath: this.s.basePath,
     });
-    ctx.notify(`Exited worktree for ${milestoneId}`, "info");
+    ctx.notify(
+      teardownFailed
+        ? `Worktree exit for ${milestoneId} needs manual cleanup.`
+        : `Exited worktree for ${milestoneId}`,
+      teardownFailed ? "warning" : "info",
+    );
   }
 
   // ── Merge and Exit ─────────────────────────────────────────────────────
@@ -824,16 +874,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 +965,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 +995,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/skills/create-gsd-extension/templates/templates.test.ts

@@ -3,56 +3,102 @@
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, dirname, relative } from "node:path";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import ts from "typescript";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const skillRoot = join(__dirname, "..");
-
-function walk(dir: string): string[] {
-	const out: string[] = [];
-	for (const entry of readdirSync(dir)) {
-		const full = join(dir, entry);
-		if (statSync(full).isDirectory()) {
-			out.push(...walk(full));
-		} else {
-			out.push(full);
-		}
+
+const extensionApiStubs = `
+declare module "@gsd/pi-coding-agent" {
+	export interface ExtensionContext {
+		hasUI: boolean;
+		sessionManager: { getBranch(): Array<{ type: string; message: { role?: string; toolName?: string; details?: unknown } }> };
+		ui: { notify(message: string, level: string): void; custom<T>(view: unknown): Promise<T> };
+	}
+	export interface ExtensionAPI {
+		on(event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown): void;
+		registerTool(tool: Record<string, unknown>): void;
+		registerCommand(name: string, command: {
+			description: string;
+			handler: (args: string, ctx: ExtensionContext) => unknown;
+		}): void;
 	}
-	return out;
+}
+
+declare module "@sinclair/typebox" {
+	export const Type: {
+		Object(shape: Record<string, unknown>): unknown;
+		Optional(schema: unknown): unknown;
+		String(options?: Record<string, unknown>): unknown;
+		Number(options?: Record<string, unknown>): unknown;
+	};
+}
+
+declare module "@gsd/pi-ai" {
+	export function StringEnum<T extends readonly string[]>(values: T): unknown;
+}
+
+declare module "@gsd/pi-tui" {
+	export class Text {
+		constructor(text: string, x: number, y: number);
+	}
+	export function truncateToWidth(text: string, width: number): string;
+	export function matchesKey(data: string, key: string): boolean;
+	export const Key: { escape: string };
+}
+`;
+
+function renderTemplate(template: string): string {
+	return template
+		.replaceAll("{{EXTENSION_NAME}}", "Sample Extension")
+		.replaceAll("{{DESCRIPTION}}", "Sample extension")
+		.replaceAll("{{CAPABILITIES_LIST}}", "- sample")
+		.replaceAll("{{tool_name}}", "sample_tool")
+		.replaceAll("{{Tool Label}}", "Sample Tool")
+		.replaceAll("{{Tool description for LLM}}", "Sample tool description")
+		.replaceAll("{{command_name}}", "sample")
+		.replaceAll("{{Command description}}", "Sample command")
+		.replaceAll("{{ItemType}}", "SampleItem")
+		.replaceAll("{{ToolDetails}}", "SampleToolDetails")
+		.replaceAll("{{Description for LLM}}", "Sample stateful tool description")
+		.replaceAll("{{items}}", "items")
+		.replaceAll("{{Items}}", "Items");
 }
 
 describe("extension templates use @gsd/* imports", () => {
 	const templates = ["extension-skeleton.ts", "stateful-tool-skeleton.ts"];
 
 	for (const template of templates) {
-		it(`${template} uses @gsd/pi-coding-agent (not @mariozechner)`, () => {
-			const content = readFileSync(join(__dirname, template), "utf-8");
-			assert.ok(content.includes("@gsd/pi-coding-agent"), `Expected @gsd/pi-coding-agent import in ${template}`);
-			assert.ok(!content.includes("@mariozechner/"), `Found stale @mariozechner/ import in ${template}`);
-		});
-	}
+		it(`${template} renders as a compilable extension module`, () => {
+			const dir = mkdtempSync(join(tmpdir(), "create-gsd-extension-template-"));
+			try {
+				const stubsPath = join(dir, "extension-api-stubs.d.ts");
+				const renderedPath = join(dir, template);
+				writeFileSync(stubsPath, extensionApiStubs, "utf-8");
+				const rendered = renderTemplate(readFileSync(join(__dirname, template), "utf-8"));
+				writeFileSync(renderedPath, rendered, "utf-8");
 
-	it("extension-skeleton.ts uses @gsd/pi-ai for StringEnum", () => {
-		const content = readFileSync(join(__dirname, "extension-skeleton.ts"), "utf-8");
-		assert.ok(content.includes("@gsd/pi-ai"), "Expected @gsd/pi-ai import");
-	});
-
-	it("stateful-tool-skeleton.ts uses @gsd/pi-tui", () => {
-		const content = readFileSync(join(__dirname, "stateful-tool-skeleton.ts"), "utf-8");
-		assert.ok(content.includes("@gsd/pi-tui"), "Expected @gsd/pi-tui import");
-	});
-
-	it("no @mariozechner/ references anywhere in create-gsd-extension/", () => {
-		const offenders: string[] = [];
-		for (const file of walk(skillRoot)) {
-			if (file.endsWith("templates.test.ts")) continue;
-			const content = readFileSync(file, "utf-8");
-			if (content.includes("@mariozechner/")) {
-				offenders.push(relative(skillRoot, file));
+				const program = ts.createProgram([stubsPath, renderedPath], {
+					allowJs: false,
+					esModuleInterop: true,
+					module: ts.ModuleKind.NodeNext,
+					moduleResolution: ts.ModuleResolutionKind.NodeNext,
+					noEmit: true,
+					skipLibCheck: true,
+					strict: false,
+					target: ts.ScriptTarget.ES2022,
+				});
+				const diagnostics = ts.getPreEmitDiagnostics(program).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+				assert.deepEqual(
+					diagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")),
+					[],
+				);
+			} finally {
+				rmSync(dir, { recursive: true, force: true });
 			}
-		}
-		assert.deepEqual(offenders, [], `Stale @mariozechner/ references found in: ${offenders.join(", ")}`);
-	});
+		});
+	}
 });