refacil-sdd-ai 4.0.10 → 4.1.0

package/README.md

@@ -64,6 +64,7 @@ npm uninstall -g refacil-sdd-ai
 |---|---|
 | `refacil-sdd-ai init` | Instala skills y hooks en el repo actual |
 | `refacil-sdd-ai update` | Re-copia skills y hooks a la ultima version |
+| `refacil-sdd-ai migration-pending [--json]` | Misma deteccion que hooks/`notify-update`; exit 1 si hay migracion de metodologia pendiente (uso en `/refacil:update`) |
 | `refacil-sdd-ai clean` | Elimina skills y hooks SDD-AI del repo |
 | `refacil-sdd-ai help` | Ver ayuda |
 
@@ -72,7 +73,7 @@ npm uninstall -g refacil-sdd-ai
 | Comando | Descripcion |
 |---|---|
 | `refacil-sdd-ai check-update` | (`SessionStart`) Verifica nueva version, sincroniza skills y `compact-guidance` en AGENTS.md |
-| `refacil-sdd-ai notify-update` | (`UserPromptSubmit` / `beforeSubmitPrompt`) Pregunta al usuario si desea ejecutar `/refacil:update` cuando hay migraciones pendientes |
+| `refacil-sdd-ai notify-update` | (`UserPromptSubmit` / `beforeSubmitPrompt`) Solo actua si hay migracion de metodologia pendiente (misma logica que `/refacil:update`); si no, no interrumpe |
 | `refacil-sdd-ai check-review` | (`PreToolUse`) Bloquea `git push` si falta `.review-passed` en algun cambio activo |
 | `refacil-sdd-ai compact-bash` | (`PreToolUse`) Reescribe comandos Bash bare via `updatedInput` |
 
@@ -233,8 +234,8 @@ Se instalan en `.claude/settings.json` **y** `.cursor/settings.json` durante `in
 
 | Hook | Evento | Que hace |
 |---|---|---|
-| `check-update` | `SessionStart` | Chequea nueva version en npm, la instala, sincroniza skills y **sincroniza el bloque `compact-guidance`** en `AGENTS.md`. Si hubo actualizacion, escribe un flag de notificacion para el siguiente hook. |
-| `notify-update` | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | Antes de procesar el siguiente mensaje del usuario, lee el flag de actualizacion pendiente. Si existe, inyecta la instruccion para que el agente pregunte al usuario si desea ejecutar `/refacil:update`. El flag se borra tras notificar. |
+| `check-update` | `SessionStart` | Al inicio borra `.refacil-pending-update` si ya no hay migracion (flags obsoletos). Luego: npm, sync skills, **compact-guidance**. Si hubo sync de skills y **si** hay migracion pendiente, escribe el flag para `notify-update`. |
+| `notify-update` | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | Si existe flag y **hay migracion de metodologia pendiente** (misma tabla que `/refacil:update`), inyecta la instruccion o pausa el primer mensaje; si solo hubo sync de skills sin migracion, el flag no se crea o se descarta sin preguntar. |
 | `compact-bash` | `PreToolUse` (Bash) | Reescribe silenciosamente comandos Bash bare via `updatedInput`. Sin turnos extra, sin que el IDE vea el cambio. Requiere Claude Code >= 2.1.89. |
 | `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y bloquea si falta `.review-passed` en algun cambio activo. |
 

package/bin/cli.js

@@ -25,6 +25,7 @@ const { installHooks, uninstallHooks, cleanLegacySettingsHooks } = require('../l
 const { handleCompact } = require('../lib/commands/compact');
 const { handleBus } = require('../lib/commands/bus');
 const { syncIgnoreFiles } = require('../lib/ignore-files');
+const { methodologyMigrationPending } = require('../lib/methodology-migration-pending');
 
 const packageRoot = path.resolve(__dirname, '..');
 const projectRoot = process.cwd();
@@ -45,6 +46,15 @@ function writePendingUpdateFlag(root, fromVersion, toVersion) {
   } catch (_) {}
 }
 
