gsd-pi 2.82.0 → 3.0.0

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

@@ -0,0 +1,241 @@
+// GSD2 — KNOWLEDGE.md hybrid projection renderer (ADR-013 Stage 2b).
+//
+// Renders `.gsd/KNOWLEDGE.md` as a hybrid file:
+//   - Rules section: read directly from the existing KNOWLEDGE.md (manual,
+//     per ADR-013 line 39 — Rules are not migrated to memories).
+//   - Patterns section: read from `memories` where `category = "pattern"`
+//     AND `structured_fields.sourceKnowledgeId` is set (matches the marker
+//     written by knowledge-backfill.ts).
+//   - Lessons Learned section: read from `memories` where
+//     `category = "gotcha"` AND `structured_fields.sourceKnowledgeId` is set.
+//
+// Triggered opportunistically by `buildBeforeAgentStartResult` after the
+// knowledge backfill runs. Output is byte-stable when nothing has changed
+// (atomic write). The Rules section is preserved verbatim — including
+// indentation, trailing whitespace, and comments — so manual edits to that
+// section continue to round-trip through `/gsd knowledge`.
+//
+// Memories captured directly via `capture_thought` (without a
+// `sourceKnowledgeId` marker) are intentionally NOT rendered into
+// KNOWLEDGE.md. They remain accessible via the loadMemoryBlock auto-injection
+// surface; KNOWLEDGE.md projects only the KNOWLEDGE.md-originating subset.
+
+import { atomicWriteSync } from "./atomic-write.js";
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import {
+  KNOWLEDGE_SECTIONS,
+  knowledgeMdPath,
+  readKnowledgeMd,
+} from "./knowledge-parser.js";
+import { logWarning } from "./workflow-logger.js";
+
+const RULES_HEADING = "## Rules";
+const PATTERNS_HEADING = "## Patterns";
+const LESSONS_HEADING = "## Lessons Learned";
+
+const PATTERNS_HEADER = "| # | Pattern | Where | Notes |";
+const PATTERNS_SEPARATOR = "|---|---------|-------|-------|";
+
+const LESSONS_HEADER = "| # | What Happened | Root Cause | Fix | Scope |";
+const LESSONS_SEPARATOR = "|---|--------------|------------|-----|-------|";
+
+const DEFAULT_INTRO = [
+  "# 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.",
+  "",
+].join("\n");
+
+interface KnowledgeMemoryRow {
+  sourceId: string;
+  structured: Record<string, unknown>;
+}
+
+interface KnowledgeMemoryReadResult {
+  ok: boolean;
+  rows: KnowledgeMemoryRow[];
+}
+
+export interface KnowledgeProjectionResult {
+  written: boolean;
+  content: string;
+}
+
+/**
+ * Read pattern memories that originated from KNOWLEDGE.md, ordered by
+ * `sourceKnowledgeId` (lexicographic — P001 < P002 < P010). Memories whose
+ * structuredFields fail to parse are skipped silently; they are diagnosed
+ * separately by the memory-consolidation scanner.
+ */
+function readKnowledgeMemories(category: "pattern" | "gotcha"): KnowledgeMemoryReadResult {
+  if (!isDbAvailable()) return { ok: false, rows: [] };
+  const adapter = _getAdapter();
+  if (!adapter) return { ok: false, rows: [] };
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT structured_fields FROM memories WHERE category = :cat AND structured_fields IS NOT NULL",
+      )
+      .all({ ":cat": category }) as Array<{ structured_fields: string | null }>;
+
+    const out: KnowledgeMemoryRow[] = [];
+    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.length === 0) continue;
+      out.push({ sourceId, structured: sf });
+    }
+    // Lexicographic sort matches the docstring contract (P001 < P002 < P010).
+    // DB seq order is creation-time; sorting by sourceId stabilizes the
+    // rendered output across reruns.
+    out.sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+    return { ok: true, rows: out };
+  } catch {
+    return { ok: false, rows: [] };
+  }
+}
+
+function escapeCell(value: string | undefined): string {
+  return (value ?? "")
+    .replace(/\s+/g, " ")
+    .replace(/\|/g, "\\|")
+    .trim();
+}
+
+function renderPatternsSection(memories: KnowledgeMemoryRow[]): string[] {
+  const lines = [PATTERNS_HEADING, "", PATTERNS_HEADER, PATTERNS_SEPARATOR];
+  for (const m of memories) {
+    const pattern = escapeCell(typeof m.structured["pattern"] === "string" ? (m.structured["pattern"] as string) : "");
+    const where = escapeCell(typeof m.structured["where"] === "string" ? (m.structured["where"] as string) : "");
+    const notes = escapeCell(typeof m.structured["notes"] === "string" ? (m.structured["notes"] as string) : "");
+    lines.push(`| ${m.sourceId} | ${pattern} | ${where || "—"} | ${notes || "—"} |`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function renderLessonsSection(memories: KnowledgeMemoryRow[]): string[] {
+  const lines = [LESSONS_HEADING, "", LESSONS_HEADER, LESSONS_SEPARATOR];
+  for (const m of memories) {
+    const what = escapeCell(typeof m.structured["whatHappened"] === "string" ? (m.structured["whatHappened"] as string) : "");
+    const rootCause = escapeCell(typeof m.structured["rootCause"] === "string" ? (m.structured["rootCause"] as string) : "");
+    const fix = escapeCell(typeof m.structured["fix"] === "string" ? (m.structured["fix"] as string) : "");
+    const scope = escapeCell(typeof m.structured["scopeText"] === "string" ? (m.structured["scopeText"] as string) : "");
+    lines.push(`| ${m.sourceId} | ${what} | ${rootCause || "—"} | ${fix || "—"} | ${scope || "project"} |`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/**
+ * Extract the Rules section (heading + table) from the existing
+ * `KNOWLEDGE.md` content, verbatim. Returns an empty default section
+ * (heading + empty table) when the source has no `## Rules` heading.
+ */
+function extractRulesSection(existing: string): string[] {
+  const lines = existing.split("\n");
+  const startIdx = lines.findIndex((l) => l.trim() === RULES_HEADING);
+  if (startIdx === -1) {
+    return [
+      RULES_HEADING,
+      "",
+      "| # | Scope | Rule | Why | Added |",
+      "|---|-------|------|-----|-------|",
+      "",
+    ];
+  }
+
+  // Find the next H2 heading that ends the Rules section.
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i]!.startsWith("## ")) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  // Strip trailing blank lines from the captured slice — the assembled
+  // output adds its own separator blank line between sections.
+  const slice = lines.slice(startIdx, endIdx);
+  while (slice.length > 0 && slice[slice.length - 1]!.trim() === "") {
+    slice.pop();
+  }
+  slice.push("");
+  return slice;
+}
+
+/**
+ * Extract the intro prose (anything before `## Rules`) verbatim, preserving
+ * any title (`# Project Knowledge`), comments, and description text. Falls
+ * back to the `DEFAULT_INTRO` template when the source has no Rules heading
+ * yet.
+ */
+function extractIntro(existing: string): string {
+  if (!existing.trim()) return DEFAULT_INTRO;
+  const lines = existing.split("\n");
+  const rulesIdx = lines.findIndex((l) => l.trim() === RULES_HEADING);
+  if (rulesIdx === -1) return DEFAULT_INTRO;
+  // Trim trailing blank lines so the assembly adds its own separator.
+  const slice = lines.slice(0, rulesIdx);
+  while (slice.length > 0 && slice[slice.length - 1]!.trim() === "") {
+    slice.pop();
+  }
+  slice.push("");
+  return slice.join("\n");
+}
+
+/**
+ * Render the hybrid `KNOWLEDGE.md`: manual Rules + projected Patterns +
+ * projected Lessons. Returns the rendered content and a flag indicating
+ * whether the file was written (skipped when content is byte-identical to
+ * what's on disk).
+ *
+ * Best-effort: catches all errors and returns `{ written: false, content: "" }`.
+ */
+export function renderKnowledgeProjection(basePath: string): KnowledgeProjectionResult {
+  try {
+    const existing = readKnowledgeMd(basePath);
+    const intro = extractIntro(existing);
+    const rules = extractRulesSection(existing);
+    const patternMemories = readKnowledgeMemories("pattern");
+    const lessonMemories = readKnowledgeMemories("gotcha");
+    if (!patternMemories.ok || !lessonMemories.ok) {
+      return { written: false, content: existing };
+    }
+    const patterns = renderPatternsSection(patternMemories.rows);
+    const lessons = renderLessonsSection(lessonMemories.rows);
+
+    const introText = intro
+      .replace(/\n{3,}/g, "\n\n")
+      .replace(/\s+$/g, "");
+    const projectedText = [...patterns, ...lessons]
+      .join("\n")
+      .replace(/\n{3,}/g, "\n\n")
+      .replace(/\s+$/g, "");
+    const content = [introText, rules.join("\n"), projectedText]
+      .join("\n")
+      .replace(/\s+$/g, "")
+      + "\n";
+
+    if (content === existing) {
+      return { written: false, content };
+    }
+
+    atomicWriteSync(knowledgeMdPath(basePath), content, "utf-8");
+    return { written: true, content };
+  } catch (e) {
+    logWarning("renderer", `KNOWLEDGE.md projection render failed: ${(e as Error).message}`);
+    return { written: false, content: "" };
+  }
+}
+
+// Re-export the section headings so tests can assert on the canonical
+// structure without re-defining the strings.
+export { KNOWLEDGE_SECTIONS };

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

@@ -32,7 +32,7 @@ import {
   resolveMilestoneFile,
   resolveSliceFile,
   resolveSlicePath,
-  resolveTasksDir,
+  gsdProjectionRoot,
   gsdRoot,
   buildTaskFileName,
   buildSliceFileName,
@@ -48,7 +48,11 @@ import { clearPathCache } from "./paths.js";
  * E.g. "/project/.gsd/milestones/M001/M001-ROADMAP.md" → "milestones/M001/M001-ROADMAP.md"
  */
 function toArtifactPath(absPath: string, basePath: string): string {
-  const root = gsdRoot(basePath);
+  const projectionRoot = gsdProjectionRoot(basePath);
+  const projectionRel = relative(projectionRoot, absPath);
+  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+    ? projectionRoot
+    : gsdRoot(basePath);
   const rel = relative(root, absPath);
   // Normalize to forward slashes for consistent DB keys
   return rel.replace(/\\/g, "/");
@@ -157,7 +161,12 @@ function renderRoadmapMarkdown(milestone: MilestoneRow, slices: SliceRow[]): str
   for (const slice of slices) {
     const done = isClosedStatus(slice.status) ? "x" : " ";
     const depends = `[${(slice.depends ?? []).join(",")}]`;
-    lines.push(`- [${done}] **${slice.id}: ${slice.title}** \`risk:${slice.risk}\` \`depends:${depends}\``);
+    // ADR-011: sketch slices get a `[sketch]` badge so the roadmap shows at a
+    // glance which slices are still pending refine-slice expansion. The badge
+    // sits in front of `risk:` so it's visible in narrow terminals that may
+    // truncate the line.
+    const sketchBadge = slice.is_sketch === 1 ? "`[sketch]` " : "";
+    lines.push(`- [${done}] **${slice.id}: ${slice.title}** ${sketchBadge}\`risk:${slice.risk}\` \`depends:${depends}\``);
     lines.push(`  > After this: ${slice.demo}`);
     lines.push("");
   }
@@ -369,10 +378,9 @@ export async function renderPlanFromDb(
     throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
   }
 
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN")
-    ?? join(slicePath, `${sliceId}-PLAN.md`);
+  const slicePath = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId);
+  mkdirSync(slicePath, { recursive: true });
+  const absPath = join(slicePath, `${sliceId}-PLAN.md`);
   const artifactPath = toArtifactPath(absPath, basePath);
   const sliceGates = getGateResults(milestoneId, sliceId, "slice");
   const content = renderSlicePlanMarkdown(slice, tasks, sliceGates);
@@ -403,8 +411,7 @@ export async function renderTaskPlanFromDb(
     throw new Error(`task ${milestoneId}/${sliceId}/${taskId} not found`);
   }
 
-  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+  const tasksDir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
   mkdirSync(tasksDir, { recursive: true });
   const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
   const artifactPath = toArtifactPath(absPath, basePath);

package/src/resources/extensions/gsd/md-importer.ts

@@ -306,7 +306,7 @@ function importRequirements(gsdDir: string): number {
 // ─── Hierarchy Artifact Walker ─────────────────────────────────────────────
 
 /** Artifact suffixes to look for at each hierarchy level */
-const MILESTONE_SUFFIXES = ['ROADMAP', 'CONTEXT', 'RESEARCH', 'ASSESSMENT'];
+const MILESTONE_SUFFIXES = ['ROADMAP', 'CONTEXT', 'RESEARCH', 'ASSESSMENT', 'SUMMARY', 'VALIDATION'];
 const SLICE_SUFFIXES = ['PLAN', 'SUMMARY', 'RESEARCH', 'CONTEXT', 'ASSESSMENT', 'UAT'];
 const TASK_SUFFIXES = ['PLAN', 'SUMMARY', 'CONTINUE', 'CONTEXT', 'RESEARCH'];
 

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;