@atlashub/smartstack-cli 4.30.0 → 4.32.0

package/package.json

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

package/templates/skills/apex/references/code-generation.md

@@ -335,7 +335,7 @@ public class EmployeeService : IEmployeeService
         _db.Employees.Add(entity);
         await _db.SaveChangesAsync(ct);
 
-        return MapToDto(entity);
+        return new EmployeeResponseDto(entity.Id, entity.Code, entity.Name, entity.CreatedAt);
     }
 }
 ```

package/templates/skills/apex/references/parallel-execution.md

@@ -98,14 +98,26 @@ Layer 2 (Backend) — if multiple entities:
   # Launched in parallel in a single message
 
 Layer 3 (Frontend) — if multiple entities:
+  # ⛔ AGENT BOUNDARY: Snipper agents do NOT have access to Skill().
+  # Pages (.tsx) MUST be generated by the principal agent via Skill("ui-components").
+  # Snipper agents handle ONLY: API clients, routes, wiring, i18n — NOT pages.
+
+  # PHASE A — Parallel: infrastructure (Snipper agents)
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 frontend for {Entity1}: pages, i18n, routes...')
+    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity1}: API client, routes, wiring, i18n.
+            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 frontend for {Entity2}: pages, i18n, routes...')
+    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity2}: API client, routes, wiring, i18n.
+            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
   # Launched in parallel in a single message
+
+  # PHASE B — Sequential: pages (principal agent only)
+  # After all Snipper agents complete, principal generates pages via Skill("ui-components").
+  # See step-03-execute.md Layer 3 HARD RULE for full protocol.
 ```
 
 Each agent has an **isolated scope**: handles one entity end-to-end within the layer.
+**Exception:** Layer 3 pages are NOT delegated — see step-03 HARD RULE.
 
 ---
 
@@ -129,8 +141,9 @@ Each agent has an **isolated scope**: handles one entity end-to-end within the l
 5. Layer 2: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
 6. Build gate: dotnet build → MUST PASS
 7. Backend tests inline (scaffold + run + fix max 3)
-8. Layer 3: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
-9. Compliance gate: 5 frontend checks → MUST PASS
+8. Layer 3 Phase A: launch Snipper agents for infra (api-client, routes, i18n) — NOT pages
+9. Layer 3 Phase B: principal agent generates ALL pages via Skill("ui-components") — sequential
+10. Compliance gate: 6 frontend checks → MUST PASS
 10. Frontend tests inline (scaffold + run + fix max 3)
 11. Layer 4 (optional): agent principal executes DevData
 ```
@@ -151,6 +164,6 @@ There is no idle state to manage — the agent principal simply waits for result
 | economy_mode = true | NO parallel agents, all sequential |
 | Single entity (any layer) | NO parallel agents, agent principal handles all |
 | Multiple entities, Layer 2 | Parallel: one Snipper agent per entity (service + controller) |
-| Multiple entities, Layer 3 | Parallel: one Snipper agent per entity (pages + i18n) |
+| Multiple entities, Layer 3 | Parallel: Snipper agents for infra (api-client, routes, i18n) — pages by principal via Skill("ui-components") |
 | Layer 0, Layer 1, Layer 4 | NO parallel agents (sequential by nature) |
 | Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |

package/templates/skills/apex/references/person-extension-pattern.md

@@ -401,7 +401,17 @@ public class CustomerService : ICustomerService
         _db.Customers.Add(entity);
         await _db.SaveChangesAsync(ct);
 
-        return MapToDto(entity);
+        // Reload with User for response
+        var created = await _db.Customers
+            .Include(x => x.User)
+            .FirstAsync(x => x.Id == entity.Id, ct);
+
+        return new CustomerResponseDto(
+            created.Id, created.Code, created.Status, created.CompanyName,
+            created.User != null ? created.User.FirstName : created.FirstName,
+            created.User != null ? created.User.LastName : created.LastName,
+            created.User != null ? created.User.Email : created.Email,
+            created.UserId);
     }
 }
 ```
