@atlashub/smartstack-cli 3.8.0 → 3.9.0

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

@@ -1,974 +1,157 @@
 ---
 name: step-01-task
-description: Load or create tasks from prd.json (v2 schema)
+description: Load or create tasks from prd.json (v3 unified or v2 legacy)
 next_step: steps/step-02-execute.md
 ---
 
 # Step 1: Load Task
 
-> **MODULE TRANSITION CHECK (MANDATORY):**
-> Before applying the "Only Read Once" rule, check for module transition marker:
+> **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
 
 ```javascript
-const moduleChangedPath = '.ralph/module-changed.json';
-const moduleTransition = fileExists(moduleChangedPath);
-
-if (moduleTransition) {
-  const transitionData = readJSON(moduleChangedPath);
-  console.log(`🔄 Module transition detected: ${transitionData.fromModule} → ${transitionData.toModule}`);
-  console.log(`   Reloading step-01 to initialize new module...`);
-
-  // Delete flag (consume it)
-  deleteFile(moduleChangedPath);
-
-  // PROCEED with step-01 execution (skip "Only Read Once" rule below)
-  // This is the EXCEPTION case for multi-module workflows
+if (fileExists('.ralph/module-changed.json')) {
+  const t = readJSON('.ralph/module-changed.json');
+  console.log(`Module transition: ${t.fromModule} → ${t.toModule}`);
+  deleteFile('.ralph/module-changed.json');
+  // PROCEED (exception to "Only Read Once" rule)
 }
 ```
 
-> **CONTEXT OPTIMIZATION:** This file is normally read ONCE per module (first iteration).
-> After the first full iteration (step-01 → step-02 → step-03 → step-04),
-> ALL subsequent iterations within the SAME module MUST use the COMPACT LOOP in step-04-check.md section 5.
-> **DO NOT re-read this file for iterations > 1 of the same module.**
->
-> **EXCEPTION:** When transitioning between modules (multi-module workflows), step-01 MUST be re-read
-> to load the next module's PRD. This is signaled by `.ralph/module-changed.json` file (checked above).
->
-> If you are re-reading this file on iteration > 1 AND no module transition detected, STOP and go to step-04 section 5 instead.
+> **CONTEXT OPTIMIZATION:** Read ONCE per module (first iteration).
+> Iterations > 1 within same module → use COMPACT LOOP in step-04.
+> Re-read ONLY on module transition (module-changed.json detected above).
 
 ## YOUR TASK:
 
-Load the current task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
-
-**ULTRA THINK about task decomposition.**
+Load task from prd.json or create initial task breakdown with categories, dependencies, and acceptance criteria.
 
 ---
 
-## EXECUTION SEQUENCE:
-
-### 0. Multi-Module Queue Check
-
-**✅ ALWAYS check for modules-queue.json, even on iteration > 1:**
-
-> **CRITICAL:** This section MUST execute even when step-01 is re-read for module transitions.
-> The module-changed.json flag (checked above) ensures this section runs when needed.
+## 0. Multi-Module Queue Check
 
 ```javascript
 const queuePath = '.ralph/modules-queue.json';
-const hasQueue = fileExists(queuePath);
-
-if (hasQueue) {
+if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
+  console.log(`Multi-module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})`);
 
-  console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  Multi-Module Workflow Detected                                 ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Current Module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})                    ║
-║  Status: ${currentModule.status}                                ║
-║  PRD File: ${currentModule.prdFile}                             ║
-╚══════════════════════════════════════════════════════════════════╝
-  `);
-
-  // ✅ FIX #3: RESTORE multi-module state variables
-  // These variables persist across step files and are critical for multi-module coordination
   {modules_queue} = queue;
   {current_module} = currentModule.code;
 
-  // ✅ Load or verify current module's PRD is in .ralph/prd.json
-  // On module transition, step-04 already loaded it, but we verify here
+  // Verify PRD matches current module
   const currentPrd = readJSON('.ralph/prd.json');
-
-  // Verify PRD matches current module (sanity check)
-  if (currentPrd.metadata && currentPrd.metadata.moduleCode !== currentModule.code) {
-    console.log(`⚠️  PRD mismatch detected. Loading correct PRD for module ${currentModule.code}...`);
-
-    // Load current module's PRD
+  if (currentPrd.metadata?.moduleCode !== currentModule.code) {
     const modulePrd = readJSON(currentModule.prdFile);
 
-    // Transform PrdJson format to Ralph v2 if needed
-    if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
-      // This is a PrdJson format from ss derive-prd → transform to Ralph v2
-      const transformedPrd = transformPrdJsonToRalphV2(modulePrd, currentModule.code);
-      writeJSON('.ralph/prd.json', transformedPrd);
-      console.log(`✅ Transformed and loaded PRD for module: ${currentModule.code}`);
-    } else {
-      // Already Ralph v2 format
+    // v3 FAST PATH: unified PRD from ss derive-prd (tasks pre-computed)
+    if (modulePrd.$version === '3.0.0') {
+      // Inject runtime fields and use directly
+      modulePrd.status = 'in_progress';
+      modulePrd.feature = `${modulePrd.project?.module || currentModule.code} (${modulePrd.project?.application || 'app'})`;
+      modulePrd.created = modulePrd.created || new Date().toISOString();
+      modulePrd.updated_at = new Date().toISOString();
+      modulePrd.config = modulePrd.config || { max_iterations: {max_iterations}, completion_promise: "{completion_promise}", current_iteration: 1 };
+      modulePrd.metadata.branch = modulePrd.metadata.branch || getCurrentBranch();
+      modulePrd.metadata.project_path = modulePrd.metadata.project_path || process.cwd();
+      modulePrd.metadata.mcp_servers = modulePrd.metadata.mcp_servers || { smartstack: true, context7: true };
+      modulePrd.history = modulePrd.history || [];
+      writeJSON('.ralph/prd.json', modulePrd);
+    }
+    // LEGACY: FORMAT A (no $version) — transform + warning
+    else if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
+      console.warn('⚠ DEPRECATED: FORMAT A prd.json detected. Re-run `ss derive-prd` to generate v3 format.');
+      writeJSON('.ralph/prd.json', transformPrdJsonToRalphV2(modulePrd, currentModule.code));
+    }
+    // v2 legacy or already runtime format
+    else {
       writeJSON('.ralph/prd.json', modulePrd);
-      console.log(`✅ Loaded PRD for module: ${currentModule.code}`);
     }
-  } else {
-    console.log(`✅ PRD already loaded for module: ${currentModule.code}`);
   }
