@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

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

@@ -0,0 +1,294 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-09-01
+keywords:
+  - barrel
+  - barrel import
+  - import por barrel
+  - sub-barrel
+  - deep import
+  - deep-path import
+  - import profundo
+  - index.ts
+  - public module surface
+  - superficie pública del módulo
+  - module encapsulation
+  - encapsulamiento de módulo
+  - apps frontend
+  - bridges barrel
+  - superficie de consumo
+  - consumer surface
+  - wiring surface
+  - superficie de wiring
+  - adapters sub-barrel
+paths:
+  - backend/src/@api/**
+  - backend/src/@app/**
+  - backend/src/@bridges/**
+  - backend/src/@aurora/**
+  - frontend/src/@aurora/**
+  - frontend/src/app/domains/admin/apps/**
+---
+
+# Imports por barrel (módulo y sub-barrel público)
+
+> **Glosario**:
+>
+> - **Barrel**: el `index.ts` de un módulo que re-exporta su superficie pública.
+> - **Sub-barrel público**: una subcarpeta del módulo con su PROPIO `index.ts` que expone una
+>   superficie acotada (p.ej. `domain/ports`, `ports`, `infrastructure/guards`). Importar de él
+>   es válido.
+> - **Deep-path import**: import que apunta a un FICHERO de implementación interno
+>   (`.../services/x.service`, `.../strategies/x.strategy`, `.../data-access/x.config`) en vez de
+>   a un barrel.
+> - **`[bc]/[module]`**: estructura `<alias-raíz>/<bounded-context>/<módulo>` común a `@api`,
+>   `@app` y `@bridges` (p.ej. `@app/o-auth/shared`, `@bridges/o-auth/client`).
+> - **Módulo de framework (`@aurora`)**: no es un BC. Backend: `@aurora/modules/<module>` (con
+>   barrel) + áreas como `@aurora/decorators`; los ficheros sueltos de primer nivel sin barrel
+>   (`@aurora/shared.module`, `@aurora/core.module`) se importan directamente. Frontend: `@aurora`
+>   expone un barrel raíz (`src/@aurora/index.ts`, siempre `from '@aurora'`) MÁS un conjunto de
+>   **sub-barrel aliases declarados explícitamente** en `frontend/tsconfig.json`
+>   (`@aurora/components`, `@aurora/modules/health`, …, HR-BARRELS-003); un specifier que nombra
+>   un fichero de implementación NO está en esa tabla y simplemente no resuelve.
+
+---
+
+## HR-BARRELS-001 — Importar activos por barrel (módulo o sub-barrel público), no por deep-path
+
+| Campo     | Valor                                                                                                                                                                                                                          |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Estado    | `derogated`                                                                                                                                                                                                                    |
+| Severidad | `informational`                                                                                                                                                                                                              |
+| Origen    | Decisión de equipo (sesión 2026-06-03): consolidar los imports entre módulos sobre el barrel público. Aplicado a `@app/o-auth/shared`, `@bridges/o-auth/client` y `@bridges/iam/<module>`; ampliado a `@aurora` (back+front) y a los BC de frontend en la misma sesión. Sustituida por **HR-BARRELS-003** (change `reduce-frontend-eager-payload`). |
+
+### Enunciado
+
+Un activo de un módulo se importa a través de un **barrel** (`index.ts`): el del módulo
+(`<alias>/<bc>/<module>`) o un **sub-barrel público** del módulo (una subcarpeta con su propio
+`index.ts` que expone una superficie acotada, p.ej. `.../domain/ports`, `.../ports`,
+`.../infrastructure/guards`). NUNCA por **deep-path a un fichero de implementación**
+(`.../services/x.service`, `.../strategies/x.strategy`, `.../data-access/x.config`). El barrel es
+la superficie pública; los ficheros internos son detalle de implementación y no deben aparecer en
+el import specifier de OTRO módulo. Si el activo no está expuesto, se AÑADE al `index.ts`
+correspondiente (del módulo o de un sub-barrel) y se importa por barrel.
+
+Importar de un sub-barrel acotado en vez del barrel raíz no solo es válido: a veces es
+OBLIGATORIO. Ej.: los contratos de `@aurora/modules/authentication/domain/ports` (Symbols +
+interfaces, cero side-effects) se importan por ese sub-barrel para NO arrastrar el
+`AuthenticationModule` vía el barrel raíz, respetando HR-MODGRAPH-001 (authentication es hoja).
+
+**Alcance.** Backend: `@api`, `@app`, `@bridges` (`[bc]/[module]`) y `@aurora`
+(`@aurora/modules/<module>`, `@aurora/decorators`, …; ficheros sueltos de primer nivel sin barrel
+se importan directamente). Frontend: `@aurora` (barrel único, siempre `from '@aurora'`) y los BC
+bajo `app/domains/admin/apps/<bc>/<module>` y `<bc>/shared` (cada uno con su `index.ts`).
+
+La regla gobierna la **FORMA** del import, no su **legitimidad**: qué módulo puede importar de cuál
+lo siguen gobernando HR-BRIDGES-001 (cross-BC SOLO vía un port en `@bridges/`) y HR-MODULES-001.
+Usar la forma barrel NUNCA autoriza un import cross-BC que esas reglas prohíben.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                                            | ¿Permitido? | Acción correcta                                                                            |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| 1   | Importar de otro módulo por su barrel: `from '@app/o-auth/shared'`                                                    | SÍ          | Forma canónica: importar del `index.ts` del módulo.                                        |
+| 2   | Importar de un sub-barrel público (carpeta con `index.ts`): `from '@aurora/modules/authentication/domain/ports'`     | SÍ          | Válido — y a veces obligatorio para no arrastrar el módulo (HR-MODGRAPH-001).              |
+| 3   | Deep-path a un fichero de implementación: `from '@app/o-auth/shared/services/token-retention.service'`               | **NO**      | Exportar el activo en el `index.ts` (del módulo o de un sub-barrel) e importar por barrel. |
+| 4   | El activo no está expuesto por ningún barrel                                                                          | SÍ          | Añadir `export * from './…'` al `index.ts` correspondiente; luego importar por barrel.     |
+| 5   | Usar la forma barrel para cruzar a OTRO BC (`@app/<other-bc>/…`) y saltarse la frontera                              | **NO**      | No autoriza cross-BC: va por un port en `@bridges/` (HR-BRIDGES-001).                      |
+| 6   | Imports relativos DENTRO del mismo módulo (`./…`) o los re-exports del propio `index.ts`                             | SÍ          | Lo interno del módulo usa rutas relativas; la regla aplica a imports ENTRE módulos.        |
+| 7   | Fichero suelto de primer nivel de `@aurora` (backend) sin barrel (`@aurora/shared.module`, `@aurora/core.module`)    | SÍ          | No es un módulo con barrel: el import directo del fichero es correcto.                     |
+| 8   | Frontend — deep-path a un fichero de otro módulo BC: `from '…/apps/iam/user/data-access/user.list-config'` | **NO**      | Importar del barrel del módulo: `…/apps/iam/user` (o `iam/shared`).            |
+| 9   | Frontend — importar de `@aurora`: `from '@aurora'`                                                                    | SÍ          | Barrel único del frontend; nunca subrutas (el alias no las resuelve).                      |
+
+### Anchor patterns
+
+Un futuro guard (lint) debe vigilar — el discriminante es **fichero-de-implementación vs
+carpeta-con-`index.ts`**, NO la profundidad de segmentos (una heurística por profundidad daría
+falsos positivos en sub-barrels):
+
+- **Backend**: un import bajo `@(api|app|bridges)/<bc>/<module>/…` o `@aurora/modules/<module>/…`
+  cuyo destino es un FICHERO `.ts` de implementación (no una carpeta con `index.ts`). Importar de
+  un sub-barrel (carpeta con `index.ts`: `ports`, `domain/ports`, `infrastructure/guards`) NO es
+  violación.
+- **Frontend**: un import a `app/domains/admin/apps/<bc>/<module>/<subdir>/<file>` que
+  apunta a un fichero interno en vez de al barrel `<bc>/<module>` o `<bc>/shared`. `@aurora` debe
+  ser siempre `from '@aurora'` (sin subrutas; el alias no las resuelve).
+- **Excepciones legítimas**: imports relativos `./…` internos al propio módulo; los
+  `export * from './…'` del propio `index.ts`; los ficheros sueltos de primer nivel de `@aurora`
+  backend; y cualquier sub-barrel público (carpeta con su propio `index.ts`).
+
+### Implementa
+
+- `backend/src/@app/o-auth/shared/index.ts` — expone `TokenRetentionService`.
+- `backend/src/@bridges/iam/permission/index.ts` — barrel de consumo de un módulo de `@bridges` (la composición de superficies de `@bridges` la gobierna HR-BARRELS-002).
+- `backend/src/@api/o-auth/o-auth.module.ts`, `backend/src/@api/iam/iam.module.ts` — importan los adapters por sub-barrel público.
+- `scripts/harness-rules/lint-barrels.ts` — lint determinista de los anchor patterns de HR-BARRELS-003 y HR-BARRELS-002; superficies: `pnpm hr:lint-barrels` (full/staged), pre-commit staged (`.husky/pre-commit`), PostToolUse por-fichero (`.claude/hooks/lint-barrels.ts`).
+
+### Reglas relacionadas
+
+- **HR-BARRELS-002** — composición de superficies en `@bridges`: qué exporta el barrel de módulo y qué el sub-barrel `adapters/`. HR-BARRELS-001 gobierna la FORMA del import; la 002, el CONTENIDO de cada barrel.
+- **HR-BRIDGES-001** — gobierna QUÉ se importa cross-BC (vía port en `@bridges/`); HR-BARRELS-001 gobierna la FORMA (barrel) del import legítimo, sin relevar fronteras.
+- **HR-MODGRAPH-001** — la razón por la que un sub-barrel acotado (`domain/ports`) es a veces obligatorio: importar por el barrel raíz arrastraría el `AuthenticationModule` (hoja) y arriesgaría un ciclo.
+- **HR-MODULES-001** — barrel-and-spread para el registro en módulos; misma filosofía del barrel como superficie pública.
+- **HR-FLOWS-001** — barrel-and-spread de flows hand-written; consistente con esta convención.
+- **HR-BARRELS-003** — regla sustituta, activa desde 2026-09-01.
+
+### Derogación
+
+**2026-09-01**: el frontend `@aurora` deja de ser un barrel único (`siempre from '@aurora'`) para
+exponer, ADEMÁS del barrel raíz, un conjunto de sub-barrel aliases declarados en
+`frontend/tsconfig.json` (change `reduce-frontend-eager-payload`), lo que hace falso el glosario y
+el Caso #9 de esta regla; sustituida por **HR-BARRELS-003**, que conserva el resto del enunciado sin
+cambios.
+
+---
+
+## HR-BARRELS-003 — Importar activos por barrel (módulo o sub-barrel público), no por deep-path
+
+| Campo     | Valor                                                                                                                                                                                                                          |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                                                                                                                                                       |
+| Severidad | `informational`                                                                                                                                                                                                              |
+| Origen    | Sustituye a **HR-BARRELS-001** (`derogated` 2026-09-01): change `reduce-frontend-eager-payload`. El frontend `@aurora` deja de ser un barrel único y pasa a exponer, además del barrel raíz, un conjunto de sub-barrel aliases declarados explícitamente en `frontend/tsconfig.json` (`@aurora/components`, `@aurora/modules/health`, …). El resto del enunciado y de la matriz de casos de HR-BARRELS-001 se conserva sin cambios. |
+
+### Enunciado
+
+Un activo de un módulo se importa a través de un **barrel** (`index.ts`): el del módulo
+(`<alias>/<bc>/<module>`) o un **sub-barrel público** del módulo (una subcarpeta con su propio
+`index.ts` que expone una superficie acotada, p.ej. `.../domain/ports`, `.../ports`,
+`.../infrastructure/guards`). NUNCA por **deep-path a un fichero de implementación**
+(`.../services/x.service`, `.../strategies/x.strategy`, `.../data-access/x.config`). El barrel es
+la superficie pública; los ficheros internos son detalle de implementación y no deben aparecer en
+el import specifier de OTRO módulo. Si el activo no está expuesto, se AÑADE al `index.ts`
+correspondiente (del módulo o de un sub-barrel) y se importa por barrel.
+
+Importar de un sub-barrel acotado en vez del barrel raíz no solo es válido: a veces es
+OBLIGATORIO. Ej.: los contratos de `@aurora/modules/authentication/domain/ports` (Symbols +
+interfaces, cero side-effects) se importan por ese sub-barrel para NO arrastrar el
+`AuthenticationModule` vía el barrel raíz, respetando HR-MODGRAPH-001 (authentication es hoja).
+
+**Alcance.** Backend: `@api`, `@app`, `@bridges` (`[bc]/[module]`) y `@aurora`
+(`@aurora/modules/<module>`, `@aurora/decorators`, …; ficheros sueltos de primer nivel sin barrel
+se importan directamente). Frontend: `@aurora` expone un **barrel raíz** (`from '@aurora'`) MÁS un
+conjunto de **sub-barrel aliases declarados explícitamente** en `frontend/tsconfig.json`
+(`@aurora/components`, `@aurora/modules/health`, …) — importar de un alias declarado es válido; un
+specifier que nombra un fichero de implementación sigue prohibido y, al no estar en esa tabla,
+simplemente NO RESUELVE. Y los BC bajo `app/domains/admin/apps/<bc>/<module>` y `<bc>/shared`
+(cada uno con su `index.ts`).
+
+La regla gobierna la **FORMA** del import, no su **legitimidad**: qué módulo puede importar de cuál
+lo siguen gobernando HR-BRIDGES-001 (cross-BC SOLO vía un port en `@bridges/`) y HR-MODULES-001.
+Usar la forma barrel NUNCA autoriza un import cross-BC que esas reglas prohíben.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                                            | ¿Permitido? | Acción correcta                                                                            |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| 1   | Importar de otro módulo por su barrel: `from '@app/o-auth/shared'`                                                    | SÍ          | Forma canónica: importar del `index.ts` del módulo.                                        |
+| 2   | Importar de un sub-barrel público (carpeta con `index.ts`): `from '@aurora/modules/authentication/domain/ports'`     | SÍ          | Válido — y a veces obligatorio para no arrastrar el módulo (HR-MODGRAPH-001).              |
+| 3   | Deep-path a un fichero de implementación: `from '@app/o-auth/shared/services/token-retention.service'`               | **NO**      | Exportar el activo en el `index.ts` (del módulo o de un sub-barrel) e importar por barrel. |
+| 4   | El activo no está expuesto por ningún barrel                                                                          | SÍ          | Añadir `export * from './…'` al `index.ts` correspondiente; luego importar por barrel.     |
+| 5   | Usar la forma barrel para cruzar a OTRO BC (`@app/<other-bc>/…`) y saltarse la frontera                              | **NO**      | No autoriza cross-BC: va por un port en `@bridges/` (HR-BRIDGES-001).                      |
+| 6   | Imports relativos DENTRO del mismo módulo (`./…`) o los re-exports del propio `index.ts`                             | SÍ          | Lo interno del módulo usa rutas relativas; la regla aplica a imports ENTRE módulos.        |
+| 7   | Fichero suelto de primer nivel de `@aurora` (backend) sin barrel (`@aurora/shared.module`, `@aurora/core.module`)    | SÍ          | No es un módulo con barrel: el import directo del fichero es correcto.                     |
+| 8   | Frontend — deep-path a un fichero de otro módulo BC: `from '…/apps/iam/user/data-access/user.list-config'` | **NO**      | Importar del barrel del módulo: `…/apps/iam/user` (o `iam/shared`).            |
+| 9   | Frontend — importar de un sub-barrel `@aurora` declarado en `frontend/tsconfig.json`: `from '@aurora'`, `from '@aurora/components'`, `from '@aurora/modules/health'` | SÍ          | Barrel raíz o alias declarado — ambos son superficie pública; un specifier que nombra un fichero de implementación no está en la tabla y no resuelve. |
+
+### Anchor patterns
+
+Un futuro guard (lint) debe vigilar — el discriminante es **fichero-de-implementación vs
+carpeta-con-`index.ts`**, NO la profundidad de segmentos (una heurística por profundidad daría
+falsos positivos en sub-barrels):
+
+- **Backend**: un import bajo `@(api|app|bridges)/<bc>/<module>/…` o `@aurora/modules/<module>/…`
+  cuyo destino es un FICHERO `.ts` de implementación (no una carpeta con `index.ts`). Importar de
+  un sub-barrel (carpeta con `index.ts`: `ports`, `domain/ports`, `infrastructure/guards`) NO es
+  violación.
+- **Frontend**: un import a `app/domains/admin/apps/<bc>/<module>/<subdir>/<file>` que
+  apunta a un fichero interno en vez de al barrel `<bc>/<module>` o `<bc>/shared`. `@aurora` acepta
+  el barrel raíz (`from '@aurora'`) y cualquier sub-barrel alias declarado en
+  `frontend/tsconfig.json`; un specifier RELATIVO que escapa a un fichero interno de `@aurora`
+  bypaseando esa tabla es violación igual que un deep-path por alias.
+- **Excepciones legítimas**: imports relativos `./…` internos al propio módulo; los
+  `export * from './…'` del propio `index.ts`; los ficheros sueltos de primer nivel de `@aurora`
+  backend; y cualquier sub-barrel público (carpeta con su propio `index.ts`).
+
+### Implementa
+
+- `frontend/tsconfig.json` — tabla de sub-barrel aliases declarados del `@aurora` frontend (D1 de `reduce-frontend-eager-payload`).
+- `scripts/harness-rules/lint-barrels.ts` — lint determinista de los anchor patterns de HR-BARRELS-003 y HR-BARRELS-002; superficies: `pnpm hr:lint-barrels` (full/staged), pre-commit staged (`.husky/pre-commit`), PostToolUse por-fichero (`.claude/hooks/lint-barrels.ts`).
+
+### Reglas relacionadas
+
+- **HR-BARRELS-001** — regla derogada que esta sustituye; misma FORMA de import, solo cambia la Alcance frontend.
+- **HR-BARRELS-002** — composición de superficies en `@bridges`: qué exporta el barrel de módulo y qué el sub-barrel `adapters/`. HR-BARRELS-003 gobierna la FORMA del import; la 002, el CONTENIDO de cada barrel.
+- **HR-BRIDGES-001** — gobierna QUÉ se importa cross-BC (vía port en `@bridges/`); HR-BARRELS-003 gobierna la FORMA (barrel) del import legítimo, sin relevar fronteras.
+- **HR-MODGRAPH-001** — la razón por la que un sub-barrel acotado (`domain/ports`) es a veces obligatorio: importar por el barrel raíz arrastraría el `AuthenticationModule` (hoja) y arriesgaría un ciclo.
+- **HR-MODULES-001** — barrel-and-spread para el registro en módulos; misma filosofía del barrel como superficie pública.
+- **HR-FLOWS-001** — barrel-and-spread de flows hand-written; consistente con esta convención.
+
+---
+
+## HR-BARRELS-002 — @bridges: el barrel de módulo expone contratos; los adapters van en su sub-barrel
+
+| Campo     | Valor                                                                                                                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                                                                                                                            |
+| Severidad | `blocking`                                                                                                                                                                                          |
+| Origen    | Decisión de equipo (sesión 2026-06-11): estandarización de barrels de `@bridges` tras detectar 28 formas de import distintas para 9 módulos y barrels de módulo re-exportando adapters (riesgo de ciclo análogo al de `AuthenticationModule`, ver HR-MODGRAPH-001). |
+
+### Enunciado
+
+Un módulo de `@bridges/<bc>/<module>` tiene DOS públicos y DOS superficies separadas. El barrel del
+módulo (`index.ts`) es la **superficie de consumo**: exporta SOLO contratos — ports (interfaces +
+tokens Symbol) y helpers públicos (funciones sueltas sin DI ni side-effects de carga) — y NUNCA
+adapters. El sub-barrel `adapters/index.ts` es la **superficie de wiring**: exporta los adapters
+concretos y lo importan exclusivamente los composition roots (`@bridges/providers/*.bridge.ts`,
+`@bridges/bridges.module.ts` y los `@api/<supplier-bc>/*.module.ts` que registran el adapter).
+Motivo: un barrel se ejecuta ENTERO en runtime; si re-exporta adapters, el consumidor que importa
+un token arrastra los services del supplier (`@app/<supplier-bc>`) a su grafo de módulos —
+acoplamiento consumidor→implementación y riesgo de ciclo. Corolarios: un módulo adapter-only (sin
+ports propios — porque el port que implementa vive en `@aurora`, como `iam/account`, o en OTRO
+módulo de `@bridges`, como `o-auth/client` que implementa el port de `iam/client`) NO tiene
+superficie de consumo y por tanto NO lleva `index.ts` de módulo; y NO existen barrels de BC
+(`@bridges/<bc>/index.ts`) — la unidad de import es siempre `[bc]/[module]`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                                  | ¿Permitido? | Acción correcta                                                                                                    |
+| --- | ----------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| 1   | Un consumidor importa un port/token/helper puro: `from '@bridges/iam/permission'`                            | SÍ          | Forma canónica de consumo: el barrel del módulo solo contiene contratos, es seguro por construcción.                |
+| 2   | Un composition root importa un adapter: `from '@bridges/iam/permission/adapters'`                            | SÍ          | Forma canónica de wiring: sub-barrel público acotado (sancionado por HR-BARRELS-001, caso 2).                       |
+| 3   | Re-exportar un adapter desde el `index.ts` del módulo (`export * from './adapters'`)                        | **NO**      | Moverlo a `adapters/index.ts`. El barrel de consumo nunca arrastra implementación del supplier.                     |
+| 4   | Un handler/service de `@app/<consumer>` importa de `…/adapters`                                              | **NO**      | Inyectar el port por token (HR-BRIDGES-001). Si lo que necesita es un helper puro, exponerlo en el barrel del módulo. |
+| 5   | Crear o usar un barrel de BC (`@bridges/iam/index.ts`)                                                       | **NO**      | Importar del módulo concreto: `@bridges/iam/<module>` (o su `/adapters` desde un composition root).                 |
+| 6   | Módulo adapter-only con `index.ts` de módulo                                                                 | **NO**      | Eliminar el `index.ts`; el wiring importa de `…/adapters` y no hay superficie de consumo que exponer.               |
+| 7   | Helper público (función suelta sin DI) cuyo fichero vive bajo `adapters/`                                    | SÍ          | Re-export explícito en el `index.ts` del módulo (`export * from './adapters/validate-redirect-uri'`); no entra en `adapters/index.ts`. |
+| 8   | Un adapter de `@bridges/<supplier-bc>` importa el contrato de `@bridges/<otro-bc>` por su barrel de módulo   | SÍ          | Es el seam del bridge (el supplier implementa el port del consumidor): `o-auth/client/adapters/*` importa `from '@bridges/iam/client'`. |
+
+### Anchor patterns
+
+Un futuro guard (lint) debe vigilar:
+
+- Un `backend/src/@bridges/<bc>/<module>/index.ts` que contenga `export * from './adapters'` o un
+  re-export de un fichero `*.adapter` — adapter filtrado a la superficie de consumo (caso 3).
+- Un import `from '@bridges/<bc>/<module>/adapters'` en un fichero que NO sea
+  `@bridges/providers/*.bridge.ts`, `@bridges/bridges.module.ts` ni `@api/**/*.module.ts` —
+  implementación consumida fuera del wiring (caso 4).
+- Un fichero `backend/src/@bridges/<bc>/index.ts` — barrel de BC prohibido (caso 5).
+
+### Implementa
+
+- `backend/src/@bridges/iam/permission/index.ts` — superficie de consumo (`export * from './ports'`).
+- `backend/src/@bridges/iam/permission/adapters/index.ts` — superficie de wiring.
+- `backend/src/@bridges/o-auth/application/index.ts` — ports + helper puro público (`validate-redirect-uri`).
+- `backend/src/@bridges/iam/account/adapters/index.ts` — módulo adapter-only: sub-barrel de wiring sin barrel de módulo.
+- `scripts/harness-rules/lint-barrels.ts` — lint determinista de los anchor patterns de HR-BARRELS-001 y HR-BARRELS-002; superficies: `pnpm hr:lint-barrels` (full/staged), pre-commit staged (`.husky/pre-commit`), PostToolUse por-fichero (`.claude/hooks/lint-barrels.ts`).
+
+### Reglas relacionadas
+
+- **HR-BARRELS-001** — gobierna la FORMA del import (barrel vs deep-path); esta regla gobierna el CONTENIDO de cada barrel de `@bridges`.
+- **HR-BRIDGES-001** — la frontera cross-BC: el consumidor inyecta el port por token; esta regla garantiza que el barrel que le da el token no le cuele el adapter.
+- **HR-MODGRAPH-001** — el mismo riesgo (arrastrar un módulo entero vía barrel) que motivó el sub-barrel de ports de authentication.
+- **HR-PORTS-001** — los módulos adapter-only de `@bridges` implementan ports que viven en `@aurora`; por eso no tienen superficie de consumo propia.

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

@@ -0,0 +1,88 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-07-31
+keywords:
+  - cross-bc
+  - cross-bounded-context
+  - puente entre bounded contexts
+  - port
+  - adapter
+  - adaptador
+  - bridges
+  - dependency inversion entre BCs
+  - app no importa otro app
+paths:
+  - backend/src/@bridges/**
+---
+
+# Cross-BC bridges (ports y adapters)
+
+> **Glosario**:
+>
+> - **Consumer BC**: bounded context que necesita datos/operaciones de otro BC.
+> - **Supplier BC**: bounded context que ofrece esos datos/operaciones.
+> - **Port**: interface que declara el consumer en `@bridges/<consumer-bc>/`.
+> - **Adapter**: implementación del port, vive en `@bridges/<supplier-bc>/`.
+> - **`@bridges/<bc>/`**: cara EXTERNA del BC (contratos cross-BC). `@app/<bc>/`: cara INTERNA
+>   (handlers, services, repositories, models). Juntos forman el BC completo.
+
+---
+
+## HR-BRIDGES-001 — Cross-BC ports y adapters viven en @bridges/
+
+| Campo     | Valor                                                                                                 |
+| --------- | ----------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                              |
+| Severidad | `blocking`                                                                                            |
+| Origen    | spec `openspec/specs/cross-bc-ports/spec.md` (convención formalizada); supersede `feedback_cross_bc_adapter_location.md`, que toleraba adapters en `@app/` |
+
+### Enunciado
+
+Toda dependencia cross-BC se materializa bajo `backend/src/@bridges/<bc>/`, NUNCA bajo `@app/<bc>/`
+ni `@api/<bc>/`. `@bridges/<bc>/` es la cara externa del BC (los contratos cross-BC); `@app/<bc>/`
+es la interna (handlers, services, repositories). Juntos forman el BC completo. Gracias a esta
+separación, la regla **"ningún archivo bajo `@app/<bc>/` importa de otro `@app/<other-bc>/`"** pasa
+a ser ENFORCEABLE POR LINTER (un regex de una línea en eslint), algo imposible en la convención DDD
+canónica donde los adapters cross-BC viven en `@app` y violarían `@app → @app` por diseño. Aurora
+DIVERGE INTENCIONALMENTE del DDD literal de Evans/Vernon (que coloca el port con su consumer y el
+adapter con su supplier, ambos dentro del dominio): Catalyst, como meta-framework, trata la
+integración cross-BC como un concern separable y lo materializa en `@bridges/`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                  | ¿Permitido? | Acción correcta                                                                                                       |
+| --- | ------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| 1   | Declarar un port para que un consumer BC lea datos de otro BC                               | SÍ          | `@bridges/<consumer-bc>/<feature>/ports/<thing>.port.ts` + `<thing>.token.ts` (Symbol DI co-localizado).              |
+| 2   | Implementar ese port (adapter)                                                              | SÍ          | `@bridges/<supplier-bc>/<module>/adapters/<thing>.adapter.ts`, nombrado con prefijo del **supplier**, `@Injectable()`. |
+| 3   | Colocar el port en `@app/<consumer>/shared/ports/` o el adapter en `@app/<supplier>/.../infrastructure/adapters/` | **NO**      | Moverlos a `@bridges/<bc>/<feature>/`. Esa ubicación rompe la regla `@app → @app` enforceable por linter.             |
+| 4   | Que un handler/módulo de `@app/<consumer>` importe directamente de `@app/<supplier>`        | **NO**      | Inyectar el port por token (`@Inject(TOKEN)`); la resolución la sirve `BridgesModule` (`@Global`).                    |
+
+> **Aclaración aditiva al caso 1 (no deroga, no cambia el resultado `SÍ`, no crea id nueva):**
+> cuando el BC lector es un **BC de capacidad de plataforma** (p.ej. `tools`, no un BC de dominio
+> par como `iam` u `o-auth`) y el contrato es **consumer-agnostic** (todo método discrimina al
+> llamante SOLO por un parámetro tipo `entityType`, y el DTO devuelto es un snapshot mínimo sin
+> proyección específica de un consumidor concreto), el puerto y su token PUEDEN vivir en el
+> territorio del **supplier** (`@bridges/<supplier-bc>/<feature>/ports/`) en vez del consumidor —
+> variante open-host / published-language. El caso 1 sigue siendo `SÍ` sin cambios: el puerto
+> sigue bajo `@bridges/`, sin ningún import `@app → @app`. Precedentes: `TOOLS_CUSTOM_FIELD_ENTITY_REGISTRAR`
+> (write port) y `TOOLS_KEY_VALUE_CONFIG`; ejemplo trabajado: `TOOLS_CUSTOM_FIELD_DEFINITION_READER`
+> (`@bridges/tools/custom-field/ports/`). Ver skill `catalyst-cross-bounded-context-ports`
+> (sección "Platform-capability read port") y `openspec/specs/cross-bc-ports/spec.md`.
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- Cualquier `*.adapter.ts` o `*.port.ts` cross-BC bajo `backend/src/@app/**/infrastructure/adapters/**`
+  o `@app/**/ports/**`: ubicación incorrecta, deben vivir en `@bridges/`.
+- Un import en un archivo bajo `backend/src/@app/<bc>/**` que resuelva a `@app/<other-bc>/**` o
+  `@api/<other-bc>/**` (cross-`@app` directo): viola la separación; debe pasar por un port de
+  `@bridges/`.
+- Un `bridges.module.ts` que exporte clases de adapter o services concretos del supplier en lugar de
+  solo los Symbols (tokens).
+
+### Reglas relacionadas
+
+- **HR-PORTS-001** — el patrón ports/adapters como default para deps cross-layer `@aurora ↔ app`;
+  misma mecánica de dependency inversion, distinta frontera (framework↔app vs BC↔BC).

package/dist/templates/monorepo/cliter/harness-rules/dev-modes.md

@@ -0,0 +1,85 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-28
+keywords:
+  - solution mode
+  - modo solución
+  - framework mode
+  - modo framework
+  - yagni
+  - fix targeted
+  - parche específico
+  - loop defensivo
+  - defensive workaround
+  - catalyst-dev-mode
+paths:
+  - backend/src/@app/**
+  - frontend/src/app/**
+---
+
+# Modos de desarrollo (Solution vs Framework)
+
+> **Glosario**:
+>
+> - **Solution mode**: modo de desarrollo del proyecto (conmutable con `/catalyst-dev-mode`).
+>   Mentalidad "shortest path": consumir el framework, no diseñar para hipotéticos.
+> - **Framework mode**: modo para tocar el codegen o el package upstream. Mentalidad de diseño
+>   general (PR upstream, cambio de template).
+> - **YAGNI**: "You Aren't Gonna Need It" — no construir generalidad que no tiene caso de uso visible.
+
+---
+
+## HR-MODES-001 — Solution mode = YAGNI sobre el campo afectado
+
+| Campo     | Valor                                                                  |
+| --------- | ---------------------------------------------------------------------- |
+| Estado    | `active`                                                               |
+| Severidad | `informational`                                                        |
+| Origen    | auto-memory `feedback_solution_mode_yagni.md` (originSessionId fd21ff72) |
+
+### Enunciado
+
+En **Solution mode**, cuando un campo concreto sufre un bug, el fix es ESPECÍFICO a ese campo, no un
+loop defensivo genérico "por si en el futuro aparece otro caso similar". Generalizar a "todos los
+campos del mismo tipo por si acaso" añade superficie de bug y desorienta a un futuro lector que ve un
+guard genérico sin caso de uso visible. Si el bug es upstream y reaparecerá en más sitios, el camino
+correcto es **Framework mode**: un PR al package upstream o un cambio en el codegen, NO un workaround
+defensivo replicado en cada handler. YAGNI aplica específicamente a workarounds locales, casts, loops
+"por si acaso" y helpers prematuros.
+
+Ejemplo concreto: ante el bug de `Obj.diff` (sparse-array) sobre `scopeOptions`, el fix correcto
+fueron 3 líneas dirigidas al campo afectado, no un loop genérico sobre todas las keys del payload:
+
+```ts
+if ('scopeOptions' in dataToUpdate) {
+  dataToUpdate['scopeOptions'] = payload.scopeOptions;
+}
+```
+
+El fix genérico ("todos los arrays escalares por si acaso") habría sido trabajo de Framework mode:
+arreglar `Obj.diff` en el paquete framework, `packages/core-back`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                              | ¿Permitido? | Acción correcta                                                                                       |
+| --- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| 1   | Bug que afecta a un solo campo concreto                                  | SÍ          | Parchear ese campo por nombre, aunque "pique" que vengan más; mínimo número de líneas.                |
+| 2   | Bug upstream que reaparecerá en más sitios                              | SÍ          | Cambiar a Framework mode: PR al package upstream o cambio en el codegen. No workaround por handler.   |
+| 3   | Loop defensivo "por si acaso" sobre todos los campos en Solution mode    | **NO**      | Limitar el fix al campo afectado. La generalización es Framework mode, no Solution mode.              |
+
+### Anchor patterns
+
+Un futuro guard (o reviewer) debe vigilar:
+
+- Loops sobre `Object.keys(...)` / `Object.entries(...)` con `Array.isArray` + `JSON.stringify`
+  añadidos en un handler para "defender cualquier futuro caso" sin un caso de uso presente.
+- Helpers o guards nuevos cuya única justificación en el PR sea "por si en el futuro…".
+- Diffs que crecen mucho más allá del campo nombrado en el bug report mientras el modo activo es
+  Solution.
+
+### Reglas relacionadas
+
+- **HR-ACL-001** — corolario en tipos: Solution mode consume el tipo canónico y estrecha en el punto
+  de uso; las abstracciones defensivas (interfaces locales, double casts) son el mismo anti-patrón de
+  generalización prematura.

package/dist/templates/monorepo/cliter/harness-rules/docs-location.md

@@ -0,0 +1,67 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-09-10
+keywords:
+  - documentación de reglas
+  - rules documentation
+  - formato de regla
+  - rule format
+  - docs location
+  - duplicación
+paths:
+  - docs/business-rules/README.md
+  - docs/harness-rules/README.md
+detect:
+  pattern: '### Enunciado'
+  message: 'HR-DOCS-001 (blocking): el README de orientación de un catálogo de reglas no reproduce la plantilla de regla. El formato de regla vive en `.claude/skills/<catálogo>-guard/references/format.md` — edítalo ahí y enlaza desde el README, no lo pegues aquí.'
+---
+
+# Ubicación de la documentación de reglas
+
+> **Glosario**:
+>
+> - **README de orientación**: `docs/business-rules/README.md` y `docs/harness-rules/README.md`,
+>   un mapa de ~40 líneas (qué es el sistema, tabla de archivos, tabla de comandos, pointers). No es
+>   el hogar del formato de regla.
+> - **`references/format.md`**: el archivo de la skill guard (`business-rules-guard` o
+>   `harness-rules-guard`) donde vive el formato exacto de una regla — frontmatter, plantilla
+>   canónica, mezcla de idiomas, estado y severidad.
+
+---
+
+## HR-DOCS-001 — Sin plantilla de regla en el README de orientación
+
+| Campo     | Valor                                                                 |
+| --------- | ---------------------------------------------------------------------- |
+| Estado    | `active`                                                              |
+| Severidad | `blocking`                                                            |
+| Origen    | propuesta `split-rules-docs-by-reader` (design.md D1, D3)             |
+
+### Enunciado
+
+Los README de orientación de los catálogos (`docs/business-rules/README.md`,
+`docs/harness-rules/README.md`) no contienen la plantilla de regla ni contenido de formato: ese
+contenido vive en `references/format.md` de la skill guard correspondiente. El marcador
+`### Enunciado` es la primera sección de la plantilla canónica en ambos catálogos, así que su
+aparición en un README de orientación es evidencia mecánica de que la plantilla se ha vuelto a
+pegar ahí, reproduciendo un contenido que ya tiene un hogar único.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                    | ¿Permitido? | Acción correcta                                                                                   |
+| --- | ------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
+| 1   | Editar la tabla de archivos o la tabla de comandos del README                 | SÍ          | Editar directamente; es contenido propio del mapa de orientación.                                   |
+| 2   | Añadir o corregir un pointer a otro documento                                 | SÍ          | Editar directamente.                                                                                 |
+| 3   | Pegar la plantilla canónica de una regla (con su sección `### Enunciado`) en el README | **NO**      | Escribirla en `.claude/skills/<catálogo>-guard/references/format.md` y enlazar desde el README.     |
+| 4   | Copiar de vuelta al README una sección completa de `format.md` "por claridad" | **NO**      | El README enlaza a `format.md`; no reproduce su contenido.                                          |
+
+### Anchor patterns
+
+- El heading literal `### Enunciado` en contenido escrito a `docs/business-rules/README.md` o
+  `docs/harness-rules/README.md` — el mismo patrón que declara `detect.pattern`.
+
+### Reglas relacionadas
+
+- **HR-ACL-001** — mismo mecanismo de content-guard (detección de un patrón literal en escritura),
+  aplicado aquí a duplicación de documentación en vez de a un double cast.

package/dist/templates/monorepo/cliter/harness-rules/generated-code.md

@@ -0,0 +1,77 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-05-28
+keywords:
+  - archivo generado editable
+  - generated file editable
+  - aurora-catalyst-generated
+  - origin reconciliation
+  - reconciliación origin
+  - three-way merge
+  - content-hash
+  - catalyst generate force
+  - aurora infraestructura compartida
+paths:
+  - backend/src/@app/**
+  - backend/src/@api/**
+  - frontend/src/app/**
+---
+
+# Código generado y reconciliación `.origin`
+
+> **Glosario**:
+>
+> - **`@aurora-catalyst-generated`**: cabecera que marca un archivo como salida de `catalyst generate`.
+>   Es metadata de origen, NO una prohibición de edición.
+> - **`.origin`**: snapshot de la última salida del template para ese archivo.
+> - **Three-way merge**: comparación en regen entre archivo editado actual, snapshot `.origin` y
+>   nueva salida del template.
+> - **`@aurora/`**: infraestructura compartida hand-written que el proyecto posee; tampoco es
+>   "no tocar".
+
+---
+
+## HR-CODEGEN-001 — Generated files son editables; .origin reconcilia
+
+| Campo     | Valor                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                           |
+| Severidad | `blocking`                                                                                         |
+| Origen    | auto-memory `feedback_generated_editable_and_ports_default.md` (parte 1, originSessionId 93db189a) |
+
+### Enunciado
+
+Los archivos con cabecera `@aurora-catalyst-generated` SON editables a mano. El sistema `.origin` +
+content-hash hace un three-way merge en cada regen: el archivo editado actual vs el snapshot
+`.origin` (última salida del template) vs la nueva salida del template. Si tus ediciones no
+conflictan, **sobreviven**; si conflictan, se deja un `.origin.ts` al lado para reconciliación
+manual. La cabecera NO es una prohibición. `@aurora/` tampoco es "no tocar": es infraestructura
+compartida hand-written que el proyecto posee y mantiene.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                   | ¿Permitido? | Acción correcta                                                                                                                |
+| --- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | Editar a mano un archivo con cabecera `@aurora-catalyst-generated`                           | SÍ          | Editar en sitio; `.origin` reconcilia en la próxima regen (`--force` deja `.origin.ts` solo si hay conflicto real).            |
+| 2   | Crear un módulo/barrel paralelo para no tocar el archivo generado                            | **NO**      | Editar el generado directamente. Ver **HR-MODULES-001** (Shadow Module Antipattern).                                           |
+| 3   | Una op hand-tuned diverge de lo que emitiría el template (p. ej. query argless/minimal)      | SÍ          | Ponerla en el archivo generado natural y reconciliar la propuesta del template en la regen `--force`.                          |
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- Comentarios o PRs que justifiquen una estructura nueva alegando "el archivo es
+  `@aurora-catalyst-generated`, no se puede tocar": razonamiento incorrecto que suele preceder a un
+  shadow module (HR-MODULES-001).
+- Edits bajo `backend/src/@aurora/**` o `frontend/src/@aurora/**` rechazados con el argumento de que
+  `@aurora` es "no tocar": es infraestructura del proyecto, sí se edita.
+- Archivos `.origin.ts` sin reconciliar acumulándose en el árbol (señal de conflictos de regen
+  pendientes, no de prohibición).
+
+### Reglas relacionadas
+
+- **HR-MODULES-001** — el corolario directo: nunca crear un módulo paralelo para evitar editar el
+  generado.
+- **HR-PORTS-001** — cuando la edición del generado implica una dep cross-layer `@aurora ↔ app`,
+  resolverla con port + adapter.