@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/monorepo/cliter/harness-rules/module-graph.md

@@ -0,0 +1,89 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-29
+keywords:
+  - leaf module
+  - módulo hoja
+  - circular dependency
+  - dependencia circular
+  - authentication module
+  - aurora decorators
+  - auth decorator
+  - guards barrel
+  - module imports cycle
+  - Auth is not a function
+  - schedule module placement
+paths:
+  - backend/src/@aurora/modules/authentication/*.module.ts
+---
+
+# Grafo de dependencias entre módulos
+
+> **Glosario**:
+>
+> - **Módulo hoja (leaf)**: módulo cuyo array `imports` no introduce dependencias hacia capas
+>   superiores (módulos de aplicación `@api/*`). Solo importa infraestructura framework neutra.
+> - **Barrel de `@aurora/decorators`**: `auth.decorator.ts` importa los guards desde
+>   `@aurora/modules/authentication` (vía su `index.ts`, que re-exporta `authentication.module`).
+>   Por eso TODO controller que use `@Auth(...)` depende transitivamente de ese módulo.
+> - **Ciclo**: si un módulo alcanzado por ese barrel importa de vuelta una capa superior, Node
+>   resuelve el export parcial a `undefined` y el boot muere.
+
+---
+
+## HR-MODGRAPH-001 — `AuthenticationModule` (y todo módulo en el barrel de `@aurora/decorators`) es HOJA
+
+| Campo     | Valor                                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                                       |
+| Severidad | `blocking`                                                                                                     |
+| Origen    | auto-memory `feedback_authentication_module_is_leaf.md` (originSessionId 93db189a). Verificado contra `@aurora/modules/authentication/authentication.module.ts` el 2026-05-29 (docstring + imports limpios) |
+
+### Enunciado
+
+`@aurora/modules/authentication/authentication.module.ts` DEBE ser un **módulo hoja**. Su array
+`imports` solo puede contener `PassportModule.register(...)` de `@nestjs/passport` (y, conceptualmente,
+módulos `@Global()` como `BridgesModule`, que no necesitan import explícito).
+
+Todo controller usa `@Auth('...')` desde `@aurora/decorators/auth.decorator.ts`, que importa los
+guards desde `@aurora/modules/authentication`. Si `authentication.module.ts` importa un módulo de
+aplicación (`OAuthModule`, `IamModule`, o cualquier `@api/*`), la cadena se cierra en ciclo:
+
+```
+controller.ts → @aurora/decorators → @aurora/modules/authentication (barrel)
+   → authentication.module.ts → OAuthModule → … → controller.ts
+```
+
+Node resuelve `Auth` a `undefined` (export parcial) y el arranque muere con
+`TypeError: (0 , decorators_1.Auth) is not a function`. El hint del stack apunta al controller, pero
+la RAÍZ está en `authentication.module.ts`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                       | ¿Permitido? | Acción correcta                                                                                                          |
+| --- | ----------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| 1   | `authentication.module.ts` con `imports: [PassportModule.register({ defaultStrategy: 'jwt' })]` | SÍ          | Estado correcto: hoja.                                                                                                    |
+| 2   | Añadir `OAuthModule` / `IamModule` / cualquier `@api/*` a `AuthenticationModule.imports`         | **NO**      | Revertir. Registrar el provider en el módulo CONSUMER que ya importa esa capa (p. ej. `@api/o-auth/o-auth.module.ts`).    |
+| 3   | Un service vive bajo `authentication/` pero depende de módulos de aplicación (repos OAuth, etc.) | parcial     | El fichero puede quedar en `@aurora/modules/authentication/infrastructure/...`, pero su `providers:` se registra en el módulo consumer (p. ej. `TokenRetentionService` registrado en `@api/o-auth/o-auth.module.ts`). |
+| 4   | `ScheduleModule.forRoot()` para providers programados de autenticación                           | **NO** aquí | Va en el módulo que aloja esos providers programados, NO en `AuthenticationModule`.                                       |
+
+### Anchor patterns
+
+Un futuro guard / la IA debe vigilar:
+
+- Aparición de `OAuthModule`, `IamModule` o cualquier import `@api/*` en el array `imports:` de
+  `authentication.module.ts` (o de otro módulo alcanzado por el barrel de `@aurora/decorators`).
+- Síntoma de regresión en runtime: el boot muere con `TypeError: (0 , decorators_1.Auth) is not a
+  function`. El stack apunta al controller (engañoso); la causa es un import de capa superior añadido
+  a un módulo que debe ser hoja → revertir ese import.
+
+> **Por qué advisory y no `detect` mecánico**: el constraint prohíbe TRES patrones distintos
+> (`OAuthModule`, `IamModule`, `@api/*`) y un `detect.pattern` es un único substring literal
+> (contrato `detect` actual). Un detect de un solo substring sería incompleto. Queda advisory: lo
+> surfacean el guard de arquitectura, la inyección de contexto y la fase propose.
+
+### Reglas relacionadas
+
+- **HR-MODULES-001** — no crear módulos paralelos; editar el generado. Ortogonal pero del mismo dominio modular.
+- **HR-BRIDGES-001** — los servicios cross-BC se exponen vía el `@Global() BridgesModule`, no importando el módulo proveedor (que es justo lo que rompería la condición de hoja aquí).

package/dist/templates/monorepo/cliter/harness-rules/modules.md

@@ -0,0 +1,78 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-29
+keywords:
+  - shadow module
+  - módulo paralelo
+  - aurora-catalyst-generated
+  - archivo generado editable
+  - generated file editable
+  - origin reconciliation
+  - three-way merge
+  - barrel-and-spread
+  - registro de flow
+  - flow registration
+  - architecture-checkpoint
+paths:
+  - backend/src/@api/**/*.module.ts
+---
+
+# Módulos y archivos generados
+
+> **Glosario**:
+>
+> - **Archivo generado**: archivo emitido por `catalyst generate` que lleva la cabecera
+>   `@aurora-catalyst-generated`.
+> - **Shadow module**: módulo paralelo creado al lado de uno generado para alojar código
+>   hand-written "sin tocar el generado". Anti-patrón.
+> - **`.origin`**: snapshot de la última salida del template. Sustenta el three-way merge en regen.
+> - **Barrel-and-spread**: patrón de registro de un flow handcrafted exportando sus piezas desde un
+>   barrel e incorporándolas por spread en el array correspondiente del módulo generado del BC.
+
+---
+
+## HR-MODULES-001 — Shadow Module Antipattern
+
+| Campo     | Valor                                                                    |
+| --------- | ------------------------------------------------------------------------ |
+| Estado    | `active`                                                                 |
+| Severidad | `blocking`                                                               |
+| Origen    | auto-memory `feedback_shadow_module_antipattern.md` (originSessionId 93db189a) |
+
+### Enunciado
+
+Cuando una funcionalidad pertenece a un módulo emitido por `catalyst generate`, se implementa
+EDITANDO el módulo generado en sitio. La cabecera `@aurora-catalyst-generated` es **metadata sobre
+el origen del archivo, NO una valla**. El sistema `.origin` + content-hash hace un three-way merge
+en cada regen (codegen / customización del dev / sesión IA): el archivo editado actual vs el
+snapshot `.origin` vs la nueva salida del template. Crear un módulo paralelo "para no tocar el
+generado" fragmenta el dominio, duplica nombres (`OAuthModule` + `OauthModule`) y produce confusión
+en runtime. NUNCA se hace.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                       | ¿Permitido? | Acción correcta                                                                                          |
+| --- | ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| 1   | Añadir lógica a un handler/resolver de un módulo generado                        | SÍ          | Editar el archivo generado en sitio; `.origin` reconcilia en la próxima regen.                           |
+| 2   | Registrar un flow handcrafted nuevo dentro del BC                                | SÍ          | Registrarlo por **barrel-and-spread** en el `<bc>.module.ts` generado (no en un `<flow>.module.ts`).     |
+| 3   | Crear `<bc>-custom.module.ts` paralelo "para no tocar el generado"               | **NO**      | Editar el generado directamente; `.origin` reconcilia. El módulo paralelo es el anti-patrón a evitar.    |
+| 4   | El cambio pertenece al CLI/generador, no a la solución concreta                  | —           | Cambiar a `/catalyst-dev-mode framework` y tocar el template `.eta`, no el archivo generado.             |
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- Creación de un nuevo `*.module.ts` cuyo nombre sea una variante de un módulo generado ya existente
+  en el mismo directorio (p. ej. `oauth.module.ts` junto a `o-auth.module.ts`, o `*-custom.module.ts`).
+- `Write` de un archivo NUEVO bajo `backend/src/@(api|app|aurora|bridges)/...`: lo intercepta el hook
+  `.claude/hooks/architecture-checkpoint.ts`, un guard **ya existente** que bloquea el primer `Write`
+  a un archivo nuevo en esas rutas para forzar la consulta de la estructura del proyecto ANTES de
+  crear shadow files. No es un anchor por verificar: el hook existe y opera hoy.
+- Comentarios `// manually maintained, re-apply after regen` ausentes en piezas hand-written dentro
+  de un archivo generado (señal de que la intención de customización no quedó marcada).
+
+### Reglas relacionadas
+
+- **HR-CODEGEN-001** — los archivos `@aurora-catalyst-generated` son editables; `.origin` reconcilia
+  en cada regen. Es el fundamento técnico que hace innecesario el shadow module.

