@atlashub/smartstack-cli 3.1.0 → 3.3.0

package/templates/skills/business-analyse/templates/tpl-launch-displays.md

@@ -0,0 +1,161 @@
+# Skill Launch Display Templates (templates/tpl-launch-displays.md)
+
+> **Used by:** step-05b-deploy (section 5-bis: Execute User Choice)
+> **Purpose:** User-facing display templates for development approach choices
+> **Note:** No emojis - uses text markers per Claude Code conventions
+
+---
+
+## 1. Ralph Loop Launch Display
+
+Display when user selects "Ralph Loop" development approach:
+
+```
+[LAUNCH] Lancement de Ralph Loop - Développement itératif automatique
+
+╔══════════════════════════════════════════════════════════════╗
+║  CYCLE RALPH LOOP - Comment ça fonctionne ?                 ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Ralph Loop exécute un cycle itératif jusqu'à 100% tests:   ║
+║                                                              ║
+║  1. ANALYSE      --> Charger task suivante du prd.json       ║
+║  2. DÉVELOPPEMENT --> Générer le code demandé                ║
+║     • Backend (Entities, Services, Controllers, Repos)      ║
+║     • Tests unitaires (xUnit) + non-régression              ║
+║     • Frontend (Pages, Components, Hooks)                   ║
+║     • Tests frontend (React Testing Library)                ║
+║     • SeedData (Core RBAC + business data)                  ║
+║     • Documentation utilisateur (inline + tooltips)         ║
+║  3. VALIDATION   --> Commit + MCP conventions check           ║
+║  4. TEST         --> Exécuter dotnet test + npm test          ║
+║  5. CORRECTION   --> Si échec, analyser et corriger           ║
+║  6. BOUCLE       --> Répéter 4-5 jusqu'à 100% tests pass      ║
+║  7. NEXT TASK    --> Passer à la task suivante (retour à 1)  ║
+║                                                              ║
+║  [TARGET] Objectif: ZÉRO ERREUR avant de passer à la task suivante║
+║  [STATS] Couverture: 95-100% (tests générés automatiquement)     ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+
+   Configuration du projet:
+   ┌────────────────────────────────────────────────────────────┐
+   │ Modules:   {modules_list}
+   │ Stratégie: {implementation_strategy}
+   │ PRD:       {prd_file_path}
+   │ Progress:  .ralph/progress.txt
+   │ Ordre:     {module_order}
+   │ └────────────────────────────────────────────────────────────┘
+
+   Modules à traiter (dans l'ordre):
+   {modules_numbered_list}
+
+   [DIR] Fichiers générés par le BA (inputs pour Ralph):
+   ├─ feature.json (master + modules) --> Spécification source
+   ├─ prd.json (ou prd-{module}.json) --> Task breakdown avec UC/FR/BR
+   ├─ progress.txt                    --> Tracker hiérarchique (module --> layer --> tasks)
+   └─ ba-interactive.html             --> Revue client (mockups, wireframes)
+
+   [LOOP] Ralph Loop va maintenant:
+   1. Détecter les prd-*.json par module (si multi-module)
+   2. Créer modules-queue.json avec l'ordre de traitement
+   3. Traiter module par module dans l'ordre topologique
+   4. Pour chaque module: parcourir les tasks (domain --> seeddata --> application --> infrastructure --> api --> frontend --> i18n --> tests)
+   5. Pour chaque task: générer code --> commit --> tests --> correction si échec --> re-test --> next task
+   6. Passer au module suivant quand 100% tasks du module actuel = completed
+   7. Générer rapport final avec métriques de couverture
+
+═══════════════════════════════════════════════════════════════
+
+--> Transition vers Ralph Loop...
+```
+
+---
+
+## 2. Feature Full Launch Display
+
+Display when user selects "Feature Full" development approach:
+
+```
+[LAUNCH] Lancement de Feature Full...
+
+   Configuration:
+   - Mode: Parallel generation
+   - Couverture: 70-80%
+   - Durée estimée: ~{estimated_hours} heures
+
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## 3. Manual Development Complete Display
+
+Display when user selects "Terminer le BA" (end Business Analysis):
+
+```
+[OK] Business Analysis terminée.
+
+   Les équipes peuvent commencer le développement manuel.
+   Tous les artefacts sont prêts pour l'implémentation.
+
+[DIR] Fichiers générés:
+   - feature.json (master + modules) - Spécification complète
+   - .ralph/prd.json (ou prd-{module}.json) - Task breakdown
+   - .ralph/progress.txt - Tracker de progression
+   - ba-interactive.html - Document de revue client
+
+[STATS] Métriques:
+   - Modules: {modules_count}
+   - Entités: {total_entities}
+   - Use cases: {total_use_cases}
+   - Business rules: {total_business_rules}
+   - Fichiers à créer: {total_files}
+
+[TARGET] Prochaines étapes recommandées:
+   1. Ouvrir ba-interactive.html dans le navigateur
+   2. Partager avec les stakeholders pour validation finale
+   3. Utiliser progress.txt comme guide de développement
+   4. Implémenter module par module selon l'ordre topologique
+
+[TIP] Pour lancer le développement assisté plus tard:
+   - Ralph Loop: /ralph-loop (détecte automatiquement .ralph/prd.json)
+   - Feature Full: /feature-full
+
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## 4. Error Handling Display
+
+Display when skill launch fails:
+
+```
+[!] Échec du lancement automatique de Ralph Loop
+
+   Veuillez lancer manuellement:
+   /ralph-loop
+
+   Si le problème persiste:
+   1. Vérifier que la skill ralph-loop est installée
+   2. Vérifier les permissions Claude Code
+   3. Consulter les logs: .ralph/logs/
+```
+
+---
+
+## Text Marker Legend
+
+| Marker | Replaces | Usage |
+|--------|----------|-------|
+| `-->` | `➡️` or `→` | Directional flow, transitions |
+| `[OK]` | `✅` | Success, completion |
+| `[!]` | `⚠️` | Warning, caution |
+| `[LAUNCH]` | `🚀` | Skill launch, startup |
+| `[DIR]` | `📂` | Files, directories, structure |
+| `[STATS]` | `📊` | Metrics, statistics, coverage |
+| `[TIP]` | `💡` | Advice, suggestions |
+| `[TARGET]` | `🎯` | Goals, objectives |
+| `[LOOP]` | `🔄` | Iteration, cycles, processing |
+| `1.`, `2.`, etc. | `1️⃣`, `2️⃣`, etc. | Numbered lists |

package/templates/skills/business-analyse/templates/tpl-progress.md

@@ -0,0 +1,171 @@
+# Progress Tracker Template (templates/tpl-progress.md)
+
+> **Used by:** step-05b-deploy (section 2: Initialize Progress Tracker)
+> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
+
+## Template
+
+```
+═════════════════════════════════════════════════════════════════
+  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
+  Project: {project_name} | Application: {app_name}
+  Modules: {count} ({moduleOrder.join(', ')})
+  Strategy: {implementation_strategy}
+  Created: {timestamp}
+  Status: HANDED-OFF
+═════════════════════════════════════════════════════════════════
+
+{For each module in topological order:}
+[MODULE: {module_name}] ({complexity})
+  Status: NOT STARTED
+  Dependencies: {list of module dependencies or "FOUNDATION"}
+
+  [DOMAIN] Entity & Value Object Definitions
+    □ Define {Entity1} entity with properties and validation
+    □ Define {Entity2} entity with relationships
+    □ Define {ValueObject1} value object
+    □ Define domain exceptions
+    □ Total: X tasks
+
+  [SEEDDATA-CORE] Core Configuration (MANDATORY)
+    □ NavigationModuleConfiguration - Module navigation structure
+    □ PermissionsConfiguration - RBAC permissions setup
+    □ RolesConfiguration - Predefined roles
+    □ TenantConfiguration - Test tenants
+    □ UserConfiguration - Test users
+    Total: 5 CORE tasks
+
+  [SEEDDATA] Business Reference Data
+    □ Seed {Entity1} reference data
+    □ Seed {Entity2} lookup values
+    □ Total: Y business seed tasks
+
+  [APPLICATION] Services & Business Logic
+    □ Create {ServiceName}Service for {UC1}
+    □ Create {DtoName}Dto for API contracts
+    □ Create {ValidatorName}Validator for input validation
+    □ Implement query handlers
+    Total: Z tasks
+
+  [INFRASTRUCTURE] Repositories & Persistence
+    □ Create {Entity1}Repository with CRUD + custom queries
+    □ Create {Entity2}Repository
+    □ Configure DbContext for module
+    □ Setup specifications for complex queries
+    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
+    □ Create DevDataSeeder + SeedConstants (if first module)
+    □ Total: A tasks
+
+  [API] REST Endpoints & Controllers
+    □ Create {ModuleNameController} GET endpoints (List, GetById)
+    □ Create {ModuleNameController} POST endpoint (Create)
+    □ Create {ModuleNameController} PUT endpoint (Update)
+    □ Create {ModuleNameController} DELETE endpoint (Delete)
+    □ Implement error handling and validation responses
+    Total: B tasks
+
+  [FRONTEND] UI Components & Pages (wireframe-driven)
+    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
+    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
+    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
+    □ Create custom hook use{ModuleName}
+    □ Implement pagination, filtering, sorting
+    □ Validate all pages match their wireframe layout
+    □ ⚠️ Routes MUST be INSIDE Layout wrapper (AdminLayout/BusinessLayout/UserLayout)
+    Total: C tasks
+
+  [I18N] Internationalization Keys
+    □ Define i18n keys for {Module} UI labels
+    □ Setup translations for locales: fr, en, it, de
+    Total: D keys
+
+  [TESTS] Unit & Integration Tests
+    □ Unit tests for {Entity} domain logic
+    □ Unit tests for {ServiceName}Service
+    □ Integration tests for {ModuleNameController}
+    □ Security tests for authorization & tenant isolation
+    □ E2E tests for critical user flows
+    Total: E unit + F integration + G security = H tests
+
+  [QA] Quality Assurance
+    □ Code review against SmartStack conventions
+    □ Test coverage minimum 80%
+    □ Security scan for OWASP vulnerabilities
+    □ Performance testing under load
+    Total: 4 QA tasks
+
+  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
+  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
+
+{If multi-module:}
+[CROSS-MODULE] Integration Tasks
+  Status: NOT STARTED
+  Dependencies: All modules COMPLETED
+
+  □ Verify cross-module entity relationships
+  □ Test cross-module API dependencies
+  □ Validate permission matrix across modules
+  □ E2E flow tests spanning multiple modules
+  □ Cross-module data consistency checks
+  □ Integration test suite for module interactions
+  Total: 6 CROSS-MODULE tasks
+
+═════════════════════════════════════════════════════════════════
+SUMMARY
+═════════════════════════════════════════════════════════════════
+Total Modules:         {count}
+Total Tasks:           {total_count}
+  - CORE SeedData:     {count} × 5 = {total_core}
+  - Business Tasks:    {total_biz}
+  - Development:       {total_dev}
+  - Tests:             {total_tests}
+  - QA:                {total_qa}
+  - Cross-Module:      {cross_module_count or 0}
+
+Strategy:              {strategy}
+Module Order:          {topological order with dependencies noted}
+
+Complexity Distribution:
+  Simple:   {count} modules ({estimate} days each)
+  Medium:   {count} modules ({estimate} days each)
+  Complex:  {count} modules ({estimate} days each)
+
+Total Effort Estimate:  {total_days} days ({total_hours} hours)
+Per Developer (2):      {total_days / 2} days
+Parallel Potential:     {strategy_efficiency_percent}%
+
+═════════════════════════════════════════════════════════════════
+LEGEND
+═════════════════════════════════════════════════════════════════
+□ = Task not started
+✓ = Task completed
+⚠ = Task in progress
+✗ = Task failed / blocked
+
+COLORS:
+[DOMAIN]      = Domain Model & Business Logic
+[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
+[SEEDDATA]    = Business reference & lookup data
+[APPLICATION] = Services, DTOs, Validators
+[INFRASTRUCTURE] = Repositories, DbContext, ORM
+[API]         = REST controllers & endpoints
+[FRONTEND]    = React pages, components, hooks
+[I18N]        = Internationalization
+[TESTS]       = Unit, Integration, Security, E2E
+[QA]          = Code quality, coverage, security
+[CROSS-MODULE] = Multi-module integration (if applicable)
+
+═════════════════════════════════════════════════════════════════
+```
+
+## Progress Tracker Rules
+
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module → layer → tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Identified dependencies for parallel execution
+- Cross-module tasks only if multi-module

package/templates/skills/ralph-loop/SKILL.md

@@ -10,27 +10,38 @@ Execute the Ralph Weegund technique - an iterative development methodology where
 </objective>
 
 <quick_start>
-**Basic usage:**
-
-```bash
-/ralph-loop implement user authentication
-```
-
-**With completion promise:**
+**Three ways to start Ralph Loop:**
+
+1. **From Business Analysis (RECOMMENDED - NEW v6.1):**
+   ```bash
+   /business-analyse MyFeature
+   # At the end, choose "Ralph Loop" → automatic launch
+   # No arguments needed - prd.json already generated
+   ```
+
+2. **Manual start with existing prd.json:**
+   ```bash
+   /ralph-loop
+   # Ralph detects .ralph/prd.json and resumes automatically
+   # Works after BA handoff or previous Ralph session
+   ```
+
+3. **Direct task (no BA):**
+   ```bash
+   /ralph-loop implement user authentication
+   # Ralph creates prd.json on the fly
+   ```
+
+**With options:**
 
 ```bash
+# Completion promise
 /ralph-loop -c "COMPLETE" refactor the cache layer
-```
 
-**With max iterations:**
-
-```bash
+# Max iterations
 /ralph-loop -m 20 -c "TESTS PASS" add comprehensive tests
-```
 
