@ronaldjdevfs/forge 1.0.1 → 1.1.0

package/skills/forge/profiles/nestjs-mongodb.md

@@ -0,0 +1,92 @@
+# Profile: NestJS + MongoDB + Mongoose
+
+## Metadata
+
+```yaml
+framework: NestJS
+runtime: Node 20+
+database: MongoDB
+orm: Mongoose
+di_strategy: framework (NestJS DI)
+architecture: hexagonal-feature
+```
+
+## DI Strategy
+
+NestJS DI nativo con `@Injectable()` y módulos. Conexión Mongoose via `MongooseModule.forRoot()`.
+
+```typescript
+// app.module.ts
+@Module({
+  imports: [
+    MongooseModule.forRoot(process.env.MONGO_URI),
+    CreditModule,
+  ],
+})
+export class AppModule {}
+```
+
+## Project Structure
+
+```
+├── src/
+│   ├── features/
+│   │   └── credit/
+│   │       ├── domain/
+│   │       │   ├── Credit.entity.ts        # Plain domain object
+│   │       │   └── ICredit.repository.ts
+│   │       ├── application/
+│   │       │   └── use-cases/
+│   │       │       └── AddCredit.uc.ts
+│   │       └── adapters/
+│   │           ├── in/http/
+│   │           │   ├── Credit.controller.ts
+│   │           │   └── Credit.module.ts
+│   │           └── out/persistence/
+│   │               ├── Credit.schema.ts     # Mongoose schema
+│   │               └── Credit.repository.ts
+│   ├── shared/
+│   ├── app.module.ts
+│   └── main.ts
+```
+
+## Persistence (Mongoose)
+
+```typescript
+// adapters/out/persistence/Credit.schema.ts
+import { Prop, Schema, SchemaFactory } from "@nestjs/mongoose";
+
+@Schema({ timestamps: true })
+export class CreditDocument {
+  @Prop({ required: true }) amount: number;
+  @Prop({ required: true }) userId: string;
+}
+
+export const CreditSchema = SchemaFactory.createForClass(CreditDocument);
+```
+
+```typescript
+// adapters/out/persistence/credit.module.ts
+@Module({
+  imports: [MongooseModule.forFeature([{ name: "Credit", schema: CreditSchema }])],
+  providers: [{ provide: ICreditRepository, useClass: CreditRepository }],
+  exports: [ICreditRepository],
+})
+export class CreditPersistenceModule {}
+```
+
+## Testing Strategy
+
+```typescript
+// Test con MongoMemoryServer
+const module = await Test.createTestingModule({
+  imports: [
+    MongooseModule.forRoot(MongoMemoryServer.create().then(m => m.getUri())),
+    CreditModule,
+  ],
+}).compile();
+```
+
+## Naming Conventions
+
+Schemas en PascalCase, colecciones en snake_case (Mongoose usa plural automático).

package/skills/forge/profiles/nestjs-postgres.md

