gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

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

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

@@ -157,7 +157,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("");
   }
@@ -920,101 +925,10 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
 }
 
 // ─── Stale Repair ─────────────────────────────────────────────────────────
-
-/**
- * Repair all stale renders detected by `detectStaleRenders()`.
- *
- * For each stale entry, calls the appropriate render function:
- * - Roadmap checkbox mismatches → renderRoadmapCheckboxes()
- * - Plan checkbox mismatches → renderPlanCheckboxes()
- * - Missing task summaries → renderTaskSummary()
- * - Missing slice summaries/UATs → renderSliceSummary()
- *
- * Idempotent: calling twice with no DB changes produces zero repairs on the second call.
- *
- * @returns the number of files repaired
- */
-export async function repairStaleRenders(basePath: string): Promise<number> {
-  const staleEntries = detectStaleRenders(basePath);
-  if (staleEntries.length === 0) return 0;
-
-  // Deduplicate: a single roadmap/plan file might appear multiple times
-  // (once per mismatched checkbox). We only need to re-render it once.
-  const repairedPaths = new Set<string>();
-  let repairCount = 0;
-
-  for (const entry of staleEntries) {
-    if (repairedPaths.has(entry.path)) continue;
-    // Normalize path separators for cross-platform regex matching
-    const normPath = entry.path.replace(/\\/g, "/");
-
-    try {
-      // Determine repair action from the reason
-      if (entry.reason.includes("in roadmap")) {
-        // Roadmap checkbox mismatch — extract milestone ID from path
-        const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
-        if (milestoneMatch) {
-          const ok = await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("in plan")) {
-        // Plan checkbox mismatch — extract milestone + slice IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^T\d+/)) {
-        // Missing task summary — extract IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
-        const taskMatch = entry.reason.match(/^(T\d+)/);
-        if (pathMatch && taskMatch) {
-          const ok = await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^S\d+/)) {
-        // Missing slice summary — extract IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("UAT.md missing")) {
-        // Missing slice UAT — renderSliceSummary handles both SUMMARY + UAT
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      }
-    } catch (err) {
-      logWarning("renderer", `repair failed for ${entry.path}: ${(err as Error).message}`);
-    }
-  }
-
-  if (repairCount > 0) {
-    process.stderr.write(
-      `markdown-renderer: repaired ${repairCount} stale render(s)\n`,
-    );
-  }
-
-  return repairCount;
-}
+// Body relocated to state-reconciliation/drift/stale-render.ts (ADR-017 #5702).
+// detectStaleRenders above stays as a useful diagnostic primitive; the
+// drift handler composes it with the per-reason renderer dispatch and the
+// reconcileBeforeDispatch lifecycle.
 
 // ─── Replan & Assessment Renderers ────────────────────────────────────────