@atlashub/smartstack-cli 4.51.0 → 4.53.0

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-develop/references/init-resume-recovery.md

@@ -65,6 +65,60 @@ if (resumeValid) {
 }
 ```
 
+### Ralph State Recovery (context compression defense)
+
+> **When context compression occurs mid-execution**, conversation variables are lost.
+> `ralph-state.json` tracks the current position and is written before each major transition.
+> This section reads it back to recover position.
+
+```javascript
+// ALWAYS attempt to read ralph-state.json on resume — regardless of -r flag
+// This file is written by: step-00 init, step-02 execute, compact-loop, module-transition
+const statePath = '.ralph/ralph-state.json';
+if (fileExists(statePath)) {
+  const state = readJSON(statePath);
+
+  console.log(`Ralph state recovered: step=${state.currentStep}, module=${state.currentModule}, ` +
+    `iteration=${state.iteration || '?'}, reason=${state.reason || 'normal'}`);
+
+  // Restore conversation variables from state
+  if (state.currentModule) {
+    {current_module} = state.currentModule;
+  }
+  if (state.iteration) {
+    {current_iteration} = state.iteration;
+  }
+  if (state.prdVersion) {
+    {prd_version} = state.prdVersion;
+  }
+
+  // Route to the correct step based on saved state
+  // This replaces the default "always go to step-01" behavior
+  const stepRouting = {
+    'step-01-task':   'steps/step-01-task.md',
+    'step-02-execute': 'steps/step-02-execute.md',
+    'step-03-commit':  'steps/step-03-commit.md',
+    'step-04-check':   'steps/step-04-check.md',
+    'compact-loop':    'steps/step-04-check.md',  // compact-loop re-enters via step-04
+    'step-05-report':  'steps/step-05-report.md'
+  };
+
+  const targetStep = stepRouting[state.currentStep] || 'steps/step-01-task.md';
+
+  // Special case: module transition — go to step-01 to detect module-changed.json
+  if (state.reason === 'module-transition') {
+    console.log(`Module transition recovery: ${state.fromModule} → ${state.currentModule}`);
+    console.log('Routing to step-01-task.md to detect module-changed.json');
+    // targetStep stays 'steps/step-01-task.md'
+  }
+
+  console.log(`Recovery routing: → ${targetStep}`);
+  // The calling code (step-00) should load targetStep instead of the default step-01
+}
+```
+
+**IMPORTANT:** This recovery is triggered BEFORE the default "Proceed to step-01" routing in step-00-init.md. If ralph-state.json provides a different target step, that step should be loaded instead.
+
 ---
 
 ## Auto-Recovery: BA Artifacts Without PRD

package/templates/skills/business-analyse-develop/steps/step-00-init.md

@@ -76,10 +76,11 @@ If tests are slow (>30s in logs), display warning but **continue execution**:
 
 ## 4. Resume or Initialize
 
-See `references/init-resume-recovery.md` for complete Resume Mode and Auto-Recovery logic.
+See `references/init-resume-recovery.md` for complete Resume Mode, Auto-Recovery, and Ralph State Recovery logic.
 
 **Quick:**
-- If `-r` flag: restore state from .ralph/prd.json
+- If `-r` flag: restore state from .ralph/prd.json + .ralph/ralph-state.json
+- Else if `.ralph/ralph-state.json` exists: recover position (step, module, iteration) — see init-resume-recovery.md "Ralph State Recovery"
 - Else if BA artifacts exist: auto-recover PRDs via `ss business-analyse-handoff`
 - Else: fresh start
 
@@ -222,14 +223,20 @@ MCP: Ready | Branch: {branch} | PRD: v{prd_version}
 
 ### 7b. Initialize State File (context compression defense)
 
+> **ralph-state.json is written here AND updated by step-02, compact-loop, and module-transition.**
+> On resume or after context compression, `init-resume-recovery.md` reads it back to route
+> to the correct step instead of always restarting from step-01.
+
 ```javascript
 writeJSON('.ralph/ralph-state.json', {
   currentStep: 'step-01-task',
   currentModule: {current_module},
   iteration: 1,
   prdVersion: {prd_version},
+  modulesQueuePath: fileExists('.ralph/modules-queue.json') ? '.ralph/modules-queue.json' : null,
   timestamp: new Date().toISOString()
 });
 ```
 
-**Proceed directly to step-01-task.md**
+**Step routing:** If ralph-state recovery (section 4) provided a different target step, load THAT step.
+Otherwise, proceed to step-01-task.md.

package/templates/skills/business-analyse-develop/steps/step-01-task.md

@@ -6,8 +6,20 @@ next_step: steps/step-02-execute.md
 
 # Step 1: Load Task
 
-> **STATE RECOVERY:** If you are unsure which step you are executing (e.g., after context compression),
-> read `.ralph/ralph-state.json` to recover your position.
+> **STATE RECOVERY (executable):** If context was compressed and you are unsure of your position:
+```javascript
+if (fileExists('.ralph/ralph-state.json')) {
+  const state = readJSON('.ralph/ralph-state.json');
+  if (state.currentStep && state.currentStep !== 'step-01-task') {
+    console.warn(`RECOVERY: ralph-state.json says currentStep="${state.currentStep}" but we are in step-01.`);
+    console.warn(`This may indicate context compression routed to the wrong step.`);
+    console.warn(`Current module: ${state.currentModule}, iteration: ${state.iteration}`);
+  }
+  // Restore module context
+  if (state.currentModule) { {current_module} = state.currentModule; }
+  if (state.iteration) { {current_iteration} = state.iteration; }
+}
+```
 
 > **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
 

package/templates/skills/business-analyse-develop/steps/step-04-check.md

@@ -6,8 +6,18 @@ next_step: steps/step-05-report.md OR steps/step-01-task.md
 
 # Step 4: Check Completion
 
-> **STATE RECOVERY:** If you are unsure which step you are executing (e.g., after context compression),
-> read `.ralph/ralph-state.json` to recover your position.
+> **STATE RECOVERY (executable):** If context was compressed:
+```javascript
+if (fileExists('.ralph/ralph-state.json')) {
+  const state = readJSON('.ralph/ralph-state.json');
+  if (state.currentStep && state.currentStep !== 'step-04-check' && state.currentStep !== 'compact-loop') {
+    console.warn(`RECOVERY: ralph-state.json says currentStep="${state.currentStep}" but we are in step-04.`);
+  }
+  // Restore module context if lost
+  if (state.currentModule) { {current_module} = state.currentModule; }
+  if (state.iteration) { {current_iteration} = state.iteration; }
+}
+```
 
 ## YOUR TASK:
 

package/templates/skills/business-analyse-handoff/references/entity-canonicalization.md

@@ -0,0 +1,158 @@
+# Entity Name Canonicalization
+
+> **Used by:** step-01-transform (section 2: file mapping) and step-02-export (POST-CHECK)
+> **Purpose:** Convert BA entity names (potentially French, with spaces/apostrophes/accents) into valid C# identifiers for file paths.
+
+---
+
+## Why This Exists
+
+Business analysts write entity names in the user's language (e.g., French: "Type d'absence", "Employé", "Congé maladie"). These names are used as-is in `entities.json`. However, C# file paths and class names **MUST** be valid identifiers:
+- No spaces
+- No apostrophes
+- No accents (diacritics)
+- PascalCase convention
+
+Without canonicalization, the handoff generates paths like `src/Domain/Entities/Type d'absence.cs` → build failure (CS1001).
+
+---
+
+## Canonicalization Rules
+
+### Step 1: Map to English PascalCase (PREFERRED)
+
+If the BA provides an explicit `codeIdentifier` or `englishName` field on the entity, use it directly.
+
+### Step 2: Strip Diacritics
+
+Remove accents from characters:
+
+| Input | Output |
+|-------|--------|
+| é, è, ê, ë | e |
+| à, â, ä | a |
+| ù, û, ü | u |
+| ô, ö | o |
+| î, ï | i |
+| ç | c |
+
+Example: `Employé` → `Employe`, `Congé` → `Conge`
+
+### Step 3: Remove Apostrophes and Split on Spaces
+
+Split the name on spaces, apostrophes, hyphens, and underscores:
+
+| Input | Tokens |
+|-------|--------|
+| `Type d'absence` | `["Type", "d", "absence"]` |
+| `Congé maladie` | `["Conge", "maladie"]` |
+| `Mise à jour` | `["Mise", "a", "jour"]` |
+
+### Step 4: Remove Articles and Prepositions (1-2 letter tokens)
+
+Remove French articles and prepositions that don't contribute to the identifier:
+
+**Remove:** `d`, `de`, `du`, `l`, `la`, `le`, `les`, `un`, `une`, `des`, `a`, `au`, `aux`, `en`
+
+| Input Tokens | Filtered |
+|-------------|----------|
+| `["Type", "d", "absence"]` | `["Type", "absence"]` |
+| `["Mise", "a", "jour"]` | `["Mise", "jour"]` |
+
+### Step 5: PascalCase Assembly
+
+Capitalize first letter of each remaining token, join without separator:
+
+| Filtered Tokens | Result |
+|----------------|--------|
+| `["Type", "absence"]` | `TypeAbsence` |
+| `["Conge", "maladie"]` | `CongeMaladie` |
+| `["Mise", "jour"]` | `MiseJour` |
+| `["Employe"]` | `Employe` |
+
+---
+
+## Canonicalization Function (Pseudocode)
+
+```javascript
+function canonicalizeEntityName(baName) {
+  // Step 1: Use explicit code identifier if available
+  // (handled by caller — check entity.codeIdentifier || entity.englishName first)
+
+  // Step 2: Strip diacritics
+  let name = baName.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+  // Step 3: Split on non-alphanumeric
+  let tokens = name.split(/[\s'\-_]+/).filter(t => t.length > 0);
+
+  // Step 4: Remove French articles/prepositions
+  const stopWords = new Set(['d', 'de', 'du', 'l', 'la', 'le', 'les', 'un', 'une', 'des', 'a', 'au', 'aux', 'en']);
+  tokens = tokens.filter(t => !stopWords.has(t.toLowerCase()));
+
+  // Step 5: PascalCase
+  return tokens.map(t => t.charAt(0).toUpperCase() + t.slice(1).toLowerCase()).join('');
+}
+```
+
+---
+
+## Validation: Is Valid C# Identifier?
+
+After canonicalization, verify the result is a valid C# identifier:
+
+```javascript
+function isValidCSharpIdentifier(name) {
+  // Must start with letter or underscore
+  // Must contain only letters, digits, underscores
+  // Must not be a C# keyword
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
+    && !CSHARP_KEYWORDS.has(name);
+}
+
+const CSHARP_KEYWORDS = new Set([
+  'abstract', 'as', 'base', 'bool', 'break', 'byte', 'case', 'catch',
+  'char', 'checked', 'class', 'const', 'continue', 'decimal', 'default',
+  'delegate', 'do', 'double', 'else', 'enum', 'event', 'explicit',
+  'extern', 'false', 'finally', 'fixed', 'float', 'for', 'foreach',
+  'goto', 'if', 'implicit', 'in', 'int', 'interface', 'internal',
+  'is', 'lock', 'long', 'namespace', 'new', 'null', 'object',
+  'operator', 'out', 'override', 'params', 'private', 'protected',
+  'public', 'readonly', 'ref', 'return', 'sbyte', 'sealed', 'short',
+  'sizeof', 'stackalloc', 'static', 'string', 'struct', 'switch',
+  'this', 'throw', 'true', 'try', 'typeof', 'uint', 'ulong',
+  'unchecked', 'unsafe', 'ushort', 'using', 'virtual', 'void',
+  'volatile', 'while'
+]);
+```
+
+---
+
+## Examples
+
+| BA Entity Name (French) | Canonicalized | File Path |
+|-------------------------|---------------|-----------|
+| `Type d'absence` | `TypeAbsence` | `src/Domain/Entities/App/Module/TypeAbsence.cs` |
+| `Employé` | `Employe` | `src/Domain/Entities/App/Module/Employe.cs` |
+| `Congé maladie` | `CongeMaladie` | `src/Domain/Entities/App/Module/CongeMaladie.cs` |
+| `Mise à jour` | `MiseJour` | `src/Domain/Entities/App/Module/MiseJour.cs` |
+| `Département` | `Departement` | `src/Domain/Entities/App/Module/Departement.cs` |
+| `Employee` | `Employee` | `src/Domain/Entities/App/Module/Employee.cs` (no change) |
+| `AbsenceType` | `AbsenceType` | `src/Domain/Entities/App/Module/AbsenceType.cs` (no change) |
+
+---
+
+## Integration Points
+
+1. **step-01-transform.md**: Apply `canonicalizeEntityName()` to ALL entity names BEFORE generating `filesToCreate` paths
+2. **step-02-export.md**: POST-CHECK validates all paths in `filesToCreate` are valid C# identifiers
+3. **entity-domain-mapping.md**: `{EntityName}` in path templates refers to the CANONICALIZED name
+4. **handoff-file-templates.md**: All `{EntityName}` placeholders use canonicalized names
+
+## Anti-Patterns
+
+| Anti-Pattern | Risk | Correct Approach |
+|-------------|------|-----------------|
+| Translate to English semantically | `MiseJour` → `Update`? No — loses domain meaning | Only strip illegal chars, keep semantics |
+| Remove all short words | `TypeAbsence` missing `Type`? | Only remove articles/prepositions, not nouns |
+| Lowercase everything | `typeabsence` is not PascalCase | PascalCase each token |
+| Skip validation | `Task` is a valid name but also a C# type | Warn on namespace conflicts, don't block |

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

