@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/workflows/import.md

@@ -32,7 +32,7 @@ Parse `$ARGUMENTS` to determine the execution mode:
 - If neither flag is found: display usage and exit:
 
 ```
-Usage: /sdd-import --from <path>
+Usage: /sdd:import --from <path>
 
   --from <path>   Import an external plan file into SDD format
 ```
@@ -107,7 +107,7 @@ Extract from the imported content:
 
 <step name="plan_conflict_detection">
 
-Run conflict checks against the loaded project context. Output as a plain-text conflict report using [BLOCKER], [WARNING], and [INFO] labels. Do NOT use markdown tables (no `|---|` format).
+Run conflict checks against the loaded project context. The report format, severity semantics, and safety-gate behavior are defined by `references/doc-conflict-engine.md` — read it and apply it here. Operation noun: `import`.
 
 ### BLOCKER checks (any one prevents import):
 
@@ -128,45 +128,15 @@ Run conflict checks against the loaded project context. Output as a plain-text c
 - Plan uses a library not currently in the project tech stack → [INFO]
 - Plan adds a new phase to the ROADMAP.md structure → [INFO]
 
-Display the full Conflict Detection Report:
+Render the full Conflict Detection Report using the format in `references/doc-conflict-engine.md`.
 
-```
-## Conflict Detection Report
-
-### BLOCKERS ({N})
-
-[BLOCKER] {Short title}
-  Found: {what the imported plan says}
-  Expected: {what project context requires}
-  → {Specific action to resolve}
-
-### WARNINGS ({N})
-
-[WARNING] {Short title}
-  Found: {what was detected}
-  Impact: {what could go wrong}
-  → {Suggested action}
-
-### INFO ({N})
-
-[INFO] {Short title}
-  Note: {relevant information}
-```
-
-**If any [BLOCKER] exists:**
-
-Display:
-```
-SDD > BLOCKED: {N} blockers must be resolved before import can proceed.
-```
-
-Exit WITHOUT writing any files. This is the safety gate — no PLAN.md is written when blockers exist.
+**If any [BLOCKER] exists:** apply the safety gate from the reference — exit WITHOUT writing any files. No PLAN.md is written when blockers exist.
 
 **If only WARNINGS and/or INFO (no blockers):**
 
-
 **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
-Ask via AskUserQuestion using the approve-revise-abort pattern:
+
+Ask via AskUserQuestion using the approve-revise-abort pattern (see `references/gate-prompts.md`):
 - question: "Review the warnings above. Proceed with import?"
 - header: "Approve?"
 - options: Approve | Abort
@@ -203,16 +173,21 @@ Apply SDD naming convention for the output filename:
 - NEVER use `PLAN-01.md`, `plan-01.md`, or any other format
 - NN = phase number (zero-padded), MM = plan number within the phase (zero-padded)
 
-Determine the target directory:
-```
-.planning/phases/{NN}-{slug}/
+Determine the target directory by querying `init.phase-op` for the phase number extracted in `plan_read_input`. This ensures the `project_code` prefix from `.planning/config.json` is applied:
+
+```bash
+INIT=$(sdd-sdk query init.phase-op "{NN}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+expected_phase_dir=$(echo "$INIT" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).expected_phase_dir)")
 ```
 
 If the directory does not exist, create it:
 ```bash
-mkdir -p ".planning/phases/{NN}-{slug}/"
+mkdir -p "${expected_phase_dir}"
 ```
 
+Set `phase_dir="${expected_phase_dir}"` for use in subsequent steps.
+
 Write the PLAN.md file to the target directory.
 
 </step>
@@ -222,12 +197,14 @@ Write the PLAN.md file to the target directory.
 Delegate validation to sdd-plan-checker:
 
 ```
