navori 0.2.7 → 0.2.10

package/README.md

@@ -48,7 +48,7 @@ Y genera:
 | `sync` | Refresca los managed blocks con conflict resolution + backups |
 | `preset init <id>` | Scaffoldea un preset local en `.navori/presets/<id>/` |
 | `scan` | Detecta workspaces nuevos en monorepos (`pnpm-workspace.yaml` / `package.json#workspaces`) |
-| `doctor` | Audita el config + reporta procedencia y drift de cada managed block (`--strict` para CI) |
+| `doctor` | Audita el config + drift de cada managed block (CLAUDE.md **y AGENTS.md**), orden canónico, markers malformados, desincronización de monorepo y tools externas faltantes (`--strict` para CI) |
 | `status` | Snapshot rápido: config, plugins activos, conteo de drift y próximos pasos |
 | `bench` | Corre `render` en dry-run N veces y reporta latencias (detecta regresiones locales) |
 | `workspace <sub>` | Gestiona workspaces cross-repo (`init`, `ls`, `show`, `rm`) |
@@ -64,14 +64,18 @@ Un preset aporta skills y reglas específicas del stack además del core. El `in
 
 | Preset | Stack |
 |---|---|
+| `vite-react-ts` | Vite + React + TS (SPA, agnóstico de UI-lib) |
 | `vite-react-ts-mantine` | Vite + React + TS + Mantine (SPA) |
 | `nextjs` | Next.js (App Router) |
+| `astro` | Astro (static / SSR) |
 | `nestjs` | NestJS (backend) |
+| `express` | Express (backend, agnóstico de DB) |
 | `express-mongoose` | Express + Mongoose (backend) |
 | `background-worker` | Worker de fondo (jobs + colas: agenda / bullmq / amqplib) |
-| `astro` | Astro (static / SSR) |
 | `medusa` | Medusa.js v2 (backend) |
 
+Los presets **neutros** (`vite-react-ts`, `express`) traen las skills genéricas del stack sin atarte a una lib; los especializados (`…-mantine`, `…-mongoose`) agregan las skills de esa capa encima.
+
 **¿Tu stack no tiene preset oficial?** No pasa nada. El `init` instala el harness completo (agentes, gates, protocolo, SDD) y funciona desde ya — solo te quedas sin los skills específicos del stack. El init te avisa, te deja en el baseline (`preset: custom`) y te sugiere cubrir el gap con un preset local.
 
 **Presets locales** — crea uno checked-in al repo bajo `.navori/presets/<id>/`:

package/dist/assets/core/core-assets/agents/commit-pr-pilot.md

@@ -136,7 +136,7 @@ Si el repo define su propio template (`.github/pull_request_template.md`), léel
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Template específico del PR si difiere del default (.github/pull_request_template.md).
      - Convenciones de scope obligatorias (lista de scopes válidos, mappings de área → scope).
      - Reglas de naming de branches (ej: `feat/BT-1234-descripcion`).

package/dist/assets/core/core-assets/agents/explorer.md

@@ -25,7 +25,7 @@ Si la pregunta es puntual ("¿dónde está X?"), no eres tú — es `researcher`
 1. Lee `CLAUDE.md` para entender convenciones del repo.
 2. Define el alcance: una carpeta, un módulo lógico, un patrón de archivos. El orquestador debería pasártelo preciso; si llega ambiguo, devuelve `blocked` nombrando las opciones (carpeta X / módulo Y / patrón Z) para que reenvíe acotado — no adivines.
 3. Recorre desde los entry points (rutas, exports raíz del módulo, `index.ts`) hacia las hojas. Para cada nivel, lista archivos y su rol breve.
-4. Identifica dependencias inversas: ¿qué módulos externos consumen este módulo? Eso indica el "blast radius" de cambiar algo acá.
+4. Identifica dependencias inversas: ¿qué módulos externos consumen este módulo? Eso indica el "blast radius" de cambiar algo aquí.
 5. Escribe `.claude/progress/explore_<area>.md`:
 
    ```markdown
@@ -81,7 +81,7 @@ done -> .claude/progress/explore_<area>.md
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Áreas que típicamente necesitan exploración (módulos grandes, monorepo workspaces).
      - Convenciones de naming que ayudan a clasificar archivos (sufijos, prefijos).
      - Limitaciones: módulos generados que no vale mapear (ej: dist/, *.gen.ts).

package/dist/assets/core/core-assets/agents/implementer.md

@@ -12,10 +12,10 @@ Ejecutas **una sola** tarea desde inicio hasta verificación. No orquestas, no l
 ## Protocolo
 
 1. **Lee** `CLAUDE.md`. Identifica las convenciones del repo y las "Reglas del proyecto" (la sección del orquestador en `CLAUDE.md`).
-2. **Anota** en `.claude/progress/current.md`:
+2. **Anota** en `.claude/progress/impl_<feature>.md` (tu archivo de trabajo; al cerrar se convierte en el informe):
    - `Tarea: <descripción breve>`
    - `Root cause: <archivo:línea + por qué>` (solo si la tarea es bugfix; no puedes tocar código sin esto).
