gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -12,7 +12,14 @@ import {
   resetEmptyTurnCounter,
 } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
+import {
+  getAutoDashboardData,
+  getAutoModeStartModel,
+  isAutoActive,
+  isAutoCompletionStopInProgress,
+  pauseAuto,
+  setCurrentDispatchedModelId,
+} from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import {
@@ -146,8 +153,7 @@ export function isBareClaudeCodeStreamAbortPlaceholder(lastMsg: unknown): boolea
  * Claude Code abort markers are intentionally ignored when the abort fires
  * while the session-switch is in flight: the abort is the expected side-effect
  * of the transition, not a user signal. Other branches (genuine `stopReason
- * === "aborted"` with diagnostic content/errorMessage) preserve the prior
- * behavior.
+ * === "aborted"` with explicit errorMessage) preserve the prior behavior.
  */
 export function _handleSessionSwitchAgentEnd(
   lastMsg: unknown,
@@ -171,10 +177,8 @@ export function _handleSessionSwitchAgentEnd(
   }
 
   if (m.stopReason === "aborted") {
-    const content = m.content;
-    const hasEmptyContent = Array.isArray(content) && content.length === 0;
     const hasErrorMessage = !!m.errorMessage;
-    if (!hasEmptyContent || hasErrorMessage) {
+    if (hasErrorMessage) {
       resolveCancelled(_buildAbortedPauseContext(m as { errorMessage?: unknown }));
     }
   }
@@ -295,6 +299,12 @@ export async function handleAgentEnd(
   }
 
   if (isObjectRecord(lastMsg) && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+    if (isAutoCompletionStopInProgress()) {
+      resetRetryState(retryState);
+      resolveAgentEnd(event);
+      return;
+    }
+
     // Empty content with aborted stopReason is a non-fatal agent stop (the LLM
     // chose to end without producing output). Only pause on genuine fatal aborts
     // that carry error context — e.g. errorMessage field or non-empty content
@@ -326,6 +336,11 @@ export async function handleAgentEnd(
     // errorMessage looks uninformative.
     const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
     if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+      if (isAutoCompletionStopInProgress()) {
+        resetRetryState(retryState);
+        resolveAgentEnd(event);
+        return;
+      }
       resolveAgentEndCancelled({
         message: rawErrorMsg,
         category: "aborted",

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

@@ -16,7 +16,7 @@ import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer,
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
-import { getAutoRuntimeSnapshot, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
+import { clearToolInvocationError, getAutoRuntimeSnapshot, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
 
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -143,7 +143,7 @@ const AUTO_UNIT_SCOPED_TOOLS: Record<string, readonly string[]> = {
   "plan-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
   "refine-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
   "replan-slice": ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
-  "complete-slice": ["gsd_slice_complete", "gsd_decision_save", "gsd_requirement_update", "subagent"],
+  "complete-slice": ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice", "gsd_decision_save", "gsd_requirement_update", "subagent"],
   "reassess-roadmap": ["gsd_reassess_roadmap"],
   "execute-task": ["gsd_task_complete", "gsd_decision_save"],
   "execute-task-simple": ["gsd_task_complete", "gsd_decision_save"],
@@ -423,6 +423,10 @@ export function registerHooks(
   pi: ExtensionAPI,
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
+  // ADR-005 Phase 3b: surface pi-ai ProviderSwitchReport via audit, notification, and counter.
+  // Idempotent — only the first registerHooks call installs.
+  void import("../provider-switch-observer.js").then((m) => m.installProviderSwitchObserver());
+
   pi.on("session_start", async (_event, ctx) => {
     const basePath = contextBasePath(ctx);
     initSessionNotifications(ctx);
@@ -480,6 +484,8 @@ export function registerHooks(
     }
     await loadToolApiKeysForSession();
     if (!isAutoActive()) {
+      ctx.ui.setWidget("gsd-progress", undefined);
+      ctx.ui.setWidget("gsd-outcome", undefined);
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
     } else {
@@ -892,6 +898,8 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+    } else if (isAutoActive()) {
+      clearToolInvocationError();
     }
     const toolName = canonicalToolName(event.toolName);
     if (toolName !== "ask_user_questions") return;
@@ -1009,6 +1017,8 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+    } else if (isAutoActive()) {
+      clearToolInvocationError();
     }
     // Safety harness: record tool execution results for evidence cross-referencing
     if (isAutoActive()) {

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Registers GSD keyboard shortcuts for dashboard, notifications, and parallel overlays.
+
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
@@ -39,18 +42,12 @@ export function registerShortcuts(pi: ExtensionAPI): void {
   };
 
   const openNotificationsOverlay = async (ctx: ExtensionContext) => {
-    const { GSDNotificationOverlay } = await import("../notification-overlay.js");
+    const { GSDNotificationOverlay, notificationOverlayOptions } = await import("../notification-overlay.js");
     await ctx.ui.custom<boolean>(
       (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
       {
         overlay: true,
-        overlayOptions: {
-          width: "80%",
-          minWidth: 60,
-          maxHeight: "88%",
-          anchor: "center",
-          backdrop: true,
-        },
+        overlayOptions: notificationOverlayOptions(),
       },
     );
   };

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

@@ -13,6 +13,7 @@ import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffect
 import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
@@ -131,9 +132,14 @@ export async function buildBeforeAgentStartResult(
     logWarning("bootstrap", `cmux prompt setup skipped: ${(e as Error).message}`);
   }
 
+  const ctxProjectRoot = (ctx as { projectRoot?: unknown }).projectRoot;
+  const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+    ? ctxProjectRoot
+    : process.cwd();
+
   let preferenceBlock = "";
   if (loadedPreferences) {
-    const cwd = process.cwd();
+    const cwd = basePath;
     const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
     preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
     if (report.warnings.length > 0) {
@@ -144,14 +150,6 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
-  if (globalSizeKb > 4) {
-    ctx.ui.notify(
-      `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,
-      "warning",
-    );
-  }
-
   // 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.
