@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

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

@@ -0,0 +1,211 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-09-13
+keywords:
+  - cross-bc
+  - cross-bounded-context
+  - puente entre bounded contexts
+  - port
+  - adapter
+  - adaptador
+  - bridges
+  - dependency inversion entre BCs
+  - app no importa otro app
+  - crossBcRelations
+  - aurora-drizzle-schema
+paths:
+  - backend/src/@bridges/**
+  - backend/src/@config/drizzle/aurora-drizzle-schema.ts
+  - backend/src/@app/**/domain/**/*.field-schema.ts
+---
+
+# 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    | `derogated`                                                                                           |
+| 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/`. Superseded by **HR-BRIDGES-002** (task T-19, see `### Derogación`). |
+
+### 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).
+- **HR-BRIDGES-002** — active replacement since 2026-09-13 (see `### Derogación`).
+
+### Derogación
+
+**2026-09-13** (task T-19): two statements of this rule are false against the code and could not be
+fixed by an in-place edit. First, "Toda dependencia cross-BC se materializa bajo `@bridges/`" is
+contradicted by the declarative cross-BC persistence relations the generator emits: 17 imports from
+`domain/*.field-schema.ts` into another BC's `domain/`, and the `crossBcRelations` block of
+`backend/src/@config/drizzle/aurora-drizzle-schema.ts` (the single, irreducible assembly point).
+Neither was governed by any rule; the `domain/` exemption lived only in an ESLint comment. Second,
+the claim that "ningún archivo bajo `@app/<bc>/` importa de otro `@app/<other-bc>/`" is linter
+enforceable did not hold: the linter only checked `application/` and `infrastructure/`. Replaced by
+**HR-BRIDGES-002**, which keeps the core unchanged, names both exceptions, and states exactly what
+the linter enforces and what it does not.
+
+---
+
+## 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                                                                                                       |
+| --- | ------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| 1   | Declare a port so a consumer BC can read data from another BC                               | SÍ          | `@bridges/<consumer-bc>/<feature>/ports/<thing>.port.ts` + `<thing>.token.ts` (co-located DI Symbol).                 |
+| 2   | Implement that port (adapter)                                                               | SÍ          | `@bridges/<supplier-bc>/<module>/adapters/<thing>.adapter.ts`, named with the **supplier** prefix, `@Injectable()`.   |
+| 3   | Put the port in `@app/<consumer>/shared/ports/` or the adapter in `@app/<supplier>/.../infrastructure/adapters/` | **NO**      | Move them to `@bridges/<bc>/<feature>/`.                                                                               |
+| 4   | A handler/module of `@app/<consumer>` imports directly from `@app/<supplier>`               | **NO**      | Inject the port by token (`@Inject(TOKEN)`); `BridgesModule` (`@Global`) serves the resolution.                      |
+| 5   | A generated `domain/*.field-schema.ts` imports another BC's `domain/` barrel to name a relation target (E1) | SÍ          | Keep it: it is the generator's relation description, reintroduced on every regen.                                     |
+| 6   | A field-schema imports another BC's handlers, services, `shared/` or root barrel; or a non-field-schema `domain/` file imports another BC | **NO**      | A relation target needs only the other BC's `domain/`; any behavior goes through a `@bridges/` port.                  |
+| 7   | Declare a relation between two BCs' tables in `crossBcRelations` of `aurora-drizzle-schema.ts` (E2) | SÍ          | Keep it there; the generator upserts entries, and hand edits are reconciled through `.origin` (HR-CODEGEN-001).       |
+| 8   | Declare a cross-BC Drizzle relation anywhere else (a `<bc>.relations.ts`, `@bridges/`, another `@config/` file), or import from `@app` anything other than `<bc>.relations` into the assembly point | **NO**      | Move the relation to E2's `crossBcRelations`; import other BCs' schemas only through `<bc>.relations`.                |
+
+> **Aclaración aditiva al caso 1, carried over unchanged from HR-BRIDGES-001:** when the reading BC is
+> a **platform-capability BC** (e.g. `tools`, not a peer domain BC like `iam` or `o-auth`) and the
+> contract is **consumer-agnostic** (every method discriminates the caller ONLY by a parameter such as
+> `entityType`, and the returned DTO is a minimal snapshot with no consumer-specific projection), the
+> port and its token MAY live in the **supplier's** territory (`@bridges/<supplier-bc>/<feature>/ports/`)
+> — open-host / published-language variant. Case 1 stays `SÍ`: the port is still under `@bridges/`,
+> with no `@app → @app` import. Precedents: `TOOLS_CUSTOM_FIELD_ENTITY_REGISTRAR` (write port) and
+> `TOOLS_KEY_VALUE_CONFIG`; worked example: `TOOLS_CUSTOM_FIELD_DEFINITION_READER`
+> (`@bridges/tools/custom-field/ports/`). See skill `catalyst-cross-bounded-context-ports` (section
+> "Platform-capability read port") and `openspec/specs/cross-bc-ports/spec.md`.
+
+### Anchor patterns
+
+A guard must watch:
+
+- Any cross-BC `*.adapter.ts` or `*.port.ts` under `backend/src/@app/**/infrastructure/adapters/**` or
+  `backend/src/@app/**/ports/**`: wrong location, they belong in `@bridges/`.
+- An import in `backend/src/@app/**` or `backend/src/@api/**` that resolves to another BC's `@app/` or
+  `@api/` — linted only for `@app/` targets from the three layers above; review for the rest
+  (declared limit).
+- An import in `backend/src/@app/**/domain/**/*.field-schema.ts` that resolves to another BC outside
+  its `domain/`.
+- A relation between two BCs declared outside `backend/src/@config/drizzle/aurora-drizzle-schema.ts`.
+- A `bridges.module.ts` that exports adapter classes or concrete supplier services instead of only the
+  Symbols (tokens).
+
+### Implementa
+
+- `backend/eslint.config.mjs` — the `boundaries/element-types` block that implements the
+  "Enforcement mecánico" list, and nothing beyond it.
+- `backend/src/@config/drizzle/aurora-drizzle-schema.ts` — E2, the `crossBcRelations` assembly point.
+
+### Reglas relacionadas
+
+- **HR-BRIDGES-001** — derogated rule this one replaces; same core, without the named exceptions and
+  with an enforcement claim that did not hold (see its `### Derogación`).
+- **HR-PORTS-001** — ports/adapters as the default for cross-layer deps `@aurora ↔ app`; same
+  dependency-inversion mechanics, different boundary (framework↔app vs BC↔BC).
+- **HR-CODEGEN-001** — E1 and E2 are generator-owned; hand edits are reconciled through `.origin`.

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-artifacts.md

