@bhargavvc/sdd-cc 1.30.1 → 1.35.0

package/scripts/rebrand-gsd-to-sdd.sh

@@ -1,220 +1,221 @@
-#!/usr/bin/env bash
-##############################################################################
-# rebrand-gsd-to-sdd.sh (for sdd-cc repo)
-#
-# Converts all G.S.D references to S.D.D in the IDE installer package.
-# IDEMPOTENT — safe to re-run. Excludes itself from modification.
-#
-# USAGE:  bash scripts/rebrand-gsd-to-sdd.sh
-# RUN AFTER:  git merge upstream-sync  (into main)
-##############################################################################
-
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-cd "$REPO_ROOT"
-
-# Build literal strings via hex to avoid self-modification by sed
-OLD_LC=$(printf '\x67\x73\x64')       # g-s-d
-OLD_UC=$(printf '\x47\x53\x44')       # G-S-D
-NEW_LC="sdd"
-NEW_UC="SDD"
-
-# The old framework directory name (hex-encoded to avoid self-match)
-OLD_DIR=$(printf '\x67\x65\x74\x2d\x73\x68\x69\x74\x2d\x64\x6f\x6e\x65')  # get-shit-done
-NEW_DIR="sdd"
-
-# Old branding phrases (hex-encoded)
-OLD_BRAND1=$(printf '\x47\x65\x74\x20\x53\x68\x69\x74\x20\x44\x6f\x6e\x65')  # Get Shit Done
-OLD_BRAND2=$(printf '\x47\x65\x74\x20\x53\x74\x75\x66\x66\x20\x44\x6f\x6e\x65') # Get Stuff Done
-NEW_BRAND="Spec-Driven Development"
-
-SELF_NAME="rebrand-$(echo "${OLD_LC}")-to-${NEW_LC}.sh"
-
-echo "=== ${NEW_UC}-CC Rebrand Script ==="
-echo "Working in: $REPO_ROOT"
-
-# ─── STEP 1: Rename directories ─────────────────────────────────────────────
-echo ""
-echo "[1/5] Renaming directories..."
-
-# Rename get-shit-done/ → sdd/
-if [ -d "${OLD_DIR}" ] && [ ! -d "${NEW_DIR}" ]; then
-  echo "  ${OLD_DIR}/ -> ${NEW_DIR}/"
-  mv "${OLD_DIR}" "${NEW_DIR}"
-fi
-
-# Rename commands/gsd/ → commands/sdd/
-if [ -d "commands/${OLD_LC}" ] && [ ! -d "commands/${NEW_LC}" ]; then
-  echo "  commands/${OLD_LC}/ -> commands/${NEW_LC}/"
-  mv "commands/${OLD_LC}" "commands/${NEW_LC}"
-fi
-
-# Rename internal get-shit-done/commands/gsd/ if it exists
-if [ -d "${NEW_DIR}/commands/${OLD_LC}" ] && [ ! -d "${NEW_DIR}/commands/${NEW_LC}" ]; then
-  echo "  ${NEW_DIR}/commands/${OLD_LC}/ -> ${NEW_DIR}/commands/${NEW_LC}/"
-  mv "${NEW_DIR}/commands/${OLD_LC}" "${NEW_DIR}/commands/${NEW_LC}"
-fi
-
-echo "  Done."
-
-# ─── STEP 2: Rename files ───────────────────────────────────────────────────
-echo ""
-echo "[2/5] Renaming files..."
-
-find . -not -path './.git/*' -not -path './node_modules/*' \
-  -not -name "$SELF_NAME" \
-  \( -name "*${OLD_LC}*" -o -name "*${OLD_UC}*" -o -name "*${OLD_DIR}*" \) \
-  -type f 2>/dev/null | sort -r | while read -r path; do
-  dir=$(dirname "$path")
-  base=$(basename "$path")
-  newbase=$(echo "$base" | sed "s/${OLD_DIR}/${NEW_DIR}/g; s/${OLD_LC}/${NEW_LC}/g; s/${OLD_UC}/${NEW_UC}/g")
-  [ "$base" = "$newbase" ] && continue
-  echo "  $path -> $dir/$newbase"
-  mv "$path" "$dir/$newbase"
-done
-
-echo "  Done."
-
-# ─── STEP 3: Replace content in all files ───────────────────────────────────
-echo ""
-echo "[3/5] Finding files with content to replace..."
-
-grep -rl --include="*.md" --include="*.js" --include="*.cjs" \
-  --include="*.json" --include="*.sh" --include="*.yml" --include="*.yaml" \
-  -E "${OLD_LC}|${OLD_UC}|${OLD_DIR}" . 2>/dev/null \
-  | grep -v '\.git/' | grep -v 'node_modules/' \
-  | grep -v "$SELF_NAME" \
-  | grep -v 'package-lock.json' \
-  > /tmp/${NEW_LC}-cc-rebrand-files.txt || true
-
-FCOUNT=$(wc -l < /tmp/${NEW_LC}-cc-rebrand-files.txt)
-echo "  Found $FCOUNT files."
-
-echo "  Replacing..."
-while IFS= read -r file; do
-  [ -z "$file" ] && continue
-
-  # Branding phrases first (longest match first)
-  sed -i \
-    -e "s/${OLD_BRAND1}/${NEW_BRAND}/g" \
-    -e "s/${OLD_BRAND2}/${NEW_BRAND}/g" \
-    "$file"
-
-  # Directory name: get-shit-done → sdd
-  sed -i \
-    -e "s/${OLD_DIR}-cc/@bhargavvc\/${NEW_LC}-cc/g" \
-    -e "s/${OLD_DIR}/${NEW_DIR}/g" \
-    "$file"
-
-  # Targeted patterns
-  sed -i \
-    -e "s/${OLD_LC}:/${NEW_LC}:/g" \
-    -e "s/${OLD_LC}-/${NEW_LC}-/g" \
-    -e "s/_${OLD_LC}/_${NEW_LC}/g" \
-    -e "s/${OLD_LC}_/${NEW_LC}_/g" \
-    -e "s/\/${OLD_LC}\//\/${NEW_LC}\//g" \
-    -e "s/\.${OLD_LC}\//\.${NEW_LC}\//g" \
-    -e "s/\.${OLD_LC}\"/.${NEW_LC}\"/g" \
-    -e "s/\.${OLD_LC}'/.${NEW_LC}'/g" \
-    -e "s/\"${OLD_LC}\"/\"${NEW_LC}\"/g" \
-    -e "s/'${OLD_LC}'/'${NEW_LC}'/g" \
-    -e "s/@${OLD_LC}\//@${NEW_LC}\//g" \
-    -e "s/${OLD_UC}_/${NEW_UC}_/g" \
-    -e "s/\"${OLD_UC}\"/\"${NEW_UC}\"/g" \
-    -e "s/'${OLD_UC}'/'${NEW_UC}'/g" \
-    "$file"
-
-  # Variable syntax: {{GSD_ARGS}} → {{SDD_ARGS}}
-  sed -i \
-    -e "s/{{${OLD_UC}_ARGS}}/{{${NEW_UC}_ARGS}}/g" \
-    -e "s/{{${OLD_UC}_/{{${NEW_UC}_/g" \
-    "$file"
-
-  # Catch-all: remaining standalone instances
-  sed -i \
-    -e "s/\b${OLD_LC}\b/${NEW_LC}/g" \
-    -e "s/\b${OLD_UC}\b/${NEW_UC}/g" \
-    "$file"
-
-  # Restore @gsd-build (upstream npm scope — must stay)
-  if grep -q "${NEW_LC}-build" "$file" 2>/dev/null; then
-    sed -i \
-      -e "s/@${NEW_LC}-build/@${OLD_LC}-build/g" \
-      -e "s/${NEW_LC}-build\//${OLD_LC}-build\//g" \
-      "$file"
-  fi
-
-done < /tmp/${NEW_LC}-cc-rebrand-files.txt
-
-rm -f /tmp/${NEW_LC}-cc-rebrand-files.txt
-echo "  Done."
-
-# ─── STEP 4: Fix package.json ───────────────────────────────────────────────
-echo ""
-echo "[4/5] Updating package.json..."
-
-if [ -f "package.json" ]; then
-  # Fix package name and bin
-  sed -i \
-    -e 's/"name": *"[^"]*"/"name": "@bhargavvc\/sdd-cc"/' \
-    -e 's/"sdd-cc-cc"/"sdd-cc"/' \
-    -e "s/\"${OLD_DIR}-cc\"/\"${NEW_LC}-cc\"/g" \
-    package.json
-
-  # Fix bin entry: the key might already be partially renamed
-  # Ensure bin is exactly: "sdd-cc": "bin/install.js"
-  node -e "
-    const pkg = require('./package.json');
-    const fs = require('fs');
-    pkg.name = '@bhargavvc/sdd-cc';
-    pkg.bin = { 'sdd-cc': 'bin/install.js' };
-    pkg.description = pkg.description
-      .replace(/Get Shit Done/gi, 'Spec-Driven Development')
-      .replace(/GSD/g, 'SDD')
-      .replace(/gsd/g, 'sdd');
-    pkg.repository = { type: 'git', url: 'git+https://github.com/bhargavvc/sdd-cc.git' };
-    pkg.homepage = 'https://github.com/bhargavvc/sdd-cc';
-    pkg.bugs = { url: 'https://github.com/bhargavvc/sdd-cc/issues' };
-    pkg.publishConfig = { access: 'public' };
-    fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-  "
-  echo "  package.json updated."
-fi
-
-echo "  Done."
-
-# ─── STEP 5: Verify ─────────────────────────────────────────────────────────
-echo ""
-echo "[5/5] Verifying..."
-
-STALE_COUNT=0
-
-echo "  Checking for stale references..."
-# Check markdown and source files for remaining gsd (excluding @gsd-build and this script)
-STALE=$(grep -rn "${OLD_LC}\|${OLD_DIR}" \
-  --include="*.md" --include="*.js" --include="*.cjs" \
-  . 2>/dev/null \
-  | grep -v '\.git/' | grep -v 'node_modules/' \
-  | grep -v "$SELF_NAME" \
-  | grep -v "@${OLD_LC}-build" \
-  | grep -v "REBRAND" \
-  | head -20 || true)
-
-if [ -n "$STALE" ]; then
-  echo "  WARNING: Stale references found:"
-  echo "$STALE"
-  STALE_COUNT=$(echo "$STALE" | wc -l)
-else
-  echo "  No stale references found."
-fi
-
-echo ""
-echo "=== Rebrand complete ==="
-echo "  Stale references: $STALE_COUNT"
-echo ""
-echo "  Next steps:"
-echo "  1. Review changes: git diff --stat"
-echo "  2. Test installer:  node bin/install.js --cursor --local"
-echo "  3. Commit:          git add -A && git commit -m 'rebrand: GSD → SDD'"
-echo "  4. Publish:         npm publish --access public"
+#!/usr/bin/env bash
+##############################################################################
+# rebrand-gsd-to-sdd.sh (for sdd-cc repo)
+#
+# Converts all G.S.D references to S.D.D in the IDE installer package.
+# IDEMPOTENT — safe to re-run. Excludes itself from modification.
+#
+# USAGE:  bash scripts/rebrand-gsd-to-sdd.sh
+# RUN AFTER:  git merge upstream-sync  (into main)
+##############################################################################
+
+set -eu
+# Note: pipefail removed — grep returns 1 for "no matches" which is normal
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Build literal strings via hex to avoid self-modification by sed
+OLD_LC=$(printf '\x67\x73\x64')       # g-s-d
+OLD_UC=$(printf '\x47\x53\x44')       # G-S-D
+NEW_LC="sdd"
+NEW_UC="SDD"
+
+# The old framework directory name (hex-encoded to avoid self-match)
+OLD_DIR=$(printf '\x67\x65\x74\x2d\x73\x68\x69\x74\x2d\x64\x6f\x6e\x65')  # get-shit-done
+NEW_DIR="sdd"
+
+# Old branding phrases (hex-encoded)
+OLD_BRAND1=$(printf '\x47\x65\x74\x20\x53\x68\x69\x74\x20\x44\x6f\x6e\x65')  # Get Shit Done
+OLD_BRAND2=$(printf '\x47\x65\x74\x20\x53\x74\x75\x66\x66\x20\x44\x6f\x6e\x65') # Get Stuff Done
+NEW_BRAND="Spec-Driven Development"
+
+SELF_NAME="rebrand-$(echo "${OLD_LC}")-to-${NEW_LC}.sh"
+
+echo "=== ${NEW_UC}-CC Rebrand Script ==="
+echo "Working in: $REPO_ROOT"
+
+# ─── STEP 1: Rename directories ─────────────────────────────────────────────
+echo ""
+echo "[1/5] Renaming directories..."
+
+# Rename get-shit-done/ → sdd/
+if [ -d "${OLD_DIR}" ] && [ ! -d "${NEW_DIR}" ]; then
+  echo "  ${OLD_DIR}/ -> ${NEW_DIR}/"
+  mv "${OLD_DIR}" "${NEW_DIR}"
+fi
+
+# Rename commands/gsd/ → commands/sdd/
+if [ -d "commands/${OLD_LC}" ] && [ ! -d "commands/${NEW_LC}" ]; then
+  echo "  commands/${OLD_LC}/ -> commands/${NEW_LC}/"
+  mv "commands/${OLD_LC}" "commands/${NEW_LC}"
+fi
+
+# Rename internal get-shit-done/commands/gsd/ if it exists
+if [ -d "${NEW_DIR}/commands/${OLD_LC}" ] && [ ! -d "${NEW_DIR}/commands/${NEW_LC}" ]; then
+  echo "  ${NEW_DIR}/commands/${OLD_LC}/ -> ${NEW_DIR}/commands/${NEW_LC}/"
+  mv "${NEW_DIR}/commands/${OLD_LC}" "${NEW_DIR}/commands/${NEW_LC}"
+fi
+
+echo "  Done."
+
+# ─── STEP 2: Rename files ───────────────────────────────────────────────────
+echo ""
+echo "[2/5] Renaming files..."
+
+find . -not -path './.git/*' -not -path './node_modules/*' \
+  -not -name "$SELF_NAME" \
+  \( -name "*${OLD_LC}*" -o -name "*${OLD_UC}*" -o -name "*${OLD_DIR}*" \) \
+  -type f 2>/dev/null | sort -r | while read -r path; do
+  dir=$(dirname "$path")
+  base=$(basename "$path")
+  newbase=$(echo "$base" | sed "s/${OLD_DIR}/${NEW_DIR}/g; s/${OLD_LC}/${NEW_LC}/g; s/${OLD_UC}/${NEW_UC}/g")
+  [ "$base" = "$newbase" ] && continue
+  echo "  $path -> $dir/$newbase"
+  mv "$path" "$dir/$newbase"
+done
+
+echo "  Done."
+
+# ─── STEP 3: Replace content in all files ───────────────────────────────────
+echo ""
+echo "[3/5] Finding files with content to replace..."
+
+grep -rl --include="*.md" --include="*.js" --include="*.cjs" \
+  --include="*.json" --include="*.sh" --include="*.yml" --include="*.yaml" \
+  -E "${OLD_LC}|${OLD_UC}|${OLD_DIR}" . 2>/dev/null \
+  | grep -v '\.git/' | grep -v 'node_modules/' \
+  | grep -v "$SELF_NAME" \
+  | grep -v 'package-lock.json' \
+  > /tmp/${NEW_LC}-cc-rebrand-files.txt || true
+
+FCOUNT=$(wc -l < /tmp/${NEW_LC}-cc-rebrand-files.txt)
+echo "  Found $FCOUNT files."
+
+echo "  Replacing..."
+while IFS= read -r file; do
+  [ -z "$file" ] && continue
+
+  # Branding phrases first (longest match first)
+  sed -i \
+    -e "s/${OLD_BRAND1}/${NEW_BRAND}/g" \
+    -e "s/${OLD_BRAND2}/${NEW_BRAND}/g" \
+    "$file"
+
+  # Directory name: get-shit-done → sdd
+  sed -i \
+    -e "s/${OLD_DIR}-cc/@bhargavvc\/${NEW_LC}-cc/g" \
+    -e "s/${OLD_DIR}/${NEW_DIR}/g" \
+    "$file"
+
+  # Targeted patterns
+  sed -i \
+    -e "s/${OLD_LC}:/${NEW_LC}:/g" \
+    -e "s/${OLD_LC}-/${NEW_LC}-/g" \
+    -e "s/_${OLD_LC}/_${NEW_LC}/g" \
+    -e "s/${OLD_LC}_/${NEW_LC}_/g" \
+    -e "s/\/${OLD_LC}\//\/${NEW_LC}\//g" \
+    -e "s/\.${OLD_LC}\//\.${NEW_LC}\//g" \
+    -e "s/\.${OLD_LC}\"/.${NEW_LC}\"/g" \
+    -e "s/\.${OLD_LC}'/.${NEW_LC}'/g" \
+    -e "s/\"${OLD_LC}\"/\"${NEW_LC}\"/g" \
+    -e "s/'${OLD_LC}'/'${NEW_LC}'/g" \
+    -e "s/@${OLD_LC}\//@${NEW_LC}\//g" \
+    -e "s/${OLD_UC}_/${NEW_UC}_/g" \
+    -e "s/\"${OLD_UC}\"/\"${NEW_UC}\"/g" \
+    -e "s/'${OLD_UC}'/'${NEW_UC}'/g" \
+    "$file"
+
+  # Variable syntax: {{GSD_ARGS}} → {{SDD_ARGS}}
+  sed -i \
+    -e "s/{{${OLD_UC}_ARGS}}/{{${NEW_UC}_ARGS}}/g" \
+    -e "s/{{${OLD_UC}_/{{${NEW_UC}_/g" \
+    "$file"
+
+  # Catch-all: remaining standalone instances
+  sed -i \
+    -e "s/\b${OLD_LC}\b/${NEW_LC}/g" \
+    -e "s/\b${OLD_UC}\b/${NEW_UC}/g" \
+    "$file"
+
+  # Restore @gsd-build (upstream npm scope — must stay)
+  if grep -q "${NEW_LC}-build" "$file" 2>/dev/null; then
+    sed -i \
+      -e "s/@${NEW_LC}-build/@${OLD_LC}-build/g" \
+      -e "s/${NEW_LC}-build\//${OLD_LC}-build\//g" \
+      "$file"
+  fi
+
+done < /tmp/${NEW_LC}-cc-rebrand-files.txt
+
+rm -f /tmp/${NEW_LC}-cc-rebrand-files.txt
+echo "  Done."
+
+# ─── STEP 4: Fix package.json ───────────────────────────────────────────────
+echo ""
+echo "[4/5] Updating package.json..."
+
+if [ -f "package.json" ]; then
+  # Fix package name and bin
+  sed -i \
+    -e 's/"name": *"[^"]*"/"name": "@bhargavvc\/sdd-cc"/' \
+    -e 's/"sdd-cc-cc"/"sdd-cc"/' \
+    -e "s/\"${OLD_DIR}-cc\"/\"${NEW_LC}-cc\"/g" \
+    package.json
+
+  # Fix bin entry: the key might already be partially renamed
+  # Ensure bin is exactly: "sdd-cc": "bin/install.js"
+  node -e "
+    const pkg = require('./package.json');
+    const fs = require('fs');
+    pkg.name = '@bhargavvc/sdd-cc';
+    pkg.bin = { 'sdd-cc': 'bin/install.js' };
+    pkg.description = pkg.description
+      .replace(/Get Shit Done/gi, 'Spec-Driven Development')
+      .replace(/GSD/g, 'SDD')
+      .replace(/gsd/g, 'sdd');
+    pkg.repository = { type: 'git', url: 'git+https://github.com/bhargavvc/sdd-cc.git' };
+    pkg.homepage = 'https://github.com/bhargavvc/sdd-cc';
+    pkg.bugs = { url: 'https://github.com/bhargavvc/sdd-cc/issues' };
+    pkg.publishConfig = { access: 'public' };
+    fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+  "
+  echo "  package.json updated."
+fi
+
+echo "  Done."
+
+# ─── STEP 5: Verify ─────────────────────────────────────────────────────────
+echo ""
+echo "[5/5] Verifying..."
+
+STALE_COUNT=0
+
+echo "  Checking for stale references..."
+# Check markdown and source files for remaining gsd (excluding @gsd-build and this script)
+STALE=$(grep -rn "${OLD_LC}\|${OLD_DIR}" \
+  --include="*.md" --include="*.js" --include="*.cjs" \
+  . 2>/dev/null \
+  | grep -v '\.git/' | grep -v 'node_modules/' \
+  | grep -v "$SELF_NAME" \
+  | grep -v "@${OLD_LC}-build" \
+  | grep -v "REBRAND" \
+  | head -20 || true)
+
+if [ -n "$STALE" ]; then
+  echo "  WARNING: Stale references found:"
+  echo "$STALE"
+  STALE_COUNT=$(echo "$STALE" | wc -l)
+else
+  echo "  No stale references found."
+fi
+
+echo ""
+echo "=== Rebrand complete ==="
+echo "  Stale references: $STALE_COUNT"
+echo ""
+echo "  Next steps:"
+echo "  1. Review changes: git diff --stat"
+echo "  2. Test installer:  node bin/install.js --cursor --local"
+echo "  3. Commit:          git add -A && git commit -m 'rebrand: GSD → SDD'"
+echo "  4. Publish:         npm publish --access public"