@@ -0,0 +1,98 @@
+# Profile: NestJS + PostgreSQL
+
+## Metadata
+
+```yaml
+framework: NestJS
+runtime: Node 20+
+database: PostgreSQL
+orm: TypeORM / native
+di_strategy: framework (NestJS DI)
+architecture: hexagonal-feature
+```
+
+## DI Strategy
+
+NestJS DI nativo. Módulos con `@Module()`, `@Injectable()` para servicios y repositorios. Providers registrados en cada módulo de feature.
+
+```typescript
+// features/credit/credit.module.ts
+@Module({
+  imports: [TypeOrmModule.forFeature([CreditEntity])],
+  controllers: [CreditController],
+  providers: [
+    { provide: ICreditRepository, useClass: CreditRepository },
+    AddCredit,
+  ],
+})
+export class CreditModule {}
+```
+
+## Project Structure
+
+```
+├── src/
+│   ├── features/
+│   │   └── credit/
+│   │       ├── domain/
+│   │       │   ├── Credit.entity.ts       # TypeORM entity (dominio anémico aceptable)
+│   │       │   └── ICredit.repository.ts
+│   │       ├── application/
+│   │       │   └── use-cases/
+│   │       │       └── AddCredit.uc.ts
+│   │       └── adapters/
+│   │           ├── in/http/
+│   │           │   ├── Credit.controller.ts
+│   │           │   └── Credit.module.ts
+│   │           └── out/persistence/
+│   │               └── Credit.repository.ts
+│   ├── shared/
+│   ├── app.module.ts
+│   └── main.ts
+```
+
+## Persistence (TypeORM)
+
+```typescript
+// domain/Credit.entity.ts
+@Entity()
+export class Credit {
+  @PrimaryGeneratedColumn("uuid") id: string;
+  @Column() amount: number;
+  @Column() userId: string;
+  @CreateDateColumn() createdAt: Date;
+}
+```
+
+```typescript
+// adapters/out/persistence/Credit.repository.ts
+@Injectable()
+export class CreditRepository implements ICreditRepository {
+  constructor(@InjectRepository(Credit) private readonly repo: Repository<Credit>) {}
+
+  async create(data: CreditInput): Promise<Credit> {
+    const entity = this.repo.create(data);
+    return this.repo.save(entity);
+  }
+}
+```
+
+## Testing Strategy
+
+```typescript
+// Test unitario sin NestJS
+const mockRepo = { create: jest.fn() };
+const uc = new AddCredit(mockRepo);
+
+// Test de integración con Test.createTestingModule
+const module = await Test.createTestingModule({
+  providers: [
+    AddCredit,
+    { provide: ICreditRepository, useClass: MockCreditRepo },
+  ],
+}).compile();
+```
+
+## Naming Conventions
+
+Mismas que `nestjs-prisma`. Entidades TypeORM en PascalCase, tablas en snake_case con `@Entity("credit")`.

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

@@ -0,0 +1,62 @@
+# API Design — Diseño de APIs REST/GraphQL
+
+## Principios arquitectónicos
+
+- Las rutas/endpoints pertenecen a `adapters/in/http/`, nunca al dominio.
+- El controller es la capa más delgada posible: parsea, delega, responde.
+- La validación de entrada ocurre en el controller o middleware, no en domain/.
+- El contrato API (OpenAPI/Swagger) se genera desde tipos compartidos.
+
+## REST
+
+### Convenciones
+
+| Verbo | Ruta | Controller responde | Use case retorna |
+|-------|------|-------------------|------------------|
+| GET | `/resources` | 200 + array | `Resource[]` |
+| GET | `/resources/:id` | 200 + object / 404 | `Resource \| null` |
+| POST | `/resources` | 201 + object | `Resource` |
+| PUT | `/resources/:id` | 200 + object | `Resource` |
+| PATCH | `/resources/:id` | 200 + object | `Resource` |
+| DELETE | `/resources/:id` | 204 / 404 | `void` |
+
+### Paginación
+
+```ts
+// shared/contracts/IPaginatedResponse.ts
+export interface IPaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  };
+}
+```
+
+```ts
+// Formato query: GET /users?page=1&limit=20&sort=name:asc&filter=status:active
+```
+
+### Versionado
+
+- Preferir versionado por encabezado (`Accept: application/vnd.api+json;version=2`)
+- Si es por URL: `/api/v1/resources` (carpeta física `adapters/in/http/v1/`)
+- Deprecar con encabezado `Sunset: Sat, 01 Jan 2027 00:00:00 GMT`
+
+## GraphQL
+
+- Schema en `adapters/in/graphql/` dentro del feature
+- Resolvers = use cases wrapped; nunca contienen lógica de negocio
+- DataLoader para N+1 en resolvers de listas
+- Scalar types custom para IDs, fechas, emails
+
+## Buenas prácticas
+
+- OpenAPI 3.1 como fuente de verdad para REST
+- Validación con zod (compartir schemas entre controller y validación)
+- Rate limiting por ruta/rol en middleware de platform/http/
+- Errores normalizados: `{ error: { code, message, details? } }`
+- Idempotencia en POST con `Idempotency-Key` header
+- HATEOAS opcional, solo para APIs hipermedia

package/skills/forge/reference/assay.md

