refacil-sdd-ai 2.1.8 → 2.1.9

package/README.md

@@ -53,7 +53,7 @@ refacil-sdd-ai init          # Instalar skills, hooks y crear configs en el repo
 refacil-sdd-ai update        # Actualizar skills y hooks a la ultima version
 refacil-sdd-ai check-update  # Verifica si hay una version mas reciente en npm (usado por hook)
 refacil-sdd-ai check-review  # Verifica que el review se haya completado (usado por hook)
-refacil-sdd-ai clean         # Eliminar skills del repo
+refacil-sdd-ai clean         # Eliminar skills y remover hooks SDD-AI del repo
 refacil-sdd-ai help          # Ver ayuda
 ```
 
@@ -72,7 +72,7 @@ Una vez instalado, estos comandos estan disponibles en Claude Code y Cursor:
 | `/refacil:verify` | Validar implementacion vs specs (con opcion de aplicar correcciones) |
 | `/refacil:review` | Review con checklist de calidad del equipo |
 | `/refacil:archive` | Archivar cambio completado |
-| `/refacil:up-code` | Subir codigo a rama de desarrollo (con validacion de ramas protegidas) |
+| `/refacil:up-code` | Integrar codigo (destino por defecto `testing`) y gestionar PR cuando aplique |
 | `/refacil:bug` | Flujo guiado completo para investigar y corregir bugs |
 
 ## Uso rapido (guia de decision)
@@ -86,7 +86,7 @@ Si no tienes claro que comando usar, aplica esta regla simple:
 - Quiero validar cumplimiento contra spec -> `/refacil:verify`
 - Quiero evaluacion de calidad tecnica -> `/refacil:review`
 - Ya termine y quiero cerrar el cambio en OpenSpec -> `/refacil:archive`
-- Quiero subir cambios y abrir PR -> `/refacil:up-code`
+- Quiero integrar cambios (a `testing` o con PR a otra rama) -> `/refacil:up-code`
 - Tengo un error en produccion o bug funcional -> `/refacil:bug`
 
 ## Flujo minimo recomendado (equipo)
@@ -101,9 +101,11 @@ Para mantener trazabilidad y calidad sin pasos innecesarios:
 6. `/refacil:archive`
 7. `/refacil:up-code`
 
-Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:review` → `/refacil:up-code`.
+Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
 
 > **Nota**: `/refacil:up-code` verifica automaticamente que el review se haya completado. Si no se ejecuto `/refacil:review`, lo lanza automaticamente antes del push como medida de seguridad.
+>
+> Politica de integracion: la rama objetivo por defecto es `testing` mediante PR. Para cualquier otra rama protegida tambien se requiere PR. No hay integraciones directas a ramas protegidas.
 
 ## Flujos de trabajo
 
@@ -125,15 +127,28 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 ### Bug fix
 
 ```
+/refacil:setup
+# → Precondicion si el repo aun no tiene openspec/ (solo la primera vez)
 /refacil:bug "descripcion del error"
 # → Investiga, implementa fix, genera tests de regresion
-# → Crea trazabilidad en openspec/changes/fix-[ID]-[nombre]/summary.md
-# → Pregunta por ID de ticket (ej. REF-123) para nombrar la carpeta
+# → Crea trazabilidad en openspec/changes/fix-[descripcion-corta]/summary.md
+# → Nombre siempre descriptivo (sin IDs de ticket)
 /refacil:review
+# → Evalua calidad del fix, crea .review-passed si aprueba
+/refacil:archive
+# → Archiva el fix SIN pasar por OpenSpec (evita error por falta de artefactos completos)
+# → Mueve carpeta a openspec/changes/archive/[fecha]-[nombre]/
+# → Crea spec individual en openspec/specs/fix-[nombre]/spec.md
+#   en formato OpenSpec estandar (Purpose/Requirements/Scenario)
+# → Crea openspec/specs/fix-[nombre]/review.yaml con metadata del review
 /refacil:up-code
 ```
 
 > **Nota**: En una misma rama pueden corregirse multiples bugs. Cada uno genera su propia carpeta `fix-*` con su trazabilidad independiente.
+>
+> **Importante**: `/refacil:archive` requiere review aprobado (`.review-passed`). Si no existe, bloquea el archivado. Para bugs, el archive no delega a OpenSpec — hace el archivado manual y documenta el bug en `openspec/specs/` como spec individual en formato OpenSpec estandar, con `review.yaml` separado.
+>
+> En cambios regulares (feature/mejora) que se archivan con OpenSpec, Refacil tambien persiste la metadata del `.review-passed` en `review.yaml` dentro de cada spec afectado (o en `openspec/specs/review-metadata.yaml` si no hay mapeo preciso).
 
 ### Explorar codigo
 
@@ -148,9 +163,17 @@ Para mantener consistencia entre todas las skills, el paquete define un contrato
 - Estados del flujo (Ready for Propose/Apply/Verify/Review/Archive/Merge)
 - Politica de `AGENTS.md` por perfil (`openspec` vs `agents`)
 - Resolucion de comando de tests multi-stack (sin hardcodear `npm test`)
-- Politica unificada de ramas protegidas y creacion de ramas
+- Politica unificada de ramas protegidas, creacion de ramas e integracion por `testing`
 - Modo de salida estandar: `conciso` por defecto, `detallado` bajo demanda
 
