@atlashub/smartstack-cli 4.27.0 → 4.29.0

package/package.json

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

package/templates/skills/apex/references/core-seed-data.md

@@ -274,7 +274,7 @@ public static class {ModulePascal}NavigationSeedData
             Description = "{desc_en}",
             Icon = "{icon}",              // Lucide React icon name
             IconType = IconType.Lucide,
-            Route = ToKebabCase($"/{appCode}/{moduleCode}"),
+            Route = ToKebabCase($"/{appCode}/{moduleCode}"),  // Absolute path for sidebar navigation (App.tsx routes are RELATIVE to module root)
             DisplayOrder = {displayOrder},
             IsActive = true
         };
@@ -731,13 +731,33 @@ public class PermissionSeedEntry
 }
 ```
 
-### Step C2: Section-Level Permissions (CONDITIONAL: only if `navSections[]` defined)
+### Step C2: Section-Level Permissions (CONDITIONAL — filtered by `permissionMode`)
 
 > When `seedDataCore.navigationSections` exists and is non-empty in feature.json,
 > add section-level permission GUIDs and entries to `PermissionsSeedData.cs`.
+>
+> **Permission generation is conditional on each section's `permissionMode`:**
+>
+> | permissionMode | Permissions generated |
+> |---|---|
+> | `crud` | wildcard + read + create + update + delete |
+> | `custom:action1,action2` | wildcard + read + custom actions |
+> | `read-only` | read only (NO CRUD wildcard) |
+> | `inherit` | NO section-level permissions (inherits from module) |
+>
+> **Default inference (when `permissionMode` is absent):**
+> - `code === "detail"` → `inherit`
+> - `code === "dashboard"` → `read-only`
+> - otherwise → `crud`
+>
+> **IMPORTANT:** Sections with `permissionMode: inherit` MUST be skipped entirely.
+> Do NOT generate any permission GUIDs, entries, or constants for them.
 
 ```csharp
 // --- Add to {ModulePascal}PermissionsSeedData class AFTER module-level permissions ---
+// FILTER: Only generate for sections where permissionMode is NOT "inherit"
+// For "read-only" sections: generate ONLY ReadPermId (no Wildcard, Create, Update, Delete)
+// For "custom:x,y" sections: generate Wildcard + Read + custom action GUIDs
 
 // Section-level permissions (for each section in navSections[])
 public static readonly Guid {SectionPascal}WildcardPermId = Guid.NewGuid();
@@ -1155,8 +1175,10 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
     {
         // Check idempotence — verify by Code (roles may already exist from SmartStack core)
+        // Scope by ApplicationId — without this, roles from OTHER apps cause false positives
         var existingRoleCodes = await context.Roles
-            .Where(r => r.Code == "admin" || r.Code == "manager" || r.Code == "contributor" || r.Code == "viewer")
+            .Where(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId
+                && (r.Code == "admin" || r.Code == "manager" || r.Code == "contributor" || r.Code == "viewer"))
             .Select(r => r.Code)
             .ToListAsync(ct);
 
@@ -1213,8 +1235,9 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         // Application-scoped roles (admin, manager, contributor, viewer) are created by
         // SeedRolesAsync() above. System roles use their own IDs that do not match
         // DeterministicGuid("role:admin").
+        // Load THIS application's roles + system roles only
         var roles = await context.Roles
-            .Where(r => r.ApplicationId != null || r.IsSystem)
+            .Where(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId || r.IsSystem)
             .ToListAsync(ct);
 
         // Resolve permissions

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

@@ -56,20 +56,42 @@ Read App.tsx and detect which pattern is used:
 
 → Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)
 
