mcp-phase-gate 2.1.0 → 2.2.0

package/build/servidor.js

@@ -0,0 +1,372 @@
+// El servidor MCP: registra las tools y las conecta con la lógica de los demás módulos.
+// Aquí no se calcula nada — las rutas viven en paths.ts, las fases en phases.ts y las tareas en
+// tasks.ts. Este archivo solo traduce entre el protocolo y esas funciones.
+//
+// crearServidor no conecta ningún transporte: lo hace index.ts con stdio, y los tests con un
+// transporte en memoria. Así el servidor entero se puede probar sin lanzar un proceso.
+//
+// Cada tool se registra con su shape de schemas.ts: el SDK valida los argumentos antes del
+// callback y convierte en `isError` tanto un fallo de validación como un Error lanzado aquí. Por
+// eso los callbacks lanzan Error con el mensaje para el modelo, y no arman respuestas de error.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as fs from "fs";
+import * as path from "path";
+import { DOCS, SERVER_NAME, SERVER_VERSION, requireBasePath, stateFile } from "./config.js";
+import { diagnosticar, formatearDiagnostico } from "./diagnostico.js";
+import { pedirConfirmacion } from "./confirmacion.js";
+import { conectarLog, log } from "./log.js";
+import { describeProjects, discoverProjects, estaDentroReal, findProjectFolder, leerTextoAcotado, requireProjectFolder, resolveDocPath, resolveRepoPath, taskFolderPath, ubicarEnTarea, validarNombreVisible, validarSegmento, } from "./paths.js";
+import { discoverPhases, loadPhasePrompt, nombreContextoInicial } from "./phases.js";
+import { asegurarCapacidadDePrompts, sincronizarPrompts, vigilarCapas } from "./prompts-mcp.js";
+import { registrarRecursos } from "./recursos.js";
+import { diagnosticoShape, getActiveTaskShape, getOrchestratorStatusShape, getPhasePromptShape, listTasksShape, readCentralDocShape, readCrossRepoShape, sinNulos, startTaskShape, switchTaskShape, writeCentralDocShape, } from "./schemas.js";
+import { avisoDeCompuerta, avisoDePendientes, bloqueDeRecibos, describeEstado, guardarPuntero, listarTareas, motivoDeProteccion, tareaActiva, tareaDelPrompt, } from "./tasks.js";
+function responder(texto) {
+    return { content: [{ type: "text", text: texto }] };
+}
+function siCancelada(extra) {
+    if (extra.signal.aborted)
+        throw new Error("El cliente canceló la llamada antes de escribir. No se escribió nada.");
+}
+function lineaDeTarea(estado, phases) {
+    return `- ${estado.taskName} — ${describeEstado(estado, phases)}`;
+}
+// Las anotaciones dicen al cliente qué hace cada tool, para que decida si pide permiso. Los
+// valores por defecto del protocolo son pesimistas (destructiva y de mundo abierto), así que todas
+// declaran los cuatro valores. openWorldHint es false en todas: ninguna sale de las carpetas
+// configuradas.
+function anotaciones(title, readOnlyHint, destructiveHint, idempotentHint) {
+    return { title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint: false };
+}
+export function crearServidor() {
+    const mcp = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { logging: {} } });
+    conectarLog(mcp);
+    registrarTools(mcp);
+    registrarRecursos(mcp);
+    // Los /fN se registran ya, antes de conectar, y se vuelven a sincronizar tras cada tool y
+    // cuando cambia una capa de prompts.
+    sincronizarPrompts(mcp);
+    asegurarCapacidadDePrompts(mcp);
+    const dejarDeVigilar = vigilarCapas(mcp);
+    const alCerrar = mcp.server.onclose;
+    mcp.server.onclose = () => {
+        dejarDeVigilar();
+        alCerrar?.();
+    };
+    return mcp;
+}
+function registrarTools(mcp) {
+    // Tras cada llamada a una tool se sincronizan los prompts /fN. Leer las carpetas de prompts
+    // cuesta milisegundos, y es lo único que garantiza que una fase nueva aparezca en OneDrive,
+    // donde fs.watch no avisa.
+    const sincronizandoTras = (callback) => async (...args) => {
+        try {
+            return await callback(...args);
+        }
+        finally {
+            sincronizarPrompts(mcp);
+        }
+    };
+    // start_task no es destructiva (se niega a pisar una tarea) ni idempotente (la segunda llamada falla).
+    mcp.registerTool("start_task", {
+        title: "Iniciar tarea",
+        description: "Inicia una tarea NUEVA creando su carpeta en la Documentación Central y guardando el contexto inicial. " +
+            "Para volver a una tarea que ya existe usa 'switch_task': start_task reescribiría su contexto inicial.",
+        inputSchema: startTaskShape,
+        annotations: anotaciones("Iniciar tarea", false, false, false),
+    }, sincronizandoTras(async (entrada, extra) => {
+        const args = sinNulos(entrada);
+        const proj = args.project; // el schema ya le quitó los espacios
+        const taskName = args.task_name;
+        // Estrenar proyecto tiene que ser deliberado: sin esta puerta, un nombre mal escrito
+        // creaba una carpeta suelta en la Documentación y nadie se enteraba hasta buscarla.
+        let carpetaProyecto = findProjectFolder(proj);
+        let estrenado = false;
+        if (!carpetaProyecto) {
+            if (args.crear_proyecto !== true) {
+                throw new Error(`No existe el proyecto "${proj}". Los proyectos disponibles son: ${describeProjects()}. ` +
+                    `Si el usuario te confirmó que quiere estrenar el proyecto "${proj.toUpperCase()}", ` +
+                    `vuelve a llamar a start_task con crear_proyecto: true.`);
+            }
+            // El nombre se vuelve carpeta tal cual: "../evil" la creaba fuera de la Documentación.
+            validarSegmento(proj, "project");
+            validarNombreVisible(proj, "project");
+            carpetaProyecto = proj.toUpperCase();
+            estrenado = true;
+        }
+        validarNombreVisible(taskName, "task_name");
+        const carpetaTarea = taskFolderPath(carpetaProyecto, taskName);
+        const contextoInicial = path.join(carpetaTarea, nombreContextoInicial());
+        const docsBase = requireBasePath(DOCS);
+        if (!estaDentroReal(docsBase, carpetaTarea)) {
+            throw new Error(`Acceso denegado: la carpeta de la tarea queda fuera de ${docsBase}.`);
+        }
+        // Estrenar un proyecto se le confirma a la persona si el cliente puede preguntarle. Sin
+        // crear_proyecto no se pregunta nada: ofrecer "¿lo creo?" ante un nombre desconocido
+        // invitaría a aceptar un typo con un clic.
+        if (estrenado) {
+            const { estado, nota } = await pedirConfirmacion(mcp, extra, {
+                mensaje: `¿Estrenar el proyecto «${carpetaProyecto}»? Se creará la carpeta \`${path.join(docsBase, carpetaProyecto)}\`.`,
+                etiqueta: `Crear el proyecto ${carpetaProyecto}`,
+            });
+            if (estado === "rechazada") {
+                throw new Error(`El usuario no confirmó el proyecto nuevo. No se creó nada.${nota ? ` ${nota}` : ""}`);
+            }
+        }
+        // start_task escribe el contexto inicial sin preguntar, así que llamarlo sobre una tarea
+        // que ya existe borraba el requerimiento original — el único documento que no se puede
+        // regenerar leyendo el código. Retomar una tarea es switch_task, que no toca archivos.
+        if (fs.existsSync(contextoInicial)) {
+            throw new Error(`La tarea "${taskName}" ya existe en ${carpetaProyecto} y start_task reescribiría su ` +
+                `contexto inicial. Si quieres retomarla, usa switch_task. Si de verdad quieres ` +
+                `empezar de cero, borra o renombra la carpeta primero: ${carpetaTarea}`);
+        }
+        siCancelada(extra);
+        if (!fs.existsSync(carpetaTarea)) {
+            fs.mkdirSync(carpetaTarea, { recursive: true });
+        }
+        fs.writeFileSync(contextoInicial, args.initial_context, "utf-8");
+        // Queda como activa de SU proyecto. Otra ventana trabajando en otro proyecto conserva
+        // la suya: los punteros son independientes.
+        guardarPuntero(carpetaProyecto, taskName);
+        // Cambia la tarea activa, y con ella qué documentos se listan como recursos.
+        mcp.sendResourceListChanged();
+        const aviso = estrenado ? `\nProyecto "${carpetaProyecto}" estrenado.` : "";
+        return responder(`Tarea '${taskName}' inicializada correctamente. Archivo guardado en: ${contextoInicial}\n` +
+            `Tarea activa de ${carpetaProyecto}: ${taskName}.${aviso}`);
+    }));
+    mcp.registerTool("get_phase_prompt", {
+        title: "Prompt de fase",
+        description: "Obtiene el prompt maestro de comportamiento de una fase. Comprueba además que no te estés saltando una " +
+            "fase: si faltan documentos anteriores, el prompt llega con un aviso al principio.",
+        inputSchema: getPhasePromptShape,
+        annotations: anotaciones("Prompt de fase", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        // Que sea un entero ya lo garantiza el schema; si la fase no existe, lo dice loadPhasePrompt.
+        const { phase, project, task_name } = sinNulos(entrada);
+        const prompt = loadPhasePrompt(phase);
+        // La compuerta avisa, no bloquea: el prompt se entrega siempre. Si comprobarla fallara
+        // por lo que sea, entregarlo igual es mejor que dejar al usuario sin fase por un aviso.
+        // Lo mismo con la lista de recibos: es una ayuda, no una condición.
+        let aviso = null;
+        let pendientes = null;
+        let recibos = null;
+        try {
+            const phases = discoverPhases();
+            const opciones = { ...(project ? { project } : {}), ...(task_name ? { taskName: task_name } : {}) };
+            aviso = avisoDeCompuerta(phase, phases, opciones);
+            const estado = tareaDelPrompt(phases, opciones);
+            if (estado && estado !== "ambigua") {
+                pendientes = avisoDePendientes(phase, estado, phases);
+                recibos = bloqueDeRecibos(phase, estado, phases);
+            }
+        }
+        catch (error) {
+            log("warning", `No se pudo comprobar la compuerta: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Lo que el modelo tiene que leer antes de nada va delante: el salto de fase y los pendientes.
+        return responder([aviso, pendientes, prompt, recibos].filter(Boolean).join("\n\n"));
+    }));
+    mcp.registerTool("get_active_task", {
+        title: "Tarea activa",
+        description: "Devuelve la tarea activa y en qué fase va, deducida de los documentos que ya tiene. Úsalo al iniciar un " +
+            "chat nuevo o si perdiste el contexto. Sin 'project' devuelve la activa de CADA proyecto.",
+        inputSchema: getActiveTaskShape,
+        annotations: anotaciones("Tarea activa", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const phases = discoverPhases();
+        const pedido = sinNulos(entrada).project ?? "";
+        // Con proyecto: la suya. Sin proyecto: la de cada uno. Antes había un único puntero
+        // global y responder "la activa" a secas obligaba a adivinar cuál de dos ventanas
+        // preguntaba; listar todas es la respuesta honesta cuando no se sabe.
+        const proyectos = pedido ? [requireProjectFolder(pedido)] : [...discoverProjects().values()].sort();
+        if (proyectos.length === 0) {
+            return responder("No hay ningún proyecto en la Documentación Central todavía.");
+        }
+        const bloques = [];
+        for (const carpetaProyecto of proyectos) {
+            const activa = tareaActiva(carpetaProyecto, phases);
+            if (!activa) {
+                bloques.push(`${carpetaProyecto}: sin tareas todavía.`);
+                continue;
+            }
+            const nota = activa.origen === "deducida"
+                ? " (deducida por ser la más reciente: no había puntero guardado, confírmalo antes de escribir)"
+                : "";
+            bloques.push(`${carpetaProyecto}: ${activa.estado.taskName}${nota}\n` +
+                `  Fase: ${describeEstado(activa.estado, phases)}\n` +
+                `  Carpeta: ${activa.estado.folderPath}`);
+        }
+        return responder(`${bloques.join("\n\n")}\n\nPunteros guardados en: ${stateFile()}`);
+    }));
+    mcp.registerTool("list_tasks", {
+        title: "Listar tareas",
+        description: "Lista las tareas que existen y la fase en la que va cada una. Úsalo para retomar una tarea vieja o para " +
+            "saber qué hay pendiente.",
+        inputSchema: listTasksShape,
+        annotations: anotaciones("Listar tareas", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const phases = discoverPhases();
+        const pedido = sinNulos(entrada).project ?? "";
+        const proyectos = pedido ? [requireProjectFolder(pedido)] : [...discoverProjects().values()].sort();
+        const bloques = [];
+        for (const carpetaProyecto of proyectos) {
+            const tareas = listarTareas(carpetaProyecto, phases);
+            const activa = tareaActiva(carpetaProyecto, phases);
+            if (tareas.length === 0) {
+                bloques.push(`${carpetaProyecto}: sin tareas.`);
+                continue;
+            }
+            const lineas = tareas.map((tarea) => {
+                const marca = tarea.taskName === activa?.estado.taskName ? " [activa]" : "";
+                return `${lineaDeTarea(tarea, phases)}${marca}`;
+            });
+            bloques.push(`${carpetaProyecto} (${tareas.length}), de la más reciente a la más antigua:\n${lineas.join("\n")}`);
+        }
+        return responder(bloques.join("\n\n") || "No hay proyectos todavía.");
+    }));
+    // Escribe el puntero, así que no es de solo lectura; pero repetirla da el mismo estado.
+    mcp.registerTool("switch_task", {
+        title: "Cambiar de tarea activa",
+        description: "Cambia cuál es la tarea activa de un proyecto, sin tocar ningún archivo. Es la forma correcta de " +
+            "retomar una tarea que ya existe.",
+        inputSchema: switchTaskShape,
+        annotations: anotaciones("Cambiar de tarea activa", false, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const args = sinNulos(entrada);
+        const phases = discoverPhases();
+        const carpetaProyecto = requireProjectFolder(args.project);
+        const taskName = args.task_name;
+        const tareas = listarTareas(carpetaProyecto, phases);
+        const encontrada = tareas.find((tarea) => tarea.taskName === taskName);
+        if (!encontrada) {
+            const disponibles = tareas.length ? tareas.map((tarea) => `"${tarea.taskName}"`).join(", ") : "(ninguna)";
+            throw new Error(`No existe la tarea "${taskName}" en ${carpetaProyecto}. Las que hay son: ${disponibles}. ` +
+                `Si es una tarea nueva, créala con start_task.`);
+        }
+        guardarPuntero(carpetaProyecto, taskName);
+        mcp.sendResourceListChanged();
+        return responder(`Tarea activa de ${carpetaProyecto}: ${taskName}.\nFase: ${describeEstado(encontrada, phases)}\n` +
+            `Carpeta: ${encontrada.folderPath}`);
+    }));
+    mcp.registerTool("read_central_doc", {
+        title: "Leer documento",
+        description: "Lee un archivo de la Documentación Central. RECOMENDADO: pasa 'project' + 'task_name' + 'file_name' y el " +
+            "servidor arma la ruta correcta automáticamente (<PROYECTO>/<subcarpeta de tareas>/<tarea>/<archivo>). " +
+            "Alternativamente puedes pasar 'file_path' relativo a la Documentación Central.",
+        inputSchema: readCentralDocShape,
+        annotations: anotaciones("Leer documento", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const docsBase = requireBasePath(DOCS);
+        const fullPath = resolveDocPath(sinNulos(entrada));
+        if (!estaDentroReal(docsBase, fullPath)) {
+            throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
+        }
+        return responder(leerTextoAcotado(fullPath));
+    }));
+    // La única destructiva: puede sobrescribir un documento. Repetirla con el mismo contenido deja
+    // el mismo archivo, así que es idempotente.
+    mcp.registerTool("write_central_doc", {
+        title: "Escribir documento",
+        description: "Escribe o sobrescribe un archivo en la Documentación Central. RECOMENDADO: pasa 'project' + 'task_name' + " +
+            "'file_name' y el servidor arma la ruta correcta automáticamente " +
+            "(<PROYECTO>/<subcarpeta de tareas>/<tarea>/<archivo>). Alternativamente puedes pasar 'file_path' relativo " +
+            "a la Documentación Central.",
+        inputSchema: writeCentralDocShape,
+        annotations: anotaciones("Escribir documento", false, true, true),
+    }, sincronizandoTras(async (entrada, extra) => {
+        const args = sinNulos(entrada);
+        const docsBase = requireBasePath(DOCS);
+        const fullPath = resolveDocPath(args);
+        if (!estaDentroReal(docsBase, fullPath)) {
+            throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
+        }
+        // Antes del mkdir: con una tarea mal escrita, el mkdir recursivo creaba su carpeta.
+        const ubicacion = ubicarEnTarea(fullPath);
+        if (!ubicacion) {
+            throw new Error("write_central_doc solo escribe dentro de la carpeta de una tarea que ya existe " +
+                "(<DOCS>/<PROYECTO>/<subcarpeta de tareas>/<tarea>/). Los archivos del proyecto, como " +
+                "phase-gate.json, no se escriben con esta tool. Para una tarea nueva, usa start_task.");
+        }
+        const motivo = motivoDeProteccion(ubicacion.carpetaTarea, ubicacion.relativo, discoverPhases(), nombreContextoInicial());
+        const existia = fs.existsSync(fullPath);
+        // Un documento protegido se le pregunta a la persona si el cliente puede mostrarle la
+        // pregunta; entonces force no basta, porque lo pone el modelo. Solo sin elicitation decide
+        // force, como antes.
+        let sufijo = "";
+        if (motivo) {
+            const archivo = ubicacion.relativo;
+            const { estado, nota } = await pedirConfirmacion(mcp, extra, {
+                mensaje: `\`${archivo}\` de la tarea «${ubicacion.taskName}» está protegido: ${motivo.replace(/\.$/, "")}. ` +
+                    (existia ? "¿Reescribirlo?" : "¿Crearlo?"),
+                etiqueta: `${existia ? "Reescribir" : "Crear"} ${archivo}`,
+            });
+            const conNota = nota ? ` ${nota}` : "";
+            if (estado === "rechazada") {
+                const accion = existia ? "la reescritura" : "la escritura";
+                throw new Error(`El usuario no confirmó ${accion} de \`${archivo}\`. No se escribió nada.${conNota}`);
+            }
+            if (estado === "no-disponible" && args.force !== true) {
+                throw new Error(`${motivo} Si de verdad hay que reescribirlo, pídele al usuario confirmación explícita ` +
+                    `y vuelve a llamar con force: true.${conNota}`);
+            }
+            // force también crea el contexto inicial cuando falta: no se dice "sobrescrito" si no lo era.
+            sufijo =
+                estado === "confirmada"
+                    ? existia
+                        ? " (reescrito con confirmación del usuario)"
+                        : " (creado con confirmación del usuario)"
+                    : existia
+                        ? " (sobrescrito con force)"
+                        : " (creado con force)";
+            if (nota)
+                sufijo += `\n${nota}`;
+        }
+        // Si el cliente canceló la llamada mientras se esperaba algo (una confirmación), ya no
+        // escucha la respuesta: escribir ahora dejaría un archivo que el modelo cree que no existe.
+        siCancelada(extra);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, args.content, "utf-8");
+        // Un archivo nuevo puede ser un documento o un recibo que se lista como recurso. Reescribir
+        // uno que ya existía no cambia la lista.
+        if (!existia)
+            mcp.sendResourceListChanged();
+        return responder(`Archivo escrito exitosamente en ${fullPath}${sufijo}`);
+    }));
+    // La misma radiografía que `npx mcp-phase-gate doctor`, más lo que solo se sabe desde dentro de
+    // una sesión: qué cliente está conectado y qué capacidades anunció.
+    mcp.registerTool("get_orchestrator_status", {
+        title: "Estado de la instalación",
+        description: "Radiografía de la instalación: versión y ruta del paquete, variables y de dónde salió cada una, qué " +
+            "archivo de prompt gana en cada fase, proyectos y tarea activa, y avisos. Úsala cuando algo no se " +
+            "comporte como esperas.",
+        inputSchema: getOrchestratorStatusShape,
+        outputSchema: diagnosticoShape,
+        annotations: anotaciones("Estado de la instalación", true, false, true),
+    }, sincronizandoTras(async () => {
+        const version = mcp.server.getClientVersion();
+        const capacidades = mcp.server.getClientCapabilities();
+        const cliente = version
+            ? {
+                nombre: version.name,
+                version: version.version,
+                capacidades: { elicitation: Boolean(capacidades?.elicitation?.form), roots: Boolean(capacidades?.roots) },
+            }
+            : undefined;
+        const diagnostico = diagnosticar(cliente ? { cliente } : {});
+        return {
+            content: [{ type: "text", text: formatearDiagnostico(diagnostico, "markdown") }],
+            structuredContent: diagnostico,
+        };
+    }));
+    mcp.registerTool("read_cross_repo", {
+        title: "Leer archivo de repositorio",
+        description: "Lee archivos de otros repositorios locales, dentro de la carpeta configurada en PHASE_GATE_REPOS_PATH.",
+        inputSchema: readCrossRepoShape,
+        annotations: anotaciones("Leer archivo de repositorio", true, false, true),
+    }, sincronizandoTras(async (entrada) => {
+        const args = sinNulos(entrada);
+        return responder(leerTextoAcotado(resolveRepoPath(args.repo_name, args.file_path)));
+    }));
+}
+//# sourceMappingURL=servidor.js.map

