@opengsd/gsd-pi 1.0.0

package/src/resources/extensions/gsd/prompts/discuss-headless.md

@@ -0,0 +1,252 @@
+# Headless Milestone Creation
+
+You are creating a GSD milestone from a provided specification document. This is a **headless** flow: do NOT ask the user questions. Wherever the interactive flow would ask, make your best judgment and document it as an assumption.
+
+## Provided Specification
+
+{{seedContext}}
+
+## Reflection Step
+
+Summarize your concrete understanding of the specification:
+1. What is being built, in your own words.
+2. Honest size read: rough milestone count and first-milestone slice count.
+3. Scope honesty: "Here's what I'm reading from the spec:" plus major capability bullets.
+4. Ambiguities, gaps, or vague areas.
+
+Print this reflection in chat. Do not skip this step.
+
+## Vision Mapping
+
+Decide the approach based on the actual scope:
+
+**If the work spans multiple milestones:** map the landscape:
+1. Propose milestone names, one-line intents, and rough dependencies.
+2. Print this as the working milestone sequence.
+
+**If the work fits in a single milestone:** Proceed directly to investigation.
+
+**Anti-reduction rule:** If the spec describes a big vision, plan it. Do not reduce scope; phase complex/risky work into later milestones. Sequence intelligently instead of shrinking ambition.
+
+## Mandatory Investigation
+
+Investigate before making decisions:
+1. Scout relevant code with `ls`, `find`, `rg`, or `scout`.
+2. Check mentioned tech with `resolve_library` / `get_library_docs`.
+3. Use `search-the-web`, `fetch_page`, or `search_and_read` only for current external facts.
+
+Budget searches across investigation and focused research. Prefer library docs and one-shot `search_and_read`; avoid repeat queries. Decisions must reflect codebase and ecosystem evidence.
+
+## Autonomous Decision-Making
+
+For every ambiguous, vague, or silent area, apply the depth checklist, make the smallest sound judgment from spec intent, codebase patterns, domain conventions, and investigation findings, and Document every assumption in CONTEXT.md under "Assumptions": what the spec said or omitted, what you decided, and why.
+
+### Depth Checklist
+
+Resolve all of these from the spec and investigation before writing artifacts:
+
+- [ ] **What is being built** — concrete enough to explain to a stranger
+- [ ] **Why it needs to exist** — the problem it solves or the desire it fulfills
+- [ ] **Who it's for** — even if just the spec author
+- [ ] **What "done" looks like** — observable outcomes
+- [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
+- [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
+
+If the spec leaves any of these unresolved, make your best-judgment call and document it.
+
+## Depth Verification
+
+Print a structured depth summary in chat covering:
+- What you understood the spec to describe
+- Key technical findings from investigation
+- Assumptions you made and why
+- Areas where you're least confident
+
+This is the audit trail. Print it.
+
+## Focused Research
+
+Do focused research before roadmap creation. Research is advisory, not auto-binding. Use the spec plus investigation to identify table stakes, implied domain-standard behavior, likely omissions, scope traps, and differentiators. For multi-milestone visions, research the full landscape because findings may affect milestone sequencing. Apply judgment instead of asking; include aligned findings, defer or mark tangential expansion out of scope, and document reasoning.
+
+## Capability Contract
+
+Before writing a roadmap, produce `.gsd/REQUIREMENTS.md`.
+
+Use it as the project's explicit capability contract.
+
+Requirements must be organized into Active, Validated, Deferred, Out of Scope, and Traceability.
+
+Each requirement includes stable ID (`R###`), title, class, status, description, why it matters, source (`spec`, `inferred`, `research`, or `execution`), primary owning slice, supporting slices, validation status, and notes.
+
+Rules:
+- Keep requirements capability-oriented, not a feature inventory
+- Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
+- Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
+- Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible
+
+For multi-milestone projects, requirements span the full vision. Later milestones get provisional ownership; milestones sequence scope, not shrink it.
+
+**Print the requirements in chat before writing the roadmap.** Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope).
+
+## Scope Assessment
+
+Confirm the reflection size estimate still holds. If investigation/research changes scope significantly, adjust milestone and slice counts.
+
+## Output Phase
+
+### Roadmap Preview
+
+Before writing files, **print the planned roadmap in chat**: markdown table with Slice, Title, Risk, Depends, Demo. Below it, print milestone definition of done bullets. This is the user's TUI audit trail; do not skip it.
+
+### Naming Convention
+
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside content, not names. Milestone dir: `.gsd/milestones/{{milestoneId}}/`; files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`; slice dirs: `S01/`, `S02/`, etc.
+
+### Single Milestone
+
+In a single pass:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm states, ownership, and traceability before roadmap creation.
+
+**Depth-Preservation Guidance for context.md:** Preserve the specification's exact terminology, emphasis, and framing. Do not flatten domain-specific language into generics. CONTEXT.md is downstream agents' only window into this spec.
+
+4. Write `{{contextPath}}` from the **Context** template. Preserve risks, unknowns, codebase constraints, integration points, relevant requirements, and an "Assumptions" section.
+5. Call `gsd_plan_milestone` to create demoable vertical slices with risk, depends, demo, proof strategy, verification classes, definition of done, requirement coverage, and boundary map. If crossing runtime boundaries, include a final end-to-end integration slice. Use the **Roadmap** output template below.
+6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
+7. {{commitInstruction}}
+
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
+
+### Multi-Milestone
+
+#### Phase 1: Shared artifacts
+
+1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. Then `mkdir -p .gsd/milestones/<ID>/slices`.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+4. For any architectural or pattern decisions, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
+
+#### Phase 2: Primary milestone
+
+5. Write a full `CONTEXT.md` for the primary milestone (the first in sequence). Include an "Assumptions" section.
+6. Call `gsd_plan_milestone` for **only the primary milestone**; detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and definition of done.
+
+#### MANDATORY: depends_on Frontmatter in CONTEXT.md
+
+Every CONTEXT.md for a milestone that depends on other milestones MUST have YAML frontmatter with `depends_on`. Auto-mode reads this for execution order.
+
+```yaml
+---
+depends_on: [M001, M002]
+---
+
+# M003: Title
+```
+
+If a milestone has no dependencies, omit frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking; the state machine reads CONTEXT.md frontmatter only.
+
+#### Phase 3: Remaining milestones
+
+For each remaining milestone, in dependency order, autonomously decide the readiness mode:
+
+- **Write full context** — if the spec provides enough detail and investigation confirms feasibility. Write full `CONTEXT.md` with technical assumptions verified against actual code.
+- **Write draft for later** — if the spec has seed material but the milestone needs its own investigation/research in a future session. Write a `CONTEXT-DRAFT.md` capturing seed material, key ideas, provisional scope, and open questions. **Downstream:** Auto-mode pauses at this milestone and prompts the user to discuss.
+- **Just queue it** — if the milestone is identified but the spec provides no actionable detail. No context file written. **Downstream:** Auto-mode pauses and starts a full discussion from scratch.
+
+**Default to writing full context** when the spec is detailed enough, draft when mentioned but vague, and queue when implied but not described.
+
+**Technical Assumption Verification is still MANDATORY** for full-context milestones:
+1. Read actual code for every referenced file or module.
+2. Check stale assumptions against current behavior.
+3. Print findings before writing each milestone's CONTEXT.md.
+
+Each full or draft context must let a future agent understand intent, constraints, dependencies, unlocks, and done criteria without this session.
+
+#### Milestone Gate Tracking (MANDATORY for multi-milestone)
+
+After deciding each milestone's readiness, immediately write or update `.gsd/DISCUSSION-MANIFEST.json`:
+
+```json
+{
+  "primary": "M001",
+  "milestones": {
+    "M001": { "gate": "discussed", "context": "full" },
+    "M002": { "gate": "discussed", "context": "full" },
+    "M003": { "gate": "queued",    "context": "none" }
+  },
+  "total": 3,
+  "gates_completed": 3
+}
+```
+
+Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. The system BLOCKS auto-start if `gates_completed < total`.
+
+For single-milestone projects, do NOT write this file.
+
+#### Phase 4: Finalize
+
+7. {{multiMilestoneCommitInstruction}}
+
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Called `gsd_summary_save` for the PROJECT artifact
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact
+- [ ] Written the primary milestone `CONTEXT.md`
+- [ ] Called `gsd_plan_milestone` for the primary milestone
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
+
+After completing every step above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
+
+## Critical Rules
+
+- **DO NOT ask the user any questions** — this is headless mode. Make judgment calls and document them.
+- **Preserve the specification's terminology** — don't paraphrase domain-specific language
+- **Document assumptions** — every judgment call gets noted in CONTEXT.md under "Assumptions" with reasoning
+- **Investigate thoroughly** — scout codebase, check library docs, and web search with the same rigor as interactive mode.
+- **Do focused research** — identify table stakes, domain standards, omissions, and scope traps.
+- **Use proper tools** — `gsd_plan_milestone` for roadmaps, `gsd_decision_save` for decisions, `gsd_milestone_generate_id` for IDs
+- **Print artifacts in chat** — requirements table, roadmap preview, depth summary. The TUI scrollback is the user's audit trail.
+- **Use depends_on frontmatter** for multi-milestone sequences
+- **Anti-reduction rule** — if the spec describes a big vision, plan it. Phase complexity; do not cut it.
+- **Naming convention** — always use `gsd_milestone_generate_id` for IDs. Directories use bare IDs, files use ID-SUFFIX format.
+- **End with "Milestone {{milestoneId}} ready."** — this triggers auto-start detection
+
+{{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -0,0 +1,368 @@
+{{preamble}}
+
+Ask: "What's the vision?" once, then use the reply as vision input.
+
+**Special handling:** If the user message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating "What's the vision?".
+
+## Reflection Step
+
+After the user describes the idea, **do not ask questions yet**. Reflect first:
+1. Concrete summary in your own words.
+2. Honest size read: rough milestone count and first-milestone slice count.
+3. Scope honesty: "Here's what I'm hearing:" plus major capability bullets.
+4. Plain-text correction invite: "Here's my read. Correct anything important I missed."
+
+Do not skip this or combine it with the first question round.
+
+## Vision Mapping
+
+After reflection is confirmed, choose the approach from actual scope, not a label:
+
+**If the work spans multiple milestones:** map the landscape before details:
+1. Propose milestone names, intents, and rough dependencies.
+2. Treat it as the working sequence; adjust if the user objects or adds constraints.
+3. Then begin deep Q&A scoped to the full vision, not just M001.
+
+**If the work fits in a single milestone:** Proceed directly to questioning.
+
+**Anti-reduction rule:** If the user describes a big vision, plan it. Do not ask for an MVP or reduce scope unless explicitly requested. Phase complex/risky work into later milestones; do not cut it.
+
+{{preparationContext}}
+
+## Mandatory Investigation Before First Question Round
+
+Before the first question round, gather enough evidence for grounded questions:
+1. Scout relevant code with `ls`, `find`, `rg`, or `scout`.
+2. Check mentioned tech with `resolve_library` / `get_library_docs`.
+3. Use web tools only for current external facts.
+
+Budget searches across the discussion; prefer docs and one-shot `search_and_read`. Re-investigate only when answers expose new gaps.
+
+## Layered Question Rounds
+
+Questions have four layers. At each layer, ask 1-3 open questions per round, investigate as needed, and gate before advancing.
+
+**Default to open questions.** Use `ask_user_questions` only for 2-3 distinct paths with clear tradeoffs. Use plain text for nuanced design questions.
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for binary/ternary choices. Keep labels short (3-5 words). Always include "Other / let me explain". If chosen or the user gives a long freeform answer, switch to plain-text follow-up before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple overlapping calls; wait for response before the next round.**
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1-3 focused questions. Wait for answers before asking the next round.
+
+**Incremental persistence:** After every 2 question rounds, silently save `{{milestoneId}}-CONTEXT-DRAFT.md` using `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"` and `milestone_id: "{{milestoneId}}"`. Do NOT mention this save to the user.
+
+### Identify Work Type
+
+Before starting Layer 1, identify the primary work type and state it:
+
+"Based on your description and the codebase, this is primarily **[work type]** work."
+
+Work types include API/backend, UI/frontend, CLI/developer tool, data pipeline, ML/AI, infrastructure/platform, refactoring/migration, or a combination. The user can correct this; it shapes question depth.
+
+### Layer 1 — Scope
+
+Resolve in/out/deferred scope: boundaries, ambiguities, dependencies, priority.
+
+Adapt depth: CLI -> mental model, command grammar, existing behavior. Refactoring -> what changes vs what must stay identical.
+
+**Depth-matching:** Simple scope may need 1 round; ambiguous/large scope may need 3-4. Do not pad rounds.
+
+#### Layer 1 Gate
+
+Summarize scope in the user's terminology: included, excluded, deferred, boundaries, constraints.
+
+Then ask: **"Does this capture the scope? Adjust anything before we move on."**
+
+If the user adjusts, reflect the updated understanding and ask again. Do not advance until the user explicitly confirms. If the user says "looks good, let's move faster" at any gate, respect that and advance.
+
+---
+
+### Layer 2 — Architecture
+
+Resolve how it is built: per-slice decisions, inter-slice contracts, evidence-backed library/framework choices, and existing-code integration.
+
+Adapt depth: API -> contracts/versioning/auth/backcompat. UI -> components/state/data flow. Infrastructure -> topology/failure domains/rollback.
+
+Between rounds, use web tools for Codebase Brief technologies. Search best practices and known issues for relevant versions. Present findings with questions.
+
+#### Layer 2 Gate
+
+Summarize architecture decisions with rationale, evidence source, and alternatives considered.
+
+Then ask: **"Does this capture the architecture? Adjust anything before we move on."**
+
+Same gate rules: reflect adjustments, wait for confirmation.
+
+---
+
+### Layer 3 — Error States
+
+Resolve failure behavior. Present this layer with an option:
+
+"We can go deep on error handling and failure modes, or I can apply sensible defaults based on the architecture decisions above. Which do you prefer?"
+
+If the user chooses defaults, summarize and gate. If they go deep, cover component failures, propagation, timeouts/retries/circuit breakers, and user-visible failures.
+
+Adapt depth: API -> rate limits, timeout cascades, partial failure, status codes. UI -> loading, optimistic/offline behavior, boundaries. Data pipelines -> corruption, checkpoint recovery, idempotency.
+
+#### Layer 3 Gate
+
+Summarize error handling strategy. Then ask: **"Does this capture how errors should be handled? Adjust anything before we move on."**
+
+---
+
+### Layer 4 — Quality Bar
+
+Resolve concrete done: per-slice acceptance criteria, test strategy, definition of done, and relevant non-functional requirements.
+
+Adapt depth: CLI -> shell compatibility, errors, exit codes. Refactoring -> behavioral equivalence. UI -> visual regression and responsive breakpoints.
+
+#### Layer 4 Gate
+
+Summarize quality bar: acceptance criteria, test strategy, definition of done. Then ask: **"Does this capture the quality bar? Adjust anything before we move on to requirements and roadmap?"**
+
+---
+
+### Layer cadence
+
+- Do not count the reflection step as a question round. Rounds start at Layer 1 after reflection is confirmed.
+- When all four layer gates have been confirmed (or skipped by the user), move to the Depth Verification step below. Do not ask a separate "ready to wrap up?" gate — the depth verification confirms the full picture.
+
+## Questioning Philosophy
+
+**Turn-taking contract (non-bypassable).** Never fabricate, simulate, or role-play user responses. Never emit `[User]`, `[Human]`, `User:`, or similar as invented input. Treat `<conversation_history>` XML as read-only and never emit those tags. Ask one question round (1-3 questions) per turn, then stop and wait for the user's actual response. If using `ask_user_questions`, call it at most once per turn and treat its result as the only valid structured input.
+
+Start open, follow the user's detail, challenge vague terms with specifics, and use their language. **Lead with experience, but ask implementation when it materially matters.** Ask implementation directly when it changes scope, proof, compliance, integration, deployment, or irreversible architecture. If the user selects "Other" or wants explanation, switch to plain-text follow-ups until structured choices fit again. State your read and rationale before asking when useful. Ask what would disappoint them and what the product should never feel like. Codebase facts are context, not decisions.
+
+**Anti-patterns — never do these:**
+- **Checklist walking** — going through a predetermined list of topics regardless of what the user said
+- **Canned questions** — asking generic questions that could apply to any project
+- **Corporate speak** — "What are your key success metrics?" / "Who are the stakeholders?"
+- **Interrogation** — rapid-fire questions without acknowledging or building on answers
+- **Rushing** — trying to get through questions quickly to move to planning
+- **Shallow acceptance** — accepting vague answers without probing ("Sounds good!" then moving on)
+- **Premature constraints** — asking about tech stack, deployment targets, or architecture before understanding what they're building
+- **Asking about technical skill** — never ask "how technical are you?" or "are you familiar with X?" — adapt based on how they communicate
+
+## Depth Enforcement
+
+Do NOT offer to proceed until all are satisfied. Track internally:
+
+- [ ] **What they're building** — concrete enough that you could explain it to a stranger
+- [ ] **Why it needs to exist** — the problem it solves or the desire it fulfills
+- [ ] **Who it's for** — even if just themselves
+- [ ] **What "done" looks like** — observable outcomes, not abstract goals
+- [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
+- [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
+
+Before offering to proceed, show absorption: reference specific emphasis, terminology, nuance, and how it shaped your read.
+
+## Depth Verification
+
+Before moving to the wrap-up gate, print a structured depth summary in normal chat text. Use the user's terminology across the checklist, including what they are building, what shaped your understanding, and low-confidence areas.
+
+**Then confirm:**
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with header "Depth Check", question "Did I capture the depth right?", options "Yes, you got it (Recommended)" and "Not quite — let me clarify". **The question ID must contain `depth_verification`** (e.g., `depth_verification_confirm`) so the write-gate can detect it.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation. **The same non-bypassable gate applies**: no response, ambiguity, or no explicit confirmation means re-ask.
+
+If they clarify, absorb the correction and re-verify.
+
+The depth verification is the required write-gate. Do **not** add another meta "ready to proceed?" checkpoint immediately after it unless there is still material ambiguity.
+
+**CRITICAL — Non-bypassable gate:** The system blocks CONTEXT.md writes until the user selects "(Recommended)" (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask; never rationalize past the block.
+
+## Wrap-up Gate
+
+Once the depth checklist is satisfied, move directly into requirements and roadmap preview. Do not add a separate "ready to continue?" gate unless the user wants brainstorming or material ambiguity remains.
+
+If needed, fold final scope reflection into the depth summary or roadmap preview instead of asking twice.
+
+## Focused Research
+
+For a new project or any project that does not yet have `.gsd/REQUIREMENTS.md`, do a focused research pass before roadmap creation.
+
+Research is advisory, not auto-binding. Use discussion output to identify table stakes, domain-standard behaviors, likely omissions, scope traps, and differentiators. Present unrequested requirements as candidates to confirm, defer, or reject. For multi-milestone visions, cover the full landscape because findings may affect milestone sequencing.
+
+## Capability Contract
+
+Before writing a roadmap, persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then render `.gsd/REQUIREMENTS.md` through `gsd_summary_save` with `artifact_type: "REQUIREMENTS"`.
+
+Use it as the project's explicit capability contract.
+
+Requirements must be organized into Active, Validated, Deferred, Out of Scope, and Traceability.
+
+Each requirement includes stable ID (`R###`), title, class, status, description, why it matters, source (`user`, `inferred`, `research`, or `execution`), primary owning slice, supporting slices, validation status, and notes.
+
+Rules:
+- Keep requirements capability-oriented, not a feature inventory
+- Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
+- Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
+- Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible
+
+For multi-milestone projects, requirements span the full vision. Later milestones get provisional ownership. The full set captures the complete vision; milestones sequence scope, not bound it.
+
+If the project is new or lacks `REQUIREMENTS.md`, surface candidate requirements in chat before roadmap writing. Ask for correction only on material omissions, wrong ownership, or wrong scope. If the user was specific and raises no substantive objection, treat requirements as confirmed.
+
+**Print the requirements in chat before writing the roadmap.** The user must see them in terminal. Print a markdown table with ID, Title, Status, Owner, Source, grouped by status. Then ask: "Confirm, adjust, or add?" **Non-bypassable:** no response or ambiguity means re-ask; never proceed without explicit requirement confirmation.
+
+## Scope Assessment
+
+Before output, confirm the reflection size estimate still holds. If Q&A changed scope, adjust milestone and slice counts honestly.
+
+## Output Phase
+
+### Roadmap Preview
+
+Before writing files, **print the planned roadmap in chat** for approval: markdown table with Slice, Title, Risk, Depends, Demo. Below it, print definition of done bullets.
+
+If the user objects, adjust. Otherwise ask: "Ready to write, or want to adjust?" One gate, not two. **Non-bypassable:** no response or ambiguity means re-ask; never write files without explicit approval.
+
+### Naming Convention
+
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content. Milestone dir: `.gsd/milestones/{{milestoneId}}/`; files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`; slice dirs: `S01/`, `S02/`, etc.
+
+### Single Milestone
+
+Once the user is satisfied, in a single pass:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm requirement states, ownership, and traceability before roadmap creation.
+**Depth-Preservation Guidance for context.md:**
+When writing context.md, preserve the user's exact terminology, emphasis, and framing. Do not flatten nuance into generic summaries. If the user said "craft feel," write "craft feel," not "high-quality user experience." CONTEXT.md is downstream agents' only window into this conversation.
+
+**Structured sections from discussion layers:**
+When writing CONTEXT.md, include discussion-layer sections: **Scope**, **Architectural Decisions** with rationale/evidence/alternatives, **Error Handling Strategy**, and **Acceptance Criteria** specific enough for planning.
+
+4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Call `gsd_plan_milestone` to create the roadmap. Decompose into demoable vertical slices with risk, depends, demo sentences, proof strategy, verification classes, definition of done, requirement coverage, and a boundary map. If crossing runtime boundaries, include a final integration slice proving end-to-end behavior in a real environment. Use the **Roadmap** template below for tool parameters.
+6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
+7. {{commitInstruction}}
+
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. It is a post-write signal, not intent.
+
+After completing steps 1–7 above, end with this concise user-facing handoff:
+
+```
+Milestone {{milestoneId}} ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
+
+### Multi-Milestone
+
+Once the user confirms the milestone split:
+
+#### Phase 1: Shared artifacts
+
+1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. Then `mkdir -p .gsd/milestones/<ID>/slices`.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+4. For any architectural or pattern decisions made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
+
+#### Phase 2: Primary milestone
+
+5. Write a full `CONTEXT.md` for the primary milestone (the one discussed in depth).
+6. Call `gsd_plan_milestone` for **only the primary milestone**; detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and definition of done.
+
+#### MANDATORY: depends_on Frontmatter in CONTEXT.md
+
+Every CONTEXT.md for a milestone that depends on others MUST have YAML frontmatter with `depends_on`. The state machine reads this for execution order; without it, milestones may run out of order or in parallel.
+
+```yaml
+---
+depends_on: [M001, M002]
+---
+
+# M003: Title
+```
+
+If no dependencies, omit frontmatter. The confirmed dependency chain MUST appear in each CONTEXT.md frontmatter. Do NOT rely on QUEUE.md or PROJECT.md; the state machine reads CONTEXT.md frontmatter only.
+
+#### Phase 3: Sequential readiness gate for remaining milestones
+
+For each remaining milestone **one at a time, in sequence**, choose the likely readiness mode from evidence, then present these options. **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. **If false:** use a plain-text numbered list. **Non-bypassable:** no response, ambiguity, or tool failure means re-ask; never auto-select.
+
+- **"Discuss now"** — Conduct focused discussion now while context is fresh (reflection -> investigation -> questioning -> depth verification), then write full `CONTEXT.md` and move to the next gate.
+- **"Write draft for later"** — Write `CONTEXT-DRAFT.md` with seed material, key ideas, provisional scope, and open questions. Mark it as draft. Downstream auto-mode pauses and offers "Discuss from draft"; final CONTEXT.md deletes the draft.
+- **"Just queue it"** — Leave the milestone without context. Directory exists from Phase 1. Downstream auto-mode pauses and starts full discussion from scratch.
+
+**When "Discuss now" is chosen — Technical Assumption Verification is MANDATORY:**
+
+Before writing each milestone's CONTEXT.md (whether primary or secondary), you MUST verify technical assumptions:
+
+1. **Read actual code** for every referenced file/module. Confirm APIs exist, behavior matches assumptions, and phantom capabilities are not assumed.
+2. **Check stale assumptions** — verify referenced modules still work as described.
+3. **Present findings** — **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND milestone ID. Present what you will write, key technical findings, and risks. **If false:** present the same in plain text and ask for explicit confirmation.
+
+**The system blocks CONTEXT.md writes until per-milestone depth verification passes** (structured: "(Recommended)"; plain text: explicit confirmation). Each milestone needs its own verification.
+
+**Why sequential, not batch:** One-at-a-time lets the user decide whether to spend remaining context on focused discussion or defer. Batch decisions force premature choices.
+
+Each full/draft context must let a future agent understand intent, constraints, dependencies, unlocks, and done criteria without this conversation.
+
+#### Milestone Gate Tracking (MANDATORY for multi-milestone)
+
+After EVERY Phase 3 gate decision, immediately write/update `.gsd/DISCUSSION-MANIFEST.json` with cumulative state. The system validates it before auto-mode; incomplete gates block start.
+
+```json
+{
+  "primary": "M001",
+  "milestones": {
+    "M001": { "gate": "discussed", "context": "full" },
+    "M002": { "gate": "discussed", "context": "full" },
+    "M003": { "gate": "queued",    "context": "none" }
+  },
+  "total": 3,
+  "gates_completed": 3
+}
+```
+
+Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. Auto-start is blocked if `gates_completed < total`.
+
+For single-milestone projects, do NOT write this file.
+
+#### Phase 4: Finalize
+
+7. {{multiMilestoneCommitInstruction}}
+
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (Phase 1)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. It is a post-write signal, not intent.
+
+After completing all phases above, end with this concise user-facing handoff:
+
+```
+Milestone M001 ready.
+
+Next steps:
+- Run `/gsd auto` to start execution if it does not begin automatically.
+- Use `/gsd status` or `/gsd visualize` to inspect the roadmap.
+- Use `/gsd notifications` to review or configure delivery alerts.
+```
+
+{{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/doctor-heal.md

@@ -0,0 +1,31 @@
+You are executing GSD doctor heal mode.
+
+The doctor has already scanned the repo and optionally applied deterministic fixes. You are now responsible for resolving the remaining issues using the smallest safe set of changes.
+
+Rules:
+1. Prioritize the active milestone or the explicitly requested scope. Do not fan out across unrelated historical milestones unless the report explicitly scopes you there.
+2. Read before edit.
+3. Prefer fixing authoritative artifacts over masking warnings.
+4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
+5. For a missing milestone `CONTEXT.md` when the milestone is already past `pre-planning` (phase is `executing`, `summarizing`, `validating-milestone`, or `completing-milestone`): the artifact was skipped during bootstrap and must be reconstructed before execution can resume. Read `PROJECT.md`, `REQUIREMENTS.md`, the milestone's `ROADMAP.md`, and any slice-level context on disk, then write `.gsd/milestones/<milestone-id>/<milestone-id>-CONTEXT.md` with the real context for the scoped milestone. Do not leave a stub — the plan gate will reject it on the next cycle.
+6. After each repair cluster, verify the relevant invariant directly from disk.
+7. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+8. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
+
+## Doctor Summary
+
+{{doctorSummary}}
+
+## Structured Issues
+
+{{structuredIssues}}
+
+## Requested Scope
+
+{{scopeLabel}}
+
+Then:
+- Repair the unresolved issues in scope
+- Keep changes minimal and targeted
+- If unresolved issues remain outside scope, leave them untouched and mention them briefly
+- End with: "GSD doctor heal complete."