+> **CRITICAL — Include Module Segment:** Paths are relative to `/{application}/`.
+> For a 3-level hierarchy (app → module → sections), paths MUST be `{module_kebab}/{section_kebab}`.
+> Using just `{section_kebab}` omits the module segment → route resolves to `/{app}/{section}` instead
+> of `/{app}/{module}/{section}` → mismatch with backend navigation seed data → 404.
+
 ```tsx
 const applicationRoutes: ApplicationRouteExtensions = {
   'human-resources': [
     // existing routes...
+    // Paths include module segment: employee-management/employees (NOT just employees)
     { path: '{module_kebab}/{section_kebab}', element: <{EntityName}ListPage /> },
     { path: '{module_kebab}/{section_kebab}/create', element: <Create{EntityName}Page /> },
     { path: '{module_kebab}/{section_kebab}/:id', element: <{EntityName}DetailPage /> },
-    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Create{EntityName}Page /> },
+    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Edit{EntityName}Page /> },
 
     // Parent redirect routes (MANDATORY — prevents /login redirect on parent navigation)
     { path: '{module_kebab}', element: <Navigate to="{module_kebab}/{first_section_kebab}" replace /> },
     { path: '', element: <Navigate to="{first_module_kebab}/{first_section_kebab}" replace /> },
   ],
 };
+
+// Concrete example: app=human-resources, module=employee-management, sections=employees,absences
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [
+    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅
+    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
+    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
+    // ...absences...
+    { path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+    { path: '', element: <Navigate to="employee-management/employees" replace /> },
+  ],
+};
+
+// ❌ WRONG — missing module segment:
+// { path: 'employees', ... }  → resolves to /human-resources/employees (backend expects /human-resources/employee-management/employees)
+```
 ```
 
 Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
@@ -162,10 +184,10 @@ For each application, add:
    { path: '{module}', element: <Navigate to="{module}/{first_section}" replace /> }
    ```
 
-**Example:** For NavRoutes `human-resources.employees.management` and `human-resources.employees.departments`:
+**Example:** For NavRoutes `human-resources.employee-management.employees` and `human-resources.employee-management.absences`:
 ```tsx
-{ path: 'employees', element: <Navigate to="employees/management" replace /> },
-{ path: '', element: <Navigate to="employees/management" replace /> },
+{ path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+{ path: '', element: <Navigate to="employee-management/employees" replace /> },
 ```
 
 The `to` prop is resolved relative to the **parent route** (`/{application}`), so always use the full path from the application root.
@@ -186,12 +208,12 @@ The `to` prop is resolved relative to the **parent route** (`/{application}`), s
     { path: '/human-resources/employees/management', element: <EmployeePage /> },
   ];
   ```
-  Custom application routes go in `applicationRoutes` with RELATIVE paths:
+  Custom application routes go in `applicationRoutes` with RELATIVE paths (including module segment):
   ```tsx
-  // ✅ CORRECT
+  // ✅ CORRECT — module segment included
   const applicationRoutes: ApplicationRouteExtensions = {
     'human-resources': [
-      { path: 'employees/management', element: <EmployeePage /> },
+      { path: 'employee-management/employees', element: <EmployeesPage /> },
     ],
   };
   ```

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

@@ -132,10 +132,121 @@ if [ -n "$CTRL_FILES" ]; then
 fi
 ```
 
