changebook 0.7.0 → 0.8.0

package/dist/respuestas.js

@@ -0,0 +1,111 @@
+/**
+ * Formas de fila y de respuesta del servidor MCP stdio.
+ *
+ * POR QUÉ EXISTE. Espejo de `supabase/functions/mcp/filasYRespuestas.ts`, que el
+ * hospedado sacó de su `index.ts` el 03/08 (AUD-C11) por la misma razón que
+ * aquí: `tools.ts` pasó de 1.400 a 1.900 líneas en un día y las herramientas que
+ * quedaban por portar no caben sin convertirlo en el módulo-dios siguiente.
+ *
+ * Y NO ES SOLO TAMAÑO: sin este corte, una herramienta en su propio fichero
+ * tendría que importar `toolResult` de `tools.ts` mientras `tools.ts` la importa
+ * a ella para registrarla — un ciclo. Estas funciones son puras y no dependen de
+ * ninguna herramienta, así que salir es lo natural.
+ *
+ * REGLA: aquí solo entra lo que no sabe NADA del atlas. Si algo necesita el
+ * cliente de Supabase, el repo o una consulta, no es de este fichero.
+ */
+import { SupabaseError } from './supabase.js';
+/**
+ * Tope de lo que se sirve en una respuesta. Por encima se recorta el texto Y se
+ * deja de mandar el `structuredContent`: mandarlo entero derrotaría el propio
+ * tope que acaba de recortar el texto.
+ */
+export const CHARACTER_LIMIT = 25_000;
+/**
+ * Las anotaciones de una tool de SOLO LECTURA. Espejo del `ro` del hospedado
+ * (`buildServer` en supabase/functions/mcp/index.ts). Vive aquí porque iba
+ * camino de su cuarta copia literal, y cuatro copias de un objeto de
+ * anotaciones es como se acaba teniendo una que miente.
+ */
+export const RO = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/**
+ * El contrato temporal de las respuestas del atlas (benchmark 2026-07-20: el
+ * agente afirmó un valor revertido porque la nota hablaba en presente). El ancla
+ * de deriva de `derivaContraHead` lo dice con precisión cuando hay árbol y hash;
+ * esta línea fija cubre el resto de los casos — nunca las dos a la vez.
+ */
+export const TEMPORAL_CONTRACT = 'Notes describe the code AS OF their date — concrete values (numbers, limits, names) may have changed since. Verify in the code before asserting them.';
+// ── Respuestas ───────────────────────────────────────────────────────────────
+function truncate(text) {
+    if (text.length <= CHARACTER_LIMIT)
+        return text;
+    return (text.slice(0, CHARACTER_LIMIT) +
+        '\n\n[Truncated. Use a smaller `limit`, an `offset`, or filters to narrow the result.]');
+}
+/**
+ * Construye el resultado de una tool. `structuredContent` duplica el texto
+ * renderizado, así que cuando hay que recortar el texto se deja fuera: mandarlo
+ * entero enviaría igualmente el objeto sin tope y derrotaría al recorte.
+ */
+export function toolResult(text, structured) {
+    if (text.length <= CHARACTER_LIMIT) {
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: structured,
+        };
+    }
+    return { content: [{ type: 'text', text: truncate(text) }] };
+}
+export function errorResult(error) {
+    const message = error instanceof SupabaseError || error instanceof Error
+        ? error.message
+        : String(error);
+    // isError deja al cliente MCP (y al agente) distinguir una llamada fallida de
+    // un resultado válido cuyo texto empieza por "Error:".
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `Error: ${message}` }],
+    };
+}
+/**
+ * Lo que de VERDAD llega al modelo. Espejo de `servedCharsOf` del hospedado.
+ *
+ * `chars_served` contaba el markdown, y el markdown casi nunca se usa: los
+ * tool_result llegan al modelo como el JSON del `structuredContent`. Solo cuando
+ * la respuesta revienta `CHARACTER_LIMIT` deja de haber JSON y queda el texto.
+ * Contar el markdown infravaloraba el gasto un 35%.
+ */
+export function servedCharsOf(result) {
+    return 'structuredContent' in result && result.structuredContent
+        ? JSON.stringify(result.structuredContent).length
+        : (result.content?.[0]?.text?.length ?? 0);
+}
+export function fileList(files) {
+    return Array.isArray(files) ? files.map(String) : [];
+}
+export function day(iso) {
+    return iso.slice(0, 10);
+}
+/** El patrón de un `or=(...ilike...)` de PostgREST, codificado una sola vez. */
+export function ilikePattern(search) {
+    return encodeURIComponent(`*${search.replace(/[%*,()]/g, ' ').trim()}*`);
+}
+// Extractos resumidos: los excerpts de diff guardados son lo más caro de
+// atlas_module_detail (~1.5k chars cada uno) y la mayoría de las llamadas solo
+// necesita saber QUÉ cambió. Por defecto va una vista previa corta; `full: true`
+// los devuelve verbatim.
+const EXCERPT_PREVIEW_LINES = 4;
+const EXCERPT_PREVIEW_CHARS = 320;
+export function previewExcerpt(excerpt) {
+    let text = excerpt.split('\n').slice(0, EXCERPT_PREVIEW_LINES).join('\n');
+    if (text.length > EXCERPT_PREVIEW_CHARS) {
+        text = text.slice(0, EXCERPT_PREVIEW_CHARS);
+    }
+    return { text: text.trimEnd(), truncated: text.length < excerpt.length };
+}
+//# sourceMappingURL=respuestas.js.map