-Task({
+Agent({
   subagent_type: "sdd-plan-checker",
   prompt: "Validate: .planning/phases/{phase}/{plan}-PLAN.md — check frontmatter completeness, task structure, and SDD conventions. Report any issues."
 })
 ```
 
+> **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 checker returns errors:
 - Display the errors to the user
 - Ask the user to resolve issues before the plan is considered imported
@@ -248,7 +225,7 @@ Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
 
 Commit the imported plan and updated files:
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
+sdd-sdk query commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
 ```
 
 Display completion:
@@ -267,7 +244,7 @@ Show: plan filename written, phase directory, validation result, next steps.
 ## Anti-Patterns
 
 Do NOT:
-- Use markdown tables (`|---|`) in the conflict detection report — use plain-text [BLOCKER]/[WARNING]/[INFO] labels
+- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
 - Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
 - Use `pbr:plan-checker` or `pbr:planner` — use `sdd-plan-checker` and `sdd-planner`
 - Write `.planning/.active-skill` — this is a PBR pattern with no SDD equivalent

package/sdd/workflows/inbox.md

@@ -212,7 +212,7 @@ For each classified PR, review against its template requirements.
 - [ ] PR title is descriptive (not just "fix" or "update")
 - [ ] One concern per PR (not mixing fix + enhancement)
 - [ ] No unrelated formatting changes visible in diff
-- [ ] CHANGELOG.md updated
+- [ ] `.changeset/*.md` fragment added for user-facing changes (or `no-changelog` label applied)
 - [ ] Not using `--no-verify` or skipping hooks
 
 **Scoring:** Same as issues — completeness percentage per PR.
@@ -370,10 +370,10 @@ Next steps:
 <offer_next>
 After triage:
 
-- /sdd-review — Run cross-AI peer review on a specific phase plan
-- /sdd-ship — Create a PR from completed work
-- /sdd-progress — See overall project state
-- /sdd-inbox --label — Re-run with auto-labeling enabled
+- /sdd:review — Run cross-AI peer review on a specific phase plan
+- /sdd:ship — Create a PR from completed work
+- /sdd:progress — See overall project state
+- /sdd:inbox --label — Re-run with auto-labeling enabled
 </offer_next>
 
 <success_criteria>

package/sdd/workflows/ingest-docs.md

@@ -0,0 +1,339 @@
+# Ingest Docs Workflow
+
+Scan a repo for mixed planning documents (ADR, PRD, SPEC, DOC), synthesize them into a consolidated context, and bootstrap or merge into `.planning/`.
+
+- `[path]` — optional target directory to scan (defaults to repo root)
+- `--mode new|merge` — override auto-detect (defaults: `new` if `.planning/` absent, `merge` if present)
+- `--manifest <file>` — YAML file listing `{path, type, precedence?}` per doc; overrides heuristic classification
+- `--resolve auto|interactive` — conflict resolution (v1: only `auto` is supported; `interactive` is reserved)
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► INGEST DOCS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS`:
+
+- First positional token (if not a flag) → `SCAN_PATH` (default: `.`)
+- `--mode new|merge` → `MODE` (default: auto-detect)
+- `--manifest <file>` → `MANIFEST_PATH` (optional)
+- `--resolve auto|interactive` → `RESOLVE_MODE` (default: `auto`; reject `interactive` in v1 with message "interactive resolution is planned for a future release")
+
+**Validate paths:**
+
+```bash
+case "{SCAN_PATH}" in *..*) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;; esac
+test -d "{SCAN_PATH}" || echo "PATH_NOT_FOUND"
+if [ -n "{MANIFEST_PATH}" ]; then
+  case "{MANIFEST_PATH}" in *..*) echo "SECURITY_ERROR: manifest path contains traversal"; exit 1 ;; esac
+  test -f "{MANIFEST_PATH}" || echo "MANIFEST_NOT_FOUND"
+fi
+```
+
+**Containment (required):** After resolving `SCAN_PATH` and `MANIFEST_PATH` relative to the repo root, canonicalize each with `realpath` (or platform equivalent) and assert the result is under `realpath("$REPO_ROOT")`. Reject absolute paths outside the repo (e.g. `/tmp`, `C:\Windows`) even when they do not contain `..`.
+
+If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
+
+</step>
+
+<step name="init_and_mode_detect">
+
+Run the init query:
+
+```bash
+INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init ingest-docs)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse `project_exists`, `planning_exists`, `has_git`, `git_worktree_root`, `in_nested_subdir`, `project_path` from INIT.
+
+**Auto-detect MODE** if not set:
+- `planning_exists: true` → `MODE=merge`
+- `planning_exists: false` → `MODE=new`
+
+If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `references/gate-prompts.md`) before overwriting.
+
+Git initialisation (Bug #3491 — never create a nested `.git` inside an existing worktree):
+
+- If `has_git: true` and `in_nested_subdir: true`: do NOT run `git init`. Surface a warning that planning files will be tracked by the outer repo at `git_worktree_root`.
+- If `has_git: true` and `in_nested_subdir: false`: already at a worktree root, skip `git init`.
+- If `has_git: false` and `MODE=new`: initialize git:
+
+```bash
+git init
+```
+
+**Detect runtime** using the same pattern as `new-project.md`:
+- execution_context path `/.codex/` → `RUNTIME=codex`
+- `/.gemini/` → `RUNTIME=gemini`
+- `/.opencode/` or `/.config/opencode/` → `RUNTIME=opencode`
+- else → `RUNTIME=claude`
+
+Fall back to env vars (`CODEX_HOME`, `GEMINI_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`) if execution_context is unavailable.
+
+</step>
+
+<step name="discover_docs">
+
+Build the doc list from three sources, in order:
+
+**1. Manifest (if provided)** — authoritative:
+
+Read `MANIFEST_PATH`. Expected YAML shape:
+
+```yaml
+docs:
+  - path: docs/adr/0001-db.md
+    type: ADR
+    precedence: 0   # optional, lower = higher precedence
+  - path: docs/prd/auth.md
+    type: PRD
+```
+
+Each entry provides `path` (required, relative to repo root) + `type` (required, one of ADR|PRD|SPEC|DOC) + `precedence` (optional integer).
+
+**2. Directory conventions** (skipped when manifest is provided):
+
+```bash
+# ADRs
+find {SCAN_PATH} -type f \( -path '*/adr/*' -o -path '*/adrs/*' -o -name 'ADR-*.md' -o -regex '.*/[0-9]\{4\}-.*\.md' \) 2>/dev/null
+
+# PRDs
+find {SCAN_PATH} -type f \( -path '*/prd/*' -o -path '*/prds/*' -o -name 'PRD-*.md' \) 2>/dev/null
+
+# SPECs / RFCs
+find {SCAN_PATH} -type f \( -path '*/spec/*' -o -path '*/specs/*' -o -path '*/rfc/*' -o -path '*/rfcs/*' -o -name 'SPEC-*.md' -o -name 'RFC-*.md' \) 2>/dev/null
+
+# Generic docs (fall-through candidates)
+find {SCAN_PATH} -type f -path '*/docs/*' -name '*.md' 2>/dev/null
+```
+
+De-duplicate the union (a file matched by multiple patterns is one doc).
+
+**3. Content heuristics** (run during classification, not here) — the classifier handles frontmatter `type:` and H1 inspection for docs that didn't match a convention.
+
+**Cap:** hard limit of 50 docs per invocation (documented v1 constraint). If the discovered set exceeds 50:
+
+```
+SDD > Discovered {N} docs, which exceeds the v1 cap of 50.
+      Use --manifest to narrow the set to ≤ 50 files, or run
+      /sdd:ingest-docs again with a narrower <path>.
+```
+
+Exit without proceeding.
+
+**Display discovered set** and request approval (see `references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
+
+```
+Discovered {N} documents:
+  {N} ADR | {N} PRD | {N} SPEC | {N} DOC | {N} unclassified
+
+  docs/adr/0001-architecture.md       [ADR]    (from manifest|directory|heuristic)
+  docs/adr/0002-database.md           [ADR]    (directory)
+  docs/prd/auth.md                    [PRD]    (manifest)
+  ...
+```
+
+**Text mode:** apply the same `--text`/`text_mode` rule as other workflows — replace `AskUserQuestion` with a numbered list.
+
+Use `AskUserQuestion` (approve-revise-abort):
+- question: "Proceed with classification of these {N} documents?"
+- header: "Approve?"
+- options: Approve | Revise | Abort
+
+On Abort: exit cleanly with "Ingest cancelled."
+On Revise: exit with guidance to re-run with `--manifest` or a narrower path.
+
+</step>
+
+<step name="classify_parallel">
+
+Create staging directory:
+
+```bash
+mkdir -p .planning/intel/classifications/
+```
+
+For each discovered doc, spawn `sdd-doc-classifier` in parallel. In Claude Code, issue all Task calls in a single message with multiple tool uses so the harness runs them concurrently. For Copilot / sequential runtimes, fall back to sequential dispatch.
+
+Per-spawn prompt fields:
+- `FILEPATH` — absolute path to the doc
+- `OUTPUT_DIR` — `.planning/intel/classifications/`
+- `MANIFEST_TYPE` — the type from the manifest if present, else omit
+- `MANIFEST_PRECEDENCE` — the precedence integer from the manifest if present, else omit
+- `<required_reading>` — `agents/sdd-doc-classifier.md` (the agent definition itself)
+
+Collect the one-line confirmations from each classifier. If any classifier errors out, surface the error and abort without touching `.planning/` further.
+
+</step>
+
+<step name="synthesize">
+
+Spawn `sdd-doc-synthesizer` once:
+
+```
+Agent({
+  subagent_type: "sdd-doc-synthesizer",
+  prompt: "
+    CLASSIFICATIONS_DIR: .planning/intel/classifications/
+    INTEL_DIR: .planning/intel/
+    CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md
+    MODE: {MODE}
+    EXISTING_CONTEXT: {paths to existing .planning files if MODE=merge, else empty}
+    PRECEDENCE: {array from manifest defaults or default ['ADR','SPEC','PRD','DOC']}
+
+    <required_reading>
+    - agents/sdd-doc-synthesizer.md
+    - sdd/references/doc-conflict-engine.md
+    </required_reading>
+  "
+})
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read or synthesize any classified documents independently 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.
+
+The synthesizer writes:
+- `.planning/intel/decisions.md`, `.planning/intel/requirements.md`, `.planning/intel/constraints.md`, `.planning/intel/context.md`
+- `.planning/intel/SYNTHESIS.md`
+- `.planning/INGEST-CONFLICTS.md`
+
+</step>
+
+<step name="conflict_gate">
+
+Read `.planning/INGEST-CONFLICTS.md`. Count entries in each bucket (the synthesizer always writes the three-bucket header; parse the `### BLOCKERS ({N})`, `### WARNINGS ({N})`, `### INFO ({N})` lines).
+
+Apply the safety semantics from `references/doc-conflict-engine.md`. Operation noun: `ingest`.
+
+**If BLOCKERS > 0:**
+
+Render the report to the user, then display:
+
+```
+SDD > BLOCKED: {N} blockers must be resolved before ingest can proceed.
+```
+
+Exit WITHOUT writing PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md. The staging intel files remain for inspection. The safety gate holds — no destination files are written when blockers exist.
+
+**If WARNINGS > 0 and BLOCKERS = 0:**
+
+Render the report, then ask via AskUserQuestion (approve-revise-abort):
+- question: "Review the competing variants above. Resolve manually and proceed, or abort?"
+- header: "Approve?"
+- options: Approve | Abort
+
+On Abort: exit cleanly with "Ingest cancelled. Staged intel preserved at `.planning/intel/`."
+
+**If BLOCKERS = 0 and WARNINGS = 0:**
+
+Proceed to routing silently, or optionally display `SDD > No conflicts. Auto-resolved: {N}.`
+
+</step>
+
+<step name="route_new_mode">
+
+**Applies only when MODE=new.**
+
+Audit PROJECT.md field requirements that `sdd-roadmapper` expects. For fields derivable from `.planning/intel/SYNTHESIS.md` (project scope, goals/non-goals, constraints, locked decisions), synthesize from the intel. For fields NOT derivable (project name, developer-facing success metric, target runtime), prompt via `AskUserQuestion` one at a time — minimal question set, no interrogation.
+
+Delegate to `sdd-roadmapper`:
+
+```
+Agent({
+  subagent_type: "sdd-roadmapper",
+  prompt: "
+    Mode: new-project-from-ingest
+    Intel: .planning/intel/SYNTHESIS.md (entry point)
+    Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md
+    User-supplied fields: {collected in previous step}
+
+    Produce:
+    - .planning/PROJECT.md
+    - .planning/REQUIREMENTS.md
+    - .planning/ROADMAP.md
+    - .planning/STATE.md
+
+    Treat ADR-locked decisions as locked in PROJECT.md <decisions> blocks.
+  "
+})
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more intel files, write planning artifacts, or create ROADMAP.md independently 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.
+
+</step>
+
+<step name="route_merge_mode">
+
+**Applies only when MODE=merge.**
+
+Load existing `.planning/ROADMAP.md`, `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, all `CONTEXT.md` files under `.planning/phases/`.
+
+The synthesizer has already hard-blocked on any LOCKED-in-ingest vs LOCKED-in-existing contradiction; if we reach this step, no such blockers remain.
+
+Plan the merge:
+- **New requirements** from synthesized `.planning/intel/requirements.md` that do not overlap existing REQUIREMENTS.md entries → append to REQUIREMENTS.md
+- **New decisions** from synthesized `.planning/intel/decisions.md` that do not overlap existing CONTEXT.md `<decisions>` blocks → write to a new phase's CONTEXT.md or append to the next milestone's requirements
+- **New scope** → derive phase additions following the `new-milestone.md` pattern; append phases to `.planning/ROADMAP.md`
+
+Preview the merge diff to the user and gate via approve-revise-abort before writing.
+
+</step>
+
+<step name="finalize">
+
+Commit the ingest results:
+
+```bash
+node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit \
+  "docs: ingest {N} docs from {SCAN_PATH} (#2387)" --files \
+  .planning/PROJECT.md \
+  .planning/REQUIREMENTS.md \
+  .planning/ROADMAP.md \
+  .planning/STATE.md \
+  .planning/intel/ \
+  .planning/INGEST-CONFLICTS.md
+```
+
+(For merge mode, substitute the actual set of modified files.)
+
+Display completion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► INGEST DOCS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show:
+- Mode ran (new or merge)
+- Docs ingested (count + type breakdown)
+- Decisions locked, requirements created, constraints captured
+- Conflict report path (`.planning/INGEST-CONFLICTS.md`)
+- Next step: `/sdd:plan-phase 1` (new mode) or `/sdd:plan-phase N` (merge, pointing at the first newly-added phase)
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
+- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md when BLOCKERs exist in the conflict report
+- Skip the 50-doc cap — larger sets must use `--manifest` to narrow the scope
+- Auto-resolve LOCKED-vs-LOCKED ADR contradictions — those are BLOCKERs in both modes
+- Merge competing PRD acceptance variants into a combined criterion — preserve all variants for user resolution
+- Bypass the discovery approval gate — users must see the classified doc list before classifiers spawn
+- Skip path validation on `SCAN_PATH` or `MANIFEST_PATH`
+- Implement `--resolve interactive` in this v1 — the flag is reserved; reject with a future-release message

package/sdd/workflows/insert-phase.md

@@ -34,7 +34,7 @@ Validate first argument is an integer.
 Load phase operation context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${after_phase}")
+INIT=$(sdd-sdk query init.phase-op "${after_phase}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -46,10 +46,10 @@ Exit.
 </step>
 
 <step name="insert_phase">
-**Delegate the phase insertion to sdd-tools:**
+**Delegate the phase insertion to `sdd-sdk query phase.insert`:**
 
 ```bash
-RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase insert "${after_phase}" "${description}")
+RESULT=$(sdd-sdk query phase.insert "${after_phase}" "${description}")
 ```
 
 The CLI handles:
@@ -63,15 +63,35 @@ Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
 </step>
 
 <step name="update_project_state">
-Update STATE.md to reflect the inserted phase:
+Update STATE.md to reflect the inserted phase via SDK handlers (never raw
+`Edit`/`Write` — projects may ship a `protect-files.sh` PreToolUse hook that
+blocks direct STATE.md writes):
 
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+1. Update STATE.md's next-phase pointer(s) to the newly inserted phase
+   `{decimal_phase}`:
+
+   ```bash
+   sdd-sdk query state.patch '{"Current Phase":"{decimal_phase}","Next recommended run":"/sdd:plan-phase {decimal_phase}"}'
    ```
-   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+
+   (Adjust field names to whatever pointers STATE.md exposes — the handler
+   reports which fields it matched.)
+
+2. Append a Roadmap Evolution entry via the dedicated handler. It creates the
+   `### Roadmap Evolution` subsection under `## Accumulated Context` if missing
+   and dedupes identical entries:
+
+   ```bash
+   sdd-sdk query state.add-roadmap-evolution \
+     --phase {decimal_phase} \
+     --action inserted \
+     --after {after_phase} \
+     --note "{description}" \
+     --urgent
    ```
 
-If "Roadmap Evolution" section doesn't exist, create it.
+   Expected response shape: `{ added: true, entry: "- Phase ... (URGENT)" }`
+   (or `{ added: false, reason: "duplicate", entry: ... }` on replay).
 </step>
 
 <step name="completion">
@@ -95,7 +115,7 @@ Project state updated: .planning/STATE.md
 
 `/clear` then:
 
-`/sdd-plan-phase {decimal_phase}`
+`/sdd:plan-phase {decimal_phase}`
 
 ---
 
@@ -115,16 +135,17 @@ Project state updated: .planning/STATE.md
 - Don't insert before Phase 1 (decimal 0.1 makes no sense)
 - Don't renumber existing phases
 - Don't modify the target phase content
-- Don't create plans yet (that's /sdd-plan-phase)
+- Don't create plans yet (that's /sdd:plan-phase)
 - Don't commit changes (user decides when to commit)
 </anti_patterns>
 
 <success_criteria>
 Phase insertion is complete when:
 
-- [ ] `sdd-tools phase insert` executed successfully
+- [ ] `sdd-sdk query phase.insert` executed successfully
 - [ ] Phase directory created
 - [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
-- [ ] STATE.md updated with roadmap evolution note
+- [ ] `sdd-sdk query state.add-roadmap-evolution ...` returned `{ added: true }` or `{ added: false, reason: "duplicate" }`
+- [ ] `sdd-sdk query state.patch` returned matched next-phase pointer field(s)
 - [ ] User informed of next steps and dependency implications
 </success_criteria>

package/sdd/workflows/list-phase-assumptions.md

@@ -153,8 +153,8 @@ Present next steps:
 
 ```
 What's next?
-1. Discuss context (/sdd-discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
-2. Plan this phase (/sdd-plan-phase ${PHASE}) - Create detailed execution plans
+1. Discuss context (/sdd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
+2. Plan this phase (/sdd:plan-phase ${PHASE}) - Create detailed execution plans
 3. Re-examine assumptions - I'll analyze again with your corrections
 4. Done for now
 ```

package/sdd/workflows/list-workspaces.md

@@ -11,7 +11,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 ## 1. Setup
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init list-workspaces)
+INIT=$(sdd-sdk query init.list-workspaces)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -25,7 +25,7 @@ Parse JSON for: `workspace_base`, `workspaces`, `workspace_count`.
 No workspaces found in ~/sdd-workspaces/
 
 Create one with:
-  /sdd-new-workspace --name my-workspace --repos repo1,repo2
+  /sdd:workspace --new --name my-workspace --repos repo1,repo2
 ```
 
 Done.