@saulwade/swl-ses 1.7.4 → 1.9.0

package/habilidades/proceso-dynamic-workflows/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: proceso-dynamic-workflows
+description: >
+  Patrones canónicos de dynamic workflows en Claude Code (Workflow tool / ultracode):
+  classify-and-act, fan-out-and-synthesize, adversarial-verification, generate-and-filter,
+  tournament. Cubre los 3 modos de falla que justifican orquestar (agentic laziness,
+  self-preferential bias, goal drift), cuándo NO usar workflows, token budgets, revisión
+  cross-modelo, y el anti-patrón de envolver skills auto-iterantes en /loop|/cron. Cargar
+  cuando se diseñe una orquestación multi-agente, se decida si una tarea amerita workflow,
+  o se quiera empaquetar un workflow como plantilla reutilizable en un skill.
+when_to_use: >
+  Usar cuando el usuario diga "ultracode", "workflow", "orquesta esto", "fan-out", "panel
+  de revisores", "tournament", o cuando una tarea sea larga, masivamente paralela o
+  adversarial y un solo context window sufra laziness/goal-drift.
+herramientasPermitidas: [Read, Grep, Glob]
+exclusiones:
+  - "No cargar para tareas de codificación normales de un solo paso — la mayoría NO necesitan un workflow; el harness por defecto basta y un workflow gasta muchos más tokens."
+  - "No cargar para el detalle de evaluator-optimizer del nemesis — eso vive en nemesis-evaluacion-json y el comando /swl:nemesis."
+  - "No cargar para escribir el .js de un workflow concreto — este skill da los patrones; el script se escribe con el Workflow tool directamente."
+---
+
+# Dynamic workflows: patrones, modos de falla y cuándo orquestar
+
+Síntesis del blog oficial de Anthropic *"A harness for every task: dynamic workflows
+in Claude Code"* + patrones validados en swl-ses (nemesis evaluator-optimizer,
+`/swl:verificar --until-converge`, `/swl:autoresearch`). Un dynamic workflow deja que
+Claude escriba su propio harness (JS que coordina subagentes con ventanas aisladas).
+
+## Cuándo cargar
+
+- Se va a diseñar una orquestación multi-agente o decidir si una tarea amerita workflow.
+- La tarea es larga, masivamente paralela, o adversarial (review, research, migración, triage).
+- Se quiere empaquetar un workflow como plantilla reutilizable en un skill.
+
+## Cuándo NO cargar
+
+- Tarea de codificación normal de 1-2 archivos — el harness por defecto basta. Un workflow
+  gasta significativamente más tokens; la mayoría de tareas de coding NO necesitan un panel
+  de 5 revisores.
+- Ya estás dentro del detalle del nemesis (`nemesis-evaluacion-json`).
+- Solo necesitas escribir el `.js` — usa el Workflow tool directo con los patrones de abajo.
+
+## Los 3 modos de falla que JUSTIFICAN orquestar
+
+Un solo context window largo degrada de tres formas — nombrarlas guía cuándo separar Claudes:
+
+1. **Agentic laziness** — Claude se detiene antes de terminar una tarea multi-parte y la
+   declara hecha con progreso parcial (ej. 20 de 50 ítems de un security review). Mitiga:
+   fan-out (un subagente por ítem, ventana limpia) + `/goal` (requisito de completitud duro).
+2. **Self-preferential bias** — Claude prefiere sus propios resultados al verificarlos contra
+   un rubric. Mitiga: **adversarial-verification** con subagente separado, y mejor aún
+   **revisión cross-modelo** (el reviewer es OTRO modelo). Es el mismo principio que
+   `gobernanza.md § Separación revisor/ejecutor`.
+3. **Goal drift** — pérdida gradual de fidelidad al objetivo tras muchos turnos y compaction
+   (cada resumen es lossy; se pierde "no hagas X"). Mitiga: subagentes con goal aislado y
+   constraints explícitas por invocación; `/goal` como ancla.
+
+## Los 5 patrones canónicos
+
+| Patrón | Cuándo | Forma |
+|--------|--------|-------|
+| **Classify-and-act** | Rutear según tipo de tarea/ítem | Clasificador → ramas distintas (al inicio o al final para decidir output) |
+| **Fan-out-and-synthesize** | Muchos sub-pasos; cada uno se beneficia de ventana limpia sin cross-contaminación | N agentes en paralelo → barrier → synthesize merge. **Default** para descomponer |
+| **Adversarial-verification** | Evitar self-preferential bias | Por cada agente, un agente separado verifica su output contra rubric. Diversificar lentes |
+| **Generate-and-filter** | Espacio de ideas amplio (taste-based) | Generar N → filtrar por rubric/verificación → dedupe → solo las mejores probadas |
+| **Tournament** | Solución taste-based con criterio | N agentes compiten con enfoques distintos → juez pairwise hasta ganador |
+
+`pipeline()` (sin barrier entre stages) es el default; usa barrier (`parallel()` entre
+stages) SOLO cuando el stage N necesita TODOS los resultados del N-1 (dedup global,
+early-exit por conteo cero, comparación cruzada).
+
+## Revisión cross-modelo (combate self-preferential bias estructuralmente)
+
+El reviewer adversarial en el MISMO modelo aún arrastra sesgo. La mejora: **executor en un
+modelo, reviewer en otro** (Claude ejecuta → Gemini/Codex/otro revisa). Patrón de ARIS
+(`mcp-servers/gemini-review`): MCP que expone `review`/`review_reply`, devuelve JSON con
+`threadId` + `response` → rastro auditable de un veredicto independiente.
+
+En swl-ses esto es **opt-in** vía `/swl:nemesis --cross-model` (ver el comando): si hay un
+MCP reviewer configurado, la verificación se rutea a un modelo externo; si no, degrada al
+reviewer same-model sin fallar (regla `arreglar-al-detectar.md` / no-fallback-silencioso →
+se anuncia la degradación). Mejoras del reviewer (de ARIS `auto-review-loop`):
+- **Reviewer memory**: el reviewer arrastra sus sospechas entre rondas (un solo `threadId`),
+  no parte de cero cada iteración.
+- **Debate protocol**: el executor puede rebatir; el reviewer falla el veredicto final —
+  *"it can drive, never acquit"* (el loop conduce, el jurado decide).
+- **POSITIVE_THRESHOLD compuesto**: `score ≥ N` **AND** `verdict ∈ {ready, almost}` — un
+  score alto con verdict "not ready" NO detiene el loop.
+
+## Anti-patrón: no envolver un skill auto-iterante en /loop · /cron · /schedule
+
+Si un skill YA itera internamente (review→fix→re-review con memoria de reviewer en un
+`threadId`), envolverlo en `/loop`, `/schedule` o `CronCreate` lo re-entra desde cero cada
+tick → `threadId` nuevo, memoria del reviewer reseteada → dispara el veredicto por
+wall-clock en vez de por cambio de artefacto: cero señal nueva, costo de tokens completo.
+Aplica a `/swl:autoresearch`, `/swl:verificar --until-converge`, nemesis `--remediar`. Si
+hay que agendar algo, agenda **la espera externa que lo precede** (ej. experimentos listos →
+entonces corre el loop UNA vez), no el loop mismo.
+
+## Token budgets, /goal y model routing
+
+- **Token budget en workflows**: el global `budget` (o "use 10k tokens" en el prompt) pone
+  cap duro. Alinea con `scripts/lib/budget-enforcer.js` de swl-ses.
+- **/goal + /loop**: para workflows repetibles (triage, research, verificación), `/goal` da
+  requisito de completitud y `/loop` la cadencia. NO sobre skills auto-iterantes (arriba).
+- **Dynamic model routing**: un agente clasificador investiga la complejidad real del scope
+  y rutea a Sonnet vs Opus por tarea (más fino que el Model-Tier estático del frontmatter).
+
+## Workflows como plantillas en skills
+
+Un `.js` de workflow puede vivir en `recursos/` de un skill y referenciarse en su SKILL.md
+como **plantilla** (no script verbatim) — Claude lo adapta al caso. Plantillas incluidas:
+
+- `recursos/template-adversarial-verify.js` — fan-out de hallazgos + verificación adversarial
+  por hallazgo (filtra los reales).
+- `recursos/template-triage.js` — clasifica ítems de un backlog, dedupe contra lo ya
+  trackeado, y rutea (fix automático vs escalar a humano) con patrón quarantine.
+
+## Quarantine (triage de contenido no confiable)
+
+En triage que lee contenido público/no confiable, los agentes lectores quedan **barred** de
+acciones de alto privilegio; esas las ejecutan agentes distintos que actúan sobre la info ya
+saneada. Coherente con `seguridad-agentes.md § Prompt injection` y el quarantine de SWL.
+
+## Gotchas
+
+- **Workflows gastan más tokens** — úsalos cuando la tarea de verdad necesita más cómputo
+  (adversarial, masivamente paralela), no por reflejo.
+- **Subagentes heredan el contexto del padre** (CLAUDE.md + reglas globales). En proyectos
+  rule-heavy pueden saturar al arrancar (autocompact thrashing). Pasa scope acotado y evita
+  hacer que el subagente explore el codebase completo (ver `harness-claude-code`).
+- **Barrier injustificado** mata wall-clock: si no hay dependencia cross-ítem entre stages,
+  usa `pipeline()`, no `parallel()` entre stages.
+
+## Origen
+
+Adoptado 2026-06-05 desde análisis de `temp/` (blog Anthropic dynamic-workflows +
+ARIS `auto-review-loop`/`mcp-servers`). Ver APRENDIZAJES.md Tipo D 2026-06-05.

package/habilidades/proceso-dynamic-workflows/recursos/template-adversarial-verify.js

@@ -0,0 +1,65 @@
+// PLANTILLA (no ejecutar verbatim) — Workflow tool de Claude Code.
+// Patrón: fan-out de hallazgos -> verificación adversarial por hallazgo -> filtrar reales.
+// Combate self-preferential bias y agentic laziness. Adapta DIMENSIONS, rubrics y schemas.
+//
+// Uso: el agente lee esta plantilla, la ajusta al caso concreto y la pasa al Workflow tool.
+
+export const meta = {
+  name: 'adversarial-verify',
+  description: 'Revisa por dimensiones y verifica cada hallazgo adversarialmente antes de aceptarlo',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+
+// Dimensiones de revisión — una por lente independiente (no se contaminan entre sí).
+const DIMENSIONS = [
+  { key: 'correctness', prompt: 'Revisa SOLO correctness del scope. Devuelve hallazgos.' },
+  { key: 'security', prompt: 'Revisa SOLO seguridad del scope. Devuelve hallazgos.' },
+  { key: 'dry', prompt: 'Revisa SOLO duplicación/DRY del scope. Devuelve hallazgos.' },
+]
+
+const FINDINGS = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          title: { type: 'string' }, file: { type: 'string' }, line: { type: 'string' },
+          severity: { type: 'string', enum: ['critico', 'mayor', 'menor'] },
+        },
+        required: ['title', 'file', 'severity'],
+      },
+    },
+  },
+  required: ['findings'],
+}
+
+const VERDICT = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    isReal: { type: 'boolean' },
+    reason: { type: 'string' },
+  },
+  required: ['isReal', 'reason'],
+}
+
+// pipeline (sin barrier): cada dimensión verifica sus hallazgos en cuanto su review termina.
+const results = await pipeline(
+  DIMENSIONS,
+  (d) => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
+  (review, d) =>
+    parallel(
+      (review?.findings || []).map((f) => () =>
+        // Verificador adversarial: prompt orientado a REFUTAR (default refutado si dudoso).
+        agent(
+          `Intenta REFUTAR este hallazgo contra el código real (cita archivo:linea). ` +
+          `Si no puedes probarlo, isReal=false: ${JSON.stringify(f)}`,
+          { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT }
+        ).then((v) => ({ ...f, verdict: v }))
+      )
+    )
+)
+
+const confirmados = results.flat().filter(Boolean).filter((f) => f.verdict?.isReal)
+return { confirmados }

package/habilidades/proceso-dynamic-workflows/recursos/template-triage.js

@@ -0,0 +1,65 @@
+// PLANTILLA (no ejecutar verbatim) — Workflow tool de Claude Code.
+// Patrón: classify-and-act + quarantine. Clasifica ítems de un backlog, dedupe contra lo
+// ya trackeado, y rutea: fix automático (bajo riesgo) vs escalar a humano (alto riesgo).
+// Quarantine: el agente que LEE contenido no confiable NO ejecuta acciones de alto privilegio.
+//
+// `args` = lista de ítems del backlog (issues, reportes, etc.). Adapta schemas y umbrales.
+
+export const meta = {
+  name: 'triage',
+  description: 'Clasifica un backlog, dedupe contra lo trackeado y rutea fix-vs-escalar (con quarantine)',
+  phases: [{ title: 'Clasificar' }, { title: 'Actuar' }],
+}
+
+const items = Array.isArray(args) ? args : []
+
+const CLASIFICACION = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    categoria: { type: 'string', enum: ['bug', 'feature', 'duplicado', 'ruido'] },
+    yaTrackeado: { type: 'boolean' },
+    riesgo: { type: 'string', enum: ['bajo', 'alto'] },
+    resumen: { type: 'string' },
+  },
+  required: ['categoria', 'yaTrackeado', 'riesgo', 'resumen'],
+}
+
+const ACCION = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    accion: { type: 'string', enum: ['fix-aplicado', 'escalado-humano', 'descartado'] },
+    detalle: { type: 'string' },
+  },
+  required: ['accion', 'detalle'],
+}
+
+// Stage 1 (quarantine): clasificador LEE el ítem (posible contenido no confiable) pero NO
+// tiene permiso de actuar — solo emite estructura. Stage 2 actúa sobre data ya saneada.
+const triaged = await pipeline(
+  items,
+  (item) =>
+    agent(
+      `Clasifica este ítem del backlog. NO ejecutes ninguna acción: solo describe. ` +
+      `Marca yaTrackeado=true si ya existe ticket. Ítem: ${JSON.stringify(item)}`,
+      { label: 'clasificar', phase: 'Clasificar', schema: CLASIFICACION }
+    ),
+  (clf, item) => {
+    if (!clf || clf.yaTrackeado || clf.categoria === 'ruido' || clf.categoria === 'duplicado') {
+      return { accion: 'descartado', detalle: clf?.resumen || 'sin señal' }
+    }
+    if (clf.riesgo === 'alto') {
+      // Alto riesgo: escalar a humano, no auto-actuar.
+      return agent(
+        `Redacta un escalamiento conciso para humano sobre: ${clf.resumen}`,
+        { label: 'escalar', phase: 'Actuar', schema: ACCION }
+      )
+    }
+    // Bajo riesgo: el agente que ACTÚA es distinto del que leyó contenido no confiable.
+    return agent(
+      `Aplica el fix de bajo riesgo para: ${clf.resumen}. Devuelve qué hiciste.`,
+      { label: 'fix', phase: 'Actuar', schema: ACCION }
+    )
+  }
+)
+
+return triaged.filter(Boolean)

package/habilidades/swl-claudemd/SKILL.md

@@ -279,7 +279,7 @@ El sistema tiene dos capas de protección complementarias:
 | Capa | Mecanismo | Cuándo actúa | Bloqueo |
 |------|-----------|--------------|---------|
 | Síncrona | Paso 6.5 de `/swl:aprender` (y equivalente en otros comandos) | Justo después del Write/Edit, antes del reporte final | Bloquea pasos posteriores hasta resolver |
-| Asíncrona | Hook `claudemd-bloat-detector.js` (PostToolUse) | Tras cualquier Write/Edit/MultiEdit a CLAUDE.md (incluso fuera de comandos SWL) | No bloquea — emite nudge a `.planning/evolucion/nudges.jsonl` |
+| Asíncrona | Hook `claudemd-bloat-detector.js` (PostToolUse) | Tras cualquier Write/Edit/MultiEdit a CLAUDE.md (incluso fuera de comandos SWL) | No bloquea — emite nudge a `.planning/evolution/nudges.jsonl` |
 
 La capa síncrona es proactiva (detiene el comando antes de reportar
 éxito). La asíncrona es retroactiva (cubre escrituras desde fuera de
@@ -370,7 +370,7 @@ Reglas incluidas en v1.7.0:
 
 `hooks/claudemd-duplicacion-detector.js` (PostToolUse, no bloquea)
 ejecuta el detector tras cualquier Write/Edit a CLAUDE.md y emite
-nudge a `.planning/evolucion/nudges.jsonl` con `kind:
+nudge a `.planning/evolution/nudges.jsonl` con `kind:
 claudemd-duplicacion-reglas`. Opt-out: `SWL_CLAUDEMD_DUPLICACION=0`.
 
 ### Cómo refactorizar duplicaciones detectadas

package/habilidades/tdd-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.6"
+version: "1.1.0"
 evolved: true
 evolved-from: "1.0.4"
 evolved-at: "2026-05-16"
@@ -40,6 +40,19 @@ que los tests exigen — ni más, ni menos.
 
 ---
 
+## Etapa opcional previa: Gherkin (BDD) y gate de mutación
+
+Dos extensiones opt-in del ciclo, ambas con guía completa en recursos:
+
+- **Antes del ciclo** — si la fase tiene criterios de aceptación de negocio,
+  convertirlos en escenarios Given–When–Then validados por el usuario ANTES de
+  implementar; cada escenario es el test RED de su criterio. Guía, runners por
+  stack y anti-patrones en [recursos/gherkin-bdd.md](recursos/gherkin-bdd.md).
+- **Después del ciclo** — en módulos críticos, verificar la calidad de los
+  asserts con mutation testing incremental sobre el diff:
+  `Skill("calidad-mutation-testing")`. La cobertura mide ejecución; los
+  mutantes sobrevivientes miden si los tests detectarían un bug.
+
 ## El ciclo fundamental RED → GREEN → REFACTOR
 
 ### Fase RED — El test debe fallar por la razón correcta

package/habilidades/tdd-workflow/recursos/gherkin-bdd.md

@@ -0,0 +1,111 @@
+# Etapa Gherkin (BDD) — de criterios de aceptación a tests ejecutables
+
+Etapa opt-in previa al ciclo RED→GREEN→REFACTOR que convierte los criterios de
+aceptación del CONTEXTO.md/PRD en escenarios **Given–When–Then** ejecutables.
+Cierra el hueco entre "lo que el negocio pidió" y "lo que los tests verifican":
+cada escenario es a la vez especificación legible por el usuario y esqueleto
+del test.
+
+Inspirada en el flujo de Robert C. Martin (spec → hard spec → Gherkin → TDD →
+mutation testing): el Gherkin es la "hard spec" verificable; el ciclo TDD la
+implementa; el mutation testing (`Skill("calidad-mutation-testing")`) verifica
+la suite resultante.
+
+## Cuándo usar la etapa (y cuándo no)
+
+**Usar cuando**: la fase tiene criterios de aceptación de negocio (PRD o
+CONTEXTO.md con decisiones cerradas), el comportamiento tiene reglas con casos
+distinguibles (descuentos, permisos, estados), o el usuario validará la spec
+sin leer código.
+
+**NO usar cuando**: la fase es técnica pura (refactor, migración, infra), los
+criterios son triviales (CRUD sin reglas), o no hay quien lea los escenarios —
+Gherkin sin lector de negocio es ceremonia que duplica los tests.
+
+## Formato
+
+```gherkin
+# language: es
+Característica: Descuento por nivel de cliente
+  Como cliente premium quiero recibir mi descuento automático
+  para no capturar cupones manualmente.
+
+  Escenario: Cliente premium recibe 15% en compras normales
+    Dado un cliente con nivel "premium"
+    Cuando realiza una compra de $100.00 MXN
+    Entonces el descuento aplicado es de $15.00 MXN
+
+  Esquema del escenario: Descuento por nivel
+    Dado un cliente con nivel "<nivel>"
+    Cuando realiza una compra de $<monto> MXN
+    Entonces el descuento aplicado es de $<descuento> MXN
+
+    Ejemplos:
+      | nivel    | monto  | descuento |
+      | normal   | 100.00 | 0.00      |
+      | premium  | 100.00 | 15.00     |
+      | mayorista| 100.00 | 22.00     |
+```
+
+Reglas de redacción:
+
+- **Un comportamiento por escenario** — si necesitas "Y cuando..." encadenados,
+  son dos escenarios.
+- **Lenguaje del dominio, no de la implementación**: "Dado un cliente premium",
+  NUNCA "Dado un row en la tabla clientes con tipo=2".
+- **Valores concretos** en los ejemplos — los criterios vagos ("un monto
+  válido") no son verificables.
+- **Esquema del escenario** para reglas con tabla de casos — es la forma
+  natural de los tests de frontera de `pruebas.md`.
+- Español de México (`# language: es`) — los escenarios los lee el usuario.
+
+## Derivación desde CONTEXTO.md / PRD
+
+1. Tomar cada criterio de aceptación cerrado del CONTEXTO.md (o historia del PRD).
+2. Reescribirlo como 1-N escenarios: el caso feliz + las fronteras + el caso de error.
+3. Presentar los escenarios al usuario para validación ANTES de implementar —
+   este es el checkpoint humano del flujo: corregir una spec cuesta una
+   conversación; corregir la implementación cuesta un refactor.
+4. Los escenarios validados se guardan en `tests/features/<dominio>.feature`
+   y el PLAN.md referencia qué tarea implementa cada escenario.
+
+## Runners por stack
+
+| Stack | Runner | Binding típico |
+|-------|--------|----------------|
+| Python | `pytest-bdd` (o `behave`) | `@scenario("features/descuento.feature", "Cliente premium...")` + steps con `@given/@when/@then` |
+| JS/TS | `@cucumber/cucumber` | steps en `features/steps/*.ts` con `Given/When/Then` |
+| C#/.NET | Reqnroll (sucesor de SpecFlow) | bindings `[Given]/[When]/[Then]` |
+| Java | Cucumber-JVM | anotaciones `@Given/@When/@Then` |
+
+Verificar versión vigente con Context7 antes de instalar (regla `usar-context7.md`).
+
+Los steps son **pegamento delgado**: parsean el Gherkin y llaman al mismo
+código de test que usaría el ciclo TDD (factories incluidas). La lógica de
+verificación vive en los asserts, no en los steps.
+
+## Integración con el ciclo TDD
+
+```
+CONTEXTO.md/PRD → escenarios Gherkin → validación del usuario (checkpoint)
+      → por cada escenario: RED (step sin implementar falla)
+      → GREEN (implementación mínima) → REFACTOR
+      → al cierre de fase: mutation testing opcional sobre el diff
+```
+
+Cada escenario Gherkin ES un test RED al inicio: el runner reporta steps sin
+implementar como fallos — exactamente la fase RED del ciclo. No escribir tests
+unitarios duplicados del mismo criterio: el escenario cubre el comportamiento
+de negocio; los tests unitarios cubren los detalles internos que el Gherkin
+no expresa (errores de infraestructura, edge cases técnicos).
+
+## Anti-patrones
+
+- **Gherkin imperativo de UI**: "Cuando hago clic en el botón #submit" — eso
+  es un script de Selenium disfrazado. Los escenarios describen comportamiento
+  de dominio; la UI cambia sin que la regla de negocio cambie.
+- **Escenarios escritos DESPUÉS de implementar** para "documentar" — pierde el
+  checkpoint de validación, que es el valor de la etapa.
+- **Steps con lógica de negocio** — la duplican; los steps solo traducen.
+- **Un .feature gigante por módulo** — un archivo por característica, como el
+  código.

package/habilidades/testing-python/SKILL.md

@@ -221,7 +221,7 @@ Para ejemplos detallados MAL vs BIEN de anti-patrones, ver [recursos/ejemplos-co
 - **`mock.patch` parcheado en el módulo de tests en lugar de en el módulo que lo usa**: el mock no tiene efecto porque la función ya fue importada en el módulo objetivo antes del patch. Causa: `mock.patch("tests.test_factura.calcular_iva")` parchea la referencia en el módulo de tests, pero `factura_service.py` ya importó `calcular_iva` directamente y sigue usando la original. Solución: patchear siempre en el lugar donde se usa la función: `mock.patch("factura_service.calcular_iva")` — el destino del patch debe ser la ruta del módulo que importó la función, no donde está definida.
 - **`pytest-asyncio` marca el test como `async def` y pasa, pero el `await` dentro no se ejecuta**: el test parece correr sin errores pero la coroutine interna nunca se ejecuta. Causa: sin `@pytest.mark.asyncio` o sin `asyncio_mode = "auto"` en pytest.ini, pytest ejecuta la función async como síncrona — la coroutine se crea y se descarta sin ejecutar. Solución: agregar `@pytest.mark.asyncio` al test o configurar `asyncio_mode = "auto"` en `pytest.ini`; verificar con `pytest --tb=short -v` que el test no termina instantáneamente.
 - **Factory Boy `SubFactory` genera objetos nuevos en cada test aunque el fixture del objeto padre ya existe**: la factory crea una instancia nueva del modelo relacionado en la BD aunque ya exista el objeto padre en el test. Causa: `factory.SubFactory(ClienteFactory)` siempre instancia un nuevo `Cliente` — no reutiliza el fixture del test. Solución: pasar el objeto padre existente al instanciar la factory: `FacturaFactory(cliente=cliente_existente)` — la factory sobreescribe el campo `cliente` con el objeto ya creado en lugar de crear uno nuevo.
-- **`os.chdir()` (Python) o `process.chdir()` (Node) en tests no afecta módulos cargados con paths relativos basados en `__dirname`/`__file__`**: si un módulo calcula su ruta de datos al cargar con `path.resolve(__dirname, ...)` o `Path(__file__).parent`, los tests no pueden redirigir esa ruta cambiando el cwd — el path se evaluó al `require`/`import` y queda fijado. Caso real: test que cambia `process.chdir(tmpDir)` antes de llamar funciones que escriben a `.planning/evolucion/nudges.jsonl` pero `RUTA_NUDGES = path.resolve(__dirname, '..', '..', '.planning', ...)` apunta al proyecto real. Solución: dos opciones: (1) test de integración con backup/restore del archivo real (más simple cuando son pocos tests), o (2) refactor del módulo para aceptar override de ruta vía parámetro o variable de entorno (preferible si el módulo es muy testeable). Aplica también a Python con `pathlib.Path(__file__).parent`.
+- **`os.chdir()` (Python) o `process.chdir()` (Node) en tests no afecta módulos cargados con paths relativos basados en `__dirname`/`__file__`**: si un módulo calcula su ruta de datos al cargar con `path.resolve(__dirname, ...)` o `Path(__file__).parent`, los tests no pueden redirigir esa ruta cambiando el cwd — el path se evaluó al `require`/`import` y queda fijado. Caso real: test que cambia `process.chdir(tmpDir)` antes de llamar funciones que escriben a `.planning/evolution/nudges.jsonl` pero `RUTA_NUDGES = path.resolve(__dirname, '..', '..', '.planning', ...)` apunta al proyecto real. Solución: dos opciones: (1) test de integración con backup/restore del archivo real (más simple cuando son pocos tests), o (2) refactor del módulo para aceptar override de ruta vía parámetro o variable de entorno (preferible si el módulo es muy testeable). Aplica también a Python con `pathlib.Path(__file__).parent`.
 - **Sanitizar antes de truncar invalida assertions de longitud en tests**: un test que verifica `truncar('a'.repeat(300), 100).length === 100` falla porque `'a'.repeat(300)` matchea la regex de redact `\b[A-Za-z0-9_-]{32,}\b` y la función sanitiza primero produciendo `[REDACTED]` (10 chars) que no se trunca. Causa: el orden `sanitizar → truncar` reduce el texto antes de que truncar opere. Solución en tests: usar fixtures que NO triggeren patrones de redact (ej: texto con espacios cada N chars como `'palabra corta '.repeat(N)`); separar tests de sanitización y truncado en casos disjuntos. NO modificar la función para reordenar — sanitizar antes es correcto en producción.
 
 ## Refactorizar parsers: fixtures multi-formato ANTES del cambio

package/habilidades/tracing-processor/SKILL.md

@@ -169,7 +169,7 @@ Endpoint: `JAEGER_OTLP_ENDPOINT` (por defecto `http://localhost:4318/v1/traces`)
 
 En lugar de persistir spans crudos, un exportador puede agregar en memoria:
 contar spans por tipo, sumar duraciones, detectar anomalías. En `onTraceEnd`
-emite las métricas agregadas a `.planning/evolucion/metricas.json` usando
+emite las métricas agregadas a `.planning/evolution/metricas.json` usando
 `atomicWriteJSON` de `hooks/lib/atomic-write.js`.
 
 ---

package/hooks/actualizar-perfil-usuario.js

@@ -10,7 +10,7 @@
  * persistente del usuario (instintos/perfil-usuario.yaml).
  *
  * No modifica el perfil directamente — solo acumula señales en un
- * "dirty-bit" (.planning/perfil-usuario/dirty.json) y, cuando el umbral
+ * "dirty-bit" (.planning/user-profile/dirty.json) y, cuando el umbral
  * se cruza, emite un nudge por stderr sugiriendo invocar el agente
  * perfilador-usuario-swl.
  *
@@ -60,7 +60,7 @@ try {
 // ---------------------------------------------------------------------------
 
 const UMBRAL_NUDGE = parseInt(process.env.SWL_PERFIL_UMBRAL || '3', 10);
-const DIR_PERFIL   = path.join(process.cwd(), '.planning', 'perfil-usuario');
+const DIR_PERFIL   = path.join(process.cwd(), '.planning', 'user-profile');
 const DIRTY_PATH   = path.join(DIR_PERFIL, 'dirty.json');
 const PERFIL_PATH  = path.join(process.cwd(), 'instintos', 'perfil-usuario.yaml');
 const APRENDIZAJES_PATH = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');

package/hooks/aiisms-detector.js

@@ -7,7 +7,7 @@
  *
  * Ejecuta el detector portable `habilidades/estilo-sin-ai-isms/scripts/detectar_aiisms.py`
  * contra archivos .md recién modificados y emite un nudge a
- * `.planning/evolucion/nudges.jsonl` si encuentra al menos un AI-ism
+ * `.planning/evolution/nudges.jsonl` si encuentra al menos un AI-ism
  * de severidad P0.
  *
  * Opt-out: SWL_AIISMS_HOOK=0 desactiva completamente el hook.
@@ -160,7 +160,7 @@ const nudge = {
 
 // Persistir a nudges.jsonl (JSONL append, no reescribir)
 try {
-  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
   const nudgesDir = path.dirname(nudgesPath);
   if (!fs.existsSync(nudgesDir)) {
     fs.mkdirSync(nudgesDir, { recursive: true });

package/hooks/auto-evolucion.js

@@ -105,7 +105,7 @@ const VENTANA_DIAS         = 14;
 const MIN_TOOL_CALLS       = 5;   // por debajo se considera trivial
 const MIN_INVOCACIONES_LOOP = 6;  // mínimo para que el ratio de convergencia sea significativo
 
-const DIR_AUTOEVOL  = path.join(process.cwd(), '.planning', 'auto-evolucion');
+const DIR_AUTOEVOL  = path.join(process.cwd(), '.planning', 'auto-evolution');
 const DIR_TRACES    = path.join(process.cwd(), '.planning', 'traces');
 const LOG_PATH      = path.join(DIR_AUTOEVOL, 'agentes.jsonl');
 const NUDGES_PATH   = path.join(DIR_AUTOEVOL, 'nudges.json');

package/hooks/captura-feedback-usuario.js

@@ -6,7 +6,7 @@
  * Tipo: UserPromptSubmit
  *
  * Detecta correcciones explícitas del usuario ("no hagas X", "recuerda Y",
- * "prefiero Z") y las encola en .planning/evolucion/feedback-queue.jsonl
+ * "prefiero Z") y las encola en .planning/evolution/feedback-queue.jsonl
  * para que el perfilador-usuario-swl, el ciclo AGP y /swl:aprender puedan
  * consumirlas sin depender de que el usuario ejecute comandos manualmente.
  *
@@ -104,7 +104,7 @@ function detectarFeedback(prompt) {
  */
 function encolar(hallazgo, meta) {
   try {
-    const dir = path.join(process.cwd(), '.planning', 'evolucion');
+    const dir = path.join(process.cwd(), '.planning', 'evolution');
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
     const entrada = {

package/hooks/claudemd-bloat-detector.js

@@ -6,7 +6,7 @@
  * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
  *
  * Ejecuta `scripts/auditar-claudemd.js` contra archivos `CLAUDE.md`
- * recién modificados y emite un nudge a `.planning/evolucion/nudges.jsonl`
+ * recién modificados y emite un nudge a `.planning/evolution/nudges.jsonl`
  * si el veredicto es WARN o ERROR.
  *
  * Aplica ADR-0016 (best practices Anthropic "The CLAUDE.md file"):
@@ -148,7 +148,7 @@ const nudge = {
 
 // ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
 try {
-  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
   const nudgesDir = path.dirname(nudgesPath);
   if (!fs.existsSync(nudgesDir)) {
     fs.mkdirSync(nudgesDir, { recursive: true });

package/hooks/claudemd-duplicacion-detector.js

@@ -157,7 +157,7 @@ const nudge = {
 
 // ─── Persistir a nudges.jsonl ─────────────────────────────────────────────
 try {
-  const nudgesPath = path.join(CWD, '.planning', 'evolucion', 'nudges.jsonl');
+  const nudgesPath = path.join(CWD, '.planning', 'evolution', 'nudges.jsonl');
   const nudgesDir = path.dirname(nudgesPath);
   if (!fs.existsSync(nudgesDir)) {
     fs.mkdirSync(nudgesDir, { recursive: true });