gsdd-cli 0.3.1 → 0.16.1

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>

package/distilled/workflows/plan.md

@@ -13,17 +13,42 @@ Before starting, read these files:
 4. `.planning/phases/*-APPROACH.md` - approach decisions from user discussion (if exists)
 5. `.planning/phases/*-PLAN.md` - any previous plans that affect this phase
 6. Relevant source code - if this phase builds on existing code, read the key files
-
+7. `.planning/phases/*-SUMMARY.md` for the prior completed phase - if a `<judgment>` section is present, read all four sub-sections. The `<judgment>` carries forward active constraints, unresolved uncertainty, decision posture, and anti-regression rules from the prior phase. Honor these as input context alongside SPEC.md decisions and APPROACH.md choices.
+8. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 7, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section and honor the same four sub-sections as input context. After reading, run `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean: the judgment has been absorbed into this session's context).
 Identify the target phase: the first phase with status `[ ]` or `[-]` in `ROADMAP.md`.
 </load_context>
 
+<integration_surface_check>
+Before planning roadmap work, inspect the live integration surface separately from checkpoint or planning artifacts:
+- current branch name
+- divergence from `main` when available
+- staged, unstaged, and untracked local truth
+- whether the current branch appears stale/spent or mixed-scope
+
+If the planning truth says "next phase is X" but the git/worktree truth says the current branch is a stale or mixed execution surface, warn explicitly and treat the dirty branch as evidence only. Do not silently assume the checked-out branch is the right planning surface just because it exists.
+</integration_surface_check>
+
+<runtime_contract>
+Use the `Runtime` and `Assurance` types 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`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Same-runtime helpers never count as cross-runtime evidence.
+</runtime_contract>
+
+<assurance_check>
+After `<load_context>`, compare the current planning pass against the strongest upstream artifact available: same-phase prior plan first, otherwise prior completed phase SUMMARY or VERIFICATION.
+Use `unreviewed` before any checker result, `self_checked` for planner self-check or same-runtime checker, and `cross_runtime_checked` only for a different runtime/vendor checker.
+If current assurance is lower, write a structured `<assurance_check>` near the top of the plan body with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
+If upstream runtime/assurance is missing, use `status: unknown`.
+</assurance_check>
+
 <context_fidelity>
 Before planning, acknowledge what is locked:
-
 - Decisions in `.planning/SPEC.md` "Key Decisions" - do not revisit them.
 - Decisions in APPROACH.md "Implementation Decisions" - these are user-validated choices. Implement the chosen approaches, not alternatives. "Agent's Discretion" items give you flexibility.
 - Patterns from previous phases - match existing conventions. Do not introduce new patterns without cause.
 - Deferred items - items marked v2, nice-to-have, or out of scope in SPEC.md or APPROACH.md. Do not plan for them.
+- Cross-check: if SPEC.md and APPROACH.md disagree on whether an item is must-have or deferred, stop and ask the user before planning. Do not silently adopt one classification over the other.
 
 If you need to challenge a locked decision: stop, ask the developer, and document the new decision explicitly.
 </context_fidelity>
@@ -58,9 +83,30 @@ Write to `.planning/research/{phase_number}-RESEARCH.md` with sections:
 - Research for this phase already exists and is still fresh
 - The phase uses only technologies already established in previous phases
 
-Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach.
+Quality gate: do not proceed to goal-backward planning if you have unresolved uncertainties about the implementation approach. If research was skipped (skip conditions above apply), document the skip reason in the plan Notes section so the plan checker can verify the skip was justified.
 </research_check>
 
+<spec_quality_check>
+### When This Runs
+After research_check, before goal_backward_planning.
+
+### Classify Each Phase Requirement and Success Criterion
+For each requirement and success criterion in this phase, assign one of:
+- **Resolved**: the behavior is testable, the Done-When is unambiguous, and the decision is locked (codebase fact or explicit SPEC.md/APPROACH.md decision). Proceed.
+- **Open**: the requirement depends on a product or UX decision that has not been made. Cannot proceed.
+- **Ambiguous**: there are two or more reasonable interpretations of what "done" means. Cannot proceed.
+
+Trigger questions per item:
+- Is the Done-When criterion specific enough to write a verify command for?
+- Does this require a product or UX decision that is absent from SPEC.md, APPROACH.md, or ROADMAP.md?
+- Would two different developers reasonably implement this differently based only on the requirement text?
+
+### Quality Gate
+- If all items are **Resolved**: proceed to goal_backward_planning.
+- If any item is **Open** or **Ambiguous**: STOP. Report each item with the specific question that would resolve it. Do not produce an execution-ready plan until the user resolves these items.
+- Exception — **minor technical ambiguity** (e.g., exact error message wording, logging format) that does not change user-facing behavior: note it as a warning in the plan Notes section and proceed. Do not use this exception for behavioral or acceptance-criteria ambiguity.
+</spec_quality_check>
+
 <goal_backward_planning>
 Plan backward from success criteria.
 
