gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/dist/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/dist/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/dist/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/dist/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/dist/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.

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

@@ -0,0 +1,126 @@
+**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, and the project shape verdict — read the `## Project Shape` section and look for `**Complexity:**` (verdict is either `simple` or `complex`; default to `complex` if the section is missing or unclear).
+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.
+
+**Shape-dependent cadence:**
+- **`simple`** — favor a single fast pass: extract requirements directly from PROJECT.md, ask 1–2 plain-text clarifying questions only if a class or status assignment is genuinely ambiguous, then write REQUIREMENTS.md.
+- **`complex`** — full multi-round questioning with structured 3–4-option questions where alternatives matter.
+
+---
+
+## 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. In **`complex`** mode, any free-form question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option grounded in the investigation above. The class-assignment and status questions are exempt — they have fixed enumerations. 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.`

package/dist/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -8,6 +8,13 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve
 
 ## Interview Protocol
 
+### 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 the section is missing or unclear).
+
+- **`simple`** — favor 1–2 plain-text rounds, write the slice context fast. Skip parallel-research investigation.
+- **`complex`** — full investigation with structured 3–4-option questions.
+
 ### Before your first question round
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -24,7 +31,7 @@ Do **not** go deep — just enough that your questions reflect what's actually t
 
 **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`:** Ask **1–3 questions per round** using `ask_user_questions`. **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`:** Ask **1–3 questions per round** using `ask_user_questions`. 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. Binary wrap-up gates are exempt from the 3-or-4 rule. **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 **1–3 questions per round** in plain text. Number them and wait for the user's response before asking the next round.
 Keep each question focused on one of:
 - **UX and user-facing behaviour** — what does the user see, click, trigger, or experience?

package/dist/resources/extensions/gsd/prompts/guided-research-decision.md

@@ -0,0 +1,70 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
+Capture the project research decision. This stage runs ONCE per project, after `discuss-requirements` and before any milestone-level work. It asks the user whether to run domain research now, then records the decision so downstream dispatch rules know what to do.
+
+This is a **fixed-question** stage. Do NOT do open Socratic interviewing. Ask the one question below, capture the answer, write the marker file, end.
+
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
+---
+
+## Stage Banner
+
+Print this banner verbatim in chat as your first action:
+
+• RESEARCH DECISION
+
+Then say: "Domain research finds table-stakes capabilities, ecosystem norms, and common pitfalls. Worth doing if you don't know this domain cold."
+
+---
+
+## The Question
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** call `ask_user_questions` exactly once with:
+
+- **header:** "Research"
+- **question:** "Run domain research before starting milestones?"
+- **options:**
+  - "Skip (Recommended)" — go straight to milestone work; you know the domain
+  - "Yes" — runs 4 parallel research passes (stack, features, architecture, pitfalls) before milestone planning
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Run domain research now? (y/n)"
+
+---
+
+## Output
+
+Once the answer is captured:
+
+1. Make sure `.gsd/runtime/` exists: `mkdir -p .gsd/runtime/`
+2. Write `.gsd/runtime/research-decision.json` containing:
+   ```json
+   {
+     "decision": "research" | "skip",
+     "decided_at": "<ISO 8601 timestamp>",
+     "source": "research-decision"
+   }
+   ```
+   - Use `"research"` if the user picked "Yes" or answered yes/y in plain text
+   - Use `"skip"` if the user picked "Skip" or answered no/n
+   - Always include `"source": "research-decision"`
+   - Optional for ambiguous or "Other / let me explain" answers: add an `inference_note` field to the JSON. Do not put inference text in chat.
+3. Print exactly one of these one-line confirmations in chat:
+```text
+Research decision: research
+Research decision: skip
+```
+4. Say exactly:
+```text
+Research decision recorded.
+```
+Nothing else.
+
+---
+
+## Critical rules
+
+- One question, one turn, write file, done. No follow-ups.
+- Do NOT actually run research in this stage — that's a separate dispatch unit (`research-project`) that fires only if the decision is `research`.
+- Do NOT call `ask_user_questions` more than once per turn.
+- If the user picks "Other / let me explain" or gives an ambiguous freeform answer, treat it as "skip" (the recommended choice). Do not change the required confirmation strings.

package/dist/resources/extensions/gsd/prompts/guided-research-project.md

