@ronaldjdevfs/forge 1.0.1 → 1.1.0

package/skills/forge/reference/events.md

@@ -0,0 +1,95 @@
+# Events — Eventos de dominio, outbox, sagas
+
+## Principios
+
+- Los eventos representan **hechos consumados** en el dominio (pasado simple).
+- Se emiten desde el use case después de persistir, nunca antes.
+- El event bus es infraestructura (platform/events/); el dominio solo define la interfaz.
+- Los handlers están en `adapters/` (out) del feature que reacciona al evento.
+
+## Estructura
+
+```
+features/<name>/
+  domain/
+    events/
+      UserCreated.event.ts
+      UserEmailChanged.event.ts
+```
+
+## Evento de dominio
+
+```ts
+// features/users/domain/events/UserCreated.event.ts
+export class UserCreatedEvent {
+  constructor(
+    public readonly userId: string,
+    public readonly email: string,
+    public readonly occurredAt: Date = new Date(),
+  ) {}
+}
+```
+
+## Emisión desde use case
+
+```ts
+// features/users/application/use-cases/CreateUser.uc.ts
+export class CreateUserUseCase {
+  constructor(
+    private readonly userRepo: IUserRepository,
+    private readonly eventBus: IEventBus,
+  ) {}
+
+  async execute(dto: CreateUserDTO): Promise<UserEntity> {
+    const user = UserEntity.create(dto);
+    const saved = await this.userRepo.save(user);
+    this.eventBus.publish(new UserCreatedEvent(saved.id, saved.email));
+    return saved;
+  }
+}
+```
+
+## Event Bus
+
+```ts
+// platform/events/EventBus.ts
+export interface IEventBus {
+  publish(event: object): void;
+  subscribe<T>(eventType: new (...args: any[]) => T, handler: (event: T) => Promise<void>): void;
+}
+```
+
+## Outbox Pattern
+
+Para eventos que **deben** entregarse de forma confiable (ej: notificar a otro servicio).
+
+1. El use case persiste el evento en una tabla `outbox` dentro de la misma transacción de BD.
+2. Un worker independiente lee la outbox y publica los eventos al message broker.
+3. Elimina o marca como enviado tras confirmación del broker.
+
+```
+features/<name>/adapters/out/persistence/
+  ├── User.repository.ts
+  └── Outbox.repository.ts
+```
+
+## Sagas / Process Managers
+
+Para flujos multi-paso que abarcan múltiples features.
+
+```ts
+// features/orders/application/sagas/CreateOrder.saga.ts
+// 1. OrderCreated → PaymentRequired
+// 2. PaymentConfirmed → InventoryReserved
+// 3. InventoryReserved → OrderConfirmed
+// 4. Si falla: compensar (rollback) cada paso
+```
+
+## Buenas prácticas
+
+- Eventos en pasado (`UserCreated`, `EmailChanged`), nunca (`CreateUser`, `ChangeEmail`)
+- Un evento por handler. Si un handler falla, no bloquea otros.
+- Idempotencia en handlers: processar el mismo evento dos veces produce el mismo resultado.
+- Eventos sin lógica: son datos, no comportamiento.
+- Para integración entre features: el feature A emite evento, el feature B lo escucha. Nunca import directo.
+- Outbox para garantía de entrega; in-memory event bus solo para tests o monolitos pequeños.

package/skills/forge/reference/help.md

@@ -0,0 +1,40 @@
+# forge — Ayuda
+
+## Uso
+  forge <comando> [flags]
+
+## Comandos
+
+  forge               Inicializar proyecto (boot sequence completa)
+  cast                Crear nuevo feature con estructura hexagonal
+  inspect             Auditoría arquitectónica (110pts → 0-100)
+  relocate            Migrar código legacy a features/platform/shared/infra
+  reforge             Refactorizar arquitectura multi-capa
+  quench              Validar reglas R1-R9 (--fix auto-corrige)
+  temper              Endurecer inyección de dependencias
+  chain               Grafo de dependencias multi-capa
+  graph               Grafo arquitectónico con risk score
+  inscribe            Generar/actualizar ARCHITECTURE.md
+  smelt               Extraer código puro a shared/
+  assay               Ensayo multi-persona (--persona=, --save)
+  nail                Crear shortcut de navegación
+  unnail              Eliminar shortcut de navegación
+  forge state         Estado persistente post-auditoría
+  forge hook          Git pre-commit hook
+  forge api           Validación de contratos API
+  forge rollback      Restauración de puntos de guardado
+  forge update        Verificar actualizaciones
+
+## Flags
+
+  --fix               Auto-corregir violaciones (quench)
+  --show-ignores      Mostrar inline ignores (quench)
+  --persona=<id>      Filtrar ensayo por persona (assay)
+  --save              Persistir ensayo en .forge/assay/ (assay)
+  --json              Salida JSON (assay, forge state)
+
+## Inline Ignores
+
+  // forge-ignore-next-line
+  // forge-ignore: R1
+  // forge-ignore: R1, R8

