gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.1afbdaa

package/dist/resources/extensions/gsd/prompts/reactive-execute.md

@@ -26,7 +26,7 @@ You are executing **multiple tasks in parallel** for this slice. The task graph
 2. **Wait for all subagents** to complete.
 3. **Verify each dispatched task's outputs** — check that expected files were created/modified, that verification commands pass where applicable, and that each task wrote its own `T##-SUMMARY.md`.
 4. **Do not rewrite successful task summaries or duplicate completion tool calls.** Treat a subagent-written summary as authoritative for that task.
-5. **If a failed task produced no summary, write a recovery summary for that task** with `blocker_discovered: true`, clear failure details, and leave the task unchecked so replan/retry has an authoritative record.
+5. **If a failed task produced no summary, call `gsd_summary_save`** with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, the failed task's `task_id`, and `artifact_type: "SUMMARY"` — include `blocker_discovered: true` and clear failure details in the `content`. Do NOT call `gsd_task_complete` for the failed task — leave it uncompleted so replan/retry has an authoritative record.
 6. **Preserve successful sibling tasks exactly as they landed.** Do not roll back good work because another parallel task failed.
 7. **Do NOT create a batch commit.** The surrounding unit lifecycle owns commits; this parent batch agent should not invent a second commit layer.
 8. **Report the batch outcome** — which tasks succeeded, which failed, and any output collisions or dependency surprises.

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -50,14 +50,14 @@ If all criteria have at least one remaining owning slice, the coverage check pas
 
 **If the roadmap is still good:**
 
-Write `{{assessmentPath}}` with a brief confirmation that roadmap coverage still holds after {{completedSliceId}}. If requirements exist, explicitly note whether requirement coverage remains sound. If `gsd_reassess_roadmap` is available, use it with `verdict: "roadmap-confirmed"`, an empty `sliceChanges` object, and the assessment text — the tool writes the assessment to the DB and renders ASSESSMENT.md.
+Use `gsd_reassess_roadmap` with `verdict: "roadmap-confirmed"`, an empty `sliceChanges` object, and the assessment text — the tool writes the assessment to the DB and renders `{{assessmentPath}}`. If requirements exist, explicitly note whether requirement coverage remains sound.
 
 **If changes are needed:**
 
-1. **Persist changes through `gsd_reassess_roadmap`.** Pass: `milestoneId`, `completedSliceId`, `verdict` (e.g. "roadmap-adjusted"), `assessment` (text explaining the decision), and `sliceChanges` with `modified` (array of sliceId, title, risk, depends, demo), `added` (same shape), `removed` (array of slice ID strings). The tool structurally enforces preservation of completed slices, writes the assessment to the DB, re-renders ROADMAP.md, and renders ASSESSMENT.md. Skip step 2 when this tool succeeds.
-2. **Degraded fallback — direct file writes:** If `gsd_reassess_roadmap` is not available, rewrite the remaining (unchecked) slices in `{{roadmapPath}}` directly. Keep completed slices exactly as they are (`[x]`). Update the boundary map for changed slices. Update the proof strategy if risks changed. Update requirement coverage if ownership or scope changed.
-3. Write `{{assessmentPath}}` explaining what changed and why — keep it brief and concrete.
-4. If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, update it.
-5. {{commitInstruction}}
+**Persist changes through `gsd_reassess_roadmap`.** Pass: `milestoneId`, `completedSliceId`, `verdict` (e.g. "roadmap-adjusted"), `assessment` (text explaining the decision), and `sliceChanges` with `modified` (array of sliceId, title, risk, depends, demo), `added` (same shape), `removed` (array of slice ID strings). The tool structurally enforces preservation of completed slices, writes the assessment to the DB, re-renders `{{roadmapPath}}`, and renders `{{assessmentPath}}`.
+
+If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, update it.
+
+{{commitInstruction}}
 
 When done, say: "Roadmap reassessed."

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -32,19 +32,8 @@ Consider these captures when rewriting the remaining tasks — they represent th
 
 1. Read the blocker task summary carefully. Understand exactly what was discovered and why it blocks the current plan.
 2. Analyze the remaining `[ ]` tasks in the slice plan. Determine which are still valid, which need modification, and which should be replaced.
