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

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -4,9 +4,9 @@ You are executing GSD auto-mode.
 
 ## Working Directory
 
-Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+Work only in `{{workingDirectory}}`. Do not `cd` elsewhere.
 
-A researcher explored the codebase and a planner decomposed the work — you are the executor. The task plan below is your authoritative contract for the slice goal and verification bar, but it is not a substitute for local reality. Verify the referenced files and surrounding code before changing them. Do not do broad re-research or spontaneous re-planning. Small factual corrections, file-path fixes, and local implementation adaptations are part of execution. Escalate to `blocker_discovered: true` only when the slice contract or downstream task graph no longer holds.
+You execute. The inlined task plan is authoritative. Verify referenced files and surrounding code before edits. Adapt minor local mismatches; use `blocker_discovered: true` only when the slice contract or downstream graph is invalid.
 
 {{overridesSection}}
 
@@ -27,72 +27,45 @@ A researcher explored the codebase and a planner decomposed the work — you are
 ## Backing Source Artifacts
 - Slice plan: `{{planPath}}`
 - Task plan source: `{{taskPlanPath}}`
-- Prior task summaries in this slice:
+- Prior task summaries:
 {{priorTaskLines}}
 
-Then:
-0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call — but write complete sentences in user-facing prose, not shorthand notes or scratchpad fragments.
-0a. Call `memory_query` with 2-4 keywords drawn from the task title and the files it touches. Surface any prior gotchas, conventions, or architectural decisions before you start changing code. Skip only if the task is trivially mechanical.
-1. {{skillActivation}} Follow any activated skills before writing code. If no skills match this task, skip this step.
-2. Execute the steps in the inlined task plan, adapting minor local mismatches when the surrounding code differs from the planner's snapshot
-3. Before any `Write` that creates an artifact or output file, check whether that path already exists. If it does, read it first and decide whether the work is already done, should be extended, or truly needs replacement. "Create" in the plan does **not** mean the file is missing — a prior session may already have started it.
-4. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature.
-5. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail). Tests must only reference files tracked in git; never import, read, or assert on paths listed in `.gitignore` (e.g. `.gsd/`, `.planning/`, `.audits/`) — those files are local-only and the test will fail for anyone else. Use inline fixtures or tracked samples instead.
-6. When implementing non-trivial runtime behavior (async flows, API boundaries, background processes, error paths), add or preserve agent-usable observability. Skip this for simple changes where it doesn't apply.
-
-   **Background process rule:** Never use bare `command &` to run background processes. The shell's `&` operator leaves stdout/stderr attached to the parent, which causes the Bash tool to hang indefinitely waiting for those streams to close. Always redirect output before backgrounding:
-   - Correct: `command > /dev/null 2>&1 &` or `nohup command > /dev/null 2>&1 &`
-   - Example: `python -m http.server 8080 > /dev/null 2>&1 &` (NOT `python -m http.server 8080 &`)
-   - Preferred: use the `bg_shell` tool if available — it manages process lifecycle correctly without stream-inheritance issues
-7. If the task plan includes a **Failure Modes** section (Q5), implement the error/timeout/malformed handling specified. Verify each dependency's failure path is handled. Skip if the section is absent.
-8. If the task plan includes a **Load Profile** section (Q6), implement protections for the identified 10x breakpoint (connection pooling, rate limiting, pagination, etc.). Skip if absent.
-9. If the task plan includes a **Negative Tests** section (Q7), write the specified negative test cases alongside the happy-path tests — malformed inputs, error paths, and boundary conditions. Skip if absent.
-10. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors)
-11. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary.
-12. After the verification gate runs (you'll see gate results in stderr/notify output), populate the `## Verification Evidence` table in your task summary with the check results. Use the `formatEvidenceTable` format: one row per check with command, exit code, verdict (✅ pass / ❌ fail), and duration. If no verification commands were discovered, note that in the section.
-13. If the task touches UI, browser flows, DOM behavior, or user-visible web state:
-   - exercise the real flow in the browser
-   - prefer `browser_batch` when the next few actions are obvious and sequential
-   - prefer `browser_assert` for explicit pass/fail verification of the intended outcome
-   - use `browser_diff` when an action's effect is ambiguous
-   - use console/network/dialog diagnostics when validating async, stateful, or failure-prone UI
-   - record verification in terms of explicit checks passed/failed, not only prose interpretation
-14. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section.
-15. **If execution is running long or verification fails:**
-
-    **Context budget:** You have approximately **{{verificationBudget}}** reserved for verification context. If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step.
-
-    **Debugging discipline:** If a verification check fails or implementation hits unexpected behavior:
-    - Form a hypothesis first. State what you think is wrong and why, then test that specific theory. Don't shotgun-fix.
-    - Change one variable at a time. Make one change, test, observe. Multiple simultaneous changes mean you can't attribute what worked.
-    - Read completely. When investigating, read entire functions and their imports, not just the line that looks relevant.
-    - Distinguish "I know" from "I assume." Observable facts (the error says X) are strong evidence. Assumptions (this library should work this way) need verification.
-    - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there.
-    - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
-16. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
-16a. **Mid-execution escalation (ADR-011 Phase 2):** If you hit an ambiguity that is *not* a plan-invalidating blocker but whose resolution materially affects downstream work AND cannot be derived from the task plan, CONTEXT.md, DECISIONS.md, or codebase evidence, you MAY escalate to the user. Populate an `escalation` object alongside the milestoneId/sliceId/taskId fields on your completion tool call with:
-    - `question` — one clear sentence
-    - `options` — 2–4 entries with `id` (short, e.g. "A", "B"), `label`, and 1–2 sentence `tradeoffs`
-    - `recommendation` — the option `id` you recommend
-    - `recommendationRationale` — 1–2 sentences on why
-    - `continueWithDefault` — `true` means finish the task using your recommendation now and let the user's later response inject a correction into the NEXT task; `false` means auto-mode pauses until the user resolves via `/gsd escalate resolve <taskId> <choice>`.
-
-    Escalate ONLY when the answer materially affects downstream tasks AND cannot be resolved from available context. Do NOT escalate for implementation style, minor deviations, or anything already covered by DECISIONS.md. Escalations must include a real recommendation — do not ask the user to pick without giving your best judgment.
-
-    **Scope:** Escalation is instrumented only in `execute-task`. Refine-slice escalation is deferred. Reactive-execute batches run to completion before escalations are surfaced — the dispatch pause happens on the next loop iteration, not mid-batch.
-
-    The `escalation` payload is ignored unless `phases.mid_execution_escalation` is enabled; populate it anyway for audit logs.
-17. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, call `capture_thought` with `category: "architecture"` (or `"pattern"`). For decisions, populate `structuredFields` with `{ scope, decision, choice, rationale, made_by: "agent", revisable }` so future projection back to a human-visible decisions register stays lossless. Not every task produces decisions — only capture when a meaningful choice was made.
-18. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, call `capture_thought` with `category: "gotcha"`, `"convention"`, `"pattern"`, or `"environment"` as appropriate. Only capture entries that would save future agents from repeating your investigation — don't capture obvious things. The memory store is the single source of truth for cross-session knowledge (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
-19. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
-20. Use that template to prepare the completion content you will pass to `gsd_task_complete` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you.
-21. Call `gsd_task_complete` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically.
-22. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
-
-All work stays in your working directory: `{{workingDirectory}}`.
-
-**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the task summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
-
-**You MUST call `gsd_task_complete` before finishing. Do not manually write `{{taskSummaryPath}}`.**
+## Execution Rules
+
+1. Tersely narrate transitions, decisions, and verification outcomes between tool-call clusters.
+2. Call `memory_query` with 2-4 keywords from the task title and touched files unless this is purely mechanical.
+3. {{skillActivation}} Follow activated skills before code edits.
+4. Execute the task plan. Before any `Write` that creates an artifact or output file, check whether that path already exists. If it does, read it first and decide whether the work is already done, should be extended, or truly needs replacement.
+5. Build real behavior through the intended surface; stubs/mocks belong in tests only.
+6. Add or update tests. Tests must use git-tracked files or inline fixtures, never .gitignore/gitignored local paths such as `.gsd/`, `.planning/`, or `.audits/`.
+7. Preserve useful observability for non-trivial async, API, background, or error-path work.
+
+**Background process rule:** never run bare `command &`. Redirect output first, e.g. `command > /dev/null 2>&1 &`, or use `bg_shell` when available.
+
+## Gates And Verification
+
+- If task sections exist for Failure Modes (Q5), Load Profile (Q6), Negative Tests (Q7), or Observability Impact, implement and verify them.
+- Verify must-haves with concrete commands or observable behavior.
+- Run slice-level verification from the slice plan. Final tasks need all checks passing; intermediate tasks should record partial passes.
+- Populate `## Verification Evidence` with `formatEvidenceTable` rows: command, exit code, verdict, duration. If no checks were found, say so.
+- For UI/browser/DOM/user-visible web changes, exercise the real flow and record explicit checks.
+
+If verification fails, use one-hypothesis-at-a-time debugging: state the hypothesis, test it, change one variable, read complete functions/imports, separate facts from assumptions, and stop after 3 failed fixes to reset the model.
+
+Keep about **{{verificationBudget}}** for verification and summary. If context is nearly spent, stop implementation and write a resumable summary.
+
+## Completion Contract
+
+- If the plan is fundamentally invalid, set `blocker_discovered: true` in the summary and explain.
+- For downstream-impacting ambiguity that cannot be resolved from code, plans, or decisions, include an `escalation` object with question, options, recommendation, rationale, and `continueWithDefault`.
+- Capture meaningful architecture/pattern/observability decisions with `capture_thought`; capture non-obvious gotchas or conventions only when they save future investigation.
+- Read the template at `{{taskSummaryTemplatePath}}`.
+- Call `gsd_task_complete` with camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`.
+- The DB-backed tool is the canonical write path. Do **not** manually write `{{taskSummaryPath}}` or edit PLAN.md checkboxes; the tool renders the summary and updates state.
+- Do not run git commands; the system commits from your summary.
+
+**Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
+
+**You MUST call `gsd_task_complete` before finishing.**
 
 When done, say: "Task {{taskId}} complete."

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

@@ -1,4 +1,4 @@
-You are debugging GSD itself. The user is donating their tokens to help find bugs in GSD's source code. Your job is to trace from symptom to root cause in the actual source and produce a filing-ready GitHub issue with specific file:line references and a concrete fix suggestion.
+Debug GSD itself. Trace the symptom to root cause in current source and produce a filing-ready GitHub issue with file:line references and a concrete fix suggestion.
 
 ## User's Problem
 
@@ -10,7 +10,7 @@ You are debugging GSD itself. The user is donating their tokens to help find bug
 
 ## GSD Source Location
 
-GSD extension source code is at: `{{gsdSourceDir}}`
+GSD extension source: `{{gsdSourceDir}}`
 
 ### Source Map by Domain
 
@@ -25,74 +25,42 @@ GSD extension source code is at: `{{gsdSourceDir}}`
 | **Git & worktrees** | `git-service.ts` `worktree.ts` `worktree-manager.ts` `git-self-heal.ts` |
 | **Commands** | `commands.ts` `commands-inspect.ts` `commands-maintenance.ts` |
 
-### Runtime Path Reference
+### Runtime Paths
 
 ```
 .gsd/
-├── PROJECT.md, DECISIONS.md, QUEUE.md, STATE.md, REQUIREMENTS.md, OVERRIDES.md, KNOWLEDGE.md, RUNTIME.md
-├── auto.lock                    — crash lock (JSON: pid, unitType, unitId, sessionFile)
-├── metrics.json                 — token/cost ledger (units array with cost, tokens, duration)
-├── completed-units.json         — array of "type/id" strings
-├── doctor-history.jsonl         — doctor check history
-├── activity/                    — session activity logs (JSONL per unit)
-│   └── {seq}-{unitType}-{unitId}.jsonl
-├── journal/                     — structured event journal (JSONL per day)
-│   └── YYYY-MM-DD.jsonl
-├── runtime/
-│   ├── paused-session.json      — serialized session when auto pauses
-│   └── headless-context.md      — headless resume context
-├── debug/                       — debug logs
-├── forensics/                   — saved forensic reports
-├── milestones/{ID}/             — milestone artifacts
-│   ├── {ID}-ROADMAP.md, {ID}-RESEARCH.md, {ID}-CONTEXT.md, {ID}-SUMMARY.md
-│   └── slices/{SID}/            — slice artifacts
-│       ├── {SID}-PLAN.md, {SID}-RESEARCH.md, {SID}-UAT.md, {SID}-SUMMARY.md
-│       └── tasks/{TID}-PLAN.md, {TID}-SUMMARY.md
-└── worktrees/{milestoneId}/     — per-milestone worktree with replicated .gsd/
+├── PROJECT.md, REQUIREMENTS.md, DECISIONS.md, KNOWLEDGE.md, QUEUE.md, STATE.md, OVERRIDES.md, RUNTIME.md
+├── auto.lock, metrics.json, completed-units.json, doctor-history.jsonl
+├── activity/{seq}-{unitType}-{unitId}.jsonl
+├── journal/YYYY-MM-DD.jsonl
+├── runtime/paused-session.json, runtime/headless-context.md
+├── debug/, forensics/, worktrees/{milestoneId}/
+└── milestones/{ID}/{ID}-ROADMAP.md, {ID}-RESEARCH.md, {ID}-CONTEXT.md, {ID}-SUMMARY.md
+    └── slices/{SID}/{SID}-PLAN.md, {SID}-RESEARCH.md, {SID}-UAT.md, {SID}-SUMMARY.md, tasks/{TID}-PLAN.md, tasks/{TID}-SUMMARY.md
 ```
 
-### Activity Log Format
+### Activity Logs
 
-- **Filename**: `{3-digit-seq}-{unitType}-{unitId}.jsonl`
-- Each line is a JSON object with `type: "message"` and a `message` field
-- `message.role: "assistant"` — contains `content[]` array:
-  - `type: "text"` entries hold the agent's reasoning
-  - `type: "toolCall"` entries hold tool invocations (`name`, `id`, `arguments`)
-- `message.role: "toolResult"` — contains `toolCallId`, `toolName`, `isError`, `content`
-- `usage` field on assistant messages: `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, `cost`
-- **To trace a failure**: find the last activity log, search for `isError: true` tool results, then read the agent's reasoning text preceding that error
+- Filename: `{3-digit-seq}-{unitType}-{unitId}.jsonl`
+- JSONL messages include assistant `content[]` text/tool calls and tool results with `toolCallId`, `toolName`, `isError`, `content`
+- `usage` has input/output/cache/token/cost fields
+- To trace failure: inspect the last activity log, find `isError: true`, and read preceding reasoning
 
 ### Journal Format (`.gsd/journal/`)
 
-The journal is a structured event log for auto-mode iterations. Each daily file contains JSONL entries:
+The journal is a structured event log for auto-mode iterations. Daily files contain JSONL:
 
 ```
 { ts: "ISO-8601", flowId: "UUID", seq: 0, eventType: "iteration-start", rule?: "rule-name", causedBy?: { flowId, seq }, data?: { unitId, status, ... } }
 ```
 
-**Key event types:**
-- `iteration-start` / `iteration-end` — marks loop iteration boundaries
-- `dispatch-match` / `dispatch-stop` — what the auto-mode decided to do (or not do)
-- `unit-start` / `unit-end` — lifecycle of individual work units
-- `terminal` — auto-mode reached a terminal state (all done, budget exceeded, etc.)
-- `guard-block` — dispatch was blocked by a guard condition (e.g. needs user input)
-- `stuck-detected` — the loop detected it was stuck (same unit repeatedly dispatched)
-- `milestone-transition` — a milestone was promoted or completed
-- `worktree-enter` / `worktree-create-failed` / `worktree-merge-start` / `worktree-merge-failed` — worktree operations
-
-**Key concepts:**
-- **flowId**: UUID grouping all events in one iteration. Use to reconstruct what happened in a single loop pass.
-- **causedBy**: Cross-reference to a prior event (same or different flow). Enables causal chain tracing.
-- **seq**: Monotonically increasing within a flow. Reconstruct event order within an iteration.
-
-**To trace a stuck loop**: filter for `stuck-detected` events, then follow `flowId` to see the surrounding dispatch and unit events.
-**To trace a guard block**: filter for `guard-block` events, check `data.reason` for why dispatch was blocked.
+Key events: `iteration-start/end`, `dispatch-match/stop`, `unit-start/end`, `terminal`, `guard-block`, `stuck-detected`, `milestone-transition`, worktree events. `flowId` groups one loop; `causedBy` links causal events; `seq` orders events. Trace stuck loops with `stuck-detected` -> `flowId`; guard blocks with `guard-block` and `data.reason`.
 
 ### Crash Lock Format (`auto.lock`)
 
 JSON with fields: `pid`, `startedAt`, `unitType`, `unitId`, `unitStartedAt`, `completedUnits`, `sessionFile`
 
-A stale lock (PID is dead) means the previous auto-mode session crashed mid-unit.
+A stale lock (dead PID) means the previous auto-mode session crashed mid-unit.
 
 ### Metrics Ledger Format (`metrics.json`)
 
@@ -100,54 +68,44 @@ A stale lock (PID is dead) means the previous auto-mode session crashed mid-unit
 { version: 1, projectStartedAt: <ms>, units: [{ type, id, model, startedAt, finishedAt, tokens: { input, output, cacheRead, cacheWrite, total }, cost, toolCalls, assistantMessages, ... }] }
 ```
 
-A unit dispatched more than once (`type/id` appears multiple times) indicates a stuck loop — the unit completed but artifact verification failed.
+A unit dispatched more than once (`type/id` repeated) indicates a stuck loop: unit completed but artifact verification failed.
 
 {{dedupSection}}
 
 ## Investigation Protocol
 
-1. **Start with the pre-parsed forensic report** above. The anomaly section contains automated findings — treat these as leads, not conclusions.
-
-2. **Check the journal timeline** if present. The journal events show the auto-mode's decision sequence (dispatches, guards, stuck detection, worktree operations). Use flow IDs to group related events and trace causal chains.
-
-3. **Cross-reference activity logs and journal**. Activity logs show *what the LLM did* (tool calls, reasoning, errors). Journal events show *what auto-mode decided* (dispatch rules, iteration boundaries, state transitions). Together they reveal the full picture.
-
-4. **Form hypotheses** about which module and code path is responsible. Use the source map to identify candidate files.
+1. Start with the forensic report; treat anomalies as leads.
+2. Check journal timeline if present. Use flow IDs to group dispatches, guards, stuck detection, transitions, and worktree operations.
+3. Cross-reference activity logs (LLM actions) with journal events (auto-mode decisions).
+4. Form hypotheses about the responsible module/code path using the source map.
 
-5. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
+5. Read actual source at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess.
 
-   **DB inspection:** If you need to check DB state as part of investigation, use `gsd_milestone_status` — never run `sqlite3 .gsd/gsd.db` or `node -e require('better-sqlite3')` directly. The engine holds a WAL write lock; direct access will either fail or return stale data.
+   **DB inspection:** Use `gsd_milestone_status`; never run `sqlite3 .gsd/gsd.db` or `node -e require('better-sqlite3')`. The engine owns the WAL connection; direct access can fail or return stale data.
 
-6. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
+6. Trace from entry point, usually `auto-loop.ts` or `auto-dispatch.ts`, to failure across files.
 
-7. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:
-   - Missing edge case / unhandled condition
-   - Wrong boolean logic or comparison
-   - Race condition or ordering issue
-   - State corruption (e.g. completed-units.json out of sync with artifacts)
-   - Timeout / recovery logic not triggering correctly
+7. Identify file and line. Classify the defect: missing edge case, wrong logic/comparison, race/order issue, state corruption, or timeout/recovery failure.
 
-8. **Clarify if needed.** Use ask_user_questions (max 2 questions) only if the report is genuinely insufficient. Do not ask questions you can answer from the data or source code.
+8. Clarify only if needed. Use ask_user_questions (max 2) only when report + source are insufficient.
 
 ## Output
 
-Explain your findings:
-- **What happened** — the failure sequence reconstructed from activity logs and anomalies
-- **Why it happened** — root cause traced to specific code in GSD source, with `file:line` references
-- **Code snippet** — the problematic code and what it should do instead
-- **Recovery** — what the user can do right now to get unstuck
+Explain findings:
+- **What happened** — sequence from activity logs/anomalies
+- **Why it happened** — root cause with `file:line`
+- **Code snippet** — problematic code and intended behavior
+- **Recovery** — immediate unstuck steps
 
 Then **offer GitHub issue creation**: "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?"
 
-**CRITICAL: The `github_issues` tool ONLY targets the current user's repository — it has no `repo` parameter. You MUST use `gh issue create --repo gsd-build/gsd-2` via the `bash` tool to file on the correct repo. Do NOT use the `github_issues` tool for this.**
+**CRITICAL:** The `github_issues` tool targets only the current user's repository and has no `repo` parameter. Use `gh issue create --repo gsd-build/gsd-2` via `bash`. Do NOT use the `github_issues` tool.
 
 If yes, create using the `bash` tool:
 
 ```bash
-# Step 1: Write issue body to a temp file to avoid escaping/truncation issues.
-# Using --body-file bypasses shell quoting entirely — backticks, quotes, and
-# content containing "EOF" all render correctly. (#2465)
-cat > /tmp/gsd-forensic-issue.md << 'GSD_ISSUE_BODY'
+ISSUE_BODY_FILE="${TMPDIR:-${TEMP:-${TMP:-.}}}/gsd-forensic-issue.md"
+cat > "$ISSUE_BODY_FILE" << 'GSD_ISSUE_BODY'
 ## Problem
 [1-2 sentence summary]
 
@@ -175,10 +133,9 @@ GSD_ISSUE_BODY
 ISSUE_URL=$(gh issue create --repo gsd-build/gsd-2 \
   --title "..." \
   --label "auto-generated" \
-  --body-file /tmp/gsd-forensic-issue.md)
-rm -f /tmp/gsd-forensic-issue.md
+  --body-file "$ISSUE_BODY_FILE")
+rm -f "$ISSUE_BODY_FILE"
 
