changebook 0.4.1 → 0.4.3

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)),
         ];
@@ -236,7 +340,7 @@ 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

package/dist/supabase.js

@@ -5,11 +5,11 @@
  * every query to the signed-in user. Refreshes the access token with the
  * refresh token when needed (refresh does not require a captcha).
  */
-import { loadCredentials, saveCredentials } from "./credentials.js";
-import { slugifyProject } from "./guard.js";
+import { loadCredentials, saveCredentials } from './credentials.js';
+import { slugifyProject } from './guard.js';
 // Public defaults — the anon key is the same public key the web app ships.
-const DEFAULT_URL = "https://oyosihxkecspjkiligga.supabase.co";
-const DEFAULT_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im95b3NpaHhrZWNzcGpraWxpZ2dhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODMwMDYyNTUsImV4cCI6MjA5ODU4MjI1NX0.TU-UK1DToHmLHp9q7QEQ5eAa7V3sq3HtgCxPEa-DvDE";
+const DEFAULT_URL = 'https://oyosihxkecspjkiligga.supabase.co';
+const DEFAULT_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im95b3NpaHhrZWNzcGpraWxpZ2dhIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODMwMDYyNTUsImV4cCI6MjA5ODU4MjI1NX0.TU-UK1DToHmLHp9q7QEQ5eAa7V3sq3HtgCxPEa-DvDE';
 export const AUTH_HELP = `No ChangeBook session configured. Run:
 
   changebook login
@@ -42,7 +42,7 @@ export class Supabase {
     // refresh tokens must be written back there or the stored one goes stale.
     persistRotation = false;
     constructor(env = process.env) {
-        this.url = (env.CHANGEBOOK_SUPABASE_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+        this.url = (env.CHANGEBOOK_SUPABASE_URL ?? DEFAULT_URL).replace(/\/+$/, '');
         this.anonKey = env.CHANGEBOOK_SUPABASE_ANON_KEY ?? DEFAULT_ANON_KEY;
         this.accessToken = env.CHANGEBOOK_ACCESS_TOKEN?.trim() || undefined;
         this.refreshToken = env.CHANGEBOOK_REFRESH_TOKEN?.trim() || undefined;
@@ -75,11 +75,11 @@ export class Supabase {
             // mezcla — la frontera por proyecto que el MCP hospedado ya aplica
             // (auditoría M3: el stdio devolvía "" = todos los proyectos y mezclaba
             // historia/módulos/contexto). Con 0 o 1 proyecto no hay ambigüedad.
-            const some = await this.rest("projects?select=id&limit=2");
+            const some = await this.rest('projects?select=id&limit=2');
             if (some.length > 1) {
-                throw new SupabaseError("Esta cuenta tiene varios proyectos. Define CHANGEBOOK_PROJECT (nombre o slug del repo) o pasa `project` en la tool para no mezclar sus datos.", 400);
+                throw new SupabaseError('Esta cuenta tiene varios proyectos. Define CHANGEBOOK_PROJECT (nombre o slug del repo) o pasa `project` en la tool para no mezclar sus datos.', 400);
             }
-            this.projectFilterCache = "";
+            this.projectFilterCache = '';
             return this.projectFilterCache;
         }
         const v = encodeURIComponent(this.projectEnv);
@@ -99,7 +99,7 @@ export class Supabase {
      * then exact name; falls back to the env-based filter when absent. The
      * atlas is per-project, so tools pass what the agent gave them here.
      */
-    async projectFilterFor(project) {
+    async projectFilterFor(project, opts) {
         const wanted = project?.trim();
         if (!wanted)
             return this.projectFilter();
@@ -111,7 +111,34 @@ export class Supabase {
             rows = await this.rest(`projects?select=id&name=eq.${encodeURIComponent(wanted)}&limit=1`);
         }
         if (rows.length === 0) {
-            throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name).`, 404);
+            // 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.
+            //
+            // `strict` desactiva ese respaldo. La diferencia es QUIÉN puede
+            // corregir la adivinanza: una tool responde a un agente que ve el
+            // nombre del proyecto en la respuesta y rectifica; sync escribe
+            // CLAUDE.md en silencio, y si adivina mal, un repo sin atlas hereda el
+            // mapa de OTRO proyecto — el invariante que la frontera por proyecto
+            // prohíbe ("el mapa debe salir VACÍO, jamás el de otro").
+            if (opts?.strict) {
+                throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name).`, 404);
+            }
+            const todos = await this.rest(`projects?select=id,name,slug&order=created_at.asc&limit=20`);
+            if (todos.length === 1)
+                return `&project_id=eq.${todos[0].id}`;
+            // Espejo del scopeNotice hospedado (mcp/scope.ts): el error LISTA los
+            // proyectos válidos. Sin la lista, el agente que recibe este 404 tiene
+            // que gastar otra petición entera (o preguntar al usuario) solo para
+            // saber qué nombres existen — la ronda perdida que 0.4.2 eliminaba.
+            const names = todos.map((p) => p.name ?? p.slug ?? p.id).join(', ');
+            throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name). ` +
+                `Projects: ${names}. Pass project with the name or slug of the repo you are working in.`, 404);
         }
         return `&project_id=eq.${rows[0].id}`;
     }