+### POST-CHECK S8: Write endpoints must NOT use Read permissions (BLOCKING)
+
+> **Source:** audit ba-002 finding C1 — Cancel endpoint (POST) used `Permissions.Absences.Read`,
+> allowing any reader to cancel absences. Write operations MUST use write permissions.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Extract blocks: find each method with Http verb + RequirePermission
+    # Check POST/PUT/DELETE/PATCH endpoints that use *.Read permission
+    WRITE_WITH_READ=$(grep -Pn '\[(HttpPost|HttpPut|HttpDelete|HttpPatch)' "$f" | while read -r line; do
+      LINE_NUM=$(echo "$line" | cut -d: -f1)
+      # Look within 5 lines for RequirePermission with .Read
+      sed -n "$((LINE_NUM-2)),$((LINE_NUM+5))p" "$f" | grep -P 'RequirePermission.*\.Read\b' | head -1
+    done)
+    if [ -n "$WRITE_WITH_READ" ]; then
+      echo "BLOCKING: Write endpoint uses Read permission in $f"
+      echo "$WRITE_WITH_READ"
+      echo "Fix: POST/PUT/DELETE/PATCH endpoints must use Create/Update/Delete permissions, never Read"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK S9: FK relationships must enforce tenant isolation (BLOCKING)
+
+> **Source:** audit ba-002 finding C5 — Department.ManagerId FK referenced Employee without
+> tenant constraint, allowing cross-tenant data leakage through navigation properties.
+
+```bash
+CONFIG_FILES=$(find src/ -path "*/Configurations/*" -name "*Configuration.cs" 2>/dev/null)
+if [ -n "$CONFIG_FILES" ]; then
+  for f in $CONFIG_FILES; do
+    # Check if entity implements ITenantEntity
+    ENTITY_NAME=$(grep -oP 'IEntityTypeConfiguration<(\w+)>' "$f" | grep -oP '<\K[^>]+')
+    if [ -z "$ENTITY_NAME" ]; then continue; fi
+
+    # Check if the entity is tenant-scoped (has TenantId in its properties or base class)
+    ENTITY_FILE=$(find src/ -path "*/Domain/*" -name "${ENTITY_NAME}.cs" 2>/dev/null | head -1)
+    if [ -z "$ENTITY_FILE" ]; then continue; fi
+
+    IS_TENANT=$(grep -cE 'ITenantEntity|BaseEntity|TenantId' "$ENTITY_FILE")
+    if [ "$IS_TENANT" -eq 0 ]; then continue; fi
+
+    # For tenant entities, check FK relationships point to other tenant entities
+    # Warning: FK to non-tenant entity from tenant entity = potential cross-tenant leak
+    FK_TARGETS=$(grep -oP 'HasOne<(\w+)>|HasOne\(e\s*=>\s*e\.(\w+)\)' "$f" | grep -oP '\w+(?=>|\))' | sort -u)
+    for TARGET in $FK_TARGETS; do
+      TARGET_FILE=$(find src/ -path "*/Domain/*" -name "${TARGET}.cs" 2>/dev/null | head -1)
+      if [ -n "$TARGET_FILE" ]; then
+        TARGET_IS_TENANT=$(grep -cE 'ITenantEntity|BaseEntity|TenantId' "$TARGET_FILE")
+        if [ "$TARGET_IS_TENANT" -gt 0 ]; then
+          # Both are tenant entities — verify the FK has a composite or filtered relationship
+          # At minimum, warn that cross-tenant reference is possible without query filter
+          HAS_QUERY_FILTER=$(grep -c 'HasQueryFilter' "$f")
+          if [ "$HAS_QUERY_FILTER" -eq 0 ]; then
+            echo "WARNING: $f — FK from tenant entity $ENTITY_NAME to tenant entity $TARGET without HasQueryFilter"
+            echo "Cross-tenant data leakage possible if FK is assigned without tenant validation"
+            echo "Fix: Add tenant validation in service layer before assigning FK, or use composite FK (TenantId + EntityId)"
+          fi
+        fi
+      fi
+    done
+  done
+fi
+```
+
 ---
 
 ## Backend — Entity, Service & Controller Checks
 
