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

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

@@ -6,55 +6,61 @@ You are executing GSD auto-mode.
 
 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.
 
-## Your Role in the Pipeline
+## Mission
 
-All slices are done. You are closing out the milestone — verifying that the assembled work actually delivers the promised outcome, writing the milestone summary, and updating project state. The milestone summary is the final record. After you finish, the system merges the worktree back to the integration branch. If there are queued milestones, the next one starts its own research → plan → execute cycle from a clean slate — the milestone summary is how it learns what was already built.
+All slices are complete. Verify the integrated work, persist milestone completion, refresh project state, and write the final record future milestones will rely on.
 
-Preloaded context below — the roadmap, compact slice-summary excerpts, requirements, decisions, and project context. **Slice summaries are excerpts, not full files.** They include frontmatter fields, section heads (deviations, known limitations, follow-ups), and short narrative only. When drafting LEARNINGS, the Decision Re-evaluation table, or cross-slice narrative, Read the full slice SUMMARY.md files listed under "On-demand Slice Summaries" — do that selectively as needed, not preemptively.
+Preloaded context includes roadmap, requirements, decisions, project context, and compact slice-summary excerpts. Slice summaries are excerpts, not full files: use them first, then selectively read full SUMMARY.md files listed under "On-demand Slice Summaries" only when section headings indicate needed evidence for LEARNINGS, Decision Re-evaluation, deviations, limitations, or cross-slice narrative.
 
 Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
 
-**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
+**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 12). Once that tool runs, the milestone is marked complete in the DB, so it must be the final persistent milestone-closeout write.
 
 ### Delegate Review Work
 
-This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+Use `subagent` for review work needing fresh context, before drafting LEARNINGS:
 
-- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
-- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
-- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+- Cross-slice integrations or new public APIs -> **reviewer** with milestone diff and roadmap.
+- Auth, network, parsing, file IO, shell exec, or crypto -> **security** audit.
+- Significant tests added or changed -> **tester** coverage check against success criteria.
 
-Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+Subagents report only; they do not write user source. Fold findings into Decision Re-evaluation and LEARNINGS before completion.
 
 {{inlinedContext}}
 
-Then:
+## Steps
+
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Compare the milestone against its integration branch (usually `main`, `master`, or the recorded integration branch), using the merge-base as the older revision and `HEAD` as the newer revision. If that branch diff lists non-`.gsd/` files, code-change verification passes. If `HEAD` is already the same commit as the integration branch/merge-base (a retry-on-main self-diff), do **not** treat the empty branch diff as proof of missing code. Instead, inspect milestone-scoped commit evidence such as recent commits with `GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers whose diff also touches `.gsd/milestones/{{milestoneId}}/`, then check those commits for non-`.gsd/` files. Only record a **verification failure** when neither the branch diff nor milestone-scoped commit evidence shows implementation files.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
-6. If the roadmap includes a **Horizontal Checklist**, verify each item was addressed during the milestone. Note unchecked items in the milestone summary.
-7. Fill the **Decision Re-evaluation** table in the milestone summary. For each key decision from `.gsd/DECISIONS.md` made during this milestone, evaluate whether it is still valid given what was actually built. Flag decisions that should be revisited next milestone.
-8. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
+3. **Verify code changes exist.** Compare milestone work against the integration branch (`main`, `master`, or recorded branch), using merge-base as older revision and `HEAD` as newer. If the diff lists non-`.gsd/` files, pass. If `HEAD` equals the integration branch/merge-base, treat it as a self-diff retry: inspect milestone-scoped commit evidence (`GSD-Unit: {{milestoneId}}` or production `GSD-Task: Sxx/Tyy` trailers touching `.gsd/milestones/{{milestoneId}}/`) and verify those commits touched non-`.gsd/` files. Record **verification failure** only when neither source shows implementation files.
+4. Verify every **success criterion** from `{{roadmapPath}}` with evidence from summaries, tests, or observable behavior. Record unmet criteria as **verification failure**.
+5. Verify **definition of done**: all slices `[x]`, summaries exist, and integrations work. Record unmet items as **verification failure**.
+6. If the roadmap includes a **Horizontal Checklist**, verify each item and note unchecked items in the summary.
+7. Fill the **Decision Re-evaluation** table: compare each key `.gsd/DECISIONS.md` decision from this milestone with what shipped, and flag decisions to revisit.
+8. Validate **requirement status transitions**. For each changed requirement, confirm evidence supports the new status. Requirements may move between Active, Validated, Deferred, Blocked, or Out of Scope only with proof.
 
-**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools — never via direct SQL.
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`; the engine owns the WAL connection. Use `gsd_milestone_status`, inlined context, or `gsd_*` tools; never direct SQL.
 
 ### 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 10.**
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed with steps 9–13.**
 
 **Failure path** (verification failed):
-- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT call `gsd_complete_milestone`.
 - Do NOT update `.gsd/PROJECT.md` to reflect completion.
-- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
-- Write a clear summary of what failed and why to help the next attempt.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements validated.
+- Write a clear failed-verification summary for the next attempt.
 - Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
 
-**Success path** (all verifications passed — continue with steps 9–13):
+**Success path** (all verifications passed):
 
 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.
+10. 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.
+11. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
+
+{{extractLearningsSteps}}
+
+12. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. This must be the final persistent write in the unit. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete.
 
    **Required parameters:**
    - `milestoneId` (string) — Milestone ID (e.g. M001)
@@ -67,19 +73,15 @@ Then:
    - `keyDecisions` (array of strings) — Key architectural/pattern decisions made during the milestone
    - `keyFiles` (array of strings) — Key files created or modified during the milestone
    - `lessonsLearned` (array of strings) — Lessons learned during the milestone
-   - `verificationPassed` (boolean) — Must be `true` — confirms that code change verification, success criteria, and definition of done checks all passed before completion
+   - `verificationPassed` (boolean) — Must be `true`; confirms code-change verification, success criteria, and definition-of-done checks all passed
 
    **Optional parameters:**
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
-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. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
-
-{{extractLearningsSteps}}
 
 13. Do not commit manually — the system auto-commits your changes after this unit completes.
 - Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run. **If a verification tool itself fails, errors, or returns unexpected output, treat it as a verification failure** — never rationalize past a tool error ("tool didn't respond, assuming success" is forbidden). A tool that cannot verify is a tool that did not verify.
+**Important:** Do NOT skip code-change, success-criteria, or definition-of-done verification (steps 3-5). The summary must reflect verified outcomes. Verification failures block completion; there is no override. If a verification tool fails, errors, or returns unexpected output, treat it as failure.
 
-**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` first. Never pass a directory path (e.g. `tasks/`, `slices/`) to `read`; it only accepts file paths.

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

@@ -4,51 +4,40 @@ 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.
 
 ## Your Role in the Pipeline
 
-Executor agents built each task and wrote task summaries. You are the closer — verify the assembled work actually delivers the slice goal, then compress everything into a slice summary. After you finish, a **reassess-roadmap agent** reads your slice summary to decide if the remaining roadmap still makes sense. The slice summary is also the primary record of what this slice achieved — future slice researchers and planners read it as a dependency summary when their work builds on yours.
-
-Write the summary for those downstream readers. What did this slice actually deliver? What patterns did it establish? What should the next slice know?
-
-All relevant context has been preloaded below — the slice plan, all task summaries, and the milestone roadmap are inlined. Start working immediately without re-reading these files.
+You are the closer: verify assembled task work delivers the slice goal, then compress it into a downstream-ready slice summary and UAT.
 
 {{inlinedContext}}
 
 {{gatesToClose}}
 
-**Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
-
-### Delegate Review Work
-
-This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+Match effort to complexity. Simple 1-2 task slices need brief summary and lightweight verification; multi-subsystem slices need stronger verification and more detail.
 
-- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
-- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
-- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+Use `subagent` only for fresh-context review when useful: reviewer for cross-cutting code/new abstractions, security for auth/network/parsing/file IO/shell/crypto, tester for coverage gaps. Subagents report; you apply findings before completion.
 
-Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_slice_complete` with `milestoneId` and `sliceId`.
+## Completion Rules
 
