fix(workflow): improve phase transition routing, progress detection, and commit recovery

[Tibsfox]

Summary

This PR improves the reliability of GSD's workflow transition layer — the handoffs between planning, execution, verification, and progress routing. Four issues addressed across 4 files, ~95 lines total.

These changes build on the foundation fixes in PR #822 (phase lifecycle, milestone detection, state parsing). Together, they address the core plan-execute-advance loop that every GSD project relies on.

---

Changes

1. Progress routing: include roadmap phases in init data — Closes #689

The experience: Running /gsd:progress announces "Milestone Complete! All phases finished!" even though 4+ phases remain in the roadmap — they just haven't been scaffolded to disk yet. This has reproduced consistently across multiple sessions for users with multi-phase milestones.

Why it happens: init progress builds its phase overview by scanning .planning/phases/ directories. Phases defined in ROADMAP.md that haven't been planned yet don't have directories, so phase_count and completed_count end up equal. The progress workflow sees completed_count === phase_count and routes to "Milestone Complete."

The issue author identified this clearly: the current_phase, next_phase, phase_count, and completed_count fields from init "look authoritative but only reflect disk state." The LLM treats this output as self-sufficient and skips the roadmap analyze step that would reveal the unscaffolded phases.

The fix: After the disk scan, parse ROADMAP.md for phase headings. Add a roadmap_phase_count field that reflects the true total from the roadmap. When all disk phases are complete but the roadmap defines more, set next_phase to the first unscaffolded phase (with a roadmap_only: true marker so consumers can distinguish it from disk phases). The existing phase_count field stays unchanged — it still means "directories on disk" — so existing consumers aren't affected.

Files: bin/lib/init.cjs (+33 lines)

2. Verify-work routing after execution — Closes #117

The experience: When gsd-verifier returns human_needed, the execute-phase workflow displays a static text block listing items that need manual testing. But the user must manually discover and invoke /gsd:verify-work to actually perform the tests. Users may miss the items entirely, proceed to the next phase without testing, or not realize the phase is unverified.

The fix: Replace the passive text display with an AskUserQuestion offering three clear paths:

• Start /gsd:verify-work — run the interactive UAT workflow (with /clear recommended for fresh context)
• Mark all approved — skip manual testing and proceed
• Review verification report — see the full VERIFICATION.md before deciding

This is complementary to PR #819 (browser pre-verification) — #819 makes the verification process itself smarter, while this fix makes the transition to verification automatic. They work well together.

Files: workflows/execute-phase.md (+16 lines, -8 lines)

3. Execute-phase offer after planning — Closes #136

The experience: After planning completes (in the non-auto-advance case), the workflow shows a static suggestion to run /gsd:execute-phase. The user has to read the suggestion, understand it, and manually invoke the command. This creates an unnecessary friction point in the plan-execute loop.

The fix: Add an AskUserQuestion to the <offer_next> section offering to execute immediately, review plans first, or clear context for a fresh start. This only fires when auto-advance is NOT enabled — the auto-advance path (step 14) already handles the transition automatically.

This is different from autopilot mode (#796): autopilot auto-advances through the full chain without asking. This fix is about the interactive case — offering a choice, not forcing execution. They're complementary features.

Files: workflows/plan-phase.md (offer_next section, +22 lines, -6 lines)

4. Commit recovery for auto-advance chains — Partially addresses #668

The experience: When discuss-phase --auto chains through plan → execute, the executor writes all files correctly but never commits them. The entire working tree is left dirty with all implementation changes unstaged.

Why it happens: The auto-advance chain runs discuss → plan → execute → executor, reaching 4 levels of Task nesting. At that depth, git operations from the innermost Task agent may not persist back to the parent working directory. The files are written correctly — only the commits are lost. When execute-phase is run directly (2 levels deep), commits work fine.

Important context: This may be a Claude Code Task tool behavior with deeply-nested subagents rather than a GSD logic bug. The fix is a pragmatic workaround inspired by the "read-your-writes" pattern from distributed systems: after each auto-advance Task returns, the calling orchestrator checks git status for uncommitted changes and commits them. This is harmless if the upstream behavior is resolved — if there are no uncommitted changes, the recovery step is a no-op.

The recovery is placed at two points in the chain:

• plan-phase.md — after execute-phase Task returns (catches executor-level orphans)
• discuss-phase.md — after plan-phase Task returns (catches anything the inner recovery missed)

Files: workflows/plan-phase.md (+14 lines), workflows/discuss-phase.md (+17 lines)

---

Verification

Fix	Steps
#689	Create a project with 12 phases in ROADMAP.md, scaffold phases 1-12, complete all. Run init progress — should show roadmap_phase_count reflecting the full ROADMAP count and next_phase pointing to the first unscaffolded phase.
#117	Run execute-phase on a phase where the verifier returns human_needed. Verify that an AskUserQuestion prompt appears offering /gsd:verify-work, "Mark approved", or "Review report".
#136	Run plan-phase WITHOUT --auto. After planning completes, verify an AskUserQuestion prompt appears in <offer_next> offering to execute, review plans, or clear context.
#668	Run discuss-phase --auto through a full chain. After completion, check git log — source code changes from the executor should be committed (either by the executor directly or by the recovery step).

Overlap & Conflict Notes

This PR touches workflow files that are also modified by several active PRs from ethan-hurst:

• fix: convert inline questions to AskUserQuestion (#803) #807 (AskUserQuestion conversions) — our changes use AskUserQuestion, so they're semantically compatible
• feat: browser pre-verification for /gsd:verify-work #819 (browser pre-verification) — complementary to Auto-trigger /gsd:verify-work when gsd-verifier returns human_needed status #117 (different files, different concerns)
• feat: autopilot mode — full pipeline automation with synthetic multi-agent discuss #796 (autopilot mode) — complementary to Calling phase execution automatically after planning would be nice #136 (autopilot is auto, ours is interactive)

Our diff is small (~95 lines) and each commit is atomic, so rebasing after any of these merge should be straightforward. The maintainer can also cherry-pick individual commits if preferred.

Relationship to PR #822

PR #822 fixes the foundation-level bugs (phase lifecycle scanning, milestone detection, state parsing) that these workflow improvements depend on. Specifically:

• Bug: /gsd:progress routes to Milestone Complete when unscaffolded phases remain #689's fix is more effective when cmdPhaseComplete reports is_last_phase:true when future phases have no directories #709 (phase lifecycle) is also fixed — both address the "disk-only scanning" root cause, but at different layers (init vs phase-complete)
• Auto-trigger /gsd:verify-work when gsd-verifier returns human_needed status #117 and Calling phase execution automatically after planning would be nice #136 benefit from state-snapshot returns all nulls — regex format mismatch with STATE.md #730 (state parsing) being correct, since workflow routing depends on state data

These PRs can merge independently, but together they address the full chain from data layer through workflow routing.

---

🤖 Generated with Claude Code