@@ -19,6 +19,7 @@ next_step: steps/step-02-export.md
 - **NEVER** invent entities/BRs not in module JSON files
 - **NEVER** load all module data in the main conversation (causes context overflow on 5+ modules)
 - **ALWAYS** generate API endpoints from use cases + entities (BA does not produce apiEndpoints)
+- **ALWAYS** canonicalize entity names before generating file paths — see `references/entity-canonicalization.md`
 
 ## YOUR TASK
 
@@ -71,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:
 
@@ -96,6 +106,19 @@ Then build the handoff data following these rules:
 ### Section UC/BR Enrichment
 Using sectionCode from usecases.json and rules.json, link each UC and BR to its section.
 
+### Entity Name Canonicalization (MANDATORY)
+Before generating any file paths, canonicalize ALL entity names from `entities.json`:
+1. Read `references/entity-canonicalization.md` for complete rules
+2. For each entity in `entities.json > entities[]`:
+   - If entity has `codeIdentifier` or `englishName` → use it directly
+   - Otherwise → apply canonicalization: strip diacritics, remove apostrophes/spaces, remove French articles (d, de, du, l, la, le, les, un, une, des, a, au, aux, en), PascalCase
+3. Use the CANONICALIZED name in ALL file path templates (`{EntityName}`, `{ServiceName}`, `{DtoName}`, etc.)
+4. Store the mapping `{ originalName: "Type d'absence", canonicalName: "TypeAbsence" }` in handoff metadata for traceability
+
+**Example:** Entity `"Type d'absence"` → canonicalized to `"TypeAbsence"` → path `src/Domain/Entities/App/Module/TypeAbsence.cs`
+
+**BLOCKING:** If ANY entity name after canonicalization is not a valid C# identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`), STOP and report the error.
+
 ### File Mapping (8 Categories)
 Read `references/handoff-file-templates.md` for complete JSON templates.
 All backend paths MUST include {ApplicationName}/ hierarchy.