+### POST-CHECK V1: Controllers with POST/PUT must have corresponding Validators (BLOCKING)
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Check if controller has POST or PUT endpoints
+    HAS_WRITE=$(grep -cE "\[Http(Post|Put)\]" "$f")
+    if [ "$HAS_WRITE" -gt 0 ]; then
+      # Extract DTO names from POST/PUT method parameters
+      DTOS=$(grep -oP '(?:Create|Update)\w+Dto' "$f" | sort -u)
+      for DTO in $DTOS; do
+        VALIDATOR_NAME=$(echo "$DTO" | sed 's/Dto$/Validator/')
+        VALIDATOR_FILE=$(find src/ -path "*/Validators/*" -name "${VALIDATOR_NAME}.cs" 2>/dev/null)
+        if [ -z "$VALIDATOR_FILE" ]; then
+          echo "BLOCKING: Controller $f uses $DTO but no ${VALIDATOR_NAME}.cs found"
+          echo "Fix: Create Validator with FluentValidation rules from business rules"
+          exit 1
+        fi
+      done
+    fi
+  done
+fi
+```
+
+### POST-CHECK V2: Validators must be registered in DI (WARNING)
+
+```bash
+VALIDATOR_FILES=$(find src/ -path "*/Validators/*" -name "*Validator.cs" 2>/dev/null)
+if [ -n "$VALIDATOR_FILES" ]; then
+  DI_FILE=$(find src/ -name "DependencyInjection.cs" -o -name "ServiceCollectionExtensions.cs" 2>/dev/null | head -1)
+  if [ -n "$DI_FILE" ]; then
+    for f in $VALIDATOR_FILES; do
+      VALIDATOR_NAME=$(basename "$f" .cs)
+      if ! grep -q "$VALIDATOR_NAME" "$DI_FILE"; then
+        echo "WARNING: Validator $VALIDATOR_NAME not registered in DI: $DI_FILE"
+      fi
+    done
+  fi
+fi
+```
+
 ### POST-CHECK C1: Navigation routes must be full paths starting with /
 
 ```bash
