navori 0.2.1 → 0.2.2

package/README.md

@@ -68,6 +68,7 @@ Un preset aporta skills y reglas específicas del stack además del core. El `in
 | `nextjs` | Next.js (App Router) |
 | `nestjs` | NestJS (backend) |
 | `express-mongoose` | Express + Mongoose (backend) |
+| `background-worker` | Worker de fondo (jobs + colas: agenda / bullmq / amqplib) |
 | `astro` | Astro (static / SSR) |
 | `medusa` | Medusa.js v2 (backend) |
 
@@ -135,6 +136,18 @@ navori ticket show bonum BNM-123
 El workspace también guarda defaults heredables:
 ```bash
 navori init --workspace bonum    # hereda engines, plugins, branchBase, etc.
+
+# Ajustar un default sin editar el manifest a mano
+navori workspace set-default bonum branchBase main
+navori workspace set-default bonum prTarget develop      # PRs van a develop, no a main
+navori workspace set-default bonum engines claude,cursor
+navori workspace set-default bonum plugins.engram.enabled true
+```
+
+Y re-renderizar todos los repos del workspace de una vez:
+```bash
+navori workspace render bonum           # preview (no toca disco)
+navori workspace render bonum --apply    # escribe en cada repo
 ```
 
 Storage: `~/.navori/workspaces/<name>/` (manifest + tickets/ + backups/).
@@ -172,7 +185,8 @@ navori configure plugins              # multiselect de plugins activos
 navori configure quality-gate         # nuevo comando de quality gate
 navori configure language en          # switch a inglés (fallback a es)
 navori configure engines              # multiselect: claude / agents-md / cursor / copilot
-navori configure branch-base develop  # fijar la branch base
+navori configure branch-base main     # punto de fork / rama protegida
+navori configure pr-target develop    # rama destino del PR (gh pr create --base)
 navori configure workspace bonum      # asociar a un workspace
 ```
 

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

@@ -18,20 +18,22 @@ Te encargas del **cierre del ciclo**: commits Conventional bien estructurados y
 ## Cuándo NO activar
 
 - Working tree con cambios sin commitear cuando el usuario solo pidió "abre el PR" → primero commiteas o pides permiso.
-- Estás en `{{branchBase}}` u otra rama protegida → abort + pedir branch.
+- Estás en `{{branchBase}}` o `{{prTarget}}` u otra rama protegida → abort + pedir branch.
 - Harness activo y `.claude/progress/review_*.md` reciente contiene `CHANGES_REQUESTED` → no se crea PR.
 - Quality gate en rojo en este turno.
 
+> **Dos ramas, dos roles:** `{{branchBase}}` es el punto de fork (de dónde ramificaste). `{{prTarget}}` es la rama destino del PR (`gh pr create --base`). Suelen coincidir; cuando difieren, el PR y su diff se calculan contra `{{prTarget}}`.
+
 ## Pre-flight obligatorio
 
 Corre estos chequeos antes de redactar nada. Si algo falla, paras y reportas.
 
 ```bash
 git status --porcelain                                # qué falta commitear
-git rev-parse --abbrev-ref HEAD                       # no puede ser {{branchBase}}
-git fetch origin {{branchBase}} --quiet
-git log origin/{{branchBase}}..HEAD --oneline         # debe haber ≥1 commit (o cambios para commitear)
-git diff origin/{{branchBase}}...HEAD --stat          # scope del PR
+git rev-parse --abbrev-ref HEAD                       # no puede ser {{branchBase}} ni {{prTarget}}
+git fetch origin {{prTarget}} --quiet
+git log origin/{{prTarget}}..HEAD --oneline           # debe haber ≥1 commit (o cambios para commitear)
+git diff origin/{{prTarget}}...HEAD --stat            # scope REAL del PR (contra el target)
 gh auth status                                        # gh autenticado
 ```
 
@@ -59,10 +61,11 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
 
 ## Flujo de PR
 
