navori 0.2.0 → 0.2.2

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.

package/dist/assets/core/core-assets/presets/background-worker.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://navori.dev/schema/navori.preset.v1.json",
+  "id": "background-worker",
+  "displayName": "Background worker (jobs + queues)",
+  "extends": "core",
+  "extras": {
+    "managed": [
+      {
+        "id": "stack-background-worker",
+        "relPath": "presets/background-worker/managed/stack.md"
+      }
+    ],
+    "agents": [],
+    "skills": [
+      {
+        "id": "worker-lifecycle",
+        "relPath": "presets/background-worker/skills/worker-lifecycle.md",
+        "destRelPath": ".claude/skills/worker-lifecycle.md"
+      },
+      {
+        "id": "job-scheduling",
+        "relPath": "presets/background-worker/skills/job-scheduling.md",
+        "destRelPath": ".claude/skills/job-scheduling.md"
+      },
+      {
+        "id": "queue-consumers",
+        "relPath": "presets/background-worker/skills/queue-consumers.md",
+        "destRelPath": ".claude/skills/queue-consumers.md"
+      }
+    ],
+    "hooks": []
+  },
+  "invariants": [
+    "worker-lifecycle",
+    "job-scheduling",
+    "queue-consumers",
+    "graceful shutdown"
+  ]
+}

package/dist/assets/core/core-assets/presets/express-mongoose/managed/stack.md

@@ -1,8 +1,8 @@
 ## Stack — Express + Mongoose
 
-Backend HTTP sobre Express + Mongoose/MongoDB en TypeScript. Las peticiones fluyen en capas: `route → validate(Zod) → asyncHandler → controller → Model (Mongoose) → ApiResponse`. Los controllers tocan los Models directo (sin repository wrappers); los errores se propagan vía `ApiError` y las respuestas se envuelven en `ApiResponse`. El logging va por el `Logger` de winston, nunca `console.log`.
+Backend HTTP sobre Express + Mongoose/MongoDB en TypeScript. Las peticiones fluyen en capas: `route → validate(schema) → asyncHandler → controller → Model (Mongoose) → ApiResponse`. Los controllers tocan los Models directo (sin repository wrappers); los errores se propagan vía `ApiError` y las respuestas se envuelven en `ApiResponse`. El logging va por el `Logger` de winston, nunca `console.log`.
 
-Regla de oro: nada de `res.json` / `res.status(500)` crudos; nada de `console.log`; nada de `process.env` fuera del módulo de config. La validación SIEMPRE ocurre en el boundary con Zod, y todo `ObjectId` se construye con `new Types.ObjectId(...)`. Aplica las skills `express-routes`, `mongoose`, `zod-validation`, `mongo-aggregations` y `winston-logging` según la capa que toques.
+Regla de oro: nada de `res.json` / `res.status(500)` crudos; nada de `console.log`; nada de `process.env` fuera del módulo de config. La validación SIEMPRE ocurre en el boundary (con el validador del repo — Zod o Joi), y todo `ObjectId` se construye con `new Types.ObjectId(...)`. Aplica las skills `express-routes`, `mongo-aggregations` y `winston-logging` del preset según la capa que toques. Las skills de `mongoose` y de validación (`zod-validation` o `joi-validation`) se inyectan según las dependencias que detecte navori en el repo — si están en `.claude/skills/`, aplícalas.
 
 El trabajo de un ticket sigue el pipeline documentado en la skill `ticket-intake` (la orquestadora). No es un generador de specs: es un protocolo que el `leader` ejecuta invocando agentes y skills en orden, con gates objetivos y artefactos en `.claude/progress/`. Mapeo de fases a la infraestructura de navori:
 

package/dist/assets/core/core-assets/presets/express-mongoose/skills/pr-create.md

@@ -1,26 +1,29 @@
 ---
 name: pr-create
-description: Crea un PR en GitHub contra la rama base del repo, delegando title/body a un modelo y validando el output. Antes de crear cualquier PR al cerrar el ciclo de un ticket (Fase 8 de ticket-intake).
+description: Crea un PR en GitHub contra la rama target del repo, delegando title/body a un modelo y validando el output. Antes de crear cualquier PR al cerrar el ciclo de un ticket (Fase 8 de ticket-intake).
 type: reference
 ---
 
 <!-- candidate: workflow-backend -->
 
