@saulwade/swl-ses 1.0.0

package/reglas/git-workflow.md

@@ -0,0 +1,245 @@
+# Regla: Git Workflow
+
+Un historial de git limpio es documentación ejecutable del proyecto. Facilita
+bisect, reverts, cherry-picks y revisiones de código. Estas reglas garantizan
+que el historial sea útil y comprensible.
+
+---
+
+## Commits atómicos — 1 cambio lógico = 1 commit
+
+- Un commit contiene exactamente un cambio lógico autocontenido.
+  Se puede entender, revertir y aplicar de forma independiente.
+- Un commit NO mezcla: refactor + nueva feature, bugfix + limpieza de código,
+  cambio de deps + lógica de negocio.
+- Si al escribir el mensaje de commit se necesita usar "y" o "también":
+  es señal de que son dos commits.
+- Commits de trabajo en progreso (`WIP`, `temp`, `fix typo`) están permitidos
+  en ramas de feature, pero se squashean antes del merge.
+- Commits con solo cambios de formato/whitespace: nunca mezclar con cambios
+  de lógica. Hacer un commit dedicado de formateo si es necesario.
+- Tamaño razonable: si un PR tiene un solo commit con 50 archivos modificados,
+  el commit no es atómico — dividir en pasos lógicos.
+
+---
+
+## Mensajes de commit — formato imperativo, <72 chars
+
+Formato estándar:
+```
+<tipo>(<scope>): <descripción en imperativo>
+
+[cuerpo opcional — explicar POR QUÉ, no qué hace el diff]
+
+[footer opcional — refs a tickets, breaking changes]
+```
+
+Tipos permitidos:
+- `feat`: nueva funcionalidad
+- `fix`: corrección de bug
+- `refactor`: cambio que no agrega funcionalidad ni corrige bug
+- `test`: agregar o corregir tests
+- `docs`: cambios en documentación
+- `chore`: actualización de deps, configuración, tooling
+- `perf`: mejora de rendimiento
+- `style`: cambios de formato (espacios, punto y coma, etc.)
+- `ci`: cambios en pipelines de CI/CD
+
+Reglas del mensaje:
+- Primera línea: imperativo, presente, sin punto al final, <72 caracteres.
+  - Mal: `Se agregó validación al formulario.`
+  - Mal: `Agrega validación al formulario de registro de usuario con múltiples campos`
+  - Bien: `feat(auth): agregar validación de formato de email en registro`
+- El cuerpo explica el contexto y la razón del cambio, no repite el diff.
+- Referenciar tickets: `Closes #123`, `Refs #456` en el footer.
+- Breaking changes: `BREAKING CHANGE: descripción` en el footer.
+
+---
+
+## Branches descriptivas
+
+Formato: `<tipo>/<descripcion-en-kebab-case>`
+
+Tipos de branch:
+- `feat/` — nueva feature
+- `fix/` — corrección de bug
+- `refactor/` — refactoring sin cambio funcional
+- `hotfix/` — corrección urgente de producción
+- `chore/` — mantenimiento, actualizaciones de deps
+- `docs/` — solo documentación
+
+Ejemplos:
+- `feat/modulo-facturacion-electronica`
+- `fix/error-calculo-impuesto-ieps`
+- `hotfix/sql-injection-endpoint-productos`
+- `refactor/migrar-callbacks-a-promises`
+
+Reglas:
+- Nombre describe el trabajo, no la persona ni el ticket.
+  - Mal: `branch-juan`, `feat-123`, `nueva-rama`
+  - Bien: `feat/exportacion-reporte-pdf`
+- Vida corta: las ramas de feature no duran más de 2 semanas sin mergearse.
+  Ramas largas generan conflictos masivos.
+- Eliminar la rama después del merge al branch base.
+
+---
+
+## No force-push a main / develop
+
+- `git push --force` y `git push --force-with-lease` están prohibidos en
+  `main`, `master` y `develop`.
+- Estas ramas deben tener protección de branch habilitada en el repositorio.
+- Si se requiere reescribir historial de main: escalar a decisión del equipo,
+  con plan de comunicación y ventana de mantenimiento.
+- En ramas de feature propias: `--force-with-lease` está permitido para rebase
+  interactivo antes del PR, con precaución.
+- Rebase en ramas compartidas (más de un colaborador): siempre coordinar antes.
+
+---
+
+## PRs — descripción y test plan obligatorios
+
+Todo Pull Request debe incluir:
+
+**Título**: sigue el mismo formato que el mensaje de commit.
+
+**Descripción mínima**:
+```markdown
+## Resumen
+- Qué cambió y por qué (1-3 bullets)
+
+## Cambios principales
+- Lista de los cambios técnicos relevantes
+
+## Test plan
+- [ ] Paso 1 para verificar manualmente
+- [ ] Paso 2 para verificar el caso edge
+- [ ] Caso de error verificado
+
+## Screenshots (si hay cambios de UI)
+
+## Notas para el reviewer
+- Contexto adicional, decisiones tomadas, alternativas descartadas
+```
+
+Reglas adicionales:
+- PRs de más de 500 líneas cambiadas: justificar o dividir en PRs menores.
+- Asignar reviewer antes de solicitar revisión.
+- No mergear el propio PR sin revisión (excepto hotfixes urgentes documentados).
+- Resolver todos los comentarios antes de mergear (o marcar como `wontfix` con justificación).
+
+---
+
+## Squash antes de merge
+
+- Commits WIP, de typos y de fix de review se squashean antes del merge.
+- El historial de main muestra solo commits semánticos y atómicos.
+- Estrategia recomendada: `Squash and merge` desde la UI de GitHub/GitLab,
+  o `rebase interactivo` antes del merge.
+- El mensaje del squash debe ser descriptivo del cambio completo, no solo
+  el primer mensaje de la rama.
+- Ramas con múltiples commits lógicos independientes: usar `rebase` en lugar
+  de `squash` para preservar la granularidad.
+
+---
+
+## Flujo completo de trabajo
+
+```
+main ─────────────────────────────────────────► main
+       │                              ▲
+       └─ feat/nombre ──[commits]──[squash]─┘
+              │
+              └─ [PR] ──[review] ──[CI pass] ──[merge]
+```
+
+1. Crear branch desde `main` (o `develop` si existe).
+2. Hacer commits atómicos en la branch.
+3. Mantener la branch actualizada con `git rebase main` (no merge).
+4. Abrir PR con descripción completa.
+5. Pasar CI (linter, tests, type-check).
+6. Obtener aprobación de al menos 1 reviewer.
+7. Squash y merge.
+8. Eliminar la branch.
+
+---
+
+## Reglas de emergencia (hotfixes)
+
+- Un hotfix de producción puede saltarse el proceso completo de review si hay
+  indisponibilidad activa, con las siguientes condiciones:
+  - Notificar al equipo en el canal de incidencias antes de mergear.
+  - El fix más pequeño posible — solo lo que resuelve el incidente.
+  - PR de follow-up con tests dentro de 24 horas.
+  - Post-mortem si el incidente duró más de 30 minutos.
+
+---
+
+## Sincronización de versiones antes de release
+
+Cuando se modifican componentes del sistema SWL (agentes, skills, reglas, hooks,
+comandos, schemas o manifiestos), la versión debe actualizarse en TODOS los
+archivos que la declaran antes de hacer commit y publicar:
+
+| Archivo | Campo | Ejemplo |
+|---------|-------|---------|
+| `package.json` | `"version"` | `"5.0.3"` |
+| `plugin.json` | `"version"` | `"5.0.3"` |
+| `SALUD.md` | `Versión del sistema` | `5.0.3` (todas las ocurrencias) |
+| `.claude/.swl-install-state.json` | `"versionSistema"` | `"5.0.3"` (local, gitignored) |
+
+El tipo de bump sigue SemVer:
+- **PATCH** (5.0.X): correcciones de bugs, mejoras de redacción, ajustes de patrones
+- **MINOR** (5.X.0): agente nuevo, skill nuevo, comando nuevo, regla nueva
+- **MAJOR** (X.0.0): cambio breaking en schemas, reglas obligatorias nuevas, restructuración
+
+Verificación rápida de consistencia:
+```bash
+node -e "const p=require('./package.json'),l=require('./plugin.json');console.log(p.version===l.version?'OK: '+p.version:'INCONSISTENTE: pkg='+p.version+' plugin='+l.version)"
+```
+
+---
+
+## Reglas de oro CI/CD (cuando se adopta swl-configurar-ci)
+
+Cuando un proyecto activa el flujo CI/CD distribuido por swl-ses (vía
+`/swl:configurar-ci init`), aplican las siguientes reglas:
+
+- **Toda feature entra vía Pull Request a main**. Nunca se hace push directo
+  a main — incluso para hotfixes urgentes (excepción documentada explícita).
+- **Branch protection en main es obligatorio**: aplicar via
+  `node scripts/configurar-branch-protection.js` o vía GitHub Settings →
+  Branches.
+- **Todo PR ejecuta automáticamente**: lint, validaciones de aislamiento,
+  tests, security review con Claude. Si algo falla, el merge queda bloqueado.
+- **main siempre lista para producción**. Cualquier commit en main debe
+  pasar el gate de CI antes de mergearse.
+- **Secrets en GitHub Secrets, nunca en código ni en .env del repo**: la
+  `CLAUDE_API_KEY` requerida por el security workflow vive en
+  Settings → Secrets and variables → Actions.
+- **Permisos mínimos en workflows**: `permissions:` declara solo lo
+  estrictamente necesario (`contents: read`, `pull-requests: write`).
+  Nunca `permissions: write-all`.
+- **Workflows desde fork PRs no reciben secrets**: la security review
+  con Claude no puede correr en PRs desde forks externos sin configuración
+  adicional. Esta limitación es de GitHub por diseño — documentarla en el
+  proyecto.
+
+Estas reglas aplican solo cuando swl-configurar-ci está activo. Proyectos
+sin CI/CD pueden mantener flujos directos a main bajo responsabilidad
+del owner.
+
+---
+
+## Checklist antes de abrir un PR
+
+- [ ] Commits son atómicos y tienen mensajes descriptivos
+- [ ] Branch actualizada con `rebase` desde main (sin conflictos)
+- [ ] Tests pasan localmente
+- [ ] Linter y type-checker pasan
+- [ ] PR tiene descripción, cambios principales y test plan
+- [ ] No se fuerza push a main
+- [ ] Commits WIP squasheados
+- [ ] Si se modificaron componentes del sistema (agentes, skills, reglas, hooks):
+      versión actualizada en package.json, plugin.json y SALUD.md
+- [ ] Si el proyecto usa `swl-configurar-ci`, este PR pasa todos los gates de CI

package/reglas/gobernanza.md

@@ -0,0 +1,271 @@
+# Regla: Gobernanza
+
+Esta regla aplica a equipos y proyectos con múltiples contribuidores.
+Define políticas de aprobación, auditoría y control de cambios del sistema SWL.
+En proyectos individuales, sirve como guía de disciplina de cambios.
+
+---
+
+## Políticas de aprobación
+
+### Cambios de alto riesgo
+
+Los siguientes cambios requieren aprobación explícita del líder técnico antes
+de incorporarse al sistema activo. "Aprobación explícita" significa una revisión
+deliberada (no automática) con evidencia documentada en `.planning/AUDITORIA.md`.
+
+Cambios que requieren aprobación:
+
+- Modificación de reglas de seguridad (`reglas/seguridad.md`)
+- Cambios en umbrales de risk scoring en `manifiestos/hooks-config.json`
+- Adición de hooks con `blocking: true`
+- Modificación de agentes con `nivelRiesgo: ALTO`
+- Cambios en manifiestos de instalación (`manifiestos/modulos.json`, `manifiestos/perfiles.json`)
+- Eliminación de reglas o agentes del sistema base
+
+### Skills generados automáticamente
+
+Los skills generados por `auto-evolucion-swl` o `/swl:evolucionar`:
+
+- Se instalan primero en `_userland/plugins/` como período de prueba.
+  NUNCA se incorporan directamente al sistema base sin revisión.
+- Requieren validación en al menos 3 sesiones de trabajo independientes
+  antes de ser promovidos al perfil `completo`.
+- Deben pasar la verificación de `/swl:salud` sin degradar el score actual.
+- La promoción se registra en `.planning/AUDITORIA.md` con justificación.
+
+### Reglas nuevas obligatorias
+
+Una regla nueva que se declare obligatoria para todos los agentes es un cambio
+`MAJOR` del sistema (ver sección de versionado). Requiere:
+
+1. Propuesta documentada: qué problema resuelve y por qué es obligatoria.
+2. Período de revisión de al menos 48 horas antes de activarse.
+3. Comunicación al equipo con tiempo suficiente para adaptarse.
+4. Entrada en el CHANGELOG con descripción del impacto.
+
+---
+
+## Auditoría
+
+### Log de operaciones de alto riesgo
+
+Toda operación marcada como `nivelRiesgo: ALTO` debe registrarse en
+`.planning/AUDITORIA.md` con el siguiente formato:
+
+```markdown
+## [YYYY-MM-DD HH:MM] <tipo-de-operacion>
+
+**Agente**: nombre-agente-swl
+**Operación**: descripción breve de qué se hizo
+**Justificación**: por qué fue necesario
+**Aprobado por**: nombre o "individual" si es proyecto personal
+**Archivos afectados**: lista de rutas modificadas
+**Estado**: completado / revertido
+```
+
+El hook `risk-scoring` genera entradas automáticas para operaciones detectadas.
+Las operaciones manuales de alto riesgo deben registrarse manualmente.
+
+### Supresión de verificaciones
+
+Cuando se necesita suprimir un hook (via `SWL_DISABLED_HOOKS` u otro mecanismo):
+
+- Usar el scope más estrecho posible: archivo o directorio específico,
+  no desactivación global del hook.
+- Documentar en `.planning/AUDITORIA.md`:
+  - Fecha y duración de la supresión
+  - Razón técnica por la que fue necesario
+  - Alcance exacto (qué hook, qué archivos)
+  - Plan de reactivación
+
+Una supresión sin documentación en AUDITORIA.md se considera deuda de gobernanza
+que debe resolverse antes del próximo release.
+
+### Retención de logs
+
+- `.planning/AUDITORIA.md` es un archivo append-only. NUNCA borrar entradas antiguas.
+- Los instintos degradados por `degradacion-instintos.js` se registran
+  automáticamente en el log de instintos, no en AUDITORIA.md.
+- Revisar AUDITORIA.md mensualmente para identificar patrones de operaciones de riesgo.
+
+---
+
+## Separación revisor / ejecutor
+
+Un agente que ejecuta cambios NUNCA verifica su propio trabajo. La verificación
+cruzada entre roles distintos reduce hallucaciones y errores de confirmación.
+
+### Principio
+
+| Rol | Permisos | Responsabilidad |
+|-----|----------|-----------------|
+| **Ejecutor** | Write, Edit, Bash | Implementa cambios según el plan. NO se auto-revisa. |
+| **Revisor** | Read, Grep, Glob, Bash (solo lectura) | Emite veredictos estructurados. NO ejecuta correcciones. |
+
+### Reglas obligatorias
+
+- El ejecutor NUNCA emite un veredicto de aprobación sobre su propio trabajo.
+  Si termina una fase, reporta completitud — el revisor valida.
+- El revisor NUNCA modifica código de producción. Si detecta un problema,
+  emite un veredicto `Fail` con instrucciones concretas en `nextStep.instructions`.
+  El ejecutor aplica las correcciones.
+- En el flujo del orquestador, el revisor y el ejecutor son agentes distintos
+  o invocaciones independientes con contexto separado.
+- Las instrucciones del revisor son específicas: archivo, línea, qué cambiar.
+  "Mejorar el código" no es una instrucción válida.
+- El ejecutor sigue las instrucciones del revisor sin inventar mejoras adicionales
+  no solicitadas. No crea un plan nuevo — ejecuta lo indicado.
+
+### Mapeo a agentes SWL
+
+| Fase | Ejecutor | Revisor |
+|------|----------|---------|
+| Implementación | implementador-swl, backend-*-swl, frontend-*-swl | revisor-codigo-swl, revisor-*-swl |
+| Seguridad | (cualquier implementador) | revisor-seguridad-swl |
+| Testing | tdd-qa-swl (escribe tests) | (el test runner es el revisor) |
+| Verificación de fase | (agente que implementó) | verificar-trabajo (skill) |
+
+### Anti-patrones
+
+- Un agente que dice "revisé mi propio código y se ve bien" — viola la separación.
+- Un revisor que aplica un fix directamente en lugar de emitir instrucciones.
+- Un ejecutor que ignora el veredicto del revisor y marca la tarea como completada.
+- Un loop de reparación infinito — máximo 2 intentos antes de escalar a humano.
+
+---
+
+## Veto items y cap enforcement (auditor-class pattern)
+
+Algunos hallazgos son **no negociables**: violaciones de reglas globales del
+sistema cuya presencia debe bloquear la aprobación independientemente de qué
+tan limpio esté el resto del trabajo. El patrón "veto items + cap enforcement"
+formaliza este criterio para todos los revisores SWL.
+
+### Principio
+
+Un revisor declara una **lista finita y específica de veto items** asociados a
+su dominio. Si detecta CUALQUIER veto item:
+
+- El **score máximo** del reporte queda CAP a un valor de "no aprobado"
+  (ejemplo: `60/100` para reportes en escala 0-100, `6.0/10` para reportes
+  por dimensión).
+- El **veredicto automático** pasa a `RECHAZADO` o `APROBADO CON CORRECCIONES`,
+  nunca `APROBADO` limpio.
+- 2+ veto items → cap más estricto (ej. `30/100` o `3.0/10`).
+
+El cap NO se compensa con scores altos en otras dimensiones. La presencia de un
+veto item indica violación de una regla global no opcional.
+
+### Reglas
+
+1. **Cada revisor declara explícitamente sus veto items** en su agente
+   (sección dedicada en el `.md` del agente, antes del formato de reporte).
+2. **Los veto items mapean a reglas del sistema** (`reglas/seguridad.md`,
+   `reglas/estilo-codigo.md`, `reglas/arquitectura.md`, etc.). NO son criterios
+   inventados ad-hoc por el revisor.
+3. **El reporte muestra los veto items detectados** al inicio, antes de la
+   tabla de scores, en bloque dedicado:
+   ```
+   ### VETO ITEMS DETECTADOS
+   - [VI-1] <descripción del veto>: `archivo.py:42`
+   - [VI-3] <descripción del veto>: `app/util.py:88`
+   → score CAP a X/Y (N veto items). Veredicto: RECHAZADO.
+   ```
+   Si no hay: `### VETO ITEMS DETECTADOS\n- Ninguno`.
+4. **El cap no se levanta por negociación**. Solo se levanta cuando se
+   demuestra remediación (commit + test que prueba la corrección) y el revisor
+   re-ejecuta la auditoría.
+5. **Un veto item siempre referencia una regla global**. Si el revisor cree
+   que algo "debería ser veto" pero no hay regla que lo respalde, primero
+   actualiza la regla, luego agrega el veto.
+
+### Aplicabilidad
+
+Revisores SWL que DEBEN implementar veto items:
+
+- `revisor-seguridad-swl` (10 veto items: secret hardcodeado, SQL injection,
+  eval con input, path traversal, CVE crítico, etc.)
+- `revisor-codigo-swl` (10 veto items: función >100 líneas, complejidad >15,
+  console.log en prod, dependencia circular, DRY mayor, etc.)
+
+Revisores específicos de lenguaje (`revisor-typescript-swl`, `revisor-react-swl`,
+`revisor-rust-swl`, etc.) PUEDEN agregar veto items adicionales propios de su
+dominio, pero deben heredar los del revisor base correspondiente.
+
+Plantilla reusable: `plantillas/auditor-veto-template.md`.
+
+### Anti-patrones
+
+- **Veto inventado sin regla**: "código feo" no es veto válido — necesita
+  regla global que lo prohíba.
+- **Veto suavizado por presión de entrega**: bajar de "veto" a "menor" porque
+  el equipo dispute es invalidación del sistema.
+- **Veto sin evidencia**: cada veto item reportado debe citar archivo:línea.
+- **Veto que no se persiste**: si el cap se levanta sin re-revisión y commit
+  de corrección, el sistema pierde su valor.
+
+---
+
+## Control de cambios del sistema
+
+### Versionado
+
+Todo cambio al sistema SWL sigue SemVer estricto:
+
+| Tipo de cambio | Versión |
+|----------------|---------|
+| Regla nueva marcada como obligatoria | MAJOR |
+| Cambio breaking en schema de agentes o skills | MAJOR |
+| Agente nuevo, skill nuevo, comando nuevo | MINOR |
+| Feature en agente o skill existente | MINOR |
+| Bug fix, corrección de typo, actualización de ejemplo | PATCH |
+| Mejora de descripción sin cambio de comportamiento | PATCH |
+
+El comando `/swl:release` maneja el versionado automáticamente.
+
+### Rollback
+
+Ante un cambio que degrada el sistema:
+
+- La versión anterior debe permanecer disponible (via git) por al menos 1 semana
+  antes de considerarse obsoleta.
+- Los hooks nuevos pueden desactivarse individualmente via variable de entorno
+  `SWL_DISABLED_HOOKS=nombre-hook` sin afectar el resto del sistema.
+- Los agentes nuevos NO reemplazan a los existentes sin un período de transición
+  documentado. Durante la transición, ambas versiones coexisten.
+- Si `/swl:salud` baja su score tras un cambio: revertir antes de continuar.
+
+### Freeze de cambios pre-release
+
+Durante las 24 horas previas a un release:
+
+- Solo se permiten bug fixes críticos (PATCH).
+- No se agregan features ni reglas nuevas.
+- El comando `/swl:salud` debe pasar sin advertencias antes de publicar.
+
+---
+
+## Plugins de terceros
+
+Los plugins instalados via `/swl:plugins install` tienen restricciones adicionales:
+
+- No pueden modificar componentes del sistema base (`agentes/`, `habilidades/`,
+  `reglas/`, `hooks/` en la raíz).
+- Sus hooks con `blocking: true` requieren revisión explícita antes de activarse.
+- Si un plugin no recibe actualizaciones en 6 meses y tiene issues conocidos:
+  marcarlo como deprecado en `.planning/PLUGINS.md`.
+- Los plugins de fuentes no verificadas no se instalan sin auditoría de su código.
+
+---
+
+## Checklist de gobernanza antes de release
+
+- [ ] Todos los cambios de alto riesgo tienen aprobación documentada en AUDITORIA.md
+- [ ] Los skills auto-generados fueron validados en al menos 3 sesiones
+- [ ] Ninguna supresión de hook activa sin justificación documentada
+- [ ] El CHANGELOG.md está actualizado con todos los cambios observables
+- [ ] Los schemas de validación pasan para todos los manifiestos modificados
+- [ ] El comando `/swl:salud` pasa sin errores ni advertencias críticas
+- [ ] La versión en `package.json` refleja el tipo de cambio realizado
+- [ ] Los plugins de terceros instalados siguen siendo compatibles con la versión nueva