-**Verbose mode:**
-
-```bash
+# Verbose mode
 /ralph-loop -v -c "DONE" fix all linting errors
 ```
 
@@ -39,6 +50,7 @@ Execute the Ralph Weegund technique - an iterative development methodology where
 - `-m N` (max): Maximum iterations before auto-stop
 - `-c TEXT` (complete): Completion promise text
 - `-v` (verbose): Detailed logging
+- `-r` (resume): Resume from previous state
 
 See `<parameters>` for complete flag list.
 </quick_start>
@@ -99,12 +111,75 @@ The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes
 5. Claude sees previous work in the files
 6. Iteratively improves until completion promise is output
 
+**Iterative Development Cycle (per task):**
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   RALPH LOOP - CYCLE                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. ANALYSE      → Load next task from prd.json            │
+│                    (UC, FR, BR, wireframes, acceptance)     │
+│                                                             │
+│  2. DÉVELOPPEMENT → Generate code for task                  │
+│     ├─ Backend:   Entity, Service, Repository, Controller  │
+│     ├─ Tests:     Unit tests (xUnit) + non-regression      │
+│     ├─ Frontend:  Page, Component, Hook (match wireframe)  │
+│     ├─ Tests:     Frontend tests (React Testing Library)   │
+│     ├─ SeedData:  CORE RBAC (5 entries) + business data    │
+│     └─ Docs:      Inline comments + tooltips + i18n keys   │
+│                                                             │
+│  3. VALIDATION   → Commit changes + MCP conventions check   │
+│                    (validate_conventions, check_migrations) │
+│                                                             │
+│  4. TEST         → Run tests (dotnet test + npm test)       │
+│                    ├─ Unit tests                            │
+│                    ├─ Integration tests                     │
+│                    ├─ Security tests (tenant isolation)     │
+│                    └─ E2E tests (critical flows)            │
+│                                                             │
+│  5. CORRECTION   → If tests fail:                           │
+│                    ├─ Analyze error logs                    │
+│                    ├─ Fix root cause                        │
+│                    ├─ Commit fix                            │
+│                    └─ Return to step 4                      │
+│                                                             │
+│  6. NEXT TASK    → Mark task as completed, loop to step 1   │
+│                                                             │
+│  🎯 Goal: 100% tests pass before moving to next task        │
+│  📊 Coverage: 95-100% (tests auto-generated)                │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
 **Completion signal:**
 ```
 <promise>{completion_promise}</promise>
 ```
 
 The loop only stops when this exact tag is output or max iterations reached.
