mcp-phase-gate 2.0.0

package/build/phases.js

@@ -0,0 +1,164 @@
+// Las fases y sus prompts. El número de fases no está cableado: se descubren de los
+// archivos que existan en la carpeta de prompts, y cada una declara en su propia cabecera
+// cómo se llama el documento que produce.
+import * as fs from "fs";
+import * as path from "path";
+import { promptsLayers } from "./config.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",
+// para que un juego de prompts en inglés funcione sin tocar el código.
+export const PHASE_FILE_PATTERN = /^(?:fase|phase)-(\d+)[-.]/i;
+// Cabecera opcional al inicio del .md, entre líneas de ---, con "clave: valor".
+// Ahí cada fase declara cómo se llama el documento que produce. Vive pegada al prompt que
+// 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?/;
+export function parsePhaseFile(fullPath) {
+    const crudo = fs.readFileSync(fullPath, "utf-8");
+    const encontrada = crudo.match(PHASE_FRONTMATTER);
+    if (!encontrada)
+        return { meta: {}, cuerpo: crudo };
+    const meta = {};
+    for (const linea of (encontrada[1] ?? "").split(/\r?\n/)) {
+        const corte = linea.indexOf(":");
+        if (corte === -1)
+            continue;
+        meta[linea.slice(0, corte).trim()] = linea
+            .slice(corte + 1)
+            .trim()
+            .replace(/^["']|["']$/g, "");
+    }
+    return { meta, cuerpo: crudo.slice(encontrada[0].length) };
+}
+// Descubre las fases disponibles a partir de los archivos de las carpetas de prompts.
+// Agregar un "fase-6-*.md" basta para que exista la fase 6 — también en la carpeta propia,
+// así que superponer no solo permite cambiar fases: permite añadirlas.
+//
+// Las capas se recorren en orden y la última que declare una fase es la que queda. Se
+// superpone POR NÚMERO DE FASE, no por nombre de archivo: el usuario no tiene por qué llamar
+// a su fase 2 igual que el paquete, y obligarle a adivinar el nombre exacto sería una trampa.
+//
+// `capas` es un parámetro y no una lectura directa del entorno para poder probar el
+// comportamiento con carpetas concretas sin depender de qué traiga el paquete instalado.
+export function discoverPhases(capas = promptsLayers()) {
+    const phases = new Map();
+    for (const base of capas) {
+        if (!fs.existsSync(base))
+            continue;
+        // Se resuelve capa por capa: dentro de una, gana el primero por orden alfabético; entre
+        // capas, gana la de más arriba. Sin este mapa intermedio la regla alfabética de la capa
+        // baja bloquearía a la de arriba, que es justo al revés de lo que se quiere.
+        const deEstaCapa = new Map();
+        for (const file of fs.readdirSync(base).sort()) {
+            const match = file.match(PHASE_FILE_PATTERN);
+            if (!match || !file.toLowerCase().endsWith(".md"))
+                continue;
+            const phaseNumber = Number(match[1]);
+            if (deEstaCapa.has(phaseNumber))
+                continue; // gana el primero por orden alfabético
+            const fullPath = path.join(base, file);
+            let meta = {};
+            let cuerpo = "";
+            try {
+                ({ meta, cuerpo } = parsePhaseFile(fullPath));
+            }
+            catch {
+                // Si el archivo no se puede leer aquí, el error real se reporta al invocar la fase.
+            }
+            deEstaCapa.set(phaseNumber, {
+                file: fullPath,
+                title: readPhaseTitle(cuerpo, file),
+                documento: meta.documento || undefined,
+                documentoInicial: meta.documento_inicial || undefined,
+            });
+        }
+        for (const [numero, datos] of deEstaCapa)
+            phases.set(numero, datos);
+    }
+    return phases;
+}
+// El título es el primer encabezado "# ..." del cuerpo; si no lo hay, se deriva del nombre
+// del archivo para que la descripción de la tool siga siendo útil.
+export function readPhaseTitle(cuerpo, fileName) {
+    for (const line of cuerpo.split(/\r?\n/)) {
+        if (line.startsWith("# "))
+            return line.slice(2).trim();
+    }
+    return fileName.replace(PHASE_FILE_PATTERN, "").replace(/\.md$/i, "");
+}
+// Nombre del archivo de contexto inicial que escribe start_task. Lo declara la fase 1 en su
+// cabecera; la constante es solo el respaldo para un juego de prompts que no lo declare.
+export const CONTEXTO_INICIAL_POR_DEFECTO = "00 - Contexto Inicial.md";
+export function nombreContextoInicial(capas = promptsLayers()) {
+    return discoverPhases(capas).get(1)?.documentoInicial || CONTEXTO_INICIAL_POR_DEFECTO;
+}
+// Se lee en cada llamada (no se cachea) para poder afinar un prompt y probarlo
+// de inmediato, sin reiniciar el servidor MCP.
+export function loadPhasePrompt(phase, capas = promptsLayers()) {
+    const available = discoverPhases(capas);
+    const entry = available.get(phase);
+    if (!entry) {
+        const list = [...available.keys()].sort((a, b) => a - b).join(", ");
+        throw new Error(list
+            ? `Fase no válida. Las fases disponibles son: ${list}.`
+            : `No se encontró ningún prompt de fase en ${capas.join(", ")}. Verifica que la carpeta 'prompts' exista junto al build.`);
+    }
+    const parts = [];
+    const globales = resolveGlobalRules(capas);
+    if (globales) {
+        parts.push(fs.readFileSync(globales, "utf-8").trim());
+    }
+    parts.push(parsePhaseFile(entry.file).cuerpo.trim());
+    const archivos = describePhaseFiles(available, phase);
+    if (archivos)
+        parts.push(archivos);
+    return parts.join("\n\n");
+}
+// Las reglas globales de la capa más alta que las tenga. Las tuyas SUSTITUYEN a las de
+// fábrica, no se suman: concatenar dos juegos de reglas hace imposible saber de qué archivo
+// salió la instrucción que estorbó cuando algo sale raro, que es justo el momento en que hay
+// que saberlo. Si quieres las de fábrica y algo más, las copias y añades.
+function resolveGlobalRules(capas) {
+    for (const base of [...capas].reverse()) {
+        const ruta = path.join(base, GLOBAL_RULES_FILE);
+        if (fs.existsSync(ruta))
+            return ruta;
+    }
+    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
+// 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) {
+    const propio = available.get(phase)?.documento;
+    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}\``);
+    if (!propio && previos.length === 0)
+        return "";
+    const lineas = ["## ARCHIVOS DE ESTA TAREA (nombres exactos)"];
+    if (previos.length) {
+        lineas.push("", "Documentos de las fases anteriores, léelos con `read_central_doc`:", ...previos);
+    }
+    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.");
+    }
+    else {
+        lineas.push("", "Esta fase no deja documento en la Documentación Central: su salida va en el chat.");
+    }
+    return lineas.join("\n");
+}
+export function describePhases() {
+    const available = discoverPhases();
+    if (available.size === 0)
+        return "No se encontraron prompts de fase.";
+    return [...available.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([number, { title }]) => `${number}: ${title}`)
+        .join(", ");
+}
+//# sourceMappingURL=phases.js.map

