@atlashub/smartstack-cli 3.39.0 → 3.40.0

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

@@ -1,127 +1,127 @@
-# Resume and Recovery Logic
-
-> **Reference for:** step-00-init.md sections 4 (Resume Mode) and 4a (Auto-Recovery)
-> **Purpose:** Handle resumption of interrupted loops and auto-recovery from BA artifacts
-
----
-
-## Resume Mode
-
-If `{resume_mode} = true` (user passed `-r` flag):
-
-```javascript
-// Check PRD exists
-if (!fileExists('.ralph/prd.json')) {
-  console.error('ERROR: -r flag set but .ralph/prd.json not found');
-  STOP;
-}
-
-const prd = readJSON('.ralph/prd.json');
-
-// Detect format
-let resumeValid = false;
-if (prd.$version === '3.0.0') {
-  // v3 unified — native format
-  resumeValid = true;
-  console.log('Resume: v3.0.0 unified PRD');
-} else if (prd.$version === '2.0.0') {
-  // v2 legacy — OK to resume
-  resumeValid = true;
-  console.log('Resume: v2.0.0 legacy PRD');
-} else if (prd.project && prd.requirements && !prd.$version) {
-  // FORMAT A deprecated — warn but transform
-  console.warn('⚠ DEPRECATED: FORMAT A prd.json detected during resume');
-  console.warn('Re-run `ss derive-prd` to generate v3 format');
-  // NOTE: Transformation happens in step-01, not here
-  resumeValid = true;
-} else {
-  console.error('ERROR: .ralph/prd.json format not recognized');
-  STOP;
-}
-
-if (resumeValid) {
-  // Check branch consistency
-  const branch = prd.metadata?.branch || 'unknown';
-  const currentBranch = getCurrentBranch();
-  if (branch !== currentBranch) {
-    console.warn(`⚠ Branch mismatch: PRD from ${branch}, currently on ${currentBranch}`);
-    console.warn('Continuing anyway — verify this is intentional');
-  }
-
-  // Restore state
-  {current_iteration} = prd.config?.current_iteration || 1;
-  {completion_promise} = prd.config?.completion_promise || null;
-  {max_iterations} = prd.config?.max_iterations || 50;
-
-  // Restore multi-module state if present
-  if (fileExists('.ralph/modules-queue.json')) {
-    {modules_queue} = readJSON('.ralph/modules-queue.json');
-    {current_module} = {modules_queue}.modules[{modules_queue}.currentIndex]?.code;
-    console.log(`Multi-module resume: ${{current_module}} (${{modules_queue}.currentIndex + 1}/${{modules_queue}.totalModules})`);
-  }
-
-  console.log(`Resuming from iteration ${{current_iteration}}`);
-  // Continue to step-01
-}
-```
-
----
-
-## Auto-Recovery: BA Artifacts Without PRD
-
-If no PRD files exist (neither `.ralph/prd-*.json` nor `.ralph/prd.json`):
-
-```javascript
-const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
-
-if (!masterFeature) {
-  // No BA artifacts found — start fresh
-  console.log('No existing PRD or BA artifacts — starting new loop');
-  return;
-}
-
-const master = readJSON(masterFeature);
-const handoffStatus = master.status || master.handoff?.status || null;
-
-if (handoffStatus === 'handed-off') {
-  // BA handoff completed — auto-derive PRDs
-  console.log('BA artifacts detected without PRD — auto-recovering...');
-
-  // Call ss derive-prd to generate PRD files
-  const result = exec(`ss derive-prd --application ${masterFeature}`);
-
-  if (result.exitCode !== 0) {
-    console.error('ss derive-prd failed — cannot auto-recover');
-    STOP;
-  }
-
-  const newPrds = glob('.ralph/prd-*.json');
-  if (newPrds.length === 0) {
-    console.error('ss derive-prd did not create any PRD files');
-    STOP;
-  }
-
-  console.log(`Auto-recovered ${newPrds.length} PRD file(s): ${newPrds.map(f => f.split('/').pop()).join(', ')}`);
-  // Continue to detect multi-module (section 4b)
-} else {
-  // BA handoff NOT complete
-  console.warn(`⚠ BA handoff status: "${handoffStatus}" (expected "handed-off")`);
-  console.warn('Cannot auto-recover PRD files without complete handoff');
-  console.warn('Run /business-analyse to complete the handoff, then retry /ralph-loop');
-  STOP;
-}
-```
-
----
-
-## State After Recovery
-
-After resume or auto-recovery:
-
-```javascript
-// If PRD now exists (either resumed or recovered):
-// - Continue to section 4b (Detect Multi-Module)
-// - Initialize modules-queue.json if 2+ PRD files found
-// - Set {modules_queue} and {current_module} appropriately
-// - Proceed to step-01 to load tasks
-```
+# Resume and Recovery Logic
+
+> **Reference for:** step-00-init.md sections 4 (Resume Mode) and 4a (Auto-Recovery)
+> **Purpose:** Handle resumption of interrupted loops and auto-recovery from BA artifacts
+
+---
+
+## Resume Mode
+
+If `{resume_mode} = true` (user passed `-r` flag):
+
+```javascript
+// Check PRD exists
+if (!fileExists('.ralph/prd.json')) {
+  console.error('ERROR: -r flag set but .ralph/prd.json not found');
+  STOP;
+}
+
+const prd = readJSON('.ralph/prd.json');
+
+// Detect format
+let resumeValid = false;
+if (prd.$version === '3.0.0') {
+  // v3 unified — native format
+  resumeValid = true;
+  console.log('Resume: v3.0.0 unified PRD');
+} else if (prd.$version === '2.0.0') {
+  // v2 legacy — OK to resume
+  resumeValid = true;
+  console.log('Resume: v2.0.0 legacy PRD');
+} else if (prd.project && prd.requirements && !prd.$version) {
+  // FORMAT A deprecated — warn but transform
+  console.warn('⚠ DEPRECATED: FORMAT A prd.json detected during resume');
+  console.warn('Re-run `ss derive-prd` to generate v3 format');
+  // NOTE: Transformation happens in step-01, not here
+  resumeValid = true;
+} else {
+  console.error('ERROR: .ralph/prd.json format not recognized');
+  STOP;
+}
+
+if (resumeValid) {
+  // Check branch consistency
+  const branch = prd.metadata?.branch || 'unknown';
+  const currentBranch = getCurrentBranch();
+  if (branch !== currentBranch) {
+    console.warn(`⚠ Branch mismatch: PRD from ${branch}, currently on ${currentBranch}`);
+    console.warn('Continuing anyway — verify this is intentional');
+  }
+
+  // Restore state
+  {current_iteration} = prd.config?.current_iteration || 1;
+  {completion_promise} = prd.config?.completion_promise || null;
+  {max_iterations} = prd.config?.max_iterations || 50;
+
+  // Restore multi-module state if present
+  if (fileExists('.ralph/modules-queue.json')) {
+    {modules_queue} = readJSON('.ralph/modules-queue.json');
+    {current_module} = {modules_queue}.modules[{modules_queue}.currentIndex]?.code;
+    console.log(`Multi-module resume: ${{current_module}} (${{modules_queue}.currentIndex + 1}/${{modules_queue}.totalModules})`);
+  }
+
+  console.log(`Resuming from iteration ${{current_iteration}}`);
+  // Continue to step-01
+}
+```
+
+---
+
+## Auto-Recovery: BA Artifacts Without PRD
+
+If no PRD files exist (neither `.ralph/prd-*.json` nor `.ralph/prd.json`):
+
+```javascript
+const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
+
+if (!masterFeature) {
+  // No BA artifacts found — start fresh
+  console.log('No existing PRD or BA artifacts — starting new loop');
+  return;
+}
+
+const master = readJSON(masterFeature);
+const handoffStatus = master.status || master.handoff?.status || null;
+
+if (handoffStatus === 'handed-off') {
+  // BA handoff completed — auto-derive PRDs
+  console.log('BA artifacts detected without PRD — auto-recovering...');
+
+  // Call ss derive-prd to generate PRD files
+  const result = exec(`ss derive-prd --application ${masterFeature}`);
+
+  if (result.exitCode !== 0) {
+    console.error('ss derive-prd failed — cannot auto-recover');
+    STOP;
+  }
+
+  const newPrds = glob('.ralph/prd-*.json');
+  if (newPrds.length === 0) {
+    console.error('ss derive-prd did not create any PRD files');
+    STOP;
+  }
+
+  console.log(`Auto-recovered ${newPrds.length} PRD file(s): ${newPrds.map(f => f.split('/').pop()).join(', ')}`);
+  // Continue to detect multi-module (section 4b)
+} else {
+  // BA handoff NOT complete
+  console.warn(`⚠ BA handoff status: "${handoffStatus}" (expected "handed-off")`);
+  console.warn('Cannot auto-recover PRD files without complete handoff');
+  console.warn('Run /business-analyse to complete the handoff, then retry /ralph-loop');
+  STOP;
+}
+```
+
+---
+
+## State After Recovery
+
+After resume or auto-recovery:
+
+```javascript
+// If PRD now exists (either resumed or recovered):
+// - Continue to section 4b (Detect Multi-Module)
+// - Initialize modules-queue.json if 2+ PRD files found
+// - Set {modules_queue} and {current_module} appropriately
+// - Proceed to step-01 to load tasks
+```

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