-1. **Recopilar contexto** (curado, no volcar todo el repo):
-   - `git log origin/{{branchBase}}..HEAD --oneline` — commits incluidos.
-   - `git diff origin/{{branchBase}}...HEAD --stat` — siempre.
-   - `git diff origin/{{branchBase}}...HEAD` — solo si el diff < 500 líneas. Si es mayor, usa solo el stat + lista de archivos + los hunks de los 2–3 archivos más relevantes.
+1. **Recopilar contexto** (curado, no volcar todo el repo). El diff del PR es contra `{{prTarget}}` (lo que GitHub mostrará):
+   - `git log origin/{{prTarget}}..HEAD --oneline` — commits incluidos.
+   - `git diff origin/{{prTarget}}...HEAD --stat` — siempre.
+   - `git diff origin/{{prTarget}}...HEAD` — solo si el diff < 500 líneas. Si es mayor, usa solo el stat + lista de archivos + los hunks de los 2–3 archivos más relevantes.
+   - **Arrastre de commits** (solo si `{{branchBase}}` ≠ `{{prTarget}}`): `git fetch origin {{branchBase}} --quiet` y `git rev-list --count origin/{{prTarget}}..origin/{{branchBase}}`. Si es > 0, `{{branchBase}}` va adelantado de `{{prTarget}}` y tu PR arrastra esos commits ajenos: avisa al usuario y sugiere rebasar sobre `{{prTarget}}` antes de abrir.
    - Ticket si aplica: nombre del branch (ej. `BT-1234-fix-x` → `BT-1234`) o referencia en el primer commit.
    - `.claude/progress/impl_<feature>.md` si existe — decisiones no obvias.
 
@@ -79,6 +82,7 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
 
    ```bash
    gh pr create \
+     --base {{prTarget}} \
      --title "<title validado>" \
      --body "$(cat <<'EOF'
    <body validado>
@@ -86,6 +90,8 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
    )"
    ```
 
+   Siempre pasa `--base {{prTarget}}` explícito — no dejes que `gh` use la rama default del repo. Si el target cambió, ajústalo con `navori configure pr-target`.
+
 5. **Output al usuario**: solo la URL del PR + 1 línea con el título. Nada más.
 
 ## Template del body (default genérico)

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

@@ -0,0 +1,57 @@
+---
+name: formik
+description: Patrones de Formik en React+TS — schema de validación, estado de form, submit, errores por campo. Aplica al crear o tocar formularios con Formik.
+type: reference
+---
+
+# Formik — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un formulario con Formik: definir initial values, validación, submit, o pintar errores. Formik es la fuente de verdad del estado del form — no dupliques sus valores en `useState` paralelos.
+
+## El patrón
+
+Validación declarativa con un schema (Yup/Zod), no a mano en `validate`:
+
+```ts
+const formik = useFormik({
+  initialValues: { email: '', role: 'coachee' },
+  validationSchema: toFormikValidationSchema(loginSchema), // zod, o un Yup schema
+  onSubmit: async (values, { setSubmitting, setStatus }) => {
+    try {
+      await api.login(values);
+    } catch (err) {
+      setStatus(toFormError(err)); // error de servidor, no de campo
+    } finally {
+      setSubmitting(false);
+    }
+  },
+});
+```
+
+En el JSX: `formik.getFieldProps('email')` cablea value/onChange/onBlur; el error se muestra solo si el campo fue tocado: `formik.touched.email && formik.errors.email`.
+
+## Gotchas que muerden
+
+- **Una sola fuente de verdad.** Los valores viven en Formik; nada de `useState` espejo que se desincroniza.
+- **`touched` antes de mostrar error** — pintar errores antes del primer blur frustra al usuario; usa `touched.<campo> && errors.<campo>`.
+- **`isSubmitting`** deshabilita el botón y evita doble submit; resetéalo siempre en `finally`.
+- **Errores de campo vs de servidor**: un fallo de validación va a `errors` (vía schema); un fallo de API va a `setStatus`/`setFieldError`, no se inventa como error de campo.
+- **Forms grandes** re-renderizan todo en cada tecla; aísla con `<Field>`/componentes memoizados si pesa.
+- **`enableReinitialize`** cuando los initial values llegan async (editar un recurso cargado), o el form arranca vacío.
+
+## Reglas duras
+
+1. Validación en un schema (Yup/Zod), nunca lógica suelta en `validate` inline.
+2. Estado del form solo en Formik; sin `useState` paralelos a sus valores.
+3. Error de campo solo tras `touched`; error de servidor vía `setStatus`/`setFieldError`.
+4. `isSubmitting` controla el botón y se limpia en `finally`.
+5. `enableReinitialize` para formularios de edición con carga async.
+
+## Antes de declarar listo
+
+- El form valida contra un schema y muestra errores solo tras blur.
+- El submit deshabilita el botón y maneja el error de servidor aparte.
+- No hay estado del form duplicado fuera de Formik.
+- `{{qualityGate.fast}}` en verde.

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