@@ -0,0 +1,120 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
+Run **project-level domain research** in 4 parallel dimensions. Read `.gsd/PROJECT.md` and `.gsd/REQUIREMENTS.md` first — they define the scope of what to research. Then spawn 4 parallel `Task` calls (one per dimension) using agent class `scout`, each writing its findings to `.gsd/research/`. This stage runs ONCE per project, after `discuss-requirements` and the `research-decision` gate, before any milestone-level work.
+
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
+---
+
+## Stage Banner
+
+Print this banner verbatim in chat as your first action:
+
+• RESEARCHING (project)
+
+Then say: "Spawning 4 research agents in parallel: stack, features, architecture, pitfalls."
+
+---
+
+## Pre-flight
+
+1. Read `.gsd/PROJECT.md` end-to-end. Extract: domain, vision, current state, milestone sequence.
+2. Read `.gsd/REQUIREMENTS.md` end-to-end. Extract: Active requirement classes (focus research on what the project must deliver).
+3. `mkdir -p .gsd/research/`
+
+If either file is missing, STOP and emit: `"PROJECT.md or REQUIREMENTS.md missing — research-project cannot run."`
+
+---
+
+## Fan-out
+
+Issue **4 `Task` tool calls in a single assistant response** (one tool block containing four `Task` invocations). Use `agent: "scout"` for every task. Do not use `agent: "researcher"` — this unit runs under the `planning-dispatch` tools-policy and only `scout` is permitted for project research. The tool runtime executes the calls concurrently — that is the parallelism mechanism here. Do not split them across multiple turns; do not chain them sequentially. After issuing the four calls, wait for ALL of their tool results to come back before doing anything in the "After fan-out completes" step below.
+
+Each task gets its own focused prompt. Each task writes one file.
+
+### Task 1 — Stack research → `.gsd/research/STACK.md`
+
+Prompt:
+
+> Research the standard stack for [domain] as of today. Identify the dominant libraries, frameworks, runtimes, and infrastructure tools used by [domain] products. For each: current stable version, primary alternatives, why teams pick it, when to avoid it.
+>
+> Constraints from PROJECT.md: [list any tech constraints / required frameworks the user already specified].
+>
+> Deliverable: `.gsd/research/STACK.md` with sections:
+> - **Recommended Stack** (with versions and rationale)
+> - **Alternatives Considered** (and why not)
+> - **What NOT to use** (and why)
+> - **Open questions** (anything where the user's choice will materially shape the architecture)
+>
+> Use `resolve_library` / `get_library_docs` for library docs. Use web search sparingly (2–3 queries). Cite sources where versions matter. Mark confidence per recommendation: high / medium / low.
+
+### Task 2 — Features research → `.gsd/research/FEATURES.md`
+
+Prompt:
+
+> Research what features [domain] products typically have. Categorize as **table stakes** (users expect this; missing it breaks the product) vs **differentiators** (compelling but optional).
+>
+> Active requirements from REQUIREMENTS.md to cross-check: [list R### IDs and titles].
+>
+> Deliverable: `.gsd/research/FEATURES.md` with sections per category (Authentication, Content, Notifications, etc.):
+> - **Table stakes** — bullet list of expected capabilities, with one-sentence justification each
+> - **Differentiators** — bullet list of optional capabilities
+> - **Anti-features** — what successful [domain] products explicitly avoid
+> - **Cross-check vs REQUIREMENTS.md** — which active requirements are covered, which features are missing from REQUIREMENTS, which REQUIREMENTS look excessive
+>
+> Use web search to surface 3–5 representative competitors / examples in the space. Don't go deep — aim for coverage breadth.
+
+### Task 3 — Architecture research → `.gsd/research/ARCHITECTURE.md`
+
+Prompt:
+
+> Research the typical architecture for [domain] products at the project's scale. Surface common patterns, data models, integration points, and scaling considerations.
+>
+> Vision/scale signals from PROJECT.md: [extract scale-relevant phrases — solo / small team / enterprise / planned user count].
+>
+> Deliverable: `.gsd/research/ARCHITECTURE.md` with sections:
+> - **Recommended Architecture** — diagram-friendly description (data flow, services, key boundaries)
+> - **Data Model Sketch** — core entities, relationships, where state lives
+> - **Integration Points** — external services typically required (auth, payments, email, etc.)
+> - **Scaling Tier** — what works at this project's scale, what to defer
+> - **Reversibility risk** — which architectural choices are hardest to walk back later
+>
+> Use `resolve_library` for library-specific architecture docs. Mark confidence per recommendation.
+
+### Task 4 — Pitfalls research → `.gsd/research/PITFALLS.md`
+
+Prompt:
+
+> Research common failure modes, gotchas, and footguns for [domain] products. Things experienced builders wish they'd known earlier.
+>
+> Project type from PROJECT.md: [greenfield / brownfield / migration].
+>
+> Deliverable: `.gsd/research/PITFALLS.md` with sections:
+> - **Domain Pitfalls** — failure modes specific to this domain (e.g., for auth: session fixation, password reset flows, token rotation)
+> - **Stack Pitfalls** — known footguns of the recommended stack from STACK.md (or domain norm if STACK isn't ready)
+> - **Scope Traps** — features that look small but are huge ("just add notifications", "just add search")
+> - **Compliance / Security gotchas** — surfaces where regulators or attackers tend to bite
+> - **Migration pitfalls** (only if brownfield) — common breakage when retrofitting [domain] capability into existing systems
+>
+> Web search for postmortems, incident reports, and "lessons learned" content. Sources matter — prefer specific writeups over generic listicles.
+
+---
+
+## After fan-out completes
+
+Once all 4 tasks return:
+
+1. Verify all 4 files exist: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md` in `.gsd/research/`. If any are missing, retry that task once.
+2. Print a concise summary in chat: one sentence per dimension, what each found or why it was blocked. The runtime clears the dispatch marker after this unit exits.
+3. Say exactly: `"Project research complete."` — nothing else.
+
+---
+
+## Critical rules
+
+- **Issue all 4 `Task` calls in a single assistant response** (one block of four tool calls). The tool runtime parallelizes them; do NOT chain them across turns or await them individually.
+- **Each task writes exactly one file** to `.gsd/research/`. No cross-writes.
+- **Research is informational, not prescriptive** — it surfaces options; the user / requirements stage already chose what to build.
+- **Stay within scope** — don't research milestones or slices. That's a different stage.
+- **Budget:** ~3–5 web searches per dimension. Prefer `resolve_library` / `get_library_docs` for library questions.
+- If any task fails twice, write a placeholder `.gsd/research/{DIMENSION}-BLOCKER.md` with the failure reason and continue. If all four dimensions are blockers, the runtime will stop before milestone planning because no usable research exists.