package/dist/templates/monorepo/cliter/harness-rules/persistence-integrity.md

@@ -0,0 +1,92 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-07-31
+keywords:
+  - Obj.diffAtomic
+  - Obj.diff
+  - update payload
+  - persistence delta
+  - dataToUpdate
+  - diff atómico
+  - array sparse
+  - jsonb parcial
+  - atomic-update-payload-diff
+paths:
+  - backend/src/@app/**
+---
+
+# Cómputo del delta de persistencia (`Obj.diffAtomic` vs `Obj.diff`)
+
+> **Glosario**:
+>
+> - **`Obj.diff`**: diff estructural/posicional de `@aurorajs.dev/core-back` — recursa en objetos
+>   anidados y, en arrays, solo asigna los índices cambiados (array disperso). Pensado para
+>   reportes de cambios y comparación, NO para construir un payload de persistencia.
+> - **`Obj.diffAtomic`**: diff atómico de `@aurorajs.dev/core-back` — compara cada clave de
+>   primer nivel con igualdad profunda y, si difiere, emite el valor COMPLETO del payload sin
+>   recursar. Pensado exactamente para construir el delta que se persiste.
+> - **Delta de persistencia**: el objeto que un handler `update-by-id` pasa a su
+>   `updateByIdService.main(...)`, y que termina como el `SET` de una sentencia SQL `UPDATE`.
+
+---
+
+## HR-PERSISTENCE-001 — El delta de persistencia se computa con `Obj.diffAtomic`, nunca con `Obj.diff`
+
+| Campo     | Valor                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------ |
+| Estado    | `active`                                                                                    |
+| Severidad | `blocking`                                                                                  |
+| Origen    | OpenSpec change `atomic-update-payload-diff`, design.md D2/D7 — data loss en producción reproducida dos veces (embedded i18n map 2026-07-19; `entityTypes` GIN array) |
+
+### Enunciado
+
+Un handler que computa el objeto a persistir en una operación de escritura (`update-by-id`,
+`update-many`, `upsert`, o cualquier variante que calcule un delta contra el registro existente)
+SIEMPRE usa `Obj.diffAtomic(payload, entity)`. `Obj.diff` recursa en objetos anidados y, en
+arrays, solo asigna los índices cambiados — un array o un mapa jsonb es una columna ATÓMICA en
+Aurora (una propiedad de agregado = una columna), así que un diff parcial reemplaza la columna
+completa con el fragmento, en silencio y sin error en ninguna capa. `Obj.diff` NO se modifica por
+esta regla: sigue siendo la función correcta para DETECCIÓN DE CAMBIO (¿difiere A de B?) y para
+reportes estructurales/posicionales — nunca para construir el objeto que se escribe.
+
+### Casos exhaustivos
+
+<!-- DECISION MATRIX: situación → ¿permitido? → acción correcta -->
+
+| #   | Situación                                                                                          | ¿Permitido? | Acción correcta                                                                                    |
+| --- | --------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| 1   | Handler `update-by-id`/`update-many`/`upsert` computa `dataToUpdate`/el objeto pasado al `updateService`/`updateByIdService` | **NO** con `Obj.diff` | Usar `Obj.diffAtomic(payload, entity)`. Es el shape que emite el template desde `atomic-update-payload-diff`. |
+| 2   | Se necesita saber SI algo cambió (booleano/rama condicional), sin construir un payload de escritura — p. ej. `BR-IAM-ACCOUNT-001`'s recompute de `dPermissions` | SÍ con `Obj.diff` | `Obj.diff` es correcto: es detección de cambio, no un delta de persistencia. No migrar este call site. |
+| 3   | Se necesita un reporte estructural/posicional (auditoría, comparación para logging, UI de "qué cambió campo a campo") | SÍ con `Obj.diff` | `Obj.diff` es el diseño correcto — preserva posiciones e intenta minimizar el reporte, no construye SQL. |
+| 4   | Un array o un mapa jsonb (columna atómica) necesita re-emitirse "a mano" con un override local para evitar la corrupción de `Obj.diff` (el patrón `entityTypesUpdate`/`i18nRecomputeIncludeMap` que este change retiró) | **NO** | No reintroducir el escape hatch local. Usar `Obj.diffAtomic` en el diff base; el override manual queda obsoleto. |
+| 5   | Un campo del payload debe excluirse del delta por ser sensible/enmascarado (p. ej. `secret` en `BR-OAUTH-APPLICATION-001`) o pertenecer a otro agregado (p. ej. `code`/`applicationId` en `BR-HUB-APP-013`, `password` en `BR-BPP-003`) | SÍ | Seguir excluyendo (`delete payload.<campo>` o no incluirlo) ANTES de llamar a `Obj.diffAtomic` — el comportamiento de "clave ausente ⇒ nunca se emite" es idéntico al de `Obj.diff`. |
+
+### Anchor patterns
+
+<!-- globs / heurísticas que el content-guard o un futuro guard vigila -->
+
+- `Obj.diff(` dentro de un `*-update-*-by-id.handler.ts`, `*-update-*.handler.ts` o
+  `*-upsert-*.handler.ts` bajo `backend/src/@app/**` cuyo resultado se spread/pasa directamente al
+  `updateService`/`updateByIdService`/`upsertService` — sospechoso por defecto; verificar si es
+  realmente detección de cambio (caso 2) antes de aceptarlo.
+- Un bloque `// #region customizations` que reconstruye a mano un campo array/jsonb "porque
+  `Obj.diff` lo corrompería" — señal de que el escape hatch debería eliminarse a favor de
+  `Obj.diffAtomic` en el diff base (caso 4).
+- La regla es **advisory** (sin `detect` mecánico): un grep ciego de `Obj.diff(` no puede
+  distinguir el caso 1 (prohibido) del caso 2/3 (correcto) sin leer el contexto — el mismo símbolo
+  sirve a ambos usos.
+
+### Reglas relacionadas
+
+- **HR-CODEGEN-001** — los handlers de update-by-id llevan cabecera `@aurora-catalyst-generated`;
+  esta regla se cumple editándolos en sitio (el fix vive también en la plantilla que los regenera).
+
+### Tests
+
+- `packages/core-back/src/domain/shared/obj.spec.ts` — describe `'diffAtomic'`.
+- `packages/cli/test/codegen/backend/i18n-recompute-handlers.test.ts` — asserts `Obj.diffAtomic`
+  en la salida del handler `update-by-id`.
+- `backend/src/@app/tools/custom-field-group/application/update/tools-update-custom-field-group-by-id.handler.spec.ts`
+  — regresión: `'persists the full entityTypes array verbatim when an entity is added — would
+  corrupt to a sparse array with a hole if left to Obj.diff'`.

package/dist/templates/monorepo/cliter/harness-rules/ports-adapters.md

@@ -0,0 +1,82 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-28
+keywords:
+  - port
+  - adapter
+  - adaptador
+  - dependency inversion
+  - inversión de dependencias
+  - cross-layer
+  - aurora provider
+  - useClass provider
+  - framework necesita app
+  - current account service
+paths:
+  - backend/src/@aurora/**
+  - frontend/src/@aurora/**
+---
+
+# Ports & adapters cross-layer (@aurora ↔ app)
+
+> **Glosario**:
+>
+> - **Port**: interface abstracta declarada en `@aurora` (framework). No conoce app/BC.
+> - **Adapter**: implementación concreta, BC-coupled, que vive en app.
+> - **`aurora.provider.ts`**: punto de cableado `{ provide: Port, useClass: Adapter }`.
+> - **Cross-layer**: dependencia que cruza la frontera framework (`@aurora`) ↔ aplicación (app/BC).
+
+---
+
+## HR-PORTS-001 — Default a ports/adapters para deps cross-layer @aurora ↔ app
+
+| Campo     | Valor                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                           |
+| Severidad | `blocking`                                                                                         |
+| Origen    | auto-memory `feedback_generated_editable_and_ports_default.md` (parte 2, originSessionId 93db189a) |
+
+### Enunciado
+
+Cuando código framework (`@aurora`) necesita algo acoplado a app o a un BC, la respuesta POR DEFECTO
+es: un **PORT** (interface abstracta) en `@aurora` + un **ADAPTER** (concreto, BC-coupled) en app,
+cableados con `{ provide: Port, useClass: Adapter }` en `app/aurora.provider.ts`; los consumidores
+inyectan el PORT, nunca el adapter. Así se resuelven las inversiones `@aurora → app` por dependency
+inversion. NUNCA se pone código acoplado a app/IAM (una query específica, un tipo de app más allá de
+`aurora.types`) dentro de `@aurora`. Es el mismo idiom en frontend (`AuthenticationService` port +
+`AuthenticationAuroraAdapterService`) y en backend. Se propone DIRECTAMENTE, no como pregunta, salvo
+fork genuino.
+
+Ejemplo canónico (aplicado en el cambio `add-iam-me-account`, 2026-05-27): el port
+`CurrentAccountService` vive en `@aurora`; el adapter `CurrentAccountIamAdapter` vive en app; se
+cablean en `aurora.provider.ts`. La query `iamMeAccount`, por ser IAM-coupled, va a la data-access
+del BC IAM (`account.graphql.ts`), no a `@aurora`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                              | ¿Permitido? | Acción correcta                                                                                          |
+| --- | -------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| 1   | `@aurora` necesita una operación/dato acoplado a app o a un BC                          | SÍ          | Port (abstracto) en `@aurora` + adapter (concreto) en app + wiring `useClass` en `aurora.provider.ts`.   |
+| 2   | Una query IAM/BC-coupled que el adapter necesita                                        | SÍ          | Vive en la data-access de su BC (`*.graphql.ts`), no en `@aurora`. El adapter la invoca.                 |
+| 3   | Meter el tipo/la query/lo app-coupled directamente dentro de `@aurora`                  | **NO**      | Extraer la abstracción como port en `@aurora` y dejar lo concreto en app vía adapter.                    |
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- Imports dentro de `backend/src/@aurora/**` (o `frontend/src/@aurora/**`) que resuelvan a `@app/**`,
+  `@api/**` o a un BC concreto: inversión `@aurora → app` sin port.
+- Tipos o queries con vocabulario de BC (IAM, OAuth, etc.) declarados dentro de `@aurora` más allá de
+  `aurora.types`.
+- Adapters concretos inyectados directamente (`useClass` referenciado por el consumer) en vez de
+  inyectar el port por su abstracción.
+
+### Reglas relacionadas
+
+- **HR-BRIDGES-001** — misma mecánica de dependency inversion en la frontera BC↔BC (ports/adapters en
+  `@bridges/`).
+- **HR-CODEGEN-001** — cuando la dep cross-layer aparece al editar un archivo generado, el port/adapter
+  es la respuesta; no se evita editando en paralelo.
+- **HR-ACL-001** — el adapter consume el tipo canónico del aggregate (`@api/graphql`), no una interface
+  local vía double cast.

package/dist/templates/monorepo/cliter/harness-rules/protocol-flows.md

@@ -0,0 +1,88 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-29
+keywords:
+  - protocol flow
+  - flow handcrafted
+  - flujo hecho a mano
+  - hand-written flow
+  - barrel-and-spread
+  - composite handler
+  - handler compuesto
+  - dispatch por transporte
+  - controller resolver dispatch
+  - oauth token issuance
+  - jwks
+  - webhook
+paths:
+  - backend/src/@api/**
+  - backend/src/@app/**
+---
+
+# Flujos de protocolo hechos a mano (no-agregado)
+
+> **Glosario**:
+>
+> - **Flujo de protocolo hand-written**: endpoint NO generado por `catalyst generate` (emisión de tokens OAuth, JWKS, webhooks custom). No tiene `*.aurora.yaml`.
+> - **Barrel-and-spread**: el patrón con el que cada agregado Cliter se registra — un `index.ts` exporta arrays (`<Bc>FlowsApiControllers`, etc.) que el `<bc>.module.ts` generado esparce (`...`) en sus propios arrays.
+> - **Composite handler**: el handler que contiene el dispatch por discriminador; los transportes (REST/GraphQL) lo invocan, no lo replican.
+
+---
+
+## HR-FLOWS-001 — Los flujos hand-written siguen barrel-and-spread + un único composite handler
+
+| Campo     | Valor                                                                                          |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                       |
+| Severidad | `blocking`                                                                                      |
+| Origen    | auto-memory `feedback_protocol_flow_structure_and_dispatch.md`; corregido 2× (Phase 2.2 y 2026-05-27). Verificado contra `@api/o-auth/flows` + `@app/o-auth/flows` el 2026-05-29 |
+
+### Enunciado
+
+Un flujo de protocolo escrito a mano (sin `cliter/<bc>/<folder>.aurora.yaml`) se estructura con la
+MISMA convención que un agregado Cliter, NO con ficheros planos y NO con un `<flow>.module.ts`
+dedicado:
+
+```
+@api/<bc>/<flow>/
+├── index.ts          ← BARREL: exporta <Bc>FlowsApi{Controllers,Resolvers,Handlers} (arrays)
+├── controllers/      ← controllers REST en subdir
+├── resolvers/        ← resolvers GraphQL en subdir
+└── graphql/          ← fragmentos de schema en subdir
+```
+
+El `<bc>.module.ts` **generado** importa el barrel del flow y **esparce** sus arrays en sus propios
+`controllers:` / `providers:` (sección manually-maintained) — igual que los agregados. **NO** hay
+`<flow>.module.ts` dedicado, **NO** hay `imports: [<Flow>Module]`, **NO** hay entrada en
+`app.module.ts`.
+
+La lógica de negocio —incluido el dispatch entre variantes— vive en UN **composite handler**
+(`@app/<bc>/<flow>/application/<flow>.handler.ts`), nunca duplicada entre transportes. El controller
+REST y el resolver GraphQL parsean su forma de transporte y ambos llaman `composite.main(input)`;
+NUNCA replican el `if (grantType === …) … else …`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                  | ¿Permitido? | Acción correcta                                                                                       |
+| --- | ------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------- |
+| 1   | Nuevo flujo hand-written expuesto sobre REST y/o GraphQL                                    | SÍ          | Subdirs `controllers/`/`resolvers/`/`graphql/` + `index.ts` barrel; esparcir en el `<bc>.module.ts` generado |
+| 2   | Ficheros del flujo planos en la raíz (`<flow>/foo.controller.ts` sin subdir)               | **NO**      | Moverlos a los subdirs canónicos                                                                       |
+| 3   | Crear `<flow>.module.ts` dedicado e `imports: [<Flow>Module]` / entrada en `app.module.ts` | **NO**      | Barrel-and-spread en el `<bc>.module.ts` generado (sección manually-maintained). Ver `HR-MODULES-001`. |
+| 4   | Endpoint en REST Y GraphQL: meter el dispatch en cada transporte                            | **NO**      | Dispatch en un composite handler; los transportes llaman `composite.main(input)`                       |
+| 5   | DTO de input GraphQL del flujo                                                              | usar codegen | Importar el tipo de `@api/graphql` (regenerado de los `*.graphql`); alias `<X>GraphQLInput` solo si choca con un tipo de dominio del mismo nombre |
+| 6   | Poner el DTO de transporte GraphQL en `@app/<bc>/<flow>/domain/flows.types.ts`              | **NO**      | `flows.types.ts` es la capa DOMINIO (Hexagonal, sin framework); aloja el input CANÓNICO transport-agnostic, no el DTO de transporte |
+
+### Anchor patterns
+
+Un futuro guard / la IA debe vigilar:
+
+- Un `*.module.ts` nuevo bajo `@api/<bc>/<flow>/` o un `imports: [<Flow>Module]` añadido al `<bc>.module.ts` o a `app.module.ts` para un flujo hand-written.
+- Ficheros `*.controller.ts` / `*.resolver.ts` planos en la raíz del directorio del flujo (fuera de `controllers/`/`resolvers/`).
+- El mismo `switch`/`if` de discriminador (grantType, etc.) presente tanto en el controller como en el resolver del mismo flujo (dispatch duplicado).
+- Una `interface` local de input en el resolver "para desacoplar del codegen", o un DTO de transporte declarado en `domain/flows.types.ts`.
+
+### Reglas relacionadas
+
+- **HR-MODULES-001** — no crear módulos paralelos; el registro va por barrel-and-spread en el generado (mismo mecanismo que este flujo usa).
+- **HR-ACL-001** — el input GraphQL del flujo es el tipo canónico de `@api/graphql`, no una interface local.

package/dist/templates/monorepo/cliter/harness-rules/types-acl.md

@@ -0,0 +1,93 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-28
+keywords:
+  - acl
+  - anti-corruption layer
+  - double cast
+  - as unknown as
+  - tipo canónico
+  - canonical type
+  - api graphql
+  - narrowing local
+  - localized assertion
+  - zod class-validator
+  - validación runtime
+paths:
+  - backend/src/@app/**
+  - backend/src/@bridges/**
+detect:
+  pattern: 'as unknown as'
+  message: 'HR-ACL-001 (blocking): double cast prohibido. Importa el tipo canónico del aggregate desde `@api/graphql` o construye un ACL real con zod/class-validator (validación runtime); nunca un `as ... as` que silencia a TypeScript sin validar nada. Para estrechar un `JSON: any` usa una assertion LOCALIZADA en el punto de uso, no una interface `Raw*` alcanzada por double cast.'
+---
+
+# Tipos y ACLs (sin fake casts)
+
+> **Glosario**:
+>
+> - **ACL (Anti-Corruption Layer)**: capa que traduce y VALIDA en runtime el contrato de otro
+>   sistema/BC. Un cast NO es un ACL.
+> - **Double cast**: `as unknown as LocalInterface`. Silencia a TypeScript sin validar nada.
+> - **Tipo canónico**: en Aurora, `@api/graphql` ES el tipo del aggregate (no un DTO transport-only).
+> - **Narrowing local**: type assertion puntual en el punto de uso para estrechar un `JSON: any`.
+
+---
+
+## HR-ACL-001 — Sin ACLs fake via as unknown as double cast
+
+| Campo     | Valor                                                          |
+| --------- | -------------------------------------------------------------- |
+| Estado    | `active`                                                       |
+| Severidad | `blocking`                                                     |
+| Origen    | auto-memory `feedback_no_fake_acl_double_cast.md` (originSessionId 93db189a) |
+
+### Enunciado
+
+NUNCA usar `as unknown as LocalInterface` para "shape-narrow" un aggregate type. El double cast
+PARECE un Anti-Corruption Layer pero NO lo es: no hay validación runtime, solo un cast que silencia a
+TypeScript y permite que la interface local DERIVE del aggregate canónico (un campo `string | null`
+acaba tipado como `string`, etc.). En Aurora, `@api/graphql` ES el tipo canónico del aggregate (el
+propio application service lo devuelve), no un DTO transport-only: se importa directamente de ahí.
+Para estrechar un campo `JSON: any` a `Record<string, string[]>` se usa una type assertion
+LOCALIZADA en el punto de uso. Si genuinamente necesitas un ACL (contrato de otro BC, sistema
+externo, invariantes runtime a imponer), se construye con `zod` / `class-validator` (validación
+runtime de verdad), nunca con un cast.
+
+Ejemplo: en `IamAccountLoaderAdapter` (2026-05-25) se había introducido `interface RawIamAccount`
+duplicando la shape de `IamAccount` y se alcanzaba vía
+`(await findAccount.main(...)) as unknown as RawIamAccount`. Era incorrecto: la interface local
+divergía (`clientId: string | null` vs `string`) y no validaba nada. Lo correcto es usar `IamAccount`
+de `@api/graphql` directamente.
+
+> **No confundir con la frontera de parseo honesta**: una assertion única como `as TFrontmatter` en
+> `scripts/_catalog-runtime/parse.ts` al parsear YAML externo realmente desconocido NO viola esta
+> regla — es narrowing legítimo de input genuinamente unknown en la frontera de parseo, distinto de
+> fingir un ACL sobre un aggregate ya tipado.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                          | ¿Permitido? | Acción correcta                                                                                          |
+| --- | ---------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| 1   | Consumir un aggregate de Aurora en un adapter o consumer                            | SÍ          | Importar el tipo desde `@api/graphql` (`IamAccount`, `OAuthClient`, …). Es el tipo canónico.             |
+| 2   | Estrechar un campo `JSON: any` a una shape concreta                                 | SÍ          | Assertion local en el punto de uso: `(account.dPermissions ?? {}) as Record<string, string[]>`.          |
+| 3   | Declarar `interface RawXxx` local + alcanzarla con `as unknown as`                  | **NO**      | Usar el tipo canónico de `@api/graphql`. El double cast es un red flag; si lo escribes, busca otra vía.  |
+| 4   | Necesitas un ACL real (otro BC, sistema externo, invariantes runtime)               | SÍ          | Construirlo con `zod` / `class-validator` (validación runtime), no con un cast.                          |
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- La secuencia `as unknown as` en cualquier archivo bajo `backend/src/@app/**` o
+  `backend/src/@bridges/**`: red flag casi siempre indicativo de un fake ACL.
+- Interfaces locales con prefijo `Raw` (`RawIamAccount`, `RawOAuthClient`, …) que dupliquen la shape
+  de un aggregate ya disponible en `@api/graphql`.
+- Excepción a NO marcar: una assertion única en una frontera de parseo de input externo realmente
+  unknown (p. ej. `as TFrontmatter` sobre YAML crudo). No es violación.
+
+### Reglas relacionadas
+
+- **HR-MODES-001** — mismo principio en Solution mode: consumir el tipo canónico y estrechar en el
+  punto de uso; la interface local es generalización defensiva prematura.
+- **HR-PORTS-001** — los adapters cross-layer también consumen el tipo canónico del aggregate, no una
+  shape local.