gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

package/src/resources/extensions/gsd/db-writer.ts

@@ -235,14 +235,63 @@ export async function nextDecisionId(): Promise<string> {
   }
 }
 
-/** Synchronous variant for use inside db.transaction(). */
-function nextDecisionIdSync(adapter: ReturnType<typeof import('./gsd-db.js')._getAdapter>): string {
+/**
+ * ADR-013 Stage 3: compute the next `D###` identifier across both the legacy
+ * `decisions` table AND the `memories.structured_fields.sourceDecisionId`
+ * surface. Returns the max numeric suffix from either side + 1, three-digit
+ * padded.
+ *
+ * Used by `saveDecisionToDb` once writes to the `decisions` table stop —
+ * new decisions live only in memories, but historical IDs sit in both
+ * places during the cutover bake. The cross-surface max keeps IDs
+ * monotonic and avoids collisions on the next save.
+ */
+function nextDecisionIdAcrossSurfaces(
+  adapter: ReturnType<typeof import('./gsd-db.js')._getAdapter>,
+): string {
   if (!adapter) return 'D001';
-  const row = adapter
-    .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
-    .get();
-  const maxNum = row ? (row['max_num'] as number | null) : null;
-  if (maxNum == null || isNaN(maxNum)) return 'D001';
+
+  let maxNum = 0;
+
+  // Legacy table — best-effort.
+  try {
+    const row = adapter
+      .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
+      .get();
+    const candidate = row ? (row['max_num'] as number | null) : null;
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+      maxNum = Math.max(maxNum, candidate);
+    }
+  } catch {
+    // fall through to memory-only
+  }
+
+  // Memory surface: scan structuredFields.sourceDecisionId for D### values.
+  // SQLite LIKE on the JSON-stringified field is sufficient — rows tagged
+  // with sourceDecisionId are bounded by the decisions count.
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT structured_fields FROM memories WHERE structured_fields LIKE '%\"sourceDecisionId\":\"D%'",
+      )
+      .all() as Array<{ structured_fields: string | null }>;
+    for (const row of rows) {
+      if (!row.structured_fields) continue;
+      let sf: Record<string, unknown>;
+      try {
+        sf = JSON.parse(row.structured_fields) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const sourceId = sf['sourceDecisionId'];
+      if (typeof sourceId !== 'string' || !sourceId.startsWith('D')) continue;
+      const num = parseInt(sourceId.slice(1), 10);
+      if (Number.isFinite(num) && num > maxNum) maxNum = num;
+    }
+  } catch {
+    // best-effort
+  }
+
   const next = maxNum + 1;
   return `D${String(next).padStart(3, '0')}`;
 }
@@ -416,6 +465,16 @@ export interface SaveDecisionFields {
   source?: string;
 }
 
