@ronaldjdevfs/forge 1.2.0 → 1.3.1

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

package/skills/forge/reference/evolutionary-architecture.md

@@ -0,0 +1,300 @@
+# Evolutionary Architecture
+
+La arquitectura no es un diseño inicial que se congela. Es una estructura que evoluciona con el conocimiento del dominio, el tamaño del equipo y las restricciones del negocio. Forge está diseñado para guiar esa evolución sin reescrituras.
+
+---
+
+## Definición
+
+Una **arquitectura evolutiva** es aquella en la que los cambios significativos pueden realizarse de forma incremental, guiados por **fitness functions** que verifican que las propiedades arquitectónicas se mantienen.
+
+**Propiedades de una arquitectura evolutiva:**
+- **Incremental**: los cambios grandes se dividen en pasos pequeños y reversibles
+- **Guiada por métricas**: se sabe si un cambio mejora o degrada la arquitectura
+- **Fitness functions automatizadas**: las propiedades se verifican en CI
+- **Sin big-bang rewrites**: nunca se reescribe desde cero
+
+---
+
+## Fitness Functions
+
+Una **fitness function** es un test automatizado que valida una característica arquitectónica. Forge ya implementa varias:
+
+### Built-in (R1-R9)
+
+Las 9 reglas de Forge son fitness functions:
+
+```ts
+// scripts/registry/rules.mjs (conceptual)
+const rules = {
+  R1: {
+    name: "feature → infra prohibited",
+    severity: "CRITICAL",
+    check: (edge) =>
+      edge.from.type === "feature" && edge.to.type === "infra",
+  },
+  R8: {
+    name: "cross-feature direct import prohibited",
+    severity: "ERROR",
+    check: (edge) =>
+      edge.from.type === "feature" && edge.to.type === "feature",
+  },
+  // R2-R7, R9 con estructura similar
+};
+```
+
+Estas fitness functions se ejecutan en:
+- `node scripts/detect.mjs` — detección local
+- `forge quench` — validación completa
+- PostToolUse hook — después de cada escritura del agente
+
+### Custom Fitness Functions
+
+Los usuarios pueden registrar sus propias funciones:
+
+```ts
+// scripts/registry/rules.mjs
+import { registerRule } from "./registry/rules.mjs";
+
+registerRule({
+  id: "CUSTOM_01",
+  name: "no console.log in use-cases",
+  severity: "WARNING",
+  check: ({ filePath, content }) =>
+    filePath.includes("application/use-cases") && content.includes("console.log"),
+  description: "Los casos de uso no deben tener console.log. Usar logger inyectado.",
+});
+```
+
+### Tipos de Fitness Functions
+
+| Tipo | Ejecución | Ejemplo |
+|---|---|---|
+| **Estática** | Lint/build | `detect.mjs` analiza imports |
+| **Dinámica** | Runtime | Verificar que event bus no pierde eventos |
+| **Benchmark** | CI periódico | Tiempo de respuesta de queries < 200ms |
+| **Trigger-based** | Evento (PR, deploy) | No hay imports directos entre features |
+| **Contrato** | CI multi-servicio | Las APIs son compatibles con versiones anteriores |
+
+### Integración en CI
+
+```yaml
+# .github/workflows/forge-fitness.yml
+jobs:
+  forge-quench:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: node .opencode/skills/forge/scripts/detect.mjs
+        env:
+          FORGE_STRICT: "true"
+      - run: node .opencode/skills/forge/scripts/chain.mjs --json
+```
+
+---
+
+## Guided Change
+
+El flujo de cambio guiado de Forge asegura que cada modificación arquitectónica es segura:
+
+### 1. Estado actual (before)
+
+```bash
+node scripts/inspect.mjs --json
+# Score: 85
+# Violaciones: 2 WARNING (R9 borderline, naming)
+```
+
+### 2. Proponer cambio
+
+```bash
+forge reforge --move features/old-payments to features/payments/v2
+# Generate plan: split feature, add ACL, migrate use-cases
+```
+
+### 3. Verificar antes de aplicar
+
+```bash
+forge quench --diff
+# Simula el cambio y reporta impacto en score
+```
+
+### 4. Ejecutar con rollback
+
+```bash
+forge reforge --apply
+# Guarda backup en .forge/backup/
+# Si falla: forge rollback --last
+```
+
+### 5. Estado actual (after)
+
+```bash
+node scripts/inspect.mjs --json
+# Score: 92 (+7)
+# Violaciones: 0
+```
+
+Si el score baja, el cambio se rechaza automáticamente (configurable con `FORGE_ALLOW_DEGRADE=true`).
+
+---
+
+## Evolución Típica de un Proyecto
+
+### Fase 1: Prototipo / MVP
+
+```
+10 features, 1 equipo, monolith
+Reglas: todas activas
+Foco: velocidad de entrega
+Tolerancia: alta para violaciones temporales
+```
+
+```bash
+forge quench --allow-warnings
+# Reporta violaciones pero no bloquea
+```
+
+### Fase 2: Crecimiento
+
+```
+20 features, 2 equipos, monolith modular
+Reglas: estrictas (R1-R9 bloquean)
+Foco: boundaries
+```
+
+```bash
+forge quench --strict
+# Las violaciones ERROR bloquean el PR
+```
+
+### Fase 3: Escalamiento
+
+```
+40 features, 3+ equipos, modular → microservicios
+Reglas: R1-R9 + custom (CQRS, outbox, SLA)
+Foco: autonomía de equipos
+```
+
+```bash
+forge inspect --extended
+# Incluye fitness functions custom
+```
+
+### Fase 4: Madurez
+
+```
+N features, equipos autónomos, servicios independientes
+Reglas: fitness functions distribuidas
+Foco: evolución continua sin regresión
+```
+
+---
+
+## Smallest Viable Change
+
+Cada cambio arquitectónico debe ser el **cambio más pequeño que mejora la arquitectura sin romper funcionalidad**.
+
+| Cambio grande (evitar) | Cambio pequeño (preferir) |
+|---|---|
+| Extraer 3 features como microservicios a la vez | Extraer 1 feature, verificar, repetir |
+| Reescribir todo el ORM | Migrar un repositorio por PR |
+| Refactorizar "toda la capa de aplicación" | Refactorizar un caso de uso, probar, continuar |
+| Cambiar de framework | Aislar framework tras interfaces primero, luego reemplazar |
+
+### Patrón: Scaffolding antes de Feature
+
+Antes de implementar una feature completa, crear la estructura del feature y verificar que no viola reglas:
+
+```bash
+# Fase 1: scaffold
+mkdir -p src/features/payments/{domain,application/use-cases,adapters/in/http,adapters/out/persistence}
+touch src/features/payments/domain/PaymentEntity.ts
+touch src/features/payments/domain/IPaymentRepository.ts
+
+# Fase 2: verify
+forge quench
+# Score: 100 (aún sin implementar, pero los boundaries son correctos)
+
+# Fase 3: implementar use-case
+touch src/features/payments/application/use-cases/ProcessPaymentUseCase.ts
+
+# Fase 4: verify again
+forge quench
+# Score: 100 (el use-case solo importa de domain y shared)
+```
+
+---
+
+## Evolución de Boundaries
+
+### Partir un feature
+
+```bash
+# Antes: features/catalog (15k líneas, toca todo)
+# Después: features/catalog (core) + features/search (búsqueda)
+
+forge cast search --from catalog
+# 1. Crea features/search con estructura completa
+# 2. Mueve SearchService y SearchIndexer de catalog a search
+# 3. Crea contratos en shared/contracts/catalog/ para que search consuma datos
+# 4. Verifica que no quedan imports de catalog → search ni viceversa
+```
+
+### Fusionar features
+
+```bash
+# Antes: features/standard-checkout + features/express-checkout
+# (80% del código duplicado entre ambos)
+
+forge reforge --merge features/express-checkout into features/checkout
+# 1. Mueve el código único de express a checkout
+# 2. Parametriza el checkout con "mode: standard | express"
+# 3. Elimina features/express-checkout
+# 4. Verifica que nada importaba de express-checkout
+```
+
+### Mover un shared kernel a package
+
+```bash
+# Antes: src/shared/contracts/ (referencia local)
+# Después: @company/contracts (npm package)
+
+forge reforge --publish shared/contracts as @company/contracts
+# 1. Extrae contracts/ a packages/contracts/
+# 2. Configura build con tsc
+# 3. Actualiza imports en todas las features
+# 4. Verifica con detect.mjs que los nuevos imports son válidos
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Big-Bang Rewrite** | Se reescribe todo. El sistema legacy se congela. El rewrite nunca alcanza el feature parity. | Strangler Fig + ACL. Migrar feature por feature. |
+| **Frozen Architecture** | "No podemos cambiar la estructura ahora". La arquitectura se vuelve un impedimento. | Fitness functions + guided change. El cambio seguro está soportado por diseño. |
+| **Analysis Paralysis** | Demasiado tiempo diseñando, poco tiempo implementando. | Smallest viable change. El diseño emerge, no se predice. |
+| **Tech Debt sin métrica** | Se acumula deuda sin saber cuánta ni dónde. | `forge inspect` da score numérico. La deuda se mide, no se estima. |
+| **Rewrite por moda** | "Pasamos a microservicios porque es moderno". | `reference/modular-monolith.md` — evaluar antes de partir. |
+| **Golden Hammer** | Forzar CQRS, Event Sourcing o Hexagonal en features que no lo necesitan. | Cada referencia tiene "cuándo usarlo". Si no aplica, no lo fuerces. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge inspect` | Score + violaciones + fitness functions |
+| `forge quench` | Ejecuta fitness functions en el código actual |
+| `forge reforge` | Cambio arquitectónico guiado con verificación |
+| `forge relocate` | Migración incremental con rollback |
+| `forge chain` | Verifica que el grafo de dependencias evoluciona saludablemente |
+| `forge graph` | Visualiza la evolución del grafo arquitectónico |
+
+## Ver también
+
+- `reference/adr.md` — ADRs como registro de cambios evolutivos
+- `reference/principles.md` — principios que las fitness functions protegen
+- `reference/modular-monolith.md` — evolución de monolith a microservicios

package/skills/forge/reference/forge.md

@@ -42,3 +42,10 @@ Inicializa un proyecto para trabajar con Forge como Backend Architecture Operati
 | Platform layer ausente | SUGGESTION |
 | Dependencias faltantes | WARNING |
 | Ownership con huérfanos | WARNING |
+
+## Ver también
+
+- `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

package/skills/forge/reference/hooks.md

@@ -60,3 +60,9 @@ Las reglas ignoradas se almacenan en `.forge/hooks-ignore.json`:
 
 Cuando una regla está ignorada, el hook no bloquea el commit por
 violaciones de esa regla, aunque el detector sigue reportándolas.
+
+## Ver también
+
+- `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