siesa-agents 2.1.82 → 2.1.84

package/bin/folder-mappings.js

@@ -0,0 +1,79 @@
+// folder-mappings.js — Single source of truth for the source→target mapping used by the
+// installer (install.js) and the publish helpers (prepare-publish.js / restore-folders.js).
+//
+// Background — the dual-mirror pattern this repo uses:
+//   Every folder that ships with the npm package exists twice in the dev tree:
+//     - The "dotted/underscored" version used by the dev workflow:
+//         `.claude/`, `.github/`, `.gemini/`, `.resources/`, `.mcp.json`, `.vscode/`,
+//         `_bmad/`, `_siesa-agents/`
+//     - The "flat" version that is what npm publish actually packages and ships:
+//         `claude/`, `github/`, `gemini/`, `resources/`, `mcp.json`, `vscode/`,
+//         `bmad/`, `siesa-agents/`
+//   When you edit anything under `.claude/skills/`, you must mirror the change into
+//   `claude/skills/`. The installer reads from the flat (tarball) names and writes to the
+//   dotted (user project) names.
+//
+// Why both? npm's `files` array historically had quirks with dot-prefixed entries
+// (`.github/` would sometimes ship, sometimes not, depending on npm version and registry
+// rules). Keeping a flat copy guarantees the file ships, while keeping the dotted copy
+// keeps the dev workflow honest (`.claude/` is what Claude Code reads, `.github/` is what
+// GitHub Actions reads).
+//
+// Three views of the same data:
+//   - installerMappings()   used by bin/install.js: { source = tarball name,
+//                           target = user project name }
+//   - publishRenames()      used by bin/prepare-publish.js. Currently empty — see comment
+//                           on the FOLDERS array.
+//   - restoreRenames()      used by bin/restore-folders.js. Currently empty — see comment.
+//
+// Add new folders here and the rest of the pipeline picks them up. If a new folder needs
+// pre-publish renaming (only when there's no flat mirror in dev), add a `devSource`.
+
+'use strict';
+
+// Each entry describes one shipping unit:
+//   - tarball:     name inside the published npm tarball (no leading `.` or `_`)
+//   - userProject: name in the user's project after `npx siesa-agents`
+//   - devSource:   optional — pre-publish rename source. Leave it `null` when the dev tree
+//                  already maintains both the dotted AND the flat copy (current strategy
+//                  for every folder shipped today). Only set it if you want the publish
+//                  pipeline to physically rename the dev folder before `npm publish`.
+const FOLDERS = [
+  { tarball: 'bmad',          userProject: '_bmad',          devSource: null },
+  { tarball: 'siesa-agents',  userProject: '_siesa-agents',  devSource: null },
+  { tarball: 'vscode',        userProject: '.vscode',        devSource: null },
+  { tarball: 'github',        userProject: '.github',        devSource: null },
+  { tarball: 'claude',        userProject: '.claude',        devSource: null },
+  { tarball: 'gemini',        userProject: '.gemini',        devSource: null },
+  { tarball: 'resources',     userProject: '.resources',     devSource: null },
+  { tarball: 'mcp.json',      userProject: '.mcp.json',      devSource: null },
+];
+
+// Shape expected by install.js: { source, target } where source is the tarball name and
+// target is what to call it in the user's project.
+function installerMappings() {
+  return FOLDERS.map(f => ({ source: f.tarball, target: f.userProject }));
+}
+
+// Shape expected by prepare-publish.js: { from, to } where from is the dev name and to is
+// the tarball name. Empty when the dev tree already maintains dual-mirror copies.
+function publishRenames() {
+  return FOLDERS
+    .filter(f => f.devSource && f.devSource !== f.tarball)
+    .map(f => ({ from: f.devSource, to: f.tarball }));
+}
+
+// Inverse of publishRenames: restore tarball names back to dev names. Empty in the
+// dual-mirror strategy.
+function restoreRenames() {
+  return FOLDERS
+    .filter(f => f.devSource && f.devSource !== f.tarball)
+    .map(f => ({ from: f.tarball, to: f.devSource }));
+}
+
+module.exports = {
+  FOLDERS,
+  installerMappings,
+  publishRenames,
+  restoreRenames,
+};

package/bin/install.js

@@ -2,27 +2,91 @@
 
 const fs = require('fs-extra');
 const path = require('path');
-const { sourceMapsEnabled } = require('process');
-const readline = require('readline');
 const { execSync } = require('child_process');
+const { installerMappings } = require('./folder-mappings');
+
+// @clack/prompts es ESM-only, así que desde este install.js CJS lo cargamos con
+// dynamic `import()`. Cachéamos la promesa para que la primera carga pague el
+// costo de resolución y las siguientes sean instantáneas.
+let _clackPromise = null;
+function loadClack() {
+  if (!_clackPromise) {
+    _clackPromise = import('@clack/prompts');
+  }
+  return _clackPromise;
+}
+
+// En Windows oculta/des-oculta una carpeta o archivo (atributo +h/-h). Sirve para
+// que las carpetas de staging `.sa-new`/`.sa-old` no aparezcan en el explorador
+// durante el breve lapso en que existen — verlas crearse y borrarse se ve raro.
+// Best-effort: si `attrib` falla no pasa nada (es puramente cosmético). No-op
+// fuera de Windows (en Unix el prefijo `.` ya las oculta en la mayoría de FMs).
+function setHidden(targetPath, hidden) {
+  if (process.platform !== 'win32') return;
+  try {
+    execSync(`attrib ${hidden ? '+h' : '-h'} "${targetPath}"`, { stdio: 'ignore' });
+  } catch (_) { /* cosmético: ignorar */ }
+}
+
+// Maneja la cancelación de un prompt clack (Ctrl+C / Esc). Sale limpio con
+// código 0 — no es un error, el usuario explícitamente abortó.
+async function bailIfCancel(value) {
+  const clack = await loadClack();
+  if (clack.isCancel(value)) {
+    clack.cancel('Instalación cancelada por el usuario.');
+    process.exit(0);
+  }
+  return value;
+}
+
+// Parse argumentos CLI básicos. Soporta:
+//   --yes / -y           Modo no-interactivo: usa defaults sensatos en cualquier prompt
+//                        en vez de leer de stdin. Defaults: "hacer backup de modificados"
+//                        (opción 2) y "no hay repo remoto" (opción 2). También se activa
+//                        automáticamente cuando stdin no es un TTY (CI, pipes).
+//   --version            Imprime la versión del paquete y sale.
+//   --help / -h          Imprime ayuda breve y sale.
+function parseCliArgs(argv) {
+  const out = { yes: false, version: false, help: false };
+  for (const a of argv) {
+    if (a === '--yes' || a === '-y') out.yes = true;
+    else if (a === '--version') out.version = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+// Deep-merge de dos objetos JSON. Source gana en conflictos; los arrays se
+// reemplazan completos (no se hace merge elemento-a-elemento). Pensado para
+// `.mcp.json`: los MCPs que el usuario agregó (no existen en el paquete) sobreviven
+// al update mientras los nativos se actualizan a la versión del paquete.
+function deepMergeJson(target, source) {
+  if (source === null || typeof source !== 'object') return source;
+  if (target === null || typeof target !== 'object') return source;
+  if (Array.isArray(source) || Array.isArray(target)) return source;
+  const out = { ...target };
+  for (const key of Object.keys(source)) {
+    out[key] = deepMergeJson(target[key], source[key]);
+  }
+  return out;
+}
 
 class SiesaBmadInstaller {
-  constructor() {
-    // Definir las carpetas primero (nombres en el paquete vs nombres finales)
-    this.folderMappings = [
-      { source: 'bmad', target: '_bmad' },
-      { source: 'siesa-agents', target: '_siesa-agents' },
-      { source: 'vscode', target: '.vscode' },
-      { source: 'github', target: '.github' },
-      { source: 'claude', target: '.claude' },
-      { source: 'gemini', target: '.gemini' },
-      { source: 'resources', target: '.resources' },
-      { source: 'mcp.json', target: '.mcp.json' }
-    ];
-    
-    // Lista de archivos que se preservan automáticamente (no se crean backups)
+  constructor(cliArgs = {}) {
+    // Definir las carpetas primero (nombres en el paquete vs nombres finales).
+    // Source of truth: bin/folder-mappings.js
+    this.folderMappings = installerMappings();
+
+    // Archivos que el instalador PRESERVA: no se sobrescriben si ya existen, no se
+    // reportan como "modificados" y no se les hace backup. El usuario los personaliza
+    // localmente y son suyos.
+    //   - data/technical-preferences.md → preferencias del usuario.
+    //   - settings.json → `.vscode/settings.json` (la única carpeta del paquete con
+    //     un settings.json en su raíz es `.vscode`, así que el match es inequívoco).
+    //     El usuario ajusta su editor; el instalador no debe pisarlo ni molestar.
     this.ignoredFiles = [
-      'data/technical-preferences.md'
+      'data/technical-preferences.md',
+      'settings.json'
     ];
 
     // Directorios base que se deben crear siempre durante la instalación
@@ -33,9 +97,14 @@ class SiesaBmadInstaller {
     this.targetDir = process.cwd();
     // Intentar múltiples ubicaciones posibles para el paquete
     this.packageDir = this.findPackageDir();
-    
+
     // Almacenamiento temporal para contenido de archivos ignorados
     this.preservedContent = new Map();
+
+    // Flag no-interactivo: opt-in via --yes/-y o auto-detectado cuando stdin no es TTY
+    // (típicamente CI, npx detrás de pipes, scripts automatizados). Si está activo, los
+    // prompts usan defaults en vez de bloquearse esperando input.
+    this.nonInteractive = Boolean(cliArgs.yes) || !process.stdin.isTTY;
   }
   
 
@@ -121,27 +190,39 @@ class SiesaBmadInstaller {
   }
 
   async promptHasRepository() {
-    console.log('\n¿Tienes un repositorio remoto?');
-    console.log('1. Sí');
-    console.log('2. No, parametrizar manual después');
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      rl.question('\nElige una opción (1 o 2): ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    if (this.nonInteractive) {
+      console.log('\n  (modo no-interactivo: sin repositorio remoto)');
+      return '2';
+    }
+
+    const clack = await loadClack();
+    const answer = await clack.select({
+      message: '¿Tienes un repositorio remoto que quieras vincular ahora?',
+      options: [
+        { value: '2', label: 'No, lo configuraré después', hint: 'recomendado si todavía no creaste el repo' },
+        { value: '1', label: 'Sí, tengo URL del repo remoto' },
+      ],
+      initialValue: '2',
     });
+    return bailIfCancel(answer);
   }
 
   async promptRepositoryUrl() {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      rl.question('Ingresa la URL del repositorio: ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    if (this.nonInteractive) {
+      // En modo no-interactivo nunca deberíamos llegar aquí (promptHasRepository
+      // devuelve '2'), pero por defensa devolvemos cadena vacía.
+      return '';
+    }
+    const clack = await loadClack();
+    const answer = await clack.text({
+      message: 'URL del repositorio',
+      placeholder: 'https://github.com/<org>/<repo>.git',
+      validate: (value) => {
+        if (!value || value.trim() === '') return 'La URL no puede estar vacía';
+      },
     });
+    const checked = await bailIfCancel(answer);
+    return checked.trim();
   }
 
   async installGitignore() {
@@ -149,7 +230,9 @@ class SiesaBmadInstaller {
     const entries = [
       'node_modules/',
       '.claude/commands/get-features/oauth-config.json',
-      '.claude/commands/get-features/tokens.json'
+      '.claude/commands/get-features/tokens.json',
+      '.vscode/settings.json',
+      '.claude.json'
     ];
 
     let content = entries.join('\n') + '\n';
@@ -268,6 +351,13 @@ class SiesaBmadInstaller {
     const modifiedFiles = [];
 
     for (const mapping of this.folderMappings) {
+      // .mcp.json no entra en la detección de modificaciones: se gestiona con
+      // deep-merge JSON en performAtomicUpdate / copyWithBackupPreservation, que
+      // preserva los MCPs personalizados del usuario y actualiza los nativos.
+      // Marcarlo como "modificado" forzaría el flujo backup-y-reemplaza y
+      // destruiría los MCPs custom.
+      if (mapping.target === '.mcp.json') continue;
+
       const sourcePath = path.join(this.packageDir, mapping.source);
       const targetPath = path.join(this.targetDir, mapping.target);
 
@@ -284,9 +374,13 @@ class SiesaBmadInstaller {
 
         if (fs.existsSync(targetFile)) {
           try {
-            // Comparar contenido de archivos
-            const sourceContent = await fs.readFile(sourceFile, 'utf8');
-            const targetContent = await fs.readFile(targetFile, 'utf8');
+            // Comparar contenido normalizando CRLF→LF. Sin esta normalización, en Windows
+            // con `core.autocrlf=true` cualquier archivo de texto cuya copia local fue
+            // checkout con CRLF aparece como "modificado" frente al paquete (que tiene LF),
+            // y el instalador pide backup en cada corrida aunque el usuario no haya tocado
+            // nada.
+            const sourceContent = (await fs.readFile(sourceFile, 'utf8')).replace(/\r\n/g, '\n');
+            const targetContent = (await fs.readFile(targetFile, 'utf8')).replace(/\r\n/g, '\n');
 
             if (sourceContent !== targetContent) {
               modifiedFiles.push({
@@ -297,7 +391,8 @@ class SiesaBmadInstaller {
               });
             }
           } catch (error) {
-            // Si no se puede leer como texto, comparar como buffer (archivos binarios)
+            // Si no se puede leer como texto, comparar como buffer (archivos binarios).
+            // Para binarios la normalización CRLF no aplica.
             const sourceBuffer = await fs.readFile(sourceFile);
             const targetBuffer = await fs.readFile(targetFile);
 
@@ -341,22 +436,26 @@ class SiesaBmadInstaller {
   }
 
   async promptUser(modifiedFiles) {
+    // modifiedFiles solo contiene archivos QUE EXISTEN EN EL PAQUETE y cuyo
+    // contenido difiere del target. Es decir: archivos del paquete (skills nativas,
+    // configs nativas, etc.) que el usuario modificó localmente. Los archivos que
+    // el usuario AGREGÓ y no están en el paquete (skills custom, flows propios,
+    // MCPs adicionales) NO aparecen aquí — se preservan automáticamente en
+    // performAtomicUpdate / copyWithBackupPreservation sin pedir permiso.
+    const nonIgnoredFiles = modifiedFiles.filter(f => !f.is_ignored);
+    if (nonIgnoredFiles.length === 0) return '2';
 
-    const hasNonIgnoredFiles = modifiedFiles.some(file => file.is_ignored == false)
-    if (!hasNonIgnoredFiles) return '2'
-
-    console.log('\n⚠️  Se detectaron archivos modificados:');
+    console.log(`\n⚠️  Detecté ${nonIgnoredFiles.length} archivo(s) del paquete Siesa-Agents que modificaste localmente:`);
 
     // Agrupar por carpeta
     const filesByFolder = {};
-    modifiedFiles.forEach(item => {
+    nonIgnoredFiles.forEach(item => {
       if (!filesByFolder[item.folder]) {
         filesByFolder[item.folder] = [];
       }
       filesByFolder[item.folder].push(item.file);
     });
 
-    // Mostrar archivos modificados por carpeta
     Object.keys(filesByFolder).forEach(folder => {
       console.log(`\n📁 ${folder}:`);
       filesByFolder[folder].forEach(file => {
@@ -364,21 +463,24 @@ class SiesaBmadInstaller {
       });
     });
 
-    console.log('\n¿Qué deseas hacer?');
-    console.log('1. Reemplazar todos los archivos (se perderán las modificaciones)');
-    console.log('2. Hacer backup de archivos modificados (se agregarán con sufijo _bk)');
+    console.log('\nℹ️  Tus skills/flows/MCPs propios (los que NO vienen en el paquete) se');
+    console.log('   preservan automáticamente — no aparecen en la lista de arriba.');
 
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout
-    });
+    if (this.nonInteractive) {
+      console.log('\n  (modo no-interactivo: backup de tus cambios)');
+      return '2';
+    }
 
-    return new Promise((resolve) => {
-      rl.question('\nElige una opción (1 o 2): ', (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
+    const clack = await loadClack();
+    const answer = await clack.select({
+      message: '¿Qué hago con TUS cambios sobre los archivos del paquete?',
+      options: [
+        { value: '2', label: 'Backup y actualizar', hint: 'guarda tus cambios con sufijo _bk + trae la versión del paquete (recomendado)' },
+        { value: '1', label: 'Reemplazar', hint: 'pierdes tus modificaciones — sin backup' },
+      ],
+      initialValue: '2',
     });
+    return bailIfCancel(answer);
   }
 
   async backupModifiedFiles(modifiedFiles) {
@@ -419,22 +521,31 @@ class SiesaBmadInstaller {
 
     // Primer intento: archivo_bk.ext
     const basicBackupPath = path.join(dir, `${name}_bk${ext}`);
-
-    // Si no existe, usar el nombre básico
     if (!fs.existsSync(basicBackupPath)) {
       return basicBackupPath;
     }
 
-    // Si ya existe _bk, crear versión con timestamp
+    // Si ya existe _bk, crear versión con timestamp. Incluimos milisegundos para
+    // evitar colisiones cuando dos backups del mismo archivo ocurren en el mismo
+    // segundo (p.ej. instalador corriendo en bucle / tests). Y por si dos backups
+    // caen en el mismo ms (esencialmente imposible pero defensivo), agregamos un
+    // contador incremental.
     const now = new Date();
     const timestamp = now.getFullYear().toString() +
       (now.getMonth() + 1).toString().padStart(2, '0') +
       now.getDate().toString().padStart(2, '0') + '_' +
       now.getHours().toString().padStart(2, '0') +
       now.getMinutes().toString().padStart(2, '0') +
-      now.getSeconds().toString().padStart(2, '0');
-
-    return path.join(dir, `${name}_bk_${timestamp}${ext}`);
+      now.getSeconds().toString().padStart(2, '0') +
+      now.getMilliseconds().toString().padStart(3, '0');
+
+    let candidate = path.join(dir, `${name}_bk_${timestamp}${ext}`);
+    let counter = 1;
+    while (fs.existsSync(candidate)) {
+      candidate = path.join(dir, `${name}_bk_${timestamp}_${counter}${ext}`);
+      counter++;
+    }
+    return candidate;
   }
 
   async performUpdateWithBackups() {
@@ -454,21 +565,33 @@ class SiesaBmadInstaller {
   async copyWithBackupPreservation(sourcePath, targetPath) {
     // Obtener todos los archivos backup existentes
     const backupFiles = await this.findBackupFiles(targetPath);
-    
-    // Copiar la carpeta preservando technical-preferences.md
-    await fs.copy(sourcePath, targetPath, {
-      overwrite: true,
-      recursive: true,
-      filter: (src) => {
-        const relativePath = path.relative(sourcePath, src);
-        // No sobrescribir archivos ignorados si ya existen
-        if (this.ignoredFiles.includes(relativePath)) {
-          const targetFile = path.join(targetPath, relativePath);
-          return !fs.existsSync(targetFile);
+
+    const sourceIsFile = (await fs.stat(sourcePath)).isFile();
+
+    if (sourceIsFile) {
+      // File mapping (.mcp.json u otros). Para .mcp.json hacemos deep-merge JSON
+      // para preservar MCPs personalizados; para cualquier otro archivo,
+      // copia directa (source-wins).
+      await this.applyFileMapping(sourcePath, targetPath, targetPath);
+    } else {
+      // Folder mapping. fs.copy con overwrite=true sobre el target es un merge:
+      // actualiza archivos que ya existían y agrega los nuevos, dejando intactos
+      // los archivos del target que no aparecen en el source (skills custom,
+      // flujos agregados por el ingeniero, etc.).
+      await fs.copy(sourcePath, targetPath, {
+        overwrite: true,
+        recursive: true,
+        filter: (src) => {
+          const relativePath = path.relative(sourcePath, src);
+          // No sobrescribir archivos ignorados si ya existen
+          if (this.ignoredFiles.includes(relativePath)) {
+            const targetFile = path.join(targetPath, relativePath);
+            return !fs.existsSync(targetFile);
+          }
+          return true;
         }
-        return true;
-      }
-    });
+      });
+    }
 
     // Restaurar los archivos backup
     for (const backupFile of backupFiles) {
@@ -485,6 +608,30 @@ class SiesaBmadInstaller {
     }
   }
 
+  // Aplica un mapping de archivo (no carpeta). Para `.mcp.json` hace deep-merge
+  // JSON con source-wins: actualiza los servidores MCP nativos a la versión del
+  // paquete pero conserva los MCPs adicionales que el usuario haya configurado.
+  // Para cualquier otro archivo, copia directa del source.
+  // El parámetro `outputPath` permite usar este método tanto en el camino atómico
+  // (escribiendo a `<target>.sa-new`) como en el camino con backups (escribiendo
+  // directamente al target).
+  async applyFileMapping(sourcePath, targetPath, outputPath) {
+    const isMcpJson = path.basename(targetPath) === '.mcp.json';
+    if (isMcpJson && fs.existsSync(targetPath)) {
+      try {
+        const sourceJson = JSON.parse(await fs.readFile(sourcePath, 'utf8'));
+        const targetJson = JSON.parse(await fs.readFile(targetPath, 'utf8'));
+        const merged = deepMergeJson(targetJson, sourceJson);
+        await fs.writeFile(outputPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+        console.log('🔀 .mcp.json: merge — MCPs nativos actualizados, MCPs personalizados preservados');
+        return;
+      } catch (err) {
+        console.warn(`⚠️  No se pudo hacer merge de .mcp.json (${err.message}). Se usará la versión del paquete.`);
+      }
+    }
+    await fs.copy(sourcePath, outputPath, { overwrite: true });
+  }
+
   async findBackupFiles(targetPath) {
     if (!fs.existsSync(targetPath)) {
       return [];
@@ -566,23 +713,121 @@ class SiesaBmadInstaller {
     if (hasBackups) {
       await this.performUpdateWithBackups();
     } else {
-      // Si no hay backups, hacer actualización normal (remover y copiar)
-      // Pero primero preservar archivos ignorados
+      // Update atómico con merge:
+      //   1. Staging arranca como CLON del target actual — preserva skills custom
+      //      en .claude/skills/, flujos agregados por el ingeniero, y cualquier
+      //      archivo no nativo que el usuario haya puesto dentro de las carpetas
+      //      del paquete.
+      //   2. Source se sobrepone al staging (actualiza archivos nativos).
+      //   3. Para .mcp.json: deep-merge JSON con source-wins — los MCPs nativos
+      //      se actualizan, los MCPs adicionales del usuario sobreviven.
+      //   4. Swap atómico: target → .sa-old, .sa-new → target, borrar .sa-old.
+      //
+      // El flujo anterior borraba el destino antes de copiar — si el proceso moría
+      // a mitad (Ctrl+C, OOM, crash), el usuario se quedaba sin instalación. Con
+      // el staging, una interrupción deja el target intacto y solo basura en
+      // .sa-new que se limpia en la próxima corrida.
+      //
+      // Trade-off conocido: archivos nativos que el paquete eliminó en una versión
+      // nueva permanecen en el target tras el update — no podemos distinguir
+      // entre "nativo removido en upstream" y "custom del usuario". El usuario
+      // limpia artefactos obsoletos a mano si los detecta.
       await this.preserveIgnoredFiles();
-      
+      await this.performAtomicUpdate();
+      await this.restoreIgnoredFiles();
+    }
+  }
+
+  async performAtomicUpdate() {
+    const STAGING_SUFFIX = '.sa-new';
+    const OLD_SUFFIX = '.sa-old';
+
+    // Phase 1: limpiar restos de runs anteriores que murieron mid-update.
+    for (const mapping of this.folderMappings) {
+      const target = path.join(this.targetDir, mapping.target);
+      for (const suffix of [STAGING_SUFFIX, OLD_SUFFIX]) {
+        const stale = target + suffix;
+        if (fs.existsSync(stale)) {
+          try { await fs.remove(stale); } catch (_) {}
+        }
+      }
+    }
+
+    // Phase 2: stage cada mapping en `<target>.sa-new`.
+    //   - Folder mapping: clonar target actual al staging y después overlay del
+    //     source. fs.copy con overwrite=true es un merge — el clon preserva los
+    //     archivos del usuario (skills custom, MCPs, etc.) y el overlay del
+    //     source actualiza los archivos nativos del paquete.
+    //   - File mapping `.mcp.json`: deep-merge JSON con source-wins (preserva
+    //     MCPs personalizados, actualiza nativos). Otros file mappings: copia
+    //     directa del source.
+    // Si falla cualquier mapping, rollback antes de tocar los targets reales.
+    const staged = [];
+    try {
       for (const mapping of this.folderMappings) {
+        const sourcePath = path.join(this.packageDir, mapping.source);
         const targetPath = path.join(this.targetDir, mapping.target);
+        const stagingPath = targetPath + STAGING_SUFFIX;
 
-        if (fs.existsSync(targetPath)) {
-          await fs.remove(targetPath);
+        if (!fs.existsSync(sourcePath)) {
+          console.warn(`⚠️  ${mapping.source} no encontrado en el paquete`);
+          continue;
         }
+
+        const sourceIsFile = (await fs.stat(sourcePath)).isFile();
+
+        if (sourceIsFile) {
+          await this.applyFileMapping(sourcePath, targetPath, stagingPath);
+        } else {
+          // Clonar target al staging primero (preserva customs), después overlay
+          // del source (actualiza nativos).
+          if (fs.existsSync(targetPath)) {
+            await fs.copy(targetPath, stagingPath, { overwrite: true, recursive: true });
+          }
+          await fs.copy(sourcePath, stagingPath, {
+            overwrite: true,
+            recursive: true,
+            filter: (src) => {
+              const relativePath = path.relative(sourcePath, src);
+              // No sobrescribir archivos ignorados si ya existen en el target real.
+              if (this.ignoredFiles.includes(relativePath)) {
+                const realTargetFile = path.join(targetPath, relativePath);
+                return !fs.existsSync(realTargetFile);
+              }
+              return true;
+            }
+          });
+        }
+        // Ocultar el staging mientras existe (cosmético, solo Windows).
+        setHidden(stagingPath, true);
+        staged.push({ targetPath, stagingPath });
+      }
+    } catch (err) {
+      // Rollback: borrar lo que sí alcanzó a copiarse al staging.
+      for (const { stagingPath } of staged) {
+        try { await fs.remove(stagingPath); } catch (_) {}
       }
+      throw err;
+    }
 
-      // Realizar instalación nueva
-      await this.performInstallation();
-      
-      // Restaurar archivos ignorados
-      await this.restoreIgnoredFiles();
+    // Phase 3: swap atómico. Por cada mapping ya staged, rename target → `.sa-old`,
+    // rename `.sa-new` → target, borrar `.sa-old`. fs.move es rename donde es posible.
+    for (const { targetPath, stagingPath } of staged) {
+      const oldPath = targetPath + OLD_SUFFIX;
+
+      if (fs.existsSync(targetPath)) {
+        await fs.move(targetPath, oldPath, { overwrite: true });
+        setHidden(oldPath, true); // ocultar el viejo mientras se borra
+      }
+      await fs.move(stagingPath, targetPath, { overwrite: true });
+      // El rename hereda el atributo oculto del staging — limpiarlo para que el
+      // target final sea visible.
+      setHidden(targetPath, false);
+      if (fs.existsSync(oldPath)) {
+        try { await fs.remove(oldPath); } catch (e) {
+          console.warn(`⚠️  No se pudo borrar ${oldPath} (se limpiará en la próxima corrida): ${e.message}`);
+        }
+      }
     }
   }
 
@@ -660,9 +905,34 @@ class SiesaBmadInstaller {
   }
 }
 
+function printHelp() {
+  console.log('Usage: npx siesa-agents [options]\n');
+  console.log('Options:');
+  console.log('  -y, --yes        Modo no-interactivo. Usa defaults sensatos en cualquier prompt');
+  console.log('                   (no preguntar por repo remoto, hacer backup de modificados).');
+  console.log('                   Se activa automáticamente cuando stdin no es un TTY.');
+  console.log('  --version        Imprime la versión del paquete y sale.');
+  console.log('  -h, --help       Muestra esta ayuda.\n');
+  console.log('Environment:');
+  console.log('  SIESA_DEBUG=1    Muestra información de diagnóstico para el descubrimiento');
+  console.log('                   del directorio del paquete.');
+}
+
 // Ejecutar instalación si el script es llamado directamente
 if (require.main === module) {
-  const installer = new SiesaBmadInstaller();
+  const cliArgs = parseCliArgs(process.argv.slice(2));
+
+  if (cliArgs.help) {
+    printHelp();
+    process.exit(0);
+  }
+  if (cliArgs.version) {
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  const installer = new SiesaBmadInstaller(cliArgs);
   installer.install();
 }
 

package/bin/prepare-publish.js

@@ -2,26 +2,33 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { publishRenames } = require('./folder-mappings');
 
 const rootDir = path.dirname(__dirname);
 
-// Renombrar carpetas que empiezan con punto para que npm las incluya
-const folderMappings = [
-  { from: '.bmad-core', to: 'bmad-core' },
-  { from: '.vscode', to: 'vscode' },
-  { from: '.github', to: 'github' }
-];
+// Renombrar carpetas dev-side a sus nombres "flat" antes de `npm publish`. Cuáles se
+// renombran lo decide bin/folder-mappings.js (un solo source of truth compartido con
+// install.js y restore-folders.js).
+const folderMappings = publishRenames();
 
 console.log('📦 Preparando carpetas para publicación (siesa-agents)...');
 
-for (const mapping of folderMappings) {
-  const fromPath = path.join(rootDir, mapping.from);
-  const toPath = path.join(rootDir, mapping.to);
+if (folderMappings.length === 0) {
+  console.log('ℹ️  El repo mantiene un mirror flat de cada carpeta (claude/, github/, bmad/, …)');
+  console.log('   junto al dotted/underscored (.claude/, .github/, _bmad/, …). No hace falta');
+  console.log('   renombrar nada antes de `npm publish` — los archivos flat ya están listos.');
+  console.log('   Si en el futuro se elimina algún mirror, declara su devSource en');
+  console.log('   bin/folder-mappings.js y este script lo renombrará automáticamente.');
+} else {
+  for (const mapping of folderMappings) {
+    const fromPath = path.join(rootDir, mapping.from);
+    const toPath = path.join(rootDir, mapping.to);
 
-  if (fs.existsSync(fromPath)) {
-    console.log(`📁 Renombrando ${mapping.from} -> ${mapping.to}`);
-    fs.moveSync(fromPath, toPath);
+    if (fs.existsSync(fromPath)) {
+      console.log(`📁 Renombrando ${mapping.from} -> ${mapping.to}`);
+      fs.moveSync(fromPath, toPath);
+    }
   }
 }
 
-console.log('✅ Carpetas preparadas para publicación');
+console.log('✅ Carpetas preparadas para publicación');

package/bin/restore-folders.js

@@ -2,26 +2,29 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { restoreRenames } = require('./folder-mappings');
 
 const rootDir = path.dirname(__dirname);
 
-// Restaurar nombres originales de las carpetas
-const folderMappings = [
-  { from: 'bmad-core', to: '.bmad-core' },
-  { from: 'vscode', to: '.vscode' },
-  { from: 'github', to: '.github' }
-];
+// Restaurar nombres originales de las carpetas dev tras `npm publish`. Cuáles se
+// restauran lo decide bin/folder-mappings.js (compartido con install.js y prepare-publish.js).
+const folderMappings = restoreRenames();
 
 console.log('🔄 Restaurando nombres originales de carpetas...');
 
-for (const mapping of folderMappings) {
-  const fromPath = path.join(rootDir, mapping.from);
-  const toPath = path.join(rootDir, mapping.to);
+if (folderMappings.length === 0) {
+  console.log('ℹ️  Nada que restaurar — prepare-publish.js no renombró nada porque el repo');
+  console.log('   mantiene mirrors flat junto a los dotted/underscored. Ver bin/folder-mappings.js.');
+} else {
+  for (const mapping of folderMappings) {
+    const fromPath = path.join(rootDir, mapping.from);
+    const toPath = path.join(rootDir, mapping.to);
 
-  if (fs.existsSync(fromPath)) {
-    console.log(`📁 Restaurando ${mapping.from} -> ${mapping.to}`);
-    fs.moveSync(fromPath, toPath);
+    if (fs.existsSync(fromPath)) {
+      console.log(`📁 Restaurando ${mapping.from} -> ${mapping.to}`);
+      fs.moveSync(fromPath, toPath);
+    }
   }
 }
 
-console.log('✅ Carpetas restauradas');
+console.log('✅ Carpetas restauradas');

package/claude/agents/sa-code-review.md

@@ -20,6 +20,7 @@ NO modifiques ningún archivo dentro de `.claude/agent-memory/` — es de SOLO L
 - Sé directo, funcional y breve.
 - Si encuentras issues que puedes auto-corregir, corrígelos directamente sin pedir confirmación.
 - Valida compliance contra los estándares cargados: folder structure correcta, naming conventions, uso de DateTimeOffset (no DateTime), UUID PKs, FluentValidation, patrones DDD, etc.
+- **Git — NO auto-gitflow:** Cuando este agente es invocado desde `sa-quick-dev`, está **prohibido** crear ramas, hacer commits, push, pull requests, worktrees ni cualquier operación git automática. Todos los cambios (incluidas las auto-correcciones) se aplican directamente sobre la rama activa del repositorio al momento de la invocación. El versionamiento es responsabilidad exclusiva del usuario.
 
 ## Ejecución
 

package/claude/agents/sa-dev-story.md

@@ -20,6 +20,7 @@ NO modifiques ningún archivo dentro de `.claude/agent-memory/` — es de SOLO L
 - Sé directo, funcional y breve.
 - Implementa SOLO lo que los acceptance criteria y las tareas de la historia requieren. Nada más.
 - Todo código DEBE seguir los estándares cargados: folder structure, naming conventions, tech stack, patterns (DDD entities, value objects, CQRS, FluentValidation, DateTimeOffset, UUID PKs, etc.).
+- **Git — NO auto-gitflow:** Cuando este agente es invocado desde `sa-quick-dev`, está **prohibido** crear ramas, hacer commits, push, pull requests, worktrees ni cualquier operación git automática. Todos los cambios se aplican directamente sobre la rama activa del repositorio al momento de la invocación. El versionamiento es responsabilidad exclusiva del usuario.
 
 ## Ejecución
 

package/claude/commands/sa-quick-dev.md

@@ -99,6 +99,64 @@ Modo: epic-level
 
 ---
 
+## Reglas generales del pipeline
+
+### Regla 1 — Observabilidad obligatoria en cada sub-agente
+
+Cada sub-agente que ejecuta un workflow BMAD (`sa-create-story`, `sa-dev-story`, `sa-code-review`) **DEBE honrar las instrucciones de observabilidad** definidas en su respectivo `workflow_ext.md`. Estas instrucciones emiten eventos de telemetría (`sa-emit.js`) a GCP en momentos específicos del flujo y son la fuente de todos los reportes de métricas del equipo.
+
+**Workflows instrumentados y eventos que se deben emitir:**
+
+| Sub-agente | `workflow_ext.md` | Eventos emitidos |
+|---|---|---|
+| `sa-create-story` | `_siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md` | `workflow.started`, `status.changed` (backlog → ready-for-dev), `workflow.finished` |
+| `sa-dev-story` | `_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md` | `workflow.started`, `status.changed` (in-progress → review), `workflow.finished` |
+| `sa-code-review` | `_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md` | `workflow.started`, `fix.started`/`fix.finished` (cuando el usuario acepta auto_fix / action_items / show_details), `status.changed` (review → done o → in-progress), `workflow.finished` |
+
+**Prohibido a cualquier sub-agente bajo este orquestador:**
+
+- ❌ Saltarse, comentar, condicionar u omitir cualquier comando `node ... sa-emit.js ...` del `workflow_ext.md` correspondiente.
+- ❌ Diferir la emisión al "final del pipeline" o agruparla en batch. Los eventos son **lifecycle markers** y solo tienen sentido en el instante exacto que el `workflow_ext.md` indica (`workflow.finished` mide `duration_ms` desde el `workflow.started` correspondiente; si lo retrasas, la métrica queda corrompida).
+
+**Manejo de errores de `sa-emit.js`:**
+
+Si la llamada a `sa-emit.js` falla (gateway caído, credenciales mal configuradas, etc.), el sub-agente debe:
+
+1. Registrar el fallo como advertencia **no-bloqueante**.
+2. **Continuar el workflow normalmente** (regla universal documentada en cada `workflow_ext.md`: *"observability must never block the workflow"*).
+3. NUNCA reemplazar la llamada por su omisión deliberada — el evento queda buffereado localmente en `~/.claude/observability/buffer/events.jsonl` y se reenvía automáticamente cuando el transporte se recupera.
+
+---
+
+## Reglas generales del pipeline
+
+### Regla 1 — Observabilidad obligatoria en cada sub-agente
+
+Cada sub-agente que ejecuta un workflow BMAD (`sa-create-story`, `sa-dev-story`, `sa-code-review`) **DEBE honrar las instrucciones de observabilidad** definidas en su respectivo `workflow_ext.md`. Estas instrucciones emiten eventos de telemetría (`sa-emit.js`) a GCP en momentos específicos del flujo y son la fuente de todos los reportes de métricas del equipo.
+
+**Workflows instrumentados y eventos que se deben emitir:**
+
+| Sub-agente | `workflow_ext.md` | Eventos emitidos |
+|---|---|---|
+| `sa-create-story` | `_siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md` | `workflow.started`, `status.changed` (backlog → ready-for-dev), `workflow.finished` |
+| `sa-dev-story` | `_siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md` | `workflow.started`, `status.changed` (in-progress → review), `workflow.finished` |
+| `sa-code-review` | `_siesa-agents/bmm/workflows/4-implementation/code-review/workflow_ext.md` | `workflow.started`, `fix.started`/`fix.finished` (cuando el usuario acepta auto_fix / action_items / show_details), `status.changed` (review → done o → in-progress), `workflow.finished` |
+
+**Prohibido a cualquier sub-agente bajo este orquestador:**
+
+- ❌ Saltarse, comentar, condicionar u omitir cualquier comando `node ... sa-emit.js ...` del `workflow_ext.md` correspondiente.
+- ❌ Diferir la emisión al "final del pipeline" o agruparla en batch. Los eventos son **lifecycle markers** y solo tienen sentido en el instante exacto que el `workflow_ext.md` indica (`workflow.finished` mide `duration_ms` desde el `workflow.started` correspondiente; si lo retrasas, la métrica queda corrompida).
+
+**Manejo de errores de `sa-emit.js`:**
+
+Si la llamada a `sa-emit.js` falla (gateway caído, credenciales mal configuradas, etc.), el sub-agente debe:
+
+1. Registrar el fallo como advertencia **no-bloqueante**.
+2. **Continuar el workflow normalmente** (regla universal documentada en cada `workflow_ext.md`: *"observability must never block the workflow"*).
+3. NUNCA reemplazar la llamada por su omisión deliberada — el evento queda buffereado localmente en `~/.claude/observability/buffer/events.jsonl` y se reenvía automáticamente cuando el transporte se recupera.
+
+---
+
 ## PASO 1 — Loop de procesamiento por historia
 
 Para CADA historia pendiente de la épica seleccionada, ejecuta secuencialmente los sub-agentes dedicados. Cada historia completa su ciclo completo antes de pasar a la siguiente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.82",
+  "version": "2.1.84",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {
@@ -26,7 +26,6 @@
     "github/**/*",
     "claude/**/*",
     "gemini/**/*",
-    "kiro/**/*",
     "bin/**/*",
     "resources/**/*",
     "README.md",
@@ -36,7 +35,7 @@
     "node": ">=14.0.0"
   },
   "dependencies": {
-    "fs-extra": "^11.1.1",
-    "path": "^0.12.7"
+    "@clack/prompts": "^0.11.0",
+    "fs-extra": "^11.1.1"
   }
 }

package/siesa-agents/bmm/workflows/4-implementation/dev-story/workflow_ext.md

@@ -147,3 +147,19 @@ node "{project_root}/_siesa-agents/observability/scripts/sa-emit.js" --event wor
 
 Before marking a story as complete, verify the Siesa-specific checklist items at:
 `@_siesa-agents/bmm/workflows/4-implementation/dev-story/checklist_ext.md`
+
+# MANDATORY RULE: SONARQUBE CODE QUALITY CONSIDERATIONS
+
+**TRIGGER:** Every time the dev-story workflow implements or modifies code.
+
+**CRITICAL INSTRUCTION:** BEFORE writing or modifying any code, YOU MUST **USE YOUR READ TOOL** to open and read the FULL contents of the SonarQube rules file at:
+`_siesa-agents/resources/sonar/sonar-rules.md`
+
+> NOTE ON THE MIRROR COPY: This reference path is ALWAYS `_siesa-agents/resources/sonar/sonar-rules.md`,
+
+## 8. Apply Sonar rules throughout implementation
+
+1. Assimilate the rules in `sonar-rules.md` (security, reliability, maintainability findings based on real SonarQube results) and keep them in memory during the entire implementation.
+2. You MUST enforce these rules in every piece of code you write or modify — never produce code that introduces a known SonarQube violation (e.g., hardcoded secrets, unhandled exceptions, code smells covered by the file).
+3. BEFORE marking the story as review/complete, validate your changes against the final checklist defined in `sonar-rules.md`.
+4. If the file does not exist for the current project, acknowledge it and proceed normally (Sonar enforcement is best-effort and must never block the workflow).

package/siesa-agents/resources/sonar/sonar-rules.md

@@ -0,0 +1,267 @@
+# Sonar Rules — Reglas transversales de calidad y seguridad
+
+> Reglas obligatorias para cualquier agente de IA (Claude Code, Cursor, Copilot, etc.) que genere o modifique código en cualquier proyecto SIESA.
+> Basado en hallazgos reales de SonarQube y prácticas de seguridad para .NET / C#.
+>
+> **Stack y versiones:** la fuente de verdad es `_siesa-agents/resources/architecture/` (.NET 10, PostgreSQL 18+, EF Core 10, xUnit, etc.). NO uses frameworks, motores de BD ni versiones distintas a los definidos allí.
+>
+> **Antes de generar código, lee este archivo completo.**
+> **Antes de hacer commit, valida el checklist final.**
+
+---
+
+## 1. Reglas críticas de seguridad (NUNCA violar)
+
+### 1.1 Secretos y credenciales
+
+**Prohibido absolutamente:**
+- Hardcodear passwords, API keys, connection strings con credenciales, encryption keys, tokens, certificados.
+- Subir `appsettings.json` o cualquier archivo con valores sensibles reales.
+- Dejar credenciales en comentarios, ejemplos o tests.
+
+**Cómo hacerlo bien:**
+
+```jsonc
+// appsettings.json — SOLO placeholders o valores no sensibles
+{
+  "DATABASE_PROVIDER": "postgres",
+  "DATABASE_URL": "",          // ← se inyecta en runtime
+  "ENCRYPTION_KEY": "",        // ← se inyecta en runtime
+  "API_PORT": 3005
+}
+```
+
+```bash
+# Variables de entorno (producción / staging) — PostgreSQL / Npgsql
+export DATABASE_URL="Host=...;Port=5432;Database=...;Username=...;Password=...;"
+export ENCRYPTION_KEY="..."
+```
+
+```bash
+# User Secrets (desarrollo local)
+dotnet user-secrets init
+dotnet user-secrets set "DATABASE_URL" "Host=localhost;Port=5432;Database=...;Username=...;Password=...;"
+dotnet user-secrets set "ENCRYPTION_KEY" "..."
+```
+
+**En producción:** Azure Key Vault, AWS Secrets Manager, o GCP Secret Manager (si el proyecto ya usa GCP, **preferir Secret Manager de GCP**).
+
+**Si encuentras un secreto hardcodeado:** no solo lo muevas — **márcalo como comprometido** y avisa al humano para rotarlo. Una vez en Git, asume que está filtrado.
+
+---
+
+### 1.2 Regex siempre con timeout
+
+Toda expresión regular **debe** especificar `matchTimeout` para prevenir ReDoS (Regular Expression Denial of Service).
+
+```csharp
+// ❌ MAL — vulnerable a ReDoS
+private static readonly Regex IdFormatoPattern =
+    new(@"^[A-Za-z0-9_]{1,40}$", RegexOptions.Compiled);
+
+// ✅ BIEN — con timeout explícito
+private static readonly Regex IdFormatoPattern =
+    new(@"^[A-Za-z0-9_]{1,40}$", RegexOptions.Compiled, TimeSpan.FromSeconds(2));
+```
+
+**Aplica a:**
+- `Regex` estáticos `readonly`
+- `Regex` instanciados ad-hoc
+- `Regex.IsMatch()`, `Regex.Match()`, `Regex.Replace()` estáticos → preferir instancias con timeout
+
+**Timeout recomendado:** entre `100ms` (validaciones rápidas) y `2s` (parsing complejo). Nunca `Timeout.InfiniteTimeSpan`.
+
+---
+
+### 1.3 HTTPS y configuración CORS
+
+**HTTP solo en `localhost` o `127.0.0.1` para desarrollo.** Cualquier otro origen → HTTPS.
+
+```csharp
+// ❌ MAL — http://app-dev.example.com:3000 es un dominio público con HTTP
+var defaultOrigins = new[]
+{
+    "http://localhost:5173",              // ok, es localhost
+    "http://app-dev.example.com:3000"     // ← NO, debe ser https
+};
+
+// ✅ BIEN
+var defaultOrigins = new[]
+{
+    "http://localhost:5173",
+    "https://app-dev.example.com:3000"
+};
+```
+
+**CORS — reglas:**
+- Nunca `AllowAnyOrigin()` en producción.
+- Lista explícita de orígenes, idealmente leída de configuración.
+- No combinar `AllowAnyOrigin()` con `AllowCredentials()` (es invalido y peligroso).
+- `AllowAnyHeader()` y `AllowAnyMethod()` aceptables solo si el conjunto de orígenes está restringido.
+
+---
+
+### 1.4 Configuración del archivo `appsettings.json`
+
+Solo valores **no sensibles**:
+- ✅ Puertos, hostnames públicos, feature flags, niveles de log, nombres de bucket
+- ❌ Passwords, connection strings con credenciales, encryption keys, JWT secrets, API tokens
+
+Si un valor sensible necesita un default visible, usa cadena vacía `""` o un placeholder claro como `"__SET_IN_ENV__"`, **nunca un valor real ni de ejemplo creíble**.
+
+---
+
+## 2. Reglas para contenedores (Docker)
+
+### 2.1 Nunca correr como root
+
+```dockerfile
+# ❌ MAL — implícitamente root
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+COPY --from=build /app/publish .
+ENTRYPOINT ["dotnet", "MyApp.API.dll"]
+
+# ✅ BIEN — usuario no privilegiado
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+RUN groupadd -r app && useradd -r -g app -u 1001 app
+WORKDIR /app
+COPY --from=build --chown=app:app /app/publish .
+USER app
+ENTRYPOINT ["dotnet", "MyApp.API.dll"]
+```
+
+### 2.2 Otras reglas Docker
+
+- Tags específicos en `FROM`, nunca `:latest`.
+- Multi-stage build para no incluir SDK en la imagen final.
+- `.dockerignore` actualizado (excluir `bin/`, `obj/`, `.git/`, `appsettings.Development.json`, secretos).
+- `COPY` específico, evitar `COPY . .` sin `.dockerignore`.
+- `HEALTHCHECK` definido.
+
+---
+
+## 3. Reglas de código C# / .NET
+
+### 3.1 Manejo de excepciones
+
+```csharp
+// ❌ MAL
+try { ... } catch (Exception ex) { _logger.LogError(ex.Message); }
+
+// ✅ BIEN — capturar específico, loguear con contexto, re-lanzar o convertir
+try { ... }
+catch (NpgsqlException ex)
+{
+    _logger.LogError(ex, "Failed to query {Entity} with id {Id}", entityName, id);
+    throw;
+}
+```
+
+- Capturar excepciones específicas, no `Exception` genérico (salvo en handlers globales).
+- Loguear con structured logging (`LogError(ex, "msg {Param}", value)`), no concatenar.
+- No tragar excepciones silenciosamente.
+- **No uses excepciones para flujos de negocio esperados** → usa el **Result Pattern** (`Result<T>`) definido en la arquitectura. Las excepciones son solo para errores inesperados / de infraestructura.
+
+### 3.2 Async / await
+
+- Usar `async`/`await` en cualquier I/O (BD, HTTP, archivos).
+- `ConfigureAwait(false)` en bibliotecas reutilizables (no en endpoints ASP.NET Core).
+- No mezclar `.Result` ni `.Wait()` con `async` (deadlocks).
+- `CancellationToken` propagado desde el endpoint hasta el repositorio.
+
+### 3.3 Nullability y disposable
+
+- `<Nullable>enable</Nullable>` en el `.csproj`, respetar las anotaciones.
+- `using` / `await using` para todo lo que implementa `IDisposable` / `IAsyncDisposable`.
+- `sealed class` por defecto si no se necesita herencia.
+
+### 3.4 Code smells frecuentes
+
+- Métodos > 50 líneas → refactorizar.
+- Complejidad ciclomática > 10 → separar.
+- Magic numbers / strings → constantes o enums.
+- TODO / FIXME sin issue asociado → prohibido. Si va, debe incluir referencia (`TODO(JIRA-123): ...`).
+- Código comentado → eliminar, no comentar (para eso está Git).
+
+---
+
+## 4. Testing — cobertura ≥ 80% en código nuevo
+
+Toda funcionalidad nueva debe incluir tests **en el mismo PR**. No "lo agrego después". **TDD es obligatorio**: escribe los tests antes del código de producción.
+
+**Mínimo esperado por tipo:**
+
+| Tipo de código | Tests requeridos |
+|---|---|
+| Validators (FluentValidation) | Happy path + cada regla de validación |
+| Endpoints (Minimal API) | 200 OK, 400 validación, 401/403 si aplica, 404, 500 mockeado |
+| Handlers (MediatR / similar) | Happy path + cada rama de negocio + manejo de excepciones |
+| Servicios con dependencias externas | Mock de la dependencia, verificar contrato |
+| Regex / parsers | Casos válidos + casos inválidos + casos borde (vacío, max length) |
+
+Frameworks de testing (definidos en la arquitectura corporativa, NO usar otros):
+- **Unit tests:** xUnit + EF Core InMemory.
+- **Integration tests:** xUnit + Testcontainers.PostgreSql (base de datos real en contenedor).
+
+Si necesitas introducir un framework adicional, primero valida contra `_siesa-agents/resources/architecture/` y justifícalo.
+
+---
+
+## 5. Reglas específicas para agentes de IA
+
+### 5.1 Antes de generar código
+
+1. Lee este archivo completo.
+2. Revisa las reglas relevantes al tipo de cambio que vas a hacer.
+3. Si vas a tocar configuración, secretos, Regex, Docker o CORS → relee la sección correspondiente.
+
+### 5.2 Durante la generación
+
+- **Si necesitas un secreto:** genera el código que lo lee de configuración / env y **explícale al humano** dónde debe definirlo. Nunca pongas un valor real ni "de ejemplo".
+- **Si generas Regex:** incluye `TimeSpan.FromSeconds(N)` siempre.
+- **Si generas Dockerfile:** incluye `USER` no-root.
+- **Si generas CORS:** lee orígenes de configuración.
+- **Si generas un endpoint o handler:** genera también su test en el mismo turno.
+
+### 5.3 Antes de declarar el cambio terminado
+
+Ejecuta este self-check mentalmente:
+
+- [ ] ¿Hay algún string que parezca una credencial real?
+- [ ] ¿Todas las `Regex` tienen `TimeSpan` como tercer/cuarto argumento?
+- [ ] ¿Algún `catch (Exception ex)` sin re-lanzar ni contexto?
+- [ ] ¿Tests nuevos para todo el código nuevo?
+- [ ] ¿`appsettings.json` modificado contiene solo valores no sensibles?
+- [ ] ¿Si toqué Dockerfile, sigue corriendo con `USER` no-root?
+- [ ] ¿Si toqué CORS, los orígenes son `https://` excepto `localhost`?
+
+Si alguna respuesta es "no" o "no sé", **vuelve atrás y corrige antes de entregar**.
+
+---
+
+## 6. Checklist final antes de commit
+
+```
+[ ] dotnet build sin warnings nuevos
+[ ] dotnet test pasa al 100%
+[ ] Cobertura de líneas nuevas ≥ 80%
+[ ] Sin secretos en el diff (revisar con: git diff --staged | grep -iE 'password|secret|key|token')
+[ ] sonar-scanner local sin issues nuevos de severidad >= Major
+[ ] Pre-commit hooks ejecutados (gitleaks, dotnet format)
+```
+
+---
+
+## 7. Cuando SonarQube falla un Quality Gate
+
+Si una corrida marca este archivo como insuficiente (apareció un patrón nuevo no cubierto aquí):
+
+1. **No solo arregles el hallazgo** — agrega la regla a este archivo.
+2. Si es una categoría nueva, abrir sección con ejemplo `❌ MAL` / `✅ BIEN`.
+3. Commit del fix + commit del update de reglas en el mismo PR.
+
+Así el siguiente código generado por IA no repetirá el patrón.
+
+---
+
+**Origen:** consolidado a partir de hallazgos reales de análisis de SonarQube en proyectos SIESA (security hotspots, cobertura insuficiente, credenciales hardcodeadas). Mantener vivo según la sección 7.

package/vscode/settings.json

@@ -9,5 +9,9 @@
     "cursor-workspace": true
   },
   "github.copilot.chat.agent.autoFix": true,
-  "chat.tools.autoApprove": false
+  "chat.tools.autoApprove": false,
+  "files.exclude": {
+    "**/*.sa-new": true,
+    "**/*.sa-old": true
+  }
 }