@atlashub/smartstack-cli 4.51.0 → 4.52.0

package/package.json

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

package/templates/skills/apex/references/core-seed-data.md

@@ -1003,6 +1003,21 @@ public class RolePermissionSeedEntry
 
 ## 6. IClientSeedDataProvider Implementation
 
+> **IMPORTANT — HasData vs Seed*Async: TWO DIFFERENT MECHANISMS**
+>
+> | Mechanism | Where | When | Purpose |
+> |-----------|-------|------|---------|
+> | **EF Core `HasData()`** | `*Configuration.cs` (Infrastructure) | At migration time | Seeds static reference data into tables via `INSERT` in migration SQL. Data is part of the migration — no runtime code needed. |
+> | **`IClientSeedDataProvider.Seed*Async()`** | `*SeedDataProvider.cs` (Infrastructure) | At runtime startup | Seeds navigation, roles, permissions, role-permissions into the **Core** schema. Runs AFTER `MigrateAsync()` in `Program.cs`. |
+>
+> **Common mistake:** Generating `HasData()` calls for navigation/permissions instead of `Seed*Async()` methods.
+> Navigation and permission data goes into the **Core** schema (`core.nav_*`, `core.auth_*`) which is managed
+> by SmartStack, not by the client's migration. Only `IClientSeedDataProvider` can write to Core tables at runtime.
+>
+> **ANTI-STUB WARNING:** Each of the 4 Seed methods MUST contain real `context.{DbSet}.Add()` calls.
+> If ANY method is just `return Task.CompletedTask;`, the module will be **invisible** in the UI (empty menu).
+> This happens when this reference file is evicted from context by compression — see step-03b safeguard.
+
 **File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
 
 ### Critical Rules

package/templates/skills/apex/references/error-classification.md

@@ -100,6 +100,28 @@
 
 ---
 
+### Category G: PRD Quality Error (FIX = fix PRD or re-run handoff)
+
+> **These errors are NOT caused by code generation — they originate from invalid PRD data.**
+> The handoff generated file paths with illegal characters (spaces, apostrophes, accents in entity names).
+> Code generation faithfully reproduced the invalid paths → build failure.
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `error CS1001: Identifier expected` with file name containing spaces | `Type d'absence.cs` → CS1001 | Re-run `/business-analyse-handoff` with entity canonicalization |
+| `error CS1513/CS1514` with file name containing apostrophes | `Congé.cs` → accent in identifier | Fix entity name in BA or re-run handoff |
+| Path contains non-ASCII characters in `.cs` file names | `Département.cs` | Canonicalize: strip diacritics, PascalCase |
+
+**Detection heuristic:** If the error file path contains spaces, apostrophes, or accented characters, it is a PRD quality error, not a code error. Do NOT attempt to fix the generated code — fix the PRD source.
+
+**Fix procedure:**
+1. Identify the invalid entity name from the error file path
+2. Report to user: "PRD quality error — entity name '{name}' is not a valid C# identifier"
+3. Either: manually canonicalize in the PRD file, or re-run `/business-analyse-handoff` (which now includes canonicalization)
+4. Re-run `/apex -d` with the corrected PRD
+
+---
+
 ## Decision Tree
 
 When a build or runtime error occurs, follow this tree:
@@ -123,9 +145,11 @@ BUILD/RUNTIME ERROR
   |     YES -> Category E (edit config files)
   |
   +-- error CS#### (C# compiler error) ?
-  |     YES -> Is the missing type in ANY project file?
-  |           NO  -> Category A (missing package)
-  |           YES -> Category F (fix source code)
+  |     YES -> Does the error file path contain spaces, apostrophes, or accents?
+  |           YES -> Category G (PRD quality error — fix handoff, not code)
+  |           NO  -> Is the missing type in ANY project file?
+  |                 NO  -> Category A (missing package)
+  |                 YES -> Category F (fix source code)
   |
   +-- Test failure (Assert/Expected) ?
         YES -> Category F (fix source code, NOT tests)

package/templates/skills/apex/references/post-checks.md

