@atlashub/smartstack-cli 3.32.0 → 3.34.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,209 @@ 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
+```
+
 **If ANY POST-CHECK fails → fix in step-03, re-validate.**

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

@@ -493,6 +493,12 @@ public class {Name}Controller : ControllerBase
 
 **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 +510,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 +525,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 +618,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 +648,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);
@@ -684,6 +723,7 @@ 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 |
 | FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |

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

@@ -325,7 +325,7 @@ export function EntityDetailPage() {
   useEffect(() => {
     if (!visitedTabsRef.current.has(activeTab)) {
       visitedTabsRef.current.add(activeTab);
-      // Load tab-specific data here
+      // Load tab-specific data here (e.g., fetch leaves for this employee)
     }
   }, [activeTab]);
 
@@ -336,6 +336,52 @@ export function EntityDetailPage() {
 }
 ```
 
+### Tab Behavior Rules (CRITICAL)
+
+> **CRITICAL: Tabs on detail pages switch content LOCALLY — they NEVER navigate to other pages.**
+> Each tab renders its content INLINE within the same page component.
+> Sub-resource data (e.g., an employee's leaves) loads via API call filtered by the parent entity ID.
+
+**Tab state management:**
+- Tabs use `useState<TabKey>('info')` for the active tab — LOCAL React state only
+- Tab click handler: `onClick={() => setActiveTab(tabKey)}` — NEVER `navigate()`
+- Tab content: conditional rendering `{activeTab === 'tabKey' && <TabContent />}`
+- Lazy loading: `visitedTabsRef` tracks which tabs have been visited to avoid redundant API calls
+
+**Tab content for sub-resources:**
+```tsx
+// CORRECT — sub-resource data loaded INLINE within the tab
+{activeTab === 'leaves' && (
+  <div>
+    <LeaveRequestsTable employeeId={entity.id} />
+    {/* Optional "View all" link INSIDE the tab content area */}
+    <Link to={`../leaves?employee=${entity.id}`}>
+      {t('employees:tabs.viewAllLeaves', 'View all leave requests')}
+    </Link>
+  </div>
+)}
+```
+
+**FORBIDDEN tab patterns:**
+```tsx
+// FORBIDDEN — tab click handler navigates to another page
+const handleTabClick = (tab: TabKey) => {
+  setActiveTab(tab);
+  if (tab === 'leaves') navigate(`../leaves?employee=${id}`);  // ← BREAKS tab UX
+};
+
+// FORBIDDEN — tab content is empty because navigation already left the page
+{activeTab === 'info' && <div>...</div>}
+// Leaves tab: nothing renders here, user is already on another page
+```
+
+**Why this matters:**
+- Navigating away loses the detail page context (entity data, scroll position, other tab state)
+- Users expect tabs to switch content in-place, not redirect to a different page
+- The browser back button should go to the list page, not toggle between tabs
+
+**POST-CHECK 43 enforces this rule.**
+
 ---
 
 ## 3b. Form Pages Pattern (Create / Edit)

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

@@ -101,6 +101,8 @@
 
 **Rules:**
 - `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- 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`
 - NEVER use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities
@@ -178,7 +180,7 @@ private static Guid GenerateDeterministicGuid(string input)
 
 | Level | Code (C#) | Route (DB) |
 |-------|-----------|-----------|
-| Application | `humanresources` | `/business/human-resources` |
+| Application | `human-resources` | `/business/human-resources` |
 | Module | `employees` | `/business/human-resources/employees` |
 | Section | `departments` | `/business/human-resources/employees/departments` |
 | Resource | `export` | `/business/human-resources/employees/departments/export` |

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

@@ -28,7 +28,7 @@ Extract flags from the raw input:
 ```
 Input: "{raw_input}"
 
-Flags to detect: -a, -x, -s, -e, -r, -pr
+Flags to detect: -a, -x, -s, -e, -r, -pr, -d {path}
 Remaining text after flag removal = {task_description}
 ```
 
@@ -41,6 +41,53 @@ save_mode: false
 economy_mode: false
 pr_mode: false
 resume_mode: false
+delegate_mode: false
+delegate_prd_path: null
+```
+
+**If `-d {path}` detected:** set `delegate_mode = true`, `delegate_prd_path = {path}`, force `auto_mode = true`, `economy_mode = true`.
+
+---
+
+## 1b. Delegate Mode Fast Path (if -d)
+
+> **When `/ralph-loop` invokes `/apex -d {prd_path}`, all context is extracted from the PRD file.**
+> Skip interactive sections (hierarchy definition, challenge questions).
+
+```
+IF delegate_mode:
+  Read prd.json from {delegate_prd_path}
+
+  Extract context:
+    {context_code}      = prd.project.context          (e.g., "business")
+    {app_name}          = prd.project.application       (e.g., "HumanResources")
+    {module_code}       = prd.project.module            (e.g., "EmployeeManagement")
+    {prd_path}          = {delegate_prd_path}
+    {feature_path}      = prd.source.feature_json_path  (if exists)
+
+  Extract sections from infrastructure tasks with _seedDataMeta:
+    Find task where _seedDataMeta.coreSeedData.navigationSections exists
+    {sections} = _seedDataMeta.coreSeedData.navigationSections[]
+    → map to: { code, label, description, route, displayOrder, navigation }
+
+  Extract entities from domain tasks:
+    {entities} = prd.tasks.filter(t => t.category == 'domain').map(t => entity name from t.description)
+
+  Extract complexity:
+    {module_complexity} = heuristic from task count:
+      <= 10 tasks → "simple-crud"
+      <= 20 tasks → "crud-rules"
+      <= 30 tasks → "crud-workflow"
+      > 30 tasks  → "complex"
+
+  Set needs:
+    {needs_seed_data}    = prd.tasks.some(t => t.category == 'seedData' || t.category == 'infrastructure')
+    {needs_migration}    = prd.tasks.some(t => t._migrationMeta != null)
+    {has_dependencies}   = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
+    {key_properties}     = [] (extracted during step-01 from feature.json if available)
+
+  SKIP sections 2 (detect context), 4 (hierarchy), 5 (challenge questions)
+  Jump to section 3 (MCP verify) → then section 6 (determine needs, already set) → section 9 (summary)
 ```
 
 ---

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

@@ -34,6 +34,43 @@ This saves ~2 minutes of Glob searches on an empty project.
 
 ---
 
+## 0b. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks provide pre-computed scope. Reduce exploration to verification only.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path} (already loaded in step-00)
+
+  1. Extract entity list from domain tasks:
+     entities[] = prd.tasks.filter(category == 'domain').map(entity name from description)
+
+  2. Extract FK relationships from frontend tasks with _frontendMeta:
+     fkFields[] = _frontendMeta.fkFields[] (e.g., ["DepartmentId→Department", "CompanyId→Company"])
+
+  3. Determine tenant modes per entity:
+     IF feature.json exists at {feature_path}:
+       Read entity definitions → extract tenantMode per entity
+     ELSE:
+       Default all entities to tenantMode: "strict"
+
+  4. Read feature.json for wireframes/componentMapping if {feature_path} exists:
+     → enriches frontend generation in step-03
+
+  5. Perform LIGHTWEIGHT code exploration (verification only):
+     - Glob("**/Domain/Entities/**/{module_code}/**/*.cs") → what already exists?
+     - Glob("**/Infrastructure/Persistence/Seeding/Data/**/*SeedData*.cs") → existing seed data?
+     - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
+     → Only to determine create vs modify vs skip (NOT deep analysis)
+
+  6. Gap Analysis: Mark all PRD tasks as "create" unless existing code found
+
+  SKIP: Full Agent Teams exploration (section 2), challenge question follow-up
+  Jump to section 5 (Gap Analysis summary) → section 7 (Analysis Summary)
+```
+
+---
+
 ## 1. Context Sources
 
 Read available context (in order of priority):

package/templates/skills/apex/steps/step-02-plan.md

@@ -16,6 +16,42 @@ Read `references/smartstack-layers.md` for layer execution rules and skill/MCP m
 
 ---
 
+## 0. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks already define the scope. Map directly to layers.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path}
+
+  Map each PRD task to a layer based on task.category:
+    domain          → Layer 0
+    infrastructure  → Layer 0
+    application     → Layer 1
+    api             → Layer 1
+    seedData        → Layer 1
+    frontend        → Layer 2
+    test            → Layer 3
+
+  For each task:
+    file_path    = task.files_changed.created[0] (primary file)
+    action       = "create" (default for delegate mode)
+    tool         = infer from category:
+                   domain/infrastructure → MCP scaffold_extension
+                   api → /controller skill or MCP scaffold_extension
+                   seedData → MCP generate_permissions + ref core-seed-data.md
+                   frontend → /ui-components skill + MCP scaffold_api_client + MCP scaffold_routes
+                   test → MCP scaffold_tests
+    acceptance_criteria = task.acceptance_criteria
+
+  Use task._seedDataMeta, _frontendMeta, _migrationMeta for enriched context.
+
+  SKIP: User checkpoint (section 6) — auto_mode implied
+  Jump to section 5 (Estimated Commits) → NEXT STEP
+```
+
+---
+
 ## 1. Map Changes to Layers
 
 For each element identified in step-01 (create or modify), assign to a SmartStack layer: