changebook 0.8.0 → 0.9.1

package/README.md

@@ -57,6 +57,7 @@ your other servers.
 | `changebook scan [dir] [--json\|--card\|--badge]` | Coupling report for **any** repo from its git history alone: no account, no network, writes nothing — run it on something you just cloned. `--card` renders a shareable SVG, `--badge` publishes four numbers and prints the README snippet (needs an account; `--badge --off` turns it off). The badge exposes those four numbers and nothing else — not your code, modules or change summaries. |
 | `changebook silence [dir]` | How often the `PreToolUse` hook stays quiet, with both raw numbers. Local by design: it answers the day you install it, not two days later. |
 | `changebook friction [dir]` | Where the agent's work gets redone in this repo, read from the **local** Claude Code transcripts — no prose leaves the machine, only paths, modules, dates and a session hash. Says **MUERTO** if the repo has edits and it read nothing, and reports its own blind spot: edits made through the shell (`sed -i`, heredocs) leave no before/after, so ~25% of writes are invisible to it and it says so. |
+| `changebook audit [dir]` | Static check of your agent setup — no network, no credentials, nothing written. Flags rules in `CLAUDE.md`/`AGENTS.md` that cite files which no longer exist (with a «did you mean…»), how much context you pay every session, and whether the impact hook is actually installed. Every check here was written after it found something real, not from a best-practices list. |
 | `changebook guard [dir]` | What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; `CHANGEBOOK_GUARD=block` makes findings abort the commit (bypass once with `git commit --no-verify`), `CHANGEBOOK_GUARD=off` silences it. |
 | `changebook sync [dir]` | Refresh the product map inside `CLAUDE.md`/`AGENTS.md`. |
 | `changebook init [dir]` | login + register MCP server + install hook + sync, in one go. |

package/dist/audit.js

