gsd-pi 2.75.0-next.9c0ec0ba1 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/gsd/health-widget-core.ts

@@ -61,9 +61,10 @@ function truncateMessage(msg: string, maxLen: number): string {
 
 /**
  * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
+ * When `width` is provided, system + budget render left and last-commit
+ * right-aligned. Without width, all parts are joined inline (RPC fallback).
  */
-export function buildHealthLines(data: HealthWidgetData): string[] {
+export function buildHealthLines(data: HealthWidgetData, width?: number): string[] {
   if (data.projectState === "none") {
     return ["  GSD  No project loaded — run /gsd to start"];
   }
@@ -72,40 +73,68 @@ export function buildHealthLines(data: HealthWidgetData): string[] {
     return ["  GSD  Project initialized — run /gsd to continue setup"];
   }
 
-  const parts: string[] = [];
+  const leftParts: string[] = [];
 
   const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
   if (totalIssues === 0) {
-    parts.push("● System OK");
+    leftParts.push("● System OK");
   } else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-    parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+    leftParts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
   } else {
-    parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+    leftParts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
   }
 
   if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
     const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-    parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+    leftParts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
   } else if (data.budgetSpent > 0) {
-    parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+    leftParts.push(`Spent: ${formatCost(data.budgetSpent)}`);
   }
 
   if (data.providerIssue) {
-    parts.push(data.providerIssue);
+    leftParts.push(data.providerIssue);
   }
 
   if (data.environmentErrorCount > 0) {
-    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+    leftParts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
   } else if (data.environmentWarningCount > 0) {
-    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+    leftParts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
   }
 
-  // Always-on last commit display — shows relative time + truncated message
+  // Last commit goes on the right-hand side when width is known.
+  let rightText = "";
   if (data.lastCommitEpoch !== null && data.lastCommitEpoch > 0) {
     const relTime = formatRelativeTime(data.lastCommitEpoch);
     const msg = data.lastCommitMessage ? ` — ${truncateMessage(data.lastCommitMessage, 50)}` : "";
-    parts.push(`Last commit: ${relTime}${msg}`);
+    rightText = `Last commit: ${relTime}${msg}`;
   }
 
-  return [`  ${parts.join("  │  ")}`];
+  const leftText = leftParts.join("  │  ");
+
+  if (width === undefined) {
+    const inline = rightText ? `${leftText}  │  ${rightText}` : leftText;
+    return [`  ${inline}`];
+  }
+
+  const prefix = "  ";
+  const innerWidth = Math.max(0, width - prefix.length);
+  const leftVis = leftText.length;
+  const rightVis = rightText.length;
+
+  if (!rightText) return [`${prefix}${truncateMessage(leftText, innerWidth)}`];
+  const MIN_GAP = 2;
+  if (leftVis + MIN_GAP + rightVis > innerWidth) {
+    // Preserve the left (status + budget) and truncate the right side
+    // (last commit) with an ellipsis so the combined line never exceeds
+    // innerWidth. If even the left alone overflows, clamp it too.
+    const leftRoom = Math.max(1, Math.min(leftVis, innerWidth - MIN_GAP - 1));
+    const clampedLeft = truncateMessage(leftText, leftRoom);
+    const rightRoom = Math.max(0, innerWidth - clampedLeft.length - MIN_GAP);
+    const clampedRight = rightRoom > 0 ? truncateMessage(rightText, rightRoom) : "";
+    if (!clampedRight) return [`${prefix}${clampedLeft}`];
+    const pad = " ".repeat(Math.max(MIN_GAP, innerWidth - clampedLeft.length - clampedRight.length));
+    return [`${prefix}${clampedLeft}${pad}${clampedRight}`];
+  }
+  const padding = " ".repeat(innerWidth - leftVis - rightVis);
+  return [`${prefix}${leftText}${padding}${rightText}`];
 }

package/src/resources/extensions/gsd/health-widget.ts

@@ -129,12 +129,16 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       void refresh();
     }, REFRESH_INTERVAL_MS);
 
