@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

package/skills/forge/reference/anti-corruption-layer.md

@@ -0,0 +1,340 @@
+# Anti-Corruption Layer (ACL)
+
+Cuando un bounded context debe integrarse con otro que tiene un modelo distinto (especialmente legacy o externo), la ACL es la capa que traduce sin contaminar.
+
+---
+
+## Definición y Propósito
+
+Una **Anti-Corruption Layer** es un mecanismo de traducción entre dos bounded contexts. Su función es evitar que el modelo de un sistema externo (o legacy) "corrompa" el modelo de dominio del sistema nuevo.
+
+```mermaid
+flowchart LR
+    subgraph "Sistema Legacy"
+        LegacyModel[(BD Legacy)]
+        Customer[CustomerLegacy]
+    end
+    subgraph "ACL"
+        Translator[Traductor]
+        Gateway[Gateway]
+    end
+    subgraph "Sistema Nuevo (Forge)"
+        DomainModel[(BD Nueva)]
+        Service[Orders Service]
+    end
+    Customer --> Gateway
+    Gateway --> Translator
+    Translator --> Service
+    Service --> DomainModel
+```
+
+**Cuándo usar ACL:**
+- Integración con un sistema legacy que no puede modificarse (SAP, Salesforce, mainframe)
+- Integración con un servicio externo cuyo modelo no controlas (API de terceros)
+- Migración incremental donde ambos sistemas coexisten (Strangler Fig)
+- Dos bounded contexts que evolucionan con ritmos distintos pero necesitan comunicarse
+
+**Cuándo NO usar ACL:**
+- El sistema externo expone un Published Language estable (usa el contrato directamente)
+- El modelo externo es idéntico o trivialmente mapeable (un mapper simple basta)
+- La integración es temporal y el sistema externo será reemplazado pronto
+
+---
+
+## Estructura de una ACL
+
+La ACL vive en `adapter/out/` de la feature que necesita protegerse:
+
+```
+src/features/orders/
+  domain/
+    entities/
+      OrderEntity.ts
+      CustomerEntity.ts          ← modelo limpio
+    repositories/
+      ICustomerRepository.ts     ← puerto que la ACL implementa
+  adapters/
+    out/
+      legacy-crm/
+        CustomerGateway.ts       ← llama al sistema legacy
+        CustomerTranslator.ts    ← traduce del modelo legacy al dominio
+        CustomerACL.ts           ← facade que combina gateway + translator
+      persistence/
+        PostgresCustomerRepository.ts  ← implementación normal
+```
+
+### Componentes de la ACL
+
+| Componente | Responsabilidad |
+|---|---|
+| **Gateway** | Comunicación con el sistema externo (HTTP, SOAP, archivos, BD) |
+| **Translator** | Mapeo del modelo externo al modelo de dominio y viceversa |
+| **Facade** | Orquesta gateway + translator. Implementa la interfaz del puerto. |
+| **Contract** | DTOs del modelo externo (viven en la ACL, no contaminan el dominio) |
+
+---
+
+## Implementación
+
+### 1. Definir el puerto (dominio)
+
+```ts
+// src/features/orders/domain/repositories/ICustomerRepository.ts
+export interface ICustomerRepository {
+  findById(id: string): Promise<CustomerEntity | null>;
+  findByEmail(email: string): Promise<CustomerEntity | null>;
+}
+```
+
+### 2. Gateway (comunicación con externo)
+
+```ts
+// src/features/orders/adapters/out/legacy-crm/CustomerGateway.ts
+// Este archivo es infra y puede depender de HTTP clients, SOAP, etc.
+
+import { LegacyCustomerDTO } from "./LegacyCustomerDTO";
+
+export class LegacyCRMGateway {
+  private readonly baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+
+  async fetchCustomer(crmId: string): Promise<LegacyCustomerDTO> {
+    const response = await fetch(`${this.baseUrl}/api/customers/${crmId}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    if (!response.ok) throw new Error(`CRM error: ${response.statusText}`);
+    return response.json();
+  }
+}
+```
+
+### 3. Translator (traducción)
+
+```ts
+// src/features/orders/adapters/out/legacy-crm/CustomerTranslator.ts
+// Este archivo es PURO. No depende de infraestructura. Solo transforma datos.
+
+import { LegacyCustomerDTO } from "./LegacyCustomerDTO";
+import { CustomerEntity } from "../../../domain/entities/CustomerEntity";
+
+export class CustomerTranslator {
+  toDomain(dto: LegacyCustomerDTO): CustomerEntity {
+    return new CustomerEntity({
+      id: dto.customerId,
+      name: `${dto.firstName} ${dto.lastName}`,
+      email: dto.emailAddress,
+      status: this.mapStatus(dto.active),
+      createdAt: new Date(dto.registrationDate),
+    });
+  }
+
+  private mapStatus(legacyActive: boolean): "active" | "inactive" {
+    return legacyActive ? "active" : "inactive";
+  }
+}
+```
+
+### 4. Facade ACL (implementación del puerto)
+
+```ts
+// src/features/orders/adapters/out/legacy-crm/CustomerACL.ts
+// Implementa ICustomerRepository traduciendo desde el CRM legacy.
+
+import { ICustomerRepository } from "../../../domain/repositories/ICustomerRepository";
+import { CustomerEntity } from "../../../domain/entities/CustomerEntity";
+import { LegacyCRMGateway } from "./CustomerGateway";
+import { CustomerTranslator } from "./CustomerTranslator";
+
+export class LegacyCRMRepository implements ICustomerRepository {
+  constructor(
+    private readonly gateway: LegacyCRMGateway,
+    private readonly translator: CustomerTranslator,
+  ) {}
+
+  async findById(id: string): Promise<CustomerEntity | null> {
+    try {
+      const dto = await this.gateway.fetchCustomer(id);
+      return this.translator.toDomain(dto);
+    } catch (error) {
+      // El gateway lanza errores técnicos. La ACL traduce a errores de dominio.
+      if (error.message.includes("404")) return null;
+      throw new Error("CustomerRepository.fetchFailed");
+    }
+  }
+
+  async findByEmail(email: string): Promise<CustomerEntity | null> {
+    // Si el CRM legacy no soporta búsqueda por email, la ACL puede:
+    // 1. Obtener todos los clientes y filtrar (ineficiente)
+    // 2. Cachear localmente y buscar en caché
+    // 3. Fallar con error explícito
+    throw new Error("CustomerRepository.methodNotSupported");
+  }
+}
+```
+
+### 5. Registro en DI
+
+```ts
+// En la composición root (platform/di/container.ts)
+container.registerSingleton<ICustomerRepository>("ICustomerRepository", {
+  useClass: process.env.USE_LEGACY_CRM === "true"
+    ? LegacyCRMRepository   // ACL
+    : PostgresCustomerRepository,  // implementación nativa
+});
+```
+
+La DI permite switchear entre legacy y nativo sin cambiar el caso de uso.
+
+---
+
+## Strangler Fig Pattern
+
+El Strangler Fig permite migrar de un sistema legacy a uno nuevo incrementalmente, usando ACL como fachada.
+
+### Fase 1: ACL intercepta todo
+
+```
+[API Gateway] → [ACL] → [Legacy CRM]
+```
+
+Todas las llamadas pasan por la ACL que habla con el legacy.
+
+### Fase 2: Rutas individuales migradas
+
+```ts
+// La ACL decide por ruta/característica si va al legacy o al nuevo
+export class CustomerRouterACL implements ICustomerRepository {
+  constructor(
+    private readonly legacy: LegacyCRMRepository,
+    private readonly newRepo: PostgresCustomerRepository,
+    private readonly migrationFlag: FeatureFlagService,
+  ) {}
+
+  async findById(id: string): Promise<CustomerEntity | null> {
+    if (this.migrationFlag.isEnabled("customer-read")) {
+      return await this.newRepo.findById(id);
+    }
+    return await this.legacy.findById(id);
+  }
+}
+```
+
+### Fase 3: Legacy retirado
+
+```
+[API Gateway] → [PostgresCustomerRepository]
+```
+
+La ACL ya no es necesaria. Se elimina el gateway, el translator y la facade.
+
+### Reglas para Strangler Fig exitoso
+
+1. **Un feature completo se migra a la vez**, no funciones sueltas
+2. **La ACL nunca modifica el legacy**. Solo lee y traduce
+3. **Feature flags** para activar/desactivar rutas migradas
+4. **Métricas de comparación**: response time, error rate, data consistency entre legacy y nuevo
+5. **Rollback plan**: desactivar el feature flag vuelve al legacy instantáneamente
+
+---
+
+## Conexión con el Modelo de Forge
+
+### Reglas de dependencia y ACL
+
+| Regla | Relación con ACL |
+|---|---|
+| **R1** (feature → infra) | La ACL está en `adapter/out/` y accede a infra (el gateway). Está permitido porque el adapter es el puerto de salida. El dominio nunca ve infra. |
+| **R7** (infra → feature) | El gateway externo llama a la ACL (infra → adapter). No viola R7 porque el adapter recibe la llamada y la traduce al dominio. |
+| **R8** (cross-feature) | Si la ACL se comunica con otra feature de Forge, debe hacerlo mediante eventos o contratos en shared/, no con imports directos. |
+
+### La ACL en la arquitectura de 4 capas
+
+```
+┌─────────────────────────────────────────────────┐
+│  features/orders/                                │
+│    domain/               ← modelo protegido        │
+│      CustomerEntity                              │
+│      ICustomerRepository ← puerto                 │
+│    adapters/out/                                 │
+│      legacy-crm/          ← ACL completa          │
+│        CustomerGateway    ← infra (llama externo) │
+│        CustomerTranslator ← pure translation      │
+│        CustomerACL        ← facade                │
+│      persistence/                                 │
+│        PostgresCustomerRepository                │
+└─────────────────────────────────────────────────┘
+            │
+            ▼  (gateway)
+┌──────────────────────┐
+│  CRM Legacy (externo) │
+│  /api/customers/:id   │
+└──────────────────────┘
+```
+
+### Dónde NO poner la ACL
+
+| Ubicación incorrecta | Problema |
+|---|---|
+| `src/shared/acl/` | La ACL es específica de un feature, no compartida. Cada feature tiene su propia ACL. |
+| `src/infra/` | La ACL no es infraestructura genérica. Pertenece al adapter del feature. |
+| `src/platform/` | Platform no debe saber qué sistemas externos existen. |
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Leaky Abstraction** | La ACL pasa DTOs del sistema externo en vez de traducir. El dominio termina dependiendo del modelo legacy. | El Translator debe mapear TODOS los campos. Si falta uno, el dominio no sabe que existe. |
+| **Pasamanos (passthrough)** | La ACL no traduce nada. Solo delega. Es una capa que añade complejidad sin valor. | Si no hay traducción que hacer, no uses ACL. Usa el contrato directamente. |
+| **ACL que escribe en el legacy** | La ACL muta el sistema externo para "facilitar" la integración. | La ACL solo traduce. Si necesitas escribir, el legacy debe exponer API de escritura. |
+| **ACL compartida** | Una sola ACL para todos los features. | Cada feature tiene su propia ACL adaptada a su modelo de dominio. |
+| **Gateway sin timeout** | Una llamada al legacy lenta bloquea todo el feature. | Timeouts, circuit breakers y fallbacks obligatorios en el gateway. |
+| **ACL sin test** | No se puede verificar que la traducción es correcta. | Tests unitarios del Translator + tests de integración del Gateway. |
+
+### Testing de ACL
+
+```ts
+// Test unitario del Translator (puro, sin infraestructura)
+describe("CustomerTranslator", () => {
+  it("traduce LegacyCustomerDTO a CustomerEntity", () => {
+    const dto: LegacyCustomerDTO = {
+      customerId: "123",
+      firstName: "John",
+      lastName: "Doe",
+      emailAddress: "john@example.com",
+      active: true,
+      registrationDate: "2024-01-15T10:00:00Z",
+    };
+    const result = new CustomerTranslator().toDomain(dto);
+    expect(result.id).toBe("123");
+    expect(result.status).toBe("active");
+  });
+
+  it("mapea active=false a status=inactive", () => {
+    const dto = { ...baseDTO, active: false };
+    const result = new CustomerTranslator().toDomain(dto);
+    expect(result.status).toBe("inactive");
+  });
+});
+```
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Durante el shape de la feature, detectar si necesita ACL |
+| `forge inspect` | Detecta patrones que indican necesidad de ACL (imports directos a infra externa) |
+| `forge relocate` | Puede generar ACL automática al migrar un feature desde legacy |
+| `forge reforge` | Sugiere introducir ACL cuando detecta leaky abstractions |
+
+## Ver también
+
+- `reference/bounded-contexts.md` — contexts que la ACL aísla
+- `reference/modular-monolith.md` — migración con ACL entre módulos
+- `reference/relocate.md` — uso de ACL durante migración legacy

package/skills/forge/reference/api-design.md

@@ -60,3 +60,10 @@ export interface IPaginatedResponse<T> {
 - Errores normalizados: `{ error: { code, message, details? } }`
 - Idempotencia en POST con `Idempotency-Key` header
 - HATEOAS opcional, solo para APIs hipermedia
+
+## Ver también
+
+- `reference/api-versioning.md` — versionado de APIs y deprecación
+- `reference/idempotency.md` — idempotency keys en POST
+- `reference/security-patterns.md` — AuthN/AuthZ, rate limiting, validación
+- `reference/testing-patterns.md` — tests de controllers y endpoints

package/skills/forge/reference/api-versioning.md

@@ -0,0 +1,354 @@
+# API Versioning — Evolución de Contratos
+
+Las APIs evolucionan. Los clientes no siempre pueden actualizarse al mismo ritmo. El versionado de APIs permite cambiar contratos sin romper clientes existentes.
+
+---
+
+## Estrategias de Versionado
+
+### URL Path (más común)
+
+```
+GET /api/v1/orders
+GET /api/v2/orders
+```
+
+```ts
+// features/orders/adapters/in/http/v1/OrderController.ts
+@Router("/api/v1/orders")
+export class OrderV1Controller {
+  @Get("/:id")
+  async getById(@Param("id") id: string) {
+    return this.useCase.execute(new GetOrderQuery(id));
+  }
+}
+
+// features/orders/adapters/in/http/v2/OrderController.ts
+@Router("/api/v2/orders")
+export class OrderV2Controller {
+  @Get("/:id")
+  async getById(@Param("id") id: string) {
+    const result = await this.useCase.execute(new GetOrderQuery(id));
+    // v2 devuelve datos adicionales que v1 no tenía
+    return { ...result, estimatedDelivery: result.shippingEstimate };
+  }
+}
+```
+
+**Pros:** explícito, fácil de rutear, fácil de cachear
+**Contras:** URLs feas, versionado de toda la API (no granular)
+
+### Header (Accept / Content-Type)
+
+```
+GET /api/orders
+Accept: application/vnd.company.v1+json
+```
+
+```ts
+// Middleware que selecciona versión según Accept header
+export class VersionResolver {
+  resolve(req: Request): string {
+    const accept = req.headers["accept"] || "";
+    const match = accept.match(/application\/vnd\.company\.v(\d+)\+json/);
+    return match ? `v${match[1]}` : "v1"; // default v1
+  }
+}
+```
+
+**Pros:** URLs limpias, versionado granular por endpoint
+**Contras:** complejidad en el cliente, difícil de debuggear, caché HTTP limitada
+
+### Query Parameter
+
+```
+GET /api/orders?version=2
+```
+
+**Pros:** simple, fácil de testear
+**Contras:** contamina la semántica del query param, fácil de olvidar
+
+### Content Negotiation (recurso vs representación)
+
+```
+GET /api/orders/123
+Accept: application/json;version=2
+```
+
+**Pros:** semánticamente correcto (negociación de contenido)
+**Contras:** complejidad, poco soporte tooling
+
+### Recomendación de Forge
+
+| Contexto | Estrategia |
+|---|---|
+| API pública (terceros) | URL path (`/api/v1/`) — la más explícita |
+| API interna (entre features) | Header Accept — URLs limpias para el monolith |
+| API móvil | URL path — los clientes móviles cachean URLs |
+| BFF (Backend for Frontend) | Sin versionado (se despliega junto al frontend) |
+
+---
+
+## Compatibilidad
+
+### Cambios backward-compatible
+
+| Cambio | Ejemplo |
+|---|---|
+| Añadir campo opcional en response | `{ name, email }` → `{ name, email, phone? }` |
+| Añadir endpoint nuevo | `GET /v1/orders/:id/items` |
+| Añadir campo en request con default | `{ name }` → `{ name, locale?: "en" }` |
+| Extender enum | `Status.Active` → `Status.Active \| Status.Pending` |
+| Relajar validación | Campo required → opcional |
+
+### Cambios breaking (requieren nueva versión)
+
+| Cambio | Ejemplo |
+|---|---|
+| Eliminar campo del response | `{ name, email }` → `{ name }` |
+| Renombrar campo | `{ email }` → `{ emailAddress }` |
+| Cambiar tipo de campo | `{ price: string }` → `{ price: number }` |
+| Hacer campo requerido | `{ locale? }` → `{ locale }` |
+| Eliminar endpoint | `DELETE /v1/users` |
+| Cambiar estructura | `{ address: string }` → `{ address: { street, city } }` |
+| Cambiar error codes | `404` → `400` para mismo error |
+
+### Compatibilidad en TypeScript
+
+```ts
+// shared/contracts/orders/v1/OrderDTO.ts
+export interface OrderV1DTO {
+  id: string;
+  total: number;
+  status: string;
+  items: { sku: string; quantity: number }[];
+}
+
+// shared/contracts/orders/v2/OrderDTO.ts
+export interface OrderV2DTO extends Omit<OrderV1DTO, "items"> {
+  total: number;
+  status: string;
+  items: { sku: string; quantity: number; name: string; imageUrl: string }[];
+  estimatedDelivery: string; // nuevo campo
+}
+```
+
+---
+
+## Versionado en el Modelo de Forge
+
+### Estructura de directorios
+
+```
+src/features/orders/
+  adapters/
+    in/http/
+      v1/
+        OrderController.ts
+        OrderRoutes.ts
+        OrderValidator.ts    ← validación de input v1
+        OrderPresenter.ts    ← formateo de output v1
+      v2/
+        OrderController.ts
+        OrderRoutes.ts
+        OrderValidator.ts
+        OrderPresenter.ts
+  application/
+    use-cases/               ← los use cases NO se versionan
+      GetOrderUseCase.ts     ← compartido entre v1 y v2
+      PlaceOrderUseCase.ts
+    mappers/                 ← los mappers pueden tener versiones
+      v1/
+        OrderMapper.ts       ← entidad de dominio → DTO v1
+      v2/
+        OrderMapper.ts       ← entidad de dominio → DTO v2
+```
+
+### Principio: la lógica de negocio no se versiona
+
+```ts
+// ✅ Los use cases son compartidos entre versiones
+// v1 y v2 llaman al mismo use case
+// Solo cambia el mapper (cómo se presenta el resultado)
+
+// v1 mapper: devuelve el DTO original
+export class OrderV1Mapper {
+  toDTO(order: OrderEntity): OrderV1DTO {
+    return {
+      id: order.id,
+      total: order.total,
+      status: order.status,
+      items: order.items.map((i) => ({ sku: i.sku, quantity: i.quantity })),
+    };
+  }
+}
+
+// v2 mapper: devuelve más información
+export class OrderV2Mapper {
+  toDTO(order: OrderEntity): OrderV2DTO {
+    return {
+      id: order.id,
+      total: order.total,
+      status: order.status,
+      items: order.items.map((i) => ({
+        sku: i.sku,
+        quantity: i.quantity,
+        name: i.productName,
+        imageUrl: i.productImage,
+      })),
+      estimatedDelivery: this.calculateDelivery(order),
+    };
+  }
+}
+```
+
+### Routing multi-versión
+
+```ts
+// platform/http/Router.ts
+export class ApiRouter {
+  constructor() {
+    this.registerV1Routes();
+    this.registerV2Routes();
+    this.registerVersionRedirect();
+  }
+
+  private registerVersionRedirect(): void {
+    // Si el cliente no especifica versión, redirigir a la más reciente estable
+    this.router.get("/api/orders", (req, res) => {
+      res.redirect("/api/v2/orders");
+    });
+  }
+}
+```
+
+---
+
+## Deprecación
+
+### Política de deprecación
+
+```
+v1: lanzada 2025-01
+v2: lanzada 2026-01  (v1 deprecated)
+v3: lanzada 2027-01  (v1 sunset, v2 deprecated)
+```
+
+### Headers de deprecación
+
+```ts
+// Middleware que añade headers de deprecación a versiones antiguas
+export class DeprecationMiddleware {
+  private readonly sunsetVersions: Record<string, string> = {
+    v1: "2027-01-01", // fecha de retiro
+  };
+
+  handle(req: Request, res: Response, next: NextFunction): void {
+    const version = this.extractVersion(req.path);
+    const sunsetDate = this.sunsetVersions[version];
+    if (sunsetDate) {
+      res.setHeader("Sunset", sunsetDate);
+      res.setHeader("Deprecation", `true`);
+      res.setHeader(
+        "Link",
+        `</api/v2${req.path.replace(/\/api\/v[0-9]/, "")}>; rel="successor-version"`,
+      );
+    }
+    next();
+  }
+}
+```
+
+### Política de retiro
+
+1. **Anunciar**: deprecación con 6 meses de anticipación (header `Deprecation: true` + `Sunset: fecha`)
+2. **Migrar**: soporte simultáneo durante el período de transición
+3. **Monitorear**: tracking de uso de versiones antiguas
+4. **Retirar**: cuando el tráfico de la versión antigua es < 1%, retirar con PR visible
+
+```bash
+# Comando para monitorear uso de versiones
+forge api --usage
+# v1: 12% de requests
+# v2: 88% de requests
+# Sugerencia: v1 está lista para retiro (< 15%)
+```
+
+---
+
+## Testing Multi-Versión
+
+```ts
+// tests/integration/orders/OrderApi.test.ts
+describe("Orders API", () => {
+  const versions = ["v1", "v2"];
+
+  versions.forEach((version) => {
+    describe(`${version} — getOrder`, () => {
+      it("returns 200 for existing order", async () => {
+        const response = await request(app)
+          .get(`/api/${version}/orders/test-id`)
+          .expect(200);
+
+        if (version === "v1") {
+          expect(response.body).not.toHaveProperty("estimatedDelivery");
+        }
+        if (version === "v2") {
+          expect(response.body).toHaveProperty("estimatedDelivery");
+        }
+      });
+
+      it("returns same core fields across versions", async () => {
+        const [v1Res, v2Res] = await Promise.all([
+          request(app).get("/api/v1/orders/test-id"),
+          request(app).get("/api/v2/orders/test-id"),
+        ]);
+
+        expect(v1Res.body.id).toBe(v2Res.body.id);
+        expect(v1Res.body.total).toBe(v2Res.body.total);
+      });
+    });
+  });
+});
+```
+
+### Compatibilidad backward en CI
+
+```bash
+# Verificar que v2 no rompe cambios backward
+forge api --check-compatibility
+# Checking orders v1 → v2... ✔ No breaking changes
+# Checking users v1 → v2... ✖ Breaking: 'email' renamed to 'emailAddress'
+#   → Crear ADR y plan de deprecación
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Versionado global** | Versionar `v1/`, `v2/` para toda la API. Un cambio mínimo en un endpoint fuerza nueva versión de toda la API. | Versionado por recurso/feature. No toda la API tiene que estar en la misma versión. |
+| **Mantener versiones para siempre** | "No podemos romper al cliente X". La deuda de mantener N versiones crece. | Política de retiro explícita (Sunset header + fecha). Máximo 2 versiones activas simultáneas. |
+| **Versionado por "fecha"** | `/api/2025-01/orders`. Sin semántica de estabilidad. | Usar `v1`, `v2` (semver simplificado: major version only). |
+| **Lógica de negocio versionada** | El use case v2 es distinto del v1. La lógica se duplica. | Los use cases son compartidos. Solo versionar la presentación (mappers + controllers). |
+| **Versionado sin deprecación** | Se lanza v2 pero v1 no se depreca oficialmente. Los clientes nunca migran. | Header Deprecation + Sunset. Comunicación proactiva a clientes. |
+| **API versionada pero eventos no** | La API versiona contratos HTTP, pero los eventos internos cambian sin versión. | Versionar schemas de eventos también (ej. `OrderPlaced.v2`). |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast payments` | Crea feature con estructura v1/ en adapters/in/http/ |
+| `forge api --check-compatibility` | Verifica que los cambios no rompen versiones anteriores |
+| `forge api --usage` | Muestra distribución de tráfico entre versiones |
+| `forge reforge` | Migra controllers de v1 a v2, depreca la anterior |
+| `forge inspect` | Reporta versiones sin Deprecation header cuando hay versión superior |
+
+## Ver también
+
+- `reference/api-design.md` — diseño de APIs REST/GraphQL
+- `reference/adr.md` — ADRs para decisiones de versionado
+- `reference/evolutionary-architecture.md` — evolución guiada de APIs