package/scripts/run-tests.cjs

@@ -19,8 +19,12 @@ if (files.length === 0) {
   process.exit(1);
 }
 
+const concurrency = process.env.TEST_CONCURRENCY
+  ? `--test-concurrency=${process.env.TEST_CONCURRENCY}`
+  : '--test-concurrency=4';
+
 try {
-  execFileSync(process.execPath, ['--test', ...files], {
+  execFileSync(process.execPath, ['--test', concurrency, ...files], {
     stdio: 'inherit',
     env: { ...process.env },
   });

package/scripts/sync-upstream.sh

@@ -2,7 +2,7 @@
 ##############################################################################
 # sync-upstream.sh
 #
-# Syncs the sdd-cc fork with upstream gsd-build/get-shit-done,
+# Syncs the sdd-cc fork with upstream gsd-build/sdd,
 # then runs the rebrand script.
 #
 # USAGE:  bash scripts/sync-upstream.sh

package/sdd/bin/lib/commands.cjs

@@ -8,6 +8,33 @@ const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, com
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
+/**
+ * Determine phase status by checking plan/summary counts AND verification state.
+ * Introduces "Executed" for phases with all summaries but no passing verification.
+ */
+function determinePhaseStatus(plans, summaries, phaseDir, defaultPending) {
+  if (plans === 0) return defaultPending;
+  if (summaries < plans && summaries > 0) return 'In Progress';
+  if (summaries < plans) return 'Planned';
+
+  // summaries >= plans — check verification
+  try {
+    const files = fs.readdirSync(phaseDir);
+    const verificationFile = files.find(f => f === 'VERIFICATION.md' || f.endsWith('-VERIFICATION.md'));
+    if (verificationFile) {
+      const content = fs.readFileSync(path.join(phaseDir, verificationFile), 'utf-8');
+      if (/status:\s*passed/i.test(content)) return 'Complete';
+      if (/status:\s*human_needed/i.test(content)) return 'Needs Review';
+      if (/status:\s*gaps_found/i.test(content)) return 'Executed';
+      // Verification exists but unrecognized status — treat as executed
+      return 'Executed';
+    }
+  } catch { /* directory read failed — fall through */ }
+
+  // No verification file — executed but not verified
+  return 'Executed';
+}
+
 function cmdGenerateSlug(text, raw) {
   if (!text) {
     error('text required for slug generation');
@@ -16,7 +43,8 @@ function cmdGenerateSlug(text, raw) {
   const slug = text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 60);
 
   const result = { slug };
   output(result, raw, slug);
@@ -254,7 +282,7 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     let branchName = null;
     if (config.branching_strategy === 'phase') {
       // Determine which phase we're committing for from the file paths
-      const phaseMatch = (files || []).join(' ').match(/(\d+)-/);
+      const phaseMatch = (files || []).join(' ').match(/(\d+(?:\.\d+)*)-/);
       if (phaseMatch) {
         const phaseNum = phaseMatch[1];
         const phaseInfo = findPhaseInternal(cwd, phaseNum);
@@ -285,11 +313,19 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
   }
 
   // Stage files
-  const filesToStage = files && files.length > 0 ? files : ['.planning/'];
+  const explicitFiles = files && files.length > 0;
+  const filesToStage = explicitFiles ? files : ['.planning/'];
   for (const file of filesToStage) {
     const fullPath = path.join(cwd, file);
     if (!fs.existsSync(fullPath)) {
-      // File was deleted/moved — stage the deletion
+      if (explicitFiles) {
+        // Caller passed an explicit --files list: missing files are skipped.
+        // Staging a deletion here would silently remove tracked planning files
+        // (e.g. STATE.md, ROADMAP.md) when they are temporarily absent (#2014).
+        continue;
+      }
+      // Default mode (staging all of .planning/): stage the deletion so
+      // removed planning files are not left dangling in the index.
       execGit(cwd, ['rm', '--cached', '--ignore-unmatch', file]);
     } else {
       execGit(cwd, ['add', file]);
@@ -528,11 +564,7 @@ function cmdProgressRender(cwd, format, raw) {
       totalPlans += plans;
       totalSummaries += summaries;
 
-      let status;
-      if (plans === 0) status = 'Pending';
-      else if (summaries >= plans) status = 'Complete';
-      else if (summaries > 0) status = 'In Progress';
-      else status = 'Planned';
+      const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Pending');
 
       phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
     }
@@ -741,7 +773,7 @@ function cmdScaffold(cwd, type, options, raw) {
   switch (type) {
     case 'context': {
       filePath = path.join(phaseDir, `${padded}-CONTEXT.md`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /sdd:discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /sdd-discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
       break;
     }
     case 'uat': {
@@ -828,18 +860,14 @@ function cmdStats(cwd, format, raw) {
       totalPlans += plans;
       totalSummaries += summaries;
 
-      let status;
-      if (plans === 0) status = 'Not Started';
-      else if (summaries >= plans) status = 'Complete';
-      else if (summaries > 0) status = 'In Progress';
-      else status = 'Planned';
+      const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Not Started');
 
       const existing = phasesByNumber.get(phaseNum);
       phasesByNumber.set(phaseNum, {
         number: phaseNum,
         name: existing?.name || phaseName,
-        plans,
-        summaries,
+        plans: (existing?.plans || 0) + plans,
+        summaries: (existing?.summaries || 0) + summaries,
         status,
       });
     }
@@ -940,6 +968,39 @@ function cmdStats(cwd, format, raw) {
   }
 }
 
+/**
+ * Check whether a commit should be allowed based on commit_docs config.
+ * When commit_docs is false, rejects commits that stage .planning/ files.
+ * Intended for use as a pre-commit hook guard.
+ */
+function cmdCheckCommit(cwd, raw) {
+  const config = loadConfig(cwd);
+
+  // If commit_docs is true (or not set), allow all commits
+  if (config.commit_docs !== false) {
+    output({ allowed: true, reason: 'commit_docs_enabled' }, raw, 'allowed');
+    return;
+  }
+
+  // commit_docs is false — check if any .planning/ files are staged
+  try {
+    const staged = execSync('git diff --cached --name-only', { cwd, encoding: 'utf-8' }).trim();
+    const planningFiles = staged.split('\n').filter(f => f.startsWith('.planning/') || f.startsWith('.planning\\'));
+
+    if (planningFiles.length > 0) {
+      error(
+        `commit_docs is false but ${planningFiles.length} .planning/ file(s) are staged:\n` +
+        planningFiles.map(f => `  ${f}`).join('\n') +
+        `\n\nTo unstage: git reset HEAD ${planningFiles.join(' ')}`
+      );
+    }
+  } catch {
+    // git diff --cached failed (no staged files or not a git repo) — allow
+  }
+
+  output({ allowed: true, reason: 'no_planning_files_staged' }, raw, 'allowed');
+}
+
 module.exports = {
   cmdGenerateSlug,
   cmdCurrentTimestamp,
@@ -956,4 +1017,5 @@ module.exports = {
   cmdTodoMatchPhase,
   cmdScaffold,
   cmdStats,
+  cmdCheckCommit,
 };