@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/application/.claude/skills/catalyst-schema-migrations/SKILL.md

@@ -3,22 +3,25 @@ name: catalyst-schema-migrations
 description: >
   Teaches the two-stage drizzle-kit schema migration workflow — `drizzle-kit generate` (offline,
   diffs `*.schema.ts` against the last `snapshot.json`, NEVER against the database) and `migrate()`
-  applied at boot by `DrizzleMigrationsRunner` (gated by `DATABASE_MIGRATE_ON_BOOT`, default `true`),
-  which matches pending migrations by FOLDER NAME against `drizzle.__drizzle_migrations.name`, runs
-  them all in ONE transaction with NO advisory lock. Also covers the `db:generate` / `db:migrate` /
-  `db:check` scripts, `generate` vs `migrate` vs `push` (push is prototyping-only, never point it at
-  a shared database), the `DATABASE_MIGRATIONS_SCHEMA`/`_TABLE` journal location and its restricted-
-  hosting gotcha, and verified failure modes (hand-edited `migration.sql` without a regenerated
-  snapshot, worktrees sharing a dev database with migrate-on-boot, Postgres index-name collisions,
-  the CLI distributing `.schema.ts` definitions but never migrations). Trigger: creating or editing
-  any `*.schema.ts` under `src/@app/*/*/infrastructure/drizzle/`; running or reasoning about
-  `drizzle-kit generate|migrate|push`, `pnpm db:generate`, `pnpm db:migrate`, `pnpm db:check`; a PR
-  failing `schema-drift-check.yml`; touching `DrizzleMigrationsRunner`,
+  applied at boot by `DrizzleMigrationsRunner` (gated by `DATABASE_MIGRATE_ON_BOOT`, default
+  `true`), which matches pending migrations by FOLDER NAME against
+  `drizzle.__drizzle_migrations.name`, runs them all in ONE transaction with NO advisory lock. Also
+  covers the `db:generate` / `db:migrate` / `db:check` / `db:query` scripts — the last one being the
+  read-only path an agent uses to inspect the LIVE Postgres catalog with no `psql` in its
+  environment — `generate` vs `migrate` vs `push` (push is prototyping-only, never point it at a
+  shared database), the `DATABASE_MIGRATIONS_SCHEMA`/`_TABLE` journal location and its
+  restricted-hosting gotcha, and verified failure modes (hand-edited `migration.sql` without a
+  regenerated snapshot, worktrees sharing a dev database with migrate-on-boot, Postgres index-name
+  collisions, the CLI distributing `.schema.ts` definitions but never migrations). Trigger: creating
+  or editing any `*.schema.ts` under `src/@app/*/*/infrastructure/drizzle/`; running or reasoning
+  about `drizzle-kit generate|migrate|push`, `pnpm db:generate`, `pnpm db:migrate`, `pnpm db:check`,
+  `pnpm db:query`; needing to read the live Postgres catalog or a row count from a headless session
+  with no `psql`; a PR failing `schema-drift-check.yml`; touching `DrizzleMigrationsRunner`,
   `drizzle-migrations.module.ts`, or `drizzle-migrations-journal.config.ts`; deciding whether a
   database change needs a migration at all; the words "migration", "migración", "schema drift",
-  "snapshot.json", "drizzle-kit", or "`__drizzle_migrations`" — EVEN IF the user only says "I added a
-  field to the schema" or "the boot is applying migrations twice". Does NOT cover ad-hoc `ALTER`s or
-  one-shot data backfills routed through the `tools` BC's declarative migrations table (see
+  "snapshot.json", "drizzle-kit", or "`__drizzle_migrations`" — EVEN IF the user only says "I added
+  a field to the schema" or "the boot is applying migrations twice". Does NOT cover ad-hoc `ALTER`s
+  or one-shot data backfills routed through the `tools` BC's declarative migrations table (see
   `catalyst-tools`), nor the Aurora YAML → `.schema.ts` codegen itself (see `catalyst-schema` in the
   monorepo root).
 license: MIT
@@ -50,14 +53,14 @@ metadata:
 
 ## The two-stage mechanism
 
-Aurora's database schema is DDL-only, driven exclusively by drizzle-kit — there is no
-runtime auto-sync. Two independent moments:
+Aurora's database schema is DDL-only, driven exclusively by drizzle-kit — there is no runtime
+auto-sync. Two independent moments:
 
 1. **`drizzle-kit generate` (offline, author-time).** Diffs the `*.schema.ts` files matched by the
    `schema` glob in `backend/drizzle.config.ts` against the **last `snapshot.json`** written to
    `src/database/migrations/drizzle/<timestamp>_<name>/` — never against a live database. No DB
    connection is opened. Writes a new folder with `migration.sql` (the DDL) + `snapshot.json` (the
-   new baseline for the *next* diff). If the diff is ambiguous (e.g. a rename), it exits with
+   new baseline for the _next_ diff). If the diff is ambiguous (e.g. a rename), it exits with
    interactive hints (exit code 2) instead of guessing.
 2. **`migrate()` at boot (online, deploy-time).** `DrizzleMigrationsRunner`
    (`src/@config/drizzle/drizzle-migrations.module.ts`) calls
