@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/templates/state.md

@@ -66,6 +66,14 @@ None yet.
 
 None yet.
 
+## Deferred Items
+
+Items acknowledged and carried forward from previous milestone close:
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* | | | |
+
 ## Session Continuity
 
 Last session: [YYYY-MM-DD HH:MM]
@@ -148,7 +156,7 @@ Updated after each plan completion.
 **Pending Todos:** Ideas captured via /sdd-add-todo
 - Count of pending todos
 - Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /sdd-check-todos")
+- Brief list if few, count if many (e.g., "5 pending todos — see /sdd:capture --list")
 
 **Blockers/Concerns:** From "Next Phase Readiness" sections
 - Issues that affect future work

package/sdd/workflows/add-backlog.md

@@ -0,0 +1,90 @@
+# Add Backlog Item Workflow
+
+Invoked by `/sdd:capture --backlog` (`commands/sdd/capture.md`).
+
+Adds an idea to the ROADMAP.md backlog parking lot using 999.x numbering. Backlog items
+are unsequenced ideas that aren't ready for active planning — they live outside the normal
+phase sequence and accumulate context over time.
+
+<process>
+
+## Step 1: Read ROADMAP.md
+
+Check for existing backlog entries:
+
+```bash
+cat .planning/ROADMAP.md
+```
+
+## Step 2: Find next backlog number
+
+```bash
+NEXT=$(sdd-sdk query phase.next-decimal 999 --raw)
+```
+
+If no 999.x phases exist yet, `phase.next-decimal` returns `999.1`. Sparse numbering
+is fine (e.g. 999.1, 999.3) — always use `phase.next-decimal`, never guess.
+
+## Step 3: Write ROADMAP entry
+
+**Write the ROADMAP entry BEFORE creating the directory.** Directory existence is a
+reliable indicator that the phase is already registered, which prevents false duplicate
+detection in any hook that checks for existing 999.x directories (#2280).
+
+Add under a `## Backlog` section. If the section doesn't exist, create it at the end
+of ROADMAP.md:
+
+```markdown
+## Backlog
+
+### Phase {NEXT}: {description} (BACKLOG)
+
+**Goal:** [Captured for future planning]
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (promote with /sdd:review-backlog when ready)
+```
+
+## Step 4: Create the phase directory
+
+Apply the `project_code` prefix (if set in `.planning/config.json`) so the backlog directory name is consistent with all other phase-creation paths:
+
+```bash
+SLUG=$(sdd-sdk query generate-slug "$ARGUMENTS" --raw)
+PROJECT_CODE=$(sdd-sdk query config-get project_code --raw 2>/dev/null || echo "")
+PREFIX=$([ -n "$PROJECT_CODE" ] && echo "${PROJECT_CODE}-" || echo "")
+PHASE_DIR=".planning/phases/${PREFIX}${NEXT}-${SLUG}"
+mkdir -p "${PHASE_DIR}"
+touch "${PHASE_DIR}/.gitkeep"
+```
+
+## Step 5: Commit
+
+```bash
+sdd-sdk query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
+```
+
+## Step 6: Report
+
+```
+## 📋 Backlog Item Added
+
+Phase {NEXT}: {description}
+Directory: {PHASE_DIR}/
+
+This item lives in the backlog parking lot.
+Use /sdd:discuss-phase {NEXT} to explore it further.
+Use /sdd:review-backlog to promote items to active milestone.
+```
+
+</process>
+
+<notes>
+- 999.x numbering keeps backlog items out of the active phase sequence
+- Phase directories are created immediately so /sdd:discuss-phase and /sdd:plan-phase work on them
+- No `Depends on:` field — backlog items are unsequenced by definition
+- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
+- Promote backlog items to the active milestone with /sdd:review-backlog
+</notes>

package/sdd/workflows/add-phase.md

@@ -29,23 +29,23 @@ Exit.
 Load phase operation context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "0")
+INIT=$(sdd-sdk query init.phase-op "0")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
 Check `roadmap_exists` from init JSON. If false:
 ```
 ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /sdd-new-project to initialize.
+Run /sdd:new-project to initialize.
 ```
 Exit.
 </step>
 
 <step name="add_phase">
-**Delegate the phase addition to sdd-tools:**
+**Delegate the phase addition to `sdd-sdk query phase.add`:**
 
 ```bash
-RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase add "${description}")
+RESULT=$(sdd-sdk query phase.add "${description}")
 ```
 
 The CLI handles:
