@atlashub/smartstack-cli 3.33.0 → 3.35.0

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

@@ -166,27 +166,57 @@ if [ -n "$PAGE_FILES" ]; then
 fi
 ```
 
-### POST-CHECK 9: Create/Edit pages must exist as separate route pages
+### POST-CHECK 9: Create/Edit pages must exist as separate route pages (BLOCKING)
 
 ```bash
 # For each module with a list page, verify create and edit pages exist
+# If ListPage has navigate() calls to /create or /:id/edit, the target pages MUST exist
 LIST_PAGES=$(find src/pages/ -name "*ListPage.tsx" -o -name "*sPage.tsx" 2>/dev/null | grep -v test)
+FAIL=false
 if [ -n "$LIST_PAGES" ]; then
   for LIST_PAGE in $LIST_PAGES; do
     PAGE_DIR=$(dirname "$LIST_PAGE")
     MODULE_NAME=$(basename "$PAGE_DIR")
+
+    # Detect if ListPage navigates to /create or /edit routes
+    HAS_CREATE_NAV=$(grep -P "navigate\(.*['/]create" "$LIST_PAGE" 2>/dev/null)
+    HAS_EDIT_NAV=$(grep -P "navigate\(.*['/]edit|navigate\(.*/:id/edit" "$LIST_PAGE" 2>/dev/null)
+
     # Check for create page
     CREATE_PAGE=$(find "$PAGE_DIR" -name "*CreatePage.tsx" 2>/dev/null)
     if [ -z "$CREATE_PAGE" ]; then
-      echo "WARNING: Module $MODULE_NAME has a list page but no CreatePage — expected EntityCreatePage.tsx"
+      if [ -n "$HAS_CREATE_NAV" ]; then
+        echo "BLOCKING: Module $MODULE_NAME ListPage navigates to /create but CreatePage does NOT exist"
+        echo "  Dead link: $HAS_CREATE_NAV"
+        echo "  Fix: Create ${MODULE_NAME}CreatePage.tsx in $PAGE_DIR"
+        FAIL=true
+      else
+        echo "WARNING: Module $MODULE_NAME has a list page but no CreatePage — expected EntityCreatePage.tsx"
+      fi
     fi
+
     # Check for edit page
     EDIT_PAGE=$(find "$PAGE_DIR" -name "*EditPage.tsx" 2>/dev/null)
     if [ -z "$EDIT_PAGE" ]; then
-      echo "WARNING: Module $MODULE_NAME has a list page but no EditPage — expected EntityEditPage.tsx"
+      if [ -n "$HAS_EDIT_NAV" ]; then
+        echo "BLOCKING: Module $MODULE_NAME ListPage navigates to /:id/edit but EditPage does NOT exist"
+        echo "  Dead link: $HAS_EDIT_NAV"
+        echo "  Fix: Create ${MODULE_NAME}EditPage.tsx in $PAGE_DIR"
+        FAIL=true
+      else
+        echo "WARNING: Module $MODULE_NAME has a list page but no EditPage — expected EntityEditPage.tsx"
+      fi
     fi
   done
 fi
+
+if [ "$FAIL" = true ]; then
+  echo ""
+  echo "BLOCKING: Create/Edit pages are MISSING but ListPage buttons link to them."
+  echo "Users will see white screen / 404 when clicking Create or Edit buttons."
+  echo "Fix: Generate form pages using /ui-components skill patterns (smartstack-frontend.md section 3b)"
+  exit 1
+fi
 ```
 
 ### POST-CHECK 10: Form pages must have companion test files
@@ -1016,4 +1046,434 @@ if [ -n "$PROVIDER" ]; then
 fi
 ```
 