+### Politica de ramas (resumen)
+
+- Toda rama nueva de trabajo (`feature/*`, `fix/*`, `hotfix/*`, etc.) se crea desde `develop` o `dev` actualizado.
+- Excepcion para repos nuevos: si no existe `develop`/`dev`, se permite usar temporalmente `main` o `master` como rama base.
+- La integracion por defecto de features/bugs es hacia `testing` mediante PR.
+- Toda integracion a ramas protegidas (`testing`, `develop`, `dev`, `main`, `master`, `qa`) requiere PR.
+- NUNCA se hacen ajustes directos en `master` o `main`.
+
 ### Checkpoints de estado (DoR/DoD)
 
 Antes de avanzar de etapa, valida estos estados:
@@ -159,7 +182,7 @@ Antes de avanzar de etapa, valida estos estados:
 - `READY_FOR_VERIFY`: implementacion terminada y enfocada al alcance
 - `READY_FOR_REVIEW`: verify ejecutado y bloqueantes tratados
 - `READY_FOR_ARCHIVE`: cambio funcionalmente cerrado + review aprobado (`.review-passed`)
-- `READY_FOR_MERGE`: review aprobado (`.review-passed`), rama remota actualizada para PR
+- `READY_FOR_MERGE`: review aprobado (`.review-passed`) y PR creado hacia la rama destino protegida
 
 ### Hooks automaticos
 
@@ -178,9 +201,11 @@ El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
   → Busca carpetas en openspec/changes/ (excluye archive/)
   → ¿Todas tienen .review-passed?
       SI → permite el push
-      NO → bloquea y ejecuta /refacil:review automaticamente
+      NO y hay 1 pendiente → bloquea y ejecuta /refacil:review <cambio> automaticamente
             → Si APROBADO: crea .review-passed, reintenta push
             → Si REQUIERE CORRECCIONES: informa al usuario, no pushea
+      NO y hay multiples pendientes → bloquea y pide seleccionar cambio explicito
+            → luego ejecutar /refacil:review <cambio-seleccionado>
 ```
 
 #### Evidencia de review
@@ -195,7 +220,7 @@ openspec/changes/mi-feature/
 ├── specs.md
 └── .review-passed        ← evidencia de review aprobado (JSON)
 
-openspec/changes/fix-REF-123-login-timeout/
+openspec/changes/fix-session-timeout-redis/
 ├── summary.md            ← trazabilidad del bug fix
 └── .review-passed        ← evidencia de review aprobado (JSON)
 ```
@@ -224,7 +249,8 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 /refacil:verify              →  Validacion PASS/FAIL (puede aplicar fixes con aprobacion)
 /refacil:review              →  Review con checklist + .review-passed si aprueba
 /refacil:bug                 →  Fix + trazabilidad en openspec/changes/fix-*/summary.md
-/refacil:archive             →  Cambio archivado
+/refacil:archive             →  Cambio archivado + specs sincronizadas
+                                 (bugs: crea openspec/specs/fix-*/spec.md OpenSpec + review.yaml)
 /refacil:up-code             →  Verifica review (si falta lo ejecuta) + push a rama
 ```
 
@@ -246,6 +272,7 @@ openspec/                    # Generado por /refacil:setup via OpenSpec
 ```bash
 # Eliminar skills del repo actual
 refacil-sdd-ai clean
+# (tambien remueve hooks SDD-AI de .claude/settings.json)
 
 # Desinstalar paquete global (opcional)
 npm uninstall -g refacil-sdd-ai

package/bin/cli.js

@@ -197,6 +197,48 @@ function installHook() {
   return true;
 }
 
