changebook 0.4.0 → 0.4.2

package/dist/analyze.js

@@ -6,7 +6,7 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, } from "./git.js";
+import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
 import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI, truncateAtFileBoundary } from "./optimize.js";
 export async function analyze(db, options = {}) {
@@ -15,10 +15,16 @@ export async function analyze(db, options = {}) {
     let rawDiff;
     let commitHash;
     let committedAt;
+    // El mensaje del commit como resumen: enruta al modelo pequeño en el servidor
+    // (~3 veces más barato). Este es el camino del hook post-commit, o sea el que
+    // dispara en CADA commit, así que es donde más veces se cobra la diferencia.
+    // Analizando cambios sin commitear no hay mensaje todavía: va sin resumen.
+    let agentSummary;
     if (options.commit) {
         const meta = await commitMeta(cwd, options.commit);
         commitHash = meta.hash;
         committedAt = meta.committedAt;
+        agentSummary = usableSummary(meta.message) ?? undefined;
         rawDiff = await commitDiff(cwd, meta.hash);
         if (!rawDiff.trim()) {
             console.error(`Commit ${meta.hash.slice(0, 8)} has no analyzable diff (merge?). Skipped.`);
@@ -53,6 +59,7 @@ export async function analyze(db, options = {}) {
         projectName,
         commitHash,
         committedAt,
+        agentSummary,
     });
     if (status !== 200 || body.error) {
         // The server's messages are user-facing (quota, waitlist…): pass through.
@@ -94,11 +101,22 @@ async function commitMeta(cwd, ref) {
         const { stdout } = await execFileAsync("git", 
         // --end-of-options so a user-supplied ref beginning with "-" is treated as
         // a revision, not as a git option.
-        ["log", "-1", "--pretty=format:%H|%cI", "--end-of-options", ref], { cwd, encoding: "utf8" });
-        const [hash, committedAt] = stdout.trim().split("|");
+        // %B (mensaje entero) va detrás de la fecha a propósito: es el único
+        // campo que puede llevar "|" y saltos de línea, así que se corta por los
+        // DOS primeros separadores y el resto se queda entero. Con -1 no hace
+        // falta -z: solo hay un registro.
+        ["log", "-1", "--pretty=format:%H|%cI|%B", "--end-of-options", ref], { cwd, encoding: "utf8" });
+        const raw = stdout.trim();
+        const firstPipe = raw.indexOf("|");
+        const secondPipe = raw.indexOf("|", firstPipe + 1);
+        const hash = firstPipe < 0 ? raw : raw.slice(0, firstPipe);
         if (!hash)
             throw new Error("empty git log output");
-        return { hash, committedAt };
+        return {
+            hash,
+            committedAt: secondPipe < 0 ? raw.slice(firstPipe + 1) : raw.slice(firstPipe + 1, secondPipe),
+            message: secondPipe < 0 ? "" : raw.slice(secondPipe + 1),
+        };
     }
     catch (error) {
         throw new Error(`Could not resolve commit "${ref}" in "${cwd}": ${gitErrorMessage(error)}`);

package/dist/git.js

@@ -11,6 +11,40 @@ export const GIT_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 // Mirror of the extension's default changebook.maxDiffCharacters (the server
 // rejects anything above 60k anyway).
 export const MAX_DIFF_CHARACTERS = 25_000;
+// ── El mensaje de commit como resumen ────────────────────────────────────────
+// El mensaje, cuando dice algo, ES el resumen del cambio: lo escribió quien lo
+// hizo y explica la intención, que es la mitad cara del análisis y la única que
+// el servidor no puede reconstruir del diff. Mandarlo hace que el servidor
+// enrute al modelo pequeño: medido, $0,063 contra $0,021 = 3 veces menos.
+//
+// Vive aquí por lo mismo que commitDiff: lo usan los DOS subcomandos (`analyze`,
+// que es el hook post-commit, e `import`, que es la historia), y tenerlo en uno
+// solo es exactamente el fallo que dejó al otro pagando el modelo caro.
+//
+// Copia deliberada de la del servidor (_shared/github.ts) y de la de la
+// extensión (src/util/summary.ts): los tres artefactos se publican por separado
+// y tienen que ser autocontenidos, igual que canonicalDiffHash.
+// test/summaryParity.test.ts fija que no se separen — si lo hacen no falla
+// nada, solo cambia la factura.
+//
+// Los dos filtros: un mensaje pobre ("fix", "wip") NO se manda, porque el
+// modelo pequeño se APOYA en el resumen y alimentarlo con ruido daría un
+// análisis peor Y más barato; y el largo se recorta por línea entera, porque el
+// servidor RECHAZA los que se pasan y un 400 no encarecería el análisis: lo
+// dejaría sin hacer.
+const MIN_USEFUL_SUMMARY_CHARS = 40;
+const MAX_AGENT_SUMMARY_CHARS = 2_400;
+/** El mensaje si sirve como resumen, recortado por línea entera; si no, null. */
+export function usableSummary(message) {
+    const text = message.trim();
+    if (text.length < MIN_USEFUL_SUMMARY_CHARS)
+        return null;
+    if (text.length <= MAX_AGENT_SUMMARY_CHARS)
+        return text;
+    const cut = text.slice(0, MAX_AGENT_SUMMARY_CHARS);
+    const lastBreak = cut.lastIndexOf("\n");
+    return (lastBreak > MIN_USEFUL_SUMMARY_CHARS ? cut.slice(0, lastBreak) : cut).trim();
+}
 /** `git show <hash> -U0` — the unified diff of a single commit, no context. */
 export async function commitDiff(cwd, hash) {
     try {

package/dist/guard.js

@@ -14,6 +14,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { execFileSync } from "node:child_process";
 import { execFileAsync } from "./git.js";
 /** Exit code that asks the pre-commit hook to abort the commit. */
 export const EXIT_BLOCK = 3;
@@ -71,8 +72,61 @@ export function moduleFilesUnion(rows) {
     }
     return new Map([...map.entries()].map(([k, v]) => [k, [...v]]));
 }
-/** Open alerts × staged files → warnings, deduped by (module, message). */
-export function guardFindings(staged, alerts, filesByModule) {
+/** Rutas propias del aviso, si las trae. */
+function alertFiles(alert) {
+    return Array.isArray(alert.files)
+        ? alert.files.filter((f) => typeof f === "string")
+        : [];
+}
+/**
+ * ¿Se contradice el aviso con el codigo que hay delante?
+ *
+ * Devuelve `true` SOLO cuando la evidencia lo tumba de forma inequivoca. Sin
+ * evidencia, con el simbolo vacio o si la busqueda falla, devuelve `false`: la
+ * duda deja pasar el aviso. Un guardian que se calla por un error de disco es
+ * peor que uno ruidoso — misma leccion que el limitador que fallaba abierto y
+ * nadie noto en nueve dias.
+ *
+ * `buscar` devuelve cuantas veces aparece el simbolo, o null si no se pudo
+ * mirar.
+ */
+export function avisoRefutado(alert, buscar) {
+    const simbolo = (alert.evidence_symbol ?? "").trim();
+    const espera = alert.evidence_expect;
+    if (!simbolo || (espera !== "present" && espera !== "absent"))
+        return false;
+    let apariciones;
+    try {
+        apariciones = buscar(simbolo);
+    }
+    catch {
+        return false;
+    }
+    if (apariciones === null)
+        return false;
+    // "present": el aviso vive de que el simbolo siga ahi. Si ya no esta, el
+    // conflicto que describia no puede darse — es el caso de las 3 alertas del
+    // renombrado latestFilesByModule -> moduleFilesUnion: cero referencias.
+    if (espera === "present")
+        return apariciones === 0;
+    // "absent": el aviso vive de que algo FALTE. Si aparece, ya esta hecho.
+    return apariciones > 0;
+}
+/**
+ * Open alerts × staged files → warnings, deduped by (module, message).
+ *
+ * Dos filtros, los dos nacidos de medir los avisos reales del 2026-07-19.
+ *
+ * 1. A QUIEN se avisa. Antes se cruzaba contra `filesByModule`: TODOS los
+ *    ficheros que alguna vez tocaron ese modulo. Por eso un aviso sobre
+ *    `i18n.ts` saltaba al preparar `mcp/index.ts` — comparten modulo. Si el
+ *    aviso trae sus propias rutas mandan esas; si no, se cae al modulo entero
+ *    como antes, porque los avisos anteriores no las tienen.
+ *
+ * 2. SI SIGUE EN PIE. `refutado` lo decide quien llama, que es quien tiene el
+ *    arbol de trabajo. De 7 avisos abiertos, 4 se caian con un grep.
+ */
+export function guardFindings(staged, alerts, filesByModule, refutado) {
     const stagedSet = new Set(staged);
     const seen = new Set();
     const findings = [];
@@ -81,9 +135,17 @@ export function guardFindings(staged, alerts, filesByModule) {
         const plain = (alert.plain ?? "").trim();
         if (!module || !plain)
             continue;
-        const touched = (filesByModule.get(module) ?? []).filter((f) => stagedSet.has(f));
+        // Las rutas del aviso mandan sobre las del modulo: dicen de QUE va, no solo
+        // a que cajon pertenece.
+        const propias = alertFiles(alert);
+        const ambito = propias.length > 0 ? propias : (filesByModule.get(module) ?? []);
+        const touched = ambito.filter((f) => stagedSet.has(f));
         if (touched.length === 0)
             continue;
+        // Se refuta DESPUES de acotar: si el aviso no te toca, no hay por que
+        // gastar una lectura de disco en tumbarlo.
+        if (refutado?.(alert))
+            continue;
         const key = module + "\u0000" + plain;
         if (seen.has(key))
             continue;
@@ -92,6 +154,48 @@ export function guardFindings(staged, alerts, filesByModule) {
     }
     return findings;
 }
+/**
+ * Cuantas veces aparece un simbolo en el codigo versionado. `null` si no se
+ * pudo mirar — y ese `null` importa: hace que el aviso pase, no que se calle.
+ *
+ * `git grep` y no un recorrido propio: respeta .gitignore, no entra en
+ * node_modules y esta escrito en C. Sobre este repo tarda ~30 ms, asi que cabe
+ * de sobra en el presupuesto de 3,5 s del guardian.
+ *
+ * `--fixed-strings` es obligatorio: el simbolo viene de un modelo y un `$` o un
+ * `.` sueltos lo convertirian en otra expresion regular.
+ */
+export function contarEnRepo(dir, simbolo) {
+    if (!/^[A-Za-z_$][\w$.]{1,118}$/.test(simbolo))
+        return null;
+    try {
+        const out = execFileSync("git", [
+            "grep",
+            "--fixed-strings",
+            "--count",
+            "--",
+            simbolo,
+            // Se busca en CODIGO, nunca en prosa. Sin esto el mecanismo nace
+            // inutil: el propio `sync` escribe el texto de las alertas en
+            // CLAUDE.md y AGENTS.md, y ese texto CONTIENE el simbolo. Cualquier
+            // aviso de tipo "esto sigue usandose" encontraria su propia cita y no
+            // podria refutarse jamas. Lo cazo el test, no el diseno.
+            ":!*.md",
+            ":!docs/",
+        ], { cwd: dir, encoding: "utf8", timeout: 2_000, maxBuffer: 4 * 1024 * 1024 });
+        // Una linea "fichero:N" por fichero con coincidencias.
+        return out
+            .split("\n")
+            .filter(Boolean)
+            .reduce((n, l) => n + (Number(l.slice(l.lastIndexOf(":") + 1)) || 0), 0);
+    }
+    catch (e) {
+        // git grep sale con 1 cuando NO hay coincidencias: eso es un cero real, no
+        // un fallo. Cualquier otro codigo si es "no he podido mirar".
+        const code = e.status;
+        return code === 1 ? 0 : null;
+    }
+}
 async function gitPath(dir, name) {
     const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", name], { cwd: dir, encoding: "utf8" });
     return path.resolve(dir, stdout.trim());
@@ -140,7 +244,7 @@ async function fetchSignals(db, dir, env) {
     let filesByModule = new Map();
     const projectId = projects[0]?.id ?? null;
     if (projectId) {
-        alerts = await db.rest(`regression_alerts?select=module,plain,created_at&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
+        alerts = await db.rest(`regression_alerts?select=module,plain,created_at,evidence_symbol,evidence_expect,files&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
         const modules = [
             ...new Set(alerts.map((a) => (a.module ?? "").trim()).filter(Boolean)),
         ];
@@ -175,15 +279,27 @@ async function logRun(dir, message) {
         // Best-effort only.
     }
 }
-function printFindings(findings, block) {
-    console.error(`\n⚠ ChangeBook: ${findings.length === 1 ? "an open alert" : `${findings.length} open alerts`} on what you're about to commit:\n`);
+/**
+ * El aviso que ve el humano, como texto.
+ *
+ * Se construye aparte de imprimirlo para poder MEDIRLO: es lo que el guardián
+ * sirve de verdad, y su longitud es lo que se registra como chars_served
+ * (QA 2026-07-19). Cadena vacía cuando no hay nada que avisar.
+ */
+export function findingsMessage(findings, block) {
+    if (findings.length === 0)
+        return "";
+    const lines = [
+        `\n⚠ ChangeBook: ${findings.length === 1 ? "an open alert" : `${findings.length} open alerts`} on what you're about to commit:\n`,
+    ];
     for (const f of findings) {
-        console.error(`  • ${f.module} — ${f.plain}`);
-        console.error(`    staged: ${f.staged.slice(0, 5).join(", ")}`);
+        lines.push(`  • ${f.module} — ${f.plain}`);
+        lines.push(`    staged: ${f.staged.slice(0, 5).join(", ")}`);
     }
-    console.error(block
+    lines.push(block
         ? "\nCommit blocked (CHANGEBOOK_GUARD=block). Review the alert in your atlas (changebook open) or bypass once with: git commit --no-verify\n"
         : "\nReview or dismiss the alert in your atlas: changebook open\n");
+    return lines.join("\n");
 }
 /**
  * Returns the process exit code. Everything that can go wrong resolves to 0
@@ -224,12 +340,22 @@ export async function runGuard(db, dir, env = process.env) {
         await logRun(dir, `timeout after ${GUARD_TIMEOUT_MS}ms — passing`);
         return 0;
     }
-    const findings = guardFindings(staged, signals.alerts, signals.filesByModule);
+    const findings = guardFindings(staged, signals.alerts, signals.filesByModule, (alert) => avisoRefutado(alert, (simbolo) => contarEnRepo(dir, simbolo)));
+    const block = mode === "block";
+    const message = findingsMessage(findings, block);
     // La consulta del guardián también es una consulta del atlas (QA
     // 2026-07-18: el contador solo veía las tools MCP y el trabajo más
     // constante del atlas era invisible). Solo las frescas — un rebase servido
     // de caché no re-consulta nada. Best-effort y ACOTADO: jamás puede
     // convertir un commit rápido en uno lento.
+    //
+    // chars_served = el aviso que el humano acaba viendo, 0 cuando todo está
+    // limpio (QA 2026-07-19). Antes se registraba siempre 0 y el guardián, que es
+    // el consumidor MÁS frecuente del atlas, no se distinguía de una consulta que
+    // no encontró nada. Con esto "revisó" y "avisó" son dos cosas separables en el
+    // dato, sin inventar ninguna valoración: esos caracteres se sirvieron de
+    // verdad. Lo que el guardián evita de verdad, un error, no se mide en
+    // caracteres y no se intenta.
     if (!signals.fromCache && signals.projectId) {
         await Promise.race([
             db
@@ -237,6 +363,7 @@ export async function runGuard(db, dir, env = process.env) {
                 project_id: signals.projectId,
                 tool: "guard_precommit",
                 source: "guard",
+                chars_served: message.length,
             })
                 .catch(() => { }),
             new Promise((resolve) => {
@@ -247,8 +374,7 @@ export async function runGuard(db, dir, env = process.env) {
     await logRun(dir, `staged=${staged.length} openAlerts=${signals.alerts.length} findings=${findings.length}`);
     if (findings.length === 0)
         return 0;
-    const block = mode === "block";
-    printFindings(findings, block);
+    console.error(message);
     return block ? EXIT_BLOCK : 0;
 }
 //# sourceMappingURL=guard.js.map

package/dist/import.js

@@ -10,7 +10,7 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, } from "./git.js";
+import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
 import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI } from "./optimize.js";
 // Under the server's MAX_BATCH_ITEMS (25) to leave headroom.
@@ -53,12 +53,16 @@ export async function importHistory(db, options = {}) {
             trivial += 1;
             continue;
         }
+        // El servidor decide con esto si enruta al modelo pequeño. Va opcional: un
+        // servidor antiguo lo ignora sin romperse.
+        const summary = usableSummary(commit.message);
         items.push({
             compressedDiff: compressed,
             rawDiffChars: diff.length,
             rawContentHash: canonicalDiffHash(diff),
             commitHash: commit.hash,
             committedAt: commit.date,
+            ...(summary ? { agentSummary: summary } : {}),
         });
     }
     if (items.length === 0) {
@@ -134,15 +138,34 @@ function sleep(ms) {
 // ── git helpers ───────────────────────────────────────────────────────────────
 async function listCommits(cwd, count) {
     try {
-        const { stdout } = await execFileAsync("git", ["log", "-n", String(count), "--no-merges", "--pretty=format:%H|%cI"], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
+        // -z separa los commits por NUL en vez de por salto de línea. Es
+        // obligatorio desde que se pide %B: el mensaje tiene saltos dentro, así que
+        // partir por "\n" mezclaría el cuerpo de un commit con el siguiente.
+        const { stdout } = await execFileAsync("git", [
+            "log",
+            "-n",
+            String(count),
+            "--no-merges",
+            "-z",
+            "--pretty=format:%H|%cI|%B",
+        ], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
         return stdout
-            .split("\n")
+            .split("\0")
             .filter(Boolean)
-            .map((line) => {
-            const [hash, date] = line.split("|");
-            return { hash, date };
+            .map((record) => {
+            // Solo los DOS primeros "|" son separadores: el hash y la fecha ISO no
+            // pueden contener uno, pero el mensaje sí, y hay que dejarlo entero.
+            const firstPipe = record.indexOf("|");
+            const secondPipe = record.indexOf("|", firstPipe + 1);
+            if (firstPipe < 0 || secondPipe < 0)
+                return null;
+            return {
+                hash: record.slice(0, firstPipe),
+                date: record.slice(firstPipe + 1, secondPipe),
+                message: record.slice(secondPipe + 1),
+            };
         })
-            .filter((c) => c.hash && c.date);
+            .filter((c) => c != null && !!c.hash && !!c.date);
     }
     catch (error) {
         const message = gitErrorMessage(error);

package/dist/supabase.js

@@ -111,6 +111,17 @@ export class Supabase {
             rows = await this.rest(`projects?select=id&name=eq.${encodeURIComponent(wanted)}&limit=1`);
         }
         if (rows.length === 0) {
+            // Con UN solo proyecto no hay frontera que proteger: el nombre sirve
+            // para elegir y no hay entre qué elegir. Fallar aquí gastaba una llamada
+            // entera para decir "no lo encuentro" cuando la respuesta era obvia — y
+            // pasa de verdad, porque el nombre que se manda es el basename del
+            // directorio y basta clonar el repo en una carpeta distinta.
+            //
+            // Espejo de decideScope en supabase/functions/mcp/scope.ts. Es lo que
+            // permite exigir `project` en el esquema sin quitarle nada a nadie.
+            const todos = await this.rest(`projects?select=id&limit=2`);
+            if (todos.length === 1)
+                return `&project_id=eq.${todos[0].id}`;
             throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name).`, 404);
         }
         return `&project_id=eq.${rows[0].id}`;

package/dist/sync.js

@@ -30,13 +30,22 @@ function sanitizeCell(text) {
 const MAX_MODULES = 15;
 const MAX_CHANGES = 5;
 const MAX_COUPLINGS = 5;
-// El bloque entra en CADA sesión de agente del usuario, así que tiene un
-// presupuesto fijo (~750 tokens) y nunca crece sin control. Cuando no cabe
-// todo, se recorta por prioridad: regresiones > encargos > acoplamientos >
-// hotspots > módulos > últimos cambios. Subido de 2.000 a 3.000 el
-// 2026-07-18: la cabecera ganó las reglas de frontera/aviso/file-context y
-// con 2.000 expulsaba Módulos y Encargos enteros del mapa.
-const SYNC_BUDGET_CHARS = 3_000;
+// El bloque entra en CADA sesión de agente del usuario, y ademas se reenvia al
+// modelo en CADA peticion de esa sesion: es coste FIJO, se consulte el atlas o
+// no. Por eso tiene presupuesto y nunca crece sin control.
+//
+// Historia de este numero, que es una leccion:
+//   2.000 -> 3.000 el 2026-07-18, porque la cabecera habia engordado y
+//            expulsaba Módulos y Encargos. Se subio el techo en vez de
+//            adelgazar la prosa.
+//   3.000 -> 2.000 el 2026-07-19, al medir que NO funciono: la cabecera crecio
+//            hasta 1.109 chars (46% del presupuesto) y la seccion "### Módulos"
+//            seguia expulsada. El bloque se llamaba "Mapa del producto" y salia
+//            sin mapa, en el commit mismo que subio el techo para evitarlo.
+//
+// Subir el techo alimenta al que se lo come. Adelgazada la cabecera a 271
+// chars, con 2.000 cabe mas contenido REAL que antes con 3.000.
+const SYNC_BUDGET_CHARS = 2_000;
 // Co-change pair thresholds — same spirit as the web's signals: at least 3
 // shared analyses and a ≥60% rate before we call it a dependency.
 const MIN_PAIR_COUNT = 3;
@@ -128,25 +137,31 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         // útiles ya van por entrada (regresiones, últimos cambios).
         "## Mapa del producto (ChangeBook · auto-generado)",
         "",
-        "Este proyecto tiene memoria en ChangeBook. Al EMPEZAR la sesión, oriéntate con UNA sola llamada a la tool MCP `atlas_project_brief` (mapa + alertas + encargos pendientes + últimos cambios); para profundizar: `atlas_module_detail` (detalle + diffs).",
+        // Esta cabecera se paga en CADA peticion de CADA sesion, se consulte el
+        // atlas o no, y ademas se reenvia al modelo cada vez. Medido el
+        // 2026-07-19: ocupaba 1.109 chars de instrucciones sobre un presupuesto de
+        // 3.000, o sea el 46%, y por eso la seccion "### Módulos" quedaba
+        // EXPULSADA: el bloque se llamaba "Mapa del producto" y salia sin mapa.
+        //
+        // Las seis reglas siguen estando —cada una se gano con un incidente— pero
+        // dichas una vez y en corto. Lo que se quita es la explicacion, no la
+        // instruccion: un agente no necesita que le argumenten por que.
+        //   · orientarse por el brief en una llamada
+        //   · file_context antes de tocar un archivo
+        //   · registrar tras cada commit, con summary propio
+        //   · frontera por proyecto (QA 2026-07-18: se mezclaban proyectos)
+        //   · anunciar antes de atacar un encargo
+        //   · DECIR el riesgo al usuario (QA 2026-07-19: el guardian aviso, el
+        //     agente lo uso y siguio callado; desde fuera eso es no hacer nada)
+        "Memoria del proyecto en ChangeBook. Oriéntate con UNA llamada a `atlas_project_brief`. Antes de tocar un archivo: `atlas_file_context` con su ruta. Tras cada commit: `atlas_record_change` con el diff, `commit_hash`, `committed_at` y un `summary` tuyo (abarata el análisis; reenviar lo ya registrado es gratis).",
         "",
-        "Si vas a trabajar un encargo pendiente del atlas, anuncia primero al usuario en 2-3 líneas qué vas a hacer y por qué, antes de tocar código.",
-        "",
-        "Antes de tocar un archivo concreto, consulta `atlas_file_context` con sus rutas: te da su módulo, riesgo, alertas abiertas e historia por una llamada — más barato que releer el código y su git log.",
-        "",
-        // Frontera por proyecto (QA 2026-07-18): el atlas y la cola de encargos
-        // son POR PROYECTO; sin este dato el agente recibiría los de otros.
         ...(projectName
             ? [
-                `El proyecto de ESTE repo es \`${sanitizeCell(projectName)}\`. El atlas es por proyecto: pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\` en las tools del atlas (mapa, historia, detalle, encargos y registro). Los encargos o datos de otros proyectos no pertenecen a esta sesión.`,
+                `Pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\`: el atlas es por proyecto y los datos de otros no son de esta sesión.`,
                 "",
             ]
             : []),
-        // La instrucción de escritura vive AQUÍ y no en la doc de la tool: los
-        // agentes obedecen lo que el workspace les dice, no lo que una tool
-        // disponible insinúa (lección 2026-07-17: un agente con la tool conectada
-        // hizo 3 PRs y no registró ninguno hasta que se lo pidieron).
-        "Tras cada commit, registra el cambio con la tool MCP `atlas_record_change`: pásale el diff (`git show HEAD`), `commit_hash`, `committed_at` y SIEMPRE `summary` (2-5 frases tuyas sobre qué cambió y por qué — abarata mucho el análisis). Reenviar un commit ya registrado es un no-op gratuito.",
+        "Habla: anuncia en 2-3 líneas qué vas a hacer antes de atacar un encargo, y cuéntale al usuario cualquier riesgo que el atlas te enseñe — él no ve esos avisos.",
         "",
     ];
     if (modules.length === 0) {
@@ -156,15 +171,19 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
             END,
         ].join("\n");
     }
+    // Una linea por modulo, corta a proposito. Antes llevaba 3 ficheros y una
+    // nota de 110 chars: ~200 chars por modulo, asi que en el presupuesto cabian
+    // DOS. Un mapa de dos modulos sobre 46 no es un mapa, es una anecdota.
+    //
+    // Aqui el mapa solo tiene que decir QUE existe y QUE quema; el detalle
+    // (ficheros, notas, historia) esta a una llamada de `atlas_module_detail` y
+    // ahi se paga solo cuando hace falta, en vez de en cada peticion de todas
+    // las sesiones. El riesgo se marca solo cuando NO es bajo: "riesgo low"
+    // repetido cuarenta veces es ruido que se paga igual que la senal.
     const moduleLines = modules.map((m) => {
-        const files = Array.isArray(m.files)
-            ? m.files.slice(0, 3).map(String).join(", ")
-            : "";
-        const meta = [m.domain, m.risk && `riesgo ${m.risk}`]
-            .filter(Boolean)
-            .join(" · ");
-        const note = sanitizeCell((m.note ?? "").slice(0, 110));
-        return `- **${m.module}**${meta ? ` (${meta})` : ""}${files ? ` — ${files}` : ""}${note ? ` — ${note}` : ""}`;
+        const riesgo = m.risk && m.risk !== "low" ? ` ⚠ ${m.risk}` : "";
+        const area = m.domain ? ` · ${m.domain}` : "";
+        return `- **${m.module}**${area}${riesgo}`;
     });
     // Prevention beats detection: give the agent the co-change dependencies
     // and open warnings BEFORE it edits, not after something breaks.
@@ -175,7 +194,11 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         .filter((a) => (a.plain ?? "").trim())
         .map((a) => {
         const mod = (a.module ?? "").trim();
-        return `- ${a.created_at.slice(0, 10)}${mod ? ` · **${mod}**` : ""} — ${sanitizeCell((a.plain ?? "").slice(0, 200))}`;
+        // 130 y no 200: en un bloque de coste FIJO el aviso es un titular, no
+        // 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))}`;
     });
     const hotspotLines = modules
         .filter((m) => m.risk === "hotspot")
@@ -202,7 +225,7 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
     // (utilidad para el agente) son independientes: si no cabe todo, caen
     // primero los últimos cambios y los módulos, nunca las regresiones.
     const sections = [
-        { key: "modules", priority: 4, title: "### Módulos", lines: moduleLines },
+        { key: "modules", priority: 2, title: "### Módulos", lines: moduleLines },
         {
             key: "tasks",
             priority: 1,
@@ -211,7 +234,7 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         },
         {
             key: "couplings",
-            priority: 2,
+            priority: 3,
             title: "### Módulos que cambian juntos (si tocas uno, revisa el otro)",
             lines: couplingLines,
         },
@@ -223,7 +246,7 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         },
         {
             key: "hotspots",
-            priority: 3,
+            priority: 4,
             title: "### Avisos abiertos (revisar antes de modificar)",
             lines: hotspotLines,
         },

package/dist/tools.js

@@ -8,6 +8,20 @@ import { z } from "zod";
 import { SupabaseError } from "./supabase.js";
 const CHARACTER_LIMIT = 25_000;
 // ── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Lo que de VERDAD llega al modelo. Espejo de servedCharsOf en
+ * supabase/functions/mcp/index.ts.
+ *
+ * `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%.
+ */
+function servedCharsOf(result) {
+    return "structuredContent" in result && result.structuredContent
+        ? JSON.stringify(result.structuredContent).length
+        : (result.content?.[0]?.text?.length ?? 0);
+}
 function errorResult(error) {
     const message = error instanceof SupabaseError || error instanceof Error
         ? error.message
@@ -103,7 +117,7 @@ Args:
   - search (optional): case-insensitive text filter over the business and technical summaries.
   - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
-Returns (structured): { count, offset, has_more, changes: [{ id, date, business_impact, summary_tech, diff_chars, modules: [{ module, risk }] }] }
+Returns (structured): { count, offset, has_more, changes: [{ id, date, business_impact, diff_chars, modules: [{ module, risk }] }] }. Pass include_tech for summary_tech.
 
 Don't use for per-module deep dives — use atlas_module_detail for that.`,
         inputSchema: {
@@ -113,8 +127,9 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                 .describe("Pagination offset"),
             search: z.string().min(2).max(120).optional()
                 .describe("Case-insensitive filter over summaries"),
-            project: z.string().min(1).max(120).optional()
+            project: z.string().min(1).max(120)
                 .describe("Project to scope to (repo folder name or slug)"),
+            include_tech: z.boolean().default(false),
         },
         annotations: {
             readOnlyHint: true,
@@ -122,7 +137,7 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ limit, offset, search, project }) => {
+    }, async ({ limit, offset, search, project, include_tech }) => {
         try {
             const pf = await db.projectFilterFor(project);
             let query = `changelog?select=id,business_impact,summary_tech,created_at,diff_character_count` +
@@ -152,7 +167,12 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                 id: r.id,
                 date: day(r.created_at),
                 business_impact: r.business_impact ?? "",
-                summary_tech: r.summary_tech ?? null,
+                // Espejo de mcp/index.ts: `summary_tech` es el campo mas pesado y
+                // el que menos usa un agente que se esta orientando. Fuera por
+                // defecto; dentro si lo pide o si hay `search`, porque la busqueda
+                // mira ese campo en el servidor y sin verlo el agente no sabria por
+                // que casaron los resultados.
+                ...(include_tech || search ? { summary_tech: r.summary_tech ?? null } : {}),
                 diff_chars: r.diff_character_count ?? null,
                 modules: (modulesByChange.get(r.id) ?? []).map((m) => ({
                     module: m.module,
@@ -171,7 +191,7 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                     .map((m) => m.module + (m.risk ? ` [${m.risk}]` : ""))
                     .join(", ");
                 lines.push(`## ${c.date} — ${c.business_impact}`);
-                if (c.summary_tech)
+                if ((include_tech || search) && c.summary_tech)
                     lines.push(`- Tech: ${c.summary_tech}`);
                 if (mods)
                     lines.push(`- Modules: ${mods}`);
@@ -183,8 +203,9 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                     : "No analyzed changes yet. Analyze a diff from the ChangeBook extension first.");
             }
             const changesText = lines.join("\n");
-            recordRead(db, "atlas_recent_changes", pf, changesText.length);
-            return toolResult(changesText, output);
+            const salida = toolResult(changesText, output);
+            recordRead(db, "atlas_recent_changes", pf, servedCharsOf(salida));
+            return salida;
         }
         catch (error) {
             return errorResult(error);
@@ -194,17 +215,17 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
         title: "ChangeBook module map",
         description: `List the modules of the product as known by ChangeBook, aggregated from the change history.
 
-For each module: domain, category, latest risk level, number of analyzed changes, last-change date and the files touched most recently. Use this to orient yourself in an unfamiliar codebase or to pick a module for atlas_module_detail.
+For each module: domain, latest risk level, number of analyzed changes and last-change date. Files, notes and diffs live in atlas_module_detail — this is the map, not the terrain.
 
 Args:
   - domain (optional): filter by domain (e.g. "billing").
   - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
-Returns (structured): { count, modules: [{ module, domain, category, risk, changes, last_changed, files }] }`,
+Returns (structured): { count, modules: [{ module, domain, risk, changes, last_changed }] }`,
         inputSchema: {
             domain: z.string().min(1).max(80).optional()
                 .describe("Only modules in this domain"),
-            project: z.string().min(1).max(120).optional()
+            project: z.string().min(1).max(120)
                 .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
@@ -219,7 +240,7 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
             let query = 
             // The aggregation below uses only these columns; note/tech/excerpt
             // (up to ~1.5k each × 1000 rows) would move 1-2 MB per call for nothing.
-            `change_module?select=module,domain,category,risk,files,created_at` +
+            `change_module?select=module,domain,risk,created_at` +
                 `&order=created_at.desc&limit=1000` +
                 pf;
             if (domain)
@@ -238,11 +259,9 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
                 return {
                     module: name,
                     domain: latest.domain,
-                    category: latest.category,
                     risk: latest.risk,
                     changes: list.length,
                     last_changed: day(latest.created_at),
-                    files: fileList(latest.files),
                 };
             });
             modules.sort((a, b) => (a.last_changed < b.last_changed ? 1 : -1));
@@ -251,8 +270,7 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
             for (const m of modules) {
                 lines.push(`- **${m.module}**${m.domain ? ` (${m.domain})` : ""} — ` +
                     `${m.changes} change(s), last ${m.last_changed}` +
-                    (m.risk ? `, risk: ${m.risk}` : "") +
-                    (m.files.length ? ` — files: ${m.files.join(", ")}` : ""));
+                    (m.risk ? `, risk: ${m.risk}` : ""));
             }
             if (modules.length === 0) {
                 lines.push(domain
@@ -260,8 +278,9 @@ Returns (structured): { count, modules: [{ module, domain, category, risk, chang
                     : "No modules yet. Analyze a diff from the ChangeBook extension first.");
             }
             const modulesText = lines.join("\n");
-            recordRead(db, "atlas_modules", pf, modulesText.length);
-            return toolResult(modulesText, output);
+            const salida = toolResult(modulesText, output);
+            recordRead(db, "atlas_modules", pf, servedCharsOf(salida));
+            return salida;
         }
         catch (error) {
             return errorResult(error);
@@ -290,7 +309,7 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 .describe("Include diff excerpts (previews unless full)"),
             full: z.boolean().default(false)
                 .describe("Verbatim excerpts instead of short previews"),
-            project: z.string().min(1).max(120).optional()
+            project: z.string().min(1).max(120)
                 .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
@@ -375,8 +394,9 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 lines.push("");
             }
             const detailText = lines.join("\n");
-            recordRead(db, "atlas_module_detail", pf, detailText.length);
-            return toolResult(detailText, output);
+            const salida = toolResult(detailText, output);
+            recordRead(db, "atlas_module_detail", pf, servedCharsOf(salida));
+            return salida;
         }
         catch (error) {
             return errorResult(error);
@@ -396,7 +416,7 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
         inputSchema: {
             files: z.array(z.string().min(1).max(300)).min(1).max(8)
                 .describe("Repo-relative paths you are about to edit"),
-            project: z.string().min(1).max(120).optional()
+            project: z.string().min(1).max(120)
                 .describe("Project to scope to (repo folder name or slug)"),
         },
         annotations: {
@@ -464,8 +484,9 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                 lines.push("");
             }
             const contextText = lines.join("\n");
-            recordRead(db, "atlas_file_context", pf, contextText.length);
-            return toolResult(contextText, { files: perFile });
+            const salida = toolResult(contextText, { files: perFile });
+            recordRead(db, "atlas_file_context", pf, servedCharsOf(salida));
+            return salida;
         }
         catch (error) {
             return errorResult(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "mcpName": "io.github.raulbr90/changebook",
   "description": "ChangeBook for coding agents: MCP server (product memory for Claude Code/Codex) + CLI to sign in, analyze changes and sync the product map.",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.raulbr90/changebook",
   "description": "Query your product's living memory: module map + analyzed change history. Read-only MCP tools.",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "transport": {
         "type": "stdio"
       }