@@ -508,7 +518,18 @@ public record CustomerResponseDto(
 />
 
 // Business fields only — no person fields
-<input type="date" value={formData.hireDate} ... />
+<div>
+  <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
+    {t('module:form.hireDate', 'Hire Date')}
+  </label>
+  <input
+    type="date"
+    value={formData.hireDate}
+    onChange={(e) => handleChange('hireDate', e.target.value)}
+    required
+    className="w-full px-3 py-2 rounded-[var(--radius-input)] border border-[var(--border-color)] bg-[var(--bg-tertiary)] text-[var(--text-primary)] focus:outline-none focus:ring-2 focus:ring-[var(--color-accent-500)]"
+  />
+</div>
 ```
 
 ### Optional — CreatePage

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

@@ -1926,6 +1926,58 @@ if [ -n "$APP_TSX" ]; then
 fi
 ```
 
+### POST-CHECK C53: Enum serialization — JsonStringEnumConverter required (BLOCKING)
+
+> **Source:** Frontend sends enum values as strings ("PaidLeave", "Morning") but C# enums serialize
+> as integers by default. Without `JsonStringEnumConverter`, the JSON binding fails → 400 Bad Request
+> on create/update endpoints. The enum check in step-03 Layer 0 can be skipped by the LLM — this
+> POST-CHECK catches it as defense-in-depth.
+
+```bash
+# Check if global JsonStringEnumConverter exists in Program.cs
+PROGRAM_CS=$(find src/ -name "Program.cs" -path "*/Api/*" 2>/dev/null | head -1)
+HAS_GLOBAL_CONVERTER=false
+if [ -n "$PROGRAM_CS" ] && grep -q "JsonStringEnumConverter" "$PROGRAM_CS" 2>/dev/null; then
+  HAS_GLOBAL_CONVERTER=true
+fi
+
+if [ "$HAS_GLOBAL_CONVERTER" = false ]; then
+  # No global converter — every enum in Domain/Enums must have the attribute
+  ENUM_FILES=$(find src/ -path "*/Domain/Enums/*" -name "*.cs" 2>/dev/null)
+  if [ -n "$ENUM_FILES" ]; then
+    for f in $ENUM_FILES; do
+      if grep -q "public enum" "$f" && ! grep -q "JsonStringEnumConverter" "$f"; then
+        echo "BLOCKING: Enum missing [JsonConverter(typeof(JsonStringEnumConverter))]: $f"
+        echo "  Frontend sends enum values as strings but C# deserializes as int by default"
+        echo "  Fix: Add [JsonConverter(typeof(JsonStringEnumConverter))] on the enum"
+        echo "  Or: Add JsonStringEnumConverter globally in Program.cs"
+      fi
+    done
+  fi
+fi
+```
+
+### POST-CHECK C54: No helper method calls inside .Select() on IQueryable (BLOCKING)
+
+> **Source:** Service `GetAllAsync()` used `.Select(a => MapToDto(a))` — EF Core cannot translate
+> helper method calls to SQL → runtime `InvalidOperationException` or `NullReferenceException`
+> (because `.Include()` is ignored when `.Select()` is present, and the helper expects loaded navigations).
+
+```bash
+SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Service.cs" 2>/dev/null)
+if [ -n "$SERVICE_FILES" ]; then
+  # Look for .Select(x => MethodName(x)) or .Select(MethodName) patterns on IQueryable
+  BAD_SELECT=$(grep -Pn '\.Select\(\s*\w+\s*=>\s*(?!new\s)[A-Z]\w+\(|\.Select\(\s*(?!x\s*=>)[A-Z]\w+\s*\)' $SERVICE_FILES 2>/dev/null)
+  if [ -n "$BAD_SELECT" ]; then
+    echo "BLOCKING: Helper method call inside .Select() on IQueryable — EF Core cannot translate to SQL"
+    echo "$BAD_SELECT"
+    echo "Fix: Use inline DTO construction: .Select(x => new ResponseDto(x.Id, x.Name, x.FK.Code))"
+    echo "  Helper methods (MapToDto, ToDto) are only safe AFTER materialization (ToListAsync, FirstAsync)"
+    exit 1
+  fi
+fi
+```
+
 ---
 
 ## Architecture — Clean Architecture Layer Isolation

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

@@ -72,6 +72,21 @@ public enum EntityScope
 }
 ```
 
+### Enum Serialization (MANDATORY)
+
+All enum types used in DTOs MUST serialize as strings for frontend compatibility.
+
+**Option A — Per-enum attribute (preferred when few enums):**
+```csharp
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum EmployeeStatus { Active, OnLeave, Terminated }
+```
+
+**Option B — Global configuration (if project has many enums):**
+Verify in `Program.cs`: `JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter())`
+
+> **Rule:** Before creating enums, check if global `JsonStringEnumConverter` exists. If yes, no per-enum attribute needed. If no, add `[JsonConverter(typeof(JsonStringEnumConverter))]` on every enum used in API responses.
+
 ---
 
 ## Entity Pattern (tenant-scoped, most common)
@@ -473,6 +488,93 @@ public class {Name}Service : I{Name}Service
 }
 ```
 
