gsd-pi 2.82.0 → 3.0.0

package/dist/resources/extensions/gsd/guided-unit-context.js

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

package/dist/resources/extensions/gsd/knowledge-backfill.js

@@ -0,0 +1,144 @@
+// 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 } from "./knowledge-parser.js";
+import { logWarning } from "./workflow-logger.js";
+/**
+ * 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) {
+    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.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) {
+    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 = [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 = [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, max) {
+    const cleaned = value.replace(/\s+/g, " ").trim();
+    return cleaned.length > max ? cleaned.slice(0, max - 1) + "…" : cleaned;
+}

package/dist/resources/extensions/gsd/knowledge-capture.js

@@ -0,0 +1,136 @@
+// 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";
+/**
+ * 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, type, entryText, scope) {
+    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 = 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.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, prefix) {
+    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, prefix) {
+    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) {
+    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}%` });
+        let max = 0;
+        for (const row of rows) {
+            if (!row.structured_fields)
+                continue;
+            let sf;
+            try {
+                sf = JSON.parse(row.structured_fields);
+            }
+            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/dist/resources/extensions/gsd/knowledge-parser.js

@@ -0,0 +1,154 @@
+// 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 const KNOWLEDGE_SECTIONS = [
+    { 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) {
+    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) {
+    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) {
+    const rows = [];
+    if (!content.trim())
+        return rows;
+    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;
+        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) {
+    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) {
+    const cells = [];
+    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;
+}

package/dist/resources/extensions/gsd/knowledge-projection.js

@@ -0,0 +1,210 @@
+// 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");
+/**
+ * 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) {
+    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 });
+        const out = [];
+        for (const row of rows) {
+            if (!row.structured_fields)
+                continue;
+            let sf;
+            try {
+                sf = JSON.parse(row.structured_fields);
+            }
+            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) {
+    return (value ?? "")
+        .replace(/\s+/g, " ")
+        .replace(/\|/g, "\\|")
+        .trim();
+}
+function renderPatternsSection(memories) {
+    const lines = [PATTERNS_HEADING, "", PATTERNS_HEADER, PATTERNS_SEPARATOR];
+    for (const m of memories) {
+        const pattern = escapeCell(typeof m.structured["pattern"] === "string" ? m.structured["pattern"] : "");
+        const where = escapeCell(typeof m.structured["where"] === "string" ? m.structured["where"] : "");
+        const notes = escapeCell(typeof m.structured["notes"] === "string" ? m.structured["notes"] : "");
+        lines.push(`| ${m.sourceId} | ${pattern} | ${where || "—"} | ${notes || "—"} |`);
+    }
+    lines.push("");
+    return lines;
+}
+function renderLessonsSection(memories) {
+    const lines = [LESSONS_HEADING, "", LESSONS_HEADER, LESSONS_SEPARATOR];
+    for (const m of memories) {
+        const what = escapeCell(typeof m.structured["whatHappened"] === "string" ? m.structured["whatHappened"] : "");
+        const rootCause = escapeCell(typeof m.structured["rootCause"] === "string" ? m.structured["rootCause"] : "");
+        const fix = escapeCell(typeof m.structured["fix"] === "string" ? m.structured["fix"] : "");
+        const scope = escapeCell(typeof m.structured["scopeText"] === "string" ? m.structured["scopeText"] : "");
+        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) {
+    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) {
+    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) {
+    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.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 };