@atlashub/smartstack-cli 4.50.0 → 4.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.50.0",
+  "version": "4.52.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/apex/SKILL.md

@@ -171,6 +171,36 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 </execution_rules>
 
+<execution_guarantee>
+
+## Execution Guarantee (CRITICAL — read before ANY step)
+
+> **The user is NOT watching. There is NOBODY to answer your questions. Stopping is a FAILURE.**
+
+When APEX runs (especially in `-d` delegate mode or `-a` auto mode), the execution is **fully autonomous**. The user has launched the command and walked away. Any pause, question, or numbered option list is a **dead end** — nobody will respond.
+
+**YOU MUST NOT:**
+- Stop to ask the user a question between layers
+- Present numbered options ("Would you like to: 1. Continue... 2. Generate... 3. Stop...")
+- Pause between layers to summarize progress and wait for confirmation
+- Stop because the work seems "large" or "complex" — that is expected
+- Add "Let me know if you want me to continue" at any point
+
+**YOU MUST:**
+- After Layer N completes, **IMMEDIATELY** load the next sub-step file. No pause, no summary, no question.
+- Execute the full pipeline: Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4 → step-04, with **ZERO pauses** between layers
+- Treat each "Load `steps/step-03X-...md`" instruction as a **mandatory immediate action**, not a suggestion
+- Continue even if a layer produced warnings (only a build gate failure after max retries is a valid stop)
+
+**The ONLY valid reasons to stop:**
+1. A build gate fails after maximum retries (3 attempts)
+2. ALL layers are completed and step-04 (eXamine) is done
+3. The user presses Ctrl+C
+
+**Anything else — including "being helpful" by asking — is a VIOLATION of the execution guarantee.**
+
+</execution_guarantee>
+
 <error_handling>
 
 ## Error Handling Strategy

package/templates/skills/apex/references/core-seed-data.md

@@ -1003,6 +1003,21 @@ public class RolePermissionSeedEntry
 
 ## 6. IClientSeedDataProvider Implementation
 
+> **IMPORTANT — HasData vs Seed*Async: TWO DIFFERENT MECHANISMS**
+>
+> | Mechanism | Where | When | Purpose |
+> |-----------|-------|------|---------|
+> | **EF Core `HasData()`** | `*Configuration.cs` (Infrastructure) | At migration time | Seeds static reference data into tables via `INSERT` in migration SQL. Data is part of the migration — no runtime code needed. |
+> | **`IClientSeedDataProvider.Seed*Async()`** | `*SeedDataProvider.cs` (Infrastructure) | At runtime startup | Seeds navigation, roles, permissions, role-permissions into the **Core** schema. Runs AFTER `MigrateAsync()` in `Program.cs`. |
+>
+> **Common mistake:** Generating `HasData()` calls for navigation/permissions instead of `Seed*Async()` methods.
+> Navigation and permission data goes into the **Core** schema (`core.nav_*`, `core.auth_*`) which is managed
+> by SmartStack, not by the client's migration. Only `IClientSeedDataProvider` can write to Core tables at runtime.
+>
+> **ANTI-STUB WARNING:** Each of the 4 Seed methods MUST contain real `context.{DbSet}.Add()` calls.
+> If ANY method is just `return Task.CompletedTask;`, the module will be **invisible** in the UI (empty menu).
+> This happens when this reference file is evicted from context by compression — see step-03b safeguard.
+
 **File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
 
 ### Critical Rules

package/templates/skills/apex/references/error-classification.md

@@ -100,6 +100,28 @@
 
 ---
 
