@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/bin/lib/roadmap.cjs

@@ -4,7 +4,56 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, planningPaths, withPlanningLock, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, phaseTokenMatches, atomicWriteFileSync } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, output, error, findPhaseInternal, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, phaseTokenMatches } = require('./core.cjs');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
+const { planningPaths, withPlanningLock } = require('./planning-workspace.cjs');
+const scanPhasePlans = require('./plan-scan.cjs');
+
+/**
+ * Coerce an arbitrary YAML scalar/object into a string for cross-cutting
+ * truth aggregation. Handles:
+ *   - strings (passthrough)
+ *   - numbers / booleans (String() coercion — issue #2770: bare YAML ints
+ *     like `- 3` must be surfaced, not silently skipped)
+ *   - kv-shaped objects from parseMustHavesBlock continuation kv (issue
+ *     #2757) — extract the first meaningful string field
+ *
+ * Returns the empty string when no usable text can be derived; callers should
+ * skip empty results.
+ */
+function coerceTruthToString(t) {
+  if (t === null || t === undefined) return '';
+  if (typeof t === 'string') return t;
+  if (typeof t === 'number' || typeof t === 'boolean' || typeof t === 'bigint') {
+    return String(t);
+  }
+  if (typeof t === 'object') {
+    // Prefer common title-bearing keys produced by parseMustHavesBlock
+    for (const k of ['title', 'text', 'name', 'rule', 'path', 'provides']) {
+      const v = t[k];
+      if (typeof v === 'string' && v.trim()) return v;
+      if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    }
+  }
+  return '';
+}
+
+function countPhasePlansAndSummaries(phaseDir) {
+  const { planCount, summaryCount } = scanPhasePlans(phaseDir);
+  // hasContext and hasResearch are not plan-scan concerns — read the directory
+  // once for the non-plan metadata that cmdRoadmapAnalyze needs.
+  let phaseFiles = [];
+  try { phaseFiles = fs.readdirSync(phaseDir); } catch { /* empty */ }
+  return {
+    planCount,
+    summaryCount,
+    hasContext: phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'),
+    hasResearch: phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+  };
+}
+
+// `phaseMarkdownRegexSource` moved to core.cjs (#3537) so phase.cjs and
+// core.cjs itself can consume it without circular deps. Imported above.
 
 /**
  * Search for a phase header (and its section) within the given content string.
@@ -45,7 +94,7 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
 
   // Find the end of this section (next ## or ### phase header, or end of file)
   const restOfContent = content.slice(headerIndex);
-  const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+\d/i);
+  const nextHeaderMatch = restOfContent.match(/\n#{2,4}\s+Phase\s+[\w][\w.-]*/i);
   const sectionEnd = nextHeaderMatch
     ? headerIndex + nextHeaderMatch.index
     : content.length;
@@ -56,6 +105,11 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
   const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
   const goal = goalMatch ? goalMatch[1].trim() : null;
 
+  // Mode: vertical-MVP slice mode flag. Lowercased + trimmed for canonical
+  // comparison; unrecognized values are preserved verbatim for forward-compat.
+  const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
+  const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
+
   // Extract success criteria as structured array
   const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
   const success_criteria = criteriaMatch
@@ -67,6 +121,7 @@ function searchPhaseInContent(content, escapedPhase, phaseNum) {
     phase_number: phaseNum,
     phase_name: phaseName,
     goal,
+    mode,
     success_criteria,
     section,
   };
@@ -84,13 +139,36 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
     const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
     const milestoneContent = extractCurrentMilestone(rawContent, cwd);
 
