@saulwade/swl-ses 1.6.3 → 1.6.6

package/habilidades/changelog-generator/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: changelog-generator
+description: >
+  Generador automático de entradas CHANGELOG.md en formato Keep a Changelog
+  desde commits Conventional Commits. Parser determinista que clasifica feat/
+  fix/perf/refactor/docs/etc. en categorías user-facing en español, detecta
+  breaking changes (marca '!' o trailer 'BREAKING CHANGE:') y reporta nivel
+  de conformidad para decidir fallback manual. Cargar en /swl:release Paso 7
+  cuando hay commits Conventional, o manualmente para previsualizar el
+  changelog antes de un release.
+version: 1.0.0
+nivelRiesgo: BAJO
+herramientasPermitidas: [Read, Bash]
+skillsInvocables: [release-semver]
+exclusiones:
+  - "No invocar para generar release notes con marketing copy o anuncios para usuarios finales — este skill produce listado técnico-legible, no narrativa."
+  - "No invocar si el repo no usa Conventional Commits — el parser detecta <80% conformidad y el caller debe abortar a flujo manual de release-semver."
+  - "No invocar para reescribir CHANGELOG histórico — solo agrega entrada de la próxima versión al inicio."
+---
+
+# /habilidades/changelog-generator — CHANGELOG automático desde Conventional Commits
+
+## Cuándo cargar
+
+- Durante `/swl:release` Paso 7 (Generar CHANGELOG), cuando el flujo automático
+  está disponible y los commits del rango siguen Conventional Commits.
+- Para previsualizar el changelog candidato antes de bumpear versión:
+  `node habilidades/changelog-generator/scripts/parse-commits.js --version X`
+- Cuando un colaborador pide un resumen legible de cambios entre dos refs
+  arbitrarias del repo.
+
+## Cuándo NO cargar
+
+- Repo sin Conventional Commits (<80% de conformidad): el parser detecta y
+  reporta; el caller debe usar `Skill("release-semver")` flujo manual.
+- Generación de **release notes** (texto narrativo con contexto de producto):
+  este skill produce CHANGELOG técnico-legible; las release notes con marketing
+  son tarea aparte (`documentador-swl` con plantilla específica).
+- Reescritura histórica del CHANGELOG (squash de varias versiones, corrección
+  de entradas antiguas): solo se agrega entrada de la versión nueva al inicio.
+
+## Qué hace el skill
+
+1. **Lee commits** desde la última tag (o entre dos refs arbitrarias) con
+   `git log --format=...` usando un separador único para parsear subject + body
+   sin colisiones.
+2. **Parsea con Conventional Commits 1.0.0**: regex que captura tipo, scope,
+   marca `!`, descripción. Soporta tipos extendidos del proyecto SWL:
+   `evolucion` (cambios de skills/agentes), además de `feat/fix/perf/refactor/
+   docs/style/test/ci/build/chore/revert`.
+3. **Detecta breaking changes** por marca `!` después del tipo o trailer
+   `BREAKING CHANGE:` en el body. Los breaking siempre van al inicio del
+   release, sin importar el tipo original.
+4. **Transforma descripción técnica → legible**:
+   - Elimina referencias a issues al final (`(#123)`, `Refs #456`).
+   - Capitaliza primera letra.
+   - Elimina punto final (Keep a Changelog usa bullets sin punto).
+5. **Agrupa en categorías** con orden canónico:
+   1. Breaking changes
+   2. Nuevas funcionalidades (feat)
+   3. Correcciones (fix)
+   4. Mejoras de rendimiento (perf)
+   5. Cambios internos (refactor)
+   6. Reversiones (revert)
+   7. Evoluciones de skills/agentes (evolucion — SWL-specific)
+   8. Mantenimiento (docs/style/test/ci/build/chore — colapsadas)
+   9. Otros (commits sin prefijo CC válido)
+6. **Reporta conformidad**: ratio commits conformes / total. Si <80%, el
+   caller debe decidir si abortar o seguir manualmente.
+
+## Helper programático
+
+```js
+const {
+  parsearCommits,
+  leerCommitsGit,
+  generarChangelog,
+} = require('./habilidades/changelog-generator/scripts/parse-commits');
+
+// 1. Leer commits desde la última tag hasta HEAD
+const commits = leerCommitsGit({ to: 'HEAD' });
+
+// 2. Parsear y clasificar
+const { categorias, conformidad, totalCommits, conformes } = parsearCommits(commits);
+
+// 3. Si conformidad < 0.8, abortar o avisar al usuario
+if (conformidad < 0.8) {
+  console.warn(`Conformidad CC: ${conformes}/${totalCommits}. Revisar "Otros".`);
+}
+
+// 4. Generar markdown listo para insertar en CHANGELOG.md
+const md = generarChangelog(categorias, {
+  version: '1.6.5',
+  fecha: '2026-05-22',  // opcional, default = hoy
+  incluirHash: true,    // muestra hash corto al inicio de cada bullet
+});
+```
+
+## Uso CLI
+
+Previsualizar changelog candidato sin escribir nada:
+
+```bash
+node habilidades/changelog-generator/scripts/parse-commits.js \
+  --version 1.6.5 \
+  --format markdown
+```
+
+Filtrar por rango específico:
+
+```bash
+node habilidades/changelog-generator/scripts/parse-commits.js \
+  --from v1.6.4 \
+  --to HEAD \
+  --version 1.6.5
+```
+
+Salida JSON estructurado para post-procesamiento:
+
+```bash
+node habilidades/changelog-generator/scripts/parse-commits.js \
+  --from v1.6.4 \
+  --format json > /tmp/changelog-candidato.json
+```
+
+## Reglas de uso desde /swl:release
+
+1. Llamar a `leerCommitsGit` con la última tag detectada en el Paso 1 del
+   release.
+2. Verificar `conformidad >= 0.8`. Si menor, presentar al usuario los commits
+   bajo "Otros" y pedir decisión: (a) continuar con el changelog, (b) abortar
+   y reescribir commits, (c) editar manualmente la categoría "Otros".
+3. Si `--dry-run` está activo en `/swl:release`, mostrar el output de
+   `generarChangelog` sin escribir a disco.
+4. Si conformidad OK: leer CHANGELOG.md actual, insertar el bloque generado
+   al inicio después del header `# Changelog`, escribir atómicamente.
+5. NO hacer commit aquí — eso lo hace el Paso 8 de `/swl:release`.
+
+## Gotchas observables
+
+- **Conventional Commits sin scope son válidos**: `fix: corregir X` parsea
+  igual que `fix(modulo): corregir X`. El parser no exige scope.
+- **El subject debe ir en una sola línea**: si un commit usa newline en el
+  subject, el parser lo trata como completo pero `git log %s` ya lo trunca.
+- **Tipos no estándar van a "Otros"**: si un equipo usa `mejora:`, `cambio:`,
+  el parser los marca como no conformes. El usuario debe ajustar la lista
+  `CATEGORIAS` en `parse-commits.js` o adoptar tipos estándar.
+- **El skill NO escribe a disco directamente**: solo retorna markdown. El
+  caller (`/swl:release` Paso 7) es responsable de leer el CHANGELOG actual,
+  insertar al inicio y escribir atómicamente.
+- **Commits revert vienen del propio git**: `git revert` genera mensajes
+  `Revert "Subject original"` que el parser categoriza correctamente bajo
+  Reversiones (regex matchea `revert:` sin que el usuario lo escriba si usa
+  `git revert -e` para editar el mensaje al formato CC).
+- **El hash corto se trunca a 7 chars**: alineado con el formato `git log
+  --oneline` estándar.
+
+## Origen
+
+Adaptado del skill `changelog-generator` de
+`temp/awesome-codex-skills-master/changelog-generator/` (ComposioHQ, MIT) con:
+
+- Frontmatter al estándar SWL (es-MX, `nivelRiesgo: BAJO`, `exclusiones`).
+- Parser determinista en Node.js (`parse-commits.js`) — el origen es solo
+  documentación; este skill agrega la implementación ejecutable.
+- Tipo `evolucion:` específico de SWL agregado al parser.
+- Soporte para breaking changes `!` y trailer `BREAKING CHANGE:` (origen
+  solo menciona el segundo).
+- Reporte de conformidad <80% como gate explícita para fallback manual.
+- Integración con `/swl:release` Paso 7 documentada en `comandos/swl/release.md`.
+
+Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).

package/habilidades/changelog-generator/scripts/parse-commits.js

@@ -0,0 +1,354 @@
+'use strict';
+
+/**
+ * parse-commits.js — Parser determinista de Conventional Commits para
+ * generación automática de CHANGELOG en /swl:release.
+ *
+ * Lee commits desde `git log` (entre dos refs o desde la última tag) y los
+ * clasifica según el spec de Conventional Commits 1.0.0:
+ *   https://www.conventionalcommits.org/en/v1.0.0/
+ *
+ * Categorías generadas (formato Keep a Changelog):
+ *   - feat                  -> "Nuevas funcionalidades"
+ *   - fix                   -> "Correcciones"
+ *   - perf                  -> "Mejoras de rendimiento"
+ *   - refactor              -> "Cambios internos"
+ *   - docs / style / test / ci / build / chore -> "Mantenimiento" (opcional)
+ *   - BREAKING CHANGE / !   -> "Breaking changes" (siempre top de cada release)
+ *   - Sin prefijo CC válido -> "Otros" (con bandera de baja conformidad)
+ *
+ * Fallback: si la conformidad de commits es <80%, el script retorna
+ * `conformidad: <ratio>` para que el caller decida si abortar o seguir.
+ *
+ * Uso desde CLI:
+ *   node parse-commits.js [--from <ref>] [--to <ref>] [--format json|markdown]
+ *
+ * Uso programático:
+ *   const { parsearCommits, generarChangelog } = require('./parse-commits');
+ *   const { categorias, conformidad } = parsearCommits(commits);
+ *   const md = generarChangelog(categorias, { version: '1.6.5', fecha: '...' });
+ *
+ * Zero-deps. Cargado por skill `changelog-generator` y por
+ * `/swl:release` paso 7.
+ *
+ * @module habilidades/changelog-generator/scripts/parse-commits
+ */
+
+const { execSync } = require('node:child_process');
+
+// -----------------------------------------------------------------------------
+// Spec Conventional Commits
+// -----------------------------------------------------------------------------
+
+/**
+ * Regex que matchea una línea de commit Conventional Commits.
+ * Grupos: [1]=tipo, [2]=scope?, [3]=!?, [4]=descripcion
+ *
+ * Ejemplos válidos:
+ *   feat(auth): agregar validación PKCE
+ *   fix: corregir cálculo IEPS
+ *   feat!: breaking change inline
+ *   refactor(hooks/lib): split evolution-tracker
+ *   chore(release): bump version
+ */
+const RE_CONVENTIONAL = /^(feat|fix|perf|refactor|docs|style|test|ci|build|chore|revert|evolucion)(?:\(([^)]+)\))?(!)?:\s*(.+)$/;
+
+/** Mapa tipo CC → categoría Keep a Changelog en es-MX. */
+const CATEGORIAS = Object.freeze({
+  feat:      'Nuevas funcionalidades',
+  fix:       'Correcciones',
+  perf:      'Mejoras de rendimiento',
+  refactor:  'Cambios internos',
+  revert:    'Reversiones',
+  evolucion: 'Evoluciones de skills/agentes',
+  docs:      'Mantenimiento',
+  style:     'Mantenimiento',
+  test:      'Mantenimiento',
+  ci:        'Mantenimiento',
+  build:     'Mantenimiento',
+  chore:     'Mantenimiento',
+});
+
+/** Orden de salida en CHANGELOG (Breaking siempre primero). */
+const ORDEN_CATEGORIAS = Object.freeze([
+  'Breaking changes',
+  'Nuevas funcionalidades',
+  'Correcciones',
+  'Mejoras de rendimiento',
+  'Cambios internos',
+  'Reversiones',
+  'Evoluciones de skills/agentes',
+  'Mantenimiento',
+  'Otros',
+]);
+
+// -----------------------------------------------------------------------------
+// Transformación técnica → user-facing
+// -----------------------------------------------------------------------------
+
+/**
+ * Aplica heurísticas de transformación para hacer la línea más legible al
+ * usuario final sin contradecir lo que dice el commit.
+ *
+ * Reglas conservadoras: solo elimina prefijos técnicos y normaliza la primera
+ * letra. NO inventa contenido; si la descripción es críptica, queda críptica.
+ *
+ * @param {string} descripcion - Descripción cruda del commit.
+ * @returns {string} Versión legible.
+ */
+function transformarLegible(descripcion) {
+  let texto = descripcion.trim();
+
+  // Eliminar referencias a issues al final si son ruido (#123, refs #...).
+  texto = texto.replace(/\s*\(#\d+\)\s*$/, '');
+  texto = texto.replace(/\s*[Rr]efs?:?\s*#\d+\s*$/, '');
+
+  // Capitalizar primera letra.
+  if (texto.length > 0) {
+    texto = texto[0].toUpperCase() + texto.slice(1);
+  }
+
+  // Eliminar punto final si existe (Keep a Changelog usa bullets sin punto).
+  texto = texto.replace(/\.$/, '');
+
+  return texto;
+}
+
+// -----------------------------------------------------------------------------
+// Parser principal
+// -----------------------------------------------------------------------------
+
+/**
+ * Detecta si el commit tiene marca de breaking change según el spec
+ * Conventional Commits 1.0.0:
+ *   - `!` después del tipo/scope en el subject, o
+ *   - Trailer `BREAKING CHANGE:` o `BREAKING-CHANGE:` al INICIO de una línea
+ *     del body (no en medio de prosa). El spec requiere este formato literal
+ *     como trailer; una mención de la palabra dentro de la descripción NO
+ *     dispara breaking change.
+ *
+ * Bug histórico (fix v1.6.5): la regex previa `/BREAKING\s+CHANGE/i` generaba
+ * falsos positivos cuando el commit describía features que mencionaban
+ * "breaking changes" en su prosa sin ser un breaking change ellos mismos.
+ *
+ * @param {string} mensajeCompleto - Mensaje completo del commit (subject + body).
+ * @param {string} marcaExclamacion - Match del grupo `!` del regex.
+ * @returns {boolean}
+ */
+function esBreakingChange(mensajeCompleto, marcaExclamacion) {
+  if (marcaExclamacion === '!') return true;
+  // Trailer al inicio de línea, mayúsculas obligatorias, dos puntos al final.
+  return /^BREAKING[-\s]CHANGE:/m.test(mensajeCompleto);
+}
+
+/**
+ * Parsea una lista de commits y los clasifica.
+ *
+ * @param {Array<{hash: string, subject: string, body?: string}>} commits
+ * @returns {{
+ *   categorias: Map<string, Array<{hash: string, descripcion: string, scope?: string}>>,
+ *   conformidad: number,
+ *   totalCommits: number,
+ *   conformes: number,
+ * }}
+ */
+function parsearCommits(commits) {
+  const categorias = new Map();
+  for (const cat of ORDEN_CATEGORIAS) categorias.set(cat, []);
+
+  let conformes = 0;
+
+  for (const commit of commits) {
+    const { hash, subject = '', body = '' } = commit;
+    const completo = `${subject}\n${body}`;
+    const match = subject.match(RE_CONVENTIONAL);
+
+    if (!match) {
+      categorias.get('Otros').push({
+        hash,
+        descripcion: transformarLegible(subject),
+      });
+      continue;
+    }
+
+    conformes += 1;
+    const [, tipo, scope, marca, descripcion] = match;
+    const entrada = {
+      hash,
+      descripcion: transformarLegible(descripcion),
+      scope: scope || null,
+    };
+
+    // Breaking change tiene precedencia sobre la categoría natural.
+    if (esBreakingChange(completo, marca)) {
+      categorias.get('Breaking changes').push(entrada);
+      continue;
+    }
+
+    const categoria = CATEGORIAS[tipo] || 'Otros';
+    categorias.get(categoria).push(entrada);
+  }
+
+  return {
+    categorias,
+    conformidad: commits.length === 0 ? 1 : conformes / commits.length,
+    totalCommits: commits.length,
+    conformes,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Lectura desde git
+// -----------------------------------------------------------------------------
+
+/**
+ * Obtiene commits desde git en formato estructurado.
+ *
+ * @param {object} opts
+ * @param {string} [opts.from] - Ref inicial (default: última tag).
+ * @param {string} [opts.to='HEAD'] - Ref final.
+ * @param {string} [opts.cwd] - Directorio del repo.
+ * @returns {Array<{hash: string, subject: string, body: string}>}
+ */
+function leerCommitsGit(opts = {}) {
+  const { from, to = 'HEAD', cwd = process.cwd() } = opts;
+
+  let rango;
+  if (from) {
+    rango = `${from}..${to}`;
+  } else {
+    // Default: desde la última tag (si existe) o desde el initial commit.
+    try {
+      const ultimaTag = execSync('git describe --tags --abbrev=0', {
+        cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
+      }).trim();
+      rango = `${ultimaTag}..${to}`;
+    } catch {
+      rango = to;
+    }
+  }
+
+  // Separador único para parsear subject + body (que puede ser multi-línea).
+  const SEP = '<<<COMMIT-SWL-SEP>>>';
+  const FIELD = '<<<FIELD-SEP>>>';
+  const formato = `%H${FIELD}%s${FIELD}%b${SEP}`;
+
+  let salida;
+  try {
+    salida = execSync(`git log ${rango} --format=${JSON.stringify(formato)}`, {
+      cwd, encoding: 'utf8',
+    });
+  } catch {
+    return [];
+  }
+
+  return salida
+    .split(SEP)
+    .map(s => s.trim())
+    .filter(Boolean)
+    .map(linea => {
+      const [hash, subject, body] = linea.split(FIELD);
+      return {
+        hash: (hash || '').trim(),
+        subject: (subject || '').trim(),
+        body: (body || '').trim(),
+      };
+    })
+    .filter(c => c.hash);
+}
+
+// -----------------------------------------------------------------------------
+// Generación de markdown
+// -----------------------------------------------------------------------------
+
+/**
+ * Genera la entrada de CHANGELOG en formato Keep a Changelog.
+ *
+ * @param {Map<string, Array>} categorias
+ * @param {object} opts
+ * @param {string} opts.version - Ej: '1.6.5'
+ * @param {string} [opts.fecha] - Default: hoy en formato YYYY-MM-DD
+ * @param {boolean} [opts.incluirHash=true] - Mostrar hash corto al inicio de cada bullet.
+ * @returns {string}
+ */
+function generarChangelog(categorias, opts) {
+  const { version, fecha, incluirHash = true } = opts || {};
+  if (!version) throw new Error('generarChangelog: version es obligatoria');
+
+  const fechaUsada = fecha || new Date().toISOString().slice(0, 10);
+  const lineas = [`## [${version}] - ${fechaUsada}`, ''];
+
+  for (const categoria of ORDEN_CATEGORIAS) {
+    const entradas = categorias.get(categoria) || [];
+    if (entradas.length === 0) continue;
+
+    lineas.push(`### ${categoria}`);
+    lineas.push('');
+    for (const entrada of entradas) {
+      const hashCorto = incluirHash && entrada.hash
+        ? `${entrada.hash.slice(0, 7)} `
+        : '';
+      const scope = entrada.scope ? `**${entrada.scope}**: ` : '';
+      lineas.push(`- ${hashCorto}${scope}${entrada.descripcion}`);
+    }
+    lineas.push('');
+  }
+
+  return lineas.join('\n');
+}
+
+// -----------------------------------------------------------------------------
+// CLI
+// -----------------------------------------------------------------------------
+
+function _parseFlags(argv) {
+  const flags = { format: 'markdown' };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--from' && argv[i + 1]) { flags.from = argv[++i]; continue; }
+    if (argv[i] === '--to' && argv[i + 1])   { flags.to   = argv[++i]; continue; }
+    if (argv[i] === '--format' && argv[i + 1]) { flags.format = argv[++i]; continue; }
+    if (argv[i] === '--version' && argv[i + 1]) { flags.version = argv[++i]; continue; }
+  }
+  return flags;
+}
+
+if (require.main === module) {
+  const flags = _parseFlags(process.argv);
+  const commits = leerCommitsGit({ from: flags.from, to: flags.to });
+  const resultado = parsearCommits(commits);
+
+  if (flags.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      ...resultado,
+      categorias: Object.fromEntries(resultado.categorias),
+    }, null, 2));
+  } else {
+    if (!flags.version) {
+      process.stderr.write('ERROR: --version requerido para format=markdown\n');
+      process.exit(1);
+    }
+    process.stdout.write(generarChangelog(resultado.categorias, {
+      version: flags.version,
+    }));
+  }
+  process.stdout.write('\n');
+
+  if (resultado.conformidad < 0.8) {
+    process.stderr.write(
+      `\nADVERTENCIA: conformidad Conventional Commits = ${(resultado.conformidad * 100).toFixed(1)}% ` +
+      `(${resultado.conformes}/${resultado.totalCommits}). ` +
+      `Revisar bloque "Otros" antes de publicar.\n`,
+    );
+  }
+}
+
+module.exports = {
+  parsearCommits,
+  leerCommitsGit,
+  generarChangelog,
+  transformarLegible,
+  esBreakingChange,
+  RE_CONVENTIONAL,
+  CATEGORIAS,
+  ORDEN_CATEGORIAS,
+};

package/habilidades/devsecops-pipeline-security/SKILL.md

@@ -267,6 +267,9 @@ volverse bloqueante. Durante observación, limpiar falsos positivos.
 - **Dependabot/Renovate sin merge automático bajo condiciones**: los PRs de bump acumulan sin merge, y cuando se necesitan todos a la vez, romper cosas se vuelve inevitable. Causa: revisar cada bump manualmente es alta fricción; sin automatización los PRs se estancan. Solución: auto-merge bump de patch + tests pasando; bump de minor/major requiere revisión; bump de security → auto-merge si CVE HIGH/CRITICAL independiente del tipo.
 - **Reglas custom de Semgrep sin tests**: escribir una regla custom sin fixtures positivas y negativas genera detecciones incorrectas. Causa: los patrones AST son sutiles; un regex mal calibrado atrapa casos irrelevantes. Solución: toda regla custom incluye archivo `rule-test.yml` con casos positivos (debe detectar) y negativos (no debe detectar); Semgrep tiene `semgrep --test` para validación automática.
 - **Reportar DAST findings como críticos sin verificar explotabilidad**: ZAP marca "High" por patrones que pueden no ser explotables en el contexto real (ej: header missing que la app no usa). Causa: los scanners son conservadores por diseño. Solución: triage de findings HIGH con verificación de explotabilidad antes de bloquear; los hallazgos con "Information Disclosure" raramente justifican bloqueo de release sin contexto adicional.
+- **Validator con centinela string hardcodeado divergente del `.env.example` real** [CONFIRMADO 2026-05-20, SIGAF]: un validator de config tipo `_CENTINELA = "CAMBIAR_POR_CLAVE_SEGURA_EN_PRODUCCION"` rechaza solo ese string exacto. Si el `.env.example` del repo usa una variante (`"CAMBIAR_POR_CLAVE_SEGURA_256_BITS_EN_PRODUCCION"` con sufijo `_256_BITS_`), el validator NO la matchea — la app arranca en cualquier ambiente con el secret trivial conocido públicamente en el repo. Causa: un refactor del `.env.example` para clarificar el placeholder abre bypass silencioso del validator. El test de regresión solo cubre el centinela exacto, no las variantes. Solución: en validators de placeholder/centinela, usar `frozenset[str]` con TODAS las variantes conocidas + regex catch-all de prefijos típicos (`^(CAMBIAR_POR|GENERAR_|REEMPLAZAR_|CHANGE_ME|TODO|FIXME|XXX_|<.*>)`). Defensa en profundidad doble: si alguien introduce una variante futura no enumerada, el regex la atrapa. Tests de regresión deben cubrir explícitamente el placeholder real del `.env.example` actual.
+- **Step de upload SARIF sin `continue-on-error: true` mata el workflow en repos privados sin GHAS** [CONFIRMADO 2026-05-20, SIGAF]: repos PRIVATE en organización requieren GitHub Advanced Security (GHAS) licenciado para aceptar uploads SARIF third-party. Sin GHAS la API responde 403 `"Code Security must be enabled for this repository to use code scanning"` y el step falla. CodeQL aparece success cosmético porque su action `github/codeql-action/analyze` embebe el upload con `continue-on-error` interno; Semgrep tiene scan y upload como steps separados — solo el scan tiene `continue-on-error: true`, el upload mata el workflow. Causa: el skill cubre el "happy path" (repo público o con GHAS) sin advertir el caso edge común "repo privado de organización sin GHAS". Solución: en cualquier workflow con upload SARIF al Security tab, el step de upload DEBE tener `continue-on-error: true` para resiliencia ante 3 escenarios — (a) GHAS no habilitado, (b) API GitHub caída, (c) PR desde fork sin secrets. SIEMPRE adjuntar el SARIF también como artefacto del run con `actions/upload-artifact` — los hallazgos quedan accesibles independientemente del estado de GHAS. Cuando GHAS se habilite, basta eliminar el `continue-on-error` para tener integración completa con el Security tab.
+- **`upload-artifact` espera archivo no generado por step previo, con `if-no-files-found: warn` enmascara fallo silenciosamente** [CONFIRMADO 2026-05-20, SIGAF]: workflow de gitleaks con step `gitleaks detect --verbose` (sin `--report-format json --report-path X`) seguido de `actions/upload-artifact` apuntando a `path: gitleaks-report.json` que nunca se genera. `if-no-files-found: warn` (default) emite warning pero el job pasa exitoso → debugging imposible cuando aparezcan hallazgos en el futuro. Mismo patrón aplica a cualquier scanner que NO emite reporte por defecto (Trivy, Semgrep sin `--output`, OWASP ZAP). Causa: dos suposiciones no validadas — (1) el scanner emite el reporte automáticamente (FALSO en muchos casos), (2) `warn` es defecto seguro (FALSO si el archivo se espera). Solución: cuando un step de CI consume archivo producido por step previo, verificar (a) el comando genera ese archivo (leer docs del CLI, no asumir), (b) `if-no-files-found: error` (no `warn`) en uploads críticos donde la ausencia del archivo indica fallo real, (c) si el archivo es opcional (ej. cobertura), `warn` es correcto pero documentar por qué. Verificación pre-push: descargar el CLI del scanner localmente y ejecutarlo contra el repo para confirmar que el flag de output funciona como se espera (patrón validado: detectó 12 CVEs reales antes del push en sesión SIGAF 2026-05-20).
 
 ## Integración con skills SWL existentes
 

package/habilidades/fastapi-experto/SKILL.md

@@ -5,12 +5,12 @@ description: >
   testing con httpx. Incluye el anti-patrón crítico MissingGreenlet (lazy loading
   en async). Cargar cuando se implementen endpoints FastAPI, schemas Pydantic v2,
   queries SQLAlchemy async, WebSockets, SSE o tests de integración con httpx.
-version: "1.2.0"
+version: "1.3.0"
 evolved: true
-evolved-from: "1.1.2"
-evolved-at: "2026-05-10"
+evolved-from: "1.2.0"
+evolved-at: "2026-05-20"
 evolved-by: "aprender"
-evolved-note: "2 reglas nuevas en sesión SIGM Opción B: response_model=dict obsoleto vs Envelope[T] tipado, RETURNING * sin soporte de JOINs (refactor a 2 queries con _SQL_X_ENRIQUECIDA)"
+evolved-note: "2 gotchas nuevos SIGAF 2026-05-15: setattr con strings inventados en whitelist bypassea persistencia silenciosamente (extiende gotcha getattr); ClassVar[frozenset] como patrón positivo para whitelists de PATCH endpoints"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para proyectos Django o Flask — los patrones de ORM sync, Class-Based Views y middleware difieren fundamentalmente; cargar `django-experto` o el skill del framework correspondiente."
@@ -222,6 +222,51 @@ class Factura(Base):
 - **`response_model=dict` produce `{[key:string]:unknown}` en `openapi-typescript` — tipos inútiles para frontend**: declarar endpoints con `response_model=dict` (placeholder) hace que el codegen `openapi-typescript` genere responses tipados como objeto vacío. El frontend lee campos via `.id`, `.monto` con type assertions implícitas → mismatches silenciosos en runtime cuando los nombres del backend cambian. Causa: FastAPI sin schema concreto no documenta el shape en `/openapi.json`. Fix: SIEMPRE declarar `response_model=EnvelopeResponse[Schema]`, `EnvelopePaginatedResponse[Schema]`, `EnvelopeOffsetResponse[Schema]` o `EnvelopeResponse[MensajeResponse]` con un schema Pydantic concreto. Genéricos `EnvelopeResponse[T] / EnvelopePaginatedResponse[T] / EnvelopeOffsetResponse[T] / MensajeResponse` deben vivir en `app/common/response.py` (Pydantic v2 + Generic[T]). Excepción única documentable: `StreamingResponse` (PDF/CSV) puede usar `response_model=dict` con comentario explicativo. Caso real: 155 endpoints SIGM refactorizados (2026-05-10) tras descubrir que el codegen producía tipos vacíos por `response_model=dict` heredado.
 - **Pydantic + PostgreSQL `RETURNING *` no soporta JOINs en INSERT/UPDATE — refactor a 2 queries**: para mutaciones que devuelven un schema enriquecido con JOINs (ej: `cajero_nombre` desde `usuario.usuario`, `clave_catastral` desde `cuenta_predial`), `INSERT/UPDATE ... RETURNING *` no permite agregar JOINs. Causa: PostgreSQL `RETURNING` solo accede a las columnas de la tabla afectada. Fix: refactorizar a 2 queries: (1) `INSERT/UPDATE ... RETURNING id`; (2) `SELECT ... FROM tabla LEFT JOIN ... WHERE id = $1`. Costo: 1 round-trip extra (sub-1ms en LAN). Beneficio: el método siempre devuelve el shape enriquecido, mappers consistentes entre `crear`, `obtener` y `listar`. Patrón DRY: extraer la query SELECT a constante de clase (`_SQL_X_ENRIQUECIDA`) para reusar entre métodos. Caso: `crear_solicitud_descuento`, `autorizar_descuento`, `obtener_solicitud_descuento` y `listar_solicitudes_pendientes` comparten `_SQL_SOLICITUD_ENRIQUECIDA` con LEFT JOIN a `cuenta_predial` + `usuario` (cajero/supervisor).
 
+- **`setattr(modelo, "col_inventada", valor)` con whitelist `_CAMPOS_MUTABLES` que referencia columnas inexistentes — bypass silencioso de persistencia**: extensión del gotcha "getattr con nombre inventado" al lado opuesto (escritura). Caso real SIGAF 2026-05-15 NEM-074 F-01: `OficioCedulaService._CAMPOS_MUTABLES = frozenset({"cuerpo_texto", "documento_firmado_subido_at", ...})` con strings que NO eran columnas del modelo (reales: `"contenido"`, `"documento_firmado_fecha"`). El endpoint `PATCH /oficios/cedulas/{id}` aceptaba el payload, ejecutaba `setattr(cedula, "cuerpo_texto", ...)` SIN error (Python permite asignar atributos arbitrarios), pero SQLAlchemy NO persistía nada porque el atributo no era columna mapeada. Respuesta HTTP 200 con body actualizado, BD intacta. Bug invisible en monitoring. Causa: `setattr` opera sobre `__dict__` del objeto Python, no sobre el mapeo SQLAlchemy. Solución preventiva: verificar la whitelist contra el modelo ANTES de declararla. Patrón de auditoría:
+```bash
+# Listar columnas reales del modelo
+grep -nE "^\s*\w+\s*:\s*Mapped" backend/app/modules/<modulo>/models.py | awk -F: '{print $2}' | awk '{print $1}'
+
+# Comparar contra la whitelist en el service
+grep -nE "_CAMPOS_MUTABLES" backend/app/modules/<modulo>/service.py
+```
+Test obligatorio para CADA whitelist `_CAMPOS_MUTABLES_*`:
+```python
+def test_campos_mutables_son_columnas_reales():
+    columnas_modelo = {col.key for col in OficioCedula.__mapper__.columns}
+    no_existentes = OficioCedulaService._CAMPOS_MUTABLES - columnas_modelo
+    assert not no_existentes, f"Whitelist con campos inexistentes: {no_existentes}"
+```
+Extender este gotcha al UNIVERSO de strings que referencian columnas ORM en código Python: `getattr(modelo, "X", default)` (default silencioso), `setattr(modelo, "X", v)` (asigna a namespace, NO persiste), `frozenset({"X", ...})` en whitelist (pasa al setattr ciego), `text("INSERT INTO X (col) ...")` (falla en runtime), `Model.X` en `where()` (AttributeError build-time — único que falla rápido). Los 4 primeros son silenciosos; el último el único que avisa.
+
+- **`_CAMPOS_MUTABLES` declarado como variable local del método se re-crea en cada invocación y no es inspeccionable** (patrón positivo SIGAF DT-VERIF-2 2026-05-15): whitelists locales son no auditables desde tests y duplican definición en archivos hermanos. Patrón correcto: declarar como `ClassVar[frozenset[str]]` de la clase del service.
+```python
+from typing import ClassVar
+
+class CedulasService:
+    _CAMPOS_MUTABLES_CEDULA_PRELIMINAR: ClassVar[frozenset[str]] = frozenset({
+        "fecha_emision", "fecha_notificacion", "contenido",
+    })
+    _CAMPOS_MUTABLES_CEDULA_DEFINITIVA: ClassVar[frozenset[str]] = frozenset({...})
+    _CAMPOS_MUTABLES_OBSERVACION_DERIVADA: ClassVar[frozenset[str]] = frozenset({...})
+
+    @staticmethod
+    async def actualizar_cedula_preliminar(db, data, cedula_id):
+        cedula = await db.get(CedulaPreliminar, cedula_id)
+        for campo, valor in data.model_dump(exclude_unset=True).items():
+            if campo not in CedulasService._CAMPOS_MUTABLES_CEDULA_PRELIMINAR:
+                logger.warning("campo_no_mutable_ignorado", campo=campo)
+                continue
+            setattr(cedula, campo, valor)
+```
+Beneficios:
+- Inspección desde tests: `assert "estatus" not in CedulasService._CAMPOS_MUTABLES_CEDULA_PRELIMINAR`.
+- Frozenset NO se re-crea en cada invocación (eficiencia marginal pero medible en endpoints high-throughput).
+- Documentación implícita: las whitelists son parte del contrato público de la clase.
+- Anti-duplicación: si dos services hermanos requieren la misma whitelist, consolidarla en una clase base común.
+
+Regla: para cualquier whitelist usada en `setattr` ciego (PATCH endpoints, factory methods, deserializadores manuales), declarar como `ClassVar[frozenset[str]]` de la clase del service. NUNCA como variable local del método. NUNCA como módulo-level constant fuera de la clase (pierde el namespacing).
+
 ## Referencias especializadas
 
 | Tema | Archivo |

package/habilidades/harness-claude-code/SKILL.md

@@ -10,7 +10,7 @@ description: >
   Cargar cuando el usuario reporte "se acabó la cuota", se prepare una
   sesión Opus larga (>2h), se planifique adopción de MCP servers, o se
   detecte context-rot recurrente.
-version: "1.0.0"
+version: "1.0.1"
 evolved: false
 herramientasPermitidas: [Read]
 exclusiones:
@@ -268,6 +268,9 @@ Sin observar la métrica, no puedes optimizarla.
 - **`/clear` mid-session destruye el plan en curso**: usuario pierde el roadmap acumulado. Causa: confundir `/clear` con `/compact`. Solución: `/compact` resume manteniendo conocimiento; `/clear` empieza desde cero. Antes de `/clear`, escribir un handoff a `.planning/COMPACTACION.md` con `/swl:compactar`.
 - **Tag files con `@` apuntando a archivos enormes**: Claude carga el archivo completo en contexto aunque solo necesite una sección. Causa: usar `@` con archivos >500 líneas. Solución: para archivos grandes, citar sección específica en el prompt (`@ src/auth.py líneas 100-150`) o pre-extraer con `Read offset/limit`.
 - **`/effort high` que se queda activo en prompts simples**: el siguiente prompt trivial gasta 2× tokens innecesarios. Causa: el effort se interpreta como "session-wide" cuando es per-prompt. Solución: explícito `/effort medium` (o lo que aplique) en el siguiente prompt si la complejidad bajó.
+- **`child_process.spawn(cmd, args, { env: {} })` REEMPLAZA el env del padre con vacío, NO hereda** [CONFIRMADO 2026-05-18]: el cliente MCP de Claude Code (y el de Cursor) lee `mcpServers.X.env` del config JSON y lo pasa literal al spawn. Si la config tiene `"env": {}` explícito, el binario hijo arranca SIN ninguna variable de entorno del padre — rompe la herencia de apiKeys que viven en HKCU/registry. Síntoma: MCP server da `40101 Authorization required` aunque `setx OBSIDIAN_API_KEY` esté correcto en HKCU y curl con esa key responda HTTP 200 al plugin. Causa: Node `child_process.spawn` con `env: {}` ≠ sin `env` option. Solución: **OMITIR la clave `env` por completo en el JSON** (no dejarla vacía). Verificado empíricamente con `spawn(binario, [], { /* sin env */ })` → binario heredó `OBSIDIAN_API_KEY`; `spawn(binario, [], { env: {} })` → binario sin env. El patch SWL para Python (`scripts/lib/mcp_config.py::build_stdio_env`) merge `os.environ + overrides` para corregir el mismo síntoma en el lado Python.
+- **MCP server devuelve auth error con apiKey correcta en disco → el proceso vivo arrancó con apiKey vieja** [CONFIRMADO 2026-05-18]: aunque `~/.cursor/mcp.json` y `~/.claude/settings.json` tengan la apiKey actual del plugin, los procesos del binario MCP (ej. `mcp-obsidian.exe`) que ya están corriendo retuvieron la apiKey del momento de su spawn. Síntoma: actualizar JSONs no soluciona 40101. Solución: `taskkill /F /IM mcp-obsidian.exe /T` (Windows) o `pkill mcp-obsidian` (Unix) + **quit total del cliente parent** (Cursor.exe / claude.exe) — no basta reload de ventana. Al reabrir, el cliente respawnea el binario con env actual. Verificar con `ps -W | grep mcp-obsidian` que solo haya procesos con timestamp posterior al reinicio.
+- **Cursor y Claude Code CLI dentro de Cursor son clientes MCP DISTINTOS con procesos independientes** [CONFIRMADO 2026-05-18]: cuando se ejecuta Claude Code CLI en una terminal embebida de Cursor, hay DOS procesos del binario MCP corriendo simultáneamente — uno por cliente. Cada uno lee SU PROPIA config: Cursor lee `~/.cursor/mcp.json`, Claude Code CLI lee `~/.claude/settings.json` + `<proyecto>/.claude/settings.local.json`. Una apiKey actualizada en uno no propaga al otro. Síntoma observado: el agente AI de Cursor responde MCP OK pero Claude Code CLI da 40101 (o viceversa). Solución: usar variable de entorno persistente del SO (`setx OBSIDIAN_API_KEY` → HKCU\Environment) como single source of truth y dejar configs JSON sin clave `env` para heredar del padre. Cada regeneración de apiKey requiere un solo `setx` + reiniciar Cursor (que reinicia ambos clientes).
 
 ---