refacil-sdd-ai 2.2.1 → 2.6.0

package/README.md

@@ -7,7 +7,9 @@ Instala skills para **Claude Code** y **Cursor** que guian al desarrollador por
 ## Requisitos
 
 - **Node.js >= 20.19.0** (requerido por OpenSpec)
-- **Claude Code** o **Cursor** instalado
+- **Claude Code >= 2.1.89** (requerido por el hook `compact-bash` para rewrite silencioso de comandos via `updatedInput`) o **Cursor**
+
+`refacil-sdd-ai init` verifica la version de Claude Code y muestra advertencia si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero el hook `compact-bash` no tendra efecto (Claude Code ignora `updatedInput` en versiones antiguas).
 
 ## Instalacion y Setup
 
@@ -53,6 +55,11 @@ refacil-sdd-ai init          # Instalar skills, hooks y crear configs en el repo
 refacil-sdd-ai update        # Actualizar skills y hooks a la ultima version
 refacil-sdd-ai check-update  # Verifica si hay una version mas reciente en npm (usado por hook)
 refacil-sdd-ai check-review  # Verifica que el review se haya completado (usado por hook)
+refacil-sdd-ai compact-bash  # Hook de rewrite de comandos Bash bare (usado por hook, no invocar manual)
+refacil-sdd-ai compact stats     # Tabla de rewrites + tokens estimados + USD ahorrado
+refacil-sdd-ai compact disable   # Desactiva el hook compact-bash sin desinstalarlo
+refacil-sdd-ai compact enable    # Reactiva el hook compact-bash
+refacil-sdd-ai compact clear-log # Limpia ~/.refacil-sdd-ai/compact.log
 refacil-sdd-ai clean         # Eliminar skills y remover hooks SDD-AI del repo
 refacil-sdd-ai help          # Ver ayuda
 ```
@@ -327,7 +334,8 @@ El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
 
 | Hook | Evento | Que hace |
 |------|--------|----------|
-| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente |
+| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente. Tambien **sincroniza el bloque `compact-guidance`** en `AGENTS.md` (ver [Eficiencia de tokens](#eficiencia-de-tokens-bloque-auto-gestionado-en-agentsmd)). |
+| `compact-bash` | `PreToolUse` (Bash) | Reescribe **silenciosamente** comandos Bash bare (git/tests/docker logs) a su forma compacta usando `updatedInput`. Sin turnos extra y sin que Claude vea el cambio. Requiere Claude Code >= 2.1.89. |
 | `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, **bloquea el push** y emite instrucciones para ejecutar `/refacil:review`. El hook no invoca skills por si mismo. |
 
 #### Flujo del hook de review
@@ -378,6 +386,121 @@ openspec/changes/fix-session-timeout-redis/
 
 El archivo `.review-passed` contiene: veredicto, fecha, resumen, cantidad de hallazgos y si hubo blockers.
 
