changebook 0.5.0 → 0.7.0

package/dist/sync.js

@@ -12,6 +12,28 @@
  */
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { aliasesFor, canonicalizeModuleRows, etiquetaPorSlug, projectIdOf, slugModule, } from './aliasDeModulo.js';
+/**
+ * Cuántas citas de historial sirve el bloque, según el plan (B5, opción A).
+ *
+ * FALLA HACIA EL PLAN GRATUITO, SIEMPRE. Un error de red, una tabla que no
+ * responde o una fila que no existe devuelven el gratuito. Al revés —regalar el
+ * de pago cuando algo falla— es un muro que se cae solo el día que hay una
+ * incidencia, y nadie se entera de que se cayó.
+ *
+ * `user_plans` está acotada por RLS al usuario de la sesión, así que no hace
+ * falta filtrar por id: si hay fila, es la suya.
+ */
+export async function citasSegunPlan(db) {
+    try {
+        const filas = await db.rest('user_plans?select=plan&limit=1');
+        const plan = (filas[0]?.plan ?? 'free').trim().toLowerCase();
+        return plan && plan !== 'free' ? CITAS_PRO : CITAS_GRATIS;
+    }
+    catch {
+        return CITAS_GRATIS;
+    }
+}
 /** The project identity of the synced repo (same rule as analyze/guard). */
 function projectNameFor(targetDir) {
     return (process.env.CHANGEBOOK_PROJECT?.trim() ||
@@ -19,6 +41,11 @@ function projectNameFor(targetDir) {
 }
 const START = '<!-- changebook:start -->';
 const END = '<!-- changebook:end -->';
+// La firma viaja con cada clone y cada PR: el bloque vive en el CLAUDE.md del
+// usuario y todo colaborador (o su agente) que lo abra la ve. Una línea, sin
+// emoji, sin mayúsculas, sin enlace markdown. Se RESERVA del presupuesto antes
+// de repartirlo, así que si algo se recorta es el contenido, nunca la firma.
+const FIRMA = '_Generado por ChangeBook · changebook.app_';
 // DB text (notes, alert bodies, business impact) is AI-written and gets embedded
 // between the markers that upsertSection splices on. If any of it contained a
 // literal marker, the next sync would splice at the wrong offset and corrupt the
@@ -95,9 +122,9 @@ export async function fetchBriefSection(db, targetDir) {
         projectFilter = '&project_id=eq.00000000-0000-0000-0000-000000000000';
         projectResolved = false;
     }
-    const projectId = /project_id=eq\.([0-9a-f-]+)/.exec(projectFilter)?.[1] ?? null;
+    const projectId = projectIdOf(projectFilter);
     const since = new Date(Date.now() - ALERT_WINDOW_DAYS * 24 * 3600 * 1000).toISOString();
-    const [moduleRows, changes, alerts, pendingTasks, healthRows] = await Promise.all([
+    const [moduleRowsCrudas, changes, alertsCrudas, historialCrudo, pendingTasks, healthRows, { aliases },] = 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}` +
@@ -106,6 +133,12 @@ export async function fetchBriefSection(db, targetDir) {
             .rest(`regression_alerts?select=module,plain,created_at&created_at=gte.${since}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}` +
             projectFilter)
             .catch(() => []),
+        // HISTORIA de regresiones: todas, sin ventana y sin filtrar por abiertas.
+        // Es lo que sustituye al mapa de modulos en el bloque — ver `hechosCaros`.
+        db
+            .rest('regression_alerts?select=module,plain,resolution,created_at,changelog_id&order=created_at.desc&limit=500' +
+            projectFilter)
+            .catch(() => []),
         projectResolved && projectId
             ? db
                 .callRpc('list_agent_tasks', {
@@ -119,11 +152,81 @@ export async function fetchBriefSection(db, targetDir) {
             .rest('project_checks?select=check_id,status,evidence,updated_at&order=updated_at.desc&limit=8' +
             projectFilter)
             .catch(() => []),
+        // Los alias entran en el MISMO Promise.all que ya se hacía: no cuesta ronda.
+        aliasesFor(db, projectId),
     ]);
+    // El punto de estrangulamiento del bloque: se canonicaliza AQUÍ, nada más
+    // traer las filas, y todo lo que hay debajo (el mapa, `hechosCaros`,
+    // `coChangePairs`, los avisos) sigue siendo puro y agrupa por nombre sin
+    // enterarse. Las TRES tablas, no solo el mapa: el bloque de CLAUDE.md cuenta
+    // regresiones por módulo, así que una fusión que resolviera el mapa y no el
+    // historial diría «3 regresiones» de un módulo y las listaría bajo otro
+    // nombre, en la misma pantalla.
+    const moduleRows = canonicalizeModuleRows(moduleRowsCrudas, aliases);
+    const alerts = canonicalizeModuleRows(alertsCrudas, aliases);
+    const historial = canonicalizeModuleRows(historialCrudo, aliases);
     const health = summarizeHealth(healthRows);
-    const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks, health.at_risk);
+    // 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
+    // modulo ha roto 3 veces» y «este modulo ha roto 3 veces, aqui, aqui y aqui».
+    // Sin el hash, la frase es una etiqueta; con el, es algo que se puede ir a
+    // mirar. El sync corre UNA vez por sesion, asi que la ronda extra se paga una
+    // vez y no por edicion.
+    const idsDeRegresion = [
+        ...new Set(historial.map((h) => h.changelog_id).filter((x) => Boolean(x))),
+    ].slice(0, 60);
+    const commitPorAnalisis = new Map();
+    if (idsDeRegresion.length > 0) {
+        const filas = await db
+            .rest(`changelog?select=id,commit_hash&id=in.(${idsDeRegresion.join(',')})` +
+            projectFilter)
+            .catch(() => []);
+        for (const f of filas) {
+            if (f.commit_hash)
+                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 };
 }
+/**
+ * Lo que va a cambiar, en corto y para una persona.
+ *
+ * Pura a propósito: la decisión de qué enseñar se prueba sin terminal y sin
+ * escribir en disco. El diff entero se deja para quien lo pida — el objetivo de
+ * B7 no es volcar un diff, es que quien instala vea que su fichero se respeta.
+ */
+export function resumenDelCambio(previo, siguiente, fichero) {
+    const nombre = fichero.split('/').pop() ?? fichero;
+    if (previo === null) {
+        return `Voy a crear ${nombre} (${siguiente.split('\n').length} líneas).`;
+    }
+    const antes = previo.split('\n');
+    const despues = siguiente.split('\n');
+    const comunes = new Set(antes);
+    const anadidas = despues.filter((l) => l.trim() && !comunes.has(l));
+    const vivas = new Set(despues);
+    const quitadas = antes.filter((l) => l.trim() && !vivas.has(l));
+    // LO QUE MÁS IMPORTA DE ESTE MENSAJE es la primera línea: que el fichero de
+    // quien lo lee NO se toca fuera del bloque. Es lo que el producto ya hacía
+    // bien y no contaba — y la desconfianza no viene de lo que haces, viene de lo
+    // que no se ve.
+    const fuera = antes.filter((l) => vivas.has(l)).length;
+    const l = [
+        `He encontrado tu ${nombre} (${antes.length} líneas). Conservo ${fuera} tal cual`,
+        `y solo reescribo el bloque entre los marcadores de ChangeBook:`,
+        '',
+    ];
+    for (const linea of anadidas.slice(0, 4))
+        l.push(`  + ${linea.slice(0, 90)}`);
+    if (anadidas.length > 4)
+        l.push(`  + … y ${anadidas.length - 4} líneas más`);
+    for (const linea of quitadas.slice(0, 2))
+        l.push(`  - ${linea.slice(0, 90)}`);
+    if (quitadas.length > 2)
+        l.push(`  - … y ${quitadas.length - 2} líneas más`);
+    return l.join('\n');
+}
 export async function syncContextFiles(db, targetDir, opts = {}) {
     const { section, projectId, projectResolved } = await fetchBriefSection(db, targetDir);
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
@@ -146,15 +249,110 @@ export async function syncContextFiles(db, targetDir, opts = {}) {
     }
 }
 /** Exported for tests. */
-export function buildSection(rows, changes, alerts = [], projectName, pendingTasks = [], atRiskHealth = []) {
+/**
+ * LO QUE YA COSTO CARO AQUI: modulos que han roto algo, con fecha y commit.
+ *
+ * ── POR QUE ESTO Y NO EL MAPA DE MODULOS ────────────────────────────────────
+ *
+ * La documentacion de Claude Code lo dice de su propio `/doctor`: recorta del
+ * CLAUDE.md «directory layouts, dependency lists, and architecture overviews»
+ * y conserva «pitfalls, rationale, and conventions that differ from tool
+ * defaults». La lista de modulos con su dominio es DERIVABLE: el agente la saca
+ * leyendo el repo, y la herramienta la recorta por su cuenta.
+ *
+ * Esto no. Que un modulo haya roto tres veces sale del HISTORIAL, no del
+ * codigo: ni un grep ni un glob pueden encontrarlo, y es exactamente la
+ * categoria que /doctor conserva.
+ *
+ * ── DOS DECISIONES QUE PARECEN DETALLES ─────────────────────────────────────
+ *
+ * FECHA Y HASH POR ENTRADA, NUNCA EN LA CABECERA. Una fecha en la cabecera
+ * cambiaria a diario e invalidaria el prefijo de prompt-cache de TODO el
+ * fichero en cada sesion. Por entrada no: una linea que no cambia no invalida
+ * nada, y `upsertSection` sigue devolviendo `unchanged` cuando no ha pasado
+ * nada, asi que hechos con fecha no producen churn diario en `git status`.
+ *
+ * SE CUENTAN PROBLEMAS DISTINTOS, no filas. Mismo criterio que
+ * `computeRecidivism`: la misma regresion re-levantada tres veces es UNA, y
+ * contarla tres veces convertiria el churn del generador en falsa gravedad.
+ */
+/**
+ * Citas por módulo en el plan gratuito. La línea es una pista para ir a mirar,
+ * no un informe.
+ */
+export const CITAS_GRATIS = 3;
+/**
+ * Y en el de pago (B5, opción A: nadie pierde nada, el que paga gana).
+ *
+ * ACOTADO, NO ILIMITADO, y el motivo está escrito dos veces en este fichero: el
+ * bloque viaja en CADA petición de CADA sesión del usuario, así que es coste
+ * FIJO, y `SYNC_BUDGET_CHARS` existe porque ya se intentó subir el techo en vez
+ * de adelgazar el contenido y NO funcionó — la sección «Módulos» se quedó fuera
+ * igual. «El que paga lo ve todo» sonaría mejor y le costaría tokens en cada
+ * turno para leer diez fechas que no va a mirar.
+ */
+export const CITAS_PRO = 8;
+export function hechosCaros(historial, commitPorAnalisis, tope = 6, maxCitas = CITAS_GRATIS) {
+    const porModulo = new Map();
+    for (const h of historial) {
+        // SOLO LAS CONFIRMADAS, igual que `computeRecidivism`. Esta es la sección
+        // que el dueño ve en su CLAUDE.md, así que dejarla contando avisos mientras
+        // la tool cuenta regresiones daría DOS cifras distintas para la misma
+        // pregunta — que es peor que una cifra mala.
+        if ((h.resolution ?? '').trim().toLowerCase() !== 'fixed')
+            continue;
+        const modulo = (h.module ?? '').trim();
+        const texto = (h.plain ?? '').trim();
+        if (!modulo || !texto)
+            continue;
+        const entrada = porModulo.get(modulo) ?? { textos: new Set(), citas: [] };
+        if (!entrada.textos.has(texto)) {
+            entrada.textos.add(texto);
+            entrada.citas.push({
+                fecha: h.created_at.slice(5, 10).split('-').reverse().join('/'),
+                commit: h.changelog_id
+                    ? (commitPorAnalisis.get(h.changelog_id) ?? null)
+                    : null,
+            });
+        }
+        porModulo.set(modulo, entrada);
+    }
+    return [...porModulo.entries()]
+        .sort((a, b) => b[1].textos.size - a[1].textos.size || a[0].localeCompare(b[0]))
+        .slice(0, tope)
+        .map(([modulo, { textos, citas }]) => {
+        const n = textos.size;
+        // Cuántas citas caben: ver CITAS_GRATIS / CITAS_PRO.
+        const cuando = citas
+            .slice(0, maxCitas)
+            .map((c) => (c.commit ? `${c.fecha} \`${c.commit}\`` : c.fecha))
+            .join(', ');
+        return `- **${modulo}**: ${n} regresi${n === 1 ? 'ón' : 'ones'}${cuando ? ` (${cuando})` : ''}`;
+    });
+}
+export function buildSection(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) {
     // 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
+    // escrito de dos maneras salia DOS VECES en el bloque que se escribe en
+    // CLAUDE.md/AGENTS.md — y ademas gastaba dos de las MAX_MODULES plazas, o
+    // sea que expulsaba a un modulo real. Este fichero ya agrupaba por slug en
+    // otros dos sitios; esta agregacion se habia quedado fuera, que es la forma
+    // exacta de la invariante 16: media normalizacion se lee igual que una
+    // entera.
+    const etiqueta = etiquetaPorSlug(rows.map((r) => r.module ?? ''));
     const seen = new Map();
     for (const row of rows) {
-        const existing = seen.get(row.module);
+        const clave = slugModule((row.module ?? '').trim());
+        const existing = seen.get(clave);
         if (existing)
             existing.count += 1;
         else
-            seen.set(row.module, { ...row, count: 1 });
+            seen.set(clave, { ...row, module: etiqueta.get(clave) ?? row.module, count: 1 });
     }
     const modules = [...seen.values()].slice(0, MAX_MODULES);
     const head = [
@@ -208,9 +406,18 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         // tokens y CERO llamadas al atlas. «editar un archivo» no casaba con cómo
         // habla quien programa con un agente. Quien no pregunta nada no reconoce un
         // disparador abstracto: hay que nombrar sus verbos.
-        'Disparador → tool: orientarte → `atlas_project_brief` (`intent:"orient"`) · antes de editar/cambiar/arreglar/refactorizar un archivo o función → `atlas_file_context` (dice QUIÉN DEPENDE de eso) · riesgos/acoplamientos → el brief. Tras cada commit: `atlas_record_change` (diff, hash, fecha, `summary` tuyo; reenviar es gratis).',
+        //
+        // Y el 2026-08-02 se vio la MITAD QUE FALTABA. Habia disparador para
+        // registrar cambios y ninguno para juzgar avisos, y el resultado esta
+        // medido: de 119 alertas, 79 sin motivo ninguno. No es que nadie las
+        // mirara — mirar y APUNTAR son dos actos distintos y solo uno era gratis.
+        // Ese dia yo mismo verifique un aviso, lo arregle y no lo cerre hasta que
+        // el dueño me pregunto por que seguia abierto. `atlas_resolve_alert` entra
+        // con sus verbos («comprobar», «arreglar») por la misma ley de arriba, y
+        // pagando su precio: cada char aqui le quita sitio al mapa.
+        'Disparador → tool: orientarte → `atlas_project_brief` (`intent:"orient"`) · antes de editar/cambiar/arreglar/refactorizar un archivo o función → `atlas_file_context` (dice QUIÉN DEPENDE de eso) · riesgos/acoplamientos → el brief. Tras cada commit: `atlas_record_change` (diff, hash, fecha, `summary` tuyo; reenviar es gratis). Al comprobar o arreglar un aviso: `atlas_resolve_alert` (si era falso, `verdict:"dismissed"`).',
         '',
-        'Tools diferidas, en UNA llamada: ToolSearch `select:mcp__changebook__atlas_project_brief,mcp__changebook__atlas_file_context,mcp__changebook__atlas_symbol_lookup`.',
+        'Tools diferidas, en UNA llamada: ToolSearch `select:mcp__changebook__atlas_project_brief,mcp__changebook__atlas_file_context`.',
         '',
         // Proyecto + conducta en UNA línea: cada char de cabecera expulsa mapa.
         //
@@ -334,7 +541,18 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
             title: '### Encargos pendientes del dueño (proponte atacarlos)',
             lines: taskLines,
         },
-        { key: 'modules', priority: 3, title: '### Módulos', lines: moduleLines },
+        {
+            key: 'costoso',
+            priority: 1,
+            title: '### Lo que ya costó caro aquí (revisa antes de tocarlo)',
+            lines: hechosCaros(historial, commitPorAnalisis, 6, maxCitas),
+        },
+        // 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
+        // es qué ha roto antes. Se conserva la sección —quitarla del todo cambia
+        // más de lo necesario— pero deja de competir con los hechos.
+        { key: 'modules', priority: 4, title: '### Módulos', lines: moduleLines },
         {
             key: 'changes',
             priority: 5,
@@ -342,7 +560,10 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
             lines: changeLines,
         },
     ];
-    let budget = SYNC_BUDGET_CHARS - head.join('\n').length - END.length;
+    // La firma se aparta del fondo ANTES del reparto (línea en blanco separadora
+    // + la propia línea): lo que compita por presupuesto lo hace sobre lo que
+    // sobra, de modo que el recorte cae siempre en el contenido, nunca en la firma.
+    let budget = SYNC_BUDGET_CHARS - head.join('\n').length - END.length - (FIRMA.length + 2);
     // ── El suelo del mapa ──────────────────────────────────────────────────────
     //
     // El presupuesto es de suma cero, así que poner el riesgo primero se lo come.
@@ -359,8 +580,17 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
     // 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');
+    // EL SUELO CAMBIA DE DUEÑO. Lo tenía el mapa porque el estudio de 76 agentes
+    // del 2026-07-20 concluyó que un mapa expulsado era «la causa nº 1 de que el
+    // agente ignore o desconfíe del atlas». Sigue siendo cierto, pero el mapa ya
+    // no es lo irreemplazable: el agente lo deriva leyendo el repo, y la propia
+    // herramienta lo recorta. Lo que nadie puede derivar es qué rompió antes, así
+    // que el suelo protege ahora eso.
+    //
+    // Y baja de 6 líneas a 3: son entradas mucho más densas —un módulo, un
+    // número y hasta tres commits— así que tres ya dicen dónde pisar con cuidado.
+    const MIN_LINEAS_MAPA = 3;
+    const mapa = sections.find((x) => x.key === 'costoso');
     let reservaMapa = 0;
     if (mapa && mapa.lines.length > 0) {
         reservaMapa = mapa.title.length + 2;
@@ -380,7 +610,7 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         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;
+        const disponible = s.key === 'costoso' ? 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) {
@@ -391,8 +621,14 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         }
         if (count > 0) {
             includedCount.set(s.key, count);
-            if (s.key === 'modules') {
+            if (s.key === 'costoso') {
                 // Lo que consumió por encima de su reserva sale del fondo común.
+                //
+                // La clave tiene que ser la MISMA que la de arriba: al mover el suelo
+                // del mapa a los hechos se me quedó aquí `modules`, así que la sección
+                // nueva gastaba la reserva Y descontaba su coste entero del fondo —
+                // doble gasto— y el mapa se llevaba luego una reserva ya usada. El
+                // bloque no reventaba el techo por casualidad, no por diseño.
                 budget -= Math.max(0, cost - reservaMapa);
                 reservaMapa = 0;
             }
@@ -412,6 +648,9 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         lines.push(s.title, ...s.lines.slice(0, count));
         first = false;
     }
+    // La firma, al final del bloque y antes del marcador de cierre. Su hueco ya
+    // se apartó del presupuesto arriba, así que entra siempre.
+    lines.push('', FIRMA);
     lines.push(END);
     return lines.join('\n');
 }