+    let cachedWidth: number | undefined;
     return {
-      render(_width: number): string[] {
-        if (!cachedLines) cachedLines = buildHealthLines(data);
+      render(width: number): string[] {
+        if (!cachedLines || cachedWidth !== width) {
+          cachedLines = buildHealthLines(data, width);
+          cachedWidth = width;
+        }
         return cachedLines;
       },
-      invalidate(): void { cachedLines = undefined; },
+      invalidate(): void { cachedLines = undefined; cachedWidth = undefined; },
       dispose(): void {
         clearInterval(refreshTimer);
       },

package/src/resources/extensions/gsd/hook-emitter.ts

@@ -0,0 +1,188 @@
+// GSD Extension — Layer 2 Event Emitter Bridge
+//
+// Holds a module-scoped reference to the ExtensionAPI so deeply-nested code
+// (auto-loop, git-service callers, verification, budget) can emit Layer 2
+// events without having to thread `pi` through every function signature.
+//
+// Set once from `registerGsdExtension`. All emitters are best-effort — a
+// missing `pi` (e.g. in standalone unit tests) silently becomes a no-op.
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type {
+  BeforeCommitEventResult,
+  BeforePrEventResult,
+  BeforePushEventResult,
+  BeforeVerifyEventResult,
+  BudgetThresholdEventResult,
+  VerifyFailure,
+} from "@gsd/pi-coding-agent";
+
+let _pi: ExtensionAPI | undefined;
+
+export function setHookEmitter(pi: ExtensionAPI): void {
+  _pi = pi;
+}
+
+export function clearHookEmitter(): void {
+  _pi = undefined;
+}
+
+// ─── Notification ──────────────────────────────────────────────────────────
+
+export async function emitNotification(
+  kind: "blocked" | "input_needed" | "milestone_ready" | "idle" | "error",
+  message: string,
+  details?: Record<string, unknown>,
+): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "notification", kind, message, details });
+}
+
+// ─── Git Lifecycle ─────────────────────────────────────────────────────────
+
+export async function emitBeforeCommit(args: {
+  message: string;
+  files: string[];
+  cwd: string;
+  author?: string;
+}): Promise<BeforeCommitEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_commit",
+    ...args,
+  })) as BeforeCommitEventResult | undefined;
+}
+
+export async function emitCommit(args: {
+  sha: string;
+  message: string;
+  files: string[];
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "commit", ...args });
+}
+
+export async function emitBeforePush(args: {
+  remote: string;
+  branch: string;
+  cwd: string;
+}): Promise<BeforePushEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_push",
+    ...args,
+  })) as BeforePushEventResult | undefined;
+}
+
+export async function emitPush(args: { remote: string; branch: string; cwd: string }): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "push", ...args });
+}
+
+export async function emitBeforePr(args: {
+  branch: string;
+  targetBranch: string;
+  title: string;
+  body: string;
+  cwd: string;
+}): Promise<BeforePrEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_pr",
+    ...args,
+  })) as BeforePrEventResult | undefined;
+}
+
+export async function emitPrOpened(args: {
+  url: string;
+  branch: string;
+  targetBranch: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "pr_opened", ...args });
+}
+
+// ─── Verification ──────────────────────────────────────────────────────────
+
+export async function emitBeforeVerify(args: {
+  unitType?: string;
+  unitId?: string;
+  cwd: string;
+}): Promise<BeforeVerifyEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_verify",
+    ...args,
+  })) as BeforeVerifyEventResult | undefined;
+}
+
+export async function emitVerifyResult(args: {
+  passed: boolean;
+  failures: VerifyFailure[];
+  unitType?: string;
+  unitId?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "verify_result", ...args });
+}
+
+// ─── Budget ────────────────────────────────────────────────────────────────
+
+export async function emitBudgetThreshold(args: {
+  fraction: number;
+  spent: number;
+  limit: number;
+}): Promise<BudgetThresholdEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "budget_threshold",
+    fraction: args.fraction,
+    spent: args.spent,
+    limit: args.limit,
+    currency: "USD",
+  })) as BudgetThresholdEventResult | undefined;
+}
+
+// ─── Orchestrator Boundaries ───────────────────────────────────────────────
+
+export async function emitMilestoneStart(args: {
+  milestoneId: string;
+  title?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "milestone_start", ...args });
+}
+
+export async function emitMilestoneEnd(args: {
+  milestoneId: string;
+  status: "completed" | "failed" | "cancelled";
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "milestone_end", ...args });
+}
+
+export async function emitUnitStart(args: {
+  unitType: string;
+  unitId: string;
+  milestoneId?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "unit_start", ...args });
+}
+
+export async function emitUnitEnd(args: {
+  unitType: string;
+  unitId: string;
+  milestoneId?: string;
+  status: "completed" | "failed" | "cancelled" | "blocked";
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "unit_end", ...args });
+}