@@ -90,7 +90,7 @@ bash references/checks/infrastructure-checks.sh
 | C20 | WARNING | Section route completeness (NavigationSection → frontend route + permissions) | seed-checks.sh |
 | C21 | WARNING | FORBIDDEN route patterns — /list and /detail/:id | seed-checks.sh |
 | C22 | WARNING | Permission path segment count (2-4 dots expected) | seed-checks.sh |
-| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods + DI registration | seed-checks.sh |
+| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods with real implementation (not stubs) + DI registration | seed-checks.sh |
 | C32 | CRITICAL | Translation seed data must have idempotency guard | seed-checks.sh |
 | C33 | CRITICAL | Resource seed data must use actual section IDs from DB | seed-checks.sh |
 | C34 | BLOCKING | NavRoute segments must use kebab-case for multi-word codes — MCP overlap | seed-checks.sh |
@@ -101,6 +101,8 @@ bash references/checks/infrastructure-checks.sh
 | C47 | WARNING | Person Extension entities must not duplicate User fields | seed-checks.sh |
 | C48 | CRITICAL | Person Extension service must Include(User) | seed-checks.sh |
 | C53 | BLOCKING | Enum serialization — JsonStringEnumConverter required | seed-checks.sh |
+| C57 | BLOCKING | SeedDataProvider Seed*Async methods must NOT be `return Task.CompletedTask` or empty body — stubs cause empty menu | seed-checks.sh |
+| C58 | BLOCKING | File paths in filesToCreate must be valid C# identifiers — no spaces, apostrophes, or accents | seed-checks.sh |
 
 ### Architecture — Clean Architecture Layer Isolation (A1-A8)
 

package/templates/skills/apex/steps/step-00-init.md