package/skills/forge/reference/hooks.md

@@ -0,0 +1,62 @@
+# Hook — Git pre-commit hook arquitectónico
+
+## Propósito
+
+Validar automáticamente la arquitectura del proyecto antes de cada commit,
+bloqueando commits que introduzcan violaciones CRITICAL o ERROR en los
+archivos staged.
+
+## Uso
+
+```bash
+# Instalar el hook pre-commit
+forge hook install
+
+# Ver estado
+forge hook status
+
+# Ignorar una regla específica
+forge hook ignore R1
+
+# Dejar de ignorar
+forge hook unignore R1
+
+# Listar reglas ignoradas
+forge hook list-ignored
+
+# Ejecutar validación manual sobre staged files
+forge hook check
+
+# Desinstalar
+forge hook uninstall
+```
+
+## Comportamiento
+
+El hook ejecuta `detect.mjs` sobre los archivos staged con extensión
+`.ts`, `.js`, `.mjs`, `.tsx`, `.jsx` dentro de `src/`. Si encuentra
+violaciones de severidad CRITICAL o ERROR que afecten a archivos staged:
+
+1. Muestra las violaciones con su severidad y fix sugerido
+2. Bloquea el commit (exit code 1)
+3. Sugiere cómo ignorar la regla si es necesario
+
+El commit puede saltarse con `git commit --no-verify`.
+
+## Archivos de configuración
+
+| Archivo | Propósito |
+|---------|-----------|
+| `.forge/hooks-ignore.json` | Lista de reglas ignoradas por el hook |
+| `.git/hooks/pre-commit` | Script instalado por `forge hook install` |
+
+## Reglas ignoradas
+
+Las reglas ignoradas se almacenan en `.forge/hooks-ignore.json`:
+
+```json
+{ "ignored": ["R1", "R7", "R9"] }
+```
+
+Cuando una regla está ignorada, el hook no bloquea el commit por
+violaciones de esa regla, aunque el detector sigue reportándolas.

package/skills/forge/reference/observability.md

@@ -0,0 +1,66 @@
+# Observability — Logging, tracing, métricas, health checks
+
+## Principios
+
+- Observabilidad es infraestructura, no dominio. Toda instrumentación está en `platform/` o `adapters/`.
+- El dominio nunca escribe logs ni emite métricas directamente.
+- Usar OpenTelemetry como estándar unificado.
+
+## Estructura recomendada
+
+```
+src/platform/observability/
+  ├── Metrics.ts         → Contadores, histogramas (Prometheus / OTel)
+  ├── Tracing.ts         → Trazas distribuidas (OpenTelemetry)
+  ├── Health.ts          → Health checks agregados
+  ├── Logger.service.ts  → Logger estructurado (pino, winston)
+  └── Logger.config.ts   → Niveles, formatos, transports
+```
+
+## Logging estructurado
+
+```ts
+// platform/observability/Logger.service.ts
+export class LoggerService {
+  info(msg: string, ctx?: Record<string, unknown>): void {
+    pino.info({ msg, ...ctx });
+  }
+  error(msg: string, err?: Error, ctx?: Record<string, unknown>): void {
+    pino.error({ msg, err: { message: err?.message, stack: err?.stack }, ...ctx });
+  }
+}
+```
+
+Inyectar en use cases solo si es estrictamente necesario (auditoría). Preferir middlewares de logging.
+
+## Health checks
+
+```ts
+// platform/observability/Health.ts
+export interface IHealthCheck {
+  name: string;
+  check(): Promise<{ status: "ok" | "degraded" | "down"; detail?: string }>;
+}
+
+// GET /health → { status: "ok", checks: [{ name: "db", status: "ok" }, ...] }
+// GET /health/ready → readiness (dependencias listas)
+// GET /health/live → liveness (proceso vivo)
+```
+
+## Métricas clave
+
+| Métrica | Tipo | Descripción |
+|---------|------|-------------|
+| `http_requests_total` | Counter | Total requests por método, ruta, status |
+| `http_request_duration_seconds` | Histogram | Latencia por ruta |
+| `db_query_duration_seconds` | Histogram | Latencia de queries por repositorio |
+| `feature_uc_execution_seconds` | Histogram | Duración de use cases por feature |
+
+## Buenas prácticas
+
+- Correlation ID en cada request (inyectado en platform/http/)
+- Logs en JSON siempre. Nivel info para flujo normal, debug para detalle, warn/error para anomalías.
+- No loggear datos sensibles (PII, passwords, tokens)
+- Tracing distribuido con baggage contextual
+- Health checks sin autenticación (solo para orquestadores)
+- Alertas basadas en métricas, no en logs

