@opengsd/gsd-pi 1.0.2-dev.5961fbf → 1.0.2-dev.5f7864c

package/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts

@@ -235,12 +235,16 @@ test("gsd_task_complete — enrichment arrays are optional", () => {
     "milestoneId",
     "oneLiner",
     "narrative",
-    "verification",
   ];
   for (const field of coreRequired) {
     assert.ok(required.has(field), `core field "${field}" must be required`);
   }
 
+  assert.ok(
+    !required.has("verification"),
+    "verification must be optional at the schema layer so step-mode can recover when verificationEvidence is present",
+  );
+
   // Enrichment fields must be optional
   const enrichmentFields = [
     "keyFiles",
@@ -272,6 +276,25 @@ test("gsd_task_complete — validates with only core params", () => {
   assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.join(", ")}`);
 });
 
+test("gsd_task_complete — accepts evidence-only verification at schema layer", () => {
+  const tool = getTool("gsd_task_complete");
+  assert.ok(tool, "gsd_task_complete must be registered");
+
+  const params = {
+    taskId: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    oneLiner: "Implemented the feature",
+    narrative: "Created the module and wired it up.",
+    verificationEvidence: [
+      { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+    ],
+  };
+
+  const errors = validateSchema(tool, params);
+  assert.strictEqual(errors.length, 0, `Evidence-only params should validate but got errors: ${errors.join(", ")}`);
+});
+
 // ─── gsd_complete_milestone: enrichment arrays must be optional ──────────────
 
 test("gsd_complete_milestone — enrichment arrays are optional", () => {

package/src/resources/extensions/gsd/tests/tui-border-assertions.ts

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+
+import { visibleWidth } from "@gsd/pi-tui";
+
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_PATTERN, "");
+}
+
+export function assertFullOuterBorder(lines: string[], width: number): void {
+  assert.ok(lines.length >= 2, "dialog must include top and bottom borders");
+
+  for (const [index, line] of lines.entries()) {
+    assert.equal(visibleWidth(line), width, `line ${index} must fill dialog width`);
+  }
+
+  const top = stripAnsi(lines[0] ?? "");
+  const bottom = stripAnsi(lines.at(-1) ?? "");
+  assert.match(top, /^[╭┌].*[╮┐]$/, `top border missing full corners: ${top}`);
+  assert.match(bottom, /^[╰└].*[╯┘]$/, `bottom border missing full corners: ${bottom}`);
+
+  for (let index = 1; index < lines.length - 1; index++) {
+    const line = stripAnsi(lines[index] ?? "");
+    assert.match(line, /^[│┃├]/, `line ${index} missing left border: ${line}`);
+    assert.match(line, /[│┃┤]$/, `line ${index} missing right border: ${line}`);
+  }
+}

package/src/resources/extensions/gsd/tests/tui-render-kit.test.ts

@@ -5,8 +5,10 @@ import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
 import { visibleWidth } from "@gsd/pi-tui";
+import { assertFullOuterBorder } from "./tui-border-assertions.ts";
 import {
   padRightVisible,
+  renderDialogFrame,
   renderFrame,
   renderKeyHints,
   renderPanel,
@@ -60,6 +62,18 @@ describe("tui render kit", () => {
     }
   });
 
+  test("renderDialogFrame draws a full titled modal border with footer", () => {
+    const lines = renderDialogFrame(theme, "Dialog", ["row", "long ".repeat(40)], 40, {
+      footer: renderKeyHints(theme, ["esc close"], 36),
+    });
+    assertWidth(lines, 40);
+    assertFullOuterBorder(lines, 40);
+    assert.match(lines[0] ?? "", /^╭─ Dialog ─+╮$/);
+    assert.ok(lines.some((line) => line.startsWith("│") && line.endsWith("│")));
+    assert.ok(lines.some((line) => line.startsWith("├") && line.endsWith("┤")));
+    assert.match(lines.at(-1) ?? "", /^╰─+╯$/);
+  });
+
   test("renderPanel stays within width and draws no vertical borders", () => {
     for (const width of [3, 40, 80]) {
       const lines = renderPanel(theme, "Title", ["row", "long ".repeat(40)], width);

package/src/resources/extensions/gsd/tests/vision-ask.test.ts

@@ -0,0 +1,23 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { chooseVisionAskVariant, VISION_ASK_VARIANTS } from "../vision-ask.ts";
+
+test("vision ask variants stay varied and conversational", () => {
+  assert.ok(VISION_ASK_VARIANTS.length >= 6, "keep enough openers to avoid repetition");
+  assert.equal(new Set(VISION_ASK_VARIANTS).size, VISION_ASK_VARIANTS.length, "openers should be unique");
+
+  for (const opener of VISION_ASK_VARIANTS) {
+    assert.ok(opener.length <= 72, `opener should stay short: ${opener}`);
+    assert.doesNotMatch(opener, /\n/, "opener should be a single line");
+    assert.doesNotMatch(opener, /\bstakeholders?|key success metrics?|business objectives?\b/i, "avoid corporate wording");
+    assert.notEqual(opener, "What's the vision?", "do not keep the old fixed opener in rotation");
+  }
+});
+
+test("chooseVisionAskVariant picks from the configured opener list", () => {
+  assert.equal(chooseVisionAskVariant(() => 0), VISION_ASK_VARIANTS[0]);
+  assert.equal(
+    chooseVisionAskVariant((exclusiveMax) => exclusiveMax - 1),
+    VISION_ASK_VARIANTS[VISION_ASK_VARIANTS.length - 1],
+  );
+});

package/src/resources/extensions/gsd/tests/visualizer-overlay.test.ts

@@ -14,6 +14,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 
 import { GSDVisualizerOverlay, TAB_COUNT } from "../visualizer-overlay.ts";
+import { assertFullOuterBorder } from "./tui-border-assertions.ts";
 
 function makeTui() {
   const renders: number[] = [];
@@ -50,7 +51,11 @@ test("overlay renders 10 tabs (Progress, Timeline, Deps, Metrics, Health, Agent,
   overlay.loading = true; // body shows loading text, but tab bar renders regardless
 
   // Use a very wide terminal so the tab bar is not truncated.
-  const lines = overlay.render(200).map(stripAnsi);
+  const rawLines = overlay.render(200);
+  assertFullOuterBorder(rawLines, 200);
+  const lines = rawLines.map(stripAnsi);
+  assert.match(lines[0] ?? "", /^╭─ GSD Visualizer /);
+  assert.match(lines.at(-1) ?? "", /^╰─+╯$/);
   const tabBar = lines.find((l) => l.includes("Progress") && l.includes("Export"));
   assert.ok(tabBar, `expected a tab-bar line containing all labels, got:\n${lines.slice(0, 5).join("\n")}`);
   for (const label of ["Progress", "Timeline", "Deps", "Metrics", "Health", "Agent", "Changes", "Knowledge", "Captures", "Export"]) {

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -1,6 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { GSD_WORKFLOW_MCP_SERVER_NAME } from "../mcp-project-config.ts";
 import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts";
 
 test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => {
@@ -74,3 +79,58 @@ test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep f
   assert.equal(notifications[0].level, "warning");
   assert.match(notifications[0].message, /Please run \/gsd mcp init \./);
 });
+
+test("before_agent_start auto-prepares project workflow MCP for Claude Code CLI", async (t) => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-before-agent-"));
+  const originalCwd = process.cwd();
+  const notifications: string[] = [];
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools() {},
+  };
+
+  t.after(() => {
+    process.chdir(originalCwd);
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  process.chdir(projectRoot);
+  registerHooks(pi as any, []);
+
+  const beforeAgentStart = handlers.get("before_agent_start")?.[0];
+  assert.ok(beforeAgentStart, "before_agent_start hook should be registered");
+
+  await beforeAgentStart(
+    { prompt: "hello", systemPrompt: "base" },
+    {
+      cwd: projectRoot,
+      model: { provider: "claude-code", baseUrl: "local://claude-code" },
+      modelRegistry: {
+        getProviderAuthMode: () => "externalCli",
+        isProviderRequestReady: () => true,
+      },
+      ui: {
+        notify(message: string) {
+          notifications.push(message);
+        },
+        setWidget() {},
+      },
+    },
+  );
+
+  const configPath = join(projectRoot, ".mcp.json");
+  assert.equal(existsSync(configPath), true, "Claude Code CLI turns should create project MCP config");
+
+  const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as {
+    mcpServers?: Record<string, unknown>;
+  };
+  assert.ok(parsed.mcpServers?.[GSD_WORKFLOW_MCP_SERVER_NAME]);
+  assert.match(notifications.join("\n"), /Claude Code MCP prepared/);
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -148,6 +148,60 @@ test("executeTaskComplete coerces string verificationEvidence entries", async ()
   }
 });
 
+test("executeTaskComplete derives missing verification from evidence", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const planDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(planDir, { recursive: true });
+    writeFileSync(join(planDir, "S01-PLAN.md"), "# S01\n\n- [ ] **T01: Demo** `est:5m`\n");
+
+    const result = await inProjectDir(base, () => executeTaskComplete({
+      milestoneId: "M001",
+      sliceId: "S01",
+      taskId: "T01",
+      oneLiner: "Completed task",
+      narrative: "Did the work",
+      verificationEvidence: [
+        { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1234 },
+      ],
+    }, base));
+
+    assert.equal(result.details.operation, "complete_task");
+    const db = _getAdapter();
+    assert.ok(db, "DB should be open");
+    const row = db!.prepare(
+      "SELECT verification_result FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?",
+    ).get("M001", "S01", "T01") as Record<string, unknown> | undefined;
+
+    assert.match(String(row?.verification_result), /Verification evidence recorded/);
+    assert.match(String(row?.verification_result), /`npm test` exited 0 \(pass\)/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeTaskComplete returns a tool error when verification cannot be derived", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const result = await inProjectDir(base, () => executeTaskComplete({
+      milestoneId: "M001",
+      sliceId: "S01",
+      taskId: "T01",
+      oneLiner: "Completed task",
+      narrative: "Did the work",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /verification is required/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSliceComplete preserves omitted optional requirement arrays", async () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/workspace-git-preflight.test.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
 import { probeGitConflictState } from "../git-conflict-state.js";
 import { ensureWorkspaceGitReadyForPath } from "../workspace-git-preflight.js";
 import { isWorkspaceGitAllowedCommand } from "../workspace-git-guard.js";
-import { cleanup, git, makeTempRepo } from "./test-utils.ts";
+import { cleanup, git, makeTempDir, makeTempRepo } from "./test-utils.ts";
 
 function seedGsdConflict(base: string): void {
   mkdirSync(join(base, ".gsd"), { recursive: true });
@@ -60,6 +60,21 @@ test("probeGitConflictState reports clean repo", () => {
   }
 });
 
+test("ensureWorkspaceGitReadyForPath allows fresh non-git project setup folders", async () => {
+  const base = makeTempDir("gsd-ws-git-non-repo-");
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    const probe = probeGitConflictState(base);
+    assert.equal(probe.status, "clean");
+
+    const ready = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(ready.ok, true);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("ensureWorkspaceGitReadyForPath auto-resolves .gsd/ conflicts", async () => {
   const base = makeTempRepo("gsd-ws-git-heal-");
   try {

package/src/resources/extensions/gsd/tests/worktree-lifecycle.test.ts

@@ -212,6 +212,34 @@ test("enterMilestone returns ok:true mode:none when isolation disabled", () => {
   assert.equal(s.basePath, "/project");
 });
 
+test("adoptStrandedMilestone forces branch recovery even when normal preferences differ", (t) => {
+  const previousCwd = process.cwd();
+  const base = makeGitRepoBase({ isolation: "worktree" });
+  t.after(() => cleanupRepoBase(base, previousCwd));
+
+  const s = makeSession({ basePath: base, originalBasePath: base });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.adoptStrandedMilestone("M001", base, ctx, {
+    mode: "branch",
+  });
+
+  assert.equal(result.ok, true, `expected ok:true, got: ${JSON.stringify(result)}`);
+  if (result.ok) {
+    assert.equal(result.mode, "branch");
+    assert.equal(result.path, base);
+  }
+  assert.equal(s.basePath, base);
+  assert.equal(s.strandedRecoveryIsolationMode, "branch");
+  const currentBranch = execFileSync("git", ["branch", "--show-current"], {
+    cwd: base,
+    encoding: "utf-8",
+  }).trim();
+  assert.equal(currentBranch, "milestone/M001");
+});
+
 test("enterMilestone returns ok:false reason:isolation-degraded when session degraded", () => {
   const s = makeSession({ isolationDegraded: true });
   const deps = makeDeps({ getIsolationMode: () => "branch" });

package/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts

@@ -14,7 +14,7 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -79,3 +79,47 @@ test("#2942: injected existsFn — milestones/ alone is enough", () => {
     p === "/proj/.gsd" || p === "/proj/.gsd/milestones";
   assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
 });
+
+test("bare /gsd routes zombie .gsd folders to project init before closeout/db checks", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-zombie-bare-command-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+
+  const previousCwd = process.cwd();
+  const previousGsdHome = process.env.GSD_HOME;
+  const previousProjectRoot = process.env.GSD_PROJECT_ROOT;
+  try {
+    process.chdir(base);
+    process.env.GSD_HOME = join(base, ".test-gsd-home");
+    delete process.env.GSD_PROJECT_ROOT;
+
+    const notifications: string[] = [];
+    const ctx = {
+      hasUI: false,
+      ui: {
+        notify: (content: unknown) => notifications.push(String(content)),
+        setStatus: () => {},
+        setWidget: () => {},
+      },
+    };
+    const { handleAutoCommand } = await import("../commands/handlers/auto.ts");
+
+    await handleAutoCommand("", ctx as any, {} as any);
+
+    assert.ok(
+      notifications.some((message) => message.includes("/gsd init did not start")),
+      "bare /gsd should route unbootstrapped zombie folders to the init wizard",
+    );
+    assert.equal(
+      existsSync(join(base, ".gsd", "gsd.db")),
+      false,
+      "bare /gsd should not create the project DB before init has bootstrapped .gsd/",
+    );
+  } finally {
+    process.chdir(previousCwd);
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    if (previousProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+    else process.env.GSD_PROJECT_ROOT = previousProjectRoot;
+  }
+});

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -173,6 +173,15 @@ export async function handleCompleteTask(
   if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
     return { error: "milestoneId is required and must be a non-empty string" };
   }
+  if (!params.oneLiner || typeof params.oneLiner !== "string" || params.oneLiner.trim() === "") {
+    return { error: "oneLiner is required and must be a non-empty string" };
+  }
+  if (!params.narrative || typeof params.narrative !== "string" || params.narrative.trim() === "") {
+    return { error: "narrative is required and must be a non-empty string" };
+  }
+  if (!params.verification || typeof params.verification !== "string" || params.verification.trim() === "") {
+    return { error: "verification is required and must be a non-empty string" };
+  }
 
   const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
 

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -306,7 +306,7 @@ export interface TaskCompleteParams {
   milestoneId: string;
   oneLiner: string;
   narrative: string;
-  verification: string;
+  verification?: string;
   deviations?: string;
   knownIssues?: string;
   keyFiles?: string[];
@@ -315,6 +315,40 @@ export interface TaskCompleteParams {
   verificationEvidence?: VerificationEvidenceInput[];
 }
 
+type NormalizedVerificationEvidence = {
+  command: string;
+  exitCode: number;
+  verdict: string;
+  durationMs: number;
+};
+
+function normalizeVerificationEvidence(
+  evidence: VerificationEvidenceInput[] | undefined,
+): NormalizedVerificationEvidence[] {
+  return (evidence ?? []).map((entry) =>
+    typeof entry === "string"
+      ? { command: entry, exitCode: -1, verdict: "unknown (coerced from string)", durationMs: 0 }
+      : entry,
+  );
+}
+
+function deriveVerificationSummary(
+  evidence: NormalizedVerificationEvidence[],
+): string | null {
+  if (evidence.length === 0) return null;
+
+  const rendered = evidence.slice(0, 3).map((entry) => {
+    const command = entry.command.trim() || "(unspecified command)";
+    const verdict = entry.verdict.trim() || "recorded";
+    return `\`${command}\` exited ${entry.exitCode} (${verdict})`;
+  });
+  const suffix = evidence.length > rendered.length
+    ? `; ${evidence.length - rendered.length} more check(s) recorded`
+    : "";
+
+  return `Verification evidence recorded: ${rendered.join("; ")}${suffix}.`;
+}
+
 export type CompleteMilestoneExecutorParams = Partial<CompleteMilestoneParams> & Record<string, unknown>;
 export type SliceCompleteExecutorParams = CompleteSliceParams;
 export type PlanMilestoneExecutorParams = PlanMilestoneParams;
