gsd-pi 2.5.0 → 2.5.1

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

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import type { GitPreferences } from "./git-service.ts";
+import { VALID_BRANCH_NAME } from "./git-service.ts";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
 const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
@@ -639,6 +640,13 @@ function validatePreferences(preferences: GSDPreferences): {
         errors.push(`git.commit_type must be one of: feat, fix, refactor, docs, test, chore, perf, ci, build, style`);
       }
     }
+    if (g.main_branch !== undefined) {
+      if (typeof g.main_branch === "string" && g.main_branch.trim() !== "" && VALID_BRANCH_NAME.test(g.main_branch)) {
+        git.main_branch = g.main_branch;
+      } else {
+        errors.push("git.main_branch must be a valid branch name (alphanumeric, _, -, /, .)");
+      }
+    }
 
     if (Object.keys(git).length > 0) {
       validated.git = git as GitPreferences;

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

@@ -6,17 +6,19 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 {{inlinedContext}}
 
+**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.
+
 Then:
 1. Read the templates:
    - `~/.gsd/agent/extensions/gsd/templates/slice-summary.md`
    - `~/.gsd/agent/extensions/gsd/templates/uat.md`
 2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
-4. Confirm the slice's observability/diagnostic surfaces are real and useful where relevant: status inspection works, failure state is externally visible, structured errors/logs are actionable, and hidden failures are not being mistaken for success.
-5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change. Surface any new candidate requirements discovered during execution instead of silently dropping them.
-6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries). Fill the requirement-related sections explicitly.
-7. Write `{{sliceUatAbsPath}}`. Fill the new `UAT Type`, `Requirements Proved By This UAT`, and `Not Proven By This UAT` sections explicitly.
-8. Review task summaries for `key_decisions`. Ensure any significant architectural, pattern, or observability decisions are in `.gsd/DECISIONS.md`. If any are missing, append them now.
+4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
+5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
+6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries).
+7. Write `{{sliceUatAbsPath}}`.
+8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
 10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
 11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.

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

@@ -9,7 +9,7 @@ Special handling: if the user message is not a project description (for example,
 After the user describes their idea, **do not ask questions yet**. First, prove you understood by reflecting back:
 
 1. Summarize what you understood in your own words — concretely, not abstractly.
-2. Include a complexity/scale read: "This sounds like [task/project/product] scale — roughly N milestone(s)."
+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. A config change might be 1 milestone with 1 slice. A social network might be 5 milestones with 8+ slices each. Use your judgment.
 3. Include scope honesty — a bullet list of the major capabilities you're hearing: "Here's what I'm hearing: [bullet list of major capabilities]."
 4. Ask: "Did I get that right, or did I miss something?" — plain text, not `ask_user_questions`. Let them correct freely.
 
@@ -17,18 +17,14 @@ This prevents runaway questioning by forcing comprehension proof before anything
 
 ## Vision Mapping
 
-After reflection is confirmed, classify the scale:
+After reflection is confirmed, decide the approach based on the actual scope — not a label:
 
-- **Task** — a focused piece of work (single milestone, few slices)
-- **Project** — a coherent product with multiple major capabilities (multi-milestone likely)
-- **Product/Platform** — a large vision with distinct phases, audiences, or systems (definitely multi-milestone)
-
-**For Project or Product/Platform scale:** Before drilling into details, map the full landscape:
+**If the work spans multiple milestones:** Before drilling into details, map the full landscape:
 1. Propose a milestone sequence — names, one-line intents, rough dependencies
 2. Present this to the user for confirmation or adjustment
 3. Only then begin the deep Q&A — and scope the Q&A to the full vision, not just M001
 
-**For Task scale:** Proceed directly to questioning.
+**If the work fits in a single milestone:** Proceed directly to questioning.
 
 **Anti-reduction rule:** If the user describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or try to reduce scope unless the user explicitly asks for an MVP or minimal version. When something is complex or risky, phase it into a later milestone — do not cut it. The user's ambition is the target, and your job is to sequence it intelligently, not shrink it.
 
@@ -77,15 +73,13 @@ Do NOT offer to proceed until ALL of the following are satisfied. Track these in
 - [ ] **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
 
-**Minimum round counts before the wrap-up gate is allowed:**
-- **Task scale:** at least 2 full rounds (6+ questions asked and answered)
-- **Project/Product scale:** at least 4 full rounds (12+ questions asked and answered)
+**Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work.
 
 Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
 
 ## Wrap-up Gate
 
-Only after the depth checklist is fully satisfied AND minimum rounds are hit, offer to proceed.
+Only after the depth checklist is fully satisfied and you genuinely understand the work, offer to proceed.
 
 The wrap-up gate must include a scope reflection:
 "Here's what I'm planning to build: [list of capabilities with rough complexity]. Does this match your vision, or did I miss something?"
@@ -149,9 +143,7 @@ If the project is new or has no `REQUIREMENTS.md`, confirm candidate requirement
 
 ## Scope Assessment
 
-Confirm the scale assessment from Vision Mapping still holds after discussion. If the scope grew or shrank significantly during Q&A, adjust the milestone count accordingly.
-
-If Vision Mapping classified the work as Task but discussion revealed Project-scale complexity, upgrade to multi-milestone and propose the split. If Vision Mapping classified it as Project but the scope narrowed to a single coherent body of work (roughly 2-12 slices), downgrade to single-milestone.
+Before moving to output, confirm the size estimate from your reflection still holds. Discussion often reveals hidden complexity or simplifies things. If the scope grew or shrank significantly during Q&A, adjust the milestone and slice counts accordingly. Be honest — if something you thought was multi-milestone turns out to be 3 slices, plan 3 slices. If something you thought was simple turns out to need multiple milestones, say so.
 
 ## Output Phase
 

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

@@ -24,11 +24,7 @@ Then:
 2. Execute the steps in the inlined task plan
 3. 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.
 4. 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).
