gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.4ea7d80e7

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

@@ -1,8 +1,8 @@
-**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`.
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `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.
+Discuss the **project** as a whole: vision, users, anti-goals, constraints, and rough milestone sequence. Ask only real gray areas, then write `.gsd/PROJECT.md` with the **Project** template below. If a `GSD Skill Preferences` block exists, use it; artifact rules still apply.
 
-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.
+This runs once before milestone discussion. Later milestones, requirements, and roadmaps depend on it.
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
@@ -22,115 +22,80 @@ Before your first action, print this banner verbatim in chat:
 
 ### 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.
+Ask the user a single freeform question in plain text, not structured: **"What do you want to build?"** Wait for the response so follow-ups use their 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.
+After the opening answer, classify project shape as **`simple`** or **`complex`**. Print exactly one verdict line, `Project shape: simple` or `Project shape: complex`, plus 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.
+**`simple`** — most apply: single primary user/team, no integrations beyond common SDKs/libs, greenfield/self-contained, scope fits 1-2 sentences, no compliance/regulatory needs, <=5 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.
+**`complex`** — any apply: roles/permissions, non-trivial brownfield codebase, auth/data integrations, compliance/security/regulated domain such as PII/payments/healthcare, >5 capabilities or unclear scope, cross-team/org work, novel domain needing 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.
+Persist the verdict to PROJECT.md -> `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `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.
+Investigate enough to avoid assumption-driven questions:
+- Scout code with `rg`, `find`, or `scout` for greenfield/brownfield and framework signals.
+- Check prior `.planning/` or `.gsd/` artifacts.
+- Use `resolve_library` / `get_library_docs` for unfamiliar mentioned libraries.
 
-Do **not** go deep — just enough that your follow-ups reflect what's actually true rather than what you assume.
+**Web search budget:** typically 3-5 per turn. Prefer docs tools; use 2-3 searches first and save the rest.
 
 ### 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
+Ask **1–3 questions per round**, one focus at a time: what, who, core value, anti-goals, constraints, existing context, or milestone shape.
 
 **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.
