@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/workflows/do.md

@@ -26,7 +26,7 @@ Wait for response before continuing.
 **Check if project exists.**
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state load 2>/dev/null)
+INIT=$(sdd-sdk query state.load 2>/dev/null)
 ```
 
 Track whether `.planning/` exists — some routes require it, others don't.
@@ -39,31 +39,35 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
 
 | If the text describes... | Route to | Why |
 |--------------------------|----------|-----|
-| Starting a new project, "set up", "initialize" | `/sdd-new-project` | Needs full project initialization |
-| Mapping or analyzing an existing codebase | `/sdd-map-codebase` | Codebase discovery |
-| A bug, error, crash, failure, or something broken | `/sdd-debug` | Needs systematic investigation |
-| Exploring, researching, comparing, or "how does X work" | `/sdd-research-phase` | Domain research before planning |
-| Discussing vision, "how should X look", brainstorming | `/sdd-discuss-phase` | Needs context gathering |
-| A complex task: refactoring, migration, multi-file architecture, system redesign | `/sdd-add-phase` | Needs a full phase with plan/build cycle |
-| Planning a specific phase or "plan phase N" | `/sdd-plan-phase` | Direct planning request |
-| Executing a phase or "build phase N", "run phase N" | `/sdd-execute-phase` | Direct execution request |
-| Running all remaining phases automatically | `/sdd-autonomous` | Full autonomous execution |
-| A review or quality concern about existing work | `/sdd-verify-work` | Needs verification |
-| Checking progress, status, "where am I" | `/sdd-progress` | Status check |
-| Resuming work, "pick up where I left off" | `/sdd-resume-work` | Session restoration |
-| A note, idea, or "remember to..." | `/sdd-add-todo` | Capture for later |
-| Adding tests, "write tests", "test coverage" | `/sdd-add-tests` | Test generation |
-| Completing a milestone, shipping, releasing | `/sdd-complete-milestone` | Milestone lifecycle |
-| A specific, actionable, small task (add feature, fix typo, update config) | `/sdd-quick` | Self-contained, single executor |
-
-**Requires `.planning/` directory:** All routes except `/sdd-new-project`, `/sdd-map-codebase`, `/sdd-help`, and `/sdd-join-discord`. If the project doesn't exist and the route requires it, suggest `/sdd-new-project` first.
+| Starting a new project, "set up", "initialize" | `/sdd:new-project` | Needs full project initialization |
+| Mapping or analyzing an existing codebase | `/sdd:map-codebase` | Codebase discovery |
+| A bug, error, crash, failure, or something broken | `/sdd:debug` | Needs systematic investigation |
+| Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/sdd:spike` | Throwaway experiment to validate feasibility |
+| Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/sdd:sketch` | Throwaway HTML mockups to explore design |
+| Wrapping up spikes, "package the spikes", "consolidate spike findings" | `/sdd:spike --wrap-up` | Package spike findings into reusable skill |
+| Wrapping up sketches, "package the designs", "consolidate sketch findings" | `/sdd:sketch --wrap-up` | Package sketch findings into reusable skill |
+| Exploring, researching, comparing, or "how does X work" | `/sdd:explore` | Socratic ideation and idea routing |
+| Discussing vision, "how should X look", brainstorming | `/sdd:discuss-phase` | Needs context gathering |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/sdd:phase` | Needs a full phase with plan/build cycle |
+| Planning a specific phase or "plan phase N" | `/sdd:plan-phase` | Direct planning request |
+| Executing a phase or "build phase N", "run phase N" | `/sdd:execute-phase` | Direct execution request |
+| Running all remaining phases automatically | `/sdd:autonomous` | Full autonomous execution |
+| A review or quality concern about existing work | `/sdd:verify-work` | Needs verification |
+| Checking progress, status, "where am I" | `/sdd:progress` | Status check |
+| Resuming work, "pick up where I left off" | `/sdd:resume-work` | Session restoration |
+| A note, idea, or "remember to..." | `/sdd:capture` | Capture for later |
+| Adding tests, "write tests", "test coverage" | `/sdd:add-tests` | Test generation |
+| Completing a milestone, shipping, releasing | `/sdd:complete-milestone` | Milestone lifecycle |
+| A specific, actionable, small task (add feature, fix typo, update config) | `/sdd:quick` | Self-contained, single executor |
+
+**Requires `.planning/` directory:** All routes except `/sdd:new-project`, `/sdd:map-codebase`, `/sdd:spike`, `/sdd:sketch`, and `/sdd:help`. If the project doesn't exist and the route requires it, suggest `/sdd:new-project` first.
 
 **Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
 
 ```
 "Refactor the authentication system" could be:
-1. /sdd-add-phase — Full planning cycle (recommended for multi-file refactors)
-2. /sdd-quick — Quick execution (if scope is small and clear)
+1. /sdd:phase — Full planning cycle (recommended for multi-file refactors)
+2. /sdd:quick — Quick execution (if scope is small and clear)
 
 Which approach fits better?
 ```

