gsd-pi 2.50.0 → 2.51.0-dev.859cedb

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -47,8 +47,29 @@ import {
 } from "./post-unit-hooks.js";
 import { hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { debugLog } from "./debug-logger.js";
-import type { AutoSession } from "./auto/session.js";
-
+import { runSafely } from "./auto-utils.js";
+import type { AutoSession, SidecarItem } from "./auto/session.js";
+
+
+/** Enqueue a sidecar item (hook, triage, or quick-task) for the main loop to
+ *  drain via runUnit. Logs the enqueue event and notifies the UI. */
+function enqueueSidecar(
+  s: AutoSession,
+  ctx: ExtensionContext,
+  entry: SidecarItem,
+  debugExtra: Record<string, unknown>,
+  notification?: string,
+): "continue" {
+  s.sidecarQueue.push(entry);
+  debugLog("postUnitPostVerification", {
+    phase: "sidecar-enqueue",
+    kind: entry.kind,
+    unitId: entry.unitId,
+    ...debugExtra,
+  });
+  if (notification) ctx.ui.notify(notification, "info");
+  return "continue";
+}
 /** Unit types that only touch `.gsd/` internal state files (no code changes).
  *  Auto-commit is skipped for these — their state files are picked up by the
  *  next actual task commit via `smartStage()`. */
@@ -239,6 +260,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
 
   // Auto-commit
   if (s.currentUnit) {
+    const unit = s.currentUnit;
     try {
       let taskContext: TaskCommitContext | undefined;
 
@@ -297,64 +319,56 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
     }
 
     // GitHub sync (non-blocking, opt-in)
-    try {
+    await runSafely("postUnit", "github-sync", async () => {
       const { runGitHubSync } = await import("../github-sync/sync.js");
-      await runGitHubSync(s.basePath, s.currentUnit.type, s.currentUnit.id);
-    } catch (e) {
-      debugLog("postUnit", { phase: "github-sync", error: String(e) });
-    }
+      await runGitHubSync(s.basePath, unit.type, unit.id);
+    });
 
     // Prune dead bg-shell processes
-    try {
+    await runSafely("postUnit", "prune-bg-shell", async () => {
       const { pruneDeadProcesses } = await import("../bg-shell/process-manager.js");
       pruneDeadProcesses();
-    } catch (e) {
-      debugLog("postUnit", { phase: "prune-bg-shell", error: String(e) });
-    }
+    });
 
     // Tear down browser between units to prevent Chrome process accumulation (#1733)
-    try {
+    await runSafely("postUnit", "browser-teardown", async () => {
       const { getBrowser } = await import("../browser-tools/state.js");
       if (getBrowser()) {
         const { closeBrowser } = await import("../browser-tools/lifecycle.js");
         await closeBrowser();
         debugLog("postUnit", { phase: "browser-teardown", status: "closed" });
       }
-    } catch (e) {
-      debugLog("postUnit", { phase: "browser-teardown", error: String(e) });
-    }
+    });
 
     // Sync worktree state back to project root (skipped for lightweight sidecars)
     if (!opts?.skipWorktreeSync && s.originalBasePath && s.originalBasePath !== s.basePath) {
-      try {
-        syncStateToProjectRoot(s.basePath, s.originalBasePath, s.currentMilestoneId);
-      } catch (e) {
-        debugLog("postUnit", { phase: "worktree-sync", error: String(e) });
-      }
+      await runSafely("postUnit", "worktree-sync", () => {
+        syncStateToProjectRoot(s.basePath, s.originalBasePath!, s.currentMilestoneId);
+      });
     }
 
     // Rewrite-docs completion
     if (s.currentUnit.type === "rewrite-docs") {
-      try {
+      await runSafely("postUnit", "rewrite-docs-resolve", async () => {
         await resolveAllOverrides(s.basePath);
+        // Reset both disk and in-memory counters. Disk counter is authoritative
+        // (survives restarts); in-memory is kept in sync for the current session.
+        const { setRewriteCount } = await import("./auto-dispatch.js");
+        setRewriteCount(s.basePath, 0);
         s.rewriteAttemptCount = 0;
         ctx.ui.notify("Override(s) resolved — rewrite-docs completed.", "info");
-      } catch (e) {
-        debugLog("postUnit", { phase: "rewrite-docs-resolve", error: String(e) });
-      }
+      });
     }
 
     // Reactive state cleanup on slice completion
     if (s.currentUnit.type === "complete-slice") {
-      try {
-        const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
+      await runSafely("postUnit", "reactive-state-cleanup", async () => {
+        const { milestone: mid, slice: sid } = parseUnitId(unit.id);
         if (mid && sid) {
           const { clearReactiveState } = await import("./reactive-graph.js");
           clearReactiveState(s.basePath, mid, sid);
         }
-      } catch (e) {
-        debugLog("postUnit", { phase: "reactive-state-cleanup", error: String(e) });
-      }
+      });
     }
 
     // Post-triage: execute actionable resolutions
@@ -502,23 +516,11 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       }
       persistHookState(s.basePath);
 
-      s.sidecarQueue.push({
-        kind: "hook",
-        unitType: hookUnit.unitType,
-        unitId: hookUnit.unitId,
-        prompt: hookUnit.prompt,
-        model: hookUnit.model,
-      });
-
-      debugLog("postUnitPostVerification", {
-        phase: "sidecar-enqueue",
-        kind: "hook",
-        unitType: hookUnit.unitType,
-        unitId: hookUnit.unitId,
-        hookName: hookUnit.hookName,
-      });
-
-      return "continue";
+      return enqueueSidecar(
+        s, ctx,
+        { kind: "hook", unitType: hookUnit.unitType, unitId: hookUnit.unitId, prompt: hookUnit.prompt, model: hookUnit.model },
+        { hookName: hookUnit.hookName },
+      );
     }
 
     // Check if a hook requested a retry of the trigger unit
