gsd-pi 2.44.0 → 2.45.0-dev.e0ee972

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

@@ -17,9 +17,9 @@ import {
 } from "../worktree.ts";
 import { readIntegrationBranch } from "../git-service.ts";
 import { _resetHasChangesCache } from "../native-git-bridge.ts";
-import { createTestContext } from './test-helpers.ts';
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
 
-const { assertEq, assertTrue, report } = createTestContext();
 
 /**
  * Normalize a path for reliable comparison on Windows CI runners.
@@ -47,56 +47,56 @@ writeFileSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLA
 run("git add .", base);
 run('git commit -m "chore: init"', base);
 
-async function main(): Promise<void> {
+describe('worktree', async () => {
 
   console.log("\n=== autoCommitCurrentBranch ===");
   // Clean — should return null
   const cleanResult = autoCommitCurrentBranch(base, "execute-task", "M001/S01/T01");
-  assertEq(cleanResult, null, "returns null for clean repo");
+  assert.deepStrictEqual(cleanResult, null, "returns null for clean repo");
 
   // Make dirty — reset the nativeHasChanges cache so the fresh dirt is detected
   _resetHasChangesCache();
   writeFileSync(join(base, "dirty.txt"), "uncommitted\n", "utf-8");
   const dirtyResult = autoCommitCurrentBranch(base, "execute-task", "M001/S01/T01");
-  assertTrue(dirtyResult !== null, "returns commit message for dirty repo");
-  assertTrue(dirtyResult!.includes("M001/S01/T01"), "commit message includes unit id");
-  assertEq(run("git status --short", base), "", "repo is clean after auto-commit");
+  assert.ok(dirtyResult !== null, "returns commit message for dirty repo");
+  assert.ok(dirtyResult!.includes("M001/S01/T01"), "commit message includes unit id");
+  assert.deepStrictEqual(run("git status --short", base), "", "repo is clean after auto-commit");
 
   console.log("\n=== getSliceBranchName ===");
-  assertEq(getSliceBranchName("M001", "S01"), "gsd/M001/S01", "branch name format correct");
-  assertEq(getSliceBranchName("M001", "S01", null), "gsd/M001/S01", "null worktree = plain branch");
-  assertEq(getSliceBranchName("M001", "S01", "my-wt"), "gsd/my-wt/M001/S01", "worktree-namespaced branch");
+  assert.deepStrictEqual(getSliceBranchName("M001", "S01"), "gsd/M001/S01", "branch name format correct");
+  assert.deepStrictEqual(getSliceBranchName("M001", "S01", null), "gsd/M001/S01", "null worktree = plain branch");
+  assert.deepStrictEqual(getSliceBranchName("M001", "S01", "my-wt"), "gsd/my-wt/M001/S01", "worktree-namespaced branch");
 
   console.log("\n=== parseSliceBranch ===");
   const plain = parseSliceBranch("gsd/M001/S01");
-  assertTrue(plain !== null, "parses plain branch");
-  assertEq(plain!.worktreeName, null, "plain branch has no worktree name");
-  assertEq(plain!.milestoneId, "M001", "plain branch milestone");
-  assertEq(plain!.sliceId, "S01", "plain branch slice");
+  assert.ok(plain !== null, "parses plain branch");
+  assert.deepStrictEqual(plain!.worktreeName, null, "plain branch has no worktree name");
+  assert.deepStrictEqual(plain!.milestoneId, "M001", "plain branch milestone");
+  assert.deepStrictEqual(plain!.sliceId, "S01", "plain branch slice");
 
   const namespaced = parseSliceBranch("gsd/feature-auth/M001/S01");
-  assertTrue(namespaced !== null, "parses worktree-namespaced branch");
-  assertEq(namespaced!.worktreeName, "feature-auth", "worktree name extracted");
-  assertEq(namespaced!.milestoneId, "M001", "namespaced branch milestone");
-  assertEq(namespaced!.sliceId, "S01", "namespaced branch slice");
+  assert.ok(namespaced !== null, "parses worktree-namespaced branch");
+  assert.deepStrictEqual(namespaced!.worktreeName, "feature-auth", "worktree name extracted");
+  assert.deepStrictEqual(namespaced!.milestoneId, "M001", "namespaced branch milestone");
+  assert.deepStrictEqual(namespaced!.sliceId, "S01", "namespaced branch slice");
 
   const invalid = parseSliceBranch("main");
-  assertEq(invalid, null, "non-slice branch returns null");
+  assert.deepStrictEqual(invalid, null, "non-slice branch returns null");
 
   const worktreeBranch = parseSliceBranch("worktree/foo");
-  assertEq(worktreeBranch, null, "worktree/ prefix is not a slice branch");
+  assert.deepStrictEqual(worktreeBranch, null, "worktree/ prefix is not a slice branch");
 
   console.log("\n=== SLICE_BRANCH_RE ===");
-  assertTrue(SLICE_BRANCH_RE.test("gsd/M001/S01"), "regex matches plain branch");
-  assertTrue(SLICE_BRANCH_RE.test("gsd/my-wt/M001/S01"), "regex matches worktree branch");
-  assertTrue(!SLICE_BRANCH_RE.test("main"), "regex rejects main");
-  assertTrue(!SLICE_BRANCH_RE.test("gsd/"), "regex rejects bare gsd/");
-  assertTrue(!SLICE_BRANCH_RE.test("worktree/foo"), "regex rejects worktree/foo");
+  assert.ok(SLICE_BRANCH_RE.test("gsd/M001/S01"), "regex matches plain branch");
+  assert.ok(SLICE_BRANCH_RE.test("gsd/my-wt/M001/S01"), "regex matches worktree branch");
+  assert.ok(!SLICE_BRANCH_RE.test("main"), "regex rejects main");
+  assert.ok(!SLICE_BRANCH_RE.test("gsd/"), "regex rejects bare gsd/");
+  assert.ok(!SLICE_BRANCH_RE.test("worktree/foo"), "regex rejects worktree/foo");
 
   console.log("\n=== detectWorktreeName ===");
-  assertEq(detectWorktreeName("/projects/myapp"), null, "no worktree in plain path");
-  assertEq(detectWorktreeName("/projects/myapp/.gsd/worktrees/feature-auth"), "feature-auth", "detects worktree name");
-  assertEq(detectWorktreeName("/projects/myapp/.gsd/worktrees/my-wt/subdir"), "my-wt", "detects worktree with subdir");
+  assert.deepStrictEqual(detectWorktreeName("/projects/myapp"), null, "no worktree in plain path");
+  assert.deepStrictEqual(detectWorktreeName("/projects/myapp/.gsd/worktrees/feature-auth"), "feature-auth", "detects worktree name");
+  assert.deepStrictEqual(detectWorktreeName("/projects/myapp/.gsd/worktrees/my-wt/subdir"), "my-wt", "detects worktree with subdir");
 
   // ═══════════════════════════════════════════════════════════════════════
   // Integration branch — facade-level tests
@@ -115,16 +115,16 @@ async function main(): Promise<void> {
     run("git add -A && git commit -m init", repo);
 
     run("git checkout -b f-123-thing", repo);
-    assertEq(getCurrentBranch(repo), "f-123-thing", "on feature branch");
+    assert.deepStrictEqual(getCurrentBranch(repo), "f-123-thing", "on feature branch");
 
     const commitsBefore = run("git rev-list --count HEAD", repo);
     captureIntegrationBranch(repo, "M001");
-    assertEq(readIntegrationBranch(repo, "M001"), "f-123-thing",
+    assert.deepStrictEqual(readIntegrationBranch(repo, "M001"), "f-123-thing",
       "captureIntegrationBranch records the current branch");
 
     // Metadata is stored in external state, not committed to git.
     const commitsAfter = run("git rev-list --count HEAD", repo);
-    assertEq(commitsAfter, commitsBefore, "captureIntegrationBranch does not create a git commit");
+    assert.deepStrictEqual(commitsAfter, commitsBefore, "captureIntegrationBranch does not create a git commit");
 
     rmSync(repo, { recursive: true, force: true });
   }
@@ -144,7 +144,7 @@ async function main(): Promise<void> {
     run("git checkout -b gsd/M001/S01", repo);
     captureIntegrationBranch(repo, "M001");
 
-    assertEq(readIntegrationBranch(repo, "M001"), null,
+    assert.deepStrictEqual(readIntegrationBranch(repo, "M001"), null,
       "capture from slice branch is a no-op");
 
     rmSync(repo, { recursive: true, force: true });
@@ -167,12 +167,12 @@ async function main(): Promise<void> {
 
     // Without milestone set, getMainBranch returns "main"
     setActiveMilestoneId(repo, null);
-    assertEq(getMainBranch(repo), "main",
+    assert.deepStrictEqual(getMainBranch(repo), "main",
       "getMainBranch returns main without milestone set");
 
     // With milestone set, getMainBranch returns feature branch
     setActiveMilestoneId(repo, "M001");
-    assertEq(getMainBranch(repo), "my-feature",
+    assert.deepStrictEqual(getMainBranch(repo), "my-feature",
       "getMainBranch returns integration branch with milestone set");
 
     rmSync(repo, { recursive: true, force: true });
@@ -180,22 +180,22 @@ async function main(): Promise<void> {
 
   // ── detectWorktreeName: symlink-resolved paths ───────────────────────────
   console.log("\n=== detectWorktreeName (symlink-resolved paths) ===");
-  assertEq(
+  assert.deepStrictEqual(
     detectWorktreeName("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
     "M001",
     "detects milestone in symlink-resolved path",
   );
-  assertEq(
+  assert.deepStrictEqual(
     detectWorktreeName("/Users/fran/.gsd/projects/abc123/worktrees/M002/subdir"),
     "M002",
     "detects milestone with trailing subdir in symlink-resolved path",
   );
-  assertEq(
+  assert.deepStrictEqual(
     detectWorktreeName("/Users/fran/.gsd/projects/abc123"),
     null,
     "returns null for project root without worktrees segment",
   );
-  assertEq(
+  assert.deepStrictEqual(
     detectWorktreeName("/foo/.gsd/worktrees/M001"),
     "M001",
     "still detects direct layout path",
@@ -211,7 +211,7 @@ async function main(): Promise<void> {
   
   // With GSD_PROJECT_ROOT env var set (layer 1 — coordinator passes it)
   process.env.GSD_PROJECT_ROOT = "/real/project";
-  assertEq(
+  assert.deepStrictEqual(
     resolveProjectRoot("/Users/fran/.gsd/projects/89e1c9ad49bf/worktrees/M001"),
     "/real/project",
     "uses GSD_PROJECT_ROOT when set",
@@ -219,7 +219,7 @@ async function main(): Promise<void> {
   delete process.env.GSD_PROJECT_ROOT;
 
   // Without GSD_PROJECT_ROOT, direct layout still works (no ~/.gsd collision)
-  assertEq(
+  assert.deepStrictEqual(
     resolveProjectRoot("/some/repo"),
     "/some/repo",
     "ignores GSD_PROJECT_ROOT override for non-worktree paths",
@@ -227,19 +227,19 @@ async function main(): Promise<void> {
   delete process.env.GSD_PROJECT_ROOT;
 
   // Without GSD_PROJECT_ROOT, direct layout still works (no ~/.gsd collision)
-  assertEq(
+  assert.deepStrictEqual(
     resolveProjectRoot("/foo/.gsd/worktrees/M001"),
     "/foo",
     "still resolves direct layout path",
   );
-  assertEq(
+  assert.deepStrictEqual(
     resolveProjectRoot("/some/repo"),
     "/some/repo",
     "returns unchanged for non-worktree path",
   );
 
   // Without GSD_PROJECT_ROOT, direct layout with nested subdirs
-  assertEq(
+  assert.deepStrictEqual(
     resolveProjectRoot("/data/.gsd/worktrees/M003/nested"),
     "/data",
     "resolves correctly with nested subdirs after worktree name (direct layout)",
@@ -264,7 +264,7 @@ async function main(): Promise<void> {
     mkdirSync(deep, { recursive: true });
 
     process.env.GSD_HOME = join(fakeHome, ".gsd");
-    assertEq(
+    assert.deepStrictEqual(
       normalizePath(resolveProjectRoot(realpathSync(deep))),
       normalizePath(project),
       "resolves to real project root from deep symlink-resolved worktree path",
@@ -276,10 +276,4 @@ async function main(): Promise<void> {
   }
 
   rmSync(base, { recursive: true, force: true });
-  report();
-}
-
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
 });

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -20,6 +20,7 @@ export interface PlanSliceTaskInput {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  fullPlanMd?: string;
 }
 
 export interface PlanSliceParams {
@@ -167,6 +168,7 @@ export async function handlePlanSlice(
           inputs: task.inputs,
           expectedOutput: task.expectedOutput,
           observabilityImpact: task.observabilityImpact ?? "",
+          fullPlanMd: task.fullPlanMd,
         });
       }
     });

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -15,6 +15,7 @@ export interface PlanTaskParams {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  fullPlanMd?: string;
 }
 
 export interface PlanTaskResult {
@@ -94,6 +95,7 @@ export async function handlePlanTask(
         inputs: params.inputs,
         expectedOutput: params.expectedOutput,
         observabilityImpact: params.observabilityImpact ?? "",
+        fullPlanMd: params.fullPlanMd,
       });
     });
   } catch (err) {

package/src/resources/extensions/gsd/tools/replan-slice.ts

@@ -21,6 +21,7 @@ export interface ReplanSliceTaskInput {
   verify: string;
   inputs: string[];
   expectedOutput: string[];
+  fullPlanMd?: string;
 }
 
 export interface ReplanSliceParams {
@@ -136,6 +137,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         } else {
           // Insert new task then set planning fields
@@ -154,6 +156,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         }
       }

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -0,0 +1,127 @@
+/**
+ * validate-milestone handler — the core operation behind gsd_validate_milestone.
+ *
+ * Persists milestone validation results to the assessments table,
+ * renders VALIDATION.md to disk, and invalidates caches.
+ */
+
+import { join } from "node:path";
+
+import {
+  transaction,
+  _getAdapter,
+} from "../gsd-db.js";
+import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+
+export interface ValidateMilestoneParams {
+  milestoneId: string;
+  verdict: "pass" | "needs-attention" | "needs-remediation";
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+export interface ValidateMilestoneResult {
+  milestoneId: string;
+  verdict: string;
+  validationPath: string;
+}
+
+function renderValidationMarkdown(params: ValidateMilestoneParams): string {
+  let md = `---
+verdict: ${params.verdict}
+remediation_round: ${params.remediationRound}
+---
+
+# Milestone Validation: ${params.milestoneId}
+
+## Success Criteria Checklist
+${params.successCriteriaChecklist}
+
+## Slice Delivery Audit
+${params.sliceDeliveryAudit}
+
+## Cross-Slice Integration
+${params.crossSliceIntegration}
+
+## Requirement Coverage
+${params.requirementCoverage}
+
+## Verdict Rationale
+${params.verdictRationale}
+`;
+
+  if (params.verdict === "needs-remediation" && params.remediationPlan) {
+    md += `\n## Remediation Plan\n${params.remediationPlan}\n`;
+  }
+
+  return md;
+}
+
+export async function handleValidateMilestone(
+  params: ValidateMilestoneParams,
+  basePath: string,
+): Promise<ValidateMilestoneResult | { error: string }> {
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+  const validVerdicts = ["pass", "needs-attention", "needs-remediation"];
+  if (!validVerdicts.includes(params.verdict)) {
+    return { error: `verdict must be one of: ${validVerdicts.join(", ")}` };
+  }
+
+  // ── Filesystem render ──────────────────────────────────────────────────
+  const validationMd = renderValidationMarkdown(params);
+
+  let validationPath: string;
+  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  if (milestoneDir) {
+    validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
+  } else {
+    const gsdDir = join(basePath, ".gsd");
+    const manualDir = join(gsdDir, "milestones", params.milestoneId);
+    validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
+  }
+
+  try {
+    await saveFile(validationPath, validationMd);
+  } catch (renderErr) {
+    process.stderr.write(
+      `gsd-db: validate_milestone — disk render failed: ${(renderErr as Error).message}\n`,
+    );
+    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  }
+
+  // ── DB write — store in assessments table ──────────────────────────────
+  const validatedAt = new Date().toISOString();
+
+  transaction(() => {
+    const adapter = _getAdapter()!;
+    adapter.prepare(
+      `INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+       VALUES (:path, :mid, NULL, NULL, :verdict, 'milestone-validation', :content, :created_at)`,
+    ).run({
+      ":path": validationPath,
+      ":mid": params.milestoneId,
+      ":verdict": params.verdict,
+      ":content": validationMd,
+      ":created_at": validatedAt,
+    });
+  });
+
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  return {
+    milestoneId: params.milestoneId,
+    verdict: params.verdict,
+    validationPath,
+  };
+}

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

@@ -0,0 +1,193 @@
+// GSD Extension — Workflow Logger
+// Centralized warning/error accumulator for the workflow engine pipeline.
+// Captures structured entries that the auto-loop can drain after each unit
+// to surface root causes for stuck loops, silent degradation, and blocked writes.
+//
+// Stderr policy: every logWarning/logError call writes immediately to stderr
+// for terminal visibility. This is intentional — unlike debug-logger (which is
+// opt-in and zero-overhead when disabled), workflow-logger covers operational
+// warnings/errors that should always be visible. There is no disable flag.
+//
+// Singleton safety: _buffer is module-level and shared across all calls within
+// a process. The auto-loop must call _resetLogs() (or drainAndSummarize()) at
+// the start of each unit to prevent log bleed between units running in the same
+// Node process.
+
+// ─── Types ──────────────────────────────────────────────────────────────
+
+export type LogSeverity = "warn" | "error";
+
+export type LogComponent =
+  | "engine"        // WorkflowEngine afterCommand side effects
+  | "projection"    // Projection rendering
+  | "manifest"      // Manifest write
+  | "event-log"     // Event append
+  | "intercept"     // Write intercept / tool-call blocks
+  | "migration"     // Auto-migration from markdown
+  | "state"         // deriveState fallback/degradation
+  | "tool"          // Tool handler errors
+  | "compaction"    // Event compaction
+  | "reconcile";    // Worktree reconciliation
+
+export interface LogEntry {
+  ts: string;
+  severity: LogSeverity;
+  component: LogComponent;
+  message: string;
+  /** Optional structured context (file path, command name, etc.) */
+  context?: Record<string, string>;
+}
+
+// ─── Buffer ─────────────────────────────────────────────────────────────
+
+const MAX_BUFFER = 100;
+let _buffer: LogEntry[] = [];
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Record a warning. Also writes to stderr for terminal visibility.
+ */
+export function logWarning(
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  _push("warn", component, message, context);
+}
+
+/**
+ * Record an error. Also writes to stderr for terminal visibility.
+ */
+export function logError(
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  _push("error", component, message, context);
+}
+
+/**
+ * Drain all accumulated entries and clear the buffer.
+ * Returns entries oldest-first.
+ *
+ * WARNING: Call summarizeLogs() or drainAndSummarize() BEFORE calling this
+ * if you need a summary — drainLogs() clears the buffer immediately.
+ */
+export function drainLogs(): LogEntry[] {
+  const entries = _buffer;
+  _buffer = [];
+  return entries;
+}
+
+/**
+ * Atomically summarize then drain — the safe way to consume logs.
+ * Use this in the auto-loop instead of calling summarizeLogs() + drainLogs()
+ * separately to avoid the ordering footgun.
+ */
+export function drainAndSummarize(): { logs: LogEntry[]; summary: string | null } {
+  const summary = summarizeLogs();
+  const logs = drainLogs();
+  return { logs, summary };
+}
+
+/**
+ * Peek at current entries without clearing.
+ */
+export function peekLogs(): readonly LogEntry[] {
+  return _buffer;
+}
+
+/**
+ * Returns true if the buffer contains any error-severity entries.
+ */
+export function hasErrors(): boolean {
+  return _buffer.some((e) => e.severity === "error");
+}
+
+/**
+ * Returns true if the buffer contains any warn-severity entries.
+ * Use hasAnyIssues() if you want to check for either severity.
+ */
+export function hasWarnings(): boolean {
+  return _buffer.some((e) => e.severity === "warn");
+}
+
+/**
+ * Returns true if the buffer contains any entries (warn or error).
+ */
+export function hasAnyIssues(): boolean {
+  return _buffer.length > 0;
+}
+
+/**
+ * Get a one-line summary of accumulated issues for stuck detection messages.
+ * Returns null if no entries.
+ *
+ * Must be called BEFORE drainLogs() — use drainAndSummarize() for safe ordering.
+ */
+export function summarizeLogs(): string | null {
+  if (_buffer.length === 0) return null;
+  const errors = _buffer.filter((e) => e.severity === "error");
+  const warns = _buffer.filter((e) => e.severity === "warn");
+
+  const parts: string[] = [];
+  if (errors.length > 0) {
+    parts.push(`${errors.length} error(s): ${errors.map((e) => e.message).join("; ")}`);
+  }
+  if (warns.length > 0) {
+    parts.push(`${warns.length} warning(s): ${warns.map((e) => e.message).join("; ")}`);
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Format entries for display (used by auto-loop post-unit notification).
+ * Note: context fields are not included in the formatted output.
+ */
+export function formatForNotification(entries: readonly LogEntry[]): string {
+  if (entries.length === 0) return "";
+  if (entries.length === 1) {
+    const e = entries[0];
+    return `[${e.component}] ${e.message}`;
+  }
+  return entries
+    .map((e) => `[${e.component}] ${e.message}`)
+    .join("\n");
+}
+
+/**
+ * Reset buffer. Call at the start of each auto-loop unit to prevent log bleed
+ * between units running in the same process. Also used in tests via _resetLogs().
+ */
+export function _resetLogs(): void {
+  _buffer = [];
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────
+
+function _push(
+  severity: LogSeverity,
+  component: LogComponent,
+  message: string,
+  context?: Record<string, string>,
+): void {
+  const entry: LogEntry = {
+    ts: new Date().toISOString(),
+    severity,
+    component,
+    message,
+    ...(context ? { context } : {}),
+  };
+
+  // Always forward to stderr so terminal watchers see it (see module header for policy)
+  const prefix = severity === "error" ? "ERROR" : "WARN";
+  const ctxStr = context ? ` ${JSON.stringify(context)}` : "";
+  process.stderr.write(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`);
+
+  // Buffer for auto-loop to drain
+  _buffer.push(entry);
+  if (_buffer.length > MAX_BUFFER) {
+    _buffer.shift();
+  }
+}

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

@@ -16,8 +16,10 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
+import { logWarning } from "./workflow-logger.js";
 import {
   nativeBranchDelete,
   nativeBranchExists,
@@ -135,9 +137,7 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
     // worktree can be created in its place.
     const gitFilePath = join(wtPath, ".git");
     if (!existsSync(gitFilePath)) {
-      console.error(
-        `[GSD] Removing stale worktree directory (no .git file): ${wtPath}`,
-      );
+      logWarning("reconcile", `Removing stale worktree directory (no .git file): ${wtPath}`, { worktree: name });
       rmSync(wtPath, { recursive: true, force: true });
     } else {
       throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
@@ -321,8 +321,44 @@ export function removeWorktree(
     return;
   }
 
-  // Remove worktree using the resolved path (force if requested, to handle dirty worktrees)
-  try { nativeWorktreeRemove(basePath, resolvedWtPath, force); } catch { /* may fail */ }
+  // Submodule safety (#2337): detect submodules with uncommitted changes
+  // before force-removing the worktree. Force removal destroys all uncommitted
+  // state, which is especially destructive for submodule directories.
+  let hasSubmoduleChanges = false;
+  const gitmodulesPath = join(resolvedWtPath, ".gitmodules");
+  if (existsSync(gitmodulesPath)) {
+    try {
+      const submoduleStatus = execFileSync(
+        "git", ["submodule", "status"], 
+        { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      ).trim();
+      // Lines starting with '+' indicate uncommitted submodule changes
+      hasSubmoduleChanges = submoduleStatus.split("\n").some(
+        (line: string) => line.startsWith("+") || line.startsWith("-"),
+      );
+      if (hasSubmoduleChanges) {
+        // Stash submodule changes so they are not lost during force removal.
+        // The stash is created in the worktree before it's torn down.
+        try {
+          execFileSync(
+            "git", ["stash", "push", "-m", "gsd: auto-stash submodule changes before worktree teardown"],
+            { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+          );
+          logWarning("reconcile", `Stashed uncommitted submodule changes before worktree teardown`, { worktree: name, path: resolvedWtPath });
+        } catch {
+          // Stash failed — warn the user that submodule changes may be lost
+          logWarning("reconcile", `Submodule changes detected — stash failed, changes may be lost during force removal`, { worktree: name, path: resolvedWtPath });
+        }
+      }
+    } catch {
+      // submodule status failed — proceed with normal removal
+    }
+  }
+
+  // Remove worktree: try non-force first when submodules have changes,
+  // falling back to force only after submodule state has been preserved.
+  const useForce = hasSubmoduleChanges ? false : force;
+  try { nativeWorktreeRemove(basePath, resolvedWtPath, useForce); } catch { /* may fail */ }
 
   // If the directory is still there (e.g. locked), try harder with force
   if (existsSync(resolvedWtPath)) {