@atlashub/smartstack-cli 3.9.0 → 3.10.0

package/package.json

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

package/templates/agents/ba-writer.md

@@ -88,6 +88,102 @@ Merge a section into an existing feature.json.
 9. **Cross-Reference Validation (for specification and handoff sections):** See CROSS-REFERENCE VALIDATION section below
 10. Return confirmation with section size and status
 
+### enrichSectionIncremental
+Incrementally update a section in feature.json using PATCH-style operations instead of full section replacement. Optimized for large files and preventing file size issues.
+
+**Input:**
+- featureId: FEAT-NNN or full path to feature.json
+- section: one of [discovery, analysis, specification, validation, handoff, suggestions, cadrage, consolidation, modules, dependencyGraph, metadata.workflow]
+- operation: "merge" | "append" | "update" | "delete"
+- path: JSON path within the section (e.g., "entities[2]", "useCases", "modules[0].status")
+- data: the data to merge/append/update
+
+**Operations:**
+
+1. **merge** - Deep merge data into existing section
+   ```javascript
+   // Example: Add new entities to analysis.entities without rewriting entire analysis
+   enrichSectionIncremental({
+     featureId: "FEAT-001",
+     section: "analysis",
+     operation: "merge",
+     path: "entities",
+     data: [
+       { name: "NewEntity", description: "...", attributes: [...] }
+     ]
+   })
+   // Result: analysis.entities now has existing entities + NewEntity
+   ```
+
+2. **append** - Append item to an array
+   ```javascript
+   // Example: Add a single business rule without rewriting all rules
+   enrichSectionIncremental({
+     featureId: "FEAT-001",
+     section: "analysis",
+     operation: "append",
+     path: "businessRules",
+     data: { id: "BR-VAL-ABC-042", name: "...", statement: "..." }
+   })
+   ```
+
+3. **update** - Update specific field in section
+   ```javascript
+   // Example: Update module status without rewriting entire modules array
+   enrichSectionIncremental({
+     featureId: "FEAT-001",
+     section: "modules",
+     operation: "update",
+     path: "[0].status",  // Path to first module's status field
+     data: "handed-off"
+   })
+   ```
+
+4. **delete** - Remove item from section
+   ```javascript
+   // Example: Remove a specific entity
+   enrichSectionIncremental({
+     featureId: "FEAT-001",
+     section: "analysis",
+     operation: "delete",
+     path: "entities[2]"  // Delete third entity
+   })
+   ```
+
+**Process:**
+1. Find and read feature.json (use findFeature if given ID)
+2. Navigate to the specified section
+3. Apply the incremental operation:
+   - **merge**: Deep merge arrays (append unique items), shallow merge objects
+   - **append**: Push item to array at path
+   - **update**: Set value at path
+   - **delete**: Remove item at path
+4. Update metadata.updatedAt with current timestamp
+5. Update metadata.updatedBy with agent name
+6. Write back with pretty-print (2-space indent)
+7. **File Size Check:** If resulting file > 100KB, display WARNING
+8. Validate schema before writing
+9. **Cross-Reference Validation:** Same rules as enrichSection
+10. Return confirmation with operation summary and file size
+
+**File Size Management:**
+- Before write: Check if file would exceed 100KB
+- If > 100KB: Display WARNING with recommendation to split into smaller operations
+- If > 500KB: BLOCKING ERROR - file too large, must use smaller chunks
+- Track cumulative file size growth across operations
+
+**Advantages over enrichSection:**
+- 50-70% reduction in tokens for large sections
+- Avoids "file too large" errors by updating incrementally
+- Allows progressive enrichment without reading/writing entire sections
+- Better performance for repeated updates (e.g., module loop)
+
+**Use Cases:**
+- Adding entities one-by-one during module specification
+- Updating module status in master without rewriting all modules
+- Appending business rules progressively
+- Updating handoff sections module-by-module
+
 ### enrichModuleHandoff
 Write the handoff section into a module feature.json. Specialized operation for step-05 module loop.
 
@@ -474,6 +570,88 @@ Before EVERY enrichSection() call for specification or handoff sections, validat
 6. **Pretty-print JSON** - use 2-space indentation
 7. **Timestamp management** - always set metadata.updatedAt to current ISO timestamp on write
 8. **Idempotency** - calling the same operation twice with same data should produce same result