-   - `Plan:` — tareas atómicas con checkboxes, una acción de 2–5 min cada una. Marca `[x]` al ir completando para que `current.md` refleje progreso real. Ejemplo:
+   - `Plan:` — tareas atómicas con checkboxes, una acción de 2–5 min cada una. Marca `[x]` al ir completando para que tu `impl_<feature>.md` refleje progreso real. Ejemplo:
 
      ```
      - [ ] Definir interface en <path>
@@ -39,12 +39,13 @@ Ejecutas **una sola** tarea desde inicio hasta verificación. No orquestas, no l
 ## Reglas duras (genéricas, aplican siempre)
 
 - **Una sola tarea por sesión.** Si descubres que tu cambio requiere tocar otra cosa fuera del scope, paras y reportas `blocked`.
+- **Nunca escribas `progress/current.md` (raíz).** El estado de sesión lo consolida el líder; tú puedes correr en paralelo con otros implementers y ese archivo es compartido. Tu único archivo de progreso es `.claude/progress/impl_<feature>.md`.
 - **Tipado fuerte, `any` prohibido en código nuevo.** Definir tipos correctos antes de avanzar. Usa `unknown` + narrowing, generics, o tipos de dominio. Cubre parámetros, retornos, callbacks, eventos, props, hooks y responses de services. Si tipar bien es genuinamente imposible (lib de tercero sin types), comentario `// any justificado: <razón>` — último recurso, no atajo.
 - **Sin hardcode**: secretos / URLs / endpoints via env vars (`process.env.*`, `import.meta.env.*`, según stack).
 - **Sin `console.log`** en código que se va a mergear (guard `import.meta.env.DEV` o equivalente del runtime).
 - **Cero errores nuevos** introducidos por tu código en las herramientas del quality gate (vs. baseline). Si dudas del baseline: `git stash` → re-correr → `git stash pop` → comparar. Devolver con cualquier herramienta en rojo (por tu cambio) es motivo automático de `CHANGES_REQUESTED`.
 - **JSDoc** obligatorio en exports públicos y funciones >15 líneas o con lógica condicional densa.
-- Si una herramienta falla raro (ej. tsc rompe sin diff aparente), **no improvises workaround**: anota `blocked` en `.claude/progress/current.md` y paras.
+- Si una herramienta falla raro (ej. tsc rompe sin diff aparente), **no improvises workaround**: anota `Estado: BLOCKED` + el motivo en `.claude/progress/impl_<feature>.md` y paras.
 
 ## Evidence-based completion (gate antes del informe)
 
@@ -91,15 +92,17 @@ done -> .claude/progress/impl_<feature>.md
 o
 
 ```
-blocked -> .claude/progress/current.md
+blocked -> .claude/progress/impl_<feature>.md
 ```
 
+(En ambos casos el archivo es el mismo: tu informe con `Estado: DONE | BLOCKED`. El líder consolida blockers y estado de sesión en `progress/current.md`; tú no tocas ese archivo.)
+
 Nunca devuelvas el diff en chat. El líder lo lee del disco si lo necesita.
 
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Flujo de capas exacto (ej: `axios → services → adapters → components`).
      - Libs forzadas / prohibidas (forms, tables, state).
      - Paths de naming convention (`<NAME>_LABELS`, etc).

package/dist/assets/core/core-assets/agents/leader.md

@@ -1,19 +1,21 @@
 ---
 name: leader
-description: Orquestador. Recibe la tarea, divide el trabajo y lanza subagentes en paralelo. NUNCA escribe código directamente.
+description: NO invocar como subagente. Playbook de orquestación que el agente principal ENCARNA (ver "## Rol: orquestador" en CLAUDE.md). Delegarlo a un subagente serializa el trabajo y tira el paralelismo.
 tools: Read, Glob, Grep, Bash, Agent
 model: {{models.leader}}
 ---
 
-# Agente Líder (Orquestador)
+# Playbook del Orquestador (encarnado por el agente principal)
 
-Tu único trabajo es **descomponer y coordinar**, nunca implementar.
+> Este archivo es **referencia de profundidad** — el rol de orquestador **lo encarna el agente principal**, no un subagente. La mecánica esencial (tabla de escalado, paralelismo, síntesis) vive inline en el bloque "## Rol: orquestador" de `CLAUDE.md`, que se auto-carga. Aquí está el detalle extendido y, abajo, las **Reglas del proyecto**. NO invoques `Agent(subagent_type: leader)`.
+
+Tu único trabajo como orquestador es **descomponer y coordinar**, nunca implementar.
 
 ## Protocolo de arranque
 
 1. Lee `CLAUDE.md` (stack, convenciones, quality gate).
 2. El catálogo de subagentes y skills está en `CLAUDE.md` (`## Agentes disponibles`, `## Skills disponibles`).
-3. Lee `.claude/progress/current.md` si existe — estado de la sesión anterior.
+3. Lee `progress/current.md` (raíz del repo) si existe — estado de la sesión anterior.
 4. Identifica el scope de la tarea contra las "Reglas del proyecto" abajo (legacy paths, áreas críticas, convenciones del repo).
 5. **¿Llega texto de un ticket (Jira/Linear/GitHub/Slack)?** Si matchea los triggers de tu agente `ticket-audit` (bug en feature crítica, migración estructural, feature que cruza >3 capas), invoca primero ese agente — produce `.claude/progress/audit_<ID>.md` que orienta toda la descomposición posterior. Para tickets triviales (typo, copy, color), sáltate el audit.
 6. **Brainstorm gate (opcional, condicional)**: si la tarea introduce un patrón nuevo, decisión arquitectural o lib nueva (NO aplica a fixes / triviales / features que sigan patterns existentes), antes del implementer:
@@ -89,9 +91,11 @@ Archivos esperados:
 - `.claude/progress/audit_<TICKET-ID>.md` — análisis profundo del ticket (`ticket-audit`)
 - `.claude/progress/explore_<tema>.md` — mapa amplio (`explorer`)
 - `.claude/progress/research_<pregunta>.md` — pregunta acotada (`researcher`)
-- `.claude/progress/impl_<feature>.md` — informe del `implementer`
+- `.claude/progress/impl_<feature>.md` — informe del `implementer` (incluye su `Estado: DONE | BLOCKED`)
 - `.claude/progress/review_<feature>.md` — veredicto del `reviewer`
 