package/templates/skills/business-analyse-handoff/steps/step-02-export.md

@@ -111,6 +111,20 @@ for (const key of specKeys) {
     BLOCKING_ERROR(`Companion file empty or too small: ${companionPath} (${companionSize} bytes)`);
   }
 }
+
+// Check 6: File paths must be valid C# identifiers (no spaces, apostrophes, accents)
+// Reference: references/entity-canonicalization.md
+for (const [cat, files] of Object.entries(ftc)) {
+  for (const file of (files || [])) {
+    const filePath = file.path || file;
+    // Extract filename without extension
+    const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
+    // Check for illegal characters in C# file names
+    if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
+      BLOCKING_ERROR(`${cat}: File path contains illegal characters for C# identifier: "${filePath}" — entity name must be canonicalized (see references/entity-canonicalization.md)`);
+    }
+  }
+}
 ```
 
 Display verification table showing all 8 categories match between module JSON files and prd.json.

package/templates/skills/business-analyse-html/SKILL.md

@@ -42,9 +42,13 @@ Generate the interactive HTML document of the business analysis from the JSON an
 
 - **NEVER** deploy an empty template — FEATURE_DATA must be injected
 - **moduleSpecs** MUST have ONE entry per module (empty = BROKEN)
+- **moduleSpecs[].screens[]** MUST have populated resources when source screens.json has data (empty resources = NO HTML mockups)
 - **Scope keys** MUST be converted: `inScope` → `inscope`, `outOfScope` → `outofscope`
 - **Wireframe fields** MUST be renamed: `mockupFormat` → `format`, `mockup` → `content`
+- **Input normalization** MUST handle both JSON schemas: Format A (`screens[]`, `useCases`, `mainScenario`) and Format B (`sections[]`, `usecases`, `steps[]` as objects)
+- **NEVER** call `.join()` on arrays without checking element types — object elements produce `[object Object]`
 - **Final file** MUST be > 100KB
+- **Final file** MUST NOT contain the string `[object Object]`
 
 ## References