@atlashub/smartstack-cli 4.74.0 → 4.75.0

package/templates/skills/apex/references/smartstack-frontend.md

@@ -121,24 +121,67 @@ t('employees:messages.created', '{{entity}} created', { entity: 'Employee' }) //
 t('common:actions.save', 'Save')                                              // Cross-namespace
 ```
 
-### Namespace Registration (CRITICAL — POST-CHECK C39)
+### Namespace Registration (CRITICAL — POST-CHECK C39 + GATE PG-4)
 
-After creating i18n JSON files, register each namespace in `src/i18n/config.ts`:
+After creating i18n JSON files, register each namespace in `src/i18n/config.ts` or `index.ts`:
 
 ```typescript
-import employees from './locales/fr/employees.json';
-// In resources: fr: { employees, common, navigation, ... }
-// OR in ns array: ns: ['common', 'navigation', 'employees'],
+// CORRECT — Full i18n config with module namespaces registered
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+
+// Import ALL module translation files for each language
+import frEmployes from './locales/fr/employes.json';
+import enEmployes from './locales/en/employes.json';
+import itEmployes from './locales/it/employes.json';
+import deEmployes from './locales/de/employes.json';
+import frAbsences from './locales/fr/absences.json';
+import enAbsences from './locales/en/absences.json';
+import itAbsences from './locales/it/absences.json';
+import deAbsences from './locales/de/absences.json';
+// ... repeat for each module
+
+i18n
+  .use(LanguageDetector)
+  .use(initReactI18next)
+  .init({
+    fallbackLng: 'fr',
+    ns: ['employes', 'absences'],  // List ALL namespaces
+    defaultNS: 'employes',
+    interpolation: { escapeValue: false },
+    resources: {
+      fr: { employes: frEmployes, absences: frAbsences },
+      en: { employes: enEmployes, absences: enAbsences },
+      it: { employes: itEmployes, absences: itAbsences },
+      de: { employes: deEmployes, absences: deAbsences },
+    },
+  });
+
+export default i18n;
 ```
 
-Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
+```typescript
+// WRONG — Missing namespace imports (keys show as raw strings like "list.title")
+i18n.init({
+  resources: {
+    en: { translation: { welcome: 'Welcome' } },
+    fr: { translation: { welcome: 'Bienvenue' } },
+  },
+});
+// ❌ Module JSON files exist on disk but are NEVER loaded → useTranslation('employes') returns empty
+```
+
+Root cause (test-apex-007, test-ba-010): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings. All t() calls displayed raw keys like `list.title`, `form.department` instead of translated text.
 
 **Rules:**
-- Provide fallback value as 2nd argument to `t()`
+- Provide fallback value as 2nd argument to `t()`: `t('employes:list.title', 'Liste des employés')`
 - Use namespace prefix: `t('namespace:key')` — never `t('key')` without namespace
 - Generate 4 language files (fr, en, it, de) with identical key structures
 - Register new namespaces in i18n config file after creating JSON files
 - Do not hardcode user-facing strings in JSX
+- **After writing i18n JSON files:** IMMEDIATELY update i18n config with imports + resources registration
+- **Verify:** `grep -q "{namespace}" src/**/i18n/index.ts` MUST match for EVERY module namespace
 
 ---
 
@@ -285,9 +328,12 @@ Do NOT use: `bg-white`, `border-gray-200`, `text-gray-900`, hardcoded hex/rgb.
 - Do not use raw `<table>` — use `DataTable`
 - Do not create custom spinners — use `Loader2` from lucide-react
 - Do not import axios directly — use `@/services/api/apiClient`
+- **Do not use raw `fetch()` — use `apiClient` from `@/services/api`** (handles auth, token refresh, tenant isolation)
 - Use `PageLoader` as Suspense fallback
 - Use `EntityLookup` for FK Guid fields (not `<select>` or `<input>` for GUIDs)
 
+> **API access rule:** ALL API calls in hooks and pages MUST use `apiClient` (or the typed API service generated by MCP `scaffold_api_client`). Using raw `fetch()` bypasses authentication, token refresh, and tenant isolation — the page will fail silently when the user is logged in. This applies to custom hooks in `src/hooks/` as well as inline API calls in pages.
+
 ---
 
 ## 6. Foreign Key Fields & Entity Lookup

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

@@ -224,6 +224,79 @@ All naming variants are derived from {app_name}, {module_code}, {sections}. Do N
 
 Call `mcp__smartstack__validate_conventions` after computing derivations. Fix any errors BEFORE step-01.
 
+### 4g. Entity-Section Mapping (DETERMINISTIC)
+
+> Each entity MUST be mapped to a hierarchy level. This determines the entity's NavRoute segment count
+> (2 vs 3 segments) and whether section-level permissions are needed.
+> **This mapping is consumed by:** step-03b (permissions), step-03c (controllers), step-04 (validation).
+
+**Rules:**
+
+1. The entity whose name derives from `{module_code}` is the **module-level entity**.
+   It gets `NavRoute = {app}.{module}` (2 segments). Its permissions are module-level.
+
+2. Every other entity that matches a section from `{sections}` is a **section-level entity**.
+   It gets `NavRoute = {app}.{module}.{section_code}` (3 segments). Its permissions are section-level.
+
+3. Entities that match NO section stay **module-level** (share the module's NavRoute).
+   This is the case for true sub-resources without their own navigation entry (e.g., InvoiceLine).
+
+**Matching algorithm:**
+
+```
+FOR EACH entity in {entities}:
+  entity_kebab = kebab(pluralize(entity.name))  // "Contact" → "contacts", "Department" → "departments"
+
+  IF entity_kebab == {module_code} OR singularize(entity_kebab) == singularize({module_code}):
+    entity.level = "module"
+    entity.navRoute = "{app_name_kebab}.{module_code}"
+    entity.section_code = null
+
+  ELSE:
+    matched = {sections}.find(s =>
+      s.code == entity_kebab                           // exact: "contacts" == "contacts"
+      OR s.code == singularize(entity_kebab)           // singular: "types" for "AbsenceType"
+      OR s.code.endsWith(entity_kebab)                 // suffix: "absence-types" ends with "types"
+      OR entity_kebab.endsWith(s.code)                 // reverse: "project-members" ends with "members"
+    )
+
+    IF matched:
+      entity.level = "section"
+      entity.navRoute = "{app_name_kebab}.{module_code}.{matched.code}"
+      entity.section_code = matched.code
+    ELSE:
+      entity.level = "module"
+      entity.navRoute = "{app_name_kebab}.{module_code}"
+      entity.section_code = null
+```
+
+**Delegate mode override:** When `permissionPaths` companion includes section-level paths
+(3+ dot segments like `app.module.section.action`), use those paths as authoritative source
+to derive entity-section mapping instead of name heuristics.
+
+**Storage:**
+
+```
+{entity_section_map}: [
+  { entity: "Employee",   level: "module",  navRoute: "rh.employes",              section_code: null },
+  { entity: "Department", level: "section", navRoute: "rh.employes.departments",  section_code: "departments" }
+]
+```
+
+Propagated to: step-03b (permissions), step-03c (controllers), step-03-execute (state), step-04 (validation).
+
+**Post-mapping validation:**
+
+```
+# No duplicate NavRoutes among section-level entities
+section_navroutes = {entity_section_map}.filter(e => e.level == "section").map(e => e.navRoute)
+IF duplicates(section_navroutes) → BLOCKING: two entities mapped to same section
+
+# All section_codes exist in {sections}
+FOR EACH entry in {entity_section_map} WHERE section_code != null:
+  IF {sections}.find(s => s.code == entry.section_code) == null → BLOCKING: orphan section_code
+```
+
 ---
 
 ## 5. Collect Technical Parameters
@@ -323,6 +396,7 @@ APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
 Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
+Entity Map: {entity_section_map.map(e => `${e.entity}→${e.navRoute}`).join(', ')}
 Code: {code_patterns summary} | PRD: {prd_path||none} | Feature: {feature_path||none}
 Flags: {active_flags} | MCP: {available|degraded} | Needs: {migration/seed/workflow/notification}
 Specs: {specification_loading_plan ? 'companion files available (layer-specific loading)' : 'none'}

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

@@ -45,7 +45,7 @@ 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}
+    {app_name}, {module_code}, {sections}, {entities}, {code_patterns}, {entity_section_map}
     IF delegate_mode: also verify {delegate_prd_path}, {specification_loading_plan}
 
   IF any variable is missing or empty:
@@ -71,7 +71,12 @@ BEFORE starting Layer N:
        - {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
-    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+       - {entity_section_map}: IF state.json has it → use directly. ELSE re-derive:
+         For each entity, check controllers for [NavRoute] value:
+           Grep("\[NavRoute\(\"", "src/**/Controllers/**/{Entity}*Controller.cs")
+           → extract navRoute segments → determine level (2 seg = module, 3 seg = section)
+         Fallback: re-apply step-00 §4g matching algorithm with {entities} and {sections}
+    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f, §4g)
     5. IF Layer N-1 already completed: skip to Layer N directly
 
   Cost: ~5-8 tool calls. Only triggered if context was compressed.
@@ -160,14 +165,21 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
   "app_name": "HumanResources",
   "module_code": "employee-management",
   "sections": ["employees", "departments"],
-  "entities": ["Employee", "Department"]
+  "entities": ["Employee", "Department"],
+  "entity_section_map": [
+    { "entity": "Employee", "level": "module", "navRoute": "human-resources.employee-management", "section_code": null },
+    { "entity": "Department", "level": "section", "navRoute": "human-resources.employee-management.departments", "section_code": "departments" }
+  ]
 }
 ```
 
-> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`**
+> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`, `entity_section_map`**
 > 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.
+> The `entity_section_map` is critical for Layers 2-3: it determines per-entity NavRoute and
+> section-level permission generation. If lost, it can be re-derived from controller [NavRoute] attributes
+> or by re-applying step-00 §4g matching algorithm.
 
 ---
 

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

@@ -113,19 +113,45 @@ Generate all files from scratch using `references/core-seed-data.md` templates:
    → If resources defined: GetResourceEntries() + resource translations
    → Query actual parent from DB for FK (NOT deterministic GUID)
 
-4. Permissions.cs
+4. Permissions.cs — MODULE-LEVEL
    → MCP generate_permissions (PRIMARY tool)
    → Static constants: public static class {Module} { public const string Read = "..."; }
    → Permission paths MUST use kebab-case matching NavRoute codes
 
-5. PermissionsSeedData.cs
+4b. Permissions.cs — SECTION-LEVEL (for each entity in {entity_section_map} where level == "section")
+   → Add nested class per section inside the module class:
+     public static class {SectionPascal} {
+       public const string View = "{navRoute}.{section_code}.read";
+       public const string Create = "{navRoute}.{section_code}.create";
+       ...
+     }
+   → Apply permissionMode inference (core-seed-data.md Step C2):
+     - section code == "detail" → inherit (SKIP — no section permissions)
+     - section code == "dashboard" → read-only (read permission only)
+     - section code == "list" or "kanban" or "calendar" or "weekly" → inherit (SKIP — view of module entity)
+     - otherwise → crud (wildcard + read + create + update + delete)
+   → Reference: core-seed-data.md lines 736-799 for full template
+
+5. PermissionsSeedData.cs — MODULE-LEVEL
    → MCP generate_permissions first, fallback template
    → Paths match Permissions.cs, wildcard + CRUD
 
