gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/dist/resources/extensions/gsd/auto/phases.js

@@ -27,7 +27,7 @@ import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
-import { ensurePlanV2Graph } from "../uok/plan-v2.js";
+import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
 import { resetEvidence, loadEvidenceFromDisk } from "../safety/evidence-collector.js";
@@ -296,27 +296,42 @@ export async function runPreDispatch(ic, loopState) {
         const compiled = ensurePlanV2Graph(s.basePath, state);
         if (!compiled.ok) {
             const reason = compiled.reason ?? "Plan v2 compilation failed";
+            if (isMissingFinalizedContextResult(compiled)) {
+                await runPreDispatchGate({
+                    gateId: "plan-v2-gate",
+                    gateType: "policy",
+                    outcome: "pass",
+                    failureClass: "none",
+                    rationale: "plan v2 missing context recovery deferred to dispatch",
+                    findings: reason,
+                    milestoneId: state.activeMilestone?.id ?? undefined,
+                });
+            }
+            else {
+                await runPreDispatchGate({
+                    gateId: "plan-v2-gate",
+                    gateType: "policy",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "plan v2 compile gate failed",
+                    findings: reason,
+                    milestoneId: state.activeMilestone?.id ?? undefined,
+                });
+                ctx.ui.notify(`Plan gate failed-closed: ${reason}\n\nIf this keeps happening, try: /gsd doctor heal`, "error");
+                await deps.pauseAuto(ctx, pi);
+                return { action: "break", reason: "plan-v2-gate-failed" };
+            }
+        }
+        if (compiled.ok) {
             await runPreDispatchGate({
                 gateId: "plan-v2-gate",
                 gateType: "policy",
-                outcome: "manual-attention",
-                failureClass: "manual-attention",
-                rationale: "plan v2 compile gate failed",
-                findings: reason,
+                outcome: "pass",
+                failureClass: "none",
+                rationale: "plan v2 compile gate passed",
                 milestoneId: state.activeMilestone?.id ?? undefined,
             });
-            ctx.ui.notify(`Plan gate failed-closed: ${reason}\n\nIf this keeps happening, try: /gsd doctor heal`, "error");
-            await deps.pauseAuto(ctx, pi);
-            return { action: "break", reason: "plan-v2-gate-failed" };
         }
-        await runPreDispatchGate({
-            gateId: "plan-v2-gate",
-            gateType: "policy",
-            outcome: "pass",
-            failureClass: "none",
-            rationale: "plan v2 compile gate passed",
-            milestoneId: state.activeMilestone?.id ?? undefined,
-        });
     }
     deps.syncCmuxSidebar(prefs, state);
     let mid = state.activeMilestone?.id;
@@ -1241,9 +1256,18 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     if (unitResult.status === "cancelled") {
         const errorCategory = unitResult.errorContext?.category;
-        // Provider-error pause: pauseAuto already handled cleanup and scheduled
-        // recovery. Don't hard-stop — just break out of the loop (#2762).
+        // Provider-error pause: agent_end recovery normally pauses before this
+        // branch. Provider readiness failures happen before dispatch, so pause here
+        // if nothing upstream already did.
         if (errorCategory === "provider") {
+            if (!s.paused) {
+                const detail = unitResult.errorContext?.message ?? `Provider unavailable for ${unitType} ${unitId}`;
+                await pauseAutoForProviderError(ctx.ui, detail, () => deps.pauseAuto(ctx, pi), {
+                    isRateLimit: false,
+                    isTransient: Boolean(unitResult.errorContext?.isTransient),
+                    retryAfterMs: unitResult.errorContext?.retryAfterMs,
+                });
+            }
             await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext?.isTransient });
             return { action: "break", reason: "provider-pause" };

package/dist/resources/extensions/gsd/auto/resolve.js

@@ -8,6 +8,7 @@
  * Imports from: auto/types
  */
 import { debugLog } from "../debug-logger.js";
+import { bumpTurnGeneration } from "./turn-epoch.js";
 // ─── Per-unit one-shot promise state ────────────────────────────────────────
 //
 // A single module-level resolve function scoped to the current unit execution.
