@atlashub/smartstack-cli 4.75.0 → 4.76.0

package/package.json

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

package/templates/skills/apex/SKILL.md

@@ -26,8 +26,8 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 /apex -e add status field to Project entity          # Economy (no agents)
 /apex -r                                             # Resume previous
 
-# From /sketch (vague idea → precise command):
-/sketch une app RH avec employés et absences         # → generates /apex command
+# From /business-analyse-quick (vague idea → Mini-PRD):
+/business-analyse-quick une app RH avec employés     # → generates PRD for /apex -d
 
 # From /business-analyse-develop (automated multi-module):
 # /business-analyse-develop delegates to /apex -d automatically

package/templates/skills/apex/references/checks/frontend-checks.sh

@@ -443,6 +443,32 @@ if [ -n "$APP_TSX" ]; then
   fi
 fi
 
+# POST-CHECK C64: ListPages must have Create/New button (BLOCKING)
+# Every ListPage must contain a navigate('create') or Link to="create" for the New button.
+# Without it, users cannot access the create form (broken CRUD workflow).
+# Note: C5 catches dead links (navigate exists but page missing). C64 catches missing buttons entirely.
+LIST_PAGES=$(find web/ src/pages/ -name "*ListPage.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\." | grep -v "\.spec\." || true)
+if [ -n "$LIST_PAGES" ]; then
+  FAIL_C64=false
+  for LP in $LIST_PAGES; do
+    # Skip dashboard-like list pages (no CRUD expected)
+    if echo "$LP" | grep -qiP "dashboard|calendar|approve|balance"; then
+      continue
+    fi
+    HAS_CREATE_NAV=$(grep -P "navigate\(.*['\"\`]create['\"\`]|navigate\(.*['\"\`].*\/create['\"\`]|to=['\"\`]create['\"\`]|to=\{.*create.*\}" "$LP" 2>/dev/null || true)
+    if [ -z "$HAS_CREATE_NAV" ]; then
+      echo "BLOCKING: ListPage missing Create/New button: $LP"
+      echo "  Every ListPage MUST have a 'New' button with navigate('create') in the page header."
+      echo "  Without it, users cannot access the create form — CRUD workflow is broken."
+      echo "  Fix: Add to page header: <button onClick={() => navigate('create')}>New</button>"
+      FAIL_C64=true
+    fi
+  done
+  if [ "$FAIL_C64" = true ]; then
+    FAIL=true
+  fi
+fi
+
 if [ "$FAIL" = true ]; then
   exit 1
 fi

package/templates/skills/apex/references/checks/seed-checks.sh

@@ -41,9 +41,6 @@ if [ -n "$APP_TSX" ] && [ -n "$SEED_ROUTES" ]; then
       SEED_NORM=$(echo "$SEED_SUFFIX" | tr '[:upper:]' '[:lower:]' | tr -d '-')
       MATCH_FOUND=false
       for FE_PATH in $FRONTEND_PATHS; do
-        if echo "$FE_PATH" | grep -qP '/list$'; then
-          echo "WARNING: Frontend route ends with /list — should use index route instead: $FE_PATH"
-        fi
         FE_BASE=$(echo "$FE_PATH" | sed 's|/list$||;s|/new$||;s|/:id.*||;s|/create$||')
         FE_NORM=$(echo "$FE_BASE" | tr '[:upper:]' '[:lower:]' | tr -d '-')
         if [ "$SEED_NORM" = "$FE_NORM" ]; then
@@ -174,14 +171,13 @@ if [ -n "$SECTION_SEED_FILES" ] && [ -n "$PERM_FILE" ]; then
   done
 fi
 
-# POST-CHECK C21: FORBIDDEN route patterns — /list and /detail/:id (WARNING)
+# POST-CHECK C21: FORBIDDEN route patterns — /detail/:id (WARNING)
 SEED_NAV_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*NavigationSeedData.cs" -o -name "*NavigationSectionSeedData.cs" 2>/dev/null)
 if [ -n "$SEED_NAV_FILES" ]; then
