@ronaldjdevfs/forge 1.3.0-beta → 1.3.2

package/skills/forge/reference/adr.md

@@ -0,0 +1,242 @@
+# Architecture Decision Records (ADR)
+
+Las decisiones arquitectónicas son el activo más valioso de un proyecto a largo plazo. Sin registro, cada nueva incorporación al equipo redescubre lo mismo. Los ADRs capturan el qué, el por qué y las consecuencias de cada decisión.
+
+---
+
+## Formato ADR Estándar
+
+Cada ADR es un archivo en `docs/adr/` con el formato `NNNN-title-with-dashes.md`.
+
+```md
+# NNNN — Título corto pero descriptivo
+
+**Estado:** [Proposed | Accepted | Deprecated | Superseded | Amended]
+**Fecha:** YYYY-MM-DD
+**Decisores:** [lista de personas que tomaron la decisión]
+
+## Contexto
+
+Describe el problema o situación que motiva la decisión. Incluye:
+- Restricciones técnicas o de negocio
+- Alternativas consideradas brevemente
+- Por qué el status quo no es aceptable
+- Enlaces a ADRs relacionados
+
+## Decisión
+
+La decisión que se tomó. Debe ser específica, no genérica.
+
+> Adoptamos Prisma como ORM para la capa de infra, con esquemas separados
+> por schema de base de datos Postgres, mapeando cada feature a un schema.
+
+## Consecuencias
+
+Lo que cambia a partir de esta decisión:
+
+- **Positivas:**
+  - Type-safe queries sin runtime validation
+  - Migraciones automáticas con `prisma migrate`
+  - Schemas por feature como primer paso hacia microservicios
+- **Negativas:**
+  - Vendor lock-in con Prisma (cambiar de ORM requiere reescribir repos)
+  - Migraciones lentas en bases de datos con millones de registros
+  - Dependencia de `prisma generate` como paso de build
+- **Neutrales:**
+  - El equipo necesita aprender Prisma (curva de 1-2 semanas)
+```
+
+---
+
+## Variantes
+
+### ADR Completo (recomendado para decisiones fundacionales)
+
+Incluye Contexto + Decisión + Consecuencias + Alternativas evaluadas.
+
+```md
+## Alternativas Consideradas
+
+| Alternativa | Pros | Contras | Veredicto |
+|---|---|---|---|
+| TypeORM | Maduro, Decorators | Performance pobre en joins complejos | ❌ |
+| Drizzle | SQL-like, sin decorators | Ecosistema más pequeño | ❌ |
+| Prisma | Type-safe, Migraciones, Schemas | Vendor lock-in, generate step | ✅ |
+```
+
+### ADR Ligero (para decisiones tácticas)
+
+```md
+# 0012 — Usar tRPC para endpoints internos
+
+**Estado:** Accepted
+**Fecha:** 2026-05-10
+
+**Contexto:** Los endpoints entre features dentro del monolith
+necesitan type-safety sin overhead de serialización REST.
+
+**Decisión:** Los endpoints internos en platform/http usarán tRPC.
+Los endpoints públicos siguen siendo REST con OpenAPI.
+
+**Consecuencias:** Type-safety extremo entre features pero
+acoplamiento a tRPC en la capa de plataforma.
+```
+
+### ADR de Excepción (para decisiones que violan una regla de Forge)
+
+```md
+# 0023 — Ignorar R1 temporalmente en ReportEngine
+
+**Estado:** Accepted
+**Fecha:** 2026-06-15
+**Expira:** 2026-09-15
+
+**Contexto:** ReportEngine necesita acceso directo a datos de infra
+para generar reportes en tiempo real. Extraer a servicio separado
+requiere 3 sprints.
+
+**Decisión:** Se permite `feature/reports → infra/prisma` como
+excepción temporal, documentada en ADR y con `forge-ignore: R1`
+en los imports afectados.
+
+**Consecuencias:** Degradación arquitectónica controlada.
+Se revertirá antes de la expiración.
+```
+
+---
+
+## Estados de un ADR
+
+```mermaid
+stateDiagram-v2
+    [*] --> Proposed
+    Proposed --> Accepted
+    Proposed --> Rejected
+    Accepted --> Amended
+    Accepted --> Superseded
+    Accepted --> Deprecated
+    Deprecated --> [*]
+    Superseded --> [*]
+    Amended --> Accepted
+```
+
+| Estado | Significado |
+|---|---|
+| **Proposed** | Propuesto, en discusión |
+| **Accepted** | Aprobado e implementado |
+| **Rejected** | Descartado, se preserva para no repetir |
+| **Deprecated** | Ya no se aplica, pero sigue vigente para sistemas existentes |
+| **Superseded** | Reemplazado por otro ADR |
+| **Amended** | Modificado parcialmente, el ADR original + amendment |
+
+---
+
+## Integración con Forge
+
+### ADRs y ARCHITECTURE.md
+
+`forge inscribe` debe incluir en ARCHITECTURE.md:
+
+```md
+## Architecture Decision Records
+
+| ADR | Título | Estado | Fecha |
+|---|---|---|---|
+| 0001 | Adoptar Prisma como ORM | Accepted | 2025-12-01 |
+| 0002 | Schemas separados por feature | Accepted | 2025-12-10 |
+| 0003 | Event Bus asíncrono con RabbitMQ | Proposed | 2026-01-15 |
+| 0004 | Feature Splits de Catalog a Search | Superseded por 0007 | 2026-02-01 |
+```
+
+### ADRs y `forge assay`
+
+El ensayo multi-persona (`assay`) debe considerar ADRs como fuente de información:
+
+- **Bezos**: evalúa si la decisión es reversible o irreversible
+- **Fowler**: evalúa la evolución de la decisión en el tiempo
+- **Arquitecta Senior**: evalúa consistencia con el modelo arquitectónico
+
+### ADRs y reglas inline ignore
+
+Cuando se usa `forge-ignore` para excepcionar una regla, debe referenciar el ADR que la autoriza:
+
+```ts
+// forge-ignore: R1 — ver ADR-0023
+import { PrismaClient } from "../../infra/prisma/client";
+```
+
+### ADRs y `forge quench`
+
+`forge quench` debe verificar que:
+- Los ADRs aceptados tienen su decisión implementada
+- Los ADRs con expiración no han vencido sin renovación
+- No hay `forge-ignore` sin ADR asociado
+
+---
+
+## Cuándo escribir un ADR
+
+| Situación | Ejemplo | ADR necesario |
+|---|---|---|
+| Decisión fundacional | Framework, ORM, BD, message broker | ✅ Obligatorio |
+| Patrón arquitectónico | CQRS, Event Sourcing, Sagas | ✅ Recomendado |
+| Cambio de regla de Forge | Ignorar R8 entre dos features | ✅ Obligatorio |
+| Tecnología nueva | Adoptar Redis, Elasticsearch | ✅ Recomendado |
+| Estándar de equipo | Formato de commits, naming conventions | ✅ Ligero |
+| Excepción temporal | Ignorar R1 por 3 sprints | ✅ Obligatorio |
+| Cambio de provider | Migrar de AWS a GCP | ✅ Obligatorio |
+| Refactor mayor | Extraer Catalog como microservicio | ✅ Obligatorio |
+| Dependencia externa | Adoptar librería X | ⚠️ Si tiene impacto arquitectónico |
+| Bugfix complejo | Cambio en algoritmo de pricing | ❌ |
+
+---
+
+## Estructura de directorios
+
+```
+docs/
+  adr/
+    0001-adopt-prisma-orm.md
+    0002-separate-schemas-per-feature.md
+    0003-event-bus-rabbitmq.md
+    README.md           ← index de ADRs activos
+```
+
+El `README.md` se genera automáticamente listando los ADRs activos:
+
+```bash
+# scripts/forge-adr.mjs (futuro)
+node scripts/forge-adr.mjs list    # lista todos los ADRs
+node scripts/forge-adr.mjs new     # crea nuevo ADR desde template
+node scripts/forge-adr.mjs status  # cambia estado de un ADR
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **ADR sin contexto** | "Usamos Prisma". Sin por qué ni alternativas. | Incluir motivación y alternativas consideradas siempre. |
+| **ADR sin consecuencia** | "Adoptamos Kafka" sin decir el costo operativo. | Documentar consecuencias positivas, negativas y neutrales. |
+| **ADRs que nadie lee** | Se escriben y se archivan. Nadie los consulta. | Integrar en `forge inscribe`. Mencionar en code review cuando aplica. |
+| **ADR sobre tecnología obvia** | "Usamos TypeScript" como ADR. | No todo es ADR. Si no hay trade-off significativo, no es ADR. |
+| **ADR sin fecha** | No se sabe cuándo se tomó ni si sigue vigente. | Fecha obligatoria. Estados para ciclo de vida. |
+| **Demasiados ADRs** | Cada PR tiene un ADR. Se deja de leer. | Solo decisiones con impacto arquitectónico. No para implementación cotidiana. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge inscribe` | Incluye ADRs activos en ARCHITECTURE.md |
+| `forge assay` | Usa ADRs como insumo para el ensayo multi-persona |
+| `forge quench` | Verifica que ADRs aceptados están implementados |
+| `forge inspect` | Reporta ADRs vencidos o sin implementar |
+| `forge reforge` | Sugiere crear ADR cuando se detecta un cambio arquitectónico |
+
+## Ver también
+
+- `reference/evolutionary-architecture.md` — fitness functions que los ADRs registran
+- `reference/principles.md` — principios que los ADRs documentan como decisiones

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