@atlashub/smartstack-cli 4.25.0 → 4.27.0

package/templates/skills/ba-generate-html/steps/step-02-build-data.md

@@ -89,24 +89,29 @@ modules: master.modules.map(m => ({
 
 **moduleSpecs{} — ONE entry per module (CRITICAL):**
 
-For EACH module, read the module index.json and map:
+> **FLAT-FILE ARCHITECTURE:** Module data comes from separate JSON files collected in step-01,
+> NOT from index.json fields. Use `collected_data.modules[moduleCode].entities`, `.usecases`, etc.
+
+For EACH module, use the flat file data from `collected_data.modules[moduleCode]`:
 
 ```javascript
+const mod = collected_data.modules[moduleCode];
+
 moduleSpecs[moduleCode] = {
-  useCases: (moduleFeature.specification?.useCases || []).map(uc => ({
+  useCases: (mod.usecases?.useCases || []).map(uc => ({
     name: uc.name,
     actor: uc.primaryActor,
     steps: (uc.mainScenario || []).join("\n"),
     alternative: (uc.alternativeScenarios || []).map(a => a.name + ": " + (a.steps || []).join(", ")).join("\n")
   })),
-  businessRules: (moduleFeature.analysis?.businessRules || []).map(br => ({
+  businessRules: (mod.rules?.rules || []).map(br => ({
     name: br.name,
     category: br.category,
     statement: br.statement,
     example: (br.examples || []).map(e => e.input + " → " + e.expected).join("; ")
   })),
   // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated
-  entities: (moduleFeature.analysis?.entities || []).map(ent => ({
+  entities: (mod.entities?.entities || []).map(ent => ({
     name: ent.name,
     description: ent.description || "",
     attributes: (ent.attributes || []).length > 0
@@ -115,8 +120,8 @@ moduleSpecs[moduleCode] = {
     relationships: (ent.relationships || []).map(r =>
       typeof r === 'string' ? r : r.target + " (" + r.type + ") - " + (r.description || ""))
   })),
-  permissions: buildPermissionKeys(moduleFeature),
-  apiEndpoints: moduleFeature.specification?.apiEndpoints || []
+  permissions: buildPermissionKeys(mod.permissions),
+  apiEndpoints: mod.usecases?.apiEndpoints || []
 }
 ```
 
@@ -158,24 +163,34 @@ handoff: {
 > **FIELD RENAME WARNING:** Module JSON uses `mockupFormat`/`mockup`. HTML reads `format`/`content`. You MUST rename.
 
 **wireframes{} — per moduleCode:**
+
+> **FLAT-FILE:** Wireframes come from `screens.json` in each module directory (collected in step-01),
+> NOT from `moduleFeature.specification.uiWireframes`.
+
 ```javascript
+const mod = collected_data.modules[moduleCode];
+const screens = mod.screens?.screens || [];
+
+// Extract wireframes from screens that have mockup/wireframe data
 wireframes: {
-  [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
-    screen: wf.screen || wf.name || wf.title || wf.id || "",
-    section: wf.section || "",
-    format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
-    content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
-    svgContent: null,
-    description: wf.description || "",
-    elements: wf.elements || [],
-    actions: wf.actions || [],
-    componentMapping: Array.isArray(wf.componentMapping) ? wf.componentMapping
-      : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
-        ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
-        : [],
-    layout: typeof wf.layout === 'object' ? wf.layout : null,
-    permissionsRequired: wf.permissionsRequired || []
-  }))
+  [moduleCode]: screens
+    .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+    .map(wf => ({
+      screen: wf.screen || wf.name || wf.title || wf.id || "",
+      section: wf.section || "",
+      format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
+      content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
+      svgContent: null,
+      description: wf.description || "",
+      elements: wf.elements || [],
+      actions: wf.actions || [],
+      componentMapping: Array.isArray(wf.componentMapping) ? wf.componentMapping
+        : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
+          ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
+          : [],
+      layout: typeof wf.layout === 'object' ? wf.layout : null,
+      permissionsRequired: wf.permissionsRequired || []
+    }))
 }
 ```
 

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -357,14 +357,12 @@ IF workflow_mode = "project":
   })
 
   Output path: docs/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/business-analyse/v{version}/*.json
-    - entities.json
-    - rules.json
-    - usecases.json
-    - permissions.json
-    - screens.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
+    - cadrage.json
     - validation.json
-    - handoff.json
+    - consolidation.json
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at project level is a BLOCKING ERROR.
 
   Store:
     project_id: string  // PROJ-NNN
@@ -395,19 +393,29 @@ ELSE:
   })
 
   Output path: docs/{app}/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/{app}/business-analyse/v{version}/*.json
-    - entities.json
-    - rules.json
-    - usecases.json
-    - permissions.json
-    - screens.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
+    - cadrage.json
     - validation.json
-    - handoff.json
+    - consolidation.json
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at application level is a BLOCKING ERROR.
 ```
 
 > **Note:** In project mode, per-application index.json files are created later in step-01-cadrage.
 > In single-app mode, step-02 (structure) determines if it's single or multi-module.
 
+### POST-CREATE VERIFICATION (MANDATORY)
+
+After creating thematic files, verify no forbidden files were created:
+
+```
+List all *.json files in {docs_dir}/
+Expected (project/application): [index.json, cadrage.json, validation.json, consolidation.json]
+If any file NOT in expected list is found → DELETE it immediately + log WARNING
+```
+
+This guard catches any accidental creation of module-only files at the wrong scope.
+
 ## Step 10: Update Config
 
 Update `.business-analyse/config.json` with new feature information.

package/templates/skills/business-analyse/steps/step-04-consolidate.md

@@ -423,6 +423,9 @@ ba-writer.enrichSection({
 // Update status
 ba-writer.updateStatus({feature_id}, "consolidated");
 
+// Clean up any forbidden files that may have been created at app level
+ba-writer.cleanupAppLevelFiles({ featureId: {feature_id} });
+
 // Save workflow state for resume support
 ba-writer.enrichSection({
   featureId: {feature_id},

package/templates/skills/derive-prd/steps/step-01-transform.md

@@ -201,8 +201,12 @@ FOR i = 0 to modules.length-1:
      - totalFiles: count from filesToCreate
      - totalTasks: estimated from complexity
      - handedOffAt: ISO timestamp
-  3. Write via ba-writer.enrichModuleHandoff({ moduleFeatureId, handoffData })
-  4. Display: "handoff {i+1}/{N}: {moduleCode} ({fileCount} files)"
+  3. Propagate featureDescription from app-level index.json:
+     ```javascript
+     handoffPayload.featureDescription = appIndex.metadata.featureDescription || null;
+     ```
+  4. Write via ba-writer.enrichModuleHandoff({ moduleFeatureId, handoffData })
+  5. Display: "handoff {i+1}/{N}: {moduleCode} ({fileCount} files)"
 ```
 
 ### 10. POST-CHECK Per Module (BLOCKING)

package/templates/skills/derive-prd/steps/step-02-export.md

@@ -29,6 +29,18 @@ For each module, generate PRD files via CLI, verify integrity, create progress t
 
 For EACH module:
 
+**Option A — Flat-file BA (recommended):**
+
+```bash
+# Single module:
+ss derive-prd --ba-dir {moduleBaDir} --output .ralph/prd-{moduleCode}.json
+
+# All modules from app-level index.json:
+ss derive-prd --ba-app {appIndexPath}
+```
+
+**Option B — Legacy feature.json:**
+
 ```bash
 ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
 ```

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -130,7 +130,7 @@ if (guardrailsNeeded.length > 0) {
     }
   }
 
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 }
 ```
 
@@ -142,7 +142,7 @@ const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
 
 if (guardrailsNeeded.length > 0) {
   prd.tasks.push(...guardrailsNeeded);
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 
   const newPending = prd.tasks.filter(t => t.status === 'pending').length;
   console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${newPending} pending tasks`);
@@ -186,7 +186,7 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
         t.error = 'Artifacts missing — re-execute';
         t.completed_at = null;
       });
-    writeJSON('.ralph/prd.json', prd);
+    writeJSON(currentPrdPath, prd);
   }
 }
 ```

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -16,6 +16,16 @@
 
 ## Loop Entry
 
+```javascript
+// PRD PATH RESOLUTION (MANDATORY - runs at loop entry)
+const queuePath = '.ralph/modules-queue.json';
+let currentPrdPath = '.ralph/prd.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+}
+```
+
 Display compact progress:
 ```
 [{iteration}/{max}] {completed}/{total} done | Finding eligible tasks...
@@ -26,7 +36,7 @@ Display compact progress:
 ## A0. Section-Split Mode (checked BEFORE standard batching)
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
+const prd = readJSON(currentPrdPath);
 
 if (prd._sectionSplit?.enabled) {
   // SECTION-SPLIT: Delegate per-phase instead of per-category batch
@@ -96,7 +106,7 @@ Apex sees a focused PRD for this phase only. After apex returns, continue:
   }
 
   prd._sectionSplit.currentPhase = nextPhase.phase;
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 
   // → Skip to section C (commit PRD state), then D (loop back)
   // → SKIP sections A and B. Jump directly to section C (COMMIT_PRD) below.
@@ -130,7 +140,7 @@ if (isDeadEnd) {
   // Then fall through to `eligible.length === 0` below which returns to step-04.
   console.log(`DEAD-END: ${prd.tasks.filter(t=>t.status==='completed').length} done, ${failedBeforeRetry.length} failed (retries exhausted), ${prd.tasks.filter(t=>t.status==='blocked').length} blocked`);
   prd.status = 'failed';
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
   // DO NOT reset retries below — skip to eligible search (will find 0 tasks → CHECK_COMPLETION)
 }
 
@@ -172,7 +182,7 @@ if (!isDeadEnd) {
     if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
   }
 
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 } // end if (!isDeadEnd)
 
 // Find ALL eligible tasks (dependencies met)
@@ -213,12 +223,12 @@ for (const task of batch) {
   task.status = 'in_progress';
   task.started_at = new Date().toISOString();
 }
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ### B2. Invoke /apex
 
-**INVOKE `/apex -d .ralph/prd.json`**
+**INVOKE `/apex -d {currentPrdPath}`**
 
 Apex handles everything for the current module:
 - Reads PRD, extracts context (app_name, module_code, entities, sections)
@@ -230,11 +240,37 @@ Apex handles everything for the current module:
 
 > **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
 
-### B3. Verify Post-Apex Results
+### B2b. MANDATORY CHECKPOINT: Verify prd.json tasks updated
 
 ```javascript
 // Re-read PRD after apex execution
-const updatedPrd = readJSON('.ralph/prd.json');
+const updatedPrd = readJSON(currentPrdPath);
+const batchIds = batch.map(t => t.id);
+
+// BLOCKING CHECK: Verify apex actually updated task statuses
+const stillPending = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'pending').length;
+if (stillPending === batchIds.length) {
+  console.error(`BLOCKING ERROR: apex did not update any task statuses — all ${stillPending} tasks still pending`);
+  console.error('Possible causes: apex crashed, PRD path mismatch, or apex did not receive the correct PRD');
+  // Mark tasks as failed so retry logic can handle them
+  for (const task of updatedPrd.tasks) {
+    if (batchIds.includes(task.id) && task.status === 'pending') {
+      task.status = 'failed';
+      task.error = 'apex did not update task status';
+    }
+  }
+  writeJSON(currentPrdPath, updatedPrd);
+}
+```
+
+> **NEVER write progress.txt manually. ALWAYS update prd.json tasks FIRST,
+> then derive progress.txt from prd.json state.**
+
+### B3. Verify Post-Apex Results
+
+```javascript
+// Re-read PRD after apex execution (use currentPrdPath)
+const updatedPrd = readJSON(currentPrdPath);
 const batchIds = batch.map(t => t.id);
 
 const completed = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed').length;
@@ -260,7 +296,7 @@ console.log(`Apex completed: ${completed}/${batchIds.length} tasks`);
 ### C1. Update Progress File (MANDATORY)
 
 ```javascript
-const prdCheck = readJSON('.ralph/prd.json');
+const prdCheck = readJSON(currentPrdPath);
 const totalCompleted = prdCheck.tasks.filter(t => t.status === 'completed').length;
 const total = prdCheck.tasks.length;
 
@@ -270,18 +306,49 @@ appendFile('.ralph/progress.txt',
 );
 ```
 
-### C2. Increment Iteration
+### C2. Skipped Task Audit
+
+After apex returns, check for newly skipped tasks:
+
+```javascript
+const newlySkipped = prdCheck.tasks.filter(t =>
+  batchIds.includes(t.id) && t.status === 'skipped'
+);
+if (newlySkipped.length > 0) {
+  console.warn(`⚠ ${newlySkipped.length} tasks were SKIPPED by apex:`);
+  newlySkipped.forEach(t => console.warn(`  - ${t.id}: ${t.description}`));
+
+  // If ALL tasks in a category were skipped → BLOCKING, reset for retry
+  const skippedCategories = [...new Set(newlySkipped.map(t => t.category))];
+  for (const cat of skippedCategories) {
+    const allInCat = prdCheck.tasks.filter(t => t.category === cat);
+    const allSkipped = allInCat.every(t => t.status === 'skipped');
+    if (allSkipped) {
+      console.error(`BLOCKING: ALL tasks in category "${cat}" were skipped — investigate root cause`);
+      // Reset to pending for retry
+      allInCat.forEach(t => {
+        t.status = 'pending';
+        t._retryCount = (t._retryCount || 0) + 1;
+        t.error = `All tasks in category "${cat}" skipped — auto-retry`;
+      });
+    }
+  }
+  writeJSON(currentPrdPath, prdCheck);
+}
+```
+
+### C3. Increment Iteration
 
 ```javascript
 prdCheck.config.current_iteration++;
 prdCheck.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prdCheck);
+writeJSON(currentPrdPath, prdCheck);
 ```
 
-### C3. Git Commit (PRD state only — apex already committed code)
+### C4. Git Commit (PRD state only — apex already committed code)
 
 ```bash
-git add .ralph/prd.json .ralph/progress.txt
+git add {currentPrdPath} .ralph/progress.txt
 [ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
 
 git commit -m "$(cat <<'EOF'
@@ -295,7 +362,7 @@ EOF
 )"
 ```
 
-### C4. PRD Sync Verification (HARD CHECK)
+### C5. PRD Sync Verification (HARD CHECK)
 
 > **Note:** `prdCheck` (read in C1) is the authoritative post-apex snapshot.
 > `completed` (from B3) was computed on a DIFFERENT read — do NOT mix the two.

package/templates/skills/ralph-loop/references/init-resume-recovery.md

@@ -16,7 +16,7 @@ if (!fileExists('.ralph/prd.json')) {
   STOP;
 }
 
-const prd = readJSON('.ralph/prd.json');
+const prd = readJSON(currentPrdPath);
 
 // Detect format
 let resumeValid = false;

package/templates/skills/ralph-loop/references/module-transition.md

@@ -54,15 +54,17 @@ if (missing.length === 0) {
       timestamp: new Date().toISOString()
     });
 
-    // Mark current PRD as complete
+    // Mark current PRD as complete (write to module-specific file, NOT .ralph/prd.json)
     prd.status = 'completed';
-    writeJSON('.ralph/prd.json', prd);
+    writeJSON(currentModule.prdFile, prd);
 
-    // Load next module's PRD
+    // Prepare next module's PRD (work directly with prd-{moduleCode}.json)
     const nextPrd = readJSON(queue.modules[nextIndex].prdFile);
     nextPrd.config.current_iteration = 1;
     nextPrd.config.max_iterations = prd.config.max_iterations;
-    writeJSON('.ralph/prd.json', nextPrd);
+    writeJSON(queue.modules[nextIndex].prdFile, nextPrd);
+    // NOTE: Ralph works directly with prd-{moduleCode}.json via currentPrdPath resolution.
+    // No need to copy to .ralph/prd.json — this avoids overwriting between modules.
 
     console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
 
@@ -76,6 +78,29 @@ if (missing.length === 0) {
 }
 ```
 
+### MANDATORY POST-CHECK: modules-queue.json integrity
+
+```javascript
+// VERIFY: modules-queue.json updated correctly after advancement
+const queueCheck = readJSON(queuePath);
+const actualCompleted = queueCheck.modules.filter(m => m.status === 'completed').length;
+if (queueCheck.completedModules !== actualCompleted) {
+  console.error(`QUEUE SYNC ERROR: completedModules=${queueCheck.completedModules} but actual=${actualCompleted}`);
+  queueCheck.completedModules = actualCompleted;
+  writeJSON(queuePath, queueCheck);
+  console.log('FIXED: completedModules synced to actual count');
+}
+
+if (nextIndex < queueCheck.totalModules) {
+  if (queueCheck.currentIndex !== nextIndex) {
+    console.error(`QUEUE SYNC ERROR: currentIndex=${queueCheck.currentIndex} but expected=${nextIndex}`);
+    queueCheck.currentIndex = nextIndex;
+    writeJSON(queuePath, queueCheck);
+    console.log('FIXED: currentIndex synced');
+  }
+}
+```
+
 ---
 
 ## Check: All Modules Complete
@@ -121,7 +146,7 @@ if (fileExists(moduleChangePath)) {
 ├─ step-04: Check completion
 │  └─ If all categories complete:
 │     ├─ Write module-changed.json
-│     ├─ Write next PRD to .ralph/prd.json
+│     ├─ Write next PRD to prd-{moduleCode}.json (via currentPrdPath)
 │     └─ Return to step-01 ✓
 │
 └─ [Phase B: Module 2]

package/templates/skills/ralph-loop/references/multi-module-queue.md

@@ -123,7 +123,7 @@ if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
 
-  const currentPrd = readJSON('.ralph/prd.json');
+  const currentPrd = readJSON(currentPrdPath);
   if (currentPrd.metadata?.moduleCode !== currentModule.code) {
     // Module has changed — load new PRD
     const modulePrd = readJSON(currentModule.prdFile);
@@ -143,16 +143,16 @@ if (fileExists(queuePath)) {
       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);
+      writeJSON(currentModule.prdFile, modulePrd);
     }
     // LEGACY: FORMAT A
     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));
+      writeJSON(currentModule.prdFile, transformPrdJsonToRalphV2(modulePrd, currentModule.code));
     }
     // v2 legacy
     else {
-      writeJSON('.ralph/prd.json', modulePrd);
+      writeJSON(currentModule.prdFile, modulePrd);
     }
   }
 

package/templates/skills/ralph-loop/references/section-splitting.md

@@ -50,7 +50,7 @@ EF Core creates a single ModelSnapshot per DbContext. If Phase 1 creates a migra
 ## 1. Detection
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
+const prd = readJSON(currentPrdPath);
 const domainTasks = prd.tasks.filter(t => t.category === 'domain');
 const sections = prd.architecture?.sections ?? [];
 
@@ -313,7 +313,7 @@ prd._sectionSplit = {
   entityToSection
 };
 
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ---
@@ -344,7 +344,7 @@ if (!depsOk) {
 // After apex returns:
 nextPhase.status = 'completed';
 prd._sectionSplit.currentPhase = nextPhase.phase;
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ---
@@ -369,7 +369,7 @@ for (const phaseTask of phasePrd.tasks) {
   }
 }
 
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ---
@@ -413,13 +413,13 @@ After all phases complete or on final report:
 if (prd._sectionSplit?.enabled) {
   // Delete temporary phase PRD files
   for (const phase of prd._sectionSplit.phases) {
-    if (fileExists(phase.prdFile) && phase.prdFile !== '.ralph/prd.json') {
+    if (fileExists(phase.prdFile) && phase.prdFile !== currentPrdPath) {
       deleteFile(phase.prdFile);
     }
   }
   // Remove split state from master PRD
   delete prd._sectionSplit;
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 }
 ```
 

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

@@ -46,17 +46,27 @@ See [references/task-transform-legacy.md](../references/task-transform-legacy.md
 
 ## 1. Check for Existing prd.json
 
-If `.ralph/prd.json` exists:
+```javascript
+// PRD PATH RESOLUTION (MANDATORY - runs before any PRD access)
+const queuePath = '.ralph/modules-queue.json';
+let currentPrdPath = '.ralph/prd.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+}
+```
+
+If `{currentPrdPath}` 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`
+   - Write back to `{currentPrdPath}`
    - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
    - Skip directly to section 5 (find next task)
 3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5)
 4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
 
-If `.ralph/prd.json` does not exist: continue to section 1b.
+If `{currentPrdPath}` does not exist: continue to section 1b.
 
 ### 1b. BA Handoff Quality Gate (BLOCKING when BA artifacts present)
 
@@ -110,7 +120,7 @@ Generate **3-30 subtasks** by category (domain → infrastructure → applicatio
 
 ## 3. Create prd.json
 
-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).
+Write `{currentPrdPath}` 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

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -30,13 +30,21 @@ Delegate the current module's tasks to `/apex -d` for code generation. Ralph han
 ### 1. Verify Dependencies
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
+// PRD PATH RESOLUTION
+const queuePath = '.ralph/modules-queue.json';
+let currentPrdPath = '.ralph/prd.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+}
+
+const prd = readJSON(currentPrdPath);
 const task = prd.tasks.find(t => t.id === {current_task_id});
 for (const depId of task.dependencies) {
   const dep = prd.tasks.find(t => t.id === depId);
   if (!dep || dep.status !== 'completed') {
     task.status = 'blocked'; task.error = `Dependency ${depId} not completed`;
-    writeJSON('.ralph/prd.json', prd);
+    writeJSON(currentPrdPath, prd);
     STOP — return to step-01
   }
 }
@@ -47,7 +55,7 @@ for (const depId of task.dependencies) {
 ```javascript
 task.status = 'in_progress';
 task.started_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ### 3. Delegate to /apex
@@ -106,7 +114,7 @@ Read `references/section-splitting.md` sections 7-9 for execution, merging, and
 
   nextPhase.status = 'completed';
   prd._sectionSplit.currentPhase = nextPhase.phase;
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 
   // Continue to step-03 (commit), then step-04 loops back for next phase
 }
@@ -116,7 +124,7 @@ Read `references/section-splitting.md` sections 7-9 for execution, merging, and
 
 #### 3c. Standard Mode (no split, no parallel)
 
-**INVOKE `/apex -d .ralph/prd.json`**
+**INVOKE `/apex -d {currentPrdPath}`**
 
 This delegates ALL remaining tasks for the current module to apex:
 
@@ -134,7 +142,7 @@ This delegates ALL remaining tasks for the current module to apex:
 
 ```javascript
 // Re-read PRD after apex execution
-const updatedPrd = readJSON('.ralph/prd.json');
+const updatedPrd = readJSON(currentPrdPath);
 const moduleTasks = updatedPrd.tasks.filter(t => t.module === {current_module});
 
 const completed = moduleTasks.filter(t => t.status === 'completed').length;