---
name: ba-audit-rules
description: >
  Audits the business rules of a `.smartstack/ba/` module — completeness,
  conflicts, redundancy, example quality, entity/UC references, per-ruleType
  edge-case coverage (BR-001..010). Reads `règles-métier.md` plus the module's
  `use-case.md` and `entité.md`, writes a verdict to `_audit/règles-métier.md`.
  Run after `/ba-create-business-rules` or as part of pre-dev readiness.
allowed-tools: [Read, Write, Glob, Grep]
---

# ba-audit-rules — Business Rules audit

You audit the business rules of a `.smartstack/ba/` module against the rules
below and write a verdict file. The rule set is unchanged from the SmartStack
convention; only the I/O is file-based.

## File model — how to audit

1. **Read state**: `Glob .smartstack/ba/**/index.md` to locate the module in
   scope. Read `.smartstack/ba/<APP>/<MODULE>[/<section>]/règles-métier.md` for
   the rules (codes, type, severity, condition, expression, error code, valid/
   invalid examples, linked use cases). Also read the module's `use-case.md`
   (to validate UC references and the upstream detail gate) and `entité.md` (to
   validate entity references). To check a UC or entity code exists, Grep it
   across the tree — if it's not found, it does not exist.
2. **Apply** the rules BR-001..009 (below) at the requested scope.
3. **Write** the verdict to `_audit/règles-métier.md` under the audited module:
   `.smartstack/ba/<APP>/<MODULE>/_audit/règles-métier.md` (keep the accented
   filename; use the audit-verdict skeleton from `_workflow/doc-templates.md`).
   Then print a 3–6 line business summary in chat.

There is no database, no `[ACTION]` envelope, no i18n label codes — the `.md`
verdict IS the record. The verdict header (`0 err` = pass) is what a downstream
gate reads.

## Gate dependencies

- **Upstream**: the use-cases phase must be ready before rules can be considered
  complete. If any UC in scope lacks a detailed main flow, this phase cannot
  complete — BR-009 emits `err` regardless of rule count.
- **Downstream**: the RBAC phase depends on this phase being ready (rules
  materialise access/ownership permissions).

## Scope

- **Module scope** (default): audit rules whose scope belongs to the target
  module. UCs are audited for UC → rule coverage within the same module.
- **Section scope**: restrict every check (BR-001..009) to rules whose section
  matches the selected section. BR-001 becomes "at least 1 rule for the selected
  section"; BR-007 becomes "every UC in the selected section has ≥1 linked rule".
  Read only the section's `règles-métier.md` and `use-case.md`.
- **Application / project scope**: rules from all descendant modules apply.
- Rules outside the active scope are out of scope. The verdict file lives at the
  audited module's `_audit/règles-métier.md`.

## Rules

### BR-001 — At least 1 business rule exists per module
- `err` if 0; `ok` if ≥ 1.
- Fix: `/ba-create-business-rules`.

### BR-002 — Rules carry complete examples (Level 2)
- `err` if any rule with examples is incomplete; `warn` if no examples at all on
  ≥1 rule; `ok` if all complete.
- **What to check**:
  1. Rules with no examples → `warn` — rule still at Level 1 shell stage.
  2. Rules with ≥1 example must have **≥1 valid + ≥1 invalid** → `err` if missing
     either side.
  3. Every example must have a non-empty given, when, then → `err` if any field
     blank.
  4. **Enforcement rules only** (rule has a populated error code or error
     message): invalid examples must have an expected error code OR expected
     error message → `err` if both missing. **Filter/visibility rules** (rule
     has no error code AND no error message, e.g. soft-delete guards,
     anonymisation filters, scope isolation) describe observable absence —
     invalid examples legitimately leave the expected error code and message
     empty. Do NOT flag these.
- Fix: `/ba-create-business-rules`.

### BR-003 — No conflicting rules (same condition, different outcomes)
- `err` if conflicts found; `ok` if none.
- Check: normalize conditions (lowercase, trim). Group by condition. If the same
  condition has different expressions → conflict.
- Fix: `/ba-create-business-rules`.

### BR-004 — No redundant rules (same condition AND same expression)
- `warn` if found; `ok` if none.
- Fix: `/ba-create-business-rules`.

### BR-005 — (relocated to DM-010 in `/ba-audit-data-model`)
Entity-reference validation moved to the data-model audit where the entity
catalogue is authoritative. No check here.

### BR-006 — All rules are linked to at least 1 use case
- `warn` if unlinked; `ok` if all linked.
- Direction: rule → UC. Complement of BR-007.
- Fix: `/ba-create-business-rules`.

### BR-007 — Every use case in scope is covered by ≥1 business rule
- `err` if UCs without rules; `ok` if every UC has ≥1 linked rule.
- Direction: UC → rule. Complement of BR-006.
- Check: for each UC in scope, count rules whose linked use cases contain the UC
  code. If 0 → UC is uncovered.
- Why `err` (not `warn`): a UC without rules cannot be vibecoded — the generated
  code would have no invariants, no validation, no failure paths. Downstream code
  generation breaks.
- Fix: `/ba-create-business-rules`.

### BR-008 — Examples cover the edge cases expected for the ruleType
- `warn` if obvious edge cases are missing for the ruleType; `ok` if covered.
- Reference: `create-business-rules` edge-case checklist by ruleType.
- Check per ruleType (minimum expected coverage — at least one example hitting each):

  | ruleType | Required edge cases (pick ≥2 of) |
  |----------|----------------------------------|
  | `validation` | null/empty, boundary (min/max length), format mismatch, case-insensitive dup |
  | `calculation` | zero, negative, rounding boundary, division by zero when applicable |
  | `state-transition` | illegal skip, reverse transition, terminal-state exit |
  | `ownership` | owner allowed, non-owner denied, manager/admin bypass |
  | `constraint` | at-limit boundary, just-above/below, null-vs-zero |
  | `derivation` | missing input (null component), recompute-on-update |
  | `workflow` | threshold boundary, delegation, timeout |
  | `integrity` | soft-deleted parent, cascade, orphaned child |
  | `cross-cutting` | batch operation, system/service account, retry |
  | `compliance` | retention expiry, retroactive policy change |
  | `access` | actor with permission, actor without permission |
  | `numbering` | sequence progression, per-tenant isolation, reset boundary, concurrent allocation (no duplicate) |

- How to detect coverage: scan each example's label, given, when, then for
  keywords from the expected list (case-insensitive). If fewer than 2 of the
  expected edge-case themes are matched → `warn`.
- Fix: `/ba-create-business-rules`.

### BR-009 — Upstream gate: every UC in scope must be detailed
- `err` if any UC in scope is not detailed; `ok` if all detailed.
- **Why**: per the gate chain `actors → UCs → rules → permissions`, rules cannot
  be considered complete while use cases are still in progress. Without detailed
  main flows, rules have nothing concrete to constrain and any downstream code
  generation would produce empty validation paths.
- **Check**: a UC is "detailed" when it has ≥1 main-flow step. Read the module's
  `use-case.md` and collect every UC code in scope (module or section) whose main
  flow is empty.
- Fix: `/ba-create-business-rules` (and re-run `/ba-create-use-case` for the
  undetailed UCs).

### BR-010 — Numbering rules are fully specified
- `err` if a `numbering` rule misses its generation spec; `ok` if all complete or
  no `numbering` rule in scope.
- **Why**: a `numbering` rule drives a code/sequence allocator. Without a complete
  spec the generated numbering is ambiguous (wrong scope = collisions across
  tenants; missing reset = ever-growing counter; unknown gapless = wrong storage).
- **What to check**: for each rule with `Type: numbering`, its Condition/Expression
  must state all four — a **format** template (with at least one token), a
  **sequence scope** (`tenant` / `global` / `parent:<Entity>`), a **reset** period
  (`none` / `yearly` / `monthly` / `daily`), and whether it is **gapless**. A reset
  period MUST match a date token in the format (yearly ⇒ `{YY}`/`{YYYY}`). Examples
  must include ≥1 valid showing the sequence **progressing** and ≥1 invalid showing
  the **no-duplicate** (concurrency / cross-tenant) or **immutability** guarantee.
- Skip when the module has no `numbering` rule.
- Fix: `/ba-create-business-rules`.

## Output

Write `_audit/règles-métier.md` per the doc-templates skeleton:
- Header `# Audit règles métier — <APP> / <MODULE>` + `_<date> · Verdict :
  <emoji> N warn · M err · K ok_`.
- `## ✅ Conforme`, `## ⚠️ Avertissements`, `## ❌ Bloquants` sections; one bullet
  per finding. Keep rule codes (`BR-001`, …) **bold** so they stay greppable, but
  explain each in business terms. For `warn`/`err`: what's wrong (offending rule
  / UC codes **bold**), why it matters, and a `→` fix naming
  `/ba-create-business-rules`.
- Re-Write the whole file each run (overwrite — it's a fresh verdict).

Then a 3–6 line chat summary in the user's language — business terms, not rule
codes. If any `err`, state clearly that the rules must be fixed before moving on.

## Used by the readiness orchestrator

`/ba-audit-pre-dev` runs every dimension and aggregates the verdicts. When invoked
by it, still write `_audit/règles-métier.md` as usual — the orchestrator reads
these files.
