@atlashub/smartstack-cli 4.52.0 → 4.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.52.0",
+  "version": "4.53.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/business-analyse/references/canonical-json-formats.md

@@ -0,0 +1,200 @@
+# Canonical JSON Formats Reference
+
+> **Purpose:** Single source of truth for all JSON file formats produced by the BA pipeline.
+> **Used by:** `/business-analyse` (step-03), `/business-analyse-design` (step-01), `/business-analyse-html`, `/business-analyse-handoff`, `/business-analyse-develop`
+> **Rule:** All producers MUST write canonical format. All consumers MUST accept canonical + deprecated fallbacks.
+
+---
+
+## entities.json
+
+```json
+{
+  "entities": [
+    {
+      "name": "Employee",
+      "description": "...",
+      "personRoleConfig": { "variant": "mandatory", "userFields": ["firstName", "lastName", "email"] },
+      "attributes": [
+        { "name": "code", "type": "string", "required": true, "description": "..." },
+        { "name": "userId", "type": "string", "required": true, "description": "FK auth_Users (ASP.NET Identity)" }
+      ],
+      "versionedAttributes": [
+        { "entity": "Salary", "attributes": ["grossAmount", "effectiveDate"], "reason": "..." }
+      ],
+      "relationships": [
+        { "target": "Department", "type": "ManyToOne", "description": "..." }
+      ]
+    }
+  ]
+}
+```
+
+**Convention guards:**
+- Person entities → `personRoleConfig` + `userId` (string), NO firstName/lastName/email
+- Versioned data → `versionedAttributes[]`, NOT inline fields
+- FK naming → always `{entity}Id` suffix
+- FK to auth_Users → type `string` (ASP.NET Identity), NOT `guid`
+
+---
+
+## usecases.json
+
+```json
+{
+  "useCases": [
+    {
+      "id": "UC-MODULE-001",
+      "name": "Créer un employé",
+      "sectionCode": "list",
+      "primaryActor": "Responsable RH",
+      "preconditions": ["..."],
+      "mainScenario": [
+        "L'utilisateur ouvre la page de création",
+        "Il remplit les champs obligatoires"
+      ],
+      "alternativeScenarios": [
+        { "name": "Données invalides", "steps": ["Le système affiche les erreurs"] }
+      ],
+      "businessRules": ["BR-VAL-MODULE-001"],
+      "result": "L'entité est créée"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `useCases` (root) | `usecases` | camelCase is canonical |
+| `primaryActor` | `actor` | |
+| `mainScenario` (string[]) | `steps` (object[] or string[]) | MUST be strings, never `{step, action}` objects |
+| `alternativeScenarios` (object[]) | `alternativeFlows`, `alternative` (string) | Must be `[{name, steps}]` |
+
+---
+
+## rules.json
+
+```json
+{
+  "rules": [
+    {
+      "id": "BR-VAL-MODULE-001",
+      "name": "Validation date",
+      "category": "validation",
+      "sectionCode": "list",
+      "statement": "La date ne peut pas être dans le futur",
+      "example": "Date = 2027-01-01 → erreur",
+      "entities": ["Employee"],
+      "severity": "blocking"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives |
+|---------------|------------------------|
+| `rules` (root) | `businessRules` |
+| `statement` | `description` |
+| `id` | `name` (as identifier) |
+
+Categories: `validation`, `calculation`, `workflow`, `security`, `data`, `notification`
+
+---
+
+## permissions.json
+
+```json
+{
+  "roles": [
+    { "role": "RH Admin", "description": "..." }
+  ],
+  "permissionPaths": [
+    "HumanResources.Employees.Read",
+    "HumanResources.Employees.Create"
+  ],
+  "matrix": {
+    "roleAssignments": [
+      { "role": "RH Admin", "permissions": ["HumanResources.Employees.*"] }
+    ]
+  }
+}
+```
+
+---
+
+## screens.json
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employés",
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "label": "Grille des employés",
+          "columns": [
+            { "field": "code", "label": "Code", "type": "text", "sortable": true }
+          ],
+          "filters": [
+            { "field": "status", "type": "select", "label": "Statut" }
+          ],
+          "actions": ["create", "export"],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `sections` (root) | `screens` (flat array) | `sections[]` with `resources[]` is canonical |
+| `sectionCode` | `id`, `code` | |
+| `sectionLabel` | `displayName`, `label` | |
+| resource `type` | `layout`, `componentType` | Must be: SmartTable, SmartForm, SmartDashboard, SmartKanban, SmartCard, SmartFilter |
+| column `field` | `code`, `name`, `id`, `fieldCode` | |
+| column `label` | `displayName` | |
+
+**DEPRECATED format (do NOT produce):**
+```json
+{
+  "screens": [
+    { "screen": "employees-list", "section": "list", "componentType": "SmartTable", "columns": [...] }
+  ]
+}
+```
+
+---
+
+## Consumer normalization pattern
+
+All downstream consumers should normalize input using this priority chain:
+
+```javascript
+// usecases
+const rawUCs = data.useCases || data.usecases || [];
+const uc = {
+  name: raw.name || raw.title || raw.id,
+  actor: raw.primaryActor || raw.actor,
+  steps: (raw.mainScenario || raw.steps || []).map(s =>
+    typeof s === 'string' ? s : (s.action || s.description || "")
+  ),
+  alternatives: raw.alternativeScenarios || raw.alternativeFlows || []
+};
+
+// screens
+const sections = data.sections || [];
+const flatScreens = data.screens || [];
+// If flat format: wrap each screen as a section with 1 resource
+
+// columns
+const col = {
+  field: raw.field || raw.code || raw.name || raw.id,
+  label: raw.label || raw.displayName || raw.code,
+  type: raw.renderAs === "badge" ? "badge" : (raw.type || raw.dataType || "text")
+};
+```

package/templates/skills/business-analyse/steps/step-03-specify.md

@@ -54,25 +54,56 @@ For each entity identified in step 02:
 {
   "name": "Employee",
   "description": "Représente un employé de l'entreprise",
+  "personRoleConfig": { "variant": "mandatory", "userFields": ["firstName", "lastName", "email"] },
   "attributes": [
-    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique" },
-    { "name": "userId", "type": "guid", "required": true, "description": "Référence vers l'utilisateur" },
+    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique auto-généré" },
+    { "name": "userId", "type": "string", "required": true, "description": "FK vers auth_Users (ASP.NET Identity — type string, NOT guid)" },
     { "name": "departmentId", "type": "guid", "required": true, "description": "Département d'affectation" },
     { "name": "hireDate", "type": "date", "required": true, "description": "Date d'embauche" },
     { "name": "position", "type": "string", "description": "Poste occupé" },
-    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "defaultValue": "Active", "description": "Statut de l'employé" },
-    { "name": "salary", "type": "decimal", "validation": { "min": 0 }, "description": "Salaire mensuel" }
+    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "defaultValue": "Active", "description": "Statut de l'employé" }
+  ],
+  "versionedAttributes": [
+    { "entity": "Salary", "attributes": ["grossAmount", "netAmount", "effectiveDate", "currency"], "reason": "Historique salarial versionné" }
   ],
   "estimatedVolume": { "monthly": 50, "total2y": 1200 },
   "searchableFields": ["code", "position", "status"],
   "defaultFilters": ["status"],
   "relationships": [
     { "target": "Department", "type": "ManyToOne", "description": "Appartient à un département" },
-    { "target": "Contract", "type": "OneToMany", "description": "Possède plusieurs contrats" }
+    { "target": "Contract", "type": "OneToMany", "description": "Possède plusieurs contrats" },
+    { "target": "Salary", "type": "OneToMany", "description": "Historique de salaires versionnés" }
   ]
 }
 ```
 
+### B-bis. SmartStack Entity Convention Guards (MANDATORY)
+
+Before finalizing each entity, apply these rules:
+
+**B-bis-1. Person Extension Pattern** (ref: `entity-architecture-decision.md` section 0)
+IF the entity matches a person role (Employee, Customer, Manager, Consultant, etc.):
+- **DO NOT** add firstName, lastName, email, phoneNumber as direct attributes
+- **DO** add `userId` (type: `string`, FK to auth_Users — ASP.NET Identity uses string IDs)
+- **DO** add `personRoleConfig` metadata with variant (mandatory/optional)
+- Personal fields come from User, not from the domain entity
+
+**B-bis-2. Versioned Sensitive Data**
+IF the entity has attributes that change over time with audit requirements (salary, rate, grade):
+- **DO NOT** put them directly on the entity as single fields
+- **DO** extract into a versioned satellite table (e.g., Employee → Salary with effectiveDate)
+- Mark with `"versionedAttributes"` in entity spec
+
+**B-bis-3. SmartStack Socle Entities (NEVER redefine)**
+- Users/Identity → `auth_Users` (managed by SmartStack Identity)
+- Tenants → `tenant_Tenants` (managed by SmartStack Core)
+- Departments → `ref_Departments` or `rh_Departments` (check if exists in target DB)
+
+**B-bis-4. Foreign Key Conventions**
+- All FK attributes MUST end with `Id` suffix (e.g., `departmentId`, `userId`)
+- FK to Identity users MUST use type `string` (ASP.NET Identity convention, NOT guid)
+- FK to domain entities MUST use type `guid`
+
 ### C. Business Rules
 
 For each entity/process, identify rules. **Each rule MUST specify `sectionCode`** matching a code from `anticipatedSections[]`:
@@ -111,23 +142,39 @@ Exemple de règle de calcul :
 
 For each stakeholder action. **Each use case MUST specify `sectionCode`** matching a code from `anticipatedSections[]` — this links the UC to the screen/page where it happens:
 
+> **CANONICAL FORMAT (MANDATORY):** The usecases.json file MUST use these exact keys:
+> - Root key: `"useCases"` (camelCase, NOT "usecases")
+> - Actor field: `"primaryActor"` (NOT "actor")
+> - Steps field: `"mainScenario"` (string[], NOT "steps" with objects)
+> - Alternatives: `"alternativeScenarios"` (object[] with `{name, steps}`, NOT "alternative" as flat string)
+> - This matches specification-schema.json. Deviation causes normalization overhead in 4+ downstream skills.
+
 ```json
 {
-  "id": "UC-EMPLOYEES-001",
-  "name": "Créer un employé",
-  "sectionCode": "list",
-  "actor": "Responsable RH",
-  "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
-  "steps": [
-    "L'utilisateur ouvre la page de création",
-    "Il remplit les champs obligatoires (nom, département, date embauche)",
-    "Il valide le formulaire",
-    "Le système vérifie les règles métier (BR-VAL-EMPLOYEES-001)",
-    "Le système crée l'employé et affiche la fiche"
-  ],
-  "alternative": "Si les données sont invalides, le système affiche les erreurs",
-  "businessRules": ["BR-VAL-EMPLOYEES-001"],
-  "result": "L'employé est créé avec le statut 'Actif'"
+  "useCases": [
+    {
+      "id": "UC-EMPLOYEES-001",
+      "name": "Créer un employé",
+      "sectionCode": "list",
+      "primaryActor": "Responsable RH",
+      "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
+      "mainScenario": [
+        "L'utilisateur ouvre la page de création",
+        "Il remplit les champs obligatoires (nom, département, date embauche)",
+        "Il valide le formulaire",
+        "Le système vérifie les règles métier (BR-VAL-EMPLOYEES-001)",
+        "Le système crée l'employé et affiche la fiche"
+      ],
+      "alternativeScenarios": [
+        {
+          "name": "Données invalides",
+          "steps": ["Le système affiche les erreurs de validation", "L'utilisateur corrige et re-soumet"]
+        }
+      ],
+      "businessRules": ["BR-VAL-EMPLOYEES-001"],
+      "result": "L'employé est créé avec le statut 'Actif'"
+    }
+  ]
 }
 ```
 
@@ -250,6 +297,33 @@ for (const mod of modules) {
     for (const a of (e.attributes || [])) {
       if (!a.type) warnings.push(mod.code + ": entity " + e.name + " attr '" + a.name + "' missing type");
       if (a.type === 'enum' && !a.defaultValue) errors.push(mod.code + ": enum attr '" + a.name + "' missing defaultValue");
+      // FK naming convention: must end with "Id"
+      if ((a.type === 'guid' || a.type === 'string') && a.foreignKey && !a.name.endsWith('Id'))
+        warnings.push(mod.code + ": entity " + e.name + " FK attr '" + a.name + "' should end with 'Id'");
+    }
+    // Person Extension Pattern check
+    const personFields = ['firstName', 'lastName', 'email', 'phoneNumber', 'phone'];
+    const foundPersonFields = (e.attributes || []).filter(a => personFields.includes(a.name));
+    if (foundPersonFields.length >= 3 && !e.personRoleConfig) {
+      errors.push(mod.code + ": entity '" + e.name + "' has " + foundPersonFields.length +
+        " person fields (" + foundPersonFields.map(f => f.name).join(", ") +
+        ") but no personRoleConfig — use Person Extension Pattern (entity-architecture-decision.md section 0). " +
+        "Person fields (firstName, lastName, email) belong on auth_Users, not on the domain entity.");
+    }
+  }
+
+  // Canonical usecases key check
+  const rawUCFile = READ(mod.dir + '/usecases.json');
+  if (rawUCFile && !rawUCFile.useCases && rawUCFile.usecases) {
+    errors.push(mod.code + ": usecases.json uses 'usecases' key instead of canonical 'useCases' — fix before proceeding");
+  }
+  // Check steps serialization format
+  for (const uc of ucs) {
+    if (uc.steps && Array.isArray(uc.steps) && uc.steps.length > 0 && typeof uc.steps[0] === 'object') {
+      errors.push(mod.code + ": UC '" + uc.id + "' uses steps[] with objects — must use mainScenario[] with strings");
+    }
+    if (uc.actor && !uc.primaryActor) {
+      warnings.push(mod.code + ": UC '" + uc.id + "' uses 'actor' instead of canonical 'primaryActor'");
     }
   }
 

package/templates/skills/business-analyse-design/steps/step-01-screens.md

@@ -149,28 +149,65 @@ Map entity attribute types to UI component types:
 
 For each module, write via ba-writer:
 
+> **CANONICAL FORMAT (MANDATORY):** screens.json MUST use the `sections[]` wrapper format below.
+> Keys MUST be `sectionCode` and `sectionLabel` (not `id`/`displayName`/`code`/`label`).
+> Each section MUST have a `resources[]` array with typed resource objects (SmartTable, SmartForm, etc.).
+> The flat `screens[]` format (one object per screen with componentType at top level) is **DEPRECATED**.
+> All downstream consumers (business-analyse-html, business-analyse-handoff, business-analyse-develop) expect `sections[]`.
+
 ```json
 {
   "sections": [
     {
       "sectionCode": "list",
       "sectionLabel": "Liste des employes",
-      "resources": [ /* SmartTable, filters */ ]
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "label": "Grille des employes",
+          "columns": [ /* ... */ ],
+          "filters": [ /* ... */ ],
+          "actions": ["create", "export"],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
     },
     {
-      "sectionCode": "form",
+      "sectionCode": "detail",
       "sectionLabel": "Fiche employe",
-      "resources": [ /* SmartForm with tabs */ ]
+      "resources": [
+        {
+          "code": "employee-form",
+          "type": "SmartForm",
+          "label": "Fiche employe",
+          "tabs": [ /* ... */ ],
+          "actions": ["save", "cancel"],
+          "permission": "HumanResources.Employees.Update"
+        }
+      ]
     },
     {
       "sectionCode": "dashboard",
       "sectionLabel": "Tableau de bord",
-      "resources": [ /* SmartDashboard */ ]
+      "resources": [
+        {
+          "code": "employees-dashboard",
+          "type": "SmartDashboard",
+          "label": "Tableau de bord RH",
+          "kpis": [ /* ... */ ],
+          "charts": [ /* ... */ ],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
     }
   ]
 }
 ```
 
+> **Key naming:** Use `sectionCode` (not `id`, `code`). Use `sectionLabel` (not `displayName`, `label`).
+> Resource `type` must be one of: `SmartTable`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`, `SmartFilter`.
+
 Update `index.json` with screens.json hash and status.
 
 ## Validation

package/templates/skills/business-analyse-handoff/steps/step-01-transform.md

@@ -72,10 +72,19 @@ Transform module "{moduleCode}" for handoff.
 ## Instructions
 Read the following 5 files from {moduleDir}:
   1. entities.json → entities[]
-  2. usecases.json → useCases[]
-  3. rules.json → rules[]
+  2. usecases.json → useCases[] (canonical key: "useCases", fallback: "usecases")
+  3. rules.json → rules[] (canonical key: "rules", fallback: "businessRules")
   4. permissions.json → roles[], matrix[], permissionPaths[]
-  5. screens.json → screens[]
+  5. screens.json → sections[] (canonical key: "sections", fallback: "screens")
+
+### Normalization Safety Net (BACKWARD COMPAT)
+When reading flat files, prefer canonical keys but fall back to alternatives:
+  - useCases: `data.useCases || data.usecases || []`
+  - primaryActor: `uc.primaryActor || uc.actor`
+  - mainScenario: `uc.mainScenario || uc.steps` (if steps[] contains objects, extract `.action`)
+  - rules: `data.rules || data.businessRules || []`
+  - screens: `data.sections || data.screens` (if screens[] exists, treat each screen as a section with 1 resource)
+This safety net handles pre-4.52 BA outputs. It should become unnecessary once step-03-specify enforces canonical keys.
 
 Then build the handoff data following these rules: