@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/{commands/sdd → sdd/workflows}/reapply-patches.md

@@ -1,14 +1,10 @@
----
-name: sdd:reapply-patches
-description: Reapply local modifications after a SDD update
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
+# Reapply Local Patches Workflow
 
-<purpose>
-After a SDD update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to reliably distinguish user customizations from version drift.
+Invoked by `/sdd:update --reapply` (`commands/sdd/update.md`).
+
+After a SDD update wipes and reinstalls files, this workflow merges user's previously saved local modifications back into the new version. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to reliably distinguish user customizations from version drift.
 
 **Critical invariant:** Every file in `sdd-local-patches/` was backed up because the installer's hash comparison detected it was modified. The workflow must NEVER conclude "no custom content" for any backed-up file — that is a logical contradiction. When in doubt, classify as CONFLICT requiring user review, not SKIP.
-</purpose>
 
 <process>
 
@@ -115,7 +111,7 @@ Read `backup-meta.json` from the patches directory.
 ```
 No local patches found. Nothing to reapply.
 
-Local patches are automatically saved when you run /sdd-update
+Local patches are automatically saved when you run /sdd:update
 after modifying any SDD workflow, command, or agent files.
 ```
 Exit.
@@ -129,7 +125,7 @@ The quality of the merge depends on having a **pristine baseline** — the origi
 
 Check for baseline sources in priority order:
 
-### Option A: Git history (most reliable)
+### Option A: Pristine hash from backup-meta.json + git history (most reliable)
 If the config directory is a git repository:
 ```bash
 CONFIG_DIR=$(dirname "$PATCHES_DIR")
@@ -137,15 +133,35 @@ if git -C "$CONFIG_DIR" rev-parse --git-dir >/dev/null 2>&1; then
   HAS_GIT=true
 fi
 ```
-When `HAS_GIT=true`, use `git log` to find the commit where SDD was originally installed (before user edits). For each file, the pristine baseline can be extracted with:
+When `HAS_GIT=true`, use the `pristine_hashes` recorded in `backup-meta.json` to locate the correct baseline commit. For each file, iterate commits that touched it and find the one whose blob SHA-256 matches the recorded pristine hash:
 ```bash
-git -C "$CONFIG_DIR" log --diff-filter=A --format="%H" -- "{file_path}"
+# Get the expected pristine SHA-256 from backup-meta.json
+PRISTINE_HASH=$(jq -r ".pristine_hashes[\"${file_path}\"] // empty" "$PATCHES_DIR/backup-meta.json")
+
+BASELINE_COMMIT=""
+if [ -n "$PRISTINE_HASH" ]; then
+  # Walk commits that touched this file, pick the one matching the pristine hash
+  while IFS= read -r commit_hash; do
+    blob_hash=$(git -C "$CONFIG_DIR" show "${commit_hash}:${file_path}" 2>/dev/null | sha256sum | cut -d' ' -f1)
+    if [ "$blob_hash" = "$PRISTINE_HASH" ]; then
+      BASELINE_COMMIT="$commit_hash"
+      break
+    fi
+  done < <(git -C "$CONFIG_DIR" log --format="%H" -- "${file_path}")
+fi
+
+# Fallback: if no pristine hash in backup-meta (older installer), use first-add commit
+if [ -z "$BASELINE_COMMIT" ]; then
+  BASELINE_COMMIT=$(git -C "$CONFIG_DIR" log --diff-filter=A --format="%H" -- "${file_path}" | tail -1)
+fi
 ```
-This gives the commit that first added the file (the install commit). Extract the pristine version:
+Extract the pristine version from the matched commit:
 ```bash
-git -C "$CONFIG_DIR" show {install_commit}:{file_path}
+git -C "$CONFIG_DIR" show "${BASELINE_COMMIT}:${file_path}"
 ```
 