@@ -1659,6 +1770,162 @@ if [ -n "$ENTITY_FILES" ]; then
 fi
 ```
 
+### POST-CHECK C49: Route Ordering in App.tsx — static before dynamic (BLOCKING)
+
+> **Source:** Dashboard 404 bug — `:id` route declared before `dashboard` route in applicationRoutes,
+> React Router matched `dashboard` as an `id` parameter → page not found.
+
+```bash
+APP_TSX=$(find web/ src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Extract all route paths from applicationRoutes in order
+  ROUTE_PATHS=$(grep -oP "path:\s*'([^']+)'" "$APP_TSX" | sed "s/path: '//;s/'//")
+  FAIL=false
+  PREV_PREFIX=""
+  PREV_IS_DYNAMIC=false
+
+  while IFS= read -r ROUTE; do
+    [ -z "$ROUTE" ] && continue
+    # Extract prefix (everything before last segment)
+    PREFIX=$(echo "$ROUTE" | sed 's|/[^/]*$||')
+    LAST_SEGMENT=$(echo "$ROUTE" | grep -oP '[^/]+$')
+    IS_DYNAMIC=$(echo "$LAST_SEGMENT" | grep -c '^:')
+
+    # Check: if previous route was dynamic and current route is static with same prefix
+    if [ "$PREV_IS_DYNAMIC" = true ] && [ "$IS_DYNAMIC" -eq 0 ] && [ "$PREFIX" = "$PREV_PREFIX" ]; then
+      echo "BLOCKING: Static route '$ROUTE' is AFTER a dynamic route with prefix '$PREFIX' in App.tsx"
+      echo "  React Router will match the dynamic route first → '$ROUTE' is unreachable (404)"
+      echo "  Fix: Move static routes BEFORE dynamic routes within the same prefix group"
+      FAIL=true
+    fi
+
+    PREV_PREFIX="$PREFIX"
+    if [ "$IS_DYNAMIC" -gt 0 ]; then
+      PREV_IS_DYNAMIC=true
+    else
+      PREV_IS_DYNAMIC=false
+    fi
+  done <<< "$ROUTE_PATHS"
+
+  # Also check: Navigate (redirect) routes must be at the end
+  REDIRECT_LINE=$(grep -n "Navigate" "$APP_TSX" | head -1 | cut -d: -f1)
+  if [ -n "$REDIRECT_LINE" ]; then
+    ROUTES_AFTER=$(tail -n +"$((REDIRECT_LINE+1))" "$APP_TSX" | grep -cP "path:\s*'" 2>/dev/null)
+    if [ "$ROUTES_AFTER" -gt 0 ]; then
+      echo "WARNING: Route definitions found AFTER Navigate redirect — redirects should be LAST"
+    fi
+  fi
+
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK C50: NavRoute Uniqueness — no duplicate NavRoute values (BLOCKING)
+
+> **Source:** Two controllers sharing the same NavRoute causes routing conflicts — one endpoint
+> silently overrides the other → 404 on the shadowed controller.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  # Extract all NavRoute values with their file paths
+  NAVROUTES=$(grep -Pn '\[NavRoute\("([^"]+)"\)' $CTRL_FILES 2>/dev/null | sed 's/.*\[NavRoute("\([^"]*\)").*/\1/' | sort)
+  DUPLICATES=$(echo "$NAVROUTES" | uniq -d)
+  if [ -n "$DUPLICATES" ]; then
+    echo "BLOCKING: Duplicate NavRoute values detected:"
+    for DUP in $DUPLICATES; do
+      echo "  NavRoute: $DUP"
+      grep -l "\[NavRoute(\"$DUP\")\]" $CTRL_FILES 2>/dev/null | while read -r f; do
+        echo "    - $f"
+      done
+    done
+    echo "  Fix: Each controller MUST have a unique NavRoute value"
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK C51: NavRoute Segments vs Controller Hierarchy (WARNING)
+
+> **Source:** ContractsController in `Controllers/{App}/Employees/` subfolder had NavRoute
+> `human-resources.contracts` (2 segments) instead of `human-resources.employees.contracts`
+> (3 segments) → API resolved to wrong path → 404 on contracts endpoints.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    NAVROUTE=$(grep -oP '\[NavRoute\("\K[^"]+' "$f")
+    if [ -z "$NAVROUTE" ]; then continue; fi
+
+    DOTS=$(echo "$NAVROUTE" | tr -cd '.' | wc -c)
+
+    # Count directory depth after Controllers/
+    # e.g., Controllers/HumanResources/Employees/ContractsController.cs = depth 2 (section)
+    REL_PATH=$(echo "$f" | sed 's|.*/Controllers/||')
+    DIR_DEPTH=$(echo "$REL_PATH" | tr '/' '\n' | wc -l)
+    # DIR_DEPTH: 2 = module level (App/Controller.cs), 3 = section level (App/Module/Controller.cs)
+
+    if [ "$DIR_DEPTH" -ge 3 ] && [ "$DOTS" -le 1 ]; then
+      echo "WARNING: Controller in section subfolder but NavRoute has only $((DOTS+1)) segments"
+      echo "  File: $f"
+      echo "  NavRoute: $NAVROUTE"
+      echo "  Expected: 3+ segments (app.module.section) for controllers in section subfolders"
+      echo "  Fix: Update NavRoute to include the module segment (e.g., 'app.module.section')"
+    fi
+
+    if [ "$DOTS" -eq 0 ]; then
+      echo "BLOCKING: NavRoute '$NAVROUTE' has only 1 segment (minimum 2 required): $f"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK C52: Frontend route paths must include module segment (BLOCKING)
+
+> **Source:** APEX regression — frontend routes used `employees` instead of `employee-management/employees`,
+> causing mismatch with backend navigation seed data routes (`/human-resources/employee-management/employees`).
+> Nav links produced 404 because React Router had no matching route for the full path.
+
+```bash
+# Compare frontend route paths in App.tsx against backend navigation seed data routes
+APP_TSX=$(find . -path "*/src/App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Extract all route paths from applicationRoutes
+  ROUTE_PATHS=$(grep -oP "path:\s*'[^']+'" "$APP_TSX" | grep -v "^path: ''" | grep -v ":id" | grep -v "create" | grep -v "edit" | sed "s/path: '//;s/'//")
+
+  # Find navigation seed data files to get backend routes
+  NAV_SEED_FILES=$(find src/ -name "*NavigationSeedData.cs" -o -name "*NavigationModuleSeedData.cs" 2>/dev/null)
+  if [ -n "$NAV_SEED_FILES" ]; then
+    # Extract module codes from seed data
+    MODULE_CODES=$(grep -oP 'Code\s*=\s*"\K[^"]+' $NAV_SEED_FILES 2>/dev/null | sort -u)
+
+    for route in $ROUTE_PATHS; do
+      # Skip redirect paths (empty or just module)
+      if [ -z "$route" ]; then continue; fi
+
+      # Check if route contains a slash (module/section pattern)
+      if ! echo "$route" | grep -q "/"; then
+        # Single segment route — check if it matches a section code (not a module code)
+        IS_MODULE=false
+        for mod in $MODULE_CODES; do
+          if [ "$route" = "$mod" ]; then IS_MODULE=true; break; fi
+        done
+        if [ "$IS_MODULE" = false ]; then
+          echo "BLOCKING: Frontend route '$route' is missing module segment"
+          echo "  Expected: '{module}/{route}' (e.g., 'employee-management/$route')"
+          echo "  Backend navigation seed data defines routes with full hierarchy: /app/module/section"
+          echo "  Frontend routes must match: module/section (relative to app root)"
+        fi
+      fi
+    done
+  fi
+fi
+```
+
 ---
 
 ## Architecture — Clean Architecture Layer Isolation
@@ -1785,6 +2052,63 @@ if [ -n "$CTRL_FILES" ]; then
 fi
 ```
 
+### POST-CHECK A8: API endpoints must match handoff apiEndpointSummary (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** 4/17 API endpoints (export, calculate, balance upsert, year-end)
+> were missing but all API tasks were marked COMPLETE. This check reconciles actual controller
+> endpoints against the handoff contract.
+
+```bash
+# Read apiEndpointSummary from PRD and verify each operation exists in controllers
+PRD_FILE=".ralph/prd.json"
+if [ ! -f "$PRD_FILE" ]; then
+  # Try module-specific PRD
+  if [ -f ".ralph/modules-queue.json" ]; then
+    PRD_FILE=$(cat .ralph/modules-queue.json | grep -o '"prdFile":"[^"]*"' | tail -1 | cut -d'"' -f4)
+  fi
+fi
+
+if [ -f "$PRD_FILE" ]; then
+  # Extract operation names from apiEndpointSummary
+  OPERATIONS=$(cat "$PRD_FILE" | grep -o '"operation"\s*:\s*"[^"]*"' | cut -d'"' -f4 2>/dev/null)
+
+  if [ -n "$OPERATIONS" ]; then
+    CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+    MISSING_OPS=""
+    TOTAL_OPS=0
+    FOUND_OPS=0
+
+    for op in $OPERATIONS; do
+      TOTAL_OPS=$((TOTAL_OPS + 1))
+      FOUND=false
+      if [ -n "$CTRL_FILES" ]; then
+        for f in $CTRL_FILES; do
+          if grep -q "$op" "$f" 2>/dev/null; then
+            FOUND=true
+            break
+          fi
+        done
+      fi
+      if [ "$FOUND" = true ]; then
+        FOUND_OPS=$((FOUND_OPS + 1))
+      else
+        MISSING_OPS="$MISSING_OPS $op"
+      fi
+    done
+
+    if [ -n "$MISSING_OPS" ]; then
+      echo "BLOCKING: API endpoints missing from controllers (handoff contract violation)"
+      echo "Found: $FOUND_OPS/$TOTAL_OPS operations"
+      echo "Missing operations:$MISSING_OPS"
+      echo "Fix: Implement missing endpoints in the appropriate Controller"
+      exit 1
+    else
+      echo "POST-CHECK A8: OK — $FOUND_OPS/$TOTAL_OPS API operations found"
+    fi
+  fi
+fi
+```
+
 ---
 
 ## Summary

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

@@ -14,8 +14,9 @@
 
 ```tsx
 // Named exports — use .then() to wrap
+// Path: @/pages/{App}/{Module}/{Section}/{Page}
 const EmployeesPage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EmployeesPage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EmployeesPage')
     .then(m => ({ default: m.EmployeesPage }))
 );
 
