changebook 0.4.9 → 0.4.10

package/dist/analyze.js

@@ -6,12 +6,12 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, FICHEROS_GENERADOS, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
+import { commitDiff, execFileAsync, FICHEROS_GENERADOS, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, projectNameFor, usableSummary, } from "./git.js";
 import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI, truncateAtFileBoundary } from "./optimize.js";
 export async function analyze(db, options = {}) {
     const cwd = path.resolve(options.dir ?? process.cwd());
-    const projectName = path.basename(cwd);
+    const projectName = projectNameFor(cwd);
     let rawDiff;
     let commitHash;
     let committedAt;

package/dist/git.js

@@ -4,7 +4,7 @@
  * normalization live here — a drift between them would make the same commit
  * compress differently across subcommands and break the server-side dedup.
  */
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import * as path from "node:path";
 import { promisify } from "node:util";
 export const execFileAsync = promisify(execFile);
@@ -114,4 +114,47 @@ export function gitErrorMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * El nombre del proyecto al que reportar desde `dir`.
+ *
+ * NACE DE UN FLECO REAL. El 2026-07-25 trabajé en un worktree llamado `seo-wt` y
+ * el atlas creó un proyecto `seo-wt` en la cuenta de Raúl: gastó un análisis y
+ * dejó 4 módulos huérfanos en su selector de proyectos. No fue un bug del
+ * servidor: los cuatro sitios del CLI que deducen el nombre lo sacaban de
+ * `path.basename(cwd)`, y en un worktree eso NO es el nombre del repo.
+ *
+ * Un worktree enlazado es el MISMO repositorio: sus commits van al mismo sitio y
+ * su historia es la misma. Reportar a otro proyecto parte el atlas en dos por un
+ * detalle de cómo tienes montado el disco, y encima en silencio.
+ *
+ * Orden: `CHANGEBOOK_PROJECT` manda siempre (quien quiera un proyecto aparte por
+ * worktree lo dice y ya); si no, el nombre del árbol PRINCIPAL; y si no se puede
+ * averiguar, el basename de siempre.
+ *
+ * Se detecta comparando `--git-dir` con `--git-common-dir`: en el árbol principal
+ * son el mismo; en un worktree enlazado el primero es `.git/worktrees/<nombre>`.
+ */
+export function projectNameFor(dir, env = process.env) {
+    const explicito = env.CHANGEBOOK_PROJECT?.trim();
+    if (explicito)
+        return explicito;
+    const base = path.basename(path.resolve(dir));
+    try {
+        const gitDir = execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+            cwd: dir, encoding: "utf8", timeout: 5_000,
+        }).trim();
+        const comun = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+            cwd: dir, encoding: "utf8", timeout: 5_000,
+        }).trim();
+        if (!gitDir || !comun || gitDir === comun)
+            return base;
+        // Worktree enlazado: el árbol principal es el padre del git-dir común.
+        const principal = path.basename(path.dirname(comun));
+        return principal || base;
+    }
+    catch {
+        // Sin git, o con una versión que no soporta estas banderas: como siempre.
+        return base;
+    }
+}
 //# sourceMappingURL=git.js.map

package/dist/guard.js

@@ -13,22 +13,69 @@
  *            deliberately does NOT block.
  */
 import * as fs from "node:fs";
-import * as path from "node:path";
 import { execFileSync } from "node:child_process";
-import { execFileAsync, gitPath } from "./git.js";
+import { execFileAsync, gitPath, projectNameFor } from "./git.js";
 import { feedWarningFor } from "./feed.js";
 /** Exit code that asks the pre-commit hook to abort the commit. */
 export const EXIT_BLOCK = 3;
 // A commit should never feel slow because of us: whatever the network hasn't
 // answered by then is treated as "no findings".
 const GUARD_TIMEOUT_MS = 3_500;
+/**
+ * Tope de greps para decidir a QUIEN se avisa (ver `guardFindings`, nota 3).
+ *
+ * Mas alto que el tope de refutaciones del hook (3) porque aqui el grep decide
+ * si el aviso SALE, no solo si se cae: quedarse corto devuelve al guardian al
+ * comportamiento contaminado que estamos arreglando. Y sigue siendo barato —
+ * ~30 ms cada uno sobre este repo, cacheados por simbolo — dentro de los 3,5 s.
+ */
+const MAX_GREPS_DE_DESTINO = 8;
 // Open alerts move at analysis speed (one per commit at most), so a short
 // cache makes rebases/amend streaks free without risking stale warnings.
 const CACHE_TTL_MS = 5 * 60_000;
 const MAX_ALERTS = 20;
