gsd-pi 2.65.0 → 2.66.0

package/dist/resources/extensions/gsd/prompt-validation.js

@@ -0,0 +1,67 @@
+/**
+ * GSD Prompt Validation — Validates enhanced context output before writing.
+ *
+ * Implements R109 validation requirement: CONTEXT.md must have required sections
+ * before being written to disk.
+ */
+/**
+ * Validate that enhanced context content has all required sections.
+ *
+ * Required sections per R109:
+ * - Scope section (## Scope, ## Milestone Scope, or ## Why This Milestone)
+ * - Architectural Decisions section (## Architectural Decisions)
+ * - Acceptance Criteria section (## Acceptance Criteria or ## Final Integrated Acceptance)
+ *
+ * Additionally validates that the Architectural Decisions section contains
+ * at least one decision entry (### heading or **Decision marker).
+ *
+ * @param content - The enhanced context markdown content
+ * @returns ValidationResult with valid flag and list of missing sections
+ */
+export function validateEnhancedContext(content) {
+    const missing = [];
+    // Required section 1: Scope (multiple acceptable header variants)
+    const hasScopeSection = /^## Scope\b/m.test(content) ||
+        /^## Milestone Scope\b/m.test(content) ||
+        /^## Why This Milestone\b/m.test(content);
+    if (!hasScopeSection) {
+        missing.push("Milestone Scope or Why This Milestone");
+    }
+    // Required section 2: Architectural Decisions
+    const hasArchitecturalDecisions = /^## Architectural Decisions\b/m.test(content);
+    if (!hasArchitecturalDecisions) {
+        missing.push("Architectural Decisions");
+    }
+    // Required section 3: Acceptance Criteria (multiple acceptable header variants)
+    const hasAcceptanceCriteria = /^## Acceptance Criteria\b/m.test(content) ||
+        /^## Final Integrated Acceptance\b/m.test(content);
+    if (!hasAcceptanceCriteria) {
+        missing.push("Acceptance Criteria");
+    }
+    // Additional validation: Architectural Decisions must have at least one entry
+    if (hasArchitecturalDecisions) {
+        // Extract the section content between ## Architectural Decisions and the next ## heading.
+        // Uses indexOf-based extraction instead of regex with \z (which is invalid in JavaScript
+        // regex — it's PCRE/Ruby syntax and JS treats it as literal 'z').
+        const sectionStart = content.indexOf("## Architectural Decisions");
+        if (sectionStart === -1) {
+            missing.push("Architectural Decisions");
+        }
+        else {
+            const afterHeading = content.slice(sectionStart + "## Architectural Decisions".length);
+            const nextSection = afterHeading.search(/^## /m);
+            const sectionContent = nextSection === -1 ? afterHeading : afterHeading.slice(0, nextSection);
+            // Check for actual decision entries:
+            // - ### heading (subsection per decision)
+            // - **Decision marker (inline decision format)
+            const hasDecisionEntry = /^### /m.test(sectionContent) || /^\*\*Decision/m.test(sectionContent);
+            if (!hasDecisionEntry) {
+                missing.push("At least one architectural decision entry");
+            }
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}

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

@@ -28,7 +28,7 @@ Then:
 
 ### Verification Gate — STOP if verification failed
 
-**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 9.**
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 10.**
 
 **Failure path** (verification failed):
 - Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
@@ -39,7 +39,8 @@ Then:
 
 **Success path** (all verifications passed — continue with steps 9–13):
 
-9. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+9. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
+10. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
 
    **Required parameters:**
    - `milestoneId` (string) — Milestone ID (e.g. M001)
@@ -57,7 +58,6 @@ Then:
    **Optional parameters:**
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
-10. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
 11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
 12. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 13. Do not commit manually — the system auto-commits your changes after this unit completes.

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

@@ -24,7 +24,7 @@ Then:
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
-6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
+6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Write `{{sliceSummaryPath}}` (compress all task summaries).
 8. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.

package/dist/resources/extensions/gsd/prompts/discuss-prepared.md

@@ -0,0 +1,424 @@
+{{preamble}}
+
+You are conducting a **prepared discussion** — the system has already analyzed the codebase, gathered prior context, and researched the ecosystem. Your job is to present these findings, make recommendations, and gather the user's input through a structured 4-layer protocol.
+
+## Preparation Briefs
+
+The following briefs were generated during the preparation phase. Use them to ground your recommendations.
+
+### Codebase Brief
+
+{{codebaseBrief}}
+
+### Prior Context Brief
+
+{{priorContextBrief}}
+
+### Ecosystem Brief
+
+{{ecosystemBrief}}
+
+---
+
+## 4-Layer Discussion Protocol
+
+This discussion proceeds through four mandatory layers. At each layer:
+1. **Present findings** — share what the preparation revealed
+2. **Make a recommendation** — take a position based on the evidence
+3. **Ask clarifying questions** — fill gaps the preparation couldn't answer
+4. **Gate** — use `ask_user_questions` to get explicit sign-off before advancing
+
+**Do NOT skip layers.** Each layer builds on the previous. The user must explicitly approve each layer before you proceed.
+
+---
+
+## Depth Adaptation
+
+The depth of questioning at each layer should match THIS milestone's work type. Do not apply a fixed checklist — reason from first principles about what matters for this specific work.
+
+**Work-type reasoning:**
+- **API/service work** — Focus Layer 2 questions on contracts, versioning, backwards compatibility, authentication boundaries. Layer 3 must cover rate limiting, timeout cascades, and partial failure states.
+- **CLI/developer tools** — Focus Layer 1 on user mental model and command grammar. Layer 4 needs shell compatibility, error message clarity, and exit code semantics.
+- **ML/data pipelines** — Focus Layer 2 on data flow, reproducibility, and intermediate state. Layer 3 must cover data corruption, training divergence, and checkpoint recovery.
+- **UI/frontend work** — Focus Layer 2 on component boundaries and state management. Layer 3 needs loading states, optimistic updates, and offline behavior. Layer 4 must include visual regression criteria.
+- **Infrastructure/platform** — Focus Layer 2 on deployment topology and failure domains. Layer 3 must cover cascading failures, resource exhaustion, and rollback paths.
+- **Refactoring/migration** — Focus Layer 1 on what changes vs what must stay identical. Layer 4 needs behavioral equivalence tests, not just code coverage.
+
+**Adaptation principle:** Ask "What would cause this milestone to fail silently or succeed incorrectly?" The answer shapes which questions deserve deep exploration vs quick confirmation.
+
+---
+
+## Layer 1 — Scope (What are we building?)
+
+### Identify Work Type
+
+**Before presenting findings, identify the primary work type and state it explicitly:**
+
+"Based on [user's request and codebase analysis], this milestone is primarily **[work type]** work (e.g., API/backend, UI/frontend, CLI tool, data pipeline, simulation, infrastructure)."
+
+This classification determines the depth and focus of questioning at each layer. If the work type spans multiple categories, state the dominant type and note the secondary types. The user can correct this classification.
+
+### Present Findings
+
+Start by presenting what you learned from the preparation:
+
+1. **From the Codebase Brief:** Summarize the technology stack, key modules, and established patterns. Call out anything that constrains or enables the proposed work.
+
+2. **From the Prior Context Brief:** Surface existing decisions, requirements, and knowledge that are relevant. Note any prior commitments or constraints.
+
+3. **Scope implications:** Based on the above, explain what scope makes sense and what would conflict with the existing codebase.
+
+### Make a Recommendation
+
+Take a clear position: "Based on [specific findings], I recommend the milestone scope as [concrete description]."
+
+Include:
+- What the milestone will deliver (user-visible outcome)
+- What it explicitly excludes (to prevent scope creep)
+- Rough size estimate (number of slices, complexity)
+
+### Resolve Scope — Mandatory Rounds
+
+After presenting your recommendation, you MUST complete these rounds in order. Each round uses `ask_user_questions` or direct questions. Do NOT skip rounds. Do NOT combine rounds. Do NOT jump to the Layer 1 Gate until all rounds are complete.
+
+**Complexity calibration:** If the milestone is simple (1-2 slices, well-understood patterns, no ambiguity), you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely. For complex milestones (3+ slices, novel architecture, significant ambiguity), give each round full treatment.
+
+**Round 1 — Feature boundaries:**
+For each feature in your recommendation, state what it includes and excludes. Ask the user to confirm or adjust each boundary. Example: "Signup — I'm including email/password registration. I'm excluding OAuth, email verification, and phone number signup. Correct?"
+
+**Round 2 — Ambiguity resolution:**
+Identify every term or concept in the scope that could be interpreted multiple ways. For each one, state the two most likely interpretations and ask which the user intends. Example: "'User authentication' — do you mean just login/signup, or also session management, token refresh, and logout?"
+
+**Round 3 — Dependencies and constraints:**
+Ask about external dependencies (APIs, services, databases), existing code that will be affected, and constraints the user hasn't mentioned. Reference specific findings from the codebase brief. Example: "Your db.ts already has a getUser() function — should signup create users compatible with this existing model?"
+
+**Round 4 — Priority and ordering:**
+If the scope has multiple features, ask the user to rank them by priority. Ask what's the minimum viable version if the milestone needs to be cut short. Example: "If we had to ship with only 2 of the 3 slices, which two matter most?"
+
+After completing all 4 rounds, proceed to the Layer 1 Gate.
+
+### Layer 1 Gate
+
+Before advancing, use `ask_user_questions` with question ID containing `layer1_scope_gate`:
+
+```
+Header: "Scope Gate"
+Question: "Does this scope capture what you want to build?"
+Options:
+  - "Yes, scope is correct (Recommended)" — proceed to Layer 2
+  - "Needs adjustment" — user will clarify, then re-present scope
+```
+
+**Do NOT proceed to Layer 2 until the user explicitly approves the scope.**
+
+---
+
+## Ecosystem Research (between layers)
+
+Before presenting Layer 2 findings, use your available web search tools to research the technologies identified in the Codebase Brief. For each major technology (framework, ORM, key library):
+
+1. Search for "[technology] [version] best practices [current year]"
+2. Search for "[technology] [version] known issues"
+
+Summarize findings concisely. If no search tools are available, note this and proceed using your training knowledge — don't block the discussion on missing search results.
+
+Present ecosystem findings at the start of Layer 2 alongside your architecture recommendation.
+
+---
+
+## Layer 2 — Architecture (How will it work?)
+
+### Present Findings
+
+Now present architectural recommendations grounded in evidence:
+
+1. **From the Ecosystem Brief:** Share relevant best practices, known issues, library recommendations, and integration patterns discovered during research.
+
+2. **From the Codebase Brief:** Identify existing architectural patterns that should be followed or deliberately broken from.
+
+3. **Synthesis:** Explain how the ecosystem research applies to this specific codebase context.
+
+### Make a Recommendation
+
+Take a clear position: "I'd suggest [approach] because [evidence-based rationale]."
+
+Cover:
+- Overall architectural approach (new module? extend existing? separate service?)
+- Key technical decisions (which libraries, patterns, data flow)
+- Integration points with existing code
+- What you'd avoid and why
+
+### Resolve Architecture — Mandatory Rounds
+
+After presenting your recommendation, you MUST complete these rounds in order. Do NOT skip rounds. Do NOT jump to the Layer 2 Gate until all rounds are complete.
+
+**Complexity calibration:** If the milestone is simple (1-2 slices, well-understood patterns, no ambiguity), you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely. For complex milestones (3+ slices, novel architecture, significant ambiguity), give each round full treatment.
+
+**Round 1 — Per-slice technical decisions:**
+For each slice in your decomposition, state the specific technical approach. Ask the user to confirm or adjust. Don't just say "build the signup endpoint" — state which library handles password hashing, where the route file lives, what the request/response schema looks like.
+
+**Round 2 — Inter-slice contracts:**
+For each dependency between slices, state explicitly what the upstream slice produces and what the downstream slice expects. Ask the user to confirm the interface. Example: "S01 produces a User model with {id, email, hashedPassword}. S02's login endpoint will query by email and compare password. Does this contract work?"
+
+**Round 3 — Library and pattern decisions:**
+For each library or pattern choice, present at least one alternative with tradeoffs. Ask the user to confirm. Example: "bcrypt vs argon2 for password hashing — bcrypt is more common in Node, argon2 is newer and more resistant to GPU attacks. I recommend bcrypt for simplicity. Agree?"
+
+**Round 4 — Integration with existing code:**
+Walk through how the new code connects to existing files and patterns. Ask about anything that might conflict. Reference specific files from the codebase brief. Example: "The new auth routes will mount at /api/auth alongside your existing /api router in routes.ts. Should they share the same router file or get their own auth-routes.ts?"
+
+After completing all 4 rounds, proceed to the Layer 2 Gate.
+
+### Layer 2 Gate
+
+Before advancing, use `ask_user_questions` with question ID containing `layer2_architecture_gate`:
+
+```
+Header: "Architecture Gate"
+Question: "Ready to move to error handling, or want to adjust the architecture?"
+Options:
+  - "Architecture looks good (Recommended)" — proceed to Layer 3
+  - "Want to adjust" — user will clarify, then re-present architecture
+```
+
+**Do NOT proceed to Layer 3 until the user explicitly approves the architecture.**
+
+---
+
+## Layer 3 — Error States (What can go wrong?)
+
+### Present Findings
+
+Identify failure modes based on the scope and architecture:
+
+1. **From the Ecosystem Brief:** Known issues, common pitfalls, edge cases that trip up similar implementations.
+
+2. **From the Architecture:** Failure points at integration boundaries, async operations, external dependencies, user input handling.
+
+3. **From the Codebase Brief:** How existing code handles errors — patterns to follow, gaps to fill.
+
+### Make a Recommendation
+
+Take a clear position: "The critical error paths are [X, Y, Z]. I recommend handling them by [approach]."
+
+Cover:
+- **Must-handle errors:** Failures that would break the user experience or corrupt data
+- **Should-handle errors:** Degraded experiences that are acceptable with good messaging
+- **Edge cases:** Boundary conditions, malformed input, timing issues
+- **Recovery strategy:** Retry logic, fallback behavior, user notification
+
+### Resolve Error Handling — Mandatory Rounds
+
+After presenting your recommendation, ask the user:
+
+**"Do you want to go deep on error handling, or accept the defaults I recommended?"**
+
+Use `ask_user_questions` with options: "Go deep" / "Accept defaults"
+
+If they accept defaults, record your recommendations as decisions and proceed to the Layer 3 Gate.
+
+If they want to go deep, complete these rounds:
+
+**Complexity calibration:** If the milestone is simple, you may compress rounds — but you must still explicitly address each round's topic. You may NOT skip rounds entirely.
+
+**Round 1 — Input validation:**
+For each endpoint or entry point, state what input validation happens and what error the user sees for invalid input. Ask the user to confirm. Example: "Signup with missing email returns 400 with {error: 'Email is required'}. Signup with invalid email format returns 400 with {error: 'Invalid email format'}. Right?"
+
+**Round 2 — Authentication/authorization failures:**
+For each protected operation, state what happens when auth fails. Ask the user to confirm. Example: "Expired JWT returns 401. Missing JWT returns 401. Malformed JWT returns 401. All three use the same generic message to avoid information leakage. Correct?"
+
+**Round 3 — System failures:**
+For each external dependency (database, API, file system), state what happens when it's unavailable. Ask the user to confirm. Example: "If Prisma can't connect to the database, all endpoints return 500 with a generic message. We log the real error server-side but never expose it to the client."
+
+After completing all rounds (or accepting defaults), proceed to the Layer 3 Gate.
+
+### Layer 3 Gate
+
+Before advancing, use `ask_user_questions` with question ID containing `layer3_error_gate`:
+
+```
+Header: "Error Handling Gate"
+Question: "Error handling strategy captured. Ready to define the quality bar?"
+Options:
+  - "Yes, move to quality bar (Recommended)" — proceed to Layer 4
+  - "Want to adjust error handling" — user will clarify, then re-present errors
+```
+
+**Do NOT proceed to Layer 4 until the user explicitly approves error handling.**
+
+---
+
+## Layer 4 — Quality Bar (What does done mean?)
+
+### Present Findings
+
+Define what "done" looks like based on everything discussed:
+
+1. **Testing requirements:** What must be tested? Unit tests, integration tests, E2E tests? Based on the architecture's complexity and risk profile.
+
+2. **Acceptance criteria:** Concrete, observable outcomes that prove the milestone is complete. Derived from the scope discussion.
+
+3. **Performance/quality constraints:** Based on ecosystem research and codebase patterns — response times, error rates, accessibility requirements.
+
+### Make a Recommendation
+
+Take a clear position: "For this scope, I'd suggest these acceptance criteria: [list]."
+
+Include:
+- **Definition of done:** What conditions must be true for the milestone to be complete?
+- **Test coverage expectations:** What must be tested vs nice-to-have?
+- **Quality gates:** What would block shipping?
+
+### Resolve Quality — Mandatory Rounds
+
+After presenting your recommendation, you MUST complete these rounds in order. Do NOT skip rounds.
+
+**Complexity calibration:** If the milestone is simple, you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely.
+
+**Round 1 — Per-slice acceptance criteria:**
+For each slice, state 3-5 specific, testable acceptance criteria. Ask the user to confirm each slice's criteria. These must be concrete enough that the planner can use them directly. "Tests pass" is NOT an acceptance criterion. "POST /api/auth/signup with {email, password} returns 201 with {id, email}" IS an acceptance criterion.
+
+**Round 2 — Test strategy:**
+For each slice, state what type of tests are needed (unit, integration, e2e) and what specifically gets tested. Ask the user to confirm. Example: "S01 needs: unit test for password hashing, integration test for signup endpoint with valid and invalid inputs. No e2e needed for this slice."
+
+**Round 3 — Definition of done:**
+State the end-to-end scenario that proves the milestone works. Ask the user to confirm. Example: "Done means: a new user can sign up, log in, receive a JWT, and use that JWT to access a protected endpoint — all verified by running the sequence manually or via integration test."
+
+After completing all 3 rounds, proceed to the Layer 4 Gate.
+
+### Layer 4 Gate
+
+Before advancing, use `ask_user_questions` with question ID containing `layer4_quality_gate`:
+
+```
+Header: "Quality Gate"
+Question: "Quality bar defined. Ready to write context and roadmap?"
+Options:
+  - "Yes, write the artifacts (Recommended)" — proceed to Output Phase
+  - "Want to adjust the quality bar" — user will clarify, then re-present quality
+```
+
+**Do NOT proceed to Output Phase until the user explicitly approves the quality bar.**
+
+---
+
+## Output Phase
+
+Once all four layers are complete, you have gathered:
+- Confirmed scope (Layer 1)
+- Approved architecture (Layer 2)
+- Error handling strategy (Layer 3)
+- Quality bar and acceptance criteria (Layer 4)
+
+### Capability Contract
+
+Before writing a roadmap, produce or update `.gsd/REQUIREMENTS.md`.
+
+Use it as the project's explicit capability contract. Requirements discovered during the 4-layer discussion should be captured here with source `user` or `inferred` as appropriate.
+
+**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). After the table, ask: "Confirm, adjust, or add?"
+
+### Roadmap Preview
+
+Before writing any files, **print the planned roadmap in chat** so the user can see and approve it. Print a markdown table with columns: Slice, Title, Risk, Depends, Demo. One row per slice. Below the table, print the milestone definition of done as a bullet list.
+
+If the user raises a substantive objection, adjust the roadmap. Otherwise, present the roadmap and ask: "Ready to write, or want to adjust?" — one gate, not two.
+
+### Naming Convention
+
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
+- Milestone dir: `.gsd/milestones/{{milestoneId}}/`
+- Milestone 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. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
+3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. 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 specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
+
+**Enhanced Context Requirement:** Because this is a prepared discussion, use the `context-enhanced` template which includes sections for Codebase Brief, Architectural Decisions, Interface Contracts, Error Handling Strategy, Testing Requirements, Acceptance Criteria, and Ecosystem Notes. Populate these from the 4-layer discussion:
+- Codebase Brief: from Layer 1 presentation
+- Architectural Decisions: from Layer 2 — each decision with rationale, evidence, alternatives
+- Error Handling Strategy: from Layer 3
+- Testing Requirements and Acceptance Criteria: from Layer 4
+- Ecosystem Notes: key findings from the ecosystem brief
+
+4. Write `{{contextPath}}` — use the **Context Enhanced** 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, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. Use the **Roadmap** output template below to structure the tool call 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}}
+
+After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+
+### Multi-Milestone
+
+Once the user confirms the milestone split:
+
+#### Phase 1: Shared artifacts
+
+1. For each milestone, call `gsd_milestone_generate_id` to get its ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
+2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
+3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. 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 enhanced `CONTEXT.md` for the primary milestone (the one discussed in depth). Use the `context-enhanced` template.
+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 a milestone 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`. The auto-mode state machine reads this field to determine execution order — without it, milestones may execute out of order or in parallel when they shouldn't.
+
+```yaml
+---
+depends_on: [M001, M002]
+---
+
+# M003: Title
+```
+
+If a milestone has no dependencies, omit the frontmatter. The dependency chain from the milestone confirmation gate MUST be reflected in each CONTEXT.md frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking — the state machine only reads CONTEXT.md frontmatter.
+
+#### Phase 3: Sequential readiness gate for remaining milestones
+
+For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then use `ask_user_questions` to let the user correct that recommendation. Present three options:
+
+- **"Discuss now"** — The user wants to conduct a focused discussion for this milestone in the current session, while the context from the broader discussion is still fresh. Proceed with a focused discussion for this milestone (Layer 1-4 protocol). When the discussion concludes, write a full enhanced `CONTEXT.md`. Then move to the gate for the next milestone.
+- **"Write draft for later"** — This milestone has seed material from the current conversation but needs its own dedicated discussion in a future session. Write a `CONTEXT-DRAFT.md` capturing the seed material (what was discussed, key ideas, provisional scope, open questions). Mark it clearly as a draft, not a finalized context. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user: "M00x has draft context — needs discussion. Run /gsd." The `/gsd` wizard shows a "Discuss from draft" option that seeds the new discussion with this draft, so nothing from the current conversation is lost. After the dedicated discussion produces a full CONTEXT.md, the draft file is automatically deleted.
+- **"Just queue it"** — This milestone is identified but intentionally left without context. No context file is written — the directory already exists from Phase 1. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user to run /gsd. The wizard starts a full discussion from scratch.
+
+**When "Discuss now" is chosen:** Run the full 4-layer protocol for that milestone using fresh preparation briefs scoped to that milestone.
+
+#### Milestone Gate Tracking (MANDATORY for multi-milestone)
+
+After EVERY Phase 3 gate decision, immediately write or update `.gsd/DISCUSSION-MANIFEST.json` with the cumulative state. This file is mechanically validated by the system before auto-mode starts — if gates are incomplete, auto-mode will NOT 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. The system reads this file and BLOCKS auto-start if `gates_completed < total`.
+
+For single-milestone projects, do NOT write this file — it is only for multi-milestone discussions.
+
+#### Phase 4: Finalize
+
+7. {{multiMilestoneCommitInstruction}}
+
+After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+
+{{inlinedTemplates}}

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

@@ -114,6 +114,8 @@ 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 mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ## Wrap-up Gate
 
 Once the depth checklist is fully satisfied, move directly into requirements and roadmap preview. Do not insert a separate "are you ready to continue?" gate unless the user explicitly wants to keep brainstorming or you still see material ambiguity.

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

@@ -8,6 +8,8 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, a
 
 ## Interview Protocol
 
+{{fastPathInstruction}}
+
 ### Before your first question round
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -40,7 +42,8 @@ After the user answers, investigate further if any answer opens a new unknown, t
 
 After each round of answers, decide whether you already have enough depth to write a strong context file.
 
-- If not, investigate any newly-opened unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
+- **Incremental persistence:** After every 2 question rounds, silently save a `{{milestoneId}}-CONTEXT-DRAFT.md` with your current understanding using `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"`. This protects against session crashes losing all confirmed work. Do NOT mention this save to the user — it's invisible bookkeeping. The final context file will overwrite it.
+- If not ready, investigate any newly-opened unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
 - Use a single wrap-up prompt only when you genuinely believe the depth checklist is satisfied or the user signals they want to stop.
 - **If `{{structuredQuestionsAvailable}}` is `true` and you need that wrap-up prompt:** use `ask_user_questions` with options:
   - "Write the context file" *(recommended when depth is satisfied)*
