gsd-pi 2.57.0 → 2.58.0-dev.394cb18

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -26,7 +26,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 4. Check **requirement coverage** — are all active requirements addressed by at least one slice?
 5. If **Verification Classes** are provided in the inlined context above, check each non-empty class:
    - For each verification class (Contract, Integration, Operational, UAT), determine whether slice summaries, UAT results, or observable behavior provide evidence that this verification tier was addressed.
-   - Document the compliance status of each class in your verdict rationale.
+   - Document the compliance status of each class in a dedicated verification classes section.
    - If `Operational` verification is non-empty and no evidence of operational verification exists, flag this explicitly — it means planned operational checks (migrations, deployments, runtime verification) were not proven.
    - A milestone with unaddressed verification classes may still pass if the gaps are minor, but the gaps MUST be documented in the Deferred Work Inventory.
 6. Determine a verdict:
@@ -36,7 +36,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 ## Persist Validation
 
-**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.
+**Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verificationClasses` (when non-empty), `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`:
 - 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.

package/src/resources/extensions/gsd/repo-identity.ts

@@ -8,7 +8,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";
 
@@ -276,9 +276,14 @@ export function validateProjectId(id: string): boolean {
  * 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: string): string {
   const projectId = process.env.GSD_PROJECT_ID;
@@ -286,8 +291,14 @@ export function repoIdentity(basePath: string): string {
     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);
 }
 
@@ -351,21 +362,148 @@ export function cleanNumberedGsdVariants(projectPath: string): string[] {
   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: string, identity: string): void {
+  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: string): string | null {
+  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: string): boolean {
+  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: string): string {
+  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: string): string {
-  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: string): string {
+  const externalPath = resolveExternalPathWithRecovery(projectPath);
   const localGsd = join(projectPath, ".gsd");
   const inWorktree = isInsideWorktree(projectPath);
 
@@ -418,12 +556,28 @@ export function ensureGsdSymlink(projectPath: string): string {
 
   const replaceWithSymlink = (): string => {
     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;
   }
@@ -442,6 +596,27 @@ export function ensureGsdSymlink(projectPath: string): string {
       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/src/resources/extensions/gsd/rethink.ts

@@ -19,6 +19,7 @@ import { isParked, 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 ──────────────────────────────────────────────────────────────
 
@@ -53,9 +54,14 @@ export async function handleRethink(
   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(

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -219,13 +219,14 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
 function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] {
   const slices: RoadmapSliceEntry[] = [];
   // 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: RegExpExecArray | null;
 
   // 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]!;
@@ -251,7 +252,7 @@ function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] {
 
     // 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);