gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.84c045fd2

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

@@ -20,8 +20,8 @@ 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;
 
@@ -64,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);
 }
 

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.
 

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

@@ -0,0 +1,148 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. For `.gsd` files in this prompt, use absolute paths rooted at `{{workingDirectory}}` instead of discovering them with `Glob`.
+
+Discuss the **project** as a whole. Identify gray areas at the project level — vision, users, anti-goals, key constraints — ask the user about them, and write `.gsd/PROJECT.md` with the decisions. Use the **Project** 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.
+
+This stage runs ONCE per project, before any milestone-level discussion. It produces the project-level context that all subsequent milestones, requirements, and roadmaps will reference.
+
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
+{{inlinedTemplates}}
+
+---
+
+## Stage Banner
+
+Before your first action, print this banner verbatim in chat:
+
+• QUESTIONING (project)
+
+---
+
+## Interview Protocol
+
+### Open the conversation
+
+Ask the user a single freeform question in plain text, not structured: **"What do you want to build?"**
+
+Wait for their response. This grounds every follow-up in their own terminology.
+
+### Classify project shape
+
+After the opening answer, classify the project as **`simple`** or **`complex`** before continuing. Print the verdict in chat as one line: `Project shape: simple` or `Project shape: complex` followed by a one-line rationale.
+
+**`simple`** — most of these apply: single primary user (the user themselves or one immediate team), no external integrations beyond well-known SDKs/libs, greenfield or self-contained, scope describable in 1–2 sentences without ambiguity, no compliance/regulatory needs, ≤5 distinct capabilities.
+
+**`complex`** — any of these apply: multi-user with roles/permissions, non-trivial brownfield codebase, external integrations with auth/data exchange, compliance/security/regulated domain (PII, payments, healthcare), >5 capabilities or unclear scope, cross-team/cross-org coordination, novel domain where assumptions need validation.
+
+**Default to `complex` when uncertain.** The user can override the verdict in plain text; if they do, accept it and proceed.
+
+The verdict drives the rest of this stage and gets persisted to PROJECT.md → `## Project Shape`. Downstream stages (`discuss-requirements`, `discuss-milestone`, `discuss-slice`) read it from there.
+
+### Before deeper rounds
+
+Do a lightweight targeted investigation so your questions are grounded in reality:
+- Scout the codebase (`rg`, `find`, or `scout`) — is this greenfield or brownfield? What language/framework signals exist?
+- Identify any prior `.planning/` or `.gsd/` artifacts hinting at history
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries the user mentions
+
+**Web search budget:** typically 3–5 per turn. Prefer `resolve_library` / `get_library_docs` for library docs. Target 2–3 web searches in the investigation pass; distribute remaining searches across follow-up rounds.
+
+Do **not** go deep — just enough that your follow-ups reflect what's actually true rather than what you assume.
+
+### Question rounds
+
+Ask **1–3 questions per round**. Each round targets one of:
+- **What they're building** — concrete enough to describe to a stranger
+- **Who it's for** — primary users, secondary users, internal vs external
+- **The core value** — the ONE thing that must work even if everything else is cut
+- **Anti-goals** — what they explicitly don't want, what would disappoint them
+- **Constraints** — budget, timeline, tech limitations, irreversible architectural choices
+- **Existing context** — prior work, brownfield state, decisions already made
+- **Milestone shape** — rough version sequence (v1 / v1.1 / ...) and what differentiates them
+
+**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.
+
+**Cadence is shape-dependent:**
+- **`simple`** — favor 1–2 plain-text rounds. Skip `ask_user_questions` unless you are presenting concrete alternatives. Get to the depth checklist fast.
+- **`complex`** — full investigation, multiple rounds, structured questions when meaningful alternatives exist.
+
+**If `{{structuredQuestionsAvailable}}` is `true` and you use `ask_user_questions`:** ask 1–3 questions per call. Every question object MUST include a stable lowercase `id`. 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 your investigation (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine. Binary depth-check / wrap-up gates are exempt from the 3-or-4 rule. Wait for each tool result before asking the next round.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions.
+
+After each round, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Round cadence
+
+After each round, decide whether you have enough depth to write a strong PROJECT.md.
+
+- **Incremental persistence:** After every 2 question rounds, silently save `.gsd/PROJECT-DRAFT.md` using `gsd_summary_save` with `artifact_type: "PROJECT-DRAFT"` and no `milestone_id`. Crash protection. Do NOT mention this save to the user.
+- If not ready, continue to the next round.
+- Use a wrap-up prompt only when you believe the depth checklist below is satisfied or the user signals they want to stop.
+
+---
+
+## Questioning philosophy
+
+**Start open, follow energy.** Let the user's enthusiasm guide where you dig deeper.
+
+**Challenge vagueness.** When the user says "it should be smart" or "good UX", push for specifics.
+
+**Position-first framing.** Have opinions. "I'd lean toward X because Y — does that match your thinking?" is better than "what do you think about X vs Y?"
+
+**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. Negative constraints are sharper than positive wishes.
+
+**Anti-patterns — never do these:**
+- Checklist walking through predetermined topics regardless of what the user said
+- Canned generic questions ("What are your key success metrics?")
+- Rapid-fire questions without acknowledging answers
+- Asking about technical skill level
+- Asking about specific milestone implementations — that's the next stage
+
+---
+
+## Depth Verification
+
+Before moving to the wrap-up gate, verify you have covered:
+
+- [ ] What they're building — concrete enough to describe to a stranger
+- [ ] Who it's for
+- [ ] Core value (the ONE thing that must work)
+- [ ] Anti-goals / explicit non-wants
+- [ ] Constraints (budget, time, tech, architecture)
+- [ ] Greenfield vs brownfield state
+- [ ] Rough milestone sequence (at least M001's intent)
+
+**Print a structured depth summary in chat first** — using the user's own terminology. Cover what you understood, what shaped your understanding, and any areas of remaining uncertainty.
+
+**Then confirm:**
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with:
+- header: "Depth Check"
+- id: "depth_verification_project_confirm"
+- question: "Did I capture the depth right?"
+- options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
+- **The question ID must contain `depth_verification_project`** — this enables the write-gate downstream.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask.
+
+If they clarify, absorb the correction and re-verify.
+
+The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it.
+
+**CRITICAL — Confirmation gate:** Do not write final PROJECT.md until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block.
+
+---
+
+## Output
+
+Once the user confirms depth:
+
+1. Use the **Project** output template (inlined above).
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing.
+3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
+4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
+5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
+6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.
+7. {{commitInstruction}}
+8. Say exactly: `"Project context written."` — nothing else.