+### POST-CHECK 39: Controllers must NOT have [Route] alongside [NavRoute] (BLOCKING)
+
+```bash
+# [NavRoute] REPLACES [Route] — it resolves HTTP routes from the navigation DB at startup.
+# Having both is redundant and may cause route conflicts.
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    HAS_NAVROUTE=$(grep -P '\[NavRoute\(' "$f" 2>/dev/null)
+    HAS_ROUTE=$(grep -P '\[Route\(' "$f" 2>/dev/null)
+    if [ -n "$HAS_NAVROUTE" ] && [ -n "$HAS_ROUTE" ]; then
+      echo "BLOCKING: Controller has both [Route] and [NavRoute] — [NavRoute] replaces [Route]: $f"
+      echo "  Found [NavRoute]: $HAS_NAVROUTE"
+      echo "  Found [Route]:    $HAS_ROUTE"
+      echo "Fix: Remove the [Route(\"api/...\")] attribute. [NavRoute] resolves routes from navigation DB at startup."
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK 40: NavRoute segments must use kebab-case for multi-word codes (BLOCKING)
+
+```bash
+# NavRoute segments are navigation entity Codes joined by dots.
+# Multi-word codes MUST use kebab-case (e.g., "human-resources", NOT "humanresources").
+# Verified from SmartStack.app: "business.support-client.my-tickets", "platform.administration.access-requests"
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    NAVROUTE_VAL=$(grep -oP 'NavRoute\("([^"]+)"\)' "$f" 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"')
+    if [ -n "$NAVROUTE_VAL" ]; then
+      # Check each segment for concatenated multi-word (10+ lowercase chars without hyphens)
+      for SEG in $(echo "$NAVROUTE_VAL" | tr '.' '\n'); do
+        if echo "$SEG" | grep -qP '^[a-z]{10,}$'; then
+          echo "BLOCKING: NavRoute segment '$SEG' in $f appears to be concatenated multi-word without hyphens"
+          echo "  Full NavRoute: $NAVROUTE_VAL"
+          echo "  Fix: Use kebab-case: e.g., 'humanresources' → 'human-resources'"
+          echo "  SmartStack convention (from SmartStack.app): 'business.support-client.my-tickets'"
+          exit 1
+        fi
+      done
+    fi
+  done
+fi
+
+# Also check seed data Code values for navigation entities
+SEED_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*NavigationSeedData.cs" -o -name "NavigationApplicationSeedData.cs" 2>/dev/null)
+if [ -n "$SEED_FILES" ]; then
+  CODES=$(grep -oP 'Code\s*=\s*"([^"]+)"' $SEED_FILES 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"' | sort -u)
+  for CODE in $CODES; do
+    if echo "$CODE" | grep -qP '^[a-z]{10,}$'; then
+      echo "BLOCKING: Navigation seed data Code '$CODE' appears to be concatenated multi-word without hyphens"
+      echo "  Fix: Use kebab-case: e.g., 'humanresources' → 'human-resources'"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK 41: Permission codes must use kebab-case matching NavRoute codes (BLOCKING)
+
+```bash
+# Permission codes in [RequirePermission] and Permissions.cs MUST use kebab-case for multi-word segments.
+# SmartStack.app convention: "business.support-client.my-tickets.read" (kebab-case everywhere)
+# FORBIDDEN: "business.humanresources.employees.read" — must be "business.human-resources.employees.read"
+
+# Check [RequirePermission] attributes in controllers
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    PERM_VALS=$(grep -oP 'RequirePermission\("([^"]+)"\)' "$f" 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"')
+    for PERM in $PERM_VALS; do
+      # Check each segment (except the action suffix) for concatenated multi-word without hyphens
+      SEGMENTS=$(echo "$PERM" | tr '.' '\n' | head -n -1)  # remove last segment (action: read/create/update/delete)
+      for SEG in $SEGMENTS; do
+        if echo "$SEG" | grep -qP '^[a-z]{10,}$'; then
+          echo "BLOCKING: Permission code segment '$SEG' in $f appears concatenated without hyphens"
+          echo "  Full permission: $PERM"
+          echo "  Fix: Use kebab-case: e.g., 'humanresources' → 'human-resources'"
+          echo "  SmartStack convention: 'business.support-client.my-tickets.read'"
+          exit 1
+        fi
+      done
+    done
+  done
+fi
+
+# Check Permissions.cs constants
+PERM_FILES=$(find src/ -path "*/Authorization/Permissions.cs" 2>/dev/null)
+if [ -n "$PERM_FILES" ]; then
+  for f in $PERM_FILES; do
+    CONST_VALS=$(grep -oP '=\s*"([^"]+)"' "$f" 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"')
+    for PERM in $CONST_VALS; do
+      SEGMENTS=$(echo "$PERM" | tr '.' '\n' | head -n -1)
+      for SEG in $SEGMENTS; do
+        if echo "$SEG" | grep -qP '^[a-z]{10,}$'; then
+          echo "BLOCKING: Permissions.cs constant segment '$SEG' in $f appears concatenated without hyphens"
+          echo "  Full permission: $PERM"
+          echo "  Fix: Use kebab-case: e.g., 'humanresources' → 'human-resources'"
+          exit 1
+        fi
+      done
+    done
+  done
+fi
+
+# Check PermissionsSeedData.cs for mismatched paths
+SEED_PERM_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*PermissionsSeedData.cs" 2>/dev/null)
+if [ -n "$SEED_PERM_FILES" ]; then
+  PATHS=$(grep -oP '"[a-z][a-z0-9.-]+\.(read|create|update|delete|\*)"' $SEED_PERM_FILES 2>/dev/null | tr -d '"')
+  for PERM in $PATHS; do
+    SEGMENTS=$(echo "$PERM" | tr '.' '\n' | head -n -1)
+    for SEG in $SEGMENTS; do
+      if echo "$SEG" | grep -qP '^[a-z]{10,}$'; then
+        echo "BLOCKING: PermissionsSeedData path segment '$SEG' appears concatenated without hyphens"
+        echo "  Full permission path: $PERM"
+        echo "  Fix: Use kebab-case matching NavRoute: 'humanresources' → 'human-resources'"
+        exit 1
+      fi
+    done
+  done
+fi
+```
+
+### POST-CHECK 42: Frontend navigate() calls must have matching route definitions (BLOCKING)
+
+```bash
+# Detect dead links: navigate() calls to paths that don't have corresponding page components.
+# Example: LeavesPage has navigate('../leave-types') but no LeaveTypesPage or route exists.
+PAGE_FILES=$(find web/ -name "*.tsx" -path "*/pages/*" ! -name "*.test.tsx" 2>/dev/null)
+if [ -n "$PAGE_FILES" ]; then
+  # Extract navigate targets (relative paths like '../leave-types', './create', etc.)
+  NAV_TARGETS=$(grep -oP "navigate\(['\"]([^'\"]+)['\"]" $PAGE_FILES 2>/dev/null | grep -oP "['\"][^'\"]+['\"]" | tr -d "'" | tr -d '"' | sort -u)
+  # Extract route paths from App.tsx or route config
+  APP_FILES=$(find web/ -name "App.tsx" -o -name "routes.tsx" -o -name "clientRoutes*.tsx" 2>/dev/null)
+  if [ -n "$APP_FILES" ] && [ -n "$NAV_TARGETS" ]; then
+    ROUTE_PATHS=$(grep -oP "path:\s*['\"]([^'\"]+)['\"]" $APP_FILES 2>/dev/null | grep -oP "['\"][^'\"]+['\"]" | tr -d "'" | tr -d '"' | sort -u)
+    for TARGET in $NAV_TARGETS; do
+      # Skip dynamic segments (:id), back navigation (-1), and absolute URLs
+      if echo "$TARGET" | grep -qP '^(:|/api|http|-[0-9])'; then continue; fi
+      # Extract the last path segment for matching (e.g., '../leave-types' → 'leave-types')
+      LAST_SEG=$(echo "$TARGET" | grep -oP '[a-z][-a-z0-9]*$')
+      if [ -z "$LAST_SEG" ]; then continue; fi
+      # Check if any route path contains this segment
+      FOUND=$(echo "$ROUTE_PATHS" | grep -F "$LAST_SEG" 2>/dev/null)
+      if [ -z "$FOUND" ]; then
+        # Verify no page component exists for this path
+        SEG_PASCAL=$(echo "$LAST_SEG" | sed -r 's/(^|-)([a-z])/\U\2/g')
+        PAGE_EXISTS=$(find web/ -name "${SEG_PASCAL}Page.tsx" -o -name "${SEG_PASCAL}ListPage.tsx" -o -name "${SEG_PASCAL}sPage.tsx" 2>/dev/null)
+        if [ -z "$PAGE_EXISTS" ]; then
+          # Find which file has this navigate call
+          SOURCE_FILE=$(grep -rl "navigate(['\"].*${LAST_SEG}" $PAGE_FILES 2>/dev/null | head -1)
+          echo "BLOCKING: Dead link detected — navigate('$TARGET') in $SOURCE_FILE"
+          echo "  Route segment '$LAST_SEG' has no matching route in App.tsx and no page component"
+          echo "  Fix: Either create the page component + route, or remove the navigate() button"
+          exit 1
+        fi
+      fi
+    done
+  fi
+fi
+```
+
+### POST-CHECK 43: Detail page tabs must NOT navigate() — content switches locally (BLOCKING)
+
+```bash
+# Tabs on detail pages MUST use local state (setActiveTab) — NEVER navigate() to other pages.
+# Root cause (test-apex-006): EmployeeDetailPage tabs navigated to ../leaves and ../time-tracking
+# instead of rendering sub-resource content inline. Users lost detail page context.
+DETAIL_PAGES=$(find src/ web/ -name "*DetailPage.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\.")
+if [ -n "$DETAIL_PAGES" ]; then
+  FAIL=false
+  for DP in $DETAIL_PAGES; do
+    # Check if the page has tabs (activeTab state)
+    HAS_TABS=$(grep -P "useState.*activeTab|setActiveTab" "$DP" 2>/dev/null)
+    if [ -z "$HAS_TABS" ]; then continue; fi
+
+    # Check if any tab click handler calls navigate()
+    # Pattern: function that both references setActiveTab AND navigate()
+    # Look for navigate() calls inside handlers that also set tab state
+    TAB_NAVIGATE=$(grep -Pn "navigate\(" "$DP" 2>/dev/null | grep -v "navigate\(\s*['\"]edit['\"]" | grep -v "navigate\(\s*-1\s*\)" | grep -v "navigate\(\s*['\`].*/:id/edit" | grep -v "//")
+    if [ -n "$TAB_NAVIGATE" ]; then
+      # Verify this navigate is in a tab handler context (near setActiveTab usage)
+      # Simple heuristic: if file has both setActiveTab AND navigate() to relative paths
+      RELATIVE_NAV=$(echo "$TAB_NAVIGATE" | grep -P "navigate\(['\"\`]\.\./" 2>/dev/null)
+      if [ -n "$RELATIVE_NAV" ]; then
+        echo "BLOCKING: Detail page tabs use navigate() instead of local content switching: $DP"
+        echo "  Tab click handlers MUST only call setActiveTab() — render content inline"
+        echo "  Found navigate() calls (likely in tab handlers):"
+        echo "$RELATIVE_NAV"
+        echo ""
+        echo "  Fix: Remove navigate() from tab handlers. Render sub-resource content inline:"
+        echo "    {activeTab === 'leaves' && <LeaveRequestsTable employeeId={entity.id} />}"
+        echo "  See smartstack-frontend.md section 3 'Tab Behavior Rules' for the correct pattern."
+        FAIL=true
+      fi
+    fi
+  done
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+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,8 +491,20 @@ 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):**
+- NavRoute: `business.human-resources.employees` → Permission: `business.human-resources.employees.read`
+- NavRoute: `business.human-resources.employees.leaves` → Permission: `business.human-resources.employees.leaves.read`
+- FORBIDDEN: `business.humanresources.employees.read` (no kebab-case — mismatches NavRoute)
+- SmartStack.app convention: `business.support-client.my-tickets.read` (always kebab-case)
+
 ### Section-Level Controller (NavRoute with 4 segments)
 
 When a module has sections, each section gets its own controller with a 4-segment navRoute:
@@ -504,7 +516,7 @@ When a module has sections, each section gets its own controller with a 4-segmen
 [Authorize]
 public class {Section}Controller : ControllerBase
 {
-    // Example: business.humanresources.employees.departments
+    // Example: business.human-resources.employees.departments
     [HttpGet]
     [RequirePermission(Permissions.{Section}.Read)]
     public async Task<ActionResult<PaginatedResult<{Section}ResponseDto>>> GetAll(
@@ -519,13 +531,46 @@ public class {Section}Controller : ControllerBase
 **NavRoute segment rules:**
 | Level | NavRoute format | Example |
 |-------|----------------|---------|
-| Module | `{context}.{app}.{module}` (3 segments) | `business.humanresources.employees` |
-| Section | `{context}.{app}.{module}.{section}` (4 segments) | `business.humanresources.employees.departments` |
+| Module | `{context}.{app}.{module}` (3 segments) | `business.human-resources.employees` |
+| Section | `{context}.{app}.{module}.{section}` (4 segments) | `business.human-resources.employees.departments` |
 
 **Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
 
 **NavRoute resolves at startup from DB:** `platform.administration.users` → `api/platform/administration/users`
 
+### Sub-Resource Pattern (NavRoute Suffix)
+
+When an entity is a child of another entity (e.g., LeaveTypes under Leaves), use `[NavRoute(..., Suffix = "types")]`:
+
+```csharp
+// Sub-resource controller: types are nested under leaves
+[ApiController]
+[NavRoute("business.human-resources.employees.leaves", Suffix = "types")]
+[Authorize]
+public class LeaveTypesController : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.Leaves.Read)]  // inherits parent section permission
+    public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAll(...)
+        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
+}
+```
+
+**Alternative pattern** (sub-resource endpoints within parent controller):
+```csharp
+// LeaveTypes as endpoints within LeavesController
+[HttpGet("types")]
+[RequirePermission(Permissions.Leaves.Read)]
+public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAllLeaveTypes(...)
+```
+
+> **CRITICAL — Sub-resource frontend completeness:**
+> If a parent page has a button (e.g., "Manage Leave Types") that `navigate()`s to a sub-resource route,
+> the frontend MUST include a page component for that route. Otherwise → dead link → white screen.
+> - Either create a dedicated sub-resource ListPage (e.g., `LeaveTypesPage.tsx`)
+> - Or DON'T include the navigate() button if pages won't be created
+> - **Prefer separate controllers** (with Suffix) over sub-endpoints in parent controller — easier to route
+
 ---
 
 ## Navigation Seed Data Pattern (CRITICAL — routes must be full paths)
@@ -579,9 +624,9 @@ public static class SeedConstants
     // Deterministic GUIDs (SHA256-based, reproducible across environments)
     // NOTE: Application/Module/Section/Resource IDs are deterministic.
     //       Context IDs are NOT — they are pre-seeded by SmartStack core.
-    public static readonly Guid ApplicationId = DeterministicGuid("nav:business.humanresources");
-    public static readonly Guid ModuleId = DeterministicGuid("nav:business.humanresources.employees");
-    public static readonly Guid SectionId = DeterministicGuid("nav:business.humanresources.employees.departments");
+    public static readonly Guid ApplicationId = DeterministicGuid("nav:business.human-resources");
+    public static readonly Guid ModuleId = DeterministicGuid("nav:business.human-resources.employees");
+    public static readonly Guid SectionId = DeterministicGuid("nav:business.human-resources.employees.departments");
 
     // FORBIDDEN — Context IDs are NOT deterministic, they come from SmartStack core:
     // public static readonly Guid BusinessContextId = DeterministicGuid("nav:business"); // WRONG!
@@ -609,7 +654,7 @@ if (businessCtx == null) return; // Context not yet seeded by SmartStack core
 
 // Application: /business/human-resources
 var app = NavigationApplication.Create(
-    businessCtx.Id, "humanresources", "Human Resources", "HR Management",
+    businessCtx.Id, "human-resources", "Human Resources", "HR Management",
     "Users", IconType.Lucide,
     "/business/human-resources",  // FULL PATH — starts with /, kebab-case
     10);
@@ -664,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 |
@@ -674,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` |
@@ -684,8 +749,11 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `UnauthorizedAccessException("Tenant context is required")` | Returns 401 → clears frontend token. Use `TenantContextRequiredException()` (400) |
 | Route `"humanresources"` in seed data | Must be full path `"/business/human-resources"` |
 | Route without leading `/` | All routes must start with `/` |
+| `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 |