@atlashub/smartstack-cli 3.7.0 → 3.9.0

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

@@ -8,682 +8,199 @@ next_step: steps/step-05-report.md OR steps/step-01-task.md
 
 ## YOUR TASK:
 
-Check if all tasks are complete and decide whether to output completion promise or continue to next task.
+Check if all tasks are complete and decide: output completion promise, advance module, or continue loop.
 
 ---
 
-## EXECUTION SEQUENCE:
-
-### 1. Read Current State
-
-**Load prd.json:**
+## 1. Read Current State
 
 ```javascript
 const prd = readJSON('.ralph/prd.json');
-
 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;
-const tasksBlocked   = prd.tasks.filter(t => t.status === 'blocked').length;
-const tasksPending   = prd.tasks.filter(t => t.status === 'pending').length;
-const tasksTotal     = prd.tasks.length;
-
-const allDone      = (tasksCompleted + tasksSkipped) === tasksTotal;
-const hasFailures  = tasksFailed > 0;
-const hasBlocked   = tasksBlocked > 0;
-const hasPending   = tasksPending > 0;
+const tasksSkipped = prd.tasks.filter(t => t.status === 'skipped').length;
+const tasksFailed = prd.tasks.filter(t => t.status === 'failed').length;
+const tasksBlocked = prd.tasks.filter(t => t.status === 'blocked').length;
+const tasksPending = prd.tasks.filter(t => t.status === 'pending').length;
+const tasksTotal = prd.tasks.length;
+const allDone = (tasksCompleted + tasksSkipped) === tasksTotal;
 ```
 
-### 1.5. REGRESSION CHECK (MANDATORY AFTER EACH ITERATION)
-
-**CRITICAL: After EVERY task completion, run full test suite to detect regressions.**
+### 1.5. Regression Check (BLOCKING)
 
+**Backend — build + tests:**
 ```bash
-PROJECT_NAME=$(basename $(pwd))
-TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+dotnet build --no-restore
+if [ $? -ne 0 ]; then
+  echo "BUILD REGRESSION — creating fix task"
+  # Inject fix task, category: validation, acceptance: "dotnet build passes"
+fi
 
+TEST_PROJECT="tests/$(basename $(pwd)).Tests.Unit"
 if [ -d "$TEST_PROJECT" ]; then
-  echo "🔍 Running regression check (full test suite)..."
-
-  # Run ALL tests to ensure nothing broke
-  dotnet test "$TEST_PROJECT" --no-build --verbosity minimal --logger "console;verbosity=minimal"
-
-  REGRESSION_EXIT_CODE=$?
-
-  if [ $REGRESSION_EXIT_CODE -ne 0 ]; then
-    echo "╔════════════════════════════════════════════════════════════╗"
-    echo "║  ⚠️  REGRESSION DETECTED                                  ║"
-    echo "╠════════════════════════════════════════════════════════════╣"
-    echo "║  A previously passing test is now failing.                 ║"
-    echo "║  This indicates the last change broke existing code.       ║"
-    echo "╠════════════════════════════════════════════════════════════╣"
-    echo "║  CORRECTIVE ACTION:                                        ║"
-    echo "║  1. Identify which test(s) started failing                 ║"
-    echo "║  2. Analyze what changed in last commit                    ║"
-    echo "║  3. Fix the regression                                     ║"
-    echo "║  4. Commit the fix                                         ║"
-    echo "║  5. Ralph will continue automatically                      ║"
-    echo "╚════════════════════════════════════════════════════════════╝"
-
-    // Parse test output to identify which tests failed
-    const regressionTests = parseFailedTests(testOutput);
-
-    // Log regression details to progress.txt
-    const progressEntry = `
-[REGRESSION DETECTED - Iteration ${prd.config.current_iteration}]
-Failed tests: ${regressionTests.join(', ')}
-Last completed task: ${prd.tasks.find(t => t.id === lastCompletedTaskId).description}
-Commit: ${lastCommitHash}
-
-ACTION REQUIRED: Fix regression before continuing.
-`;
-    appendToFile('.ralph/progress.txt', progressEntry);
-
-    // Mark current state as having regression
-    prd.regression_detected = {
-      iteration: prd.config.current_iteration,
-      failed_tests: regressionTests,
-      last_task: lastCompletedTaskId,
-      commit_hash: lastCommitHash
-    };
+  dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+  if [ $? -ne 0 ]; then
+    echo "TEST REGRESSION — creating fix task"
+    # Inject fix task into prd.json:
+    prd.tasks.push({ id: maxId+1, description: "Fix test regression — all tests must pass",
+      status: "pending", category: "validation", dependencies: [],
+      acceptance_criteria: "dotnet test exits 0, all tests pass" });
     writeJSON('.ralph/prd.json', prd);
+  fi
+fi
+```
 
