Guías

Solución de problemas

Los problemas que se conocen con @falcux/ai-first 0.5.1, cada uno con el síntoma que ves, la causa y qué hacer. Si el tuyo no está, revisa primero qué versión corres con npx @falcux/ai-first@latest --version.

El hook dice que no encuentra node

Síntoma. Al hacer push aparece esto y el push sigue sin auditar:

ai-first: no encuentro node, así que el punto de control no corrió.
          Si empujas desde un cliente gráfico, arráncalo desde una
          terminal o deja node en /usr/local/bin.

Causa. Un push lanzado desde un cliente gráfico, un IDE o un servicio del sistema no hereda el PATH de tu shell, que es donde nvm, Homebrew o fnm dejan node. El hook lo busca en /opt/homebrew/bin, /usr/local/bin y en nvm.sh; si aun así no aparece, avisa y deja pasar. No encontrar node nunca frena un push.

Qué hacer. Arranca el cliente desde una terminal, para que herede su PATH, o deja node en /usr/local/bin. Hasta entonces, el CI sigue auditando cada pull request.

El hook dice que ai-first no está instalado

Síntoma.

ai-first: no está instalado, así que el punto de control no corrió.
          Instálalo con «pnpm add -D @falcux/ai-first» o quita este hook.

Causa. El hook no descarga nada. Busca el ai-first de node_modules, luego el del PATH, y sólo usa npx --no-install si el paquete ya está en la caché de npx. Si no encuentra ninguno, avisa y deja pasar.

Qué hacer. Instálalo como dependencia de desarrollo, como sugiere el mensaje, para que todo el equipo corra la misma versión.

init reporta «saltado» o «sugerido»

Síntoma. El reporte de init trae líneas como éstas:

  saltado  AI-FIRST.md (ya existe)
  saltado  AGENTS.md (el bloque ya está al día)
  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks

Causa. init nunca sobreescribe. saltado es algo que ya existía y no se tocó; no es un error. sugerido es algo que haría falta cambiar en un archivo o una configuración tuya: en vez de cambiarlo, te dice qué agregar. Una skill cuya carpeta ya existe se salta entera.

Qué hacer. Lee la razón de cada sugerido y aplícala a mano si te sirve. Si quieres la versión del paquete de algo que se saltó, borra la tuya y vuelve a correr init: sólo escribe lo que falta. Si una skill chocó con una tuya del mismo nombre, las salidas están en Adoptar en un proyecto existente.

core.hooksPath ya estaba configurado

Síntoma. El push no pasa por el hook de ai-first, y el reporte de init dijo:

  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks

Causa. El repo ya usaba husky, lefthook u otra carpeta de hooks. init escribió .githooks/pre-push, pero no cambió core.hooksPath: hacerlo habría apagado los hooks que ya tenías. Git sigue leyendo la carpeta anterior.

Qué hacer. Una de dos: mueve el contenido de .githooks/pre-push al pre-push de la carpeta que ya usas, o apunta git a .githooks si ya no necesitas la otra:

git config core.hooksPath .githooks

audit sale con código 1

Síntoma. audit termina con código 1 y el hook frena el push, o el check del pull request queda en rojo.

ai-first audit — demo
árbol de trabajo contra HEAD · 2 archivos tocados

✗ Zona Prohibida tocada
    P0  Zona Prohibida «.env*» tocada — credenciales
          .env.local
✓ Decisión sin fila en ADR
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»

Entropía: 40 / 100 (1 P0 · 0 P1 · 0 P2)

Causa. Hay al menos un P0: se tocó una Zona Prohibida. Sin --estricto, es lo único que hace salir con 1. Con --estricto, que es como corre el flujo de CI, también sale con 1 ante cualquier P1 o P2.

Qué hacer. Si el cambio en la zona fue un error, reviértelo. Si fue deliberado y aprobado, la zona está bien declarada y el hallazgo cumplió su función: decide con tu equipo si se publica. Si la zona no debía serlo, quítala de zonas_prohibidas en AI-FIRST.md. Qué significa cada hallazgo está en Las cinco verificaciones.

