@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

package/skills/forge/reference/modular-monolith.md

@@ -0,0 +1,252 @@
+# Modular Monolith
+
+No todo proyecto necesita microservicios. El modular monolith es el punto óptimo para la mayoría de los equipos: la modularidad de features de Forge con la simplicidad operativa de un solo deploy.
+
+---
+
+## Espectro Monolith → Modular → Microservices
+
+```
+Monolith clásico          Modular Monolith              Microservicios
+┌──────────────────┐    ┌──────────────────┐    ┌──┐ ┌──┐ ┌──┐ ┌──┐
+│ Todo en una capa │    │ ┌─┐ ┌─┐ ┌─┐ ┌─┐│    │F1│ │F2│ │F3│ │F4│
+│ Sin boundaries   │    │ │F1│ │F2│ │F3│ │F4││    └──┘ └──┘ └──┘ └──┘
+│ BD compartida    │    │ └─┘ └─┘ └─┘ └─┘│    BD separadas
+│ Sin features     │    │ Platform/Shared/Infra      │    APIs síncronas
+└──────────────────┘    └──────────────────┘    │    Eventos asíncronos
+                                                    │    Deploy independiente
+                                                    └───────────────────────────
+```
+
+| Aspecto | Monolith clásico | Modular Monolith | Microservicios |
+|---|---|---|---|
+| **Boundaries** | No existen | Features con R8-R9 | Servicios independientes |
+| **Comunicación** | Llamadas directas | Inyección de interfaces + eventos | HTTP/gRPC + eventos |
+| **Deploy** | Todo junto | Todo junto | Independiente |
+| **BD** | Compartida | Schemas separados por feature | BD independiente |
+| **Equipo** | 1 equipo | 1-2 equipos | 3+ equipos |
+| **Forge** | No aplica | Modelo nativo | Modelo nativo + split |
+| **Escala** | < 20 features | < 40 features | Sin límite |
+
+El modular monolith NO es un monolith clásico. La diferencia son los **boundaries explícitos**: cada feature respeta R8 (no imports directos) y R9 (no ciclos), igual que en microservicios, pero todo corre en el mismo proceso.
+
+---
+
+## Marco de Decisión
+
+### Cuándo mantener Modular Monolith
+
+| Condición | Señal |
+|---|---|
+| Equipo pequeño (< 8 personas) | Un solo equipo puede mantener todas las features |
+| Dominio cohesionado | Los bounded contexts están estrechamente relacionados |
+| Latencia crítica | El overhead de red de microservicios es inaceptable |
+| Fase inicial | El dominio no está lo suficientemente entendido para partir |
+| Baja carga operativa | Sin equipo de infraestructura dedicado |
+| Deploy semanal/mensual | La velocidad de deploy no es el cuello de botella |
+
+### Cuándo considerar partir a microservicios
+
+| Señal | Síntoma |
+|---|---|
+| **Team scaling** | Dos equipos distintos modifican la misma feature frecuentemente |
+| **Deployment bottleneck** | Un cambio en una feature requiere validar todo el monolith |
+| **Boundaries maduros** | Los bounded contexts están estables y bien definidos |
+| **Failure isolation** | Una feature con alta criticidad (ej. pagos) arrastra a las demás en fallos |
+| **Diferentes características** | Una feature necesita escalar distinto (ej. Search vs Catalog) |
+| **Stack divergence** | Una feature se beneficiaría de un stack tecnológico distinto |
+
+### Contra-señales (no partir)
+
+| Falsa señal | Realidad |
+|---|---|
+| "Es lo moderno" | Microservicios son una decisión de negocio, no técnica |
+| "Escalabilidad" | El cuello de botella suele ser BD, no el monolith |
+| "Equipos autónomos" | Sin boundaries bien definidos, los microservicios serán un distributed monolith |
+| "Rendimiento" | El overhead de red puede empeorar la latencia |
+| "Está de moda" | Moda tecnológica no justifica la complejidad operativa |
+
+---
+
+## Arquitectura Interna del Modular Monolith
+
+### Comunicación entre features
+
+En el modular monolith, la comunicación entre features sigue exactamente las mismas reglas que en microservicios:
+
+```ts
+// ✅ Permitido: inyección de interfaz desde shared
+// src/features/orders/application/use-cases/PlaceOrderUseCase.ts
+import { IInventoryService } from "src/shared/contracts/catalog";
+import { IUnitOfWork } from "src/shared/contracts/data";
+
+// ❌ Prohibido: import directo a otra feature (R8)
+import { StockEntity } from "src/features/inventory/domain/StockEntity";
+
+// ❌ Prohibido: import directo a infra de otra feature (R1 + R8)
+import { prisma } from "src/features/inventory/adapters/out/persistence/prisma";
+```
+
+### Shared Kernel
+
+```ts
+// src/shared/contracts/catalog/IInventoryService.ts
+export interface IInventoryService {
+  reserveStock(orderId: string, items: LineItem[]): Promise<ReservationResult>;
+  releaseStock(reservationId: string): Promise<void>;
+}
+
+// Los DTOs de los contratos viven junto a la interfaz
+export type ReservationResult = {
+  success: boolean;
+  reservationId?: string;
+  insufficientItems: { sku: string; available: number }[];
+};
+```
+
+La implementación se inyecta en tiempo de construcción:
+
+```ts
+// src/features/inventory/adapters/out/shared/InventoryService.ts
+export class InventoryServiceImpl implements IInventoryService {
+  constructor(private readonly stockRepo: IStockRepository) {}
+  // implementación real que la feature Inventory expone al Shared Kernel
+}
+```
+
+### Base de datos
+
+En el modular monolith, cada feature tiene su propio schema dentro de la misma BD:
+
+```sql
+-- Schema por feature, misma base de datos
+CREATE SCHEMA IF NOT EXISTS orders;
+CREATE SCHEMA IF NOT EXISTS catalog;
+CREATE SCHEMA IF NOT EXISTS inventory;
+
+CREATE TABLE orders.orders ( … );
+CREATE TABLE catalog.products ( … );
+CREATE TABLE inventory.stock ( … );
+
+-- No existen foreign keys entre schemas de distintas features
+-- La integridad referencial se maneja en la aplicación, no en la BD
+```
+
+En Prisma esto se configura con `schema` por modelo:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+  schemas  = ["orders", "catalog", "inventory"]
+}
+
+model Order {
+  id        String @id @default(uuid())
+  // ...
+  @@schema("orders")
+}
+
+model Product {
+  id        String @id @default(uuid())
+  // ...
+  @@schema("catalog")
+}
+```
+
+### Eventos dentro del monolith
+
+Dentro del modular monolith, los eventos pueden ser sincrónicos (in-process event bus) o asíncronos (message broker):
+
+```ts
+// Sincrónico: EventBus in-process, sin serialización
+// platform/events/EventBus.ts
+export interface IEventBus {
+  publish(event: DomainEvent): Promise<void>;
+  subscribe<T extends DomainEvent>(eventType: string, handler: (event: T) => Promise<void>): void;
+}
+
+// Uso en feature
+// orders/application/use-cases/PlaceOrderUseCase.ts
+await this.eventBus.publish(new OrderPlacedEvent(order));
+// inventory/adapters/in/events/OrderPlacedHandler.ts
+eventBus.subscribe("OrderPlaced", async (event) => {
+  await this.stockService.reserveStock(event.orderId, event.items);
+});
+```
+
+**Regla: dentro del monolith, puedes elegir síncrono o asíncrono.** Pero si planeas partir a microservicios en el futuro, usa asíncrono desde el día 1 (message broker). La migración será solo cambiar la URL del broker.
+
+---
+
+## Integración con Forge
+
+| Elemento | Modular Monolith | Microservicios |
+|---|---|---|
+| **Reglas R1-R9** | Se aplican igual | Se aplican igual |
+| **Contratos en shared/** | Interfaces + DTOs | Mismos contratos (packages publicados) |
+| **Eventos** | In-process o broker | Broker siempre |
+| **Platform** | Monolítica, compartida | Por servicio o shared library |
+| **Infra** | Schemas separados en misma BD | BD independientes |
+| **Deploy** | Un solo artefacto | N artefactos |
+| **forge cast** | Crea feature en el monolith | Crea feature + esqueleto de servicio |
+| **forge inspect** | Auditoría normal | Auditoría + health check distribuido |
+| **forge relocate** | Extraer feature del monolith | Dividir servicio o fusionar |
+
+### Transición guiada: Modular Monolith → Microservicios
+
+```
+Fase 1: Asegurar boundaries
+  - Verificar que R8 y R9 se cumplen
+  - shared/contracts/ debe contener todas las interfaces entre features
+  - Schemas separados por feature
+
+Fase 2: Extraer eventos
+  - Migrar de event bus in-process a broker (RabbitMQ, Kafka)
+  - Verificar que los handlers de eventos son idempotentes
+
+Fase 3: Extraer feature como servicio
+  1. forge relocate extrae la feature a un nuevo repo
+  2. La feature origen ahora inyecta un cliente HTTP/gRPC en vez de la impl directa
+  3. El contrato en shared/ se convierte en API contract
+  4. Los eventos viajan por el broker existente
+
+Fase 4: Iterar
+  - Repetir Fase 3 para cada feature que se beneficie de partir
+  - Dejar las demás en el monolith
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Distributed Monolith** | Microservicios que se llaman sincrónicamente en cadena. Si un servicio falla, todos fallan. | Usar eventos asíncronos entre servicios. Si la latencia lo exige sincrónico, reconsiderar si deberían ser un solo servicio. |
+| **Shared Database (microservices)** | Microservicios que comparten BD. Los boundaries son ficticios. | Migrar a schemas separados o BD independientes. Empezar con schemas si el split es futuro. |
+| **Nano-services** | Microservicio por entidad. Cada servicio es un CRUD sin lógica. | Fusionar en features por dominio de negocio. El overhead de operar N servicios pequeños es mayor que el beneficio. |
+| **Premature splitting** | Partir antes de entender los bounded contexts. | Esperar a que los contexts estén estables. El monolith modular permite partir sin reescribir. |
+| **Monolith con carpetas** | Solo hay separación por carpetas, no por boundaries. Cualquier código importa cualquier otro. | Implementar R8 y R9. Si duele, significa que los boundaries están mal diseñados o no existen. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Crea feature en el monolith modular con boundaries correctos |
+| `forge inspect` | Verifica que los boundaries entre features son saludables |
+| `forge relocate` | Extrae una feature del monolith a un servicio independiente |
+| `forge reforge` | Rediseña boundaries mal definidos dentro del monolith |
+| `forge graph` | Visualiza dependencias entre features; identifica candidatos a partir |
+
+## Ver también
+
+- `reference/bounded-contexts.md` — contexts como módulos del monolith
+- `reference/anti-corruption-layer.md` — ACL entre módulos
+- `reference/sagas.md` — coordinación entre módulos
+- `reference/events.md` — comunicación asíncrona entre módulos

