gsd-pi 2.76.0 → 2.77.0

package/src/resources/extensions/gsd/preferences-types.ts

@@ -28,6 +28,37 @@ export interface ContextManagementConfig {
   compaction_threshold_percent?: number;  // default: 0.70, range: 0.5-0.95
   tool_result_max_chars?: number;         // default: 800, range: 200-10000
 }
+
+/**
+ * Opt-in tool-output sandboxing for sub-sessions. When enabled, the gsd_exec
+ * MCP tool runs scripts in an isolated subprocess and returns only a short
+ * digest to the calling agent's context window; full stdout/stderr persist
+ * in the project memory store and can be retrieved by id later.
+ *
+ * Inspired by mksglu/context-mode (Elastic License 2.0). This is an
+ * independent implementation — no upstream code is incorporated.
+ */
+export interface ContextModeConfig {
+  /** Master switch. Default: true (opt-out via `enabled: false`). */
+  enabled?: boolean;
+  /** Per-invocation timeout in milliseconds. Default: 30_000. Range: 1_000–600_000. */
+  exec_timeout_ms?: number;
+  /** Cap on persisted stdout bytes per invocation. Default: 1_048_576 (1 MiB). Range: 4_096–16_777_216. */
+  exec_stdout_cap_bytes?: number;
+  /** Number of trailing stdout characters returned in the digest. Default: 300. Range: 0–4_000. */
+  exec_digest_chars?: number;
+  /** Environment variables forwarded to sandboxed processes (case-sensitive names). PATH and HOME are always forwarded. */
+  exec_env_allowlist?: string[];
+}
+
+/**
+ * Resolve whether context-mode features (gsd_exec sandbox + compaction
+ * snapshot) should be active. Default is ON: missing config or missing
+ * `enabled` is treated as true. Only `enabled: false` disables.
+ */
+export function isContextModeEnabled(prefs: { context_mode?: ContextModeConfig } | null | undefined): boolean {
+  return prefs?.context_mode?.enabled !== false;
+}
 import type { GitHubSyncConfig } from "../github-sync/types.js";
 
 // ─── Workflow Modes ──────────────────────────────────────────────────────────
@@ -117,6 +148,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "flat_rate_providers",
   "language",
   "context_window_override",
