@atlashub/smartstack-cli 4.26.0 → 4.28.0

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,12 +309,41 @@ 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: `''` or `'{section}'`)
+2. Create route (`'{section}/create'`)
+3. Static sections (`'{section}/dashboard'`, `'{section}/departments'`, etc.)
+4. Dynamic routes (`'{section}/:id'`, `'{section}/:id/edit'`)
+5. Redirect routes (`Navigate`) — ALWAYS LAST
+
+```tsx
+// ✅ CORRECT — static before dynamic
+{ path: 'employees', element: <EmployeesPage /> },
+{ path: 'employees/create', element: <CreateEmployeePage /> },
+{ path: 'employees/dashboard', element: <EmployeeDashboardPage /> },
+{ path: 'employees/:id', element: <EmployeeDetailPage /> },
+{ path: 'employees/:id/edit', element: <EditEmployeePage /> },
+{ path: '', element: <Navigate to="employees" replace /> },
+
+// ❌ WRONG — :id before dashboard → dashboard is unreachable (matched as id="dashboard")
+{ path: 'employees/:id', element: <EmployeeDetailPage /> },
+{ path: '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:
 
 ```tsx
 // Section routes are nested inside the module's children array
+// IMPORTANT: static routes BEFORE dynamic routes (see Route Ordering rule above)
 { 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> },

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

@@ -108,6 +108,15 @@ Verify the plan respects dependencies:
 - Build gate between EVERY layer (must pass): Layer 0 → 1 → 2 → 3 → 4
 ```
 
+### 4b. Module Code Collision Guard (BLOCKING)
+
+```
+IF appCode == moduleCode:
+  BLOCK — module_code identique à app_code cause des segments doublés (e.g. /hr/hr).
+  Suggestion : "{appCode}-core", "{appCode}-management"
+  ASK user pour un module_code différent.
+```
+
 ---
 
 ## 5. Estimated Commits

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

@@ -290,6 +290,57 @@ When launching agents for multi-entity layers:
 - Agent principal updates activeForm after each entity completion:
   `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
 