+### Category G: PRD Quality Error (FIX = fix PRD or re-run handoff)
+
+> **These errors are NOT caused by code generation — they originate from invalid PRD data.**
+> The handoff generated file paths with illegal characters (spaces, apostrophes, accents in entity names).
+> Code generation faithfully reproduced the invalid paths → build failure.
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `error CS1001: Identifier expected` with file name containing spaces | `Type d'absence.cs` → CS1001 | Re-run `/business-analyse-handoff` with entity canonicalization |
+| `error CS1513/CS1514` with file name containing apostrophes | `Congé.cs` → accent in identifier | Fix entity name in BA or re-run handoff |
+| Path contains non-ASCII characters in `.cs` file names | `Département.cs` | Canonicalize: strip diacritics, PascalCase |
+
+**Detection heuristic:** If the error file path contains spaces, apostrophes, or accented characters, it is a PRD quality error, not a code error. Do NOT attempt to fix the generated code — fix the PRD source.
+
+**Fix procedure:**
+1. Identify the invalid entity name from the error file path
+2. Report to user: "PRD quality error — entity name '{name}' is not a valid C# identifier"
+3. Either: manually canonicalize in the PRD file, or re-run `/business-analyse-handoff` (which now includes canonicalization)
+4. Re-run `/apex -d` with the corrected PRD
+
+---
+
 ## Decision Tree
 
 When a build or runtime error occurs, follow this tree:
@@ -123,9 +145,11 @@ BUILD/RUNTIME ERROR
   |     YES -> Category E (edit config files)
   |
   +-- error CS#### (C# compiler error) ?
-  |     YES -> Is the missing type in ANY project file?
-  |           NO  -> Category A (missing package)
-  |           YES -> Category F (fix source code)
+  |     YES -> Does the error file path contain spaces, apostrophes, or accents?
+  |           YES -> Category G (PRD quality error — fix handoff, not code)
+  |           NO  -> Is the missing type in ANY project file?
+  |                 NO  -> Category A (missing package)
+  |                 YES -> Category F (fix source code)
   |
   +-- Test failure (Assert/Expected) ?
         YES -> Category F (fix source code, NOT tests)

package/templates/skills/apex/references/post-checks.md

@@ -90,7 +90,7 @@ bash references/checks/infrastructure-checks.sh
 | C20 | WARNING | Section route completeness (NavigationSection → frontend route + permissions) | seed-checks.sh |
 | C21 | WARNING | FORBIDDEN route patterns — /list and /detail/:id | seed-checks.sh |
 | C22 | WARNING | Permission path segment count (2-4 dots expected) | seed-checks.sh |
-| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods + DI registration | seed-checks.sh |
+| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods with real implementation (not stubs) + DI registration | seed-checks.sh |
 | C32 | CRITICAL | Translation seed data must have idempotency guard | seed-checks.sh |
 | C33 | CRITICAL | Resource seed data must use actual section IDs from DB | seed-checks.sh |
 | C34 | BLOCKING | NavRoute segments must use kebab-case for multi-word codes — MCP overlap | seed-checks.sh |
@@ -101,6 +101,8 @@ bash references/checks/infrastructure-checks.sh
 | C47 | WARNING | Person Extension entities must not duplicate User fields | seed-checks.sh |
 | C48 | CRITICAL | Person Extension service must Include(User) | seed-checks.sh |
 | C53 | BLOCKING | Enum serialization — JsonStringEnumConverter required | seed-checks.sh |
+| C57 | BLOCKING | SeedDataProvider Seed*Async methods must NOT be `return Task.CompletedTask` or empty body — stubs cause empty menu | seed-checks.sh |
+| C58 | BLOCKING | File paths in filesToCreate must be valid C# identifiers — no spaces, apostrophes, or accents | seed-checks.sh |
 
 ### Architecture — Clean Architecture Layer Isolation (A1-A8)
 

package/templates/skills/apex/steps/step-00-init.md