+**Separación de rutas (no mezclar):** `.claude/progress/` es SOLO para estos handoffs efímeros entre agentes. El **estado de sesión** (tarea en curso, plan, blockers) vive en `progress/current.md` (raíz del repo, persiste en git) y lo consolidas **TÚ, únicamente**: los subagentes nunca lo escriben. Cuando un `implementer` reporta `blocked` en su `impl_<feature>.md`, tú registras el blocker en `progress/current.md` junto con el siguiente paso.
+
 ## Cierre del ciclo: crear el PR
 
 Cuando `.claude/progress/review_<feature>.md` contenga `APPROVED`:
@@ -129,7 +133,7 @@ Si la tarea es:
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Áreas críticas que requieren review extra: {{project.criticalAreas}}
      - Carpetas legacy con reglas distintas: {{project.legacyPaths}}
      - Convenciones de naming / estructura del repo.

package/dist/assets/core/core-assets/agents/researcher.md

@@ -76,7 +76,7 @@ Nunca devuelvas el contenido del informe en chat. El leader lo lee del disco.
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Subsistemas con naming particular donde grep simple falla (módulos generados, abreviaturas).
      - Repos hermanos o submódulos que también vale buscar (paths absolutos).
      - Patrones de búsqueda compuestos que se usan recurrentemente.

package/dist/assets/core/core-assets/agents/reviewer.md

@@ -14,12 +14,17 @@ Eres un revisor estricto. Tu única función es **aprobar o rechazar**. No edita
 ### Setup (común a las dos pasadas)
 
 1. Lee `CLAUDE.md`, `.claude/progress/impl_<feature>.md`, `.claude/progress/audit_<ID>.md` (si existe).
-2. Identifica archivos modificados:
+2. Identifica archivos modificados. Difea contra `{{prTarget}}` (la rama destino
+   del PR), **no** contra el punto de fork: es el diff EXACTO que verá GitHub y el
+   que revisa commit-pr-pilot. Cuando `{{branchBase}}` ≠ `{{prTarget}}` (p.ej.
+   ramificas de `main` pero el PR va a `develop`) revisar contra el fork mostraría
+   un diff distinto al del PR.
 
    ```bash
    git status --short
+   git fetch origin {{prTarget}} --quiet
    git diff --stat
-   git diff origin/{{branchBase}}...HEAD
+   git diff origin/{{prTarget}}...HEAD
    ```
 
 3. Aplica `.claude/skills/verify-before-done.md` antes de cualquier veredicto: corre los comandos de quality gate **en este turno** (no asumas del cache del informe del implementer).
@@ -41,7 +46,7 @@ Eres un revisor estricto. Tu única función es **aprobar o rechazar**. No edita
 
 ### Pasada 2 — Code quality (solo si SPEC_OK)
 
-¿El código matchea las convenciones del repo? Acá sí revisas estilo/naming/tipos.
+¿El código matchea las convenciones del repo? Aquí sí revisas estilo/naming/tipos.
 
 Aplica `.claude/skills/review-diff.md` — la checklist completa por dimensiones (tipos, capa de datos, errores, seguridad, hardcode, naming, dead code) con severidades. Sus CRÍTICO/ALTO mapean a los issues ≥80 de abajo; MEDIO a las observaciones informativas. Resumen de lo mínimo a validar contra `CLAUDE.md` y las "Reglas del proyecto" del leader:
 
@@ -147,7 +152,7 @@ CHANGES_REQUESTED -> .claude/progress/review_<feature>.md
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Chequeos de convenciones que tu reviewer debe correr siempre (libs, capas, patrones).
      - Anti-patterns específicos del stack que son auto-CHANGES_REQUESTED.
      - Reglas de áreas críticas: {{project.criticalAreas}}

package/dist/assets/core/core-assets/agents/ticket-audit.md

@@ -65,7 +65,7 @@ Si encuentras un audit reciente para el mismo ticket, léelo primero. No re-audi
 <2–4 líneas: qué pide el ticket, dónde impacta>
 
 ## Hipótesis de causa raíz (si es bug)
-1. [confianza:0–100] `<archivo>:<línea>` — <descripción + por qué crees que es acá>
+1. [confianza:0–100] `<archivo>:<línea>` — <descripción + por qué crees que es aquí>
 
 ## Approaches alternativos (si es feature/refactor)
 ### Approach A — <nombre>
@@ -116,7 +116,7 @@ El leader lee el audit del disco y descompone desde ahí.
 <!-- navori:user-section -->
 ## Reglas del proyecto
 
-<!-- user: agrega acá lo específico de tu repo. Sugerencias:
+<!-- user: agrega aquí lo específico de tu repo. Sugerencias:
      - Áreas críticas que casi siempre requieren audit: {{project.criticalAreas}}
      - Subsistemas con reglas particulares (ej: migración legacy↔nuevo backend, módulo X solo lo toca alguien con context).
      - Patrones de tickets recurrentes que tienen plantilla de análisis específica.

package/dist/assets/core/core-assets/hooks/guard-destructive.sh

@@ -13,7 +13,24 @@
 # bottom — `$cmd` is already parsed and in scope there.
 set -euo pipefail
 
-cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null || true)
+# Extract .tool_input.command from the PreToolUse payload WITHOUT hard-depending
+# on jq (NOT preinstalled on macOS — a missing jq used to make this guard wave
+# every command through). Try jq, then node (Claude Code's own runtime), and if
+# no JSON parser is on PATH fall back to a best-effort sed unwrap so the guard
+# still inspects the command instead of failing open.
+payload=$(cat)
+extract_cmd() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null && return 0
+  fi
+  if command -v node >/dev/null 2>&1; then
+    printf '%s' "$payload" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{try{process.stdout.write(String(JSON.parse(s)?.tool_input?.command??""))}catch{}})' 2>/dev/null && return 0
+  fi
+  # No JSON parser on PATH: pull the "command" string out with sed. Best-effort
+  # (won't handle a literal embedded quote), but far better than failing open.
+  printf '%s' "$payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p'
+}
+cmd=$(extract_cmd)
 [ -z "$cmd" ] && exit 0
 
 base="{{branchBase}}"

