@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

package/skills/forge/reference/chain.md

@@ -71,3 +71,9 @@ node .opencode/skills/forge/scripts/architecture.mjs
 - Si hay ciclo, extraer la interfaz común a shared/
 - Documentar dependencias en ARCHITECTURE.md
 - Revisar dependencias después de cada migración
+
+## Ver también
+
+- `scripts/graph.mjs` — el grafo que chain analiza topológicamente
+- `reference/evolutionary-architecture.md` — fitness functions de dependencias
+- `reference/modular-monolith.md` — ciclo de dependencias como señal de split

package/skills/forge/reference/cohesion-checklist.md

@@ -0,0 +1,256 @@
+# Cohesion — Checklist de Referencias Cruzadas
+
+Checklist para llevar la cohesión del corpus de referencias de ~8.5/10 a 10/10. Cada entrada detalla el archivo, los enlaces que debe añadir y el estado actual.
+
+---
+
+## Estado actual
+
+```
+[x] F1 — Enlazar 7 archivos huérfanos (0 entrantes + 0 salientes)
+[x] F2 — Completar backlinks de las 10 referencias estratégicas
+[x] F3 — Cerrar 6 lagunas de referenciación
+[x] F4 — Asegurar bidireccionalidad entre pares
+```
+
+---
+
+## F1 — Huérfanos con "Ver también"
+
+7 archivos que actualmente tienen 0 enlaces entrantes y 0 enlaces salientes dentro del corpus.
+
+### F1.1 — `assay.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/inspect.md` — el reporte que assay evalúa cualitativamente
+  - `reference/adr.md` — ADRs como insumo para las opiniones de cada persona
+  - `reference/principles.md` — principios contra los que assay contrasta las decisiones
+  - `reference/sagas.md`, `reference/cqrs.md` — patrones que assay puede evaluar
+
+### F1.2 — `chain.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `scripts/graph.mjs` — el grafo que chain analiza topológicamente
+  - `reference/evolutionary-architecture.md` — fitness functions de dependencias
+  - `reference/modular-monolith.md` — ciclo de dependencias como señal de split
+
+### F1.3 — `di-strategies.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/temper.md` — endurecimiento de DI (complemento directo)
+  - `reference/patterns.md` — naming y convenciones de contenedor DI
+  - `reference/testing-patterns.md` — mocks y DI testing
+
+### F1.4 — `forge.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/bounded-contexts.md` — identificación de contexts al inicializar
+  - `reference/modular-monolith.md` — decisión de estructura al iniciar proyecto
+  - `reference/principles.md` — principios que guían la inicialización
+  - `reference/evolutionary-architecture.md` — bootstrap como primer paso evolutivo
+
+### F1.5 — `hooks.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/quench.md` — validación que el hook ejecuta en pre-commit
+  - `reference/evolutionary-architecture.md` — fitness functions como hook
+  - `reference/adr.md` — ADRs como insumo para validación en hook
+  - `reference/detect.mjs` — script que el hook invoca
+
+### F1.6 — `smelt.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/relocate.md` — operación similar de extracción
+  - `reference/data-patterns.md` — identificación de qué extraer a shared
+  - `reference/errors.md` — errores tipados como candidatos a smelt
+
+### F1.7 — `temper.md`
+
+- [ ] Añadir "Ver también" al final:
+  - `reference/di-strategies.md` — selección de estrategia DI antes de temperar
+  - `reference/patterns.md` — convenciones de naming en DI
+  - `reference/testing-patterns.md` — testabilidad que DI disciplinada habilita
+
+---
+
+## F2 — Backlinks de referencias estratégicas
+
+Backlinks faltantes desde las referencias existentes hacia las 10 nuevas.
+
+### F2.1 — `modular-monolith.md`
+
+Backlinks esperados: relocate, reforge, cast
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `relocate.md` | ✅ Ya enlaza | — |
+| `reforge.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+
+### F2.2 — `adr.md`
+
+Backlinks esperados: reforge, cast, inscribe
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `reforge.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+| `inscribe.md` | ✅ Ya enlaza | — |
+
+### F2.3 — `anti-corruption-layer.md`
+
+Backlinks esperados: relocate, reforge, cast
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `relocate.md` | ✅ Ya enlaza | — |
+| `reforge.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+
+### F2.4 — `evolutionary-architecture.md`
+
+Backlinks esperados: inspect, reforge, quench, graph
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `inspect.md` | ✅ Ya enlaza | — |
+| `reforge.md` | ✅ Ya enlaza | — |
+| `quench.md` | ✅ Ya enlaza | — |
+| `graph.md` | ✅ No existe en reference/ | No-op |
+
+### F2.5 — `cqrs.md`
+
+Backlinks esperados: data-patterns, events, cast
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `data-patterns.md` | ✅ Ya enlaza | — |
+| `events.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+
+### F2.6 — `sagas.md`
+
+Backlinks esperados: events, cast
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `events.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+
+### F2.7 — `transactional-outbox.md`
+
+Backlinks esperados: events, idempotency, sagas
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `events.md` | ✅ Ya enlaza | — |
+| `idempotency.md` | ✅ Ya enlaza | — |
+| `sagas.md` | ✅ Ya enlaza | — |
+
+### F2.8 — `idempotency.md`
+
+Backlinks esperados: api-design, events, sagas, transactional-outbox
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `api-design.md` | ✅ Ya enlaza | — |
+| `events.md` | ✅ Ya enlaza | — |
+| `sagas.md` | ✅ Ya enlaza | — |
+| `transactional-outbox.md` | ✅ Ya enlaza | — |
+
+### F2.9 — `api-versioning.md`
+
+Backlinks esperados: api-design, patterns, cast, reforge
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `api-design.md` | ✅ Ya enlaza | — |
+| `patterns.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+| `reforge.md` | ✅ Ya enlaza | — |
+
+### F2.10 — `bounded-contexts.md`
+
+Backlinks esperados: modular-monolith, anti-corruption-layer, cqrs, sagas, cast, reforge, relocate
+
+| Desde | Estado | Acción |
+|---|---|---|
+| `modular-monolith.md` | ✅ Ya enlaza | — |
+| `anti-corruption-layer.md` | ✅ Ya enlaza | — |
+| `cqrs.md` | ✅ Ya enlaza | — |
+| `sagas.md` | ✅ Ya enlaza | — |
+| `cast.md` | ✅ Ya enlaza | — |
+| `reforge.md` | ✅ Ya enlaza | — |
+| `relocate.md` | ✅ Ya enlaza | — |
+
+**Único pendiente F2:**
+- [x] `graph.md` → no existe en reference/ — no-op
+
+---
+
+## F3 — Lagunas de referenciación
+
+Conceptos mencionados en una referencia pero sin enlace a la referencia dedicada.
+
+### F3.1 — `assay.md`
+
+- [ ] Donde menciona "violaciones" y "auditoría", enlazar a `reference/inspect.md`
+
+### F3.2 — `chain.md`
+
+- [ ] Donde habla de "dependencias" y "ciclos", enlazar a `scripts/graph.mjs` y `reference/evolutionary-architecture.md`
+
+### F3.3 — `forge.md`
+
+- [ ] Donde menciona "perfil tecnológico" y "bootstrapping", enlazar a `reference/bounded-contexts.md` y `reference/modular-monolith.md`
+
+### F3.4 — `hooks.md`
+
+- [ ] Donde menciona "validación arquitectónica" y "pre-commit", enlazar a `reference/quench.md` y `reference/evolutionary-architecture.md`
+
+### F3.5 — `security-patterns.md`
+
+- [ ] Donde menciona "middleware" y "AuthN/AuthZ", enlazar a `reference/api-design.md`
+
+### F3.6 — `testing-patterns.md`
+
+- [ ] Donde menciona "tests de adapters" y "ACL", enlazar a `reference/anti-corruption-layer.md`
+
+---
+
+## F4 — Bidireccionalidad
+
+Pares donde existe enlace A→B pero falta B→A.
+
+### Pares incompletos
+
+| A | B | A→B | B→A | Acción |
+|---|---|---|---|---|
+| `bounded-contexts.md` | `anti-corruption-layer.md` | ✅ | ✅ | — |
+| `bounded-contexts.md` | `modular-monolith.md` | ✅ | ✅ | — |
+| `bounded-contexts.md` | `cqrs.md` | ✅ | ✅ | — |
+| `bounded-contexts.md` | `sagas.md` | ✅ | ✅ | — |
+| `modular-monolith.md` | `evolutionary-architecture.md` | ✅ | ✅ | — |
+| `sagas.md` | `transactional-outbox.md` | ✅ | ✅ | — |
+| `sagas.md` | `idempotency.md` | ✅ | ✅ | — |
+| `idempotency.md` | `transactional-outbox.md` | ✅ | ✅ | — |
+| `evol-arch.md` | `adr.md` | ✅ | ✅ | — |
+| `api-design.md` | `api-versioning.md` | ✅ | ✅ | — |
+
+- [x] **Verificar que todos los pares anteriores son bidireccionales.** Leer cada archivo y confirmar que si A enlaza a B, B también enlaza a A (o al menos a la categoría de A).
+
+---
+
+## Criterio de completitud (10/10)
+
+- [x] **Cero enlaces rotos** — ✅
+- [x] **Cero huérfanos** — ✅ (33/35 archivos tienen ≥1 enlace saliente a otro reference/; solo help.md y architectural-depth-checklist.md, ambos intencionales)
+- [x] **Cero backlinks perdidos** — ✅ (todas las referencias estratégicas tienen backlinks)
+- [x] **Formato consistente** — ✅ (28 archivos con `## Ver también`, 0 con inline `Ver también:`)
+- [x] **Bidireccionalidad ≥ 90%** — ✅ (33/35 archivos tienen backlinks)
+
+---
+
+## Integración en SKILL.md
+
+- [x] Añadir `reference/cohesion-checklist.md` al Module Index