package/dist/supabase.js

@@ -261,14 +261,50 @@ export class Supabase {
             throw new SupabaseError(`Patch on ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
         }
     }
-    patchOnce(table, filter, patch) {
+    /**
+     * Como `patchRows`, pero DEVUELVE las filas escritas (`return=representation`).
+     *
+     * POR QUÉ EXISTE, y no es cosmético (invariante 17). Con `return=minimal` un
+     * PATCH que no tocó nada y un PATCH que tocó cinco filas se ven exactamente
+     * igual: 204 los dos. Quien llama no puede distinguir «no había nada que
+     * cerrar» de «no me dejaron escribir», y esa confusión ya costó cara aquí: el
+     * 25/07 se añadió la columna `resolution` sin meterla en el grant POR COLUMNA
+     * de `regression_alerts` y los tres caminos que la escribían empezaron a
+     * fallar EN SILENCIO —`atlas_resolve_alert` informaba de que había cerrado
+     * cero, como si el aviso ya no estuviera abierto—. Volvió a asomar el 02/08
+     * con `resolution_by`. Ver 20260802120000_quien_juzgo_el_aviso.sql, que lo
+     * cuenta en su propio comentario.
+     *
+     * Devolver la representación no impide que vuelva a pasar; lo que hace es que
+     * cuando pase se VEA: quien llama compara lo que pidió cerrar con lo que
+     * volvió y puede gritar en vez de informar de un cero tranquilizador.
+     */
+    async patchRowsReturning(table, filter, patch) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.patchOnce(table, filter, patch, 'return=representation');
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.patchOnce(table, filter, patch, 'return=representation');
+        }
+        if (!res.ok) {
+            throw new SupabaseError(`Patch on ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
+        }
+        return (await res.json());
+    }
+    patchOnce(table, filter, patch, 
+    // `return=minimal` sigue siendo el defecto: cambiarlo para todos haría que
+    // cada PATCH del CLI se trajera filas que nadie lee.
+    prefer = 'return=minimal') {
         return fetch(`${this.url}/rest/v1/${table}?${filter}`, {
             method: 'PATCH',
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
                 'Content-Type': 'application/json',
-                Prefer: 'return=minimal',
+                Prefer: prefer,
             },
             body: JSON.stringify(patch),
             signal: AbortSignal.timeout(10_000),

package/dist/sync.js

@@ -54,6 +54,37 @@ const FIRMA = '_Generado por ChangeBook · changebook.app_';
 function sanitizeCell(text) {
     return text.replace(/<!--/g, '<!- -');
 }
+/**
+ * Recorta a `tope` caracteres sin partir palabras y DICIENDO que ha recortado.
+ *
+ * POR QUÉ EXISTE. Los topes de este bloque son deliberados —entra en cada
+ * sesión de agente y se reenvía en cada petición, así que es coste FIJO— pero
+ * se aplicaban con un `.slice(0, n)` pelado. El 04/08 el CLAUDE.md de este
+ * mismo repo decía «permitiendo validar q»: cortado a media palabra y sin
+ * ninguna marca. Eso no se lee como un extracto, se lee como salida rota, y
+ * este bloque es el artefacto más leído del producto.
+ *
+ * DOS COSAS, Y LAS DOS IMPORTAN:
+ *
+ *   · La elipsis SOLO aparece si de verdad se recortó. Ponerla siempre haría
+ *     que toda nota pareciera truncada, que es el error simétrico y igual de
+ *     malo: dejaría de distinguir lo completo de lo cortado.
+ *   · El hueco de la elipsis sale DE DENTRO del tope. El presupuesto está en
+ *     caracteres; un tope que se desborda por la marca que anuncia el tope es
+ *     un tope de mentira.
+ *
+ * Una palabra sola más larga que el tope se corta a lo bruto: retroceder al
+ * espacio anterior devolvería la cadena vacía, y perder la nota entera es peor
+ * que un corte feo. Ese caso está en el corpus del test.
+ */
+export function recorta(texto, tope) {
+    if (texto.length <= tope)
+        return texto;
+    const cortado = texto.slice(0, tope - 1);
+    const ultimoEspacio = cortado.lastIndexOf(' ');
+    const base = ultimoEspacio > 0 ? cortado.slice(0, ultimoEspacio) : cortado;
+    return `${base.replace(/[\s.,;:]+$/, '')}…`;
+}
 const MAX_MODULES = 15;
 const MAX_CHANGES = 5;
 const MAX_COUPLINGS = 5;
@@ -464,21 +495,21 @@ maxCitas = CITAS_GRATIS) {
         // un parrafo. Tres alertas a 200 chars se comian el 30% del presupuesto
         // y expulsaban el mapa. El texto entero sigue a una llamada de
         // `atlas_project_brief`, donde se paga solo si alguien pregunta.
-        return `- ${a.created_at.slice(0, 10)}${mod ? ` · **${mod}**` : ''} — ${sanitizeCell((a.plain ?? '').slice(0, 130))}`;
+        return `- ${a.created_at.slice(0, 10)}${mod ? ` · **${mod}**` : ''} — ${sanitizeCell(recorta(a.plain ?? '', 130))}`;
     });
     const hotspotLines = modules
         .filter((m) => m.risk === 'hotspot')
         .slice(0, 5)
         .map((m) => {
-        const note = sanitizeCell((m.note ?? '').slice(0, 110));
+        const note = sanitizeCell(recorta(m.note ?? '', 110));
         return `- **${m.module}** está marcado crítico${note ? ` — ${note}` : ''}`;
     });
