gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

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

@@ -17,20 +17,31 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. In that case, do NOT mark the milestone as passing verification — document the gap clearly in the summary and state that implementation is missing.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. Record this as a **verification failure**.
+4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
+5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
 6. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-7. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
-8. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+
+### Verification Gate — STOP if verification failed
+
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 7.**
+
+**Failure path** (verification failed):
+- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT update `.gsd/PROJECT.md` to reflect completion.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
+- Write a clear summary of what failed and why to help the next attempt.
+- Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
+
+**Success path** (all verifications passed — continue with steps 7–11):
+
+7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`, `verificationPassed: true`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+8. For each requirement whose status changed in step 6, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
 9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
 10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 11. Do not commit manually — the system auto-commits your changes after this unit completes.
+- Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met or no code changes exist, document it clearly in the summary and do not mark the milestone as passing verification.
+**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run.
 
 **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/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -23,28 +23,15 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
-6. Call the `gsd_slice_complete` tool (alias: `gsd_complete_slice`) to record the slice as complete. The tool validates all tasks are complete, updates the slice status in the DB, renders the summary to `{{sliceSummaryPath}}`, UAT to `{{sliceUatPath}}`, and re-renders `{{roadmapPath}}` — all atomically. Read the summary and UAT templates at `~/.gsd/agent/extensions/gsd/templates/` to understand the expected structure, then pass the following parameters:
-
-   **Identity:** `sliceId`, `milestoneId`, `sliceTitle`
-
-   **Narrative:** `oneLiner` (one-line summary of what the slice accomplished), `narrative` (detailed account of what happened across all tasks), `verification` (what was verified and how), `deviations` (deviations from plan, or "None."), `knownLimitations` (gaps or limitations, or "None."), `followUps` (follow-up work discovered, or "None.")
-
-   **Files:** `keyFiles` (array of key file paths), `filesModified` (array of `{path, description}` objects for all files changed)
-
-   **Requirements:** `requirementsAdvanced` (array of `{id, how}`), `requirementsValidated` (array of `{id, proof}`), `requirementsInvalidated` (array of `{id, what}`), `requirementsSurfaced` (array of new requirement strings)
-
-   **Patterns & decisions:** `keyDecisions` (array of decision strings), `patternsEstablished` (array), `observabilitySurfaces` (array)
-
-   **Dependencies:** `provides` (what this slice provides downstream), `affects` (downstream slice IDs affected), `requires` (array of `{slice, provides}` for upstream dependencies consumed), `drillDownPaths` (paths to task summaries)
-
-   **UAT content:** `uatContent` — the UAT markdown body. This must be a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. The tool writes it to `{{sliceUatPath}}`.
-
-7. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-8. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
-9. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-10. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
-
-**You MUST call `gsd_slice_complete` before finishing.** The tool handles writing `{{sliceSummaryPath}}`, `{{sliceUatPath}}`, and updating `{{roadmapPath}}` atomically. You must still review decisions and knowledge manually (steps 7-8).
+5. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
+6. Write `{{sliceSummaryPath}}` (compress all task summaries).
+7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
+9. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+10. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
+12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+
+**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) call `gsd_complete_slice`. The unit will not be marked complete if any of these are missing.**
 
 When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -203,7 +203,7 @@ When writing context.md, preserve the user's exact terminology, emphasis, and sp
 
 4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
 5. Call `gsd_plan_milestone` to create the roadmap. Decompose into demoable vertical slices with risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. Use the **Roadmap** output template below to structure the tool call parameters.
-6. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below. Append rows for any architectural or pattern decisions made during discussion.
+6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
@@ -217,7 +217,7 @@ Once the user confirms the milestone split:
 1. For each milestone, call `gsd_milestone_generate_id` to get its ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
 2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
 3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
-4. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below.
+4. For any architectural or pattern decisions made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 #### Phase 2: Primary milestone
 

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -63,23 +63,13 @@ Then:
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
 12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
 13. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
-14. Call the `gsd_task_complete` tool (alias: `gsd_complete_task`) to record the task completion. This single tool call atomically updates the task status in the DB, renders the summary file to `{{taskSummaryPath}}`, and re-renders the plan file at `{{planPath}}`. Read the summary template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md` to understand the expected structure — but pass the content as tool parameters, not as a file write. The tool parameters are:
-    - `taskId`: "{{taskId}}"
-    - `sliceId`: "{{sliceId}}"
-    - `milestoneId`: "{{milestoneId}}"
-    - `oneLiner`: One-line summary of what was accomplished (becomes the commit message)
-    - `narrative`: Detailed narrative of what happened during the task
-    - `verification`: What was verified and how — commands run, tests passed, behavior confirmed
-    - `deviations`: Deviations from the task plan, or "None."
-    - `knownIssues`: Known issues discovered but not fixed, or "None."
-    - `keyFiles`: Array of key files created or modified
-    - `keyDecisions`: Array of key decisions made during this task
-    - `blockerDiscovered`: Whether a plan-invalidating blocker was discovered (boolean)
-    - `verificationEvidence`: Array of `{ command, exitCode, verdict, durationMs }` objects from the verification gate
-15. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
+14. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
+15. Write `{{taskSummaryPath}}`
+16. Call `gsd_complete_task` with milestone_id, slice_id, task_id, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically.
+17. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
 
 All work stays in your working directory: `{{workingDirectory}}`.
 