package/src/resources/extensions/gsd/init-wizard.ts

@@ -17,6 +17,7 @@ import { assertSafeDirectory } from "./validate-directory.js";
 import type { ProjectDetection, ProjectSignals } from "./detection.js";
 import { runSkillInstallStep } from "./skill-catalog.js";
 import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js";
+import { handlePrefsWizard, writePreferencesFile } from "./commands-prefs-wizard.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -232,8 +233,53 @@ export async function showProjectInit(
     // Non-fatal — skill installation failure should never block project init
   }
 
-  // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
-  bootstrapGsdDirectory(basePath, prefs, signals);
+  // ── Step 9: Optional full-prefs review ─────────────────────────────────────
+  // Ask BEFORE bootstrapping so a defer (`not_yet`) leaves the project untouched.
+  // Once the user commits, we bootstrap and route preferences through the unified
+  // writer (commands-prefs-wizard.writePreferencesFile) so init and the prefs
+  // wizard share one serializer. The "Open full wizard" branch surfaces every
+  // configurable preference, prefilled with the init answers.
+  const reviewChoice = await showNextAction(ctx, {
+    title: "GSD — Review All Preferences (Optional)",
+    summary: [
+      "Open the full preferences wizard now? It includes models, timeouts,",
+      "budget, notifications, and skills — all pre-filled with your answers.",
+      "",
+      "Skip if you just want sensible defaults; you can always run /gsd prefs project later.",
+    ],
+    actions: [
+      { id: "skip", label: "Skip — use defaults", description: "Save preferences and continue", recommended: true },
+      { id: "review", label: "Open full wizard", description: "Tweak any category before saving" },
+    ],
+    notYetMessage: "Run /gsd init when ready.",
+  });
+
+  if (reviewChoice === "not_yet") {
+    // User deferred — don't create .gsd/ or persist preferences. Pre-step state
+    // (e.g. git init from Step 2) remains as-is, matching prior step semantics.
+    return { completed: false, bootstrapped: false };
+  }
+
+  // ── Step 10: Bootstrap .gsd/ + write preferences ───────────────────────────
+  bootstrapGsdDirectoryStructure(basePath, signals);
+  const prefillPrefs = mapInitPrefsToWizardShape(prefs);
+  // Always derive the preferences path from basePath so init writing the
+  // structure to one location and preferences to another (cwd-derived) is
+  // impossible — see #4457 codex review.
+  const projectPrefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+
+  if (reviewChoice === "review") {
+    // Wizard writes via writePreferencesFile internally; pass pathOverride so it
+    // targets basePath rather than cwd.
+    await handlePrefsWizard(ctx, "project", prefillPrefs, { pathOverride: projectPrefsPath });
+  } else {
+    // Direct path: write the init-collected prefs through the unified writer.
+    await writePreferencesFile(projectPrefsPath, prefillPrefs, ctx, {
+      scope: "project",
+      defaultBody: buildInitPreferencesBody(),
+      notifyOnSave: false,
+    });
+  }
 
   // Initialize SQLite database so GSD starts in full-capability mode (#3880).
   // Without this, isDbAvailable() returns false and GSD enters degraded