-6. RolesSeedData.cs
+5b. PermissionsSeedData.cs — SECTION-LEVEL (for each entity where level == "section" AND permissionMode != "inherit")
+   → Add CreateSectionPermissions(Guid {sectionCode}SectionId) method
+   → Section-level entries: wildcard + CRUD matching Permissions.cs nested class
+   → Reference: core-seed-data.md Step C2 lines 758-779 for template
+
+6. RolesSeedData.cs — MODULE-LEVEL
    → Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R
    → Code-based role mapping (not deterministic GUIDs for roles)
    → Look up roles by Code at runtime
+
+6b. RolesSeedData.cs — SECTION-LEVEL (for each entity where level == "section" AND permissionMode != "inherit")
+   → Add section-level mappings in GetRolePermissionMappings():
+     Admin: section wildcard ({navRoute}.{section_code}.*)
+     Manager: read + create + update for section
+     Contributor: read + create for section
+     Viewer: read for section
 ```
 
 #### If SEED_MODE = "UPDATE"
@@ -241,9 +267,16 @@ ELSE IF Program.cs ONLY calls `MigrateAsync()` without seed data execution:
 For each section in {sections} from step-00:
   ✓ NavigationModuleSeedData has section entry + translations (4 langs)
   ✓ NavigationModuleSeedData has route: /{app}/{module}/{section}
-  ✓ Permissions.cs has constants for this section (Read/Create/Update/Delete/Wildcard)
-  ✓ PermissionsSeedData has HasData() for each permission
-  ✓ RolesSeedData maps all 4 roles to section permissions
+
+For each entity in {entity_section_map} where level == "section" AND permissionMode != "inherit":
+  ✓ Permissions.cs has SECTION-LEVEL nested class {SectionPascal} with constants
+  ✓ PermissionsSeedData has CreateSectionPermissions(Guid {section}SectionId) method
+  ✓ RolesSeedData.GetRolePermissionMappings() includes section-level role mappings
+
+Module-level (always):
+  ✓ Permissions.cs has MODULE-LEVEL constants (Read/Create/Update/Delete/Wildcard)
+  ✓ PermissionsSeedData has module-level HasData() for each permission
+  ✓ RolesSeedData maps all 4 roles to module permissions
   ✓ {App}SeedDataProvider references all seed data classes
   ✓ Program.cs executes seed data providers after MigrateAsync()
   ✓ DI registers: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()

package/templates/skills/apex/steps/step-03c-layer2-backend.md

@@ -122,21 +122,48 @@ For each entity where {code_patterns} defines strategy != "manual":
 > **AGENT BOUNDARY:** Snipper agents do NOT have access to MCP tools or Bash.
 > MCP scaffolding and bash validation MUST be executed by the principal agent.
 
+#### Pre-Phase A — NavRoute Uniqueness Validation
+
+> **BLOCKING gate.** Run BEFORE any scaffold_extension call.
+
+```
+# Verify {entity_section_map} produces unique NavRoutes for section-level entities
+allNavRoutes = {entity_section_map}.map(e => e.navRoute)
+duplicates = allNavRoutes.filter((nr, i, arr) => arr.indexOf(nr) !== i)
+
+# Module-level entities MAY share NavRoute (sub-resources without own section)
+# Section-level entities MUST have unique NavRoutes
+sectionNavRoutes = {entity_section_map}.filter(e => e.level == "section").map(e => e.navRoute)
+sectionDuplicates = sectionNavRoutes.filter((nr, i, arr) => arr.indexOf(nr) !== i)
+
+IF sectionDuplicates.length > 0:
+  BLOCKING: "Two section-level entities share the same NavRoute: {sectionDuplicates}"
+  → Fix entity_section_map in step-00 §4g before proceeding
+```
+
 #### Phase A — Sequential: MCP scaffolding (principal agent)
 
-For each entity, the principal agent calls MCP directly:
+For each entity, the principal agent calls MCP directly with **per-entity NavRoute from `{entity_section_map}`**:
 
 ```
 IF NOT economy_mode AND entities.length > 1:
 
   FOR EACH entity in entities:
-    1. mcp__smartstack__scaffold_extension(type: "dto", name: "{Entity}", options: { navRoute: "{navRoute}" })
-    2. mcp__smartstack__scaffold_extension(type: "controller", name: "{Entity}", options: { navRoute: "{navRoute}" })
+    # Resolve per-entity NavRoute from entity_section_map (step-00 §4g)
+    entityMap = {entity_section_map}.find(e => e.entity == entity)
+    entityNavRoute = entityMap.navRoute   // e.g., "crm.clients.contacts" for Contact
+    entityLevel = entityMap.level         // "module" or "section"
+
+    1. mcp__smartstack__scaffold_extension(type: "dto", name: "{Entity}", options: { navRoute: "{entityNavRoute}" })
+    2. mcp__smartstack__scaffold_extension(type: "controller", name: "{Entity}", options: { navRoute: "{entityNavRoute}" })
 
     # Immediate NavRoute verification (principal has Bash access)
-    3. Verify: [NavRoute] present, [Route] absent, segment count >= 2
+    3. Verify:
+       - [NavRoute] present, [Route] absent
+       - NavRoute value == entityNavRoute (exact match)
+       - Segment count matches level: "module" → 2 segments (1 dot), "section" → 3 segments (2 dots)
        If [Route] found alongside [NavRoute] → remove [Route] immediately
-       If [NavRoute] missing → add it with correct value
+       If [NavRoute] missing or wrong value → fix with entityNavRoute
 ```
 
 #### Phase B — Parallel: post-scaffold adjustments (Snipper agents)
@@ -160,6 +187,7 @@ After ALL Phase A scaffolding completes, launch Snipper agents in parallel:
 
         DO NOT regenerate controller or DTO files — already created by MCP in Phase A.
         DO NOT add [Route] attribute — NavRoute is already set correctly.
+        NavRoute for this entity: {entityNavRoute} (from entity_section_map — DO NOT change it)
         Files already created: {list of paths from Phase A}')
   # All agents launched in parallel
 ```
@@ -293,11 +321,28 @@ for ENTITY in $ENTITIES; do
   ALL_NAVROUTES="$ALL_NAVROUTES
 $NR"
 done
+
+# Check MediatR pattern — MCP scaffold_extension generates ISender, manual code uses I*Service
+FAIL_MEDIATOR=false
+for ENTITY in $ENTITIES; do
+  CTRL=$(find src/ -path "*/Controllers/*" -name "${ENTITY}*Controller.cs" 2>/dev/null | head -1)
+  [ -z "$CTRL" ] && continue
+  if grep -qE 'private readonly I[A-Za-z0-9_]+Service ' "$CTRL" && ! grep -q 'ISender' "$CTRL"; then
+    echo "BLOCKING: $CTRL injects service directly instead of ISender _mediator"
+    echo "  MCP scaffold_extension was NOT called — regenerate via MCP"
+    FAIL_MEDIATOR=true
+  fi
+done
+if [ "$FAIL_MEDIATOR" = true ]; then
+  echo "BLOCKING: One or more controllers bypass MCP scaffold_extension (HARD RULE violation)"
+  exit 1
+fi
 ```
 
 > IF any BLOCKING found: fix the controller(s) BEFORE proceeding to Layer 3.
 > The fix is: remove [Route], add [NavRoute] with the correct dot-separated value,
 > add `using SmartStack.Api.Routing;`.
+> If ISender missing: delete the controller and call `mcp__smartstack__scaffold_extension(type: 'controller')`.
 
 ### Post-Layer 2 Build Gate
 

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

@@ -115,7 +115,11 @@ TaskUpdate(taskId: progress_tracker_id,
 ### Frontend Tasks (sequential or parallel within layer)
 
 For each module:
-- API client: MCP scaffold_api_client
+- API client: MCP scaffold_api_client — **MANDATORY, do not skip or generate manually.**
+  → The generated API client uses `apiClient` from `@/services/api` (auth, token refresh, tenant isolation).
+  → Hooks MUST import from the generated API service, NEVER use raw `fetch()` or direct axios.
+  → If `scaffold_api_client` is unavailable: generate the service manually using `apiClient` import,
+    but NEVER using `fetch()`. Pattern: `import apiClient from '@/services/api'; const res = await apiClient.get('/api/...');`
 - Routes — TWO mandatory steps:
   1. Generate registry: MCP scaffold_routes (source: 'controllers', outputFormat: 'componentRegistry', dryRun: false)
      → Creates/updates componentRegistry.generated.ts + navRoutes.generated.ts
@@ -163,7 +167,12 @@ For each module:
   → Follow JSON template from smartstack-frontend.md
   → Keys: actions, labels, errors, validation, columns, form, messages, empty
   → All t() calls must use namespace prefix + fallback: t('ns:key', 'Default text')
-  → **Register namespace in i18n config** (critical — POST-CHECK C39 catches this, but fix it now):
+  → **UTF-8 accents are MANDATORY** — NEVER use ASCII-only text for accented languages:
+    - FR: "Département" (not "Departement"), "employés" (not "employes"), "trouvée" (not "trouvee")
+    - DE: "Übersicht" (not "Ubersicht"), "Beschäftigung" (not "Beschaftigung")
+    - IT: "attività" (not "attivita"), "dipendentì" (not "dipendenti")
+    - EN: no accents needed (but proper apostrophes: "employee's" not "employees")
+  → **Register namespace in i18n config** (critical — POST-CHECK C39 + GATE PG-4 catch this, but fix it now):
     1. Find i18n config: `Glob("src/**/i18n/config.ts")` or `index.ts` or `i18n.ts`
     2. Read the config → find the resources/ns registration pattern
     3. Add the new namespace import + registration for all 4 languages
@@ -172,11 +181,20 @@ For each module:
     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).
+    7. **If registration is missing after step 6:** This is a BLOCKING error. The page will show raw keys
+       (`list.title`, `form.department`) instead of translated text. Fix before proceeding.
 - 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.
   ComponentKey convention: `{app_code}.{module_code}.{section_code}` (dot-separated, lowercase).
   DynamicRouter generates the URL paths from seed data Route field.
+  **CRITICAL: PageRegistry keys use DOTS as hierarchy separator, NEVER hyphens.**
+  - Correct: `PageRegistry.register('rh.employes.list', lazy(...))`
+  - WRONG:   `PageRegistry.register('rh-employes-list', lazy(...))`
+  NavigationService computes `ComponentKey = "{app.Code}.{module.Code}.{section.Code}"` at runtime.
+  DynamicRouter calls `PageRegistry.resolve(componentKey)` — keys MUST match exactly.
+  For client projects: `import { PageRegistry } from '@atlashub/smartstack';`
+  For SmartStack core: `import { PageRegistry } from '@/extensions/PageRegistry';`
 - MUST use src/pages/{App}/{Module}/ hierarchy (NOT flat)
 
 ### Documentation (after frontend pages exist)
@@ -281,6 +299,88 @@ When delegating to `/ui-components` skill, include explicit instructions:
 - "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`."
 - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`)."
 - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
+- "Hooks: MUST use apiClient from @/services/api — NEVER raw fetch() or direct axios import."
+
+### ⛔ POST-GENERATION VERIFICATION GATES (MANDATORY — run after ALL pages are created)
+
+> **These checks are BLOCKING.** Do not commit until ALL pass. Each check targets a known failure mode
+> observed in production runs where the agent bypassed /ui-components or delegated pages to Snipper agents.
+
+```
+### GATE PG-1: /ui-components Skill Invocation Check
+# Verify that Skill("ui-components") was actually called during this layer execution.
+# The HARD RULE says: "If ANY .tsx page was created by Write tool WITHOUT a prior
+# Skill('ui-components') call, the frontend layer is INVALID."
+#
+# How to verify: Review your own tool call history in this conversation.
+# IF you created ANY .tsx file in src/pages/ WITHOUT calling Skill("ui-components") first:
+#   → FAIL — delete ALL pages in src/pages/, invoke Skill("ui-components"), regenerate.
+#   → This is NOT optional. Pages generated without the skill WILL use fictional CSS classes,
+#     raw HTML <table>, and miss DataTable/EntityCard/CSS variables/responsive design.
+
+### GATE PG-2: Page Completeness Check (4 page types per section)
+# For each section that has a ListPage, verify ALL 4 page types exist:
+for section_dir in $(find src/pages -mindepth 2 -maxdepth 3 -type d); do
+  section_name=$(basename "$section_dir")
+  has_list=$(find "$section_dir" -name "*List*Page.tsx" | head -1)
+  if [ -n "$has_list" ]; then
+    has_detail=$(find "$section_dir" -name "*Detail*Page.tsx" | head -1)
+    has_create=$(find "$section_dir" -name "*Create*Page.tsx" -o -name "Create*Page.tsx" | head -1)
+    has_edit=$(find "$section_dir" -name "*Edit*Page.tsx" -o -name "Edit*Page.tsx" | head -1)
+    if [ -z "$has_detail" ] || [ -z "$has_create" ] || [ -z "$has_edit" ]; then
+      echo "FAIL PG-2: $section_dir missing pages: detail=${has_detail:-MISSING} create=${has_create:-MISSING} edit=${has_edit:-MISSING}"
+      # → Generate missing pages via Skill("ui-components")
+    fi
+  fi
+done
+
+### GATE PG-3: No Stub Pages ("Under development" detection)
+# Pages must be fully implemented — not placeholders.
+grep -rl "Under development\|Under construction\|TODO.*implement\|Coming soon" src/pages/ && {
+  echo "FAIL PG-3: Stub pages detected — all pages must be fully implemented"
+  # → For each stub: invoke Skill("ui-components") to generate the real implementation
+  # → Stubs are NEVER acceptable as deliverables
+}
+
+### GATE PG-4: I18n Namespace Registration Check
+# JSON translation files MUST be imported in i18n config. Missing imports cause
+# all translation keys to render as raw strings (e.g., "list.title" instead of "Liste des employés").
+I18N_CONFIG=$(find src -path "*/i18n/index.ts" -o -path "*/i18n/config.ts" | head -1)
+if [ -n "$I18N_CONFIG" ]; then
+  for json_file in $(find src -path "*/i18n/locales/fr/*.json" -type f); do
+    namespace=$(basename "$json_file" .json)
+    if ! grep -q "$namespace" "$I18N_CONFIG"; then
+      echo "FAIL PG-4: Namespace '$namespace' not registered in $I18N_CONFIG"
+      # → Add import + registration for all 4 languages (fr, en, it, de)
+    fi
+  done
+fi
+
+### GATE PG-5: No Raw fetch() in Hooks
+# Hooks MUST use apiClient from @/services/api (which handles auth, token refresh, tenant isolation).
+# Raw fetch() bypasses authentication and session management.
+grep -rl "fetch(" src/hooks/ && {
+  echo "FAIL PG-5: Raw fetch() found in hooks — must use apiClient from @/services/api"
+  # → Rewrite hooks to use: import apiClient from '@/services/api';
+  # → Replace fetch() calls with apiClient.get(), apiClient.post(), etc.
+}
+
+### GATE PG-6: No Fictional CSS Classes
+# Pages MUST use Tailwind + CSS variables. Fictional classes indicate /ui-components was bypassed.
+FICTIONAL_CLASSES="page-container\|page-header\|page-actions\|filter-bar\|data-table\|btn btn-primary\|btn btn-outline\|btn-sm\|loading-spinner\|empty-state"
+grep -rl "$FICTIONAL_CLASSES" src/pages/ && {
+  echo "FAIL PG-6: Fictional CSS classes found — pages were not generated by /ui-components"
+  # → Delete ALL pages, invoke Skill("ui-components"), regenerate from scratch
+}
+
+### GATE PG-7: Agent Boundary Verification
+# This is a self-check: review all Agent() calls made during Layer 3.
+# IF any Agent(subagent_type='Snipper') prompt contained "Page.tsx" or "pages/" file creation:
+#   → VIOLATION of the agent boundary rule (Snipper cannot generate pages)
+#   → Delete pages created by Snipper, regenerate via Skill("ui-components")
+```
+
+> **If ANY gate fails:** Fix the issue, then re-run ALL gates. Do not commit with failures.
 
 ### Frontend Tests Inline
 

package/templates/skills/application/references/frontend-route-wiring-app-tsx.md

@@ -48,6 +48,9 @@ import './extensions/componentRegistry.generated';
 
 ## For Client SDK Pages
 
+> **CRITICAL:** Keys use DOT notation (`rh.employes.list`), NEVER hyphens (`rh-employes-list`).
+> Dots are hierarchy separators matching `NavigationService.ComponentKey` computation at runtime.
+
 Clients register their own pages directly:
 
 ```tsx

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