@@ -49,7 +50,7 @@ element: (
 **Incorrect patterns:**
 ```tsx
 // WRONG: static import in route file
-import { EmployeesPage } from '@/pages/HumanResources/Employees/EmployeesPage';
+import { EmployeesPage } from '@/pages/HumanResources/EmployeeManagement/Employees/EmployeesPage';
 
 // WRONG: no Suspense wrapper
 element: <EmployeesPage />
@@ -64,8 +65,9 @@ In the client `App.tsx` (where application routes are defined), all page imports
 
 **Correct — Lazy imports in client App.tsx:**
 ```tsx
+// Path includes module level: {App}/{Module}/{Section}/{Page}
 const ClientsListPage = lazy(() =>
-  import('@/pages/HumanResources/Clients/ClientsListPage')
+  import('@/pages/HumanResources/ClientManagement/Clients/ClientsListPage')
     .then(m => ({ default: m.ClientsListPage }))
 );
 ```
@@ -73,7 +75,7 @@ const ClientsListPage = lazy(() =>
 **Do not use — Static imports in client App.tsx:**
 ```tsx
 // WRONG: Static import kills code splitting
-import { ClientsListPage } from '@/pages/HumanResources/Clients/ClientsListPage';
+import { ClientsListPage } from '@/pages/HumanResources/ClientManagement/Clients/ClientsListPage';
 ```
 
 > **Note:** The `smartstackRoutes.tsx` from the npm package may use static imports internally — this is acceptable for the package. But client `App.tsx` code MUST always use lazy imports for business pages.
@@ -698,18 +700,19 @@ export function EntityEditPage() {
 
 ```tsx
 // In route files — form pages are also lazy-loaded
+// Path: @/pages/{App}/{Module}/{Section}/{Page}
 const EntityCreatePage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EntityCreatePage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityCreatePage')
     .then(m => ({ default: m.EntityCreatePage }))
 );
 const EntityEditPage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EntityEditPage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityEditPage')
     .then(m => ({ default: m.EntityEditPage }))
 );
 
