theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/verificacion-factual/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: verificacion-factual
+description: Compuerta de verificación factual que bloquea Edit/Write/Bash (incluido MultiEdit) y exige una investigación concreta (importadores, esquemas de datos, instrucción del usuario) antes de permitir la acción. Mejora la calidad del resultado de forma medible, +2.25 puntos frente a agentes sin compuerta.
+---
+
+# Verificación factual — Compuerta pre-acción que fuerza hechos
+
+Una compuerta pre-acción que obliga al modelo a investigar antes de editar. En lugar de autoevaluación ("¿estás seguro?"), exige hechos concretos. El acto de investigar crea una conciencia del contexto que la autoevaluación nunca logró.
+
+Esta skill es una **capa de verificación factual complementaria** al sistema de permisos de Theus: no lo sustituye ni duplica sus mensajes. El sistema de permisos decide *si* una acción está autorizada; esta compuerta exige *evidencia* de que la acción está bien fundamentada antes del primer intento.
+
+## Cuándo activarla
+
+- Al trabajar en cualquier base de código donde una edición afecta a varios módulos
+- En proyectos con archivos de datos que tienen esquemas o formatos de fecha específicos
+- En equipos donde el código generado por IA debe respetar los patrones existentes
+- En cualquier flujo donde el modelo tiende a adivinar en lugar de investigar
+
+## Concepto central
+
+La autoevaluación de un LLM no funciona. Si preguntas "¿violaste alguna política?", la respuesta siempre es "no". Esto está verificado experimentalmente.
+
+Pero pedir "lista todos los archivos que importan este módulo" fuerza al LLM a ejecutar Grep y Read. La investigación en sí misma crea contexto que cambia el resultado.
+
+**Compuerta de tres etapas:**
+
+```
+1. DENEGAR  — bloquea el primer intento de Edit/Write/Bash
+2. FORZAR   — indica al modelo exactamente qué hechos debe reunir
+3. PERMITIR — autoriza el reintento después de presentar los hechos
+```
+
+La mayoría de los enfoques equivalentes se quedan en la denegación; muy pocos completan las tres etapas.
+
+## Evidencia
+
+Dos pruebas A/B independientes, agentes idénticos, misma tarea:
+
+| Tarea | Con compuerta | Sin compuerta | Diferencia |
+| --- | --- | --- | --- |
+| Módulo de analítica | 8.0/10 | 6.5/10 | +1.5 |
+| Validador de webhooks | 10.0/10 | 7.0/10 | +3.0 |
+| **Promedio** | **9.0** | **6.75** | **+2.25** |
+
+Ambos agentes producen código que corre y pasa los tests. La diferencia está en la profundidad del diseño.
+
+## Tipos de compuerta
+
+### Compuerta de Edit / MultiEdit (primera edición por archivo)
+
+MultiEdit se maneja de forma idéntica: cada archivo del lote pasa por la compuerta de forma individual.
+
+```
+Antes de editar {file_path}, presenta estos hechos:
+
+1. Lista TODOS los archivos que importan/requieren este archivo (busca en el
+   árbol — Glob/Grep, o find/grep vía Bash)
+2. Lista las funciones/clases públicas afectadas por este cambio
+3. Si este archivo lee/escribe archivos de datos, muestra los nombres de campo,
+   la estructura y el formato de fecha (usa valores redactados o sintéticos,
+   nunca datos crudos de producción)
+4. Cita textualmente la instrucción actual del usuario
+```
+
+### Compuerta de Write (primera creación de un archivo nuevo)
+
+```
+Antes de crear {file_path}, presenta estos hechos:
+
+1. Nombra el/los archivo(s) y línea(s) que llamarán a este archivo nuevo
+2. Confirma que ningún archivo existente cumple el mismo propósito (busca en el
+   árbol — Glob/Grep, o find/grep vía Bash)
+3. Si este archivo lee/escribe archivos de datos, muestra los nombres de campo,
+   la estructura y el formato de fecha (usa valores redactados o sintéticos,
+   nunca datos crudos de producción)
+4. Cita textualmente la instrucción actual del usuario
+```
+
+### Compuerta de Bash destructivo (cada comando destructivo)
+
+Se dispara con: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
+
+```
+1. Lista todos los archivos/datos que este comando modificará o eliminará
+2. Escribe un procedimiento de reversión en una línea
+3. Cita textualmente la instrucción actual del usuario
+```
+
+### Compuerta de Bash rutinario (una vez por sesión)
+
+```
+1. La petición actual del usuario en una frase
+2. Qué verifica o produce este comando específico
+```
+
+## Inicio rápido
+
+La compuerta existe en dos niveles, complementarios:
+
+**1. Hook automático (perfil estricto).** El arsenal incluye el motor real en `scripts/hooks/verificacion-factual.js`, registrado en PreToolUse para `Edit|Write` y `Bash`. Se activa corriendo la sesión con `THEUS_HOOK_PROFILE=strict`: el primer toque de cada archivo (y cada comando destructivo) se deniega con el bloque de hechos correspondiente, y el reintento tras presentar los hechos pasa. En el perfil estándar el hook no interviene. Variables de control:
+
+- `THEUS_VERIFICACION_FACTUAL=off` — desactiva la compuerta en la sesión (válvula de escape para trabajo de instalación/reparación).
+- `THEUS_VERIFICACION_GLOBS_EXENTOS` — globs separados por comas exentos del forzado (p. ej. `tests/**,dist/**`).
+- `THEUS_VERIFICACION_EXTRA_DESTRUCTIVOS` — regex adicional de comandos destructivos propios de tu dominio.
+- `THEUS_VERIFICACION_BASH_RUTINARIO_OFF=1` — desactiva solo la compuerta rutinaria de Bash (la destructiva sigue).
+- `THEUS_VERIFICACION_STATE_DIR` — carpeta de estado (por defecto `~/.theus/arsenal/verificacion-factual/`; caduca a los 30 minutos de inactividad).
+
+**2. Flujo de trabajo del agente (cualquier perfil).** Con esta skill activa, el agente ejecuta por sí mismo las tres etapas (denegar → forzar → permitir) antes de cada acción cubierta, reuniendo los hechos del tipo de compuerta correspondiente.
+
+Cómo aplicar el flujo en la práctica:
+
+- **Primera edición de un archivo:** antes de tocarlo, presenta el bloque completo de cuatro hechos de la compuerta de Edit. En ediciones por lote (MultiEdit), cada archivo del lote pasa por la compuerta de forma individual.
+- **Primera creación de un archivo nuevo:** presenta los hechos de la compuerta de Write.
+- **Bash destructivo:** presenta los hechos de su compuerta cada vez. El Bash rutinario pasa por la compuerta una sola vez por sesión.
+- **Reintentos:** una vez presentados los hechos para un archivo o comando, no vuelvas a pasarlo por la compuerta en la misma sesión.
+- **Sesiones largas:** emite el bloque completo de cuatro hechos solo en las primeras denegaciones (unas 3); condensa las posteriores en una sola línea con el ordinal de la denegación, de modo que bloques casi idénticos no se acumulen en la ventana de contexto ni amplifiquen bucles de repetición.
+
+### Ajustes por proyecto
+
+Al aplicar el flujo, adapta la compuerta a tu dominio en las instrucciones del proyecto:
+
+- Exenta rutas que no aportan señal (p. ej. `.venv/**`, `node_modules/**`, `.git/**`).
+- Amplía la lista de patrones de Bash destructivo con los riesgos propios de tu dominio.
+- Si la compuerta entorpece trabajo de instalación o reparación, suspéndela de forma explícita para esa sesión y déjalo anotado.
+
+## Antipatrones
+
+- **No uses autoevaluación en su lugar.** "¿Estás seguro?" siempre recibe un "sí". Está verificado experimentalmente.
+- **No te saltes la comprobación del esquema de datos.** En ambas pruebas A/B los agentes asumieron fechas ISO-8601 cuando los datos reales usaban `%Y/%m/%d %H:%M`. Comprobar la estructura de los datos (con valores redactados) previene toda esta clase de bugs.
+- **No pongas compuerta a cada comando Bash.** El Bash rutinario pasa por la compuerta una vez por sesión. El Bash destructivo, cada vez. Ese equilibrio evita ralentizar sin dejar de atrapar los riesgos reales.
+
+## Buenas prácticas
+
+- Deja que la compuerta se dispare de forma natural. No intentes pre-responder sus preguntas: la investigación en sí es lo que mejora la calidad.
+- Personaliza los mensajes de la compuerta para tu dominio. Si tu proyecto tiene convenciones específicas, añádelas a los prompts de la compuerta.
+- Exenta de la compuerta rutas como `.venv/`, `node_modules/`, `.git/`.
+- No dupliques los mensajes del sistema de permisos de Theus: si el sistema de permisos ya denegó una acción, la compuerta no debe añadir un segundo mensaje sobre lo mismo.
+
+## Skills relacionadas
+
+- `modo-seguro` — Comprobaciones de seguridad en tiempo de ejecución (complementaria, no se solapa)
+- Agente `revisor-codigo` — Revisión posterior a la edición (esta compuerta es investigación previa a la edición)

package/vendor/theus-arsenal/skills/verificacion-laravel/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: verificacion-laravel
+description: "Bucle de verificación para proyectos Laravel: comprobaciones de entorno, linting, análisis estático, pruebas con cobertura, escaneos de seguridad y preparación para el despliegue."
+---
+
+# Bucle de verificación de Laravel
+
+Ejecútalo antes de abrir PRs, tras cambios importantes y antes de desplegar.
+
+## Cuándo usarla
+
+- Antes de abrir un pull request en un proyecto Laravel
+- Tras refactors grandes o actualizaciones de dependencias
+- Verificación previa al despliegue en staging o producción
+- Para ejecutar el pipeline completo lint -> tests -> seguridad -> preparación de despliegue
+
+## Cómo funciona
+
+- Ejecuta las fases en orden, desde las comprobaciones de entorno hasta la preparación del despliegue, de modo que cada capa se apoye en la anterior.
+- Las comprobaciones de entorno y Composer condicionan todo lo demás; detente de inmediato si fallan.
+- El linting y el análisis estático deben estar limpios antes de ejecutar las pruebas completas y la cobertura.
+- Las revisiones de seguridad y migraciones vienen después de las pruebas, para verificar el comportamiento antes de tocar datos o pasos de release.
+- La preparación de build/deploy y las comprobaciones de colas/scheduler son las puertas finales; cualquier fallo bloquea el release.
+
+## Fase 1: comprobaciones de entorno
+
+```bash
+php -v
+composer --version
+php artisan --version
+```
+
+- Verifica que `.env` existe y que las claves requeridas están presentes
+- Confirma `APP_DEBUG=false` en entornos de producción
+- Confirma que `APP_ENV` coincide con el destino del despliegue (`production`, `staging`)
+
+Si usas Laravel Sail en local:
+
+```bash
+./vendor/bin/sail php -v
+./vendor/bin/sail artisan --version
+```
+
+## Fase 1.5: Composer y autoload
+
+```bash
+composer validate
+composer dump-autoload -o
+```
+
+## Fase 2: linting y análisis estático
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+```
+
+Si tu proyecto usa Psalm en lugar de PHPStan:
+
+```bash
+vendor/bin/psalm
+```
+
+## Fase 3: pruebas y cobertura
+
+```bash
+php artisan test
+```
+
+Cobertura (CI):
+
+```bash
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+Ejemplo de CI (formato -> análisis estático -> pruebas):
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+## Fase 4: seguridad y dependencias
+
+```bash
+composer audit
+```
+
+## Fase 5: base de datos y migraciones
+
+```bash
+php artisan migrate --pretend
+php artisan migrate:status
+```
+
+- Revisa con cuidado las migraciones destructivas
+- Asegura que los nombres de migración siguen el formato `Y_m_d_His_*` (p. ej., `2025_03_14_154210_create_orders_table.php`) y describen el cambio con claridad
+- Asegura que los rollbacks son posibles
+- Verifica los métodos `down()` y evita pérdidas de datos irreversibles sin copias de seguridad explícitas
+
+## Fase 6: build y preparación del despliegue
+
+```bash
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+- Asegura que el precalentado de cachés funciona con la configuración de producción
+- Verifica que los workers de cola y el scheduler están configurados
+- Confirma que `storage/` y `bootstrap/cache/` son escribibles en el entorno de destino
+
+## Fase 7: comprobaciones de colas y scheduler
+
+```bash
+php artisan schedule:list
+php artisan queue:failed
+```
+
+Si se usa Horizon:
+
+```bash
+php artisan horizon:status
+```
+
+Si `queue:monitor` está disponible, úsalo para comprobar el backlog sin procesar jobs:
+
+```bash
+php artisan queue:monitor default --max=100
+```
+
+Verificación activa (solo en staging): despacha un job no operativo a una cola dedicada y ejecuta un único worker para procesarlo (asegúrate de tener configurada una conexión de cola distinta de `sync`).
+
+```bash
+php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
+php artisan queue:work --once --queue=healthcheck
+```
+
+Verifica que el job produjo el efecto esperado (entrada de log, fila en la tabla de healthcheck o métrica).
+
+Ejecuta esto únicamente en entornos que no sean de producción, donde procesar un job de prueba sea seguro.
+
+## Ejemplos
+
+Flujo mínimo:
+
+```bash
+php -v
+composer --version
+php artisan --version
+composer validate
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+php artisan test
+composer audit
+php artisan migrate --pretend
+php artisan config:cache
+php artisan queue:failed
+```
+
+Pipeline estilo CI:
+
+```bash
+composer validate
+composer dump-autoload -o
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+composer audit
+php artisan migrate --pretend
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+php artisan schedule:list
+```
+
+## Skills relacionadas
+
+- `tdd-laravel` — estrategias de testing en Laravel con PHPUnit y Pest
+- `patrones-laravel` — arquitectura de Laravel, Eloquent, rutas y patrones de API
+- `seguridad-laravel` — autenticación, autorización y código seguro en Laravel