@atlashub/smartstack-cli 3.34.0 → 3.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
@@ -21,7 +21,6 @@
     "dist",
     "templates",
     "config",
-    "scripts",
     ".documentation"
   ],
   "engines": {

package/templates/mcp-scaffolding/controller.cs.hbs

@@ -6,6 +6,9 @@ using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using SmartStack.Api.Authorization;
+{{#if navRoute}}
+using SmartStack.Api.Routing;
+{{/if}}
 using SmartStack.Application.Common.Models;
 
 namespace {{namespace}}.Controllers;
@@ -14,9 +17,10 @@ namespace {{namespace}}.Controllers;
 /// API controller for {{name}} operations
 /// </summary>
 [ApiController]
-[Route("api/[controller]")]
 {{#if navRoute}}
 [NavRoute("{{navRoute}}")]
+{{else}}
+[Route("api/[controller]")]
 {{/if}}
 [Authorize]
 [Produces("application/json")]

package/templates/skills/apex/SKILL.md

@@ -86,7 +86,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
 | 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
 | 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
-| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 21 POST-CHECKs, acceptance criteria |
+| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 50 POST-CHECKs, acceptance criteria |
 | 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
 | 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
 | 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP |
@@ -98,11 +98,11 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Phase | Step | Obligatory | Description |
 |-------|------|------------|-------------|
-| *Init* | 00 | Yes | Setup, hierarchy, challenge the need (skipped in `-d` delegate mode) |
+| *Init* | 00 | Yes | Setup, hierarchy, challenge the need, **scope guard** (skipped in `-d` delegate mode) |
 | **A** — Analyze | 01 | Yes | Explore existing code |
 | **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
 | **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
-| **X** — eXamine | 04 | Yes | 30 POST-CHECKs, MCP validation, build, acceptance criteria |
+| **X** — eXamine | 04 | Yes | 50 POST-CHECKs, MCP validation, build, acceptance criteria |
 | *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
 | *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
 | *Tests* | 07-08 | **Yes** | Scaffold and run tests |

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

@@ -1251,4 +1251,229 @@ if [ -n "$DETAIL_PAGES" ]; then
 fi
 ```
 
+### POST-CHECK 44: Migration ModelSnapshot must contain ALL entities registered in DbContext (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): 7 entities registered in DbContext but migration only covered 3.
+# Happens when migration is created ONCE in Layer 0 for the first batch, then additional entities
+# are added in subsequent iterations without re-running migration.
+SNAPSHOT=$(find src/ -name "*ModelSnapshot.cs" -path "*/Migrations/*" 2>/dev/null | head -1)
+DBCONTEXT=$(find src/ -name "*DbContext.cs" -path "*/Persistence/*" ! -name "*DesignTime*" 2>/dev/null | head -1)
+if [ -n "$SNAPSHOT" ] && [ -n "$DBCONTEXT" ]; then
+  # Extract DbSet entity names from DbContext (DbSet<EntityName>)
+  DBSET_ENTITIES=$(grep -oP 'DbSet<(\w+)>' "$DBCONTEXT" 2>/dev/null | grep -oP '<\K\w+(?=>)' | sort -u)
+  FAIL=false
+  for ENTITY in $DBSET_ENTITIES; do
+    # Skip base SmartStack entities (handled by core migrations)
+    if echo "$ENTITY" | grep -qP '^(Navigation|Tenant|User|Role|Permission|AuditLog|ApplicationTracking)'; then
+      continue
+    fi
+    # Check if the entity appears in ModelSnapshot (builder.Entity<EntityName>)
+    if ! grep -q "Entity<$ENTITY>" "$SNAPSHOT" 2>/dev/null; then
+      echo "BLOCKING: Entity '$ENTITY' is registered as DbSet in $DBCONTEXT but MISSING from ModelSnapshot"
+      echo "  This means no migration was created for this entity — it will not exist in the database."
+      echo "  Fix: Run 'dotnet ef migrations add' to include all new entities"
+      FAIL=true
+    fi
+  done
+  if [ "$FAIL" = true ]; then
+    echo ""
+    echo "  Root cause: Migration was likely created once for the first batch of entities,"
+    echo "  but additional entities were added later without regenerating the migration."
+    echo "  Fix: Create a new migration that covers ALL missing entities."
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 45: I18n namespace files must be registered in i18n config (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): i18n JSON files existed in src/i18n/locales/ but were never
+# registered in the i18n config (config.ts or index.ts). Pages calling useTranslation(['module'])
+# got empty translations at runtime.
+I18N_CONFIG=$(find src/ web/ -path "*/i18n/config.ts" -o -path "*/i18n/index.ts" -o -path "*/i18n/i18n.ts" 2>/dev/null | grep -v node_modules | head -1)
+if [ -n "$I18N_CONFIG" ]; then
+  # Find all module JSON files in the primary language (fr)
+  FR_FILES=$(find src/ web/ -path "*/i18n/locales/fr/*.json" 2>/dev/null | grep -v node_modules | grep -v common.json | grep -v navigation.json)
+  if [ -n "$FR_FILES" ]; then
+    FAIL=false
+    for JSON_FILE in $FR_FILES; do
+      NS=$(basename "$JSON_FILE" .json)
+      # Check if namespace is referenced in config (import or resource key)
+      if ! grep -q "$NS" "$I18N_CONFIG" 2>/dev/null; then
+        echo "BLOCKING: i18n namespace '$NS' (from $JSON_FILE) is not registered in $I18N_CONFIG"
+        echo "  Pages using useTranslation(['$NS']) will get empty translations at runtime"
+        echo "  Fix: Add '$NS' to the resources/ns configuration in $I18N_CONFIG"
+        FAIL=true
+      fi
+    done
+    if [ "$FAIL" = true ]; then
+      exit 1
+    fi
+  fi
+fi
+```
+
+### POST-CHECK 46: FluentValidation validators must be registered via DI (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): Validators existed but were never registered in DI.
+# Without DI registration, [FromBody] DTOs are never validated — any data is accepted.
+VALIDATOR_FILES=$(find src/ -name "*Validator.cs" -path "*/Validators/*" 2>/dev/null | grep -v test | grep -v Test)
+if [ -n "$VALIDATOR_FILES" ]; then
+  # Check DI registration file exists
+  DI_FILE=$(find src/ -name "DependencyInjection.cs" -o -name "ServiceCollectionExtensions.cs" 2>/dev/null | grep -v test | head -1)
+  if [ -z "$DI_FILE" ]; then
+    echo "BLOCKING: Validators exist but no DependencyInjection.cs found for DI registration"
+    exit 1
+  fi
+  # Check for AddValidatorsFromAssembly or individual validator registration
+  HAS_ASSEMBLY_REG=$(grep -c "AddValidatorsFromAssembly\|AddValidatorsFromAssemblyContaining" "$DI_FILE" 2>/dev/null)
+  if [ "$HAS_ASSEMBLY_REG" -eq 0 ]; then
+    # Check individual registrations as fallback
+    VALIDATOR_COUNT=$(echo "$VALIDATOR_FILES" | wc -l)
+    REGISTERED_COUNT=0
+    for VF in $VALIDATOR_FILES; do
+      VN=$(basename "$VF" .cs)
+      if grep -q "$VN" "$DI_FILE" 2>/dev/null; then
+        REGISTERED_COUNT=$((REGISTERED_COUNT + 1))
+      fi
+    done
+    if [ "$REGISTERED_COUNT" -eq 0 ]; then
+      echo "BLOCKING: $VALIDATOR_COUNT validators exist but NONE are registered in DI ($DI_FILE)"
+      echo "  Fix: Add 'services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();' to $DI_FILE"
+      echo "  Or use 'services.AddValidatorsFromAssembly(typeof(Create{Entity}DtoValidator).Assembly);'"
+      exit 1
+    fi
+  fi
+fi
+```
+
+### POST-CHECK 47: Date/date properties in DTOs must use DateOnly, not string (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): WorkLog DTO had Date property typed as string instead of DateOnly.
+# This causes: invalid date parsing, no date validation, inconsistent formats across clients.
+DTO_FILES=$(find src/ -name "*Dto.cs" -path "*/DTOs/*" 2>/dev/null)
+if [ -n "$DTO_FILES" ]; then
+  FAIL=false
+  for f in $DTO_FILES; do
+    # Find string properties whose name contains "Date" (case-insensitive)
+    BAD_DATES=$(grep -Pn 'string\??\s+\w*[Dd]ate\w*\s*[{;,]' "$f" 2>/dev/null | grep -vi "Updated\|Created\|format\|pattern\|string\|parse")
+    if [ -n "$BAD_DATES" ]; then
+      echo "BLOCKING: DTO has string type for date field — must use DateOnly: $f"
+      echo "$BAD_DATES"
+      echo "  Fix: Change 'string Date' to 'DateOnly Date' (or 'DateOnly? Date' if nullable)"
+      echo "  DateOnly is the correct .NET type for date-only values (no time component)"
+      FAIL=true
+    fi
+  done
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 48: NavRoute attribute values must use kebab-case (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): Controllers had [NavRoute("business.humanresources.employees")]
+# instead of [NavRoute("business.human-resources.employees")]. This causes route mismatch with
+# seed data and permission codes, resulting in 404s at runtime.
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  FAIL=false
+  for f in $CTRL_FILES; do
+    NAVROUTE_VALS=$(grep -oP 'NavRoute\("([^"]+)"' "$f" 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"')
+    for NR in $NAVROUTE_VALS; do
+      # Check each segment for concatenated multi-word without hyphens
+      SEGMENTS=$(echo "$NR" | tr '.' '\n')
+      for SEG in $SEGMENTS; do
+        # Detect segments that look like concatenated words (lowercase, 8+ chars, no hyphens)
+        # Use a simpler heuristic: lowercase-only segment with known multi-word patterns
+        if echo "$SEG" | grep -qP '^[a-z]{8,}$'; then
+          # Additional check: does it contain a known multi-word pattern?
+          if echo "$SEG" | grep -qP '(human|project|leave|client|support|email|time|work|resource)'; then
+            echo "BLOCKING: NavRoute segment '$SEG' in $f appears to be concatenated multi-word without hyphens"
+            echo "  Full NavRoute: $NR"
+            echo "  Fix: Use kebab-case: e.g., 'humanresources' → 'human-resources', 'projectmanagement' → 'project-management'"
+            FAIL=true
+          fi
+        fi
+      done
+    done
+  done
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 49: Every module with entities must have a migration covering them (BLOCKING)
+
+```bash
+# Complementary to POST-CHECK 44 — checks from the entity side.
+# Finds entity .cs files in Domain/ and verifies they appear in at least one migration file.
+ENTITY_FILES=$(find src/ -path "*/Domain/Entities/*" -name "*.cs" 2>/dev/null | grep -v test)
+MIGRATION_DIR=$(find src/ -path "*/Migrations" -type d 2>/dev/null | head -1)
+if [ -n "$ENTITY_FILES" ] && [ -n "$MIGRATION_DIR" ]; then
+  MIGRATION_FILES=$(find "$MIGRATION_DIR" -name "*.cs" ! -name "*ModelSnapshot*" ! -name "*DesignTime*" 2>/dev/null)
+  if [ -z "$MIGRATION_FILES" ]; then
+    echo "BLOCKING: Entity files exist in Domain/Entities but NO migration files found in $MIGRATION_DIR"
+    exit 1
+  fi
+  FAIL=false
+  for EF in $ENTITY_FILES; do
+    ENTITY_NAME=$(basename "$EF" .cs)
+    # Skip abstract base classes and interfaces
+    if grep -qP '^\s*(public\s+)?(abstract|interface)\s' "$EF" 2>/dev/null; then continue; fi
+    # Check if entity appears in any migration (CreateTable or AddColumn or entity reference)
+    FOUND=$(grep -l "$ENTITY_NAME" $MIGRATION_FILES 2>/dev/null)
+    if [ -z "$FOUND" ]; then
+      echo "BLOCKING: Entity '$ENTITY_NAME' ($EF) not found in any migration file"
+      echo "  This entity will NOT have a database table."
+      echo "  Fix: Run 'dotnet ef migrations add' to create a migration covering this entity"
+      FAIL=true
+    fi
+  done
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 50: Controllers must NOT have both [Route] and [NavRoute] attributes (BLOCKING)
+
+```bash
+# Root cause (test-apex-007): All 7 controllers had BOTH [Route("api/...")] and [NavRoute("...")].
+# In SmartStack, [NavRoute] resolves routes dynamically from Navigation entities at startup.
+# [Route] is standard ASP.NET Core static routing. When both exist:
+# - NavRoute middleware tries to resolve from DB → fails if seed data not applied → no route
+# - [Route] may or may not take over depending on middleware order
+# - Result: 404 on ALL endpoints
+# The MCP validate_conventions previously ENCOURAGED adding [Route] with [NavRoute] — this was a bug.
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  FAIL=false
+  for f in $CTRL_FILES; do
+    HAS_NAVROUTE=$(grep -c '\[NavRoute(' "$f" 2>/dev/null)
+    HAS_ROUTE=$(grep -c '\[Route(' "$f" 2>/dev/null)
+    if [ "$HAS_NAVROUTE" -gt 0 ] && [ "$HAS_ROUTE" -gt 0 ]; then
+      NAVROUTE_VAL=$(grep -oP 'NavRoute\("([^"]+)"' "$f" 2>/dev/null | head -1)
+      ROUTE_VAL=$(grep -oP 'Route\("([^"]+)"' "$f" 2>/dev/null | head -1)
+      echo "BLOCKING: Controller has BOTH [Route] and [NavRoute] — remove [Route]: $f"
+      echo "  Found: [$ROUTE_VAL] + [$NAVROUTE_VAL]"
+      echo "  In SmartStack, [NavRoute] resolves routes dynamically from the database."
+      echo "  Having [Route] alongside it causes route conflicts and 404s."
+      echo "  Fix: Remove the [Route(...)] attribute, keep only [NavRoute(...)]"
+      FAIL=true
+    fi
+  done
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
 **If ANY POST-CHECK fails → fix in step-03, re-validate.**

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

@@ -491,6 +491,12 @@ public class {Name}Controller : ControllerBase
 }
 ```
 
+**CRITICAL — Route attribute rules:**
+- `[NavRoute]` is the ONLY route attribute needed — it resolves routes dynamically from Navigation entities at startup
+- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes route conflicts and 404s at runtime
+- **FORBIDDEN:** `[Route("api/[controller]")]` — this is standard ASP.NET Core, NOT SmartStack
+- If a controller has `[NavRoute]`, there must be NO `[Route]` attribute on the class
+
 **CRITICAL:** Use `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint — NEVER `[Authorize]` alone (no RBAC enforcement).
 
 **CRITICAL — Permission paths use IDENTICAL segments to NavRoute codes (kebab-case):**
@@ -703,6 +709,26 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 
 ---
 
+## DTO Type Mapping (CRITICAL)
+
+> **Use the correct .NET type for each property.** Incorrect types cause runtime parsing errors.
+
+| Property Pattern | .NET Type | JSON Format | Example |
+|-----------------|-----------|-------------|---------|
+| `*Date`, `StartDate`, `EndDate`, `BirthDate` | `DateOnly` | `"2025-03-15"` | `public DateOnly Date { get; set; }` |
+| `CreatedAt`, `UpdatedAt` | `DateTime` | `"2025-03-15T10:30:00Z"` | `public DateTime CreatedAt { get; set; }` |
+| `*Time`, `StartTime` | `TimeOnly` | `"14:30:00"` | `public TimeOnly StartTime { get; set; }` |
+| Duration, hours | `decimal` | `8.5` | `public decimal HoursWorked { get; set; }` |
+| FK reference | `Guid` | `"uuid-string"` | `public Guid EmployeeId { get; set; }` |
+
+**FORBIDDEN in DTOs:**
+- `string Date` / `string StartDate` — use `DateOnly`
+- `string Time` — use `TimeOnly`
+- `DateTime BirthDate` — use `DateOnly` (no time component needed)
+- `int` for hours/duration — use `decimal` for fractional values
+
+---
+
 ## Common Mistakes to Avoid
 
 | Mistake | Reality |
@@ -713,7 +739,7 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `e.IsDeleted` filter | Does NOT exist — no soft delete |
 | `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
 | `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
-| `[Route] + [NavRoute]` | Only `[NavRoute]` needed (resolves route from DB) |
+| `[Route("api/...")] + [NavRoute]` | **FORBIDDEN** — causes 404s. Only `[NavRoute]` needed (resolves route from DB at startup). Remove ALL `[Route]` attributes when `[NavRoute]` is present. |
 | `SmartStack.Domain.Common.Interfaces` | Wrong — interfaces are in `SmartStack.Domain.Common` directly |
 | `[Authorize]` without `[RequirePermission]` | No RBAC enforcement — always use `[RequirePermission]` |
 | `tenantId: Guid.Empty` in services | OWASP A01 — always use validated `_currentTenant.TenantId` |
@@ -726,6 +752,8 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `business.humanresources.employees.read` in permissions | Permission segments MUST match NavRoute kebab-case: `business.human-resources.employees.read` |
 | `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
 | `GetAllAsync()` without search param | ALL GetAll endpoints MUST support `?search=` for EntityLookup |
+| `string Date` in DTO | Date-only fields MUST use `DateOnly`, NEVER `string` |
+| `DateTime` for date-only | Use `DateOnly` when no time component needed |
 | FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |
 | `PagedResult<T>` / `PaginatedResultDto<T>` | FORBIDDEN — use `PaginatedResult<T>` only |
 

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

@@ -187,11 +187,38 @@ t('common:actions.save', 'Save')
 t('common:errors.network', 'Network error')
 ```
 
+### Namespace Registration (CRITICAL)
+
+> **After creating i18n JSON files, you MUST register each namespace in the i18n config.**
+> Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
+
+In the i18n config file (`src/i18n/config.ts` or `src/i18n/index.ts`), add each new namespace:
+
+```typescript
+// Example: registering new module namespaces
+import employees from './locales/fr/employees.json';
+import projects from './locales/fr/projects.json';
+import clients from './locales/fr/clients.json';
+
+// In resources configuration:
+resources: {
+  fr: { employees, projects, clients, common, navigation },
+  en: { employees: employeesEn, projects: projectsEn, clients: clientsEn, ... },
+  // ... it, de
+}
+
+// OR with ns array:
+ns: ['common', 'navigation', 'employees', 'projects', 'clients'],
+```
+
+POST-CHECK 45 validates this. Unregistered namespaces → BLOCKING.
+
 ### Rules
 
 - **ALWAYS** provide a fallback value as 2nd argument to `t()`
 - **ALWAYS** use namespace prefix: `t('namespace:key')`
 - **ALWAYS** generate 4 language files (fr, en, it, de) with identical key structures
+- **ALWAYS** register new namespaces in i18n config file after creating JSON files
 - **NEVER** hardcode user-facing strings in JSX
 - **NEVER** use `t('key')` without namespace prefix
 

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

@@ -51,6 +51,11 @@
 
 **BLOCKING:** `dotnet build --no-restore` MUST pass after migration.
 
+> **CRITICAL — Migration must cover ALL entities (POST-CHECK 44, 49):**
+> Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
+> Verify with `dotnet ef migrations has-pending-model-changes` — must report NO pending changes.
+> If entities are added incrementally across modules, create a NEW migration for each batch.
+
 ---
 
 ## Layer 1 — Application (parallel with API)
@@ -75,10 +80,13 @@
 - **ALL services MUST inject `ICurrentUserService`** for audit trails
 - **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
-- FluentValidation for all commands
+- FluentValidation for all commands — **MUST register validators via DI:**
+  `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
+  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 46)
+- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 47). See `smartstack-api.md` DTO Type Mapping.
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
-- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`)
+- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
 
 ---
 
@@ -101,8 +109,16 @@
 
 **Rules:**
 - `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- **NavRoute values MUST use kebab-case for ALL multi-word segments:**
+  - `[NavRoute("business.human-resources.employees")]` (CORRECT)
+  - `[NavRoute("business.humanresources.employees")]` (WRONG — missing hyphens)
+  - `[NavRoute("business.project-management.projects")]` (CORRECT)
+  - `[NavRoute("business.projectmanagement.projects")]` (WRONG)
 - Permission paths MUST use kebab-case matching NavRoute codes (e.g., `business.human-resources.employees.read`)
 - FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
+- POST-CHECK 48 detects non-kebab-case NavRoute values. POST-CHECK 41 detects non-kebab-case permissions.
+- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 50)
+- `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
 - NEVER use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities

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

@@ -194,6 +194,79 @@ These values are propagated to:
 
 ---
 
+## 5d. Scope Complexity Guard (BLOCKING)
+
+> **Root cause (test-apex-007):** `/apex` was invoked with 3 applications and 7 entities.
+> The model's context window saturated, causing: incomplete migrations, lost conventions,
+> missing pages, unregistered i18n, forgotten DI registrations.
+>
+> `/apex` is designed for **incremental** development (1 module at a time).
+> Multi-module projects should use `/ralph-loop` which calls `/apex -d` per module.
+
+### Scope Detection
+
+```
+entity_count = {entities}.length
+section_count = {sections}.length
+app_count = number of DISTINCT applications detected in {task_description}
+           (heuristics: "application X et application Y", "module X, module Y, module Z"
+            with different app names, "3 apps", etc.)
+
+scope_score = entity_count + (section_count * 0.5) + (app_count * 3)
+```
+
+### Guard Rules
+
+```
+IF delegate_mode (-d flag):
+  → SKIP guard (ralph-loop already handles scope per module)
+
+ELSE IF app_count > 1:
+  → BLOCKING: "Multiple applications detected ({app_count} apps, {entity_count} entities).
+     /apex handles 1 module at a time. For multi-module projects, use:
+     - /ralph-loop (automated: reads PRD, generates all modules sequentially)
+     - Multiple /apex calls (manual: one /apex per module)
+
+     To override this guard, split your request:
+       /apex -e add HR employee management
+       /apex -e add CRM client management
+       /apex -e add Project management"
+
+ELSE IF scope_score > 8:
+  → WARNING: "Large scope detected ({entity_count} entities, {section_count} sections).
+     /apex works best with ≤ 4 entities per invocation.
+     Consider splitting into smaller iterations.
+     Proceeding, but expect higher risk of omissions."
+
+  AskUserQuestion:
+    header: "Scope"
+    question: "Le périmètre est large ({entity_count} entités). Réduire le scope ou continuer ?"
+    options:
+      - label: "Continue anyway"
+        description: "Proceed with full scope (higher risk of omissions)"
+      - label: "Split into iterations"
+        description: "Focus on the first module/app, then run /apex again for the rest"
+      - label: "Use /ralph-loop"
+        description: "Switch to /ralph-loop for automated multi-module orchestration"
+
+  IF "Split" → ask user which module to focus on first, update {entities}/{sections}
+  IF "/ralph-loop" → display command to run, STOP execution
+
+ELSE:
+  → PASS (scope is manageable)
+```
+
+### Recommended Scope per /apex Invocation
+
+| Metric | Safe | Warning | Blocking |
+|--------|------|---------|----------|
+| Applications | 1 | 1 (large) | >1 |
+| Entities | 1-4 | 5-6 | >6 without -d |
+| Sections | 1-3 | 4-5 | >5 without -d |
+| Sub-resources | 0-2 | 3-4 | >4 without -d |
+
+---
+
 ## 6. Determine Needs
 
 ```

package/templates/skills/apex/steps/step-01-analyze.md

@@ -211,6 +211,27 @@ Cross-reference with step-00 challenge responses:
 
 ---
 
+## 5b. Scope Re-Check (after exploration)
+
+> **Re-validate scope after code exploration reveals the true entity count.**
+> Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
+
+```
+IF NOT delegate_mode:
+  actual_entities = count of entities marked "create" in gap analysis
+  actual_sections = count of sections marked "create"
+
+  IF actual_entities > 6:
+    WARNING: "Code exploration reveals {actual_entities} entities to create.
+     This exceeds the recommended maximum (4) for a single /apex invocation.
+     Risk: incomplete migrations, lost conventions, missing pages.
+     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
+
+    AskUserQuestion: (same options as step-00 section 5d)
+```
+
+---
+
 ## 6. Analysis Validation (User Checkpoint)
 
 > **Objective:** Present findings and validate scope with the user BEFORE planning.

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

@@ -44,16 +44,26 @@ For each entity:
 
 ### Migration (BLOCKING)
 
+> **CRITICAL — Migration must cover ALL entities, not just the first batch.**
+> Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities
+> were added later without re-running migration → 4 entities had no database tables.
+> **RULE:** Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
+> If entities are added incrementally, create a NEW migration for each batch.
+
 ```
-1. MCP suggest_migration → get standardized name
-2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
-3. Cleanup corrupted EF Core artifacts:
+1. Verify ALL entities have been added as DbSet in ExtensionsDbContext
+2. Verify ALL EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
+3. MCP suggest_migration → get standardized name
+4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
+5. Cleanup corrupted EF Core artifacts:
    for d in src/*/bin?Debug; do [ -d "$d" ] && rm -rf "$d"; done
-4. dotnet ef database update (if local DB)
-5. dotnet build → MUST PASS
+6. dotnet ef database update (if local DB)
+7. dotnet build → MUST PASS
+8. Verify: dotnet ef migrations has-pending-model-changes → MUST report "No pending model changes"
 ```
 
 **BLOCKING:** If build fails after migration, fix EF configs before proceeding.
+**BLOCKING:** If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
 
 ### Post-Layer 0 Build Gate
 
@@ -67,10 +77,66 @@ dotnet build
 
 ## Layer 1 — Application + API + Seed Data
 
+### NavRoute and Permission Kebab-Case (CRITICAL)
+
+> **ALL NavRoute segments and permission codes MUST use kebab-case for multi-word identifiers.**
+> Root cause (test-apex-007): Controllers had `[NavRoute("business.humanresources.employees")]`
+> instead of `[NavRoute("business.human-resources.employees")]`. This mismatched seed data routes
+> and permission codes, causing 404s and permission denials at runtime.
+
+**Rules:**
+- NavRoute: `business.human-resources.employees` (NEVER `business.humanresources.employees`)
+- Permissions: `business.human-resources.employees.read` (segments MATCH NavRoute exactly)
+- Seed data codes: `human-resources` (NEVER `humanresources`)
+- C# class names stay PascalCase (`HumanResourcesController`) — only route/permission strings use kebab-case
+- POST-CHECKs 41 + 48 validate this. Fix BEFORE committing.
+
+### Controller Route Attribute (BLOCKING)
+
+> **Controllers with `[NavRoute]` must NOT have `[Route]` attribute.**
+> Root cause (test-apex-007): ALL 7 controllers had BOTH `[Route("api/...")]` AND `[NavRoute("...")]`.
+> In SmartStack, `[NavRoute]` resolves routes dynamically from Navigation entities in the database at startup.
+> Having `[Route]` alongside causes route conflicts → all endpoints return 404.
+
+**Rules:**
+- `[NavRoute("context.app.module")]` is the ONLY route attribute needed on controllers
+- **FORBIDDEN:** `[Route("api/business/human-resources/employees")]` alongside `[NavRoute]`
+- **FORBIDDEN:** `[Route("api/[controller]")]` alongside `[NavRoute]`
+- If generating via MCP `scaffold_extension` with `navRoute` option → output is correct (NavRoute only)
+- If generating via `/controller` skill → verify NO `[Route]` is added
+- POST-CHECK 50 validates this. Fix BEFORE committing.
+
+### Validators DI Registration (CRITICAL)
+
+> After creating validators, they MUST be registered in DI. Without registration, `[FromBody]` DTOs are never validated.
+
+```
+In DependencyInjection.cs (or ServiceCollectionExtensions.cs):
+  services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();
+```
+
+POST-CHECK 46 validates this. If validators exist but no DI registration → BLOCKING.
+
 ### If economy_mode: Sequential execution
 
 Execute each item from the plan sequentially using skills and MCP.
 
+### Date Fields — Use DateOnly (CRITICAL)
+
+> **ALL date-only fields in DTOs MUST use `DateOnly`, NEVER `string`.**
+> Root cause (test-apex-007): WorkLog DTO had `string Date` instead of `DateOnly Date`.
+> This causes: no date validation, inconsistent date formats, parsing errors.
+
+**Type mapping for DTOs:**
+| Domain type | DTO type | Example |
+|-------------|----------|---------|
+| `DateTime` | `DateTime` | `CreatedAt`, `UpdatedAt` |
+| Date-only field | `DateOnly` | `Date`, `StartDate`, `EndDate`, `BirthDate` |
+| `string` for date | **FORBIDDEN** | Never use `string` for dates |
+| `DateTime` for date-only | **Avoid** | Use `DateOnly` when no time component needed |
+
+POST-CHECK 47 validates this. If a DTO has `string` type for a property named `*Date*` → BLOCKING.
+
 ### Code Generation (if entities have codePattern != "manual")
 
 For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
@@ -114,6 +180,7 @@ Code stays in CreateDto, user provides it, validator has regex rule.
   - A dead link (navigate to a route with no page) is a BLOCKING issue (POST-CHECK 42)
 - Read `references/smartstack-frontend.md` for mandatory patterns (sections 3b + 8)
 - Generate i18n JSON files for all 4 languages (fr, en, it, de) — `src/i18n/locales/{lang}/{module}.json`
+- **I18n REGISTRATION (CRITICAL):** After creating i18n JSON files, register EACH new namespace in the i18n config file (config.ts/index.ts/i18n.ts). Unregistered namespaces → `useTranslation(['module'])` returns empty strings at runtime. POST-CHECK 45 validates this.
 - All pages must follow loading → error → content pattern with CSS variables
 
 ### If NOT economy_mode: Agent Teams (parallel)