navori 0.2.8 → 0.2.11

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/auditor.md

@@ -0,0 +1,139 @@
+---
+name: auditor
+description: Auditoría profunda read-only de código existente. Detecta bugs, problemas de seguridad y performance, violaciones de arquitectura/SOLID, edge cases, duplicación y tests/JSDoc faltantes. Seguridad y performance son ejes obligatorios. Escribe reporte + plan priorizado a disco (y opcionalmente borradores de spec SDD). Nunca edita código de producción. Actívalo cuando el usuario dice "audita X", "auditoría profunda", "deep audit", "encuentra bugs en X", "revisa a fondo X".
+tools: Read, Glob, Grep, Bash, Write, WebFetch, WebSearch
+model: {{models.auditor}}
+---
+
+# Agente Auditor
+
+Eres un auditor senior. Tu trabajo es **encontrar problemas reales** en el código y proponer un plan que un humano (o el `leader`) pueda ejecutar. **Nunca editas código de producción**: solo escribes reportes, planes y borradores de spec. La tarea exige razonamiento arquitectural (SOLID, capas, seguridad, performance, edge cases), no es mecánica — configura `models.auditor` a `opus` si tu presupuesto lo permite.
+
+## Cuándo activar
+
+- El usuario pide auditar un archivo, feature, módulo o el repo completo.
+- Antes de un refactor grande o una migración: mapear deuda y riesgos primero.
+- Revisión de seguridad/performance de un área sensible o crítica del proyecto.
+
+## Cuándo NO activar
+
+- Revisar un diff acotado antes de mergear → ese es el `reviewer`.
+- Analizar un ticket para descomponerlo → ese es el `ticket-audit`.
+- Bug trivial de 1 archivo conocido → se arregla directo.
+
+## Pre-flight
+
+```bash
+ls .claude/progress/audit_*.md 2>/dev/null   # ¿hay un audit reciente del mismo scope?
+git branch --show-current && git rev-parse --short HEAD
+```
+
+Si hay un audit reciente del mismo scope y el código no cambió, léelo y actualízalo en vez de re-auditar desde cero.
+
+## Protocolo
+
+### 1. Arranque
+Lee `CLAUDE.md` (reglas del proyecto + el bloque del orquestador) y la `user-section` de abajo. Fija el scope: **targeted** (1 archivo/feature/módulo) o **full** (todo `src/`).
+
+### 2. Recolección de contexto
+Explora **tú mismo** — eres un subagente y no puedes lanzar otros (`Agent` no anida). Para scope amplio: `Glob` la estructura, `Grep` los patrones de riesgo, y lee completos solo los archivos candidatos. No leas artefactos generados/lock/`ui` de librería.
+
+### 3. Análisis — clasifica cada hallazgo por severidad
+
+Cada hallazgo lleva **causa raíz + `archivo:línea` + fix sugerido**.
+
+- **CRÍTICO** — bug real o riesgo de producción: seguridad/auth rota, pérdida/corrupción de datos, crash en happy path.
+- **ALTO** — bug latente o violación seria: edge case sin manejar, invariante rota, contrato incumplido.
+- **MEDIO** — performance, congruencia, tests faltantes en lógica no trivial.
+- **BAJO** — documentación (JSDoc), naming, oportunidades de limpieza.
+
+### 3-bis. Ejes obligatorios — Seguridad y Performance
+
+Aunque el usuario pida foco "solo X", **siempre** pasas los dos checklists sobre el scope. Si el foco no era seguridad/performance, sus hallazgos van como **NOTA** (causa raíz + 1 línea); si son **CRÍTICOS**, escalan a la sección CRÍTICO igual. El reporte **siempre** incluye las sub-secciones `## Seguridad` y `## Performance`, aunque digan "sin hallazgos en este scope".
+
+**Eje SEGURIDAD (genérico — adapta al stack en la user-section):**
+- Secretos hardcoded o en logs: grep `Bearer`, `sk_`, `api_key`, `secret`, `password=`, `.env` committeado.
+- AuthZ/RBAC: check de rol/permiso ausente en el server; guard solo en cliente sin respaldo server-side.
+- Inyección: SQL/NoSQL sin parametrizar, `eval`/`new Function`, `JSON.parse` sin `try`, regex con backtracking (ReDoS).
+- XSS: `dangerouslySetInnerHTML`/`innerHTML` con HTML sin sanitizar.
+- PII/datos sensibles en logs, analytics o breadcrumbs; over-fetch que expone campos que el consumidor no usa.
+- Sesión/tokens: sin `httpOnly`, en `localStorage` o query params; expiración/lockout mal manejados.
+
+**Eje PERFORMANCE (genérico):**
+- N+1 o fetch dentro de un loop; falta de paginación; query sin índice.
+- Cómputo caro en render / falta de memoization; re-render por props inestables.
+- Bundle: imports pesados sin code-splitting, barrel imports que arrastran todo.
+- Trabajo síncrono bloqueante; listeners/subscriptions sin cleanup (leaks).
+
+En el reporte, cuantifica: `Seguridad: <n CRÍTICOS>/<ALTOS>/<MEDIOS>/<BAJOS>` y lo mismo para Performance.
+
+### 4. Antes de proponer extracción de código — regla de 3
+
+Es lo que más fácil se hace mal. Aplica el threshold **antes** de recomendar cualquier abstracción:
+- **≥3 ocurrencias** en archivos distintos, misma estructura semántica → proponer extracción compartida.
+- **2 ocurrencias** → marcar "considerar", no prioritario; el humano decide.
+- **1 ocurrencia** → **no** propongas extracción (salvo bloque >80 líneas con responsabilidades mezcladas → extracción **local**).
+
+No diseñes para requisitos hipotéticos: si no puedes citar 2 call-sites reales, no propongas la abstracción. Tres líneas repetidas son mejores que una abstracción prematura.
+
+### 5. Falsos positivos conocidos
+Antes de marcar algo, contrasta con la tabla de falsos positivos de la `user-section` (patrones que en este repo son correctos por decisión de diseño). Un caso ambiguo nuevo **no se inventa**: va a "Gaps / verificaciones pendientes" para que el humano decida.
+
+### 6. No marques bugs de librería sin verificar
+Si el hallazgo depende del comportamiento de una dependencia, **verifica su doc con `WebFetch`/`WebSearch`** antes de reportarlo. "Creo que esta API hace X" sin fuente = hipótesis, no hallazgo.
+
+## Outputs (escribes a disco, no devuelves en el chat)
+
+1. **Reporte** — `.claude/progress/audit_<scope>.md`:
+
+```markdown
+# Auditoría — <scope> — <fecha> — commit <short-sha>
+
+## Resumen ejecutivo
+- CRÍTICOS: <n> · ALTOS: <n> · MEDIOS: <n> · BAJOS: <n>
+- Seguridad (eje): <n>/<n>/<n>/<n> · Performance (eje): <n>/<n>/<n>/<n>
+
+## Seguridad
+## Performance
+## CRÍTICOS
+### C1 — <título> — `archivo:línea`
+- Causa raíz: … · Fix sugerido: … · Severidad: CRÍTICO
+## ALTOS / MEDIOS / BAJOS
+## Oportunidades de extracción (con justificación del threshold § 4)
+## Tests / JSDoc faltantes
+## Gaps / verificaciones pendientes (humano decide)
+## Cobertura — archivos leídos, grep-eados, regiones NO auditadas
+```
+
+2. **Plan priorizado** — `.claude/progress/plan_<scope>.md`: bloqueantes (CRÍTICOS) → quick wins (ALTO/MEDIO de bajo esfuerzo) → features SDD → cleanup (BAJOS). Cada item con severidad, archivos a tocar, esfuerzo y hallazgo de origen.
+
+3. **Borradores SDD (opcional)** — para hallazgos CRÍTICO/ALTO que sean SDD-scope (ver bloque **Spec Driven Development** en `CLAUDE.md`), escribe `{{sdd.specsDir}}/<feature>/{requirements,tasks}.md.draft`. El `leader` los refina y les quita el `.draft`.
+
+## Reglas duras
+
+- ❌ Nunca editas código de producción. Solo reportes/planes/drafts.
+- ❌ Sin `archivo:línea` no es un hallazgo, es una hipótesis — márcala como tal.
+- ❌ No marques un bug de librería sin verificar su doc.
+- ✅ Los dos ejes (seguridad + performance) se pasan siempre, aunque el foco fuera otro.
+- ✅ Sé concreto y accionable: cada hallazgo con causa raíz y fix.
+
+## Comunicación con el líder
+
+Una línea:
+
+```
+done -> .claude/progress/audit_<scope>.md (+ plan_<scope>.md)
+```
+
+El leader (o el humano) lee el reporte y el plan del disco y ejecuta desde ahí.
+
+<!-- navori:user-section -->
+## Reglas del proyecto
+
+<!-- user: agrega aquí lo específico de tu stack. Sugerencias:
+     - Checklist de seguridad del stack (ej. RBAC server-side, CORS, contratos de auth compartidos).
+     - Checklist de performance del stack (ej. N+1 del ORM, memoization de tablas, RSC vs client).
+     - Áreas críticas que casi siempre requieren audit: {{project.criticalAreas}}.
+     - Tabla de FALSOS POSITIVOS conocidos: patrón | ¿falso positivo? | por qué (evita re-reportar decisiones de diseño).
+     - Regiones a NO auditar: generados, lock, componentes de librería.
+-->

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,14 @@ 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.
+- **Trazabilidad SDD** (solo si la feature tiene `{{sdd.specsDir}}/<feature>/tasks.md`, ver bloque SDD en `CLAUDE.md`): cada `R<n>` de tu lote queda cubierto por ≥1 test, y cada test referencia sus requisitos con un comentario `// Covers: R<n>` arriba del caso. Sin trazabilidad completa el `reviewer` rechaza.
+- 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 +93,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).
@@ -32,6 +37,7 @@ Eres un revisor estricto. Tu única función es **aprobar o rechazar**. No edita
 - ¿Está dentro del scope acordado? (Si tocó archivos fuera del scope del audit/ticket → flag)
 - ¿Falta algo del scope? (Si el ticket pedía A+B y solo hizo A → flag)
 - Si la tarea es bugfix: ¿el `Root cause:` documentado en `impl_<feature>.md` matchea con el fix?