-# Step 2: Set issue type via GraphQL (gh issue create has no --type flag)
 ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
 ISSUE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issue(number:'"$ISSUE_NUM"') { id } } }' --jq '.data.repository.issue.id')
 TYPE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issueTypes(first:20) { nodes { id name } } } }' --jq '.data.repository.issueTypes.nodes[] | select(.name=="Bug") | .id')
@@ -191,8 +148,8 @@ Before creating the issue, you MUST:
 - Replace all absolute paths with relative paths
 - Remove any API keys, tokens, or credentials
 - Remove any environment variable values
-- Do not include user's project code — only GSD structural information (tool names, file names, error messages)
+- Do not include user project code — only GSD structure (tool names, file names, error messages)
 
 ## Report Saved
 
-Remind the user that the full forensic report was saved locally (the path will be in the notification).
+Remind the user that the full forensic report was saved locally; the notification includes the path.

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

@@ -1,6 +1,6 @@
 **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
 
-Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Use the **Context** output template below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify real gray areas, ask about them, then write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the **Context** template below. If a `GSD Skill Preferences` block exists, use it to choose skills; artifact rules still apply.
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
@@ -14,48 +14,46 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, a
 
 ### Read project shape
 
-Before your first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. The verdict is either **`simple`** or **`complex`** (default to `complex` if PROJECT.md is missing the section, predates this convention, or the value is unclear). The verdict scales the rest of this stage:
+Before asking, read `.gsd/PROJECT.md` and find `## Project Shape` -> `**Complexity:**`. Use `simple` or `complex`; default to `complex` if missing, stale, or unclear.
 
