@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/monorepo/.claude/skills/catalyst-update-skill-registry/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: catalyst-update-skill-registry
+description: >
+  Regenerates the project's skill catalog at `.claude/skills/REGISTRY.md` by scanning every
+  SKILL.md across the three scopes (monorepo, frontend, backend) and preserving the scope-first
+  taxonomy. Trigger: IMMEDIATELY after creating, editing, deleting, or renaming ANY SKILL.md in the
+  project — even if the user does not ask explicitly — because a stale registry lies to the next
+  Claude and breaks skill discovery. Also trigger whenever the user mentions "update the registry",
+  "regenerate the catalog", "skill catalog", "skill index", or anything related to the inventory of
+  skills, EVEN IF they don't use the word "registry".
+license: MIT
+metadata:
+  author: aurora
+  version: '1.1'
+  auto_invoke: 'After creating/editing/deleting a SKILL.md; when user asks to update the skill registry'
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+## When to Use
+
+- You have just created a new `SKILL.md` in any scope
+- You have just edited the `name`, `description`, or trigger of an existing `SKILL.md`
+- You have just deleted or renamed a skill
+- The user asks to "update the registry", "regenerate the skill catalog", or similar
+
+**STOP if you are not sure** which skills changed. Scan first, do not assume.
+
+## Critical Patterns
+
+### 1. Scope-first taxonomy
+
+The REGISTRY is organized into three sections by scope, and within each one by type. Scope comes
+first because it matches the directory layout and the way a reader filters: "I'm touching Angular"
+→ go to Frontend. Breaking that order forces readers to re-learn the mental model.
+
+| Scope | Directory | Current subcategories |
+| --- | --- | --- |
+| **Monorepo** | `.claude/skills/` | Aurora Domain, Code Quality, Workflow — OpenSpec SDD, Meta |
+| **Frontend** | `frontend/.claude/skills/` | UI & Components, Layout & Design, i18n, Structure & Review |
+| **Backend** | `backend/.claude/skills/` | Structure & Review (add others if new skills appear) |
+
+**Do NOT change the taxonomy without reason.** If a new skill does not fit an existing
+subcategory, add a new one — but preserve the existing ones.
+
+### 2. Exclude this skill from self-processing
+
+`catalyst-update-skill-registry` must appear under the `Meta` section of the monorepo scope, but do NOT
+self-duplicate logic by scanning itself multiple times. Include it exactly once.
+
+### 3. Skills duplicated between frontend and backend
+
+If a skill with the same `name` exists in both `frontend/.claude/skills/` AND
+`backend/.claude/skills/`, they are TWO separate skills (not a single dual-scope one):
+
+- One entry in the `frontend` scope table, marked with `*`
+- One entry in the `backend` scope table, marked with `*`
+- Section note: *"Skills marked with `*` also exist in the other stack. When modifying one version,
+  evaluate whether the change applies to the other."*
+
+### 4. Trigger formatting
+
+Extract from the frontmatter `description` the text after `Trigger:` if present. Otherwise, use
+the full description text. Keep it concise (1-2 lines).
+
+### 5. Preserve the preamble
+
+The REGISTRY preamble (title, "How to use", sync rule) is preserved across regenerations. Only the
+tables change.
+
+## Procedure
+
+### Step 1 — Scan SKILL.md files
+
+```bash
+for f in .claude/skills/*/SKILL.md frontend/.claude/skills/*/SKILL.md backend/.claude/skills/*/SKILL.md; do
+  echo "=== $f ==="
+  awk '/^---$/{c++; next} c==1{print}' "$f"
+done
+```
+
+Extract for each skill:
+
+- `name` (from frontmatter)
+- `description` (from frontmatter, the narrative part)
+- Trigger (the text after `Trigger:` inside `description`)
+
+### Step 2 — Classify
+
+For each skill:
+
+1. **Scope** = the directory it lives in (monorepo / frontend / backend)
+2. **Subcategory** = infer from the skill's function:
+   - catalyst-schema (operates on `*.aurora.yaml` schemas/DDD) → `Aurora Domain`
+   - typescript, prettier, eslint → `Code Quality`
+   - openspec-\*, sdd-\* → `Workflow — OpenSpec SDD`
+   - catalyst-skill-creator, catalyst-update-skill-registry → `Meta`
+   - catalyst-component-\*, catalyst-data-table-\*, catalyst-form-\* → `UI & Components`
+   - layout-\*, design-\* → `Layout & Design`
+   - transloco-\*, i18n-\* → `i18n`
+   - catalyst-project-structure, catalyst-review-module → `Structure & Review`
+
+If a skill does not fit, STOP and ask the user before inventing a new subcategory.
+
+### Step 3 — Detect duplicates
+
+Compare names between `frontend/.claude/skills/` and `backend/.claude/skills/`. Mark matches with
+`*` in both entries.
+
+### Step 4 — Write REGISTRY.md
+
+Use exactly this template (preserving the preamble and section order):
+
+```markdown
+# Skill Registry — Aurora Catalyst
+
+A navigable catalog of the project's skills, organized by **scope** (physical location) and within
+each scope by **type**. Each `SKILL.md` is the source of truth — this file is only the index.
+
+**Sync rule**: after creating, editing, or deleting any skill, regenerate this file so it reflects
+the real state.
+
+## How to use this registry
+
+1. Detect the **scope** of your task (monorepo, frontend, backend) — usually the first thing you know
+2. Go to the matching section and locate the applicable skill type
+3. Read the `SKILL.md` BEFORE writing code
+4. Multiple skills may apply at once — read them all and combine their rules
+
+---
+
+## Monorepo (`.claude/skills/`)
+
+Apply to the whole project, stack-agnostic.
+
+### {Subcategory}
+
+| Skill | Trigger | Path |
+| --- | --- | --- |
+| `{name}` | {trigger} | `.claude/skills/{name}/SKILL.md` |
+
+---
+
+## Frontend (`frontend/.claude/skills/`)
+
+Angular-specific.
+
+### {Subcategory}
+
+...
+
+---
+
+## Backend (`backend/.claude/skills/`)
+
+NestJS-specific.
+
+### {Subcategory}
+
+...
+```
+
+### Step 5 — Verify
+
+After writing the REGISTRY:
+
+1. Count skills per scope: `ls .claude/skills/ frontend/.claude/skills/ backend/.claude/skills/`
+2. Count entries in the generated REGISTRY
+3. The numbers must match (each existing SKILL.md = one entry in the registry)
+4. If there is a mismatch, investigate before marking the task complete
+
+## Rules
+
+- Keep a REGISTRY section even when it feels redundant, unless a skill has actually disappeared
+  from the filesystem. Removing a section may delete navigational context that other entries still
+  lean on.
+- Do not invent new subcategories on the fly. If a new skill doesn't fit an existing one, ask the
+  user first — subcategories are UX for humans, and arbitrary ones fragment the mental model.
+- Preserve the preamble verbatim. It explains the usage flow; rewriting it every regeneration is
+  churn with no reader benefit.
+- Maintain scope order (monorepo → frontend → backend) and alphabetical order of skills within each
+  subcategory. This matches the cognitive flow "what am I touching first" and avoids diff noise
+  when skills are added.
+- Mark duplicates with `*` in both entries and include the cross-stack section note. Without it,
+  readers assume the frontend and backend versions are identical when they may differ.
+
+## Commands
+
+```bash
+# List every skill across the three scopes
+ls .claude/skills/ frontend/.claude/skills/ backend/.claude/skills/
+
+# Extract frontmatter from every SKILL.md
+for f in .claude/skills/*/SKILL.md frontend/.claude/skills/*/SKILL.md backend/.claude/skills/*/SKILL.md; do
+  echo "=== $f ==="
+  awk '/^---$/{c++; next} c==1{print}' "$f"
+done
+
+# Detect duplicates between frontend and backend
+comm -12 \
+  <(ls frontend/.claude/skills/ | sort) \
+  <(ls backend/.claude/skills/ | sort)
+```

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

