gsd-pi 2.78.1-dev.8a893322c → 2.78.1-dev.8e0e96cfc

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

@@ -0,0 +1,133 @@
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. For `.gsd` files in this prompt, use absolute paths rooted at `{{workingDirectory}}` instead of discovering them with `Glob`.
+
+Discuss the **project** as a whole. Identify gray areas at the project level — vision, users, anti-goals, key constraints — ask the user about them, and write `.gsd/PROJECT.md` with the decisions. Use the **Project** output template below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+
+This stage runs ONCE per project, before any milestone-level discussion. It produces the project-level context that all subsequent milestones, requirements, and roadmaps will reference.
+
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
+{{inlinedTemplates}}
+
+---
+
+## Stage Banner
+
+Before your first action, print this banner verbatim in chat:
+
+• QUESTIONING (project)
+
+---
+
+## Interview Protocol
+
+### Open the conversation
+
+Ask the user a single freeform question in plain text, not structured: **"What do you want to build?"**
+
+Wait for their response. This grounds every follow-up in their own terminology.
+
+### Before deeper rounds
+
+Do a lightweight targeted investigation so your questions are grounded in reality:
+- Scout the codebase (`rg`, `find`, or `scout`) — is this greenfield or brownfield? What language/framework signals exist?
+- Identify any prior `.planning/` or `.gsd/` artifacts hinting at history
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries the user mentions
+
+**Web search budget:** typically 3–5 per turn. Prefer `resolve_library` / `get_library_docs` for library docs. Target 2–3 web searches in the investigation pass; distribute remaining searches across follow-up rounds.
+
+Do **not** go deep — just enough that your follow-ups reflect what's actually true rather than what you assume.
+
+### Question rounds
+
+Ask **1–3 questions per round**. Each round targets one of:
+- **What they're building** — concrete enough to describe to a stranger
+- **Who it's for** — primary users, secondary users, internal vs external
+- **The core value** — the ONE thing that must work even if everything else is cut
+- **Anti-goals** — what they explicitly don't want, what would disappoint them
+- **Constraints** — budget, timeline, tech limitations, irreversible architectural choices
+- **Existing context** — prior work, brownfield state, decisions already made
+- **Milestone shape** — rough version sequence (v1 / v1.1 / ...) and what differentiates them
+
+**Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
+
+**Plain-text default:** Project discovery is open-ended. Ask question rounds in plain text unless you are presenting 2–3 concrete alternatives with clear tradeoffs.
+
+**If `{{structuredQuestionsAvailable}}` is `true` and you use `ask_user_questions`:** ask 1–3 questions per call. Every question object MUST include a stable lowercase `id`. Keep option labels short (3–5 words). Do not add a separate "Other" option; the question UI provides a freeform path automatically. Wait for each tool result before asking the next round.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions.
+
+After each round, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Round cadence
+
+After each round, decide whether you have enough depth to write a strong PROJECT.md.
+
+- **Incremental persistence:** After every 2 question rounds, silently save `.gsd/PROJECT-DRAFT.md` using `gsd_summary_save` with `artifact_type: "PROJECT-DRAFT"` and no `milestone_id`. Crash protection. Do NOT mention this save to the user.
+- If not ready, continue to the next round.
+- Use a wrap-up prompt only when you believe the depth checklist below is satisfied or the user signals they want to stop.
+
+---
+
+## Questioning philosophy
+
+**Start open, follow energy.** Let the user's enthusiasm guide where you dig deeper.
+
+**Challenge vagueness.** When the user says "it should be smart" or "good UX", push for specifics.
+
+**Position-first framing.** Have opinions. "I'd lean toward X because Y — does that match your thinking?" is better than "what do you think about X vs Y?"
+
+**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. Negative constraints are sharper than positive wishes.
+
+**Anti-patterns — never do these:**
+- Checklist walking through predetermined topics regardless of what the user said
+- Canned generic questions ("What are your key success metrics?")
+- Rapid-fire questions without acknowledging answers
+- Asking about technical skill level
+- Asking about specific milestone implementations — that's the next stage
+
+---
+
+## Depth Verification
+
+Before moving to the wrap-up gate, verify you have covered:
+
+- [ ] What they're building — concrete enough to describe to a stranger
+- [ ] Who it's for
+- [ ] Core value (the ONE thing that must work)
+- [ ] Anti-goals / explicit non-wants
+- [ ] Constraints (budget, time, tech, architecture)
+- [ ] Greenfield vs brownfield state
+- [ ] Rough milestone sequence (at least M001's intent)
+
+**Print a structured depth summary in chat first** — using the user's own terminology. Cover what you understood, what shaped your understanding, and any areas of remaining uncertainty.
+
+**Then confirm:**
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with:
+- header: "Depth Check"
+- id: "depth_verification_project_confirm"
+- question: "Did I capture the depth right?"
+- options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
+- **The question ID must contain `depth_verification_project`** — this enables the write-gate downstream.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask.
+
+If they clarify, absorb the correction and re-verify.
+
+The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it.
+
+**CRITICAL — Confirmation gate:** Do not write final PROJECT.md until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block.
+
+---
+
+## Output
+
+Once the user confirms depth:
+
+1. Use the **Project** output template (inlined above).
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing.
+3. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
+4. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
+5. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.
+6. {{commitInstruction}}
+7. Say exactly: `"Project context written."` — nothing else.

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

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

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.

package/dist/resources/extensions/gsd/prompts/guided-workflow-preferences.md

@@ -0,0 +1,68 @@
+**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`.
+
+Configure project workflow preferences. This stage runs ONCE per project, early in deep-mode bootstrap, before `discuss-project`. It applies a small set of recommended workflow defaults and persists them to the YAML frontmatter of `.gsd/PREFERENCES.md` (the same file the runtime reads its preferences from).
+
+This is a **default-writing** stage — do NOT ask the user questions. Write the recommended defaults, then end. No follow-ups, no research, no opinion.
+
+---
+
+## Stage Banner
+
+Print this banner verbatim in chat as your first action:
+
+• WORKFLOW PREFERENCES
+
+Then say: "Quick setup — applying recommended workflow defaults."
+
+---
+
+## Default Set
+
+Use these recommended defaults without asking:
+
+- `commit_policy: per-task` — atomic commit after every task; finest granularity, easiest to revert
+- `branch_model: single` — all work on current branch
+- `uat_dispatch: true` — verification runs automatically; failures pause execution
+- `models.executor_class: balanced` — sensible cost/quality default
+- `research: skip` — deterministic default; the dedicated research-decision stage can later switch to `research`
+
+---
+
+## Output
+
+Apply the defaults:
+
+1. Read `{{workingDirectory}}/.gsd/PREFERENCES.md` if it exists. The file is YAML frontmatter (between `---` lines) followed by an optional markdown body. Parse the existing frontmatter so you can preserve unrelated keys (e.g. `planning_depth`).
+2. Merge the defaults into the frontmatter under these keys, preserving any existing explicit value:
+   - top-level `commit_policy: per-task`
+   - top-level `branch_model: single`
+   - top-level `uat_dispatch: true`
+   - top-level `research: skip`
+   - nested `models.executor_class: balanced`
+3. Also set top-level `workflow_prefs_captured: true` — this is the single explicit marker the dispatch layer uses to know the wizard has run.
+4. Write `{{workingDirectory}}/.gsd/PREFERENCES.md` back with the merged frontmatter and the original body preserved unchanged. Frontmatter delimiters are exactly `---` on their own lines.
+5. Pre-seed the research decision so the standalone `research-decision` stage is a no-op if the user already answered here:
+   - Ensure `{{workingDirectory}}/.gsd/runtime/` exists.
+   - Write `{{workingDirectory}}/.gsd/runtime/research-decision.json`:
+     ```json
+     {
+       "decision": "skip",
+       "decided_at": "<ISO 8601 timestamp>",
+       "source": "workflow-preferences",
+       "reason": "deterministic-default"
+     }
+     ```
+   Use `"skip"` unless an existing valid `{{workingDirectory}}/.gsd/runtime/research-decision.json` explicitly says `"research"` with `"source": "research-decision"` or `"source": "user"`.
+6. Print a concise summary in chat: each key on its own line, format `key: value`. Include `commit_policy`, `branch_model`, `uat_dispatch`, `models.executor_class`, and `research` (matching the preserved or pre-seeded runtime research decision).
+7. Say exactly: `"Workflow preferences saved."` — nothing else.
+
+Do NOT write to `.gsd/config.json`; runtime preferences load from `PREFERENCES.md`.
+
+---
+
+## Critical rules
+
+- Do NOT ask any questions. Defaults only, write file, done.
+- Do NOT call `ask_user_questions`, `AskUserQuestion`, or any other interactive user-input tool in this stage.
+- Do NOT change any keys other than the frontmatter keys specified plus `workflow_prefs_captured`. Research is persisted to `.gsd/runtime/research-decision.json`, NOT to `phases.skip_research`.
+- Preserve existing explicit values for `commit_policy`, `branch_model`, `uat_dispatch`, and `models.executor_class`; only fill missing values with defaults.

package/dist/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -1,5 +1,7 @@
 # Parallel Slice Research
 
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
 You are dispatching parallel research agents for **{{sliceCount}} slices** in milestone **{{mid}} — {{midTitle}}**.
 
 ## Slices to Research

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

@@ -10,6 +10,12 @@ All relevant context has been preloaded below — start working immediately with
 
 {{inlinedContext}}
 
+## Already Planned? Soft Brake
+
+If `{{outputPath}}` already exists on disk with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call `gsd_plan_milestone` — its UPSERT would overwrite the existing plan with whatever you reconstruct, which is unsafe when you don't have the original decomposition reasoning. Skip directly to the ready phrase at the end of this prompt.
+
+If only the file exists (no DB rows) or only DB rows exist (no file), the prior write was incomplete — proceed with planning as normal so the tool reconciles both.
+
 ## Your Role in the Pipeline
 
 You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.
@@ -23,7 +29,7 @@ Before decomposing, build your understanding:
 1. **Codebase exploration.** For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 2. **Library docs.** Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase.
 3. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
-4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors.
+4. **Requirements analysis.** If `.gsd/REQUIREMENTS.md` exists, research against it and treat Active requirements as the capability contract for this milestone. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage in the roadmap.
 
 ### Strategic Questions to Answer
 
@@ -47,7 +53,7 @@ Then:
 2. {{skillActivation}}
 3. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
 4. Order by risk (high-risk first)
-5. Call `gsd_plan_milestone` to persist the milestone planning fields, slice rows, and **horizontal checklist** in the DB-backed planning path. Do **not** write `{{outputPath}}`, `ROADMAP.md`, or other planning artifacts manually — the planning tool owns roadmap rendering and persistence.
+5. Call `gsd_plan_milestone` to persist the milestone planning fields, slice rows, and **horizontal checklist** in the DB-backed planning path. Fill the Horizontal Checklist with cross-cutting concerns considered during planning (requirements re-read, decisions re-evaluated, graceful shutdown, revenue paths, auth boundary, shared resources, reconnection). Omit it for trivial milestones where none apply. Do **not** write `{{outputPath}}`, `ROADMAP.md`, or other planning artifacts manually — the planning tool owns roadmap rendering and persistence.
 6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), call `gsd_decision_save` for each decision — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 ## Requirement Mapping Rules

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

@@ -26,7 +26,7 @@ This unit runs under the `planning-dispatch` tools-policy: you may use the `suba
 
 - You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
 - The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
-- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **scout** agent.
 
 **Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
 
@@ -66,7 +66,7 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 {{executorContextConstraints}}
 
 Then:
-0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
+0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. Owned requirements are acceptance criteria for this slice — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met. Supporting requirements are compatibility constraints only; do not pull a later slice's primary work into this slice unless the roadmap explicitly assigns that work here.
 0a. Call `memory_query` with keywords from the slice title and the source files listed below. Prior architectural decisions, conventions, and gotchas in this area should inform task decomposition — not be re-derived during execution.
 1. Read the templates:
    - `~/.gsd/agent/extensions/gsd/templates/plan.md`
@@ -80,7 +80,7 @@ Then:
    - Planned test files must only read from or import paths that are tracked in git. Do NOT plan tests whose inputs or fixtures are paths listed in `.gitignore` (e.g. `.gsd/`, `.planning/`, `.audits/`). If the scenario seems to require such a file, plan an inline fixture or a tracked sample instead.
 4. **For non-trivial slices only** — plan observability, proof level, and integration closure:
    - Include `Observability / Diagnostics` for backend, integration, async, stateful, or UI slices where failure diagnosis matters.
-   - Fill `Proof Level` and `Integration Closure` when the slice crosses runtime boundaries or has meaningful integration concerns.
+   - Fill `Proof Level` and `Integration Closure` truthfully when the slice crosses runtime boundaries or has meaningful integration concerns — say what class of proof this slice really delivers and what end-to-end wiring still remains. Do not phrase fixture/contract-only proof as if it were live integration proof.
    - **Omit these sections entirely for simple slices** where they would all be "none" or trivially obvious.
 5. **Quality gates** — for non-trivial slices, fill the Threat Surface (Q3) and Requirement Impact (Q4) sections in the slice plan:
    - **Threat Surface:** Identify abuse scenarios, data exposure risks, and input trust boundaries. Required when the slice handles user input, authentication, authorization, or sensitive data. Omit entirely for internal refactoring or simple changes.
@@ -92,16 +92,18 @@ Then:
    - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
    - **Inputs and Expected Output must list concrete backtick-wrapped file paths** (e.g. `` `src/types.ts` ``). These are machine-parsed to derive task dependencies — vague prose without paths breaks parallel execution. Every task must have at least one output file path.
    - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
-7. **Persist planning state through `gsd_plan_slice`.** Call it with the full slice planning payload (goal, demo, must-haves, verification, tasks, and metadata). The tool inserts all tasks in the same transaction, writes to the DB, and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** call `gsd_plan_task` separately — `gsd_plan_slice` handles task persistence. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tool is the canonical write path for slice and task planning state.
+7. **Persist planning state through `gsd_plan_slice`.** Call it with the full slice planning payload: `goal`, `successCriteria`, optional `proofLevel`, optional `integrationClosure`, optional `observabilityImpact`, and `tasks`. Keep each task description's first paragraph concise; detailed steps and must-haves may follow, but the parent slice plan should read as a summary. The tool inserts all tasks in the same transaction, writes to the DB, and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` files automatically. Do **not** call `gsd_plan_task` separately — `gsd_plan_slice` handles task persistence. Do **not** rely on direct `PLAN.md` writes as the source of truth; the DB-backed tool is the canonical write path for slice and task planning state.
 8. **Self-audit the plan.** Walk through each check — if any fail, fix the plan files before moving on:
     - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true.
-    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task.
+    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task with verification that proves the requirement is met.
+    - **Decisions honored:** The plan respects locked decisions from any inlined context, research, or `.gsd/DECISIONS.md` artifacts. Do not silently re-litigate prior decisions.
     - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague. Inputs and Expected Output list backtick-wrapped file paths, not prose descriptions.
     - **Dependency correctness:** Task ordering is consistent. No task references work from a later task.
     - **Key links planned:** For every pair of artifacts that must connect, there is an explicit step that wires them.
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
-    - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding.
-    - **Quality gate coverage:** For non-trivial slices, Threat Surface and Requirement Impact sections are present and specific (not placeholder text). For non-trivial tasks, Failure Modes, Load Profile, and Negative Tests are addressed in the task plan.
+    - **Proof-level truthfulness:** The proof-level wording does not overclaim live integration if only fixture/contract proof is planned.
+    - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding. If the slice has a UI surface, at least one task builds the real UI; if it has an API, at least one task connects it to a real data source. Showing the completed result to a non-technical stakeholder should demonstrate real product progress rather than developer artifacts.
+    - **Quality gate coverage:** For non-trivial slices, Threat Surface (Q3: abuse, data exposure, input trust) and Requirement Impact (Q4: requirements touched, re-verify, decisions revisited) sections are present and specific (not placeholder text). For non-trivial tasks, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) are addressed in the task plan.
 10. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
 11. {{commitInstruction}}
 

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -26,7 +26,7 @@ This unit runs under the `planning-dispatch` tools-policy: you may use the `suba
 
 - You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
 - A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
-- You need current external information (library docs, API behavior) → dispatch the **researcher** agent.
+- You need current external information (library docs, API behavior) → dispatch the **scout** agent.
 
 **Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
 

package/dist/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -1,5 +1,7 @@
 You are executing GSD auto-mode.
 
+**Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
 ## UNIT: Rewrite Documents — Apply Override(s) for Milestone {{milestoneId}} ("{{milestoneTitle}}")
 
 An override was issued by the user that changes a fundamental decision or approach. Your job is to propagate this change across all active planning documents so they are internally consistent and future tasks execute correctly.