-// Route registration — form pages have their own routes
+// Route registration — Pattern B (JSX nested children):
 {
-  path: 'employees',
+  path: 'employee-management/employees',
   children: [
     { index: true, element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense> },
     { path: 'create', element: <Suspense fallback={<PageLoader />}><EntityCreatePage /></Suspense> },
@@ -718,6 +721,18 @@ const EntityEditPage = lazy(() =>
   ]
 }
 
+// Route registration — Pattern A (applicationRoutes flat paths):
+// CRITICAL: paths are RELATIVE to /{app}/ and MUST include the module segment
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [
+    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅ includes module
+    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
+    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
+    { path: 'employee-management/employees/:id/edit', element: <EditEmployeePage /> }, // ✅
+    // ❌ WRONG: { path: 'employees', ... } — missing module segment → 404 on nav click
+  ],
+};
+
 // Section-level routes — children of the module route (when module has sections)
 //
 // > **IMPORTANT:** The `list` and `detail` sections do NOT generate additional route entries.

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

@@ -257,6 +257,8 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 - POST-CHECK C34 detects non-kebab-case NavRoute values. POST-CHECK C35 detects non-kebab-case permissions
 - Do not combine `[Route("api/...")]` with `[NavRoute]` — causes 404s (POST-CHECK C43)
 - `[NavRoute]` is the only route attribute needed — resolves routes from DB at startup