package/skills/forge/reference/patterns.md

@@ -86,6 +86,58 @@ src/features/<feature-name>/
 
 ---
 
+## Events
+
+| Archivo | Formato | Ejemplo |
+|---------|---------|---------|
+| Eventos de dominio | `<Domain><Accion>.event.ts` | `UserCreated.event.ts`, `OrderPaid.event.ts` |
+| Handlers | `<Domain><Accion>.handler.ts` | `SendWelcomeEmail.handler.ts` |
+| Outbox record | `<Entidad>.outbox.ts` | `User.outbox.ts` |
+
+Los eventos siempre en pasado (`Created`, `Updated`, `Deleted`, `Paid`, `Shipped`), nunca en imperativo.
+
+---
+
+## Observability
+
+| Archivo | Formato | Ejemplo |
+|---------|---------|---------|
+| Loggers | `Logger.service.ts`, `Logger.config.ts` | — |
+| Métricas | `Metrics.ts`, `Metrics.middleware.ts` | — |
+| Tracing | `Tracing.ts` | — |
+| Health | `Health.ts`, `Health.controller.ts` | — |
+
+Toda instrumentación vive en `platform/observability/`.
+Para referencia completa ver `reference/observability.md`.
+
+---
+
+## Errors
+
+| Archivo | Formato | Ejemplo |
+|---------|---------|---------|
+| Error base | `<Name>Error.ts` | `AppError.ts` |
+| Error específico | `<Name>Error.ts` | `NotFoundError.ts`, `ValidationError.ts`, `ConflictError.ts` |
+
+Los errores transversales viven en `shared/errors/`. Errores específicos de feature en `features/<name>/domain/errors/`.
+Para guía completa ver `reference/errors.md`.
+
+---
+
+## API
+
+| Archivo | Formato | Ejemplo |
+|---------|---------|---------|
+| Esquemas de validación | `<name>.schema.ts` | `createUser.schema.ts` |
+| Routes | `<Name>.routes.ts` | `User.routes.ts` |
+| Controller | `<Name>.controller.ts` | `User.controller.ts` |
+| DTOs request | `<Name>.req.ts` | `CreateUser.req.ts` |
+| DTOs response | `<Name>.res.ts` | `User.res.ts` |
+
+REST prefiere `/api/v1/resources`. GraphQL schema en `adapters/in/graphql/` dentro del feature.
+
+---
+
 ## Infra Layer
 
 | Directorio | Archivos | Ejemplo |

package/skills/forge/reference/principles.md

@@ -27,3 +27,9 @@
 11. **El sistema es un grafo arquitectónico vivo** — Todo componente es un nodo tipado (platform, feature, shared, infra, domain, adapter, application). Toda relación es un edge validado. Las violaciones son edges prohibidos. El grafo es la fuente de verdad del sistema y se regenera en cada auditoría. Riesgo, salud y ownership se derivan del grafo, no de opiniones.
 
 12. **Cuatro dominios arquitectónicos con ownership estricto** — Todo backend se modela en cuatro capas: Platform (backbone técnico), Features (negocio), Shared (código puro reutilizable) e Infrastructure (implementaciones concretas). Cada componente tiene un único propietario arquitectónico. Los huérfanos, duplicados y componentes mal ubicados se detectan automáticamente. Las reglas de dependencia entre capas son obligatorias: `feature → platform → infra`, `feature → shared`, `adapter → infra`. Cualquier violación es una degradación arquitectónica.