-3. **Persist replan state through `gsd_replan_slice`.** Call it with the following parameters: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders PLAN.md, and renders REPLAN.md. Skip steps 4–5 when this tool succeeds.
-4. **Degraded fallback — direct file writes:** If `gsd_replan_slice` is not available, fall back to writing files directly. Write `{{replanPath}}` documenting:
-   - What blocker was discovered and in which task
-   - What changed in the plan and why
-   - Which incomplete tasks were modified, added, or removed
-   - Any new risks or considerations introduced by the replan
-5. If using the degraded fallback, rewrite `{{planPath}}` with the updated slice plan:
-   - Keep all `[x]` tasks exactly as they were (same IDs, same descriptions, same checkmarks)
-   - Update the `[ ]` tasks to address the blocker
-   - Ensure the slice Goal and Demo sections are still achievable with the new tasks, or update them if the blocker fundamentally changes what the slice can deliver
-   - Update the Files Likely Touched section if the replan changes which files are affected
-   - If a DB-backed planning tool exists for this phase, use it as the source of truth and make any rewritten `PLAN.md` reflect that persisted state rather than bypassing it
-6. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
-7. Do not commit manually — the system auto-commits your changes after this unit completes.
+3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`.
+4. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
+5. Do not commit manually — the system auto-commits your changes after this unit completes.
 
 When done, say: "Slice {{sliceId}} replanned."

package/dist/resources/extensions/gsd/prompts/research-slice.md

@@ -48,10 +48,10 @@ Research what this slice needs. Narrate key findings and surprises as you go —
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
 5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
 6. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
-7. Write `{{outputPath}}`
+7. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the full research markdown as `content` — the tool computes the file path and persists to both DB and disk.
 
-The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.
+The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir.
 
-**You MUST write the file `{{outputPath}}` before finishing.**
+**You MUST call `gsd_summary_save` with the research content before finishing.**
 
 When done, say: "Slice {{sliceId}} researched."

package/dist/resources/extensions/gsd/prompts/rethink.md

@@ -0,0 +1,83 @@
+You are a project reorganization assistant for a GSD (Get Shit Done) project. The user wants to rethink their milestone plan — reorder priorities, remove work that's no longer needed, add new milestones, or restructure dependencies.
+
+## Current Milestone Landscape
+
+{{rethinkData}}
+
+## Detailed Milestone Context
+
+{{existingMilestonesContext}}
+
+## Your Role
+
+1. Present the current milestone order as a clear numbered list with status indicators (e.g. ✅ complete, ▶ active, ⏳ pending, ⏸ parked)
+2. Ask: **"What would you like to change?"**
+3. Execute changes conversationally, confirming destructive operations before proceeding
+
+## Supported Operations
+
+<!-- NOTE: Park, unpark, reorder, discard, and dependency-update operations are intentionally
+     file-based. No gsd_* tool API exists for these milestone-lifecycle mutations yet.
+     The single-writer DB tools (gsd_plan_milestone, gsd_complete_milestone, etc.) own
+     create and complete; queue management is file-driven until tool support is added. -->
+
+### Reorder milestones
+Change execution order of pending/active milestones. Write `.gsd/QUEUE-ORDER.json`:
+```json
+{ "order": ["M003", "M001", "M002"], "updatedAt": "<ISO timestamp>" }
+```
+Only include non-complete milestone IDs. Validate dependency constraints before saving.
+
+### Park a milestone
+Temporarily shelve a milestone (reversible). Create a `{ID}-PARKED.md` file in the milestone directory:
+```markdown
+---
+parked_at: <ISO timestamp>
+reason: "<reason>"
+---
+
+# {ID} — Parked
+
+> <reason>
+```
+**Bias toward parking over discarding** when a milestone has any completed slices or tasks.
+
+### Unpark a milestone
+Remove the `{ID}-PARKED.md` file from the milestone directory to reactivate it.
+
+### Discard a milestone
+**Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. **Always confirm with the user before discarding.** Warn explicitly if the milestone has completed work.
+
+### Add a new milestone
+Use the `gsd_milestone_generate_id` tool to get the next ID, then call `gsd_summary_save` with `milestone_id: {ID}`, `artifact_type: "CONTEXT"`, and the scope/goals/success criteria as `content` — the tool writes the context file to disk and persists to DB. Update QUEUE-ORDER.json to place it at the desired position.
+
+### Update dependencies
+Edit `depends_on` in the YAML frontmatter of a milestone's `{ID}-CONTEXT.md` file. For example:
+```yaml
+depends_on: [M001, M003]
+```
+
+## Dependency Validation Rules
+
+Before applying any reorder, verify:
+- A milestone **cannot** be scheduled before any milestone in its `depends_on` list (would_block)
+- Circular dependencies are forbidden
+- Dependencies on non-existent milestones are invalid (missing_dep)
+- Completed milestones always satisfy dependencies regardless of position
+
+If a proposed order would violate constraints, explain the issue and suggest alternatives (e.g. removing the dependency, reordering differently, or parking the blocker).
+
+## After Each Change
+
+1. Execute the change (write/delete files, update QUEUE-ORDER.json)
+2. Show the updated milestone order
+3. Note if the active milestone changed as a result
+4. Ask if there's anything else to adjust
+
+## Important Constraints
+
+- Do NOT modify completed milestones — they're done
+- Do NOT park completed milestones — it would corrupt dependency satisfaction
+- Park is preferred over discard when a milestone has any completed work
+- Always persist queue order changes to `.gsd/QUEUE-ORDER.json`
+- After changes, run `git add .gsd/ && git commit -m "docs(gsd): rethink milestone plan"` to persist (rethink runs interactively outside auto-mode, so no system auto-commit)

package/dist/resources/extensions/gsd/prompts/system.md

@@ -112,7 +112,7 @@ In all modes, slices commit sequentially on the active branch; there are no per-
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.
 - **Tasks** are single-context-window units of work (T01, T02, ...)
-- Checkboxes in roadmap and plan files track completion (`[ ]` → `[x]`)
+- Checkboxes in roadmap and plan files track completion (`[ ]` → `[x]`) — toggled automatically by gsd_* tools, never edited manually
 - Summaries compress prior work - read them instead of re-reading all task details
 - `STATE.md` is a system-managed status file — rebuilt automatically after each unit completes
 

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

@@ -16,6 +16,8 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 {{inlinedContext}}
 
+{{skillActivation}}
+
 ## Validation Steps
 
 1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion.
@@ -25,47 +27,15 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 5. Determine a verdict:
    - `pass` — all criteria met, all slices delivered, no gaps
    - `needs-attention` — minor gaps that do not block completion (document them)
-   - `needs-remediation` — material gaps found; add remediation slices to the roadmap
-
-## Output
-
-Write `{{validationPath}}` with this structure:
-
-```markdown
----
-verdict: <pass|needs-attention|needs-remediation>
-remediation_round: {{remediationRound}}
----
-
-# Milestone Validation: {{milestoneId}}
+   - `needs-remediation` — material gaps found; remediation slices must be added to the roadmap
 