+- **NavRoute uniqueness:** Each controller MUST have a unique NavRoute value. Two controllers sharing the same NavRoute causes routing conflicts and 404s (POST-CHECK C50)
+- **NavRoute segment count vs hierarchy:** If a controller lives in a section subfolder (e.g., `Controllers/{App}/Employees/ContractsController.cs`), its NavRoute MUST have 3 segments (`app.module.section`), not 2. A 2-segment NavRoute on a section controller causes API 404s because the resolved route doesn't match the expected path (POST-CHECK C51)
 - Do not use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities
@@ -307,16 +309,61 @@ const [loading, setLoading] = useState(true);
 
 **Loader:** `Loader2` from `lucide-react` for spinners, `PageLoader` for Suspense fallback
 
+### RULE — Frontend Route Ordering
+
+> **CRITICAL:** React Router matches routes top-to-bottom. Dynamic routes (`:id`, `:id/edit`) placed BEFORE static routes (`dashboard`, `create`) will swallow the static paths — e.g., `/employees/dashboard` matches `:id` with `id="dashboard"` → 404.
+
+**Order (MANDATORY):**
+
+1. Index/list route (path: `'{module}/{section}'`)
+2. Create route (`'{module}/{section}/create'`)
+3. Static sections (`'{module}/{section}/dashboard'`, etc.)
+4. Dynamic routes (`'{module}/{section}/:id'`, `'{module}/{section}/:id/edit'`)
+5. Module redirect (`'{module}'` → `'{module}/{first_section}'`)
+6. Application redirect (`''` → `'{first_module}/{first_section}'`) — ALWAYS LAST
+
+```tsx
+// ✅ CORRECT — module segment included, static before dynamic
+// (inside applicationRoutes['human-resources'], paths are relative to /human-resources/)
+{ path: 'employee-management/employees', element: <EmployeesPage /> },
+{ path: 'employee-management/employees/create', element: <CreateEmployeePage /> },
+{ path: 'employee-management/employees/dashboard', element: <EmployeeDashboardPage /> },
+{ path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },
+{ path: 'employee-management/employees/:id/edit', element: <EditEmployeePage /> },
+{ path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+{ path: '', element: <Navigate to="employee-management/employees" replace /> },
+
+// ❌ WRONG — missing module segment (resolves to /human-resources/employees instead of /human-resources/employee-management/employees)
+{ path: 'employees', element: <EmployeesPage /> },
+
+// ❌ WRONG — :id before dashboard → dashboard is unreachable (matched as id="dashboard")
+{ path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },
+{ path: 'employee-management/employees/dashboard', element: <EmployeeDashboardPage /> },  // NEVER REACHED
+```
+
+POST-CHECK C49 detects this anti-pattern and BLOCKS.
+
 ### Section Routes (when module has sections)
 
-If the module defines `{sections}`, generate frontend routes for EACH section as children of the module route:
+If the module defines `{sections}`, generate frontend routes for EACH section as children of the application route.
+
+> **CRITICAL — Module Segment Required:** Route paths in `applicationRoutes['{app}']` are RELATIVE to the application root.
+> They MUST include the module segment: `{module-kebab}/{section-kebab}`, NOT just `{section-kebab}`.
+> Without the module segment, the route resolves to `/{app}/{section}` instead of `/{app}/{module}/{section}`,
+> causing a mismatch with backend navigation seed data routes → nav links produce 404s.
 
 ```tsx
-// Section routes are nested inside the module's children array
-{ path: '{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
-{ path: '{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
-{ path: '{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
-{ path: '{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
+// Routes in applicationRoutes['human-resources'] — RELATIVE paths include module segment
+// IMPORTANT: static routes BEFORE dynamic routes (see Route Ordering rule above)
+// Example: app=human-resources, module=employee-management, section=employees
+{ path: '{module-kebab}/{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
+
+// Concrete example:
+// { path: 'employee-management/employees', element: ... },         → /human-resources/employee-management/employees ✅
+// { path: 'employees', element: ... },                             → /human-resources/employees ❌ WRONG (missing module)
 ```
 
 Section pages live in `src/pages/{AppPascal}/{Module}/{Section}/`.