gsd-pi 2.8.0 → 2.8.2

package/src/resources/extensions/gsd/git-service.ts

@@ -27,6 +27,7 @@ export interface GitPreferences {
   pre_merge_check?: boolean | string;
   commit_type?: string;
   main_branch?: string;
+  merge_strategy?: "squash" | "merge";
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -55,7 +56,7 @@ export interface PreMergeCheckResult {
  * GSD runtime paths that should be excluded from smart staging.
  * These are transient/generated artifacts that should never be committed.
  * Matches the union of SKIP_PATHS + SKIP_EXACT in worktree-manager.ts
- * and the first 6 entries in gitignore.ts BASELINE_PATTERNS.
+ * and the first 7 entries in gitignore.ts BASELINE_PATTERNS.
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/activity/",
@@ -63,6 +64,7 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/worktrees/",
   ".gsd/auto.lock",
   ".gsd/metrics.json",
+  ".gsd/completed-units.json",
   ".gsd/STATE.md",
 ];
 
@@ -130,16 +132,42 @@ export class GitServiceImpl {
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
     const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
-    const excludes = allExclusions.map(p => `':(exclude)${p}'`);
-    const args = ["add", "-A", "--", ".", ...excludes];
-    try {
-      this.git(args);
-    } catch {
-      console.error("GitService: smart staging failed, falling back to git add -A");
-      this.git(["add", "-A"]);
+
+    // One-time cleanup: if runtime files are already tracked in the index
+    // (from older versions where the fallback bug staged them), untrack them
+    // in a dedicated commit. This must happen as a separate commit because
+    // the git reset HEAD step below would otherwise undo the rm --cached.
+    if (!this._runtimeFilesCleanedUp) {
+      let cleaned = false;
+      for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
+        const result = this.git(["rm", "--cached", "-r", "--ignore-unmatch", exclusion], { allowFailure: true });
+        if (result && result.includes("rm '")) cleaned = true;
+      }
+      if (cleaned) {
+        this.git(["commit", "-F", "-"], { input: "chore: untrack .gsd/ runtime files from git index" });
+      }
+      this._runtimeFilesCleanedUp = true;
+    }
+
+    // Stage everything, then unstage excluded paths.
+    //
+    // Previous approach used pathspec excludes (:(exclude)...) with git add -A,
+    // but that fails when .gsd/ is in .gitignore — git exits non-zero before
+    // evaluating the excludes. The catch fallback ran plain `git add -A`,
+    // staging all tracked runtime files unconditionally and defeating the
+    // exclusion list entirely.
+    //
+    // git reset HEAD silently succeeds when the path isn't staged, so no
+    // error handling is needed per-path.
+    this.git(["add", "-A"]);
+    for (const exclusion of allExclusions) {
+      this.git(["reset", "HEAD", "--", exclusion], { allowFailure: true });
     }
   }
 
+  /** Tracks whether runtime file cleanup has run this session. */
+  private _runtimeFilesCleanedUp = false;
+
   /**
    * Stage files (smart staging) and commit.
    * Returns the commit message string on success, or null if nothing to commit.
@@ -312,6 +340,12 @@ export class GitServiceImpl {
     // Exclude .gsd/ to prevent merge conflicts when both branches modify planning artifacts.
     this.autoCommit("pre-switch", current, [".gsd/"]);
 
+    // Discard uncommitted .gsd/ changes so checkout doesn't fail.
+    // These are runtime files (metrics, completed-units, STATE) that were
+    // intentionally excluded from the commit above. If they remain dirty,
+    // git checkout refuses when the target branch has different versions.
+    this.git(["checkout", "--", ".gsd/"], { allowFailure: true });
+
     this.git(["checkout", branch]);
     return created;
   }
@@ -327,6 +361,9 @@ export class GitServiceImpl {
     // Exclude .gsd/ to prevent merge conflicts when both branches modify planning artifacts.
     this.autoCommit("pre-switch", current, [".gsd/"]);
 
+    // Discard uncommitted .gsd/ changes so checkout doesn't fail.
+    this.git(["checkout", "--", ".gsd/"], { allowFailure: true });
+
     this.git(["checkout", mainBranch]);
   }
 
@@ -490,25 +527,33 @@ export class GitServiceImpl {
     // Pull latest main before merging to avoid conflicts from remote changes
     this.git(["pull", "--rebase", "origin", mainBranch], { allowFailure: true });
 
-    // Squash merge — abort cleanly on conflict so the working tree is never
-    // left in a half-merged state (see: merge-bug-fix).
+    // Merge slice branch — strategy is configurable via git.merge_strategy
+    // preference. Default: "squash" (preserves existing behavior).
+    // "merge" uses --no-ff which is more resilient to conflicts from
+    // long-lived branches or frequently-changing .gsd/* artifacts.
+    const strategy = this.prefs.merge_strategy ?? "squash";
+    const mergeArgs = strategy === "merge"
+      ? ["merge", "--no-ff", "-m", message, branch]
+      : ["merge", "--squash", branch];
+
     try {
-      this.git(["merge", "--squash", branch]);
+      this.git(mergeArgs);
     } catch (mergeError) {
-      // git merge --squash exits non-zero on conflict. The working tree now
-      // has conflict markers and a dirty index. Reset to restore a clean state.
+      // Merge exits non-zero on conflict. Reset to restore a clean state.
       this.git(["reset", "--hard", "HEAD"], { allowFailure: true });
       const msg = mergeError instanceof Error ? mergeError.message : String(mergeError);
       throw new Error(
-        `Squash-merge of "${branch}" into "${mainBranch}" failed with conflicts. ` +
+        `${strategy === "merge" ? "Merge" : "Squash-merge"} of "${branch}" into "${mainBranch}" failed with conflicts. ` +
         `Working tree has been reset to a clean state. ` +
-        `Resolve manually: git checkout ${mainBranch} && git merge --squash ${branch}\n` +
+        `Resolve manually: git checkout ${mainBranch} && git merge ${strategy === "merge" ? "--no-ff" : "--squash"} ${branch}\n` +
         `Original error: ${msg}`,
       );
     }
 
-    // Commit with rich message via stdin pipe
-    this.git(["commit", "-F", "-"], { input: message });
+    // Squash merge needs a separate commit; --no-ff merge already committed
+    if (strategy === "squash") {
+      this.git(["commit", "-F", "-"], { input: message });
+    }
 
     // Delete the merged branch
     this.git(["branch", "-D", branch]);

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

@@ -8,6 +8,7 @@
 
 import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
 
 /**
  * Patterns that are always correct regardless of project type.
@@ -20,6 +21,7 @@ const BASELINE_PATTERNS = [
   ".gsd/worktrees/",
   ".gsd/auto.lock",
   ".gsd/metrics.json",
+  ".gsd/completed-units.json",
   ".gsd/STATE.md",
 
   // ── OS junk ──
@@ -105,6 +107,32 @@ export function ensureGitignore(basePath: string): boolean {
   return true;
 }
 
+/**
+ * Remove BASELINE_PATTERNS runtime paths from the git index if they are
+ * currently tracked. This fixes repos that started tracking these files
+ * before the .gitignore rule was added — git continues tracking files
+ * already in the index even after .gitignore is updated.
+ *
+ * Only removes from the index (`--cached`), never from disk. Idempotent.
+ */
+export function untrackRuntimeFiles(basePath: string): void {
+  // The GSD runtime paths are the first 7 entries in BASELINE_PATTERNS
+  const runtimePaths = BASELINE_PATTERNS.slice(0, 7);
+
+  for (const pattern of runtimePaths) {
+    // Use -r for directory patterns (trailing slash), strip the slash for the command
+    const target = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+    try {
+      execSync(`git rm -r --cached ${target}`, {
+        cwd: basePath,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+    } catch {
+      // File not tracked or doesn't exist — expected, ignore
+    }
+  }
+}
+
 /**
  * Ensure basePath/.gsd/PREFERENCES.md exists as an empty template.
  * Creates the file with frontmatter only if it doesn't exist.

package/src/resources/extensions/gsd/guided-flow.ts

@@ -14,15 +14,16 @@ import { deriveState } from "./state.js";
 import { startAuto } from "./auto.js";
 import { readCrashLock, clearLock, formatCrashInfo } from "./crash-recovery.js";
 import {
-  gsdRoot, milestonesDir, resolveMilestoneFile,
+  gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
   relMilestoneFile, relSliceFile, relSlicePath,
 } from "./paths.js";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
-import { ensureGitignore, ensurePreferences } from "./gitignore.js";
+import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { showConfirm } from "../shared/confirm-ui.js";
 
 // ─── Auto-start after discuss ─────────────────────────────────────────────────
 
@@ -35,6 +36,11 @@ let pendingAutoStart: {
   step?: boolean; // preserve step mode through discuss → auto transition
 } | null = null;
 
+/** Returns the milestoneId being discussed, or null if no discussion is active */
+export function getDiscussionMilestoneId(): string | null {
+  return pendingAutoStart?.milestoneId ?? null;
+}
+
 /** Called from agent_end to check if auto-mode should start after discuss */
 export function checkAutoStartAfterDiscuss(): boolean {
   if (!pendingAutoStart) return false;
@@ -81,13 +87,13 @@ function dispatchWorkflow(pi: ExtensionAPI, note: string, customType = "gsd-run"
  * Build the discuss-and-plan prompt for a new milestone.
  * Used by all three "new milestone" paths (first ever, no active, all complete).
  */
-function buildDiscussPrompt(nextId: string, preamble: string, basePath: string): string {
-  const milestoneDirAbs = join(basePath, ".gsd", "milestones", nextId);
+function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string): string {
+  const milestoneRel = `.gsd/milestones/${nextId}`;
   return loadPrompt("discuss", {
     milestoneId: nextId,
     preamble,
-    contextAbsPath: join(milestoneDirAbs, `${nextId}-CONTEXT.md`),
-    roadmapAbsPath: join(milestoneDirAbs, `${nextId}-ROADMAP.md`),
+    contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
+    roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
   });
 }
 
@@ -339,16 +345,16 @@ async function buildDiscussSlicePrompt(
     ? `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`
     : `## Inlined Context\n\n_(no context files found yet — go in blind and ask broad questions)_`;
 
-  const sliceDirAbsPath = join(base, ".gsd", "milestones", mid, "slices", sid);
-  const contextAbsPath = join(sliceDirAbsPath, `${sid}-CONTEXT.md`);
+  const sliceDirPath = `.gsd/milestones/${mid}/slices/${sid}`;
+  const sliceContextPath = `${sliceDirPath}/${sid}-CONTEXT.md`;
 
   return loadPrompt("guided-discuss-slice", {
     milestoneId: mid,
     sliceId: sid,
     sliceTitle: sTitle,
     inlinedContext,
-    sliceDirAbsPath,
-    contextAbsPath,
+    sliceDirPath,
+    contextPath: sliceContextPath,
     projectRoot: base,
   });
 }
@@ -451,6 +457,7 @@ export async function showSmartEntry(
 
   // ── Ensure .gitignore has baseline patterns ──────────────────────────
   ensureGitignore(basePath);
+  untrackRuntimeFiles(basePath);
 
   // ── No GSD project OR no milestone → Create first/next milestone ────
   if (!existsSync(join(basePath, ".gsd"))) {
@@ -601,6 +608,16 @@ export async function showSmartEntry(
           label: "Discuss first",
           description: "Capture decisions on gray areas before planning.",
         }] : []),
+        {
+          id: "skip_milestone",
+          label: "Skip — create new milestone",
+          description: "Leave this milestone on disk and start a fresh one.",
+        },
+        {
+          id: "discard_milestone",
+          label: "Discard this milestone",
+          description: "Delete the milestone directory and start over.",
+        },
       ];
 
       const choice = await showNextAction(ctx as any, {
@@ -619,6 +636,27 @@ export async function showSmartEntry(
         dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
           milestoneId, milestoneTitle,
         }));
+      } else if (choice === "skip_milestone") {
+        const milestoneIds = findMilestoneIds(basePath);
+        const nextId = `M${String(milestoneIds.length + 1).padStart(3, "0")}`;
+        pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode };
+        dispatchWorkflow(pi, buildDiscussPrompt(nextId,
+          `New milestone ${nextId}.`,
+          basePath
+        ));
+      } else if (choice === "discard_milestone") {
+        const mDir = resolveMilestonePath(basePath, milestoneId);
+        if (!mDir) return;
+        const confirmed = await showConfirm(ctx as any, {
+          title: "Discard milestone?",
+          message: `This will permanently delete ${milestoneId} and all its contents.`,
+          confirmLabel: "Discard",
+          declineLabel: "Cancel",
+        });
+        if (confirmed) {
+          rmSync(mDir, { recursive: true, force: true });
+          return showSmartEntry(ctx, pi, basePath, options);
+        }
       }
     } else {
       // Roadmap exists — either blocked or ready for auto

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

@@ -20,18 +20,20 @@
 
 import type {
   ExtensionAPI,
+  ExtensionCommandContext,
   ExtensionContext,
 } from "@gsd/pi-coding-agent";
-import { createBashTool, createWriteTool, createReadTool, createEditTool } from "@gsd/pi-coding-agent";
+import { createBashTool, createWriteTool, createReadTool, createEditTool, isToolCallEventType } from "@gsd/pi-coding-agent";
 
 import { registerGSDCommand } from "./commands.js";
+import { registerExitCommand } from "./exit-command.js";
 import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
 import { saveFile, formatContinue, loadFile, parseContinue, parseSummary } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData } from "./auto.js";
 import { saveActivityLog } from "./activity-log.js";
-import { checkAutoStartAfterDiscuss } from "./guided-flow.js";
+import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId } from "./guided-flow.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import {
   loadEffectiveGSDPreferences,