@@ -0,0 +1,82 @@
+# Assay
+
+Genera un **ensayo arquitectónico multi-persona** que evalúa el estado actual de la arquitectura desde 5 perspectivas expertas.
+
+## Cuándo usarlo
+
+- Después de `forge inspect` para obtener interpretación cualitativa de los resultados
+- Para entender el impacto de las violaciones desde ángulos complementarios
+- Para priorizar acciones de refactor con criterio multi-disciplinario
+- Como herramienta de discusión en revisiones arquitectónicas de equipo
+
+## Las 5 Personas
+
+| Persona | Rol | Enfoque |
+|---------|-----|---------|
+| **Jeff Bezos** | Arquitecto de Escalabilidad y Autonomía | Acoplamiento entre features, contratos de API, autonomía de equipos, ciclos de dependencias |
+| **Martin Fowler** | Refinador de Patrones y Deuda Técnica | Dirección de dependencias, code smells, naming, refactoring evolutivo |
+| **El Hacker** | Pragmático y Simplificador | Over-engineering, complejidad innecesaria, abstracciones sin valor, costo real de mantenimiento |
+| **Alex** | Product Manager Técnico | Velocidad de entrega, ROI de la deuda técnica, impacto en roadmap, time-to-market |
+| **Dra. Carter** | Arquitecta Senior — Deuda Técnica y Gobernanza | Sostenibilidad a 3-5 años, consistencia entre equipos, gobernanza y ownership |
+
+## Uso
+
+```bash
+# Ensayo completo con todas las personas
+node .opencode/skills/forge/scripts/assay.mjs
+
+# Solo la opinión de una persona
+node .opencode/skills/forge/scripts/assay.mjs --persona=bezos
+node .opencode/skills/forge/scripts/assay.mjs --persona=fowler
+node .opencode/skills/forge/scripts/assay.mjs --persona=hacker
+node .opencode/skills/forge/scripts/assay.mjs --persona=pm
+node .opencode/skills/forge/scripts/assay.mjs --persona=senior
+
+# Salida JSON (para consumo por herramientas)
+node .opencode/skills/forge/scripts/assay.mjs --json
+
+# Persistir ensayo en .forge/assay/
+node .opencode/skills/forge/scripts/assay.mjs --save
+
+# Ver historial de ensayos
+node .opencode/skills/forge/scripts/assay.mjs history
+
+# Leer un ensayo previo
+node .opencode/skills/forge/scripts/assay.mjs read assay-2026-06-25T00-00-00.md
+```
+
+## Formato de salida
+
+```
+═══ Forge Assay — Ensayo Arquitectónico ═══
+Score: 72/140 (51%) — D
+Violaciones: 8
+Personas: Jeff Bezos, Martin Fowler, El Hacker, Alex, Dra. Carter
+Fecha: 2026-06-25
+
+──── Jeff Bezos — Arquitecto de Escalabilidad y Autonomía ────
+...
+
+──── Martin Fowler — Refinador de Patrones y Deuda Técnica ────
+...
+
+──── El Hacker — Pragmático y Simplificador ────
+...
+
+──── Alex — Product Manager Técnico ────
+...
+
+──── Dra. Carter — Arquitecta Senior ────
+...
+```
+
+## Integración con inspect
+
+El ensayo se basa en los datos del último `forge inspect`. Si no hay auditoría previa, el ensayo se genera igual pero con menos datos contextuales.
+
+Se recomienda:
+1. `forge inspect` → obtener score, violaciones, grafo
+2. `forge assay` → interpretar los resultados desde las 5 perspectivas
+3. Priorizar acciones basado en las recomendaciones
+4. Refactorizar con `reforge`, `temper`, o `smelt`
+5. Repetir el ciclo

package/skills/forge/reference/cast.md

@@ -17,11 +17,84 @@ Antes de crear un feature, verificar la existencia de los layers arquitectónico
 
 Si alguno no existe, ejecutar `bootstrapPlatform()` automáticamente para crearlos.
 