package/build/tasks.d.ts

@@ -36,5 +36,7 @@ export type OpcionesDeTarea = {
 export declare function tareaDelPrompt(phases: Map<number, PhaseFile>, opciones?: OpcionesDeTarea): EstadoTarea | "ambigua" | null;
 export declare function avisoDeCompuerta(fasePedida: number, phases: Map<number, PhaseFile>, opciones?: OpcionesDeTarea): string | null;
 export declare function bloqueDeRecibos(fasePedida: number, estado: EstadoTarea, phases: Map<number, PhaseFile>): string | null;
+export declare function tieneValidacionesPendientes(texto: string): boolean;
+export declare function avisoDePendientes(fasePedida: number, estado: EstadoTarea, phases: Map<number, PhaseFile>): string | null;
 export declare function avisoDeSalto(salto: Salto, taskName: string, phases: Map<number, PhaseFile>): string;
 //# sourceMappingURL=tasks.d.ts.map

package/build/tasks.js

@@ -14,7 +14,9 @@
 import * as fs from "fs";
 import * as path from "path";
 import { MODULE_DIR, stateDir, stateFile } from "./config.js";
-import { claveDeNombre, findProjectFolder, requireProjectFolder, tasksRootPath } from "./paths.js";
+import { log } from "./log.js";
+import { claveDeNombre, findProjectFolder, leerTextoAcotado, requireProjectFolder, tasksRootPath } from "./paths.js";
+import { separarFrontmatter } from "./phases.js";
 export function leerPunteros() {
     const archivo = stateFile();
     if (!fs.existsSync(archivo))
@@ -67,7 +69,7 @@ export function limpiarEstadoViejo() {
         try {
             if (fs.existsSync(viejo)) {
                 fs.unlinkSync(viejo);
-                console.error(`[orquestador] Estado en formato anterior eliminado: ${viejo}`);
+                log("info", `Estado en formato anterior eliminado: ${viejo}`);
             }
         }
         catch {
@@ -304,6 +306,116 @@ export function bloqueDeRecibos(fasePedida, estado, phases) {
         ...lineas,
     ].join("\n");
 }
+// ─── Pendientes heredados ───────────────────────────────────────────────────
+// Refuerzo del servidor para la regla global PENDIENTES HEREDADOS (#39): si la fase anterior dejó
+// algo sin comprobar, el prompt de la siguiente llega con un aviso que lo nombra. Lee encabezados
+// y frontmatter de documentos que el prompt ya obliga a escribir; no guarda estado ni cambia la
+// deducción de fase. Si el modelo no escribió la sección, el aviso no sale y todo sigue igual.
+//
+// No contradice el rechazo de la #39 a un campo `Estado:`: aquello era hacer depender la
+// compuerta de algo escrito por el modelo. Esto no bloquea ni cambia la fase: solo señala.
+const ENCABEZADO_PENDIENTES = "## Validaciones pendientes";
+// Lo que se escribe por costumbre en una sección que no tiene nada: no es un pendiente.
+const SECCION_VACIA = new Set([
+    "",
+    "ninguna",
+    "ninguno",
+    "ninguna pendiente",
+    "nada",
+    "sin pendientes",
+    "no hay pendientes",
+    "fase cerrada sin pendientes",
+    "n/a",
+    "no aplica",
+]);
+// La sección reducida a su texto: sin viñetas ni numeración, sin énfasis de Markdown (_ * `),
+// sin puntos suspensivos ni punto final, en una línea y en minúsculas. Así "- Ninguna.",
+// "_Ninguna._" o "Ninguna..." cuentan igual que "Ninguna".
+function textoDeSeccion(seccion) {
+    return seccion
+        .split("\n")
+        .map((linea) => linea.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, ""))
+        .join(" ")
+        .replace(/[_*`]/g, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/(?:\.+|…)$/, "")
+        .trim()
+        .toLowerCase();
+}
+const ESTADOS_PENDIENTES = new Set(["con pendientes", "fallido", "descartado"]);
+// La sección es el texto entre su encabezado y el siguiente "## " (o el final). Devuelve true si
+// existe y tiene algo que no sea una forma de decir "ninguna".
+export function tieneValidacionesPendientes(texto) {
+    const lineas = separarFrontmatter(texto).cuerpo.split("\n");
+    // El encabezado se compara sin distinguir mayúsculas: "## Validaciones Pendientes" también vale.
+    const buscado = ENCABEZADO_PENDIENTES.toLowerCase();
+    const inicio = lineas.findIndex((linea) => linea.trimEnd().normalize("NFC").toLowerCase() === buscado);
+    if (inicio === -1)
+        return false;
+    const resto = lineas.slice(inicio + 1);
+    const fin = resto.findIndex((linea) => linea.startsWith("## "));
+    const seccion = (fin === -1 ? resto : resto.slice(0, fin)).join("\n");
+    return !SECCION_VACIA.has(textoDeSeccion(seccion));
+}
+function leerSinFallar(ruta) {
+    try {
+        return leerTextoAcotado(ruta);
+    }
+    catch {
+        return null; // un documento ilegible no es un pendiente: el aviso es una ayuda, no un control
+    }
+}
+export function avisoDePendientes(fasePedida, estado, phases) {
+    const ordenadas = [...phases.entries()].sort((a, b) => a[0] - b[0]);
+    const lineas = [];
+    // La fase anterior es la de mayor número, por debajo de la pedida, cuyo documento existe.
+    const anterior = ordenadas
+        .filter(([numero, datos]) => numero < fasePedida && datos.documento)
+        .reverse()
+        .find(([, datos]) => fs.existsSync(path.join(estado.folderPath, datos.documento)));
+    if (anterior) {
+        const documento = anterior[1].documento;
+        const texto = leerSinFallar(path.join(estado.folderPath, documento));
+        if (texto !== null && tieneValidacionesPendientes(texto)) {
+            lineas.push(`- \`${documento}\` tiene una sección \`${ENCABEZADO_PENDIENTES}\`.`);
+        }
+    }
+    // Los recibos de lote de las fases anteriores que quedaron con pendientes, fallidos o
+    // descartados. Con un solo lote, el recibo es el documento de la fase y se mira también.
+    for (const [numero, datos] of ordenadas) {
+        if (numero >= fasePedida || !datos.recibos)
+            continue;
+        const candidatos = [];
+        if (datos.documento)
+            candidatos.push(datos.documento);
+        const subcarpeta = path.join(estado.folderPath, datos.recibos);
+        if (fs.existsSync(subcarpeta)) {
+            for (const entrada of fs.readdirSync(subcarpeta, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (entrada.isFile() && entrada.name.toLowerCase().endsWith(".md"))
+                    candidatos.push(`${datos.recibos}/${entrada.name}`);
+            }
+        }
+        for (const relativo of candidatos) {
+            const ruta = path.join(estado.folderPath, ...relativo.split("/"));
+            if (!fs.existsSync(ruta))
+                continue;
+            const texto = leerSinFallar(ruta);
+            const valor = texto === null ? "" : (separarFrontmatter(texto).meta.estado ?? "").trim().toLowerCase();
+            if (ESTADOS_PENDIENTES.has(valor))
+                lineas.push(`- \`${relativo}\`: estado \`${valor}\`.`);
+        }
+    }
+    if (lineas.length === 0)
+        return null;
+    return [
+        "## PENDIENTES HEREDADOS (detectados por el servidor)",
+        "",
+        ...lineas,
+        "",
+        "Nómbraselos al usuario antes de empezar (ver PENDIENTES HEREDADOS en las reglas globales).",
+    ].join("\n");
+}
 export function avisoDeSalto(salto, taskName, phases) {
     const titulo = phases.get(salto.siguienteFase)?.title;
     const vaEn = titulo ? `Fase ${salto.siguienteFase} (${titulo})` : `Fase ${salto.siguienteFase}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-phase-gate",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada una deje su documento en una documentación central.",
   "main": "build/index.js",
   "bin": {
@@ -43,7 +43,6 @@
   "homepage": "https://github.com/Montse2308/mcp-phase-gate#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "dotenv": "^17.4.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/prompts/comandos/f1.md

@@ -0,0 +1,14 @@
+Vas a iniciar la FASE 1 (Descubrimiento) del flujo del mcp-phase-gate.
+
+Datos de la tarea (tómalos del texto que escribí después del comando; si falta alguno, pregúntame antes de seguir):
+- project: uno de los proyectos que ya existen. Si no lo reconoce, `start_task` te devuelve la lista; no inventes uno ni pases `crear_proyecto` salvo que yo te diga explícitamente que quiero estrenar un proyecto nuevo.
+- task_name: nombre corto de la tarea
+- initial_context: el correo / mensaje / requerimiento completo
+
+Pasos:
+1. Llama a la tool `start_task` del mcp-phase-gate con project, task_name e initial_context.
+2. Llama a `get_phase_prompt(1)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol de comportamiento.
+3. Analiza el código actual de este repositorio para entender el impacto del requerimiento.
+4. Guarda el análisis técnico y funcional con `write_central_doc`, usando el nombre de archivo exacto que te indicó `get_phase_prompt`.
+
+No escribas código de producción todavía.

package/prompts/comandos/f2.md

@@ -0,0 +1,12 @@
+Vas a iniciar la FASE 2 (Decisiones) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes cuál es la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(2)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee el documento de la Fase 1 con `read_central_doc`; `get_phase_prompt` te dio su nombre exacto.
+4. Identifica lagunas técnicas, riesgos y dependencias con el código existente.
+5. Hazme la lista de preguntas críticas de decisión, explicándome las implicaciones de cada una.
+6. Detente y espera mis respuestas. No escribas código aún.
+7. Cuando ya te haya respondido: valida cada decisión contra el código real antes de darla por cerrada y guarda el documento de la fase con `write_central_doc`, con el nombre que te indicó `get_phase_prompt` y la estructura que pide el prompt.
+
+El documento de la Fase 2 es obligatorio, aunque las decisiones se hayan tomado conversando: el chat no viaja entre dispositivos, el documento sí.

package/prompts/comandos/f3.md

@@ -0,0 +1,9 @@
+Vas a iniciar la FASE 3 (Plan Técnico) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(3)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee los documentos de las fases anteriores con `read_central_doc`; `get_phase_prompt` te dio sus nombres exactos.
+4. Comprueba contra el código real lo que el plan va a afirmar, ANTES de escribirlo.
+5. Con las decisiones ya tomadas, genera el plan con su tabla de lotes, respetando "Cero Rupturas".
+6. Guárdalo con `write_central_doc`, con el nombre que te indicó `get_phase_prompt`.

package/prompts/comandos/f4.md

@@ -0,0 +1,10 @@
+Vas a iniciar la FASE 4 (Ejecución) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(4)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee el plan técnico de la Fase 3 con `read_central_doc` —`get_phase_prompt` te dio su nombre exacto— y nómbrame sus pendientes antes de tocar código.
+4. Ejecútalo **lote por lote**, como indica el prompt: implementa un lote, verifícalo ejecutando, escribe su recibo, muéstrame archivos y mensaje de commit, y con mi OK haz el commit antes de abrir el siguiente. Nunca hagas push.
+5. Con un solo lote, su recibo es el documento de la fase. Con más de uno, el documento de la fase es el índice y se escribe solo al cerrar el último.
+
+El entregable de esta fase es el código funcionando, lote por lote; cada recibo es corto y se escribe al cerrar su lote.

package/prompts/comandos/f5.md

@@ -0,0 +1,12 @@
+Vas a iniciar la FASE 5 (Auditoría / Pre-PR) del flujo del mcp-phase-gate.
+
+Commits a auditar: si escribí un rango después del comando, usa ese. Si no, tómalos de los recibos de la Fase 4. Si tampoco hay recibos, pregúntame cuáles antes de seguir.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name): la auditoría se guarda en su carpeta.
+2. Llama a `get_phase_prompt(5)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol de auditor externo.
+3. Inspecciona los commits indicados usando SOLO lectura (git diff / git log de solo lectura, leer archivos). Nunca hagas commits, push ni subas PRs; de eso me encargo yo.
+4. Entrégame en el chat:
+   - La AUDITORÍA con el formato del revisor, dejando clarísimo si hay cambios BLOQUEANTES para subir el PR.
+   - La DESCRIPCIÓN del PR (título + cuerpo), contrastada contra el código real.
+5. Guarda el documento de la fase con `write_central_doc`, con el nombre que te indicó `get_phase_prompt`: lleva la auditoría y la descripción del PR tal cual me las entregaste.