@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/mvp-phase.md

@@ -0,0 +1,221 @@
+<purpose>
+Guide the user through MVP-mode planning for a phase. Prompts for an "As a / I want to / So that" user story, runs SPIDR splitting check on the story, writes the result to ROADMAP.md, and delegates to `/sdd plan-phase` (which auto-detects MVP via the roadmap mode field shipped in PRD Phase 1).
+</purpose>
+
+<required_reading>
+@~/.claude/sdd/references/user-story-template.md
+@~/.claude/sdd/references/spidr-splitting.md
+@~/.claude/sdd/references/planner-mvp-mode.md
+</required_reading>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+
+**TEXT_MODE fallback:** Set TEXT_MODE=true if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number.
+</runtime_note>
+
+<process>
+
+## 1. Parse and validate phase argument
+
+Extract the phase number from `$ARGUMENTS` (integer or decimal like `2.1`). Optional flag: `--force` (allow operating on `in_progress` / `completed` phases).
+
+If no argument:
+```
+ERROR: Phase number required
+Usage: /sdd mvp-phase <phase-number>
+Example: /sdd mvp-phase 1
+Example: /sdd mvp-phase 2.1
+```
+Exit.
+
+Normalize per `@~/.claude/sdd/references/phase-argument-parsing.md` (zero-pad integer phases to two digits).
+
+## 2. Validate phase exists and check status
+
+```bash
+PHASE_INFO=$(sdd-sdk query roadmap.get-phase "${PHASE}")
+PHASE_FOUND=$(echo "$PHASE_INFO" | jq -r '.found')
+PHASE_NAME=$(echo "$PHASE_INFO" | jq -r '.phase_name')
+PHASE_GOAL=$(echo "$PHASE_INFO" | jq -r '.goal')
+PHASE_MODE=$(echo "$PHASE_INFO" | jq -r '.mode // ""')
+PHASE_COMPLETE=$(echo "$PHASE_INFO" | jq -r '.roadmap_complete // false')
+
+ANALYZE=$(sdd-sdk query roadmap.analyze)
+if [[ "$ANALYZE" == @file:* ]]; then ANALYZE=$(cat "${ANALYZE#@file:}"); fi
+DISK_STATUS=$(echo "$ANALYZE" | jq -r --arg p "$PHASE" '.phases[] | select((.phase_number|tostring)==$p) | .disk_status' | head -1)
+if [[ "$DISK_STATUS" == "complete" || "$PHASE_COMPLETE" == "true" ]]; then
+  STATUS="completed"
+elif [[ "$DISK_STATUS" == "planned" || "$DISK_STATUS" == "partial" ]]; then
+  STATUS="in_progress"
+else
+  STATUS="not_started"
+fi
+```
+
+If `PHASE_FOUND` is `false`: error and exit. Suggest `/sdd add-phase` or `/sdd insert-phase` to create the phase first.
+
+**Status guard.** If the phase is `in_progress` (has plans but not complete) or `completed`, refuse unless `--force` is in `$ARGUMENTS`:
+
+```text
+ERROR: Phase ${PHASE} is currently ${STATUS}.
+Converting an active or completed phase to MVP mode mid-flight will
+invalidate any existing plans and summaries.
+
+To proceed anyway: /sdd mvp-phase ${PHASE} --force
+```
+
+**Already-MVP guard.** If `PHASE_MODE` is already `mvp`, surface this and ask whether to re-prompt the user story or abort:
+
+> "Phase ${PHASE} is already in MVP mode with goal: «${PHASE_GOAL}». Re-run user-story prompts and SPIDR check?"
+
+Use `AskUserQuestion` with options [Re-prompt / Abort]. On Abort, exit cleanly. On Re-prompt, proceed.
+
+## 3. User story prompts
+
+Run three sequential `AskUserQuestion` calls. Each is free-text. After all three, assemble into the canonical sentence per `@~/.claude/sdd/references/user-story-template.md`:
+
+**Prompt 1 — As a:**
+> "As a [user role]?"
+> (Examples: "new user", "admin", "signed-in customer", "API consumer")
+
+**Prompt 2 — I want to:**
+> "I want to [capability]?"
+> (Examples: "register and log in", "upload a CSV", "see my dashboard")
+
+**Prompt 3 — So that:**
+> "So that [outcome]?"
+> (Examples: "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention")
+
+Assemble:
+
+```
+USER_STORY="As a ${ROLE}, I want to ${CAPABILITY}, so that ${OUTCOME}."
+```
+
+If any of the three answers is empty or whitespace-only, error and re-prompt that single field. Do NOT proceed with a partial story.
+
+**Validate via the centralized User Story validator.** The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and surfaces per-error guidance:
+
+```bash
+USER_STORY_RESULT=$(sdd-sdk query user-story.validate --story "$USER_STORY")
+if [ "$(echo "$USER_STORY_RESULT" | jq -r '.valid')" != "true" ]; then
+  echo "$USER_STORY_RESULT" | jq -r '.errors[]' >&2
+  # Re-prompt the offending field(s) per surfaced errors, then re-run validation.
+  # Do not abort the workflow on first invalid draft.
+  RE_PROMPT_USER_STORY=true
+fi
+```
+
+This guarantees the goal stored in ROADMAP.md will satisfy the same guard the verifier applies later.
+If `RE_PROMPT_USER_STORY=true`, re-run only the offending prompt field(s), rebuild `USER_STORY`, and validate again before continuing.
+
+## 4. SPIDR splitting check
+
+Run the SPIDR rules from `@~/.claude/sdd/references/spidr-splitting.md`. Briefly:
+
+**Trigger evaluation.** Check the assembled `USER_STORY` against the four size signals from the reference (compound capabilities, multi-actor, length > 120 chars, vague capability). If none fire, **skip SPIDR** entirely — go to step 5.
+
+**If SPIDR triggers.**
+
+a) Restate the story to the user:
+
+> "Your story: «${USER_STORY}»
+>
+> This story has [signal description, e.g., 'two compound capabilities joined by and']. Splitting it into multiple phases will produce a cleaner Walking Skeleton and reduce the risk of mid-phase scope creep.
+>
+> Want to walk through SPIDR splitting?"
+
+Use `AskUserQuestion` with options [Yes, walk through SPIDR / No, proceed with the story as-is].
+
+If "No": skip SPIDR, go to step 5.
+
+If "Yes": continue to (b).
+
+b) Ask which SPIDR axis fits best:
+
+> "Which axis best fits how to split this story?"
+
+Use `AskUserQuestion` with the five options from `spidr-splitting.md` (Spike / Paths / Interfaces / Data / Rules). Each option includes its targeted question as the description so the user can pick by understanding what each axis means.
+
+c) Walk through the chosen axis with **one** targeted question (not all five). For example, if the user picked "Paths":
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+Free-text response. Workflow parses to identify the split.
+
+d) Produce a split proposal. Example:
+
+> "Proposed split (Paths axis):
+> - **Phase ${PHASE} (this one):** Happy path — ${HAPPY_STORY}
+> - **Phase ${PHASE+1} (new):** Edge case — ${EDGE_STORY}
+>
+> Accept this split?"
+
+Use `AskUserQuestion` [Accept / Modify / Reject].
+
+- **Accept**: `USER_STORY` becomes the first split's story (`${HAPPY_STORY}` in the example). Surface the remaining splits as a list of `/sdd add-phase` invocations the user can run after this command completes — do NOT auto-create the new phases (preserve user control over numbering).
+- **Modify**: re-prompt the splits one more time, then accept or reject.
+- **Reject**: revert `USER_STORY` to the original, proceed without splitting.
+
+## 5. Update ROADMAP.md
+
+Read `ROADMAP.md`. Find the section for `Phase ${PHASE}`. Apply two edits:
+
+**Edit 1 — Update Goal line.**
+
+Find: `**Goal:** ${OLD_GOAL_TEXT}`
+Replace with: `**Goal:** ${USER_STORY}`
+
+**Edit 2 — Insert Mode line.**
+
+If `**Mode:**` already exists in the section (replacing or re-running), update it to `**Mode:** mvp`.
+If `**Mode:**` does not exist, insert `**Mode:** mvp` on the line immediately after `**Goal:**`.
+
+Show the user a unified diff (lines being changed) and ask:
+
+> "Apply these changes to ROADMAP.md?"
+
+Use `AskUserQuestion` [Apply / Cancel]. On Cancel, exit without writing.
+
+On Apply, write the updated `ROADMAP.md` atomically (read-edit-write).
+
+## 6. Verify the write
+
+```bash
+NEW_MODE=$(sdd-sdk query roadmap.get-phase "${PHASE}" --pick mode)
+NEW_GOAL=$(sdd-sdk query roadmap.get-phase "${PHASE}" --pick goal)
+```
+
+Assert:
+- `NEW_MODE` equals `mvp`
+- `NEW_GOAL` equals the assembled user story
+
+If either assertion fails, surface the discrepancy to the user and exit. Do not proceed to plan-phase delegation with a half-applied write.
+
+## 7. Delegate to /sdd plan-phase
+
+Invoke `/sdd plan-phase ${PHASE}` (no flags). Phase 1's MVP_MODE resolution chain (CLI flag → roadmap mode → config → false) will detect the new `**Mode:** mvp` line and run plan-phase in vertical-slice mode automatically.
+
+The Walking Skeleton gate (also from Phase 1) will fire automatically if `${PHASE} == "01"` and there are zero prior phase summaries.
+
+## 8. Surface deferred phase splits (if any)
+
+If SPIDR produced a split in step 4, append a final user-facing message:
+
+> "**SPIDR split deferred phases.**
+>
+> Your original story was split. The first slice is now planned via plan-phase.
+> To create the remaining slice(s) as new phases, run:
+>
+> - `/sdd add-phase` — for the next slice: «${SPLIT_2_STORY}»
+> - `/sdd add-phase` — for the next slice: «${SPLIT_3_STORY}»
+>
+> Each will be added to the end of the current milestone. You can then run
+> `/sdd mvp-phase <new-phase-number>` on each to plan them as MVP slices."
+
+## 9. Exit
+
+Workflow ends. The phase is now in MVP mode with a planned PLAN.md, optionally with deferred follow-up phases surfaced for the user.
+
+</process>