+## ⚠️ Pre-Cast Discovery — 3 Gates Obligatorios
+
+**NO escribir código hasta pasar los 3 gates de aprobación.** Cast solía crear scaffolding directamente del nombre del feature. Esto producía features genéricos que requerían refactor posterior. Ahora todo `cast` requiere descubrimiento direccional multi-ronda.
+
+Usar las **señales de `forge-signals.mjs`** para contextualizar el descubrimiento:
+- Si hay features existentes, revisar sus entidades y casos de uso para mantener coherencia.
+- Si el perfil está detectado, usarlo para preguntas específicas (ej: "Prisma detectado → schema primero").
+- Si hay archivos modificados en git, considerarlos como contexto del nuevo feature.
+
+### Gate 1: Brief del Feature
+
+Hacer **al menos 1 ronda de preguntas** usando la herramienta `question`. No inferir todas las respuestas del prompt inicial. Preguntar:
+
+**Ronda 1 (obligatoria — 2-3 preguntas):**
+- ¿Cuál es la entidad principal del dominio? (ej: "Factura", "Suscripción", "Producto")
+- ¿Qué operaciones CRUD necesita? ¿Todas o solo un subconjunto?
+- ¿Este feature se relaciona con algún feature existente? ¿Cuál y cómo?
+
+**Ronda 2 (si aplica — preguntar solo si la Ronda 1 dejó dudas):**
+- ¿Necesita eventos de dominio o integración con scheduler?
+- ¿Expone API REST? ¿También GraphQL o gRPC?
+- ¿Requiere cache? ¿Lectura > escritura o viceversa?
+
+**No preguntes sobre detalles de implementación (nombre de columnas, puertos, etc.) en esta fase.** Eso se resuelve en el scaffold. El brief es sobre qué hace el feature, no cómo se implementa.
+
+**Salida:** Brief del feature confirmado por el usuario.
+
+### Gate 2: Confirmar Estructura
+
+Tras el brief, presentar la estructura propuesta al usuario para confirmación:
+
+```
+src/features/<name>/
+├── domain/
+│   ├── <Name>.entity.ts
+│   └── I<Name>.repository.ts
+├── application/
+│   ├── use-cases/
+│   │   ├── Create<Name>.uc.ts
+│   │   ├── Get<Name>.uc.ts
+│   │   └── List<Name>.uc.ts     (los que apliquen según brief)
+│   └── mappers/
+│       └── <Name>.mapper.ts
+└── adapters/
+    ├── in/http/
+    │   ├── <Name>.controller.ts
+    │   └── <name>.routes.ts
+    └── out/persistence/
+        ├── <Name>.schema.ts
+        └── <Name>.repository.ts
+```
+
+Preguntar: "¿Esta estructura cubre el dominio? ¿Falta algo, sobra algo?"
+
+**No avanzar sin confirmación explícita del usuario.**
+
+### Gate 3: Confirmar Wiring
+
+Antes de escribir código, confirmar las decisiones de integración:
+
+- **Repository**: "Inyecto `I<Name>Repository` vía interfaz. Implementación concreta en `adapters/out/persistence/`. ¿OK?"
+- **Controller**: "El controller parsea, llama al use case, responde. Sin lógica de negocio. ¿OK?"
+- **DI**: Según perfil: "Uso `@injectable()` + `@inject(Token)` con tsyringe" o "DI manual en bootstrap". ¿OK?
+- **Routing**: "Registro las rutas en el enrutador principal de HTTP. ¿OK?"
+
+Preguntar: "¿Confirmas este wiring antes de generar el feature?"
+
+**Sin Gate 3 confirmado, no se escribe ni un archivo.**
+
+---
+
 ## Flujo
 
 1. Verificar que `src/platform/`, `src/shared/`, `src/infra/` existan (crearlos si no)
-2. Determinar el nombre del feature (formato: kebab-case)
-3. Crear estructura de directorios:
+2. **Ejecutar Pre-Cast Discovery** (3 gates obligatorios)
+3. Determinar el nombre del feature (formato: kebab-case) — ya debería estar claro del brief
+4. Opcional: persistir brief en `.forge/features/<name>/brief.md` para futuras referencias
+5. Crear estructura de directorios:
    ```
    src/features/<name>/
    ├── domain/
@@ -32,18 +105,18 @@ Si alguno no existe, ejecutar `bootstrapPlatform()` automáticamente para crearl
        ├── in/http/
        └── out/persistence/
    ```
-4. Crear archivos del feature en este orden (ver `templates/feature/`):
+6. Crear archivos del feature en este orden (ver `templates/feature/`):
    - `<Name>.entity.ts` — interfaz de dominio
    - `I<Name>Repository.ts` — puerto de repositorio
    - `<Name>.mapper.ts` — mapper dominio ↔ persistencia
    - `<Name>Schema.ts` — schema de BD (según perfil)
    - `<Name>Repository.ts` — implementación del repositorio
-   - Use cases (`Create.ts`, `Get.ts`, `List.ts`, `Update.ts`, `Delete.ts`)
+   - Use cases (`Create.ts`, `Get.ts`, `List.ts`, `Update.ts`, `Delete.ts` — según brief)
    - `<Name>Controller.ts` — controlador HTTP
    - `<name>.routes.ts` — rutas HTTP