package/sdd/workflows/docs-update.md

@@ -14,9 +14,9 @@ Valid SDD subagent types (use exact names — do not fall back to 'general-purpo
 Load docs-update context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" docs-init)
+INIT=$(sdd-sdk query docs-init)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" agent-skills sdd-doc-writer 2>/dev/null)
+AGENT_SKILLS=$(sdd-sdk query agent-skills sdd-doc-writer)
 ```
 
 Extract from init JSON:
@@ -382,7 +382,7 @@ Use `run_in_background=true` for all three to enable parallel execution.
 **Agent 1: README**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -404,7 +404,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Agent 2: ARCHITECTURE**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -426,7 +426,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Agent 3: CONFIGURATION**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -448,6 +448,8 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 
 **CRITICAL:** Agent prompts must contain ONLY the `<doc_assignment>` block, the `${AGENT_SKILLS}` variable, and the return instruction. Do not include project planning context, workflow prose, or any internal tooling references in agent prompts.
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all Wave 1 Agent() calls above with `run_in_background=true`, do NOT generate any documentation independently while the subagents are active. Wait for all Wave 1 agents to complete before proceeding. This prevents duplicate work and wasted context.
+
 Continue to collect_wave_1.
 </step>
 
@@ -509,7 +511,7 @@ Use `run_in_background=true` for all Wave 2 agents to enable parallel execution
 **Agent: GETTING-STARTED**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -535,7 +537,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Agent: DEVELOPMENT**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -561,7 +563,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Agent: TESTING**
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -587,7 +589,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Conditional Agent: API** (only if `has_api_routes` was true — spawn only if API.md was queued)
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -613,7 +615,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Conditional Agent: DEPLOYMENT** (only if `has_deploy_config` was true — spawn only if DEPLOYMENT.md was queued)
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -640,7 +642,7 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 **Conditional Agent: CONTRIBUTING** (only if `is_open_source` was true — spawn only if CONTRIBUTING.md was queued)
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -665,6 +667,8 @@ Write the doc file directly. Return confirmation only — do not return doc cont
 
 **CRITICAL:** Agent prompts must contain ONLY the `<doc_assignment>` block, the `${AGENT_SKILLS}` variable, and the return instruction. Do not include project planning context, workflow prose, or any internal tooling references in agent prompts.
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all Wave 2 Agent() calls above with `run_in_background=true`, do NOT generate any documentation independently while the subagents are active. Wait for all Wave 2 agents to complete before proceeding. This prevents duplicate work and wasted context.
+
 Continue to collect_wave_2.
 </step>
 
@@ -727,7 +731,7 @@ Determine mode:
 Spawn a `sdd-doc-writer` agent with `run_in_background=true`:
 
 ```
-Task(
+Agent(
   subagent_type="sdd-doc-writer",
   model="{doc_writer_model}",
   run_in_background=true,
@@ -747,6 +751,8 @@ Write {package_dir}/README.md directly. Return confirmation only — do not retu
 )
 ```
 
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all per-package Agent() calls above with `run_in_background=true`, do NOT generate any package READMEs independently while the subagents are active. Wait for all agents to complete via TaskOutput before proceeding. This prevents duplicate work and wasted context.
+
 Collect confirmations via TaskOutput for all package agents. Note failures in the final report.
 
 **Fallback when Task tool is unavailable:** Generate per-package READMEs sequentially inline after the `sequential_generation` step. For each package directory with a `package.json`, construct the equivalent `doc_assignment` block and generate the README following sdd-doc-writer instructions.
@@ -988,8 +994,8 @@ Failed claims:
 
 Display note:
 ```
-To fix failures automatically: /sdd-docs-update (runs generation + fix loop)
-To regenerate all docs from scratch: /sdd-docs-update --force
+To fix failures automatically: /sdd:docs-update (runs generation + fix loop)
+To regenerate all docs from scratch: /sdd:docs-update --force
 ```
 
 Clean up temp files: remove `.planning/tmp/verify-*.json` files.
@@ -1024,7 +1030,7 @@ This would expose credentials if committed.
 Action required:
 1. Review the flagged lines above
 2. Remove any real secrets from the doc files
-3. Re-run /sdd-docs-update to regenerate clean docs
+3. Re-run /sdd:docs-update to regenerate clean docs
 ```
 
 Then confirm with AskUserQuestion:
@@ -1054,7 +1060,7 @@ Only run this step if `commit_docs` is `true` from the init JSON. If `commit_doc
 Assemble the list of files that were actually generated (do not include files that failed or were skipped):
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: generate project documentation" \
+sdd-sdk query commit "docs: generate project documentation" \
   --files README.md docs/ARCHITECTURE.md docs/CONFIGURATION.md docs/GETTING-STARTED.md docs/DEVELOPMENT.md docs/TESTING.md
 # Append any conditional docs that were generated:
 # --files ... docs/API.md docs/DEPLOYMENT.md CONTRIBUTING.md
@@ -1126,7 +1132,7 @@ All generated files committed.
 Remind the user they can fact-check generated docs:
 
 ```
-Run `/sdd-docs-update --verify-only` to fact-check generated docs against the codebase.
+Run `/sdd:docs-update --verify-only` to fact-check generated docs against the codebase.
 ```
 
 End workflow.

package/sdd/workflows/edit-phase.md

@@ -0,0 +1,294 @@
+<purpose>
+Edit any field of an existing phase in ROADMAP.md in place. The phase number and position are always preserved. Guarded against in-progress and completed phases unless --force is passed. Validates depends_on references before writing. Shows a diff and requests confirmation before writing.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: phase number to edit (integer or decimal)
+- Optional flag: --force (allow editing in_progress/completed phases)
+
+Examples:
+  `/sdd-edit-phase 5`       → phase = 5, force = false
+  `/sdd-edit-phase 5 --force` → phase = 5, force = true
+  `/sdd-edit-phase 12.1`    → phase = 12.1, force = false
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /sdd-edit-phase <phase-number> [--force]
+Example: /sdd-edit-phase 5
+Example: /sdd-edit-phase 5 --force
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(sdd-sdk query init.phase-op "${target}")
+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.
+```
+Exit.
+</step>
+
+<step name="load_phase">
+Read the current phase section from ROADMAP.md:
+
+```bash
+PHASE_DATA=$(sdd-sdk query roadmap get-phase "${target}")
+```
+
+Parse the JSON result. If `found` is false:
+
+```
+ERROR: Phase {target} not found in ROADMAP.md
+
+Available phases can be seen with /sdd:progress.
+```
+
+Exit.
+
+Extract from the result:
+- `phase_name` — the phase title
+- `goal` — the phase goal/description
+- `success_criteria` — array of criteria
+- `section` — full raw section text (preserves depends_on, requirements, plans, etc.)
+
+Also parse the full section text to extract additional fields not in the SDK result:
+- `depends_on` — from `**Depends on:** ...` or `**Depends on**: ...` line
+- `requirements` — from `**Requirements:** ...` block if present
+</step>
+
+<step name="check_phase_status">
+Determine the phase status from disk. Compare against STATE.md current phase:
+
+```bash
+ANALYZE=$(sdd-sdk query roadmap analyze)
+```
+
+Find the phase entry in the `phases` array. Extract `disk_status`.
+
+Map disk_status to a user-friendly status:
+- `complete` → status = `completed`
+- `planned` or `partial` → status = `in_progress`
+- `empty`, `no_directory`, `discussed`, `researched` → status = `future`
+
+If status is `in_progress` or `completed` AND `--force` was NOT passed:
+
+```
+ERROR: Cannot edit Phase {target} — status is {status}
+
+Editing an in-progress or completed phase may invalidate executed plans.
+
+To edit anyway, run:
+  /sdd-edit-phase {target} --force
+```
+
+Exit.
+
+If `--force` was passed and status is `in_progress` or `completed`, continue with a warning printed to the user:
+
+```
+WARNING: Editing Phase {target} which is {status}. Proceeding due to --force.
+```
+</step>
+
+<step name="present_current_values">
+Display the current phase fields clearly:
+
+```
+Current values for Phase {target}: {phase_name}
+
+Title:            {phase_name}
+Goal:             {goal}
+Depends on:       {depends_on or "(none)"}
+Requirements:     {requirements or "(none)"}
+Success Criteria:
+  1. {criterion_1}
+  2. {criterion_2}
+  ...
+```
+
+Then ask the user what they want to change:
+
+```
+What would you like to do?
+
+  [1] Edit specific fields (title, goal, depends_on, requirements, success_criteria)
+  [2] Regenerate all fields from a clarified intent
+  [3] Cancel
+
+Enter choice (1, 2, or 3):
+```
+
+Wait for user input.
+</step>
+
+<step name="collect_edits">
+
+**If user chose [3] Cancel:** Exit cleanly.
+
+**If user chose [1] Edit specific fields:**
+
+Ask which fields to edit. For each field the user wants to change, prompt for the new value. Only fields the user explicitly answers become updates; empty answers preserve the existing value.
+
+```
+Which fields do you want to update? (comma-separated or "all")
+Options: title, goal, depends_on, requirements, success_criteria
+```
+
+For each selected field, ask:
+
+```
+New value for {field} [current: {current_value}]:
+```
+
+Build an `updates` map of {field → new_value} for non-empty answers.
+
+**If user chose [2] Regenerate all from clarified intent:**
+
+Ask the user:
+
+```
+Describe the revised intent for Phase {target} (replace the current description):
+```
+
+Wait for user input. Use the clarified intent to rewrite all fields:
+- Generate a clear, concise `title` from the intent
+- Write a complete `goal` statement
+- Produce updated `requirements` if the original had them
+- Generate `success_criteria` (3-5 measurable criteria)
+- Preserve `depends_on` unless the user explicitly mentioned changing it
+</step>
+
+<step name="validate_depends_on">
+If `depends_on` is being updated (or preserved as non-empty), validate that every referenced phase number exists in ROADMAP.md:
+
+```bash
+ALL_PHASES=$(sdd-sdk query roadmap analyze)
+```
+
+Parse the `phases` array to get all valid phase numbers.
+
+For each phase number referenced in `depends_on`:
+- Normalize it (strip whitespace, "Phase" prefix if present)
+- Check it is in the valid phase numbers set
+- It must not reference itself (phase {target})
+
+If any reference is invalid:
+
+```
+ERROR: depends_on references invalid phase(s): {bad_refs}
+
+Valid phase numbers: {valid_list}
+
+Fix the depends_on field and try again.
+```
+
+Exit (do not write).
+</step>
+
+<step name="show_diff_and_confirm">
+Build the updated phase section by applying the changes to the original `section` text:
+
+- For `title`: replace the heading text after `Phase {N}:`
+- For `goal`: replace the `**Goal:**` line value
+- For `depends_on`: replace or add the `**Depends on:**` line
+- For `requirements`: replace or add the requirements block
+- For `success_criteria`: replace the numbered list under `**Success Criteria**:`
+- For full regeneration: rebuild the entire section from the new field values
+
+Show a unified-style diff of old vs. new:
+
+```
+Proposed changes to Phase {target}:
+
+--- current
++++ updated
+@@ ...
+- **Goal:** {old_goal}
++ **Goal:** {new_goal}
+...
+
+Apply these changes? (y/n):
+```
+
+Wait for confirmation. If the user says `n`, exit without writing.
+</step>
+
+<step name="write_updated_phase">
+Write the updated phase back in place in ROADMAP.md.
+
+Read the full ROADMAP.md content, locate the phase section by its header (`## Phase {N}:` or `### Phase {N}:`), and replace exactly the old section text with the new section text. All content before and after the section (including other phases, milestone headers, and the summary checklist) must be left unchanged.
+
+After writing ROADMAP.md, update STATE.md Roadmap Evolution:
+
+```bash
+sdd-sdk query state.add-roadmap-evolution \
+  --phase {target} \
+  --action edited \
+  --note "edited fields: {changed_field_list}"
+```
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} updated in ROADMAP.md.
+
+Fields changed: {changed_field_list}
+
+---
+
+## What's Next
+
+- `/sdd:progress` — view updated roadmap
+- `/sdd:plan-phase {target}` — re-plan this phase (if needed)
+- `/sdd:discuss-phase {target}` — discuss implementation approach
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+- Don't renumber the phase — number and position must be preserved exactly
+- Don't modify other phases when editing one
+- Don't skip depends_on validation (invalid references block writes)
+- Don't write without showing a diff and getting confirmation
+- Don't edit in_progress/completed phases without --force
+- Don't use raw Write on ROADMAP.md without reading it first; always replace section in place
+- Don't modify the phase directory structure — only ROADMAP.md changes
+- Don't commit the change — that's the user's decision
+</anti_patterns>
+
+<success_criteria>
+Edit-phase is complete when:
+
+- [ ] Phase {target} found and loaded from ROADMAP.md
+- [ ] Status check performed; in_progress/completed blocked without --force
+- [ ] Current values presented to user
+- [ ] User chose edit mode (specific fields or full regeneration)
+- [ ] depends_on references validated; invalid references blocked
+- [ ] Diff shown and confirmed by user
+- [ ] Updated phase written back in place; number, position, and status preserved
+- [ ] STATE.md Roadmap Evolution updated
+- [ ] User informed of next steps
+</success_criteria>

package/sdd/workflows/eval-review.md

@@ -1,7 +1,7 @@
 <purpose>
 Retroactive audit of an implemented AI phase's evaluation coverage. Standalone command that works on any SDD-managed AI phase. Produces a scored EVAL-REVIEW.md with gap analysis and remediation plan.
 
-Use after /sdd-execute-phase to verify that the evaluation strategy from AI-SPEC.md was actually implemented. Mirrors the pattern of /sdd-ui-review and /sdd-validate-phase.
+Use after /sdd:execute-phase to verify that the evaluation strategy from AI-SPEC.md was actually implemented. Mirrors the pattern of /sdd:ui-review and /sdd:validate-phase.
 </purpose>
 
 <required_reading>
@@ -13,14 +13,14 @@ Use after /sdd-execute-phase to verify that the evaluation strategy from AI-SPEC
 ## 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
 ```
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
 
 ```bash
-AUDITOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-eval-auditor --raw)
+AUDITOR_MODEL=$(sdd-sdk query resolve-model sdd-eval-auditor 2>/dev/null | jq -r '.model' 2>/dev/null || true)
 ```
 
 Display banner:
@@ -40,7 +40,7 @@ EVAL_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-EVAL-REVIEW.md 2>/dev/null | head -1)
 
 **State A** — AI-SPEC.md + SUMMARY.md exist: Full audit against spec
 **State B** — SUMMARY.md exists, no AI-SPEC.md: Audit against general best practices
-**State C** — No SUMMARY.md: Exit — "Phase {N} not executed. Run /sdd-execute-phase {N} first."
+**State C** — No SUMMARY.md: Exit — "Phase {N} not executed. Run /sdd:execute-phase {N} first."
 
 
 **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.
@@ -58,7 +58,7 @@ If "Re-audit": continue.
 ```
 No AI-SPEC.md found for Phase {N}.
 Audit will evaluate against general AI eval best practices rather than a phase-specific plan.
