@bhargavvc/sdd-cc 1.30.0 → 1.35.0

package/hooks/sdd-statusline.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// sdd-hook-version: {{SDD_VERSION}}
+// Claude Code Statusline - SDD Edition
+// Shows: model | current task (or SDD state) | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// --- SDD state reader -------------------------------------------------------
+
+/**
+ * Walk up from dir looking for .planning/STATE.md.
+ * Returns parsed state object or null.
+ */
+function readSddState(dir) {
+  const home = os.homedir();
+  let current = dir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(current, '.planning', 'STATE.md');
+    if (fs.existsSync(candidate)) {
+      try {
+        return parseStateMd(fs.readFileSync(candidate, 'utf8'));
+      } catch (e) {
+        return null;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current || current === home) break;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Parse STATE.md frontmatter + Phase line from body.
+ * Returns { status, milestone, milestoneName, phaseNum, phaseTotal, phaseName }
+ */
+function parseStateMd(content) {
+  const state = {};
+
+  // YAML frontmatter between --- markers
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    for (const line of fmMatch[1].split('\n')) {
+      const m = line.match(/^(\w+):\s*(.+)/);
+      if (!m) continue;
+      const [, key, val] = m;
+      const v = val.trim().replace(/^["']|["']$/g, '');
+      if (key === 'status') state.status = v === 'null' ? null : v;
+      if (key === 'milestone') state.milestone = v === 'null' ? null : v;
+      if (key === 'milestone_name') state.milestoneName = v === 'null' ? null : v;
+    }
+  }
+
+  // Phase: N of M (name)  or  Phase: none active (...)
+  const phaseMatch = content.match(/^Phase:\s*(\d+)\s+of\s+(\d+)(?:\s+\(([^)]+)\))?/m);
+  if (phaseMatch) {
+    state.phaseNum = phaseMatch[1];
+    state.phaseTotal = phaseMatch[2];
+    state.phaseName = phaseMatch[3] || null;
+  }
+
+  // Fallback: parse Status: from body when frontmatter is absent
+  if (!state.status) {
+    const bodyStatus = content.match(/^Status:\s*(.+)/m);
+    if (bodyStatus) {
+      const raw = bodyStatus[1].trim().toLowerCase();
+      if (raw.includes('ready to plan') || raw.includes('planning')) state.status = 'planning';
+      else if (raw.includes('execut')) state.status = 'executing';
+      else if (raw.includes('complet') || raw.includes('archived')) state.status = 'complete';
+    }
+  }
+
+  return state;
+}
+
+/**
+ * Format SDD state into display string.
+ * Format: "v1.9 Code Quality · executing · fix-graphiti-deployment (1/5)"
+ * Gracefully degrades when parts are missing.
+ */
+function formatSddState(s) {
+  const parts = [];
+
+  // Milestone: version + name (skip placeholder "milestone")
+  if (s.milestone || s.milestoneName) {
+    const ver = s.milestone || '';
+    const name = (s.milestoneName && s.milestoneName !== 'milestone') ? s.milestoneName : '';
+    const ms = [ver, name].filter(Boolean).join(' ');
+    if (ms) parts.push(ms);
+  }
+
+  // Status
+  if (s.status) parts.push(s.status);
+
+  // Phase
+  if (s.phaseNum && s.phaseTotal) {
+    const phase = s.phaseName
+      ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
+      : `ph ${s.phaseNum}/${s.phaseTotal}`;
+    parts.push(phase);
+  }
+
+  return parts.join(' · ');
+}
+
+// --- stdin ------------------------------------------------------------------
+
+function runStatusline() {
+  let input = '';
+  // Timeout guard: if stdin doesn't close within 3s (e.g. pipe issues on
+  // Windows/Git Bash), exit silently instead of hanging. See #775.
+  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to usable context)
+    // Claude Code reserves ~16.5% for autocompact buffer, so usable context
+    // is 83.5% of the total window. We normalize to show 100% at that point.
+    const AUTO_COMPACT_BUFFER_PCT = 16.5;
+    let ctx = '';
+    if (remaining != null) {
+      // Normalize: subtract buffer from remaining, scale to usable range
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+
+      // Write context metrics to bridge file for the context-monitor PostToolUse hook.
+      // The monitor reads this file to inject agent-facing warnings when context is low.
+      // Reject session IDs with path separators or traversal sequences to prevent
+      // a malicious session_id from writing files outside the temp directory.
+      const sessionSafe = session && !/[/\\]|\.\./.test(session);
+      if (sessionSafe) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
+          const bridgeData = JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000)
+          });
+          fs.writeFileSync(bridgePath, bridgeData);
+        } catch (e) {
+          // Silent fail -- bridge is best-effort, don't break statusline
+        }
+      }
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usable context thresholds
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    // Respect CLAUDE_CONFIG_DIR for custom config directory setups (#870)
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+    const todosDir = path.join(claudeDir, 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {
+        // Silently fail on file system errors - don't break statusline
+      }
+    }
+
+    // SDD state (milestone · status · phase) — shown when no todo task
+    const sddStateStr = task ? '' : formatSddState(readSddState(dir) || {});
+
+    // SDD update available?
+    // Check shared cache first (#1421), fall back to runtime-specific cache for
+    // backward compatibility with older sdd-check-update.js versions.
+    let sddUpdate = '';
+    const sharedCacheFile = path.join(homeDir, '.cache', 'sdd', 'sdd-update-check.json');
+    const legacyCacheFile = path.join(claudeDir, 'cache', 'sdd-update-check.json');
+    const cacheFile = fs.existsSync(sharedCacheFile) ? sharedCacheFile : legacyCacheFile;
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          sddUpdate = '\x1b[33m⬆ /sdd-update\x1b[0m │ ';
+        }
+        if (cache.stale_hooks && cache.stale_hooks.length > 0) {
+          sddUpdate += '\x1b[31m⚠ stale hooks — run /sdd-update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    const middle = task
+      ? `\x1b[1m${task}\x1b[0m`
+      : sddStateStr
+        ? `\x1b[2m${sddStateStr}\x1b[0m`
+        : null;
+
+    if (middle) {
+      process.stdout.write(`${sddUpdate}\x1b[2m${model}\x1b[0m │ ${middle} │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${sddUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});
+}
+
+// Export helpers for unit tests. Harmless when run as a script.
+module.exports = { readSddState, parseStateMd, formatSddState };
+
+if (require.main === module) runStatusline();

package/hooks/sdd-validate-commit.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# sdd-validate-commit.sh — PreToolUse hook: enforce Conventional Commits format
+# Blocks git commit commands with non-conforming messages (exit 2).
+# Allows conforming messages and all non-commit commands (exit 0).
+# Uses Node.js for JSON parsing (always available in SDD projects, no jq dependency).
+#
+# OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
+# Enable with: "hooks": { "community": true } in .planning/config.json
+
+# Check opt-in config — exit silently if not enabled
+if [ -f .planning/config.json ]; then
+  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  if [ "$ENABLED" != "1" ]; then exit 0; fi
+else
+  exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract command from JSON using Node (handles escaping correctly, no jq needed)
+CMD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{}})" 2>/dev/null)
+
+# Only check git commit commands
+if [[ "$CMD" =~ ^git[[:space:]]+commit ]]; then
+  # Extract message from -m flag
+  MSG=""
+  if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  elif [[ "$CMD" =~ -m[[:space:]]+\'([^\']+)\' ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  fi
+
+  if [ -n "$MSG" ]; then
+    SUBJECT=$(echo "$MSG" | head -1)
+    # Validate Conventional Commits format
+    if ! [[ "$SUBJECT" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?:[[:space:]].+ ]]; then
+      echo '{"decision": "block", "reason": "Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Subject must be <=72 chars, lowercase, imperative mood, no trailing period."}'
+      exit 2
+    fi
+    if [ ${#SUBJECT} -gt 72 ]; then
+      echo '{"decision": "block", "reason": "Commit subject must be 72 characters or less."}'
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

package/hooks/sdd-workflow-guard.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// sdd-hook-version: {{SDD_VERSION}}
+// SDD Workflow Guard — PreToolUse hook
+// Detects when Claude attempts file edits outside a SDD workflow context
+// (no active /sdd- skill or Task subagent) and injects an advisory warning.
+//
+// This is a SOFT guard — it advises, not blocks. The edit still proceeds.
+// The warning nudges Claude to use /sdd-quick or /sdd-fast instead of
+// making direct edits that bypass state tracking.
+//
+// Enable via config: hooks.workflow_guard: true (default: false)
+// Only triggers on Write/Edit tool calls to non-.planning/ files.
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only guard Write and Edit tool calls
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    // Check if we're inside a SDD workflow (Task subagent or /sdd- skill)
+    // Subagents have a session_id that differs from the parent
+    // and typically have a description field set by the orchestrator
+    if (data.tool_input?.is_subagent || data.session_type === 'task') {
+      process.exit(0);
+    }
+
+    // Check the file being edited
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Allow edits to .planning/ files (SDD state management)
+    if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
+      process.exit(0);
+    }
+
+    // Allow edits to common config/docs files that don't need SDD tracking
+    const allowedPatterns = [
+      /\.gitignore$/,
+      /\.env/,
+      /CLAUDE\.md$/,
+      /AGENTS\.md$/,
+      /GEMINI\.md$/,
+      /settings\.json$/,
+    ];
+    if (allowedPatterns.some(p => p.test(filePath))) {
+      process.exit(0);
+    }
+
+    // Check if workflow guard is enabled
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (!config.hooks?.workflow_guard) {
+          process.exit(0); // Guard disabled (default)
+        }
+      } catch (e) {
+        process.exit(0);
+      }
+    } else {
+      process.exit(0); // No SDD project — don't guard
+    }
+
+    // If we get here: SDD project, guard enabled, file edit outside .planning/,
+    // not in a subagent context. Inject advisory warning.
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a SDD command. ` +
+          'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
+          'Consider using /sdd-fast for trivial fixes or /sdd-quick for larger changes ' +
+          'to maintain project state tracking. ' +
+          'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail — never block tool execution
+    process.exit(0);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhargavvc/sdd-cc",
-  "version": "1.30.0",
+  "version": "1.35.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by TÂCHES.",
   "bin": {
     "sdd-cc": "bin/install.js"
@@ -10,7 +10,7 @@
     "commands",
     "sdd",
     "agents",
-    "hooks/dist",
+    "hooks",
     "scripts"
   ],
   "keywords": [
@@ -36,7 +36,7 @@
     "url": "https://github.com/bhargavvc/sdd-cc/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "devDependencies": {
     "c8": "^11.0.0",

package/scripts/build-hooks.js

@@ -18,8 +18,13 @@ const HOOKS_TO_COPY = [
   'sdd-check-update.js',
   'sdd-context-monitor.js',
   'sdd-prompt-guard.js',
+  'sdd-read-guard.js',
   'sdd-statusline.js',
-  'sdd-workflow-guard.js'
+  'sdd-workflow-guard.js',
+  // Community hooks (bash, opt-in via .planning/config.json hooks.community)
+  'sdd-session-state.sh',
+  'sdd-validate-commit.sh',
+  'sdd-phase-boundary.sh'
 ];
 
 /**
@@ -59,16 +64,22 @@ function build() {
       continue;
     }
 
-    // Validate syntax before copying
-    const syntaxError = validateSyntax(src);
-    if (syntaxError) {
-      console.error(`\x1b[31m✗ ${hook}: SyntaxError — ${syntaxError}\x1b[0m`);
-      hasErrors = true;
-      continue;
+    // Validate JS syntax before copying (.sh files skip — not Node.js)
+    if (hook.endsWith('.js')) {
+      const syntaxError = validateSyntax(src);
+      if (syntaxError) {
+        console.error(`\x1b[31m✗ ${hook}: SyntaxError — ${syntaxError}\x1b[0m`);
+        hasErrors = true;
+        continue;
+      }
     }
 
     console.log(`\x1b[32m✓\x1b[0m Copying ${hook}...`);
     fs.copyFileSync(src, dest);
+    // Preserve executable bit for shell scripts
+    if (hook.endsWith('.sh')) {
+      try { fs.chmodSync(dest, 0o755); } catch (e) { /* Windows */ }
+    }
   }
 
   if (hasErrors) {

package/scripts/prompt-injection-scan.sh

@@ -72,6 +72,7 @@ ALLOWLIST=(
   'tests/security-scan.test.cjs'
   'tests/security.test.cjs'
   'tests/prompt-injection-scan.test.cjs'
+  'tests/verify.test.cjs'
   'sdd/bin/lib/security.cjs'
   'hooks/sdd-prompt-guard.js'
   'SECURITY.md'