changebook 0.4.4 → 0.4.6

package/dist/context.js

@@ -0,0 +1,162 @@
+/**
+ * `changebook context [dir]` — prints the FRESH atlas brief to stdout as a
+ * Claude Code SessionStart hook payload
+ * (`hookSpecificOutput.additionalContext`). Wired by `changebook init` into
+ * `.claude/settings.json` (with the user's consent), it pushes the map into
+ * the agent's context at turn 0 of EVERY session — headless included — so the
+ * brief stops being a tool the agent must remember to call and stops being a
+ * file that can go stale between commits: it is generated on the spot, per
+ * session.
+ *
+ * FAIL-OPEN, ABSOLUTE. This runs on the critical path of opening a session.
+ * Every failure mode — logged out, offline, no project, or merely slow — must
+ * print NOTHING and exit 0. A broken or slow atlas can never block or delay a
+ * user's session start. The whole body races a short timeout; on timeout or
+ * any throw, we emit nothing.
+ */
+import * as fs from "node:fs";
+import path from "node:path";
+import { fetchBriefSection } from "./sync.js";
+import { commitAliasesShort, derivaContraHead } from "./tools.js";
+/** Hard ceiling on the critical path: past this, emit nothing and move on. */
+const CONTEXT_TIMEOUT_MS = 2_000;
+async function buildPayload(db, dir) {
+    // Logged out → silent no-op. A fresh clone with the hook installed but no
+    // session must open exactly as fast as before.
+    if (!db.hasCredentials())
+        return null;
+    const targetDir = path.resolve(dir);
+    const { section, projectId } = await fetchBriefSection(db, targetDir);
+    if (!section)
+        return null;
+    // Drift line vs local HEAD: the anti-staleness signal. The brief itself is
+    // fresh (built now), but this tells the agent how far the working tree has
+    // moved past the last analyzed commit. Best-effort — never blocks the brief.
+    let drift = null;
+    if (projectId) {
+        try {
+            const latest = await db.rest(`changelog?select=commit_hash,hash_aliases&commit_hash=not.is.null&order=created_at.desc&limit=1&project_id=eq.${projectId}`);
+            const candidatos = [
+                latest[0]?.commit_hash ?? null,
+                ...commitAliasesShort(latest[0]?.hash_aliases),
+            ];
+            for (const c of candidatos) {
+                drift = await derivaContraHead(targetDir, c);
+                if (drift)
+                    break;
+            }
+        }
+        catch {
+            drift = null;
+        }
+    }
+    return drift ? `${section}\n\n${drift}` : section;
+}
+// ── SessionStart hook install (opt-in, per repo) ─────────────────────────────
+//
+// The push channel lives in `.claude/settings.json` under hooks.SessionStart.
+// Consent is the act of running `changebook hook-context install` (or saying
+// yes to init's offer) — this file is often committed and shared, so we NEVER
+// write it silently and NEVER clobber a config we can't parse.
+// `2>/dev/null || true`: if `changebook` isn't on PATH for some teammate, the
+// shell error is swallowed and the hook exits 0 — a missing binary must not
+// make a session-start hook look failed. printContext already emits only the
+// JSON payload (or nothing) on stdout.
+const HOOK_COMMAND = "changebook context 2>/dev/null || true";
+// Recognisable substring to find/remove our own entry without touching others.
+const HOOK_MARKER = "changebook context";
+function settingsPath(dir) {
+    return path.join(path.resolve(dir), ".claude", "settings.json");
+}
+function groupHasMarker(g) {
+    return (g.hooks ?? []).some((h) => (h.command ?? "").includes(HOOK_MARKER));
+}
+function readSettings(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {}; // missing file → empty settings
+    }
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null; // unparseable → caller must refuse, never clobber
+    }
+}
+export function contextHookInstalled(dir) {
+    const s = readSettings(settingsPath(dir));
+    return Boolean(s?.hooks?.SessionStart?.some(groupHasMarker));
+}
+export function installContextHook(dir) {
+    const file = settingsPath(dir);
+    const settings = readSettings(file);
+    if (settings === null) {
+        throw new Error(`Refusing to touch ${file}: it isn't valid JSON. Fix or remove it, then retry.`);
+    }
+    const hooks = (settings.hooks ??= {});
+    const sessionStart = (hooks.SessionStart ??= []);
+    if (sessionStart.some(groupHasMarker))
+        return "already";
+    sessionStart.push({
+        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+    return "installed";
+}
+export function uninstallContextHook(dir) {
+    const file = settingsPath(dir);
+    const settings = readSettings(file);
+    if (!settings || !settings.hooks?.SessionStart)
+        return "absent";
+    const before = settings.hooks.SessionStart;
+    // Drop our command from every group, then drop groups left empty. Foreign
+    // hooks in the same group (unusual, but possible) are preserved.
+    const after = before
+        .map((g) => ({
+        ...g,
+        hooks: (g.hooks ?? []).filter((h) => !(h.command ?? "").includes(HOOK_MARKER)),
+    }))
+        .filter((g) => (g.hooks ?? []).length > 0);
+    if (after.length === before.length && before.every((g) => !groupHasMarker(g))) {
+        return "absent";
+    }
+    if (after.length > 0)
+        settings.hooks.SessionStart = after;
+    else
+        delete settings.hooks.SessionStart;
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+    return "removed";
+}
+export async function printContext(db, dir) {
+    try {
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), CONTEXT_TIMEOUT_MS));
+        const additionalContext = await Promise.race([
+            buildPayload(db, dir),
+            timeout,
+        ]);
+        if (!additionalContext)
+            return;
+        // The SessionStart contract: stdout JSON whose additionalContext is
+        // injected into the agent's context. Anything else on stdout would be
+        // treated as context too, so we emit ONLY this object.
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "SessionStart",
+                additionalContext,
+            },
+        }));
+    }
+    catch {
+        // Swallow everything: opening a session must never fail because of us.
+    }
+}
+//# sourceMappingURL=context.js.map

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

