gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/src/resources/extensions/gsd/bootstrap/exec-tools.ts

@@ -0,0 +1,109 @@
+// 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 type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+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: ExtensionAPI): void {
+  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: Awaited<ReturnType<typeof loadEffectiveGSDPreferences>> | null = null;
+      try {
+        prefs = loadEffectiveGSDPreferences();
+      } catch (err) {
+        logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
+        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 as Parameters<typeof executeExecSearch>[0], {
+        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 as Parameters<typeof executeResume>[0], {
+        baseDir: process.cwd(),
+      });
+    },
+  });
+}

package/src/resources/extensions/gsd/bootstrap/memory-tools.ts

@@ -50,6 +50,11 @@ export function registerMemoryTools(pi: ExtensionAPI): void {
       ),
       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/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -8,6 +8,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 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";
@@ -66,6 +67,19 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
   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
@@ -87,6 +101,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["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/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -18,12 +18,13 @@ 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";
@@ -48,7 +49,9 @@ export function registerHooks(
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
-    initHealthWidget(ctx);
+    if (!isAutoActive()) {
+      initHealthWidget(ctx);
+    }
     resetWriteGateState();
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
@@ -90,7 +93,7 @@ export function registerHooks(
     }
     loadToolApiKeys();
     if (isAutoActive()) {
-      ctx.ui.setFooter(hideFooter);
+      ctx.ui.setWidget("gsd-health", undefined);
     }
   });
 
@@ -113,7 +116,7 @@ export function registerHooks(
     }
     loadToolApiKeys();
     if (isAutoActive()) {
-      ctx.ui.setFooter(hideFooter);
+      ctx.ui.setWidget("gsd-health", undefined);
     }
   });
 
@@ -225,6 +228,42 @@ export function registerHooks(
     }));
   });
 
+  // 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: string | null = 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: ExtensionContext) => {
     if (isParallelActive()) {
       try {
@@ -445,7 +484,7 @@ export function registerHooks(
 
   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) => {
@@ -461,6 +500,15 @@ export function registerHooks(
     // 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);
+        }
+      }
     }
   });
 

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -29,10 +29,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: Array<{ trigger: string; skill: string }> = [
+export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> = [
   { 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(): string {
@@ -111,36 +131,21 @@ export async function buildBeforeAgentStartResult(
     );
   }
 
-  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: typeof allRanked = [];
-    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 as Error).message}`);
+    logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
+  const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
+
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -220,6 +225,64 @@ export async function buildBeforeAgentStartResult(
   };
 }
 
+/**
+ * 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: string): Promise<string> {
+  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: typeof allRanked = [];
+    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 as Error).message}`);
+    return "";
+  }
+}
+
 export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: string; globalSizeKb: number } {
   // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
   let globalKnowledge = "";

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -28,8 +28,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<string>();
 let activeQueuePhase = false;
@@ -117,9 +138,21 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   };
 }
 
+const EMPTY_SNAPSHOT: WriteGateSnapshot = {
+  verifiedDepthMilestones: [],
+  activeQueuePhase: false,
+  pendingGateId: null,
+};
+
 export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
-  if (!existsSync(path)) return currentWriteGateSnapshot();
+  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")));
   } catch {

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -0,0 +1,111 @@
+/**
+ * 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";
+
+export interface PreflightResult {
+  /** true when a stash was pushed and postflightPopStash should be called */
+  stashPushed: boolean;
+  /** human-readable summary of what happened (empty string for clean trees) */
+  summary: string;
+}
+
+/**
+ * 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: string,
+  milestoneId: string,
+  notify: (message: string, level: "info" | "warning" | "error") => void,
+): PreflightResult {
+  // 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: string,
+  milestoneId: string,
+  notify: (message: string, level: "info" | "warning" | "error") => void,
+): void {
+  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");
+  }
+}