package/dist/assets/core/core-assets/hooks/quality-gate-pre-commit.sh

@@ -9,7 +9,20 @@
 # bottom — they keep `cmd` and the original exit codes in scope.
 set -euo pipefail
 
-cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null || true)
+# Extract .tool_input.command WITHOUT hard-depending on jq (not preinstalled on
+# macOS). Try jq, then node (Claude Code's own runtime), then a best-effort sed
+# unwrap. If nothing extracts a command $cmd stays empty and the gate skips.
+payload=$(cat)
+extract_cmd() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null && return 0
+  fi
+  if command -v node >/dev/null 2>&1; then
+    printf '%s' "$payload" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{try{process.stdout.write(String(JSON.parse(s)?.tool_input?.command??""))}catch{}})' 2>/dev/null && return 0
+  fi
+  printf '%s' "$payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p'
+}
+cmd=$(extract_cmd)
 
 case "$cmd" in
   'git commit'*|'git push'*)

package/dist/assets/core/core-assets/lib-skills/mongoose.md

@@ -8,9 +8,9 @@ type: reference
 
 ## Cuándo usar este skill
 
-Cuando la tarea toca `domain/models` o ejecuta operaciones de Mongoose en los controllers. Mongoose 6+ sobre MongoDB. El repo no usa repository wrappers: los controllers tocan los Models directo, así que null-guards, casts de ObjectId y `.lean()` viven en cada controller method.
+Cuando la tarea toca `domain/models` o ejecuta operaciones de Mongoose en los controllers. Sin repository wrappers: los controllers tocan los Models directo, así que null-guards, casts de ObjectId y `.lean()` viven en cada controller method.
 
-En **NestJS** (`@nestjs/mongoose`) el Model no se importa directo: se inyecta con `@InjectModel(Resource.name) private resourceModel: Model<ResourceDocument>` en el constructor del service. El resto de patrones (`.lean()`, `new Types.ObjectId`, null-guards, soft delete) aplican igual.
+En **NestJS** (`@nestjs/mongoose`) el Model se inyecta: `@InjectModel(Resource.name) private model: Model<ResourceDocument>`; el resto de patrones aplican igual.
 
 ## Patrón canónico
 
@@ -21,36 +21,31 @@ if (!doc) throw new NotFoundError(`Resource ${id} not found`);
 const docs = await Resource.find(filter).lean<IResource[]>();  // read-only
 
 const updated = await Resource.findByIdAndUpdate(
-  id, { $set: dto }, { new: true, runValidators: true }
+  id, { $set: dto }, { returnDocument: 'after', runValidators: true }
 );
 ```
 
-`{ new: true }` devuelve el doc actualizado, no el viejo; `{ runValidators: true }` valida updates parciales.
+`returnDocument: 'after'` (reemplaza el deprecado `new: true`) devuelve el doc actualizado; `runValidators: true` valida el update parcial. Ojo: `findByIdAndUpdate` **no** dispara hooks `pre('save')` ni valida el doc completo — si hay lógica en middleware `save`, usa `doc.save()`.
 
 ## ObjectId — la trampa más común
 
-Un `id` de `req.params`/`req.body` es **string**. `findById` lo castea solo, pero aggregations y queries complejas requieren cast explícito con `new`:
-
-```ts
-import { Types } from 'mongoose';
-const _id = new Types.ObjectId(id);  // Mongoose 6+ exige `new`
-```
-
-Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si no, un string mal-formado lanza `CastError`. Compara ObjectId con `.equals()`, no con `==`.
+Un `id` de `req.params`/`req.body` es **string**. `findById` lo castea solo, pero aggregations y queries complejas requieren `new Types.ObjectId(id)` (el `new` es obligatorio en Mongoose 6+). Valida el formato antes (`/^[a-f\d]{24}$/i`) o un string mal-formado lanza `CastError`. Compara ObjectId con `.equals()`, nunca `==`.
 
 ## Gotchas que muerden
 
-- **N+1**: `populate` ejecuta queries extra. En paginate sobre datasets grandes usa `$lookup` en vez de `populate`.
-- **`.lean()`**: el resultado no tiene `.save()`, `.delete()` ni virtuals. Si necesitas mutar, no lo uses.
-- **Soft delete**: con `mongoose-delete`, `find` ya excluye `deleted: true`; borra con `doc.delete()` (no `findByIdAndDelete`) y restaura con `doc.restore()`.
+- **Query injection**: `Model.find(req.query)` crudo deja pasar operadores (`{ $ne: null }`). Arma el filtro campo por campo o `.setOptions({ sanitizeFilter: true })`. Y `strictQuery` es `false` por default (Mongoose 7+): un campo con typo se ignora → filtro vacío que devuelve **toda** la colección.
+- **Atomicidad multi-doc**: escrituras relacionadas en `connection.transaction(async (session) => {...})`, pasando `{ session }` a cada op. `bulkWrite` no es transacción.
+- **Índices**: filtros y `.sort()` sobre campos sin índice = COLLSCAN. Declara `schema.index(...)`, verifica con `.explain()`.
+- **populate** batchea con `$in` (1 query por path, no N); no filtra/ordena por el child — ahí `$lookup`. `.lean()` pierde `.save()`/virtuals.
+- **Soft delete**: con `mongoose-delete`, `find` ya excluye `deleted: true`; borra con `doc.delete()` (no `findByIdAndDelete`), restaura con `doc.restore()`.
 
 ## Reglas duras
 
 1. **Ops de Mongoose nunca en la ruta** — siempre dentro de un controller method.
-2. **Null-guard tras `findById`/`findOne`** — `if (!doc) throw new NotFoundError(...)`. Nada de `if (doc) {...}` silencioso.
-3. **`.lean()` cuando no necesitas mutar** — evita el overhead de documentos Mongoose.
-4. **Comparar ObjectId con `.equals()`** / `.toString()`, nunca `==`.
-5. **Respeta el soft delete del repo** — no hard delete en modelos con `mongoose-delete`.
+2. **Null-guard tras `findById`/`findOne`** — `if (!doc) throw new NotFoundError(...)`.
+3. **`.lean()` cuando no necesitas mutar**; comparar ObjectId con `.equals()`, nunca `==`.
+4. **Nunca `Model.find(req.query)` crudo** — filtro campo por campo o `sanitizeFilter`.
+5. **Respeta el soft delete del repo**; escrituras relacionadas en `connection.transaction`.
 
 ## Tabla rápida
 
@@ -59,16 +54,14 @@ Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si n
 | Buscar por id | `findById(id)` + null-guard → `NotFoundError` |
 | Cast string → ObjectId | `new Types.ObjectId(id)` |
 | Query read-only | `.find(filter).lean()` |
-| Cargar relaciones | `.populate({ path, model })` (cuidado N+1) |
-| Paginar | plugin `.paginate(...)` o `skip().limit()` + `countDocuments` |
+| Paginar | `.paginate(...)` o `skip().limit()` + `countDocuments` |
 | Borrar con soft delete | `doc.delete()` (no `findByIdAndDelete`) |
-| Update devolviendo el nuevo doc | `findByIdAndUpdate(id, { $set }, { new: true, runValidators: true })` |
-| Muchas escrituras | `bulkWrite([...])` |
+| Update devolviendo el nuevo | `findByIdAndUpdate(id, { $set }, { returnDocument: 'after', runValidators: true })` |
+| Escrituras relacionadas | `connection.transaction(async (session) => …)` |
 
 ## Antes de declarar listo
 
-- Toda op de Mongoose vive en un controller method, no en la ruta.
-- Cada `findById`/`findOne` tiene su null-guard que lanza `NotFoundError`.
-- Las queries read-only usan `.lean()`; los ObjectId se comparan con `.equals()`.
-- Los borrados respetan el soft delete del modelo cuando aplica.
+- Cada `findById`/`findOne` tiene null-guard → `NotFoundError`; read-only con `.lean()`.
+- Ningún filtro arma con `req.query`/`req.body` crudo; ObjectId comparado con `.equals()`.
+- Borrados respetan soft delete; escrituras relacionadas van en transacción.
 - `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/lib-skills/react-hook-form.md

