@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/pr-branch.md

@@ -1,7 +1,8 @@
 <purpose>
-Create a clean branch for pull requests by filtering out .planning/ commits.
-The PR branch contains only code changes — reviewers don't see SDD artifacts
-(PLAN.md, SUMMARY.md, STATE.md, CONTEXT.md, etc.).
+Create a clean branch for pull requests by filtering out transient .planning/ commits.
+The PR branch contains only code changes and structural planning state — reviewers
+don't see SDD transient artifacts (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, etc.)
+but milestone archives, STATE.md, ROADMAP.md, and PROJECT.md changes are preserved.
 
 Uses git cherry-pick with path filtering to rebuild a clean history.
 </purpose>
@@ -48,24 +49,47 @@ Classify commits:
 git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges
 ```
 
-For each commit, check if it ONLY touches .planning/ files:
+**Structural planning files** — always preserved (repository planning state):
+- `.planning/STATE.md`
+- `.planning/ROADMAP.md`
+- `.planning/MILESTONES.md`
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/milestones/**`
+
+**Transient planning files** — excluded from PR branch (reviewer noise):
+- `.planning/phases/**` (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, etc.)
+- `.planning/quick/**`
+- `.planning/research/**`
+- `.planning/threads/**`
+- `.planning/todos/**`
+- `.planning/debug/**`
+- `.planning/seeds/**`
+- `.planning/codebase/**`
+- `.planning/ui-reviews/**`
+
+For each commit, check what it touches:
 
 ```bash
 # For each commit hash
 FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
-ALL_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
+NON_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
+STRUCTURAL=$(echo "$FILES" | grep -E "^\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\.md|^\.planning/milestones/" | wc -l)
+TRANSIENT_ONLY=$(echo "$FILES" | grep "^\.planning/" | grep -vE "^\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\.md|^\.planning/milestones/" | wc -l)
 ```
 
 Classify:
 - **Code commits**: Touch at least one non-.planning/ file → INCLUDE
