refacil-sdd-ai 4.1.1 → 4.1.3

package/agents/auditor.md

@@ -11,6 +11,8 @@ Eres un lider tecnico auditor, exigente pero constructivo, que evalua el codigo
 
 **Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
 
+Si inspeccionas `openspec/changes/<cambio>/` para prereqs o contexto, los marcadores **`.review-passed`** son dotfiles: **`METHODOLOGY-CONTRACT.md` §8** (no concluyas ausencia con `ls` sin `-a`).
+
 ## Guardrail: deteccion de invocacion directa
 
 Estas disenado para ser **delegado por el skill `/refacil:review`**, que resuelve el scope y escribe el marcador `.review-passed` con el JSON que emites. Si detectas que fuiste invocado **directamente** (ej. el prompt del usuario no trae un scope explicito tipo nombre de cambio activo, lista de rutas o "git-diff"), tu PRIMERA respuesta debe ser:

package/agents/validator.md

@@ -29,6 +29,10 @@ Si prefieres solo el reporte (sin aplicar fixes), respondeme con el scope explic
 
 **No procedas con lecturas ni corras tests hasta que el usuario confirme scope.**
 
+## Archivos ocultos en `openspec/changes/<cambio>/`
+
+Antes de afirmar ausencia de **`.review-passed`** u otros dotfiles, aplica **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §8**.
+
 ## Reglas criticas del sub-agente
 
 - **NO modificas ningun archivo**. No tienes `Edit` ni `Write`. Solo lectura + ejecucion de tests via `Bash`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "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/archive/SKILL.md

@@ -22,7 +22,7 @@ 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.
 
-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:
+4. **Review aprobado (bloqueante)**: Verifica que existe el archivo `.review-passed` en la carpeta del cambio (`openspec/changes/[nombre-cambio]/.review-passed`) siguiendo **`METHODOLOGY-CONTRACT.md` §8** (dotfile; no concluyas por listados sin dotfiles). Si NO existe, **detener el archivado** e informar al usuario:
    ```
    No se puede archivar: el cambio no tiene review aprobado.
    Ejecuta /refacil:review primero.

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -98,7 +98,18 @@ Si el usuario no pide detalle, usa modo conciso.
 
 ## 7) Persistencia de evidencia de review
 
-- `archive` requiere `.review-passed` como precondicion bloqueante.
+- `archive` requiere `.review-passed` como precondicion bloqueante (comprobar existencia segun **§8**).
 - 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`.
+
+## 8) Archivos ocultos bajo `openspec/changes/<cambio>/`
+
+- **`.review-passed`** y cualquier archivo cuyo nombre empiece por **`.`** son **ocultos** en muchos entornos: en shell, **`ls` sin `-a` / `-la` no los lista** — no concluyas que no existen por eso (evita falsos negativos en prereqs, review, verify, `up-code` y archive).
+- **Preferido**: herramienta **`Glob`** (patron bajo `openspec/changes/<nombre>/`), **`Read`** sobre la ruta exacta `openspec/changes/<nombre>/.review-passed`, o Bash **`test -f`** / **`[ -f ... ]`** sobre esa ruta.
+- Si el usuario dice que el archivo existe y tu comprobacion lo nego, **re-verifica** con uno de los metodos anteriores antes de insistir.
+
+## 9) Identificador de carpeta bajo `openspec/changes/<cambio>/`
+
+- El **nombre de la carpeta** del cambio activo es el identificador que usa el CLI de OpenSpec (`openspec status --change`, flujos de archive, etc.).
+- **Debe empezar con una letra ASCII** `[a-zA-Z]`. Si el primer caracter es un digito u otro simbolo, el CLI rechaza el nombre (p. ej. `Invalid change name: Change name must start with a letter`).

package/skills/prereqs/OPENSPEC-DELTAS.md

@@ -10,6 +10,7 @@ Lee este archivo **ademas** de la skill `openspec-*` que indique el comando `ref
 
 ## propose — `openspec-propose`
 
+- **Nombre de carpeta del cambio** (`openspec/changes/<nombre>/`): cumplir **`METHODOLOGY-CONTRACT.md` §9** — el primer caracter **debe** ser letra ASCII; **prohibido** crear el cambio con nombre que empiece por digito (incluye prefijos tipo `YYYY-MM-DD-...`). El CLI OpenSpec falla con esos nombres (`openspec status --change`, etc.). Fijar o validar el slug **antes** de generar artefactos.
 - Criterios de aceptacion: formato **Dado / Cuando / Entonces**.
 - Incluir **criterios de rechazo** (edge cases) en specs.
 - Tasks con estimacion de esfuerzo **S / M / L**.

package/skills/propose/SKILL.md

@@ -21,6 +21,16 @@ Si el usuario NO proporciono suficiente contexto en $ARGUMENTS, preguntale:
 
 Si $ARGUMENTS ya es claro, no preguntes de nuevo.
 
+### Paso 1.5: Identificador de carpeta del cambio (bloqueante — CLI OpenSpec)
+
+El directorio `openspec/changes/<nombre>/` **no puede** usar un `<nombre>` cuyo **primer caracter no sea una letra ASCII** `[a-zA-Z]` — ver **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §9**. Nombres como `2026-04-17-exponer-algo` hacen fallar `openspec status --change` y otros comandos.
+
+**Antes del Paso 2:**
+
+1. Acuerda o deriva el **slug final** del cambio (kebab-case: `feat-...`, `exponer-...`, `imp-...`, etc.). Fecha o ticket no van al **inicio** del nombre.
+2. Si el usuario o OpenSpec proponen un nombre invalido, **corrigelo** (p. ej. prefijo `feat-` o `change-`) o pide al usuario el slug; **no** crees la carpeta ni delegues propose hasta tener un nombre valido.
+3. Pasa ese nombre valido al flujo OpenSpec (argumento explicito, contexto o convencion que use `openspec-propose`) para que los artefactos queden bajo `openspec/changes/<nombre-valido>/`.
+
 ### Paso 2: Delegar a OpenSpec ff (fast-forward)
 
 1. Lee `openspec-propose/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