@@ -20,6 +20,7 @@ import { runGuard } from "./guard.js";
 import { hookStatus, installHook, uninstallHook } from "./hook.js";
 import { importHistory } from "./import.js";
 import { registerAgents } from "./init.js";
+import { contextHookInstalled, installContextHook, printContext, uninstallContextHook, } from "./context.js";
 import { login } from "./login.js";
 import { AUTH_HELP, Supabase } from "./supabase.js";
 import { syncContextFiles } from "./sync.js";
@@ -45,6 +46,11 @@ Usage:
   changebook guard [dir]    Check staged files against open atlas alerts
                           (what the pre-commit hook runs; exit 3 = block)
   changebook sync [dir]     Refresh the product map inside CLAUDE.md/AGENTS.md
+  changebook context [dir]  Print the fresh atlas brief as a Claude Code
+                          SessionStart hook payload (used by the push hook)
+  changebook hook-context install|uninstall|status [dir]
+                          Push the atlas into EVERY Claude Code session at turn 0
+                          via a SessionStart hook in .claude/settings.json
   changebook init [dir]     login + register MCP in every agent found + hook + sync
   changebook open           Open the web atlas in the browser
   changebook serve          Run the MCP server on stdio (default with no arguments)
@@ -131,7 +137,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": {
@@ -163,6 +185,34 @@ async function main() {
             await syncContextFiles(db, arg ?? process.cwd());
             return;
         }