+function uninstallHook() {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) return false;
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (_) {
+    console.log('  No se pudieron remover hooks: .claude/settings.json invalido.');
+    return false;
+  }
+
+  if (!settings.hooks) return false;
+
+  let changed = false;
+
+  if (Array.isArray(settings.hooks.SessionStart)) {
+    const original = settings.hooks.SessionStart.length;
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+      (h) => h._sdd !== true,
+    );
+    if (settings.hooks.SessionStart.length !== original) changed = true;
+    if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
+  }
+
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    const original = settings.hooks.PreToolUse.length;
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+      (h) => h._sdd_review !== true,
+    );
+    if (settings.hooks.PreToolUse.length !== original) changed = true;
+    if (settings.hooks.PreToolUse.length === 0) delete settings.hooks.PreToolUse;
+  }
+
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  if (!changed) return false;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
 // --- Check update ---
 
 function checkUpdate() {
@@ -274,15 +316,21 @@ function checkReview() {
 
   if (missing.length > 0) {
     const names = missing.map((e) => e.name).join(', ');
+    const reason =
+      missing.length === 1
+        ? `[refacil-sdd-ai] Review pendiente para: ${names}. ` +
+          'Ejecuta /refacil:review automaticamente ahora sobre ese cambio pendiente. ' +
+          'Informa al usuario que el review se esta ejecutando automaticamente antes de subir el codigo. ' +
+          'Si el review aprueba, reintenta el git push. ' +
+          'Si el review requiere correcciones, informa los hallazgos al usuario y NO reintentar el push.'
+        : `[refacil-sdd-ai] Hay multiples cambios sin review aprobado: ${names}. ` +
+          'Deten el push y pide al usuario seleccionar explicitamente que cambio quiere subir. ' +
+          'Luego ejecuta /refacil:review <nombre-cambio> para ese cambio especifico y reintenta el push. ' +
+          'No ejecutes review automatico sin seleccion cuando hay mas de un cambio pendiente.';
     console.log(
       JSON.stringify({
         decision: 'block',
-        reason:
-          `[refacil-sdd-ai] Review pendiente para: ${names}. ` +
-          'Ejecuta la skill /refacil:review automaticamente ahora sobre los cambios pendientes. ' +
-          'Informa al usuario que el review se esta ejecutando automaticamente antes de subir el codigo. ' +
-          'Si el review aprueba, reintenta el git push. ' +
-          'Si el review requiere correcciones, informa los hallazgos al usuario y NO reintentar el push.',
+        reason,
       }),
     );
   }
@@ -345,6 +393,11 @@ function clean() {
   console.log('\n  refacil-sdd-ai: Eliminando skills...\n');
   const count = removeSkills();
   console.log(`  ${count} skills eliminadas de .claude/skills/ y .cursor/skills/`);
+  if (uninstallHook()) {
+    console.log('  Hooks SDD-AI removidos de .claude/settings.json');
+  } else {
+    console.log('  No se encontraron hooks SDD-AI para remover.');
+  }
   console.log('  AGENTS.md, CLAUDE.md y .cursorrules no fueron eliminados.');
   console.log('\n  Nota: Los comandos opsx:* de OpenSpec no se eliminan.');
   console.log('  Para eliminar OpenSpec: rm -rf openspec/ .claude/commands/opsx .cursor/commands/opsx\n');
@@ -359,7 +412,7 @@ function help() {
     update        Re-copia skills (para actualizar a nueva version del paquete)
     check-update  Verifica si hay una version mas reciente en npm
     check-review  Verifica que el review se haya completado (usado por hook PreToolUse)
-    clean         Elimina skills de .claude/ y .cursor/
+    clean         Elimina skills y remueve hooks SDD-AI de .claude/settings.json
     help          Muestra esta ayuda
 
   Flujo completo:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/apply/SKILL.md

@@ -44,15 +44,16 @@ OpenSpec a veces solo genera el arbol `specs/**/*.md`; eso **cumple** la fila de
 
 **IMPORTANTE**: Este comando NUNCA genera artefactos SDD. Si no existen, el usuario debe usar `/refacil:propose`.
 
-### Paso 1: Validar rama de trabajo
+### Paso 1: Validar rama de trabajo (bloqueante — antes de escribir cualquier linea de codigo)
 
 Ejecuta `git branch --show-current` para obtener la rama actual.
 
 Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
 
-- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
+- **Si la rama actual es protegida**: ejecutar el protocolo completo de creacion de rama **antes de continuar**. No escribir ni una linea de codigo hasta estar en una rama de trabajo.
 - Para `refacil:apply`, el prefijo sugerido de rama es `feature/`.
-- Si la rama actual ya es de trabajo (feature/fix/hotfix/refactor/etc.), continuar sin interrumpir.
+- Si la rama actual ya es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continuar sin interrumpir.
+- Si el usuario no aprueba la creacion/cambio de rama, **detener**. No continuar con la implementacion.
 
 ### Paso 2: Delegar a OpenSpec apply
 

package/skills/archive/SKILL.md

@@ -25,32 +25,107 @@ Antes de archivar, verifica que el cambio esta realmente completo:
 
 3. **Sin archivos pendientes**: Ejecuta `git status` y verifica si hay cambios sin commitear relacionados al feature. Si los hay, sugiere hacer commit antes de archivar.
 
-Si alguna verificacion falla, informa al usuario pero permite que decida si continuar.
+4. **Review aprobado (bloqueante)**: Verifica que existe el archivo `.review-passed` en la carpeta del cambio (`openspec/changes/[nombre-cambio]/.review-passed`). Si NO existe, **detener el archivado** e informar al usuario:
+   ```
+   No se puede archivar: el cambio no tiene review aprobado.
+   Ejecuta /refacil:review primero.
+   ```
+   Esta verificacion es **obligatoria y bloqueante** — no se puede saltar.
 
-### Paso 2: Delegar a OpenSpec archive
+Si alguna de las verificaciones 1-3 falla, informa al usuario pero permite que decida si continuar.
+Si la verificacion 4 falla, el archivado no puede continuar.
+
+### Paso 2: Determinar tipo de cambio
+
+Inspecciona la carpeta del cambio en `openspec/changes/`:
+
+- **Es un bug fix** si el nombre de la carpeta empieza con `fix-` (creado por `refacil:bug`).
+- **Es un cambio regular** en cualquier otro caso (creado por `refacil:propose`).
+
+Segun el tipo, sigue el paso correspondiente:
+
+### Paso 2A: Bug fix → Archivado manual (sin OpenSpec)
+
+Los bug fixes solo contienen `summary.md` (y opcionalmente `.review-passed`), no tienen los artefactos completos que OpenSpec espera. Por eso se archivan **sin delegar a OpenSpec**.
+
+1. **Mover a archive**: Mueve la carpeta completa del fix a `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/`
+
+2. **Documentar en specs**: Lee el `summary.md` y el `.review-passed` del fix, y crea un spec individual para el bug en `openspec/specs/[nombre-descriptivo]/spec.md`.
+
+   **Nombre de la carpeta en specs**: Usa una descripcion corta y clara del bug en kebab-case (ej. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **NO uses IDs de tickets** (REF-123, JIRA-456, etc.) — el nombre debe ser descriptivo para que `/refacil:explore` pueda encontrar y entender el fix sin contexto externo.
+
+   Contenido del `spec.md` (formato OpenSpec estandar):
+   ```markdown
+   # [nombre-descriptivo] Specification
+
+   ## Purpose
+   Corregir [descripcion clara del bug] para restaurar el comportamiento esperado sin introducir regresiones.
+
+   ## Requirements
+   ### Requirement: [comportamiento esperado principal]
+   El sistema SHALL [comportamiento correcto despues del fix].
+
+   #### Scenario: Bug corregido en condicion original
+   - **WHEN** [condicion que antes fallaba]
+   - **THEN** el sistema SHALL [resultado esperado]
+
+   #### Scenario: Flujo normal permanece estable
+   - **WHEN** [condicion normal]
+   - **THEN** el sistema SHALL [comportamiento normal sin regresion]
+   ```
+
+3. **Persistir metadata de review separada**: crea `openspec/specs/[nombre-descriptivo]/review.yaml` con los campos de `.review-passed`:
+   ```yaml
+   verdict: APROBADO|APROBADO CON OBSERVACIONES
+   date: 2026-04-10T00:00:00.000Z
+   changeName: fix-...
+   summary: "..."
+   failCount: 0
+   blockers: false
+   ```
+
+4. Continua al **Paso 3**.
+
+### Paso 2B: Cambio regular → Delegar a OpenSpec archive
 
 1. Lee `openspec-archive-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
 2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **archive**).
 3. Sigue OpenSpec con argumento **$ARGUMENTS** (sync de specs segun deltas).
 
-### Paso 3: Verificar sincronizacion (aporte Refacil)
-
-Despues de que OpenSpec archive, verifica que `openspec/specs/` fue actualizada:
-
-1. Revisa si hay archivos nuevos o modificados en `openspec/specs/`
-2. Si la sincronizacion no ocurrio (OpenSpec la salto o fallo), ejecuta manualmente la sincronizacion:
-   - Lee la especificacion del cambio archivado: `specs.md` si existe **y** todos los `.md` bajo `specs/` de esa carpeta (misma regla que `refacil:apply`)
-   - Busca el spec principal relevante en `openspec/specs/`
-   - Si existe, integra los cambios (ADDED → agregar, MODIFIED → actualizar, REMOVED → eliminar)
-   - Si NO existe, crea un spec principal nuevo con nombre descriptivo
+4. **Verificar sincronizacion**: Despues de que OpenSpec archive, verifica que `openspec/specs/` fue actualizada:
+   - Revisa si hay archivos nuevos o modificados en `openspec/specs/`
+   - Si la sincronizacion no ocurrio (OpenSpec la salto o fallo), ejecuta manualmente:
+     - Lee la especificacion del cambio archivado: `specs.md` si existe **y** todos los `.md` bajo `specs/` de esa carpeta (misma regla que `refacil:apply`)
+     - Busca el spec principal relevante en `openspec/specs/`
+     - Si existe, integra los cambios (ADDED → agregar, MODIFIED → actualizar, REMOVED → eliminar)
+     - Si NO existe, crea un spec principal nuevo con nombre descriptivo
+
+5. **Persistir evidencia de review en specs (obligatorio)**:
+   - Lee `openspec/changes/[nombre-cambio]/.review-passed` **antes** de mover/archivar (o desde la ruta archivada si ya fue movido).
+   - Toma sus campos (`verdict`, `date`, `summary`, `failCount`, `blockers`, `changeName`).
+   - Crea/actualiza `review.yaml` en cada carpeta de spec afectada (`openspec/specs/<spec-name>/review.yaml`).
+   - Formato de `review.yaml`:
+     ```yaml
+     verdict: APROBADO|APROBADO CON OBSERVACIONES
+     date: 2026-04-10T00:00:00.000Z
+     changeName: nombre-del-cambio
+     summary: "..."
+     failCount: 0
+     blockers: false
+     ```
+   - Si el cambio sincroniza multiples specs, crea/actualiza `review.yaml` en cada una.
+   - Si no se puede determinar con precision los specs afectados, crea/actualiza `openspec/specs/review-metadata.yaml` con un registro por cambio.
+
+6. Continua al **Paso 3**.
 
 El objetivo es que `openspec/specs/` documente como funciona el sistema HOY.
 
-### Paso 4: Confirmar
+### Paso 3: Confirmar
 
 ```
 === Cambio archivado ===
  Cambio: [nombre]
+ Tipo: [Bug fix | Cambio regular]
  Ubicacion: openspec/changes/archive/[fecha]-[nombre]/
  Specs sincronizadas: SI
  Tests: PASS
@@ -58,7 +133,7 @@ El objetivo es que `openspec/specs/` documente como funciona el sistema HOY.
  El cambio ha sido completado y archivado exitosamente.
 ```
 
-### Paso 5: Recomendar subir codigo
+### Paso 4: Recomendar subir codigo
 
 Despues de confirmar el archivado, recomienda al usuario subir los cambios al remoto:
 
@@ -70,5 +145,6 @@ Tip: Ejecuta /refacil:up-code para subir los cambios a tu rama de desarrollo.
 
 - Siempre verificar completitud antes de archivar
 - La sincronizacion de specs es OBLIGATORIA en la metodologia Refacil
+- La metadata de `.review-passed` debe persistirse separada en YAML (`review.yaml`) dentro de cada carpeta de spec
 - No eliminar artefactos, solo moverlos a archive/ para trazabilidad
 - Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)

package/skills/bug/SKILL.md

@@ -15,6 +15,18 @@ Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del
 
 ## Instrucciones
 
+### Paso 0: Verificar prerequisito de trazabilidad
+
+Este flujo crea evidencia en `openspec/changes/`. Antes de continuar:
+
+1. Verifica si existe la carpeta `openspec/` en la raiz del repo.
+2. Si NO existe, deten el flujo y muestra:
+   ```
+   Este flujo de bugfix requiere OpenSpec inicializado para guardar trazabilidad.
+   Ejecuta /refacil:setup y vuelve a correr /refacil:bug.
+   ```
+3. Si existe, continua al Paso 1.
+
 ### Paso 1: Describir el bug
 
 Preguntale al usuario (si no lo proporciono en $ARGUMENTS):
@@ -90,24 +102,17 @@ Genera tests que:
 2. **Verifican el fix**: El mismo test pasa CON el fix
 3. **Verifican no regresion**: Tests del flujo normal siguen pasando
 
-Estructura:
-```typescript
-describe('Bug Fix: [descripcion corta]', () => {
-  it('should [comportamiento correcto] when [condicion que antes fallaba]', () => {
-    // Este test hubiera fallado antes del fix
-  });
-
-  it('should still [comportamiento normal] when [condicion normal]', () => {
-    // Este test verifica que no se rompio nada
-  });
-});
-```
+Detecta el stack y framework de testing del proyecto siguiendo `METHODOLOGY-CONTRACT.md` §3 y los patrones existentes (ubicacion, nombrado, mocks, assertions). Genera los tests con la estructura y convenciones reales del proyecto.
+
+Cada test de regresion debe cubrir:
+- **Caso del bug**: `should [comportamiento correcto] when [condicion que antes fallaba]`
+- **Caso normal**: `should still [comportamiento normal] when [condicion normal]`
 
 ### Paso 8: Crear trazabilidad del fix (obligatorio)
 
-Pregunta al usuario: **"Tienes un ID de tarea o ticket para este bug? (ej. REF-123, JIRA-456)"**
-- Si responde con un ID → nombre de carpeta: `fix-[ID]-[descripcion-corta]` (ej. `fix-REF-123-login-timeout`)
-- Si no tiene o quiere continuar → genera un nombre descriptivo corto: `fix-[descripcion-corta]` (maximo 3-4 palabras en kebab-case, ej. `fix-null-pointer-payment`)
+Genera un nombre de carpeta **siempre descriptivo**: `fix-[descripcion-corta]` (maximo 3-4 palabras en kebab-case, ej. `fix-session-timeout-redis`, `fix-null-pointer-payment`).
+
+**No uses IDs de tickets** (REF-123, JIRA-456, etc.) en el nombre de carpeta — el nombre debe ser descriptivo para que sirva como insumo legible en `/refacil:explore` y en `openspec/specs/`.
 
 **No uses el nombre de la rama** como nombre de carpeta — en una misma rama pueden corregirse multiples bugs, cada uno con su propia carpeta fix.
 
@@ -144,8 +149,9 @@ Este archivo es obligatorio para la trazabilidad del fix y permite que el hook d
  [comando-test]: PASS
 
  Siguientes pasos:
- 1. /refacil:review — Review del fix (obligatorio antes de push)
- 2. /refacil:up-code — Subir los cambios a tu rama de desarrollo
+ 1. /refacil:review — Review del fix (obligatorio antes de archivar)
+ 2. /refacil:archive — Archiva el fix y documenta en openspec/specs/fix-[nombre]/spec.md (OpenSpec) + review.yaml
+ 3. /refacil:up-code — Subir los cambios a tu rama de desarrollo
 ```
 
 ## Reglas

package/skills/guide/SKILL.md

@@ -18,15 +18,15 @@ Eres un guia **breve**: eliges el siguiente comando; el detalle de cada flujo es
 ## Menu
 
 1. Feature nuevo → `/refacil:propose` → `/refacil:apply` → `/refacil:test` → `/refacil:verify` → `/refacil:review` → `/refacil:archive` → `/refacil:up-code`
-2. Bug → `/refacil:bug` → `/refacil:review` → `/refacil:up-code`
+2. Bug → (`/refacil:setup` si falta `openspec/`) → `/refacil:bug` → `/refacil:review` → `/refacil:archive` → `/refacil:up-code`
 3. Explorar → `/refacil:explore`
 4. Tests → `/refacil:test`
 5. Validar implementacion → `/refacil:verify`
 6. Review de calidad → `/refacil:review`
-7. Subir codigo → `/refacil:up-code`
+7. Subir codigo y crear PR → `/refacil:up-code`
 8. Configurar repo → `refacil-sdd-ai init` (global + por repo) y `/refacil:setup`
 
-> **Nota**: `/refacil:up-code` verifica automaticamente que el review se haya completado. Si no se ejecuto `/refacil:review`, lo lanza automaticamente antes del push como medida de seguridad.
+> **Nota**: `/refacil:up-code` verifica que el review este aprobado (`.review-passed`). Si falta y hay un solo cambio pendiente, lanza `/refacil:review` automaticamente (sin re-ejecutar si no hay cambios nuevos). Si hay multiples cambios sin review, pide seleccion explicita. Toda integracion a ramas protegidas (incluyendo `testing`) requiere PR. Nunca se hacen ajustes directos en `master` o `main`. La validacion de rama se hace en `/refacil:apply` o `/refacil:bug`, no en `up-code`.
 
 ## Tips (una linea por herramienta)
 

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -7,9 +7,10 @@ Este archivo centraliza reglas transversales para evitar duplicacion e inconsist
 - **READY_FOR_PROPOSE**: problema entendido (objetivo, alcance, restricciones) y contexto minimo del repo.
 - **READY_FOR_APPLY**: artefactos SDD completos (`proposal.md`, `design.md`, `tasks.md`, especificacion en `specs.md` y/o `specs/**/*.md`) y aprobacion explicita del usuario.
 - **READY_FOR_VERIFY**: implementacion terminada, sin cambios fuera de alcance.
-- **READY_FOR_REVIEW**: verify ejecutado, issues criticos resueltos o explicitamente aceptados por el usuario.
+- **READY_FOR_REVIEW**: para cambios regulares (propose), verify ejecutado e issues criticos resueltos o aceptados por el usuario. Para bug fixes, la implementacion y tests de regresion estan completos (los bugs no pasan por verify).
 - **READY_FOR_ARCHIVE**: review aprobado (`.review-passed` existe), tasks completas o excepciones aprobadas, cambio funcionalmente cerrado.
-- **READY_FOR_MERGE**: review aprobado (`.review-passed` existe), rama remota actualizada para PR. `/refacil:up-code` verifica automaticamente el review antes del push — si falta, lo ejecuta.
+- **READY_FOR_MERGE**: review aprobado (`.review-passed` existe) e integracion lista: PR creado para la rama destino. `/refacil:up-code` verifica automaticamente el review antes del push — si falta, lo ejecuta.
+- Si existen multiples cambios activos sin review, se debe seleccionar explicitamente el cambio objetivo antes de ejecutar review/push.
 
 ## 2) Politica AGENTS.md
 
@@ -33,13 +34,36 @@ Coverage (si aplica): detectar comando del proyecto (`test:cov`, `coverage`, `py
 
 ## 4) Politica de ramas protegidas y creacion de rama
 
-Ramas protegidas: `master`, `main`, `develop`, `dev`, `testing`, `qa`.
+Ramas protegidas (nunca desarrollar directamente en ellas): `master`, `main`, `develop`, `dev`, `testing`, `qa`.
+
+Regla critica:
+- **NUNCA** hacer cambios directos en ramas protegidas.
+- Toda integracion a ramas protegidas se hace mediante PR, sin excepciones (incluye `testing`).
+
+### Creacion de ramas de trabajo
+
+- Regla general: toda rama nueva de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.) debe crearse desde `develop` o `dev` actualizado.
+- Excepcion para repos nuevos: si aun no existe `develop` ni `dev`, se permite crear temporalmente desde `main` o `master`.
+- Si se usa la excepcion, recomendar crear `develop`/`dev` y adoptar ese flujo como estandar del repo.
+- **NUNCA** crear ramas de trabajo desde `testing`, `qa` ni desde otras ramas de feature/bug.
+
+### Integracion
+
+- Toda integracion a cualquier rama protegida requiere **PR**.
+- No hay excepciones: `testing`, `develop`, `main`, `master`, `qa`, `release/*` — todas requieren PR.
+- Recomendar al usuario crear PR a `testing` para que los cambios esten disponibles en el entorno de pruebas.
+
+### Protocolo cuando la rama actual es protegida
+
+Si la rama actual es protegida y se necesita escribir codigo:
 
-Si la rama actual es protegida:
 1. Informar y pedir identificador de tarea (Jira u otro).
 2. Verificar working directory limpio (`git status --porcelain`).
 3. Si hay cambios sin commitear, pedir aprobacion para `git stash push -m "stash-automatico-refacil"`.
-4. Detectar base (`develop` o `dev`), cambiar y actualizar (`git pull origin <base>`).
+4. Detectar rama base para crear rama de trabajo:
+   - Preferir `develop`, luego `dev`.
+   - Solo si no existen (repo nuevo), usar `main` o `master` como excepcion temporal.
+   - Cambiar y actualizar (`git pull origin <base>`). Si ninguna existe, detener.
 5. Crear rama de trabajo:
    - Feature: `feature/<ID>`
    - Bugfix: `fix/<ID>`
@@ -55,3 +79,16 @@ Modo por defecto: **conciso**.
 - **Detallado**: reporte completo por seccion.
 
 Si el usuario no pide detalle, usa modo conciso.
+
+## 6) Scope de review y push
+
+- `up-code` y `check-review` solo deben auto-ejecutar review cuando hay un unico cambio pendiente.
+- Si hay multiples cambios pendientes de review, bloquear y pedir seleccion explicita de `nombre-cambio`.
+- `review` no debe correr en modo masivo por defecto cuando hay multiples cambios activos sin alcance explicito.
+
+## 7) Persistencia de evidencia de review
+
+- `archive` requiere `.review-passed` como precondicion bloqueante.
+- Al archivar cambios regulares (via OpenSpec), la metadata de `.review-passed` debe persistirse en `openspec/specs/`.
+- El formato recomendado es `review.yaml` dentro de cada carpeta de spec afectada.
+- Si no se puede mapear de forma confiable a specs concretos, registrar la evidencia en `openspec/specs/review-metadata.yaml`.

package/skills/review/SKILL.md

@@ -31,10 +31,22 @@ Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` y aplica el modo de salida de
   1) Argumento del usuario (`$ARGUMENTS`)
   2) Cambio activo en `openspec/changes/`
   3) Cambios no commiteados (`git diff`)
+- Si hay multiples cambios activos en `openspec/changes/` y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio revisar.
+- No ejecutes review masivo por defecto cuando hay multiples cambios activos.
+
+**Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review:
+1. Lee la `date` del `.review-passed`.
+2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain` para detectar commits o archivos modificados despues del review.
+3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y re-ejecuta el review completo para evaluar el estado actual.
+4. **Si NO hay cambios nuevos**: informa al usuario y no re-ejecutes:
+   ```
+   El cambio [nombre] ya tiene review aprobado ([verdict] — [date]) y no hay cambios posteriores.
+   ```
 
 ### Paso 1: Identificar que revisar
 
 Si hay un cambio activo en `openspec/changes/`, usalo como referencia.
+Si hay multiples cambios y el usuario ya selecciono uno, revisa solo ese cambio.
 Si el usuario paso un argumento ($ARGUMENTS), revisa ese archivo o carpeta especifica.
 Si no hay cambio activo ni argumento, revisa los cambios no commiteados (git diff).
 

package/skills/up-code/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: refacil:up-code
-description: Subir codigo a la rama de desarrollo — git add, commit y push con validacion de ramas protegidas
+description: Subir codigo y crear PR para integracion — git add, commit, push y PR a la rama destino
 user-invocable: true
 ---
 
-# refacil:up-code — Subir Codigo a Rama de Desarrollo
+# refacil:up-code — Integrar Codigo y Publicar Cambios
 
-Sube los cambios al repositorio remoto asegurando que NUNCA se haga push directo a ramas de ambiente protegidas.
+Sube los cambios al repositorio remoto y genera el PR para integracion.
+Toda integracion a ramas protegidas requiere PR — sin excepciones (incluye `testing`).
+NUNCA se hacen ajustes directos en `master` o `main`.
 
 ## Antes de empezar
 
@@ -15,42 +17,48 @@ Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del
 
 ## Instrucciones
 
-### Paso 1: Detectar rama actual
+### Paso 1: Detectar y validar rama actual
 
 Ejecuta `git branch --show-current` para obtener el nombre de la rama.
 
-### Paso 2: Validar rama
+- Si la rama actual es protegida (`master`, `main`, `develop`, `dev`, `testing`, `qa`), **detente** e informa al usuario:
+  ```
+  No se puede subir codigo desde una rama protegida ([nombre]).
+  La validacion de rama se hace en /refacil:apply o /refacil:bug antes de escribir codigo.
+  Cambia a tu rama de trabajo (feature/*, fix/*, etc.) y vuelve a ejecutar /refacil:up-code.
+  ```
+- Si la rama es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continua.
 
-Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
-
-- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
-- Para `refacil:up-code`, el prefijo sugerido de rama es `feature/` (o `fix/` si el cambio es bugfix).
-- Si el usuario no aprueba la creacion/cambio de rama, detener. No continuar con commit/push.
-
-### Paso 3: Verificar review (obligatorio)
+### Paso 2: Verificar review (obligatorio)
 
 Antes de continuar, verifica si hay cambios activos en `openspec/changes/` (excluir carpeta `archive/`).
 
 Si hay cambios activos:
-1. Para cada carpeta activa, verifica si existe el archivo `.review-passed`
-2. Si **todas** tienen `.review-passed` → continua al paso 4
-3. Si **alguna** no tiene `.review-passed`:
-   - Informa al usuario: "Se detectaron cambios sin review aprobado: [nombres de carpetas sin review]"
-   - Ejecuta `/refacil:review` automaticamente sobre los cambios pendientes
-   - Si el review aprueba (crea `.review-passed`) → continua al paso 4
-   - Si el review requiere correcciones → detente e informa los hallazgos al usuario
+1. Para cada carpeta activa, verifica si existe el archivo `.review-passed`.
+2. Si **todas** tienen `.review-passed` → continua al paso 3.
+3. Si hay **una sola** carpeta sin `.review-passed`:
+   - Informa al usuario cual es.
+   - Ejecuta `/refacil:review <nombre-cambio>` automaticamente sobre ese cambio.
+   - Si el review aprueba (crea `.review-passed`) → continua al paso 3.
+   - Si el review requiere correcciones → detente e informa los hallazgos al usuario.
+4. Si hay **multiples** carpetas sin `.review-passed`:
+   - Deten el flujo y pide al usuario seleccionar explicitamente que cambio quiere subir.
+   - Ejecuta `/refacil:review <nombre-cambio-seleccionado>` solo para ese cambio.
+   - No ejecutes review automatico masivo en este caso.
+
+**IMPORTANTE**: `/refacil:review` verifica internamente si `.review-passed` existe y si hay cambios posteriores. Solo re-ejecuta si detecta cambios nuevos despues del ultimo review aprobado.
 
-Si no hay carpeta `openspec/changes/` o no hay cambios activos → continua al paso 4 (no hay nada que revisar).
+Si no hay carpeta `openspec/changes/` o no hay cambios activos → continua al paso 3 (no hay nada que revisar).
 
-### Paso 4: Verificar cambios pendientes
+### Paso 3: Verificar cambios pendientes
 
 Ejecuta `git status` para verificar si hay cambios para subir.
 
 - Si no hay cambios pendientes ni commits sin push, informa al usuario y detente.
-- Si hay cambios sin commitear, continua al paso 5.
-- Si solo hay commits sin push (nada que commitear), salta directo al paso 6.
+- Si hay cambios sin commitear, continua al paso 4.
+- Si solo hay commits sin push (nada que commitear), salta directo al paso 5.
 
-### Paso 5: Commit de cambios
+### Paso 4: Commit de cambios
 
 1. Ejecuta `git status --short` y muestra al usuario la lista de archivos detectados.
 2. Pide confirmacion explicita antes de stagear todo.
@@ -60,11 +68,11 @@ Ejecuta `git status` para verificar si hay cambios para subir.
 6. Si no se proporciono mensaje, genera uno descriptivo basado en los cambios detectados con `git diff --staged --stat`.
 7. Ejecuta `git commit -m "[mensaje]"`.
 
-### Paso 6: Push a remoto
+### Paso 5: Push a remoto
 
 Ejecuta `git push -u origin [rama-actual]` para subir los cambios.
 
-### Paso 7: Confirmar y crear PR
+### Paso 6: Confirmar y crear PR
 
 1. Muestra el resumen del push:
 ```
@@ -74,26 +82,28 @@ Ejecuta `git push -u origin [rama-actual]` para subir los cambios.
  Remote: origin/[nombre-rama]
 ```
 
-2. **Pregunta al usuario** hacia cual rama destino quiere crear el Pull Request. **No sugieras ni asumas** una rama por defecto. Simplemente pregunta:
+2. **Pregunta al usuario** a que rama quiere crear el PR. Sugiere `testing` como destino por defecto para validacion funcional:
 ```
-Hacia cual rama quieres crear el Pull Request?
+A que rama quieres crear el PR? (recomendado: testing)
 ```
 
-3. Una vez el usuario responda, obtén la URL del repositorio remoto con `git remote get-url origin` y determina el hosting para generar el link correcto de creación del PR:
+3. Obtén la URL del repositorio remoto con `git remote get-url origin` y determina el hosting para generar el link correcto:
    - **GitHub** (url contiene `github.com`): `https://github.com/[owner]/[repo]/compare/[rama-destino]...[rama-actual]?expand=1`
    - **Bitbucket** (url contiene `bitbucket.org`): `https://bitbucket.org/[workspace]/[repo]/pull-requests/new?source=[rama-actual]&dest=[rama-destino]`
    - Si no se puede determinar el hosting, muestra ambos formatos para que el usuario elija.
+   - Nota: para URLs SSH (`git@github.com:owner/repo.git` o `git@bitbucket.org:workspace/repo.git`), extrae owner/workspace y repo del path tras el `:`.
 
-   Nota: para URLs SSH (`git@github.com:owner/repo.git` o `git@bitbucket.org:workspace/repo.git`), extrae owner/workspace y repo del path tras el `:`.
-
-4. Muestra el link al usuario:
+4. Muestra el link al usuario y recomienda PR a `testing`:
 ```
  Crea tu PR aqui: [link]
+
+ Tip: Se recomienda PR a testing para habilitar pruebas integradas
+ antes de promover a otras ramas protegidas.
 ```
 
 ## Reglas
 
-- NUNCA hacer push a ramas protegidas: master, main, develop, dev, testing, qa
-- Si el usuario esta en una rama protegida, SIEMPRE preguntar antes de crear una rama nueva
-- Siempre hacer push a ramas de desarrollo propias (feature/, fix/, hotfix/, refactor/, etc.)
+- NUNCA hacer push directo a ramas protegidas: master, main, develop, dev, testing, qa
+- Si la rama actual es protegida, **detener** — la validacion de rama se hace en `/refacil:apply` o `/refacil:bug`, no aqui
+- Toda integracion a cualquier rama protegida requiere PR
 - No forzar push (--force) a menos que el usuario lo pida explicitamente

package/skills/verify/SKILL.md

@@ -88,8 +88,9 @@ Lista los issues para que el usuario los corrija manualmente. Sugiere ejecutar `
 
 ## Reglas
 
-- Durante la fase de verificacion (Pasos 1-3): NO modificar codigo, solo analizar y reportar
-- Las correcciones SOLO se aplican en el Paso 4, despues del reporte completo y con aprobacion explicita del usuario
+- **verify NUNCA modifica codigo por cuenta propia** — los Pasos 1-3 son solo analisis y reporte
+- Las correcciones SOLO se aplican en el Paso 4, **despues** de presentar el reporte completo y recibir aprobacion explicita del usuario
+- Sin aprobacion explicita, verify termina en el reporte — no toca ningun archivo
 - Las correcciones deben ser quirurgicas: solo lo necesario para resolver los issues reportados
 - Ser estricto con los criterios de la spec
 - Si algo no esta en la spec pero parece necesario, mencionarlo como SUGGESTION (observacion), no como CRITICAL/WARNING