+### Controller NavRoute Attribute (MANDATORY)
+
+After controller generation, verify `[NavRoute]` attribute is present on every controller:
+- Expected: `[NavRoute("{app_name}.{module_code}.{section_code}")]` on the controller class
+- If missing: Add it manually above `[Authorize]`
+- When calling `scaffold_extension(type: "controller")`, always pass `navRoute` in options
+- This is REQUIRED for `scaffold_routes` to auto-detect routes in Layer 3
+
+### Guard: NavRoute Uniqueness and Segment Count (MANDATORY)
+
+**BEFORE proceeding past Layer 2**, verify for EACH controller:
+
+1. **Unique NavRoute:** No two controllers may share the same `[NavRoute("...")]` value. Duplicate NavRoutes cause routing conflicts → 404s on one of the controllers.
+
+2. **Segment count matches hierarchy:** Count the dots in the NavRoute value:
+   - 1 dot = 2 segments (module-level, e.g., `human-resources.employees`) — controller is at `Controllers/{App}/`
+   - 2 dots = 3 segments (section-level, e.g., `human-resources.employees.contracts`) — controller is at `Controllers/{App}/{Module}/` or in a section subfolder
+   - **If a controller is in a section subfolder** (e.g., `Controllers/{App}/Employees/ContractsController.cs`) **but has only 2 segments** → the API route will be wrong → 404. It MUST have 3 segments.
+   - 0 dots = INVALID → BLOCK
+
+```bash
+# Quick validation
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+for f in $CTRL_FILES; do
+  NAVROUTE=$(grep -oP '\[NavRoute\("\K[^"]+' "$f")
+  if [ -n "$NAVROUTE" ]; then
+    DOTS=$(echo "$NAVROUTE" | tr -cd '.' | wc -c)
+    if [ "$DOTS" -eq 0 ]; then
+      echo "BLOCKING: NavRoute '$NAVROUTE' has only 1 segment (need minimum 2): $f"
+      exit 1
+    fi
+    # Check if controller is in a section subfolder but NavRoute has only 2 segments
+    DEPTH=$(echo "$f" | grep -oP 'Controllers/[^/]+/[^/]+/' | wc -l)
+    if [ "$DEPTH" -gt 0 ] && [ "$DOTS" -eq 1 ]; then
+      echo "WARNING: Controller in section subfolder but NavRoute has only 2 segments: $f"
+      echo "  NavRoute: $NAVROUTE — expected 3 segments (app.module.section)"
+    fi
+  fi
+done
+```
+
+```bash
+# Quick check: all controllers must have [NavRoute] (not just [Route])
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+for f in $CTRL_FILES; do
+  if ! grep -q "\[NavRoute" "$f" && grep -q "\[Route" "$f"; then
+    echo "WARNING: $f has [Route] but no [NavRoute] — add [NavRoute] for route auto-detection"
+  fi
+done
+```
+
 ### Post-Layer 2 Build Gate
 
 ```bash
@@ -368,16 +419,31 @@ TaskUpdate(taskId: progress_tracker_id,
 
 For each module:
 - API client: MCP scaffold_api_client
-- Routes: MCP scaffold_routes (outputFormat: 'applicationRoutes') → generates lazy imports + Suspense
+- Routes — TWO mandatory steps:
+  1. Generate registry: MCP scaffold_routes (source: 'controllers', outputFormat: 'applicationRoutes', dryRun: false)
+     → Creates navRoutes.generated.ts (required by POST-CHECK C2)
+  2. Wire to App.tsx (see below)
 - Wire Routes to App.tsx: After scaffold_routes, routes must be wired into App.tsx:
   → Read App.tsx and detect the routing pattern
   → Pattern A (`applicationRoutes: ApplicationRouteExtensions`): add routes to `applicationRoutes['{application_kebab}'][]` with RELATIVE paths
   → Pattern B (JSX `<Route>`): nest routes inside `<Route path="/{application}" element={<AppLayout />}>` + duplicate in tenant block
+  → **BEFORE wiring:** Verify route ordering — static routes (`create`, `dashboard`, `departments`) MUST come BEFORE dynamic routes (`:id`, `:id/edit`). Redirect routes (`Navigate`) MUST be LAST. See `references/smartstack-layers.md` "RULE — Frontend Route Ordering".
   → Do not add business routes to `clientRoutes[]` — it is only for non-app routes (`/about`, `/pricing`)
   → All business applications use `<AppLayout />` as layout wrapper
   → See `references/frontend-route-wiring-app-tsx.md` for full Pattern A/B detection and examples
   → Verify: `mcp__smartstack__validate_frontend_routes (scope: 'routes')`
-- Pages: use /ui-components skill — follow smartstack-frontend.md patterns:
+- Pages per section: When a section exists (e.g., "list"), generate ALL 4 page types:
+  → {Section}ListPage.tsx (index route)
+  → {Section}DetailPage.tsx (/:id route) — click on list item navigates here
+  → 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.
+- 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.
+  NEVER use Write tool to create pages without first calling Skill("ui-components").
+  The skill loads the full style guide + patterns (entity-card, data-table, dashboard-chart, grid-layout).
+  Follow smartstack-frontend.md patterns:
   → React.lazy() for all page imports (named export wrapping)
   → `<Suspense fallback={<PageLoader />}>` around all lazy components
   → Page structure: hooks → useEffect(load) → loading → error → content
@@ -451,7 +517,7 @@ IF NOT economy_mode AND entities.length > 1:
       prompt='Execute Layer 3 frontend for {EntityName}:
         **MANDATORY: Read references/smartstack-frontend.md FIRST**
         - API client: MCP scaffold_api_client
-        - Routes: MCP scaffold_routes (outputFormat: "applicationRoutes")
+        - Routes: MCP scaffold_routes (outputFormat: "applicationRoutes", dryRun: false) → MUST generate navRoutes.generated.ts
         - Wire Routes to App.tsx (BLOCKING): detect Pattern A/B, wire accordingly
           → See references/frontend-route-wiring-app-tsx.md for full patterns
           → Verify: mcp__smartstack__validate_frontend_routes (scope: "routes")
@@ -466,7 +532,21 @@ IF NOT economy_mode AND entities.length > 1:
   # All agents launched in parallel
 
 ELSE:
-  # Agent principal handles all entities sequentially
+  # Economy mode: Agent principal handles all entities SEQUENTIALLY.
+  # MANDATORY: You MUST still call Skill("ui-components") for page generation.
+  # economy_mode only disables parallel agents — it does NOT skip /ui-components.
+  For each entity (sequentially):
+    1. MCP scaffold_api_client
+    2. MCP scaffold_routes (outputFormat: 'applicationRoutes')
+    3. Wire routes to App.tsx (Pattern A/B — see references/frontend-route-wiring-app-tsx.md)
+    4. **INVOKE Skill("ui-components")** — pass entity context:
+       - 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')"
+    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
 ```
 
 ### Parallel Agents + TaskCreate Integration