-**You MUST call `gsd_task_complete` before finishing.** The tool handles writing `{{taskSummaryPath}}` and updating the plan file at `{{planPath}}` — do not write the summary file or modify the plan file manually.
+**You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.**
 
 When done, say: "Task {{taskId}} complete."

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -105,6 +105,6 @@ Once the user confirms depth:
 
 1. Use the **Context** output template below
 2. `mkdir -p` the milestone directory if needed
-3. Write `{{milestoneId}}-CONTEXT.md` — preserve the user's exact terminology, emphasis, and framing. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "CONTEXT"`, and the full context markdown as `content` — the tool writes the file to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing in the content. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
 4. {{commitInstruction}}
 5. Say exactly: `"{{milestoneId}} context written."` — nothing else.

package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -48,7 +48,7 @@ Once the user is ready to wrap up:
 
 1. Use the **Slice Context** output template below
 2. `mkdir -p {{sliceDirPath}}`
-3. Write `{{contextPath}}` — use the template structure, filling in:
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT"`, and the context as `content` — the tool writes the file to disk and persists to DB. Use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers
    - **Why this Slice** — why now, what it unblocks
    - **Scope / In Scope** — what was confirmed in scope during the interview

package/src/resources/extensions/gsd/prompts/guided-plan-slice.md

@@ -1,3 +1,3 @@
-Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Use the **Slice Plan** and **Task Plan** output templates below. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. {{skillActivation}} Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Use the **Slice Plan** and **Task Plan** output templates below. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Call `gsd_plan_slice` to persist the slice plan — the tool writes `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files to disk and persists to DB. Do **not** write plan files manually — use the DB-backed tool so state stays consistent. If planning produces structural decisions, call `gsd_decision_save` for each — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically. {{skillActivation}} Before finishing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
 
 {{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/guided-research-slice.md

@@ -1,4 +1,4 @@
-Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs` — skip this for libraries already used in the codebase. Use the **Research** output template below. Write `{{sliceId}}-RESEARCH.md` in the slice directory.
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. {{skillActivation}} Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs` — skip this for libraries already used in the codebase. Use the **Research** output template below. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "RESEARCH"`, and the research content — the tool writes the file to disk and persists to DB.
 
 **You are the scout.** A planner agent reads your output in a fresh context to decompose this slice into tasks. Write for the planner — surface key files, where the work divides naturally, what to build first, and how to verify. If the research doc is vague, the planner re-explores code you already read. If it's precise, the planner decomposes immediately.
 

package/src/resources/extensions/gsd/prompts/plan-milestone.md

@@ -48,7 +48,7 @@ Then:
 3. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
 4. Order by risk (high-risk first)
 5. Call `gsd_plan_milestone` to persist the milestone planning fields and slice rows in the DB-backed planning path. Do **not** write `{{outputPath}}`, `ROADMAP.md`, or other planning artifacts manually — the planning tool owns roadmap rendering and persistence.
-6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined context above if the file doesn't exist yet)
+6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), call `gsd_decision_save` for each decision — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 ## Requirement Mapping Rules
 

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -63,7 +63,7 @@ Then:
    - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
    - **Inputs and Expected Output must list concrete backtick-wrapped file paths** (e.g. `` `src/types.ts` ``). These are machine-parsed to derive task dependencies — vague prose without paths breaks parallel execution. Every task must have at least one output file path.
    - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
