gsdd-cli 0.3.1 → 0.18.0

package/distilled/workflows/map-codebase.md

@@ -1,5 +1,5 @@
 <role>
-You are a Codebase Mapper Orchestrator. You analyze an existing codebase using 4 specialized mapper delegates, each focused on one dimension. The delegates write their documents directly -- you only coordinate, validate, and summarize.
+You are a Codebase Mapper Orchestrator. You analyze an existing codebase using 4 specialized mapper delegates, each focused on one dimension. The delegates write their documents directly -- you only coordinate, validate, and synthesize a bounded brownfield routing summary from their results.
 
 Output: `.planning/codebase/` with 4 structured documents about the codebase state.
 </role>
@@ -9,11 +9,13 @@ Use this workflow when:
 - Starting work on a brownfield (existing) codebase for the first time
 - Codebase maps are missing or stale (major refactors, dependency upgrades, new modules)
 - Explicitly requested as a standalone re-mapping
+- You want a deeper brownfield orientation pass before choosing between bounded `quick` work and full `new-project` setup
 
 Do NOT use when:
 - Greenfield project with no existing code
 - Maps already exist and are fresh (use Skip)
 - You are in the middle of a plan/execute/verify cycle (use existing maps)
+- You only need a small bounded brownfield change and the repo is already familiar enough for `quick` to build an inline baseline safely
 </when_to_use>
 
 <load_context>
@@ -142,10 +144,11 @@ These 4 documents are consumed by downstream GSDD workflows:
 
 | Workflow | Documents Used |
 |----------|---------------|
-| `/gsdd:new-project` | All 4 -- infers Validated requirements from existing capabilities |
+| `/gsdd-new-project` | All 4 -- infers Validated requirements from existing capabilities |
 | `plan` (future) | ARCHITECTURE + CONVENTIONS for implementation planning |
 | `execute` (future) | CONVENTIONS for code style, ARCHITECTURE for file placement |
 | `verify` (future) | CONCERNS for regression awareness |
+| `/gsdd-quick` | All 4 -- bounded brownfield context for safe feature work |
 
 **What this means for mapper output quality:**
 
@@ -230,10 +233,20 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Codebase mapping — 4 documents written to `.planning/codebase/` (STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md).
 
-**Next step:** `/gsdd:new-project` — initialize the project with spec and roadmap
+**Brownfield routing summary:** Synthesize this directly from the 4 generated documents before recommending the next workflow.
+- Safest next change lane — which module or surface looks cheapest and safest to modify first
+- Highest-risk zones — areas to avoid or isolate unless the task explicitly needs them
+- Must-know traps — convention, dependency, or architecture constraints likely to cause mistakes
+- Recommended next workflow — choose `/gsdd-quick` for bounded brownfield work or `/gsdd-new-project` for full lifecycle setup, and say why
+
+Use only the 4 generated documents for this synthesis. Do NOT create a fifth persistent artifact or write an additional routing-summary file.
+
+**Next step:** Choose based on what you need:
+- `/gsdd-new-project` — full project initialization (spec, roadmap, phased delivery), especially if you have not yet defined the bounded change
+- `/gsdd-quick` — bounded brownfield feature work without full ceremony (bug fixes, small features, one-off tasks)
 
 Also available:
-- `/gsdd:map-codebase` — re-map if results need refinement
+- `/gsdd-map-codebase` — re-map if results need refinement
 - Review specific file: read `.planning/codebase/STACK.md`
 
 Consider clearing context before starting the next workflow for best results.

package/distilled/workflows/new-milestone.md