+
+13. **Errores tipados en el dominio** — Los errores de dominio son clases explícitas, no `throw Error()` genéricos. Viven en `shared/errors/` si son transversales o en `domain/` del feature si son específicos. Los adapters HTTP traducen errores de dominio a códigos HTTP. La capa de aplicación nunca sabe qué códigos HTTP existen. Ver `reference/errors.md`.
+
+14. **Tests como ciudadanos de primera clase** — El dominio y los casos de uso se testean con unit tests sin infraestructura (mocks en las interfaces). Los adapters se testean con integration tests contra infraestructura real. La pirámide de tests es 70% unit / 20% integration / 10% e2e. Sin coverage de use cases no hay aprobación arquitectónica. Ver `reference/testing-patterns.md`.
+
+15. **Seguridad como infraestructura transversal** — AuthN, AuthZ, rate limiting y validación son infraestructura, no dominio. Se implementan en `platform/security/` y `platform/http/` como middlewares. El dominio recibe `userId` o `role` si un caso de uso lo necesita, pero nunca implementa lógica de autenticación. Ver `reference/security-patterns.md` y `reference/api-design.md`.

package/skills/forge/reference/reforge.md

@@ -2,6 +2,8 @@
 
 Refactoriza la arquitectura de un feature o de un componente de platform/shared/infra.
 
+También renombra archivos para cumplir con las convenciones de naming (`reference/patterns.md`).
+
 ## Cuándo usarlo
 
 - Un feature tiene violaciones arquitectónicas
@@ -9,20 +11,82 @@ Refactoriza la arquitectura de un feature o de un componente de platform/shared/
 - Un componente de platform necesita refinarse
 - Un componente de shared necesita rediseñarse
 - El grafo arquitectónico muestra violaciones que requieren intervención
+- Un archivo no cumple con las convenciones de naming (`patterns.md`)
+- Quieres renombrar un archivo y actualizar todos sus imports automáticamente
+
+## Caso A — `reforge <filename>` (solo renombrar)
+
+Renombra un único archivo según las convenciones de `reference/patterns.md` y actualiza todos los imports que lo referencian.
+
+**No ejecuta backup** (el rename no modifica lógica de negocio).
+
+### Flujo
+
+1. Identificar la ruta del archivo (relativa a la raíz del proyecto)
+2. Ejecutar `node .opencode/skills/forge/scripts/rename.mjs --detect --file <path>` para detectar violación
+3. Si el archivo ya cumple naming, informar y terminar
+4. Mostrar preview del cambio al usuario
+5. Ejecutar `node .opencode/skills/forge/scripts/rename.mjs --file <path>` que:
+   - Renombra físicamente el archivo
+   - Escanea todos los `.ts`/`.js` del proyecto
+   - Actualiza imports que referencian el path antiguo (relativos y absolutos)
+6. Verificar con `forge quench`
+7. Reportar resultado: archivo renombrado + cantidad de imports actualizados
+
+### Ejemplo
+
+```
+$ forge reforge src/features/users/domain/userEntity.ts
+  Renombrar:
+    src/features/users/domain/userEntity.ts
+    → src/features/users/domain/User.entity.ts
+    Regla: feature/users/domain: <Name>.entity.ts
 
-## Flujo básico
+  ✓ Archivo renombrado: userEntity.ts → User.entity.ts
+  ✓ Imports actualizados en 3 archivo(s):
+       src/features/users/application/use-cases/CreateUser.uc.ts
+       src/features/users/application/mappers/User.mapper.ts
+       src/features/users/adapters/in/http/User.controller.ts
+```
 
+## Caso B — `reforge` (completo con auto-fix naming)
+
+### Flujo
+
+0. **Backup**: Ejecutar `forge rollback backup <target>` antes de cualquier cambio
 1. Ejecutar `forge inspect` para obtener estado actual
 2. Identificar violaciones en el grafo arquitectónico
 3. Identificar ownership problemático (huérfanos, duplicados, mal ubicados)