+### Hook `compact-bash` — rewrite silencioso de comandos Bash
+
+Segunda capa de reduccion de tokens, **sin costo conversacional**. Antes de que Claude Code ejecute un comando Bash, el hook `compact-bash` inspecciona el comando y, si matchea una regla, lo reescribe usando el campo `updatedInput` del hook. Claude **no ve el cambio**, no hay turno adicional, no hay bloqueo.
+
+**Reglas activas (19 reglas)**:
+
+Fase 1 — git, tests base, docker logs:
+
+| Comando bare | Reescrito a | Ahorro tipico |
+|---|---|---|
+| `git log` | `git log --oneline -20` | ~85% |
+| `git status` | `git status -s` | ~70% |
+| `git diff` (sin args) | `git diff --stat` | ~80% |
+| `git show` | `git show --stat` | ~70% |
+| `docker logs <container>` | `docker logs --tail 100 <container>` | ~80%+ |
+| `npm test` / `yarn test` / `pnpm test` | `… 2>&1 \| tail -80` | ~90% |
+| `jest` | `jest --silent --reporters=summary` | ~85% |
+| `pytest` | `pytest -q` | ~60% |
+
+Fase 2A — linters, type checkers, build, sistema:
+
+| Comando bare | Reescrito a | Ahorro tipico |
+|---|---|---|
+| `eslint` | `eslint . --format compact --quiet` | ~70% |
+| `eslint <path>` | `eslint <path> --format compact` | ~60% |
+| `biome check` | `biome check --reporter=summary` | ~65% |
+| `tsc` / `npx tsc …` | `… 2>&1 \| head -80` | variable |
+| `prettier --check <path>` | `prettier --check <path> --loglevel warn` | ~50% |
+| `npm audit` | `npm audit 2>&1 \| tail -10` | ~80% |
+| `npm ls` | `npm ls --depth=0` | ~90% |
+| `cargo build` / `cargo test` / `cargo check` | `… --quiet` | ~50% |
+| `go test …` (sin flags) | `… 2>&1 \| tail -80` | ~70% |
+| `mvn test` | `mvn test -q` | ~60% |
+| `./gradlew test` / `gradle test` | `… -q` | ~60% |
+| `ps aux` | `ps -eo pid,pcpu,pmem,comm \| head -30` | ~80% |
+
+**Detector de intencion**: si el comando ya tiene flags explicitos (`git log -p`, `git log --all`, `jest --watch`, `docker logs --tail 50 …`), el hook **no interviene**. Tu intencion manda.
+
+**Escape mecanismo**: prefija `COMPACT=0` al comando para desactivar el rewrite puntualmente: `COMPACT=0 git log`.
+
+**Pipes y redirecciones** en test bare: si ya hay `|` o `>`, el detector no las envuelve de nuevo.
+
+**Subcomandos de control**:
+
+```bash
+refacil-sdd-ai compact stats       # tabla de rewrites + tokens estimados + USD
+refacil-sdd-ai compact disable     # desactiva el hook sin desinstalar
+refacil-sdd-ai compact enable      # reactiva el hook
+refacil-sdd-ai compact clear-log   # limpia ~/.refacil-sdd-ai/compact.log
+```
+
+**Telemetria**: cada rewrite genera una linea JSON en `~/.refacil-sdd-ai/compact.log` con timestamp, ruleId y estimacion de tokens ahorrados. El log se usa para el comando `compact stats` que agrega por regla y calcula costo estimado (a razon de $3/MTok input de Sonnet, conservador). La telemetria es local; nada se envia a la nube.
+
+**Flujo del hook**:
+
+```
+Claude emite "git log"
+  │
+  ▼
+Hook compact-bash recibe tool_input via stdin (JSON)
+  │
+  ▼
+¿Matchea alguna regla y no tiene intent flags?
+  │
+  ├─ SI  ──► stdout JSON:
+  │          {
+  │            "hookSpecificOutput": {
+  │              "hookEventName": "PreToolUse",
+  │              "permissionDecision": "allow",
+  │              "updatedInput": { "command": "git log --oneline -20", ... },
+  │              "permissionDecisionReason": "compact-bash: git log → --oneline -20"
+  │            }
+  │          }
+  │          Claude Code ejecuta el comando reescrito. Claude no lo ve.
+  │
+  └─ NO  ──► stdout vacio → Claude Code ejecuta el comando original.
+```
+
+### Eficiencia de tokens (bloque auto-gestionado en AGENTS.md)
+
+La metodologia SDD-AI genera consumo elevado de contexto (artefactos, specs, prompts de skills). Para compensarlo, `refacil-sdd-ai` mantiene un bloque de guia de eficiencia de tokens dentro de `AGENTS.md` que instruye a la IA sobre como pedir salidas compactas (Read con offset/limit, `git log --oneline`, tests solo con failures, etc.).
+
+**Caracteristicas**:
+- Delimitado por marcadores HTML: `<!-- refacil-sdd-ai:compact-guidance:start -->` y `<!-- refacil-sdd-ai:compact-guidance:end -->`
+- Fuente de verdad: `templates/compact-guidance.md` dentro del paquete
+- Se sincroniza automaticamente en tres momentos:
+  1. `refacil-sdd-ai init` (al instalar)
+  2. `refacil-sdd-ai update` (al actualizar manualmente)
+  3. Hook `check-update` en cada `SessionStart` (garantiza que repos ya instalados reciban las guias nuevas sin intervencion manual)
+- Si `AGENTS.md` aun no existe (el usuario no ha corrido `/refacil:setup`), la sincronizacion no hace nada — no se crea el archivo a espaldas del usuario
+- `refacil-sdd-ai clean` remueve el bloque de forma limpia
+
+> **IMPORTANTE**: No edites manualmente el contenido entre los marcadores. Cualquier cambio se sobrescribira en la proxima sesion. Si tienes sugerencias sobre reglas de eficiencia, proponlas al paquete (`templates/compact-guidance.md`).
+
+**Flujo del refresh automatico**:
+
+```
+Nueva sesion de Claude Code
+  │
+  ▼
+Hook SessionStart → ejecuta "refacil-sdd-ai check-update"
+  │
+  ├─► syncCompactGuidance()
+  │     │
+  │     ├─ AGENTS.md no existe → skip (sin ruido)
+  │     ├─ sin marcadores      → append del bloque al final
+  │     ├─ con marcadores      → reemplaza contenido entre ellos
+  │     └─ contenido identico  → no-op (no ensucia git status)
+  │
+  └─► chequeo de version npm
+        │
+        └─ si hay version nueva → npm update -g + refacil-sdd-ai update
+                                  (que vuelve a sincronizar el bloque)
+```
+
 ## Como funciona
 
 1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, crea `CLAUDE.md` + `.cursorrules`, y configura hooks automaticos en `.claude/settings.json`