-- **`simple`** — favor 1–2 plain-text question rounds. Skip the parallel-research investigation. Skip `ask_user_questions` unless presenting concrete alternatives.
-- **`complex`** — full investigation, 3–4-option structured questions, multi-round.
+- `simple`: 1-2 plain-text rounds; skip parallel-research investigation; use `ask_user_questions` only for concrete alternatives.
+- `complex`: investigate first, use 3-4-option structured questions, and expect multiple rounds.
 
 ### Before your first question round
 
-Do a lightweight targeted investigation so your questions are grounded in reality:
-- Scout the codebase (`rg`, `find`, or `scout`) to understand what already exists that this milestone touches or builds on
-- Check the roadmap context above (if present) to understand what surrounds this milestone
-- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation
-- Identify the 3–5 biggest behavioural and architectural unknowns: things where the user's answer will materially change what gets built
+Investigate enough to avoid assumption-driven questions:
+- Scout existing code with `rg`, `find`, or `scout`.
+- Check roadmap context above for surrounding scope.
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries; prefer them over web search.
+- Identify the 3-5 behavioral or architectural unknowns that materially change what gets built.
 
-**Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them.
-
-Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume.
+**Web search budget:** Limited per turn, typically 3-5. Prefer docs tools and `search_and_read`; use 2-3 searches in the first pass and save the rest.
 
 ### Question rounds
 