-4. Decidir las acciones correctivas en orden:
+4. **Detectar naming violations**: Ejecutar `node .opencode/skills/forge/scripts/rename.mjs --detect --json`
+5. Si hay naming violations, preguntar al usuario: "¿Corregir naming conventions automáticamente?"
+   - Si acepta, ejecutar `node .opencode/skills/forge/scripts/rename.mjs --all`
+6. Decidir las acciones correctivas en orden:
    - Violaciones CRITICAL primero (R1, R2, R5, R6)
    - Violaciones ERROR después (R3, R4, R8, R9)
    - Ownership problemático
+   - Naming violations (si no se corrigieron en paso 5)
    - Warnings
-5. Ejecutar cambios en el feature o componente
-6. Ejecutar `forge quench` para verificar
-7. Actualizar `ARCHITECTURE.md`
+7. Ejecutar cambios en el feature o componente
+8. Verificar con `forge rollback verify` — si el score empeora, restaurar
+9. Ejecutar `forge quench` para verificar
+10. Actualizar `ARCHITECTURE.md`
+
+### Flags
+
+| Flag | Efecto |
+|------|--------|
+| `--dry-run` | Preview de naming violations sin hacer cambios |
+| `--fix-naming` | Corregir naming violations sin preguntar |
+| `--skip-naming` | Omitir detección y corrección de naming |
+
+## Rollback
+
+Si la refactorización empeora el score arquitectónico, restaurar automáticamente:
+
+```bash
+forge rollback list
+forge rollback restore <id>
+```
 
 ## Refactorización multi-capa
 

package/skills/forge/reference/relocate.md

@@ -15,6 +15,7 @@ También puede migrar componentes legacy a los layers Platform, Shared o Infrast
 
 ## Flujo
 
+0. **Backup automático**: Ejecutar `forge rollback backup <target>` antes de cualquier cambio
 1. Identificar el componente a migrar
 2. Clasificarlo en el layer correcto:
    - Configuración, servidor, logger, DI → **Platform**
@@ -25,8 +26,20 @@ También puede migrar componentes legacy a los layers Platform, Shared o Infrast
 4. Migrar archivos manteniendo la lógica intacta
 5. Actualizar imports
 6. Eliminar estructura legacy
-7. Ejecutar `forge quench` para verificar
-8. Actualizar `ARCHITECTURE.md`
+7. Verificar con `forge rollback verify` — si el score empeora, restaurar con `forge rollback restore <backup-id>`
+8. Ejecutar `forge quench` para verificar
+9. Actualizar `ARCHITECTURE.md`
+
+## Rollback
+
+Si la migración introduce violaciones (R1-R9), el agente DEBE restaurar automáticamente:
+
+```bash
+forge rollback list          # ver backups disponibles
+forge rollback restore <id>  # restaurar
+```
+
+El backup se almacena en `.forge/backups/<target>--<timestamp>/` y preserva la estructura original completa.
 
 ## Estrategias por layer
 

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

