@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/hooks/dist/sdd-statusline.js

@@ -7,6 +7,92 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+// --- Config + last-command readers ------------------------------------------
+
+/**
+ * Walk up from dir looking for .planning/config.json and return its parsed contents.
+ * Returns {} if not found or unreadable.
+ */
+function readSddConfig(dir) {
+  const home = os.homedir();
+  let current = dir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(current, '.planning', 'config.json');
+    if (fs.existsSync(candidate)) {
+      try {
+        return JSON.parse(fs.readFileSync(candidate, 'utf8')) || {};
+      } catch (e) {
+        return {};
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current || current === home) break;
+    current = parent;
+  }
+  return {};
+}
+
+/**
+ * Lookup a dotted key path (e.g. 'statusline.show_last_command') in a config
+ * object that may use either nested or flat keys.
+ */
+function getConfigValue(cfg, keyPath) {
+  if (!cfg || typeof cfg !== 'object') return undefined;
+  if (keyPath in cfg) return cfg[keyPath];
+  const parts = keyPath.split('.');
+  let cur = cfg;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object' || !(p in cur)) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+/**
+ * Extract the most recently invoked slash command from a Claude Code JSONL
+ * transcript file. Returns the command name (no leading slash) or null.
+ *
+ * Claude Code embeds slash invocations in user messages as
+ *   <command-name>/foo</command-name>
+ * We scan lines from the end of the file, stopping at the first match.
+ */
+function readLastSlashCommand(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+  let content;
+  try {
+    if (!fs.existsSync(transcriptPath)) return null;
+    // Read only the tail — typical transcripts grow large. 256 KiB comfortably
+    // covers dozens of recent turns while staying cheap per render.
+    const stat = fs.statSync(transcriptPath);
+    const MAX = 256 * 1024;
+    const start = Math.max(0, stat.size - MAX);
+    const fd = fs.openSync(transcriptPath, 'r');
+    try {
+      const buf = Buffer.alloc(stat.size - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      content = buf.toString('utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (e) {
+    return null;
+  }
+  // Find the LAST occurrence — scan right-to-left via lastIndexOf on the tag.
+  const tagClose = '</command-name>';
+  const idx = content.lastIndexOf(tagClose);
+  if (idx < 0) return null;
+  const openTag = '<command-name>';
+  const openIdx = content.lastIndexOf(openTag, idx);
+  if (openIdx < 0) return null;
+  let name = content.slice(openIdx + openTag.length, idx).trim();
+  // Strip a leading slash if present, and any trailing arguments-on-same-line noise.
+  if (name.startsWith('/')) name = name.slice(1);
+  // Command names in Claude Code transcripts are plain identifiers like "sdd-plan-phase"
+  // or namespaced like "plugin:skill". Reject anything with whitespace/newlines/control chars.
+  if (!name || /[\s\\"<>]/.test(name) || name.length > 80) return null;
+  return name;
+}
+
 // --- SDD state reader -------------------------------------------------------
 
 /**
@@ -34,22 +120,69 @@ function readSddState(dir) {
 
 /**
  * Parse STATE.md frontmatter + Phase line from body.
- * Returns { status, milestone, milestoneName, phaseNum, phaseTotal, phaseName }
+ *
+ * Returns:
+ *   { status, milestone, milestoneName, phaseNum, phaseTotal, phaseName,
+ *     activePhase, nextAction, nextPhases, completedPhases, totalPhases, percent }
+ *
+ * Phase-lifecycle fields (issue #2833):
+ *   - activePhase  : phase number ("4.5") when an orchestrator is mid-flight, null otherwise
+ *   - nextAction   : recommended next command ("execute-phase") when idle, null otherwise
+ *   - nextPhases   : array of phase numbers (["4.5"]) for nextAction, null otherwise
+ *   - completedPhases / totalPhases / percent : milestone progress dimension
+ *
+ * All new fields default to undefined when absent — formatSddState() degrades
+ * gracefully so existing STATE.md files (without these fields) keep working.
  */
 function parseStateMd(content) {
   const state = {};
 
-  // YAML frontmatter between --- markers
+  // YAML frontmatter between --- markers (anchored at file start)
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (fmMatch) {
-    for (const line of fmMatch[1].split('\n')) {
+    const fm = fmMatch[1];
+    // Top-level scalar key: value
+    for (const line of fm.split('\n')) {
       const m = line.match(/^(\w+):\s*(.+)/);
       if (!m) continue;
       const [, key, val] = m;
       const v = val.trim().replace(/^["']|["']$/g, '');
+      // status / milestone-level fields (existing — preserved exactly)
       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-lifecycle fields (new in issue #2833)
+      // active_phase: phase number when an orchestrator is in-flight, null when idle
+      if (key === 'active_phase') state.activePhase = (v === 'null' || v === '') ? null : v;
+      // next_action: recommended command when idle (discuss-phase / plan-phase / execute-phase / verify-phase)
+      if (key === 'next_action') state.nextAction = (v === 'null' || v === '') ? null : v;
+    }
+    // next_phases supports both flow array and block-list YAML forms.
+    const npFlowMatch = fm.match(/^next_phases:\s*\[([^\]]*)\]/m);
+    if (npFlowMatch) {
+      const items = npFlowMatch[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+      state.nextPhases = items.length > 0 ? items : null;
+    } else {
+      const npBlockMatch = fm.match(/^next_phases:\s*\n((?:[ \t]*-[ \t]*[^\n]+\n?)*)/m);
+      if (npBlockMatch) {
+        const items = npBlockMatch[1]
+          .split('\n')
+          .map(line => line.match(/^[ \t]*-[ \t]*(.+)$/))
+          .filter(Boolean)
+          .map(m => m[1].trim().replace(/^["']|["']$/g, ''))
+          .filter(Boolean);
+        state.nextPhases = items.length > 0 ? items : null;
+      }
+    }
+    // progress nested block: completed_phases / total_phases / percent (2-space indent)
+    const progMatch = fm.match(/^progress:\s*\n((?:[ \t]+\w+:.+\n?)+)/m);
+    if (progMatch) {
+      const cp = progMatch[1].match(/^[ \t]+completed_phases:\s*(\d+)/m);
+      const tp = progMatch[1].match(/^[ \t]+total_phases:\s*(\d+)/m);
+      const pc = progMatch[1].match(/^[ \t]+percent:\s*(\d+)/m);
+      if (cp) state.completedPhases = cp[1];
+      if (tp) state.totalPhases = tp[1];
+      if (pc) state.percent = pc[1];
     }
   }
 
@@ -75,31 +208,77 @@ function parseStateMd(content) {
   return state;
 }
 
+/**
+ * Render a 10-segment milestone progress bar (matches the context meter style).
+ *
+ * @param {number|string|null|undefined} percent — 0-100; missing/NaN returns ''
+ * @returns {string} '[█████░░░░░] 50%' or '' (so callers can `[bar].filter(Boolean)`)
+ */
+function renderProgressBar(percent) {
+  if (percent == null || isNaN(percent)) return '';
+  const pct = Math.max(0, Math.min(100, parseInt(percent, 10)));
+  const filled = Math.floor(pct / 10);
+  const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+  return `[${bar}] ${pct}%`;
+}
+
 /**
  * Format SDD state into display string.
- * Format: "v1.9 Code Quality · executing · fix-graphiti-deployment (1/5)"
- * Gracefully degrades when parts are missing.
+ *
+ * Backward-compatible default (no new fields populated):
+ *   "v1.9 Code Quality · executing · fix-graphiti-deployment (1/5)"
+ *
+ * Phase-lifecycle scenes (issue #2833 — activate when STATE.md frontmatter
+ * carries the new fields; otherwise rendering falls through to the default):
+ *
+ *   active_phase set                       → "v2.0 [██░] X% · Phase 4.5 executing"
+ *   active_phase null + next_action set    → "v2.0 [██░] X% · next execute-phase 4.5"
+ *   percent=100 (milestone done)           → "v2.0 [██████████] 100% · milestone complete"
+ *   none of the above                      → existing "<status> · <phase>" path
+ *
+ * Progress bar is opt-in: appended to the milestone segment only when
+ * progress.percent is present in frontmatter; absent → empty string.
  */
 function formatSddState(s) {
   const parts = [];
 
-  // Milestone: version + name (skip placeholder "milestone")
+  // Milestone segment: version + name + (opt-in) progress bar
   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);
+    const bar = renderProgressBar(s.percent);
+    const pieces = [ver, name, bar].filter(Boolean);
+    if (pieces.length > 0) parts.push(pieces.join(' '));
   }
 
-  // Status
-  if (s.status) parts.push(s.status);
+  // Phase-lifecycle scenes (issue #2833) — first match wins; falls through to
+  // the original "<status> · <phase>" path when none of the new fields apply.
+  const phasesStr = (s.nextPhases && s.nextPhases.length > 0) ? s.nextPhases.join('/') : null;
 
-  // Phase
-  if (s.phaseNum && s.phaseTotal) {
-    const phase = s.phaseName
-      ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
-      : `ph ${s.phaseNum}/${s.phaseTotal}`;
-    parts.push(phase);
+  if (s.activePhase) {
+    // Scene 1: an orchestrator is mid-flight on this phase.
+    // stage = whichever lifecycle status was written by the orchestrator
+    //   (discussing / planning / executing / verifying)
+    const stage = s.status || '';
+    parts.push(stage ? `Phase ${s.activePhase} ${stage}` : `Phase ${s.activePhase}`);
+  } else if (s.nextAction && phasesStr) {
+    // Scene 2: idle + a recommended next command is visible to the user.
+    // Surfaces "what to run next" without the user opening STATE.md.
+    parts.push(`next ${s.nextAction} ${phasesStr}`);
+  } else if (Number(s.percent) === 100 || (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases)) {
+    // Scene 3: milestone complete (every phase done).
+    parts.push('milestone complete');
+  } else {
+    // Backward-compatible default — preserved EXACTLY for STATE.md files that
+    // don't carry the new lifecycle fields. Identical output to v1.38.x and
+    // earlier so no existing project's status-line changes shape.
+    if (s.status) parts.push(s.status);
+    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(' · ');
@@ -124,9 +303,15 @@ function runStatusline() {
     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;
+    // Claude Code reserves a buffer for autocompact. By default this is ~16.5%
+    // of the total window, but users can override it via CLAUDE_CODE_AUTO_COMPACT_WINDOW
+    // (a token count). When the env var is set, compute the buffer % dynamically so
+    // the meter correctly reflects early-compaction configurations (#2219).
+    const totalCtx = data.context_window?.total_tokens || 1_000_000;
+    const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
+    const AUTO_COMPACT_BUFFER_PCT = acw > 0
+      ? Math.min(100, (acw / totalCtx) * 100)
+      : 16.5;
     let ctx = '';
     if (remaining != null) {
       // Normalize: subtract buffer from remaining, scale to usable range
@@ -141,10 +326,15 @@ function runStatusline() {
       if (sessionSafe) {
         try {
           const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
+          // used_pct written to the bridge must match CC's native /context reporting:
+          // raw used = 100 - remaining_percentage (no buffer normalization applied).
+          // The normalized `used` value is correct for the statusline progress bar but
+          // inflates the context monitor warning messages by ~13 points (#2451).
+          const rawUsedPct = Math.round(100 - remaining);
           const bridgeData = JSON.stringify({
             session_id: session,
             remaining_percentage: remaining,
-            used_pct: used,
+            used_pct: rawUsedPct,
             timestamp: Math.floor(Date.now() / 1000)
           });
           fs.writeFileSync(bridgePath, bridgeData);
@@ -208,14 +398,47 @@ function runStatusline() {
       try {
         const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
         if (cache.update_available) {
-          sddUpdate = '\x1b[33m⬆ /sdd-update\x1b[0m │ ';
+          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 │ ';
+          // If installed version is ahead of npm latest, this is a dev install.
+          // Running /sdd:update would downgrade — show a contextual warning instead.
+          const isDevInstall = (() => {
+            if (!cache.installed || !cache.latest || cache.latest === 'unknown') return false;
+            const parseV = v => v.replace(/^v/, '').split('.').map(Number);
+            const [ai, bi, ci] = parseV(cache.installed);
+            const [an, bn, cn] = parseV(cache.latest);
+            return ai > an || (ai === an && bi > bn) || (ai === an && bi === bn && ci > cn);
+          })();
+          if (isDevInstall) {
+            sddUpdate += '\x1b[33m⚠ dev install — re-run installer to sync hooks\x1b[0m │ ';
+          } else {
+            sddUpdate += '\x1b[31m⚠ stale hooks — run /sdd:update\x1b[0m │ ';
+          }
         }
       } catch (e) {}
     }
 
+    // Last-slash-command suffix and context_position config (#2538, #2937).
+    // Reads the active session transcript for the most recent <command-name> tag.
+    // Failure here must never break the statusline — wrap the entire lookup.
+    let lastCmdSuffix = '';
+    let position = 'end';
+    try {
+      const cfg = readSddConfig(dir);
+      if (getConfigValue(cfg, 'statusline.show_last_command') === true) {
+        const transcriptPath = data.transcript_path;
+        const lastCmd = readLastSlashCommand(transcriptPath);
+        if (lastCmd) {
+          lastCmdSuffix = ` │ \x1b[2mlast: /${lastCmd}\x1b[0m`;
+        }
+      }
+      const cfgPos = getConfigValue(cfg, 'statusline.context_position');
+      if (cfgPos != null) position = cfgPos;
+    } catch (e) {
+      // Never break the statusline on config/transcript errors
+    }
+
     // Output
     const dirname = path.basename(dir);
     const middle = task
@@ -224,18 +447,91 @@ function runStatusline() {
         ? `\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}`);
-    }
+    process.stdout.write(composeStatusline({ sddUpdate, model, ctx, middle, dirname, lastCmdSuffix, position }));
   } catch (e) {
     // Silent fail - don't break statusline on parse errors
   }
 });
 }
 
+// --- Layout composer --------------------------------------------------------
+
+/**
+ * Compose the statusline string from pre-built segments.
+ *
+ * @param {object} opts
+ * @param {string} [opts.sddUpdate='']      - leading update/stale-hooks warning (already formatted)
+ * @param {string} opts.model               - model display name (plain text; dim styling applied here)
+ * @param {string} [opts.ctx='']            - context-window meter segment (empty string = absent)
+ * @param {string|null} [opts.middle=null]  - middle segment (todo task or SDD state), null = absent
+ * @param {string} opts.dirname             - project directory basename (dim styling applied here)
+ * @param {string} [opts.lastCmdSuffix='']  - last-command suffix, e.g. ' │ last: /foo'
+ * @param {'end'|'front'} [opts.position='end']
+ *   - 'end'   (default): ctx appended after dirname — preserved byte-for-byte
+ *   - 'front': ctx immediately after model name so the meter stays visible in narrow terminals
+ *
+ * Invalid position values are silently coerced to 'end' — config-set schema rejects
+ * invalid values upfront; runtime fallback defends against stale/corrupt configs
+ * without breaking the statusline.
+ */
+function composeStatusline({
+  sddUpdate = '',
+  model,
+  ctx = '',
+  middle = null,
+  dirname,
+  lastCmdSuffix = '',
+  position = 'end',
+} = {}) {
+  const modelSeg = `\x1b[2m${model}\x1b[0m`;
+  const dirSeg = `\x1b[2m${dirname}\x1b[0m`;
+  // Coerce invalid values to 'end' (belt-and-suspenders; see JSDoc above)
+  const pos = position === 'front' ? 'front' : 'end';
+
+  if (pos === 'front') {
+    if (middle) return `${sddUpdate}${modelSeg}${ctx} │ ${middle} │ ${dirSeg}${lastCmdSuffix}`;
+    return `${sddUpdate}${modelSeg}${ctx} │ ${dirSeg}${lastCmdSuffix}`;
+  }
+  // 'end' — preserved byte-for-byte relative to original inline templates
+  if (middle) return `${sddUpdate}${modelSeg} │ ${middle} │ ${dirSeg}${ctx}${lastCmdSuffix}`;
+  return `${sddUpdate}${modelSeg} │ ${dirSeg}${ctx}${lastCmdSuffix}`;
+}
+
 // Export helpers for unit tests. Harmless when run as a script.
-module.exports = { readSddState, parseStateMd, formatSddState };
+module.exports = {
+  readSddState, parseStateMd, formatSddState,
+  readSddConfig, getConfigValue, readLastSlashCommand,
+  composeStatusline,
+};
+
+/**
+ * Render the statusline from an already-parsed hook input object. Exported for
+ * testing without feeding stdin. Returns the rendered string.
+ */
+function renderStatusline(data) {
+  const model = data.model?.display_name || 'Claude';
+  const dir = data.workspace?.current_dir || process.cwd();
+  const dirname = path.basename(dir);
+
+  let lastCmdSuffix = '';
+  let position = 'end';
+  try {
+    const cfg = readSddConfig(dir);
+    if (getConfigValue(cfg, 'statusline.show_last_command') === true) {
+      const lastCmd = readLastSlashCommand(data.transcript_path);
+      if (lastCmd) {
+        lastCmdSuffix = ` │ \x1b[2mlast: /${lastCmd}\x1b[0m`;
+      }
+    }
+    const cfgPos = getConfigValue(cfg, 'statusline.context_position');
+    if (cfgPos != null) position = cfgPos;
+  } catch (e) { /* swallow */ }
+
+  const sddStateStr = formatSddState(readSddState(dir) || {});
+  const middle = sddStateStr ? `\x1b[2m${sddStateStr}\x1b[0m` : null;
+  return composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, position });
+}
+
+module.exports.renderStatusline = renderStatusline;
 
 if (require.main === module) runStatusline();

package/hooks/dist/sdd-update-banner.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// sdd-hook-version: {{SDD_VERSION}}
+// SessionStart banner that surfaces SDD update availability when SDD's
+// statusline isn't installed. Reads the cache that
+// sdd-check-update-worker.js writes to ~/.cache/sdd/sdd-update-check.json.
+//
+// Opt-in by design: bin/install.js only registers this hook when the user
+// declines to install (or replace) the SDD statusline. The presence of the
+// SessionStart entry IS the opt-in — there is no separate runtime flag.
+//
+// See issue #2795 for the rationale.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Suppress repeat parse-error banners for 24 hours so a genuinely broken
+// cache file doesn't nag the user every session.
+const RATE_LIMIT_SECONDS = 24 * 60 * 60;
+
+/**
+ * Build the SessionStart JSON envelope to emit, given parsed cache state.
+ * Pure function — no I/O. Returns null when the hook should print nothing.
+ *
+ * @param {object} state
+ * @param {object|null} state.cache                  Parsed cache, or null if missing/unreadable.
+ * @param {boolean}     state.parseError             True iff cache file existed but JSON.parse failed.
+ * @param {boolean}     state.suppressFailureWarning True when a recent failure warning already fired.
+ * @returns {{systemMessage: string}|null}           JSON envelope, or null for silent exit.
+ */
+function buildBannerOutput(state) {
+  const { cache, parseError, suppressFailureWarning } = state || {};
+  if (parseError) {
+    if (suppressFailureWarning) return null;
+    return { systemMessage: 'SDD update check failed.' };
+  }
+  if (!cache) return null;
+  if (!cache.update_available) return null;
+  const installed = cache.installed || 'unknown';
+  const latest = cache.latest || 'unknown';
+  return {
+    systemMessage: `SDD update available: ${installed} → ${latest}. Run /sdd:update.`,
+  };
+}
+
+/**
+ * Read and parse the update-check cache file.
+ *
+ * @param {string} cacheFile
+ * @returns {{cache: object|null, parseError: boolean}}
+ */
+function readCache(cacheFile) {
+  let cache = null;
+  let parseError = false;
+  try {
+    if (fs.existsSync(cacheFile)) {
+      const raw = fs.readFileSync(cacheFile, 'utf8');
+      cache = JSON.parse(raw);
+    }
+  } catch (e) {
+    // Distinguish "file unreadable" from "JSON malformed": both fail-open to
+    // null cache, but a JSON parse error becomes a one-time diagnostic.
+    parseError = e instanceof SyntaxError;
+  }
+  return { cache, parseError };
+}
+
+/**
+ * Has a failure warning been emitted within the rate-limit window?
+ *
+ * @param {string} sentinelFile
+ * @param {number} nowSeconds
+ * @returns {boolean}
+ */
+function shouldSuppressFailureWarning(sentinelFile, nowSeconds) {
+  try {
+    if (!fs.existsSync(sentinelFile)) return false;
+    const last = parseInt(fs.readFileSync(sentinelFile, 'utf8').trim(), 10);
+    if (!Number.isFinite(last)) return false;
+    return nowSeconds - last < RATE_LIMIT_SECONDS;
+  } catch (e) {
+    return false;
+  }
+}
+
+function recordFailureWarning(sentinelFile, nowSeconds) {
+  try {
+    fs.writeFileSync(sentinelFile, String(nowSeconds));
+  } catch (e) {
+    // Best-effort: a non-writable cache dir means we'll re-warn next session,
+    // which is no worse than the un-instrumented baseline.
+  }
+}
+
+function main() {
+  const cacheDir = path.join(os.homedir(), '.cache', 'sdd');
+  const cacheFile = path.join(cacheDir, 'sdd-update-check.json');
+  const sentinelFile = path.join(cacheDir, 'banner-failure-warned-at');
+  const now = Math.floor(Date.now() / 1000);
+
+  const { cache, parseError } = readCache(cacheFile);
+  const suppressFailureWarning = parseError
+    ? shouldSuppressFailureWarning(sentinelFile, now)
+    : false;
+  const output = buildBannerOutput({ cache, parseError, suppressFailureWarning });
+
+  if (parseError && !suppressFailureWarning) {
+    // Ensure cache dir exists before writing the sentinel — first-run case
+    // where ~/.cache/sdd was created by check-update but the parent dir got
+    // wiped between runs.
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+    } catch (e) {
+      // Best-effort: failure to create the dir means we'll re-warn next
+      // session, which is no worse than the un-instrumented baseline.
+    }
+    recordFailureWarning(sentinelFile, now);
+  }
+
+  if (output) {
+    process.stdout.write(JSON.stringify(output));
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  buildBannerOutput,
+  readCache,
+  shouldSuppressFailureWarning,
+  RATE_LIMIT_SECONDS,
+};

package/hooks/dist/sdd-validate-commit.sh

@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# sdd-hook-version: {{SDD_VERSION}}
 # 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).
@@ -20,8 +21,15 @@ 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
+# Only check git commit commands.
+# Delegates to hooks/lib/git-cmd.js isGitSubcommand() — the canonical token-walk
+# classifier that handles env-prefix, -C path, and full-path git invocations.
+# A naive `^git\s+commit` regex misses all three; this guard fixes that (#3129).
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+if GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
+  const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
+  process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
+" "$CMD" 2>/dev/null; then
   # Extract message from -m flag
   MSG=""
   if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
@@ -34,11 +42,13 @@ if [[ "$CMD" =~ ^git[[:space:]]+commit ]]; 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."}'
+      # Emit a typed `code` field alongside `reason` (#2974). Tests assert
+      # on the stable code string; the reason is the human-readable copy.
+      echo '{"decision": "block", "code": "CONVENTIONAL_COMMITS_VIOLATION", "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."}'
+      echo '{"decision": "block", "code": "COMMIT_SUBJECT_TOO_LONG", "reason": "Commit subject must be 72 characters or less."}'
       exit 2
     fi
   fi

package/hooks/dist/sdd-workflow-guard.js

@@ -5,7 +5,7 @@
 // (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
+// 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)
@@ -80,7 +80,7 @@ process.stdin.on('end', () => {
         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 ' +
+          '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.'
       }