@atlashub/smartstack-cli 4.24.0 → 4.26.0

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;

package/templates/skills/ralph-loop/steps/step-03-commit.md

@@ -18,8 +18,19 @@ Commit PRD state changes after apex delegation. Apex already committed code —
 
 ### 1. Finalize Task in prd.json
 
+> **BLOCKING:** If prd.tasks has any task with status='pending' that should be 'completed'
+> based on actual code commits, FIX prd.json BEFORE committing.
+
 ```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 now = new Date().toISOString();
 
 // Apex updates individual task statuses. Ralph updates overall PRD state.
@@ -29,7 +40,7 @@ prd.status = allDone ? 'completed' : prd.tasks.some(t => t.status === 'failed' |
 prd.config.current_iteration++;
 prd.updated_at = now;
 
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ### 2. Update progress.txt
@@ -44,7 +55,7 @@ Module: {current_module}
 ### 3. Stage and Commit (PRD state only)
 
 ```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'
@@ -69,7 +80,7 @@ prd.history.push({
   commit_hash: COMMIT_HASH,
   notes: "Delegated to /apex"
 });
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ### 5. Verify

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

@@ -15,7 +15,15 @@ Check if all tasks are complete and decide: output completion promise, advance m
 ## 1. Read Current State
 
 ```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 tasksCompleted = prd.tasks.filter(t => t.status === 'completed').length;
 const tasksSkipped = prd.tasks.filter(t => t.status === 'skipped').length;
 const tasksFailed = prd.tasks.filter(t => t.status === 'failed').length;
@@ -41,7 +49,7 @@ if [ $BUILD_RC -ne 0 ]; then
   prd.tasks.push({ id: maxId+1, description: "Fix build regression",
     status: "pending", category: "validation", dependencies: [],
     acceptance_criteria: "dotnet build passes" });
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 fi
 ```
 
@@ -57,7 +65,7 @@ const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
 
 if (guardrailsNeeded.length > 0) {
   prd.tasks.push(...guardrailsNeeded);
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
   console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${prd.tasks.filter(t => t.status === 'pending').length} pending tasks`);
 }
 // Artifact verification is handled inside checkCategoryCompleteness() — see reference file.
@@ -117,6 +125,8 @@ if (fileExists(queuePath)) {
   } else {
     // All categories complete — advance to next module
     // (detailed logic in references/module-transition.md)
+    // MANDATORY: If this was the LAST module, ALWAYS proceed to step-05-report.md.
+    // NEVER stop without generating the final report.
   }
 }
 ```
@@ -128,7 +138,11 @@ ALL TASKS COMPLETE | Iterations: {n} | Tasks: {completed}/{total}
 <promise>{completion_promise}</promise>
 ```
 
-Set `prd.status = 'completed'` → step-05.
+Set `prd.status = 'completed'`.
+
+**MANDATORY: After displaying completion, ALWAYS load step-05-report.md and generate the report.**
+**NEVER stop after displaying "ALL TASKS COMPLETE" without generating the report.**
+→ step-05.
 
 ## 4. Dead-End Check
 
@@ -149,7 +163,7 @@ if (!hasPending && !allDone && retriableCount > 0) {
   // TRUE dead-end: all retries exhausted
   console.log(`DEAD-END: ${tasksCompletedNow} done, ${tasksFailed} failed (retries exhausted), ${tasksBlocked} blocked`);
   prd.status = 'failed';
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
   // → step-05
 }
 ```

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -15,7 +15,17 @@ Generate a comprehensive feature report using structured data from prd.json.
 ## 1. Load Data
 
 ```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);
+  // For report, use last module's PRD (or current if still in progress)
+  const idx = Math.min(queue.currentIndex, queue.modules.length - 1);
+  currentPrdPath = queue.modules[idx].prdFile;
+}
+
+const prd = readJSON(currentPrdPath);
 const stats = {
   feature: prd.feature, status: prd.status,
   iterations_used: prd.config.current_iteration - 1,
@@ -53,6 +63,28 @@ if (fileExists(queuePath)) {
 }
 ```
 
+### 1d. Artifact Verification (Post-Execution Validation)
+
+```javascript
+// Verify key artifacts exist on disk
+const allFiles = prd.implementation?.filesToCreate || {};
+const missingFiles = [];
+for (const cat of Object.keys(allFiles)) {
+  for (const file of allFiles[cat] || []) {
+    if (!fileExists(file.path)) missingFiles.push(file.path);
+  }
+}
+if (missingFiles.length > 0) {
+  console.warn(`WARNING: ${missingFiles.length} files declared in PRD but not found on disk`);
+  for (const f of missingFiles.slice(0, 10)) {
+    console.warn(`  MISSING: ${f}`);
+  }
+  if (missingFiles.length > 10) {
+    console.warn(`  ... and ${missingFiles.length - 10} more`);
+  }
+}
+```
+
 ### 1c. Test Metrics (from PRD)
 
 > **Note:** Apex already ran tests and recorded results. Source metrics from PRD task data.
@@ -136,7 +168,7 @@ Write to `.ralph/reports/{feature-slug}.md`:
 // can resume with `-r` — deleting them here would make recovery impossible.
 if (prd._sectionSplit?.enabled && prd.status === 'completed') {
   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);
     }
   }
@@ -146,7 +178,7 @@ if (prd._sectionSplit?.enabled && prd.status === 'completed') {
 }
 
 prd.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ## 4. Display Summary