gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

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

@@ -449,10 +449,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
         depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
         demo: Type.String({ description: "Roadmap demo text / After this" }),
         goal: Type.String({ description: "Slice goal" }),
-        successCriteria: Type.String({ description: "Slice success criteria block" }),
-        proofLevel: Type.String({ description: "Slice proof level" }),
-        integrationClosure: Type.String({ description: "Slice integration closure" }),
-        observabilityImpact: Type.String({ description: "Slice observability impact" }),
+        // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
+        successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block (required for full slices; omit for sketches)" })),
+        proofLevel: Type.Optional(Type.String({ description: "Slice proof level (required for full slices; omit for sketches)" })),
+        integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure (required for full slices; omit for sketches)" })),
+        observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact (required for full slices; omit for sketches)" })),
+        // ADR-011 sketch-then-refine fields.
+        isSketch: Type.Optional(Type.Boolean({ description: "ADR-011: true marks this slice as a sketch awaiting refine-slice expansion" })),
+        sketchScope: Type.Optional(Type.String({ description: "ADR-011: 2–3 sentence scope boundary, required when isSketch=true" })),
       }), { description: "Planned slices for the milestone" }),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
       status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })),
@@ -631,6 +635,20 @@ export function registerDbTools(pi: ExtensionAPI): void {
       keyFiles: Type.Optional(Type.Array(Type.String(), { description: "List of key files created or modified" })),
       keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "List of key decisions made during this task" })),
       blockerDiscovered: Type.Optional(Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" })),
+      // ADR-011 Phase 2: mid-execution escalation — agent asks the user to resolve an ambiguity.
+      escalation: Type.Optional(Type.Object({
+        question: Type.String({ description: "The question the user needs to answer — one clear sentence." }),
+        options: Type.Array(Type.Object({
+          id: Type.String({ description: "Short id (e.g. 'A', 'B') used by /gsd escalate resolve." }),
+          label: Type.String({ description: "One-line label." }),
+          tradeoffs: Type.String({ description: "1-2 sentences on the tradeoffs of this option." }),
+        }), { minItems: 2, maxItems: 4, description: "2–4 options the user can choose between." }),
+        recommendation: Type.String({ description: "Option id the executor recommends." }),
+        recommendationRationale: Type.String({ description: "Why the recommendation — 1–2 sentences." }),
+        continueWithDefault: Type.Boolean({
+          description: "When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve.",
+        }),
+      }, { description: "ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true." })),
       verificationEvidence: Type.Optional(Type.Array(
         Type.Union([
           Type.Object({
@@ -758,32 +776,26 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     }
     try {
-      const { getSlice, updateSliceStatus } = await import("../gsd-db.js");
+      const { handleSkipSlice } = await import("../tools/skip-slice.js");
       const { invalidateStateCache } = await import("../state.js");
 
-      const slice = getSlice(params.milestoneId, params.sliceId);
-      if (!slice) {
-        return {
-          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} not found in milestone ${params.milestoneId}` }],
-          details: { operation: "skip_slice", error: "slice_not_found" } as any,
-        };
-      }
+      const result = handleSkipSlice({
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        reason: params.reason,
+      });
 
-      if (slice.status === "complete" || slice.status === "done") {
+      if (result.error) {
         return {
-          content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} is already complete — cannot skip.` }],
-          details: { operation: "skip_slice", error: "already_complete" } as any,
+          content: [{ type: "text" as const, text: `Error: ${result.error}` }],
+          details: {
+            operation: "skip_slice",
+            error: result.error,
+            errorCode: result.errorCode ?? "skip_failed",
+          } as any,
         };
       }
 
-      if (slice.status === "skipped") {
-        return {
-          content: [{ type: "text" as const, text: `Slice ${params.sliceId} is already skipped.` }],
-          details: { operation: "skip_slice", sliceId: params.sliceId, milestoneId: params.milestoneId } as any,
-        };
-      }
-
-      updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
       invalidateStateCache();
 
       // Rebuild STATE.md so it reflects the skip immediately (#3477).
@@ -796,13 +808,21 @@ export function registerDbTools(pi: ExtensionAPI): void {
         logError("tool", `skip_slice rebuildState failed: ${(err as Error).message}`, { tool: "gsd_skip_slice" });
       }
 
+      const suffix = result.wasAlreadySkipped
+        ? result.tasksSkipped > 0
+          ? ` (already skipped; cascaded ${result.tasksSkipped} leftover task(s) to skipped).`
+          : " (already skipped; no pending tasks to cascade)."
+        : ` Cascaded ${result.tasksSkipped} task(s) to skipped. Auto-mode will advance past this slice.`;
+
       return {
-        content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}. Auto-mode will advance past this slice.` }],
+        content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}.${suffix}` }],
         details: {
           operation: "skip_slice",
           sliceId: params.sliceId,
           milestoneId: params.milestoneId,
           reason: params.reason,
+          tasksSkipped: result.tasksSkipped,
+          wasAlreadySkipped: result.wasAlreadySkipped,
         } as any,
       };
     } catch (err) {
@@ -820,12 +840,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
     label: "Skip Slice",
     description:
       "Mark a slice as skipped so auto-mode advances past it without executing. " +
+      "Non-closed tasks within the slice are cascaded to skipped so milestone completion is not blocked by leftover pending tasks (#4375). " +
       "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.",
     promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)",
     promptGuidelines: [
       "Use gsd_skip_slice when a slice should be bypassed — descoped, superseded, or no longer relevant.",
       "Cannot skip a slice that is already complete.",
       "Skipped slices satisfy downstream dependencies just like completed slices.",
+      "All pending/active tasks in the slice are cascaded to skipped; completed tasks are never downgraded.",
     ],
     parameters: Type.Object({
       sliceId: Type.String({ description: "Slice ID (e.g. S02)" }),

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

@@ -0,0 +1,163 @@
+// GSD2 — Memory tool registration
+//
+// Exposes the memory-layer tools (capture_thought, memory_query, gsd_graph)
+// to the LLM over MCP. All three degrade gracefully when the GSD database
+// is unavailable.
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { ensureDbOpen } from "./dynamic-tools.js";
+import {
+  executeGsdGraph,
+  executeMemoryCapture,
+  executeMemoryQuery,
+} from "../tools/memory-tools.js";
+
+export function registerMemoryTools(pi: ExtensionAPI): void {
+  // ─── capture_thought ────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "capture_thought",
+    label: "Capture Thought",
+    description:
+      "Record a durable piece of project knowledge (decision, convention, gotcha, pattern, " +
+      "preference, or environment detail) into the GSD memory store. Use sparingly — one memory " +
+      "per genuinely reusable insight, not per task.",
+    promptSnippet:
+      "Capture a durable project insight into the GSD memory store (categories: architecture, convention, gotcha, pattern, preference, environment)",
+    promptGuidelines: [
+      "Use capture_thought for insights that will remain useful across future sessions.",
+      "Do NOT capture one-off bug fixes, temporary state, secrets, or task-specific details.",
+      "Keep content to 1–3 sentences.",
+      "Set confidence: 0.6 tentative, 0.8 solid, 0.95 well-confirmed (default 0.8).",
+    ],
+    parameters: Type.Object({
+      category: Type.Union(
+        [
+          Type.Literal("architecture"),
+          Type.Literal("convention"),
+          Type.Literal("gotcha"),
+          Type.Literal("preference"),
+          Type.Literal("environment"),
+          Type.Literal("pattern"),
+        ],
+        { description: "Memory category" },
+      ),
+      content: Type.String({ description: "The memory text (1–3 sentences, no secrets)" }),
+      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();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot capture memory." }],
+          details: { operation: "memory_capture", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryCapture(params as Parameters<typeof executeMemoryCapture>[0]);
+    },
+  });
+
+  // ─── memory_query ───────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "memory_query",
+    label: "Query Memory",
+    description:
+      "Search the GSD memory store for relevant memories. Phase 1 uses keyword matching ranked " +
+      "by confidence and reinforcement; future phases add semantic (embedding) retrieval.",
+    promptSnippet:
+      "Search the GSD memory store by keyword; returns ranked memories with id, category, and content",
+    promptGuidelines: [
+      "Use memory_query when you need durable project context that may not be in the current prompt.",
+      "Provide a short keyword-style query — not a full question.",
+      "Use category to narrow results to gotchas, conventions, architecture notes, etc.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Keyword query (2+ char terms)" }),
+      k: Type.Optional(Type.Number({ description: "Max results (default 10, max 50)", minimum: 1, maximum: 50 })),
+      category: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("architecture"),
+            Type.Literal("convention"),
+            Type.Literal("gotcha"),
+            Type.Literal("preference"),
+            Type.Literal("environment"),
+            Type.Literal("pattern"),
+          ],
+          { description: "Restrict results to a single category" },
+        ),
+      ),
+      scope: Type.Optional(Type.String({ description: "Only include memories with this scope (e.g. 'project', 'global')" })),
+      tag: Type.Optional(Type.String({ description: "Only include memories tagged with this value" })),
+      include_superseded: Type.Optional(Type.Boolean({ description: "Include superseded memories (default false)" })),
+      reinforce_hits: Type.Optional(
+        Type.Boolean({ description: "Increment hit_count on returned memories (default false)" }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot query memory." }],
+          details: { operation: "memory_query", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeMemoryQuery(params as Parameters<typeof executeMemoryQuery>[0]);
+    },
+  });
+
+  // ─── gsd_graph ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "gsd_graph",
+    label: "GSD Knowledge Graph",
+    description:
+      "Inspect the relationship graph between memories. mode=query walks supersedes edges from a " +
+      "given memoryId; mode=build is a placeholder that future phases will use to rebuild graph " +
+      "edges from milestone LEARNINGS artifacts.",
+    promptSnippet: "Query the memory relationship graph or trigger a rebuild",
+    promptGuidelines: [
+      "Use mode=query with a memoryId when you want to see how a memory relates to others.",
+      "Phase 1 only exposes supersedes edges; additional relation types arrive in later phases.",
+    ],
+    parameters: Type.Object({
+      mode: Type.Union([Type.Literal("build"), Type.Literal("query")], {
+        description: "build = recompute graph (placeholder), query = inspect edges",
+      }),
+      memoryId: Type.Optional(Type.String({ description: "Memory ID (required when mode=query)" })),
+      depth: Type.Optional(Type.Number({ description: "Hops to traverse (0–5, default 1)", minimum: 0, maximum: 5 })),
+      rel: Type.Optional(Type.Union([
+        Type.Literal("related_to"),
+        Type.Literal("depends_on"),
+        Type.Literal("contradicts"),
+        Type.Literal("elaborates"),
+        Type.Literal("supersedes"),
+      ], { description: "Only include edges with this relation type" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const ok = await ensureDbOpen();
+      if (!ok) {
+        return {
+          content: [{ type: "text" as const, text: "Error: GSD database is not available." }],
+          details: { operation: "gsd_graph", error: "db_unavailable" },
+          isError: true,
+        };
+      }
+      return executeGsdGraph(params as Parameters<typeof executeGsdGraph>[0]);
+    },
+  });
+}

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

@@ -4,6 +4,7 @@ import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js";
+import { checkpointDatabase } from "../gsd-db.js";
 
 export function registerQueryTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -31,4 +32,34 @@ export function registerQueryTools(pi: ExtensionAPI): void {
       return executeMilestoneStatus(params);
     },
   });
