@atlashub/smartstack-cli 3.5.0 → 3.7.0

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

@@ -0,0 +1,538 @@
+# Core Seed Data - Execution Reference
+
+> **Loaded by:** step-02-execute and step-04 compact loop
+> **Condition:** Infrastructure task involves core seed data or IClientSeedDataProvider
+> **Applies to:** Client projects only (seeding_strategy = "provider", ExtensionsDbContext)
+>
+> **Source of truth:** `/application` skill `templates-seed.md` (lines 608-916)
+
+---
+
+## 1. Parameter Extraction
+
+Extract navigation hierarchy from the task's `_seedDataMeta` (populated by guardrail 1e):
+
+```javascript
+const task = currentTask;
+const meta = task._seedDataMeta || task._providerMeta || {};
+const coreSeedData = meta.coreSeedData || {};
+
+// Navigation hierarchy
+const navModules = coreSeedData.navigationModules || coreSeedData.navigation || [];
+const permissions = coreSeedData.permissions || [];
+const rolePerms = coreSeedData.rolePermissions || [];
+
+// Derived context (from guardrail or PRD)
+const navRoute = meta.navRoute;         // e.g. "business.humanresources.projects"
+const contextCode = meta.contextCode;   // e.g. "business"
+const appCode = meta.appCode;           // e.g. "humanresources"
+const moduleCode = task.module;         // e.g. "projects"
+
+// If _seedDataMeta is absent, fallback to PRD source
+if (!navRoute) {
+  const prd = readJSON('.ralph/prd.json');
+  const navRoute = `${prd.source?.context || 'business'}.${prd.source?.application || prd.metadata?.module}.${task.module}`;
+}
+```
+
+**State variables after extraction:**
+
+| Variable | Example | Source |
+|----------|---------|--------|
+| `navRoute` | `business.humanresources.projects` | `_seedDataMeta.navRoute` |
+| `contextCode` | `business` | `_seedDataMeta.contextCode` |
+| `appCode` | `humanresources` | `_seedDataMeta.appCode` |
+| `moduleCode` | `projects` | `task.module` |
+| `navModules[]` | `[{code, label, icon, route, translations}]` | `coreSeedData.navigationModules` |
+| `permissions[]` | `[{path, action, description}]` | `coreSeedData.permissions` |
+| `rolePerms[]` | `[{role, permissions[]}]` | `coreSeedData.rolePermissions` |
+
+---
+
+## 2. NavigationModuleSeedData.cs
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/NavigationModuleSeedData.cs`
+
+### GUID Generation Rule
+
+```csharp
+// NEVER use Guid.NewGuid() — ALWAYS deterministic
+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());
+}
+
+// Usage: GUIDs are derived from the navigation path
+public static readonly Guid ModuleId = GenerateDeterministicGuid("navigation-module-{navRoute}");
+// Example: GenerateDeterministicGuid("navigation-module-business.humanresources.projects")
+```
+
+### Template
+
+```csharp
+using SmartStack.Domain.Navigation;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Navigation seed data for {ModuleLabel} module.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}NavigationSeedData
+{
+    // Deterministic GUID for this module
+    public static readonly Guid {ModulePascal}ModuleId =
+        GenerateDeterministicGuid("navigation-module-{navRoute}");
+
+    /// <summary>
+    /// Returns navigation module entry for seeding into core.nav_Modules.
+    /// </summary>
+    public static NavigationModuleSeedEntry GetModuleEntry(Guid applicationId)
+    {
+        return new NavigationModuleSeedEntry
+        {
+            Id = {ModulePascal}ModuleId,
+            ApplicationId = applicationId,
+            Code = "{moduleCode}",
+            Label = "{label_en}",
+            Description = "{desc_en}",
+            Icon = "{icon}",              // Lucide React icon name
+            IconType = IconType.Lucide,
+            Route = "/{contextCode}/{appCode}/{moduleCode}",
+            DisplayOrder = {displayOrder},
+            IsActive = true
+        };
+    }
+
+    /// <summary>
+    /// Returns 4-language translations for this module.
+    /// </summary>
+    public static IEnumerable<NavigationTranslationSeedEntry> GetTranslationEntries()
+    {
+        var moduleId = {ModulePascal}ModuleId;
+        return new[]
+        {
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "fr",
+                Label = "{label_fr}",
+                Description = "{desc_fr}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "en",
+                Label = "{label_en}",
+                Description = "{desc_en}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "it",
+                Label = "{label_it}",
+                Description = "{desc_it}"
+            },
+            new NavigationTranslationSeedEntry
+            {
+                EntityType = NavigationEntityType.Module,
+                EntityId = moduleId,
+                LanguageCode = "de",
+                Label = "{label_de}",
+                Description = "{desc_de}"
+            }
+        };
+    }
+
+    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());
+    }
+}
+
+/// <summary>Seed entry DTO for navigation module.</summary>
+public class NavigationModuleSeedEntry
+{
+    public Guid Id { get; init; }
+    public Guid ApplicationId { get; init; }
+    public string Code { get; init; } = null!;
+    public string Label { get; init; } = null!;
+    public string Description { get; init; } = null!;
+    public string Icon { get; init; } = null!;
+    public IconType IconType { get; init; }
+    public string Route { get; init; } = null!;
+    public int DisplayOrder { get; init; }
+    public bool IsActive { get; init; }
+}
+
+/// <summary>Seed entry DTO for navigation translation.</summary>
+public class NavigationTranslationSeedEntry
+{
+    public NavigationEntityType EntityType { get; init; }
+    public Guid EntityId { get; init; }
+    public string LanguageCode { get; init; } = null!;
+    public string Label { get; init; } = null!;
+    public string Description { get; init; } = null!;
+}
+```
+
+**Replace placeholders** with values from `navModules[]` and PRD `project` metadata.
+
+---
+
+## 3. PermissionsSeedData.cs — MCP-First
+
+### Step A: Call MCP (PRIMARY)
+
+```
+Tool: mcp__smartstack__generate_permissions
+Args:
+  navRoute: "{navRoute}"
+  includeStandardActions: true
+  includeWildcard: true
+```
+
+MCP returns:
+- `Permissions.cs` nested class (Application layer constants)
+- Permission seed entries with deterministic GUIDs
+
+### Step B: Write Permissions.cs (Application layer)
+
+```csharp
+// Add to Application/Common/Authorization/Permissions.cs
+public static class {ContextPascal}
+{
+    public const string Access = "{contextCode}.{appCode}";
+
+    public static class {ModulePascal}
+    {
+        public const string View = "{navRoute}.read";
+        public const string Create = "{navRoute}.create";
+        public const string Update = "{navRoute}.update";
+        public const string Delete = "{navRoute}.delete";
+    }
+}
+```
+
+### Step C: Write PermissionsSeedData.cs (Infrastructure layer)
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/PermissionsSeedData.cs`
+
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Permission seed data for {ModuleLabel} module.
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}PermissionsSeedData
+{
+    // Deterministic GUIDs for permissions
+    public static readonly Guid WildcardPermId = GenerateGuid("{navRoute}.*");
+    public static readonly Guid ReadPermId = GenerateGuid("{navRoute}.read");
+    public static readonly Guid CreatePermId = GenerateGuid("{navRoute}.create");
+    public static readonly Guid UpdatePermId = GenerateGuid("{navRoute}.update");
+    public static readonly Guid DeletePermId = GenerateGuid("{navRoute}.delete");
+
+    public static IEnumerable<PermissionSeedEntry> GetPermissionEntries(Guid moduleId)
+    {
+        return new[]
+        {
+            new PermissionSeedEntry { Id = WildcardPermId, Path = "{navRoute}.*", Level = PermissionLevel.Module, Action = PermissionAction.Access, IsWildcard = true, ModuleId = moduleId, Description = "Full {moduleLabel} access" },
+            new PermissionSeedEntry { Id = ReadPermId, Path = "{navRoute}.read", Level = PermissionLevel.Module, Action = PermissionAction.Read, IsWildcard = false, ModuleId = moduleId, Description = "View {moduleLabel}" },
+            new PermissionSeedEntry { Id = CreatePermId, Path = "{navRoute}.create", Level = PermissionLevel.Module, Action = PermissionAction.Create, IsWildcard = false, ModuleId = moduleId, Description = "Create {moduleLabel}" },
+            new PermissionSeedEntry { Id = UpdatePermId, Path = "{navRoute}.update", Level = PermissionLevel.Module, Action = PermissionAction.Update, IsWildcard = false, ModuleId = moduleId, Description = "Update {moduleLabel}" },
+            new PermissionSeedEntry { Id = DeletePermId, Path = "{navRoute}.delete", Level = PermissionLevel.Module, Action = PermissionAction.Delete, IsWildcard = false, ModuleId = moduleId, Description = "Delete {moduleLabel}" }
+        };
+    }
+
+    private static Guid GenerateGuid(string path)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes($"permission-{path}"));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+
+public class PermissionSeedEntry
+{
+    public Guid Id { get; init; }
+    public string Path { get; init; } = null!;
+    public PermissionLevel Level { get; init; }
+    public PermissionAction Action { get; init; }
+    public bool IsWildcard { get; init; }
+    public Guid ModuleId { get; init; }
+    public string Description { get; init; } = null!;
+}
+```
+
+### Step D: MCP Fallback
+
+If MCP `generate_permissions` fails, use the template above directly with values derived from the PRD `coreSeedData.permissions[]`.
+
+---
+
+## 4. RolesSeedData.cs
+
+**File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/RolesSeedData.cs`
+
+### Context-Based Role Mapping
+
+| Context | Admin | Manager | Contributor | Viewer |
+|---------|-------|---------|-------------|--------|
+| `platform.*` | CRUD | CRU | CR | R |
+| `business.*` | CRUD | CRU | CR | R |
+| `personal.*` | CRUD | CRU | CR | R |
+
+### Template
+
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data.{ModulePascal};
+
+/// <summary>
+/// Role-permission mapping seed data for {ModuleLabel} module.
+/// Maps permissions to application-scoped roles (Admin, Manager, Contributor, Viewer).
+/// Consumed by IClientSeedDataProvider at application startup.
+/// </summary>
+public static class {ModulePascal}RolesSeedData
+{
+    /// <summary>
+    /// Returns role-permission mappings for this module.
+    /// Roles are resolved at runtime by Code (not hardcoded GUIDs).
+    /// </summary>
+    public static IEnumerable<RolePermissionSeedEntry> GetRolePermissionEntries()
+    {
+        // Admin: wildcard access
+        yield return new RolePermissionSeedEntry { RoleCode = "admin", PermissionPath = "{navRoute}.*" };
+
+        // Manager: CRUD
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.read" };
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.create" };
+        yield return new RolePermissionSeedEntry { RoleCode = "manager", PermissionPath = "{navRoute}.update" };
+
+        // Contributor: CR
+        yield return new RolePermissionSeedEntry { RoleCode = "contributor", PermissionPath = "{navRoute}.read" };
+        yield return new RolePermissionSeedEntry { RoleCode = "contributor", PermissionPath = "{navRoute}.create" };
+
+        // Viewer: R
+        yield return new RolePermissionSeedEntry { RoleCode = "viewer", PermissionPath = "{navRoute}.read" };
+    }
+}
+
+public class RolePermissionSeedEntry
+{
+    public string RoleCode { get; init; } = null!;
+    public string PermissionPath { get; init; } = null!;
+}
+```
+
+---
+
+## 5. IClientSeedDataProvider Implementation
+
+**File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+
+### Critical Rules
+
+| Rule | Description |
+|------|-------------|
+| Factory methods | `NavigationModule.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 |
+| DI registration | `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()` |
+
+### Template
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+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.{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
+/// into the SmartStack Core schema at application startup.
+/// </summary>
+public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
+{
+    public int Order => 100;
+
+    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // --- Application ---
+        var exists = await context.NavigationApplications
+            .AnyAsync(a => a.Code == "{appCode}", ct);
+        if (exists) return;
+
+        var parentContext = await context.NavigationContexts
+            .FirstAsync(c => c.Code == "{contextCode}", ct);
+
+        var app = NavigationApplication.Create(
+            parentContext.Id, "{appCode}", "{appLabel_en}",
+            "{appDesc_en}", "{appIcon}", IconType.Lucide,
+            "/{contextCode}/{appCode}", 1);
+        context.NavigationApplications.Add(app);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Application translations (4 languages) ---
+        var appTranslations = new[]
+        {
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "fr", "{appLabel_fr}", "{appDesc_fr}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "en", "{appLabel_en}", "{appDesc_en}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "it", "{appLabel_it}", "{appDesc_it}"),
+            NavigationTranslation.Create(NavigationEntityType.Application, app.Id, "de", "{appLabel_de}", "{appDesc_de}")
+        };
+        foreach (var t in appTranslations) context.NavigationTranslations.Add(t);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Modules ---
+        // Module: {Module1}
+        var mod1Entry = {Module1Pascal}NavigationSeedData.GetModuleEntry(app.Id);
+        var mod1 = NavigationModule.Create(
+            mod1Entry.ApplicationId, mod1Entry.Code, mod1Entry.Label,
+            mod1Entry.Description, mod1Entry.Icon, mod1Entry.IconType,
+            mod1Entry.Route, mod1Entry.DisplayOrder);
+        context.NavigationModules.Add(mod1);
+
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Module translations ---
+        foreach (var t in {Module1Pascal}NavigationSeedData.GetTranslationEntries())
+        {
+            context.NavigationTranslations.Add(
+                NavigationTranslation.Create(t.EntityType, t.EntityId, t.LanguageCode, t.Label, t.Description));
+        }
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        var exists = await context.Permissions
+            .AnyAsync(p => p.Path == "{contextCode}.{appCode}.*", ct);
+        if (exists) return;
+
+        // Application-level wildcard
+        var appWildcard = Permission.CreateWildcard(
+            "{contextCode}.{appCode}.*", PermissionLevel.Application,
+            "Full {appLabel_en} access");
+        context.Permissions.Add(appWildcard);
+
+        // Module permissions
+        var mod1 = await context.NavigationModules
+            .FirstAsync(m => m.Code == "{module1Code}", ct);
+        foreach (var entry in {Module1Pascal}PermissionsSeedData.GetPermissionEntries(mod1.Id))
+        {
+            var perm = entry.IsWildcard
+                ? Permission.CreateWildcard(entry.Path, entry.Level, entry.Description)
+                : Permission.CreateForModule(entry.Path, entry.Level, entry.Action, false, entry.ModuleId, entry.Description);
+            context.Permissions.Add(perm);
+        }
+
+        // Repeat for each module...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        var exists = await context.RolePermissions
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{contextCode}.{appCode}."), ct);
+        if (exists) return;
+
+        // Resolve roles by Code
+        var roles = await context.Roles
+            .Where(r => r.ApplicationId != null || r.IsSystem)
+            .ToListAsync(ct);
+
+        // Resolve permissions
+        var permissions = await context.Permissions
+            .Where(p => p.Path.StartsWith("{contextCode}.{appCode}."))
+            .ToListAsync(ct);
+
+        // Apply role-permission mappings from all modules
+        var allMappings = new List<RolePermissionSeedEntry>();
+        allMappings.AddRange({Module1Pascal}RolesSeedData.GetRolePermissionEntries());
+        // allMappings.AddRange({Module2Pascal}RolesSeedData.GetRolePermissionEntries()); // per module
+
+        foreach (var mapping in allMappings)
+        {
+            var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);
+            var perm = permissions.FirstOrDefault(p => p.Path == mapping.PermissionPath);
+            if (role != null && perm != null)
+            {
+                context.RolePermissions.Add(RolePermission.Create(role.Id, perm.Id, "system"));
+            }
+        }
+
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+}
+```
+
+### DI Registration
+
+```csharp
+// In Infrastructure/DependencyInjection.cs — add:
+using SmartStack.Application.Common.Interfaces.Seeding;
+
+// In the registration method:
+services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
+```
+
+---
+
+## 6. 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)
+
+### 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)
+
+**Detection:** Check if `{AppPascalName}SeedDataProvider.cs` exists. If yes, READ it and ADD the new module's entries to each of the 3 methods.
+
+---
+
+## 7. 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)
+- [ ] `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
+- [ ] Each Seed method is idempotent (checks existence before inserting)
+- [ ] Factory methods used throughout (NEVER `new Entity()`)
+- [ ] `SaveChangesAsync` called per group (Navigation → Permissions → RolePermissions)
+- [ ] DI registration added: `services.AddScoped<IClientSeedDataProvider, ...>()`
+- [ ] `dotnet build` passes after generation
+
+**If ANY check fails, the task status = 'failed'.**

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

