@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

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

package/skills/forge/reference/idempotency.md

@@ -0,0 +1,283 @@
+# Idempotency — Operaciones Seguras para Retry
+
+En sistemas distribuidos, las operaciones fallan. Los clientes reintentan. Sin idempotencia, un reintento puede crear facturas duplicadas, cargar dos veces la misma tarjeta o enviar un email dos veces. La idempotencia garantiza que N intentos producen el mismo resultado que uno.
+
+---
+
+## Definición
+
+Una operación es **idempotente** si ejecutarla una o varias veces produce el mismo efecto secundario.
+
+```ts
+GET /orders/123       → idempotente (natural, no cambia estado)
+PUT /orders/123       → idempotente (el mismo body produce el mismo estado final)
+DELETE /orders/123    → idempotente (borrar algo ya borrado no cambia nada)
+POST /orders          → NO es idempotente (crea un recurso nuevo cada vez)
+PATCH /orders/123     → NO es idempotente por defecto (depende del delta)
+```
+
+Para hacer POST y PATCH idempotentes se necesita un **idempotency key**.
+
+---
+
+## Idempotency Keys en APIs
+
+El cliente envía una clave única en el header `Idempotency-Key`. El servidor:
+1. Si la clave es nueva: ejecuta la operación, guarda la respuesta, la retorna
+2. Si la clave ya existe: retorna la respuesta guardada sin ejecutar la operación
+
+### Implementación
+
+```ts
+// Platform middleware
+// platform/http/middleware/IdempotencyMiddleware.ts
+export class IdempotencyMiddleware {
+  constructor(
+    private readonly idempotencyRepo: IIdempotencyRepository,
+    private readonly clock: IClock,
+  ) {}
+
+  async handle(req: Request, res: Response, next: NextFunction): Promise<void> {
+    // Solo para métodos mutantes
+    if (!["POST", "PATCH", "PUT"].includes(req.method)) return next();
+
+    const key = req.headers["idempotency-key"] as string;
+    if (!key) {
+      // POST sin key es válido pero no tiene protección de idempotencia
+      // Para operaciones críticas (pagos), debería ser obligatorio
+      return next();
+    }
+
+    // Validar formato UUID
+    if (!this.isValidUUID(key)) {
+      return res.status(400).json({
+        error: "Invalid idempotency key format. Must be a UUID v4.",
+      });
+    }
+
+    const existing = await this.idempotencyRepo.find(key);
+    if (existing) {
+      // Clave ya usada → devolver respuesta en caché
+      // Si la clave expiró, rechazar con 422
+      if (existing.isExpired(this.clock)) {
+        return res.status(422).json({
+          error: "Idempotency key expired. Use a new key.",
+        });
+      }
+      return res.status(existing.statusCode).json(existing.responseBody);
+    }
+
+    // Registrar clave antes de ejecutar (protege contra duplicados simultáneos)
+    await this.idempotencyRepo.save(IdempotencyEntry.pending(key, req));
+
+    // Ejecutar y guardar respuesta
+    res.on("finish", async () => {
+      await this.idempotencyRepo.save(
+        IdempotencyEntry.completed(key, res.statusCode, res.body),
+      );
+    });
+
+    next();
+  }
+}
+```
+
+### Repositorio de idempotencia
+
+```ts
+// infra/redis/IdempotencyRepository.ts
+export class RedisIdempotencyRepository implements IIdempotencyRepository {
+  private readonly TTL_SECONDS = 60 * 60 * 24; // 24 horas
+
+  constructor(private readonly redis: Redis) {}
+
+  async find(key: string): Promise<IdempotencyEntry | null> {
+    const data = await this.redis.get(`idempotency:${key}`);
+    if (!data) return null;
+    return IdempotencyEntry.fromJSON(data);
+  }
+
+  async save(entry: IdempotencyEntry): Promise<void> {
+    await this.redis.set(
+      `idempotency:${entry.key}`,
+      entry.toJSON(),
+      "EX",
+      this.TTL_SECONDS,
+    );
+  }
+}
+```
+
+### Contract en shared/
+
+```ts
+// shared/contracts/http/IIdempotencyRepository.ts
+export interface IIdempotencyRepository {
+  find(key: string): Promise<IdempotencyEntry | null>;
+  save(entry: IdempotencyEntry): Promise<void>;
+}
+```
+
+### Reglas del Idempotency Key
+
+1. **Generado por el cliente** (nunca por el servidor): el cliente necesita poder reintentar sin haber recibido respuesta
+2. **Formato UUID v4**: único, no secuencial, sin colisiones
+3. **TTL**: 24 horas típicamente. Si el cliente reintenta después del TTL, la clave expiró y debe generar una nueva
+4. **Único por recurso/operación**: un mismo key no debe reusarse para operaciones distintas
+5. **Protección de concurrencia**: dos requests simultáneos con el mismo key deben producir exactamente una ejecución (lock optimista en Redis)
+
+---
+
+## Idempotencia en Eventos
+
+Los consumidores de eventos deben deduplicar por event ID para garantizar exactly-once processing.
+
+```ts
+// base consumer pattern
+export abstract class IdempotentEventConsumer<T extends DomainEvent> {
+  constructor(
+    protected readonly processedEvents: IProcessedEventRepository,
+  ) {}
+
+  async handle(event: T): Promise<void> {
+    // 1. Deduplicación
+    const alreadyProcessed = await this.processedEvents.exists(event.eventId);
+    if (alreadyProcessed) return;
+
+    // 2. Ejecutar lógica de negocio
+    await this.processEvent(event);
+
+    // 3. Marcar como procesado (idealmente en la misma transacción)
+    await this.processedEvents.markProcessed(event.eventId);
+  }
+
+  protected abstract processEvent(event: T): Promise<void>;
+}
+```
+
+```ts
+// Implementación concreta
+export class OrderPlacedHandler extends IdempotentEventConsumer<OrderPlacedEvent> {
+  constructor(
+    processedEvents: IProcessedEventRepository,
+    private readonly inventoryService: IInventoryService,
+  ) {
+    super(processedEvents);
+  }
+
+  protected async processEvent(event: OrderPlacedEvent): Promise<void> {
+    await this.inventoryService.reserveStock(event.orderId, event.items);
+  }
+}
+```
+
+### Tabla de eventos procesados
+
+```sql
+CREATE TABLE IF NOT EXISTS public.processed_events (
+  event_id      VARCHAR(255) PRIMARY KEY,
+  consumer_name VARCHAR(255) NOT NULL,
+  processed_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Cleanup periódico: eventos procesados > 7 días
+CREATE INDEX idx_processed_events_cleanup ON public.processed_events (processed_at);
+```
+
+---
+
+## Idempotencia Natural por Operación
+
+| Operación HTTP | Idempotencia natural | Cómo hacerla idempotente |
+|---|---|---|
+| **GET** | ✅ Sí | Nada. Es idempotente por definición. |
+| **PUT** | ✅ Sí | Mismo body → mismo estado. |
+| **DELETE** | ✅ Sí | Borrar algo ya borrado no cambia estado. |
+| **POST** | ❌ No | Idempotency-Key header. |
+| **PATCH** | ❌ No | Idempotency-Key header + operaciones basadas en estado (ej. "set status = X" es idempotente, "increment count" no lo es). |
+
+### Operaciones condicionalmente idempotentes
+
+```ts
+// ❌ NO idempotente: el resultado cambia cada vez
+PATCH /orders/123 { "action": "addItem", "productId": "abc" }
+
+// ✅ Idempotente: el resultado es el mismo estado final
+PUT /orders/123 { "items": ["abc", "def"] }
+
+// ✅ Condicionalmente idempotente con idempotency key
+POST /orders/123/items
+Idempotency-Key: uuid-abc-123
+Body: { "productId": "abc", "quantity": 1 }
+```
+
+---
+
+## Implementación en el Modelo de Forge
+
+### Estructura
+
+```
+src/platform/
+  http/
+    middleware/
+      IdempotencyMiddleware.ts    ← middleware que intercepta requests
+    contracts/
+      IIdempotencyRepository.ts   ← interfaz en shared/
+
+src/infra/
+  redis/
+    IdempotencyRepository.ts      ← implementación con Redis
+
+src/features/<name>/
+  adapters/
+    in/
+      events/
+        <Name>Handler.ts          ← consumer con deduplicación
+    out/
+      persistence/
+        ProcessedEventRepository.ts ← tabla processed_events
+```
+
+### Reglas de ubicación
+
+| Componente | Capa | Razón |
+|---|---|---|
+| Middleware HTTP | platform/ | Es infraestructura transversal |
+| Interfaz IIdempotencyRepository | shared/contracts/ | Contrato puro sin implementación |
+| Implementación Redis | infra/ | Implementación concreta |
+| IdempotencyKey generación | Cliente (frontend/CLI) | El cliente necesita la clave antes del request |
+| Deduplicación en consumidores | feature/adapters/in/events/ | Específico del feature |
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Idempotency sin expiración** | Las claves se acumulan infinitamente. | TTL obligatorio (24h típico). Configurable por operación. |
+| **Claves generadas por el servidor** | El servidor genera la key y la devuelve. Si la respuesta se pierde, el cliente no puede reintentar. | El cliente genera la key (UUID v4). El servidor solo la valida. |
+| **Idempotencia en GET** | GET debe ser idempotente por definición. Si no lo es, el problema es otro (efectos secundarios en GET). | No añadir idempotency keys a GET. Mover efectos secundarios a POST/PUT. |
+| **Mutex como idempotencia** | Bloquear el recurso en vez de deduplicar la operación. | Idempotencia no es locking. La clave permite deduplicar sin bloquear. |
+| **Idempotency key corta** | Claves predecibles (incrementales, timestamp). Un cliente puede adivinar claves de otros. | UUID v4 obligatorio. No secuencial. No predecible. |
+| **No verificar método** | El middleware aplica a GET también, añadiendo latencia innecesaria. | Solo POST, PATCH, PUT. GET pasa sin verificar. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Incluir idempotency middleware + repo Redis en features críticas |
+| `forge quench` | Regla detect: feature con POST sin idempotency key |
+| `forge inspect` | Reporta endpoints sin protección de idempotencia |
+| `forge api` | Verifica que los contratos OpenAPI incluyen idempotency-key header |
+| `forge temper` | Endurece DI del middleware de idempotencia |
+
+## Ver también
+
+- `reference/transactional-outbox.md` — deduplicación en relayer
+- `reference/api-design.md` — idempotency-key header en APIs
+- `reference/events.md` — handlers idempotentes
+- `reference/sagas.md` — retry seguro en sagas

package/skills/forge/reference/inscribe.md

@@ -127,3 +127,8 @@ Genera y mantiene el archivo `ARCHITECTURE.md` del proyecto.
 - Se actualiza automáticamente después de cada comando
 - No editar manualmente los campos auto-detectados
 - Forge preserva cualquier sección adicional que el usuario agregue
+
+## Ver también
+
+- `reference/adr.md` — Architecture Decision Records como insumo para ARCHITECTURE.md
+- `reference/principles.md` — principios arquitectónicos documentados en ARCHITECTURE.md

package/skills/forge/reference/inspect.md

@@ -55,4 +55,10 @@ Inspecciona la conformidad arquitectónica del proyecto.
 node .opencode/skills/forge/scripts/inspect.mjs
 node .opencode/skills/forge/scripts/inspect.mjs --json
 node .opencode/skills/forge/scripts/detect.mjs --severity ERROR
+
+## Ver también
+
+- `reference/evolutionary-architecture.md` — fitness functions como complemento al inspect
+- `reference/assay.md` — interpretación cualitativa multi-persona del reporte de inspect
+- `reference/principles.md` — principios contra los que inspect evalúa el proyecto
 ```