+
+**What Ralph generates per task:**
+- **Backend code**: Entities (Domain), Services (Application), Repositories (Infrastructure), Controllers (API)
+- **Unit tests**: xUnit tests for domain logic, services, repositories
+- **Integration tests**: Controller tests with WebApplicationFactory
+- **Frontend code**: React pages, components, custom hooks (matching BA wireframes)
+- **Frontend tests**: React Testing Library for components and pages
+- **SeedData**: 5 CORE entries (Navigation, Permissions, Roles, Tenants, Users) + business reference data
+- **Documentation**: Inline code comments, user-facing tooltips, i18n translation keys
+- **Security tests**: Tenant isolation, permission checks, OWASP validations
+
+**prd.json structure (input from BA):**
+The prd.json is generated by `/business-analyse` via `ss derive-prd` command. It contains:
+- **feature**: Feature description (from BA)
+- **tasks[]**: Task breakdown by category (domain, application, infrastructure, api, frontend, i18n, test, validation)
+  - Each task has: id, description, category, dependencies, acceptance_criteria, linkedFRs, linkedUCs, linkedBRs
+  - Frontend tasks include: linkedWireframes (screen IDs from BA mockups), wireframeAcceptanceCriteria
+  - SeedData tasks specify: category (core|business), source (specification.seedDataCore or seedDataBusiness)
+- **source**: Traceability to feature.json path (source of truth)
+- **metadata**: Project context (branch, namespace, module order)
+- **config**: max_iterations, completion_promise, current_iteration
+
+Ralph reads prd.json to know WHAT to generate, then generates it, tests it, fixes it, and moves to the next task.
 </ralph_concept>
 
 <workflow>
@@ -118,19 +193,62 @@ The loop only stops when this exact tag is output or max iterations reached.
 7. Check completion → enter COMPACT LOOP (step-04)
 8. **COMPACT LOOP** (step-04 section 5, NO re-reading step files):
    - Find eligible tasks → batch by category (max 5)
-   - Execute batch inline
-   - Commit batch
+   - Execute batch inline (generate code)
+   - Run tests (dotnet test + npm test)
+   - If tests fail: analyze → fix → re-test (loop until 100% pass)
+   - Commit batch (only when tests pass)
    - Re-check completion → loop or finish
 9. When complete: generate final report (step-05)
 
-**Multi-module flow (from BA handoff):**
-1-3. Same as standard flow
+**Multi-module flow (from BA handoff - NEW v6.1: automatic launch):**
+1-3. Same as standard flow (or launched automatically from `/business-analyse`)
 4. Detect `prd-*.json` files → create `modules-queue.json`
 5. Copy current module's prd to `prd.json`
-6. Execute all tasks for current module via COMPACT LOOP
+6. Execute all tasks for current module via COMPACT LOOP:
+   - Process tasks by category (domain → seeddata → application → infrastructure → api → frontend → i18n → tests)
+   - For each task: generate → test → fix (if needed) → re-test → commit (when pass)
+   - Each task generates: backend code + tests + frontend code + tests + seeddata + docs
+   - Each frontend task respects wireframes from BA (specification.uiWireframes[])
+   - Continue until ALL tasks of module = completed
 7. When module complete: advance to next module in queue (step-04 section 3)
 8. Repeat steps 5-7 for each module (step-01 is re-read ONLY for module transitions)
 9. When all modules done: generate cross-module report
