mcp-phase-gate 2.0.1 → 2.1.0

package/README.es.md

@@ -32,7 +32,7 @@ flowchart TD
 
 Y entre una fase y otra hay una **compuerta**, que es lo que le da el nombre al servidor: si pides una fase saltándote la anterior, el servidor lo detecta y avisa ([ver abajo](#-la-compuerta-saltarse-una-fase-deja-de-ser-invisible)).
 
-En la fase 5 la IA solo lee. **Los commits y el PR los haces tú**, siempre.
+En la Fase 4 la IA hace el commit de cada lote solo con tu OK; nunca hace push ni abre el PR. En la Fase 5 solo lee.
 
 ## Para quién es
 
@@ -57,7 +57,10 @@ DOCUMENTACIÓN/
 │           ├── 01 - Análisis Técnico.md   ← Fase 1
 │           ├── 02 - Decisiones.md         ← Fase 2
 │           ├── 03 - Plan Técnico.md       ← Fase 3
-│           ├── 04 - Ejecución.md          ← Fase 4
+│           ├── 04 - Ejecución/            ← Fase 4, con más de un lote: un recibo por lote
+│           │   ├── L01 - <slug>.md
+│           │   └── L02 - <slug>.md
+│           ├── 04 - Ejecución.md          ← Fase 4: el recibo, o el índice de los recibos
 │           └── 05 - Auditoría.md          ← Fase 5
 ├── PROYECTO-B/
 │   └── Proyectos/
@@ -69,6 +72,8 @@ DOCUMENTACIÓN/
 
 `PROYECTO-A`, `PROYECTO-B` y `PROYECTO-C` son de ejemplo: tus proyectos son las carpetas que tú tengas ahí, con los nombres que tú les pongas. El nivel `Proyectos` es la subcarpeta de tareas, y su nombre también es configurable — ver `ORQUESTADOR_TASKS_SUBDIR` más abajo.
 
+**Lotes y recibos.** El plan de la Fase 3 parte el trabajo en lotes (`L01`, `L02`…): cada uno es un cambio que se revierte solo y deja la aplicación funcionando. La Fase 4 los ejecuta uno a la vez y cierra cada lote con un **recibo** corto (qué se hizo, qué se verificó, qué espera por ti) y un commit. Con un solo lote, el recibo es directamente `04 - Ejecución.md` y no hay subcarpeta, salvo que ese lote falle o se descarte: entonces su recibo va a `04 - Ejecución/` y la fase no se da por cerrada. Con varios, los recibos van en `04 - Ejecución/` y `04 - Ejecución.md` es el índice que se escribe al cerrar el último: hasta entonces la fase no aparece como terminada. Al pedir la Fase 4 o la 5, el servidor añade al prompt la lista de recibos que ya existen, para retomar en otro chat sin adivinar sus nombres.
+
 > El servidor arma esta ruta **automáticamente**. Tú (o el LLM) solo indican `project`, `task_name` y `file_name`; no hay que escribir la ruta completa a mano.
 
 ---
@@ -291,15 +296,15 @@ Lo que hace cada uno:
 | `/f1` | `start_task` + `get_phase_prompt(1)` | El de la Fase 1 |
 | `/f2` | `get_phase_prompt(2)`, lee el de la Fase 1 | El de la Fase 2, después de que respondas las preguntas |
 | `/f3` | `get_phase_prompt(3)`, lee los anteriores | El de la Fase 3 |
-| `/f4` | `get_phase_prompt(4)`, lee el plan | El de la Fase 4, corto y al final |
+| `/f4` | `get_phase_prompt(4)`, lee el plan | Un recibo por lote; el documento de la fase al cerrar |
 | `/f5` | `get_phase_prompt(5)` | El de la Fase 5: la auditoría y la descripción del PR, que además van en el chat |
 
 Ningún comando nombra un archivo: el nombre lo declara la cabecera del prompt de cada fase
 y `get_phase_prompt` se lo entrega al modelo.
 
-`/f1` y `/f5` esperan datos después del comando: `/f1` necesita project, task_name y el
-requerimiento completo; `/f5`, cuáles commits auditar. Los otros cuatro arrancan de
-`get_active_task`.
+`/f1` espera datos después del comando: project, task_name y el requerimiento completo.
+`/f5` acepta un rango de commits; si no le das ninguno, audita los que registran los recibos
+de la Fase 4, y solo si no hay recibos te pregunta. Los demás arrancan de `get_active_task`.
 
 **Dónde ponerlos según el cliente:**
 
@@ -338,6 +343,19 @@ Tres cosas que **no** hace, a propósito:
 
 ---
 
+## 🔒 Documentos protegidos
+
+Cada fase trabaja sobre los documentos de las anteriores, así que reescribir uno ya superado cambia en silencio la base de lo que vino después. Por eso `write_central_doc` se niega, **sin `force: true`**, a escribir:
+
+- **El contexto inicial** (`00 - Contexto Inicial.md`), siempre, incluso para crearlo. Solo `start_task` lo escribe sin `force`.
+- **El documento de una fase congelada.** Una fase se congela en cuanto existe el documento de una fase posterior, o en cuanto la Fase 4 tiene algún recibo en `04 - Ejecución/`. Los recibos cuentan como de la Fase 4: a ellos y a `04 - Ejecución.md` solo los congela la Fase 5.
+
+Crear un documento de fase que todavía no existe nunca se rechaza; un recibo nuevo sí, cuando la Fase 5 ya está presente. Los nombres se comparan sin distinguir mayúsculas y en la misma forma Unicode, así que escribirlos de otra manera no esquiva la protección. Si hace falta una corrección legítima —una errata en el análisis con las decisiones ya escritas—, el mensaje de rechazo explica cómo pedirla: la IA solo usa `force` con tu confirmación explícita en el chat, y la respuesta avisa de que el documento se sobrescribió (o se creó, si no existía).
+
+Además, `write_central_doc` solo escribe **dentro de la carpeta de una tarea que ya existe**: no crea carpetas sueltas en la Documentación.
+
+---
+
 ## 🛠 Tools Disponibles
 
 | Tool | Qué hace |
@@ -348,7 +366,7 @@ Tres cosas que **no** hace, a propósito:
 | `switch_task` | Cambia cuál es la tarea activa de un proyecto. **No toca ningún archivo**: es la forma correcta de retomar una tarea que ya existe. |
 | `get_phase_prompt` | Trae las reglas de comportamiento globales según la fase (1–5): 1 Descubrimiento, 2 Decisiones, 3 Plan Técnico, 4 Ejecución, 5 Auditoría / Pre-PR. El texto vive en `prompts/` (ver abajo). Comprueba de paso la **compuerta**: si pasas `project` y te saltaste una fase, el prompt llega con el aviso al principio. |
 | `read_central_doc` | Lee un archivo de la Documentación. **Recomendado:** pasar `project` + `task_name` + `file_name` (el servidor arma la ruta). También acepta `file_path` relativo. |
-| `write_central_doc` | Escribe/sobrescribe un archivo. Mismos parámetros que `read_central_doc` + `content`. |
+| `write_central_doc` | Escribe/sobrescribe un archivo dentro de la carpeta de una tarea. Mismos parámetros que `read_central_doc` + `content`, y `force` para los [documentos protegidos](#-documentos-protegidos). |
 | `read_cross_repo` | Lee archivos de otros repos locales en tu carpeta de proyectos (ej. desde `repo-a` consultar cómo `repo-b` maneja un endpoint) sin cambiar de ventana. |
 
 ### Cómo el servidor arma las rutas
@@ -424,6 +442,7 @@ Tres detalles que importan:
 - **Se superpone por número de fase, no por nombre de archivo.** Tu `fase-2-a-mi-manera.md` pisa al `fase-2-decisiones.md` del paquete. No tienes que adivinar cómo se llama el original.
 - **También sirve para añadir.** Un `fase-6-despliegue.md` en tu carpeta crea la fase 6, sin tocar nada más.
 - **Tu `global-rules.md` sustituye al del paquete, no se suma.** Concatenar dos juegos de reglas hace imposible saber de qué archivo salió la instrucción que estorbó, justo cuando necesitas saberlo. Si quieres las de fábrica y algo más, cópialas y añade.
+  **Ojo:** las de fábrica traen las secciones `EVIDENCIA`, `BASE DE CADA DECISIÓN` y `PENDIENTES HEREDADOS`, que las fases citan. Un `global-rules.md` propio que no las incluya deja a las fases citando reglas que no existen; cópialas a tu archivo.
 
 Por el camino `npx` esta es la **única** forma de personalizar: los prompts de fábrica viven dentro de `node_modules` y editarlos ahí no sirve, porque la siguiente instalación se los lleva.
 

package/README.md

@@ -34,7 +34,7 @@ flowchart TD
 
 And between one phase and the next there is a **gate**, which is what gives the server its name: ask for a phase while skipping the previous one and the server notices and warns you ([see below](#-the-gate-skipping-a-phase-stops-being-invisible)).
 
-In phase 5 the AI only reads. **You always make the commits and open the PR.**
+In phase 4 the AI commits each batch only with your OK; it never pushes or opens the PR. In phase 5 it only reads.
 
 ## Who it's for
 
@@ -59,7 +59,10 @@ DOCUMENTATION/
 │           ├── 01 - Análisis Técnico.md   ← Phase 1
 │           ├── 02 - Decisiones.md         ← Phase 2
 │           ├── 03 - Plan Técnico.md       ← Phase 3
-│           ├── 04 - Ejecución.md          ← Phase 4
+│           ├── 04 - Ejecución/            ← Phase 4, with more than one batch: one receipt each
+│           │   ├── L01 - <slug>.md
+│           │   └── L02 - <slug>.md
+│           ├── 04 - Ejecución.md          ← Phase 4: the receipt, or the index of receipts
 │           └── 05 - Auditoría.md          ← Phase 5
 ├── PROJECT-B/
 │   └── Proyectos/
@@ -71,6 +74,8 @@ DOCUMENTATION/
 
 The `Proyectos` level is the tasks subfolder, and its name is configurable — see `ORQUESTADOR_TASKS_SUBDIR` below. The document names come from the phase prompts, which is why they are in Spanish by default.
 
+**Batches and receipts.** The phase 3 plan splits the work into batches (`L01`, `L02`…): each one is a change that can be reverted on its own and leaves the application working. Phase 4 runs them one at a time and closes each batch with a short **receipt** (what was done, what was verified, what is waiting for you) and a commit. With a single batch, the receipt is `04 - Ejecución.md` itself and there is no subfolder, unless that batch fails or is discarded: then its receipt goes in `04 - Ejecución/` and the phase isn't marked as closed. With several, the receipts go in `04 - Ejecución/` and `04 - Ejecución.md` is the index written when the last one closes: until then the phase doesn't show as finished. When you ask for phase 4 or 5, the server appends the list of existing receipts to the prompt, so a new chat can pick up without guessing their names.
+
 > The server builds this path **automatically**. You (or the LLM) only supply `project`, `task_name` and `file_name`; nobody has to type a full path.
 
 ---
@@ -287,12 +292,12 @@ You invoke them by typing `/f1`, `/f2`, etc. in the chat. **They are orchestrati
 | `/f1` | `start_task` + `get_phase_prompt(1)` | Phase 1's |
 | `/f2` | `get_phase_prompt(2)`, reads phase 1's | Phase 2's, after you answer the questions |
 | `/f3` | `get_phase_prompt(3)`, reads the previous ones | Phase 3's |
-| `/f4` | `get_phase_prompt(4)`, reads the plan | Phase 4's, short and at the end |
+| `/f4` | `get_phase_prompt(4)`, reads the plan | One receipt per batch; the phase document when it closes |
 | `/f5` | `get_phase_prompt(5)` | Phase 5's: the audit and the PR description, which also go in the chat |
 
 No command names a file: the name is declared in each phase prompt's header and `get_phase_prompt` hands it to the model.
 
-`/f1` and `/f5` expect data after the command: `/f1` needs project, task_name and the full requirement; `/f5`, which commits to audit. The other four start from `get_active_task`.
+`/f1` expects data after the command: project, task_name and the full requirement. `/f5` accepts a commit range; without one it audits the commits recorded in the phase 4 receipts, and only asks if there are no receipts. The rest start from `get_active_task`.
 
 **Where to put them, per client:**
 
@@ -329,6 +334,19 @@ Three things it deliberately does **not** do:
 
 ---
 
+## 🔒 Protected documents
+
+Each phase works on top of the previous phases' documents, so rewriting one that's already been passed silently changes the basis of everything that came after. That's why `write_central_doc` refuses, **without `force: true`**, to write:
+
+- **The initial context** (`00 - Contexto Inicial.md`), always, even to create it. Only `start_task` writes it without `force`.
+- **The document of a frozen phase.** A phase freezes as soon as a later phase's document exists, or as soon as phase 4 has any receipt in `04 - Ejecución/`. Receipts count as phase 4: they and `04 - Ejecución.md` are frozen only by phase 5.
+
+Creating a phase document that doesn't exist yet is never refused; a new receipt is, once phase 5 is present. Names are compared ignoring case and in the same Unicode form, so spelling them differently doesn't get around the protection. If a legitimate fix is needed — a typo in the analysis when the decisions are already written — the refusal message explains how to ask for it: the AI only uses `force` with your explicit confirmation in the chat, and the response warns that the document was overwritten (or created, if it didn't exist).
+
+On top of that, `write_central_doc` only writes **inside the folder of a task that already exists**: it doesn't create stray folders in the documentation.
+
+---
+
 ## 🛠 Available tools
 
 | Tool | What it does |
@@ -339,7 +357,7 @@ Three things it deliberately does **not** do:
 | `switch_task` | Changes which task is active for a project. **Touches no files**: it's the correct way to resume an existing task. |
 | `get_phase_prompt` | Returns the behaviour rules for a phase (1–5), with the global rules prepended and the exact document filenames appended. The text lives in `prompts/`. It also checks the **gate**: pass `project` and, if you skipped a phase, the prompt arrives with the warning on top. |
 | `read_central_doc` | Reads a file from the central documentation. **Recommended:** pass `project` + `task_name` + `file_name` and let the server build the path. It also accepts a relative `file_path`. |
-| `write_central_doc` | Writes/overwrites a file. Same parameters as `read_central_doc` plus `content`. |
+| `write_central_doc` | Writes/overwrites a file inside a task folder. Same parameters as `read_central_doc` plus `content`, and `force` for [protected documents](#-protected-documents). |
 | `read_cross_repo` | Reads files from your other local repos, so you can check how another codebase solved something without switching windows. |
 
 ### How the server builds paths
@@ -411,6 +429,7 @@ Three details that matter:
 - **Layering is by phase number, not by filename.** Your `fase-2-my-way.md` overrides the package's `fase-2-decisiones.md`. You don't have to guess the original's name.
 - **It also adds.** A `fase-6-deployment.md` in your folder creates phase 6, nothing else needed.
 - **Your `global-rules.md` replaces the packaged one, it doesn't stack.** Concatenating two rule sets makes it impossible to tell which file an unwanted instruction came from, exactly when you need to know. If you want the packaged rules plus extras, copy them and add.
+  **Watch out:** the packaged rules include the `EVIDENCIA`, `BASE DE CADA DECISIÓN` and `PENDIENTES HEREDADOS` sections, which the phases refer to. A `global-rules.md` of your own without them leaves the phases pointing at rules that don't exist; copy them into your file.
 
 On the `npx` route this is the **only** way to customise: the packaged prompts live inside `node_modules`, where editing them achieves nothing because the next install wipes them.
 

package/build/index.js

@@ -11,9 +11,9 @@ 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, estaDentroReal, findProjectFolder, leerTextoAcotado, requireProjectFolder, resolveDocPath, resolveRepoPath, taskFolderPath, validarSegmento, } 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,
@@ -116,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"],
                 },
@@ -159,9 +160,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 // 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);
@@ -194,18 +197,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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(), {
-                    ...(project ? { project } : {}),
-                    ...(task_name ? { taskName: 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 (llamada.tool === "get_active_task") {
@@ -298,10 +306,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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 (llamada.tool === "read_cross_repo") {

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;
@@ -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

@@ -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;

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

@@ -28,6 +28,7 @@ export declare const readCentralDocShape: {
 };
 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>>;
@@ -67,6 +68,7 @@ declare const SHAPES: {
     };
     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>>;

package/build/schemas.js

@@ -43,6 +43,9 @@ export const readCentralDocShape = {
 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`."),

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