@@ -74,18 +77,18 @@ runtime auto-sync. Two independent moments:
 The practical consequence: renaming a migration folder is safe (a DB that already applied it, under
 the old name, will just get a new row — but `pnpm db:migrate`/boot on a DB that never applied it
 runs the regenerated SQL, which describes the same end state). What is NOT safe is editing
-`migration.sql` by hand without regenerating `snapshot.json` — see [Gotchas](#gotchas-verified). When
-the MODEL itself does not change and only DDL/data must run (a data-only backfill, a hand-written
-index tweak), `--custom` is the supported way in: see the table below.
+`migration.sql` by hand without regenerating `snapshot.json` — see [Gotchas](#gotchas-verified).
+When the MODEL itself does not change and only DDL/data must run (a data-only backfill, a
+hand-written index tweak), `--custom` is the supported way in: see the table below.
 
 ## generate vs migrate vs push
 
-| Command | Diffs against | Touches the DB? | Use it for |
-| --- | --- | --- | --- |
-| `drizzle-kit generate` (`pnpm db:generate --name <x>`) | last `snapshot.json` | No | Authoring a new migration after editing `*.schema.ts`. The only path that produces a reviewable, committable `migration.sql`. |
-| `drizzle-kit generate --custom` (`pnpm db:generate --name <x> --custom`) | nothing (no `*.schema.ts` diff) | No | The MODEL doesn't change, only DDL/data must run. Creates the folder with an EMPTY `migration.sql` to fill in and a `snapshot.json` correctly CHAINED to the previous one (new `id`, `prevIds` pointing at it) — measured (T-6.1): never hand-copy or hand-edit a snapshot instead. |
-| `migrate()` (`pnpm db:migrate`, or automatically at boot) | `drizzle.__drizzle_migrations.name` on the target DB | Yes (DDL apply) | Applying already-generated, already-committed migrations. Never diffs schema — it only replays files that exist on disk. |
-| `drizzle-kit push` | live DB schema directly | Yes (writes DDL immediately, no file produced) | **Local, disposable prototyping only.** It is interactive/destructive on renames and produces **no artifact** — nothing to review, commit, or replay elsewhere. |
+| Command                                                                  | Diffs against                                        | Touches the DB?                                | Use it for                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `drizzle-kit generate` (`pnpm db:generate --name <x>`)                   | last `snapshot.json`                                 | No                                             | Authoring a new migration after editing `*.schema.ts`. The only path that produces a reviewable, committable `migration.sql`.                                                                                                                                                       |
+| `drizzle-kit generate --custom` (`pnpm db:generate --name <x> --custom`) | nothing (no `*.schema.ts` diff)                      | No                                             | The MODEL doesn't change, only DDL/data must run. Creates the folder with an EMPTY `migration.sql` to fill in and a `snapshot.json` correctly CHAINED to the previous one (new `id`, `prevIds` pointing at it) — measured (T-6.1): never hand-copy or hand-edit a snapshot instead. |
+| `migrate()` (`pnpm db:migrate`, or automatically at boot)                | `drizzle.__drizzle_migrations.name` on the target DB | Yes (DDL apply)                                | Applying already-generated, already-committed migrations. Never diffs schema — it only replays files that exist on disk.                                                                                                                                                            |
+| `drizzle-kit push`                                                       | live DB schema directly                              | Yes (writes DDL immediately, no file produced) | **Local, disposable prototyping only.** It is interactive/destructive on renames and produces **no artifact** — nothing to review, commit, or replay elsewhere.                                                                                                                     |
 
 **Never point `push` at a shared database** (dev, staging, prod). If the change is meant to survive
 past your own machine, it has to become a migration — that is the entire reason this workflow
@@ -97,27 +100,111 @@ honest. This project deliberately does **not** wire `push` to any script or CI j
 Defined in `backend/package.json`, proxied from the monorepo root (`pnpm db:generate` etc. delegate
 to `pnpm --filter aurora-back db:<x>`).
 
-| Script | What it does | When |
-| --- | --- | --- |
-| `pnpm db:generate --name <descriptive-name>` | Wraps `drizzle-kit generate`; **`--name` is mandatory** — refuses to run without it. Bare `drizzle-kit generate` silently invents a random nickname (`busy_mystique`) instead of failing, which is exactly the gap that let an unreviewable, unnamed migration slip through in the incident this workflow repairs. | After editing any `*.schema.ts`. |
-| `pnpm db:migrate` | Applies pending migrations **without starting the Nest app**, reusing the exact same `migrate()` call the boot runner uses (`backend/scripts/db/migrate.ts`), including the same journal-location resolution (`drizzle-migrations-journal.config.ts`). Loads `.env` with a minimal hand-rolled parser (no `dotenv` dependency in `backend/`). | Deploys with `DATABASE_MIGRATE_ON_BOOT=false` (see below), or applying by hand without booting Nest. |
-| `pnpm db:check` | Runs a probe `generate --name db-check-drift-probe` in a try/finally, detects whether a new migration folder got created (or drizzle-kit asked for hints, exit 2) — either means drift — and **always deletes the probe folder** before exiting, success or failure. Fully offline, no DB needed. Exit 0 = no drift; exit ≠ 0 = drift or ambiguity. | CI (`schema-drift-check.yml`, runs on PRs touching `*.schema.ts` or the migrations folder) and locally before opening a PR. |
+| Script                                       | What it does                                                                                                                                                                                                                                                                                                                                        | When                                                                                                                                                                                                       |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm db:generate --name <descriptive-name>` | Wraps `drizzle-kit generate`; **`--name` is mandatory** — refuses to run without it. Bare `drizzle-kit generate` silently invents a random nickname (`busy_mystique`) instead of failing, which is exactly the gap that let an unreviewable, unnamed migration slip through in the incident this workflow repairs.                                  | After editing any `*.schema.ts`.                                                                                                                                                                           |
+| `pnpm db:migrate`                            | Applies pending migrations **without starting the Nest app**, reusing the exact same `migrate()` call the boot runner uses (`backend/scripts/db/migrate.ts`), including the same journal-location resolution (`drizzle-migrations-journal.config.ts`). Loads `.env` with a minimal hand-rolled parser (no `dotenv` dependency in `backend/`).       | Deploys with `DATABASE_MIGRATE_ON_BOOT=false` (see below), or applying by hand without booting Nest.                                                                                                       |
+| `pnpm db:check`                              | Runs a probe `generate --name db-check-drift-probe` in a try/finally, detects whether a new migration folder got created (or drizzle-kit asked for hints, exit 2) — either means drift — and **always deletes the probe folder** before exiting, success or failure. Fully offline, no DB needed. Exit 0 = no drift; exit ≠ 0 = drift or ambiguity. | CI (`schema-drift-check.yml`, runs on PRs touching `*.schema.ts` or the migrations folder) and locally before opening a PR.                                                                                |
+| `pnpm db:query "<SQL>"`                      | Runs one read-only `SELECT`/`WITH` statement against the live database — rejects anything else (embedded `;`, multiple statements, any non-`SELECT`/`WITH` keyword) before opening a connection, then executes inside `BEGIN TRANSACTION READ ONLY` / `COMMIT`. Add `--json` for machine-readable output; default is a formatted table.             | Inspecting the live Postgres catalog or row data when `*.schema.ts` and the migrations journal don't answer the question — see [Catalog discovery with `db:query`](#catalog-discovery-with-dbquery) below. |
+
+Implementation: `backend/scripts/db/{generate,migrate,check,query}.ts`, run via `tsx`.
+
+## Catalog discovery with `db:query`
+
+A headless worker has no `psql` (or any interactive database client) in its environment. `db:query`
+is how an agent inspects the LIVE database when `*.schema.ts` and the migrations journal do not
+answer the question — what a legacy column's real Postgres type is, whether an ENUM type is still
+attached to anything, how many rows match a condition — without a client and without write access.
+
+A worked case: `openspec/changes/archive/2026-09-08-normalize-legacy-native-enums/design.md`
+(decision **D5**) hits exactly this wall. The `sap-integration` BC declares three `enum` columns in
+its YAML, but the database has four `enum_sap_integration_*` types — the fourth can only be found by
+querying the catalog:
+
+```sql
+-- 1. Tipos ENUM del esquema y la columna que los usa
+SELECT c.relname AS tabla, a.attname AS columna, t.typname AS tipo
+FROM pg_type t
+JOIN pg_namespace n ON n.oid = t.typnamespace
+LEFT JOIN pg_attribute a ON a.atttypid = t.oid AND a.attnum > 0 AND NOT a.attisdropped
+LEFT JOIN pg_class c ON c.oid = a.attrelid
+WHERE t.typtype = 'e' AND n.nspname = 'public'
+ORDER BY t.typname;
+```
+
+Read-only is enforced by three layers. The **primary** control is the connecting role: `db:query`
+connects with `DATABASE_QUERY_USER` / `DATABASE_QUERY_PASSWORD`, a dedicated role that must not be a
+superuser. `runReadOnlyQuery()` in `query.ts` probes the live connection right after opening it and
+aborts if the role turns out to be a superuser or a member of a server-file role
+(`pg_read_server_files` / `pg_write_server_files` / `pg_execute_server_program`) — the property this
+control depends on is measured against the actual connection, not trusted from configuration. There
+is no fallback to `DATABASE_USER`: if `DATABASE_QUERY_USER` is absent, `db:query` refuses to run.
+
+Set the role up once per environment:
+
+```sql
+CREATE ROLE catalyst_readonly LOGIN PASSWORD '<put it in SOPS, not here>';
+GRANT CONNECT ON DATABASE <database> TO catalyst_readonly;
+GRANT USAGE ON SCHEMA public TO catalyst_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO catalyst_readonly;
+-- The migrations journal (`drizzle.__drizzle_migrations` by default — see
+-- DATABASE_MIGRATIONS_SCHEMA/_TABLE below) lives in its OWN schema, not `public`. "Which
+-- migrations has this database applied?" is the most obvious question this tool exists to
+-- answer, and it fails with "permission denied for schema drizzle" without this grant.
+GRANT USAGE ON SCHEMA drizzle TO catalyst_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA drizzle TO catalyst_readonly;
+-- `FOR ROLE` is load-bearing, not decoration: migrations run as DATABASE_USER, not as the
+-- superuser pasting this snippet. `ALTER DEFAULT PRIVILEGES` with no `FOR ROLE` only covers
+-- tables the CURRENT role (the one running this statement) creates later — it says nothing
+-- about tables DATABASE_USER creates. Without `FOR ROLE`, the very next `pnpm db:migrate`
+-- creates a table catalyst_readonly cannot read, which is exactly what this line exists to
+-- prevent.
+ALTER DEFAULT PRIVILEGES FOR ROLE <the DATABASE_USER role, e.g. catalyst_app> IN SCHEMA public
+  GRANT SELECT ON TABLES TO catalyst_readonly;
+```
 
-Implementation: `backend/scripts/db/{generate,migrate,check}.ts`, run via `tsx`.
+No grant is needed for `pg_catalog` — PostgreSQL grants `USAGE` on it to `PUBLIC` by default, which
+is why catalog discovery (the D5 example above) works with nothing more than `SELECT` privileges on
+`public`.
+
+Two more layers back the role up, for the case where it turns out to be more privileged than
+intended: `validateReadOnlyQuery()` rejects anything but a single `SELECT`/`WITH` statement — plus a
+denylist of filesystem/host-reaching functions (`DENIED_SQL_FUNCTIONS` in `query.ts`) — before a
+connection even opens. The query then still runs inside `BEGIN TRANSACTION READ ONLY`, which makes
+Postgres refuse any statement whose plan modifies data — **writes only, not reads**.
+
+The role fixes filesystem/host access, not column-level exposure: it still holds `SELECT` on every
+table, so nothing above stops it from reading a `password`/`secret`/token column raw. See the
+callout below for what does.
+
+> **Use `db:query` for the catalog and for row counts — type names, column names, constraint names,
+> `count(*)`. That is what it is for.**
+>
+> **Never paste result rows containing real data into a task note, a task comment, a commit message,
+> or a PR body.** The repository is private, so the audience is repository collaborators, not the
+> internet — but `scripts/backlog/close.ts`'s `composePrBody` splices a worker's Implementation
+> Notes verbatim (through `sanitizeCommentBody`, which strips stray `---` lines and truncates — it
+> does not redact) into the body of a GitHub pull request that every collaborator can read. Report a
+> shape or a number ("4 columns still use a native enum", "1 340 rows"), never the rows themselves.
+>
+> `db:query` also reads columns RAW, bypassing the `@Format` masking that hides `password` /
+> `secret` / token columns on every API read (`BR-IAM-USER-001`, `BR-IAM-USER-002`) — a `SELECT *`
+> over `iam_user` or `o_auth_credential` returns exactly what the API refuses to return. Name the
+> columns you need instead of `SELECT *`.
 
 ## Boot gating: `DATABASE_MIGRATE_ON_BOOT`
 
 Default (absent, or `'true'`) preserves current behavior: `DrizzleMigrationsRunner.onModuleInit()`
-migrates on every boot — fine for dev, and for single-instance deploys. Set `DATABASE_MIGRATE_ON_BOOT=false`
-for **multi-replica production**: since `migrate()` has no advisory lock, concurrent replica boots
-racing the same migration can crash the loser. The supported pattern there is running `pnpm db:migrate`
-as an explicit, privileged deploy step **before** replicas start, with the app itself running under
-the restricted runtime credentials.
+migrates on every boot — fine for dev, and for single-instance deploys. Set
+`DATABASE_MIGRATE_ON_BOOT=false` for **multi-replica production**: since `migrate()` has no advisory
+lock, concurrent replica boots racing the same migration can crash the loser. The supported pattern
+there is running `pnpm db:migrate` as an explicit, privileged deploy step **before** replicas start,
+with the app itself running under the restricted runtime credentials.
 
 ### Restricted-hosting gotcha (Plesk-style, no `CREATE` privilege)
 
 Verified empirically: `migrate()` executes `CREATE SCHEMA IF NOT EXISTS` **unconditionally** —
-Postgres checks the `CREATE` privilege on the database *before* checking whether the schema already
+Postgres checks the `CREATE` privilege on the database _before_ checking whether the schema already
 exists, so the statement is denied for a restricted user even when the target schema is already
 there (including `public`). Configuring `DATABASE_MIGRATIONS_SCHEMA`/`_TABLE` does **not**, by
 itself, make `migrate()` work under a restricted user. The supported pattern is the same one as
@@ -126,9 +213,9 @@ credentials at deploy time.
 
 ## Journal location: `DATABASE_MIGRATIONS_SCHEMA` / `DATABASE_MIGRATIONS_TABLE`
 
-Both optional, defaulting to drizzle-orm's own defaults (`drizzle` / `__drizzle_migrations`) —
-when the env var is absent, the key is omitted from the config object entirely rather than defaulted
-to the literal string, so there is exactly one place (`drizzle-orm` itself) that owns the default
+Both optional, defaulting to drizzle-orm's own defaults (`drizzle` / `__drizzle_migrations`) — when
+the env var is absent, the key is omitted from the config object entirely rather than defaulted to
+the literal string, so there is exactly one place (`drizzle-orm` itself) that owns the default
 value. Resolved by `resolveDrizzleMigrationsJournalConfig()` in
 `src/@config/drizzle/drizzle-migrations-journal.config.ts` — the **single shared point** consumed by
 both `DrizzleMigrationsRunner` (via `ConfigService`) and `pnpm db:migrate` (via `process.env`). If
@@ -145,32 +232,32 @@ Decide once per environment, before the first boot.
 1. **Hand-edited `migration.sql` without regenerating `snapshot.json` → stale snapshot → phantom
    hints for the whole team.** This is the exact incident that motivated this workflow: someone
    edited a `migration.sql` by hand (renamed some indexes) without regenerating the accompanying
-   `snapshot.json`, so every subsequent `drizzle-kit generate` anywhere on the team saw a schema that
-   didn't match the recorded snapshot and produced dozens of interactive "rename or create?" hints.
-   **Resync procedure** (full steps in `src/database/migrations/drizzle/README.md`): delete the
-   corrupted folder, temporarily move out any in-flight `.schema.ts` that shouldn't enter this diff,
-   regenerate with `db:generate` (must come out with **zero** hints), then rename the resulting
-   folder back to the **exact original name** — `migrate()` matches by folder name against
+   `snapshot.json`, so every subsequent `drizzle-kit generate` anywhere on the team saw a schema
+   that didn't match the recorded snapshot and produced dozens of interactive "rename or create?"
+   hints. **Resync procedure** (full steps in `src/database/migrations/drizzle/README.md`): delete
+   the corrupted folder, temporarily move out any in-flight `.schema.ts` that shouldn't enter this
+   diff, regenerate with `db:generate` (must come out with **zero** hints), then rename the
+   resulting folder back to the **exact original name** — `migrate()` matches by folder name against
    `__drizzle_migrations.name`, so a database that already applied the old name skips it after the
-   rename; only a database that never applied it runs the (equivalent) regenerated SQL.
-   **When the model doesn't change and you only need to add hand-written DDL/data, don't repeat this
-   incident by hand-copying a snapshot** — `pnpm db:generate --name <x> --custom` produces a
-   correctly chained `snapshot.json` plus an empty `migration.sql` for you to fill in (measured,
-   T-6.1: a hand-copy without `cp` truncated a 432 KB snapshot to 167 bytes).
+   rename; only a database that never applied it runs the (equivalent) regenerated SQL. **When the
+   model doesn't change and you only need to add hand-written DDL/data, don't repeat this incident
+   by hand-copying a snapshot** — `pnpm db:generate --name <x> --custom` produces a correctly
+   chained `snapshot.json` plus an empty `migration.sql` for you to fill in (measured, T-6.1: a
+   hand-copy without `cp` truncated a 432 KB snapshot to 167 bytes).
 2. **Worktrees share the dev database, and migrate-on-boot runs automatically.** Booting a
    feature-branch worktree with `DATABASE_MIGRATE_ON_BOOT` at its default `true` applies that
    branch's unmerged migrations to the shared dev database immediately — before anyone reviewed the
    PR, and before the branch might even be finished. Treat this as a fact of the environment, not a
-   bug: check `git status`/`git log` on `src/database/migrations/drizzle/` before assuming the dev DB
-   only reflects `main`.
+   bug: check `git status`/`git log` on `src/database/migrations/drizzle/` before assuming the dev
+   DB only reflects `main`.
 3. **Postgres index names share a namespace per schema.** Two unrelated migrations that both emit an
    index called `row_id_key` collide the moment both run against the same schema — Postgres index
    names are unique per schema, not per table. Always qualify: `<table>_<columns>_idx` (or similar),
    and keep it under 63 characters (Postgres identifier limit — anything longer gets silently
-   truncated, which can itself cause an unexpected collision). A CLI template regression once emitted
-   short, colliding index names across BCs — run something like `uniq -c` over the index names in
-   any new `migration.sql` before committing it.
-4. **The catalyst CLI distributes schema *definitions*, never migrations.** `catalyst generate`
+   truncated, which can itself cause an unexpected collision). A CLI template regression once
+   emitted short, colliding index names across BCs — run something like `uniq -c` over the index
+   names in any new `migration.sql` before committing it.
+4. **The catalyst CLI distributes schema _definitions_, never migrations.** `catalyst generate`
    writes/updates `*.schema.ts` files; it does not run `drizzle-kit generate` for you. After
    installing or regenerating a module that touches `infrastructure/drizzle/*.schema.ts`, you still
    owe the repo a `pnpm db:generate --name <x>` — `db:check`/CI will catch it if you forget, but
@@ -179,16 +266,16 @@ Decide once per environment, before the first boot.
    `DATABASE_SYNCHRONIZE` / `DATABASE_SYNCHRONIZE_ALTER` (plus the unrelated dead
    `DATABASE_DIALECT`/`DATABASE_STORAGE`/`DATABASE_SOCKET`) have zero references in core-back and
    have been removed from `.env`. All schema DDL now arrives exclusively through committed
-   migrations — if you're looking for "where does the schema get synced", the answer is
-   "it doesn't; it gets migrated."
+   migrations — if you're looking for "where does the schema get synced", the answer is "it doesn't;
+   it gets migrated."
 
 ## Decision summary
 
-| You need… | Reach for | Authored where |
-| --- | --- | --- |
-| A column/table/index change on any BC's aggregate | drizzle-kit (`db:generate` → review `migration.sql` → commit) | `*.schema.ts` (CLI-generated) + `src/database/migrations/drizzle/` |
-| A one-shot data backfill or an `ALTER` you want to activate/roll back independently of a deploy | `tools` BC migrations | `src/database/migrations/<NNN>_<slug>.sql` (flat, no drizzle-kit) — see `catalyst-tools` |
-| Local throwaway prototyping, DB you're about to drop anyway | `drizzle-kit push` (never scripted, never CI, never a shared DB) | n/a — no artifact produced |
+| You need…                                                                                       | Reach for                                                        | Authored where                                                                           |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| A column/table/index change on any BC's aggregate                                               | drizzle-kit (`db:generate` → review `migration.sql` → commit)    | `*.schema.ts` (CLI-generated) + `src/database/migrations/drizzle/`                       |
+| A one-shot data backfill or an `ALTER` you want to activate/roll back independently of a deploy | `tools` BC migrations                                            | `src/database/migrations/<NNN>_<slug>.sql` (flat, no drizzle-kit) — see `catalyst-tools` |
+| Local throwaway prototyping, DB you're about to drop anyway                                     | `drizzle-kit push` (never scripted, never CI, never a shared DB) | n/a — no artifact produced                                                               |
 
 ## Commands
 
@@ -201,6 +288,12 @@ pnpm db:migrate
 
 # Offline drift check — no DB required (what CI runs on schema-touching PRs)
 pnpm db:check
+
+# Read-only catalog lookup — no psql needed
+pnpm db:query "SELECT typname FROM pg_type WHERE typtype = 'e'"
+
+# Same, machine-readable
+pnpm db:query "SELECT typname FROM pg_type WHERE typtype = 'e'" --json
 ```
 
 ## Resources

package/dist/templates/backend/application/.oxlintrc.json

@@ -0,0 +1,171 @@
+{
+  "jsPlugins": ["eslint-plugin-boundaries"],
+  "settings": {
+    "import/resolver": {
+      "typescript": {
+        "project": "./tsconfig.json"
+      }
+    },
+    "boundaries/root-path": ".",
+    // The plugin default dependency-node set is import-only; a re-export or a dynamic
+    // `import()` would cross a boundary silently otherwise.
+    "boundaries/dependency-nodes": ["import", "export", "dynamic-import", "require"],
+    // File-shaped classifications (a single literal path, or a filename-terminal glob) MUST be
+    // declared under `boundaries/files`, not `boundaries/elements`: an element descriptor in this
+    // plugin version only matches folders, and silently never matches a filename-terminal pattern
+    // (measured — `src/@app/*/**/domain/**/*.field-schema.ts` as an element never classifies any
+    // file, with no error, only an advisory warning naming the three affected patterns below).
+    "boundaries/files": [
+      {
+        "category": "drizzle-assembly",
+        "pattern": "src/@config/drizzle/aurora-drizzle-schema.ts"
+      },
+      {
+        "category": "app-relations",
+        "pattern": "src/@app/*/*.relations.ts",
+        "capture": ["bc"]
+      },
+      {
+        "category": "app-field-schema",
+        "pattern": "src/@app/*/**/domain/**/*.field-schema.ts",
+        "capture": ["bc"]
+      }
+    ],
+    // Folder-shaped classifications. Order matters (first match wins, single-match is the
+    // default): `app-domain` must precede `app-behavioral` because `o-auth` has a MODULE named
+    // `application`, so `@app/o-auth/application/domain` would otherwise classify as behavioral
+    // and flag every generated field-schema that targets it. `app-other` is the broadest pattern
+    // and stays last so it only catches what the other two do not (e.g. `<bc>.relations.ts`,
+    // `shared/`).
+    "boundaries/elements": [
+      {
+        "type": "app-domain",
+        "pattern": "src/@app/*/**/domain/**",
+        "capture": ["bc"],
+        "partialMatch": false
+      },
+      {
+        "type": "app-behavioral",
+        "pattern": "src/@app/*/**/{application,infrastructure}/**",
+        "capture": ["bc"],
+        "partialMatch": false
+      },
+      {
+        "type": "app-other",
+        "pattern": "src/@app/*/**",
+        "capture": ["bc"],
+        "partialMatch": false
+      }
+    ]
+  },
+  "rules": {
+    // ── Cross-BC isolation (HR-BRIDGES-002, section "Enforcement mecánico") ──
+    // This checks EXACTLY what the rule declares as mechanically enforced, and only for a
+    // string-literal specifier:
+    //   - files under a folder named application/, infrastructure/ or domain/ of `@app/<bc>`
+    //     (other than an E1 field-schema) import nothing from another `@app/<other-bc>`;
+    //   - E1: a `domain/**/*.field-schema.ts` imports from another `@app/<other-bc>` only its
+    //     domain/;
+    //   - E2: `@config/drizzle/aurora-drizzle-schema.ts` imports from `@app` only a BC-root
+    //     `*.relations.ts`.
+    // Declared limit, NOT an exemption: other files of `@app/<bc>/` (e.g. `shared/`,
+    // `<bc>.relations.ts`), all of `@api/**`, any other file outside `@app/**` except the assembly
+    // point (e.g. `@bridges/**`, other `@config/` files), and imports whose target is `@api/**` or
+    // `@bridges/**` are not linted here. The rule still applies to them by review; do not read a
+    // clean run as proof that they comply. No file-glob scope is declared on this rule (an
+    // `overrides` entry silently never fires for a jsPlugins rule, measured): the element/file
+    // patterns above only ever classify paths under `src/@app/**` and the one assembly file, so
+    // every other tree is naturally never a `from` match and default:"allow" leaves it untouched.
+    // ─────────────────────────────────────────────────────────────────────────
+    "boundaries/dependencies": [
+      "error",
+      {
+        "default": "allow",
+        "policies": [
+          {
+            "from": [{ "file": { "categories": "app-field-schema" } }],
+            "disallow": [
+              {
+                "to": {
+                  "file": { "categories": "app-relations", "captured": { "bc": "!{{from.file.captured.bc}}" } }
+                }
+              },
+              {
+                "to": {
+                  "element": { "type": "app-behavioral", "captured": { "bc": "!{{from.file.captured.bc}}" } }
+                }
+              },
+              { "to": { "element": { "type": "app-other", "captured": { "bc": "!{{from.file.captured.bc}}" } } } }
+            ],
+            "message": "Cross-BC import forbidden: a field-schema of \"{{from.file.captured.bc}}\" may import only the domain/ of another BC (HR-BRIDGES-002, E1)."
+          },
+          {
+            "from": [
+              { "element": { "type": "app-behavioral" } },
+              { "element": { "type": "app-domain", "fileInternalPath": "!*.field-schema.ts" } }
+            ],
+            "disallow": [
+              {
+                "to": {
+                  "file": { "categories": "app-relations", "captured": { "bc": "!{{from.element.captured.bc}}" } }
+                }
+              },
+              {
+                "to": {
+                  "file": { "categories": "app-field-schema", "captured": { "bc": "!{{from.element.captured.bc}}" } }
+                }
+              },
+              {
+                "to": { "element": { "type": "app-domain", "captured": { "bc": "!{{from.element.captured.bc}}" } } }
+              },
+              {
+                "to": {
+                  "element": { "type": "app-behavioral", "captured": { "bc": "!{{from.element.captured.bc}}" } }
+                }
+              },
+              { "to": { "element": { "type": "app-other", "captured": { "bc": "!{{from.element.captured.bc}}" } } } }
+            ],
+            "message": "Cross-BC import forbidden: \"{{from.element.captured.bc}}\" cannot import from \"@app/{{to.element.captured.bc}}\". Route the dependency through a @bridges/ port (HR-BRIDGES-002)."
+          },
+          {
+            "from": [{ "file": { "categories": "drizzle-assembly" } }],
+            "disallow": [
+              { "to": { "file": { "categories": "app-field-schema" } } },
+              { "to": { "element": { "type": "app-domain" } } },
+              { "to": { "element": { "type": "app-behavioral" } } },
+              { "to": { "element": { "type": "app-other", "fileInternalPath": "!**/*.relations.ts" } } }
+            ],
+            "message": "The cross-BC relations assembly point may import from @app only a BC-root \"<bc>.relations\" module (HR-BRIDGES-002, E2)."
+          }
+        ]
+      }
+    ],
+    // `expect(mock.method)` is a legitimate unbound reference in a test; see the `overrides` entry
+    // below rather than a blanket disable.
+    // `no-useless-default-assignment` needs `strictNullChecks`, which is off in tsconfig.json;
+    // turning it on is out of scope for this change (measurements.md, 1.6).
+    "typescript/no-useless-default-assignment": "off",
+    // `ignoreRestSiblings` matches the destructure-to-omit idiom used throughout this codebase
+    // (`const { unwanted, ...rest } = x; return rest;`) — already the convention core-back's own
+    // former ESLint config declared for the same pattern.
+    "eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "destructuredArrayIgnorePattern": "^_",
+        "caughtErrors": "all",
+        "caughtErrorsIgnorePattern": "^_",
+        "ignoreRestSiblings": true
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["*.spec.ts", "*.e2e-spec.ts"],
+      "rules": {
+        "typescript/unbound-method": "off"
+      }
+    }
+  ]
+}