+  "context_mode",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -300,6 +332,12 @@ export interface GSDPreferences {
    */
   context_window_override?: number;
   context_management?: ContextManagementConfig;
+  /**
+   * Tool-output sandboxing via gsd_exec. Keeps sub-session context windows
+   * clean by running scripts in a subprocess and only surfacing a short
+   * digest. See `ContextModeConfig`. Default: disabled.
+   */
+  context_mode?: ContextModeConfig;
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
   auto_visualize?: boolean;
@@ -354,6 +392,14 @@ export interface GSDPreferences {
     checkpoints?: boolean;
     auto_rollback?: boolean;
     timeout_scale_cap?: number;
+    /**
+     * Glob patterns for files that are always expected side-effects of any task.
+     * Files matching any pattern here are excluded from unexpected-change warnings.
+     * Supports standard glob syntax (e.g. `tracking/history/**`, `*.log`).
+     * Fixes #4385/#4436 — audit-trail snapshots, build artifacts, and other
+     * project-level secondary writes shouldn't require per-task declaration.
+     */
+    file_change_allowlist?: string[];
   };
 
 

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -644,6 +644,50 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Context Mode (gsd_exec sandbox) ────────────────────────────────────
+  if (preferences.context_mode !== undefined) {
+    if (typeof preferences.context_mode === "object" && preferences.context_mode !== null) {
+      const cmode = preferences.context_mode as unknown as Record<string, unknown>;
+      const validCmode: Record<string, unknown> = {};
+
+      if (cmode.enabled !== undefined) {
+        if (typeof cmode.enabled === "boolean") validCmode.enabled = cmode.enabled;
+        else errors.push("context_mode.enabled must be a boolean");
+      }
+      if (cmode.exec_timeout_ms !== undefined) {
+        const t = cmode.exec_timeout_ms;
+        if (typeof t === "number" && t >= 1000 && t <= 600_000) validCmode.exec_timeout_ms = Math.floor(t);
+        else errors.push("context_mode.exec_timeout_ms must be a number between 1000 and 600000");
+      }
+      if (cmode.exec_stdout_cap_bytes !== undefined) {
+        const b = cmode.exec_stdout_cap_bytes;
+        if (typeof b === "number" && b >= 4096 && b <= 16_777_216) validCmode.exec_stdout_cap_bytes = Math.floor(b);
+        else errors.push("context_mode.exec_stdout_cap_bytes must be a number between 4096 and 16777216");
+      }
+      if (cmode.exec_digest_chars !== undefined) {
+        const c = cmode.exec_digest_chars;
+        if (typeof c === "number" && c >= 0 && c <= 4000) validCmode.exec_digest_chars = Math.floor(c);
+        else errors.push("context_mode.exec_digest_chars must be a number between 0 and 4000");
+      }
+      if (cmode.exec_env_allowlist !== undefined) {
+        if (
+          Array.isArray(cmode.exec_env_allowlist) &&
+          cmode.exec_env_allowlist.every((v) => typeof v === "string" && /^[A-Z_][A-Z0-9_]*$/i.test(v))
+        ) {
+          validCmode.exec_env_allowlist = cmode.exec_env_allowlist;
+        } else {
+          errors.push("context_mode.exec_env_allowlist must be an array of valid env var names");
+        }
+      }
+
+      if (Object.keys(validCmode).length > 0) {
+        validated.context_mode = validCmode as any;
+      }
+    } else {
+      errors.push("context_mode must be an object");
+    }
+  }
+
   // ─── Parallel Config ────────────────────────────────────────────────────
   if (preferences.parallel && typeof preferences.parallel === "object") {
     const p = preferences.parallel as unknown as Record<string, unknown>;
@@ -697,6 +741,41 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Slice Parallel Config ───────────────────────────────────────────────
+  if (preferences.slice_parallel !== undefined) {
+    if (typeof preferences.slice_parallel === "object" && preferences.slice_parallel !== null) {
+      const sp = preferences.slice_parallel as Record<string, unknown>;
+      const validSp: NonNullable<GSDPreferences["slice_parallel"]> = {};
+
+      if (sp.enabled !== undefined) {
+        if (typeof sp.enabled === "boolean") validSp.enabled = sp.enabled;
+        else errors.push("slice_parallel.enabled must be a boolean");
+      }
+
+      if (sp.max_workers !== undefined) {
+        const maxWorkers = typeof sp.max_workers === "number" ? sp.max_workers : Number(sp.max_workers);
+        if (Number.isFinite(maxWorkers) && maxWorkers >= 1 && maxWorkers <= 8) {
+          validSp.max_workers = Math.floor(maxWorkers);
+        } else {
+          errors.push("slice_parallel.max_workers must be a number between 1 and 8");
+        }
+      }
+
+      const knownSliceParallelKeys = new Set(["enabled", "max_workers"]);
+      for (const key of Object.keys(sp)) {
+        if (!knownSliceParallelKeys.has(key)) {
+          warnings.push(`unknown slice_parallel key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validSp).length > 0) {
+        validated.slice_parallel = validSp;
+      }
+    } else {
+      errors.push("slice_parallel must be an object");
+    }
+  }
+
   // ─── Reactive Execution ─────────────────────────────────────────────────
   if (preferences.reactive_execution !== undefined) {
     if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {

package/src/resources/extensions/gsd/preferences.ts

@@ -68,13 +68,13 @@ export { resolveAllSkillReferences } from "./preferences-skills.js";
 // These lived in preferences-skills.ts but imported loadEffectiveGSDPreferences
 // back from this file, creating a circular dependency. Moved here since they
 // are trivial wrappers over loadEffectiveGSDPreferences.
-export function resolveSkillDiscoveryMode(): SkillDiscoveryMode {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath?: string): SkillDiscoveryMode {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_discovery ?? "suggest";
 }
 
-export function resolveSkillStalenessDays(): number {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath?: string): number {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_staleness_days ?? 60;
 }
 
@@ -109,16 +109,16 @@ function legacyGlobalPreferencesPath(): string {
   return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 
-function projectPreferencesPath(): string {
-  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath: string = process.cwd()): string {
+  return join(gsdRoot(basePath), "PREFERENCES.md");
 }
 // Legacy lowercase files can still exist in older projects. Keep them as a
 // compatibility-only fallback, but route new reads/writes through PREFERENCES.md.
 function legacyGlobalPreferencesPathLowercase(): string {
   return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase(): string {
-  return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath: string = process.cwd()): string {
+  return join(gsdRoot(basePath), "preferences.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
@@ -129,8 +129,8 @@ export function getLegacyGlobalGSDPreferencesPath(): string {
   return legacyGlobalPreferencesPath();
 }
 
-export function getProjectGSDPreferencesPath(): string {
-  return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath?: string): string {
+  return projectPreferencesPath(basePath);
 }
 
 // ─── Loading ────────────────────────────────────────────────────────────────
@@ -141,14 +141,14 @@ export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
     ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
-export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(projectPreferencesPath(), "project")
-    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
+  return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
 
-export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
+export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
-  const projectPreferences = loadProjectGSDPreferences();
+  const projectPreferences = loadProjectGSDPreferences(basePath);
 
   if (!globalPreferences && !projectPreferences) return null;
 
@@ -603,8 +603,8 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode(): "none" | "worktree" | "branch" {
-  const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath?: string): "none" | "worktree" | "branch" {
+  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
   if (prefs?.isolation === "worktree") return "worktree";
   if (prefs?.isolation === "branch") return "branch";
   return "none"; // default — no isolation, work on current branch

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -24,6 +24,35 @@ import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { logWarning } from "./workflow-logger.js";
 
+type ExistsFn = (path: string) => boolean;
+
+function hasRequiredExtensionAssets(rootDir: string, exists: ExistsFn = existsSync): boolean {
+  return (
+    exists(join(rootDir, "prompts")) &&
+    exists(join(rootDir, "templates", "task-summary.md"))
+  );
+}
+
+export function resolveExtensionDirFromCandidates(
+  moduleDir: string,
+  agentGsdDir: string,
+  exists: ExistsFn = existsSync,
+): string {
+  const moduleUsable = hasRequiredExtensionAssets(moduleDir, exists);
+  const agentUsable = hasRequiredExtensionAssets(agentGsdDir, exists);
+
+  // Prefer the user-local extension tree when both are valid. This avoids
+  // leaking npm/global-install paths into prompts on Windows.
+  if (agentUsable) return agentGsdDir;
+  if (moduleUsable) return moduleDir;
+
+  // Degraded fallback: if required template is missing in both locations,
+  // keep previous behavior and prefer whichever still has prompts/.
+  if (exists(join(moduleDir, "prompts"))) return moduleDir;
+  if (exists(join(agentGsdDir, "prompts"))) return agentGsdDir;
+  return moduleDir;
+}
+
 /**
  * Resolve the GSD extension directory.
  *
@@ -36,15 +65,9 @@ import { logWarning } from "./workflow-logger.js";
  */
 function resolveExtensionDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
-  if (existsSync(join(moduleDir, "prompts"))) return moduleDir;
-
-  // Fallback: user-local agent directory
   const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
   const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
-  if (existsSync(join(agentGsdDir, "prompts"))) return agentGsdDir;
-
-  // Last resort: return the module dir (warmCache will silently handle the miss)
-  return moduleDir;
+  return resolveExtensionDirFromCandidates(moduleDir, agentGsdDir);
 }
 
 const __extensionDir = resolveExtensionDir();

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -59,7 +59,7 @@ Then:
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
 11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
-12. Extract structured learnings from this milestone and persist them to the cross-session knowledge surfaces. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md`, appends Patterns and Lessons to `.gsd/KNOWLEDGE.md`, and persists Decisions via the `gsd_save_decision` MCP tool.
+12. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
 
 {{extractLearningsSteps}}
 

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -29,8 +29,8 @@ Then:
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
 8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
-9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+9. Review task summaries for `key_decisions`. For each significant decision, call `capture_thought` with `category: "architecture"` (or `"pattern"`) and a `structuredFields` payload of `{ scope, decision, choice, rationale, made_by: "agent", revisable }`.
+10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. For each one that would save future agents from repeating investigation, call `capture_thought` with the matching category (`gotcha`, `convention`, `pattern`, `environment`). The memory store is the single source of truth (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
 11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.
 12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.

package/src/resources/extensions/gsd/prompts/debug-diagnose.md

@@ -18,8 +18,10 @@ Goal semantics:
 ## Instructions
 
 1. Read `.gsd/debug/sessions/{{slug}}.json` for any prior session context.
+1a. Call `memory_query` with keywords from the issue (error text, subsystem, file paths). A prior session may have captured this exact gotcha — finding it now saves the investigation.
 2. Investigate the reported issue in `{{workingDirectory}}`.
 3. Follow the goal constraint above strictly.
 4. When complete, surface a clear summary: what failed, why, and what was done (or what a fix would require for root-cause-only mode).
+5. Once root cause is identified, call `capture_thought` with `category: "gotcha"` so future debug sessions can find it via `memory_query`. Keep the content to 1–3 sentences — the symptom, the root cause, and the fix or guard.
 
 {{skillActivation}}

package/src/resources/extensions/gsd/prompts/discuss-headless.md

@@ -162,6 +162,10 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `{{contextPath}}`, and called `gsd_plan_milestone`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
@@ -234,6 +238,10 @@ For single-milestone projects, do NOT write this file.
 
 7. {{multiMilestoneCommitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, the primary `CONTEXT.md`, called `gsd_plan_milestone` for the primary milestone, and written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -339,7 +339,20 @@ These sections are in addition to whatever other context the discussion surfaced
 6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -418,6 +431,20 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (Phase 1)
+- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -32,6 +32,7 @@ A researcher explored the codebase and a planner decomposed the work — you are
 
 Then:
 0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call — but write complete sentences in user-facing prose, not shorthand notes or scratchpad fragments.
+0a. Call `memory_query` with 2-4 keywords drawn from the task title and the files it touches. Surface any prior gotchas, conventions, or architectural decisions before you start changing code. Skip only if the task is trivially mechanical.
 1. {{skillActivation}} Follow any activated skills before writing code. If no skills match this task, skip this step.
 2. Execute the steps in the inlined task plan, adapting minor local mismatches when the surrounding code differs from the planner's snapshot
 3. Before any `Write` that creates an artifact or output file, check whether that path already exists. If it does, read it first and decide whether the work is already done, should be extended, or truly needs replacement. "Create" in the plan does **not** mean the file is missing — a prior session may already have started it.
@@ -81,8 +82,8 @@ Then:
     **Scope:** Escalation is instrumented only in `execute-task`. Refine-slice escalation is deferred. Reactive-execute batches run to completion before escalations are surfaced — the dispatch pause happens on the next loop iteration, not mid-batch.
 
     The `escalation` payload is ignored unless `phases.mid_execution_escalation` is enabled; populate it anyway for audit logs.
-17. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
-18. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
+17. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, call `capture_thought` with `category: "architecture"` (or `"pattern"`). For decisions, populate `structuredFields` with `{ scope, decision, choice, rationale, made_by: "agent", revisable }` so future projection back to a human-visible decisions register stays lossless. Not every task produces decisions — only capture when a meaningful choice was made.
+18. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, call `capture_thought` with `category: "gotcha"`, `"convention"`, `"pattern"`, or `"environment"` as appropriate. Only capture entries that would save future agents from repeating your investigation — don't capture obvious things. The memory store is the single source of truth for cross-session knowledge (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
 19. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 20. Use that template to prepare the completion content you will pass to `gsd_complete_task` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you.
 21. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically.

package/src/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -15,8 +15,11 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
 3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
-4. If any subagent failed to write its RESEARCH file, re-run it individually
-5. Report which slices completed research and which (if any) failed
+4. If a subagent failed to write its RESEARCH file, retry it **once** individually
+5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
+6. Report which slices completed research and which (if any) needed a blocker note
+
+**Important**: Each failed slice gets exactly one retry. After that, write the blocker and move on. Never retry the same slice more than once.
 
 ## Subagent Prompts
 

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -44,6 +44,7 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 
 Then:
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
+0a. Call `memory_query` with keywords from the slice title and the source files listed below. Prior architectural decisions, conventions, and gotchas in this area should inform task decomposition — not be re-derived during execution.
 1. Read the templates:
    - `~/.gsd/agent/extensions/gsd/templates/plan.md`
    - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`

package/src/resources/extensions/gsd/prompts/research-slice.md

@@ -42,6 +42,7 @@ An honest "this is straightforward, here's the pattern to follow" is more valuab
 
 Research what this slice needs. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach.
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements this slice owns or supports. Research should target these requirements — surfacing risks, unknowns, and implementation constraints that could affect whether the slice actually delivers them.
+0a. Call `memory_query` with keywords from the slice title and scope. Prior slices may have captured architecture notes, conventions, or gotchas in subsystems you're about to explore — pulling them now prevents re-discovering known constraints.
 1. {{skillActivation}} Reference specific rules from loaded skills in your findings where they inform the implementation approach.
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -3,10 +3,26 @@
  * Tracks every bash command, file write, and file edit during a unit execution.
  * Evidence is compared against LLM completion claims in evidence-cross-ref.ts.
  *
+ * Evidence is persisted to .gsd/safety/evidence-<mid>-<sid>-<tid>.json so it
+ * survives session restarts (pause/resume, crash recovery). On unit start,
+ * call resetEvidence() then loadEvidenceFromDisk(). On every new tool call,
+ * saveEvidenceToDisk() is called automatically by recordToolCall/recordToolResult.
+ *
  * Follows the same module-level Map pattern as auto-tool-tracking.ts.
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
 
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 export interface BashEvidence {
@@ -62,6 +78,109 @@ export function getFilePaths(): string[] {
     .map(e => e.path);
 }
 
+// ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
+
+/**
+ * Build the path for the evidence JSON file for a given unit.
+ * Lives under .gsd/safety/ which is gitignored and session-scoped.
+ */
+function evidencePath(basePath: string, milestoneId: string, sliceId: string, taskId: string): string {
+  return join(basePath, ".gsd", "safety", `evidence-${milestoneId}-${sliceId}-${taskId}.json`);
+}
+
+/**
+ * Validate that a parsed value is an array of EvidenceEntry objects.
+ * Rejects corrupt / schema-mismatch data rather than letting it poison state.
+ */
+function isEvidenceArray(data: unknown): data is EvidenceEntry[] {
+  if (!Array.isArray(data)) return false;
+  return data.every((e) => {
+    if (e === null || typeof e !== "object") return false;
+    const rec = e as Record<string, unknown>;
+    if (typeof rec.toolCallId !== "string") return false;
+    if (typeof rec.timestamp !== "number") return false;
+    if (rec.kind === "bash") {
+      return (
+        typeof rec.command === "string" &&
+        typeof rec.exitCode === "number" &&
+        typeof rec.outputSnippet === "string"
+      );
+    }
+    if (rec.kind === "write" || rec.kind === "edit") {
+      return typeof rec.path === "string";
+    }
+    return false;
+  });
+}
+
+/**
+ * Persist the current in-memory evidence to disk so it survives a session
+ * restart. Called from saveEvidenceToDisk after recordToolCall/recordToolResult.
+ * Non-fatal — persistence failures must never break unit execution.
+ */
+export function saveEvidenceToDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // Non-fatal — don't let persistence failures break unit execution
+  }
+}
+
+/**
+ * Load persisted evidence from disk into the in-memory array.
+ * Call after resetEvidence() on session resume to restore context for a
+ * partially-executed unit. If the file does not exist (fresh unit), this
+ * is a no-op — getEvidence() will return [] which is correct.
+ */
+export function loadEvidenceFromDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    if (!existsSync(path)) return;
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (isEvidenceArray(parsed)) {
+      unitEvidence = parsed;
+    }
+  } catch {
+    // Non-fatal — corrupt / missing file is treated as empty evidence
+  }
+}
+
+/**
+ * Delete the persisted evidence file for a unit after it has been fully
+ * processed. Prevents stale evidence from affecting future retries of
+ * the same unit ID.
+ */
+export function clearEvidenceFromDisk(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+  taskId: string,
+): void {
+  try {
+    const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+    if (existsSync(path)) {
+      unlinkSync(path);
+    }
+  } catch {
+    // Non-fatal
+  }
+}
+
 // ─── Recording (called from register-hooks.ts) ─────────────────────────────
 
 /**