+**Why this matters:** `git log --diff-filter=A` returns the commit that *first added* the file, which is the wrong baseline on repos that have been through multiple SDD update cycles. The `pristine_hashes` field in `backup-meta.json` records the SHA-256 of the file as it existed in the pre-update SDD release — matching against it finds the correct baseline regardless of how many updates have occurred.
+
 ### Option B: Pristine snapshot directory
 Check if a `sdd-pristine/` directory exists alongside `sdd-local-patches/`:
 ```bash
@@ -212,7 +228,7 @@ d. **If ALL differences appear to be mechanical drift → still flag as CONFLICT
 When the config directory is a git repo but the pristine install commit can't be found, use commit history to identify user changes:
 ```bash
 # Find non-update commits that touched this file
-git -C "$CONFIG_DIR" log --oneline --no-merges -- "{file_path}" | grep -v "sdd:update\|SDD update\|sdd-install"
+git -C "$CONFIG_DIR" log --oneline --no-merges -- "{file_path}" | grep -v "sdd:update\|sdd-update\|SDD update\|sdd-install"
 ```
 Each matching commit represents an intentional user modification. Use the commit messages and diffs to understand what was changed and why.
 
@@ -253,17 +269,80 @@ After writing each merged file, verify that user modifications survived the merg
 
 ## Step 5: Hunk Verification Gate
 
-Before proceeding to cleanup, evaluate the Hunk Verification Table produced in Step 4.
+Two layered gates. Both must pass before proceeding to cleanup.
+
+### 5a: Deterministic verifier (binding gate, #2969)
 
-**If the Hunk Verification Table is absent** (Step 4 did not produce it), STOP immediately and report to the user:
+Run the deterministic verifier script. Do NOT rely solely on the free-text `verified: yes/no` Hunk Verification Table from Step 4 — bug #2969 traced repeated false-positive `verified: yes` reports to that table being filled in without an actual content-presence check. The script performs the check structurally and exits non-zero on any miss.
+
+Run the verifier as a child process (the sdd-tools binary directory is not required — the script ships under `sdd/bin/` in the source repo and is installed to `${SDD_HOME}/sdd/bin/`; it is also exposed via the SDK at `sdk/dist/cli.js verify-reapply` when present):
+
+```bash
+PRISTINE_DIR="${CONFIG_DIR}/sdd-pristine"
+
+# Build args as a bash array so paths with spaces survive expansion intact
+# (string-concat + unquoted expansion would split incorrectly on whitespace).
+VERIFY_ARGS=(
+  --patches-dir "$PATCHES_DIR"
+  --config-dir  "$CONFIG_DIR"
+)
+if [ -d "$PRISTINE_DIR" ]; then
+  VERIFY_ARGS+=(--pristine-dir "$PRISTINE_DIR")
+fi
+VERIFY_ARGS+=(--json)
+
+# Capture stdout (the structured JSON report) separately from stderr so that
+# Node warnings, deprecation notices, or stack traces do not corrupt the
+# JSON parse downstream. Stderr is preserved on the controlling terminal
+# for operator visibility.
+VERIFY_OUTPUT="$(node "${SDD_HOME}/sdd/bin/verify-reapply-patches.cjs" "${VERIFY_ARGS[@]}")"
+VERIFY_STATUS=$?
 ```
-ERROR: Hunk Verification Table is missing. Post-merge verification was not completed.
-Rerun /sdd-reapply-patches to retry with full verification.
+
+**If `VERIFY_STATUS` is non-zero**, STOP and report to the user, parsing the JSON output:
+
+```text
+ERROR: {failures} file(s) failed deterministic post-merge verification (#2969 gate).
+
+The verifier compared user-added lines (computed from the diff between
+the backup and the pristine baseline) against the merged installed file.
+Lines listed below are present in the backup but absent from the merged result.
+
+For each failed file:
+  {file}
+    missing: {first significant missing line, up to 5 per file}
+    backup:  {patches_dir}/{file}
+
+Resolve before proceeding:
+  (a) Re-merge the missing content into the installed file by hand, or
+  (b) Restore from backup: cp {patches_dir}/{file} {installed_path}
+
+Then re-run /sdd:update --reapply to re-verify.
+```
+
+Do not proceed to cleanup until the verifier exits 0.
+
+**Only when `VERIFY_STATUS` is 0** (or when all files had zero significant user-added lines, which the verifier reports as `Failures: 0`) may execution continue to gate 5b.
+
+### 5b: Hunk Verification Table review (advisory gate, #1999)
+
+The Hunk Verification Table produced in Step 4 must also be reviewed before proceeding. This is advisory after the script gate but is preserved as a defense-in-depth check — if the script ever has a bug or the pristine baseline is unavailable, the table-based gate still catches obvious regressions.
+
+**If the Hunk Verification Table is absent** (Step 4 silently produced nothing), STOP and report:
+
 ```
+ERROR: Hunk Verification Table is missing — Step 4 did not produce it.
+The deterministic verifier (5a) may still have passed, but a missing table
+means post-merge verification was not fully completed. Rerun
+/sdd:update --reapply to retry with full verification.
+```
+
+A missing table absent from the workflow output cannot bypass this gate.
+
+**If any row in the Hunk Verification Table shows `verified: no`**, STOP and report:
 
-**If any row in the Hunk Verification Table shows `verified: no`**, STOP and report to the user:
 ```
-ERROR: {N} hunk(s) failed verification — content may have been dropped during merge.
+ERROR: {N} hunk(s) failed Step 5b verification — content may have been dropped during merge.
 
 Unverified hunks:
   {file} hunk {hunk_id}: signature line "{signature_line}" not found in merged output
@@ -274,9 +353,9 @@ Review the merged file manually, then either:
   (b) Restore from backup: cp {patches_dir}/{file} {installed_path}
 ```
 
-Do not proceed to cleanup until the user confirms they have resolved all unverified hunks.
+Do not proceed to cleanup until both gates (5a and 5b) pass.
 
-**Only when all rows show `verified: yes`** (or when all files had zero user-added hunks) may execution continue to Step 6.
+**Why both gates?** 5a (the script) is the binding gate — it does the actual substring check structurally and cannot be shortcut by the LLM. 5b (the table review) is the advisory gate — it provides a redundant safety net via the Step 4 prose summary, ensuring that even a script regression or absent pristine baseline cannot silently allow a `verified: no` row to slip past, nor can a missing table go unnoticed. Layered gates favour false-positive halts (recoverable) over silent successes on lost content (unrecoverable).
 
 ## Step 6: Cleanup option
 

package/sdd/workflows/remove-phase.md

@@ -29,7 +29,7 @@ Exit.
 Load phase operation context:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init phase-op "${target}")
+INIT=$(sdd-sdk query init.phase-op "${target}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -53,7 +53,7 @@ Only future phases can be removed:
 - Current phase: {current}
 - Phase {target} is current or completed
 
-To abandon current work, use /sdd-pause-work instead.
+To abandon current work, use /sdd:pause-work instead.
 ```
 
 Exit.
@@ -77,16 +77,16 @@ Wait for confirmation.
 </step>
 
 <step name="execute_removal">
-**Delegate the entire removal operation to sdd-tools:**
+**Delegate the entire removal operation to `sdd-sdk query phase.remove`:**
 
 ```bash
-RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase remove "${target}")
+RESULT=$(sdd-sdk query phase.remove "${target}")
 ```
 
-If the phase has executed plans (SUMMARY.md files), sdd-tools will error. Use `--force` only if the user confirms:
+If the phase has executed plans (SUMMARY.md files), the CLI will error. Use `--force` only if the user confirms:
 
 ```bash
-RESULT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" phase remove "${target}" --force)
+RESULT=$(sdd-sdk query phase.remove "${target}" --force)
 ```
 
 The CLI handles:
@@ -103,7 +103,7 @@ Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `ren
 Stage and commit the removal:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+sdd-sdk query commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
 ```
 
 The commit message preserves the historical record of what was removed.
@@ -126,7 +126,7 @@ Changes:
 ## What's Next
 
 Would you like to:
-- `/sdd-progress` — see updated roadmap status
+- `/sdd:progress` — see updated roadmap status
 - Continue with current phase
 - Review roadmap
 
@@ -140,7 +140,7 @@ Would you like to:
 
 - Don't remove completed phases (have SUMMARY.md files) without --force
 - Don't remove current or past phases
-- Don't manually renumber — use `sdd-tools phase remove` which handles all renumbering
+- Don't manually renumber — use `sdd-sdk query phase.remove` which handles all renumbering
 - Don't add "removed phase" notes to STATE.md — git commit is the record
 - Don't modify completed phase directories
 </anti_patterns>
@@ -149,7 +149,7 @@ Would you like to:
 Phase removal is complete when:
 
 - [ ] Target phase validated as future/unstarted
-- [ ] `sdd-tools phase remove` executed successfully
+- [ ] `sdd-sdk query phase.remove` executed successfully
 - [ ] Changes committed with descriptive message
 - [ ] User informed of changes
 </success_criteria>

package/sdd/workflows/remove-workspace.md

@@ -13,7 +13,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 Extract workspace name from $ARGUMENTS.
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init remove-workspace "$WORKSPACE_NAME")
+INIT=$(sdd-sdk query init.remove-workspace "$WORKSPACE_NAME")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -43,7 +43,7 @@ Cannot remove workspace "$WORKSPACE_NAME" — the following repos have uncommitt
   - repo2
 
 Commit or stash changes in these repos before removing the workspace:
