---
name: business-rules-guard
description:
  'Guards and guides the business rules catalog. Triggers when adding,
  modifying, or derogating rules; when a rule is cited or asked about by
  ID; when about to touch code of an aggregate with active rules; or when
  any /business-rules:* command is invoked.'
license: MIT
metadata:
  author: aurora
  version: '1.0'
  auto_invoke:
    'Mentioning business rules, BR-XXX-YYY-NNN, derogating rules,
    active/derogated/proposed rules, /business-rules:*, files under
    cliter/<bc>/business-rules/.'
---

## When to Use

Invoke this skill when:

- The user asks to add, modify, or derogate a **business rule**.
- The user references a rule by its identifier (`BR-PROD-EVENT-005`, etc.).
- The user is about to modify code under paths governed by active rules
  (look up `cliter/business-rules-index.json` by path or aggregate).
- The user invokes `/business-rules:promote`, `/business-rules:document`,
  `/business-rules:audit`, or `/business-rules:check`.
- During `/opsx:propose`, you detect the change affects an aggregate
  with rules and need to consult the "Business rules affected" section
  declared in `proposal.md`.

## Step 0 — Three entry routes

First identify which **route** applies. Each one has its own workflow.

| Route                                   | When it applies                                                                | Command                                       |
| --------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
| **Crystallize after OpenSpec archive**  | A change has just been archived declaring rule actions in its proposal.md      | `/business-rules:promote`                     |
| **Document retroactively**              | The catalog does not cover an aggregate yet and you want to extract implicit rules from code | `/business-rules:document <bc>/<aggregate>`   |
| **Operate / consult**                   | Audit the catalog, validate a PR/branch, look at an aggregate's rules          | `/business-rules:audit`, `/business-rules:check` |

Never create rules manually without using one of these commands as the
entry point (see "Anti-patterns" below).

## Inviolable conventions

1. **Catalog lives at `cliter/<bc>/business-rules/<aggregate>.md`**. Never
   under `openspec/`, `docs/business-rules/<bc>/`, or anywhere else.
2. **IDs in UPPERCASE** (`BR-<BC>-<AGG>-<NNN>`). **Never** reuse
   identifiers from derogated rules.
3. **Frontmatter in kebab-lowercase**, plural arrays
   (`bounded_contexts`, `aggregates`, `paths` are always arrays).
4. **Deliberate language mix**: prose in Spanish, identifiers and
   citations in English, keywords bilingual. **NEVER "harmonize"**.
5. **JSON output keys in English**: `state`, `severity`, `origin`,
   `triggerOn`, `effectOn`. 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 case table semantics in place.
8. **Rules are post-implementation**, not preconditions. A proposal can
   declare it will create BR-X and BR-Y; the catalog is updated AFTER
   archive via `/business-rules:promote`.
9. **`@rule` in code is optional**, not enforcement.
10. **Modifying `openspec/`**: only `openspec/config.yaml` (where the
    extension that injects business rules into `/opsx:propose` lives).
    Nothing else under `openspec/`.

## How to work with each route

Read the reference file that applies:

- **Add / derogate rules** → `references/workflow.md`.
- **Exact `.md` format** → `references/format.md`.
- **Interpret audit reports** → `references/audit.md`.

For high-level system context (rationale, languages, ID policy,
structure), read `docs/business-rules/README.md`. For deep technical
detail (every component, every file, every flow), read
`docs/business-rules/ARCHITECTURE.md`.

## Anti-patterns (do not do)

1. **Editing the semantics of a rule in place**. If you change the
   `Enunciado` or the case table, **derogate + create new**. Editing
   formatting, typos, broken paths in `Implementa`/`Tests` IS allowed.
2. **Reusing derogated identifiers**. Compromises historical traceability
   of citations in code and commits.
3. **Translating the catalog to a single language** or "harmonizing" the
   mix. The mix is deliberate; this skill and `CLAUDE.md` document it.
4. **Creating rules under `openspec/`** or `docs/business-rules/<bc>/`.
   Rules belong in `cliter/<bc>/business-rules/<aggregate>.md` (cohesion
   with the aggregate's YAML and `CONTEXT.md`).
5. **Modifying files under `openspec/`** other than `config.yaml`. The
   OpenSpec CLI may regenerate them (`openspec update`).
6. **Citing `@rule BR-...` with a non-existent identifier**. The audit
   reports it as orphan. Verify with `pnpm br:check BR-...` before
   citing.
7. **Documenting rules exhaustively up-front** for the entire domain.
   This is the recipe for the catalog to be abandoned. Lazy bootstrap
   per bounded context: `/business-rules:document` is invoked when
   needed, not as an independent project.
8. **Treating the catalog as executable truth**. Executable truth is
   the code and the tests. The catalog is **memory** and **incoherence
   detector**.
9. **Skipping `/business-rules:promote` after `/opsx:archive`** when the
   `proposal.md` declared rule actions. If you don't promote, the
   catalog goes out of sync with the spec just archived.
10. **Auto-filling the body of new rules in `promote`**. The script
    automatically applies derogations, but new rules require human input
    (statement, exhaustive cases). The promote report indicates which
    rules need to be written manually.

## Available slash commands

| Command                                 | Function                                               |
| --------------------------------------- | ------------------------------------------------------ |
| `/business-rules:promote [<archive>]`   | Crystallizes rules declared in an OpenSpec archive    |
| `/business-rules:document <bc>/<agg>`   | Retroactive bootstrap from code (with `--from <md>`)   |
| `/business-rules:audit`                 | Catalog report: structural (drift, assumptions, pointers) + semantic tensions (Claude continues the session and runs pairwise analysis) |
| `/business-rules:check [args]`          | Targeted validation (aggregate, rule, branch, PR, working tree) |

Pnpm equivalents: `br:generate`, `br:validate`, `br:validate:citations`,
`br:check`. **The audit, promote, and document slash commands have NO
`pnpm br:*` alias on purpose**: all three follow the script + LLM
continuation pattern and their useful output is the integrated one
(structural + LLM-driven content). Exposing them as `pnpm br:*` would
attach the same name to a partial output. They are invoked exclusively
via slash commands; for tooling or debugging the scripts can still be
called directly as `npx tsx scripts/business-rules/<script>.ts`.

## Quick verification after any catalog change

```bash
pnpm br:generate && pnpm br:validate
```

If this fails, **do not commit** until you fix it. The pre-commit hook
regenerates the index automatically; if regeneration fails, the commit
is aborted.