-- **Planning-only commits**: Touch only .planning/ files → EXCLUDE
-- **Mixed commits**: Touch both → INCLUDE (planning changes come along)
+- **Structural planning commits**: Touch only structural .planning/ files (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md, REQUIREMENTS.md, milestones/**) → INCLUDE
+- **Transient planning commits**: Touch only transient .planning/ files (phases/, quick/, research/, etc.) → EXCLUDE
+- **Mixed commits**: Touch code + any planning files → INCLUDE (transient planning changes come along; acceptable in mixed context)
 
 Display analysis:
 ```
-Commits to include: {N} (code changes)
-Commits to exclude: {N} (planning-only)
+Commits to include: {N} (code changes + structural planning)
+Commits to exclude: {N} (transient planning-only)
 Mixed commits: {N} (code + planning — included)
+Structural planning commits: {N} (STATE/ROADMAP/milestone updates — included)
 ```
 </step>
 
@@ -77,13 +101,17 @@ PR_BRANCH="${CURRENT_BRANCH}-pr"
 git checkout -b "$PR_BRANCH" "$TARGET"
 ```
 
-Cherry-pick only code commits (in order):
+Cherry-pick code commits and structural planning commits (in order):
 
 ```bash
-for HASH in $CODE_COMMITS; do
+for HASH in $CODE_AND_STRUCTURAL_COMMITS; do
   git cherry-pick "$HASH" --no-commit
-  # Remove any .planning/ files that came along in mixed commits
-  git rm -r --cached .planning/ 2>/dev/null || true
+  # Remove only transient .planning/ subdirectories that came along in mixed commits.
+  # DO NOT remove structural files (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md,
+  # REQUIREMENTS.md, milestones/) — these must survive into the PR branch.
+  for dir in phases quick research threads todos debug seeds codebase ui-reviews; do
+    git rm -r --cached ".planning/$dir/" 2>/dev/null || true
+  done
   git commit -C "$HASH"
 done
 ```

package/sdd/workflows/profile-user.md

@@ -1,7 +1,7 @@
 <purpose>
 Orchestrate the full developer profiling flow: consent, session analysis (or questionnaire fallback), profile generation, result display, and artifact creation.
 
-This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing sdd-tools.cjs subcommands and the sdd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX.
+This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing `sdd-sdk query` handlers (with legacy `sdd-tools.cjs` parity where needed) and the sdd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX.
 </purpose>
 
 <required_reading>
@@ -9,7 +9,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 Key references:
 - @$HOME/.claude/sdd/references/ui-brand.md (display patterns)
-- @$HOME/.claude/sdd/agents/sdd-user-profiler.md (profiler agent definition)
+- @$HOME/.claude/agents/sdd-user-profiler.md (profiler agent definition)
 - @$HOME/.claude/sdd/references/user-profiling.md (profiling reference doc)
 </required_reading>
 
@@ -30,6 +30,8 @@ PROFILE_PATH="$HOME/.claude/sdd/USER-PROFILE.md"
 
 **If profile exists AND --refresh NOT set AND --questionnaire NOT set:**
 
+
+**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.
 Use AskUserQuestion:
 - header: "Existing Profile"
 - question: "You already have a profile. What would you like to do?"
@@ -46,7 +48,7 @@ If "Cancel": Display "No changes made." and exit.
 
 Backup existing profile:
 ```bash
-cp "$HOME/.claude/sdd/USER-PROFILE.md" "$HOME/.claude/sdd/USER-PROFILE.backup.md"
+cp "$HOME/.claude/sdd/USER-PROFILE.md" "$HOME/.claude/USER-PROFILE.backup.md"
 ```
 
 Display: "Re-analyzing your sessions to update your profile."
@@ -128,7 +130,7 @@ Display: "◆ Scanning sessions..."
 
 Run session scan:
 ```bash
-SCAN_RESULT=$(node $HOME/.claude/sdd/bin/sdd-tools.cjs scan-sessions --json 2>/dev/null)
+SCAN_RESULT=$(sdd-sdk query scan-sessions --json 2>/dev/null)
 ```
 
 Parse the JSON output to get session count and project count.
@@ -148,7 +150,7 @@ Display: "◆ Sampling messages..."
 
 Run profile sampling:
 ```bash
-SAMPLE_RESULT=$(node $HOME/.claude/sdd/bin/sdd-tools.cjs profile-sample --json 2>/dev/null)
+SAMPLE_RESULT=$(sdd-sdk query profile-sample --json 2>/dev/null)
 ```
 
 Parse the JSON output to get the temp directory path and message count.
@@ -199,7 +201,7 @@ Display: "Using questionnaire to build your profile."
 
 **Get questions:**
 ```bash
-QUESTIONS=$(node $HOME/.claude/sdd/bin/sdd-tools.cjs profile-questionnaire --json 2>/dev/null)
+QUESTIONS=$(sdd-sdk query profile-questionnaire --json 2>/dev/null)
 ```
 
 Parse the questions JSON. It contains 8 questions, one per dimension.
@@ -222,7 +224,7 @@ Write the answers JSON to `$ANSWERS_PATH`.
 
 **Convert answers to analysis:**
 ```bash
-ANALYSIS_RESULT=$(node $HOME/.claude/sdd/bin/sdd-tools.cjs profile-questionnaire --answers "$ANSWERS_PATH" --json 2>/dev/null)
+ANALYSIS_RESULT=$(sdd-sdk query profile-questionnaire --answers "$ANSWERS_PATH" --json 2>/dev/null)
 ```
 
 Parse the analysis JSON from the result.
@@ -269,7 +271,7 @@ Write updated analysis JSON back to `$ANALYSIS_PATH`.
 Display: "◆ Writing profile..."
 
 ```bash
-node $HOME/.claude/sdd/bin/sdd-tools.cjs write-profile --input "$ANALYSIS_PATH" --json 2>/dev/null
+sdd-sdk query write-profile --input "$ANALYSIS_PATH" --json
 ```
 
 Display: "✓ Profile written to $HOME/.claude/sdd/USER-PROFILE.md"
@@ -333,7 +335,7 @@ Use AskUserQuestion with multiSelect:
 - header: "Artifacts"
 - question: "Which artifacts should I generate?"
 - options (ALL pre-selected by default):
-  - "/sdd:dev-preferences command file" -- "Load your preferences in any session"
+  - "/sdd-dev-preferences command file" -- "Load your preferences in any session"
   - "CLAUDE.md profile section" -- "Add profile to this project's CLAUDE.md"
   - "Global CLAUDE.md" -- "Add profile to $HOME/.claude/CLAUDE.md for all projects"
 
@@ -345,18 +347,18 @@ Use AskUserQuestion with multiSelect:
 
 Generate selected artifacts sequentially (file I/O is fast, no benefit from parallel agents):
 
-**For /sdd:dev-preferences (if selected):**
+**For /sdd-dev-preferences (if selected):**
 
 ```bash
-node $HOME/.claude/sdd/bin/sdd-tools.cjs generate-dev-preferences --analysis "$ANALYSIS_PATH" --json 2>/dev/null
+sdd-sdk query generate-dev-preferences --analysis "$ANALYSIS_PATH" --json
 ```
 
-Display: "✓ Generated /sdd:dev-preferences at $HOME/.claude/commands/sdd/dev-preferences.md"
+Display: "✓ Generated /sdd-dev-preferences at $HOME/.claude/skills/sdd-dev-preferences/SKILL.md"
 
 **For CLAUDE.md profile section (if selected):**
 
 ```bash
-node $HOME/.claude/sdd/bin/sdd-tools.cjs generate-claude-profile --analysis "$ANALYSIS_PATH" --json 2>/dev/null
+sdd-sdk query generate-claude-profile --analysis "$ANALYSIS_PATH" --json
 ```
 
 Display: "✓ Added profile section to CLAUDE.md"
@@ -364,12 +366,12 @@ Display: "✓ Added profile section to CLAUDE.md"
 **For Global CLAUDE.md (if selected):**
 
 ```bash
-node $HOME/.claude/sdd/bin/sdd-tools.cjs generate-claude-profile --analysis "$ANALYSIS_PATH" --global --json 2>/dev/null
+sdd-sdk query generate-claude-profile --analysis "$ANALYSIS_PATH" --global --json
 ```
 
 Display: "✓ Added profile section to $HOME/.claude/CLAUDE.md"
 
-**Error handling:** If any sdd-tools.cjs call fails, display the error message and use AskUserQuestion to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact.
+**Error handling:** If any `sdd-sdk query` or sdd-tools.cjs call fails, display the error message and use AskUserQuestion to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact.
 
 ---
 
@@ -381,7 +383,7 @@ Read both old backup and new analysis to compare dimension ratings/confidence.
 
 Read the backed-up profile:
 ```bash
-BACKUP_PATH="$HOME/.claude/sdd/USER-PROFILE.backup.md"
+BACKUP_PATH="$HOME/.claude/USER-PROFILE.backup.md"
 ```
 
 Compare each dimension's rating and confidence between old and new. Display diff table showing only changed dimensions:
@@ -410,7 +412,7 @@ Your profile:    $HOME/.claude/sdd/USER-PROFILE.md
 Then list paths for each generated artifact:
 ```
 Artifacts:
-  ✓ /sdd:dev-preferences   $HOME/.claude/commands/sdd/dev-preferences.md
+  ✓ /sdd-dev-preferences   $HOME/.claude/skills/sdd-dev-preferences/SKILL.md
   ✓ CLAUDE.md section       ./CLAUDE.md
   ✓ Global CLAUDE.md        $HOME/.claude/CLAUDE.md
 ```
@@ -444,7 +446,7 @@ rm -f "$ANALYSIS_PATH" 2>/dev/null
 - [ ] Profile written to USER-PROFILE.md via write-profile subcommand
 - [ ] Result display shows report card table and highlight reel with evidence
 - [ ] Artifact selection uses multiSelect with all options pre-selected
-- [ ] Artifacts generated sequentially via sdd-tools.cjs subcommands
+- [ ] Artifacts generated sequentially via sdd-sdk query (or sdd-tools.cjs) subcommands
 - [ ] Refresh diff shows changed dimensions when --refresh was used
 - [ ] Temp files cleaned up on completion
 </success_criteria>

package/sdd/workflows/progress.md

@@ -12,14 +12,14 @@ Read all files referenced by the invoking prompt's execution_context before star
 **Load progress context (paths only):**
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init progress)
+INIT=$(sdd-sdk query init.progress)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.
 
 ```bash
-DISCUSS_MODE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+DISCUSS_MODE=$(sdd-sdk query config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
 ```
 
 If `project_exists` is false (no `.planning/` directory):
@@ -42,11 +42,11 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/sdd:new-project`.
 </step>
 
 <step name="load">
-**Use structured extraction from sdd-tools:**
+**Use structured extraction from `sdd-sdk query` (or legacy sdd-tools.cjs):**
 
 Instead of reading full files, use targeted tools to get only the data needed for the report:
-- `ROADMAP=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap analyze)`
-- `STATE=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state-snapshot)`
+- `ROADMAP=$(sdd-sdk query roadmap.analyze)`
+- `STATE=$(sdd-sdk query state-snapshot)`
 
 This minimizes orchestrator context usage.
 </step>
@@ -55,7 +55,7 @@ This minimizes orchestrator context usage.
 **Get comprehensive roadmap analysis (replaces manual parsing):**
 
 ```bash
-ROADMAP=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap analyze)
+ROADMAP=$(sdd-sdk query roadmap.analyze)
 ```
 
 This returns structured JSON with:
@@ -74,7 +74,7 @@ Use this instead of manually reading/parsing ROADMAP.md.
 - Find the 2-3 most recent SUMMARY.md files
 - Use `summary-extract` for efficient parsing:
   ```bash
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" summary-extract <path> --fields one_liner
+  sdd-sdk query summary-extract <path> --fields one_liner
   ```
 - This shows "what we've been working on"
   </step>
@@ -89,11 +89,16 @@ Use this instead of manually reading/parsing ROADMAP.md.
   </step>
 
 <step name="report">
-**Generate progress bar from sdd-tools, then present rich status report:**
+> ⚠️ Context authority: PROJECT.md, STATE.md, and ROADMAP.md are the authoritative sources
+> for project name, milestone, current phase, and next-step routing. CLAUDE.md ## Project
+> blocks are a secondary config aid that may be significantly stale — do NOT use the
+> CLAUDE.md project description as a source for any progress report field.
+
+**Generate progress bar from `sdd-sdk query progress` / `progress.json`, then present rich status report:**
 
 ```bash
 # Get formatted progress bar
-PROGRESS_BAR=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" progress bar --raw)
+PROGRESS_BAR=$(sdd-sdk query progress.bar --raw)
 ```
 
 Present:
@@ -123,7 +128,7 @@ CONTEXT: [✓ if has_context | - if not]
 - [e.g. jq -r '.blockers[].text' from state-snapshot]
 
 ## Pending Todos
-- [count] pending — /sdd:check-todos to review
+- [count] pending — /sdd:capture --list to review
 
 ## Active Debug Sessions
 - [count] active — /sdd:debug to continue
@@ -135,6 +140,31 @@ CONTEXT: [✓ if has_context | - if not]
 
 </step>
 
+<step name="mvp_display">
+**MVP-mode display (when phase has `**Mode:** mvp` in ROADMAP.md).**
+
+Resolve `MVP_MODE` per phase via the centralized resolver. progress has no `--mvp` CLI flag (mode is inherited from the planned phase), so we omit `--cli-flag`:
+
+```bash
+MVP_MODE=$(sdd-sdk query phase.mvp-mode "${PHASE_NUMBER}" --pick active)
+```
+
+When `MVP_MODE=true`, the per-phase progress block adds a **user-flow status** sub-block sourced from the phase's PLAN.md task names. Each task whose name reads like a user-visible capability (e.g., "Register flow", "Login flow", "Password reset") is rendered as a status line:
+
+```
+Phase 1 — User Auth MVP
+  ✅ Walking Skeleton complete           ← from SKELETON.md existence
+  ✅ Register flow working               ← from PLAN.md task with summary
+  ✅ Login flow working                  ← from PLAN.md task with summary
+  🔄 Password reset (in progress)        ← from PLAN.md task without summary
+  ⬜ Email verification                  ← from PLAN.md task not yet started
+```
+
+**User-flow filter:** Tasks whose names are technical-sounding ("Wire DB schema", "Create migration", "Bump deps") are NOT rendered as user-flow status lines. Heuristic: a task name is user-flow-shaped if it ends in "flow", "page", "screen", or starts with a verb the user would recognize ("Register", "Login", "Upload", "View"). Tasks that fail the heuristic still count toward the standard task progress total but don't appear in the user-flow sub-block.
+
+When `MVP_MODE=false` (mode is null, absent, or the phase has no `**Mode:**` line), fall back to the standard display path — no behavioral change.
+</step>
+
 <step name="route">
 **Determine next action based on verified counts.**
 
@@ -168,7 +198,7 @@ Track:
 Scan ALL phases in the current milestone for outstanding verification debt using the CLI (which respects milestone boundaries via `getMilestonePhaseFilter`):
 
 ```bash
-DEBT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" audit-uat --raw 2>/dev/null)
+DEBT=$(sdd-sdk query audit-uat --raw 2>/dev/null)
 ```
 
 Parse JSON for `summary.total_items` and `summary.total_files`.
@@ -211,13 +241,13 @@ Read its `<objective>` section.
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
 
-`/sdd:execute-phase {phase} ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:execute-phase {phase} ${SDD_WS}`
 
 ---
 ```
@@ -231,7 +261,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 Check if current phase has UI indicators:
 
 ```bash
-PHASE_SECTION=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${CURRENT_PHASE}" 2>/dev/null)
+PHASE_SECTION=$(sdd-sdk query roadmap.get-phase "${CURRENT_PHASE}" 2>/dev/null)
 PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")
 ```
 
@@ -240,14 +270,14 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 <sub>✓ Context gathered, ready to plan</sub>
 
-`/sdd:plan-phase {phase-number} ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:plan-phase {phase-number} ${SDD_WS}`
 
 ---
 ```
@@ -257,20 +287,20 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/sdd:discuss-phase {phase}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:discuss-phase {phase}` — gather context and clarify approach
 
 ---
 
 **Also available:**
 - `/sdd:ui-phase {phase}` — generate UI design contract (recommended for frontend phases)
 - `/sdd:plan-phase {phase}` — skip discussion, plan directly
-- `/sdd:list-phase-assumptions {phase}` — see Claude's assumptions
+- `/sdd:discuss-phase {phase}` — include assumptions check before planning
 
 ---
 ```
@@ -280,19 +310,19 @@ PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" ||
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/sdd:discuss-phase {phase} ${SDD_WS}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:discuss-phase {phase} ${SDD_WS}` — gather context and clarify approach
 
 ---
 
 **Also available:**
 - `/sdd:plan-phase {phase} ${SDD_WS}` — skip discussion, plan directly
-- `/sdd:list-phase-assumptions {phase} ${SDD_WS}` — see Claude's assumptions
+- `/sdd:discuss-phase {phase} ${SDD_WS}` — include assumptions check before planning
 
 ---
 ```
@@ -310,9 +340,9 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **{phase_num}-UAT.md** has {N} gaps requiring fixes.
 
-`/sdd:plan-phase {phase} --gaps ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:plan-phase {phase} --gaps ${SDD_WS}`
 
 ---
 
@@ -336,9 +366,9 @@ UAT.md exists with `status: partial` — testing session ended before all items
 
 **{phase_num}-UAT.md** has {N} unresolved tests (pending, blocked, or skipped).
 
-`/sdd:verify-work {phase} ${SDD_WS}` — resume testing from where you left off
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:verify-work {phase} ${SDD_WS}` — resume testing from where you left off
 
 ---
 
@@ -377,7 +407,7 @@ Read ROADMAP.md to get the next phase's name and goal.
 Check if next phase has UI indicators:
 
 ```bash
-NEXT_PHASE_SECTION=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "$((Z+1))" 2>/dev/null)
+NEXT_PHASE_SECTION=$(sdd-sdk query roadmap.get-phase "$((Z+1))" 2>/dev/null)
 NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")
 ```
 
@@ -388,13 +418,13 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 ## ✓ Phase {Z} Complete
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/sdd:discuss-phase {Z+1}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:discuss-phase {Z+1}` — gather context and clarify approach
 
 ---
 
@@ -413,13 +443,13 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 ## ✓ Phase {Z} Complete
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/sdd:discuss-phase {Z+1} ${SDD_WS}` — gather context and clarify approach
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:discuss-phase {Z+1} ${SDD_WS}` — gather context and clarify approach
 
 ---
 
@@ -441,13 +471,13 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 All {N} phases finished!
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Complete Milestone** — archive and prepare for next
 
-`/sdd:complete-milestone ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:complete-milestone ${SDD_WS}`
 
 ---
 
@@ -472,13 +502,13 @@ Read MILESTONES.md to find the last completed milestone version.
 
 Ready to plan the next milestone.
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Start Next Milestone** — questioning → research → requirements → roadmap
 
-`/sdd:new-milestone ${SDD_WS}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:new-milestone ${SDD_WS}`
 
 ---
 ```
@@ -492,7 +522,119 @@ Ready to plan the next milestone.
 - All work complete → offer milestone completion
 - Blockers present → highlight before offering to continue
 - Handoff file exists → mention it, offer `/sdd:resume-work ${SDD_WS}`
-  </step>
+</step>
+
+<step name="forensic_audit">
+**Forensic Integrity Audit** — only runs when `--forensic` is present in ARGUMENTS.
+
+If `--forensic` is NOT present in ARGUMENTS: skip this step entirely. Default progress behavior (standard report + routing) is unchanged.
+
+If `--forensic` IS present: after the standard report and routing suggestion have been displayed, append the following audit section.
+
+---
+
+## Forensic Integrity Audit
+
+Running 6 deep checks against project state...
+
+Run each check in order. For each check, emit ✓ (pass) or ⚠ (warning) with concrete evidence when a problem is found.
+
+**Check 1 — STATE vs artifact consistency**
+
+Read STATE.md `status` / `stopped_at` fields (from the STATE snapshot already loaded). Compare against the artifact count from the roadmap analysis. If STATE.md claims the current phase is pending/mid-flight but the artifact count shows it as complete (all PLAN.md files have matching SUMMARY.md files), flag inconsistency. Emit:
+- ✓ `STATE.md consistent with artifact count` — if both agree
+- ⚠ `STATE.md claims [status] but artifact count shows phase complete` — with the specific values
+
+**Check 2 — Orphaned handoff files**
+
+Check for existence of:
+```bash
+ls .planning/HANDOFF.json .planning/phases/*/.continue-here.md .planning/phases/*/*HANDOFF*.md 2>/dev/null || true
+```
+Also check `.planning/continue-here.md`.
+
+Emit:
+- ✓ `No orphaned handoff files` — if none found
+- ⚠ `Orphaned handoff files found` — list each file path, add: `→ Work was paused mid-flight. Read the handoff before continuing.`
+
+**Check 3 — Deferred scope drift**
+
+Search phase artifacts (CONTEXT.md, DISCUSSION-LOG.md, BUG-BRIEF.md, VERIFICATION.md, SUMMARY.md, HANDOFF.md files under `.planning/phases/`) for patterns:
+```bash
+grep -rl "defer to Phase\|future phase\|out of scope Phase\|deferred to Phase" .planning/phases/ 2>/dev/null || true
+```
+
+For each match, extract the referenced phase number. Cross-reference against ROADMAP.md phase list. If the referenced phase number is NOT in ROADMAP.md, flag as deferred scope not captured.
+
+Emit:
+- ✓ `All deferred scope captured in ROADMAP` — if no mismatches
+- ⚠ `Deferred scope references phase(s) not in ROADMAP` — list: file, reference text, missing phase number
+
+**Check 4 — Memory-flagged pending work**
+
+Check if `.planning/MEMORY.md` or `.planning/memory/` exists:
+```bash
+ls .planning/MEMORY.md .planning/memory/*.md 2>/dev/null || true
+```
+
+If found, grep for entries containing: `pending`, `status`, `deferred`, `not yet run`, `backfill`, `blocking`.
+
+Emit:
+- ✓ `No memory entries flagging pending work` — if none found or no MEMORY.md
+- ⚠ `Memory entries flag pending/deferred work` — list the matching lines (max 5, truncated at 80 chars)
+
+**Check 5 — Blocking operational todos**
+
+Check for pending todos:
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null || true
+```
+
+For files found, scan for keywords indicating operational blockers: `script`, `credential`, `API key`, `manual`, `verification`, `setup`, `configure`, `run `.
+
+Emit:
+- ✓ `No blocking operational todos` — if no pending todos or none match operational keywords
+- ⚠ `Blocking operational todos found` — list the file names and matching keywords (max 5)
+
+**Check 6 — Uncommitted code**
+
+```bash
+git status --porcelain 2>/dev/null | grep -v "^??" | grep -v "^.planning\/" | grep -v "^\.\." | head -10
+```
+
+If output is non-empty (modified/staged files outside `.planning/`), flag as uncommitted code.
+
+Emit:
+- ✓ `Working tree clean` — if no modified files outside `.planning/`
+- ⚠ `Uncommitted changes in source files` — list up to 10 file paths
+
+---
+
+After all 6 checks, display the verdict:
+
+**If all 6 checks passed:**
+```
+### Verdict: CLEAN
+
+The standard progress report is trustworthy — proceed with the routing suggestion above.
+```
+
+**If 1 or more checks failed:**
+```
+### Verdict: N INTEGRITY ISSUE(S) FOUND
+
+The standard progress report may not reflect true project state.
+Review the flagged items above before acting on the routing suggestion.
+```
+
+Then for each failed check, add a concrete next action:
+- Check 2 (orphaned handoff): `Read the handoff file(s) and resume from where work was paused: /sdd:resume-work ${SDD_WS}`
+- Check 3 (deferred scope): `Add the missing phases to ROADMAP.md or update the deferred references`
+- Check 4 (memory pending): `Review the flagged memory entries and resolve or clear them`
+- Check 5 (blocking todos): `Complete the operational steps in .planning/todos/pending/ before continuing`
+- Check 6 (uncommitted code): `Commit or stash the uncommitted changes before advancing`
+- Check 1 (STATE inconsistency): `Run /sdd:verify-work ${PHASE} ${SDD_WS} to reconcile state`
+</step>
 
 </process>