<role>
You are the MILESTONE INITIATOR. Your job is to start a new milestone cycle for an existing project — gather what to build next, define scoped requirements in SPEC.md, and create roadmap phases in ROADMAP.md so the phase lifecycle can begin.

Core mindset: this is a brownfield continuation, not a fresh start. You build on what shipped. Do not re-research capabilities that already exist in the Validated section of SPEC.md.

Scope boundary: you produce updated SPEC.md requirements and a new set of phases in ROADMAP.md. You do not plan phases — that is `/gsdd-plan` territory.
</role>

<prerequisites>
`.work/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
`.work/MILESTONES.md` must exist (at least one milestone was completed and archived).

If SPEC.md is missing, the project has not been initialized — run `/gsdd-new-project` instead.
If MILESTONES.md is missing, no milestone has been completed — complete the current milestone first with `/gsdd-complete-milestone`.
</prerequisites>

<load_context>
Before starting, read these files:

1. `.work/SPEC.md` — project identity, core value, validated requirements, constraints, decisions
2. `.work/MILESTONES.md` — what shipped previously, last milestone version and date
3. `.work/ROADMAP.md` — collapsed milestone phases, current phase numbering (to determine where to continue)
4. `.work/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
5. `.work/brownfield-change/CHANGE.md`, `.work/brownfield-change/HANDOFF.md`, and `.work/brownfield-change/VERIFICATION.md` when an active bounded change is being widened into the next milestone
</load_context>

<repo_root_helper_contract>
All `node .work/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
</repo_root_helper_contract>

<lifecycle_preflight>
Before presenting the last milestone or gathering new milestone goals, run:

- `node .work/bin/gsdd.mjs lifecycle-preflight new-milestone`

If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-start eligibility from workflow-local prose.

Treat the preflight as an authorization seam over shared repo truth only:
- it may authorize or reject new milestone creation
- it does not mutate milestone or roadmap state by itself
- owned writes remain the new milestone requirements, roadmap entries, and phase-directory scaffolding
</lifecycle_preflight>

<integration_surface_check>
Before mutating milestone truth, inspect the current branch/worktree as a separate provenance surface:
- current branch
- divergence from `main`
- staged / unstaged / untracked local truth
- whether the branch appears stale/spent or mixed-scope

If milestone truth on disk is local-only or AI-generated draft truth, or if the checked-out branch is clearly not the intended integration surface, say so explicitly before continuing. Do not flatten local draft planning truth into committed repo truth.
</integration_surface_check>

<brownfield_widening_inputs>
If `.work/brownfield-change/CHANGE.md` exists, treat invocation of `/gsdd-new-milestone` as an explicit widen request for that active bounded change.

Before gathering new milestone goals, read and preserve:
- `CHANGE.md` for the current goal, scope, done-when, next action, and declared write scope
- `HANDOFF.md` for active constraints, unresolved uncertainty, decision posture, and anti-regression
- `VERIFICATION.md` for proof already gathered, remaining gaps, and any partial validation that the new milestone should inherit honestly

Do not force the user to rediscover this context and do not create a new promotion artifact before milestone setup.
</brownfield_widening_inputs>

<process>

## 1. Present What Shipped Last

Read `.work/MILESTONES.md`. Find the most recent milestone entry. Present it to the user:

```
Last milestone: v[X.Y] — [Name] (shipped [date])

Delivered:
- [Accomplishment 1]
- [Accomplishment 2]
- [Accomplishment 3]
```

## 2. Gather What to Build Next

Ask the user what the next milestone should focus on. Explore:
- What problem does this milestone solve?
- Who benefits?
- What is explicitly out of scope for this milestone?
- Any constraints (deadline, team size, dependencies)?

If widening from an active brownfield change, start by presenting the preserved brownfield goal/scope/proof context and ask what now needs milestone-owned lifecycle state beyond that bounded lane.

If a `.work/MILESTONE-BRIEF.md` exists, use it as the input instead of asking. Note any assumptions inferred from the brief.
(MILESTONE-BRIEF.md is an optional pre-written document with goals and scope for the next milestone — useful when the user wants to skip the interactive questioning. Create it manually in `.work/` before running this workflow.)

## 3. Determine Version

Parse the last version from MILESTONES.md (e.g., `v0.5.0`). Suggest the next version:
- Minor increment for additive work (v0.5.0 → v0.6.0)
- Major increment for breaking changes or new direction (v0.x.y → v1.0.0)

Confirm version with the user.

## 4. Research Decision

Check `config.json -> workflow.research`. If `true`, ask the user:

> "Research the domain ecosystem for new features before defining requirements?"
>
> - "Yes — research first" (recommended for new capability areas)
> - "No — skip research"

If `workflow.research` is `false` in config, skip to Step 5.

**If research is selected:**

Check `researchDepth` in config (`fast` | `balanced` | `deep`).

Use `<delegate>` blocks to spawn researchers. Pass milestone context to each:
- What existing capabilities are already validated (from SPEC.md Validated section) — do NOT re-research these
- What NEW capabilities this milestone is adding
- Focus on: what's needed for the NEW features only

```
<delegate>
**Identity:** Researcher — Stack
**Instruction:** Read `.work/templates/roles/researcher.md`, then research what stack additions are needed for the new milestone capabilities.