-5. Registrar rutas en el enrutador principal
-6. Ejecutar `forge quench` para verificar el feature
-7. Actualizar `ARCHITECTURE.md`
+7. Registrar rutas en el enrutador principal
+8. Ejecutar `forge quench` para verificar el feature
+9. Actualizar `ARCHITECTURE.md` + estado persistente
 
 ## Convenciones
 
@@ -75,3 +148,4 @@ Usar el perfil detectado para determinar:
 - `forge quench` — verificar que no hay violaciones
 - `forge inspect` — confirmar puntuación
 - `ARCHITECTURE.md` actualizado automáticamente
+- `.forge/state.json` actualizado automáticamente

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

@@ -0,0 +1,86 @@
+# Data Patterns — Repository, Unit of Work, CQRS, Event Sourcing
+
+## Repository Pattern
+
+### Reglas
+
+- La interfaz del repositorio está en `domain/` del feature.
+- La implementación está en `adapters/out/persistence/`.
+- El use case recibe la interfaz por constructor y nunca sabe qué BD hay detrás.
+
+```ts
+// domain/IUser.repository.ts
+export interface IUserRepository {
+  findById(id: string): Promise<UserEntity | null>;
+  findByEmail(email: string): Promise<UserEntity | null>;
+  save(user: UserEntity): Promise<UserEntity>;
+  delete(id: string): Promise<void>;
+}
+```
+
+```ts
+// adapters/out/persistence/PostgresUser.repository.ts
+export class PostgresUserRepository implements IUserRepository {
+  constructor(private readonly db: PrismaClient) {}
+  async findById(id: string) { … }
+}
+```
+
+## Unit of Work
+
+Para operaciones que requieren transacción entre múltiples repositorios.
+
+```ts
+// domain/IUnitOfWork.ts
+export interface IUnitOfWork {
+  withTransaction<T>(fn: (uow: { userRepo: IUserRepository; accountRepo: IAccountRepository }) => Promise<T>): Promise<T>;
+}
+```
+
+## CQRS
+
+Separar commands (escritura) de queries (lectura) solo cuando el modelo de lectura difiere significativamente del de escritura.
+
+| Aspecto | Commands | Queries |
+|---------|----------|---------|
+| Feature dir | `application/use-cases/` | `application/queries/` |
+| Retorno | `void` o ID | DTOs planos |
+| Cache | No | Sí |
+| Repositorio | Domain interface | Query interface separada |
+
+## Event Sourcing
+
+Para features que requieren auditoría completa o reconstrucción de estado histórico.
+
+- Eventos en `domain/events/` dentro del feature
+- Aggregate root: solo persiste eventos, nunca estado actual
+- Proyecciones: tablas/materialized views que reflejan el estado actual
+- Snapshotting cada N eventos para performance
+
+### Estructura
+
+```
+features/<name>/
+  domain/
+    events/
+      UserCreated.event.ts
+      UserEmailChanged.event.ts
+      UserDeleted.event.ts
+```
+
+## Cuándo usar cada patrón
+
+| Patrón | Cuándo usarlo |
+|--------|---------------|
+| Repository | Siempre. Es el estándar para acceso a datos. |
+| Unit of Work | Cuando una operación modifica 2+ agregados en una transacción. |
+| CQRS | Cuando las queries de lectura son significativamente distintas a los comandos de escritura. |
+| Event Sourcing | Solo cuando necesitas auditoría forense o reconstrucción de estado histórico. |
+
+## Buenas prácticas
+
+- Repositorios devuelven entidades de dominio, no schemas de BD
+- Siempre hay un mapper entre schema de BD y entidad de dominio
+- Transacciones en el Unit of Work, no en el use case ni en el repositorio individual
+- CQRS no significa event sourcing; son patrones independientes
+- Event sourcing sin snapshotting es inviable a escala

package/skills/forge/reference/di-strategies.md

