gsd-pi 2.76.0 → 2.77.0-dev.538325aea

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

@@ -19,6 +19,18 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+/**
+ * Read a tool result's structured payload, accommodating MCP's `details` →
+ * `structuredContent` rename (#4472, #4477). In-process executions still
+ * deliver the payload on `result.details`; MCP-routed executions deliver it
+ * on `result.structuredContent` (post `adaptExecutorResult` transform). All
+ * `renderResult` callbacks in this file route through this helper so a future
+ * field rename only needs to be applied in one place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
+function readDetails(result) {
+    return result?.details ?? result?.structuredContent;
+}
 export function registerDbTools(pi) {
     // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
     const decisionSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -92,7 +104,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -175,7 +187,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -255,7 +267,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -301,7 +313,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -382,7 +394,7 @@ export function registerDbTools(pi) {
             return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -967,13 +979,31 @@ export function registerDbTools(pi) {
             text += theme.fg("dim", ` → ${args.verdict ?? ""}`);
             return new Text(text, 0, 0);
         },
+        /**
+         * Render the save_gate_result tool output for the TUI.
+         *
+         * Prefers structured fields, but falls back to `content[0].text` when the
+         * structured payload is empty. Defensive: the structural fix on this
+         * branch plumbs `details` through MCP via `structuredContent`, but older
+         * hosts, a future handler that forgets `structuredContent`, or any drop
+         * of non-standard return fields would otherwise render as
+         * "undefined: undefined". Same fallback applies to error rendering, and
+         * we strip a leading `Error:` from the fallback text to avoid producing
+         * `Error: Error: ...`.
+         */
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
-                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+                const rawMsg = d?.error ?? result.content?.[0]?.text ?? "unknown";
+                const msg = rawMsg.replace(/^\s*Error:\s*/i, "");
+                return new Text(theme.fg("error", `Error: ${msg}`), 0, 0);
+            }
+            if (!d?.gateId || !d?.verdict) {
+                const text = result.content?.[0]?.text ?? "Gate result saved";
+                return new Text(theme.fg("success", text), 0, 0);
             }
-            const color = d?.verdict === "flag" ? "warning" : "success";
-            return new Text(theme.fg(color, `${d?.gateId}: ${d?.verdict}`), 0, 0);
+            const color = d.verdict === "flag" ? "warning" : "success";
+            return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
         },
     };
     pi.registerTool(saveGateResultTool);

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