@@ -14,6 +14,8 @@ next_step: steps/step-01-task.md
 - YOU ARE AN INITIALIZER, not an executor
 - FORBIDDEN to load step-01 until init is complete
 - ALWAYS check prd.json version is v2
+- **CONTEXT BUDGET**: Keep init output COMPACT. Do NOT dump verbose MCP responses or long file listings. Every token saved here = more tokens for actual code generation in the COMPACT LOOP.
+- **NEVER DELEGATE**: Do NOT use the Task tool to delegate the Ralph loop to a sub-agent. The loop MUST run in the main agent context. Sub-agents lose skill context and stop prematurely.
 
 ## YOUR TASK:
 
@@ -199,7 +201,73 @@ mkdir -p .ralph/logs
 mkdir -p .ralph/reports
 ```
 
-### 4b. Detect Multi-Module PRDs (from BA Handoff)
+### 4a. Auto-Recovery: Detect BA Artifacts Without PRD (NEW)
+
+> **Scenario:** Business-analyse completed (feature.json with status="handed-off") but step-05b
+> didn't generate PRD files (context exhaustion). Ralph-loop auto-recovers by running `ss derive-prd`.
+
+**Check for BA artifacts when no PRD files exist:**
+
+```bash
+PRD_EXISTS=$(ls .ralph/prd-*.json 2>/dev/null | head -1)
+SINGLE_PRD_EXISTS=$(test -f .ralph/prd.json && echo "yes" || echo "no")
+```
+
+**IF no PRD files found (neither prd-*.json nor prd.json):**
+
+```bash
+# Search for handed-off master feature.json
+MASTER_FEATURE=$(find docs/business -maxdepth 4 -name "feature.json" -path "*/business-analyse/*" 2>/dev/null | head -1)
+```
+
+**IF master feature.json found:**
+
+```javascript
+const master = readJSON(MASTER_FEATURE);
+
+if (master.status === "handed-off" || master.handoff?.status === "handed-off") {
+  // BA completed but PRD files are missing — auto-recover
+  console.log("BA artifacts detected without PRD files — auto-recovering...");
+
+  // Display validation table
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  BA ARTIFACT VALIDATION                                          ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Master feature.json: ✅ Found (status: ${master.status})        ║
+║  Application: ${master.metadata?.application || 'unknown'}       ║
+║  Modules: ${master.modules?.length || 0}                         ║
+║  PRD files: ❌ Missing — will auto-generate                      ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Running: ss derive-prd --application ${MASTER_FEATURE}          ║
+╚══════════════════════════════════════════════════════════════════╝
+  `);
+
+  // Execute ss derive-prd to generate missing PRD files
+  // This is a deterministic CLI command (no LLM), safe to auto-run
+  exec(`ss derive-prd --application ${MASTER_FEATURE}`);
+
+  // Verify PRD files were generated
+  const newPrdFiles = glob('.ralph/prd-*.json');
+  if (newPrdFiles.length === 0) {
+    console.log("❌ ss derive-prd failed to generate PRD files");
+    console.log("   Verify: ss derive-prd is installed (npm list -g @atlashub/smartstack-cli)");
+    console.log("   Manual: ss derive-prd --application " + MASTER_FEATURE);
+    STOP;
+  }
+
+  console.log(`✅ Auto-recovered ${newPrdFiles.length} PRD files`);
+  // Continue to section 4b which will detect and queue them
+}
+```
+
+**IF master feature.json NOT found OR status ≠ "handed-off":**
+- No BA artifacts → proceed normally (step-01 will create prd.json from task description)
+
+**IF PRD files already exist:**
+- Skip auto-recovery entirely → proceed to section 4b
+
+### 4b. Detect Multi-Module PRDs (from BA Handoff or Auto-Recovery)
 
 **After creating `.ralph/` directory, check for per-module PRD files:**
 
@@ -263,6 +331,16 @@ Queue: {module codes joined by " → "}
 Starting with: {modules[0].code}
 ```
 
+6. **Display BA artifact validation (if from BA handoff):**
+```
+[CHECK] BA Artifact Validation:
+  ✓ Master feature.json: {MASTER_FEATURE} (status: handed-off)
+  ✓ Module feature.json: {module_count} modules (all handed-off)
+  ✓ PRD files: {PRD_COUNT} modules (.ralph/prd-*.json)
+  ✓ progress.txt: {exists ? "present" : "will be created"}
+  [PASS] All BA artifacts valid. Multi-module development ready.
+```
+
 **If only `.ralph/prd.json` exists (single module):**
 - Skip queue creation (backward compatible)
 - Proceed normally

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -499,7 +499,19 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
         "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs"
       ], modified: [] },
       validation: null, error: null, module: moduleCode,
-      _seedDataMeta: { source: "guardrail-derived", coreSeedData }
+      _seedDataMeta: {
+        source: "guardrail-derived",
+        coreSeedData,
+        navRoute: prdJson.project?.navRoute
+          || (permissions?.[0]?.path?.split('.').slice(0, -1).join('.'))
+          || `business.${prdJson.project?.application || 'app'}.${moduleCode}`,
+        contextCode: prdJson.project?.context
+          || coreSeedData.navigationModules?.[0]?.route?.split('/')?.[1]
+          || 'business',
+        appCode: prdJson.project?.application
+          || coreSeedData.navigationModules?.[0]?.route?.split('/')?.[2],
+        appLabels: prdJson.project?.labels || null
+      }
     });
     lastIdByCategory["infrastructure"] = taskId;
     taskId++;
@@ -530,7 +542,18 @@ function transformPrdJsonToRalphV2(prdJson, moduleCode) {
       ].join("; "),
       started_at: null, completed_at: null, iteration: null, commit_hash: null,
       files_changed: { created: ["src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs"], modified: ["src/Infrastructure/DependencyInjection.cs"] },
-      validation: null, error: null, module: moduleCode
+      validation: null, error: null, module: moduleCode,
+      _providerMeta: {
+        consumesSeedDataFiles: [
+          `Infrastructure/Persistence/Seeding/Data/${moduleCode}/NavigationModuleSeedData.cs`,
+          `Infrastructure/Persistence/Seeding/Data/${moduleCode}/PermissionsSeedData.cs`,
+          `Infrastructure/Persistence/Seeding/Data/${moduleCode}/RolesSeedData.cs`
+        ],
+        navRoute: prdJson.project?.navRoute
+          || `business.${prdJson.project?.application || 'app'}.${moduleCode}`,
+        contextCode: prdJson.project?.context || 'business',
+        appCode: prdJson.project?.application
+      }
     });
     lastIdByCategory["infrastructure"] = taskId;
     taskId++;