gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.725028083

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

@@ -1,9 +1,10 @@
 // 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).
+// Idempotent migration that copies every decisions row (active and
+// superseded — see Stage 2a note below) 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, superseded_by, sourceDecisionId).
 //
 // The backfill exists so the cutover in ADR-013 step 6 can drop the
 // decisions table without losing schema fidelity. Idempotency is enforced
@@ -14,6 +15,13 @@
 // 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.
+//
+// ADR-013 Stage 2a (PR #5755): backfill now includes superseded rows so the
+// DECISIONS.md projection regen can source from memories without losing
+// historical entries. An auto-heal pass runs after the initial migration to
+// pick up superseded_by changes that occurred after the source decision was
+// already migrated (e.g. a fresh md-importer run that introduced a new
+// supersedes-chain).
 
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
 import { createMemory } from "./memory-store.js";
@@ -31,8 +39,10 @@ interface DecisionRow {
   superseded_by: string | null;
 }
 
+type DecisionContentFields = Pick<DecisionRow, "decision" | "choice" | "rationale">;
+
 /**
- * Backfill active decisions rows into the memories table.
+ * Backfill decisions rows into the memories table.
  *
  * - Idempotent (per-row): every row written carries
  *   `structured_fields.sourceDecisionId = "<decisionId>"`. Each candidate
@@ -41,13 +51,18 @@ interface DecisionRow {
  *   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.
+ * - Full migration (ADR-013 Stage 2a): both active and superseded rows are
+ *   migrated. `structured_fields.superseded_by` preserves the supersedes
+ *   chain so the DECISIONS.md projection regen can source from memories
+ *   without losing historical entries.
+ * - Drift auto-heal: after the initial insert pass, the function updates
+ *   any pre-existing memory whose `structured_fields.superseded_by` drifted
+ *   from the source decision (e.g. a fresh md-importer run introduced a
+ *   new supersedes annotation after the initial migration).
  *
  * 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.
+ * when the DB has no decisions). Drift-heal updates are not counted in
+ * this return — they are logged separately.
  */
 export function backfillDecisionsToMemories(): number {
   if (!isDbAvailable()) return 0;
@@ -56,7 +71,7 @@ export function backfillDecisionsToMemories(): number {
 
   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")
+      .prepare("SELECT id, when_context, scope, decision, choice, rationale, made_by, revisable, superseded_by FROM decisions ORDER BY seq")
       .all() as Array<Record<string, unknown>>;
 
     if (decisions.length === 0) return 0;
@@ -67,10 +82,14 @@ export function backfillDecisionsToMemories(): number {
     // 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",
+      "SELECT id, structured_fields FROM memories WHERE structured_fields LIKE :pattern LIMIT 1",
+    );
+    const updateStructuredFields = adapter.prepare(
+      "UPDATE memories SET structured_fields = :sf, updated_at = :ts WHERE id = :id",
     );
 
     let written = 0;
+    let healed = 0;
     for (const raw of decisions) {
       const row: DecisionRow = {
         id: String(raw["id"] ?? ""),
@@ -85,11 +104,48 @@ export function backfillDecisionsToMemories(): number {
       };
       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 pattern = `%"sourceDecisionId":"${row.id}"%`;
+      const existing = checkExisting.get({ ":pattern": pattern }) as
+        | { id: string; structured_fields: string | null }
+        | undefined;
 
-      const content = synthesizeContent(row);
+      if (existing) {
+        // Drift auto-heal: if the source decision's superseded_by has changed
+        // since the original migration, update the memory in place. Read-side
+        // queries reconstruct Decision.superseded_by from this field, so the
+        // DECISIONS.md projection stays accurate without us having to track
+        // supersedes events at the write site.
+        const parsedSf = existing.structured_fields
+          ? safeParse(existing.structured_fields)
+          : {};
+        if (existing.structured_fields && !parsedSf) {
+          logWarning(
+            "memory-backfill",
+            `decisions->memories drift heal skipped for ${row.id}: invalid structured_fields JSON`,
+          );
+          continue;
+        }
+        const currentSf = parsedSf ?? {};
+        const memorySuperseded =
+          typeof currentSf["superseded_by"] === "string" || currentSf["superseded_by"] === null
+            ? (currentSf["superseded_by"] as string | null | undefined)
+            : null;
+        if (memorySuperseded !== row.superseded_by) {
+          const merged = {
+            ...currentSf,
+            superseded_by: row.superseded_by,
+          };
+          updateStructuredFields.run({
+            ":id": existing.id,
+            ":sf": JSON.stringify(merged),
+            ":ts": new Date().toISOString(),
+          });
+          healed += 1;
+        }
+        continue;
+      }
+
+      const content = synthesizeDecisionMemoryContent(row);
       const id = createMemory({
         category: "architecture",
         content,
@@ -104,11 +160,19 @@ export function backfillDecisionsToMemories(): number {
           rationale: row.rationale,
           made_by: row.made_by,
           revisable: row.revisable,
+          superseded_by: row.superseded_by,
         },
       });
       if (id) written += 1;
     }
 
+    if (healed > 0) {
+      logWarning(
+        "memory-backfill",
+        `decisions->memories drift healed: ${healed} row${healed === 1 ? "" : "s"} updated superseded_by`,
+      );
+    }
+
     return written;
   } catch (e) {
     logWarning("memory-backfill", `decisions->memories backfill failed: ${(e as Error).message}`);
@@ -116,6 +180,14 @@ export function backfillDecisionsToMemories(): number {
   }
 }
 
+function safeParse(raw: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Combine the decision's structured fields into a 1-3 sentence content
  * string suitable for keyword retrieval and human review.
@@ -124,7 +196,7 @@ export function backfillDecisionsToMemories(): number {
  * Truncates each field to keep the synthesized line under ~600 chars so
  * memory_query rendering stays readable.
  */
-function synthesizeContent(row: DecisionRow): string {
+export function synthesizeDecisionMemoryContent(row: DecisionContentFields): 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;

package/src/resources/extensions/gsd/memory-consolidation-scanner.ts

@@ -0,0 +1,277 @@
+// GSD-2 — ADR-013 Phase 6 preflight scanner.
+//
+// Read-only detection of rows in the legacy knowledge surfaces (decisions
+// table, `.gsd/KNOWLEDGE.md`) that lack a corresponding `memories` row.
+// Runs on session start (and on demand via doctor); never mutates state.
+//
+// The scanner exists so the destructive Phase 6 cutover (#5755) can prove
+// the migration is complete before any tables are dropped. Today's
+// `backfillDecisionsToMemories` writes a `structured_fields.sourceDecisionId`
+// marker on each migrated row; the scanner uses that marker for decisions
+// detection. A `sourceKnowledgeId` marker is reserved for the parallel
+// KNOWLEDGE.md backfill that Phase 6 will introduce — until that ships,
+// every KNOWLEDGE.md row is reported as unmigrated, which is the honest
+// state of the consolidation.
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { appendNotification } from "./notification-store.js";
+import { resolveGsdRootFile } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface KnowledgeSurfaceReport {
+  total: number;
+  migrated: number;
+  unmigrated: number;
+  byTable: { rules: number; patterns: number; lessons: number };
+  /** Up to 5 sample row IDs/content for diagnosing what's unmigrated. */
+  samples: Array<{ table: "rules" | "patterns" | "lessons"; id: string; row: string }>;
+}
+
+export interface DecisionsSurfaceReport {
+  total: number;
+  migrated: number;
+  unmigrated: number;
+  /** Up to 5 sample decision IDs with a short content excerpt. */
+  samples: Array<{ id: string; decision: string }>;
+}
+
+export interface ConsolidationGapReport {
+  decisions: DecisionsSurfaceReport;
+  knowledge: KnowledgeSurfaceReport;
+  /** Sum of unmigrated rows across both surfaces. Zero ⇒ clean preflight. */
+  totalGaps: number;
+  /** Human-readable single-line summary suitable for notifications + logs. */
+  summary: string;
+}
+
+// ─── KNOWLEDGE.md parsing ────────────────────────────────────────────────────
+
+const KNOWLEDGE_SECTIONS = [
+  { table: "rules" as const, heading: "## Rules", idPrefix: "K" },
+  { table: "patterns" as const, heading: "## Patterns", idPrefix: "P" },
+  { table: "lessons" as const, heading: "## Lessons Learned", idPrefix: "L" },
+];
+
+interface KnowledgeRow {
+  table: "rules" | "patterns" | "lessons";
+  id: string;
+  row: string;
+}
+
+/**
+ * Parse `.gsd/KNOWLEDGE.md` into rows, one per table entry. Skips the table
+ * header and separator lines; ignores rows from unrecognized sections.
+ *
+ * The format is locked in `files.ts:appendKnowledge` — three `## ` sections
+ * (Rules, Patterns, Lessons Learned), each a Markdown table. Row IDs are
+ * `K###` / `P###` / `L###`.
+ */
+export function parseKnowledgeRows(content: string): KnowledgeRow[] {
+  const rows: KnowledgeRow[] = [];
+  if (!content.trim()) return rows;
+
+  // Slice the content into sections by heading. The leading text before the
+  // first ## heading is intro prose — ignored.
+  const lines = content.split("\n");
+  let activeSection: typeof KNOWLEDGE_SECTIONS[number] | undefined;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("## ")) {
+      activeSection = KNOWLEDGE_SECTIONS.find((s) => s.heading === trimmed);
+      continue;
+    }
+    if (!activeSection) continue;
+    if (!trimmed.startsWith("|")) continue;
+
+    // Skip the table header rows: the column-titles line and the |---|---| separator.
+    // Real data rows start with `| <prefix>### |`.
+    const idMatch = new RegExp(`^\\|\\s*(${activeSection.idPrefix}\\d+)\\s*\\|`).exec(trimmed);
+    if (!idMatch) continue;
+
+    rows.push({
+      table: activeSection.table,
+      id: idMatch[1] ?? "",
+      row: trimmed,
+    });
+  }
+
+  return rows;
+}
+
+function knowledgeMdContent(basePath: string): string {
+  const path = resolveGsdRootFile(basePath, "KNOWLEDGE");
+  if (!existsSync(path)) return "";
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+// ─── DB queries ──────────────────────────────────────────────────────────────
+
+interface DecisionRow {
+  id: string;
+  decision: string;
+}
+
+function getActiveDecisions(): DecisionRow[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT id, decision FROM decisions WHERE superseded_by IS NULL",
+      )
+      .all() as Array<Record<string, unknown>>;
+    return rows
+      .map((row): DecisionRow => ({
+        id: String(row["id"] ?? ""),
+        decision: String(row["decision"] ?? ""),
+      }))
+      .filter((row) => row.id.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * True when a memory row has a `structured_fields` JSON payload containing
+ * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
+ * `backfillDecisionsToMemories` so the scanner is consistent with the
+ * backfill's idempotency check.
+ */
+function memoryHasSourceMarker(markerKey: string, value: string): boolean {
+  if (!isDbAvailable()) return false;
+  const adapter = _getAdapter();
+  if (!adapter) return false;
+  try {
+    const pattern = `%"${markerKey}":"${value}"%`;
+    const row = adapter
+      .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
+      .get({ ":pattern": pattern });
+    return row !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+const SAMPLE_LIMIT = 5;
+
+/**
+ * Scan the legacy knowledge surfaces and return a structured report of what's
+ * already in the `memories` table vs what's still unmigrated. Pure detection
+ * — no DB writes, no file writes, no notifications.
+ */
+export function scanConsolidationGaps(basePath: string): ConsolidationGapReport {
+  // ── Decisions ────────────────────────────────────────────────────────
+  const decisions = getActiveDecisions();
+  const decisionSamples: DecisionsSurfaceReport["samples"] = [];
+  let decisionMigrated = 0;
+  for (const decision of decisions) {
+    if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+      decisionMigrated += 1;
+      continue;
+    }
+    if (decisionSamples.length < SAMPLE_LIMIT) {
+      decisionSamples.push({
+        id: decision.id,
+        decision: decision.decision.length > 80 ? decision.decision.slice(0, 79) + "…" : decision.decision,
+      });
+    }
+  }
+
+  // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
+  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+  const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
+  const knowledgeSamples: KnowledgeSurfaceReport["samples"] = [];
+  let knowledgeMigrated = 0;
+  for (const row of knowledgeRows) {
+    knowledgeByTable[row.table] += 1;
+    // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
+    // KNOWLEDGE.md backfill. Until that path ships, this check returns
+    // false for every row, which is the honest state of the consolidation.
+    if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+      knowledgeMigrated += 1;
+      continue;
+    }
+    if (knowledgeSamples.length < SAMPLE_LIMIT) {
+      knowledgeSamples.push({
+        table: row.table,
+        id: row.id,
+        row: row.row.length > 100 ? row.row.slice(0, 99) + "…" : row.row,
+      });
+    }
+  }
+
+  const decisionsReport: DecisionsSurfaceReport = {
+    total: decisions.length,
+    migrated: decisionMigrated,
+    unmigrated: decisions.length - decisionMigrated,
+    samples: decisionSamples,
+  };
+  const knowledgeReport: KnowledgeSurfaceReport = {
+    total: knowledgeRows.length,
+    migrated: knowledgeMigrated,
+    unmigrated: knowledgeRows.length - knowledgeMigrated,
+    byTable: knowledgeByTable,
+    samples: knowledgeSamples,
+  };
+
+  const totalGaps = decisionsReport.unmigrated + knowledgeReport.unmigrated;
+
+  // Summary line is intentionally short so it fits in a single notification
+  // (notification-store truncates messages over 500 chars). Detail is
+  // accessible via getProviderSwitchStats-style callers, not embedded here.
+  const parts: string[] = [];
+  if (decisionsReport.unmigrated > 0) {
+    parts.push(`${decisionsReport.unmigrated} of ${decisionsReport.total} active decisions`);
+  }
+  if (knowledgeReport.unmigrated > 0) {
+    parts.push(`${knowledgeReport.unmigrated} of ${knowledgeReport.total} KNOWLEDGE.md rows`);
+  }
+  const summary =
+    parts.length === 0
+      ? "Memory consolidation: all decisions and KNOWLEDGE.md rows are in memories."
+      : `Memory consolidation: ${parts.join(" and ")} not yet in memories table. Run /doctor for details.`;
+
+  return { decisions: decisionsReport, knowledge: knowledgeReport, totalGaps, summary };
+}
+
+/**
+ * Run the scanner and emit a persistent notification + workflow-logger
+ * warning when gaps exist. Best-effort: never throws; a broken scanner
+ * cannot block agent startup.
+ *
+ * Returns the full {@link ConsolidationGapReport} regardless of whether gaps
+ * exist (including when `totalGaps === 0`). Returns `null` only when
+ * `scanConsolidationGaps` itself throws. `appendNotification` and
+ * `logWarning` are called only when `report.totalGaps > 0`.
+ *
+ * Idempotent at the surface: the notification store applies its own
+ * 30-second dedup window keyed on (severity, source, message), so repeated
+ * boots with identical gaps produce one notification, not a flood.
+ */
+export function reportConsolidationGaps(basePath: string): ConsolidationGapReport | null {
+  try {
+    const report = scanConsolidationGaps(basePath);
+    if (report.totalGaps === 0) return report;
+    appendNotification(report.summary, "warning", "workflow-logger");
+    logWarning("memory-consolidation", report.summary);
+    return report;
+  } catch (e) {
+    logWarning(
+      "memory-consolidation",
+      `scanner failed: ${(e as Error).message}`,
+    );
+    return null;
+  }
+}

package/src/resources/extensions/gsd/prompts/system.md

@@ -27,7 +27,7 @@ GSD ships with bundled skills. When the task matches, load the relevant skill fi
 
 - Never ask the user to do work the agent can execute or verify itself.
 - Use the lightest sufficient tool first.
-- Read before edit.
+- Read before edit or overwrite. Before any write that creates or replaces a file, verify the target path and read relevant existing files, templates, callers, or surrounding code. For truly new files, confirm the path does not already exist.
 - Reproduce before fix when possible.
 - Work is not done until the relevant verification has passed.
 - **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar; never emit `<user_message>`, `<assistant_message>`, or similar as user input. Treat `<conversation_history>` as read-only context. Ask one question round (1-3 questions), then stop and wait for the user's actual response. If `ask_user_questions` is available, its result is the only valid structured user input for that round. If it cancels, fails, or returns nothing, never use earlier chat as confirmation for the current gate; ask in plain chat and stop.
@@ -102,7 +102,7 @@ Templates are in `{{templatesDir}}`.
 
 **File reading:** Use `read` for file inspection. Never use `cat`, `head`, `tail`, or `sed -n` to view contents. Use `read` with `offset`/`limit` for slicing. `bash` is for searching (`rg`, `grep`, `find`) and commands, not displaying files.
 
-**File editing:** Always `read` before `edit`; exact text match is required. Use `write` only for new files or complete rewrites.
+**File editing:** Always `read` before `edit` or overwrite. Before `write`, confirm whether the path exists; if it does, `read` it first and preserve intentional existing content. Use `write` only for new files or complete rewrites.
 
 **Code navigation:** Use `lsp` for definition, type_definition, implementation, references, calls, hover, signature, symbols, rename, code_actions, format, and diagnostics. Do not `grep` symbol definitions or shell out to formatters when `lsp` can do it. After code edits, run `lsp diagnostics`.
 

package/src/resources/extensions/gsd/provider-switch-observer.ts

@@ -0,0 +1,185 @@
+// GSD-2 — ADR-005 Phase 3b: surface ProviderSwitchReport from pi-ai.
+//
+// pi-ai builds a ProviderSwitchReport on every cross-provider transform but
+// only logs it to stderr when GSD_VERBOSE=1. This module installs a
+// single-subscriber observer that surfaces non-empty reports through GSD's
+// three usual telemetry surfaces:
+//
+//   1. UOK audit event (category model-policy, type provider-switch) — only
+//      when an auto trace is active.
+//   2. Persistent notification (.gsd/notifications.jsonl, severity warning) —
+//      whenever the GSD basePath is known, so users see the loss in the
+//      dashboard / status surface without GSD_VERBOSE.
+//   3. In-memory counter, exposed via getProviderSwitchStats() so any
+//      caller (dashboard, doctor, tests) can read the rollup.
+
+import { setProviderSwitchObserver, type ProviderSwitchReport } from "@gsd/pi-ai";
+
+import { autoSession } from "./auto-runtime-state.js";
+import { appendNotification } from "./notification-store.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+
+/** Rollup of cross-provider context transformations, grouped by trace. */
+export interface ProviderSwitchStats {
+  /** Total non-empty reports observed since process start (or last reset). */
+  totalSwitches: number;
+  /** Sum of every counted transformation across all reports. */
+  totals: {
+    thinkingBlocksDropped: number;
+    thinkingBlocksDowngraded: number;
+    toolCallIdsRemapped: number;
+    syntheticToolResultsInserted: number;
+    thoughtSignaturesDropped: number;
+  };
+  /** Per-trace breakdown. Key "interactive" covers reports outside auto-mode. */
+  byTrace: Record<string, TraceSwitchStats>;
+  /** The most recent non-empty report, if any. */
+  lastReport: ProviderSwitchReport | null;
+  /** ISO timestamp of the most recent non-empty report, if any. */
+  lastAt: string | null;
+}
+
+export interface TraceSwitchStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+const INTERACTIVE_TRACE_KEY = "interactive";
+
+interface MutableTraceStats {
+  switches: number;
+  lastReport: ProviderSwitchReport;
+  lastAt: string;
+}
+
+let installed = false;
+let totalSwitches = 0;
+const totals = {
+  thinkingBlocksDropped: 0,
+  thinkingBlocksDowngraded: 0,
+  toolCallIdsRemapped: 0,
+  syntheticToolResultsInserted: 0,
+  thoughtSignaturesDropped: 0,
+};
+const byTrace = new Map<string, MutableTraceStats>();
+let lastReport: ProviderSwitchReport | null = null;
+let lastAt: string | null = null;
+
+/** Format a one-line summary suitable for a notification message. */
+function summarize(report: ProviderSwitchReport): string {
+  const parts: string[] = [];
+  if (report.thinkingBlocksDropped > 0) parts.push(`${report.thinkingBlocksDropped} thinking dropped`);
+  if (report.thinkingBlocksDowngraded > 0) parts.push(`${report.thinkingBlocksDowngraded} thinking downgraded`);
+  if (report.toolCallIdsRemapped > 0) parts.push(`${report.toolCallIdsRemapped} tool ids remapped`);
+  if (report.syntheticToolResultsInserted > 0) parts.push(`${report.syntheticToolResultsInserted} synthetic tool results`);
+  if (report.thoughtSignaturesDropped > 0) parts.push(`${report.thoughtSignaturesDropped} thought signatures dropped`);
+  return `Provider switch ${report.fromApi} → ${report.toApi}: ${parts.join(", ")}`;
+}
+
+function recordReport(report: ProviderSwitchReport): void {
+  const now = new Date().toISOString();
+  totalSwitches += 1;
+  totals.thinkingBlocksDropped += report.thinkingBlocksDropped;
+  totals.thinkingBlocksDowngraded += report.thinkingBlocksDowngraded;
+  totals.toolCallIdsRemapped += report.toolCallIdsRemapped;
+  totals.syntheticToolResultsInserted += report.syntheticToolResultsInserted;
+  totals.thoughtSignaturesDropped += report.thoughtSignaturesDropped;
+  lastReport = report;
+  lastAt = now;
+
+  const traceKey = autoSession.currentTraceId ?? INTERACTIVE_TRACE_KEY;
+  const existing = byTrace.get(traceKey);
+  if (existing) {
+    existing.switches += 1;
+    existing.lastReport = report;
+    existing.lastAt = now;
+  } else {
+    byTrace.set(traceKey, { switches: 1, lastReport: report, lastAt: now });
+  }
+}
+
+function emitAudit(report: ProviderSwitchReport): void {
+  const traceId = autoSession.currentTraceId;
+  const basePath = autoSession.basePath;
+  if (!traceId || !basePath) return;
+  try {
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId,
+        category: "model-policy",
+        type: "provider-switch",
+        payload: {
+          fromApi: report.fromApi,
+          toApi: report.toApi,
+          thinkingBlocksDropped: report.thinkingBlocksDropped,
+          thinkingBlocksDowngraded: report.thinkingBlocksDowngraded,
+          toolCallIdsRemapped: report.toolCallIdsRemapped,
+          syntheticToolResultsInserted: report.syntheticToolResultsInserted,
+          thoughtSignaturesDropped: report.thoughtSignaturesDropped,
+        },
+      }),
+    );
+  } catch {
+    // Audit emission is best-effort. Counter + notification still fire.
+  }
+}
+
+function emitNotification(report: ProviderSwitchReport): void {
+  try {
+    appendNotification(summarize(report), "warning", "workflow-logger");
+  } catch {
+    // Notification persistence is best-effort.
+  }
+}
+
+function handleReport(report: ProviderSwitchReport): void {
+  recordReport(report);
+  emitAudit(report);
+  emitNotification(report);
+}
+
+/**
+ * Install the pi-ai observer. Idempotent — calling more than once is a no-op
+ * after the first install.
+ */
+export function installProviderSwitchObserver(): void {
+  if (installed) return;
+  setProviderSwitchObserver(handleReport);
+  installed = true;
+}
+
+/** Uninstall the observer. Intended for tests. */
+export function uninstallProviderSwitchObserver(): void {
+  setProviderSwitchObserver(undefined);
+  installed = false;
+}
+
+/** Read-only snapshot of the in-memory rollup. */
+export function getProviderSwitchStats(): ProviderSwitchStats {
+  const trace: Record<string, TraceSwitchStats> = {};
+  for (const [key, value] of byTrace) {
+    trace[key] = { switches: value.switches, lastReport: { ...value.lastReport }, lastAt: value.lastAt };
+  }
+  return {
+    totalSwitches,
+    totals: { ...totals },
+    byTrace: trace,
+    lastReport: lastReport ? { ...lastReport } : null,
+    lastAt,
+  };
+}
+
+/** Reset the in-memory rollup. Intended for tests. */
+export function _resetProviderSwitchStats(): void {
+  totalSwitches = 0;
+  totals.thinkingBlocksDropped = 0;
+  totals.thinkingBlocksDowngraded = 0;
+  totals.toolCallIdsRemapped = 0;
+  totals.syntheticToolResultsInserted = 0;
+  totals.thoughtSignaturesDropped = 0;
+  byTrace.clear();
+  lastReport = null;
+  lastAt = null;
+}

package/src/resources/extensions/gsd/templates/knowledge.md

@@ -1,7 +1,7 @@
 # Project Knowledge
 
-Append-only register of project-specific rules, patterns, and lessons learned.
-Agents read this before every unit. Add entries when you discover something worth remembering.
+Project-specific rules plus projected patterns and lessons learned.
+Rules are maintained in this file. Patterns and lessons are persisted to the memories table and rendered here on the next session-start projection.
 
 ## Rules