@@ -42,7 +44,7 @@ import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "./skill-disc
 import {
   resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTaskFiles, resolveTasksDir,
   relSliceFile, relSlicePath, relTaskFile,
-  buildSliceFileName, gsdRoot,
+  buildSliceFileName, buildMilestoneFileName, gsdRoot, resolveMilestonePath,
 } from "./paths.js";
 import { Key } from "@gsd/pi-tui";
 import { join } from "node:path";
@@ -50,6 +52,32 @@ import { existsSync } from "node:fs";
 import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@gsd/pi-tui";
 
+// ── Depth verification state ──────────────────────────────────────────────
+let depthVerificationDone = false;
+
+export function isDepthVerified(): boolean {
+  return depthVerificationDone;
+}
+
+// ── Write-gate: block CONTEXT.md writes during discussion without depth verification ──
+const MILESTONE_CONTEXT_RE = /M\d+-CONTEXT\.md$/;
+
+export function shouldBlockContextWrite(
+  toolName: string,
+  inputPath: string,
+  milestoneId: string | null,
+  depthVerified: boolean,
+): { block: boolean; reason?: string } {
+  if (toolName !== "write") return { block: false };
+  if (!milestoneId) return { block: false };
+  if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
+  if (depthVerified) return { block: false };
+  return {
+    block: true,
+    reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
+  };
+}
+
 // ── ASCII logo ────────────────────────────────────────────────────────────
 const GSD_LOGO_LINES = [
   "   ██████╗ ███████╗██████╗ ",
@@ -63,22 +91,12 @@ const GSD_LOGO_LINES = [
 export default function (pi: ExtensionAPI) {
   registerGSDCommand(pi);
   registerWorktreeCommand(pi);
-
-  // ── /exit — graceful exit (cleanup auto-mode, save state) ──────────────
-  pi.registerCommand("exit", {
-    description: "Exit GSD gracefully (saves auto-mode state)",
-    handler: async (_ctx) => {
-      // Gracefully stop auto-mode if running (saves activity log, clears locks)
-      const { stopAuto } = await import("./auto.js");
-      await stopAuto(_ctx, pi);
-      process.exit(0);
-    },
-  });
+  registerExitCommand(pi);
 
   // ── /kill — immediate exit (bypass cleanup) ─────────────────────────────
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
-    handler: async (_ctx) => {
+    handler: async (_args: string, _ctx: ExtensionCommandContext) => {
       process.exit(0);
     },
   });
@@ -299,7 +317,10 @@ export default function (pi: ExtensionAPI) {
   // ── agent_end: auto-mode advancement or auto-start after discuss ───────────
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
     // If discuss phase just finished, start auto-mode
-    if (checkAutoStartAfterDiscuss()) return;
+    if (checkAutoStartAfterDiscuss()) {
+      depthVerificationDone = false;
+      return;
+    }
 
     // If auto-mode is already running, advance to next unit
     if (!isAutoActive()) return;
@@ -373,6 +394,80 @@ export default function (pi: ExtensionAPI) {
       saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
     }
   });
+
+  // ── tool_call: block CONTEXT.md writes during discussion without depth verification ──
+  pi.on("tool_call", async (event) => {
+    if (!isToolCallEventType("write", event)) return;
+    const result = shouldBlockContextWrite(
+      event.toolName,
+      event.input.path,
+      getDiscussionMilestoneId(),
+      isDepthVerified(),
+    );
+    if (result.block) return result;
+  });
+
+  // ── tool_result: persist discussion exchanges & detect depth gate ──────
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "ask_user_questions") return;
+
+    const milestoneId = getDiscussionMilestoneId();
+    if (!milestoneId) return;
+
+    const details = event.details as any;
+    if (details?.cancelled || !details?.response) return;
+
+    // ── Depth gate detection ──────────────────────────────────────────
+    const questions: any[] = (event.input as any)?.questions ?? [];
+    for (const q of questions) {
+      if (typeof q.id === "string" && q.id.includes("depth_verification")) {
+        depthVerificationDone = true;
+        break;
+      }
+    }
+
+    // ── Persist exchange to DISCUSSION.md ──────────────────────────────
+    const basePath = process.cwd();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) return;
+
+    const fileName = buildMilestoneFileName(milestoneId, "DISCUSSION");
+    const discussionPath = join(milestoneDir, fileName);
+    const timestamp = new Date().toISOString();
+
+    // Format exchange as markdown
+    const lines: string[] = [`## Exchange — ${timestamp}`, ""];
+
+    for (const q of questions) {
+      lines.push(`### ${q.header ?? "Question"}`);
+      lines.push("");
+      lines.push(q.question ?? "");
+      if (Array.isArray(q.options)) {
+        lines.push("");
+        for (const opt of q.options) {
+          lines.push(`- **${opt.label}** — ${opt.description ?? ""}`);
+        }
+      }
+
+      // Append user response for this question
+      const answer = details.response?.answers?.[q.id];
+      if (answer) {
+        lines.push("");
+        const selected = Array.isArray(answer.selected) ? answer.selected.join(", ") : answer.selected;
+        lines.push(`**Selected:** ${selected}`);
+        if (answer.notes) {
+          lines.push(`**Notes:** ${answer.notes}`);
+        }
+      }
+      lines.push("");
+    }
+
+    lines.push("---", "");
+
+    const newBlock = lines.join("\n");
+    const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
+    await saveFile(discussionPath, existing + newBlock);
+  });
 }
 
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {

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

@@ -702,6 +702,14 @@ function validatePreferences(preferences: GSDPreferences): {
         errors.push(`git.commit_type must be one of: feat, fix, refactor, docs, test, chore, perf, ci, build, style`);
       }
     }