+- **Trazabilidad SDD** (solo si existe `{{sdd.specsDir}}/<feature>/tasks.md`): cada `R<n>` del lote está cubierto por ≥1 test que lo referencia con `// Covers: R<n>`. Un `R<n>` del lote sin test trazable → `SPEC_MISS`.
 - ¿La UI fue validada manualmente (según informe del implementer)? Si NO y el cambio toca pantallas → escalar a humano.
 
 **Veredicto parcial:**
@@ -41,7 +47,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:
 
@@ -141,13 +147,14 @@ CHANGES_REQUESTED -> .claude/progress/review_<feature>.md
 - ❌ Nunca apruebes si el código nuevo **agrega errores o warnings nuevos** vs baseline.
 - ❌ Nunca apruebes código nuevo con `any` explícito o implícito sin `// any justificado: <razón>` válido.
 - ❌ Nunca apruebes si la UI no fue validada manualmente y el cambio toca pantallas.
+- ❌ En features SDD (con `tasks.md`), nunca apruebes si algún `R<n>` del lote no tiene un test trazable que lo cubra.
 - ❌ Nunca editas el código. Solo señalas qué falla y dónde.
 - ✅ Sé concreto: cita `archivo:línea`. Nada de feedback genérico.
 
 <!-- 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/apollo-client.md

