mcp-phase-gate 2.0.1 → 2.2.0

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,14 @@ 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 tieneValidacionesPendientes(texto: string): boolean;
+export declare function avisoDePendientes(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,9 @@
 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 { log } from "./log.js";
+import { claveDeNombre, findProjectFolder, leerTextoAcotado, requireProjectFolder, tasksRootPath } from "./paths.js";
+import { separarFrontmatter } from "./phases.js";
 export function leerPunteros() {
     const archivo = stateFile();
     if (!fs.existsSync(archivo))
@@ -67,7 +69,7 @@ export function limpiarEstadoViejo() {
         try {
             if (fs.existsSync(viejo)) {
                 fs.unlinkSync(viejo);
-                console.error(`[orquestador] Estado en formato anterior eliminado: ${viejo}`);
+                log("info", `Estado en formato anterior eliminado: ${viejo}`);
             }
         }
         catch {
@@ -120,6 +122,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 +199,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 +242,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 +264,158 @@ 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");
+}
+// ─── Pendientes heredados ───────────────────────────────────────────────────
+// Refuerzo del servidor para la regla global PENDIENTES HEREDADOS (#39): si la fase anterior dejó
+// algo sin comprobar, el prompt de la siguiente llega con un aviso que lo nombra. Lee encabezados
+// y frontmatter de documentos que el prompt ya obliga a escribir; no guarda estado ni cambia la
+// deducción de fase. Si el modelo no escribió la sección, el aviso no sale y todo sigue igual.
+//
+// No contradice el rechazo de la #39 a un campo `Estado:`: aquello era hacer depender la
+// compuerta de algo escrito por el modelo. Esto no bloquea ni cambia la fase: solo señala.
+const ENCABEZADO_PENDIENTES = "## Validaciones pendientes";
+// Lo que se escribe por costumbre en una sección que no tiene nada: no es un pendiente.
+const SECCION_VACIA = new Set([
+    "",
+    "ninguna",
+    "ninguno",
+    "ninguna pendiente",
+    "nada",
+    "sin pendientes",
+    "no hay pendientes",
+    "fase cerrada sin pendientes",
+    "n/a",
+    "no aplica",
+]);
+// La sección reducida a su texto: sin viñetas ni numeración, sin énfasis de Markdown (_ * `),
+// sin puntos suspensivos ni punto final, en una línea y en minúsculas. Así "- Ninguna.",
+// "_Ninguna._" o "Ninguna..." cuentan igual que "Ninguna".
+function textoDeSeccion(seccion) {
+    return seccion
+        .split("\n")
+        .map((linea) => linea.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, ""))
+        .join(" ")
+        .replace(/[_*`]/g, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/(?:\.+|…)$/, "")
+        .trim()
+        .toLowerCase();
+}
+const ESTADOS_PENDIENTES = new Set(["con pendientes", "fallido", "descartado"]);
+// La sección es el texto entre su encabezado y el siguiente "## " (o el final). Devuelve true si
+// existe y tiene algo que no sea una forma de decir "ninguna".
+export function tieneValidacionesPendientes(texto) {
+    const lineas = separarFrontmatter(texto).cuerpo.split("\n");
+    // El encabezado se compara sin distinguir mayúsculas: "## Validaciones Pendientes" también vale.
+    const buscado = ENCABEZADO_PENDIENTES.toLowerCase();
+    const inicio = lineas.findIndex((linea) => linea.trimEnd().normalize("NFC").toLowerCase() === buscado);
+    if (inicio === -1)
+        return false;
+    const resto = lineas.slice(inicio + 1);
+    const fin = resto.findIndex((linea) => linea.startsWith("## "));
+    const seccion = (fin === -1 ? resto : resto.slice(0, fin)).join("\n");
+    return !SECCION_VACIA.has(textoDeSeccion(seccion));
+}
+function leerSinFallar(ruta) {
+    try {
+        return leerTextoAcotado(ruta);
+    }
+    catch {
+        return null; // un documento ilegible no es un pendiente: el aviso es una ayuda, no un control
+    }
+}
+export function avisoDePendientes(fasePedida, estado, phases) {
+    const ordenadas = [...phases.entries()].sort((a, b) => a[0] - b[0]);
+    const lineas = [];
+    // La fase anterior es la de mayor número, por debajo de la pedida, cuyo documento existe.
+    const anterior = ordenadas
+        .filter(([numero, datos]) => numero < fasePedida && datos.documento)
+        .reverse()
+        .find(([, datos]) => fs.existsSync(path.join(estado.folderPath, datos.documento)));
+    if (anterior) {
+        const documento = anterior[1].documento;
+        const texto = leerSinFallar(path.join(estado.folderPath, documento));
+        if (texto !== null && tieneValidacionesPendientes(texto)) {
+            lineas.push(`- \`${documento}\` tiene una sección \`${ENCABEZADO_PENDIENTES}\`.`);
+        }
+    }
+    // Los recibos de lote de las fases anteriores que quedaron con pendientes, fallidos o
+    // descartados. Con un solo lote, el recibo es el documento de la fase y se mira también.
+    for (const [numero, datos] of ordenadas) {
+        if (numero >= fasePedida || !datos.recibos)
+            continue;
+        const candidatos = [];
+        if (datos.documento)
+            candidatos.push(datos.documento);
+        const subcarpeta = path.join(estado.folderPath, datos.recibos);
+        if (fs.existsSync(subcarpeta)) {
+            for (const entrada of fs.readdirSync(subcarpeta, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (entrada.isFile() && entrada.name.toLowerCase().endsWith(".md"))
+                    candidatos.push(`${datos.recibos}/${entrada.name}`);
+            }
+        }
+        for (const relativo of candidatos) {
+            const ruta = path.join(estado.folderPath, ...relativo.split("/"));
+            if (!fs.existsSync(ruta))
+                continue;
+            const texto = leerSinFallar(ruta);
+            const valor = texto === null ? "" : (separarFrontmatter(texto).meta.estado ?? "").trim().toLowerCase();
+            if (ESTADOS_PENDIENTES.has(valor))
+                lineas.push(`- \`${relativo}\`: estado \`${valor}\`.`);
+        }
+    }
+    if (lineas.length === 0)
+        return null;
+    return [
+        "## PENDIENTES HEREDADOS (detectados por el servidor)",
+        "",
+        ...lineas,
+        "",
+        "Nómbraselos al usuario antes de empezar (ver PENDIENTES HEREDADOS en las reglas globales).",
+    ].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.2.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": {
@@ -43,7 +43,6 @@
   "homepage": "https://github.com/Montse2308/mcp-phase-gate#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "dotenv": "^17.4.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/prompts/comandos/f1.md

@@ -0,0 +1,14 @@
+Vas a iniciar la FASE 1 (Descubrimiento) del flujo del mcp-phase-gate.
+
+Datos de la tarea (tómalos del texto que escribí después del comando; si falta alguno, pregúntame antes de seguir):
+- project: uno de los proyectos que ya existen. Si no lo reconoce, `start_task` te devuelve la lista; no inventes uno ni pases `crear_proyecto` salvo que yo te diga explícitamente que quiero estrenar un proyecto nuevo.
+- task_name: nombre corto de la tarea
+- initial_context: el correo / mensaje / requerimiento completo
+
+Pasos:
+1. Llama a la tool `start_task` del mcp-phase-gate con project, task_name e initial_context.
+2. Llama a `get_phase_prompt(1)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol de comportamiento.
+3. Analiza el código actual de este repositorio para entender el impacto del requerimiento.
+4. Guarda el análisis técnico y funcional con `write_central_doc`, usando el nombre de archivo exacto que te indicó `get_phase_prompt`.
+
+No escribas código de producción todavía.

package/prompts/comandos/f2.md

@@ -0,0 +1,12 @@
+Vas a iniciar la FASE 2 (Decisiones) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes cuál es la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(2)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee el documento de la Fase 1 con `read_central_doc`; `get_phase_prompt` te dio su nombre exacto.
+4. Identifica lagunas técnicas, riesgos y dependencias con el código existente.
+5. Hazme la lista de preguntas críticas de decisión, explicándome las implicaciones de cada una.
+6. Detente y espera mis respuestas. No escribas código aún.
+7. Cuando ya te haya respondido: valida cada decisión contra el código real antes de darla por cerrada y guarda el documento de la fase con `write_central_doc`, con el nombre que te indicó `get_phase_prompt` y la estructura que pide el prompt.
+
+El documento de la Fase 2 es obligatorio, aunque las decisiones se hayan tomado conversando: el chat no viaja entre dispositivos, el documento sí.

package/prompts/comandos/f3.md

@@ -0,0 +1,9 @@
+Vas a iniciar la FASE 3 (Plan Técnico) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(3)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee los documentos de las fases anteriores con `read_central_doc`; `get_phase_prompt` te dio sus nombres exactos.
+4. Comprueba contra el código real lo que el plan va a afirmar, ANTES de escribirlo.
+5. Con las decisiones ya tomadas, genera el plan con su tabla de lotes, respetando "Cero Rupturas".
+6. Guárdalo con `write_central_doc`, con el nombre que te indicó `get_phase_prompt`.

package/prompts/comandos/f4.md

@@ -0,0 +1,10 @@
+Vas a iniciar la FASE 4 (Ejecución) del flujo del mcp-phase-gate.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name).
+2. Llama a `get_phase_prompt(4)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol.
+3. Lee el plan técnico de la Fase 3 con `read_central_doc` —`get_phase_prompt` te dio su nombre exacto— y nómbrame sus pendientes antes de tocar código.
+4. Ejecútalo **lote por lote**, como indica el prompt: implementa un lote, verifícalo ejecutando, escribe su recibo, muéstrame archivos y mensaje de commit, y con mi OK haz el commit antes de abrir el siguiente. Nunca hagas push.
+5. Con un solo lote, su recibo es el documento de la fase. Con más de uno, el documento de la fase es el índice y se escribe solo al cerrar el último.
+
+El entregable de esta fase es el código funcionando, lote por lote; cada recibo es corto y se escribe al cerrar su lote.

package/prompts/comandos/f5.md

@@ -0,0 +1,12 @@
+Vas a iniciar la FASE 5 (Auditoría / Pre-PR) del flujo del mcp-phase-gate.
+
+Commits a auditar: si escribí un rango después del comando, usa ese. Si no, tómalos de los recibos de la Fase 4. Si tampoco hay recibos, pregúntame cuáles antes de seguir.
+
+Pasos:
+1. Si no sabes la tarea activa, llama a `get_active_task` (o pídeme project + task_name): la auditoría se guarda en su carpeta.
+2. Llama a `get_phase_prompt(5)` indicándole también el `project` en el que estoy trabajando —con eso comprueba que no me esté saltando una fase— y asume ese rol de auditor externo.
+3. Inspecciona los commits indicados usando SOLO lectura (git diff / git log de solo lectura, leer archivos). Nunca hagas commits, push ni subas PRs; de eso me encargo yo.
+4. Entrégame en el chat:
+   - La AUDITORÍA con el formato del revisor, dejando clarísimo si hay cambios BLOQUEANTES para subir el PR.
+   - La DESCRIPCIÓN del PR (título + cuerpo), contrastada contra el código real.
+5. Guarda el documento de la fase con `write_central_doc`, con el nombre que te indicó `get_phase_prompt`: lleva la auditoría y la descripción del PR tal cual me las entregaste.

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**?