gsd-pi 2.58.0 → 2.59.0-dev.023bd39

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

@@ -24,27 +24,27 @@ export { validatePreferences } from "./preferences-validation.js";
 // ─── Re-exports: skills ─────────────────────────────────────────────────────
 export { resolveAllSkillReferences, resolveSkillDiscoveryMode, resolveSkillStalenessDays, } from "./preferences-skills.js";
 // ─── Re-exports: models ─────────────────────────────────────────────────────
-export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
+export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 function gsdHome() {
     return process.env.GSD_HOME || join(homedir(), ".gsd");
 }
 function globalPreferencesPath() {
-    return join(gsdHome(), "PREFERENCES.md");
+    return join(gsdHome(), "preferences.md");
 }
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+    return join(gsdRoot(process.cwd()), "preferences.md");
 }
-// Legacy: older versions used lowercase preferences.md.
-// Check lowercase as a fallback so those files aren't silently ignored.
-function globalPreferencesPathLegacy() {
-    return join(gsdHome(), "preferences.md");
+// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
+// Check uppercase as a fallback so those files aren't silently ignored.
+function globalPreferencesPathUppercase() {
+    return join(gsdHome(), "PREFERENCES.md");
 }
-function projectPreferencesPathLegacy() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+function projectPreferencesPathUppercase() {
+    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -58,12 +58,12 @@ export function getProjectGSDPreferencesPath() {
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
     return loadPreferencesFile(globalPreferencesPath(), "global")
-        ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global")
+        ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 export function loadProjectGSDPreferences() {
     return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project");
+        ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
 }
 export function loadEffectiveGSDPreferences() {
     const globalPreferences = loadGlobalGSDPreferences();
@@ -149,7 +149,7 @@ export function parsePreferencesMarkdown(content) {
     }
     if (!_warnedUnrecognizedFormat) {
         _warnedUnrecognizedFormat = true;
-        console.warn("[parsePreferencesMarkdown] PREFERENCES.md exists but uses an unrecognized format — skipping.");
+        console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
     }
     return null;
 }
@@ -289,9 +289,6 @@ function mergePreferences(base, override) {
         service_tier: override.service_tier ?? base.service_tier,
         forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
         show_token_cost: override.show_token_cost ?? base.show_token_cost,
-        experimental: (base.experimental || override.experimental)
-            ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) }
-            : undefined,
     };
 }
 function mergeStringLists(base, override) {
@@ -412,7 +409,7 @@ export function resolvePreDispatchHooks() {
  * Resolve the effective git isolation mode from preferences.
  * Returns "none" (default), "worktree", or "branch".
  *
- * Default is "none" so GSD works out of the box without PREFERENCES.md.
+ * Default is "none" so GSD works out of the box without preferences.md.
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */

package/dist/resources/extensions/gsd/prompt-loader.js

@@ -124,7 +124,10 @@ export function loadPrompt(name, vars = {}) {
         }
     }
     for (const [key, value] of Object.entries(effectiveVars)) {
-        content = content.replaceAll(`{{${key}}}`, value);
+        // Use split/join instead of replaceAll to avoid JavaScript's special
+        // replacement patterns ($', $`, $&) being interpreted in the value.
+        // See: https://github.com/gsd-build/gsd-2/issues/2968
+        content = content.split(`{{${key}}}`).join(value);
     }
     return content.trim();
 }

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

@@ -56,7 +56,7 @@ Then:
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
 10. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
-11. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
+11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
 12. 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`.
 13. Do not commit manually — the system auto-commits your changes after this unit completes.
 - Say: "Milestone {{milestoneId}} complete."

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

@@ -29,9 +29,11 @@ Then:
 8. 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.
 9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 10. 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.
-11. 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. Call `gsd_complete_slice` with milestoneId, sliceId, 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.
 12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
+
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 

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

@@ -38,7 +38,7 @@ Do a mandatory investigation pass before making any decisions. This is not optio
 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the spec references external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
 
 **Web search budget:** Budget carefully across investigation + focused research:
-- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation.
+- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation.
 - Prefer `search_and_read` for one-shot topic research.
 - Target 2-3 web searches in this investigation pass. Save remaining budget for focused research.
 - Do NOT repeat the same or similar queries.

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

@@ -37,7 +37,7 @@ Before asking your first question, do a mandatory investigation pass. This is no
 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the user referenced external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
 
 **Web search budget:** You have a limited number of web searches per turn (typically 3-5). The discuss phase spans many turns (investigation, question rounds, focused research, requirements), so budget carefully:
-- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation — they don't consume the web search budget.
+- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation — they don't consume the web search budget.
 - Prefer `search_and_read` for one-shot topic research — it combines search + page fetch in a single call.
 - Target 2-3 web searches in the investigation pass. Save remaining budget for the focused research pass before roadmap creation.
 - Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on.

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

@@ -68,11 +68,13 @@ Then:
 17. 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.
 18. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 19. Write `{{taskSummaryPath}}`
-20. 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.
+20. Call `gsd_complete_task` with milestoneId, sliceId, taskId, 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.
 21. 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}}`.
 
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the task summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
+
 **You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.**
 
 When done, say: "Task {{taskId}} complete."

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

@@ -102,6 +102,8 @@ A stale lock (PID is dead) means the previous auto-mode session crashed mid-unit
 
 A unit dispatched more than once (`type/id` appears multiple times) indicates a stuck loop — the unit completed but artifact verification failed.
 
+{{dedupSection}}
+
 ## Investigation Protocol
 
 1. **Start with the pre-parsed forensic report** above. The anomaly section contains automated findings — treat these as leads, not conclusions.
@@ -133,8 +135,6 @@ Explain your findings:
 - **Code snippet** — the problematic code and what it should do instead
 - **Recovery** — what the user can do right now to get unstuck
 
-{{dedupSection}}
-
 Then **offer GitHub issue creation**: "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?"
 
 **CRITICAL: The `github_issues` tool ONLY targets the current user's repository — it has no `repo` parameter. You MUST use `gh issue create --repo gsd-build/gsd-2` via the `bash` tool to file on the correct repo. Do NOT use the `github_issues` tool for this.**

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

@@ -13,7 +13,7 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, a
 Do a lightweight targeted investigation so your questions are grounded in reality:
 - Scout the codebase (`rg`, `find`, or `scout`) to understand what already exists that this milestone touches or builds on
 - Check the roadmap context above (if present) to understand what surrounds this milestone
-- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `web_search` for library documentation
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation
 - Identify the 3–5 biggest behavioural and architectural unknowns: things where the user's answer will materially change what gets built
 
 **Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them.

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

@@ -13,7 +13,7 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve
 Do a lightweight targeted investigation so your questions are grounded in reality:
 - Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on
 - Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it
-- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `web_search` for library documentation
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation
 - Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built
 
 **Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them.

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

@@ -82,6 +82,8 @@ Then:
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.
 
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the plan. If a decision genuinely requires human input, write a note in the relevant task's description and call `gsd_plan_slice` with what you have.
+
 **You MUST call `gsd_plan_slice` to persist the planning state before finishing.**
 
 When done, say: "Slice {{sliceId}} planned."

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

@@ -80,4 +80,4 @@ If a proposed order would violate constraints, explain the issue and suggest alt
 - 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)
+- {{commitInstruction}}

package/dist/resources/extensions/gsd/prompts/triage-captures.md

@@ -54,6 +54,7 @@ For each capture, classify it as one of:
    - Add `**Resolution:** <brief description of what will happen>`
    - Add `**Rationale:** <why this classification>`
    - Add `**Resolved:** <current ISO timestamp>`
+   - Add `**Milestone:** <current milestone ID>` (e.g., `**Milestone:** M003`)
 
 4. **Summarize** what was triaged: how many captures, what classifications were assigned, and what actions are pending (e.g., "2 quick-tasks ready for execution, 1 deferred to S03").
 

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

@@ -7,7 +7,7 @@
  */
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
@@ -255,9 +255,14 @@ export function validateProjectId(id) {
  * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected
  * to have already happened at startup via `validateProjectId`).
  *
- * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated
- * to 12 hex chars. Deterministic: same repo always produces the same hash
- * regardless of which worktree the caller is inside.
+ * For repos with a remote URL, returns SHA-256 of the remote URL only —
+ * this makes the identity stable across directory moves/renames (#2750).
+ *
+ * For local-only repos (no remote), includes the git root in the hash.
+ * Local repos use a `.gsd-id` marker file for recovery after moves.
+ *
+ * Deterministic: same repo always produces the same hash regardless of
+ * which worktree the caller is inside.
  */
 export function repoIdentity(basePath) {
     const projectId = process.env.GSD_PROJECT_ID;
@@ -265,8 +270,14 @@ export function repoIdentity(basePath) {
         return projectId;
     }
     const remoteUrl = getRemoteUrl(basePath);
+    if (remoteUrl) {
+        // Remote URL alone uniquely identifies the repo — path is redundant.
+        // This makes moves transparent for repos with remotes (#2750).
+        return createHash("sha256").update(remoteUrl).digest("hex").slice(0, 12);
+    }
+    // Local-only repo: include git root since there's no remote to anchor identity.
     const root = resolveGitRoot(basePath);
-    const input = `${remoteUrl}\n${root}`;
+    const input = `\n${root}`;
     return createHash("sha256").update(input).digest("hex").slice(0, 12);
 }
 // ─── External State Directory ───────────────────────────────────────────────
@@ -325,20 +336,149 @@ export function cleanNumberedGsdVariants(projectPath) {
     }
     return removed;
 }
+// ─── .gsd-id Marker ─────────────────────────────────────────────────────────
+/**
+ * Write a `.gsd-id` marker file in the project root.
+ *
+ * This file records the identity hash used for the external state directory.
+ * For local-only repos (no remote), this marker survives directory moves and
+ * enables automatic recovery of orphaned state (#2750).
+ *
+ * The marker is gitignored by ensureGitignore(). Non-fatal: failure to write
+ * the marker must never block project setup.
+ */
+function writeGsdIdMarker(projectPath, identity) {
+    try {
+        const markerPath = join(projectPath, ".gsd-id");
+        // Only write if content differs to avoid unnecessary disk writes.
+        if (existsSync(markerPath)) {
+            try {
+                if (readFileSync(markerPath, "utf-8").trim() === identity)
+                    return;
+            }
+            catch { /* fall through and overwrite */ }
+        }
+        writeFileSync(markerPath, identity + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal — marker write failure should not block project setup
+    }
+}
+/**
+ * Read the `.gsd-id` marker from the project root.
+ * Returns the identity hash, or null if the marker doesn't exist or is unreadable.
+ */
+function readGsdIdMarker(projectPath) {
+    try {
+        const markerPath = join(projectPath, ".gsd-id");
+        if (!existsSync(markerPath))
+            return null;
+        const content = readFileSync(markerPath, "utf-8").trim();
+        return /^[a-zA-Z0-9_-]+$/.test(content) ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check whether an external state directory has meaningful content.
+ * Returns true if the directory contains any files or subdirectories
+ * beyond just repo-meta.json.
+ */
+function hasProjectState(externalPath) {
+    try {
+        if (!existsSync(externalPath))
+            return false;
+        const entries = readdirSync(externalPath);
+        return entries.some(e => e !== "repo-meta.json");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the external state directory, with recovery for relocated projects.
+ *
+ * For local-only repos where the computed identity produces an empty state dir,
+ * checks the `.gsd-id` marker for the original identity hash and recovers
+ * the old state directory if it still exists and contains data (#2750).
+ *
+ * Returns the resolved external path (may differ from the computed identity).
+ */
+function resolveExternalPathWithRecovery(projectPath) {
+    const computedPath = externalGsdRoot(projectPath);
+    const computedId = repoIdentity(projectPath);
+    // Check if computed path already has state — fast path, no recovery needed.
+    if (hasProjectState(computedPath)) {
+        return computedPath;
+    }
+    // Check for .gsd-id marker from a previous location.
+    const markerId = readGsdIdMarker(projectPath);
+    if (markerId && markerId !== computedId) {
+        // The marker points to a different identity — the repo was likely moved.
+        const base = process.env.GSD_STATE_DIR || gsdHome;
+        const markerPath = join(base, "projects", markerId);
+        if (hasProjectState(markerPath)) {
+            // Recover: use the old state directory and update the marker to the new identity.
+            // Move the state from the old hash dir to the new one so future lookups work
+            // without the marker.
+            try {
+                mkdirSync(computedPath, { recursive: true });
+                const entries = readdirSync(markerPath);
+                for (const entry of entries) {
+                    try {
+                        const src = join(markerPath, entry);
+                        const dst = join(computedPath, entry);
+                        // Use rename for same-filesystem (fast) or fall back to copy.
+                        try {
+                            renameSync(src, dst);
+                        }
+                        catch {
+                            cpSync(src, dst, { recursive: true, force: true });
+                        }
+                    }
+                    catch { /* continue with remaining entries */ }
+                }
+                // Clean up old directory after successful migration.
+                try {
+                    rmSync(markerPath, { recursive: true, force: true });
+                }
+                catch { /* non-fatal */ }
+            }
+            catch {
+                // If migration fails, just point at the old directory.
+                return markerPath;
+            }
+        }
+    }
+    return computedPath;
+}
 // ─── Symlink Management ─────────────────────────────────────────────────────
 /**
  * Ensure the `<project>/.gsd` symlink points to the external state directory.
  *
  * 1. Clean up any macOS numbered collision variants (`.gsd 2`, `.gsd 3`, etc.)
- * 2. mkdir -p the external dir
- * 3. If `<project>/.gsd` doesn't exist → create symlink
- * 4. If `<project>/.gsd` is already the correct symlink → no-op
- * 5. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
+ * 2. Resolve external dir (with relocation recovery via `.gsd-id` marker)
+ * 3. mkdir -p the external dir
+ * 4. If `<project>/.gsd` doesn't exist → create symlink
+ * 5. If `<project>/.gsd` is already the correct symlink → no-op
+ * 6. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
+ * 7. Write `.gsd-id` marker for future relocation recovery
  *
  * Returns the resolved external path.
  */
 export function ensureGsdSymlink(projectPath) {
-    const externalPath = externalGsdRoot(projectPath);
+    const result = ensureGsdSymlinkCore(projectPath);
+    // Write .gsd-id marker so future relocations can recover this state (#2750).
+    // Only write for the project root (not subdirectories or worktrees that
+    // delegate to a parent .gsd).
+    if (!isInsideWorktree(projectPath)) {
+        writeGsdIdMarker(projectPath, repoIdentity(projectPath));
+    }
+    return result;
+}
+function ensureGsdSymlinkCore(projectPath) {
+    const externalPath = resolveExternalPathWithRecovery(projectPath);
     const localGsd = join(projectPath, ".gsd");
     const inWorktree = isInsideWorktree(projectPath);
     // Guard: Never create a symlink at ~/.gsd — that's the user-level GSD home,
@@ -387,11 +527,34 @@ export function ensureGsdSymlink(projectPath) {
     writeRepoMeta(externalPath, getRemoteUrl(projectPath), resolveGitRoot(projectPath));
     const replaceWithSymlink = () => {
         rmSync(localGsd, { recursive: true, force: true });
+        // Defensive: remove any residual entry (e.g. dangling symlink) before creating.
+        try {
+            unlinkSync(localGsd);
+        }
+        catch { /* already gone */ }
         symlinkSync(externalPath, localGsd, "junction");
         return externalPath;
     };
+    // Check for dangling symlinks (e.g. after relocation recovery removed the old
+    // state dir). existsSync follows symlinks, so it returns false for dangling ones.
+    // lstatSync does NOT follow, so we can detect the dangling symlink and replace it.
     if (!existsSync(localGsd)) {
-        // Nothing exists yet — create symlink
+        try {
+            const stat = lstatSync(localGsd);
+            if (stat.isSymbolicLink()) {
+                // Dangling symlink — replace with correct one (#2750).
+                return replaceWithSymlink();
+            }
+        }
+        catch {
+            // lstat also failed — nothing exists at this path
+        }
+        // Nothing exists yet — create symlink.
+        // Defensive: remove any residual entry to avoid EEXIST race (#2750).
+        try {
+            unlinkSync(localGsd);
+        }
+        catch { /* nothing to remove */ }
         symlinkSync(externalPath, localGsd, "junction");
         return externalPath;
     }
@@ -408,6 +571,37 @@ export function ensureGsdSymlink(projectPath) {
             if (inWorktree) {
                 return replaceWithSymlink();
             }
+            // After identity hash change (e.g. upgrade from path-based to remote-only
+            // hash, or relocation recovery), migrate data from old target to new path
+            // and update the symlink (#2750).
+            if (!hasProjectState(externalPath) && hasProjectState(target)) {
+                try {
+                    mkdirSync(externalPath, { recursive: true });
+                    const oldEntries = readdirSync(target);
+                    for (const entry of oldEntries) {
+                        try {
+                            const src = join(target, entry);
+                            const dst = join(externalPath, entry);
+                            try {
+                                renameSync(src, dst);
+                            }
+                            catch {
+                                cpSync(src, dst, { recursive: true, force: true });
+                            }
+                        }
+                        catch { /* continue */ }
+                    }
+                    try {
+                        rmSync(target, { recursive: true, force: true });
+                    }
+                    catch { /* non-fatal */ }
+                    return replaceWithSymlink();
+                }
+                catch {
+                    // Migration failed — preserve old symlink
+                    return target;
+                }
+            }
             // Outside worktrees, preserve custom overrides or legacy symlinks.
             return target;
         }

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

@@ -16,6 +16,7 @@ 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";
+import { isGsdGitignored } from "./gitignore.js";
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 export async function handleRethink(_args, ctx, pi) {
     if (isAutoActive()) {
@@ -38,9 +39,13 @@ export async function handleRethink(_args, ctx, pi) {
     const queueOrder = loadQueueOrder(basePath);
     const rethinkData = buildRethinkData(basePath, milestoneIds, state, queueOrder);
     const existingMilestonesContext = await buildExistingMilestonesContext(basePath, milestoneIds, state);
+    const commitInstruction = isGsdGitignored(basePath)
+        ? "Do not commit planning artifacts — .gsd/ is gitignored in this project."
+        : '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)';
     const content = loadPrompt("rethink", {
         rethinkData,
         existingMilestonesContext,
+        commitInstruction,
     });
     pi.sendMessage({ customType: "gsd-rethink", content, display: false }, { triggerTurn: true });
 }

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

@@ -211,12 +211,13 @@ export function parseRoadmapSlices(content) {
 function parseProseSliceHeaders(content) {
     const slices = [];
     // Match H1-H4 headers containing S<digits> with optional "Slice" prefix, bold markers,
-    // and optional checkmark completion marker before the slice ID.
+    // numeric prefixes (e.g., "1.", "(1)"), bracketed IDs (e.g., "[S01]"),
+    // optional checkmark completion marker, and optional leading indentation.
     // Separator after the ID is flexible: colon, dash, em/en dash, dot, or just whitespace.
-    const headerPattern = /^#{1,4}\s+\*{0,2}(?:\u2713\s+)?(?:Slice\s+)?(S\d+)\*{0,2}[:\s.\u2014\u2013-]*\s*(.+)/gm;
+    const headerPattern = /^\s*#{1,4}\s+\*{0,2}(?:\u2713\s+)?(?:\d+[.)]\s+)?(?:\(\d+\)\s+)?(?:Slice\s+)?\[?(S\d+)\]?\*{0,2}[:\s.\u2014\u2013-]*\s*(.+)/gm;
     let match;
     // Check for checkmark before the slice ID (e.g., "## checkmark S01: Title")
-    const prefixCheckPattern = /^#{1,4}\s+\*{0,2}\u2713\s+/;
+    const prefixCheckPattern = /^\s*#{1,4}\s+\*{0,2}\u2713\s+/;
     while ((match = headerPattern.exec(content)) !== null) {
         const id = match[1];
         let title = match[2].trim().replace(/\*{1,2}$/g, "").trim(); // strip trailing bold markers
@@ -238,7 +239,7 @@ function parseProseSliceHeaders(content) {
         }
         // Try to extract depends from prose: "Depends on: S01" or "**Depends on:** S01, S02"
         const afterHeader = content.slice(match.index + match[0].length);
-        const nextHeader = afterHeader.search(/^#{1,4}\s/m);
+        const nextHeader = afterHeader.search(/^\s*#{1,4}\s/m);
         const section = nextHeader !== -1 ? afterHeader.slice(0, nextHeader) : afterHeader.slice(0, 500);
         const depsMatch = section.match(/\*{0,2}Depends\s+on:?\*{0,2}\s*(.+)/i);
         let depends = [];