mcp-phase-gate 2.0.1 → 2.2.0

package/build/index.js

@@ -2,390 +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, validarSegmento, } from "./paths.js";
-import { describePhases, discoverPhases, loadPhasePrompt, nombreContextoInicial, } from "./phases.js";
-import { avisoDeCompuerta, describeEstado, guardarPuntero, limpiarEstadoViejo, listarTareas, tareaActiva, } 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. Solo si no usas project+task_name." },
-                        content: { type: "string", description: "Contenido a escribir" }
-                    },
-                    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");
-                carpetaProyecto = proj.toUpperCase();
-                estrenado = true;
-            }
-            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.
-            let aviso = null;
-            try {
-                aviso = avisoDeCompuerta(phase, discoverPhases(), {
-                    ...(project ? { project } : {}),
-                    ...(task_name ? { taskName: task_name } : {}),
-                });
-            }
-            catch (error) {
-                console.error(`[orquestador] No se pudo comprobar la compuerta: ${error.message}`);
-            }
-            return {
-                content: [{ type: "text", text: aviso ? `${aviso}\n\n${prompt}` : prompt }],
-            };
-        }
-        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}.`);
-            }
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, content, "utf-8");
-            return {
-                content: [{ type: "text", text: `Archivo escrito exitosamente en ${fullPath}` }],
-            };
-        }
-        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.d.ts

@@ -1,7 +1,9 @@
 export declare function estaDentro(base: string, ruta: string): boolean;
 export declare function rutaReal(ruta: string): string;
 export declare function estaDentroReal(base: string, ruta: string): boolean;
+export declare function claveDeNombre(nombre: string): string;
 export declare function validarSegmento(valor: string, campo: string): string;
+export declare function validarNombreVisible(valor: string, campo: string): string;
 export declare function discoverProjects(): Map<string, string>;
 export declare function describeProjects(): string;
 export declare function findProjectFolder(project: string): string | null;
@@ -16,6 +18,13 @@ export type ArgumentosDeDocumento = {
     file_path?: string | undefined;
 };
 export declare function resolveDocPath(args: ArgumentosDeDocumento): string;
+export type UbicacionEnTarea = {
+    carpetaProyecto: string;
+    taskName: string;
+    carpetaTarea: string;
+    relativo: string;
+};
+export declare function ubicarEnTarea(rutaAbsoluta: string): UbicacionEnTarea | null;
 export declare function resolveRepoPath(repoName: string, filePath: string): string;
 export declare const LIMITE_LECTURA_BYTES = 1048576;
 export declare function leerTextoAcotado(ruta: string): string;

package/build/paths.js

@@ -38,6 +38,13 @@ export function rutaReal(ruta) {
 export function estaDentroReal(base, ruta) {
     return estaDentro(rutaReal(base), rutaReal(ruta));
 }
+// Clave para comparar nombres de documento: dos nombres con la misma clave se ven iguales, y en
+// Windows y macOS abren el mismo archivo. rutaReal solo corrige las mayúsculas de lo que ya
+// existe, así que lo que todavía no existe se compara por aquí. Sin distinguir mayúsculas en
+// todos los sistemas, para que el comportamiento no dependa del equipo.
+export function claveDeNombre(nombre) {
+    return nombre.normalize("NFC").toLowerCase();
+}
 // Un nombre de proyecto, tarea o repo es UN segmento de ruta, portable entre sistemas:
 // la Documentación viaja entre equipos con Windows, macOS y Linux. Lo que se rechaza es lo
 // que hoy ya era peligroso (separadores, "..") o lo que Windows no puede guardar y rompe la
@@ -69,6 +76,17 @@ export function validarSegmento(valor, campo) {
     }
     return valor;
 }
+// Un proyecto o una tarea que start_task va a crear tampoco puede empezar por punto: las carpetas
+// con punto no son proyecto ni tarea, así que no aparecería en list_tasks y write_central_doc no
+// podría escribir en ella. No va en validarSegmento porque read_central_doc también lo usa, y la
+// lectura no cambia.
+export function validarNombreVisible(valor, campo) {
+    if (valor.startsWith(".")) {
+        throw new Error(`${campo} ${JSON.stringify(valor)} no es válido: no puede empezar por punto. Las carpetas ` +
+            `con punto no cuentan como proyecto ni como tarea, así que no se vería después.`);
+    }
+    return valor;
+}
 // ─── Proyectos ──────────────────────────────────────────────────────────────
 // Los proyectos no se declaran en ninguna parte: son las carpetas que existen. Antes había
 // una tabla fija con los proyectos de quien escribió el código, que no restringía nada
@@ -78,12 +96,13 @@ export function validarSegmento(valor, campo) {
 // Es proyecto la carpeta que contenga la subcarpeta de tareas. Esa regla deja fuera sola a
 // las carpetas que no son proyectos, y da de alta uno nuevo con solo crearle su subcarpeta.
 // Si la subcarpeta está vacía la regla no se puede aplicar y vale cualquier carpeta.
+// Las carpetas con punto nunca son proyecto: .obsidian o .git en la raíz de la Documentación.
 export function discoverProjects() {
     const proyectos = new Map(); // clave en minúsculas -> nombre real de la carpeta
     const base = requireBasePath(DOCS);
     const subdir = tasksSubdir();
     for (const entrada of fs.readdirSync(base, { withFileTypes: true })) {
-        if (!entrada.isDirectory())
+        if (!entrada.isDirectory() || entrada.name.startsWith("."))
             continue;
         if (subdir && !fs.existsSync(path.join(base, entrada.name, subdir)))
             continue;
@@ -97,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.
@@ -114,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);
@@ -143,10 +162,10 @@ function validarRutaRelativa(valor, campo, relativaA) {
 // la base: antes "../otra-tarea/x.md" escribía en otra tarea y la comprobación de la tool,
 // que solo miraba la base, lo dejaba pasar.
 //
-// Con file_path basta con no salir de la base (la restricción a carpetas de tarea llega en la
-// Etapa 1), pero sus segmentos también tienen que ser portables: antes creaba dentro de la
-// Documentación un "CON", un "nul.md" o un flujo alterno "nota.md:secreto", que el Explorador
-// y OneDrive no saben manejar.
+// Con file_path aquí basta con no salir de la base (write_central_doc además exige que caiga en
+// una tarea: ubicarEnTarea), pero sus segmentos también tienen que ser portables: antes creaba
+// dentro de la Documentación un "CON", un "nul.md" o un flujo alterno "nota.md:secreto", que el
+// Explorador y OneDrive no saben manejar.
 export function resolveDocPath(args) {
     const { project = "", task_name: taskName = "", file_name: fileName = "", file_path: filePath = "" } = args;
     if (project && taskName && fileName) {
@@ -169,6 +188,50 @@ export function resolveDocPath(args) {
     }
     throw new Error("Debes proporcionar (project + task_name + file_name) o bien file_path.");
 }
+// Segmentos de `ruta` dentro de `base`, o null si no cae dentro. Las dos ya vienen resueltas.
+function segmentosDentro(base, ruta) {
+    const relativa = path.relative(base, ruta);
+    if (relativa === "")
+        return [];
+    if (relativa.startsWith("..") || path.isAbsolute(relativa))
+        return null;
+    return relativa.split(/[\\/]/);
+}
+// write_central_doc solo escribe dentro de la carpeta de una tarea que ya existe. Con file_path
+// se podía escribir en cualquier lugar de la Documentación, incluido el phase-gate.json del
+// proyecto, y con una tarea mal escrita el mkdir recursivo creaba una carpeta suelta.
+//
+// Se mide sobre rutas reales, como la contención: un enlace interno que lleva a una tarea vale,
+// porque lo que se escribe acaba dentro de ella. La subcarpeta de tareas se compara con la que
+// hay en disco y no con la variable: en Windows y macOS pueden diferir en mayúsculas, y
+// discoverProjects ya da el proyecto por bueno.
+//
+// Devuelve null si la ruta no cae dentro de la carpeta de una tarea existente, o si algún
+// segmento dentro de la tarea empieza por punto (.git, .phase-gate no son documentos).
+export function ubicarEnTarea(rutaAbsoluta) {
+    const docsReal = rutaReal(requireBasePath(DOCS));
+    const segmentos = segmentosDentro(docsReal, rutaReal(rutaAbsoluta));
+    if (!segmentos || segmentos.length === 0)
+        return null;
+    // El nombre que da el disco tiene que ser el del proyecto, no solo parecerse en mayúsculas.
+    const [proyecto = "", ...resto] = segmentos;
+    const carpetaProyecto = findProjectFolder(proyecto);
+    if (carpetaProyecto !== proyecto)
+        return null;
+    const raizProyecto = path.join(docsReal, carpetaProyecto);
+    const subdir = segmentosDentro(raizProyecto, rutaReal(tasksRootPath(carpetaProyecto)));
+    if (!subdir || subdir.some((segmento, i) => resto[i] !== segmento))
+        return null;
+    const [taskName, ...archivo] = resto.slice(subdir.length);
+    if (!taskName || taskName.startsWith(".") || archivo.length === 0)
+        return null;
+    if (archivo.some((segmento) => segmento.startsWith(".")))
+        return null;
+    const carpetaTarea = path.join(raizProyecto, ...subdir, taskName);
+    if (!fs.statSync(carpetaTarea, { throwIfNoEntry: false })?.isDirectory())
+        return null;
+    return { carpetaProyecto, taskName, carpetaTarea, relativo: archivo.join("/") };
+}
 // ─── Repos ──────────────────────────────────────────────────────────────────
 // Ruta de un archivo dentro de UN repo. Antes la comprobación miraba la carpeta de repos
 // entera, y desde repoA "../repoB/.env" pasaba: estaba dentro de la carpeta de repos. El repo

package/build/phases.d.ts

@@ -1,19 +1,31 @@
+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;
     title: string;
     documento?: string | undefined;
     documentoInicial?: string | undefined;
+    recibos?: string | undefined;
 };
+export declare const MARCADOR_RANURA: RegExp;
+export declare function quitarMarcadores(texto: string): string;
 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