gsd-pi 2.58.0 → 2.59.0-dev.3de3832

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -113,14 +113,6 @@ export function registerDbTools(pi) {
             };
         }
         try {
-            const db = await import("../gsd-db.js");
-            const existing = db.getRequirementById(params.id);
-            if (!existing) {
-                return {
-                    content: [{ type: "text", text: `Error: Requirement ${params.id} not found.` }],
-                    details: { operation: "update_requirement", id: params.id, error: "not_found" },
-                };
-            }
             const { updateRequirementInDb } = await import("../db-writer.js");
             const updates = {};
             if (params.status !== undefined)
@@ -193,6 +185,86 @@ export function registerDbTools(pi) {
     };
     pi.registerTool(requirementUpdateTool);
     registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
+    // ─── gsd_requirement_save ─────────────────────────────────────────────
+    const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot save requirement." }],
+                details: { operation: "save_requirement", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { saveRequirementToDb } = await import("../db-writer.js");
+            const result = await saveRequirementToDb({
+                class: params.class,
+                status: params.status,
+                description: params.description,
+                why: params.why,
+                source: params.source,
+                primary_owner: params.primary_owner,
+                supporting_slices: params.supporting_slices,
+                validation: params.validation,
+                notes: params.notes,
+            }, process.cwd());
+            return {
+                content: [{ type: "text", text: `Saved requirement ${result.id}` }],
+                details: { operation: "save_requirement", id: result.id },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logError("tool", `gsd_requirement_save tool failed: ${msg}`, { tool: "gsd_requirement_save", error: String(err) });
+            return {
+                content: [{ type: "text", text: `Error saving requirement: ${msg}` }],
+                details: { operation: "save_requirement", error: msg },
+            };
+        }
+    };
+    const requirementSaveTool = {
+        name: "gsd_requirement_save",
+        label: "Save Requirement",
+        description: "Record a new requirement to the GSD database and regenerate REQUIREMENTS.md. " +
+            "Requirement IDs are auto-assigned — never provide an ID manually.",
+        promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
+        promptGuidelines: [
+            "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+            "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
+            "class, description, why, and source are required. All other fields are optional.",
+            "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
+        ],
+        parameters: Type.Object({
+            class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+            description: Type.String({ description: "Short description of the requirement" }),
+            why: Type.String({ description: "Why this requirement matters" }),
+            source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
+            status: Type.Optional(Type.String({ description: "Status (default: 'active')" })),
+            primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })),
+            supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
+            validation: Type.Optional(Type.String({ description: "Validation criteria" })),
+            notes: Type.Optional(Type.String({ description: "Additional notes" })),
+        }),
+        execute: requirementSaveExecute,
+        renderCall(args, theme) {
+            let text = theme.fg("toolTitle", theme.bold("requirement_save "));
+            if (args.class)
+                text += theme.fg("accent", `[${args.class}] `);
+            if (args.description)
+                text += theme.fg("muted", args.description);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            let text = theme.fg("success", `Requirement ${d?.id ?? ""} saved`);
+            text += theme.fg("dim", ` → REQUIREMENTS.md`);
+            return new Text(text, 0, 0);
+        },
+    };
+    pi.registerTool(requirementSaveTool);
+    registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
     // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
     const summarySaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const dbAvailable = await ensureDbOpen();

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -26,6 +26,29 @@ export function resolveProjectRootDbPath(basePath) {
         const projectRoot = basePath.slice(0, fwdIdx);
         return join(projectRoot, ".gsd", "gsd.db");
     }
+    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/M001/...
+    // The project root is everything before /.gsd/projects/ (#2517)
+    const symlinkMarker = `${sep}.gsd${sep}projects${sep}`;
+    const symlinkIdx = basePath.indexOf(symlinkMarker);
+    if (symlinkIdx !== -1) {
+        const afterProjects = basePath.slice(symlinkIdx + symlinkMarker.length);
+        // Expect: <hash>/worktrees/...
+        const worktreeSeg = `${sep}worktrees${sep}`;
+        if (afterProjects.includes(worktreeSeg)) {
+            const projectRoot = basePath.slice(0, symlinkIdx);
+            return join(projectRoot, ".gsd", "gsd.db");
+        }
+    }
+    // Forward-slash variant for symlink-resolved layout
+    const fwdSymlinkMarker = "/.gsd/projects/";
+    const fwdSymlinkIdx = basePath.indexOf(fwdSymlinkMarker);
+    if (fwdSymlinkIdx !== -1) {
+        const afterProjects = basePath.slice(fwdSymlinkIdx + fwdSymlinkMarker.length);
+        if (afterProjects.includes("/worktrees/")) {
+            const projectRoot = basePath.slice(0, fwdSymlinkIdx);
+            return join(projectRoot, ".gsd", "gsd.db");
+        }
+    }
     return join(basePath, ".gsd", "gsd.db");
 }
 export async function ensureDbOpen() {
@@ -70,9 +93,17 @@ export async function ensureDbOpen() {
                 setLogBasePath(projectRoot);
             return opened;
         }
+        process.stderr.write(`gsd-db: ensureDbOpen failed — no .gsd directory found (resolvedPath=${resolveProjectRootDbPath(basePath)}, cwd=${basePath})\n`);
         return false;
     }
