@atlashub/smartstack-cli 3.43.0 → 3.44.0

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

@@ -505,12 +505,12 @@ public class {Name}Controller : ControllerBase
 - FORBIDDEN: `humanresources.employees.read` (no kebab-case — mismatches NavRoute)
 - SmartStack.app convention: `support-client.my-tickets.read` (always kebab-case)
 
-### Section-Level Controller (NavRoute with 4 segments)
+### Section-Level Controller (NavRoute with 3 segments)
 
-When a module has sections, each section gets its own controller with a 4-segment navRoute:
+When a module has sections, each section gets its own controller with a 3-segment navRoute:
 
 ```csharp
-// Section-level controller: navRoute has 4 segments
+// Section-level controller: navRoute has 3 segments
 [ApiController]
 [NavRoute("{app}.{module}.{section}")]
 [Authorize]
@@ -528,11 +528,17 @@ public class {Section}Controller : ControllerBase
 }
 ```
 
-**NavRoute segment rules:**
+**NavRoute segment rules (minimum 2 segments):**
 | Level | NavRoute format | Example |
 |-------|----------------|---------|
-| Module | `{app}.{module}` (2 segments) | `human-resources.employees` |
-| Section | `{app}.{module}.{section}` (3 segments) | `human-resources.employees.departments` |
+| Module | `{app}.{module}` (2 segments) | `administration.users` |
+| Section | `{app}.{module}.{section}` (3 segments) | `administration.users.groups` |
+| Sub-resource (Suffix) | `{app}.{module}` + Suffix | `administration.ai` + `Suffix = "prompts"` |
+
+> **POST-CONTEXT REMOVAL:** The old "context" level (1st segment) has been removed.
+> Before: `platform.administration.users` (3 segments). After: `administration.users` (2 segments).
+> The NavigationRouteRegistryBuilder builds 2-segment paths from DB (application.module).
+> Controllers with 3+ segments use the fallback route generator (dots → slashes).
 
 **Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
 
@@ -540,18 +546,18 @@ public class {Section}Controller : ControllerBase
 
 ### Sub-Resource Pattern (NavRoute Suffix)
 
-When an entity is a child of another entity (e.g., LeaveTypes under Leaves), use `[NavRoute(..., Suffix = "types")]`:
+When an entity is a child of another entity (e.g., AiPrompts under AI), use `[NavRoute(..., Suffix = "...")]`:
 
 ```csharp
-// Sub-resource controller: types are nested under leaves
+// Sub-resource controller: prompts are nested under AI module
 [ApiController]
-[NavRoute("human-resources.employees.leaves", Suffix = "types")]
+[NavRoute("administration.ai", Suffix = "prompts")]
 [Authorize]
-public class LeaveTypesController : ControllerBase
+public class AiPromptsController : ControllerBase
 {
     [HttpGet]
-    [RequirePermission(Permissions.Leaves.Read)]  // inherits parent section permission
-    public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAll(...)
+    [RequirePermission(Permissions.Ai.Prompts.Read)]
+    public async Task<ActionResult<PaginatedResult<AiPromptResponseDto>>> GetAll(...)
         => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
 }
 ```
@@ -610,28 +616,13 @@ private static string ToKebabCase(string value)
         .ToLowerInvariant();
 ```
 
-### SeedConstants Pattern
+### GUID Generation Rule
 
 ```csharp