@@ -617,26 +619,12 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
             }
 
             const triageUnitId = `${mid}/${sid}/triage`;
-            s.sidecarQueue.push({
-              kind: "triage",
-              unitType: "triage-captures",
-              unitId: triageUnitId,
-              prompt,
-            });
-
-            debugLog("postUnitPostVerification", {
-              phase: "sidecar-enqueue",
-              kind: "triage",
-              unitId: triageUnitId,
-              pendingCount: pending.length,
-            });
-
-            ctx.ui.notify(
+            return enqueueSidecar(
+              s, ctx,
+              { kind: "triage", unitType: "triage-captures", unitId: triageUnitId, prompt },
+              { pendingCount: pending.length },
               `Triaging ${pending.length} pending capture${pending.length === 1 ? "" : "s"}...`,
-              "info",
             );
-
-            return "continue";
           }
         }
       }
@@ -665,27 +653,12 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       markCaptureExecuted(s.basePath, capture.id);
 
       const qtUnitId = `${s.currentMilestoneId}/${capture.id}`;
-      s.sidecarQueue.push({
-        kind: "quick-task",
-        unitType: "quick-task",
-        unitId: qtUnitId,
-        prompt,
-        captureId: capture.id,
-      });
-
-      debugLog("postUnitPostVerification", {
-        phase: "sidecar-enqueue",
-        kind: "quick-task",
-        unitId: qtUnitId,
-        captureId: capture.id,
-      });
-
-      ctx.ui.notify(
+      return enqueueSidecar(
+        s, ctx,
+        { kind: "quick-task", unitType: "quick-task", unitId: qtUnitId, prompt, captureId: capture.id },
+        { captureId: capture.id },
         `Executing quick-task: ${capture.id} — "${capture.text}"`,
-        "info",
       );
-
-      return "continue";
     } catch (e) {
       debugLog("postUnit", { phase: "quick-task-dispatch", error: String(e) });
     }

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