@@ -56,6 +57,22 @@ export function resolveAgentEnd(event) {
 export function isSessionSwitchInFlight() {
     return _sessionSwitchInFlight;
 }
+// ─── bumpAndResolveSynthetic ────────────────────────────────────────────────
+/**
+ * Bump the turn epoch and synthetically resolve the pending unit promise —
+ * the exact sequence timeout recovery must perform when it advances past a
+ * timed-out unit. Using this helper enforces the invariant "bump iff we are
+ * actually superseding the turn" so a future caller cannot resolve without
+ * bumping (orphaned writes leak) or bump without resolving (next turn starts
+ * already stale).
+ *
+ * NOT to be used for steering retries that keep the same turn alive — those
+ * do not supersede the turn and must not bump.
+ */
+export function bumpAndResolveSynthetic(reason) {
+    bumpTurnGeneration(reason);
+    resolveAgentEnd({ messages: [], _synthetic: reason });
+}
 // ─── resolveAgentEndCancelled ─────────────────────────────────────────────────
 /**
  * Force-resolve the pending unit promise with { status: "cancelled" }.
@@ -66,6 +83,10 @@ export function isSessionSwitchInFlight() {
  */
 export function resolveAgentEndCancelled(errorContext) {
     if (_currentResolve) {
+        // Cancellation supersedes the in-flight turn the same way timeout
+        // recovery does — bump the turn epoch so any lingering writes from the
+        // cancelled turn drop themselves.
+        bumpTurnGeneration(`cancelled:${errorContext?.category ?? "unknown"}`);
         debugLog("resolveAgentEndCancelled", { status: "resolving-cancelled" });
         const r = _currentResolve;
         _currentResolve = null;
@@ -81,6 +102,9 @@ export function _resetPendingResolve() {
     _currentResolve = null;
     _sessionSwitchInFlight = false;
 }
+export function _hasPendingResolveForTest() {
+    return _currentResolve !== null;
+}
 /**
  * No-op for backward compatibility with tests that previously set the
  * active session. The module no longer holds a session reference.

package/dist/resources/extensions/gsd/auto/run-unit.js

@@ -4,7 +4,8 @@
  * Imports from: auto/types, auto/resolve
  */
 import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
-import { _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
+import { _clearCurrentResolve, _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
+import { getCurrentTurnGeneration, runWithTurnGeneration, } from "./turn-epoch.js";
 import { debugLog } from "../debug-logger.js";
 import { logWarning } from "../workflow-logger.js";
 import { resolveAutoSupervisorConfig } from "../preferences.js";
@@ -117,6 +118,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
                 ready = false;
             }
             if (!ready) {
+                _clearCurrentResolve();
                 return {
                     status: "cancelled",
                     errorContext: {
@@ -128,6 +130,12 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             }
         }
     }
+    // ── Capture turn generation for stale-write detection ──
+    // Any write site reached via the sendMessage → tool-call → await chain
+    // below sees this generation via AsyncLocalStorage. If a timeout recovery
+    // or cancellation bumps the generation while this turn is in flight, those
+    // writes see themselves as stale and self-drop.
+    const capturedTurnGen = getCurrentTurnGeneration();
     // ── Send the prompt ──
     debugLog("runUnit", { phase: "send-message", unitType, unitId });
     pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
@@ -143,7 +151,7 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } });
         }, UNIT_HARD_TIMEOUT_MS);
     });