+**Shape-dependent cadence:**
+- **`simple`**: 1-2 plain-text rounds; use `ask_user_questions` only for concrete alternatives; reach the depth checklist quickly.
+- **`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 `true` and you use `ask_user_questions`:** ask 1-3 questions per call. Every question needs stable lowercase `id`. Keep labels short (3-5 words). In **`complex`** mode, multi-choice questions MUST offer **3 or 4 concrete, researched options** plus **"Other — let me discuss"**; options must be grounded in the investigation, not placeholders. In **`simple`** mode, 2 options is fine. Binary depth-check/wrap-up gates are exempt. Wait for each tool result before 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.
+After each round, investigate only new unknowns, then ask the next round.
 
 ### Round cadence
 
-After each round, decide whether you have enough depth to write a strong PROJECT.md.
+After each round, decide whether PROJECT.md would be strong enough.
 
-- **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.
+- **Incremental persistence:** After every 2 question rounds, silently save `.gsd/PROJECT-DRAFT.md` via `gsd_summary_save` with `artifact_type: "PROJECT-DRAFT"` and no `milestone_id`. 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.
+- Use a wrap-up prompt only when the depth checklist is satisfied or the user wants 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.
+Start open and follow the user's language. Challenge vague phrases with specifics. Use position-first framing when useful: "I'd lean toward X because Y — does that match your thinking?" Ask what would disappoint them and what they do not want.
 
-**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
+**Anti-patterns — never do these:** checklist walking, canned questions ("What are your key success metrics?"), rapid-fire interrogation, asking about technical skill level, or asking milestone implementation details.
 
 ---
 
 ## 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)
+Before the wrap-up gate, verify coverage: what they're building, who it's for, core value, anti-goals, constraints, greenfield/brownfield state, and rough milestone sequence.
 
-**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.
+**Print a structured depth summary in chat first** using the user's terminology: what you understood, what shaped it, and 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 `true`:** use `ask_user_questions` with header "Depth Check", id "depth_verification_project_confirm", question "Did I capture the depth right?", and options "Yes, you got it (Recommended)" / "Not quite — let me clarify". **The question ID must contain `depth_verification_project`** so the write-gate can detect it.
 
-**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 `{{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, 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.
+**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, re-ask.
 
 ---
 
@@ -139,7 +104,7 @@ The depth verification is the only required confirmation gate. Do not add a seco
 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.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` and persists to DB. Preserve the user's terms 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.

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

@@ -1,8 +1,8 @@
-**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`.
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `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.
+Discuss **project-level requirements**. Read `.gsd/PROJECT.md` first; it is authoritative for vision, core value, anti-goals, and milestone sequence. Requirements must trace to it. Ask capability gray areas, then write `.gsd/REQUIREMENTS.md` using v2 `R###` format and the **Requirements** template.
 
-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.
+This runs once after `discuss-project` and before milestone work, creating the capability contract for milestones, slices, and verification.
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
@@ -20,13 +20,13 @@ Before your first action, print this banner verbatim in chat:
 
 ## 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.
+1. Read `.gsd/PROJECT.md` end-to-end. If missing, STOP and emit: `"PROJECT.md missing — run discuss-project first."`
+2. Extract Core Value, Anti-goals, Constraints, Milestone Sequence, and project shape from `## Project Shape` -> `**Complexity:**` (`simple` or `complex`; default to `complex` if missing/unclear).
+3. If `.gsd/REQUIREMENTS.md` exists, read it 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.
+- **`simple`**: one fast pass. Extract from PROJECT.md, ask 1-2 plain-text clarifiers only when class/status is ambiguous, then write REQUIREMENTS.md.
+- **`complex`**: multi-round questioning with structured 3-4-option questions where alternatives matter.
 
 ---
 
@@ -34,75 +34,48 @@ Before your first action, print this banner verbatim in chat:
 
 ### 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)
+Before questioning, investigate enough to avoid assumption-driven requirements:
+- Scout existing capabilities; already-built work is `Validated` or `Active`.
+- Cross-check milestone sequence; every milestone needs at least one owned Active requirement.
+- Use `resolve_library` / `get_library_docs` for libraries that imply capabilities.
+- Identify domain table-stakes only when 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.
+**Web search budget:** 3–5 per turn. Use 1–2 in 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.
+Ask **1–3 questions per round**, one dimension at a time: capability scoping, class assignment, milestone ownership, status, anti-features, or quality attributes. Keep capabilities testable: "User can recover account", not "Forgot-password button".
 
 **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 `true`:** use `ask_user_questions`. Every question needs stable lowercase `id`. For class assignments, present allowed classes as multi-select options. For status, present the four statuses as exclusive options. In **`complex`** mode, free-form questions MUST offer **3 or 4 concrete, researched options** plus **"Other — let me discuss"** grounded in investigation. class-assignment and status questions are exempt because they have fixed enumerations. Ask 1-3 questions per call and wait.
 
 **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.
+- **Incremental persistence:** After every 2 question rounds, silently save the draft using `gsd_summary_save` with `artifact_type: "REQUIREMENTS-DRAFT"` and no `milestone_id`. Do NOT mention this save to the user.
 - 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?"
+Stay capability-oriented, not feature-oriented: "User can authenticate" is a capability; "Sign-up button shows on landing page" is implementation. Use position-first framing: "I'd suggest making this Active because the milestone goal can't ship without it — sound right?" Make each requirement atomic and testable.
 
-**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
+**Anti-patterns — never do these:** requirement inflation; vague verbs ("Handle", "Support"); skipping anti-features; mapping to slices that do not exist yet. Use `M###/none yet` with the milestone id required, never bare `none yet`.
 
 ---
 
 ## 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
+Before the wrap-up gate, verify: every milestone has an Active requirement; Core Value is covered; each Active requirement has all fields and owner (`M###/S##` or `M###/none yet`; never bare `none yet`); anti-features are captured; stated quality thresholds are captured; no requirement is implementation-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.
+**Print a structured requirements table in chat first**: markdown table with 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 `true`:** use `ask_user_questions` with header "Depth Check", id "depth_verification_requirements_confirm", question "Are these the right requirements at the right scope?", and options "Yes, ship it (Recommended)" / "Not quite — let me adjust". **The question ID must contain `depth_verification_requirements`**.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Are these requirements right? Tell me anything to add, remove, or reclassify." Wait for explicit confirmation.
 
@@ -116,9 +89,9 @@ If they adjust, absorb and re-verify.
 
 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.
+1. Use the **Requirements** output template to render final markdown in memory.
+2. Every entry must use `R###` and all fields. Use `gsd_requirement_save` for each requirement so DB state is saved first.
+3. After all `gsd_requirement_save` calls, call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"`; omit `milestone_id`. The requirements table is source of truth, and this tool renders `.gsd/REQUIREMENTS.md` from DB state. Pass markdown as 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`.

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

@@ -1,6 +1,6 @@
-You are interviewing the user to surface behavioural, UX, and usage grey areas for slice **{{sliceId}}: {{sliceTitle}}** of milestone **{{milestoneId}}**.
+You are interviewing the user to surface behavioural, UX, and usage grey areas for slice **{{sliceId}}: {{sliceTitle}}** in milestone **{{milestoneId}}**.
 
-Your goal is **not** to center the discussion on tech stack trivia, naming conventions, or speculative architecture. Your goal is to produce a context file that captures the human decisions: what this slice should feel like, how it should behave, what edge cases matter, where scope begins and ends, and what the user cares about that won't be obvious from the roadmap entry alone. If a technical choice materially changes scope, proof, or integration behavior, ask it directly and capture it.
+Do **not** center the discussion on tech stack trivia, naming, or speculative architecture. Produce a context file with the human decisions: feel, behaviour, important edge cases, scope boundaries, and user priorities not obvious from the roadmap. If a technical choice materially changes scope, proof, or integration, ask and capture it.
 
 {{inlinedContext}}
 
@@ -8,47 +8,47 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve
 
 ## Interview Protocol
 
-### Read project shape
+### 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).
+Before the first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. Verdicts are **`simple`** or **`complex`**; default to `complex` if 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.
+- **`simple`** — use 1–2 plain-text rounds, then write context. Skip parallel-research investigation.
+- **`complex`** — investigate first, then ask structured 3–4-option questions.
 
-### Before your first question round
+### Investigation
 
-Do a lightweight targeted investigation so your questions are grounded in reality:
-- Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on
-- Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it
-- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation
-- Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built
+Do enough targeted investigation that questions reflect reality:
+- Scout touched code with `rg`, `find`, or `scout` for broad unfamiliar areas.
+- Check roadmap context for predecessor and dependent work.
+- For unfamiliar libraries, prefer `resolve_library` / `get_library_docs` over `search-the-web`.
+- Identify the 3–5 biggest behavioural unknowns where the user's answer materially changes the build.
 
-**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them.
+**Web search budget:** You typically have 3-5 searches per turn. Use `resolve_library` / `get_library_docs` for library docs and `search_and_read` for one-shot topic research. Target 2-3 searches in investigation; keep the rest for later rounds.
 
-Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume.
+Do **not** go deep; stop when you can ask grounded questions.
 
 ### Question rounds
 
 **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`. 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?
-- **Edge cases and failure states** — what happens when things go wrong or are in unusual states?
-- **Scope boundaries** — what is explicitly in vs out for this slice? What deferred to later?
-- **Feel and experience** — tone, responsiveness, feedback, transitions, what "done" feels like to the user
+**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 final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not placeholders. In **`simple`** mode, 2 options is fine. Binary wrap-up gates are exempt. **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 numbered plain-text questions per round**, then wait.
+Focus questions on:
+- **UX and user-facing behaviour** — what users see, click, trigger, or experience.
+- **Edge cases and failure states** — what happens in unusual or broken states.
+- **Scope boundaries** — what is in, out, or deferred.
+- **Feel and experience** — tone, responsiveness, feedback, transitions, and what "done" feels like.
 
-After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
+After answers, investigate new unknowns if needed, then ask the next round.
 
 ### Round cadence
 
-After each round of answers, decide whether you already have enough signal to write the slice context cleanly.
+After each answer round, decide whether you have enough signal to write context cleanly.
 
-- **Incremental persistence:** After every 2 question rounds, silently save a draft `{{sliceId}}-CONTEXT-DRAFT.md` in `{{sliceDirPath}}` using `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT-DRAFT"`. This protects against session crashes losing confirmed work. Do NOT mention this to the user. The final context file will replace it.
-- If not, investigate any new unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
-- Ask a single wrap-up question only when you genuinely believe the slice is well understood or the user signals they want to stop.
-- When you do ask it, offer two choices: "Write the context file" *(recommended when the slice is well understood)* or "One more pass". Use `ask_user_questions` if available, otherwise ask in plain text.
+- **Incremental persistence:** After every 2 question rounds, silently save `{{sliceId}}-CONTEXT-DRAFT.md` in `{{sliceDirPath}}` using `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT-DRAFT"`. Do NOT mention this to the user. Final context replaces it.
+- If more signal is needed, investigate new unknowns and continue. Do **not** ask a meta "ready to wrap up?" question after every round.
+- Ask one wrap-up question only when the slice is well understood or the user wants to stop.
+- Offer exactly two choices: "Write the context file" *(recommended when understood)* or "One more pass". Use `ask_user_questions` if available; otherwise ask in plain text.
 
 **CRITICAL — Non-bypassable gate:** Do NOT write the context file until the user explicitly selects "Write the context file." If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. "Tool not responding, I'll proceed," "auth issues," or "the slice seems well understood, I'll write it" are all **forbidden**. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around.
 
@@ -58,16 +58,16 @@ After each round of answers, decide whether you already have enough signal to wr
 
 Once the user has explicitly confirmed they are ready to write the context file:
 
-1. Use the **Slice Context** output template below
+1. Use the **Slice Context** template below.
 2. `mkdir -p {{sliceDirPath}}`
-3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT"`, and the context as `content` — the tool writes the file to disk and persists to DB. Use the template structure, filling in:
-   - **Goal** — one sentence: what this slice delivers
-   - **Why this Slice** — why now, what it unblocks
-   - **Scope / In Scope** — what was confirmed in scope during the interview
-   - **Scope / Out of Scope** — what was explicitly deferred or excluded
-   - **Constraints** — anything the user flagged as a hard constraint
-   - **Integration Points** — what this slice consumes and produces
-   - **Open Questions** — anything still unresolved, with current thinking
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT"`, and context as `content`; the tool writes to disk and DB. Fill:
+   - **Goal** — one sentence.
+   - **Why this Slice** — why now and what it unblocks.
+   - **Scope / In Scope** — confirmed scope.
+   - **Scope / Out of Scope** — deferred or excluded work.
+   - **Constraints** — hard constraints.
+   - **Integration Points** — consumed and produced interfaces/artifacts.
+   - **Open Questions** — unresolved items with current thinking.
 4. {{commitInstruction}}
 5. Say exactly: `"{{sliceId}} context written."` — nothing else.
 

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

@@ -1,6 +1,6 @@
 **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.
+Run one-time **project-level domain research** after `discuss-requirements` and the `research-decision` gate, before milestone work. Read `.gsd/PROJECT.md` and `.gsd/REQUIREMENTS.md`, then spawn 4 parallel `Task` calls with agent class `scout`, one per research dimension, each writing exactly one file under `.gsd/research/`.
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
@@ -18,8 +18,8 @@ Then say: "Spawning 4 research agents in parallel: stack, features, architecture
 
 ## 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).
+1. Read `.gsd/PROJECT.md` end-to-end. Extract domain, vision, current state, milestone sequence, scale, project type, and tech constraints.
+2. Read `.gsd/REQUIREMENTS.md` end-to-end. Extract Active requirement classes; focus research on required deliverables.
 3. `mkdir -p .gsd/research/`
 
 If either file is missing, STOP and emit: `"PROJECT.md or REQUIREMENTS.md missing — research-project cannot run."`
@@ -28,7 +28,7 @@ If either file is missing, STOP and emit: `"PROJECT.md or REQUIREMENTS.md missin
 
 ## 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.
+Issue **4 `Task` tool calls in one assistant response** (one block with four calls). Use `agent: "scout"` for every task. Do not use `agent: "researcher"`. Runtime parallelizes them, so do not chain calls across turns. Wait for ALL results before "After fan-out completes."
 
 Each task gets its own focused prompt. Each task writes one file.
 
@@ -36,15 +36,11 @@ Each task gets its own focused prompt. Each task writes one file.
 
 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.
+> Research the standard stack for [domain] as of today: dominant libraries, frameworks, runtimes, and infrastructure tools. For each: stable version, alternatives, selection rationale, and avoid-when guidance.
 >
-> Constraints from PROJECT.md: [list any tech constraints / required frameworks the user already specified].
+> Constraints from PROJECT.md: [list any tech constraints / required frameworks the user 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)
+> Deliver `.gsd/research/STACK.md` with: **Recommended Stack** (versions/rationale), **Alternatives Considered**, **What NOT to use**, **Open questions**.
 >
 > 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.
 
@@ -52,32 +48,23 @@ Prompt:
 
 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).
+> Research typical [domain] product features. Categorize as **table stakes** (expected; missing 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
+> Deliver `.gsd/research/FEATURES.md` with sections per category (Authentication, Content, Notifications, etc.): **Table stakes** with one-sentence justifications, **Differentiators**, **Anti-features**, and **Cross-check vs REQUIREMENTS.md** (covered, missing, excessive).
 >
-> Use web search to surface 3–5 representative competitors / examples in the space. Don't go deep — aim for coverage breadth.
+> Use web search to surface 3–5 representative competitors / examples. Don't go deep; aim for 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.
+> Research typical architecture for [domain] products at this project's scale: patterns, data models, integrations, and scaling considerations.
 >
-> Vision/scale signals from PROJECT.md: [extract scale-relevant phrases — solo / small team / enterprise / planned user count].
+> 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
+> Deliver `.gsd/research/ARCHITECTURE.md` with: **Recommended Architecture** (diagram-friendly data flow, services, boundaries), **Data Model Sketch**, **Integration Points**, **Scaling Tier**, **Reversibility risk**.
 >
 > Use `resolve_library` for library-specific architecture docs. Mark confidence per recommendation.
 
@@ -85,18 +72,13 @@ Prompt:
 
 Prompt:
 
-> Research common failure modes, gotchas, and footguns for [domain] products. Things experienced builders wish they'd known earlier.
+> Research common failure modes, gotchas, and footguns for [domain] products: things experienced builders wish they had 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
+> Deliver `.gsd/research/PITFALLS.md` with: **Domain Pitfalls**, **Stack Pitfalls** from the recommended/domain-norm stack, **Scope Traps**, **Compliance / Security gotchas**, and **Migration pitfalls** only if brownfield.
 >
-> Web search for postmortems, incident reports, and "lessons learned" content. Sources matter — prefer specific writeups over generic listicles.
+> Web search for postmortems, incident reports, and "lessons learned" content. Sources matter; prefer specific writeups over generic listicles.
 
 ---
 
@@ -104,17 +86,17 @@ Prompt:
 
 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.
+1. Verify `.gsd/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md` exist. If any are missing, retry that task once.
+2. Print a concise summary in chat: one sentence per dimension, what each found or why 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.
+- **Issue all 4 `Task` calls in one assistant response** (one block of four tool calls). The runtime parallelizes them; do NOT chain calls 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.
+- If any task fails twice, write `.gsd/research/{DIMENSION}-BLOCKER.md` with the failure reason and continue. If all four dimensions are blockers, runtime stops before milestone planning because no usable research exists.