+type NormalizedSaveDecisionFields = Omit<
+  SaveDecisionFields,
+  'when_context' | 'revisable' | 'made_by' | 'source'
+> & {
+  when_context: string;
+  revisable: string;
+  made_by: NonNullable<SaveDecisionFields['made_by']>;
+  source: string;
+};
+
 /**
  * Save a new decision to DB and regenerate DECISIONS.md.
  * Auto-assigns the next ID via nextDecisionId().
@@ -445,44 +504,59 @@ export async function saveDecisionToDb(
 
   try {
     const db = await import('./gsd-db.js');
-
     const adapter = db._getAdapter();
+    const normalized: NormalizedSaveDecisionFields = {
+      ...fields,
+      when_context: fields.when_context ?? '',
+      revisable: fields.revisable ?? 'Yes',
+      made_by: fields.made_by ?? 'agent',
+      source: fields.source ?? 'discussion',
+    };
 
-    const id = db.transaction(() => {
-      const nextId = nextDecisionIdSync(adapter);
-      db.upsertDecision({
-        id: nextId,
-        when_context: fields.when_context ?? '',
-        scope: fields.scope,
-        decision: fields.decision,
-        choice: fields.choice,
-        rationale: fields.rationale,
-        revisable: fields.revisable ?? 'Yes',
-        made_by: fields.made_by ?? 'agent',
-        source: fields.source ?? 'discussion',
-        superseded_by: null,
+    // ADR-013 Stage 3 (destructive): writes to the `decisions` table stop
+    // here. New decisions live only in the `memories` table; the projection
+    // regen below sources from memories (Stage 2a). The decisions table
+    // remains for backwards-compat reads (queryDecisions, md-importer,
+    // commands-inspect, workflow-manifest) until #5756 drops it.
+    //
+    // Reversal: a code revert of this change restores the upsertDecision
+    // call. Memory rows written between merge and revert stay durable; the
+    // legacy table simply doesn't grow during the cutover window.
+    const id = nextDecisionIdAcrossSurfaces(adapter);
+
+    // The mirror-to-memories write is what persists the new decision. Must
+    // run before the projection regen — the regen sources from memories
+    // (Stage 2a) and would otherwise miss the just-saved decision. Pass
+    // the normalized field set so defaults (revisable, made_by, source)
+    // are recorded on the memory row.
+    await mirrorDecisionToMemory(id, normalized);
+
+    // Fetch all decisions (including superseded for the full register).
+    // ADR-013 Stage 2a: source from the `memories` table. The Phase 5
+    // dual-write keeps memories in sync with each decision save; the backfill
+    // (memory-backfill.ts) absorbs the historical chain and drift-heals
+    // superseded_by on every session start.
+    const { getAllDecisionsFromMemories } = await import('./context-store.js');
+    let allDecisions: Decision[] = getAllDecisionsFromMemories();
+    if (!allDecisions.some(d => d.id === id)) {
+      logWarning('projection', 'just-saved decision missing from memories after mirror; injecting fallback for projection', {
+        fn: 'saveDecisionToDb',
+        decisionId: id,
       });
-
-
-      return nextId;
-    });
-
-    // Fetch all decisions (including superseded for the full register)
-    let allDecisions: Decision[] = [];
-    if (adapter) {
-      const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
-      allDecisions = rows.map(row => ({
-        seq: row['seq'] as number,
-        id: row['id'] as string,
-        when_context: row['when_context'] as string,
-        scope: row['scope'] as string,
-        decision: row['decision'] as string,
-        choice: row['choice'] as string,
-        rationale: row['rationale'] as string,
-        revisable: row['revisable'] as string,
-        made_by: (row['made_by'] as string as import('./types.js').DecisionMadeBy) ?? 'agent',
-        superseded_by: (row['superseded_by'] as string) ?? null,
-      }));
+      const nextSeq = allDecisions.reduce((max, d) => Math.max(max, d.seq ?? 0), 0) + 1;
+      const fallback: Decision = {
+        seq: nextSeq,
+        id,
+        when_context: normalized.when_context,
+        scope: normalized.scope,
+        decision: normalized.decision,
+        choice: normalized.choice,
+        rationale: normalized.rationale,
+        revisable: normalized.revisable,
+        made_by: normalized.made_by,
+        superseded_by: null,
+      };
+      allDecisions = [...allDecisions, fallback];
     }
 
     const filePath = resolveGsdRootFile(basePath, 'DECISIONS');
@@ -538,48 +612,6 @@ export async function saveDecisionToDb(
     clearPathCache();
     clearParseCache();
 
-    // ADR-013 dual-write: keep the memory store in sync with every decision
-    // persisted via the legacy gsd_save_decision path. Without this, prompts
-    // that still call gsd_save_decision (discuss.md, plan-milestone.md,
-    // plan-slice.md, et al.) would create decisions rows invisible to
-    // memory_query and loadMemoryBlock.
-    // Best-effort — never throw, never roll back the decision on failure.
-    try {
-      const { createMemory } = await import('./memory-store.js');
-      const decisionText = (fields.decision ?? '').trim();
-      const choiceText = (fields.choice ?? '').trim();
-      const rationaleText = (fields.rationale ?? '').trim();
-      const contentParts: string[] = [];
-      if (decisionText) contentParts.push(decisionText);
-      if (choiceText) contentParts.push(`Chose: ${choiceText}.`);
-      if (rationaleText) contentParts.push(`Rationale: ${rationaleText}.`);
-      const content = contentParts.join(' ').slice(0, 600);
-      if (content) {
-        createMemory({
-          category: 'architecture',
-          content,
-          scope: fields.scope || 'project',
-          confidence: 0.85,
-          structuredFields: {
-            sourceDecisionId: id,
-            when_context: fields.when_context ?? '',
-            scope: fields.scope,
-            decision: fields.decision,
-            choice: fields.choice,
-            rationale: fields.rationale,
-            made_by: fields.made_by ?? 'agent',
-            revisable: fields.revisable ?? '',
-          },
-        });
-      }
-    } catch (mirrorErr) {
-      logError('manifest', 'memory-store mirror write failed (non-fatal)', {
-        fn: 'saveDecisionToDb',
-        decisionId: id,
-        error: String((mirrorErr as Error).message),
-      });
-    }
-
     return { id };
   } catch (err) {
     logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String((err as Error).message) });
@@ -589,6 +621,57 @@ export async function saveDecisionToDb(
   }
 }
 
+/**
+ * ADR-013 dual-write — mirror a freshly-saved decision into the `memories`
+ * table so the memory store remains the single source of truth for the
+ * DECISIONS.md projection (Stage 2a) and for prompt-inline reads (Stage 1).
+ *
+ * Best-effort mirror: logs failures without throwing to avoid blocking saves.
+ * Caller invokes this AFTER the decisions-table write completes and
+ * BEFORE the projection regen — the regen sources from memories and would
+ * otherwise miss the just-saved decision.
+ */
+async function mirrorDecisionToMemory(
+  id: string,
+  normalizedFields: NormalizedSaveDecisionFields,
+): Promise<boolean> {
+  try {
+    const { createMemory } = await import('./memory-store.js');
+    const { synthesizeDecisionMemoryContent } = await import('./memory-backfill.js');
+    const content = synthesizeDecisionMemoryContent(normalizedFields);
+    if (!content) return false;
+
+    createMemory({
+      category: 'architecture',
+      content,
+      scope: normalizedFields.scope || 'project',
+      confidence: 0.85,
+      structuredFields: {
+        sourceDecisionId: id,
+        when_context: normalizedFields.when_context,
+        scope: normalizedFields.scope,
+        decision: normalizedFields.decision,
+        choice: normalizedFields.choice,
+        rationale: normalizedFields.rationale,
+        made_by: normalizedFields.made_by,
+        revisable: normalizedFields.revisable,
+        // New decisions are always written as active; md-importer can later
+        // set superseded_by on the source decision row, and the backfill's
+        // drift auto-heal pass propagates that update to this memory.
+        superseded_by: null,
+      },
+    });
+    return true;
+  } catch (mirrorErr) {
+    logError('manifest', 'memory-store mirror write failed', {
+      fn: 'saveDecisionToDb',
+      decisionId: id,
+      error: String((mirrorErr as Error).message),
+    });
+    return false;
+  }
+}
+
 /**
  * Extract a milestone/slice reference from a deferral decision.
  *

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -100,7 +100,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `skill_rules`: situational rules with a human-readable `when` trigger and one or more of `use`, `prefer`, or `avoid`.
 
-- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
+- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge, use `.gsd/KNOWLEDGE.md` instead. Rules are file-canonical; patterns and lessons are persisted to the `memories` table and projected back into `KNOWLEDGE.md` on the next session start.
 
 - `language`: preferred response language for all GSD interactions. Accepts any language name or code — `"Chinese"`, `"zh"`, `"German"`, `"de"`, `"日本語"`, etc. When set, GSD injects "Always respond in \<language\>" into every agent's system prompt, including after `/clear`. Quickest way to set it: `/gsd language <name>`. To clear: `/gsd language off`.
 

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -1,3 +1,5 @@
+// GSD-2 doctor git health checks
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { join, sep } from "node:path";
 
@@ -52,6 +54,26 @@ function isSameOrNestedPath(candidate: string, container: string): boolean {
     normalizedCandidate.startsWith(`${normalizedContainer}/`);
 }
 
+function getSnapshotDiffCheckFailure(basePath: string): string | null {
+  const failures: string[] = [];
+
+  for (const args of [["--cached"], []]) {
+    const result = spawnSync("git", ["diff", "--check", ...args], {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    if (result.status === 0) continue;
+
+    const output = [result.stdout, result.stderr, result.error?.message]
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    failures.push(output || `git diff --check ${args.join(" ")} failed`);
+  }
+
+  return failures.length > 0 ? failures.join("\n") : null;
+}
+
 async function isCompletedMilestoneTerminal(basePath: string, milestoneId: string): Promise<boolean> {
   const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
   if (!summaryPath) return false;
@@ -411,15 +433,31 @@ export async function checkGitHealth(
             fixable: true,
           });
 
+          const diffCheckFailure = getSnapshotDiffCheckFailure(basePath);
+          if (diffCheckFailure) {
+            issues.push({
+              severity: "error",
+              code: "conflict_markers_in_tracked_files",
+              scope: "project",
+              unitId: "project",
+              message: `Cannot create gsd snapshot: tracked changes contain conflict markers or whitespace errors. Resolve conflicts manually before auto-mode can proceed.\n${diffCheckFailure}`,
+              fixable: false,
+            });
+          }
+
           if (shouldFix("stale_uncommitted_changes")) {
             try {
-              nativeAddTracked(basePath);
-              const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
-              const result = nativeCommit(basePath, commitMsg);
-              if (result) {
-                fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
+              if (diffCheckFailure) {
+                fixesApplied.push("gsd snapshot skipped - conflict markers detected in tracked files");
               } else {
-                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
+                nativeAddTracked(basePath);
+                const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
+                const result = nativeCommit(basePath, commitMsg);
+                if (result) {
+                  fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
+                } else {
+                  fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
+                }
               }
             } catch {
               fixesApplied.push("failed to create gsd snapshot commit");

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

@@ -1,3 +1,4 @@
+// GSD-2 doctor report types
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
   | "invalid_preferences"
@@ -65,6 +66,7 @@ export type DoctorIssueCode =
   | "worktree_unpushed"
   // Stale commit safety check
   | "stale_uncommitted_changes"
+  | "conflict_markers_in_tracked_files"
   // Snapshot ref bloat
   | "snapshot_ref_bloat"
   // Runtime data integrity

package/src/resources/extensions/gsd/git-service.ts

@@ -37,6 +37,7 @@ import {
   nativeAddPaths,
   nativeResetSoft,
   nativeCommitSubject,
+  nativeIsIgnored,
   _resetHasChangesCache,
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
@@ -760,6 +761,7 @@ export class GitServiceImpl {
     const normalized = keyFiles
       .map(file => normalizeRepoRelativePath(this.basePath, file))
       .filter((file): file is string => file !== null)
+      .filter(file => !nativeIsIgnored(this.basePath, file))
       .filter(file => !isExcludedScopedPath(file, allExclusions));
 
     // Drop entries that don't exist on disk. The LLM occasionally lists files

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

@@ -1136,33 +1136,17 @@ export function setSliceSketchFlag(milestoneId: string, sliceId: string, isSketc
 }
 
 /**
- * ADR-011 auto-heal: reconcile stale is_sketch=1 rows whose PLAN already exists.
- *
- * Callers pass a predicate that resolves whether a plan file exists for a slice.
- * The predicate MUST use the canonical path resolver (`resolveSliceFile`, etc.)
- * to keep path logic in one place — do not hand-roll the path inside the callback.
- *
- * Recovers from two scenarios:
- *   1. Crash between `gsd_plan_slice` write and the sketch flag flip.
- *   2. Flag-OFF downgrade path: when `progressive_planning` is off, the dispatch
- *      rule routes sketch slices to plan-slice, which writes PLAN.md but leaves
- *      `is_sketch=1` — the next state derivation auto-heals it to 0 here.
- *
- * Not aggressive in practice: PLAN.md is only written via the DB-backed
- * `gsd_plan_slice` tool (which also inserts tasks), so a "stale PLAN.md with
- * is_sketch=1" is extremely unlikely to indicate anything other than the two
- * recovery scenarios above.
+ * ADR-017 raw primitive: returns slice IDs in a milestone whose is_sketch flag
+ * is still 1. The stale-sketch-flag drift handler at
+ * `state-reconciliation/drift/sketch-flag.ts` composes this with PLAN.md
+ * existence checks to detect drift, then writes via `setSliceSketchFlag`.
  */
