gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/dist/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/dist/resources/extensions/gsd/state.js

@@ -208,10 +208,17 @@ export async function getActiveMilestoneId(basePath) {
  * Legacy filesystem parsing is available only through an explicit opt-in for
  * tests/recovery flows; runtime must not silently infer state from markdown.
  */
-export async function deriveState(basePath) {
-    // Return cached result if within the TTL window for the same basePath
+export async function deriveState(basePath, opts) {
+    // Use the canonical project root (when provided) as the cache key so that
+    // two calls with different basePath strings (e.g. worktree path vs project
+    // root) but the same canonical .gsd/ share a single cache entry. The same
+    // key is used for both the lookup AND the write below — keying lookup on
+    // canonical-root while writing on basePath would silently return stale
+    // results across path-form alternation.
+    const cacheKey = opts?.projectRootForReads ?? basePath;
+    // Return cached result if within the TTL window for the same cacheKey
     if (_stateCache &&
-        _stateCache.basePath === basePath &&
+        _stateCache.basePath === cacheKey &&
         Date.now() - _stateCache.timestamp < CACHE_TTL_MS) {
         return _stateCache.result;
     }
@@ -230,7 +237,7 @@ export async function deriveState(basePath) {
         if (wasDbOpenAttempted()) {
             logWarning("state", "DB unavailable — using explicit legacy filesystem state derivation");
         }
-        result = await _deriveStateImpl(basePath);
+        result = await _deriveStateImpl(basePath, opts);
         _telemetry.markdownDeriveCount++;
     }
     else {
@@ -252,7 +259,7 @@ export async function deriveState(basePath) {
     }
     stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
     debugCount("deriveStateCalls");
-    _stateCache = { basePath, result, timestamp: Date.now() };
+    _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
     return result;
 }
 /**
@@ -689,7 +696,15 @@ export async function deriveStateFromDb(basePath) {
 // LEGACY: Filesystem-based state derivation for unmigrated projects.
 // DB-backed projects use deriveStateFromDb() above. Target: extract to
 // state-legacy.ts when all projects are DB-backed.
-export async function _deriveStateImpl(basePath) {
+export async function _deriveStateImpl(basePath, opts) {
+    // When the caller supplies a canonical project root for reads (e.g.
+    // s.canonicalProjectRoot from auto-mode), route all artifact reads through
+    // it. This prevents the worktree-local empty `.gsd/` from being consulted
+    // when the canonical state lives at the project root (or via a `.gsd`
+    // symlink into the external state dir).
+    if (opts?.projectRootForReads) {
+        basePath = opts.projectRootForReads;
+    }
     const diskIds = findMilestoneIds(basePath);
     const customOrder = loadQueueOrder(basePath);
     const milestoneIds = sortByQueueOrder(diskIds, customOrder);

package/dist/resources/extensions/gsd/templates/project.md

@@ -11,6 +11,16 @@
 
 {{theOneThingThatMustWorkEvenIfEverythingElseIsCut}}
 
+## Project Shape
+
+<!-- Drives questioning depth in downstream stages. `simple` → short plain-text
+     rounds, fast PROJECT/CONTEXT/REQUIREMENTS writes. `complex` → researched
+     3–4-option questions with an "Other — let me discuss" hatch.
+     Default to `complex` when uncertain. -->
+
+- **Complexity:** {{simple | complex}}
+- **Why:** {{one-line rationale citing the signals that decided it}}
+
 ## Current State
 
 {{whatHasBeenBuiltSoFar — what works, what exists, what's deployed}}

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -292,9 +292,9 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType) {
         case "execute-task":
         case "execute-task-simple":
         case "reactive-execute":
-            return ["gsd_complete_task"];
+            return ["gsd_task_complete"];
         case "complete-slice":
-            return ["gsd_complete_slice"];
+            return ["gsd_slice_complete"];
         case "replan-slice":
             return ["gsd_replan_slice"];
         case "reassess-roadmap":

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

@@ -0,0 +1,59 @@
+// GSD-2 + Workspace handle: single source of truth for path resolution per milestone
+import { join, resolve } from "node:path";
+import { resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+function tryRealpath(p) {
+    return normalizeRealPath(p);
+}
+/**
+ * Create an immutable GsdWorkspace handle from a raw base path.
+ * Resolves both the project root and (when applicable) the worktree root,
+ * normalizes them via realpath, and freezes the result.
+ */
+export function createWorkspace(rawBasePath) {
+    const resolvedBase = resolve(rawBasePath);
+    const isWorktree = isGsdWorktreePath(resolvedBase);
+    const projectRootRaw = resolveWorktreeProjectRoot(resolvedBase);
+    const projectRoot = tryRealpath(resolve(projectRootRaw));
+    const worktreeRoot = isWorktree ? tryRealpath(resolvedBase) : null;
+    // Derive a canonical base from the already-realpath-normalized paths so that
+    // resolveGsdPathContract always receives a canonical path. Using the raw
+    // resolvedBase here can produce a non-canonical projectGsd when the input
+    // path contains symlinks, causing contract.projectGsd to diverge from the
+    // realpath-normalized projectRoot / identityKey.
+    const canonicalBase = isWorktree ? (worktreeRoot ?? resolvedBase) : projectRoot;
+    const contract = Object.freeze(resolveGsdPathContract(canonicalBase));
+    const identityKey = tryRealpath(projectRoot);
+    const mode = isWorktree ? "worktree" : "project";
+    const workspace = Object.freeze({
+        projectRoot,
+        worktreeRoot,
+        mode,
+        contract,
+        identityKey,
+        lockRoot: projectRoot,
+    });
+    return workspace;
+}
+/**
+ * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
+ * with path-returning closures that resolve via the authoritative projectGsd.
+ *
+ * All milestone-content paths route to contract.projectGsd (canonical),
+ * since that is the authoritative source of truth regardless of worktree mode.
+ */
+export function scopeMilestone(workspace, milestoneId) {
+    const { contract } = workspace;
+    const gsd = contract.projectGsd;
+    const scope = Object.freeze({
+        workspace,
+        milestoneId,
+        contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
+        roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+        stateFile: () => join(gsd, "STATE.md"),
+        dbPath: () => contract.projectDb,
+        milestoneDir: () => join(gsd, "milestones", milestoneId),
+        metaJson: () => join(gsd, `${milestoneId}-META.json`),
+    });
+    return scope;
+}

package/dist/resources/extensions/gsd/worktree-resolver.js

@@ -1,3 +1,4 @@
+// GSD-2 — WorktreeResolver: encapsulates worktree path state and merge/exit lifecycle.
 /**
  * WorktreeResolver — encapsulates worktree path state and merge/exit lifecycle.
  *
@@ -20,7 +21,20 @@ import { emitJournalEvent } from "./journal.js";
 import { emitWorktreeCreated, emitWorktreeMerged } from "./worktree-telemetry.js";
 import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain } from "./slice-cadence.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "./worktree-root.js";
+import { claimMilestoneLease, releaseMilestoneLease } from "./db/milestone-leases.js";
+// ─── Path Comparison Helper ────────────────────────────────────────────────
+/**
+ * Compare two paths for physical identity, tolerating trailing slashes,
+ * symlink differences, and case variations on case-insensitive volumes.
+ *
+ * Used in place of string `===` / `!==` wherever one operand may be
+ * realpath-normalised (e.g. from the workspace registry) and the other
+ * may not be (e.g. a raw caller-supplied basePath).
+ */
+function isSamePath(a, b) {
+    return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 /**
  * Resolve the project root from session path state.
@@ -98,6 +112,69 @@ export class WorktreeResolver {
             });
             return;
         }
+        // Phase B: claim a milestone lease before any worktree mutation. Two
+        // workers cannot enter the same milestone concurrently. Best-effort:
+        // skip if no worker registered (single-worker fallback) or DB
+        // unavailable; reuse existing lease if we already hold it on this
+        // milestone (re-entry within the same session).
+        if (this.s.workerId) {
+            if (this.s.currentMilestoneId === milestoneId && this.s.milestoneLeaseToken !== null) {
+                // Already held — no-op, the heartbeat in loop.ts refreshes TTL.
+            }
+            else {
+                // If we held a different milestone, release it first so other
+                // workers don't have to wait for TTL.
+                if (this.s.currentMilestoneId && this.s.currentMilestoneId !== milestoneId && this.s.milestoneLeaseToken !== null) {
+                    try {
+                        releaseMilestoneLease(this.s.workerId, this.s.currentMilestoneId, this.s.milestoneLeaseToken);
+                    }
+                    catch (err) {
+                        debugLog("WorktreeResolver", {
+                            action: "enterMilestone",
+                            milestoneId,
+                            releasePriorLeaseError: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                    this.s.milestoneLeaseToken = null;
+                }
+                try {
+                    const claim = claimMilestoneLease(this.s.workerId, milestoneId);
+                    if (claim.ok) {
+                        this.s.milestoneLeaseToken = claim.token;
+                        debugLog("WorktreeResolver", {
+                            action: "enterMilestone",
+                            milestoneId,
+                            leaseAcquired: true,
+                            fencingToken: claim.token,
+                            expiresAt: claim.expiresAt,
+                        });
+                    }
+                    else {
+                        // Lease held by another worker — fail loud so the user can
+                        // see the conflict instead of silently double-running.
+                        const msg = `Milestone ${milestoneId} is held by worker ${claim.byWorker} until ${claim.expiresAt}.`;
+                        debugLog("WorktreeResolver", {
+                            action: "enterMilestone",
+                            milestoneId,
+                            leaseHeldByOther: claim.byWorker,
+                            expiresAt: claim.expiresAt,
+                        });
+                        ctx.notify(`${msg} Another auto-mode worker is active. Stop it before entering ${milestoneId}.`, "error");
+                        return;
+                    }
+                }
+                catch (err) {
+                    // DB unavailable or other error — log and fall through to the
+                    // pre-Phase-B single-worker behavior so a fresh project before
+                    // DB init still works.
+                    debugLog("WorktreeResolver", {
+                        action: "enterMilestone",
+                        milestoneId,
+                        leaseError: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
         // Resolve the project root for worktree operations via shared helper.
         // Handles the case where originalBasePath is falsy and basePath is itself
         // a worktree path — prevents double-nested worktree paths (#3729).
@@ -454,7 +531,7 @@ export class WorktreeResolver {
             // roadmap triggers bare teardown which deletes the branch and orphans all
             // milestone commits (#1573).
             let roadmapPath = this.deps.resolveMilestoneFile(originalBase, milestoneId, "ROADMAP");
-            if (!roadmapPath && this.s.basePath !== originalBase) {
+            if (!roadmapPath && !isSamePath(this.s.basePath, originalBase)) {
                 roadmapPath = this.deps.resolveMilestoneFile(this.s.basePath, milestoneId, "ROADMAP");
                 if (roadmapPath) {
                     debugLog("WorktreeResolver", {

package/dist/resources/extensions/gsd/write-intercept.js

@@ -85,9 +85,9 @@ function matchesBlockedPattern(path) {
  * Directs the agent to use engine tool calls instead.
  */
 export const BLOCKED_WRITE_ERROR = `Direct writes to .gsd/STATE.md and .gsd/gsd.db are blocked. Use engine tool calls instead:
-- To complete a task: call gsd_complete_task(milestone_id, slice_id, task_id, summary)
-- To complete a slice: call gsd_complete_slice(milestone_id, slice_id, summary, uat_result)
-- To save a decision: call gsd_save_decision(scope, decision, choice, rationale)
+- To complete a task: call gsd_task_complete(milestone_id, slice_id, task_id, summary)
+- To complete a slice: call gsd_slice_complete(milestone_id, slice_id, summary, uat_result)
+- To save a decision: call gsd_decision_save(scope, decision, choice, rationale)
 - To start a task: call gsd_start_task(milestone_id, slice_id, task_id)
 - To record verification: call gsd_record_verification(milestone_id, slice_id, task_id, evidence)
 - To report a blocker: call gsd_report_blocker(milestone_id, slice_id, task_id, description)`;