package/sdd/workflows/new-milestone.md

@@ -30,7 +30,7 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 - Read PROJECT.md (existing project, validated requirements, decisions)
 - Read MILESTONES.md (what shipped previously)
 - Read STATE.md (pending todos, blockers)
-- Check for MILESTONE-CONTEXT.md (from /sdd:discuss-milestone)
+- Check for MILESTONE-CONTEXT.md (from /sdd-discuss-milestone)
 
 ## 2. Gather Milestone Goals
 
@@ -40,10 +40,61 @@ If the flag is absent, keep the current behavior of continuing phase numbering f
 
 **If no context file:**
 - Present what shipped in last milestone
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 - Ask inline (freeform, NOT AskUserQuestion): "What do you want to build next?"
 - Wait for their response, then use AskUserQuestion to probe specifics
 - If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another AskUserQuestion
 
+## 2.5. Scan Planted Seeds
+
+Check `.planning/seeds/` for seed files that match the milestone goals gathered in step 2.
+
+```bash
+ls .planning/seeds/SEED-*.md 2>/dev/null
+```
+
+**If no seed files exist:** Skip this step silently — do not print any message or prompt.
+
+**If seed files exist:** Read each `SEED-*.md` file and extract from its frontmatter and body:
+- **Idea** — the seed title (heading after frontmatter, e.g. `# SEED-001: <idea>`)
+- **Trigger conditions** — the `trigger_when` frontmatter field and the "When to Surface" section's bullet list
+- **Planted during** — the `planted_during` frontmatter field (for context)
+
+Compare each seed's trigger conditions against the milestone goals from step 2. A seed matches when its trigger conditions are relevant to any of the milestone's target features or goals.
+
+**If no seeds match:** Skip silently — do not prompt the user.
+
+**If matching seeds found:**
+
+**`--auto` mode:** Auto-select ALL matching seeds. Log: `[auto] Selected N matching seed(s): [list seed names]`
+
+**Text mode (`TEXT_MODE=true`):** Present matching seeds as a plain-text numbered list:
+```
+Seeds that match your milestone goals:
+1. SEED-001: <idea> (trigger: <trigger_when>)
+2. SEED-003: <idea> (trigger: <trigger_when>)
+
+Enter numbers to include (comma-separated), or "none" to skip:
+```
+
+**Normal mode:** Present via AskUserQuestion:
+```
+AskUserQuestion(
+  header: "Seeds",
+  question: "These planted seeds match your milestone goals. Include any in this milestone's scope?",
+  multiSelect: true,
+  options: [
+    { label: "SEED-001: <idea>", description: "Trigger: <trigger_when> | Planted during: <planted_during>" },
+    ...
+  ]
+)
+```
+
+**After selection:**
+- Selected seeds become additional context for requirement definition in step 9. Store them in an accumulator (e.g. `$SELECTED_SEEDS`) so step 9 can reference the ideas and their "Why This Matters" sections when defining requirements.
+- Unselected seeds remain untouched in `.planning/seeds/` — never delete or modify seed files during this workflow.
+
 ## 3. Determine Milestone Version
 
 - Parse last version from MILESTONES.md
