navori 0.2.8 → 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

@@ -15,7 +15,7 @@ Tu único trabajo como orquestador es **descomponer y coordinar**, nunca impleme
 
 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:
@@ -91,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`:
@@ -131,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/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

@@ -31,7 +31,7 @@ Aprobado el plan/scope, ejecuta TODAS las sub-tareas sin pedir confirmación ent
 
 ### Síntesis sin teléfono descompuesto
 
-Instruye a los subagentes a **escribir en `.claude/progress/<archivo>.md`**; tú recibes solo `done -> archivo`. 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.
+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)
 

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
 

package/dist/assets/core/core-assets/presets/background-worker/skills/queue-consumers.md

@@ -31,21 +31,23 @@ await channel.consume(queue, async (msg) => {
 });
 ```
 
-bullmq: lanzar dentro del `Worker` handler re-encola según `attempts`/`backoff`; al agotarse, el job queda `failed` (tu DLQ lógica).
+bullmq: lanzar dentro del `Worker` handler re-encola según `attempts`/`backoff`; al agotarse, el job queda `failed`. **`failed` NO es una DLQ**: nadie reprocesa ni alerta solo — escucha `worker.on('failed')` / `QueueEvents`, o mueve a una `failed`-queue dedicada con monitoreo.
 
 ## Gotchas que muerden
 
-- **`nack` con `requeue: true` siempre** → loop infinito si el mensaje es venenoso. Requeue una vez (chequea `redelivered`), luego dead-letter.
+- **`redelivered` es una heurística pobre para reintentos.** Se activa en **cualquier** re-entrega (incluida recuperación de conexión) y solo distingue "0 vs ≥1", no un contador; `nack` con requeue reencola en la **cabeza** → hot-loop sin backoff. El patrón robusto es **dead-letter exchange (DLX) + retry queue con TTL** (o header `x-death`/contador), no `redelivered`.
+- **Dedup atómica, no check-then-act.** `if (await alreadyProcessed(id))` es TOCTOU: con `prefetch>1` o dos consumers, dos entregas pasan ambas el check. Usa `INSERT` con unique index (captura duplicate-key) o `SET NX` en Redis.
+- **Parse fallido = no-retryable** → DLQ directo, no requeue (un payload corrupto haría loop eterno).
 - **Sin `prefetch`** el consumer traga toda la cola en memoria. Fija un prefetch acorde a la duración del handler.
 - **`ack` antes de procesar** = pérdida de mensajes si el handler crashea. Confirma **después** del éxito.
 - **Mensajes duplicados** son normales (redelivery). El handler debe ser idempotente.
 
 ## Reglas duras
 
-1. `ack` solo tras éxito; en fallo, `nack`/requeue acotado o dead-letter.
-2. Nunca requeue infinito de un mensaje venenoso — DLQ tras el primer redelivery.
+1. `ack` solo tras éxito; en fallo, reintento acotado (DLX + retry queue / contador) o dead-letter.
+2. Nunca requeue infinito de un mensaje venenoso; un parse fallido va directo a DLQ.
 3. `prefetch` explícito para backpressure.
-4. Handler **idempotente**: chequea dedup antes de actuar.
+4. Handler **idempotente** con dedup **atómica** (unique index / `SET NX`), no check-then-act.
 5. Errores logueados (estructurado), nunca tragados en silencio.
 
 ## Antes de declarar listo

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