-  cd $WORKSPACE_PATH/repo1
+  cd "$WORKSPACE_PATH/repo1"
   git stash   # or git commit
 ```
 
@@ -62,21 +62,36 @@ Use AskUserQuestion:
 
 **If strategy is `worktree`:**
 
+Initialize the failure flag once before iterating repos:
+
+```bash
+REMOVE_FAILED=false
+```
+
 For each repo in the workspace:
 
 ```bash
 cd "$SOURCE_REPO_PATH"
-git worktree remove "$WORKSPACE_PATH/$REPO_NAME" 2>&1 || true
+if ! git worktree remove "$WORKSPACE_PATH/$REPO_NAME" 2>&1; then
+  echo "Warning: Could not remove worktree for $REPO_NAME — source repo may have been moved, deleted, locked, or dirty." >&2
+  REMOVE_FAILED=true
+fi
 ```
 
-If `git worktree remove` fails, warn but continue:
-```
-Warning: Could not remove worktree for $REPO_NAME — source repo may have been moved or deleted.
+If any `git worktree remove` fails, stop before deleting the workspace directory:
+```text
+Refusing to delete "$WORKSPACE_PATH" because one or more git worktrees could not be removed.
+Resolve the failed worktree removal manually, then rerun remove-workspace.
 ```
 
 ## 5. Delete Workspace Directory
 
 ```bash
+if [ "${REMOVE_FAILED:-false}" = "true" ]; then
+  echo "Refusing to delete \"$WORKSPACE_PATH\" because one or more git worktrees could not be removed." >&2
+  exit 1
+fi
+
 rm -rf "$WORKSPACE_PATH"
 ```
 

