refacil-sdd-ai 5.2.2 → 5.3.0

package/lib/commands/sdd.js

@@ -3,21 +3,9 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { loadBranchConfigWithSources, parseYaml, readConfigFile, SUPPORTED_LANGUAGES } = require('../config');
-
-function findProjectRoot() {
-  let dir = process.cwd();
-  const { root } = path.parse(dir);
-  while (dir !== root) {
-    if (fs.existsSync(path.join(dir, 'refacil-sdd')) || fs.existsSync(path.join(dir, '.git'))) {
-      return dir;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return process.cwd();
-}
+const { loadBranchConfigWithSources, parseYaml, readConfigFile, SUPPORTED_LANGUAGES, CODEGRAPH_MODES } = require('../config');
+const { findProjectRoot } = require('../project-root');
+const { collectSpecSourceFiles } = require('../spec-sync');
 
 // --- Helpers ---
 
@@ -42,6 +30,11 @@ function parseArgs(argv) {
   return args;
 }
 
+/** Bug-fix changes from refacil:bug use fix-* and only carry summary.md (no specs/). */
+function isBugFixChangeName(name) {
+  return typeof name === 'string' && name.startsWith('fix-');
+}
+
 function validateChangeName(name) {
   if (!name || name.trim() === '') {
     return { valid: false, reason: 'El nombre del cambio no puede estar vacío.' };
@@ -64,6 +57,59 @@ function validateChangeName(name) {
   return { valid: true };
 }
 
+/**
+ * Looks up a change name inside the archive directory.
+ * Archive entry format: refacil-sdd/changes/archive/YYYY-MM-DD-<changeName>/
+ *
+ * Rules:
+ * - Matches by exact suffix `-<name>` (not substring).
+ * - Validates prefix matches /^\d{4}-\d{2}-\d{2}-/.
+ * - Returns most recent directory path (sorted descending by date prefix).
+ * - If two entries share the same suffix (same name, different dates) → returns most recent.
+ * - If the name is ambiguous (two entries with truly different names both match) → returns null and emits error.
+ * - Returns null if no match or archive dir doesn't exist.
+ */
+function resolveArchivedChangeName(projectRoot, name) {
+  if (!name || typeof name !== 'string') return null;
+
+  const archiveDir = path.join(projectRoot, 'refacil-sdd', 'changes', 'archive');
+  if (!fs.existsSync(archiveDir)) return null;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(archiveDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch (_) {
+    return null;
+  }
+
+  // Date prefix pattern
+  const datePrefix = /^\d{4}-\d{2}-\d{2}-/;
+
+  // Filter by exact suffix match AND valid date prefix
+  const suffix = `-${name}`;
+  const matches = entries.filter((entry) => {
+    if (!datePrefix.test(entry)) return false;
+    return entry.endsWith(suffix);
+  });
+
+  if (matches.length === 0) return null;
+
+  // Check for ambiguity: extract the clean name (strip date prefix) and verify all match the same name
+  const cleanNames = new Set(matches.map((entry) => entry.replace(datePrefix, '')));
+  if (cleanNames.size > 1) {
+    // Multiple distinct clean names matched — truly ambiguous
+    console.error(`Nombre de cambio archivado ambiguo: '${name}'. Coincidencias: ${matches.join(', ')}`);
+    return null;
+  }
+
+  // Sort descending by date prefix so most recent is first
+  matches.sort((a, b) => b.localeCompare(a));
+
+  return path.join(archiveDir, matches[0]);
+}
+
 function resolveExistingChangeName(projectRoot, inputName) {
   if (!inputName || typeof inputName !== 'string') {
     return { ok: false, reason: 'El nombre del cambio no puede estar vacío.' };
@@ -179,6 +225,38 @@ function cmdNewChange(argv, projectRoot) {
   console.log(`Cambio '${name}' creado en refacil-sdd/changes/${name}/`);
 }
 
+function cmdSyncSpec(argv, projectRoot) {
+  const args = parseArgs(argv);
+  const rawName = args._positional[0];
+
+  autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
+  const fromArchive = args['from-archive'] === true;
+
+  if (!fromArchive) {
+    const sourceDir = path.join(projectRoot, 'refacil-sdd', 'changes', name);
+    if (!fs.existsSync(sourceDir)) {
+      console.error(`No existe el cambio '${name}' en refacil-sdd/changes/${name}/`);
+      process.exit(1);
+    }
+  }
+
+  try {
+    const { syncSpecToCatalog } = require('../spec-sync');
+    const result = syncSpecToCatalog(projectRoot, name, { fromArchive });
+    const rel = path.relative(projectRoot, result.specPath).replace(/\\/g, '/');
+    console.log(`  Spec sincronizado: ${rel} (${result.criteriaCount} criterios, idioma: ${result.language})`);
+  } catch (err) {
+    console.error(`  Error sincronizando spec: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 function cmdArchive(argv, projectRoot) {
   const args = parseArgs(argv);
   const rawName = args._positional[0];
@@ -203,6 +281,20 @@ function cmdArchive(argv, projectRoot) {
     process.exit(1);
   }
 
+  if (!isBugFixChangeName(name)) {
+    try {
+      const { syncSpecToCatalog } = require('../spec-sync');
+      const result = syncSpecToCatalog(projectRoot, name);
+      const rel = path.relative(projectRoot, result.specPath).replace(/\\/g, '/');
+      console.log(`  Spec sincronizado: ${rel} (idioma: ${result.language}, ${result.criteriaCount} criterios)`);
+    } catch (err) {
+      console.error(`  Error sincronizando spec antes de archivar: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    console.log('  Bug fix (fix-*): omitiendo sincronización de spec (use refacil:archive para documentar en refacil-sdd/specs/)');
+  }
+
   const date = new Date().toISOString().slice(0, 10);
   const archiveDir = path.join(projectRoot, 'refacil-sdd', 'changes', 'archive');
   const destDir = path.join(archiveDir, `${date}-${name}`);
@@ -212,10 +304,6 @@ function cmdArchive(argv, projectRoot) {
     process.exit(1);
   }
 
-  // Delete memory.yaml before archiving (CA-18)
-  const memoryFile = path.join(sourceDir, 'memory.yaml');
-  if (fs.existsSync(memoryFile)) fs.unlinkSync(memoryFile);
-
   fs.mkdirSync(archiveDir, { recursive: true });
   fs.renameSync(sourceDir, destDir);
 
@@ -389,6 +477,7 @@ function cmdClearReviewFails(argv, projectRoot) {
 function cmdList(argv, projectRoot) {
   const args = parseArgs(argv);
   const wantJson = args.json === true;
+  const includeArchived = args['include-archived'] === true;
 
   autoMigrateOpenspec(projectRoot);
 
@@ -410,17 +499,55 @@ function cmdList(argv, projectRoot) {
     return { name: e.name, reviewPassed };
   });
 
+  // Build archived entries when --include-archived is requested
+  const archivedResult = [];
+  if (includeArchived) {
+    const archiveDir = path.join(changesDir, 'archive');
+    if (fs.existsSync(archiveDir)) {
+      const datePrefix = /^\d{4}-\d{2}-\d{2}-/;
+      try {
+        const archiveEntries = fs.readdirSync(archiveDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && datePrefix.test(e.name));
+        for (const e of archiveEntries) {
+          const dateMatch = e.name.match(/^(\d{4}-\d{2}-\d{2})-/);
+          const archivedDate = dateMatch ? dateMatch[1] : null;
+          const cleanName = e.name.replace(datePrefix, '');
+          archivedResult.push({ name: cleanName, reviewPassed: null, archived: true, archivedDate });
+        }
+        // Sort descending by date prefix (most recent first)
+        archivedResult.sort((a, b) => {
+          const da = a.archivedDate || '';
+          const db = b.archivedDate || '';
+          return db.localeCompare(da);
+        });
+      } catch (_) {}
+    }
+    // If archive dir doesn't exist, gracefully produce empty list (exit 0)
+  }
+
   if (wantJson) {
-    process.stdout.write(JSON.stringify(result) + '\n');
+    const combined = result.concat(archivedResult);
+    process.stdout.write(JSON.stringify(combined) + '\n');
   } else {
-    if (result.length === 0) {
+    if (result.length === 0 && archivedResult.length === 0) {
       console.log('Sin cambios activos.');
       return;
     }
-    console.log('Cambios activos en refacil-sdd/changes/:');
-    for (const item of result) {
-      const badge = item.reviewPassed ? '[reviewed]' : '[pending-review]';
-      console.log(`  ${item.name}  ${badge}`);
+    if (result.length > 0) {
+      console.log('Cambios activos en refacil-sdd/changes/:');
+      for (const item of result) {
+        const badge = item.reviewPassed ? '[reviewed]' : '[pending-review]';
+        console.log(`  ${item.name}  ${badge}`);
+      }
+    } else if (!includeArchived) {
+      console.log('Sin cambios activos.');
+    }
+    if (includeArchived && archivedResult.length > 0) {
+      if (result.length > 0) console.log('');
+      console.log('Cambios archivados en refacil-sdd/changes/archive/:');
+      for (const item of archivedResult) {
+        console.log(`  ${item.name}  [archived]  (${item.archivedDate || '?'})`);
+      }
     }
   }
 }
@@ -454,16 +581,7 @@ function cmdStatus(argv, projectRoot) {
   const hasDesign = fs.existsSync(path.join(changeDir, 'design.md'));
   const hasTasks = fs.existsSync(path.join(changeDir, 'tasks.md'));
 
-  // specs: specs.md existe OR specs/ dir con al menos un .md
-  let hasSpecs = false;
-  const specsMd = path.join(changeDir, 'specs.md');
-  const specsDir = path.join(changeDir, 'specs');
-  if (fs.existsSync(specsMd)) {
-    hasSpecs = true;
-  } else if (fs.existsSync(specsDir) && fs.statSync(specsDir).isDirectory()) {
-    const mdFiles = fs.readdirSync(specsDir).filter((f) => f.endsWith('.md'));
-    hasSpecs = mdFiles.length > 0;
-  }
+  const hasSpecs = collectSpecSourceFiles(changeDir).length > 0;
 
   const artifacts = {
     proposal: hasProposal,
@@ -485,7 +603,7 @@ function cmdStatus(argv, projectRoot) {
   const reviewPassed = fs.existsSync(path.join(changeDir, '.review-passed'));
 
   const ready = {
-    forApply: artifacts.proposal && artifacts.tasks,
+    forApply: artifacts.proposal && artifacts.design && artifacts.tasks && artifacts.specs,
     forArchive: reviewPassed && taskStats.total > 0 && taskStats.pending === 0,
   };
 
@@ -653,11 +771,12 @@ function cmdWriteConfig(argv, projectRoot) {
   const rawBaseBranch = args['base-branch'];
   const rawProtectedBranches = args['protected-branches'];
   const rawArtifactLanguage = args['artifact-language'];
+  const rawCodegraph = args['codegraph'];
 
   // CR-03: no flags provided
-  if (rawBaseBranch === undefined && rawProtectedBranches === undefined && rawArtifactLanguage === undefined) {
-    console.error('Uso: refacil-sdd-ai sdd write-config [--global] [--base-branch <branch>] [--protected-branches <csv>] [--artifact-language <language>]');
-    console.error('Debe especificar al menos --base-branch, --protected-branches o --artifact-language.');
+  if (rawBaseBranch === undefined && rawProtectedBranches === undefined && rawArtifactLanguage === undefined && rawCodegraph === undefined) {
+    console.error('Uso: refacil-sdd-ai sdd write-config [--global] [--base-branch <branch>] [--protected-branches <csv>] [--artifact-language <language>] [--codegraph <mode>]');
+    console.error('Debe especificar al menos --base-branch, --protected-branches, --artifact-language o --codegraph.');
     process.exit(1);
   }
 
@@ -689,6 +808,18 @@ function cmdWriteConfig(argv, projectRoot) {
     }
   }
 
+  // --codegraph: must be a valid CODEGRAPH_MODES value
+  if (rawCodegraph !== undefined) {
+    if (typeof rawCodegraph !== 'string' || rawCodegraph.trim() === '') {
+      console.error('Error: --codegraph no puede estar vacío.');
+      process.exit(1);
+    }
+    if (!CODEGRAPH_MODES.includes(rawCodegraph.trim())) {
+      console.error(`Error: --codegraph "${rawCodegraph.trim()}" no es un modo válido. Valores válidos: ${CODEGRAPH_MODES.join(', ')}.`);
+      process.exit(1);
+    }
+  }
+
   const targetPath = isGlobal
     ? path.join(os.homedir(), '.refacil-sdd-ai', 'config.yaml')
     : path.join(projectRoot, 'refacil-sdd', 'config.yaml');
@@ -707,6 +838,9 @@ function cmdWriteConfig(argv, projectRoot) {
   if (rawArtifactLanguage !== undefined) {
     merged.artifactLanguage = rawArtifactLanguage.trim();
   }
+  if (rawCodegraph !== undefined) {
+    merged.codegraphMode = rawCodegraph.trim();
+  }
 
   // CA-03: no-op when all provided keys already match existing config (semantic comparison)
   const isNoOp = Object.keys(existing).length > 0 &&
@@ -714,7 +848,8 @@ function cmdWriteConfig(argv, projectRoot) {
     (protectedBranchesList === undefined ||
       (Array.isArray(existing.protectedBranches) &&
        JSON.stringify(existing.protectedBranches.slice().sort()) === JSON.stringify(protectedBranchesList.slice().sort()))) &&
-    (rawArtifactLanguage === undefined || existing.artifactLanguage === rawArtifactLanguage.trim());
+    (rawArtifactLanguage === undefined || existing.artifactLanguage === rawArtifactLanguage.trim()) &&
+    (rawCodegraph === undefined || existing.codegraphMode === rawCodegraph.trim());
   if (isNoOp) {
     console.log(`Sin cambios: ${targetPath} ya tiene los valores indicados.`);
     process.exit(0);
@@ -730,14 +865,234 @@ function cmdWriteConfig(argv, projectRoot) {
   console.log(`Configuración escrita en ${targetPath} (nivel: ${level})`);
 }
 
+function cmdTestScope(argv, projectRoot) {
+  const args = parseArgs(argv);
+  const wantJson = args.json === true;
+
+  const filesRaw = args.files || '';
+  const stackHint = args.stack || undefined;
+  const baselineCmd = args.baseline || '';
+  // Use the already-resolved projectRoot from handleSdd (via findProjectRoot()) so
+  // the CLI works correctly when invoked from a subdirectory within the monorepo.
+  const root = projectRoot || process.cwd();
+
+  // Parse CSV files — empty string or missing → empty array (CR-04: never fail on empty)
+  const files = filesRaw
+    ? filesRaw.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  const { testScope } = require('../test-scope');
+  const result = testScope({ files, stack: stackHint, baseline: baselineCmd, projectRoot: root });
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+  } else {
+    console.log(`testCommand: ${result.testCommand}`);
+    console.log(`files: ${result.files.join(', ') || '(none)'}`);
+    console.log(`fallback: ${result.fallback}`);
+    if (result.fallbackReason) console.log(`fallbackReason: ${result.fallbackReason}`);
+  }
+  // Always exit 0 (CR-04)
+  process.exit(0);
+}
+
+function cmdStats(argv, projectRoot) {
+  const args = parseArgs(argv);
+  const rawName = args._positional[0];
+  const wantJson = args.json === true;
+
+  if (!rawName) {
+    console.error('Uso: refacil-sdd-ai sdd stats <nombre-cambio> [--json]');
+    process.exit(1);
+  }
+
+  autoMigrateOpenspec(projectRoot);
+  const resolved = resolveExistingChangeName(projectRoot, rawName);
+  if (!resolved.ok) {
+    console.error(resolved.reason);
+    process.exit(1);
+  }
+  const name = resolved.name;
+
+  let changeDir = path.join(projectRoot, 'refacil-sdd', 'changes', name);
+  let isArchived = false;
+  let archivedDate = null;
+
+  if (!fs.existsSync(changeDir)) {
+    // Fallback: try to find in archive
+    const archivedPath = resolveArchivedChangeName(projectRoot, name);
+    if (archivedPath) {
+      changeDir = archivedPath;
+      isArchived = true;
+      // Extract YYYY-MM-DD from the directory basename
+      const baseName = path.basename(archivedPath);
+      const dateMatch = baseName.match(/^(\d{4}-\d{2}-\d{2})-/);
+      archivedDate = dateMatch ? dateMatch[1] : null;
+    } else {
+      console.error(`No existe el cambio '${name}' en refacil-sdd/changes/${name}/ ni en el archivo.`);
+      process.exit(1);
+    }
+  }
+
+  // --- Read memory.yaml ---
+  const memoryPath = path.join(changeDir, 'memory.yaml');
+  let memory = {};
+  if (fs.existsSync(memoryPath)) {
+    try {
+      memory = parseYaml(fs.readFileSync(memoryPath, 'utf8')) || {};
+    } catch (_) {
+      memory = {};
+    }
+  }
+  const testCommand = memory.testCommand || memory.commandsRun || null;
+  const lastStep = memory.lastStep || null;
+  const criteriaRun = Array.isArray(memory.criteriaRun) ? memory.criteriaRun : [];
+
+  // --- Read .review-passed ---
+  const reviewPassedPath = path.join(changeDir, '.review-passed');
+  let reviewDate = null;
+  let reviewVerdict = null;
+  let reviewFailCount = 0;
+  if (fs.existsSync(reviewPassedPath)) {
+    try {
+      const rp = JSON.parse(fs.readFileSync(reviewPassedPath, 'utf8'));
+      reviewDate = rp.date || null;
+      reviewVerdict = rp.verdict || null;
+      reviewFailCount = rp.failCount || 0;
+    } catch (_) {}
+  }
+
+  // --- Determine change start date from proposal.md mtime (fallback: summary.md) ---
+  const proposalPath = path.join(changeDir, 'proposal.md');
+  let startDate = null;
+  if (fs.existsSync(proposalPath)) {
+    try {
+      const stat = fs.statSync(proposalPath);
+      startDate = stat.mtime;
+    } catch (_) {}
+  }
+  if (!startDate) {
+    const summaryPath = path.join(changeDir, 'summary.md');
+    if (fs.existsSync(summaryPath)) {
+      try {
+        const stat = fs.statSync(summaryPath);
+        startDate = stat.mtime;
+      } catch (_) {}
+    }
+  }
+
+  // --- Read compact.log filtered by change period ---
+  let compactStats = { totalRewrites: 0, totalSaved: 0, totalAlreadyCompact: 0, totalAlreadyCompactPotential: 0, totalEvents: 0 };
+  try {
+    const compactTelemetry = require('../compact/telemetry');
+    const allCompact = compactTelemetry.readLog ? compactTelemetry.readLog() : [];
+    const filtered = startDate ? allCompact.filter((e) => e.ts && new Date(e.ts) >= startDate) : allCompact;
+    let totalRewrites = 0, totalSaved = 0, totalAlreadyCompact = 0, totalAlreadyCompactPotential = 0;
+    for (const e of filtered) {
+      const evType = e.eventType || 'hook_rewrite';
+      if (evType === 'already_compact') {
+        totalAlreadyCompact++;
+        totalAlreadyCompactPotential += e.savedTokensEst || 0;
+      } else {
+        totalRewrites++;
+        totalSaved += e.savedTokensEst || 0;
+      }
+    }
+    compactStats = { totalRewrites, totalSaved, totalAlreadyCompact, totalAlreadyCompactPotential, totalEvents: filtered.length };
+  } catch (_) {}
+
+  // --- Read codegraph.log filtered by change period ---
+  let codegraphStats = { totalEvents: 0, totalToolCalls: 0, totalTokensSaved: 0 };
+  try {
+    const cgTelemetry = require('../codegraph-telemetry');
+    const allCg = cgTelemetry.readLog ? cgTelemetry.readLog() : [];
+    const filtered = startDate ? allCg.filter((e) => e.ts && new Date(e.ts) >= startDate) : allCg;
+    let totalEvents = 0, totalToolCalls = 0, totalTokensSaved = 0;
+    for (const e of filtered) {
+      totalEvents++;
+      totalToolCalls += e.toolCallsCount || 0;
+      totalTokensSaved += e.estimatedTokensSaved || 0;
+    }
+    codegraphStats = { totalEvents, totalToolCalls, totalTokensSaved };
+  } catch (_) {}
+
+  // --- Build stats object ---
+  const statsObj = {
+    changeName: name,
+    isArchived,
+    archivedDate,
+    startDate: startDate ? startDate.toISOString() : null,
+    memory: {
+      testCommand: testCommand || null,
+      lastStep: lastStep || null,
+      criteriaRun,
+    },
+    review: {
+      passed: reviewDate !== null,
+      verdict: reviewVerdict,
+      date: reviewDate,
+      failCount: reviewFailCount,
+    },
+    compact: {
+      eventsInPeriod: compactStats.totalEvents,
+      rewrites: compactStats.totalRewrites,
+      estimatedTokensSavedByRewrites: compactStats.totalSaved,
+      alreadyCompact: compactStats.totalAlreadyCompact,
+      estimatedTokensSavedAlreadyCompact: compactStats.totalAlreadyCompactPotential,
+    },
+    codegraph: {
+      eventsInPeriod: codegraphStats.totalEvents,
+      totalToolCalls: codegraphStats.totalToolCalls,
+      estimatedTokensSaved: codegraphStats.totalTokensSaved,
+    },
+  };
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(statsObj) + '\n');
+    return;
+  }
+
+  // --- Tabular output ---
+  const pad = (s, n) => String(s).padEnd(n);
+  const noDataLabel = isArchived ? '(archivado)' : '(sin datos)';
+  console.log('');
+  console.log(`  Stats del cambio: ${name}${isArchived && archivedDate ? `  [archivado el ${archivedDate}]` : ""}`);
+  if (startDate) console.log(`  Inicio estimado:  ${startDate.toISOString().slice(0, 10)}`);
+  console.log('');
+  console.log('  Memory');
+  console.log(`    ${pad('lastStep', 20)} ${lastStep || noDataLabel}`);
+  console.log(`    ${pad('criteriaRun', 20)} ${criteriaRun.length > 0 ? criteriaRun.join(', ') : noDataLabel}`);
+  console.log(`    ${pad('testCommand', 20)} ${testCommand || noDataLabel}`);
+  console.log('');
+  console.log('  Review');
+  console.log(`    ${pad('passed', 20)} ${reviewDate !== null ? 'Si' : 'No'}`);
+  if (reviewVerdict) console.log(`    ${pad('verdict', 20)} ${reviewVerdict}`);
+  if (reviewDate) console.log(`    ${pad('date', 20)} ${reviewDate}`);
+  if (reviewDate) console.log(`    ${pad('failCount', 20)} ${reviewFailCount}`);
+  console.log('');
+  console.log('  Compact telemetry (periodo del cambio)');
+  console.log(`    ${pad('eventos', 20)} ${compactStats.totalEvents}`);
+  console.log(`    ${pad('rewrites', 20)} ${compactStats.totalRewrites}`);
+  console.log(`    ${pad('tokens ahorrados', 20)} ${compactStats.totalSaved}`);
+  console.log('');
+  console.log('  CodeGraph telemetry (periodo del cambio)');
+  console.log(`    ${pad('eventos', 20)} ${codegraphStats.totalEvents}`);
+  console.log(`    ${pad('tool calls', 20)} ${codegraphStats.totalToolCalls}`);
+  console.log(`    ${pad('tokens ahorrados', 20)} ${codegraphStats.totalTokensSaved}`);
+  console.log('');
+}
+
 function sddHelp() {
   console.log(`
   refacil-sdd-ai sdd — Gestión de artefactos SDD-AI
 
   Subcomandos:
     sdd new-change <nombre>            Crea un nuevo cambio con los 4 artefactos scaffold
-    sdd archive <nombre>               Archiva un cambio completado a refacil-sdd/changes/archive/
-    sdd list [--json]                  Lista cambios activos con estado de review
+    sdd sync-spec <nombre>             Sincroniza specs del change a refacil-sdd/specs/<nombre>/spec.md
+                                         (mismo idioma que los artefactos; sin traducción)
+      [--from-archive]                 Lee el change desde refacil-sdd/changes/archive/*-<nombre>/
+    sdd archive <nombre>               Archiva un cambio (sync-spec automático + mueve a archive/)
+    sdd list [--json] [--include-archived]  Lista cambios activos con estado de review
     sdd status <nombre> [--json]       Muestra estado de artefactos y tasks de un cambio
     sdd mark-reviewed <nombre>         Escribe .review-passed con veredicto y resumen
       --verdict <v>                      Veredicto (ej: approved, approved-with-notes, rejected)
@@ -769,11 +1124,20 @@ function sddHelp() {
       [--base-branch <branch>]           Rama base para nuevos cambios
       [--protected-branches <csv>]       Ramas protegidas (separadas por coma)
       [--artifact-language <language>]   Idioma para los artefactos SDD generados (english, spanish)
+    sdd stats <nombre> [--json]        Muestra estadísticas del cambio: memoria, review,
+                                         compact telemetry y CodeGraph en el periodo del cambio
+    sdd test-scope                     Resolves scoped test files for the given source files
+      --files <csv>                      Comma-separated source file paths to scope tests for
+      [--stack <name>]                   Stack hint (node, python, go, rust, java, dotnet)
+      [--baseline <cmd>]                 Fallback test command when no test files are found
+      [--json]                           Output result as JSON (testCommand, files, fallback, fallbackReason)
+                                         Always exits 0.
 
   Notas:
     - Los nombres de cambio deben empezar con minúscula y usar solo [a-z0-9-]
     - Si existe openspec/ y no existe refacil-sdd/, se migra automáticamente
-    - sdd archive elimina memory.yaml automáticamente antes de mover el cambio
+    - sdd archive ejecuta sync-spec antes de mover (preserva idioma de CA/CR del change)
+    - sdd archive mueve el cambio completo (incluyendo memory.yaml si existe) al directorio archive/
   `);
 }
 
@@ -790,6 +1154,9 @@ function handleSdd(sub, argv, projectRoot) {
     case 'archive':
       cmdArchive(args, root);
       break;
+    case 'sync-spec':
+      cmdSyncSpec(args, root);
+      break;
     case 'list':
       cmdList(args, root);
       break;
@@ -823,10 +1190,28 @@ function handleSdd(sub, argv, projectRoot) {
     case 'write-config':
       cmdWriteConfig(args, root);
       break;
+    case 'stats':
+      cmdStats(args, root);
+      break;
+    case 'test-scope':
+      cmdTestScope(args, root);
+      break;
     default:
       sddHelp();
       process.exit(1);
   }
 }
 
-module.exports = { handleSdd, parseArgs, autoMigrateOpenspec, validateChangeName, resolveExistingChangeName, findProjectRoot, cmdWriteConfig };
+module.exports = {
+  handleSdd,
+  parseArgs,
+  autoMigrateOpenspec,
+  validateChangeName,
+  isBugFixChangeName,
+  resolveExistingChangeName,
+  resolveArchivedChangeName,
+  findProjectRoot,
+  cmdWriteConfig,
+  cmdStats,
+  cmdTestScope,
+};