@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/workflows/validate-phase.md

@@ -16,19 +16,19 @@ Valid SDD subagent types (use exact names — do not fall back to 'general-purpo
 ## 0. Initialize
 
 ```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
-AGENT_SKILLS_AUDITOR=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-nyquist-auditor 2>/dev/null)
+AGENT_SKILLS_AUDITOR=$(sdd-sdk query agent-skills sdd-nyquist-auditor)
 ```
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 
 ```bash
-AUDITOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-nyquist-auditor --raw)
-NYQUIST_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.nyquist_validation --raw)
+AUDITOR_MODEL=$(sdd-sdk query resolve-model sdd-nyquist-auditor --raw)
+NYQUIST_CFG=$(sdd-sdk query config-get workflow.nyquist_validation --raw)
 ```
 
-If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /sdd-settings."
+If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /sdd:settings."
 
 Display banner: `SDD > VALIDATE PHASE {N}: {name}`
 
@@ -41,7 +41,7 @@ SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
 
 - **State A** (`VALIDATION_FILE` non-empty): Audit existing
 - **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
-- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /sdd-execute-phase {N} ${SDD_WS} first."
+- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /sdd:execute-phase {N} ${SDD_WS} first."
 
 ## 2. Discovery
 
@@ -93,7 +93,7 @@ Call AskUserQuestion with gap table and options:
 ## 5. Spawn sdd-nyquist-auditor
 
 ```
-Task(
+Agent(
   prompt="Read ~/.claude/agents/sdd-nyquist-auditor.md for instructions.\n\n" +
     "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
     "<gaps>{gap list}</gaps>" +
@@ -106,6 +106,8 @@ Task(
 )
 ```
 
+> **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:
 - `## GAPS FILLED` → record tests + map updates, Step 6
 - `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
@@ -137,7 +139,7 @@ Handle return:
 git add {test_files}
 git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
 
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(phase-${PHASE}): add/update validation strategy"
+sdd-sdk query commit "docs(phase-${PHASE}): add/update validation strategy"
 ```
 
 ## 8. Results + Routing
@@ -146,14 +148,14 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(phase-${PHASE}): add/upd
 ```
 SDD > PHASE {N} IS NYQUIST-COMPLIANT
 All requirements have automated verification.
-▶ Next: /sdd-audit-milestone ${SDD_WS}
+▶ Next: /sdd:audit-milestone ${SDD_WS}
 ```
 
 **Partial:**
 ```
 SDD > PHASE {N} VALIDATED (PARTIAL)
 {M} automated, {K} manual-only.
-▶ Retry: /sdd-validate-phase {N} ${SDD_WS}
+▶ Retry: /sdd:validate-phase {N} ${SDD_WS}
 ```
 
 Display `/clear` reminder.

package/sdd/workflows/verify-phase.md

@@ -29,7 +29,7 @@ Then verify each level against the actual codebase.
 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
 ```
 
@@ -37,14 +37,14 @@ Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `has_plans`,
 
 Then load phase details and list plans/summaries:
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${phase_number}"
+sdd-sdk query roadmap.get-phase "${phase_number}"
 grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null || true
 ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null || true
 ```
 
 Load full milestone phases for deferred-item filtering (Step 9b):
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap analyze
+sdd-sdk query roadmap.analyze
 ```
 
 Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks), **requirements** from REQUIREMENTS.md if it exists, and **all milestone phases** from roadmap analyze (for cross-referencing gaps against later phases).
@@ -53,11 +53,11 @@ Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks), **req
 <step name="establish_must_haves">
 **Option A: Must-haves in PLAN frontmatter**
 
-Use sdd-tools to extract must_haves from each PLAN:
+Use `sdd-sdk query` verify handlers (or legacy sdd-tools) to extract must_haves from each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  MUST_HAVES=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" frontmatter get "$plan" --field must_haves)
+  MUST_HAVES=$(sdd-sdk query frontmatter.get "$plan" --field must_haves)
   echo "=== $plan ===" && echo "$MUST_HAVES"
 done
 ```
@@ -71,7 +71,7 @@ Aggregate all must_haves across plans for phase-level verification.
 If no must_haves in frontmatter (MUST_HAVES returns error or empty), check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${phase_number}" --raw)
+PHASE_DATA=$(sdd-sdk query roadmap.get-phase "${phase_number}" --raw)
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -103,11 +103,11 @@ For each truth: identify supporting artifacts → check artifact status → chec
 </step>
 
 <step name="verify_artifacts">
-Use sdd-tools for artifact verification against must_haves in each PLAN:
+Use `sdd-sdk query verify.artifacts` (or legacy sdd-tools) for artifact verification against must_haves in each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  ARTIFACT_RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" verify artifacts "$plan")
+  ARTIFACT_RESULT=$(sdd-sdk query verify.artifacts "$plan")
   echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
 done
 ```
@@ -146,11 +146,11 @@ wiring or leftover code from plan revisions.
 </step>
 
 <step name="verify_wiring">
-Use sdd-tools for key link verification against must_haves in each PLAN:
+Use `sdd-sdk query verify.key-links` (or legacy sdd-tools) for key link verification against must_haves in each PLAN:
 
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
-  LINKS_RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" verify key-links "$plan")
+  LINKS_RESULT=$(sdd-sdk query verify.key-links "$plan")
   echo "=== $plan ===" && echo "$LINKS_RESULT"
 done
 ```
@@ -183,6 +183,57 @@ grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null || true
 For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN.
 </step>
 
+<step name="verify_decisions">
+**Decision coverage validation gate (issue #2492).**
+
+After requirements coverage, also check that each trackable CONTEXT.md
+`<decisions>` entry shows up somewhere in the shipped artifacts (plans,
+SUMMARY.md, files modified by the phase, or recent commit subjects on the
+phase branch).
+
+This gate is **non-blocking / warning only** by deliberate asymmetry with
+the plan-phase translation gate. The plan-phase gate already blocked at
+translation time, so by the time verification runs every decision has
+either been translated or explicitly deferred. This gate's job is to
+surface decisions that *were* translated but vanished during execution —
+that's a soft signal because "honors a decision" is a fuzzy substring
+heuristic, and we don't want a paraphrase miss to fail an otherwise good
+phase.
+
+**Skip if** `workflow.context_coverage_gate` is explicitly set to `false`
+(absent key = enabled). Also skip cleanly when CONTEXT.md is missing or has
+no `<decisions>` block.
+
+```bash
+GATE_CFG=$(sdd-sdk query config-get workflow.context_coverage_gate 2>/dev/null || echo "true")
+if [ "$GATE_CFG" != "false" ]; then
+  # Discover the phase CONTEXT.md via glob expansion rather than `ls | head`
+  # (review F17 / ShellCheck SC2012). Globs preserve filenames containing
+  # spaces and avoid an extra subprocess.
+  CONTEXT_PATH=""
+  for f in "${PHASE_DIR}"/*-CONTEXT.md; do
+    [ -e "$f" ] && CONTEXT_PATH="$f" && break
+  done
+  DECISION_RESULT=$(sdd-sdk query check.decision-coverage-verify "${PHASE_DIR}" "${CONTEXT_PATH}")
+fi
+```
+
+The handler returns JSON `{ skipped, blocking: false, total, honored,
+not_honored: [...], message }`.
+
+**Reporting:** Append the handler's `message` (a `### Decision Coverage`
+section) to VERIFICATION.md regardless of outcome — even when all
+decisions are honored, recording the count helps reviewers spot drift over
+time. Set `decision_coverage` in the verification result to
+`{honored, total, not_honored: [...]}` so downstream tooling can read it.
+
+**Status impact:** none. The decision gate does NOT influence the
+`gaps_found` / `human_needed` / `passed` decision tree in
+`determine_status`. Its findings are warnings the user reviews and may act
+on by re-opening the phase or by acknowledging the decision was abandoned
+intentionally.
+</step>
+
 <step name="behavioral_verification">
 **Run the project's test suite and CLI commands to verify behavior, not just structure.**
 
@@ -197,22 +248,29 @@ inspecting static artifacts.
 **Step 1: Run test suite**
 
 ```bash
+# Resolve test command: project config > Makefile > language sniff
+TEST_CMD=$(sdd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    TEST_CMD="go test ./..."
+  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    TEST_CMD="python -m pytest -q --tb=short 2>&1 || uv run python -m pytest -q --tb=short"
+  else
+    TEST_CMD="false"
+    echo "⚠ No test runner detected — skipping test suite"
+  fi
+fi
 # Detect test runner and run all tests (timeout: 5 minutes)
 TEST_EXIT=0
-timeout 300 bash -c '
-if [ -f "package.json" ]; then
-  npm test 2>&1
-elif [ -f "Cargo.toml" ]; then
-  cargo test 2>&1
-elif [ -f "go.mod" ]; then
-  go test ./... 2>&1
-elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
-  python -m pytest -q --tb=short 2>&1 || uv run python -m pytest -q --tb=short 2>&1
-else
-  echo "⚠ No test runner detected — skipping test suite"
-  exit 1
-fi
-'
+timeout 300 bash -c "$TEST_CMD" 2>&1
 TEST_EXIT=$?
 if [ "${TEST_EXIT}" -eq 0 ]; then
   echo "✓ Test suite passed"
@@ -271,7 +329,8 @@ Extract files modified in this phase from SUMMARY.md, scan each:
 
 | Pattern | Search | Severity |
 |---------|--------|----------|
-| TODO/FIXME/XXX/HACK | `grep -n -E "TODO\|FIXME\|XXX\|HACK"` | ⚠️ Warning |
+| TBD/FIXME/XXX without same-line `issue #123`, `PR #123`, `#123`, or `DEF-*` reference | `grep -n -e TBD -e FIXME -e XXX` | 🛑 Blocker |
+| TODO/HACK | `grep -n -e TODO -e HACK` | ⚠️ Warning |
 | Placeholder content | `grep -n -iE "placeholder\|coming soon\|will be here"` | 🛑 Blocker |
 | Empty returns | `grep -n -E "return null\|return \{\}\|return \[\]\|=> \{\}"` | ⚠️ Warning |
 | Log-only functions | Functions containing only console.log | ⚠️ Warning |
@@ -367,9 +426,34 @@ If a requirement specifies a quantity of test cases (e.g., "30 calculations"), c
 </step>
 
 <step name="identify_human_verification">
-**Always needs human:** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
+**First: determine if this is an infrastructure/foundation phase.**
+
+Infrastructure and foundation phases — code foundations, database schema, internal APIs, data models, build tooling, CI/CD, internal service integrations — have no user-facing elements by definition. For these phases:
+
+- Do NOT invent artificial manual steps (e.g., "manually run git commits", "manually invoke methods", "manually check database state").
+- Mark human verification as **N/A** with rationale: "Infrastructure/foundation phase — no user-facing elements to test manually."
+- Set `human_verification: []` and do **not** produce a `human_needed` status solely due to lack of user-facing features.
+- Only add human verification items if the phase goal or success criteria explicitly describe something a user would interact with (UI, CLI command output visible to end users, external service UX).
+
+**How to determine if a phase is infrastructure/foundation:**
+- Phase goal or name contains: "foundation", "infrastructure", "schema", "database", "internal API", "data model", "scaffolding", "pipeline", "tooling", "CI", "migrations", "service layer", "backend", "core library"
+- Phase success criteria describe only technical artifacts (files exist, tests pass, schema is valid) with no user interaction required
+- There is no UI, CLI output visible to end users, or real-time behavior to observe
+
+**If the phase IS infrastructure/foundation:** auto-pass UAT — skip the human verification items list entirely. Log:
+
+```markdown
+## Human Verification
+
+N/A — Infrastructure/foundation phase with no user-facing elements.
+All acceptance criteria are verifiable programmatically.
+```
+
+**If the phase IS user-facing:** Only flag items that genuinely require a human. Do not invent steps.
+
+**Always needs human (user-facing phases only):** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
 
-**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state-dependent behavior, edge cases.
+**Needs human if uncertain (user-facing phases only):** Complex wiring grep can't trace, dynamic state-dependent behavior, edge cases.
 
 Format each as: Test Name → What to do → Expected result → Why can't verify programmatically.
 </step>
@@ -447,6 +531,7 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 - [ ] All artifacts checked at all three levels
 - [ ] All key links verified
 - [ ] Requirements coverage assessed (if applicable)
+- [ ] CONTEXT.md decisions checked against shipped artifacts (#2492 — non-blocking)
 - [ ] Anti-patterns scanned and categorized
 - [ ] Test quality audited (disabled tests, circular patterns, assertion strength, provenance)
 - [ ] Human verification items identified

package/sdd/workflows/verify-work.md

@@ -1,5 +1,5 @@
 <purpose>
-Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /sdd-plan-phase --gaps.
+Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /sdd:plan-phase --gaps.
 
 User tests, Claude records. One test at a time. Plain text responses.
 </purpose>
@@ -30,20 +30,31 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 If $ARGUMENTS contains a phase number, load context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init verify-work "${PHASE_ARG}")
+SDD_WS=""
+echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[^[:space:]]+' && SDD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[^[:space:]]+')
+PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[^[:space:]]+//g' | xargs)
+
+INIT=$(sdd-sdk query init.verify-work "${PHASE_ARG}" ${SDD_WS})
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_PLANNER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-planner 2>/dev/null)
-AGENT_SKILLS_CHECKER=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-checker 2>/dev/null)
+AGENT_SKILLS_PLANNER=$(sdd-sdk query agent-skills sdd-planner)
+AGENT_SKILLS_CHECKER=$(sdd-sdk query agent-skills sdd-plan-checker)
 ```
 
 Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`.