-public static class SeedConstants
-{
-    // Deterministic GUIDs (SHA256-based, reproducible across environments)
-    // NOTE: Application/Module/Section/Resource IDs are deterministic.
-    public static readonly Guid ApplicationId = DeterministicGuid("nav:human-resources");
-    public static readonly Guid ModuleId = DeterministicGuid("nav:human-resources.employees");
-    public static readonly Guid SectionId = DeterministicGuid("nav:human-resources.employees.departments");
-
-    private static Guid DeterministicGuid(string input)
-    {
-        var hash = System.Security.Cryptography.SHA256.HashData(
-            System.Text.Encoding.UTF8.GetBytes(input));
-        var bytes = new byte[16];
-        Array.Copy(hash, bytes, 16);
-        bytes[6] = (byte)((bytes[6] & 0x0F) | 0x50); // version 5
-        bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); // variant
-        return new Guid(bytes);
-    }
-}
+// ALWAYS use Guid.NewGuid() for ALL seed data IDs
+// Avoids conflicts between projects/tenants/environments
+// Idempotence is handled by Code-based lookups at runtime
+// Navigation entities are resolved by Code, not by fixed GUIDs
 ```
 
 ### Navigation Seed Data Example
@@ -665,7 +656,7 @@ var section = NavigationSection.Create(
 |---------|---------|
 | `"humanresources"` as route | Must be `"/human-resources"` (full path, kebab-case) |
 | `"employees"` as route | Must be `"/human-resources/employees"` (includes parent) |
-| `Guid.NewGuid()` in seed data | Must use deterministic GUIDs (SHA256) |
+| Deterministic/sequential/fixed GUIDs in seed data | ALWAYS use `Guid.NewGuid()` |
 | Missing translations | Must have 4 languages: fr, en, it, de |
 | Missing NavigationApplicationSeedData | Menu invisible without Application level |
 
@@ -740,6 +731,13 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `DateTime` for date-only | Use `DateOnly` when no time component needed |
 | FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |
 | `PagedResult<T>` / `PaginatedResultDto<T>` | FORBIDDEN — use `PaginatedResult<T>` only |
+| Controller injects `DbContext` | **Clean Architecture violation** — create an Application service and inject it instead |
+| Domain entity has `[Table]` attribute | Infrastructure concern in Domain — move to `IEntityTypeConfiguration<T>` in Infrastructure |
+| `using Microsoft.EntityFrameworkCore` in Domain | EF Core belongs in Infrastructure, not Domain — Domain must be persistence-ignorant |
+| Controller returns `Employee` entity | Domain leak in API response — return `EmployeeResponseDto` instead |
+| `IEmployeeService.cs` in Infrastructure | Interface belongs in Application — move to `Application/Interfaces/` |
+| Service implementation in Application layer | Implementations belong in Infrastructure — Application only contains interfaces |
+| Controller injects `IRepository<T>` directly | Controllers use Application services, not repositories — add a service layer |
 
 ---
 
@@ -861,8 +859,8 @@ export interface PaginationParams {
 - **Max pageSize = 100** — enforced via `Math.Clamp(pageSize, 1, 100)` or extension method
 - **Default page = 1, pageSize = 20** — all GetAll endpoints
 - **Search param mandatory** — enables `EntityLookup` on frontend
-- **POST-CHECK 16** blocks `List<T>` returns on GetAll
-- **POST-CHECK 31** blocks non-canonical pagination type names
+- **POST-CHECK 11** blocks `List<T>` returns on GetAll
+- **POST-CHECK 26** blocks non-canonical pagination type names
 
 ---
 

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

@@ -211,7 +211,7 @@ resources: {
 ns: ['common', 'navigation', 'employees', 'projects', 'clients'],
 ```
 
-POST-CHECK 45 validates this. Unregistered namespaces → BLOCKING.
+POST-CHECK 37 validates this. Unregistered namespaces → BLOCKING.
 
 ### Rules
 