@@ -151,11 +178,11 @@ export class Supabase {
     }
     rpcOnce(fn, args) {
         return fetch(`${this.url}/rest/v1/rpc/${fn}`, {
-            method: "POST",
+            method: 'POST',
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
-                "Content-Type": "application/json",
+                'Content-Type': 'application/json',
             },
             body: JSON.stringify(args),
             signal: AbortSignal.timeout(15_000),
@@ -163,12 +190,12 @@ export class Supabase {
     }
     insertOnce(table, row) {
         return fetch(`${this.url}/rest/v1/${table}`, {
-            method: "POST",
+            method: 'POST',
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
-                "Content-Type": "application/json",
-                Prefer: "return=minimal",
+                'Content-Type': 'application/json',
+                Prefer: 'return=minimal',
             },
             body: JSON.stringify(row),
             signal: AbortSignal.timeout(10_000),
@@ -190,7 +217,7 @@ export class Supabase {
             }
         }
         await fetch(`${this.url}/auth/v1/logout?scope=global`, {
-            method: "POST",
+            method: 'POST',
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
@@ -223,7 +250,7 @@ export class Supabase {
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
-                Accept: "application/json",
+                Accept: 'application/json',
             },
             signal: AbortSignal.timeout(30_000),
         });
@@ -285,8 +312,8 @@ export class Supabase {
     }
     refreshOnce(refreshToken) {
         return fetch(`${this.url}/auth/v1/token?grant_type=refresh_token`, {
-            method: "POST",
-            headers: { apikey: this.anonKey, "Content-Type": "application/json" },
+            method: 'POST',
+            headers: { apikey: this.anonKey, 'Content-Type': 'application/json' },
             body: JSON.stringify({ refresh_token: refreshToken }),
             signal: AbortSignal.timeout(30_000),
         });
@@ -318,11 +345,11 @@ export class Supabase {
     }
     invokeOnce(name, payload) {
         return fetch(`${this.url}/functions/v1/${name}`, {
-            method: "POST",
+            method: 'POST',
             headers: {
                 apikey: this.anonKey,
                 Authorization: `Bearer ${this.accessToken}`,
-                "Content-Type": "application/json",
+                'Content-Type': 'application/json',
             },
             body: JSON.stringify(payload),
             signal: AbortSignal.timeout(120_000),

package/dist/sync.js

@@ -10,33 +10,42 @@
  * The section lives between markers and is replaced in place; everything
  * outside the markers is never touched.
  */
-import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 /** The project identity of the synced repo (same rule as analyze/guard). */
 function projectNameFor(targetDir) {
     return (process.env.CHANGEBOOK_PROJECT?.trim() ||
         path.basename(path.resolve(targetDir)));
 }
-const START = "<!-- changebook:start -->";
-const END = "<!-- changebook:end -->";
+const START = '<!-- changebook:start -->';
+const END = '<!-- changebook:end -->';
 // DB text (notes, alert bodies, business impact) is AI-written and gets embedded
 // between the markers that upsertSection splices on. If any of it contained a
 // literal marker, the next sync would splice at the wrong offset and corrupt the
 // file injected into every agent session. Break the HTML-comment opener so no
 // exact marker can be forged; both markers begin with "<!--".
 function sanitizeCell(text) {
-    return text.replace(/<!--/g, "<!- -");
+    return text.replace(/<!--/g, '<!- -');
 }
 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;
@@ -53,16 +62,19 @@ export async function syncContextFiles(db, targetDir) {
     let projectFilter;
     let projectResolved = true;
     try {
-        projectFilter = await db.projectFilterFor(projectName);
+        // strict: el respaldo de proyecto único (0.4.2) es para tools que
+        // conversan con un agente; sync escribe este archivo en silencio y no
+        // puede adivinar — si el nombre no casa, mapa vacío y punto.
+        projectFilter = await db.projectFilterFor(projectName, { strict: true });
     }
     catch {
-        projectFilter = "&project_id=eq.00000000-0000-0000-0000-000000000000";
+        projectFilter = '&project_id=eq.00000000-0000-0000-0000-000000000000';
         projectResolved = false;
     }
     const projectId = /project_id=eq\.([0-9a-f-]+)/.exec(projectFilter)?.[1] ?? null;
     const since = new Date(Date.now() - ALERT_WINDOW_DAYS * 24 * 3600 * 1000).toISOString();
     const [moduleRows, changes, alerts, pendingTasks] = await Promise.all([
-        db.rest("change_module?select=changelog_id,module,domain,risk,files,note,created_at&order=created_at.desc&limit=500" +
+        db.rest('change_module?select=changelog_id,module,domain,risk,files,note,created_at&order=created_at.desc&limit=500' +
             projectFilter),
         db.rest(`changelog?select=business_impact,created_at&order=created_at.desc&limit=${MAX_CHANGES}` +
             projectFilter),
@@ -81,15 +93,15 @@ export async function syncContextFiles(db, targetDir) {
         // Best-effort como las alertas.
         projectResolved && projectId
             ? db
-                .callRpc("list_agent_tasks", {
+                .callRpc('list_agent_tasks', {
                 p_project_id: projectId,
             })
-                .then((rows) => rows.filter((r) => r.status === "pending"))
+                .then((rows) => rows.filter((r) => r.status === 'pending'))
                 .catch(() => [])
             : Promise.resolve([]),
     ]);
     const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks);
-    for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const file = path.join(targetDir, name);
         const updated = await upsertSection(file, section);
         console.error(`${updated} ${name}`);
@@ -99,10 +111,10 @@ export async function syncContextFiles(db, targetDir) {
     // pagar tool calls. Cuenta como lectura (best-effort).
     if (projectResolved && projectId) {
         await db
-            .insertRow("atlas_reads", {
+            .insertRow('atlas_reads', {
             project_id: projectId,
-            tool: "sync_context_files",
-            source: "sync",
+            tool: 'sync_context_files',
+            source: 'sync',
             chars_served: section.length,
         })
             .catch(() => { });
@@ -126,51 +138,55 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         // del usuario y una fecha que cambia a diario invalidaría el prefijo de
         // prompt-cache de TODO el archivo en cada sesión del agente. Las fechas
         // ú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).",
-        "",
-        "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.",
-        "",
-        // QA de Raúl 2026-07-19: el atlas avisó de un riesgo real, el agente lo
-        // usó y siguió trabajando sin decir nada. Desde fuera, un guardián que
-        // trabaja callado y un producto que no hace nada son la misma cosa. El
-        // dueño paga esto: tiene que verlo ocurrir.
-        "Cuando el atlas te avise de un riesgo (alerta abierta, `atlas_file_context` o el guardián), DÍSELO al usuario en 1-2 líneas antes de seguir, aunque lo resuelvas tú: él no ve esos avisos.",
-        "",
-        "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.
+        '## Mapa del producto (ChangeBook · auto-generado)',
+        '',
+        // 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).',
+        '',
         ...(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) {
         return [
             ...head,
-            "_Aún no hay módulos analizados. Ejecuta un análisis desde la extensión o importa el historial de git._",
+            '_Aún no hay módulos analizados. Ejecuta un análisis desde la extensión o importa el historial de git._',
             END,
-        ].join("\n");
+        ].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.
@@ -178,25 +194,29 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
     // AI-detected regressions from the latest analyses: the most urgent thing
     // an agent can know before editing — a change already broke a coupling.
     const alertLines = alerts
-        .filter((a) => (a.plain ?? "").trim())
+        .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))}`;
+        const mod = (a.module ?? '').trim();
+        // 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")
+        .filter((m) => m.risk === 'hotspot')
         .slice(0, 5)
         .map((m) => {
-        const note = sanitizeCell((m.note ?? "").slice(0, 110));
-        return `- **${m.module}** está marcado crítico${note ? ` — ${note}` : ""}`;
+        const note = sanitizeCell((m.note ?? '').slice(0, 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((c.business_impact ?? '').slice(0, 140))}`);
     // 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
     // llevar la misma señal encolada varias veces).
     const taskTitles = [
-        ...new Set(pendingTasks.map((t) => (t.title ?? "").trim()).filter(Boolean)),
+        ...new Set(pendingTasks.map((t) => (t.title ?? '').trim()).filter(Boolean)),
     ].slice(0, 3);
     const taskLines = taskTitles.length > 0
         ? [
@@ -208,39 +228,39 @@ 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",
+            key: 'tasks',
             priority: 1,
-            title: "### Encargos pendientes del dueño (proponte atacarlos)",
+            title: '### Encargos pendientes del dueño (proponte atacarlos)',
             lines: taskLines,
         },
         {
-            key: "couplings",
-            priority: 2,
-            title: "### Módulos que cambian juntos (si tocas uno, revisa el otro)",
+            key: 'couplings',
+            priority: 3,
+            title: '### Módulos que cambian juntos (si tocas uno, revisa el otro)',
             lines: couplingLines,
         },
         {
-            key: "alerts",
+            key: 'alerts',
             priority: 0,
-            title: "### Regresiones detectadas (resolver o verificar YA)",
+            title: '### Regresiones detectadas (resolver o verificar YA)',
             lines: alertLines,
         },
         {
-            key: "hotspots",
-            priority: 3,
-            title: "### Avisos abiertos (revisar antes de modificar)",
+            key: 'hotspots',
+            priority: 4,
+            title: '### Avisos abiertos (revisar antes de modificar)',
             lines: hotspotLines,
         },
         {
-            key: "changes",
+            key: 'changes',
             priority: 5,
-            title: "### Últimos cambios",
+            title: '### Últimos cambios',
             lines: changeLines,
         },
     ];
-    let budget = SYNC_BUDGET_CHARS - head.join("\n").length - END.length;
+    let budget = SYNC_BUDGET_CHARS - head.join('\n').length - END.length;
     const includedCount = new Map();
     for (const s of [...sections].sort((a, b) => a.priority - b.priority)) {
         if (s.lines.length === 0)
@@ -265,12 +285,12 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         if (count === 0)
             continue;
         if (!first)
-            lines.push("");
+            lines.push('');
         lines.push(s.title, ...s.lines.slice(0, count));
         first = false;
     }
     lines.push(END);
-    return lines.join("\n");
+    return lines.join('\n');
 }
 /**
  * Symmetric co-change pairs: modules that appear in the same analyses often
@@ -279,11 +299,15 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
  */
 // Module labels contain spaces, so pair keys use a separator that cannot
 // appear in a label.
-const PAIR_SEP = "\u0000";
-function coChangePairs(rows) {
+const PAIR_SEP = '\u0000';
+// Exportada para el test de paridad con la copia del brief hospedado
+// (supabase/functions/mcp/scope.ts): si las dos implementaciones derivan, el
+// mismo repo enseñaría acoplamientos distintos según por dónde entre el
+// agente — y la deriva sería silenciosa.
+export function coChangePairs(rows) {
     const byAnalysis = new Map();
     for (const r of rows) {
-        const label = (r.module ?? "").trim();
+        const label = (r.module ?? '').trim();
         if (!label)
             continue;
         let set = byAnalysis.get(r.changelog_id);
@@ -321,25 +345,25 @@ function coChangePairs(rows) {
 export async function upsertSection(file, section) {
     let content = null;
     try {
-        content = await readFile(file, "utf8");
+        content = await readFile(file, 'utf8');
     }
     catch {
         content = null;
     }
     if (content === null) {
-        await writeFile(file, section + "\n");
-        return "created";
+        await writeFile(file, section + '\n');
+        return 'created';
     }
     // Migración del renombrado (AppAtlas → ChangeBook): si el archivo aún tiene
     // el bloque con los marcadores antiguos, elimínalo antes de upsertar el
     // nuevo — si no, quedarían dos mapas (uno obsoleto) en el mismo archivo.
-    const LEGACY_START = "<!-- appatlas:start -->";
-    const LEGACY_END = "<!-- appatlas:end -->";
+    const LEGACY_START = '<!-- appatlas:start -->';
+    const LEGACY_END = '<!-- appatlas:end -->';
     const legacyStart = content.indexOf(LEGACY_START);
     const legacyEnd = content.indexOf(LEGACY_END);
     if (legacyStart !== -1 && legacyEnd !== -1 && legacyEnd > legacyStart) {
         content = (content.slice(0, legacyStart) +
-            content.slice(legacyEnd + LEGACY_END.length)).replace(/\n{3,}/g, "\n\n");
+            content.slice(legacyEnd + LEGACY_END.length)).replace(/\n{3,}/g, '\n\n');
         await writeFile(file, content);
     }
     const start = content.indexOf(START);
@@ -349,12 +373,12 @@ export async function upsertSection(file, section) {
         // Idempotente: si el mapa no cambió, no tocar el archivo — reescribirlo
         // actualizaría el mtime, ensuciaría git status y podría invalidar cachés.
         if (next === content)
-            return "unchanged";
+            return 'unchanged';
         await writeFile(file, next);
-        return "updated";
+        return 'updated';
     }
-    const separator = content.endsWith("\n") ? "\n" : "\n\n";
-    await writeFile(file, content + separator + section + "\n");
-    return "appended";
+    const separator = content.endsWith('\n') ? '\n' : '\n\n';
+    await writeFile(file, content + separator + section + '\n');
+    return 'appended';
 }
 //# sourceMappingURL=sync.js.map

package/dist/tools.js

@@ -4,10 +4,35 @@
  * All tools are read-only queries over the user's own ChangeBook data
  * (Row Level Security scopes every request to the signed-in user).
  */
+import path from "node:path";
 import { z } from "zod";
+import { execFileAsync } from "./git.js";
+import { avisoRefutado, contarEnRepo, slugifyProject, } from "./guard.js";
 import { SupabaseError } from "./supabase.js";
 const CHARACTER_LIMIT = 25_000;
+/**
+ * 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.
+ */
+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.";
 // ── 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
@@ -89,6 +114,47 @@ function recordRead(db, tool, projectFilter, charsServed) {
 function ilikePattern(search) {
     return encodeURIComponent(`*${search.replace(/[%*,()]/g, " ").trim()}*`);
 }
+/**
+ * ¿El árbol de trabajo donde corre este servidor ES el proyecto consultado?
+ *
+ * Solo entonces un grep local puede refutar una alerta: la tool recibe
+ * `project` como argumento, pero el proceso corre donde el cliente lo arrancó.
+ * En un repo válido pero AJENO, un símbolo ausente da un 0 REAL (no null) y
+ * avisoRefutado con expect='present' lo tomaría como refutación — silenciar
+ * una alerta verdadera por mirar donde no era es peor que el ruido. Misma
+ * identidad que usa el guardián: CHANGEBOOK_PROJECT o el basename del
+ * directorio, pasados por la slugify del servidor.
+ */
+function cwdEsElProyecto(project) {
+    const candidato = process.env.CHANGEBOOK_PROJECT?.trim() ||
+        path.basename(path.resolve(process.cwd()));
+    return slugifyProject(candidato) === slugifyProject(project.trim());
+}
+/**
+ * "Atlas current up to commit X — your HEAD is N ahead": la señal MECÁNICA de
+ * que la respuesta es memoria, no estado (benchmark 2026-07-20: el agente
+ * repitió un valor revertido porque nada le decía hasta qué commit llegaba lo
+ * que leía). Fail-open total: sin hash, con hash desconocido (clon shallow,
+ * historia sin fetch) o sin repo, no hay línea — el ancla jamás rompe la
+ * lectura que ancla.
+ */
+export async function derivaContraHead(dir, hash) {
+    if (!hash || !/^[0-9a-f]{7,64}$/i.test(hash))
+        return null;
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-list", "--count", `${hash}..HEAD`], { cwd: dir, timeout: 2_000 });
+        const n = Number(stdout.trim());
+        if (!Number.isFinite(n))
+            return null;
+        const corto = hash.slice(0, 7);
+        return n === 0
+            ? `Atlas current up to commit ${corto} — matches your HEAD.`
+            : `Atlas current up to commit ${corto} — your HEAD is ${n} commit(s) ahead; later changes are NOT reflected here. Verify current values in the code before asserting them.`;
+    }
+    catch {
+        return null;
+    }
+}
 // ── Registration ──────────────────────────────────────────────────────────────
 export function registerTools(server, db) {
     server.registerTool("atlas_recent_changes", {
@@ -103,7 +169,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 +179,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 +189,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 +219,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 +243,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 +255,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 +267,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 +292,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 +311,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 +322,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 +330,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);
@@ -280,7 +351,7 @@ Args:
   - full (default false): return the diff excerpts verbatim instead of the token-saving previews. Only pass it when you actually need the code lines.
   - 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): { module, count, changes: [{ date, risk, note, tech, files, business_impact, excerpt, excerpt_truncated }] }`,
+Returns (structured): { module, count, changes: [{ date, commit, risk, note, tech, files, business_impact, excerpt, excerpt_truncated }] }. Notes describe the code AS OF their commit/date — verify current values in the code before asserting them.`,
         inputSchema: {
             module: z.string().min(1).max(120)
                 .describe("Exact module name (see atlas_modules)"),
@@ -290,7 +361,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: {
@@ -316,7 +387,7 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 };
             }
             const ids = [...new Set(rows.map((r) => r.changelog_id))].join(",");
-            const logs = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count&id=in.(${ids})`);
+            const logs = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash&id=in.(${ids})`);
             const logById = new Map(logs.map((l) => [l.id, l]));
             const changes = rows.map((r) => {
                 let excerpt = null;
@@ -333,6 +404,9 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 }
                 return {
                     date: day(r.created_at),
+                    // El commit del que salió cada entrada: la nota deja de flotar en
+                    // el tiempo y se puede cuadrar contra git.
+                    commit: logById.get(r.changelog_id)?.commit_hash?.slice(0, 7) ?? null,
                     risk: r.risk,
                     note: r.note,
                     tech: r.tech,
@@ -342,6 +416,14 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                     excerpt_truncated: excerptTruncated,
                 };
             });
+            // Ancla temporal de la respuesta entera: el commit más nuevo servido,
+            // comparado con el HEAD del árbol — solo si este árbol ES el proyecto
+            // (misma puerta que la refutación de alertas).
+            const ancla = cwdEsElProyecto(project)
+                ? await derivaContraHead(process.cwd(), rows
+                    .map((r) => logById.get(r.changelog_id)?.commit_hash)
+                    .find(Boolean) ?? null)
+                : null;
             const latest = rows[0];
             const output = {
                 module,
@@ -354,10 +436,12 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 `# Module: ${module}` +
                     (latest.domain ? ` (${latest.domain}` +
                         (latest.category ? ` / ${latest.category}` : "") + ")" : ""),
-                "",
             ];
+            if (ancla)
+                lines.push(ancla);
+            lines.push("");
             for (const c of changes) {
-                lines.push(`## ${c.date}${c.risk ? ` — risk: ${c.risk}` : ""}`);
+                lines.push(`## ${c.date}${c.commit ? ` · commit ${c.commit}` : ""}${c.risk ? ` — risk: ${c.risk}` : ""}`);
                 if (c.business_impact)
                     lines.push(`- Impact: ${c.business_impact}`);
                 if (c.note)
@@ -374,9 +458,12 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 }
                 lines.push("");
             }
+            if (!ancla)
+                lines.push(TEMPORAL_CONTRACT, "");
             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 +483,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: {
@@ -436,17 +523,43 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                 ...new Set(perFile.flatMap((f) => f.modules.map((m) => m.module))),
             ];
             const alerts = moduleNames.length
-                ? await db.rest(`regression_alerts?select=module,plain&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(moduleNames))})&order=created_at.desc&limit=10` +
+                ? await db.rest(`regression_alerts?select=module,plain,evidence_symbol,evidence_expect&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(moduleNames))})&order=created_at.desc&limit=10` +
                     pf)
                 : [];
+            // Refutación al servir (benchmark 2026-07-20): el mismo grep que el
+            // guardián corre en el pre-commit, pero aquí, en la consulta que el
+            // agente hace ANTES de editar — 4 de 7 alertas abiertas se caían con
+            // un grep (migración alert_evidence). Fail-open en todo: sin
+            // evidencia, sin repo o con la búsqueda rota, la alerta pasa; y si el
+            // cwd no es el proyecto consultado, no se refuta nada (ver
+            // cwdEsElProyecto).
+            const refutada = cwdEsElProyecto(project)
+                ? (a) => avisoRefutado(a, (s) => contarEnRepo(process.cwd(), s))
+                : () => false;
             const alertsByModule = new Map();
             for (const a of alerts) {
                 const m = (a.module ?? "").trim();
                 if (!m || !a.plain)
                     continue;
+                if (refutada(a))
+                    continue;
                 alertsByModule.set(m, [...(alertsByModule.get(m) ?? []), a.plain]);
             }
-            const lines = [`# File context (${paths.length} file(s))`, ""];
+            // Ancla temporal: el último commit analizado del proyecto vs el HEAD
+            // de este árbol (misma puerta de proyecto que la refutación).
+            // Best-effort: el ancla jamás rompe la lectura que ancla.
+            let ancla = null;
+            if (cwdEsElProyecto(project)) {
+                const ultimo = await db
+                    .rest(`changelog?select=commit_hash&commit_hash=not.is.null&order=created_at.desc&limit=1` +
+                    pf)
+                    .catch(() => []);
+                ancla = await derivaContraHead(process.cwd(), ultimo[0]?.commit_hash ?? null);
+            }
+            const lines = [`# File context (${paths.length} file(s))`];
+            if (ancla)
+                lines.push(ancla);
+            lines.push("");
             for (const f of perFile) {
                 lines.push(`## ${f.file}`);
                 if (f.modules.length === 0) {
@@ -455,17 +568,22 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                 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(`  - Latest note: ${m.last_note}`);
+                    if (m.last_note) {
+                        // Con fecha: una nota es una observación fechada, no estado.
+                        lines.push(`  - Note from last analysis (${m.last_changed}): ${m.last_note}`);
+                    }
                     for (const plain of alertsByModule.get(m.module) ?? []) {
                         lines.push(`  - ⚠ OPEN ALERT: ${plain}`);
                     }
                 }
                 lines.push("");
             }
+            if (!ancla)
+                lines.push(TEMPORAL_CONTRACT, "");
             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.1",
+  "version": "0.4.3",
   "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.1",
+  "version": "0.4.3",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.4.1",
+      "version": "0.4.3",
       "transport": {
         "type": "stdio"
       }