@@ -0,0 +1,87 @@
+# Security Patterns — Autenticación, autorización, rate limiting, validación
+
+## Principios arquitectónicos
+
+- La seguridad es **infraestructura transversal**, no dominio de negocio.
+- AuthN/AuthZ se implementan en `platform/security/` y se inyectan como middleware o decoradores.
+- El dominio nunca contiene lógica de autenticación. Solo recibe `userId` si el caso de uso lo necesita.
+- Validación de entrada en el controller o middleware de validación, nunca en la entidad de dominio.
+
+## Capas de seguridad
+
+| Capa | Responsabilidad | Ubicación |
+|------|----------------|-----------|
+| Transport | TLS, HSTS, CORS, CSRF | platform/http/ |
+| AuthN | Verificar quién es el usuario | platform/security/ |
+| AuthZ | Verificar qué puede hacer | platform/security/ + features |
+| Input validation | Sanitizar entrada | platform/http/ middleware |
+| Rate limiting | Proteger contra abuso | platform/http/ middleware |
+| Audit logging | Registrar acciones sensibles | platform/observability/ |
+
+## AuthN: Estrategias
+
+| Estrategia | Cuándo usarla |
+|------------|---------------|
+| JWT (access + refresh) | SPAs, mobile, APIs stateless |
+| Session + cookie | SSR tradicional, apps server-side |
+| API Key | Service-to-service, CLIs |
+| OAuth2 / OIDC | Delegación a terceros (Google, GitHub) |
+
+```ts
+// platform/security/Auth.middleware.ts
+export class AuthMiddleware {
+  async authenticate(req: Request, res: Response, next: NextFunction) {
+    const token = req.headers.authorization?.replace("Bearer ", "");
+    const payload = await this.jwtService.verify(token);
+    req.user = payload;
+    next();
+  }
+}
+```
+
+## AuthZ: RBAC y Policy-based
+
+```ts
+// features/users/application/use-cases/DeleteUser.uc.ts
+export class DeleteUserUseCase {
+  constructor(
+    private readonly userRepo: IUserRepository,
+    private readonly authz: IAuthorizationService,
+  ) {}
+
+  async execute(actorId: string, targetId: string): Promise<void> {
+    await this.authz.require(actorId, "user:delete", { targetId });
+    // … lógica del caso de uso
+  }
+}
+```
+
+## Rate limiting
+
+```ts
+// platform/http/RateLimiter.middleware.ts
+// Por IP, por ruta, por rol. Almacenamiento en Redis.
+// Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
+```
+
+## Validación
+
+```ts
+// shared/contracts/schemas.ts (zod)
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  role: z.enum(["admin", "user"]).default("user"),
+});
+```
+
+## Buenas prácticas
+
+- Jamás almacenar passwords en texto plano. Usar bcrypt/argon2.
+- JWT con corta expiración (15min access, 7d refresh)
+- Refresh token rotation al usarse
+- Rate limit por endpoint según criticidad: login (5/min), register (3/min), GET (100/min)
+- CORS whitelist de origins conocidos, nunca `*`
+- Helmet para headers de seguridad (CSP, X-Frame-Options, etc.)
+- Secretos en variables de entorno, nunca en código
+- Auditoría de acciones sensibles: login, delete, role change, export

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

@@ -0,0 +1,69 @@
+# Testing Patterns — Tests en arquitectura hexagonal
+
+## Pirámide de tests
+
+```
+     ╱╲
+    ╱ E2E ╲          (2-5%) — happy paths críticos
+   ╱────────╲
+  ╱ Integration ╲    (15-25%) — adapters, rutas, repositorios
+ ╱────────────────╲
+╱   Unit Tests     ╲  (70-80%) — use cases, entidades, mappers
+```
+
+## Qué testear en cada capa
+
+| Capa | Tipo | Qué testear |
+|------|------|-------------|
+| `domain/entity` | Unit | Reglas de negocio, invariantes, validaciones |
+| `application/use-cases` | Unit | Flujo completo con mocks de repositorios |
+| `application/mappers` | Unit | Mapeo dominio ↔ DTO |
+| `adapters/in/http` | Integration | HTTP requests, status codes, payloads |
+| `adapters/out/persistence` | Integration | Queries reales (test DB) |
+| `shared/errors` | Unit | Mensajes, códigos, instanceof |
+| `platform/` | Integration | Middleware, server, logger, cache |
+
+## Unit: Use case con mocks
+
+```ts
+// test/features/users/CreateUser.uc.test.ts
+import { CreateUserUseCase } from "@/features/users/application/use-cases/CreateUser.uc.js";
+
+const mockRepo = {
+  findByEmail: vi.fn(),
+  save: vi.fn(),
+};
+
+const uc = new CreateUserUseCase(mockRepo);
+
+it("creates a user successfully", async () => {
+  mockRepo.findByEmail.mockResolvedValue(null);
+  mockRepo.save.mockResolvedValue({ id: "1", email: "test@test.com" });
+
+  const result = await uc.execute({ email: "test@test.com", name: "Test" });
+  expect(result).toHaveProperty("id");
+});
+```
+
+## Integration: Controller
+
+```ts
+// test/features/users/User.controller.test.ts
+import supertest from "supertest";
+
+it("POST /users returns 201", async () => {
+  const res = await request(app)
+    .post("/users")
+    .send({ email: "test@test.com", name: "Test" });
+  expect(res.status).toBe(201);
+});
+```
+
+## Buenas prácticas
+
+- No testear frameworks, solo tu código
+- Mocks en el puerto (interfaz), no en la implementación
+- Tests de integración contra BD real o testcontainers
+- Nombrar tests como unidades de comportamiento, no métodos
+- Coverage mínimo sugerido: 85% use cases, 75% adapters
+- Los mappers se testean con fixtures: entrada conocida → salida esperada