@atlashub/smartstack-cli 4.32.0 → 4.34.0

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

@@ -6,11 +6,13 @@ prev_step: steps/step-02-plan.md
 next_step: steps/step-04-examine.md
 ---
 
-# Step 3: Execute
+# Step 3: Execute — Orchestrator
 
 /apex ORCHESTRATES. It does not write SmartStack code directly.
 All code goes through skills (/controller, /application, /ui-components, /efcore) or MCP tools.
 
+**This step dispatches to layer-specific sub-steps.** Each sub-step is loaded sequentially.
+
 ## LOAD CONDITIONALLY
 
 > 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.
@@ -26,20 +28,8 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 ## Foundation Mode Detection
 
 **IF `{foundation_mode}` == true:**
-
-This is a foundation-only execution (called by ralph-loop Phase 0). Execute ONLY:
-- Layer 0: Domain entities + EF configs + Migration
-
-Skip all other layers:
-- Layer 1: Seed Data → SKIP
-- Layer 2: Backend → SKIP
-- Layer 3: Frontend → SKIP
-- Layer 4: DevData → SKIP
-
-After Layer 0 completes and builds successfully:
-- Commit with message: `chore(foundation): entities for {module_code}`
-- Jump to step-04 for POST-CHECKs (domain + infrastructure only)
-- End execution
+Execute ONLY Layer 0 (domain entities + EF configs + migration). Skip all other layers.
+After Layer 0 completes: commit `chore(foundation): entities for {module_code}`, jump to step-04.
 
 **IF `{foundation_mode}` == false:**
 Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
@@ -57,734 +47,33 @@ BEFORE starting Layer N:
 
   IF any variable is missing or empty:
     1. Read .claude/output/apex/{task_id}/state.json (if exists)