+        case "context": {
+            // Runs on the SessionStart critical path: NEVER requireCredentials (it
+            // would exit 1), NEVER print help. printContext fails open — logged out,
+            // offline or slow all resolve to zero output and exit 0.
+            await printContext(new Supabase(), arg ?? process.cwd());
+            return;
+        }
+        case "hook-context": {
+            const dir = process.argv[4] ?? process.cwd();
+            if (arg === "install") {
+                const r = installContextHook(dir);
+                console.error(r === "installed"
+                    ? `✓ SessionStart hook installed (${dir}/.claude/settings.json). Every Claude Code session now opens with the fresh atlas map.`
+                    : "SessionStart hook already installed.");
+            }
+            else if (arg === "uninstall") {
+                const r = uninstallContextHook(dir);
+                console.error(r === "removed"
+                    ? "✓ SessionStart hook removed."
+                    : "No ChangeBook SessionStart hook found.");
+            }
+            else {
+                console.error(contextHookInstalled(dir)
+                    ? `✓ ChangeBook SessionStart hook installed (${dir}/.claude/settings.json).`
+                    : "✗ No ChangeBook SessionStart hook. Install with: changebook hook-context install");
+            }
+            return;
+        }
         case "init": {
             let db = new Supabase();
             if (!db.hasCredentials()) {
@@ -181,6 +231,14 @@ async function main() {
                 console.error(error instanceof Error ? error.message : String(error));
             }
             await syncContextFiles(db, dir);
+            // Ofrecer el push, NUNCA instalarlo en silencio: .claude/settings.json se
+            // suele commitear y compartir, y meter un hook en el arranque de sesiones
+            // ajenas sin permiso explícito no se hace. Se ofrece el comando; correrlo
+            // ES el consentimiento.
+            if (!contextHookInstalled(dir)) {
+                console.error("\nOptional: push the atlas into EVERY Claude Code session at turn 0 " +
+                    "(no tool call needed, never stale):\n  changebook hook-context install");
+            }
             console.error(`✓ Ready. Ask your agent about the atlas, or open ${atlasWebUrl()}`);
             return;
         }

package/dist/sync.js

@@ -53,18 +53,21 @@ 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) {
+/**
+ * Trae del atlas los datos del bloque y los destila con buildSection, SIN
+ * escribir nada. Es el corazón compartido de `sync` (que lo escribe en
+ * CLAUDE.md/AGENTS.md) y de `context` (que lo empuja por stdout al hook
+ * SessionStart). Misma frontera por proyecto estricta que sync: proyecto que
+ * no casa → bloque vacío, jamás el de otro.
+ */
+export async function fetchBriefSection(db, targetDir) {
     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
-    // los datos de todos. Y si el proyecto aún no existe en el atlas, el mapa
-    // debe salir VACÍO — jamás el de otro proyecto.
+    // Frontera por proyecto (QA 2026-07-18): sin filtro, una cuenta con varios
+    // proyectos construiría el mapa de ESTE repo mezclando los datos de todos.
+    // Y si el proyecto aún no existe en el atlas, el mapa debe salir VACÍO.
     let projectFilter;
     let projectResolved = true;
     try {
-        // strict: el respaldo de proyecto único (0.4.2) es para tools que
-        // conversan con un agente; sync escribe este archivo en silencio y no
-        // puede adivinar — si el nombre no casa, mapa vacío y punto.
         projectFilter = await db.projectFilterFor(projectName, { strict: true });
     }
     catch {
@@ -78,19 +81,10 @@ export async function syncContextFiles(db, targetDir) {
             projectFilter),
         db.rest(`changelog?select=business_impact,created_at&order=created_at.desc&limit=${MAX_CHANGES}` +
             projectFilter),
-        // AI-detected regression warnings: best-effort — an error (older schema,
-        // RLS hiccup) must not block the sync of the rest of the map.
         db
-            .rest(
-        // resolved_at=is.null: a dismissed/auto-resolved alert inside the
-        // window must not resurface in every agent session as urgent.
-        `regression_alerts?select=module,plain,created_at&created_at=gte.${since}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}` +
+            .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(() => []),
-        // Auto-remediación fase 2: los encargos pendientes entran en el bloque
-        // para que CUALQUIER sesión arranque sabiéndolos y se ofrezca a atacarlos
-        // (proponer, no ejecutar — la aprobación sigue siendo del humano).
-        // Best-effort como las alertas.
         projectResolved && projectId
             ? db
                 .callRpc('list_agent_tasks', {
@@ -101,9 +95,13 @@ export async function syncContextFiles(db, targetDir) {
             : Promise.resolve([]),
     ]);
     const section = buildSection(moduleRows, changes, alerts, projectName, pendingTasks);
+    return { section, projectId, projectResolved };
+}
+export async function syncContextFiles(db, targetDir, opts = {}) {
+    const { section, projectId, projectResolved } = await fetchBriefSection(db, targetDir);
     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 +157,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 +356,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 +365,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 +375,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,30 @@ 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;
+}
+export const FILE_COMMITS_CAP = 5;
+export function recentCommitsForFile(changelogIds, commitById, cap = FILE_COMMITS_CAP) {
+    const all = changelogIds
+        .map((id) => commitById.get(id))
+        .filter((c) => Boolean(c));
+    return { commits: all.slice(0, cap), more: Math.max(0, all.length - cap) };
+}
 // 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 +318,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 +356,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 +377,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 +526,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 +546,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 +558,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 +593,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)
@@ -583,7 +623,7 @@ Returns (structured): { module, count, changes: [{ date, commit, risk, note, tec
     });
     server.registerTool("atlas_file_context", {
         title: "Context of the files you are about to edit",
-        description: `Everything the atlas knows about specific FILES: which module each belongs to, its risk, open regression alerts on those modules, how often they changed recently, and the CURRENT value of watched config constants (with the commit it comes from — no need to re-read the file for those).
+        description: `Everything the atlas knows about specific FILES: which module each belongs to, its risk, open regression alerts on those modules, how often they changed recently, the recent commits that touched each file (cite these instead of running git log), and the CURRENT value of watched config constants (with the commit it comes from — no need to re-read the file for those).
 
 Call this BEFORE editing a file — one cheap call instead of re-reading the code and its git history.
 
@@ -591,7 +631,7 @@ Args:
   - files (required): 1-8 repo-relative paths.
   - project (recommended): the repo you are working in (folder name or slug). The atlas is per-project — always scope to your own project.
 
-Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_changed, last_note }], open_alerts, watched_values: [{ name, value, commit }] }] }`,
+Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_changed, last_note }], open_alerts, recent_commits: [{ commit, commit_aliases, date }], recent_commits_more, watched_values: [{ name, value, commit }] }] }`,
         inputSchema: {
             files: z.array(z.string().min(1).max(300)).min(1).max(8)
                 .describe("Repo-relative paths you are about to edit"),
@@ -610,10 +650,18 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             const pf = await db.projectFilterFor(project);
             const paths = [...new Set(files.map(normalizeRepoPath).filter(Boolean))];
             const perFile = await Promise.all(paths.map(async (file) => {
-                const rows = await db.rest(`change_module?select=module,risk,note,created_at&${fileContainsFilter(file)}&order=created_at.desc&limit=20` +
+                const rows = await db.rest(`change_module?select=changelog_id,module,risk,note,created_at&${fileContainsFilter(file)}&order=created_at.desc&limit=20` +
                     pf);
                 const byModule = new Map();
+                // Commits que tocaron ESTE archivo, del más nuevo al más viejo,
+                // deduplicados (un mismo análisis puede traer varias filas de
+                // change_module para el mismo archivo). El hash lo resuelve la
+                // consulta batcheada de abajo; aquí solo se guarda el orden.
+                const changelogIds = [];
                 for (const row of rows) {
+                    if (!changelogIds.includes(row.changelog_id)) {
+                        changelogIds.push(row.changelog_id);
+                    }
                     const name = (row.module ?? "").trim();
                     if (!name)
                         continue;
@@ -630,11 +678,38 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                         });
                     }
                 }
-                return { file, modules: [...byModule.values()] };
+                return { file, modules: [...byModule.values()], changelogIds };
             }));
             const moduleNames = [
                 ...new Set(perFile.flatMap((f) => f.modules.map((m) => m.module))),
             ];
+            // Commits recientes por archivo (T2: el agente que va a editar dejaba
+            // de necesitar `git log -- <archivo>`). UNA consulta batcheada para
+            // TODOS los archivos, no una por archivo: es la tool que corre antes
+            // de cada edición. hash_aliases entra por el espejo post-squash — el
+            // hash servido tiene que existir en el main del consultante.
+            const allChangelogIds = [
+                ...new Set(perFile.flatMap((f) => f.changelogIds)),
+            ];
+            const commitById = new Map();
+            if (allChangelogIds.length > 0) {
+                const commitRows = await db
+                    .rest(`changelog?select=id,commit_hash,created_at,hash_aliases&id=in.(${allChangelogIds.join(",")})`)
+                    .catch(() => []);
+                for (const r of commitRows) {
+                    if (!r.commit_hash)
+                        continue;
+                    commitById.set(r.id, {
+                        commit: r.commit_hash.slice(0, 7),
+                        commit_aliases: commitAliasesShort(r.hash_aliases),
+                        date: day(r.created_at),
+                    });
+                }
+            }
+            const commitsByFile = new Map();
+            for (const f of perFile) {
+                commitsByFile.set(f.file, recentCommitsForFile(f.changelogIds, commitById));
+            }
             const [alerts, watched] = await Promise.all([
                 moduleNames.length
                     ? db.rest(`regression_alerts?select=module,plain,evidence_symbol,evidence_expect&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(moduleNames))})&order=created_at.desc&limit=10` +
@@ -678,10 +753,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)
@@ -709,6 +794,13 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                             ? ` (as of commit ${w.commit_hash.slice(0, 7)})`
                             : ""));
                 }
