changebook 0.4.9 → 0.5.0

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,71 @@
  *            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 { createHash } from "node:crypto";
+import { execFileAsync, gitPath, projectNameFor } from "./git.js";
 import { feedWarningFor } from "./feed.js";
+import { avisoDeRamaPara } from "./rama.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 +131,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 +198,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,20 +283,53 @@ 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();
+    // Map y no Set: al colapsar dos avisos con el mismo (modulo, texto) hay que
+    // QUEDARSE con los dos ids, no descartar el segundo. Se sirve una linea —dos
+    // frases identicas no dejan actuar distinto— pero se registran las dos
+    // alertas, que es lo que permitira atribuir el veredicto a la que toca.
+    const porClave = new Map();
     const findings = [];
     for (const alert of alerts) {
         const module = (alert.module ?? "").trim();
         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;
@@ -148,10 +338,22 @@ export function guardFindings(staged, alerts, filesByModule, refutado) {
         if (refutado?.(alert))
             continue;
         const key = module + "\u0000" + plain;
-        if (seen.has(key))
+        const id = alert.id ?? null;
+        const ya = porClave.get(key);
+        if (ya) {
+            // El aviso ya se sirve; lo unico que queda por recoger es su identidad.
+            if (id && !ya.alertIds.includes(id))
+                ya.alertIds.push(id);
             continue;
-        seen.add(key);
-        findings.push({ module, plain, staged: touched });
+        }
+        const finding = {
+            module,
+            plain,
+            staged: touched,
+            alertIds: id ? [id] : [],
+        };
+        porClave.set(key, finding);
+        findings.push(finding);
     }
     return findings;
 }
@@ -167,13 +369,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
@@ -182,25 +421,47 @@ export function contarEnRepo(dir, simbolo) {
             // aviso de tipo "esto sigue usandose" encontraria su propia cita y no
             // podria refutarse jamas. Lo cazo el test, no el diseno.
             ":!*.md",
+            // Y tampoco en el resto de la PROSA, por la misma razon exacta. El
+            // 2026-07-30, usando el producto sobre si mismo, un aviso sobre
+            // `reason` se sirvio diciendo «still appears in privacidad.html,
+            // terminos.html» — la comprobacion encontro la PALABRA en dos paginas
+            // legales y la presento como si hablara del codigo. Un simbolo en un
+            // parrafo no es una referencia: es una coincidencia de idioma.
+            ":!*.html",
+            ":!*.txt",
+            ":!*.csv",
+            ":!*.svg",
             // Con comodín a propósito: un pathspec sin comodín ("docs/") hace
             // abortar a git grep si la carpeta no existe — en cualquier repo de
             // usuario sin docs/ el buscador devolvía null y la refutación moría
             // 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;
     }
 }
+/**
+ * LA VERSIÓN DE LA FORMA DE LA CACHÉ. Súbela cuando cambie QUÉ se guarda —las
+ * columnas del select, un campo del que dependa una decisión—, no cuando cambie
+ * el código de alrededor.
+ *
+ * El caso concreto que la trae: el commit anterior añadió `evidence_scope` al
+ * select de las alertas. Sin versión, la caché escrita por el binario de antes
+ * se deserializa sin error y el guardián decide sobre ella cinco minutos más,
+ * con el ámbito ausente — o sea, sin refutar nada. Y no hay forma de notarlo: la
+ * caché vieja no está rota, solo incompleta, así que el guardián se calla en vez
+ * de fallar. Mismo modo de fallo que la caché de `{project_id: null}` que costó
+ * cinco minutos de silencio el 2026-07-26.
+ *
+ * Empieza en 1: una caché SIN `v` es anterior al versionado y se descarta
+ * siempre.
+ */
+const GUARD_CACHE_V = 1;
 export async function stagedFiles(dir) {
     // -z: NUL-separated, and crucially git does NOT octal-quote non-ASCII paths
     // (default quotepath would emit "m\303\263dulo.ts", which never matches the
@@ -209,12 +470,25 @@ export async function stagedFiles(dir) {
     const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], { cwd: dir, encoding: "utf8" });
     return stdout.split("\0").filter(Boolean);
 }
+/**
+ * ¿Se puede decidir sobre esta caché? De esta forma Y fresca.
+ *
+ * Otra forma → se trata como si no hubiera caché: se vuelve a consultar. El
+ * guardián ya sabe hacer eso (es el camino en frío), así que descartar no añade
+ * ningún modo de fallo nuevo. Pura y exportada porque lo que evita —decidir
+ * sobre campos que no están— no se ve desde fuera: la caché vieja no está rota.
+ */
+export function cacheDelGuardianServible(cache, ahora) {
+    if (!cache)
+        return false;
+    if (cache.v !== GUARD_CACHE_V)
+        return false;
+    return ahora - cache.fetched_at <= CACHE_TTL_MS;
+}
 function loadCache(file) {
     try {
         const cache = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (Date.now() - cache.fetched_at > CACHE_TTL_MS)
-            return null;
-        return cache;
+        return cacheDelGuardianServible(cache, Date.now()) ? cache : null;
     }
     catch {
         return null;
@@ -233,7 +507,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`)
@@ -245,7 +519,17 @@ 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,evidence_symbol,evidence_expect,files&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
+        alerts = await db.rest(
+        // `evidence_scope` NO es opcional aquí, por mucho que el tipo lo sea: sin
+        // él, `alcanceDelRepo` devuelve "sin_declarar" para TODA alerta y la
+        // refutación de `avisoRefutado` no descarta nada nunca. El campo se
+        // escribe en la base desde el 2026-07-26 y ningún cliente lo pedía; el
+        // comentario de `avisoRefutado` decía que esa rama "disparó 0 veces en
+        // producción", y disparó cero porque el dato no llegaba, no porque el gate
+        // fuera barato. Lo vigila `test/alcanceLlegaAlCliente.test.ts`, que lee
+        // ESTA línea: un test de comportamiento no lo caza, porque los stubs
+        // inyectan el campo a mano.
+        `regression_alerts?select=id,module,plain,created_at,evidence_symbol,evidence_expect,evidence_scope,evidence_line,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)),
         ];
