@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/monorepo/.claude/skills/catalyst-schema/types-reference.md

@@ -14,14 +14,49 @@
 | Small numbers       | `smallint`      | -                              | 0-255 range                                   |
 | Money/decimals      | `decimal`       | `decimals: [precision, scale]` | Never use float for money                     |
 | Approximate         | `float`         | -                              | Scientific only                               |
-| Date + time (ISO)   | `dateTime`      | -                              | Datetime as ISO string (e.g. `expiresAt`)     |
-| Date only           | `date`          | -                              | Birthdays, deadlines                          |
-| Epoch (numeric)     | `timestamp`     | -                              | Numeric Unix epoch (`number`); rarely needed  |
+| Date + time (ISO)   | `dateTime`      | -                              | An instant in a Postgres `timestamp` column (timezone-bearing unless `applyTimezone: false`), written as an ISO string, read back as raw Postgres text — see "How a date value travels" below (e.g. `expiresAt`) |
+| Date only           | `date`          | -                              | A calendar day in a Postgres `date` column — no time, no timezone (birthdays, deadlines) |
+| Epoch (numeric)     | `timestamp`     | -                              | Integer Unix epoch (`number`) in a `bigint` column; a string is rejected, even a numeric one; rarely needed |
 | True/false          | `boolean`       | -                              | Use is*/has*/can\* prefix                     |
 | Fixed options       | `enum`          | `enumOptions: [...]`           | Document each option                          |
 | Structured data     | `json`, `jsonb` | -                              | Use jsonb for PostgreSQL                      |
 | Navigation property | `relationship`  | `relationship: {...}`          | One-to-many, many-to-many inverse side        |
 
+## How a date value travels — the runtime chain
+
+Authoring picks the type; this is what each type then does at runtime. Read it before touching a
+form seed, a table cell or a type handler. The GraphQL layer transforms NOTHING:
+`GraphQLISODateTime` and `GraphQLTimestamp` are declared in `core.graphql` with no `@Scalar()`
+implementation, so graphql-js serializes them with `identityFunc` and the driver's raw value
+reaches the browser unchanged. The scalar's name promises nothing.
+
+| Link                        | `date`                                                    | `dateTime`                                                                     | `timestamp`                                                                               |
+| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Drizzle column              | `date(col, { mode: 'string' })`                           | `timestamp(col, { mode: 'string', withTimezone: true })`                       | `bigint(col, { mode: 'number' })`                                                         |
+| Value the browser READS     | `2026-08-01`                                              | `2026-08-30 22:00:00+00` — raw Postgres text: a space, not `T`; `+00`, not `Z` | an epoch number                                                                           |
+| Type handler on WRITE       | `validate` only: rejects anything but a real `YYYY-MM-DD` | `validate` + `sanitize`: normalizes any parseable value to UTC ISO             | `validate` only: rejects anything but a safe integer epoch — a string, even a numeric one |
+| Form model seed             | `init?.x ?? null`                                         | `init?.x ?? null`                                                              | `init?.x ?? null`                                                                         |
+| Form control                | `<au-date-picker>`                                        | `<au-datetime-picker>`                                                         | —                                                                                         |
+| Display (`DateCell` `kind`) | `formatIsoDate` → `DD-MM-YYYY`, never converted           | `formatIsoDateTime` → `DD-MM-YYYY HH:mm` in the viewer's timezone              | —                                                                                         |
+
+Two consequences no single file shows:
+
+- **Read shape ≠ write shape for `dateTime`.** What you send may be ISO; what you read back is
+  Postgres text. Never assert an ISO string on a value read from the API. This is MORE load-bearing
+  now that the form seeds the raw value verbatim: when the user does not touch the control, that
+  Postgres text round-trips back to the server untouched, and it is the server's `dateTime` write
+  handler — not the form model — that normalizes it to UTC ISO before persisting.
+- **A `date` is never converted; a `dateTime` always is.** Converting a `date` to a timezone moves
+  it to the neighbouring day; NOT converting a `dateTime` shows the reader someone else's clock.
+  `DateCell`'s `kind` is the column's TYPE, not a formatting preference.
+
+No handler declares `format()`: the server applies no timezone to any date field. Sources: the
+column mappers in `packages/cli/src/generator/domain/config.ts`, the handlers under
+`packages/core-back/src/modules/type-handlers/handlers/`, the helpers under
+`frontend/src/@aurora/lib/`.
+
+---
+
 ## Varchar Length Standards (Byte-Optimized)
 
 **IMPORTANT: When defining varchar fields, ALWAYS use one of these standard lengths.**
@@ -81,3 +116,149 @@ These lengths are optimized for PostgreSQL byte storage efficiency:
 | Long description   | 1022               |
 | URL/Link           | 2046               |
 | Slug               | 2046               |