@@ -459,11 +698,17 @@ const ES_FICHERO_DE_PRUEBAS = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[A
  */
 const RATIO_MODULO_DE_PRUEBAS = 0.8;
 export function modulosDePruebas(rows) {
+    // Por slug: si el módulo va partido en dos etiquetas, cada mitad se evaluaría
+    // contra el umbral por su cuenta y una podría pasar por «de pruebas» mientras
+    // la otra no. El Set devuelto lleva la etiqueta representante, que es la
+    // misma que usa coChangePairs, para que el `dePruebas.has(...)` de allí case.
+    const etiqueta = etiquetaPorSlug(rows.map((r) => r.module ?? ''));
     const porModulo = new Map();
     for (const r of rows) {
-        const label = (r.module ?? '').trim();
-        if (!label || !Array.isArray(r.files))
+        const crudo = (r.module ?? '').trim();
+        if (!crudo || !Array.isArray(r.files))
             continue;
+        const label = etiqueta.get(slugModule(crudo)) ?? crudo;
         const set = porModulo.get(label) ?? new Set();
         for (const f of r.files) {
             if (typeof f === 'string' && f.trim())
@@ -485,11 +730,19 @@ export function modulosDePruebas(rows) {
     return fuera;
 }
 export function coChangePairs(rows) {
+    // LA ARISTA QUE FALTA NO LA VE NADIE. Un módulo partido en dos etiquetas
+    // reparte sus apariciones entre las dos mitades: con 13+1 se pierde poco,
+    // pero con un reparto parejo —8 y 6 contra un umbral de 10— las DOS mitades
+    // caen por debajo de MIN_PAIR_COUNT y el acoplamiento real desaparece del
+    // grafo. El fantasma del brief se ve y se denuncia; esto no lo nota nadie
+    // nunca, y es justo lo que el producto promete enseñar.
+    const etiqueta = etiquetaPorSlug(rows.map((r) => r.module ?? ''));
     const byAnalysis = new Map();
     for (const r of rows) {
-        const label = (r.module ?? '').trim();
-        if (!label)
+        const crudo = (r.module ?? '').trim();
+        if (!crudo)
             continue;
+        const label = etiqueta.get(slugModule(crudo)) ?? crudo;
         let set = byAnalysis.get(r.changelog_id);
         if (!set) {
             set = new Set();
@@ -535,11 +788,25 @@ export async function upsertSection(file, section, opts = {}) {
     catch {
         content = null;
     }
+    /** Escribe, salvo que quien mira diga que no. */
+    const escribir = async (siguiente, resultado) => {
+        if (opts.confirmar) {
+            const ok = await opts.confirmar({
+                fichero: file,
+                previo: content,
+                siguiente,
+                resumen: resumenDelCambio(content, siguiente, file),
+            });
+            if (!ok)
+                return 'skipped';
+        }
+        await writeFile(file, siguiente);
+        return resultado;
+    };
     if (content === null) {
         if (opts.refreshOnly)
             return 'skipped';
-        await writeFile(file, section + '\n');
-        return 'created';
+        return escribir(section + '\n', 'created');
     }
     // Migración del renombrado (AppAtlas → ChangeBook): si el archivo aún tiene
     // el bloque con los marcadores antiguos, elimínalo antes de upsertar el
@@ -567,13 +834,13 @@ export async function upsertSection(file, section, opts = {}) {
         const next = content.slice(0, start) + section + content.slice(end + END.length);
         // Idempotente: si el mapa no cambió, no tocar el archivo — reescribirlo
         // actualizaría el mtime, ensuciaría git status y podría invalidar cachés.
+        // Y NO SE PREGUNTA cuando no hay nada que cambiar: una pregunta cuya única
+        // respuesta útil es «sí, no hagas nada» es ruido que enseña a decir que sí.
         if (next === content)
             return 'unchanged';
-        await writeFile(file, next);
-        return 'updated';
+        return escribir(next, 'updated');
     }
     const separator = content.endsWith('\n') ? '\n' : '\n\n';
-    await writeFile(file, content + separator + section + '\n');
-    return 'appended';
+    return escribir(content + separator + section + '\n', 'appended');
 }
 //# sourceMappingURL=sync.js.map