-    const changeLines = changes.map((c) => `- ${c.created_at.slice(0, 10)} — ${sanitizeCell((c.business_impact ?? '').slice(0, 140))}`);
+    const changeLines = changes.map((c) => `- ${c.created_at.slice(0, 10)} — ${sanitizeCell(recorta(c.business_impact ?? '', 140))}`);
     // Salud en riesgo: los controles (auth, secretos, validación, límites…) que
     // el análisis ya marcó rotos con evidencia. Alta prioridad de presupuesto —
     // es seguridad. Solo los at_risk (lo accionable); el texto entero va a
     // `atlas_project_brief`. Cap a 130 chars como las alertas.
-    const healthLines = atRiskHealth.map((h) => `- ⚠ **${h.check}**${h.since ? ` (desde ${h.since})` : ''} — ${sanitizeCell(h.evidence.slice(0, 130))}`);
+    const healthLines = atRiskHealth.map((h) => `- ⚠ **${h.check}**${h.since ? ` (desde ${h.since})` : ''} — ${sanitizeCell(recorta(h.evidence, 130))}`);
     // Auto-remediación fase 2: la cola entra en cada sesión para que el agente
     // se OFREZCA a atacarla — proponer con plan y esperar el OK del humano,
     // nunca ejecutar por su cuenta. Títulos deduplicados (la cola real puede