+
+---
+
+## Property flags: readOnly and createOnly
+
+A property in `*.aurora.yaml` can declare one of three writability states. `readOnly` and
+`createOnly` are mutually exclusive on the same property — declaring both is a load-time error
+(`catalyst generate` fails naming the file and the property, and writes nothing).
+
+### The three writability states
+
+| State | Who supplies the value, and when | Declared as |
+| ----- | --------------------------------- | ----------- |
+| Normal (default) | The client, on create AND on every update | no flag |
+| `createOnly: true` | The client, ONLY at creation — frozen forever after | `createOnly: true` |
+| `readOnly: true` | Never the client — a column default, a database trigger/procedure, or an internal backend flow (a lifecycle `status`, a cascade write) | `readOnly: true` |
+
+Concrete example already in this repo: `production-order-header.status` is `readOnly: true` — its
+column default fixes it to `PENDING` on create, and only the `provision` action / backend cascades
+change it afterward, never the client. A hypothetical external reference code chosen by the client
+once, at creation, and never editable afterward would be `createOnly: true`.
+
+### What each state emits, surface by surface
+
+| Surface | Normal | `createOnly: true` | `readOnly: true` |
+| ------- | ------ | ------------------- | ------------------ |
+| Create input (GraphQL) + create DTO, create-many input + DTO | present | **present** | excluded |
+| Update-by-id input (GraphQL) + DTO, update-many input + DTO | present | **excluded** | excluded |
+| Generated form, `new` mode — render / model / validators | rendered, validated | **rendered, validated** | absent everywhere |
+| Generated form, `edit` mode — render | editable | **rendered, `disabled()`** | absent |
+| Generated form, `edit` mode — emitted `save` payload | key present | **key OMITTED** (never emitted as `null`/`undefined`) | (already absent) |
+| Generated `*.field-schema.ts` entry | no entry | `createOnly: true` | `readOnly: true` |
+| Runtime write pipeline (`sanitizeRecord`, via `@ApplySchema`/`@Sanitize`) | accepted | key present on an **update** → `400`; on a **create** → accepted and written | key present, **any** operation → `400` |
+| Read surfaces (output type, list column, fragment) | unchanged | unchanged | unchanged |
+| Persistence column (Drizzle) | unchanged | unchanged | unchanged |
+
+The runtime distinction is operation-awareness: `readOnly` rejects a present key unconditionally;
+`createOnly` rejects it only when the write is an `update`. This is carried by a MANDATORY
+`operation: 'create' | 'update'` option on `@Sanitize` / `@ApplySchema` — both decorators accept
+ONLY the options-object form, and a call that omits `operation` fails to compile; there is no
+default. The generator declares `operation: 'create'` on create and create-many handlers,
+`operation: 'update'` on the two update handlers (by-id and bulk), and — counter-intuitively, since
+its payload type is the update-by-id input — `operation: 'update'` on the upsert handler too: five
+emission points in total, each stating its operation explicitly, whether or not the aggregate
+declares any `createOnly` property.
+
+### What does NOT belong in `createOnly`
+
+Three needs look similar but are a different mechanism — do not reach for `createOnly` for any of
+them:
+
+- **A UI-only lock.** Making the control look non-interactive on screen while the value is still
+  writable through the API (REST or GraphQL directly) is a form concern, not a schema flag — use
+  `widget` configuration. `createOnly` changes the WIRE contract itself (the key disappears from
+  the update input entirely); a UI lock never does.
+- **A system-computed value.** A value the client never supplies, in ANY operation, is `readOnly:
+  true`, not `createOnly`. `createOnly` requires the opposite: the client MUST be able to supply the
+  value once, at creation.
+- **A freeze conditioned on the record's state or a state machine.** For example, "immutable once
+  the record reaches an ACTIVE state" or "immutable only after the first related document is
+  issued." `createOnly` is unconditional — frozen from the moment the record exists, forever, with
+  no state check. A conditional freeze is hand-written logic in the handler, not a schema flag.
+
+### Coexistence: three hand-written guards are NOT migrated to `createOnly`
+
+`iam/account`, `hub/app`, and `tools/custom-field-definition` / `custom-field-option` each already
+freeze a field by hand, and none of them adopts `createOnly` — this is a deliberate decision, not a
+gap:
+
+| Site | Behavior today | Why it stays hand-written |
+| ---- | --------------- | -------------------------- |
+| `iam/account` (update-by-id handler) | `409 ConflictException` with a translated message; also covers the bulk update; compares against the PERSISTED value, so echoing back the SAME value is accepted | `createOnly` answers `400` on the key's mere presence — adopting it would change a documented public error code and would start rejecting an unchanged echoed value the current rule accepts |
+| `hub/app` (update-by-id handler) | Silently strips the frozen keys (`code`, `applicationId`) from the payload | `createOnly` rejects with `400` instead — a real behavior change for existing clients, which needs its own change |
+| `tools/custom-field-definition` / `custom-field-option` | `400 BadRequestException` naming the field | Already the same shape `createOnly` would produce, but migrating is a code change for zero behavioral gain — not done here |
+
+`createOnly` is the declarative mechanism for NEW fields going forward. None of these three existing
+guards is replaced by it.
+
+### The `createOnly` + `upsert` rule
+
+The generated `upsert` handler types its payload as the UPDATE input, and `createOnly` fields are
+excluded from that input by design. So an aggregate that declares `createOnly` while its upsert
+handler is still actually generated fails `catalyst generate` at load time — naming the aggregate,
+the property, and the remedy — before any file is written. The rule is keyed EXCLUSIVELY on
+`excludedOperations` — declare `upsert` there and the same aggregate generates normally.
+`excludedFiles` is deliberately NOT a suppression path for this rule: excluding
+only the upsert handler's own path still leaves the upsert RESOLVER generated, importing and
+injecting the handler class regardless, so the emitted backend does not compile; excluding the
+whole `src/@app/**` tree also removes every `*.field-schema.ts` file, so the runtime `createOnly`
+guard is never emitted at all while the still-generated `@api` contracts drop the key — a
+contract-only enforcement already measured insufficient to stop a write. Either shape leaves the
+module broken independent of `createOnly`, so use `excludedOperations` — the only mechanism that
+declares an operation coherently absent.
+
+### The `createOnly` + `autoIncrement` rule
+
+`buildFieldSchemaEntries` (property-mappers.ts) skips every `autoIncrement` property before it ever
+reaches `makeScalarEntry` — the only place that copies `createOnly` onto a generated
+`*.field-schema.ts` entry. So `createOnly` on an `autoIncrement` property has no runtime guard to
+attach to; the flag would silently do nothing. `catalyst generate` fails at load time naming the
+aggregate and the property, and the remedy is simply to drop `createOnly`.
+
+### Known limitation: `update-and-increment` is hand-written, not generator-aware
+
+`update-and-increment` ships a generated SERVICE but no generated handler — any handler driving it
+is hand-written. The generator's own `createOnly` wiring (the mandatory `operation` option on
+`@ApplySchema`/`@Sanitize`, above) only ever reaches the five write handlers it emits itself: create
+and create-many with `'create'`, update-by-id, bulk update and upsert with `'update'`. A
+hand-written `update-and-increment` handler is outside that reach: nothing in this codegen path
+declares `operation` for you, and the decorator will not compile without it. **If you hand-write an
+`update-and-increment` handler on an aggregate that declares `createOnly` properties, declare
+`operation: 'update'` yourself** on that handler's `@ApplySchema`/`@Sanitize` call — writing
+`operation: 'create'` there would compile but let the handler accept a `createOnly` key it should
+reject; the generator cannot choose this for you.
+
+### `readOnly` + `nullable: false` warning
+
+**Do not combine `readOnly: true` with `nullable: false` and no way to fill the column.** If the
+property is `readOnly: true` + `nullable: false` and NOTHING else populates the column (no
+`defaultValue`, no database trigger, no procedure), the INSERT will fail: no client can supply the
+value, and nothing else will. The generator cannot see triggers/procedures declared outside the
+YAML, so it does not fail-fast on this — verify by hand that some other mechanism fills the column
+before shipping a `readOnly: true` + `nullable: false` property.
+
+`readOnly` is orthogonal to `widget.isDetailHidden` (which only hides the control from the detail
+form — the property still lives in the model/payload) and to `type: 'secret'` / `type: 'password'`
+(which mask a value on read, not block a write).
+
+### `readOnly` is the only spelling `core-back` accepts
+
+`readOnly` is the canonical, and only, spelling `sanitizeRecord` reads. The two places the flag
+travels through disagree on which spellings they accept, and that asymmetry is deliberate:
+
+- **YAML / CLI loader.** A property declaring `readonly: true` in `*.aurora.yaml` still loads
+  normally: the loader normalizes it to `readOnly` in memory and emits ONE deprecation warning
+  naming the file and the property before generating the `*.field-schema.ts`. Declaring BOTH
+  spellings on one property is a load-time error.
+- **`core-back` runtime.** `FieldSchemaScalar` has no `readonly` member at all — a hand-authored or
+  un-regenerated `*.field-schema.ts` that still carries the old key fails to compile as
+  `FieldSchema[]` (excess-property check), and if it reaches `sanitizeRecord` anyway (through a cast
+  or an unchecked consumer), the key is simply not read: the field is treated as writable, with no
+  warning.
+
+So a schema authored by hand or through the CLI's YAML normalization always ends up with the
+canonical `readOnly` key by the time it reaches the runtime — the compatibility surface lives
+entirely in the loader, not in `core-back`.