audit sale con código 2

Síntoma. audit o init terminan con código 2 y un mensaje que empieza por ai-first:, por ejemplo:

ai-first: No hay AI-FIRST.md en /ruta/a/tu/proyecto.

Causa. El código 2 es un error de uso, no un hallazgo: no hay AI-FIRST.md, su formato no se puede leer, la carpeta no es un repositorio git, la ref de --base no existe, dos opciones se contradicen, se pidió una skill que el paquete no trae o el bloque de AGENTS.md tiene una marca sin su pareja. Una opción desconocida también sale con 2, aunque con una traza de Node en vez de un mensaje propio.

Qué hacer. Lee el mensaje: dice qué falta. Si no hay AI-FIRST.md, corre npx @falcux/ai-first@latest init. Para ver las opciones válidas, npx @falcux/ai-first@latest --help.

Un check aparece como omitido

Síntoma. Una línea empieza con – y dice «omitido»:

– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»

Causa. El check no tenía con qué correr. Omitido no es aprobado: no se verificó nada, y la razón dice qué falta. Alcance se omite mientras no haya un cambio abierto en docs/changes/pending/, que es lo correcto. Inventario se omite mientras AI-FIRST.md no declare el inventario y la carpeta de componentes.

Qué hacer. Nada, si el proyecto no tiene eso. Si lo tiene, declara lo que la razón pide en AI-FIRST.md. Si hay componentes, init deja las dos líneas comentadas bajo artefactos, listas para descomentar.

Un P1 por «Decisión sin fila en ADR» que no es una decisión

Síntoma. Tocaste una superficie de decisión o cambiaste las dependencias de producción de un package.json, no era una decisión arquitectónica, y aparece un P1. Así se ve tras agregar una dependencia:

ai-first audit — nuevo
árbol de trabajo contra HEAD · 1 archivo tocado

✓ Zona Prohibida tocada
✗ Decisión sin fila en ADR
    P1  Hay señales de decisión arquitectónica y ADR.md no ganó ninguna fila
          package.json: +zod
          Silenciar: agregar la fila al ADR, o «<!-- ai-first: sin-decision -->» en el cuerpo del commit.
– Alcance excedido — omitido: no hay ninguna spec activa en docs/changes/pending/
✓ Artefacto huérfano
– Inventario de componentes desactualizado — omitido: faltan «artefactos.inventario_componentes» o «artefactos.componentes_dir»

Entropía: 20 / 100 (0 P0 · 1 P1 · 0 P2)

Sin --estricto el código de salida es 0: el P1 avisa, no frena.

Causa. El check es una heurística: una superficie tocada, o una dependencia de producción agregada o quitada, se presume decisión. A veces no lo es, como cambiar un número de versión en un archivo de configuración.

Qué hacer. Si era una decisión, agrega la fila al ADR. Si no, escribe esta anotación en el cuerpo del commit:

<!-- ai-first: sin-decision -->

Por ejemplo:

git commit -m "chore: sube la version en la configuracion" -m "<!-- ai-first: sin-decision -->"

La anotación sólo se lee en modo rango, con --base: es como corren el flujo de CI y el hook cuando la rama ya existe en el remoto. En modo árbol de trabajo no hay commits donde buscarla; ahí el P1 se imprime pero no frena nada salvo con --estricto. No quites la superficie de superficies_de_decision para silenciarlo: ahí viven las decisiones reales.

Necesito publicar sin pasar por el hook

Síntoma. El hook frena un push que tienes que hacer igual.

Causa. El hook corre audit sin --estricto, así que lo frena un P0 —una Zona Prohibida tocada— o un error de uso con código 2, como un AI-FIRST.md que no se puede leer. El mensaje de audit dice cuál de los dos.

Qué hacer. Si es deliberado:

git push --no-verify

Relacionado

ai-first auditModos, opciones y códigos de salida.

Auditar en local y en CIEl hook, el flujo de CI y cómo leer lo que reportan.

NovedadesQué cambió en cada versión publicada.