@@ -495,6 +575,24 @@ 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/`."
 
+### HARD RULE — /ui-components is NON-NEGOTIABLE
+
+> **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
+> a prior Skill("ui-components") call in this execution, the frontend layer is INVALID.
+>
+> **You MUST NOT:**
+> - Generate .tsx page code in Agent prompts and dispatch to Snipper agents
+> - Write page content directly via the Write tool
+> - Copy-paste page templates from your knowledge
+>
+> **You MUST:**
+> - Call Skill("ui-components") which loads the style guide, responsive guidelines,
+>   accessibility rules, and pattern files (entity-card, data-table, dashboard-chart, grid-layout, kanban)
+> - Let /ui-components generate all pages with correct conventions
+>
+> **Why this matters:** Without the skill, pages miss CSS variables, DataTable/EntityCard,
+> memo()/useCallback, responsive mobile-first design, and accessibility patterns.
+
 ### Frontend Tests Inline
 
 > **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**

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

@@ -69,6 +69,39 @@ const applicationRoutes: ApplicationRouteExtensions = {
 
 Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
 
+#### RULE — Route Ordering in applicationRoutes
+
+> **CRITICAL:** Routes within each application key MUST follow static-before-dynamic order.
+> React Router matches top-to-bottom — a `:id` route placed before a `dashboard` route
+> will match `dashboard` as an `id` parameter → 404.
+
+```tsx
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [
+    // ✅ CORRECT ORDER — static before dynamic
+    { path: 'employees', element: <EmployeesPage /> },
+    { path: 'employees/create', element: <CreateEmployeePage /> },
+    { path: 'employees/dashboard', element: <EmployeeDashboardPage /> },
+    { path: 'employees/:id', element: <EmployeeDetailPage /> },
+    { path: 'employees/:id/edit', element: <EditEmployeePage /> },
+
+    // Redirect routes ALWAYS LAST
+    { path: '', element: <Navigate to="employees" replace /> },
+  ],
+};
+```
+
+```tsx
+// ❌ FORBIDDEN — :id before static routes
+'human-resources': [
+  { path: 'employees/:id', element: <EmployeeDetailPage /> },      // ← WRONG: catches 'dashboard'
+  { path: 'employees/dashboard', element: <DashboardPage /> },      // ← NEVER REACHED
+]
+```
+
+See `smartstack-layers.md` "RULE — Frontend Route Ordering" for the full ordering specification.
+POST-CHECK C49 detects and BLOCKS this anti-pattern.
+
 #### Custom Applications (Pattern A)
 
 Custom application keys (any key **not** in the built-in list: `administration`, `support`, `user`, `api`) are fully supported in `applicationRoutes`. `mergeRoutes()` automatically:

package/templates/skills/business-analyse/references/consolidation-structural-checks.md

@@ -89,6 +89,21 @@ FOR each entity in analysis.entities[]:
   IF endpoints.length === 0 -> ERROR: "Entity {entity.name} has NO endpoints — missing controller"
 ```
 
+## H. Permission Granularity Check
+
+> Validates that section permission modes are respected in the generated permission data.
+
+```
+FOR each module:
+  FOR each section in anticipatedSections[]:
+    IF section.sectionType == "view" OR section.permissionMode == "inherit":
+      IF section has own permissions in seedDataCore.permissions[] -> WARNING: "Section '{code}' is type 'view' but has own permissions — should inherit from module"
+    IF section.permissionMode == "read-only":
+      IF section has create/update/delete permissions -> ERROR: "Section '{code}' is read-only but has write permissions"
+    IF section.sectionType == "primary" AND NOT section.permissionMode:
+      -> WARNING: "Primary section '{code}' missing explicit permissionMode — defaulting to 'crud'"
+```
+
 ## Result Aggregation
 
 ```json
@@ -100,6 +115,8 @@ FOR each entity in analysis.entities[]:
     { "check": "id-uniqueness", "module": "...", "status": "PASS|ERROR", "details": "..." },
     { "check": "wireframe-layout", "module": "...", "status": "PASS|ERROR", "details": "..." },
     { "check": "seeddata-translations", "module": "...", "status": "PASS|ERROR", "details": "..." }
+    ,
+    { "check": "permission-granularity", "module": "...", "status": "PASS|WARNING|ERROR", "details": "..." }
   ]
 }
 ```

