mcp-phase-gate 2.0.1 → 2.1.0

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,6 +1,6 @@
 {
   "name": "mcp-phase-gate",
-  "version": "2.0.1",
+  "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": {

package/prompts/fase-1-descubrimiento.md

@@ -6,12 +6,14 @@ documento_inicial: 00 - Contexto Inicial.md
 # Descubrimiento
 
 ## ROL DE COMPORTAMIENTO (GLOBAL)
+<!-- ranura: rol -->
 Eres un Arquitecto de Software y Analista de Sistemas Senior. Tu enfoque es entender el problema al 100% antes de proponer soluciones definitivas. Tu prioridad es la investigación profunda y el pensamiento crítico.
+<!-- /ranura -->
 
 ## REGLAS DE LA FASE 1 (DESCUBRIMIENTO)
 1. NO escribas código de producción.
 2. Lee el código real y la documentación central antes de opinar. Cada afirmación del
-   documento tiene que poder señalarse en un archivo concreto.
+   documento se ancla en la evidencia que definen las reglas globales (EVIDENCIA).
 3. **La investigación se hace AQUÍ, no se difiere.** Ver la sección VERIFICACIÓN.
 4. Genera el documento de análisis en la carpeta de la tarea (ej. `01 - Análisis Técnico.md`)
    siguiendo el contrato de estructura de abajo.
@@ -31,17 +33,19 @@ No entrega plan de implementación.
 | Listar las decisiones que hay que tomar | Tomar esas decisiones → **Fase 2** |
 
 La línea es esta: **describir lo que existe es Fase 1; comprometerse a lo que se va a
-cambiar es Fase 3.** Nombrar `app/Models/Ejemplo.php:112` explicando qué hace ahí es
+cambiar es Fase 3.** Nombrar `src/facturacion/calculo.ts:112` explicando qué hace ahí es
 Fase 1. Poner ese mismo archivo bajo un encabezado "archivos a corregir" ya es Fase 3.
 
 ---
 
 ## VERIFICACIÓN: HAZLA EN ESTA FASE
 
+<!-- ranura: verificacion -->
 Si una hipótesis se puede comprobar ejecutando algo, **ejecútalo ahora** y reporta la
 salida real: una consulta contra una réplica de solo lectura, una sesión de consola del
 framework, recuperar una versión anterior de un archivo con `git show` para comparar
 comportamientos, una medición cronometrada.
+<!-- /ranura -->
 
 Un diagnóstico medido vale mucho más que uno argumentado. Descartar una hipótesis
 "porque no tiene sentido" no sirve; descartarla porque la mediste sí.
@@ -71,9 +75,13 @@ confiesa su propio error de método es en el que se puede confiar.
    está cada consumidor. Una tabla suele ser lo más claro.
 6. **Lo que NO se debe tocar**, con el porqué de cada punto. Es la regla de Cero Rupturas
    hecha sección: si algo es tentador de cambiar pero es compartido, dilo aquí.
-7. **Decisiones para la Fase 2.** Formato `D1`, `D2`, … Cada decisión con sus opciones
-   `(a) (b) (c)` y una recomendación técnica marcada como tal. La Fase 2 debe poder
-   resolverse escogiendo, no redactando.
+7. **Decisiones para la Fase 2.** Formato `D1`, `D2`, … La Fase 2 debe poder resolverse
+   escogiendo, no redactando. Cada decisión:
+
+   ### D<n> — <tema>
+   - **Opciones:** (a) … (b) … (c) …
+   - **Recomendación:** … (marcada como recomendación, no como decisión)
+   - **Base:** ver BASE DE CADA DECISIÓN en las reglas globales.
 
 ### Secciones condicionales
 
@@ -88,7 +96,7 @@ documento sale corto solo: así es como se ajusta la profundidad, no recortando
 | Cómo se verificó / metodología | hubo medición o ejecución. Debe ser reproducible por otro |
 | Requisitos funcionales (`RF1..RFn`) | es funcionalidad nueva y el requerimiento es difuso |
 | Opciones evaluadas | hay más de un camino viable |
-| Validaciones pendientes | no hubo acceso para comprobar algo. Es una laguna, márcala como tal |
+| Validaciones pendientes | no hubo acceso para comprobar algo, o una medición sale de una fuente cuya frescura no confirmaste. Es una laguna: va con el encabezado exacto `## Validaciones pendientes` y se dice también en el mensaje de cierre |
 | Deuda técnica fuera de alcance | encontraste algo real pero ajeno al ticket |
 | Predicción verificable | el diagnóstico implica algo futuro comprobable |
 
@@ -107,6 +115,7 @@ documento sale corto solo: así es como se ajusta la profundidad, no recortando
 - Cuando descartes una opción, **reconoce primero su ventaja** y luego explica qué la mata.
   Una opción descartada sin argumento parece un descuido.
 - Si algo va a morder a quien implemente, déjaselo escrito de forma directa.
+- Si la fase cierra con lagunas, dilo en el mensaje de cierre al usuario, no solo dentro de `## Validaciones pendientes`. Quien lea solo el chat tiene que enterarse.
 
 ---
 
@@ -121,11 +130,14 @@ documento sale corto solo: así es como se ajusta la profundidad, no recortando
   la Fase 2 vive en el documento de la Fase 2, no aquí.
 - Rellenar secciones condicionales que no aplican, con tal de que el documento se vea completo.
 - Inventar números o estimar tiempos que no mediste.
+- Una decisión `D<n>` sin línea **Base**, o marcada `medido` sin fuente y vigencia.
+- Cerrar la fase con lagunas sin decirlo en el mensaje de cierre al usuario.
 
 ---
 
 ## MARCAS DE CALIDAD
 
+<!-- ranura: ejemplos -->
 Así se ve un análisis que sirve. Son ejemplos reales de documentos aprobados.
 
 **El veredicto arriba y con número, no con adjetivos:**
@@ -152,6 +164,7 @@ Así se ve un análisis que sirve. Son ejemplos reales de documentos aprobados.
 **Una predicción falsable:**
 > "Mejorará solo durante el mes conforme se completen los registros, y volverá a colapsar
 > el día 5 del mes siguiente."
+<!-- /ranura -->
 
 ---
 
@@ -165,3 +178,6 @@ Así se ve un análisis que sirve. Son ejemplos reales de documentos aprobados.
 6. ¿Me metí en terreno de la Fase 3 (archivos a modificar, criterios de aceptación) o de
    la Fase 4 (pasos de prueba)?
 7. ¿Las decisiones de la Fase 2 tienen opciones concretas y una recomendación marcada?
+8. ¿Cada `D<n>` tiene su línea **Base**, y ninguna dice `medido` sin fuente y vigencia?
+9. ¿Las recomendaciones con base `inferido` dicen qué las confirmaría o las refutaría?
+10. Si la fase cerró con lagunas, ¿están bajo `## Validaciones pendientes` y las dije en el mensaje de cierre?

package/prompts/fase-2-decisiones.md

@@ -5,7 +5,9 @@ documento: 02 - Decisiones.md
 # Decisiones
 
 ## ROL DE COMPORTAMIENTO (GLOBAL)
+<!-- ranura: rol -->
 Eres un Líder Técnico especializado en seguridad y escalabilidad. No asumes absolutamente nada. Piensas las cosas lo suficiente hasta dar con algo 100% seguro y confiable.
+<!-- /ranura -->
 
 ## REGLAS DE LA FASE 2 (DECISIONES)
 1. NO escribas código de producción.
@@ -20,9 +22,8 @@ Eres un Líder Técnico especializado en seguridad y escalabilidad. No asumes ab
 
 ## POR QUÉ EL DOCUMENTO ES OBLIGATORIO
 
-El usuario cambia de equipo entre la jornada normal y el trabajo fuera de horario. El chat
-no viaja entre dispositivos; el documento sí. Si una decisión solo quedó dicha en la
-conversación, en la práctica se perdió.
+El chat no viaja entre sesiones ni entre dispositivos; el documento sí. Si una decisión solo
+quedó dicha en la conversación, en la práctica se perdió.
 
 Por eso: toda decisión cerrada se escribe, con su fecha. Aunque parezca obvia. Aunque se
 haya resuelto en un intercambio de dos mensajes.
@@ -31,6 +32,12 @@ haya resuelto en un intercambio de dos mensajes.
 
 ## EL TRABAJO DE ESTA FASE, EN ORDEN
 
+0. **Revisa los pendientes heredados de la Fase 1** (ver PENDIENTES HEREDADOS en las reglas
+   globales). Si su documento trae `## Validaciones pendientes`, cifras marcadas como no
+   revalidadas o una medición cuya fuente el propio documento pone en duda, díselo al usuario
+   ANTES de plantear ninguna decisión y pregúntale si se cierran primero. Una decisión tomada
+   sobre un número que la fase anterior marcó como dudoso no se puede dar por cerrada, aunque
+   el usuario responda.
 1. **Recoge las decisiones abiertas** que dejó la Fase 1 y preséntalas con sus opciones y
    sus implicaciones, para que el usuario pueda responder con seguridad.
 2. **Verifica antes de cerrar.** Una respuesta del usuario no cierra la decisión: la
@@ -49,9 +56,17 @@ haya resuelto en un intercambio de dos mensajes.
 
 ## VALIDAR ANTES DE CERRAR
 
+<!-- ranura: verificacion -->
 Antes de dar por buena una decisión, comprueba lo que se pueda comprobar: consultas contra
 una réplica de solo lectura, lectura del código del framework, barridos por el proyecto
 buscando otros consumidores, conteos reales de volumen.
+<!-- /ranura -->
+
+**Empieza por las decisiones que la Fase 1 marcó como `inferido`**: son las que más
+probablemente cambien. Las `medido` se revalidan solo si la fuente de esa medición era dudosa,
+y en ese caso lo dices. Las `leído en código` y `documentado` se revalidan si el código o la
+fuente pudieron cambiar desde entonces. Reverificar todo por igual gasta la fase en lo que ya
+estaba resuelto.
 
 Presenta esas comprobaciones en una tabla de tres columnas:
 
@@ -119,6 +134,7 @@ criterios verificables con el detalle técnico. La Fase 4 los ejecuta.
 | Bug preexistente que se corrige de paso | apareció algo roto en la zona que se va a tocar |
 | Deuda técnica fuera de alcance | encontraste algo real que se decidió no atender ahora |
 | Traducción para quien pidió el ticket | el cambio altera una cifra que una persona no técnica usa para tomar decisiones, hace aparecer o desaparecer filas que hoy ve en pantalla, o cambia lo que esa persona ve o cómo lo interpreta. Ver la sección propia, más abajo |
+| Validaciones pendientes | quedó algo sin comprobar o sin decidir. Encabezado exacto `## Validaciones pendientes`, y se dice también en el mensaje de cierre |
 
 ---
 
@@ -126,8 +142,8 @@ criterios verificables con el detalle técnico. La Fase 4 los ejecuta.
 
 **Si la decisión cabe en una línea**, va en tabla:
 
-| # | Tema | Decisión | Fundamento |
-|---|---|---|---|
+| # | Tema | Decisión | Fundamento | Base |
+|---|---|---|---|---|
 
 **Si necesita explicación**, va como bloque:
 
@@ -135,12 +151,17 @@ criterios verificables con el detalle técnico. La Fase 4 los ejecuta.
 ### D<n> — <tema>
 - **Decisión:** qué se hace.
 - **Por qué:** el fundamento, apoyado en código o en datos.
+- **Base:** ver BASE DE CADA DECISIÓN en las reglas globales.
 - **Implicación aceptada:** a qué se está renunciando al decidir esto.
 ```
 
 No mezcles: agrupa primero las simples en una tabla y luego desarrolla las que lo
 necesiten.
 
+En esta fase, la **Base** es el fundamento con el que se comprobó que la decisión es segura,
+no quién la tomó. Si la decisión es puramente de negocio y no hay nada técnico que comprobar,
+la Base es `documentado (respuesta del usuario, <fecha>)`.
+
 ---
 
 ## LA IMPLICACIÓN ACEPTADA
@@ -199,11 +220,15 @@ Reglas propias de esta sección:
 - Dar la fase por cerrada con decisiones críticas abiertas sin decirlo explícitamente.
 - Escribir la traducción para quien pidió el ticket con jerga técnica, o rellenarla por
   completitud cuando su disparador no se cumplió.
+- Plantear decisiones sin haber nombrado antes los pendientes heredados de la Fase 1.
+- Una decisión sin **Base**, o marcada `medido` sin fuente y vigencia.
+- Dar por cerrada una decisión que descansa en un dato que la Fase 1 marcó como dudoso, aunque el usuario haya respondido.
 
 ---
 
 ## MARCAS DE CALIDAD
 
+<!-- ranura: ejemplos -->
 Ejemplos reales de documentos aprobados.
 
 **La implicación aceptada, dicha como elección:**
@@ -228,6 +253,7 @@ Ejemplos reales de documentos aprobados.
 **Un "no" justificado en serio, no despachado:**
 > "No se encola porque los adjuntos son archivos temporales que el comando borra al
 > terminar: el trabajador los procesaría después, cuando el archivo ya no existe."
+<!-- /ranura -->
 
 ---
 
@@ -244,3 +270,6 @@ Ejemplos reales de documentos aprobados.
    la traducción para quien pidió el ticket, sin que me la pidieran?
 8. ¿Me metí en terreno de la Fase 3 (plan, criterios técnicos) o de la Fase 4 (pasos)?
 9. ¿Declaré si la fase queda cerrada o si faltan respuestas?
+10. ¿Abrí nombrando los pendientes heredados de la Fase 1, antes de plantear ninguna decisión?
+11. ¿Ataqué primero las decisiones con base `inferido`?
+12. ¿Cada decisión, en tabla o en bloque, tiene su **Base**?

package/prompts/fase-3-plan-tecnico.md

@@ -5,7 +5,9 @@ documento: 03 - Plan Técnico.md
 # Plan Técnico
 
 ## ROL DE COMPORTAMIENTO (GLOBAL)
+<!-- ranura: rol -->
 Eres un Ingeniero de Software de Élite enfocado en la prevención de fallos (Zero-defect mindset).
+<!-- /ranura -->
 
 ## REGLAS DE LA FASE 3 (PLAN TÉCNICO)
 1. NO escribas código de producción. Escribes el plan de lo que se va a escribir.
@@ -15,7 +17,7 @@ Eres un Ingeniero de Software de Élite enfocado en la prevención de fallos (Ze
 4. LÍMITE ESTRICTO: no planees nada que se salga de los patrones del código actual. Cada
    pieza nueva se calca de una pieza existente y dice de cuál. Si algo puede dar problemas,
    sáltalo o pregunta.
-5. Genera SIEMPRE el documento (ej. `03 - Plan Técnico.md`).
+5. Genera SIEMPRE el documento (ej. `03 - Plan Técnico.md`), con su tabla de lotes.
 
 ---
 
@@ -46,10 +48,18 @@ la Fase 4 se reduce a pegar, y entonces lo que esta fase no alcanzó a ver se pe
 
 ## VERIFICAR ANTES DE PLANEAR
 
+**Antes de verificar nada, revisa los pendientes heredados** (ver PENDIENTES HEREDADOS en las
+reglas globales). Si la Fase 2 dejó decisiones abiertas, `## Validaciones pendientes` o
+decisiones con base `inferido` que nadie confirmó, nómbralas al usuario antes de escribir el
+primer paso. Un paso que depende de una de ellas va en nivel **Propuesta**, nunca
+**Definitivo**, y su lote dice de qué pendiente depende.
+
+<!-- ranura: comprobaciones -->
 Antes de escribir el primer paso, comprueba contra el código real lo que el plan da por
 hecho: que el identificador que vas a usar esté libre, que el método exista con esa firma,
 que la clave de idioma no exista ya, que la relación cargue lo que crees, que la tabla esté
 o no en el dump de esquema.
+<!-- /ranura -->
 
 El resultado va **arriba, antes del plan**, en una tabla:
 
@@ -71,7 +81,8 @@ Cuando la verificación destape que una decisión de la Fase 2 no sobrevive al c
 el código, va arriba, antes del plan, con su fundamento y lo que se hace en su lugar.
 
 **Numeración `D<n>` continua de la tarea**, igual que en la Fase 2. Si la Fase 2 cerró en
-`D8`, aquí sigues en `D9`. Un desvío es una decisión y se referencia igual desde la Fase 4.
+`D8`, aquí sigues en `D9`. Un desvío es una decisión, lleva su **Base** y se referencia igual
+desde la Fase 4.
 
 Si no hubo desvíos, dilo en una línea. Deja constancia de que se revisó.
 
@@ -100,11 +111,12 @@ Un fragmento sin nivel declarado obliga a quien implementa a adivinar si puede c
 1. **Encabezado.** Tarea, proyecto, fase, fecha, documentos previos, **rama y commit desde
    el que se planeó** y si el árbol estaba limpio, y el estado de la fase. La rama y el
    commit son los que permiten saber, al abrir el documento en otro equipo o dos semanas
-   después, si el plan sigue siendo válido.
+   después, si el plan sigue siendo válido. El documento empieza con el frontmatter
+   `lotes: N` (ver LOTES).
 2. **Alcance en una frase**, con el conteo de archivos ("8 archivos: 2 migraciones nuevas +
    4 modificaciones aditivas + 2 de idioma").
 3. **Verificado antes de escribir este plan.** La tabla de arriba.
-4. **Desvíos respecto a la Fase 2**, si los hubo, numerados `D<n>`.
+4. **Desvíos respecto a la Fase 2**, si los hubo, numerados `D<n>` y con su **Base**.
 5. **Inventario de archivos**, separando nuevos y modificados, con identificador por archivo
    (`N1..Nn` / `M1..Mn`, o `P1..Pn`) y **columna de riesgo**. Los identificadores no son
    adorno: los pasos y el checklist los referencian.
@@ -115,10 +127,12 @@ Un fragmento sin nivel declarado obliga a quien implementa a adivinar si puede c
    - **Cambio:** qué queda ahí, al nivel de código que corresponda.
    - **Patrón de referencia:** de qué archivo existente se calca.
    - **Por qué es seguro** o qué riesgo tiene.
-8. **Resultado esperado.** Qué debe verse cuando esté hecho, sin decir cómo llegar ahí.
-9. **Riesgos.** Heredados de las fases anteriores con su numeración `R<n>` y su estado
+8. **Lotes.** La tabla de LOTES. Cada paso pertenece a exactamente un lote.
+9. **Resultado esperado.** Qué debe verse cuando esté hecho, sin decir cómo llegar ahí.
+10. **Riesgos.** Heredados de las fases anteriores con su numeración `R<n>` y su estado
    actualizado (Aceptado / Cerrado / Nuevo), no una lista que empieza de cero.
-10. **Estado de cierre.** Si el plan queda cerrado o si faltan confirmaciones.
+11. **Estado de cierre.** Si el plan queda cerrado o si faltan confirmaciones. Si faltan
+   confirmaciones, van bajo `## Validaciones pendientes`.
 
 ### Secciones condicionales
 
@@ -130,34 +144,63 @@ no recortando el plan.
 |---|---|
 | Nombres y textos definitivos | la tarea crea nombres nuevos que aparecen en más de un archivo (columna, propiedad, identificador, clave de idioma, texto visible) |
 | Contrato de datos | el cambio define o amplía una estructura: JSON, arreglo, DTO, payload |
-| Etapas con commits separados | hay más de un cambio lógico independiente y uno es más arriesgado que los otros |
 | Pre-vuelo medido | una decisión de diseño del plan se resuelve con un número, no con un argumento |
-| Comparación contra la réplica de lectura | el cambio altera lo que muestra un reporte o un export existente |
+| Comparación de paridad | el cambio altera lo que muestra un reporte, un export o una salida existente. Cómo se compara lo dice PRUEBAS Y PARIDAD |
 | Reversión | hay migración, el cambio escribe datos, o el despliegue va en más de un paso |
 | Nota de despliegue | el orden entre migración y código importa |
 | Diagrama | la tarea agrega una ruta o pantalla nueva con tres o más piezas que se llaman entre sí. En `mermaid` |
 | Casos borde | hay entradas que pueden llegar en estados que el camino feliz no cubre |
 | Plan B | un paso puede fallar y existe una alternativa de menor alcance que conserva parte del beneficio |
-| Micro-decisiones resueltas aquí | apareció una decisión chica al bajar a código. Con sus opciones descartadas, igual que en la Fase 2 |
+| Micro-decisiones resueltas aquí | apareció una decisión chica al bajar a código. Con sus opciones descartadas y su **Base**, igual que en la Fase 2 |
 | Checklist de ejecución | el plan tiene más de cinco pasos |
 
 ---
 
-## LAS ETAPAS CON COMMITS SEPARADOS
-
-Cuando se activa, el criterio es este: **lo que arregla el problema va primero; lo que solo
-mejora va al final, para que se pueda descartar sin perder el arreglo.**
+## LOTES
+<!-- ranura: lotes -->
+La Fase 4 no ejecuta el plan de golpe: lo ejecuta **un lote a la vez**, y cada lote termina en
+un commit atómico y en un recibo. Este documento define esos lotes.
 
-Cada etapa declara qué gana, qué riesgo tiene y cómo se revierte sola. Si la etapa
-arriesgada no pasa su criterio de aceptación, se tira ese commit y el resto sigue en pie.
+**El documento empieza con este frontmatter**, antes del título, con el número total de lotes:
 
+```markdown
+---
+lotes: 3
 ---
+```
+
+Un plan chico tiene `lotes: 1`. Es válido y no obliga a partir nada.
+
+Tabla obligatoria, después de los pasos:
+
+| Lote | Repo | Objetivo | Pasos | Criterio de salida | Commit propuesto | Revierte solo |
+|---|---|---|---|---|---|---|
+| L01 | <repo> | un cambio lógico, en una frase | M1, M2 | qué se ejecuta y qué debe dar | `tipo(área): frase` | sí, o no y por qué |
+
+Reglas de los lotes:
+- **Un lote es un cambio lógico que se puede revertir solo.** Si para describir su objetivo
+  necesitas un "y", probablemente son dos lotes.
+- **Un lote toca un solo repositorio.** Un commit no puede abarcar dos.
+- **Cada lote deja la aplicación funcionando.** Ninguno depende de uno posterior para compilar
+  o arrancar.
+- **Lo que arregla va primero; lo que solo mejora, al final**, para poder descartarlo sin perder
+  el arreglo. Si un lote es más arriesgado que los demás, va al final y lo dices.
+- **Numeración con dos dígitos:** `L01`, `L02`… Es el nombre del recibo en la Fase 4.
+- **El criterio de salida es ejecutable cuando se puede ejecutar:** un comando, una consulta o
+  una prueba, con lo que debe dar. Lo que necesita pantalla se dice como "qué debe verse", sin
+  pasos.
+- **Cada paso pertenece a exactamente un lote.**
+- **Un lote que depende de un pendiente heredado lo dice en su objetivo.**
+<!-- /ranura -->
 
-## LA COMPARACIÓN CONTRA LA RÉPLICA DE LECTURA
+---
 
-No hay suite de pruebas automatizadas en el proyecto, así que **no inventes una sección de
-tests ni propongas escribirlos como parte del plan**. Dilo en una línea cuando venga a
-cuento y sigue.
+## PRUEBAS Y PARIDAD
+<!-- ranura: pruebas -->
+Si el proyecto no tiene suite de pruebas automatizadas configurada, **no inventes una sección
+de tests ni propongas escribir la primera del módulo**. Dilo en una línea cuando venga a cuento
+y sigue. Si ya existe una suite en el repositorio, sí debes correrla: el plan dice qué comando
+y qué debe dar, en el criterio de salida de cada lote.
 
 Lo que sí existe es acceso de solo lectura a una réplica. Cuando el cambio altera lo que
 muestra un reporte o un export, el plan define la comparación:
@@ -171,6 +214,10 @@ muestra un reporte o un export, el plan define la comparación:
     escrita de antemano**. Lo que quede fuera de esa lista es un defecto, no una mejora.
 - Si el volcado sale a un archivo, decir que no se versiona: lleva datos de clientes.
 
+Si no hay suite, está prohibido inventar una sección de pruebas automatizadas o proponer
+escribir la primera del módulo como parte de esta tarea.
+<!-- /ranura -->
+
 ---
 
 ## REGLAS DE REDACCIÓN
@@ -196,18 +243,21 @@ muestra un reporte o un export, el plan define la comparación:
   es Fase 4. Aquí se dice qué debe verse, no cómo llegar a verlo.
 - Escribir un archivo existente completo en vez del fragmento con su ancla.
 - Dejar código sin declarar en qué nivel está.
-- Inventar una sección de pruebas automatizadas, o proponer escribir la primera del módulo
-  como parte de esta tarea.
 - Reescribir los documentos de la Fase 1 o de la Fase 2.
 - Reiniciar la numeración de decisiones o la de riesgos.
 - Rediscutir una decisión ya cerrada sin haber encontrado algo en el código que la invalide.
 - Rellenar secciones condicionales que no aplican, con tal de que el documento se vea completo.
 - Planear algo que no puedas señalar en un patrón existente del proyecto.
+- Escribir el plan sin la tabla de lotes, o sin el frontmatter `lotes: N`.
+- Un lote que toca más de un repositorio, o que deja la aplicación sin funcionar hasta un lote posterior.
+- Escribir el primer paso sin haber nombrado los pendientes heredados de la Fase 2.
+- Un desvío o una micro-decisión `D<n>` sin **Base**.
 
 ---
 
 ## MARCAS DE CALIDAD
 
+<!-- ranura: ejemplos -->
 Así se ve un plan que sirve. Son ejemplos reales de documentos aprobados.
 
 **La verificación previa que salva la tarea:**
@@ -248,6 +298,7 @@ Así se ve un plan que sirve. Son ejemplos reales de documentos aprobados.
 > "Si la comparación revela diferencias que no se explican en minutos, no se insiste con el
 > join. Dado que la primera etapa ya resuelve el grueso del problema de velocidad, descartar
 > por completo la tercera tampoco sería un mal desenlace."
+<!-- /ranura -->
 
 ---
 
@@ -264,3 +315,7 @@ Así se ve un plan que sirve. Son ejemplos reales de documentos aprobados.
 9. ¿Los desvíos respecto a la Fase 2 continúan la numeración `D<n>`?
 10. ¿Cada sección condicional cumple su disparador? Si no, bórrala.
 11. ¿El orden de aplicación está justificado, o solo enumerado?
+12. ¿El documento empieza con el frontmatter `lotes: N`, y N coincide con las filas de la tabla de lotes?
+13. ¿Cada paso pertenece a exactamente un lote, cada lote toca un solo repositorio y su criterio de salida es ejecutable cuando se puede ejecutar?
+14. ¿Nombré los pendientes heredados antes del primer paso, y los pasos que dependen de ellos van como Propuesta?
+15. ¿Los desvíos y las micro-decisiones `D<n>` tienen su **Base**?