+### Service Pattern — Entity with FK to another business entity
+
+When an entity has a FK to another business entity (e.g., `Absence.EmployeeId → Employee`), use navigation properties **directly inside `.Select()`**. EF Core translates navigation access to SQL JOINs automatically — `.Include()` is NOT needed when using `.Select()`.
+
+```csharp
+// Example: Absence has FK EmployeeId → Employee
+public async Task<PaginatedResult<AbsenceResponseDto>> GetAllAsync(
+    string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
+{
+    var tenantId = _currentTenant.TenantId
+        ?? throw new TenantContextRequiredException();
+
+    var query = _db.Absences
+        .Where(x => x.TenantId == tenantId)
+        .AsNoTracking();
+
+    if (!string.IsNullOrWhiteSpace(search))
+    {
+        query = query.Where(x =>
+            x.Employee.Code.Contains(search) ||       // Navigate FK in Where — EF translates to JOIN
+            x.Employee.User!.LastName.Contains(search));
+    }
+
+    // CORRECT: Inline construction — access FK navigation directly in Select()
+    // EF Core generates the JOIN automatically. Do NOT use .Include() here.
+    return await query
+        .OrderByDescending(x => x.StartDate)
+        .Select(x => new AbsenceResponseDto(
+            x.Id, x.StartDate, x.EndDate, x.Type,
+            x.EmployeeId, x.Employee.Code,
+            x.Employee.User!.FirstName, x.Employee.User!.LastName))
+        .ToPaginatedResultAsync(page, pageSize, ct);
+}
+
+// GetByIdAsync — same inline Select pattern
+public async Task<AbsenceResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
+{
+    var tenantId = _currentTenant.TenantId
+        ?? throw new TenantContextRequiredException();
+
+    return await _db.Absences
+        .Where(x => x.Id == id && x.TenantId == tenantId)
+        .AsNoTracking()
+        .Select(x => new AbsenceResponseDto(
+            x.Id, x.StartDate, x.EndDate, x.Type,
+            x.EmployeeId, x.Employee.Code,
+            x.Employee.User!.FirstName, x.Employee.User!.LastName))
+        .FirstOrDefaultAsync(ct);
+}
+
+// CreateAsync — use .Include() AFTER materialization (need full entity for response)
+public async Task<AbsenceResponseDto> CreateAsync(CreateAbsenceDto dto, CancellationToken ct)
+{
+    var tenantId = _currentTenant.TenantId
+        ?? throw new TenantContextRequiredException();
+
+    // Verify FK target exists in same tenant
+    var employeeExists = await _db.Employees
+        .AnyAsync(e => e.Id == dto.EmployeeId && e.TenantId == tenantId, ct);
+    if (!employeeExists)
+        throw new KeyNotFoundException($"Employee {dto.EmployeeId} not found");
+
+    var entity = Absence.Create(tenantId, dto.EmployeeId, dto.StartDate, dto.EndDate, dto.Type);
+    entity.CreatedBy = _currentUser.UserId?.ToString();
+
+    _db.Absences.Add(entity);
+    await _db.SaveChangesAsync(ct);
+
+    // Reload with FK navigation for response
+    var created = await _db.Absences
+        .Include(x => x.Employee).ThenInclude(e => e.User)
+        .FirstAsync(x => x.Id == entity.Id, ct);
+
+    return new AbsenceResponseDto(
+        created.Id, created.StartDate, created.EndDate, created.Type,
+        created.EmployeeId, created.Employee.Code,
+        created.Employee.User!.FirstName, created.Employee.User!.LastName);
+}
+```
+
+> **Rules for FK inter-entity services:**
+> - **GetAllAsync / GetByIdAsync:** Use `.Select()` with inline navigation access (e.g., `x.Employee.Code`). Do NOT use `.Include()` — it is ignored when `.Select()` is present. EF Core generates the JOIN from the navigation path.
+> - **CreateAsync / UpdateAsync:** Use `.Include()` AFTER `SaveChangesAsync()` to reload the entity with its FK navigation for the response DTO.
+> - **FK validation:** Always verify the FK target exists in the same tenant before creating/updating.
+> - **Navigation depth:** Limit to 1-2 levels (e.g., `x.Employee.User.LastName`). Deeper navigation generates complex JOINs — consider denormalization if needed.
+> - **Search:** Include FK display fields in the search filter (e.g., `x.Employee.Code.Contains(search)`).
+
 **Key interfaces (from SmartStack NuGet package):**
 - `ICurrentUserService` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `UserId` (Guid?), `Email` (string?), `IsAuthenticated` (bool)
 - `ICurrentTenantService` (from `SmartStack.Application.Common.Interfaces.Tenants`): provides `TenantId` (Guid?), `HasTenant` (bool), `TenantSlug` (string?)
@@ -933,6 +1035,15 @@ public async Task<PaginatedResult<{Name}ResponseDto>> GetAllAsync(
 }
 ```
 
+> **WARNING — IQueryable .Select() constraints:**
+> Inside `.Select()` on an `IQueryable` (before `ToListAsync`/`FirstAsync`), use ONLY inline DTO construction:
+> `.Select(x => new ResponseDto(x.Id, x.Code, x.Name))`
+>
+> NEVER call a helper method (e.g., `MapToDto(x)`) inside `.Select()` — EF Core cannot translate method calls to SQL → runtime `InvalidOperationException`.
+> Helper methods are fine AFTER materialization (`ToListAsync`, `FirstAsync`, `SaveChangesAsync`).
+>
+> **FK navigation in `.Select()` is safe:** `.Select(x => new Dto(x.Id, x.Employee.Code, x.Employee.User!.LastName))` — EF Core translates navigation property access to SQL JOINs. `.Include()` is NOT needed and is ignored when `.Select()` is used.
+
 ### Frontend Types (`@/types/pagination.ts`)
 
 ```typescript

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

@@ -591,4 +591,26 @@ if [ -n "$PAGE_FILES" ]; then
 fi
 ```
 
-> **ALL 5 gates MUST pass before frontend commit.** When delegating to `/ui-components` skill, include explicit instructions: CSS variables only, forms as full pages, i18n with namespace + fallback.
+### Gate 6: SmartStack Components (no raw HTML tables)
+
+```bash
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null | grep -v "\.test\." | grep -v node_modules)
+if [ -n "$PAGE_FILES" ]; then
+  FAIL=false
+  RAW_TABLE=$(grep -Pn '<table[> ]|<tr[> ]|<td[> ]|<th[> ]' $PAGE_FILES 2>/dev/null)
+  if [ -n "$RAW_TABLE" ]; then
+    echo "BLOCKING: Raw HTML <table>/<tr>/<td> found — pages MUST use DataTable component (invoke /ui-components)"
+    echo "$RAW_TABLE"
+    FAIL=true
+  fi
+  RAW_CSS=$(grep -Pn 'style=\{?\{|style="[^"]*"' $PAGE_FILES 2>/dev/null | grep -v "className")
+  if [ -n "$RAW_CSS" ]; then
+    echo "BLOCKING: Inline CSS style= found — pages MUST use Tailwind + CSS variables (invoke /ui-components)"
+    echo "$RAW_CSS"
+    FAIL=true
+  fi
+  if [ "$FAIL" = false ]; then echo "PASS: SmartStack components (no raw HTML)"; fi
+fi
+```
+
+> **ALL 6 gates MUST pass before frontend commit.** When delegating to `/ui-components` skill, include explicit instructions: CSS variables only, forms as full pages, i18n with namespace + fallback.

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

@@ -274,7 +274,7 @@ export function EntityListPage() {
       setLoading(true);
       setError(null);
       const result = await entityApi.getAll();
-      setData(result.items);
+      setData(result?.items ?? []);
     } catch (err: any) {
       setError(err.message || t('{module}:errors.loadFailed', 'Failed to load data'));
     } finally {
@@ -364,6 +364,11 @@ export function EntityListPage() {
 }
 ```
 
+> **DEFENSIVE RULE — API Response Guards:**
+> Always use `result?.items ?? []` when extracting arrays from API responses.
+> SmartStack's axios interceptor may resolve with `undefined` on auth failures (401/403)
+> instead of rejecting the promise. Without the guard, `data.length` will crash.
+
 ### Detail Page Pattern
 
 ```tsx
@@ -875,9 +880,27 @@ When generating form fields, determine the field type from the entity property:
 | `Guid` (FK — e.g., `EmployeeId`, `DepartmentId`) | **Entity Lookup** | `<EntityLookup />` |
 | `bool` | Toggle/Checkbox | `<input type="checkbox" />` |
 | `int` / `decimal` | Number input | `<input type="number" />` |
-| `DateTime` | Date picker | `<input type="date" />` |
+| `DateTime` / `DateOnly` | Date input | `<input type="date" className="..." />` — wrap with label + error state using CSS variables |
 | `enum` | Select dropdown | `<select>` |
 
+#### Date Field Pattern (styled with CSS variables)
+
+```tsx
+{/* Date field — styled with CSS variables */}
+<div>
+  <label className="block text-sm font-medium text-[var(--text-primary)] mb-1">
+    {t('{module}:form.startDate', 'Start Date')}
+  </label>
+  <input
+    type="date"
+    value={formData.startDate}
+    onChange={(e) => handleChange('startDate', e.target.value)}
+    required
+    className="w-full px-3 py-2 rounded-[var(--radius-input)] border border-[var(--border-color)] bg-[var(--bg-tertiary)] text-[var(--text-primary)] focus:outline-none focus:ring-2 focus:ring-[var(--color-accent-500)]"
+  />
+</div>
+```
+
 **How to detect FK fields:** Any property named `{Entity}Id` of type `Guid` that has a corresponding navigation property is a foreign key. Examples: `EmployeeId`, `DepartmentId`, `CategoryId`, `ParentId`.
 
 ### EntityLookup Component Pattern

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

@@ -59,6 +59,7 @@ Web            → Application (via API clients)
 - No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
 - Domain events for state changes
 - Value objects for composite values
+- **Enum serialization:** All enums in DTOs must serialize as strings. Check if `JsonStringEnumConverter` is configured globally. If not, add `[JsonConverter(typeof(JsonStringEnumConverter))]` on each enum. Frontend sends/receives strings (e.g., `"Active"`, not `0`).
 - **Person Extension Pattern:** If entity has `personRoleConfig` (from PRD or feature.json):
   - Load `references/person-extension-pattern.md` for full patterns
   - Mandatory variant (`userLinkMode: 'mandatory'`): `Guid UserId` (non-nullable), ZERO person fields (`FirstName`, `LastName`, `Email`), unique index `(TenantId, UserId)`

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

@@ -64,6 +64,7 @@ BEFORE starting Layer N:
          - {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 GetSectionEntries
+         - {code_patterns}: Read state.json code_patterns field, OR re-derive from existing ICodeGenerator registrations in DependencyInjection.cs, OR default to "manual" for all entities
     3. IF Layer N-1 was already completed (check state.json or git log):
        → Skip to Layer N directly
 
@@ -89,6 +90,36 @@ For each entity to create/modify:
   → Verify entity matches patterns in references/smartstack-api.md
 ```
 
+### Code Generation Integration
+
+```
+For each entity with auto-generated code ({code_patterns} from step-00):
+  IF {code_patterns} has entry for this entity AND strategy != "manual":
+    → Pass codePattern in scaffold_extension options:
+      MCP scaffold_extension (type: "entity", target: entity_name, options: {
+        codePattern: {
+          strategy: {code_patterns[entity].strategy},
+          prefix: {code_patterns[entity].prefix},
+          digits: {code_patterns[entity].digits},
+          includeTenantSlug: {code_patterns[entity].includeTenantSlug},
+          separator: {code_patterns[entity].separator}
+        }
+      })
+    → Verify: Code property exists on entity but is NOT in CreateDto
+    → Verify: ICodeGenerator<{Entity}> is ready for DI registration (Layer 2)
+  ELSE:
+    → Default behavior (strategy: "manual", Code in CreateDto)
+```
+
+### Enum Serialization Check
+
+```
+For each enum type created in Domain/Enums/:
+  1. Grep("JsonStringEnumConverter", "src/**/Program.cs")
+  2. IF global config exists → no action
+  3. IF no global config → add [JsonConverter(typeof(JsonStringEnumConverter))] on each enum
+```
+
 ### Person Extension Detection
 
 **If entity has personRoleConfig (mandatory or optional UserId link):**