-    const result = await Promise.race([unitPromise, timeoutResult]);
+    const result = await runWithTurnGeneration(capturedTurnGen, () => Promise.race([unitPromise, timeoutResult]));
     if (unitTimeoutHandle)
         clearTimeout(unitTimeoutHandle);
     debugLog("runUnit", {

package/dist/resources/extensions/gsd/auto/session.js

@@ -105,6 +105,11 @@ export class AutoSession {
     /** Set to true after phases.ts successfully calls mergeAndExit, so that
      *  stopAuto does not attempt the same merge a second time (#2645). */
     milestoneMergedInPhases = false;
+    // #4765 — slice-cadence collapse: main-branch SHAs at the moment each
+    // milestone's first slice merge began. Used by resquashMilestoneOnMain at
+    // milestone completion to collapse N slice commits into one. Cleared when
+    // the milestone finishes (or resquash runs).
+    milestoneStartShas = new Map();
     // ── Dispatch circuit breakers ──────────────────────────────────────
     rewriteAttemptCount = 0;
     /** Tracks consecutive bootstrap attempts that found phase === "complete".
@@ -221,6 +226,7 @@ export class AutoSession {
         this.lastGitActionStatus = null;
         this.isolationDegraded = false;
         this.milestoneMergedInPhases = false;
+        this.milestoneStartShas = new Map();
         this.checkpointSha = null;
         // Signal handler
         this.sigtermHandler = null;

package/dist/resources/extensions/gsd/auto/turn-epoch.js

@@ -0,0 +1,95 @@
+/**
+ * auto/turn-epoch.ts — Turn generation counter + AsyncLocalStorage-backed
+ * capture for stale-turn write dropping.
+ *
+ * Problem: when auto-timeout-recovery synthetically resolves a timed-out
+ * unit so the loop can advance, the original LLM turn keeps running in the
+ * background. Its subsequent writes (journal events, audit events, tool
+ * calls that flow through closeout) then race the replacement unit's
+ * writes. DB-level guards (complete-task/complete-slice) block double
+ * state transitions, but journal/audit/closeout side-effects still fire
+ * with fresh identifiers and pollute forensics.
+ *
+ * Containment: every time we decide a turn is done (timeout recovery,
+ * explicit cancellation), bump a module-level generation counter.
+ * Turn-aware call sites wrap their body in `runWithTurnGeneration`, which
+ * captures the generation into AsyncLocalStorage. Write sites deep in the
+ * stack call `isStaleWrite` — if the captured generation is older than
+ * current, the turn has been superseded and the write is dropped.
+ *
+ * Failure mode: if AsyncLocalStorage context is lost across some exotic
+ * async boundary (e.g. a native-side worker callback), the write site sees
+ * `no-store` and falls through to current behavior — the write proceeds
+ * normally. That is a safe default; the correctness regression is only
+ * "noisier forensics under rare boundary loss," not duplicated state.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { debugLog } from "../debug-logger.js";
+let _currentGeneration = 0;
+const turnContext = new AsyncLocalStorage();
+/** Current turn generation. Mutated only by bumpTurnGeneration. */
+export function getCurrentTurnGeneration() {
+    return _currentGeneration;
+}
+/**
+ * Bump the turn generation and return the new value. Every caller should
+ * pass a short `reason` string so forensics can reconstruct why a given
+ * turn was marked stale.
+ */
+export function bumpTurnGeneration(reason) {
+    _currentGeneration += 1;
+    debugLog("turnEpoch.bump", { reason, newGeneration: _currentGeneration });
+    return _currentGeneration;
+}
+/**
+ * Run fn() with `capturedGen` attached to AsyncLocalStorage so that any
+ * write site reached from within fn() can check for staleness without
+ * parameter threading.
+ */
+export function runWithTurnGeneration(capturedGen, fn) {
+    return turnContext.run({ capturedGen }, fn);
+}
+/**
+ * True when the current async context was started at a turn generation
+ * older than the current one — meaning the turn has been superseded by
+ * recovery/cancellation since it began.
+ *
+ * Returns false when there is no captured generation (e.g. the write is
+ * happening outside any wrapped turn). That is the safe default: writes
+ * proceed as they did before this epoch was introduced.
+ */
+export function isStaleWrite(component) {
+    const store = turnContext.getStore();
+    if (!store)
+        return false;
+    const captured = store.capturedGen;
+    const current = _currentGeneration;
+    if (captured < current) {
+        debugLog("turnEpoch.stale", {
+            component: component ?? "unknown",
+            captured,
+            current,
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * Snapshot of both the captured turn generation and the current one.
+ * Used by closeoutUnit to persist an orphan-marker entry instead of
+ * silently skipping the full closeout on a stale turn.
+ */
+export function describeTurnEpoch() {
+    const store = turnContext.getStore();
+    const captured = store?.capturedGen ?? null;
+    const current = _currentGeneration;
+    return {
+        captured,
+        current,
+        stale: captured !== null && captured < current,
+    };
+}
+/** Test helper — resets module state so tests start from a known baseline. */
+export function _resetTurnEpoch() {
+    _currentGeneration = 0;
+}

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -17,11 +17,13 @@ import { parseRoadmap } from "./parsers-legacy.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
-import { hasImplementationArtifacts, classifyMilestoneSummaryContent } from "./auto-recovery.js";
+import { hasImplementationArtifacts } from "./auto-recovery.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { buildDiscussMilestonePrompt, buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildRefineSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, buildReactiveExecutePrompt, buildGateEvaluatePrompt, buildParallelResearchSlicesPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
 import { resolveModelWithFallbacksForUnit } from "./preferences-models.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
+import { EXECUTION_ENTRY_PHASES, hasFinalizedMilestoneContext } from "./uok/plan-v2.js";
 function missingSliceStop(mid, phase) {
     return {
         action: "stop",
@@ -155,6 +157,35 @@ export const DISPATCH_RULES = [
             };
         },
     },
+    {
+        // #4671 — Recovery path for execution-entry phases with missing CONTEXT.md.
+        //
+        // Once `deriveStateFromDb` returns an execution-entry phase (executing /
+        // summarizing / validating-milestone / completing-milestone), the
+        // pre-planning guard at `pre-planning (no context) → discuss-milestone`
+        // no longer fires. The plan-v2 gate correctly detects the missing context
+        // but can only block — it cannot redispatch. Without this rule the
+        // milestone is stuck until `/gsd doctor heal` repairs it (and heal
+        // historically missed this check too).
+        //
+        // Fire BEFORE the execution-entry phase rules so we redispatch to
+        // `discuss-milestone` instead of hitting the plan-v2 gate.
+        name: "execution-entry phase (no context) → discuss-milestone",
+        match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
+            if (!EXECUTION_ENTRY_PHASES.has(state.phase))
+                return null;
+            // Align with the plan-v2 gate's lookup semantics: whitespace-only counts
+            // as missing, and an auto worktree may fall back to GSD_PROJECT_ROOT.
+            if (hasFinalizedMilestoneContext(basePath, mid))
+                return null;
+            return {
+                action: "dispatch",
+                unitType: "discuss-milestone",
+                unitId: mid,
+                prompt: await buildDiscussMilestonePrompt(mid, midTitle, basePath, structuredQuestionsAvailable),
+            };
+        },
+    },
     {
         name: "summarizing → complete-slice",
         match: async ({ state, mid, midTitle, basePath }) => {
@@ -319,6 +350,30 @@ export const DISPATCH_RULES = [
             };
         },
     },
+    {
+        name: "planning (require_slice_discussion) → pause for discussion (#3454)",
+        match: async ({ state, mid, basePath, prefs }) => {
+            if (state.phase !== "planning")
+                return null;
+            if (!prefs?.phases?.require_slice_discussion)
+                return null;
+            if (!state.activeSlice)
+                return null;
+            // Only pause if the slice has no context file yet (discussion not done).
+            // resolveSliceFile returns null when the file does not exist on disk,
+            // but cachedReaddir could return a stale hit — verify with existsSync
+            // so the guard is defence-in-depth and the contract is explicit at the
+            // call site.
+            const sliceContextFile = resolveSliceFile(basePath, mid, state.activeSlice.id, "CONTEXT");
+            if (sliceContextFile && existsSync(sliceContextFile))
+                return null; // discussion already done, proceed
+            return {
+                action: "stop",
+                reason: `Slice ${state.activeSlice.id} requires discussion before planning (require_slice_discussion is enabled). Run /gsd discuss to discuss this slice, then /gsd auto to resume.`,
+                level: "info",
+            };
+        },
+    },
     {
         // Keep this rule before the single-slice research rule so the multi-slice
         // path wins whenever 2+ slices are ready.
@@ -704,7 +759,7 @@ export const DISPATCH_RULES = [
             }
             const existingSummary = resolveMilestoneFile(basePath, mid, "SUMMARY");
             let summaryOutcome = "unknown";
-            if (existingSummary && isDbAvailable()) {
+            if (existingSummary) {
                 const summaryContent = await loadFile(existingSummary);
                 if (summaryContent) {
                     summaryOutcome = classifyMilestoneSummaryContent(summaryContent);
@@ -791,10 +846,14 @@ export const DISPATCH_RULES = [
             // - success summary: reconcile DB and skip re-dispatch
             // - failure summary: pause/fail-closed
             // - unknown summary: pause/fail-closed
-            if (existingSummary && isDbAvailable()) {
-                const milestone = getMilestone(mid);
-                const status = milestone?.status ?? "missing";
+            if (existingSummary) {
+                const milestone = isDbAvailable() ? getMilestone(mid) : null;
+                const status = milestone?.status ?? (isDbAvailable() ? "missing" : "unavailable");
                 if (summaryOutcome === "success") {
+                    if (!isDbAvailable()) {
+                        logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB is unavailable — skipping duplicate complete-milestone dispatch`);
+                        return { action: "skip" };
+                    }
                     try {
                         updateMilestoneStatus(mid, "complete", new Date().toISOString());
                         logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB status was "${status}" — reconciled DB to complete (#4658)`);

package/dist/resources/extensions/gsd/auto-loop.js

@@ -8,6 +8,6 @@
  */
 export { autoLoop, runUokKernelLoop, runLegacyAutoLoop } from "./auto/loop.js";
 export { isInfrastructureError, INFRA_ERROR_CODES } from "./auto/infra-errors.js";
-export { resolveAgentEnd, resolveAgentEndCancelled, isSessionSwitchInFlight, _resetPendingResolve, _setActiveSession } from "./auto/resolve.js";
+export { resolveAgentEnd, resolveAgentEndCancelled, isSessionSwitchInFlight, _hasPendingResolveForTest, _resetPendingResolve, _setActiveSession } from "./auto/resolve.js";
 export { detectStuck } from "./auto/detect-stuck.js";
 export { runUnit } from "./auto/run-unit.js";

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -46,6 +46,7 @@ import { resolveUokFlags } from "./uok/flags.js";
 import { UokGateRunner } from "./uok/gate-runner.js";
 import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
+import { detectAbandonMilestone } from "./abandon-detect.js";
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
@@ -472,6 +473,36 @@ export async function postUnitPreVerification(pctx, opts) {
         // Rewrite-docs completion
         if (s.currentUnit.type === "rewrite-docs") {
             await runSafely("postUnit", "rewrite-docs-resolve", async () => {
+                // Detect abandon/descope overrides BEFORE resolving them (#3490).
+                // If an override is about abandoning the milestone, park it so the
+                // state engine skips it. Without this, rewrite-docs only edits
+                // markdown but the DB still has the milestone as active.
+                try {
+                    const { loadActiveOverrides } = await import("./files.js");
+                    const overrides = await loadActiveOverrides(s.basePath);
+                    const decision = detectAbandonMilestone(overrides, s.currentMilestoneId);
+                    if (decision.shouldPark && s.currentMilestoneId) {
+                        const { parkMilestone } = await import("./milestone-actions.js");
+                        const parked = parkMilestone(s.basePath, s.currentMilestoneId, decision.reason);
+                        if (parked) {
+                            ctx.ui.notify(`Milestone ${s.currentMilestoneId} parked: "${decision.reason}"`, "info");
+                        }
+                        else {
+                            // Park refused: milestone directory missing, milestone already
+                            // completed (SUMMARY present), or PARKED.md already exists.
+                            // resolveAllOverrides below will still consume the override —
+                            // surface this loudly so the user notices state drift rather
+                            // than silently losing the abandon directive.
+                            const msg = `Abandon detected for ${s.currentMilestoneId} but park refused (milestone is completed, already parked, or missing). Override will be resolved anyway — verify state is correct.`;
+                            logError("engine", msg);
+                            ctx.ui.notify(msg, "warning");
+                        }
+                    }
+                }
+                catch (err) {
+                    logError("engine", `abandon-detect failed: ${err.message}`);
+                    ctx.ui.notify(`Abandon detection failed — check logs. Overrides will still be resolved.`, "warning");
+                }
                 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.
@@ -490,6 +521,85 @@ export async function postUnitPreVerification(pctx, opts) {
                     clearReactiveState(s.basePath, mid, sid);
                 }
             });
+            // #4765 — slice-cadence collapse. When `git.collapse_cadence: "slice"`
+            // is set, squash-merge the slice's commits from the milestone branch
+            // onto main right here, so orphan risk shrinks from milestone-size to
+            // slice-size. Only runs in worktree isolation mode — the feature needs
+            // a milestone branch to squash from.
+            let sliceMergeStopped = false;
+            await runSafely("postUnit", "slice-cadence-merge", async () => {
+                const prefsResult = loadEffectiveGSDPreferences(s.basePath);
+                const prefs = prefsResult?.preferences;
+                const { getCollapseCadence, mergeSliceToMain } = await import("./slice-cadence.js");
+                if (getCollapseCadence(prefs) !== "slice")
+                    return;
+                if (prefs?.git?.isolation !== "worktree")
+                    return;
+                if (s.isolationDegraded)
+                    return;
+                const projectRoot = s.originalBasePath || s.basePath;
+                const { milestone: mid, slice: sid } = parseUnitId(unit.id);
+                if (!mid || !sid)
+                    return;
+                // Record the milestone start SHA before the first slice merge, so
+                // resquashMilestoneOnMain has a target at milestone completion.
+                // Resolve main branch dynamically — hard-coding "main" breaks repos
+                // that use "master" or a custom default branch.
+                if (!s.milestoneStartShas.has(mid)) {
+                    try {
+                        const { nativeDetectMainBranch } = await import("./native-git-bridge.js");
+                        const mainBranch = nativeDetectMainBranch(projectRoot);
+                        const { execFileSync } = await import("node:child_process");
+                        const sha = execFileSync("git", ["rev-parse", mainBranch], {
+                            cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
+                        }).trim();
+                        if (sha)
+                            s.milestoneStartShas.set(mid, sha);
+                    }
+                    catch (err) {
+                        logWarning("engine", `slice-cadence: failed to record milestone start SHA: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                try {
+                    const result = mergeSliceToMain(projectRoot, mid, sid);
+                    if (result.skipped) {
+                        logWarning("engine", `slice-cadence: merge skipped for ${sid} — ${result.skippedReason}`);
+                        return;
+                    }
+                    ctx.ui.notify(`slice-cadence: ${sid} merged to main (${result.durationMs}ms).`, "info");
+                }
+                catch (err) {
+                    const { MergeConflictError } = await import("./git-service.js");
+                    if (err instanceof MergeConflictError) {
+                        ctx.ui.notify(`slice-cadence merge conflict in ${sid}: ${err.conflictedFiles.join(", ")}. ` +
+                            `Resolve manually on main and run \`/gsd auto\` to resume.`, "error");
+                        // Stop auto AND signal the outer postUnit flow to exit early.
+                        // Without the flag, subsequent hooks (triage, rogue detection,
+                        // DB writes) would keep running against a conflicted main
+                        // checkout after the loop was already told to stop.
+                        const { stopAuto } = await import("./auto.js");
+                        await stopAuto(ctx, undefined, `slice-merge-conflict on ${sid}`);
+                        sliceMergeStopped = true;
+                        return;
+                    }
+                    logError("engine", `slice-cadence merge failed for ${sid}`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    // Non-conflict failures (dirty main, rev-walk error, etc.) can
+                    // leave the checkout in an unexpected state. Stop auto-mode so
+                    // the next slice doesn't dispatch on top of it.
+                    const { stopAuto } = await import("./auto.js");
+                    await stopAuto(ctx, undefined, `slice-merge-error on ${sid}`);
+                    sliceMergeStopped = true;
+                }
+            });
+            // Exit early after stopAuto so the rest of post-unit processing
+            // (triage, rogue detection, hook dispatch, DB writes) doesn't run
+            // against a conflicted main checkout. Return "dispatched" to match
+            // the convention used by other stop/pauseAuto paths in this function
+            // (see signal handling earlier: stop/pause also return "dispatched").
+            if (sliceMergeStopped)
+                return "dispatched";
         }
         // Post-triage: execute actionable resolutions
         if (s.currentUnit.type === "triage-captures") {

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -446,6 +446,40 @@ export async function inlineKnowledgeScoped(base, keywords) {
         return null;
     return `### Project Knowledge (scoped)\nSource: \`${relGsdRootFile("KNOWLEDGE")}\`\n\n${scoped.trim()}`;
 }
+/**
+ * Budget-capped knowledge inline for milestone-level prompt assembly.
+ *
+ * Addresses issue #4719: the six milestone-phase prompts (research-milestone,
+ * plan-milestone, complete-slice, complete-milestone, validate-milestone,
+ * reassess-roadmap) previously injected the full KNOWLEDGE.md (~226KB for a
+ * real project) on every invocation. This helper scopes by caller-supplied
+ * keywords and caps the payload at `maxChars` (default 30,000 chars).
+ *
+ * Returns null when no KNOWLEDGE.md exists or no entries match any keyword.
+ */
+export async function inlineKnowledgeBudgeted(base, keywords, options) {
+    const DEFAULT_MAX_CHARS = 30_000;
+    const HARD_MAX_CHARS = 100_000;
+    const raw = Number(options?.maxChars ?? DEFAULT_MAX_CHARS);
+    const maxChars = Number.isFinite(raw)
+        ? Math.max(0, Math.min(Math.floor(raw), HARD_MAX_CHARS))
+        : DEFAULT_MAX_CHARS;
+    const knowledgePath = resolveGsdRootFile(base, "KNOWLEDGE");
+    if (!existsSync(knowledgePath))
+        return null;
+    const content = await loadFile(knowledgePath);
+    if (!content)
+        return null;
+    const { queryKnowledge } = await import("./context-store.js");
+    const scoped = await queryKnowledge(content, keywords);
+    if (!scoped)
+        return null;
+    const trimmed = scoped.trim();
+    const truncated = trimmed.length > maxChars
+        ? `${trimmed.slice(0, maxChars)}\n\n[...truncated ${trimmed.length - maxChars} chars; rerun with narrower scope if needed]`
+        : trimmed;
+    return `### Project Knowledge (scoped)\nSource: \`${relGsdRootFile("KNOWLEDGE")}\`\n\n${truncated}`;
+}
 /**
  * Inline a roadmap excerpt for a specific slice.
  * Reads full roadmap, extracts minimal excerpt with header + predecessor + target row.
@@ -958,7 +992,8 @@ export async function buildResearchMilestonePrompt(mid, midTitle, base) {
     const decisionsInline = await inlineDecisionsFromDb(base, mid);
     if (decisionsInline)
         inlined.push(decisionsInline);
-    const knowledgeInlineRM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719
+    const knowledgeInlineRM = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
     if (knowledgeInlineRM)
         inlined.push(knowledgeInlineRM);
     inlined.push(inlineTemplate("research", "Research"));
@@ -1015,7 +1050,8 @@ export async function buildPlanMilestonePrompt(mid, midTitle, base, level) {
         const queueInline = await inlineFileSmart(queuePath, relGsdRootFile("QUEUE"), "Project Queue", `${mid} ${midTitle}`);
         inlined.push(queueInline);
     }
-    const knowledgeInlinePM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719
+    const knowledgeInlinePM = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
     if (knowledgeInlinePM)
         inlined.push(knowledgeInlinePM);
     inlined.push(inlineTemplate("roadmap", "Roadmap"));
@@ -1417,7 +1453,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
         }),
     });
 }
-export async function buildCompleteSlicePrompt(mid, _midTitle, sid, sTitle, base, level) {
+export async function buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, base, level) {
     const inlineLevel = level ?? resolveInlineLevel();
     const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
     const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
@@ -1436,7 +1472,9 @@ export async function buildCompleteSlicePrompt(mid, _midTitle, sid, sTitle, base
         if (requirementsInline)
             inlined.push(requirementsInline);
     }
-    const knowledgeInlineCS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719. Slice context is richer than
+    // milestone context at complete-slice time, so combine both title sources.
+    const knowledgeInlineCS = await inlineKnowledgeBudgeted(base, [...extractKeywords(midTitle), ...extractKeywords(sTitle)]);
     if (knowledgeInlineCS)
         inlined.push(knowledgeInlineCS);
     // Inline all task summaries for this slice
@@ -1532,7 +1570,8 @@ export async function buildCompleteMilestonePrompt(mid, midTitle, base, level) {
         if (projectInline)
             inlined.push(projectInline);
     }
-    const knowledgeInlineCM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719
+    const knowledgeInlineCM = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
     if (knowledgeInlineCM)
         inlined.push(knowledgeInlineCM);
     // Inline milestone context file (milestone-level, not GSD root)
@@ -1671,7 +1710,8 @@ export async function buildValidateMilestonePrompt(mid, midTitle, base, level) {
         if (projectInline)
             inlined.push(projectInline);
     }
-    const knowledgeInline = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719
+    const knowledgeInline = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
     if (knowledgeInline)
         inlined.push(knowledgeInline);
     // Inline milestone context file
@@ -1841,7 +1881,8 @@ export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId
         if (decisionsInline)
             inlined.push(decisionsInline);
     }
-    const knowledgeInlineRA = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
+    // Scoped + budgeted — see issue #4719
+    const knowledgeInlineRA = await inlineKnowledgeBudgeted(base, extractKeywords(midTitle));
     if (knowledgeInlineRA)
         inlined.push(knowledgeInlineRA);
     const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);