@@ -78,6 +88,7 @@ Quieres que continue con /refacil:apply?
 
 ## Reglas
 
+- **Nombre de carpeta del cambio**: cumplir siempre **§9** del contrato metodologico (primer caracter letra ASCII; nunca iniciar con digito).
 - **NUNCA escribir, modificar o generar codigo fuente** en esta fase — solo artefactos SDD: `proposal.md`, `design.md`, `tasks.md`, y especificacion en `specs.md` y/o `specs/**/*.md` (convencion OpenSpec)
 - Aunque el usuario pase una descripcion completa y detallada en $ARGUMENTS, la salida es EXCLUSIVAMENTE artefactos de planificacion
 - Si el usuario pide que tambien implemente, responder: "La implementacion se hace con `/refacil:apply` despues de aprobar los artefactos."

package/skills/review/SKILL.md

@@ -20,7 +20,7 @@ Este skill es un **wrapper delgado** que delega el review pesado al sub-agente `
   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 invoques al sub-agente con scope ambiguo.**
 
-**Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review:
+**Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review (existencia del marcador: **`METHODOLOGY-CONTRACT.md` §8**):
 1. Lee la `date` del `.review-passed`.
 2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain`.
 3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y continua (invoca al sub-agente para re-evaluar).

package/skills/review/checklist-back.md

@@ -48,7 +48,8 @@
 - Las consultas usan indices apropiados
 - No hay queries N+1
 - No hay inyeccion SQL/NoSQL posible (queries parametrizadas con el ORM/driver del proyecto)
-- Las migraciones (si hay) son reversibles y no rompen datos existentes
+- **Esquema (DDL)**: por defecto, no usar el sistema de migraciones de TypeORM ni `synchronize` para aplicar o versionar cambios de BD (ni `MigrationInterface`, ni depender de `migration:run` / `migration:generate` en el flujo de despliegue de la app). Los cambios de esquema se entregan como **scripts explícitos** (p. ej. `.sql` versionados bajo convención del repo) para que **quien opera el motor** los ejecute **manualmente y aparte** en cada entorno (Postgres, MySQL, etc.). **Excepción**: si `AGENTS.md` define **explicitamente** como regla de **ese** repositorio otro mecanismo (p. ej. migraciones TypeORM u otro pipeline acordado), marca esta viñeta como **N/A** y revisa solo que el cambio cumple lo documentado allí (sin exigir scripts manuales).
+- Si aplica la politica por defecto (scripts manuales): los scripts de esquema entregados documentan orden de ejecución, son reversibles o describen rollback, y no destruyen datos existentes sin plan explícito. Si aplica la excepción por `AGENTS.md`, marca **N/A** o evalua segun lo que ese archivo exija para migraciones.
 
 ## B7. Caching
 - Consultas repetitivas a BD usan cache **distribuido** (no cache local en memoria del proceso — evitar reinicios por falta de RAM)

package/skills/up-code/SKILL.md

@@ -30,7 +30,7 @@ Ejecuta `git branch --show-current` para obtener el nombre de la rama.
 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`.
+1. Para cada carpeta activa, verifica si existe el archivo `.review-passed` (marcador oculto: **`METHODOLOGY-CONTRACT.md` §8** — no concluyas por `ls` sin `-a`).
 2. Si **todas** tienen `.review-passed` → continua al paso 3.
 3. Si hay **una sola** carpeta sin `.review-passed`:
    - Informa al usuario cual es.

package/skills/verify/SKILL.md

@@ -21,6 +21,10 @@ Determina el scope antes de invocar al sub-agente. Prioriza este orden:
 
 No invoques al sub-agente con scope ambiguo.
 
+### Paso 0.5: Archivos ocultos bajo `openspec/changes/` (evitar falsos negativos)
+
+Si **esta sesion** inspecciona el directorio del cambio (listar archivos, confirmar precondiciones) **antes o despues** de delegar, aplica **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §8**. El sub-agente `refacil-validator` sigue la misma regla.
+
 ### Paso 1: Delegar al sub-agente refacil-validator
 
 Invoca a `refacil-validator` pasandole:
@@ -86,6 +90,7 @@ Lista los issues para que el usuario los corrija manualmente. Sugiere `/refacil:
 ## Reglas
 
 - **Siempre delega al sub-agente** para el analisis (pasos 1-3). No repliques aqui la logica de lectura de specs ni de ejecucion de tests.
+- **Dotfiles en `openspec/changes/`**: nunca afirmes ausencia de `.review-passed` (u otros `.…`) basandote solo en `ls` sin `-a`; ver `METHODOLOGY-CONTRACT.md` §8 y Paso 0.5.
 - **Las correcciones SOLO las aplica este wrapper** (Paso 4), despues de aprobacion explicita del usuario. El sub-agente es read-only.
 - **No muestres el bloque JSON al usuario**. Es solo metadata para parsear el resultado.
 - **Las correcciones deben ser quirurgicas**: solo lo necesario para resolver los issues reportados.