gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -1031,6 +1031,29 @@ export function validatePreferences(preferences) {
         if (g.merge_to_main !== undefined) {
             warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
         }
+        // #4765 — collapse cadence + milestone resquash
+        if (g.collapse_cadence !== undefined) {
+            const validCadence = new Set(["milestone", "slice"]);
+            if (typeof g.collapse_cadence === "string" && validCadence.has(g.collapse_cadence)) {
+                git.collapse_cadence = g.collapse_cadence;
+            }
+            else {
+                errors.push("git.collapse_cadence must be one of: milestone, slice");
+            }
+        }
+        if (g.milestone_resquash !== undefined) {
+            if (typeof g.milestone_resquash === "boolean") {
+                git.milestone_resquash = g.milestone_resquash;
+                const cadence = git.collapse_cadence
+                    ?? (typeof g.collapse_cadence === "string" ? g.collapse_cadence : undefined);
+                if (cadence !== "slice") {
+                    warnings.push('git.milestone_resquash is ignored unless git.collapse_cadence is "slice"');
+                }
+            }
+            else {
+                errors.push("git.milestone_resquash must be a boolean");
+            }
+        }
         if (Object.keys(git).length > 0) {
             validated.git = git;
         }

package/dist/resources/extensions/gsd/prompt-cache-optimizer.js

@@ -24,6 +24,10 @@ const SEMI_STATIC_LABELS = new Set([
     "prior-summaries",
     "project-context",
     "overrides",
+    // KNOWLEDGE is milestone-scoped (stable within a session), so it belongs
+    // in the cacheable prefix. See issue #4719.
+    "knowledge",
+    "project-knowledge",
 ]);
 /** Labels that change per-task */
 const DYNAMIC_LABELS = new Set([

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -164,9 +164,18 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 
 ### Ready-phrase pre-condition (NON-BYPASSABLE)
 
-Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `{{contextPath}}`, and called `gsd_plan_milestone`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -240,9 +249,19 @@ For single-milestone projects, do NOT write this file.
 
 ### Ready-phrase pre-condition (NON-BYPASSABLE)
 
-Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, the primary `CONTEXT.md`, called `gsd_plan_milestone` for the primary milestone, and written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md`
+- [ ] Written `.gsd/REQUIREMENTS.md`
+- [ ] Written the primary milestone `CONTEXT.md`
+- [ ] Called `gsd_plan_milestone` for the primary milestone
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+After completing every step above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules
 

package/dist/resources/extensions/gsd/prompts/doctor-heal.md

@@ -7,9 +7,10 @@ Rules:
 2. Read before edit.
 3. Prefer fixing authoritative artifacts over masking warnings.
 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
-5. After each repair cluster, verify the relevant invariant directly from disk.
-6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
-7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
+5. For a missing milestone `CONTEXT.md` when the milestone is already past `pre-planning` (phase is `executing`, `summarizing`, `validating-milestone`, or `completing-milestone`): the artifact was skipped during bootstrap and must be reconstructed before execution can resume. Read `PROJECT.md`, `REQUIREMENTS.md`, the milestone's `ROADMAP.md`, and any slice-level context on disk, then write `.gsd/milestones/<milestone-id>/<milestone-id>-CONTEXT.md` with the real context for the scoped milestone. Do not leave a stub — the plan gate will reject it on the next cycle.
+6. After each repair cluster, verify the relevant invariant directly from disk.
+7. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+8. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
 
 ## Doctor Summary
 
@@ -27,4 +28,4 @@ Then:
 - Repair the unresolved issues in scope
 - Keep changes minimal and targeted
 - If unresolved issues remain outside scope, leave them untouched and mention them briefly
-- End with: "GSD doctor heal complete."
+- End with: "GSD doctor heal complete."

package/dist/resources/extensions/gsd/reports.js

@@ -13,8 +13,9 @@
  * Auto-triggered: after each milestone completion (when auto_report: true).
  * Manual: /gsd export --html
  */
-import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { atomicWriteSync } from './atomic-write.js';
 import { gsdRoot } from './paths.js';
 import { formatCost, formatTokenCount } from './metrics.js';
 import { formatDateShort, formatDuration } from '../shared/format-utils.js';
@@ -43,7 +44,7 @@ export function loadReportsIndex(basePath) {
 function saveReportsIndex(basePath, index) {
     const dir = reportsDir(basePath);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
+    atomicWriteSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
 }
 /**
  * Write a report snapshot to .gsd/reports/, update reports.json, regenerate index.html.
@@ -56,7 +57,7 @@ export function writeReportSnapshot(args) {
     const prefix = args.milestoneId === 'final' ? 'final' : args.milestoneId;
     const filename = `${prefix}-${timestamp}.html`;
     const filePath = join(dir, filename);
-    writeFileSync(filePath, args.html, 'utf-8');
+    atomicWriteSync(filePath, args.html, 'utf-8');
     // Load or init registry
     const existing = loadReportsIndex(args.basePath);
     const index = existing ?? {
@@ -97,7 +98,7 @@ export function writeReportSnapshot(args) {
 // ─── HTML Index Generator ─────────────────────────────────────────────────────
 export function regenerateHtmlIndex(basePath, index) {
     const html = buildIndexHtml(index);
-    writeFileSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
+    atomicWriteSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
 }
 function buildIndexHtml(index) {
     const { projectName, projectPath, gsdVersion, entries } = index;

package/dist/resources/extensions/gsd/slice-cadence.js

@@ -0,0 +1,238 @@
+/**
+ * Slice-cadence collapse — #4765.
+ *
+ * When `git.collapse_cadence: "slice"` is set, each slice's commits are
+ * squash-merged from the milestone branch to main as soon as the slice
+ * passes validation. Shrinks the orphan window (#4761) from milestone-size
+ * to slice-size and surfaces merge conflicts per-slice rather than all at
+ * once at milestone end.
+ *
+ * This module is deliberately focused and narrower than mergeMilestoneToMain:
+ *   - No worktree teardown (worktree is reused for the next slice)
+ *   - No DB reconciliation (modern worktrees share the main DB via path resolver)
+ *   - No roadmap/summary/gate handling (that's still the milestone's job)
+ *   - Fails loudly on dirty main — caller is responsible for cleanliness
+ *
+ * Kernighan: the v1 surface handles the happy path + conflict. Edge cases
+ * that mergeMilestoneToMain covers (concurrent merges, shared DB paths,
+ * submodules) are explicit non-goals; users opt in via preference and early-
+ * adopter scenarios are scoped narrow.
+ */
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { MergeConflictError } from "./git-service.js";
+import { nativeBranchForceReset, nativeCheckoutBranch, nativeCommit, nativeCommitCountBetween, nativeConflictFiles, nativeDetectMainBranch, nativeMergeSquash, } from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+import { logWarning } from "./workflow-logger.js";
+import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
+/**
+ * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
+ * auto-worktree.ts; duplicated here to avoid a cyclic import.
+ */
+function milestoneBranchName(milestoneId) {
+    return `milestone/${milestoneId}`;
+}
+function cleanupMergeArtifacts(projectRoot) {
+    try {
+        const gitDir = resolveGitDir(projectRoot);
+        for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+            const p = join(gitDir, f);
+            if (existsSync(p))
+                unlinkSync(p);
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `merge artifact cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Squash-merge one slice's commits from the milestone branch to main.
+ *
+ * Preconditions:
+ *   - Caller is on the milestone branch inside the worktree
+ *   - `projectRoot` points at the real project root (not the worktree)
+ *
+ * Post-conditions on success:
+ *   - Slice's commits are a single squash commit on main
+ *   - `milestone/<MID>` is fast-forwarded to main (so next slice's work
+ *     starts from a clean base)
+ *   - caller's process.cwd is restored
+ *
+ * Throws MergeConflictError on conflicts; caller should surface and stop.
+ * Throws GSDError on dirty main / detection failures.
+ */
+export function mergeSliceToMain(projectRoot, milestoneId, sliceId) {
+    const started = Date.now();
+    const worktreeCwd = process.cwd();
+    const milestoneBranch = milestoneBranchName(milestoneId);
+    const mainBranch = nativeDetectMainBranch(projectRoot);
+    // Fast path: if the milestone branch has no commits ahead of main, there
+    // is nothing to merge. Return a skip result instead of no-op'ing silently
+    // so the caller's telemetry shows the decision.
+    let commitsAhead = 0;
+    try {
+        commitsAhead = nativeCommitCountBetween(projectRoot, mainBranch, milestoneBranch);
+    }
+    catch {
+        // If we can't count, assume there's work and let the merge proceed —
+        // a failing merge is more informative than a silent skip.
+        commitsAhead = 1;
+    }
+    if (commitsAhead === 0) {
+        // Do NOT emit slice-merged here — this is a no-op, not a merge. Emitting
+        // would inflate slicesMerged in telemetry/forensics and distort the
+        // conflict rate denominator.
+        return {
+            commitSha: null,
+            mainBranch,
+            milestoneBranch,
+            durationMs: Date.now() - started,
+            skipped: true,
+            skippedReason: "no-commits-ahead",
+        };
+    }
+    process.chdir(projectRoot);
+    try {
+        // Dirty-main check — v1 fails loudly rather than auto-stashing. Users
+        // running slice-cadence opt in knowing main stays clean between merges.
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd: projectRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        if (status) {
+            throw new GSDError(GSD_GIT_ERROR, `slice-cadence merge requires a clean project root; uncommitted changes detected. ` +
+                `Commit or stash at ${projectRoot} before retrying. Status:\n${status}`);
+        }
+        nativeCheckoutBranch(projectRoot, mainBranch);
+        // Clean any stale merge artifacts before attempting the squash (#2912 pattern)
+        cleanupMergeArtifacts(projectRoot);
+        const mergeResult = nativeMergeSquash(projectRoot, milestoneBranch);
+        if (!mergeResult.success) {
+            const conflictedFiles = mergeResult.conflicts.length > 0
+                ? mergeResult.conflicts
+                : nativeConflictFiles(projectRoot);
+            cleanupMergeArtifacts(projectRoot);
+            try {
+                emitSliceMerged(projectRoot, milestoneId, sliceId, {
+                    durationMs: Date.now() - started,
+                    conflict: true,
+                });
+            }
+            catch { /* silent */ }
+            throw new MergeConflictError(conflictedFiles, "squash", milestoneBranch, mainBranch);
+        }
+        // Commit the squash with a slice-scoped message
+        const commitSha = nativeCommit(projectRoot, `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`);
+        // Advance the milestone branch to main so the next slice's commits start
+        // from a clean base. Force-reset is safe because we just merged this
+        // branch's entire delta.
+        nativeBranchForceReset(projectRoot, milestoneBranch, mainBranch);
+        const durationMs = Date.now() - started;
+        try {
+            emitSliceMerged(projectRoot, milestoneId, sliceId, {
+                durationMs,
+                conflict: false,
+                commitSha: commitSha ?? undefined,
+            });
+        }
+        catch { /* silent */ }
+        return {
+            commitSha,
+            mainBranch,
+            milestoneBranch,
+            durationMs,
+            skipped: false,
+        };
+    }
+    finally {
+        // Always restore cwd even if anything above threw.
+        try {
+            process.chdir(worktreeCwd);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * Re-squash per-slice commits on main into a single milestone commit.
+ *
+ * Runs at milestone completion when `collapse_cadence: "slice"` AND
+ * `milestone_resquash: true`. The `startSha` is the SHA of main immediately
+ * before the milestone's first slice merge — the caller is responsible for
+ * recording this (AutoSession field, git ref, or DB row).
+ *
+ * Strategy: soft-reset main to startSha, then commit the net diff. The
+ * N slice commits between startSha and HEAD are collapsed into one.
+ *
+ * No-op (returns false) if startSha equals HEAD (nothing to re-squash).
+ */
+export function resquashMilestoneOnMain(projectRoot, milestoneId, startSha) {
+    const mainBranch = nativeDetectMainBranch(projectRoot);
+    const worktreeCwd = process.cwd();
+    process.chdir(projectRoot);
+    try {
+        nativeCheckoutBranch(projectRoot, mainBranch);
+        // Verify the startSha..HEAD range contains ONLY this milestone's slice-
+        // cadence commits. If any unrelated commits landed on main since the
+        // milestone started (e.g. concurrent work, cherry-picks, hotfixes), a
+        // blind `git reset --soft` would fold them into the re-squash and rewrite
+        // their attribution. Fail closed — the user can resolve manually.
+        const expectedSuffix = `(slice-cadence)`;
+        const expectedMilestoneToken = ` of ${milestoneId} `;
+        let subjectsRaw = "";
+        try {
+            subjectsRaw = execFileSync("git", ["log", "--format=%s", `${startSha}..HEAD`], { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+        }
+        catch {
+            return { resquashed: false, newSha: null };
+        }
+        const subjects = subjectsRaw.split("\n").filter((s) => s.length > 0);
+        const sliceCount = subjects.length;
+        if (sliceCount === 0) {
+            return { resquashed: false, newSha: null };
+        }
+        const foreign = subjects.filter((s) => !(s.endsWith(expectedSuffix) && s.includes(expectedMilestoneToken)));
+        if (foreign.length > 0) {
+            logWarning("worktree", `slice-cadence: skipping milestone resquash for ${milestoneId} — ` +
+                `${foreign.length} non-slice-cadence commit(s) in ${startSha}..HEAD ` +
+                `would be folded in. First: "${foreign[0]}". Resolve history manually.`);
+            return { resquashed: false, newSha: null };
+        }
+        // Safe to collapse: all commits in the range are this milestone's slices.
+        execFileSync("git", ["reset", "--soft", startSha], {
+            cwd: projectRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        const newSha = nativeCommit(projectRoot, `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`, { allowEmpty: true });
+        try {
+            emitMilestoneResquash(projectRoot, milestoneId, {
+                sliceCount,
+                startSha,
+                endSha: newSha ?? undefined,
+            });
+        }
+        catch { /* silent */ }
+        return { resquashed: true, newSha };
+    }
+    finally {
+        try {
+            process.chdir(worktreeCwd);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * Read the effective collapse cadence from validated preferences. Accepts
+ * a raw preferences object (the shape loadEffectiveGSDPreferences returns).
+ */
+export function getCollapseCadence(prefs) {
+    return prefs?.git?.collapse_cadence ?? "milestone";
+}
+export function getMilestoneResquash(prefs) {
+    // Default true when cadence is slice — resquash preserves the milestone-
+    // level history shape users expect.
+    return prefs?.git?.milestone_resquash !== false;
+}

package/dist/resources/extensions/gsd/state-transition-matrix.js

@@ -0,0 +1,118 @@
+export const STATE_TRANSITION_MATRIX = [
+    {
+        from: "needs-discussion",
+        event: "context-ready",
+        guard: "CONTEXT artifact exists or PRD/context express path produced context",
+        to: "researching",
+        onFail: "needs-discussion",
+        reasonCode: "state",
+    },
+    {
+        from: "researching",
+        event: "research-ready",
+        guard: "RESEARCH artifact exists or research is explicitly skipped",
+        to: "planning",
+        onFail: "researching",
+        reasonCode: "state",
+    },
+    {
+        from: "planning",
+        event: "plan-ready",
+        guard: "ROADMAP/PLAN artifacts exist and plan gate passes",
+        to: "executing",
+        onFail: "replanning-slice",
+        reasonCode: "state",
+    },
+    {
+        from: "executing",
+        event: "task-dispatched",
+        guard: "task inputs are ready and dependencies are closed",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "dependency",
+    },
+    {
+        from: "executing",
+        event: "slice-complete",
+        guard: "all slice tasks are closed and verification gate passes",
+        to: "summarizing",
+        onFail: "validating-milestone",
+        reasonCode: "state",
+    },
+    {
+        from: "summarizing",
+        event: "summary-ready",
+        guard: "SUMMARY artifact exists for the completed work unit",
+        to: "validating-milestone",
+        onFail: "summarizing",
+        reasonCode: "state",
+    },
+    {
+        from: "validating-milestone",
+        event: "validation-pass",
+        guard: "validation verdict is terminal and not remediation-required",
+        to: "completing-milestone",
+        onFail: "blocked",
+        reasonCode: "state",
+    },
+    {
+        from: "blocked",
+        event: "recovery-plan-ready",
+        guard: "reassessment produced an executable next action",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "recovery",
+    },
+    {
+        from: "replanning-slice",
+        event: "replan-ready",
+        guard: "replacement slice/task plan exists and plan gate passes",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "recovery",
+    },
+    {
+        from: "completing-milestone",
+        event: "closeout-complete",
+        guard: "closeout gate passes and git transaction succeeds",
+        to: "complete",
+        onFail: "blocked",
+        reasonCode: "state",
+    },
+    {
+        from: "*",
+        event: "manual-block",
+        guard: "operator or hard gate requested manual attention",
+        to: "blocked",
+        onFail: "manual-attention",
+        reasonCode: "manual",
+    },
+    {
+        from: "*",
+        event: "retryable-failure",
+        guard: "retry budget remains for failure class",
+        to: "executing",
+        onFail: "blocked",
+        reasonCode: "retry",
+    },
+];
+export function findTransition(from, event) {
+    return STATE_TRANSITION_MATRIX.find((entry) => (entry.from === from || entry.from === "*") && entry.event === event);
+}
+export function validateTransitionMatrix(requiredEvents) {
+    const seen = new Set();
+    const duplicateKeys = [];
+    for (const entry of STATE_TRANSITION_MATRIX) {
+        const key = `${entry.from}:${entry.event}`;
+        if (seen.has(key))
+            duplicateKeys.push(key);
+        seen.add(key);
+    }
+    const availableEvents = new Set(STATE_TRANSITION_MATRIX.map((entry) => entry.event));
+    const missingEvents = requiredEvents.filter((event) => !availableEvents.has(event));
+    return {
+        ok: missingEvents.length === 0 && duplicateKeys.length === 0,
+        missingEvents,
+        duplicateKeys,
+    };
+}

package/dist/resources/extensions/gsd/state.js

@@ -15,6 +15,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { loadEffectiveGSDPreferences } from './preferences.js';
 import { detectPendingEscalation } from './escalation.js';
+import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
 import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, insertSlice, insertTask, updateSliceStatus, updateTaskStatus, getPendingGateCountForTurn, autoHealSketchFlags, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
@@ -81,6 +82,10 @@ export function isMilestoneComplete(roadmap) {
 export function isValidationTerminal(validationContent) {
     return extractVerdict(validationContent) != null;
 }
+async function isTerminalMilestoneSummaryFile(path, loader) {
+    const content = await loader(path);
+    return content != null && isTerminalMilestoneSummaryContent(content);
+}
 const CACHE_TTL_MS = 100;
 let _stateCache = null;
 // ── Telemetry counters for derive-path observability ────────────────────────
@@ -138,18 +143,19 @@ export async function getActiveMilestoneId(basePath) {
         const content = roadmapFile ? await loadFile(roadmapFile) : null;
         if (!content) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile)
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
                 continue;
             if (isGhostMilestone(basePath, mid))
                 continue;
             return mid;
         }
         const roadmap = parseRoadmap(content);
-        if (!isMilestoneComplete(roadmap)) {
-            const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (!summaryFile)
-                return mid;
-        }
+        const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+        if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile))
+            continue;
+        if (!isMilestoneComplete(roadmap))
+            return mid;
+        return mid;
     }
     return null;
 }
@@ -550,7 +556,6 @@ function resolveSliceDependencies(activeMilestoneSlices) {
             return { activeSlice: null, activeSliceRow: null };
         }
     }
-    // First pass: find a slice with ALL dependencies satisfied (strict)
     let bestFallback = null;
     let bestFallbackSatisfied = -1;
     for (const s of activeMilestoneSlices) {
@@ -561,17 +566,12 @@ function resolveSliceDependencies(activeMilestoneSlices) {
         if (s.depends.every(dep => doneSliceIds.has(dep))) {
             return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s };
         }
-        // Track the slice with the most satisfied dependencies as fallback
         const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
         if (satisfied > bestFallbackSatisfied || (satisfied === bestFallbackSatisfied && !bestFallback)) {
             bestFallback = s;
             bestFallbackSatisfied = satisfied;
         }
     }
-    // Fallback: if no slice has all deps met but there ARE incomplete non-deferred
-    // slices, pick the one with the most deps satisfied. This prevents hard-blocking
-    // when dependency metadata is stale (e.g. after reassessment added/removed slices)
-    // or when deps reference slices from previous milestones.
     if (bestFallback) {
         const unmet = bestFallback.depends.filter(dep => !doneSliceIds.has(dep));
         logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallback.id} ` +
@@ -988,7 +988,7 @@ export async function _deriveStateImpl(basePath) {
         const rc = rf ? await cachedLoadFile(rf) : null;
         if (!rc) {
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
@@ -998,12 +998,12 @@ export async function _deriveStateImpl(basePath) {
             // Summary is the terminal artifact — if it exists, the milestone is
             // complete even when roadmap checkboxes weren't ticked (#864).
             const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (sf)
+            if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
                 completeMilestoneIds.add(mid);
             continue;
         }
         const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-        if (sf)
+        if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile))
             completeMilestoneIds.add(mid);
     }
     // Phase 2: Build registry using cached roadmaps (no re-parsing or re-reading)
@@ -1028,12 +1028,14 @@ export async function _deriveStateImpl(basePath) {
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
             if (summaryFile) {
                 const summaryContent = await cachedLoadFile(summaryFile);
-                const summaryTitle = summaryContent
-                    ? (parseSummary(summaryContent).title || mid)
-                    : mid;
-                registry.push({ id: mid, title: summaryTitle, status: 'complete' });
-                completeMilestoneIds.add(mid);
-                continue;
+                if (summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent)) {
+                    const summaryTitle = summaryContent
+                        ? (parseSummary(summaryContent).title || mid)
+                        : mid;
+                    registry.push({ id: mid, title: summaryTitle, status: 'complete' });
+                    completeMilestoneIds.add(mid);
+                    continue;
+                }
             }
             // Ghost milestone (only META.json, no CONTEXT/ROADMAP/SUMMARY) — skip entirely
             if (isGhostMilestone(basePath, mid))
@@ -1087,7 +1089,7 @@ export async function _deriveStateImpl(basePath) {
             const verdict = validationContent ? extractVerdict(validationContent) : undefined;
             // needs-remediation is terminal but requires re-validation (#3596)
             const needsRevalidation = !validationTerminal || verdict === 'needs-remediation';
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 // Summary exists → milestone is complete regardless of validation state.
                 // The summary is the terminal artifact (#864).
                 registry.push({ id: mid, title, status: 'complete' });
@@ -1118,7 +1120,7 @@ export async function _deriveStateImpl(basePath) {
             // Roadmap slices not all checked — but if a summary exists, the milestone
             // is still complete. The summary is the terminal artifact (#864).
             const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-            if (summaryFile) {
+            if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
                 registry.push({ id: mid, title, status: 'complete' });
             }
             else if (!activeMilestoneFound) {
@@ -1396,14 +1398,12 @@ export async function _deriveStateImpl(basePath) {
                 activeSlice = { id: s.id, title: s.title };
                 break;
             }
-            // Track best fallback
             const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
             if (satisfied > bestFallbackLegacySatisfied) {
                 bestFallbackLegacy = s;
                 bestFallbackLegacySatisfied = satisfied;
             }
         }
-        // Fallback: if no slice has all deps met, pick the one with the most deps satisfied
         if (!activeSlice && bestFallbackLegacy) {
             const unmet = bestFallbackLegacy.depends.filter(dep => !doneSliceIds.has(dep));
             logWarning("state", `No slice has all deps satisfied — falling back to ${bestFallbackLegacy.id} ` +