diff --git a/.gsd/DECISIONS.md b/.gsd/DECISIONS.md
new file mode 100644
index 000000000..a5e6d73e2
--- /dev/null
+++ b/.gsd/DECISIONS.md
@@ -0,0 +1,17 @@
+# Decisions Register
+
+<!-- Append-only. Never edit or remove existing rows.
+     To reverse a decision, add a new row that supersedes it.
+     Read this file at the start of any planning or research phase. -->
+
+| # | When | Scope | Decision | Choice | Rationale | Revisable? |
+|---|------|-------|----------|--------|-----------|------------|
+| D001 | M001/S01 | arch | Exclusion filter for smart staging | Not file ownership tracking | Simpler, covers the use case | No |
+| D002 | M001/S01 | pattern | Thin facade pattern for worktree.ts migration | Preserve all exports, delegate to GitServiceImpl | Backward compatibility without breaking consumers | No |
+| D003 | M001/S01 | convention | Branch lifecycle after squash merge | Branches deleted after merge | Clean branch list, history preserved in squash commit | No |
+| D004 | M001/S01 | arch | Snapshot storage mechanism | Hidden refs (refs/gsd/snapshots/) not checkpoint commits | Invisible to normal git log, recoverable when needed | No |
+| D005 | M002 | arch | Secret guidance source | LLM-generated at planning time | No static database to maintain, adapts to any service | Yes — if accuracy becomes a problem |
+| D006 | M002 | arch | Secret collection timing | Up-front during planning only | Solves the primary blocking problem; existing fallback behavior unchanged | Yes — if missed secrets are frequent |
+| D007 | M002 | arch | Secret forecasting scope | Current milestone only | Later milestones may change; collect when planning each | Yes — if cross-milestone friction observed |
+| D008 | M002 | arch | Existing key handling | Silent skip (no confirmation) | Less friction on repeated runs | Yes — if users want to rotate keys |
+| D009 | M002 | arch | Destination detection | Infer from project context (vercel.json, convex/ dir) | User shouldn't specify — falls back to .env | No |
diff --git a/.gsd/PROJECT.md b/.gsd/PROJECT.md
new file mode 100644
index 000000000..c882ca740
--- /dev/null
+++ b/.gsd/PROJECT.md
@@ -0,0 +1,33 @@
+# Project
+
+## What This Is
+
+GSD (Get Shit Done) is a CLI coding agent harness built on pi. It provides a structured planning methodology — milestones, slices, tasks — with auto-mode that executes work autonomously via fresh LLM sessions per unit of work. Ships as the `gsd-pi` npm package.
+
+## Core Value
+
+Autonomous multi-session execution: the agent plans, executes, verifies, and advances through an entire milestone without human intervention, resuming cleanly from crashes and compaction.
+
+## Current State
+
+M001 complete — centralized all git mechanics into a deterministic `GitServiceImpl` class. Smart staging, conventional commit inference, merge guards, hidden snapshot refs, auto-push, and rich commit messages. All git operations route through the service; no raw git commands in LLM-facing prompts.
+
+The extension has a full auto-mode state machine (`auto.ts`), guided wizard flow (`guided-flow.ts`), prompt-based unit dispatch, crash recovery, metrics tracking, and a TUI dashboard overlay.
+
+## Architecture / Key Patterns
+
+- **Extension architecture:** GSD is a pi extension in `src/resources/extensions/gsd/`. Registers tools, hooks (`agent_end`), and commands (`/gsd`, `/gsd auto`).
+- **Auto-mode state machine:** `auto.ts` derives state from disk files, determines next unit type, creates fresh LLM sessions with focused prompts. Unit types: research-milestone, plan-milestone, research-slice, plan-slice, execute-task, complete-slice, complete-milestone, reassess-roadmap, replan-slice, run-uat.
+- **Prompt injection:** Each unit type has a `.md` prompt template in `prompts/`. Variables are interpolated by `prompt-loader.ts`.
+- **State derivation:** `state.ts` reads roadmap/plan files to determine phase and active work item. State is derived, not stored.
+- **Git service:** `git-service.ts` owns all git mechanics. `worktree.ts` is a thin facade for backward compatibility.
+- **Secret collection:** `get-secrets-from-user.ts` provides `secure_env_collect` tool with paged masked TUI input. Currently reactive (collects when asked), not proactive.
+
+## Capability Contract
+
+See `.gsd/REQUIREMENTS.md` for the explicit capability contract, requirement status, and coverage mapping.
+
+## Milestone Sequence
+
+- [x] M001: Deterministic GitService — Centralized all git mechanics into a single typed service
+- [ ] M002: Proactive Secret Management — Front-load API key collection during milestone planning so auto-mode runs uninterrupted
diff --git a/.gsd/REQUIREMENTS.md b/.gsd/REQUIREMENTS.md
new file mode 100644
index 000000000..499b0792c
--- /dev/null
+++ b/.gsd/REQUIREMENTS.md
@@ -0,0 +1,193 @@
+# Requirements
+
+This file is the explicit capability and coverage contract for the project.
+
+## Active
+
+### R001 — Secret forecasting during milestone planning
+- Class: core-capability
+- Status: active
+- Description: During milestone planning, the LLM analyzes the roadmap's slices and boundary map to predict which external services and API keys will be needed across the milestone. Produces a structured secrets manifest.
+- Why it matters: Without forecasting, auto-mode blocks hours into execution when it encounters a missing API key, wasting the user's time.
+- Source: user
+- Primary owning slice: M002/S01
+- Supporting slices: M002/S03
+- Validation: unmapped
+- Notes: Forecasting is LLM-generated at planning time, not from a static database.
+
+### R002 — Secrets manifest file persisted in .gsd/
+- Class: continuity
+- Status: active
+- Description: A secrets manifest file in `.gsd/milestones/M00x/M00x-SECRETS.md` tracks what keys are needed, what's been collected, per-key guidance, and collection status.
+- Why it matters: Enables referencing later (onboarding, new slices adding requirements), and lets auto-mode know what's already been collected.
+- Source: user
+- Primary owning slice: M002/S01
+- Supporting slices: M002/S02, M002/S03
+- Validation: unmapped
+- Notes: File format must be parseable by the auto-mode state machine.
+
+### R003 — LLM-generated step-by-step guidance per key
+- Class: primary-user-loop
+- Status: active
+- Description: Each forecasted secret includes LLM-generated guidance: the service name, dashboard URL, numbered navigation steps to find the key, and what the key format looks like.
+- Why it matters: Current `secure_env_collect` just shows the key name and an optional format hint. Users shouldn't have to search for where to find a key.
+- Source: user
+- Primary owning slice: M002/S01
+- Supporting slices: M002/S02
+- Validation: unmapped
+- Notes: Guidance quality depends on LLM knowledge of common services. Accuracy is best-effort.
+
+### R004 — Summary screen before collection
+- Class: primary-user-loop
+- Status: active
+- Description: Before collecting secrets one-by-one, show a summary screen listing all needed keys with their guidance. User sees the full picture before entering any values.
+- Why it matters: Collecting 5-8 keys blind is disorienting. A summary lets the user prepare (open dashboards, etc.) before the collection loop starts.
+- Source: user
+- Primary owning slice: M002/S02
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Summary screen is a TUI custom component, not just text output.
+
+### R005 — Existing key detection and silent skip
+- Class: primary-user-loop
+- Status: active
+- Description: Before collecting, check the environment and .env file for each needed key. Keys that already exist are silently skipped — no prompt, no confirmation.
+- Why it matters: Reduces friction on repeated runs or when some keys are already configured.
+- Source: user
+- Primary owning slice: M002/S02
+- Supporting slices: M002/S03
+- Validation: unmapped
+- Notes: Check both process.env and .env file contents.
+
+### R006 — Smart destination detection
+- Class: integration
+- Status: active
+- Description: Automatically detect whether secrets should be written to .env, Vercel, or Convex based on project context (presence of vercel.json, convex/, etc.).
+- Why it matters: User shouldn't have to specify destination — it should be inferred from the project.
+- Source: inferred
+- Primary owning slice: M002/S02
+- Supporting slices: M002/S03
+- Validation: unmapped
+- Notes: Falls back to .env if no specific platform detected.
+
+### R007 — Auto-mode integration
+- Class: core-capability
+- Status: active
+- Description: Auto-mode dispatches a `collect-secrets` phase after `plan-milestone` completes and before the first slice begins execution. If a secrets manifest exists with uncollected keys, auto-mode pauses for collection.
+- Why it matters: This is the primary insertion point that prevents auto-mode from blocking on missing secrets hours into execution.
+- Source: user
+- Primary owning slice: M002/S03
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Must integrate with existing dispatchNextUnit state machine in auto.ts.
+
+### R008 — Guided /gsd wizard integration
+- Class: core-capability
+- Status: active
+- Description: The guided `/gsd` flow triggers the same secret collection after milestone planning, providing a consistent experience regardless of entry point.
+- Why it matters: Users who use `/gsd` instead of `/gsd auto` should get the same proactive secret collection.
+- Source: user
+- Primary owning slice: M002/S03
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Hooks into guided-flow.ts.
+
+### R009 — Planning prompts instruct LLM to forecast secrets
+- Class: integration
+- Status: active
+- Description: The plan-milestone prompt template instructs the LLM to analyze slices for external service dependencies and write a secrets manifest as part of milestone planning output.
+- Why it matters: Without prompt instructions, the LLM won't know to forecast secrets during planning.
+- Source: inferred
+- Primary owning slice: M002/S01
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Modifies plan-milestone.md and possibly the discuss prompt.
+
+### R010 — secure_env_collect enhanced with guidance field
+- Class: primary-user-loop
+- Status: active
+- Description: The `secure_env_collect` tool's key schema gains a `guidance` field (multi-line string or array of strings) beyond the existing single-line `hint`. The TUI displays this guidance prominently during collection.
+- Why it matters: Current `hint` is a single format string like "starts with sk-". Step-by-step guidance needs more space.
+- Source: inferred
+- Primary owning slice: M002/S02
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Backward compatible — existing `hint` still works. `guidance` is additive.
+
+## Validated
+
+(None yet — M002 has not started execution.)
+
+## Deferred
+
+### R011 — Multi-milestone secret forecasting
+- Class: core-capability
+- Status: deferred
+- Description: Forecast secrets across all milestones in a multi-milestone project, not just the current one.
+- Why it matters: Could prevent even more blocking, but later milestones may change significantly.
+- Source: user
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: unmapped
+- Notes: User explicitly chose current-milestone only. Revisit if multi-milestone friction observed.
+
+### R012 — Secret rotation/refresh reminders
+- Class: operability
+- Status: deferred
+- Description: Track key expiry or staleness and remind the user to refresh secrets.
+- Why it matters: Keys expire. Stale keys cause confusing failures.
+- Source: research
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: unmapped
+- Notes: Low priority — solve the blocking problem first.
+
+## Out of Scope
+
+### R013 — Curated service knowledge base
+- Class: constraint
+- Status: out-of-scope
+- Description: A hand-maintained registry of common services (Stripe, OpenAI, Supabase, etc.) with baked-in guidance.
+- Why it matters: Prevents scope confusion — guidance comes from LLM generation, not a database to maintain.
+- Source: user
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: User explicitly chose LLM-generated over curated.
+
+### R014 — Just-in-time collection enhancement
+- Class: constraint
+- Status: out-of-scope
+- Description: Enhancing the reactive just-in-time secret collection experience when a task discovers it needs a key mid-execution.
+- Why it matters: Prevents scope confusion — the goal is front-loading, not improving the fallback path.
+- Source: user
+- Primary owning slice: none
+- Supporting slices: none
+- Validation: n/a
+- Notes: User explicitly chose up-front only. Existing fallback behavior remains as-is.
+
+## Traceability
+
+| ID | Class | Status | Primary owner | Supporting | Proof |
+|---|---|---|---|---|---|
+| R001 | core-capability | active | M002/S01 | M002/S03 | unmapped |
+| R002 | continuity | active | M002/S01 | M002/S02, M002/S03 | unmapped |
+| R003 | primary-user-loop | active | M002/S01 | M002/S02 | unmapped |
+| R004 | primary-user-loop | active | M002/S02 | none | unmapped |
+| R005 | primary-user-loop | active | M002/S02 | none | unmapped |
+| R006 | integration | active | M002/S02 | M002/S03 | unmapped |
+| R007 | core-capability | active | M002/S03 | none | unmapped |
+| R008 | core-capability | active | M002/S03 | none | unmapped |
+| R009 | integration | active | M002/S01 | none | unmapped |
+| R010 | primary-user-loop | active | M002/S02 | none | unmapped |
+| R011 | core-capability | deferred | none | none | unmapped |
+| R012 | operability | deferred | none | none | unmapped |
+| R013 | constraint | out-of-scope | none | none | n/a |
+| R014 | constraint | out-of-scope | none | none | n/a |
+
+## Coverage Summary
+
+- Active requirements: 10
+- Mapped to slices: 10
+- Validated: 0
+- Unmapped active requirements: 0
diff --git a/.gsd/STATE.md b/.gsd/STATE.md
new file mode 100644
index 000000000..f304b690c
--- /dev/null
+++ b/.gsd/STATE.md
@@ -0,0 +1,23 @@
+# GSD State
+
+**Active Milestone:** M002 — Proactive Secret Management
+**Active Slice:** —
+**Active Task:** —
+**Phase:** pre-planning
+**Slice Branch:** main
+**Active Workspace:** default
+**Next Action:** Research and plan M002 roadmap slices
+**Last Updated:** 2026-03-12
+**Requirements Status:** 10 active · 0 validated · 2 deferred · 2 out of scope
+
+## Recent Decisions
+
+- D005: Secret guidance is LLM-generated at planning time, not from a static database
+- D006: Secret collection is up-front during planning only
+- D007: Secret forecasting scoped to current milestone only
+- D008: Existing keys silently skipped without confirmation
+- D009: Destination inferred from project context
+
+## Blockers
+
+- (none)
diff --git a/.gsd/milestones/M002/M002-CONTEXT.md b/.gsd/milestones/M002/M002-CONTEXT.md
new file mode 100644
index 000000000..299b891bd
--- /dev/null
+++ b/.gsd/milestones/M002/M002-CONTEXT.md
@@ -0,0 +1,117 @@
+# M002: Proactive Secret Management — Context
+
+**Gathered:** 2026-03-12
+**Status:** Ready for planning
+
+## Project Description
+
+Add proactive secret forecasting and guided collection to GSD's milestone planning phase. When a milestone is planned, the LLM analyzes what external services and API keys will be needed, writes a secrets manifest with step-by-step guidance for each key, and collects them all before auto-mode begins execution.
+
+## Why This Milestone
+
+Auto-mode's value proposition is autonomous execution — plan it, walk away, come back to finished work. But if a task at S02/T03 needs a Stripe API key, auto-mode blocks and sits there for hours waiting. The user comes back expecting progress and finds a prompt asking for a key. This milestone eliminates that failure mode by front-loading secret collection into the planning phase.
+
+## User-Visible Outcome
+
+### When this milestone is complete, the user can:
+
+- Describe a project during `/gsd` discuss that involves external APIs (Stripe, Supabase, OpenAI, etc.) and see a secrets manifest produced during planning with step-by-step guidance for each key
+- See a summary screen listing all needed keys with guidance, then enter them one-by-one with detailed instructions showing where to find each key
+- Run `/gsd auto` and have it collect any uncollected secrets before starting slice execution, so auto-mode runs uninterrupted
+
+### Entry point / environment
+
+- Entry point: `/gsd` wizard and `/gsd auto` CLI commands
+- Environment: local dev terminal (pi TUI)
+- Live dependencies involved: `secure_env_collect` tool, .env files, optionally Vercel/Convex CLIs
+
+## Completion Class
+
+- Contract complete means: planning prompts produce secrets manifests, the manifest parser works, the collection TUI shows guidance and skips existing keys, and auto-mode dispatches collection at the right time
+- Integration complete means: a real `/gsd auto` run with a milestone that needs API keys triggers collection before slice execution
+- Operational complete means: none — this is a dev-time workflow, not a running service
+
+## Final Integrated Acceptance
+
+To call this milestone complete, we must prove:
+
+- A milestone planning run that involves external APIs produces a parseable secrets manifest with per-key guidance
+- Auto-mode detects the manifest and pauses for collection before dispatching the first slice
+- Keys already in the environment are silently skipped
+- The guided `/gsd` flow triggers the same collection
+- `npm run build` passes
+- `npm run test` passes (no new failures beyond pre-existing ones)
+
+## Risks and Unknowns
+
+- **Prompt compliance** — The LLM must reliably produce a well-formatted secrets manifest during planning. If the format is inconsistent, the parser won't find the keys. Mitigated by clear prompt instructions and a forgiving parser.
+- **Guidance accuracy** — LLM-generated guidance for finding API keys (dashboard URLs, navigation steps) may be outdated or wrong. This is best-effort and explicitly accepted by the user.
+- **State machine insertion** — Adding a new phase to `dispatchNextUnit` in `auto.ts` must not break the existing phase flow. The insertion point is between `plan-milestone` completion and the first slice dispatch.
+
+## Existing Codebase / Prior Art
+
+- `src/resources/extensions/get-secrets-from-user.ts` — The existing `secure_env_collect` tool. Has paged masked TUI input, writes to .env/Vercel/Convex. Currently has a single-line `hint` field per key. Needs a `guidance` field for multi-line instructions and a summary screen.
+- `src/resources/extensions/gsd/auto.ts` — The auto-mode state machine. `dispatchNextUnit()` determines next unit type from derived state. New `collect-secrets` unit type inserts between plan-milestone and first slice.
+- `src/resources/extensions/gsd/guided-flow.ts` — The `/gsd` wizard. `showSmartEntry()` handles all entry paths. Needs to trigger secret collection after milestone planning.
+- `src/resources/extensions/gsd/prompts/plan-milestone.md` — The planning prompt template. Needs instructions to forecast secrets and write the manifest.
+- `src/resources/extensions/gsd/state.ts` — State derivation from disk files. May need to expose whether a secrets manifest exists and whether collection is complete.
+- `src/resources/extensions/gsd/files.ts` — File parsing utilities. Needs a secrets manifest parser.
+- `src/resources/extensions/gsd/types.ts` — Core type definitions. Needs types for secrets manifest entries.
+- `src/resources/extensions/gsd/paths.ts` — Path resolution. Needs a `resolveMilestoneFile` entry for SECRETS files.
+
+> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
+
+## Relevant Requirements
+
+- R001 — Secret forecasting during milestone planning (core capability)
+- R002 — Secrets manifest file persisted in .gsd/ (continuity)
+- R003 — LLM-generated step-by-step guidance per key (primary user loop)
+- R004 — Summary screen before collection (primary user loop)
+- R005 — Existing key detection and silent skip (primary user loop)
+- R006 — Smart destination detection (integration)
+- R007 — Auto-mode integration (core capability)
+- R008 — Guided /gsd wizard integration (core capability)
+- R009 — Planning prompts instruct LLM to forecast secrets (integration)
+- R010 — secure_env_collect enhanced with guidance field (primary user loop)
+
+## Scope
+
+### In Scope
+
+- Secret forecasting during plan-milestone phase
+- Secrets manifest file format and parser
+- Enhanced secure_env_collect with guidance and summary screen
+- Existing key detection (.env and process.env)
+- Smart destination detection from project context
+- Auto-mode collect-secrets phase insertion
+- Guided flow collection trigger
+- Manifest status tracking (collected/pending/skipped)
+
+### Out of Scope / Non-Goals
+
+- Multi-milestone secret forecasting (deferred — R011)
+- Secret rotation reminders (deferred — R012)
+- Curated service knowledge base (out of scope — R013)
+- Just-in-time collection enhancement (out of scope — R014)
+- Modifying how secure_env_collect writes to Vercel/Convex (existing behavior preserved)
+
+## Technical Constraints
+
+- Must not break existing auto-mode phase flow — new phase inserts cleanly
+- `secure_env_collect` changes must be backward compatible — existing callers unaffected
+- Secrets manifest must be parseable by simple regex/string parsing (consistent with files.ts patterns)
+- The discuss prompt (GSD-WORKFLOW.md) already handles milestone planning for guided flow — secret forecasting instructions go in plan-milestone.md which runs in auto-mode after discuss completes
+
+## Integration Points
+
+- `secure_env_collect` tool — Enhanced with guidance field and summary screen
+- `dispatchNextUnit()` in auto.ts — New collect-secrets unit type
+- `plan-milestone.md` prompt — Instructions to forecast secrets
+- `guided-flow.ts` — Collection trigger after planning
+- `state.ts` / `files.ts` — Manifest parsing and state derivation
+- `.env` file / process.env — Existing key detection
+
+## Open Questions
+
+- **Manifest format** — Markdown with structured sections (consistent with other .gsd files) vs. YAML/JSON. Leaning toward markdown with parseable structure, matching the roadmap/plan pattern.
+- **Destination inference heuristics** — How aggressively to detect Vercel/Convex vs. defaulting to .env. Leaning toward simple file-presence checks (vercel.json → Vercel, convex/ dir → Convex).
diff --git a/.gsd/milestones/M002/M002-ROADMAP.md b/.gsd/milestones/M002/M002-ROADMAP.md
new file mode 100644
index 000000000..7190ffd24
--- /dev/null
+++ b/.gsd/milestones/M002/M002-ROADMAP.md
@@ -0,0 +1,122 @@
+# M002: Proactive Secret Management
+
+**Vision:** Front-load API key collection during milestone planning so auto-mode runs uninterrupted. The LLM forecasts which secrets a milestone needs, generates step-by-step guidance for finding each key, and collects them all before execution begins.
+
+## Success Criteria
+
+- After milestone planning, a secrets manifest exists listing all predicted API keys with per-key step-by-step guidance
+- Auto-mode pauses to collect uncollected secrets before dispatching the first slice
+- The guided `/gsd` flow triggers the same collection after planning
+- Keys already present in the environment are silently skipped
+- The collection UX shows a summary of all needed keys before collecting them one-by-one
+- `npm run build` passes
+- `npm run test` passes (no new failures beyond pre-existing)
+
+## Key Risks / Unknowns
+
+- **Prompt compliance** — LLM must reliably produce a well-formatted secrets manifest during planning
+- **State machine insertion** — Adding a new phase to `dispatchNextUnit` must not break existing flow
+
+## Proof Strategy
+
+- Prompt compliance → retire in S01 by proving the plan-milestone prompt produces a parseable manifest when the milestone involves external APIs
+- State machine insertion → retire in S03 by proving auto-mode dispatches collect-secrets at the right time and proceeds normally after
+
+## Verification Classes
+
+- Contract verification: unit tests for manifest parser, build passes, existing tests pass
+- Integration verification: auto-mode dispatches collect-secrets phase correctly, guided flow triggers collection
+- Operational verification: none — dev-time workflow
+- UAT / human verification: real milestone planning produces usable manifest, collection UX is clear
+
+## Milestone Definition of Done
+
+This milestone is complete only when all are true:
+
+- Planning prompts instruct the LLM to forecast secrets and write a manifest
+- The manifest file persists in `.gsd/milestones/M00x/` with per-key guidance
+- `secure_env_collect` supports multi-line guidance beyond the single-line hint
+- Auto-mode dispatches a collect-secrets phase between plan-milestone and first slice
+- Guided `/gsd` flow triggers the same collection
+- Existing keys are detected and silently skipped
+- Destination is inferred from project context
+- Success criteria are re-verified against live behavior
+- `npm run build` passes
+- `npm run test` passes
+
+## Requirement Coverage
+
+- Covers: R001, R002, R003, R004, R005, R006, R007, R008, R009, R010
+- Partially covers: none
+- Leaves for later: R011 (multi-milestone forecasting), R012 (rotation reminders)
+- Orphan risks: none
+
+## Slices
+
+- [ ] **S01: Secret Forecasting & Manifest** `risk:medium` `depends:[]`
+  > After this: running plan-milestone on a project involving external APIs produces a `.gsd/milestones/M00x/M00x-SECRETS.md` manifest file with predicted keys and step-by-step guidance for each. Verified by planning a test milestone and confirming the manifest is parseable.
+
+- [ ] **S02: Enhanced Collection UX** `risk:medium` `depends:[S01]`
+  > After this: `secure_env_collect` shows a summary screen of all needed keys with guidance before collecting, displays multi-line guidance per key during collection, detects and silently skips keys already in the environment, and infers the write destination from project context. Verified by running the enhanced tool with a test manifest.
+
+- [ ] **S03: Auto-Mode & Guided Flow Integration** `risk:low` `depends:[S01,S02]`
+  > After this: auto-mode dispatches a collect-secrets phase after plan-milestone and before the first slice. The guided `/gsd` flow triggers the same collection. Collected status is tracked in the manifest. Verified by running auto-mode through the plan → collect → execute transition.
+
+- [ ] **S04: End-to-End Verification** `risk:low` `depends:[S03]`
+  > After this: the full flow is verified end-to-end — a real milestone planning session that involves external APIs produces a manifest, triggers collection, and auto-mode proceeds to slice execution without blocking on secrets. All tests pass, build succeeds.
+
+## Boundary Map
+
+### S01 → S02
+
+Produces:
+- `types.ts` → `SecretsManifestEntry` interface (key, service, guidance, status, destination)
+- `types.ts` → `SecretsManifest` interface (entries array, milestone, generated_at)
+- `files.ts` → `parseSecretsManifest(content: string): SecretsManifest` parser
+- `files.ts` → `formatSecretsManifest(manifest: SecretsManifest): string` writer
+- `paths.ts` → `resolveMilestoneFile` recognizes `"SECRETS"` suffix
+- `prompts/plan-milestone.md` → instructions to write `M00x-SECRETS.md` during planning
+- `templates/secrets-manifest.md` → template for the manifest format
+
+Consumes:
+- nothing (first slice)
+
+### S01 → S03
+
+Produces:
+- Same as S01 → S02 (manifest types, parser, paths)
+- `files.ts` → `parseSecretsManifest` for reading manifest status
+
+Consumes:
+- nothing (first slice)
+
+### S02 → S03
+
+Produces:
+- `get-secrets-from-user.ts` → enhanced `secure_env_collect` with `guidance` field on keys
+- `get-secrets-from-user.ts` → summary screen TUI component before collection
+- `get-secrets-from-user.ts` → `checkExistingEnvKeys(keys, envPath): string[]` helper
+- `get-secrets-from-user.ts` → `detectDestination(basePath): "dotenv" | "vercel" | "convex"` helper
+
+Consumes from S01:
+- `types.ts` → `SecretsManifestEntry`, `SecretsManifest` interfaces
+- `files.ts` → `parseSecretsManifest` to read the manifest
+- `paths.ts` → `resolveMilestoneFile(base, mid, "SECRETS")` to find the manifest
+
+### S03 → S04
+
+Produces:
+- `auto.ts` → collect-secrets unit type in `dispatchNextUnit`
+- `auto.ts` → `buildCollectSecretsPrompt()` or direct TUI dispatch (no LLM session needed)
+- `guided-flow.ts` → collection trigger after milestone planning
+- `state.ts` → secrets collection status in derived state
+- `files.ts` → `updateSecretsManifestStatus()` to mark keys as collected/skipped
+
+Consumes from S01:
+- `types.ts` → manifest types
+- `files.ts` → manifest parser/writer
+- `paths.ts` → SECRETS file resolution
+
+Consumes from S02:
+- `get-secrets-from-user.ts` → enhanced `secure_env_collect` with guidance and summary
+- `get-secrets-from-user.ts` → `checkExistingEnvKeys`, `detectDestination`