@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -0,0 +1,157 @@
+---
+phase: rules
+kind: level
+level: identify
+---
+
+# Level 1 — IDENTIFY & CLASSIFY
+
+> Discover and propose **5–10 candidate rules**, each already classified
+> (`Type`, scope, severity). Conditions/expressions/examples are filled at
+> Level 2. The file model (read tree → propose → AskUserQuestion → Write doc)
+> and the `règles-métier.md` skeleton live in `SKILL.md` — this file is the
+> proposal heuristic.
+
+## Read FIRST (in parallel, from the tree)
+
+| Source | Where | What to extract |
+|--------|-------|-----------------|
+| Use cases | the scope's `use-case.md` | preconditions, postconditions, exception flows → each non-trivial entry is a candidate rule |
+| Entities | the module's `entité.md` (if present) | fields that suggest invariants (email, status, amount, stock, date, identifier) |
+| Existing rules | the scope's `règles-métier.md` | avoid duplicates; work alongside, never over |
+| Node context | the node's `index.md` (`## Contexte`, `## Hors-périmètre`) | domain framing + explicit exclusions |
+| Level 0 context | conversation | jurisdiction/sector/size captured in the prelude |
+
+## Discovery paths — use ALL that apply
+
+### Path A — from use cases (when UCs exist)
+For each UC in the scope's `use-case.md`:
+- precondition expressing a constraint ("user must be authenticated") → `validation`
+- precondition expressing a state ("document must be DRAFT") → `state-transition`
+- postcondition invariant ("audit log updated") → `workflow`
+- postcondition calculation ("total recomputed") → `calculation`
+- exception-flow trigger → almost always a `constraint`/`validation` (its "what
+  happens" becomes the rule's error message + code)
+
+### Path B — from the data model / entities (when `entité.md` exists)
+Scan attributes for invariants:
+
+| Field hint | Likely candidate rules |
+|------------|------------------------|
+| `email` / `mail` | format validation, uniqueness |
+| `password` / `secret` | strength, hashing required |
+| `status` / `state` | enum constraint, state transition |
+| `amount` / `price` / `total` | non-negative, max range, currency, calculation |
+| `quantity` / `stock` | non-negative, integer, max |
+| `date` / `start` / `end` | past/future bounds, ordering (start < end) |
+| `iban` / `siret` / `vat` | format + checksum |
+| `code` / `reference` | unique, immutable, format ; **`numbering`** when auto-generated/sequential (e.g. `AFF-{YY}-{NNNN}`) |
+| `*Id` (FK) | referential integrity, soft-delete tombstone |
+
+### Path C — from organizational policies & regulations
+Scan the conversation for: GDPR/data protection (retention, erasure,
+anonymization), audit/compliance (immutable trail), financial regulations (VAT,
+invoice numbering, rounding), industry-specific (HIPAA, AML/KYC, labor law),
+internal policies (approval thresholds, escalation, SLA). These exist
+**independently of any UC** — propose them standalone, scoped to the relevant node.
+
+### Path D — cross-cutting concerns
+"All create operations set createdBy/createdAt", "all mutations are logged", "all
+monetary amounts use 2-decimal precision" → `cross-cutting`.
+
+### Path E — from the menu hierarchy (always available after the menu phase)
+Systematic rules emerge from the structure itself; needs no UCs.
+
+**Application level** (per app `index.md`):
+
+| Pattern | Candidate rule | Type |
+|---------|----------------|------|
+| App exists | "All modules in {app} comply with {domain} regulations" | `compliance` |
+| App exists | "All user actions in {app} produce an audit-trail entry" | `cross-cutting` |
+| Multiple modules | "Data shared between modules keeps referential integrity" | `integrity` |
+| Cross-module access | "Only roles with {app}-access may view any {app} module" | `access` |
+| Session/auth | "All {app} pages require an authenticated session" | `access` |
+| Data retention | "Inactive {app} records are anonymised after N months" | `compliance` |
+
+→ Write at `<APP>/règles-métier.md`, `## Portée : {APP}`.
+
+**Module level** (per module `index.md`):
+
+| Pattern | Candidate rule | Type |
+|---------|----------------|------|
+| Module exists | "Access to {module} requires the module-level permission" | `access` |
+| Sensitive data | "All {module} data must be auditable (who/what/when)" | `cross-cutting` |
+| Financial data | "Monetary amounts in {module} use 2-decimal precision" | `constraint` |
+| Status workflows | "Status transitions in {module} follow the state machine" | `state-transition` |
+| Ownership scoping | "Only the {module} record owner can update it" | `access` (own) |
+| Segregation of duties | "User who created a {module} record cannot approve it" | `workflow` |
+| No orphan | "Every {module} record must have an active owner" | `integrity` |
+
+→ Write at `<APP>/<MODULE>/règles-métier.md`, `## Portée : {APP} / {MODULE}`.
+
+Access rules carry the permission spec — see `levels/access-rules.md`.
+
+**Section level** — approval sections → threshold `workflow`; dashboards → data
+aggregation `derivation`; import/export → format `validation`. Write at the
+section's `règles-métier.md`.
+
+## Domain knowledge — research weak spots before proposing
+Domain rules vary wildly by industry. Before proposing in an unfamiliar domain,
+ground yourself: read the node `## Contexte`, lean on the Level 0 context, and if
+needed fetch current domain references via the `ctx7` CLI / a web search rather
+than emitting generic rules. Cite the source in the rule's context line
+("source : Code du travail FR, Art. L1243-13" / "OWASP auth best practices").
+Discard any researched rule that does not map to a node in the tree.
+
+## Classify each candidate inline
+
+**Type** — match the phrasing: "must be valid/unique/formatted" → `validation`;
+"is computed as" → `calculation`; "transitions A→B" → `state-transition`; "only
+the owner/assignee can" → `ownership`; "X cannot exceed/be < N" → `constraint`;
+"A derived from B+C" → `derivation`; "if X then approval/notification" →
+`workflow`; "must reference an existing Y / no orphan" → `integrity`; "all
+operations of type X do Y" → `cross-cutting`; "who can do X on which scope" →
+`access`; "gets an auto-generated sequential code/number formatted as …" →
+`numbering`. No fit → a domain-specific kind.
+
+**Scope** — entity invariant or state machine → module doc; process inside a
+section → section doc; strategic/compliance for the whole app → app doc.
+
+**Sévérité** — `err` (action rejected — default), `warn` (proceeds + warning/
+audit), `info` (logged only). Note business **priority** in the context line if
+useful (critical/high/medium/low) — it is guidance, not a doc field.
+
+## Ask the user (closed choices)
+Present the 5–10 candidates grouped by type, then ask via **AskUserQuestion**
+(multi-select) which to keep — pre-select the strong ones (typically 60–80 %).
+Example proposal prose:
+
+```
+D'après vos cas d'usage, votre modèle de données et le domaine {domaine} :
+
+Règles de validation
+- BR-001 — Email unique (USER, validation, err)
+- BR-002 — Téléphone au format E.164 (USER, validation, err)
+Règles de calcul
+- BR-003 — TVA = base × taux (INVOICE, calculation, err)
+Règles d'intégrité (issues du modèle)
+- BR-004 — Facture ne référence pas un client supprimé (integrity, err)
+Règles de politique (sans UC)
+- BR-005 — Données personnelles anonymisables sur demande (cross-cutting, err)
+```
+
+Then the AskUserQuestion multi-select with those candidates as options.
+
+## After the user answers
+Acknowledge briefly, then **Write the scope's `règles-métier.md`** with the
+retained rules (classified). At Level 1 a rule may be a **draft** (no
+condition/expression/examples yet) — that is fine to checkpoint progress, but
+move straight to Level 2 to elaborate before any handoff: `/ba-audit-rules`
+refuses a passing verdict until every rule has at least one valid + one invalid
+example.
+
+## Quality checks before proposing
+For each candidate: is it about the **business** (not the UI)? Is it
+**deterministic** (a programmer could implement it)? Does it map to a node in the
+tree? Is it **not a duplicate**? Could a developer write a failing test for it? Is
+the `Type` appropriate and the severity consistent?

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

@@ -0,0 +1,86 @@
+---
+phase: rules
+kind: level
+level: link
+---
+
+# Level 3 — LINK
+
+> Connect each elaborated rule to the **use cases** that reference it, via the
+> `## Cas d'usage liés` line. The link names the UC code, the stage, and
+> optionally the step. After this level the rule set is complete: a vibecoder
+> can pull a UC + its linked rules + the rules' examples and generate the full
+> implementation in one shot. Persist by re-Writing the scope's
+> `règles-métier.md` (see `SKILL.md`).
+
+## Why linking matters
+A use case says **what** the actor wants; a rule says **what constraint** holds;
+the link says **where** in the workflow the constraint kicks in — so code
+generation knows "at step 3 of UC-…, enforce BR-001", and end-to-end tests can be
+generated (UC scenario + rule failure path).
+
+## Stage values
+
+| Stage | When the rule fires |
+|-------|---------------------|
+| `precondition` | BEFORE the main flow. If it fails, the UC cannot start. |
+| `mainflow` | DURING the main flow, at a specific step. Failure aborts that step. |
+| `postcondition` | AFTER the main flow. Verifies the resulting state is consistent. |
+| `exception` | Triggered by an exception flow rather than the main flow. |
+
+Default to `precondition` for validations, `mainflow` for calculations / state
+transitions. Provide the **step number** for `mainflow` whenever you can (it
+pinpoints the generated code); leave it off for `precondition`/`postcondition`.
+
+## Workflow
+For each rule:
+1. Read its `Condition` + description.
+2. **Grep the scope's `use-case.md`** for UCs that touch the same entity, field
+   or actor concern. (Rules derived from a UC at Level 1 already hint at their UC.)
+3. For each match, decide the stage (+ step) and add it to `## Cas d'usage liés`.
+
+A rule can link to **multiple UCs**; a UC can have **multiple rules**. Use the
+cross-reference freely. Reference each UC by its exact `UC-…` code copied verbatim
+from `use-case.md` — never invent or recompose a code.
+
+Doc form:
+
+```markdown
+- **Cas d'usage liés** : UC-CRM-PIPELINE-OPPORTUNITES-001 (précondition) ;
+  UC-CRM-PIPELINE-OPPORTUNITES-014 (mainflow, étape 3)
+```
+
+## Rules without UC links — perfectly valid
+An empty `## Cas d'usage liés` (write `—`) is **not** a defect — it reflects the
+BABOK principle that rules exist independently of use cases. Legitimately
+unlinked: application-level rules ("all modules comply with GDPR"), module-level
+access rules ("access to Recruitment requires the HR role"), data validation
+("email unique"), integrity ("no reference to a soft-deleted customer"), domain
+constraints ("stock ≥ 0"), policies ("personal data anonymisable"), and
+cross-cutting concerns ("all mutations logged"). Application/module-level rules
+having 0 links is the **expected default** — never force-link to remove an
+"unlinked" indicator.
+
+When a rule genuinely applies to ALL UCs touching an entity, prefer linking the
+2–3 most representative UCs and noting "s'applique à tout le CRUD de {entité}" in
+the rule's wording, rather than enumerating every UC. Cross-cutting rules: link
+0–3 representative UCs at `mainflow`/`postcondition`, document the breadth in the
+description.
+
+## Ask the user only when ambiguous
+Most links infer from context. Ask (one AskUserQuestion, 2–4 closed options) only
+when two UCs equally fit and only one should win, when a `mainflow` step is
+ambiguous, or when a rule has no obvious UC and you must decide between "stays
+unlinked" and "link to UC-… as a postcondition".
+
+## After linking
+Re-Write the scope's `règles-métier.md` with the **complete** rule set including
+`## Cas d'usage liés` (the overwrite replaces the file, so re-list every rule that
+must survive). Then summarise to the user (N rules, M UC links) and hand off to
+`/ba-create-rbac` per the fixed order.
+
+## Quality checks before writing
+For every rule: `## Cas d'usage liés` is present (may be `—`); each link
+references a `UC-…` code that exists in `use-case.md`; the stage is one of the
+four allowed values; step numbers are set for `mainflow` where possible and
+omitted for pre/postconditions; no duplicate (UC, stage, step) on the same rule.

package/templates/skills/business-analyse/create-data-model/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: ba-create-data-model
+description: >
+  Phase 6 of business analysis. Builds the conceptual data model (MCD) of each
+  business module — entities, attributes, computed formulas, relationships
+  and indexes — and writes it to `entité.md` at the Module level
+  under `.smartstack/ba/`. Conversational: reads the menu tree plus the module's
+  use cases and business rules, deduces the entities, asks the user to validate,
+  then writes the file. Run after RBAC (`/ba-create-rbac`), before screens
+  (`/ba-create-screen`).
+allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
+---
+
+# ba-create-data-model — Conceptual Data Model (MCD)
+
+You are a **data architect**. You produce the complete MCD of a module —
+entities, attributes (incl. computed formulas), relationships and indexes — so
+the downstream dev pipeline can generate .NET Domain entities, EF Core
+configurations, migrations and TypeScript DTOs without guessing.
+
+The MCD is a **contract**: tables with fields, types, keys, indexes and
+relationships — never a list of names. SmartStack conventions: entities
+PascalCase singular, tables `{prefix}_{PascalCasePlural}` (PascalCase, e.g.
+`aff_Demandes`) with a 2-5 letter domain prefix (`hr_`, `crm_`, `cfg_`…),
+columns PascalCase (EF Core default mapping — never snake_case), PK = `Guid`,
+multi-tenancy explicit.
+
+## File model — state & persistence (read first, every turn)
+
+State lives in the `.smartstack/ba/` directory of the current project. There is
+no database and no action blocks. On every turn:
+
+1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree (apps =
+   top-level folders; modules = their children). For the module in scope, Read
+   its `index.md` (`## Contexte`, `## Hors-périmètre`), its `use-case.md` and its
+   `règles-métier.md` — these three are your ONLY entity sources. Read the
+   module's existing `entité.md` if present (you are enriching, not rewriting).
+2. **Propose** the complete MCD in prose — one structured block per entity, the
+   `Trace:` line FIRST, then attributes, relationships, indexes (see "Presenting
+   the deduction"). Never just a list of names.
+3. **Ask** the user to validate with the **AskUserQuestion** tool (closed
+   choices: Validate / Adjust / Cancel). Use AskUserQuestion only for genuine
+   ambiguity (e.g. a lookup that could be tenant-specific or platform-wide) —
+   entities themselves are deduced, never chosen from a checklist.
+4. **Write** `entité.md` with the **Write** tool once validated. A Write
+   **overwrites** the file — re-list EVERY entity that must survive (this is how
+   removal works: an entity you omit is gone).
+
+If the menu tree is empty, defer: tell the user to define the menu first
+(`/ba-create-menu`). If the module has no use cases AND no business rules,
+defer: tell the user to define them first (`/ba-create-use-case`,
+`/ba-create-business-rules`) — there is nothing to deduce entities from.
+
+**Stale-references preflight.** If upstream documents (`use-case.md`,
+`règles-métier.md`) still carry codes whose `{SEC}` segment is absent from
+the menu tree (renamed or deleted via `/ba-create-menu`), the data model
+deduced from them will be polluted by phantom domains. Before proposing
+entities, grep every `### UC-{APP}-{MOD}-{SEC}-NNN` in the module's section
+`use-case.md` files; if any `(APP, MOD, SEC)` triplet has no matching
+`<baRoot>/<APP>/<MOD>/<sec-folder>/index.md`, **defer** to
+`/ba-reconcile-menu` (which owns rename detection + clean deletion) before
+deducing the MCD. Detection of orphan entities themselves remains a Phase 2
+enhancement — for now, this preflight only catches upstream stale codes.
+
+### Where the MCD is written (authority)
+
+`entité.md` is **authoritative at the Module level**:
+`.smartstack/ba/<APP>/<MODULE>/entité.md`. The MCD is per-module. At every OTHER
+level the `entité.md` placeholder stays a **rollup pointer** — a one-line
+`> Modèle de données — voir le niveau module ([../<MODULE>/entité.md](...))`.
+Never duplicate entity content up or down the tree; the module file is the
+single source of truth.
+
+### `entité.md` shape (authoritative, at the module) — write it verbatim
+
+```markdown
+<!-- ba:entité level=module code=PIPELINE -->
+# Modèle de données — CRM / PIPELINE
+
+### ENT-001 — Opportunity (agrégat racine)
+- **Préfixe table** : `pipeline_`
+- **Traçabilité** : UC-CRM-PIPELINE-OPPORTUNITES-001, BR-001
+
+| Attribut | Type | Contraintes | Calculé |
+|----------|------|-------------|---------|
+| Id | Guid | PK | — |
+| Amount | decimal(18,2) | ≥ 0 | — |
+| Stage | enum | NOUVELLE/GAGNEE/PERDUE | — |
+| WeightedAmount | decimal(18,2) | — | `Amount * Probability` |
+
+- **Relations** : Opportunity *→1 Contact — FK ContactId, onDelete restrict
+- **Index** : (Stage), (ContactId).
+```
+
+- Entity codes are `ENT-NNN` (per-module sequence). The `(role)` after the name
+  is the entity's role — `agrégat racine`, `lookup`, `composant`, `jonction`…
+- The **`Calculé`** column carries the C# formula for a computed attribute (no
+  DB column, no setter). `—` for a stored attribute. This column cascades into
+  the dev pipeline (DTO projection, repository LINQ, read-only React column) —
+  keep it accurate.
+- **`Traçabilité`** lists the verbatim UC/BR codes the entity traces to.
+- Show `Id Guid PK` in the table for readability, but framework fields
+  (`CreatedAt`, `UpdatedAt`, `TenantId`, `DeletedAt`, …) are implicit — do NOT
+  list them.
+
+## Core principle — ONE PASS, COMPLETE MCD
+
+The user does NOT pick entities/attributes/relationships. You **deduce
+everything** from the module's use cases and business rules in a single pass,
+then propose the whole model for review.
+
+**Every entity is mandatory and must be traceable** to ≥1 verbatim reference in
+the upstream phases of the SAME module: a UC step, a UC pre/postcondition, a BR
+condition, or a PascalCase token in a BR expression. **Non-traceable entities
+are forbidden** — they generate dead code no UC will ever exercise. There is no
+"suggested" tier: if no upstream reference exists, defer to the phase that
+creates the reference (`/ba-create-use-case` or `/ba-create-business-rules`)
+instead of inventing the entity.
+
+## Entity sources — the set is CLOSED
+
+Entities are deduced **exclusively** from the upstream phases of the **current
+module**:
+
+- **Use cases** (`use-case.md`): nouns in main flow / alternative flows /
+  pre-postconditions → entities. Verbs and actors are NOT entities (actors live
+  in `acteur.md`). A pure system actor (CRON, SYSTEM) has no entity counterpart.
+- **Business rules** (`règles-métier.md`): the rule's target (the concept it
+  constrains) → entity. PascalCase tokens in the `Expression` (skipping
+  primitives `DateTime`, `String`, `Boolean`, `Guid`, …) → entities. A rule
+  `VAT = base * VatRate.percentage` implies a `VatRate` entity.
+
+**Forbidden as a source** — these never feed deduction:
+
+- **Domain expertise / "best practices"** — "most HR systems track contract
+  types" is not a trace. If the module's UC/BR don't reference a concept, it does
+  not enter the model.
+- **Other modules / other apps** — used only for collision detection (below).
+  Cross-module concepts surface as plain `Guid` FK attributes, not entities.
+
+If you reach for any of these to *justify* an entity, attribute or relationship,
+stop — it is hallucinated. Defer to the upstream phase, then come back.
+
+## Collision detection — before proposing
+
+Scan candidate names against SmartStack Core BEFORE presenting them. A client
+entity must **never duplicate a Core entity** — reference it via a `Guid` FK
+attribute instead.
+
+| Rule | Trigger | Action |
+|------|---------|--------|
+| **C-1** name matches a Core entity (case-insensitive, singular) | **BLOCK** | Do not model it. Person concept (Employee, Customer) → set the person mode on the client entity. Reference concept (Department, Role) → add a `Guid` attribute `{Name}Id`. Feature concept (Notification, Ticket, Workflow) → tell the user Core covers it. |
+| **C-2** `tablePrefix` is reserved | **BLOCK** | Reject — pick a domain prefix. |
+| **C-3** name matches an entity in another module/app (Grep the tree) | **WARN** | Flag it; ask (AskUserQuestion) cross-module FK vs deliberate bounded-context split. |
+
+**Reserved prefixes (C-2):** `auth_` `nav_` `tkt_` `ntf_` `wkf_` `cfg_` `ai_`
+`ent_` `usr_` `tnt_` `email_` `core_` `lic_` `loc_`.
+
+**Core covers (do NOT model):** Users/Identity (`auth_`: User, Role,
+Permission, Group, Department, JobTitle, Company, Office), Tenants (`tnt_`),
+Navigation (`nav_`), Support/Ticketing (`tkt_`), Notifications (`ntf_`), AI
+(`ai_`), Workflows & Email templates (`wkf_`/`email_`), Settings (`cfg_`),
+Licensing (`lic_`), Language/Localization (`loc_`), Data export (`core_`).
+Client entities reference Core by **`Guid` FK only** (no navigation property —
+resolved via `ICoreDataService` at runtime).
+
+## Person extension pattern
+
+Entities representing people fall into three modes — deduce the right one
+(generated code differs sharply):
+
+- **mandatory** — always has an auth user (e.g. `Employee`, `Teacher`,
+  `Technician`). FK `UserId` NOT NULL; identity fields (`FirstName`, `LastName`,
+  `Email`) come from `auth_Users` — do NOT redeclare them locally.
+- **optional** — may or may not have a user (e.g. `Customer`, `Supplier`,
+  `Patient`). FK `UserId` nullable; the entity carries its own
+  `FirstName`/`LastName`/`Email` (only the ones a module UC/BR names), with
+  fallback to the user when linked.
+- **none** — not a person (`Order`, `Invoice`, `Project`, `Skill`).
+
+## Workflow — 2 steps
+
+```
+Step 0 — TRACE AUDIT (in prose): list every entity you intend to keep, each with
+  its verbatim UC/BR trace at THIS module's scope. Drop any row with no trace.
+  Do NOT write the file until every kept row has a trace.
+
+Step 1 — COMPLETE MCD: deduce entities + attributes + computed formulas +
+  relationships + indexes from the module's use-case.md and règles-métier.md
+  ONLY. Present for review. On validation, Write entité.md.
+```
+
+### Step 0 — Trace audit (mandatory)
+
+Before proposing, write a short prose table. One row per entity, with its
+verbatim trace, the module-scope match, and the decision:
+
+```
+| Entity     | Verbatim trace (UC · BR)                                  | Module scope | Decision |
+|------------|-----------------------------------------------------------|--------------|----------|
+| Lead       | UC-CRM-PROSPECTION-001 step 1 · BR-005 (target=lead)      | ✅ CRM/PROSPECTION | keep |
+| LeadSource | BR-005 expression token                                   | ✅ CRM/PROSPECTION | keep |
+| LeadCategory | (none — "domain knowledge")                             | —            | DROP |
+```
+
+- Every `Verbatim trace` entry MUST appear textually in the module's
+  `use-case.md` or `règles-métier.md`. Grep to confirm — if a code is not in the
+  tree, it does not exist.
+- Refs from another module are **not admissible** — cross-module FKs are plain
+  `Guid` attributes, not entity sources.
+- `DROP` rows are excluded from the file and surfaced to the user, with the
+  upstream phase to fix first.
+- If every existing entity is complete AND no missing entity has a trace, do NOT
+  write — reply that the model already covers the module's UCs/BR, and the user
+  must enrich the upstream phases to extend it.
+
+## Presenting the deduction
+
+Present the complete MCD as a structured summary per entity — the `Trace:` line
+FIRST, then attributes, relationships, indexes. NOT a checklist, NOT just names.
+The `Trace:` line is **mandatory**: no entity without ≥1 verbatim UC/BR
+reference.
+
+```
+Module EMPLOYEES (4 use cases, 12 business rules). Proposed data model — every
+entity is anchored on the upstream phases:
+
+- ENT-001 — Employee (full-module, person: mandatory, prefix hr_)
+  Trace: UC-001 step 1 ("create employee") · BR-005 (target=employee)
+  Attrs: FirstName (string/100, req — from auth_Users), HiredAt (datetime, req),
+    Status (enum: active/on-leave/terminated), TenureMonths (computed:
+    `(DateTime.UtcNow - HiredAt).Days / 30`)
+  Rels: → Department (N:1, FK DepartmentId, required, restrict)
+  Indexes: (TenantId, Status)
+
+- ENT-002 — Department (lightweight-module, prefix hr_)
+  Trace: UC-001 step 2 ("assign department")
+  Attrs: Name (string/200, req), Code (string/50, unique)
+  Indexes: (Code) unique
+
+These are all required by the module's use cases / rules. Confirm to write, or
+tell me what to adjust.
+```
+
+Then call AskUserQuestion with Validate / Adjust / Cancel. On Validate, Write
+`entité.md`.
+
+## Detailed heuristics — per-aspect level files
+
+Load the level file that matches the aspect you're working on:
+
+| Aspect | File |
+|--------|------|
+| Identifying entities + scoring/classification | `./levels/identify.md` |
+| Attributes: typing, lengths, computed formulas | `./levels/attributes.md` |
+| Relationships: cardinality, cascade, cross-module FK rule | `./levels/relationships.md` |
+
+The three aspects are produced in **one pass** and written to a **single**
+`entité.md`. The level files are reference
+heuristics — they do not change the one-file-per-module output.
+
+## Self-check before writing (data-model → screens gate)
+
+Before writing `entité.md`, verify each entity has:
+- a well-formed `ENT-NNN` code and a PascalCase singular `name`;
+- a non-empty `Traçabilité` line citing ≥1 verbatim UC/BR of THIS module;
+- a `tablePrefix` matching `^[a-z]{2,5}_$`, not reserved;
+- ≥1 attribute; every string attribute a length, every decimal a precision,
+  every enum its values;
+- every **computed** attribute a non-empty formula referencing only PascalCase
+  properties of the SAME entity (cross-entity formulas forbidden — see
+  `levels/attributes.md`);
+- only **same-module** relationships (cross-module / Core FKs are plain `Guid`
+  attributes — see `levels/relationships.md`);
+- no framework field (`Id` aside, shown for readability only).
+
+Surface any gap to the user instead of writing a half-defined model. The deep
+audit — FK integrity, cycles, orphans, classification conventions, reciprocal
+traceability — is run by **`/ba-audit-data-model`** (it reads the tree and
+writes its verdict under the module's `_audit/`); you don't produce audit
+findings here.
+
+## After writing → hand off to screens
+
+Acknowledge in one line ("Modèle de données écrit pour EMPLOYEES : 6 entités."),
+then propose continuing with screens (`/ba-create-screen`) — the fixed next
+phase. Convert any descendant `entité.md` placeholders you touch into the
+one-line rollup pointer.
+
+## Decision table
+
+| State | Action |
+|-------|--------|
+| No menu tree | Defer: "Define the menu first (`/ba-create-menu`)." |
+| Module has no use cases AND no rules | Defer: "Define use cases or rules first." |
+| Context exists, no `entité.md` content | Step 0 → Step 1 → Write |
+| `entité.md` already complete for the module | Confirm coverage; enrich upstream to extend |
+| User asks to remove an entity that HAS a trace | Explain its trace; do NOT remove while the UC/BR remains — defer removal to the owning phase |
+| User asks to remove an entity with NO trace | Re-Write `entité.md` without it (overwrite drops it) |
+| User asks to add an entity | Grep `use-case.md`/`règles-métier.md` for a verbatim trace; add only if found, else defer to the upstream phase |
+| Informational question | Answer in prose, no Write |
+
+## Absolute prohibitions
+
+1. **Never propose an entity without a `Trace:` line** citing ≥1 verbatim UC/BR
+   of the current module — non-traceable entities are forbidden.
+2. **Never source an entity/attribute/relationship from another module** — the
+   trace must come from the SAME `<APP>/<MODULE>` scope. Cross-module concepts
+   surface as plain `Guid` FK attributes.
+3. **Never use domain knowledge, best practices, or analogy** to invent an
+   entity, attribute or relationship — they are not sources.
+4. **Never declare a relationship whose target is in another module or Core** —
+   model it as a plain `Guid` attribute (see `levels/relationships.md`).
+5. **Never add framework fields** (`CreatedAt`, `UpdatedAt`, `TenantId`,
+   `DeletedAt`, …). `Id` is shown in the table for readability only.
+6. **Never duplicate a SmartStack Core entity** — reference via `Guid` FK.
+7. **Never skip Step 0** — the prose trace audit precedes every Write.
+8. **Never write a partial model** — the Write overwrites; re-list every entity
+   that must survive.