@@ -0,0 +1,61 @@
+---
+name: react-hook-form
+description: Patrones de React Hook Form en React+TS — register vs Controller, zodResolver, errores por campo, re-renders. Aplica al crear o tocar formularios con RHF.
+type: reference
+---
+
+# React Hook Form — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un formulario con RHF: validación con Zod, submit, errores, o cablear inputs de una lib controlada (Mantine/MUI `Select`, `DatePicker`). RHF es la fuente de verdad del form — no dupliques sus valores en `useState`. Ventaja sobre Formik: los inputs nativos van **uncontrolled** (vía refs), así que teclear no re-renderiza el form entero.
+
+## El patrón
+
+Uncontrolled por defecto + Zod como schema + `Controller` **solo** donde el input no emite un evento DOM nativo.
+
+```tsx
+const schema = z.object({ email: z.string().email(), role: z.enum(['coach', 'coachee']) });
+type FormValues = z.infer<typeof schema>;
+
+const { register, control, handleSubmit, formState: { errors, isSubmitting } } =
+  useForm<FormValues>({ resolver: zodResolver(schema), defaultValues: { email: '', role: 'coachee' } });
+
+<TextInput error={errors.email?.message} {...register('email')} />  // nativo → register
+// Select de Mantine (onChange da el valor, no un event) → Controller:
+<Controller control={control} name="role" render={({ field, fieldState }) => (
+  <Select data={['coach','coachee']} error={fieldState.error?.message} {...field} />
+)} />
+```
+
+## Gotchas que muerden
+
+- **`register` por defecto; `Controller` es la excepción.** Un input que reenvía `ref` y dispara `onChange` con un evento DOM (texto, textarea, checkbox nativo, `<TextInput>` de Mantine) va con `{...register('campo')}`. Envolverlo en `Controller` re-introduce el re-render por tecla que RHF existe para evitar.
+- **Cuándo SÍ va `Controller`:** componentes cuyo `onChange` entrega el **valor directo** — Mantine `Select`/`MultiSelect`/`NumberInput`/`DateInput`, todo MUI, `react-select`. Cablea `field.value`/`onChange`/`onBlur`/`ref`; el error sale de `fieldState.error?.message`.
+- **`defaultValues` no es opcional.** Sin él, un campo arranca `undefined` → warning "uncontrolled to controlled" (`Controller` con `undefined` es inválido: usa `null`/`''`). Para edición async usa `reset(data)` en un `useEffect`, no valores a mano en cada render.
+- **`watch()` re-renderiza todo.** Para leer en submit usa `getValues('campo')`; para que un hijo dependa de un campo, `useWatch({ control, name })` en ese hijo. `watch()` global en un form grande es anti-patrón.
+- **Números: `register('age', { valueAsNumber: true })`.** Sin esto un `type="number"` entrega **string** y tu `z.number()` falla. Corre antes del resolver, así validas con `z.number()` directo.
+- **`useFieldArray` con `key={field.id}`, nunca el índice** (corrompe el estado al reordenar). Error de servidor con `setError('root.server', …)`, no en un campo.
+
+## Reglas duras
+
+1. Validación en schema Zod vía `zodResolver`; tipo por `z.infer`. Nada de `rules` inline ni tipos paralelos.
+2. `register` por defecto; `Controller` solo para inputs sin evento DOM nativo.
+3. `defaultValues` siempre; edición async con `reset(data)`, sin `useState` espejo.
+4. `getValues`/`useWatch` para leer sin re-render; `isSubmitting` deshabilita el botón.
+
+## Tabla rápida
+
+| Input | Cómo cablear |
+|---|---|
+| Texto / textarea / checkbox nativo | `{...register('campo')}` |
+| Número | `register('n', { valueAsNumber: true })` |
+| Select / Date / Number de Mantine/MUI | `<Controller>` + `{...field}` |
+| Lista dinámica | `useFieldArray` + `key={field.id}` |
+
+## Antes de declarar listo
+
+- Zod + `zodResolver`, tipo por `z.infer`; `Controller` para inputs controlados, `register` para texto; sin `useState` espejo.
+- `defaultValues` seteado; sin warnings "uncontrolled to controlled". Submit con `handleSubmit` + `isSubmitting`.
+- `{{qualityGate.fast}}` en verde.
+</content>