-6. **Persist planning state through DB-backed tools.** Call `gsd_plan_slice` with the full slice planning payload (goal, demo, must-haves, verification, tasks, and metadata). Then call `gsd_plan_task` for each task to persist its planning fields. These tools write to the DB and render `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tools are the canonical write path for slice and task planning state.
+6. **Persist planning state through `gsd_plan_slice`.** Call it with the full slice planning payload (goal, demo, must-haves, verification, tasks, and metadata). The tool inserts all tasks in the same transaction, writes to the DB, and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** call `gsd_plan_task` separately — `gsd_plan_slice` handles task persistence. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tool is the canonical write path for slice and task planning state.
 7. **Self-audit the plan.** Walk through each check — if any fail, fix the plan files before moving on:
     - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true.
     - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task.
@@ -72,9 +72,11 @@ Then:
     - **Key links planned:** For every pair of artifacts that must connect, there is an explicit step that wires them.
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
     - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding.
-8. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
-9. {{commitInstruction}}
+10. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
+11. {{commitInstruction}}
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.
 
+**You MUST write the file `{{outputPath}}` before finishing.**
+
 When done, say: "Slice {{sliceId}} planned."

package/src/resources/extensions/gsd/prompts/queue.md

@@ -8,7 +8,7 @@ Before asking "What do you want to add?", check the existing milestones context
 
 1. Tell the user which milestones have draft contexts and briefly summarize what each draft contains (read the draft file).
 2. Use `ask_user_questions` to ask per-draft milestone:
-   - **"Discuss now"** — Treat this draft as the primary topic. Read the draft content, use it as seed material, and conduct a focused discussion following the standard discussion flow (reflection → investigation → questioning → depth verification → requirements → roadmap). After the discussion, write the full CONTEXT.md and delete the `CONTEXT-DRAFT.md` file. The milestone is then ready for auto-planning.
+   - **"Discuss now"** — Treat this draft as the primary topic. Read the draft content, use it as seed material, and conduct a focused discussion following the standard discussion flow (reflection → investigation → questioning → depth verification → requirements → roadmap). After the discussion, call `gsd_summary_save` with the milestone ID and `artifact_type: "CONTEXT"` to write the full context — then delete the `CONTEXT-DRAFT.md` file. The milestone is then ready for auto-planning.
    - **"Leave for later"** — Keep the draft as-is. The user will discuss it in a future session. Auto-mode will continue to pause when it reaches this milestone.
 3. Handle all draft discussions before proceeding to new queue work.
 4. If no drafts exist in the context, skip this section entirely and proceed to "What do you want to add?"
@@ -108,7 +108,7 @@ The user confirms or corrects before you write. One depth verification per miles
 Once the user is satisfied, in a single pass for **each** new milestone:
 
 1. Call `gsd_milestone_generate_id` to get the milestone ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
-2. Write `.gsd/milestones/<ID>/<ID>-CONTEXT.md` — use the **Context** output template below. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution." **If this milestone depends on other milestones, add YAML frontmatter with `depends_on`:**
+2. Call `gsd_summary_save` with `milestone_id: <ID>`, `artifact_type: "CONTEXT"`, and the full context markdown as `content` — the tool computes the file path and persists to both DB and disk. Capture intent, scope, risks, constraints, integration points, and relevant requirements in the content. Mark the status as "Queued — pending auto-mode execution." **If this milestone depends on other milestones, include YAML frontmatter with `depends_on` in the content:**
    ```yaml
    ---
    depends_on: [M001, M002]

package/src/resources/extensions/gsd/prompts/quick-task.md

@@ -21,7 +21,9 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
    - Use conventional commit messages (feat:, fix:, refactor:, etc.)
    - Stage only relevant files — never commit secrets or runtime files.
    - Commit logical units separately if the task involves distinct changes.
+   - Quick tasks run outside the auto-mode lifecycle — there is no system auto-commit, so commit directly here.
 7. Write a brief summary to `{{summaryPath}}`:
+   - Quick tasks operate outside the milestone/slice/task DB structure, so `gsd_summary_save` (which requires a `milestone_id`) cannot be used here. Write the file directly.
 
 ```markdown
 # Quick Task: {{description}}

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/resources/extensions/gsd/provider-error-pause.ts

@@ -19,6 +19,11 @@ export function classifyProviderError(errorMsg: string): {
   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);
 
@@ -37,6 +42,10 @@ export function classifyProviderError(errorMsg: string): {
     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/src/resources/extensions/gsd/repo-identity.ts

@@ -104,16 +104,17 @@ export function readRepoMeta(externalPath: string): RepoMeta | null {
  * 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: string): boolean {
   try {
@@ -124,12 +125,12 @@ export function isInheritedRepo(basePath: string): boolean {
 
     // 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"))) return false;
+    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"))) return false;
+      if (isProjectGsd(join(dir, ".gsd"))) return false;
       dir = dirname(dir);
     }
 
@@ -139,6 +140,44 @@ export function isInheritedRepo(basePath: string): boolean {
   }
 }
 
+/**
+ * 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: string): boolean {
+  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 ──────────────────────────────────────────────────────────
 
 /**