# 001 · Plan

Cómo se hace lo que pide [spec.md](spec.md), con las decisiones D1–D4 que tomó
Carla el 24-oct-2026. El avance está en [tasks.md](tasks.md).

## Cambios

### 1. Candados para los secretos (fuera del repo, en `EWC-BOT/.claude/`)

- **Reglas de permisos** en `EWC-BOT/.claude/settings.json` (archivo nuevo):
  - `ask` (pedir confirmación): leer y editar `.env`, `.env.*` y
    `env.production` en cualquier carpeta, y leer `DOCUMENTACION-TRASPASO.md`.
  - `deny` (bloquear): editar `DOCUMENTACION-TRASPASO.md`.
  - Estas reglas cubren las herramientas de lectura y edición de Claude, y
    también los comandos de terminal cuando se ejecutan dentro del sandbox.
- **Hook `PreToolUse`**: una segunda capa, que cubre también los comandos que
  se ejecutan fuera del sandbox. Es un script pequeño en Node, sin
  dependencias: `EWC-BOT/.claude/hooks/guard-secrets.mjs`.
  - En la terminal (`Bash`), lee el comando que Claude va a ejecutar. Si
    menciona `DOCUMENTACION-TRASPASO`, lo bloquea. Si menciona un `.env` (salvo
    `env.example`), pide confirmación.
  - En las herramientas de archivos (`Read`, `Edit`, `Write`…), mira la ruta.
    Si es el traspaso, pide confirmación para leerlo y bloquea cualquier
    modificación. Si es un `.env`, pide confirmación.
  - Así los candados no dependen solo de cómo interprete Claude Code las
    rutas de las reglas, y se pueden probar sin reiniciar.
  - Limitación: las búsquedas amplias (`Grep`) desde `EWC-BOT/` dependen solo
    de las reglas de permisos. Claude Code las aplica a las búsquedas «en lo
    posible», no con garantía.

### 2. Comprobar la documentación (en el repo)

- `scripts/check-doc-links.mjs` (nuevo): el comprobador del 24-oct, pasado a
  Node y sin dependencias.
  - Revisa todos los `.md` del repo, salvo `node_modules`, `.git`, `.claude` y
    `dist`.
  - Comprueba los enlaces relativos a archivos y las anclas a secciones, con
    el mismo formato que usa GitHub.
  - Termina con código 1 si encuentra alguno roto.
- `package.json` de la raíz: se añade el script
  `"check:docs": "node scripts/check-doc-links.mjs"`. Hoy no tiene scripts; sus
  dependencias no se tocan.
- **Hook `PostToolUse` para `Write|Edit`**, en `EWC-BOT/.claude/settings.json`.
  Si el archivo editado es un `.md` del repo, ejecuta la comprobación completa
  (tarda menos de un segundo). Si hay enlaces rotos, se los devuelve a Claude
  para que los arregle.

### 3. Recordatorio al terminar (fuera del repo)

- **Hook `Stop`**: `EWC-BOT/.claude/hooks/remind-docs.mjs`.
  - Si ya está actuando por un recordatorio anterior (`stop_hook_active`), no
    hace nada. Así no puede entrar en bucle.
  - Mira `git status --porcelain` del repo. Si hay cambios en `backend/`,
    `frontend/`, `prisma/`, `scripts/` o en scripts `*.sh`, y ninguno en
    `CHANGELOG.md` ni en `docs/`, le devuelve a Claude el recordatorio: revisar
    las reglas «Al terminar» de `AGENTS.md`, y si no hace falta actualizar
    nada, decirlo y terminar.
  - Avisa una sola vez por sesión para el mismo conjunto de archivos
    cambiados; si aparecen cambios nuevos, vuelve a avisar.
  - Limitación: solo ve los cambios sin commitear. Si el código ya se
    commiteó en ese mismo turno, no avisa.

### 4. CI en GitHub (en el repo)

`.github/workflows/ci.yml` (nuevo) se ejecuta en cada `push` y cada
`pull_request` a `main`. También se puede lanzar a mano, sobre cualquier rama,
desde la pestaña Actions de GitHub. Si llega un push nuevo, cancela la
ejecución anterior de esa rama, para no gastar minutos de más. Tiene tres
trabajos en paralelo con Node 22, la misma versión que los Dockerfile:

- `backend`: `npm ci`, `npm run prisma:generate` y `npm run build` (`tsc`), en
  `backend/`.
- `frontend`: `npm ci` y `npm run build` (incluye `vue-tsc`), en `frontend/`.
- `docs`: `node scripts/check-doc-links.mjs`.

## Riesgos y compatibilidad

- **Un `settings.json` con un error de JSON desactiva toda la configuración de
  ese archivo, sin avisar.** Se valida el JSON y se prueba cada hook con
  entradas simuladas antes de darlo por bueno.
- **Falsos positivos del candado de terminal.** Un comando que menciona `.env`
  sin leerlo, como `grep --exclude=.env`, pedirá confirmación. Es preferible a
  que se escape una lectura.
- **La CI puede fallar la primera vez** por diferencias con el entorno local
  (por ejemplo, variables que el build del frontend espera). Se ajusta dentro
  de esta misma tarea.
- **La configuración de Claude solo aplica al abrir Claude Code en
  `EWC-BOT/`** (D2).
- **Codex no queda cubierto por los candados**: solo por la CI y por las reglas
  de `AGENTS.md`.

## Pruebas

Las de los criterios de aceptación de la spec, una por una:

- **Candados:** pedir lecturas y ediciones de prueba y comprobar que sale la
  confirmación o el bloqueo. Cuando salga la confirmación, se contesta «no»,
  así que ningún secreto se llega a leer.
- **`check:docs`:** ejecutarlo sobre la documentación actual; después, sobre un
  archivo temporal con un enlace roto, para ver que falla.
- **Hooks:** primero con entradas simuladas (el JSON que reciben, pasado por
  stdin) y después en una sesión real de Claude Code.
- **CI:** el push normal tiene que pasar. Para comprobar que falla cuando debe,
  una rama de prueba con un error de TypeScript, que se borra después. Se crea
  solo con el OK de Carla, porque se sube a GitHub.

## Despliegue

- En producción no se despliega nada: todo es configuración local y de GitHub.
- Orden: 1 → 2 → 3 → 4. Lo que va en el repo (pasos 2 y 4), un commit por
  paso. Lo de `EWC-BOT/.claude/` no está en git.
- Para volver atrás:
  - quitar las entradas de `EWC-BOT/.claude/settings.json` desactiva los
    candados y los hooks;
  - borrar `.github/workflows/ci.yml` desactiva la CI.
