gsd-pi 2.45.0 → 2.46.0-dev.cc9d310

package/dist/resources/extensions/gsd/workflow-migration.js

@@ -0,0 +1,280 @@
+// GSD Extension — Legacy Markdown to Engine Migration
+// Converts legacy markdown-only projects to engine state by parsing
+// existing ROADMAP.md, *-PLAN.md, and *-SUMMARY.md files.
+// Populates data into the already-existing v10 schema tables.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { _getAdapter, transaction } from "./gsd-db.js";
+import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
+// ─── needsAutoMigration ───────────────────────────────────────────────────
+/**
+ * Returns true when engine tables are empty AND a .gsd/milestones/ directory
+ * with markdown files exists — signals that this is a legacy project that needs
+ * one-time migration from markdown to engine state.
+ */
+export function needsAutoMigration(basePath) {
+    const db = _getAdapter();
+    if (!db)
+        return false;
+    // If milestones table already has rows, migration already done
+    try {
+        const row = db.prepare("SELECT COUNT(*) as cnt FROM milestones").get();
+        if (row && row["cnt"] > 0)
+            return false;
+    }
+    catch {
+        // Table might not exist yet — that's fine, we can still migrate
+        return false;
+    }
+    // Check if .gsd/milestones/ directory exists
+    const milestonesDir = join(basePath, ".gsd", "milestones");
+    if (!existsSync(milestonesDir))
+        return false;
+    return true;
+}
+// ─── migrateFromMarkdown ──────────────────────────────────────────────────
+/**
+ * Migrate legacy markdown-only .gsd/ projects to engine DB state.
+ * Reads .gsd/milestones/<ID>/ directories and parses ROADMAP.md, *-PLAN.md
+ * files. All inserts are wrapped in a transaction.
+ *
+ * This function only INSERTs data into the already-existing v10 schema tables
+ * (milestones, slices, tasks). It does NOT create tables or run migrations.
+ *
+ * Handles all directory shapes:
+ * - No DB: caller is responsible for openDatabase + initSchema before calling
+ * - Stale DB (empty tables): inserts succeed normally
+ * - No markdown at all: returns early with stderr message
+ * - Orphaned summary files: logs warning, skips without crash
+ */
+export function migrateFromMarkdown(basePath) {
+    const db = _getAdapter();
+    if (!db) {
+        process.stderr.write("workflow-migration: no database connection, cannot migrate\n");
+        return;
+    }
+    const milestonesDir = join(basePath, ".gsd", "milestones");
+    if (!existsSync(milestonesDir)) {
+        process.stderr.write("workflow-migration: no .gsd/milestones/ directory found, nothing to migrate\n");
+        return;
+    }
+    // Discover milestone directories (any directory at the top level of milestones/)
+    let milestoneDirs;
+    try {
+        milestoneDirs = readdirSync(milestonesDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name);
+    }
+    catch {
+        process.stderr.write("workflow-migration: failed to read milestones directory\n");
+        return;
+    }
+    if (milestoneDirs.length === 0) {
+        process.stderr.write("workflow-migration: no milestone directories found in .gsd/milestones/\n");
+        return;
+    }
+    // Collect all data before the transaction
+    const migratedMilestoneIds = [];
+    const milestoneInserts = [];
+    const sliceInserts = [];
+    const taskInserts = [];
+    for (const mId of milestoneDirs) {
+        const mDir = join(milestonesDir, mId);
+        // Determine milestone status: done if a milestone-level SUMMARY.md exists
+        const milestoneSummaryPath = join(mDir, "SUMMARY.md");
+        const milestoneDone = existsSync(milestoneSummaryPath);
+        const milestoneStatus = milestoneDone ? "done" : "active";
+        // Parse ROADMAP.md for slices list
+        const roadmapPath = join(mDir, "ROADMAP.md");
+        let roadmapSlices = [];
+        if (existsSync(roadmapPath)) {
+            try {
+                const roadmapContent = readFileSync(roadmapPath, "utf-8");
+                const roadmap = parseRoadmap(roadmapContent);
+                // Extract milestone title from roadmap
+                const mTitle = roadmap.title || mId;
+                milestoneInserts.push({ id: mId, title: mTitle, status: milestoneStatus });
+                roadmapSlices = roadmap.slices.map(s => ({
+                    id: s.id,
+                    title: s.title,
+                    done: s.done,
+                    risk: s.risk || "low",
+                }));
+            }
+            catch (err) {
+                process.stderr.write(`workflow-migration: failed to parse ROADMAP.md for ${mId}: ${err.message}\n`);
+                // Still add milestone with ID as title
+                milestoneInserts.push({ id: mId, title: mId, status: milestoneStatus });
+            }
+        }
+        else {
+            // No ROADMAP.md — add milestone entry anyway using directory name
+            milestoneInserts.push({ id: mId, title: mId, status: milestoneStatus });
+        }
+        migratedMilestoneIds.push(mId);
+        // Collect slices from ROADMAP + their tasks from PLAN files
+        const knownSliceIds = new Set(roadmapSlices.map(s => s.id));
+        for (let sIdx = 0; sIdx < roadmapSlices.length; sIdx++) {
+            const slice = roadmapSlices[sIdx];
+            // Per Pitfall #5: if milestone is done, force all child slices to done
+            const sliceStatus = milestoneDone ? "done" : (slice.done ? "done" : "pending");
+            sliceInserts.push({
+                id: slice.id,
+                milestoneId: mId,
+                title: slice.title,
+                status: sliceStatus,
+                risk: slice.risk,
+                sequence: sIdx,
+                forceDone: milestoneDone,
+            });
+            // Read *-PLAN.md for this slice
+            const planPath = join(mDir, `${slice.id}-PLAN.md`);
+            if (existsSync(planPath)) {
+                try {
+                    const planContent = readFileSync(planPath, "utf-8");
+                    const plan = parsePlan(planContent);
+                    for (let tIdx = 0; tIdx < plan.tasks.length; tIdx++) {
+                        const task = plan.tasks[tIdx];
+                        // Per Pitfall #5: if milestone is done, force all tasks to done
+                        const taskStatus = milestoneDone ? "done" : (task.done ? "done" : "pending");
+                        taskInserts.push({
+                            id: task.id,
+                            sliceId: slice.id,
+                            milestoneId: mId,
+                            title: task.title,
+                            status: taskStatus,
+                            sequence: tIdx,
+                        });
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`workflow-migration: failed to parse ${slice.id}-PLAN.md for ${mId}: ${err.message}\n`);
+                }
+            }
+        }
+        // Check for orphaned summary files (summary for a slice not in ROADMAP)
+        try {
+            const files = readdirSync(mDir);
+            const summaryFiles = files.filter(f => f.endsWith("-SUMMARY.md") && f !== "SUMMARY.md");
+            for (const summaryFile of summaryFiles) {
+                const sliceId = summaryFile.replace("-SUMMARY.md", "");
+                if (!knownSliceIds.has(sliceId)) {
+                    process.stderr.write(`workflow-migration: orphaned summary file ${summaryFile} in ${mId} (slice not found in ROADMAP.md), skipping\n`);
+                }
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    // Execute all inserts atomically
+    const now = new Date().toISOString();
+    if (migratedMilestoneIds.length === 0) {
+        process.stderr.write("workflow-migration: no milestones collected, nothing to insert\n");
+        return;
+    }
+    const placeholders = migratedMilestoneIds.map(() => "?").join(",");
+    transaction(() => {
+        // Clear existing data to handle stale DB shape (DELETE ... IN (...))
+        db.prepare(`DELETE FROM tasks WHERE milestone_id IN (${placeholders})`).run(...migratedMilestoneIds);
+        db.prepare(`DELETE FROM slices WHERE milestone_id IN (${placeholders})`).run(...migratedMilestoneIds);
+        db.prepare(`DELETE FROM milestones WHERE id IN (${placeholders})`).run(...migratedMilestoneIds);
+        // Insert milestones
+        const insertMilestone = db.prepare("INSERT INTO milestones (id, title, status, created_at) VALUES (?, ?, ?, ?)");
+        for (const m of milestoneInserts) {
+            insertMilestone.run(m.id, m.title, m.status, now);
+        }
+        // Insert slices (using v10 column names: depends, sequence)
+        const insertSlice = db.prepare("INSERT INTO slices (id, milestone_id, title, status, risk, depends, sequence, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+        for (const s of sliceInserts) {
+            insertSlice.run(s.id, s.milestoneId, s.title, s.status, s.risk, "[]", s.sequence, now);
+        }
+        // Insert tasks (using v10 column names: sequence, blocker_discovered, full_summary_md)
+        const insertTask = db.prepare("INSERT INTO tasks (id, slice_id, milestone_id, title, description, status, estimate, files, sequence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)");
+        for (const t of taskInserts) {
+            insertTask.run(t.id, t.sliceId, t.milestoneId, t.title, "", t.status, "", "[]", t.sequence);
+        }
+    });
+}
+// ─── validateMigration ────────────────────────────────────────────────────
+/**
+ * D-14: Validate that engine state matches what markdown parsers report.
+ * Compares milestone count, slice count, task count, and status distributions.
+ * Logs each discrepancy to stderr but does NOT throw.
+ * Returns array of discrepancy strings (empty = clean migration).
+ */
+export function validateMigration(basePath) {
+    const db = _getAdapter();
+    if (!db) {
+        return { discrepancies: ["No database connection for validation"] };
+    }
+    const discrepancies = [];
+    // Get engine counts
+    const engMilestones = db.prepare("SELECT COUNT(*) as cnt FROM milestones").get();
+    const engSlices = db.prepare("SELECT COUNT(*) as cnt FROM slices").get();
+    const engTasks = db.prepare("SELECT COUNT(*) as cnt FROM tasks").get();
+    const engineMilestoneCount = engMilestones ? engMilestones["cnt"] : 0;
+    const engineSliceCount = engSlices ? engSlices["cnt"] : 0;
+    const engineTaskCount = engTasks ? engTasks["cnt"] : 0;
+    // Count from markdown
+    const milestonesDir = join(basePath, ".gsd", "milestones");
+    if (!existsSync(milestonesDir)) {
+        return { discrepancies };
+    }
+    let mdMilestoneCount = 0;
+    let mdSliceCount = 0;
+    let mdTaskCount = 0;
+    try {
+        const milestoneDirs = readdirSync(milestonesDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name);
+        mdMilestoneCount = milestoneDirs.length;
+        for (const mId of milestoneDirs) {
+            const mDir = join(milestonesDir, mId);
+            const roadmapPath = join(mDir, "ROADMAP.md");
+            if (existsSync(roadmapPath)) {
+                try {
+                    const content = readFileSync(roadmapPath, "utf-8");
+                    const roadmap = parseRoadmap(content);
+                    mdSliceCount += roadmap.slices.length;
+                    for (const slice of roadmap.slices) {
+                        const planPath = join(mDir, `${slice.id}-PLAN.md`);
+                        if (existsSync(planPath)) {
+                            try {
+                                const planContent = readFileSync(planPath, "utf-8");
+                                const plan = parsePlan(planContent);
+                                mdTaskCount += plan.tasks.length;
+                            }
+                            catch {
+                                // Skip unreadable plan
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Skip unreadable roadmap
+                }
+            }
+        }
+    }
+    catch {
+        return { discrepancies: ["Failed to read markdown for validation"] };
+    }
+    // Compare counts
+    if (engineMilestoneCount !== mdMilestoneCount) {
+        const msg = `Milestone count mismatch: engine=${engineMilestoneCount}, markdown=${mdMilestoneCount}`;
+        discrepancies.push(msg);
+        process.stderr.write(`workflow-migration: ${msg}\n`);
+    }
+    if (engineSliceCount !== mdSliceCount) {
+        const msg = `Slice count mismatch: engine=${engineSliceCount}, markdown=${mdSliceCount}`;
+        discrepancies.push(msg);
+        process.stderr.write(`workflow-migration: ${msg}\n`);
+    }
+    if (engineTaskCount !== mdTaskCount) {
+        const msg = `Task count mismatch: engine=${engineTaskCount}, markdown=${mdTaskCount}`;
+        discrepancies.push(msg);
+        process.stderr.write(`workflow-migration: ${msg}\n`);
+    }
+    return { discrepancies };
+}

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -0,0 +1,373 @@
+// GSD Extension — Projection Renderers (DB -> Markdown)
+// Renders PLAN.md, ROADMAP.md, SUMMARY.md, and STATE.md from database rows.
+// Projections are read-only views of engine state (Layer 3 of the architecture).
+import { _getAdapter, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, } from "./gsd-db.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { join } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+import { logWarning } from "./workflow-logger.js";
+import { deriveState } from "./state.js";
+// ─── PLAN.md Projection ──────────────────────────────────────────────────
+/**
+ * Render PLAN.md content from a slice row and its task rows.
+ * Pure function — no side effects.
+ */
+export function renderPlanContent(sliceRow, taskRows) {
+    const lines = [];
+    lines.push(`# ${sliceRow.id}: ${sliceRow.title}`);
+    lines.push("");
+    lines.push(`**Goal:** ${sliceRow.goal || sliceRow.full_summary_md || "TBD"}`);
+    lines.push(`**Demo:** After this: ${sliceRow.demo || sliceRow.full_uat_md || "TBD"}`);
+    lines.push("");
+    lines.push("## Tasks");
+    for (const task of taskRows) {
+        const checkbox = task.status === "done" || task.status === "complete" ? "[x]" : "[ ]";
+        lines.push(`- ${checkbox} **${task.id}: ${task.title}** \u2014 ${task.description}`);
+        // Estimate subline (always present if non-empty)
+        if (task.estimate) {
+            lines.push(`  - Estimate: ${task.estimate}`);
+        }
+        // Files subline (only if non-empty array)
+        if (task.files && task.files.length > 0) {
+            lines.push(`  - Files: ${task.files.join(", ")}`);
+        }
+        // Verify subline (only if non-null)
+        if (task.verify) {
+            lines.push(`  - Verify: ${task.verify}`);
+        }
+        // Duration subline (only if recorded)
+        if (task.duration) {
+            lines.push(`  - Duration: ${task.duration}`);
+        }
+        // Blocker subline (if discovered)
+        if (task.blocker_discovered && task.known_issues) {
+            lines.push(`  - Blocker: ${task.known_issues}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Render PLAN.md projection to disk for a specific slice.
+ * Queries DB via helper functions, renders content, writes via atomicWriteSync.
+ */
+export function renderPlanProjection(basePath, milestoneId, sliceId) {
+    const sliceRows = getMilestoneSlices(milestoneId);
+    const sliceRow = sliceRows.find(s => s.id === sliceId);
+    if (!sliceRow)
+        return;
+    const taskRows = getSliceTasks(milestoneId, sliceId);
+    const content = renderPlanContent(sliceRow, taskRows);
+    const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId);
+    mkdirSync(dir, { recursive: true });
+    atomicWriteSync(join(dir, `${sliceId}-PLAN.md`), content);
+}
+// ─── ROADMAP.md Projection ───────────────────────────────────────────────
+/**
+ * Render ROADMAP.md content from a milestone row and its slice rows.
+ * Pure function — no side effects.
+ */
+export function renderRoadmapContent(milestoneRow, sliceRows) {
+    const lines = [];
+    lines.push(`# ${milestoneRow.id}: ${milestoneRow.title}`);
+    lines.push("");
+    lines.push("## Vision");
+    lines.push(milestoneRow.vision || milestoneRow.title || "TBD");
+    lines.push("");
+    lines.push("## Slice Overview");
+    lines.push("| ID | Slice | Risk | Depends | Done | After this |");
+    lines.push("|----|-------|------|---------|------|------------|");
+    for (const slice of sliceRows) {
+        const done = slice.status === "done" || slice.status === "complete" ? "\u2705" : "\u2B1C";
+        // depends is already parsed to string[] by rowToSlice
+        let depends = "\u2014";
+        if (slice.depends && slice.depends.length > 0) {
+            depends = slice.depends.join(", ");
+        }
+        const risk = (slice.risk || "low").toLowerCase();
+        const demo = slice.demo || slice.full_uat_md || "TBD";
+        lines.push(`| ${slice.id} | ${slice.title} | ${risk} | ${depends} | ${done} | ${demo} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Render ROADMAP.md projection to disk for a specific milestone.
+ * Queries DB via helper functions, renders content, writes via atomicWriteSync.
+ */
+export function renderRoadmapProjection(basePath, milestoneId) {
+    const milestoneRow = getMilestone(milestoneId);
+    if (!milestoneRow)
+        return;
+    const sliceRows = getMilestoneSlices(milestoneId);
+    const content = renderRoadmapContent(milestoneRow, sliceRows);
+    const dir = join(basePath, ".gsd", "milestones", milestoneId);
+    mkdirSync(dir, { recursive: true });
+    atomicWriteSync(join(dir, `${milestoneId}-ROADMAP.md`), content);
+}
+// ─── SUMMARY.md Projection ──────────────────────────────────────────────
+/**
+ * Render SUMMARY.md content from a task row.
+ * Pure function — no side effects.
+ */
+export function renderSummaryContent(taskRow, sliceId, milestoneId) {
+    const lines = [];
+    // Frontmatter
+    lines.push("---");
+    lines.push(`id: ${taskRow.id}`);
+    lines.push(`parent: ${sliceId}`);
+    lines.push(`milestone: ${milestoneId}`);
+    lines.push("provides: []");
+    lines.push("requires: []");
+    lines.push("affects: []");
+    // key_files is already parsed to string[]
+    if (taskRow.key_files && taskRow.key_files.length > 0) {
+        lines.push(`key_files: [${taskRow.key_files.map(f => `"${f}"`).join(", ")}]`);
+    }
+    else {
+        lines.push("key_files: []");
+    }
+    // key_decisions is already parsed to string[]
+    if (taskRow.key_decisions && taskRow.key_decisions.length > 0) {
+        lines.push(`key_decisions: [${taskRow.key_decisions.map(d => `"${d}"`).join(", ")}]`);
+    }
+    else {
+        lines.push("key_decisions: []");
+    }
+    lines.push("patterns_established: []");
+    lines.push("drill_down_paths: []");
+    lines.push("observability_surfaces: []");
+    lines.push(`duration: "${taskRow.duration || ""}"`);
+    lines.push(`verification_result: "${taskRow.verification_result || ""}"`);
+    lines.push(`completed_at: ${taskRow.completed_at || ""}`);
+    lines.push(`blocker_discovered: ${taskRow.blocker_discovered ? "true" : "false"}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${taskRow.id}: ${taskRow.title}`);
+    lines.push("");
+    // One-liner (if present)
+    if (taskRow.one_liner) {
+        lines.push(`> ${taskRow.one_liner}`);
+        lines.push("");
+    }
+    lines.push("## What Happened");
+    lines.push(taskRow.full_summary_md || taskRow.narrative || "No summary recorded.");
+    lines.push("");
+    // Deviations (if present)
+    if (taskRow.deviations) {
+        lines.push("## Deviations");
+        lines.push(taskRow.deviations);
+        lines.push("");
+    }
+    // Known issues (if present)
+    if (taskRow.known_issues) {
+        lines.push("## Known Issues");
+        lines.push(taskRow.known_issues);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Render SUMMARY.md projection to disk for a specific task.
+ * Queries DB via helper functions, renders content, writes via atomicWriteSync.
+ */
+export function renderSummaryProjection(basePath, milestoneId, sliceId, taskId) {
+    const taskRows = getSliceTasks(milestoneId, sliceId);
+    const taskRow = taskRows.find(t => t.id === taskId);
+    if (!taskRow)
+        return;
+    const content = renderSummaryContent(taskRow, sliceId, milestoneId);
+    const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+    mkdirSync(dir, { recursive: true });
+    atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
+}
+// ─── STATE.md Projection ────────────────────────────────────────────────
+/**
+ * Render STATE.md content from GSDState.
+ * Matches the buildStateMarkdown output format from doctor.ts exactly.
+ * Pure function — no side effects.
+ */
+export function renderStateContent(state) {
+    const lines = [];
+    lines.push("# GSD State", "");
+    const activeMilestone = state.activeMilestone
+        ? `${state.activeMilestone.id}: ${state.activeMilestone.title}`
+        : "None";
+    const activeSlice = state.activeSlice
+        ? `${state.activeSlice.id}: ${state.activeSlice.title}`
+        : "None";
+    lines.push(`**Active Milestone:** ${activeMilestone}`);
+    lines.push(`**Active Slice:** ${activeSlice}`);
+    lines.push(`**Phase:** ${state.phase}`);
+    if (state.requirements) {
+        lines.push(`**Requirements Status:** ${state.requirements.active} active \u00b7 ${state.requirements.validated} validated \u00b7 ${state.requirements.deferred} deferred \u00b7 ${state.requirements.outOfScope} out of scope`);
+    }
+    lines.push("");
+    lines.push("## Milestone Registry");
+    for (const entry of state.registry) {
+        const glyph = entry.status === "complete" ? "\u2705" : entry.status === "active" ? "\uD83D\uDD04" : entry.status === "parked" ? "\u23F8\uFE0F" : "\u2B1C";
+        lines.push(`- ${glyph} **${entry.id}:** ${entry.title}`);
+    }
+    lines.push("");
+    lines.push("## Recent Decisions");
+    if (state.recentDecisions.length > 0) {
+        for (const decision of state.recentDecisions)
+            lines.push(`- ${decision}`);
+    }
+    else {
+        lines.push("- None recorded");
+    }
+    lines.push("");
+    lines.push("## Blockers");
+    if (state.blockers.length > 0) {
+        for (const blocker of state.blockers)
+            lines.push(`- ${blocker}`);
+    }
+    else {
+        lines.push("- None");
+    }
+    lines.push("");
+    lines.push("## Next Action");
+    lines.push(state.nextAction || "None");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Render STATE.md projection to disk.
+ * Derives state from DB, renders content, writes via atomicWriteSync.
+ */
+export async function renderStateProjection(basePath) {
+    try {
+        if (!isDbAvailable())
+            return;
+        // Probe DB handle — adapter may be set but underlying handle closed
+        const adapter = _getAdapter();
+        if (!adapter)
+            return;
+        try {
+            adapter.prepare("SELECT 1").get();
+        }
+        catch {
+            return;
+        }
+        const state = await deriveState(basePath);
+        const content = renderStateContent(state);
+        const dir = join(basePath, ".gsd");
+        mkdirSync(dir, { recursive: true });
+        atomicWriteSync(join(dir, "STATE.md"), content);
+    }
+    catch (err) {
+        logWarning("projection", `renderStateProjection failed: ${err.message}`);
+    }
+}
+// ─── renderAllProjections ───────────────────────────────────────────────
+/**
+ * Regenerate all projection files for a milestone from DB state.
+ * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ */
+export async function renderAllProjections(basePath, milestoneId) {
+    // Render ROADMAP.md for the milestone
+    try {
+        renderRoadmapProjection(basePath, milestoneId);
+    }
+    catch (err) {
+        logWarning("projection", `renderRoadmapProjection failed for ${milestoneId}: ${err.message}`);
+    }
+    // Query all slices for this milestone
+    const sliceRows = getMilestoneSlices(milestoneId);
+    for (const slice of sliceRows) {
+        // Render PLAN.md for each slice
+        try {
+            renderPlanProjection(basePath, milestoneId, slice.id);
+        }
+        catch (err) {
+            logWarning("projection", `renderPlanProjection failed for ${milestoneId}/${slice.id}: ${err.message}`);
+        }
+        // Render SUMMARY.md for each completed task
+        const taskRows = getSliceTasks(milestoneId, slice.id);
+        const doneTasks = taskRows.filter(t => t.status === "done" || t.status === "complete");
+        for (const task of doneTasks) {
+            try {
+                renderSummaryProjection(basePath, milestoneId, slice.id, task.id);
+            }
+            catch (err) {
+                logWarning("projection", `renderSummaryProjection failed for ${milestoneId}/${slice.id}/${task.id}: ${err.message}`);
+            }
+        }
+    }
+    // Render STATE.md
+    try {
+        await renderStateProjection(basePath);
+    }
+    catch (err) {
+        logWarning("projection", `renderStateProjection failed: ${err.message}`);
+    }
+}
+// ─── regenerateIfMissing ────────────────────────────────────────────────
+/**
+ * Check if a projection file exists on disk. If missing, regenerate it from DB.
+ * Returns true if the file was regenerated, false if it already existed.
+ * Satisfies PROJ-05 (corrupted/deleted projections regenerate on demand).
+ */
+export function regenerateIfMissing(basePath, milestoneId, sliceId, fileType) {
+    let filePath;
+    switch (fileType) {
+        case "PLAN":
+            filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+            break;
+        case "ROADMAP":
+            filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
+            break;
+        case "SUMMARY":
+            // For SUMMARY, we regenerate all task summaries in the slice
+            filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+            break;
+        case "STATE":
+            filePath = join(basePath, ".gsd", "STATE.md");
+            break;
+    }
+    if (fileType === "SUMMARY") {
+        // Check each completed task's SUMMARY file individually (not just the directory)
+        const taskRows = getSliceTasks(milestoneId, sliceId);
+        const doneTasks = taskRows.filter(t => t.status === "done" || t.status === "complete");
+        let regenerated = 0;
+        for (const task of doneTasks) {
+            const summaryPath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks", `${task.id}-SUMMARY.md`);
+            if (!existsSync(summaryPath)) {
+                try {
+                    renderSummaryProjection(basePath, milestoneId, sliceId, task.id);
+                    regenerated++;
+                }
+                catch (err) {
+                    console.error(`[projections] regenerateIfMissing SUMMARY failed for ${task.id}:`, err);
+                }
+            }
+        }
+        return regenerated > 0;
+    }
+    if (existsSync(filePath)) {
+        return false;
+    }
+    // Regenerate the missing file
+    try {
+        switch (fileType) {
+            case "PLAN":
+                renderPlanProjection(basePath, milestoneId, sliceId);
+                break;
+            case "ROADMAP":
+                renderRoadmapProjection(basePath, milestoneId);
+                break;
+            case "STATE":
+                // renderStateProjection is async — fire-and-forget.
+                // Return false since the file isn't written yet; it will appear
+                // on the next post-mutation hook cycle.
+                void renderStateProjection(basePath);
+                return false;
+        }
+        return true;
+    }
+    catch (err) {
+        console.error(`[projections] regenerateIfMissing ${fileType} failed:`, err);
+        return false;
+    }
+}