-    // Create a new task to fix the regression
-    const fixTask = {
-      id: prd.tasks.length + 1,
-      description: `Fix regression: ${regressionTests.length} test(s) failing`,
-      status: 'pending',
-      category: 'validation',
-      dependencies: [],
-      acceptance_criteria: `All tests pass: ${regressionTests.join(', ')}`,
-      started_at: null,
-      completed_at: null,
-      iteration: null,
-      commit_hash: null,
-      files_changed: { created: [], modified: [] },
-      validation: null,
-      error: null
-    };
-    prd.tasks.push(fixTask);
-    prd.updated_at = new Date().toISOString();
+**Frontend — typecheck + lint:**
+```bash
+if [ -f "web/package.json" ] || [ -f "package.json" ]; then
+  npm run typecheck
+  if [ $? -ne 0 ]; then
+    echo "FRONTEND REGRESSION — creating fix task"
+    prd.tasks.push({ id: maxId+1, description: "Fix frontend typecheck errors",
+      status: "pending", category: "frontend", dependencies: [],
+      acceptance_criteria: "npm run typecheck exits 0" });
     writeJSON('.ralph/prd.json', prd);
-
-    // DO NOT STOP - continue to next task (which is the fix task)
-    echo "📋 Created task ${fixTask.id}: Fix regression";
-  } else {
-    echo "✅ Regression check passed. No tests broken.";
-
-    // Update test metrics in progress.txt
-    const testStats = parseTestStats(testOutput);
-    const metricsEntry = `
-[Test Metrics - Iteration ${prd.config.current_iteration}]
-Total: ${testStats.total} | Passed: ${testStats.passed} | Failed: ${testStats.failed} | Skipped: ${testStats.skipped}
-Duration: ${testStats.duration}
-`;
-    appendToFile('.ralph/progress.txt', metricsEntry);
-  }
+  fi
 fi
 ```
 
-### 2. Check Iteration Limit
-
-**If `prd.config.current_iteration` > `prd.config.max_iterations`:**
+## 2. Check Iteration Limit
 
+If `current_iteration > max_iterations`:
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║  ⚠️ MAX ITERATIONS REACHED                                     ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Iterations: {current_iteration} / {max_iterations}             ║
-║  Tasks: {tasksCompleted} / {tasksTotal} complete                ║
-║  Failed: {tasksFailed}  |  Blocked: {tasksBlocked}             ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Ralph loop stopped due to iteration limit.                     ║
-║  Remaining tasks:                                                ║
-║  {list of tasks with status != completed and != skipped}        ║
-╚══════════════════════════════════════════════════════════════════╝
-
+MAX ITERATIONS REACHED: {iteration}/{max} | {completed}/{total} done
 -> Generating partial report...
 ```
+Set `prd.status = 'partial'` → step-05.
 
-**Update prd.json:**
-```javascript
-prd.status = 'partial';
-prd.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
-```
+## 3. Check All Tasks Complete
 
-**Proceed to step-05-report.md**
+If `allDone`:
 
-### 3. Check All Tasks Complete
+### 3a. Team Mode (multi-module with Agent Teams)
 
-**If allDone = true:**
+```javascript
+if ({team_active}) {
+  // Signal team lead that this module is done
+  SendMessage({
+    type: "message", recipient: "team-lead",
+    content: `MODULE_COMPLETE:${current_module}`,
+    summary: `${current_module} complete`
+  });
+  // STOP — team lead manages next module
+  return;
+}
+```
 
-**First, check for multi-module queue:**
+### 3b. Sequential Multi-Module (modules-queue.json)
 
 ```javascript
 const queuePath = '.ralph/modules-queue.json';