+
+```bash
+# MVP mode detection via the centralized phase.mvp-mode resolver.
+# verify-work has no --mvp CLI flag (mode is inherited from the planned phase),
+# so we omit --cli-flag — the verb falls through roadmap → config → false.
+MVP_MODE=$(sdd-sdk query phase.mvp-mode "${phase_number}" ${SDD_WS} --pick active)
+```
 </step>
 
 <step name="check_active_session">
 **First: Check for active UAT sessions**
 
 ```bash
-(find .planning/phases -name "*-UAT.md" -type f 2>/dev/null || true) | head -5
+(find .planning/phases -name "*-UAT.md" -type f 2>/dev/null || true)
 ```
 
 **If active sessions exist AND no $ARGUMENTS provided:**
@@ -78,7 +89,7 @@ If no, continue to `create_uat_file`.
 ```
 No active UAT sessions.
 
-Provide a phase number to start testing (e.g., /sdd-verify-work 4)
+Provide a phase number to start testing (e.g., /sdd:verify-work 4)
 ```
 
 **If no active sessions AND $ARGUMENTS provided:**
@@ -93,7 +104,7 @@ Before running manual UAT, check whether this phase has a UI component and wheth
 `mcp__playwright__*` or `mcp__puppeteer__*` tools are available in the current session.
 
 ```
-UI_PHASE_FLAG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ui_phase --raw 2>/dev/null || echo "true")
+UI_PHASE_FLAG=$(sdd-sdk query config-get workflow.ui_phase --raw 2>/dev/null || echo "true")
 UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 ```
 
