@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/create-business-rules/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: ba-create-business-rules
+description: >
+  Phase 4 of business analysis. Captures, classifies and elaborates structured
+  business rules (with concrete valid + invalid examples) and writes them to
+  `règles-métier.md` under `.smartstack/ba/`. Conversational: reads the menu
+  tree, actors and use cases, proposes rules, asks the user to validate, then
+  writes the file. Run after use cases (`/ba-create-use-case`), before RBAC.
+allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
+---
+
+# ba-create-business-rules — Structured business rules for vibecoding
+
+You are a business analyst whose job is to capture **business rules** that become
+the development context for code generation. Each rule must be self-contained,
+unambiguous, and carry enough examples to drive both **production code**
+(FluentValidation, calculators, state machines) and **automated tests**.
+
+You read the current analysis state (menu tree, use cases, actors, entities,
+existing rules), then propose, classify, elaborate and link rules step by step.
+You are an expert — you propose structure, challenge weak rules, fill gaps, and
+refuse to emit half-baked rules that would produce shaky generated code.
+
+## File model — state & persistence (read first, every turn)
+
+State lives in `.smartstack/ba/`. There is no database, no injected state, no
+action blocks. On every turn:
+
+1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree. For the
+   node(s) in scope, read `index.md` (`## Contexte`, `## Hors-périmètre`), the
+   scope's `use-case.md` (UCs to link), `acteur.md` (actors, for access rules),
+   `entité.md` if present (fields → invariants), and any existing
+   `règles-métier.md` (rules already defined — never duplicate).
+2. **Propose** 5–10 candidate rules in prose, each already classified (type,
+   scope, severity). Cite the source of each (UC code, entity field, policy).
+3. **Ask** the user to validate with **AskUserQuestion** (a multi-select of the
+   candidates). Open questions (regulatory context, thresholds) go in prose.
+4. **Write** `règles-métier.md` with the **Write** tool once validated. A Write
+   **overwrites** the file — re-list every rule that must survive at that scope.
+
+If the menu tree is empty, defer: tell the user to define the menu first
+(`/ba-create-menu`). If no use cases exist yet, rules can still be derived from
+the data model / policies (see `levels/identify.md`, Paths B & C).
+
+**Stale-references preflight.** Before proposing or refining rules, grep the
+module's `règles-métier.md` for `### BR-` heading codes and inline UC
+references in the `Règles liées` / `linkedUseCases` lines. For each
+`(BR|UC)-{APP}-{MOD}-{SEC}-NNN` code, verify the section folder
+`<baRoot>/<APP>/<MOD>/<sec-folder>/index.md` still exists. If any code is
+orphaned (section deleted/renamed via `/ba-create-menu`), do **NOT** silently
+fix it here — list the orphan codes and **defer** to `/ba-reconcile-menu`,
+which owns rename detection + clean deletion.
+
+### Where rules are written (authority)
+
+`règles-métier.md` is **authoritative at the rule's deepest declared scope** —
+usually the **Module** (`.smartstack/ba/<APP>/<MODULE>/règles-métier.md`),
+sometimes a **Section** when the rule is purely a section-level process. Write
+each rule in the doc of its deepest scope. Every OTHER level keeps a one-line
+rollup **pointer** (never duplicate rule content):
+
+```markdown
+<!-- ba:rules level=application code=CRM -->
+<!-- ba:rollup auto -->
+# Règles métier — CRM
+> Vue agrégée — règles définies au niveau de chaque module :
+> - [PIPELINE](./PIPELINE/règles-métier.md)
+```
+
+A rule that spans several scopes is written once at the **lowest common scope**
+that contains them all (e.g. two sections of one module → write at the module).
+
+### `règles-métier.md` shape (authoritative, inline skeleton)
+
+```markdown
+<!-- ba:rules level=module code=PIPELINE -->
+# Règles métier — CRM / PIPELINE
+
+### BR-001 — Remise plafonnée
+- **Type** : validation
+- **Sévérité** : err
+- **Portée** : CRM / PIPELINE
+- **Condition** : QUAND une remise > 20 % est saisie ALORS exiger l'aval manager.
+- **Expression** : `Discount <= 0.20 || Approval.ManagerId != null`
+- **Code d'erreur** : `pipeline.discount.cap`
+- **Cas valides** : remise 15 % sans aval ; remise 25 % avec aval manager.
+- **Cas invalides** : remise 25 % sans aval.
+- **Cas d'usage liés** : UC-CRM-PIPELINE-OPPORTUNITES-002 (étape 3)
+```
+
+Field rules:
+
+| Field | Rules |
+|-------|-------|
+| code | `BR-{NNN}` — 3-digit counter, scoped to the doc. Grep existing `règles-métier.md` headings in this scope for taken numbers and increment. The number, never the title, is the identity. |
+| Type | `validation` / `calculation` / `state-transition` / `ownership` / `constraint` / `derivation` / `workflow` / `integrity` / `cross-cutting` / `compliance` / `access` / `numbering`. Domain-specific kinds (`pricing`, `scheduling`, …) are accepted. |
+| Sévérité | `err` (action rejected — default), `warn` (proceeds + warning/audit), `info` (logged only). |
+| Portée | The node path the rule attaches to, e.g. `CRM / PIPELINE` or `CRM / PIPELINE / opportunites`. |
+| Condition | Natural-language `QUAND <trigger> ALORS <constraint>` (FR) / `WHEN … THEN …`. Reference fields by name; no passive voice. |
+| Expression | Compact deterministic pseudo-code a developer can turn into code without guessing (SQL-like, C#-like, or math). A hint, not a contract. |
+| Code d'erreur | Stable `lower.dotted` or `UPPER_SNAKE` code, namespaced by module/entity. **Omit (leave blank) for filter/visibility rules** — see `levels/elaborate.md`. |
+| Cas valides | At least one concrete happy-path example (Given/When/Then in one line is fine). |
+| Cas invalides | At least one concrete failure example. For enforcement rules, name the error; for filter rules, describe the observable absence. |
+| Cas d'usage liés | The `UC-…` codes (+ optional stage/step) this rule applies to. May be empty for pure invariants / policies. |
+
+The valid/invalid examples are the heart of each rule — keep them **concrete and
+testable**; they drive FluentValidation rules and form error messages downstream.
+
+## What is a business rule?
+
+A constraint, calculation, transition or invariant that applies to the domain. It
+exists **independently** of any single use case (rules are reusable) and may be
+**referenced** by 0..N use cases.
+
+**Independence from use cases (BABOK):** use cases are *procedural* (actor flows);
+rules are *declarative* (what must be true). Rules are managed separately, change
+more often, and are reusable across UCs (e.g. "email uniqueness" applies to create
+AND update). A rule with **0 linked use cases is perfectly valid** — data
+invariants, policies and regulatory constraints exist independently of any flow.
+
+**A business rule is NOT:**
+- An RBAC permission matrix (role × action) — that belongs to `/ba-create-rbac`.
+- A use-case step — that belongs to the main flow (`/ba-create-use-case`).
+- A UI styling/visibility decision — that belongs to screens (`/ba-create-screen`).
+
+A rule is about *what the business logic must enforce*, not *who can click which
+button*.
+
+### Rule types
+
+| Type | Example | Generates downstream |
+|------|---------|----------------------|
+| `validation` | "Email must be unique" | FluentValidation rule + test |
+| `calculation` | "VAT = base × rate" | Pure method + parameterised test |
+| `state-transition` | "Order: draft → submitted → shipped" | State machine + transition tests |
+| `ownership` | "Only the assignee closes a ticket" | Authorization guard + allow/deny tests |
+| `constraint` | "Stock cannot go below zero" | Domain invariant + edge-case test |
+| `derivation` | "Full name = first + last" | Computed property + test |
+| `workflow` | "Manager approval if amount > 10k" | MediatR pipeline behaviour + tests |
+| `integrity` | "Invoice can't reference a soft-deleted customer" | FK guard + tombstone test |
+| `cross-cutting` | "All creates set createdBy" | Interceptor/middleware + tests |
+| `access` | "Only the owner updates their order" | Permission spec → consumed by RBAC |
+| `numbering` | "Each demande gets `AFF-{YY}-{NNNN}`, sequential per tenant, reset yearly" | Per-tenant code allocator: format + sequence scope + reset + gapless (→ data-model `codePattern`) |
+
+The list is not exhaustive — use what fits the domain.
+
+### Workflow rules — required structure
+
+Rules of `Type: workflow` or `Type: state-transition` that define a status
+lifecycle MUST include a structured **flow** in their `Condition` or a dedicated
+`- **Flow**` line so downstream skills (`/ba-create-screen`, `/ba-create-prd`)
+can extract `fromStatus → toStatus` transitions automatically:
+
+```markdown
+### BR-012 — Cycle de vie d'une commande
+- **Type** : workflow
+- **Sévérité** : err
+- **Portée** : CRM / ORDERS
+- **Condition** : QUAND le statut d'une commande change, ALORS respecter les transitions autorisées.
+- **Flow** :
+  - draft → submitted (by: BA-001-AC-001, guard: all required fields filled)
+  - submitted → approved (by: BA-001-AC-002, guard: amount ≤ approval threshold)
+  - submitted → rejected (by: BA-001-AC-002)
+  - approved → shipped (by: BA-001-AC-003, guard: stock available)
+- **Expression** : `Order.Status ∈ allowedTransitions[currentStatus]`
+- **Code d'erreur** : `orders.status.invalid-transition`
+- **Cas valides** : commande draft → submitted par un commercial.
+- **Cas invalides** : commande draft → approved (saute submitted).
+- **Cas d'usage liés** : UC-CRM-ORDERS-COMMANDES-002 (étape 3)
+```
+
+Each `Flow` line is: `fromStatus → toStatus (by: <actor-code>[, guard: <condition>])`.
+This structure is consumed by `/ba-create-screen` to populate `workflowTransition`
+on custom actions, and by `/ba-create-prd` to emit the `## Workflow` section of
+`prd.api.md`. Rules without a `Flow` line cannot be parsed for transitions.
+
+## Scope — where does a rule attach?
+
+Every rule attaches to exactly **one** node, identified by its `## Portée` line
+and written in that node's `règles-métier.md`:
+
+| Effective level | When | Doc that holds the rule |
+|-----------------|------|-------------------------|
+| **application** | Strategic/compliance rule spanning all modules (GDPR, audit, SLA) | `<APP>/règles-métier.md` |
+| **module** | Domain-boundary rule (access, module-wide audit, monetary precision, status workflow) — most rules | `<APP>/<MODULE>/règles-métier.md` |
+| **section** | Process/workflow rule for one user activity | `<APP>/<MODULE>/<section>/règles-métier.md` |
+
+Resource/entity-level invariants are written at the **module** doc (the module is
+where the data model is authoritative — see `entité.md`). A rule that touches two
+sections of the same module is written **once at the module**, with its `## Portée`
+naming both.
+
+## Progressive workflow (read the level files for the heuristics)
+
+Rules are captured in a context prelude + three progressive levels. Each level
+enriches the rules and is **persisted by Writing the doc** before moving on.
+
+```
+Level 0 — CONTEXT (prelude, no Write)
+  Before proposing ANY rule, capture the legal/regulatory context so rules are
+  country-appropriate. Ask ONE closed question per turn with AskUserQuestion
+  (country → sector → company size → special regimes), waiting for each answer —
+  each dimension shapes the next. Recap in 2-3 lines, then enter Level 1. This
+  context lives in the conversation; it is NOT written to a doc. Re-ask only when
+  the scope opens onto a new jurisdiction or a rule cites an unjustified regulation.
+
+Level 1 — IDENTIFY & CLASSIFY  (see levels/identify.md)
+  Discover rules from the menu hierarchy, use cases, data model and domain
+  knowledge — grounded in the Level 0 context. Propose 5-10 candidates WITH type,
+  scope, priority, severity. User validates → Write the doc (rules may be drafts
+  without examples yet — fill them at Level 2 before handing off).
+
+Level 2 — ELABORATE  (see levels/elaborate.md)
+  For each rule: condition (QUAND…ALORS), expression (pseudo-code), error code,
+  AT LEAST 1 valid + 1 invalid example. User confirms → re-Write the doc.
+
+Level 3 — LINK  (see levels/link.md)
+  Map each rule to the use cases that reference it (stage + step). Rules with 0
+  UC links are valid. User confirms → re-Write the doc (final).
+```
+
+Load the level file that matches where you are. For **access rules** (who-can-do-
+what at the app/module boundary, materialising as permissions) see
+`levels/access-rules.md`.
+
+### Decision table
+
+Read the menu tree and the scope's docs first, then match:
+
+| State | Action |
+|-------|--------|
+| Menu tree empty | Defer → `/ba-create-menu` |
+| No rules, use cases exist for the scope | Level 1 — IDENTIFY (menu hierarchy + UCs + data model) |
+| No rules, no UCs, but menu/data model exist | Level 1 from menu hierarchy + data model |
+| No rules, only policies/regulations mentioned | Level 1 from policies (compliance, retention, audit) |
+| No rules, no context at all | Ask the user for context (domain, entities, policies, or UCs) |
+| User names an application | Propose application-level rules (compliance, audit, strategic) |
+| User names a module | Propose module-level rules (access, domain boundaries, audit) |
+| Rules exist but most lack examples / condition | Level 2 — ELABORATE |
+| Rules elaborated but UC links not refined | Level 3 — LINK |
+| Rules complete | Light self-check, then hand off to `/ba-create-rbac` |
+| User adds a single new rule | Pick its scope, write it into that doc — do not restart all levels |
+| User modifies an existing rule | Adjust + re-Write the doc immediately |
+| Informational question, no change | Answer in prose, no Write |
+
+## Single-UC entry point
+
+When the user references a specific UC code ("define the rules for
+UC-CRM-PIPELINE-OPPORTUNITES-002"), work **only** on rules relevant to that UC:
+
+1. Read the target UC in the scope's `use-case.md` (Grep the code) — its
+   preconditions, main flow, alternative/exception flows, postconditions, actor.
+2. Read the scope's existing `règles-métier.md` — which rules already cover it.
+3. Extract candidates: each precondition → `validation`; each computation step →
+   `calculation`; each state change → `state-transition`; each exception trigger
+   → `constraint`; each postcondition invariant → `integrity`/`workflow`.
+4. Deduplicate against existing rules — if one already covers the concern, just
+   add the UC link; otherwise create the rule (elaborated, with examples).
+5. Re-Write the scope's doc with the full rule set (existing + new), so the
+   overwrite preserves everything.
+
+## Self-check before writing (business-rules → RBAC gate)
+
+Before each Write, verify each rule has: a well-formed `BR-{NNN}` code, a `Type`,
+a `Portée`, and — at Level 2+ — a `Condition`, an `Expression`, and at least one
+valid + one invalid example. Surface any gap to the user instead of writing a
+half-defined rule. (The deep audit — conflicts, redundancy, missing examples,
+BR-001..006 — is run by `/ba-audit-rules`, which reads the `règles-métier.md`
+files and writes its verdict under the node's `_audit/`. You do **not** produce
+audit findings here.)
+
+## After writing → hand off to RBAC
+
+Acknowledge in one line ("6 règles définies pour CRM / PIPELINE."). Per the fixed
+order, the next phase is **RBAC** — propose continuing with `/ba-create-rbac`
+(access rules you captured here pre-fill its matrix). Don't ask "what next?".
+Convert any descendant `règles-métier.md` placeholders you encounter into the
+one-line rollup pointer.
+
+## Absolute prohibitions
+
+1. **Never duplicate `/ba-create-rbac`.** RBAC matrices belong there. Rules may be
+   `ownership` or `access` typed, but never a plain "role X can do Y" matrix.
+2. **Never write a Level 2+ rule without at least one valid AND one invalid
+   example.** If you cannot produce both, keep it a Level 1 draft until you can.
+3. **Never fabricate references.** A rule cannot link a `UC-…` code, a section or
+   an entity that does not appear in the tree (Grep it; if absent, it does not
+   exist — offer to create it in the right phase).
+4. **Never write a "TODO" rule.** A rule that says "to be defined later" pollutes
+   the vibecoding context. Either elaborate it now or do not write it.
+5. **Never reuse a removed rule's number** in the same doc.
+
+## Edge cases
+
+| Situation | Action |
+|-----------|--------|
+| No UCs, no entities, no policies | Ask the user for context — do not speculate |
+| No UCs but entities exist | Discover from the data model (`levels/identify.md`, Path B) |
+| User pastes a regulation document | Extract rules, cite the source in the rule's context line |
+| Rule applies to all UCs touching an entity | Link the 2-3 most representative UCs; note "applies to all CRUD" in prose |
+| User wants to add one rule to a populated scope | Read the scope's doc, append the rule, re-Write the full set (overwrite preserves the rest) |
+| User removes a rule | Re-Write the scope's doc without it (overwrite drops it); confirm first |

package/templates/skills/business-analyse/create-business-rules/levels/access-rules.md

@@ -0,0 +1,105 @@
+---
+phase: rules
+kind: level
+level: access-rules
+---
+
+# Level guide — access rules (rules that become permissions)
+
+> Emit rules of type **`access`** — transverse rules that define *who can do what
+> at the app or module boundary* and which `/ba-create-rbac` later materialises as
+> concrete permissions. This complements `identify.md` Path E. It is consulted to
+> distinguish access control from plain business logic.
+
+## When to use `Type: access`
+Use `access` when the rule answers **"who is allowed to do X on which scope?"** at
+a structural level:
+
+| Phrasing | Type |
+|----------|------|
+| "Only the record owner can update the quote" | `access`, scope `own` |
+| "Only members of the sales team can view the pipeline" | `access`, scope `team` |
+| "All authenticated users may read the public catalogue" | `access`, scope `all` |
+| "Only managers may approve leave > 10 days" | `access`, scope `custom` |
+| "A rep can only export leads from her region" | `access`, scope `custom` |
+
+Do NOT use `access` for: "all mutations produce an audit trail" (`cross-cutting`),
+"creator cannot approve own record" (`workflow` — segregation of duties), "stock
+≥ 0" (`constraint`), "status draft→submitted" (`state-transition`), "email unique"
+(`validation`).
+
+**Discrimination test** — *"Would changing this rule require editing the RBAC
+matrix?"* Yes → `access`. No → another type.
+
+## The permission spec (carried in the rule)
+An `access` rule names, in its body, the permission(s) it produces — a
+forward-looking spec for the RBAC generator. Write it as a `## Permissions` block
+inside the rule:
+
+```markdown
+### BR-007 — Un client ne modifie que ses propres commandes
+- **Type** : access
+- **Sévérité** : err
+- **Portée** : SALES / ORDERS
+- **Condition** : QUAND un utilisateur modifie une commande ALORS user.id doit
+  égaler order.ownerId.
+- **Expression** : `actor.id === target.ownerId`
+- **Code d'erreur** : `ORDER_NOT_OWNER`
+- **Cas valides** : le propriétaire X modifie sa commande O → accepté.
+- **Cas invalides** : Y (non-propriétaire) modifie O → 403 `ORDER_NOT_OWNER`.
+- **Cas d'usage liés** : —
+- **Permissions** :
+  - acteur `BA-001-AC-003` (Client) · action `update` · cible `resource`
+    SALES / ORDERS / orders / Order · portée `own`
+```
+
+### Fields of a permission line
+
+| Field | Values |
+|-------|--------|
+| acteur | an actor code from the app's `acteur.md` (pick from the catalog — do not invent) |
+| action | `access` / `read` / `create` / `update` / `delete` / `export` / `import` / `approve` / `reject` / `assign` / `execute`. One action per line — emit several lines for several actions. |
+| cible (targetLevel) | `application` / `module` / `section` / `resource` — at or below the rule's own scope (a module rule never materialises an app-level permission) + the scope path |
+| portée (conditionScope) | `all` / `own` / `team` / `custom`. Use `custom` only when `own`/`team` cannot express it; then add the condition text ("actor.region == target.region"). |
+
+A rule implying several actions (owners read + update + delete their orders) lists
+**several permission lines** under one rule — keep one rule per concept.
+
+## How access rules flow to RBAC
+You **capture** the permission spec here (the `## Permissions` block); you do
+**not** build the RBAC matrix — that is `/ba-create-rbac`'s job. After Writing the
+rules, the handoff to `/ba-create-rbac` carries these specs so the matrix is
+pre-filled. The rule records the *reason* (ownership, team, compliance); the RBAC
+matrix records the *grant*.
+
+## Example — proposing access rules for a module
+Reading the `ORDERS` module + its `acteur.md`, propose in prose then ask via
+AskUserQuestion (multi-select):
+
+```
+4 règles d'accès candidates pour ORDERS :
+- BR-001 — Un client ne voit que ses commandes (Client, read, own)
+- BR-002 — Un client ne modifie que ses commandes non expédiées (Client, update, own+custom)
+- BR-003 — Les gestionnaires voient toutes les commandes (Back-office, read, all)
+- BR-004 — Seul un manager annule une commande > 1000€ (Manager, approve, custom)
+```
+
+After the user confirms, Write the module's `règles-métier.md` with each rule's
+`## Permissions` block filled.
+
+## Edge cases
+
+| Situation | Action |
+|-----------|--------|
+| No actors yet (`acteur.md` empty/placeholder) | STOP. Access rules need actors — defer to `/ba-create-actors`. |
+| Rule spans several actor roles | One rule per actor — do not multiplex the actor field. |
+| `custom` scope but no clear condition text | Downgrade to `workflow` — `custom` is not a dumping ground. |
+| Access rule at resource level | Allowed, but check it is not really a field-level `validation`. |
+| User describes a permission, not a rule ("admins can do everything") | Skip the access rule, point at `/ba-create-rbac`. |
+
+## Quality checks before writing
+For each `access` rule: the `## Permissions` block is present and non-empty; each
+actor exists in `acteur.md`; the target level is at or below the rule's scope; the
+scope path is complete; `portée` is `all`/`own`/`team`/`custom` (custom carries a
+condition text); the rule still has ≥1 valid + ≥1 invalid example; the rule sits
+at application or module scope (challenge it if pushed lower).

package/templates/skills/business-analyse/create-business-rules/levels/elaborate.md

@@ -0,0 +1,193 @@
+---
+phase: rules
+kind: level
+level: elaborate
+---
+
+# Level 2 — ELABORATE
+
+> Turn a classified rule (Level 1) into a vibecoding-ready specification:
+> a natural `Condition`, a pseudo-code `Expression`, an error code, and
+> **at least one valid + one invalid example**. This is the most important
+> level — the quality of the generated code and tests depends on it. Persist
+> by re-Writing the scope's `règles-métier.md` (see `SKILL.md`).
+
+## Anatomy of a complete rule
+
+### Condition — natural language QUAND…ALORS / WHEN…THEN
+Always `QUAND <trigger> ALORS <constraint>`. Unambiguous, no passive voice,
+reference fields by name.
+
+| Weak | Strong |
+|------|--------|
+| "Users are validated" | "QUAND un utilisateur est créé/modifié ALORS son email doit être unique parmi les non-supprimés" |
+| "Status check" | "QUAND le statut d'une commande change ALORS le nouveau statut doit être un successeur valide" |
+| "Auto compute" | "QUAND une ligne de facture est ajoutée ALORS sous-total = quantité × prix unitaire" |
+
+### Expression — pseudo-code
+Compact, deterministic, a developer can implement without guessing (SQL-like,
+C#-like or math). It is a hint, not a contract.
+
+```
+// uniqueness
+NOT EXISTS(SELECT 1 FROM users WHERE LOWER(email)=LOWER(@email) AND id!=@id AND deleted_at IS NULL)
+// calculation
+vatAmount = round(baseAmount * vatRate, 2)
+// state transition
+@to IN { draft:[submitted,cancelled], submitted:[shipped,cancelled], shipped:[delivered] }[@from]
+// ownership
+@user.id == @ticket.assigneeId OR 'manager' IN @user.roles
+```
+
+### Error code — stable, namespaced
+`lower.dotted` (matching the module, e.g. `pipeline.discount.cap`) or
+`UPPER_SNAKE` (`USER_EMAIL_DUPLICATE`). Namespaced by module/entity.
+
+## Examples — the heart of the rule
+
+Each rule MUST have at least **1 valid** and **1 invalid** example. Non-negotiable
+(both the success and the failure path are needed to generate meaningful tests).
+Write them as concrete one-liners under `## Cas valides` / `## Cas invalides`, in
+Given/When/Then form when it helps:
+
+```
+- Email unique : aucun utilisateur 'alice@x.com' n'existe → POST /users {email:'alice@x.com'} → 201 créé.
+```
+
+### Two patterns: enforcement vs filter/visibility
+
+**Enforcement rule** — declares an error code. The invariant rejects an action;
+the invalid example names the error (e.g. "→ 409 `USER_EMAIL_DUPLICATE`").
+Examples: uniqueness, illegal transition, ownership check.
+
+**Filter / visibility rule** — **no error code** (leave it blank). The invariant
+silently excludes records (repository WHERE clause, soft-delete guard,
+anonymisation tombstone, tenant isolation). There is no user-facing error — the
+record is simply absent. The invalid example describes the **observable absence**
+("le contact n'apparaît PAS dans les résultats — filtré au niveau repository"),
+never a fake error.
+
+| Pattern | Rule error code | Invalid example |
+|---------|:---------------:|-----------------|
+| Enforcement | present | names the expected error |
+| Filter/visibility | blank | observable absence, no error |
+
+### Numbering rules — the extra spec
+
+A `numbering` rule defines how an entity's business code/reference is
+**generated** (not merely validated). Beyond the standard fields, capture in the
+Condition + Expression:
+
+- **Format** — a template of literals + tokens, e.g. `AFF-{YY}-{SEQ:4}` (`{YY}` /
+  `{YYYY}` year, `{MM}` month, `{SEQ:n}` zero-padded counter, `{TENANT}`…).
+- **Sequence scope** — what the counter is partitioned by: `tenant` (default for
+  tenant-isolated data), `global` (platform-wide), or `parent:<Entity>` (sub-count
+  inside a parent). MUST be consistent with the entity's `tenantMode`.
+- **Reset** — when the counter restarts: `none` / `yearly` / `monthly` / `daily`.
+  A reset MUST align with a matching date token in the format (yearly ⇒ `{YY}`).
+- **Gapless** — `true` (no gaps allowed — legal/accounting; needs transactional
+  allocation) or `false` (gaps tolerated — faster, e.g. on rollback).
+- **Immutable** — once assigned the code never changes (state it in the rule).
+
+These map 1:1 to the data-model `codePattern` (`create-data-model`) and drive the
+sequence allocator the Studio provides at runtime. The valid examples MUST show the
+sequence **progressing** and the **reset boundary**; an invalid example MUST show
+**no duplicate** under concurrency / across tenants.
+
+```markdown
+### BR-007 — Numéro de demande
+- **Type** : numbering
+- **Sévérité** : err
+- **Portée** : RH / DEMANDES
+- **Condition** : QUAND une demande est créée ALORS son numéro = `AFF-{YY}-{NNNN}`
+  (séquence par tenant, remise à zéro chaque année, sans trou, immuable).
+- **Expression** : `reference = "AFF-" + fmt(year,"yy") + "-" + pad(nextSeq(scope=tenant, reset=yearly), 4)`
+- **Code d'erreur** : `demande.reference.duplicate`
+- **Cas valides** :
+  - 1re demande 2026 (tenant A) → `AFF-26-0001` ; suivante → `AFF-26-0002`.
+  - 1re demande 2027 → `AFF-27-0001` (reset annuel).
+  - 1re demande tenant B en 2026 → `AFF-26-0001` (séquence isolée par tenant).
+- **Cas invalides** :
+  - Deux créations concurrentes → JAMAIS le même numéro (allocation atomique).
+  - Numéro modifié après création → rejeté (immuable).
+- **Cas d'usage liés** : UC-RH-DEMANDES-001 (postcondition)
+```
+
+### Coverage — aim for 3–5 on rules with edge cases
+1 valid happy path · 1 invalid clear failure · 1 invalid edge case · 1 valid edge
+case on the right side. Pick 2–3 relevant edge cases per type:
+
+| Type | Edge cases worth covering |
+|------|---------------------------|
+| `validation` | null, empty, max length, format mismatch, case-insensitive duplicate, whitespace-only |
+| `calculation` | zero, negatives, rounding (2 vs 4 decimals), currency conversion, division by zero |
+| `state-transition` | same-state (idempotent?), skipped state, concurrent transition, terminal state, re-entry |
+| `ownership` | owner ok, manager bypass, deactivated owner, ownership transfer, service account |
+| `constraint` | exactly at limit, just-above, just-below, zero, negative, null vs 0 |
+| `derivation` | missing/empty inputs, recompute on update vs create |
+| `workflow` | threshold exactly at boundary, multiple approvers, delegation, timeout |
+| `integrity` | soft-deleted parent, cascade delete, circular/self FK, orphaned children |
+| `cross-cutting` | system operation with no user, batch of N, async, retry |
+| `compliance` | retention expiry, erasure conflict, cross-border transfer, retroactive change |
+| `numbering` | first-of-period, sequence progression, per-tenant isolation, reset boundary (year rollover), concurrent allocation (no duplicate/gap if gapless) |
+
+Application-level rules: cover inter-module scenarios (audit trail across modules
+A→B). Module-level: show both authorized and unauthorized access patterns.
+
+## Worked example — a fully elaborated rule (doc form)
+
+```markdown
+### BR-001 — Email unique
+- **Type** : validation
+- **Sévérité** : err
+- **Portée** : HR / EMPLOYEES
+- **Condition** : QUAND un utilisateur est créé/modifié ALORS son email ne doit
+  matcher aucun email d'utilisateur non-supprimé (insensible à la casse).
+- **Expression** : `NOT EXISTS(SELECT 1 FROM users WHERE LOWER(email)=LOWER(@email) AND id!=@id AND deleted_at IS NULL)`
+- **Code d'erreur** : `USER_EMAIL_DUPLICATE`
+- **Cas valides** :
+  - Aucun 'alice@x.com' → créer {email:'alice@x.com'} → 201 créé.
+  - Email d'un utilisateur soft-deleted réutilisable → 201 créé (tombstone).
+- **Cas invalides** :
+  - 'bob@x.com' existe → créer {email:'bob@x.com'} → 409 `USER_EMAIL_DUPLICATE`.
+  - 'BOB@X.COM' → 409 `USER_EMAIL_DUPLICATE` (comparaison insensible à la casse).
+- **Cas d'usage liés** : UC-HR-EMPLOYEES-DIRECTORY-001 (précondition)
+```
+
+Filter-rule variant — `Code d'erreur` blank, invalid case = absence:
+
+```markdown
+### BR-014 — Contacts anonymisés exclus des recherches
+- **Type** : constraint
+- **Sévérité** : err
+- **Portée** : CRM / CONTACTS
+- **Condition** : QUAND une recherche de contacts s'exécute ALORS les contacts
+  avec `anonymizedAt` non nul sont exclus.
+- **Expression** : `WHERE contact.anonymizedAt IS NULL`
+- **Code d'erreur** : —
+- **Cas valides** : contact actif (anonymizedAt null) → présent dans la réponse.
+- **Cas invalides** : contact anonymisé → ABSENT de la réponse (filtré au
+  niveau repository, aucune erreur renvoyée).
+- **Cas d'usage liés** : —
+```
+
+## Workflow
+1. Pick the next rule with no examples (or no condition).
+2. Fill `Condition`, `Expression`, `Code d'erreur` (blank for filter rules).
+3. Write the valid example(s) first (the happy path), then the invalid one(s).
+4. Review: could a developer with no context turn this into code AND a test? If
+   not, add detail.
+5. Repeat for all rules at the scope, then re-Write the doc with the full set.
+
+## Ask the user only when truly ambiguous
+You usually have enough context to draft. Ask (via AskUserQuestion, 2–4 closed
+options) only for: a choice between two plausible error codes; a threshold
+constant ("max discount: 50 / 100 / no limit"); or an edge-case decision
+("soft-deleted users still block email reuse, or release it?").
+
+## Quality checks before writing
+For every rule: `Condition` is `QUAND…ALORS`; `Expression` is non-empty; the
+pattern is identified (enforcement → error code + invalid examples name it;
+filter → error code blank + invalid examples describe absence); every example has
+a concrete given/when/then; at least 1 valid + 1 invalid; a developer could code
+it and test it.