gsd-pi 2.35.0 → 2.36.0-dev.f887f4e

package/dist/resources/extensions/gsd/health-widget.js

@@ -11,21 +11,23 @@ import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.j
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
+import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands.js";
+import { deriveState, invalidateStateCache } from "./state.js";
+import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
 // ── Data loader ────────────────────────────────────────────────────────────────
-function loadHealthWidgetData(basePath) {
-    let hasProject = false;
+function loadBaseHealthWidgetData(basePath) {
     let budgetCeiling;
     let budgetSpent = 0;
     let providerIssue = null;
     let environmentErrorCount = 0;
     let environmentWarningCount = 0;
+    const projectState = detectHealthWidgetProjectState(basePath);
     try {
         const prefs = loadEffectiveGSDPreferences();
         budgetCeiling = prefs?.preferences?.budget_ceiling;
         const ledger = loadLedgerFromDisk(basePath);
         if (ledger) {
-            hasProject = true;
             const totals = getProjectTotals(ledger.units ?? []);
             budgetSpent = totals.cost;
         }
@@ -47,7 +49,7 @@ function loadHealthWidgetData(basePath) {
     }
     catch { /* non-fatal */ }
     return {
-        hasProject,
+        projectState,
         budgetCeiling,
         budgetSpent,
         providerIssue,
@@ -56,50 +58,85 @@ function loadHealthWidgetData(basePath) {
         lastRefreshed: Date.now(),
     };
 }
-// ── Rendering ──────────────────────────────────────────────────────────────────
-function formatCost(n) {
-    return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+function compactText(text, max = 64) {
+    const trimmed = text.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, max - 1).trimEnd()}…`;
 }
-/**
- * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
- */
-export function buildHealthLines(data) {
-    if (!data.hasProject) {
-        return ["  GSD  No project loaded — run /gsd to start"];
-    }
-    const parts = [];
-    // System status signal
-    const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
-    if (totalIssues === 0) {
-        parts.push("● System OK");
-    }
-    else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-        parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
-    }
-    else {
-        parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+function summarizeExecutionStatus(state) {
+    switch (state.phase) {
+        case "blocked": return "Blocked";
+        case "paused": return "Paused";
+        case "complete": return "Complete";
+        case "executing": return "Executing";
+        case "planning": return "Planning";
+        case "pre-planning": return "Pre-planning";
+        case "summarizing": return "Summarizing";
+        case "validating-milestone": return "Validating";
+        case "completing-milestone": return "Completing";
+        case "needs-discussion": return "Needs discussion";
+        case "replanning-slice": return "Replanning";
+        default: return "Active";
     }
-    // Budget
-    if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
-        const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-        parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
-    }
-    else if (data.budgetSpent > 0) {
-        parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
-    }
-    // Provider issue (if any)
-    if (data.providerIssue) {
-        parts.push(data.providerIssue);
+}
+function summarizeExecutionTarget(state) {
+    switch (state.phase) {
+        case "needs-discussion":
+            return state.activeMilestone ? `Discuss ${state.activeMilestone.id}` : "Discuss milestone draft";
+        case "pre-planning":
+            return state.activeMilestone ? `Plan ${state.activeMilestone.id}` : "Research & plan milestone";
+        case "planning":
+            return state.activeSlice ? `Plan ${state.activeSlice.id}` : "Plan next slice";
+        case "executing":
+            return state.activeTask ? `Execute ${state.activeTask.id}` : "Execute next task";
+        case "summarizing":
+            return state.activeSlice ? `Complete ${state.activeSlice.id}` : "Complete current slice";
+        case "validating-milestone":
+            return state.activeMilestone ? `Validate ${state.activeMilestone.id}` : "Validate milestone";
+        case "completing-milestone":
+            return state.activeMilestone ? `Complete ${state.activeMilestone.id}` : "Complete milestone";
+        case "replanning-slice":
+            return state.activeSlice ? `Replan ${state.activeSlice.id}` : "Replan current slice";
+        case "blocked":
+            return `waiting on ${compactText(state.blockers[0] ?? state.nextAction, 56)}`;
+        case "paused":
+            return compactText(state.nextAction || "waiting to resume", 56);
+        case "complete":
+            return "All milestones complete";
+        default:
+            return compactText(describeNextUnit(state).label, 56);
     }
-    // Environment issues
-    if (data.environmentErrorCount > 0) {
-        parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+}
+async function enrichHealthWidgetData(basePath, baseData) {
+    if (baseData.projectState !== "active")
+        return baseData;
+    try {
+        invalidateStateCache();
+        const state = await deriveState(basePath);
+        if (state.activeMilestone) {
+            // Warm the slice-progress cache so estimateTimeRemaining() has data
+            updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
+        }
+        return {
+            ...baseData,
+            executionPhase: state.phase,
+            executionStatus: summarizeExecutionStatus(state),
+            executionTarget: summarizeExecutionTarget(state),
+            nextAction: state.nextAction,
+            blocker: state.blockers[0] ?? null,
+            activeMilestoneId: state.activeMilestone?.id,
+            activeSliceId: state.activeSlice?.id,
+            activeTaskId: state.activeTask?.id,
+            progress: state.progress,
+            eta: state.phase === "blocked" || state.phase === "paused" || state.phase === "complete"
+                ? null
+                : estimateTimeRemaining(),
+        };
     }
-    else if (data.environmentWarningCount > 0) {
-        parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+    catch {
+        return baseData;
     }
-    return [`  ${parts.join("  │  ")}`];
 }
 // ── Widget init ────────────────────────────────────────────────────────────────
 const REFRESH_INTERVAL_MS = 60_000;
@@ -112,19 +149,33 @@ export function initHealthWidget(ctx) {
         return;
     const basePath = projectRoot();
     // String-array fallback — used in RPC mode (factory is a no-op there)
-    const initialData = loadHealthWidgetData(basePath);
+    const initialData = loadBaseHealthWidgetData(basePath);
     ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
     // Factory-based widget for TUI mode — replaces the string-array above
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
         let data = initialData;
         let cachedLines;
-        const refreshTimer = setInterval(() => {
+        let refreshInFlight = false;
+        const refresh = async () => {
+            if (refreshInFlight)
+                return;
+            refreshInFlight = true;
             try {
-                data = loadHealthWidgetData(basePath);
+                const baseData = loadBaseHealthWidgetData(basePath);
+                data = await enrichHealthWidgetData(basePath, baseData);
                 cachedLines = undefined;
                 _tui.requestRender();
             }
             catch { /* non-fatal */ }
+            finally {
+                refreshInFlight = false;
+            }
+        };
+        // Fire first enrichment immediately. requestRender() inside is a no-op
+        // if the widget has not yet rendered, so this is safe before factory return.
+        void refresh();
+        const refreshTimer = setInterval(() => {
+            void refresh();
         }, REFRESH_INTERVAL_MS);
         return {
             render(_width) {

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

@@ -46,33 +46,21 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-function loadAgentInstructions() {
-    const parts = [];
-    const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-    if (existsSync(globalPath)) {
-        try {
-            const content = readFileSync(globalPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
-        }
-        catch { /* non-fatal — skip unreadable file */ }
-    }
-    const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-    if (existsSync(projectPath)) {
-        try {
-            const content = readFileSync(projectPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+function warnDeprecatedAgentInstructions() {
+    const paths = [
+        join(homedir(), ".gsd", "agent-instructions.md"),
+        join(process.cwd(), ".gsd", "agent-instructions.md"),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            console.warn(`[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+                `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+                `See https://github.com/gsd-build/GSD-2/issues/1492`);
         }
-        catch { /* non-fatal — skip unreadable file */ }
     }
-    if (parts.length === 0)
-        return null;
-    return parts.join("\n\n");
 }
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
@@ -140,7 +128,16 @@ export default function (pi) {
                 // Pipe closed — nothing we can write; just exit cleanly
                 process.exit(0);
             }
-            // Re-throw anything that isn't EPIPE so real crashes still surface
+            if (err.code === "ENOENT" &&
+                err.syscall?.startsWith("spawn")) {
+                // spawn ENOENT — command not found (e.g., npx on Windows).
+                // This surfaces as an uncaught exception from child_process but
+                // is not a fatal process error. Log and continue instead of
+                // crashing auto-mode (#1384).
+                process.stderr.write(`[gsd] spawn ENOENT: ${err.path ?? "unknown"} — command not found\n`);
+                return;
+            }
+            // Re-throw anything that isn't EPIPE/ENOENT so real crashes still surface
             throw err;
         };
         process.on("uncaughtException", _gsdEpipeGuard);