package/build/tasks.d.ts

@@ -0,0 +1,36 @@
+import type { PhaseFile } from "./phases.js";
+export type Punteros = Record<string, string>;
+export declare function leerPunteros(): Punteros;
+export declare function guardarPuntero(project: string, taskName: string): void;
+export declare function limpiarEstadoViejo(): void;
+export type EstadoTarea = {
+    taskName: string;
+    folderPath: string;
+    fasesHechas: number[];
+    siguienteFase: number | null;
+    fasesConDocumento: number;
+    ultimoCambio: number | null;
+};
+export declare function estadoDeTarea(taskName: string, folderPath: string, phases: Map<number, PhaseFile>): EstadoTarea;
+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 = {
+    estado: EstadoTarea;
+    origen: "puntero" | "deducida";
+};
+export declare function tareaActiva(carpetaProyecto: string, phases: Map<number, PhaseFile>): TareaActiva | null;
+export type Salto = {
+    fasePedida: number;
+    siguienteFase: number;
+    faltan: {
+        fase: number;
+        documento: string;
+    }[];
+};
+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?: {
+    project?: string;
+    taskName?: string;
+}): string | null;
+export declare function avisoDeSalto(salto: Salto, taskName: string, phases: Map<number, PhaseFile>): string;
+//# sourceMappingURL=tasks.d.ts.map