@@ -0,0 +1,104 @@
+---
+scope: project
+bounded_contexts: []
+last_updated: 2026-09-16
+keywords:
+  - artefacto generado
+  - generated artifact
+  - salida compilada
+  - compiled output
+  - dist versionado
+  - tracked dist
+  - puerta de deriva
+  - drift gate
+  - espejo del packager
+  - packager mirror
+  - prepare on install
+paths:
+  - scripts/packager/**
+  - scripts/rebuild-core-packages.sh
+---
+
+# Artefactos generados: seguidos con puerta, o no seguidos
+
+> **Glosario**:
+>
+> - **Artefacto generado**: cualquier fichero que una herramienta produce a partir de otro fichero
+>   del repositorio — salida de `tsc`, de `ng-packagr`, de `scripts/packager/publish.mjs`.
+> - **Seguido**: presente en el índice de git (`git ls-files` lo lista), con historial propio.
+> - **Puerta de deriva**: un paso de CI que REGENERA el artefacto y exige que
+>   `git status --porcelain` salga vacío sobre su ruta.
+> - **Consumidor externo**: algo que necesita el artefacto sin poder construirlo, por no tener las
+>   dependencias de desarrollo a mano.
+
+Esta regla NO habla de los ficheros con cabecera `@aurora-catalyst-generated` bajo `@app`/`@api`:
+esos son editables a mano y los reconcilia `.origin` — ver **HR-CODEGEN-001**. Aquí se trata de
+salida que nadie edita, solo se produce.
+
+> **Límite de la búsqueda `byPath`**: el esquema del catálogo solo admite rutas bajo
+> `backend|frontend|cliter|scripts|docs` (`docs/_catalog-schema-base.json`), así que
+> `packages/**`, `.github/workflows/**` y los `.gitignore` NO se pueden declarar aquí aunque la
+> regla los gobierne. Se llega a esta regla por `byKeyword` (`dist versionado`, `tracked dist`,
+> `puerta de deriva`, `artefacto generado`), no por la ruta del fichero que estés tocando.
+
+---
+
+## HR-ARTIFACTS-001 — Un artefacto generado no se versiona sin puerta de deriva
+
+| Campo     | Valor                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------- |
+| Estado    | `active`                                                                                                |
+| Severidad | `informational`                                                                                         |
+| Origen    | sesión 2026-09-16: 816 ficheros de `packages/core-back/dist` seguidos sin puerta; PR #234 los desindexa |
+
+### Enunciado
+
+Un artefacto generado está en UNO de dos estados, y el tercero está prohibido:
+
+1. **No seguido.** Es el estado por defecto. Lo produce la instalación (`"prepare": "pnpm run build"`
+   del propio paquete) o un paso de build bajo demanda. Su ruta está en un `.gitignore` que se
+   cumple de verdad.
+2. **Seguido CON puerta de deriva.** Solo cuando un consumidor externo lo necesita sin poder
+   construirlo. Entonces CI regenera el artefacto en cada pull request y falla si queda alguna
+   diferencia.
+
+**Prohibido: seguido SIN puerta.** Son dos copias de la misma cosa dentro de git y nada que
+compruebe que siguen coincidiendo. La deriva no avisa: aparece como un error de tipos en el
+consumidor sobre un símbolo que está a la vista en el código fuente.
+
+Un `.gitignore` NO es la puerta, ni prueba el estado 1. Git no desindexa lo que ya estaba dentro
+cuando se escribió la regla, así que una ruta puede estar ignorada y seguida a la vez, durante años,
+sin que nada lo señale. El estado se comprueba con `git ls-files <ruta> | wc -l`, nunca leyendo el
+`.gitignore`.
+
+### Casos exhaustivos
+
+| #   | Situación                                                                                          | ¿Permitido? | Acción correcta                                                                                                                                                              |
+| --- | -------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | Salida de build de un paquete del workspace que solo consumen este repo, CI y los slots             | NO seguirla | Dejar que el `prepare` del paquete la produzca en cada `pnpm install`. Es el caso de `packages/core-back/dist` y `packages/core-front/dist`.                                    |
+| 2   | Espejo que un consumidor externo lee sin construir nada                                             | SÍ, con puerta | Seguirlo Y añadir el paso de CI que lo regenera y exige `git status --porcelain` vacío. Es el caso de `packages/cli/src/templates/{backend,frontend,monorepo}`.               |
+| 3   | Seguir un artefacto "para que no haya que construirlo" sin añadir puerta                            | **NO**      | O se justifica un consumidor externo y se añade la puerta, o no se sigue. La comodidad no es una de las dos condiciones.                                                       |
+| 4   | Añadir la ruta al `.gitignore` y dar por hecho que ya no se versiona                                | **NO**      | Medir con `git ls-files`. Si devuelve ficheros, hace falta además `git rm -r --cached <ruta>`.                                                                                  |
+| 5   | Desindexar un artefacto que los consumidores resuelven en tiempo de ejecución                        | SÍ, con red | El commit BORRA esos ficheros del disco de todo el mundo sin tocar ninguna fuente. Hace falta que algo los reconstruya al traerlo — en este repo, `scripts/rebuild-core-packages.sh` desde `post-merge`/`post-checkout`. |
+| 6   | Añadir una puerta de deriva que corra fuera de pull request                                          | **NO**      | Las puertas de este repositorio corren en PR. Una comprobación posterior al merge deja una ventana en la que `main` ya está derivada, y nadie sabría leerla cuando falle.      |
+
+### Anchor patterns
+
+Un futuro guard debe vigilar:
+
+- Una ruta que aparezca a la vez en un `.gitignore` y en `git ls-files`. Es el estado prohibido, y es
+  silencioso: así estuvieron los 816 ficheros de `packages/core-back/dist`.
+- Un pull request que añada salida de build al índice sin tocar `.github/workflows/`. Seguir sin
+  puerta.
+- Una propuesta que resuelva una deriva construyendo en `main` después del merge, o con un bot que
+  empuje el artefacto regenerado. Caso 6.
+- Un `git rm -r --cached` sobre un artefacto que se resuelve en tiempo de ejecución, sin nada que lo
+  reconstruya al hacer `pull`. Caso 5.
+
+### Reglas relacionadas
+
+- **HR-CODEGEN-001** — el otro sentido de "generado": ficheros con cabecera
+  `@aurora-catalyst-generated` que SÍ se editan a mano y reconcilia `.origin`. Esta regla no los
+  gobierna.
+- **HR-DOCS-001** — misma familia de disciplina: un artefacto con un sitio declarado y una
+  comprobación que lo sostiene.

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.

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

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