refacil-sdd-ai 2.2.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +170 -17
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -97,13 +97,15 @@ Para mantener trazabilidad y calidad sin pasos innecesarios:
97
97
  2. `/refacil:apply`
98
98
  3. `/refacil:test`
99
99
  4. `/refacil:verify`
100
- 5. `/refacil:review` (automatico si no se ejecuto — ver [Hooks automaticos](#hooks-automaticos))
100
+ 5. `/refacil:review` (si lo omites, `/refacil:up-code` lo dispara antes del push)
101
101
  6. `/refacil:archive`
102
102
  7. `/refacil:up-code`
103
103
 
104
- Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
104
+ Si es bugfix, inicia con `/refacil:bug` (ya genera tests de regresion internamente) y continua con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
105
105
 
106
- > **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.
106
+ > **Nota — dos capas independientes de chequeo de review**:
107
+ > - `/refacil:up-code` detecta si falta `.review-passed` y **ejecuta `/refacil:review` automaticamente** antes del push.
108
+ > - 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.
107
109
  >
108
110
 
109
111
  ## Flujos de trabajo
@@ -117,7 +119,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
117
119
  /refacil:test
118
120
  /refacil:verify
119
121
  # → Si hay correcciones: verify pregunta si aplicarlas automaticamente
120
- # → Si aprueba: aplica fixes y re-verifica (max 2 rondas)
122
+ # → Si aprueba: aplica fixes y re-verifica (maximo 2 rondas de correccion automatica)
121
123
  /refacil:review
122
124
  /refacil:archive
123
125
  /refacil:up-code
@@ -147,7 +149,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
147
149
  >
148
150
  > **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.
149
151
  >
150
- > 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).
152
+ > 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.
151
153
 
152
154
  ### Explorar codigo
153
155
 
@@ -155,6 +157,143 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
155
157
  /refacil:explore "que quiero entender"
156
158
  ```
157
159
 
160
+ ## Diagrama de flujo completo
161
+
162
+ Vista unica del ciclo de vida de un cambio — desde la necesidad hasta el PR integrado.
163
+
164
+ ```
165
+ ┌─────────────────────────────────────────────────────────────────┐
166
+ │ INICIO: Necesidad de cambio │
167
+ └────────────────────────────────┬────────────────────────────────┘
168
+ │
169
+ ▼
170
+ ┌────────────────────────┐
171
+ │ ¿Repo configurado? │
172
+ └───┬────────────────┬───┘
173
+ NO│ │SI
174
+ ▼ │
175
+ ┌──────────────────┐ │
176
+ │ refacil-sdd-ai │ │
177
+ │ init │ │
178
+ │ /refacil:setup │ │
179
+ └────────┬─────────┘ │
180
+ └────────┬────────┘
181
+ ▼
182
+ ┌────────────────────────┐
183
+ │ ¿Que tipo de tarea? │
184
+ └───┬────────┬───────┬───┘
185
+ │ │ │
186
+ ┌─────────┘ │ └─────────┐
187
+ ▼ ▼ ▼
188
+ ┌────────────────┐ ┌──────────────┐ ┌──────────────┐
189
+ │ FEATURE NUEVO │ │ BUG │ │ EXPLORAR │
190
+ └───────┬────────┘ └──────┬───────┘ └──────┬───────┘
191
+ │ │ │
192
+ ▼ ▼ ▼
193
+ ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
194
+ │/refacil:propose │ │/refacil:bug │ │/refacil:explore │
195
+ │ │ │ │ │ │
196
+ │ Genera: │ │ Investiga + │ │ Analiza codigo │
197
+ │ • proposal.md │ │ fix + test │ │ sin modificar │
198
+ │ • specs/ │ │ de regresion │ │ │
199
+ │ • design.md │ │ (interno) │ │ (FIN) │
200
+ │ • tasks.md │ │ │ └─────────────────┘
201
+ └────────┬────────┘ └──────┬───────┘
202
+ │ │
203
+ ▼ │
204
+ ┌─────────────────┐ │
205
+ │ REVISAR │ │
206
+ │ artefactos │ │
207
+ │ (aprobacion │ │
208
+ │ humana) │ │
209
+ └────────┬────────┘ │
210
+ │ │
211
+ ▼ │
212
+ ┌─────────────────┐ │
213
+ │ /refacil:apply │ │
214
+ │ Implementa │ │
215
+ │ tasks │ │
216
+ └────────┬────────┘ │
217
+ │ │
218
+ ▼ │
219
+ ┌─────────────────┐ │
220
+ │ /refacil:test │ │
221
+ │ Tests unitarios │ │
222
+ │ + edge cases │ │
223
+ └────────┬────────┘ │
224
+ │ │
225
+ ▼ │
226
+ ┌─────────────────┐ │
227
+ │ /refacil:verify │ │
228
+ │ ¿Cumple specs? │ │
229
+ │ (max 2 rondas │ │
230
+ │ autofix) │ │
231
+ └────────┬────────┘ │
232
+ │ │
233
+ └────────┬────────┘
234
+ ▼
235
+ ┌─────────────────┐
236
+ │ /refacil:review │
237
+ │ Checklist │──► genera .review-passed
238
+ │ calidad │ (JSON con veredicto)
239
+ └────────┬────────┘
240
+ ▼
241
+ ┌─────────────────┐
242
+ │/refacil:archive │
243
+ │ Mueve a archive/│
244
+ │ Sincroniza specs│
245
+ │ (bug → fix-*/ │
246
+ │ spec OpenSpec) │
247
+ └────────┬────────┘
248
+ ▼
249
+ ┌─────────────────┐
250
+ │/refacil:up-code │
251
+ │ commit + push │
252
+ │ + PR │
253
+ └────────┬────────┘
254
+ ▼
255
+ ┌─────────────────┐
256
+ │ PR creado │
257
+ │ (FIN) │
258
+ └─────────────────┘
259
+ ```
260
+
261
+ ### Gate de review en el push
262
+
263
+ Vista del mecanismo de dos capas que protege `git push`:
264
+
265
+ ```
266
+ ┌──────────────────────────────┐
267
+ │ Dev ejecuta /refacil:up-code │
268
+ │ o git push manual │
269
+ └────────────────┬─────────────┘
270
+ │
271
+ ┌──────────────────────┴──────────────────────┐
272
+ │ Via /refacil:up-code │ git push directo
273
+ ▼ ▼
274
+ ┌─────────────────────────┐ ┌───────────────────────────┐
275
+ │ up-code detecta │ │ Hook check-review │
276
+ │ .review-passed faltante │ │ (PreToolUse en Bash) │
277
+ │ │ │ │
278
+ │ INVOCA /refacil:review │ │ Verifica .review-passed │
279
+ │ automaticamente │ │ en openspec/changes/* │
280
+ └────────────┬────────────┘ └────────────┬───────────────┘
281
+ │ │
282
+ ▼ ▼
283
+ ┌──────────────┐ ┌─────────────────┐
284
+ │ Review OK? │ │ Falta alguno? │
285
+ └──┬────────┬──┘ └──┬───────────┬──┘
286
+ SI│ NO│ SI│ NO│
287
+ ▼ ▼ ▼ ▼
288
+ ┌─────────┐ ┌────────────┐ ┌─────────────┐ ┌────────┐
289
+ │ push OK │ │ informa │ │ block + │ │ allow │
290
+ │ │ │ correccion │ │ instruccion │ │ push │
291
+ │ │ │ no pushea │ │ a ejecutar │ │ │
292
+ │ │ │ │ │ /refacil: │ │ │
293
+ │ │ │ │ │ review │ │ │
294
+ └─────────┘ └────────────┘ └─────────────┘ └────────┘
295
+ ```
296
+
158
297
  ## Reglas metodologicas transversales
159
298
 
160
299
  Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
@@ -189,21 +328,35 @@ El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
189
328
  | Hook | Evento | Que hace |
190
329
  |------|--------|----------|
191
330
  | `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente |
192
- | `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 |
331
+ | `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. |
193
332
 
194
333
  #### Flujo del hook de review
195
334
 
335
+ El hook unicamente decide `allow` o `block`. La ejecucion automatica de `/refacil:review` la realiza `/refacil:up-code`, no el hook.
336
+
196
337
  ```
197
- /refacil:up-code (o git push manual)
198
- → Hook check-review se dispara
199
- → Busca carpetas en openspec/changes/ (excluye archive/)
200
- → ¿Todas tienen .review-passed?
201
- SI → permite el push
202
- NO y hay 1 pendiente → bloquea y ejecuta /refacil:review <cambio> automaticamente
203
- → Si APROBADO: crea .review-passed, reintenta push
204
- → Si REQUIERE CORRECCIONES: informa al usuario, no pushea
205
- NO y hay multiples pendientes → bloquea y pide seleccionar cambio explicito
206
- → luego ejecutar /refacil:review <cambio-seleccionado>
338
+ git push (manual o via /refacil:up-code)
339
+ │
340
+ ▼
341
+ Hook check-review se dispara
342
+ │
343
+ ▼
344
+ Busca carpetas activas en openspec/changes/ (excluye archive/)
345
+ │
346
+ ▼
347
+ ¿Todas tienen .review-passed?
348
+ │
349
+ ├─ SI ──► allow → el push procede
350
+ │
351
+ └─ NO ──► block → emite mensaje instructivo:
352
+ • 1 pendiente → sugiere "/refacil:review <cambio>"
353
+ • N pendientes → lista cambios y pide seleccionar uno
354
+
355
+ Capa adicional cuando se usa /refacil:up-code:
356
+ /refacil:up-code detecta el faltante ANTES de llamar a git push,
357
+ invoca /refacil:review y solo entonces intenta el push.
358
+ • Si el review APRUEBA → genera .review-passed → push procede
359
+ • Si requiere CORRECCIONES → informa al usuario, no pushea
207
360
  ```
208
361
 
209
362
  #### Evidencia de review
@@ -258,7 +411,7 @@ refacil-sdd-ai init → Skills en .claude/ y .cursor/
258
411
  .claude/skills/refacil-*/ # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
259
412
  .claude/settings.json # Hooks automaticos (check-update + check-review)
260
413
  .cursor/skills/refacil-*/ # Cursor — copia equivalente
261
- .../refacil-setup/ # troubleshooting.md si falla install/PATH
414
+ .claude/skills/refacil-setup/troubleshooting.md # guia incluida en refacil-setup si falla install/PATH
262
415
  CLAUDE.md # Claude Code — apunta a AGENTS.md
263
416
  .cursorrules # Cursor — apunta a AGENTS.md
264
417
  AGENTS.md # Generado por /refacil:setup (NO por el CLI)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "refacil-sdd-ai",
3
- "version": "2.2.0",
3
+ "version": "2.2.1",
4
4
  "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
5
5
  "bin": {
6
6
  "refacil-sdd-ai": "./bin/cli.js"