+
+**Note:** When launched from `/business-analyse` (v6.1+), Ralph Loop receives:
+- `.ralph/prd-{module}.json` for each module (generated by `ss derive-prd`)
+  - Each prd contains: tasks breakdown with UC/FR/BR/wireframes/acceptance criteria
+  - Task categories: domain, application, infrastructure, api, frontend, i18n, test, validation
+  - Each task linked to: functional requirements (FR), use cases (UC), business rules (BR)
+  - Frontend tasks include: linkedWireframes[] (screen IDs from BA mockups)
+  - SeedData tasks specify: category (core 5 entries MANDATORY + business data)
+- `.ralph/progress.txt` with comprehensive task tracker (hierarchical: module → layer → tasks)
+- Module order from BA's topological dependency graph (dependencies first)
+- No arguments needed - fully configured by BA handoff
+
+**Task execution cycle (per task):**
+```
+LOAD TASK → GENERATE CODE → COMMIT → RUN TESTS → [FAIL?] → ANALYZE ERROR → FIX → RE-TEST → [PASS!] → NEXT TASK
+                                                    ↑___________________________________________|
+                                                         (loop until 100% tests pass)
+```
+
+**What gets generated per module:**
+1. **Domain layer**: Entities, Value Objects, Enums, Domain Exceptions
+2. **SeedData layer**: 5 CORE entries (Navigation, Permissions, Roles, Tenants, Users) + business reference data
+3. **Application layer**: Services, DTOs, Validators, Query Handlers
+4. **Infrastructure layer**: Repositories, DbContext, Specifications
+5. **API layer**: Controllers, Error Handlers, Validation Responses
+6. **Frontend layer**: Pages (matching wireframes), Components, Custom Hooks, Forms
+7. **I18n layer**: Translation keys (fr, en, it, de) for UI labels
+8. **Tests layer**: Unit tests (Domain, Application), Integration tests (API), Security tests (tenant isolation), E2E tests (critical flows)
+
+**Acceptance criteria per task:**
+- Code compiles (dotnet build + npm build)
+- Tests pass (dotnet test + npm test)
+- MCP conventions validated (validate_conventions)
+- Wireframes respected (frontend pages match BA mockups from specification.uiWireframes[])
+- Business rules implemented (BR-to-code mapping from BA)
+- Security enforced (tenant isolation, RBAC permissions)
 </workflow>
 
 <state_variables>

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -6,11 +6,35 @@ next_step: steps/step-02-execute.md
 
 # Step 1: Load Task
 
-> **CONTEXT OPTIMIZATION:** This file is only read ONCE (first iteration).
+> **MODULE TRANSITION CHECK (MANDATORY):**
+> Before applying the "Only Read Once" rule, check for module transition marker:
+
+```javascript
+const moduleChangedPath = '.ralph/module-changed.json';
+const moduleTransition = fileExists(moduleChangedPath);
+
+if (moduleTransition) {
+  const transitionData = readJSON(moduleChangedPath);
+  console.log(`🔄 Module transition detected: ${transitionData.fromModule} → ${transitionData.toModule}`);
+  console.log(`   Reloading step-01 to initialize new module...`);
+
+  // Delete flag (consume it)
+  deleteFile(moduleChangedPath);
+
+  // PROCEED with step-01 execution (skip "Only Read Once" rule below)
+  // This is the EXCEPTION case for multi-module workflows
+}
+```
+
+> **CONTEXT OPTIMIZATION:** This file is normally read ONCE per module (first iteration).
 > After the first full iteration (step-01 → step-02 → step-03 → step-04),