-  BAD_ROUTES=$(grep -Pn 'Route\s*=\s*.*"[^"]*/(list|detail)["/]' $SEED_NAV_FILES 2>/dev/null | grep -v '//.*Route' || true)
+  BAD_ROUTES=$(grep -Pn 'Route\s*=\s*.*"[^"]*/(detail)["/]' $SEED_NAV_FILES 2>/dev/null | grep -v '//.*Route' || true)
   if [ -n "$BAD_ROUTES" ]; then
     echo "WARNING: FORBIDDEN route pattern in seed data"
-    echo "  - 'list' section route = module route (NO /list suffix)"
-    echo "  - 'detail' section route = module route + /:id (NOT /detail/:id)"
+    echo "  - 'detail' is an implicit route — do NOT use /detail/:id as section route"
     echo "$BAD_ROUTES"
   fi
 fi
@@ -531,6 +527,50 @@ if [ "$HAS_GLOBAL_CONVERTER" = false ]; then
   fi
 fi
 
+# POST-CHECK C63: Reserved section codes must NOT be seeded as visible menu items (BLOCKING)
+# Reserved codes: detail, create, edit, *-detail
+# These are internal route targets resolved by DynamicRouter convention, NOT sidebar menu items.
+SEED_NAV_FILES=$(find src/ -path "*/Seeding/Data/*" \( -name "*NavigationSeedData.cs" -o -name "*NavigationModuleSeedData.cs" \) 2>/dev/null)
+if [ -n "$SEED_NAV_FILES" ]; then
+  for f in $SEED_NAV_FILES; do
+    for RESERVED in detail create edit; do
+      # Pattern A: SectionData record — new("detail", ...)
+      MATCHES=$(grep -Pn "new\s*\(\s*\"${RESERVED}\"" "$f" 2>/dev/null || true)
+      if [ -n "$MATCHES" ]; then
+        echo "BLOCKING: Reserved section code '${RESERVED}' seeded as menu item in $f"
+        echo "$MATCHES"
+        echo "  Reserved codes (detail, create, edit) are internal route targets, NOT sidebar menu items."
+        echo "  Fix: Remove this section entry. DynamicRouter resolves /:id, /create, /:id/edit by convention."
+        FAIL=true
+      fi
+      # Pattern B: NavigationSectionSeedEntry — Code = "detail"
+      MATCHES=$(grep -Pn "Code\s*=\s*\"${RESERVED}\"" "$f" 2>/dev/null || true)
+      if [ -n "$MATCHES" ]; then
+        # Check if IsActive = false is nearby (acceptable)
+        HAS_INACTIVE=$(grep -A 10 "Code\s*=\s*\"${RESERVED}\"" "$f" | grep -P "IsActive\s*=\s*false" 2>/dev/null || true)
+        if [ -z "$HAS_INACTIVE" ]; then
+          echo "BLOCKING: Reserved section code '${RESERVED}' seeded with IsActive=true in $f"
+          echo "$MATCHES"
+          echo "  Fix: Remove this section, or set IsActive = false."
+          FAIL=true
+        fi
+      fi
+    done
+    # Check for *-detail codes (e.g., department-detail)
+    DETAIL_SUFFIX=$(grep -Pn "new\s*\(\s*\"[a-z]+-detail\"" "$f" 2>/dev/null || true)
+    if [ -z "$DETAIL_SUFFIX" ]; then
+      DETAIL_SUFFIX=$(grep -Pn "Code\s*=\s*\"[a-z]+-detail\"" "$f" 2>/dev/null || true)
+    fi
+    if [ -n "$DETAIL_SUFFIX" ]; then
+      echo "BLOCKING: Section code with '-detail' suffix seeded as menu item in $f"
+      echo "$DETAIL_SUFFIX"
+      echo "  Detail routes are the /:id route of their parent section."
+      echo "  Fix: Remove this section entry. Use parent section's /:id route instead."
+      FAIL=true
+    fi
+  done
+fi
+
 if [ "$FAIL" = true ]; then
   exit 1
 fi

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

