@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/workflows/next.md

@@ -14,7 +14,7 @@ Read project state to determine current position:
 
 ```bash
 # Get state snapshot
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" state json 2>/dev/null || echo "{}"
+sdd-sdk query state.json 2>/dev/null || echo "{}"
 ```
 
 Also read:
@@ -34,6 +34,129 @@ No SDD project detected. Run `/sdd:new-project` to get started.
 Exit.
 </step>
 
+<step name="safety_gates">
+Run hard-stop checks before routing. Exit on first hit unless `--force` was passed.
+
+If `--force` flag was passed, skip all gates and the consecutive guard.
+Print a one-line warning: `⚠ --force: skipping safety gates`
+Then proceed directly to `determine_next_action`.
+
+**Gate 1: Unresolved checkpoint**
+Check if `.planning/.continue-here.md` exists:
+```bash
+[ -f .planning/.continue-here.md ]
+```
+If found:
+```
+⛔ Hard stop: Unresolved checkpoint
+
+`.planning/.continue-here.md` exists — a previous session left
+unfinished work that needs manual review before advancing.
+
+Read the file, resolve the issue, then delete it to continue.
+Use `--force` to bypass this check.
+```
+Exit (do not route).
+
+**Gate 2: Error state**
+Check if STATE.md contains `status: error` or `status: failed`:
+If found:
+```
+⛔ Hard stop: Project in error state
+
+STATE.md shows status: {status}. Resolve the error before advancing.
+Run `/sdd:health` to diagnose, or manually fix STATE.md.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Gate 3: Unchecked verification**
+Check if the current phase has a VERIFICATION.md with any `FAIL` items that don't have overrides:
+If found:
+```
+⛔ Hard stop: Unchecked verification failures
+
+VERIFICATION.md for phase {N} has {count} unresolved FAIL items.
+Address the failures or add overrides before advancing to the next phase.
+Use `--force` to bypass this check.
+```
+Exit.
+
+**Prior-phase completeness scan:**
+After passing all three hard-stop gates, scan all phases that precede the current phase in ROADMAP.md order for incomplete work. For each prior phase number `N`, use `sdd-sdk query find-phase <N>` JSON (plans, summaries, incomplete_plans, etc.) to inspect that phase.
+
+Detect three categories of incomplete work:
+1. **Plans without summaries** — a PLAN.md exists in a prior phase directory but no matching SUMMARY.md exists (execution started but not completed).
+2. **Verification failures not overridden** — a prior phase has a VERIFICATION.md with `FAIL` items that have no override annotation.
+3. **CONTEXT.md without plans** — a prior phase directory has a CONTEXT.md but no PLAN.md files (discussion happened, planning never ran).
+
+If no incomplete prior work is found, continue to `determine_next_action` silently with no interruption.
+
+If incomplete prior work is found, show a structured completeness report:
+```
+⚠ Prior phase has incomplete work
+
+Phase {N} — "{name}" has unresolved items:
+  • Plan {N}-{M} ({slug}): executed but no SUMMARY.md
+  [... additional items ...]
+
+Advancing before resolving these may cause:
+  • Verification gaps — future phase verification won't have visibility into what prior phases shipped
+  • Context loss — plans that ran without summaries leave no record for future agents
+
+Options:
+  [C] Continue and defer these items to backlog
+  [S] Stop and resolve manually (recommended)
+  [F] Force advance without recording deferral
+
+Choice [S]:
+```
+
+**If the user chooses "Stop" (S or Enter/default):** Exit without routing.
+
+**If the user chooses "Continue and defer" (C):**
+1. For each incomplete item, create a backlog entry in `ROADMAP.md` under `## Backlog` using the existing `999.x` numbering scheme:
+```markdown
+### Phase 999.{N}: Follow-up — Phase {src} incomplete plans (BACKLOG)
+
+**Goal:** Resolve plans that ran without producing summaries during Phase {src} execution
+**Source phase:** {src}
+**Deferred at:** {date} during /sdd:progress --next advancement to Phase {dest}
+**Plans:**
+- [ ] {N}-{M}: {slug} (ran, no SUMMARY.md)
+```
+2. Commit the deferral record:
+```bash
+sdd-sdk query commit "docs: defer incomplete Phase {src} items to backlog"
+```
+3. Continue routing to `determine_next_action` immediately — no second prompt.
+
+**If the user chooses "Force" (F):** Continue to `determine_next_action` without recording deferral.
+</step>
+
+<step name="spike_sketch_notice">
+Check for pending spike/sketch work and surface a notice (does not change routing):
+
+```bash
+# Check for pending spikes (verdict: PENDING in any README)
+PENDING_SPIKES=$(grep -rl 'verdict: PENDING' .planning/spikes/*/README.md 2>/dev/null | wc -l | tr -d ' ')
+
+# Check for pending sketches (winner: null in any README)
+PENDING_SKETCHES=$(grep -rl 'winner: null' .planning/sketches/*/README.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+If either count is > 0, display before routing:
+```
+⚠ Pending exploratory work:
+  {PENDING_SPIKES} spike(s) with unresolved verdicts in .planning/spikes/
+  {PENDING_SKETCHES} sketch(es) without a winning variant in .planning/sketches/
+
+  Resume with `/sdd:spike` or `/sdd:sketch`, or continue with phase work below.
+```
+
+Only show lines for non-zero counts. If both are 0, skip this notice entirely.
+</step>
+
 <step name="determine_next_action">
 Apply routing rules based on state:
 
@@ -55,7 +178,7 @@ If plans exist but not all have matching summaries:
 
 **Route 5: All plans have summaries → verify and complete**
 If all plans in the current phase have summaries:
-→ Next action: `/sdd:verify-work` then `/sdd:complete-phase`
+→ Next action: `/sdd:verify-work`
 
 **Route 6: Phase complete, next phase exists → advance**
 If the current phase is complete and the next phase exists in ROADMAP:
@@ -79,12 +202,12 @@ Display the determination:
 **Current:** Phase [N] — [name] | [progress]%
 **Status:** [status description]
 
-▶ **Next step:** `/sdd:[command] [args]`
+▶ **Next step:** `/sdd-[command] [args]`
   [One-line explanation of why this is the next step]
 ```
 
 Then immediately invoke the determined command via SlashCommand.
-Do not ask for confirmation — the whole point of `/sdd:next` is zero-friction advancement.
+Do not ask for confirmation — the whole point of `/sdd:progress --next` is zero-friction advancement.
 </step>
 
 </process>

package/sdd/workflows/note.md

@@ -1,5 +1,7 @@
 <purpose>
 Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+
+**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.
 Runs inline — no Task, no AskUserQuestion, no Bash.
 </purpose>
 
@@ -43,7 +45,7 @@ promoted: false
 | Arguments are empty (no text at all) | **list** |
 | Anything else | **append** (the text IS the note) |
 
-**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/sdd:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/sdd-note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
 </step>
 
 <step name="append">
@@ -87,7 +89,7 @@ Project (.planning/notes/):
 Global (~/.claude/notes/):
   4. [2026-02-08 10:00] cross-project idea about shared config
 
-{count} active note(s). Use `/sdd:note promote <N>` to convert to a todo.
+{count} active note(s). Use `/sdd-note promote <N>` to convert to a todo.
 ```
 
 If a scope has no directory or no entries, show: `(no notes)`
@@ -101,7 +103,7 @@ If a scope has no directory or no entries, show: `(no notes)`
 3. If N is invalid or refers to an already-promoted note, tell the user and stop
 4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a SDD project. Run `/sdd:new-project` to initialize one."
 5. Ensure `.planning/todos/pending/` directory exists
-6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/completed/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
 7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
@@ -110,7 +112,7 @@ If a scope has no directory or no entries, show: `(no notes)`
 title: "{note text}"
 status: pending
 priority: P2
-source: "promoted from /sdd:note"
+source: "promoted from /sdd-note"
 created: {YYYY-MM-DD}
 theme: general
 ---
@@ -135,7 +137,7 @@ Promoted from quick note captured on {original date}.
 </process>
 
 <edge_cases>
-1. **"list" as note text**: `/sdd:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+1. **"list" as note text**: `/sdd-note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
 2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
 3. **Promote without project**: Warns that todos require `.planning/`, suggests `/sdd:new-project`
 4. **Large files**: `list` shows last 10 when >20 active entries

package/sdd/workflows/pause-work.md

@@ -9,14 +9,32 @@ Read all files referenced by the invoking prompt's execution_context before star
 <process>
 
 <step name="detect">
-Find current phase directory from most recently modified files:
+## Context Detection
+
+Determine what kind of work is being paused and set the handoff destination accordingly:
 
 ```bash