-    // Escape special regex chars in phase number, handle decimal
-    const escapedPhase = escapeRegex(phaseNum);
+    // #3599 two-pass: when the caller passes a project-code-prefixed ID like
+    // `PROJ-42`, try the exact-prefixed heading first (`### Phase PROJ-42:`).
+    // If no match, fall back to the #3537 padding-tolerant numeric form so
+    // a `CK-01` query still resolves to `### Phase 1:`. Doing this at the
+    // call site (instead of inside phaseMarkdownRegexSource) avoids the
+    // alternation-order ambiguity where a bare `### Phase 42:` heading in
+    // the same document would intercept the match for a `PROJ-42` query.
+    const fullContent = stripShippedMilestones(rawContent);
+
+    const exactSource = phaseMarkdownRegexSourceExact(phaseNum);
+    if (exactSource) {
+      const exactMilestone = searchPhaseInContent(milestoneContent, exactSource, phaseNum);
+      if (exactMilestone && !exactMilestone.error) {
+        output(exactMilestone, raw, exactMilestone.section);
+        return;
+      }
+      const exactFull = searchPhaseInContent(fullContent, exactSource, phaseNum);
+      if (exactFull && !exactFull.error) {
+        output(exactFull, raw, exactFull.section);
+        return;
+      }
+    }
+
+    // #3537: padding-tolerant fragment so callers passing `02.7` still match
+    // un-padded ROADMAP prose (`### Phase 2.7:`).
+    const escapedPhase = phaseMarkdownRegexSource(phaseNum);
 
     // Search the current milestone slice first, then fall back to full roadmap.
     // A malformed_roadmap result (checklist-only) from the milestone should not
     // block finding a full header match in the wider roadmap content.
-    const fullContent = stripShippedMilestones(rawContent);
     const milestoneResult = searchPhaseInContent(milestoneContent, escapedPhase, phaseNum);
     const result = (milestoneResult && !milestoneResult.error)
       ? milestoneResult