@@ -38,6 +38,8 @@ main().catch((err) => { logger.error({ err }, 'fatal on boot'); process.exit(1);
 
 `once` garantiza que dos señales seguidas no disparen dos shutdowns. El orden importa: **primero dejas de aceptar trabajo**, luego drenas lo en vuelo, luego cierras conexiones.
 
+Sin HTTP server no hay red de seguridad: registra también `process.on('unhandledRejection'|'uncaughtException', ...)` con log estructurado + shutdown, o una promesa sin catch mata el proceso en silencio. El timeout de drenado debe ser **menor** que el `terminationGracePeriodSeconds` del orquestador (30s default en K8s), o el pod recibe `SIGKILL` a media faena. En BullMQ, `worker.close()` **no** tiene timeout propio: acótalo con un `Promise.race` contra tu propio timeout.
+
 ## Healthcheck (si el orquestador lo exige)
 
 Un solo endpoint `/health` con un `http.createServer` mínimo está bien — **no es** una API. Devuelve `200` si las conexiones (DB, broker) están vivas. Nada de rutas de negocio aquí.
@@ -49,6 +51,7 @@ Un solo endpoint `/health` con un `http.createServer` mínimo está bien — **n
 3. Nunca `process.exit` a mitad de un job sin re-encolarlo o dejarlo `nack`-eado.
 4. Sin rutas HTTP de negocio. `/health` es el único endpoint permitido.
 5. Errores de arranque → log estructurado + `exit(1)`; no arranques a medias.
+6. Registra `unhandledRejection`/`uncaughtException`; drain-timeout < grace period del orquestador.
 
 ## Antes de declarar listo
 

package/dist/assets/core/core-assets/presets/express-mongoose/skills/mongo-aggregations.md

@@ -10,7 +10,7 @@ Aggregation pipelines para joins, agregaciones y listados paginados con count en
 
 ## Cuándo usar este skill
 
-Usa aggregation en vez de `find + populate` cuando filtras por un campo de la colección child (populate no filtra), agregas/cuentas/agrupas (populate no agrega), o la performance importa (populate hace N queries; aggregation, 1). Para CRUD simple, `find()` directo basta.
+Usa aggregation en vez de `find + populate` cuando filtras/ordenas/agrupas por un campo de la colección child (populate no lo hace: batchea con `$in` pero no filtra server-side). Para CRUD simple, `find()` directo basta.
 
 ## El patrón
 
@@ -30,36 +30,34 @@ const [result] = await Model.aggregate<ResultType>(pipeline);
 
 ## Gotchas que muerden
 
-- **ObjectId en `$match`**: Mongoose NO castea ObjectIds en aggregation. Un string no matchea y falla silencioso. Usa `new Types.ObjectId(id)` (el `new` es obligatorio en Mongoose 6+). Excepción: si el schema declara el campo como `String`, va string directo — revisa el schema antes de decidir.
+- **ObjectId en `$match`**: Mongoose NO castea ObjectIds en aggregation. Un string no matchea y falla silencioso. Usa `new Types.ObjectId(id)` (o string directo si el schema declara el campo como `String`).
 - **`$unwind` sin `preserveNullAndEmptyArrays`** pierde los docs sin match (INNER en vez de LEFT join).
 - **`from` es el nombre real de la colección** (lowercase plural, p. ej. `related`), no el Model (`Related`). Si dudas: `db.getCollectionNames()`.
+- **Soft-delete NO se aplica solo.** El pipeline ignora `mongoose-delete` y todo middleware/filtro del schema: `find` esconde los borrados, `aggregate` los **devuelve** → leak. Agrega `{ deleted: { $ne: true } }` en el primer `$match`.
+- **`$lookup` sin índice en `foreignField` = COLLSCAN por doc de entrada.** Asegúrate de que el `foreignField` esté indexado, o el join es O(n·m).
+- **`$group`/`$sort` grandes revientan a los 100 MB/stage** ("Exceeded memory limit") → `.option({ allowDiskUse: true })`. `$match`/`$sort` solo usan índice al inicio; ponlos arriba.
 
 ## Reglas duras
 
-1. `$match` antes del primer `$lookup` — filtra primero, no proceses toda la colección.
+1. `$match` primero (antes del `$lookup`), lo más arriba posible; incluye `{ deleted: { $ne: true } }` si el modelo usa soft-delete (el pipeline no lo aplica solo).
 2. `new Types.ObjectId(id)` en `$match` cuando el campo es ObjectId (string directo si el schema es `String`).
 3. `$unwind` con `preserveNullAndEmptyArrays` cuando esperas left-join.
 4. `aggregate<T>(...)` siempre tipado — Mongoose no tipa el output; sin esto es `any[]`.
-5. `$project` sin mezclar `1` y `0` (salvo `_id`) — Mongo rechaza el pipeline. Úsalo para ocultar campos sensibles.
-6. Filtra en `$match`, no en JS — traer todo y filtrar en código desperdicia tráfico y memoria.
+5. `$project` sin mezclar `1` y `0` (salvo `_id`); úsalo para ocultar campos sensibles.
+6. `foreignField` indexado; `allowDiskUse` para `$group`/`$sort` grandes.
 
 ## Tabla rápida
 
 | Stage | Para qué |
 |---|---|
-| `$match` | WHERE — lo más temprano posible |
-| `$lookup` | JOIN (`from` = colección real, lowercase plural) |
-| `$unwind` | Aplanar el array del lookup a doc individual |
+| `$match` | WHERE — lo más temprano posible (usa índice solo al inicio) |
+| `$lookup` | JOIN (`from` = colección real, lowercase plural; `foreignField` indexado) |
+| `$unwind` | Aplanar el array del lookup (`preserveNullAndEmptyArrays` = left-join) |
 | `$project` | SELECT / renombrar / ocultar sensibles |
-| `$group` | `$sum:1` count, `$sum/$avg/$min/$max`, `$push`, `$addToSet` |
-| `$facet` | docs + count en una query (paginación) |
-| `$sort` / `$skip` / `$limit` | Orden y paginación |
+| `$group` / `$facet` | agregados (`$sum/$avg/$push`) / docs + count en una query |
 
 ## Antes de declarar listo
 
-- El `$match` por ObjectId usa `new Types.ObjectId(id)` (o string si el schema declara `String`).
-- Hay un `$match` antes del primer `$lookup`.
-- `$unwind` usa `preserveNullAndEmptyArrays` si esperas left-join.
-- El resultado está tipado con `aggregate<T>(...)`.
-- `$project` oculta campos sensibles y no mezcla `1`/`0`.
+- `$match` temprano con `new Types.ObjectId(id)` y `{ deleted: { $ne: true } }` si aplica soft-delete.
+- Resultado tipado con `aggregate<T>(...)`; `$project` oculta sensibles y no mezcla `1`/`0`.
 - `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/presets/express-mongoose/skills/new-endpoint.md

@@ -4,8 +4,6 @@ description: Sumar un endpoint nuevo a un recurso Express + Mongoose que ya exis
 type: reference
 ---
 
-<!-- candidate: workflow-backend -->
-
 # new-endpoint — sumar un endpoint a un recurso existente
 
 ## Cuándo usar este skill

package/dist/assets/core/core-assets/presets/express-mongoose/skills/new-resource.md

@@ -4,8 +4,6 @@ description: Crear un recurso end-to-end en un backend Express + Mongoose (Model
 type: reference
 ---
 
-<!-- candidate: workflow-backend -->
-
 # new-resource — recurso end-to-end
 
 ## Cuándo usar este skill