@saulwade/swl-ses 2.6.1 → 2.8.0

package/habilidades/swl-claudemd/recursos/plantillas-init.md

@@ -1,94 +1,94 @@
-# Plantillas literales de init-project / init-user
-
-Bloques exactos que `/swl:claudemd init-project` inserta en el CLAUDE.md
-generado. Este recurso es la fuente de verdad de los templates — el SKILL.md
-los referencia sin duplicarlos.
-
----
-
-## Bloque obligatorio SWL-tooling (init-project)
-
-Toda generación nueva en un proyecto destino incluye esta sub-sección literal
-(empareja el CLAUDE.md con la sección swl-ses del `.gitignore` — gestionada por
-`scripts/lib/gitignore-manifest.js`). Sin ella, un compañero del equipo no sabe
-qué archivos son del proyecto y cuáles son runtime de la herramienta:
-
-```markdown
-## SWL es tooling de desarrollo (frontera de versionado)
-
-Este proyecto usa [swl-ses](https://www.npmjs.com/package/@saulwade/swl-ses) como
-herramienta de desarrollo. Lo que SWL instala y genera **no forma parte del
-proyecto** y está en `.gitignore` (sección `# [swl-ses:inicio]`): `.claude/`
-(framework), `hooks/`, `instintos/`, `usage.db` y el runtime bajo `.planning/`
-(APRENDIZAJES, métricas, sesiones, traces, evolution, loops, locks, feature-list,
-caches del grafo, etc.).
-
-SÍ se versionan (los edita el equipo): `CLAUDE.md`, `.claude/settings.json`, el
-manifest `.swl-ses`, y las plantillas de `.planning/` — `PROYECTO.md`,
-`REQUISITOS.md`, `HOJA-RUTA.md`, `ESTADO.md`, `research/`, `adrs/`, y los
-`fases/0N-{CONTEXTO,PLAN,RESUMEN,VERIFICACION}.md`.
-
-Reinstalar/actualizar el tooling: `npx -y @saulwade/swl-ses@latest install`.
-```
-
-Justificación: la lista de qué se ignora vs qué se commitea es la **fuente de
-verdad** de `gitignore-manifest.js`. Replicarla en prosa en el CLAUDE.md del
-proyecto cierra el gap de "el .gitignore lo sabe pero el humano que lee CLAUDE.md
-no". Mantener ambas en sync: si `ENTRADAS_BASE` cambia, este bloque se actualiza.
-
----
-
-## Bloque obligatorio Karpathy (init-project)
-
-Toda generación nueva incluye esta sub-sección literal en "Reglas de
-máxima prioridad":
-
-```markdown
-### Cuatro principios de implementación (Karpathy)
-Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
-```
-
-Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
-se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
-La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
-de cualquier proyecto sin agregar opinión específica.
-
----
-
-## Check Karpathy en audit
-
-`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):
-
-- `/karpathy/i`
-- `/cuatro principios/i` o `/4 principios/i`
-- `/prevencion-sobreingenieria/`
-- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`
-
-Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
-(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:
-
-```
-CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
-prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
-(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
-```
-
-Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
-(`~/.claude/`) NO se evalúa contra este check.
-
----
-
-## Secciones canónicas: project-level vs user-level (init-user)
-
-| Sección | Project-level | User-level |
-|---|---|---|
-| Stack | Sí — del proyecto | No (varía por proyecto) |
-| Comandos | Sí — del proyecto | No |
-| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
-| Conventions | Sí — del proyecto | No |
-| Mi rol y stack preferido | No | Sí |
-| Estilo de comunicación | No | Sí |
-| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
-
-El template completo de user-level vive en el comando `/swl:claudemd`
-sección `init-user`.
+# Plantillas literales de init-project / init-user
+
+Bloques exactos que `/swl:claudemd init-project` inserta en el CLAUDE.md
+generado. Este recurso es la fuente de verdad de los templates — el SKILL.md
+los referencia sin duplicarlos.
+
+---
+
+## Bloque obligatorio SWL-tooling (init-project)
+
+Toda generación nueva en un proyecto destino incluye esta sub-sección literal
+(empareja el CLAUDE.md con la sección swl-ses del `.gitignore` — gestionada por
+`scripts/lib/gitignore-manifest.js`). Sin ella, un compañero del equipo no sabe
+qué archivos son del proyecto y cuáles son runtime de la herramienta:
+
+```markdown
+## SWL es tooling de desarrollo (frontera de versionado)
+
+Este proyecto usa [swl-ses](https://www.npmjs.com/package/@saulwade/swl-ses) como
+herramienta de desarrollo. Lo que SWL instala y genera **no forma parte del
+proyecto** y está en `.gitignore` (sección `# [swl-ses:inicio]`): `.claude/`
+(framework), `hooks/`, `instintos/`, `usage.db` y el runtime bajo `.planning/`
+(APRENDIZAJES, métricas, sesiones, traces, evolution, loops, locks, feature-list,
+caches del grafo, etc.).
+
+SÍ se versionan (los edita el equipo): `CLAUDE.md`, `.claude/settings.json`, el
+manifest `.swl-ses`, y las plantillas de `.planning/` — `PROYECTO.md`,
+`REQUISITOS.md`, `HOJA-RUTA.md`, `ESTADO.md`, `research/`, `adrs/`, y los
+`fases/0N-{CONTEXTO,PLAN,RESUMEN,VERIFICACION}.md`.
+
+Reinstalar/actualizar el tooling: `npx -y @saulwade/swl-ses@latest install`.
+```
+
+Justificación: la lista de qué se ignora vs qué se commitea es la **fuente de
+verdad** de `gitignore-manifest.js`. Replicarla en prosa en el CLAUDE.md del
+proyecto cierra el gap de "el .gitignore lo sabe pero el humano que lee CLAUDE.md
+no". Mantener ambas en sync: si `ENTRADAS_BASE` cambia, este bloque se actualiza.
+
+---
+
+## Bloque obligatorio Karpathy (init-project)
+
+Toda generación nueva incluye esta sub-sección literal en "Reglas de
+máxima prioridad":
+
+```markdown
+### Cuatro principios de implementación (Karpathy)
+Antes de implementar, refactorizar o corregir bugs: (1) **pensar antes de codificar** (no asumir en silencio), (2) **simplicidad primero** (sin abstracciones especulativas), (3) **cambios quirúrgicos** (leer archivo completo antes de editar, no refactor de oportunidad), (4) **ejecución orientada a metas** (criterios verificables, test que reproduce bugs antes del fix). Detalle + 9 ejemplos MAL→BIEN: `Skill("prevencion-sobreingenieria")` + `recursos/EXAMPLES.md`.
+```
+
+Justificación: el skill `prevencion-sobreingenieria` y su `recursos/EXAMPLES.md`
+se distribuyen con cada instalación SWL, así que la referencia siempre resuelve.
+La sub-sección compacta (5 líneas) ataca los gaps cognitivos más frecuentes
+de cualquier proyecto sin agregar opinión específica.
+
+---
+
+## Check Karpathy en audit
+
+`scripts/auditar-claudemd.js` debe verificar (search regex case-insensitive):
+
+- `/karpathy/i`
+- `/cuatro principios/i` o `/4 principios/i`
+- `/prevencion-sobreingenieria/`
+- `/Skill\(["'`]prevencion-sobreingenieria["'`]\)/`
+
+Si NO encuentra ninguna AND el archivo tiene >50 LOC AND es project-level
+(no `~/.claude/CLAUDE.md`): emitir hallazgo WARN con mensaje:
+
+```
+CLAUDE.md no menciona los cuatro principios Karpathy ni el skill
+prevencion-sobreingenieria. Considerar agregar la sub-sección compacta
+(ver /swl:claudemd init-project § Bloque obligatorio Karpathy).
+```
+
+Esta dimensión es WARN, no ERROR — guía sin imponer. CLAUDE.md user-level
+(`~/.claude/`) NO se evalúa contra este check.
+
+---
+
+## Secciones canónicas: project-level vs user-level (init-user)
+
+| Sección | Project-level | User-level |
+|---|---|---|
+| Stack | Sí — del proyecto | No (varía por proyecto) |
+| Comandos | Sí — del proyecto | No |
+| Code style | Sí — convenciones del equipo | Sí — preferencias personales (indent, naming favorito) |
+| Conventions | Sí — del proyecto | No |
+| Mi rol y stack preferido | No | Sí |
+| Estilo de comunicación | No | Sí |
+| Patrones que aplico siempre | No | Sí — meta-preferencias cross-project |
+
+El template completo de user-level vive en el comando `/swl:claudemd`
+sección `init-user`.

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

@@ -1,111 +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.
+# 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/hooks/calidad-pre-commit.js

@@ -13,12 +13,12 @@
  *
  *   Todos los archivos:
  *     - Sin credenciales hardcodeadas (password=, secret=, api_key=, token=)
- *     - Sin archivos > 1 MB siendo commiteados
+ *     - Sin archivos > 2 MB siendo commiteados
  *     - Sin pendientes (TO-DO) sin referencia a ticket/issue
  *
  *   Archivos .py / .ts / .js:
  *     - Sin console.log() de debug (.ts / .js)
- *     - Sin print() de debug (.py) — excluye print dentro de if __name__
+ *     - Sin print() de debug (.py) — permite salida del entrypoint __main__
  *
  *   Archivos .py:
  *     - Funciones públicas deben tener type hints en parámetros y retorno
@@ -53,7 +53,10 @@ const { normalizeForDetection } = require('./lib/normalize-input');
 // ---------------------------------------------------------------------------
 
 /** Tamaño máximo permitido por archivo a commitear (en bytes). */
-const LIMITE_TAMANO_BYTES = 1024 * 1024; // 1 MB
+// 2 MB: el corpus congelado de C10 (manifiestos/harness-ir.json, ~1.6 MB, fixture
+// generado por generar-harness-ir.js) es un artefacto versionado legítimo que los
+// tests de freeze leen del disco tracked; 1 MB lo bloqueaba al re-baselinear.
+const LIMITE_TAMANO_BYTES = 2 * 1024 * 1024; // 2 MB
 
 /**
  * Patrones de credenciales hardcodeadas.
@@ -210,7 +213,7 @@ function verificarTamano(rutaRelativa) {
     const mb = (tamano / (1024 * 1024)).toFixed(2);
     return {
       ok: false,
-      mensaje: `  [TAMAÑO] ${rutaRelativa}: ${mb} MB supera el límite de 1 MB`,
+      mensaje: `  [TAMAÑO] ${rutaRelativa}: ${mb} MB supera el límite de 2 MB`,
     };
   }
   return { ok: true, mensaje: '' };
@@ -294,12 +297,113 @@ function verificarConsoleLog(rutaRelativa, contenido) {
  * Reglas de exclusión:
  *   - Líneas comentadas con #
  *   - print() dentro de bloques if __name__ == '__main__'
+ *   - print() dentro de funciones de nivel superior invocadas por ese bloque
  *   - Archivos de test
  *
  * @param {string} rutaRelativa
  * @param {string} contenido
  * @returns {{ ok: boolean, mensajes: string[] }}
  */
+function buscarDelimitadorTriple(linea, delimitador, desde) {
+  for (let indice = linea.indexOf(delimitador, desde); indice >= 0;
+    indice = linea.indexOf(delimitador, indice + 1)) {
+    let barras = 0;
+    for (let cursor = indice - 1; cursor >= 0 && linea[cursor] === '\\'; cursor--) barras++;
+    if (barras % 2 === 0) return indice;
+  }
+  return -1;
+}
+
+function buscarCierreStringSimplePython(linea, comilla, desde) {
+  for (let cursor = desde; cursor < linea.length; cursor++) {
+    if (linea[cursor] === '\\') cursor++;
+    else if (linea[cursor] === comilla) return cursor;
+  }
+  return -1;
+}
+
+function tieneContinuacionPython(linea) {
+  let barras = 0;
+  for (let cursor = linea.length - 1; cursor >= 0 && linea[cursor] === '\\'; cursor--) barras++;
+  return barras % 2 === 1;
+}
+
+function ocultarSegmentoStringPython(
+  linea, visible, delimitador, desde, inicio, esContinuacion = false
+) {
+  const cierre = delimitador.length === 3
+    ? buscarDelimitadorTriple(linea, delimitador, desde)
+    : buscarCierreStringSimplePython(linea, delimitador, desde);
+  const fin = cierre < 0 ? linea.length : cierre + delimitador.length;
+  const sigueAbierto = cierre < 0
+    && (delimitador.length === 3 || tieneContinuacionPython(linea));
+  if (delimitador.length === 3 || esContinuacion || sigueAbierto) {
+    visible.fill(' ', inicio, fin);
+  }
+  return { cursor: fin, sigueAbierto };
+}
+
+function ocultarLineaMultilineaPython(linea, estado) {
+  const visible = [...linea];
+  let cursor = 0;
+  while (cursor < linea.length) {
+    if (estado.delimitador) {
+      const segmento = ocultarSegmentoStringPython(
+        linea, visible, estado.delimitador, cursor, cursor, true
+      );
+      cursor = segmento.cursor;
+      if (segmento.sigueAbierto) return visible.join('');
+      estado.delimitador = null;
+      continue;
+    }
+    const caracter = linea[cursor];
+    if (caracter === '#') break;
+    if (caracter !== "'" && caracter !== '"') {
+      cursor++;
+      continue;
+    }
+    const triple = caracter.repeat(3);
+    const delimitador = linea.startsWith(triple, cursor) ? triple : caracter;
+    const segmento = ocultarSegmentoStringPython(
+      linea, visible, delimitador, cursor + delimitador.length, cursor
+    );
+    cursor = segmento.cursor;
+    if (segmento.sigueAbierto) {
+      estado.delimitador = delimitador;
+      return visible.join('');
+    }
+  }
+  return visible.join('');
+}
+
+function ocultarStringsMultilineaPython(lineas) {
+  const estado = { delimitador: null };
+  return lineas.map((linea) => ocultarLineaMultilineaPython(linea, estado));
+}
+
+function obtenerFuncionesEntrypointPython(lineas) {
+  const funciones = new Set();
+  const patronGuard = /^if\s+__name__\s*==\s*['"]__main__['"]\s*:/;
+  const patronDirecto = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/;
+  const patronWrapper = /^\s*(?:raise\s+)?(?:SystemExit|sys\.exit|asyncio\.run)\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/;
+
+  for (let i = 0; i < lineas.length; i++) {
+    if (!patronGuard.test(lineas[i])) continue;
+    let indentacionBloque = null;
+    for (let j = i + 1; j < lineas.length; j++) {
+      const linea = lineas[j];
+      if (!linea.trim() || /^\s*#/.test(linea)) continue;
+      const indentacion = linea.match(/^(\s*)/)?.[1].length ?? 0;
+      if (indentacion === 0) break;
+      if (indentacionBloque === null) indentacionBloque = indentacion;
+      if (indentacion !== indentacionBloque) continue;
+      const invocacion = patronWrapper.exec(linea) || patronDirecto.exec(linea);
+      if (invocacion) funciones.add(invocacion[1]);
+    }
+  }
+  return funciones;
+}
+
 function verificarPrintPython(rutaRelativa, contenido) {
   const esArchivoTest = /test.*\.py$/.test(rutaRelativa) ||
     /[/\\]tests?[/\\]/.test(rutaRelativa);
@@ -309,22 +413,56 @@ function verificarPrintPython(rutaRelativa, contenido) {
   if (esArchivoTest || esVendor) return { ok: true, mensajes: [] };
 
   const lineas   = contenido.split('\n');
+  const lineasAnalizables = ocultarStringsMultilineaPython(lineas);
   const mensajes = [];
   // Patrón de print() al inicio de la sentencia (no como argumento de otra función)
   const patronPrint     = /^\s*print\s*\(/;
   const esComentario    = /^\s*#/;
   // Detectar si estamos dentro de if __name__ == '__main__':
-  const patronMainBlock = /if\s+__name__\s*==\s*['"]__main__['"]\s*:/;
+  const patronMainBlock = /^if\s+__name__\s*==\s*['"]__main__['"]\s*:/;
+  const patronFuncionNivelSuperior = /^(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/;
+  const patronScopeAnidado = /^(\s+)(?:(?:async\s+)?def|class)\s+[A-Za-z_][A-Za-z0-9_]*\b/;
+  const funcionesEntrypoint = obtenerFuncionesEntrypointPython(lineasAnalizables);
 
   let dentroDeMainBlock = false;
   let indentacionMain   = -1;
+  let indentacionScopeMain = null;
+  let dentroDeFuncionEntrypoint = false;
+  let indentacionScopeAnidado = null;
 
-  for (let i = 0; i < lineas.length; i++) {
-    const linea = lineas[i];
+  for (let i = 0; i < lineasAnalizables.length; i++) {
+    const linea = lineasAnalizables[i];
+
+    const funcion = patronFuncionNivelSuperior.exec(linea);
+    if (funcion) {
+      dentroDeFuncionEntrypoint = funcionesEntrypoint.has(funcion[1]);
+      indentacionScopeAnidado = null;
+      continue;
+    }
+    if (dentroDeFuncionEntrypoint) {
+      const esIgnorable = linea.trim() === '' || /^\s*#/.test(linea);
+      if (esIgnorable) continue;
+      const indentacion = linea.match(/^(\s*)/)?.[1].length ?? 0;
+      if (indentacion === 0) {
+        dentroDeFuncionEntrypoint = false;
+        indentacionScopeAnidado = null;
+      } else {
+        if (indentacionScopeAnidado !== null && indentacion <= indentacionScopeAnidado) {
+          indentacionScopeAnidado = null;
+        }
+        const scopeAnidado = patronScopeAnidado.exec(linea);
+        if (scopeAnidado && indentacionScopeAnidado === null) {
+          indentacionScopeAnidado = scopeAnidado[1].length;
+          continue;
+        }
+        if (indentacionScopeAnidado === null && patronPrint.test(linea)) continue;
+      }
+    }
 
     // Detectar inicio del bloque __main__
     if (patronMainBlock.test(linea)) {
       dentroDeMainBlock = true;
+      indentacionScopeMain = null;
       // La indentación del bloque es la del if más 4 espacios (convención Python)
       indentacionMain = (linea.match(/^(\s*)/)?.[1].length ?? 0) + 1;
       continue;
@@ -333,13 +471,23 @@ function verificarPrintPython(rutaRelativa, contenido) {
     // Verificar si seguimos dentro del bloque __main__
     if (dentroDeMainBlock) {
       const indentacionLinea = linea.match(/^(\s*)/)?.[1].length ?? 0;
-      const esLineaVacia     = linea.trim() === '';
+      const esLineaVacia     = linea.trim() === '' || /^\s*#/.test(linea);
+      if (esLineaVacia) continue;
       // Salir del bloque si la indentación vuelve al nivel del if o menor
-      if (!esLineaVacia && indentacionLinea < indentacionMain) {
+      if (indentacionLinea < indentacionMain) {
         dentroDeMainBlock = false;
         indentacionMain   = -1;
+        indentacionScopeMain = null;
       } else {
-        continue; // Dentro del bloque main — permitir print()
+        if (indentacionScopeMain !== null && indentacionLinea <= indentacionScopeMain) {
+          indentacionScopeMain = null;
+        }
+        const scopeAnidado = patronScopeAnidado.exec(linea);
+        if (scopeAnidado && indentacionScopeMain === null) {
+          indentacionScopeMain = scopeAnidado[1].length;
+          continue;
+        }
+        if (indentacionScopeMain === null) continue;
       }
     }
 
@@ -1267,6 +1415,7 @@ module.exports = {
   esArchivoFuente,
   extraerMensajeCommit,
   esPrefijoExentoDeTests,
+  verificarPrintPython,
   verificarTestPresence,
   verificarTodosSinTicket,
   detectarRunnerCoverage,