@@ -404,12 +404,11 @@ public static readonly Guid {ResourcePascal}ResourceId = Guid.NewGuid();
 
 ### Section Methods (add to {ModulePascal}NavigationSeedData.cs)
 
-> **ROUTE SPECIAL CASES (list and detail):**
-> The `list` and `detail` sections are view modes of the module, NOT functional sub-areas.
-> - `list` section route = module route (e.g., `/human-resources/employees`) — NO `/list` suffix
-> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
-> - Do not use: `/{module}/list`, `/{module}/detail/:id`
-> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
+> **ROUTE CONVENTION:**
+> ALL sections use a UNIFORM route pattern: module route + `/{section-code}`.
+> - `list` section route = module route + `/list` (e.g., `/human-resources/employees/list`)
+> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id` (detail is an implicit route, not a section)
+> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (same rule)
 
 ```csharp
 // --- Add AFTER GetTranslationEntries() in {ModulePascal}NavigationSeedData.cs ---
@@ -434,14 +433,18 @@ public static IEnumerable<NavigationSectionSeedEntry> GetSectionEntries(Guid mod
             Description = "{section1_desc_en}",
             Icon = "{section1_icon}",
             IconType = IconType.Lucide,
-            // ROUTE CONVENTION:
-            // - "list" section → same as module route (no extra segment)
-            // - "detail" section → module route + "/:id"
-            // - Other sections → module route + "/{section-kebab}"
-            // Do not use: "/employees/list", "/employees/detail/:id"
+            // ROUTE CONVENTION: ALL sections use module route + "/{section-code}" (uniform rule)
+            // - "list" section → module route + "/list" (e.g., /human-resources/employees/list)
+            // - Other sections → module route + "/{section-kebab}" (same rule)
+            // Implicit routes (detail, create, edit) are NOT sections — registered by DynamicRouter convention
             Route = "{section_route}",  // From seedDataCore.navigationSections[].route
             DisplayOrder = {section1_sort},
-            IsActive = true
+            // VISIBILITY RULE (MANDATORY):
+            // Reserved codes ("detail", "create", "edit") and codes containing "-detail"
+            // are internal route targets, NOT sidebar menu items.
+            // → IsActive = false for these codes (DynamicRouter resolves them by convention)
+            // → IsActive = true for all other sections (visible in sidebar menu)
+            IsActive = true  // Set to FALSE if section code is "detail", "create", "edit", or "*-detail"
         }
         // Repeat for each section...
     };
