@saulwade/swl-ses 2.5.3 → 2.6.1

package/habilidades/git-worktrees-paralelo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: git-worktrees-paralelo
 description: Uso de git worktrees para ejecución paralela de agentes. Crear, usar y limpiar worktrees de forma segura para que múltiples agentes trabajen sin conflictos.
-version: "1.0.0"
+version: "1.0.1"
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -268,3 +268,21 @@ git worktree remove --force ../mi-app-agente-1
 **`git stash` en un worktree guarda el stash en el stash global del repositorio compartido, no en el worktree**: si el Agente 1 hace `git stash` en `mi-app-agente-1/` y luego el Agente 2 hace `git stash pop` en `mi-app-agente-2/`, aplica el stash del Agente 1 en la rama incorrecta. Causa: el stash de Git es una referencia global en `.git/refs/stash`, no por worktree. Fix: NUNCA usar `git stash` en flujos con múltiples worktrees. En su lugar, hacer un commit temporal con mensaje `WIP:` y usar `git reset HEAD~1` para deshacer cuando se necesite.
 
 **Eliminar un worktree con `git worktree remove --force` mientras hay un agente activo escribiendo archivos en ese directorio produce corrupción del objeto store de Git**: si el agente tiene archivos en proceso de escritura (commit parcial, `git add` pendiente) y otro proceso ejecuta `remove --force`, Git puede quedar con objetos huérfanos o referencias rotas. Causa: `--force` no verifica si hay procesos con file handles abiertos en el worktree. Fix: el orquestador debe verificar que cada agente emitió su commit final antes de ejecutar `git worktree remove`. Usar `git worktree list --porcelain` para confirmar que la rama del worktree tiene el commit esperado.
+
+**Un worktree creado con `isolation: "worktree"` (Agent tool) puede branchear desde una base desactualizada — no la rama de trabajo activa — si pasó tiempo o hubo compactación de contexto entre sesiones** [CONFIRMADO]: si el mecanismo que crea el worktree resuelve el punto de partida contra una referencia que quedó "congelada" (ej. `main` publicado, 100+ commits detrás de la rama de feature real en la que se trabaja), el agente produce commits legítimos, pero al intentar fusionarlos aparecen decenas de conflictos espurios en archivos que el agente ni siquiera tocó — el diff real es contra una base vieja, no contra el trabajo del agente. Caso real (sesión de 4 agentes en paralelo): 2 de 4 worktrees branchearon desde `main` (un PR ya squash-mergeado, 182 commits detrás de la rama de trabajo activa) en vez de la rama de feature; el merge directo habría arrastrado cientos de líneas de diffs no relacionados, y de hecho generó colisión real de números consecutivos de migración. Causa raíz: el punto de partida del worktree se fijó en un momento donde apuntaba a la rama correcta, pero la rama activa siguió avanzando mientras el worktree quedó anclado a su snapshot original — cuanto más dura la sesión (o si hay compactación de por medio), mayor la ventana de divergencia. Diagnóstico ANTES de fusionar (barato, dos comandos):
+```bash
+git merge-base --is-ancestor <rama-actual> <rama-worktree> && echo "base correcta" || echo "requiere investigar"
+git merge-base <rama-actual> <rama-worktree>   # compara contra el HEAD conocido de cuando se lanzó el agente
+```
+Si la base real está muy por detrás de lo esperado: **no usar `git merge` directo** (arrastraría el diff completo vs. la base vieja) — usar `git cherry-pick` de los commits propios del agente, uno por uno, sobre la punta actual de la rama de trabajo (`git log --reverse --oneline <base-vieja>..<rama-worktree>` para la lista en orden). Los conflictos del cherry-pick son reales y acotados al cambio de ESE commit, no ruido de la divergencia de base.
+
+**Un conflicto de merge/cherry-pick en un archivo SQL con múltiples `CREATE PROCEDURE`/`CREATE FUNCTION` consecutivos y boilerplate similar (`LANGUAGE plpgsql SECURITY INVOKER AS $$ DECLARE ... END; $$;`) puede hacer que el diff de línea de Git "interleave" el contenido de dos objetos distintos** [CONFIRMADO x2]: cuando ambos lados de un conflicto agregan objetos PL/pgSQL nuevos en la misma posición del archivo, git empareja las líneas de cierre genéricas (`)`, `LANGUAGE plpgsql`, `SECURITY INVOKER`, `AS $$`, `DECLARE`) como si fueran contexto compartido sin cambios — el bloque `<<<<<<< / ======= / >>>>>>>` alterna entre la firma de un objeto de un lado y el cuerpo de OTRO objeto del otro lado. Resolver aceptando los hunks tal cual (o con merge automático) borra o duplica el cuerpo de uno de los dos procedimientos/funciones. Diagnóstico antes de resolver: contar cuántos `CREATE OR REPLACE (PROCEDURE|FUNCTION)` hay en cada lado del rango conflictuado (`grep -n "CREATE OR REPLACE"` entre las líneas del `<<<<<<<` y `>>>>>>>`) — si el conteo no cuadra con objetos completos y autocontenidos, hay interleaving. Fix: NO editar los hunks en el sitio; reconstruir manualmente objeto-por-objeto, concatenando cada `CREATE ... COMMENT ON ...` completo de un lado seguido del completo del otro lado, en cualquier orden (son independientes). Verificar al final: `grep -c '\$\$' archivo.sql` debe dar un número PAR, y el conteo de `CREATE OR REPLACE PROCEDURE/FUNCTION` debe coincidir con la suma real esperada de ambos lados sin duplicados.
+
+**Una rama que sigue recibiendo commits DESPUÉS de que su propio PR se squash-mergeó a `main` genera un conflicto espurio de 20+ archivos en el SIGUIENTE PR de esa misma rama** [CONFIRMADO — variante del gotcha anterior]: el caso de "worktree con base desactualizada" cubre una rama que *branchea desde* una base squasheada; este es el caso hermano donde la MISMA rama continúa avanzando tras su propio squash-merge. El historial de commits de la rama nunca queda como descendiente del commit squash en `main` — git no tiene ancestro común que refleje el squash, así que el siguiente PR desde esa rama muestra `mergeStateStatus: CONFLICTING` aunque semánticamente nada choque. Diagnóstico y resolución seguros — **barrido "ours vs theirs" por shortstat ANTES de elegir estrategia**, nunca a ciegas:
+```bash
+git log --oneline -3 main   # confirmar que main NO avanzó desde el squash
+git diff --name-only <rama-local> main   # lista de archivos en conflicto
+# Para CADA archivo conflictuado, comparar tamaño de cambio de cada lado:
+git diff --shortstat :2:<archivo> :3:<archivo>   # :2 = ours/HEAD, :3 = theirs/main
+```
+Si TODOS los archivos muestran que "theirs" (main, congelado en el punto del squash) es subconjunto estricto de líneas de "ours" (la rama que sigue avanzando), y `main` no avanzó desde el squash (paso 1), `git checkout --ours <archivo>` para cada uno es seguro — no se pierde contenido independiente de main. Si algún archivo muestra líneas exclusivas del lado "theirs" que "ours" no tiene, DETENERSE y resolver ese archivo manualmente (no aplica el atajo). Referencia cruzada: `~/.claude/rules/sesiones-paralelas.md`.

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

@@ -10,7 +10,7 @@ description: >
   Cargar cuando el usuario reporte "se acabó la cuota", se prepare una
   sesión Opus larga (>2h), se planifique adopción de MCP servers, o se
   detecte context-rot recurrente.
-version: "1.0.5"
+version: "1.0.6"
 evolved: false
 herramientasPermitidas: [Read]
 exclusiones:
@@ -264,8 +264,12 @@ Sin observar la métrica, no puedes optimizarla.
 
 ---
 
-## Gotchas / Errores comunes no obvios
-
+## Gotchas / Errores comunes no obvios
+
+- **La frontera de escritura/seguridad de un hook es la raíz del repo git, no el CWD de la sesión** [doble caso real 2026-07-10]: (1) `proteccion-rutas` bloqueó la escritura de `.planning/audit/` en SIGM porque la sesión corría en `sigm/backend/` — el destino estaba dentro del proyecto pero un nivel arriba del CWD; (2) en sistema-verificacion-oic, los hooks de telemetría anclados a `process.cwd()` crearon TRES árboles `.planning/` (raíz + backend + frontend) fragmentando la memoria del proyecto. Causa común: tratar el CWD de arranque como frontera del proyecto — en monorepos la sesión se abre en subdirectorios rutinariamente. Fix de clase: ascender hasta `.git` (directorio o archivo — worktrees) y usar esa raíz como frontera de permisos y como ancla de escritura; si la detección falla → conservador (bloquear / caer al CWD). Aplicado a `proteccion-rutas` con boundary checks (repos ajenos y siblings `repo-evil` siguen bloqueados); el resto de hooks en DT-HOOKS-RAIZ-GIT.
+
+- **`node --test <directorio>` en Windows intenta ejecutar el directorio como test y falla en milisegundos sin correr nada** [caso real 2026-07-10: `node --test tests/ciclo-autonomo/` reportó 1 fail en 42ms cuando el glob equivalente corría 21 tests]: la duración es la delatora — <100ms para una suite que debería tardar segundos significa que el runner no encontró tests, no que fallaron. Fix: glob explícito entre comillas — `node --test "tests/ciclo-autonomo/*.test.js"`.
+
 - **El exit code de un pipeline es el del ÚLTIMO comando — verificar suites con `cmd | grep` enmascara fallos** [caso real 2026-07-09: `npm run test:all | grep ℹ | head` reportó "verde" durante horas sobre una suite que fallaba; el único runner sin máscara fue el `prepublishOnly` del usuario, que tumbó el publish]: en bash, `a | b` sale con el código de `b` (grep=0 si matcheó algo). Patrón correcto para verificar comandos largos: `cmd > /tmp/x.log 2>&1; echo "exit=$?"` y decidir por el exit explícito; el grep va DESPUÉS, sobre el log. Alternativa: `set -o pipefail` al inicio del script. Aplica a todo: suites, builds, linters, gates.
 
 - **Matriz de canales de hooks — stderr con exit 0 es un canal INVISIBLE** [origen: check-update 2026-07-08, el aviso de nuevas versiones se emitió al vacío desde su creación]: en Claude Code, el canal correcto depende del exit code. **exit 0 (éxito)**: solo el stdout llega — como contexto del turno en UserPromptSubmit/SessionStart (o `hookSpecificOutput.additionalContext`); el stderr no lo lee nadie. **exit 2 (bloqueo)**: solo el stderr llega al modelo con la razón del bloqueo; stdout con exit 2 = bloqueo ciego (regla ya conocida, L1 #4 de APRENDIZAJES). Anti-patrón resultante: "hook que funciona perfecto y nadie ve" — todo aviso al usuario desde un hook exitoso DEBE ir a stdout, idealmente con instrucción explícita ("INFORMA AL USUARIO...") para que el modelo lo retransmita. Verificación: correr el hook a mano con un flag de forzado y confirmar en qué canal aparece el mensaje.

package/habilidades/infra-github-actions/SKILL.md

@@ -82,14 +82,15 @@ gh secret set CLAUDE_API_KEY
 
 ## Branch protection
 
-Aplicar después de tener CI funcionando. El script del repo swl-ses:
+Aplicar después de tener CI funcionando. El subcomando del CLI (resuelve
+cross-scope: repo madre → bin en PATH → `npx -y @saulwade/swl-ses@latest`):
 
 ```bash
 # Ver qué haría sin aplicar cambios
-node scripts/configurar-branch-protection.js --dry-run
+swl-ses configure-branch-protection --dry-run
 
 # Aplicar
-node scripts/configurar-branch-protection.js
+swl-ses configure-branch-protection
 ```
 
 Requiere `gh` CLI autenticado y permisos de admin en el repositorio.

package/habilidades/instalar-sistema/SKILL.md

@@ -2,7 +2,7 @@
 name: instalar-sistema
 description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
 user-invocable: false
-version: "1.0.2"
+version: "1.0.3"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
@@ -176,6 +176,10 @@ cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
 
 ## Gotchas / Errores comunes no obvios
 
+- **Todo mecanismo que ENCIENDE escritores debe sembrar el ignore de sus outputs en el mismo acto** [caso real 2026-07-10: `install --solo-hooks` activaba la telemetría (los hooks escriben METRICAS.md, audit*.jsonl, evolution/nudges.jsonl, runs/…) sin aplicar `gitignore-manifest` — 19 archivos runtime aparecieron como cambios pendientes en el editor del usuario en sistema-verificacion-oic]: activar hooks/telemetría/watchers es un contrato de DOS partes — registrar el escritor Y declarar sus outputs como runtime ignorado. Fix: `activar-hooks-proyecto` aplica `actualizarGitignore()` tras registrar (no bloqueante, reporta la ruta). Patrón general: al agregar cualquier writer nuevo al sistema, preguntarse en el mismo commit "¿quién ignora lo que este escribe en el destino?".
+
+- **Todo rename de path runtime necesita shim de migración en el manifest de ignorados** [caso real 2026-07-10: instalaciones pre-ADR-0031 escriben `.planning/evolucion/` (español) — el manifest solo ignoraba `evolution/` (inglés), así que los proyectos con hooks viejos ensuciaban su working tree hasta correr `update`]: al renombrar un directorio runtime, el path viejo sigue VIVO en el campo mientras existan instalaciones sin actualizar; el manifest debe cubrir ambas variantes (con comentario de vigencia) hasta que la base instalada migre. Señal en reportes de campo: un path "que ya no existe en el fuente" apareciendo en capturas del usuario delata instalación vieja — pedir `update`, no buscar el writer en el código actual.
+
 - **Un generador de archivos de instrucciones NUNCA sobrescribe un archivo sin su marcador de procedencia** [caso real 2026-07-08: `install --target opencode` pisó el AGENTS.md canónico del repo madre — 420 líneas de documentación curada reemplazadas por el stub del transformador]: la rama "clásica" de `generarArchivoInstrucciones` escribía a ciegas. Regla: antes de sobrescribir AGENTS.md/GEMINI.md/etc. en el destino, verificar que el archivo existente contenga el marcador `Generado por swl-ses`; sin marcador = contenido del usuario o doc canónica del proyecto → preservar y avisar ("borra el archivo y reinstala si quieres el generado"). El guard vive en `scripts/instalador.js` (rama clásica). Patrón general: todo writer de archivos compartidos necesita prueba de ownership antes de escribir — el mismo principio del merge-no-overwrite (ADR-0040) aplicado a archivos generados.
 
 - **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.

package/habilidades/memoria-busqueda/SKILL.md

@@ -71,29 +71,26 @@ sobre el ranking RRF si lo desea. Si `rrf-fusion.js` no está disponible,
 
 **Cuándo usar**: Siempre primero. Retorna solo id, tipo, título, fecha y relevancia.
 
-```js
-const { search } = require('./hooks/lib/memory-search');
-
-// Busqueda basica
-const resultados = search(baseDir, "error build classpath");
-// → [
-//     { id: "apr-5",               tipo: "aprendizaje", titulo: "Fix classpath Maven en CI", fecha: "2026-03-10", relevancia: 0.9 },
-//     { id: "ses-20260310-142000", tipo: "sesion",      titulo: "Investigacion build Java",  fecha: "2026-03-10", relevancia: 0.6 },
-//   ]
-
-// Con filtros
-const soloAprendizajes = search(baseDir, "autenticación JWT", {
-  tipo:        'aprendizaje',
-  fecha_desde: '2026-01-01',
-  limit:       10,
-});
+```bash
+# Búsqueda básica (JSON a stdout)
+swl-ses memoria-search search --query="error build classpath"
+# → [
+#     { "id": "apr-5",               "tipo": "aprendizaje", "titulo": "Fix classpath Maven en CI", "fecha": "2026-03-10", "relevancia": 0.9 },
+#     { "id": "ses-20260310-142000", "tipo": "sesion",      "titulo": "Investigacion build Java",  "fecha": "2026-03-10", "relevancia": 0.6 }
+#   ]
+
+# Con filtros
+swl-ses memoria-search search --query="autenticación JWT" --tipo=aprendizaje --desde=2026-01-01 --limit=10
 ```
 
+(El CLI resuelve cross-scope; en el repo madre el módulo equivalente es
+`hooks/lib/memory-search.js` — `search(baseDir, query, filtros)`.)
+
 **Filtros disponibles**:
-- `tipo`: `'aprendizaje'` | `'sesion'` | `'instinto'` (sin filtro = todas las fuentes)
-- `fecha_desde`: string YYYY-MM-DD — excluye resultados anteriores
-- `fecha_hasta`: string YYYY-MM-DD — excluye resultados posteriores
-- `limit`: número máximo de resultados (default: 20)
+- `--tipo`: `aprendizaje` | `sesion` | `instinto` (sin filtro = todas las fuentes)
+- `--desde`: YYYY-MM-DD — excluye resultados anteriores
+- `--hasta`: YYYY-MM-DD — excluye resultados posteriores
+- `--limit`: número máximo de resultados (default: 20)
 
 **Costo por resultado**: ~50-100 tokens. Seguro pedir hasta 20 resultados.
 
@@ -104,17 +101,14 @@ const soloAprendizajes = search(baseDir, "autenticación JWT", {
 **Cuándo usar**: Después de search(), para los 3-7 resultados más relevantes.
 Agrega contexto resumido sin traer el contenido completo.
 
-```js
-const { timeline } = require('./hooks/lib/memory-search');
-
-// Tomar los 5 ids mas relevantes de search()
-const ids  = resultados.slice(0, 5).map(r => r.id);
-const ctx  = timeline(baseDir, ids);
-// → [
-//     { id: "apr-5", tipo: "aprendizaje", titulo: "...", contenido: "<primeros 500 chars>", fecha: "2026-03-10" },
-//     { id: "ses-...", tipo: "sesion", contenido: "Modo: dev | Tool calls: 47 | Archivos: build.gradle | ...", fecha: "2026-03-10" },
-//   ]
-// Ordenado descendente por fecha (más reciente primero).
+```bash
+# Tomar los 3-7 ids más relevantes de search()
+swl-ses memoria-search timeline --ids=apr-5,ses-20260310-142000
+# → [
+#     { "id": "apr-5", "tipo": "aprendizaje", "titulo": "...", "contenido": "<primeros 500 chars>", "fecha": "2026-03-10" },
+#     { "id": "ses-...", "tipo": "sesion", "contenido": "Modo: dev | Tool calls: 47 | Archivos: build.gradle | ...", "fecha": "2026-03-10" }
+#   ]
+# Ordenado descendente por fecha (más reciente primero).
 ```
 
 **Costo por entrada**: ~200-500 tokens. Seguro para 5-7 entradas simultáneas.
@@ -126,15 +120,13 @@ const ctx  = timeline(baseDir, ids);
 **Cuándo usar**: Solo para los 1-3 resultados definitivamente relevantes.
 Retorna el contenido completo sin truncar.
 
-```js
-const { fetch } = require('./hooks/lib/memory-search');
-
-// Solo para el resultado más relevante
-const detalle = fetch(baseDir, "apr-5");
-// → { id: "apr-5", tipo: "aprendizaje", contenido: "<bloque completo del APRENDIZAJES.md>" }
+```bash
+# Solo para el resultado más relevante
+swl-ses memoria-search fetch --id=apr-5
+# → { "id": "apr-5", "tipo": "aprendizaje", "contenido": "<bloque completo del APRENDIZAJES.md>" }
 
-const sesionCompleta = fetch(baseDir, "ses-20260310-142000");
-// → { id: "ses-...", tipo: "sesion", contenido: { ...objeto JSON completo... } }
+swl-ses memoria-search fetch --id=ses-20260310-142000
+# → { "id": "ses-...", "tipo": "sesion", "contenido": { ...objeto JSON completo... } }
 ```
 
 **Costo**: ~500-1,000 tokens por resultado. NO hacer fetch de todos los resultados.

package/habilidades/planear-fase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: planear-fase
 description: Crea el PLAN.md ejecutable para una fase de desarrollo. Descompone la fase en tareas atómicas con dependencias explícitas, las agrupa en oleadas de ejecución paralela cuando es posible, y aplica verificación goal-backward para garantizar que el plan completo satisface los criterios de éxito definidos en CONTEXTO.md.
-version: "1.3.2"
+version: "1.3.3"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar si no existe CONTEXTO.md para la fase — ejecutar `discutir-fase` primero."
@@ -283,6 +283,14 @@ Todo REQ del CONTEXTO tiene ≥1 tarea. ✓
 - **Plan sin oleada de verificación final**: el plan puede estar completo pero
   los criterios de éxito sin satisfacer
 - **Mezclar implementación y tests en una sola tarea**: deben ser tareas separadas
+- **Prosa narrativa que contradice el criterio de verificación de la tarea**:
+  cuando la descripción dice una cosa y el criterio verificable dice otra,
+  **el criterio manda** — es la autoridad más específica y comprobable [caso
+  real F22·T-06, 2026-07-10: la prosa decía "un no-op puede spawnear" y el
+  criterio exigía "no-op → detector NO corre"; el implementador resolvió a
+  favor del criterio y documentó la ambigüedad]. El autor del plan debe
+  auto-revisar esta consistencia; el ejecutor que la detecte resuelve por el
+  criterio y registra la desviación — nunca elige en silencio
 
 ---
 

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

@@ -1,166 +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`).
+# 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`).