gsd-pi 2.82.0 → 3.0.0

package/src/resources/extensions/gsd/guided-unit-context.ts

@@ -0,0 +1,30 @@
+// GSD-2 — Guided workflow Unit context.
+// Tracks the guided Unit whose queued turn should use manifest Tool Contract policy.
+
+export interface GuidedUnitContext {
+  basePath: string;
+  unitType: string;
+  startedAt: number;
+}
+
+const guidedUnitContextByBasePath = new Map<string, GuidedUnitContext>();
+
+export function setGuidedUnitContext(basePath: string, unitType: string): GuidedUnitContext {
+  const context = { basePath, unitType, startedAt: Date.now() };
+  guidedUnitContextByBasePath.set(basePath, context);
+  return context;
+}
+
+export function getGuidedUnitContext(basePath?: string): GuidedUnitContext | null {
+  if (basePath) return guidedUnitContextByBasePath.get(basePath) ?? null;
+  if (guidedUnitContextByBasePath.size === 1) return guidedUnitContextByBasePath.values().next().value!;
+  return null;
+}
+
+export function clearGuidedUnitContext(basePath?: string): void {
+  if (basePath) {
+    guidedUnitContextByBasePath.delete(basePath);
+  } else {
+    guidedUnitContextByBasePath.clear();
+  }
+}

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;
+}

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

@@ -0,0 +1,160 @@
+// GSD2 — KNOWLEDGE.md write-side cutover (ADR-013 Stage 2c).
+//
+// Replaces the legacy `appendKnowledge` file-append path for Patterns and
+// Lessons with `createMemory` calls. Rules (K###) continue to flow through
+// the legacy file-append because they are intentionally not migrated to
+// memories per ADR-013 line 39.
+//
+// Next-ID assignment is the cross-surface stable rule: read the existing
+// `.gsd/KNOWLEDGE.md` for the highest <prefix>### in that section, AND read
+// the memories table for the highest `sourceKnowledgeId` with the matching
+// prefix, take the max, and increment. This stays stable across the
+// knowledge backfill mid-run (when some rows exist only in the file and
+// others only in memories) and on a fresh project where neither has any
+// entries yet.
+
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { createMemory } from "./memory-store.js";
+import { parseKnowledgeRows, readKnowledgeMd } from "./knowledge-parser.js";
+import { logWarning } from "./workflow-logger.js";
+
+export type PatternLessonType = "pattern" | "lesson";
+
+export interface CaptureKnowledgeResult {
+  /** The assigned <prefix>### identifier (e.g. "P004"). */
+  id: string;
+  /** Whether the memory row was actually written. False only when the
+   *  DB is unavailable or the createMemory call returned undefined. */
+  written: boolean;
+}
+
+/**
+ * Append a new Pattern or Lesson by writing it as a memory row carrying a
+ * `sourceKnowledgeId` marker. The next session's KNOWLEDGE.md projection
+ * render (`knowledge-projection.ts`) picks it up and emits the row into the
+ * appropriate section.
+ *
+ * `entryText` is treated as the row's primary description cell (Pattern for
+ * patterns, "What Happened" for lessons). Auxiliary cells (Where/Notes for
+ * patterns; Root Cause/Fix/Scope for lessons) are left empty — the projection
+ * renders `—` for empty cells. Users who need richer structure can call
+ * `capture_thought` directly with a fuller `structuredFields` payload.
+ */
+export function captureKnowledgeEntry(
+  basePath: string,
+  type: PatternLessonType,
+  entryText: string,
+  scope: string,
+): CaptureKnowledgeResult {
+  const cleaned = entryText.trim();
+  const idPrefix = type === "pattern" ? "P" : "L";
+  const id = nextKnowledgeId(basePath, idPrefix);
+
+  if (!cleaned) {
+    return { id, written: false };
+  }
+
+  if (!isDbAvailable()) {
+    logWarning("knowledge-capture", "DB unavailable; cannot persist knowledge entry");
+    return { id, written: false };
+  }
+
+  try {
+    const category = type === "pattern" ? "pattern" : "gotcha";
+    const structuredFields: Record<string, unknown> =
+      type === "pattern"
+        ? {
+            sourceKnowledgeId: id,
+            sourceKnowledgeTable: "patterns",
+            pattern: cleaned,
+            where: "",
+            notes: "",
+          }
+        : {
+            sourceKnowledgeId: id,
+            sourceKnowledgeTable: "lessons",
+            whatHappened: cleaned,
+            rootCause: "",
+            fix: "",
+            scopeText: scope,
+          };
+
+    const memoryId = createMemory({
+      category,
+      content: cleaned,
+      scope: scope || "project",
+      confidence: 0.85,
+      structuredFields,
+    });
+
+    return { id, written: !!memoryId };
+  } catch (e) {
+    logWarning(
+      "knowledge-capture",
+      `failed to persist ${type} entry as memory: ${(e as Error).message}`,
+    );
+    return { id, written: false };
+  }
+}
+
+/**
+ * Compute the next <prefix>### identifier across both the legacy
+ * `.gsd/KNOWLEDGE.md` and the `memories.structured_fields.sourceKnowledgeId`
+ * surface. Takes the max numeric suffix from either side and increments.
+ *
+ * Padded to three digits to match the existing `appendKnowledge` convention.
+ * Exported for tests; production callers go through `captureKnowledgeEntry`.
+ */
+export function nextKnowledgeId(basePath: string, prefix: "K" | "P" | "L"): string {
+  const fromFile = maxIdInFile(basePath, prefix);
+  const fromMemories = maxIdInMemories(prefix);
+  const next = Math.max(fromFile, fromMemories) + 1;
+  return `${prefix}${String(next).padStart(3, "0")}`;
+}
+
+function maxIdInFile(basePath: string, prefix: "K" | "P" | "L"): number {
+  const content = readKnowledgeMd(basePath);
+  if (!content.trim()) return 0;
+  const expectedTable =
+    prefix === "K" ? "rules" : prefix === "P" ? "patterns" : "lessons";
+
+  let max = 0;
+  for (const row of parseKnowledgeRows(content)) {
+    if (row.table !== expectedTable) continue;
+    const num = parseInt(row.id.slice(1), 10);
+    if (Number.isFinite(num) && num > max) max = num;
+  }
+  return max;
+}
+
+function maxIdInMemories(prefix: "K" | "P" | "L"): number {
+  if (!isDbAvailable()) return 0;
+  const adapter = _getAdapter();
+  if (!adapter) return 0;
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT structured_fields FROM memories WHERE structured_fields LIKE :pattern",
+      )
+      .all({ ":pattern": `%"sourceKnowledgeId":"${prefix}%` }) as Array<{
+      structured_fields: string | null;
+    }>;
+    let max = 0;
+    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["sourceKnowledgeId"];
+      if (typeof sourceId !== "string" || !sourceId.startsWith(prefix)) continue;
+      const num = parseInt(sourceId.slice(1), 10);
+      if (Number.isFinite(num) && num > max) max = num;
+    }
+    return max;
+  } catch {
+    return 0;
+  }
+}

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