@@ -453,11 +499,13 @@ async function customizeAdvancedPrefs(
 
 // ─── Bootstrap ──────────────────────────────────────────────────────────────────
 
-function bootstrapGsdDirectory(
-  basePath: string,
-  prefs: ProjectPreferences,
-  signals: ProjectSignals,
-): void {
+/**
+ * Create .gsd/ directory structure and seed CONTEXT.md.
+ *
+ * Preferences are written separately by the caller via the unified
+ * writePreferencesFile helper so init and the prefs wizard share one path.
+ */
+function bootstrapGsdDirectoryStructure(basePath: string, signals: ProjectSignals): void {
   // Final safety check before writing any files
   assertSafeDirectory(basePath);
 
@@ -465,10 +513,6 @@ function bootstrapGsdDirectory(
   mkdirSync(join(gsd, "milestones"), { recursive: true });
   mkdirSync(join(gsd, "runtime"), { recursive: true });
 
-  // Write PREFERENCES.md from wizard answers
-  const preferencesContent = buildPreferencesFile(prefs);
-  writeFileSync(join(gsd, "PREFERENCES.md"), preferencesContent, "utf-8");
-
   // Seed CONTEXT.md with detected project signals
   const contextContent = buildContextSeed(signals);
   if (contextContent) {
@@ -476,60 +520,49 @@ function bootstrapGsdDirectory(
   }
 }
 
-function buildPreferencesFile(prefs: ProjectPreferences): string {
-  const lines: string[] = ["---"];
-  lines.push("version: 1");
-  lines.push(`mode: ${prefs.mode}`);
-
-  // Git preferences
-  lines.push("git:");
-  lines.push(`  isolation: ${prefs.gitIsolation}`);
-  lines.push(`  main_branch: ${prefs.mainBranch}`);
-  lines.push(`  auto_push: ${prefs.autoPush}`);
+/**
+ * Map init wizard's typed ProjectPreferences to the prefs-wizard's
+ * Record<string, unknown> shape, matching the keys serializePreferencesToFrontmatter
+ * expects (mode, git.{isolation,main_branch,auto_push}, verification_commands, etc.).
+ *
+ * Exported for testing; init-wizard uses it inline.
+ */
+export function mapInitPrefsToWizardShape(prefs: ProjectPreferences): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    mode: prefs.mode,
+    git: {
+      isolation: prefs.gitIsolation,
+      main_branch: prefs.mainBranch,
+      auto_push: prefs.autoPush,
+    },
+  };
 
-  // Verification commands
   if (prefs.verificationCommands.length > 0) {
-    lines.push("verification_commands:");
-    for (const cmd of prefs.verificationCommands) {
-      lines.push(`  - "${cmd}"`);
-    }
+    out.verification_commands = prefs.verificationCommands;
   }
-
-  // Custom instructions
   if (prefs.customInstructions.length > 0) {
-    lines.push("custom_instructions:");
-    for (const inst of prefs.customInstructions) {
-      lines.push(`  - "${inst.replace(/"/g, '\\"')}"`);
-    }
+    out.custom_instructions = prefs.customInstructions;
   }
-
-  // Token profile (only if non-default)
   if (prefs.tokenProfile !== "balanced") {
-    lines.push(`token_profile: ${prefs.tokenProfile}`);
+    out.token_profile = prefs.tokenProfile;
   }
-
-  // Phase skips
   if (prefs.skipResearch) {
-    lines.push("phases:");
-    lines.push("  skip_research: true");
+    out.phases = { skip_research: true };
   }
 
-  // Defaults for wizard-generated files
-  lines.push("always_use_skills: []");
-  lines.push("prefer_skills: []");
-  lines.push("avoid_skills: []");
-  lines.push("skill_rules: []");
-
-  lines.push("---");
-  lines.push("");
-  lines.push("# GSD Project Preferences");
-  lines.push("");
-  lines.push("Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.");
-  lines.push("");
-  lines.push("See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.");
-  lines.push("");
+  return out;
+}
 
-  return lines.join("\n");
+function buildInitPreferencesBody(): string {
+  return [
+    "",
+    "# GSD Project Preferences",
+    "",
+    "Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.",
+    "",
+    "See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.",
+    "",
+  ].join("\n");
 }
 
 function buildContextSeed(signals: ProjectSignals): string | null {

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -169,7 +169,7 @@ function renderRoadmapMarkdown(milestone: MilestoneRow, slices: SliceRow[]): str
   lines.push("## Slices");
   lines.push("");
   for (const slice of slices) {
-    const done = slice.status === "complete" ? "x" : " ";
+    const done = isClosedStatus(slice.status) ? "x" : " ";
     const depends = `[${(slice.depends ?? []).join(",")}]`;
     lines.push(`- [${done}] **${slice.id}: ${slice.title}** \`risk:${slice.risk}\` \`depends:${depends}\``);
     lines.push(`  > After this: ${slice.demo}`);
@@ -496,7 +496,7 @@ export async function renderRoadmapCheckboxes(
   // Apply checkbox patches for each slice
   let updated = content;
   for (const slice of slices) {
-    const isDone = slice.status === "complete";
+    const isDone = isClosedStatus(slice.status);
     const sid = slice.id;
 
     if (isDone) {
@@ -821,19 +821,19 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
         const parsed = parseRoadmap(content);
 
         for (const slice of slices) {
-          const isCompleteInDb = slice.status === "complete";
+          const isCompleteInDb = isClosedStatus(slice.status);
           const roadmapSlice = parsed.slices.find((s: { id: string }) => s.id === slice.id);
           if (!roadmapSlice) continue;
 
           if (isCompleteInDb && !roadmapSlice.done) {
             stale.push({
               path: roadmapPath,
-              reason: `${slice.id} is complete in DB but unchecked in roadmap`,
+              reason: `${slice.id} is closed in DB but unchecked in roadmap`,
             });
           } else if (!isCompleteInDb && roadmapSlice.done) {
             stale.push({
               path: roadmapPath,
-              reason: `${slice.id} is not complete in DB but checked in roadmap`,
+              reason: `${slice.id} is not closed in DB but checked in roadmap`,
             });
           }
         }

package/src/resources/extensions/gsd/memory-backfill.ts

@@ -0,0 +1,140 @@
+// GSD2 — Decisions -> memories backfill (ADR-013 step 5)
+//
+// Idempotent one-shot migration that copies every active decisions row into
+// the memories table with category="architecture" and a structured_fields
+// payload preserving the original gsd_save_decision schema (when_context,
+// scope, decision, choice, rationale, made_by, revisable, sourceDecisionId).
+//
+// The backfill exists so the cutover in ADR-013 step 6 can drop the
+// decisions table without losing schema fidelity. Idempotency is enforced
+// by tagging each backfilled memory with structured_fields.sourceDecisionId
+// and skipping any decision whose ID already appears in the memories table.
+//
+// Triggered opportunistically by buildBeforeAgentStartResult so the cost
+// only ever fires once per project. Costs O(N) inserts on first run where
+// N is the active-decisions count; subsequent runs are an O(N) lookup that
+// finds existing markers and exits.
+
+import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import { createMemory } from "./memory-store.js";
+import { logWarning } from "./workflow-logger.js";
+
+interface DecisionRow {
+  id: string;
+  when_context: string;
+  scope: string;
+  decision: string;
+  choice: string;
+  rationale: string;
+  made_by: string;
+  revisable: string;
+  superseded_by: string | null;
+}
+
+/**
+ * Backfill active decisions rows into the memories table.
+ *
+ * - Idempotent (per-row): every row written carries
+ *   `structured_fields.sourceDecisionId = "<decisionId>"`. Each candidate
+ *   decision is checked individually; only decisions whose id is already
+ *   present in the memory store are skipped. A user-authored memory with
+ *   their own `sourceDecisionId` does NOT abort the backfill.
+ * - Best-effort: never throws. Logs and returns 0 on failure so a broken
+ *   backfill cannot block agent startup.
+ * - Active-only: skips rows where `superseded_by IS NOT NULL`. Superseded
+ *   decisions are historical record; the memory store is for active
+ *   knowledge.
+ *
+ * Returns the number of memories written (0 when already backfilled or
+ * when the DB has no decisions). Callers can log the result or surface it
+ * to the user.
+ */
+export function backfillDecisionsToMemories(): number {
+  if (!isDbAvailable()) return 0;
+  const adapter = _getAdapter();
+  if (!adapter) return 0;
+
+  try {
+    const decisions = adapter
+      .prepare("SELECT id, when_context, scope, decision, choice, rationale, made_by, revisable, superseded_by FROM decisions WHERE superseded_by IS NULL")
+      .all() as Array<Record<string, unknown>>;
+
+    if (decisions.length === 0) return 0;
+
+    // Per-row idempotency: each memory backfilled from a decision carries
+    // structured_fields.sourceDecisionId="<decisionId>". Skipping is decided
+    // per row by matching that exact id, NOT by a global sentinel — a global
+    // sentinel would silently abort the backfill if a user manually called
+    // capture_thought with their own structuredFields.sourceDecisionId.
+    const checkExisting = adapter.prepare(
+      "SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1",
+    );
+
+    let written = 0;
+    for (const raw of decisions) {
+      const row: DecisionRow = {
+        id: String(raw["id"] ?? ""),
+        when_context: String(raw["when_context"] ?? ""),
+        scope: String(raw["scope"] ?? ""),
+        decision: String(raw["decision"] ?? ""),
+        choice: String(raw["choice"] ?? ""),
+        rationale: String(raw["rationale"] ?? ""),
+        made_by: String(raw["made_by"] ?? "agent"),
+        revisable: String(raw["revisable"] ?? ""),
+        superseded_by: raw["superseded_by"] == null ? null : String(raw["superseded_by"]),
+      };
+      if (!row.id) continue;
+
+      // Pattern is anchored to the JSON-stringified shape and the exact
+      // decision id to avoid prefix collisions (e.g. "D1" vs "D10").
+      if (checkExisting.get({ ":pattern": `%"sourceDecisionId":"${row.id}"%` })) continue;
+
+      const content = synthesizeContent(row);
+      const id = createMemory({
+        category: "architecture",
+        content,
+        scope: row.scope || "project",
+        confidence: 0.85,
+        structuredFields: {
+          sourceDecisionId: row.id,
+          when_context: row.when_context,
+          scope: row.scope,
+          decision: row.decision,
+          choice: row.choice,
+          rationale: row.rationale,
+          made_by: row.made_by,
+          revisable: row.revisable,
+        },
+      });
+      if (id) written += 1;
+    }
+
+    return written;
+  } catch (e) {
+    logWarning("memory-backfill", `decisions->memories backfill failed: ${(e as Error).message}`);
+    return 0;
+  }
+}
+
+/**
+ * Combine the decision's structured fields into a 1-3 sentence content
+ * string suitable for keyword retrieval and human review.
+ *
+ * Format: "<decision> Chose: <choice>. Rationale: <rationale>."
+ * Truncates each field to keep the synthesized line under ~600 chars so
+ * memory_query rendering stays readable.
+ */
+function synthesizeContent(row: DecisionRow): string {
+  const trim = (value: string, max: number): string => {
+    const cleaned = value.replace(/\s+/g, " ").trim();
+    return cleaned.length > max ? cleaned.slice(0, max - 1) + "\u2026" : cleaned;
+  };
+  const parts: string[] = [];
+  const decision = trim(row.decision, 240);
+  const choice = trim(row.choice, 200);
+  const rationale = trim(row.rationale, 200);
+  if (decision) parts.push(decision);
+  if (choice) parts.push(`Chose: ${choice}.`);
+  if (rationale) parts.push(`Rationale: ${rationale}.`);
+  return parts.join(" ");
+}