@@ -522,15 +525,14 @@ public static IEnumerable<NavigationResourceSeedEntry> GetResourceEntries(Guid s
         {
             // RESOURCE ROUTE CONVENTION:
             // Resources inherit their parent section's resolved route as base:
-            // - Under "list" section → base = module route (no /list)
-            // - Under "detail" section → base = module route (no /detail, resource routes don't include /:id)
+            // - Under "list" section → base = module route + /list
             // - Under other sections → base = module route + /{section-kebab}
             // Then append: /{resource-kebab}
             //
             // Example: resource "export" under section "dashboard":
             //   Route = /human-resources/employees/dashboard/export
             // Example: resource "employees-grid" under section "list":
-            //   Route = /human-resources/employees/employees-grid (NOT /employees/list/employees-grid)
+            //   Route = /human-resources/employees/list/employees-grid
             new NavigationResourceSeedEntry
             {
                 Id = {Resource1Pascal}ResourceId,
@@ -539,7 +541,7 @@ public static IEnumerable<NavigationResourceSeedEntry> GetResourceEntries(Guid s
                 Label = "{resource1_label_en}",
                 EntityType = "{resource1_entity}",
                 // Use parent section's resolved route + /{resource-kebab}
-                // For "list"/"detail" sections, the section route = module route (no /list or /detail segment)
+                // For "list" sections, route = module route + /list. "detail" is implicit (not a section).
                 Route = "{resource_route}",  // From seedDataCore: parent section route + /{resource-kebab}
                 DisplayOrder = 1
             }
@@ -591,10 +593,10 @@ public class NavigationResourceSeedEntry
 | `{section_label_xx}` | `specification.navigation.entries[]` where `level == "section"` → `labels.xx` |
 | `{section_icon}` | `seedDataCore.navigationSections[].icon` |
 | `{section_sort}` | `seedDataCore.navigationSections[].sort` |
-| `{section_route}` | `seedDataCore.navigationSections[].route` — **SPECIAL CASES:** `list` → module route (no `/list`), `detail` → module route + `/:id` (no `/detail/:id`), others → module route + `/{section-kebab}` |
+| `{section_route}` | `seedDataCore.navigationSections[].route` — ALL sections use uniform rule: module route + `/{section-code}` (`list` → module route + `/list`). `detail` is implicit (not a section): module route + `/:id`. |
 | `{resourceCode}` | `seedDataCore.navigationResources[].code` |
 | `{resource_entity}` | `seedDataCore.navigationResources[].entity` |
-| `{resource_route}` | Computed from parent section route + `/{resource-kebab}`. **SPECIAL CASES:** if parent section is `list` → module route + `/{resource-kebab}` (no `/list/`), if parent is `detail` → module route + `/{resource-kebab}` (no `/detail/`). |
+| `{resource_route}` | Computed from parent section route + `/{resource-kebab}`. For `list` parent → module route + `/list/{resource-kebab}`. For other parents → module route + `/{section-kebab}/{resource-kebab}`. |
 | `{parentSectionCode}` | `seedDataCore.navigationResources[].parentCode` |
 
 ---

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

@@ -75,6 +75,7 @@ bash references/checks/infrastructure-checks.sh
 | C37 | CRITICAL | Detail page tabs must NOT navigate() — content switches locally | frontend-checks.sh |
 | C49 | BLOCKING | Route Ordering in App.tsx — static before dynamic | frontend-checks.sh |
 | C52 | BLOCKING | Frontend route paths must include module segment | frontend-checks.sh |
+| C64 | BLOCKING | ListPages must have Create/New button (navigate to create route) | frontend-checks.sh |
 
 ### Seed Data — Navigation, Roles, Permissions (C1-C2, C10, C15-C23, C32-C35, C44-C48, C53)
 
@@ -89,7 +90,7 @@ bash references/checks/infrastructure-checks.sh
 | C18 | BLOCKING | Permissions.cs static constants must exist | seed-checks.sh |
 | C19 | BLOCKING | ApplicationRolesSeedData.cs must exist | seed-checks.sh |
 | C20 | WARNING | Section route completeness (NavigationSection → frontend route + permissions) | seed-checks.sh |
-| C21 | WARNING | FORBIDDEN route patterns — /list and /detail/:id | seed-checks.sh |
+| C21 | WARNING | FORBIDDEN route patterns — /detail/:id | seed-checks.sh |
 | C22 | WARNING | Permission path segment count (2-4 dots expected) | seed-checks.sh |
 | C23 | BLOCKING | IClientSeedDataProvider must have 4 methods with real implementation (not stubs) + DI registration | seed-checks.sh |
 | C32 | CRITICAL | Translation seed data must have idempotency guard | seed-checks.sh |
@@ -104,6 +105,7 @@ bash references/checks/infrastructure-checks.sh
 | C53 | BLOCKING | Enum serialization — JsonStringEnumConverter required | seed-checks.sh |
 | C57 | BLOCKING | SeedDataProvider Seed*Async methods must NOT be `return Task.CompletedTask` or empty body — stubs cause empty menu | seed-checks.sh |
 | C58 | BLOCKING | File paths in filesToCreate must be valid C# identifiers — no spaces, apostrophes, or accents | seed-checks.sh |
+| C63 | BLOCKING | Reserved section codes (detail/create/edit/*-detail) must NOT be seeded as menu items | seed-checks.sh |
 
 ### Architecture — Clean Architecture Layer Isolation (A1-A8)
 
@@ -135,6 +137,21 @@ bash references/checks/infrastructure-checks.sh
 | C60 | BLOCKING | Controllers must inject ISender _mediator, NOT direct business services | infrastructure-checks.sh |
 | C61 | BLOCKING | Controllers with [NavRoute] must have [Authorize] attribute | infrastructure-checks.sh |
 
+### PRD Compliance — Delegate Mode Only (PC-1 to PC-6)
+
+> **These checks run ONLY in delegate mode** (when `/apex -d` is used with companion spec files).
+> They validate that generated code matches the PRD specifications from `.ralph/` companion files.
+> Implemented in `step-04-examine.md` section 6d — no separate .sh script needed.
+
+| ID | Severity | Description | Source |
+|----|----------|-------------|--------|
+| PC-1 | BLOCKING | All columns from screens.json SmartTable resources must exist in generated ListPage | step-04 §6d |
+| PC-2 | BLOCKING | All actions from screens.json (create, edit, delete, approve, reject, export) must have handlers in pages | step-04 §6d |
+| PC-3 | WARNING | I18n labels must have correct UTF-8 accents (FR: Employés not Employes, DE: Übersicht not Ubersicht) | step-04 §6d |
+| PC-4 | BLOCKING | All permissionPaths from permissions.json must exist in PermissionsSeedData.cs and Permissions.cs | step-04 §6d |
+| PC-5 | WARNING | Every primary/functional section in screens.json must have a corresponding page file | step-04 §6d |
+| PC-6 | WARNING | Module i18n namespace must be registered in i18n config (prevents raw key display) | step-04 §6d |
+
 ---
 
 ## Summary

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

@@ -343,10 +343,10 @@ public class {Name}Controller : ControllerBase
 | Module | `/{app-kebab}/{module-kebab}` | `/human-resources/employees` |
 | Section | `/{app-kebab}/{module-kebab}/{section-kebab}` | `/human-resources/employees/departments` |
 
-**Route special cases:** `list` and `detail` sections are view modes, NOT sub-areas:
-- `list` route = module route (e.g., `/human-resources/employees`)
-- `detail` route = module route + `/:id`
-- Do NOT use: `/employees/list`, `/employees/detail/:id`
+**Route convention:** ALL sections use uniform route = module route + `/{section-code}`:
+- `list` route = module route + `/list` (e.g., `/human-resources/employees/list`)
+- `detail` is an implicit route (not a section): module route + `/:id`
+- Do NOT use: `/employees/detail/:id` (detail is implicit)
 
 **Rules:**
 - Routes ALWAYS start with `/`, include full hierarchy, use kebab-case

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

@@ -256,7 +256,7 @@ const applicationRoutes: ApplicationRouteExtensions = {
 };
 ```
 
-**Section-level routes:** `list` and `detail` do NOT add path segments (handled by `index: true` and `:id`). Only other sections (dashboard, approve, import) add `{section-kebab}` child routes.
+**Section-level routes:** ALL sections add their code as path segment (`list` → `/list`, `dashboard` → `/dashboard`, `approve` → `/approve`). `detail`/`create`/`edit` are implicit routes (`/:id`, `/create`, `/:id/edit`), NOT sections.
 
 **PermissionGuard for sections:**
 ```tsx

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

@@ -175,12 +175,12 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 // → "/human-resources/employees/departments"
 ```
 
-**Route special cases (list and detail sections):**
-> `list` and `detail` are view modes of the module, NOT functional sub-areas.
-> - `list` section route = module route (e.g., `/human-resources/employees`) — NO `/list` suffix
-> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
-> - Do not use: `/employees/list`, `/employees/detail/:id`
-> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
+**Route convention:**
+> ALL sections use a UNIFORM route pattern: module route + `/{section-code}`.
+> - `list` section route = module route + `/list` (e.g., `/human-resources/employees/list`)
+> - `detail` is an implicit route (not a section): module route + `/:id` (e.g., `/human-resources/employees/:id`)
+> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (same rule)
+> - Do NOT use: `/employees/detail/:id` (detail is implicit, not a section code)
 
 **Do not:**
 - Use deterministic/sequential/fixed GUIDs — always use `Guid.NewGuid()`

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

@@ -164,7 +164,7 @@ IF precision_score < 2:
   ║  Your request looks more like a discovery/design task.      ║
   ║                                                             ║
   ║  Suggestions:                                               ║
-  ║  1. Use /sketch to quickly design your module (~2 min)      ║
+  ║  1. Use /business-analyse-quick to design your module       ║
   ║  2. Use /business-analyse for full analysis (40+ questions) ║
   ║  3. Rewrite your prompt with entities and fields, e.g.:     ║
   ║     /apex add employees section with Employee entity        ║

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -100,6 +100,32 @@ IF existing_seed_files is NOT EMPTY:
 
 ---
 
+### Reserved Section Code Guard (MANDATORY — runs before ANY section seeding)
+
+> **CRITICAL RULE:** Reserved section codes must NOT be seeded as menu-visible sections.
+
+```
+RESERVED_SECTION_CODES = ["detail", "create", "edit"]
+
+For each section in {sections} (from PRD or entity_section_map):
+  IF section.code IN RESERVED_SECTION_CODES OR section.code contains "-detail":
+    → Do NOT seed this section in NavigationSeedData at all
+    → "detail" is the /:id route of its parent list section (DynamicRouter convention)
+    → "create" is the /create route (DynamicRouter convention)
+    → "edit" is the /:id/edit route (DynamicRouter convention)
+    → "*-detail" (e.g., "department-detail") is the /:id route of its parent section
+    → Set permissionMode = "inherit" (no dedicated permissions)
+    → LOG: "Skipped reserved section '{section.code}' — resolved by DynamicRouter convention"
+
+  ELSE:
+    → Seed normally with IsActive = true
+
+In delegate mode (-d): PRD data may contain reserved codes that were not challenged.
+This guard catches them regardless of mode.
+```
+
+---
+
 ### Per-Module Seed Data (CREATE or UPDATE)
 
 #### If SEED_MODE = "CREATE"

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -41,6 +41,108 @@ if (delegate_mode && specification_loading_plan) {
 > - **Dashboard pages**: use `screen.kpis[]` for KPI card and chart definitions
 > - **Actions**: use `screen.actions[]` for action buttons (create, export, bulk operations)
 
+### Build Per-Entity PRD Context Block (delegate mode)
+
+> **CRITICAL:** This block builds the authoritative specification that MUST be passed to `/ui-components`.
+> Without it, `/ui-components` infers columns from entity structure and misses PRD-specified fields
+> (e.g., Person Extension Pattern display fields like DisplayFirstName, DisplayLastName).
+
+When companion specs are loaded, build a `{prd_context}` map keyed by entity name:
+
+```javascript
+const prdContextMap = {};  // entityName → structured PRD block
+
+if (screensData?.sections) {
+  for (const section of screensData.sections) {
+    for (const resource of (section.resources || [])) {
+      if (!resource.entity) continue;
+      const entityName = resource.entity;
+
+      if (!prdContextMap[entityName]) {
+        prdContextMap[entityName] = { screens: [], labels: {}, permissions: [] };
+      }
+
+      // Collect screen resource specs
+      prdContextMap[entityName].screens.push({
+        sectionCode: section.code,
+        sectionType: section.sectionType,
+        resourceType: resource.type,
+        columns: resource.columns || null,
+        fields: resource.fields || null,
+        actions: resource.actions || [],
+        defaultSort: resource.defaultSort || null,
+        defaultPageSize: resource.defaultPageSize || 20
+      });
+
+      // Collect section labels (4 languages)
+      if (section.labels) {
+        prdContextMap[entityName].labels[section.code] = section.labels;
+      }
+
+      // Collect permissions
+      if (section.permission) {
+        prdContextMap[entityName].permissions.push(section.permission);
+      }
+    }
+  }
+}
+```
+
+Then, for each entity, serialize the PRD context into a text block to inject into `/ui-components`:
+
+```javascript
+function buildPrdBlock(entityName) {
+  const ctx = prdContextMap[entityName];
+  if (!ctx || ctx.screens.length === 0) return '';
+
+  let block = '\n--- PRD SPECIFICATION (AUTHORITATIVE — use these EXACT definitions) ---\n';
+
+  // SmartTable columns
+  const tableScreens = ctx.screens.filter(s => s.resourceType === 'SmartTable' && s.columns);
+  for (const screen of tableScreens) {
+    block += `\nCOLUMNS for DataTable (section: "${screen.sectionCode}") — use ALL, in this EXACT order:\n`;
+    for (const col of screen.columns) {
+      block += `  - key: "${col.field}", label_fr: "${col.label?.fr || col.field}", ` +
+               `label_en: "${col.label?.en || col.field}", format: "${col.format}", ` +
+               `sortable: ${col.sortable || false}\n`;
+    }
+    if (screen.actions.length > 0) {
+      block += `ACTIONS: ${screen.actions.join(', ')}\n`;
+    }
+    if (screen.defaultSort) {
+      block += `DEFAULT SORT: field="${screen.defaultSort.field}", direction="${screen.defaultSort.direction}"\n`;
+    }
+    block += `PAGE SIZE: ${screen.defaultPageSize}\n`;
+  }
+
+  // SmartForm fields
+  const formScreens = ctx.screens.filter(s => s.resourceType === 'SmartForm' && s.fields);
+  for (const screen of formScreens) {
+    block += `\nFORM FIELDS (section: "${screen.sectionCode}"):\n`;
+    for (const field of screen.fields) {
+      block += `  - name: "${field.name}", type: "${field.type}", required: ${field.required || false}\n`;
+    }
+  }
+
+  // Labels
+  block += '\nSECTION LABELS (use for page titles, breadcrumbs, i18n — 4 languages):\n';
+  for (const [code, labels] of Object.entries(ctx.labels)) {
+    block += `  ${code}: fr="${labels.fr}" en="${labels.en}" it="${labels.it}" de="${labels.de}"\n`;
+  }
+
+  // Permissions
+  if (ctx.permissions.length > 0) {
+    block += `\nPERMISSIONS: ${ctx.permissions.join(', ')}\n`;
+  }
+
+  block += '--- END PRD SPECIFICATION ---\n';
+  return block;
+}
+```
+
+**Usage:** When invoking `Skill("ui-components")`, append `buildPrdBlock(entityName)` to the arguments.
+The `/ui-components` skill reads free-text instructions — the structured block is parsed naturally.
+
 ### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)
 
 > **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
@@ -130,6 +232,15 @@ For each module:
   → Create{Section}Page.tsx (/create route)
   → Edit{Section}Page.tsx (/:id/edit route)
   "detail" is NEVER a separate section — it's the /:id route of the list section.
+- **CRUD Page Completeness (MANDATORY for every entity section with a ListPage):**
+  1. ALL 4 page types MUST exist (List, Detail, Create/Form, Edit/Form)
+  2. **Create button on ListPage (MANDATORY):** Every ListPage MUST include a "New" / "Create" button
+     in the header that calls `navigate('create')`. Without this button, users cannot access the create form.
+  3. **componentRegistry registration:** ALL page types MUST be registered via `PageRegistry.register()`.
+     After `scaffold_routes`, verify the registry contains keys for ALL pages.
+     If form pages (create/edit) are missing from registry, add them manually.
+  4. **POST-CHECK Gate PG-2b:** Grep every `*ListPage.tsx` for `navigate.*create`.
+     If absent → BLOCKING error — add the create button before proceeding.
 - Pages: **MANDATORY — INVOKE Skill("ui-components")** for ALL page generation.
   ⚠ BLOCKING REQUIREMENT: You MUST call Skill("ui-components") for EVERY page (.tsx).
   NEVER generate .tsx page code directly. NEVER write page content in Agent prompts.
@@ -245,13 +356,17 @@ IF NOT economy_mode AND entities.length > 1:
   # PHASE B — Sequential: pages via /ui-components (principal agent)
   # Snipper agents cannot call Skill() — only the principal agent can.
   For each entity (sequentially):
-    **INVOKE Skill("ui-components")** — pass entity context:
+    **INVOKE Skill("ui-components")** — pass entity context + PRD spec:
       - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
       - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)
       - "CSS: Use CSS variables ONLY — bg-[var(--bg-card)], text-[var(--text-primary)]"
       - "Forms: Create/Edit are FULL PAGES with own routes (/create, /:id/edit)"
       - "FK FIELDS: EntityLookup for ALL FK Guid fields"
       - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+      - {buildPrdBlock(EntityName)} — append the PRD specification block from companion specs
+      - "COLUMNS ARE AUTHORITATIVE: Do NOT infer columns from entity attributes. Use ALL columns from the PRD SPECIFICATION block above, in the EXACT order listed. Do NOT add, remove, or reorder columns."
+      - "LABELS ARE AUTHORITATIVE: Use PRD SECTION LABELS for i18n t() fallback text and page titles. Do NOT invent labels."
+      - "ACTIONS ARE AUTHORITATIVE: Implement ALL action buttons listed in the PRD SPECIFICATION (create, edit, delete, approve, reject, export, etc.)."
     Generate form tests: co-located .test.tsx for Create and Edit pages
 
 ELSE:
@@ -263,12 +378,16 @@ ELSE:
     2. MCP scaffold_routes (outputFormat: 'componentRegistry')
     3. Verify PageRegistry registration (componentRegistry.generated.ts)
        No manual App.tsx wiring needed — DynamicRouter resolves at runtime
-    4. **INVOKE Skill("ui-components")** — pass entity context:
+    4. **INVOKE Skill("ui-components")** — pass entity context + PRD spec:
        - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
        - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)
        - "CSS: Use CSS variables ONLY — bg-[var(--bg-card)], text-[var(--text-primary)]"
        - "Forms: Create/Edit are FULL PAGES with own routes (/create, /:id/edit)"
        - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+       - {buildPrdBlock(EntityName)} — append the PRD specification block from companion specs
+       - "COLUMNS ARE AUTHORITATIVE: Do NOT infer columns from entity attributes. Use ALL columns from the PRD SPECIFICATION block above, in the EXACT order listed."
+       - "LABELS ARE AUTHORITATIVE: Use PRD SECTION LABELS for i18n t() fallback text."
+       - "ACTIONS ARE AUTHORITATIVE: Implement ALL action buttons listed in the PRD SPECIFICATION."
     5. I18n: 4 JSON files (fr, en, it, de) + register namespace in i18n config
     6. Form tests: co-located .test.tsx for Create and Edit pages
 ```
@@ -300,6 +419,9 @@ When delegating to `/ui-components` skill, include explicit instructions:
 - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`)."
 - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
 - "Hooks: MUST use apiClient from @/services/api — NEVER raw fetch() or direct axios import."
+- "PRD COLUMNS: If a `--- PRD SPECIFICATION ---` block is present, use its columns[] as the EXACT DataTable columns. Do NOT add, remove, or reorder. Do NOT infer columns from entity attributes — the PRD is the source of truth."
+- "PRD LABELS: If a `--- PRD SPECIFICATION ---` block is present, use its SECTION LABELS for page titles and i18n fallback text in all 4 languages."
+- "PRD ACTIONS: If a `--- PRD SPECIFICATION ---` block lists actions (approve, reject, export, etc.), generate the corresponding buttons and handlers."
 
 ### ⛔ POST-GENERATION VERIFICATION GATES (MANDATORY — run after ALL pages are created)