@@ -393,6 +516,7 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 
 /refacil:setup               →  OpenSpec instalado
                                  AGENTS.md generado (analisis automatico del repo)
+                                 + bloque compact-guidance inyectado automaticamente
 
 /refacil:propose             →  Artefactos en openspec/changes/
 /refacil:apply               →  Codigo implementado
@@ -415,6 +539,7 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 CLAUDE.md                    # Claude Code — apunta a AGENTS.md
 .cursorrules                 # Cursor — apunta a AGENTS.md
 AGENTS.md                    # Generado por /refacil:setup (NO por el CLI)
+                             # Incluye bloque compact-guidance auto-gestionado por el hook SessionStart
 openspec/                    # Generado por /refacil:setup via OpenSpec
 ```
 
@@ -436,6 +561,29 @@ npm uninstall -g refacil-sdd-ai
 - [Claude Code](https://claude.ai/code) — CLI de Anthropic
 - [Cursor](https://cursor.sh) — IDE con IA
 
+## Cambios recientes
+
+**v2.6.0** — Fase 2 del hook `compact-bash`:
+- 11 reglas nuevas: `eslint`, `biome check`, `tsc`, `prettier --check`, `npm audit`, `npm ls`, `cargo build/test/check`, `go test`, `mvn test`, `gradle test`, `ps aux` (total: 19 reglas)
+- Telemetria local en `~/.refacil-sdd-ai/compact.log`
+- Subcomandos `compact stats | disable | enable | clear-log`
+- `ps-aux` solo se activa en Unix (Linux/Mac); en Windows la regla no interviene
+
+**v2.5.0** — Fase 1 del hook `compact-bash`:
+- Hook `PreToolUse` que reescribe silenciosamente comandos Bash bare via `updatedInput` (requiere Claude Code >= 2.1.89)
+- Reglas iniciales: git log/status/diff/show, docker logs, npm/yarn/pnpm test, jest, pytest
+- Escape mecanismo `COMPACT=0 <cmd>`
+
+**v2.4.0** — Reduccion de tokens en la metodologia:
+- Boilerplate "Antes de empezar" unificado en 9 skills
+- Validacion de OpenSpec simplificada en `prereqs/SKILL.md`
+- Templates consolidados (`claude-md.md` + `cursorrules.md` → `methodology-guide.md` unico)
+- Compactacion de `review/SKILL.md`, `bug/SKILL.md`, `test/SKILL.md`
+
+**v2.3.0** — Bloque `compact-guidance` auto-gestionado en `AGENTS.md`:
+- Hook `SessionStart` sincroniza el bloque en cada sesion
+- Fuente de verdad: `templates/compact-guidance.md`
+
 ## Licencia
 
 MIT

package/bin/cli.js

@@ -2,6 +2,12 @@
 
 const fs = require('fs');
 const path = require('path');
+const {
+  syncCompactGuidance,
+  removeCompactGuidance,
+} = require('../lib/compact-guidance');
+const compactBash = require('../lib/compact/bash');
+const compactTelemetry = require('../lib/compact/telemetry');
 
 const SKILLS = [
   'setup',
@@ -64,44 +70,47 @@ function extractSddSection(templateContent) {
   return templateContent.substring(idx);
 }
 
-function createClaudeMd() {
-  const dest = path.join(projectRoot, 'CLAUDE.md');
-  const template = fs.readFileSync(path.join(packageRoot, 'templates', 'claude-md.md'), 'utf8');
+function readMethodologyGuide() {
+  return fs.readFileSync(
+    path.join(packageRoot, 'templates', 'methodology-guide.md'),
+    'utf8',
+  );
+}
 
-  if (fs.existsSync(dest)) {
-    const existing = fs.readFileSync(dest, 'utf8');
+function writeGuideFile(destPath, header, label) {
+  const guide = readMethodologyGuide();
+  const content = `# ${header}\n\n${guide}`;
+
+  if (fs.existsSync(destPath)) {
+    const existing = fs.readFileSync(destPath, 'utf8');
     if (existing.includes(SDD_SECTION_MARKER)) {
-      console.log('  CLAUDE.md ya tiene la seccion SDD-AI. Sin cambios.');
+      console.log(`  ${label} ya tiene la seccion SDD-AI. Sin cambios.`);
       return false;
     }
-    const sddSection = extractSddSection(template);
-    fs.writeFileSync(dest, existing.trimEnd() + '\n\n' + sddSection + '\n');
-    console.log('  CLAUDE.md existente — seccion SDD-AI agregada al final.');
+    const sddSection = extractSddSection(guide);
+    fs.writeFileSync(destPath, existing.trimEnd() + '\n\n' + sddSection + '\n');
+    console.log(`  ${label} existente — seccion SDD-AI agregada al final.`);
     return true;
   }
 