-Ask **1–3 questions per round**. Keep each question focused on one of:
-- **What they're building** — 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** — user, team, 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
+Ask **1–3 questions per round**. Target one focus at a time:
+- **What**: concrete enough to explain to a stranger.
+- **Why**: problem solved or desire fulfilled.
+- **Who**: user, team, or themselves.
+- **Done**: observable outcomes.
+- **Risks**: biggest unknowns or assumptions.
+- **External systems**: APIs, databases, third-party services.
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine when alternatives are genuinely binary. Binary depth-check / wrap-up gates are exempt from the 3-or-4 rule. When the user picks "Other — let me discuss" or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: 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 `true`:** use `ask_user_questions` exactly once per turn with 1-3 question objects. Keep labels short (3-5 words). In `complex` mode, multi-choice questions MUST offer **3 or 4 concrete, researched options** plus **"Other — let me discuss"**; options must be grounded in the investigation, not placeholders. In `simple` mode, 2 options is fine for binary alternatives. Binary depth-check/wrap-up gates are exempt. If the user chooses "Other — let me discuss" or gives a long freeform answer, switch to plain-text follow-up before resuming structured questions.
 
 **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.
 
-After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
+After each answer, investigate only new unknowns, then ask the next round.
 
 ### Round cadence
 
-After each round of answers, decide whether you already have enough depth to write a strong context file.
+After each answer round, decide whether the context would be strong enough.
 