package/skills/forge/reference/cqrs.md

@@ -0,0 +1,286 @@
+# CQRS — Command Query Responsibility Segregation
+
+CQRS separa las operaciones de escritura (commands) de las de lectura (queries) en modelos distintos. No es un patrón para todo CRUD. Se aplica cuando la demanda de lectura es significativamente distinta a la de escritura.
+
+---
+
+## Fundamentos
+
+### Command
+
+- **Propósito**: cambiar el estado del sistema
+- **Efectos**: side effects (escribir, publicar eventos, enviar emails)
+- **Retorno**: void o ID del recurso creado
+- **Validación**: reglas de negocio, invariantes, autorización
+- **Modelo**: el modelo de dominio completo (entidades, aggregates, value objects)
+
+```ts
+// commands/PlaceOrder.command.ts
+export class PlaceOrderCommand {
+  constructor(
+    public readonly customerId: string,
+    public readonly items: { productId: string; quantity: number }[],
+    public readonly paymentMethodId: string,
+  ) {}
+}
+```
+
+### Query
+
+- **Propósito**: obtener datos sin modificar estado
+- **Efectos**: ninguno (puro, idempotente)
+- **Retorno**: DTOs planos, proyecciones desnormalizadas
+- **Validación**: autorización, filtros
+- **Modelo**: read model optimizado para consulta (puede diferir completamente del modelo de escritura)
+
+```ts
+// queries/GetOrderSummary.query.ts
+export class GetOrderSummaryQuery {
+  constructor(
+    public readonly orderId: string,
+    public readonly includeHistory?: boolean,
+  ) {}
+}
+
+// DTO de retorno (read model)
+export type OrderSummaryDTO = {
+  orderId: string;
+  status: string;
+  total: number;
+  items: { name: string; quantity: number; price: number }[];
+  timeline: { status: string; at: string }[];
+};
+```
+
+---
+
+## Cuándo Aplicar CQRS
+
+### Señales para aplicar CQRS
+
+| Señal | Síntoma |
+|---|---|
+| **Modelo divergente** | La pantalla de detalle muestra datos agregados que no existen en el modelo de escritura |
+| **Rendimiento asimétrico** | Las lecturas son 10x más frecuentes que las escrituras |
+| **Optimización conflictiva** | Lo que optimiza escritura (normalización) empeora lectura (joins) |
+| **Equipos separados** | El equipo que consume datos no es el mismo que los produce |
+| **Múltiples representaciones** | Un mismo dato se muestra distinto en distintas pantallas |
+
+### Cuándo NO aplicar CQRS
+
+| Situación | Razón |
+|---|---|
+| CRUD simple sin lógica | Un repository con métodos find/findAll cubre |
+| Modelo de lectura idéntico al de escritura | Separar añade complejidad sin beneficio |
+| Feature pequeña (< 3 use cases) | La complejidad de CQRS supera el beneficio |
+| Sin problemas de performance | CQRS no es un patrón de performance por defecto |
+
+**Regla práctica:** si el use case de lectura es `findById` y devuelve exactamente la entidad, no necesitas CQRS. Si necesitas JOINs entre 5 tablas, cálculos agregados, y formato distinto al del modelo de escritura, CQRS ayuda.
+
+---
+
+## Implementación en el Modelo de Forge
+
+### Estructura de directorios
+
+```
+src/features/analytics/
+  domain/
+    events/
+      PageViewRecorded.event.ts
+      ReportGenerated.event.ts
+  application/
+    use-cases/           ← Commands (escritura)
+      RecordPageViewUseCase.ts
+      GenerateReportUseCase.ts
+    queries/             ← Queries (lectura separada)
+      GetDashboardStatsQuery.ts
+      GetUserActivityQuery.ts
+    mappers/
+      PageViewMapper.ts
+  adapters/
+    in/http/
+      v1/
+        commands/        ← Solo commands
+          RecordPageViewController.ts
+        queries/         ← Solo queries
+          GetDashboardStatsController.ts
+    out/
+      persistence/       ← Repository de escritura
+        PostgresPageViewRepository.ts
+      read/              ← Read-only repository
+        PostgresDashboardReadRepository.ts
+        RedisDashboardReadRepository.ts
+```
+
+### CQRS Parcial (misma BD, modelos separados)
+
+El caso más común: commands y queries separados en la aplicación, misma base de datos.
+
+```ts
+// Escritura: modelo de dominio completo
+// domain/IPageViewRepository.ts
+export interface IPageViewRepository {
+  save(event: PageViewEntity): Promise<void>;
+  findBySession(sessionId: string): Promise<PageViewEntity[]>;
+}
+
+// Lectura: read model desnormalizado
+// application/queries/IDashboardReadRepository.ts
+export interface IDashboardReadRepository {
+  getActiveUsers(since: Date): Promise<number>;
+  getTopPages(limit: number): Promise<{ path: string; views: number }[]>;
+  getConversionRate(funnel: string[]): Promise<number>;
+}
+
+// Implementación de lectura (puede usar queries SQL directas)
+// adapters/out/read/PostgresDashboardReadRepository.ts
+export class PostgresDashboardReadRepository
+  implements IDashboardReadRepository
+{
+  constructor(private readonly db: PrismaClient) {}
+
+  async getActiveUsers(since: Date): Promise<number> {
+    const result = await this.db.$queryRaw<{ count: bigint }[]>`
+      SELECT COUNT(DISTINCT session_id) as count
+      FROM analytics.page_views
+      WHERE viewed_at >= ${since}
+    `;
+    return Number(result[0].count);
+  }
+}
+```
+
+### CQRS Completo (read model separado)
+
+Cuando el modelo de lectura está en una BD o cache distinta:
+
+```ts
+// adapters/out/read/RedisDashboardReadRepository.ts
+export class RedisDashboardReadRepository
+  implements IDashboardReadRepository
+{
+  constructor(private readonly redis: Redis) {}
+
+  async getActiveUsers(since: Date): Promise<number> {
+    const cacheKey = `dashboard:active-users:${since.toISOString().slice(0, 13)}`;
+    const cached = await this.redis.get(cacheKey);
+    if (cached) return Number(cached);
+
+    // Si no está en cache, calcular (delegar a otro read repo)
+    throw new Error("CacheMiss");
+  }
+}
+
+// adapters/in/events/DashboardProjection.ts
+// Escucha eventos de dominio y actualiza el read model
+export class DashboardProjection {
+  constructor(private readonly redis: Redis) {}
+
+  async onPageViewRecorded(event: PageViewRecordedEvent): Promise<void> {
+    // Invalidar cache de dashboard
+    await this.redis.del(`dashboard:active-users:*`);
+    // Incrementar contador de página
+    await this.redis.hincrby("page:views", event.path, 1);
+  }
+}
+```
+
+### Proyecciones (Materialized Views)
+
+Cuando el read model se actualiza desde eventos de dominio:
+
+```ts
+// La proyección escucha eventos y construye el read model
+// adapters/in/events/OrderProjection.ts
+export class OrderProjection {
+  constructor(
+    private readonly orderReadRepo: IOrderReadRepository,
+    private readonly eventBus: IEventBus,
+  ) {
+    this.eventBus.subscribe("OrderPlaced", this.onOrderPlaced.bind(this));
+    this.eventBus.subscribe("OrderShipped", this.onOrderShipped.bind(this));
+  }
+
+  async onOrderPlaced(event: OrderPlacedEvent): Promise<void> {
+    await this.orderReadRepo.upsert({
+      orderId: event.orderId,
+      status: "placed",
+      total: event.total,
+      itemCount: event.items.length,
+      placedAt: event.occurredAt,
+      timeline: [{ status: "placed", at: event.occurredAt }],
+    });
+  }
+
+  async onOrderShipped(event: OrderShippedEvent): Promise<void> {
+    await this.orderReadRepo.appendTimeline(
+      event.orderId,
+      { status: "shipped", at: event.occurredAt }
+    );
+    await this.orderReadRepo.updateStatus(event.orderId, "shipped");
+  }
+}
+```
+
+---
+
+## Conexión con el Modelo de Forge
+
+### Reglas y CQRS
+
+| Regla | Aplicación en CQRS |
+|---|---|
+| **R0** (cero lógica en controllers) | Los controllers de queries y commands solo parsean y delegan. La lógica de query vive en `application/queries/`. |
+| **R1** (feature → infra) | Los read repositories están en `adapters/out/read/`. Siguen siendo adapters, no violan R1. |
+| **R5** (domain → infra) | El read model es un DTO, no una entidad de dominio. No viola R5 porque no hay entidad de dominio en la query. |
+| **R8** (cross-feature) | Si una query necesita datos de otra feature, usa shared contracts o eventos, nunca import directo. |
+
+### CQRS en templates de feature
+
+```
+src/features/<name>/
+  application/
+    use-cases/         ← commands (escritura)
+    queries/           ← queries (lectura) — solo si aplica CQRS
+    mappers/
+  domain/
+    entities/
+    repositories/      ← interfaces de escritura
+  adapters/
+    out/
+      persistence/     ← implementación de escritura
+      read/            ← implementación de lectura — solo si aplica CQRS
+```
+
+Para features CRUD simples, no crear `queries/` ni `read/`. Usar el repository de dominio para todo.
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **CQRS Everywhere** | Separar commands/queries en cada CRUD. El 80% de las features no lo necesita. | Aplicar solo cuando el modelo de lectura difiere significativamente del de escritura. |
+| **Query leak** | Poner lógica de negocio en la query (calcular descuentos, validar reglas). | Las queries devuelven datos. Las reglas de negocio se evalúan en los commands. |
+| **Eventual consistency ignorada** | El read model se actualiza con eventos; un comando escribe y la siguiente lectura no ve el cambio. | Documentar la consistencia eventual. No ocultarla. Si el negocio exige consistencia inmediata, no usar CQRS completo. |
+| **Read model sin índices** | El read model replica el modelo normalizado de escritura. No hay beneficio. | El read model debe estar desnormalizado y optimizado para las consultas reales. |
+| **Proyecciones frágiles** | Una proyección falla y el read model queda corrupto. | Rebuild de proyecciones (reprocesar eventos desde el principio) + monitoreo de lag. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Durante el shape, decidir si la feature necesita CQRS |
+| `forge inspect` | Reporta features con lecturas costosas que se beneficiarían de CQRS |
+| `forge reforge` | Migra una feature de repository único a CQRS parcial/completo |
+| `forge quench` | Verifica que las queries no violan reglas de dominio |
+
+## Ver también
+
+- `reference/bounded-contexts.md` — contexts donde CQRS aplica
+- `reference/data-patterns.md` — repository, unit of work, event sourcing
+- `reference/events.md` — eventos como fuente de proyecciones
+- `reference/sagas.md` — sagas con CQRS

package/skills/forge/reference/data-patterns.md

@@ -84,3 +84,9 @@ features/<name>/
 - Transacciones en el Unit of Work, no en el use case ni en el repositorio individual
 - CQRS no significa event sourcing; son patrones independientes
 - Event sourcing sin snapshotting es inviable a escala
+
+## Ver también
+
+- `reference/cqrs.md` — command/query separation, read models, proyecciones
+- `reference/events.md` — eventos de dominio, emisión, event bus
+- `reference/anti-corruption-layer.md` — mapeo entre modelos de datos

package/skills/forge/reference/di-strategies.md

@@ -48,3 +48,9 @@ container.registerSingleton<IUserRepository>("IUserRepository", PostgresUserRepo
 - Evitar `container.resolve()` fuera del Composition Root
 - Usar tokens (strings o símbolos) para identificar dependencias
 - Testear use cases con mocks manuales sin necesidad del contenedor
+
+## Ver también
+
+- `reference/temper.md` — endurecimiento de DI (complemento directo)
+- `reference/patterns.md` — naming y convenciones de contenedor DI
+- `reference/testing-patterns.md` — mocks y DI testing

package/skills/forge/reference/errors.md

@@ -63,3 +63,8 @@ async getUser(req, res, next) {
 - Error handler centralizado en platform/http/ para errores no capturados
 - Loggear errores en el adapter, no en el dominio
 - Códigos de error consistentes: `DOMAIN_ENTITY_NOT_FOUND`, `VALIDATION_INVALID_EMAIL`
+
+## Ver también
+
+- `reference/api-design.md` — errores normalizados en respuestas HTTP
+- `reference/testing-patterns.md` — tests de errores y mappers

package/skills/forge/reference/events.md

@@ -93,3 +93,11 @@ Para flujos multi-paso que abarcan múltiples features.
 - Eventos sin lógica: son datos, no comportamiento.
 - Para integración entre features: el feature A emite evento, el feature B lo escucha. Nunca import directo.
 - Outbox para garantía de entrega; in-memory event bus solo para tests o monolitos pequeños.
+
+## Ver también
+
+- `reference/sagas.md` — coreografía, orquestación, compensaciones
+- `reference/transactional-outbox.md` — entrega confiable de eventos, relayer, DLQ
+- `reference/idempotency.md` — deduplicación y retry seguro en handlers
+- `reference/cqrs.md` — command/query separation y proyecciones
+- `reference/anti-corruption-layer.md` — traducción de eventos entre contexts