@@ -83,13 +83,13 @@ Roadmap updated: .planning/ROADMAP.md
 
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase {N}: {description}**
 
 `/clear` then:
 
-`/sdd-plan-phase {N}`
+`/sdd:plan-phase {N}`
 
 ---
 
@@ -104,7 +104,7 @@ Roadmap updated: .planning/ROADMAP.md
 </process>
 
 <success_criteria>
-- [ ] `sdd-tools phase add` executed successfully
+- [ ] `sdd-sdk query phase.add` executed successfully
 - [ ] Phase directory created
 - [ ] Roadmap updated with new phase entry
 - [ ] STATE.md updated with roadmap evolution note

package/sdd/workflows/add-tests.md

@@ -1,7 +1,7 @@
 <purpose>
 Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Users currently hand-craft `/sdd-quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
+Users currently hand-craft `/sdd:quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
 </purpose>
 
 <required_reading>
@@ -15,15 +15,15 @@ Parse `$ARGUMENTS` for:
 - Phase number (integer, decimal, or letter-suffix) → store as `$PHASE_ARG`
 - Remaining text after phase number → store as `$EXTRA_INSTRUCTIONS` (optional)
 
-Example: `/sdd-add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
+Example: `/sdd:add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
 
 If no phase argument provided:
 
 ```
 ERROR: Phase number required
-Usage: /sdd-add-tests <phase> [additional instructions]
-Example: /sdd-add-tests 12
-Example: /sdd-add-tests 12 focus on edge cases in the pricing module
+Usage: /sdd:add-tests <phase> [additional instructions]
+Example: /sdd:add-tests 12
+Example: /sdd:add-tests 12 focus on edge cases in the pricing module
 ```
 
 Exit.
@@ -33,7 +33,7 @@ Exit.
 Load phase operation context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${PHASE_ARG}")
+INIT=$(sdd-sdk query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -54,7 +54,7 @@ Read the phase artifacts (in order of priority):
 If no SUMMARY.md exists:
 ```
 ERROR: No SUMMARY.md found for phase ${PHASE_ARG}
-This command works on completed phases. Run /sdd-execute-phase first.
+This command works on completed phases. Run /sdd:execute-phase first.
 ```
 Exit.
 
@@ -300,7 +300,7 @@ Create a test coverage report and present to user:
 
 Record test generation in project state:
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state-snapshot
+sdd-sdk query state-snapshot
 ```
 
 If there are passing tests to commit:
@@ -315,10 +315,10 @@ Present next steps:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 {if bugs discovered:}
-**Fix discovered bugs:** `/sdd-quick fix the {N} test failures discovered in phase ${phase_number}`
+**Fix discovered bugs:** `/sdd:quick fix the {N} test failures discovered in phase ${phase_number}`
 
 {if blocked tests:}
 **Resolve test blockers:** {description of what's needed}
@@ -329,8 +329,8 @@ Present next steps:
 ---
 
 **Also available:**
-- `/sdd-add-tests {next_phase}` — test another phase
-- `/sdd-verify-work {phase_number}` — run UAT verification
+- `/sdd:add-tests {next_phase}` — test another phase
+- `/sdd:verify-work {phase_number}` — run UAT verification
 
 ---
 ```

package/sdd/workflows/add-todo.md

@@ -12,7 +12,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 Load todo context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init todos)
+INIT=$(sdd-sdk query init.todos)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -86,7 +86,7 @@ Use values from init context: `timestamp` and `date` are already available.
 
 Generate slug for the title:
 ```bash
-slug=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" generate-slug "$title" --raw)
+slug=$(sdd-sdk query generate-slug "$title" --raw)
 ```
 
 Write to `.planning/todos/pending/${date}-${slug}.md`:
@@ -121,7 +121,7 @@ If `.planning/STATE.md` exists:
 Commit the todo and any updated state:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+sdd-sdk query commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.
@@ -143,7 +143,7 @@ Would you like to:
 
 1. Continue with current work
 2. Add another todo
-3. View all todos (/sdd-check-todos)
+3. View all todos (/sdd:capture --list)
 ```
 </step>
 

package/sdd/workflows/ai-integration-phase.md

@@ -20,7 +20,7 @@ This prevents the two most common AI development failures: choosing the wrong fr
 ## 1. Initialize
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init plan-phase "$PHASE")
+INIT=$(sdd-sdk query init.plan-phase "$PHASE")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -30,31 +30,31 @@ Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded
 
 Resolve agent models:
 ```bash
-SELECTOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-framework-selector --raw)
-RESEARCHER_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-ai-researcher --raw)
-DOMAIN_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-domain-researcher --raw)
-PLANNER_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-eval-planner --raw)
+SELECTOR_MODEL=$(sdd-sdk query resolve-model sdd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+RESEARCHER_MODEL=$(sdd-sdk query resolve-model sdd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+DOMAIN_MODEL=$(sdd-sdk query resolve-model sdd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+PLANNER_MODEL=$(sdd-sdk query resolve-model sdd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)
 ```
 
 Check config:
 ```bash
-AI_PHASE_ENABLED=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ai_integration_phase 2>/dev/null || echo "true")
+AI_PHASE_ENABLED=$(sdd-sdk query config-get workflow.ai_integration_phase 2>/dev/null || echo "true")
 ```
 
 **If `AI_PHASE_ENABLED` is `false`:**
 ```
-AI phase is disabled in config. Enable via /sdd-settings.
+AI phase is disabled in config. Enable via /sdd:settings.
 ```
 Exit workflow.
 
-**If `planning_exists` is false:** Error — run `/sdd-new-project` first.
+**If `planning_exists` is false:** Error — run `/sdd:new-project` first.
 
 ## 2. Parse and Validate Phase
 
 Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
 
 ```bash
-PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHASE}")
+PHASE_INFO=$(sdd-sdk query roadmap.get-phase "${PHASE}")
 ```
 
 **If `found` is false:** Error with available phases.
@@ -64,7 +64,7 @@ PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHA
 **If `has_context` is false:**
 ```
 No CONTEXT.md found for Phase {N}.
-Recommended: run /sdd-discuss-phase {N} first to capture framework preferences.
+Recommended: run /sdd:discuss-phase {N} first to capture framework preferences.
 Continuing without user decisions — framework selector will ask all questions.
 ```
 Continue (non-blocking).
@@ -122,7 +122,7 @@ Goal: {phase_goal}
 
 Parse selector output for: `primary_framework`, `system_type`, `model_provider`, `eval_concerns`, `alternative_framework`.
 
-**If selector fails or returns empty:** Exit with error — "Framework selection failed. Re-run /sdd-ai-integration-phase {N} or answer the framework question in /sdd-discuss-phase {N} first."
+**If selector fails or returns empty:** Exit with error — "Framework selection failed. Re-run /sdd:ai-integration-phase {N} or answer the framework question in /sdd:discuss-phase {N} first."
 
 ## 6. Initialize AI-SPEC.md
 
@@ -139,6 +139,8 @@ Fill in header fields:
 
 ## 7. Spawn sdd-ai-researcher
 
+> **Ordering note (prevents tool-level last-writer-wins race):** Steps 7 and 8 write disjoint sections of AI-SPEC.md but MUST run sequentially — wait for Step 7 to complete before spawning Step 8. Both agents use the `Edit` tool exclusively (never `Write`) when modifying AI-SPEC.md. A `Write` on a shared file replaces the entire file, silently overwriting the other agent's work; `Edit` targets only the relevant lines. See #3096 for a confirmed 40%-incidence race on parallel dispatch.
+
 Display:
 ```
 ◆ Step 2/4 — Researching {primary_framework} docs + AI systems best practices...
@@ -148,9 +150,12 @@ Spawn `sdd-ai-researcher` with:
 ```markdown
 Read ~/.claude/agents/sdd-ai-researcher.md for instructions.
 
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
 <objective>
-Research {primary_framework} for Phase {phase_number}: {phase_name}
-Write Sections 3 and 4 of AI-SPEC.md
 </objective>
 
 <files_to_read>
@@ -169,6 +174,8 @@ phase_context: Phase {phase_number}: {phase_name} — {phase_goal}
 
 ## 8. Spawn sdd-domain-researcher
 
+> **Wait for Step 7 to complete before spawning this step** (see ordering note in Step 7).
+
 Display:
 ```
 ◆ Step 3/4 — Researching domain context and expert evaluation criteria...
@@ -178,9 +185,12 @@ Spawn `sdd-domain-researcher` with:
 ```markdown
 Read ~/.claude/agents/sdd-domain-researcher.md for instructions.
 
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
 <objective>
-Research the business domain and expert evaluation criteria for Phase {phase_number}: {phase_name}
-Write Section 1b (Domain Context) of AI-SPEC.md
 </objective>
 
 <files_to_read>
@@ -266,7 +276,7 @@ git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} +
 ◆ Output: {ai_spec_path}
 
 Next step:
-  /sdd-plan-phase {N}   — planner will consume AI-SPEC.md
+  /sdd:plan-phase {N}   — planner will consume AI-SPEC.md
 ```
 
 </process>

package/sdd/workflows/analyze-dependencies.md

@@ -1,12 +1,12 @@
 <purpose>
-Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/sdd-manager`.
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/sdd:manager`.
 </purpose>
 
 <process>
 
 ## 1. Load ROADMAP.md
 
-Read `.planning/ROADMAP.md`. If it does not exist, error: "No ROADMAP.md found — run `/sdd-new-project` first."
+Read `.planning/ROADMAP.md`. If it does not exist, error: "No ROADMAP.md found — run `/sdd:new-project` first."
 
 Extract all phases. For each phase capture:
 - Phase number and name
@@ -91,6 +91,6 @@ When writing to ROADMAP.md:
 - Preserve all other phase content unchanged
 - Do not reorder phases
 
-After applying: "ROADMAP.md updated. Run `/sdd-manager` to execute phases in the correct order."
+After applying: "ROADMAP.md updated. Run `/sdd:manager` to execute phases in the correct order."
 
 </process>

package/sdd/workflows/audit-fix.md

@@ -32,7 +32,7 @@ Invoke the source audit command and capture output.
 
 For `audit-uat` source:
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init audit-uat 2>/dev/null || echo "{}")
+INIT=$(sdd-sdk query audit-uat 2>/dev/null || echo "{}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -95,15 +95,35 @@ For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
 **a. Spawn executor agent:**
 ```
-Task(
+Agent(
   prompt="Fix finding {ID}: {description}. Files: {file_refs}. Make the minimal change to resolve this specific finding. Do not refactor surrounding code.",
   subagent_type="sdd-executor"
 )
 ```
 
+> **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.
+
 **b. Run tests:**
 ```bash
-npm test 2>&1 | tail -20
+AUDIT_TEST_CMD=$(sdd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$AUDIT_TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    AUDIT_TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    AUDIT_TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    AUDIT_TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    AUDIT_TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    AUDIT_TEST_CMD="go test ./..."
+  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    AUDIT_TEST_CMD="python -m pytest -x -q --tb=short"
+  else
+    AUDIT_TEST_CMD="true"
+  fi
+fi
+eval "$AUDIT_TEST_CMD" 2>&1 | tail -20
 ```
 
 **c. If tests pass** — commit atomically:

package/sdd/workflows/audit-milestone.md

@@ -16,23 +16,23 @@ Valid SDD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize Milestone Context
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init milestone-op)
+INIT=$(sdd-sdk query init.milestone-op)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_CHECKER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-integration-checker 2>/dev/null)
+AGENT_SKILLS_CHECKER=$(sdd-sdk query agent-skills sdd-integration-checker)
 ```
 
 Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
 
 Resolve integration checker model:
 ```bash