@@ -784,6 +784,14 @@ export async function checkNeedsRunUat(
         if (!uatContent) return null;
         // If the UAT file already contains a verdict, UAT has been run — skip
         if (hasVerdict(uatContent)) return null;
+        // Also check the ASSESSMENT file — the run-uat prompt writes the verdict
+        // there (via gsd_summary_save artifact_type:"ASSESSMENT"), not into the
+        // UAT spec file. Without this check the unit re-dispatches indefinitely.
+        const assessmentFile = resolveSliceFile(base, mid, sid, "ASSESSMENT");
+        if (assessmentFile) {
+          const assessmentContent = await loadFile(assessmentFile);
+          if (assessmentContent && hasVerdict(assessmentContent)) return null;
+        }
         const uatType = getUatType(uatContent);
         return { sliceId: sid, uatType };
       }
@@ -808,6 +816,13 @@ export async function checkNeedsRunUat(
   if (!uatContentFb) return null;
   // If the UAT file already contains a verdict, UAT has been run — skip
   if (hasVerdict(uatContentFb)) return null;
+  // Also check the ASSESSMENT file for the file-based fallback path (same
+  // reason as the DB path above — verdict lives in ASSESSMENT, not UAT).
+  const assessmentFileFb = resolveSliceFile(base, mid, uatSid, "ASSESSMENT");
+  if (assessmentFileFb) {
+    const assessmentContentFb = await loadFile(assessmentFileFb);
+    if (assessmentContentFb && hasVerdict(assessmentContentFb)) return null;
+  }
   const uatTypeFb = getUatType(uatContentFb);
   return { sliceId: uatSid, uatType: uatTypeFb };
 }