@@ -159,12 +157,50 @@ export async function buildBeforeAgentStartResult(
     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");
+      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store.`, "info");
     }
   } catch (e) {
     logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
+  // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
+  // re-render the hybrid projection (manual Rules + projected Patterns +
+  // projected Lessons). Both are idempotent and best-effort — failures here
+  // can't block agent startup.
+  try {
+    const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
+    const writtenK = backfillKnowledgeToMemories(basePath);
+    if (writtenK > 0) {
+      ctx.ui.notify(`GSD: backfilled ${writtenK} KNOWLEDGE.md row${writtenK === 1 ? "" : "s"} into the memory store.`, "info");
+    }
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${(e as Error).message}`);
+  }
+  try {
+    const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
+    renderKnowledgeProjection(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${(e as Error).message}`);
+  }
+
+  // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
+  // yet in the memories table. Read-only; never throws. Runs after the two
+  // backfills above so the gap report reflects post-backfill state.
+  try {
+    const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
+    reportConsolidationGaps(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `memory consolidation scan failed: ${(e as Error).message}`);
+  }
+
+  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
+  if (globalSizeKb > 4) {
+    ctx.ui.notify(
+      `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,
+      "warning",
+    );
+  }
+
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -370,7 +406,9 @@ export async function loadMemoryBlock(
 }
 
 export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: string; globalSizeKb: number } {
-  // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
+  // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project,
+  //    user-maintained. NOT migrated to memories (which are project-scoped),
+  //    so the full file is injected unchanged.
   let globalKnowledge = "";
   let globalSizeKb = 0;
   const globalKnowledgePath = join(gsdHomeDir, "agent", "KNOWLEDGE.md");
@@ -386,13 +424,18 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
     }
   }
 
-  // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
+  // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific.
+  //    ADR-013 Stage 2b: Patterns and Lessons are projected from the
+  //    memories table and already reach the LLM via loadMemoryBlock. Inject
+  //    only the intro prose + `## Rules` section here to avoid duplicating
+  //    Patterns/Lessons content in the prompt. Rules stay manual per
+  //    ADR-013 line 39 and have no memory equivalent.
   let projectKnowledge = "";
   const knowledgePath = resolveGsdRootFile(cwd, "KNOWLEDGE");
   if (existsSync(knowledgePath)) {
     try {
-      const content = readFileSync(knowledgePath, "utf-8").trim();
-      if (content) projectKnowledge = content;
+      const raw = readFileSync(knowledgePath, "utf-8").trim();
+      if (raw) projectKnowledge = extractIntroAndRules(raw).trim();
     } catch (e) {
       logWarning("bootstrap", `project knowledge file read failed: ${(e as Error).message}`);
     }
@@ -411,7 +454,7 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
   }
   const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
   return {
-    block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
+    block: `\n\n[KNOWLEDGE — Rules from KNOWLEDGE.md (Patterns and Lessons reach the LLM via the memory block)]\n\n${body}`,
     globalSizeKb,
   };
 }

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -96,7 +96,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd unpark [id]    Reactivate a parked milestone",
     "",
     "PROJECT KNOWLEDGE",
-    "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "  /gsd knowledge <type> <text>   Add a rule to KNOWLEDGE.md or capture a pattern/lesson to memories",
     "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
     "SHIPPING & BACKLOG",

package/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts

@@ -1,5 +1,5 @@
-// GSD Extension — /gsd notifications Command Handler
-// View, filter, and clear the persistent notification history.
+// Project/App: GSD-2
+// File Purpose: Handles /gsd notifications commands and opens the notification history overlay.
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
@@ -11,7 +11,7 @@ import {
   unsuppressPersistence,
   type NotifySeverity,
 } from "../../notification-store.js";
-import { GSDNotificationOverlay } from "../../notification-overlay.js";
+import { GSDNotificationOverlay, notificationOverlayOptions } from "../../notification-overlay.js";
 
 const MAX_INLINE_ENTRIES = 40;
 
@@ -108,13 +108,7 @@ export async function handleNotificationsCommand(
           (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
           {
             overlay: true,
-            overlayOptions: {
-              width: "80%",
-              minWidth: 60,
-              maxHeight: "88%",
-              anchor: "center",
-              backdrop: true,
-            },
+            overlayOptions: notificationOverlayOptions(),
           },
         );
         if (result !== undefined) {

package/src/resources/extensions/gsd/commands/handlers/parallel.ts

@@ -14,6 +14,7 @@ import {
 import { formatEligibilityReport } from "../../parallel-eligibility.js";
 import { formatMergeResults, mergeAllCompleted, mergeCompletedMilestone } from "../../parallel-merge.js";
 import { loadEffectiveGSDPreferences, resolveParallelConfig } from "../../preferences.js";
+import { reconcileBeforeSpawn } from "../../state-reconciliation.js";
 import { projectRoot } from "../context.js";
 function emitParallelMessage(pi: ExtensionAPI, content: string): void {
   pi.sendMessage({ customType: "gsd-parallel", content, display: true });
@@ -40,6 +41,17 @@ export async function handleParallelCommand(trimmed: string, _ctx: ExtensionComm
       emitParallelMessage(pi, `${report}\n\nNo milestones are eligible for parallel execution.`);
       return true;
     }
+    // ADR-017 #5707: reconcile before spawning so workers don't independently
+    // race on the same drift. Failures abort the spawn with an actionable
+    // user-visible message.
+    const gate = await reconcileBeforeSpawn(root);
+    if (!gate.ok) {
+      emitParallelMessage(
+        pi,
+        `${report}\n\nParallel orchestration aborted before spawn — ${gate.reason}`,
+      );
+      return true;
+    }
     const result = await startParallel(
       root,
       candidates.eligible.map((candidate) => candidate.milestoneId),

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -368,8 +368,25 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
     : "global";
 
-  await appendKnowledge(basePath, type, entryText, scope);
-  ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
+  // ADR-013 Stage 2c: Patterns and Lessons land in the memories table; the
+  // next session-start projection render emits them back into KNOWLEDGE.md.
+  // Rules stay file-canonical per ADR-013 line 39 — Rules are not migrated.
+  if (type === "rule") {
+    await appendKnowledge(basePath, type, entryText, scope);
+    ctx.ui.notify(`Added rule to KNOWLEDGE.md: "${entryText}"`, "success");
+    return;
+  }
+
+  const { captureKnowledgeEntry } = await import("./knowledge-capture.js");
+  const { id, written } = captureKnowledgeEntry(basePath, type, entryText, scope);
+  if (!written) {
+    ctx.ui.notify(`Could not persist ${type} — see logs for details.`, "error");
+    return;
+  }
+  ctx.ui.notify(
+    `Captured ${type} ${id} to memories; KNOWLEDGE.md will render it on next session start.`,
+    "success",
+  );
 }
 
 export async function handleRunHook(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {

package/src/resources/extensions/gsd/context-store.ts

@@ -5,7 +5,7 @@
 // All functions degrade gracefully: return empty results when DB unavailable, never throw.
 
 import { isDbAvailable, _getAdapter } from './gsd-db.js';
-import type { Decision, Requirement } from './types.js';
+import type { Decision, DecisionMadeBy, Requirement } from './types.js';
 
 // ─── Query Functions ───────────────────────────────────────────────────────
 
@@ -66,6 +66,125 @@ export function queryDecisions(opts?: DecisionQueryOpts): Decision[] {
   }
 }
 
+/**
+ * Internal: shared core for the two memory-sourced decision queries. Reads
+ * memory rows tagged with `sourceDecisionId` and reconstructs `Decision[]`
+ * from their `structured_fields` JSON.
+ *
+ * @param includeSuperseded — when false, drops rows whose
+ *   `structured_fields.superseded_by` is non-null. The supersedes-chain is
+ *   captured by the backfill (`memory-backfill.ts`) and kept in sync by
+ *   the backfill's drift auto-heal pass.
+ */
+function readDecisionsFromMemories(
+  opts: DecisionQueryOpts | undefined,
+  includeSuperseded: boolean,
+): Decision[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = [
+      "category = 'architecture'",
+      "structured_fields LIKE '%\"sourceDecisionId\":\"%'",
+    ];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.milestoneId) {
+      // when_context is a free-text JSON value; substring match preserves the
+      // semantics of `when_context LIKE '%milestoneId%'` on the legacy table.
+      clauses.push("json_extract(structured_fields, '$.when_context') LIKE :milestone_pattern");
+      params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+    }
+
+    if (opts?.scope) {
+      // Stage 1 used `json_extract` in main (post-merge); preserve that
+      // style here. Exact equality on the JSON value avoids the prefix
+      // collision risk LIKE patterns had (scope=M001 vs scope=M001-S01).
+      clauses.push("json_extract(structured_fields, '$.scope') = :scope");
+      params[':scope'] = opts.scope;
+    }
+
+    const sql = `SELECT seq, structured_fields FROM memories WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+    const rows = adapter.prepare(sql).all(params) as Array<Record<string, unknown>>;
+
+    const decisions: Decision[] = [];
+    for (const row of rows) {
+      const seq = row['seq'] as number;
+      const sfRaw = row['structured_fields'] as string | null;
+      if (!sfRaw) continue;
+      let sf: Record<string, unknown>;
+      try {
+        sf = JSON.parse(sfRaw) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const sourceId = sf['sourceDecisionId'];
+      if (typeof sourceId !== 'string' || sourceId.length === 0) continue;
+
+      // Decision-level superseded status lives in structured_fields.superseded_by
+      // (written by mirrorDecisionToMemory / memory-backfill.ts). The top-level
+      // memories.superseded_by column is intentionally never set for decision mirrors,
+      // so active-only filtering must be done here in the JS loop.
+      const supersededBy = typeof sf['superseded_by'] === 'string' ? (sf['superseded_by'] as string) : null;
+      if (!includeSuperseded && supersededBy) continue;
+
+      decisions.push({
+        seq,
+        id: sourceId,
+        when_context: typeof sf['when_context'] === 'string' ? (sf['when_context'] as string) : '',
+        scope: typeof sf['scope'] === 'string' ? (sf['scope'] as string) : '',
+        decision: typeof sf['decision'] === 'string' ? (sf['decision'] as string) : '',
+        choice: typeof sf['choice'] === 'string' ? (sf['choice'] as string) : '',
+        rationale: typeof sf['rationale'] === 'string' ? (sf['rationale'] as string) : '',
+        revisable: typeof sf['revisable'] === 'string' ? (sf['revisable'] as string) : '',
+        made_by: ((typeof sf['made_by'] === 'string' ? sf['made_by'] : 'agent') as DecisionMadeBy),
+        superseded_by: supersededBy,
+      });
+    }
+
+    return decisions;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * ADR-013 Phase 6 cutover (Stage 1): read **active** decisions from the
+ * `memories` table instead of the legacy `decisions` table. Returns the
+ * same `Decision[]` shape as `queryDecisions` so downstream formatters
+ * work unchanged.
+ *
+ * Filter semantics match `queryDecisions` exactly:
+ * - active only (skips rows where `structured_fields.superseded_by` is set)
+ * - `milestoneId`: substring match on `structured_fields.when_context`
+ * - `scope`: exact match on `structured_fields.scope`
+ *
+ * Used by the prompt-inline path (`inlineDecisionsFromDb` in
+ * `auto-prompts.ts`). For the projection regen (which renders superseded
+ * rows too), see `getAllDecisionsFromMemories`.
+ */
+export function queryDecisionsFromMemories(opts?: DecisionQueryOpts): Decision[] {
+  return readDecisionsFromMemories(opts, /* includeSuperseded */ false);
+}
+
+/**
+ * ADR-013 Phase 6 cutover (Stage 2a): read **all** decisions (active +
+ * superseded) from the `memories` table. Used by the DECISIONS.md
+ * projection regen in `saveDecisionToDb`, which must render the full
+ * supersedes-chain for the canonical register format.
+ *
+ * Equivalent to `SELECT * FROM decisions ORDER BY seq` over the legacy
+ * table — but sourced from memories so the legacy table can be retired
+ * in Stage 3. Includes `superseded_by` reconstructed from
+ * `structured_fields.superseded_by` (populated by the backfill's drift
+ * auto-heal pass).
+ */
+export function getAllDecisionsFromMemories(): Decision[] {
+  return readDecisionsFromMemories(undefined, /* includeSuperseded */ true);
+}
+
 /**
  * Query active (non-superseded) requirements with optional filters.
  * - milestoneId: combined with sliceId for precise filtering (e.g. %M005/S01%)