@@ -256,6 +540,7 @@ async function fetchSignals(db, dir, env) {
     }
     if (cacheFile) {
         const cache = {
+            v: GUARD_CACHE_V,
             fetched_at: Date.now(),
             project_id: projectId,
             alerts,
@@ -320,6 +605,71 @@ export function findingsMessage(findings, block) {
         : "\nReview or dismiss the alert in your atlas: changebook open\n");
     return lines.join("\n");
 }
+/** Tope de rutas por fila: un registro no puede crecer sin limite por un commit gigante. */
+const MAX_FICHEROS_EN_LA_ENTREGA = 50;
+/**
+ * EL NUCLEO, sin la forma del guardian.
+ *
+ * Existe porque hay DOS canales que sirven avisos —el guardian en el commit y el
+ * hook antes de editar— y el libro tiene que registrar lo mismo en los dos. Si
+ * cada uno armara su fila, el tope de ficheros o el dedup de ids podrian
+ * divergir y "en total" empezaria a significar dos cosas distintas segun el
+ * canal. Un criterio, un sitio.
+ *
+ * `message` es lo que de verdad se sirvio, no un resumen: el hash ata la fila al
+ * texto exacto que se imprimio, y eso es lo que impide reescribir el consejo a
+ * posteriori para que parezca que acerto.
+ */
+export function entregaDe(input) {
+    if (input.message.trim().length === 0)
+        return null;
+    const alertIds = [
+        ...new Set(input.alertIds.filter((id) => typeof id === "string" && id.length > 0)),
+    ];
+    return {
+        advice_hash: input.hash(input.message),
+        alert_ids: alertIds,
+        advice_files: [...new Set(input.files)].slice(0, MAX_FICHEROS_EN_LA_ENTREGA),
+        head_sha: input.headSha,
+    };
+}
+export function entregaDeAviso(findings, message, headSha, hash) {
+    if (findings.length === 0)
+        return null;
+    return entregaDe({
+        // flatMap y no map: un finding puede venir de varias alertas colapsadas por
+        // texto (ver GuardFinding.alertIds). El Set de `entregaDe` quita ademas el
+        // mismo aviso servido por dos rutas, que es otra cosa.
+        alertIds: findings.flatMap((f) => f.alertIds),
+        files: findings.flatMap((f) => f.staged),
+        message,
+        headSha,
+        hash,
+    });
+}
+/** sha256 en hex. Aparte para que `entregaDeAviso` se pueda probar sin crypto. */
+export function hashDelTexto(texto) {
+    return createHash("sha256").update(texto, "utf8").digest("hex");
+}
+/**
+ * El commit en el que esta el repo. `null` si no se puede saber — y ese null se
+ * guarda tal cual: un ancla inventada es peor que ninguna. Repo recien creado
+ * sin commits incluido, que es el caso que devuelve error de verdad.
+ */
+export function headShaDe(dir) {
+    try {
+        const salida = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: dir,
+            encoding: "utf8",
+            timeout: 1_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return /^[0-9a-f]{7,40}$/.test(salida) ? salida : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Returns the process exit code. Everything that can go wrong resolves to 0
  * (pass): the guard informs, it does not gatekeep — except when the user
@@ -337,6 +687,13 @@ export async function runGuard(db, dir, env = process.env) {
     const pulse = await feedWarningFor(dir);
     if (pulse)
         console.error(pulse);
+    // ANTES del corte por credenciales a proposito: que tu rama vaya a revertir el
+    // trabajo de otro es un hecho de git, no del atlas. Quien no tenga sesion —o
+    // no tenga cuenta— tambien merece enterarse. Ver rama.ts para el porque de la
+    // señal (solapamiento, no "vas atrasado").
+    const rama = await avisoDeRamaPara(dir);
+    if (rama)
+        console.error(rama);
     if (!db.hasCredentials())
         return 0;
     let staged;
@@ -367,7 +724,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
@@ -391,6 +776,9 @@ export async function runGuard(db, dir, env = process.env) {
                 tool: "guard_precommit",
                 source: "guard",
                 chars_served: message.length,
+                // El libro de entregas. Solo viaja cuando de verdad se avisó: una
+                // corrida limpia sigue siendo una fila normal, purgable como siempre.
+                ...(entregaDeAviso(findings, message, headShaDe(dir), hashDelTexto) ?? {}),
             })
                 .catch(() => { }),
             new Promise((resolve) => {