@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/business-analyse-develop/references/init-resume-recovery.md

@@ -1,183 +0,0 @@
-# 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(currentPrdPath);
-
-// 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 business-analyse-handoff` 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
-}
-```
-
-### Ralph State Recovery (context compression defense)
-
-> **When context compression occurs mid-execution**, conversation variables are lost.
-> `ralph-state.json` tracks the current position and is written before each major transition.
-> This section reads it back to recover position.
-
-```javascript
-// ALWAYS attempt to read ralph-state.json on resume — regardless of -r flag
-// This file is written by: step-00 init, step-02 execute, compact-loop, module-transition
-const statePath = '.ralph/ralph-state.json';
-if (fileExists(statePath)) {
-  const state = readJSON(statePath);
-
-  console.log(`Ralph state recovered: step=${state.currentStep}, module=${state.currentModule}, ` +
-    `iteration=${state.iteration || '?'}, reason=${state.reason || 'normal'}`);
-
-  // Restore conversation variables from state
-  if (state.currentModule) {
-    {current_module} = state.currentModule;
-  }
-  if (state.iteration) {
-    {current_iteration} = state.iteration;
-  }
-  if (state.prdVersion) {
-    {prd_version} = state.prdVersion;
-  }
-
-  // Route to the correct step based on saved state
-  // This replaces the default "always go to step-01" behavior
-  const stepRouting = {
-    'step-01-task':   'steps/step-01-task.md',
-    'step-02-execute': 'steps/step-02-execute.md',
-    'step-03-commit':  'steps/step-03-commit.md',
-    'step-04-check':   'steps/step-04-check.md',
-    'compact-loop':    'steps/step-04-check.md',  // compact-loop re-enters via step-04
-    'step-05-report':  'steps/step-05-report.md'
-  };
-
-  const targetStep = stepRouting[state.currentStep] || 'steps/step-01-task.md';
-
-  // Special case: module transition — go to step-01 to detect module-changed.json
-  if (state.reason === 'module-transition') {
-    console.log(`Module transition recovery: ${state.fromModule} → ${state.currentModule}`);
-    console.log('Routing to step-01-task.md to detect module-changed.json');
-    // targetStep stays 'steps/step-01-task.md'
-  }
-
-  console.log(`Recovery routing: → ${targetStep}`);
-  // The calling code (step-00) should load targetStep instead of the default step-01
-}
-```
-
-**IMPORTANT:** This recovery is triggered BEFORE the default "Proceed to step-01" routing in step-00-init.md. If ralph-state.json provides a different target step, that step should be loaded instead.
-
----
-
-## 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 business-analyse-handoff to generate PRD files
-  // Flag: --feature (path to feature.json) — matches ss business-analyse-handoff CLI convention
-  // See also: step-05c-ralph-readiness.md section 2 "Fix: ss business-analyse-handoff --feature {path} --output ..."
-  const result = exec(`ss business-analyse-handoff --feature ${masterFeature}`);
-
-  if (result.exitCode !== 0) {
-    console.error('ss business-analyse-handoff failed — cannot auto-recover');
-    STOP;
-  }
-
-  const newPrds = glob('.ralph/prd-*.json');
-  if (newPrds.length === 0) {
-    console.error('ss business-analyse-handoff 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-handoff to generate the handoff, then retry /business-analyse-develop');
-  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/business-analyse-develop/references/module-transition.md

@@ -1,246 +0,0 @@
-# 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...
-
-  // HANDOFF FILE GATE (double-security — step-04 §1.8 is primary, this is defense-in-depth)
-  // The build gate does NOT detect missing files if nothing references them (no compile error).
-  const ftc = prd.implementation?.filesToCreate;
-  if (ftc) {
-    let ftcMissing = 0;
-    const ftcDetails = [];
-    for (const [cat, files] of Object.entries(ftc)) {
-      for (const file of (files || [])) {
-        if (!fileExists(file.path || file)) {
-          ftcMissing++;
-          ftcDetails.push(`${cat}: ${(file.path || file).split('/').pop()}`);
-        }
-      }
-    }
-    if (ftcMissing > 0) {
-      console.error(`BLOCKING: ${ftcMissing} handoff files missing — cannot advance module`);
-      ftcDetails.forEach(d => console.error(`  ${d}`));
-      return; // Back to compact loop — remediation tasks already injected by category-completeness
-    }
-  }
-}
-```
-
----
-
-## Advance to Next Module
-
-```javascript
-if (missing.length === 0) {
-  // MANDATORY BUILD+TEST GATE before advancing module
-  // (audit ba-002: module marked "100% complete" despite build errors and security flaws)
-  const buildOk = execSync('dotnet build --no-restore --verbosity quiet').exitCode === 0;
-  if (!buildOk) {
-    console.error(`BLOCKING: Module ${currentModule.code} build fails — cannot advance to next module`);
-    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
-    prd.tasks.push({
-      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix build for module ${currentModule.code}`,
-      status: 'pending', category: 'validation', dependencies: [],
-      acceptance_criteria: 'dotnet build passes with 0 errors'
-    });
-    writeJSON(currentPrdPath, prd);
-    return; // Back to compact loop — do NOT advance
-  }
-
-  const testOk = execSync('dotnet test --no-build --verbosity quiet').exitCode === 0;
-  if (!testOk) {
-    console.error(`BLOCKING: Module ${currentModule.code} tests fail — cannot advance to next module`);
-    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
-    prd.tasks.push({
-      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix tests for module ${currentModule.code}`,
-      status: 'pending', category: 'validation', dependencies: [],
-      acceptance_criteria: 'dotnet test passes with 0 failures'
-    });
-    writeJSON(currentPrdPath, prd);
-    return; // Back to compact loop — do NOT advance
-  }
-
-  console.log(`MODULE GATE PASSED: ${currentModule.code} — build OK, tests OK`);
-
-  // 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 (write to module-specific file, NOT .ralph/prd.json)
-    prd.status = 'completed';
-    writeJSON(currentModule.prdFile, 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(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}`);
-
-    // CONTEXT REFRESH: Force /compact between modules to prevent context degradation
-    // (audit ba-002: quality degraded progressively — module 2 had more errors than module 1
-    // because patterns from module 1 were lost during context compaction)
-    // STATE PERSISTENCE: Write state BEFORE compaction so position survives context compression
-    writeJSON('.ralph/ralph-state.json', {
-      currentStep: 'step-01-task',
-      currentModule: queue.modules[nextIndex].code,
-      reason: 'module-transition',
-      fromModule: currentModule.code,
-      timestamp: new Date().toISOString()
-    });
-
-    console.log('Forcing /compact for fresh context before next module...');
-    // The /compact command clears accumulated tool results and intermediate reasoning,
-    // preserving only key decisions and the current state. This ensures the next module
-    // starts with a clean context window instead of degraded fragments from the previous module.
-    // INVOKE /compact
-    // After compaction: read .ralph/ralph-state.json to recover position if context lost
-
-    // 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
-}
-```
-
-### 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
-
-```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 prd-{moduleCode}.json (via currentPrdPath)
-│     └─ 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

package/templates/skills/business-analyse-develop/references/multi-module-queue.md

@@ -1,171 +0,0 @@
-# Multi-Module Queue Initialization
-
-> **Reference for:** step-01-task.md section 0
-> **Purpose:** Initialize multi-module state when 2+ PRD files detected
-> **Output:** modules-queue.json with module list and current index
-
----
-
-## Detection
-
-```javascript
-const prdFiles = glob('.ralph/prd-*.json');
-const PRD_COUNT = prdFiles.length;
-
-if (PRD_COUNT === 0) {
-  {modules_queue} = null;
-  {current_module} = null;
-  return;  // Single module mode or no PRDs
-}
-
-if (PRD_COUNT === 1) {
-  // Single module
-  {modules_queue} = null;
-  {current_module} = null;
-  return;  // Use standard mode
-}
-
-// PRD_COUNT > 1 → Multi-module detected
-```
-
----
-
-## Module Queue Construction
-
-```javascript
-const modules = [];
-
-// Step 1: Get module order from master feature.json
-const masterFeature = findFile('docs/business/**/business-analyse/**/feature.json');
-let moduleOrder = [];
-
-if (masterFeature) {
-  const master = readJSON(masterFeature);
-  moduleOrder = master.metadata?.workflow?.moduleOrder || [];
-}
-
-// Step 2: Build queue in order
-for (const mod of moduleOrder) {
-  const prdFile = `.ralph/prd-${mod.code}.json`;
-  if (fileExists(prdFile)) {
-    modules.push({
-      code: mod.code,
-      prdFile: prdFile,
-      status: 'pending'
-    });
-  }
-}
-
-// Step 3: Fallback to alphabetical if no order from feature.json
-if (modules.length === 0) {
-  for (const file of prdFiles) {
-    const code = file.match(/prd-(.+)\.json$/)[1];
-    modules.push({
-      code: code,
-      prdFile: `.ralph/${file}`,
-      status: 'pending'
-    });
-  }
-  modules.sort((a, b) => a.code.localeCompare(b.code));
-}
-
-// Step 4: Initialize first module as in-progress
-if (modules.length > 0) {
-  modules[0].status = 'in-progress';
-}
-```
-
----
-
-## Queue State Structure
-
-```javascript
-const queue = {
-  modules: modules,              // Array of {code, prdFile, status}
-  currentIndex: 0,               // Index of currently executing module
-  totalModules: modules.length,  // Total count
-  completedModules: 0            // Count of completed modules
-};
-
-writeJSON('.ralph/modules-queue.json', queue);
-
-{modules_queue} = queue;
-{current_module} = modules[0].code;
-
-console.log(`Multi-module: ${modules.length} modules → ${modules.map(m => m.code).join(' → ')}`);
-```
-
----
-
-## Module Transition (Next Iteration)
-
-When calling step-01 after a module completes:
-
-```javascript
-// Check for module transition marker
-if (fileExists('.ralph/module-changed.json')) {
-  const transition = readJSON('.ralph/module-changed.json');
-  console.log(`Module transition: ${transition.fromModule} → ${transition.toModule}`);
-  deleteFile('.ralph/module-changed.json');
-
-  // PROCEED — this is an exception to the "Read Once" rule
-  // Continue to load the new module's PRD
-}
-```
-
----
-
-## PRD Loading for Current Module
-
-```javascript
-const queuePath = '.ralph/modules-queue.json';
-if (fileExists(queuePath)) {
-  const queue = readJSON(queuePath);
-  const currentModule = queue.modules[queue.currentIndex];
-
-  const currentPrd = readJSON(currentPrdPath);
-  if (currentPrd.metadata?.moduleCode !== currentModule.code) {
-    // Module has changed — load new PRD
-    const modulePrd = readJSON(currentModule.prdFile);
-
-    // v3 FAST PATH
-    if (modulePrd.$version === '3.0.0') {
-      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(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 business-analyse-handoff` to generate v3 format.');
-      writeJSON(currentModule.prdFile, transformPrdJsonToRalphV2(modulePrd, currentModule.code));
-    }
-    // v2 legacy
-    else {
-      writeJSON(currentModule.prdFile, modulePrd);
-    }
-  }
-
-  {current_module} = currentModule.code;
-}
-```
-
----
-
-## Single Module Mode
-
-If PRD_COUNT === 0 or 1:
-- {modules_queue} = null
-- {current_module} = null
-- Skip multi-module logic
-- Use standard single-module compact loop