+
+  pi.registerTool({
+    name: "gsd_checkpoint_db",
+    label: "Checkpoint GSD Database",
+    description:
+      "Flush the SQLite WAL (Write-Ahead Log) into the base gsd.db file. " +
+      "Call this before `git add .gsd/gsd.db` to ensure the committed database " +
+      "contains current milestone/slice/task state rather than stale pre-session content. " +
+      "Safe to call at any time while GSD is running.",
+    promptSnippet: "Flush WAL into gsd.db so git add stages current state",
+    promptGuidelines: [
+      "Call gsd_checkpoint_db immediately before staging .gsd/gsd.db with git add.",
+      "Do not use sqlite3 or shell commands to checkpoint — they are blocked. Use this tool instead.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      const dbAvailable = await ensureDbOpen();
+      if (!dbAvailable) {
+        return {
+          content: [{ type: "text", text: "Error: GSD database is not available. Cannot checkpoint." }],
+          details: { operation: "checkpoint_db", error: "db_unavailable" },
+        };
+      }
+      checkpointDatabase();
+      return {
+        content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
+        details: { operation: "checkpoint_db", status: "ok" },
+      };
+    },
+  });
 }

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -9,6 +9,7 @@ import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
+import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
@@ -65,6 +66,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
@@ -85,6 +99,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["db-tools", () => registerDbTools(pi)],
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
+    ["memory-tools", () => registerMemoryTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
     ["hooks", () => registerHooks(pi, ecosystemHandlers)],
     ["ecosystem", () => {

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -18,6 +18,7 @@ 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";
@@ -88,6 +89,9 @@ export function registerHooks(
       } catch { /* non-fatal */ }
     }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("session_switch", async (_event, ctx) => {
@@ -108,6 +112,9 @@ export function registerHooks(
       prepareWorkflowMcpForProject(ctx, process.cwd());
     }
     loadToolApiKeys();
+    if (isAutoActive()) {
+      ctx.ui.setFooter(hideFooter);
+    }
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
@@ -325,6 +332,7 @@ export function registerHooks(
   // ── Safety harness: evidence collection + destructive command warnings ──
   pi.on("tool_call", async (event, ctx) => {
     if (!isAutoActive()) return;
+    markToolStart(event.toolCallId, event.toolName);
     safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
     // Destructive command classification (warn only, never block)
@@ -343,6 +351,20 @@ export function registerHooks(
   });
 
   pi.on("tool_result", async (event) => {
+    if (isAutoActive() && typeof event.toolCallId === "string") {
+      markToolEnd(event.toolCallId);
+    }
+    if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+      const resultPayload = ("result" in event ? event.result : undefined) as any;
+      const errorText = typeof resultPayload === "string"
+        ? resultPayload
+        : (typeof resultPayload?.content?.[0]?.text === "string"
+            ? resultPayload.content[0].text
+            : (typeof (event as any).content === "string"
+                ? (event as any).content
+                : String(resultPayload ?? "")));
+      recordToolInvocationError(event.toolName, errorText);
+    }
     if (event.toolName !== "ask_user_questions") return;
     const milestoneId = getDiscussionMilestoneId(process.cwd());
     const queueActive = isQueuePhaseActive();

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,20 +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 } = await import("../memory-store.js");
-    const memories = getActiveMemoriesRanked(30);
-    if (memories.length > 0) {
-      const formatted = formatMemoriesForPrompt(memories, 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();
@@ -204,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 = "";