@atlashub/smartstack-cli 3.31.0 → 3.32.0

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -228,10 +228,11 @@ const checklist = {
   },
 
   seedDataBusiness: {
-    check: "Business seed data template defined for modules with reference/lookup entities",
-    status: specification.seedDataBusiness !== undefined ? "PASS" : "FAIL",
-    blocking: true,  // BLOCKING — missing seed data causes empty dropdowns and test failures
-    details: "Business seed data (reference types, categories, statuses) is required for testing and dev environment"
+    check: "Business seed data template defined (if applicable — generated during implementation, not BA)",
+    status: specification.seedDataBusiness !== undefined ? "PASS" : "WARN",
+    blocking: false,  // WARNING only — business seed data is generated during ralph-loop implementation, not during BA phase
+    details: "Business seed data (reference types, categories, statuses) is generated during implementation (ralph-loop). " +
+             "BA phase ensures seedDataCore is complete (navigation, permissions). seedDataBusiness is optional at this stage."
   },
 
   // SECTION 8: API ENDPOINTS (BLOCKING)

package/templates/skills/business-analyse/schemas/sections/analysis-schema.json

@@ -78,6 +78,50 @@
                 "description": { "type": "string" }
               }
             }
+          },
+          "codePattern": {
+            "type": "object",
+            "description": "Code auto-generation strategy for this entity. Defines how entity codes are automatically generated (e.g., acme-emp-00001).",
+            "properties": {
+              "strategy": {
+                "type": "string",
+                "enum": ["sequential", "timestamp-daily", "timestamp-minute", "year-sequential", "uuid-short", "manual"],
+                "default": "sequential",
+                "description": "Code generation strategy. sequential: {tenant}-{prefix}-{N}. timestamp-daily: {tenant}-{prefix}-{YYYYMMDD}-{N}. timestamp-minute: {tenant}-{prefix}-{YYYYMMDDHHmm}-{N}. year-sequential: {tenant}-{prefix}-{YYYY}-{N}. uuid-short: {tenant}-{prefix}-{8hex}. manual: user-provided."
+              },
+              "prefix": {
+                "type": "string",
+                "pattern": "^[a-z]{2,6}$",
+                "description": "Entity prefix in the code (e.g., emp for Employee, inv for Invoice)"
+              },
+              "includeTenantSlug": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether to include the tenant slug as prefix (e.g., acme-emp-00001 vs emp-00001)"
+              },
+              "separator": {
+                "type": "string",
+                "enum": ["-", "_"],
+                "default": "-",
+                "description": "Separator between code segments"
+              },
+              "estimatedVolume": {
+                "type": "integer",
+                "minimum": 10,
+                "maximum": 10000000,
+                "description": "Estimated number of records per tenant. Used to calculate digit count via x10 rule: digits = max(4, ceil(log10(volume * 10)))"
+              },
+              "digits": {
+                "type": "integer",
+                "minimum": 4,
+                "maximum": 7,
+                "description": "Number of digits for sequential part. Auto-calculated from estimatedVolume if omitted."
+              },
+              "example": {
+                "type": "string",
+                "description": "Example generated code for documentation (e.g., acme-emp-00001)"
+              }
+            }
           }
         }
       }

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

@@ -88,6 +88,61 @@ Define entities for this module (business attributes, not technical):
 > **Why forbidden:** `tableName`, `primaryKey` are technical fields that do NOT belong in analysis. `fields[]` is NOT recognized by the build pipeline — only `attributes[]` is. `type` with SQL types (UUID, string, timestamp) belongs in implementation, not analysis. Using this format causes **empty entity data in the HTML documentation** and **broken PRD extraction**.
 > The canonical format uses `attributes[]` (not `fields[]`), `relationships[]` (not FK inside fields), and NO technical fields (tableName, primaryKey).
 
+#### 6b-bis. Code Pattern Definition
+
+For EACH entity defined above, determine the code generation strategy.
+
+> **STRUCTURE CARD: analysis.entities[].codePattern**
+> ```json
+> {
+>   "strategy": "sequential|timestamp-daily|timestamp-minute|year-sequential|uuid-short|manual",
+>   "prefix": "emp",
+>   "includeTenantSlug": true,
+>   "separator": "-",
+>   "estimatedVolume": 1000,
+>   "digits": 5,
+>   "example": "acme-emp-00001"
+> }
+> ```
+
+**Strategy selection heuristic** (use as default when user does not specify):
+
+| Entity type / name pattern | Default strategy | Example |
+|---------------------------|-----------------|---------|
+| Invoice, Order, Receipt, Bill, Delivery | `timestamp-daily` | `acme-inv-20260215-001` |
+| Ticket, Request, Incident, Support, Alert | `timestamp-minute` | `acme-ticket-202602151430-001` |
+| Contract, Agreement, Policy, License | `year-sequential` | `acme-ctr-2026-00001` |
+| Reference, Category, Tag, Type, Status | `uuid-short` | `acme-ref-a1b2c3d4` |
+| Employee, Customer, Partner, Project, Product | `sequential` | `acme-emp-00001` |
+| User says "manual" or "user-provided" | `manual` | (user types the code) |
+
+**Digits calculation (x10 rule):**
+- Use Q4.4 (estimated volume) as input
+- Apply: `digits = max(4, ceil(log10(volume * 10)))`
+- If no volume estimate: default to 5 digits (capacity: 99,999)
+
+**Interactive question (if NOT team agent):**
+
+```yaml
+questions:
+  - header: "Code Pattern"
+    question: "For entity {entityName}, how should the Code be generated?"
+    options:
+      - label: "Auto-sequential (Recommended)"
+        description: "{tenant}-{prefix}-00001 — simple sequential numbering"
+      - label: "Date-based (daily)"
+        description: "{tenant}-{prefix}-20260215-001 — includes creation date"
+      - label: "Year-sequential"
+        description: "{tenant}-{prefix}-2026-00001 — yearly numbering"
+      - label: "Manual entry"
+        description: "User provides the code — no auto-generation"
+    multiSelect: false
+```
+
+If team agent: use heuristic defaults autonomously.
+
+**Reference:** See `apex/references/code-generation.md` for full ICodeGenerator<T> implementation details, DI registration patterns, and backend service integration.
+
 #### 6c. Process Flow
 
 Define the main business process flow for this module (not lifecycle — that's in 8j):
@@ -109,7 +164,10 @@ Define the main business process flow for this module (not lifecycle — that's
 > ```
 > **FORBIDDEN:** Do NOT put lifecycle/state machine data here. Use `specification.lifeCycles[]` for that.
 
-#### 6d. Data Lifecycle
+#### 6d. Data Lifecycle (MANDATORY — ALL modules)
+
+> **CRITICAL:** This section is MANDATORY for EVERY module, even simple ones without GDPR requirements.
+> Missing `analysis.dataLifecycle` causes BLOCKING errors in step-03d validation and consolidation structural checks.
 
 Define data retention and lifecycle policies:
 
@@ -126,6 +184,19 @@ Define data retention and lifecycle policies:
 >   ]
 > }
 > ```
+>
+> **Standard defaults** (use for modules without specific GDPR/retention requirements):
+> ```json
+> {
+>   "retentionPeriod": "Standard (as per company policy)",
+>   "archiveStrategy": "Soft-delete with audit trail",
+>   "gdprCompliance": "N/A — no PII or standard audit trail only",
+>   "states": [
+>     { "name": "active", "transitions": ["archived"] },
+>     { "name": "archived", "transitions": ["active"] }
+>   ]
+> }
+> ```
 
 ### 7. Business Rules Extraction
 

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

@@ -258,13 +258,47 @@ Module → Sections → Resources (levels 3-4-5 of the hierarchy).
 > ```json
 > {
 >   "entries": [
->     { "level": "module", "code": "{module}", "labels": {"fr": "...", "en": "..."}, "route": "/business/{app}/{module}", "icon": "list" },
+>     { "level": "module", "code": "{module}", "labels": {"fr": "...", "en": "...", "it": "...", "de": "..."}, "route": "/business/{app}/{module}", "icon": "list" },
 >     { "level": "section", "code": "list", "labels": {"fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste"}, "route": "/business/{app}/{module}", "icon": "list" },
->     { "level": "section", "code": "dashboard", "labels": {"fr": "Dashboard", "en": "Dashboard"}, "route": "/business/{app}/{module}/dashboard", "icon": "chart-bar", "isNew": true }
+>     { "level": "section", "code": "dashboard", "labels": {"fr": "Tableau de bord", "en": "Dashboard", "it": "Cruscotto", "de": "Dashboard"}, "route": "/business/{app}/{module}/dashboard", "icon": "chart-bar", "isNew": true }
 >   ]
 > }
 > ```
 
+#### 8e-POST-CHECK: Navigation Enforcement (BLOCKING)
+
+> **CRITICAL:** `specification.navigation.entries[]` is MANDATORY. If absent, auto-generate from sections.
+
+```javascript
+const nav = specification.navigation;
+if (!nav || !nav.entries || nav.entries.length === 0) {
+  console.warn('AUTO-FIX: navigation.entries is empty — generating from sections');
+  const sections = specification.sections || [];
+  const entries = [
+    { level: "module", code: "{module}", labels: {fr: "{ModuleName}", en: "{ModuleName}", it: "{ModuleName}", de: "{ModuleName}"}, route: "/business/{app}/{module}", icon: "list" }
+  ];
+  for (const section of sections) {
+    entries.push({
+      level: "section",
+      code: section.code,
+      labels: {fr: section.name || section.code, en: section.name || section.code, it: section.name || section.code, de: section.name || section.code},
+      route: section.route || `/business/{app}/{module}/${section.code}`,
+      icon: section.icon || "file-text"
+    });
+  }
+  specification.navigation = { entries };
+}
+// Verify ALL entries have 4 languages
+for (const entry of specification.navigation.entries) {
+  for (const lang of ['fr', 'en', 'it', 'de']) {
+    if (!entry.labels[lang]) {
+      entry.labels[lang] = entry.labels['en'] || entry.labels['fr'] || entry.code;
+      console.warn(`AUTO-FIX: navigation entry "${entry.code}" missing ${lang} label — copied from fallback`);
+    }
+  }
+}
+```
+
 #### 8f. SeedData Core
 
 7 MANDATORY typed arrays — each with structured objects, NOT flat strings or objects.
@@ -489,17 +523,64 @@ RESTful routes following SmartStack patterns.
 Translation keys for all UI text (4 languages: fr, en, it, de).
 
 > **STRUCTURE CARD: specification.i18nKeys**
+> **CRITICAL:** ALL leaf translation keys MUST have 4 languages (fr, en, it, de). IT/DE can use shorter translations but MUST exist.
 > ```json
 > {
 >   "title": { "fr": "{Module}", "en": "{Module}", "it": "{Module}", "de": "{Module}" },
->   "list": { "title": { "fr": "Liste", "en": "List" }, "empty": { "fr": "Aucun enregistrement", "en": "No records" } },
->   "create": { "title": { "fr": "Nouveau", "en": "New" } },
->   "detail": { "title": { "fr": "Détail", "en": "Detail" } },
->   "buttons": { "create": { "fr": "Créer", "en": "Create" }, "edit": { "fr": "Modifier", "en": "Edit" }, "delete": { "fr": "Supprimer", "en": "Delete" } },
->   "validation": { "required": { "fr": "Ce champ est requis", "en": "This field is required" } }
+>   "list": {
+>     "title": { "fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste" },
+>     "empty": { "fr": "Aucun enregistrement", "en": "No records", "it": "Nessun record", "de": "Keine Einträge" }
+>   },
+>   "create": { "title": { "fr": "Nouveau", "en": "New", "it": "Nuovo", "de": "Neu" } },
+>   "detail": { "title": { "fr": "Détail", "en": "Detail", "it": "Dettaglio", "de": "Detail" } },
+>   "buttons": {
+>     "create": { "fr": "Créer", "en": "Create", "it": "Crea", "de": "Erstellen" },
+>     "edit": { "fr": "Modifier", "en": "Edit", "it": "Modifica", "de": "Bearbeiten" },
+>     "delete": { "fr": "Supprimer", "en": "Delete", "it": "Elimina", "de": "Löschen" },
+>     "save": { "fr": "Enregistrer", "en": "Save", "it": "Salva", "de": "Speichern" },
+>     "cancel": { "fr": "Annuler", "en": "Cancel", "it": "Annulla", "de": "Abbrechen" }
+>   },
+>   "validation": {
+>     "required": { "fr": "Ce champ est requis", "en": "This field is required", "it": "Campo obbligatorio", "de": "Pflichtfeld" }
+>   }
 > }
 > ```
 
+#### 8l-POST-CHECK: i18n 4 Languages Enforcement (BLOCKING)
+
+> **CRITICAL:** i18n keys with missing IT/DE translations are a recurring issue.
+> This POST-CHECK walks ALL leaf keys and auto-fills missing translations.
+
+```javascript
+const i18n = specification.i18nKeys || {};
+const REQUIRED_LANGS = ['fr', 'en', 'it', 'de'];
+let missingCount = 0;
+
+function walkI18n(obj, path) {
+  if (typeof obj !== 'object' || obj === null) return;
+  // Leaf node: has at least 'fr' or 'en' as direct string properties
+  const hasLangKey = REQUIRED_LANGS.some(l => typeof obj[l] === 'string');
+  if (hasLangKey) {
+    for (const lang of REQUIRED_LANGS) {
+      if (!obj[lang] || typeof obj[lang] !== 'string') {
+        // Fallback: copy from en > fr > first available
+        obj[lang] = obj['en'] || obj['fr'] || Object.values(obj).find(v => typeof v === 'string') || path;
+        missingCount++;
+      }
+    }
+  } else {
+    // Branch node: recurse
+    for (const key of Object.keys(obj)) {
+      walkI18n(obj[key], `${path}.${key}`);
+    }
+  }
+}
+walkI18n(i18n, 'i18nKeys');
+if (missingCount > 0) {
+  console.warn(`AUTO-FIX: filled ${missingCount} missing i18n translations (IT/DE fallbacks from EN/FR)`);
+}
+```
+
 ---
 
 ## SELF-VERIFICATION (MANDATORY before loading next step)
@@ -521,6 +602,11 @@ Before loading step-03d-validate, verify all 12 subsections (8a-8l) are populate
 
 13. **Wireframes present** — `(specification.uiWireframes || specification.wireframes || []).length >= 1` (BLOCKING)
     Quick check: the wireframe data from step-03b MUST still be in memory OR persisted to feature.json
+
+14. **Wireframes create/edit** — For each data-centric section with a create form, a wireframe `{section}-create` MUST exist (BLOCKING).
+    For each modifiable entity, a wireframe `{section}-edit` SHOULD exist (WARNING if absent).
+    Create/edit wireframes are action-page wireframes — they are NOT separate navigation sections.
+    They describe the full-page form layout (fields, validation, submit/cancel buttons).
     (step-03b now writes wireframes intermediately). If wireframes are empty:
     - First, re-read the module feature.json to check if step-03b wrote them
     - If present in file but not in memory → load them from file

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

@@ -60,7 +60,9 @@ Validate the module specification for completeness and consistency, write to fea
 | permissionMatrix | 1 resource × 2 roles | `specification.permissionMatrix.permissions.length >= 1 && specification.permissionMatrix.roleAssignments.length >= 2` | PASS/FAIL |
 | entities | 1 | `analysis.entities.length >= 1` | PASS/FAIL |
 | entitySchemaFormat | attributes[] not fields[] (BLOCKING) | `analysis.entities.every(e => e.attributes?.length > 0)` | PASS/FAIL |
-| entityAttributeTypes | ALL attributes have `type` field (BLOCKING) | `analysis.entities.every(e => e.attributes.every(a => a.type))` | PASS/FAIL |
+| entityAttributeTypes | ALL attributes have `type` field (BLOCKING) | `analysis.entities.every(e => e.attributes.every(a => a.type))` — **NOTE:** Entities in analysis phase may NOT have `type`. Step-03c auto-fix MUST have run first. If types are missing, RE-RUN step-03c auto-fix algorithm. | PASS/FAIL |
+| navigation | entries[] present (BLOCKING) | `specification.navigation?.entries?.length >= 1` | PASS/FAIL |
+| dataLifecycle | present in analysis (BLOCKING) | `analysis.dataLifecycle !== undefined` | PASS/FAIL |
 | wireframes | 1 per section (BLOCKING) | `(specification.uiWireframes \|\| specification.wireframes \|\| []).length >= (specification.sections \|\| []).length` (count REAL elements, check BOTH key names) | PASS/FAIL |
 | wireframeSchema | All required fields present (BLOCKING) | `(specification.uiWireframes \|\| specification.wireframes \|\| []).every(w => (w.screen \|\| w.title) && w.section && (w.mockup \|\| w.ascii \|\| w.content))` | PASS/FAIL |
 | sections | 1 (BLOCKING) | `specification.sections.length >= 1` (EVERY module needs at least 1 section) | PASS/FAIL |
@@ -243,6 +245,19 @@ ba-writer.enrichSection({
 })
 ```
 
+#### 9e-POST-CHECK: Validation Section Persistence (BLOCKING)
+
+> **CRITICAL:** The `validation` section MUST be persisted to feature.json. Without it, consolidation checks fail.
+
+```bash
+MODULE_JSON="{module_feature_json_path}"
+node -e "const d=JSON.parse(require('fs').readFileSync(process.argv[1],'utf-8'));
+if(!d.validation||!d.validation.decision) { console.error('FAIL: validation section missing or incomplete'); process.exit(1); }
+console.log('PASS: validation section present with decision');" "$MODULE_JSON"
+```
+
+IF this check FAILS → re-execute section 9e write and re-run this check.
+
 #### 9f. Module Specification Checklist (BLOCKING)
 
 > **CRITICAL:** This checklist MUST be FULLY COMPLETED before marking module status = "specified".
@@ -453,10 +468,27 @@ const checks = [
   ['gherkin is array',       Array.isArray(spec.gherkinScenarios)?1:0, 1],
   ['apiEndpoints >= 1',      (spec.apiEndpoints||[]).length,           1],
   ['messages >= 4',          (spec.messages||[]).length,               4],
-  ['validations >= 1',       (spec.validations||[]).length,            1]
+  ['validations >= 1',       (spec.validations||[]).length,            1],
+  ['navigation entries',     (spec.navigation?.entries||[]).length,    1],
+  ['dataLifecycle',          analysis.dataLifecycle ? 1 : 0,           1],
+  ['validation section',     data.validation ? 1 : 0,                  1]
 ];
+// AC-18: i18n 4 languages check
+const i18n = spec.i18nKeys || {};
+const i18nLangs = ['fr','en','it','de'];
+let i18nMissing = 0;
+function checkI18nLeaf(obj) {
+  if (typeof obj !== 'object' || obj === null) return;
+  const hasLang = i18nLangs.some(l => typeof obj[l] === 'string');
+  if (hasLang) { i18nLangs.forEach(l => { if (!obj[l]) i18nMissing++; }); }
+  else { Object.values(obj).forEach(v => checkI18nLeaf(v)); }
+}
+checkI18nLeaf(i18n);
+checks.push(['i18n 4 languages (missing keys)', 0, i18nMissing > 10 ? 1 : 0]);
+
 const fails = checks.filter(c => c[1] < c[2]);
 fails.forEach(f => console.error('FAIL: ' + f[0] + ' = ' + f[1] + ' (min: ' + f[2] + ')'));
+if (i18nMissing > 0 && i18nMissing <= 10) { console.warn('WARNING: ' + i18nMissing + ' i18n leaf keys missing translations (IT/DE)'); }
 // Check wireframe content
 const emptyWf = wf.filter(w => !w.mockup && !w.ascii && !w.content);
 if (emptyWf.length > 0) { fails.push(['wireframe content', 0, 1]); console.error('FAIL: ' + emptyWf.length + ' wireframes have EMPTY content'); }

package/templates/skills/business-analyse/steps/step-04b-analyze.md

@@ -87,6 +87,46 @@ options:
     description: "Le Manager devrait aussi pouvoir approuver les factures"
 ```
 
+**3e. Permission-Role Coherence Across Modules (WARNING)**
+
+For each role defined in `cadrage.applicationRoles`, verify the permission PATTERN is consistent across ALL modules:
+
+```javascript
+// Build role-to-actions matrix per module
+const roleActions = {};
+for (const module of completedModules) {
+  const pm = module.specification.permissionMatrix;
+  for (const ra of pm.roleAssignments || []) {
+    const key = ra.role;
+    if (!roleActions[key]) roleActions[key] = {};
+    roleActions[key][module.code] = ra.permissions.map(p => p.split('.').pop()); // extract action
+  }
+}
+
+// Detect inconsistencies: role has action X in module A but not in module B
+for (const [role, modules] of Object.entries(roleActions)) {
+  const allActions = new Set(Object.values(modules).flat());
+  for (const [mod, actions] of Object.entries(modules)) {
+    for (const action of allActions) {
+      if (!actions.includes(action)) {
+        // Role has this action in other modules but NOT in this one
+        const otherMods = Object.entries(modules).filter(([m, a]) => a.includes(action)).map(([m]) => m);
+        console.warn(`WARNING: permission-role-coherence: ${role} has "${action}" in [${otherMods.join(', ')}] but NOT in ${mod}`);
+      }
+    }
+  }
+}
+```
+
+Store as semantic check with severity WARNING (not ERROR — some permission differences may be intentional):
+```json
+{
+  "check": "permission-role-coherence",
+  "status": "WARNING",
+  "details": "Contributor has 'create' in [Projects, TimeManagement] but NOT in Employees — verify if intentional"
+}
+```
+
 ### 4. Semantic Validation (MANDATORY)
 
 For EACH module feature.json, execute these checks:

package/templates/skills/controller/references/controller-code-templates.md

@@ -49,7 +49,7 @@ public class {module}Controller : ControllerBase
 ```csharp
 [HttpGet]
 [RequirePermission(Permissions.{module}.View)]
-[ProducesResponseType(typeof(PagedResult<{entity}ResponseDto>), StatusCodes.Status200OK)]
+[ProducesResponseType(typeof(PaginatedResult<{entity}ResponseDto>), StatusCodes.Status200OK)]
 [ProducesResponseType(StatusCodes.Status401Unauthorized)]
 [ProducesResponseType(StatusCodes.Status403Forbidden)]
 public async Task<IActionResult> GetAll(
@@ -68,7 +68,7 @@ public async Task<IActionResult> GetAll(
         .Select(x => new {entity}ResponseDto(x))
         .ToListAsync(ct);
 
-    return Ok(new PagedResult<{entity}ResponseDto>(items, total, page, pageSize));
+    return Ok(new PaginatedResult<{entity}ResponseDto>(items, total, page, pageSize));
 }
 ```
 

package/templates/skills/controller/templates.md

@@ -53,8 +53,8 @@ public class {Module}Controller : ControllerBase
 
     [HttpGet]
     [RequirePermission(Permissions.{PermissionClass}.View)]
-    [ProducesResponseType(typeof(PagedResult<{Entity}ListDto>), StatusCodes.Status200OK)]
-    public async Task<ActionResult<PagedResult<{Entity}ListDto>>> Get{Module}(
+    [ProducesResponseType(typeof(PaginatedResult<{Entity}ListDto>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<PaginatedResult<{Entity}ListDto>>> Get{Module}(
         [FromQuery] int page = 1,
         [FromQuery] int pageSize = 20,
         [FromQuery] string? search = null,
@@ -89,7 +89,7 @@ public class {Module}Controller : ControllerBase
         _logger.LogInformation("User {User} retrieved {Count} {Module}",
             _currentUser.Email, items.Count, "{Module}");
 
-        return Ok(new PagedResult<{Entity}ListDto>(items, totalCount, page, pageSize));
+        return Ok(new PaginatedResult<{Entity}ListDto>(items, totalCount, page, pageSize));
     }
 
     #endregion
@@ -329,7 +329,7 @@ public record Update{Entity}Request(
     string? Description
 );
 
-public record PagedResult<T>(
+public record PaginatedResult<T>(
     List<T> Items,
     int TotalCount,
     int Page,
@@ -337,8 +337,8 @@ public record PagedResult<T>(
 )
 {
     public int TotalPages => (int)Math.Ceiling((double)TotalCount / PageSize);
-    public bool HasPrevious => Page > 1;
-    public bool HasNext => Page < TotalPages;
+    public bool HasPreviousPage => Page > 1;
+    public bool HasNextPage => Page < TotalPages;
 }
 
 #endregion
@@ -813,7 +813,7 @@ return NotFound(new { message = "Resource not found" });
 ```csharp
 public static class QueryableExtensions
 {
-    public static async Task<PagedResult<T>> ToPagedResultAsync<T>(
+    public static async Task<PaginatedResult<T>> ToPaginatedResultAsync<T>(
         this IQueryable<T> query,
         int page,
         int pageSize,
@@ -825,7 +825,7 @@ public static class QueryableExtensions
             .Take(pageSize)
             .ToListAsync(ct);
 
-        return new PagedResult<T>(items, totalCount, page, pageSize);
+        return new PaginatedResult<T>(items, totalCount, page, pageSize);
     }
 }
 ```
@@ -1514,7 +1514,7 @@ public class ContactsController : ControllerBase
 {
     [HttpGet]
     [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
-    public async Task<ActionResult<PagedResult<ContactDto>>> GetAll(...) { ... }
+    public async Task<ActionResult<PaginatedResult<ContactDto>>> GetAll(...) { ... }
 }
 
 // v2 - Breaking changes only
@@ -1525,7 +1525,7 @@ public class ContactsV2Controller : ControllerBase
 {
     [HttpGet]
     [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
-    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAll(...) { ... }
+    public async Task<ActionResult<PaginatedResult<ContactV2Dto>>> GetAll(...) { ... }
 }
 ```
 
@@ -1538,11 +1538,11 @@ public class ContactsController : ControllerBase
 {
     [HttpGet]
     [MapToApiVersion("1.0")]
-    public async Task<ActionResult<PagedResult<ContactDto>>> GetAllV1(...) { ... }
+    public async Task<ActionResult<PaginatedResult<ContactDto>>> GetAllV1(...) { ... }
 
     [HttpGet]
     [MapToApiVersion("2.0")]
-    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAllV2(...) { ... }
+    public async Task<ActionResult<PaginatedResult<ContactV2Dto>>> GetAllV2(...) { ... }
 }
 ```
 

package/templates/skills/feature-full/steps/step-01-implementation.md

@@ -22,7 +22,7 @@ public enum {Entity}Status { Active = 0, Inactive = 1, Archived = 2 }
 
 ```csharp
 // I{Entity}Service.cs
-Task<PagedResult<{Entity}Dto>> GetAllAsync(...);
+Task<PaginatedResult<{Entity}Dto>> GetAllAsync(...);
 Task<{Entity}Dto> CreateAsync(Create{Entity}Request request, CancellationToken ct);
 
 // DTOs
@@ -62,8 +62,8 @@ services.AddScoped<I{Entity}Service, {Entity}Service>();
 public class {Entity}Controller : ControllerBase
 {
     [HttpGet][RequirePermission(Permissions.{Area}.{Module}.View)]
-    [ProducesResponseType(typeof(PagedResult<{Entity}Dto>), 200)]
-    public async Task<ActionResult<PagedResult<{Entity}Dto>>> GetAll(...);
+    [ProducesResponseType(typeof(PaginatedResult<{Entity}Dto>), 200)]
+    public async Task<ActionResult<PaginatedResult<{Entity}Dto>>> GetAll(...);
 
     [HttpPost][RequirePermission(Permissions.{Area}.{Module}.Create)]
     [ProducesResponseType(typeof({Entity}Dto), 201)]
@@ -76,7 +76,7 @@ public class {Entity}Controller : ControllerBase
 ```typescript
 // {module}Api.ts
 export const {module}Api = {
-  getAll: (page, pageSize, search?) => apiClient.get<PagedResult<{Entity}Dto>>('/{area}/{module}', { params }),
+  getAll: (page, pageSize, search?) => apiClient.get<PaginatedResult<{Entity}Dto>>('/{area}/{module}', { params }),
   create: (data) => apiClient.post<{Entity}Dto>('/{area}/{module}', data),
 };
 

package/templates/skills/ralph-loop/references/category-rules.md

@@ -205,7 +205,7 @@ public class {Entity}Service : I{Entity}Service
         _currentUser = currentUser;
     }
 
-    public async Task<PagedResult<{Entity}Response>> GetAllAsync(/* filters */, CancellationToken ct)
+    public async Task<PaginatedResult<{Entity}Response>> GetAllAsync(/* filters */, CancellationToken ct)
     {
         var tenantId = _currentUser.TenantId;
         var query = _db.{Entities}
@@ -385,7 +385,7 @@ fi
 - Edit form: `EntityEditPage.tsx` with route `/{module}/:id/edit`
 - ALL forms are full pages with their own URL — NEVER Modal/Dialog/Drawer/Popup
 - Back button with `navigate(-1)` on every form page
-- Use React.lazy() + `<Suspense fallback={<PageLoader />}>` for form page imports
+- Use React.lazy() + `<Suspense fallback={<PageLoader />}>` for ALL page imports (not just forms — see "Lazy loading" section above)
 - **Form tests (MANDATORY):** Co-located `EntityCreatePage.test.tsx` and `EntityEditPage.test.tsx`
   → Cover: rendering, validation, submit, pre-fill (edit), navigation, error handling
 
@@ -433,6 +433,45 @@ fi
 - Error messages MUST use i18n: `setError(t('{mod}:errors.saveFailed'))` — NEVER hardcoded English strings
 - Toast/notification messages MUST also use i18n
 
+**Service call pattern (MANDATORY — NO custom entity hooks):**
+
+> **ROOT CAUSE (test-v4-014):** ralph-loop generated custom hooks (`useEmployees()`, `useProjects()`,
+> `useTimeManagement()`) that wrapped services with `useState`/`useEffect`/`try-catch`.
+> These hooks swallowed 401 errors with generic `catch → setError(string)`, creating a race condition
+> with SmartStack's auth interceptor (`window.location.href = "/login"`).
+> Result: token cleared + redirect + React re-render → cascade of unauthenticated requests.
+
+- Pages MUST call API services **directly** in `useCallback` + `useEffect` — NOT through custom wrapper hooks
+- FORBIDDEN: `useEmployees()`, `useProjects()`, `use{Entity}()` — custom hooks that wrap service calls with useState/useEffect/try-catch
+- Only allowed custom hook: `use{Module}Preferences.ts` (preferences only, step 5)
+- Pattern for pages:
+  ```tsx
+  // CORRECT — direct service call in page component
+  const [data, setData] = useState<EmployeeResponseDto[]>([]);
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    try {
+      const response = await employeeApi.getAll({ pageSize: 200 });
+      setData(response.items);  // ← extract .items from PaginatedResult
+    } catch { setError(t('employees:errors.loadFailed')); }
+    finally { setLoading(false); }
+  }, []);
+  useEffect(() => { fetchData(); }, [fetchData]);
+  ```
+- **PaginatedResult<T>**: ALL service `getAll` methods MUST type responses as `PaginatedResult<T>` — extract `.items` in the page
+- FORBIDDEN: `api.get<Employee[]>(url)` — use `api.get<PaginatedResult<EmployeeResponseDto>>(url)` then `.items`
+
+**Lazy loading (MANDATORY — ALL pages, not just forms):**
+- ALL page imports in App.tsx MUST use `React.lazy()` + `<Suspense fallback={<PageLoader />}>`
+- FORBIDDEN: `lazy(() => import(...))` without a `<Suspense>` boundary in the rendering tree
+- Pattern for App.tsx:
+  ```tsx
+  import { lazy, Suspense } from 'react';
+  const EmployeesListPage = lazy(() => import('./pages/.../EmployeesListPage'));
+  // In routes:
+  { path: 'employees', element: <Suspense fallback={<PageLoader />}><EmployeesListPage /></Suspense> }
+  ```
+
 **Dependency verification (BLOCKING):**
 - BEFORE writing any import, verify the package exists in `package.json`
 - If package not present: run `npm install {package}` BEFORE writing the import
@@ -464,6 +503,9 @@ window.confirm() / confirm()              → MUST use ConfirmDialog component w
 Hardcoded English text in JSX (>Create<)  → MUST use t('{mod}:actions.create', 'Create')
 Hardcoded error strings in hooks           → MUST use t('{mod}:errors.loadFailed') in all hooks
 /business/humanresources/                  → MUST use kebab-case: /business/human-resources/
+useEmployees() / use{Entity}() hooks       → pages call services DIRECTLY in useCallback (no hook wrapper)
+api.get<Employee[]>(url)                   → api.get<PaginatedResult<Employee>>(url) then .items
+lazy(() => import(...)) without Suspense   → ALL lazy pages MUST have <Suspense fallback={<PageLoader />}>
 ```
 
 ---