-
-  console.log(`State restored: modules_queue and current_module set`);
 } else {
-  // Single-module workflow
   {modules_queue} = null;
   {current_module} = null;
 }
 ```
 
-**PrdJson → Ralph v2 transformation:**
-
-The PrdJson format (from `ss derive-prd`) has this structure:
-```
-{ version, source, project, requirements: { useCases[], functionalRequirements[] },
-  businessRules[], architecture: { entities[], apiEndpoints[], sections[] },
-  implementation: { filesToCreate: { domain[], application[], infrastructure[], api[], frontend[], tests[] } },
-  seedData }
-```
-
-```javascript
-function transformPrdJsonToRalphV2(prdJson, moduleCode) {
-  const tasks = [];
-  let taskId = 1;
-
-  // Layer processing order (SmartStack convention)
-  const layerOrder = [
-    { key: "domain",         category: "domain" },
-    { key: "infrastructure", category: "infrastructure" },
-    { key: "application",    category: "application" },
-    { key: "api",            category: "api" },
-    { key: "frontend",       category: "frontend" },
-    { key: "seedData",       category: "infrastructure" },
-    { key: "tests",          category: "test" }
-  ];
-
-  // Support BOTH formats: nested (from ss derive-prd) and flat (LLM-generated)
-  const filesToCreate = prdJson.implementation?.filesToCreate
-                     || prdJson.filesToCreate
-                     || {};
-
-  // 1. Generate tasks from implementation.filesToCreate (primary source)
-  //    CRITICAL: Frontend and i18n tasks are CONSOLIDATED into ONE module-level task each.
-  //    These use MCP scaffolding tools, NOT manual file-by-file generation.
-  const lastIdByCategory = {};
-  const frontendFiles = [];  // Collect frontend files for consolidated task
-  const i18nFiles = [];      // Collect i18n files for consolidated task
-
-  for (const layer of layerOrder) {
-    const files = filesToCreate[layer.key] || [];
-
-    // FRONTEND & I18N: Collect files, do NOT create individual tasks
-    if (layer.category === "frontend") {
-      frontendFiles.push(...files);
-      continue;  // Skip individual task creation
-    }
-
-    for (const fileSpec of files) {
-      // Check if this is an i18n file (category "infrastructure" but path contains i18n)
-      if (fileSpec.path?.includes('i18n/') || fileSpec.path?.includes('/locales/')) {
-        i18nFiles.push(fileSpec);
-        continue;  // Skip individual task creation
-      }
-
-      const depIds = [];
-      // Depend on last task in same category (sequential within layer)
-      if (lastIdByCategory[layer.category]) {
-        depIds.push(lastIdByCategory[layer.category]);
-      }
-      // Cross-layer: api depends on last application task
-      if (layer.category === "api" && lastIdByCategory["application"]) {
-        depIds.push(lastIdByCategory["application"]);
-      }
-      if (layer.category === "test" && lastIdByCategory["api"]) {
-        depIds.push(lastIdByCategory["api"]);
-      }
-
-      // Build acceptance criteria from linked FRs and UCs
-      // Support both nested (requirements.functionalRequirements) and flat (functionalRequirements) formats
-      const allFRs = prdJson.requirements?.functionalRequirements || prdJson.functionalRequirements || [];
-      const linkedFRs = (fileSpec.linkedFRs || [])
-        .map(frId => {
-          const fr = allFRs.find(f => f.id === frId);
-          return fr ? fr.statement : frId;
-        });
-      let criteria = linkedFRs.length > 0
-        ? `Implements: ${linkedFRs.join("; ")}`
-        : `File ${fileSpec.path} created and compiles correctly`;
-
-      // Enhance acceptance criteria for API tasks with permission enforcement
-      const permMatrix = prdJson.architecture?.permissionMatrix || prdJson.permissionMatrix;
-      if (layer.category === "api" && permMatrix?.permissions?.length > 0) {
-        criteria += "; MANDATORY: [RequirePermission] attributes on every endpoint (NOT [Authorize])";
-      }
-
-      tasks.push({
-        id: taskId,
-        description: fileSpec.description
-          ? `[${layer.category}] ${fileSpec.description} → ${fileSpec.path}`
-          : `[${layer.category}] Create ${fileSpec.type}: ${fileSpec.path}`,
-        status: "pending",
-        category: layer.category,
-        dependencies: [...new Set(depIds)],
-        acceptance_criteria: criteria,
-        started_at: null,
-        completed_at: null,
-        iteration: null,
-        commit_hash: null,
-        files_changed: { created: [fileSpec.path], modified: [] },
-        validation: null,
-        error: null,
-        module: moduleCode
-      });
-
-      lastIdByCategory[layer.category] = taskId;
-      taskId++;
-    }
-  }
-
-  // 1b. Create CONSOLIDATED frontend task (ONE task per module, uses MCP tools)
-  if (frontendFiles.length > 0) {
-    const apiDepId = lastIdByCategory["api"] || lastIdByCategory["application"];
-    const allLinkedUCs = [...new Set(frontendFiles.flatMap(f => f.linkedUCs || []))];
-    const allLinkedWireframes = [...new Set(frontendFiles.flatMap(f => f.linkedWireframes || []))];
-    const allPaths = frontendFiles.map(f => f.path);
-
-    tasks.push({
-      id: taskId,
-      description: `[frontend] Generate COMPLETE frontend for module ${moduleCode} via MCP scaffold tools (${frontendFiles.length} files: pages, components, hooks, API client)`,
-      status: "pending",
-      category: "frontend",
-      dependencies: apiDepId ? [apiDepId] : [],
-      acceptance_criteria: [
-        "MCP scaffold_api_client called → API client + types generated",
-        "MCP scaffold_routes called → routes.tsx updated with nested routes inside Layout wrapper",
-        "Pages match wireframes: " + allLinkedWireframes.join(", "),
-        "SmartTable for lists (NOT HTML tables), EntityCard for grids (NOT custom divs)",
-        "CSS variables ONLY (NO hardcoded Tailwind colors like bg-blue-600)",
-        "useNavigate + useParams for routing, NOT window.location",
-        "Loading/error/empty states on all pages",
-        "4-language i18n keys (fr, en, it, de)",
-        "npm run typecheck passes"
-      ].join("; "),
-      started_at: null,
-      completed_at: null,
-      iteration: null,
-      commit_hash: null,
-      files_changed: { created: allPaths, modified: [] },
-      validation: null,
-      error: null,
-      module: moduleCode,
-      _frontendMeta: {
-        wireframes: allLinkedWireframes,
-        linkedUCs: allLinkedUCs,
-        filesToCreate: frontendFiles
-      }
-    });
-
-    lastIdByCategory["frontend"] = taskId;
-    taskId++;
-  }
-
-  // 1c. Create CONSOLIDATED i18n task (ONE task per module)
-  if (i18nFiles.length > 0) {
-    tasks.push({
-      id: taskId,
-      description: `[i18n] Generate i18n translations for module ${moduleCode} (4 languages: fr, en, it, de)`,
-      status: "pending",
-      category: "i18n",
-      dependencies: lastIdByCategory["frontend"] ? [lastIdByCategory["frontend"]] : [],
-      acceptance_criteria: "4 JSON files (fr, en, it, de) with identical keys; all UI labels translated",
-      started_at: null,
-      completed_at: null,
-      iteration: null,
-      commit_hash: null,
-      files_changed: { created: i18nFiles.map(f => f.path), modified: [] },
-      validation: null,
-      error: null,
-      module: moduleCode
-    });
-    lastIdByCategory["i18n"] = taskId;
-    taskId++;
-  }
-
-  // 1d. GUARDRAIL: Inject missing layer tasks when filesToCreate is incomplete
-  //     This handles LLM-generated PRDs that omit layers present in the source data.
-  //     Uses architecture data (entities, apiEndpoints, sections, wireframes) as fallback.
-
-  const entities = prdJson.architecture?.entities || prdJson.entities || [];
-  const apiEndpoints = prdJson.architecture?.apiEndpoints || prdJson.apiEndpoints || [];
-  const sections = prdJson.architecture?.sections || prdJson.sections || [];
-  const wireframes = prdJson.specification?.uiWireframes || prdJson.uiWireframes || [];
-  const dashboards = prdJson.specification?.dashboards || prdJson.dashboards || [];
-
-  const hasDomainTasks = tasks.some(t => t.category === 'domain');
-  const hasInfraTasks = tasks.some(t => t.category === 'infrastructure');
-  const hasApiTasks = tasks.some(t => t.category === 'api');
-  const hasFrontendTasks = frontendFiles.length > 0; // Already handled in 1b
-  const hasTestTasks = tasks.some(t => t.category === 'test');
-
-  // INJECT consolidated infrastructure task if missing
-  if (!hasInfraTasks && entities.length > 0) {
-    const domainDepId = lastIdByCategory["domain"];
-    tasks.push({
-      id: taskId,
-      description: `[infrastructure] Create EF Core configurations, services, and seed data for module ${moduleCode} (${entities.length} entities)`,
-      status: "pending",
-      category: "infrastructure",
-      dependencies: domainDepId ? [domainDepId] : [],
-      acceptance_criteria: `EF Core configs for all ${entities.length} entities; Service implementations; DbSet in ExtensionsDbContext; DI registration; Seed data`,
-      started_at: null, completed_at: null, iteration: null, commit_hash: null,
-      files_changed: { created: [], modified: [] },
-      validation: null, error: null, module: moduleCode
-    });
-    lastIdByCategory["infrastructure"] = taskId;
-    taskId++;
-    console.log(`⚠️ GUARDRAIL: Injected missing [infrastructure] task from ${entities.length} entities`);
-  }
-
-  // INJECT consolidated API task if missing
-  if (!hasApiTasks && apiEndpoints.length > 0) {
-    const appDepId = lastIdByCategory["application"] || lastIdByCategory["infrastructure"];
-    const permMatrix = prdJson.architecture?.permissionMatrix || prdJson.permissionMatrix;
-    const hasPermissions = permMatrix?.permissions?.length > 0;
-
-    tasks.push({
-      id: taskId,
-      description: `[api] Create API controllers for module ${moduleCode} (${apiEndpoints.length} endpoints)`,
-      status: "pending",
-      category: "api",
-      dependencies: appDepId ? [appDepId] : [],
-      acceptance_criteria: [
-        `Controllers for all ${apiEndpoints.length} endpoints`,
-        hasPermissions
-          ? "MANDATORY: [RequirePermission(Permissions.{Action})] on EVERY endpoint (NOT generic [Authorize])"
-          : "Authorization attributes",
-        "Swagger docs"
-      ].join("; "),
-      started_at: null, completed_at: null, iteration: null, commit_hash: null,
-      files_changed: { created: [], modified: [] },
-      validation: null, error: null, module: moduleCode
-    });
-    lastIdByCategory["api"] = taskId;
-    taskId++;
-    console.log(`⚠️ GUARDRAIL: Injected missing [api] task from ${apiEndpoints.length} endpoints`);
-  }
+## PrdJson → Ralph v2 Transformation (DEPRECATED)
 
-  // CRITICAL: INJECT consolidated frontend task if missing
-  // This is the MOST COMMON failure mode — LLM-generated PRDs often omit frontend
-  if (!hasFrontendTasks && (sections.length > 0 || wireframes.length > 0 || apiEndpoints.length > 0)) {
-    const apiDepId = lastIdByCategory["api"] || lastIdByCategory["application"];
-
-    // Derive frontend file list from available data sources
-    const derivedFrontendFiles = [];
-
-    // From wireframes → pages
-    for (const wf of wireframes) {
-      const screenId = wf.screen || wf.id;
-      derivedFrontendFiles.push({
-        path: `web/src/pages/${moduleCode}/${screenId}.tsx`,
-        type: screenId.includes('dashboard') ? 'DashboardPage' : 'Page',
-        linkedWireframes: [screenId],
-        linkedUCs: wf.linkedUCs || [],
-      });
-    }
+> **DEPRECATED:** This transformation is a fallback for old FORMAT A PRDs (pre-v3.9.0).
+> New PRDs generated by `ss derive-prd` use unified v3 format with pre-computed tasks.
+> This function will be removed in a future release.
 
-    // From dashboards → dashboard pages (if not already from wireframes)
-    for (const dash of dashboards) {
-      const dashId = dash.code || dash.id;
-      if (!derivedFrontendFiles.some(f => f.path.includes(dashId))) {
-        derivedFrontendFiles.push({
-          path: `web/src/pages/${moduleCode}/${dashId}.tsx`,
-          type: 'DashboardPage',
-          linkedWireframes: [dashId],
-          dashboardRef: dashId,
-        });
-      }
-    }
-
-    // From API endpoints → API client service
-    if (apiEndpoints.length > 0) {
-      derivedFrontendFiles.push({
-        path: `web/src/services/api/${moduleCode}Api.ts`,
-        type: 'ApiService',
-      });
-    }
-
-    const allWireframeIds = derivedFrontendFiles.flatMap(f => f.linkedWireframes || []);
-
-    tasks.push({
-      id: taskId,
-      description: `[frontend] Generate COMPLETE frontend for module ${moduleCode} via MCP scaffold tools (${derivedFrontendFiles.length} files: pages, components, hooks, API client)`,
-      status: "pending",
-      category: "frontend",
-      dependencies: apiDepId ? [apiDepId] : [],
-      acceptance_criteria: [
-        "MCP scaffold_api_client called → API client + types generated",
-        "MCP scaffold_routes called → routes.tsx updated with nested routes inside Layout wrapper",
-        allWireframeIds.length > 0 ? "Pages match wireframes: " + allWireframeIds.join(", ") : "Pages created for all UI sections",
-        "SmartTable for lists (NOT HTML tables), EntityCard for grids (NOT custom divs)",
-        "CSS variables ONLY (NO hardcoded Tailwind colors like bg-blue-600)",
-        "useNavigate + useParams for routing, NOT window.location",
-        "Loading/error/empty states on all pages",
-        "4-language i18n keys (fr, en, it, de)",
-        "npm run typecheck passes"
-      ].join("; "),
-      started_at: null, completed_at: null, iteration: null, commit_hash: null,
-      files_changed: { created: derivedFrontendFiles.map(f => f.path), modified: [] },
-      validation: null, error: null, module: moduleCode,
-      _frontendMeta: {
-        wireframes: allWireframeIds,
-        filesToCreate: derivedFrontendFiles,
-        source: "guardrail-derived"
-      }
-    });
-    lastIdByCategory["frontend"] = taskId;
-    taskId++;
-    console.log(`⚠️ GUARDRAIL: Injected missing [frontend] task derived from ${wireframes.length} wireframes + ${dashboards.length} dashboards + ${apiEndpoints.length} endpoints`);
-
-    // Also inject i18n task if not already present
-    if (i18nFiles.length === 0) {
-      tasks.push({
-        id: taskId,
-        description: `[i18n] Generate i18n translations for module ${moduleCode} (4 languages: fr, en, it, de)`,
-        status: "pending",
-        category: "i18n",
-        dependencies: [lastIdByCategory["frontend"]],
-        acceptance_criteria: "4 JSON files (fr, en, it, de) with identical keys; all UI labels translated",
-        started_at: null, completed_at: null, iteration: null, commit_hash: null,
-        files_changed: { created: [], modified: [] },
-        validation: null, error: null, module: moduleCode
-      });
-      lastIdByCategory["i18n"] = taskId;
-      taskId++;
-    }
-  }
-
-  // INJECT consolidated test task if missing
-  if (!hasTestTasks && entities.length > 0) {
-    const apiDepId = lastIdByCategory["api"] || lastIdByCategory["application"];
-    tasks.push({
-      id: taskId,
-      description: `[test] Create unit and integration tests for module ${moduleCode}`,
-      status: "pending",
-      category: "test",
-      dependencies: apiDepId ? [apiDepId] : [],
-      acceptance_criteria: "Domain unit tests + service unit tests + controller integration tests; dotnet test passes; coverage >= 80%",
-      started_at: null, completed_at: null, iteration: null, commit_hash: null,
-      files_changed: { created: [], modified: [] },
-      validation: null, error: null, module: moduleCode
-    });
-    lastIdByCategory["test"] = taskId;
-    taskId++;
-    console.log(`⚠️ GUARDRAIL: Injected missing [test] task`);
-  }
-
-  // 1e. GUARDRAIL: Inject seedData tasks when core seed data exists but filesToCreate.seedData is empty
-  //     This is the MOST CRITICAL guardrail — without core seed data, the application has:
-  //     - No navigation menu entries
-  //     - No RBAC permissions in the database
-  //     - No role-permission mappings
-  //     - Controllers accessible to ANY authenticated user
-  const coreSeedData = prdJson.seedData?.core
-                    || prdJson.seedDataCore
-                    || prdJson.specification?.seedDataCore;
-  const hasSeedDataTasks = (filesToCreate["seedData"]?.length ?? 0) > 0;
-  const hasSeedDataInTasks = tasks.some(t =>
-    t.description?.includes("SeedData") || t.description?.includes("seed data"));
-
-  if (coreSeedData && !hasSeedDataTasks && !hasSeedDataInTasks) {
-    const infraDepId = lastIdByCategory["infrastructure"] || lastIdByCategory["domain"];
-
-    // Derive navigation/permissions/roles from coreSeedData
-    const navModules = coreSeedData.navigationModules || coreSeedData.navigation || [];
-    const permissions = coreSeedData.permissions || [];
-    const rolePerms = coreSeedData.rolePermissions || [];
-
-    // Inject consolidated core seedData task
-    tasks.push({
-      id: taskId,
-      description: `[infrastructure] Create core seed data files for module ${moduleCode}: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedConstants`,
-      status: "pending",
-      category: "infrastructure",
-      dependencies: infraDepId ? [infraDepId] : [],
-      acceptance_criteria: [
-        `NavigationModuleSeedData.cs with ${navModules.length} navigation module(s)`,
-        `PermissionsSeedData.cs with ${permissions.length} permission(s) from seedData.core`,
-        `RolesSeedData.cs with ${rolePerms.length} role-permission mapping(s)`,
-        "SeedConstants.cs with deterministic GUIDs",
-        "All seed data classes are static with GetSeedData() method"
-      ].join("; "),
-      started_at: null, completed_at: null, iteration: null, commit_hash: null,
-      files_changed: { created: [
-        `src/Infrastructure/Persistence/Seeding/Data/${moduleCode}/NavigationModuleSeedData.cs`,
-        `src/Infrastructure/Persistence/Seeding/Data/${moduleCode}/PermissionsSeedData.cs`,
-        `src/Infrastructure/Persistence/Seeding/Data/${moduleCode}/RolesSeedData.cs`,
-        "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs"
-      ], modified: [] },
-      validation: null, error: null, module: moduleCode,
-      _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++;
-    console.log(`GUARDRAIL: Injected missing [infrastructure] core seed data task from seedData.core (${navModules.length} nav, ${permissions.length} perms, ${rolePerms.length} roles)`);
-  }
-
-  // 2. Add IClientSeedDataProvider task for client projects (ExtensionsDbContext)
-  // This is MANDATORY - without it, core seed data (navigation, permissions, roles) is dead code
-  const hasClientSeedData = filesToCreate["seedData"]?.some(f =>
-    f.type === "IClientSeedDataProvider" || f.path?.includes("SeedDataProvider"));
-  const hasProviderInTasks = tasks.some(t =>
-    t.description?.includes("IClientSeedDataProvider") || t.description?.includes("SeedDataProvider"));
-
-  // Trigger when: seedData files exist OR coreSeedData exists (fallback for incomplete PRDs)
-  if (!hasClientSeedData && !hasProviderInTasks &&
-      (filesToCreate["seedData"]?.length > 0 || coreSeedData)) {
-    tasks.push({
-      id: taskId,
-      description: `[infrastructure] Create IClientSeedDataProvider to inject core seed data (navigation, permissions, roles) at runtime`,
-      status: "pending",
-      category: "infrastructure",
-      dependencies: [lastIdByCategory["infrastructure"] || lastIdByCategory["domain"]].filter(Boolean),
-      acceptance_criteria: [
-        "Implements IClientSeedDataProvider with SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync",
-        "Registered in DI: services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()",
-        "All methods are idempotent (check existence before inserting)",
-        "Consumes seed data from NavigationModuleSeedData, PermissionsSeedData, RolesSeedData"
-      ].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,
-      _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++;
-  }
-
-  // 3. Add a final validation task
-  tasks.push({
-    id: taskId,
-    description: `[validation] Build, test, and MCP validate module ${moduleCode}`,
-    status: "pending",
-    category: "validation",
-    dependencies: Object.values(lastIdByCategory),
-    acceptance_criteria: "dotnet build succeeds, dotnet test passes, MCP validate_conventions clean",
-    started_at: null,
-    completed_at: null,
-    iteration: null,
-    commit_hash: null,
-    files_changed: { created: [], modified: [] },
-    validation: null,
-    error: null,
-    module: moduleCode
-  });
-
-  return {
-    $version: "2.0.0",
-    feature: `${prdJson.project?.module || moduleCode} (${prdJson.project?.application || "app"})`,
-    status: "in_progress",
-    created: new Date().toISOString(),
-    updated_at: new Date().toISOString(),
-    metadata: {
-      cli_version: "unknown",
-      branch: getCurrentBranch(),
-      project_path: process.cwd(),
-      mcp_servers: { smartstack: true, context7: true },
-      module: moduleCode
-    },
-    config: {
-      max_iterations: {max_iterations},
-      completion_promise: "{completion_promise}",
-      current_iteration: 1
-    },
-    source: {
-      type: "ba-handoff",
-      handoff_path: null,
-      feature_json_path: prdJson.source?.featureJson || null,
-      module: moduleCode
-    },
-    tasks: tasks,
-    history: []
-  };
-}
-```
-
-**If no queue exists:** proceed with standard logic below (backward compatible).
+See [references/task-transform-legacy.md](../references/task-transform-legacy.md) for the full `transformPrdJsonToRalphV2()` function including:
+- Layer-ordered task generation (domain → infra → app → api → frontend → seedData → tests)
+- Consolidated frontend + i18n tasks
+- Guardrails 1d-1j (inject missing infrastructure, API, frontend, tests, seed data, migration)
 
 ---
 
-### 1. Check for Existing prd.json
-
-**If `.ralph/prd.json` exists:**
-- Read and parse the file
-- Verify `$version` is `"2.0.0"` (if not, STOP - run step-00 migration first)
-- Find the next eligible task (see step 5)
-- Skip to step 5
+## 1. Check for Existing prd.json
 
-**If `.ralph/prd.json` does NOT exist:**
-- Continue to step 2 (create tasks)
+If `.ralph/prd.json` exists:
+1. Read the PRD
+2. **v3 FAST PATH:** If `$version === "3.0.0"` AND `tasks[]` exists:
+   - Inject runtime fields if missing (status, config, feature, created, updated_at, history)
+   - Write back to `.ralph/prd.json`
+   - Skip directly to section 5 (find next task)
+3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5), skip to section 5
+4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
 
-### 2. Analyze Task Description
+If `.ralph/prd.json` does not exist: continue to section 2.
 
-**ULTRA THINK about the task:**
+## 2. Analyze Task Description
 
-- What are the logical subtasks?
-- What order should they be executed?
-- What are the success criteria for each?
-- What files will be modified?
-- What layer does each task belong to?
-- What dependencies exist between tasks?
+Check for BA handoff source (priority):
+1. Per-module PRD files (handled by section 0)
+2. Single prd.json already present
+3. Markdown handoff: `find . -path "*development-handoff*" -name "*.md"`
+4. Direct task from `{task_description}`
 
-**Check for BA handoff source (priority order):**
+Generate **3-30 subtasks** by category (domain → infrastructure → application → api → frontend → i18n → test → validation).
 
-```bash
-# Priority 1: Per-module PRD files (from ss derive-prd / BA handoff)
-# These are already handled by Section 0 if modules-queue.json exists
-PRD_MODULE=$(ls .ralph/prd-*.json 2>/dev/null | head -1)
+## 3. Create prd.json
 
-# Priority 2: Single prd.json already present (from BA or previous run)
-PRD_SINGLE=".ralph/prd.json"
-
-# Priority 3: Markdown handoff document
-HANDOFF=$(find . -path "*development-handoff*" -name "*.md" | head -1)
-BA_OUTPUT=$(find . -path ".claude/output/ba/*" -name "4-*.md" | head -1)
-SOURCE_PATH=${HANDOFF:-$BA_OUTPUT}
-```
-
-**If prd-*.json files exist but no modules-queue.json:**
-- This means step-00 didn't create a queue (single prd file)
-- Copy the single `prd-*.json` to `prd.json` and transform if needed
-
-**If markdown handoff found:**
-- Read the handoff document
-- Derive tasks from its specifications (per-layer breakdown)
-- Set `source.type = "ba-handoff"` and `source.handoff_path`
-- Look for feature.json in the same directory
-
-**If no handoff:**
-- Generate task breakdown from `{task_description}`
-- Set `source = null`
-
-**Generate task breakdown:**
-
-For `{task_description}`, identify **3-30 subtasks** organized by category.
-
-**Task categories (use SmartStack layer order):**
-
-| Category | Description | Examples |
-|----------|-------------|---------|
-| `domain` | Domain entities and value objects | Create entities, enums, interfaces |
-| `application` | CQRS handlers, DTOs, validators | Commands, Queries, DTOs, FluentValidation |
-| `infrastructure` | EF Core, external services | DbContext configs, migrations, services |
-| `api` | Controllers, middleware | REST endpoints, filters, middleware |
-| `frontend` | React pages, components, hooks | Pages, API services, React Query hooks |
-| `i18n` | Translations | Translation JSON files |
-| `test` | Unit and integration tests | xUnit tests, React testing library |
-| `validation` | Build, lint, MCP checks | dotnet build, pnpm build, MCP validate |
-| `other` | Anything else | Documentation, configuration |
-
-**Example for "implement user authentication":**
-```json
-{
-  "tasks": [
-    {
-      "id": 1,
-      "description": "Create User entity in SmartStack.Domain/Entities/Business/",
-      "status": "pending",
-      "category": "domain",
-      "dependencies": [],
-      "acceptance_criteria": "Entity compiles with all required properties per handoff spec"
-    },
-    {
-      "id": 2,
-      "description": "Add User DbSet to ApplicationDbContext and create EF Core configuration",
-      "status": "pending",
-      "category": "infrastructure",
-      "dependencies": [1],
-      "acceptance_criteria": "DbContext compiles, configuration maps all properties"
-    },
-    {
-      "id": 3,
-      "description": "Create EF Core migration for User table",
-      "status": "pending",
-      "category": "infrastructure",
-      "dependencies": [2],
-      "acceptance_criteria": "Migration applies without errors, 3 files present"
-    },
-    {
-      "id": 4,
-      "description": "Implement IPasswordService and IJwtService",
-      "status": "pending",
-      "category": "application",
-      "dependencies": [1],
-      "acceptance_criteria": "Services compile, follow existing patterns"
-    },
-    {
-      "id": 5,
-      "description": "Create CQRS Commands: LoginCommand + RegisterCommand with handlers",
-      "status": "pending",
-      "category": "application",
-      "dependencies": [4],
-      "acceptance_criteria": "Handlers compile, validators defined"
-    },
-    {
-      "id": 6,
-      "description": "Create AuthController with login/register endpoints",
-      "status": "pending",
-      "category": "api",
-      "dependencies": [5],
-      "acceptance_criteria": "Endpoints respond correctly, Swagger displays them"
-    },
-    {
-      "id": 7,
-      "description": "Write unit tests for User entity and validators",
-      "status": "pending",
-      "category": "test",
-      "dependencies": [5],
-      "acceptance_criteria": "All tests pass, >80% coverage on new code"
-    },
-    {
-      "id": 8,
-      "description": "Run dotnet build, dotnet test, MCP validate_conventions",
-      "status": "pending",
-      "category": "validation",
-      "dependencies": [6, 7],
-      "acceptance_criteria": "Build succeeds, all tests pass, MCP validation clean"
-    }
-  ]
-}
-```
-
-**Task count validation:**
-- MINIMUM: 3 tasks (anything less is too coarse)
-- MAXIMUM: 30 tasks (anything more needs re-grouping)
-- If over 30, merge related subtasks into larger units
-
-### 3. Create prd.json (v2)
-
-**Write `.ralph/prd.json`:**
-
-```json
-{
-  "$version": "2.0.0",
-  "feature": "{task_description}",
-  "status": "in_progress",
-  "created": "{ISO_TIMESTAMP}",
-  "updated_at": "{ISO_TIMESTAMP}",
-  "metadata": {metadata},
-  "config": {
-    "max_iterations": {max_iterations},
-    "completion_promise": "{completion_promise}",
-    "current_iteration": 1
-  },
-  "source": {source_object_or_null},
-  "tasks": [{generated_tasks_with_all_fields}],
-  "history": []
-}
-```
-
-**IMPORTANT: Every task MUST have ALL fields:**
-```json
-{
-  "id": 1,
-  "description": "...",
-  "status": "pending",
-  "category": "domain|application|infrastructure|api|frontend|i18n|test|validation|other",
-  "dependencies": [],
-  "acceptance_criteria": "...",
-  "started_at": null,
-  "completed_at": null,
-  "iteration": null,
-  "commit_hash": null,
-  "files_changed": { "created": [], "modified": [] },
-  "validation": null,
-  "error": null
-}
-```
-
-**Initialize `.ralph/progress.txt`:**
+Write `.ralph/prd.json` with all tasks (every task MUST have: id, description, status, category, dependencies, acceptance_criteria, started_at, completed_at, iteration, commit_hash, files_changed, validation, error).
 
+Initialize `.ralph/progress.txt`:
 ```markdown
 # Ralph Loop Progress
-
 ## Task: {task_description}
 ## Started: {timestamp}
-## Schema: v2.0.0
-## Source: {source_type or "direct"}
-
----
-
-## Iteration 1
-
-### Context
-Starting fresh implementation.
-
-### Learnings
-(To be updated after each iteration)
+## Schema: v3.0.0
 ```
 
-### 4. Validate Task Integrity
-
-**After creation, verify:**
-
-```javascript
-// Check all tasks have required fields
-const requiredFields = ['id', 'description', 'status', 'category',
-  'dependencies', 'acceptance_criteria', 'started_at', 'completed_at',
-  'iteration', 'commit_hash', 'files_changed', 'validation', 'error'];
-
-for (const task of prd.tasks) {
-  for (const field of requiredFields) {
-    if (!(field in task)) {
-      ERROR: "Task ${task.id} missing field: ${field}";
-    }
-  }
-}
-
-// Check dependency references are valid
-const taskIds = prd.tasks.map(t => t.id);
-for (const task of prd.tasks) {
-  for (const dep of task.dependencies) {
-    if (!taskIds.includes(dep)) {
-      ERROR: "Task ${task.id} depends on non-existent task ${dep}";
-    }
-  }
-}
-
-// Check no circular dependencies
-// (simple: a task cannot depend on a task with higher or equal id)
-for (const task of prd.tasks) {
-  for (const dep of task.dependencies) {
-    if (dep >= task.id) {
-      ERROR: "Task ${task.id} has forward/circular dependency on task ${dep}";
-    }
-  }
-}
-
-// Check task count
-if (prd.tasks.length < 3 || prd.tasks.length > 30) {
-  WARNING: "Task count ${prd.tasks.length} outside recommended range (3-30)";
-}
-```
+## 4. Validate Task Integrity
 
-### 5. Find Current Task
+- All tasks have required fields
+- Dependency references are valid (exist, no forward/circular)
+- Task count 3-30
 
-**Find the next eligible task:**
+## 5. Find Current Task
 
 ```javascript
 function findNextTask(tasks) {
   for (const task of tasks) {
     if (task.status !== 'pending') continue;
-
-    // Check all dependencies are completed
-    const depsOk = task.dependencies.every(depId => {
-      const dep = tasks.find(t => t.id === depId);
-      return dep && dep.status === 'completed';
-    });
-
-    // Check if any dependency failed (→ block this task)
-    const depsBlocked = task.dependencies.some(depId => {
-      const dep = tasks.find(t => t.id === depId);
+    const depsBlocked = task.dependencies.some(d => {
+      const dep = tasks.find(t => t.id === d);
       return dep && (dep.status === 'failed' || dep.status === 'blocked');
     });
-
-    if (depsBlocked) {
-      task.status = 'blocked';
-      task.error = `Blocked by failed dependency`;
-      continue;
-    }
-
+    if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; continue; }
+    const depsOk = task.dependencies.every(d => tasks.find(t => t.id === d)?.status === 'completed');
     if (depsOk) return task;
   }
-  return null; // No eligible tasks
+  return null;
 }
-
-const currentTask = findNextTask(prd.tasks);
 ```
 
-**If no eligible task found:**
-- Check if all tasks are completed → skip to step-05 (report)
-- Check if remaining tasks are all blocked → report as partial, step-05
-- Otherwise → unexpected state, STOP
+If no eligible task: all completed → step-05, all blocked → step-05, else STOP.
 
-**Store in state:**
-```
-{current_task_id}          = currentTask.id
-{current_task_description} = currentTask.description
-{current_task_category}    = currentTask.category
-{current_task_criteria}    = currentTask.acceptance_criteria
-{tasks_completed}          = tasks.filter(t => t.status === 'completed').length
-{tasks_total}              = tasks.length
-{tasks_blocked}            = tasks.filter(t => t.status === 'blocked').length
-```
-
-### 6. Read Previous Progress
-
-**If iteration > 1:**
-
-Read `.ralph/progress.txt` to understand:
-- What was done in previous iterations
-- Key learnings and context
-- Files that were modified
-- Issues encountered
-
-**Also read `history[]` from prd.json for structured context.**
-
-### 7. Show Task Status
-
-**Display current state:**
+## 6. Show Task Status
 
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║  ITERATION {current_iteration} / {max_iterations}               ║
-║  {modules_queue ? "Module " + (currentIndex+1) + "/" + totalModules + ": " + current_module : ""} ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Progress: {tasks_completed} / {tasks_total} tasks complete     ║
-║  Blocked:  {tasks_blocked}                                      ║
-║                                                                  ║
-║  Current Task:                                                   ║
-║  [{current_task_id}] {current_task_description}                 ║
-║  Category: {current_task_category}                               ║
-║  Criteria: {current_task_criteria}                               ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Previous Learnings:                                             ║
-║  {summary from progress.txt}                                    ║
-╚══════════════════════════════════════════════════════════════════╝
-
--> Executing task...
-```
-
----
-
-## OUTPUT FORMAT:
-
-```
-Task Loaded:
-
-| Field | Value |
-|-------|-------|
-| Iteration | {current_iteration} / {max_iterations} |
-| Task ID | {current_task_id} |
-| Task | {current_task_description} |
-| Category | {current_task_category} |
-| Criteria | {current_task_criteria} |
-| Progress | {tasks_completed} / {tasks_total} |
-| Blocked | {tasks_blocked} |
-
+[{iteration}/{max}] {completed}/{total} done | Task [{id}] {description} ({category})
 -> Executing...
 ```