-## Success Criteria Checklist
-- [x] Criterion 1 — evidence: ...
-- [ ] Criterion 2 — gap: ...
+## Persist Validation
 
-## Slice Delivery Audit
-| Slice | Claimed | Delivered | Status |
-|-------|---------|-----------|--------|
-| S01   | ...     | ...       | pass   |
-
-## Cross-Slice Integration
-(any boundary mismatches)
-
-## Requirement Coverage
-(any unaddressed requirements)
-
-## Verdict Rationale
-(why this verdict was chosen)
-
-## Remediation Plan
-(only if verdict is needs-remediation — list new slices to add to the roadmap)
-```
+**Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` (if verdict is `needs-remediation`). The tool writes the validation to the DB and renders VALIDATION.md to disk.
 
 If verdict is `needs-remediation`:
-- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
-- These slices will be planned and executed before validation re-runs
-
-**You MUST write `{{validationPath}}` before finishing.**
+- After calling `gsd_validate_milestone`, use `gsd_reassess_roadmap` to add remediation slices. Pass `milestoneId`, a synthetic `completedSliceId` (e.g. "VALIDATION"), `verdict: "roadmap-adjusted"`, `assessment` text, and `sliceChanges` with the new slices in the `added` array. The tool persists the changes to the DB and re-renders ROADMAP.md.
+- These remediation slices will be planned and executed before validation re-runs.
 
 **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.
 