@@ -135,6 +146,29 @@ Read each SUMMARY.md to extract testable deliverables.
 </step>
 
 <step name="extract_tests">
+**MVP-mode UAT framing.** When `MVP_MODE=true`, follow the rules in `@~/.claude/sdd/references/verify-mvp-mode.md`. Briefly:
+
+1. Generate the UAT script in three ordered sections: (a) user-flow walk-through derived from the phase's user-story goal, (b) technical checks (deferred — only run after user flow passes), (c) coverage check (goal-backward, narrowed to the user story's outcome clause).
+2. **User-flow steps run first.** Each step is one user action: open, fill, click, type, observe. No HTTP verbs, no JSON shapes, no error codes in user-flow steps.
+3. **Technical checks are deferred.** They run AFTER the user flow passes — same checks as non-MVP mode (endpoint schemas, error states, edge cases), just reordered.
+4. **If user-flow step N fails, do not advance.** The verdict is FAIL; technical checks do not run. The user can re-run after fixing the underlying flow.
+
+When `MVP_MODE=false` (mode is null, absent, or the phase has no `**Mode:**` line in ROADMAP.md), fall back to the standard UAT generation path — no behavioral change.
+
+**User-story format guard.** When `MVP_MODE=true`, also verify the phase's goal is in User Story format via the centralized validator:
+
+```bash
+PHASE_GOAL=$(sdd-sdk query roadmap.get-phase "${phase_number}" ${SDD_WS} --pick goal)
+USER_STORY_VALID=$(sdd-sdk query user-story.validate --story "$PHASE_GOAL" --pick valid)
+if [ "$USER_STORY_VALID" != "true" ]; then
+  echo "Phase ${phase_number} has '**Mode:** mvp' in ROADMAP.md but the **Goal:** is not in user-story format."
+  echo "Run /sdd mvp-phase ${phase_number} to set a user-story goal before verifying."
+  exit 1
+fi
+```
+
+The verb owns the canonical regex `/^As a .+, I want to .+, so that .+\.$/` and returns slot extractions plus per-error guidance when invalid. Halt UAT generation on failure — never attempt to derive user-flow steps from a non-User-Story goal (low-quality UAT).
+
 **Extract testable deliverables from SUMMARY.md:**
 
 Parse for:
@@ -233,7 +267,7 @@ Proceed to `present_test`.
 Render the checkpoint from the structured UAT file instead of composing it freehand:
 
 ```bash
-CHECKPOINT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" uat render-checkpoint --file "$uat_path" --raw)
+CHECKPOINT=$(sdd-sdk query uat.render-checkpoint --file "$uat_path" --raw)
 if [[ "$CHECKPOINT" == @file:* ]]; then CHECKPOINT=$(cat "${CHECKPOINT#@file:}"); fi
 ```
 
@@ -391,7 +425,7 @@ Clear Current Test section:
 
 Commit the UAT file:
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
+sdd-sdk query commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
 ```
 
 Present summary:
@@ -415,27 +449,27 @@ Present summary:
 **If issues == 0:**
 
 ```bash
-SECURITY_CFG=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+SECURITY_CFG=$(sdd-sdk query config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
 If `SECURITY_CFG` is `true` AND `SECURITY_FILE` is empty:
 ```
-⚠ Security enforcement enabled — /sdd-secure-phase {phase} has not run.
+⚠ Security enforcement enabled — /sdd:secure-phase {phase} has not run.
 Run before advancing to the next phase.
 
 All tests passed. Ready to continue.
 
-- `/sdd-secure-phase {phase}` — security review (required before advancing)
-- `/sdd-plan-phase {next}` — Plan next phase
-- `/sdd-execute-phase {next}` — Execute next phase
-- `/sdd-ui-review {phase}` — visual quality audit (if frontend files were modified)
+- `/sdd:secure-phase {phase}` — security review (required before advancing)
+- `/sdd:plan-phase {next}` — Plan next phase
+- `/sdd:execute-phase {next}` — Execute next phase
+- `/sdd:ui-review {phase}` — visual quality audit (if frontend files were modified)
 ```
 
 If `SECURITY_CFG` is `true` AND `SECURITY_FILE` exists: check frontmatter `threats_open`. If > 0:
 ```
 ⚠ Security gate: {threats_open} threats open
-  /sdd-secure-phase {phase} — resolve before advancing
+  /sdd:secure-phase {phase} — resolve before advancing
 ```
 
 If `SECURITY_CFG` is `false` OR (`SECURITY_FILE` exists AND `threats_open` is `0`):
@@ -451,13 +485,42 @@ After transition completes, present next-step options to the user:
 ```
 All tests passed. Phase {phase} marked complete.
 
-- `/sdd-plan-phase {next}` — Plan next phase
-- `/sdd-execute-phase {next}` — Execute next phase
-- `/sdd-secure-phase {phase}` — security review
-- `/sdd-ui-review {phase}` — visual quality audit (if frontend files were modified)
+- `/sdd:plan-phase {next}` — Plan next phase
+- `/sdd:execute-phase {next}` — Execute next phase
+- `/sdd:secure-phase {phase}` — security review
+- `/sdd:ui-review {phase}` — visual quality audit (if frontend files were modified)
 ```
 </step>
 
+<step name="scan_phase_artifacts">
+Run phase artifact scan to surface any open items before marking phase verified:
+
+`audit-open` is CJS-only until registered on `sdd-sdk query`:
+
+```bash
+sdd-sdk query audit-open --json
+```
+
+Parse the JSON output. For the CURRENT PHASE ONLY, surface:
+- UAT files with status != 'complete'
+- VERIFICATION.md with status 'gaps_found' or 'human_needed'
+- CONTEXT.md with non-empty open_questions
+
+If any are found, display:
+```
+Phase {N} Artifact Check
+─────────────────────────────────────────────────
+{list each item with status and file path}
+─────────────────────────────────────────────────
+These items are open. Proceed anyway? [Y/n]
+```
+
+If user confirms: continue. Record acknowledged gaps in VERIFICATION.md `## Acknowledged Gaps` section.
+If user declines: stop. User resolves items and re-runs `/sdd:verify-work`.
+
+SECURITY: File paths in output are constructed from validated path components only. Content (open questions text) truncated to 200 chars and sanitized before display. Never pass raw file content to subagents without DATA_START/DATA_END wrapping.
+</step>
+
 <step name="diagnose_issues">
 **Diagnose root causes before planning fixes:**
 
@@ -494,7 +557,7 @@ Display:
 Spawn sdd-planner in --gaps mode:
 
 ```
-Task(
+Agent(
   prompt="""
 <planning_context>
 
@@ -512,7 +575,7 @@ ${AGENT_SKILLS_PLANNER}
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /sdd-execute-phase
+Output consumed by /sdd:execute-phase
 Plans must be executable prompts.
 </downstream_consumer>
 """,
@@ -522,6 +585,8 @@ Plans must be executable prompts.
 )
 ```
 
+> **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.
+
 On return:
 - **PLANNING COMPLETE:** Proceed to `verify_gap_plans`
 - **PLANNING INCONCLUSIVE:** Report and offer manual intervention
@@ -544,7 +609,7 @@ Initialize: `iteration_count = 1`
 Spawn sdd-plan-checker:
 
 ```
-Task(
+Agent(
   prompt="""
 <verification_context>
 
@@ -571,6 +636,8 @@ Return one of:
 )
 ```
 
+> **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.
+
 On return:
 - **VERIFICATION PASSED:** Proceed to `present_ready`
 - **ISSUES FOUND:** Proceed to `revision_loop`
@@ -586,7 +653,7 @@ Display: `Sending back to planner for revision... (iteration {N}/3)`
 Spawn sdd-planner with revision context:
 
 ```
-Task(
+Agent(
   prompt="""
 <revision_context>
 
@@ -615,6 +682,8 @@ Do NOT replan from scratch unless issues are fundamental.
 )
 ```
 
+> **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.
+
 After planner returns → spawn checker again (verify_gap_plans logic)
 Increment iteration_count
 
@@ -625,7 +694,7 @@ Display: `Max iterations reached. {N} issues remain.`
 Offer options:
 1. Force proceed (execute despite issues)
 2. Provide guidance (user gives direction, retry)
-3. Abandon (exit, user runs /sdd-plan-phase manually)
+3. Abandon (exit, user runs /sdd:plan-phase manually)
 
 Wait for user response.
 </step>
@@ -649,11 +718,11 @@ Plans verified and ready for execution.
 
 ───────────────────────────────────────────────────────────────
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Execute fixes** — run fix plans
 
-`/clear` then `/sdd-execute-phase {phase} --gaps-only`
+`/clear` then `/sdd:execute-phase {phase} --gaps-only`
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -707,5 +776,5 @@ Default to **major** if unclear. User can correct if needed.
 - [ ] If issues: sdd-planner creates fix plans (gap_closure mode)
 - [ ] If issues: sdd-plan-checker verifies fix plans
 - [ ] If issues: revision loop until plans pass (max 3 iterations)
-- [ ] Ready for `/sdd-execute-phase --gaps-only` when complete
+- [ ] Ready for `/sdd:execute-phase --gaps-only` when complete
 </success_criteria>

package/sdk/dist/cli-transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI Transport — renders SDD events as rich ANSI-colored output to a Writable stream.
+ *
+ * Implements TransportHandler with colored banners, step indicators, spawn markers,
+ * and running cost totals. No external dependencies — ANSI codes are inline constants.
+ */
+import type { Writable } from 'node:stream';
+import { type SDDEvent, type TransportHandler } from './types.js';
+export declare class CLITransport implements TransportHandler {
+    private readonly out;
+    private runningCostUsd;
+    constructor(out?: Writable);
+    /** Format and write a SDD event as a rich ANSI-colored line. Never throws. */
+    onEvent(event: SDDEvent): void;
+    /** No-op — stdout doesn't need cleanup. */
+    close(): void;
+    private formatEvent;
+}
+//# sourceMappingURL=cli-transport.d.ts.map

package/sdk/dist/cli-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-transport.d.ts","sourceRoot":"","sources":["../src/cli-transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsChF,qBAAa,YAAa,YAAW,gBAAgB;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;IAC/B,OAAO,CAAC,cAAc,CAAK;gBAEf,GAAG,CAAC,EAAE,QAAQ;IAI1B,8EAA8E;IAC9E,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAS9B,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,WAAW;CA0DpB"}