package/dist/templates/backend/application/CLAUDE.md

@@ -1,3 +1,25 @@
+## Runtime
+
+- Native ESM: `"type": "module"` in `package.json`; `module`/`moduleResolution: nodenext`,
+  `resolvePackageJsonExports: true`, `target: ES2023` in `tsconfig.json` / `tsconfig.build.json`.
+  NestJS 12, GraphQL 14 / Apollo 14, TypeScript 6.
+- Build: `nest build` (tsc under the hood — Vite is not a build tool here, only Vitest's engine).
+  Entry point after a build is `dist/src/main.js` (`start:prod`); `nest-cli.json`'s asset entries
+  (`i18n/**/*`, `assets/**/*`, `database/**/*`) declare `outDir: "dist"` so they land in
+  `dist/src/i18n`, `dist/src/assets`, `dist/src/database`.
+- Test runner: Vitest (`pnpm --filter aurora-back test`, config in `vitest.config.ts` /
+  `vitest.config.e2e.ts`). See `.claude/skills/catalyst-backend-testing/SKILL.md`.
+- Linter: oxlint (`pnpm back:lint`, config in `.oxlintrc.json`), carrying the cross-BC boundary
+  rules (HR-BRIDGES-002) via `eslint-plugin-boundaries` loaded as an oxlint `jsPlugin`. Prettier
+  formats separately (`pnpm --filter aurora-back format`) and does not run through the linter.
+- Import convention: every relative or aliased specifier is explicit — a file target ends in
+  `.js`, a barrel directory target (one carrying an `index.ts`) ends in `/index.js`. A bare
+  package specifier (`@nestjs/common`, `dayjs`) is untouched. `tsc` under `nodenext` rejects a
+  missing suffix in an `import`/`export` statement with `TS2307`/`TS2835`. A specifier written
+  as a string argument (`vi.mock('…')`, `vi.importMock('…')`, `vi.importActual('…')`) is not
+  checked by the compiler and takes the same explicit form by hand. See
+  `.claude/skills/catalyst-project-structure/SKILL.md` for the barrel-vs-file rule.
+
 ## Skills (Auto-invoke based on context)
 
 | Context                                                                                                                                                                            | Read this file                                       |

package/dist/templates/backend/application/nest-cli.json

@@ -7,17 +7,17 @@
     "assets": [
       {
         "include": "i18n/**/*",
-        "outDir": "dist/src",
+        "outDir": "dist",
         "watchAssets": true
       },
       {
         "include": "assets/**/*",
-        "outDir": "dist/src",
+        "outDir": "dist",
         "watchAssets": true
       },
       {
         "include": "database/**/*",
-        "outDir": "dist/src",
+        "outDir": "dist",
         "watchAssets": true
       }
     ]