# kinds/business-rule.md — one business rule, after the fact

The playbook `/ba-change` loads for `kind: business-rule`. The frame is in
`SKILL.md`; this file carries what is specific to a **business rule**.

Owner document: `règles-métier.md` at the rule's **deepest scope** — the
module doc, or the section doc when the rule governs one section's process
only (full re-Write). Grammar: `_workflow/doc-templates.md` § règles-métier.md;
elaboration guidance in `ba-create-business-rules/levels/elaborate.md`.
Code: `allocation.next` — `BR-NNN`, allocated **module-wide** (a number free
in the target doc but taken in a sibling doc is avoided: BR codes are
doc-scoped and `derive-rule-links` reports the ambiguity).

## 1. Analyse the request

One grouped AskUserQuestion:

| Question | Why it matters |
|---|---|
| **What does it guarantee** — a validation, a calculation, a state transition, a constraint, an integrity invariant, a workflow, an access restriction, a numbering scheme? | the `Type` decides the downstream: Flow lines, RBAC channel, Code pattern |
| **How strict** — `err` (refused), `warn` (allowed, surfaced), `info`? Which error code (`module.subject.reason`, module prefix — BR-011)? | severity decides enforcement; the error code is a public API contract |
| **Which use case(s)** does it govern, at which step? | BR-006; the linked UC's section is where derive-rule-links maps the pagespec |
| **One valid AND one invalid example**, concrete (amounts, dates, statuses)? | BR-002 — without both the rule stays a Level 1 draft; they become the test cases |

## 2. Challenge it

- **Is it a rule or a permission?** « Seul le manager peut approuver » is an
  RBAC row (`/ba-change` kind=permission), or an `access`/`ownership`-typed
  rule whose channel is the matrix — it is exempt from the pagespec link, and
  the matrix must carry it.
- **Is it a rule or a use case?** A sentence with an actor goal and a flow is
  a use case; a rule has a condition and an outcome.
- **Does it already exist?** `existing.exact[]` (same title or same error
  code) → link the UC to the existing rule instead (`Cas d'usage liés` +=);
  `similar[]` → is it a refinement (op=modify) or a distinct rule? BR-003/004
  err on conflicting and redundant rules.
- **Does its Expression name real attributes?** Compare with `entité.md`
  (`data.entities` in the impact step); a missing column → `/ba-change`
  kind=attribute (the rule IS its upstream trace).
- **Does it name real statuses?** A workflow / state-transition rule writes
  `- **Flow**` lines `from → to (by: …, guard: …)` whose values must exist in
  the entity's enum (DM-026, XD-001..003); a new status is kind=attribute
  first.
- **Who enforces it?** Generated code, through the pagespec
  `linkedBusinessRules[]` (DEV-API-008 reads that field, DEV-TEST-009 wants a
  `[Trait("BR","BR-NNN")]` test) — unless the rule is `numbering` (the socle
  allocates codes: the rule is the SPEC of the entity `**Code pattern**`,
  never a hand-rolled allocator), `access` (the matrix), or authored
  `- **Enforcement** : plateforme|manuel — <raison>` (a REAL other channel,
  named).

## 3. Author

```markdown
### <allocation.next> — <Titre>
- **Type** : validation
- **Sévérité** : err
- **Portée** : <APP> / <MODULE>[ / <section>]
- **Condition** : QUAND … ALORS …
- **Expression** : `…`
- **Code d'erreur** : `<module>.<sujet>.<raison>`
- **Flow** :                                   (workflow / state-transition only)
  - draft → submitted (by: BA-001-AC-001, guard: …)
- **Cas valides** : …
- **Cas invalides** : …
- **Cas d'usage liés** : UC-… (étape n)
- **Sources** : SRC-NNN §n                     (when the registry exists)
```

Then the full re-Write of the owner doc (SKILL.md Step 3) and the verify
(`expectCode` = the new code, `baselineCount` = `existing.count`).

## 4. Verify

`report.verify.ok` true: found, delta +1, no duplicate code in the doc, no
near-miss heading, sources cited when required.

## 5. Propagate — what a new rule drags along

1. **Type-specific consequences** — workflow / state-transition: statuses in
   the enum, a UC that moves the state (XD-002), a kanban / workflow screen
   (XD-003); `access` / `ownership`: the RBAC row; `numbering`: the entity
   `**Code pattern**` (`derive-code-specs --mode check`, PRD-132).
2. **Attributes exist** — `entité.md` carries every column the Expression
   reads (DM-025).
3. **The pagespec link** — `derive-rule-links --mode backfill` writes
   `linkedBusinessRules[]` on the pagespecs of the linked UCs' sections
   (mapping ladder: rule-doc folder → linked-UC sections → `needs-judgment`).
   A `needs-judgment` rule (module-level, no linked UC) is linked **by hand**
   in the owning pagespec's json block — never an invented link. Optional: a
   custom action line gains `BR: BR-NNN`. PRD-129/130. Skipped for `access`
   rules (their channel is the matrix) and when the module has no pagespecs.
4. **Never `/ba-create-prd`** on a module with pagespecs.

## 6. Audit

`audit-ba` on the module, dimensions `rules, use-cases, cross-dimension`,
plus `/ba-audit-prd` when pagespecs exist. What an err means here: BR-002
(examples missing), BR-003/004 (conflict / redundancy), BR-006 (no UC),
BR-010 (numbering under-specified), BR-011 (error code without the module
prefix), PRD-129/130 (unlinked / unresolvable), XD-001 (a state with no
transition rule).

## Hand-off — an honest note

`/ba-develop`'s Phase 2a pre-entry checks (DEV-API-024/010/026) do **not**
detect a new rule. What catches it is the post-phase `audit-dev-api`
DEV-API-008 (module-scoped trace of every enforceable rule) and
`audit-dev-tests` DEV-TEST-009 (the `[Trait("BR","BR-NNN")]` test) inside the
auto-heal loop — the business layer is re-scaffolded from
`linkedBusinessRules[]`. Say it, run `/audit-fix` after the run for anything
left, and never hand-implement the rule outside the scaffolders.

## Modify variant (op=modify)

- A changed **error code** is a public API contract: every AC that asserts it
  verbatim and every test that pins it must follow (DEV-TEST-010).
- A changed **type** to workflow / state-transition: `derive-kanban-spec
  --mode check` and `derive-lifecycle --mode check` (the board transitions and
  the form phases read the Flow graph).
- A changed **Portée** may move the rule to another doc — that is a delete +
  add; announce it and route the deletion (never silent).
- The pagespec links stay valid (PRD-130) unless the linked UCs change —
  then `derive-rule-links --mode check` first.
- Verify expects delta **0**.