changebook 0.4.4 → 0.4.5

package/dist/guard.js

@@ -181,7 +181,11 @@ 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",
-            ":!docs/",
+            // 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

package/dist/index.js

@@ -131,7 +131,23 @@ async function main() {
         case "analyze": {
             const db = new Supabase();
             requireCredentials(db);
-            await analyze(db, parseAnalyzeArgs(process.argv.slice(3)));
+            const options = parseAnalyzeArgs(process.argv.slice(3));
+            await analyze(db, options);
+            // El mapa de CLAUDE.md/AGENTS.md se regeneraba solo en `init`/`sync`,
+            // así que se congelaba el día que lo instalabas (estudio 2026-07-20: la
+            // causa nº 1 de que el agente desconfíe del atlas). analyze es el camino
+            // del hook post-commit, o sea CADA commit: refrescar aquí hace el mapa
+            // fresco por construcción, como watched_values. refreshOnly: jamás crea
+            // archivos ni resucita un bloque borrado. Best-effort: un sync caído no
+            // puede tumbar un análisis ya cobrado y registrado.
+            try {
+                await syncContextFiles(db, options.dir ?? process.cwd(), {
+                    refreshOnly: true,
+                });
+            }
+            catch (error) {
+                console.error(`Map refresh failed (analysis itself succeeded): ${error instanceof Error ? error.message : String(error)}`);
+            }
             return;
         }
         case "import": {

package/dist/sync.js

@@ -53,7 +53,7 @@ const MIN_PAIR_RATE = 0.6;
 // Same window/limit the web uses for the signals strip.
 const ALERT_WINDOW_DAYS = 14;
 const MAX_ALERTS = 3;
-export async function syncContextFiles(db, targetDir) {
+export async function syncContextFiles(db, targetDir, opts = {}) {
     const projectName = projectNameFor(targetDir);
     // Frontera por proyecto también aquí (QA 2026-07-18): sin filtro, una
     // cuenta con varios proyectos construiría el mapa de ESTE repo mezclando
@@ -103,7 +103,7 @@ export async function syncContextFiles(db, targetDir) {
     const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks);
     for (const name of ['CLAUDE.md', 'AGENTS.md']) {
         const file = path.join(targetDir, name);
-        const updated = await upsertSection(file, section);
+        const updated = await upsertSection(file, section, opts);
         console.error(`${updated} ${name}`);
     }
     // El sync ES una consulta del atlas — la más apalancada: el mapa que
@@ -159,15 +159,28 @@ export function buildSection(rows, changes, alerts = [], projectName, pendingTas
         //   · cargar las tools diferidas de UNA vez (benchmark 2026-07-20: 3 de 7
         //     llamadas del agente CON atlas eran ToolSearch cargando esquemas de
         //     uno en uno — cada una relee ~45k tokens de contexto)
-        'Memoria del proyecto en ChangeBook. Oriéntate con UNA llamada a `atlas_project_brief`. Antes de tocar un archivo: `atlas_file_context` con su ruta. Tras cada commit: `atlas_record_change` con el diff, `commit_hash`, `committed_at` y un `summary` tuyo (abarata el análisis; reenviar lo ya registrado es gratis). Tools diferidas: una sola llamada a ToolSearch con todas, nunca de una en una.',
+        //
+        // La FORMA de las instrucciones es disparador → tool, no prosa. Medido en
+        // la tanda 8808ebe (adopcion por celda, 2026-07-21): la adopcion sigue al
+        // matching LITERAL entre la tarea y el disparador escrito — "vas a editar
+        // el archivo" casaba con el disparador de file_context y adopto 5/5; el
+        // generico de orientacion 3/5; "investiga la funcion X", sin disparador,
+        // 0/5. Un agente no infiere que una tool aplica: reconoce su tarea en el
+        // texto o no la usa. Por eso cada tool lleva delante la formulacion de
+        // tarea que debe capturar, y el ToolSearch va con el select completo
+        // listo para copiar (cargar esquemas de uno en uno costaba 3 turnos).
+        // El disparador de symbol_lookup se RETIRÓ el 2026-07-21 con medición en
+        // la mano (tanda 957372c): llevó la adopción de t3 de 0/5 a 3/5, pero los
+        // adoptantes gastaron 607k tok/9 turnos vs 254k/4 del brazo sin atlas —
+        // la tool solo cubre definiciones y el agente acababa pagando atlas Y
+        // grep. Con repo local, grep gana; el sitio de symbol_lookup es el agente
+        // hospedado sin repo. Medir → actuar, aunque sea des-haciendo lo de ayer.
+        'Disparador → tool: orientarte → `atlas_project_brief` (`intent:"orient"`) · editar un archivo → `atlas_file_context` con su ruta · riesgos/acoplamientos → el brief. Tras cada commit: `atlas_record_change` (diff, hash, fecha, `summary` tuyo; reenviar es gratis).',
+        '',
+        'Tools diferidas, en UNA llamada: ToolSearch `select:mcp__changebook__atlas_project_brief,mcp__changebook__atlas_file_context,mcp__changebook__atlas_symbol_lookup`.',
         '',
-        ...(projectName
-            ? [
-                `Pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\`: el atlas es por proyecto y los datos de otros no son de esta sesión.`,
-                '',
-            ]
-            : []),
-        'Habla: anuncia en 2-3 líneas qué vas a hacer antes de atacar un encargo, y cuéntale al usuario cualquier riesgo que el atlas te enseñe — él no ve esos avisos.',
+        // Proyecto + conducta en UNA línea: cada char de cabecera expulsa mapa.
+        `${projectName ? `Pasa SIEMPRE \`project: "${sanitizeCell(projectName)}"\`. ` : ''}Anuncia antes de atacar un encargo, y DILE al usuario los riesgos que el atlas te enseñe — él no los ve.`,
         '',
     ];
     if (modules.length === 0) {
@@ -345,7 +358,7 @@ export function coChangePairs(rows) {
     return pairs.sort((x, y) => y.rate - x.rate).slice(0, MAX_COUPLINGS);
 }
 /** Exported for tests. */
-export async function upsertSection(file, section) {
+export async function upsertSection(file, section, opts = {}) {
     let content = null;
     try {
         content = await readFile(file, 'utf8');
@@ -354,6 +367,8 @@ export async function upsertSection(file, section) {
         content = null;
     }
     if (content === null) {
+        if (opts.refreshOnly)
+            return 'skipped';
         await writeFile(file, section + '\n');
         return 'created';
     }
@@ -362,6 +377,14 @@ export async function upsertSection(file, section) {
     // nuevo — si no, quedarían dos mapas (uno obsoleto) en el mismo archivo.
     const LEGACY_START = '<!-- appatlas:start -->';
     const LEGACY_END = '<!-- appatlas:end -->';
+    // Un archivo sin NINGÚN bloque (ni actual ni legado) en modo refreshOnly es
+    // una decisión del dueño, no un hueco que rellenar: borró el mapa y el
+    // refresco automático no puede volver a pegárselo en cada commit.
+    if (opts.refreshOnly &&
+        !(content.includes(START) && content.includes(END)) &&
+        !(content.includes(LEGACY_START) && content.includes(LEGACY_END))) {
+        return 'skipped';
+    }
     const legacyStart = content.indexOf(LEGACY_START);
     const legacyEnd = content.indexOf(LEGACY_END);
     if (legacyStart !== -1 && legacyEnd !== -1 && legacyEnd > legacyStart) {

package/dist/tools.js

@@ -121,6 +121,23 @@ export function filesUnionByChange(rows, cap = FILES_CAP) {
     }
     return out;
 }
+// Espejo de supabase/functions/mcp/scope.ts (paridad en
+// test/espejoDeCommits.test.ts): aliases post-squash del mismo contenido,
+// para que el hash citado exista en el main del consultante.
+export function commitAliasesShort(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((h) => typeof h === "string" && /^[0-9a-f]{7,64}$/i.test(h))
+        .map((h) => h.slice(0, 7));
+}
+export function commitLabel(hash, aliasesRaw) {
+    const corto = hash?.slice(0, 7) ?? null;
+    if (!corto)
+        return null;
+    const aliases = commitAliasesShort(aliasesRaw);
+    return aliases.length > 0 ? `${corto} (=${aliases.join(",")})` : corto;
+}
 // Consultation metering (never billing): each successful read leaves a row in
 // atlas_reads so the web can show "your agent consulted the atlas N times".
 // Best-effort and non-blocking — metering must never break or slow a read.
@@ -294,7 +311,7 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
         try {
             const t0 = Date.now();
             const pf = await db.projectFilterFor(project);
-            let query = `changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash` +
+            let query = `changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash,hash_aliases` +
                 `&order=created_at.desc&limit=${limit}&offset=${offset}` +
                 pf;
             if (search) {
@@ -332,6 +349,9 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                 ...(include_tech || search ? { summary_tech: r.summary_tech ?? null } : {}),
                 diff_chars: r.diff_character_count ?? null,
                 commit: r.commit_hash?.slice(0, 7) ?? null,
+                // Post-squash: el mismo cambio bajo otro hash (rama vs main). Si
+                // `commit` no existe en tu repo, uno de estos sí.
+                commit_aliases: commitAliasesShort(r.hash_aliases),
                 files: filesByChange.get(r.id)?.files ?? [],
                 files_more: filesByChange.get(r.id)?.more ?? 0,
                 modules: (modulesByChange.get(r.id) ?? []).map((m) => ({
@@ -350,7 +370,7 @@ Don't use for per-module deep dives — use atlas_module_detail for that.`,
                 const mods = c.modules
                     .map((m) => m.module + (m.risk ? ` [${m.risk}]` : ""))
                     .join(", ");
-                lines.push(`## ${c.date}${c.commit ? ` · ${c.commit}` : ""} — ${c.business_impact}`);
+                lines.push(`## ${c.date}${c.commit ? ` · ${c.commit}${c.commit_aliases.length > 0 ? ` (=${c.commit_aliases.join(",")})` : ""}` : ""} — ${c.business_impact}`);
                 if ((include_tech || search) && c.summary_tech)
                     lines.push(`- Tech: ${c.summary_tech}`);
                 if (mods)
@@ -499,7 +519,7 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
                 };
             }
             const ids = [...new Set(rows.map((r) => r.changelog_id))].join(",");
-            const logs = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash&id=in.(${ids})`);
+            const logs = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count,commit_hash,hash_aliases&id=in.(${ids})`);
             const logById = new Map(logs.map((l) => [l.id, l]));
             const changes = rows.map((r) => {
                 let excerpt = null;
@@ -519,6 +539,7 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
                     // El commit del que salió cada entrada: la nota deja de flotar en
                     // el tiempo y se puede cuadrar contra git.
                     commit: logById.get(r.changelog_id)?.commit_hash?.slice(0, 7) ?? null,
+                    commit_aliases: commitAliasesShort(logById.get(r.changelog_id)?.hash_aliases),
                     risk: r.risk,
                     note: r.note,
                     tech: r.tech,
@@ -530,12 +551,24 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
             });
             // Ancla temporal de la respuesta entera: el commit más nuevo servido,
             // comparado con el HEAD del árbol — solo si este árbol ES el proyecto
-            // (misma puerta que la refutación de alertas).
-            const ancla = cwdEsElProyecto(project)
-                ? await derivaContraHead(process.cwd(), rows
-                    .map((r) => logById.get(r.changelog_id)?.commit_hash)
-                    .find(Boolean) ?? null)
-                : null;
+            // (misma puerta que la refutación de alertas). Post-squash, el hash
+            // primario puede no existir en este árbol: se prueban sus aliases
+            // antes de rendirse.
+            let ancla = null;
+            if (cwdEsElProyecto(project)) {
+                const log = rows
+                    .map((r) => logById.get(r.changelog_id))
+                    .find((l) => l?.commit_hash);
+                const candidatos = [
+                    log?.commit_hash ?? null,
+                    ...commitAliasesShort(log?.hash_aliases),
+                ];
+                for (const c of candidatos) {
+                    ancla = await derivaContraHead(process.cwd(), c);
+                    if (ancla)
+                        break;
+                }
+            }
             const latest = rows[0];
             const output = {
                 module,
@@ -553,7 +586,7 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
                 lines.push(ancla);
             lines.push("");
             for (const c of changes) {
-                lines.push(`## ${c.date}${c.commit ? ` · commit ${c.commit}` : ""}${c.risk ? ` — risk: ${c.risk}` : ""}`);
+                lines.push(`## ${c.date}${c.commit ? ` · commit ${c.commit}${c.commit_aliases.length > 0 ? ` (=${c.commit_aliases.join(",")})` : ""}` : ""}${c.risk ? ` — risk: ${c.risk}` : ""}`);
                 if (c.business_impact)
                     lines.push(`- Impact: ${c.business_impact}`);
                 if (c.note)
@@ -678,10 +711,20 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             let ancla = null;
             if (cwdEsElProyecto(project)) {
                 const ultimo = await db
-                    .rest(`changelog?select=commit_hash&commit_hash=not.is.null&order=created_at.desc&limit=1` +
+                    .rest(`changelog?select=commit_hash,hash_aliases&commit_hash=not.is.null&order=created_at.desc&limit=1` +
                     pf)
                     .catch(() => []);
-                ancla = await derivaContraHead(process.cwd(), ultimo[0]?.commit_hash ?? null);
+                // Post-squash: si el hash primario no existe en este árbol (era el
+                // de la rama), sus aliases sí pueden — probar antes de rendirse.
+                const candidatos = [
+                    ultimo[0]?.commit_hash ?? null,
+                    ...commitAliasesShort(ultimo[0]?.hash_aliases),
+                ];
+                for (const c of candidatos) {
+                    ancla = await derivaContraHead(process.cwd(), c);
+                    if (ancla)
+                        break;
+                }
             }
             const lines = [`# File context (${paths.length} file(s))`];
             if (ancla)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "mcpName": "io.github.raulbr90/changebook",
   "description": "ChangeBook for coding agents: MCP server (product memory for Claude Code/Codex) + CLI to sign in, analyze changes and sync the product map.",
   "type": "module",
@@ -29,7 +29,7 @@
   ],
   "scripts": {
     "start": "node dist/index.js",
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/index.js",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.raulbr90/changebook",
   "description": "Query your product's living memory: module map + analyzed change history. Read-only MCP tools.",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "websiteUrl": "https://changebook.dev",
   "remotes": [
     {
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "changebook",
-      "version": "0.4.4",
+      "version": "0.4.5",
       "transport": {
         "type": "stdio"
       }