package/dist/templates/monorepo/.claude/skills/harness-rules-guard/SKILL.md

@@ -61,7 +61,8 @@ First identify which **route** applies.
 | **Edit the catalog**               | A convention genuinely changed and the rule must be derogated/replaced                           | Derogate + create a new rule with a NEW id; `pnpm hr:generate && hr:validate` |
 
 There IS a `/harness-rules:audit` command (read-only health/drift: script
-sections A-B + LLM section E — see `references/enforcement.md`). There is **no**
+sections A-B + LLM section E — see `references/enforcement.md`; to READ its
+report finding by finding, `references/audit.md`). There is **no**
 `/harness-rules:document` or `/harness-rules:promote` command, by design: HR are
 not bootstrapped from an aggregate's code, nor crystallized per-change. Beyond
 audit, HR enforcement is the prompt-time injection + propose-time detection +
@@ -179,6 +180,9 @@ Read the reference file that applies:
   how to create/derogate/modify a rule) → `references/format.md`.
 - **The three activation layers + advisory-vs-content-blocked split** →
   `references/enforcement.md`.
+- **How to read the `/harness-rules:audit` report** (what each section means,
+  what each drift finding means, and the concrete action it asks for — including
+  why check 1a fails the audit and 1b does not) → `references/audit.md`.
 
 For a first-time orientation map (what the catalog is, a file table, the
 command table, and pointers to the rest), read `docs/harness-rules/README.md`.