@@ -0,0 +1,243 @@
+---
+name: harness-rules-guard
+description:
+  'Guards and guides the harness rules catalog — the project''s
+  architectural/framework constraints. Triggers when an HR rule is cited or
+  asked about by ID; when about to touch paths governed by an active HR rule;
+  during /opsx:propose (declaring `## Harness rules applicable`); or when
+  editing files under cliter/harness-rules/.'
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+  auto_invoke:
+    'Mentioning harness rules, HR-XXX-NNN, an architectural/framework
+    constraint (shadow module, cross-BC, ports/adapters, generated code, dev
+    modes, double cast); about to touch paths governed by an active HR rule;
+    during /opsx:propose; files under cliter/harness-rules/.'
+---
+
+## When to Use
+
+Invoke this skill when:
+
+- The user references a **harness rule** by its identifier (`HR-MODULES-001`,
+  `HR-BRIDGES-001`, `HR-ACL-001`, etc.).
+- You are about to modify code under paths governed by an active HR rule (look
+  up `cliter/harness-rules-index.json` by `byPath`, `byKeyword`, or `byId`).
+- During `/opsx:propose`, you need to declare the `## Harness rules applicable`
+  section in `proposal.md` (COMPLY / VIOLATE / DEROGATE per governing rule).
+- You are editing a rule file under `cliter/harness-rules/<topic>.md` (or the
+  bc-bound location).
+- A write is blocked by the architecture checkpoint and its message names
+  governing `HR-*` ids you must consult.
+
+## Framing — HR are CONSTRAINTS, not post-implementation memory
+
+This is the single most important difference from `business-rules-guard`. **Do
+not** carry over the BR mental model.
+
+| Aspect      | Business Rules (BR)                                  | Harness Rules (HR)                                          |
+| ----------- | --------------------------------------------------- | ---------------------------------------------------------- |
+| Nature      | Domain **invariants** — what the business is true   | Architectural / framework **constraints** — how code lives |
+| Framing     | **Memory** + incoherence detector (post-hoc)        | **Constraint** you honor NOW, before/while you write       |
+| Verb        | `mantiene` / `deroga` / `extiende`                  | **COMPLY** / **VIOLATE** / **DEROGATE**                    |
+| Lifecycle   | Crystallized POST-archive via `/business-rules:promote` | **No promote lifecycle.** Stable; changes only by a deliberate architectural decision |
+| In proposal | `## Business rules affected` (declares future rules) | `## Harness rules applicable` (records compliance with EXISTING rules) |
+
+HR are **enforce-able architectural/framework constraints to honor (COMPLY) or
+deliberately retire (DEROGATE via an architectural decision)**. They are NOT
+documented after the fact to be promoted later — they govern the work you are
+about to do.
+
+## Step 0 — Three entry routes
+
+First identify which **route** applies.
+
+| Route                              | When it applies                                                                                  | What to do                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| **Consult before/while coding**    | About to touch a path an active HR governs, or a write was blocked citing an HR id               | Look up the index (`byPath`/`byKeyword`/`byId`), read the rule, COMPLY      |
+| **Declare at propose time**        | During `/opsx:propose` — record `## Harness rules applicable` in `proposal.md`                   | Run the propose-time conflict detection (`enforcement.md`), declare per rule |
+| **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**
+`/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 +
+checkpoint messaging + content-guard described in `references/enforcement.md`.
+
+## How to consult the index
+
+`cliter/harness-rules-index.json` is the consolidated, generated index (run
+`pnpm hr:generate` to regenerate — never edit it by hand). Three lookups:
+
+- **`byPath`** — array of `{ pattern, ruleIds }`. Find every entry whose glob
+  `pattern` matches the file you are about to touch; the `ruleIds` are the rules
+  that govern it. This is the primary lookup before writing code.
+- **`byKeyword`** — map of `keyword → ruleIds`. Use when the task mentions a
+  harness concept (`shadow module`, `cross-bc`, `ports`, `generated code`,
+  `solution mode`, `double cast`) but you are unsure which paths it touches.
+  Keywords are deliberately bilingual (Spanish + English).
+- **`byId`** — map of `id → rule entry` (with `state`, `severity`, `paths`,
+  `keywords`, `filePath`, and an optional `detect`). Use when the user cites an
+  id directly, and to read `severity` (`blocking` | `informational`) and `state`
+  (only `active` rules govern).
+
+Then open the rule file at `byId[id].filePath` for the full `### Enunciado`,
+`### Casos exhaustivos` decision matrix, and `### Anchor patterns`.
+
+## Identifier convention
+
+```
+Core:        HR-<TOPIC>-<NNN>            → HR-MODULES-001, HR-ACL-001
+Bc-bound:    HR-<BC>-<TOPIC>-<NNN>       → HR-TOOLS-MIGRATIONS-001 (when one exists)
+Multi-BC:    primary BC in the id; the rest declared in `bounded_contexts`
+```
+
+- **UPPERCASE**, deliberately — they stand out as references in code, prose, and
+  PRs. Must match `[A-Z]{2,}-[A-Z0-9-]+`.
+- `<NNN>` is sequential, zero-padded to 3 digits, unique within its topic prefix.
+- **IDs are never reused.** A derogated rule keeps its id permanently.
+
+## COMPLY / VIOLATE / DEROGATE semantics
+
+When a rule governs the work, the change does exactly ONE of:
+
+- **COMPLY** — the approach honors the rule. This is the default and the desired
+  outcome. Record it so the analysis is auditable (e.g. in `## Harness rules
+  applicable`).
+- **VIOLATE** — the approach breaks the rule as written. For a `blocking` rule
+  this HALTS `/opsx:propose` and requires a user decision (derogate / exception /
+  justify no-conflict). For an `informational` rule it is surfaced but does not
+  halt.
+- **DEROGATE** — a deliberate architectural decision to retire or replace the
+  rule. This is rare and is itself an architectural change (its own OpenSpec
+  change), not a side effect of an ordinary proposal. It means editing the rule
+  file (state → `derogated`) and creating a replacement with a new id.
+
+There is no `mantiene / extiende` here, and there is **no** "new HR to be
+created post-archive" — that vocabulary belongs to Business Rules only.
+
+## Two-level enforcement (advisory vs content-blocked)
+
+HR are NOT enforced uniformly. Know which level a rule sits at — full detail in
+`references/enforcement.md`.
+
+- **Content-blocked** — a rule that declares a `detect: { pattern, message }`
+  field (propagated to `byId[id].detect`) is enforced by a `PreToolUse`
+  content-guard that BLOCKS (exit 2) any `Write`/`Edit`/`MultiEdit` whose content
+  matches the pattern under the rule's paths. **Today the ONLY content-blocked
+  rule is `HR-ACL-001`** (`as unknown as`). An approach that needs that pattern
+  is a hard VIOLATE.
+- **Advisory** — the other five rules (`HR-MODULES-001`, `HR-BRIDGES-001`,
+  `HR-PORTS-001`, `HR-CODEGEN-001`, `HR-MODES-001`) have NO `detect` field. They
+  are surfaced via this skill, prompt-time injection, propose-time detection, and
+  checkpoint messaging; the agent applies judgment. They are **never
+  auto-blocked** — a path glob cannot distinguish a legitimate new flow from a
+  shadow module, nor a within-BC adapter from a misplaced cross-BC one.
+
+## Inviolable conventions
+
+1. **Catalog lives at `cliter/harness-rules/<topic>.md`** (core) or
+   `cliter/<bc>/harness-rules/<topic>.md` (bc-bound). The file name describes the
+   **topic** (`modules`, `bridges`, `ports-adapters`), not an aggregate — HR are
+   mostly procedural.
+2. **IDs in UPPERCASE** (`HR-<TOPIC>-<NNN>`). **Never** reuse identifiers from
+   derogated rules.
+3. **Frontmatter in kebab-lowercase**; `bounded_contexts`, `keywords`, `paths`
+   are arrays. `scope` (`project | bc-bound | multi-bc`) is an HR-only field BR
+   does not have; `bounded_contexts` allows `minItems: 0` and `aggregates` is
+   optional (both differ from BR).
+4. **Deliberate language mix**: prose in Spanish, identifiers and citations in
+   English, keywords bilingual. **NEVER "harmonize"**.
+5. **JSON output keys in English**: `state`, `severity`, `scope`, `paths`,
+   `keywords`, `detect`. The metadata table labels in the `.md` stay in Spanish
+   (`Estado`, `Severidad`, `Origen`).
+6. **Enum values in English**: `active | derogated | proposed` for state,
+   `blocking | informational` for severity.
+7. **Semantic changes = derogate + create new**, never edit the `### Enunciado`
+   or the `### Casos exhaustivos` matrix in place. Editing typos, broken paths,
+   or `last_updated` IS allowed.
+8. **HR are stable constraints.** There is no `/harness-rules:promote`; a
+   proposal records compliance with the EXISTING catalog, it does not declare HR
+   to be created later.
+9. **`cliter/harness-rules-index.json` and `docs/harness-rules/INDEX.md` are
+   generated.** Never edit them by hand — run `pnpm hr:generate`.
+10. **Modifying `openspec/`**: only `openspec/config.yaml` (the Harness Rules
+    guidance folded into its `context:` block and `rules.proposal` list — the
+    keys OpenSpec injects into `/opsx:propose`). Nothing else under `openspec/`.
+
+## How to work with each route
+
+Read the reference file that applies:
+
+- **Exact rule-file format** (frontmatter, `detect`, metadata table, decision
+  matrix, anchor patterns) → `references/format.md`.
+- **The three activation layers + advisory-vs-content-blocked split** →
+  `references/enforcement.md`.
+
+For high-level system context (rationale, dual location, scope semantics, ID
+policy, format-vs-BR differences), read `docs/harness-rules/README.md`. It is the
+canonical catalog convention doc — this skill references it, it does not
+duplicate it.
+
+## Anti-patterns (do not do)
+
+1. **Treating HR like BR memory.** HR are constraints you honor while writing,
+   not documentation crystallized post-archive. Do not look for a `promote`
+   step; there is none.
+2. **Using `mantiene / deroga / extiende` or a `Nuevas` subsection in a
+   proposal.** That is BR vocabulary. HR use COMPLY / VIOLATE / DEROGATE against
+   the existing catalog.
+3. **Editing the semantics of a rule in place** (the `### Enunciado` or the
+   `### Casos exhaustivos` results) without derogating. Semantic change =
+   derogate + create new with a new id.
+4. **Reusing derogated identifiers.** Compromises historical traceability of
+   citations in code and PRs.
+5. **"Harmonizing" the language mix** to a single language. It is deliberate and
+   documented in `docs/harness-rules/README.md` and `CLAUDE.md`.
+6. **Hand-editing `cliter/harness-rules-index.json` or
+   `docs/harness-rules/INDEX.md`.** They are generated; run `pnpm hr:generate`.
+7. **Declaring `aggregates` on a procedural HR** just out of BR habit. It is
+   optional; omit it unless the rule is aggregate-specific.
+8. **Citing a path in `### Implementa` that does not resolve on disk.** Causes
+   `pnpm hr:validate` exit 2; cite only verified paths or reference the source in
+   prose.
+9. **Expecting the content-guard to block semantic rules.** Only rules with a
+   `detect` field block (today only `HR-ACL-001`). MODULES/BRIDGES/PORTS/
+   CODEGEN/MODES are advisory — the agent's judgment is the enforcement.
+10. **Skipping the `## Harness rules applicable` section in a proposal that
+    touches governed paths.** Write `None` only when no active rule governs any
+    touched path.
+
+## Available commands
+
+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
+design (HR are not bootstrapped from code / not crystallized per-change). Operate
+the catalog with the pnpm scripts:
+
+| Command                | Function                                                        |
+| ---------------------- | --------------------------------------------------------------- |
+| `pnpm hr:generate`     | Regenerate `cliter/harness-rules-index.json` and `INDEX.md`.    |
+| `pnpm hr:validate`     | Validate format and consistency (exit `0` / `1` / `2`).         |
+| `pnpm hr:check`        | Targeted validation (topic, rule, branch, PR, working tree).    |
+| `/harness-rules:audit` | Read-only health/drift report + semantic-tension continuation.  |
+
+`hr:validate` exit codes: `0` valid, `1` structural errors (invalid frontmatter,
+duplicate ids, missing/unknown Estado/Severidad), `2` warnings only (typically a
+`### Implementa` path that no longer resolves on disk).
+
+## Quick verification after any catalog change
+
+```bash
+pnpm hr:generate && pnpm hr:validate
+```
+
+If this fails, **do not commit** until you fix it. The pre-commit hook
+regenerates the index automatically when `cliter/harness-rules/**/*.md` (or
+`cliter/*/harness-rules/**/*.md`) changes; if regeneration fails, the commit is
+aborted. A BR-only change does NOT trigger HR regeneration (and vice versa).

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