@@ -106,7 +157,7 @@ Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects cre
 
 This document evolves at phase transitions and milestone boundaries.
 
-**After each phase transition** (via `/sdd:transition`):
+**After each phase transition** (via `/sdd-transition`):
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
@@ -122,6 +173,19 @@ This document evolves at phase transitions and milestone boundaries.
 
 ## 5. Update STATE.md
 
+Reset STATE.md frontmatter AND body atomically via the SDK. This writes the new
+milestone version/name into the YAML frontmatter, resets `status` to
+`planning`, zeroes `progress.*` counters, and rewrites the `## Current Position`
+section to the new-milestone template. Accumulated Context (decisions,
+blockers, todos) is preserved across the switch — symmetric with
+`milestone.complete`.
+
+```bash
+sdd-sdk query state.milestone-switch --milestone "v[X.Y]" --name "[Name]"
+```
+
+The resulting Current Position section looks like:
+
 ```markdown
 ## Current Position
 
@@ -131,27 +195,51 @@ Status: Defining requirements
 Last activity: [today] — Milestone v[X.Y] started
 ```
 
-Keep Accumulated Context section from previous milestone.
+Bug #2630: a prior version of this workflow rewrote the Current Position body
+manually but left the frontmatter pointing at the previous milestone, so every
+downstream reader (`state.json`, `getMilestoneInfo`, progress bars) reported the
+stale milestone until the first phase advance forced a resync. Always use the
+SDK handler above — do not hand-edit STATE.md here.
 
 ## 6. Cleanup and Commit
 
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
+Clear leftover phase directories from the previous milestone:
+
+```bash
+sdd-sdk query phases.clear --confirm
+```
+
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+sdd-sdk query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init new-milestone)
+INIT=$(sdd-sdk query init.new-milestone)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_RESEARCHER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-project-researcher 2>/dev/null)
-AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-synthesizer 2>/dev/null)
-AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-roadmapper 2>/dev/null)
+AGENT_SKILLS_RESEARCHER=$(sdd-sdk query agent-skills sdd-project-researcher)
+AGENT_SKILLS_SYNTHESIZER=$(sdd-sdk query agent-skills sdd-research-synthesizer)
+AGENT_SKILLS_ROADMAPPER=$(sdd-sdk query agent-skills sdd-roadmapper)
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`, `agents_installed`, `missing_agents`.
+
+**If `agents_installed` is false:** Display a warning before proceeding:
+```
+⚠ SDD agents not installed. The following agents are missing from your agents directory:
+  {missing_agents joined with newline}
+
+Subagent spawns (sdd-project-researcher, sdd-research-synthesizer, sdd-roadmapper) will fail
+with "agent type not found". Run the installer with --global to make agents available:
+
+  npx @bhargavvc/sdd-cc@latest --global
+
+Proceeding without research subagents — roadmap will be generated inline.
+```
+Skip the parallel research spawn step and generate the roadmap inline.
 
 ## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
 
@@ -209,8 +297,8 @@ mkdir -p .planning/research
 Spawn 4 parallel sdd-project-researcher agents. Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
-```
-Task(prompt="
+```text
+Agent(prompt="
 <research_type>Project Research — {DIMENSION} for [new features].</research_type>
 
 <milestone_context>
@@ -248,10 +336,12 @@ Use template: ~/.claude/sdd/templates/research-project/{FILE}
 | GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
 | FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all 4 researcher Agent() calls above, do NOT read research files or synthesize content independently while the subagents are active. Wait for all 4 researchers to complete before spawning the synthesizer. This prevents duplicate work and wasted context.
+
 After all 4 complete, spawn synthesizer:
 
-```
-Task(prompt="
+```text
+Agent(prompt="
 Synthesize research outputs into SUMMARY.md.
 
 <files_to_read>
@@ -269,6 +359,8 @@ Commit after writing.
 ", subagent_type="sdd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
 Display key findings from SUMMARY.md:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -292,6 +384,8 @@ Display key findings from SUMMARY.md:
 
 Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
 
+**If `$SELECTED_SEEDS` is non-empty (from step 2.5):** Include selected seed ideas and their "Why This Matters" sections as additional input when defining requirements. Seeds provide user-validated feature ideas that should be incorporated into the requirement categories alongside research findings or conversation-gathered features.
+
 **If research exists:** Read FEATURES.md, extract feature categories.
 
 Present features by category:
@@ -350,7 +444,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+sdd-sdk query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -367,8 +461,8 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: define milestone v[X.Y]
 - If `--reset-phase-numbers` is active, start at **Phase 1**
 - Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6)
 
-```
-Task(prompt="
+```text
+Agent(prompt="
 <planning_context>
 <files_to_read>
 - .planning/PROJECT.md
@@ -399,6 +493,8 @@ Write files first, then return.
 ", subagent_type="sdd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
 **Handle return:**
 
 **If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
@@ -434,7 +530,57 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+sdd-sdk query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 10.5. Link Pending Todos to Roadmap Phases
+
+After roadmap approval, scan pending todos against the newly approved phases. For each todo whose scope matches a phase, tag it with `resolves_phase: N` in its YAML frontmatter.
+
+**Check for pending todos:**
+```bash
+PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | head -50)
+```
+
+**If no pending todos exist:** Skip this step silently.
+
+**If pending todos exist:**
+
+Read the approved ROADMAP.md and extract the phase list: phase number, phase name, goal, and requirement IDs.
+
+For each pending todo, compare:
+- The todo's `title` and `area` frontmatter fields
+- The todo body (Problem and Solution sections)
+
+Against each phase's:
+- Phase goal
+- Requirement IDs and descriptions
+
+**Match criteria (best-effort — do not over-match):** A todo is considered resolved by a phase if the phase's goal or requirements directly describe implementing the same feature, area, or capability as the todo. Narrow, specific todos with concrete scopes are the best candidates. Vague or cross-cutting todos should be left unlinked.
+
+**For each matched todo**, add `resolves_phase: [N]` to the YAML frontmatter block (after the existing fields):
+```yaml
+---
+created: [existing]
+title: [existing]
+area: [existing]
+resolves_phase: [N]
+files: [existing]
+---
+```
+
+**Only modify todos that have a clear, confident match.** Leave unmatched todos unmodified.
+
+**If any todos were linked:**
+```bash
+sdd-sdk query commit "docs: tag [count] pending todos with resolves_phase after milestone v[X.Y] roadmap" --files .planning/todos/pending/*.md
+```
+
+Print a summary:
+```
+◆ Linked [N] pending todos to roadmap phases:
+  → [todo title] → Phase [N]: [Phase Name]
+  (Leave [M] unmatched todos in pending/)
 ```
 
 ## 11. Done
@@ -455,13 +601,13 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: create milestone v[X.Y]
 
 **[N] phases** | **[X] requirements** | Ready to build ✓
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/sdd:discuss-phase [N] ${SDD_WS}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:discuss-phase [N] ${SDD_WS}` — gather context and clarify approach
 
 Also: `/sdd:plan-phase [N] ${SDD_WS}` — skip discussion, plan directly
 ```
@@ -480,7 +626,9 @@ Also: `/sdd:plan-phase [N] ${SDD_WS}` — skip discussion, plan directly
 - [ ] User feedback incorporated (if any)
 - [ ] Phase numbering mode respected (continued or reset)
 - [ ] All commits made (if planning docs committed)
+- [ ] Pending todos scanned for phase matches; matched todos tagged with `resolves_phase: N`
 - [ ] User knows next step: `/sdd:discuss-phase [N] ${SDD_WS}`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>
+</output>