+9. **File size management** - check file size before write, use incremental operations for large files
+
+## File Size Management (CRITICAL)
+
+**Problem:** Large feature.json files (>100KB) can cause write failures and token exhaustion.
+
+**Solution:** Progressive monitoring and incremental operations.
+
+### Size Thresholds
+
+| File Size | Status | Action |
+|-----------|--------|--------|
+| < 50KB | ✓ Safe | Use enrichSection normally |
+| 50-100KB | ⚠ Warning | Display warning, recommend enrichSectionIncremental for next operations |
+| 100-500KB | ⚠ High | STRONGLY recommend enrichSectionIncremental, limit enrichSection use |
+| > 500KB | ✗ Critical | BLOCK enrichSection, REQUIRE enrichSectionIncremental or split file |
+
+### Pre-Write File Size Check
+
+Before EVERY write operation:
+
+```javascript
+const currentFileSize = getFileSize(featurePath);
+const estimatedNewSize = currentFileSize + newDataSize;
+
+if (estimatedNewSize > 100 * 1024) {  // 100KB
+  WARNING(`Feature.json will be ${formatBytes(estimatedNewSize)} after write`);
+  WARNING(`Recommend using enrichSectionIncremental for future operations`);
+}
+
+if (estimatedNewSize > 500 * 1024) {  // 500KB
+  BLOCKING_ERROR(`Feature.json would exceed 500KB (${formatBytes(estimatedNewSize)})`);
+  BLOCKING_ERROR(`Use enrichSectionIncremental instead of enrichSection`);
+  STOP;
+}
+```
+
+### Operation Selection Guide
+
+| Scenario | Recommended Operation | Reason |
+|----------|----------------------|--------|
+| First-time section write | `enrichSection` | No existing data, full write needed |
+| Module loop (3+ iterations) | `enrichSectionIncremental` | Avoids rewriting same data multiple times |
+| Large sections (>20KB) | `enrichSectionIncremental` | Reduces token usage by 50-70% |
+| File size > 100KB | `enrichSectionIncremental` (REQUIRED) | Prevents file size bloat |
+| Single field update | `enrichSectionIncremental` with `update` | Most efficient for targeted changes |
+
+### Monitoring & Reporting
+
+After EVERY write, report file size status:
+
+```
+✓ feature.json written successfully
+  Path: docs/business/HumanResources/Projects/business-analyse/v1.0/feature.json
+  Size: 87.3 KB (↑ 12.1 KB from previous)
+  Status: ⚠ Approaching 100KB threshold
+  Recommendation: Use enrichSectionIncremental for remaining modules
+```
+
+### Splitting Large Files (Advanced)
+
+If a module feature.json exceeds 500KB despite incremental operations:
+
+1. **Split specification section** into separate files:
+   - `specification-entities.json` (entities, relationships)
+   - `specification-rules.json` (business rules, validations)
+   - `specification-ui.json` (wireframes, sections, navigation)
+
+2. **Update feature.json** with file references:
+   ```json
+   {
+     "specification": {
+       "$ref": "./specification-entities.json",
+       "$ref2": "./specification-rules.json",
+       "$ref3": "./specification-ui.json"
+     }
+   }
+   ```
+
+3. **ba-reader** auto-resolves references when reading
+
+**Note:** File splitting is a LAST RESORT. Prefer enrichSectionIncremental first.
 
 ## Error Handling
 

package/templates/skills/application/references/application-roles-template.md

