@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/ralph-loop/references/core-seed-data.md

@@ -279,7 +279,129 @@ If MCP `generate_permissions` fails, use the template above directly with values
 
 ---
 
-## 4. RolesSeedData.cs
+## 4. ApplicationRolesSeedData.cs (Application-Level, Once per Application)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs`
+
+### Purpose
+
+Creates the 4 standard application-scoped roles: Admin, Manager, Contributor, Viewer.
+
+**CRITICAL:** This file is created **ONCE per application** (not per module).
+Without these roles, role-permission mappings in `SeedRolePermissionsAsync()` will fail silently.
+
+### GUID Generation Rule
+
+```csharp
+// Deterministic GUID from application ID + role type
+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());
+}
+// roleType values: "admin", "manager", "contributor", "viewer"
+```
+
+### 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
+{
+    // Application ID from NavigationApplicationSeedData
+    private static readonly Guid ApplicationId = {ApplicationGuid};
+
+    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");
+
+    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());
+    }
+}
+
+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; }
+}
+```
+
+**Replace placeholders** with values from PRD and navigation metadata.
+
+---
+
+## 5. {Module}RolesSeedData.cs (Per Module)
 
 **File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/RolesSeedData.cs`
 
@@ -335,7 +457,7 @@ public class RolePermissionSeedEntry
 
 ---
 
-## 5. IClientSeedDataProvider Implementation
+## 6. IClientSeedDataProvider Implementation
 
 **File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
 
@@ -343,10 +465,11 @@ public class RolePermissionSeedEntry
 
 | Rule | Description |
 |------|-------------|
-| Factory methods | `NavigationModule.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
+| Factory methods | `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
 | Idempotence | Each Seed method checks existence before inserting |
-| SaveChanges per group | Navigation -> save -> Permissions -> save -> RolePermissions -> save |
-| FK resolution by Code | Parent entities found by `Code`, not hardcoded GUID |
+| Execution order | Navigation → Roles → Permissions → RolePermissions (roles MUST exist before mapping) |
+| SaveChanges per group | Navigation -> save -> Roles -> save -> Permissions -> save -> RolePermissions -> save |
+| FK resolution by Code | Parent entities (modules, roles) found by `Code`, not hardcoded GUID |
 | DI registration | `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()` |
 
 ### Template
@@ -357,13 +480,14 @@ using SmartStack.Application.Common.Interfaces;
 using SmartStack.Application.Common.Interfaces.Seeding;
 using SmartStack.Domain.Navigation;
 using SmartStack.Domain.Platform.Administration.Roles;
+using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
 using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module1Pascal};
 // using {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{Module2Pascal}; // Add per module
 
 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.
 /// </summary>
 public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
