refacil-sdd-ai 5.2.3 → 5.3.1

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.' };
@@ -137,6 +183,88 @@ function serializeMemoryYaml(obj) {
   return lines.join('\n') + '\n';
 }
 
+// --- State tracking ---
+
+const VALID_STATES = [
+  'proposed',
+  'approved',
+  'apply-in-progress',
+  'applied',
+  'tested',
+  'verified',
+  'reviewed',
+  'archived',
+];
+
+/**
+ * Infers the current state of a change from its artifacts when no explicit
+ * currentState is stored in memory. Retrocompatible — never writes to disk.
+ *
+ * Priority (descending):
+ *  1. .review-passed exists                                   → 'reviewed'
+ *  2. lastStep === 'verify' or 'verified'                    → 'verified'
+ *  3. lastStep === 'test'                                     → 'tested'
+ *  4. lastStep === 'apply'                                    → 'applied'
+ *  5. tasks.md has at least one [x] and lastStep is absent   → 'apply-in-progress'
+ *  6. only proposal.md exists                                → 'proposed'
+ *  7. none of the above                                       → 'unknown'
+ *
+ * NOTE — 'approved' is intentionally absent from this table.
+ * There is no artifact signal that distinguishes an approved proposal from a
+ * merely proposed one: both have proposal.md, specs.md, design.md, tasks.md.
+ * 'approved' is set exclusively via `set-memory --state approved --actor propose-skill`
+ * when the human approves the artifacts in /refacil:propose Step 4.
+ * Inference can only detect 'proposed' (artifact exists but no explicit state recorded).
+ *
+ * @param {string} changeDir  Absolute path to the change directory.
+ * @param {object} memory     Parsed memory.yaml object (may be empty).
+ * @returns {{ currentState: string, inferred: boolean }}
+ */
+function inferCurrentState(changeDir, memory) {
+  // 1. .review-passed
+  if (fs.existsSync(path.join(changeDir, '.review-passed'))) {
+    return { currentState: 'reviewed', inferred: true };
+  }
+
+  const lastStep = memory.lastStep || null;
+
+  // 2. lastStep verify/verified
+  if (lastStep === 'verify' || lastStep === 'verified') {
+    return { currentState: 'verified', inferred: true };
+  }
+
+  // 3. lastStep test
+  if (lastStep === 'test') {
+    return { currentState: 'tested', inferred: true };
+  }
+
+  // 4. lastStep apply
+  if (lastStep === 'apply') {
+    return { currentState: 'applied', inferred: true };
+  }
+
+  // 5. tasks.md has at least one [x] and lastStep absent
+  const tasksPath = path.join(changeDir, 'tasks.md');
+  if (!lastStep && fs.existsSync(tasksPath)) {
+    try {
+      const tasksContent = fs.readFileSync(tasksPath, 'utf8');
+      if (/^- \[x\]/m.test(tasksContent)) {
+        return { currentState: 'apply-in-progress', inferred: true };
+      }
+    } catch (_) {
+      // Unexpected read error (e.g. permission denied): swallow and fall through
+      // to the proposal.md check so inference still produces a useful result.
+    }
+  }
+
+  // 6. only proposal.md exists (no design, tasks, specs)
+  if (fs.existsSync(path.join(changeDir, 'proposal.md'))) {
+    return { currentState: 'proposed', inferred: true };
+  }
+
+  return { currentState: 'unknown', inferred: true };
+}
+
 // --- Subcomandos ---
 
 function cmdValidateName(argv) {
@@ -179,6 +307,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 +363,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 +386,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);
 
@@ -232,7 +402,7 @@ function cmdSetMemory(argv, projectRoot) {
   const rawName = args._positional[0];
 
   if (!rawName) {
-    console.error('Uso: refacil-sdd-ai sdd set-memory <nombre-cambio> [--last-step <value>] [--stack-detected <value>] [--touched-files <csv>] [--commands-run <value>] [--criteria-run <csv>]');
+    console.error('Uso: refacil-sdd-ai sdd set-memory <nombre-cambio> [--last-step <value>] [--stack-detected <value>] [--touched-files <csv>] [--commands-run <value>] [--criteria-run <csv>] [--state <estado>] [--actor <nombre>]');
     process.exit(1);
   }
 
@@ -252,10 +422,30 @@ function cmdSetMemory(argv, projectRoot) {
     process.exit(1);
   }
 
+  // Validate --state before touching any file (CR-01: exit 1 without modifying file)
+  if (args['state'] !== undefined) {
+    const stateValue = args['state'];
+    // CR-02: empty string or bare flag (parsed as boolean true) → explicit empty-state error
+    if (stateValue === '' || stateValue === true) {
+      console.error('set-memory: el estado no puede estar vacío');
+      process.exit(1);
+    }
+    if (!VALID_STATES.includes(stateValue)) {
+      console.error(`set-memory: estado inválido '${stateValue}'. Estados válidos: ${VALID_STATES.join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  // Validate --actor: pipe character would corrupt the stateHistory pipe format
+  if (args['actor'] !== undefined && String(args['actor']).includes('|')) {
+    console.error("set-memory: --actor no puede contener el carácter '|'");
+    process.exit(1);
+  }
+
   // Require at least one field flag
-  const knownFlags = ['last-step', 'stack-detected', 'touched-files', 'commands-run', 'criteria-run'];
+  const knownFlags = ['last-step', 'stack-detected', 'touched-files', 'commands-run', 'criteria-run', 'state', 'actor'];
   if (!knownFlags.some((f) => args[f] !== undefined)) {
-    console.error('set-memory: debe especificar al menos un campo (--last-step, --stack-detected, --touched-files, --commands-run, --criteria-run)');
+    console.error('set-memory: debe especificar al menos un campo (--last-step, --stack-detected, --touched-files, --commands-run, --criteria-run, --state, --actor)');
     process.exit(1);
   }
 
@@ -282,6 +472,18 @@ function cmdSetMemory(argv, projectRoot) {
     existing['criteriaRun'] = args['criteria-run'].split(',').map((s) => s.trim()).filter(Boolean);
   }
 
+  // State tracking (T-01)
+  if (args['state'] !== undefined) {
+    const actor = args['actor'] !== undefined ? String(args['actor']) : 'cli';
+    existing['currentState'] = args['state'];
+    const iso = new Date().toISOString();
+    const entry = `${args['state']}|${iso}|${actor}`;
+    if (!Array.isArray(existing['stateHistory'])) {
+      existing['stateHistory'] = [];
+    }
+    existing['stateHistory'].push(entry);
+  }
+
   fs.writeFileSync(memoryPath, serializeMemoryYaml(existing), 'utf8');
   console.log(`memory.yaml actualizado para '${name}'`);
 }
@@ -389,6 +591,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 +613,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 +695,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,16 +717,46 @@ 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,
   };
 
+  // Read memory for currentState / lastStep / touchedFiles
+  const memoryPath = path.join(changeDir, 'memory.yaml');
+  let memory = {};
+  if (fs.existsSync(memoryPath)) {
+    try {
+      memory = parseYaml(fs.readFileSync(memoryPath, 'utf8')) || {};
+    } catch (_) {
+      memory = {};
+    }
+  }
+
+  // Resolve currentState: explicit from memory or inferred
+  let currentState = null;
+  let stateInferred = false;
+  if (memory.currentState) {
+    currentState = memory.currentState;
+    stateInferred = false;
+  } else {
+    const inferred = inferCurrentState(changeDir, memory);
+    currentState = inferred.currentState;
+    stateInferred = inferred.inferred;
+  }
+
+  const lastStep = memory.lastStep || null;
+  const touchedFiles = Array.isArray(memory.touchedFiles) ? memory.touchedFiles : [];
+
   const status = {
     name,
     artifacts,
     tasks: taskStats,
     reviewPassed,
     ready,
+    currentState,
+    stateInferred,
+    lastStep,
+    touchedFiles,
   };
 
   if (wantJson) {
@@ -514,6 +776,11 @@ function cmdStatus(argv, projectRoot) {
     console.log('');
     console.log(`  Review aprobado: ${reviewPassed ? 'Si' : 'No'}`);
     console.log('');
+    console.log('  Estado:');
+    console.log(`    currentState: ${currentState}${stateInferred ? ' (inferido)' : ''}`);
+    if (lastStep) console.log(`    lastStep:     ${lastStep}`);
+    if (touchedFiles.length > 0) console.log(`    touchedFiles: ${touchedFiles.join(', ')}`);
+    console.log('');
     console.log('  Listo para:');
     console.log(`    apply:   ${ready.forApply ? 'Si' : 'No'}`);
     console.log(`    archive: ${ready.forArchive ? 'Si' : 'No'}`);
@@ -653,11 +920,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 +957,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 +987,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 +997,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 +1014,249 @@ 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 : [];
+
+  // Resolve currentState for stats
+  let statsCurrentState = null;
+  let statsStateInferred = false;
+  if (memory.currentState) {
+    statsCurrentState = memory.currentState;
+    statsStateInferred = false;
+  } else {
+    const inferred = inferCurrentState(changeDir, memory);
+    statsCurrentState = inferred.currentState;
+    statsStateInferred = inferred.inferred;
+  }
+
+  // --- 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,
+      currentState: statsCurrentState,
+      stateInferred: statsStateInferred,
+    },
+    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('currentState', 20)} ${statsCurrentState || noDataLabel}${statsStateInferred ? ' (inferido)' : ''}`);
+  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)
@@ -755,6 +1274,8 @@ function sddHelp() {
       [--touched-files <csv>]            Archivos modificados (separados por coma)
       [--commands-run <value>]           Comando de test ejecutado
       [--criteria-run <csv>]             Criterios CA/CR ejecutados (separados por coma)
+      [--state <estado>]                 Estado del ciclo SDD-AI (proposed, approved, apply-in-progress, applied, tested, verified, reviewed, archived)
+      [--actor <nombre>]                 Actor que origina el cambio de estado (default: cli)
     sdd get-memory <nombre>            Lee memory.yaml del cambio
       [--json]                           Salida en JSON (por defecto: YAML raw)
     sdd set-review-fails <nombre>      Escribe .review-last-fails.json con archivos fallidos
@@ -769,11 +1290,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 (incluyendo currentState),
+                                         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 +1320,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 +1356,30 @@ 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,
+  VALID_STATES,
+  inferCurrentState,
+};