gsd-pi 2.75.0-dev.b6ad8c5f7 → 2.75.0-dev.e41b70b10

package/src/resources/extensions/gsd/auto/loop-deps.ts

@@ -16,7 +16,7 @@ import type {
   VerificationContext,
   VerificationResult,
 } from "../auto-verification.js";
-import type { DispatchAction } from "../auto-dispatch.js";
+import type { DispatchAction, DispatchContext } from "../auto-dispatch.js";
 import type { WorktreeResolver } from "../worktree-resolver.js";
 import type { CmuxLogLevel } from "../../cmux/index.js";
 import type { JournalEntry } from "../journal.js";
@@ -145,15 +145,7 @@ export interface LoopDeps {
   } | null>;
 
   // Dispatch
-  resolveDispatch: (dctx: {
-    basePath: string;
-    mid: string;
-    midTitle: string;
-    state: GSDState;
-    prefs: GSDPreferences | undefined;
-    session?: AutoSession;
-    structuredQuestionsAvailable?: "true" | "false";
-  }) => Promise<DispatchAction>;
+  resolveDispatch: (dctx: DispatchContext) => Promise<DispatchAction>;
   runPreDispatchHooks: (
     unitType: string,
     unitId: string,

package/src/resources/extensions/gsd/auto/phases.ts

@@ -50,6 +50,7 @@ import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
+import type { MinimalModelRegistry } from "../context-budget.js";
 import { ensurePlanV2Graph } from "../uok/plan-v2.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
@@ -857,6 +858,8 @@ export async function runDispatch(
     prefs,
     session: s,
     structuredQuestionsAvailable,
+    sessionContextWindow: ctx.model?.contextWindow,
+    modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
   });
 
   if (dispatchResult.action === "stop") {

package/src/resources/extensions/gsd/auto-dashboard.ts

@@ -18,6 +18,7 @@ import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { getErrorMessage } from "./error-utils.js";
+import { nativeIsRepo } from "./native-git-bridge.js";
 import {
   resolveMilestoneFile,
   resolveSliceFile,
@@ -336,6 +337,10 @@ let lastCommitFetchedAt = 0;
 
 function refreshLastCommit(basePath: string): void {
   try {
+    if (!nativeIsRepo(basePath)) {
+      cachedLastCommit = null;
+      return;
+    }
     const raw = execFileSync("git", ["log", "-1", "--format=%cr|%s"], {
       cwd: basePath,
       encoding: "utf-8",
@@ -349,10 +354,12 @@ function refreshLastCommit(basePath: string): void {
         message: raw.slice(sep + 1),
       };
     }
-    lastCommitFetchedAt = Date.now();
   } catch (err) {
     // Non-fatal — just skip last commit display
+    cachedLastCommit = null;
     logWarning("dashboard", `operation failed: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    lastCommitFetchedAt = Date.now();
   }
 }
 
@@ -364,6 +371,23 @@ function getLastCommit(basePath: string): { timeAgo: string; message: string } |
   return cachedLastCommit;
 }
 
+export function _resetLastCommitCacheForTests(): void {
+  cachedLastCommit = null;
+  lastCommitFetchedAt = 0;
+}
+
+export function _refreshLastCommitForTests(basePath: string): void {
+  refreshLastCommit(basePath);
+}
+
+export function _getLastCommitForTests(basePath: string): { timeAgo: string; message: string } | null {
+  return getLastCommit(basePath);
+}
+
+export function _getLastCommitFetchedAtForTests(): number {
+  return lastCommitFetchedAt;
+}
+
 // ─── Footer Factory ───────────────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -28,6 +28,7 @@ import {
   buildReplanSlicePrompt,
 } from "./auto-prompts.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import type { MinimalModelRegistry } from "./context-budget.js";
 import { pauseAuto } from "./auto.js";
 import {
   getWorkflowTransportSupportError,
@@ -104,7 +105,13 @@ export async function dispatchDirectPhase(
         }
         unitType = "plan-slice";
         unitId = `${mid}/${sid}`;
-        prompt = await buildPlanSlicePrompt(mid, midTitle, sid, sTitle, base);
+        prompt = await buildPlanSlicePrompt(
+          mid, midTitle, sid, sTitle, base, undefined,
+          {
+            sessionContextWindow: ctx.model?.contextWindow,
+            modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
+          },
+        );
       } else {
         unitType = "plan-milestone";
         unitId = mid;
@@ -129,7 +136,13 @@ export async function dispatchDirectPhase(
       }
       unitType = "execute-task";
       unitId = `${mid}/${sid}/${tid}`;
-      prompt = await buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base);
+      prompt = await buildExecuteTaskPrompt(
+        mid, sid, sTitle, tid, tTitle, base,
+        {
+          sessionContextWindow: ctx.model?.contextWindow,
+          modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
+        },
+      );
       break;
     }
 

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -12,6 +12,7 @@
 import type { GSDState } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
 import type { UatType } from "./files.js";
+import type { MinimalModelRegistry } from "./context-budget.js";
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
 import { isDbAvailable, getMilestoneSlices, getPendingGates, markAllGatesOmitted, getMilestone, updateMilestoneStatus } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -81,6 +82,10 @@ export interface DispatchContext {
   prefs: GSDPreferences | undefined;
   session?: import("./auto/session.js").AutoSession;
   structuredQuestionsAvailable?: "true" | "false";
+  /** Session model context window in tokens, forwarded to the budget engine's prompt builders. */
+  sessionContextWindow?: number;
+  /** Model registry forwarded to the budget engine so it can look up the configured executor model. */
+  modelRegistry?: MinimalModelRegistry;
 }
 
 export interface DispatchRule {
@@ -521,7 +526,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     // auto-heal without either adding an explicit `setSliceSketchFlag(..., false)`
     // call here or doing so inside the plan-slice tool handler.
     name: "refining → refine-slice",
-    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "refining") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice.id;
@@ -546,7 +551,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           unitId: `${mid}/${sid}`,
           prompt: await buildPlanSlicePrompt(
             mid, midTitle, sid, sTitle, basePath, undefined,
-            softScopeHint ? { softScopeHint } : undefined,
+            { ...(softScopeHint ? { softScopeHint } : {}), sessionContextWindow, modelRegistry },
           ),
         };
       }
@@ -554,13 +559,16 @@ export const DISPATCH_RULES: DispatchRule[] = [
         action: "dispatch",
         unitType: "refine-slice",
         unitId: `${mid}/${sid}`,
-        prompt: await buildRefineSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+        prompt: await buildRefineSlicePrompt(
+          mid, midTitle, sid, sTitle, basePath, undefined,
+          { sessionContextWindow, modelRegistry },
+        ),
       };
     },
   },
   {
     name: "planning → plan-slice",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "planning") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -575,6 +583,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
           sid,
           sTitle,
           basePath,
+          undefined,
+          { sessionContextWindow, modelRegistry },
         ),
       };
     },
@@ -635,7 +645,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → reactive-execute (parallel dispatch)",
-    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return null; // fall through
 
@@ -726,6 +736,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
             selected,
             basePath,
             subagentModel,
+            { sessionContextWindow, modelRegistry },
           ),
         };
       } catch (err) {
@@ -737,7 +748,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task (recover missing task plan → plan-slice)",
-    match: async ({ state, mid, midTitle, basePath }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -761,6 +772,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
             sid,
             sTitle,
             basePath,
+            undefined,
+            { sessionContextWindow, modelRegistry },
           ),
         };
       }
@@ -770,7 +783,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task",
-    match: async ({ state, mid, basePath }) => {
+    match: async ({ state, mid, basePath, sessionContextWindow, modelRegistry }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -789,6 +802,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           tid,
           tTitle,
           basePath,
+          { sessionContextWindow, modelRegistry },
         ),
       };
     },

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -488,7 +488,9 @@ export function resolveModelId<T extends { id: string; provider: string }>(
     if (providerMatch) return providerMatch;
   }
 
-  // Prefer "anthropic" as the canonical provider for Anthropic models
+  // Prefer "anthropic" as the canonical provider for Anthropic models.
+  // Transport-specific tiebreaker (ADR-012): intentionally keys on provider,
+  // not api — we want the plain Anthropic transport when multiple are available.
   const anthropicMatch = candidates.find(m => m.provider === "anthropic");
   if (anthropicMatch) return anthropicMatch;
 

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -23,7 +23,7 @@ import type { GSDPreferences } from "./preferences.js";
 import { getLoadedSkills, type Skill } from "@gsd/pi-coding-agent";
 import { join, basename } from "node:path";
 import { existsSync } from "node:fs";
-import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary } from "./context-budget.js";
+import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
 import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
 import {
   GATE_REGISTRY,
@@ -94,14 +94,19 @@ function capPreamble(preamble: string): string {
  * Uses the budget engine to compute task count ranges and inline context budgets
  * based on the configured executor model's context window.
  */
-function formatExecutorConstraints(): string {
+function formatExecutorConstraints(
+  sessionContextWindow?: number,
+  modelRegistry?: MinimalModelRegistry,
+): string {
   let windowTokens: number;
   try {
     const prefs = loadEffectiveGSDPreferences();
-    windowTokens = resolveExecutorContextWindow(undefined, prefs?.preferences);
+    windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow);
   } catch (e) {
     logWarning("prompt", `resolveExecutorContextWindow failed: ${(e as Error).message}`);
-    windowTokens = 200_000; // safe default
+    // Delegate to the budget engine without prefs (the path that just threw)
+    // so DEFAULT_CONTEXT_WINDOW stays the single source of truth.
+    windowTokens = resolveExecutorContextWindow(undefined, undefined, sessionContextWindow);
   }
   const budgets = computeBudgets(windowTokens);
   const { min, max } = budgets.taskCountRange;
@@ -1288,8 +1293,13 @@ async function renderSlicePrompt(options: {
   promptTemplate: "plan-slice" | "refine-slice";
   prependBlocks?: string[];
   extraVars?: Record<string, string>;
+  sessionContextWindow?: number;
+  modelRegistry?: MinimalModelRegistry;
 }): Promise<string> {
-  const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {} } = options;
+  const {
+    mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {},
+    sessionContextWindow, modelRegistry,
+  } = options;
 
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
@@ -1341,7 +1351,7 @@ async function renderSlicePrompt(options: {
   if (overridesInline) inlined.unshift(overridesInline);
 
   const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
-  const executorContextConstraints = formatExecutorConstraints();
+  const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry);
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
   const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
 
@@ -1370,7 +1380,7 @@ async function renderSlicePrompt(options: {
 
 export async function buildPlanSlicePrompt(
   mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
-  options?: { softScopeHint?: string },
+  options?: { softScopeHint?: string; sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry },
 ): Promise<string> {
   const prependBlocks: string[] = [];
   // ADR-011: when the refining-phase dispatch rule gracefully downgrades to
@@ -1388,6 +1398,8 @@ export async function buildPlanSlicePrompt(
     level: level ?? resolveInlineLevel(),
     promptTemplate: "plan-slice",
     prependBlocks,
+    sessionContextWindow: options?.sessionContextWindow,
+    modelRegistry: options?.modelRegistry,
   });
 }
 
@@ -1400,6 +1412,7 @@ export async function buildPlanSlicePrompt(
  */
 export async function buildRefineSlicePrompt(
   mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
+  options?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry },
 ): Promise<string> {
   // Pull the stored sketch scope from the DB — the hard constraint we plan within.
   let sketchScope = "";
@@ -1426,6 +1439,8 @@ export async function buildRefineSlicePrompt(
     promptTemplate: "refine-slice",
     prependBlocks,
     extraVars: { sketchScope },
+    sessionContextWindow: options?.sessionContextWindow,
+    modelRegistry: options?.modelRegistry,
   });
 }
 
@@ -1434,6 +1449,10 @@ export interface ExecuteTaskPromptOptions {
   level?: InlineLevel;
   /** Override carry-forward paths (dependency-based instead of order-based). */
   carryForwardPaths?: string[];
+  /** Session model context window in tokens, forwarded to the budget engine. */
+  sessionContextWindow?: number;
+  /** Model registry forwarded to the budget engine for executor-model lookup. */
+  modelRegistry?: MinimalModelRegistry;
 }
 
 export async function buildExecuteTaskPrompt(
@@ -1525,7 +1544,7 @@ export async function buildExecuteTaskPrompt(
 
   // Compute verification budget for the executor's context window (issue #707)
   const prefs = loadEffectiveGSDPreferences();
-  const contextWindow = resolveExecutorContextWindow(undefined, prefs?.preferences);
+  const contextWindow = resolveExecutorContextWindow(opts.modelRegistry, prefs?.preferences, opts.sessionContextWindow);
   const budgets = computeBudgets(contextWindow);
   const verificationBudget = `~${Math.round(budgets.verificationBudgetChars / 1000)}K chars`;
 
@@ -2101,6 +2120,7 @@ export async function buildReactiveExecutePrompt(
   mid: string, midTitle: string, sid: string, sTitle: string,
   readyTaskIds: string[], base: string,
   subagentModel?: string,
+  opts?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry },
 ): Promise<string> {
   const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
 
@@ -2142,7 +2162,11 @@ export async function buildReactiveExecutePrompt(
     // Build a full execute-task prompt with dependency-based carry-forward
     const taskPrompt = await buildExecuteTaskPrompt(
       mid, sid, sTitle, tid, tTitle, base,
-      { carryForwardPaths: depPaths },
+      {
+        carryForwardPaths: depPaths,
+        sessionContextWindow: opts?.sessionContextWindow,
+        modelRegistry: opts?.modelRegistry,
+      },
     );
 
     const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -238,6 +238,14 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void
   }
 }
 
+function isProjectGsdSymlink(basePath: string): boolean {
+  try {
+    return lstatSyncFn(join(basePath, ".gsd")).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 // ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
 
 /** Patterns for machine-generated build artifacts that can be safely
@@ -1675,12 +1683,19 @@ export function mergeMilestoneToMain(
       // CONTEXT files into the stash. If stash pop later fails, those files
       // are permanently trapped in the stash entry and lost on the next
       // stash push or drop.
+      //
+      // When `.gsd` itself is a symlink, Git rejects pathspecs below it
+      // ("beyond a symbolic link"). In that layout, exclude the whole symlink
+      // and keep stashing real project files that could block the merge.
+      const stashPathspecs = isProjectGsdSymlink(originalBasePath_)
+        ? [".", ":(exclude).gsd"]
+        : [":(exclude).gsd/milestones"];
       execFileSync(
         "git",
         [
           "stash", "push", "--include-untracked",
           "-m", `gsd: pre-merge stash for ${milestoneId}`,
-          "--", ":(exclude).gsd/milestones",
+          "--", ...stashPathspecs,
         ],
         { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
       );

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

@@ -0,0 +1,158 @@
+// 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)" })),
+    }),
+    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/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";
@@ -85,6 +86,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/system-context.ts

@@ -113,10 +113,26 @@ export async function buildBeforeAgentStartResult(
 
   let memoryBlock = "";
   try {
-    const { formatMemoriesForPrompt, getActiveMemoriesRanked } = await import("../memory-store.js");
-    const memories = getActiveMemoriesRanked(30);
-    if (memories.length > 0) {
-      const formatted = formatMemoriesForPrompt(memories, 2000);
+    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}`;
       }