-       → Restore: completed_layers, completed_entities, files_created
-    2. IF state.json missing:
-       → Re-derive from filesystem:
-         - {app_name}: Glob("docs/business/*/") → first directory name
-         - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
-         - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
-         - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse GetSectionEntries
-         - {code_patterns}: Read state.json code_patterns field, OR re-derive from existing ICodeGenerator registrations in DependencyInjection.cs, OR default to "manual" for all entities
-    3. IF Layer N-1 was already completed (check state.json or git log):
-       → Skip to Layer N directly
+    2. IF state.json missing → re-derive from filesystem:
+       - {app_name}: Glob("docs/business/*/") → first directory name
+       - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
+       - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
+       - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse
+       - {code_patterns}: Read state.json or re-derive from DependencyInjection.cs
+    3. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+    4. IF Layer N-1 already completed: skip to Layer N directly
 
   Cost: ~5 tool calls. Only triggered if context was compressed.
 ```
 
 ---
 
-## Layer 0 — Domain + Infrastructure (sequential, agent principal)
-
-### Task Progress
-TaskUpdate(taskId: layer0_task_id, status: "in_progress")
-TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-03 (Execute), Layer 0",
-  activeForm: "Executing Layer 0")
-
-### Domain Entities
-
-```
-For each entity to create/modify:
-  → MCP scaffold_extension (type: "entity", target: entity_name)
-  → Verify: inherits BaseEntity, implements ITenantEntity + IAuditableEntity
-  → Verify entity matches patterns in references/smartstack-api.md
-```
-
-### Code Generation Integration
-
-```
-For each entity with auto-generated code ({code_patterns} from step-00):
-  IF {code_patterns} has entry for this entity AND strategy != "manual":
-    → Pass codePattern in scaffold_extension options:
-      MCP scaffold_extension (type: "entity", target: entity_name, options: {
-        codePattern: {
-          strategy: {code_patterns[entity].strategy},
-          prefix: {code_patterns[entity].prefix},
-          digits: {code_patterns[entity].digits},
-          includeTenantSlug: {code_patterns[entity].includeTenantSlug},
-          separator: {code_patterns[entity].separator}
-        }
-      })
-    → Verify: Code property exists on entity but is NOT in CreateDto
-    → Verify: ICodeGenerator<{Entity}> is ready for DI registration (Layer 2)
-  ELSE:
-    → Default behavior (strategy: "manual", Code in CreateDto)
-```
-
-### Enum Serialization Check
-
-```
-For each enum type created in Domain/Enums/:
-  1. Grep("JsonStringEnumConverter", "src/**/Program.cs")
-  2. IF global config exists → no action
-  3. IF no global config → add [JsonConverter(typeof(JsonStringEnumConverter))] on each enum
-```
-
-### Person Extension Detection
-
-**If entity has personRoleConfig (mandatory or optional UserId link):**
-See `references/person-extension-pattern.md` for full entity, EF config, service, DTO, and frontend patterns.
-
-```
-1. scaffold_extension with options: { isPersonRole: true, userLinkMode: 'mandatory' | 'optional' }
-2. Verify: EF config has unique index on (TenantId, UserId)
-   → Mandatory variant: plain .IsUnique()
-   → Optional variant: .IsUnique().HasFilter("[UserId] IS NOT NULL")
-3. Verify all build checks pass before continuing
-```
-
-### EF Core Configurations
-
-```
-For each entity:
-  → Create IEntityTypeConfiguration<T> manually per smartstack-api.md patterns
-  → Verify: table name, relationships, indexes
-  → Register DbSet in ExtensionsDbContext if new entity
-```
-
-### Migration
-
-> Migration must cover ALL entities. Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities were added later without re-running → 4 entities had no tables. Create/update migration AFTER ALL entities and EF configs are registered in DbContext. If entities are added incrementally, create a new migration for each batch.
-
-```
-1. Verify all entities have been added as DbSet in ExtensionsDbContext
-2. Verify all EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
-3. MCP suggest_migration → get standardized name
-4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
-5. dotnet ef database update (if local DB)
-6. dotnet build
-7. Verify: dotnet ef migrations has-pending-model-changes → must report "No pending model changes"
-```
-
-If build fails after migration, fix EF configs before proceeding.
-If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
-
-### Post-Layer 0 Build Gate
-
-```bash
-dotnet build
-# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
-```
-
-Must pass before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.
-
-TaskUpdate(taskId: layer0_task_id, status: "completed",
-  metadata: { build_gate: "pass" })
-
-### Layer 0 Commit
-
-```
-feat({module}): [domain+infra] {short description}
-```
-
----
-
-## Layer 1 — Seed Data (DEDICATED LAYER — sequential, agent principal)
-
-### Task Progress
-TaskUpdate(taskId: layer1_task_id, status: "in_progress")
-TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-03 (Execute), Layer 1",
-  activeForm: "Executing Layer 1")
-
-> This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
-
-### Application-Level Seed Data (ONCE per application)
-
-```
-1. NavigationApplicationSeedData.cs
-   → Application-level navigation entry (MUST be first)
-   → 4 language translations (fr, en, it, de)
-
-2. ApplicationRolesSeedData.cs
-   → 4 roles: admin, manager, contributor, viewer
-   → References NavigationApplicationSeedData.ApplicationId
-```
-
-### Per-Module Seed Data
-
-```
-3. NavigationModuleSeedData.cs
-   → 4 languages (fr, en, it, de), GetModuleEntry() + GetTranslationEntries()
-   → If sections defined: GetSectionEntries() + GetSectionTranslationEntries()
-   → If resources defined: GetResourceEntries() + resource translations
-   → Query actual parent from DB for FK (NOT deterministic GUID)
-
-4. Permissions.cs
-   → MCP generate_permissions (PRIMARY tool)
-   → Static constants: public static class {Module} { public const string Read = "..."; }
-   → Permission paths MUST use kebab-case matching NavRoute codes
-
-5. PermissionsSeedData.cs
-   → MCP generate_permissions first, fallback template
-   → Paths match Permissions.cs, wildcard + CRUD
-
-6. RolesSeedData.cs
-   → Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R
-   → Code-based role mapping (not deterministic GUIDs for roles)
-   → Look up roles by Code at runtime
-```
-
-### Infrastructure Provider (ONCE per application)
-
-```
-7. {App}SeedDataProvider.cs
-   → Implements IClientSeedDataProvider
-   → SeedNavigationAsync(): Application → Module → Section → Resource + translations
-   → SeedRolesAsync(): application-scoped roles from ApplicationRolesSeedData
-   → SeedPermissionsAsync(): permission entries from PermissionsSeedData
-   → SeedRolePermissionsAsync(): maps roles to permissions (by Code, NOT by GUID)
-   → DI: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()
-```
-
-### Post-Layer 1 Build Gate
-
-```bash
-dotnet build
-```
-
-Must pass before Layer 2.
-
-TaskUpdate(taskId: layer1_task_id, status: "completed",
-  metadata: { build_gate: "pass" })
-
-### Layer 1 Commit
-
-```
-feat({module}): [seed] navigation, permissions, roles
-```
-
-> **Context release:** `references/core-seed-data.md` is no longer needed after Layer 1. Its templates have been consumed. Do not reference it in Layer 2+.
-
----
-
-## Layer 2 — Backend (Services + Controllers)
-
-### Task Progress
-TaskUpdate(taskId: layer2_task_id, status: "in_progress")
-TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-03 (Execute), Layer 2",
-  activeForm: "Executing Layer 2")
-
-> **Layer 2 rules** are in `references/smartstack-layers.md` (already in context from step-02):
-> - NavRoute and permission kebab-case (Layer 2 - 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 within layer)
-
-- Services/DTOs: MCP scaffold_extension
-- Controllers: use /controller skill for complex, MCP scaffold_extension for simple
-- Important: All GetAll endpoints must support `?search=` query parameter (enables EntityLookup on frontend)
-- Guard: DTO mapping in services MUST use inline construction (`new ResponseDto(...)`) inside IQueryable `.Select()`. Never use helper methods (MapToDto, ToDto) inside `.Select()` — EF Core cannot translate them. Helper methods are allowed only after materialization (ToListAsync, FirstAsync).
-
-### Code Generation Service Registration (per entity)
-
-```
-For each entity where {code_patterns} defines strategy != "manual":
-  1. Verify DI registration in DependencyInjection.cs:
-     → services.AddScoped<ICodeGenerator<{Entity}>>(sp => new CodeGenerator<{Entity}>(...))
-     → Use CodePatternConfig matching {code_patterns[entity]} values
-     → See references/code-generation.md "DI Registration Pattern"
-     → Guard: Do NOT duplicate if ICodeGenerator<{Entity}> is already registered
-  2. Verify service injection:
-     → {Entity}Service constructor receives ICodeGenerator<{Entity}>
-     → CreateAsync uses _codeGenerator.NextCodeAsync(ct) instead of dto.Code
-     → See references/code-generation.md "Service Integration Pattern"
-  3. Verify CreateDto:
-     → Code property MUST NOT be in Create{Entity}Dto
-     → Code property MUST be in {Entity}ResponseDto
-     → See references/code-generation.md "CreateDto Changes"
-  4. Verify Validator:
-     → Create{Entity}Validator has NO Code rule (auto-generated)
-     → Update{Entity}Validator has Code rule with regex ^[a-z0-9_-]+$ (if Code is mutable)
-```
-- FK inter-entity pattern: When an entity has FK to another business entity (e.g., Absence → Employee), use navigation properties directly inside `.Select()` (e.g., `x.Employee.Code`, `x.Employee.User!.LastName`). EF Core translates navigation access to SQL JOINs automatically. Do NOT use `.Include()` with `.Select()` — it is ignored. See `references/smartstack-api.md` "Service Pattern — Entity with FK to another business entity" for the full pattern.
-
-### Skill Delegation
-
-| Skill | When | Context to provide |
-|-------|------|--------------------|
-| /controller | Custom routes, complex auth, file upload | entity, CRUD actions, permissions, routes |
-| /application | Full app/module from scratch | app, module names |
-| /ui-components | Complex pages (tables, grids, dashboards) | entity, fields, page type |
-| /efcore | Complex EF configs, inheritance | relationships, indexes |
-| /notification | In-app or email notifications | trigger, recipients, template |
-| /workflow | Automated workflows | trigger, steps, conditions |
-
-### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
-
-> **Protocol:** See `references/parallel-execution.md`
-
-```
-IF NOT economy_mode AND entities.length > 1:
-  For each entity, launch in parallel (single message):
-    Agent(subagent_type='Snipper', model='opus',
-      prompt='Execute Layer 2 backend for {EntityName}:
-        - Application service/DTO: MCP scaffold_extension
-        - Controller: /controller skill or MCP scaffold_extension
-        - IMPORTANT: GetAll endpoint MUST support ?search= parameter
-        - Validators: FluentValidation + DI registration
-        - CODE GENERATION: {code_patterns[EntityName] summary — e.g., "strategy: sequential, prefix: emp, digits: 5" or "manual"}
-          If strategy != "manual": read references/code-generation.md, then:
-          → Register ICodeGenerator<{EntityName}> in DI (DependencyInjection.cs) with CodePatternConfig matching {code_patterns}
-          → Inject ICodeGenerator<{EntityName}> in {EntityName}Service, use _codeGenerator.NextCodeAsync(ct) in CreateAsync
-          → Remove Code from Create{EntityName}Dto (auto-generated, not user-provided)
-          → Keep Code in {EntityName}ResponseDto
-          → Create{EntityName}Validator: NO Code rule. Update{EntityName}Validator: Code rule with regex ^[a-z0-9_-]+$
-        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
-        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
-  # All agents launched in parallel
-
-ELSE:
-  # Agent principal handles all entities sequentially
-```
-
-### Parallel Agents + TaskCreate Integration
-
-When launching agents for multi-entity layers:
-- Each agent receives its task ID and metadata context in the prompt
-- Agent must call TaskUpdate(status: "in_progress") before starting
-- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
-- Agent principal monitors via TaskList() after all agents complete
-- 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
-dotnet build
-```
-
-Must pass before backend tests.
-
-TaskUpdate(taskId: layer2_task_id, status: "completed",
-  metadata: { build_gate: "pass" })
-TaskUpdate(taskId: progress_tracker_id,
-  activeForm: "Running build gate (Layer 2)")
-
-### Backend Tests Inline
-
-> **Tests are scaffolded and run WITHIN Layer 2, not deferred to step-07.**
-
-```
-1. Scaffold backend tests:
-   → MCP scaffold_tests (target_layer: "domain", module: "{module_code}", test_type: "unit")
-   → MCP scaffold_tests (target_layer: "application", module: "{module_code}", test_type: "unit")
-   → MCP scaffold_tests (target_layer: "api", module: "{module_code}", test_type: "integration")
-
-2. Run tests:
-   dotnet test --no-build --verbosity normal
-
-3. Fix loop (max 3 iterations):
-   IF tests fail:
-     → Identify root cause (ALWAYS code bug, not test bug)
-     → Fix production CODE via appropriate skill/MCP
-     → dotnet build --no-restore
-     → dotnet test --no-build
-     → Repeat until pass or max 3
-
-4. If still failing after 3 iterations: note failures, continue to Layer 3.
-   Step-07 "Final Test Sweep" will handle remaining failures.
-```
-
-### Layer 2 Commits
-
-```
-feat({module}): [app+api] {short description}
-test({module}): backend unit and integration tests
-```
-
-> **Context release:** `references/smartstack-api.md` entity patterns and `references/smartstack-layers.md` Layer 2 rules have been consumed. Layer 3 only needs their frontend sections (already covered by `smartstack-frontend.md`).
-
----
-
-## Layer 3 — Frontend (Pages + I18n + Documentation)
-
-### ⛔ 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
-> 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.
->
-> **Agent boundary rule:** Snipper sub-agents DO NOT have access to the Skill tool.
-> Therefore, .tsx page generation MUST NEVER be delegated to Snipper agents.
-> Pages are ALWAYS generated by the principal agent via Skill("ui-components").
-> Snipper agents handle: API clients, routes, wiring, i18n, tests — NOT pages.
-
-### Load Frontend References (deferred from top of step)
-
-- Read `references/smartstack-frontend.md` now — lazy loading, i18n, page structure, CSS variables, EntityLookup (sections 1-6)
-- Read `references/smartstack-frontend-compliance.md` now — documentation, form testing, compliance gates (sections 7-9)
-
-### Pre-flight: Shared component existence check
-
-Before generating any page, verify shared components exist:
-
-```
-Glob("src/components/ui/DataTable.*")
-Glob("src/components/ui/EntityCard.*")
-Glob("src/components/ui/PageLoader.*")
-Glob("src/components/ui/EntityLookup.*")
-```
-
-If ANY shared component is MISSING:
-  → Log warning: "Shared component {Component} not found — will be generated locally"
-  → When invoking Skill("ui-components"), add instruction:
-    "MISSING SHARED COMPONENTS: {list}. Generate these locally in src/components/ui/"
-
-**EntityLookup special handling (FK fields):**
-If ANY entity has FK Guid fields (e.g., EmployeeId, DepartmentId) AND EntityLookup is missing:
-  → Generate EntityLookup FIRST, BEFORE any Create/Edit pages
-  → Use the EXACT implementation from `references/smartstack-frontend.md` section 6 (EntityLookup Component Pattern)
-  → Critical: response parsing MUST use `(res.data.items || res.data).map(mapOption)` to handle both paginated and array responses
-  → Do NOT improvise — copy the reference implementation verbatim
-  → Do NOT write a simplified version with `result.data` or `Array.isArray(result.data)` — the reference handles both `PaginatedResult<T>` (`.items`) and raw array responses
-  → Verify after generation: the component MUST contain the expression `(res.data.items || res.data).map(mapOption)` — if it does not, replace with the reference version
-
-### Task Progress
-TaskUpdate(taskId: layer3_task_id, status: "in_progress")
-TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-03 (Execute), Layer 3",
-  activeForm: "Executing Layer 3")
-
-> **Frontend patterns** are in `references/smartstack-frontend.md` (already loaded above):
-> - API client generation (MCP scaffold_api_client)
-> - 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 (no 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
-
-### Frontend Tasks (sequential or parallel within layer)
-
-For each module:
-- API client: MCP scaffold_api_client
-- 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
-  → **CRITICAL — Module Segment Required:** Route paths MUST include the module segment.
-    For a 3-level hierarchy (app → module → sections), paths are `{module_kebab}/{section_kebab}`.
-    Example: `employee-management/employees` NOT just `employees`.
-    Without the module segment, routes resolve to `/{app}/{section}` instead of `/{app}/{module}/{section}`,
-    causing mismatch with backend navigation seed data → nav links produce 404s.
-  → **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 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
-  → CSS variables only: bg-[var(--bg-card)], text-[var(--text-primary)]
-  → DataTable/EntityCard (not raw HTML `<table>`)
-  → If entity has FK Guid fields: generate EntityLookup component in @/components/ui/EntityLookup (see smartstack-frontend.md section 6)
-  → Dashboard pages: generate StatCard + ChartCard locally (see ui-components patterns/dashboard-chart.md)
-- Form pages: Create/Edit forms are full pages with own routes:
-  → EntityCreatePage.tsx with route /{module}/create
-  → EntityEditPage.tsx with route /{module}/:id/edit
-  → Zero modals/popups/drawers/dialogs for forms
-  → Back button with navigate(-1) on every form page
-  → See smartstack-frontend.md section 3b for templates
-- Tabs on detail pages: Tabs must switch content locally:
-  → Tab click handler: setActiveTab(tabKey) only — do not navigate() to another page
-  → Tab content: render inline with {activeTab === 'tabKey' && <TabContent />}
-  → Sub-resource data: fetch via API filtered by parent ID, display in tab panel
-  → Do not use navigate('../leaves?employee=${id}') in tab handler
-  → See smartstack-frontend.md section 3 'Tab Behavior Rules'
-- FK fields: Foreign key Guid fields (e.g., EmployeeId) must use EntityLookup:
-  → Do not render FK fields as `<input>` — users cannot type GUIDs
-  → Do not render FK fields as `<select>` — even with API-loaded options, `<select>` is not acceptable
-  → Only use `<EntityLookup />` from @/components/ui/EntityLookup for searchable selection
-  → Each FK field needs: apiEndpoint, mapOption (display name), search support on backend
-  → Do not use `<select value={formData.departmentId}>`, `<option value={dept.id}>`, `e.target.value` for FK fields
-  → See smartstack-frontend.md section 6 for the full EntityLookup pattern
-- I18n: Generate 4 JSON files per module namespace (fr, en, it, de)
-  → Follow JSON template from smartstack-frontend.md
-  → Keys: actions, labels, errors, validation, columns, form, messages, empty
-  → All t() calls must use namespace prefix + fallback: t('ns:key', 'Default text')
-  → **Register namespace in i18n config** (critical — POST-CHECK C39 catches this, but fix it now):
-    1. Find i18n config: `Glob("src/**/i18n/config.ts")` or `index.ts` or `i18n.ts`
-    2. Read the config → find the resources/ns registration pattern
-    3. Add the new namespace import + registration for all 4 languages
-    4. If config uses dynamic imports: add namespace to the `ns` array
-    5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
-- 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 `applicationRoutes['{app_kebab}']`.
-  Route paths MUST include the module segment: `{module_kebab}/{section_kebab}` (e.g., `employee-management/employees`).
-  Do NOT use just `{section_kebab}` (e.g., `employees`) — this omits the module level and causes 404s.
-  Wire PermissionGuard for section routes with section-level permissions.
-- MUST use src/pages/{App}/{Module}/ hierarchy (NOT flat)
-
-### Documentation (after frontend pages exist)
-
-> **After frontend pages are created, generate module documentation via `/documentation` skill.**
-
-```
-Invoke /documentation {module_code} --type user
-
-This generates:
-- src/pages/docs/business/{app}/{module}/doc-data.ts (data file)
-- src/pages/docs/business/{app}/{module}/index.tsx (page wrapper)
-- src/i18n/locales/fr/docs-{app}-{module}.json (French doc translations)
-- Updates App.tsx routing for doc page
-- Updates docs-manifest.json
-```
-
-**Verify DocToggleButton presence in list/detail pages:**
-- Every `*ListPage.tsx` and `*DetailPage.tsx` MUST import and render `DocToggleButton` in their header
-- Import: `import { DocToggleButton } from '@/components/docs/DocToggleButton';`
-- Placement: inside the header actions area (see `smartstack-frontend.md` section 7)
-
-### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
-
-> **Protocol:** See `references/parallel-execution.md`
-
-```
-IF NOT economy_mode AND entities.length > 1:
-  # PHASE A — Parallel: infrastructure frontend (NO page generation)
-  # Snipper agents DO NOT have access to the Skill tool, so they CANNOT call /ui-components.
-  # Pages MUST be generated by the principal agent in Phase B.
-  For each entity, launch in parallel (single message):
-    Agent(subagent_type='Snipper', model='opus',
-      prompt='Execute Layer 3 INFRASTRUCTURE for {EntityName}:
-        **MANDATORY: Read references/smartstack-frontend.md FIRST**
-        - API client: MCP scaffold_api_client
-        - 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
-          → CRITICAL: Route paths MUST include module segment: {module_kebab}/{section_kebab} (e.g., employee-management/employees, NOT just employees)
-          → See references/frontend-route-wiring-app-tsx.md for full patterns
-          → Verify: mcp__smartstack__validate_frontend_routes (scope: "routes")
-        - I18n: 4 JSON files (fr, en, it, de) + REGISTER namespace in i18n config
-        - DO NOT generate any .tsx page files — pages are handled by the principal agent
-        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
-        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
-  # Wait for all agents to complete
-
-  # 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:
-      - 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')"
-    Generate form tests: co-located .test.tsx for Create and Edit pages
-
-ELSE:
-  # 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)
-       CRITICAL: paths MUST include module segment: {module_kebab}/{section_kebab} (e.g., employee-management/employees)
-    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
-
-When launching agents for multi-entity layers:
-- Each agent receives its task ID and metadata context in the prompt
-- Agent must call TaskUpdate(status: "in_progress") before starting
-- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
-- Agent principal monitors via TaskList() after all agents complete
-- Agent principal updates activeForm after each entity completion:
-  `TaskUpdate(taskId: layer3_task_id, activeForm: "Building {EntityName} frontend (2/5 entities)")`
-
-### Frontend Compliance Gate
-
-> See `references/smartstack-frontend-compliance.md` section 9 "Compliance Gates" for all 6 required 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)
-> 5. useTranslation in Pages (all text translated)
-> 6. SmartStack Components (no raw HTML tables — DataTable/EntityCard required)
-
-Do not commit frontend changes until all 6 gates pass.
-
-When delegating to `/ui-components` skill, include explicit instructions:
-- "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`."
-- "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/`."
-
-### Frontend Tests Inline
-
-> **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**
-
-```
-1. Scaffold frontend tests:
-   → For each module with create/edit pages:
-     → Generate EntityCreatePage.test.tsx and EntityEditPage.test.tsx
-     → Co-located next to the page component (NOT in __tests__/ folder)
-     → Cover: rendering, validation, submit, pre-fill, navigation, errors
-     → Tools: Vitest + React Testing Library + @testing-library/user-event
-     → Mock API: vi.mock() or MSW — NEVER real API calls
-
-2. Run tests:
-   WEB_DIR=$(find . -name "vitest.config.ts" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | head -1)
-   if [ -n "$WEB_DIR" ]; then
-     (cd "$WEB_DIR" && npm run test)
-   fi
-
-3. Fix loop (max 3 iterations):
-   IF tests fail:
-     → Identify root cause (ALWAYS code bug, not test bug)
-     → Fix production CODE
-     → Re-run tests
-     → Repeat until pass or max 3
-
-4. If still failing after 3 iterations: note failures, continue.
-   Step-07 "Final Test Sweep" will handle remaining failures.
-```
-
-### Typecheck Gate
-
-```bash
-npm run typecheck
-```
-
-Must pass before commit.
-
-TaskUpdate(taskId: layer3_task_id, status: "completed",
-  metadata: { build_gate: "pass" })
-
-### Layer 3 Commits
-
-```
-feat({module}): [frontend] pages, routes, i18n, documentation
-test({module}): frontend form tests
-```
-
----
-
-## Layer 4 — DevData (optional)
-
-### Task Progress
-IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "in_progress")
-IF layer4 task exists: TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-03 (Execute), Layer 4",
-  activeForm: "Executing Layer 4")
-
-> **Business test data for development/demo environments.**
-> Skip this layer if no meaningful test data is needed.
-
-```
-1. Create DevDataSeeder:
-   → Infrastructure/Persistence/Seeding/DevData/{Module}DevDataSeeder.cs
-   → ALL entities MUST include TenantId
-   → Realistic business data for demo purposes
-
-2. Build gate:
-   dotnet build → MUST PASS
-```
+## Layer Dispatch
 
-IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "completed",
-  metadata: { build_gate: "pass" })
+Load each sub-step sequentially:
 
-### Layer 4 Commit (if applicable)
+| Layer | Sub-step | Content |
+|-------|----------|---------|
+| 0 | `steps/step-03a-layer0-domain.md` | Domain entities, EF configs, migration |
+| 1 | `steps/step-03b-layer1-seed.md` | Seed data (navigation, permissions, roles) |
+| 2 | `steps/step-03c-layer2-backend.md` | Services, controllers, backend tests |
+| 3 | `steps/step-03d-layer3-frontend.md` | Pages, i18n, routes, frontend tests |
+| 4 | `steps/step-03e-layer4-devdata.md` | Development test data (optional) |
 
-```
-feat({module}): [devdata] test data for development
-```
+**FIRST ACTION:** Load `steps/step-03a-layer0-domain.md`
 
 ---
 
@@ -801,7 +90,7 @@ IF delegate_mode:
       task.completed_at = new Date().toISOString()
       task.iteration = 1  (delegate mode = single iteration)
       task.commit_hash = $(git rev-parse --short HEAD)
-      task.files_changed = { created: [...files created...], modified: [...files modified...] }
+      task.files_changed = { created: [...], modified: [...] }
       task.validation = "APEX_PASS" (or error details)
     prd.updated_at = new Date().toISOString()
     Write back to {delegate_prd_path}
@@ -811,8 +100,6 @@ IF delegate_mode:
 
 ## Commits Per Layer
 
-After each layer completes, gates pass, and builds pass:
-
 ```
 Layer 0: feat({module}): [domain+infra] {short description}
 Layer 1: feat({module}): [seed] navigation, permissions, roles
@@ -835,8 +122,7 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
 
 ```json
 {
-  "step": 3,
-  "layer": 2,
+  "step": 3, "layer": 2,
   "completed_layers": [0, 1, 2],
   "completed_entities": ["Employee", "Department"],
   "files_created": ["Employee.cs", "EmployeeConfiguration.cs", "..."],
@@ -846,19 +132,6 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
 }
 ```
 
-```
-IF .claude/output/apex/{task_id}/ does not exist:
-  Generate {task_id} from timestamp (e.g., "20260306-143000")
-  Create directory
-
-After EACH layer build gate passes:
-  Read existing state.json (or create new)
-  Update: layer, completed_layers, completed_entities, files_created, build_gates, commits
-  Write back to state.json
-```
-
-This file is consumed by resume mode (`-r`) to skip completed layers instead of re-deriving from git.
-
 ---
 
 ## Save Output (if save_mode)