@@ -489,7 +520,7 @@ maxCitas = CITAS_GRATIS) {
     const taskLines = taskTitles.length > 0
         ? [
             `- Hay ${pendingTasks.length} encargo(s) pendientes en la cola de este proyecto. Propón cuál atacarías. Cola viva: \`atlas_pending_tasks\`; cierra con \`atlas_complete_task\`.`,
-            ...taskTitles.map((t) => `- ${sanitizeCell(t.slice(0, 120))}`),
+            ...taskTitles.map((t) => `- ${sanitizeCell(recorta(t, 120))}`),
         ]
         : [];
     // El orden de renderizado (legibilidad) y la prioridad de presupuesto (qué se

package/dist/toolActionPlan.js

@@ -0,0 +1,98 @@
+/**
+ * `atlas_action_plan`: qué arreglar primero, en una sola lista priorizada.
+ *
+ * PORTADA DEL HOSPEDADO EL 09/08. Existía allí desde el 24/07 (`333c49a`).
+ *
+ * POR TIERS EXPLÍCITOS Y NO POR UNA PUNTUACIÓN: un número oculto obliga a
+ * confiar; cuatro tiers con nombre —regresión abierta, control de salud roto,
+ * hotspot, reincidente— dejan discutir el orden. Es agregación pura de señales
+ * que el atlas ya tiene: no dispara ningún análisis nuevo.
+ */
+import { z } from "zod";
+import { alertasDesde, briefModules, buildActionPlan, computeRecidivism, lineaDePrecision, projectIdFromFilter, recordRead, } from "./agregados.js";
+import { aliasesFor, canonicalizeModuleRows } from "./aliasDeModulo.js";
+import { RO, errorResult, servedCharsOf, toolResult, } from "./respuestas.js";
+import { summarizeHealth } from "./sync.js";
+export function registrarActionPlan(server, db) {
+    server.registerTool("atlas_action_plan", {
+        title: "Action plan (what to fix first)",
+        description: "A single prioritized list of what to address in this project, most urgent first: open regressions (a change already broke something), at-risk health controls (a safety posture the analysis flagged), hotspot modules (fragile by design) and repeat-offender modules. Pure aggregation of signals the atlas already holds — no new analysis, ordered by transparent severity tiers rather than a hidden score. Use it to decide where to start, then ANNOUNCE your pick and wait for the user's OK before acting. " +
+            "project: the repo you are working in (folder name or slug).",
+        inputSchema: { project: z.string().min(1).max(120) },
+        annotations: RO,
+    }, async ({ project }) => {
+        const t0 = Date.now();
+        try {
+            const pf = await db.projectFilterFor(project);
+            const projectId = projectIdFromFilter(pf);
+            const [modRowsCrudas, alertRowsCrudas, healthRows, { aliases }] = await Promise.all([
+                db.rest(`change_module?select=changelog_id,module,domain,risk,created_at&order=created_at.desc&limit=1000${pf}`),
+                db
+                    .rest(
+                // SIN `created_at=gte` A PROPÓSITO. Esta lectura sirve a DOS
+                // cosas con criterios de edad OPUESTOS: las regresiones abiertas
+                // (que sí quieren la ventana de 14 días) y la reincidencia (que
+                // la quiere all-time — recortarla borraría el historial que
+                // justifica llamar reincidente a un módulo). La ventana se
+                // aplica abajo, sobre estas mismas filas.
+                `regression_alerts?select=module,plain,resolution,resolved_at,created_at&order=created_at.desc&limit=500${pf}`)
+                    .catch(() => []),
+                db
+                    .rest(`project_checks?select=check_id,status,evidence,updated_at&order=updated_at.desc&limit=8${pf}`)
+                    .catch(() => []),
+                aliasesFor(db, projectId),
+            ]);
+            // LAS DOS, y antes de nada: `modules` alimenta los hotspots del plan y
+            // `alertRows` la reincidencia. Canonicalizar una sola haría que el plan
+            // hablara de un módulo con la reincidencia de otro.
+            const modRows = canonicalizeModuleRows(modRowsCrudas, aliases);
+            const alertRows = canonicalizeModuleRows(alertRowsCrudas, aliases);
+            const { modules } = briefModules(modRows);
+            const desde = alertasDesde();
+            const openAlerts = alertRows.filter((a) => !a.resolved_at && a.created_at >= desde);
+            const recidivism = computeRecidivism(alertRows);
+            const health = summarizeHealth(healthRows);
+            const plan = buildActionPlan({
+                alerts: openAlerts,
+                atRiskHealth: health.at_risk,
+                modules,
+                recidivism,
+            });
+            const lines = [`# ${project} — action plan`, ""];
+            if (plan.length === 0) {
+                lines.push("Nothing flagged: no open regressions, no at-risk health controls, no hotspot or repeat-offender modules. Nothing the atlas can point at right now.");
+            }
+            else {
+                lines.push(`${plan.length} item(s), most urgent first:`, "");
+                for (const it of plan) {
+                    lines.push(`${it.rank}. **${it.what}** — ${it.why}`);
+                }
+                lines.push("", "ANNOUNCE to the user which item you'd start with and why, and wait " +
+                    "for their OK before touching code. They cannot see this plan.");
+            }
+            // ¿ACERTAMOS? Al final, no al principio: el plan es lo accionable y el
+            // número es el respaldo. Del MISMO RPC que sirve el panel del dueño: si
+            // el agente y la persona vieran cifras distintas, el número dejaría de
+            // valer para los dos. Best-effort — un plan útil no puede caerse por su
+            // respaldo.
+            if (projectId) {
+                const precision = await db
+                    .callRpc("atlas_precision", {
+                    p_user_id: null,
+                    p_project_id: projectId,
+                })
+                    .catch(() => null);
+                const linea = lineaDePrecision(precision);
+                if (linea)
+                    lines.push("", linea);
+            }
+            const salida = toolResult(lines.join("\n"), { project, plan });
+            recordRead(db, "atlas_action_plan", pf, servedCharsOf(salida), Date.now() - t0);
+            return salida;
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=toolActionPlan.js.map

package/dist/toolProjectBrief.js

@@ -0,0 +1,310 @@
+/**
+ * `atlas_project_brief`: el brief de orientación, la herramienta que abre cada
+ * sesión.
+ *
+ * PORTADA DEL HOSPEDADO EL 09/08. Existía allí desde el 18/07 (`9a8387a`) y el
+ * bloque de CLAUDE.md que escribe este mismo paquete decía «orientarte →
+ * `atlas_project_brief`» desde entonces. Quien instalaba por npm leía la orden
+ * en cada sesión y no tenía con qué cumplirla.
+ *
+ * VIVE EN SU PROPIO FICHERO, y no por estética: `tools.ts` iba por 1.900 líneas
+ * y esto son otras 300. Es el mismo corte que el hospedado hizo el 03/08
+ * (AUD-C11). Los agregados puros que necesita salieron antes a `agregados.ts`,
+ * porque pedírselos a `tools.ts` —que importa este módulo para registrarlo—
+ * cerraría un ciclo.
+ *
+ * UNA LLAMADA, NO CUATRO. Cada llamada extra del agente relee ~45k tokens de
+ * contexto fijo (anatomía medida en el benchmark del 2026-07-20), mientras que
+ * los joins de aquí cuestan milisegundos. Por eso `intent` ENSANCHA esta misma
+ * llamada en vez de sugerir otra.
+ */
+import { z } from "zod";
+import { MODULE_GRAPH_WINDOW_ROWS, aggregateFileContext, briefModules, commitLabel, computeRecidivism, fileContainsFilter, filesUnionByChange, normalizeRepoPath, projectIdFromFilter, quotedInList, recordRead, } from "./agregados.js";
+import { aliasesFor, canonicalizeModuleRows } from "./aliasDeModulo.js";
+import { bloqueDeFriccion, consultaDeSucesos, friccionParaStructured, } from "./friccionDelBrief.js";
+import { RO, day, errorResult, ilikePattern, servedCharsOf, toolResult, } from "./respuestas.js";
+import { coChangePairs, summarizeHealth } from "./sync.js";
+/**
+ * Ventana de filas de `change_module` sobre la que se calcula el mapa.
+ *
+ * ES UNA VENTANA, NO UN CENSO, y el brief lo dice con esas palabras. Medido el
+ * 2026-08-03: la ventana estaba llena al ras, así que el número de módulos BAJA
+ * según se trabaja. Llamarlo «total» hacía leer eso como módulos que
+ * desaparecen.
+ */
+const MODULE_WINDOW = MODULE_GRAPH_WINDOW_ROWS;
+const MAX_ALERTS = 10;
+const MAX_TASKS = 10;
+export function registrarProjectBrief(server, db) {
+    server.registerTool("atlas_project_brief", {
+        title: "Project brief (start here)",
+        description: "Call this FIRST, the moment a session opens, to get your bearings: it hands you the module map with risks, the open regression alerts, the project health (which safety controls the analysis has evidenced as passing or at-risk), the tasks the owner queued for you, and the latest analyzed changes — ONE call that replaces atlas_modules + atlas_pending_tasks + atlas_recent_changes. Optional intent widens the SAME call (never a second trip): intent=orient serves 10 recent changes with commit+files; intent=pre_edit with files=[paths] appends each file's modules, notes and current watched values; intent=feature with feature=\"text\" appends the changes matching that text. After reading it, tell the user in 1-3 lines what you found and what you plan to do, and WAIT for their OK before editing any code — announcing and then editing in the same turn leaves the owner nothing to decide. " +
+            "project: the repo you are working in (folder name or slug).",
+        inputSchema: {
+            project: z.string().min(1).max(120),
+            intent: z.enum(["orient", "pre_edit", "feature"]).optional(),
+            files: z.array(z.string().min(1).max(300)).min(1).max(8).optional(),
+            feature: z.string().min(2).max(120).optional(),
+        },
+        annotations: RO,
+    }, async ({ project, intent, files, feature }) => {
+        const t0 = Date.now();
+        try {
+            const pf = await db.projectFilterFor(project);
+            const projectId = projectIdFromFilter(pf);
+            // intent=orient sirve 10 cambios en vez de 5: la tarea de orientación
+            // del benchmark pide «los 10 commits más recientes», y con 5 el agente
+            // gastaba una segunda llamada para el resto.
+            const changesLimit = intent === "orient" ? 10 : 5;
+            // TODO EN PARALELO. Son consultas independientes y el arranque del
+            // agente es tiempo que el usuario ve. Las que pueden faltar por tabla
+            // ausente caen a vacío en vez de tumbar el brief entero.
+            const [modRowsCrudas, alertsCrudas, changes, healthRows, tasks, unanalyzed, { aliases }, filasDeFriccion,] = await Promise.all([
+                db.rest(`change_module?select=changelog_id,module,domain,risk,files,note,created_at` +
+                    `&order=created_at.desc&limit=${MODULE_WINDOW}${pf}`),
+                db
+                    .rest(`regression_alerts?select=id,module,plain,created_at,evidence_symbol,evidence_expect,evidence_scope,evidence_line,evidence_in_diff` +
+                    `&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}${pf}`)
+                    .catch(() => []),
+                db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash,hash_aliases` +
+                    `&order=created_at.desc&limit=${changesLimit}${pf}`),
+                db
+                    .rest(`project_checks?select=check_id,status,evidence,updated_at&order=updated_at.desc&limit=8${pf}`)
+                    .catch(() => []),
+                projectId
+                    ? db
+                        .callRpc("list_agent_tasks", {
+                        p_project_id: projectId,
+                    })
+                        .then((rows) => rows.filter((r) => r.status === "pending").slice(0, MAX_TASKS))
+                        .catch(() => [])
+                    : Promise.resolve([]),
+                db
+                    .rest(`unanalyzed_commits?select=commit_hash,committed_at,reason&order=committed_at.asc&limit=200${pf}`)
+                    .catch(() => []),
+                aliasesFor(db, projectId),
+                // Dónde hay que rehacer el trabajo. Va en el MISMO viaje: son 8 filas
+                // en 30 días (medido), así que no añade latencia al arranque. Cae a
+                // vacío si la tabla no está, en vez de tumbar el brief.
+                db
+                    .rest(consultaDeSucesos(pf, Date.now()))
+                    .catch(() => []),
+            ]);
+            // SE CANONICALIZA AQUÍ Y UNA VEZ. `briefModules`, `coChangePairs` y
+            // `computeRecidivism` son puras sobre estas filas: resolviendo alias
+            // antes, las tres ven lo mismo. Resolver dentro de cada una es cómo la
+            // identidad del módulo acabó viviendo en tres sitios y divergiendo.
+            const modRows = canonicalizeModuleRows(modRowsCrudas, aliases);
+            const alerts = canonicalizeModuleRows(alertsCrudas, aliases);
+            const { modules, total: modulesTotal } = briefModules(modRows);
+            const parejas = coChangePairs(modRows);
+            const recidivism = computeRecidivism(alertsCrudas.map((a) => ({
+                module: a.module ?? null,
+                plain: a.plain ?? null,
+                resolution: a.resolution,
+            })));
+            const health = summarizeHealth(healthRows);
+            const filesByChange = filesUnionByChange(modRowsCrudas);
+            const lines = [`# ${project} — project brief`, ""];
+            // ARRIBA DEL TODO. Si el mapa está incompleto, eso condiciona todo lo
+            // que viene detrás y hay que saberlo ANTES de leerlo, no en una nota al
+            // pie.
+            if (unanalyzed.length > 0) {
+                const oldest = unanalyzed[0]?.committed_at;
+                // LA CAUSA CAMBIA LO QUE EL USUARIO TIENE QUE HACER, así que cambia
+                // lo que se le dice. Culparle de su cuota cuando el que falló fue
+                // ChangeBook sería mentirle, y encima le empujaría a pagar por algo
+                // que no arregla nada (incidente del 2026-07-19).
+                const provider = unanalyzed.filter((u) => u.reason === "provider_error").length;
+                const quota = unanalyzed.length - provider;
+                const causa = provider > 0 && quota > 0
+                    ? `${quota} because the monthly analysis quota ran out, and ${provider} because ChangeBook could not reach the AI (a ChangeBook-side failure, not the user's fault)`
+                    : provider > 0
+                        ? `because ChangeBook could not reach the AI. This is a ChangeBook-side failure, NOT the user's quota and NOT their fault — they do not need to upgrade or pay anything`
+                        : `because the monthly analysis quota ran out`;
+                const salida = provider > 0 && quota === 0
+                    ? `They will be analyzable once the service recovers.`
+                    : `Their atlas will keep drifting until the quota renews on the 1st or they upgrade.`;
+                lines.push(`> **This atlas is out of date.** ${unanalyzed.length} commit(s) ` +
+                    `could not be analyzed${oldest ? ` (oldest: ${day(oldest)})` : ""} ` +
+                    `${causa}. Their files and commit messages were recorded, but they ` +
+                    `have no narrated summary and no regression check. Treat the module ` +
+                    `map below as missing those changes, and TELL THE USER. ${salida}`, "");
+            }
+            lines.push(modulesTotal > modules.length
+                ? `## Modules (${modules.length} most recent of ${modulesTotal} seen in the last ${MODULE_WINDOW} changes — all of them in atlas_modules, same window)`
+                : `## Modules (${modulesTotal} in the last ${MODULE_WINDOW} changes)`);
+            for (const m of modules) {
+                // Reincidente: N problemas de regresión DISTINTOS a lo largo del
+                // tiempo. Es un hecho de los datos, no una corazonada.
+                const previas = recidivism.get(m.module);
+                lines.push(`- **${m.module}**${m.domain ? ` · ${m.domain}` : ""} — ${m.changes} change(s), last ${m.last_changed}` +
+                    (m.risk ? `, risk: ${m.risk}` : "") +
+                    (previas ? ` · ⚠ ${previas} prior regressions` : ""));
+            }
+            if (parejas.length > 0) {
+                lines.push("", "## Change together (touch one, check the other)");
+                for (const p of parejas) {
+                    lines.push(`- **${p.a}** ↔ **${p.b}** — together in ${Math.round(p.rate * 100)}% of their changes`);
+                }
+            }
+            // Devuelve [] cuando no hay nada que decir, así que no deja cabecera
+            // huérfana. Va ANTES de los avisos abiertos, igual que en el hospedado.
+            lines.push(...bloqueDeFriccion(filasDeFriccion));
+            lines.push("", `## Open regression alerts (${alerts.length})`);
+            if (alerts.length === 0)
+                lines.push("None — no open alerts.");
+            for (const a of alerts) {
+                lines.push(`- ${(a.created_at ?? "").slice(0, 10)}${a.module ? ` · **${a.module}**` : ""} — ${a.plain ?? ""}`);
+            }
+            if (alerts.length > 0) {
+                lines.push("", "SAY THIS OUT LOUD to the user, in one or two lines, before you start " +
+                    "working. They cannot see this brief. A warning you absorb silently and " +
+                    "route around is indistinguishable, from where they sit, from a product " +
+                    "that does nothing: they paid for this and never learn it fired. Name the " +
+                    "module and what it puts at risk, in plain language, and only then get on " +
+                    "with the task. Once you FIX or verify one, call atlas_resolve_alert({ " +
+                    "project, module, verdict }) so it stops being re-raised and stops re-queuing " +
+                    "the owner's task — an alert nobody closes is billed forever.");
+            }
+            lines.push("", `## Project health (${health.passed} passed, ${health.at_risk.length} at risk)`);
+            if (healthRows.length === 0) {
+                lines.push("Not yet evidenced — no analyzed change has touched a health control yet.");
+            }
+            else if (health.at_risk.length === 0) {
+                lines.push("All evidenced controls passing.");
+            }
+            else {
+                for (const h of health.at_risk) {
+                    lines.push(`- ⚠ **${h.check}** at risk${h.since ? ` (since ${h.since})` : ""} — ${h.evidence}`);
+                }
+                lines.push("", "SAY THIS OUT LOUD to the user before you edit: a health control the " +
+                    "analysis already caught as at-risk (an unauthorized endpoint, a " +
+                    "hardcoded secret, a table-wide grant) is exactly what they cannot " +
+                    "see. Name it in plain language, then get on with the task.");
+            }
+            lines.push("", `## Tasks the owner queued for you (${tasks.length})`);
+            if (tasks.length === 0)
+                lines.push("None pending.");
+            for (const t of tasks)
+                lines.push(`- [${t.id}] ${t.title}`);
+            if (tasks.length > 0) {
+                lines.push("", "Fetch a task's full body with atlas_pending_tasks({ task_id }). Tell the user which task you picked and your plan, and WAIT for their OK before touching code.");
+            }
+            lines.push("", `## Latest changes`);
+            for (const c of changes) {
+                // Con aliases post-squash: `abc1234 (=def5678)` — si el primero no
+                // existe en el main del lector, el segundo sí.
+                const commit = commitLabel(c.commit_hash, c.hash_aliases);
+                lines.push(`- ${day(c.created_at)}${commit ? ` · ${commit}` : ""} — ${c.business_impact ?? ""}`);
+                const served = filesByChange.get(c.id);
+                if (served && served.files.length > 0) {
+                    lines.push(`  files: ${served.files.join(", ")}${served.more > 0 ? ` (+${served.more} more)` : ""}`);
+                }
+            }
+            // ── intent=pre_edit: el contexto por fichero, en ESTA misma llamada ──
+            let preEdit = [];
+            if (intent === "pre_edit" && files && files.length > 0) {
+                const paths = [...new Set(files.map(normalizeRepoPath).filter(Boolean))];
+                const [perFileCrudo, watchedRows] = await Promise.all([
+                    Promise.all(paths.map((p) => db
+                        .rest(`change_module?select=changelog_id,module,risk,note,created_at&${fileContainsFilter(p)}&order=created_at.desc&limit=20${pf}`)
+                        .then((rows) => ({ p, rows })))),
+                    db
+                        .rest(`watched_values?select=file,name,value,commit_hash&file=in.(${encodeURIComponent(quotedInList(paths))})&order=name.asc&limit=40${pf}`)
+                        .catch(() => []),
+                ]);
+                // La agregación va DESPUÉS de canonicalizar: `aggregateFileContext`
+                // agrupa por slug, y canonicalizar después dejaría dos grupos para el
+                // mismo módulo.
+                preEdit = perFileCrudo.map(({ p, rows }) => {
+                    const { file, modules: mods } = aggregateFileContext(p, canonicalizeModuleRows(rows, aliases));
+                    return {
+                        file,
+                        modules: mods,
+                        watched_values: watchedRows
+                            .filter((w) => w.file === file)
+                            .map((w) => ({
+                            name: w.name,
+                            value: w.value,
+                            commit: w.commit_hash?.slice(0, 7) ?? null,
+                        })),
+                    };
+                });
+                lines.push("", `## Pre-edit context (${preEdit.length} file(s))`);
+                for (const f of preEdit) {
+                    lines.push(`### ${f.file}`);
+                    if (f.modules.length === 0) {
+                        lines.push("No atlas history for this file yet (new or never analyzed).");
+                    }
+                    for (const m of f.modules) {
+                        lines.push(`- Module **${m.module}** — ${m.changes} change(s), last ${m.last_changed}` +
+                            (m.risk ? `, risk: ${m.risk}` : ""));
+                        if (m.last_note) {
+                            lines.push(`  - Note from last analysis (${m.last_changed}): ${m.last_note}`);
+                        }
+                    }
+                    for (const w of f.watched_values) {
+                        lines.push(`- Current value: ${w.name} = ${w.value}` +
+                            (w.commit ? ` (as of commit ${w.commit})` : ""));
+                    }
+                }
+            }
+            else if (intent === "pre_edit") {
+                lines.push("", "intent=pre_edit needs files=[paths]; nothing appended.");
+            }
+            // ── intent=feature: los cambios que casan con un texto ───────────────
+            let featureMatches = [];
+            if (intent === "feature" && feature) {
+                const patron = ilikePattern(feature);
+                const rows = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash,hash_aliases` +
+                    `&or=(business_impact.ilike.${patron},summary_tech.ilike.${patron})&order=created_at.desc&limit=5${pf}`);
+                featureMatches = rows.map((r) => ({
+                    date: day(r.created_at),
+                    commit: commitLabel(r.commit_hash, r.hash_aliases),
+                    business_impact: r.business_impact ?? "",
+                }));
+                lines.push("", `## Changes matching "${feature}" (${rows.length})`);
+                if (rows.length === 0) {
+                    lines.push("No analyzed change mentions it.");
+                }
+                for (const m of featureMatches) {
+                    lines.push(`- ${m.date}${m.commit ? ` · ${m.commit}` : ""} — ${m.business_impact}`);
+                }
+            }
+            else if (intent === "feature") {
+                lines.push("", 'intent=feature needs feature="text"; nothing appended.');
+            }
+            const salida = toolResult(lines.join("\n"), {
+                project,
+                modules,
+                modules_total: modulesTotal,
+                couplings: parejas,
+                // Paridad con el texto, igual que en el hospedado: sin esto, lo único
+                // que dice dónde se rehace trabajo vive SÓLO dentro del markdown.
+                friction: friccionParaStructured(filasDeFriccion),
+                alerts: alerts.map((a) => ({
+                    module: a.module,
+                    plain: a.plain,
+                    created_at: a.created_at ?? null,
+                })),
+                health,
+                tasks: tasks.map((t) => ({ id: t.id, title: t.title })),
+                changes: changes.map((c) => ({
+                    date: day(c.created_at),
+                    commit: commitLabel(c.commit_hash, c.hash_aliases),
+                    business_impact: c.business_impact ?? "",
+                })),
+                unanalyzed: unanalyzed.length,
+                ...(preEdit.length > 0 ? { pre_edit: preEdit } : {}),
+                ...(featureMatches.length > 0 ? { feature_matches: featureMatches } : {}),
+            });
+            recordRead(db, "atlas_project_brief", pf, servedCharsOf(salida), Date.now() - t0);
+            return salida;
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=toolProjectBrief.js.map