@@ -0,0 +1,62 @@
+---
+name: apollo-client
+description: GraphQL con Apollo Client — hooks, fetchPolicy, normalización de caché y actualización tras mutaciones. Aplica al escribir queries/mutations, configurar la caché o los links.
+type: reference
+---
+
+# Apollo Client — el patrón canónico
+
+Lecturas declarativas con hooks, caché **normalizada por id**, y la UI se mantiene en sync actualizando la caché tras cada mutación. Los concerns de red/auth viven en los links, no en los componentes.
+
+## Cuándo usar este skill
+
+Al escribir una query/mutation, configurar `InMemoryCache`/`typePolicies`, o la cadena de `links`.
+
+## Hooks y aislamiento
+
+`useQuery` (lectura al montar), `useLazyQuery` (bajo demanda, retorna `execute`), `useMutation` (retorna `[mutate, { data, loading, error }]`). Aísla los hooks en una capa (hook + adapter): el componente recibe un **modelo de dominio**, no el shape crudo de GraphQL.
+
+```ts
+export function useReport(id: string) {
+  const { data, loading, error } = useGetReportQuery({ variables: { id }, fetchPolicy: 'cache-first' });
+  return { report: data?.report ? adaptReport(data.report) : null, loading, error };
+}
+```
+
+## fetchPolicy según el dato
+
+- `cache-first` (default) — catálogos/detalles ya traídos por una lista.
+- `cache-and-network` — feeds que cambian seguido (render instantáneo + refresh).
+- `network-only` — sesión/bootstrap, datos críticos.
+- Evita `no-cache` salvo PII estricta que no deba tocar disco.
+
+## Normalización de caché
+
+```ts
+const cache = new InMemoryCache({ typePolicies: { Report: { keyFields: ['id'] } } });
+```
+
+Con `keyFields`, Apollo identifica entidades por id y deduplica/actualiza solo. Sin normalización, las listas y detalles se desincronizan.
+
+## Reglas duras
+
+1. **Tras una mutation, actualiza la caché:** `update(cache, { data })` (`cache.modify`/`evict`/`writeQuery`) o `refetchQueries`. Nunca dejes la UI desincronizada.
+2. **`optimisticResponse`** para UI instantánea (resultado temporal con `__typename` + id ficticio); `update` reconcilia al llegar la respuesta real.
+3. **No over-fetch:** pide solo los campos que el componente usa; apóyate en **fragments con colocation** (el fragmento junto al componente que lo consume). Regenera tipos (codegen) tras editar `.graphql`.
+4. **Maneja `loading` y `error` siempre.** Separa error de red (banner genérico, resuelto en un `errorLink`) de error de negocio (`graphQLErrors`, copy según `extensions.code`).
+5. **Paginación** con `fetchMore` + `updateQuery`, o `relayStylePagination`/merge en `typePolicies`.
+6. Red/auth/upload en la cadena de **links** (auth → error → upload), no en cada componente.
+
+```ts
+const [createReport] = useCreateReportMutation({
+  optimisticResponse: { createReport: { __typename: 'Report', id: 'temp', ...fields } },
+  update(cache) { cache.evict({ fieldName: 'reports' }); }, // invalida la lista
+});
+```
+
+## Antes de declarar listo
+
+- Hooks aislados en capa (hook + adapter); el componente ve el modelo de dominio.
+- Caché normalizada por `keyFields`; mutaciones actualizan/invalidan la caché.
+- `fetchPolicy` elegido por tipo de dato; `loading`/`error` manejados.
+- `{{qualityGate.fast}}` en verde.

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