package/dist/resources/extensions/gsd/provider-error-pause.js

@@ -10,6 +10,10 @@
 export function classifyProviderError(errorMsg) {
     const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
     const isServerError = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i.test(errorMsg);
+    // Connection/process errors — transient, auto-resume after brief backoff (#2309).
+    // These indicate the process was killed, the connection was reset, or a network
+    // blip occurred. They are NOT permanent failures.
+    const isConnectionError = /terminated|connection.?reset|connection.?refused|other side closed|fetch failed|network.?(?:is\s+)?unavailable|ECONNREFUSED|ECONNRESET|EPIPE/i.test(errorMsg);
     // Permanent errors — never auto-resume
     const isPermanent = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i.test(errorMsg);
     if (isPermanent && !isRateLimit) {
@@ -24,6 +28,9 @@ export function classifyProviderError(errorMsg) {
     if (isServerError) {
         return { isTransient: true, isRateLimit: false, suggestedDelayMs: 30_000 }; // 30s for server errors
     }
+    if (isConnectionError) {
+        return { isTransient: true, isRateLimit: false, suggestedDelayMs: 15_000 }; // 15s for connection errors
+    }
     // Unknown error — treat as permanent (user reviews)
     return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
 }

package/dist/resources/extensions/gsd/repo-identity.js

@@ -89,16 +89,17 @@ export function readRepoMeta(externalPath) {
  * Returns true when ALL of:
  *   1. basePath is inside a git repo (git rev-parse succeeds)
  *   2. The resolved git root is a proper ancestor of basePath
- *   3. There is no `.gsd` directory at the git root (the parent project
- *      has not been initialised with GSD)
+ *   3. There is no *project* `.gsd` directory at the git root or any
+ *      intermediate ancestor (the parent project has not been
+ *      initialised with GSD)
  *
  * When true, the caller should run `git init` at basePath so that
  * `repoIdentity()` produces a hash unique to this directory, preventing
  * cross-project state leaks (#1639).
  *
- * When the git root already has `.gsd`, the directory is a legitimate
- * subdirectory of an existing GSD project — `cd src/ && /gsd` should
- * still load the parent project's milestones.
+ * When the git root already has a project `.gsd`, the directory is a
+ * legitimate subdirectory of an existing GSD project — `cd src/ && /gsd`
+ * should still load the parent project's milestones.
  */
 export function isInheritedRepo(basePath) {
     try {
@@ -109,12 +110,12 @@ export function isInheritedRepo(basePath) {
             return false; // basePath IS the root
         // The git root is a proper ancestor. Check whether it already has .gsd
         // (i.e. the parent project was initialised with GSD).
-        if (existsSync(join(root, ".gsd")))
+        if (isProjectGsd(join(root, ".gsd")))
             return false;
         // Also walk up from basePath to the git root checking for .gsd
         let dir = normalizedBase;
         while (dir !== normalizedRoot && dir !== dirname(dir)) {
-            if (existsSync(join(dir, ".gsd")))
+            if (isProjectGsd(join(dir, ".gsd")))
                 return false;
             dir = dirname(dir);
         }
@@ -124,6 +125,43 @@ export function isInheritedRepo(basePath) {
         return false;
     }
 }
+/**
+ * Distinguish a *project* `.gsd` from the global `~/.gsd` state directory.
+ *
+ * A project `.gsd` is either:
+ *   - A symlink to an external state directory (normal post-migration layout)
+ *   - A legacy real directory that is NOT the global GSD home
+ *
+ * When the user's home directory is itself a git repo (e.g. dotfile managers),
+ * `~/.gsd` exists but is the global state directory — not a project `.gsd`.
+ * Treating it as a project `.gsd` would cause isInheritedRepo() to wrongly
+ * conclude that subdirectories are part of the home "project" (#2393).
+ */
+function isProjectGsd(gsdPath) {
+    if (!existsSync(gsdPath))
+        return false;
+    try {
+        const stat = lstatSync(gsdPath);
+        // Symlinks are always project .gsd (created by ensureGsdSymlink).
+        if (stat.isSymbolicLink())
+            return true;
+        // For real directories, check that this isn't the global GSD home.
+        // Recompute gsdHome dynamically so env overrides (GSD_HOME) are
+        // picked up at call time, not just at module load time.
+        if (stat.isDirectory()) {
+            const currentGsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+            const normalizedGsdPath = canonicalizeExistingPath(gsdPath);
+            const normalizedGsdHome = canonicalizeExistingPath(currentGsdHome);
+            if (normalizedGsdPath === normalizedGsdHome)
+                return false;
+            return true;
+        }
+    }
+    catch {
+        // lstat failed — treat as no .gsd present
+    }
+    return false;
+}
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 /**
  * Get the git remote URL for "origin", or "" if no remote is configured.

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

@@ -0,0 +1,115 @@
+/**
+ * GSD Rethink — Conversational project reorganization.
+ *
+ * Collects a snapshot of all milestones (status, dependencies, slice progress,
+ * queue order) and dispatches a prompt that turns Claude into a reorganization
+ * assistant. Claude can then reorder, park, unpark, discard, or add milestones
+ * through conversation.
+ */
+import { existsSync } from "node:fs";
+import { isAutoActive } from "./auto.js";
+import { deriveState } from "./state.js";
+import { gsdRoot } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
+import { loadQueueOrder, validateQueueOrder } from "./queue-order.js";
+import { getParkedReason } from "./milestone-actions.js";
+import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { buildExistingMilestonesContext } from "./guided-flow-queue.js";
+import { loadPrompt } from "./prompt-loader.js";
+// ─── Entry Point ──────────────────────────────────────────────────────────────
+export async function handleRethink(_args, ctx, pi) {
+    if (isAutoActive()) {
+        ctx.ui.notify("Cannot rethink while auto-mode is active. Stop auto-mode first.", "error");
+        return;
+    }
+    const basePath = process.cwd();
+    const root = gsdRoot(basePath);
+    if (!existsSync(root)) {
+        ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");
+        return;
+    }
+    ctx.ui.notify("Building project snapshot for rethink...", "info");
+    const state = await deriveState(basePath);
+    const milestoneIds = findMilestoneIds(basePath);
+    if (milestoneIds.length === 0) {
+        ctx.ui.notify("No milestones exist yet. Nothing to rethink.", "warning");
+        return;
+    }
+    const queueOrder = loadQueueOrder(basePath);
+    const rethinkData = buildRethinkData(basePath, milestoneIds, state, queueOrder);
+    const existingMilestonesContext = await buildExistingMilestonesContext(basePath, milestoneIds, state);
+    const content = loadPrompt("rethink", {
+        rethinkData,
+        existingMilestonesContext,
+    });
+    pi.sendMessage({ customType: "gsd-rethink", content, display: false }, { triggerTurn: true });
+}
+// ─── Data Builder ─────────────────────────────────────────────────────────────
+function buildRethinkData(basePath, milestoneIds, state, queueOrder) {
+    const lines = [];
+    const dbAvailable = isDbAvailable();
+    // ── Summary stats ───────────────────────────────────────────────────
+    const counts = { complete: 0, active: 0, pending: 0, parked: 0 };
+    for (const entry of state.registry) {
+        if (entry.status in counts)
+            counts[entry.status]++;
+    }
+    lines.push("### Summary");
+    lines.push(`${counts.complete} complete, ${counts.active} active, ${counts.pending} pending, ${counts.parked} parked — ${milestoneIds.length} total`);
+    lines.push(`Queue order source: ${queueOrder ? "explicit QUEUE-ORDER.json" : "default numeric (by ID)"}`);
+    if (state.activeMilestone) {
+        lines.push(`Active milestone: ${state.activeMilestone}`);
+    }
+    lines.push("");
+    // ── Milestone table ─────────────────────────────────────────────────
+    lines.push("### Execution Order");
+    lines.push("");
+    lines.push("| # | ID | Title | Status | Dependencies | Slices |");
+    lines.push("|---|-----|-------|--------|--------------|--------|");
+    for (let i = 0; i < milestoneIds.length; i++) {
+        const mid = milestoneIds[i];
+        const entry = state.registry.find(m => m.id === mid);
+        const title = entry?.title ?? mid;
+        const status = entry?.status ?? "unknown";
+        const deps = entry?.dependsOn?.length ? entry.dependsOn.join(", ") : "—";
+        let sliceInfo = "—";
+        if (dbAvailable && status !== "complete") {
+            const slices = getMilestoneSlices(mid);
+            if (slices.length > 0) {
+                const done = slices.filter(s => s.status === "complete").length;
+                sliceInfo = `${done}/${slices.length} complete`;
+            }
+        }
+        // Add parked reason if applicable
+        let statusDisplay = status;
+        if (status === "parked") {
+            const reason = getParkedReason(basePath, mid);
+            if (reason)
+                statusDisplay = `parked (${reason})`;
+        }
+        lines.push(`| ${i + 1} | ${mid} | ${title} | ${statusDisplay} | ${deps} | ${sliceInfo} |`);
+    }
+    // ── Dependency validation ───────────────────────────────────────────
+    const pendingIds = milestoneIds.filter(mid => {
+        const entry = state.registry.find(m => m.id === mid);
+        return entry?.status !== "complete";
+    });
+    const completedIds = new Set(state.registry.filter(m => m.status === "complete").map(m => m.id));
+    const depsMap = new Map();
+    for (const entry of state.registry) {
+        if (entry.dependsOn?.length) {
+            depsMap.set(entry.id, entry.dependsOn);
+        }
+    }
+    if (pendingIds.length > 0 && depsMap.size > 0) {
+        const validation = validateQueueOrder(pendingIds, depsMap, completedIds);
+        if (validation.violations.length > 0) {
+            lines.push("");
+            lines.push("### Dependency Issues");
+            for (const v of validation.violations) {
+                lines.push(`- **${v.type}**: ${v.message}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/resources/extensions/gsd/session-lock.js

@@ -169,7 +169,6 @@ export function acquireSessionLock(basePath) {
         unitType: "starting",
         unitId: "bootstrap",
         unitStartedAt: new Date().toISOString(),
-        completedUnits: 0,
     };
     let lockfile;
     try {
@@ -314,7 +313,7 @@ function acquireFallbackLock(basePath, lp, lockData) {
  * Update the lock file metadata (called on each unit dispatch).
  * Does NOT re-acquire the OS lock — just updates the JSON content.
  */
-export function updateSessionLock(basePath, unitType, unitId, completedUnits, sessionFile) {
+export function updateSessionLock(basePath, unitType, unitId, sessionFile) {
     if (_lockedPath !== basePath && _lockedPath !== null)
         return;
     const lp = lockPath(basePath);
@@ -325,7 +324,6 @@ export function updateSessionLock(basePath, unitType, unitId, completedUnits, se
             unitType,
             unitId,
             unitStartedAt: new Date().toISOString(),
-            completedUnits,
             sessionFile,
         };
         atomicWriteSync(lp, JSON.stringify(data, null, 2));

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

@@ -4,12 +4,12 @@
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';
-import { findMilestoneIds } from './milestone-ids.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles } from './native-parser-bridge.js';
 import { join, resolve } from 'path';
 import { existsSync, readdirSync } from 'node:fs';
 import { debugCount, debugTime } from './debug-logger.js';
-import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, } from './gsd-db.js';
+import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, } from './gsd-db.js';
 /**
  * A "ghost" milestone directory contains only META.json (and no substantive
  * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY).  These appear when
@@ -57,6 +57,10 @@ export function isValidationTerminal(validationContent) {
 }
 const CACHE_TTL_MS = 100;
 let _stateCache = null;
+// ── Telemetry counters for derive-path observability ────────────────────────
+let _telemetry = { dbDeriveCount: 0, markdownDeriveCount: 0 };
+export function getDeriveTelemetry() { return { ..._telemetry }; }
+export function resetDeriveTelemetry() { _telemetry = { dbDeriveCount: 0, markdownDeriveCount: 0 }; }
 /**
  * Invalidate the deriveState() cache. Call this whenever planning files on disk
  * may have changed (unit completion, merges, file writes).
@@ -141,14 +145,17 @@ export async function deriveState(basePath) {
             const stopDbTimer = debugTime("derive-state-db");
             result = await deriveStateFromDb(basePath);
             stopDbTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
+            _telemetry.dbDeriveCount++;
         }
         else {
             // DB open but empty hierarchy tables — pre-migration project, use filesystem
             result = await _deriveStateImpl(basePath);
+            _telemetry.markdownDeriveCount++;
         }
     }
     else {
         result = await _deriveStateImpl(basePath);
+        _telemetry.markdownDeriveCount++;
     }
     stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
     debugCount("deriveStateCalls");
@@ -192,7 +199,45 @@ function isStatusDone(status) {
  */
 export async function deriveStateFromDb(basePath) {
     const requirements = parseRequirementCounts(await loadFile(resolveGsdRootFile(basePath, "REQUIREMENTS")));
-    const allMilestones = getAllMilestones();
+    let allMilestones = getAllMilestones();
+    // Incremental disk→DB sync: milestone directories created outside the DB
+    // write path (via /gsd queue, manual mkdir, or complete-milestone writing the
+    // next CONTEXT.md) are never inserted by the initial migration guard in
+    // auto-start.ts because that guard only runs when gsd.db doesn't exist yet.
+    // Reconcile here so deriveStateFromDb never silently misses queued milestones.
+    // insertMilestone uses INSERT OR IGNORE, so this is safe to call every time.
+    const dbIdSet = new Set(allMilestones.map(m => m.id));
+    const diskIds = findMilestoneIds(basePath);
+    let synced = false;
+    for (const diskId of diskIds) {
+        if (!dbIdSet.has(diskId) && !isGhostMilestone(basePath, diskId)) {
+            insertMilestone({ id: diskId, status: 'active' });
+            synced = true;
+        }
+    }
+    if (synced)
+        allMilestones = getAllMilestones();
+    // Reconcile: discover milestones that exist on disk but are missing from
+    // the DB. This happens when milestones were created before the DB migration
+    // or were manually added to the filesystem. Without this, disk-only
+    // milestones are invisible after migration (#2416).
+    const dbMilestoneIds = new Set(allMilestones.map(m => m.id));
+    const diskMilestoneIds = findMilestoneIds(basePath);
+    for (const diskId of diskMilestoneIds) {
+        if (!dbMilestoneIds.has(diskId)) {
+            // Synthesize a minimal MilestoneRow for the disk-only milestone.
+            // Title and status will be resolved from disk files in the loop below.
+            allMilestones.push({
+                id: diskId,
+                title: diskId,
+                status: 'active',
+                depends_on: [],
+                created_at: new Date().toISOString(),
+            });
+        }
+    }
+    // Re-sort so milestones are in canonical order after injection
+    allMilestones.sort((a, b) => milestoneIdSort(a.id, b.id));
     // Parallel worker isolation: when locked, filter to just the locked milestone
     const milestoneLock = process.env.GSD_MILESTONE_LOCK;
     const milestones = milestoneLock