package/sdd/workflows/resume-project.md

@@ -20,7 +20,7 @@ Instantly restore full project context so "Where were we?" has an immediate, com
 Load all context in one call:
 
 ```bash
-INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init resume)
+INIT=$(sdd-sdk query init.resume)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -28,7 +28,7 @@ Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_ex
 
 **If `state_exists` is true:** Proceed to load_state
 **If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
-**If `planning_exists` is false:** This is a new project - route to /sdd-new-project
+**If `planning_exists` is false:** This is a new project - route to /sdd:new-project
 </step>
 
 <step name="load_state">
@@ -66,8 +66,13 @@ Look for incomplete work that needs attention:
 # Check for structured handoff (preferred — machine-readable)
 cat .planning/HANDOFF.json 2>/dev/null || true
 
-# Check for continue-here files (mid-plan resumption)
-ls .planning/phases/*/.continue-here*.md 2>/dev/null || true
+# Check for continue-here files (phase + non-phase + legacy fallback)
+ls .planning/phases/*/.continue-here*.md \
+   .planning/spikes/*/.continue-here*.md \
+   .planning/sketches/*/.continue-here*.md \
+   .planning/deliberations/.continue-here*.md \
+   .planning/.continue-here*.md \
+   .continue-here*.md 2>/dev/null || true
 
 # Check for plans without summaries (incomplete execution)
 for plan in .planning/phases/*/*-PLAN.md; do
@@ -84,7 +89,7 @@ fi
 
 **If HANDOFF.json exists:**
 
-- This is the primary resumption source — structured data from `/sdd-pause-work`
+- This is the primary resumption source — structured data from `/sdd:pause-work`
 - Parse `status`, `phase`, `plan`, `task`, `total_tasks`, `next_action`
 - Check `blockers` and `human_actions_pending` — surface these immediately
 - Check `completed_tasks` for `in_progress` items — these need attention first
@@ -93,7 +98,7 @@ fi
 - Flag: "Found structured handoff — resuming from task {task}/{total_tasks}"
 - **After successful resumption, delete HANDOFF.json** (it's a one-shot artifact)
 
-**If .continue-here file exists (fallback):**
+**If .continue-here file exists (phase/non-phase/legacy fallback):**
 
 - This is a mid-plan resumption point
 - Read the file for specific resumption context
@@ -140,7 +145,7 @@ Present complete project status to user:
     Resume with: Task tool (resume parameter with agent ID)
 
 [If pending todos exist:]
-📋 [N] pending todos — /sdd-check-todos to review
+📋 [N] pending todos — /sdd:capture --list to review
 
 [If blockers exist:]
 ⚠️  Carried concerns:
@@ -200,11 +205,11 @@ What would you like to do?
 [Primary action based on state - e.g.:]
 1. Resume interrupted agent [if interrupted agent found]
    OR
-1. Execute phase (/sdd-execute-phase {phase} ${SDD_WS})
+1. Execute phase (/sdd:execute-phase {phase} ${SDD_WS})
    OR
-1. Discuss Phase 3 context (/sdd-discuss-phase 3 ${SDD_WS}) [if CONTEXT.md missing]
+1. Discuss Phase 3 context (/sdd:discuss-phase 3 ${SDD_WS}) [if CONTEXT.md missing]
    OR
-1. Plan Phase 3 (/sdd-plan-phase 3 ${SDD_WS}) [if CONTEXT.md exists or discuss option declined]
+1. Plan Phase 3 (/sdd:plan-phase 3 ${SDD_WS}) [if CONTEXT.md exists or discuss option declined]
 
 [Secondary options:]
 2. Review current phase status
@@ -225,39 +230,37 @@ Wait for user selection.
 </step>
 
 <step name="route_to_workflow">
-Based on user selection, route to appropriate workflow:
+Based on user selection, route to appropriate workflow.
 
-- **Execute plan** → Show command for user to run after clearing:
+Resume-specific exception: do **not** emit `/clear then:` here. Resume is already a session-entry flow, so the next command should be shown directly.
+
+- **Execute plan** → Show direct next command:
   ```
   ---
 
-  ## ▶ Next Up
+  ## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
   **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
 
-  `/clear` then:
-
-  `/sdd-execute-phase {phase} ${SDD_WS}`
+  `/sdd:execute-phase {phase} ${SDD_WS}`
 
   ---
   ```
-- **Plan phase** → Show command for user to run after clearing:
+- **Plan phase** → Show direct next command:
   ```
   ---
 
-  ## ▶ Next Up
+  ## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
   **Phase [N]: [Name]** — [Goal from ROADMAP.md]
 
-  `/clear` then:
-
-  `/sdd-plan-phase [phase-number] ${SDD_WS}`
+  `/sdd:plan-phase [phase-number] ${SDD_WS}`
 
   ---
 
   **Also available:**
-  - `/sdd-discuss-phase [N] ${SDD_WS}` — gather context first
-  - `/sdd-research-phase [N] ${SDD_WS}` — investigate unknowns
+  - `/sdd:discuss-phase [N] ${SDD_WS}` — gather context first
+  - `/sdd:plan-phase --research-phase [N] ${SDD_WS}` — investigate unknowns
 
   ---
   ```