@@ -0,0 +1,73 @@
+---
+name: joi-validation
+description: Validación de input con Joi (@hapi/joi) en Express — schemas por recurso, middleware validate genérico, DTOs explícitos. Aplica al crear schemas o tocar input validation de body/query/params.
+type: reference
+---
+
+# Joi Validation — el patrón canónico
+
+Un schema por recurso (`<resource>.schema.ts`), validado por un middleware genérico que reemplaza `req[target]` con el valor convertido. Como Joi no infiere tipos, el DTO es una `interface` explícita junto al schema.
+
+## Cuándo usar este skill
+
+Al crear un schema, agregar validación a un endpoint, definir un DTO, o tocar input de body/query/params.
+
+## El patrón
+
+El middleware vive en `helpers/validate.ts`: corre `schema.validate(req[target], { abortEarly: true, convert: true })`, y al fallar lanza `BadRequestError(\`${detail.path.join('.')}: ${detail.message}\`)` con el primer issue. En éxito, reasigna `req[target] = value` (el valor ya convertido). Schema y DTO:
+
+```ts
+const objectId = Joi.string().pattern(/^[a-f\d]{24}$/i).message('Invalid ObjectId');
+
+export const createResourceSchema = Joi.object({
+  owner: objectId.required(),
+  resourceType: Joi.string().valid(...Object.values(ResourceTypeEnum)).required(),
+  page: Joi.number().integer().positive().default(1),
+});
+export const updateResourceSchema = createResourceSchema.fork(
+  Object.keys(createResourceSchema.describe().keys),
+  (s) => s.optional(),
+);
+
+export interface CreateResourceDto {
+  owner: string;
+  resourceType: ResourceTypeEnum;
+  page: number;
+}
+```
+
+En la route: `router.post('/', validate(createResourceSchema, 'body'), ...)`. En el controller el cast `req.body as CreateResourceDto` es seguro porque el middleware ya validó y convirtió.
+
+## Gotchas que muerden
+
+- **ObjectId pelado** (`Joi.string()`) deja pasar `"abc"`; Mongoose lanza CastError 500 en vez de 400 limpio. Usa siempre el helper `objectId`.
+- **`convert: true` es obligatorio** para query/params: las query strings llegan como string y Joi sin `convert` rechaza `Joi.number()`. Con `convert` las castea a number/date/boolean.
+- **`abortEarly`**: con `false` juntas todos los errores; con `true` (default recomendado aquí) cortas en el primero — sé consistente con lo que el middleware reporta.
+
+## Reglas duras
+
+1. Toda validación en el schema, nunca inline en el controller.
+2. El schema vive en `<resource>.schema.ts`, nunca en las routes.
+3. DTO como `interface` explícita al lado del schema — mantenlos en sync (Joi no infiere tipos).
+4. Nada de `Joi.any()`: equivale a `any`, prohibido en código nuevo.
+5. Un solo validador por endpoint — no mezcles Joi + Zod (al migrar entre ambos, migra el endpoint completo).
+6. ObjectId con el helper `objectId`; query/params siempre con `convert: true`.
+
+## Tabla rápida
+
+| Necesito validar | Helper |
+|---|---|
+| ObjectId | `objectId` (pattern `/^[a-f\d]{24}$/i`) |
+| String no vacío | `Joi.string().trim().min(1)` |
+| Number desde query | `Joi.number().integer().positive()` (+ `convert: true`) |
+| Date | `Joi.date()` (+ `convert: true`) |
+| Enum TS / literal | `Joi.string().valid(...Object.values(MyEnum))` |
+| Update parcial | `schema.fork(keys, (s) => s.optional())` |
+| Validación cruzada | `.custom((v, helpers) => ...)` o `Joi.object().and('a', 'b')` |
+
+## Antes de declarar listo
+
+- El schema vive en `<resource>.schema.ts` y el DTO es una `interface` explícita.
+- El endpoint usa `validate(schema, target)`; sin validación inline en el controller.
+- Campos ObjectId con el helper `objectId`; el middleware corre con `convert: true`.
+- `{{qualityGate.fast}}` en verde.

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

