refacil-sdd-ai 2.1.9 → 2.2.1

package/README.md

@@ -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` | Integrar codigo (destino por defecto `testing`) y gestionar PR cuando aplique |
+| `/refacil:up-code` | Integrar codigo a rama propia del desarollo y gestionar PR |
 | `/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 integrar cambios (a `testing` o con PR a otra rama) -> `/refacil:up-code`
+- Quiero subir cambios al repositorio -> `/refacil:up-code`
 - Tengo un error en produccion o bug funcional -> `/refacil:bug`
 
 ## Flujo minimo recomendado (equipo)
@@ -97,15 +97,16 @@ Para mantener trazabilidad y calidad sin pasos innecesarios:
 2. `/refacil:apply`
 3. `/refacil:test`
 4. `/refacil:verify`
-5. `/refacil:review` (automatico si no se ejecuto — ver [Hooks automaticos](#hooks-automaticos))
+5. `/refacil:review` (si lo omites, `/refacil:up-code` lo dispara antes del push)
 6. `/refacil:archive`
 7. `/refacil:up-code`
 
-Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
+Si es bugfix, inicia con `/refacil:bug` (ya genera tests de regresion internamente) y continua 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.
+> **Nota — dos capas independientes de chequeo de review**:
+> - `/refacil:up-code` detecta si falta `.review-passed` y **ejecuta `/refacil:review` automaticamente** antes del push.
+> - El hook `check-review` (en `.claude/settings.json`) intercepta tambien `git push` manuales y **bloquea** la operacion si falta `.review-passed`. El hook NO invoca skills por si mismo — solo bloquea y emite instrucciones para ejecutar `/refacil:review` manualmente.
 >
-> 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
 
@@ -118,7 +119,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 /refacil:test
 /refacil:verify
 # → Si hay correcciones: verify pregunta si aplicarlas automaticamente
-# → Si aprueba: aplica fixes y re-verifica (max 2 rondas)
+# → Si aprueba: aplica fixes y re-verifica (maximo 2 rondas de correccion automatica)
 /refacil:review
 /refacil:archive
 /refacil:up-code
@@ -148,7 +149,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 >
 > **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).
+> En cambios regulares (feature/mejora) que se archivan con OpenSpec, Refacil **extrae los campos** de `.review-passed` (JSON) y los persiste como `review.yaml` dentro de cada spec afectado (o en `openspec/specs/review-metadata.yaml` si no hay mapeo preciso). El archivo `.review-passed` original no se copia: solo su contenido convertido a YAML.
 
 ### Explorar codigo
 
@@ -156,6 +157,143 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 /refacil:explore "que quiero entender"
 ```
 
+## Diagrama de flujo completo
+
+Vista unica del ciclo de vida de un cambio — desde la necesidad hasta el PR integrado.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              INICIO: Necesidad de cambio                        │
+└────────────────────────────────┬────────────────────────────────┘
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │  ¿Repo configurado?    │
+                    └───┬────────────────┬───┘
+                      NO│                │SI
+                        ▼                │
+              ┌──────────────────┐       │
+              │ refacil-sdd-ai   │       │
+              │ init             │       │
+              │ /refacil:setup   │       │
+              └────────┬─────────┘       │
+                       └────────┬────────┘
+                                ▼
+                    ┌────────────────────────┐
+                    │   ¿Que tipo de tarea?  │
+                    └───┬────────┬───────┬───┘
+                        │        │       │
+              ┌─────────┘        │       └─────────┐
+              ▼                  ▼                 ▼
+     ┌────────────────┐  ┌──────────────┐  ┌──────────────┐
+     │ FEATURE NUEVO  │  │     BUG      │  │  EXPLORAR    │
+     └───────┬────────┘  └──────┬───────┘  └──────┬───────┘
+             │                  │                 │
+             ▼                  ▼                 ▼
+    ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
+    │/refacil:propose │ │/refacil:bug  │ │/refacil:explore │
+    │                 │ │              │ │                 │
+    │ Genera:         │ │ Investiga +  │ │ Analiza codigo  │
+    │ • proposal.md   │ │ fix + test   │ │ sin modificar   │
+    │ • specs/        │ │ de regresion │ │                 │
+    │ • design.md     │ │ (interno)    │ │     (FIN)       │
+    │ • tasks.md      │ │              │ └─────────────────┘
+    └────────┬────────┘ └──────┬───────┘
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ REVISAR         │        │
+    │ artefactos      │        │
+    │ (aprobacion     │        │
+    │  humana)        │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:apply  │        │
+    │ Implementa      │        │
+    │ tasks           │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:test   │        │
+    │ Tests unitarios │        │
+    │ + edge cases    │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:verify │        │
+    │ ¿Cumple specs?  │        │
+    │ (max 2 rondas   │        │
+    │  autofix)       │        │
+    └────────┬────────┘        │
+             │                 │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │ /refacil:review │
+             │ Checklist       │──► genera .review-passed
+             │ calidad         │    (JSON con veredicto)
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │/refacil:archive │
+             │ Mueve a archive/│
+             │ Sincroniza specs│
+             │ (bug → fix-*/   │
+             │  spec OpenSpec) │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │/refacil:up-code │
+             │ commit + push   │
+             │ + PR            │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │   PR creado     │
+             │     (FIN)       │
+             └─────────────────┘
+```
+
+### Gate de review en el push
+
+Vista del mecanismo de dos capas que protege `git push`:
+
+```
+                ┌──────────────────────────────┐
+                │ Dev ejecuta /refacil:up-code │
+                │       o git push manual      │
+                └────────────────┬─────────────┘
+                                 │
+          ┌──────────────────────┴──────────────────────┐
+          │ Via /refacil:up-code                        │ git push directo
+          ▼                                             ▼
+┌─────────────────────────┐                ┌───────────────────────────┐
+│ up-code detecta         │                │ Hook check-review          │
+│ .review-passed faltante │                │ (PreToolUse en Bash)       │
+│                         │                │                            │
+│ INVOCA /refacil:review  │                │ Verifica .review-passed    │
+│ automaticamente         │                │ en openspec/changes/*      │
+└────────────┬────────────┘                └────────────┬───────────────┘
+             │                                          │
+             ▼                                          ▼
+      ┌──────────────┐                         ┌─────────────────┐
+      │ Review OK?   │                         │ Falta alguno?   │
+      └──┬────────┬──┘                         └──┬───────────┬──┘
+       SI│      NO│                              SI│         NO│
+         ▼        ▼                                ▼           ▼
+   ┌─────────┐ ┌────────────┐              ┌─────────────┐ ┌────────┐
+   │ push OK │ │ informa    │              │ block +     │ │ allow  │
+   │         │ │ correccion │              │ instruccion │ │ push   │
+   │         │ │ no pushea  │              │ a ejecutar  │ │        │
+   │         │ │            │              │ /refacil:   │ │        │
+   │         │ │            │              │ review      │ │        │
+   └─────────┘ └────────────┘              └─────────────┘ └────────┘
+```
+
 ## Reglas metodologicas transversales
 
 Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
@@ -163,14 +301,13 @@ 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, creacion de ramas e integracion por `testing`
+- Politica unificada de ramas protegidas, creacion de ramas e integracion por pr
 - 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`.
 
@@ -191,21 +328,35 @@ El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
 | Hook | Evento | Que hace |
 |------|--------|----------|
 | `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente |
-| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, ejecuta `/refacil:review` automaticamente |
+| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, **bloquea el push** y emite instrucciones para ejecutar `/refacil:review`. El hook no invoca skills por si mismo. |
 
 #### Flujo del hook de review
 
+El hook unicamente decide `allow` o `block`. La ejecucion automatica de `/refacil:review` la realiza `/refacil:up-code`, no el hook.
+
 ```
-/refacil:up-code (o git push manual)
-  → Hook check-review se dispara
-  → Busca carpetas en openspec/changes/ (excluye archive/)
-  → ¿Todas tienen .review-passed?
-      SI → permite el push
-      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>
+git push (manual o via /refacil:up-code)
+  │
+  ▼
+Hook check-review se dispara
+  │
+  ▼
+Busca carpetas activas en openspec/changes/ (excluye archive/)
+  │
+  ▼
+¿Todas tienen .review-passed?
+  │
+  ├─ SI ──► allow → el push procede
+  │
+  └─ NO ──► block → emite mensaje instructivo:
+             • 1 pendiente   → sugiere "/refacil:review <cambio>"
+             • N pendientes  → lista cambios y pide seleccionar uno
+
+Capa adicional cuando se usa /refacil:up-code:
+  /refacil:up-code detecta el faltante ANTES de llamar a git push,
+  invoca /refacil:review y solo entonces intenta el push.
+    • Si el review APRUEBA      → genera .review-passed → push procede
+    • Si requiere CORRECCIONES  → informa al usuario, no pushea
 ```
 
 #### Evidencia de review
@@ -260,7 +411,7 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 .claude/skills/refacil-*/    # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
 .claude/settings.json        # Hooks automaticos (check-update + check-review)
 .cursor/skills/refacil-*/    # Cursor — copia equivalente
-.../refacil-setup/           # troubleshooting.md si falla install/PATH
+.claude/skills/refacil-setup/troubleshooting.md  # guia incluida en refacil-setup si falla install/PATH
 CLAUDE.md                    # Claude Code — apunta a AGENTS.md
 .cursorrules                 # Cursor — apunta a AGENTS.md
 AGENTS.md                    # Generado por /refacil:setup (NO por el CLI)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.1.9",
+  "version": "2.2.1",
   "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"