-Consider running /sdd-ai-integration-phase {N} before implementation next time.
+Consider running /sdd:ai-integration-phase {N} before implementation next time.
 ```
 Continue (non-blocking).
 
@@ -124,10 +124,10 @@ Read the written EVAL-REVIEW.md. Extract:
 ◆ Output: {eval_review_path}
 
 {If PRODUCTION READY:}
-  Next step: /sdd-plan-phase (next phase) or deploy
+  Next step: /sdd:plan-phase (next phase) or deploy
 
 {If NEEDS WORK:}
-  Address critical gaps in EVAL-REVIEW.md, then re-run /sdd-eval-review {N}
+  Address critical gaps in EVAL-REVIEW.md, then re-run /sdd:eval-review {N}
 
 {If SIGNIFICANT GAPS or NOT IMPLEMENTED:}
   Review AI-SPEC.md evaluation plan. Critical eval dimensions are not implemented.

package/sdd/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -0,0 +1,81 @@
+# Step: codebase_drift_gate
+
+Post-execution structural drift detection (#2003). Runs after the last wave
+commits, before verification. **Non-blocking by contract:** any internal
+error here MUST fall through and continue to `verify_phase_goal`. The phase
+is never failed by this gate.
+
+```bash
+DRIFT=$(sdd-sdk query verify.codebase-drift 2>/dev/null || echo '{"skipped":true,"reason":"sdk-failed"}')
+```
+
+Parse JSON for: `skipped`, `reason`, `action_required`, `directive`,
+`spawn_mapper`, `affected_paths`, `elements`, `threshold`, `action`,
+`last_mapped_commit`, `message`.
+
+**If `skipped` is true (no STRUCTURE.md, missing git, or any internal error):**
+Log one line — `Codebase drift check skipped: {reason}` — and continue to
+`verify_phase_goal`. Do NOT prompt the user. Do NOT block.
+
+**If `action_required` is false:** Continue silently to `verify_phase_goal`.
+
+**If `action_required` is true AND `directive` is `warn`:**
+Print the `message` field verbatim. The format is:
+
+```text
+Codebase drift detected: {N} structural element(s) since last mapping.
+
+New directories:
+  - {path}
+New barrel exports:
+  - {path}
+New migrations:
+  - {path}
+New route modules:
+  - {path}
+
+Run /sdd:map-codebase --paths {affected_paths} to refresh planning context.
+```
+
+Then continue to `verify_phase_goal`. Do NOT block. Do NOT spawn anything.
+
+**If `action_required` is true AND `directive` is `auto-remap`:**
+
+First load the mapper agent's skill bundle (the executor's `AGENT_SKILLS`
+from step `init_context` is for `sdd-executor`, not the mapper):
+
+```bash
+AGENT_SKILLS_MAPPER=$(sdd-sdk query agent-skills sdd-codebase-mapper)
+```
+
+Then spawn `sdd-codebase-mapper` agents with the `--paths` hint:
+
+```text
+Agent(
+  subagent_type="sdd-codebase-mapper",
+  description="Incremental codebase remap (drift)",
+  prompt="Focus: arch
+Today's date: {date}
+--paths {affected_paths joined by comma}
+
+Refresh STRUCTURE.md and ARCHITECTURE.md scoped to the listed paths only.
+Stamp last_mapped_commit in each document's frontmatter.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+> **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.
+
+If the spawn fails or the agent reports an error: log `Codebase drift
+auto-remap failed: {reason}` and continue to `verify_phase_goal`. The phase
+is NOT failed by a remap failure.
+
+If the remap succeeds: log `Codebase drift auto-remap completed for paths:
+{affected_paths}` and continue to `verify_phase_goal`.
+
+The two relevant config keys (continue on error / failure if either is invalid):
+- `workflow.drift_threshold` (integer, default 3) — minimum drift elements before action
+- `workflow.drift_action` — `warn` (default) or `auto-remap`
+
+This step is fully non-blocking — it never fails the phase, and any
+exception path returns control to `verify_phase_goal`.