@@ -350,9 +384,27 @@ export async function executeTaskComplete(
   }
   try {
     const coerced = { ...params };
-    coerced.verificationEvidence = (params.verificationEvidence ?? []).map((v) =>
-      typeof v === "string" ? { command: v, exitCode: -1, verdict: "unknown (coerced from string)", durationMs: 0 } : v,
-    );
+    const verificationEvidence = normalizeVerificationEvidence(params.verificationEvidence);
+    coerced.verificationEvidence = verificationEvidence;
+
+    const verification = typeof params.verification === "string" ? params.verification.trim() : "";
+    if (verification.length === 0) {
+      const derived = deriveVerificationSummary(verificationEvidence);
+      if (derived) {
+        coerced.verification = derived;
+      } else if (params.blockerDiscovered === true) {
+        coerced.verification = "Not run: blocker discovered before verification.";
+      } else {
+        return {
+          content: [{
+            type: "text",
+            text: "Error completing task: verification is required unless verificationEvidence is provided or blockerDiscovered is true.",
+          }],
+          details: { operation: "complete_task", error: "verification_required" },
+          isError: true,
+        };
+      }
+    }
 
     const result = await handleCompleteTask(coerced as any, basePath);
     if ("error" in result) {

package/src/resources/extensions/gsd/tui/render-kit.ts

@@ -151,3 +151,85 @@ export function renderFrame(
   lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
   return lines.map((line) => safeLine(line, width, ""));
 }
+
+export interface DialogFrameOptions {
+  borderColor?: string;
+  paddingX?: number;
+  footer?: string | string[];
+  scroll?: {
+    offset: number;
+    visibleRows: number;
+    totalRows: number;
+    trackOffset?: number;
+    trackRows?: number;
+  };
+}
+
+function renderTitledTopBorder(
+  theme: ThemeLike,
+  title: string,
+  width: number,
+  border: (text: string) => string,
+): string {
+  const trimmedTitle = title.trim();
+  if (!trimmedTitle || width < 10) {
+    return border("╭" + "─".repeat(width - 2) + "╮");
+  }
+
+  const maxTitleWidth = Math.max(0, width - 7);
+  const safeTitle = safeLine(trimmedTitle, maxTitleWidth);
+  const fill = Math.max(0, width - visibleWidth(safeTitle) - 5);
+  return border("╭─ ") + theme.bold(theme.fg("accent", safeTitle)) + border(" " + "─".repeat(fill) + "╮");
+}
+
+export function renderDialogFrame(
+  theme: ThemeLike,
+  title: string,
+  inner: string[],
+  width: number,
+  options: DialogFrameOptions = {},
+): string[] {
+  if (width < 4) return inner.map((line) => safeLine(line, width));
+
+  const borderColor = options.borderColor ?? "borderAccent";
+  const paddingX = Math.max(0, options.paddingX ?? 1);
+  const contentWidth = Math.max(0, width - 2 - paddingX * 2);
+  const border = (text: string) => theme.fg(borderColor, text);
+  const pad = " ".repeat(paddingX);
+  const lines = [renderTitledTopBorder(theme, title, width, border)];
+
+  const scroll = options.scroll;
+  const bodyRows = inner.length;
+  const trackOffset = Math.max(0, Math.min(scroll?.trackOffset ?? 0, bodyRows));
+  const trackRows = Math.max(0, Math.min(scroll?.trackRows ?? bodyRows, bodyRows - trackOffset));
+  const scrollable = !!scroll && scroll.totalRows > scroll.visibleRows && trackRows > 0;
+  const thumbLen = scrollable
+    ? Math.max(1, Math.round((scroll.visibleRows / scroll.totalRows) * trackRows))
+    : 0;
+  const maxThumbStart = Math.max(0, trackRows - thumbLen);
+  const maxScrollOffset = scrollable ? Math.max(1, scroll.totalRows - scroll.visibleRows) : 1;
+  const thumbStart = scrollable
+    ? trackOffset + Math.min(maxThumbStart, Math.round((scroll.offset / maxScrollOffset) * maxThumbStart))
+    : -1;
+
+  for (let i = 0; i < inner.length; i++) {
+    const line = inner[i] ?? "";
+    const rightBorder = scrollable && i >= thumbStart && i < thumbStart + thumbLen ? "┃" : "│";
+    lines.push(border("│") + pad + padRightVisible(line, contentWidth) + pad + border(rightBorder));
+  }
+
+  const footer = Array.isArray(options.footer)
+    ? options.footer
+    : options.footer
+      ? [options.footer]
+      : [];
+  if (footer.length > 0) {
+    lines.push(border("├" + "─".repeat(width - 2) + "┤"));
+    for (const line of footer) {
+      lines.push(border("│") + pad + padRightVisible(line, contentWidth) + pad + border("│"));
+    }
+  }
+
+  lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+  return lines.map((line) => safeLine(line, width, ""));
+}

package/src/resources/extensions/gsd/vision-ask.ts

@@ -0,0 +1,28 @@
+/**
+ * Natural-language openers for milestone discussion.
+ *
+ * Keep these short and conversational. They are often the user's first prompt
+ * when GSD starts shaping a project or milestone, so they should feel like a
+ * collaborator starting a working session rather than a form field.
+ */
+import { randomInt } from "node:crypto";
+
+export const VISION_ASK_VARIANTS = [
+  "What are we building?",
+  "What do you want to make next?",
+  "What should this become?",
+  "What are you picturing?",
+  "Where should we take this?",
+  "What should this milestone unlock?",
+  "Tell me what you want to build.",
+  "What should GSD help you shape?",
+] as const;
+
+export type VisionAskVariant = typeof VISION_ASK_VARIANTS[number];
+
+export function chooseVisionAskVariant(
+  pickIndex: (exclusiveMax: number) => number = randomInt,
+): VisionAskVariant {
+  const index = pickIndex(VISION_ASK_VARIANTS.length);
+  return VISION_ASK_VARIANTS[index] ?? VISION_ASK_VARIANTS[0];
+}