package/dist/assets/core/core-assets/lib-skills/redux-toolkit.md

@@ -31,16 +31,18 @@ export const { setActive } = slice.actions;
 Store + hooks tipados una sola vez, y se usan en toda la app:
 
 ```ts
-export const useAppDispatch: () => AppDispatch = useDispatch;
-export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>();     // patrón vigente (RTK 2 / react-redux 9)
+export const useAppSelector = useSelector.withTypes<RootState>();       // no el viejo TypedUseSelectorHook
 ```
 
 ## Gotchas que muerden
 
 - **Immer solo dentro de `createSlice`.** Ahí "mutas" el draft; fuera de un reducer, mutar el state es un bug. No retornes Y mutes en el mismo reducer.
 - **Selectores memoizados** con `createSelector` cuando derivan/transforman — un selector que crea un array/objeto nuevo en cada llamada re-renderiza siempre.
-- **`useSelector` devuelve la referencia**: selecciona lo mínimo, no el slice entero.
-- **Async**: `createAsyncThunk` para casos simples; si es data de API que cacheas/invalidas, evalúa RTK Query en vez de thunks + slice manual.
+- **`useSelector` devuelve la referencia**: selecciona lo mínimo, no el slice entero. Si necesitas varios campos, envuelve con `useShallow(...)` (react-redux 9) para comparar superficial y no re-renderizar de más.
+- **Efectos reactivos → `createListenerMiddleware`**, no un `useEffect` espiando el store ni sagas. Reacciona a una acción/cambio de estado desde el middleware.
+- **Colecciones por id → `createEntityAdapter`**: `selectAll`/`selectById` memoizados gratis, CRUD normalizado, sin arreglos a mano.
+- **Async**: `createAsyncThunk` simple; si es data de API que cacheas/invalidas, evalúa RTK Query. `extraReducers` con builder callback (`(b) => b.addCase(...)`), la forma-objeto se eliminó en RTK 2.
 - **No-serializables** (Date, Map, funciones) fuera del store; rompen devtools y persistencia.
 
 ## Reglas duras

package/dist/assets/core/core-assets/lib-skills/socketio.md