-export function autoHealSketchFlags(milestoneId: string, hasPlanFile: (sliceId: string) => boolean): void {
-  if (!currentDb) return;
+export function getSketchedSliceIds(milestoneId: string): string[] {
+  if (!currentDb) return [];
   const rows = currentDb.prepare(
     `SELECT id FROM slices WHERE milestone_id = :mid AND is_sketch = 1`,
   ).all({ ":mid": milestoneId }) as Array<{ id: string }>;
-  for (const row of rows) {
-    if (hasPlanFile(row.id)) {
-      setSliceSketchFlag(milestoneId, row.id, false);
-    }
-  }
+  return rows.map((r) => r.id);
 }
 
 export function upsertSlicePlanning(milestoneId: string, sliceId: string, planning: Partial<SlicePlanningRecord>): void {

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

@@ -70,7 +70,7 @@ export function buildHealthLines(data: HealthWidgetData, width?: number): string
   }
 
   if (data.projectState === "initialized") {
-    return ["  GSD  Project initialized — run /gsd to continue setup"];
+    return ["  GSD  Project Initialized"];
   }
 
   const leftParts: string[] = [];

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

@@ -1,12 +1,5 @@
-/**
- * GSD Health Widget — always-on ambient health signal rendered belowEditor.
- *
- * Shows a compact 1-2 line summary: progress score, budget, provider key
- * status, and doctor/environment issue count. Refreshes every 60 seconds.
- * Quiet when everything is healthy; turns amber/red when issues arise.
- *
- * Widget key: "gsd-health", placement: "belowEditor"
- */
+// Project/App: GSD-2
+// File Purpose: Always-on ambient health signal rendered below the editor.
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import type { GSDState } from "./types.js";
@@ -24,6 +17,9 @@ import {
   type HealthWidgetData,
 } from "./health-widget-core.js";
 
+export const HEALTH_WIDGET_ACTIVE_HINTS =
+  "  /gsd auto to run  ·  /gsd status for overview  ·  /gsd visualize to inspect  ·  /gsd notifications for history  ·  /gsd help";
+
 // ── Data loader ────────────────────────────────────────────────────────────────
 
 function loadHealthWidgetData(basePath: string): HealthWidgetData {
@@ -136,7 +132,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
         if (!cachedLines || cachedWidth !== width) {
           cachedLines = buildHealthLines(data, width);
           if (data.projectState === "active") {
-            cachedLines = [...cachedLines, _theme.fg("dim", "  /gsd auto to run  ·  /gsd status for overview  ·  /gsd help")];
+            cachedLines = [...cachedLines, _theme.fg("dim", HEALTH_WIDGET_ACTIVE_HINTS)];
           }
           cachedWidth = width;
         }

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

@@ -39,6 +39,8 @@ export type JournalEventType =
   | "unit-start"
   | "unit-end"
   | "post-unit-hook"
+  | "post-unit-finalize-start"
+  | "post-unit-finalize-end"
   | "terminal"
   | "guard-block"
   | "milestone-transition"

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

@@ -0,0 +1,164 @@
+// GSD2 — KNOWLEDGE.md -> memories backfill (ADR-013 Stage 2b).
+//
+// Idempotent migration of `.gsd/KNOWLEDGE.md` Patterns and Lessons rows into
+// the `memories` table. Patterns become memories with `category: "pattern"`;
+// Lessons become memories with `category: "gotcha"` (mirroring the ADR-013
+// line 38 contract). Rules (K###) are NOT migrated — they remain manually
+// maintained in `KNOWLEDGE.md` per ADR-013 line 39.
+//
+// Idempotency is enforced by tagging each backfilled memory with
+// `structured_fields.sourceKnowledgeId = "<P|L>NNN"`. The
+// memory-consolidation-scanner (PR #5765) checks for the same marker.
+//
+// Triggered opportunistically by `buildBeforeAgentStartResult` so the cost
+// only ever fires once per project. Costs O(N) inserts on first run where N
+// is the row count; subsequent runs are an O(N) lookup that finds existing
+// markers and exits.
+
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { createMemory } from "./memory-store.js";
+import { parseKnowledgeRows, readKnowledgeMd, type KnowledgeRow } from "./knowledge-parser.js";
+import { logWarning } from "./workflow-logger.js";
+
+interface SynthesizedRow {
+  table: "patterns" | "lessons";
+  id: string;
+  category: "pattern" | "gotcha";
+  content: string;
+  scope: string;
+  structuredFields: Record<string, unknown>;
+}
+
+/**
+ * Backfill KNOWLEDGE.md Patterns + Lessons rows into the memories table.
+ *
+ * - Idempotent (per-row): each migrated memory carries
+ *   `structured_fields.sourceKnowledgeId = "<P|L>NNN"`. Rows whose ID is
+ *   already present in the memory store are skipped.
+ * - Best-effort: never throws. Logs and returns 0 on failure so a broken
+ *   backfill cannot block agent startup.
+ * - Rules (K###) are intentionally skipped — they remain manually maintained
+ *   in `KNOWLEDGE.md` per ADR-013.
+ *
+ * Returns the number of memories written (0 when there's nothing to migrate
+ * or when the file is absent).
+ */
+export function backfillKnowledgeToMemories(basePath: string): number {
+  if (!isDbAvailable()) return 0;
+  const adapter = _getAdapter();
+  if (!adapter) return 0;
+
+  try {
+    const content = readKnowledgeMd(basePath);
+    if (!content.trim()) return 0;
+
+    const rows = parseKnowledgeRows(content);
+    if (rows.length === 0) return 0;
+
+    const checkExisting = adapter.prepare(
+      "SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1",
+    );
+
+    let written = 0;
+    for (const row of rows) {
+      const synth = synthesize(row);
+      if (!synth) continue;
+
+      // Pattern is anchored on both sides of the value to avoid prefix
+      // collisions (e.g. P1 vs P10).
+      const matchPattern = `%"sourceKnowledgeId":"${synth.id}"%`;
+      if (checkExisting.get({ ":pattern": matchPattern })) continue;
+
+      const id = createMemory({
+        category: synth.category,
+        content: synth.content,
+        scope: synth.scope,
+        confidence: 0.85,
+        structuredFields: synth.structuredFields,
+      });
+      if (id) written += 1;
+    }
+
+    return written;
+  } catch (e) {
+    logWarning(
+      "memory-backfill",
+      `KNOWLEDGE.md -> memories backfill failed: ${(e as Error).message}`,
+    );
+    return 0;
+  }
+}
+
+/**
+ * Convert a parsed KNOWLEDGE.md row into the memory payload we insert.
+ * Returns `null` for Rules (K###) which are not migrated, or for rows whose
+ * primary content cell is empty (defensive against malformed manual edits).
+ */
+function synthesize(row: KnowledgeRow): SynthesizedRow | null {
+  if (row.table === "rules") return null;
+
+  if (row.table === "patterns") {
+    // Cells: [P###, Pattern, Where, Notes]
+    const [, pattern, where, notes] = row.cells;
+    const cleaned = (pattern ?? "").trim();
+    if (!cleaned) return null;
+
+    const contentParts: string[] = [cleaned];
+    if (where && where.trim() && where.trim() !== "—") {
+      contentParts.push(`Where: ${where.trim()}.`);
+    }
+    if (notes && notes.trim() && notes.trim() !== "—") {
+      contentParts.push(`Notes: ${notes.trim()}.`);
+    }
+
+    return {
+      table: "patterns",
+      id: row.id,
+      category: "pattern",
+      content: trim(contentParts.join(" "), 600),
+      scope: (where ?? "").trim() || "project",
+      structuredFields: {
+        sourceKnowledgeId: row.id,
+        sourceKnowledgeTable: "patterns",
+        pattern: cleaned,
+        where: (where ?? "").trim(),
+        notes: (notes ?? "").trim(),
+      },
+    };
+  }
+
+  // table === "lessons"
+  // Cells: [L###, What Happened, Root Cause, Fix, Scope]
+  const [, whatHappened, rootCause, fix, scope] = row.cells;
+  const cleanedWhat = (whatHappened ?? "").trim();
+  if (!cleanedWhat) return null;
+
+  const contentParts: string[] = [cleanedWhat];
+  if (rootCause && rootCause.trim() && rootCause.trim() !== "—") {
+    contentParts.push(`Root cause: ${rootCause.trim()}.`);
+  }
+  if (fix && fix.trim() && fix.trim() !== "—") {
+    contentParts.push(`Fix: ${fix.trim()}.`);
+  }
+
+  return {
+    table: "lessons",
+    id: row.id,
+    category: "gotcha",
+    content: trim(contentParts.join(" "), 600),
+    scope: (scope ?? "").trim() || "project",
+    structuredFields: {
+      sourceKnowledgeId: row.id,
+      sourceKnowledgeTable: "lessons",
+      whatHappened: cleanedWhat,
+      rootCause: (rootCause ?? "").trim(),
+      fix: (fix ?? "").trim(),
+      scopeText: (scope ?? "").trim(),
+    },
+  };
+}
+
+function trim(value: string, max: number): string {
+  const cleaned = value.replace(/\s+/g, " ").trim();
+  return cleaned.length > max ? cleaned.slice(0, max - 1) + "…" : cleaned;
+}