+    if (g.merge_strategy !== undefined) {
+      const validStrategies = new Set(["squash", "merge"]);
+      if (typeof g.merge_strategy === "string" && validStrategies.has(g.merge_strategy)) {
+        git.merge_strategy = g.merge_strategy as "squash" | "merge";
+      } else {
+        errors.push("git.merge_strategy must be one of: squash, merge");
+      }
+    }
     if (g.main_branch !== undefined) {
       if (typeof g.main_branch === "string" && g.main_branch.trim() !== "" && VALID_BRANCH_NAME.test(g.main_branch)) {
         git.main_branch = g.main_branch;

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

@@ -12,7 +12,7 @@ Then:
 3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
 4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
 5. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-6. Write `{{milestoneSummaryAbsPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
+6. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
 7. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
 8. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
 9. Do not commit manually — the system auto-commits your changes after this unit completes.
@@ -20,6 +20,6 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
-**You MUST write `{{milestoneSummaryAbsPath}}` AND update PROJECT.md before finishing.**
+**You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

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

@@ -16,14 +16,14 @@ Then:
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
-6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries).
-7. Write `{{sliceUatAbsPath}}`.
+6. Write `{{sliceSummaryPath}}` (compress all task summaries).
+7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
 10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
 11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 12. Update `.gsd/STATE.md`
 
-**You MUST mark {{sliceId}} as `[x]` in `{{roadmapPath}}` AND write `{{sliceSummaryAbsPath}}` before finishing.**
+**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) mark {{sliceId}} as `[x]` in `{{roadmapPath}}`. The unit will not be marked complete if any of these files are missing.**
 
 When done, say: "Slice {{sliceId}} complete."

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

@@ -52,6 +52,16 @@ You are a thinking partner, not an interviewer.
 
 **Freeform rule:** When the user selects "Other" or clearly wants to explain something freely, stop using `ask_user_questions` and switch to plain text follow-ups. Let them talk. Resume structured questions when appropriate.
 
+**Depth-signal awareness.** When a user writes extensively about something — long notes, detailed explanations, specific examples — that's a signal. Probe that area deeper. Don't spread attention evenly across all topics when the user is clearly investing energy in one.
+
+**Enrichment fusion.** Weave the user's specific language, terminology, and framing into your subsequent questions. If they said "craft feel," your next question references "craft feel" — don't paraphrase it into "user experience quality." Their precision is signal, not noise.
+
+**Position-first framing.** Have opinions. State your read of a tradeoff with rationale before asking what they think. "I'd lean toward X because Y — does that match your thinking, or am I missing context?" is better than "what do you think about X vs Y?" You're a thinking partner, not a neutral interviewer.
+
+**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. What the product should never feel like. Negative constraints are sharper than positive wishes — "never feel sluggish" defines the performance bar more precisely than "should be fast."
+
+**Observation ≠ Conclusion.** Technical facts you discover in the codebase during investigation are context, not decisions. Present them as context and let the user decide what they mean for direction. "The current auth uses JWT with 24h expiry" is an observation. Whether to keep that pattern is the user's call.
+
 **Anti-patterns — never do these:**
 - **Checklist walking** — going through a predetermined list of topics regardless of what the user said
 - **Canned questions** — asking generic questions that could apply to any project
@@ -73,10 +83,22 @@ Do NOT offer to proceed until ALL of the following are satisfied. Track these in
 - [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
 - [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
 
+Before offering to proceed, demonstrate absorption: reference specific things the user emphasized, specific terminology they used, specific nuance they sharpened — and show how those shaped your understanding. Synthesize, don't recite. "Your emphasis on X led me to prioritize Y over Z" is good. "You said X, you said Y, you said Z" is not. The user should feel heard in the specifics, not just acknowledged in the abstract.
+
 **Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work.
 
 Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
 
+## Depth Verification
+
+Before moving to the wrap-up gate, present a structured depth summary to the user via `ask_user_questions`. This is a checkpoint — show what you captured across the depth checklist dimensions, using the user's own terminology and framing.
+
+The question should summarize: what you understood them to be building, what shaped your understanding most (their emphasis, constraints, concerns), and any areas where you're least confident in your understanding. Frame it as: "Before we move to planning, here's what I captured — did I get the depth right?"
+
+**Convention:** The question ID must contain `depth_verification` (e.g., `depth_verification_summary`). This naming convention enables downstream mechanical detection of this step.
+
+Offer two options: "Yes, you got it (Recommended)" and "Not quite — let me clarify." If they clarify, absorb the correction and re-verify.
+
 ## Wrap-up Gate
 
 Only after the depth checklist is fully satisfied and you genuinely understand the work, offer to proceed.
@@ -166,8 +188,11 @@ Once the user is satisfied, in a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
 2. Write or update `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
 3. Write or update `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
-4. Write `{{contextAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
-5. Write `{{roadmapAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
+**Depth-Preservation Guidance for context.md:**
+When writing context.md, preserve the user's exact terminology, emphasis, and specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
+
+4. Write `{{contextPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Write `{{roadmapPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
 6. Seed `.gsd/DECISIONS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
 7. Update `.gsd/STATE.md`
 8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`

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

@@ -49,13 +49,13 @@ Then:
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
 12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
 13. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
-14. Write `{{taskSummaryAbsPath}}`
+14. Write `{{taskSummaryPath}}`
 15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
 16. Do not commit manually — the system auto-commits your changes after this unit completes.
 17. Update `.gsd/STATE.md`
 
 You are on the slice branch. All work stays here.
 
-**You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryAbsPath}}` before finishing.**
+**You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryPath}}` before finishing.**
 
 When done, say: "Task {{taskId}} complete."

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

@@ -46,8 +46,8 @@ If the user wants to keep going, keep asking. Stop when they say wrap up.
 Once the user is ready to wrap up:
 
 1. Read the slice context template at `~/.gsd/agent/extensions/gsd/templates/slice-context.md`
-2. `mkdir -p {{sliceDirAbsPath}}`
-3. Write `{{contextAbsPath}}` — use the template structure, filling in:
+2. `mkdir -p {{sliceDirPath}}`
+3. Write `{{contextPath}}` — use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers
    - **Why this Slice** — why now, what it unblocks
    - **Scope / In Scope** — what was confirmed in scope during the interview
@@ -55,5 +55,5 @@ Once the user is ready to wrap up:
    - **Constraints** — anything the user flagged as a hard constraint
    - **Integration Points** — what this slice consumes and produces
    - **Open Questions** — anything still unresolved, with current thinking
-4. Commit: `git -C {{projectRoot}} add {{contextAbsPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
+4. Commit: `git -C {{projectRoot}} add {{contextPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
 5. Say exactly: `"{{sliceId}} context written."` — nothing else.