-Then:
-1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
+1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-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. Task artifacts use a **flat file layout** directly inside `tasks/` (for example `T01-SUMMARY.md`, `T02-SUMMARY.md`) rather than per-task subdirectories. If you need to count or re-read task summaries during verification, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never use `tasks/*/SUMMARY.md` — that glob expects subdirectories that do not exist.
-4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. Address every gate listed in the **Gates to Close** section above — each gate maps to a specific slice-summary section the handler inspects (for example, Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, and monitoring gaps). Leaving a section empty records the gate as `omitted`.
-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. Prepare the slice completion content you will pass to `gsd_slice_complete` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
-8. Draft the UAT content you will pass as `uatContent` — 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. Fill the `UAT Type` and `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven (e.g. live integration paths, performance under load, scenarios deferred to a later slice).
-9. Review task summaries for `key_decisions`. For each significant decision, call `capture_thought` with `category: "architecture"` (or `"pattern"`) and a `structuredFields` payload of `{ scope, decision, choice, rationale, made_by: "agent", revisable }`.
-10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. For each one that would save future agents from repeating investigation, call `capture_thought` with the matching category (`gotcha`, `convention`, `pattern`, `environment`). The memory store is the single source of truth (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
-11. Call `gsd_slice_complete` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.
-12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
-
-**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 slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
-
-**File system safety:** Task summaries are preloaded in the inlined context above. Task artifacts use a **flat file layout** — files such as `T01-SUMMARY.md` and `T02-SUMMARY.md` live directly inside the `tasks/` directory, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first. Never use `tasks/*/SUMMARY.md`, and never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
-
-**You MUST call `gsd_slice_complete` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
+3. Run all slice-level verification checks from the slice plan. Fix failures before marking done; refresh current state if needed.
+4. Task summaries use a flat file layout under `tasks/` such as `T01-SUMMARY.md`, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. Never use `tasks/*/SUMMARY.md`.
+5. If observability/diagnostics were planned, verify them unless the slice is simple.
+6. Address every gate in Gates to Close. Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, monitoring gaps. Empty sections are recorded as omitted.
+7. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
+8. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
+9. Draft concrete UAT with preconditions, numbered steps, expected outcomes, edge cases, UAT Type, and Not Proven By This UAT.
+10. Review task summaries for DECISIONS.md and KNOWLEDGE.md-worthy decisions, patterns, and gotchas. Capture significant items with `capture_thought`; do not append knowledge files directly.
+11. Call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes; the tool renders files and updates projections.
+12. Do not run git commands.
+13. Update `.gsd/PROJECT.md` with a full `write` only if the current project state needs refresh.
+
+**Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
+
+**File system safety:** if re-reading task summaries, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never pass `{{slicePath}}` or any directory path directly to the `read` tool.
+
+**You MUST call `gsd_slice_complete` with summary and UAT content before finishing.**
 
 When done, say: "Slice {{sliceId}} complete."

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

@@ -1,6 +1,6 @@
 # Headless Milestone Creation
 
-You are creating a GSD milestone from a provided specification document. This is a **headless** (non-interactive) flow — do NOT ask the user any questions. Wherever the interactive flow would ask the user, make your best-judgment call and document it as an assumption.
+You are creating a GSD milestone from a provided specification document. This is a **headless** flow: do NOT ask the user questions. Wherever the interactive flow would ask, make your best judgment and document it as an assumption.
 
 ## Provided Specification
 
@@ -8,12 +8,11 @@ You are creating a GSD milestone from a provided specification document. This is
 
 ## Reflection Step
 
-Summarize your understanding of the specification concretely — not abstractly:
-
-1. Summarize what is being built in your own words.
-2. Give an honest size read: roughly how many milestones, roughly how many slices in the first one. Base this on the actual work involved, not a classification label.
-3. Include scope honesty — a bullet list of the major capabilities: "Here's what I'm reading from the spec: [bullet list of major capabilities]."
-4. Note any ambiguities, gaps, or areas where the spec is vague.
+Summarize your concrete understanding of the specification:
+1. What is being built, in your own words.
+2. Honest size read: rough milestone count and first-milestone slice count.
+3. Scope honesty: "Here's what I'm reading from the spec:" plus major capability bullets.
+4. Ambiguities, gaps, or vague areas.
 
 Print this reflection in chat. Do not skip this step.
 
@@ -21,47 +20,35 @@ Print this reflection in chat. Do not skip this step.
 
 Decide the approach based on the actual scope:
 
-**If the work spans multiple milestones:** Map the full landscape:
-1. Propose a milestone sequence — names, one-line intents, rough dependencies
-2. Print this in chat as the working milestone sequence
+**If the work spans multiple milestones:** map the landscape:
+1. Propose milestone names, one-line intents, and rough dependencies.
+2. Print this as the working milestone sequence.
 
 **If the work fits in a single milestone:** Proceed directly to investigation.
 
-**Anti-reduction rule:** If the spec describes a big vision, plan the big vision. Do not reduce scope. Phase complex/risky work into later milestones — do not cut it. The spec's ambition is the target, and your job is to sequence it intelligently, not shrink it.
+**Anti-reduction rule:** If the spec describes a big vision, plan it. Do not reduce scope; phase complex/risky work into later milestones. Sequence intelligently instead of shrinking ambition.
 
 ## Mandatory Investigation
 
-Do a mandatory investigation pass before making any decisions. This is not optional.
-
-1. **Scout the codebase** — `ls`, `find`, `rg`, or `scout` for broad unfamiliar areas. Understand what already exists, what patterns are established, what constraints current code imposes.
-2. **Check library docs** — `resolve_library` / `get_library_docs` for any tech mentioned in the spec. Get current facts about capabilities, constraints, API shapes, version-specific behavior.
-3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the spec references external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
-
-**Web search budget:** Budget carefully across investigation + focused research:
-- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation.
-- Prefer `search_and_read` for one-shot topic research.
-- Target 2-3 web searches in this investigation pass. Save remaining budget for focused research.
-- Do NOT repeat the same or similar queries.
+Investigate before making decisions:
+1. Scout relevant code with `ls`, `find`, `rg`, or `scout`.
+2. Check mentioned tech with `resolve_library` / `get_library_docs`.
+3. Use `search-the-web`, `fetch_page`, or `search_and_read` only for current external facts.
 
-The goal: your decisions should reflect what's actually true in the codebase and ecosystem, not what you assume.
+Budget searches across investigation and focused research. Prefer library docs and one-shot `search_and_read`; avoid repeat queries. Decisions must reflect codebase and ecosystem evidence.
 
 ## Autonomous Decision-Making
 
-For every area where the spec is ambiguous, vague, or silent:
-
-- Apply the depth checklist (below) to identify what needs resolution
-- Make your best-judgment call based on: the spec's intent, codebase patterns, domain conventions, and investigation findings
-- **Document every assumption** in the Context file under an "Assumptions" section
-- For each assumption, note: what the spec said (or didn't say), what you decided, and why
+For every ambiguous, vague, or silent area, apply the depth checklist, make the smallest sound judgment from spec intent, codebase patterns, domain conventions, and investigation findings, and Document every assumption in CONTEXT.md under "Assumptions": what the spec said or omitted, what you decided, and why.
 
 ### Depth Checklist
 
-Ensure ALL of these are resolved before writing artifacts — from the spec + investigation, not by asking:
+Resolve all of these from the spec and investigation before writing artifacts:
 
-- [ ] **What is being built** — concrete enough that you could explain it to a stranger
+- [ ] **What is being built** — concrete enough to explain to a stranger
 - [ ] **Why it needs to exist** — the problem it solves or the desire it fulfills
 - [ ] **Who it's for** — even if just the spec author
-- [ ] **What "done" looks like** — observable outcomes, not abstract goals
+- [ ] **What "done" looks like** — observable outcomes
 - [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
 - [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
 
@@ -75,22 +62,11 @@ Print a structured depth summary in chat covering:
 - Assumptions you made and why
 - Areas where you're least confident
 
-This is your audit trail. Print it — do not skip it.
+This is the audit trail. Print it.
 
 ## Focused Research
 
-Do a focused research pass before roadmap creation.
-
-Research is advisory, not auto-binding. Use the spec + investigation to identify:
-- table stakes the product space usually expects
-- domain-standard behaviors that may be implied but not stated
-- likely omissions that would make the product feel incomplete
-- plausible anti-features or scope traps
-- differentiators worth preserving
-
-For multi-milestone visions, research should cover the full landscape, not just the first milestone. Research findings may affect milestone sequencing, not just slice ordering within M001.
-
-**Key difference from interactive flow:** Where the interactive flow would present research-surfaced candidate requirements for the user to confirm/defer/reject, you instead apply your best judgment. If a research finding clearly aligns with the spec's intent, include it. If it's tangential or would expand scope beyond what the spec describes, defer it or mark it out of scope. Document the reasoning.
+Do focused research before roadmap creation. Research is advisory, not auto-binding. Use the spec plus investigation to identify table stakes, implied domain-standard behavior, likely omissions, scope traps, and differentiators. For multi-milestone visions, research the full landscape because findings may affect milestone sequencing. Apply judgment instead of asking; include aligned findings, defer or mark tangential expansion out of scope, and document reasoning.
 
 ## Capability Contract
 
@@ -98,67 +74,45 @@ Before writing a roadmap, produce `.gsd/REQUIREMENTS.md`.
 
 Use it as the project's explicit capability contract.
 
-Requirements must be organized into:
-- Active
-- Validated
-- Deferred
-- Out of Scope
-- Traceability
-
-Each requirement should include:
-- stable ID (`R###`)
-- title
-- class
-- status
-- description
-- why it matters
-- source (`spec`, `inferred`, `research`, or `execution`)
-- primary owning slice
-- supporting slices
-- validation status
-- notes
+Requirements must be organized into Active, Validated, Deferred, Out of Scope, and Traceability.
+
+Each requirement includes stable ID (`R###`), title, class, status, description, why it matters, source (`spec`, `inferred`, `research`, or `execution`), primary owning slice, supporting slices, validation status, and notes.
 
 Rules:
-- Keep requirements capability-oriented, not a giant feature inventory
+- Keep requirements capability-oriented, not a feature inventory
 - Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
 - Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
 - Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible
 
-For multi-milestone projects, requirements should span the full vision. Requirements owned by later milestones get provisional ownership. The full requirement set captures the spec's complete vision — milestones are the sequencing strategy, not the scope boundary.
+For multi-milestone projects, requirements span the full vision. Later milestones get provisional ownership; milestones sequence scope, not shrink it.
 
 **Print the requirements in chat before writing the roadmap.** Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope).
 
 ## Scope Assessment
 
-Confirm the size estimate from your reflection still holds. Investigation and research often reveal hidden complexity or simplify things. If the scope grew or shrank significantly, adjust the milestone and slice counts accordingly.
+Confirm the reflection size estimate still holds. If investigation/research changes scope significantly, adjust milestone and slice counts.
 
 ## Output Phase
 
 ### Roadmap Preview
 
-Before writing any files, **print the planned roadmap in chat**. 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.
-
-This is the user's audit trail in the TUI scrollback — do not skip it.
+Before writing files, **print the planned roadmap in chat**: markdown table with Slice, Title, Risk, Depends, Demo. Below it, print milestone definition of done bullets. This is the user's TUI audit trail; do not skip it.
 
 ### Naming Convention
 
-Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
-- Milestone dir: `.gsd/milestones/{{milestoneId}}/`
-- Milestone files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`
-- Slice dirs: `S01/`, `S02/`, etc.
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside content, not names. Milestone dir: `.gsd/milestones/{{milestoneId}}/`; files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`; slice dirs: `S01/`, `S02/`, etc.
 
 ### Single Milestone
 
 In a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
 2. 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.
+3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm states, ownership, and traceability before roadmap creation.
 
-**Depth-Preservation Guidance for context.md:**
-Preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. If the spec said "craft feel," write "craft feel" — not "high-quality user experience." The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
+**Depth-Preservation Guidance for context.md:** Preserve the specification's exact terminology, emphasis, and framing. Do not flatten domain-specific language into generics. CONTEXT.md is downstream agents' only window into this spec.
 
-4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during research. Include an "Assumptions" section documenting every judgment call.
-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.
+4. Write `{{contextPath}}` from the **Context** template. Preserve risks, unknowns, codebase constraints, integration points, relevant requirements, and an "Assumptions" section.
+5. Call `gsd_plan_milestone` to create demoable vertical slices with risk, depends, demo, proof strategy, verification classes, definition of done, requirement coverage, and boundary map. If crossing runtime boundaries, include a final end-to-end integration slice. Use the **Roadmap** output template below.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
@@ -173,7 +127,7 @@ Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
 If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
 
-Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
 
 After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
@@ -181,7 +135,7 @@ After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} read
 
 #### 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` for each.
+1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. 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, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
@@ -189,11 +143,11 @@ After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} read
 #### Phase 2: Primary milestone
 
 5. Write a full `CONTEXT.md` for the primary milestone (the first in sequence). Include an "Assumptions" section.
-6. Call `gsd_plan_milestone` for **only the primary milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
+6. Call `gsd_plan_milestone` for **only the primary milestone**; detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and definition of done.
 
 #### MANDATORY: depends_on Frontmatter in CONTEXT.md
 
-Every CONTEXT.md for a milestone that depends on other milestones MUST have YAML frontmatter with `depends_on`. 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.
+Every CONTEXT.md for a milestone that depends on other milestones MUST have YAML frontmatter with `depends_on`. Auto-mode reads this for execution order.
 
 ```yaml
 ---
@@ -203,24 +157,24 @@ depends_on: [M001, M002]
 # M003: Title
 ```
 