-5. When implementing non-trivial runtime behavior, add or preserve agent-usable observability:
-   - Prefer structured logs/events, stable error codes/types, and explicit status surfaces over ad hoc console text
-   - Ensure failures are externally inspectable rather than swallowed or hidden
-   - Persist high-value failure state when it materially improves retries, recovery, or later debugging
-   - Never log secrets, tokens, or sensitive raw payloads unnecessarily
+5. 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.
 6. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors)
 7. 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.
 8. If the task touches UI, browser flows, DOM behavior, or user-visible web state:
@@ -38,7 +34,7 @@ Then:
    - 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
-9. If observability or diagnostics were part of this task's scope, verify them directly — e.g. structured errors, status inspection, health endpoints, persisted failure state, browser/network diagnostics, or equivalent.
+9. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section.
 10. **If execution is running long or verification fails:**
 
     **Context budget:** 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.

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

@@ -21,3 +21,7 @@ Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md`
 - **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
 - **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
 - **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
+
+## Secret Forecasting
+
+After writing the roadmap, analyze the slices and their boundary maps for external service dependencies (third-party APIs, SaaS platforms, cloud providers, databases requiring credentials, OAuth providers, etc.). If this milestone requires any external API keys or secrets, read the template at `~/.gsd/agent/extensions/gsd/templates/secrets-manifest.md` for the expected format and write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with the Service name, a direct Dashboard URL to the console page where the key is created, a Format hint showing what the key looks like, Status set to `pending`, and Destination (`dotenv`, `vercel`, or `convex`). Include numbered step-by-step guidance for obtaining each key. If this milestone does not require any external API keys or secrets, skip this step entirely — do not create an empty manifest.

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

@@ -12,7 +12,7 @@ Then:
 1. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md`
 2. Read `.gsd/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract.
 3. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting
-4. Create the roadmap: decompose into demoable vertical slices — as many as the work needs, no more
+4. 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.
 5. Order by risk (high-risk first)
 6. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. 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
 7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet)
@@ -43,6 +43,38 @@ Apply these when decomposing and ordering slices:
 - **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
 - **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
 - **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
+- **Right-size the decomposition.** Match slice count to actual complexity. If the work is small enough to build and verify in one pass, it's one slice — don't split it into three just because you can identify sub-steps. Multiple requirements can share a single slice. Conversely, don't cram genuinely independent capabilities into one slice just to keep the count low. Let the work dictate the structure.
+
+## Single-Slice Fast Path
+
+If the roadmap has only one slice, also write the slice plan and task plans inline during this unit — don't leave them for a separate planning session.
+
+1. Read the templates:
+   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
+   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
+2. `mkdir -p {{milestonePath}}/slices/S01/tasks`
+3. Write the S01 plan file at `{{milestonePath}}/slices/S01/S01-PLAN.md`
+4. Write individual task plans at `{{milestonePath}}/slices/S01/tasks/T01-PLAN.md`, etc.
+5. For simple slices, keep the plan lean — omit Proof Level, Integration Closure, and Observability sections if they would all be "none". Executable verification commands are sufficient.
+
+This eliminates a separate research-slice + plan-slice cycle when the work is straightforward.
+
+## Secret Forecasting
+
+After writing the roadmap, analyze the slices and their boundary maps for external service dependencies (third-party APIs, SaaS platforms, cloud providers, databases requiring credentials, OAuth providers, etc.).
+
+If this milestone requires any external API keys or secrets:
+
+1. Read the template at `~/.gsd/agent/extensions/gsd/templates/secrets-manifest.md` for the expected format
+2. Write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with:
+   - **Service** — the external service name
+   - **Dashboard** — direct URL to the console/dashboard page where the key is created (not a generic homepage)
+   - **Format hint** — what the key looks like (e.g. `sk-...`, `ghp_...`, 40-char hex, UUID)
+   - **Status** — always `pending` during planning
+   - **Destination** — `dotenv`, `vercel`, or `convex` depending on where the key will be consumed
+   - Numbered step-by-step guidance for obtaining the key (navigate to dashboard → create project → generate key → copy)
+
+If this milestone does not require any external API keys or secrets, skip this step entirely — do not create an empty manifest.
 
 **You MUST write the file `{{outputAbsPath}}` before finishing.**
 

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

@@ -12,7 +12,9 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 {{dependencySummaries}}
 
-Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why.
+Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. Keep the narration proportional to the work — a simple slice doesn't need a long justification.
+
+**Right-size the plan.** If the slice is simple enough to be 1 task, plan 1 task. Don't split into multiple tasks just because you can identify sub-steps. Don't fill in sections with "None" when the section doesn't apply — omit them entirely. The plan's job is to guide execution, not to fill a template.
 
 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.
@@ -20,43 +22,33 @@ Then:
    - `~/.gsd/agent/extensions/gsd/templates/plan.md`
    - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
 2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting
-3. Define slice-level verification first — the objective stopping condition for this slice:
-   - For non-trivial slices: plan actual test files with real assertions. Name the files. The first task creates them (initially failing). Remaining tasks make them pass.
+3. Define slice-level verification — the objective stopping condition for this slice:
+   - For non-trivial slices: plan actual test files with real assertions. Name the files.
    - For simple slices: executable commands or script assertions are fine.
    - If the project is non-trivial and has no test framework, the first task should set one up.
    - If this slice establishes a boundary contract, verification must exercise that contract.
-4. Plan observability and diagnostics explicitly:
-   - For non-trivial backend, integration, async, stateful, or UI slices, include an `Observability / Diagnostics` section in the slice plan.
-   - Define how a future agent will inspect state, detect failure, and localize the problem.
-   - Prefer structured logs/events, stable error codes/types, status surfaces, and persisted failure state over ad hoc debug text.
-   - Include at least one verification check for a diagnostic or failure-path signal when relevant.
-5. Fill the `Proof Level` and `Integration Closure` sections truthfully:
-   - State whether the slice proves contract, integration, operational, or final-assembly behavior.
-   - Say whether real runtime or human/UAT is required.
-   - Name the wiring introduced in this slice and what still remains before the milestone is truly usable end-to-end.
-6. Decompose the slice into tasks, each fitting one context window
-7. Every task in the slice plan should be written as an executable increment with:
+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.
+   - **Omit these sections entirely for simple slices** where they would all be "none" or trivially obvious.
+5. Decompose the slice into tasks, each fitting one context window. Each task needs:
    - a concrete, action-oriented title
    - the inline task entry fields defined in the plan.md template (Why / Files / Do / Verify / Done when)
-   - a matching task plan containing description, steps, must-haves, verification, observability impact, inputs, and expected output
-8. Each task needs: title, description, steps, must-haves, verification, observability impact, inputs, and expected output
-9. If verification includes test files, ensure the first task includes creating them with expected assertions (they should fail initially — that's correct)
-10. Write `{{outputPath}}`
-11. Write individual task plans in `{{sliceAbsPath}}/tasks/`: `T01-PLAN.md`, `T02-PLAN.md`, etc.
-12. **Self-audit the plan before continuing.** 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 at the claimed proof level. Do not allow a task plan that only scaffolds toward a future working state.
-    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned.
-    - **Task completeness:** Every task has steps, must-haves, verification, observability impact, inputs, and expected output — none are blank or vague.
+   - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
+   - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
+6. Write `{{outputPath}}`
+7. Write individual task plans in `{{sliceAbsPath}}/tasks/`: `T01-PLAN.md`, `T02-PLAN.md`, etc.
+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.
+    - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague.
     - **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 (component → API, API → database, form → handler), there is an explicit step that wires them — not just "create X" and "create Y" in separate tasks with no connection step.
-    - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 6–8 steps or 8–10 files is a warning — consider splitting. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
-    - **Context compliance:** If context/research artifacts or `.gsd/DECISIONS.md` exist, the plan honors locked decisions and doesn't include deferred or out-of-scope items.
-    - **Requirement coverage:** If `REQUIREMENTS.md` exists, every Active requirement this slice owns (per the roadmap) maps to at least one task with verification that proves the requirement is met. No owned requirement is left without a task. No task claims to satisfy a requirement that is Deferred or Out of Scope.
-    - **Proof honesty:** The `Proof Level` and `Integration Closure` sections match what this slice will actually prove, and they do not imply live end-to-end completion if only fixture or 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 (not a placeholder). If the slice has an API, at least one task connects it to a real data source (not hardcoded returns). If every task were completed and you showed the result to a non-technical stakeholder, they should see real product progress, not developer artifacts.
-13. If planning produced structural decisions (e.g. verification strategy, observability strategy, technology choices, patterns to follow), append them to `.gsd/DECISIONS.md`
-14. Commit: `docs({{sliceId}}): add slice plan`
-15. Update `.gsd/STATE.md`
+    - **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.
+9. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
+10. Commit: `docs({{sliceId}}): add slice plan`
+11. Update `.gsd/STATE.md`
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. You are on the slice branch; all work stays here.
 

package/src/resources/extensions/gsd/templates/plan.md

@@ -10,6 +10,8 @@
 
 ## Proof Level
 
+<!-- Omit this section entirely for simple slices where the answer is trivially obvious. -->
+
 - This slice proves: {{contract | integration | operational | final-assembly}}
 - Real runtime required: {{yes/no}}
 - Human/UAT required: {{yes/no}}
@@ -41,17 +43,11 @@
 
 ## Observability / Diagnostics
 
-<!-- Required for non-trivial backend, integration, async, stateful, or UI slices.
-     Describe how a future agent will inspect current state, detect failure,
-     and localize the problem with minimal ambiguity.
-
-     Prefer:
-     - structured logs/events over ad hoc console strings
-     - stable error codes/types over vague failures
-     - health/readiness/status surfaces over hidden internal state
-     - persisted failure state when it materially improves retries or recovery
+<!-- Include this section for non-trivial backend, integration, async, stateful, or UI slices.
+     OMIT ENTIRELY for simple slices where all fields would be "none".
 
-     Keep this section concise and high-signal. Do not log secrets or sensitive raw payloads. -->
+     When included, describe how a future agent will inspect current state, detect failure,
+     and localize the problem with minimal ambiguity. Keep it concise and high-signal. -->
 
 - Runtime signals: {{structured log/event, state transition, metric, or none}}
 - Inspection surfaces: {{status endpoint, CLI command, script, UI state, DB table, or none}}
@@ -60,6 +56,8 @@
 
 ## Integration Closure
 
+<!-- Omit this section entirely for simple slices with no meaningful integration concerns. -->
+
 - Upstream surfaces consumed: {{specific files / modules / contracts}}
 - New wiring introduced in this slice: {{entrypoint / composition / runtime hookup, or none}}
 - What remains before the milestone is truly usable end-to-end: {{list or "nothing"}}

package/src/resources/extensions/gsd/templates/secrets-manifest.md

@@ -0,0 +1,22 @@
+# Secrets Manifest
+
+<!-- This file lists predicted API keys and secrets for the milestone.
+     Each H3 section defines one secret with setup guidance.
+     The parser extracts entries by H3 heading (the env var name).
+     Bold fields: Service, Dashboard, Format hint, Status, Destination.
+     Guidance is a numbered list under each entry. -->
+
+**Milestone:** {{milestone}}
+**Generated:** {{generatedAt}}
+
+### {{ENV_VAR_NAME}}
+
+**Service:** {{serviceName}}
+**Dashboard:** {{dashboardUrl}}
+**Format hint:** {{formatHint}}
+**Status:** pending
+**Destination:** dotenv
+
+1. {{Step 1 guidance}}
+2. {{Step 2 guidance}}
+3. {{Step 3 guidance}}

package/src/resources/extensions/gsd/templates/task-plan.md

@@ -32,13 +32,13 @@ estimated_files: {{estimatedFiles}}
 
 ## Observability Impact
 
-<!-- If this task creates or changes a runtime boundary, async flow, API, UI state,
-     background process, or error path, explain how it improves or depends on
-     future agent observability. Use "None" when genuinely not applicable. -->
+<!-- OMIT THIS SECTION ENTIRELY for simple tasks that don't touch runtime boundaries,
+     async flows, APIs, background processes, or error paths.
+     Include it only when the task meaningfully changes how failures are detected or diagnosed. -->
 
-- Signals added/changed: {{structured logs, statuses, errors, metrics, or None}}
-- How a future agent inspects this: {{command, endpoint, file, UI state, or None}}
-- Failure state exposed: {{what becomes visible on failure, or None}}
+- Signals added/changed: {{structured logs, statuses, errors, metrics}}
+- How a future agent inspects this: {{command, endpoint, file, UI state}}
+- Failure state exposed: {{what becomes visible on failure}}
 
 ## Inputs
 

package/src/resources/extensions/gsd/tests/git-service.test.ts

@@ -7,6 +7,7 @@ import {
   inferCommitType,
   GitServiceImpl,
   RUNTIME_EXCLUSION_PATHS,
+  VALID_BRANCH_NAME,
   runGit,
   type GitPreferences,
   type CommitOptions,
@@ -1230,6 +1231,68 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ─── VALID_BRANCH_NAME regex ──────────────────────────────────────────
+
+  console.log("\n=== VALID_BRANCH_NAME regex ===");
+
+  {
+    // Valid branch names
+    assert(VALID_BRANCH_NAME.test("main"), "VALID_BRANCH_NAME accepts 'main'");
+    assert(VALID_BRANCH_NAME.test("master"), "VALID_BRANCH_NAME accepts 'master'");
+    assert(VALID_BRANCH_NAME.test("develop"), "VALID_BRANCH_NAME accepts 'develop'");
+    assert(VALID_BRANCH_NAME.test("feature/foo"), "VALID_BRANCH_NAME accepts 'feature/foo'");
+    assert(VALID_BRANCH_NAME.test("release-1.0"), "VALID_BRANCH_NAME accepts 'release-1.0'");
+    assert(VALID_BRANCH_NAME.test("my_branch"), "VALID_BRANCH_NAME accepts 'my_branch'");
+    assert(VALID_BRANCH_NAME.test("v2.0.1"), "VALID_BRANCH_NAME accepts 'v2.0.1'");
+
+    // Invalid / injection attempts
+    assert(!VALID_BRANCH_NAME.test("main; rm -rf /"), "VALID_BRANCH_NAME rejects shell injection");
+    assert(!VALID_BRANCH_NAME.test("main && echo pwned"), "VALID_BRANCH_NAME rejects && injection");
+    assert(!VALID_BRANCH_NAME.test(""), "VALID_BRANCH_NAME rejects empty string");
+    assert(!VALID_BRANCH_NAME.test("branch name"), "VALID_BRANCH_NAME rejects spaces");
+    assert(!VALID_BRANCH_NAME.test("branch`cmd`"), "VALID_BRANCH_NAME rejects backticks");
+    assert(!VALID_BRANCH_NAME.test("branch$(cmd)"), "VALID_BRANCH_NAME rejects $() subshell");
+  }
+
+  // ─── getMainBranch: configured main_branch preference ──────────────────
+
+  console.log("\n=== getMainBranch: configured main_branch ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, { main_branch: "trunk" });
+
+    assertEq(svc.getMainBranch(), "trunk", "getMainBranch returns configured main_branch preference");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── getMainBranch: falls back to auto-detection when not set ──────────
+
+  console.log("\n=== getMainBranch: fallback to auto-detection ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, {});
+
+    assertEq(svc.getMainBranch(), "main", "getMainBranch falls back to auto-detection when main_branch not set");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── getMainBranch: ignores invalid branch names ───────────────────────
+
+  console.log("\n=== getMainBranch: ignores invalid branch name ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, { main_branch: "main; rm -rf /" });
+
+    assertEq(svc.getMainBranch(), "main", "getMainBranch ignores invalid branch name and falls back to auto-detection");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
   // ─── PreMergeCheckResult type export compile check ─────────────────────
 
   console.log("\n=== PreMergeCheckResult type export ===");