-    catch {
+    catch (err) {
+        const basePath = process.cwd();
+        const diagnostic = {
+            resolvedPath: resolveProjectRootDbPath(basePath),
+            cwd: basePath,
+            error: err.message ?? String(err),
+        };
+        process.stderr.write(`gsd-db: ensureDbOpen failed — ${JSON.stringify(diagnostic)}\n`);
         return false;
     }
 }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -3,8 +3,9 @@ import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
-import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
+import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockQueueExecution } from "./write-gate.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
+import { cleanupQuickBranch } from "../quick.js";
 import { getDiscussionMilestoneId } from "../guided-flow.js";
 import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -13,8 +14,6 @@ import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markTool
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
-import { startRtkStatusUpdates, stopRtkStatusUpdates } from "../rtk-status.js";
-import { rewriteCommandWithRtk } from "../../shared/rtk.js";
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
@@ -23,19 +22,10 @@ async function syncServiceTierStatus(ctx) {
     ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
 export function registerHooks(pi) {
-    // Route all agent bash tool commands through RTK rewrite when opted in.
-    // This is a no-op when RTK is disabled or not installed.
-    pi.on("bash_transform", async (event) => {
-        const rewritten = rewriteCommandWithRtk(event.command);
-        if (rewritten === event.command)
-            return undefined;
-        return { command: rewritten };
-    });
     pi.on("session_start", async (_event, ctx) => {
         resetWriteGateState();
         resetToolCallLoopGuard();
         await syncServiceTierStatus(ctx);
-        startRtkStatusUpdates(ctx);
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -52,27 +42,20 @@ export function registerHooks(pi) {
                 if (gsdBinPath) {
                     const { dirname } = await import("node:path");
                     const { printWelcomeScreen } = await import(join(dirname(gsdBinPath), "welcome-screen.js"));
-                    printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0" });
+                    let remoteChannel;
+                    try {
+                        const { resolveRemoteConfig } = await import("../../remote-questions/config.js");
+                        const rc = resolveRemoteConfig();
+                        if (rc)
+                            remoteChannel = rc.channel;
+                    }
+                    catch { /* non-fatal */ }
+                    printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0", remoteChannel });
                 }
             }
             catch { /* non-fatal */ }
         }
         loadToolApiKeys();
-        try {
-            const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([
-                import("../../remote-questions/config.js"),
-                import("../../remote-questions/status.js"),
-            ]);
-            const status = getRemoteConfigStatus();
-            const latest = getLatestPromptSummary();
-            if (!status.includes("not configured")) {
-                const suffix = latest ? `\nLast remote prompt: ${latest.id} (${latest.status})` : "";
-                ctx.ui.notify(`${status}${suffix}`, status.includes("disabled") ? "warning" : "info");
-            }
-        }
-        catch {
-            // ignore
-        }
     });
     pi.on("session_switch", async (_event, ctx) => {
         resetWriteGateState();
@@ -80,10 +63,6 @@ export function registerHooks(pi) {
         clearDiscussionFlowState();
         await syncServiceTierStatus(ctx);
         loadToolApiKeys();
-        startRtkStatusUpdates(ctx);
-    });
-    pi.on("session_fork", async (_event, ctx) => {
-        startRtkStatusUpdates(ctx);
     });
     pi.on("before_agent_start", async (event, ctx) => {
         return buildBeforeAgentStartResult(event, ctx);
@@ -92,6 +71,17 @@ export function registerHooks(pi) {
         resetToolCallLoopGuard();
         await handleAgentEnd(pi, event, ctx);
     });
+    // Squash-merge quick-task branch back to the original branch after the
+    // agent turn completes (#2668). cleanupQuickBranch is a no-op when no
+    // quick-return state is pending, so this is safe to call on every turn.
+    pi.on("turn_end", async () => {
+        try {
+            cleanupQuickBranch();
+        }
+        catch {
+            // Best-effort: don't break the turn lifecycle if cleanup fails.
+        }
+    });
     pi.on("session_before_compact", async () => {
         if (isAutoActive() || isAutoPaused()) {
             return { cancel: true };
@@ -130,7 +120,6 @@ export function registerHooks(pi) {
         }));
     });
     pi.on("session_shutdown", async (_event, ctx) => {
-        stopRtkStatusUpdates(ctx);
         if (isParallelActive()) {
             try {
                 await shutdownParallel(process.cwd());
@@ -152,6 +141,25 @@ export function registerHooks(pi) {
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
+        // ── Queue-mode execution guard (#2545): block source-code mutations ──
+        // When /gsd queue is active, the agent should only create milestones,
+        // not execute work. Block write/edit to non-.gsd/ paths and bash commands
+        // that would modify files.
+        if (isQueuePhaseActive()) {
+            let queueInput = "";
+            if (isToolCallEventType("write", event)) {
+                queueInput = event.input.path;
+            }
+            else if (isToolCallEventType("edit", event)) {
+                queueInput = event.input.path;
+            }
+            else if (isToolCallEventType("bash", event)) {
+                queueInput = event.input.command;
+            }
+            const queueGuard = shouldBlockQueueExecution(event.toolName, queueInput, true);
+            if (queueGuard.block)
+                return queueGuard;
+        }
         // ── Single-writer engine: block direct writes to STATE.md ──────────
         // Covers write, edit, and bash tools to prevent bypass vectors.
         if (isToolCallEventType("write", event)) {
@@ -227,7 +235,7 @@ export function registerHooks(pi) {
     pi.on("tool_execution_start", async (event) => {
         if (!isAutoActive())
             return;
-        markToolStart(event.toolCallId, event.toolName);
+        markToolStart(event.toolCallId);
     });
     pi.on("tool_execution_end", async (event) => {
         markToolEnd(event.toolCallId);

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { debugTime } from "../debug-logger.js";
 import { loadPrompt } from "../prompt-loader.js";
+import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
@@ -70,27 +71,48 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             newSkillsBlock = formatSkillsXml(newSkills);
         }
     }
+    let codebaseBlock = "";
+    const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE");
+    if (existsSync(codebasePath)) {
+        try {
+            const rawContent = readFileSync(codebasePath, "utf-8").trim();
+            if (rawContent) {
+                // Cap injection size to ~2 000 tokens to avoid bloating every request.
+                // Full map is always available at .gsd/CODEBASE.md.
+                const MAX_CODEBASE_CHARS = 8_000;
+                const generatedMatch = rawContent.match(/Generated: (\S+)/);
+                const generatedAt = generatedMatch?.[1] ?? "unknown";
+                const content = rawContent.length > MAX_CODEBASE_CHARS
+                    ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
+                    : rawContent;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, may be stale — run /gsd codebase update to refresh)]\n\n${content}`;
+            }
+        }
+        catch {
+            // skip
+        }
+    }
     warnDeprecatedAgentInstructions();
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+    // Re-inject forensics context on follow-up turns (#2941)
+    const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd()) : null;
     const worktreeBlock = buildWorktreeContextBlock();
-    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
     stopContextTimer({
         systemPromptSize: fullSystem.length,
-        injectionSize: injection?.length ?? 0,
+        injectionSize: injection?.length ?? forensicsInjection?.length ?? 0,
         hasPreferences: preferenceBlock.length > 0,
         hasNewSkills: newSkillsBlock.length > 0,
     });
+    // Determine which context message to inject (guided execute takes priority)
+    const contextMessage = injection
+        ? { customType: "gsd-guided-context", content: injection, display: false }
+        : forensicsInjection
+            ? { customType: "gsd-forensics", content: forensicsInjection, display: false }
+            : null;
     return {
         systemPrompt: fullSystem,
-        ...(injection
-            ? {
-                message: {
-                    customType: "gsd-guided-context",
-                    content: injection,
-                    display: false,
-                },
-            }
-            : {}),
+        ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
@@ -332,3 +354,35 @@ function escapeRegExp(value) {
 function oneLine(text) {
     return text.replace(/\s+/g, " ").trim();
 }
+// ─── Forensics Context Re-injection (#2941) ──────────────────────────────────
+/**
+ * Check for an active forensics session and return the prompt content
+ * so it can be re-injected on follow-up turns.
+ */
+function buildForensicsContextInjection(basePath) {
+    const marker = readForensicsMarker(basePath);
+    if (!marker)
+        return null;
+    // Expire markers older than 2 hours to avoid stale context
+    const age = Date.now() - new Date(marker.createdAt).getTime();
+    if (age > 2 * 60 * 60 * 1000) {
+        clearForensicsMarker(basePath);
+        return null;
+    }
+    return marker.promptContent;
+}
+/**
+ * Remove the active forensics marker file, e.g. when the investigation
+ * is complete or the session expires.
+ */
+export function clearForensicsMarker(basePath) {
+    const markerPath = join(basePath, ".gsd", "runtime", "active-forensics.json");
+    if (existsSync(markerPath)) {
+        try {
+            unlinkSync(markerPath);
+        }
+        catch {
+            // non-fatal
+        }
+    }
+}

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,4 +1,27 @@
 const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+/**
+ * Path segment that identifies .gsd/ planning artifacts.
+ * Writes to these paths are allowed during queue mode.
+ */
+const GSD_DIR_RE = /(^|[/\\])\.gsd([/\\]|$)/;
+/**
+ * Read-only tool names that are always safe during queue mode.
+ */
+const QUEUE_SAFE_TOOLS = new Set([
+    "read", "grep", "find", "ls", "glob",
+    // Discussion & planning tools
+    "ask_user_questions",
+    "gsd_milestone_generate_id",
+    "gsd_summary_save",
+    // Web research tools used during queue discussion
+    "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
+    "search_and_read",
+]);
+/**
+ * Bash commands that are read-only / investigative — safe during queue mode.
+ * Matches the leading command in a bash invocation.
+ */
+const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s)/;
 let depthVerificationDone = false;
 let activeQueuePhase = false;
 export function isDepthVerified() {
@@ -36,3 +59,47 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, depthV
         reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
     };
 }
+/**
+ * Queue-mode execution guard (#2545).
+ *
+ * When the queue phase is active, the agent should only create planning
+ * artifacts (milestones, CONTEXT.md, QUEUE.md, etc.) — never execute work.
+ * This function blocks write/edit/bash tool calls that would modify source
+ * code outside of .gsd/.
+ *
+ * @param toolName  The tool being called (write, edit, bash, etc.)
+ * @param input     For write/edit: the file path. For bash: the command string.
+ * @param queuePhaseActive  Whether the queue phase is currently active.
+ * @returns { block, reason } — block=true if the call should be rejected.
+ */
+export function shouldBlockQueueExecution(toolName, input, queuePhaseActive) {
+    if (!queuePhaseActive)
+        return { block: false };
+    // Always-safe tools (read-only, discussion, planning)
+    if (QUEUE_SAFE_TOOLS.has(toolName))
+        return { block: false };
+    // write/edit — allow if targeting .gsd/ planning artifacts
+    if (toolName === "write" || toolName === "edit") {
+        if (GSD_DIR_RE.test(input))
+            return { block: false };
+        return {
+            block: true,
+            reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` +
+                `Cannot ${toolName} to "${input}" during queue mode. ` +
+                `Write CONTEXT.md files and update PROJECT.md/QUEUE.md instead.`,
+        };
+    }
+    // bash — allow read-only/investigative commands, block everything else
+    if (toolName === "bash") {
+        if (BASH_READ_ONLY_RE.test(input))
+            return { block: false };
+        return {
+            block: true,
+            reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` +
+                `Cannot run "${input.slice(0, 80)}${input.length > 80 ? "…" : ""}" during queue mode. ` +
+                `Use read-only commands (cat, grep, git log, etc.) to investigate, then write planning artifacts.`,
+        };
+    }
+    // Unknown tools — allow by default (custom extension tools, etc.)
+    return { block: false };
+}

package/dist/resources/extensions/gsd/captures.js

@@ -134,7 +134,7 @@ export function countPendingCaptures(basePath) {
  * Mark a capture as resolved with classification and rationale.
  * Rewrites the entry in place, preserving other entries.
  */
-export function markCaptureResolved(basePath, captureId, classification, resolution, rationale) {
+export function markCaptureResolved(basePath, captureId, classification, resolution, rationale, milestoneId) {
     const filePath = resolveCapturesPath(basePath);
     if (!existsSync(filePath))
         return;
@@ -155,12 +155,16 @@ export function markCaptureResolved(basePath, captureId, classification, resolut
         `**Rationale:** ${rationale}`,
         `**Resolved:** ${resolvedAt}`,
     ];
-    // Remove any existing classification/resolution/rationale/resolved fields
+    if (milestoneId) {
+        newFields.push(`**Milestone:** ${milestoneId}`);
+    }
+    // Remove any existing classification/resolution/rationale/resolved/milestone fields
     // (in case of re-triage)
     section = section.replace(/\*\*Classification:\*\*\s*.+\n?/g, "");
     section = section.replace(/\*\*Resolution:\*\*\s*.+\n?/g, "");
     section = section.replace(/\*\*Rationale:\*\*\s*.+\n?/g, "");
     section = section.replace(/\*\*Resolved:\*\*\s*.+\n?/g, "");
+    section = section.replace(/\*\*Milestone:\*\*\s*.+\n?/g, "");
     // Add new fields after Status line
     section = section.trimEnd() + "\n" + newFields.join("\n") + "\n";
     const updated = content.replace(sectionRegex, section);
@@ -192,13 +196,59 @@ export function markCaptureExecuted(basePath, captureId) {
  * Load resolved captures that have actionable classifications (inject, replan,
  * quick-task) but have NOT yet been executed.
  * These are captures whose resolutions need to be carried out.
+ *
+ * When `currentMilestoneId` is provided, captures resolved in a *different*
+ * milestone are treated as stale and excluded.  This prevents quick-task
+ * captures from a prior milestone re-executing after the underlying issues
+ * were already fixed by planned milestone work (#2872).
+ *
+ * Captures that have no `resolvedInMilestone` (legacy captures resolved before
+ * this field was introduced) are always included for backward compatibility.
  */
-export function loadActionableCaptures(basePath) {
+export function loadActionableCaptures(basePath, currentMilestoneId) {
     return loadAllCaptures(basePath).filter(c => c.status === "resolved" &&
         !c.executed &&
         (c.classification === "inject" ||
             c.classification === "replan" ||
-            c.classification === "quick-task"));
+            c.classification === "quick-task") &&
+        // Staleness gate: exclude captures resolved in a different milestone (#2872)
+        (!currentMilestoneId ||
+            !c.resolvedInMilestone ||
+            c.resolvedInMilestone === currentMilestoneId));
+}
+/**
+ * Retroactively stamp a capture with a milestone ID.
+ *
+ * Used by executeTriageResolutions() as a safety net when the triage LLM
+ * resolves a capture without writing the **Milestone:** field.  This ensures
+ * the staleness gate in loadActionableCaptures() works correctly even for
+ * captures resolved before the prompt was updated (#2872).
+ */
+export function stampCaptureMilestone(basePath, captureId, milestoneId) {
+    const filePath = resolveCapturesPath(basePath);
+    if (!existsSync(filePath))
+        return;
+    const content = readFileSync(filePath, "utf-8");
+    const sectionRegex = new RegExp(`(### ${escapeRegex(captureId)}\\n(?:(?!### ).)*?)(?=### |$)`, "s");
+    const match = sectionRegex.exec(content);
+    if (!match)
+        return;
+    let section = match[1];
+    // Only stamp if not already present
+    if (/\*\*Milestone:\*\*/.test(section))
+        return;
+    // Insert after the Resolved field (or at end of section)
+    const resolvedFieldEnd = section.search(/\*\*Resolved:\*\*\s*.+\n?/);
+    if (resolvedFieldEnd !== -1) {
+        const resolvedMatch = section.match(/\*\*Resolved:\*\*\s*.+\n?/);
+        const insertPos = resolvedFieldEnd + (resolvedMatch?.[0]?.length ?? 0);
+        section = section.slice(0, insertPos) + `**Milestone:** ${milestoneId}\n` + section.slice(insertPos);
+    }
+    else {
+        section = section.trimEnd() + "\n" + `**Milestone:** ${milestoneId}` + "\n";
+    }
+    const updated = content.replace(sectionRegex, section);
+    writeFileSync(filePath, updated, "utf-8");
 }
 // ─── Parser ───────────────────────────────────────────────────────────────────
 /**
@@ -221,6 +271,7 @@ function parseCapturesContent(content) {
         const resolution = extractBoldField(body, "Resolution");
         const rationale = extractBoldField(body, "Rationale");
         const resolvedAt = extractBoldField(body, "Resolved");
+        const milestoneId = extractBoldField(body, "Milestone");
         const executedAt = extractBoldField(body, "Executed");
         if (!text || !timestamp)
             continue;
@@ -236,6 +287,7 @@ function parseCapturesContent(content) {
             ...(resolution ? { resolution } : {}),
             ...(rationale ? { rationale } : {}),
             ...(resolvedAt ? { resolvedAt } : {}),
+            ...(milestoneId ? { resolvedInMilestone: milestoneId } : {}),
             ...(executedAt ? { executed: true } : {}),
         });
     }