@@ -10,6 +10,8 @@ type: reference
 
 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.
 
+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.
+
 ## Patrón canónico
 
 ```ts
@@ -40,7 +42,7 @@ Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si n
 
 - **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`, que es hard delete) y restaura con `doc.restore()`. Plugin sin tipos → `@ts-expect-error` puntual.
+- **Soft delete**: con `mongoose-delete`, `find` ya excluye `deleted: true`; borra con `doc.delete()` (no `findByIdAndDelete`) y restaura con `doc.restore()`.
 
 ## Reglas duras
 
@@ -49,7 +51,6 @@ Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si n
 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`.
-6. **Cast explícito solo cuando hace falta** — `new Types.ObjectId(id)` para aggregations/queries complejas; nada de casts innecesarios.
 
 ## Tabla rápida
 

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

@@ -0,0 +1,59 @@
+---
+name: redux-toolkit
+description: Patrones de Redux Toolkit en React+TS — slices, store tipado, hooks tipados, async thunks, selectores. Aplica al tocar estado global, slices o el store.
+type: reference
+---
+
+# Redux Toolkit — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un slice, el store, async thunks, o leer/escribir estado global. RTK es el estándar — nada de `createStore` pelado, action types a mano, ni `connect`. Estado de servidor (fetch/cache) NO va aquí: eso es TanStack Query. Redux es para estado de cliente compartido (sesión, UI cross-página, carrito).
+
+## El patrón
+
+```ts
+const slice = createSlice({
+  name: 'session',
+  initialState,
+  reducers: {
+    setActive(state, action: PayloadAction<Session>) {
+      state.active = action.payload; // Immer: "mutas" un draft, no el real
+    },
+  },
+  extraReducers: (b) => {
+    b.addCase(loadSession.fulfilled, (s, a) => { s.active = a.payload; });
+  },
+});
+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;
+```
+
+## 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.
+- **No-serializables** (Date, Map, funciones) fuera del store; rompen devtools y persistencia.
+
+## Reglas duras
+
+1. Estado global solo vía slices de RTK; nada de Context improvisado para lo mismo.
+2. Hooks `useAppDispatch`/`useAppSelector` tipados, nunca los crudos sin tipo.
+3. Selecciona lo mínimo y memoiza los derivados con `createSelector`.
+4. Estado de servidor no vive en Redux — eso es cache de queries.
+5. Solo valores serializables en el store.
+
+## Antes de declarar listo
+
+- El slice nuevo expone acciones tipadas y se consume con los hooks tipados.
+- Los selectores derivados están memoizados; los componentes seleccionan lo mínimo.
+- Nada de data de API duplicada en el store si ya hay capa de queries.
+- `{{qualityGate.fast}}` en verde.

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

@@ -0,0 +1,56 @@
+---
+name: socketio
+description: Patrones de Socket.IO en un servicio Node — namespaces, rooms, auth en el handshake, eventos tipados, cleanup. Aplica al tocar realtime, gateways o handlers de socket.
+type: reference
+---
+
+# Socket.IO — convenciones del servicio
+
+## Cuándo usar este skill
+
+Al agregar o tocar realtime: un namespace, un evento, autenticación de conexión, o broadcast a un room. Socket.IO sobre el HTTP server de Express. La regla base: el handler de socket es una capa de transporte, no de negocio — delega al mismo service/controller que usan las rutas HTTP.
+
+## El patrón
+
+```ts
+io.of('/sessions').use(authSocket).on('connection', (socket) => {
+  socket.join(`session:${socket.data.sessionId}`);
+
+  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);
+      ack?.({ ok: true, id: saved._id });
+    } catch (err) {
+      ack?.({ ok: false, error: toClientError(err) });
+    }
+  });
+
+  socket.on('disconnect', () => { /* cleanup timers/subscriptions */ });
+});
+```
+
+`authSocket` valida el token en `socket.handshake.auth.token` y rellena `socket.data` (userId/sessionId). Nunca confíes en un id que venga en el payload del evento sin cruzarlo contra `socket.data`.
+
+## Gotchas que muerden
+
+- **Rooms, no broadcast global.** `io.emit` manda a todos los conectados; usa `io.to(room)` / `socket.to(room)` para no filtrar datos entre sesiones/tenants.
+- **`socket.emit` vs `io.to(...).emit`.** `socket.emit` responde solo al emisor; para incluirte y al resto del room usa `io.to(room)`, para excluirte usa `socket.to(room)`.
+- **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`.
+
+## Reglas duras
+
+1. El handler delega al service; nada de queries ni lógica de negocio inline.
+2. Identidad desde `socket.data` (poblado en auth), nunca desde el payload.
+3. Emite a un room específico; `io.emit` global solo para health/system.
+4. Cada `on(...)` con efectos secundarios tiene su cleanup en `disconnect`.
+5. Errores al cliente vía `ack`/evento `error`, con el mismo `ApiError` mapeado que HTTP.
+
+## Antes de declarar listo
+
+- Los eventos nuevos validan su input igual que un endpoint HTTP.
+- Ningún `io.emit` global salvo señales de sistema; el resto va por room.
+- Auth resuelta en el middleware del namespace, no dentro de los handlers.
+- `{{qualityGate.fast}}` en verde.

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