-If a milestone has no dependencies, omit the frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking — the state machine only reads CONTEXT.md frontmatter.
+If a milestone has no dependencies, omit frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking; the state machine reads CONTEXT.md frontmatter only.
 
 #### Phase 3: Remaining milestones
 
-For each remaining milestone, in dependency order, autonomously decide the best readiness mode:
+For each remaining milestone, in dependency order, autonomously decide the readiness mode:
 
-- **Write full context** — if the spec provides enough detail for this milestone and investigation confirms feasibility. Write a full `CONTEXT.md` with technical assumptions verified against the actual codebase.
+- **Write full context** — if the spec provides enough detail and investigation confirms feasibility. Write full `CONTEXT.md` with technical assumptions verified against actual code.
 - **Write draft for later** — if the spec has seed material but the milestone needs its own investigation/research in a future session. Write a `CONTEXT-DRAFT.md` capturing seed material, key ideas, provisional scope, and open questions. **Downstream:** Auto-mode pauses at this milestone and prompts the user to discuss.
 - **Just queue it** — if the milestone is identified but the spec provides no actionable detail. No context file written. **Downstream:** Auto-mode pauses and starts a full discussion from scratch.
 
-**Default to writing full context** when the spec is detailed enough. Default to draft when the spec mentions the milestone but is vague. Default to queue when the milestone is implied by the vision but not described.
+**Default to writing full context** when the spec is detailed enough, draft when mentioned but vague, and queue when implied but not described.
 
 **Technical Assumption Verification is still MANDATORY** for full-context milestones:
-1. Read the actual code for every file or module you reference. Confirm APIs exist, check what functions actually do.
-2. Check for stale assumptions — verify referenced modules still work as described.
-3. Print findings in chat before writing each milestone's CONTEXT.md.
+1. Read actual code for every referenced file or module.
+2. Check stale assumptions against current behavior.
+3. Print findings before writing each milestone's CONTEXT.md.
 
-Each context file (full or draft) should be rich enough that a future agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.
+Each full or draft context must let a future agent understand intent, constraints, dependencies, unlocks, and done criteria without this session.
 
 #### Milestone Gate Tracking (MANDATORY for multi-milestone)
 
@@ -239,7 +193,7 @@ After deciding each milestone's readiness, immediately write or update `.gsd/DIS
 }
 ```
 
-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`.
+Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. The system BLOCKS auto-start if `gates_completed < total`.
 
 For single-milestone projects, do NOT write this file.
 
@@ -259,7 +213,7 @@ Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
 If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
 
-Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+Do not announce the ready phrase as something you are "about to" do. The ready phrase is a post-write signal, not an intent signal.
 
 After completing every step above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
@@ -268,12 +222,12 @@ After completing every step above, say exactly: "Milestone {{milestoneId}} ready
 - **DO NOT ask the user any questions** — this is headless mode. Make judgment calls and document them.
 - **Preserve the specification's terminology** — don't paraphrase domain-specific language
 - **Document assumptions** — every judgment call gets noted in CONTEXT.md under "Assumptions" with reasoning
-- **Investigate thoroughly** — scout codebase, check library docs, web search. Same rigor as interactive mode.
-- **Do focused research** — identify table stakes, domain standards, omissions, scope traps. Same rigor as interactive mode.
+- **Investigate thoroughly** — scout codebase, check library docs, and web search with the same rigor as interactive mode.
+- **Do focused research** — identify table stakes, domain standards, omissions, and scope traps.
 - **Use proper tools** — `gsd_plan_milestone` for roadmaps, `gsd_decision_save` for decisions, `gsd_milestone_generate_id` for IDs
 - **Print artifacts in chat** — requirements table, roadmap preview, depth summary. The TUI scrollback is the user's audit trail.
 - **Use depends_on frontmatter** for multi-milestone sequences
-- **Anti-reduction rule** — if the spec describes a big vision, plan the big vision. Phase complexity — don't cut it.
+- **Anti-reduction rule** — if the spec describes a big vision, plan it. Phase complexity; do not cut it.
 - **Naming convention** — always use `gsd_milestone_generate_id` for IDs. Directories use bare IDs, files use ID-SUFFIX format.
 - **End with "Milestone {{milestoneId}} ready."** — this triggers auto-start detection