@saulwade/swl-ses 2.3.1 → 2.4.1

package/habilidades/postgresql-experto/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: postgresql-experto
 description: PostgreSQL avanzado. JSONB, arrays, tipos personalizados, búsqueda de texto completo, window functions, CTEs recursivos, Row Level Security y funciones almacenadas.
-version: "1.2.0"
+version: "1.2.1"
 herramientasPermitidas: [Read, Grep]
 exclusiones:
   - "No cargar para optimización de queries SQL (EXPLAIN ANALYZE, índices, partitioning) — para optimización cargar `sql-optimizacion`."
@@ -142,6 +142,8 @@ ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
 
 ## Gotchas / Errores comunes no obvios
 
+**Bajo `lc_ctype=C` (default de `postgres:alpine`), `upper()`/`lower()` son operaciones puramente ASCII — no transforman caracteres acentuados**: `upper('auditoría')` devuelve `AUDITORíA` (la `í` queda intacta), así que una normalización de búsqueda que ejecute `upper()` ANTES de remover acentos con `translate()` produce strings que nunca matchean — la búsqueda falla silenciosamente devolviendo 0 resultados. Causa: en locale `C` las funciones de case solo mapean `[a-z]↔[A-Z]`. Fix: ejecutar `translate()` (remover acentos) SIEMPRE antes de `upper()`/`lower()`, nunca después; y aplicar el mismo orden en ambos lados de la comparación (columna y término de búsqueda). Origen: SIGAF 2026-07-02 — filtros de menú completamente rotos en `postgres:alpine`.
+
 **`SET LOCAL app.empresa_id` para RLS no persiste fuera de una transacción**: `SET LOCAL` establece la variable solo para la transacción actual — si se ejecuta fuera de `BEGIN/COMMIT`, tiene el mismo efecto que `SET` (sesión completa). En aplicaciones con pooling (PgBouncer en transaction mode), la sesión se reutiliza entre conexiones y la variable puede persistir de una petición anterior. Causa: el pool de conexiones reutiliza sessions sin limpiar el estado. Fix: usar SIEMPRE `SET LOCAL` dentro de una transacción explícita (`async with session.begin()`) y verificar que el pool esté en transaction mode.
 
 **RLS NO se aplica a superusuarios — verificar siempre con rol app-only**: `FORCE ROW LEVEL SECURITY` hace que las policies apliquen al OWNER de la tabla, pero los superusuarios SIEMPRE bypassean RLS. En imágenes oficiales (`postgis/postgis`, `postgres`), el rol que se crea por defecto (con `POSTGRES_USER`) es superusuario. Caso real: `SET app.tenant_id = COAT` mostraba 20 predios del tenant MINA porque la query corría como `sigm` superuser. Fix: para verificar aislamiento RLS o exponer al backend de producción, crear un rol app-only sin BYPASSRLS:

package/habilidades/prevencion-sobreingenieria/SKILL.md

@@ -2,12 +2,16 @@
 name: prevencion-sobreingenieria
 description: >
   Previene sobre-ingeniería y código innecesario en generación asistida por IA.
-  Cuatro principios: pensar antes de codificar, simplicidad primero, cambios
-  quirúrgicos y ejecución orientada a metas verificables. Cargar antes de
-  implementar features, refactorizar código o resolver bugs — especialmente
-  cuando el agente tiende a agregar abstracciones especulativas o tocar código
-  fuera del alcance solicitado.
-version: "1.2.0"
+  Escalera de decisión de 7 peldaños (YAGNI → reusar → stdlib → nativo →
+  dependencia instalada → una línea → mínimo que funciona) con guardas
+  intocables de seguridad, más cuatro principios: pensar antes de codificar,
+  simplicidad primero, cambios quirúrgicos y ejecución orientada a metas
+  verificables. Cargar antes de implementar features, refactorizar código o
+  resolver bugs — especialmente cuando el agente tiende a agregar abstracciones
+  especulativas, reinventar lo que la plataforma ya tiene, o tocar código fuera
+  del alcance solicitado. Incluye la convención de marcador `simplificado:`
+  (techo + trigger) cosechable por /swl:deuda-codigo.
+version: "1.3.0"
 herramientasPermitidas: [Read, Grep]
 toolsRequeridos: Read, Grep, Glob
 exclusiones:
@@ -19,12 +23,11 @@ evolvable: true  # default para skill estandar
 ---
 # Prevención de sobre-ingeniería
 
-Skill derivado de los principios de Andrej Karpathy sobre errores comunes de LLMs
-al generar código, adaptado al ecosistema SWL.
+Principios de Andrej Karpathy sobre errores comunes de LLMs al generar
+código + escalera de decisión de ponytail, adaptados al ecosistema SWL.
 
 > **Para 9 ejemplos MAL→BIEN lado a lado con código real**, ver
-> [recursos/EXAMPLES.md](recursos/EXAMPLES.md). Cada ejemplo está mapeado a un
-> escenario operativo concreto de SWL (qué agente debe citarlo, en qué flujo).
+> [recursos/EXAMPLES.md](recursos/EXAMPLES.md) — cada uno mapeado a su escenario SWL.
 
 ## Cuándo cargar
 
@@ -34,6 +37,59 @@ al generar código, adaptado al ecosistema SWL.
 - Cuando el usuario reporta que el agente "hace demasiado" o "cambia cosas que no debía"
 - En revisiones de código donde se detecta complejidad innecesaria
 
+## Escalera de decisión — antes de escribir código
+
+Detenerse en el **primer peldaño que aplique** (adaptada de
+[ponytail](https://github.com/DietrichGebert/ponytail), MIT — benchmark
+agéntico: −54% LOC, −20% costo, 100% seguridad vs el mismo agente sin disciplina):
+
+1. **¿Necesita existir?** Necesidad especulativa = omitir y decirlo en una línea (YAGNI).
+2. **¿Ya existe en este codebase?** Helper, util, tipo o patrón que ya vive aquí
+   → reusarlo. Reimplementar lo que está a unos archivos es el desperdicio más común.
+3. **¿La stdlib lo hace?** Usarla.
+4. **¿Una feature nativa de la plataforma lo cubre?** `<input type="date">`
+   sobre una lib de picker, CSS sobre JS, constraint de BD sobre código de app.
+   Tablas de referencia: [recursos/soluciones-nativas.md](recursos/soluciones-nativas.md).
+5. **¿Una dependencia ya instalada lo resuelve?** Usarla. NUNCA agregar una
+   nueva para lo que unas líneas cubren (refuerza `usar-context7.md`).
+6. **¿Cabe en una línea?** Una línea.
+7. **Solo entonces**: el mínimo código que funciona.
+
+La escalera corre DESPUÉS de entender el problema, no en su lugar: leer la
+tarea y el código que toca, trazar el flujo real, y entonces subir. Un diff
+pequeño que no se entiende no es eficiencia — es un segundo bug.
+
+### Guardas intocables (nunca simplificar)
+
+Validación de inputs en fronteras de confianza (trust boundaries) · manejo de
+errores que previene pérdida de datos · medidas de seguridad · básicos de
+accesibilidad · lo que el usuario pidió explícitamente (si insiste en la
+versión completa, construirla sin re-debatir).
+
+Entre dos opciones stdlib del mismo tamaño, elegir la correcta en edge cases:
+menos código no significa el algoritmo más frágil. La lógica no trivial deja
+UN check ejecutable mínimo (test pequeño o assert de auto-verificación); los
+one-liners triviales no lo requieren — YAGNI aplica también a los tests.
+
+### Bug fix = causa raíz, no síntoma
+
+El reporte nombra un síntoma. Antes de editar, grep de TODOS los callers de la
+función a tocar: un guard en la función compartida es un diff menor que un guard
+por caller — parchar solo la ruta del ticket deja rotos a los callers hermanos.
+
+### Marcador de simplificación deliberada
+
+Toda simplificación intencional con techo conocido se marca con un comentario
+`simplificado:` que nombra el techo y el trigger de upgrade:
+
+```python
+# simplificado: lock global, pasar a locks por cuenta si el throughput importa
+```
+
+`/swl:deuda-codigo` cosecha los marcadores hacia `.planning/DEUDA-TECNICA.md`.
+Un marcador **sin trigger** es deuda silenciosa (prohibida por
+`arreglar-al-detectar.md`) — siempre nombrar la condición observable de upgrade.
+
 ## Principio 1 — Pensar antes de codificar
 
 Antes de escribir una sola línea, explicitar supuestos y resolver ambigüedades.
@@ -236,87 +292,9 @@ de código requiere análisis profundo. La simplicidad también aplica al proces
 - **Principio 1 (clarificar antes de implementar) aplicado a tareas que ya tienen spec completa**: el agente pregunta por decisiones que ya están documentadas en el PLAN.md aprobado. Causa: no leer la spec antes de preguntar. Solución: el Principio 1 aplica cuando hay ambigüedad real después de leer el PLAN.md, CLAUDE.md y los archivos relevantes — si la respuesta está en los documentos ya leídos, preguntar es sobreingeniería del proceso, no clarificación.
 - **Criterio de 3 usos para abstracciones aplicado a tipos (interfaces/protocolos)**: el agente no crea una interfaz para un tipo que se usa en un solo lugar. Causa: confundir "3 usos para abstracciones de comportamiento" con "3 usos para tipos". Solución: el criterio de 3 usos aplica a factories, strategies, y patrones de comportamiento especulativos; una interfaz TypeScript o un Protocol Python que define un contrato usado una vez puede ser la solución correcta si el tipo es el boundary entre módulos.
 
----
-
 ## Variables residuales post-refactor son code smell
 
-### Regla
-
-Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
-casi siempre residuos de una versión anterior del código que el refactor no
-limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
-refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
-asignaciones quedaron.
-
-### Por qué son peligrosas
-
-- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
-- **Inflan el diff cognitivo** del refactor real.
-- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
-  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
-- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
-  realidad no afectan el resultado.
-
-### Patrón operativo
-
-Después de **cualquier refactor** que modifique el flujo de una función (extraer
-método, inlinear función, cambiar el shape de un return), correr:
-
-```bash
-ruff check --select=F841 ruta/al/modulo.py
-# o para todo el proyecto
-ruff check --select=F841 .
-```
-
-Cada F841 detectado post-refactor es candidato 1 de 2:
-
-1. **Variable muerta** (caso común post-refactor): eliminarla.
-2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
-   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
-   con prefijo `_` y comentar el propósito.
-
-### Anti-patrón típico
-
-```python
-# Antes del refactor: había un if que usaba exito_key
-def procesar(data):
-    exito, exito_key = intentar(data)
-    if exito_key == "via_rapida":
-        return procesar_rapido(data)
-    return procesar_normal(data, exito_key)
-
-
-# Después de refactor que eliminó la rama "via_rapida"
-def procesar(data):
-    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
-    return procesar_normal(data)         # ← también exito residual
-```
-
-### Patrón canónico
-
-```python
-# Post-refactor limpio
-def procesar(data):
-    _ = intentar(data)   # si el side effect de intentar() importa
-    return procesar_normal(data)
-
-# o mejor: si ni siquiera el side effect importa
-def procesar(data):
-    return procesar_normal(data)
-```
-
-### Reglas
-
-- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
-- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
-- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
-- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
-
-### Aplicabilidad
-
-Detectable en:
-
-- Python: `ruff --select=F841`, `flake8 --select=F841`.
-- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
-- Go: el compilador lo hace obligatorio (`declared but not used`).
-- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.
+Variables asignadas pero no usadas (F841) post-refactor delatan un refactor
+incompleto: confunden al lector, ocultan side effects muertos e invalidan la
+cobertura. Patrón operativo completo (gate pre-commit, anti-patrón, detección
+por lenguaje): [recursos/variables-residuales-post-refactor.md](recursos/variables-residuales-post-refactor.md).

package/habilidades/prevencion-sobreingenieria/recursos/soluciones-nativas.md

@@ -0,0 +1,166 @@
+# Soluciones nativas de plataforma
+
+Recurso de `prevencion-sobreingenieria` — peldaño 4 de la escalera de decisión.
+La primera pregunta del ingeniero perezoso-eficiente: *¿la plataforma ya hace
+esto?* Antes de instalar un paquete o escribir un componente, revisar aquí.
+La plataforma viaja gratis con la app, no se rompe en updates, y la escribió
+gente cuyo trabajo es exactamente ese problema.
+
+Adaptado de [ponytail](https://github.com/DietrichGebert/ponytail)
+`docs/platform-native.md` (MIT, DietrichGebert).
+
+---
+
+## Elementos HTML
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| Lib de date picker | `<input type="date">` |
+| Lib de time picker | `<input type="time">` |
+| Lib de color picker | `<input type="color">` |
+| Lib de range slider | `<input type="range">` |
+| Componente de progress bar | `<progress value="70" max="100">` |
+| Componente meter/gauge | `<meter value="0.7">` |
+| Lib de modal/diálogo | `<dialog>` + `dialog.showModal()` |
+| Componente acordeón/FAQ | `<details><summary>Título</summary>…</details>` |
+| Lib de tooltips | atributo `title` + CSS `::before`/`::after` |
+| Dropdown con búsqueda | `<input list="id"> <datalist id="id">` |
+| Textarea auto-crecible | `field-sizing: content` (CSS) |
+| Header sticky | `position: sticky; top: 0` (CSS) |
+
+## Capacidades CSS (donde se suele usar JS)
+
+| Crees que necesitas JS para | CSS ya tiene |
+|---|---|
+| Font size responsivo | `font-size: clamp(1rem, 2.5vw, 2rem)` |
+| Espaciado fluido | `padding: clamp(1rem, 5vw, 3rem)` |
+| Dark mode | `@media (prefers-color-scheme: dark)` |
+| Reduced motion | `@media (prefers-reduced-motion: reduce)` |
+| Layout responsivo sin breakpoints | `grid-template-columns: repeat(auto-fill, minmax(250px, 1fr))` |
+| Responsive a nivel componente | `@container` queries |
+| Design tokens / theming global | Custom properties (`--color-primario: #7c3aed`) |
+| Smooth scroll | `scroll-behavior: smooth` |
+| Carrusel con scroll-snap | `scroll-snap-type: x mandatory` + `scroll-snap-align: start` |
+| Aspect ratio | `aspect-ratio: 16 / 9` |
+| Truncar texto con elipsis | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` |
+| Clamp multilínea | `-webkit-line-clamp: 3` |
+| Aislamiento de estilos por capas | `@layer base, components, utilities` |
+| Selectores anidados | CSS nesting nativo (sin preprocesador) |
+| Selector de padre | `:has(input:checked)` |
+
+## JavaScript / APIs del navegador
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| `query-string` / `qs` | `new URLSearchParams(location.search)` |
+| `lodash.clonedeep` | `structuredClone(obj)` |
+| `lodash.groupby` | `Object.groupBy(arr, fn)` |
+| `numeral` / `accounting` | `new Intl.NumberFormat("es-MX", { style: "currency", currency: "MXN" })` |
+| `date-fns` format | `new Intl.DateTimeFormat("es-MX", { dateStyle: "long" }).format(fecha)` |
+| Tiempo relativo | `new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-3, "day")` |
+| Plurales i18n | `new Intl.PluralRules("es-MX").select(cantidad)` |
+| `clipboard.js` | `navigator.clipboard.writeText(texto)` |
+| `uuid` (v4) | `crypto.randomUUID()` |
+| Lib de infinite scroll | `new IntersectionObserver(cb).observe(sentinela)` |
+| Lib de resize listener | `new ResizeObserver(cb).observe(elemento)` |
+| Watcher de mutaciones DOM | `new MutationObserver(cb).observe(el, opciones)` |
+| Check de conectividad | `navigator.onLine` + eventos `online`/`offline` |
+| Lib de share sheet | `navigator.share({ title, text, url })` |
+| `store.js` / `localForage` (caso simple) | `localStorage.setItem(clave, JSON.stringify(valor))` |
+| Abortar fetch por timeout | `AbortSignal.timeout(5000)` pasado a `fetch` |
+| Event bus custom | `new EventTarget()` / `dispatchEvent(new CustomEvent("x", { detail }))` |
+
+**Debounce en 3 líneas** (sin dependencia):
+
+```js
+// simplificado: debounce de una sola instancia; lib si se necesitan N independientes
+let t;
+const debounce = (fn, ms) => (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
+```
+
+## Swift / SwiftUI
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| Lib de date/time picker | `DatePicker` |
+| Lib de color picker | `ColorPicker` |
+| Search bar + filtrado | `.searchable(text:)` |
+| Lib de pull-to-refresh | `.refreshable { }` |
+| Swipe-to-delete / acciones de fila | `.swipeActions { }` |
+| Carga async de imágenes + caché | `AsyncImage` |
+| Lib de gráficas | Swift Charts (`import Charts`) |
+| Render de Markdown | `Text(...)` markdown / `AttributedString(markdown:)` |
+| Share sheet | `ShareLink` |
+| Spinner de carga | `ProgressView()` |
+| Photo picker | `PhotosPicker` |
+| JSON (SwiftyJSON) | `Codable` + `JSONDecoder`/`JSONEncoder` |
+| HTTP simple (Alamofire) | `URLSession` async/await |
+| Crypto (CryptoSwift) | `CryptoKit` |
+| Persistencia / ORM | `SwiftData`, o `@AppStorage` para key-values |
+| Logging | `Logger` (`os.log`) |
+
+## Stdlib de Node.js
+
+| Crees que necesitas | Node ya tiene |
+|---|---|
+| `mkdirp` / `make-dir` | `fs.mkdirSync(ruta, { recursive: true })` |
+| `rimraf` | `fs.rmSync(ruta, { recursive: true, force: true })` |
+| `uuid` (v4) | `crypto.randomUUID()` |
+| `object-assign` | `Object.assign()` / spread |
+| `array-uniq` | `[...new Set(arr)]` |
+| `array-flatten` / `flat` | `arr.flat(profundidad)` |
+| `path-exists` | `fs.existsSync(ruta)` |
+| `load-json-file` | `JSON.parse(fs.readFileSync(ruta, "utf8"))` |
+| `write-json-file` | `fs.writeFileSync(ruta, JSON.stringify(obj, null, 2))` |
+| `pkg-dir` | `path.resolve(__dirname, "..")` / `import.meta.dirname` |
+
+## Stdlib de Python
+
+| Crees que necesitas | Python ya tiene |
+|---|---|
+| `python-dateutil` (parsing básico) | `datetime.fromisoformat()` (3.7+) |
+| `pytz` | `zoneinfo.ZoneInfo("America/Mexico_City")` (3.9+) |
+| `attrs` (data classes simples) | `@dataclass` |
+| `pathlib2` | `pathlib.Path` (3.4+) |
+| `simplejson` (uso básico) | `json` (stdlib) |
+| `requests` (GET simple) | `urllib.request.urlopen(url)`; `requests` para algo real |
+| `click` (comando único) | `argparse` (stdlib) |
+| `mergedeep` | `dict \| otro_dict` (3.9+) |
+| `more-itertools` (básico) | `itertools`: `chain`, `islice`, `groupby`, `product` |
+| `toolz` (básico) | `functools`: `lru_cache`, `partial`, `reduce` |
+
+## Base de datos
+
+| Crees que necesitas código de app para | La BD ya tiene |
+|---|---|
+| Paginación | `LIMIT 20 OFFSET 40` |
+| Totales acumulados | `SUM(...) OVER (ORDER BY fecha)` (window function) |
+| Rank por grupo | `RANK() OVER (PARTITION BY categoria ORDER BY score DESC)` |
+| Deduplicación | `SELECT DISTINCT` / `ON CONFLICT DO NOTHING` |
+| Recorrido de árboles | CTE recursivo (`WITH RECURSIVE`) |
+| Full-text search (básico) | `tsvector` / `MATCH AGAINST` / `FTS5` |
+| Almacenar + consultar JSON | `jsonb` (Postgres) / `JSON_EXTRACT` (SQLite/MySQL) |
+| Generación de UUID | `gen_random_uuid()` (Postgres) / `UUID()` (MySQL) |
+| Timestamps de insert/update | `DEFAULT now()` + trigger / `ON UPDATE CURRENT_TIMESTAMP` |
+| Unicidad | constraint `UNIQUE`, no checks en la app |
+| Integridad referencial | `FOREIGN KEY`, no checks en la app |
+| Rangos de valores | `CHECK (precio > 0)`, no validación en la app |
+
+---
+
+## El patrón
+
+En todas las capas es el mismo ciclo:
+
+```
+El equipo de la plataforma pasa años resolviendo el problema.
+Alguien lo envuelve en un paquete.
+Instalas el wrapper.
+El wrapper queda sin mantenimiento.
+Terminas debugueando el wrapper.
+```
+
+Sáltate el wrapper. Cuando la solución nativa es genuinamente insuficiente
+(soporte de navegadores viejos, edge cases que no cubre, ergonomía que importa
+a escala), la librería se gana su lugar — instálala entonces, no antes
+(y verifica su vigencia con Context7, regla `usar-context7.md`).

package/habilidades/prevencion-sobreingenieria/recursos/variables-residuales-post-refactor.md

@@ -0,0 +1,85 @@
+# Variables residuales post-refactor son code smell
+
+Recurso de `prevencion-sobreingenieria`. Extraído del SKILL.md en v1.3.0 para
+respetar el límite de 300 líneas; el contenido es normativo sin cambios.
+
+## Regla
+
+Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
+casi siempre residuos de una versión anterior del código que el refactor no
+limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
+refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
+asignaciones quedaron.
+
+## Por qué son peligrosas
+
+- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
+- **Inflan el diff cognitivo** del refactor real.
+- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
+  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
+- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
+  realidad no afectan el resultado.
+
+## Patrón operativo
+
+Después de **cualquier refactor** que modifique el flujo de una función (extraer
+método, inlinear función, cambiar el shape de un return), correr:
+
+```bash
+ruff check --select=F841 ruta/al/modulo.py
+# o para todo el proyecto
+ruff check --select=F841 .
+```
+
+Cada F841 detectado post-refactor es candidato 1 de 2:
+
+1. **Variable muerta** (caso común post-refactor): eliminarla.
+2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
+   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
+   con prefijo `_` y comentar el propósito.
+
+## Anti-patrón típico
+
+```python
+# Antes del refactor: había un if que usaba exito_key
+def procesar(data):
+    exito, exito_key = intentar(data)
+    if exito_key == "via_rapida":
+        return procesar_rapido(data)
+    return procesar_normal(data, exito_key)
+
+
+# Después de refactor que eliminó la rama "via_rapida"
+def procesar(data):
+    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
+    return procesar_normal(data)         # ← también exito residual
+```
+
+## Patrón canónico
+
+```python
+# Post-refactor limpio
+def procesar(data):
+    _ = intentar(data)   # si el side effect de intentar() importa
+    return procesar_normal(data)
+
+# o mejor: si ni siquiera el side effect importa
+def procesar(data):
+    return procesar_normal(data)
+```
+
+## Reglas
+
+- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
+- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
+- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
+- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
+
+## Aplicabilidad
+
+Detectable en:
+
+- Python: `ruff --select=F841`, `flake8 --select=F841`.
+- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
+- Go: el compilador lo hace obligatorio (`declared but not used`).
+- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.

package/hooks/audit-trail.js

@@ -33,10 +33,10 @@ const MERKLE_FILE = path.join(CWD, '.planning', 'audit-merkle.jsonl');
 // Herramientas excluidas del audit (muy ruidosas, bajo valor de auditoría)
 // ---------------------------------------------------------------------------
 
-const HERRAMIENTAS_EXCLUIDAS = new Set([
-  'linea-estado',       // Hook de estado — solo UI
-  'monitor-contexto',   // Interno del sistema
-]);
+// Vacío desde 2026-07-03: los dos hooks excluidos (linea-estado,
+// monitor-contexto) se eliminaron del sistema. El set se conserva como
+// punto de extensión para futuras exclusiones.
+const HERRAMIENTAS_EXCLUIDAS = new Set([]);
 
 // ---------------------------------------------------------------------------
 // Helpers

package/hooks/calidad-pre-commit.js

@@ -375,6 +375,11 @@ function verificarTodosSinTicket(rutaRelativa, contenido) {
   // Construir palabra clave dinámicamente para evitar auto-detección
   const keyword = 'TO' + 'DO';
   const patronSinTicket = new RegExp(`\\b${keyword}\\b(?!\\s*[:(]\\s*(?:#\\d+|[A-Z]+-\\d+|https?:\\/\\/))`);
+  // En Markdown, "TODO" solo cuenta como marcador con sintaxis explícita
+  // (TODO: / TODO() — la palabra española "TODO" en prosa ("en TODO destino",
+  // "tumbaba TODO el release") nunca la lleva. La blacklist de verbos previa
+  // era frágil: cada frase nueva la esquivaba (falsos positivos 2026-07-03).
+  const patronSinTicketMd = new RegExp(`\\b${keyword}\\s*[:(](?!\\s*(?:#\\d+|[A-Z]+-\\d+|https?:\\/\\/))`);
   const patronConTicket = new RegExp(`\\b${keyword}\\s*[:(]\\s*(?:#\\d+|[A-Z]+-\\d+|https?:\\/\\/)`);
   const patronNosec = /\/\/\s*nosec/;
 
@@ -391,15 +396,12 @@ function verificarTodosSinTicket(rutaRelativa, contenido) {
     if (dentroDeCodigoMd) continue;
     // Excluir líneas marcadas con // nosec o <!-- nosec -->
     if (patronNosec.test(linea) || /<!--\s*nosec\s*-->/.test(linea)) continue;
-    // En Markdown, excluir "TODO" dentro de backticks (código inline) o como palabra española
+    // En Markdown, excluir "TODO" dentro de backticks (código inline)
     if (esMd && /`[^`]*TODO[^`]*`/.test(linea)) continue;
-    if (esMd && /\b(capturar|cargar|cubrir|cumplir|verificar|pasar|incluir|tener)\s+TODO\b/i.test(linea)) continue;
-    // En Markdown, excluir líneas descriptivas que mencionan TODO como concepto (ej: "detecta TODO sin ticket")
-    if (esMd && /TODO\s+sin\s+ticket/i.test(linea)) continue;
     // Si tiene referencia a ticket, es válido
     if (patronConTicket.test(linea)) continue;
-    // Si no tiene referencia, es una violación
-    if (patronSinTicket.test(linea)) {
+    // Si no tiene referencia, es una violación (en .md solo el marcador explícito)
+    if ((esMd ? patronSinTicketMd : patronSinTicket).test(linea)) {
       const tag = '[TO' + 'DO]';
       mensajes.push(
         `  ${tag} ${rutaRelativa}:${i + 1} — sin referencia a ticket/issue`
@@ -1009,10 +1011,11 @@ function ejecutarCoverage(fuentes, runner) {
 
 let inputRaw = '';
 
-// Solo enganchar stdin cuando el hook se ejecuta directamente (no al hacer
-// `require()` desde un test). Permite testear las funciones puras sin disparar
-// el flujo de stdin.
-if (require.main === module) {
+// Solo enganchar stdin cuando el hook corre como entrypoint: ejecución directa
+// O vía el wrapper de settings.json `node -e "require('./hooks/...')"`, donde
+// require.main es undefined. Al hacer `require()` desde un test, require.main
+// es el runner (definido y ≠ este módulo) → no engancha stdin.
+if (!require.main || require.main === module) {
 
 process.stdin.on('data', chunk => {
   inputRaw += chunk;
@@ -1182,7 +1185,7 @@ process.stdin.on('end', () => {
   }
 });
 
-} // fin if (require.main === module)
+} // fin gate de entrypoint (directo o wrapper node -e)
 
 // ─── Coverage diferencial opt-in (gate G2-cov, Fase 11) ──────────────────────
 //
@@ -1265,6 +1268,7 @@ module.exports = {
   extraerMensajeCommit,
   esPrefijoExentoDeTests,
   verificarTestPresence,
+  verificarTodosSinTicket,
   detectarRunnerCoverage,
   coverageDiferencial,
 };

package/hooks/captura-acciones-post.js

@@ -134,8 +134,9 @@ function procesarTurno(data, baseDir) {
   }
 }
 
-// Listeners de stdin SOLO en modo CLI (evita colgar la suite de tests).
-if (require.main === module) {
+// Listeners de stdin SOLO en modo entrypoint: ejecución directa o wrapper
+// `node -e "require(...)"` (require.main undefined). Evita colgar los tests.
+if (!require.main || require.main === module) {
   let inputRaw = '';
   process.stdin.on('data', (c) => { inputRaw += c; });
   process.stdin.on('end', () => {

package/hooks/captura-acciones-session.js

@@ -138,8 +138,9 @@ function inspeccionar(baseDir) {
   return { encolados: n };
 }
 
-// Listeners de stdin SOLO en modo CLI.
-if (require.main === module) {
+// Listeners de stdin SOLO en modo entrypoint: ejecución directa o wrapper
+// `node -e "require(...)"` (require.main undefined). Evita colgar los tests.
+if (!require.main || require.main === module) {
   let inputRaw = '';
   process.stdin.on('data', (c) => { inputRaw += c; });
   process.stdin.on('end', () => {

package/hooks/contexto-iteracion.js

@@ -139,6 +139,7 @@ function main() {
   });
 }
 
-if (require.main === module) main();
+// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
+if (!require.main || require.main === module) main();
 
 module.exports = { debeInyectar, registrarInyeccion, construirBloque, THROTTLE_MS, ARCHIVO_ESTADO };

package/hooks/contexto-subagente.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: contexto-subagente.js
+ * Tipo: SubagentStart (aplica a todos los subagentes Task/Agent)
+ *
+ * El contexto emitido por hooks de SessionStart es solo del hilo padre y
+ * NUNCA llega a los subagentes: cada agente spawneado vía Task/Agent corre
+ * sin las disciplinas activas de la sesión (patrón documentado en ponytail
+ * issue #252 — mismo gap verificado en swl-ses el 2026-07-03: 0 usos de
+ * SubagentStart hasta este hook).
+ *
+ * Re-inyecta a cada subagente un bloque compacto (~120 tokens) con las
+ * disciplinas transversales no negociables: idioma es-MX, escalera de código
+ * mínimo con guardas intocables, y la convención de marcador `simplificado:`.
+ * Deliberadamente mínimo — el costo se paga en CADA spawn de subagente.
+ *
+ * Opt-out: SWL_CONTEXTO_SUBAGENTE=0 desactiva la inyección.
+ * Formato de salida: SubagentStart requiere la forma JSON hookSpecificOutput
+ * (stdout crudo se descarta en este evento — a diferencia de SessionStart).
+ */
+
+/**
+ * Construye el bloque de disciplinas que se inyecta al subagente.
+ *
+ * @returns {string} Contexto compacto en es-MX.
+ */
+function construirContexto() {
+  return [
+    'DISCIPLINAS SWL ACTIVAS (heredadas de la sesión padre):',
+    '- Idioma: español de México en todo output (código, comentarios, commits, reportes).',
+    '- Código mínimo — escalera antes de escribir: ¿necesita existir (YAGNI)? →',
+    '  ¿ya existe en este codebase? → ¿stdlib? → ¿feature nativa de la plataforma? →',
+    '  ¿dependencia ya instalada? → ¿una línea? → solo entonces, el mínimo que funciona.',
+    '- Guardas intocables (nunca simplificar): validación en trust boundaries,',
+    '  manejo de errores que previene pérdida de datos, seguridad, accesibilidad.',
+    '- Simplificación deliberada se marca: `simplificado: <techo>, <trigger de upgrade>`.',
+    '- Bug fix = causa raíz: grep de todos los callers antes de parchar uno.',
+    'Detalle completo: Skill("prevencion-sobreingenieria").',
+  ].join('\n');
+}
+
+/**
+ * Emite el contexto en el formato JSON que SubagentStart exige.
+ * Nunca falla hacia afuera: un stdout roto no debe reportarse como hook error.
+ */
+function main() {
+  if (process.env.SWL_CONTEXTO_SUBAGENTE === '0') return;
+  try {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SubagentStart',
+        additionalContext: construirContexto(),
+      },
+    }));
+  } catch (_) {
+    // Silencioso — no interrumpir el spawn del subagente.
+  }
+}
+
+// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
+// No consume stdin: emite y termina — sin listeners, el proceso sale solo.
+if (!require.main || require.main === module) {
+  main();
+}
+
+module.exports = { construirContexto };