@@ -94,6 +94,46 @@ if (prd.specificationFiles) {
 
 Each layer step (step-03a through step-03d) will load its companion files at the start. This provides full BA specifications (entity attributes, BR formulas, UC steps, screen columns) without loading the entire spec corpus.
 
+**PRD Quality Gate (delegate mode — BLOCKING):**
+
+> Validate that PRD file paths are valid C# identifiers BEFORE starting execution.
+> Invalid entity names (French with spaces/apostrophes/accents) cause CS1001 build errors
+> that waste 3+ retry iterations before being correctly classified.
+
+```javascript
+// Extract all file paths from PRD
+const filesToCreate = prd.$version === '4.0.0' ? prd.expectedFiles : prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  const invalidPaths = [];
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      const filePath = file.path || file;
+      // Extract filename (without extension) from path
+      const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
+      // Check for illegal characters in C# identifiers
+      if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
+        invalidPaths.push({ category, path: filePath, fileName });
+      }
+    }
+  }
+
+  if (invalidPaths.length > 0) {
+    console.error('BLOCKING — PRD QUALITY ERROR (not a code error):');
+    console.error('The following file paths contain illegal C# identifier characters:');
+    for (const p of invalidPaths) {
+      console.error(`  ${p.category}: ${p.path} (invalid name: "${p.fileName}")`);
+    }
+    console.error('');
+    console.error('FIX: Re-run /business-analyse-handoff which now includes entity name canonicalization.');
+    console.error('     Or manually fix entity names in the PRD (strip accents, remove spaces/apostrophes, PascalCase).');
+    console.error('');
+    console.error('This is a PRD quality error (Category G), NOT a code generation error.');
+    console.error('Do NOT attempt to generate code from this PRD — it will fail with CS1001.');
+    STOP; // Do not proceed with invalid PRD
+  }
+}
+```
+
 **Jump to:** section 3 (MCP verify) → section 6 (determine needs) → section 9 (summary)
 
 ---
@@ -248,6 +288,23 @@ needs_notification = {module_complexity} in ["crud-workflow","complex"] OR menti
 
 Read latest task directory in `.claude/output/apex/`:
 - **If state.json exists:** resume step-03 at next uncompleted layer (skip completed)
+  - **Delegate context recovery:** If `state.delegate_mode === true`:
+    1. Restore `{delegate_prd_path}` from `state.delegate_prd_path`
+    2. Restore `{app_name}`, `{module_code}`, `{sections}`, `{entities}` from state
+    3. Re-read PRD at `{delegate_prd_path}` to rebuild `{specification_loading_plan}`:
+       ```javascript
+       const prd = readJSON(state.delegate_prd_path);
+       if (prd.specificationFiles) {
+         const sf = prd.specificationFiles;
+         specification_loading_plan = {
+           layer0_domain:   [sf.entities],
+           layer1_seed:     [sf.entities, sf.permissions],
+           layer2_backend:  [sf.rules, sf.usecases],
+           layer3_frontend: [sf.screens, sf.usecases]
+         };
+       }
+       ```
+    4. Set `{delegate_mode} = true` — companion spec loading will work in remaining layers
 - **Else if 00-context.md exists:** restore step-00 state, re-derive post-step-00 from git + files
 - **Else:** full re-derive from git history + files
 

package/templates/skills/apex/steps/step-03-execute.md

@@ -46,19 +46,35 @@ Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
 BEFORE starting Layer N:
   Verify these variables are still accessible:
     {app_name}, {module_code}, {sections}, {entities}, {code_patterns}
+    IF delegate_mode: also verify {delegate_prd_path}, {specification_loading_plan}
 
   IF any variable is missing or empty:
     1. Read .claude/output/apex/{task_id}/state.json (if exists)
-    2. IF state.json missing → re-derive from filesystem:
+    2. IF state.json has delegate context:
+       - {delegate_prd_path} = state.delegate_prd_path
+       - {delegate_mode} = state.delegate_mode
+       - Re-read PRD at {delegate_prd_path} to rebuild specification_loading_plan:
+         const prd = readJSON(delegate_prd_path);
+         if (prd.specificationFiles) {
+           specification_loading_plan = {
+             layer0_domain:   [prd.specificationFiles.entities],
+             layer1_seed:     [prd.specificationFiles.entities, prd.specificationFiles.permissions],
+             layer2_backend:  [prd.specificationFiles.rules, prd.specificationFiles.usecases],
+             layer3_frontend: [prd.specificationFiles.screens, prd.specificationFiles.usecases]
+           };
+         }
+       - {app_name} = state.app_name || prd.project?.application || prd.metadata?.applicationCode
+       - {module_code} = state.module_code || prd.project?.module || prd.metadata?.moduleCode
+    3. IF state.json missing OR no delegate context → re-derive from filesystem:
        - {app_name}: Glob("docs/business/*/") → first directory name
        - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
        - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
        - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse
        - {code_patterns}: Read state.json or re-derive from DependencyInjection.cs
-    3. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
-    4. IF Layer N-1 already completed: skip to Layer N directly
+    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+    5. IF Layer N-1 already completed: skip to Layer N directly
 
-  Cost: ~5 tool calls. Only triggered if context was compressed.
+  Cost: ~5-8 tool calls. Only triggered if context was compressed.
 ```
 
 ---
@@ -126,6 +142,7 @@ Layer 4: feat({module}): [devdata] test data for development  # if applicable
 ## State Auto-Save (after each layer)
 
 > **Automatic** — not dependent on `-s` flag. Enables reliable resume after context loss.
+> **CRITICAL (audit ba-003):** Delegate context MUST be persisted for resume to work in delegate mode.
 
 After each layer's build gate passes, write state to `.claude/output/apex/{task_id}/state.json`:
 
@@ -137,10 +154,21 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
   "files_created": ["Employee.cs", "EmployeeConfiguration.cs", "..."],
   "build_gates": { "layer0": "pass", "layer1": "pass", "layer2": "pass" },
   "commits": ["abc1234", "def5678", "ghi9012"],
-  "timestamp": "2026-03-06T14:30:00Z"
+  "timestamp": "2026-03-06T14:30:00Z",
+  "delegate_mode": true,
+  "delegate_prd_path": ".ralph/prd-employees.json",
+  "app_name": "HumanResources",
+  "module_code": "employee-management",
+  "sections": ["employees", "departments"],
+  "entities": ["Employee", "Department"]
 }
 ```
 
+> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`**
+> are persisted so that Context Recovery Protocol (above) can restore the full execution context
+> after context compression or resume (`-r`). The `specification_loading_plan` is rebuilt from the
+> PRD file at `delegate_prd_path` — no need to serialize it directly.
+
 ---
 
 ## Save Output (if save_mode)

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -42,6 +42,24 @@ TaskUpdate(taskId: progress_tracker_id,
 
 > This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
 
+> **CONTEXT COMPRESSION SAFEGUARD (delegate mode):**
+> In delegate mode (`-d`), `references/core-seed-data.md` may have been evicted from context by compression
+> before Layer 1 begins (it was loaded at step-03 entry but is ~1464 lines).
+>
+> **CHECK:** Can you see Section 6 "IClientSeedDataProvider Implementation" from `core-seed-data.md` in your context?
+> - **YES** → Proceed normally using the templates from that section.
+> - **NO** → **Re-read** `references/core-seed-data.md` lines 1004-1296 NOW (the IClientSeedDataProvider template).
+>   This section contains the complete C# template for the provider class with all 4 Seed methods.
+>
+> **WARNING — ANTI-STUB RULE:**
+> The SeedDataProvider MUST contain real implementation code. Each of the 4 methods
+> (`SeedNavigationAsync`, `SeedRolesAsync`, `SeedPermissionsAsync`, `SeedRolePermissionsAsync`)
+> MUST have actual entity creation logic with `context.{DbSet}.Add()` calls.
+>
+> **BLOCKING:** If ANY Seed method body is just `return Task.CompletedTask;` or `{ }` (empty),
+> the seed data layer is INVALID. The module will be invisible in the UI (menu vide / empty menu).
+> Re-read the template from `references/core-seed-data.md` Section 6 and generate proper implementation.
+
 ---
 
 ### Mode Detection: CREATE vs UPDATE

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -169,6 +169,9 @@ For each module:
     3. Add the new namespace import + registration for all 4 languages
     4. If config uses dynamic imports: add namespace to the `ns` array
     5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
+    6. **I18n File/Import Alignment Check:** Verify that every locale JSON file on disk for this module
+       has a corresponding import in the i18n config index.ts. Glob `src/**/i18n/locales/*/` for module files,
+       then verify each is imported. Missing imports cause silent translation failures (keys show as raw strings).
 - Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
   then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
 - Section routes: Ensure navigation seed data has ComponentKey matching PageRegistry keys.

package/templates/skills/apex/steps/step-04-examine.md

@@ -131,6 +131,41 @@ IF ANY cell = NO → BLOCKING — return to step-03b to fix
 
 Execute all checks from `references/post-checks.md`. If any fails, fix in step-03 and re-validate.
 
+### 6c. SeedDataProvider Content Verification (BLOCKING)
+
+> **LESSON LEARNED (audit ba-003):** SeedDataProvider existed and had 4 methods (passed C23),
+> but all methods were `return Task.CompletedTask` — stubs generated when `core-seed-data.md`
+> was evicted from context by compression. Result: empty menu, 0 applications visible.
+
+```javascript
+// Find the SeedDataProvider file
+const providerFiles = Glob("**/Seeding/*SeedDataProvider.cs");
+for (const providerFile of providerFiles) {
+  const content = readFile(providerFile);
+
+  // Check 1: No stub methods — each Seed*Async must have real implementation
+  const methods = ['SeedNavigationAsync', 'SeedRolesAsync', 'SeedPermissionsAsync', 'SeedRolePermissionsAsync'];
+  for (const method of methods) {
+    const methodRegex = new RegExp(`${method}[^{]*\\{([^}]*)\\}`, 's');
+    const match = content.match(methodRegex);
+    if (match) {
+      const body = match[1].trim();
+      if (body === 'return Task.CompletedTask;' || body === '' || body === 'return;') {
+        BLOCKING_ERROR(`${providerFile}: ${method} is a STUB (${body || 'empty body'}). ` +
+          `Re-read references/core-seed-data.md Section 6 and generate real implementation. ` +
+          `Stub seed methods cause EMPTY MENU — 0 applications visible in UI.`);
+      }
+    }
+  }
+
+  // Check 2: Must contain actual entity creation calls
+  if (!content.includes('.Add(') && !content.includes('.AddRange(')) {
+    BLOCKING_ERROR(`${providerFile}: No .Add() or .AddRange() calls found. ` +
+      `SeedDataProvider must actually insert seed data, not just return.`);
+  }
+}
+```
+
 ---
 
 ## 7. Acceptance Criteria POST-CHECK

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
 
@@ -96,6 +97,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.