refacil-sdd-ai 5.2.3 → 5.3.1

package/lib/installer.js

@@ -3,7 +3,17 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { globalClaudeDir, globalCursorDir, globalOpenCodeDir, globalCodexDir, globalSddVersionPath } = require('./global-paths');
+const {
+  globalClaudeDir,
+  globalCursorDir,
+  globalOpenCodeDir,
+  globalCodexDir,
+  globalSddVersionPath,
+  validateOpenCodeConfigDir,
+} = require('./global-paths');
+const { migrateOpenCodeLegacyArtifacts } = require('./opencode-migrate');
+
+const DEFAULT_IDE_DIRS = ['claude', 'cursor', 'opencode', 'codex'];
 const { convertAgentToToml } = require('./toml-converter');
 
 const SKILLS = [
@@ -19,6 +29,8 @@ const SKILLS = [
   'archive',
   'bug',
   'up-code',
+  'autopilot',
+  'read-spec',
   'join',
   'say',
   'ask',
@@ -26,6 +38,8 @@ const SKILLS = [
   'inbox',
   'attend',
   'update',
+  'stats',
+  'status',
 ];
 
 const AGENTS = [
@@ -70,12 +84,17 @@ function copyDir(src, dest) {
  * Install skills into global IDE directories.
  * @param {string} packageRoot - path to the refacil-sdd-ai package
  * @param {string} homeDir - user home directory (injectable for testing; default: os.homedir())
- * @param {string[]} [ideDirs] - which IDEs to install for (['claude','cursor','opencode'])
+ * @param {string[]} [ideDirs] - which IDEs to install for (default: all four IDEs)
  * @returns {number} number of skills installed
  */
 function installSkills(packageRoot, homeDir, ideDirs) {
   const resolvedHome = homeDir || os.homedir();
-  const dirs = ideDirs || ['claude', 'cursor', 'opencode'];
+  const dirs = ideDirs || DEFAULT_IDE_DIRS;
+  const installOpenCode =
+    (dirs.includes('opencode') || dirs.includes('.opencode')) && validateOpenCodeConfigDir();
+  if (installOpenCode) {
+    migrateOpenCodeLegacyArtifacts(resolvedHome);
+  }
   let installed = 0;
 
   for (const skill of SKILLS) {
@@ -88,7 +107,7 @@ function installSkills(packageRoot, homeDir, ideDirs) {
     if (dirs.includes('cursor') || dirs.includes('.cursor')) {
       copyDir(srcDir, path.join(globalCursorDir(resolvedHome), 'skills', `refacil-${skill}`));
     }
-    if (dirs.includes('opencode') || dirs.includes('.opencode')) {
+    if (installOpenCode) {
       // OpenCode: byte-for-byte copy (same as Claude Code — no transformation needed)
       copyDir(srcDir, path.join(globalOpenCodeDir(resolvedHome), 'skills', `refacil-${skill}`));
     }
@@ -129,7 +148,17 @@ function installOpenCodeJson(projectRoot) {
     merged['$schema'] = sddKeys['$schema'];
   }
 
-  fs.writeFileSync(ocJsonPath, JSON.stringify(merged, null, 2) + '\n');
+  // CA-16: idempotency guard — skip write if serialized content is identical to what is on disk.
+  const proposed = JSON.stringify(merged, null, 2) + '\n';
+  if (fs.existsSync(ocJsonPath)) {
+    try {
+      const onDisk = fs.readFileSync(ocJsonPath, 'utf8');
+      if (onDisk === proposed) return;
+    } catch (_) {
+      // CR-02 pattern: if read fails, proceed to write.
+    }
+  }
+  fs.writeFileSync(ocJsonPath, proposed);
 }
 
 // Claude Code: tools allowlist granular, model: sonnet|opus|haiku
@@ -239,12 +268,17 @@ function transformFrontmatterForOpenCode(content) {
  * Install agents into global IDE directories.
  * @param {string} packageRoot - path to the refacil-sdd-ai package
  * @param {string} homeDir - user home directory (injectable for testing; default: os.homedir())
- * @param {string[]} [ideDirs] - which IDEs to install for (['claude','cursor','opencode'])
+ * @param {string[]} [ideDirs] - which IDEs to install for (default: all four IDEs)
  * @returns {number} number of agents installed
  */
 function installAgents(packageRoot, homeDir, ideDirs) {
   const resolvedHome = homeDir || os.homedir();
-  const dirs = ideDirs || ['claude', 'cursor', 'opencode'];
+  const dirs = ideDirs || DEFAULT_IDE_DIRS;
+  const installOpenCode =
+    (dirs.includes('opencode') || dirs.includes('.opencode')) && validateOpenCodeConfigDir();
+  if (installOpenCode) {
+    migrateOpenCodeLegacyArtifacts(resolvedHome);
+  }
 
   const claudeAgentsDir = path.join(globalClaudeDir(resolvedHome), 'agents');
   const cursorAgentsDir = path.join(globalCursorDir(resolvedHome), 'agents');
@@ -253,7 +287,7 @@ function installAgents(packageRoot, homeDir, ideDirs) {
 
   if (dirs.includes('claude') || dirs.includes('.claude')) fs.mkdirSync(claudeAgentsDir, { recursive: true });
   if (dirs.includes('cursor') || dirs.includes('.cursor')) fs.mkdirSync(cursorAgentsDir, { recursive: true });
-  if (dirs.includes('opencode') || dirs.includes('.opencode')) fs.mkdirSync(openCodeAgentsDir, { recursive: true });
+  if (installOpenCode) fs.mkdirSync(openCodeAgentsDir, { recursive: true });
   if (dirs.includes('codex') || dirs.includes('.codex')) fs.mkdirSync(codexAgentsDir, { recursive: true });
 
   let installed = 0;
@@ -273,7 +307,7 @@ function installAgents(packageRoot, homeDir, ideDirs) {
         transformFrontmatterForCursor(content),
       );
     }
-    if (dirs.includes('opencode') || dirs.includes('.opencode')) {
+    if (installOpenCode) {
       fs.writeFileSync(
         path.join(openCodeAgentsDir, `refacil-${agent}.md`),
         transformFrontmatterForOpenCode(content),
@@ -365,10 +399,12 @@ function removeProjectLevelArtifacts(projectRoot) {
     } catch (_) {}
   }
 
-  // Remove .opencode/plugins/refacil-hooks.js if present
-  const ocPlugin = path.join(projectRoot, '.opencode', 'plugins', 'refacil-hooks.js');
-  if (fs.existsSync(ocPlugin)) {
-    try { fs.unlinkSync(ocPlugin); removed++; } catch (_) {}
+  // Remove .opencode/plugins/refacil-hooks.js and refacil-check-review.js if present
+  for (const name of ['refacil-hooks.js', 'refacil-check-review.js']) {
+    const ocPlugin = path.join(projectRoot, '.opencode', 'plugins', name);
+    if (fs.existsSync(ocPlugin)) {
+      try { fs.unlinkSync(ocPlugin); removed++; } catch (_) {}
+    }
   }
   // Remove .opencode/plugins/ if now empty
   const ocPluginsDir = path.join(projectRoot, '.opencode', 'plugins');
@@ -412,10 +448,12 @@ function removeOpenCodeArtifacts(projectRoot) {
     } catch (_) {}
   }
 
-  // Remove .opencode/plugins/refacil-hooks.js
-  const pluginFile = path.join(projectRoot, '.opencode', 'plugins', 'refacil-hooks.js');
-  if (fs.existsSync(pluginFile)) {
-    try { fs.unlinkSync(pluginFile); } catch (_) {}
+  // Remove .opencode/plugins/refacil-hooks.js and refacil-check-review.js
+  for (const name of ['refacil-hooks.js', 'refacil-check-review.js']) {
+    const pluginFile = path.join(projectRoot, '.opencode', 'plugins', name);
+    if (fs.existsSync(pluginFile)) {
+      try { fs.unlinkSync(pluginFile); } catch (_) {}
+    }
   }
 
   // Revert SDD-AI keys from .opencode/opencode.json (currently only $schema key, leave file if other keys remain)
@@ -439,6 +477,23 @@ function writeGuideFile(destPath, header, label) {
     `# ${header}\n\n` +
     'Contexto completo del proyecto: ver `AGENTS.md`.\n' +
     'Si no existe, ejecuta `/refacil:setup`.\n';
+
+  // Idempotency guard: skip write if normalized content is identical (CA-01, CA-02, CR-05).
+  // Normalization is comparison-only — the content written to disk is never altered.
+  if (fs.existsSync(destPath)) {
+    try {
+      const existing = fs.readFileSync(destPath, 'utf8');
+      const normalizedExisting = existing.replace(/\r\n/g, '\n');
+      const normalizedNew = content.replace(/\r\n/g, '\n');
+      if (normalizedExisting === normalizedNew) {
+        // Content is identical (or differs only in CRLF vs LF) — skip write.
+        return false;
+      }
+    } catch (_) {
+      // CR-02: if read fails, treat as non-identical and proceed to write.
+    }
+  }
+
   fs.writeFileSync(destPath, content);
   console.log(`  ${label} generado.`);
   return true;
@@ -573,12 +628,12 @@ function removeSkills(projectRoot) {
 /**
  * Remove skills from global IDE directories.
  * @param {string} homeDir - user home directory (injectable for testing)
- * @param {string[]} [ideDirs] - which IDEs to remove from (['claude','cursor','opencode'])
+ * @param {string[]} [ideDirs] - which IDEs to remove from (default: all four IDEs)
  * @returns {number} number of skill directories removed
  */
 function removeGlobalSkills(homeDir, ideDirs) {
   const resolvedHome = homeDir || os.homedir();
-  const dirs = ideDirs || ['claude', 'cursor', 'opencode'];
+  const dirs = ideDirs || DEFAULT_IDE_DIRS;
   let removed = 0;
 
   for (const skill of SKILLS) {
@@ -610,6 +665,42 @@ function removeGlobalSkills(homeDir, ideDirs) {
   return removed;
 }
 
+/**
+ * Remove all refacil-* OpenCode artifacts from the global OpenCode config directory.
+ * Tolerant: each removal is wrapped in try/catch.
+ * @param {string} [homeDir] - user home directory (injectable for testing)
+ */
+function removeOpenCodeGlobalArtifacts(homeDir) {
+  const resolvedHome = homeDir || os.homedir();
+  const ocDir = globalOpenCodeDir(resolvedHome);
+
+  for (const skill of SKILLS) {
+    const skillDir = path.join(ocDir, 'skills', `refacil-${skill}`);
+    if (fs.existsSync(skillDir)) {
+      try { fs.rmSync(skillDir, { recursive: true }); } catch (_) {}
+    }
+  }
+
+  const agentsDir = path.join(ocDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    try {
+      const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.startsWith('refacil-') && entry.name.endsWith('.md')) {
+          try { fs.unlinkSync(path.join(agentsDir, entry.name)); } catch (_) {}
+        }
+      }
+    } catch (_) {}
+  }
+
+  for (const name of ['refacil-hooks.js', 'refacil-check-review.js', 'rules.js']) {
+    const pluginFile = path.join(ocDir, 'plugins', name);
+    if (fs.existsSync(pluginFile)) {
+      try { fs.unlinkSync(pluginFile); } catch (_) {}
+    }
+  }
+}
+
 /**
  * Remove all refacil-* Codex artifacts from the global ~/.codex directory.
  * Tolerant: each removal is wrapped in try/catch.
@@ -730,6 +821,89 @@ function checkNodeVersion() {
   return true;
 }
 
+/**
+ * Prompt the user for their preferred CodeGraph integration mode.
+ * Skippable with --yes / --defaults flags or when stdout is not a TTY.
+ * Persists the answer via writeConfigValue from lib/config.js.
+ *
+ * @param {string} homeDir - user home directory
+ * @returns {Promise<void>}
+ */
+async function promptCodegraphMode(homeDir) {
+  const { writeConfigValue, CODEGRAPH_MODES, DEFAULT_CODEGRAPH_MODE } = require('./config');
+  const resolvedHome = homeDir || os.homedir();
+
+  const skipFlags = ['--yes', '--defaults'];
+  if (skipFlags.some((f) => process.argv.includes(f)) || !process.stdout.isTTY) {
+    writeConfigValue('codegraphMode', DEFAULT_CODEGRAPH_MODE, resolvedHome);
+    if (DEFAULT_CODEGRAPH_MODE !== 'disabled') {
+      try {
+        const cg = require('./codegraph');
+        const { readSelectedIDEs } = require('./global-paths');
+        cg.registerMcp(readSelectedIDEs(resolvedHome) || ['.claude', '.cursor', '.opencode', '.codex'], resolvedHome);
+        if (DEFAULT_CODEGRAPH_MODE === 'enabled' && cg.isInstalled()) {
+          cg.init(require('path').resolve('.'));
+        }
+      } catch (_) {}
+    }
+    return;
+  }
+
+  console.log('\n  CodeGraph integration (optional — https://github.com/colbymchenry/codegraph)');
+  console.log('  When enabled, exploratory sub-agents (investigate, propose, debug) will');
+  console.log('  prefer CodeGraph symbol queries over raw file reads, reducing token usage ~71%.');
+  console.log(`  Mode options: ${CODEGRAPH_MODES.join(' | ')} (default: ${DEFAULT_CODEGRAPH_MODE})\n`);
+
+  let selectedMode;
+
+  try {
+    const clack = require('@clack/prompts');
+    const result = await clack.select({
+      message: 'CodeGraph integration mode:',
+      options: [
+        { value: 'enabled', label: 'enabled — auto-index every repo on setup (recommended)' },
+        { value: 'per-repo', label: 'per-repo — ask once per project (set via /refacil:setup)' },
+        { value: 'disabled', label: 'disabled — never use CodeGraph' },
+      ],
+      initialValue: DEFAULT_CODEGRAPH_MODE,
+    });
+    if (clack.isCancel(result)) {
+      console.log('  CodeGraph config prompt cancelled. Using default (enabled).\n');
+      selectedMode = DEFAULT_CODEGRAPH_MODE;
+    } else {
+      selectedMode = result;
+    }
+  } catch (_) {
+    // @clack/prompts not available — use inline readline fallback
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+    const answer = await ask(
+      `  CodeGraph mode [${DEFAULT_CODEGRAPH_MODE}] (${CODEGRAPH_MODES.join('/')}): `,
+    );
+    rl.close();
+    const trimmed = answer.trim().toLowerCase();
+    selectedMode = CODEGRAPH_MODES.includes(trimmed) ? trimmed : DEFAULT_CODEGRAPH_MODE;
+  }
+
+  writeConfigValue('codegraphMode', selectedMode, resolvedHome);
+  if (selectedMode !== 'disabled') {
+    try {
+      const cg = require('./codegraph');
+      const { readSelectedIDEs } = require('./global-paths');
+      cg.registerMcp(readSelectedIDEs(resolvedHome) || ['.claude', '.cursor', '.opencode', '.codex'], resolvedHome);
+      // Auto-index current repo in background when mode is enabled and CLI is installed
+      if (selectedMode === 'enabled' && cg.isInstalled()) {
+        const projectRoot = require('path').resolve('.');
+        cg.init(projectRoot);
+        console.log('  CodeGraph: indexing current repo in background (~30s).');
+      }
+    } catch (_) {}
+  }
+  console.log(`  CodeGraph mode set to: ${selectedMode}\n`);
+}
+
 module.exports = {
   SKILLS,
   AGENTS,
@@ -741,10 +915,12 @@ module.exports = {
   transformFrontmatterForOpenCode,
   installAgents,
   removeOpenCodeArtifacts,
+  removeOpenCodeGlobalArtifacts,
   removeCodexArtifacts,
   removeProjectLevelArtifacts,
   createClaudeMd,
   createCursorRules,
+  writeGuideFile,
   readRepoVersion,
   writeRepoVersion,
   readGlobalVersion,
@@ -755,4 +931,5 @@ module.exports = {
   removeOpenspecLegacyAssets,
   checkClaudeCodeVersion,
   checkNodeVersion,
+  promptCodegraphMode,
 };

package/lib/kapso.js

@@ -0,0 +1,308 @@
+'use strict';
+
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+const os = require('os');
+const readline = require('readline/promises');
+
+const KAPSO_ENV_DIR = path.join(os.homedir(), '.refacil-sdd-ai');
+const KAPSO_ENV_FILE = path.join(KAPSO_ENV_DIR, 'kapso.env');
+const KAPSO_LOG_FILE = path.join(KAPSO_ENV_DIR, 'autopilot.log');
+const KAPSO_API_BASE = 'https://api.kapso.ai/meta/whatsapp/v24.0';
+
+const PHONE_REGEX = /^\+\d{7,15}$/;
+
+// ─── credentials ─────────────────────────────────────────────────────────────
+
+function readCredentials() {
+  if (!fs.existsSync(KAPSO_ENV_FILE)) return null;
+  const creds = {};
+  for (const line of fs.readFileSync(KAPSO_ENV_FILE, 'utf8').split('\n')) {
+    const m = line.match(/^([^#][^=]+)=(.+)$/);
+    if (m) creds[m[1].trim()] = m[2].trim();
+  }
+  const { KAPSO_API_KEY, KAPSO_PHONE_NUMBER_ID, NOTIFY_PHONE } = creds;
+  if (!KAPSO_API_KEY || !KAPSO_PHONE_NUMBER_ID || !NOTIFY_PHONE) return null;
+  return { apiKey: KAPSO_API_KEY, phoneNumberId: KAPSO_PHONE_NUMBER_ID, notifyPhone: NOTIFY_PHONE };
+}
+
+// ─── http ─────────────────────────────────────────────────────────────────────
+
+function postMessage(creds, bodyText) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify({
+      messaging_product: 'whatsapp',
+      recipient_type: 'individual',
+      to: creds.notifyPhone,
+      type: 'text',
+      text: { body: bodyText },
+    });
+
+    const urlPath = `${KAPSO_API_BASE}/${creds.phoneNumberId}/messages`;
+    const parsed = new URL(urlPath);
+
+    const req = https.request(
+      {
+        hostname: parsed.hostname,
+        path: parsed.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': creds.apiKey,
+          'Content-Length': Buffer.byteLength(payload),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => resolve({ status: res.statusCode, body: data }));
+      },
+    );
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// ─── validation ────────────────────────────────────────────────────────────────
+
+// Unfilled template token left in the command, e.g. "<changeName>" or "<repoSlug>".
+const PLACEHOLDER_REGEX = /<[^>]+>/;
+
+function isBlankOrPlaceholder(value) {
+  if (value === null || value === undefined) return true;
+  const s = String(value).trim();
+  if (s === '') return true;
+  if (PLACEHOLDER_REGEX.test(s)) return true;
+  return false;
+}
+
+// Returns a list of human-readable problems with the notify payload.
+// Empty list ⇒ the payload is complete enough to send.
+//
+// This is the guard against the autopilot failure mode where the skill fires
+// `kapso notify` once with unfilled <placeholders>/empty flags (sending a junk
+// WhatsApp message) and again with the real values. We reject the incomplete
+// call so it never reaches postMessage().
+function validateNotifyOpts(type, opts) {
+  const problems = [];
+  const required =
+    type === 'success'
+      ? ['repo', 'change', 'branch', 'tasks']
+      : ['repo', 'change', 'branch', 'phase'];
+
+  for (const field of required) {
+    if (isBlankOrPlaceholder(opts[field])) {
+      problems.push(`--${field} faltante, vacío o sin rellenar`);
+    }
+  }
+
+  // tasks must look like "done/total" (e.g. "5/5"), not a placeholder or prose.
+  if (
+    type === 'success' &&
+    !isBlankOrPlaceholder(opts.tasks) &&
+    !/^\d+\/\d+$/.test(String(opts.tasks).trim())
+  ) {
+    problems.push(`--tasks con formato inválido (esperado "done/total"): "${opts.tasks}"`);
+  }
+
+  return problems;
+}
+
+// ─── log ─────────────────────────────────────────────────────────────────────
+
+function appendLog(msg) {
+  try {
+    fs.mkdirSync(KAPSO_ENV_DIR, { recursive: true });
+    fs.appendFileSync(KAPSO_LOG_FILE, `${new Date().toISOString()} ${msg}\n`, 'utf8');
+  } catch (_) {}
+}
+
+// ─── public commands ──────────────────────────────────────────────────────────
+
+async function setup() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    console.log('\n  Kapso setup — WhatsApp notification credentials\n');
+
+    let apiKey = '';
+    while (!apiKey.trim()) {
+      apiKey = await rl.question('  KAPSO_API_KEY: ');
+      if (!apiKey.trim()) console.log('  KAPSO_API_KEY cannot be empty. Try again.');
+    }
+
+    let phoneNumberId = '';
+    while (!phoneNumberId.trim()) {
+      phoneNumberId = await rl.question('  KAPSO_PHONE_NUMBER_ID: ');
+      if (!phoneNumberId.trim()) console.log('  KAPSO_PHONE_NUMBER_ID cannot be empty. Try again.');
+    }
+
+    let notifyPhone = '';
+    while (true) {
+      notifyPhone = await rl.question(
+        "  NOTIFY_PHONE (E.164 format, e.g. +5731XXXXXXXX, or 'cancelar' to abort): ",
+      );
+      if (notifyPhone.trim().toLowerCase() === 'cancelar') {
+        console.log('\n  Setup cancelled.\n');
+        rl.close();
+        return;
+      }
+      if (PHONE_REGEX.test(notifyPhone.trim())) break;
+      console.log('  Invalid format. Must start with + followed by 7-15 digits (E.164). Try again.');
+    }
+
+    fs.mkdirSync(KAPSO_ENV_DIR, { recursive: true });
+
+    const content =
+      [`KAPSO_API_KEY=${apiKey.trim()}`, `KAPSO_PHONE_NUMBER_ID=${phoneNumberId.trim()}`, `NOTIFY_PHONE=${notifyPhone.trim()}`].join('\n') +
+      '\n';
+
+    fs.writeFileSync(KAPSO_ENV_FILE, content, { encoding: 'utf8' });
+
+    try {
+      fs.chmodSync(KAPSO_ENV_FILE, 0o600);
+    } catch (_) {}
+
+    console.log('\n  ✅ Kapso configurado en ~/.refacil-sdd-ai/kapso.env\n');
+  } finally {
+    rl.close();
+  }
+}
+
+// kapso preflight
+// Returns credential status and a 24h window notice (sync, always exits 0).
+// sync — no network I/O
+function preflight() {
+  const creds = readCredentials();
+  if (!creds) {
+    return { kapsoEnabled: false };
+  }
+  const preflightMessage =
+    'WhatsApp solo entrega mensajes de texto libre dentro de las **24 horas** de tu último mensaje **entrante** al número de notificación. ' +
+    'Si han pasado más de 24 horas desde que enviaste un mensaje a ese número, envía cualquier mensaje (p.ej. `ok`) antes de una ejecución larga. ' +
+    'Sin eso, el pipeline igual corre pero la alerta final de WhatsApp puede no llegar.';
+  return { kapsoEnabled: true, notifyPhone: creds.notifyPhone, preflightMessage };
+}
+
+// kapso notify success --repo <slug> --change <name> --branch <branch>
+//   --tasks <done>/<total> --duration <min>
+//   [--pr <url>] [--improvements <n>] [--apply <n>] [--test <n>] [--review <n>]
+//   [--warnings "<w1>|<w2>"]
+//
+// kapso notify failure --repo <slug> --change <name> --branch <branch>
+//   --phase <phase> --last-commit "<commit>" --error "<summary>"
+async function notify(type, opts) {
+  if (type !== 'success' && type !== 'failure') {
+    console.error(`  Unknown notify type: "${type}". Use "success" or "failure".`);
+    process.exit(1);
+  }
+
+  // Reject incomplete/placeholder payloads BEFORE doing anything else so a junk
+  // notification is never sent. Throwing surfaces a clear, actionable error to
+  // the caller (autopilot) without ever hitting the WhatsApp API.
+  const problems = validateNotifyOpts(type, opts);
+  if (problems.length > 0) {
+    appendLog(`kapso notify ${type} REJECTED (datos inválidos): ${problems.join('; ')}`);
+    throw new Error(
+      `kapso notify ${type}: datos inválidos o incompletos — ${problems.join('; ')}. ` +
+        'No se envió la notificación. Reintenta con todos los flags requeridos rellenados con valores reales.',
+    );
+  }
+
+  const creds = readCredentials();
+  if (!creds) {
+    appendLog('kapso notify skipped: no credentials');
+    return;
+  }
+
+  let message;
+
+  if (type === 'success') {
+    const {
+      repo = '',
+      change = '',
+      branch = '',
+      tasks = '0/0',
+      duration = '0',
+      pr = null,
+      apply = 0,
+      test = 0,
+      review = 0,
+      warnings = '',
+    } = opts;
+
+    const totalImprovements = Number(apply) + Number(test) + Number(review);
+    const warningList = warnings ? warnings.split('|').map((w) => w.trim()).filter(Boolean) : [];
+
+    let msg = [
+      '✅ SDD Autopilot completado',
+      '',
+      `Repo: ${repo}`,
+      `Change: ${change}`,
+      `Branch: ${branch}`,
+      `Tareas: ${tasks}`,
+      'Tests: pass',
+      'Review: ✓',
+      `Mejoras aplicadas: ${totalImprovements} (apply: ${apply}, test: ${test}, review: ${review})`,
+      `Duración: ${duration} min`,
+    ].join('\n');
+
+    if (warningList.length > 0) {
+      msg += `\n\n⚠️ Warnings (${warningList.length}):\n` + warningList.slice(0, 3).join('\n');
+    }
+
+    msg += `\n\nPR: ${pr || 'sin PR (solo push)'}`;
+    message = msg;
+  } else if (type === 'failure') {
+    const {
+      repo = '',
+      change = '',
+      branch = '',
+      phase = '',
+      lastCommit = '',
+      error = '',
+    } = opts;
+
+    message = [
+      '❌ SDD Autopilot falló',
+      '',
+      `Repo: ${repo}`,
+      `Change: ${change}`,
+      `Fase fallida: ${phase}`,
+      `Branch: ${branch}`,
+      `Último commit: ${lastCommit}`,
+      '',
+      'Detalle:',
+      error,
+      '',
+      'El árbol de trabajo quedó en su estado actual para revisión.',
+    ].join('\n');
+  }
+
+  try {
+    const result = await postMessage(creds, message);
+    if (result.status >= 200 && result.status < 300) {
+      appendLog(`kapso notify ${type} sent OK`);
+      console.log(`  ✅ Kapso: ${type} notification sent`);
+    } else {
+      appendLog(`kapso notify ${type} FAILED (HTTP ${result.status}): ${result.body}`);
+      console.warn(`  ⚠️  Kapso API error (HTTP ${result.status}): ${result.body}`);
+    }
+  } catch (err) {
+    appendLog(`kapso notify ${type} NETWORK ERROR: ${err.message}`);
+    console.warn(`  ⚠️  Kapso network error: ${err.message}`);
+  }
+}
+
+module.exports = {
+  setup,
+  preflight,
+  notify,
+  readCredentials,
+  validateNotifyOpts,
+  isBlankOrPlaceholder,
+  PHONE_REGEX,
+};

package/lib/methodology-migration-pending.js

@@ -95,6 +95,19 @@ function methodologyMigrationPending(root) {
     reasons.push(`commands opsx sobrantes: ${extraOpsx.join(', ')}`);
   }
 
+  // CodeGraph: CLI not installed when user has opted in (enabled or per-repo)
+  try {
+    const { loadBranchConfigWithSources } = require('./config');
+    const { isInstalled: cgIsInstalled } = require('./codegraph');
+    const cfgInfo = loadBranchConfigWithSources(root);
+    const cgMode = cfgInfo.codegraphMode;
+    if ((cgMode === 'enabled' || cgMode === 'per-repo') && !cgIsInstalled()) {
+      reasons.push(`CodeGraph CLI no instalado (modo: ${cgMode}) — ejecuta /refacil:update para instalarlo`);
+    }
+  } catch (_) {
+    // Tolerant — CodeGraph check must not break migration detection
+  }
+
   return { pending: reasons.length > 0, reasons };
 }