package/build/tasks.js

@@ -0,0 +1,243 @@
+// Tareas: cuáles existen, en qué fase va cada una, y cuál es la activa de cada proyecto.
+//
+// La idea central: **la carpeta es el registro**. Las tareas son las carpetas que existen y la
+// fase de cada una se deduce de los documentos que hay dentro, porque cada fase declara en su
+// cabecera cómo se llama el suyo. No hay un archivo que liste tareas ni que apunte fases.
+//
+// Guardar esa información sería tener dos copias de la misma verdad, y la copia guardada
+// dependería de que el modelo se acordara de reportar cada avance. Deducirla del disco la
+// vuelve un hecho: si borras un documento a mano porque quedó mal, la fase baja sola.
+//
+// Lo único que sí se guarda es un puntero por proyecto —cuál es la tarea activa—, porque eso
+// el disco no lo puede saber. Antes era un solo puntero global y dos ventanas abiertas a la
+// vez se lo pisaban: la ventana A preguntaba dónde estaba y le contestaban la tarea de B.
+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";
+export function leerPunteros() {
+    const archivo = stateFile();
+    if (!fs.existsSync(archivo))
+        return {};
+    try {
+        const crudo = JSON.parse(fs.readFileSync(archivo, "utf-8"));
+        if (!crudo || typeof crudo !== "object" || Array.isArray(crudo))
+            return {};
+        // Se filtra en vez de confiar: el archivo lo puede haber tocado cualquiera, y una entrada
+        // con forma rara no debe tumbar las demás.
+        const punteros = {};
+        for (const [proyecto, tarea] of Object.entries(crudo)) {
+            if (typeof tarea === "string" && tarea.trim())
+                punteros[proyecto.toLowerCase()] = tarea;
+        }
+        return punteros;
+    }
+    catch {
+        // Un archivo ilegible no debe dejar al usuario sin servicio: se ignora y el sistema cae
+        // en la deducción, que da una respuesta razonable sin necesitar estado guardado.
+        return {};
+    }
+}
+export function guardarPuntero(project, taskName) {
+    const punteros = leerPunteros(); // se relee justo antes de escribir: otra ventana pudo cambiarlo
+    punteros[project.toLowerCase()] = taskName;
+    escribirPunteros(punteros);
+}
+// Escribe a un temporal y renombra. El renombrado es atómico dentro del mismo sistema de
+// archivos, así que un corte a media escritura no deja el archivo a medias: o está el de
+// antes, o está el nuevo. Importa porque ahora son varias ventanas escribiendo el mismo
+// archivo, y antes cada escritura era un objeto suelto que se sobrescribía entero.
+//
+// Queda una ventana mínima entre leer y escribir en la que dos procesos simultáneos podrían
+// perder el puntero del otro. No se bloquea el archivo a propósito: el costo de perder un
+// puntero es un `switch_task`, y un lock mal soltado deja el servidor inservible.
+function escribirPunteros(punteros) {
+    const archivo = stateFile();
+    const temporal = `${archivo}.tmp`;
+    fs.mkdirSync(stateDir(), { recursive: true });
+    fs.writeFileSync(temporal, JSON.stringify(punteros, null, 2), "utf-8");
+    fs.renameSync(temporal, archivo);
+}
+// El formato anterior guardaba una sola tarea activa global en `active_task.json`. Ya no se
+// puede leer —cambió de forma— y conservarlo solo deja basura en la carpeta de datos, así
+// que se borra la primera vez que arranca esta versión.
+export function limpiarEstadoViejo() {
+    const viejos = [path.join(stateDir(), "active_task.json"), path.join(MODULE_DIR, "active_task.json")];
+    for (const viejo of viejos) {
+        try {
+            if (fs.existsSync(viejo)) {
+                fs.unlinkSync(viejo);
+                console.error(`[orquestador] Estado en formato anterior eliminado: ${viejo}`);
+            }
+        }
+        catch {
+            // Que no se pueda borrar no impide trabajar: el archivo viejo ya no se lee.
+        }
+    }
+}
+// Mira qué documentos existen en la carpeta y traduce eso a fases hechas y fase siguiente.
+// Solo cuentan las fases que declaran documento: una fase sin documento no puede completarse
+// y, si contara, dejaría la deducción atascada en ella para siempre.
+export function estadoDeTarea(taskName, folderPath, phases) {
+    const conDocumento = [...phases.entries()]
+        .filter(([, datos]) => datos.documento)
+        .sort((a, b) => a[0] - b[0]);
+    const fasesHechas = [];
+    const pendientes = [];
+    let ultimoCambio = null;
+    for (const [numero, datos] of conDocumento) {
+        const documento = path.join(folderPath, datos.documento);
+        if (!fs.existsSync(documento)) {
+            pendientes.push(numero);
+            continue;
+        }
+        fasesHechas.push(numero);
+        try {
+            const mtime = fs.statSync(documento).mtimeMs;
+            if (ultimoCambio === null || mtime > ultimoCambio)
+                ultimoCambio = mtime;
+        }
+        catch {
+            // Si no se puede leer la fecha, la tarea sigue contando como avanzada; solo pierde
+            // precisión al ordenarla por actividad.
+        }
+    }
+    // Sin ningún documento todavía, la carpeta recién creada por start_task marca la actividad.
+    if (ultimoCambio === null) {
+        try {
+            ultimoCambio = fs.statSync(folderPath).mtimeMs;
+        }
+        catch {
+            ultimoCambio = null;
+        }
+    }
+    return {
+        taskName,
+        folderPath,
+        fasesHechas,
+        siguienteFase: pendientes.length ? pendientes[0] : null,
+        fasesConDocumento: conDocumento.length,
+        ultimoCambio,
+    };
+}
+// 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) {
+    if (estado.fasesConDocumento === 0) {
+        return "fase desconocida (ningún prompt de fase declara documento, así que no hay nada que deducir)";
+    }
+    if (estado.siguienteFase === null) {
+        return "terminada: todas las fases dejaron su documento";
+    }
+    const titulo = phases.get(estado.siguienteFase)?.title;
+    const siguiente = titulo
+        ? `va en Fase ${estado.siguienteFase} (${titulo})`
+        : `va en Fase ${estado.siguienteFase}`;
+    return estado.fasesHechas.length
+        ? `${siguiente}; hechas: ${estado.fasesHechas.join(", ")}`
+        : `${siguiente}; todavía sin documentos`;
+}
+// ─── 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.
+export function listarTareas(carpetaProyecto, phases) {
+    const raiz = tasksRootPath(carpetaProyecto);
+    if (!fs.existsSync(raiz))
+        return [];
+    return fs
+        .readdirSync(raiz, { withFileTypes: true })
+        .filter((entrada) => entrada.isDirectory())
+        .map((entrada) => estadoDeTarea(entrada.name, path.join(raiz, entrada.name), phases))
+        .sort((a, b) => (b.ultimoCambio ?? 0) - (a.ultimoCambio ?? 0));
+}
+// Con puntero guardado se devuelve esa. Sin puntero —estado borrado, equipo nuevo, archivo
+// corrupto— se deduce la tarea con actividad más reciente, marcada como deducción. Así perder
+// el archivo de estado deja de ser un callejón sin salida.
+export function tareaActiva(carpetaProyecto, phases) {
+    const tareas = listarTareas(carpetaProyecto, phases);
+    if (tareas.length === 0)
+        return null;
+    const apuntada = leerPunteros()[carpetaProyecto.toLowerCase()];
+    if (apuntada) {
+        const encontrada = tareas.find((tarea) => tarea.taskName === apuntada);
+        // Un puntero a una carpeta que ya no existe (renombrada o borrada) no debe dejar sin
+        // respuesta: se ignora y se deduce, igual que si no hubiera puntero.
+        if (encontrada)
+            return { estado: encontrada, origen: "puntero" };
+    }
+    return { estado: tareas[0], origen: "deducida" };
+}
+export function detectarSalto(fasePedida, estado, phases) {
+    // Sin fases con documento no hay nada contra lo que comparar; y una tarea terminada no
+    // tiene huecos, así que ninguna fase que se pida puede ser un salto.
+    if (estado.siguienteFase === null)
+        return null;
+    // Pedir la fase que toca, o una anterior, es legítimo. Solo se mira hacia adelante.
+    if (fasePedida <= estado.siguienteFase)
+        return null;
+    const faltan = [...phases.entries()]
+        .filter(([numero, datos]) => numero < fasePedida && datos.documento && !estado.fasesHechas.includes(numero))
+        .sort((a, b) => a[0] - b[0])
+        .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 = {}) {
+    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.");
+        }
+        const encontrada = findProjectFolder(conPuntero[0]);
+        if (!encontrada)
+            return null; // Puntero de un proyecto que ya no existe: se ignora.
+        carpetaProyecto = encontrada;
+    }
+    const estado = opciones.taskName
+        ? listarTareas(carpetaProyecto, phases).find((tarea) => tarea.taskName === opciones.taskName)
+        : tareaActiva(carpetaProyecto, phases)?.estado;
+    if (!estado)
+        return null; // Proyecto sin tareas, o un nombre de tarea que no existe.
+    const salto = detectarSalto(fasePedida, estado, phases);
+    return salto ? avisoDeSalto(salto, estado.taskName, phases) : null;
+}
+export function avisoDeSalto(salto, taskName, phases) {
+    const titulo = phases.get(salto.siguienteFase)?.title;
+    const vaEn = titulo ? `Fase ${salto.siguienteFase} (${titulo})` : `Fase ${salto.siguienteFase}`;
+    const lista = salto.faltan.map(({ fase, documento }) => `- Fase ${fase}: falta \`${documento}\``);
+    return [
+        "## ATENCIÓN — COMPUERTA DE FASE",
+        "",
+        `Pediste la Fase ${salto.fasePedida}, pero la tarea "${taskName}" no tiene los documentos de fases anteriores:`,
+        "",
+        ...lista,
+        "",
+        `Esta tarea va en la ${vaEn}. NO hagas el trabajo de la Fase ${salto.fasePedida} sobre documentos que no existen ` +
+            "ni te los inventes a partir del contexto del chat.",
+        "",
+        "Díselo al usuario antes de nada y pregúntale si prefiere hacer primero la fase que falta o continuar de todos " +
+            "modos. Lo que sigue es el prompt de la fase que pediste: aplícalo solo después de resolver esto con el usuario.",
+    ].join("\n");
+}
+//# sourceMappingURL=tasks.js.map