@@ -0,0 +1,227 @@
+# Application Roles Seed Data Template
+
+> Referenced from `core-seed-data.md` and `step-03-roles.md` — C# template for application-scoped roles in client projects.
+
+---
+
+## Problem Statement
+
+When using `IClientSeedDataProvider` (client projects with `seeding_strategy = "provider"`), role-permission mappings reference roles by their `Code`:
+
+```csharp
+var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);  // "admin", "manager", "contributor", "viewer"
+```
+
+**However**, the current templates do NOT create these application-scoped roles. They assume:
+- System roles (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser) exist in Core
+- Application-scoped roles (Admin, Manager, Contributor, Viewer) already exist with valid `Code` values
+
+**Result:** Role-permission mappings fail silently when `role == null`.
+
+---
+
+## Solution: Application Roles Seed Data
+
+Create application-scoped roles with deterministic GUIDs and valid `Code` values.
+
+---
+
+## File Location
+
+**Path:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+This file should be created **ONCE per application** (not per module).
+
+---
+
+## Template
+
+```csharp
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+
+/// <summary>
+/// Application-scoped role seed data for {AppLabel}.
+/// Defines the 4 standard application roles: Admin, Manager, Contributor, Viewer.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class ApplicationRolesSeedData
+{
+    // Deterministic GUIDs for application roles
+    // Generated from: "role-{applicationId}-{roleType}"
+    private static readonly Guid ApplicationId = {ApplicationGuid}; // From NavigationApplicationSeedData
+
+    public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
+    public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
+    public static readonly Guid ContributorRoleId = GenerateRoleGuid("contributor");
+    public static readonly Guid ViewerRoleId = GenerateRoleGuid("viewer");
+
+    /// <summary>
+    /// Returns application-scoped role entries for seeding into core.auth_Roles.
+    /// </summary>
+    public static IEnumerable<ApplicationRoleSeedEntry> GetRoleEntries()
+    {
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = AdminRoleId,
+            Code = "admin",
+            Name = "{AppLabel} Admin",
+            Description = "Full administrative access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 1
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ManagerRoleId,
+            Code = "manager",
+            Name = "{AppLabel} Manager",
+            Description = "Management access to {AppLabel} (Create, Read, Update)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 2
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ContributorRoleId,
+            Code = "contributor",
+            Name = "{AppLabel} Contributor",
+            Description = "Contributor access to {AppLabel} (Create, Read)",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 3
+        };
+
+        yield return new ApplicationRoleSeedEntry
+        {
+            Id = ViewerRoleId,
+            Code = "viewer",
+            Name = "{AppLabel} Viewer",
+            Description = "Read-only access to {AppLabel}",
+            ApplicationId = ApplicationId,
+            IsSystem = false,
+            IsActive = true,
+            DisplayOrder = 4
+        };
+    }
+
+    private static Guid GenerateRoleGuid(string roleType)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"role-{ApplicationId}-{roleType}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+/// <summary>Seed entry DTO for application role.</summary>
+public class ApplicationRoleSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Code { get; init; } = null!;
+    public string Name { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public Guid ApplicationId { get; init; }
+    public bool IsSystem { get; init; }
+    public bool IsActive { get; init; }
+    public int DisplayOrder { get; init; }
+}
+```
+
+---
+
+## Placeholder Replacement
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
+| `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
+| `{ApplicationGuid}` | GUID of the application (from NavigationApplicationSeedData) | `30f1fbba-e8c3-4879-9a49-d18deaa70a83` |
+
+---
+
+## Integration into IClientSeedDataProvider
+
+Add a new method `SeedRolesAsync()` to the provider:
+
+```csharp
+public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+{
+    // Check idempotence
+    var exists = await context.Roles
+        .AnyAsync(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId, ct);
+    if (exists) return;
+
+    // Create application-scoped roles using factory method
+    foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+    {
+        var role = Role.Create(
+            entry.Code,
+            entry.Name,
+            entry.Description,
+            entry.ApplicationId,
+            entry.IsSystem);
+
+        context.Roles.Add(role);
+    }
+
+    await ((DbContext)context).SaveChangesAsync(ct);
+}
+```
+
+---
+
+## Execution Order in Provider
+
+**CRITICAL:** Roles must be created BEFORE role-permission mappings.
+
+```
+1. SeedNavigationAsync()   → Creates application + modules + translations
+2. SeedRolesAsync()         → Creates application-scoped roles (NEW)
+3. SeedPermissionsAsync()   → Creates permissions
+4. SeedRolePermissionsAsync() → Maps roles to permissions (now succeeds because roles exist)
+```
+
+---
+
+## Verification Checklist
+
+Before marking the task as completed, verify:
+
+- [ ] `ApplicationRolesSeedData.cs` created in `Infrastructure/Persistence/Seeding/Data/`
+- [ ] Deterministic GUIDs used (NEVER `Guid.NewGuid()`)
+- [ ] 4 roles defined: Admin, Manager, Contributor, Viewer
+- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
+- [ ] Each role has `ApplicationId` set to the application GUID
+- [ ] `SeedRolesAsync()` method added to `IClientSeedDataProvider`
+- [ ] `SeedRolesAsync()` is idempotent (checks existence before inserting)
+- [ ] `Role.Create()` factory method used (NEVER `new Role()`)
+- [ ] `SaveChangesAsync()` called after role creation
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
+- [ ] `dotnet build` passes after generation
+
+---
+
+## Notes
+
+- **Application ID source:** Read from the navigation application created in `SeedNavigationAsync()` or from `{AppPascal}NavigationSeedData.cs`
+- **Role factory method:** Use `Role.Create(code, name, description, applicationId, isSystem)` from SmartStack.Domain
+- **Code uniqueness:** Role codes must be unique within the application scope
+- **System roles:** These are NOT system roles (IsSystem = false) - they are application-scoped roles
+- **Tenant isolation:** Application-scoped roles are automatically tenant-isolated via the Core authorization system
+
+---
+
+## Migration Impact
+
+**For existing projects without application roles:**
+1. Generate `ApplicationRolesSeedData.cs` using this template
+2. Add `SeedRolesAsync()` method to the existing `IClientSeedDataProvider`
+3. Update the provider's execution to call `SeedRolesAsync()` BEFORE `SeedRolePermissionsAsync()`
+4. Run the application - roles will be created on next startup
+5. Role-permission mappings will now succeed

package/templates/skills/application/references/provider-template.md

@@ -19,7 +19,7 @@ using SmartStack.Domain.Platform.Administration.Roles;
 namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
 
 /// <summary>
-/// Seeds {AppLabel} navigation, permissions, and role-permission data
+/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
 /// into the SmartStack Core schema at application startup.
 /// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
 /// (no Core migrations required).
@@ -75,6 +75,29 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         await ((DbContext)context).SaveChangesAsync(ct);
     }
 
+    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var applicationId = ApplicationRolesSeedData.ApplicationId;
+        var exists = await context.Roles
+            .AnyAsync(r => r.ApplicationId == applicationId, ct);
+        if (exists) return;
+
+        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
+        // Use data from ApplicationRolesSeedData.cs
+        foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+        {
+            var role = Role.Create(
+                entry.Code,
+                entry.Name,
+                entry.Description,
+                entry.ApplicationId,
+                entry.IsSystem);
+            context.Roles.Add(role);
+        }
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
     public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
     {
         // Check idempotence
@@ -126,9 +149,10 @@ services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
 
 ## Critical Rules
 
-1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
+1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
 2. **Idempotence**: Each Seed method checks existence before inserting
-3. **SaveChangesAsync per group**: Navigation → save → Permissions → save → RolePermissions → save
-4. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
-5. **Resolve FK by Code**: Parent modules are found by `Code`, not hardcoded GUID
-6. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence
+3. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
+4. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
+5. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
+6. **Resolve FK by Code**: Parent modules and roles are found by `Code`, not hardcoded GUID
+7. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence

package/templates/skills/application/steps/step-03-roles.md

@@ -1,23 +1,29 @@
 ---
 name: step-03-roles
-description: Generate role-permission mappings using MCP scaffold_role_permissions (with fallback)
+description: Generate application roles and role-permission mappings using MCP scaffold_role_permissions (with fallback)
 prev_step: steps/step-02-permissions.md
 next_step: steps/step-03b-provider.md
 ---
 
-# Step 3: Role-Permission Mapping
+# Step 3: Application Roles & Role-Permission Mapping
 
 ## MANDATORY EXECUTION RULES
 
+- For **client projects** (`seeding_strategy = "provider"`): Generate ApplicationRolesSeedData.cs and module role mappings
+- For **core projects** (`seeding_strategy = "hasdata"`): Use RolePermissionConfiguration.cs
 - PREFER MCP `scaffold_role_permissions` tool as the primary method
 - If MCP is unavailable or the call fails, use the FALLBACK PROCEDURE below
 - ALWAYS assign permissions to default roles
 - NEVER leave permissions without role assignments
-- ALWAYS WRITE generated code to the actual RolePermissionConfiguration.cs file
+- ALWAYS WRITE generated code to the actual files
 
 ## YOUR TASK
 
-Generate role-permission mappings:
+For **client projects**:
+1. **ApplicationRolesSeedData.cs** (once per application) — defines the 4 application-scoped roles
+2. **{Module}RolePermissionSeedData.cs** (per module) — maps permissions to roles by Code
+
+For **core projects**:
 1. RolePermissionConfiguration.cs HasData() entries
 2. Default role assignments (SuperAdmin, PlatformAdmin, TenantAdmin, StandardUser)
 3. Application-scoped role assignments (Admin, Manager, Contributor, Viewer)
@@ -131,13 +137,38 @@ If MCP call fails or `{mcp_available}` = false:
 **For core (`{seeding_strategy}` = "hasdata"):** Write in RolePermissionConfiguration.cs (existing pattern)
 
 **For client (`{seeding_strategy}` = "provider"):** DO NOT write in RolePermissionConfiguration.cs (does not exist in client projects).
-Instead, create:
-- `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+Instead, create TWO files:
+
+### 1. ApplicationRolesSeedData.cs (ONCE per application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+**Purpose:** Defines the 4 standard application-scoped roles (Admin, Manager, Contributor, Viewer) with valid `Code` values.
+
+**CRITICAL:** Without this file, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently because `roles.FirstOrDefault(r => r.Code == mapping.RoleCode)` will return null.
+
+See [references/application-roles-template.md](../references/application-roles-template.md) for the complete template.
+
+**Key requirements:**
+- Deterministic GUIDs based on `role-{applicationId}-{roleType}`
+- 4 roles: Admin, Manager, Contributor, Viewer
+- Each role has a valid `Code` property ("admin", "manager", "contributor", "viewer")
+- `ApplicationId` references the navigation application GUID
+- `IsSystem = false` (application-scoped, not system roles)
+
+**Detection:** Check if ApplicationRolesSeedData.cs exists. If yes, skip creation (already exists from Module 1). If no, create it.
+
+### 2. {Module}RolePermissionSeedData.cs (PER module)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}RolePermissionSeedData.cs`
+
+**Purpose:** Maps permissions to roles by Code (e.g., "admin" → "{navRoute}.*").
 
 Content: static class with method `GetRolePermissionEntries()` that returns the role-permission mapping data.
 These entries will be consumed by the `IClientSeedDataProvider` at step 03b.
 