-# pr-create — crear PR contra `{{branchBase}}`
+# pr-create — crear PR contra `{{prTarget}}`
 
 ## Cuándo usar este skill
 
-Al cierre del ciclo, tras el `APPROVED` del reviewer. Es la Fase 8 del pipeline `ticket-intake`. El pre-flight es bloqueante: ningún PR sale si el gate no está verde o si falta aprobación cuando el harness está activo.
+Al cierre del ciclo, tras el `APPROVED` del reviewer (Fase 8 de `ticket-intake`). El pre-flight es bloqueante: ningún PR sale con el gate en rojo o sin aprobación (harness activo).
+
+`{{branchBase}}` es el punto de fork; `{{prTarget}}` es la rama destino del PR. Cuando difieren, el PR y su diff van contra `{{prTarget}}`.
 
 ## Pre-flight (bloqueante — cualquier check falla → ABORT con mensaje claro)
 
 1. **Working tree limpio** o solo cambios del feature: `git status --porcelain`. Si hay cambios uncommitted que NO son del feature, párate y pregunta.
-2. **No estás en rama base**: aborta si la rama es `main|master|{{branchBase}}`.
+2. **No estás en una rama protegida**: aborta si la rama actual es `main|master|{{branchBase}}|{{prTarget}}`.
 3. **`gh` autenticado**: `gh auth status`.
 4. **Gate verde en este turno**: `{{qualityGate.fast}}`. Falla → manda al implementer.
 5. **Review APPROVED** (si el harness está activo): `grep -q APPROVED .claude/progress/review_*.md`. Falla → manda al reviewer.
-6. **Hay commits pusheables**: `git log origin/{{branchBase}}..HEAD --oneline`. Vacío → nada que PR-ear.
-7. **Branch sincronizada**: `git fetch origin {{branchBase}}` y `git log HEAD..origin/{{branchBase}} --oneline`. Si origin va adelante, considera rebase y pregunta al usuario.
+6. **Hay commits para el PR**: `git fetch origin {{prTarget}} --quiet` y `git log origin/{{prTarget}}..HEAD --oneline`. Vacío → nada que PR-ear.
+7. **Branch sincronizada**: `git log HEAD..origin/{{prTarget}} --oneline`. Si origin va adelante, rebase y pregunta.
+8. **Arrastre de commits** (solo si `{{branchBase}}` ≠ `{{prTarget}}`): `git rev-list --count origin/{{prTarget}}..origin/{{branchBase}}`. Si es > 0, `{{branchBase}}` va adelantado de `{{prTarget}}` y el PR arrastra esos commits ajenos: avisa y sugiere `git rebase origin/{{prTarget}}` antes de abrir.
 
 ## Push y redacción
 
@@ -28,32 +31,29 @@ Si la branch no está pusheada: `git push -u origin "$current_branch"`. Si el up
 
 Delega title + body a un `Agent` (modelo rápido). Reglas que le impones:
 - **Title**: Conventional Commit con scope de tu dominio, ≤70 chars, español MX, sin emojis ni puntuación final.
-- **Body**: markdown con secciones fijas `## Resumen`, `## Cambios`, `## Test plan`, `## Notas` (opcional). Tono directo, sin "Generated by Claude".
-- **Contexto al redactor**: branch, base `{{branchBase}}`, ticket, `impl_<feature>.md`, `review_<feature>.md`, `git log {{branchBase}}..HEAD --oneline` y `--stat`.
+- **Body**: secciones fijas `## Resumen`, `## Cambios`, `## Test plan`, `## Notas` (opcional). Tono directo, sin "Generated by Claude".
+- **Contexto al redactor**: branch, base `{{prTarget}}`, ticket, `impl_<feature>.md`, `review_<feature>.md`, y el diff REAL del PR — `git log origin/{{prTarget}}..HEAD --oneline` + `git diff origin/{{prTarget}}...HEAD --stat`.
 - **Output**: JSON exacto `{"title": "...", "body": "..."}` sin fences.
 
-Valida el output: `title` ≤70 y matchea `^(feat|fix|refactor|chore|docs|style|test|build|ci|perf)(\(.+\))?: `; `body` contiene Resumen, Cambios y Test plan. Si falla, re-invoca al redactor con el feedback (máx. 2 reintentos).
+Valida: `title` ≤70 y Conventional Commit; `body` con Resumen, Cambios y Test plan. Si falla, reintenta (máx. 2).
 
 ## Crear el PR
 
 ```bash
-gh pr create --base {{branchBase}} --title "$title" --body "$body"
+gh pr create --base {{prTarget}} --title "$title" --body "$body"
 ```
 
 Captura la URL del output y muéstrasela al usuario.
 
 ## Reglas duras
 
-- **NUNCA `git push --force`** sin que lo pida el usuario.
-- **NUNCA `--base main` ni `--base master`.** Siempre `--base {{branchBase}}`.
-- **NUNCA `--no-verify`** en commits previos.
+- **NUNCA `git push --force`** ni `--no-verify` sin que lo pida el usuario.
+- **Siempre `--base {{prTarget}}`.** No lo cambies a mano; si el target del repo cambió, ajústalo con `navori configure pr-target`.
 - **Cambios uncommitted ajenos al feature** → párate y pregunta, no los arrastres al PR.
-- **No agregues** "Generated with Claude" ni emojis al body.
 - **Reviewers/labels**: no los agregues automático salvo que el usuario lo pida.
 
 ## Antes de declarar listo
 
-- El pre-flight pasó completo (gate verde, branch ≠ base, commits pusheables, review APPROVED si aplica).
-- El title pasó la validación Conventional Commit (≤70 chars) y el body tiene las secciones fijas.
-- El PR se creó contra `{{branchBase}}` y su URL quedó mostrada al usuario.
-- Post-PR: `mem_save` de cualquier decisión no obvia, entrada en `history.md`, `current.md` a `state: idle`, y `mem_session_summary`.
+- El pre-flight pasó completo y el title/body validaron.
+- El PR se creó contra `{{prTarget}}` y su URL quedó mostrada al usuario.
+- Post-PR: `mem_save` de decisiones no obvias, entrada en `history.md`, `current.md` a `state: idle`, y `mem_session_summary`.

package/dist/assets/core/core-assets/presets/express-mongoose.json

@@ -17,16 +17,6 @@
         "relPath": "presets/express-mongoose/skills/express-routes.md",
         "destRelPath": ".claude/skills/express-routes.md"
       },
-      {
-        "id": "mongoose",
-        "relPath": "presets/express-mongoose/skills/mongoose.md",
-        "destRelPath": ".claude/skills/mongoose.md"
-      },
-      {
-        "id": "zod-validation",
-        "relPath": "presets/express-mongoose/skills/zod-validation.md",
-        "destRelPath": ".claude/skills/zod-validation.md"
-      },
       {
         "id": "mongo-aggregations",
         "relPath": "presets/express-mongoose/skills/mongo-aggregations.md",
@@ -66,8 +56,6 @@
     "ApiResponse",
     "mongoose",
     "Types.ObjectId",
-    "zod-validation",
-    "z.coerce",
     "ticket-intake",
     "new-resource"
   ]

package/dist/assets/core/core-assets/settings/settings-base.json

@@ -14,6 +14,18 @@
       "Bash(git branch*)",
       "Bash(git fetch*)",
       "Bash(git stash*)",
+      "Bash(git blame*)",
+      "Bash(git describe*)",
+      "Bash(git rev-parse*)",
+      "Bash(git ls-files*)",
+      "Bash(git cat-file*)",
+      "Bash(git shortlog*)",
+      "Bash(git tag -l*)",
+      "Bash(git tag --list*)",
+      "Bash(git config --get*)",
+      "Bash(git config --list*)",
+      "Bash(git remote -v*)",
+      "Bash(git remote get-url*)",
       "Read",
       "Glob",
       "Grep",
@@ -26,7 +38,16 @@
       "Bash(which:*)",
       "Bash(file:*)",
       "Bash(stat:*)",
-      "Bash(tree:*)"
+      "Bash(tree:*)",
+      "Bash(grep:*)",
+      "Bash(jq:*)",
+      "Bash(diff:*)",
+      "Bash(cut:*)",
+      "Bash(du:*)",
+      "Bash(df:*)",
+      "Bash(realpath:*)",
+      "Bash(dirname:*)",
+      "Bash(basename:*)"
     ],
     "ask": [
       "Bash(rm -rf *)",