@@ -96,6 +142,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/lib/auth.ts
@@ -196,6 +244,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/routes/users.ts
@@ -231,6 +281,16 @@ must_haves:
 1. [Observable truth from ROADMAP.md]
 2. [Observable truth from ROADMAP.md]
 
+<checks>
+<plan_check>
+checker: self | cross_runtime
+checker_runtime: claude-code
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the checker actually validated or why it was skipped]
+</plan_check>
+</checks>
+
 ## Tasks
 
 <task id="01-01" type="auto">
@@ -250,6 +310,8 @@ must_haves:
 ## Notes
 [Gotchas, implementation notes, or explicit assumptions]
 ```
+
+**MANDATORY: You MUST write PLAN.md to disk at `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, planning is NOT complete.**
 </plan_structure>
 
 <approach_exploration>
@@ -342,9 +404,7 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 7. `context_compliance` - locked decisions are honored and deferred ideas stay out of scope
 8. `goal_achievement` - the plan, if executed perfectly, actually achieves the stated phase goal: goal addressed (tasks deliver the goal), success criteria reachable (each criterion traceable to a task verify output), and outcome observable (a human or automated check can confirm the goal was met)
 9. `approach_alignment` - when APPROACH.md exists, plans implement the chosen approaches, not alternatives. Blocker if plan contradicts an explicit user choice. Warning if plan drifts from recommendation without justification. Skipped when no APPROACH.md is provided.
-
 ### Invoking the Checker
-
 1. If `.planning/config.json` has `workflow.planCheck: false`, skip the independent checker. Perform the planner self-check below and report `reduced_assurance`.
 2. If plan checking is enabled, check if your runtime provides a `gsdd-plan-checker` agent.
 3. If a native checker agent is available, invoke it in a fresh context with only these explicit inputs:
@@ -375,9 +435,12 @@ After the planner produces a draft plan, an independent checker reviews it in fr
 6. If the checker returns `issues_found`, revise the existing plan files only where needed, then invoke the checker again.
 7. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
 8. If no native checker agent is available in your runtime, perform the planner self-check below and explicitly report `reduced_assurance` rather than claiming an independent checker ran.
-
+When the checker outcome is finalized, write the result into the plan artifact:
+- checker ran in same runtime or planner self-check only -> set frontmatter `assurance: self_checked`
+- checker ran in a different runtime/vendor and passed -> set frontmatter `assurance: cross_runtime_checked`
+- draft exists before any checker result is recorded -> keep `assurance: unreviewed`
+- record the structured outcome in the plan's `<checks>` block; do not leave the checker result only in chat context
 ### Orchestration Summary
-
 After plan checking completes, report:
 - target phase
 - whether independent plan checking ran
@@ -401,7 +464,6 @@ For every success criterion from `ROADMAP.md`:
 - [ ] At least one task produces an artifact that satisfies it
 - [ ] The task's `<verify>` section checks it specifically
 - [ ] The criterion is covered explicitly, not only implied
-
 ### Check Task Completeness
 For each task:
 - [ ] The `<files>` section lists every file to create or modify
@@ -430,6 +492,8 @@ Planning is done when all of these are true:
 - [ ] Success criteria from `ROADMAP.md` are represented as must-haves
 - [ ] Goal-backward derivation from criteria to artifacts to key links to tasks is explicit
 - [ ] Every plan has frontmatter with `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, and `must_haves`
+- [ ] Every plan frontmatter records `runtime` and `assurance`
+- [ ] Every plan records checker outcome in a structured `<checks>` block
 - [ ] Every task has XML structure with `id`, `type`, `files`, `action`, `verify`, and `done`
 - [ ] Every task has at least one runnable verify command
 - [ ] Plan sizing stays within 2-5 tasks, preferring 2-3
@@ -443,11 +507,11 @@ Report to the user what was accomplished, then present the next step:
 ---
 **Completed:** Phase planning — created `.planning/phases/{phase_dir}/{plan_id}-PLAN.md`.
 
-**Next step:** `/gsdd:execute` — execute the plan
+**Next step:** `/gsdd-execute` — execute the plan
 
 Also available:
-- `/gsdd:plan` — create additional plans for the same phase (if multi-wave)
-- `/gsdd:progress` — check overall project status
+- `/gsdd-plan` — create additional plans for the same phase (if multi-wave)
+- `/gsdd-progress` — check overall project status
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/progress.md

@@ -18,7 +18,7 @@ This is a read-only workflow. No files are created, modified, or deleted. If `.p
 Check for project artifacts in order:
 
 1. **No `.planning/` directory** — tell the user to run `gsdd init`. Stop.
