gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/paths.ts

@@ -1,3 +1,4 @@
+// GSD-2 — ID-based path resolution for GSD project files and directories
 /**
  * GSD Paths — ID-based path resolution
  *
@@ -10,12 +11,13 @@
  */
 
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join, dirname, normalize } from "node:path";
+import { join, dirname, normalize, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
@@ -127,9 +129,15 @@ function cachedReaddir(dirPath: string): string[] {
 }
 
 /**
- * Clear the directory listing cache.
+ * Clear the volatile directory listing caches.
  * Call after milestone transitions, file creation in planning directories,
  * or at the start/end of a dispatch cycle.
+ *
+ * NOTE: This does NOT clear gsdRootCache. The project root is stable for
+ * the lifetime of a process; clearing it on every agent turn-end caused a
+ * 250–2500 ms regression per session (git rev-parse + dir walk per turn).
+ * Use _clearGsdRootCache() at session-reset boundaries (workspace switch,
+ * process exit) when the project root may genuinely change.
  */
 export function clearPathCache(): void {
   dirEntryCache.clear();
@@ -284,13 +292,97 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
 
 // ─── GSD Root Discovery ───────────────────────────────────────────────────────
 
+// Process-lifetime cache for gsdRoot() results.
+// Keys are realpath-normalized (via normCacheKey) so /foo and /foo/ share the
+// same entry and so do case-variant paths on case-insensitive volumes. This
+// normalization is the safety net that prevents cache poisoning from the
+// ~/.gsd walk-up bug (fixed in c46cf4786 + b35e070eb), making it safe to
+// hold this cache for the entire process lifetime.
+// Use _clearGsdRootCache() only at session-reset boundaries (workspace switch,
+// process exit) — NOT inside clearPathCache(), which runs on every agent turn.
 const gsdRootCache = new Map<string, string>();
 
-/** Exported for tests only — do not call in production code. */
+export interface GsdPathContract {
+  /** Canonical repo/project root where authoritative state lives. */
+  projectRoot: string;
+  /** Current execution root, which may be an auto-worktree. */
+  workRoot: string;
+  /** Canonical authoritative .gsd directory. */
+  projectGsd: string;
+  /** Legacy worktree-local .gsd projection directory, when applicable. */
+  worktreeGsd: string | null;
+  /** Canonical authoritative SQLite DB path. */
+  projectDb: string;
+  /** True when workRoot is inside a GSD worktree layout. */
+  isWorktree: boolean;
+}
+
+export function resolveGsdPathContract(
+  workRoot: string,
+  originalProjectRoot?: string | null,
+): GsdPathContract {
+  const resolvedWorkRoot = resolve(workRoot || process.cwd());
+  const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
+  if (isWorktree && !originalProjectRoot?.trim()) {
+    const externalMatch = /[/\\]\.gsd[/\\]projects[/\\][^/\\]+[/\\]worktrees(?:[/\\]|$)/.exec(resolvedWorkRoot);
+    if (externalMatch) {
+      const worktreesIdx = externalMatch[0].search(/[/\\]worktrees(?:[/\\]|$)/);
+      const projectGsd = resolvedWorkRoot.slice(0, externalMatch.index + worktreesIdx);
+      return {
+        projectRoot: dirname(dirname(projectGsd)),
+        workRoot: resolvedWorkRoot,
+        projectGsd,
+        worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+        projectDb: join(projectGsd, "gsd.db"),
+        isWorktree,
+      };
+    }
+  }
+  const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
+  const projectGsd = join(projectRoot, ".gsd");
+  const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+
+  return {
+    projectRoot,
+    workRoot: resolvedWorkRoot,
+    projectGsd,
+    worktreeGsd,
+    projectDb: join(projectGsd, "gsd.db"),
+    isWorktree,
+  };
+}
+
+/**
+ * Invalidate the gsdRoot cache.
+ * Use ONLY at session-reset boundaries: workspace switch, process exit, or
+ * any context where the project root itself may genuinely change.
+ * Do NOT call this on every agent turn — use clearPathCache() for volatile
+ * directory listing invalidation instead.
+ */
 export function _clearGsdRootCache(): void {
   gsdRootCache.clear();
 }
 
+/**
+ * Resolve a path to its canonical real path using the native resolver.
+ * On macOS case-insensitive (HFS+/APFS) volumes, realpathSync.native normalizes
+ * case — ensuring that /foo/Bar and /foo/bar resolve to the same string.
+ * Falls back to resolve(p) for non-existent paths.
+ *
+ * Use this helper everywhere a path is used as an identity/cache key so that
+ * all callers agree on the canonical form.
+ */
+export function normalizeRealPath(p: string): string {
+  try { return realpathSync.native(p); } catch { return resolve(p); }
+}
+
+/** Normalize a path for use as a gsdRootCache key (realpath + trailing-slash strip). */
+function normCacheKey(p: string): string {
+  const r = normalizeRealPath(p);
+  const s = r.replaceAll("\\", "/").replace(/\/+$/, "");
+  return process.platform === "win32" ? s.toLowerCase() : s;
+}
+
 /**
  * Resolve the `.gsd` directory for a given project base path.
  *
@@ -300,13 +392,19 @@ export function _clearGsdRootCache(): void {
  *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
  *   4. basePath/.gsd         — creation fallback (init scenario)
  *
- * Result is cached per basePath for the process lifetime.
+ * Result is cached per normalized basePath for the process lifetime.
+ * Keys are realpath-normalized so /foo and /foo/ share the same cache entry.
  */
 export function gsdRoot(basePath: string): string {
-  const cached = gsdRootCache.get(basePath);
+  const cacheKey = normCacheKey(basePath);
+  const cached = gsdRootCache.get(cacheKey);
   if (cached) return cached;
 
-  const result = probeGsdRoot(basePath);
+  // Canonicalize result via realpath before asserting and caching so that
+  // callers always receive a canonical path regardless of whether probeGsdRoot
+  // returned a path through a symlink. Without this, the cached value can
+  // diverge from other realpath-normalized paths (e.g. workspace.identityKey).
+  const result = normalizeRealPath(probeGsdRoot(basePath));
 
   // Defense-in-depth: if basePath resolves to the user's home directory and
   // the result equals gsdHome(), refuse — project-scoped writes must never
@@ -314,7 +412,7 @@ export function gsdRoot(basePath: string): string {
   // valid (their basePath does not equal homedir).
   assertNotGlobalGsdHome(basePath, result);
 
-  gsdRootCache.set(basePath, result);
+  gsdRootCache.set(cacheKey, result);
   return result;
 }
 
@@ -378,6 +476,9 @@ function isInsideGsdWorktree(p: string): boolean {
 }
 
 function probeGsdRoot(rawBasePath: string): string {
+  const contract = resolveGsdPathContract(rawBasePath);
+  if (contract.isWorktree) return contract.projectGsd;
+
   // 1. Fast path — check the input path directly
   const local = join(rawBasePath, ".gsd");
   if (existsSync(local)) return local;
@@ -412,9 +513,21 @@ function probeGsdRoot(rawBasePath: string): string {
     }
   } catch { /* git not available */ }
 
+  // Compute gsdHome once for the skip-check used in steps 2 and 3.
+  const normPath = (p: string): string => {
+    let r: string;
+    try { r = realpathSync.native(p); } catch { r = p; }
+    const s = r.replaceAll("\\", "/").replace(/\/+$/, "");
+    return process.platform === "win32" ? s.toLowerCase() : s;
+  };
+  let gsdHomeNorm: string;
+  try { gsdHomeNorm = normPath(gsdHome()); } catch { gsdHomeNorm = ""; }
+
   if (gitRoot) {
     const candidate = join(gitRoot, ".gsd");
-    if (existsSync(candidate)) return candidate;
+    // Skip if the candidate resolves to the global GSD home — a subdir basePath
+    // must not be anchored to ~/.gsd just because $HOME is a git repo.
+    if (existsSync(candidate) && normPath(candidate) !== gsdHomeNorm) return candidate;
   }
 
   // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
@@ -422,7 +535,7 @@ function probeGsdRoot(rawBasePath: string): string {
     let cur = dirname(basePath);
     while (cur !== basePath) {
       const candidate = join(cur, ".gsd");
-      if (existsSync(candidate)) return candidate;
+      if (existsSync(candidate) && normPath(candidate) !== gsdHomeNorm) return candidate;
       if (cur === gitRoot) break;
       basePath = cur;
       cur = dirname(cur);

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

@@ -28,7 +28,7 @@ This unit runs under the `planning-dispatch` tools-policy: you may use the `suba
 - **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
 - **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
 
-Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_slice_complete` with `milestoneId` and `sliceId`.
 
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
@@ -37,11 +37,11 @@ Then:
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. Address every gate listed in the **Gates to Close** section above — each gate maps to a specific slice-summary section the handler inspects (for example, Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, and monitoring gaps). Leaving a section empty records the gate as `omitted`.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
-7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
+7. Prepare the slice completion content you will pass to `gsd_slice_complete` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
 8. Draft the UAT content you will pass as `uatContent` — 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. Fill the `UAT Type` and `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven (e.g. live integration paths, performance under load, scenarios deferred to a later slice).
 9. Review task summaries for `key_decisions`. For each significant decision, call `capture_thought` with `category: "architecture"` (or `"pattern"`) and a `structuredFields` payload of `{ scope, decision, choice, rationale, made_by: "agent", revisable }`.
 10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. For each one that would save future agents from repeating investigation, call `capture_thought` with the matching category (`gotcha`, `convention`, `pattern`, `environment`). The memory store is the single source of truth (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
-11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.
+11. Call `gsd_slice_complete` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates 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: 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.
 
@@ -49,6 +49,6 @@ Then:
 
 **File system safety:** Task summaries are preloaded in the inlined context above. Task artifacts use a **flat file layout** — files such as `T01-SUMMARY.md` and `T02-SUMMARY.md` live directly inside the `tasks/` directory, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first. Never use `tasks/*/SUMMARY.md`, and never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
 
-**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.**
+**You MUST call `gsd_slice_complete` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
 When done, say: "Slice {{sliceId}} complete."

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

@@ -85,14 +85,14 @@ Then:
 17. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, call `capture_thought` with `category: "architecture"` (or `"pattern"`). For decisions, populate `structuredFields` with `{ scope, decision, choice, rationale, made_by: "agent", revisable }` so future projection back to a human-visible decisions register stays lossless. Not every task produces decisions — only capture when a meaningful choice was made.
 18. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, call `capture_thought` with `category: "gotcha"`, `"convention"`, `"pattern"`, or `"environment"` as appropriate. Only capture entries that would save future agents from repeating your investigation — don't capture obvious things. The memory store is the single source of truth for cross-session knowledge (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
 19. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
-20. Use that template to prepare the completion content you will pass to `gsd_complete_task` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you.
-21. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically.
+20. Use that template to prepare the completion content you will pass to `gsd_task_complete` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you.
+21. Call `gsd_task_complete` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically.
 22. 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` before finishing. Do not manually write `{{taskSummaryPath}}`.**
+**You MUST call `gsd_task_complete` before finishing. Do not manually write `{{taskSummaryPath}}`.**
 
 When done, say: "Task {{taskId}} complete."

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

@@ -12,6 +12,13 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, a
 
 {{fastPathInstruction}}
 
+### Read project shape
+
+Before your first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. The verdict is either **`simple`** or **`complex`** (default to `complex` if PROJECT.md is missing the section, predates this convention, or the value is unclear). The verdict scales the rest of this stage:
+
+- **`simple`** — favor 1–2 plain-text question rounds. Skip the parallel-research investigation. Skip `ask_user_questions` unless presenting concrete alternatives.
+- **`complex`** — full investigation, 3–4-option structured questions, multi-round.
+
 ### Before your first question round
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -36,7 +43,7 @@ Ask **1–3 questions per round**. Keep each question focused on one of:
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple calls with the same or overlapping questions — wait for the user's response before asking the next round.**
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine when alternatives are genuinely binary. Binary depth-check / wrap-up gates are exempt from the 3-or-4 rule. When the user picks "Other — let me discuss" or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple calls with the same or overlapping questions — wait for the user's response before asking the next round.**
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round.
 

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

@@ -26,6 +26,18 @@ Ask the user a single freeform question in plain text, not structured: **"What d
 
 Wait for their response. This grounds every follow-up in their own terminology.
 
+### Classify project shape
+
+After the opening answer, classify the project as **`simple`** or **`complex`** before continuing. Print the verdict in chat as one line: `Project shape: simple` or `Project shape: complex` followed by a one-line rationale.
+
+**`simple`** — most of these apply: single primary user (the user themselves or one immediate team), no external integrations beyond well-known SDKs/libs, greenfield or self-contained, scope describable in 1–2 sentences without ambiguity, no compliance/regulatory needs, ≤5 distinct capabilities.
+
+**`complex`** — any of these apply: multi-user with roles/permissions, non-trivial brownfield codebase, external integrations with auth/data exchange, compliance/security/regulated domain (PII, payments, healthcare), >5 capabilities or unclear scope, cross-team/cross-org coordination, novel domain where assumptions need validation.
+
+**Default to `complex` when uncertain.** The user can override the verdict in plain text; if they do, accept it and proceed.
+
+The verdict drives the rest of this stage and gets persisted to PROJECT.md → `## Project Shape`. Downstream stages (`discuss-requirements`, `discuss-milestone`, `discuss-slice`) read it from there.
+
 ### Before deeper rounds
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -50,9 +62,11 @@ Ask **1–3 questions per round**. Each round targets one of:
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**Plain-text default:** Project discovery is open-ended. Ask question rounds in plain text unless you are presenting 2–3 concrete alternatives with clear tradeoffs.
+**Cadence is shape-dependent:**
+- **`simple`** — favor 1–2 plain-text rounds. Skip `ask_user_questions` unless you are presenting concrete alternatives. Get to the depth checklist fast.
+- **`complex`** — full investigation, multiple rounds, structured questions when meaningful alternatives exist.
 
-**If `{{structuredQuestionsAvailable}}` is `true` and you use `ask_user_questions`:** ask 1–3 questions per call. Every question object MUST include a stable lowercase `id`. Keep option labels short (3–5 words). Do not add a separate "Other" option; the question UI provides a freeform path automatically. Wait for each tool result before asking the next round.
+**If `{{structuredQuestionsAvailable}}` is `true` and you use `ask_user_questions`:** ask 1–3 questions per call. Every question object MUST include a stable lowercase `id`. Keep option labels short (3–5 words). In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option; options must be grounded in your investigation (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine. Binary depth-check / wrap-up gates are exempt from the 3-or-4 rule. Wait for each tool result before asking the next round.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions.
 
@@ -126,8 +140,9 @@ Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
 2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing.
-3. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
-4. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
-5. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.
-6. {{commitInstruction}}
-7. Say exactly: `"Project context written."` — nothing else.
+3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
+4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
+5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
+6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.
+7. {{commitInstruction}}
+8. Say exactly: `"Project context written."` — nothing else.

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

@@ -21,9 +21,13 @@ Before your first action, print this banner verbatim in chat:
 ## Pre-flight
 
 1. Read `.gsd/PROJECT.md` end-to-end. If it does not exist, STOP and emit: `"PROJECT.md missing — run discuss-project first."`
-2. Extract: Core Value, Anti-goals, Constraints, Milestone Sequence.
+2. Extract: Core Value, Anti-goals, Constraints, Milestone Sequence, and the project shape verdict — read the `## Project Shape` section and look for `**Complexity:**` (verdict is either `simple` or `complex`; default to `complex` if the section is missing or unclear).
 3. Check for existing `.gsd/REQUIREMENTS.md` — if present, this is a refinement pass, not a fresh write. Read existing requirements and treat them as the working set.
 
+**Shape-dependent cadence:**
+- **`simple`** — favor a single fast pass: extract requirements directly from PROJECT.md, ask 1–2 plain-text clarifying questions only if a class or status assignment is genuinely ambiguous, then write REQUIREMENTS.md.
+- **`complex`** — full multi-round questioning with structured 3–4-option questions where alternatives matter.
+
 ---
 
 ## Interview Protocol
@@ -51,7 +55,7 @@ Ask **1–3 questions per round**. Each round targets one dimension:
 
 **Never fabricate or simulate user input.** Wait for actual responses.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. Every question object MUST include a stable lowercase `id`. For class assignments, present the allowed classes as multi-select options. For status, present the four statuses as exclusive options. Ask 1–3 questions per call. Wait for each tool result before asking the next round.
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. Every question object MUST include a stable lowercase `id`. For class assignments, present the allowed classes as multi-select options. For status, present the four statuses as exclusive options. In **`complex`** mode, any free-form question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option grounded in the investigation above. The class-assignment and status questions are exempt — they have fixed enumerations. Ask 1–3 questions per call. Wait for each tool result before asking the next round.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text. Keep each round to 1–3 questions.
 

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

@@ -8,6 +8,13 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve
 
 ## Interview Protocol
 
+### Read project shape
+
+Before your first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. The verdict is either **`simple`** or **`complex`** (default to `complex` if the section is missing or unclear).
+
+- **`simple`** — favor 1–2 plain-text rounds, write the slice context fast. Skip parallel-research investigation.
+- **`complex`** — full investigation with structured 3–4-option questions.
+
 ### Before your first question round
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -24,7 +31,7 @@ Do **not** go deep — just enough that your questions reflect what's actually t
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
+**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine. Binary wrap-up gates are exempt from the 3-or-4 rule. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
 **If `{{structuredQuestionsAvailable}}` is `false`:** Ask **1–3 questions per round** in plain text. Number them and wait for the user's response before asking the next round.
 Keep each question focused on one of:
 - **UX and user-facing behaviour** — what does the user see, click, trigger, or experience?

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

@@ -10,6 +10,12 @@ All relevant context has been preloaded below — start working immediately with
 
 {{inlinedContext}}
 
+## Already Planned? Soft Brake
+
+If `{{outputPath}}` already exists on disk with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call `gsd_plan_milestone` — its UPSERT would overwrite the existing plan with whatever you reconstruct, which is unsafe when you don't have the original decomposition reasoning. Skip directly to the ready phrase at the end of this prompt.
+
+If only the file exists (no DB rows) or only DB rows exist (no file), the prior write was incomplete — proceed with planning as normal so the tool reconciles both.
+
 ## Your Role in the Pipeline
 
 You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.

package/src/resources/extensions/gsd/queue-order.ts

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { isDbAvailable, setMilestoneQueueOrder } from "./gsd-db.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -63,9 +64,13 @@ export function loadQueueOrder(basePath: string): string[] | null {
 }
 
 /**
- * Save a custom queue order to disk.
+ * Save a custom queue order. The DB sequence is canonical when a DB
+ * connection is open; QUEUE-ORDER.json remains a compatibility projection.
  */
 export function saveQueueOrder(basePath: string, order: string[]): void {
+  if (isDbAvailable()) {
+    setMilestoneQueueOrder(order);
+  }
   const data: QueueOrderFile = {
     order,
     updatedAt: new Date().toISOString(),

package/src/resources/extensions/gsd/rethink.ts

@@ -20,7 +20,7 @@ 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";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 
@@ -34,7 +34,7 @@ export async function handleRethink(
     return;
   }
 
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const root = gsdRoot(basePath);
   if (!existsSync(root)) {
     ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");