@@ -0,0 +1,58 @@
+---
+name: tanstack-query
+description: Patrones de TanStack Query (React Query) — query keys, mutations, invalidación, staleTime. Aplica al tocar fetching, cache de servidor o mutaciones de datos remotos.
+type: reference
+---
+
+# TanStack Query — convenciones
+
+## Cuándo usar este skill
+
+Al leer/escribir datos del servidor: un `useQuery`, un `useMutation`, invalidar cache, o paginar. TanStack Query es la fuente de verdad del **estado de servidor** (fetch + cache + revalidación). No lo uses para estado de cliente puro (eso es useState/Redux), ni dupliques su data en otro store.
+
+## El patrón
+
+Query keys estructuradas y centralizadas para invalidar sin strings sueltos:
+
+```ts
+const sessionKeys = {
+  all: ['sessions'] as const,
+  detail: (id: string) => [...sessionKeys.all, id] as const,
+};
+
+const { data, isPending, error } = useQuery({
+  queryKey: sessionKeys.detail(id),
+  queryFn: () => api.getSession(id),
+  staleTime: 30_000,
+  enabled: Boolean(id),
+});
+
+const mutation = useMutation({
+  mutationFn: api.updateSession,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: sessionKeys.all }),
+});
+```
+
+## Gotchas que muerden
+
+- **Query keys como datos, no strings.** Una factory (`sessionKeys`) evita typos y permite invalidar por prefijo (`sessionKeys.all` invalida todos los detalles).
+- **`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).
+
+## Reglas duras
+
+1. Estado de servidor vive en Query; no se copia a otro store.
+2. Query keys desde una factory tipada, nunca arrays literales dispersos.
+3. Tras una mutation, invalida las keys afectadas.
+4. `enabled` en queries dependientes; nada de queries con params inválidos.
+5. `staleTime` explícito cuando la data no cambia cada segundo.
+
+## Antes de declarar listo
+
+- Las keys nuevas salen de la factory y se invalidan tras mutar.
+- Ningún dato de query duplicado en useState/Redux.
+- Las queries dependientes usan `enabled`.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/managed/cierre-sesion.md

@@ -2,7 +2,7 @@
 
 Antes de cerrar la sesión:
 
-1. **Quality gate**: corre `{{qualityGate.full}}` y confirma que pasa (o documenta deuda en `progress/current.md`).
+1. **Quality gate**: {{qualityGate.full}} — confirma que pasa (o documenta deuda en `progress/current.md`).
 2. **History**: agrega entrada en `progress/history.md` con `## YYYY-MM-DD HH:MM <agente> — <resumen>` + cambios + estado del gate.
 3. **Vaciar current**: deja `progress/current.md` en estado `idle` o con el siguiente paso explícito.
 4. **Sin temporales**: borra scratch files, no dejes `console.log`, `debugger`, ni código comentado.

package/dist/assets/core/core-assets/managed/idioma-rol.md

@@ -1,4 +1,4 @@
 ## Idioma y rol
 
-- Código/JSDoc: inglés. Chat: español MX.
+- Código y comentarios (JSDoc/docstrings): inglés. Chat: español MX.
 - Rol Tech Lead Senior. Antes de codear: ¿lo más simple? ¿legible en 6 meses? ¿mantiene patrón existente? Simplicidad > cleverness.

package/dist/assets/core/core-assets/managed/operaciones-seguras.md

@@ -4,5 +4,6 @@ Read-only por default. Antes de mutar datos, esquema o infraestructura (DB, stor
 
 - **DB / queries**: por default solo lectura (`SELECT`, `EXPLAIN`, flags tipo `onlyRead`). `INSERT/UPDATE/DELETE/DROP/ALTER/TRUNCATE` requieren que el usuario lo pida de forma explícita.
 - **Comandos de shell**: inspeccionar es libre (`ls`, `cat`, `git status/diff/log`). Los destructivos (`rm -rf`, `git reset --hard`, force-push, `chmod -R`) los manda el harness a `ask`/`deny` y un hook los bloquea — no intentes evadir esa capa.
+- **Búsqueda de código**: usa las tools nativas `Glob` (archivos por nombre/patrón) y `Grep` (contenido). Son read-only, más rápidas (ripgrep por debajo) y ya saltan `node_modules`/`.git`, así que no piden permiso. Reserva `find`/`grep` por shell para lo que las tools no cubren — búsqueda por metadata del FS (`-size`, `-mtime`, permisos) — y úsalo solo cuando sea críticamente necesario. `find` no está pre-aprobado a propósito: con `-exec`/`-delete` no es read-only puro, así que pedir permiso ahí es la red de seguridad correcta, no un estorbo.
 - **Si una mutación destructiva es legítima y necesaria**: explica qué hace y por qué, y deja que el usuario la confirme o la corra. Nunca la disfraces con variables, subshells o `--no-verify` para saltarte el gate.
 - **Datos sensibles**: no vuelques secretos, PII ni dumps completos a logs, chat o archivos del repo.

package/dist/assets/core/core-assets/presets/background-worker/managed/stack.md

@@ -0,0 +1,18 @@
+## Stack — Background worker (jobs + queues)
+
+Proceso de fondo en Node/TS cuyo trabajo es **procesar jobs y mensajes**, no servir HTTP. El flujo típico: un scheduler (`agenda` / `bullmq` / `node-cron`) dispara jobs en el tiempo, y/o un consumidor de cola (`amqplib` / `bullmq` / `kafkajs`) reacciona a mensajes. Cada handler hace su trabajo (mandar email, push, recalcular, sincronizar) y reporta éxito/fallo a la infraestructura de jobs.
+
+Aunque el repo tenga `express` en deps, **no expone endpoints de negocio** — a lo sumo un `/health` para el orquestador. Si te piden agregar una "ruta", confirma: casi siempre es un job o un consumer nuevo, no un endpoint.
+
+Reglas de oro:
+- **Idempotencia**: un job/mensaje puede entregarse más de una vez. Todo handler debe ser seguro de re-ejecutar (claves de deduplicación, upserts, chequear estado antes de actuar).
+- **Graceful shutdown**: en `SIGTERM`/`SIGINT`, deja de tomar trabajo nuevo, espera a que los jobs en vuelo terminen (con timeout) y cierra conexiones (DB, broker) antes de salir. Nunca mates un job a la mitad sin re-encolar.
+- **Errores explícitos**: un fallo se reintenta con backoff o va a una dead-letter; nunca se traga en silencio. El logging va por el `Logger` estructurado, nunca `console.log`.
+- **Nada de `process.env`** fuera del módulo de config.
+
+Aplica las skills según la capa que toques:
+- `worker-lifecycle` — bootstrap, graceful shutdown, healthcheck, no servir HTTP de negocio.
+- `job-scheduling` — definir/agendar jobs (agenda/bullmq), idempotencia, reintentos con backoff.
+- `queue-consumers` — consumir mensajes (amqplib/bullmq), `ack`/`nack`, dead-letter, backpressure.
+
+El logging y el flujo de tickets/PR los cubre el harness base (agentes `leader`, `implementer`, `reviewer`, `commit-pr-pilot` y las skills core).

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

@@ -0,0 +1,54 @@
+---
+name: job-scheduling
+description: Definir y agendar jobs en un worker (agenda / bullmq) — idempotencia, reintentos con backoff, concurrencia. Aplica al crear o tocar un job programado o recurrente.
+type: reference
+---
+
+# job-scheduling — jobs idempotentes y reintentables
+
+Un job define **qué** hacer; el scheduler decide **cuándo** y **cuántas veces**. Como un job puede correr más de una vez (reintento, doble disparo), el handler debe ser idempotente.
+
+## Cuándo usar este skill
+
+Al definir un job nuevo, agendar uno recurrente, o ajustar reintentos/concurrencia.
+
+## El patrón (agenda)
+
+Un archivo por job (`<name>.job.ts`) que registra el handler; el scheduling vive aparte del handler.
+
+```ts
+export function defineSyncJob(agenda: Agenda) {
+  agenda.define('sync-user', { concurrency: 5, lockLifetime: 60_000 }, async (job) => {
+    const { userId } = job.attrs.data as { userId: string };
+    // idempotente: chequea estado antes de actuar
+    if (await alreadySynced(userId, job.attrs.lastRunAt)) return;
+    await syncUser(userId);
+  });
+}
+
+// scheduling, separado del handler:
+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 })`.
+
+## 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.
+- **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.
+
+## Reglas duras
+
+1. Un job por archivo `<name>.job.ts`; handler separado del scheduling.
+2. Handler **idempotente**: chequea estado antes de mutar; usa upserts/claves de dedup.
+3. Reintentos con backoff exponencial y un tope (`attempts`); sin reintento infinito.
+4. `concurrency` y `lockLifetime` explícitos y coherentes con la duración del job.
+5. Nada de trabajo no idempotente que dependa de "correr exactamente una vez".
+
+## Antes de declarar listo
+
+- El handler es seguro de re-ejecutar (probado corriéndolo dos veces).
+- Reintentos con backoff y tope configurados.
+- `{{qualityGate.fast}}` en verde.

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

@@ -0,0 +1,55 @@
+---
+name: queue-consumers
+description: Consumir mensajes de una cola en un worker (amqplib / bullmq) — ack/nack, dead-letter, prefetch/backpressure, idempotencia. Aplica al crear o tocar un consumidor de cola.
+type: reference
+---
+
+# queue-consumers — consumir sin perder ni duplicar
+
+Un consumer reacciona a mensajes. La regla central: **un mensaje no se confirma (`ack`) hasta que se procesó con éxito**; si falla, se re-encola o va a dead-letter — nunca se pierde en silencio.
+
+## Cuándo usar este skill
+
+Al crear un consumer, manejar fallos de procesamiento, o ajustar prefetch / dead-letter.
+
+## El patrón (amqplib)
+
+```ts
+await channel.prefetch(10); // backpressure: máx 10 sin ack a la vez
+await channel.consume(queue, async (msg) => {
+  if (!msg) return;
+  try {
+    const payload = JSON.parse(msg.content.toString());
+    if (await alreadyProcessed(payload.id)) { channel.ack(msg); return; } // idempotente
+    await handle(payload);
+    channel.ack(msg);
+  } catch (err) {
+    logger.error({ err }, 'consume failed');
+    // requeue una vez; si ya fue redelivered, mándalo a la DLQ (no requeue infinito)
+    channel.nack(msg, false, !msg.fields.redelivered);
+  }
+});
+```
+
+bullmq: lanzar dentro del `Worker` handler re-encola según `attempts`/`backoff`; al agotarse, el job queda `failed` (tu DLQ lógica).
+
+## Gotchas que muerden
+
+- **`nack` con `requeue: true` siempre** → loop infinito si el mensaje es venenoso. Requeue una vez (chequea `redelivered`), luego dead-letter.
+- **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.
+3. `prefetch` explícito para backpressure.
+4. Handler **idempotente**: chequea dedup antes de actuar.
+5. Errores logueados (estructurado), nunca tragados en silencio.
+
+## Antes de declarar listo
+
+- Un mensaje que falla no se pierde ni hace loop infinito (va a DLQ).
+- `prefetch` configurado; el handler es idempotente.
+- `{{qualityGate.fast}}` en verde.

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

@@ -0,0 +1,57 @@
+---
+name: worker-lifecycle
+description: Ciclo de vida de un worker de fondo en Node/TS — bootstrap, graceful shutdown, healthcheck mínimo, sin servir HTTP de negocio. Aplica al tocar el arranque/apagado del proceso o la conexión a DB/broker.
+type: reference
+---
+
+# worker-lifecycle — arrancar y apagar limpio
+
+Un worker no es un HTTP server: arranca conexiones, registra schedulers/consumers, y debe **apagar limpio** sin matar trabajo en vuelo. Su `main` orquesta el bootstrap y un único shutdown idempotente.
+
+## Cuándo usar este skill
+
+Al tocar `index.ts`/`main.ts`, el arranque del scheduler/consumer, la conexión a Mongo/broker, o el manejo de señales.
+
+## El patrón
+
+```ts
+async function main() {
+  const db = await connectMongo(config.mongoUri);
+  const broker = await connectBroker(config.amqpUrl);
+  const scheduler = startScheduler({ db });   // job-scheduling
+  const consumer = startConsumer({ broker });  // queue-consumers
+
+  const shutdown = once(async (signal: string) => {
+    logger.info({ signal }, 'shutting down');
+    await consumer.stop();        // deja de tomar mensajes nuevos
+    await scheduler.stop();       // deja de disparar jobs
+    await drainInflight(15_000);  // espera lo en vuelo, con timeout
+    await broker.close();
+    await db.close();
+    process.exit(0);
+  });
+
+  for (const sig of ['SIGTERM', 'SIGINT'] as const) process.on(sig, () => shutdown(sig));
+}
+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.
+
+## 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í.
+
+## Reglas duras
+
+1. Un único punto de shutdown, idempotente (`once`), escuchando `SIGTERM` y `SIGINT`.
+2. Dejar de aceptar trabajo **antes** de drenar; drenar con timeout; cerrar conexiones al final.
+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.
+
+## Antes de declarar listo
+
+- `SIGTERM` apaga limpio: sin jobs muertos a la mitad, conexiones cerradas.
+- El proceso no expone endpoints de negocio.
+- `{{qualityGate.fast}}` en verde.