@@ -420,6 +544,28 @@ 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)
+        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)
     {
         var exists = await context.Permissions
@@ -495,44 +641,110 @@ services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
 
 ---
 
-## 6. Multi-Module Handling
+## 7. Multi-Module Handling
 
 When processing multiple modules in the same ralph-loop run:
 
 ### Module 1 (first): Creates everything from scratch
 
-1. `{Module1}NavigationSeedData.cs`
-2. `{Module1}PermissionsSeedData.cs`
-3. `{Module1}RolesSeedData.cs`
-4. `{AppPascalName}SeedDataProvider.cs` (new)
-5. DI registration (new)
+1. `ApplicationRolesSeedData.cs` (application-level, once per app)
+2. `{Module1}NavigationSeedData.cs`
+3. `{Module1}PermissionsSeedData.cs`
+4. `{Module1}RolesSeedData.cs`
+5. `{AppPascalName}SeedDataProvider.cs` (new, with 4 methods)
+6. DI registration (new)
 
 ### Module 2+ (subsequent): Append to existing provider
 
-1. `{Module2}NavigationSeedData.cs` (new file)
-2. `{Module2}PermissionsSeedData.cs` (new file)
-3. `{Module2}RolesSeedData.cs` (new file)
-4. `{AppPascalName}SeedDataProvider.cs` (**modify** — add using, add entries in each Seed method)
-5. DI registration (already exists — skip)
+1. `ApplicationRolesSeedData.cs` (already exists — skip)
+2. `{Module2}NavigationSeedData.cs` (new file)
+3. `{Module2}PermissionsSeedData.cs` (new file)
+4. `{Module2}RolesSeedData.cs` (new file)
+5. `{AppPascalName}SeedDataProvider.cs` (**modify** — add using, add entries in Navigation/Permissions/RolePermissions methods)
+6. DI registration (already exists — skip)
 
-**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to each of the 3 methods.
+**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to the appropriate methods (Navigation, Permissions, RolePermissions). Do NOT modify SeedRolesAsync().
 
 ---
 
-## 7. Verification Checklist (BLOCKING)
+## 8. Verification Checklist (BLOCKING)
 
 Before marking the task as completed, verify ALL:
 
 - [ ] Deterministic GUIDs (NEVER `Guid.NewGuid()`) — SHA256 of path
 - [ ] 4 languages for each navigation entity (fr, en, it, de)
+- [ ] `ApplicationRolesSeedData.cs` created (once per application)
+- [ ] 4 application roles defined: Admin, Manager, Contributor, Viewer
+- [ ] Each role has a valid `Code` value ("admin", "manager", "contributor", "viewer")
 - [ ] `Permissions.cs` constants match seed data paths
 - [ ] MCP `generate_permissions` called (or fallback used)
 - [ ] Role-permission mappings assigned (Admin, Manager, Contributor, Viewer)
-- [ ] `IClientSeedDataProvider` generated with 3 methods
+- [ ] `IClientSeedDataProvider` generated with 4 methods (Navigation, Roles, Permissions, RolePermissions)
+- [ ] Execution order: Navigation → Roles → Permissions → RolePermissions
 - [ ] Each Seed method is idempotent (checks existence before inserting)
 - [ ] Factory methods used throughout (NEVER `new Entity()`)
-- [ ] `SaveChangesAsync` called per group (Navigation → Permissions → RolePermissions)
+- [ ] `SaveChangesAsync` called per group (Navigation → Roles → Permissions → RolePermissions)
 - [ ] DI registration added: `services.AddScoped<IClientSeedDataProvider, ...>()`
 - [ ] `dotnet build` passes after generation
 
 **If ANY check fails, the task status = 'failed'.**
+
+---
+
+## 9. Business Seed Data (DevDataSeeder) — TenantId Rules
+
+> **Applies to:** Seed data for business entities (reference types, categories, statuses).
+> **NOT the same as** core seed data above (navigation, permissions, roles).
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| TenantId MANDATORY | ALL business seed entities MUST set `TenantId` |
+| Deterministic TenantId | Use `SeedConstants.DefaultTenantId` (NEVER inline GUID) |
+| DevDataSeeder pattern | Implement `IDevDataSeeder` with `SeedAsync()` method |
+| Idempotency | Each seeder MUST check `AnyAsync()` before inserting |
+| Order | DevDataSeeder `Order >= 200` (after core seed data at Order 100) |
+
+### Template (Reference Types)
+
+```csharp
+public class {Module}DevDataSeeder : IDevDataSeeder
+{
+    public int Order => 200; // After core seed data (Order 100)
+
+    public async Task SeedAsync(ExtensionsDbContext context, CancellationToken ct)
+    {
+        if (await context.Set<{EntityType}>().AnyAsync(ct)) return;
+
+        var items = new[]
+        {
+            new {EntityType}
+            {
+                Id = GenerateDeterministicGuid("{entity-type}-{code}"),
+                Code = "{code}",
+                Name = "{name}",
+                TenantId = SeedConstants.DefaultTenantId,  // MANDATORY
+                IsActive = true
+            }
+        };
+
+        context.Set<{EntityType}>().AddRange(items);
+        await context.SaveChangesAsync(ct);
+    }
+
+    private static Guid GenerateDeterministicGuid(string seed)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(seed));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+```
+
+### FORBIDDEN
+
+- Seeding business entities WITHOUT `TenantId`
+- Using `Guid.NewGuid()` for TenantId
+- Omitting idempotency check (`AnyAsync`)
+- Hardcoding TenantId inline (use `SeedConstants.DefaultTenantId`)

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -48,7 +48,70 @@ mcp__context7__resolve-library-id: libraryName: "test"  → {mcp_context7} = tru
 
 If ANY fails: show error, suggest `smartstack check-mcp`, STOP.
 
-## 3. Resume Mode
+## 3. Human-in-the-Loop Checkpoint (RECOMMENDED)
+
+> **Best Practice:** Commencer en mode supervisé avant le mode autonome complet.
+
+### Why HITL First?
+
+Ralph-loop est puissant mais peut diverger si :
+- Les requirements sont ambigus
+- Les tests sont lents (>30s)
+- Le code généré ne compile pas immédiatement
+
+**Stratégie recommandée :**
+
+1. **Première itération supervisée** - Lancer manuellement la première tâche pour vérifier :
+   - La qualité du code généré
+   - Le temps d'exécution des tests
+   - La clarté des messages d'erreur
+
+2. **Mode autonome limité** - Si première itération OK, relancer avec `--max-iterations 5-10`
+
+3. **Mode autonome complet** - Une fois confiant, augmenter à `--max-iterations 50`
+
+### Checkpoint Prompt (Optional)
+
+Si vous détectez que c'est la première utilisation de ralph-loop sur ce projet (pas de `.ralph/logs/`), proposer :
+
+```javascript
+if (!dirExists('.ralph/logs') && !resume_mode) {
+  AskUserQuestion({
+    questions: [{
+      question: "Premier usage de ralph-loop détecté. Démarrer en mode supervisé ou autonome ?",
+      header: "Mode",
+      multiSelect: false,
+      options: [
+        { label: "Supervisé (recommandé)", description: "Exécuter 1 tâche, puis demander confirmation" },
+        { label: "Autonome limité", description: "Max 10 itérations automatiques" },
+        { label: "Autonome complet", description: "Jusqu'à 50 itérations (mode AFK)" }
+      ]
+    }]
+  });
+
+  if (answer === "Supervisé") {
+    max_iterations = 1;
+    console.log("Mode supervisé : 1 tâche sera exécutée. Relancez avec -r pour continuer.");
+  } else if (answer === "Autonome limité") {
+    max_iterations = Math.min(max_iterations, 10);
+  }
+}
+```
+
+### Feedback Speed Warning
+
+⚠️ **IMPORTANT :** Si vos tests prennent >30 secondes, ralph-loop peut devenir inefficace.
+
+```
+Temps test recommandés :
+  - Unitaires : <5s
+  - Intégration : <15s
+  - E2E : <30s (à exécuter en dehors du loop)
+```
+
+Si tests lents détectés (via logs), avertir l'utilisateur et suggérer de désactiver tests E2E pendant le loop.
+
+## 4. Resume Mode
 
 If `{resume_mode} = true`:
 

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -40,12 +40,20 @@ if [ -d "$TEST_PROJECT" ]; then
   dotnet test "$TEST_PROJECT" --no-build --verbosity normal
   if [ $? -ne 0 ]; then
     echo "TEST REGRESSION — creating fix task"
-    # Inject fix task into prd.json:
     prd.tasks.push({ id: maxId+1, description: "Fix test regression — all tests must pass",
       status: "pending", category: "validation", dependencies: [],
       acceptance_criteria: "dotnet test exits 0, all tests pass" });
     writeJSON('.ralph/prd.json', prd);
   fi
+else
+  # CRITICAL: Test project MUST exist if test tasks are marked completed
+  const testTasksDone = prd.tasks.filter(t => t.category === 'test' && t.status === 'completed');
+  if (testTasksDone.length > 0) {
+    echo "ARTIFACT MISSING — test tasks marked completed but no test project exists"
+    // Reset test tasks to pending and inject guardrail
+    testTasksDone.forEach(t => { t.status = 'pending'; t.error = null; t.completed_at = null; });
+    writeJSON('.ralph/prd.json', prd);
+  fi
 fi
 ```
 
@@ -99,11 +107,28 @@ if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
 
-  // MODULE COMPLETENESS CHECK: verify all expected layers
+  // MODULE COMPLETENESS CHECK: verify all expected layers AND their artifacts
   const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
   const expected = ['domain', 'infrastructure', 'application', 'api', 'frontend', 'test'];
   const missing = expected.filter(c => !completedCats.has(c));
 
+  // ARTIFACT EXISTENCE CHECK: categories with completed tasks must have real files
+  const artifactChecks = {
+    'infrastructure': () => fs.existsSync('src/*/Persistence/Migrations') && fs.readdirSync('src/*/Persistence/Migrations').length > 0,
+    'test': () => fs.existsSync(`tests/${projectName}.Tests.Unit`) && glob.sync('tests/**/*Tests.cs').length > 0,
+    'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0,
+    'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0
+  };
+  for (const [cat, check] of Object.entries(artifactChecks)) {
+    if (completedCats.has(cat) && !check()) {
+      // Tasks marked completed but artifacts missing — reset to pending
+      prd.tasks.filter(t => t.category === cat && t.status === 'completed')
+        .forEach(t => { t.status = 'pending'; t.error = 'Artifacts missing — re-execute'; t.completed_at = null; });
+      missing.push(cat);
+      console.log(`ARTIFACT RESET: ${cat} tasks reset to pending (no files found)`);
+    }
+  }
+
   if (missing.length > 0) {
     // Inject guardrail tasks for missing layers
     let maxId = Math.max(...prd.tasks.map(t => t.id));