mcp-phase-gate 2.0.0 → 2.1.0

package/build/phases.js

@@ -4,6 +4,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { promptsLayers } from "./config.js";
+import { claveDeNombre, validarSegmento } from "./paths.js";
 // Las reglas globales se anteponen a cada fase.
 const GLOBAL_RULES_FILE = "global-rules.md";
 // Acepta "fase-1-descubrimiento.md" y también "phase-1-discovery.md",
@@ -14,8 +15,72 @@ export const PHASE_FILE_PATTERN = /^(?:fase|phase)-(\d+)[-.]/i;
 // describe ese documento —no en un archivo de configuración aparte— para que el nombre exista
 // en un solo lugar y se lea en vivo, sin recompilar, igual que el resto del prompt.
 const PHASE_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+// Los prompts propios, escritos por ejemplo con el Bloc de notas, llegan en CRLF, y a veces con
+// BOM al principio. Se normalizan al leer: lo que se entrega al modelo y lo que se compara en los
+// tests va siempre en LF y sin BOM. Con el BOM delante, el frontmatter no se reconocía y la fase
+// se quedaba sin documento.
+function aLF(texto) {
+    return texto.replace(/^/, "").replace(/\r\n/g, "\n");
+}
+// Quita los marcadores de ranura y conserva su contenido. El modelo nunca los ve.
+// Una ranura marca el contenido de una sección que un preset podrá sustituir en la Etapa 3:
+//   <!-- ranura: verificacion -->
+//   contenido por defecto
+//   <!-- /ranura -->
+// Solo cuenta un marcador que ocupa su propia línea, y la línea se quita entera. Un marcador con
+// texto detrás, o dos en la misma línea, no se toca: lo avisa loadPhasePrompt.
+export const MARCADOR_RANURA = /^[ \t]*<!--[ \t]*\/?ranura(?:[ \t]*:[ \t]*[\w-]+)?[ \t]*-->[ \t]*\r?$\n?/gm;
+export function quitarMarcadores(texto) {
+    return texto.replace(MARCADOR_RANURA, "");
+}
+// Lo que parece un marcador de ranura y sobrevivió a quitarMarcadores: mal escrito (con acento,
+// en mayúsculas, con texto detrás). Llegaría tal cual al modelo, así que queda en el log.
+const RESTO_DE_MARCADOR = /<!--[^\n]*?ranura/i;
+function entregable(texto, archivo) {
+    const limpio = quitarMarcadores(texto);
+    if (RESTO_DE_MARCADOR.test(limpio)) {
+        console.error(`[orquestador] ${archivo} tiene un marcador de ranura que no se reconoce: llega tal cual al modelo.`);
+    }
+    return limpio.trim();
+}
+// La subcarpeta de recibos acaba dentro de un file_name, así que tiene que ser un solo segmento
+// portable, y visible: write_central_doc no escribe en segmentos que empiezan por punto. Un valor
+// inválido no tumba la fase: se ignora y queda en el log.
+function leerRecibos(valor, archivo) {
+    if (!valor)
+        return undefined;
+    try {
+        const segmento = validarSegmento(valor, "recibos");
+        if (segmento.startsWith("."))
+            throw new Error("no puede empezar por punto.");
+        return segmento;
+    }
+    catch (error) {
+        console.error(`[orquestador] Se ignora el frontmatter recibos de ${archivo}: ${error.message}`);
+        return undefined;
+    }
+}
+// Una subcarpeta de recibos con el nombre de un documento rompe el flujo: si se llama como el
+// documento de la fase, la carpeta hace que la fase cuente como cerrada al primer recibo. Se
+// comprueba al final, con las fases de todas las capas ya resueltas.
+function descartarRecibosQueChocan(phases) {
+    const documentos = new Set();
+    for (const datos of phases.values()) {
+        for (const nombre of [datos.documento, datos.documentoInicial]) {
+            if (nombre)
+                documentos.add(claveDeNombre(nombre));
+        }
+    }
+    for (const datos of phases.values()) {
+        if (datos.recibos && documentos.has(claveDeNombre(datos.recibos))) {
+            console.error(`[orquestador] Se ignora el frontmatter recibos de ${datos.file}: ` +
+                `"${datos.recibos}" es el nombre de un documento de fase.`);
+            datos.recibos = undefined;
+        }
+    }
+}
 export function parsePhaseFile(fullPath) {
-    const crudo = fs.readFileSync(fullPath, "utf-8");
+    const crudo = aLF(fs.readFileSync(fullPath, "utf-8"));
     const encontrada = crudo.match(PHASE_FRONTMATTER);
     if (!encontrada)
         return { meta: {}, cuerpo: crudo };
@@ -71,11 +136,13 @@ export function discoverPhases(capas = promptsLayers()) {
                 title: readPhaseTitle(cuerpo, file),
                 documento: meta.documento || undefined,
                 documentoInicial: meta.documento_inicial || undefined,
+                recibos: leerRecibos(meta.recibos, fullPath),
             });
         }
         for (const [numero, datos] of deEstaCapa)
             phases.set(numero, datos);
     }