-# Find most recent phase directory with work
-(ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true) | head -1 | grep -oP 'phases/\K[^/]+' || true
+# Check for active phase
+phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true)
+
+# Check for active spike
+spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true)
+
+# Check for active sketch
+sketch=$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2>/dev/null || true ) | head -1 | grep -oP 'sketches/\K[^/]+' || true)
+
+# Check for active deliberation
+deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true)
 ```
 
-If no active phase detected, ask user which phase they're pausing work on.
+- **Phase work**: active phase directory → handoff to `.planning/phases/XX-name/.continue-here.md`
+- **Spike work**: active spike directory or spike-related files (no active phase) → handoff to `.planning/spikes/SPIKE-NNN/.continue-here.md` (create directory if needed)
+- **Sketch work**: active sketch directory (no active phase/spike) → handoff to `.planning/sketches/.continue-here.md`
+- **Deliberation work**: active deliberation file (no phase/spike/sketch) → handoff to `.planning/deliberations/.continue-here.md`
+- **Research work**: research notes exist but no phase/spike/sketch/deliberation → handoff to `.planning/.continue-here.md`
+- **Default**: no detectable context → handoff to `.planning/.continue-here.md`, note the ambiguity in `<current_state>`
+
+If phase is detected, proceed with phase handoff path. Otherwise use the first matching non-phase path above.
 </step>
 
 <step name="gather">
@@ -30,6 +48,9 @@ If no active phase detected, ask user which phase they're pausing work on.
 6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
 7. **Background processes**: Any running servers/watchers that were part of the workflow
 8. **Files modified**: What's changed but not committed
+9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
+   - `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
+   - `advisory` — Important context but does not gate resumption.
 
 Ask user for clarifications if needed via conversational questions.
 
@@ -45,7 +66,7 @@ Report any summaries with placeholder content as incomplete items.
 **Write structured handoff to `.planning/HANDOFF.json`:**
 
 ```bash
-timestamp=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" current-timestamp full --raw)
+timestamp=$(sdd-sdk query current-timestamp full --raw)
 ```
 
 ```json
@@ -85,10 +106,11 @@ timestamp=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" current-timestamp full --
 </step>
 
 <step name="write">
-**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
+**Write handoff to the path determined in the detect step** (e.g. `.planning/phases/XX-name/.continue-here.md`, `.planning/spikes/SPIKE-NNN/.continue-here.md`, or `.planning/.continue-here.md`):
 
 ```markdown
 ---
+context: [phase|spike|sketch|deliberation|research|default]
 phase: XX-name
 task: 3
 total_tasks: 7
@@ -96,12 +118,35 @@ status: in_progress
 last_updated: [timestamp from current-timestamp]
 ---
 
+# BLOCKING CONSTRAINTS — Read Before Anything Else
+
+> These are not suggestions. Each constraint below was discovered through failure.
+> Acknowledge each one explicitly before proceeding.
+
+- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]
+
+**Do not proceed until all boxes are checked.**
+
+_If no constraints have been identified yet, remove this section._
+
+## Critical Anti-Patterns
+
+| Pattern | Description | Severity | Prevention Mechanism |
+|---------|-------------|----------|---------------------|
+| [pattern name] | [what it is and how it manifested] | blocking | [structural step that prevents recurrence — not acknowledgment] |
+| [pattern name] | [what it is and how it manifested] | advisory | [guidance for avoiding it] |
+
+**Severity values:** `blocking` — resuming agent must pass understanding check before proceeding. `advisory` — important context, does not gate resumption.
+
+_Remove rows that do not apply. The discuss-phase and execute-phase workflows parse this table and enforce a mandatory understanding check for any `blocking` rows._
+
 <current_state>
 [Where exactly are we? Immediate context]
 </current_state>
 
 <completed_work>
 
