@ronaldjdevfs/forge 1.3.0-beta → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 <img src="favicon.svg" alt="Forge Logo" width="100" height="100">
 
-> **v1.3.0-beta** — Multi-Agent: OpenCode · Claude Code · Cursor · Codex CLI · Gemini
+> **v1.3.1** — Bugfixes, New Templates & Interactive Flags
 
 ## Forge — Backend Architecture Operating System
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronaldjdevfs/forge",
-  "version": "1.3.0-beta",
+  "version": "1.3.1",
   "description": "Forge — Architecture Operating System for backend systems. Arquitectura Hexagonal, DDD pragmático y vertical slices.",
   "type": "module",
   "bin": {

package/skills/forge/SKILL.md

@@ -70,57 +70,55 @@ En esencia:
 
 ---
 
-## Boot Sequence (OBLIGATORIO — ejecutar siempre antes de responder)
+## Boot Sequence
 
-ANTES de cualquier acción, Forge DEBE ejecutar esta secuencia. Si no lo haces, puedes dar respuestas incorrectas:
-
-1. **context.mjs** — Detectar stack, platform, features, shared, infra, grafo, estado
-2. **armorer.mjs** — Detectar ownership, huérfanos, duplicados, mal ubicados
-3. **profile.mjs** — Determinar perfil tecnológico
-4. **graph.mjs** — Construir grafo arquitectónico global (4 capas + 9 reglas)
-5. **chain.mjs** — Analizar dependencias multi-capa
-6. **inspect.mjs** — Auditoría completa con ownership + platform
-7. **architecture.mjs** — Generar/actualizar ARCHITECTURE.md
-8. **Ejecutar comando solicitado** — cast, quench, temper, etc.
-9. **forgeSentinel** — Verificar cambios tras escritura (`scripts/forgeSentinel.mjs --reminder`)
-10. **Actualizar ARCHITECTURE.md** — Reflejar nuevo estado
+ANTES de cualquier acción, Forge DEBE ejecutar `forge-boot.mjs` con la profundidad adecuada al comando:
 
 ```bash
-# Template de setup que debes ejecutar:
-ctx=$(node .opencode/skills/forge/scripts/context.mjs --json 2>/dev/null)
-armorer=$(node .opencode/skills/forge/scripts/armorer.mjs --json 2>/dev/null)
-profile=$(node .opencode/skills/forge/scripts/profile.mjs --extended 2>/dev/null)
-graph=$(node .opencode/skills/forge/scripts/graph.mjs --json 2>/dev/null)
-deps=$(node .opencode/skills/forge/scripts/chain.mjs --json 2>/dev/null)
-inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
+boot=$(node .opencode/skills/forge/scripts/forge-boot.mjs --depth <depth> --json 2>/dev/null)
 ```
 
+La profundidad (`--depth`) depende del comando (ver Execution Flow):
+- **minimal** → context + profile (cast, temper, smelt, relocate, reforge, inscribe)
+- **standard** → minimal + graph + chain (chain, graph, forge hook)
+- **full** → standard + ownership + inspect (inspect, quench, default)
+
+Si `$boot` contiene datos cacheados en `.forge/cache/` se reusan automáticamente. Pasa `--force` para regenerar.
+
 ---
 
 ## Command Routing
 
-| Lenguaje natural | Comando | Archivo |
+| Intención | Comando | Referencia |
 |---|---|---|
-| "ayuda", "help", "comandos", "lista", "--help" | `forge --help` | `reference/help.md` |
-| "inicializar", "setup", "empezar" | `forge` | `reference/forge.md` |
-| "crear feature", "nuevo dominio" | `cast` | `reference/cast.md` |
-| "inspeccionar", "diagnóstico", "evaluar" | `inspect` | `reference/inspect.md` |
-| "trasladar", "mover", "reestructurar feature" | `relocate` | `reference/relocate.md` |
-| "refactorizar", "rediseñar", "cambiar estructura" | `reforge` | `reference/reforge.md` |
-| "verificar", "quench", "checklist" | `quench` | `reference/quench.md` |
-| "templar", "endurecer", "mejorar" | `temper` | `reference/temper.md` |
-| "cadena", "grafo", "acoplamiento" | `chain` | `scripts/chain.mjs` |
-| "inscribir", "grabar", "ARCHITECTURE.md" | `inscribe` | `reference/inscribe.md` |
-| "grafo", "graph", "nodo", "violaciones", "risk score" | `graph` | `scripts/graph.mjs` |
-| "fundir", "compartir", "mover a shared" | `smelt` | `reference/smelt.md` |
-| "ownership", "huérfanos", "armorer" | `inspect` | (incluido en auditoría) |
-| "fijar", "pinar", "atajo", "shortcut" | `nail` | `scripts/pin.mjs` |
-| "desfijar", "despinar", "remover atajo" | `unnail` | `scripts/pin.mjs` |
-| "hook", "pre-commit", "githook", "validar commit" | `forge hook` | `reference/hooks.md` |
-| "api", "contrato", "openapi", "swagger", "graphql" | `forge api` | `scripts/forge-api.mjs` |
-| "rollback", "restaurar", "deshacer", "backup" | `forge rollback` | `scripts/rollback.mjs` |
-| "estado", "state", "último audit" | `forge state --show` | `scripts/forge-state.mjs` |
-| "examinar","calidad", "assay", "opinión", "personas", "critique", "evaluación cualitativa" | `assay` | `reference/assay.md` |
+| Ayuda | `forge --help` | `reference/help.md` |
+| Setup inicial | `forge` | `reference/forge.md` |
+| Crear feature | `cast` | `reference/cast.md` |
+| Auditar | `inspect` | `reference/inspect.md` |
+| Relocalizar feature | `relocate` | `reference/relocate.md` |
+| Refactorizar | `reforge` | `reference/reforge.md` |
+| Verificar violaciones | `quench` | `reference/quench.md` |
+| Endurecer | `temper` | `reference/temper.md` |
+| Dependencias | `chain` | `scripts/chain.mjs` |
+| Inscribir ARCHITECTURE.md | `inscribe` | `reference/inscribe.md` |
+| Grafo arquitectónico | `graph` | `scripts/graph.mjs` |
+| Fundir a shared | `smelt` | `reference/smelt.md` |
+| Atajo / pin | `nail` / `unnail` | `scripts/pin.mjs` |
+| Git hook | `forge hook` | `reference/hooks.md` |
+| API design | `forge api` | `scripts/forge-api.mjs` |
+| Rollback | `forge rollback` | `scripts/rollback.mjs` |
+| Estado | `forge state` | `scripts/forge-state.mjs` |
+| Ensayo cualitativo | `assay` | `reference/assay.md` |
+| Bounded context | `forge` | `reference/bounded-contexts.md` |
+| Modular monolith | `forge` | `reference/modular-monolith.md` |
+| ADR | `inscribe` | `reference/adr.md` |
+| Anti-corruption layer | `relocate` | `reference/anti-corruption-layer.md` |
+| Evolutionary arch | `reforge` | `reference/evolutionary-architecture.md` |
+| CQRS | `cast` | `reference/cqrs.md` |
+| Sagas | `cast` | `reference/sagas.md` |
+| Outbox | `cast` | `reference/transactional-outbox.md` |
+| Idempotencia | `forge` | `reference/idempotency.md` |
+| API versioning | `forge api` | `reference/api-versioning.md` |
 
 ---
 
@@ -128,15 +126,17 @@ inspect=$(node .opencode/skills/forge/scripts/inspect.mjs --json 2>/dev/null)
 
 Para cada comando, Forge sigue este flujo:
 
-1. **Contexto**: Ejecutar `context.mjs` + `armorer.mjs` + `profile.mjs`
-2. **Grafo**: Ejecutar `graph.mjs` + `chain.mjs`
-3. **Auditoría**: Ejecutar `inspect.mjs`
-4. **Referencia**: Cargar `reference/<command>.md`
-5. **Ejecutar**: Aplicar el flujo definido en la referencia, usando los scripts según corresponda
-6. **Verificar**: Ejecutar `scripts/detect.mjs` para verificar que no se introdujeron violaciones
-7. **forgeSentinel**: Ejecutar `scripts/forgeSentinel.mjs --reminder` para reportar cambios
-8. **Actualizar ARCHITECTURE.md**: Reflejar el nuevo estado (`architecture.mjs`)
-9. **Reportar**: Mostrar resultado al usuario con severidades
+1. **Boot condicional**: Ejecutar `forge-boot.mjs --depth <depth>` donde depth es:
+   - `minimal` para cast, temper, smelt, relocate, reforge, inscribe
+   - `standard` para chain, graph, forge hook
+   - `full` para inspect, quench, o cualquier otro comando
+2. **Referencia**: Cargar `reference/<command>.md`
+3. **Ejecutar**: Aplicar el flujo definido en la referencia
+4. **Verificar**: Ejecutar `detect.mjs --summary` (resumen compacto)
+5. **Actualizar ARCHITECTURE.md**: `architecture.mjs` (solo en full)
+6. **Reportar**: Mostrar resultado al usuario con severidades
+
+El boot usa caché de `.forge/cache/`. Si los archivos `src/` no cambiaron, los datos se reusan. Usa `forge-boot.mjs --force` para regenerar todo.
 
 ---
 
@@ -169,87 +169,13 @@ import { crossFeature } from "../other-feature/domain/Entity"; // ← R1 y R8 ig
 
 ## ARCHITECTURE.md
 
-Forge mantiene un archivo `ARCHITECTURE.md` en la raíz del proyecto con el contexto persistente. Contiene:
-
-```md
-# Architecture State
-
-- Project Name: <name>
-- Framework: <detectado>
-- Runtime: <detectado>
-- Database: <detectado>
-- ORM: <detectado>
-- DI Strategy: <detectado>
-- Profile: <detectado>
-- Architecture: hexagonal-feature (Platform + Features + Shared + Infra)
-- Last Audit: <fecha> (score: <puntaje>)
-
-## Platform
-- platform/config/
-- platform/server/
-...
-
-## Features
-- features/users/
-...
-
-## Shared
-- shared/errors/
-...
-
-## Infrastructure
-- infra/prisma/
-...
-
-## Ownership
-- Health: healthy | degraded | critical
-- Score: 0-100
-- Orphans: 0
-- Duplicates: 0
-- Misplaced: 0
-
-## Architecture Graph
-...
-
-## Dependency Health
-...
-```
+Forge mantiene `ARCHITECTURE.md` en la raíz con el estado persistente del proyecto (framework, DB, features, ownership, graph). Se genera y actualiza con `architecture.mjs`.
 
-El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo al finalizar cada comando.
+El agente DEBE leer este archivo al inicio de cada interacción y actualizarlo al finalizar cada comando. Ver `scripts/architecture.mjs` para el formato completo.
 
 ---
 
-## Module Index
-
-| Módulo | Propósito |
-|---|---|
-| `reference/principles.md` | Manifiesto y 12 principios inquebrantables |
-| `reference/patterns.md` | Convenciones de nomenclatura globales (PascalCase.artifact, kebab dirs, etc.) |
-| `reference/errors.md` | Manejo de errores tipados en dominio y aplicación |
-| `reference/di-strategies.md` | Estrategias de inyección de dependencias según tamaño |
-| `reference/testing-patterns.md` | Pirámide de tests, unit mocks, integration tests |
-| `reference/api-design.md` | REST / GraphQL, paginación, validación, contratos |
-| `reference/observability.md` | Logging, tracing, métricas, health checks |
-| `reference/data-patterns.md` | Repository, Unit of Work, CQRS, Event Sourcing |
-| `reference/security-patterns.md` | AuthN, AuthZ, RBAC, rate limiting, validación |
-| `reference/events.md` | Eventos de dominio, outbox pattern, sagas |
-| `reference/hooks.md` | Git pre-commit hook para validación arquitectónica |
-| `reference/help.md` | Lista completa de comandos y flags de Forge |
-| `reference/assay.md` | Ensayo arquitectónico multi-persona — interpretación cualitativa del audit |
-| `profiles/` | Perfiles tecnológicos detallados (Express, Fastify, NestJS, etc.) |
-| `scripts/` | Scripts: context, detect, inspect, chain, profile, graph, architecture, armorer, bootstrap, forge-config, forge-signals, forge-state, forge-api, pin, update, rollback, hook, forgeSentinel, forgeSentinel-lib, forgeSmith, forgeSmith-admin, formatter, assay, registry/rules |
-| `scripts/registry/rules.mjs` | Anti-pattern rule registry (R1-R9 + custom rules desacopladas de detect.mjs) |
-| `scripts/formatter.mjs` | Output formatter unificado (JSON, tabla, severidad coloreada, scoreBar, formatCheck, formatViolation) |
-| `scripts/forgeSentinel.mjs` | PostToolUse hook — analiza archivos modificados tras escritura y reporta violaciones |
-| `scripts/forgeSentinel-lib.mjs` | Lógica compartida para hooks forgeSentinel y forgeSmith |
-| `scripts/forgeSmith.mjs` | preToolUse gate — previene escrituras con violaciones CRITICAL/ERROR (Cursor) |
-| `scripts/forgeSmith-admin.mjs` | Gestión de hooks (on/off/status) |
-| `scripts/assay.mjs` | Motor de ensayo arquitectónico multi-persona (Bezos, Fowler, Hacker, PM, Arquitecta Senior) |
-| `templates/feature/` | Templates de feature (entity, repository, uc, controller, routes, schema, mapper) |
-| `templates/platform/` | Templates de platform (config, server, database, logger, http, di) |
-| `templates/shared/` | Templates de shared (errors, contracts, types, utils) |
-| `templates/infra/` | Templates de infra (prisma, mongodb, redis, mail) |
-| `command/forge.md` | Definición del comando `/forge` para opencode |
+> 📚 Todas las referencias están en `reference/`. La tabla de routing arriba mapea cada comando a su referencia. Ver `reference/help.md` para la lista completa de flags.
 
 ### Tests
 
@@ -269,8 +195,11 @@ node --test .opencode/skills/forge/tests/core.test.mjs
 | `formatter.mjs` | 4 | Output format, colores, JSON |
 | `registry/rules.mjs` | 4 | R1-R9, evaluación, custom rules |
 | `detect.mjs` (inline ignores) | 5 | parseInlineIgnores, isIgnored |
-| `forgeSentinel.mjs` | 1 | PostToolUse hook |
+| `posttool.mjs` | 1 | PostToolUse hook |
 | `assay.mjs` | 4 | Personas, generateAssay, opiniones |
+| transactional-outbox | 5 | Entry lifecycle, retry, DLQ, required fields, pending |
+| idempotency | 5 | UUID validation, cached response, different keys, TTL, method filter |
+| anti-corruption-layer | 5 | DTO mapping (2 dirs), null handling, 404, delegation order |
 
 ### Flags adicionales
 

package/skills/forge/command/forge.md

@@ -1,29 +1,51 @@
 ---
-description: Forge — Backend Architecture OS. Subcomandos: forge, cast, inspect, relocate, reforge, quench, temper, chain, inscribe, smelt.
+description: Forge — Backend Architecture OS. Comandos: forge, cast, inspect, assay, quench, chain, graph, armorer, inscribe, smelt, relocate, reforge, temper.
 agent: build
 ---
 
 Ejecuta herramientas de Forge según el subcomando especificado en $ARGUMENTS.
 
+Si el subcomando NO tiene flags en $ARGUMENTS y tiene flags disponibles (ver tabla abajo), pregunta al usuario cuáles quiere usar con la `question` tool (tipo checkboxes múltiples). Si el usuario no selecciona ninguna, ejecuta sin flags.
+
+| Comando | Flags disponibles |
+|---------|------------------|
+| `forge` | Sin flags |
+| `cast` | Sin flags (pide nombre del feature interactivamente) |
+| `inspect` | `--json`, `--diff`, `--full`, `--summary`, `--severity=<nivel>`, `--force` |
+| `assay` | `--persona=<id>`, `--json`, `--save`, `history` |
+| `quench` | `--fix`, `--show-ignores`, `--severity=<nivel>`, `--json` |
+| `chain` | `--json` |
+| `graph` | `--json` |
+| `armorer` | Sin flags |
+| `inscribe` | `--output=<path>` |
+| `smelt` | Sin flags (pide qué extraer interactivamente) |
+| `relocate` | Sin flags (pide feature y destino) |
+| `reforge` | `--cycles` |
+| `temper` | Sin flags |
+
 ## Build
 
 ### forge
 
-Inicializa el proyecto arquitectónicamente (incluye platform, shared, infra).
+Inicializa el proyecto arquitectónicamente. Ejecuta context + bootstrap + profile + armorer + graph + chain + inscribe.
 
 ```
 node .opencode/skills/forge/scripts/context.mjs
 node .opencode/skills/forge/scripts/bootstrap.mjs
+node .opencode/skills/forge/scripts/profile.mjs
 node .opencode/skills/forge/scripts/armorer.mjs
+node .opencode/skills/forge/scripts/graph.mjs
+node .opencode/skills/forge/scripts/chain.mjs
+node .opencode/skills/forge/scripts/architecture.mjs
 ```
 
 ### cast
 
-Crea un nuevo feature (verifica platform/shared/infra primero).
+Crea un nuevo feature. Primero verifica que platform/shared/infra existan; si falta, llama a bootstrap.
 
 ### relocate
 
-Migra un feature existente.
+Migra un feature existente. Puede targetizar platform/, shared/, infra/ o features/.
 
 ### inscribe
 
@@ -33,9 +55,9 @@ Genera ARCHITECTURE.md con grafo arquitectónico, ownership y platform.
 node .opencode/skills/forge/scripts/architecture.mjs
 ```
 
-### architecture
+### graph
 
-Construye el grafo arquitectónico del proyecto (4 capas: platform, feature, shared, infra).
+Construye el grafo arquitectónico del proyecto (4 capas: platform, feature, shared, infra) con reglas R1-R9.
 
 ```
 node .opencode/skills/forge/scripts/graph.mjs
@@ -49,11 +71,11 @@ node .opencode/skills/forge/scripts/graph.mjs --json
 
 ### smelt
 
-Extrae código reutilizable a shared/.
+Extrae código reutilizable a shared/ (solo código puro, sin dependencias infra/feature).
 
 ### bootstrap
 
-Inicializa platform, shared e infra layers (interno, se ejecuta automáticamente).
+Inicializa platform, shared e infra layers (uso interno, se ejecuta automáticamente).
 
 ```
 node .opencode/skills/forge/scripts/bootstrap.mjs
@@ -63,7 +85,7 @@ node .opencode/skills/forge/scripts/bootstrap.mjs
 
 ### inspect
 
-Inspecciona la conformidad arquitectónica (incluye ownership y platform).
+Audita la conformidad arquitectónica completa. 6 categorías: structure(20), layers(20), ownership(20), platform(15), dependencies(15), graph(20).
 
 ```
 node .opencode/skills/forge/scripts/inspect.mjs
@@ -75,9 +97,26 @@ Para salida JSON:
 node .opencode/skills/forge/scripts/inspect.mjs --json
 ```
 
+### assay
+
+Ensayo arquitectónico multi-persona. Interpretación cualitativa del audit desde 5 perspectivas (Bezos, Fowler, Hacker, PM, Arquitecta Senior).
+
+```
+node .opencode/skills/forge/scripts/assay.mjs
+```
+
+Filtros:
+
+```
+node .opencode/skills/forge/scripts/assay.mjs --persona=bezos
+node .opencode/skills/forge/scripts/assay.mjs --json
+node .opencode/skills/forge/scripts/assay.mjs --save
+node .opencode/skills/forge/scripts/assay.mjs history
+```
+
 ### quench
 
-Verifica reglas arquitectónicas.
+Valida reglas arquitectónicas R1-R9.
 
 ```
 node .opencode/skills/forge/scripts/detect.mjs
@@ -85,15 +124,21 @@ node .opencode/skills/forge/scripts/detect.mjs
 
 ### chain
 
-Analiza dependencias multi-capa (platform, features, shared, infra).
+Orden topológico de dependencias multi-capa (platform, features, shared, infra).
 
 ```
 node .opencode/skills/forge/scripts/chain.mjs
 ```
 
+Para salida JSON:
+
+```
+node .opencode/skills/forge/scripts/chain.mjs --json
+```
+
 ### armorer
 
-Detecta ownership, huérfanos, duplicados y mal ubicados.
+Reporte de ownership: huérfanos, duplicados, componentes mal ubicados.
 
 ```
 node .opencode/skills/forge/scripts/armorer.mjs
@@ -103,8 +148,8 @@ node .opencode/skills/forge/scripts/armorer.mjs
 
 ### reforge
 
-Refactoriza la arquitectura de un feature.
+Refactoriza la arquitectura de un feature considerando las 4 capas.
 
 ### temper
 
-Fortalece la arquitectura (DI, seguridad, consistencia).
+Fortalece la arquitectura: constructor injection, sin service locators.

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