+                // Commits recientes que tocaron este archivo: cita estos hashes en
+                // vez de correr `git log -- <archivo>`.
+                const rc = commitsByFile.get(f.file);
+                if (rc && rc.commits.length > 0) {
+                    const parts = rc.commits.map((c) => `${c.commit}${c.commit_aliases.length ? ` (=${c.commit_aliases.join(",")})` : ""} (${c.date})`);
+                    lines.push(`- Recent commits: ${parts.join(", ")}${rc.more > 0 ? ` (+${rc.more} more)` : ""}`);
+                }
                 lines.push("");
             }
             if (!ancla)
@@ -718,7 +810,7 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             // descripción lo prometía y solo viajaba en el texto (bug cazado por
             // el verificador adversarial del benchmark).
             const salida = toolResult(contextText, {
-                files: perFile.map((f) => ({
+                files: perFile.map(({ changelogIds: _drop, ...f }) => ({
                     ...f,
                     open_alerts: f.modules.flatMap((m) => (alertsByModule.get(m.module) ?? []).map((plain) => ({
                         module: m.module,
@@ -729,6 +821,8 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                         value: w.value,
                         commit: w.commit_hash?.slice(0, 7) ?? null,
                     })),
+                    recent_commits: commitsByFile.get(f.file)?.commits ?? [],
+                    recent_commits_more: commitsByFile.get(f.file)?.more ?? 0,
                 })),
             });
             recordRead(db, "atlas_file_context", pf, servedCharsOf(salida), Date.now() - t0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changebook",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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.6",
   "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.6",
       "transport": {
         "type": "stdio"
       }