-**After creating RolePermission SeedData:** Proceed to step-03b-provider.md (which will skip for core projects).
+**After creating both files:** Proceed to step-03b-provider.md (which will skip for core projects).
 
 ---
 
@@ -280,6 +311,13 @@ If user selects "Custom adjustments", ask which roles/permissions to change and
 
 ## SUCCESS METRICS
 
+**For client projects:**
+- ApplicationRolesSeedData.cs created (once per application)
+- {Module}RolePermissionSeedData.cs created with role-permission mappings
+- All 4 application roles defined with valid Code values
+- Proceeded to step-03b-provider.md
+
+**For core projects:**
 - Role-permission mappings generated (via MCP or fallback)
 - RolePermissionConfiguration.cs WRITTEN with new entries
 - All default roles have appropriate access

package/templates/skills/application/steps/step-03b-provider.md

@@ -50,9 +50,10 @@ From previous steps:
 ## FILES TO GENERATE
 
 See [references/provider-template.md](../references/provider-template.md) for the complete implementation:
-- **Provider class** (`{AppPascalName}SeedDataProvider.cs`) with 3 seed methods (Navigation, Permissions, RolePermissions)
+- **ApplicationRolesSeedData.cs** (once per application) — defines application-scoped roles (Admin, Manager, Contributor, Viewer)
+- **Provider class** (`{AppPascalName}SeedDataProvider.cs`) with 4 seed methods (Navigation, Roles, Permissions, RolePermissions)
 - **DI registration** pattern for `Infrastructure/DependencyInjection.cs`