@@ -580,12 +577,8 @@ export default function (pi) {
                 newSkillsBlock = formatSkillsXml(newSkills);
             }
         }
-        // Load agent instructions (global + project)
-        let agentInstructionsBlock = "";
-        const agentInstructions = loadAgentInstructions();
-        if (agentInstructions) {
-            agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-        }
+        // Warn if deprecated agent-instructions.md files are still present
+        warnDeprecatedAgentInstructions();
         const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
         // Worktree context — override the static CWD in the system prompt
         let worktreeBlock = "";
@@ -628,7 +621,7 @@ export default function (pi) {
                 "Write every .gsd artifact in the worktree path above, never in the main project tree.",
             ].join("\n");
         }
-        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
         stopContextTimer({
             systemPromptSize: fullSystem.length,
             injectionSize: injection?.length ?? 0,

package/dist/resources/extensions/gsd/migrate-external.js

@@ -5,10 +5,11 @@
  * `~/.gsd/projects/<hash>/` state directory. After migration, a
  * symlink replaces the original directory so all paths remain valid.
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
+import { hasGitTrackedGsdFiles } from "./gitignore.js";
 /**
  * Migrate a legacy in-project `.gsd/` directory to external storage.
  *
@@ -42,6 +43,27 @@ export function migrateToExternalState(basePath) {
     catch (err) {
         return { migrated: false, error: `Cannot stat .gsd: ${getErrorMessage(err)}` };
     }
+    // Skip if .gsd/ contains git-tracked files — the project intentionally
+    // keeps .gsd/ in version control and migration would destroy that.
+    if (hasGitTrackedGsdFiles(basePath)) {
+        return { migrated: false };
+    }
+    // Skip if .gsd/worktrees/ has active worktree directories (#1337).
+    // On Windows, active git worktrees hold OS-level directory handles that
+    // prevent rename/delete. Attempting migration causes EBUSY and data loss.
+    const worktreesDir = join(localGsd, "worktrees");
+    if (existsSync(worktreesDir)) {
+        try {
+            const entries = readdirSync(worktreesDir, { withFileTypes: true });
+            if (entries.some(e => e.isDirectory())) {
+                return { migrated: false };
+            }
+        }
+        catch {
+            // Can't read worktrees dir — skip migration to be safe
+            return { migrated: false };
+        }
+    }
     const externalPath = externalGsdRoot(basePath);
     const migratingPath = join(basePath, ".gsd.migrating");
     try {
@@ -89,7 +111,38 @@ export function migrateToExternalState(basePath) {
         }
         // Create symlink .gsd -> external path
         symlinkSync(externalPath, localGsd, "junction");
-        // Remove .gsd.migrating
+        // Verify the symlink resolves correctly before removing the backup (#1377).
+        // On Windows, junction creation can silently succeed but resolve to the wrong
+        // target, or the external dir may not be accessible. If verification fails,
+        // restore from the backup.
+        try {
+            const resolved = realpathSync(localGsd);
+            const resolvedExternal = realpathSync(externalPath);
+            if (resolved !== resolvedExternal) {
+                // Symlink points to wrong target — restore backup
+                try {
+                    rmSync(localGsd, { force: true });
+                }
+                catch { /* may not exist */ }
+                renameSync(migratingPath, localGsd);
+                return { migrated: false, error: `Migration verification failed: symlink resolves to ${resolved}, expected ${resolvedExternal}` };
+            }
+            // Verify we can read through the symlink
+            readdirSync(localGsd);
+        }
+        catch (verifyErr) {
+            // Symlink broken or unreadable — restore backup
+            try {
+                rmSync(localGsd, { force: true });
+            }
+            catch { /* may not exist */ }
+            try {
+                renameSync(migratingPath, localGsd);
+            }
+            catch { /* best-effort restore */ }
+            return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
+        }
+        // Remove .gsd.migrating only after symlink is verified
         rmSync(migratingPath, { recursive: true, force: true });
         return { migrated: true };
     }

