gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.23d50d0

package/src/resources/extensions/gsd/mechanical-completion.ts

@@ -0,0 +1,430 @@
+/**
+ * Mechanical Completion — deterministic post-verification artifact generation.
+ *
+ * Pure functions that aggregate task-level outputs into slice/milestone summaries,
+ * UAT stubs, roadmap checkbox updates, and validation reports. Zero orchestration
+ * dependencies — operates on filesystem paths and parsed structures only.
+ *
+ * ADR-003: replaces LLM-driven complete-slice and validate-milestone units with
+ * mechanical aggregation when the data is sufficient.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { loadFile, parseSummary } from "./files.js";
+import { extractMarkdownSection } from "./auto-prompts.js";
+import {
+  resolveTaskFiles,
+  resolveTaskJsonFiles,
+  resolveTasksDir,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  resolveGsdRootFile,
+} from "./paths.js";
+import type { Summary, SummaryFrontmatter } from "./types.js";
+import type { EvidenceJSON } from "./verification-evidence.js";
+
+// ─── Slice Completion ────────────────────────────────────────────────────────
+
+/**
+ * Mechanically complete a slice by aggregating task summaries into:
+ * - S##-SUMMARY.md (aggregated frontmatter + task one-liners)
+ * - S##-UAT.md (extracted from plan Verification section)
+ * - Roadmap checkbox [x] update
+ *
+ * Returns true if completion succeeded, false if data is insufficient
+ * (serves as quality gate — caller falls back to LLM completion).
+ */
+export async function mechanicalSliceCompletion(
+  base: string, mid: string, sid: string,
+): Promise<boolean> {
+  const tDir = resolveTasksDir(base, mid, sid);
+  if (!tDir) return false;
+
+  // Read all task summaries
+  const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+  if (summaryFiles.length === 0) return false;
+
+  const taskSummaries: Array<{ taskId: string; summary: Summary }> = [];
+  for (const file of summaryFiles) {
+    const content = readFileSync(join(tDir, file), "utf-8");
+    if (!content.trim()) continue;
+    const summary = parseSummary(content);
+    const taskId = file.match(/^(T\d+)/)?.[1] ?? file;
+    taskSummaries.push({ taskId, summary });
+  }
+
+  if (taskSummaries.length === 0) return false;
+
+  // Quality gate: multi-task slices need substantive summaries
+  if (taskSummaries.length > 1) {
+    const totalContent = taskSummaries
+      .map(ts => ts.summary.whatHappened || ts.summary.oneLiner || "")
+      .join("");
+    if (totalContent.length < 200) return false;
+  }
+
+  // Aggregate frontmatter
+  const aggregated = aggregateFrontmatter(taskSummaries.map(ts => ts.summary.frontmatter));
+
+  // Build SUMMARY.md
+  const summaryLines: string[] = [
+    "---",
+    `id: ${sid}`,
+    `parent: ${mid}`,
+    `milestone: ${mid}`,
+  ];
+  if (aggregated.provides.length > 0)
+    summaryLines.push(`provides:\n${aggregated.provides.map(p => `  - ${p}`).join("\n")}`);
+  if (aggregated.key_files.length > 0)
+    summaryLines.push(`key_files:\n${aggregated.key_files.map(f => `  - ${f}`).join("\n")}`);
+  if (aggregated.key_decisions.length > 0)
+    summaryLines.push(`key_decisions:\n${aggregated.key_decisions.map(d => `  - ${d}`).join("\n")}`);
+  if (aggregated.patterns_established.length > 0)
+    summaryLines.push(`patterns_established:\n${aggregated.patterns_established.map(p => `  - ${p}`).join("\n")}`);
+  if (aggregated.affects.length > 0)
+    summaryLines.push(`affects:\n${aggregated.affects.map(a => `  - ${a}`).join("\n")}`);
+  if (aggregated.observability_surfaces.length > 0)
+    summaryLines.push(`observability_surfaces:\n${aggregated.observability_surfaces.map(o => `  - ${o}`).join("\n")}`);
+  const allPassed = taskSummaries.every(ts => ts.summary.frontmatter.verification_result === "passed");
+  summaryLines.push(`verification_result: ${allPassed ? "passed" : "mixed"}`);
+  summaryLines.push(`completed_at: ${new Date().toISOString()}`);
+  summaryLines.push("---");
+  summaryLines.push("");
+  summaryLines.push(`# ${sid}: Slice Summary`);
+  summaryLines.push("");
+
+  // Task one-liners
+  for (const { taskId, summary } of taskSummaries) {
+    const line = summary.oneLiner || summary.title || taskId;
+    summaryLines.push(`- **${taskId}**: ${line}`);
+  }
+  summaryLines.push("");
+
+  const sDir = resolveSlicePath(base, mid, sid);
+  if (!sDir) return false;
+
+  const summaryPath = join(sDir, `${sid}-SUMMARY.md`);
+  atomicWriteSync(summaryPath, summaryLines.join("\n"));
+  process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+
+  // Build UAT.md from plan's Verification section
+  const planPath = resolveSliceFile(base, mid, sid, "PLAN");
+  if (planPath) {
+    const planContent = readFileSync(planPath, "utf-8");
+    const verification = extractMarkdownSection(planContent, "Verification");
+    if (verification) {
+      const uatContent = [
+        "---",
+        `id: ${sid}`,
+        `parent: ${mid}`,
+        "type: artifact-driven",
+        "---",
+        "",
+        `# ${sid}: UAT`,
+        "",
+        verification,
+        "",
+      ].join("\n");
+      const uatPath = join(sDir, `${sid}-UAT.md`);
+      atomicWriteSync(uatPath, uatContent);
+      process.stderr.write(`gsd-mechanical: wrote ${uatPath}\n`);
+    }
+  }
+
+  // Mark slice [x] in ROADMAP
+  await markSliceInRoadmap(base, mid, sid);
+
+  // Append new decisions if any
+  await appendNewDecisions(base, taskSummaries.map(ts => ts.summary));
+
+  // Update requirements if all passed
+  if (allPassed) {
+    await mechanicalRequirementsUpdate(base, mid, sid, taskSummaries.map(ts => ts.summary));
+  }
+
+  return true;
+}
+
+// ─── Requirements Update ─────────────────────────────────────────────────────
+
+/**
+ * Conservative requirements update: mark requirements Validated only if
+ * all tasks' verification passed.
+ */
+export async function mechanicalRequirementsUpdate(
+  _base: string, _mid: string, _sid: string, _taskSummaries: Summary[],
+): Promise<void> {
+  // Conservative: requirements validation requires human or LLM judgment
+  // about whether the requirement is truly met. Mechanical completion only
+  // marks the slice done — requirement status updates are left to the
+  // existing validation pipeline.
+}
+
+// ─── Decision Aggregation ────────────────────────────────────────────────────
+
+/**
+ * Collect key_decisions from task summaries, deduplicate against existing
+ * DECISIONS.md, and append new ones.
+ */
+export async function appendNewDecisions(
+  base: string, taskSummaries: Summary[],
+): Promise<void> {
+  const allDecisions = taskSummaries.flatMap(s => s.frontmatter.key_decisions);
+  if (allDecisions.length === 0) return;
+
+  const decisionsPath = resolveGsdRootFile(base, "DECISIONS");
+  const existing = existsSync(decisionsPath)
+    ? readFileSync(decisionsPath, "utf-8")
+    : "";
+
+  // Deduplicate — skip decisions whose text already appears in the file
+  const newDecisions = allDecisions.filter(d =>
+    d.trim() && !existing.includes(d.trim()),
+  );
+  if (newDecisions.length === 0) return;
+
+  const entries = newDecisions
+    .map(d => `- ${d} _(auto-aggregated from task summaries)_`)
+    .join("\n");
+
+  const updated = existing.trimEnd() + "\n\n### Auto-aggregated Decisions\n\n" + entries + "\n";
+  atomicWriteSync(decisionsPath, updated);
+  process.stderr.write(`gsd-mechanical: appended ${newDecisions.length} decision(s) to DECISIONS.md\n`);
+}
+
+// ─── Milestone Verification ──────────────────────────────────────────────────
+
+export interface MilestoneVerificationResult {
+  verdict: "passed" | "failed" | "mixed";
+  checks: EvidenceJSON[];
+  uatResults: string[];
+  markdown: string;
+}
+
+/**
+ * Aggregate T##-VERIFY.json files and S##-UAT-RESULT.md files across all
+ * slices in a milestone to produce VALIDATION.md.
+ */
+export async function aggregateMilestoneVerification(
+  base: string, mid: string,
+): Promise<MilestoneVerificationResult> {
+  const mDir = resolveMilestonePath(base, mid);
+  if (!mDir) return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+
+  const allChecks: EvidenceJSON[] = [];
+  const allUatResults: string[] = [];
+
+  // Scan all slices
+  const slicesDir = join(mDir, "slices");
+  if (!existsSync(slicesDir)) return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+
+  const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+
+  for (const sliceName of sliceDirs) {
+    const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (tDir) {
+      const verifyFiles = resolveTaskJsonFiles(tDir, "VERIFY");
+      for (const vf of verifyFiles) {
+        try {
+          const content = readFileSync(join(tDir, vf), "utf-8");
+          const evidence = JSON.parse(content) as EvidenceJSON;
+          allChecks.push(evidence);
+        } catch {
+          // Skip malformed JSON
+        }
+      }
+    }
+
+    // Check for UAT result
+    const uatResultPath = resolveSliceFile(base, mid, sid, "UAT-RESULT");
+    if (uatResultPath) {
+      try {
+        const uatContent = readFileSync(uatResultPath, "utf-8");
+        allUatResults.push(`### ${sid}\n\n${uatContent}`);
+      } catch {
+        // Non-fatal
+      }
+    }
+  }
+
+  // Determine verdict
+  const allPassed = allChecks.length > 0 && allChecks.every(c => c.passed);
+  const anyFailed = allChecks.some(c => !c.passed);
+  const verdict: "passed" | "failed" | "mixed" = allPassed
+    ? "passed"
+    : anyFailed
+      ? (allChecks.some(c => c.passed) ? "mixed" : "failed")
+      : "passed"; // No checks = vacuously passed
+
+  // Build VALIDATION.md
+  const mdLines: string[] = [
+    "---",
+    `milestone: ${mid}`,
+    `verdict: ${verdict}`,
+    "remediation_round: 0",
+    `validated_at: ${new Date().toISOString()}`,
+    "---",
+    "",
+    `# ${mid}: Milestone Validation`,
+    "",
+    `**Verdict:** ${verdict}`,
+    "",
+    "## Verification Results",
+    "",
+  ];
+
+  if (allChecks.length === 0) {
+    mdLines.push("_No verification evidence found._");
+  } else {
+    mdLines.push("| Task | Passed | Checks | Failed |");
+    mdLines.push("|------|--------|--------|--------|");
+    for (const check of allChecks) {
+      const failedCount = check.checks.filter(c => c.verdict === "fail").length;
+      mdLines.push(
+        `| ${check.taskId} | ${check.passed ? "yes" : "no"} | ${check.checks.length} | ${failedCount} |`,
+      );
+    }
+  }
+
+  if (allUatResults.length > 0) {
+    mdLines.push("");
+    mdLines.push("## UAT Results");
+    mdLines.push("");
+    mdLines.push(...allUatResults);
+  }
+
+  mdLines.push("");
+
+  const markdown = mdLines.join("\n");
+
+  // Write VALIDATION.md
+  const validationPath = join(mDir, `${mid}-VALIDATION.md`);
+  atomicWriteSync(validationPath, markdown);
+  process.stderr.write(`gsd-mechanical: wrote ${validationPath}\n`);
+
+  return { verdict, checks: allChecks, uatResults: allUatResults, markdown };
+}
+
+// ─── Milestone Summary ──────────────────────────────────────────────────────
+
+/**
+ * Read all S##-SUMMARY.md files and produce M##-SUMMARY.md.
+ */
+export async function generateMilestoneSummary(
+  base: string, mid: string,
+): Promise<string> {
+  const mDir = resolveMilestonePath(base, mid);
+  if (!mDir) return "";
+
+  const slicesDir = join(mDir, "slices");
+  if (!existsSync(slicesDir)) return "";
+
+  const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+
+  const aggregatedProvides: string[] = [];
+  const aggregatedKeyFiles: string[] = [];
+  const aggregatedKeyDecisions: string[] = [];
+  const aggregatedPatterns: string[] = [];
+  const sliceOneLinerList: string[] = [];
+
+  for (const sliceName of sliceDirs) {
+    const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+    const summaryPath = resolveSliceFile(base, mid, sid, "SUMMARY");
+    if (!summaryPath) continue;
+
+    try {
+      const content = readFileSync(summaryPath, "utf-8");
+      const summary = parseSummary(content);
+      aggregatedProvides.push(...summary.frontmatter.provides);
+      aggregatedKeyFiles.push(...summary.frontmatter.key_files);
+      aggregatedKeyDecisions.push(...summary.frontmatter.key_decisions);
+      aggregatedPatterns.push(...summary.frontmatter.patterns_established);
+      sliceOneLinerList.push(`- **${sid}**: ${summary.oneLiner || summary.title || sid}`);
+    } catch {
+      sliceOneLinerList.push(`- **${sid}**: _(summary unavailable)_`);
+    }
+  }
+
+  const mdLines: string[] = [
+    "---",
+    `id: ${mid}`,
+  ];
+  if (dedup(aggregatedProvides).length > 0)
+    mdLines.push(`provides:\n${dedup(aggregatedProvides).map(p => `  - ${p}`).join("\n")}`);
+  if (dedup(aggregatedKeyFiles).length > 0)
+    mdLines.push(`key_files:\n${dedup(aggregatedKeyFiles).map(f => `  - ${f}`).join("\n")}`);
+  if (dedup(aggregatedKeyDecisions).length > 0)
+    mdLines.push(`key_decisions:\n${dedup(aggregatedKeyDecisions).map(d => `  - ${d}`).join("\n")}`);
+  if (dedup(aggregatedPatterns).length > 0)
+    mdLines.push(`patterns_established:\n${dedup(aggregatedPatterns).map(p => `  - ${p}`).join("\n")}`);
+  mdLines.push(`completed_at: ${new Date().toISOString()}`);
+  mdLines.push("---");
+  mdLines.push("");
+  mdLines.push(`# ${mid}: Milestone Summary`);
+  mdLines.push("");
+  mdLines.push("## Slices");
+  mdLines.push("");
+  mdLines.push(...sliceOneLinerList);
+  mdLines.push("");
+
+  const content = mdLines.join("\n");
+
+  // Write M##-SUMMARY.md
+  const summaryPath = join(mDir, `${mid}-SUMMARY.md`);
+  atomicWriteSync(summaryPath, content);
+  process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+
+  return content;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function aggregateFrontmatter(fms: SummaryFrontmatter[]): {
+  provides: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  affects: string[];
+  observability_surfaces: string[];
+} {
+  return {
+    provides: dedup(fms.flatMap(f => f.provides)),
+    key_files: dedup(fms.flatMap(f => f.key_files)),
+    key_decisions: dedup(fms.flatMap(f => f.key_decisions)),
+    patterns_established: dedup(fms.flatMap(f => f.patterns_established)),
+    affects: dedup(fms.flatMap(f => f.affects)),
+    observability_surfaces: dedup(fms.flatMap(f => f.observability_surfaces)),
+  };
+}
+
+function dedup(arr: string[]): string[] {
+  return [...new Set(arr.filter(s => s.trim()))];
+}
+
+async function markSliceInRoadmap(base: string, mid: string, sid: string): Promise<void> {
+  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+  if (!roadmapPath) return;
+  const content = await loadFile(roadmapPath);
+  if (!content) return;
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[x] **${sid}:`,
+  );
+  if (updated !== content) {
+    atomicWriteSync(roadmapPath, updated);
+    process.stderr.write(`gsd-mechanical: marked ${sid} done in ROADMAP\n`);
+  }
+}
+
+function readdirSyncSafe(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

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

@@ -13,11 +13,11 @@
  *   4. On crash recovery or fresh start, the ledger is loaded from disk
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { gsdRoot } from "./paths.js";
 import { getAndClearSkills } from "./skill-telemetry.js";
+import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // Re-export from shared — canonical implementation lives in format-utils.
 export { formatTokenCount } from "../shared/mod.js";
@@ -502,45 +502,31 @@ function metricsPath(base: string): string {
   return join(gsdRoot(base), "metrics.json");
 }
 
+function isMetricsLedger(data: unknown): data is MetricsLedger {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as MetricsLedger).version === 1 &&
+    Array.isArray((data as MetricsLedger).units)
+  );
+}
+
+function defaultLedger(): MetricsLedger {
+  return { version: 1, projectStartedAt: Date.now(), units: [] };
+}
+
 /**
  * Load ledger from disk without initializing in-memory state.
  * Used by history/export commands outside of auto-mode.
  */
 export function loadLedgerFromDisk(base: string): MetricsLedger | null {
-  try {
-    const raw = readFileSync(metricsPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && Array.isArray(parsed.units)) {
-      return parsed as MetricsLedger;
-    }
-  } catch {
-    // File doesn't exist or is corrupt
-  }
-  return null;
+  return loadJsonFileOrNull(metricsPath(base), isMetricsLedger);
 }
 
 function loadLedger(base: string): MetricsLedger {
-  try {
-    const raw = readFileSync(metricsPath(base), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version === 1 && Array.isArray(parsed.units)) {
-      return parsed as MetricsLedger;
-    }
-  } catch {
-    // File doesn't exist or is corrupt — start fresh
-  }
-  return {
-    version: 1,
-    projectStartedAt: Date.now(),
-    units: [],
-  };
+  return loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger);
 }
 
 function saveLedger(base: string, data: MetricsLedger): void {
-  try {
-    mkdirSync(gsdRoot(base), { recursive: true });
-    writeFileSync(metricsPath(base), JSON.stringify(data, null, 2) + "\n", "utf-8");
-  } catch {
-    // Don't let metrics failures break auto-mode
-  }
+  saveJsonFile(metricsPath(base), data);
 }

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

@@ -137,14 +137,6 @@ export function clearPathCache(): void {
 
 // ─── Name Builders ─────────────────────────────────────────────────────────
 
-/**
- * Build a directory name from an ID.
- * ("M001") → "M001"
- */
-export function buildDirName(id: string): string {
-  return id;
-}
-
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"
@@ -244,6 +236,23 @@ export function resolveTaskFiles(tasksDir: string, suffix: string): string[] {
   }
 }
 
+/**
+ * Find all task JSON files matching a pattern in a tasks directory.
+ * Returns sorted file names matching T##-SUFFIX.json or legacy T##-*-SUFFIX.json
+ */
+export function resolveTaskJsonFiles(tasksDir: string, suffix: string): string[] {
+  if (!existsSync(tasksDir)) return [];
+  try {
+    const currentPattern = new RegExp(`^T\\d+-${suffix}\\.json$`, "i");
+    const legacyPattern = new RegExp(`^T\\d+-.*-${suffix}\\.json$`, "i");
+    return cachedReaddir(tasksDir)
+      .filter(f => currentPattern.test(f) || legacyPattern.test(f))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
 // ─── Full Path Builders ────────────────────────────────────────────────────
 
 export const GSD_ROOT_FILES = {

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

@@ -254,13 +254,19 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
           subagent: "claude-sonnet-4-5-20250514",
         },
         phases: {
+          skip_research: true,
+          skip_reassess: true,
           skip_slice_research: true,
         },
       };
     case "quality":
       return {
         models: {},
-        phases: {},
+        phases: {
+          skip_research: true,
+          skip_slice_research: true,
+          skip_reassess: true,
+        },
       };
   }
 }

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

@@ -172,9 +172,10 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (p.skip_reassess !== undefined) validatedPhases.skip_reassess = !!p.skip_reassess;
       if (p.skip_slice_research !== undefined) validatedPhases.skip_slice_research = !!p.skip_slice_research;
       if (p.skip_milestone_validation !== undefined) validatedPhases.skip_milestone_validation = !!p.skip_milestone_validation;
+      if (p.reassess_after_slice !== undefined) validatedPhases.reassess_after_slice = !!p.reassess_after_slice;
       if ((p as any).require_slice_discussion !== undefined) (validatedPhases as any).require_slice_discussion = !!(p as any).require_slice_discussion;
       // Warn on unknown phase keys
-      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation", "require_slice_discussion"]);
+      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation", "reassess_after_slice", "require_slice_discussion"]);
       for (const key of Object.keys(p)) {
         if (!knownPhaseKeys.has(key)) {
           warnings.push(`unknown phases key "${key}" — ignored`);

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

@@ -16,13 +16,15 @@ Summarize your understanding of the specification concretely:
 - Scope estimate (how many milestones × slices)
 - Any ambiguities or gaps you notice
 
-### Step 2: Investigate
+### Step 2: Investigate (brief)
 
-Scout the codebase to understand what already exists:
+Quickly scout the codebase to understand what already exists — spend no more than 5-6 tool calls here:
 - `ls` the project root and key directories
 - Search for relevant existing code, patterns, dependencies
 - Check library docs if needed (`resolve_library` / `get_library_docs`)
 
+Then move on to writing artifacts. Do not explore exhaustively — the research phase will do deeper investigation later.
+
 ### Step 3: Make Decisions
 
 For any ambiguities or gaps in the specification:

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

@@ -91,7 +91,7 @@ Before moving to the wrap-up gate, verify you have covered:
 - options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
 - **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream.
 
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? Anything I missed?" Wait for confirmation before proceeding.
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for confirmation before proceeding.
 
 If they clarify, absorb the correction and re-verify.
 

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

@@ -12,9 +12,33 @@ All relevant context has been preloaded below — start working immediately with
 
 ## Your Role in the Pipeline
 
-A **researcher agent** already explored the codebase and documented findings in the milestone research doc (inlined above, if present). It identified key files, technology choices, constraints, and risks. **Trust the research.** Your job is strategic decomposition — turning findings into an ordered set of demoable slices — not re-exploration. Don't read code files the research already summarized unless something is ambiguous or missing.
+You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.
 
-After you finish, each slice goes through its own research → plan → execute cycle. Slice researchers dive deeper into the specific area. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
+After you finish, each slice goes through its own plan → execute cycle. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
+
+### Explore First, Then Decompose
+
+Before decomposing, build your understanding:
+
+1. **Codebase exploration.** For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
+2. **Library docs.** Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase.
+3. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
+4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors.
+
+### Strategic Questions to Answer
+
+- What should be proven first?
+- What existing patterns should be reused?
+- What boundary contracts matter?
+- What constraints does the existing codebase impose?
+- Are there known failure modes that should shape slice ordering?
+- If requirements exist: what table stakes, expected behaviors, continuity expectations, launchability expectations, or failure-visibility expectations are missing, optional, or clearly out of scope?
+
+### Source Files
+
+{{sourceFilePaths}}
+
+If milestone research exists (inlined above), trust those findings and skip redundant exploration. If findings are significant and no research file exists yet, write `{{researchOutputPath}}`.
 
 Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. Use complete sentences rather than planner shorthand or fragmentary notes.
 

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

@@ -18,7 +18,21 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
-A **researcher agent** already explored the codebase and documented findings in the slice research doc (inlined above, if present). It identified key files, build order, constraints, and verification approach. **Trust the research.** Your job is decomposition — turning findings into executable tasks — not re-exploration. Don't read code files the research already summarized unless something is ambiguous or missing from its findings.
+You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
+
+### Verify Roadmap Assumptions
+
+Check prior slice summaries (inlined above as dependency summaries, if present). If prior slices discovered constraints, changed approaches, or flagged fragility, adjust your plan accordingly. The roadmap description may be stale — verify it against the current codebase state.
+
+### Explore Slice Scope
+
+Read the code files relevant to this slice. Confirm the roadmap's description of what exists, what needs to change, and what boundaries apply. Use `rg`, `find`, and targeted reads.
+
+### Source Files
+
+{{sourceFilePaths}}
+
+If slice research exists (inlined above), trust those findings and skip redundant exploration.
 
 After you finish, **executor agents** implement each task in isolated fresh context windows. They see only their task plan, the slice plan excerpt (goal/demo/verification), and compressed summaries of prior tasks. They do not see the research doc, the roadmap, or REQUIREMENTS.md. Everything an executor needs must be in the task plan itself — file paths, specific steps, expected inputs and outputs.