-> ALL subsequent iterations MUST use the COMPACT LOOP in step-04-check.md section 5.
-> **DO NOT re-read this file for iterations > 1.**
-> If you are re-reading this file on iteration > 1, STOP and go to step-04 section 5 instead.
+> ALL subsequent iterations within the SAME module MUST use the COMPACT LOOP in step-04-check.md section 5.
+> **DO NOT re-read this file for iterations > 1 of the same module.**
+>
+> **EXCEPTION:** When transitioning between modules (multi-module workflows), step-01 MUST be re-read
+> to load the next module's PRD. This is signaled by `.ralph/module-changed.json` file (checked above).
+>
+> If you are re-reading this file on iteration > 1 AND no module transition detected, STOP and go to step-04 section 5 instead.
 
 ## YOUR TASK:
 
@@ -24,7 +48,10 @@ Load the current task from prd.json or create initial task breakdown with catego
 
 ### 0. Multi-Module Queue Check
 
-**Before any other logic, check for modules-queue.json:**
+**✅ ALWAYS check for modules-queue.json, even on iteration > 1:**
+
+> **CRITICAL:** This section MUST execute even when step-01 is re-read for module transitions.
+> The module-changed.json flag (checked above) ensures this section runs when needed.
 
 ```javascript
 const queuePath = '.ralph/modules-queue.json';
@@ -34,22 +61,52 @@ if (hasQueue) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
 
-  console.log(`Module ${queue.currentIndex + 1}/${queue.totalModules}: ${currentModule.code}`);
-
-  // Copy current module's prd file to prd.json (overwrite)
-  const modulePrd = readJSON(currentModule.prdFile);
-
-  // Transform PrdJson format to Ralph v2 if needed
-  if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
-    // This is a PrdJson format from ss derive-prd → transform to Ralph v2
-    const transformedPrd = transformPrdJsonToRalphV2(modulePrd, currentModule.code);
-    writeJSON('.ralph/prd.json', transformedPrd);
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  Multi-Module Workflow Detected                                 ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Current Module: ${currentModule.code} (${queue.currentIndex + 1}/${queue.totalModules})                    ║
+║  Status: ${currentModule.status}                                ║
+║  PRD File: ${currentModule.prdFile}                             ║
+╚══════════════════════════════════════════════════════════════════╝
+  `);
+
+  // ✅ FIX #3: RESTORE multi-module state variables
+  // These variables persist across step files and are critical for multi-module coordination
+  {modules_queue} = queue;
+  {current_module} = currentModule.code;
+
+  // ✅ Load or verify current module's PRD is in .ralph/prd.json
+  // On module transition, step-04 already loaded it, but we verify here
+  const currentPrd = readJSON('.ralph/prd.json');
+
+  // Verify PRD matches current module (sanity check)
+  if (currentPrd.metadata && currentPrd.metadata.moduleCode !== currentModule.code) {
+    console.log(`⚠️  PRD mismatch detected. Loading correct PRD for module ${currentModule.code}...`);
+
+    // Load current module's PRD
+    const modulePrd = readJSON(currentModule.prdFile);
+
+    // Transform PrdJson format to Ralph v2 if needed
+    if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
+      // This is a PrdJson format from ss derive-prd → transform to Ralph v2
+      const transformedPrd = transformPrdJsonToRalphV2(modulePrd, currentModule.code);
+      writeJSON('.ralph/prd.json', transformedPrd);
+      console.log(`✅ Transformed and loaded PRD for module: ${currentModule.code}`);
+    } else {
+      // Already Ralph v2 format
+      writeJSON('.ralph/prd.json', modulePrd);
+      console.log(`✅ Loaded PRD for module: ${currentModule.code}`);
+    }
   } else {
-    // Already Ralph v2 format
-    writeJSON('.ralph/prd.json', modulePrd);
+    console.log(`✅ PRD already loaded for module: ${currentModule.code}`);
   }
 
-  console.log(`Loaded PRD for module: ${currentModule.code}`);
+  console.log(`State restored: modules_queue and current_module set`);
+} else {
+  // Single-module workflow
+  {modules_queue} = null;
+  {current_module} = null;
 }
 ```