@@ -152,6 +230,9 @@ function cmdRoadmapAnalyze(cwd, raw) {
     const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
 
+    const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    const mode = modeMatch ? modeMatch[1].trim().toLowerCase() : null;
+
     const dependsMatch = section.match(/\*\*Depends on(?::\*\*|\*\*:)\s*([^\n]+)/i);
     const depends_on = dependsMatch ? dependsMatch[1].trim() : null;
 
@@ -167,11 +248,11 @@ function cmdRoadmapAnalyze(cwd, raw) {
       const dirMatch = _phaseDirNames.find(d => phaseTokenMatches(d, normalized));
 
       if (dirMatch) {
-        const phaseFiles = fs.readdirSync(path.join(phasesDir, dirMatch));
-        planCount = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
-        summaryCount = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
-        hasContext = phaseFiles.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md');
-        hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md');
+        const counts = countPhasePlansAndSummaries(path.join(phasesDir, dirMatch));
+        planCount = counts.planCount;
+        summaryCount = counts.summaryCount;
+        hasContext = counts.hasContext;
+        hasResearch = counts.hasResearch;
 
         if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete';
         else if (summaryCount > 0) diskStatus = 'partial';
@@ -182,8 +263,11 @@ function cmdRoadmapAnalyze(cwd, raw) {
       }
     } catch { /* intentionally empty */ }
 
-    // Check ROADMAP checkbox status
-    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${escapeRegex(phaseNum)}[:\\s]`, 'i');
+    // Check ROADMAP checkbox status.
+    // #3537: padding-tolerant fragment — the heading discovered above may use
+    // a different padding than the summary-bullet checkbox below it (mixed
+    // padding inside one ROADMAP is legal and seen in real projects).
+    const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}[:\\s]`, 'i');
     const checkboxMatch = content.match(checkboxPattern);
     const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
 
@@ -198,6 +282,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
       number: phaseNum,
       name: phaseName,
       goal,
+      mode,
       depends_on,
       plan_count: planCount,
       summary_count: summaryCount,
@@ -286,11 +371,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   // Wrap entire read-modify-write in lock to prevent concurrent corruption
   withPlanningLock(cwd, () => {
     let roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
-    const phaseEscaped = escapeRegex(phaseNum);
+    const phasePattern = phaseMarkdownRegexSource(phaseNum);
 
     // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
     const tableRowPattern = new RegExp(
-      `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
+      `^(\\|\\s*${phasePattern}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
       'im'
     );
     const dateField = isComplete ? ` ${today} ` : '  ';
@@ -312,7 +397,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
 
     // Update plan count in phase detail section
     const planCountPattern = new RegExp(
-      `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
+      `(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
       'i'
     );
     const planCountText = isComplete
@@ -323,7 +408,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     // If complete: check checkbox
     if (isComplete) {
       const checkboxPattern = new RegExp(
-        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
+        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}[:\\s][^\\n]*)`,
         'i'
       );
       roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
@@ -341,7 +426,7 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
       roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
     }
 
-    atomicWriteFileSync(roadmapPath, roadmapContent, 'utf-8');
+    platformWriteSync(roadmapPath, roadmapContent);
   });
   output({
     updated: true,
@@ -353,8 +438,184 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   }, raw, `${summaryCount}/${planCount} ${status}`);
 }
 
+/**
+ * Annotate the ROADMAP.md plan list for a phase with wave dependency notes
+ * and a cross-cutting constraints subsection derived from PLAN frontmatter.
+ *
+ * Wave dependency notes: "Wave 2 — blocked on Wave 1 completion" inserted as
+ * bold headers before each wave group in the plan checklist.
+ *
+ * Cross-cutting constraints: must_haves.truths strings that appear in 2+ plans
+ * are surfaced in a "Cross-cutting constraints" subsection below the plan list.
+ *
+ * The operation is idempotent: if wave headers already exist in the section
+ * the function returns without modifying the file.
+ */
+function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
+  if (!phaseNum) {
+    error('phase number required for roadmap annotate-dependencies');
+  }
+
+  const roadmapPath = planningPaths(cwd).roadmap;
+  if (!fs.existsSync(roadmapPath)) {
+    output({ updated: false, reason: 'ROADMAP.md not found' }, raw, 'no roadmap');
+    return;
+  }
+
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo || phaseInfo.plans.length === 0) {
+    output({ updated: false, reason: 'no plans found for phase', phase: phaseNum }, raw, 'no plans');
+    return;
+  }
+
+  const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
+
+  // Read each PLAN.md and extract wave + must_haves.truths
+  const planData = [];
+  for (const planFile of phaseInfo.plans) {
+    const planPath = path.join(path.resolve(cwd, phaseInfo.directory), planFile);
+    try {
+      const content = fs.readFileSync(planPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      const wave = parseInt(fm.wave, 10) || 1;
+      const planId = planFile.replace(/-PLAN\.md$/i, '').replace(/PLAN\.md$/i, '');
+      const truths = parseMustHavesBlock(content, 'truths') || [];
+      planData.push({ planFile, planId, wave, truths });
+    } catch { /* skip unreadable plans */ }
+  }
+
+  if (planData.length === 0) {
+    output({ updated: false, reason: 'could not read plan frontmatter' }, raw, 'no frontmatter');
+    return;
+  }
+
+  // Group plans by wave (sorted)
+  const waveGroups = new Map();
+  for (const p of planData) {
+    if (!waveGroups.has(p.wave)) waveGroups.set(p.wave, []);
+    waveGroups.get(p.wave).push(p);
+  }
+  const waves = [...waveGroups.keys()].sort((a, b) => a - b);
+
+  // Find cross-cutting truths: appear in 2+ plans (de-duplicated, case-insensitive).
+  //
+  // Issue #2770: must **coerce, not skip**. A previous guard
+  // `if (typeof t !== 'string') continue` silently dropped numeric scalars
+  // (YAML ints like `- 3`) and kv-shaped truths (`- title: X`), so the
+  // cross-cutting analysis lost real constraints rather than crashing on
+  // `t.trim()`. We coerce primitives via `String(t)` and extract a sensible
+  // string field from object-shaped items produced by parseMustHavesBlock's
+  // continuation-kv path (issue #2757 produces those shapes for nested keys).
+  const truthCounts = new Map();
+  for (const { truths } of planData) {
+    const seen = new Set();
+    for (const t of truths) {
+      const text = coerceTruthToString(t);
+      if (!text) continue;
+      const trimmed = text.trim();
+      const key = trimmed.toLowerCase();
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      if (!truthCounts.has(key)) truthCounts.set(key, { count: 0, text: trimmed });
+      truthCounts.get(key).count++;
+    }
+  }
+  const crossCuttingTruths = [...truthCounts.values()]
+    .filter(v => v.count >= 2)
+    .map(v => v.text);
+
+  // Patch ROADMAP.md
+  let updated = false;
+  withPlanningLock(cwd, () => {
+    let content = fs.readFileSync(roadmapPath, 'utf-8');
+
+    // Find the phase section.
+    // #3537: padding-tolerant fragment so the caller's resolved padded id
+    // matches un-padded ROADMAP headings.
+    const phaseEscaped = phaseMarkdownRegexSource(phaseNum);
+    const phaseHeaderPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}:[^\\n]*)`, 'i');
+    const phaseMatch = content.match(phaseHeaderPattern);
+    if (!phaseMatch) return;
+
+    const phaseStart = phaseMatch.index;
+    const restAfterHeader = content.slice(phaseStart);
+    const nextPhaseOffset = restAfterHeader.slice(1).search(/\n#{2,4}\s+Phase\s+\d/i);
+    const phaseEnd = nextPhaseOffset >= 0 ? phaseStart + 1 + nextPhaseOffset : content.length;
+    const phaseSection = content.slice(phaseStart, phaseEnd);
+
+    // Idempotency: skip if annotation markers already present
+    if (
+      /\*\*Wave\s+\d+/i.test(phaseSection) ||
+      /\*\*Cross-cutting constraints:\*\*/i.test(phaseSection)
+    ) return;
+
+    // Find the Plans: section within the phase section
+    const plansBlockMatch = phaseSection.match(/(Plans:\s*\n)((?:\s*-\s*\[[ x]\][^\n]*\n?)*)/i);
+    if (!plansBlockMatch) return;
+
+    const plansHeader = plansBlockMatch[1];
+    const existingList = plansBlockMatch[2];
+    const listLines = existingList.split('\n').filter(l => /^\s*-\s*\[/.test(l));
+
+    if (listLines.length === 0) return;
+
+    // Build wave-annotated plan list
+    const linesByWave = new Map();
+    for (const line of listLines) {
+      // Match plan ID from line: "- [ ] 01-01-PLAN.md — ..." or "- [ ] 01-01: ..."
+      const idMatch = line.match(/\[\s*[x ]\s*\]\s*([\w-]+?)(?:-PLAN\.md|\.md|:|\s—)/i);
+      const planId = idMatch ? idMatch[1] : null;
+      const planEntry = planId ? planData.find(p => p.planId === planId) : null;
+      const wave = planEntry ? planEntry.wave : 1;
+      if (!linesByWave.has(wave)) linesByWave.set(wave, []);
+      linesByWave.get(wave).push(line);
+    }
+
+    const annotatedLines = [];
+    const sortedWaves = [...linesByWave.keys()].sort((a, b) => a - b);
+    for (let i = 0; i < sortedWaves.length; i++) {
+      const w = sortedWaves[i];
+      const waveLines = linesByWave.get(w);
+      if (sortedWaves.length > 1) {
+        const dep = i > 0 ? ` *(blocked on Wave ${sortedWaves[i - 1]} completion)*` : '';
+        annotatedLines.push(`**Wave ${w}**${dep}`);
+      }
+      annotatedLines.push(...waveLines);
+      if (i < sortedWaves.length - 1) annotatedLines.push('');
+    }
+
+    // Append cross-cutting constraints subsection if any found
+    if (crossCuttingTruths.length > 0) {
+      annotatedLines.push('');
+      annotatedLines.push('**Cross-cutting constraints:**');
+      for (const t of crossCuttingTruths) {
+        annotatedLines.push(`- ${t}`);
+      }
+    }
+
+    const newListBlock = annotatedLines.join('\n') + '\n';
+    const newPhaseSection = phaseSection.replace(
+      plansBlockMatch[0],
+      plansHeader + newListBlock
+    );
+
+    const nextContent = content.slice(0, phaseStart) + newPhaseSection + content.slice(phaseEnd);
+    if (nextContent === content) return;
+    platformWriteSync(roadmapPath, nextContent);
+    updated = true;
+  });
+
+  output({
+    updated,
+    phase: phaseNum,
+    waves: waves.length,
+    cross_cutting_constraints: crossCuttingTruths.length,
+  }, raw, updated ? `annotated ${waves.length} wave(s), ${crossCuttingTruths.length} constraint(s)` : 'skipped (already annotated or no plan list)');
+}
+
 module.exports = {
   cmdRoadmapGetPhase,
   cmdRoadmapAnalyze,
   cmdRoadmapUpdatePlanProgress,
+  cmdRoadmapAnnotateDependencies,
 };

package/sdd/bin/lib/runtime-homes.cjs

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * runtime-homes.cjs — canonical runtime → global config/skills directory mapping.
+ *
+ * Single source of truth for resolving the global config base directory and
+ * the correct global skills directory for every SDD-supported runtime.
+ *
+ * Mirrors the logic in bin/install.js getGlobalDir() but as a pure,
+ * side-effect-free module safe to require() at any point without triggering
+ * the installer. bin/install.js is the authoritative source — keep in sync.
+ *
+ * Runtime-specific notes:
+ *   hermes  — SDD skills nest under skills/sdd/<skillName>/ (not the flat
+ *             skills/<skillName>/ layout used by all other runtimes). This
+ *             collapses 86 skill entries into one category in Hermes' system
+ *             prompt (#2841).
+ *   cline   — Rules-based; commands are embedded in .clinerules. Cline does
+ *             not use a skills/ directory. getGlobalSkillDir() returns null
+ *             for cline so the caller can emit an appropriate warning.
+ */
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Expand a leading ~ to os.homedir().
+ * @param {string} p
+ * @returns {string}
+ */
+function expandTilde(p) {
+  if (!p) return p;
+  if (p.startsWith('~/') || p === '~') return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+/**
+ * Return the global config base directory for the given runtime.
+ * Respects the same env-var overrides as bin/install.js getGlobalDir().
+ *
+ * @param {string} runtime
+ * @returns {string} Absolute path to the runtime's global config directory
+ */
+function getGlobalConfigDir(runtime) {
+  const home = os.homedir();
+  const env = process.env;
+
+  switch (runtime) {
+    // ── Claude Code ──────────────────────────────────────────────────────────
+    case 'claude':
+      return env.CLAUDE_CONFIG_DIR ? expandTilde(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+
+    // ── Cursor ───────────────────────────────────────────────────────────────
+    case 'cursor':
+      return env.CURSOR_CONFIG_DIR ? expandTilde(env.CURSOR_CONFIG_DIR) : path.join(home, '.cursor');
+
+    // ── Gemini CLI ───────────────────────────────────────────────────────────
+    case 'gemini':
+      return env.GEMINI_CONFIG_DIR ? expandTilde(env.GEMINI_CONFIG_DIR) : path.join(home, '.gemini');
+
+    // ── Codex ────────────────────────────────────────────────────────────────
+    case 'codex':
+      return env.CODEX_HOME ? expandTilde(env.CODEX_HOME) : path.join(home, '.codex');
+
+    // ── Copilot (VS Code) ────────────────────────────────────────────────────
+    case 'copilot':
+      return env.COPILOT_CONFIG_DIR ? expandTilde(env.COPILOT_CONFIG_DIR) : path.join(home, '.copilot');
+
+    // ── Antigravity ──────────────────────────────────────────────────────────
+    case 'antigravity':
+      return env.ANTIGRAVITY_CONFIG_DIR
+        ? expandTilde(env.ANTIGRAVITY_CONFIG_DIR)
+        : path.join(home, '.gemini', 'antigravity');
+
+    // ── Windsurf ─────────────────────────────────────────────────────────────
+    case 'windsurf':
+      return env.WINDSURF_CONFIG_DIR
+        ? expandTilde(env.WINDSURF_CONFIG_DIR)
+        : path.join(home, '.codeium', 'windsurf');
+
+    // ── Augment ──────────────────────────────────────────────────────────────
+    case 'augment':
+      return env.AUGMENT_CONFIG_DIR ? expandTilde(env.AUGMENT_CONFIG_DIR) : path.join(home, '.augment');
+
+    // ── Trae ─────────────────────────────────────────────────────────────────
+    case 'trae':
+      return env.TRAE_CONFIG_DIR ? expandTilde(env.TRAE_CONFIG_DIR) : path.join(home, '.trae');
+
+    // ── Qwen Code ────────────────────────────────────────────────────────────
+    case 'qwen':
+      return env.QWEN_CONFIG_DIR ? expandTilde(env.QWEN_CONFIG_DIR) : path.join(home, '.qwen');
+
+    // ── Hermes Agent ─────────────────────────────────────────────────────────
+    // Note: skills use a nested layout (skills/sdd/<skill>/) — see getGlobalSkillDir().
+    case 'hermes':
+      return env.HERMES_HOME ? expandTilde(env.HERMES_HOME) : path.join(home, '.hermes');
+
+    // ── CodeBuddy ────────────────────────────────────────────────────────────
+    case 'codebuddy':
+      return env.CODEBUDDY_CONFIG_DIR ? expandTilde(env.CODEBUDDY_CONFIG_DIR) : path.join(home, '.codebuddy');
+
+    // ── Cline ────────────────────────────────────────────────────────────────
+    // Note: Cline is rules-based (.clinerules) — no skills/ directory.
+    // getGlobalSkillDir() returns null for cline.
+    case 'cline':
+      return env.CLINE_CONFIG_DIR ? expandTilde(env.CLINE_CONFIG_DIR) : path.join(home, '.cline');
+
+    // ── OpenCode (XDG) ───────────────────────────────────────────────────────
+    case 'opencode': {
+      if (env.OPENCODE_CONFIG_DIR) return expandTilde(env.OPENCODE_CONFIG_DIR);
+      if (env.XDG_CONFIG_HOME) return path.join(expandTilde(env.XDG_CONFIG_HOME), 'opencode');
+      return path.join(home, '.config', 'opencode');
+    }
+
+    // ── Kilo (XDG) ───────────────────────────────────────────────────────────
+    case 'kilo': {
+      if (env.KILO_CONFIG_DIR) return expandTilde(env.KILO_CONFIG_DIR);
+      if (env.XDG_CONFIG_HOME) return path.join(expandTilde(env.XDG_CONFIG_HOME), 'kilo');
+      return path.join(home, '.config', 'kilo');
+    }
+
+    // ── Default (Claude fallback) ─────────────────────────────────────────────
+    default:
+      return env.CLAUDE_CONFIG_DIR ? expandTilde(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+  }
+}
+
+/**
+ * Return the global skills base directory for the given runtime.
+ * Most runtimes: <configDir>/skills
+ * Hermes: <configDir>/skills/sdd  (nested category layout — #2841)
+ * Cline:  null (rules-based, no skills directory)
+ *
+ * @param {string} runtime
+ * @returns {string|null}
+ */
+function getGlobalSkillsBase(runtime) {
+  if (runtime === 'cline') return null;
+  const configDir = getGlobalConfigDir(runtime);
+  if (runtime === 'hermes') return path.join(configDir, 'skills', 'sdd');
+  return path.join(configDir, 'skills');
+}
+
+/**
+ * Return the full path to a specific skill's directory for the given runtime.
+ * Returns null for runtimes that don't use a skills directory (cline).
+ *
+ * @param {string} runtime
+ * @param {string} skillName - e.g. 'sdd-executor'
+ * @returns {string|null}
+ */
+function getGlobalSkillDir(runtime, skillName) {
+  const base = getGlobalSkillsBase(runtime);
+  if (base === null) return null;
+  return path.join(base, skillName);
+}
+
+/**
+ * Return a human-readable display path for a global skill (for log messages).
+ *
+ * @param {string} runtime
+ * @param {string} skillName
+ * @returns {string}
+ */
+function getGlobalSkillDisplayPath(runtime, skillName) {
+  const dir = getGlobalSkillDir(runtime, skillName);
+  if (!dir) return `(${runtime} does not use a skills directory)`;
+  // Replace homedir prefix with ~ for readability
+  const home = os.homedir();
+  return dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+}
+
+module.exports = {
+  getGlobalConfigDir,
+  getGlobalSkillsBase,
+  getGlobalSkillDir,
+  getGlobalSkillDisplayPath,
+};

package/sdd/bin/lib/sdd2-import.cjs

@@ -19,6 +19,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
 
 // ─── Utilities ──────────────────────────────────────────────────────────────
 
@@ -420,7 +421,7 @@ function buildPreview(sdd2Data, artifacts) {
   lines.push('');
   lines.push('Cannot migrate automatically:');
   lines.push('  - SDD-2 cost/token ledger (no v1 equivalent)');
-  lines.push('  - SDD-2 database state (rebuilt from files on first /sdd-health)');
+  lines.push('  - SDD-2 database state (rebuilt from files on first /sdd:health)');
   lines.push('  - VS Code extension state');
 
   return lines.join('\n');
@@ -434,8 +435,7 @@ function buildPreview(sdd2Data, artifacts) {
 function writePlanningDir(artifacts, planningRoot) {
   for (const [rel, content] of artifacts) {
     const absPath = path.join(planningRoot, rel);
-    fs.mkdirSync(path.dirname(absPath), { recursive: true });
-    fs.writeFileSync(absPath, content, 'utf8');
+    platformWriteSync(absPath, content);
   }
 }
 

package/sdd/bin/lib/secrets.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Secrets handling — masking convention for API keys and other
+ * credentials managed via /sdd-settings-integrations.
+ *
+ * Convention: strings 8+ chars long render as `****<last-4>`; shorter
+ * strings render as `****` with no tail (to avoid leaking a meaningful
+ * fraction of a short secret). null/empty renders as `(unset)`.
+ *
+ * Keys considered sensitive are listed in SECRET_CONFIG_KEYS and matched
+ * at the exact key-path level. The list is intentionally narrow — these
+ * are the fields documented as secrets in docs/CONFIGURATION.md.
+ */
+
+const SECRET_CONFIG_KEYS = new Set([
+  'brave_search',
+  'firecrawl',
+  'exa_search',
+]);
+
+function isSecretKey(keyPath) {
+  return SECRET_CONFIG_KEYS.has(keyPath);
+}
+
+function maskSecret(value) {
+  if (value === null || value === undefined || value === '') return '(unset)';
+  const s = String(value);
+  if (s.length < 8) return '****';
+  return '****' + s.slice(-4);
+}
+
+module.exports = { SECRET_CONFIG_KEYS, isSecretKey, maskSecret };

package/sdd/bin/lib/security.cjs

@@ -141,7 +141,7 @@ const INJECTION_PATTERNS = [
   // Requires > to close the tag (not just whitespace) to avoid matching generic types like Promise<User | null>
   /<\/?(?:system|assistant|human)>/i,
   /\[SYSTEM\]/i,
-  /\[INST\]/i,
+  /\[\/?(INST)\]/i,
   /<<\s*SYS\s*>>/i,
 
   // Exfiltration attempts
@@ -163,7 +163,7 @@ const OBFUSCATION_PATTERN_ENTRIES = [
   },
   {
     pattern: /<\/?(system|human|assistant|user)\s*>/i,
-    message: 'Delimiter injection pattern: <system>/<assistant>/<user> tag detected',
+    message: 'Delimiter injection pattern: <system>/<human>/<assistant>/<user> tag detected',
   },
   {
     pattern: /0x[0-9a-fA-F]{16,}/,
@@ -245,14 +245,15 @@ function sanitizeForPrompt(text) {
   // Neutralize XML/HTML tags that mimic system boundaries
   // Replace < > with full-width equivalents to prevent tag interpretation
   // Note: <instructions> is excluded — SDD uses it as legitimate prompt structure
-  sanitized = sanitized.replace(/<(\/?)(?:system|assistant|human)>/gi,
+  // Matches system|assistant|human|user with optional whitespace before the closing >
+  sanitized = sanitized.replace(/<(\/?)\s*(?:system|assistant|human|user)\s*>/gi,
     (_, slash) => `＜${slash || ''}system-text＞`);
 
-  // Neutralize [SYSTEM] / [INST] markers
-  sanitized = sanitized.replace(/\[(SYSTEM|INST)\]/gi, '[$1-TEXT]');
+  // Neutralize [SYSTEM] / [INST] / [/INST] markers — both opening and closing variants
+  sanitized = sanitized.replace(/\[(\/?)(SYSTEM|INST)\]/gi, (_, slash, tag) => `[${slash}${tag.toUpperCase()}-TEXT]`);
 
-  // Neutralize <<SYS>> markers
-  sanitized = sanitized.replace(/<<\s*SYS\s*>>/gi, '«SYS-TEXT»');
+  // Neutralize <<SYS>> and <</SYS>> markers (Llama-style delimiters)
+  sanitized = sanitized.replace(/<<\/?\s*SYS\s*>>/gi, '«SYS-TEXT»');
 
   return sanitized;
 }