# Solución de problemas

> Los problemas conocidos de init, audit y el hook de pre-push, cada uno con su síntoma, su causa y qué hacer.

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:

```text
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.**

```text
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:

```text
  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](https://ai-first.falcux.com/docs/empezar/proyecto-existente/#si-un-nombre-ya-est%C3%A1-ocupado).

## core.hooksPath ya estaba configurado

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

```text
  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:

```bash
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.

```text
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](https://ai-first.falcux.com/docs/referencia/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:

```text
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»:

```text
– 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:

```text
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:

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

Por ejemplo:

```bash
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:

```bash
git push --no-verify
```

Precaución

`--no-verify` salta el hook, no el flujo de CI: el pull request se audita igual, con `--estricto`. El detector informa; la disciplina es del equipo.

## Relacionado

[ai-first audit](https://ai-first.falcux.com/docs/referencia/audit/)Modos, opciones y códigos de salida.

[Auditar en local y en CI](https://ai-first.falcux.com/docs/guias/auditar-en-local-y-en-ci/)El hook, el flujo de CI y cómo leer lo que reportan.

[Novedades](https://ai-first.falcux.com/docs/novedades/)Qué cambió en cada versión publicada.