-2. **No `.planning/ROADMAP.md` AND no `.planning/SPEC.md`** — project has no artifacts. Suggest running the `/gsdd:new-project` workflow. Stop.
+2. **No `.planning/ROADMAP.md` AND no `.planning/SPEC.md`** — project has no artifacts. Suggest running the `/gsdd-new-project` workflow. Stop.
 3. **No `.planning/ROADMAP.md` BUT `.planning/SPEC.md` exists** — this is a between-milestones state (milestone was completed and archived). Go to Branch F.
 4. **Both exist** — proceed to derive status.
 </check_existence>
@@ -51,6 +51,14 @@ Scan `.planning/phases/` for:
 
 **Quick task log:**
 If `.planning/quick/LOG.md` exists, check the last entry for a non-terminal status.
+
+<unmerged_commits_check>
+Run `git log main..HEAD --oneline` to detect commits on the current branch that have not been merged to `main`.
+
+- If the command exits non-zero or `main` does not exist, skip silently — do not surface an error or any output.
+- If the output is empty, record nothing — the silent path; no status line is added.
+- If the output is non-empty, record the commit lines and count them. This will be surfaced in the status block.
+</unmerged_commits_check>
 </derive_status>
 
 <recent_work>
@@ -78,7 +86,7 @@ Recent Work:
 - Phase [Y]: [one-liner from SUMMARY.md]
 
 [If .continue-here.md exists:]
-Checkpoint: paused work found — run /gsdd:resume to restore context
+Checkpoint: paused work found — run /gsdd-resume to restore context
 
 [If PLAN without SUMMARY found:]
 Incomplete execution: Phase [N] has PLAN but no SUMMARY
@@ -89,6 +97,11 @@ Unverified: Phase [N] has SUMMARY but no VERIFICATION
 [If incomplete quick task found:]
 Incomplete quick task: [description]
 
+[If unmerged commits found (git log main..HEAD --oneline returned output):]
+Unmerged commits: [N] commit(s) on this branch not yet merged to main
+  → Merge or push this branch before closing the milestone, or verify
+    these commits are intentional working-branch state.
+
 [If all phases [x]:]
 All phases complete — ready for milestone audit
 ```
@@ -107,8 +120,8 @@ Recent Work:
 Incomplete execution: Phase 3 has PLAN but no SUMMARY
 
 Suggested next action:
-  Run /gsdd:execute to continue Phase 3 execution
-  Also available: /gsdd:plan (re-plan), /gsdd:progress (refresh status)
+  Run /gsdd-execute to continue Phase 3 execution
+  Also available: /gsdd-plan (re-plan), /gsdd-progress (refresh status)
 ```
 
 No ASCII art, no progress bars. Keep it scannable.
@@ -122,8 +135,8 @@ Condition: `.continue-here.md` exists.
 
 ```
 Suggested next action:
-  Run /gsdd:resume to restore paused session context
-  Also available: /gsdd:execute (ignore checkpoint, continue current phase), /gsdd:progress (refresh)
+  Run /gsdd-resume to restore paused session context
+  Also available: /gsdd-execute (ignore checkpoint, continue current phase), /gsdd-progress (refresh)
 ```
 
 **Branch B: Execute (PLAN without SUMMARY in current phase)**
@@ -131,8 +144,8 @@ Condition: Current phase has a PLAN file but no matching SUMMARY.
 
 ```
 Suggested next action:
-  Run /gsdd:execute to continue Phase [N] execution
-  Also available: /gsdd:plan (re-plan current phase), /gsdd:verify (if prior phase needs verification)
+  Run /gsdd-execute to continue Phase [N] execution
+  Also available: /gsdd-plan (re-plan current phase), /gsdd-verify (if prior phase needs verification)
 ```
 
 **Branch C: Plan (no PLAN for current phase)**
