gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

package/src/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/src/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/src/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/src/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/src/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/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- 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 **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`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.
@@ -56,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`
@@ -70,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.
@@ -82,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/src/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- 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 **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`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

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

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

@@ -35,7 +35,7 @@ GSD ships with bundled skills. Load the relevant skill file with the `read` tool
 - Read before edit.
 - Reproduce before fix when possible.
 - Work is not done until the relevant verification has passed.
-- **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar to represent user input inside your own output. Prior conversation context may be provided to you inside `<conversation_history>` with `<user_message>` / `<assistant_message>` XML tags — treat those as read-only context and never emit those tags in your response. Ask one question round (1-3 questions), then stop and wait for the user's actual response before continuing. If `ask_user_questions` is available, treat its returned response as the only valid structured user input for that round.
+- **Never fabricate, simulate, or role-play user responses.** Never generate markers like `[User]`, `[Human]`, `User:`, or similar to represent user input inside your own output. Prior conversation context may be provided to you inside `<conversation_history>` with `<user_message>` / `<assistant_message>` XML tags — treat those as read-only context and never emit those tags in your response. Ask one question round (1-3 questions), then stop and wait for the user's actual response before continuing. If `ask_user_questions` is available, treat its returned response as the only valid structured user input for that round. If `ask_user_questions` is cancelled, fails, or returns no response, never treat earlier chat as confirmation for the current gate; ask in plain chat and stop.
 - Never print, echo, log, or restate secrets or credentials. Report only key names and applied/skipped status.
 - Never ask the user to edit `.env` files or set secrets manually. Use `secure_env_collect`.
 - In enduring files, write current state only unless the file is explicitly historical.
@@ -90,11 +90,11 @@ Titles live inside file content (headings, frontmatter), not in file or director
 
 ### Isolation Model
 
-Auto-mode supports three isolation modes (configured in `.gsd/PREFERENCES.md` under `taskIsolation.mode`):
+Auto-mode supports three isolation modes (configured in `.gsd/PREFERENCES.md` under `git.isolation`):
 
-- **worktree** (default): Work happens in `.gsd/worktrees/<MID>/`, a full git worktree on the `milestone/<MID>` branch. Each worktree has its own working copy and `.gsd/` directory. Squash-merged back to the integration branch on milestone completion.
+- **none** (default): Work happens directly on the current branch. No worktree, no milestone branch. Commits land in-place.
+- **worktree**: Work happens in `.gsd/worktrees/<MID>/`, a full git worktree on the `milestone/<MID>` branch. Each worktree has its own working copy and `.gsd/` directory. Squash-merged back to the integration branch on milestone completion.
 - **branch**: Work happens in the project root on a `milestone/<MID>` branch. No worktree directory — files are checked out in-place.
-- **none**: Work happens directly on the current branch. No worktree, no milestone branch. Commits land in-place.
 
 In all modes, slices commit sequentially on the active branch; there are no per-slice branches.
 

package/src/resources/extensions/gsd/queue-order.ts

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { isDbAvailable, setMilestoneQueueOrder } from "./gsd-db.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -63,9 +64,13 @@ export function loadQueueOrder(basePath: string): string[] | null {
 }
 
 /**
- * Save a custom queue order to disk.
+ * Save a custom queue order. The DB sequence is canonical when a DB
+ * connection is open; QUEUE-ORDER.json remains a compatibility projection.
  */
 export function saveQueueOrder(basePath: string, order: string[]): void {
+  if (isDbAvailable()) {
+    setMilestoneQueueOrder(order);
+  }
   const data: QueueOrderFile = {
     order,
     updatedAt: new Date().toISOString(),

package/src/resources/extensions/gsd/repo-identity.ts

@@ -9,10 +9,9 @@
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Repo Metadata ───────────────────────────────────────────────────────────
 
@@ -168,7 +167,7 @@ function isProjectGsd(gsdPath: string): boolean {
     // Recompute gsdHome dynamically so env overrides (GSD_HOME) are
     // picked up at call time, not just at module load time.
     if (stat.isDirectory()) {
-      const currentGsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+      const currentGsdHome = gsdHome();
       const normalizedGsdPath = canonicalizeExistingPath(gsdPath);
       const normalizedGsdHome = canonicalizeExistingPath(currentGsdHome);
       if (normalizedGsdPath === normalizedGsdHome) return false;
@@ -311,7 +310,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || gsdHome;
+  const base = process.env.GSD_STATE_DIR || gsdHome();
   return join(base, "projects", repoIdentity(basePath));
 }
 
@@ -320,7 +319,7 @@ export function externalGsdRoot(basePath: string): string {
  * Honors GSD_STATE_DIR override before falling back to GSD_HOME.
  */
 export function externalProjectsRoot(): string {
-  const base = process.env.GSD_STATE_DIR || gsdHome;
+  const base = process.env.GSD_STATE_DIR || gsdHome();
   return join(base, "projects");
 }
 
@@ -441,7 +440,7 @@ function resolveExternalPathWithRecovery(projectPath: string): string {
   const markerId = readGsdIdMarker(projectPath);
   if (markerId && markerId !== computedId) {
     // The marker points to a different identity — the repo was likely moved.
-    const base = process.env.GSD_STATE_DIR || gsdHome;
+    const base = process.env.GSD_STATE_DIR || gsdHome();
     const markerPath = join(base, "projects", markerId);
     if (hasProjectState(markerPath)) {
       // Recover: use the old state directory and update the marker to the new identity.
@@ -510,9 +509,16 @@ function ensureGsdSymlinkCore(projectPath: string): string {
   // Guard: Never create a symlink at ~/.gsd — that's the user-level GSD home,
   // not a project .gsd. This can happen if resolveProjectRoot() or
   // escapeStaleWorktree() returned ~ as the project root (#1676).
-  const localGsdNormalized = localGsd.replaceAll("\\", "/");
-  const gsdHomePath = gsdHome.replaceAll("\\", "/");
-  if (localGsdNormalized === gsdHomePath) {
+  // Canonical normalization: resolve symlinks, trim trailing slashes, case-fold on Windows.
+  const normalizeForGuard = (p: string): string => {
+    let resolved: string;
+    try { resolved = realpathSync(p); } catch { resolved = resolve(p); }
+    const s = resolved.replaceAll("\\", "/").replace(/\/+$/, "");
+    return process.platform === "win32" ? s.toLowerCase() : s;
+  };
+  const localGsdNormalized = normalizeForGuard(localGsd);
+  const gsdHomeNorm = normalizeForGuard(gsdHome());
+  if (localGsdNormalized === gsdHomeNorm) {
     return localGsd;
   }
 

package/src/resources/extensions/gsd/rethink.ts

@@ -20,6 +20,7 @@ import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
 import { buildExistingMilestonesContext } from "./guided-flow-queue.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { isGsdGitignored } from "./gitignore.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 
@@ -33,7 +34,7 @@ export async function handleRethink(
     return;
   }
 
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const root = gsdRoot(basePath);
   if (!existsSync(root)) {
     ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");

package/src/resources/extensions/gsd/safety/git-checkpoint.ts

@@ -23,7 +23,7 @@ const CHECKPOINT_PREFIX = "refs/gsd/checkpoints/";
  */
 export function createCheckpoint(basePath: string, unitId: string): string | null {
   try {
-    const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+    const sha = execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
@@ -41,6 +41,15 @@ export function createCheckpoint(basePath: string, unitId: string): string | nul
 
     return sha;
   } catch (e) {
+    const stderr = (e as { stderr?: Buffer | string }).stderr;
+    const stderrText = Buffer.isBuffer(stderr) ? stderr.toString("utf-8") : String(stderr ?? "");
+    if (
+      stderrText.includes("Needed a single revision") ||
+      stderrText.includes("unknown revision") ||
+      stderrText.includes("ambiguous argument 'HEAD'")
+    ) {
+      return null;
+    }
     logWarning("safety", `checkpoint creation failed: ${(e as Error).message}`);
     return null;
   }

package/src/resources/extensions/gsd/schemas/__fixtures__/valid-project.md

@@ -0,0 +1,26 @@
+# Project
+
+## What This Is
+
+A test project for validating Phase 11 deep planning mode artifact contracts.
+
+## Core Value
+
+The project must produce reliable validation results for malformed artifacts.
+
+## Current State
+
+Phase 11 dispatch units are landed. Validators are being built.
+
+## Architecture / Key Patterns
+
+TypeScript monorepo with markdown artifacts, AJV-style validators, parser-then-schema pattern.
+
+## Capability Contract
+
+See `.gsd/REQUIREMENTS.md` for the explicit capability contract.
+
+## Milestone Sequence
+
+- [ ] M001: Validators — build the runtime artifact validation framework
+- [ ] M002: Manifest — extend DISCUSSION-MANIFEST.json with planning stages

package/src/resources/extensions/gsd/schemas/__fixtures__/valid-requirements.md

@@ -0,0 +1,57 @@
+# Requirements
+
+## Active
+
+### R001 — Validators reject malformed artifacts
+- Class: core-capability
+- Status: active
+- Description: validateArtifact returns ok=false when required sections are missing
+- Why it matters: prevents malformed PROJECT.md/REQUIREMENTS.md from propagating to downstream stages
+- Source: spec
+- Primary owning slice: M001/S01
+- Supporting slices: none
+- Validation: unmapped
+- Notes: contract spec at 11-CONTRACTS.md
+
+## Validated
+
+## Deferred
+
+### R020 — Schema versioning
+- Class: operability
+- Status: deferred
+- Description: schema_version field in DISCUSSION-MANIFEST.json
+- Why it matters: enables backward-compat migrations
+- Source: research
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: unmapped
+- Notes: lands with manifest extension in M002
+
+## Out of Scope
+
+### R030 — Real-time validation
+- Class: anti-feature
+- Status: out-of-scope
+- Description: file watcher that validates on every save
+- Why it matters: prevents scope creep into IDE tooling
+- Source: inferred
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: out of scope for Phase 11
+
+## Traceability
+
+| ID | Class | Status | Primary owner | Supporting | Proof |
+|---|---|---|---|---|---|
+| R001 | core-capability | active | M001/S01 | none | unmapped |
+| R020 | operability | deferred | none | none | unmapped |
+| R030 | anti-feature | out-of-scope | none | none | n/a |
+
+## Coverage Summary
+
+- Active requirements: 1
+- Mapped to slices: 1
+- Validated: 0
+- Unmapped active requirements: 0