@@ -1,151 +1,151 @@
-# Module Transition Logic
-
-> **Reference for:** step-04-check.md section 3b
-> **Trigger:** Multi-module mode + current module complete
-> **Purpose:** Advance to next module in queue OR finish if all done
-
----
-
-## When Module Transition Occurs
-
-```javascript
-const queuePath = '.ralph/modules-queue.json';
-if (fileExists(queuePath)) {
-  const queue = readJSON(queuePath);
-  const currentModule = queue.modules[queue.currentIndex];
-
-  // MODULE COMPLETENESS CHECK
-  const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
-  const expected = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
-  const missing = expected.filter(c => !completedCats.has(c));
-
-  if (missing.length > 0) {
-    console.log(`Module ${currentModule.code}: missing categories ${missing.join(', ')} — continuing loop`);
-    // Fall through to compact loop (section 5)
-    return;
-  }
-
-  // All categories present — module is complete
-  // Continue below...
-}
-```
-
----
-
-## Advance to Next Module
-
-```javascript
-if (missing.length === 0) {
-  // Mark current module done
-  currentModule.status = 'completed';
-  queue.completedModules++;
-  const nextIndex = queue.currentIndex + 1;
-
-  if (nextIndex < queue.totalModules) {
-    // More modules to process
-    queue.currentIndex = nextIndex;
-    queue.modules[nextIndex].status = 'in-progress';
-    writeJSON(queuePath, queue);
-
-    // Signal module transition to step-01
-    writeJSON('.ralph/module-changed.json', {
-      fromModule: currentModule.code,
-      toModule: queue.modules[nextIndex].code,
-      timestamp: new Date().toISOString()
-    });
-
-    // Mark current PRD as complete
-    prd.status = 'completed';
-    writeJSON('.ralph/prd.json', prd);
-
-    // Load next module's PRD
-    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);
-
-    console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
-
-    // Return to step-01 to load next module's tasks
-    // (step-01 will detect module-changed.json and load next PRD)
-    return GO_TO_STEP_01;
-  }
-
-  // ALL MODULES COMPLETE
-  // Continue to section 3c (completion output) → step-05
-}
-```
-
----
-
-## Check: All Modules Complete
-
-```javascript
-if (nextIndex >= queue.totalModules) {
-  // No more modules
-  writeJSON(queuePath, queue);
-  console.log(`ALL ${queue.totalModules} MODULES COMPLETE`);
-
-  // Fall through to step 3c (completion output) → step-05
-}
-```
-
----
-
-## Step-01 Module Detection
-
-When returning to step-01 after module transition:
-
-```javascript
-// In step-01, section 0:
-const moduleChangePath = '.ralph/module-changed.json';
-if (fileExists(moduleChangePath)) {
-  const transition = readJSON(moduleChangePath);
-  console.log(`Module transition: ${transition.fromModule} → ${transition.toModule}`);
-  deleteFile(moduleChangePath);
-
-  // This is an exception to "Read Once" rule — PRD has changed
-  // PROCEED with loading the new module's tasks
-}
-```
-
----
-
-## State Transitions
-
-```
-[Phase A: Module 1]
-├─ step-01: Load tasks from prd-module1.json
-├─ step-02: Delegate to /apex
-├─ step-03: Commit PRD state
-├─ step-04: Check completion
-│  └─ If all categories complete:
-│     ├─ Write module-changed.json
-│     ├─ Write next PRD to .ralph/prd.json
-│     └─ Return to step-01 ✓
-│
-└─ [Phase B: Module 2]
-   ├─ step-01: Detect module-changed.json, load next PRD
-   ├─ step-02: Delegate to /apex
-   ├─ ... (repeat for module 2)
-   │
-   └─ [Module 2 complete]
-      ├─ Mark module 2 done in modules-queue.json
-      ├─ Check if more modules
-      │  ├─ If yes: Transition to module 3 (goto Phase C)
-      │  └─ If no: Fall through to step-05 ✓
-      │
-      └─ [Phase N: Final Module]
-         ├─ ... (repeat)
-         └─ ALL MODULES COMPLETE → step-05
-```
-
----
-
-## Rules
-
-- **Module completeness check runs EVERY iteration:** Not just once
-- **Exception to "Read Once":** When transitioning modules, step-01 re-reads the new PRD
-- **Atomic module advancement:** Only transition when all required categories are complete
-- **Max iterations applies globally:** Not per-module
-- **State persistence:** modules-queue.json tracks progress across modules
+# Module Transition Logic
+
+> **Reference for:** step-04-check.md section 3b
+> **Trigger:** Multi-module mode + current module complete
+> **Purpose:** Advance to next module in queue OR finish if all done
+
+---
+
+## When Module Transition Occurs
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  const currentModule = queue.modules[queue.currentIndex];
+
+  // MODULE COMPLETENESS CHECK
+  const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+  const expected = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+  const missing = expected.filter(c => !completedCats.has(c));
+
+  if (missing.length > 0) {
+    console.log(`Module ${currentModule.code}: missing categories ${missing.join(', ')} — continuing loop`);
+    // Fall through to compact loop (section 5)
+    return;
+  }
+
+  // All categories present — module is complete
+  // Continue below...
+}
+```
+
+---
+
+## Advance to Next Module
+
+```javascript
+if (missing.length === 0) {
+  // Mark current module done
+  currentModule.status = 'completed';
+  queue.completedModules++;
+  const nextIndex = queue.currentIndex + 1;
+
+  if (nextIndex < queue.totalModules) {
+    // More modules to process
+    queue.currentIndex = nextIndex;
+    queue.modules[nextIndex].status = 'in-progress';
+    writeJSON(queuePath, queue);
+
+    // Signal module transition to step-01
+    writeJSON('.ralph/module-changed.json', {
+      fromModule: currentModule.code,
+      toModule: queue.modules[nextIndex].code,
+      timestamp: new Date().toISOString()
+    });
+
+    // Mark current PRD as complete
+    prd.status = 'completed';
+    writeJSON('.ralph/prd.json', prd);
+
+    // Load next module's PRD
+    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);
+
+    console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
+
+    // Return to step-01 to load next module's tasks
+    // (step-01 will detect module-changed.json and load next PRD)
+    return GO_TO_STEP_01;
+  }
+
+  // ALL MODULES COMPLETE
+  // Continue to section 3c (completion output) → step-05
+}
+```
+
+---
+
+## Check: All Modules Complete
+
+```javascript
+if (nextIndex >= queue.totalModules) {
+  // No more modules
+  writeJSON(queuePath, queue);
+  console.log(`ALL ${queue.totalModules} MODULES COMPLETE`);
+
+  // Fall through to step 3c (completion output) → step-05
+}
+```
+
+---
+
+## Step-01 Module Detection
+
+When returning to step-01 after module transition:
+
+```javascript
+// In step-01, section 0:
+const moduleChangePath = '.ralph/module-changed.json';
+if (fileExists(moduleChangePath)) {
+  const transition = readJSON(moduleChangePath);
+  console.log(`Module transition: ${transition.fromModule} → ${transition.toModule}`);
+  deleteFile(moduleChangePath);
+
+  // This is an exception to "Read Once" rule — PRD has changed
+  // PROCEED with loading the new module's tasks
+}
+```
+
+---
+
+## State Transitions
+
+```
+[Phase A: Module 1]
+├─ step-01: Load tasks from prd-module1.json
+├─ step-02: Delegate to /apex
+├─ step-03: Commit PRD state
+├─ step-04: Check completion
+│  └─ If all categories complete:
+│     ├─ Write module-changed.json
+│     ├─ Write next PRD to .ralph/prd.json
+│     └─ Return to step-01 ✓
+│
+└─ [Phase B: Module 2]
+   ├─ step-01: Detect module-changed.json, load next PRD
+   ├─ step-02: Delegate to /apex
+   ├─ ... (repeat for module 2)
+   │
+   └─ [Module 2 complete]
+      ├─ Mark module 2 done in modules-queue.json
+      ├─ Check if more modules
+      │  ├─ If yes: Transition to module 3 (goto Phase C)
+      │  └─ If no: Fall through to step-05 ✓
+      │
+      └─ [Phase N: Final Module]
+         ├─ ... (repeat)
+         └─ ALL MODULES COMPLETE → step-05
+```
+
+---
+
+## Rules
+
+- **Module completeness check runs EVERY iteration:** Not just once
+- **Exception to "Read Once":** When transitioning modules, step-01 re-reads the new PRD
+- **Atomic module advancement:** Only transition when all required categories are complete
+- **Max iterations applies globally:** Not per-module
+- **State persistence:** modules-queue.json tracks progress across modules