-- **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.
+- **Incremental persistence:** After every 2 question rounds, silently save `{{milestoneId}}-CONTEXT-DRAFT.md` via `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"`. Do NOT mention this save to the user. The final context overwrites it.
+- If not ready, investigate new unknowns and continue. Do **not** ask a meta "ready to wrap up?" question after every round.
+- Use one wrap-up prompt only when the depth checklist is satisfied or the user wants 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)*
   - "One more pass"
@@ -65,15 +63,7 @@ After each round of answers, decide whether you already have enough depth to wri
 
 ## Questioning philosophy
 
-**Start open, follow energy.** Let the user's enthusiasm guide where you dig deeper.
-
-**Challenge vagueness, make abstract concrete.** When the user says something abstract ("it should be smart" / "good UX"), push for specifics.
-
-**Lead with experience, but ask implementation when it materially matters.** Default questions should target the experience and outcome. But when implementation choices materially change scope, proof, compliance, integration, deployment, or irreversible architecture, ask them directly instead of forcing a fake UX phrasing.
-
-**Position-first framing.** Have opinions. "I'd lean toward X because Y — does that match your thinking?" is better than "what do you think about X vs Y?"
-
-**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. Negative constraints are sharper than positive wishes.
+Start open and follow the user's language. Challenge vague phrases with specifics. Default to experience/outcome questions, but ask implementation questions when choices materially affect scope, proof, compliance, integration, deployment, or irreversible architecture. Use position-first framing when useful: "I'd lean toward X because Y — does that match your thinking?" Ask what would disappoint them and what they explicitly do not want.
 
 **Anti-patterns — never do these:**
 - Checklist walking through predetermined topics regardless of what the user said