package/dist/resources/extensions/gsd/milestone-ids.js

@@ -67,8 +67,9 @@ export function findMilestoneIds(basePath) {
             .filter((d) => d.isDirectory())
             .map((d) => {
             const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-            return match ? match[1] : d.name;
-        });
+            return match ? match[1] : null;
+        })
+            .filter((id) => id !== null);
         // Apply custom queue order if available, else fall back to numeric sort
         const customOrder = loadQueueOrder(basePath);
         return sortByQueueOrder(ids, customOrder);

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

@@ -9,7 +9,8 @@
  * via prefix matching, so existing projects work without migration.
  */
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
@@ -263,15 +264,81 @@ const LEGACY_GSD_ROOT_FILES = {
     OVERRIDES: "overrides.md",
     KNOWLEDGE: "knowledge.md",
 };
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+const gsdRootCache = new Map();
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache() {
+    gsdRootCache.clear();
+}
+/**
+ * Resolve the `.gsd` directory for a given project base path.
+ *
+ * Probe order:
+ *   1. basePath/.gsd         — fast path (common case)
+ *   2. git rev-parse root    — handles cwd-is-a-subdirectory
+ *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
+ *   4. basePath/.gsd         — creation fallback (init scenario)
+ *
+ * Result is cached per basePath for the process lifetime.
+ */
 export function gsdRoot(basePath) {
-    const local = join(basePath, ".gsd");
+    const cached = gsdRootCache.get(basePath);
+    if (cached)
+        return cached;
+    const result = probeGsdRoot(basePath);
+    gsdRootCache.set(basePath, result);
+    return result;
+}
+function probeGsdRoot(rawBasePath) {
+    // 1. Fast path — check the input path directly
+    const local = join(rawBasePath, ".gsd");
+    if (existsSync(local))
+        return local;
+    // Resolve symlinks so path comparisons work correctly across platforms
+    // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
+    let basePath;
     try {
-        const resolved = realpathSync(local);
-        if (resolved !== local)
-            return resolved; // symlink resolved
+        basePath = realpathSync.native(rawBasePath);
+    }
+    catch {
+        basePath = rawBasePath;
+    }
+    // 2. Git root anchor — used as both probe target and walk-up boundary
+    //    Only walk if we're inside a git project — prevents escaping into
+    //    unrelated filesystem territory when running outside any repo.
+    let gitRoot = null;
+    try {
+        const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: basePath,
+            encoding: "utf-8",
+        });
+        if (out.status === 0) {
+            const r = out.stdout.trim();
+            if (r)
+                gitRoot = normalize(r);
+        }
+    }
+    catch { /* git not available */ }
+    if (gitRoot) {
+        const candidate = join(gitRoot, ".gsd");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
+    if (gitRoot && basePath !== gitRoot) {
+        let cur = dirname(basePath);
+        while (cur !== basePath) {
+            const candidate = join(cur, ".gsd");
+            if (existsSync(candidate))
+                return candidate;
+            if (cur === gitRoot)
+                break;
+            basePath = cur;
+            cur = dirname(cur);
+        }
     }
-    catch { /* doesn't exist yet — fall through */ }
-    return local; // backwards compat: unmigrated projects
+    // 4. Fallback for init/creation
+    return local;
 }
 export function milestonesDir(basePath) {
     return join(gsdRoot(basePath), "milestones");

package/dist/resources/extensions/gsd/post-unit-hooks.js

@@ -111,10 +111,13 @@ function dequeueNextHook(basePath) {
         };
         // Build the prompt with variable substitution
         const [mid, sid, tid] = triggerUnitId.split("/");
-        const prompt = config.prompt
+        let prompt = config.prompt
             .replace(/\{milestoneId\}/g, mid ?? "")
             .replace(/\{sliceId\}/g, sid ?? "")
             .replace(/\{taskId\}/g, tid ?? "");
+        // Inject browser safety instruction for hooks that may use browser tools (#1345).
+        // Vite HMR and other persistent connections prevent networkidle from resolving.
+        prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
         return {
             hookName: config.name,
             prompt,

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

@@ -14,9 +14,24 @@ export function validatePreferences(preferences) {
     const warnings = [];
     const validated = {};
     // ─── Unknown Key Detection ──────────────────────────────────────────
+    // Common key migration hints for pi-level settings that don't map to GSD prefs
+    const KEY_MIGRATION_HINTS = {
+        taskIsolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        task_isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        manage_gitignore: 'use "git.manage_gitignore" instead',
+        auto_push: 'use "git.auto_push" instead',
+        main_branch: 'use "git.main_branch" instead',
+    };
     for (const key of Object.keys(preferences)) {
         if (!KNOWN_PREFERENCE_KEYS.has(key)) {
-            warnings.push(`unknown preference key "${key}" — ignored`);
+            const hint = KEY_MIGRATION_HINTS[key];
+            if (hint) {
+                warnings.push(`unknown preference key "${key}" — ${hint}`);
+            }
+            else {
+                warnings.push(`unknown preference key "${key}" — ignored`);
+            }
         }
     }
     if (preferences.version !== undefined) {

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

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 import { MODE_DEFAULTS, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
 import { formatSkillRef } from "./preferences-skills.js";
@@ -79,6 +80,17 @@ export function loadEffectiveGSDPreferences() {
             ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
         };
     }
+    // Apply token-profile defaults as the lowest-priority layer so that
+    // `token_profile: budget` sets models and phase-skips automatically.
+    // Explicit user preferences always override profile defaults.
+    const profile = result.preferences.token_profile;
+    if (profile) {
+        const profileDefaults = _resolveProfileDefaults(profile);
+        result = {
+            ...result,
+            preferences: mergePreferences(profileDefaults, result.preferences),
+        };
+    }
     // Apply mode defaults as the lowest-priority layer
     if (result.preferences.mode) {
         result = {

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -28,6 +28,8 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -67,4 +67,6 @@ If verdict is `needs-remediation`:
 
 **You MUST write `{{validationPath}}` before finishing.**
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/dist/resources/extensions/gsd/roadmap-mutations.js

@@ -0,0 +1,55 @@
+/**
+ * Roadmap Mutations — shared utilities for modifying roadmap checkbox state.
+ *
+ * Extracts the duplicated "flip slice checkbox" pattern that existed in
+ * doctor.ts, mechanical-completion.ts, and auto-recovery.ts.
+ */
+import { readFileSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { clearParseCache } from "./files.js";
+/**
+ * Mark a slice as done ([x]) in the milestone roadmap.
+ * Idempotent — no-op if already checked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceDoneInRoadmap(basePath, mid, sid) {
+    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+    if (!roadmapFile)
+        return false;
+    let content;
+    try {
+        content = readFileSync(roadmapFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"), `$1[x] **${sid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(roadmapFile, updated);
+    clearParseCache();
+    return true;
+}
+/**
+ * Mark a task as done ([x]) in the slice plan.
+ * Idempotent — no-op if already checked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskDoneInPlan(basePath, planPath, tid) {
+    let content;
+    try {
+        content = readFileSync(planPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"), `$1[x] **${tid}:`);
+    if (updated === content)
+        return false;
+    atomicWriteSync(planPath, updated);
+    clearParseCache();
+    return true;
+}