@@ -0,0 +1,174 @@
+// GSD-2 — KNOWLEDGE.md parsing helpers shared by the consolidation scanner,
+// the Patterns/Lessons backfill, and the hybrid projection renderer
+// (ADR-013 Stage 2a/2b).
+//
+// The KNOWLEDGE.md format is locked in `files.ts:appendKnowledge`:
+//
+//   # Project Knowledge
+//
+//   <optional intro prose>
+//
+//   ## Rules
+//
+//   | # | Scope | Rule | Why | Added |
+//   |---|-------|------|-----|-------|
+//   | K001 | project | <rule text> | <reason> | <date> |
+//
+//   ## Patterns
+//
+//   | # | Pattern | Where | Notes |
+//   |---|---------|-------|-------|
+//   | P001 | <pattern> | <location> | <notes> |
+//
+//   ## Lessons Learned
+//
+//   | # | What Happened | Root Cause | Fix | Scope |
+//   |---|--------------|------------|-----|-------|
+//   | L001 | <what> | <cause> | <fix> | <scope> |
+//
+// Row IDs use a strict <prefix><digits> format (K001, P001, L001 …). Parsers
+// skip the column-title and separator rows; only rows whose first cell
+// matches the expected prefix are emitted.
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { resolveGsdRootFile } from "./paths.js";
+
+export type KnowledgeTable = "rules" | "patterns" | "lessons";
+
+export interface KnowledgeRow {
+  table: KnowledgeTable;
+  id: string;
+  /** Full table row, trimmed. Useful as a sample for diagnostic surfaces. */
+  raw: string;
+  /** Pipe-split cell values (excluding the leading/trailing empty cells from `| ... |`). */
+  cells: string[];
+}
+
+export const KNOWLEDGE_SECTIONS: ReadonlyArray<{
+  table: KnowledgeTable;
+  heading: string;
+  idPrefix: string;
+}> = [
+  { table: "rules", heading: "## Rules", idPrefix: "K" },
+  { table: "patterns", heading: "## Patterns", idPrefix: "P" },
+  { table: "lessons", heading: "## Lessons Learned", idPrefix: "L" },
+];
+
+/** Read `.gsd/KNOWLEDGE.md` content if present. Returns "" when absent or unreadable. */
+export function readKnowledgeMd(basePath: string): string {
+  const path = resolveGsdRootFile(basePath, "KNOWLEDGE");
+  if (!existsSync(path)) return "";
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/** Resolve the canonical `.gsd/KNOWLEDGE.md` path. */
+export function knowledgeMdPath(basePath: string): string {
+  return resolveGsdRootFile(basePath, "KNOWLEDGE");
+}
+
+/**
+ * Parse KNOWLEDGE.md into row records. Skips intro prose, table headers,
+ * separator lines, and rows from unrecognized sections. Each row's first
+ * cell must match the section's expected prefix (K/P/L + digits).
+ */
+export function parseKnowledgeRows(content: string): KnowledgeRow[] {
+  const rows: KnowledgeRow[] = [];
+  if (!content.trim()) return rows;
+
+  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;
+
+    const idMatch = new RegExp(`^\\|\\s*(${activeSection.idPrefix}\\d+)\\s*\\|`).exec(trimmed);
+    if (!idMatch) continue;
+
+    rows.push({
+      table: activeSection.table,
+      id: idMatch[1] ?? "",
+      raw: trimmed,
+      cells: splitPipeRow(trimmed),
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Slice the KNOWLEDGE.md content to just the intro prose plus the `## Rules`
+ * section, dropping `## Patterns` and `## Lessons Learned`. Used by
+ * `loadKnowledgeBlock` to avoid double-injecting Patterns and Lessons —
+ * those reach the LLM via `loadMemoryBlock` after the ADR-013 Stage 2b
+ * cutover, so re-emitting them through the KNOWLEDGE.md block is pure
+ * token-cost overhead.
+ *
+ * Returns the full content unchanged when no `## Rules` heading exists
+ * (legacy projects or unusual layouts — better to over-inject than drop
+ * unfamiliar content silently).
+ */
+export function extractIntroAndRules(content: string): string {
+  if (!content.trim()) return "";
+  const lines = content.split("\n");
+  const rulesIdx = lines.findIndex((l) => l.trim() === "## Rules");
+  if (rulesIdx === -1) return content;
+
+  // End of the Rules section is the next `## ` heading (Patterns or
+  // Lessons Learned) or end-of-file. Drop trailing blank lines so the
+  // caller can join the slice without producing a triple newline.
+  let endIdx = lines.length;
+  for (let i = rulesIdx + 1; i < lines.length; i++) {
+    if (lines[i]!.startsWith("## ")) {
+      endIdx = i;
+      break;
+    }
+  }
+  const slice = lines.slice(0, endIdx);
+  while (slice.length > 0 && slice[slice.length - 1]!.trim() === "") {
+    slice.pop();
+  }
+  return slice.join("\n") + "\n";
+}
+
+/**
+ * Split a Markdown table row on un-escaped pipes. Returns the cell values
+ * (without the leading/trailing empty fragments from `| ... |`), each
+ * trimmed. Escaped pipes (`\|`) inside a cell are preserved as `|` in the
+ * output.
+ */
+export function splitPipeRow(row: string): string[] {
+  const cells: string[] = [];
+  let current = "";
+  for (let i = 0; i < row.length; i++) {
+    const ch = row[i];
+    if (ch === "\\" && row[i + 1] === "|") {
+      current += "|";
+      i += 1;
+      continue;
+    }
+    if (ch === "|") {
+      cells.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim().length > 0) {
+    cells.push(current.trim());
+  }
+  // Drop the leading empty fragment from `|<cell>|...|` — the first split
+  // produces an empty string before the first pipe.
+  if (cells.length > 0 && cells[0] === "") cells.shift();
+  return cells;
+}