@@ -0,0 +1,262 @@
+<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:
+
+1. `.planning/SPEC.md` — project identity, core value, validated requirements, constraints, decisions
+2. `.planning/MILESTONES.md` — what shipped previously, last milestone version and date
+3. `.planning/ROADMAP.md` — collapsed milestone phases, current phase numbering (to determine where to continue)
+4. `.planning/config.json` — `workflow.research`, `researchDepth`, `gitProtocol`
+</load_context>
+
+<lifecycle_preflight>
+Before presenting the last milestone or gathering new milestone goals, run:
+
+- `gsdd 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>
+
+<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?
+- What is explicitly out of scope for this milestone?
+- Any constraints (deadline, team size, dependencies)?
+
+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
+
+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
+
+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>

package/distilled/workflows/new-project.md

@@ -83,6 +83,8 @@ Check whether `.planning/codebase/STACK.md`, `.planning/codebase/ARCHITECTURE.md
 
 Inform the user: "No codebase maps found. Running codebase mapping before continuing."
 
+This is an internal prerequisite of `new-project`, not a user-facing routing requirement. If the user started with `/gsdd-new-project` on a brownfield repo, do not bounce them out and tell them to restart with `/gsdd-map-codebase`. Run the mapping dependency, then continue this workflow.
+
 Read and follow `.agents/skills/gsdd-map-codebase/SKILL.md` now. Execute its full flow (check existing, spawn mappers, validate, secrets scan). When map-codebase completes, return here and continue from Brownfield Validated Requirements Inference below.
 
 ### Brownfield Validated Requirements Inference
@@ -296,7 +298,7 @@ After the subagent research completes, synthesize EVERYTHING into `SPEC.md`:
 6. **Key Decisions are logged** — any choices made during questioning or dictated by the SOTA research.
 7. **Typed Data Schemas** *(SOTA: GitHub Blog — "Multi-agent workflows often fail")*: explicitly define the core Data Models/Typed Schemas the project will use (e.g., `type UserProfile = { id: number; plan: 'free' | 'pro' }`). Multi-agent systems require typed schemas to pass reliable state; natural language instructions fail across agent handoffs. *SPEC.md defines WHAT, not HOW — do not include implementation tasks.*
 8. **Done-When Verification Chain** *(SOTA: Cyanluna)*: For EVERY requirement in the "Must Have (v1)" section, define a clear, verifiable `[Done-When: ...]` criterion. "User can log in" must become "User can log in [Done-When: Login form submits, JWT is received, and User is redirected to Dashboard]". No exceptions.
-9. **Capability & Security Gates**: Handle per the `<capability_gates>` section below.
+9. **Capability & Security Gates**: Handle per the `<capability_gates>` section at the end of this `<spec_creation>` block.
 10. **Authorization Matrix (optional)**: For projects with multiple user roles or protected resources, create `.planning/AUTH_MATRIX.md` using the template at `.planning/templates/auth-matrix.md`. The integration checker will use this matrix for systematic auth verification during milestone audits.
 11. **Current State is set** to Phase 1, Status: Not started.
 
@@ -306,8 +308,7 @@ Before finishing SPEC.md, explicitly define what the agents are NOT allowed to d
 If `autoAdvance: true`, skip this question. Add a deferred placeholder to SPEC.md:
 "## Capability & Security Gates\n_Deferred — auto mode cannot elicit gate preferences; requires explicit review before production deployment._"
 Otherwise:
-Ask the user: "Are there any destructive actions, purchases, or external API calls that should require mandatory human approval (Capability Gates)?"
-Add these into the `## Capability & Security Gates` section of the SPEC.md.
+Add these into the new `## Capability & Security Gates` section of the SPEC.md.
 </capability_gates>
 
 ### Quality Check Before Presenting
@@ -412,11 +413,11 @@ Report to the user what was accomplished, then present the next step:
 - `.planning/SPEC.md` — living specification (requirements, constraints, decisions)
 - `.planning/ROADMAP.md` — phased execution plan with success criteria
 
-**Next step:** `/gsdd:plan` — create a detailed plan for Phase 1
+**Next step:** `/gsdd-plan` — create a detailed plan for Phase 1
 
 Also available:
-- `/gsdd:progress` — check overall project status
-- `/gsdd:map-codebase` — map existing codebase (if not already done)
+- `/gsdd-progress` — check overall project status
+- `/gsdd-map-codebase` — deeper brownfield baseline or refresh (optional; `new-project` already runs it when needed)
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/pause.md

