mcp-phase-gate 2.0.0 → 2.1.0

package/build/index.js

@@ -11,9 +11,10 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 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, estaDentro, findProjectFolder, requireProjectFolder, resolveDocPath, taskFolderPath, } from "./paths.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, describeEstado, guardarPuntero, limpiarEstadoViejo, listarTareas, tareaActiva, } from "./tasks.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,
@@ -115,8 +116,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         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" }
+                        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"],
                 },
@@ -139,25 +141,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        if (name === "start_task") {
-            const proj = String(args?.project).trim();
-            const taskName = String(args?.task_name);
-            const context = String(args?.initial_context);
+        // 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 (args?.crear_proyecto !== true) {
+                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.
@@ -178,31 +191,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `Tarea '${taskName}' inicializada correctamente. Archivo guardado en: ${contextoInicial}\nTarea activa de ${carpetaProyecto}: ${taskName}.${aviso}` }],
             };
         }
-        if (name === "get_phase_prompt") {
-            const phase = Number(args?.phase);
-            if (!Number.isInteger(phase)) {
-                throw new Error(`Debes indicar un número de fase. Disponibles: ${PHASES_DESCRIPTION}.`);
-            }
+        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 {
-                aviso = avisoDeCompuerta(phase, discoverPhases(), {
-                    ...(args?.project ? { project: String(args.project) } : {}),
-                    ...(args?.task_name ? { taskName: String(args.task_name) } : {}),
-                });
+                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: aviso ? `${aviso}\n\n${prompt}` : prompt }],
+                content: [{ type: "text", text: texto }],
             };
         }
-        if (name === "get_active_task") {
+        if (llamada.tool === "get_active_task") {
             const phases = discoverPhases();
-            const pedido = args?.project ? String(args.project) : "";
+            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.
@@ -230,9 +246,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `${bloques.join("\n\n")}\n\nPunteros guardados en: ${stateFile()}` }],
             };
         }
-        if (name === "list_tasks") {
+        if (llamada.tool === "list_tasks") {
             const phases = discoverPhases();
-            const pedido = args?.project ? String(args.project) : "";
+            const pedido = llamada.args.project ?? "";
             const proyectos = pedido
                 ? [requireProjectFolder(pedido)]
                 : [...discoverProjects().values()].sort();
@@ -254,10 +270,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: bloques.join("\n\n") || "No hay proyectos todavía." }],
             };
         }
-        if (name === "switch_task") {
+        if (llamada.tool === "switch_task") {
             const phases = discoverPhases();
-            const carpetaProyecto = requireProjectFolder(String(args?.project));
-            const taskName = String(args?.task_name);
+            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) {
@@ -272,39 +288,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `Tarea activa de ${carpetaProyecto}: ${taskName}.\nFase: ${describeEstado(encontrada, phases)}\nCarpeta: ${encontrada.folderPath}` }],
             };
         }