+/** Borra `.refacil-pending-update` si ya no hay migracion (flags viejos o sync de skills sin migracion). */
+function clearStalePendingUpdateFlag(root) {
+  const flagPath = path.join(root, '.refacil-pending-update');
+  if (!fs.existsSync(flagPath)) return;
+  if (!methodologyMigrationPending(root).pending) {
+    try { fs.unlinkSync(flagPath); } catch (_) {}
+  }
+}
+
 function readStdinPrompt() {
   try {
     const raw = fs.readFileSync(0, 'utf8');
@@ -62,6 +72,12 @@ function notifyUpdate() {
   let info = {};
   try { info = JSON.parse(fs.readFileSync(flagPath, 'utf8')); } catch (_) {}
 
+  const mig = methodologyMigrationPending(projectRoot);
+  if (!mig.pending) {
+    try { fs.unlinkSync(flagPath); } catch (_) {}
+    return;
+  }
+
   const fromLabel = info.from ? `v${info.from}` : 'version anterior';
 
   // Si el usuario ya está ejecutando /refacil:update, dejar pasar y borrar el flag
@@ -145,7 +161,24 @@ function syncRepoSkillsIfStale(globalVersion) {
   }
 }
 
+function migrationPendingCmd() {
+  const wantJson = process.argv.includes('--json');
+  const { pending, reasons } = methodologyMigrationPending(projectRoot);
+  if (wantJson) {
+    process.stdout.write(`${JSON.stringify({ pending, reasons })}\n`);
+  } else if (pending) {
+    console.log('  Migraciones de metodologia pendientes:');
+    for (const r of reasons) console.log(`    - ${r}`);
+  } else {
+    console.log('  Sin migraciones de metodologia pendientes (criterio alineado con hooks y /refacil:update).');
+  }
+  clearStalePendingUpdateFlag(projectRoot);
+  process.exit(pending ? 1 : 0);
+}
+
 function checkUpdate() {
+  clearStalePendingUpdateFlag(projectRoot);
+
   const { execSync } = require('child_process');
   let localVersion = getPackageVersion(packageRoot);
 
@@ -188,7 +221,9 @@ function checkUpdate() {
       `[refacil-sdd-ai] Skills de este repo sincronizadas (${fromLabel} -> v${syncResult.to}). ` +
       'Reinicia la sesion de Claude Code o Cursor para detectar los cambios.',
     );
-    writePendingUpdateFlag(projectRoot, syncResult.from, syncResult.to);
+    if (methodologyMigrationPending(projectRoot).pending) {
+      writePendingUpdateFlag(projectRoot, syncResult.from, syncResult.to);
+    }
   } else if (syncResult && syncResult.failed) {
     console.log(
       `[refacil-sdd-ai] Skills de este repo estan desactualizadas respecto al paquete global (v${syncResult.to}) ` +
@@ -401,8 +436,9 @@ function help() {
   Comandos:
     init          Instala skills en .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
     update        Re-copia skills (para actualizar a nueva version del paquete)
+    migration-pending  Misma validacion que hooks/notify-update: lista migraciones (exit 1 si hay; --json)
     check-update   Sincroniza skills y compact-guidance al inicio de sesion (hook SessionStart)
-    notify-update  Notifica al LLM sobre migraciones pendientes (hook UserPromptSubmit)
+    notify-update  Notifica migracion de metodologia solo si aplica (hook UserPromptSubmit)
     check-review   Verifica que el review se haya completado (usado por hook PreToolUse)
     compact-bash  Reescribe comandos Bash bare para reducir tokens (usado por hook PreToolUse)
     compact       Subcomandos del hook compact-bash:
@@ -452,6 +488,9 @@ switch (command) {
   case 'update':
     update();
     break;
+  case 'migration-pending':
+    migrationPendingCmd();
+    break;
   case 'check-update':
     checkUpdate();
     break;

package/lib/methodology-migration-pending.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Motor compartido con `refacil-sdd-ai migration-pending`, hooks `check-update` / `notify-update`
+ * y la skill `refacil:update`. Si ninguna condicion aplica, no hace falta migrar metodologia.
+ */
+const REQUIRED_OPENSPEC_SKILLS = new Set([
+  'openspec-propose',
+  'openspec-explore',
+  'openspec-apply-change',
+  'openspec-archive-change',
+  'openspec-verify-change',
+]);
+
+const REQUIRED_OPSX_CLAUDE = new Set([
+  'apply.md',
+  'archive.md',
+  'explore.md',
+  'propose.md',
+  'verify.md',
+]);
+
+const REQUIRED_OPSX_CURSOR = new Set([
+  'opsx-apply.md',
+  'opsx-archive.md',
+  'opsx-explore.md',
+  'opsx-propose.md',
+  'opsx-verify.md',
+]);
+
+function legacyIndexDoc(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split(/\r?\n/).length;
+  const pointsToAgents = /AGENTS\.md/i.test(content);
+  return lines > 5 || !pointsToAgents;
+}
+
+function collectExtraOpenspecSkills(root) {
+  const out = [];
+  for (const rel of ['.claude/skills', '.cursor/skills']) {
+    const full = path.join(root, rel);
+    if (!fs.existsSync(full)) continue;
+    let names;
+    try {
+      names = fs.readdirSync(full, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const d of names) {
+      if (!d.isDirectory()) continue;
+      const name = d.name;
+      if (!name.startsWith('openspec-')) continue;
+      if (REQUIRED_OPENSPEC_SKILLS.has(name)) continue;
+      out.push(path.join(rel, name));
+    }
+  }
+  return out;
+}
+
+function collectExtraOpsxClaude(root) {
+  const dir = path.join(root, '.claude', 'commands', 'opsx');
+  if (!fs.existsSync(dir)) return [];
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const extra = [];
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    if (REQUIRED_OPSX_CLAUDE.has(name)) continue;
+    extra.push(path.join('.claude/commands/opsx', name));
+  }
+  return extra;
+}
+
+function collectExtraOpsxCursor(root) {
+  const dir = path.join(root, '.cursor', 'commands');
+  if (!fs.existsSync(dir)) return [];
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const extra = [];
+  for (const name of names) {
+    if (!name.startsWith('opsx-') || !name.endsWith('.md')) continue;
+    if (REQUIRED_OPSX_CURSOR.has(name)) continue;
+    extra.push(path.join('.cursor/commands', name));
+  }
+  return extra;
+}
+
+/**
+ * @param {string} root - raíz del repo
+ * @returns {{ pending: boolean, reasons: string[] }}
+ */
+function methodologyMigrationPending(root) {
+  const reasons = [];
+
+  const agentsMd = path.join(root, 'AGENTS.md');
+  const agentsDir = path.join(root, '.agents');
+  if (fs.existsSync(agentsMd) && !fs.existsSync(agentsDir)) {
+    reasons.push('AGENTS.md existe sin carpeta .agents/');
+  }
+
+  const claudeMd = path.join(root, 'CLAUDE.md');
+  if (legacyIndexDoc(claudeMd)) {
+    reasons.push('CLAUDE.md requiere normalización (índice mínimo → AGENTS.md)');
+  }
+
+  const cursorRules = path.join(root, '.cursorrules');
+  if (legacyIndexDoc(cursorRules)) {
+    reasons.push('.cursorrules requiere normalización (índice mínimo → AGENTS.md)');
+  }
+
+  const extraSkills = collectExtraOpenspecSkills(root);
+  if (extraSkills.length) {
+    reasons.push(`skills OpenSpec sobrantes: ${extraSkills.join(', ')}`);
+  }
+
+  const extraOpsx = [...collectExtraOpsxClaude(root), ...collectExtraOpsxCursor(root)];
+  if (extraOpsx.length) {
+    reasons.push(`commands opsx sobrantes: ${extraOpsx.join(', ')}`);
+  }
+
+  return { pending: reasons.length > 0, reasons };
+}
+
+module.exports = { methodologyMigrationPending };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.0.10",
+  "version": "4.1.0",
   "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"
@@ -37,7 +37,7 @@
     "node": ">=20.19.0"
   },
   "scripts": {
-    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js"
+    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js"
   },
   "dependencies": {
     "ws": "^8.18.0"

package/skills/update/SKILL.md

@@ -8,26 +8,41 @@ user-invocable: true
 
 Detecta el estado actual del repo y aplica solo lo que este pendiente. No repite pasos de instalacion (OpenSpec, hooks, skills).
 
-## Paso 1: Detectar migraciones pendientes
+El hook `notify-update` usa el **mismo motor** que este comando; no re-evalues a mano el repo para decidir si hay trabajo.
 
-Evalua cada condicion y marca si aplica:
+## Paso 1: Validar con el CLI (obligatorio)
 
-| # | Condicion detectada | Migracion |
+En la **raiz del repo** (donde esta `AGENTS.md` o `.claude/`), ejecuta con `Bash`:
+
+```bash
+refacil-sdd-ai migration-pending
+```
+
+- **Codigo de salida 0**: no hay migraciones de metodologia pendientes → informa al usuario que todo esta al dia respecto a este criterio y **termina** (sin tocar archivos).
+- **Codigo de salida 1**: hay al menos una razon listada en stdout → continua al Paso 2.
+
+Opcional para parseo estable: `refacil-sdd-ai migration-pending --json` → objeto `{ "pending": bool, "reasons": string[] }`.
+
+No sustituyas este paso por inspeccion manual del arbol salvo que el comando falle (error de entorno); en ese caso documenta el error y pide reintentar.
+
+### Referencia (mapeo razon → accion en Paso 3)
+
+La implementacion vive en `lib/methodology-migration-pending.js` del paquete; la tabla resume lo que detecta:
+
+| # | Condicion (resumen) | Migracion en Paso 3 |
 |---|---|---|
 | 1 | `AGENTS.md` existe y no existe carpeta `.agents/` | Reestructurar en `.agents/` + reescribir como indice |
 | 2 | `CLAUDE.md` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
 | 3 | `.cursorrules` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
-| 4 | Existen skills `openspec-*` o commands `opsx-*` fuera del conjunto requerido en `.claude/` o `.cursor/` | Eliminar los sobrantes y reconfigurar OpenSpec |
-
-Si ninguna condicion aplica: informar al usuario que todo esta al dia y salir sin cambios.
+| 4 | Skills `openspec-*` o commands `opsx-*` fuera del conjunto requerido | Eliminar sobrantes y reconfigurar OpenSpec |
 
 ## Paso 2: Confirmar con el usuario
 
-Mostrar la lista de migraciones detectadas y pedir confirmacion antes de aplicar cualquier cambio.
+Mostrar al usuario las mismas lineas que imprimio `migration-pending` (o el array `reasons` del JSON) y pedir confirmacion antes de aplicar cualquier cambio.
 
 ## Paso 3: Aplicar migraciones confirmadas
 
-Ejecutar solo las migraciones marcadas en el Paso 1.
+Ejecutar solo las migraciones que correspondan a las razones detectadas (ver tabla de referencia arriba).
 
 ### Migracion 1 — AGENTS.md → `.agents/` + indice
 
@@ -96,19 +111,22 @@ Conjunto requerido de commands: `.claude/commands/opsx/` → `apply.md`, `archiv
 
 ## Paso 4: Limpiar flag de actualizacion pendiente
 
-Eliminar el archivo de flag si existe (puede estar en `.claude/` o `.cursor/`):
+Tras migrar, elimina el flag en la raiz del repo si sigue existiendo:
 
 ```bash
 rm -f .refacil-pending-update
 ```
 
+Si no hubo cambios (Paso 1 dio exit 0), el flag obsoleto suele borrarse solo al proximo `check-update` (SessionStart) o al ejecutar `refacil-sdd-ai migration-pending` con exit 0; el `rm` manual solo hace falta si aplicaste migraciones a mano o quedo un vestigio.
+
 ## Paso 5: Resumen
 
 Informar que archivos se crearon o modificaron. Mencionar que el bloque `compact-guidance` se sincronizara automaticamente en el proximo SessionStart.
 
 ## Reglas
 
+- **Deteccion**: confiar en `refacil-sdd-ai migration-pending` (mismo criterio que `check-update` / `notify-update`).
 - Solo aplica lo que este pendiente — no toca archivos que ya cumplen el patron.
 - No inventa contenido: distribuye lo que ya existe en AGENTS.md sin agregar ni eliminar informacion.
 - No ejecuta pasos de OpenSpec, hooks ni instalacion de skills.
-- Extensible: futuras versiones de la metodologia agregaran filas a la tabla del Paso 1 sin cambiar la estructura de la skill.
+- Extensible: nuevas reglas de deteccion se agregan en el paquete (`methodology-migration-pending.js`); esta skill actualiza la tabla de referencia y los pasos de aplicacion cuando cambie el contrato.