package/package.json

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

package/prompts/fase-1-descubrimiento.md

@@ -0,0 +1,167 @@
+---
+documento: 01 - Análisis Técnico.md
+documento_inicial: 00 - Contexto Inicial.md
+---
+
+# Descubrimiento
+
+## ROL DE COMPORTAMIENTO (GLOBAL)
+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.
+
+## 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.
+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.
+
+---
+
+## ALCANCE DE ESTA FASE (se presta a confusión: léelo)
+
+La Fase 1 entrega **diagnóstico más una recomendación de dirección marcada como tal**.
+No entrega plan de implementación.
+
+| Sí te toca | No te toca |
+|---|---|
+| Inventariar qué existe y quién lo consume, nombrando archivos y líneas | Listar los archivos "a modificar" o los pasos de implementación → **Fase 3** |
+| Explicar la causa raíz y demostrarla | Definir qué se va a validar → **Fase 2**; convertirlo en criterios verificables → **Fase 3** |
+| Recomendar una dirección, diciendo explícitamente que es una recomendación | Escribir pasos de prueba en la interfaz → **Fase 4** |
+| 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
+Fase 1. Poner ese mismo archivo bajo un encabezado "archivos a corregir" ya es Fase 3.
+
+---
+
+## VERIFICACIÓN: HAZLA EN ESTA FASE
+
+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.
+
+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í.
+
+Dejar consultas escritas "listas para correr" es el **último recurso**, válido solo
+cuando el acceso no existe de verdad. Si caes ahí:
+- Dilo como una **laguna del análisis**, no como un entregable.
+- Pide el acceso o pide que se corran **antes** de dar la fase por cerrada.
+
+Si te equivocaste al medir, dilo y descarta esos números explícitamente. Un análisis que
+confiesa su propio error de método es en el que se puede confiar.
+
+---
+
+## ESTRUCTURA DEL DOCUMENTO
+
+### Núcleo (siempre, en este orden)
+
+1. **Encabezado de metadatos.** Tarea, proyecto, fase, ruta o módulo afectado, fecha.
+   Declara que no se escribió código de producción.
+2. **Resumen ejecutivo.** VA ARRIBA, nunca al final. El veredicto en la primera línea, con
+   el número concreto si lo hay. Quien lea solo esta sección debe quedarse con lo esencial.
+3. **Estado actual / mapa de código.** Cómo funciona hoy, con `archivo:línea`.
+4. **Hallazgos.** Cada uno etiquetado con **Severidad** (Alta / Media / Baja) y
+   **Confianza** (Alta / Media / Baja). Separa el hallazgo principal de los secundarios.
+5. **Impacto y superficie afectada.** Quién más consume lo que se tocaría, y en qué estado
+   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.
+
+### Secciones condicionales
+
+Incluye SOLO las que cumplan su disparador. Un ajuste chico no dispara casi ninguna y el
+documento sale corto solo: así es como se ajusta la profundidad, no recortando el análisis.
+
+| Sección | Se activa si… |
+|---|---|
+| Comportamiento observado | el ticket reporta un síntoma concreto: qué se ve y dónde |
+| Respuesta a las hipótesis del ticket | quien reportó planteó causas posibles. Contéstalas UNA POR UNA, incluso las que descartas |
+| Reproducción del síntoma | lograste reproducirlo. Incluye el escenario numérico exacto |
+| 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 |
+| Deuda técnica fuera de alcance | encontraste algo real pero ajeno al ticket |
+| Predicción verificable | el diagnóstico implica algo futuro comprobable |
+
+---
+
+## REGLAS DE REDACCIÓN
+
+- **Siempre `archivo:línea`.** Nunca hables de "el servicio de cálculo" sin decir cuál es.
+- **Sin emojis**, en ninguna sección.
+- **Los hallazgos secundarios van como lista de una línea cada uno**, con la nota de que
+  se detallan si se aprueban. Excepción: si un hallazgo secundario tiene Severidad Alta,
+  ese sí va completo — no escondas algo grave en una lista.
+- Si el requerimiento parte de una **premisa falsa**, dilo lo más arriba posible. Descubrir
+  en la Fase 4 que el supuesto del ticket no existe en el código es el fallo más caro
+  de todo el flujo.
+- 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.
+
+---
+
+## PROHIBIDO
+
+- Afirmar cualquier cosa que no puedas señalar en un archivo o en una salida real.
+- Encabezados de "archivos a modificar" o "pasos de implementación": eso es Fase 3.
+- Listas de qué validar o criterios de aceptación: eso es de la Fase 2 en adelante.
+- Pasos de prueba en la interfaz: eso es Fase 4.
+- Tomar las decisiones en vez de listarlas: eso es Fase 2.
+- Volver a escribir sobre este documento en fases posteriores. La decisión que se tome en
+  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.
+
+---
+
+## MARCAS DE CALIDAD
+
+Así se ve un análisis que sirve. Son ejemplos reales de documentos aprobados.
+
+**El veredicto arriba y con número, no con adjetivos:**
+> "El tablero tarda ~66 segundos por request y el costo se concentra en una sola
+> subconsulta, no en el diseño general ni en los cambios recientes."
+
+**Las hipótesis del ticket, contestadas una por una:**
+> "¿Fue la columna nueva? NO. ¿Fue el widget? NO. ¿Es un problema general del sistema? NO.
+> Las tres se descartaron con medición, no con opinión."
+
+**El propio error de método, confesado:**
+> "Un primer intento de medición pegó por error a la conexión default y midió solo el
+> costo fijo. Esos números se descartaron."
+
+**La premisa falsa del requerimiento, marcada de entrada:**
+> "Estas dos afirmaciones NO describen el mismo dato en el código actual. Es el punto que
+> hay que resolver antes de diseñar."
+
+**Una opción descartada, reconociendo su ventaja:**
+> "Para este caso sería viable y más limpio conceptualmente. Descartada porque no se puede
+> aplicar al segundo problema, y dejaría dos soluciones distintas para el mismo defecto en
+> el mismo archivo."
+
+**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."
+
+---
+
+## AUTOVERIFICACIÓN (antes de entregar, revísalas una por una)
+
+1. ¿El resumen ejecutivo está arriba y trae el veredicto con su número?
+2. ¿Cada hallazgo tiene Severidad y Confianza?
+3. ¿Toda afirmación se puede señalar en un archivo concreto o en una salida real?
+4. ¿Comprobé lo que era comprobable, en vez de dejarlo pendiente?
+5. ¿Cada sección condicional cumple su disparador? Si no, bórrala.
+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?