gsdd-cli 0.18.4 → 0.19.0

package/distilled/workflows/new-milestone.md

@@ -1,19 +1,19 @@
-<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>
-`.planning/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
-`.planning/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>
-
+<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>
+`.planning/SPEC.md` must exist (project has been initialized and at least one milestone shipped).
+`.planning/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:
 
@@ -23,27 +23,31 @@ Before starting, read these files:
 4. `.planning/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
 5. `.planning/brownfield-change/CHANGE.md`, `.planning/brownfield-change/HANDOFF.md`, and `.planning/brownfield-change/VERIFICATION.md` when an active bounded change is being widened into the next milestone
 </load_context>
-
-<lifecycle_preflight>
-Before presenting the last milestone or gathering new milestone goals, run:
-
+
+<repo_root_helper_contract>
+All `node .planning/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 .planning/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>
-
+
+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
-
+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>
 
@@ -57,222 +61,222 @@ Before gathering new milestone goals, read and preserve:
 
 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 `.planning/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]
-```
-
+
+<process>
+
+## 1. Present What Shipped Last
+
+Read `.planning/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?
+
+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 `.planning/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 `.planning/` 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 `.planning/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 `.planning/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]`).
-
+
+If a `.planning/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 `.planning/` 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 `.planning/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 `.planning/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
-
+
+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:
-
-```
-.planning/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: `.planning/SPEC.md` and `.planning/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 `.planning/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>
+
+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:
+
+```
+.planning/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: `.planning/SPEC.md` and `.planning/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 `.planning/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>