mcp-phase-gate 2.1.0 → 2.2.0

package/build/index.js

@@ -2,413 +2,53 @@
 // El shebang es lo que vuelve ejecutable este archivo como `bin` del paquete. Sin él,
 // `npx mcp-phase-gate` falla en Linux y macOS: el sistema no sabe con qué interpretarlo.
 //
-// Servidor MCP: define 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.
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+// El punto de entrada: con argumentos, la línea de comandos (cli.ts); sin ellos, el servidor MCP
+// (servidor.ts) conectado por stdio. Aquí no se define ninguna tool.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import * as fs from "fs";
-import * as path from "path";
-import { DOCS, REPOS, SERVER_NAME, SERVER_VERSION, requireBasePath, stateFile } from "./config.js";
-import { describeProjects, discoverProjects, estaDentroReal, findProjectFolder, leerTextoAcotado, requireProjectFolder, resolveDocPath, resolveRepoPath, taskFolderPath, ubicarEnTarea, validarNombreVisible, validarSegmento, } from "./paths.js";
-import { describePhases, discoverPhases, loadPhasePrompt, nombreContextoInicial, } from "./phases.js";
-import { avisoDeCompuerta, bloqueDeRecibos, describeEstado, guardarPuntero, limpiarEstadoViejo, listarTareas, motivoDeProteccion, tareaActiva, tareaDelPrompt, } from "./tasks.js";
-import { validarLlamada } from "./schemas.js";
-const server = new Server({
-    name: SERVER_NAME,
-    version: SERVER_VERSION,
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-// La lista de tools es estática, así que estas descripciones se arman una sola vez al
-// arrancar. La de proyectos puede quedarse vieja si creas una carpeta con el cliente abierto:
-// es orientativa, y la lista que manda es la que devuelven las tools al rechazar un proyecto.
-const PHASES_DESCRIPTION = describePhases();
-const PROJECTS_DESCRIPTION = describeProjects();
-// ─── Formato de las respuestas de tarea ─────────────────────────────────────
-function lineaDeTarea(estado, phases) {
-    return `- ${estado.taskName} — ${describeEstado(estado, phases)}`;
-}
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: "start_task",
-                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: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto. Tiene que ser uno de los que ya existen: ${PROJECTS_DESCRIPTION}. Si no lo es, la tool te devuelve la lista actualizada.` },
-                        task_name: { type: "string", description: "Nombre de la tarea (creará una carpeta con este nombre)" },
-                        initial_context: { type: "string", description: "El contexto, correo o requerimiento inicial completo" },
-                        crear_proyecto: { type: "boolean", description: "Solo para ESTRENAR un proyecto que todavía no existe. Déjalo sin poner salvo que el usuario te haya dicho explícitamente que quiere crear un proyecto nuevo: sirve para que un nombre mal escrito no cree una carpeta suelta en la Documentación." }
-                    },
-                    required: ["project", "task_name", "initial_context"],
-                },
-            },
-            {
-                name: "get_phase_prompt",
-                description: `Obtiene el prompt maestro de comportamiento según la fase. Fases disponibles — ${PHASES_DESCRIPTION}. Comprueba además que no te estés saltando una fase: si faltan documentos anteriores, el prompt llega con un aviso al principio.`,
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        phase: { type: "number", description: `Número de la fase. Disponibles: ${PHASES_DESCRIPTION}.` },
-                        project: { type: "string", description: `Proyecto en el que estás trabajando: ${PROJECTS_DESCRIPTION}. Pásalo siempre que lo sepas —lo sabes por el repositorio que tienes abierto— para que se pueda comprobar que no te saltas una fase. La tarea se toma de la activa de ese proyecto.` },
-                        task_name: { type: "string", description: "Solo si quieres comprobar contra una tarea distinta de la activa del proyecto. Normalmente se omite." }
-                    },
-                    required: ["phase"],
-                },
-            },
-            {
-                name: "get_active_task",
-                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: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto del que quieres la tarea activa: ${PROJECTS_DESCRIPTION}. Si lo omites, se listan las de todos los proyectos.` }
-                    },
-                },
-            },
-            {
-                name: "list_tasks",
-                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: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto a listar: ${PROJECTS_DESCRIPTION}. Si lo omites, se listan todos.` }
-                    },
-                },
-            },
-            {
-                name: "switch_task",
-                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: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto de la tarea: ${PROJECTS_DESCRIPTION}.` },
-                        task_name: { type: "string", description: "Nombre de la carpeta de la tarea a activar. Si no existe, la tool te devuelve las que sí." }
-                    },
-                    required: ["project", "task_name"],
-                },
-            },
-            {
-                name: "read_central_doc",
-                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>/Proyectos/<tarea>/<archivo>). Alternativamente puedes pasar 'file_path' relativo a DOCUMENTACIÓN.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto, uno de los existentes: ${PROJECTS_DESCRIPTION}. Úsalo junto con task_name y file_name.` },
-                        task_name: { type: "string", description: "Nombre de la carpeta de la tarea." },
-                        file_name: { type: "string", description: "Nombre (o ruta relativa) del archivo dentro de la carpeta de la tarea (ej. '01 - Análisis Técnico.md')." },
-                        file_path: { type: "string", description: "ALTERNATIVA: ruta relativa dentro de DOCUMENTACIÓN (ej. 'PROYECTO-A/Proyectos/tarea/01-analisis.md'). Solo si no usas project+task_name." }
-                    },
-                },
-            },
-            {
-                name: "write_central_doc",
-                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>/Proyectos/<tarea>/<archivo>). Alternativamente puedes pasar 'file_path' relativo a DOCUMENTACIÓN.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        project: { type: "string", description: `Proyecto, uno de los existentes: ${PROJECTS_DESCRIPTION}. Úsalo junto con task_name y file_name.` },
-                        task_name: { type: "string", description: "Nombre de la carpeta de la tarea." },
-                        file_name: { type: "string", description: "Nombre (o ruta relativa) del archivo dentro de la carpeta de la tarea (ej. '01 - Análisis Técnico.md')." },
-                        file_path: { type: "string", description: "ALTERNATIVA: ruta relativa dentro de DOCUMENTACIÓN, que tiene que caer dentro de la carpeta de una tarea que ya existe (ej. 'PROYECTO-A/Proyectos/tarea/01 - Análisis Técnico.md'). Los archivos del proyecto no se escriben con esta tool. Solo si no usas project+task_name." },
-                        content: { type: "string", description: "Contenido a escribir" },
-                        force: { type: "boolean", description: "Solo con confirmación explícita del usuario en el chat. Permite reescribir un documento congelado o el contexto inicial." }
-                    },
-                    required: ["content"],
-                },
-            },
-            {
-                name: "read_cross_repo",
-                description: "Lee archivos de otros repositorios locales, dentro de la carpeta configurada en ORQUESTADOR_REPOS_PATH.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        repo_name: { type: "string", description: "Nombre del repositorio (ej. 'repo-a', 'repo-b')" },
-                        file_path: { type: "string", description: "Ruta relativa del archivo dentro del repositorio (ej. 'src/main.ts')" }
-                    },
-                    required: ["repo_name", "file_path"],
-                },
-            }
-        ],
-    };
-});
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    try {
-        // Todo argumento se valida aquí, antes de que ninguna tool lo use. Un campo ausente o de
-        // otro tipo devuelve un error que lo nombra, en vez de convertirse en "undefined".
-        const llamada = validarLlamada(name, args);
-        if (llamada.tool === "start_task") {
-            const proj = llamada.args.project; // el schema ya le quitó los espacios
-            const taskName = llamada.args.task_name;
-            const context = llamada.args.initial_context;
-            // 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 (llamada.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}.`);
-            }
-            // 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}`);
-            }
-            if (!fs.existsSync(carpetaTarea)) {
-                fs.mkdirSync(carpetaTarea, { recursive: true });
-            }
-            fs.writeFileSync(contextoInicial, 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);
-            const aviso = estrenado ? `\nProyecto "${carpetaProyecto}" estrenado.` : "";
-            return {
-                content: [{ type: "text", text: `Tarea '${taskName}' inicializada correctamente. Archivo guardado en: ${contextoInicial}\nTarea activa de ${carpetaProyecto}: ${taskName}.${aviso}` }],
-            };
-        }
-        if (llamada.tool === "get_phase_prompt") {
-            // Que sea un entero ya lo garantiza el schema; si la fase no existe, lo dice loadPhasePrompt.
-            const { phase, project, task_name } = llamada.args;
-            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 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")
-                    recibos = bloqueDeRecibos(phase, estado, phases);
-            }
-            catch (error) {
-                console.error(`[orquestador] No se pudo comprobar la compuerta: ${error.message}`);
-            }
-            const texto = [aviso, prompt, recibos].filter(Boolean).join("\n\n");
-            return {
-                content: [{ type: "text", text: texto }],
-            };
-        }
-        if (llamada.tool === "get_active_task") {
-            const phases = discoverPhases();
-            const pedido = llamada.args.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 { content: [{ type: "text", text: `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 {
-                content: [{ type: "text", text: `${bloques.join("\n\n")}\n\nPunteros guardados en: ${stateFile()}` }],
-            };
-        }
-        if (llamada.tool === "list_tasks") {
-            const phases = discoverPhases();
-            const pedido = llamada.args.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 {
-                content: [{ type: "text", text: bloques.join("\n\n") || "No hay proyectos todavía." }],
-            };
-        }
-        if (llamada.tool === "switch_task") {
-            const phases = discoverPhases();
-            const carpetaProyecto = requireProjectFolder(llamada.args.project);
-            const taskName = llamada.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);
-            return {
-                content: [{ type: "text", text: `Tarea activa de ${carpetaProyecto}: ${taskName}.\nFase: ${describeEstado(encontrada, phases)}\nCarpeta: ${encontrada.folderPath}` }],
-            };
-        }
-        if (llamada.tool === "read_central_doc") {
-            const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(llamada.args);
-            if (!estaDentroReal(docsBase, fullPath)) {
-                throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
-            }
-            const content = leerTextoAcotado(fullPath);
-            return {
-                content: [{ type: "text", text: content }],
-            };
-        }
-        if (llamada.tool === "write_central_doc") {
-            const content = llamada.args.content;
-            const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(llamada.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());
-            if (motivo && llamada.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.`);
-            }
-            const existia = fs.existsSync(fullPath);
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, content, "utf-8");
-            // force también crea el contexto inicial cuando falta: no se dice "sobrescrito" si no lo era.
-            const forzado = motivo ? (existia ? " (sobrescrito con force)" : " (creado con force)") : "";
-            return {
-                content: [{ type: "text", text: `Archivo escrito exitosamente en ${fullPath}${forzado}` }],
-            };
-        }
-        if (llamada.tool === "read_cross_repo") {
-            const fullPath = resolveRepoPath(llamada.args.repo_name, llamada.args.file_path);
-            const content = leerTextoAcotado(fullPath);
-            return {
-                content: [{ type: "text", text: content }],
-            };
-        }
-        throw new Error(`Unknown tool: ${name}`);
-    }
-    catch (error) {
-        return {
-            content: [{ type: "text", text: `Error ejecutando tool ${name}: ${error.message}` }],
-            isError: true,
-        };
-    }
-});
+import { DOCS, NOMBRES_LOGICOS, REPOS, SERVER_NAME, errorDeEnv, leerVariable, requireBasePath } from "./config.js";
+import { ejecutarCli } from "./cli.js";
+import { log } from "./log.js";
+import { crearServidor } from "./servidor.js";
+import { limpiarEstadoViejo } from "./tasks.js";
 // Deja en el log el estado de cada ruta al arrancar. No aborta: el servidor sigue en pie y
 // el error real se entrega al llamar la tool. Esto es solo para que, cuando alguien acabe
 // abriendo el log, el motivo ya esté ahí escrito.
 function reportarRutas() {
     for (const requerida of [DOCS, REPOS]) {
         try {
-            console.error(`[orquestador] ${requerida.variable} = ${requireBasePath(requerida)}`);
+            const ruta = requireBasePath(requerida);
+            log("info", `${leerVariable(requerida.logica).usada} = ${ruta}`);
         }
         catch (error) {
-            console.error(`[orquestador] SIN CONFIGURAR: ${error.message}`);
+            log("error", `SIN CONFIGURAR: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-}
-// Un servidor MCP habla JSON-RPC por stdin y no imprime nada por stdout. Ejecutado a mano en
-// una terminal —que es exactamente lo que hace quien acaba de leer `npx mcp-phase-gate` en el
-// README— se queda esperando entrada, sin señal de vida, y parece roto. Estas dos banderas
-// existen para que ese momento devuelva una explicación en vez de un cursor parpadeando.
-const AYUDA = `${SERVER_NAME} v${SERVER_VERSION}
-
-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.
-
-Esto NO se ejecuta a mano: lo lanza tu cliente MCP. Ejecutado directamente se queda esperando
-mensajes JSON-RPC por stdin, que es lo que parece que se colgó.
-
-Regístralo en tu cliente (Cursor, VS Code, Claude Code) así:
-
-  {
-    "mcpServers": {
-      "${SERVER_NAME}": {
-        "command": "npx",
-        "args": ["-y", "mcp-phase-gate"],
-        "env": {
-          "ORQUESTADOR_DOCS_PATH": "<tu carpeta de documentación>",
-          "ORQUESTADOR_REPOS_PATH": "<tu carpeta de repositorios>"
-        }
-      }
+    // Las dos variables de un mismo nombre lógico, con valores distintos: se avisa una vez.
+    for (const logica of NOMBRES_LOGICOS) {
+        const { discrepancia } = leerVariable(logica);
+        if (discrepancia)
+            log("warning", discrepancia);
     }
-  }
-
-Variables de entorno:
-  ORQUESTADOR_DOCS_PATH      Obligatoria. Raíz de la Documentación Central.
-  ORQUESTADOR_REPOS_PATH     Obligatoria. Carpeta con tus repositorios de código.
-  ORQUESTADOR_TASKS_SUBDIR   Subcarpeta de tareas dentro de cada proyecto. Por defecto "Proyectos".
-  ORQUESTADOR_PROMPTS_PATH   Carpeta de prompts propios, que se superponen a los del paquete.
-  ORQUESTADOR_STATE_PATH     Dónde guardar los punteros de tarea activa.
-
-Documentación: https://github.com/Montse2308/mcp-phase-gate`;
+    const delEnv = errorDeEnv();
+    if (delEnv)
+        log("error", delEnv);
+}
 async function main() {
-    const bandera = process.argv[2];
-    if (bandera === "--version" || bandera === "-v") {
-        console.log(SERVER_VERSION);
-        return;
-    }
-    if (bandera === "--help" || bandera === "-h") {
-        console.log(AYUDA);
+    // Con argumentos, el binario es la herramienta de la persona (ayuda, versión, doctor); sin
+    // ellos, el servidor que lanza el cliente. exitCode y no exit(): exit cortaría la salida de
+    // doctor a medio escribir cuando stdout es una tubería.
+    const resultado = ejecutarCli(process.argv.slice(2));
+    if (resultado.accion === "salir") {
+        process.exitCode = resultado.codigo;
         return;
     }
     limpiarEstadoViejo();
     reportarRutas();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`${SERVER_NAME} MCP server running on stdio`);
+    await crearServidor().connect(new StdioServerTransport());
+    log("info", `${SERVER_NAME} MCP server running on stdio`);
 }
 main().catch((error) => {
-    console.error("Server error:", error);
+    log("error", `Server error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
     process.exit(1);
 });
 //# sourceMappingURL=index.js.map

package/build/log.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
+export declare const PREFIJO_LOG = "[mcp-phase-gate]";
+export declare function conectarLog(mcp: McpServer | null): void;
+export declare function log(nivel: LoggingLevel, texto: string): void;
+//# sourceMappingURL=log.d.ts.map

package/build/log.js

@@ -0,0 +1,27 @@
+// El log del servidor. Va siempre a stderr, que es lo que guardan los clientes en su archivo de
+// log, y además, cuando hay un cliente conectado, como notificación MCP (`notifications/message`),
+// que algunos clientes muestran en su panel. stdout nunca: es el canal del JSON-RPC.
+//
+// Vive en su propio módulo y no en servidor.ts porque lo usan también phases.ts y tasks.ts, que
+// servidor.ts importa: ponerlo ahí haría un import circular.
+import { SERVER_NAME } from "./config.js";
+export const PREFIJO_LOG = `[${SERVER_NAME}]`;
+// Un solo servidor por proceso, que es lo que hay en producción. Si se crean varios (los tests),
+// las notificaciones van al último que se creó; stderr sigue recibiendo todo.
+let conectado = null;
+// Lo llama crearServidor. Desde ese momento, si el servidor está conectado, cada línea del log
+// también sale como notificación.
+export function conectarLog(mcp) {
+    conectado = mcp;
+}
+export function log(nivel, texto) {
+    console.error(`${PREFIJO_LOG} ${texto}`);
+    // Solo después del initialize: antes, el cliente no espera notificaciones, y en una terminal la
+    // línea JSON aparecía cruda en stdout al arrancar.
+    if (!conectado?.isConnected() || !conectado.server.getClientVersion())
+        return;
+    // El SDK descarta solo lo que esté por debajo del nivel que pidió el cliente. Un fallo al
+    // notificar no puede tumbar la operación que estaba registrando: ya quedó en stderr.
+    conectado.server.sendLoggingMessage({ level: nivel, logger: SERVER_NAME, data: texto }).catch(() => { });
+}
+//# sourceMappingURL=log.js.map

package/build/paths.js

@@ -116,8 +116,8 @@ export function describeProjects() {
         return nombres.length ? nombres.join(", ") : "(ninguno todavía)";
     }
     catch {
-        // Sin ORQUESTADOR_DOCS_PATH configurada no se pueden listar; el error real lo da la tool.
-        return "(no se pudieron leer: revisa ORQUESTADOR_DOCS_PATH)";
+        // Sin DOCS_PATH configurada no se pueden listar; el error real lo da la tool.
+        return "(no se pudieron leer: revisa PHASE_GATE_DOCS_PATH)";
     }
 }
 // Devuelve el nombre real de la carpeta, respetando mayúsculas, o null si no existe.
@@ -133,7 +133,7 @@ export function requireProjectFolder(project) {
 }
 // ─── Carpetas de tarea ──────────────────────────────────────────────────────
 // La ruta de una tarea SIEMPRE se arma aquí, en un solo lugar.
-// Estructura: <ORQUESTADOR_DOCS_PATH>/<PROYECTO>/<subcarpeta de tareas>/<tarea>
+// Estructura: <PHASE_GATE_DOCS_PATH>/<PROYECTO>/<subcarpeta de tareas>/<tarea>
 export function taskFolderPath(carpetaProyecto, taskName) {
     validarSegmento(taskName, "task_name");
     return path.join(requireBasePath(DOCS), carpetaProyecto, tasksSubdir(), taskName);

package/build/phases.d.ts

@@ -1,3 +1,7 @@
+export declare const GLOBAL_RULES_FILE = "global-rules.md";
+export declare const CARPETA_COMANDOS = "comandos";
+export declare function resolveCommandFile(numero: number, capas?: string[]): string | null;
+export declare function esCarpeta(ruta: string): boolean;
 export declare const PHASE_FILE_PATTERN: RegExp;
 export type PhaseFile = {
     file: string;
@@ -12,11 +16,16 @@ export declare function parsePhaseFile(fullPath: string): {
     meta: Record<string, string>;
     cuerpo: string;
 };
+export declare function separarFrontmatter(texto: string): {
+    meta: Record<string, string>;
+    cuerpo: string;
+};
 export declare function discoverPhases(capas?: string[]): Map<number, PhaseFile>;
 export declare function readPhaseTitle(cuerpo: string, fileName: string): string;
 export declare const CONTEXTO_INICIAL_POR_DEFECTO = "00 - Contexto Inicial.md";
 export declare function nombreContextoInicial(capas?: string[]): string;
 export declare function loadPhasePrompt(phase: number, capas?: string[]): string;
+export declare function resolveGlobalRules(capas?: string[]): string | null;
+export declare function leerPromptNormalizado(ruta: string): string;
 export declare function describePhaseFiles(available: Map<number, PhaseFile>, phase: number): string;
-export declare function describePhases(): string;
 //# sourceMappingURL=phases.d.ts.map