-  fs.writeFileSync(dest, template);
+  fs.writeFileSync(destPath, content);
   return true;
 }
 
-function createCursorRules() {
-  const dest = path.join(projectRoot, '.cursorrules');
-  const template = fs.readFileSync(path.join(packageRoot, 'templates', 'cursorrules.md'), 'utf8');
-
-  if (fs.existsSync(dest)) {
-    const existing = fs.readFileSync(dest, 'utf8');
-    if (existing.includes(SDD_SECTION_MARKER)) {
-      console.log('  .cursorrules ya tiene la seccion SDD-AI. Sin cambios.');
-      return false;
-    }
-    const sddSection = extractSddSection(template);
-    fs.writeFileSync(dest, existing.trimEnd() + '\n\n' + sddSection + '\n');
-    console.log('  .cursorrules existente — seccion SDD-AI agregada al final.');
-    return true;
-  }
+function createClaudeMd() {
+  return writeGuideFile(
+    path.join(projectRoot, 'CLAUDE.md'),
+    'CLAUDE.md',
+    'CLAUDE.md',
+  );
+}
 
-  fs.writeFileSync(dest, template);
-  return true;
+function createCursorRules() {
+  return writeGuideFile(
+    path.join(projectRoot, '.cursorrules'),
+    'Cursor Rules',
+    '.cursorrules',
+  );
 }
 
 function removeSkills() {
@@ -121,6 +130,29 @@ function removeSkills() {
   return removed;
 }
 
+function checkClaudeCodeVersion() {
+  const { execSync } = require('child_process');
+  try {
+    const output = execSync('claude --version 2>&1', {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const match = output.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return { ok: null, version: null };
+    const maj = Number(match[1]);
+    const min = Number(match[2]);
+    const patch = Number(match[3]);
+    const ok =
+      maj > 2 ||
+      (maj === 2 && min > 1) ||
+      (maj === 2 && min === 1 && patch >= 89);
+    return { ok, version: `${maj}.${min}.${patch}` };
+  } catch (_) {
+    return { ok: null, version: null };
+  }
+}
+
 function checkNodeVersion() {
   const version = process.version; // e.g. v20.19.5
   const major = parseInt(version.split('.')[0].replace('v', ''));
@@ -167,9 +199,28 @@ function installHook() {
     changed = true;
   }
 
-  // PreToolUse: check-review
+  // PreToolUse
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
+  // compact-bash (must run BEFORE check-review so rewrite is visible to subsequent hooks)
+  const hasCompactHook = settings.hooks.PreToolUse.some(
+    (h) => h._sdd_compact === true,
+  );
+  if (!hasCompactHook) {
+    settings.hooks.PreToolUse.unshift({
+      _sdd_compact: true,
+      matcher: 'Bash',
+      hooks: [
+        {
+          type: 'command',
+          command: 'refacil-sdd-ai compact-bash',
+        },
+      ],
+    });
+    changed = true;
+  }
+
+  // check-review
   const hasReviewHook = settings.hooks.PreToolUse.some(
     (h) => h._sdd_review === true,
   );
@@ -225,7 +276,7 @@ function uninstallHook() {
   if (Array.isArray(settings.hooks.PreToolUse)) {
     const original = settings.hooks.PreToolUse.length;
     settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-      (h) => h._sdd_review !== true,
+      (h) => h._sdd_review !== true && h._sdd_compact !== true,
     );
     if (settings.hooks.PreToolUse.length !== original) changed = true;
     if (settings.hooks.PreToolUse.length === 0) delete settings.hooks.PreToolUse;
@@ -245,6 +296,15 @@ function checkUpdate() {
   const { execSync } = require('child_process');
   const localVersion = require(path.join(packageRoot, 'package.json')).version;
 
+  // Always ensure AGENTS.md has current compact-guidance block (silent unless error)
+  try {
+    syncCompactGuidance(projectRoot, packageRoot);
+  } catch (err) {
+    process.stderr.write(
+      `[refacil-sdd-ai] No se pudo sincronizar compact-guidance: ${err.message}\n`,
+    );
+  }
+
   try {
     const latest = execSync('npm view refacil-sdd-ai version', {
       encoding: 'utf8',
@@ -319,8 +379,7 @@ function checkReview() {
     const reason =
       missing.length === 1
         ? `[refacil-sdd-ai] Review pendiente para: ${names}. ` +
-          'Ejecuta /refacil:review automaticamente ahora sobre ese cambio pendiente. ' +
-          'Informa al usuario que el review se esta ejecutando automaticamente antes de subir el codigo. ' +
+          'Deten el push y ejecuta /refacil:review sobre ese cambio antes de subir codigo. ' +
           'Si el review aprueba, reintenta el git push. ' +
           'Si el review requiere correcciones, informa los hallazgos al usuario y NO reintentar el push.'
         : `[refacil-sdd-ai] Hay multiples cambios sin review aprobado: ${names}. ` +
@@ -347,6 +406,18 @@ function init() {
     console.log(`  Node.js ${process.version} OK`);
   }
 
+  // Check Claude Code version (for compact-bash hook)
+  const claudeCheck = checkClaudeCodeVersion();
+  if (claudeCheck.ok === true) {
+    console.log(`  Claude Code ${claudeCheck.version} OK`);
+  } else if (claudeCheck.ok === false) {
+    console.log(`\n  ADVERTENCIA: Claude Code ${claudeCheck.version} detectado.`);
+    console.log('  El hook compact-bash requiere Claude Code >= 2.1.89 para rewrite silencioso.');
+    console.log('  Con version inferior se instala igual pero el rewrite no tendra efecto.');
+    console.log('  Actualiza con: npm install -g @anthropic-ai/claude-code\n');
+  }
+  // ok === null: claude no esta en PATH, silencioso
+
   // Install skills
   const count = installSkills();
   console.log(`  ${count} skills instaladas en .claude/skills/ y .cursor/skills/`);
@@ -366,6 +437,18 @@ function init() {
     console.log('  Hook check-update agregado a .claude/settings.json');
   }
 
+  // Sync compact-guidance block in AGENTS.md (if it exists)
+  try {
+    const result = syncCompactGuidance(projectRoot, packageRoot);
+    if (result.status === 'appended') {
+      console.log('  Bloque compact-guidance agregado a AGENTS.md');
+    } else if (result.status === 'replaced') {
+      console.log('  Bloque compact-guidance actualizado en AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo sincronizar compact-guidance: ${err.message}`);
+  }
+
   console.log('\n  Siguientes pasos:\n');
   console.log('  1. REINICIA tu sesion de Claude Code o Cursor');
   console.log('     (las skills nuevas no se detectan hasta reiniciar)\n');
@@ -386,6 +469,18 @@ function update() {
     console.log('  Hook check-update agregado a .claude/settings.json');
   }
 
+  // Sync compact-guidance block in AGENTS.md
+  try {
+    const result = syncCompactGuidance(projectRoot, packageRoot);
+    if (result.status === 'appended') {
+      console.log('  Bloque compact-guidance agregado a AGENTS.md');
+    } else if (result.status === 'replaced') {
+      console.log('  Bloque compact-guidance actualizado en AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo sincronizar compact-guidance: ${err.message}`);
+  }
+
   console.log('\n  REINICIA tu sesion de Claude Code o Cursor para aplicar los cambios.\n');
 }
 
@@ -398,11 +493,75 @@ function clean() {
   } else {
     console.log('  No se encontraron hooks SDD-AI para remover.');
   }
+
+  // Remove compact-guidance block from AGENTS.md if present
+  try {
+    const result = removeCompactGuidance(projectRoot);
+    if (result.status === 'removed') {
+      console.log('  Bloque compact-guidance removido de AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo limpiar compact-guidance: ${err.message}`);
+  }
+
   console.log('  AGENTS.md, CLAUDE.md y .cursorrules no fueron eliminados.');
   console.log('\n  Nota: Los comandos opsx:* de OpenSpec no se eliminan.');
   console.log('  Para eliminar OpenSpec: rm -rf openspec/ .claude/commands/opsx .cursor/commands/opsx\n');
 }
 
+// --- Compact subcommands (stats / enable / disable / clear-log) ---
+
+function handleCompactSubcommand(sub) {
+  switch (sub) {
+    case 'stats':
+      showCompactStats();
+      break;
+    case 'disable':
+      compactTelemetry.disable();
+      console.log('  compact-bash deshabilitado. Reactiva con: refacil-sdd-ai compact enable');
+      break;
+    case 'enable':
+      compactTelemetry.enable();
+      console.log('  compact-bash habilitado.');
+      break;
+    case 'clear-log':
+      compactTelemetry.clearLog();
+      console.log('  compact.log limpiado.');
+      break;
+    default:
+      console.log('Uso: refacil-sdd-ai compact <stats|disable|enable|clear-log>');
+  }
+}
+
+function showCompactStats() {
+  const s = compactTelemetry.stats();
+  if (s.totalRewrites === 0) {
+    console.log('\n  No hay rewrites registrados todavia. El hook compact-bash aun no se ha disparado o esta deshabilitado.\n');
+    return;
+  }
+
+  const sorted = Object.entries(s.byRule).sort((a, b) => b[1].saved - a[1].saved);
+
+  console.log(`\n  compact-bash stats (${s.totalRewrites} rewrites en total)\n`);
+  for (const [id, data] of sorted) {
+    const kTokens = (data.saved / 1000).toFixed(1);
+    console.log(
+      `    ${id.padEnd(18)} ${String(data.count).padStart(6)} rewrites   ~${kTokens.padStart(7)}k tokens estimados`,
+    );
+  }
+  const totalK = (s.totalSaved / 1000).toFixed(1);
+  const costUsd = ((s.totalSaved / 1_000_000) * 3).toFixed(2);
+  console.log(`    ${'-'.repeat(62)}`);
+  console.log(
+    `    ${'Total'.padEnd(18)} ${String(s.totalRewrites).padStart(6)} rewrites   ~${totalK.padStart(7)}k tokens (~$${costUsd} USD, Sonnet input)`,
+  );
+  console.log(`\n  Log: ${compactTelemetry.LOG_PATH}`);
+  if (compactTelemetry.isDisabled()) {
+    console.log('  Estado: DESHABILITADO (no se registran nuevos rewrites)');
+  }
+  console.log('');
+}
+
 function help() {
   console.log(`
   refacil-sdd-ai — Metodologia SDD-AI con OpenSpec
@@ -410,8 +569,14 @@ function help() {
   Comandos:
     init          Instala skills en .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
     update        Re-copia skills (para actualizar a nueva version del paquete)
-    check-update  Verifica si hay una version mas reciente en npm
+    check-update  Verifica si hay una version mas reciente en npm y sincroniza compact-guidance en AGENTS.md
     check-review  Verifica que el review se haya completado (usado por hook PreToolUse)
+    compact-bash  Reescribe comandos Bash bare para reducir tokens (usado por hook PreToolUse)
+    compact       Subcomandos del hook compact-bash:
+                    compact stats      - Estadisticas de rewrites y ahorro estimado
+                    compact disable    - Desactiva el rewrite temporalmente
+                    compact enable     - Re-activa el rewrite
+                    compact clear-log  - Borra el log historico
     clean         Elimina skills y remueve hooks SDD-AI de .claude/settings.json
     help          Muestra esta ayuda
 
@@ -423,7 +588,7 @@ function help() {
 
   Requisitos:
     - Node.js >= 20.19.0 (requerido por OpenSpec)
-    - Claude Code o Cursor instalado
+    - Claude Code >= 2.1.89 (requerido por compact-bash para rewrite silencioso) o Cursor
   `);
 }
 
@@ -444,6 +609,12 @@ switch (command) {
   case 'check-review':
     checkReview();
     break;
+  case 'compact-bash':
+    compactBash.run();
+    break;
+  case 'compact':
+    handleCompactSubcommand(process.argv[3]);
+    break;
   case 'clean':
     clean();
     break;

package/lib/compact/bash.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const { findRule } = require('./rules');
+const telemetry = require('./telemetry');
+
+function run() {
+  let input;
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (!stdin.trim()) return;
+    input = JSON.parse(stdin);
+  } catch (_) {
+    return;
+  }
+
+  if (input.tool_name !== 'Bash') return;
+  if (telemetry.isDisabled()) return;
+
+  const origCommand = input.tool_input && input.tool_input.command;
+  if (typeof origCommand !== 'string') return;
+
+  const rule = findRule(origCommand);
+  if (!rule) return;
+
+  let newCommand;
+  try {
+    newCommand = rule.rewrite(origCommand);
+  } catch (_) {
+    return;
+  }
+
+  if (!newCommand || newCommand === origCommand) return;
+
+  telemetry.logRewrite(rule.id, rule.savedTokensEst);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      permissionDecisionReason: `compact-bash: ${rule.reason}`,
+      updatedInput: {
+        ...input.tool_input,
+        command: newCommand,
+      },
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+module.exports = { run };