+Completed Tasks:
 - Task 1: [name] - Done
 - Task 2: [name] - Done
 - Task 3: [name] - In progress, [what's done]
@@ -124,6 +169,25 @@ last_updated: [timestamp from current-timestamp]
 - [Blocker 1]: [status/workaround]
 </blockers>
 
+## Required Reading (in order)
+<!-- List documents the resuming agent must read before acting -->
+1. [document] — [why it matters]
+1. `.planning/METHODOLOGY.md` (if it exists) — project analytical lenses; apply before any assumption analysis
+
+## Critical Anti-Patterns (do NOT repeat these)
+<!-- Mistakes discovered this session that must be structurally avoided -->
+- [ANTI-PATTERN]: [what it is] → [structural mitigation]
+
+## Infrastructure State
+<!-- Running services, external state, environment specifics -->
+- [service/env]: [current state]
+
+## Pre-Execution Critique Required
+<!-- Fill in ONLY if pausing between design and execution (e.g. spike design done, not yet run) -->
+- Design artifact: [path]
+- Critique focus: [key questions the critic should probe]
+- Gate: Do NOT begin execution until critique is complete and design is revised
+
 <context>
 [Mental state, what were you thinking, the plan]
 </context>
@@ -137,13 +201,13 @@ Be specific enough for a fresh Claude to understand immediately.
 
 Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
 ```bash
-timestamp=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" current-timestamp full --raw)
+timestamp=$(sdd-sdk query current-timestamp full --raw)
 ```
 </step>
 
 <step name="commit">
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/phases/*/.continue-here.md .planning/HANDOFF.json
+sdd-sdk query commit "wip: [context-name] paused at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
 ```
 </step>
 
@@ -151,11 +215,12 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [phase-name] paused at t
 ```
 ✓ Handoff created:
   - .planning/HANDOFF.json (structured, machine-readable)
-  - .planning/phases/[XX-name]/.continue-here.md (human-readable)
+  - [handoff-path] (human-readable)
 
 Current state:
 
-- Phase: [XX-name]
+- Context: [phase|spike|deliberation|research]
+- Location: [XX-name or SPIKE-NNN]
 - Task: [X] of [Y]
 - Status: [in_progress/blocked]
 - Blockers: [count] ({human_actions_pending count} need human action)
@@ -169,8 +234,10 @@ To resume: /sdd:resume-work
 </process>
 
 <success_criteria>
-- [ ] .continue-here.md created in correct phase directory
-- [ ] All sections filled with specific content
+- [ ] Context detected (phase/spike/deliberation/research/default)
+- [ ] .continue-here.md created at correct path for detected context
+- [ ] Required Reading, Anti-Patterns, and Infrastructure State sections filled
+- [ ] Pre-Execution Critique section filled if pausing between design and execution
 - [ ] Committed as WIP
 - [ ] User knows location and how to resume
 </success_criteria>

package/sdd/workflows/plan-milestone-gaps.md

@@ -1,5 +1,5 @@
 <purpose>
-Create all phases necessary to close gaps identified by `/sdd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/sdd:add-phase` per gap.
+Create all phases necessary to close gaps identified by `/sdd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/sdd-add-phase` per gap.
 </purpose>
 
 <required_reading>
@@ -65,7 +65,7 @@ Gap: Flow "View dashboard" broken at data fetch
 Find highest existing phase:
 ```bash
 # Get sorted phase list, extract last one
-HIGHEST=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phases list --pick directories[-1])
+HIGHEST=$(sdd-sdk query phases.list --pick directories[-1])
 ```
 
 New phases continue from there:
@@ -139,14 +139,21 @@ grep -c "Pending" .planning/REQUIREMENTS.md
 
 ## 8. Create Phase Directories
 
+For each new phase (N, N+1, …), resolve the directory name via `init.phase-op` so the `project_code` prefix is honoured:
+
 ```bash
-mkdir -p ".planning/phases/{NN}-{name}"
+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)")
+mkdir -p "${expected_phase_dir}"
 ```
 
+Repeat for each gap-closure phase number. This produces `{CODE}-{NN}-{slug}/` when `project_code` is set in `.planning/config.json`, and `{NN}-{slug}/` otherwise — consistent with all other phase-creation paths.
+
 ## 9. Commit Roadmap and Requirements Update
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+sdd-sdk query commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 
 ## 10. Offer Next Steps
@@ -159,13 +166,13 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs(roadmap): add gap closur
 
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Plan first gap closure phase**
 
-`/sdd:plan-phase {N}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd:plan-phase {N}`
 
 ---