@@ -0,0 +1,50 @@
+# DI Strategies — Inyección de dependencias
+
+## Principios
+
+- Constructor injection sobre service locators o decoradores mágicos.
+- El dominio nunca importa el contenedor. Solo application y adapters.
+- Interfaces en domain/; implementaciones en adapters/out/ o platform/.
+
+## Estrategias según tamaño del proyecto
+
+| Tamaño | Estrategia | Cuándo usarla |
+|--------|-----------|---------------|
+| Pequeño (< 10 features) | DI Manual | Wires explícitos en composición root (src/app.ts) |
+| Mediano (10-30 features) | Contenedor ligero | awilix, tsyringe, o el DI del framework |
+| Grande (> 30 features) | Contenedor con módulos | NestJS modular, inversify con módulos lazy |
+
+## DI Manual
+
+```ts
+// src/app.ts — Composition Root
+import { PostgresUserRepository } from "./features/users/adapters/out/persistence/PostgresUser.repository.js";
+import { CreateUserUseCase } from "./features/users/application/use-cases/CreateUser.uc.js";
+import { UserController } from "./features/users/adapters/in/http/User.controller.js";
+
+const userRepo = new PostgresUserRepository(db);
+const createUserUc = new CreateUserUseCase(userRepo);
+const userController = new UserController(createUserUc);
+
+router.post("/users", (req, res) => userController.create(req, res));
+```
+
+## Contenedor (tsyringe)
+
+```ts
+// di/Container.ts
+import { container } from "tsyringe";
+import { IUserRepository } from "@/features/users/domain/IUser.repository.js";
+import { PostgresUserRepository } from "@/features/users/adapters/out/persistence/PostgresUser.repository.js";
+
+container.registerSingleton<IUserRepository>("IUserRepository", PostgresUserRepository);
+```
+
+## Buenas prácticas
+
+- Composition Root único y lo más cercano al entrypoint posible
+- Solo el Composition Root conoce todas las implementaciones concretas
+- Preferir interfaces sobre clases abstractas en domain/
+- Evitar `container.resolve()` fuera del Composition Root
+- Usar tokens (strings o símbolos) para identificar dependencias
+- Testear use cases con mocks manuales sin necesidad del contenedor

package/skills/forge/reference/errors.md

@@ -0,0 +1,65 @@
+# Errors — Manejo de errores en arquitectura hexagonal
+
+## Principios
+
+- Los errores de dominio pertenecen al **dominio**, no al framework ni a HTTP.
+- Los casos de uso lanzan errores de dominio; los adapters HTTP los traducen a respuestas HTTP.
+- Nunca lanzar `throw new Error("...")` desde domain/application. Usar errores tipados.
+
+## Estructura
+
+```
+src/shared/errors/
+  ├── AppError.ts          → Clase base abstracta (opcional)
+  ├── NotFoundError.ts     → 404
+  ├── ValidationError.ts   → 400 / 422
+  ├── UnauthorizedError.ts → 401
+  ├── ForbiddenError.ts    → 403
+  ├── ConflictError.ts     → 409
+  └── DomainError.ts       → 500 genérico de dominio
+```
+
+## Ejemplo
+
+```ts
+// shared/errors/NotFoundError.ts
+export class NotFoundError extends Error {
+  constructor(public readonly entity: string, public readonly id: string) {
+    super(`${entity} with id ${id} not found`);
+    this.name = "NotFoundError";
+  }
+}
+```
+
+```ts
+// features/users/domain/IUser.repository.ts
+import { NotFoundError } from "@/shared/errors/NotFoundError.js";
+
+export interface IUserRepository {
+  findById(id: string): Promise<UserEntity | null>;
+  // el use case decide si lanza NotFoundError
+}
+```
+
+```ts
+// features/users/adapters/in/http/User.controller.ts
+import { NotFoundError } from "@/shared/errors/NotFoundError.js";
+
+async getUser(req, res, next) {
+  try {
+    const user = await this.getUserUc.execute(req.params.id);
+    res.json(user);
+  } catch (err) {
+    if (err instanceof NotFoundError) return res.status(404).json({ error: err.message });
+    next(err);
+  }
+}
+```
+
+## Buenas prácticas
+
+- Errores de dominio en `domain/` (o shared/errors si son transversales)
+- `Result<T, E>` pattern para casos donde el error es parte del flujo esperado
+- Error handler centralizado en platform/http/ para errores no capturados
+- Loggear errores en el adapter, no en el dominio
+- Códigos de error consistentes: `DOMAIN_ENTITY_NOT_FOUND`, `VALIDATION_INVALID_EMAIL`