@@ -0,0 +1,93 @@
+// GSD2 — Exec (context-mode) tool registration.
+//
+// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
+// `context_mode.enabled: true` is set in preferences.
+import { Type } from "@sinclair/typebox";
+import { executeGsdExec } from "../tools/exec-tool.js";
+import { executeExecSearch } from "../tools/exec-search-tool.js";
+import { executeResume } from "../tools/resume-tool.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { logWarning } from "../workflow-logger.js";
+export function registerExecTools(pi) {
+    pi.registerTool({
+        name: "gsd_exec",
+        label: "Exec (Sandboxed)",
+        description: "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+            ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
+            "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
+            "count/grep/summarize and log the finding. Enabled by default; opt out via " +
+            "preferences.context_mode.enabled=false.",
+        promptSnippet: "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+        promptGuidelines: [
+            "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
+            "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
+            "The digest is the last ~300 chars of stdout — size your log output accordingly.",
+            "Need the full output? Read the stdout_path returned in details (file on local disk).",
+        ],
+        parameters: Type.Object({
+            runtime: Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." }),
+            script: Type.String({ description: "Script body. Keep output small (log the finding, not the data)." }),
+            purpose: Type.Optional(Type.String({ description: "Short label recorded in meta.json for later review." })),
+            timeout_ms: Type.Optional(Type.Number({
+                description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+                minimum: 1_000,
+                maximum: 600_000,
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            let prefs = null;
+            try {
+                prefs = loadEffectiveGSDPreferences();
+            }
+            catch (err) {
+                logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return executeGsdExec(params, {
+                baseDir: process.cwd(),
+                preferences: prefs?.preferences ?? null,
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_exec_search",
+        label: "Search gsd_exec History",
+        description: "List prior gsd_exec runs (most recent first) from .gsd/exec/*.meta.json. Useful for " +
+            "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.",
+        promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
+        promptGuidelines: [
+            "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
+            "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+        ],
+        parameters: Type.Object({
+            query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
+            runtime: Type.Optional(Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
+                description: "Restrict to one runtime.",
+            })),
+            failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeExecSearch(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_resume",
+        label: "Resume (Read Snapshot)",
+        description: "Return the contents of .gsd/last-snapshot.md — a ≤2 KB digest of top memories, recent " +
+            "gsd_exec runs, and active context, written automatically on session_before_compact. Use " +
+            "this after compaction or session resume to re-orient quickly.",
+        promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss",
+        promptGuidelines: [
+            "Call this right after a session resumes if you feel you've lost durable context.",
+            "The snapshot is a summary — use memory_query or gsd_exec_search for detail.",
+        ],
+        parameters: Type.Object({}),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeResume(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+}

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

@@ -34,6 +34,9 @@ export function registerMemoryTools(pi) {
             confidence: Type.Optional(Type.Number({ description: "0.1–0.99, default 0.8", minimum: 0.1, maximum: 0.99 })),
             tags: Type.Optional(Type.Array(Type.String(), { description: "Free-form tags (reserved for future use)" })),
             scope: Type.Optional(Type.String({ description: "Scope name (reserved for future use; defaults to project)" })),
+            structuredFields: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+                description: "Optional structured payload preserved alongside content (ADR-013). Use for decisions to retain scope/decision/choice/rationale/made_by/revisable. Omit for plain captures.",
+            })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const ok = await ensureDbOpen();

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

@@ -4,6 +4,7 @@ import { registerWorktreeCommand } from "../worktree-command.js";
 import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerExecTools } from "./exec-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
 import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
@@ -58,6 +59,16 @@ export function registerGsdExtension(pi) {
     // so we intentionally skip it here to avoid double-registration.
     registerWorktreeCommand(pi);
     registerExitCommand(pi);
+    // Wire the Layer 2 event emitter bridge so deeply-nested GSD code can emit
+    // extension events (git lifecycle, verify, budget, milestone, unit) without
+    // threading `pi` through every call site.
+    import("../hook-emitter.js")
+        .then(({ setHookEmitter }) => setHookEmitter(pi))
+        .catch((err) => {
+        // Non-fatal — emitters simply become no-ops if this import fails, but
+        // surface the failure so silent bootstrap breakage is debuggable.
+        process.stderr.write(`[gsd] Failed to bootstrap hook-emitter bridge: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    });
     installEpipeGuard();
     // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
     // GSD-owned `before_agent_start` dispatch step (#3338).
@@ -76,6 +87,7 @@ export function registerGsdExtension(pi) {
         ["journal-tools", () => registerJournalTools(pi)],
         ["query-tools", () => registerQueryTools(pi)],
         ["memory-tools", () => registerMemoryTools(pi)],
+        ["exec-tools", () => registerExecTools(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
         ["hooks", () => registerHooks(pi, ecosystemHandlers)],
         ["ecosystem", () => {

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

@@ -13,12 +13,12 @@ import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { deriveState } from "../state.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
-import { hideFooter } from "../auto-dashboard.js";
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
 import { resetAskUserQuestionsCache } from "../../ask-user-questions.js";
-import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult } from "../safety/evidence-collector.js";
+import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
+import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
@@ -37,7 +37,9 @@ export function registerHooks(pi, ecosystemHandlers) {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
         initNotificationWidget(ctx);
-        initHealthWidget(ctx);
+        if (!isAutoActive()) {
+            initHealthWidget(ctx);
+        }
         resetWriteGateState();
         resetToolCallLoopGuard();
         resetAskUserQuestionsCache();
@@ -79,7 +81,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         loadToolApiKeys();
         if (isAutoActive()) {
-            ctx.ui.setFooter(hideFooter);
+            ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
@@ -101,7 +103,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         loadToolApiKeys();
         if (isAutoActive()) {
-            ctx.ui.setFooter(hideFooter);
+            ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
@@ -204,6 +206,41 @@ export function registerHooks(pi, ecosystemHandlers) {
             nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
         }));
     });
+    // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
+    // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
+    // preferences.context_mode.enabled. Runs after the auto-cancel handler
+    // above — if that one returned cancel:true, pi still fires us but the
+    // compaction won't actually happen; the snapshot is still useful then,
+    // since auto may pause and resume later.
+    pi.on("session_before_compact", async () => {
+        try {
+            const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+            const { isContextModeEnabled } = await import("../preferences-types.js");
+            const prefs = loadEffectiveGSDPreferences();
+            if (!isContextModeEnabled(prefs?.preferences))
+                return;
+            const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen();
+            const basePath = process.cwd();
+            let activeContext = null;
+            try {
+                const state = await deriveState(basePath);
+                if (state.activeMilestone && state.activeSlice && state.activeTask) {
+                    activeContext =
+                        `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+                            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
+                }
+            }
+            catch {
+                /* non-fatal */
+            }
+            writeCompactionSnapshot(basePath, { activeContext });
+        }
+        catch (err) {
+            safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         if (isParallelActive()) {
             try {
@@ -406,7 +443,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("tool_execution_start", async (event) => {
         if (!isAutoActive())
             return;
-        markToolStart(event.toolCallId);
+        markToolStart(event.toolCallId, event.toolName);
     });
     pi.on("tool_execution_end", async (event) => {
         markToolEnd(event.toolCallId);
@@ -421,6 +458,15 @@ export function registerHooks(pi, ecosystemHandlers) {
         // Safety harness: record tool execution results for evidence cross-referencing
         if (isAutoActive()) {
             safetyRecordToolResult(event.toolCallId, event.toolName, event.result, event.isError);
+            // Persist evidence to disk after each tool result so it survives a session
+            // restart mid-unit (Bug #4385 — non-persisted evidence false positives).
+            const dash = getAutoDashboardData();
+            if (dash.basePath && dash.currentUnit?.type === "execute-task") {
+                const { milestone: pMid, slice: pSid, task: pTid } = parseUnitId(dash.currentUnit.id);
+                if (pMid && pSid && pTid) {
+                    saveEvidenceToDisk(dash.basePath, pMid, pSid, pTid);
+                }
+            }
         }
     });
     pi.on("model_select", async (_event, ctx) => {

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

@@ -24,10 +24,30 @@ const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
  * hardcoding absolute paths in the system prompt template. Only skills
  * that actually exist on disk are included in the table. (#3575)
  */
-const BUNDLED_SKILL_TRIGGERS = [
+export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
     { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
     { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+    { trigger: "Code review - security, performance, bugs, quality review of staged/unstaged diffs or PRs", skill: "review" },
+    { trigger: "Test generation or execution - auto-detect framework, generate tests, run suite, analyze failures", skill: "test" },
+    { trigger: "Linting/formatting - run the detected linter/formatter with auto-fix, report remaining issues", skill: "lint" },
+    { trigger: "Polishing UI details - animations, hover states, typography, borders, micro-interactions, optical alignment", skill: "make-interfaces-feel-better" },
+    { trigger: "Accessibility audit - WCAG, screen reader, keyboard navigation, a11y review", skill: "accessibility" },
+    { trigger: "Planning interviews - stress-test a plan, grill the user, resolve decision trees one branch at a time", skill: "grill-me" },
+    { trigger: "Interface design - produce 3+ radically different designs for a module/API, compare in prose, synthesize", skill: "design-an-interface" },
+    { trigger: "TDD - red-green-refactor vertical slices, never refactor while red, tests survive refactors", skill: "tdd" },
+    { trigger: "Draft a milestone brief (M###-CONTEXT.md) or PRD from current conversation context", skill: "write-milestone-brief" },
+    { trigger: "Break a plan into vertical-slice roadmap slices (M###-ROADMAP.md) or GitHub issues with dependency ordering", skill: "decompose-into-slices" },
+    { trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" },
+    { trigger: "Block completion claims until verification evidence has been produced in this message", skill: "verify-before-complete" },
+    { trigger: "Create a Model Context Protocol (MCP) server — tool design, error handling, Inspector testing, evals", skill: "create-mcp-server" },
+    { trigger: "Write documentation, proposals, specs, RFCs, or READMEs for a fresh reader", skill: "write-docs" },
+    { trigger: "Post-mortem a failed GSD auto-mode run using .gsd/activity, .gsd/journal, and .gsd/metrics.json", skill: "forensics" },
+    { trigger: "Prepare a clean cross-session handoff — continue.md + summary updates (pause/resume work)", skill: "handoff" },
+    { trigger: "Security review with STRIDE threat modeling and exploit-scenario reporting", skill: "security-review" },
+    { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
+    { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
+    { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
 ];
 function buildBundledSkillsTable() {
     const cwd = process.cwd();
@@ -87,33 +107,20 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }
-    let memoryBlock = "";
+    // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+    // and best-effort — first run absorbs the existing decisions table into
+    // the memory store; subsequent runs are a single sentinel SELECT.
     try {
-        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
-        // Always-on "critical" set — small, stable memories that belong in every
-        // turn (gotchas, environment, conventions). Ranked by the existing score.
-        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention"]);
-        const allRanked = getActiveMemoriesRanked(60);
-        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, 5);
-        const criticalIds = new Set(critical.map((m) => m.id));
-        // Prompt-relevance set — hybrid FTS5 + (future) semantic retrieval.
-        let relevant = [];
-        const userPrompt = (event.prompt ?? "").trim();
-        if (userPrompt) {
-            const hits = queryMemoriesRanked({ query: userPrompt, k: 10 });
-            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
-        }
-        const merged = [...critical, ...relevant];
-        if (merged.length > 0) {
-            const formatted = formatMemoriesForPrompt(merged, 2000);
-            if (formatted) {
-                memoryBlock = `\n\n${formatted}`;
-            }
+        const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+        const written = backfillDecisionsToMemories();
+        if (written > 0) {
+            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
         }
     }
     catch (e) {
-        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -183,6 +190,60 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
+/**
+ * ADR-013 step 4 — auto-injection parity for the memories table.
+ *
+ * Mirrors loadKnowledgeBlock by producing a labeled, deterministic block
+ * combining two memory sets:
+ *
+ * 1. Always-on "critical" set — top-ranked active memories in categories
+ *    that future GSD turns generally want without asking. After ADR-013
+ *    expands this to include "architecture", these memories serve as the
+ *    auto-injected replacement for inlineDecisionsFromDb when the cutover
+ *    in step 6 lands.
+ * 2. Prompt-relevance set — FTS5/semantic hits against the current user
+ *    prompt, deduplicated against the critical set.
+ *
+ * Both sets are ranked, merged, and rendered via formatMemoriesForPrompt
+ * with a token-budget cap. Failures degrade gracefully — the function never
+ * throws and returns "" so the system prompt construction continues.
+ */
+export async function loadMemoryBlock(userPrompt) {
+    try {
+        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+        // Categories that belong in every turn. Pre-ADR-013 this was just
+        // {gotcha, environment, convention}. ADR-013 adds "architecture" so
+        // decision-equivalent memories survive the inlineDecisionsFromDb cutover
+        // in step 6.
+        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention", "architecture"]);
+        const CRITICAL_CAP = 8;
+        const QUERY_K = 10;
+        // ~1 token ≈ 4 chars. 4000 chars ≈ 1000 tokens — comfortably under the
+        // KNOWLEDGE.md 4KB warning threshold and roughly twice the pre-ADR-013
+        // budget so the absorbed DECISIONS surface fits.
+        const CHAR_BUDGET = 4000;
+        const allRanked = getActiveMemoriesRanked(80);
+        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, CRITICAL_CAP);
+        const criticalIds = new Set(critical.map((m) => m.id));
+        let relevant = [];
+        const trimmed = userPrompt.trim();
+        if (trimmed) {
+            const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
+            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+        }
+        const merged = [...critical, ...relevant];
+        if (merged.length === 0)
+            return "";
+        const formatted = formatMemoriesForPrompt(merged, CHAR_BUDGET);
+        if (!formatted)
+            return "";
+        return `\n\n[MEMORY — Critical and prompt-relevant memories from the GSD memory store]\n\n${formatted}`;
+    }
+    catch (e) {
+        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        return "";
+    }
+}
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
     // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
     let globalKnowledge = "";

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

@@ -24,8 +24,29 @@ const QUEUE_SAFE_TOOLS = new Set([
 /**
  * Bash commands that are read-only / investigative — safe during queue mode.
  * Matches the leading command in a bash invocation.
+ *
+ * Extension policy: add commands here when they are read-only / diagnostic.
+ * Never add commands that mutate project state (write files, run builds that
+ * emit artifacts, install packages, etc.).
+ *
+ * Current read-only additions (Bug #4385):
+ *   npm run <diagnostic> — read-only diagnostic scripts: test, lint, typecheck, etc.
+ *                         NOT: build, install, compile, generate, deploy (artifact-producing)
+ *   npm ls/list/info    — inspect installed packages (read-only)
+ *   npm outdated/audit  — security/update checks (read-only)
+ *   npx <pkg>           — run a package binary without installing globally
+ *   tsx                 — TypeScript runner used for dry-run / inspection scripts
+ *   node --print        — evaluate and print an expression, no side effects
+ *   python / python3    — script inspection, version checks
+ *   pip / pip3 show     — show installed package info (read-only)
+ *   jq                  — read-only JSON query
+ *   yq                  — read-only YAML query
+ *   curl -s / curl --silent — fetch for inspection (no -o / no output redirect)
+ *   openssl version     — version / certificate inspection
+ *   env / printenv      — print environment variables
+ *   true / false        — shell no-ops / test exit codes
  */
-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)/;
+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|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
 const verifiedDepthMilestones = new Set();
 let activeQueuePhase = false;
 /**
@@ -99,10 +120,21 @@ function normalizeWriteGateSnapshot(value) {
         pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
     };
 }
+const EMPTY_SNAPSHOT = {
+    verifiedDepthMilestones: [],
+    activeQueuePhase: false,
+    pendingGateId: null,
+};
 export function loadWriteGateSnapshot(basePath = process.cwd()) {
     const path = writeGateSnapshotPath(basePath);
-    if (!existsSync(path))
+    if (!existsSync(path)) {
+        // When persist mode is active and the file has been deleted, treat it as a
+        // full state reset so deleting the file clears the HARD BLOCK gate.
+        // In non-persist mode the file is never written, so fall back to in-memory.
+        if (shouldPersistWriteGateSnapshot())
+            return EMPTY_SNAPSHOT;
         return currentWriteGateSnapshot();
+    }
     try {
         return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
     }

package/dist/resources/extensions/gsd/clean-root-preflight.js

@@ -0,0 +1,93 @@
+/**
+ * clean-root-preflight.ts — Preflight gate for dirty working trees before milestone merges.
+ *
+ * #2909: Adds a fast-path git status check before milestone completion merges.
+ * When the working tree is dirty the user is warned and changes are auto-stashed
+ * so the merge can proceed cleanly.  After the merge completes, postflightPopStash
+ * restores the stashed changes.
+ *
+ * Design constraints (from Trek-e approval):
+ *  - Warn the user before stashing (no silent surprises)
+ *  - git stash push / git stash pop only — no custom stash management layer
+ *  - Stash/pop errors are logged but MUST NOT block the merge
+ *  - Fast-path status check — clean trees pay no extra cost
+ */
+import { execFileSync } from "node:child_process";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { logWarning } from "./workflow-logger.js";
+import { nativeHasChanges } from "./native-git-bridge.js";
+/**
+ * Check the working tree for dirty files before a milestone merge.
+ *
+ * Clean tree path: O(1) — returns immediately with stashPushed=false.
+ *
+ * Dirty tree path:
+ *  1. Emits a warning notification via the provided `notify` callback.
+ *  2. Runs `git stash push --include-untracked -m "gsd-preflight-stash"`.
+ *  3. Returns stashPushed=true so the caller knows to call postflightPopStash.
+ *
+ * Any stash error is logged but does NOT throw — the merge proceeds regardless.
+ */
+export function preflightCleanRoot(basePath, milestoneId, notify) {
+    // Fast-path: clean tree — nothing to do
+    let isDirty = false;
+    try {
+        isDirty = nativeHasChanges(basePath);
+    }
+    catch (err) {
+        // If the status check itself fails, treat as clean and let the merge decide
+        logWarning("preflight", `clean-root status check failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { stashPushed: false, summary: "" };
+    }
+    if (!isDirty) {
+        return { stashPushed: false, summary: "" };
+    }
+    // Warn the user before stashing
+    const warnMsg = `Working tree has uncommitted changes before milestone ${milestoneId} merge. Auto-stashing to allow clean merge (stash will be restored after merge).`;
+    notify(warnMsg, "warning");
+    // Push the stash
+    try {
+        execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        return {
+            stashPushed: true,
+            summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
+        };
+    }
+    catch (err) {
+        // Stash failure is non-fatal — log and let the merge attempt proceed
+        const msg = `git stash push failed before merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}`;
+        logWarning("preflight", msg);
+        notify(`Auto-stash failed before milestone ${milestoneId} merge — proceeding anyway. ${msg}`, "warning");
+        return { stashPushed: false, summary: `stash-push-failed: ${msg}` };
+    }
+}
+/**
+ * Restore stashed changes after a milestone merge completes.
+ *
+ * Only called when preflightCleanRoot returned stashPushed=true.
+ * Any pop error (e.g. conflict) is logged and notified but does NOT throw —
+ * the merge already completed successfully.
+ */
+export function postflightPopStash(basePath, milestoneId, notify) {
+    try {
+        execFileSync("git", ["stash", "pop"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        notify(`Restored stashed changes after milestone ${milestoneId} merge.`, "info");
+    }
+    catch (err) {
+        // Pop conflicts mean the merged code collides with the stashed changes.
+        // Log a warning — the user needs to resolve manually, but the merge succeeded.
+        const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+        logWarning("preflight", msg);
+        notify(msg, "warning");
+    }
+}