nexakit 0.1.0 → 0.2.0

package/src/project-signals.js

@@ -0,0 +1,339 @@
+// Detects the technologies of a project from its root and its first-level subfolders: from the manifests, or from
+// the README keywords in a folder without manifests. Each signal keeps where it came from, so a suggestion can
+// say why. Read-only and bounded.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MAX_MANIFEST_BYTES = 512 * 1024;
+const MAX_README_BYTES = 64 * 1024;
+const MAX_SUBFOLDERS = 20;
+
+export const SIGNAL_LABELS = Object.freeze({
+  nodejs: 'Node.js',
+  typescript: 'TypeScript',
+  'mcp-sdk': 'MCP SDK',
+  react: 'React',
+  nextjs: 'Next.js',
+  tailwindcss: 'Tailwind CSS',
+  astro: 'Astro',
+  vue: 'Vue',
+  svelte: 'Svelte',
+  supabase: 'Supabase',
+  postgres: 'PostgreSQL',
+  express: 'Express',
+  fastify: 'Fastify',
+  hono: 'Hono',
+  playwright: 'Playwright',
+  vitest: 'Vitest',
+  django: 'Django',
+  fastapi: 'FastAPI',
+  flask: 'Flask',
+  tauri: 'Tauri',
+  python: 'Python',
+  rust: 'Rust',
+  'rest-api': 'API REST'
+});
+
+export const PACKAGE_TO_SIGNAL = Object.freeze({
+  '@modelcontextprotocol/sdk': 'mcp-sdk',
+  '@modelcontextprotocol/server': 'mcp-sdk',
+  '@modelcontextprotocol/client': 'mcp-sdk',
+  fastmcp: 'mcp-sdk',
+  next: 'nextjs',
+  react: 'react',
+  'react-dom': 'react',
+  tailwindcss: 'tailwindcss',
+  '@tailwindcss/postcss': 'tailwindcss',
+  '@tailwindcss/vite': 'tailwindcss',
+  typescript: 'typescript',
+  astro: 'astro',
+  vue: 'vue',
+  nuxt: 'vue',
+  svelte: 'svelte',
+  '@sveltejs/kit': 'svelte',
+  '@supabase/supabase-js': 'supabase',
+  '@supabase/ssr': 'supabase',
+  pg: 'postgres',
+  postgres: 'postgres',
+  '@neondatabase/serverless': 'postgres',
+  'drizzle-orm': 'postgres',
+  '@prisma/client': 'postgres',
+  express: 'express',
+  fastify: 'fastify',
+  hono: 'hono',
+  '@hono/node-server': 'hono',
+  playwright: 'playwright',
+  '@playwright/test': 'playwright',
+  vitest: 'vitest',
+  '@tauri-apps/api': 'tauri',
+  '@tauri-apps/cli': 'tauri'
+});
+
+const PYTHON_PACKAGE_TO_SIGNALS = Object.freeze({
+  django: ['django'],
+  djangorestframework: ['django', 'rest-api'],
+  fastapi: ['fastapi'],
+  flask: ['flask']
+});
+
+const FRAMEWORK_CONFIG_HINTS = Object.freeze([
+  ['next.config.js', 'nextjs'],
+  ['next.config.mjs', 'nextjs'],
+  ['next.config.ts', 'nextjs'],
+  ['tailwind.config.js', 'tailwindcss'],
+  ['tailwind.config.ts', 'tailwindcss'],
+  ['astro.config.mjs', 'astro'],
+  ['svelte.config.js', 'svelte']
+]);
+
+const OUT_OF_COVERAGE_MANIFESTS = Object.freeze(['go.mod', 'composer.json', 'Gemfile']);
+// A folder with any of these is described by them; its README is read only when it has none. A README often lists
+// technologies it documents or talks about (nexakit's own README names every catalog technology) without using them.
+const PROJECT_MANIFESTS = Object.freeze(['package.json', 'tsconfig.json', 'requirements.txt', 'pyproject.toml', 'manage.py',
+  'Cargo.toml', 'tauri.conf.json', 'src-tauri/Cargo.toml', 'src-tauri/tauri.conf.json', ...OUT_OF_COVERAGE_MANIFESTS]);
+
+// README dictionary. Case-insensitive, whole words only: "Reactor", "vue-router" or "flask_utils" do not count,
+// "Express.js" does.
+const README_TERMS = Object.freeze([
+  [['React'], 'react'], [['Next.js'], 'nextjs'], [['Vue'], 'vue'], [['Svelte'], 'svelte'], [['Astro'], 'astro'],
+  [['TypeScript'], 'typescript'], [['Tailwind'], 'tailwindcss'], [['Django'], 'django'], [['FastAPI'], 'fastapi'],
+  [['Flask'], 'flask'], [['Express'], 'express'], [['Fastify'], 'fastify'], [['Hono'], 'hono'], [['Tauri'], 'tauri'],
+  [['Supabase'], 'supabase'], [['PostgreSQL'], 'postgres'], [['Playwright'], 'playwright'], [['MCP'], 'mcp-sdk'],
+  [['API REST', 'REST API', 'OpenAPI'], 'rest-api']
+].map(([terms, signal]) => {
+  const escaped = terms.map(term => term.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&').replace(/ /gu, '\\s+'));
+  return [new RegExp(`(?<![\\p{L}\\p{N}_.-])(?:${escaped.join('|')})(?![\\p{L}\\p{N}_-])`, 'iu'), signal];
+}));
+
+const lstatOrNull = target => fs.lstat(target).catch(err => {
+  if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return null;
+  throw err;
+});
+const isPlainFile = info => Boolean(info?.isFile() && !info.isSymbolicLink());
+
+async function readHead(file, maxBytes) {
+  const handle = await fs.open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+    return buffer.subarray(0, bytesRead).toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+
+// Folders Git ignores, asked to Git itself so every .gitignore rule (nested, negated, global) is respected.
+function gitIgnored(root, names) {
+  if (names.length === 0) return new Set();
+  const result = spawnSync('git', ['check-ignore', '-z', '--stdin'], {
+    cwd: root, input: names.map(name => `${name}/\0`).join(''), encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore']
+  });
+  if (result.error || (result.status !== 0 && result.status !== 1)) return new Set();
+  return new Set(result.stdout.split('\0').filter(Boolean).map(entry => entry.replace(/\/$/u, '')));
+}
+
+async function foldersToScan(root, git, limits) {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  let names = entries
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules' && !/[\n\0]/u.test(entry.name))
+    .map(entry => entry.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (git) {
+    const ignored = gitIgnored(root, names);
+    names = names.filter(name => !ignored.has(name));
+  }
+  if (names.length > MAX_SUBFOLDERS) limits.push(`Se revisaron ${MAX_SUBFOLDERS} de ${names.length} subcarpetas.`);
+  return ['.', ...names.slice(0, MAX_SUBFOLDERS)];
+}
+
+// Reads the TOML array that starts at `text[0]` ('['). Returns where it ends and the strings it holds directly or in
+// nested arrays, skipping comments and inline tables (`{ include-group = "dev" }` names a group, not a package).
+// Double-quoted strings honour backslash escapes; single-quoted ones are literal.
+function tomlArrayStrings(text) {
+  const strings = [];
+  let depth = 0, braces = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'") {
+      let value = '', j = i + 1;
+      for (; j < text.length && text[j] !== ch && text[j] !== '\n'; j++) {
+        if (ch === '"' && text[j] === '\\' && j + 1 < text.length) j++;
+        value += text[j];
+      }
+      if (braces === 0) strings.push(value);
+      i = j;
+    } else if (ch === '#') {
+      const newline = text.indexOf('\n', i);
+      if (newline < 0) break;
+      i = newline;
+    } else if (ch === '{') braces++;
+    else if (ch === '}') braces--;
+    else if (ch === '[') depth++;
+    else if (ch === ']' && --depth === 0) return { end: i, strings };
+  }
+  return { end: -1, strings: [] };
+}
+
+// Dependency names declared in a pyproject.toml, without a TOML parser: PEP 621 `[project] dependencies`,
+// `[project.optional-dependencies]` and `[dependency-groups]` arrays, and Poetry `[tool.poetry.*dependencies]` keys.
+// Metadata such as `keywords` or `description` is never read.
+function pyprojectDependencies(text) {
+  const names = new Set();
+  const nameOf = spec => spec.match(/^\s*([A-Za-z0-9._-]+)/u)?.[1].toLowerCase().replace(/_/gu, '-');
+  const lines = text.split(/\r?\n/u);
+  let table = '';
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const header = line.match(/^\s*(\[\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/u);
+    if (header) {
+      // Arrays of tables ([[…]]) never hold dependencies here; quoted parts stay quoted so they never match.
+      table = header[1] === '[[' ? null : header[2].replace(/\s+/gu, '');
+      continue;
+    }
+    const key = line.match(/^\s*([A-Za-z0-9._-]+|"[^"]*"|'[^']*')\s*=\s*(.*)$/u);
+    if (!key || table === null) continue;
+    const keyName = key[1].replace(/^["']|["']$/gu, '');
+    if (/^tool\.poetry(?:\.group\.[^.]+)?\.(?:dev-)?dependencies$/u.test(table)) {
+      const name = nameOf(keyName);
+      if (name) names.add(name);
+      continue;
+    }
+    const holdsArray = (table === 'project' && keyName === 'dependencies')
+      || table === 'project.optional-dependencies' || table === 'dependency-groups';
+    if (!holdsArray || !key[2].trimStart().startsWith('[')) continue;
+    const rest = [key[2].trimStart(), ...lines.slice(index + 1)].join('\n');
+    const { end, strings } = tomlArrayStrings(rest);
+    if (end < 0) continue;
+    for (const spec of strings) {
+      const name = nameOf(spec);
+      if (name) names.add(name);
+    }
+    index += rest.slice(0, end).split('\n').length - 1;
+  }
+  return names;
+}
+
+function pythonPackages(text, kind) {
+  const found = new Set();
+  if (kind === 'requirements') {
+    for (const raw of text.split(/\r?\n/u)) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#') || line.startsWith('-')) continue;
+      const name = line.match(/^[A-Za-z0-9._-]+/u)?.[0].toLowerCase().replace(/_/gu, '-');
+      if (name && PYTHON_PACKAGE_TO_SIGNALS[name]) found.add(name);
+    }
+  } else {
+    for (const name of pyprojectDependencies(text)) if (PYTHON_PACKAGE_TO_SIGNALS[name]) found.add(name);
+  }
+  return [...found].sort();
+}
+
+async function scanFolder(root, folder, add, limits, { nestedAllowed }) {
+  const dir = path.join(root, folder);
+  const shown = name => (folder === '.' ? name : `${folder}/${name}`);
+  // Nested manifests (src-tauri/…) are read only through a real folder that Git does not ignore: a link could
+  // lead out of the project.
+  const nestedDir = nestedAllowed ? lstatOrNull(path.join(dir, 'src-tauri')) : Promise.resolve(null);
+  const fileInfo = async name => {
+    if (name.includes('/')) {
+      const info = await nestedDir;
+      if (!info?.isDirectory() || info.isSymbolicLink()) return null;
+    }
+    return lstatOrNull(path.join(dir, name));
+  };
+  const readSmall = async name => {
+    const info = await fileInfo(name);
+    return isPlainFile(info) && info.size <= MAX_MANIFEST_BYTES ? fs.readFile(path.join(dir, name), 'utf8') : null;
+  };
+  const fromPackageJson = new Set();
+
+  const pkgInfo = await fileInfo('package.json');
+  if (pkgInfo) {
+    if (!isPlainFile(pkgInfo) || pkgInfo.size > MAX_MANIFEST_BYTES) {
+      limits.push(`${shown('package.json')} excede el límite o no es un archivo regular; no se inspeccionó.`);
+    } else {
+      let pkg = null;
+      try { pkg = JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf8')); } catch {
+        limits.push(`${shown('package.json')} no contiene JSON válido; no se dedujeron dependencias Node.`);
+      }
+      if (pkg && typeof pkg === 'object' && !Array.isArray(pkg)) {
+        add('nodejs', shown('package.json'), 'manifest');
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+          const deps = pkg[field];
+          if (!deps || typeof deps !== 'object' || Array.isArray(deps)) continue;
+          for (const dep of Object.keys(deps)) {
+            const signal = PACKAGE_TO_SIGNAL[dep];
+            if (signal) { add(signal, `${shown('package.json')} (${dep})`, 'manifest'); fromPackageJson.add(signal); }
+          }
+        }
+      }
+    }
+  }
+  if (isPlainFile(await fileInfo('tsconfig.json'))) add('typescript', shown('tsconfig.json'), 'manifest');
+  for (const [config, signal] of FRAMEWORK_CONFIG_HINTS) {
+    if (isPlainFile(await fileInfo(config)) && !fromPackageJson.has(signal)) {
+      limits.push(`Configuración observada sin dependencia confirmada en package.json: ${shown(config)}.`);
+    }
+  }
+
+  for (const [name, kind] of [['requirements.txt', 'requirements'], ['pyproject.toml', 'pyproject']]) {
+    const text = await readSmall(name);
+    if (text === null) continue;
+    add('python', shown(name), 'manifest');
+    for (const pkgName of pythonPackages(text, kind)) {
+      for (const signal of PYTHON_PACKAGE_TO_SIGNALS[pkgName]) add(signal, `${shown(name)} (${pkgName})`, 'manifest');
+    }
+  }
+  if (isPlainFile(await fileInfo('manage.py'))) {
+    add('python', shown('manage.py'), 'manifest');
+    add('django', shown('manage.py'), 'manifest');
+  }
+  for (const cargo of ['Cargo.toml', 'src-tauri/Cargo.toml']) {
+    const text = await readSmall(cargo);
+    if (text === null) continue;
+    add('rust', shown(cargo), 'manifest');
+    if (/^\s*tauri\s*=/mu.test(text)) add('tauri', `${shown(cargo)} (tauri)`, 'manifest');
+  }
+  for (const conf of ['tauri.conf.json', 'src-tauri/tauri.conf.json']) {
+    if (isPlainFile(await fileInfo(conf))) add('tauri', shown(conf), 'manifest');
+  }
+  for (const foreign of OUT_OF_COVERAGE_MANIFESTS) {
+    const info = await fileInfo(foreign);
+    if (info && !info.isSymbolicLink()) limits.push(`Stack fuera de cobertura automática observada: ${shown(foreign)}.`);
+  }
+
+  for (const manifest of PROJECT_MANIFESTS) if (await fileInfo(manifest)) return;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const readme = entries.filter(entry => entry.name.toLowerCase() === 'readme.md').map(entry => entry.name).sort()[0];
+  if (readme && isPlainFile(await fileInfo(readme))) {
+    const text = await readHead(path.join(dir, readme), MAX_README_BYTES);
+    for (const [pattern, signal] of README_TERMS) if (pattern.test(text)) add(signal, shown(readme), 'readme');
+  }
+}
+
+export async function detectSignals(root, { git = false } = {}) {
+  const limits = [];
+  const found = new Map();
+  const add = (id, source, kind) => {
+    const sources = found.get(id) ?? new Map();
+    if (!sources.has(source)) sources.set(source, kind);
+    found.set(id, sources);
+  };
+  const scanned = await foldersToScan(root, git, limits);
+  const nestedIgnored = git ? gitIgnored(root, scanned.map(folder => (folder === '.' ? 'src-tauri' : `${folder}/src-tauri`))) : new Set();
+  for (const folder of scanned) {
+    const nested = folder === '.' ? 'src-tauri' : `${folder}/src-tauri`;
+    await scanFolder(root, folder, add, limits, { nestedAllowed: !nestedIgnored.has(nested) });
+  }
+
+  const byPath = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  const signals = [...found.entries()]
+    .map(([id, sources]) => {
+      const of = kind => [...sources].filter(([, k]) => k === kind).map(([source]) => source).sort(byPath);
+      return { id, label: SIGNAL_LABELS[id] ?? id, sources: [...of('manifest'), ...of('readme')] };
+    })
+    .sort((a, b) => byPath(a.id, b.id));
+  if (signals.length === 0) limits.push('No se detectaron tecnologías en la raíz ni en sus subcarpetas.');
+  return { signals, limits, scanned };
+}

package/src/recommend-report.js

@@ -0,0 +1,77 @@
+// Plain-text report of `npx nexakit recommend`: what was detected and which skills fit, read-only.
+export function formatRecommendationReport(report) {
+  const lines = [
+    `Agent Toolkit · Recomendaciones para ${report.projectName}`,
+    `Raíz: ${report.projectRoot}${report.profile ? ` · Perfil: ${report.profile}` : ''}${report.client ? ` · Cliente: ${report.client}` : ''}`,
+    '',
+    'Tecnologías detectadas:'
+  ];
+
+  if (report.signals.length === 0) {
+    lines.push('  - Ninguna tecnología cubierta detectada automáticamente.');
+  } else {
+    for (const sig of report.signals) {
+      lines.push(`  ✓ ${sig.label} ← ${sig.sources.join(', ')}`);
+    }
+  }
+  for (const unm of report.unmatchedSignals) {
+    lines.push(`  • ${unm.label} (sin skill empaquetada aún)`);
+  }
+
+  lines.push('', `Recomendaciones con escenario probado (${report.recommended.length}):`);
+  if (report.recommended.length === 0) {
+    lines.push('  - Ninguna cumple todavía los 4 criterios de escenario probado para este filtro.');
+  } else {
+    for (const rec of report.recommended) {
+      lines.push(`  - ${rec.name} (${rec.license}) ← ${rec.reasons.join(', ')} [tarea: ${rec.taskClass}]`);
+    }
+  }
+
+  lines.push('', `Skills compatibles, no probadas (${report.candidates.length}):`);
+  if (report.candidates.length === 0) {
+    lines.push('  - Ninguna skill específica adicional coincide con las señales actuales.');
+  } else {
+    for (const cand of report.candidates) {
+      const state = cand.installed ? ` · en proyecto: ${cand.installed.integrity}` : '';
+      lines.push(`  - ${cand.name} (${cand.license}, SHA-256 ✓) ← ${cand.reasons.join(', ')}${state}`);
+      lines.push(`    Utilidad prevista: ${cand.summary}`);
+      lines.push('    No probada: nadie ha comprobado aún que mejore el trabajo con este agente.');
+      if (cand.reviewStatus === 'reviewed-with-observations') lines.push(`    Observaciones: ${cand.reviewNotes}`);
+      for (const reason of cand.pendingReasons) lines.push(`    Pendiente: ${reason}`);
+      if (cand.overlapsWith.length) lines.push(`    Comparte ámbito con: ${cand.overlapsWith.join(', ')}`);
+    }
+  }
+
+  if (report.optional && report.optional.length > 0) {
+    lines.push('', `Opcionales disponibles en el catálogo (${report.optional.length}):`);
+    for (const opt of report.optional) {
+      lines.push(`  - ${opt.name} (${opt.license}) ← perfil ${opt.profiles.join('/')} · no probada`);
+    }
+  }
+
+  if (report.externalCandidates?.length > 0) {
+    lines.push('', `Disponibles fuera del catálogo, se instalan aparte (${report.externalCandidates.length}):`);
+    for (const ref of report.externalCandidates) {
+      lines.push(`  - ${ref.name} ← ${ref.reasons.join(', ')} · no probada`);
+      lines.push(`    Utilidad prevista: ${ref.summary}`);
+      lines.push(`    Dónde: ${ref.sourceUrl}`);
+      lines.push(`    Nota: ${ref.statusNote}`);
+    }
+  }
+
+  if (report.addons.length > 0) {
+    lines.push('', 'Añadidos:');
+    for (const addon of report.addons) {
+      const kind = addon.optional ? 'opcional' : 'obligatorio';
+      lines.push(`  - ${addon.name} (${addon.versionReviewed}, ${addon.license}, ${kind}): ${addon.summary}`);
+    }
+  }
+
+  if (report.limits.length > 0) {
+    lines.push('', 'Límites de la inspección:');
+    for (const lim of report.limits) lines.push(`  ! ${lim}`);
+  }
+  lines.push('', 'SHA-256 comprueba integridad de archivos; no acredita utilidad ni calidad.');
+
+  return lines.join('\n') + '\n';
+}

package/src/review-instructions.js

@@ -0,0 +1,211 @@
+import { RECOMMENDED_REVIEWERS } from './review-policy.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+const START = '<!-- nexakit:review:start -->',
+  END = '<!-- nexakit:review:end -->';
+const BODY = `${START}
+# Método de trabajo de nexakit
+
+Para programar sigue el proceso de Superpowers (obligatorio): contexto y
+memoria, diseño y plan proporcionales, rama, pruebas, implementación,
+verificación y cierre con memoria. No hace falta un comando para empezar.
+Sobre sus skills mandan: modo tutor (la persona escribe el código, un paso
+verificable cada vez); no borrar código existente sin acuerdo aunque el TDD lo
+pida; commit, push, PR y memoria solo con autorización. Reutiliza un diseño o
+plan ya aprobado. Antes de un PR o de la revisión cruzada, quality-gate.
+
+Al terminar una tarea con cambios de código, pide automáticamente UNA revisión
+a otra IA, corrige los hallazgos verificables y resume el resultado. Máximo dos
+rondas por tarea; si queda algo grave, avisa. Solo documentos no dispara revisión.
+Si el usuario dice «sin revisión», omítela. /revisar pide una revisión adicional.
+No uses hooks ni subagentes para automatizarlo.
+
+Lee la skill revision-cruzada para el encargo y la ejecución de solo lectura.
+Usa elegir-modelo para nombres reales y esfuerzos. Nunca cambies solo el modelo.
+Usa la orden estable ~/.nexakit/nexakit (Windows: nexakit.cmd en esa carpeta).
+Un fallo del comando o informe vacío no significa «sin hallazgos».
+
+La IA revisora se elige en la terminal durante la sesión, nunca en el arranque
+ni en answers. Excluye siempre a la IA que programa. Antes de cada revisión ejecuta
+\`nexakit revision --disponibles --principal <IA que programa>\` (claude,
+codex o antigravity), sin llamadas a modelos. Ofrece las otras IA instaladas
+con certificación «sí» o «pendiente» (avisa si la primera vez se certifican);
+nunca las «no». Recomendadas: Claude→${RECOMMENDED_REVIEWERS.claude},
+Codex→${RECOMMENDED_REVIEWERS.codex} y Antigravity→${RECOMMENDED_REVIEWERS.antigravity}.
+Primera revisión con varias opciones: «¿A dónde mando la revisión?» marcando
+la recomendada (Claude: selector; Codex/Antigravity: pregunta normal). Una
+opción: úsala sin preguntar; ninguna: avisa que no hay revisión; si falta
+certificar un perfil, infórmalo. Después conserva la elección en la sesión y
+anuncia «Revisando con <IA>…». «que lo revise <IA>» cambia la elección. Si
+desaparece, usa la única alternativa o pregunta entre las restantes. No persistas
+la elección.
+
+Si una tarea larga queda a medias —pausa, cambio de IA, bloqueo o cierre— escribe o actualiza la nota de seguimiento con project-handoff; recomienda sesión nueva en los casos de project-handoff, y cierra el seguimiento al integrar con cerrar-memoria.
+${END}`;
+
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const proofPath = (home) => path.join(home, '.nexakit', 'review-instructions.json');
+const NAMES = { claude: 'CLAUDE.md', codex: 'AGENTS.md', antigravity: 'GEMINI.md' };
+function targets({ homeDirectory, environment = {}, codexHome, agents = Object.keys(NAMES) }) {
+  if (!homeDirectory || !path.isAbsolute(homeDirectory))
+    throw new Error('Se requiere homeDirectory absoluto.');
+  const folders = {
+    claude: path.join(homeDirectory, '.claude'),
+    codex: codexHome ?? environment.CODEX_HOME ?? path.join(homeDirectory, '.codex'),
+    antigravity: path.join(homeDirectory, '.gemini'),
+  };
+  return agents
+    .filter((client) => NAMES[client])
+    .map((client) => ({ client, name: NAMES[client], target: path.join(folders[client], NAMES[client]) }));
+}
+async function readText(file) {
+  try {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+      throw new Error('Archivo de instrucciones o registro en conflicto.');
+    return await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+async function checkParent(directory, create = false) {
+  const info = await fs.lstat(directory).catch((error) => {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  });
+  if (info && (!info.isDirectory() || info.isSymbolicLink()))
+    throw new Error('La carpeta de instrucciones o registro no es normal.');
+  if (!info && create) await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+}
+async function proof(home) {
+  await checkParent(path.dirname(proofPath(home)));
+  const text = await readText(proofPath(home));
+  if (text === null) return {};
+  const records = JSON.parse(text);
+  if (!records || typeof records !== 'object' || Array.isArray(records))
+    throw new Error('Registro de instrucciones inválido.');
+  return records;
+}
+function blockOf(text) {
+  const a = text?.indexOf(START) ?? -1,
+    b = text?.indexOf(END) ?? -1;
+  if (a < 0 || b <= a || text.indexOf(START, a + START.length) >= 0 || text.indexOf(END, b + END.length) >= 0)
+    return null;
+  return text.slice(a, b + END.length);
+}
+async function writeAtomic(target, text, lock) {
+  await lock.assertHeld();
+  const stat = await fs.lstat(target).catch((error) => {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  });
+  const tmp = target + '.' + randomUUID();
+  await fs.writeFile(tmp, text, { flag: 'wx', mode: stat?.mode ?? 0o600 });
+  try {
+    await lock.assertHeld();
+    await fs.rename(tmp, target);
+  } finally {
+    await fs.rm(tmp, { force: true });
+  }
+}
+export async function planReviewInstructions(options = {}) {
+  const owned = await proof(options.homeDirectory),
+    items = [];
+  for (const item of targets(options)) {
+    let before;
+    try {
+      await checkParent(path.dirname(item.target));
+      before = await readText(item.target);
+    } catch {
+      items.push({ ...item, state: 'conflict' });
+      continue;
+    }
+    const block = blockOf(before),
+      record = owned[item.target];
+    if ((before?.includes(START) && !block) || (block && record?.blockHash !== hash(block))) {
+      items.push({ ...item, state: 'conflict' });
+      continue;
+    }
+    const prefix = before === null ? '' : before.endsWith('\n') ? before + '\n' : before + '\n\n';
+    const after = block ? before.replace(block, BODY) : prefix + BODY + '\n';
+    items.push({
+      ...item,
+      before,
+      after,
+      state: after === before ? 'ready' : 'pending',
+      original: record ? record.original : before,
+      created: record ? record.created : before === null,
+    });
+  }
+  return { homeDirectory: options.homeDirectory, items };
+}
+export async function applyReviewInstructions(plan, lock) {
+  const owned = await proof(plan.homeDirectory),
+    pending = plan.items.filter((item) => item.state === 'pending');
+  for (const item of pending) {
+    await checkParent(path.dirname(item.target));
+    if ((await readText(item.target)) !== item.before)
+      throw new Error(`${item.name} cambió mientras confirmabas.`);
+    owned[item.target] = {
+      client: item.client,
+      blockHash: hash(BODY),
+      original: item.original,
+      created: item.created,
+    };
+  }
+  if (!pending.length) return;
+  await lock.assertHeld();
+  await checkParent(path.dirname(proofPath(plan.homeDirectory)), true);
+  // Record ownership before publishing blocks so an interrupted install can be resumed.
+  await writeAtomic(proofPath(plan.homeDirectory), JSON.stringify(owned), lock);
+  for (const item of pending) {
+    await lock.assertHeld();
+    await checkParent(path.dirname(item.target), true);
+    if ((await readText(item.target)) !== item.before)
+      throw new Error(`${item.name} cambió mientras confirmabas.`);
+    await writeAtomic(item.target, item.after, lock);
+  }
+}
+export async function removeReviewInstructions(options, lock) {
+  const owned = await proof(options.homeDirectory);
+  for (const item of targets(options)) {
+    const entry = owned[item.target];
+    if (!entry) continue;
+    let text;
+    try {
+      await checkParent(path.dirname(item.target));
+      text = await readText(item.target);
+    } catch {
+      continue;
+    }
+    const block = blockOf(text);
+    if (!block || hash(block) !== entry.blockHash) continue;
+    await lock.assertHeld();
+    if ((await readText(item.target)) !== text) throw new Error(`${item.name} cambió durante la retirada.`);
+    const without = text.replace(block, '');
+    if (entry.created && !without.trim()) await fs.unlink(item.target);
+    else if (
+      text ===
+      (entry.original ?? '') + ((entry.original ?? '').endsWith('\n') ? '\n' : '\n\n') + block + '\n'
+    )
+      await writeAtomic(item.target, entry.original ?? '', lock);
+    else await writeAtomic(item.target, without, lock);
+    delete owned[item.target];
+  }
+  if (!Object.keys(owned).length) {
+    await lock.assertHeld();
+    await fs.rm(proofPath(options.homeDirectory), { force: true });
+  } else await writeAtomic(proofPath(options.homeDirectory), JSON.stringify(owned), lock);
+}
+export async function ownedReviewInstructions(options) {
+  const owned = await proof(options.homeDirectory),
+    result = [];
+  for (const item of targets(options)) {
+    const text = await readText(item.target).catch(() => null),
+      block = blockOf(text);
+    if (block && owned[item.target]?.blockHash === hash(block)) result.push(item.name);
+  }
+  return result;
+}

package/src/review-policy.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+const CLIENTS = ['claude', 'codex', 'antigravity'];
+export const RECOMMENDED_REVIEWERS = Object.freeze({
+  claude: 'codex',
+  codex: 'claude',
+  antigravity: 'claude',
+});
+export function selectReviewer({ principal, available, certified, pending = [], sessionChoice, requested }) {
+  if (!CLIENTS.includes(principal)) throw new Error('IA principal inválida.');
+  const options = CLIENTS.filter(
+    (ia) => ia !== principal && available.includes(ia) && (certified.includes(ia) || pending.includes(ia)),
+  );
+  const recommended = options.includes(RECOMMENDED_REVIEWERS[principal])
+    ? RECOMMENDED_REVIEWERS[principal]
+    : (options[0] ?? null);
+  const preferred = requested ?? sessionChoice;
+  const selected = options.includes(preferred) ? preferred : options.length === 1 ? options[0] : null;
+  return {
+    options,
+    pending: options.filter((ia) => !certified.includes(ia) && pending.includes(ia)),
+    recommended,
+    selected,
+    ask: options.length > 1 && !selected,
+    unavailable: preferred && !options.includes(preferred) ? preferred : null,
+  };
+}
+export function shouldAutoReview({ changedFiles = [], withoutReview = false, alreadyReviewed = false }) {
+  if (withoutReview || alreadyReviewed) return false;
+  return changedFiles.some(
+    (file) =>
+      !['.md', '.mdx', '.txt', '.rst', '.adoc', '.pdf', '.png', '.jpg', '.jpeg', '.svg'].includes(
+        path.extname(file).toLowerCase(),
+      ) && !/^(readme|license|licence|notice|changelog)$/iu.test(path.basename(file)),
+  );
+}