@@ -1330,6 +1345,24 @@ export async function buildValidateMilestonePrompt(
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
 
+  // Inline verification classes from planning (if available in DB)
+  try {
+    const { isDbAvailable, getMilestone } = await import("./gsd-db.js");
+    if (isDbAvailable()) {
+      const milestone = getMilestone(mid);
+      if (milestone) {
+        const classes: string[] = [];
+        if (milestone.verification_contract) classes.push(`- **Contract:** ${milestone.verification_contract}`);
+        if (milestone.verification_integration) classes.push(`- **Integration:** ${milestone.verification_integration}`);
+        if (milestone.verification_operational) classes.push(`- **Operational:** ${milestone.verification_operational}`);
+        if (milestone.verification_uat) classes.push(`- **UAT:** ${milestone.verification_uat}`);
+        if (classes.length > 0) {
+          inlined.push(`### Verification Classes (from planning)\n\nThese verification tiers were defined during milestone planning. Each non-empty class must be checked for evidence during validation.\n\n${classes.join("\n")}`);
+        }
+      }
+    }
+  } catch { /* fall through */ }
+
   // Inline all slice summaries and UAT results
   let valSliceIds: string[] = [];
   try {
@@ -1359,6 +1392,21 @@ export async function buildValidateMilestonePrompt(
     if (uatInline) inlined.push(uatInline);
   }
 
+  // Aggregate unresolved follow-ups and known limitations across slices
+  const outstandingItems: string[] = [];
+  for (const sid of valSliceIds) {
+    const summaryPath = resolveSliceFile(base, mid, sid, "SUMMARY");
+    if (!summaryPath) continue;
+    const content = await loadFile(summaryPath);
+    if (!content) continue;
+    const summary = parseSummary(content);
+    if (summary.followUps) outstandingItems.push(`- **${sid} Follow-ups:** ${summary.followUps.trim()}`);
+    if (summary.knownLimitations) outstandingItems.push(`- **${sid} Known Limitations:** ${summary.knownLimitations.trim()}`);
+  }
+  if (outstandingItems.length > 0) {
+    inlined.push(`### Outstanding Items (aggregated from slice summaries)\n\nThese follow-ups and known limitations were documented during slice completion but have not been resolved.\n\n${outstandingItems.join('\n')}`);
+  }
+
   // Inline existing VALIDATION file if this is a re-validation round
   const validationPath = resolveMilestoneFile(base, mid, "VALIDATION");
   const validationRel = relMilestoneFile(base, mid, "VALIDATION");

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

@@ -12,7 +12,7 @@ import { parseUnitId } from "./unit-id.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getTask, getSlice, getSliceTasks } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getSliceTasks, updateTaskStatus } from "./gsd-db.js";
 import { isValidationTerminal } from "./state.js";
 import {
   nativeConflictFiles,
@@ -195,13 +195,8 @@ export function verifyExpectedArtifact(
   // Reactive-execute: verify that each dispatched task's summary exists.
   // The unitId encodes the batch: "{mid}/{sid}/reactive+T02,T03"
   if (unitType === "reactive-execute") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sidAndBatch = parts[1];
-    const batchPart = parts[2]; // "reactive+T02,T03"
-    if (!mid || !sidAndBatch || !batchPart) return false;
-
-    const sid = sidAndBatch;
+    const { milestone: mid, slice: sid, task: batchPart } = parseUnitId(unitId);
+    if (!mid || !sid || !batchPart) return false;
     const plusIdx = batchPart.indexOf("+");
     if (plusIdx === -1) {
       // Legacy format "reactive" without batch IDs — fall back to "any summary"
@@ -233,10 +228,7 @@ export function verifyExpectedArtifact(
   // Gate-evaluate: verify that each dispatched gate has been resolved in the DB.
   // The unitId encodes the batch: "{mid}/{sid}/gates+Q3,Q4"
   if (unitType === "gate-evaluate") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
-    const batchPart = parts[2]; // "gates+Q3,Q4"
+    const { milestone: mid, slice: sid, task: batchPart } = parseUnitId(unitId);
     if (!mid || !sid || !batchPart) return false;
 
     const plusIdx = batchPart.indexOf("+");
@@ -286,10 +278,7 @@ export function verifyExpectedArtifact(
   // execute-task: DB status is authoritative. Fall back to heading-style plan
   // detection when the DB is unavailable (unmigrated projects).
   if (unitType === "execute-task") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
-    const tid = parts[2];
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     if (mid && sid && tid) {
       const dbTask = getTask(mid, sid, tid);
       if (dbTask) {
@@ -319,9 +308,7 @@ export function verifyExpectedArtifact(
   // but omitted T{tid}-PLAN.md files would be marked complete, causing execute-task
   // to dispatch with a missing task plan (see issue #739).
   if (unitType === "plan-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (mid && sid) {
       try {
         // DB primary path — get task IDs to verify task plan files exist
@@ -356,9 +343,7 @@ export function verifyExpectedArtifact(
   // complete-slice: DB status is authoritative for whether the slice is done.
   // Fall back to file-based check (roadmap [x]) when DB is unavailable.
   if (unitType === "complete-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (mid && sid) {
       const dir = resolveSlicePath(base, mid, sid);
       if (dir) {
@@ -425,6 +410,17 @@ export function writeBlockerPlaceholder(
     `Review and replace this file before relying on downstream artifacts.`,
   ].join("\n");
   writeFileSync(absPath, content, "utf-8");
+
+  // Mark the task as complete in the DB so verifyExpectedArtifact passes.
+  // Without this, the DB status stays "pending" and the dispatch loop
+  // re-derives the same task indefinitely (#2531).
+  if (unitType === "execute-task" && isDbAvailable()) {
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+    if (mid && sid && tid) {
+      try { updateTaskStatus(mid, sid, tid, "complete", new Date().toISOString()); } catch { /* non-fatal */ }
+    }
+  }
+
   return diagnoseExpectedArtifact(unitType, unitId, base);
 }
 
@@ -544,10 +540,7 @@ export function buildLoopRemediationSteps(
   unitId: string,
   base: string,
 ): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "execute-task": {
       if (!mid || !sid || !tid) break;

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

@@ -67,6 +67,7 @@ import {
   getDebugLogPath,
 } from "./debug-logger.js";
 import { parseUnitId } from "./unit-id.js";
+import { setLogBasePath } from "./workflow-logger.js";
 import type { AutoSession } from "./auto/session.js";
 import {
   existsSync,
@@ -461,6 +462,7 @@ export async function bootstrapAutoSession(
     s.verbose = verboseMode;
     s.cmdCtx = ctx;
     s.basePath = base;
+    setLogBasePath(base);
     s.unitDispatchCount.clear();
     s.unitRecoveryCount.clear();
     s.lastBudgetAlertLevel = 0;

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

@@ -15,6 +15,8 @@ import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.j
 import {
   getInFlightToolCount,
   getOldestInFlightToolStart,
+  clearInFlightTools,
+  hasInteractiveToolInFlight,
 } from "./auto-tool-tracking.js";
 import { detectWorkingTreeActivity } from "./auto-supervisor.js";
 import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
@@ -146,7 +148,17 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
 
       // Agent has tool calls currently executing — not idle, just waiting.
       // But only suppress recovery if the tool started recently.
+      let stalledToolDetected = false;
       if (getInFlightToolCount() > 0) {
+        // User-interactive tools (ask_user_questions, secure_env_collect) block
+        // waiting for human input by design — never treat them as stalled (#2676).
+        if (hasInteractiveToolInFlight()) {
+          writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+            lastProgressAt: Date.now(),
+            lastProgressKind: "interactive-tool-waiting",
+          });
+          return;
+        }
         const oldestStart = getOldestInFlightToolStart()!;
         const toolAgeMs = Date.now() - oldestStart;
         if (toolAgeMs < idleTimeoutMs) {
@@ -156,6 +168,12 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
           });
           return;
         }
+        // Tool has been in-flight longer than idle timeout — treat as hung.
+        // Clear the stale entries so subsequent ticks don't re-detect them,
+        // and set the flag so the filesystem-activity check below does not
+        // override the stall verdict (#2527).
+        stalledToolDetected = true;
+        clearInFlightTools();
         ctx.ui.notify(
           `Stalled tool detected: a tool has been in-flight for ${Math.round(toolAgeMs / 60000)}min. Treating as hung — attempting idle recovery.`,
           "warning",
@@ -163,7 +181,9 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       }
 
       // Check if the agent is producing work on disk.
-      if (detectWorkingTreeActivity(s.basePath)) {
+      // Skip this when a stalled tool was just detected — filesystem changes
+      // from earlier in the task should not override the stall verdict (#2527).
+      if (!stalledToolDetected && detectWorkingTreeActivity(s.basePath)) {
         writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
           lastProgressAt: Date.now(),
           lastProgressKind: "filesystem-activity",
@@ -180,6 +200,10 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       const recovery = await recoverTimedOutUnit(ctx, pi, unitType, unitId, "idle", buildRecoveryContext());
       if (recovery === "recovered") return;
 
+      // Guard: recoverTimedOutUnit is async — pauseAuto/stopAuto may have
+      // set s.currentUnit = null during the await (#2527).
+      if (!s.currentUnit) return;
+
       writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
         phase: "paused",
       });

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -4,15 +4,27 @@
  * can distinguish "waiting for tool completion" from "truly idle".
  */
 
-const inFlightTools = new Map<string, number>();
+interface InFlightTool {
+  startedAt: number;
+  toolName: string;
+}
+
+const inFlightTools = new Map<string, InFlightTool>();
+
+/**
+ * Tools that block waiting for human input by design.
+ * The idle watchdog must not treat these as stalled.
+ */
+const INTERACTIVE_TOOLS = new Set(["ask_user_questions", "secure_env_collect"]);
 
 /**
  * Mark a tool execution as in-flight.
- * Records start time so the idle watchdog can detect tools hung longer than the idle timeout.
+ * Records start time and tool name so the idle watchdog can detect tools
+ * hung longer than the idle timeout while exempting interactive tools.
  */
-export function markToolStart(toolCallId: string, isActive: boolean): void {
+export function markToolStart(toolCallId: string, isActive: boolean, toolName?: string): void {
   if (!isActive) return;
-  inFlightTools.set(toolCallId, Date.now());
+  inFlightTools.set(toolCallId, { startedAt: Date.now(), toolName: toolName ?? "unknown" });
 }
 
 /**
@@ -29,7 +41,7 @@ export function getOldestInFlightToolAgeMs(): number {
   if (inFlightTools.size === 0) return 0;
   let oldestStart = Infinity;
   for (const t of inFlightTools.values()) {
-    if (t < oldestStart) oldestStart = t;
+    if (t.startedAt < oldestStart) oldestStart = t.startedAt;
   }
   return Date.now() - oldestStart;
 }
@@ -48,11 +60,23 @@ export function getOldestInFlightToolStart(): number | undefined {
   if (inFlightTools.size === 0) return undefined;
   let oldest = Infinity;
   for (const t of inFlightTools.values()) {
-    if (t < oldest) oldest = t;
+    if (t.startedAt < oldest) oldest = t.startedAt;
   }
   return oldest;
 }
 
+/**
+ * Returns true if any currently in-flight tool is a user-interactive tool
+ * (e.g. ask_user_questions, secure_env_collect) that blocks waiting for
+ * human input. These must be exempt from idle stall detection.
+ */
+export function hasInteractiveToolInFlight(): boolean {
+  for (const { toolName } of inFlightTools.values()) {
+    if (INTERACTIVE_TOOLS.has(toolName)) return true;
+  }
+  return false;
+}
+
 /**
  * Clear all in-flight tool tracking state.
  */

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

@@ -0,0 +1,25 @@
+// Shared utilities for the auto-loop modules (auto-post-unit, auto, etc.).
+
+import { debugLog } from "./debug-logger.js";
+
+/**
+ * Run a non-fatal operation, logging any error via `debugLog` and continuing.
+ *
+ * Replaces the repeated try-catch-debugLog-continue boilerplate that wraps
+ * operations whose failure should not abort the post-unit pipeline.
+ *
+ * @param context - The debugLog event name (e.g. "postUnit")
+ * @param phase   - The phase label attached to the debug entry
+ * @param fn      - The operation to execute (may be sync or async)
+ */
+export async function runSafely(
+  context: string,
+  phase: string,
+  fn: () => Promise<void> | void,
+): Promise<void> {
+  try {
+    await fn();
+  } catch (e) {
+    debugLog(context, { phase, error: String(e) });
+  }
+}

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

@@ -82,6 +82,10 @@ const ROOT_STATE_FILES = [
   "QUEUE.md",
   "completed-units.json",
   "metrics.json",
+  // NOTE: preferences.md is intentionally NOT in ROOT_STATE_FILES.
+  // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree().
+  // Back-sync (worktree → main) must NEVER overwrite the project root's copy
+  // because the project root is authoritative for preferences (#2684).
 ] as const;
 
 /**
@@ -416,6 +420,22 @@ export function syncGsdStateToWorktree(
     }
   }
 
+  // Forward-sync preferences.md from project root to worktree (additive only).
+  // NOT in ROOT_STATE_FILES because syncWorktreeStateBack() must never overwrite
+  // the project root's preferences — the project root is authoritative (#2684).
+  {
+    const src = join(mainGsd, "preferences.md");
+    const dst = join(wtGsd, "preferences.md");
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        cpSync(src, dst);
+        synced.push("preferences.md");
+      } catch {
+        /* non-fatal */
+      }
+    }
+  }
+
   // Sync milestones: copy entire milestone directories that are missing
   const mainMilestonesDir = join(mainGsd, "milestones");
   const wtMilestonesDir = join(wtGsd, "milestones");
@@ -946,6 +966,7 @@ function copyPlanningArtifacts(srcBase: string, wtPath: string): void {
     "STATE.md",
     "KNOWLEDGE.md",
     "OVERRIDES.md",
+    "preferences.md",
   ]) {
     safeCopy(join(srcGsd, file), join(dstGsd, file), { force: true });
   }