@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/bin/lib/surface.cjs

@@ -0,0 +1,398 @@
+'use strict';
+/**
+ * Runtime surface module — ADR-0011 Phase 2 (Option B).
+ *
+ * Manages the runtime enable/disable surface state (the `.sdd-surface.json` marker in
+ * each runtime's skills dir) independently of the install-time profile marker
+ * (`.sdd-profile`). Runtime config locations are resolved by callers.
+ *
+ * Effective skill set = base profile ∪ explicitAdds − disabledClusters − explicitRemoves,
+ * then transitively closed via the manifest.
+ *
+ * Exports:
+ *   readSurface(runtimeConfigDir)
+ *   writeSurface(runtimeConfigDir, surfaceState)
+ *   resolveSurface(runtimeConfigDir, manifest, clusterMap)
+ *   applySurface(runtimeConfigDir, commandsDir, agentsDir, manifest, clusterMap)
+ *   listSurface(runtimeConfigDir, manifest, clusterMap)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
+
+const {
+  readActiveProfile,
+  resolveProfile,
+  stageSkillsForProfile,
+  stageAgentsForProfile,
+  loadSkillsManifest,
+  PROFILES,
+} = require('./install-profiles.cjs');
+const { CLUSTERS, allClusteredSkills } = require('./clusters.cjs');
+
+const SURFACE_FILE_NAME = '.sdd-surface.json';
+
+// ---------------------------------------------------------------------------
+// State IO
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} SurfaceState
+ * @property {string} baseProfile
+ * @property {string[]} disabledClusters
+ * @property {string[]} explicitAdds
+ * @property {string[]} explicitRemoves
+ */
+
+/**
+ * Read the surface state from a runtime config directory.
+ *
+ * @param {string} runtimeConfigDir
+ * @returns {SurfaceState|null} null if file missing or corrupt
+ */
+function readSurface(runtimeConfigDir) {
+  const filePath = path.join(runtimeConfigDir, SURFACE_FILE_NAME);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    // Structural validation — must have these fields with expected types
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    if (typeof parsed.baseProfile !== 'string') return null;
+    if (!Array.isArray(parsed.disabledClusters)) return null;
+    if (!Array.isArray(parsed.explicitAdds)) return null;
+    if (!Array.isArray(parsed.explicitRemoves)) return null;
+    return {
+      baseProfile: parsed.baseProfile,
+      disabledClusters: parsed.disabledClusters,
+      explicitAdds: parsed.explicitAdds,
+      explicitRemoves: parsed.explicitRemoves,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the surface state atomically via the platform seam (mkdir + tmp+rename).
+ *
+ * @param {string} runtimeConfigDir
+ * @param {SurfaceState} surfaceState
+ */
+function writeSurface(runtimeConfigDir, surfaceState) {
+  platformWriteSync(path.join(runtimeConfigDir, SURFACE_FILE_NAME), JSON.stringify(surfaceState, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Expand cluster names to skill stems using the provided clusterMap.
+ *
+ * @param {string[]} clusterNames
+ * @param {Object} clusterMap CLUSTERS or override
+ * @returns {Set<string>}
+ */
+function clustersToSkills(clusterNames, clusterMap) {
+  const result = new Set();
+  for (const name of clusterNames) {
+    const members = clusterMap[name];
+    if (members) {
+      for (const s of members) result.add(s);
+    }
+  }
+  return result;
+}
+
+/**
+ * Resolve the effective surface to a typed profile-like object.
+ * Shape: { name, skills: Set<string>|'*', agents: Set<string> }
+ *
+ * Resolution order:
+ * 1. Start with base profile resolved via resolveProfile()
+ * 2. Remove skills in disabled clusters
+ * 3. Add explicitAdds (and their transitive closure)
+ * 4. Remove explicitRemoves (only the stem itself, no cascade)
+ *
+ * @param {string} runtimeConfigDir
+ * @param {Map<string, string[]>} manifest
+ * @param {Object} [clusterMap] defaults to CLUSTERS
+ * @returns {{ name: string, skills: Set<string>, agents: Set<string> }}
+ */
+function resolveSurface(runtimeConfigDir, manifest, clusterMap) {
+  const cm = clusterMap || CLUSTERS;
+  const surface = readSurface(runtimeConfigDir);
+
+  // Determine base profile name: from surface state or from .sdd-profile marker
+  const baseProfileName = (surface && surface.baseProfile)
+    ? surface.baseProfile
+    : (readActiveProfile(runtimeConfigDir) || 'full');
+
+  // Resolve base profile
+  const baseResolved = resolveProfile({
+    modes: baseProfileName.split(',').map(s => s.trim()),
+    manifest,
+  });
+
+  // If full, we need to enumerate all skills from the manifest
+  let skills;
+  if (baseResolved.skills === '*') {
+    // Materialize all skill stems from manifest
+    skills = new Set();
+    for (const [key] of manifest) {
+      if (!key.startsWith('_calls_agents_')) skills.add(key);
+    }
+  } else {
+    skills = new Set(baseResolved.skills);
+  }
+
+  if (surface) {
+    // Step 2: remove disabled cluster members
+    const disabledSkills = clustersToSkills(surface.disabledClusters, cm);
+    for (const s of disabledSkills) skills.delete(s);
+
+    // Step 3: add explicitAdds with transitive closure
+    if (surface.explicitAdds.length > 0) {
+      const addSet = new Set(surface.explicitAdds);
+      // Compute closure of adds
+      const queue = [...addSet];
+      const visited = new Set(addSet);
+      while (queue.length > 0) {
+        const stem = queue.pop();
+        const deps = manifest.get(stem) || [];
+        for (const dep of deps) {
+          if (!visited.has(dep)) {
+            visited.add(dep);
+            queue.push(dep);
+          }
+        }
+      }
+      for (const s of visited) skills.add(s);
+    }
+
+    // Step 4: remove explicitRemoves (stem only, no cascade)
+    for (const s of surface.explicitRemoves) {
+      skills.delete(s);
+    }
+  }
+
+  // Derive agents from skills
+  const agents = new Set();
+  for (const skillStem of skills) {
+    const agentRefs = manifest.get(`_calls_agents_${skillStem}`) || [];
+    for (const agentStem of agentRefs) agents.add(agentStem);
+  }
+
+  const name = surface ? `surface:${surface.baseProfile}` : `profile:${baseProfileName}`;
+  return { name, skills, agents };
+}
+
+// ---------------------------------------------------------------------------
+// Apply
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-stage the active surface to commandsDir and agentsDir in-place.
+ * Only touches files matching `sdd-` prefix or `*.md` in commandsDir.
+ * Never touches non-`sdd-*` files.
+ *
+ * Steps:
+ *  1. Resolve surface → active skill/agent sets
+ *  2. Stage to temp dirs via stageSkillsForProfile / stageAgentsForProfile
+ *  3. Find the install source (where skill files live)
+ *  4. Sync: copy missing, delete superseded (sdd-only)
+ *
+ * @param {string} runtimeConfigDir
+ * @param {string} commandsDir  runtime commands/sdd dir (resolved per-runtime by callers)
+ * @param {string} agentsDir    runtime agents dir (resolved per-runtime by callers)
+ * @param {Map<string, string[]>} manifest
+ * @param {Object} [clusterMap]
+ */
+function applySurface(runtimeConfigDir, commandsDir, agentsDir, manifest, clusterMap) {
+  const resolved = resolveSurface(runtimeConfigDir, manifest, clusterMap);
+
+  // Find install source
+  const srcCommandsDir = _findInstallSource(runtimeConfigDir);
+
+  // Stage skills
+  const stagedSkills = stageSkillsForProfile(srcCommandsDir, resolved);
+
+  // Sync commandsDir from stagedSkills
+  _syncSddDir(stagedSkills, commandsDir, 'commands');
+
+  // Stage and sync agents
+  if (agentsDir && fs.existsSync(agentsDir)) {
+    const srcAgentsDir = _findAgentsSource(runtimeConfigDir);
+    if (srcAgentsDir) {
+      const stagedAgents = stageAgentsForProfile(srcAgentsDir, resolved);
+      _syncSddDir(stagedAgents, agentsDir, 'agents');
+    }
+  }
+}
+
+/**
+ * Sync destination directory from staged source.
+ * Adds files present in staged but missing in dest.
+ * Removes sdd-prefixed .md files in dest not present in staged.
+ * Never touches non-sdd files.
+ *
+ * @param {string} stagedDir source (staged temp dir or original)
+ * @param {string} destDir runtime destination
+ * @param {'commands'|'agents'} context
+ */
+function _syncSddDir(stagedDir, destDir, context) {
+  if (!fs.existsSync(stagedDir)) return;
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const stagedFiles = new Set(
+    fs.readdirSync(stagedDir).filter(f => f.endsWith('.md'))
+  );
+
+  // Copy missing files from staged to dest
+  for (const file of stagedFiles) {
+    const destFile = path.join(destDir, file);
+    if (!fs.existsSync(destFile)) {
+      fs.copyFileSync(path.join(stagedDir, file), destFile);
+    } else {
+      // Overwrite to ensure content is current
+      fs.copyFileSync(path.join(stagedDir, file), destFile);
+    }
+  }
+
+  // Remove sdd-only files from dest that aren't in staged set
+  // For commands dir: all .md files are sdd skills
+  // For agents dir: only sdd-* files
+  const destEntries = fs.readdirSync(destDir).filter(f => f.endsWith('.md'));
+  for (const file of destEntries) {
+    if (context === 'agents' && !file.startsWith('sdd-')) continue;
+    if (!stagedFiles.has(file)) {
+      try { fs.unlinkSync(path.join(destDir, file)); } catch {}
+    }
+  }
+}
+
+/**
+ * Find the install source commands/sdd directory.
+ * Checks the runtime's `.sdd-source` marker (sibling of the surface state file),
+ * then walks up from __dirname to find the installed package source.
+ *
+ * @param {string} runtimeConfigDir
+ * @returns {string} path to install source commands/sdd
+ */
+function _findInstallSource(runtimeConfigDir) {
+  // Check for .sdd-source marker
+  const sourceMarker = path.join(runtimeConfigDir, '.sdd-source');
+  if (fs.existsSync(sourceMarker)) {
+    try {
+      const src = fs.readFileSync(sourceMarker, 'utf8').trim();
+      if (src && fs.existsSync(src)) return src;
+    } catch {}
+  }
+
+  // Walk up from this module's dir to find commands/sdd
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, 'commands', 'sdd');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Fallback: the runtimeConfigDir itself
+  return path.join(runtimeConfigDir, '..', 'commands', 'sdd');
+}
+
+/**
+ * Find the install source agents directory.
+ *
+ * @param {string} runtimeConfigDir
+ * @returns {string|null}
+ */
+function _findAgentsSource(runtimeConfigDir) {
+  // Prefer .sdd-source sibling marker (commands/sdd) and derive agents from it.
+  const sourceMarker = path.join(runtimeConfigDir, '.sdd-source');
+  if (fs.existsSync(sourceMarker)) {
+    try {
+      const commandsSrc = fs.readFileSync(sourceMarker, 'utf8').trim();
+      if (commandsSrc && fs.existsSync(commandsSrc)) {
+        const commandsParent = path.dirname(commandsSrc); // .../commands
+        const candidate = path.resolve(commandsParent, '..', 'agents');
+        if (fs.existsSync(candidate)) return candidate;
+      }
+    } catch {}
+  }
+
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, 'agents');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+
+/**
+ * List the currently enabled and disabled skills with token cost.
+ *
+ * Token cost = sum of description lengths ÷ 4 (mirrors audit script).
+ * Descriptions are read from the installed commandsDir skill files.
+ *
+ * @param {string} runtimeConfigDir
+ * @param {Map<string, string[]>} manifest
+ * @param {Object} [clusterMap]
+ * @returns {{ enabled: string[], disabled: string[], tokenCost: number }}
+ */
+function listSurface(runtimeConfigDir, manifest, clusterMap) {
+  const resolved = resolveSurface(runtimeConfigDir, manifest, clusterMap);
+
+  // All known stems from manifest (exclude _calls_agents_ meta keys)
+  const allStems = [];
+  for (const [key] of manifest) {
+    if (!key.startsWith('_calls_agents_')) allStems.push(key);
+  }
+
+  const enabledSet = resolved.skills instanceof Set ? resolved.skills : new Set(allStems);
+
+  const enabled = allStems.filter(s => enabledSet.has(s)).sort();
+  const disabled = allStems.filter(s => !enabledSet.has(s)).sort();
+
+  // Compute token cost by reading descriptions from the install source
+  const srcCommandsDir = _findInstallSource(runtimeConfigDir);
+  let tokenCost = 0;
+  for (const stem of enabled) {
+    const filePath = path.join(srcCommandsDir, `${stem}.md`);
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const descMatch = content.match(/^description:\s*(.+)$/m);
+      if (descMatch) {
+        tokenCost += Math.ceil(descMatch[1].trim().length / 4);
+      }
+    } catch {}
+  }
+
+  return { enabled, disabled, tokenCost };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  readSurface,
+  writeSurface,
+  resolveSurface,
+  applySurface,
+  listSurface,
+  // Exported for testing
+  _findInstallSource,
+  _syncSddDir,
+};

package/sdd/bin/lib/template.cjs

@@ -4,7 +4,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { normalizePhaseName, findPhaseInternal, generateSlugInternal, normalizeMd, toPosixPath, planningDir, output, error } = require('./core.cjs');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = require('./core.cjs');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
+const { planningDir } = require('./planning-workspace.cjs');
 const { reconstructFrontmatter } = require('./frontmatter.cjs');
 
 function cmdTemplateSelect(cwd, planPath, raw) {
@@ -218,7 +220,7 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
     return;
   }
 
-  fs.writeFileSync(outPath, normalizeMd(fullContent), 'utf-8');
+  platformWriteSync(outPath, fullContent);
   const relPath = toPosixPath(path.relative(cwd, outPath));
   output({ created: true, path: relPath, template: templateType }, raw, relPath);
 }

package/sdd/bin/lib/uat.cjs

@@ -7,7 +7,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, getMilestonePhaseFilter, planningDir, toPosixPath } = require('./core.cjs');
+const { output, error, getMilestonePhaseFilter, toPosixPath } = require('./core.cjs');
+const { planningDir } = require('./planning-workspace.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { requireSafePath, sanitizeForDisplay } = require('./security.cjs');
 
@@ -181,7 +182,8 @@ function buildCheckpoint(currentTest) {
 function parseUatItems(content) {
   const items = [];
   // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n
-  const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*(\w+)(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
+  // Accept both bare (result: pending) and bracketed (result: [pending]) formats (#2273)
+  const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*\[?(\w+)\]?(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
   let match;
   while ((match = testPattern.exec(content)) !== null) {
     const [, num, name, expected, result] = match;
@@ -224,6 +226,11 @@ function parseVerificationItems(content, status) {
         const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
 
         if (tableMatch) {
+          // Skip rows that already have a passing result (PASS, pass, resolved, etc.)
+          const rowRemainder = line.slice(tableMatch.index + tableMatch[0].length);
+          const cellValues = rowRemainder.split('|').map(c => c.trim());
+          const hasPassResult = cellValues.some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
+          if (hasPassResult) continue;
           items.push({
             test: parseInt(tableMatch[1], 10),
             name: tableMatch[2].trim(),

package/sdd/bin/lib/validate-command-router.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+const { VALIDATE_SUBCOMMANDS } = require('./command-aliases.generated.cjs');
+
+function routeValidateCommand({ verify, args, cwd, raw, parseNamedArgs, output, error }) {
+  const subcommand = args[1];
+
+  if (subcommand === 'consistency') {
+    verify.cmdValidateConsistency(cwd, raw);
+  } else if (subcommand === 'health') {
+    const repairFlag = args.includes('--repair');
+    const backfillFlag = args.includes('--backfill');
+    verify.cmdValidateHealth(cwd, { repair: repairFlag, backfill: backfillFlag }, raw);
+  } else if (subcommand === 'agents') {
+    verify.cmdValidateAgents(cwd, raw);
+  } else if (subcommand === 'context') {
+    const opts = parseNamedArgs(args, ['tokens-used', 'context-window']);
+    if (opts['tokens-used'] === null) {
+      error('--tokens-used <integer> is required for `validate context`');
+      return;
+    }
+    if (opts['context-window'] === null) {
+      error('--context-window <integer> is required for `validate context`');
+      return;
+    }
+    const { classifyContextUtilization, STATES } = require('./context-utilization.cjs');
+    const RECOMMENDATIONS = {
+      [STATES.HEALTHY]: null,
+      [STATES.WARNING]: 'Context is approaching the fracture zone — consider /sdd:thread to continue in a fresh window.',
+      [STATES.CRITICAL]: 'Reasoning quality may degrade past 70% utilization (fracture point). Run /sdd:thread now to preserve output quality.',
+    };
+    let classified;
+    try {
+      classified = classifyContextUtilization(Number(opts['tokens-used']), Number(opts['context-window']));
+    } catch (e) {
+      const flag = /tokensUsed/.test(e.message) ? '--tokens-used' : '--context-window';
+      error(`${flag} must be a non-negative integer (window > 0), got the values supplied`);
+      return;
+    }
+    const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
+    if (args.includes('--json')) {
+      output(result, raw);
+    } else {
+      const lines = [`Context utilization: ${result.percent}% (${result.state})`];
+      if (result.recommendation) lines.push(result.recommendation);
+      output(result, true, lines.join('\n'));
+    }
+  } else {
+    error(`Unknown validate subcommand. Available: ${VALIDATE_SUBCOMMANDS.join(', ')}`);
+  }
+}
+
+module.exports = {
+  routeValidateCommand,
+};

package/sdd/bin/lib/verify-command-router.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+const { VERIFY_SUBCOMMANDS } = require('./command-aliases.generated.cjs');
+
+function routeVerifyCommand({ verify, args, cwd, raw, error }) {
+  const subcommand = args[1];
+
+  if (subcommand === 'plan-structure') {
+    verify.cmdVerifyPlanStructure(cwd, args[2], raw);
+  } else if (subcommand === 'phase-completeness') {
+    verify.cmdVerifyPhaseCompleteness(cwd, args[2], raw);
+  } else if (subcommand === 'references') {
+    verify.cmdVerifyReferences(cwd, args[2], raw);
+  } else if (subcommand === 'commits') {
+    verify.cmdVerifyCommits(cwd, args.slice(2), raw);
+  } else if (subcommand === 'artifacts') {
+    verify.cmdVerifyArtifacts(cwd, args[2], raw);
+  } else if (subcommand === 'key-links') {
+    verify.cmdVerifyKeyLinks(cwd, args[2], raw);
+  } else if (subcommand === 'schema-drift') {
+    const rest = args.slice(2);
+    const skipFlag = rest.includes('--skip');
+    const phaseArg = rest.find((arg) => !arg.startsWith('-'));
+    verify.cmdVerifySchemaDrift(cwd, phaseArg, skipFlag, raw);
+  } else if (subcommand === 'codebase-drift') {
+    verify.cmdVerifyCodebaseDrift(cwd, raw);
+  } else {
+    error(`Unknown verify subcommand. Available: ${VERIFY_SUBCOMMANDS.join(', ')}`);
+  }
+}
+
+module.exports = {
+  routeVerifyCommand,
+};