-- **6 critical rules** (factory methods, idempotence, SaveChangesAsync order, deterministic GUIDs, FK by Code, Order property)
+- **7 critical rules** (factory methods, idempotence, execution order, SaveChangesAsync order, deterministic GUIDs, FK by Code, Order property)
 
 ---
 
@@ -64,9 +65,11 @@ Identify all SeedData files created in previous steps:
 
 ```
 Glob: **/Persistence/Seeding/Data/{Domain}/*SeedData.cs
+Glob: **/Persistence/Seeding/Data/ApplicationRolesSeedData.cs
 ```
 
 Expected files:
+- `ApplicationRolesSeedData.cs` (application-level, once per app)
 - `{Module}NavigationSeedData.cs` (from step 01)
 - `{Module}NavigationTranslationSeedData.cs` (from step 01)
 - `{Module}PermissionSeedData.cs` (from step 02)
@@ -96,9 +99,11 @@ Add the `IClientSeedDataProvider` registration.
 ### 4. Verify
 
 Before proceeding to step-04, verify:
-- [ ] Provider generated with 3 methods (SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync)
+- [ ] ApplicationRolesSeedData.cs created (once per application)
+- [ ] Provider generated with 4 methods (SeedNavigationAsync, SeedRolesAsync, SeedPermissionsAsync, SeedRolePermissionsAsync)
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
 - [ ] Registered in DI (`services.AddScoped<IClientSeedDataProvider, ...>()`)
-- [ ] Consumes SeedData classes from steps 01-03
+- [ ] Consumes SeedData classes from steps 01-03 + ApplicationRolesSeedData
 - [ ] Idempotent (check existence before insert)
 - [ ] Uses factory methods (no `new Entity()`)
 
@@ -106,9 +111,11 @@ Before proceeding to step-04, verify:
 
 ## SUCCESS METRICS
 
-- Provider class generated with all 3 seed methods
+- ApplicationRolesSeedData.cs created (application-level)
+- Provider class generated with all 4 seed methods (Navigation, Roles, Permissions, RolePermissions)
+- Correct execution order enforced
 - DI registration added
-- SeedData classes from steps 01-03 properly consumed
+- SeedData classes from steps 01-03 + ApplicationRolesSeedData properly consumed
 - All methods are idempotent
 - Factory methods used throughout
 - Proceeded to step-04-backend.md