@@ -236,3 +236,17 @@ STEP 04 (consolidate) — FINAL BA STEP
 ## Entry Point
 
 **FIRST ACTION:** Load `steps/step-00-init.md`
+
+<success_criteria>
+- Web research performed: >= 2 WebSearch per application + 1 per complex module (Level 1 + Level 2)
+- cadrage.json with domain research findings, business process mapping, competitive analysis
+- Module completeness challenged per application against industry archetypes (module-completeness-challenge.md)
+- ALL CORE modules present or explicitly excluded with documented justification in globalScope.outOfScope
+- Section completeness: workflow modules have >= 5 sections including contextual views (open-requests, rejected, history, etc.)
+- Business rules: >= 2 domain-specific rules per module (not just generic CRUD validation)
+- entities.json, rules.json, usecases.json, permissions.json par module
+- Validation cross-module completee (modele de donnees, coherence permissions, flux E2E)
+- validation.json with qualityAssessment (self-scoring) and processCoverage
+- Quality self-assessment score >= 7/10 (research + modules + sections + rules)
+- Statut feature mis a jour a "consolidated" dans index.json
+</success_criteria>

package/templates/skills/business-analyse/_shared.md

@@ -1,5 +1,32 @@
 # Business Analysis — Shared Conventions
 
+## Fundamental Analysis Rules
+
+1. **NEVER skip web research.** Domain research is MANDATORY and BLOCKING.
+   An analysis without research is a 2/10 regardless of structural quality.
+
+2. **NEVER accept a thin application.** Every application MUST be challenged
+   against industry standard module counts (see `references/module-completeness-challenge.md`).
+   A 1-module billing application is ALWAYS wrong — challenge it.
+
+3. **ALWAYS propose domain-specific business rules.** Generic CRUD rules
+   (date validation, required fields) are the MINIMUM baseline. Domain rules
+   (half-day absences, team capacity, carry-over limits, credit note linking,
+   sequential invoice numbering) are what make an analysis valuable.
+
+4. **ALWAYS propose contextual views.** A workflow module without filtered
+   views (open-requests, rejected, history, my-{entity}) is incomplete.
+
+5. **ALWAYS process application by application.** Research each app's domain
+   before decomposing into modules. Challenge module completeness per app.
+
+6. **ACT AS AN EXPERT ANALYST, NOT A NOTE-TAKER.** Challenge, propose,
+   question. If the user says "billing with invoices", your job is to say
+   "standard billing also includes credit notes, payment tracking, and
+   dunning. Would you like to add these?" The user came to you for expertise.
+
+---
+
 ## JSON-First Architecture
 
 Feature data is stored as granular JSON files, NOT markdown. Each module has an `index.json` referencing thematic files.