package/skills/forge/reference/observability.md

@@ -64,3 +64,8 @@ export interface IHealthCheck {
 - Tracing distribuido con baggage contextual
 - Health checks sin autenticación (solo para orquestadores)
 - Alertas basadas en métricas, no en logs
+
+## Ver también
+
+- `reference/security-patterns.md` — audit logging como práctica de seguridad
+- `reference/testing-patterns.md` — tests de instrumentación y health checks

package/skills/forge/reference/quench.md

@@ -71,4 +71,9 @@ node .opencode/skills/forge/scripts/detect.mjs --severity ERROR
 
 # Solo un tipo específico
 node .opencode/skills/forge/scripts/detect.mjs --type layers
+
+## Ver también
+
+- `reference/evolutionary-architecture.md` — fitness functions como validación continua
+- `reference/hooks.md` — integración de quench en pre-commit hook
 ```

package/skills/forge/reference/relocate.md

@@ -49,3 +49,9 @@ El backup se almacena en `.forge/backups/<target>--<timestamp>/` y preserva la e
 | Feature | `src/application/use-cases/<name>/` | `src/features/<name>/` |
 | Shared | `src/utils/`, `src/helpers/`, `src/lib/` | `src/shared/<name>/` |
 | Infra | `src/database/`, `src/providers/` | `src/infra/<name>/` |
+
+## Ver también
+
+- `reference/anti-corruption-layer.md` — aislamiento de legacy durante migración
+- `reference/modular-monolith.md` — decisión de estructura al migrar features
+- `reference/reforge.md` — refactor post-migración

package/skills/forge/reference/sagas.md

@@ -0,0 +1,359 @@
+# Sagas — Transacciones Multi-Feature
+
+Los procesos de negocio rara vez caben en una sola feature. Una saga coordina múltiples pasos a través de bounded contexts, garantizando consistencia eventual sin ACID distribuido.
+
+---
+
+## El Problema
+
+Una transacción como "realizar un pedido" cruza múltiples features:
+
+```
+Orders: crear pedido → Inventory: reservar stock → Payments: cobrar → Shipping: preparar envío
+```
+
+En un monolith con una sola BD, esto sería una transacción ACID. Cuando cada feature tiene su propio schema o BD, no hay transacción distribuida. Las sagas resuelven este problema.
+
+### Una saga no es:
+- Una transacción ACID (no hay rollback, hay compensación)
+- Un workflow BPMN con motor externo (aunque puede parecerse)
+- Un event pipeline unidireccional (tiene lógica de decisión)
+
+### Una saga es:
+- Una secuencia de transacciones locales
+- Cada paso tiene una acción compensatoria si falla
+- La saga completa tiene consistencia eventual garantizada
+
+---
+
+## Coreografía (Choreography)
+
+Cada participante publica eventos y reacciona a eventos de otros. No hay coordinador central.
+
+```mermaid
+sequenceDiagram
+    participant Orders
+    participant Inventory
+    participant Payments
+    participant Shipping
+
+    Orders->>Orders: crear pedido
+    Orders->>Inventory: OrderPlaced (event)
+    Inventory->>Inventory: reservar stock
+    alt stock suficiente
+        Inventory->>Orders: StockReserved (event)
+        Orders->>Payments: cobrar (event)
+        Payments->>Payments: procesar pago
+    else stock insuficiente
+        Inventory->>Orders: StockReservationFailed (event)
+        Orders->>Orders: cancelar pedido
+    end
+```
+
+### Implementación coreografía
+
+```ts
+// Cada feature publica y escucha eventos
+// features/orders/adapters/in/events/OrderSaga.ts
+export class OrderSaga {
+  constructor(
+    private readonly orderRepo: IOrderRepository,
+    private readonly eventBus: IEventBus,
+  ) {
+    // Escucha respuestas de otros features
+    this.eventBus.subscribe("StockReserved", this.onStockReserved.bind(this));
+    this.eventBus.subscribe("StockReservationFailed", this.onStockFailed.bind(this));
+    this.eventBus.subscribe("PaymentProcessed", this.onPaymentProcessed.bind(this));
+    this.eventBus.subscribe("PaymentFailed", this.onPaymentFailed.bind(this));
+  }
+
+  async onStockReserved(event: StockReservedEvent): Promise<void> {
+    await this.orderRepo.updateStatus(event.orderId, "stock_reserved");
+    this.eventBus.publish(new RequestPaymentCommand(event.orderId, event.amount));
+  }
+
+  async onStockFailed(event: StockReservationFailedEvent): Promise<void> {
+    await this.orderRepo.updateStatus(event.orderId, "cancelled_no_stock");
+    // No hay compensación adicional: el pedido nunca se confirmó
+  }
+
+  async onPaymentProcessed(event: PaymentProcessedEvent): Promise<void> {
+    await this.orderRepo.updateStatus(event.orderId, "paid");
+    this.eventBus.publish(new RequestShippingCommand(event.orderId));
+  }
+
+  async onPaymentFailed(event: PaymentFailedEvent): Promise<void> {
+    await this.orderRepo.updateStatus(event.orderId, "payment_failed");
+    // Compensación: liberar stock
+    this.eventBus.publish(new ReleaseStockCommand(event.orderId));
+  }
+}
+```
+
+### Pros y contras
+
+| Pro | Contra |
+|---|---|
+| Sin punto central de fallo | Lógica de saga distribuida: difícil de entender el flujo completo |
+| Cada feature es autónomo | Seguimiento complejo (¿en qué paso está cada pedido?) |
+| Fácil de añadir nuevos participantes | Riesgo de ciclos de eventos |
+| Escala horizontalmente | Testing de integración más complejo |
+
+---
+
+## Orquestación (Orchestration)
+
+Un coordinador central (orchestrator) dirige cada paso y decide el flujo.
+
+```mermaid
+sequenceDiagram
+    participant CheckoutSaga as Orchestrator
+    participant Orders
+    participant Inventory
+    participant Payments
+    participant Shipping
+
+    CheckoutSaga->>Orders: crearPedido()
+    Orders-->>CheckoutSaga: ok
+    CheckoutSaga->>Inventory: reservarStock()
+    Inventory-->>CheckoutSaga: ok
+    CheckoutSaga->>Payments: procesarPago()
+    alt pago exitoso
+        Payments-->>CheckoutSaga: ok
+        CheckoutSaga->>Shipping: prepararEnvio()
+    else pago falla
+        Payments-->>CheckoutSaga: failed
+        CheckoutSaga->>Inventory: liberarStock()  ← compensación
+        CheckoutSaga->>Orders: cancelarPedido()   ← compensación
+    end
+```
+
+### Implementación orquestación
+
+El orchestrator es un feature independiente:
+
+```
+src/features/checkout-saga/
+  domain/
+    SagaInstance.entity.ts      ← estado de cada saga activa
+    ISagaStepExecutor.ts         ← interfaz para ejecutar pasos
+  application/
+    use-cases/
+      ExecuteCheckoutSaga.ts     ← orquesta la saga
+  adapters/
+    out/
+      saga-steps/
+        CreateOrderStep.ts       ← llama a Orders
+        ReserveStockStep.ts      ← llama a Inventory
+        ProcessPaymentStep.ts    ← llama a Payments
+        PrepareShippingStep.ts   ← llama a Shipping
+        CancelOrderStep.ts       ← compensación de Orders
+        ReleaseStockStep.ts      ← compensación de Inventory
+```
+
+```ts
+// features/checkout-saga/application/use-cases/ExecuteCheckoutSaga.ts
+export class ExecuteCheckoutSaga {
+  constructor(
+    private readonly sagaRepo: ISagaInstanceRepository,
+    private readonly stepFactory: SagaStepFactory,
+  ) {}
+
+  async execute(command: StartCheckoutCommand): Promise<void> {
+    const saga = SagaInstance.start("CHECKOUT", {
+      orderId: command.orderId,
+      customerId: command.customerId,
+      items: command.items,
+    });
+
+    const steps = [
+      this.stepFactory.createOrderStep(),
+      this.stepFactory.reserveStockStep(),
+      this.stepFactory.processPaymentStep(),
+      this.stepFactory.prepareShippingStep(),
+    ];
+
+    for (const step of steps) {
+      try {
+        await step.execute(saga.context);
+        saga.advance(step.name);
+        await this.sagaRepo.save(saga);
+      } catch (error) {
+        saga.fail(step.name, error.message);
+        await this.compensate(saga, steps);
+        return;
+      }
+    }
+
+    saga.complete();
+    await this.sagaRepo.save(saga);
+  }
+
+  private async compensate(saga: SagaInstance, steps: SagaStep[]): Promise<void> {
+    // Ejecuta compensaciones en orden inverso
+    const executedSteps = steps.slice(0, saga.currentStepIndex);
+    for (const step of executedSteps.reverse()) {
+      try {
+        await step.compensate(saga.context);
+      } catch (err) {
+        // La compensación falló — requiere intervención manual
+        saga.requireManualIntervention();
+      }
+    }
+  }
+}
+```
+
+### Pros y contras
+
+| Pro | Contra |
+|---|---|
+| Flujo completo visible en un lugar | Punto central de fallo |
+| Fácil de testear el orchestrator | El orchestrator conoce todos los participantes |
+| Compensaciones explícitas y centralizadas | Riesgo de orchestrator con lógica de negocio |
+| Trazabilidad: cada saga tiene estado | Más boilerplate que coreografía |
+
+---
+
+## Cuándo Elegir Cada Una
+
+| Situación | Recomendación |
+|---|---|
+| 2-3 features, flujo simple | Coreografía |
+| 4+ features, flujo con ramas | Orquestación |
+| Equipos autónomos que no quieren coordinar | Coreografía |
+| Requisito de trazabilidad y monitoreo | Orquestación |
+| Flujo con muchas compensaciones | Orquestación |
+| Feature nuevo que se suma al flujo existente | Coreografía (solo escucha/publica) |
+
+---
+
+## Manejo de Fallos
+
+### Retry con Backoff
+
+```ts
+export class RetryPolicy {
+  constructor(
+    private readonly maxRetries: number = 3,
+    private readonly baseDelay: number = 100,
+  ) {}
+
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        if (attempt === this.maxRetries) throw error;
+        const delay = this.baseDelay * Math.pow(2, attempt - 1);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+}
+```
+
+### Dead Letter Queue (DLQ)
+
+Cuando una saga no puede completarse ni compensarse después de N reintentos:
+
+```ts
+if (saga.retryCount >= 5) {
+  saga.sendToDLQ({
+    reason: "Payment service unavailable after 5 retries",
+    context: saga.context,
+    lastError: error.message,
+  });
+  // Requiere intervención humana
+  await this.sagaRepo.markFailed(saga);
+  await this.notificationService.alertOperations(
+    `Saga ${saga.id} requiere intervención manual`
+  );
+}
+```
+
+### Fallback Humano
+
+Para casos donde la compensación automática no es posible (ej. un pago ya procesado que no puede revertirse automáticamente):
+
+```ts
+if (error.name === "IrreversibleError") {
+  saga.requireManualIntervention({
+    reason: "Payment already captured, manual refund required",
+    instructions: `Login to payment dashboard, refund transaction ${event.paymentId}, then resume saga ${saga.id}`,
+    severity: "HIGH",
+  });
+}
+```
+
+---
+
+## Conexión con el Modelo de Forge
+
+### Reglas y Sagas
+
+| Regla | Aplicación |
+|---|---|
+| **R8** (no cross-feature imports) | La saga se comunica con features mediante eventos o interfaces. Nunca importa directamente. |
+| **R5** (domain → infra) | La saga opera en application/use-cases/. No hay infra en dominio de saga. |
+| **R9** (no ciclos) | Las sagas coreografiadas deben auditarse para evitar ciclos de eventos (A→B→C→A). |
+
+### Ubicación de la saga en la arquitectura
+
+```
+src/features/
+  checkout-saga/                ← orchestrator como feature
+    domain/
+      SagaInstance.entity.ts
+      ISagaStepExecutor.ts
+    application/
+      use-cases/
+        ExecuteCheckoutSaga.ts
+    adapters/
+      out/
+        saga-steps/
+          CreateOrderStep.ts    ← llama a contracts de Orders
+          ReserveStockStep.ts   ← llama a contracts de Inventory
+          ProcessPaymentStep.ts ← llama a contracts de Payments
+        saga-persistence/
+          PostgresSagaRepository.ts
+  orders/
+    adapters/
+      in/
+        events/                  ← escucha eventos de la saga
+        http/
+          commands/              ← la saga llama aquí via contract
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Saga sin compensación** | Un paso falla y el sistema queda inconsistente. | Cada paso debe tener compensación definida explícitamente. |
+| **Orchestrator con lógica de negocio** | El orchestrator decide descuentos, valida reglas, calcula montos. | El orchestrator solo coordina. La lógica de negocio vive en los use cases de cada feature. |
+| **Coreografía sin trazabilidad** | Múltiples eventos volando, nadie sabe el estado global de un proceso. | Usar saga log + event store. Monitorear con `forge chain`. |
+| **Timeout único** | Todas las operaciones tienen el mismo timeout. Operaciones lentas (pagos) fallan donde rápidas (stock) no. | Timeout configurable por paso de saga. |
+| **Compensación que falla sin alerta** | La compensación falla silenciosamente. El sistema cree que compensó pero no lo hizo. | Alertas de operaciones para compensaciones fallidas. Siempre. |
+| **Saga como transacción ACID** | Se intenta revertir un paso que ya tuvo efectos visibles para el usuario. | Las sagas ofrecen consistencia eventual. Los efectos visibles deben diseñarse para ser reversibles (o aceptar que no lo son). |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast checkout-saga` | Crea feature orchestrator con estructura de saga |
+| `forge inspect` | Detecta features que se comunican sincrónicamente (candidatos a saga) |
+| `forge graph` | Visualiza el flujo de la saga como grafo de dependencias entre features |
+| `forge chain` | Verifica que la saga no introduce ciclos (R9) |
+| `forge assay` | Evalúa si la estrategia de coordinación (coreografía vs orquestación) es la adecuada |
+
+## Ver también
+
+- `reference/bounded-contexts.md` — contexts que la saga coordina
+- `reference/events.md` — eventos como unidad de la saga
+- `reference/cqrs.md` — commands como pasos de la saga
+- `reference/transactional-outbox.md` — entrega confiable de eventos de saga
+- `reference/idempotency.md` — retry seguro de pasos de saga

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

@@ -85,3 +85,9 @@ export const createUserSchema = z.object({
 - Helmet para headers de seguridad (CSP, X-Frame-Options, etc.)
 - Secretos en variables de entorno, nunca en código
 - Auditoría de acciones sensibles: login, delete, role change, export
+
+## Ver también
+
+- `reference/api-design.md` — middleware de seguridad, validación de entrada
+- `reference/observability.md` — audit logging como práctica de observabilidad
+- `reference/testing-patterns.md` — tests de middleware y seguridad

package/skills/forge/reference/smelt.md

@@ -29,3 +29,9 @@ Extrae código reutilizable desde features hacia `shared/`.
 - El código extraído NO debe importar de infraestructura
 - El código extraído debe ser puro o depender solo de otros componentes shared
 - Si el código depende de platform, considerar moverlo a platform en lugar de shared
+
+## Ver también
+
+- `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

package/skills/forge/reference/temper.md

@@ -47,3 +47,9 @@ Templa la arquitectura aplicando reglas de inyección de dependencias, seguridad
 - ❌ Importar tsyringe en archivos de dominio
 - ❌ Mezclar DI manual y contenedor en el mismo feature
 - ❌ Proxies automáticos o decoradores ocultos que dificulten el rastreo
+
+## Ver también
+
+- `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

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

@@ -67,3 +67,9 @@ it("POST /users returns 201", async () => {
 - Nombrar tests como unidades de comportamiento, no métodos
 - Coverage mínimo sugerido: 85% use cases, 75% adapters
 - Los mappers se testean con fixtures: entrada conocida → salida esperada
+
+## Ver también
+
+- `reference/anti-corruption-layer.md` — tests de ACL y traducción entre contexts
+- `reference/di-strategies.md` — DI testing con mocks manuales
+- `reference/temper.md` — DI disciplinada que habilita testabilidad