+/**
+ * ¿Puede el REPO contestar la afirmacion de este aviso?
+ *
+ * Es la pregunta que faltaba, y la respuesta decide si el grep significa algo.
+ * Medido el 2026-07-26 sobre las 28 alertas con evidencia de AppAtlas: seis se
+ * descartaban en silencio porque su simbolo aparecia en el repo, y dos de ellas
+ * eran las UNICAS del registro que predijeron un incidente real —el desfase de
+ * esquema del 22 de julio, tres dias sin persistir alertas— porque hablaban de
+ * algo ausente en la BASE DE DATOS DE PRODUCCION. El simbolo estaba en el repo,
+ * claro: era el nombre del fichero de migracion.
+ *
+ * Una migracion presente en el repo NO prueba que su DDL haya corrido. Eso no se
+ * arregla con mejores greps; se arregla no haciendo el grep.
+ */
+export function alcanceDelRepo(alert) {
+    const scope = (alert.evidence_scope ?? "").trim();
+    if (scope === "repo")
+        return "si";
+    if (scope === "prod_db" || scope === "deployed")
+        return "no";
+    // Las 99 historicas y cualquier aviso donde el modelo lo omita. No se infiere
+    // del texto: adivinar el ambito es exactamente lo que rompio esto.
+    return "sin_declarar";
+}
+/**
+ * La frase para un aviso que el repo NO puede contestar. Es informacion, no
+ * ruido: le dice al agente donde SI habria que mirar, que en los dos casos
+ * medidos era "comprueba si la migracion corrio en produccion".
+ */
+export function dondeComprobarlo(alert) {
+    const scope = (alert.evidence_scope ?? "").trim();
+    if (scope === "prod_db") {
+        return "this claim is about the PRODUCTION DATABASE, not the repo — a migration file existing here does not mean its DDL ran";
+    }
+    if (scope === "deployed") {
+        return "this claim is about what is DEPLOYED right now, not the repo — check the deployed version, not the source";
+    }
+    return null;
+}
 /**
  * Same slug the backend derives from the project name (analysis.ts slugify):
- * the CLI sends `path.basename(cwd)` as projectName and the server slugifies
+ * the CLI sends `projectNameFor(cwd)` as projectName and the server slugifies
  * it, so reproducing that transform is how the guard finds its project row.
  */
 export function slugifyProject(value) {
@@ -82,19 +129,60 @@ function alertFiles(alert) {
 /**
  * ¿Se contradice el aviso con el codigo que hay delante?
  *
- * Devuelve `true` SOLO cuando la evidencia lo tumba de forma inequivoca. Sin
+ * 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.
  *
+ * ── 2026-07-26: LA RAMA "absent" NO ERA INEQUIVOCA Y SE QUITO ───────────────
+ *
+ * Decia: expect 'absent' + el simbolo aparece => refutado ("si aparece, ya esta
+ * hecho"). Medido sobre las 28 alertas con evidencia de AppAtlas:
+ *
+ *     expect 'present' y el simbolo ya no esta -> descartar     0 veces
+ *     expect 'absent'  y el simbolo aparece    -> descartar     6 veces
+ *
+ * O sea que el 100% de los descartes venia de esa rama, y la solida no disparaba
+ * NUNCA. Y las seis eran de las mejores del registro:
+ *
+ *   · `alert_evidence` (22 jul): "esto deja regression_warnings vacio hasta que
+ *     se aplique la migracion en produccion". SE CUMPLIO: tres dias sin
+ *     persistir alertas.
+ *   · `admin_install_metrics` (25 jul): el MISMO fallo otra vez, citando el
+ *     precedente del 22. Una de las 5 alertas que alguien juzgo y arreglo.
+ *
+ * POR QUE FALLABA: "el simbolo aparece" significa dos cosas OPUESTAS — que el
+ * reemplazo se revirtio (el aviso ya no aplica) o que queda una referencia
+ * obsoleta (el aviso CUMPLIENDOSE). Y en esas seis, peor: hablaban de algo que
+ * falta en la BASE DE DATOS DE PRODUCCION, mientras el grep mira el REPO. El
+ * simbolo esta en el repo, claro que esta: es el nombre del fichero de
+ * migracion. Se buscaba en un sitio una afirmacion que era sobre otro.
+ *
+ * El caso que lo paga: cuando `vite.config.ts` todavia importaba `noscriptFor`,
+ * la alerta que lo nombraba se "refutaba" por aqui. Ese dia el build se rompio
+ * por eso exactamente.
+ *
+ * QUE SE HACE AHORA con ese caso: no se descarta, se SIRVE diciendo donde
+ * aparece el simbolo (ver `dondeApareceElSimbolo`). Nombrar el sitio es util en
+ * las dos lecturas y falso en ninguna, mientras que descartar es catastrofico en
+ * una de las dos. Es la misma regla de siempre —la duda deja pasar el aviso—
+ * aplicada donde no se estaba aplicando.
+ *
  * `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"))
+    // Solo 'present' puede refutarse con un grep del repo. 'absent' es ambiguo
+    // (ver arriba) y se resuelve sirviendo las rutas, no descartando.
+    if (!simbolo || espera !== "present")
+        return false;
+    // Y solo si la afirmacion es SOBRE el repo. Un 'sin_declarar' tampoco refuta:
+    // gatearlo no cuesta nada medido —esta rama disparo 0 veces en produccion— y
+    // quita el riesgo de tirar una alerta de produccion por buscar donde no era.
+    if (alcanceDelRepo(alert) !== "si")
         return false;
     let apariciones;
     try {
@@ -108,10 +196,77 @@ export function avisoRefutado(alert, buscar) {
     // "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;
+    return apariciones === 0;
+}
+/**
+ * Una linea por TEXTO: si dos avisos abiertos dicen lo mismo, se sirve uno.
+ *
+ * El dedup de creacion distingue por (simbolo, expectativa) a proposito — "tiene
+ * que seguir" y "tiene que desaparecer" son afirmaciones opuestas y colapsarlas
+ * escondería una regresion real. Pero eso es la IDENTIDAD, no la PANTALLA.
+ *
+ * Visto en produccion el 2026-07-27, servido al agente:
+ *
+ *   ⚠ OPEN ALERT: La funcion noscriptFor fue reemplazada por crawlerBodyFor...
+ *   ⚠ OPEN ALERT: La funcion noscriptFor fue reemplazada por crawlerBodyFor...
+ *     → CHECKED NOW: ...
+ *
+ * Dos alertas de verdad distintas (una 'present', otra 'absent') con el MISMO
+ * texto, porque la expectativa no se muestra. Para quien lo lee es una
+ * repeticion, y un avisador que repite se ignora igual que uno que se equivoca.
+ * No se puede actuar distinto sobre dos frases identicas.
+ *
+ * `informativo` decide cual sobrevive: se prefiere el que trae la linea de
+ * comprobacion (donde aparece el simbolo, o donde habria que mirarlo), porque es
+ * el unico que añade algo. Empate: el primero, y el orden de entrada se respeta.
+ */
+export function unoPorTexto(items, texto, informativo) {
+    const mejor = new Map();
+    for (const it of items) {
+        const clave = texto(it).trim();
+        if (!clave)
+            continue;
+        const actual = mejor.get(clave);
+        if (!actual || (!informativo(actual) && informativo(it))) {
+            mejor.set(clave, it);
+        }
+    }
+    return [...mejor.values()];
+}
+/**
+ * Donde aparece el simbolo de un aviso 'absent', para poder CONTESTAR el
+ * condicional en vez de vigilarlo.
+ *
+ * Es la otra mitad del cambio de arriba. El aviso de `noscriptFor` decia
+ * "actualiza cualquier referencia interna a noscriptFor ... SI LOS HUBIERA", y
+ * la respuesta era un grep. El 56% de los textos lleva un condicional asi
+ * ("si los hubiera", "podria", "sugiriendo"): en vez de prohibir la redaccion
+ * —que es tratar el sintoma— se resuelve la condicion y se dice el hecho.
+ *
+ * Devuelve null cuando no hay nada que añadir: otro `expect`, sin simbolo, la
+ * busqueda fallo, o el simbolo no aparece (y entonces el aviso se sirve tal
+ * cual, que es lo que ya hacia).
+ */
+export function dondeApareceElSimbolo(alert, buscarFicheros) {
+    const simbolo = (alert.evidence_symbol ?? "").trim();
+    if (!simbolo || alert.evidence_expect !== "absent")
+        return null;
+    // Con 'prod_db' o 'deployed' no se busca: decir "sigue apareciendo en X" sobre
+    // una afirmacion que no era del repo es afirmar algo falso con cara de hecho
+    // comprobado, que es peor que callarse. Para esos va `dondeComprobarlo`.
+    // 'sin_declarar' SI localiza: es aditivo y no puede perder un aviso.
+    if (alcanceDelRepo(alert) === "no")
+        return null;
+    let ficheros;
+    try {
+        ficheros = buscarFicheros(simbolo);
+    }
+    catch {
+        return null;
+    }
+    if (!ficheros || ficheros.length === 0)
+        return null;
+    return ficheros;
 }
 /**
  * Open alerts × staged files → warnings, deduped by (module, message).
@@ -126,8 +281,32 @@ export function avisoRefutado(alert, buscar) {
  *
  * 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.
+ *
+ * 3. DONDE VIVE EL SIMBOLO manda sobre la lista del aviso (2026-07-27), y esto
+ *    nace de medir el guardian en 62 corridas reales. Aviso 2 veces; una en el
+ *    clavo y otra falso positivo:
+ *
+ *      La alerta era sobre `noscriptFor` en PUBLICACION (seoRoutes.ts,
+ *      publish.yml) y salto al preparar `tools/bench-orientacion.mjs` — el arnes
+ *      del benchmark, que no tiene nada que ver con noscriptFor.
+ *
+ *    La causa: la lista `files` de un aviso son LOS FICHEROS DEL DIFF QUE LO
+ *    LEVANTO, no los ficheros donde vive el simbolo. Medido sobre las 27 alertas
+ *    con lista: **10 (37%) no nombran ni un fichero donde su simbolo este**. Y
+ *    los peores contaminadores son los que se tocan a todas horas —
+ *    `_shared/analysis.ts` sale en 5 listas, `bench-orientacion.mjs` en 4 —, o
+ *    sea que cada vez que los editas arrastras avisos ajenos.
+ *
+ *    Con `ficherosDelSimbolo` se pregunta donde esta el simbolo DE VERDAD. Es la
+ *    misma pieza que sirve para contestar el condicional (`ficherosEnRepo`), aqui
+ *    para decidir a quien se avisa.
+ *
+ *    ORDEN DE PREFERENCIA, y cada escalon es un fallo-abierto del siguiente:
+ *      donde vive el simbolo  >  lista del aviso  >  ficheros del modulo
+ *    Si el grep falla o no encuentra nada se cae a la lista de siempre, asi que
+ *    un fallo de disco no puede volver mudo al guardian.
  */
-export function guardFindings(staged, alerts, filesByModule, refutado) {
+export function guardFindings(staged, alerts, filesByModule, refutado, ficherosDelSimbolo) {
     const stagedSet = new Set(staged);
     const seen = new Set();
     const findings = [];
@@ -136,10 +315,15 @@ export function guardFindings(staged, alerts, filesByModule, refutado) {
         const plain = (alert.plain ?? "").trim();
         if (!module || !plain)
             continue;
-        // Las rutas del aviso mandan sobre las del modulo: dicen de QUE va, no solo
-        // a que cajon pertenece.
+        // Donde vive el simbolo manda sobre la lista del aviso, y la lista del aviso
+        // sobre el modulo: de mas preciso a menos. Ver la nota 3 de arriba.
+        const porSimbolo = ficherosDelSimbolo?.(alert) ?? null;
         const propias = alertFiles(alert);
-        const ambito = propias.length > 0 ? propias : (filesByModule.get(module) ?? []);
+        const ambito = porSimbolo && porSimbolo.length > 0
+            ? porSimbolo
+            : propias.length > 0
+                ? propias
+                : (filesByModule.get(module) ?? []);
         const touched = ambito.filter((f) => stagedSet.has(f));
         if (touched.length === 0)
             continue;
@@ -167,13 +351,50 @@ export function guardFindings(staged, alerts, filesByModule, refutado) {
  * `.` sueltos lo convertirian en otra expresion regular.
  */
 export function contarEnRepo(dir, simbolo) {
+    const out = grepDelRepo(dir, simbolo, "--count");
+    if (out === null)
+        return null;
+    // 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);
+}
+/**
+ * En QUE ficheros aparece el simbolo. Mismo grep, mismos pathspecs, distinta
+ * pregunta: `contarEnRepo` sirve para refutar y este para CONTESTAR (ver
+ * `dondeApareceElSimbolo`).
+ *
+ * Comparten `grepDelRepo` a proposito y no por ahorrar lineas: si divergieran
+ * los pathspecs, uno podria decir "no aparece" y el otro "aparece en X" sobre el
+ * mismo simbolo, y no habria forma de saber cual miente.
+ */
+export function ficherosEnRepo(dir, simbolo) {
+    const out = grepDelRepo(dir, simbolo, "--files-with-matches");
+    if (out === null)
+        return null;
+    return out.split("\n").filter(Boolean).slice(0, MAX_FICHEROS_SERVIDOS);
+}
+/** Tope de rutas que se nombran en un aviso: la lista es una pista, no un informe. */
+const MAX_FICHEROS_SERVIDOS = 4;
+/**
+ * El grep compartido. `modo` es `--count` o `--files-with-matches`.
+ *
+ * `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.
+ */
+function grepDelRepo(dir, simbolo, modo) {
     if (!/^[A-Za-z_$][\w$.]{1,118}$/.test(simbolo))
         return null;
     try {
-        const out = execFileSync("git", [
+        return execFileSync("git", [
             "grep",
             "--fixed-strings",
-            "--count",
+            modo,
             "--",
             simbolo,
             // Se busca en CODIGO, nunca en prosa. Sin esto el mecanismo nace
@@ -188,17 +409,12 @@ export function contarEnRepo(dir, simbolo) {
             // en silencio. Lo cazó el fixture hermético del test (2026-07-21).
             ":!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;
+        return code === 1 ? "" : null;
     }
 }
 export async function stagedFiles(dir) {
@@ -233,7 +449,7 @@ async function fetchSignals(db, dir, env) {
     }
     // Same project the analyze/hook pipeline reports to: CHANGEBOOK_PROJECT
     // wins, otherwise the directory name, matched by server-side slug first.
-    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const candidate = projectNameFor(dir, env);
     const slug = slugifyProject(candidate);
     let projects = slug
         ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
@@ -367,7 +583,35 @@ 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, (alert) => avisoRefutado(alert, (simbolo) => contarEnRepo(dir, simbolo)));
+    // Presupuesto de greps para decidir A QUIEN se avisa. `contarEnRepo` y
+    // `ficherosEnRepo` son execFileSync, o sea que BLOQUEAN el bucle de eventos y
+    // el techo de GUARD_TIMEOUT_MS no puede desalojarlos — un Promise.race no gana
+    // a una llamada sincrona. Con muchas alertas abiertas esto se comeria el
+    // presupuesto del commit a ~30 ms por grep. Pasado el tope se cae a la lista
+    // del aviso, que es el comportamiento de siempre.
+    //
+    // Se cachea por simbolo porque varias alertas comparten el mismo (noscriptFor
+    // salio 3 veces): sin esto se pagaria el mismo grep tres veces.
+    let grepsRestantes = MAX_GREPS_DE_DESTINO;
+    const cacheSimbolo = new Map();
+    const ficherosDelSimbolo = (alert) => {
+        const simbolo = (alert.evidence_symbol ?? "").trim();
+        if (!simbolo)
+            return null;
+        // Misma puerta que la refutacion: en 'prod_db' o 'deployed' el repo no dice
+        // donde vive la afirmacion, asi que apuntar con el grep seria apuntar mal.
+        if (alcanceDelRepo(alert) === "no")
+            return null;
+        if (cacheSimbolo.has(simbolo))
+            return cacheSimbolo.get(simbolo) ?? null;
+        if (grepsRestantes <= 0)
+            return null;
+        grepsRestantes -= 1;
+        const encontrados = ficherosEnRepo(dir, simbolo);
+        cacheSimbolo.set(simbolo, encontrados);
+        return encontrados;
+    };
+    const findings = guardFindings(staged, signals.alerts, signals.filesByModule, (alert) => avisoRefutado(alert, (simbolo) => contarEnRepo(dir, simbolo)), ficherosDelSimbolo);
     const block = mode === "block";
     const message = findingsMessage(findings, block);
     // La consulta del guardián también es una consulta del atlas (QA

package/dist/impact.js

@@ -41,8 +41,8 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { presupuestoDeTiempo } from "./context.js";
-import { execFileAsync, gitPath } from "./git.js";
-import { avisoRefutado, contarEnRepo, slugifyProject, } from "./guard.js";
+import { execFileAsync, gitPath, projectNameFor } from "./git.js";
+import { avisoRefutado, contarEnRepo, dondeApareceElSimbolo, dondeComprobarlo, ficherosEnRepo, slugifyProject, unoPorTexto, } from "./guard.js";
 import { computeRecidivism, dependentsOf } from "./tools.js";
 /**
  * Techo duro del camino crítico. Más corto que el de `context` (2 s) porque
@@ -66,6 +66,29 @@ const SEEN_TTL_MS = 30 * 60_000;
 const SEEN_MAX = 200;
 /** Cuántos módulos se describen si el archivo pertenece a varios. */
 const MAX_MODULES = 3;
+/**
+ * Cuánto de la nota del análisis se sirve.
+ *
+ * SE SIRVE, y ese es el cambio del 2026-07-26 por la tarde. El hook nacía
+ * escueto a propósito —dependientes, alertas, reincidencia— y las notas se
+ * quedaron fuera por miedo al ruido. Midiendo se vio el coste de esa decisión:
+ * la nota de `Carga y arranque de la aplicación` sobre sync.ts dice «el
+ * SYNC_BUDGET_CHARS se rebaja de 3.000 a 2.000 porque la prosa gorda expulsaba
+ * el mapa», que es EXACTAMENTE el fallo en el que caí dos veces ese mismo día. Y
+ * es lo único que ningún grep puede encontrar: no está en el código, está en la
+ * historia del análisis. El canal estaba construido y servía lo que git ya sabe.
+ *
+ * Acotada, no libre: 320 chars por nota y solo en los módulos que YA se
+ * reportan (los que tienen dependientes, alerta abierta o reincidencia). Sin el
+ * tope, un archivo de diez módulos volcaría diez párrafos y el hook volvería a
+ * ser ruido que se aprende a ignorar.
+ *
+ * 320 y no 220: con 220, la nota de sync.ts se cortaba en «…porque la prosa
+ * gord…», justo antes de la conclusión. Estas notas describen primero y concluyen
+ * al final, así que un tope corto se come exactamente la carga útil y deja la
+ * paja. Tres notas de 320 son ~250 tokens una vez por archivo y sesión.
+ */
+const MAX_NOTE_CHARS = 320;
 /** Tope de greps de refutación: son síncronos y el techo no los desaloja. */
 const MAX_REFUTACIONES = 3;
 export const IMPACT_HOOK = {
@@ -170,8 +193,36 @@ export function impactText(file, modules) {
         if (m.dependents.length > 0) {
             lines.push(`  - ↘ DEPENDS ON THIS: ${m.dependents.join(", ")} — check these too before you finish`);
         }
-        for (const plain of m.alerts)
-            lines.push(`  - ⚠ OPEN ALERT: ${plain}`);
+        for (const a of m.alerts) {
+            lines.push(`  - ⚠ OPEN ALERT: ${a.plain}`);
+            // La condicion, resuelta. Va en su propia linea y con el simbolo delante
+            // para que se lea como un hecho comprobado y no como parte de la prosa del
+            // modelo, que es justo la que hedgea.
+            //
+            // Y DICE LAS DOS LECTURAS a proposito, porque el hecho no distingue: un
+            // simbolo que sigue apareciendo cuando se esperaba ausente puede ser una
+            // referencia que se quedo sin actualizar (el caso `noscriptFor`, que rompio
+            // el build) o un aviso que ya no vale (el caso `registerTools`). Antes se
+            // elegia la segunda en silencio y se tiraba el aviso; ahora se le dan al
+            // agente el hecho y las dos salidas, que es mas informacion que la que
+            // habia en cualquiera de las dos versiones anteriores.
+            if (a.donde && a.donde.length > 0) {
+                lines.push(`    → CHECKED NOW: "${a.simbolo}" still appears in ${a.donde.join(", ")}` +
+                    ` — alert expects it gone: either a reference was missed, or the alert is stale`);
+            }
+            // El caso opuesto: el repo NO puede contestar esta afirmacion. Se dice, en
+            // vez de dejar que el agente (o el refutador) la compruebe donde no era —
+            // que es lo que tiraba las dos alertas del desfase de esquema.
+            if (a.fueraDelRepo) {
+                lines.push(`    → NOT CHECKABLE HERE: ${a.fueraDelRepo}`);
+            }
+        }
+        // Con fecha y con la misma etiqueta que atlas_file_context: una nota es una
+        // observación fechada, no estado vigente. Va DESPUÉS de dependientes y
+        // alertas porque es contexto, no una orden.
+        if (m.note) {
+            lines.push(`  - Note from last analysis${m.noteDate ? ` (${m.noteDate})` : ""}: ${m.note}`);
+        }
     }
     if (modules.length > MAX_MODULES) {
         lines.push(`- (+${modules.length - MAX_MODULES} more module(s) affected)`);
@@ -216,10 +267,20 @@ export function modulosDelArchivo(file, rows) {
         if (!label || out.has(label))
             continue;
         const files = Array.isArray(row.files) ? row.files.map(String) : [];
-        if (files.includes(file))
-            out.set(label, row.risk);
+        if (!files.includes(file))
+            continue;
+        const nota = (row.note ?? "").trim();
+        out.set(label, {
+            risk: row.risk,
+            note: nota
+                ? nota.length > MAX_NOTE_CHARS
+                    ? `${nota.slice(0, MAX_NOTE_CHARS - 1).trimEnd()}…`
+                    : nota
+                : null,
+            noteDate: (row.created_at ?? "").slice(0, 10) || null,
+        });
     }
-    return [...out.entries()].map(([module, risk]) => ({ module, risk }));
+    return [...out.entries()].map(([module, v]) => ({ module, ...v }));
 }
 async function cachePath(dir) {
     return gitPath(dir, "changebook-impact-cache.json").catch(() => null);
@@ -247,7 +308,7 @@ function escribirJson(file, data) {
 async function fetchAtlas(db, dir, env) {
     // Mismo proyecto al que reporta analyze/hook: CHANGEBOOK_PROJECT manda, si no
     // el nombre del directorio, casado por slug del servidor primero.
-    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const candidate = projectNameFor(dir, env);
     const slug = slugifyProject(candidate);
     let projects = slug
         ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
@@ -275,7 +336,7 @@ async function fetchAtlas(db, dir, env) {
     // reincidencia (all-time) salen del mismo conjunto.
     const [rows, deps, alerts] = await Promise.all([
         db
-            .rest(`change_module?select=module,files,risk,created_at&project_id=eq.${projectId}&order=created_at.desc&limit=${GRAPH_WINDOW_ROWS}`)
+            .rest(`change_module?select=module,files,risk,note,created_at&project_id=eq.${projectId}&order=created_at.desc&limit=${GRAPH_WINDOW_ROWS}`)
             .catch(() => []),
         db
             .rest(`change_module?select=module,deps&project_id=eq.${projectId}&deps=not.is.null&order=created_at.desc&limit=${GRAPH_WINDOW_ROWS}`)
@@ -353,7 +414,21 @@ export async function warmImpactCache(db, dir, env = process.env) {
         const cached = leerJson(file);
         if (cached && Date.now() - cached.fetched_at < CACHE_TTL_MS)
             return;
-        escribirJson(file, await fetchAtlas(db, dir, env));
+        const fresco = await fetchAtlas(db, dir, env);
+        // Un calentamiento que NO resolvió el proyecto no se cachea.
+        //
+        // Cazado el 2026-07-26 montando el banco de pruebas: `impact --warm` sin
+        // CHANGEBOOK_PROJECT en un directorio cuyo nombre no es el del proyecto
+        // guardaba `{project_id: null, rows: []}`, y `atlasSignals` lo tomaba por
+        // caché válida durante CACHE_TTL_MS. Resultado: cinco minutos de silencio
+        // que se leen EXACTAMENTE igual que "no hay nada que decir" — la clase de
+        // fallo que este producto existe para cazar, dentro del producto.
+        //
+        // Sin cachearlo, el siguiente intento vuelve a preguntar. Cuesta un
+        // calentamiento desacoplado más; callar cinco minutos cuesta el canal.
+        if (!fresco.project_id)
+            return;
+        escribirJson(file, fresco);
     }
     catch {
         // Nadie está mirando esta salida; el síntoma de un fallo aquí es que no hay
@@ -417,13 +492,28 @@ async function buildImpact(db, payload) {
     // archivo con muchas alertas vivas podría comerse el presupuesto entero a
     // 30 ms por grep. Tres es lo que cabe de sobra; el resto pasa sin refutar,
     // que es el lado seguro (la duda deja pasar el aviso).
+    //
+    // El presupuesto lo comparten refutar y localizar, porque son el mismo grep
+    // sobre el mismo simbolo y solo uno de los dos aplica a cada aviso: 'present'
+    // se refuta, 'absent' se localiza (ver avisoRefutado). Nunca se gastan dos.
     let grepsRestantes = MAX_REFUTACIONES;
     const refutada = (a) => {
+        if (a.evidence_expect !== "present")
+            return false;
         if (grepsRestantes <= 0)
             return false;
         grepsRestantes -= 1;
         return avisoRefutado(a, (s) => contarEnRepo(toplevel, s));
     };
+    /** Donde sigue apareciendo el simbolo de un aviso 'absent'. Contesta el condicional. */
+    const localizar = (a) => {
+        if (a.evidence_expect !== "absent")
+            return null;
+        if (grepsRestantes <= 0)
+            return null;
+        grepsRestantes -= 1;
+        return dondeApareceElSimbolo(a, (s) => ficherosEnRepo(toplevel, s));
+    };
     const depsRows = signals.deps ?? [];
     const bloques = [];
     const avisadas = [];
@@ -436,14 +526,42 @@ async function buildImpact(db, payload) {
             .map((m) => ({
             module: m.module,
             risk: m.risk,
+            note: m.note,
+            noteDate: m.noteDate,
             dependents: dependientes.get(m.module) ?? [],
-            alerts: abiertas
+            // Una linea por texto: dos avisos con la MISMA frase no le dejan al
+            // agente hacer nada distinto, por mucho que por dentro sean
+            // afirmaciones opuestas. Gana el que trae linea de comprobacion.
+            alerts: unoPorTexto(abiertas
                 .filter((a) => (a.module ?? "").trim() === m.module && a.plain)
                 .filter((a) => !refutada(a))
-                .map((a) => a.plain),
+                .map((a) => {
+                const donde = localizar(a);
+                const fuera = dondeComprobarlo(a);
+                return {
+                    plain: a.plain,
+                    ...(donde
+                        ? { donde, simbolo: (a.evidence_symbol ?? "").trim() }
+                        : {}),
+                    ...(fuera ? { fueraDelRepo: fuera } : {}),
+                };
+            }), (x) => x.plain, (x) => Boolean(x.donde || x.fueraDelRepo)),
             priorRegressions: recidivism.get(m.module) ?? 0,
         }))
-            .filter(valeLaPena);
+            .filter(valeLaPena)
+            // Por PELIGRO, no por lo más reciente. Solo caben MAX_MODULES y el orden
+            // decide qué se ve: con el orden por recencia, el módulo cuya nota decía
+            // «la prosa gorda expulsaba el mapa» —6 regresiones previas, y el fallo
+            // exacto en el que caí dos veces el 2026-07-26— quedaba en el «+N more».
+            // Servir la nota no vale nada si la nota que importa no entra.
+            //
+            // Total y determinista: el desempate por nombre mantiene el string estable
+            // entre sesiones, que es lo que evita pagar una escritura de caché a 1,25×
+            // en vez de una lectura a 0,1×.
+            .sort((a, b) => b.alerts.length - a.alerts.length ||
+            b.priorRegressions - a.priorRegressions ||
+            b.dependents.length - a.dependents.length ||
+            a.module.localeCompare(b.module));
         if (impactos.length === 0)
             continue;
         bloques.push(impactText(file, impactos));

package/dist/import.js

@@ -10,7 +10,7 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
+import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, projectNameFor, usableSummary, } from "./git.js";
 import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI } from "./optimize.js";
 // Under the server's MAX_BATCH_ITEMS (25) to leave headroom.
@@ -29,7 +29,7 @@ const SKIP_FILE_PATTERNS = [
 ];
 export async function importHistory(db, options = {}) {
     const cwd = path.resolve(options.dir ?? process.cwd());
-    const projectName = path.basename(cwd);
+    const projectName = projectNameFor(cwd);
     const count = Math.max(1, Math.min(options.commits ?? 25, 100));
     // A previous run may have been interrupted after submitting: the Anthropic
     // batch keeps running server-side, so finish those before spending more.

package/dist/sync.js

@@ -285,23 +285,25 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
             ...taskTitles.map((t) => `- ${sanitizeCell(t.slice(0, 120))}`),
         ]
         : [];
-    // El orden de renderizado (legibilidad) y la prioridad de presupuesto
-    // (utilidad para el agente) son independientes: si no cabe todo, caen
-    // primero los últimos cambios y los módulos, nunca las regresiones.
+    // El orden de renderizado (legibilidad) y la prioridad de presupuesto (qué se
+    // recorta primero) son independientes. Los dos importan, y hasta el 2026-07-26
+    // solo uno estaba bien.
+    //
+    // EL RIESGO VA PRIMERO AL LEER, y eso es el cambio. El presupuesto ya
+    // priorizaba las regresiones sobre el mapa, pero el ORDEN DE LECTURA ponía
+    // `### Módulos` en cabeza, así que lo que estaba frágil quedaba debajo de una
+    // lista de quince módulos. Medido ese día con 30 corridas: el bloque empujado
+    // al prompt del agente entrega 0,40 de los hechos de riesgo contra 0,60 de la
+    // tool, y las cinco corridas del brazo con empuje van de 0,4 a 0,6 mientras las
+    // de git puro van de 0 a 0,2. O sea: el canal llega, el agente lo tiene
+    // delante, y no lo usa. La hipótesis que queda es la posición.
+    //
+    // Y `hotspots` sube de prioridad 4 a 1. Con 4 era la penúltima en caer, así que
+    // en un proyecto con muchos módulos se recortaba y los críticos solo aparecían
+    // como un ⚠ inline dentro de la lista del mapa — el sitio exacto donde no se
+    // leen. Los módulos bajan a 3: el mapa se puede pedir con una tool, el riesgo
+    // de hoy no está en ningún sitio más.
     const sections = [
-        { key: 'modules', priority: 2, title: '### Módulos', lines: moduleLines },
-        {
-            key: 'tasks',
-            priority: 1,
-            title: '### Encargos pendientes del dueño (proponte atacarlos)',
-            lines: taskLines,
-        },
-        {
-            key: 'couplings',
-            priority: 3,
-            title: '### Módulos que cambian juntos (si tocas uno, revisa el otro)',
-            lines: couplingLines,
-        },
         {
             key: 'alerts',
             priority: 0,
@@ -316,10 +318,23 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         },
         {
             key: 'hotspots',
-            priority: 4,
-            title: '### Avisos abiertos (revisar antes de modificar)',
+            priority: 1,
+            title: '### Módulos críticos (frágiles por diseño: revisa antes de modificar)',
             lines: hotspotLines,
         },
+        {
+            key: 'couplings',
+            priority: 2,
+            title: '### Módulos que cambian juntos (si tocas uno, revisa el otro)',
+            lines: couplingLines,
+        },
+        {
+            key: 'tasks',
+            priority: 1,
+            title: '### Encargos pendientes del dueño (proponte atacarlos)',
+            lines: taskLines,
+        },
+        { key: 'modules', priority: 3, title: '### Módulos', lines: moduleLines },
         {
             key: 'changes',
             priority: 5,
@@ -328,21 +343,62 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         },
     ];
     let budget = SYNC_BUDGET_CHARS - head.join('\n').length - END.length;
+    // ── El suelo del mapa ──────────────────────────────────────────────────────
+    //
+    // El presupuesto es de suma cero, así que poner el riesgo primero se lo come.
+    // Medido el 2026-07-26 al hacerlo: con datos de producción reales (1 regresión,
+    // 1 control en riesgo, 2 módulos críticos, 2 encargos) el mapa cayó de 18
+    // módulos a DOS.
+    //
+    // Y eso no es un detalle estético: el estudio de 76 agentes del 2026-07-20
+    // concluyó que el mapa expulsado era «la causa nº 1 de que el agente ignore o
+    // desconfíe del atlas». Cambiar un fallo medido por otro fallo medido no es una
+    // mejora.
+    //
+    // Así que el reparto deja de ser el-que-llega-primero-se-lo-lleva-todo: se
+    // reserva lo que cuestan las primeras MIN_LINEAS_MAPA líneas del mapa, y solo
+    // el resto se disputa por prioridad. Si el mapa tiene menos líneas que el
+    // suelo, sobra menos reserva; si no hay mapa, no se reserva nada.
+    const MIN_LINEAS_MAPA = 6;
+    const mapa = sections.find((x) => x.key === 'modules');
+    let reservaMapa = 0;
+    if (mapa && mapa.lines.length > 0) {
+        reservaMapa = mapa.title.length + 2;
+        for (const line of mapa.lines.slice(0, MIN_LINEAS_MAPA)) {
+            reservaMapa += line.length + 1;
+        }
+        // Nunca más de un tercio: el suelo protege al mapa, no lo convierte en el
+        // dueño del bloque.
+        reservaMapa = Math.min(reservaMapa, Math.floor(budget / 3));
+        // Se APARTA del fondo común aquí. Sin esto, dárselo luego al mapa como
+        // `budget + reserva` lo contaba dos veces y el bloque se pasaba del tope
+        // (medido: 2.344 de 2.000).
+        budget -= reservaMapa;
+    }
     const includedCount = new Map();
     for (const s of [...sections].sort((a, b) => a.priority - b.priority)) {
         if (s.lines.length === 0)
             continue;
+        // El mapa gasta su reserva ADEMÁS de lo que haya quedado libre.
+        const disponible = s.key === 'modules' ? budget + reservaMapa : budget;
         let cost = s.title.length + 2; // título + línea en blanco separadora
         let count = 0;
         for (const line of s.lines) {
-            if (cost + line.length > budget)
+            if (cost + line.length > disponible)
                 break;
             cost += line.length + 1;
             count += 1;
         }
         if (count > 0) {
             includedCount.set(s.key, count);
-            budget -= cost;
+            if (s.key === 'modules') {
+                // Lo que consumió por encima de su reserva sale del fondo común.
+                budget -= Math.max(0, cost - reservaMapa);
+                reservaMapa = 0;
+            }
+            else {
+                budget -= cost;
+            }
         }
     }
     const lines = [...head];

package/dist/tools.js

@@ -7,7 +7,7 @@
 import path from "node:path";
 import { z } from "zod";
 import { execFileAsync } from "./git.js";
-import { avisoRefutado, contarEnRepo, slugifyProject, } from "./guard.js";
+import { avisoRefutado, contarEnRepo, dondeApareceElSimbolo, dondeComprobarlo, ficherosEnRepo, slugifyProject, unoPorTexto, } from "./guard.js";
 import { SupabaseError } from "./supabase.js";
 const CHARACTER_LIMIT = 25_000;
 /**
@@ -822,17 +822,49 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             // 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)
+            const enElProyecto = cwdEsElProyecto(project);
+            const refutada = enElProyecto
                 ? (a) => avisoRefutado(a, (s) => contarEnRepo(process.cwd(), s))
                 : () => false;
-            const alertsByModule = new Map();
+            // La otra mitad, desde el 2026-07-26: un aviso 'absent' cuyo símbolo
+            // SIGUE apareciendo ya no se descarta (era ambiguo y tiraba las dos
+            // alertas que predijeron el desfase de esquema de producción). Se sirve
+            // diciendo dónde aparece, que es contestar el condicional del texto
+            // ("...si los hubiera") en vez de prohibir la redacción.
+            //
+            // Mismas palabras que el hook (impactText) a propósito: dos redacciones
+            // del mismo hecho son dos hechos para el agente.
+            const localizada = enElProyecto
+                ? (a) => dondeApareceElSimbolo(a, (s) => ficherosEnRepo(process.cwd(), s))
+                : () => null;
+            // Se construye la lista ANTES de renderizar para poder dejar una linea
+            // por texto: dos avisos con la misma frase se leen como una repeticion
+            // aunque por dentro sean afirmaciones opuestas, y sobre dos frases
+            // identicas no se puede actuar distinto. Gana el que trae comprobacion.
+            const porModulo = 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 donde = localizada(a);
+                const fuera = dondeComprobarlo(a);
+                let extra = "";
+                if (donde) {
+                    extra +=
+                        `\n    → CHECKED NOW: "${(a.evidence_symbol ?? "").trim()}" still appears in ${donde.join(", ")}` +
+                            ` — alert expects it gone: either a reference was missed, or the alert is stale`;
+                }
+                // El repo no puede contestar esta afirmacion: se dice, en vez de
+                // dejar que se compruebe donde no era.
+                if (fuera)
+                    extra += `\n    → NOT CHECKABLE HERE: ${fuera}`;
+                porModulo.set(m, [...(porModulo.get(m) ?? []), { plain: a.plain, extra }]);
+            }
+            const alertsByModule = new Map();
+            for (const [m, entradas] of porModulo) {
+                alertsByModule.set(m, unoPorTexto(entradas, (e) => e.plain, (e) => e.extra.length > 0).map((e) => e.plain + e.extra));
             }
             // Reincidencia: nº de problemas de regresión DISTINTOS por módulo
             // (count(distinct plain), all-time), solo los con antecedentes (>= 2).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "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.9",
+  "version": "0.4.10",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.4.9",
+      "version": "0.4.10",
       "transport": {
         "type": "stdio"
       }