changebook 0.4.2 → 0.4.3

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();
@@ -119,10 +119,26 @@ export class Supabase {
             //
             // 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`);
+            //
+            // `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}`;
-            throw new SupabaseError(`No ChangeBook project named "${wanted}" (by slug or name).`, 404);
+            // 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}`;
     }
@@ -162,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),
@@ -174,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),
@@ -201,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}`,
@@ -234,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),
         });
@@ -296,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),
         });
@@ -329,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,22 +10,22 @@
  * 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;
@@ -62,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),
@@ -90,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}`);
@@ -108,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(() => { });
@@ -135,8 +138,8 @@ 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)",
-        "",
+        '## 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
@@ -153,23 +156,23 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         //   · 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).",
-        "",
+        '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
             ? [
                 `Pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\`: el atlas es por proyecto y los datos de otros no son de esta sesión.`,
-                "",
+                '',
             ]
             : []),
-        "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.",
-        "",
+        '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
@@ -181,8 +184,8 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
     // 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 riesgo = m.risk && m.risk !== "low" ? ` ⚠ ${m.risk}` : "";
-        const area = m.domain ? ` · ${m.domain}` : "";
+        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
@@ -191,29 +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();
+        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))}`;
+        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
         ? [
@@ -225,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: 2, 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",
+            key: 'couplings',
             priority: 3,
-            title: "### Módulos que cambian juntos (si tocas uno, revisa el otro)",
+            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",
+            key: 'hotspots',
             priority: 4,
-            title: "### Avisos abiertos (revisar antes de modificar)",
+            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)
@@ -282,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
@@ -296,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);
@@ -338,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);
@@ -366,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,9 +4,20 @@
  * 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
@@ -103,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", {
@@ -299,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)"),
@@ -335,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;
@@ -352,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,
@@ -361,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,
@@ -373,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)
@@ -393,6 +458,8 @@ Returns (structured): { module, count, changes: [{ date, risk, note, tech, files
                 }
                 lines.push("");
             }
+            if (!ancla)
+                lines.push(TEMPORAL_CONTRACT, "");
             const detailText = lines.join("\n");
             const salida = toolResult(detailText, output);
             recordRead(db, "atlas_module_detail", pf, servedCharsOf(salida));
@@ -456,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) {
@@ -475,14 +568,18 @@ 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");
             const salida = toolResult(contextText, { files: perFile });
             recordRead(db, "atlas_file_context", pf, servedCharsOf(salida));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.2",
+  "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.2",
+  "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.2",
+      "version": "0.4.3",
       "transport": {
         "type": "stdio"
       }