@@ -407,7 +407,7 @@ const handleTabClick = (tab: TabKey) => {
 - 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.**
+**POST-CHECK 35 enforces this rule.**
 
 ---
 
@@ -1179,7 +1179,7 @@ Before marking frontend tasks as complete, verify:
 - [ ] Translation files exist for **all 4 languages** (fr, en, it, de) in `src/i18n/locales/`
 - [ ] All `t()` calls include namespace prefix AND fallback value
 - [ ] No hardcoded strings in JSX — all text goes through `t()`
-- [ ] CSS uses variables only — no hardcoded Tailwind colors (BLOCKING POST-CHECK 13)
+- [ ] CSS uses variables only — no hardcoded Tailwind colors (BLOCKING POST-CHECK 9)
 - [ ] Pages follow loading → error → content pattern
 - [ ] Pages use `src/pages/{App}/{Module}/` hierarchy
 - [ ] API calls use generated hooks or `apiClient` (never raw axios)
@@ -1569,3 +1569,99 @@ describe('EntityEditPage', () => {
 - Use `@testing-library/react` + `@testing-library/user-event` (NEVER enzyme)
 - Mock API with `vi.mock()` or MSW — NEVER make real API calls in tests
 - Test files live next to their component (co-located, NOT in a separate `__tests__/` folder)
+
+---
+
+## 9. Frontend Compliance Gates (5 Mandatory Checks)
+
+> **Run these checks before any frontend commit.** All 5 gates MUST pass.
+> Previously in separate files `execution-frontend-gates.md` and `execution-frontend-patterns.md` — now consolidated here.
+
+### Gate 1: CSS Variables (Theme System)
+
+```bash
+ALL_PAGES=$(find src/pages/ src/components/ -name "*.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\.")
+if [ -n "$ALL_PAGES" ]; then
+  HARDCODED=$(grep -Pn '(bg|text|border)-(?!\[)(red|blue|green|gray|white|black|slate|zinc|neutral|stone)-' $ALL_PAGES 2>/dev/null)
+  if [ -n "$HARDCODED" ]; then
+    echo "FAIL: Hardcoded Tailwind colors found — must use CSS variables (see section 4)"
+    echo "$HARDCODED"
+  else
+    echo "PASS: CSS variables"
+  fi
+fi
+```
+
+**Fix mapping:** See section 4 (CSS Variables) for the complete variable reference table.
+
+### Gate 2: Forms as Pages (ZERO Modals/Drawers)
+
+```bash
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null)
+if [ -n "$PAGE_FILES" ]; then
+  FAIL=false
+  MODAL_IMPORTS=$(grep -Pn "import.*(?:Modal|Dialog|Drawer|Popup|Sheet|SlideOver|Overlay)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_IMPORTS" ]; then
+    echo "FAIL: Modal/Dialog/Drawer imports — forms MUST be full pages (see section 3b)"
+    echo "$MODAL_IMPORTS"
+    FAIL=true
+  fi
+  MODAL_STATE=$(grep -Pn "useState.*(?:isOpen|showModal|showDialog|showCreate|showEdit|showForm|isCreating|isEditing|showDrawer|showPanel|showSlideOver|selectedEntity|editingEntity)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_STATE" ]; then
+    echo "FAIL: Inline form state detected — forms MUST be separate pages (see section 3b)"
+    echo "$MODAL_STATE"
+    FAIL=true
+  fi
+  if [ "$FAIL" = false ]; then echo "PASS: No modals/drawers"; fi
+fi
+```
+
+### Gate 3: I18n File Structure
+
+```bash
+if [ ! -d "src/i18n/locales" ]; then
+  echo "FAIL: Missing src/i18n/locales/ directory"
+else
+  for LANG in fr en it de; do
+    JSON_FILES=$(find "src/i18n/locales/$LANG" -name "*.json" 2>/dev/null | wc -l)
+    if [ "$JSON_FILES" -eq 0 ]; then
+      echo "FAIL: No JSON files in src/i18n/locales/$LANG/"
+    else
+      echo "PASS: $LANG ($JSON_FILES files)"
+    fi
+  done
+fi
+```
+
+### Gate 4: Lazy Loading
+
+```bash
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+ROUTE_FILES=$(find src/routes/ -name "*.tsx" -o -name "*.ts" 2>/dev/null)
+if [ -n "$APP_TSX" ]; then
+  STATIC_IMPORTS=$(grep -Pn "^import .+ from '@/pages/" "$APP_TSX" $ROUTE_FILES 2>/dev/null)
+  if [ -n "$STATIC_IMPORTS" ]; then
+    echo "FAIL: Static page imports — MUST use React.lazy() (see section 1)"
+    echo "$STATIC_IMPORTS"
+  else
+    echo "PASS: Lazy loading"
+  fi
+fi
+```
+
+### Gate 5: useTranslation in Pages
+
+```bash
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null | grep -v "\.test\." | grep -v node_modules)
+if [ -n "$PAGE_FILES" ]; then
+  TOTAL=$(echo "$PAGE_FILES" | wc -l)
+  WITH_I18N=$(grep -l "useTranslation" $PAGE_FILES 2>/dev/null | wc -l)
+  if [ "$WITH_I18N" -eq 0 ]; then
+    echo "FAIL: No pages use useTranslation — all text must be translated (see section 2)"
+  else
+    echo "PASS: $WITH_I18N/$TOTAL pages use useTranslation"
+  fi
+fi
+```
+
+> **ALL 5 gates MUST pass before frontend commit.** When delegating to `/ui-components` skill, include explicit instructions: CSS variables only, forms as full pages, i18n with namespace + fallback.

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

@@ -5,6 +5,38 @@
 
 ---
 
+## Layer Isolation Rules (Clean Architecture)
+
+### Dependency Graph (allowed imports)
+
+```
+Domain         → (nothing)
+Application    → Domain
+Infrastructure → Domain, Application
+Api            → Application, Infrastructure
+Web            → Application (via API clients)
+```
+
+### FORBIDDEN Patterns
+
+| Layer | FORBIDDEN import | Why |
+|-------|-----------------|-----|
+| Domain | Application, Infrastructure, Api | Domain is the core, depends on nothing |
+| Application | Infrastructure, Api | Application defines interfaces, Infrastructure implements them |
+| Controller | DbContext (direct injection) | Controllers use Application services, not database directly |
+| Controller | IRepository (direct injection) | Controllers use Application services, not repositories |
+| Domain | EF Core attributes (`[Table]`, `[Column]`, `[Index]`) | Domain must be persistence-ignorant; use `IEntityTypeConfiguration<T>` in Infrastructure |
+| Domain | `using Microsoft.EntityFrameworkCore` | Infrastructure concern leaking into Domain |
+| API response | Domain entity (e.g., `ActionResult<Employee>`) | Return DTOs (`EmployeeResponseDto`), never Domain entities |
+
+### Enforcement
+
+- **MCP `validate_conventions(checks: ['architecture'])`** — scans `.cs` files for forbidden imports, DbContext injection, entity exposure, and service interface placement
+- **MCP `review_code(checks: ['architecture'])`** — detects layer violations, DbContext in controllers, EF Core attributes in Domain, entity exposure in API responses
+- **POST-CHECKs A1–A7** — bash-based defense-in-depth (see `post-checks.md`)
+
+---
+
 ## Layer 0 — Domain (sequential)
 
 **Entities:** `Domain/Entities/{App}/{Module}/`
@@ -51,7 +83,7 @@
 
 **BLOCKING:** `dotnet build --no-restore` MUST pass after migration.
 
-> **CRITICAL — Migration must cover ALL entities (POST-CHECK 44, 49):**
+> **CRITICAL — Migration must cover ALL entities (POST-CHECK 36, 40):**
 > Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
 > Verify with `dotnet ef migrations has-pending-model-changes` — must report NO pending changes.
 > If entities are added incrementally across modules, create a NEW migration for each batch.
@@ -82,8 +114,8 @@
 - CQRS with MediatR
 - FluentValidation for all commands — **MUST register validators via DI:**
   `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
-  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 46)
-- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 47). See `smartstack-api.md` DTO Type Mapping.
+  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 38)
+- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 39). See `smartstack-api.md` DTO Type Mapping.
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 - **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
@@ -102,6 +134,10 @@
 
 **Rules:**
 - `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- **NavRoute minimum 2 segments** (application.module):
+  - `[NavRoute("human-resources.employees")]` (CORRECT — module-level, 2 segments)
+  - `[NavRoute("human-resources.employees.departments")]` (CORRECT — section-level, 3 segments)
+  - `[NavRoute("administration.ai", Suffix = "prompts")]` (CORRECT — sub-resource with Suffix)
 - **NavRoute values MUST use kebab-case for ALL multi-word segments:**
   - `[NavRoute("human-resources.employees")]` (CORRECT)
   - `[NavRoute("humanresources.employees")]` (WRONG — missing hyphens)
@@ -109,8 +145,8 @@
   - `[NavRoute("projectmanagement.projects")]` (WRONG)
 - Permission paths MUST use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
 - FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
-- POST-CHECK 48 detects non-kebab-case NavRoute values. POST-CHECK 41 detects non-kebab-case permissions
-- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 50)
+- POST-CHECK 32 detects non-kebab-case NavRoute values. POST-CHECK 33 detects non-kebab-case permissions
+- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 41)
 - `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
 - NEVER use `[Authorize]` without specific permission
 - Swagger XML documentation
@@ -136,10 +172,10 @@
 
 **Application-level (created ONCE, shared across modules):**
 1. **NavigationApplicationSeedData.cs** — Application-level navigation entry (MUST be first)
-2. **ApplicationRolesSeedData.cs** — Application-scoped roles (admin, manager, contributor, viewer) with deterministic GUIDs. Provides role entries for SeedRolesAsync().
+2. **ApplicationRolesSeedData.cs** — Application-scoped roles (admin, manager, contributor, viewer) with random GUIDs (`Guid.NewGuid()`). Provides role entries for SeedRolesAsync().
 
 **Per-module:**
-3. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages (fr, en, it, de)
+3. **NavigationModuleSeedData.cs** — Random GUIDs (`Guid.NewGuid()`), 4 languages (fr, en, it, de)
 4. **NavigationSectionSeedData.cs** — Section-level navigation (if sections defined)
 5. **NavigationResourceSeedData.cs** — Resource-level navigation (if resources defined)
 6. **Permissions.cs** — Static permission constants: `public static class {Module} { public const string Read = "..."; }`. Referenced by `[RequirePermission(Permissions.{Module}.Read)]`.
@@ -154,21 +190,13 @@
    - `SeedRolePermissionsAsync()` — maps roles to permissions (roles resolved by Code, NOT by GUID)
    - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`
 
-### Deterministic GUID Pattern
+### GUID Generation Rule
 
 ```csharp
-// Use SHA256 for deterministic GUIDs (reproducible across environments)
-// NOTE: Application/Module/Section/Resource IDs are deterministic.
-public static readonly Guid ModuleId = GenerateDeterministicGuid("nav-module-{app}-{module}");
-
-private static Guid GenerateDeterministicGuid(string input)
-{
-    var hash = System.Security.Cryptography.SHA256.HashData(
-        System.Text.Encoding.UTF8.GetBytes(input));
-    var bytes = new byte[16];
-    Array.Copy(hash, bytes, 16);
-    return new Guid(bytes);
-}
+// ALWAYS use Guid.NewGuid() for ALL seed data IDs
+// Avoids conflicts between projects/tenants/environments
+// Idempotence is handled by Code-based lookups at runtime
+public static readonly Guid ModuleId = Guid.NewGuid();
 ```
 
 ### Route Convention (CRITICAL — Full Paths Required)
@@ -217,7 +245,7 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 > - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
 
 **FORBIDDEN:**
-- `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
+- Deterministic/sequential/fixed GUIDs → ALWAYS use `Guid.NewGuid()`
 - Missing translations (must have fr, en, it, de)
 - Empty seed classes with no seeding logic
 - PascalCase in route URLs → always kebab-case
@@ -275,7 +303,7 @@ const [loading, setLoading] = useState(true);
 ### Components & CSS
 
 **Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
-**CSS:** Variables ONLY — hardcoded Tailwind colors are **BLOCKING** in POST-CHECK 13:
+**CSS:** Variables ONLY — hardcoded Tailwind colors are **BLOCKING** in POST-CHECK 9:
 
 | Instead of | Use |
 |-----------|-----|
@@ -375,7 +403,7 @@ t('{module}:actions.create', 'Create entity') // ALWAYS with namespace prefix
 | Action | Tool |
 |--------|------|
 | Generate doc-data.ts + page wrapper | `/documentation` skill (type: user) |
-| Verify DocToggleButton in pages | POST-CHECK 29 |
+| Verify DocToggleButton in pages | POST-CHECK 24 |
 
 **Output files:**
 - `src/pages/docs/business/{app}/{module}/doc-data.ts` — data-driven documentation
@@ -400,3 +428,97 @@ See `references/smartstack-frontend.md` section 7 for the component pattern.
 
 **Target:** >= 80% coverage, 100% pass rate.
 **Fix CODE, not tests.**
+
+---
+
+## Planning Template — Per-File Plan Format
+
+> **Used by step-02 when creating the execution plan.** Each entity MUST include:
+
+```yaml
+Entity: {EntityName}
+  - tenantMode: strict | optional | scoped | none
+  - codePattern: auto-generated strategy (if applicable)
+  - fkFields: [{field, targetEntity}] (if applicable)
+  - acceptance criteria: [AC1, AC2, ...]
+```
+
+For EACH file in the plan, specify HOW it will be created/modified:
+
+**Layer 0 — Domain + Infrastructure (sequential):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 1 | Domain/Entities/.../Entity.cs | create | MCP scaffold_extension |
+| 2 | Infrastructure/.../EntityConfiguration.cs | create | MCP scaffold_extension |
+| 3 | Infrastructure/Migrations/ | create | MCP suggest_migration + dotnet ef |
+
+**Layer 1 — Application + API + Seed Data (parallel):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 4 | Application/Services/.../Service.cs | create | MCP scaffold_extension |
+| 5 | Application/DTOs/.../Dto.cs | create | MCP scaffold_extension |
+| 6 | Api/Controllers/.../Controller.cs | create | /controller skill or MCP scaffold_extension |
+| 7 | Seeding/Data/NavigationApplicationSeedData.cs | create | Reference Layer 1 Seed Data (once per app) |
+| 7b | Seeding/Data/ApplicationRolesSeedData.cs | create | Reference Layer 1 Seed Data (once per app) |
+| 7c | Infrastructure/Services/CodeGeneration/ | create | Reference code-generation.md (if codePattern != manual) |
+| 8 | Seeding/Data/.../NavigationModuleSeedData.cs | create | Reference core-seed-data.md (4 langs) |
+| 8b | Application/Authorization/Permissions.cs | create | MCP generate_permissions |
+| 9 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
+| 10 | Seeding/Data/.../RolesSeedData.cs | create | Reference Layer 1 Seed Data |
+| 10b | Seeding/{App}SeedDataProvider.cs | create | Reference core-seed-data.md (IClientSeedDataProvider + DI) |
+
+**Layer 1 — Frontend (parallel):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 11 | src/pages/{App}/{Mod}/ListPage.tsx | create | /ui-components skill |
+| 11b | src/pages/{App}/{Mod}/CreatePage.tsx | create | /ui-components skill (FK: EntityLookup) |
+| 11c | src/pages/{App}/{Mod}/EditPage.tsx | create | /ui-components skill (FK: EntityLookup) |
+| 12 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
+| 13 | src/routes/{module}.tsx | create | MCP scaffold_routes |
+| 14 | src/i18n/locales/{lang}/{module}.json | create | Reference smartstack-frontend.md (4 languages) |
+
+**Layer 2b — Documentation (after frontend):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 14b | src/pages/docs/business/{app}/{module}/doc-data.ts | create | /documentation skill |
+| 14c | src/pages/docs/business/{app}/{module}/index.tsx | create | /documentation skill |
+
+**Layer 3 — Tests (sequential):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 15 | tests/.../EntityTests.cs | create | MCP scaffold_tests |
+| 16 | tests/.../ServiceTests.cs | create | MCP scaffold_tests |
+
+**FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6).
+
+---
+
+## Parallelization Strategy (Agent Teams)
+
+If NOT economy_mode AND Layer 1 has both backend and frontend work:
+
+**Create agent teams to execute Layer 1 backend and frontend in parallel.**
+
+See `references/agent-teams-protocol.md` for team creation, teammate spawning, task coordination, and shutdown.
+
+---
+
+## Delegate Mode Fast Path
+
+When `/ralph-loop` invokes `/apex -d {prd_path}`, PRD tasks already define the scope.
+
+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: infer file_path, action, and tool from category. SKIP user checkpoint. Jump to "Estimated Commits" section.

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

@@ -131,9 +131,9 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 ## 4. Define Navigation Hierarchy (4 Levels)
 
-> **Reference:** Load `references/initialization-challenge-flow.md` for detailed challenge flow:
+> **Reference:** Load `references/challenge-questions.md` for hierarchy rules and challenge questions:
 > - 4-level hierarchy structure (Application → Module → Section → Resource)
-> - Challenge questions (4a: Application, 4b: Module, 4c: Sections)
+> - Challenge questions (4a: Application, 4b: Module, 4c: Sections, 5a: Entities, 5b: Dependencies)
 > - Validation rules (sections MUST have at least one entry)
 > - Storage format for each level
 > - Delegate mode skip (if -d)

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

@@ -13,6 +13,7 @@ next_step: steps/step-02-plan.md
 ## LOAD CONDITIONALLY
 
 - **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
+  > **CONTEXT NOTE:** This file stays in context and is reused by step-03. Do NOT re-read it there.
 - If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
 
 ---

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

@@ -12,7 +12,8 @@ next_step: steps/step-03-execute.md
 
 ## LOAD CONDITIONALLY
 
-Read `references/smartstack-layers.md` for layer execution rules and skill/MCP mapping.
+Read `references/smartstack-layers.md` for layer execution rules, skill/MCP mapping, planning templates, and delegate mode fast path.
+> **CONTEXT NOTE:** This file stays in context and is reused by step-03. Do NOT re-read it there.
 
 ---
 
@@ -54,11 +55,11 @@ IF delegate_mode:
 
 ## 1-3. Layer Mapping, Skill Assignment, Parallelization
 
-> **Reference:** Load `references/planning-layer-mapping.md` for detailed planning procedures:
+> **Reference:** All planning procedures are now in `references/smartstack-layers.md` (already loaded above):
 > - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
 > - Entity definition template (tenantMode, codePattern, fkFields, ACs)
 > - Skill/MCP assignment table (per file, per layer)
-> - Layer 0/1/2b/3 file lists with tools
+> - Layer 0/1/2b/3 file lists with tools (see "Planning Template" section)
 > - FK field guidance (EntityLookup + backend ?search= parameter)
 > - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
 > - Delegate mode fast path (PRD task mapping to layers)

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

@@ -13,9 +13,9 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 
 ## LOAD CONDITIONALLY
 
-- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
-- **ALWAYS** read `references/smartstack-frontend.md` — lazy loading, i18n, page structure, CSS variables
-- Read `references/smartstack-layers.md` for execution rules per layer
+> **CONTEXT REUSE:** `smartstack-api.md` (loaded in step-01) and `smartstack-layers.md` (loaded in step-02) are already in context. Do NOT re-read them.
+
+- **ALWAYS** read `references/smartstack-frontend.md` — lazy loading, i18n, page structure, CSS variables, EntityLookup, compliance gates (sections 1-9)
 - If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`
 - If `{delegate_mode}` AND seedData tasks exist: read `references/core-seed-data.md` — comprehensive seed data templates
 - If build failure during execution: read `references/error-classification.md` — error diagnosis categories A-F
@@ -98,12 +98,12 @@ dotnet build
 
 ## Layer 1 — Application + API + Seed Data
 
-> **Reference:** Load `references/execution-layer1-rules.md` for critical Layer 1 rules:
-> - NavRoute and permission kebab-case (POST-CHECKs 41 + 48)
-> - Controller route attributes (POST-CHECK 50)
-> - Validators DI registration (POST-CHECK 46)
-> - DateOnly vs string (POST-CHECK 47)
-> - Code generation patterns (ICodeGenerator<T> registration)
+> **Layer 1 rules** are in `references/smartstack-layers.md` (already in context from step-02):
+> - NavRoute and permission kebab-case (Layer 1 - API section)
+> - Controller route attributes (FORBIDDEN: [Route] alongside [NavRoute])
+> - Validators DI registration
+> - DateOnly vs string for DTO date fields
+> - Code generation patterns (ICodeGenerator<T> registration, see references/code-generation.md)
 
 ### Backend Tasks (sequential or parallel)
 
@@ -114,17 +114,17 @@ dotnet build
 
 ### Frontend Tasks (sequential or parallel)
 
-> **Reference:** Load `references/execution-frontend-patterns.md` for complete frontend patterns:
+> **Frontend patterns** are in `references/smartstack-frontend.md` (already loaded above):
 > - API client generation (MCP scaffold_api_client)
-> - Route scaffolding (MCP scaffold_routes)
-> - Page types (ListPage, DetailPage, CreatePage, EditPage)
-> - FK field handling (EntityLookup component)
-> - Form structure (ZERO modals — all full pages)
-> - Detail page tabs (local state only)
-> - Testing patterns (co-located form tests)
-> - Section-level routes and permissions
-> - Sub-resource handling
-> - I18n JSON structure and registration (POST-CHECK 45)
+> - Route scaffolding (MCP scaffold_routes) — section 1 + 3b
+> - Page types (ListPage, DetailPage, CreatePage, EditPage) — section 3
+> - FK field handling (EntityLookup component) — section 6
+> - Form structure (ZERO modals — all full pages) — section 3b
+> - Detail page tabs (local state only) — section 3 "Tab Behavior Rules"
+> - Testing patterns (co-located form tests) — section 8
+> - Section-level routes and permissions — section 3b
+> - I18n JSON structure and registration — section 2
+> - Compliance gates (5 mandatory checks) — section 9
 
 ### If NOT economy_mode: Agent Teams (parallel)
 
@@ -187,8 +187,8 @@ Spawn 2 teammates (Opus, full tools):
       → EntityEditPage.test.tsx (co-located next to page)
       → Cover: rendering, validation, submit, pre-fill, navigation, errors
       → See smartstack-frontend.md section 8 for test templates
-    - **SECTION PERMISSIONS:** After MCP generate_permissions for the module navRoute (2 segments),
-      also call MCP generate_permissions for EACH section navRoute (3 segments: {app}.{module}.{section})
+    - **PERMISSIONS:** Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
+      then also call MCP generate_permissions for EACH section (3 segments: {app}.{module}.{section}).
     - **SECTION ROUTES:** Add section child routes to the module's children array.
       Wire PermissionGuard for section routes with section-level permissions.
     - I18n: Generate 4 JSON files per module namespace (fr, en, it, de)
@@ -253,7 +253,7 @@ After Layer 1 completes:
 ```
 1. Verify seed data completeness:
    - NavigationModuleSeedData.cs with 4 languages
-   - PermissionsSeedData.cs with deterministic GUIDs
+   - PermissionsSeedData.cs with Guid.NewGuid()
    - RolesSeedData.cs with context-based role mapping
    - IClientSeedDataProvider updated
    - DI registration added
@@ -267,8 +267,8 @@ After Layer 1 completes:
 
 ## FRONTEND COMPLIANCE GATE (MANDATORY before commit)
 
-> **Reference:** Load `references/execution-frontend-gates.md` for all 5 mandatory checks:
-> 1. CSS Variables (theme system) — POST-CHECK 13
+> **Reference:** See `references/smartstack-frontend.md` section 9 "Compliance Gates" for all 5 mandatory checks:
+> 1. CSS Variables (theme system)
 > 2. Forms as Pages (ZERO modals/drawers/slide-overs)
 > 3. I18n File Structure (4 languages, separate JSON files)
 > 4. Lazy Loading (React.lazy() — no static imports)