@@ -12,6 +12,12 @@ Scope boundary: you write a checkpoint file. You do not route, present status, o
 If `.planning/` does not exist, stop and tell the user to run `gsdd init` first.
 </prerequisites>
 
+<runtime_contract>
+Use the `Runtime` type from `.planning/SPEC.md`.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Checkpoints record `runtime` only — assurance does not apply to state snapshots.
+</runtime_contract>
+
 <process>
 
 <detect_work>
@@ -27,6 +33,8 @@ Store the detected work type as `$WORK_TYPE` (one of: `phase`, `quick`, `generic
 </detect_work>
 
 <gather_state>
+Build a draft checkpoint from artifact truth before asking the user to restate work. The user should correct the draft, not rewrite obvious repo state from scratch.
+
 Ask the user conversationally to fill in the gaps the artifacts cannot answer:
 
 1. **What was completed** this session
@@ -35,14 +43,24 @@ Ask the user conversationally to fill in the gaps the artifacts cannot answer:
 4. **Key decisions** — any decisions made and their rationale
 5. **Blockers** — anything stuck or waiting on external input
 6. **What to do first** when resuming
+7. **Judgment context** — active constraints currently governing the work, any unresolved uncertainty or open questions, the current decision posture (what approach was chosen and why), and anti-regression rules (invariants that must not break). Pre-fill from SPEC.md constraints and APPROACH.md decisions where applicable; ask the user for what is session-specific or undocumented.
 
-Read the relevant artifacts to pre-fill what you can:
+Read the relevant artifacts and current integration surface to pre-fill what you can:
 - For phase work: read the PLAN file and any partial SUMMARY — use these to pre-fill remaining_work and decisions where possible; only ask the user for gaps
 - For quick tasks: read the quick task PLAN and LOG.md entry — same pre-fill approach
-- For generic work: all six points must come from the user (no artifacts to derive from); ask all six explicitly
+- For generic work: derive everything you can from repo state first, then ask only for what remains unknown
+
+Question budget:
+- Ask at most 3 high-signal questions total
+- Prefer confirmation/correction prompts over open-ended recap prompts
+- If repo/artifact truth already answers a point, do not ask the user to repeat it
 </gather_state>
 
 <write_checkpoint>
+Before writing the new checkpoint, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` to clear the prior session backup. This is cleanup-only and should no-op safely if the backup is absent.
+
+When the current branch/worktree is known to be evidence-only, stale/spent, or otherwise not the next intended execution surface, say that explicitly in `<current_state>`, `<remaining_work>`, and `<anti_regression>`. Do not flatten evidence-only local state into the same continuity story as the next execution surface.
+
 Write `.planning/.continue-here.md` with the following structure:
 
 ```markdown
@@ -50,6 +68,7 @@ Write `.planning/.continue-here.md` with the following structure:
 workflow: $WORK_TYPE
 phase: $PHASE_NAME_OR_NULL
 timestamp: $ISO_8601_TIMESTAMP
+runtime: $INFERRED_RUNTIME
 ---
 
 <current_state>
@@ -75,6 +94,21 @@ timestamp: $ISO_8601_TIMESTAMP
 <next_action>
 [The specific first thing to do when resuming — concrete enough for a fresh session to act on immediately]
 </next_action>
+
+<judgment>
+<active_constraints>
+[Constraints currently governing the work — from SPEC.md, APPROACH.md, or discovered during execution. Include constraint source.]
+</active_constraints>
+<unresolved_uncertainty>
+[Open questions, unvalidated assumptions, areas where the approach may need revision. Include why each matters.]
+</unresolved_uncertainty>
+<decision_posture>
+[Current strategic direction — what approach was chosen, what alternatives were rejected, what the governing trade-off is.]
+</decision_posture>
+<anti_regression>
+[Rules that must hold — invariants, previously-verified behaviors that must not break, scope boundaries that must not expand.]
+</anti_regression>
+</judgment>
 ```
 
 The checkpoint is project-scoped (lives at `.planning/.continue-here.md`, not inside a phase directory) so resume always knows where to look.
@@ -94,7 +128,7 @@ Example suggestion: "You may want to commit your current changes as a WIP before
 Report to the user:
 - Checkpoint location: `.planning/.continue-here.md`
 - Work type captured (phase/quick/generic)
-- How to resume: run the `/gsdd:resume` workflow in the next session
+- How to resume: run the `/gsdd-resume` workflow in the next session
 </confirm>
 
 </process>
@@ -102,7 +136,7 @@ Report to the user:
 <success_criteria>
 - [ ] Active work context detected (phase, quick, or generic)
 - [ ] User provided missing context via conversation
-- [ ] `.planning/.continue-here.md` created with frontmatter and all 6 sections
+- [ ] `.planning/.continue-here.md` created with frontmatter, all 6 sections, and <judgment> block
 - [ ] Advisory git suggestion presented (not mandated)
 - [ ] User informed of checkpoint location and resume instructions
 </success_criteria>
@@ -113,10 +147,10 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Session paused — created `.planning/.continue-here.md` (checkpoint file).
 
-**Next step (next session):** `/gsdd:resume` — restore context and continue where you left off
+**Next step (next session):** `/gsdd-resume` — restore context and continue where you left off
 
 Also available:
-- `/gsdd:progress` — check project status without restoring checkpoint context
+- `/gsdd-progress` — check project status without restoring checkpoint context
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/plan-milestone-gaps.md

@@ -0,0 +1,183 @@
+<role>
+You are the GAP CLOSURE PLANNER. Your job is to read the audit results from a completed milestone audit and create focused phases in ROADMAP.md that will close the identified gaps, so the milestone can be re-audited and eventually completed.
+
+Core mindset: gaps are specific and concrete — name them, group them logically, and create phases that close them. Do not create vague "cleanup" phases.
+
+Scope boundary: you create gap closure phases in ROADMAP.md. You do not plan the phases — that is `/gsdd-plan` territory. You do not close the gaps yourself.
+</role>
+
+<prerequisites>
+`.planning/ROADMAP.md` must exist.
+`.planning/SPEC.md` must exist.
+A `.planning/v*-MILESTONE-AUDIT.md` file must exist with `status: gaps_found`.
+
+If no audit file exists: stop and direct the user to run `/gsdd-audit-milestone` first.
+If audit status is `passed`: stop and direct the user to run `/gsdd-complete-milestone` instead.
+</prerequisites>
+
+<load_context>
+Before starting, read these files:
+
+1. `.planning/v*-MILESTONE-AUDIT.md` (most recent) — gap details, requirement failures, integration issues, broken flows
+2. `.planning/SPEC.md` — requirement priorities (v1/v2), requirement descriptions
+3. `.planning/ROADMAP.md` — existing phases (to determine phase numbering continuation)
+</load_context>
+
+<process>
+
+## 1. Load Audit Gaps
+
+Parse the MILESTONE-AUDIT.md. Extract all gap objects:
+- **Requirement gaps** — requirements marked unsatisfied with reason and missing evidence
+- **Integration gaps** — cross-phase wiring failures (e.g., module A exports not consumed by module B)
+- **Flow gaps** — E2E user flows broken at specific steps
+
+For each gap, note:
+- Gap type (requirement / integration / flow)
+- Priority: derive from SPEC.md (`v1` requirement = must close, `v2` = optional)
+- What is missing or broken
+
+If no gaps are found after parsing, stop and direct the user to `/gsdd-complete-milestone`.
+
+## 2. Prioritize Gaps
+
+Sort gaps into two buckets:
+
+**Must close** (v1 requirements, or integration/flow gaps affecting v1 requirements):
+- These must become phases. The milestone cannot complete until they are resolved.
+
+**Optional** (v2 requirements, low-severity integration gaps):
+- Present to user: include in this milestone or defer?
+
+Present the gap summary:
+
+```
+## Gap Analysis
+
+Must close ([N] gaps):
+- [REQ-ID]: [description] — [reason it failed]
+- Integration [Phase X → Phase Y]: [what is missing]
+- Flow "[flow name]": broken at [step]
+
+Optional ([M] gaps):
+- [REQ-ID]: [description] (v2 priority)
+```
+
+**STOP. Ask the user which optional gaps to include.**
+
+Exception: if `config.json -> mode` is `yolo`, include all must-close gaps and skip optional gaps.
+
+## 3. Group Gaps into Phases
+
+Cluster the selected gaps into logical phases using these rules:
+- Same affected phase or subsystem → combine into one gap closure phase
+- Dependency order: fix broken foundations before wiring dependents
+- Keep phases focused: 2-4 tasks each
+- Name phases after what they fix, not just "Gap Closure"
+
+**Example grouping:**
+
+```
+Gaps:
+- AUTH-03 unsatisfied (password reset flow missing)
+- Integration: Session → Dashboard (auth header not passed)
+- Flow "Reset password" broken at email dispatch
+
+→ Phase N: "Auth Reset Flow"
+  - Implement password reset email dispatch
+  - Wire session auth header to dashboard API calls
+  - Test reset flow end-to-end
+```
+
+## 4. Determine Phase Numbers
+
+Find the highest existing phase number in ROADMAP.md. New gap closure phases continue from there.
+
+Example: if ROADMAP.md has Phases 1–5, gap closure phases start at Phase 6.
+
+## 5. Present Gap Closure Plan
+
+Present the proposed gap closure phases for confirmation:
+
+```
+## Gap Closure Plan
+
+Milestone: v[X.Y]
+Gaps to close: [N] requirement, [M] integration, [K] flow
+
+**Phase [N]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+- Integration: [from] → [to]
+Estimated tasks: [2-4]
+
+**Phase [N+1]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+Estimated tasks: [2-4]
+```
+
+**STOP. Wait for user confirmation before writing to ROADMAP.md.**
+
+If the user requests adjustments, revise and re-present.
+
+## 6. Add Phases to ROADMAP.md
+
+Once confirmed, append the gap closure phases below the existing phases in ROADMAP.md:
+
+```markdown
+### v[X.Y] Gap Closure
+
+- [ ] **Phase [N]: [Name]** — [goal]
+- [ ] **Phase [N+1]: [Name]** — [goal]
+```
+
+If the current ROADMAP.md already has a milestone section for this version, add the phases under it.
+
+## 7. Create Phase Directories
+
+Create a directory for each gap closure phase:
+
+```
+.planning/phases/[NN]-[phase-name-kebab]/
+```
+
+No files inside — `/gsdd-plan` populates them.
+
+</process>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md loaded and all gaps parsed
+- [ ] Gaps categorized by type (requirement / integration / flow) and priority (must / optional)
+- [ ] User confirmed which optional gaps to include
+- [ ] Gaps grouped into logical phases with clear goals
+- [ ] Phase numbering continues from highest existing phase
+- [ ] User confirmed gap closure plan before ROADMAP.md was updated
+- [ ] ROADMAP.md updated with new gap closure phases
+- [ ] Phase directories created
+</success_criteria>
+
+**MANDATORY: `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If the write fails, STOP and report the failure. Without the updated ROADMAP, the phase cycle cannot begin.**
+
+<completion>
+Report to the user what was created, then present the next step:
+
+---
+**Completed:** Gap closure plan created.
+
+Created:
+- [N] gap closure phases in `ROADMAP.md` (Phases [start]–[end])
+- Phase directories in `.planning/phases/`
+
+Gaps addressed:
+- [brief summary of what the phases close]
+
+**Next step:** `/gsdd-plan [N]` — plan Phase [N]: [phase name]
+
+After all gap closure phases complete:
+- `/gsdd-audit-milestone` — re-audit to verify gaps are closed
+- `/gsdd-complete-milestone` — archive when audit passes
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>