@@ -0,0 +1,170 @@
+# Enforcement reference — Harness Rules activation
+
+How Harness Rules are put in front of the agent and the developer. Unlike
+Business Rules (framed as post-implementation **memory**), HR are **constraints**
+activated at the moment they matter. For the rule-file format, see `format.md`.
+For the catalog conventions and rationale, see `docs/harness-rules/README.md`.
+
+---
+
+## The three activation layers
+
+HR replicate the BR three-layer activation pattern, adapted to the distinct
+nature of HR (constraints, not crystallized invariants).
+
+```
+              PROMPT-TIME                PROPOSE-TIME              WRITE-TIME
+          (UserPromptSubmit)            (/opsx:propose)            (PreToolUse)
+                  │                          │                         │
+       inject-rules-context.ts      openspec/config.yaml      architecture-checkpoint.ts
+       (loads HR index, top-N,      (HR guidance folded into  (existing structural gate —
+        SEPARATE block, framed       context: + rules —        on block, APPENDS governing
+        as CONSTRAINTS)              "Harness rules            HR-IDs to the message)
+                                     applicable", HALT on
+                  │                   VIOLATE of a blocking          +
+                  │                   HR)                       harness-rules-content-guard.ts
+                  │                          │                  (NEW hook — BLOCKS content
+                  │                          │                   matching a rule's detect)
+```
+
+### Layer 1 — Prompt-time injection (`UserPromptSubmit`)
+
+`.claude/hooks/inject-rules-context.ts` loads `cliter/harness-rules-index.json`
+in addition to the BR index, scores active HR rules (primarily by bilingual
+keyword), and injects the most relevant ones as a **SEPARATE labeled block** with
+**CONSTRAINT framing** — distinct from the BR footer that frames rules as
+"memory". HR get their own top-N budget so they do not compete with BR for slots.
+
+- The block is headed as constraints that GOVERN the work (e.g. "harness rules
+  que gobiernan este trabajo — constraints arquitectónicos, no solo memoria").
+- Only `state: active` rules are injected.
+- If the HR index is absent or empty, the hook degrades cleanly to pure BR
+  behavior (BR injection is byte-identical to before this change).
+
+### Layer 2 — Propose-time conflict detection (`/opsx:propose`)
+
+`openspec/config.yaml` carries the Harness Rules guidance **folded into the
+`context:` block and the `rules.proposal` list** (the only keys OpenSpec injects
+into `openspec instructions`; an unknown top-level `harness_rules:` key would be
+silently ignored). The Business Rules `context`/`rules` are preserved verbatim.
+During `/opsx:propose` the agent:
+
+1. Loads `cliter/harness-rules-index.json`.
+2. Uses `byPath` to find active rules whose glob `pattern` matches the change's
+   file paths (and `byKeyword` / `byId` as secondary lookups).
+3. Records a `## Harness rules applicable` section in `proposal.md`, placed
+   **immediately AFTER `## Business rules affected`**, declaring **COMPLY /
+   VIOLATE / DEROGATE** per governing rule. Writes `None` if no active rule
+   governs any touched path.
+4. **HALTs only** when the approach would VIOLATE a rule of severity `blocking`,
+   presenting the resolution options (derogate the rule / create an exception /
+   justify no conflict) and recording the choice. A VIOLATE of an
+   `informational` rule is recorded but does not halt.
+
+This block uses COMPLY/VIOLATE/DEROGATE, **never** the BR `mantiene/deroga/
+extiende` vocabulary, and **never** schedules a `/harness-rules:promote` task —
+there is no such lifecycle (see "No promote lifecycle" below).
+
+### Layer 3 — Write-time messaging + content-guard (`PreToolUse`)
+
+Two hooks operate at write time. They are independent; either one exiting 2
+blocks the write.
+
+**(a) Rule-aware checkpoint messaging** — `.claude/hooks/architecture-checkpoint.ts`
+is the EXISTING structural gate that blocks the first `Write` to a NEW file under
+`backend/src/@(api|app|aurora|bridges)/...`. This change made its block message
+**rule-aware**: when it already blocks, it resolves the active HR ids whose
+`byPath` matches the target file (reusing `rulesByPath`/`globToRegex` from
+`scripts/_catalog-runtime/glob.ts`) and APPENDS them to the message ("Reglas
+harness que gobiernan este path: HR-BRIDGES-001 — consúltalas"). It introduces
+**no new blocking condition** — the `exit 2` is still governed solely by the
+existing structural gate. If the HR index is missing, the message degrades to the
+prior structural text.
+
+**(b) Content-guard** — `.claude/hooks/harness-rules-content-guard.ts` is a NEW
+`PreToolUse` hook on `Write`/`Edit`/`MultiEdit`. It is **catalog-driven**: it
+reads the active rules' `detect` fields from the index, and BLOCKS (exit 2,
+emitting `detect.message`) when the tool's content contains a rule's
+`detect.pattern` AND the target file matches that rule's `paths`. It hardcodes no
+rule knowledge.
+
+---
+
+## Advisory vs content-blocked — the two-level split
+
+HR are NOT enforced uniformly. A rule's enforcement level is decided by its
+**detectability**, not by its severity.
+
+| Level               | Which rules                                                              | How enforced                                                          |
+| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| **Content-blocked** | Rules with a `detect` field. **Today: `HR-ACL-001` only** (`as unknown as`) | The content-guard BLOCKS the write (exit 2). A hard VIOLATE.          |
+| **Advisory**        | The other five: `HR-MODULES-001`, `HR-BRIDGES-001`, `HR-PORTS-001`, `HR-CODEGEN-001`, `HR-MODES-001` | Surfaced via the skill, prompt injection, propose detection, and checkpoint messaging. The agent applies judgment. **Never auto-blocked.** |
+
+### Why the semantic rules are advisory, not blocked by path
+
+A path glob cannot encode intent:
+
+- `HR-MODULES-001` prohibits a **shadow module**, not the creation of
+  `*.module.ts` (catalyst generates them; devs add legitimate flows). A glob
+  cannot tell a legitimate new flow from a shadow module.
+- `HR-BRIDGES-001` prohibits cross-BC code in `@app/`, but legitimate within-BC
+  adapters also live there. A glob cannot tell them apart.
+
+Blocking these by path would over-block normal operations (false positives). Their
+enforcement therefore stays advisory — the agent, guided by this skill and the
+injected constraints, makes the call. Only rules whose violation is **mechanically
+detectable without ambiguity** (a literal content pattern, like `HR-ACL-001`'s
+`as unknown as`) get blocking teeth.
+
+### Adding a new content-blocked rule (catalog-driven)
+
+Because the content-guard is catalog-driven, giving a rule blocking teeth is a
+**catalog edit, not a code edit**: add a `detect: { pattern, message }` to the
+rule's `.md` frontmatter, run `pnpm hr:generate`, and the guard picks it up from
+`byId[id].detect`. Keep `pattern` a substring literal unless an unambiguous regex
+is genuinely needed; keep `message` citing the id and the correct alternative.
+
+---
+
+## Slash commands: audit exists; promote / document do NOT
+
+There IS one HR slash command — `/harness-rules:audit` — and the propose-time
+block **never** schedules a promote. The promote/document absence is the
+deliberate, defining difference from Business Rules:
+
+- **`/harness-rules:audit` EXISTS** — a **read-only** health/drift report
+  (`scripts/harness-rules/audit.ts` + `.claude/commands/harness-rules/audit.md`)
+  following the structural-script + LLM-continuation pattern: the script emits
+  sections **A (health)** and **B (mechanical drift)** and exits `0` (clean) /
+  `2` (warnings); Claude then continues the session with section **E (semantic
+  tensions)** over the rule bodies. It is NOT exposed as a `pnpm hr:*` alias
+  (matching BR audit) — invoke it via the slash command, or run
+  `npx tsx scripts/harness-rules/audit.ts` (`--json` for tooling) directly. It
+  never mutates the catalog or the index.
+- **`/harness-rules:promote` does NOT exist (by design).** A BR is crystallized
+  POST-archive: the proposal declares future rules and `/business-rules:promote`
+  writes them after archive. HR are **stable constraints**, NOT crystallized
+  per-change — there is no promote lifecycle (S3 decision, encoded in
+  `openspec/config.yaml`). An HR changes ONLY through a deliberate architectural
+  decision (its own change): derogate the old rule, create a new one with a NEW
+  id (ids never reused). An ordinary proposal records COMPLY/VIOLATE/DEROGATE
+  against the EXISTING catalog; it does not crystallize anything later.
+- **`/harness-rules:document` does NOT exist (by design).** A BR is documented
+  retroactively FROM an aggregate's code; HR are cross-cutting architectural
+  patterns authored BEFORE they govern code — there is no aggregate to bootstrap
+  from. Documenting an HR is writing the `.md` directly + `pnpm hr:generate`.
+
+To create or change a rule, edit the catalog manually (Workflow: derogate +
+create new) and run `pnpm hr:generate && pnpm hr:validate`.
+
+---
+
+## Degradation guarantees (regression safety)
+
+- If `cliter/harness-rules-index.json` is absent or empty, all three layers
+  degrade to pure BR behavior: prompt injection emits only the BR block, the
+  checkpoint emits only its structural message, the content-guard finds no
+  patterns and blocks nothing.
+- Extending the shared hooks (`inject-rules-context.ts`,
+  `architecture-checkpoint.ts`) preserves 100% of the observable BR behavior —
+  this is a verified invariant of the change.