@@ -220,7 +224,9 @@ It carries no format content and no procedure content — those live in
 The only HR slash command is **`/harness-rules:audit`** (read-only health/drift:
 script sections A-B + LLM section E; not exposed as a `pnpm hr:*` alias — run via
 the slash command or `npx tsx scripts/harness-rules/audit.ts`, `--json` for
-tooling). `/harness-rules:document` and `/harness-rules:promote` do NOT exist by
+tooling). To interpret the report it produces — every section, every drift
+finding, and the action each one asks for — read `references/audit.md`.
+`/harness-rules:document` and `/harness-rules:promote` do NOT exist by
 design (HR are not bootstrapped from code / not crystallized per-change). Operate
 the catalog with the pnpm scripts:
 

package/dist/templates/monorepo/.claude/skills/harness-rules-guard/references/audit.md

@@ -0,0 +1,384 @@
+# Audit reference — Harness Rules Catalog
+
+Cómo se lee el informe de `/harness-rules:audit` y qué acción pide cada hallazgo.
+
+El audit tiene dos mitades, y solo la primera es determinista:
+
+1. **Guion estructural** — `scripts/harness-rules/audit.ts`. Solo lectura, sin
+   juicio. Emite la sección **A (salud)** y la sección **B (deriva)**.
+2. **Continuación del LLM** — Claude sigue la sesión y escribe la sección
+   **E (tensiones semánticas)**. El guion NO la produce.
+
+En harness **no existen las secciones C ni D**. En business sí: C son las
+asunciones pendientes y D los pointers cross-BC. Aquí las asunciones viejas son
+la comprobación 6 de la sección B, y el concepto de pointer cross-BC no existe.
+
+---
+
+## Cómo se invoca
+
+| Forma                                           | Qué obtienes                               |
+| ----------------------------------------------- | ------------------------------------------ |
+| `/harness-rules:audit`                          | Secciones A + B + E (el informe completo). |
+| `npx tsx scripts/harness-rules/audit.ts`        | Solo A + B. Sin análisis semántico.        |
+| `npx tsx scripts/harness-rules/audit.ts --json` | A + B como JSON, para tooling.             |
+
+No existe un alias `pnpm hr:audit`, y es deliberado — igual que en business. El
+porqué está en [`enforcement.md`](enforcement.md) (sección «Slash commands: audit
+exists; promote / document do NOT»).
+
+---
+
+## Códigos de salida
+
+| Código | Significado                                                                                                                |
+| ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `0`    | Limpio. Nada que leer.                                                                                                     |
+| `2`    | Hay al menos un aviso. **No es un fallo de build**: es «hay algo que leer».                                                 |
+| `1`    | El guion falló. Casi siempre falta `cliter/harness-rules-index.json`, o está corrupto — corre `pnpm hr:generate`.           |
+
+Ocho condiciones elevan la salida a `2`: las comprobaciones **1a, 2 (muertos), 2
+(demasiado amplios), 3, 4, 5 (huérfanas), 5 (zombis) y 6**, más **un bucket de
+tamaño distinto de `OK`**. Esa última sorprende: con 150 reglas activas el bucket
+pasa a `INFO` y el audit ya sale con `2` aunque la sección B esté limpia.
+
+**La comprobación 1b es la única que no eleva la salida.** Es informativa por
+diseño, y su subsección explica por qué.
+
+---
+
+## Sección A — SALUD
+
+```
+A) SALUD
+  Reglas activas:    12
+  Reglas derogadas:  1
+  Reglas propuestas: 0
+  Total:             13 en 11 archivos
+  Topics cubiertos:  barrels, bridges, dev-modes, ...
+  Tamaño estimado:   ~9,100 tokens
+  Bucket de tamaño:  OK
+```
+
+| Línea              | De dónde sale                                                       |
+| ------------------ | ------------------------------------------------------------------- |
+| Conteos por estado | Del índice `cliter/harness-rules-index.json`, no se recuentan aquí. |
+| Topics cubiertos   | El nombre de cada archivo del catálogo sin la extensión.            |
+| Tamaño estimado    | `reglas totales × 700` tokens. Es una estimación, no una medición.  |
+| Bucket de tamaño   | Se clasifica por **reglas activas**, no por el total.               |
+
+Un conteo de derogadas que crece no es deriva: las reglas derogadas se conservan
+a propósito, porque los ids nunca se reutilizan.
+
+### Buckets de tamaño y qué hacer con cada uno
+
+| Bucket        | Reglas activas | Acción                                                                          |
+| ------------- | -------------- | ------------------------------------------------------------------------------- |
+| `OK`          | < 150          | Ninguna. Barrido semántico completo viable.                                     |
+| `INFO`        | ≥ 150          | Ninguna urgente. Empieza a filtrar el barrido por scope o por BC.                |
+| `WARN`        | ≥ 250          | Filtra siempre. Pregunta al usuario antes de un barrido completo.                |
+| `SOFT_ERROR`  | ≥ 500          | Filtrar es obligatorio. No corras el barrido completo sin permiso explícito.     |
+| `REARCHITECT` | ≥ 1000         | El emparejamiento por pares ya no escala. Propón sub-catálogos antes de auditar. |
+
+Fuera de `OK`, el guion añade una línea que sugiere filtrado por scope o BC en
+`propose` y revisar la arquitectura del catálogo.
+
+---
+
+## Sección B — DRIFT
+
+Siete comprobaciones mecánicas bajo seis numerales. Cada una pide una acción
+distinta, y confundirlas produce trabajo inútil.
+
+| #   | Hallazgo                                      | Acción                                               | ¿Sale con `2`? |
+| --- | --------------------------------------------- | ---------------------------------------------------- | -------------- |
+| 1a  | Glob de `paths` sin ficheros                  | Corregir el glob o derogar la regla.                 | **Sí**         |
+| 1b  | Anchor pattern sin ficheros                   | Leer y decidir; casi siempre nada.                   | No             |
+| 2   | `detect.pattern` sin coincidencias            | Comprobar la errata; si no la hay, nada.             | **Sí**         |
+| 2   | `detect.pattern` con demasiadas coincidencias | Juzgar en la sección E si el patrón es muy amplio.   | **Sí**         |
+| 3   | Regla `bc-bound` con BC desinstalado          | Instalar el BC o derogar la regla.                   | **Sí**         |
+| 4   | `scope` incoherente con `bounded_contexts`    | Corregir el frontmatter. Es siempre un error real.   | **Sí**         |
+| 5   | Citación `@rule HR-…` huérfana                | Corregir la cita o restaurar la regla.               | **Sí**         |
+| 5   | Regla zombi                                   | Hoy, casi siempre nada. Lee la subsección.           | **Sí**         |
+| 6   | Marcador `[VERIFICAR]` / `[ASUNCIÓN]` viejo   | Verificar el supuesto y editar la regla en su sitio. | **Sí**         |
+
+### 1a — Globs de `paths` sin coincidencias
+
+```
+  ⚠ Globs de paths sin matches — gobierno muerto (1):
+    - [HR-XXX-001] backend/src/@app/legacy/**
+```
+
+`paths` declara lo que la regla **gobierna ahora**. Cero ficheros significa que
+la regla no gobierna nada: gobierno muerto. Por eso falla la auditoría.
+
+Un glob sin metacaracteres no se resuelve como glob: se comprueba su existencia
+directamente. Así que una ruta concreta mal escrita cae aquí igual.
+
+**Acción**: corrige el glob si es una errata o una ruta que se movió. Si el área
+que gobernaba ya no existe en el proyecto, deroga la regla y crea una nueva con
+un id nuevo — nunca edites el enunciado en el sitio. El procedimiento está en
+[`format.md`](format.md), sección «Cómo crear, derogar y modificar reglas».
+
+### 1b — Anchor patterns con cero coincidencias
+
+```
+  ℹ Anchor patterns con 0 matches hoy (2) — esperado si vigilan un caso aún inexistente; revisa en sección E si alguno parece pattern muerto o con typo:
+    - [HR-XXX-001] backend/src/@app/**/domain/*.repository.ts
+```
+
+Aquí está la diferencia que más confunde. `### Anchor patterns` no declara lo que
+la regla gobierna: describe **lo que un guard debe vigilar**. Un ancla que vigila
+una violación que todavía nadie ha escrito tiene cero coincidencias, y eso es el
+estado sano. Fallar la auditoría por ello sería una alarma que suena siempre.
+
+Por eso el guion la marca con `ℹ`, no con `⚠`, y la deja fuera del código de
+salida. Cuando no hay ninguna, no imprime nada: aquí no hay línea `✓`.
+
+Dos detalles mecánicos explican por qué un ancla tuya puede no aparecer nunca en
+esta lista:
+
+- Solo se extraen tokens entre backticks que empiecen por `backend/`, `frontend/`,
+  `cliter/`, `scripts/` o `docs/`. Una heurística en prosa («interfaces locales
+  con prefijo `Raw`») no se comprueba jamás.
+- Se descarta todo token con `<`, `>`, `(`, `)`, `|` o `...`, porque son prosa
+  ilustrativa, no rutas. `backend/src/@app/<bc>/**` nunca se comprueba;
+  `backend/src/@app/**` sí. Los metacaracteres `*`, `?`, `{` y `}` sí se conservan.
+
+Si quieres que un ancla se vigile de verdad, escríbela como una ruta literal.
+
+#### Cómo distinguir un ancla sana de una muerta o con errata
+
+El guion no lo decide. Lo decides tú, con estas señales en orden:
+
+| Señal                                                    | Veredicto             | Acción                             |
+| -------------------------------------------------------- | --------------------- | ---------------------------------- |
+| El prefijo literal del glob no existe en disco           | Errata o ruta movida  | Corrige el glob en la regla.       |
+| El prefijo existe, pero ningún fichero casa el sufijo    | Ancla sana, esperando | No toques nada.                    |
+| El glob casa ficheros si le quitas o cambias un segmento | Errata                | Corrige el segmento.               |
+| El ancla describe un caso que el proyecto ya abandonó    | Ancla muerta          | Deroga la regla o quita ese ancla. |
+
+Para medir en vez de deducir, corre el mismo glob con las mismas opciones que usa
+el guion, **desde la raíz del repositorio**:
+
+```bash
+node -e "require('fast-glob')('<glob>',{dot:false,onlyFiles:true,ignore:['**/node_modules/**','**/dist/**','**/.angular/**']}).then(m=>console.log(m.length,m.slice(0,5)))"
+```
+
+Prueba después con el prefijo solo (`backend/src/@app/**`). Si el prefijo devuelve
+ficheros y el glob completo no, la errata está en el sufijo.
+
+### 2 — `detect.pattern` muerto o demasiado amplio
+
+Solo se comprueban las reglas **activas** que declaran `detect`. El guion cuenta
+cuántos ficheros gobernados por la regla contienen el patrón como substring
+literal.
+
+Ojo con el alcance de la búsqueda: de los `paths` de la regla solo se usan las
+entradas **con metacaracteres de glob**. La lista completa se usa únicamente si
+ninguna entrada los tiene. Una regla que mezcle una ruta concreta con un glob
+nunca busca en la ruta concreta.
+
+```
+  ⚠ detect.pattern sin matches en código gobernado — dientes muertos (1):
+    - [HR-DOCS-001] "### Enunciado"
+```
+
+**Cuidado con la etiqueta «dientes muertos».** Un `detect.pattern` describe
+siempre una **violación**: es lo que el content-guard bloquea al escribir. Cero
+coincidencias es, por tanto, el estado normal de una regla que se está
+obedeciendo. El ejemplo de arriba es real: `HR-DOCS-001` prohíbe reproducir la
+plantilla de regla en los README de orientación, y sus dos ficheros gobernados no
+la reproducen. La regla funciona. La acción correcta es ninguna.
+
+Distingue así:
+
+| Señal                                                     | Veredicto                 | Acción                    |
+| --------------------------------------------------------- | ------------------------- | ------------------------- |
+| El patrón está bien escrito y los `paths` casan ficheros  | La regla se obedece       | Nada.                     |
+| El patrón tiene una errata o cambió de forma en el código | Dientes muertos de verdad | Corrige `detect.pattern`. |
+| Los `paths` de la regla también salieron en 1a            | El problema es el gobierno| Arregla 1a primero.       |
+
+Al revés, un conteo mayor que cero no prueba salud: significa que hay apariciones
+ya escritas del patrón prohibido, anteriores al guard o exentas.
+
+```
+  ⚠ detect.pattern con muchos matches — posiblemente demasiado amplio (1); juicio diferido a sección E:
+    - [HR-XXX-001] "as any" → 312 ficheros
+```
+
+El umbral es **más de 50 ficheros**, es decir, salta a partir de 51. El guion no
+juzga: expone el conteo y difiere el veredicto a la sección E. Un patrón demasiado amplio bloquea escrituras legítimas,
+que es el modo de fallo caro de un guard.
+
+**Acción**: en la sección E, decide si el patrón describe la violación con
+precisión. Si no, estrecha `detect.pattern` o baja la regla a advisory quitándole
+`detect`. La forma exacta del campo está en [`format.md`](format.md), sección
+«El campo `detect`».
+
+### 3 — Regla `bc-bound` con BC desinstalado
+
+```
+  ⚠ Reglas bc-bound con BC desinstalado (1):
+    - [HR-XXX-001] BC "sap" (cliter/sap/ no existe)
+```
+
+La regla declara `scope: bc-bound` y su BC, pero `cliter/<bc>/` no existe. La
+regla no puede aparecer en el índice, así que no gobierna nada.
+
+**Acción**: si el BC va a instalarse, deja la regla y no hagas nada. Si el BC se
+retiró del proyecto, deroga la regla.
+
+### 4 — Incoherencia entre `scope` y `bounded_contexts`
+
+```
+  ⚠ Incoherencias scope ↔ bounded_contexts (1):
+    - [HR-XXX-001] scope "bc-bound" exige exactamente 1 bounded_context, tiene 0
+```
+
+Las tres combinaciones válidas: `project` exige cero BCs, `bc-bound` exige
+exactamente uno, `multi-bc` exige dos o más. La semántica completa está en
+[`format.md`](format.md), sección «Scope».
+
+**Acción**: es siempre un error real de frontmatter. Corrígelo y corre
+`pnpm hr:generate && pnpm hr:validate`.
+
+### 5 — Citaciones huérfanas y reglas zombi
+
+Las citas se buscan **solo** en `backend/src/**/*.{ts,tsx}` y
+`frontend/src/**/*.{ts,tsx,html}`, con el patrón `@rule HR-…`. No se busca en
+`cliter/`, ni en `docs/`, ni en `.claude/`.
+
+**Citación huérfana**: el código cita un id que no está en el índice.
+
+```
+  ⚠ Citaciones huérfanas (1):
+    - HR-XXX-001 en /Users/tu-usuario/Projects/aurora/aurora-catalyst/backend/src/@app/iam/user/domain/iam-user.aggregate.ts:42
+```
+
+La ruta sale **absoluta** aquí, a diferencia de la comprobación 6, que la imprime
+relativa a la raíz del repositorio.
+
+**Acción**: casi siempre la cita se quedó atrás tras una derogación. Apunta la
+cita al id nuevo. Si el id nunca existió, es una errata.
+
+**Regla zombi**: activa, con 30 días o más desde su `last_updated`, y sin ninguna
+cita en el código.
+
+```
+  ⚠ Reglas zombi (9):
+    - HR-BRIDGES-001 (41 días sin citas)
+```
+
+**Léelo con cuidado: hoy el catálogo tiene cero citas `@rule HR-…` en el código.**
+Con cero citas, esta lista no mide deriva — mide cuántas reglas activas llevan más
+de 30 días sin editarse. Todas las reglas viejas aparecen, por construcción.
+
+**Acción**: no añadas citas en masa para vaciar la lista. Muchas HR son
+arquitectónicas y advisory, y no tienen un punto del código donde citarlas de
+forma natural. Cuando toques código que una HR gobierna de verdad, añade
+`@rule HR-<TOPIC>-<NNN>` en el JSDoc; el resto de la lista es ruido conocido hasta
+que existan citas.
+
+### 6 — Marcadores `[VERIFICAR]` y `[ASUNCIÓN]` antiguos
+
+```
+  ⚠ Marcadores con > 30 días (1):
+    - [HR-XXX-001] [ASUNCIÓN: el guard corre antes del hook] (45 días) en cliter/harness-rules/bridges.md
+```
+
+Un marcador señala una afirmación que se escribió sin medir. Solo se escanean los
+archivos cuyo `last_updated` tenga 30 días o más: un marcador recién escrito no
+molesta.
+
+**Acción**: verifica el supuesto contra el código y **edita el archivo en el
+sitio** para quitar el marcador. Esto no es cambiar la regla: el enunciado no se
+toca, solo se resuelve una nota del autor. Si al verificar descubres que el
+enunciado es falso, entonces sí: deroga y crea una regla nueva.
+
+---
+
+## Sección E — TENSIONES SEMÁNTICAS
+
+La escribe Claude después del guion. Compara los enunciados de las reglas entre
+sí, que es lo que ninguna comprobación mecánica puede hacer.
+
+Se emparejan reglas con `paths` solapados o con una `keywords` en común. No se
+compara cada regla contra todas: eso no escala, y por eso el bucket de tamaño de
+la sección A decide cuánto se barre.
+
+El vocabulario de veredictos y la plantilla de salida viven en el propio comando,
+`.claude/commands/harness-rules/audit.md`. Lo que interesa aquí es la acción:
+
+| Veredicto       | Qué significa                                | Acción                                                   |
+| --------------- | -------------------------------------------- | -------------------------------------------------------- |
+| `contradiction` | Las dos reglas no pueden cumplirse a la vez. | Decisión arquitectónica: deroga una y crea la sustituta. |
+| `needs-review`  | Puede haber conflicto, hace falta un humano. | Preséntalo al usuario. No lo decidas solo.               |
+| `extension`     | Una extiende a la otra sin contradecirla.    | Añade el enlace en `### Reglas relacionadas` de ambas.   |
+| `orthogonal`    | No se tocan.                                 | Nada. No se reporta.                                     |
+
+Claude se salta esta sección si el catálogo está vacío, si no hay ninguna regla
+activa, o si pediste una auditoría solo estructural.
+
+---
+
+## El nivel de enforcement lo decide la detectabilidad, no la severidad
+
+Es el malentendido más caro al leer el informe. `Severidad: blocking` describe la
+**consecuencia** de violar la regla. No decide cómo se aplica.
+
+Lo que decide el enforcement es el campo `detect`: una regla que lo declara es
+content-blocked y el guard bloquea la escritura; una regla sin `detect` es
+advisory y ningún guard la bloquea nunca. La autoridad es el índice
+(`byId[<id>].detect`), no una lista escrita en prosa.
+
+Por eso hay reglas `blocking` que nunca bloquean nada: su violación no se puede
+expresar como un substring literal sin falsos positivos. El desarrollo completo
+está en [`enforcement.md`](enforcement.md), sección «Advisory vs content-blocked».
+
+Consecuencia práctica al leer la sección B: **la comprobación 2 solo habla de las
+reglas con `detect`**. El silencio del audit sobre una regla advisory no significa
+que se esté cumpliendo. Significa que nadie la mide.
+
+---
+
+## Lo que este audit NO te pide hacer
+
+Harness **no tiene ciclo de `promote` ni de `document`**. Los comandos
+`/harness-rules:promote` y `/harness-rules:document` no existen, y su ausencia es
+deliberada, no una pieza pendiente.
+
+Por tanto, ningún hallazgo de este informe termina en «cristaliza esto» ni en
+«documenta el agregado». Una HR cambia solo por una decisión arquitectónica
+deliberada: derogar la vieja y crear una nueva con un id nuevo. El porqué está en
+[`enforcement.md`](enforcement.md), sección «Slash commands: audit exists;
+promote / document do NOT».
+
+Si vienes de leer la guía de business, ahí la resolución de una cita huérfana
+puede acabar en `/business-rules:document`. Aquí no existe ese comando, así que
+esa salida no está disponible: la cita se corrige a mano.
+
+---
+
+## Workflow recomendado tras un audit
+
+1. Lee la sección A. Si el bucket no es `OK`, decide el filtrado antes de seguir.
+2. Resuelve la sección B por coste: primero 4 (siempre error real), luego 1a,
+   luego 3, luego 5 huérfanas.
+3. Trata 1b, 2 y 5 zombis como lectura, no como tareas. Actúa solo si la tabla de
+   su subsección da un veredicto de errata.
+4. Verifica los supuestos de 6 y quita los marcadores en el sitio.
+5. Si editaste el catálogo, corre `pnpm hr:generate && pnpm hr:validate`.
+6. Vuelve a correr el audit y compara. Un `2` que solo viene de 5 zombis y de 2
+   con patrones sanos es el estado estable de hoy.
+
+## Cuándo no ejecutar el audit
+
+- **A media implementación.** El audit mide el catálogo contra el disco; con el
+  código a medio escribir, 1a y 2 mienten.
+- **Con el índice desactualizado.** Corre `pnpm hr:generate` primero. Este es el
+  caso peligroso: un índice viejo pero válido **no falla**, sale con `0` o con `2`
+  y con conteos y edades equivocados. Solo un índice ausente o corrupto sale
+  con `1`.
+- **Para validar el formato de una regla.** Eso es `pnpm hr:validate`, y son cosas
+  distintas: `validate` comprueba estructura, `audit` comprueba deriva.