package/templates/skills/business-analyse/references/spec-auto-inference.md

@@ -34,13 +34,18 @@
 
 > **RULE:** Sections = functional zones only. `create`/`edit` are separate pages with own URL routes (`/create` and `/:id/edit`). `detail` is a tabbed page reached from `list`.
 
-| featureType | Sections (functional zones) | List page includes | Form pages | Detail page tabs |
-|---|---|---|---|---|
-| data-centric | list | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations} |
-| workflow | list, approve | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
-| integration | list | grid, filters, config button | `/create` page, `/:id/edit` page | Infos, Config, Logs |
-| reporting | dashboard | — | — | — |
-| full-module | list, dashboard | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| featureType | Sections (functional zones) | permissionMode | List page includes | Form pages | Detail page tabs |
+|---|---|---|---|---|---|
+| data-centric | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations} |
+| data-centric | (detail — implicit) | `inherit` | — | — | — |
+| workflow | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| workflow | approve | `custom:approve,reject` | — | — | — |
+| integration | list | `crud` | grid, filters, config button | `/create` page, `/:id/edit` page | Infos, Config, Logs |
+| reporting | dashboard | `read-only` | — | — | — |
+| full-module | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| full-module | dashboard | `read-only` | — | — | — |
+
+> **RULE:** `detail` is NEVER a section with its own permission set. It is always `sectionType: view`, `permissionMode: inherit`. Detail pages inherit permissions from their parent module.
 
 ## Component Generation Rules
 

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -357,13 +357,12 @@ IF workflow_mode = "project":
   })
 
   Output path: docs/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/business-analyse/v{version}/*.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
     - cadrage.json
     - validation.json
     - consolidation.json
-    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
-    // They are created by step-03 (specify) in each module directory.
-    // Do NOT create them at project/app level — empty files mislead downstream tools.
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at project level is a BLOCKING ERROR.
 
   Store:
     project_id: string  // PROJ-NNN
@@ -394,18 +393,29 @@ ELSE:
   })
 
   Output path: docs/{app}/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/{app}/business-analyse/v{version}/*.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
     - cadrage.json
     - validation.json
-    - handoff.json
-    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
-    // They are created by step-03 (specify) in each module directory.
-    // Do NOT create them at app level — empty files mislead derive-prd and ralph-loop.
+    - consolidation.json
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at application level is a BLOCKING ERROR.
 ```
 
 > **Note:** In project mode, per-application index.json files are created later in step-01-cadrage.
 > In single-app mode, step-02 (structure) determines if it's single or multi-module.
 
+### POST-CREATE VERIFICATION (MANDATORY)
+
+After creating thematic files, verify no forbidden files were created:
+
+```
+List all *.json files in {docs_dir}/
+Expected (project/application): [index.json, cadrage.json, validation.json, consolidation.json]
+If any file NOT in expected list is found → DELETE it immediately + log WARNING
+```
+
+This guard catches any accidental creation of module-only files at the wrong scope.
+
 ## Step 10: Update Config
 
 Update `.business-analyse/config.json` with new feature information.

package/templates/skills/business-analyse/steps/step-02-structure.md

@@ -72,16 +72,27 @@ For each module, anticipate the navigation structure:
 For each section:
   - code (kebab-case, e.g., "list", "detail", "dashboard")
   - label (display name)
+  - sectionType: primary | functional | view | embedded
+  - permissionMode: crud | custom | read-only | inherit
   - resources: [
       { code, type (SmartTable|SmartForm|SmartCard|SmartKanban|SmartDashboard|SmartFilter), label }
     ]
 ```
 
+**Section classification rules:**
+
+| sectionType | permissionMode | When to use | Examples |
+|---|---|---|---|
+| `primary` | `crud` | Main entry point of the module, visible in menu | list |
+| `functional` | `crud` or `custom` | Independent functional zone with own access control | approve, import, planning |
+| `view` | `inherit` | Subordinate view reached from a primary section | detail, edit |
+| `embedded` | `read-only` | Widget or tab embedded in another section | dashboard (when embedded in module) |
+
 Common patterns:
-- **Data-centric module**: list (SmartTable) + detail (SmartForm)
-- **Workflow module**: list + detail + kanban (SmartKanban)
-- **Reporting module**: dashboard (SmartDashboard) + detail
-- **Full module**: list + detail + dashboard
+- **Data-centric module**: list (`primary`/`crud`) + detail (`view`/`inherit`)
+- **Workflow module**: list (`primary`/`crud`) + detail (`view`/`inherit`) + approve (`functional`/`custom`)
+- **Reporting module**: dashboard (`primary`/`read-only`) + detail (`view`/`inherit`)
+- **Full module**: list (`primary`/`crud`) + detail (`view`/`inherit`) + dashboard (`embedded`/`read-only`)
 
 ### 4. Dependency Graph
 
@@ -111,6 +122,9 @@ For EACH identified element, ask yourself:
 - Does this module need a dashboard?
 - Is the list/detail pattern sufficient or are there other views?
 - Are there workflow steps that need dedicated sections?
+- Does this section need its own access control? If not → `view` or `embedded`
+- Is this a read-only view (dashboard, balances, statistics)? If yes → `permissionMode: read-only`
+- Is this section reached by clicking a row in another section? If yes → always `view`
 
 **Resources:**
 - Is SmartTable the right component for this list?
@@ -159,8 +173,8 @@ Write via ba-writer:
       "priority": "must",
       "entities": ["Employee", "Contract"],
       "anticipatedSections": [
-        { "code": "list", "label": "Liste", "resources": [{ "code": "employees-grid", "type": "SmartTable" }] },
-        { "code": "detail", "label": "Fiche", "resources": [{ "code": "employee-form", "type": "SmartForm" }] }
+        { "code": "list", "label": "Liste", "sectionType": "primary", "permissionMode": "crud", "resources": [{ "code": "employees-grid", "type": "SmartTable" }] },
+        { "code": "detail", "label": "Fiche", "sectionType": "view", "permissionMode": "inherit", "resources": [{ "code": "employee-form", "type": "SmartForm" }] }
       ]
     }
   ],

package/templates/skills/business-analyse/steps/step-03-specify.md

@@ -123,6 +123,10 @@ Define the permission matrix:
 }
 ```
 
+**Auto-detection rules:**
+- If the cadrage mentions "export", "Excel", "CSV", or "télécharger" → automatically add `.export` permission and an export use case (UC-{PREFIX}-EXPORT)
+- If the cadrage mentions "import", "importer", "upload" → automatically add `.import` permission and an import use case (UC-{PREFIX}-IMPORT)
+
 ### F. Interface Specs — Delegated to /ba-design-ui
 
 > **Screen specifications are NOT produced in this step.**
@@ -163,6 +167,9 @@ Before advancing to step 04, verify:
 - [ ] All entity relationships reference existing entities
 - [ ] All UC business rule references exist
 - [ ] All permission paths follow the convention
+- [ ] Sections with `sectionType: view` do NOT appear in `permissionPaths` (they inherit from module)
+- [ ] Sections with `permissionMode: read-only` only have `.read` in `permissionPaths` (no create/update/delete)
+- [ ] Sections with `permissionMode: inherit` have ZERO entries in `permissionPaths`
 
 ## Transition
 

package/templates/skills/business-analyse/steps/step-04-consolidate.md

@@ -423,20 +423,8 @@ ba-writer.enrichSection({
 // Update status
 ba-writer.updateStatus({feature_id}, "consolidated");
 
-// FIX H3: Clean up app-level index.json files entries
-// Only keep entries for files that actually have content at app level.
-// Module-level data lives in module directories — do NOT declare empty app-level files.
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "files",
-  data: {
-    // Keep only files that exist and have content at app level
-    cadrage: { path: "cadrage.json", hash: "framed", lastModified: now() },
-    validation: { path: "validation.json", hash: "consolidated", lastModified: now() }
-    // REMOVED: entities, rules, usecases, permissions, screens, handoff
-    // These exist only at module level (flat-file architecture)
-  }
-});
+// Clean up any forbidden files that may have been created at app level
+ba-writer.cleanupAppLevelFiles({ featureId: {feature_id} });
 
 // Save workflow state for resume support
 ba-writer.enrichSection({

package/templates/skills/controller/references/mcp-scaffold-workflow.md

@@ -123,6 +123,26 @@ if (actualNavRoute !== permission_path) {
   console.warn(`  Got: "${actualNavRoute}"`);
   // Warning only — proceed
 }
+
+// Validate segment count
+const segments = actualNavRoute ? actualNavRoute.split('.').length : 0;
+if (segments < 2) {
+  console.error(`BLOCKING: NavRoute "${actualNavRoute}" has only ${segments} segment(s) — minimum 2 required`);
+  console.error(`  Format: "app.module" (2 segments) or "app.module.section" (3 segments)`);
+  STOP;
+}
+
+// If entity is in a section subfolder, NavRoute must have 3+ segments
+// Check: controller path has 3+ levels after Controllers/ → section-level
+const controllerDir = controllerCall.controllerFile.replace(/[^/]*$/, '');
+const depthAfterControllers = controllerDir.split('Controllers/')[1]?.split('/').filter(Boolean).length || 0;
+if (depthAfterControllers >= 2 && segments < 3) {
+  console.warn(`WARNING: Controller is in a section subfolder (depth=${depthAfterControllers})`);
+  console.warn(`  but NavRoute "${actualNavRoute}" has only ${segments} segments`);
+  console.warn(`  Expected 3 segments: "app.module.section"`);
+  console.warn(`  A 2-segment NavRoute on a section controller causes API 404s`);
+  // Warning — developer should verify and fix
+}
 ```
 
 ---

package/templates/skills/derive-prd/references/handoff-file-templates.md

@@ -30,6 +30,12 @@ From `usecases.json > useCases[]`:
 
 Include: Service per UC cluster, DTOs for API contracts, Validators (FluentValidation), Query handlers
 
+**Validator generation rules:**
+- Every entity with Create and/or Update use cases MUST have a corresponding Validator
+- Validators MUST be registered in DI (`services.AddScoped<IValidator<CreateXxxDto>, CreateXxxValidator>()`)
+- Validators MUST be injected into controllers/services that handle POST/PUT operations
+- NO TODO/placeholder comments allowed in Validators — all validation rules from business rules (BR-VAL-*) must be implemented
+
 ## 4.3 Infrastructure Files
 
 From `entities.json > entities[]`:
@@ -48,7 +54,8 @@ Generated from `usecases.json` + `entities.json`:
 
 ```json
 "api": [
-  { "path": "src/API/Controllers/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
+  { "path": "src/API/Controllers/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}", "isSection": false, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" },
+  { "path": "src/API/Controllers/{ApplicationName}/{ModuleName}/{SectionEntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}.{section-kebab}", "isSection": true, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
 ]
 ```
 
@@ -80,6 +87,23 @@ From `screens.json > screens[]` and `usecases.json > useCases[]`:
 
 **Dashboard acceptance criteria:** Chart library (Recharts), chart types matching spec, KPI cards, filters, CSS variables, responsive layout, wireframe-matching positions.
 
+## 4.5b Notification Files (CONDITIONAL)
+
+> Generated only when `lifeCycles[].transitions[].effects[]` contains entries with `type: "notification"`.
+
+```json
+"notifications": [
+  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}Notification.cs", "type": "Notification", "linkedUCs": [], "module": "{moduleCode}", "description": "Notification triggered by lifecycle transition" },
+  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}NotificationHandler.cs", "type": "NotificationHandler", "linkedUCs": [], "module": "{moduleCode}", "description": "Handler that sends in-app/email notification" }
+]
+```
+
+**Generation rules:**
+- One Notification + Handler pair per unique `notification` effect in lifecycle transitions
+- NotificationName derived from transition: `{Entity}{TransitionName}` (e.g., `OrderApproved`)
+- Handler must use `INotificationService` for in-app and `IEmailService` for email type
+- Notification must include: recipient resolution, template reference, and payload mapping
+
 ## 4.6 SeedData Files
 
 **OBLIGATORY: 2 app-level CORE + per module CORE (NavigationModule + NavigationSections + Permissions + Roles) + business per module:**

package/templates/skills/derive-prd/references/handoff-seeddata-generation.md

@@ -127,7 +127,9 @@ const seedDataCore = {
               ? `/${toKebabCase(appCode)}/${toKebabCase(m.code)}/:id`
               : `/${toKebabCase(appCode)}/${toKebabCase(m.code)}/${toKebabCase(s.code)}`,
           displayOrder: (j + 1) * 10,
-          navigation: s.code === "detail" ? "hidden" : "visible"
+          navigation: s.code === "detail" ? "hidden" : "visible",
+          // Propagate permissionMode for section-level permission generation
+          permissionMode: s.permissionMode || (s.code === "detail" ? "inherit" : s.code === "dashboard" ? "read-only" : "crud")
         }))
       );