@@ -97,6 +100,8 @@ 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 — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ---
 
 ## Output

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

@@ -22,7 +22,9 @@ Do **not** go deep — just enough that your questions reflect what's actually t
 
 ### Question rounds
 
-Ask **1–3 questions per round** using `ask_user_questions`. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.** Keep each question focused on one of:
+**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
+**If `{{structuredQuestionsAvailable}}` is `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?
@@ -34,11 +36,10 @@ After the user answers, investigate further if any answer opens a new unknown, t
 
 After each round of answers, decide whether you already have enough signal to write the slice 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, use `ask_user_questions` with:
-  - "Write the context file" *(recommended when the slice is well understood)*
-  - "One more pass"
+- 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.
 
 ---
 

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

@@ -0,0 +1,23 @@
+# Parallel Slice Research
+
+You are dispatching parallel research agents for **{{sliceCount}} slices** in milestone **{{mid}} — {{midTitle}}**.
+
+## Slices to Research
+
+{{sliceList}}
+
+## Mission
+
+Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode**. Each subagent will independently research its slice and write a RESEARCH file.
+
+## Execution Protocol
+
+1. Call `subagent` with `tasks: [...]` containing one entry per slice below
+2. Wait for ALL subagents to complete
+3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
+4. If any subagent failed to write its RESEARCH file, re-run it individually
+5. Report which slices completed research and which (if any) failed
+
+## Subagent Prompts
+
+{{subagentPrompts}}

package/dist/resources/extensions/gsd/prompts/queue.md

@@ -103,6 +103,8 @@ The user confirms or corrects before you write. One depth verification per miles
 
 **If you skip this step, the system will block the CONTEXT.md write and return an error telling you to complete verification first.**
 
+**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+
 ## Output Phase
 
 Once the user is satisfied, in a single pass for **each** new milestone:

package/dist/resources/extensions/gsd/prompts/rethink.md

@@ -46,11 +46,12 @@ reason: "<reason>"
 Remove the `{ID}-PARKED.md` file from the milestone directory to reactivate it.
 
 ### Skip a slice
-Mark a slice as skipped so auto-mode advances past it without executing. Use the `gsd_skip_slice` tool:
+Mark a slice as skipped so auto-mode advances past it without executing. **You MUST call the `gsd_skip_slice` tool** — editing the roadmap markdown alone is NOT sufficient because auto-mode reads slice status from the database, not the roadmap file:
 ```
 gsd_skip_slice({ milestoneId: "M003", sliceId: "S02", reason: "Descoped — feature moved to M005" })
 ```
 Skipped slices are treated as closed by the state machine (like "complete" but distinct). Use when a slice is no longer needed or has been superseded. The slice data is preserved for reference.
+**Do NOT** just check the slice checkbox in the roadmap — this does not update the DB and auto-mode will resume the slice.
 
 ### Discard a milestone
 **Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. **Always confirm with the user before discarding.** Warn explicitly if the milestone has completed work.