-integration_checker_model=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-integration-checker --raw)
+integration_checker_model=$(sdd-sdk query resolve-model sdd-integration-checker --raw)
 ```
 
 ## 1. Determine Milestone Scope
 
 ```bash
 # Get phases in milestone (sorted numerically, handles decimals)
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phases list
+sdd-sdk query phases.list
 ```
 
 - Parse version from arguments or detect current from ROADMAP.md
@@ -46,7 +46,7 @@ For each phase directory, read the VERIFICATION.md:
 
 ```bash
 # For each phase, use find-phase to resolve the directory (handles archived phases)
-PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" find-phase 01 --raw)
+PHASE_INFO=$(sdd-sdk query find-phase 01 --raw)
 # Extract directory from JSON, then read VERIFICATION.md from that directory
 # Repeat for each phase number from ROADMAP.md
 ```
@@ -67,7 +67,7 @@ With phase context collected:
 Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.
 
 ```
-Task(
+Agent(
   prompt="Check cross-phase integration and E2E flows.
 
 Phases: {phase_dirs}
@@ -86,6 +86,8 @@ ${AGENT_SKILLS_CHECKER}",
 )
 ```
 
+> **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.
+
 ## 4. Collect Results
 
 Combine:
@@ -113,7 +115,7 @@ For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmat
 ```bash
 for summary in .planning/phases/*-*/*-SUMMARY.md; do
   [ -e "$summary" ] || continue
-  node "$HOME/.claude/sdd/bin/sdd-tools.cjs" summary-extract "$summary" --fields requirements_completed --pick requirements_completed
+  sdd-sdk query summary-extract "$summary" --fields requirements_completed --pick requirements_completed
 done
 ```
 
@@ -141,7 +143,7 @@ For each REQ-ID, determine status using all three sources:
 Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled).
 
 ```bash
-NYQUIST_CONFIG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.nyquist_validation --raw 2>/dev/null)
+NYQUIST_CONFIG=$(sdd-sdk query config-get workflow.nyquist_validation --raw 2>/dev/null)
 ```
 
 If `false`: skip entirely.
@@ -158,7 +160,7 @@ Classify per phase:
 
 Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
 
-Discovery only — never auto-calls `/sdd-validate-phase`.
+Discovery only — never auto-calls `/sdd:validate-phase`.
 
 ## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
 
@@ -225,13 +227,13 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 ───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Complete milestone** — archive and tag
 
 /clear then:
 
-/sdd-complete-milestone {version}
+/sdd:complete-milestone {version}
 
 ───────────────────────────────────────────────────────────────
 
@@ -264,25 +266,36 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 | Phase | VALIDATION.md | Compliant | Action |
 |-------|---------------|-----------|--------|
-| {phase} | exists/missing | true/false/partial | `/sdd-validate-phase {N}` |
+| {phase} | exists/missing | true/false/partial | `/sdd:validate-phase {N}` |
 
-Phases needing validation: run `/sdd-validate-phase {N}` for each flagged phase.
+Phases needing validation: run `/sdd:validate-phase {N}` for each flagged phase.
 
 ───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
-**Plan gap closure** — create phases to complete milestone
+**Close the gaps inline** — gap planning happens as part of this audit's
+output (see the Unsatisfied Requirements, Cross-Phase Issues, Broken Flows,
+and Nyquist Coverage sections above). Insert one closure phase per gap (or
+per group of related gaps) using the standard phase chain:
 
 /clear then:
 
-/sdd-plan-milestone-gaps
+/sdd:phase --insert <N> "Close gap: <REQ-ID> — <description>"
+/sdd:discuss-phase <N>
+/sdd:plan-phase <N>
+/sdd:execute-phase <N>
+
+For Nyquist-coverage gaps flagged in the table above, prefer running
+`/sdd:validate-phase <N>` for each flagged phase (and `/sdd:secure-phase
+<N>` if SECURITY.md was flagged) before inserting a new closure phase —
+they may close the gap retroactively without a new phase.
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
 - cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
-- /sdd-complete-milestone {version} — proceed anyway (accept tech debt)
+- /sdd:complete-milestone {version} — proceed anyway (accept tech debt)
 
 ───────────────────────────────────────────────────────────────
 
@@ -312,13 +325,17 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 
 **A. Complete milestone** — accept debt, track in backlog
 
-/sdd-complete-milestone {version}
+/sdd:complete-milestone {version}
 
-**B. Plan cleanup phase** — address debt before completing
+**B. Plan a cleanup phase** — address the debt above before completing.
+Insert a closure phase using the standard chain:
 
 /clear then:
 
-/sdd-plan-milestone-gaps
+/sdd:phase --insert <N> "Address tech debt: <area>"
+/sdd:discuss-phase <N>
+/sdd:plan-phase <N>
+/sdd:execute-phase <N>
 
 ───────────────────────────────────────────────────────────────
 </offer_next>

package/sdd/workflows/audit-uat.md

@@ -8,7 +8,7 @@ Cross-phase audit of all UAT and verification files. Finds every outstanding ite
 Run the CLI audit:
 
 ```bash
-AUDIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" audit-uat --raw)
+AUDIT=$(sdd-sdk query audit-uat --raw)
 ```
 
 Parse JSON for `results` array and `summary` object.
@@ -76,9 +76,9 @@ Present the audit report:
 
 ## Recommended Actions
 
-1. **Close stale items:** `/sdd-verify-work {phase}` — mark stale tests as resolved
+1. **Close stale items:** `/sdd:verify-work {phase}` — mark stale tests as resolved
 2. **Run active tests:** Human UAT test plan below
-3. **When prerequisites met:** Retest blocked items with `/sdd-verify-work {phase}`
+3. **When prerequisites met:** Retest blocked items with `/sdd:verify-work {phase}`
 ```
 </step>