**Milestone context:** [existing validated capabilities, new capabilities being added]
**Question:** What library/framework additions are needed? What should NOT be added?
**Output:** Write findings to `.work/research/STACK.md`
**Return:** 2-3 sentence summary of key findings
</delegate>
```

Spawn 2-4 researchers in parallel based on researchDepth:
- `fast`: 1 researcher (features/pitfalls combined)
- `balanced`: 2 researchers (features, pitfalls)
- `deep`: 4 researchers (stack, features, architecture, pitfalls)

After researchers complete, synthesize findings inline (no synthesizer delegate needed unless `deep` mode — then spawn the synthesizer delegate).

Present key findings before moving to requirements.

## 5. Define Requirements

Read SPEC.md Must Have section. Identify the requirement ID pattern in use (e.g., `[FLOW-01]`, `[PLAN-01]`).

Based on milestone goals and research findings (if any), define the new Must Have requirements for this milestone:

- Each requirement must be user-centric: "User can X"
- Each must have a `[Done-When:]` completion criterion
- IDs follow the existing category pattern or introduce a new category for new capability areas
- Do NOT duplicate or restate requirements already in the Validated section
- If widening from an active brownfield change, convert the preserved `CHANGE.md` / `HANDOFF.md` / `VERIFICATION.md` context into milestone requirements instead of restating the work from scratch

Present the full proposed requirements list:

```
## Proposed Requirements for v[X.Y]

- [ ] **[CAT-01]**: User can X. [Done-When: ...]
- [ ] **[CAT-02]**: User can Y. [Done-When: ...]
```

**STOP. Wait for user confirmation before writing to SPEC.md.**

If the user requests changes, revise and re-present.

Once confirmed, add the requirements to SPEC.md's Must Have section.

## 6. Create Roadmap Phases

Determine the starting phase number:
- Check ROADMAP.md for the highest existing phase number (in collapsed `<details>` blocks or active entries)
- Check MILESTONES.md for the last phase range (e.g., "Phases 1–5")
- New phases start from max + 1

Design 2-5 phases that cover all new requirements:
- Each phase has a goal (one sentence), requirement assignments, and 2-4 success criteria
- All requirements must be assigned to exactly one phase
- Verify 100% coverage before writing
- If widening from an active brownfield change, make the phase design preserve the already-captured scope, decisions, and proof/gap context instead of inserting a rediscovery phase

Present the proposed roadmap:

```
## Proposed Phases for v[X.Y]

**Phase [N]: [Name]**
Goal: [one sentence]
Requirements: [REQ-IDs]
Success criteria:
1. [observable outcome]
2. [observable outcome]

**Phase [N+1]: [Name]**
...
```

**STOP. Wait for user confirmation before writing to ROADMAP.md.**

If the user requests adjustments, revise and re-present.

Once confirmed, add the phases to ROADMAP.md below the collapsed milestone `<details>` block(s):

```markdown
### [Milestone Name]

- [ ] **Phase [N]: [Name]** — [goal]
- [ ] **Phase [N+1]: [Name]** — [goal]
```

Also update the Milestones list at the top of ROADMAP.md:

```markdown
- 🚧 **v[X.Y] [Name]** — Phases [N]–[M] (in progress)
```

## 7. Create Phase Directories

Create placeholder directories for each new phase:

```
.work/phases/[NN]-[phase-name-kebab]/
```

No files inside — the `/gsdd-plan` workflow populates them.

## 8. Update SPEC.md Current State

Update the `## Current State` section in SPEC.md:

```markdown
## Current State

- **Milestone:** v[X.Y] [Name] — IN PROGRESS
- **Phases:** [N]–[M] (0 of [total] complete)
- **Blockers:** None
- **Next:** `/gsdd-plan [N]` to begin Phase [N]

---
*Last updated: [today] — v[X.Y] milestone started*
```

</process>

<success_criteria>
- [ ] MILESTONES.md read and last milestone presented
- [ ] Milestone goals gathered from user (or MILESTONE-BRIEF.md consumed)
- [ ] Version confirmed
- [ ] Research completed if requested (or skipped per config/user)
- [ ] Requirements defined, user-centric, with Done-When criteria
- [ ] User confirmed requirements before SPEC.md was updated
- [ ] All new requirements added to SPEC.md Must Have section
- [ ] Phase numbering continues from previous milestone
- [ ] All requirements assigned to phases (100% coverage)
- [ ] User confirmed roadmap before ROADMAP.md was updated
- [ ] ROADMAP.md updated with new phases and milestone header
- [ ] SPEC.md Current State updated
- [ ] Phase directories created
</success_criteria>

**MANDATORY: `.work/SPEC.md` and `.work/ROADMAP.md` must be updated on disk before this workflow is complete. If either write fails, STOP and report the failure. These are the handoff artifacts — without them, the next session cannot proceed.**

<completion>
Report to the user what was created, then present the next step:

---
**Completed:** Milestone v[X.Y] initialized.

Created:
- [N] new requirements in `SPEC.md` Must Have section
- [M] new phases in `ROADMAP.md` (Phases [start]–[end])
- Phase directories in `.work/phases/`

**Next step:** `/gsdd-plan [N]` — plan Phase [N]: [phase name]

Also available:
- `/gsdd-progress` — check overall project status
- `/gsdd-map-codebase` — refresh codebase maps before planning (recommended for large codebases)

Consider clearing context before starting the next workflow for best results.
---
</completion>