@@ -19,7 +19,7 @@ io.of('/sessions').use(authSocket).on('connection', (socket) => {
   socket.on('message:send', async (dto, ack) => {
     try {
       const saved = await messageService.create(socket.data.userId, dto);
-      io.to(`session:${dto.sessionId}`).emit('message:new', saved);
+      io.to(`session:${socket.data.sessionId}`).emit('message:new', saved); // room de socket.data, no del payload
       ack?.({ ok: true, id: saved._id });
     } catch (err) {
       ack?.({ ok: false, error: toClientError(err) });
@@ -39,6 +39,9 @@ io.of('/sessions').use(authSocket).on('connection', (socket) => {
 - **Listeners colgados.** Toda suscripción/intervalo creado en `connection` se limpia en `disconnect`, o se filtra memoria.
 - **Errores.** Un throw dentro de un handler no llega al cliente: reporta vía el callback `ack` o un evento `error:*`, nunca dejes la promesa sin catch.
 - **Auth en el handshake**, no por evento — rechaza en el middleware `.use()` antes de `connection`.
+- **Tipa el `Server`/`Socket`** con las 4 interfaces (`Server<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>`): autocompletado y type-check de payloads y acks. `socket.data` se tipa vía `SocketData`, no `any`.
+- **Multi-instancia ⇒ adapter (Redis) + sticky sessions.** Sin adapter, `io.to(room)` solo alcanza a los sockets de **este** proceso (broadcasts perdidos al escalar); sin sticky, el long-polling da "Session ID unknown".
+- **Acks que esperan respuesta usan timeout**: `socket.timeout(ms).emitWithAck(...)`. Sin timeout, un ack ausente cuelga/leakea.
 
 ## Reglas duras
 

package/dist/assets/core/core-assets/lib-skills/tanstack-query.md

@@ -39,8 +39,9 @@ const mutation = useMutation({
 - **`staleTime` vs `gcTime`.** `staleTime` decide cuándo refetchea; con `0` (default) refetchea agresivo. Súbelo para data estable y evita parpadeos/llamadas extra.
 - **No espejes la data en useState/Redux.** Lee de `data` directo; copiarla a otro estado crea dos verdades que se desincronizan.
 - **`enabled`** para queries dependientes — no dispares con el id aún `undefined`.
-- **Invalidación tras mutar**, no edición manual del cache, salvo update optimista deliberado con rollback en `onError`.
-- **`isPending` vs `isFetching`**: `isPending` es la primera carga sin data; `isFetching` es cualquier fetch en curso (incluye revalidación).
+- **`useQuery` NO tiene `onSuccess`/`onError`/`onSettled`** (v5 los eliminó; solo sobreviven en `useMutation`). Para reaccionar a la data, hazlo en render o con `select`. Es el gotcha #1 al migrar de v4: el callback simplemente nunca corre.
+- **Update optimista completo**: en `onMutate` haz `await queryClient.cancelQueries({ queryKey })` (sin esto, un refetch en vuelo pisa tu update), snapshot con `getQueryData`, aplica con `setQueryData`; restaura el snapshot en `onError`; `invalidateQueries` en `onSettled`.
+- **`isPending` vs `isFetching`**: `isPending` es la primera carga sin data; `isFetching` es cualquier fetch en curso (incluye revalidación). Paginación: `placeholderData: keepPreviousData` (v5 reemplazó `keepPreviousData: true`).
 
 ## Reglas duras
 

package/dist/assets/core/core-assets/{presets/express-mongoose/skills → lib-skills}/winston-logging.md

@@ -28,7 +28,7 @@ try {
 
 Con `format.errors({ stack: true })` (config típica), pasar un `Error` loguea el stack solo. Prefija con `[<scope>:<verb>]` (`[job:sendReminder]`, `[email:welcome]`) para que sea grep-friendly.
 
-A menudo NO necesitas try/catch en el controller: el `asyncHandler` ya pasa el error al middleware global. Agrégalo solo para loguear contexto extra, mapear un error específico (ej. `MongoServerError` 11000 → `BadRequestError`), o cleanup antes del re-throw.
+Si tu framework ya centraliza el error async (`asyncHandler` en Express, exception filters en Nest, error middleware global), NO dupliques try/catch en cada handler. Agrégalo solo para loguear contexto extra, mapear un error específico (ej. `MongoServerError` 11000 → `BadRequestError`), o hacer cleanup antes del re-throw.
 
 ## Gotchas que muerden
 

package/dist/assets/core/core-assets/lib-skills/zod-validation.md

@@ -33,7 +33,9 @@ En la route: `router.post('/', validate(createResourceSchema, 'body'), ...)`. En
 ## Gotchas que muerden
 
 - **ObjectId pelado** (`z.string()`) deja pasar `"abc"`; Mongoose lanza CastError 500 en vez de 400 limpio. Usa siempre el helper `objectId`.
-- **Query strings siempre son string.** Sin `z.coerce`, `z.number()` las rechaza. Usa `z.coerce.number()` / `z.coerce.date()`.
+- **Query strings siempre son string.** Sin `z.coerce`, `z.number()` las rechaza. Usa `z.coerce.number()` / `z.coerce.date()`. **Footgun:** `z.coerce.number()` usa `Number()`, así que `""`/`" "`/`null` → `0` (un `?page=` vacío pasa como `0`). Si importa, pon límites explícitos o `z.string().regex(...).transform(Number)`.
+- **Claves desconocidas se descartan en silencio:** `z.object({...})` hace *strip*, así que un typo en el body (`{ ammount }`) se pierde sin error. En endpoints de mutación usa `z.strictObject({...})` para atraparlo.
+- **Versión:** este skill asume Zod v3. En **v4**: `z.nativeEnum`→`z.enum`, `z.string().datetime()`→`z.iso.datetime()`, y `{ message }`→`{ error }` en las opciones de error.
 
 ## Reglas duras
 

package/dist/assets/core/core-assets/managed/orquestacion.md

@@ -1,15 +1,40 @@
-## Rol: orquestador
+## Rol: orquestador (centro de gravedad)
 
-Ante una tarea no trivial **actúas como el `leader`** (`.claude/agents/leader.md`): descompones y coordinas, no implementas el código tú directamente. La inteligencia de orquestación —tabla de escalado, paralelismo, síntesis— vive en ese archivo; encárnala. El catálogo de subagentes está en "## Agentes disponibles".
+Ante una tarea no trivial **tú actúas como el orquestador**: descompones y coordinas, no implementas el código directamente. Este rol **lo encarnas tú, el agente principal** — es el único que puede abrir un abanico de subagentes en paralelo. **NUNCA lo delegues**: no invoques `Agent(subagent_type: leader)`. El archivo `.claude/agents/leader.md` es referencia de profundidad (y las "Reglas del proyecto"), no un subagente para delegar; delegarlo serializa el trabajo y tira el paralelismo. El catálogo de subagentes hoja está en "## Agentes disponibles".
 
-### Cómo operas
+### Cómo descomponer (tabla de escalado)
 
-- **Descompón** la tarea y, para cada pieza, **lanza el subagente apropiado** vía la tool `Agent`: investigación → `researcher`/`explorer`; implementación → `implementer`; validación → `reviewer`; cierre con PR → `commit-pr-pilot`.
-- **Paraleliza lo independiente**: si necesitas varios investigadores (o varios `implementer` de scopes disjuntos), **emite todas las llamadas `Agent` en un mismo turno** — no una, esperar, otra. Es la palanca que más agiliza. El detalle (fan-out → síntesis, implementers que no se pisen) está en `leader.md`.
-- **Sintetiza tú**: los subagentes escriben en `.claude/progress/<archivo>.md` y te devuelven solo la referencia. Recopila los N y analiza a fondo antes de decidir.
+| Complejidad | Subagentes |
+|---|---|
+| Trivial (1 archivo) | 1 `implementer` |
+| Media (2–3 archivos) | 1 `implementer` → 1 `reviewer` |
+| Multi-bug independiente (sin shared state) | N `implementer` en paralelo (1 por bug, scopes aislados) → 1 `reviewer` que valida los N diffs juntos |
+| Compleja (migración, refactor multi-capa) | `ticket-audit` → 2–3 `researcher`/`explorer` en paralelo → `implementer` → `reviewer` → `commit-pr-pilot` |
+| Muy compleja | Divide en sub-tareas y re-aplica la tabla |
+
+Investigación con preguntas acotadas → `researcher`; mapas amplios (¿dónde vive X?) → `explorer`. Con audit previo, pásale al `implementer` la ruta de `.claude/progress/audit_<ID>.md`.
+
+### Paralelismo (la palanca — mecánica, no opcional)
+
+El paralelismo es **analítico**, no solo velocidad: el valor está en partir el problema en piezas genuinamente independientes y en cómo integras lo que vuelve. La mecánica: cuando la tabla dice "en paralelo", eso se logra emitiendo **TODAS las llamadas `Agent` en un MISMO turno**. Claude por defecto las lanza en serie; el paralelo hay que pedirlo explícito, en un solo mensaje.
+
+- ✅ En un mensaje, invoca `Agent` 3 veces (`explorer` auth, db, api). Corren concurrentes; el total ≈ el más lento.
+- ❌ Invocar auth, esperar su `done -> archivo`, luego db, luego api. Eso es serie y tira lo que el paralelo ahorra.
+
+Regla: sub-tareas **independientes** (no comparten estado ni una depende del output de otra) → mismo turno. Serializa solo con dependencia real (`implementer` → `reviewer`). **`implementer` en paralelo SOLO con archivos disjuntos** (dos que tocan el mismo archivo se pisan → van en serie; en la duda, serie). Reparte el scope explícito antes de abrir el abanico.
+
+**Fan-out → síntesis:** para una pregunta amplia, descompónla en sub-preguntas y lanza un investigador por cada una en paralelo. Cuando vuelven los `done -> archivo`, **recopila y analiza a fondo TÚ**: lee los N archivos juntos, cruza hallazgos (contradicciones, gaps, qué falta) y recién ahí decides la implementación. La síntesis no se delega.
+
+### Ejecución continua (no pausar entre tareas)
+
+Aprobado el plan/scope, ejecuta TODAS las sub-tareas sin pedir confirmación entre nodos. No hagas "hice la 1, ¿sigo con la 2?" — ejecuta el plan. Solo paras por: **BLOCKED** (subagente bloqueado que no puedes resolver), **spec ambigua mid-flight** (gap real fuera de scope), o **ciclo completo** (listo para PR). Cap: 2 ciclos `CHANGES_REQUESTED` sobre la misma tarea → escala al usuario en vez de reintentar en loop.
+
+### Síntesis sin teléfono descompuesto
+
+Instruye a los subagentes a **escribir en `.claude/progress/<archivo>.md`**; tú recibes solo `done -> archivo`. Esa carpeta es SOLO para handoffs efímeros entre agentes (`audit_*`, `explore_*`, `research_*`, `impl_*`, `review_*`); el **estado de sesión** (tarea, plan, blockers) vive en `progress/current.md` (raíz, persiste en git) y lo consolidas tú, nunca los subagentes — cada `implementer` reporta su estado (incluido `blocked`) en su propio `impl_<feature>.md`. Verifica el diff/evidencia tú mismo, no confíes ciego en el reporte. Al cerrar el ciclo, cuando `review_<feature>.md` diga `APPROVED`, invoca `commit-pr-pilot` (pre-flight: working tree limpio, no en `{{branchBase}}`, `{{qualityGate.fast}}` verde, `gh auth status` ok). Si dice `CHANGES_REQUESTED`, lanza otro `implementer` — no el pilot.
 
 ### Cuándo NO orquestar (hazlo tú directo)
 
-- Pregunta conceptual o lectura pura → responde sin subagentes.
-- Cambios en `docs/`, `.claude/`, `CLAUDE.md`, `progress/` → edítalos tú.
-- Una sola línea trivial en un archivo conocido → puede no valer el overhead.
+- Pregunta conceptual / lectura pura → responde sin subagentes.
+- Cambios en `docs/`, `.claude/`, `CLAUDE.md`, `progress/` → **edítalos tú** (esos sí los tocas; el código fuente del proyecto NUNCA — eso es del `implementer`).
+- Una sola línea trivial en un archivo conocido → puede no valer el overhead del fan-out. El fan-out cuesta contexto; no abras 5 explorers para una tarea chica.

package/dist/assets/core/core-assets/presets/background-worker/skills/job-scheduling.md

@@ -31,13 +31,14 @@ await agenda.every('0 * * * *', 'sync-user', { userId });   // recurrente
 await agenda.schedule('in 5 minutes', 'sync-user', { userId }); // one-off
 ```
 
-bullmq es equivalente: `new Worker(name, handler, { concurrency })` + `queue.add(name, data, { repeat, attempts, backoff })`.
+bullmq es equivalente: `new Worker(name, handler, { concurrency, connection })` + `queue.add(name, data, { attempts, backoff })`. Para recurrentes usa **`queue.upsertJobScheduler(id, { pattern: '0 * * * *' }, { name, data })`** — NO la opción `repeat` (deprecada en BullMQ 5); `upsert` con el mismo `id` actualiza el schedule en vez de duplicarlo en cada deploy.
 
 ## Gotchas que muerden
 
-- **Doble disparo**: dos instancias del worker pueden tomar el mismo job. agenda usa `lockLifetime`; bullmq usa locks por job. Aun así, **el handler debe ser idempotente** — no confíes solo en el lock.
+- **Doble disparo**: dos workers pueden tomar el mismo job. agenda usa `lockLifetime`; bullmq re-procesa si el `lockDuration` expira antes de renovarse (`stalledInterval`/`maxStalledCount`). Aun así, **el handler debe ser idempotente** — no confíes solo en el lock.
+- **BullMQ: la conexión IORedis del `Worker` DEBE llevar `maxRetriesPerRequest: null`**, o el arranque falla (error #1). Y setea `removeOnComplete`/`removeOnFail` (`{ age, count }`), sino Redis crece sin límite con jobs viejos.
 - **Reintentos sin backoff** martillan un servicio caído. Configura `attempts` + `backoff` exponencial.
-- **`lockLifetime` corto** + job largo → el lock expira y otro worker lo retoma en paralelo. Ajústalo por encima de la duración real del job.
+- **`lockLifetime`/`lockDuration` corto** + job largo → el lock expira y otro worker lo retoma en paralelo. Ajústalo por encima de la duración real del job.
 
 ## Reglas duras