@@ -86,7 +76,7 @@ After each round of answers, decide whether you already have enough depth to wri
 
 ## Depth Verification
 
-Before moving to the wrap-up gate, verify you have covered:
+Before the wrap-up gate, verify coverage:
 
 - [ ] What they're building — concrete enough to explain to a stranger
 - [ ] Why it needs to exist
@@ -95,7 +85,7 @@ Before moving to the wrap-up gate, verify you have covered:
 - [ ] The biggest technical unknowns / risks
 - [ ] What external systems/services this touches
 
-**Print a structured depth summary in chat first** — using the user's own terminology. Cover what you understood, what shaped your understanding, and any areas of remaining uncertainty.
+**Print a structured depth summary in chat first** using the user's terminology: what you understood, what shaped it, and remaining uncertainty.
 
 **Then confirm:**
 
@@ -105,13 +95,13 @@ Before moving to the wrap-up gate, verify you have covered:
 - options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
 - **The question ID must contain `depth_verification` and the milestone id** (e.g. `depth_verification_{{milestoneId}}_confirm`) — this enables the write-gate downstream and keeps verification scoped to the milestone being discussed.
 
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation before proceeding. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask. Never rationalize past a missing confirmation.
+**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 to the plain-text path**: if the user does not respond, is ambiguous, or does not explicitly confirm, re-ask. Never rationalize past missing confirmation.
 
 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 (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block ("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.
+**CRITICAL — Non-bypassable gate:** The system blocks CONTEXT.md writes until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask; never rationalize past the block ("tool not responding, I'll proceed" is forbidden).
 
 ---
 
@@ -121,6 +111,6 @@ Once the user confirms depth:
 
 1. Use the **Context** output template below
 2. `mkdir -p` the milestone directory if needed
-3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "CONTEXT"`, and the full context markdown as `content` — the tool writes the file to disk and persists to DB. Preserve the user's exact terminology, emphasis, and framing in the content. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
+3. Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `artifact_type: "CONTEXT"`, and full context markdown as `content`; the tool writes the file and persists to DB. Preserve the user's terminology, emphasis, and framing; downstream agents rely on this file.
 4. {{commitInstruction}}
 5. Say exactly: `"{{milestoneId}} context written."` — nothing else.