@@ -94,6 +94,46 @@ if (prd.specificationFiles) {
 
 Each layer step (step-03a through step-03d) will load its companion files at the start. This provides full BA specifications (entity attributes, BR formulas, UC steps, screen columns) without loading the entire spec corpus.
 
+**PRD Quality Gate (delegate mode — BLOCKING):**
+
+> Validate that PRD file paths are valid C# identifiers BEFORE starting execution.
+> Invalid entity names (French with spaces/apostrophes/accents) cause CS1001 build errors
+> that waste 3+ retry iterations before being correctly classified.
+
+```javascript
+// Extract all file paths from PRD
+const filesToCreate = prd.$version === '4.0.0' ? prd.expectedFiles : prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  const invalidPaths = [];
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      const filePath = file.path || file;
+      // Extract filename (without extension) from path
+      const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
+      // Check for illegal characters in C# identifiers
+      if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
+        invalidPaths.push({ category, path: filePath, fileName });
+      }
+    }
+  }
+
+  if (invalidPaths.length > 0) {
+    console.error('BLOCKING — PRD QUALITY ERROR (not a code error):');
+    console.error('The following file paths contain illegal C# identifier characters:');
+    for (const p of invalidPaths) {
+      console.error(`  ${p.category}: ${p.path} (invalid name: "${p.fileName}")`);
+    }
+    console.error('');
+    console.error('FIX: Re-run /business-analyse-handoff which now includes entity name canonicalization.');
+    console.error('     Or manually fix entity names in the PRD (strip accents, remove spaces/apostrophes, PascalCase).');
+    console.error('');
+    console.error('This is a PRD quality error (Category G), NOT a code generation error.');
+    console.error('Do NOT attempt to generate code from this PRD — it will fail with CS1001.');
+    STOP; // Do not proceed with invalid PRD
+  }
+}
+```
+
 **Jump to:** section 3 (MCP verify) → section 6 (determine needs) → section 9 (summary)
 
 ---
@@ -248,6 +288,23 @@ needs_notification = {module_complexity} in ["crud-workflow","complex"] OR menti
 
 Read latest task directory in `.claude/output/apex/`:
 - **If state.json exists:** resume step-03 at next uncompleted layer (skip completed)
+  - **Delegate context recovery:** If `state.delegate_mode === true`:
+    1. Restore `{delegate_prd_path}` from `state.delegate_prd_path`
+    2. Restore `{app_name}`, `{module_code}`, `{sections}`, `{entities}` from state
+    3. Re-read PRD at `{delegate_prd_path}` to rebuild `{specification_loading_plan}`:
+       ```javascript
+       const prd = readJSON(state.delegate_prd_path);
+       if (prd.specificationFiles) {
+         const sf = prd.specificationFiles;
+         specification_loading_plan = {
+           layer0_domain:   [sf.entities],
+           layer1_seed:     [sf.entities, sf.permissions],
+           layer2_backend:  [sf.rules, sf.usecases],
+           layer3_frontend: [sf.screens, sf.usecases]
+         };
+       }
+       ```
+    4. Set `{delegate_mode} = true` — companion spec loading will work in remaining layers
 - **Else if 00-context.md exists:** restore step-00 state, re-derive post-step-00 from git + files
 - **Else:** full re-derive from git history + files
 

package/templates/skills/apex/steps/step-03-execute.md

@@ -46,25 +46,48 @@ Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
 BEFORE starting Layer N:
   Verify these variables are still accessible:
     {app_name}, {module_code}, {sections}, {entities}, {code_patterns}
+    IF delegate_mode: also verify {delegate_prd_path}, {specification_loading_plan}
 
   IF any variable is missing or empty:
     1. Read .claude/output/apex/{task_id}/state.json (if exists)
-    2. IF state.json missing → re-derive from filesystem:
+    2. IF state.json has delegate context:
+       - {delegate_prd_path} = state.delegate_prd_path
+       - {delegate_mode} = state.delegate_mode
+       - Re-read PRD at {delegate_prd_path} to rebuild specification_loading_plan:
+         const prd = readJSON(delegate_prd_path);
+         if (prd.specificationFiles) {
+           specification_loading_plan = {
+             layer0_domain:   [prd.specificationFiles.entities],
+             layer1_seed:     [prd.specificationFiles.entities, prd.specificationFiles.permissions],
+             layer2_backend:  [prd.specificationFiles.rules, prd.specificationFiles.usecases],
+             layer3_frontend: [prd.specificationFiles.screens, prd.specificationFiles.usecases]
+           };
+         }
+       - {app_name} = state.app_name || prd.project?.application || prd.metadata?.applicationCode
+       - {module_code} = state.module_code || prd.project?.module || prd.metadata?.moduleCode
+    3. IF state.json missing OR no delegate context → re-derive from filesystem:
        - {app_name}: Glob("docs/business/*/") → first directory name
        - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
        - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
        - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse
        - {code_patterns}: Read state.json or re-derive from DependencyInjection.cs
-    3. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
-    4. IF Layer N-1 already completed: skip to Layer N directly
+    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+    5. IF Layer N-1 already completed: skip to Layer N directly
 
-  Cost: ~5 tool calls. Only triggered if context was compressed.
+  Cost: ~5-8 tool calls. Only triggered if context was compressed.
 ```
 
 ---
 
 ## Layer Dispatch
 
+> **CRITICAL RULES — LAYER EXECUTION GUARANTEE**
+>
+> - **NEVER** stop between layers. NEVER ask the user. NEVER present numbered options between layers.
+> - The pipeline is sequential and mandatory: **0 → 1 → 2 → 3 → 4 → step-04**, with **ZERO pauses**.
+> - After each sub-step completes, IMMEDIATELY load the next one. No summary, no confirmation request.
+> - Stopping between layers is a **VIOLATION** of the execution guarantee defined in SKILL.md.
+
 Load each sub-step sequentially:
 
 | Layer | Sub-step | Content |
@@ -119,6 +142,7 @@ Layer 4: feat({module}): [devdata] test data for development  # if applicable
 ## State Auto-Save (after each layer)
 
 > **Automatic** — not dependent on `-s` flag. Enables reliable resume after context loss.
+> **CRITICAL (audit ba-003):** Delegate context MUST be persisted for resume to work in delegate mode.
 
 After each layer's build gate passes, write state to `.claude/output/apex/{task_id}/state.json`:
 
@@ -130,10 +154,21 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
   "files_created": ["Employee.cs", "EmployeeConfiguration.cs", "..."],
   "build_gates": { "layer0": "pass", "layer1": "pass", "layer2": "pass" },
   "commits": ["abc1234", "def5678", "ghi9012"],
-  "timestamp": "2026-03-06T14:30:00Z"
+  "timestamp": "2026-03-06T14:30:00Z",
+  "delegate_mode": true,
+  "delegate_prd_path": ".ralph/prd-employees.json",
+  "app_name": "HumanResources",
+  "module_code": "employee-management",
+  "sections": ["employees", "departments"],
+  "entities": ["Employee", "Department"]
 }
 ```
 
+> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`**
+> are persisted so that Context Recovery Protocol (above) can restore the full execution context
+> after context compression or resume (`-r`). The `specification_loading_plan` is rebuilt from the
+> PRD file at `delegate_prd_path` — no need to serialize it directly.
+
 ---
 
 ## Save Output (if save_mode)

package/templates/skills/apex/steps/step-03a-layer0-domain.md

@@ -136,6 +136,9 @@ feat({module}): [domain+infra] {short description}
 
 ---
 
-## NEXT SUB-STEP
+## NEXT SUB-STEP (MANDATORY — IMMEDIATE)
+
+> **DO NOT STOP.** DO NOT ask the user. DO NOT present options. IMMEDIATELY load the next sub-step.
+> Stopping here is a VIOLATION of the execution guarantee.
 
 Load `steps/step-03b-layer1-seed.md`

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -42,6 +42,24 @@ TaskUpdate(taskId: progress_tracker_id,
 
 > This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
 
+> **CONTEXT COMPRESSION SAFEGUARD (delegate mode):**
+> In delegate mode (`-d`), `references/core-seed-data.md` may have been evicted from context by compression
+> before Layer 1 begins (it was loaded at step-03 entry but is ~1464 lines).
+>
+> **CHECK:** Can you see Section 6 "IClientSeedDataProvider Implementation" from `core-seed-data.md` in your context?
+> - **YES** → Proceed normally using the templates from that section.
+> - **NO** → **Re-read** `references/core-seed-data.md` lines 1004-1296 NOW (the IClientSeedDataProvider template).
+>   This section contains the complete C# template for the provider class with all 4 Seed methods.
+>
+> **WARNING — ANTI-STUB RULE:**
+> The SeedDataProvider MUST contain real implementation code. Each of the 4 methods
+> (`SeedNavigationAsync`, `SeedRolesAsync`, `SeedPermissionsAsync`, `SeedRolePermissionsAsync`)
+> MUST have actual entity creation logic with `context.{DbSet}.Add()` calls.
+>
+> **BLOCKING:** If ANY Seed method body is just `return Task.CompletedTask;` or `{ }` (empty),
+> the seed data layer is INVALID. The module will be invisible in the UI (menu vide / empty menu).
+> Re-read the template from `references/core-seed-data.md` Section 6 and generate proper implementation.
+
 ---
 
 ### Mode Detection: CREATE vs UPDATE
@@ -254,6 +272,9 @@ feat({module}): [seed] navigation, permissions, roles
 
 ---
 
-## NEXT SUB-STEP
+## NEXT SUB-STEP (MANDATORY — IMMEDIATE)
+
+> **DO NOT STOP.** DO NOT ask the user. DO NOT present options. IMMEDIATELY load the next sub-step.
+> Stopping here is a VIOLATION of the execution guarantee.
 
 Load `steps/step-03c-layer2-backend.md`

package/templates/skills/apex/steps/step-03c-layer2-backend.md

@@ -348,6 +348,9 @@ test({module}): backend unit and integration tests
 
 ---
 
-## NEXT SUB-STEP
+## NEXT SUB-STEP (MANDATORY — IMMEDIATE)
+
+> **DO NOT STOP.** DO NOT ask the user. DO NOT present options. IMMEDIATELY load the next sub-step.
+> Stopping here is a VIOLATION of the execution guarantee.
 
 Load `steps/step-03d-layer3-frontend.md`

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -169,6 +169,9 @@ For each module:
     3. Add the new namespace import + registration for all 4 languages
     4. If config uses dynamic imports: add namespace to the `ns` array
     5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
+    6. **I18n File/Import Alignment Check:** Verify that every locale JSON file on disk for this module
+       has a corresponding import in the i18n config index.ts. Glob `src/**/i18n/locales/*/` for module files,
+       then verify each is imported. Missing imports cause silent translation failures (keys show as raw strings).
 - Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
   then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
 - Section routes: Ensure navigation seed data has ComponentKey matching PageRegistry keys.
@@ -329,6 +332,9 @@ test({module}): frontend form tests
 
 ---
 
-## NEXT SUB-STEP
+## NEXT SUB-STEP (MANDATORY — IMMEDIATE)
+
+> **DO NOT STOP.** DO NOT ask the user. DO NOT present options. IMMEDIATELY load the next sub-step.
+> Stopping here is a VIOLATION of the execution guarantee.
 
 Load `steps/step-03e-layer4-devdata.md`

package/templates/skills/apex/steps/step-04-examine.md

@@ -131,6 +131,41 @@ IF ANY cell = NO → BLOCKING — return to step-03b to fix
 
 Execute all checks from `references/post-checks.md`. If any fails, fix in step-03 and re-validate.
 
+### 6c. SeedDataProvider Content Verification (BLOCKING)
+
+> **LESSON LEARNED (audit ba-003):** SeedDataProvider existed and had 4 methods (passed C23),
+> but all methods were `return Task.CompletedTask` — stubs generated when `core-seed-data.md`
+> was evicted from context by compression. Result: empty menu, 0 applications visible.
+
+```javascript
+// Find the SeedDataProvider file
+const providerFiles = Glob("**/Seeding/*SeedDataProvider.cs");
+for (const providerFile of providerFiles) {
+  const content = readFile(providerFile);
+
+  // Check 1: No stub methods — each Seed*Async must have real implementation
+  const methods = ['SeedNavigationAsync', 'SeedRolesAsync', 'SeedPermissionsAsync', 'SeedRolePermissionsAsync'];
+  for (const method of methods) {
+    const methodRegex = new RegExp(`${method}[^{]*\\{([^}]*)\\}`, 's');
+    const match = content.match(methodRegex);
+    if (match) {
+      const body = match[1].trim();
+      if (body === 'return Task.CompletedTask;' || body === '' || body === 'return;') {
+        BLOCKING_ERROR(`${providerFile}: ${method} is a STUB (${body || 'empty body'}). ` +
+          `Re-read references/core-seed-data.md Section 6 and generate real implementation. ` +
+          `Stub seed methods cause EMPTY MENU — 0 applications visible in UI.`);
+      }
+    }
+  }
+
+  // Check 2: Must contain actual entity creation calls
+  if (!content.includes('.Add(') && !content.includes('.AddRange(')) {
+    BLOCKING_ERROR(`${providerFile}: No .Add() or .AddRange() calls found. ` +
+      `SeedDataProvider must actually insert seed data, not just return.`);
+  }
+}
+```
+
 ---
 
 ## 7. Acceptance Criteria POST-CHECK

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

@@ -65,6 +65,60 @@ if (resumeValid) {
 }
 ```
 
+### 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

package/templates/skills/business-analyse-develop/steps/step-00-init.md

@@ -76,10 +76,11 @@ If tests are slow (>30s in logs), display warning but **continue execution**:
 
 ## 4. Resume or Initialize
 
-See `references/init-resume-recovery.md` for complete Resume Mode and Auto-Recovery logic.
+See `references/init-resume-recovery.md` for complete Resume Mode, Auto-Recovery, and Ralph State Recovery logic.
 
 **Quick:**
-- If `-r` flag: restore state from .ralph/prd.json
+- If `-r` flag: restore state from .ralph/prd.json + .ralph/ralph-state.json
+- Else if `.ralph/ralph-state.json` exists: recover position (step, module, iteration) — see init-resume-recovery.md "Ralph State Recovery"
 - Else if BA artifacts exist: auto-recover PRDs via `ss business-analyse-handoff`
 - Else: fresh start
 
@@ -222,14 +223,20 @@ MCP: Ready | Branch: {branch} | PRD: v{prd_version}
 
 ### 7b. Initialize State File (context compression defense)
 
+> **ralph-state.json is written here AND updated by step-02, compact-loop, and module-transition.**
+> On resume or after context compression, `init-resume-recovery.md` reads it back to route
+> to the correct step instead of always restarting from step-01.
+
 ```javascript
 writeJSON('.ralph/ralph-state.json', {
   currentStep: 'step-01-task',
   currentModule: {current_module},
   iteration: 1,
   prdVersion: {prd_version},
+  modulesQueuePath: fileExists('.ralph/modules-queue.json') ? '.ralph/modules-queue.json' : null,
   timestamp: new Date().toISOString()
 });
 ```
 
-**Proceed directly to step-01-task.md**
+**Step routing:** If ralph-state recovery (section 4) provided a different target step, load THAT step.
+Otherwise, proceed to step-01-task.md.

package/templates/skills/business-analyse-develop/steps/step-01-task.md

@@ -6,8 +6,20 @@ next_step: steps/step-02-execute.md
 
 # Step 1: Load Task
 
-> **STATE RECOVERY:** If you are unsure which step you are executing (e.g., after context compression),
-> read `.ralph/ralph-state.json` to recover your position.
+> **STATE RECOVERY (executable):** If context was compressed and you are unsure of your position:
+```javascript
+if (fileExists('.ralph/ralph-state.json')) {
+  const state = readJSON('.ralph/ralph-state.json');
+  if (state.currentStep && state.currentStep !== 'step-01-task') {
+    console.warn(`RECOVERY: ralph-state.json says currentStep="${state.currentStep}" but we are in step-01.`);
+    console.warn(`This may indicate context compression routed to the wrong step.`);
+    console.warn(`Current module: ${state.currentModule}, iteration: ${state.iteration}`);
+  }
+  // Restore module context
+  if (state.currentModule) { {current_module} = state.currentModule; }
+  if (state.iteration) { {current_iteration} = state.iteration; }
+}
+```
 
 > **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
 

package/templates/skills/business-analyse-develop/steps/step-04-check.md

@@ -6,8 +6,18 @@ next_step: steps/step-05-report.md OR steps/step-01-task.md
 
 # Step 4: Check Completion
 
-> **STATE RECOVERY:** If you are unsure which step you are executing (e.g., after context compression),
-> read `.ralph/ralph-state.json` to recover your position.
+> **STATE RECOVERY (executable):** If context was compressed:
+```javascript
+if (fileExists('.ralph/ralph-state.json')) {
+  const state = readJSON('.ralph/ralph-state.json');
+  if (state.currentStep && state.currentStep !== 'step-04-check' && state.currentStep !== 'compact-loop') {
+    console.warn(`RECOVERY: ralph-state.json says currentStep="${state.currentStep}" but we are in step-04.`);
+  }
+  // Restore module context if lost
+  if (state.currentModule) { {current_module} = state.currentModule; }
+  if (state.iteration) { {current_iteration} = state.iteration; }
+}
+```
 
 ## YOUR TASK: