# 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.
- **Gate G8 — evidencia de calidad obligatoria**: antes de mover un skill
  desde `_userland/plugins/` a `habilidades/`, ejecutar
  `/swl:evaluar-skill <nombre>` y exigir badge ≥ **Plata** (score ≥ 70).
  Skills con Bronce o sin badge se devuelven a `_userland/` con feedback
  de qué dimensiones bajan el score. Detalle del flujo en
  `agentes/auto-evolucion-swl.md` sección "Gate G8". Origen ADR 0013
  sección 3C.
- La promoción se registra en `.planning/AUDITORIA.md` con justificación
  Y en `.planning/evolucion/evoluciones.jsonl` con evento
  `tipo: "promocion-skill"` y `score`.

### 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