+    descartarRecibosQueChocan(phases);
     return phases;
 }
 // El título es el primer encabezado "# ..." del cuerpo; si no lo hay, se deriva del nombre
@@ -107,9 +174,9 @@ export function loadPhasePrompt(phase, capas = promptsLayers()) {
     const parts = [];
     const globales = resolveGlobalRules(capas);
     if (globales) {
-        parts.push(fs.readFileSync(globales, "utf-8").trim());
+        parts.push(entregable(aLF(fs.readFileSync(globales, "utf-8")), globales));
     }
-    parts.push(parsePhaseFile(entry.file).cuerpo.trim());
+    parts.push(entregable(parsePhaseFile(entry.file).cuerpo, entry.file));
     const archivos = describePhaseFiles(available, phase);
     if (archivos)
         parts.push(archivos);
@@ -128,7 +195,8 @@ function resolveGlobalRules(capas) {
     return null;
 }
 // Bloque que se añade al final del prompt con los nombres exactos de los documentos: el que
-// produce esta fase y los de las anteriores, que son los que hay que leer. Va aquí y no en el
+// produce esta fase y los de las anteriores, que son los que hay que leer, y la subcarpeta de
+// recibos de la fase que la declare. Va aquí y no en el
 // comando del cliente para que el nombre viva en un solo sitio; así afinar un prompt no obliga
 // a editar además un comando en cada dispositivo.
 export function describePhaseFiles(available, phase) {
@@ -136,7 +204,10 @@ export function describePhaseFiles(available, phase) {
     const previos = [...available.entries()]
         .filter(([numero, datos]) => numero < phase && datos.documento)
         .sort((a, b) => a[0] - b[0])
-        .map(([numero, datos]) => `- Fase ${numero}: \`${datos.documento}\``);
+        .map(([numero, datos]) => {
+        const recibos = datos.recibos ? ` (recibos de lote en \`${datos.recibos}/\`)` : "";
+        return `- Fase ${numero}: \`${datos.documento}\`${recibos}`;
+    });
     if (!propio && previos.length === 0)
         return "";
     const lineas = ["## ARCHIVOS DE ESTA TAREA (nombres exactos)"];
@@ -146,6 +217,12 @@ export function describePhaseFiles(available, phase) {
     if (propio) {
         lineas.push("", `El documento de esta fase se llama exactamente \`${propio}\`. Guárdalo con ` +
             "`write_central_doc` en la carpeta de la tarea activa, con ese nombre y sin cambiarlo.");
+        const recibos = available.get(phase)?.recibos;
+        if (recibos) {
+            lineas.push("", `Los recibos de lote van en la subcarpeta \`${recibos}/\`, uno por lote: ` +
+                `\`${recibos}/L01 - <slug>.md\`. Con un solo lote no hay subcarpeta: el recibo es el ` +
+                "documento de esta fase.");
+        }
     }
     else {
         lineas.push("", "Esta fase no deja documento en la Documentación Central: su salida va en el chat.");

package/build/schemas.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+export declare const startTaskShape: {
+    project: z.ZodString;
+    task_name: z.ZodString;
+    initial_context: z.ZodString;
+    crear_proyecto: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+};
+export declare const getPhasePromptShape: {
+    phase: z.ZodNumber;
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const getActiveTaskShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const listTasksShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const switchTaskShape: {
+    project: z.ZodString;
+    task_name: z.ZodString;
+};
+export declare const readCentralDocShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const writeCentralDocShape: {
+    content: z.ZodString;
+    force: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const readCrossRepoShape: {
+    repo_name: z.ZodString;
+    file_path: z.ZodString;
+};
+declare const SHAPES: {
+    start_task: {
+        project: z.ZodString;
+        task_name: z.ZodString;
+        initial_context: z.ZodString;
+        crear_proyecto: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    };
+    get_phase_prompt: {
+        phase: z.ZodNumber;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    get_active_task: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    list_tasks: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    switch_task: {
+        project: z.ZodString;
+        task_name: z.ZodString;
+    };
+    read_central_doc: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    write_central_doc: {
+        content: z.ZodString;
+        force: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    read_cross_repo: {
+        repo_name: z.ZodString;
+        file_path: z.ZodString;
+    };
+};
+type NombreTool = keyof typeof SHAPES;
+type SinNulos<T> = {
+    [K in keyof T]: Exclude<T[K], null>;
+};
+export type LlamadaValidada = {
+    [K in NombreTool]: {
+        tool: K;
+        args: SinNulos<z.output<z.ZodObject<(typeof SHAPES)[K]>>>;
+    };
+}[NombreTool];
+export declare function validarLlamada(tool: string, args: unknown): LlamadaValidada;
+export {};
+//# sourceMappingURL=schemas.d.ts.map

package/build/schemas.js

@@ -0,0 +1,108 @@
+// Los argumentos de cada tool, declarados una sola vez con zod.
+//
+// Antes cada tool leía sus argumentos con String(args?.x), que no valida nada: sin task_name,
+// String(undefined) creaba la tarea "undefined/" y la dejaba activa. Ahora todo pasa por aquí
+// antes de usarse, y el error nombra el campo.
+//
+// Se exportan shapes (los campos sueltos) y no z.object(...): es lo que recibe registerTool
+// del SDK, al que se pasarán tal cual en la migración a McpServer (Etapa 2).
+//
+// Los opcionales son .nullish() y null cuenta como ausente: algunos clientes con modelos en
+// modo estricto mandan null en todo campo opcional. Un número en texto (phase: "3") no se
+// convierte: se rechaza con un mensaje que dice qué se espera. Es raro, el modelo lo corrige
+// al primer intento, y convertirlo complicaría el JSON Schema que se generará desde aquí.
+import { z } from "zod";
+export const startTaskShape = {
+    project: z.string().trim().min(1, "Falta `project`."),
+    task_name: z.string().min(1, "Falta `task_name`."),
+    initial_context: z.string().min(1, "Falta `initial_context`."),
+    crear_proyecto: z.boolean().nullish(),
+};
+export const getPhasePromptShape = {
+    phase: z.number().int(),
+    project: z.string().nullish(),
+    task_name: z.string().nullish(),
+};
+export const getActiveTaskShape = {
+    project: z.string().nullish(),
+};
+export const listTasksShape = {
+    project: z.string().nullish(),
+};
+export const switchTaskShape = {
+    project: z.string().trim().min(1, "Falta `project`."),
+    task_name: z.string().min(1, "Falta `task_name`."),
+};
+// Los cuatro son opcionales por separado: qué combinación vale lo decide resolveDocPath.
+export const readCentralDocShape = {
+    project: z.string().nullish(),
+    task_name: z.string().nullish(),
+    file_name: z.string().nullish(),
+    file_path: z.string().nullish(),
+};
+export const writeCentralDocShape = {
+    ...readCentralDocShape,
+    content: z.string(),
+    // Solo con confirmación explícita del usuario en el chat. Permite reescribir un documento
+    // congelado o el contexto inicial.
+    force: z.boolean().nullish(),
+};
+export const readCrossRepoShape = {
+    repo_name: z.string().min(1, "Falta `repo_name`."),
+    file_path: z.string().min(1, "Falta `file_path`."),
+};
+const SHAPES = {
+    start_task: startTaskShape,
+    get_phase_prompt: getPhasePromptShape,
+    get_active_task: getActiveTaskShape,
+    list_tasks: listTasksShape,
+    switch_task: switchTaskShape,
+    read_central_doc: readCentralDocShape,
+    write_central_doc: writeCentralDocShape,
+    read_cross_repo: readCrossRepoShape,
+};
+// Lo que se espera de cada tipo, dicho como se le diría al modelo para que corrija la llamada.
+// El único número es `phase`, de ahí el ejemplo.
+const TIPOS = {
+    string: "un texto",
+    number: "un número, por ejemplo 3",
+    int: "un número entero, por ejemplo 3",
+    boolean: "true o false",
+    object: "un objeto",
+};
+function describirProblema(issue, recibidos) {
+    const campo = issue.path.map(String).join(".");
+    if (!campo)
+        return "los argumentos tienen que ser un objeto.";
+    const nombre = `\`${campo}\``;
+    // null también es "falta": en un opcional se tolera, en un obligatorio es lo mismo que no venir.
+    if (issue.code === "invalid_type") {
+        return recibidos[campo] == null
+            ? `Falta ${nombre}.`
+            : `${nombre} debe ser ${TIPOS[issue.expected] ?? issue.expected}.`;
+    }
+    // Los mínimos llevan su mensaje en español en el propio shape ("Falta `task_name`.").
+    if (issue.code === "too_small")
+        return issue.message;
+    // Los máximos no: el único que puede saltar es el del entero seguro de `phase`.
+    if (issue.code === "too_big")
+        return `${nombre} es demasiado grande.`;
+    return `${nombre}: ${issue.message}.`;
+}
+export function validarLlamada(tool, args) {
+    if (!Object.hasOwn(SHAPES, tool)) {
+        throw new Error(`Unknown tool: ${tool}`);
+    }
+    const resultado = z.object(SHAPES[tool]).safeParse(args ?? {});
+    if (!resultado.success) {
+        const recibidos = (args && typeof args === "object" ? args : {});
+        const problemas = resultado.error.issues.map((issue) => describirProblema(issue, recibidos));
+        throw new Error(`Argumentos no válidos. ${problemas.join(" ")}`);
+    }
+    // null cuenta como ausente: se quita aquí, una vez, para que ninguna tool tenga que
+    // distinguir entre un campo que no vino y uno que vino vacío.
+    const sinNulos = Object.fromEntries(Object.entries(resultado.data).filter(([, valor]) => valor !== null));
+    // El cast es seguro: los datos los acaba de producir el shape de esta misma tool.
+    return { tool, args: sinNulos };
+}
+//# sourceMappingURL=schemas.js.map

package/build/tasks.d.ts

@@ -12,6 +12,7 @@ export type EstadoTarea = {
     ultimoCambio: number | null;
 };
 export declare function estadoDeTarea(taskName: string, folderPath: string, phases: Map<number, PhaseFile>): EstadoTarea;
+export declare function motivoDeProteccion(carpetaTarea: string, relativo: string, phases: Map<number, PhaseFile>, contextoInicial: string): string | null;
 export declare function describeEstado(estado: EstadoTarea, phases: Map<number, PhaseFile>): string;
 export declare function listarTareas(carpetaProyecto: string, phases: Map<number, PhaseFile>): EstadoTarea[];
 export type TareaActiva = {
@@ -28,9 +29,12 @@ export type Salto = {
     }[];
 };
 export declare function detectarSalto(fasePedida: number, estado: EstadoTarea, phases: Map<number, PhaseFile>): Salto | null;
-export declare function avisoDeCompuerta(fasePedida: number, phases: Map<number, PhaseFile>, opciones?: {
+export type OpcionesDeTarea = {
     project?: string;
     taskName?: string;
-}): string | null;
+};
+export declare function tareaDelPrompt(phases: Map<number, PhaseFile>, opciones?: OpcionesDeTarea): EstadoTarea | "ambigua" | null;
+export declare function avisoDeCompuerta(fasePedida: number, phases: Map<number, PhaseFile>, opciones?: OpcionesDeTarea): string | null;
+export declare function bloqueDeRecibos(fasePedida: number, estado: EstadoTarea, phases: Map<number, PhaseFile>): string | null;
 export declare function avisoDeSalto(salto: Salto, taskName: string, phases: Map<number, PhaseFile>): string;
 //# sourceMappingURL=tasks.d.ts.map

package/build/tasks.js

@@ -14,7 +14,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { MODULE_DIR, stateDir, stateFile } from "./config.js";
-import { findProjectFolder, requireProjectFolder, tasksRootPath } from "./paths.js";
+import { claveDeNombre, findProjectFolder, requireProjectFolder, tasksRootPath } from "./paths.js";
 export function leerPunteros() {
     const archivo = stateFile();
     if (!fs.existsSync(archivo))
@@ -120,6 +120,63 @@ export function estadoDeTarea(taskName, folderPath, phases) {
         ultimoCambio,
     };
 }
+// ─── Documentos congelados ──────────────────────────────────────────────────
+// Un documento de fase se congela en cuanto una fase posterior está presente: reescribirlo
+// después cambiaría la base sobre la que esa fase ya trabajó, sin que nada lo avise. Se puede
+// reescribir con force, que el modelo solo usa con la confirmación explícita del usuario.
+//
+// Una fase está presente si existe su documento, o si declara recibos y su subcarpeta tiene al
+// menos un .md: con varios lotes, la Fase 4 está en curso mucho antes de escribir su documento.
+function presenciaDeFase(carpetaTarea, datos) {
+    if (datos.documento && fs.existsSync(path.join(carpetaTarea, datos.documento))) {
+        return `existe \`${datos.documento}\``;
+    }
+    if (datos.recibos) {
+        const subcarpeta = path.join(carpetaTarea, datos.recibos);
+        const entradas = fs.existsSync(subcarpeta) ? fs.readdirSync(subcarpeta, { withFileTypes: true }) : [];
+        if (entradas.some((entrada) => entrada.isFile() && entrada.name.toLowerCase().endsWith(".md"))) {
+            return `existen recibos en \`${datos.recibos}/\``;
+        }
+    }
+    return null;
+}
+// Los nombres protegidos se comparan por su clave (claveDeNombre) y no como texto exacto. Sin
+// ella un archivo nuevo esquivaba la protección: `00 - contexto inicial.md` o
+// `04 - ejecución/L01 - x.md` en Windows y macOS, donde abren lo mismo que el nombre protegido, y
+// en cualquier sistema un nombre en Unicode NFD, que se ve igual que el documento. En Linux, un
+// nombre que solo difiere en mayúsculas de un documento protegido también pide force; no hace
+// falta nunca.
+const clave = claveDeNombre;
+// Devuelve el motivo del rechazo, o null si se puede escribir sin force. `relativo` es la ruta
+// dentro de la tarea, con "/" como separador (la de ubicarEnTarea).
+export function motivoDeProteccion(carpetaTarea, relativo, phases, contextoInicial) {
+    const buscado = clave(relativo);
+    // Ni siquiera para crearlo: solo start_task lo escribe.
+    if (buscado === clave(contextoInicial)) {
+        return "El contexto inicial está siempre protegido: es el único documento que no se puede regenerar leyendo el código.";
+    }
+    const fases = [...phases.entries()].sort((a, b) => a[0] - b[0]);
+    const propia = fases.find(([, datos]) => (datos.documento && clave(datos.documento) === buscado) ||
+        (datos.recibos && buscado.startsWith(`${clave(datos.recibos)}/`)));
+    if (!propia)
+        return null; // no es un archivo de fase
+    // Crear un documento nunca pisa nada, ni siquiera cuando rellena un hueco. Se mira el nombre
+    // declarado y no el que llegó, que puede venir en otras mayúsculas. Un recibo nuevo sí se
+    // congela: con la Fase 5 presente, la ejecución ya se auditó.
+    const [numero, datos] = propia;
+    const esDocumento = datos.documento !== undefined && clave(datos.documento) === buscado;
+    if (esDocumento && !fs.existsSync(path.join(carpetaTarea, datos.documento)))
+        return null;
+    for (const [posterior, datosPosterior] of fases) {
+        if (posterior <= numero)
+            continue;
+        const presencia = presenciaDeFase(carpetaTarea, datosPosterior);
+        if (presencia) {
+            return `\`${relativo}\` está congelado: la Fase ${posterior} ya está en curso o cerrada (${presencia}).`;
+        }
+    }
+    return null;
+}
 // Frase corta para el chat. Se le pasa el mapa de fases para poder nombrar la fase siguiente
 // con su título real en vez de un número suelto.
 export function describeEstado(estado, phases) {
@@ -140,13 +197,15 @@ export function describeEstado(estado, phases) {
 // ─── Listado ────────────────────────────────────────────────────────────────
 // Las tareas son las carpetas que hay bajo la subcarpeta de tareas del proyecto. Se listan
 // del disco, así que también aparecen las que alguien creó a mano sin pasar por start_task.
+// Las carpetas con punto no son tareas: con la subcarpeta vacía, .phase-gate/ o .git/ del
+// proyecto cuelgan del mismo sitio que ellas.
 export function listarTareas(carpetaProyecto, phases) {
     const raiz = tasksRootPath(carpetaProyecto);
     if (!fs.existsSync(raiz))
         return [];
     return fs
         .readdirSync(raiz, { withFileTypes: true })
-        .filter((entrada) => entrada.isDirectory())
+        .filter((entrada) => entrada.isDirectory() && !entrada.name.startsWith("."))
         .map((entrada) => estadoDeTarea(entrada.name, path.join(raiz, entrada.name), phases))
         .sort((a, b) => (b.ultimoCambio ?? 0) - (a.ultimoCambio ?? 0));
 }
@@ -181,34 +240,20 @@ export function detectarSalto(fasePedida, estado, phases) {
         .map(([numero, datos]) => ({ fase: numero, documento: datos.documento }));
     return { fasePedida, siguienteFase: estado.siguienteFase, faltan };
 }
-// El aviso va al principio del prompt, no en un campo aparte, porque lo tiene que leer el
-// modelo como parte de sus instrucciones. Avisa y entrega igual: bloquear estorbaría el día
-// que haga falta saltarse una fase a propósito, y hoy no hay dato de cuántas veces pasa.
-// Resuelve de qué tarea se está hablando y devuelve el aviso, o null si no hay nada que decir.
-//
-// Quién hace este trabajo es la decisión de diseño de la compuerta: lo hace el servidor, no el
-// modelo. El puntero por proyecto ya está guardado aquí, así que pedírselo al modelo sería
-// trabajo de más y una vía de fricción — si no lograra deducirlo acabaría preguntándoselo al
-// usuario en cada fase, y escribir "/f4" para que te contesten "¿en qué tarea estamos?" es peor
-// que no tener compuerta.
-//
-// `project` y `taskName` son solo anulación manual, para comprobar contra una tarea distinta de
-// la activa. Sin ellos se usa el puntero; y cuando de verdad no se puede saber se dice en voz
-// alta, en vez de callar como si todo estuviera en orden.
-export function avisoDeCompuerta(fasePedida, phases, opciones = {}) {
+// La tarea de la que habla una llamada a get_phase_prompt: la indicada, o la activa del proyecto.
+// Sin proyecto solo se puede resolver si hay exactamente un candidato con tarea activa; con
+// varios, se devuelve "ambigua" para que quien llama lo diga en vez de callar.
+export function tareaDelPrompt(phases, opciones = {}) {
     let carpetaProyecto;
     if (opciones.project) {
         carpetaProyecto = requireProjectFolder(opciones.project);
     }
     else {
-        // Sin proyecto solo se puede resolver si hay exactamente un candidato con tarea activa.
         const conPuntero = Object.keys(leerPunteros());
         if (conPuntero.length === 0)
             return null; // Nada empezado: no hay nada que comprobar.
-        if (conPuntero.length > 1) {
-            return ("> Nota: no se comprobó la compuerta de fase porque no se indicó `project` y hay varios " +
-                "proyectos con tarea activa. Pasa `project` para que se compruebe.");
-        }
+        if (conPuntero.length > 1)
+            return "ambigua";
         const encontrada = findProjectFolder(conPuntero[0]);
         if (!encontrada)
             return null; // Puntero de un proyecto que ya no existe: se ignora.
@@ -217,11 +262,48 @@ export function avisoDeCompuerta(fasePedida, phases, opciones = {}) {
     const estado = opciones.taskName
         ? listarTareas(carpetaProyecto, phases).find((tarea) => tarea.taskName === opciones.taskName)
         : tareaActiva(carpetaProyecto, phases)?.estado;
+    return estado ?? null; // null: proyecto sin tareas, o un nombre de tarea que no existe.
+}
+export function avisoDeCompuerta(fasePedida, phases, opciones = {}) {
+    const estado = tareaDelPrompt(phases, opciones);
+    if (estado === "ambigua") {
+        return ("> Nota: no se comprobó la compuerta de fase porque no se indicó `project` y hay varios " +
+            "proyectos con tarea activa. Pasa `project` para que se compruebe.");
+    }
     if (!estado)
-        return null; // Proyecto sin tareas, o un nombre de tarea que no existe.
+        return null;
     const salto = detectarSalto(fasePedida, estado, phases);
     return salto ? avisoDeSalto(salto, estado.taskName, phases) : null;
 }
+// ─── Recibos que ya existen ─────────────────────────────────────────────────
+// Ninguna tool lista una carpeta, así que al retomar la Fase 4 en otro chat, o al auditar en la
+// Fase 5 sin índice, el modelo no tenía cómo saber qué recibos hay ni cómo se llaman sus slugs.
+// Se los da el servidor al final del prompt de la fase que los declara y de las posteriores.
+export function bloqueDeRecibos(fasePedida, estado, phases) {
+    const lineas = [];
+    for (const [numero, datos] of [...phases.entries()].sort((a, b) => a[0] - b[0])) {
+        if (!datos.recibos || numero > fasePedida)
+            continue;
+        const subcarpeta = path.join(estado.folderPath, datos.recibos);
+        if (!fs.existsSync(subcarpeta))
+            continue;
+        const recibos = fs
+            .readdirSync(subcarpeta, { withFileTypes: true })
+            .filter((entrada) => entrada.isFile() && entrada.name.toLowerCase().endsWith(".md"))
+            .map((entrada) => entrada.name)
+            .sort();
+        for (const recibo of recibos)
+            lineas.push(`- Fase ${numero}: \`${datos.recibos}/${recibo}\``);
+    }
+    if (lineas.length === 0)
+        return null;
+    return [
+        `## RECIBOS QUE YA EXISTEN EN LA TAREA "${estado.taskName}"`,
+        "",
+        "Léelos con `read_central_doc` usando estas rutas tal cual:",
+        ...lineas,
+    ].join("\n");
+}
 export function avisoDeSalto(salto, taskName, phases) {
     const titulo = phases.get(salto.siguienteFase)?.title;
     const vaEn = titulo ? `Fase ${salto.siguienteFase} (${titulo})` : `Fase ${salto.siguienteFase}`;

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "mcp-phase-gate",
-  "version": "2.0.0",
-  "description": "Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada una deje su documento en una documentación central.",
-  "main": "build/index.js",
-  "bin": {
-    "mcp-phase-gate": "build/index.js"
-  },
-  "files": [
-    "build",
-    "prompts",
-    "!build/**/*.map"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node build/index.js",
-    "dev": "ts-node src/index.ts",
-    "test": "tsc -p tsconfig.test.json && node --test \"build-test/test/**/*.test.js\"",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Montse2308/mcp-phase-gate.git"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "phase-gate",
-    "workflow",
-    "documentation",
-    "cursor",
-    "claude-code"
-  ],
-  "author": "Montserrat Ximena Hernández Gallegos",
-  "license": "MIT",
-  "type": "module",
-  "bugs": {
-    "url": "https://github.com/Montse2308/mcp-phase-gate/issues"
-  },
-  "homepage": "https://github.com/Montse2308/mcp-phase-gate#readme",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "dotenv": "^17.4.2"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^6.0.3"
-  }
-}
+{
+  "name": "mcp-phase-gate",
+  "version": "2.1.0",
+  "description": "Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada una deje su documento en una documentación central.",
+  "main": "build/index.js",
+  "bin": {
+    "mcp-phase-gate": "build/index.js"
+  },
+  "files": [
+    "build",
+    "prompts",
+    "!build/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "test": "tsc -p tsconfig.test.json && node --test \"build-test/test/**/*.test.js\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Montse2308/mcp-phase-gate.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "phase-gate",
+    "workflow",
+    "documentation",
+    "cursor",
+    "claude-code"
+  ],
+  "author": "Montserrat Ximena Hernández Gallegos",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/Montse2308/mcp-phase-gate/issues"
+  },
+  "homepage": "https://github.com/Montse2308/mcp-phase-gate#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}