gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

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

@@ -275,6 +275,15 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Planning Depth (deep planning mode) ─────────────────────────
+  if (preferences.planning_depth !== undefined) {
+    if (preferences.planning_depth === "light" || preferences.planning_depth === "deep") {
+      validated.planning_depth = preferences.planning_depth;
+    } else {
+      errors.push(`planning_depth must be "light" or "deep"`);
+    }
+  }
+
   // ─── Search Provider ─────────────────────────────────────────────
   if (preferences.search_provider !== undefined) {
     const validSearchProviders = new Set(["brave", "tavily", "ollama", "native", "auto"]);
@@ -610,6 +619,27 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Disabled Model Providers ───────────────────────────────────────
+  if (preferences.disabled_model_providers !== undefined) {
+    if (Array.isArray(preferences.disabled_model_providers)) {
+      const allStrings = preferences.disabled_model_providers.every(
+        (provider: unknown) => typeof provider === "string",
+      );
+      if (!allStrings) {
+        errors.push("disabled_model_providers must be an array of strings");
+      } else {
+        const normalized = preferences.disabled_model_providers
+          .map((provider) => provider.trim())
+          .filter((provider) => provider.length > 0);
+        if (normalized.length > 0) {
+          validated.disabled_model_providers = Array.from(new Set(normalized));
+        }
+      }
+    } else {
+      errors.push("disabled_model_providers must be an array of strings");
+    }
+  }
+
   // ─── Context Management ──────────────────────────────────────────────
   if (preferences.context_management !== undefined) {
     if (typeof preferences.context_management === "object" && preferences.context_management !== null) {
@@ -1101,6 +1131,20 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Auto-Mode Request Interval ───────────────────────────────────
+  if (preferences.min_request_interval_ms !== undefined) {
+    if (
+      typeof preferences.min_request_interval_ms === "number" &&
+      Number.isFinite(preferences.min_request_interval_ms) &&
+      preferences.min_request_interval_ms >= 0 &&
+      preferences.min_request_interval_ms <= 2_147_483_647
+    ) {
+      validated.min_request_interval_ms = Math.floor(preferences.min_request_interval_ms);
+    } else {
+      errors.push("min_request_interval_ms must be a non-negative number <= 2147483647");
+    }
+  }
+
   // ─── Experimental Features ────────────────────────────────────────
   if (preferences.experimental !== undefined) {
     if (typeof preferences.experimental === "object" && preferences.experimental !== null) {

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

@@ -21,6 +21,7 @@ import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { logWarning } from "./workflow-logger.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
+import { nativeHasCommittedHead, nativeIsRepo } from "./native-git-bridge.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
@@ -33,6 +34,7 @@ import {
   formatSkillRef,
 } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ─── Re-exports: types ──────────────────────────────────────────────────────
 // Every type/interface that was previously exported from this file is
@@ -89,18 +91,16 @@ export {
   resolveDynamicRoutingConfig,
   resolveAutoSupervisorConfig,
   resolveProfileDefaults,
+  getProfileTierMap,
   resolveEffectiveProfile,
   resolveInlineLevel,
   resolveContextSelection,
   resolveSearchProviderFromPreferences,
+  resolveDisabledModelProvidersFromPreferences,
 } from "./preferences-models.js";
 
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 
-function gsdHome(): string {
-  return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
-
 function globalPreferencesPath(): string {
   return join(gsdHome(), "PREFERENCES.md");
 }
@@ -146,9 +146,13 @@ export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferenc
     ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
 
-export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
+export function loadEffectiveGSDPreferences(
+  basePath?: string,
+  opts?: { availableModelIds?: string[] },
+): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
   const projectPreferences = loadProjectGSDPreferences(basePath);
+  const projectHasPlanningDepth = projectPreferences?.preferences.planning_depth !== undefined;
 
   if (!globalPreferences && !projectPreferences) return null;
 
@@ -175,7 +179,11 @@ export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPrefere
   // Explicit user preferences always override profile defaults.
   const profile = result.preferences.token_profile as TokenProfile | undefined;
   if (profile) {
-    const profileDefaults = _resolveProfileDefaults(profile);
+    const profileDefaults = _resolveProfileDefaults(
+      profile,
+      opts?.availableModelIds,
+      result.preferences.dynamic_routing,
+    );
     result = {
       ...result,
       preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
@@ -190,9 +198,27 @@ export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPrefere
     };
   }
 
+  result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
+
   return result;
 }
 
+function stripInheritedPlanningDepth(
+  loaded: LoadedGSDPreferences,
+  projectHasPlanningDepth: boolean,
+): LoadedGSDPreferences {
+  if (projectHasPlanningDepth || loaded.preferences.planning_depth === undefined) {
+    return loaded;
+  }
+
+  // planning_depth is a project bootstrap routing flag, not a user-global
+  // preference. A global ~/.gsd/PREFERENCES.md value should not make every
+  // fresh repo behave like `/gsd new-project --deep`.
+  const preferences: GSDPreferences = { ...loaded.preferences };
+  delete preferences.planning_depth;
+  return { ...loaded, preferences };
+}
+
 function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedGSDPreferences | null {
   if (!existsSync(path)) return null;
 
@@ -380,6 +406,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
       ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
       : undefined,
+    disabled_model_providers: mergeStringLists(
+      base.disabled_model_providers,
+      override.disabled_model_providers,
+    ),
     uok: (base.uok || override.uok)
       ? {
           enabled: override.uok?.enabled ?? base.uok?.enabled,
@@ -433,6 +463,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     service_tier: override.service_tier ?? base.service_tier,
     forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
     show_token_cost: override.show_token_cost ?? base.show_token_cost,
+    min_request_interval_ms: override.min_request_interval_ms ?? base.min_request_interval_ms,
     codebase: (base.codebase || override.codebase)
       ? {
           ...(base.codebase ?? {}),
@@ -448,6 +479,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       ? { ...(base.slice_parallel ?? {}), ...(override.slice_parallel ?? {}) }
       : undefined,
     language: override.language ?? base.language,
+    planning_depth: override.planning_depth ?? base.planning_depth,
   };
 }
 
@@ -605,7 +637,10 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  */
 export function getIsolationMode(basePath?: string): "none" | "worktree" | "branch" {
   const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-  if (prefs?.isolation === "worktree") return "worktree";
+  if (prefs?.isolation === "worktree") {
+    if (basePath && nativeIsRepo(basePath) && !nativeHasCommittedHead(basePath)) return "none";
+    return "worktree";
+  }
   if (prefs?.isolation === "branch") return "branch";
   return "none"; // default — no isolation, work on current branch
 }

package/src/resources/extensions/gsd/project-research-policy.ts

@@ -0,0 +1,259 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteSync } from "./atomic-write.js";
+import {
+  classifyMilestoneScope,
+  type ScopeClassificationResult,
+} from "./milestone-scope-classifier.js";
+import { clearParseCache } from "./files.js";
+import { gsdRoot, clearPathCache } from "./paths.js";
+import { parseProject, parseRequirements } from "./schemas/parsers.js";
+
+export const PROJECT_RESEARCH_DIMENSIONS = ["STACK", "FEATURES", "ARCHITECTURE", "PITFALLS"] as const;
+export const PROJECT_RESEARCH_BLOCKER = "PROJECT-RESEARCH-BLOCKER.md";
+export const PROJECT_RESEARCH_INFLIGHT_MARKER = "research-project-inflight";
+
+export type ProjectResearchDimension = typeof PROJECT_RESEARCH_DIMENSIONS[number];
+
+export interface ProjectResearchStatus {
+  complete: boolean;
+  blocked: boolean;
+  allDimensionBlockers: boolean;
+  globalBlocker: boolean;
+  missingDimensions: ProjectResearchDimension[];
+  completedDimensions: ProjectResearchDimension[];
+  blockerDimensions: ProjectResearchDimension[];
+  hasRealResearch: boolean;
+}
+
+export interface ProjectResearchClassification extends ScopeClassificationResult {
+  source: "project-research";
+}
+
+export type ProjectResearchFinalizeOutcome =
+  | {
+      kind: "completed";
+      status: ProjectResearchStatus;
+      written: string[];
+    }
+  | {
+      kind: "partial-blockers";
+      status: ProjectResearchStatus;
+      written: string[];
+    }
+  | {
+      kind: "global-blocker";
+      status: ProjectResearchStatus;
+      written: string[];
+    };
+
+function researchDir(basePath: string): string {
+  return join(gsdRoot(basePath), "research");
+}
+
+function runtimeDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime");
+}
+
+function researchDecisionPath(basePath: string): string {
+  return join(runtimeDir(basePath), "research-decision.json");
+}
+
+function clearResearchCaches(): void {
+  clearPathCache();
+  clearParseCache();
+}
+
+function isProjectResearchDimensionSatisfied(dir: string, name: ProjectResearchDimension): boolean {
+  return existsSync(join(dir, `${name}.md`)) || existsSync(join(dir, `${name}-BLOCKER.md`));
+}
+
+function writeIfMissing(path: string, content: string): boolean {
+  if (existsSync(path)) return false;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf-8");
+  return true;
+}
+
+function markdownTitle(content: string): string {
+  return content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? "Project";
+}
+
+function selectedSections(sections: Record<string, string>): string {
+  return [
+    "What This Is",
+    "Core Value",
+    "Current State",
+    "Architecture / Key Patterns",
+    "Constraints",
+    "Milestone Sequence",
+  ]
+    .map((name) => sections[name] ?? "")
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function classifyProjectResearchScope(
+  projectContent: string,
+  requirementsContent: string,
+): ProjectResearchClassification {
+  const project = parseProject(projectContent);
+  const requirements = parseRequirements(requirementsContent);
+  const activeRequirements = requirements.requirements.filter((r) =>
+    r.status === "active" || r.parentSection === "Active"
+  );
+  const activeCapabilities = activeRequirements.filter((r) =>
+    r.class !== "constraint" && r.class !== "anti-feature"
+  );
+  const requirementCoverage = activeRequirements
+    .map((r) => [
+      r.id,
+      r.title,
+      r.class,
+      r.status,
+      r.description,
+      r.notes,
+    ].filter(Boolean).join(" — "))
+    .join("\n");
+
+  const result = classifyMilestoneScope({
+    title: markdownTitle(projectContent),
+    vision: selectedSections(project.sections),
+    successCriteria: activeCapabilities.map((r) => `${r.title}: ${r.description}`),
+    definitionOfDone: activeCapabilities.map((r) => r.validation).filter(Boolean),
+    requirementCoverage: [
+      requirementCoverage,
+      Object.entries(requirements.coverageSummary)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n"),
+    ].filter(Boolean).join("\n\n"),
+  });
+
+  return {
+    ...result,
+    source: "project-research",
+  };
+}
+
+export function getProjectResearchStatus(basePath: string): ProjectResearchStatus {
+  const dir = researchDir(basePath);
+  const globalBlocker = existsSync(join(dir, PROJECT_RESEARCH_BLOCKER));
+
+  const completedDimensions: ProjectResearchDimension[] = [];
+  const blockerDimensions: ProjectResearchDimension[] = [];
+  const missingDimensions: ProjectResearchDimension[] = [];
+
+  for (const name of PROJECT_RESEARCH_DIMENSIONS) {
+    if (existsSync(join(dir, `${name}.md`))) completedDimensions.push(name);
+    else if (existsSync(join(dir, `${name}-BLOCKER.md`))) blockerDimensions.push(name);
+    else missingDimensions.push(name);
+  }
+
+  const allSatisfied = PROJECT_RESEARCH_DIMENSIONS.every((name) =>
+    isProjectResearchDimensionSatisfied(dir, name),
+  );
+  const allDimensionBlockers =
+    allSatisfied &&
+    completedDimensions.length === 0 &&
+    blockerDimensions.length === PROJECT_RESEARCH_DIMENSIONS.length;
+  const blocked = globalBlocker || allDimensionBlockers;
+
+  return {
+    complete: allSatisfied && !blocked,
+    blocked,
+    allDimensionBlockers,
+    globalBlocker,
+    missingDimensions,
+    completedDimensions,
+    blockerDimensions,
+    hasRealResearch: completedDimensions.length > 0,
+  };
+}
+
+export function writeProjectResearchAutoSkipDecision(
+  basePath: string,
+  classification: ProjectResearchClassification,
+): void {
+  atomicWriteSync(
+    researchDecisionPath(basePath),
+    JSON.stringify({
+      decision: "skip",
+      decided_at: new Date().toISOString(),
+      source: "project-research-fast-path",
+      previous_source: "workflow-preferences",
+      reason: "trivial-static-local-project",
+      classifier_variant: classification.variant,
+      classifier_reasons: classification.reasons,
+    }, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+export function clearProjectResearchInflightMarker(basePath: string): void {
+  const marker = join(runtimeDir(basePath), PROJECT_RESEARCH_INFLIGHT_MARKER);
+  if (existsSync(marker)) unlinkSync(marker);
+}
+
+export function finalizeProjectResearchTimeout(
+  basePath: string,
+  reason: string,
+): ProjectResearchFinalizeOutcome {
+  const dir = researchDir(basePath);
+  mkdirSync(dir, { recursive: true });
+  clearProjectResearchInflightMarker(basePath);
+
+  const before = getProjectResearchStatus(basePath);
+  const written: string[] = [];
+
+  if (before.complete) {
+    clearResearchCaches();
+    return { kind: "completed", status: before, written };
+  }
+  if (before.blocked) {
+    clearResearchCaches();
+    return { kind: "global-blocker", status: before, written };
+  }
+
+  if (before.hasRealResearch) {
+    for (const dimension of before.missingDimensions) {
+      const blockerPath = join(dir, `${dimension}-BLOCKER.md`);
+      if (writeIfMissing(blockerPath, [
+        `# ${dimension} research blocker`,
+        ``,
+        `Auto-mode stopped project research before this dimension produced a durable artifact.`,
+        ``,
+        `**Reason**: ${reason}`,
+        ``,
+        `At least one other project research dimension completed, so this blocker satisfies the project research gate without rerunning every scout.`,
+      ].join("\n"))) {
+        written.push(blockerPath);
+      }
+    }
+    clearResearchCaches();
+    return {
+      kind: "partial-blockers",
+      status: getProjectResearchStatus(basePath),
+      written,
+    };
+  }
+
+  const blockerPath = join(dir, PROJECT_RESEARCH_BLOCKER);
+  if (writeIfMissing(blockerPath, [
+    `# Project research blocker`,
+    ``,
+    `Auto-mode stopped project research before any usable research dimension completed.`,
+    ``,
+    `**Reason**: ${reason}`,
+    ``,
+    `This fail-closed blocker prevents milestone planning from relying on missing project research.`,
+  ].join("\n"))) {
+    written.push(blockerPath);
+  }
+  clearResearchCaches();
+  return {
+    kind: "global-blocker",
+    status: getProjectResearchStatus(basePath),
+    written,
+  };
+}

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -7,22 +7,21 @@
  * Templates live at prompts/ relative to this module's directory.
  * They use {{variableName}} syntax for substitution.
  *
- * All templates are eagerly loaded into cache at module init via warmCache().
- * This prevents a running session from being invalidated when another `gsd`
- * launch overwrites ~/.gsd/agent/ with newer templates via initResources().
- * Without eager caching, the in-memory extension code (which knows variable
- * set A) can read a newer template from disk (which expects variable set B),
- * causing a "template declares {{X}} but no value was provided" crash
- * mid-session — especially for late-loading templates like complete-milestone
- * that aren't read until the end of a long auto-mode run.
+ * Templates are snapshotted shortly after module init via warmCache().
+ * This keeps import/extension-registration fast while still preventing a
+ * running session from being invalidated when another `gsd` launch overwrites
+ * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * in-memory extension code (which knows variable set A) can read a newer
+ * template from disk (which expects variable set B), causing a
+ * "template declares {{X}} but no value was provided" crash mid-session.
  */
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { GSDError, GSD_PARSE_ERROR } from "./errors.js";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { logWarning } from "./workflow-logger.js";
+import { gsdHome } from "./gsd-home.js";
 
 type ExistsFn = (path: string) => boolean;
 
@@ -65,8 +64,7 @@ export function resolveExtensionDirFromCandidates(
  */
 function resolveExtensionDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+  const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd");
   return resolveExtensionDirFromCandidates(moduleDir, agentGsdDir);
 }
 
@@ -82,8 +80,8 @@ export function getTemplatesDir(): string {
   return templatesDir;
 }
 
-// Cache all templates eagerly at module load — a running session uses the
-// template versions that were on disk at startup, immune to later overwrites.
+// Cache all templates from a startup snapshot — a running session uses the
+// template versions that were on disk near startup, immune to later overwrites.
 const templateCache = new Map<string, string>();
 
 /**
@@ -124,8 +122,23 @@ function warmCache(): void {
   }
 }
 
-// Snapshot all templates at module load time
-warmCache();
+let warmCacheScheduled = false;
+
+function scheduleWarmCache(): void {
+  if (warmCacheScheduled) return;
+  warmCacheScheduled = true;
+
+  const run = () => {
+    warmCache();
+  };
+
+  const timer = setTimeout(run, 1000);
+  timer.unref?.();
+}
+
+// Snapshot the full prompt/template tree after import so extension startup only
+// pays for prompts that are actually needed immediately.
+scheduleWarmCache();
 
 /**
  * Load a prompt template and substitute variables.

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

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

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

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **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_slice_complete` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}
@@ -27,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.
-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.
+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.
 
@@ -39,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

@@ -1,3 +1,5 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
 Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Use the **Context** output template below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
@@ -10,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:
@@ -34,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.