@opengsd/gsd-pi 1.7.0 → 1.8.1

package/README.md

@@ -28,12 +28,14 @@ See [CHANGELOG.md](./CHANGELOG.md) for release-by-release fixes and [Legacy Rele
 ## Latest Release Highlights
 
 <!-- release-highlights:start -->
-Latest release: **v1.7.0**
-
-- **cloud:** Add device-flow login to daemon + @opengsd/gsd-cloud agent (#1278).
-- **issue:** [Bug]: Unattended `gsd headless auto` has no resumer for the parallel/slice_parallel worker pause signal → terminal exit 10 after the first unit.
-- **issue:** Complete-slice's reopen reason never reaches the re-dispatched execute-task (follow-up to #1225).
-- **issue:** [Feature Request]: gsd-browser daemon has no automatic teardown — orphaned Chrome process survives session/task completion.
+Latest release: **v1.8.1**
+
+- **doctor:** Extract state checks.
+- **doctor:** Extract history and workspace checks.
+- **issue:** Unregistered-milestone false positive: flat-phase ID extractor derives bare M### from descriptive slug, missing suffixed DB row (M###-abcdef) (#1282).
+- **issue:** [Bug] reconcile triggers mass re-projection of all historical PLAN.md files, resetting completed task checkboxes to unchecked (#1279).
+- **issue:** [Bug]: `migrateHierarchyToDb` imports a `[sketch]` slice's stub PLAN tasks as real DB rows, flipping planning→executing.
+- **issue:** [Bug]: `sketchFlagHandler` clears `is_sketch` on mere PLAN-file existence, including a stub or leftover PLAN.
 
 <!-- release-highlights:end -->
 

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-1995c618cd0898a5
+f38cd5787a6340c5

package/dist/resources/extensions/gsd/doctor-history.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { saveFile } from "./files.js";
+import { gsdRoot } from "./paths.js";
+function buildDoctorHistorySummary(report, errorCount, warningCount, issueDetails) {
+    const summaryParts = [];
+    if (report.ok) {
+        summaryParts.push("Clean");
+    }
+    else {
+        const counts = [];
+        if (errorCount > 0)
+            counts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
+        if (warningCount > 0)
+            counts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
+        summaryParts.push(counts.join(", "));
+    }
+    if (report.fixesApplied.length > 0) {
+        summaryParts.push(`${report.fixesApplied.length} fixed`);
+    }
+    if (issueDetails && issueDetails.length > 0) {
+        const topIssue = issueDetails.find(i => i.severity === "error") ?? issueDetails[0];
+        summaryParts.push(topIssue.message);
+    }
+    return summaryParts.join(" · ");
+}
+export async function appendDoctorHistory(basePath, report) {
+    try {
+        const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+        const errorCount = report.issues.filter(i => i.severity === "error").length;
+        const warningCount = report.issues.filter(i => i.severity === "warning").length;
+        const issueDetails = report.issues
+            .filter(i => i.severity === "error" || i.severity === "warning")
+            .slice(0, 10) // cap to keep JSONL lines bounded
+            .map(i => ({ severity: i.severity, code: i.code, message: i.message, unitId: i.unitId }));
+        const entry = JSON.stringify({
+            ts: new Date().toISOString(),
+            ok: report.ok,
+            errors: errorCount,
+            warnings: warningCount,
+            fixes: report.fixesApplied.length,
+            codes: [...new Set(report.issues.map(i => i.code))],
+            issues: issueDetails.length > 0 ? issueDetails : undefined,
+            fixDescriptions: report.fixesApplied.length > 0 ? report.fixesApplied : undefined,
+            scope: report.scope,
+            summary: buildDoctorHistorySummary(report, errorCount, warningCount, issueDetails),
+        });
+        const existing = existsSync(historyPath) ? readFileSync(historyPath, "utf-8") : "";
+        await saveFile(historyPath, existing + entry + "\n");
+    }
+    catch { /* non-fatal */ }
+}
+/** Read the last N doctor history entries. Returns most-recent-first. */
+export async function readDoctorHistory(basePath, lastN = 50) {
+    try {
+        const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+        if (!existsSync(historyPath))
+            return [];
+        const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+        return lines.slice(-lastN).reverse().map(l => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/resources/extensions/gsd/doctor-state-checks.js

@@ -0,0 +1,509 @@
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
+import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, legacyMilestonesDir, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
+import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
+import { runProviderChecks } from "./doctor-providers.js";
+import { validateTitle } from "./validation.js";
+function matchesScope(unitId, scope) {
+    if (!scope)
+        return true;
+    return unitId === scope || unitId.startsWith(`${scope}/`);
+}
+function auditRequirements(content) {
+    if (!content)
+        return [];
+    const issues = [];
+    const blocks = content.split(/^###\s+/m).slice(1);
+    for (const block of blocks) {
+        const idMatch = block.match(/^(R\d+)/);
+        if (!idMatch)
+            continue;
+        const requirementId = idMatch[1];
+        const status = block.match(/^-\s+Status:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
+        const owner = block.match(/^-\s+Primary owning slice:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
+        const notes = block.match(/^-\s+Notes:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
+        if (status === "active" && (!owner || owner === "none" || owner === "none yet")) {
+            // #4414: Downgrade to warning. A newly-created requirement has
+            // primary_owner='' by default until the planning agent wires it to
+            // a slice via gsd_requirement_update. Flagging this as an error
+            // during normal planning is noisy — the real failure mode is when
+            // it persists past milestone completion, which is covered by other
+            // audits. Keep the signal but don't treat it as a blocker.
+            issues.push({
+                severity: "warning",
+                code: "active_requirement_missing_owner",
+                scope: "project",
+                unitId: requirementId,
+                message: `${requirementId} is Active but has no primary owning slice`,
+                file: relGsdRootFile("REQUIREMENTS"),
+                fixable: false,
+            });
+        }
+        if (status === "blocked" && !notes) {
+            issues.push({
+                severity: "warning",
+                code: "blocked_requirement_missing_reason",
+                scope: "project",
+                unitId: requirementId,
+                message: `${requirementId} is Blocked but has no reason in Notes`,
+                file: relGsdRootFile("REQUIREMENTS"),
+                fixable: false,
+            });
+        }
+    }
+    return issues;
+}
+// ── Helper: circular dependency detection ──────────────────────────────────
+function detectCircularDependencies(slices) {
+    const known = new Set(slices.map(s => s.id));
+    const adj = new Map();
+    for (const s of slices)
+        adj.set(s.id, s.depends.filter(d => known.has(d)));
+    const state = new Map();
+    for (const s of slices)
+        state.set(s.id, "unvisited");
+    const cycles = [];
+    function dfs(id, path) {
+        const st = state.get(id);
+        if (st === "done")
+            return;
+        if (st === "visiting") {
+            cycles.push([...path.slice(path.indexOf(id)), id]);
+            return;
+        }
+        state.set(id, "visiting");
+        for (const dep of adj.get(id) ?? [])
+            dfs(dep, [...path, id]);
+        state.set(id, "done");
+    }
+    for (const s of slices)
+        if (state.get(s.id) === "unvisited")
+            dfs(s.id, []);
+    return cycles;
+}
+export async function checkGsdStateHealth(basePath, issues, fixesApplied, options) {
+    const { fix, shouldFix, scope } = options;
+    const requirementsPath = resolveGsdRootFile(basePath, "REQUIREMENTS");
+    const requirementsContent = await loadFile(requirementsPath);
+    issues.push(...auditRequirements(requirementsContent));
+    const state = await deriveState(basePath);
+    // Provider / auth health checks — only relevant when there is active work to dispatch.
+    // Skipped for idle projects (no active milestone) to avoid noise in environments
+    // where CI/test runners have no API key configured.
+    if (state.activeMilestone) {
+        try {
+            const providerResults = runProviderChecks();
+            for (const result of providerResults) {
+                if (!result.required)
+                    continue;
+                if (result.status === "error") {
+                    issues.push({
+                        severity: "warning",
+                        code: "provider_key_missing",
+                        scope: "project",
+                        unitId: "project",
+                        message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+                        fixable: false,
+                    });
+                }
+                else if (result.status === "warning") {
+                    issues.push({
+                        severity: "warning",
+                        code: "provider_key_backedoff",
+                        scope: "project",
+                        unitId: "project",
+                        message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+                        fixable: false,
+                    });
+                }
+            }
+        }
+        catch {
+            // Non-fatal — provider check failure should not block other checks
+        }
+    }
+    // When DB is unavailable, state.registry is empty. Fall back to a direct
+    // filesystem scan so the doctor can still report issues (e.g. missing ROADMAP)
+    // for milestone dirs that exist on disk.
+    const milestoneEntries = state.registry.length > 0
+        ? state.registry
+        : findMilestoneIds(basePath).map(id => ({ id, title: id }));
+    for (const milestone of milestoneEntries) {
+        const milestoneId = milestone.id;
+        const milestonePath = resolveMilestonePath(basePath, milestoneId);
+        if (!milestonePath)
+            continue;
+        // Validate milestone title for delimiter characters that break state documents.
+        const milestoneTitleIssue = validateTitle(milestone.title);
+        if (milestoneTitleIssue) {
+            const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+            let wasFixed = false;
+            if (shouldFix("delimiter_in_title") && roadmapFile) {
+                try {
+                    const raw = readFileSync(roadmapFile, "utf-8");
+                    // Replace em/en dashes with " - " in the H1 title line only
+                    const sanitized = raw.replace(/^(# .*)$/m, (line) => line.replace(/[\u2014\u2013]/g, "-"));
+                    if (sanitized !== raw) {
+                        await saveFile(roadmapFile, sanitized);
+                        fixesApplied.push(`sanitized delimiter characters in ${milestoneId} title`);
+                        wasFixed = true;
+                    }
+                }
+                catch { /* non-fatal — report the warning below */ }
+            }
+            if (!wasFixed) {
+                issues.push({
+                    severity: "warning",
+                    code: "delimiter_in_title",
+                    scope: "milestone",
+                    unitId: milestoneId,
+                    message: `Milestone ${milestoneId} ${milestoneTitleIssue}. Rename the milestone to remove these characters to prevent state corruption.`,
+                    file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+                    fixable: true,
+                });
+            }
+        }
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+        if (!roadmapContent) {
+            issues.push({
+                severity: "error",
+                code: "missing_roadmap",
+                scope: "milestone",
+                unitId: milestoneId,
+                message: `Milestone ${milestoneId} is missing its ROADMAP.md file.`,
+                fixable: false,
+            });
+            continue;
+        }
+        let slices;
+        if (isDbAvailable()) {
+            const dbSlices = getMilestoneSlices(milestoneId);
+            slices = dbSlices.map(s => ({
+                id: s.id,
+                title: s.title,
+                done: isClosedStatus(s.status),
+                pending: s.status === "pending",
+                skipped: s.status === "skipped",
+                risk: (s.risk || "medium"),
+                depends: s.depends,
+                demo: s.demo,
+            }));
+        }
+        else {
+            const activeMilestoneId = state.activeMilestone?.id;
+            const activeSliceId = state.activeSlice?.id;
+            slices = parseLegacyRoadmap(roadmapContent).slices.map(s => ({
+                ...s,
+                // Legacy roadmaps only encode done vs not-done. For doctor's
+                // missing-directory checks, treat every undone slice except the
+                // current active slice as effectively pending/unstarted.
+                pending: !s.done && (milestoneId !== activeMilestoneId || s.id !== activeSliceId),
+            }));
+        }
+        // Wrap in Roadmap-compatible shape for detectCircularDependencies
+        const roadmap = { slices };
+        // ── Circular dependency detection ──────────────────────────────────────
+        for (const cycle of detectCircularDependencies(roadmap.slices)) {
+            issues.push({
+                severity: "error",
+                code: "circular_slice_dependency",
+                scope: "milestone",
+                unitId: milestoneId,
+                message: `Circular dependency detected: ${cycle.join(" → ")}`,
+                file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+                fixable: false,
+            });
+        }
+        // ── Orphaned slice directories ─────────────────────────────────────────
+        try {
+            const slicesDir = join(milestonePath, "slices");
+            if (existsSync(slicesDir)) {
+                const knownSliceIds = new Set(roadmap.slices.map(s => s.id));
+                for (const entry of readdirSync(slicesDir)) {
+                    try {
+                        if (!lstatSync(join(slicesDir, entry)).isDirectory())
+                            continue;
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (entry === "parallel-research")
+                        continue;
+                    if (!knownSliceIds.has(entry)) {
+                        const quarantineExample = `.gsd/quarantine/milestones/${milestoneId}/slices/${entry}-manual-review`;
+                        issues.push({
+                            severity: "warning",
+                            code: "orphaned_slice_directory",
+                            scope: "milestone",
+                            unitId: milestoneId,
+                            message: `Directory "${entry}" exists in ${milestoneId}/slices/ but is not referenced in the roadmap or DB. ` +
+                                `Review it; if stale, move or delete it. To preserve it, move it under ${quarantineExample}. ` +
+                                "If it contains work to keep, copy or merge that content into a DB-backed slice before resuming.",
+                            file: `${relMilestonePath(basePath, milestoneId)}/slices/${entry}`,
+                            fixable: false,
+                        });
+                    }
+                }
+            }
+        }
+        catch { /* non-fatal */ }
+        for (const slice of roadmap.slices) {
+            const unitId = `${milestoneId}/${slice.id}`;
+            if (scope && !matchesScope(unitId, scope) && scope !== milestoneId)
+                continue;
+            // Validate slice title for delimiter characters.
+            const sliceTitleIssue = validateTitle(slice.title);
+            if (sliceTitleIssue) {
+                // Slice titles live inside the roadmap H1/checkbox lines — the milestone-level
+                // fix above already sanitizes the roadmap file. For slices we only report, because
+                // the title comes from the checkbox text and requires careful regex to fix safely.
+                issues.push({
+                    severity: "warning",
+                    code: "delimiter_in_title",
+                    scope: "slice",
+                    unitId,
+                    message: `Slice ${unitId} ${sliceTitleIssue}. Rename the slice to remove these characters to prevent state corruption.`,
+                    file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+                    fixable: false,
+                });
+            }
+            // Check for unresolvable dependency IDs
+            const knownSliceIds = new Set(roadmap.slices.map(s => s.id));
+            for (const dep of slice.depends) {
+                if (!knownSliceIds.has(dep)) {
+                    issues.push({
+                        severity: "warning",
+                        code: "unresolvable_dependency",
+                        scope: "slice",
+                        unitId,
+                        message: `Slice ${unitId} depends on "${dep}" which is not a slice ID in this roadmap. This permanently blocks the slice. Use comma-separated IDs: \`depends:[S01,S02]\``,
+                        file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+                        fixable: false,
+                    });
+                }
+            }
+            const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
+            if (!slicePath) {
+                // Pending slices haven't been planned yet — directories are created
+                // lazily by ensurePreconditions() at dispatch time. Skipped slices are
+                // intentionally allowed to remain summary-less and directory-less.
+                if (slice.pending || slice.skipped)
+                    continue;
+                const expectedPath = relSlicePath(basePath, milestoneId, slice.id);
+                issues.push({
+                    severity: slice.done ? "warning" : "error",
+                    code: "missing_slice_dir",
+                    scope: "slice",
+                    unitId,
+                    message: slice.done
+                        ? `Missing slice directory for ${unitId} (slice is complete — cosmetic only)`
+                        : `Missing slice directory for ${unitId}`,
+                    file: expectedPath,
+                    fixable: true,
+                });
+                if (fix) {
+                    const absoluteSliceDir = join(milestonePath, "slices", slice.id);
+                    mkdirSync(absoluteSliceDir, { recursive: true });
+                    fixesApplied.push(`created ${absoluteSliceDir}`);
+                }
+                continue;
+            }
+            const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id);
+            if (!tasksDir) {
+                // Pending slices haven't been planned yet — tasks/ is created on demand.
+                // Skipped slices may legitimately never create tasks/.
+                if (slice.pending || slice.skipped)
+                    continue;
+                // Flat-phase: tasks are embedded in plan files; no tasks/ subdir expected.
+                if (!existsSync(legacyMilestonesDir(basePath)))
+                    continue;
+                issues.push({
+                    severity: slice.done ? "warning" : "error",
+                    code: "missing_tasks_dir",
+                    scope: "slice",
+                    unitId,
+                    message: slice.done
+                        ? `Missing tasks directory for ${unitId} (slice is complete \u2014 cosmetic only)`
+                        : `Missing tasks directory for ${unitId}`,
+                    file: relSlicePath(basePath, milestoneId, slice.id),
+                    fixable: true,
+                });
+                if (fix) {
+                    mkdirSync(join(slicePath, "tasks"), { recursive: true });
+                    fixesApplied.push(`created ${join(slicePath, "tasks")}`);
+                }
+            }
+            const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+            const planContent = planPath ? await loadFile(planPath) : null;
+            // Normalize plan tasks: prefer DB, fall back to parsers-legacy
+            let plan = null;
+            if (isDbAvailable()) {
+                const dbTasks = getSliceTasks(milestoneId, slice.id);
+                if (dbTasks.length > 0) {
+                    plan = { tasks: dbTasks.map(t => ({ id: t.id, done: t.status === "complete" || t.status === "done", title: t.title, estimate: t.estimate || undefined })) };
+                }
+            }
+            if (!plan && planContent) {
+                plan = parseLegacyPlan(planContent);
+            }
+            if (!plan) {
+                if (!slice.done) {
+                    issues.push({
+                        severity: "warning",
+                        code: "missing_slice_plan",
+                        scope: "slice",
+                        unitId,
+                        message: `Slice ${unitId} has no plan file`,
+                        file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"),
+                        fixable: false,
+                    });
+                }
+                continue;
+            }
+            // ── Duplicate task IDs ───────────────────────────────────────────────
+            const taskIdCounts = new Map();
+            for (const task of plan.tasks)
+                taskIdCounts.set(task.id, (taskIdCounts.get(task.id) ?? 0) + 1);
+            for (const [taskId, count] of taskIdCounts) {
+                if (count > 1) {
+                    issues.push({ severity: "error", code: "duplicate_task_id", scope: "slice", unitId,
+                        message: `Task ID "${taskId}" appears ${count} times in ${slice.id}-PLAN.md — duplicate IDs cause dispatch failures`,
+                        file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"), fixable: false });
+                }
+            }
+            // ── Task files on disk not in plan ────────────────────────────────────
+            try {
+                if (tasksDir) {
+                    const planTaskIds = new Set(plan.tasks.map(t => t.id));
+                    for (const f of readdirSync(tasksDir)) {
+                        if (!f.endsWith("-SUMMARY.md"))
+                            continue;
+                        const diskTaskId = f.replace(/-SUMMARY\.md$/, "");
+                        if (!planTaskIds.has(diskTaskId)) {
+                            issues.push({ severity: "info", code: "task_file_not_in_plan", scope: "slice", unitId,
+                                message: `Task summary "${f}" exists on disk but "${diskTaskId}" is not in ${slice.id}-PLAN.md`,
+                                file: relTaskFile(basePath, milestoneId, slice.id, diskTaskId, "SUMMARY"), fixable: false });
+                        }
+                    }
+                }
+            }
+            catch { /* non-fatal */ }
+            let allTasksDone = plan.tasks.length > 0;
+            for (const task of plan.tasks) {
+                const taskUnitId = `${unitId}/${task.id}`;
+                const summaryPath = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY");
+                const hasSummary = !!(summaryPath && await loadFile(summaryPath));
+                // Must-have verification
+                if (task.done && hasSummary) {
+                    const taskPlanPath = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "PLAN");
+                    if (taskPlanPath) {
+                        const taskPlanContent = await loadFile(taskPlanPath);
+                        if (taskPlanContent) {
+                            const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+                            if (mustHaves.length > 0) {
+                                const summaryContent = await loadFile(summaryPath);
+                                const mentionedCount = summaryContent
+                                    ? countMustHavesMentionedInSummary(mustHaves, summaryContent)
+                                    : 0;
+                                if (mentionedCount < mustHaves.length) {
+                                    issues.push({
+                                        severity: "warning",
+                                        code: "task_done_must_haves_not_verified",
+                                        scope: "task",
+                                        unitId: taskUnitId,
+                                        message: `Task ${task.id} has ${mustHaves.length} must-haves but summary addresses only ${mentionedCount}`,
+                                        file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"),
+                                        fixable: false,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // ── Future timestamp check ─────────────────────────────────────
+                if (task.done && hasSummary && summaryPath) {
+                    try {
+                        const rawSummary = await loadFile(summaryPath);
+                        const m = rawSummary?.match(/^completed_at:\s*(.+)$/m);
+                        if (m) {
+                            const ts = new Date(m[1].trim());
+                            if (!isNaN(ts.getTime()) && ts.getTime() > Date.now() + 24 * 60 * 60 * 1000) {
+                                issues.push({ severity: "warning", code: "future_timestamp", scope: "task", unitId: taskUnitId,
+                                    message: `Task ${task.id} has completed_at "${m[1].trim()}" which is more than 24h in the future`,
+                                    file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"), fixable: false });
+                            }
+                        }
+                    }
+                    catch { /* non-fatal */ }
+                }
+                allTasksDone = allTasksDone && task.done;
+            }
+            // Blocker-without-replan detection
+            // Skip when all tasks are done — the blocker was implicitly resolved
+            // within the task and the slice is not stuck (#3105 Bug 2).
+            const replanPath = resolveSliceFile(basePath, milestoneId, slice.id, "REPLAN");
+            if (!replanPath && !allTasksDone) {
+                for (const task of plan.tasks) {
+                    if (!task.done)
+                        continue;
+                    const summaryPath = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY");
+                    if (!summaryPath)
+                        continue;
+                    const summaryContent = await loadFile(summaryPath);
+                    if (!summaryContent)
+                        continue;
+                    const summary = parseSummary(summaryContent);
+                    if (summary.frontmatter.blocker_discovered) {
+                        issues.push({
+                            severity: "warning",
+                            code: "blocker_discovered_no_replan",
+                            scope: "slice",
+                            unitId,
+                            message: `Task ${task.id} reported blocker_discovered but no REPLAN.md exists for ${slice.id} \u2014 slice may be stuck`,
+                            file: relSliceFile(basePath, milestoneId, slice.id, "REPLAN"),
+                            fixable: false,
+                        });
+                        break;
+                    }
+                }
+            }
+            // ── Stale REPLAN: exists but all tasks done ────────────────────────
+            if (replanPath && allTasksDone) {
+                issues.push({ severity: "info", code: "stale_replan_file", scope: "slice", unitId,
+                    message: `${slice.id} has a REPLAN.md but all tasks are done — REPLAN.md may be stale`,
+                    file: relSliceFile(basePath, milestoneId, slice.id, "REPLAN"), fixable: false });
+            }
+        }
+        // Milestone-level check: all slices done but no validation file
+        const milestoneComplete = roadmap.slices.length > 0 && roadmap.slices.every(s => s.done);
+        if (milestoneComplete && !resolveMilestoneFile(basePath, milestoneId, "VALIDATION") && !resolveMilestoneFile(basePath, milestoneId, "SUMMARY")) {
+            issues.push({
+                severity: "info",
+                code: "all_slices_done_missing_milestone_validation",
+                scope: "milestone",
+                unitId: milestoneId,
+                message: `All slices are done but the milestone VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
+                file: relMilestoneFile(basePath, milestoneId, "VALIDATION"),
+                fixable: false,
+            });
+        }
+        // Milestone-level check: all slices done but no milestone summary
+        if (milestoneComplete && !resolveMilestoneFile(basePath, milestoneId, "SUMMARY")) {
+            issues.push({
+                severity: "warning",
+                code: "all_slices_done_missing_milestone_summary",
+                scope: "milestone",
+                unitId: milestoneId,
+                message: `All slices are done but ${milestoneId}-SUMMARY.md is missing \u2014 milestone is stuck in completing-milestone phase`,
+                file: relMilestoneFile(basePath, milestoneId, "SUMMARY"),
+                fixable: false,
+            });
+        }
+    }
+}