-const hasQueue = fileExists(queuePath);
-
-if (hasQueue) {
+if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
 
-  // ✅ FIX #4: MODULE COMPLETENESS CHECK (MANDATORY before advancing)
-  // A module is NOT complete unless all expected layers have at least one completed task.
-  // This prevents marking a module as "done" when only backend was implemented.
-  const completedCategories = new Set(
-    prd.tasks.filter(t => t.status === 'completed').map(t => t.category)
-  );
-  const expectedCategories = ['domain', 'infrastructure', 'application', 'api', 'frontend', 'test'];
-  const missingCategories = expectedCategories.filter(c => !completedCategories.has(c));
-
-  if (missingCategories.length > 0) {
-    console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  ⚠️ MODULE INCOMPLETE: Missing layers                           ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Module: ${currentModule.code}                                   ║
-║  Missing: ${missingCategories.join(', ')}                        ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Injecting guardrail tasks for missing layers...                 ║
-╚══════════════════════════════════════════════════════════════════╝
-    `);
-
-    // Inject guardrail tasks for each missing category
-    let maxId = Math.max(...prd.tasks.map(t => t.id));
-    const lastCompletedByCategory = {};
-    for (const task of prd.tasks) {
-      if (task.status === 'completed') lastCompletedByCategory[task.category] = task.id;
-    }
+  // MODULE COMPLETENESS CHECK: verify all expected layers
+  const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+  const expected = ['domain', 'infrastructure', 'application', 'api', 'frontend', 'test'];
+  const missing = expected.filter(c => !completedCats.has(c));
 
-    for (const cat of missingCategories) {
+  if (missing.length > 0) {
+    // Inject guardrail tasks for missing layers
+    let maxId = Math.max(...prd.tasks.map(t => t.id));
+    for (const cat of missing) {
       maxId++;
-      const depId = cat === 'frontend'
-        ? (lastCompletedByCategory['api'] || lastCompletedByCategory['application'])
-        : cat === 'test'
-        ? (lastCompletedByCategory['api'] || lastCompletedByCategory['frontend'])
-        : (lastCompletedByCategory['domain'] || lastCompletedByCategory['infrastructure']);
-
       prd.tasks.push({
-        id: maxId,
-        description: `[${cat}] GUARDRAIL: Generate missing ${cat} layer for module ${currentModule.code}`,
-        status: 'pending',
-        category: cat,
-        dependencies: depId ? [depId] : [],
-        acceptance_criteria: `${cat} layer fully implemented for module ${currentModule.code}`,
-        started_at: null, completed_at: null, iteration: null, commit_hash: null,
-        files_changed: { created: [], modified: [] },
+        id: maxId, description: `[${cat}] GUARDRAIL: Generate missing ${cat} for ${currentModule.code}`,
+        status: 'pending', category: cat, dependencies: [],
+        acceptance_criteria: `${cat} layer fully implemented`, started_at: null, completed_at: null,
+        iteration: null, commit_hash: null, files_changed: { created: [], modified: [] },
         validation: null, error: null, module: currentModule.code
       });
-      console.log(`  → Injected task ${maxId}: [${cat}] guardrail for ${currentModule.code}`);
     }
-
-    prd.updated_at = new Date().toISOString();
     writeJSON('.ralph/prd.json', prd);
-
-    // DO NOT mark module as complete — continue the COMPACT LOOP with new tasks
-    // Fall through to section 5 (COMPACT LOOP)
+    // Fall through to section 5 (compact loop)
   } else {
+    // Module complete — advance
+    currentModule.status = 'completed';
+    queue.completedModules++;
+    const nextIndex = queue.currentIndex + 1;
+
+    if (nextIndex < queue.totalModules) {
+      queue.currentIndex = nextIndex;
+      queue.modules[nextIndex].status = 'in-progress';
+      writeJSON(queuePath, queue);
+
+      // Create transition marker
+      writeJSON('.ralph/module-changed.json', {
+        fromModule: currentModule.code, toModule: queue.modules[nextIndex].code,
+        timestamp: new Date().toISOString()
+      });
 
-  // Mark current module as completed (only when ALL layers verified)
-  currentModule.status = 'completed';
-  queue.completedModules++;
-
-  // Check if more modules remain
-  const nextIndex = queue.currentIndex + 1;
+      // Load next module PRD
+      prd.status = 'completed';
+      writeJSON('.ralph/prd.json', 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}`);
+      // → step-01 (module transition)
+      return;
+    }
 
