@atlashub/smartstack-cli 4.25.0 → 4.27.0

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