@@ -247,6 +278,30 @@ TaskUpdate(taskId: progress_tracker_id,
 - Services/DTOs: MCP scaffold_extension
 - Controllers: use /controller skill for complex, MCP scaffold_extension for simple
 - Important: All GetAll endpoints must support `?search=` query parameter (enables EntityLookup on frontend)
+- Guard: DTO mapping in services MUST use inline construction (`new ResponseDto(...)`) inside IQueryable `.Select()`. Never use helper methods (MapToDto, ToDto) inside `.Select()` — EF Core cannot translate them. Helper methods are allowed only after materialization (ToListAsync, FirstAsync).
+
+### Code Generation Service Registration (per entity)
+
+```
+For each entity where {code_patterns} defines strategy != "manual":
+  1. Verify DI registration in DependencyInjection.cs:
+     → services.AddScoped<ICodeGenerator<{Entity}>>(sp => new CodeGenerator<{Entity}>(...))
+     → Use CodePatternConfig matching {code_patterns[entity]} values
+     → See references/code-generation.md "DI Registration Pattern"
+     → Guard: Do NOT duplicate if ICodeGenerator<{Entity}> is already registered
+  2. Verify service injection:
+     → {Entity}Service constructor receives ICodeGenerator<{Entity}>
+     → CreateAsync uses _codeGenerator.NextCodeAsync(ct) instead of dto.Code
+     → See references/code-generation.md "Service Integration Pattern"
+  3. Verify CreateDto:
+     → Code property MUST NOT be in Create{Entity}Dto
+     → Code property MUST be in {Entity}ResponseDto
+     → See references/code-generation.md "CreateDto Changes"
+  4. Verify Validator:
+     → Create{Entity}Validator has NO Code rule (auto-generated)
+     → Update{Entity}Validator has Code rule with regex ^[a-z0-9_-]+$ (if Code is mutable)
+```
+- FK inter-entity pattern: When an entity has FK to another business entity (e.g., Absence → Employee), use navigation properties directly inside `.Select()` (e.g., `x.Employee.Code`, `x.Employee.User!.LastName`). EF Core translates navigation access to SQL JOINs automatically. Do NOT use `.Include()` with `.Select()` — it is ignored. See `references/smartstack-api.md` "Service Pattern — Entity with FK to another business entity" for the full pattern.
 
 ### Skill Delegation
 
@@ -272,6 +327,13 @@ IF NOT economy_mode AND entities.length > 1:
         - Controller: /controller skill or MCP scaffold_extension
         - IMPORTANT: GetAll endpoint MUST support ?search= parameter
         - Validators: FluentValidation + DI registration
+        - CODE GENERATION: {code_patterns[EntityName] summary — e.g., "strategy: sequential, prefix: emp, digits: 5" or "manual"}
+          If strategy != "manual": read references/code-generation.md, then:
+          → Register ICodeGenerator<{EntityName}> in DI (DependencyInjection.cs) with CodePatternConfig matching {code_patterns}
+          → Inject ICodeGenerator<{EntityName}> in {EntityName}Service, use _codeGenerator.NextCodeAsync(ct) in CreateAsync
+          → Remove Code from Create{EntityName}Dto (auto-generated, not user-provided)
+          → Keep Code in {EntityName}ResponseDto
+          → Create{EntityName}Validator: NO Code rule. Update{EntityName}Validator: Code rule with regex ^[a-z0-9_-]+$
         - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
         - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
   # All agents launched in parallel
@@ -392,11 +454,59 @@ test({module}): backend unit and integration tests
 
 ## Layer 3 — Frontend (Pages + I18n + Documentation)
 
+### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)
+
+> **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
+> a prior Skill("ui-components") call in this execution, the frontend layer is INVALID.
+>
+> **You MUST NOT:**
+> - Generate .tsx page code in Agent prompts and dispatch to Snipper agents
+> - Write page content directly via the Write tool
+> - Copy-paste page templates from your knowledge
+>
+> **You MUST:**
+> - Call Skill("ui-components") which loads the style guide, responsive guidelines,
+>   accessibility rules, and pattern files (entity-card, data-table, dashboard-chart, grid-layout, kanban)
+> - Let /ui-components generate all pages with correct conventions
+>
+> **Why this matters:** Without the skill, pages miss CSS variables, DataTable/EntityCard,
+> memo()/useCallback, responsive mobile-first design, and accessibility patterns.
+>
+> **Agent boundary rule:** Snipper sub-agents DO NOT have access to the Skill tool.
+> Therefore, .tsx page generation MUST NEVER be delegated to Snipper agents.
+> Pages are ALWAYS generated by the principal agent via Skill("ui-components").
+> Snipper agents handle: API clients, routes, wiring, i18n, tests — NOT pages.
+
 ### Load Frontend References (deferred from top of step)
 
 - Read `references/smartstack-frontend.md` now — lazy loading, i18n, page structure, CSS variables, EntityLookup (sections 1-6)
 - Read `references/smartstack-frontend-compliance.md` now — documentation, form testing, compliance gates (sections 7-9)
 
+### Pre-flight: Shared component existence check
+
+Before generating any page, verify shared components exist:
+
+```
+Glob("src/components/ui/DataTable.*")
+Glob("src/components/ui/EntityCard.*")
+Glob("src/components/ui/PageLoader.*")
+Glob("src/components/ui/EntityLookup.*")
+```
+
+If ANY shared component is MISSING:
+  → Log warning: "Shared component {Component} not found — will be generated locally"
+  → When invoking Skill("ui-components"), add instruction:
+    "MISSING SHARED COMPONENTS: {list}. Generate these locally in src/components/ui/"
+
+**EntityLookup special handling (FK fields):**
+If ANY entity has FK Guid fields (e.g., EmployeeId, DepartmentId) AND EntityLookup is missing:
+  → Generate EntityLookup FIRST, BEFORE any Create/Edit pages
+  → Use the EXACT implementation from `references/smartstack-frontend.md` section 6 (EntityLookup Component Pattern)
+  → Critical: response parsing MUST use `(res.data.items || res.data).map(mapOption)` to handle both paginated and array responses
+  → Do NOT improvise — copy the reference implementation verbatim
+  → Do NOT write a simplified version with `result.data` or `Array.isArray(result.data)` — the reference handles both `PaginatedResult<T>` (`.items`) and raw array responses
+  → Verify after generation: the component MUST contain the expression `(res.data.items || res.data).map(mapOption)` — if it does not, replace with the reference version
+
 ### Task Progress
 TaskUpdate(taskId: layer3_task_id, status: "in_progress")
 TaskUpdate(taskId: progress_tracker_id,
@@ -519,9 +629,12 @@ This generates:
 
 ```
 IF NOT economy_mode AND entities.length > 1:
+  # PHASE A — Parallel: infrastructure frontend (NO page generation)
+  # Snipper agents DO NOT have access to the Skill tool, so they CANNOT call /ui-components.
+  # Pages MUST be generated by the principal agent in Phase B.
   For each entity, launch in parallel (single message):
     Agent(subagent_type='Snipper', model='opus',
-      prompt='Execute Layer 3 frontend for {EntityName}:
+      prompt='Execute Layer 3 INFRASTRUCTURE for {EntityName}:
         **MANDATORY: Read references/smartstack-frontend.md FIRST**
         - API client: MCP scaffold_api_client
         - Routes: MCP scaffold_routes (outputFormat: "applicationRoutes", dryRun: false) → MUST generate navRoutes.generated.ts
@@ -529,15 +642,23 @@ IF NOT economy_mode AND entities.length > 1:
           → CRITICAL: Route paths MUST include module segment: {module_kebab}/{section_kebab} (e.g., employee-management/employees, NOT just employees)
           → See references/frontend-route-wiring-app-tsx.md for full patterns
           → Verify: mcp__smartstack__validate_frontend_routes (scope: "routes")
-        - Pages: /ui-components skill (ALL 4 types: List, Detail, Create, Edit)
         - I18n: 4 JSON files (fr, en, it, de) + REGISTER namespace in i18n config
-        - FORM PAGES: Full pages with own routes (no modals)
-        - FK FIELDS: EntityLookup for all FK Guid fields
-        - TABS: Local state only (NEVER navigate())
-        - FORM TESTS: Co-located .test.tsx for Create and Edit pages
+        - DO NOT generate any .tsx page files — pages are handled by the principal agent
         - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
         - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
-  # All agents launched in parallel
+  # Wait for all agents to complete
+
+  # PHASE B — Sequential: pages via /ui-components (principal agent)
+  # Snipper agents cannot call Skill() — only the principal agent can.
+  For each entity (sequentially):
+    **INVOKE Skill("ui-components")** — pass entity context:
+      - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
+      - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)
+      - "CSS: Use CSS variables ONLY — bg-[var(--bg-card)], text-[var(--text-primary)]"
+      - "Forms: Create/Edit are FULL PAGES with own routes (/create, /:id/edit)"
+      - "FK FIELDS: EntityLookup for ALL FK Guid fields"
+      - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+    Generate form tests: co-located .test.tsx for Create and Edit pages
 
 ELSE:
   # Economy mode: Agent principal handles all entities SEQUENTIALLY.
@@ -570,38 +691,21 @@ When launching agents for multi-entity layers:
 
 ### Frontend Compliance Gate
 
-> See `references/smartstack-frontend.md` section 9 "Compliance Gates" for all 5 required checks:
+> See `references/smartstack-frontend-compliance.md` section 9 "Compliance Gates" for all 6 required checks:
 > 1. CSS Variables (theme system)
 > 2. Forms as Pages (zero modals/drawers/slide-overs)
 > 3. I18n File Structure (4 languages, separate JSON files)
 > 4. Lazy Loading (React.lazy() — no static imports)
 > 5. useTranslation in Pages (all text translated)
+> 6. SmartStack Components (no raw HTML tables — DataTable/EntityCard required)
 
-Do not commit frontend changes until all 5 gates pass.
+Do not commit frontend changes until all 6 gates pass.
 
 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/`."
 
-### HARD RULE — /ui-components is NON-NEGOTIABLE
-
-> **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
-> a prior Skill("ui-components") call in this execution, the frontend layer is INVALID.
->
-> **You MUST NOT:**
-> - Generate .tsx page code in Agent prompts and dispatch to Snipper agents
-> - Write page content directly via the Write tool
-> - Copy-paste page templates from your knowledge
->
-> **You MUST:**
-> - Call Skill("ui-components") which loads the style guide, responsive guidelines,
->   accessibility rules, and pattern files (entity-card, data-table, dashboard-chart, grid-layout, kanban)
-> - Let /ui-components generate all pages with correct conventions
->
-> **Why this matters:** Without the skill, pages miss CSS variables, DataTable/EntityCard,
-> memo()/useCallback, responsive mobile-first design, and accessibility patterns.
-
 ### Frontend Tests Inline
 
 > **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**

package/templates/skills/application/templates-frontend.md

@@ -157,7 +157,7 @@ export function $MODULE_PASCALListView({
         ...(search && { search }),
       });
       const result = await api.get<PaginatedResult>(`/api/$module?${params}`);
-      setData(result);
+      setData(result ?? null);
     } catch (err) {
       setError(t('common:errors.loadFailed'));
       console.error('Failed to load $module:', err);

package/templates/skills/ba-generate-html/SKILL.md

@@ -42,7 +42,7 @@ Generate the interactive HTML document of the business analysis from the JSON an
 
 - **NEVER** deploy an empty template — FEATURE_DATA must be injected
 - **moduleSpecs** MUST have ONE entry per module (empty = BROKEN)
-- **Scope keys** MUST be converted: `mustHave` → `vital`, `shouldHave` → `important`, `couldHave` → `optional`, `outOfScope` → `excluded`
+- **Scope keys** MUST be converted: `inScope` → `inscope`, `outOfScope` → `outofscope`
 - **Wireframe fields** MUST be renamed: `mockupFormat` → `format`, `mockup` → `content`
 - **Final file** MUST be > 100KB