gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

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 {
+  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 {
+  mkdirSync(runtimeDir(basePath), { recursive: true });
+  writeFileSync(
+    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_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

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}}**

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

@@ -0,0 +1,133 @@
+**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.
+
+### 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.
+
+**Plain-text default:** Project discovery is open-ended. Ask question rounds in plain text unless you are presenting 2–3 concrete alternatives with clear tradeoffs.
+
+**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). Do not add a separate "Other" option; the question UI provides a freeform path automatically. 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 `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
+4. 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.
+5. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.
+6. {{commitInstruction}}
+7. Say exactly: `"Project context written."` — nothing else.

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

@@ -0,0 +1,122 @@
+**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 **project-level requirements**. Read `.gsd/PROJECT.md` first — it is the authoritative source for vision, core value, anti-goals, and milestone sequence. All requirements must trace back to it. Identify gray areas about what capabilities the project must deliver, ask the user, and write `.gsd/REQUIREMENTS.md` using the v2 structured `R###` format. Use the **Requirements** output template below.
+
+This stage runs ONCE per project, after `discuss-project` and before any milestone-level work. It produces the explicit capability contract that all milestones, slices, and verification will reference.
+
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
+{{inlinedTemplates}}
+
+---
+
+## Stage Banner
+
+Before your first action, print this banner verbatim in chat:
+
+• REQUIREMENTS
+
+---
+
+## Pre-flight
+
+1. Read `.gsd/PROJECT.md` end-to-end. If it does not exist, STOP and emit: `"PROJECT.md missing — run discuss-project first."`
+2. Extract: Core Value, Anti-goals, Constraints, Milestone Sequence.
+3. Check for existing `.gsd/REQUIREMENTS.md` — if present, this is a refinement pass, not a fresh write. Read existing requirements and treat them as the working set.
+
+---
+
+## Interview Protocol
+
+### Before your first question round
+
+Investigate to ground requirements in reality:
+- Scout the codebase for existing capabilities (anything already built counts as `Validated` or `Active`)
+- Cross-check the project's milestone sequence — every milestone must have at least one Active requirement it owns
+- Use `resolve_library` / `get_library_docs` for libraries that imply capabilities (auth library → auth requirements)
+- Identify table-stakes capabilities for the domain (research the domain only if PROJECT.md confidence is low)
+
+**Web search budget:** 3–5 per turn. Target 1–2 web searches in this pre-investigation; reserve the rest for follow-ups.
+
+### Question rounds
+
+Ask **1–3 questions per round**. Each round targets one dimension:
+
+- **Capability scoping** — what must the project DO at the capability level? (Not features, capabilities. "User can recover account" not "Forgot-password button")
+- **Class assignment** — for each capability, which class? (`core-capability`, `primary-user-loop`, `launchability`, `continuity`, `failure-visibility`, `integration`, `quality-attribute`, `operability`, `admin/support`, `compliance/security`, `differentiator`, `constraint`, `anti-feature`)
+- **Milestone ownership** — which milestone in the sequence will own this capability? Provisional ownership for later milestones is fine.
+- **Status** — Active (must build), Deferred (later), Out of Scope (explicit no), Validated (already proven)
+- **Anti-features** — what capabilities are explicitly excluded? Capture as `out-of-scope` with rationale.
+- **Quality attributes** — performance, reliability, observability, security thresholds. These are requirements too.
+
+**Never fabricate or simulate user input.** Wait for actual responses.
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. Every question object MUST include a stable lowercase `id`. For class assignments, present the allowed classes as multi-select options. For status, present the four statuses as exclusive options. Ask 1–3 questions per call. Wait for each tool result before asking the next round.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text. Keep each round to 1–3 questions.
+
+### Round cadence
+
+- **Incremental persistence:** After every 2 question rounds, silently save the current requirements draft using `gsd_summary_save` with `artifact_type: "REQUIREMENTS-DRAFT"` and no `milestone_id`. Crash protection. Do NOT mention this save.
+- Continue rounds until the depth checklist is satisfied or the user signals stop.
+
+---
+
+## Questioning philosophy
+
+**Capability-oriented, not feature-oriented.** "User can authenticate" is a capability. "Sign-up button shows on landing page" is implementation. Push back when users describe implementation — extract the underlying capability.
+
+**Position-first framing.** Have opinions. "I'd suggest making this Active because the milestone goal can't ship without it — sound right?"
+
+**Atomic and testable.** Each requirement should be one verifiable thing. Reject "user can sign up and manage profile" — split it.
+
+**Anti-patterns — never do these:**
+- Listing every conceivable feature ("requirement inflation")
+- Vague verbs ("Handle", "Support") — push for "User can X" or "System emits Y when Z"
+- Skipping anti-features — explicit out-of-scope is part of the contract
+- Mapping requirements to slices that don't exist yet — use `M###/none yet` with the milestone id required
+
+---
+
+## Depth Verification
+
+Before the wrap-up gate, verify:
+
+- [ ] Every milestone in PROJECT.md has at least one Active requirement
+- [ ] Core Value (from PROJECT.md) is covered by at least one Active requirement
+- [ ] Each Active requirement has: ID, title, class, status, description, why-it-matters, source, primary owner (`M###/S##` or `M###/none yet`; never bare `none yet`), validation, notes
+- [ ] At least one explicit Out of Scope entry per major capability area (anti-features captured)
+- [ ] Quality attributes (performance, reliability, etc.) captured where the user has stated thresholds
+- [ ] No requirement is implementation-flavored ("button", "endpoint", "table") — all are capability-flavored
+
+**Print a structured requirements table in chat first** — markdown table with columns: ID, Title, Class, Status, Owner, Source. Group by status (Active / Deferred / Out of Scope / Validated). This is the user's audit trail.
+
+**Then confirm:**
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with:
+- header: "Depth Check"
+- id: "depth_verification_requirements_confirm"
+- question: "Are these the right requirements at the right scope?"
+- options: "Yes, ship it (Recommended)", "Not quite — let me adjust"
+- **The question ID must contain `depth_verification_requirements`** — enables the write-gate.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Are these requirements right? Tell me anything to add, remove, or reclassify." Wait for explicit confirmation.
+
+If they adjust, absorb and re-verify.
+
+**CRITICAL — Confirmation gate:** Do not write final REQUIREMENTS.md until explicit confirmation. Never rationalize past it.
+
+---
+
+## Output
+
+Once the user confirms:
+
+1. Use the **Requirements** output template (inlined above) to render the final markdown in working memory.
+2. Every entry must conform to the `R###` format with all listed fields. Use `gsd_requirement_save` (NOT plain file edit) for each requirement so DB state is saved first.
+3. After all `gsd_requirement_save` calls complete, call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"`; omit `milestone_id`. The requirements table is the source of truth, and this tool renders `.gsd/REQUIREMENTS.md` from DB state. Pass the rendered markdown as `content` for audit context only; do not rely on markdown to update DB rows.
+4. The file MUST contain all required sections: `## Active`, `## Validated`, `## Deferred`, `## Out of Scope`, `## Traceability`, `## Coverage Summary`. Empty sections are OK; missing sections are not.
+5. Print the final coverage summary in chat: `Active: N | Validated: N | Deferred: N | Out of Scope: N | Mapped to slices: N | Unmapped active: N`.
+6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "REQUIREMENTS"`; that creates a fake milestone instead of `.gsd/REQUIREMENTS.md`.
+7. {{commitInstruction}}
+8. End your response with exactly: `Requirements written.`