@@ -0,0 +1,226 @@
+/**
+ * `changebook audit` — la pieza `[5]`: auditoría ESTÁTICA del setup.
+ *
+ * QUÉ LA DISTINGUE DE UNA LISTA DE BUENAS PRÁCTICAS. Cada comprobación de aquí
+ * se escribió DESPUÉS de encontrar algo real en un setup real (este repo, el
+ * 24/08), no antes. Una lista de comprobaciones inventadas produce avisos que
+ * nadie ha visto fallar nunca, y eso entrena a ignorar la herramienta.
+ *
+ * SIN RED Y SIN CREDENCIALES, como `silence` y `scan`: todo lo que dice sale de
+ * ficheros del repo. Así contesta el mismo día en que alguien lo instala, antes
+ * de tener cuenta, y no puede quedarse callada por un fallo de red — que es la
+ * forma en que una auditoría miente.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Los ficheros de contexto que un agente lee al abrir, por convención. */
+export const FICHEROS_DE_CONTEXTO = ['CLAUDE.md', 'AGENTS.md'];
+const INICIO = '<!-- changebook:start -->';
+const FIN = '<!-- changebook:end -->';
+/**
+ * Las rutas citadas entre backticks que parecen ficheros.
+ *
+ * Se exige extensión conocida a propósito: sin ella, cualquier `foo.bar` de la
+ * prosa entraría como ruta y la auditoría publicaría falsos positivos — que en
+ * una herramienta que se corre a mano es peor que no publicar nada.
+ */
+export function rutasCitadas(texto) {
+    const re = /`([A-Za-z0-9_./-]+\.(?:ts|tsx|js|mjs|cjs|sql|yml|yaml|json|sh))`/g;
+    return [...new Set([...texto.matchAll(re)].map((m) => m[1]))];
+}
+/** El bloque auto-generado, si lo hay. */
+export function partirContexto(texto) {
+    const i = texto.indexOf(INICIO);
+    const j = texto.indexOf(FIN);
+    if (i === -1 || j === -1 || j < i)
+        return { auto: '', aMano: texto };
+    const auto = texto.slice(i, j + FIN.length);
+    return { auto, aMano: texto.replace(auto, '') };
+}
+/**
+ * ¿Existe? Y si no, ¿hay algo que se le parezca?
+ *
+ * El «quizá quisiste decir» no es adorno: los dos casos reales que encontró
+ * esto el 24/08 —`test/aliasEnLasToolsDelCli.ts` y `test/sinRayasEnLaWeb.ts`—
+ * eran el mismo fichero con `.test.ts`. Un aviso que sólo dice «no existe»
+ * manda a buscar; uno que dice el nombre bueno se arregla en diez segundos.
+ */
+export function resolverCita(raiz, cita) {
+    if (fs.existsSync(path.join(raiz, cita)))
+        return { existe: true };
+    // UN NOMBRE A SECAS NO ES UNA RUTA ROTA. La primera versión avisaba de
+    // `publish-extension.yml` —que existe, en `.github/workflows/`— porque se
+    // cita por su nombre. Ese falso positivo enseña a ignorar los avisos buenos,
+    // que era justo el riesgo escrito en la cabecera de este fichero. Cazado el
+    // 24/08 corriendo la auditoría contra su propio repo.
+    if (!cita.includes('/')) {
+        return { existe: buscarPorNombre(raiz, cita) };
+    }
+    const dir = path.join(raiz, path.dirname(cita));
+    const base = path.basename(cita, path.extname(cita));
+    let vecinos;
+    try {
+        vecinos = fs.readdirSync(dir);
+    }
+    catch {
+        return { existe: false };
+    }
+    const parecido = vecinos.find((v) => v.startsWith(`${base}.`) && v !== path.basename(cita));
+    return parecido
+        ? { existe: false, parecido: path.join(path.dirname(cita), parecido) }
+        : { existe: false };
+}
+/**
+ * ¿Existe algún fichero con ese nombre, en cualquier parte del repo?
+ *
+ * Con tope de profundidad y saltándose lo que no se versiona: sin eso, un
+ * `node_modules` convierte una orden instantánea en una que se piensa.
+ */
+function buscarPorNombre(raiz, nombre, profundidad = 6) {
+    const saltar = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+    const pila = [[raiz, 0]];
+    while (pila.length > 0) {
+        const [dir, nivel] = pila.pop();
+        let entradas;
+        try {
+            entradas = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entradas) {
+            if (e.isFile() && e.name === nombre)
+                return true;
+            if (e.isDirectory() && !saltar.has(e.name) && nivel < profundidad) {
+                pila.push([path.join(dir, e.name), nivel + 1]);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Citas rotas en los ficheros de contexto.
+ *
+ * DE DÓNDE SALE: 2 de 9 rutas citadas en el `CLAUDE.md` de este repo no
+ * existían. Una regla que apunta a código que no está es peor que no tener la
+ * regla — le enseña al agente a desconfiar del documento entero, incluidas las
+ * partes que sí valen.
+ */
+export function citasRotas(raiz) {
+    const out = [];
+    for (const nombre of FICHEROS_DE_CONTEXTO) {
+        let texto;
+        try {
+            texto = fs.readFileSync(path.join(raiz, nombre), 'utf8');
+        }
+        catch {
+            continue; // No tenerlo no es un fallo: no todos los repos los tienen.
+        }
+        // Sólo lo escrito A MANO: el bloque auto-generado se regenera solo y sus
+        // rutas salen de la base de datos, no de la prosa de nadie.
+        const { aMano } = partirContexto(texto);
+        const rotas = rutasCitadas(aMano)
+            .map((c) => ({ cita: c, ...resolverCita(raiz, c) }))
+            .filter((c) => !c.existe);
+        if (rotas.length === 0)
+            continue;
+        out.push({
+            nivel: 'aviso',
+            titulo: `${nombre}: ${rotas.length} cita(s) apuntan a ficheros que no existen`,
+            detalle: rotas.map((r) => r.parecido ? `${r.cita} → ¿quisiste decir ${r.parecido}?` : r.cita),
+        });
+    }
+    return out;
+}
+/**
+ * El peso de contexto que se paga en CADA sesión.
+ *
+ * DE DÓNDE SALE, medido el 24/08 en este repo: el bloque auto-generado se
+ * raciona a 2.000 chars —hay una PR entera dedicada a que sea honesto cuando
+ * recorta— y al lado había **12.407 chars escritos a mano, seis veces más**,
+ * sin tope y sin que nadie los midiera. No se juzga si sobran: se ponen delante.
+ */
+export function pesoDeContexto(raiz, topeAuto = 2000) {
+    const out = [];
+    for (const nombre of FICHEROS_DE_CONTEXTO) {
+        let texto;
+        try {
+            texto = fs.readFileSync(path.join(raiz, nombre), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { auto, aMano } = partirContexto(texto);
+        const detalle = [
+            `total ${texto.length} chars`,
+            `auto-generado ${auto.length} (tope ${topeAuto})`,
+            `escrito a mano ${aMano.length}, sin tope`,
+        ];
+        // El aviso salta cuando lo de a mano PASA del bloque racionado: hasta ahí,
+        // la comparación no dice nada que preocupe.
+        out.push({
+            nivel: aMano.length > topeAuto ? 'aviso' : 'nota',
+            titulo: aMano.length > topeAuto
+                ? `${nombre}: lo escrito a mano pesa ${(aMano.length / topeAuto).toFixed(1)}× el bloque racionado`
+                : `${nombre}: ${texto.length} chars en cada sesión`,
+            detalle,
+        });
+    }
+    return out;
+}
+/**
+ * El hook de contexto: ¿está puesto, y su orden existe?
+ *
+ * Un hook cuyo comando no resuelve falla en silencio para siempre — la línea
+ * que instala el propio producto acaba en `|| true`, así que ni siquiera deja
+ * un exit distinto de cero. Es el Invariante 17 en la instalación.
+ */
+export function hookDeImpacto(raiz) {
+    const p = path.join(raiz, '.claude', 'settings.json');
+    let crudo;
+    try {
+        crudo = fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        return [
+            {
+                nivel: 'aviso',
+                titulo: 'No hay hook de impacto instalado',
+                detalle: [
+                    'Sin él, nadie te avisa de qué depende del fichero que vas a tocar.',
+                    'Se instala con `changebook init`.',
+                ],
+            },
+        ];
+    }
+    const puesto = /changebook\s+impact/.test(crudo);
+    return puesto
+        ? []
+        : [
+            {
+                nivel: 'aviso',
+                titulo: '.claude/settings.json existe pero no lanza `changebook impact`',
+                detalle: ['Se reinstala con `changebook init`.'],
+            },
+        ];
+}
+/** Todas las comprobaciones, en el orden en que conviene leerlas. */
+export function auditarSetup(raiz) {
+    return [...citasRotas(raiz), ...hookDeImpacto(raiz), ...pesoDeContexto(raiz)];
+}
+export function informeDeAuditoria(hallazgos) {
+    const avisos = hallazgos.filter((h) => h.nivel === 'aviso');
+    if (hallazgos.length === 0)
+        return 'Setup sin nada que señalar.';
+    const cabecera = avisos.length === 0
+        ? 'Setup sin avisos.'
+        : `${avisos.length} aviso(s) sobre tu setup:`;
+    return [
+        cabecera,
+        ...hallazgos.map((h) => [
+            `${h.nivel === 'aviso' ? '⚠' : '·'} ${h.titulo}`,
+            ...h.detalle.map((d) => `    ${d}`),
+        ].join('\n')),
+    ].join('\n');
+}
+//# sourceMappingURL=audit.js.map

package/dist/friction.js

@@ -289,24 +289,27 @@ export const MIN_CORRECCIONES_PARA_HABLAR = 2;
  * vez sobre el mismo fichero producirían "reediciones" cruzadas que son un
  * artefacto del orden en que se leyeron los ficheros, no un hecho.
  */
-export function correccionesDeEdiciones(ediciones) {
+export function veredictosDeEdiciones(ediciones) {
     const ultima = new Map();
-    const out = [];
+    const out = new Map();
     for (const e of ediciones) {
         const clave = `${e.sesion} ${e.ruta}`;
         const previa = ultima.get(clave);
         // `clasificarEdicion` y no `clasificarReedicion`: es el MISMO clasificador
         // que usa `procesarFriccion`. Con dos, el ranking del CLI y lo que se sube
         // dirían cosas distintas — ya pasó con el módulo, y van tres veces.
-        if (previa &&
-            e.turno > previa.turno &&
-            clasificarEdicion(previa, e) === 'correccion') {
-            out.push(e);
-        }
+        out.set(e, previa ? clasificarEdicion(previa, e) : 'primera');
         ultima.set(clave, e);
     }
     return out;
 }
+export function correccionesDeEdiciones(ediciones) {
+    const veredictos = veredictosDeEdiciones(ediciones);
+    // El filtro por turno vive en `clasificarEdicion`, que devuelve 'iteracion'
+    // para las del mismo turno. Repetirlo aquí sería la segunda copia de la
+    // regla, y este fichero ya lleva tres avisos de lo que eso cuesta.
+    return ediciones.filter((e) => veredictos.get(e) === 'correccion');
+}
 /**
  * De correcciones a filas de fricción, por fichero: la vista de TASA.
  *
@@ -862,6 +865,105 @@ export function lineaDeSuceso(s) {
         ? `${cuando} · ${s.ruta} — ${s.modulo}`
         : `${cuando} · ${s.ruta}`;
 }
+// ── Dónde el agente rehace SU PROPIO trabajo ─────────────────────────────────
+//
+// OTRA PREGUNTA, no la misma con otro umbral. La corrección mide «tú tuviste
+// que arreglarlo»; esto mide «al agente le costó varios intentos acertar». La
+// segunda no dice que el resultado esté mal — dice que ese fichero es caro.
+//
+// POR QUÉ ESTA SEÑAL SÍ SE PUEDE USAR Y LA OTRA NO, medido el 24/08 contra
+// producción:
+//   · Las correcciones son **8**, repartidas en **7 sesiones distintas**, y
+//     sólo un fichero repite. No hay patrón del que generalizar nada.
+//   · Las iteraciones son **811** y se concentran: 18 ficheros con iteración en
+//     ≥3 sesiones distintas.
+//
+// Y LA COMPROBACIÓN QUE PODÍA TUMBARLA: si el ratio iteración/ediciones fuera
+// plano, esto sería el conteo de cambios disfrazado — y el atlas ya lo da. No
+// lo es: va del **37% al 95%**, mediana 63%.
+//
+// Tampoco es el tamaño disfrazado, ni el historial de regresiones disfrazado:
+// `App.tsx` es el fichero MÁS GRANDE (2.604 líneas), está en el trinquete de
+// módulos-dios, y tiene el ratio MÁS BAJO (37%). `impact.ts` encabeza con 85%
+// y no está en esa lista. Son señales independientes.
+/**
+ * Sesiones distintas mínimas para llamarlo patrón.
+ *
+ * TRES, y es la constante que hace el trabajo: con una sola sesión, un ratio
+ * del 95% es **una tarea grande** —`privacidad.html`, 19 iteraciones de 20 en
+ * una sentada—, no un fichero difícil. Lo que distingue «me costó aquel día» de
+ * «me cuesta siempre» es que vuelva a pasar en sesiones que no se conocen entre
+ * sí.
+ */
+export const MIN_SESIONES_PARA_PATRON = 3;
+/**
+ * Los ficheros donde el agente rehace su propio trabajo, una y otra vez, en
+ * sesiones distintas.
+ *
+ * NO SUGIERE QUÉ HACER, y eso es deliberado. Con 8 correcciones en 7 sesiones
+ * no hay base para que nada proponga una regla; lo que hay base para decir es
+ * el HECHO. El remedio lo elige quien conoce el código — igual que el atlas
+ * dice «esto rompió 8 veces» y no escribe el arreglo.
+ */
+export function ficherosQueCuestan(ediciones, opts = {}) {
+    const suelo = opts.sueloDeExposicion ?? SUELO_DE_EXPOSICION;
+    const minSesiones = opts.minSesiones ?? MIN_SESIONES_PARA_PATRON;
+    // LA MISMA cadena que alimenta las correcciones. Dos pasadas distintas sobre
+    // la misma pregunta acaban discrepando, y en este fichero ya van tres avisos.
+    const veredictos = veredictosDeEdiciones(ediciones);
+    const acc = new Map();
+    for (const e of ediciones) {
+        const f = acc.get(e.ruta) ?? {
+            ediciones: 0,
+            iteraciones: 0,
+            sesiones: new Set(),
+        };
+        f.ediciones += 1;
+        f.sesiones.add(e.sesion);
+        if (veredictos.get(e) === 'iteracion')
+            f.iteraciones += 1;
+        acc.set(e.ruta, f);
+    }
+    return [...acc.entries()]
+        .map(([ruta, v]) => ({
+        ruta,
+        ediciones: v.ediciones,
+        iteraciones: v.iteraciones,
+        sesiones: v.sesiones.size,
+        ratio: v.iteraciones / v.ediciones,
+    }))
+        .filter((f) => f.ediciones >= suelo && f.sesiones >= minSesiones)
+        .sort((a, b) => b.ratio - a.ratio);
+}
+/** Una línea por fichero caro. */
+export function lineaDeFicheroQueCuesta(f) {
+    return `${Math.round(f.ratio * 100)}% — ${f.iteraciones} de ${f.ediciones} ediciones fueron rehacer, en ${f.sesiones} sesiones distintas`;
+}
+/** Cuántos ficheros caros se enseñan. El resto se dice, no se calla. */
+export const MAX_FICHEROS_CAROS = 5;
+/**
+ * El bloque, o `[]` si no hay nada que decir.
+ *
+ * Vive fuera de `rankingDeFriccion` para tener contrato propio: hoy me han
+ * mordido DOS veces bloques que existían, estaban probados y no se pintaban
+ * —la fricción que no llegaba al brief del CLI, y la sección que el presupuesto
+ * tiraba en silencio—. Un armado sin test es la tercera.
+ *
+ * Las rutas llegan YA relativas: hacer `path.relative` aquí dentro ataría esta
+ * función al disco y dejaría de ser pura.
+ */
+export function bloqueDeFicherosCaros(caros) {
+    if (caros.length === 0)
+        return [];
+    const mostrados = caros.slice(0, MAX_FICHEROS_CAROS);
+    return [
+        '',
+        // El total en la cabecera: recortar sin decirlo se lee como «esto es todo».
+        `Dónde el agente rehace su propio trabajo (${mostrados.length} de ${caros.length}):`,
+        ...mostrados.map((f) => `  ${f.ruta}\n    ${lineaDeFicheroQueCuesta(f)}`),
+        '  (No dice que esté mal: dice que cuesta. El remedio lo eliges tú.)',
+    ];
+}
 /**
  * El ranking local, para `changebook friction`.
  *
@@ -906,11 +1008,23 @@ export function rankingDeFriccion(dir, home, tope = 10, ahoraMs = Date.now()) {
         modulo: null,
     }))
         .sort((a, b) => (b.fecha ?? '').localeCompare(a.fecha ?? ''));
+    // La OTRA señal, calculada UNA vez: 811 iteraciones contra 8 correcciones.
+    // Responde a otra pregunta —«¿qué fichero le cuesta al agente?»— y por eso
+    // puede tener algo que decir justo cuando la primera calla.
+    const caros = ficherosQueCuestan(ediciones).map((f) => ({
+        ...f,
+        ruta: path.relative(dir, f.ruta),
+    }));
+    const bloqueCaros = bloqueDeFicherosCaros(caros);
     // VACÍO ES UN DATO, y se dice. Un «no hay nada» a secas se lee igual que un
     // instrumento averiado —Invariante 17—, y aquí el caso normal es el vacío:
-    // medido el 24/08, 8 correcciones en 30 días.
+    // medido el 24/08, 8 correcciones en 30 días. Pero vacío de CORRECCIONES no
+    // es vacío del informe: si hay ficheros caros, el comando sí tiene qué contar.
     if (sucesos.length === 0) {
-        return (`Sin correcciones en los últimos ${VENTANA_DIAS} días.\n` +
+        const cabecera = `Sin correcciones en los últimos ${VENTANA_DIAS} días.`;
+        if (bloqueCaros.length > 0)
+            return [cabecera, ...bloqueCaros].join('\n');
+        return (`${cabecera}\n` +
             `(Vacío significa que no has tenido que rehacer trabajo del agente. ` +
             `Si el lector estuviera parado lo diría el diagnóstico de aquí arriba.)`);
     }
@@ -924,7 +1038,7 @@ export function rankingDeFriccion(dir, home, tope = 10, ahoraMs = Date.now()) {
     if (sucesos.length > mostrados.length) {
         lineas.push(`  … y ${sucesos.length - mostrados.length} más (sube el tope para verlas).`);
     }
-    return lineas.join('\n');
+    return [...lineas, ...bloqueCaros].join('\n');
 }
 // ── El punto ciego del shell, cerrado por el canal desacoplado ───────────────
 //

package/dist/index.js

@@ -8,6 +8,7 @@
  * The CLI subcommands feed and connect that memory without the VS Code
  * extension: login, analyze, sync, init, open.
  */
+import { auditarSetup, informeDeAuditoria } from "./audit.js";
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -70,6 +71,10 @@ Usage:
   changebook friction [dir] Where the agent's work gets redone in this repo,
                           read from the local Claude Code transcripts. Says
                           MUERTO if the repo has edits and it read nothing
+  changebook audit [dir]  Static check of your agent setup: rules in CLAUDE.md
+                          that cite files which no longer exist, how much
+                          context you pay per session, whether the hook is on.
+                          No account, no network, writes nothing
   changebook scan [dir] [--json|--card|--badge]
                           Coupling report for any repo, from its git history
                           alone. No account, no network, writes nothing — run it
@@ -363,6 +368,14 @@ async function main() {
             console.log(rankingDeFriccion(dir));
             return;
         }
+        case "audit": {
+            // Como `silence` y `scan`: sin credenciales, sin red, sin escribir. Todo
+            // lo que dice sale de ficheros del repo, así que contesta el mismo día en
+            // que alguien lo instala y no puede callarse por un fallo de red.
+            const dir = process.argv[3] ?? process.cwd();
+            console.log(informeDeAuditoria(auditarSetup(dir)));
+            return;
+        }
         case "silence": {
             // Sin credenciales y sin red: el contador es local por diseño (ver
             // tallyPath). Se lee del repo, no del servidor, y por eso contesta el

package/dist/sync.js

@@ -13,6 +13,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { aliasesFor, canonicalizeModuleRows, etiquetaPorSlug, projectIdOf, slugModule, } from './aliasDeModulo.js';
+import { consultaDeSucesos } from './friccionDelBrief.js';
 /**
  * Cuántas citas de historial sirve el bloque, según el plan (B5, opción A).
  *
@@ -103,7 +104,7 @@ const MAX_COUPLINGS = 5;
 //
 // Subir el techo alimenta al que se lo come. Adelgazada la cabecera a 271
 // chars, con 2.000 cabe mas contenido REAL que antes con 3.000.
-const SYNC_BUDGET_CHARS = 2_000;
+export const SYNC_BUDGET_CHARS = 2_000;
 // Co-change pair thresholds — same spirit as the web's signals: at least 3
 // shared analyses and a ≥60% rate before we call it a dependency.
 const MIN_PAIR_COUNT = 3;
@@ -155,7 +156,7 @@ export async function fetchBriefSection(db, targetDir) {
     }
     const projectId = projectIdOf(projectFilter);
     const since = new Date(Date.now() - ALERT_WINDOW_DAYS * 24 * 3600 * 1000).toISOString();
-    const [moduleRowsCrudas, changes, alertsCrudas, historialCrudo, pendingTasks, healthRows, { aliases },] = await Promise.all([
+    const [moduleRowsCrudas, changes, alertsCrudas, historialCrudo, pendingTasks, healthRows, { aliases }, friccionCruda,] = await Promise.all([
         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}` +
@@ -185,6 +186,12 @@ export async function fetchBriefSection(db, targetDir) {
             .catch(() => []),
         // Los alias entran en el MISMO Promise.all que ya se hacía: no cuesta ronda.
         aliasesFor(db, projectId),
+        // FRICCIÓN: dónde hubo que rehacer el trabajo. Es la misma consulta que
+        // sirve el brief —filtrada por veredicto en el servidor—, así que son 8
+        // filas en 30 días y no cuesta ronda tampoco.
+        db
+            .rest(consultaDeSucesos(projectFilter, Date.now()))
+            .catch(() => []),
     ]);
     // El punto de estrangulamiento del bloque: se canonicaliza AQUÍ, nada más
     // traer las filas, y todo lo que hay debajo (el mapa, `hechosCaros`,
@@ -196,6 +203,10 @@ export async function fetchBriefSection(db, targetDir) {
     const moduleRows = canonicalizeModuleRows(moduleRowsCrudas, aliases);
     const alerts = canonicalizeModuleRows(alertsCrudas, aliases);
     const historial = canonicalizeModuleRows(historialCrudo, aliases);
+    // LA CUARTA TABLA. La fricción también trae nombre de módulo, así que sin
+    // esto una fusión resolvería tres secciones y dejaría la fricción citando el
+    // nombre viejo — en la misma pantalla y sin que nada fallara.
+    const friccion = canonicalizeModuleRows(friccionCruda, aliases);
     const health = summarizeHealth(healthRows);
     // El commit de cada regresion, para poder citarlo. Una consulta mas, y solo
     // por los analisis que de verdad rompieron algo: es la diferencia entre «este
@@ -217,8 +228,8 @@ export async function fetchBriefSection(db, targetDir) {
                 commitPorAnalisis.set(f.id, f.commit_hash.slice(0, 7));
         }
     }
-    const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks, health.at_risk, historial, commitPorAnalisis, await citasSegunPlan(db));
-    return { section, projectId, projectResolved };
+    const { section, omitidas } = buildSectionConInforme(moduleRows, changes, alerts, projectName, pendingTasks, health.at_risk, historial, commitPorAnalisis, await citasSegunPlan(db), friccion);
+    return { section, projectId, projectResolved, omitidas };
 }
 /**
  * Lo que va a cambiar, en corto y para una persona.
@@ -259,12 +270,23 @@ export function resumenDelCambio(previo, siguiente, fichero) {
     return l.join('\n');
 }
 export async function syncContextFiles(db, targetDir, opts = {}) {
-    const { section, projectId, projectResolved } = await fetchBriefSection(db, targetDir);
+    const { section, projectId, projectResolved, omitidas } = await fetchBriefSection(db, targetDir);
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const file = path.join(targetDir, name);
         const updated = await upsertSection(file, section, opts);
         console.error(`${updated} ${name}`);
     }
+    // LO QUE NO CUPO, dicho a la persona. El bloque tiene presupuesto fijo —es
+    // coste que se paga en CADA sesión de CADA agente— y hasta hoy una sección
+    // que no cabía desaparecía sin dejar rastro en ningún sitio. Se dice aquí y
+    // no dentro del bloque: al agente no le falta (la cabecera ya le manda a
+    // `atlas_project_brief`, que no tiene tope), y meterlo dentro gastaría
+    // presupuesto de todas las sesiones para avisar de que falta presupuesto.
+    if (omitidas.length > 0) {
+        console.error(`⚠ No cupo todo en ${SYNC_BUDGET_CHARS} chars — pídelo con \`atlas_project_brief\`:`);
+        for (const o of omitidas)
+            console.error(`  · ${o}`);
+    }
     // El sync ES una consulta del atlas — la más apalancada: el mapa que
     // destila entra en CADA sesión de agente vía CLAUDE.md/AGENTS.md sin
     // pagar tool calls. Cuenta como lectura (best-effort).
@@ -361,11 +383,31 @@ export function hechosCaros(historial, commitPorAnalisis, tope = 6, maxCitas = C
         return `- **${modulo}**: ${n} regresi${n === 1 ? 'ón' : 'ones'}${cuando ? ` (${cuando})` : ''}`;
     });
 }
-export function buildSection(rows, changes, alerts = [], projectName, pendingTasks = [], atRiskHealth = [], historial = [], commitPorAnalisis = new Map(), 
+/**
+ * El bloque, y **qué se quedó fuera por tamaño**.
+ *
+ * POR QUÉ EXISTE ESTA SEGUNDA SALIDA, 24/08: el presupuesto es de suma cero y
+ * una sección entera que no cabe desaparecía **en silencio**. `recorta` avisa
+ * cuando corta una línea —lleva su elipsis desde el 04/08— pero perder la
+ * sección completa no dejaba rastro en ningún sitio.
+ *
+ * El informe NO va dentro del bloque. Al agente no le falta: la cabecera ya le
+ * dice que pida `atlas_project_brief`, que no tiene este tope. A quien le falta
+ * es a la PERSONA que corre `changebook sync`, y a ésa se le dice por stderr
+ * —una vez, cuando puede hacer algo— en vez de gastar presupuesto de cada
+ * sesión para siempre.
+ */
+export function buildSectionConInforme(rows, changes, alerts = [], projectName, pendingTasks = [], atRiskHealth = [], historial = [], commitPorAnalisis = new Map(), 
 // B5 · el que paga ve más historial de regresiones. Por defecto, el gratuito:
 // un fallo al leer el plan tiene que degradar HACIA el plan libre, nunca
 // regalar el de pago por un error de red.
-maxCitas = CITAS_GRATIS) {
+maxCitas = CITAS_GRATIS, 
+// Décimo posicional, y no me gusta: esta firma pide ya un objeto de opciones.
+// Se deja posicional a propósito porque cambiarla toca todos los sitios de
+// llamada y todos los contratos que la prueban, y eso no es parte de esta
+// pieza. Por defecto `[]`: un proyecto sin fricción —o una consulta que
+// falló— produce la sección vacía, que desaparece sola.
+friccion = []) {
     // Newest-first rows: the first occurrence of a module is its latest state.
     //
     // POR SLUG (03/08). Agrupaba por `row.module` crudo, asi que un modulo
@@ -462,11 +504,17 @@ maxCitas = CITAS_GRATIS) {
         '',
     ];
     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._',
-            END,
-        ].join('\n');
+        // Sin módulos no hay reparto, así que no hay nada omitido — y decir `[]` no
+        // es lo mismo que no decir nada: quien lea el informe sabe que aquí no se
+        // perdió nada por tamaño, sino que no había datos.
+        return {
+            section: [
+                ...head,
+                '_Aún no hay módulos analizados. Ejecuta un análisis desde la extensión o importa el historial de git._',
+                END,
+            ].join('\n'),
+            omitidas: [],
+        };
     }
     // 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
@@ -523,6 +571,41 @@ maxCitas = CITAS_GRATIS) {
             ...taskTitles.map((t) => `- ${sanitizeCell(recorta(t, 120))}`),
         ]
         : [];
+    // ── Fricción: dónde hubo que rehacer el trabajo ────────────────────────────
+    //
+    // POR QUÉ ENTRA, medido el 24/08 contra producción antes de escribirlo: de los
+    // 4 módulos con fricción en 30 días, **3 no aparecen en ninguna otra sección**
+    // (`Badge del README`, `Analítica de producto`, `Consolidación de módulos`).
+    // El único que se solapa es `Reportes de regresiones`, que ya sale en «costó
+    // caro» con 8. Si el solape hubiera sido total, esta sección sería decoración
+    // compitiendo por un presupuesto de suma cero contra señales validadas.
+    //
+    // TRES Y NO CINCO como el brief: esto entra en el contexto de CADA sesión, no
+    // se pide. El listado entero se sirve con `changebook friction` y por
+    // `atlas_project_brief`.
+    //
+    // ⚠ LO QUE ESTA SEÑAL NO ES: una regresión confirmada. Dice «aquí hubo que
+    // rehacer trabajo», con una precisión que NO está validada (n=15, un repo, y
+    // etiquetado por quien escribió el clasificador). Por eso su prioridad de
+    // presupuesto es 2 y no 1: cae antes que los avisos abiertos, la salud, los
+    // módulos críticos y el historial de regresiones, que sí están medidos.
+    //
+    // Y ESO TIENE UNA CONSECUENCIA MEDIDA, dicha aquí para que nadie la
+    // redescubra: en ESTE repo la sección NO SE PINTA. El bloque sale a 1.998 de
+    // 2.000 chars —saturado por tres módulos críticos y cinco entradas de
+    // historial— y la sección cuesta 271. Que pierda esa puja es lo correcto:
+    // enfrente hay regresiones confirmadas. En un repo con menos historial sí
+    // entra (comprobado con `buildSection` sobre un repo nuevo y sobre uno con
+    // una regresión: sale en los dos).
+    //
+    // ⚠ Y el hueco que esto destapa, PREVIO a esta sección y común a todas: una
+    // sección descartada por presupuesto es MUDA. `recorta` avisa cuando corta
+    // una línea, pero nada avisa cuando cae una sección entera. Mientras siga
+    // así, el listado completo se pide con `changebook friction` o por
+    // `atlas_project_brief`, que no tienen este tope.
+    const friccionLines = friccion
+        .slice(0, 3)
+        .map((f) => `- ${(f.occurred_at ?? '').slice(8, 10)}/${(f.occurred_at ?? '').slice(5, 7)} · \`${sanitizeCell(recorta(f.path, 80))}\`${f.module ? ` — **${sanitizeCell(f.module)}**` : ''}`);
     // 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.
@@ -578,6 +661,16 @@ maxCitas = CITAS_GRATIS) {
             title: '### Lo que ya costó caro aquí (revisa antes de tocarlo)',
             lines: hechosCaros(historial, commitPorAnalisis, 6, maxCitas),
         },
+        {
+            key: 'friccion',
+            priority: 2,
+            // EL TOTAL VA EN EL TÍTULO. Se enseñan 3 de las que haya, y un recorte
+            // mudo se lee como «esto es todo». Meterlo en el título cuesta CERO
+            // líneas de presupuesto, que es lo que impide que la honestidad compita
+            // con el contenido. El listado entero: `changebook friction`.
+            title: `### Dónde hubo que rehacer el trabajo (${friccionLines.length} de ${friccion.length}, últimos 30 días)`,
+            lines: friccionLines,
+        },
         // El mapa baja de 3 a 4, y no es una degradación caprichosa: `/doctor` de
         // Claude Code recorta por su cuenta «architecture overviews» de un
         // CLAUDE.md porque el agente los deriva del repo. Lo que no puede derivar
@@ -683,7 +776,28 @@ maxCitas = CITAS_GRATIS) {
     // se apartó del presupuesto arriba, así que entra siempre.
     lines.push('', FIRMA);
     lines.push(END);
-    return lines.join('\n');
+    // LO QUE NO CABIÓ. Una sección con líneas que se quedó con `count` 0 —o con
+    // menos líneas de las que traía— no entró entera. Se compara contra lo que la
+    // sección TENÍA, no contra un tope fijo: así también se ve la que entró a
+    // medias, que es igual de muda.
+    const omitidas = sections
+        .filter((x) => x.lines.length > 0)
+        .filter((x) => (includedCount.get(x.key) ?? 0) < x.lines.length)
+        .map((x) => {
+        const dentro = includedCount.get(x.key) ?? 0;
+        const nombre = x.title.replace(/^#+\s*/, '').replace(/\s*\(.*\)\s*$/, '');
+        return dentro === 0
+            ? `${nombre} (entera, ${x.lines.length} línea(s))`
+            : `${nombre} (${x.lines.length - dentro} de ${x.lines.length} línea(s))`;
+    });
+    return { section: lines.join('\n'), omitidas };
+}
+/**
+ * El bloque, a secas. La forma que usan los diez sitios de llamada que no
+ * necesitan el informe.
+ */
+export function buildSection(...args) {
+    return buildSectionConInforme(...args).section;
 }
 /**
  * Symmetric co-change pairs: modules that appear in the same analyses often

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "mcpName": "io.github.raulbr90/changebook",
   "description": "Your agent already broke this three times. ChangeBook tells it before the fourth. MCP server + CLI: the history of what broke in your repo, served to Claude Code, Cursor or Codex before they edit.",
   "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": "Your agent already broke this three times. ChangeBook tells it before the fourth.",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.8.0",
+      "version": "0.9.1",
       "transport": {
         "type": "stdio"
       }