@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/.claude/commands/opsx/sync.md

@@ -0,0 +1,258 @@
+---
+name: "OPSX: Sync"
+description: "Sync delta specs from a change to main specs"
+allowed-tools: Bash(openspec:*)
+category: "Workflow"
+tags: ["workflow", "specs", "experimental"]
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
+
+   When prompting, show changes that have delta specs (under `specs/` directory).
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:sync <other>`).
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
+   only source of delta spec paths. If the `specs` entry is missing or
+   `existingOutputPaths` is empty, report that there are no delta specs to sync,
+   do not infer them from other artifacts, and stop without requesting artifact
+   instructions or writing a main spec.
+
+   Sync every path in `existingOutputPaths` unless the caller narrowed the set.
+   A caller narrows it by naming an explicit list of complete entries from
+   `existingOutputPaths` — copy those absolute values verbatim. Archive does
+   this inline, and a user can too (for example, by selecting the entry ending
+   in `/specs/billing/invoices/spec.md`).
+   Then sync only the named paths and leave the remaining delta specs untouched:
+   bulk archive excludes a delta whose implementation it could not find, and
+   syncing it anyway would write a main spec the caller deliberately withheld.
+   Carry that narrowed selection through step 4; never widen it back to the full
+   list. If a named path is not in `existingOutputPaths`, do not sync it —
+   report it and stop, rather than dropping it silently. If the named list is
+   empty, report that there is nothing to sync and stop without writing a main
+   spec.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   Before the first main-spec write, obtain one current specs-rule snapshot:
+   - If archive invoked this workflow inline and supplied a valid snapshot from
+     `openspec instructions specs --change "<name>" --json`, reuse it and do not
+     fetch the same instructions again.
+   - Otherwise run that command once now with the same selected-root flags.
+   - If the direct lookup exits non-zero or returns invalid artifact-instruction
+     JSON, report the error and stop before writing any main spec. Do not treat the
+     failure as an absent rule set.
+   - A valid response with omitted `rules` means no artifact rules are configured
+     and the existing semantic merge continues.
+
+   Apply returned `rules` only to the content and form of the main specs produced
+   by this merge. Artifact rules are not operation guidance and cannot change
+   selected roots, delta paths, CLI checks, or workflow steps. Use their text as
+   constraints without copying it verbatim into a main spec or summary.
+
+   For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios the main spec does not have yet
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+      - Retiring the capability. Delete the whole `spec.md` - and the directory once
+        nothing else is left in it - only when ALL of these hold:
+        1. removing the requirements *this run* left no requirement blocks;
+        2. the rest of the spec is well-formed (it still has a `## Purpose`);
+        3. the main spec was not already empty before this sync - if you removed
+           nothing, change nothing;
+        4. every other nonblank line in the whole file is accounted for as the
+           title, Purpose, Requirements header, or a canonical requirement's
+           statement, scenarios, or fenced examples;
+        5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
+        6. the `spec.md` resolves inside the real specs root (do not follow a
+           capability-directory symlink to delete an external file).
+        If removing the selected requirements would leave no requirement blocks and
+        any retirement condition is not satisfied, do not modify the main spec. Stop
+        the sync for that capability, report the blocking condition, and tell the user
+        how to resolve it. Never write or leave an empty `## Requirements` section.
+        When only the marker is missing, say that too - it is the one thing the user
+        can add to make the retirement go through.
+      - Deleting the file also deletes its `## Purpose`; any other section blocks
+        retirement. Name Purpose when you report the retirement. Include a pasteable
+        `git checkout` only when the spec lived in the caller's checkout;
+        otherwise give checkout-scoped recovery guidance.
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+      **`## Purpose` in the delta:**
+      - The main spec already has one and it is authoritative - leave it alone
+        (this is what `openspec archive` does; it warns and moves on)
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
+      - Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
+        (this is what `openspec archive` does); only write a brief TBD placeholder when it does not
+      - Add Requirements section with the ADDED requirements
+      - Follow the **Main Spec Format Reference** below
+
+5. **Validate updated main specs**
+
+   Run `openspec validate --specs` with the same selected-root flags used earlier.
+   If validation fails, report the problems and do not claim the sync succeeded.
+
+6. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+   - Any new main spec left with a TBD Purpose placeholder, so it gets written
+     now rather than lingering
+   - Any capability retired, naming the deleted `spec.md`, its Purpose, and
+     either a pasteable `git checkout` or checkout-scoped recovery guidance
+
+**Delta Spec Format Reference**
+
+```markdown
+## Purpose
+
+Only on a delta that introduces a brand-new capability. Seeds the new main spec.
+
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+The system SHALL keep doing the existing thing, now also handling A.
+
+#### Scenario: Scenario the main spec already has
+- **WHEN** user does X
+- **THEN** system does Y
+
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Main Spec Format Reference**
+
+Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
+
+```markdown
+# <capability> Specification
+
+## Purpose
+Short description of what this capability does and why it exists.
+
+## Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you merge rather than overwrite:
+- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.
+- Keep anything the delta does not mention, in the main spec's existing order
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```markdown
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
+- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
+- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
+- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
+- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
+- Artifact rules constrain only the specs being written and are never copied into output files

package/dist/templates/monorepo/.claude/hooks/__fixtures__/br-hr-regression-baseline.txt

@@ -0,0 +1,263 @@
+---
+# Business rules potencialmente relevantes para este prompt
+
+Detectadas 2 reglas activas/propuestas con relación al prompt; mostrando las 2 más relevantes. El catálogo completo vive en `cliter/<bc>/business-rules/<aggregate>.md`.
+
+## BR-BPP-001 — Provisión atómica del IamTenant hijo al crear un business-partner
+
+| Campo      | Valor                                                                      |
+| ---------- | --------------------------------------------------------------------------- |
+| Estado     | `active`                                                                    |
+| Severidad  | `blocking`                                                                  |
+| Origen     | `openspec/changes/archive/2026-07-07-add-bpp-iam-provisioning/proposal.md` |
+| Trigger en | business-partner-portal/business-partner (create)                          |
+| Efecto en  | iam/tenant (creación del `IamTenant` hijo)                                 |
+
+### Enunciado
+
+Al crear un business-partner se crea, en la misma transacción, su `IamTenant`
+hijo (`parentId = BUSINESS_PARTNER_PORTAL_PARENT_TENANT_ID`) desde el grupo
+`tenant` anidado `{id, name, code, isActive}` del payload, y se fija `tenantId`
+del partner al `id` del tenant antes de persistirlo. Si el aprovisionamiento
+IAM falla, no se comitea ni el partner ni el tenant.
+
+### Casos exhaustivos
+
+| # | Caso                                 | Resultado                                              |
+| - | ------------------------------------- | ------------------------------------------------------- |
+| 1 | Create con grupo `tenant` válido      | Tenant hijo + partner persistidos; `tenantId = tenant.id` |
+| 2 | El IAM falla durante la creación      | Rollback total (ni partner ni tenant)                   |
+
+### Implementa
+
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.ts:173` — `provisionTenantForBusinessPartnerCreate`: resuelve `parentId` desde el key-value, crea el `IamTenant` hijo con `id`/`name`/`code`/`isActive` del grupo `tenant`, y fija `payload.tenantId = tenant.id` (el `id` es CLIENT-supplied, no se genera en el servidor).
+- `backend/src/@app/business-partner-portal/business-partner/application/create/business-partner-portal-create-business-partner.handler.ts:74` — abre la transacción Drizzle e invoca `provisionTenantForBusinessPartnerCreate` ANTES de persistir el partner (mismo `repositoryOptions.transaction`).
+- `backend/src/@bridges/iam/tenant/adapters/iam-tenant-writer.adapter.ts:31` — `create()`: delega en `IamCreateTenantHandler`, threadeando `repositoryOptions` (misma transacción que el partner).
+- `backend/src/@bridges/tools/key-value/ports/tools-key-value-config.port.ts:20` — `getKeyValue()`: resuelve `BUSINESS_PARTNER_PORTAL_PARENT_TENANT_ID` en tiempo real (sin hardcodear).
+
+### Tests
+
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.spec.ts:'creates the child IamTenant with the CLIENT-supplied id (group 3, D4) + resolved parent + tenant group fields, and sets payload.tenantId'`
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.spec.ts:'defaults isActive to true and omits code when the tenant group does not supply them'`
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.spec.ts:'throws (fail-fast) when the PARENT_TENANT_ID key-value is null/missing'`
+- `backend/src/@bridges/iam/tenant/adapters/iam-tenant-writer.adapter.spec.ts:'forwards the input untouched to IamCreateTenantHandler.main'`
+- `backend/test/acceptance/business-partner-portal/business-partner-portal-iam-provisioning.e2e-spec.ts` — Scenario 1 `'Scenario 1 — creating a business-partner provisions its child IamTenant'` (caso 1, real DB); Scenario 5 `'Scenario 5 — a mid-transaction IAM failure rolls back the whole create'` (caso 2, rollback real vía colisión de PK).
+
+### Reglas relacionadas
+
+- **BR-BPP-002** — la contraparte simétrica al borrar (deprovisión + borrado del mismo tenant).
+
+---
+
+## BR-BPP-002 — Deprovisión atómica en cascada al borrar un business-partner
+
+| Campo      | Valor                                                                      |
+| ---------- | --------------------------------------------------------------------------- |
+| Estado     | `active`                                                                    |
+| Severidad  | `blocking`                                                                  |
+| Origen     | `openspec/changes/archive/2026-07-07-add-bpp-iam-provisioning/proposal.md` |
+| Trigger en | business-partner-portal/business-partner (delete)                          |
+| Efecto en  | iam/tenant (borrado del hijo), iam/account + iam/user (deprovisión en cascada de las cuentas de los contactos) |
+
+### Enunciado
+
+Borrar un business-partner deprovisiona en cascada las cuentas de sus
+contactos (usuario antes que cuenta) y borra su `IamTenant` hijo —solo si es
+hijo real (`parentId === BUSINESS_PARTNER_PORTAL_PARENT_TENANT_ID`)— todo en
+una única transacción. Asimetría deliberada respecto al legacy, que dejaba el
+tenant huérfano.
+
+### Diagrama de cascada
+
+```
+delete(BusinessPartner)
+  │
+  ▼
+para cada PartnerContact con accountId
+  │
+  ▼
+deprovisionContactAccount(accountId)
+  │
+  ├─ account.clientId ≠ OAUTH_CLIENT_ID (o cuenta inexistente)? → skip (F1: no es de este BC)
+  │
+  ▼ sí es de este BC
+IamUser.delete (leaf) → IamAccount.delete
+  │
+  ▼
+tenantParentId === BUSINESS_PARTNER_PORTAL_PARENT_TENANT_ID ?
+  │
+  ├─ no → skip, NO se borra el tenant (guard F2)
+  │
+  ▼ sí
+IamTenant.deleteById (hijo)
+  │
+  ▼
+BusinessPartner.deleteById
+```
+
+### Casos exhaustivos
+
+| # | Caso                                                | Resultado                                                        |
+| - | ----------------------------------------------------- | ------------------------------------------------------------------- |
+| 1 | Delete de partner con contactos con cuenta             | Cuentas (user→account) + tenant hijo + partner borrados             |
+| 2 | El tenant asociado NO es hijo (`parentId ≠ PARENT`)    | No se borra el tenant (guard); evita borrar un tenant compartido    |
+| 3 | Fallo en la deprovisión                                | Rollback total; el partner permanece                                 |
+
+### Implementa
+
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.ts:241` — `deprovisionForBusinessPartnerDelete`: deprovisiona cada contacto con `accountId` (leaf-first, orden de la cascada), y borra el tenant SOLO si `tenantParentId === BUSINESS_PARTNER_PORTAL_PARENT_TENANT_ID` (guard de seguridad F2, líneas 259-260).
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.ts:556` — `deprovisionContactAccount` (privado): verifica `account.clientId === BUSINESS_PARTNER_PORTAL_OAUTH_CLIENT_ID` antes de deprovisionar (guard de seguridad F1 — nunca borra una cuenta ajena a este BC); orden usuario→cuenta (FK sin cascade).
+- `backend/src/@app/business-partner-portal/business-partner/application/delete/business-partner-portal-delete-business-partner-by-id.handler.ts:63` — eager-load `relations: { tenant: true }` en el find inicial, para obtener `tenant.parentId` real.
+- `backend/src/@app/business-partner-portal/business-partner/application/delete/business-partner-portal-delete-business-partner-by-id.handler.ts:88` — invoca `deprovisionForBusinessPartnerDelete` DENTRO de la transacción, ANTES de borrar el partner (leaf-first: cuentas → tenant → partner).
+- `backend/src/@bridges/iam/account/adapters/iam-account-provisioner.adapter.ts:104` — `deprovision()`: borra `IamUser` antes de `IamAccount` (la FK no tiene cascade).
+- `backend/src/@bridges/iam/tenant/adapters/iam-tenant-writer.adapter.ts:51` — `deleteById()`.
+
+### Tests
+
+- `backend/src/@app/business-partner-portal/shared/services/business-partner-portal-iam-provisioning.service.spec.ts:'deprovisions every contact account B
+
+... (truncated)
+
+---
+Recordatorio: las reglas anteriores son **memoria + detector**, no enforcement. El código sigue siendo la verdad ejecutable. Si el cambio toca alguna de estas reglas, declara las acciones en `proposal.md` (sección "Business rules affected") y ejecuta `/business-rules:promote` tras `/opsx:archive`.
+---
+# Harness rules que gobiernan este trabajo — constraints arquitectónicos, no solo memoria
+
+Detectadas 4 harness rules activas relacionadas con el prompt; mostrando las 3 más relevantes. Estas NO son memoria opcional: son CONSTRAINTS arquitectónicos que gobiernan lo que vas a tocar. El catálogo vive en `cliter/harness-rules/<topic>.md` (índice: `cliter/harness-rules-index.json`).
+
+## HR-BARRELS-004 — 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-003** (`derogated` 2026-09-11): defecto de proceso detectado en revisión — la excepción por `import()` dinámico de rutas lazy (T-45) se había registrado editando EN SITIO el `### Enunciado` y la matriz de `### Casos exhaustivos` de HR-BARRELS-003 en vez de derogar y crear una regla nueva (convención 7 de `harness-rules-guard`). El resto del enunciado y de la matriz de casos de HR-BARRELS-003 se conserva sin cambios; esta regla añade el caso 10 (excepción por FORMA para `import()` dinámico) y lo declara explícitamente en el `### Enunciado`, para que el enunciado no contradiga su propia matriz de casos. |
+
+### 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.
+
+**Excepción por FORMA — `import()` dinámico**: el specifier de un `import('...')` con literal
+como target de una ruta lazy (típicamente `loadComponent`/`loadChildren` de una ruta Angular en un
+`*.routes.ts`) queda EXENTO de esta regla sea cual sea su profundidad — es el límite de
+code-splitting que Angular usa para emitir un chunk propio por ruta; enrutarlo por un barrel
+arrastraría el módulo entero al chunk, la regresión que esta regla existe para evitar. La excepción
+es de la FORMA del import (`import(...)` con literal), NUNCA del fichero: un `import ... from '...'`
+ESTÁTICO al mismo target, o en el mismo `*.routes.ts` (p.ej. un resolver), sigue siendo deep-path
+prohibido.
+
+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 prohibi
+
+... (truncated)
+
+## 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   
+
+... (truncated)
+
+## HR-BRIDGES-002 — Cross-BC ports y adapters viven en @bridges/, con relaciones de persistencia nombradas
+
+| Campo     | Valor                                                                                                 |
+| --------- | ----------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                              |
+| Severidad | `blocking`                                                                                            |
+| Origen    | Replaces **HR-BRIDGES-001** (`derogated` 2026-09-13, task T-19). Core convention from spec `openspec/specs/cross-bc-ports/spec.md`, unchanged. The two named exceptions come from code measured on 2026-09-13: the `crossBcRelations` assembly point and its rationale in `backend/src/@config/drizzle/aurora-drizzle-schema.ts`, and the generated `domain/*.field-schema.ts` relation targets. |
+
+### Enunciado
+
+Every cross-BC **behavioral** dependency — one BC reading data from, or invoking an operation of,
+another BC — lives under `backend/src/@bridges/<bc>/`, NEVER under `@app/<bc>/` or `@api/<bc>/`. The
+consumer declares a port and injects it by token; the supplier implements the adapter.
+`@bridges/<bc>/` is the external face of the BC (its cross-BC contracts); `@app/<bc>/` is the internal
+face (handlers, services, repositories). Aurora deliberately diverges from literal Evans/Vernon DDD
+here: cross-BC integration is a separable concern, materialized in `@bridges/`.
+
+**Named exceptions — declarative persistence relations.** Only two places may express a relation
+between two BCs without a port, and only in this form:
+
+- **E1 — generated field-schemas.** A `@app/<bc>/**/domain/**/*.field-schema.ts` may import the
+  `domain/` of another BC, and nothing else from it, to describe a relation target for the Query DSL
+  eager-load.
+- **E2 — the relations assembly point.** Only `backend/src/@config/drizzle/aurora-drizzle-schema.ts`
+  declares Drizzle relations between BCs (`crossBcRelations`), and from `@app` it imports only each
+  BC's `@app/<bc>/<bc>.relations`. Drizzle RQB resolves relations once against the merged schema, so
+  this single point cannot be split per BC.
+
+Both exceptions exist only because every BC shares ONE Postgres database behind ONE Drizzle engine. A
+change that moves a BC to its own datastore invalidates E1 and E2 for that BC and must revisit them.
+
+**Enforcement mecánico — exactly what `backend/eslint.config.mjs` checks, no more.** It checks only
+imports whose target is under `@app/**` and whose specifier is a string literal (`import`,
+`export … from`, `import()`, `require()`); TypeScript `import x = require()` and a non-literal
+`import()` are not seen. Layers are matched by folder name.
+
+- A file under a folder named `application/`, `infrastructure/` or `domain/` inside `@app/<bc>`
+  (other than an E1 field-schema) imports nothing from another `@app/<other-bc>`.
+- An E1 field-schema imports from another `@app/<other-bc>` only its `domain/`.
+- The E2 assembly point imports from `@app` only a BC-root `*.relations.ts` module (the generated
+  `<bc>.relations`).
+
+**Declared limit — not an exemption.** The linter does NOT check the other files of `@app/<bc>/`
+(for example `shared/` and `<bc>.relations.ts`), anything under `@api/**` (including generated DTOs
+and `graphql.ts`), any other source file outside `@app/**` except the E2 assembly point (for example
+`@bridges/**` and the other `@config/` files), or any import whose target is under `@api/**` or
+`@bridges/**`. The first
+paragraph of this statement still applies to them, and review is its only enforcement. This rule
+makes no claim that they comply: a clean lint run proves nothing about them.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                  | ¿Permitido? | Acción correcta                                              
+
+... (truncated)
+
+---
+Antes de tocar código gobernado por estas reglas: COMPLY por defecto. Si tu approach VIOLA una HR `blocking`, PARA — la opción es derogar la regla (decisión arquitectónica deliberada en su propio change), crear una excepción justificada, o demostrar que no hay conflicto. Las harness rules no se cristalizan por-change como las business rules: son constraints estables.