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

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -0,0 +1,222 @@
+// 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";
+// ─── KNOWLEDGE.md parsing ────────────────────────────────────────────────────
+const KNOWLEDGE_SECTIONS = [
+    { table: "rules", heading: "## Rules", idPrefix: "K" },
+    { table: "patterns", heading: "## Patterns", idPrefix: "P" },
+    { table: "lessons", heading: "## Lessons Learned", idPrefix: "L" },
+];
+/**
+ * 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) {
+    const rows = [];
+    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;
+    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) {
+    const path = resolveGsdRootFile(basePath, "KNOWLEDGE");
+    if (!existsSync(path))
+        return "";
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function getActiveDecisions() {
+    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();
+        return rows
+            .map((row) => ({
+            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, value) {
+    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) {
+    // ── Decisions ────────────────────────────────────────────────────────
+    const decisions = getActiveDecisions();
+    const decisionSamples = [];
+    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 = [];
+    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 = {
+        total: decisions.length,
+        migrated: decisionMigrated,
+        unmigrated: decisions.length - decisionMigrated,
+        samples: decisionSamples,
+    };
+    const knowledgeReport = {
+        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 = [];
+    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) {
+    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.message}`);
+        return null;
+    }
+}

package/dist/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/dist/resources/extensions/gsd/provider-switch-observer.js

@@ -0,0 +1,146 @@
+// 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 } from "@gsd/pi-ai";
+import { autoSession } from "./auto-runtime-state.js";
+import { appendNotification } from "./notification-store.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+const INTERACTIVE_TRACE_KEY = "interactive";
+let installed = false;
+let totalSwitches = 0;
+const totals = {
+    thinkingBlocksDropped: 0,
+    thinkingBlocksDowngraded: 0,
+    toolCallIdsRemapped: 0,
+    syntheticToolResultsInserted: 0,
+    thoughtSignaturesDropped: 0,
+};
+const byTrace = new Map();
+let lastReport = null;
+let lastAt = null;
+/** Format a one-line summary suitable for a notification message. */
+function summarize(report) {
+    const parts = [];
+    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) {
+    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) {
+    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) {
+    try {
+        appendNotification(summarize(report), "warning", "workflow-logger");
+    }
+    catch {
+        // Notification persistence is best-effort.
+    }
+}
+function handleReport(report) {
+    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() {
+    if (installed)
+        return;
+    setProviderSwitchObserver(handleReport);
+    installed = true;
+}
+/** Uninstall the observer. Intended for tests. */
+export function uninstallProviderSwitchObserver() {
+    setProviderSwitchObserver(undefined);
+    installed = false;
+}
+/** Read-only snapshot of the in-memory rollup. */
+export function getProviderSwitchStats() {
+    const trace = {};
+    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() {
+    totalSwitches = 0;
+    totals.thinkingBlocksDropped = 0;
+    totals.thinkingBlocksDowngraded = 0;
+    totals.toolCallIdsRemapped = 0;
+    totals.syntheticToolResultsInserted = 0;
+    totals.thoughtSignaturesDropped = 0;
+    byTrace.clear();
+    lastReport = null;
+    lastAt = null;
+}

package/dist/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