@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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,251 @@
+---
+# 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-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                                                                            |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ----------- | -----------------------------------------------------------------
+
+... (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-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-boun
+
+... (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.