-        if (name === "read_central_doc") {
+        if (llamada.tool === "read_central_doc") {
             const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(args);
-            if (!estaDentro(docsBase, fullPath)) {
+            const fullPath = resolveDocPath(llamada.args);
+            if (!estaDentroReal(docsBase, fullPath)) {
                 throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
             }
-            const content = fs.readFileSync(fullPath, "utf-8");
+            const content = leerTextoAcotado(fullPath);
             return {
                 content: [{ type: "text", text: content }],
             };
         }
-        if (name === "write_central_doc") {
-            const content = String(args?.content);
+        if (llamada.tool === "write_central_doc") {
+            const content = llamada.args.content;
             const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(args);
-            if (!estaDentro(docsBase, fullPath)) {
+            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}` }],
+                content: [{ type: "text", text: `Archivo escrito exitosamente en ${fullPath}${forzado}` }],
             };
         }
-        if (name === "read_cross_repo") {
-            const repoName = String(args?.repo_name);
-            const filePath = String(args?.file_path);
-            const reposBase = requireBasePath(REPOS);
-            const fullPath = path.join(reposBase, repoName, filePath);
-            if (!estaDentro(reposBase, fullPath)) {
-                throw new Error(`Acceso denegado: la ruta queda fuera de ${reposBase}.`);
-            }
-            const content = fs.readFileSync(fullPath, "utf-8");
+        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 }],
             };
@@ -335,36 +360,36 @@ function reportarRutas() {
 // 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>"
-        }
-      }
-    }
-  }
-
-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.
-
+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>"
+        }
+      }
+    }
+  }
+
+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`;
 async function main() {
     const bandera = process.argv[2];

package/build/paths.d.ts

@@ -1,4 +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;
@@ -6,5 +11,21 @@ export declare function requireProjectFolder(project: string): string;
 export declare function taskFolderPath(carpetaProyecto: string, taskName: string): string;
 export declare function resolveTaskFolder(project: string, taskName: string): string;
 export declare function tasksRootPath(carpetaProyecto: string): string;
-export declare function resolveDocPath(args: any): string;
+export type ArgumentosDeDocumento = {
+    project?: string | undefined;
+    task_name?: string | undefined;
+    file_name?: string | undefined;
+    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;
 //# sourceMappingURL=paths.d.ts.map

package/build/paths.js

@@ -6,7 +6,7 @@
 // busca. Por eso además de armarlas hay que comprobar que caigan dentro de la base.
 import * as fs from "fs";
 import * as path from "path";
-import { DOCS, requireBasePath, tasksSubdir } from "./config.js";
+import { DOCS, REPOS, requireBasePath, tasksSubdir } from "./config.js";
 // Comprueba que una ruta quede dentro de otra. No sirve startsWith, y falla en las dos
 // direcciones: con base "C:\PROYECTOS\TRABAJO" deja pasar "C:\PROYECTOS\TRABAJO_VIEJO",
 // que empieza igual sin estar dentro; y rechaza rutas válidas cuando la base viene escrita
@@ -15,6 +15,78 @@ export function estaDentro(base, ruta) {
     const relativa = path.relative(path.resolve(base), path.resolve(ruta));
     return relativa === "" || (!relativa.startsWith("..") && !path.isAbsolute(relativa));
 }
+// Resuelve symlinks y junctions del ancestro existente más cercano y vuelve a unir el resto.
+// Hace falta porque la ruta que se va a escribir casi nunca existe todavía, y realpath solo
+// funciona sobre lo que existe. "Existe" se mira con lstat y no con existsSync: un enlace roto
+// cuenta como existente, realpath falla sobre él y la operación se rechaza. Con existsSync se
+// saltaría, y escribir a través de él crearía su destino, esté donde esté.
+export function rutaReal(ruta) {
+    let existente = path.resolve(ruta);
+    const pendientes = [];
+    while (!fs.lstatSync(existente, { throwIfNoEntry: false })) {
+        const padre = path.dirname(existente);
+        if (padre === existente)
+            break; // ni la raíz existe: que realpath dé el error
+        pendientes.unshift(path.basename(existente));
+        existente = padre;
+    }
+    return path.join(fs.realpathSync.native(existente), ...pendientes);
+}
+// estaDentro sobre rutas reales. Comparar el texto no basta: un symlink dentro de la
+// Documentación que apunta fuera tiene una ruta que "está dentro" y un destino que no.
+// La base también se resuelve: una DOCS que es symlink sigue valiendo.
+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
+// sincronización (caracteres reservados, punto o espacio final, CON, NUL…).
+const CARACTERES_RESERVADOS = /[<>:"|?*]/;
+const CARACTERES_DE_CONTROL = /[\u0000-\u001f\u007f]/;
+// Windows también reserva COM y LPT con los superíndices ¹²³, y las consolas CONIN$ y CONOUT$.
+// Los espacios antes de la extensión no cuentan: "nul .txt" sigue siendo NUL.
+const NOMBRES_RESERVADOS_WINDOWS = /^(con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³]) *(\..*)?$/i;
+export function validarSegmento(valor, campo) {
+    const incumple = (regla) => {
+        throw new Error(`${campo} ${JSON.stringify(valor)} no es válido: ${regla}. Tiene que ser un solo nombre de ` +
+            `carpeta o archivo, que funcione igual en Windows, macOS y Linux.`);
+    };
+    if (valor.trim() === "")
+        incumple("está vacío");
+    if (valor === "." || valor === "..")
+        incumple(`no puede ser "${valor}"`);
+    if (/[\\/]/.test(valor))
+        incumple("no puede llevar / ni \\");
+    if (CARACTERES_DE_CONTROL.test(valor))
+        incumple("no puede llevar caracteres de control");
+    if (CARACTERES_RESERVADOS.test(valor))
+        incumple('no puede llevar ninguno de < > : " | ? *');
+    if (/[. ]$/.test(valor))
+        incumple("no puede terminar en punto ni en espacio");
+    if (NOMBRES_RESERVADOS_WINDOWS.test(valor)) {
+        incumple("es un nombre reservado de Windows (CON, PRN, AUX, NUL, CONIN$, CONOUT$, COM1–COM9, LPT1–LPT9)");
+    }
+    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
@@ -24,12 +96,13 @@ export function estaDentro(base, ruta) {
 // 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;
@@ -62,6 +135,7 @@ export function requireProjectFolder(project) {
 // La ruta de una tarea SIEMPRE se arma aquí, en un solo lugar.
 // Estructura: <ORQUESTADOR_DOCS_PATH>/<PROYECTO>/<subcarpeta de tareas>/<tarea>
 export function taskFolderPath(carpetaProyecto, taskName) {
+    validarSegmento(taskName, "task_name");
     return path.join(requireBasePath(DOCS), carpetaProyecto, tasksSubdir(), taskName);
 }
 export function resolveTaskFolder(project, taskName) {
@@ -74,16 +148,157 @@ export function tasksRootPath(carpetaProyecto) {
 }
 // Resuelve la ruta absoluta para read/write. Prioriza project+task_name+file_name;
 // si no, cae al modo legacy con file_path relativo a la Documentación Central.
+//
+// Una ruta relativa hecha de segmentos portables. Cada segmento se valida por separado para que
+// una subcarpeta legítima como "04 - Ejecución/L01 - x.md" siga valiendo.
+function validarRutaRelativa(valor, campo, relativaA) {
+    if (path.isAbsolute(valor)) {
+        throw new Error(`${campo} no puede ser una ruta absoluta ("${valor}"): es relativo a ${relativaA}.`);
+    }
+    for (const segmento of valor.split(/[\\/]/))
+        validarSegmento(segmento, campo);
+}
+// Con file_name la ruta tiene que quedar dentro de la carpeta de la tarea, no solo dentro de
+// 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 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 = args?.project ? String(args.project) : "";
-    const taskName = args?.task_name ? String(args.task_name) : "";
-    const fileName = args?.file_name ? String(args.file_name) : "";
+    const { project = "", task_name: taskName = "", file_name: fileName = "", file_path: filePath = "" } = args;
     if (project && taskName && fileName) {
-        return path.join(resolveTaskFolder(project, taskName), fileName);
+        const carpetaTarea = resolveTaskFolder(project, taskName);
+        validarRutaRelativa(fileName, "file_name", "la carpeta de la tarea");
+        const ruta = path.join(carpetaTarea, fileName);
+        if (!estaDentroReal(carpetaTarea, ruta)) {
+            throw new Error(`Acceso denegado: file_name "${fileName}" queda fuera de la carpeta de la tarea ${carpetaTarea}.`);
+        }
+        return ruta;
     }
-    if (args?.file_path) {
-        return path.join(requireBasePath(DOCS), String(args.file_path));
+    if (filePath) {
+        const docsBase = requireBasePath(DOCS);
+        validarRutaRelativa(filePath, "file_path", "la Documentación Central");
+        const ruta = path.join(docsBase, filePath);
+        if (!estaDentroReal(docsBase, ruta)) {
+            throw new Error(`Acceso denegado: file_path queda fuera de ${docsBase}.`);
+        }
+        return ruta;
     }
     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
+// se resuelve a su ruta real para que un repo que es un enlace a otra unidad siga valiendo.
+export function resolveRepoPath(repoName, filePath) {
+    validarSegmento(repoName, "repo_name");
+    const repo = path.join(requireBasePath(REPOS), repoName);
+    const repoReal = rutaReal(repo);
+    const ruta = path.join(repo, filePath);
+    if (!estaDentroReal(repoReal, ruta)) {
+        throw new Error(`Acceso denegado: file_path "${filePath}" queda fuera del repositorio ${repoName}.`);
+    }
+    return ruta;
+}
+// ─── Lectura acotada ────────────────────────────────────────────────────────
+// Lo que leen las tools va entero al contexto del modelo. Un volcado de varios megas o un
+// binario no le sirven de nada y se comen la conversación, así que se cortan antes de leer.
+export const LIMITE_LECTURA_BYTES = 1_048_576;
+// La misma heurística que usa git para decidir si un archivo es binario.
+const BYTES_PARA_DETECTAR_BINARIO = 8000;
+// Se lee del descriptor y no de la ruta: tipo, tamaño y contenido salen del mismo archivo
+// abierto. Con statSync seguido de readFileSync, un archivo que crecía entre las dos llamadas
+// se leía entero, sin tope. Y nunca se piden más de LIMITE + 1 bytes, que es lo justo para
+// saber si se pasa. O_NONBLOCK, que no existe en Windows, evita que abrir un FIFO se quede
+// esperando a que alguien escriba en él.
+//
+// Riesgo aceptado: la contención se comprueba sobre la ruta real y aquí se abre la ruta tal
+// cual, así que cambiar un enlace justo entre las dos cosas abriría otro destino. Cerrarlo
+// exige abrir sin seguir enlaces componente a componente, que Node no ofrece de forma portable.
+export function leerTextoAcotado(ruta) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(ruta, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        if (error?.code === "EISDIR")
+            throw new Error(`${ruta} no es un archivo: es una carpeta.`);
+        throw error;
+    }
+    try {
+        const info = fs.fstatSync(descriptor);
+        if (!info.isFile()) {
+            throw new Error(`${ruta} no es un archivo normal: es una carpeta, un dispositivo o una tubería.`);
+        }
+        if (info.size > LIMITE_LECTURA_BYTES) {
+            throw new Error(`${ruta} pesa ${info.size} bytes y el límite de lectura es 1 MB (${LIMITE_LECTURA_BYTES} bytes).`);
+        }
+        const buffer = Buffer.alloc(LIMITE_LECTURA_BYTES + 1);
+        let leidos = 0;
+        while (leidos < buffer.length) {
+            const bytes = fs.readSync(descriptor, buffer, leidos, buffer.length - leidos, null);
+            if (bytes === 0)
+                break;
+            leidos += bytes;
+        }
+        if (leidos > LIMITE_LECTURA_BYTES) {
+            throw new Error(`${ruta} creció mientras se leía y pasa del límite de lectura de 1 MB (${LIMITE_LECTURA_BYTES} bytes).`);
+        }
+        const contenido = buffer.subarray(0, leidos);
+        if (contenido.subarray(0, BYTES_PARA_DETECTAR_BINARIO).includes(0)) {
+            throw new Error(`${ruta} parece binario: tiene un byte NUL en sus primeros ${BYTES_PARA_DETECTAR_BINARIO} bytes. ` +
+                `Estas tools solo leen texto.`);
+        }
+        return contenido.toString("utf-8");
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
 //# sourceMappingURL=paths.js.map

package/build/phases.d.ts

@@ -4,7 +4,10 @@ export type PhaseFile = {
     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;