-  if (nextIndex < queue.totalModules) {
-    // ADVANCE TO NEXT MODULE
-    queue.currentIndex = nextIndex;
-    queue.modules[nextIndex].status = 'in-progress';
+    // ALL MODULES COMPLETE
     writeJSON(queuePath, queue);
-
-    // ✅ FIX #1: Create module transition marker
-    // This signals to step-01 that it MUST reload even on iteration > 1
-    writeJSON('.ralph/module-changed.json', {
-      fromModule: currentModule.code,
-      toModule: queue.modules[nextIndex].code,
-      timestamp: new Date().toISOString()
-    });
-
-    // Mark current prd.json as completed
-    prd.status = 'completed';
-    prd.updated_at = new Date().toISOString();
-    writeJSON('.ralph/prd.json', prd);
-
-    // ✅ FIX #2: Load next module's PRD NOW and reset iteration counter
-    const nextModulePrd = readJSON(queue.modules[nextIndex].prdFile);
-    nextModulePrd.config.current_iteration = 1;
-    nextModulePrd.config.max_iterations = prd.config.max_iterations; // Preserve
-    nextModulePrd.updated_at = new Date().toISOString();
-    writeJSON('.ralph/prd.json', nextModulePrd);
-
-    console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  ✅ MODULE COMPLETE: ${currentModule.code}                      ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Tasks: ${tasksCompleted} completed, ${tasksSkipped} skipped    ║
-║  Modules: ${queue.completedModules} / ${queue.totalModules}     ║
-╠══════════════════════════════════════════════════════════════════╣
-║  ADVANCING TO NEXT MODULE: ${queue.modules[nextIndex].code}     ║
-║  Next module PRD loaded: ${queue.modules[nextIndex].prdFile}    ║
-║  Iteration counter reset: 1                                      ║
-╚══════════════════════════════════════════════════════════════════╝
-    `);
-
-    // Loop back to step-01 which will detect module-changed.json
-    // and skip the "Only Read Once" rule for this transition
-    // -> Proceed to step-01-task.md
-    return;
+    console.log(`ALL ${queue.totalModules} MODULES COMPLETE`);
   }
-
-  // ALL MODULES COMPLETE - fall through to completion below
-  writeJSON(queuePath, queue);
-
-  console.log(`
-╔══════════════════════════════════════════════════════════════════╗
-║  ✅ ALL MODULES COMPLETE                                        ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Modules: ${queue.completedModules} / ${queue.totalModules}     ║
-║  ${queue.modules.map(m => m.code + ": " + m.status).join("\n║  ")} ║
-╚══════════════════════════════════════════════════════════════════╝
-  `);
-  } // end else (module completeness check passed)
 }
 ```
 
-**Then output completion (single module or all modules done):**
-
-```
-╔══════════════════════════════════════════════════════════════════╗
-║  ✅ ALL TASKS COMPLETE                                          ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Iterations: {current_iteration - 1}                            ║
-║  Tasks: {tasksCompleted} completed, {tasksSkipped} skipped      ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Output completion promise:                                      ║
-║  <promise>{completion_promise}</promise>                         ║
-╚══════════════════════════════════════════════════════════════════╝
-
-<promise>{completion_promise}</promise>
-```
-
-**Update prd.json:**
-```javascript
-prd.status = 'completed';
-prd.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
-```
+### 3c. Completion Output
 
-**CRITICAL: Output the promise tag exactly as shown:**
 ```
+ALL TASKS COMPLETE | Iterations: {n} | Tasks: {completed}/{total}
 <promise>{completion_promise}</promise>
 ```
 
-**Proceed to step-05-report.md**
+Set `prd.status = 'completed'` → step-05.
 
-### 4. Check for Dead-End (all remaining are blocked/failed)
-
-**If !hasPending AND !allDone:**
-
-All remaining tasks are blocked or failed. No progress is possible.
+## 4. Dead-End Check
 
+If `!hasPending && !allDone`: all remaining blocked/failed, no progress possible.
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║  ⚠️ DEAD-END DETECTED                                          ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Tasks: {tasksCompleted} completed, {tasksFailed} failed,       ║
-║         {tasksBlocked} blocked                                   ║
-╠══════════════════════════════════════════════════════════════════╣
-║  No more tasks can be executed.                                  ║
-║  Failed tasks:                                                   ║
-║  {list of failed tasks with error messages}                     ║
-║                                                                  ║
-║  Blocked tasks (downstream):                                     ║
-║  {list of blocked tasks with dependency info}                   ║
-╚══════════════════════════════════════════════════════════════════╝
-
--> Generating partial report...
-```
-
-**Update prd.json:**
-```javascript
-prd.status = 'failed';
-prd.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prd);
+DEAD-END: {completed} done, {failed} failed, {blocked} blocked
 ```
+Set `prd.status = 'failed'` → step-05.
 
-**Proceed to step-05-report.md**
-
-### 5. More Tasks Remaining — COMPACT LOOP (CRITICAL)
-
-> **MANDATORY RULE: DO NOT STOP. DO NOT WAIT FOR USER INPUT. DO NOT RE-READ STEP FILES.**
-> After the first full iteration (step-01 → step-02 → step-03 → step-04), all subsequent iterations
-> MUST use this COMPACT LOOP inline. Re-reading step files wastes context and causes the loop to stall.
-> **STOPPING THE LOOP = BUG.** Only completion, max iterations, or dead-end stop the loop.
-
-**If hasPending AND iteration < max_iterations:**
-
-Display compact progress (ONE line):
-```
-[{current_iteration}/{max_iterations}] {tasksCompleted}/{tasksTotal} done | Next: finding eligible task...
-```
+## 5. Compact Loop (CRITICAL)
 
-**IMMEDIATELY execute the following inline loop — DO NOT re-read step files:**
+> **MANDATORY:** After first full iteration, ALL subsequent iterations use this inline loop.
+> DO NOT stop. DO NOT wait for user. DO NOT re-read step files.
+> **Read `references/compact-loop.md` and execute inline.**
 
-#### 5a. Find Next Eligible Task (inline step-01)
+If `hasPending && iteration < max`:
 
-```javascript
-const prd = readJSON('.ralph/prd.json');
-
-// Block tasks whose dependencies failed
-for (const task of prd.tasks) {
-  if (task.status !== 'pending') continue;
-  const depsBlocked = task.dependencies.some(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && (dep.status === 'failed' || dep.status === 'blocked');
-  });
-  if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
-}
-
-// Find ALL eligible tasks (dependencies met)
-const eligible = prd.tasks.filter(task => {
-  if (task.status !== 'pending') return false;
-  return task.dependencies.every(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && dep.status === 'completed';
-  });
-});
-
-if (eligible.length === 0) {
-  // Dead-end or all done — re-run sections 2-4 above
-  goto CHECK_COMPLETION;
-}
-
-// BATCH MODE: group eligible tasks by category, take the first group
-const firstCategory = eligible[0].category;
-const batch = eligible.filter(t => t.category === firstCategory);
-// Cap batch at 5 tasks max to keep atomic
-const tasksToExecute = batch.slice(0, 5);
-```
-
-Display:
-```
-Batch: {tasksToExecute.length} task(s) [{firstCategory}]
-  {tasksToExecute.map(t => `[${t.id}] ${t.description}`).join('\n  ')}
-```
-
-#### 5b. Execute Batch (inline step-02)
-
-**For EACH task in tasksToExecute:**
-
-1. Mark `task.status = 'in_progress'`, `task.started_at = now`
-2. ULTRA THINK: implement the task following SmartStack conventions
-   - Track files_created and files_modified per task
-3. **MANDATORY TEST-DRIVEN CYCLE (per task):**
-   ```
-   ┌─────────────────────────────────────────────────────────┐
-   │  TASK EXECUTION CYCLE (100% tests pass required)       │
-   ├─────────────────────────────────────────────────────────┤
-   │                                                         │
-   │  1. GENERATE CODE                                       │
-   │     ├─ Backend:  Entity, Service, Repository, Controller│
-   │     ├─ Frontend: Page, Component, Hook                 │
-   │     ├─ Tests:    Unit tests + Integration tests        │
-   │     └─ Docs:     Inline comments + tooltips + i18n     │
-   │                                                         │
-   │  2. COMPILE CODE                                        │
-   │     ├─ Backend:  dotnet build --no-restore             │
-   │     └─ Frontend: npm run typecheck                     │
-   │                                                         │
-   │  3. RUN TESTS (MANDATORY)                               │
-   │     ├─ Backend:  dotnet test {TestProject}             │
-   │     ├─ Frontend: npm test (if applicable)              │
-   │     └─ Security: tenant isolation + RBAC checks        │
-   │                                                         │
-   │  4. CHECK RESULT                                        │
-   │     ├─ IF 100% PASS → Mark task completed, next task   │
-   │     └─ IF ANY FAIL  → Go to step 5                     │
-   │                                                         │
-   │  5. FIX ERRORS (loop until pass)                        │
-   │     ├─ Parse test output → identify failing tests      │
-   │     ├─ Analyze root cause (stack trace, logs)          │
-   │     ├─ Fix code (NOT test - fix implementation)        │
-   │     ├─ Re-compile (step 2)                             │
-   │     └─ Re-run tests (step 3) → loop until 100% pass    │
-   │                                                         │
-   │  🎯 Goal: ZERO test failures before next task           │
-   │  📊 Coverage: 95-100% (tests auto-generated per task)   │
-   │                                                         │
-   └─────────────────────────────────────────────────────────┘
-   ```
-
-   **Implementation per task:**
-   a. Generate code + tests
-   b. Compile: `dotnet build` or `npm run typecheck`
-   c. Run tests: `dotnet test {TestProject}` or `npm test`
-   d. Parse test output → count passed/failed/skipped
-   e. IF failed > 0:
-      - Log failure details to progress.txt
-      - Analyze error (stack trace, assertion message)
-      - Fix code (modify implementation, NOT test)
-      - Re-compile
-      - Re-run tests
-      - Repeat until passed = total (100%)
-   f. IF passed = total → task.status = 'completed'
-
-4. Verify acceptance criteria
-5. If task execution failed (not tests, but code generation): set `task.status = 'failed'`, `task.error = reason`, continue to next task in batch
-
-**CATEGORY-SPECIFIC EXECUTION RULES:**
-
-**IF category = "frontend":** Follow MCP-FIRST protocol (MANDATORY):
-  1. Call `mcp__smartstack__scaffold_api_client` → generates API client + types
-  2. Call `mcp__smartstack__scaffold_routes` → updates routes inside Layout wrapper
-  3. Create pages using SmartStack components (SmartTable, EntityCard, SmartForm, SmartFilter)
-  4. CSS variables ONLY (NO `bg-blue-600`, use `bg-[var(--color-accent-600)]`)
-  5. `EntityCard` for grids, `SmartTable` for lists (NO HTML `<table>` or custom `<div>` cards)
-  6. All pages MUST have loading/error/empty states
-  7. API client uses `@/services/api/apiClient` (NOT axios)
-  8. Generate 4-language i18n (fr, en, it, de)
-  9. `npm run typecheck` MUST pass
-
-**IF category = "domain":** Entities in `Domain/Entities/{ContextPascal}/{App}/{Module}/`, Enums in `Domain/Enums/{ContextPascal}/{App}/{Module}/`
-
-**IF category = "application":** Services in `Application/Services/{ContextPascal}/{App}/{Module}/`, DTOs in `Application/DTOs/{ContextPascal}/{App}/{Module}/`
-
-**IF category = "infrastructure":**
-  - EF configs in `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/`
-  - Seed data in `Infrastructure/Persistence/Seeding/Data/{Module}/`
-  - **IF task description contains "seed data", "SeedData", or "IClientSeedDataProvider":**
-    Read `references/core-seed-data.md` for COMPLETE execution guidance (parameter extraction,
-    MCP `generate_permissions` call, code templates, IClientSeedDataProvider, verification checklist).
-    **Do NOT improvise core seed data generation.**
-
-**IF category = "api":** Controllers in `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs`
-
-After ALL tasks in batch executed:
-- Run `mcp__smartstack__validate_conventions` ONCE for the whole batch
-- Quick build check: `dotnet build --no-restore` (backend) or `npm run typecheck` (frontend)
-
-#### 5c. Commit Batch (inline step-03)
-
-```bash
-# Stage all changed files
-git add {all files from batch}
-git add .ralph/prd.json
-
-# Single commit for the batch
-git commit -m "$(cat <<'EOF'
-feat({scope}): [{firstCategory}] {tasksToExecute.length} tasks — {short summary}
-
-Tasks: {tasksToExecute.map(t => t.id).join(', ')} / {tasks_total}
-Iteration: {current_iteration}
-{current_module ? "Module: " + current_module : ""}
-
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-EOF
-)"
-
-COMMIT_HASH=$(git rev-parse --short HEAD)
-```
-
-**Finalize each task in prd.json:**
-```javascript
-for (const task of tasksToExecute) {
-  if (task.status !== 'failed') task.status = 'completed';
-  task.completed_at = now;
-  task.iteration = prd.config.current_iteration;
-  task.commit_hash = COMMIT_HASH;
-}
-prd.history.push({
-  iteration: prd.config.current_iteration,
-  task_ids: tasksToExecute.map(t => t.id),
-  action: 'batch-completed',
-  timestamp: now,
-  commit_hash: COMMIT_HASH,
-  notes: "{What was accomplished}"
-});
-prd.config.current_iteration++;
-prd.updated_at = now;
-writeJSON('.ralph/prd.json', prd);
-```
-
-```bash
-git add .ralph/prd.json .ralph/progress.txt
-[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
-git commit -m "chore(ralph): progress — iteration {current_iteration}"
-```
-
-#### 5d. Re-check Completion (loop back to section 1)
-
-**IMMEDIATELY go back to section 1 (Read Current State) of THIS step.**
-**DO NOT stop. DO NOT wait for user. DO NOT re-read step files.**
-
----
-
-## DECISION TREE:
-
-```
-                    ┌─────────────────────┐
-                    │  Check Completion   │
-                    └──────────┬──────────┘
-                               │
-          ┌────────────────────┼────────────────────┐
-          │                    │                    │
-          ▼                    ▼                    ▼
-   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
-   │ Max Iters    │   │ All Tasks    │   │ Tasks        │
-   │ Reached      │   │ Done         │   │ Remaining    │
-   └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
-          │                  │                   │
-          │         ┌────────┴────────┐  ┌───────┴────────┐
-          │         │                 │  │                │
-          ▼         ▼                 ▼  ▼                ▼
-   ┌────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-   │ Partial    │ │ More modules│ │ No more     │ │ Dead-End /  │
-   │ Report     │ │ in queue?   │ │ modules     │ │ Loop to     │
-   │ step-05    │ │ → step-01   │ │ → Promise   │ │ step-01     │
-   │ status:    │ │ (next mod)  │ │ → step-05   │ │             │
-   │ "partial"  │ └─────────────┘ └─────────────┘ └─────────────┘
-   └────────────┘
-```
-
----
-
-## OUTPUT FORMAT:
-
-**If continuing:**
-```
-Completion Check:
-
-| Field | Value |
-|-------|-------|
-| Iteration | {current_iteration} / {max_iterations} |
-| Completed | {tasksCompleted} / {tasksTotal} |
-| Failed | {tasksFailed} |
-| Blocked | {tasksBlocked} |
-| Pending | {tasksPending} |
-| Status | Continuing |
-
--> Loading next task...
-```
-
-**If complete:**
-```
-Completion Check:
-
-| Field | Value |
-|-------|-------|
-| Iterations Used | {current_iteration - 1} |
-| Completed | {tasksCompleted} / {tasksTotal} |
-| Skipped | {tasksSkipped} |
-| Status | COMPLETE |
-
-<promise>{completion_promise}</promise>
-
--> Generating report...
-```
-
-**If partial/failed:**
-```
-Completion Check:
-
-| Field | Value |
-|-------|-------|
-| Iterations Used | {current_iteration - 1} |
-| Completed | {tasksCompleted} / {tasksTotal} |
-| Failed | {tasksFailed} |
-| Blocked | {tasksBlocked} |
-| Status | {PARTIAL or FAILED} |
-| Reason | {max iterations / dead-end} |
-
--> Generating report...
-```
+1. Read `references/compact-loop.md`
+2. Execute sections A → B → C → D inline
+3. Return to section 1 of THIS step
 
 ---
 
 ## CRITICAL RULES:
 
-**NEVER output the completion promise unless:**
-1. ALL tasks have `status: "completed"` or `status: "skipped"`
-2. Zero tasks with `status: "blocked"` or `status: "failed"`
-3. The statement is genuinely true
-4. **Multi-module:** ALL modules in `modules-queue.json` have `status: "completed"`
-
-**False promises to escape the loop are FORBIDDEN.**
-
-**Always update `prd.status` and `prd.updated_at` before proceeding.**
-
-**NEVER DELEGATE THE LOOP:**
-- NEVER use the Task tool to spawn a sub-agent for Ralph loop execution.
-- Sub-agents lose ALL skill context and WILL stop prematurely.
-- The ONLY acceptable Task usage: isolated read-only research (e.g., Context7 docs lookup).
-
-**MODULE COMPLETENESS (multi-module):**
-- Before advancing to the next module, verify ALL expected layers have completed tasks.
-- Expected layers: domain, infrastructure, application, api, frontend, test.
-- If any layer is missing, inject guardrail tasks and continue the COMPACT LOOP.
-- A module with only backend tasks is NOT complete.
-
-**LOOP CONTINUATION IS MANDATORY:**
-- After the first full iteration (step-01→02→03→04), ALL subsequent iterations use the COMPACT LOOP in section 5.
-- DO NOT re-read step-01, step-02, step-03 files. You already know the instructions.
-- DO NOT stop and wait for user input between iterations.
-- DO NOT output a summary and pause. The loop is AUTONOMOUS.
-- DO NOT decide to stop because "quality over quantity" or "this is enough for now".
-- DO NOT stop after completing one module when others remain in the queue.
-- DO NOT reduce scope autonomously ("I'll skip frontend/tests to save time").
-- The ONLY reasons to stop: ALL tasks complete (all modules), max iterations, dead-end, or user Ctrl+C.
-- Stopping for any other reason is a **BUG** that wastes user time and context.
-- **BATCH tasks of the same category** to reduce iterations (max 5 per batch).
-- Prefer compact output (1-2 lines per task) over verbose output during the loop.
+- **NEVER** output completion promise unless ALL tasks done (all modules if multi)
+- **NEVER** delegate the loop to sub-agents (except team mode for multi-module)
+- **NEVER** stop between iterations
+- **BATCH** same-category tasks (max 5)
+- **MODULE COMPLETENESS:** All layers must have completed tasks before advancing
+- Only valid stop: all complete, max iterations, dead-end, or user Ctrl+C
 
 ---
 
 ## NEXT STEP:
 
-- If all tasks complete AND more modules in queue: `./step-01-task.md` (next module)
-- If all tasks complete AND no more modules (or no queue): `./step-05-report.md`
-- If max iterations or dead-end: `./step-05-report.md`
-- If tasks remaining in current module: `./step-01-task.md`
+- All done + more modules in queue → `./step-01-task.md`
+- All done (no more modules) → `./step-05-report.md`
+- Max iterations or dead-end → `./step-05-report.md`
+- Tasks remaining → compact loop (section 5)