@@ -140,8 +153,8 @@ Condition: Current phase has no PLAN files.
 
 ```
 Suggested next action:
-  Run /gsdd:plan to create a plan for Phase [N]: [phase name]
-  Also available: /gsdd:quick (sub-hour task outside phases), /gsdd:map-codebase (refresh codebase maps)
+  Run /gsdd-plan to create a plan for Phase [N]: [phase name]
+  Also available: /gsdd-quick (sub-hour task outside phases), /gsdd-map-codebase (refresh codebase maps)
 ```
 
 **Branch D: Verify (SUMMARY without VERIFICATION)**
@@ -149,8 +162,8 @@ Condition: Current phase has SUMMARY but no VERIFICATION file (verifier enabled)
 
 ```
 Suggested next action:
-  Run /gsdd:verify to validate Phase [N]
-  Also available: /gsdd:execute (continue to next phase), /gsdd:plan (plan next phase)
+  Run /gsdd-verify to validate Phase [N]
+  Also available: /gsdd-execute (continue to next phase), /gsdd-plan (plan next phase)
 ```
 
 **Branch E: Audit milestone (all phases [x])**
@@ -158,17 +171,26 @@ Condition: All phases in ROADMAP.md are marked `[x]`.
 
 ```
 Suggested next action:
-  Run /gsdd:audit-milestone to audit the completed milestone
-  Also available: /gsdd:verify (re-verify a specific phase), /gsdd:quick (sub-hour task)
+  Run /gsdd-audit-milestone to audit the completed milestone
+  Also available: /gsdd-verify (re-verify a specific phase), /gsdd-quick (sub-hour task)
 ```
 
 **Branch F: Between milestones (SPEC.md exists, ROADMAP.md absent)**
 Condition: `.planning/SPEC.md` exists but `.planning/ROADMAP.md` does not — a milestone was completed and archived.
 
+Check `.planning/MILESTONES.md`:
+- If MILESTONES.md exists and has at least one milestone entry → this is a subsequent milestone
+- If MILESTONES.md does not exist or is empty → this is the first milestone setup
+
 ```
-Suggested next action:
-  Run /gsdd:new-project to start the next milestone cycle (create a new ROADMAP.md)
-  Also available: /gsdd:progress (refresh after milestone setup)
+Suggested next action (subsequent milestone):
+  Run /gsdd-new-milestone to start the next milestone cycle (gather goals, define requirements, create ROADMAP.md)
+  Also available: /gsdd-progress (refresh after milestone setup)
+
+Suggested next action (incomplete milestone state — SPEC.md exists but no milestone archived yet):
+  Inspect .planning/ manually — a milestone is likely still in progress.
+  If a ROADMAP.md was deleted prematurely, re-run /gsdd-new-milestone to restore it.
+  Do NOT run /gsdd-new-project — SPEC.md already exists and re-running would overwrite it.
 ```
 
 If none of the above conditions match, report that the project is in a clean state with no obvious next action.
@@ -178,7 +200,7 @@ If none of the above conditions match, report that the project is in a clean sta
 Handle compound states:
 
 - **Checkpoint + unexecuted plan:** Both `.continue-here.md` exists and a PLAN lacks a SUMMARY. Prioritize checkpoint (Branch A) but mention the unexecuted plan in the status block.
-- **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. Mention both — suggest clearing the stale checkpoint via `/gsdd:resume`, then routing to milestone audit.
+- **All phases complete + checkpoint:** All phases `[x]` but a checkpoint exists. Mention both — suggest clearing the stale checkpoint via `/gsdd-resume`, then routing to milestone audit.
 - **Phase done but next unplanned:** Current phase has both PLAN and SUMMARY, but the next phase has no PLAN. Show the current phase as complete and suggest planning the next phase (Branch C targeting the next phase).
 - **No matching condition:** If the project state does not match any branch, report it clearly and suggest the user inspect `.planning/` manually.
 </edge_cases>
@@ -193,7 +215,8 @@ Handle compound states:
 - [ ] Routing suggestion is specific (includes phase number and branch-specific output block)
 - [ ] Named branch output format used with "Also available" alternatives
 - [ ] No files created, modified, or deleted (read-only workflow)
-- [ ] All workflow references use portable `/gsdd:*` command format
+- [ ] All workflow references use portable `/gsdd-*` command format
 - [ ] No interactive menus, no numbered option lists, no waiting for user selection
 - [ ] Edge cases handled for compound states
+- [ ] Unmerged-commit warning only appears when `git log main..HEAD --oneline` returns output; silent when empty
 </success_criteria>