@atlashub/smartstack-cli 4.47.0 → 4.49.0

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

@@ -9,6 +9,38 @@ parent_step: steps/step-03-execute.md
 
 # Layer 3 — Frontend (Pages + I18n + Documentation)
 
+### Companion Specs Loading (delegate mode)
+
+```javascript
+if (delegate_mode && specification_loading_plan) {
+  const specsDir = path.dirname(delegate_prd_path);
+  // Layer 3 loads: screens + usecases companions
+  for (const file of specification_loading_plan.layer3_frontend) {
+    const specPath = path.join(specsDir, file);
+    if (fileExists(specPath)) {
+      const specData = readJSON(specPath);
+      if (specData.screens) {
+        // Full screen definitions: columns[], fields[], filters[], actions[], kpis[]
+        // Use for: DataTable columns, form fields, filter configs, action buttons, dashboard KPIs
+        console.log(`Loaded screens: ${specData.screens.length} screen specs with columns/fields/filters`);
+      }
+      if (specData.useCases || specData.usecases) {
+        const ucs = specData.useCases || specData.usecases;
+        // UC steps inform form validation, navigation flows, error states
+        console.log(`Loaded usecases: ${ucs.length} use cases for form flows`);
+      }
+    }
+  }
+}
+```
+
+> When companion specs are loaded:
+> - **List pages**: use `screen.columns[]` for exact DataTable column definitions (key, label, type, sortable)
+> - **Form pages**: use `screen.fields[]` for exact form field definitions (name, type, required, validation)
+> - **Filter configs**: use `screen.filters[]` for search/filter UI generation
+> - **Dashboard pages**: use `screen.kpis[]` for KPI card and chart definitions
+> - **Actions**: use `screen.actions[]` for action buttons (create, export, bulk operations)
+
 ### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)
 
 > **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT

package/templates/skills/application/references/backend-controller-hierarchy.md

@@ -38,14 +38,24 @@ Api/Controllers/
 The generated controller uses NavRoute attribute:
 
 ```csharp
-[NavRoute("{full_path}")]
 [ApiController]
-[Authorize]
+[NavRoute("{full_path}")]
+[Microsoft.AspNetCore.Authorization.Authorize]
+[Produces("application/json")]
+[Tags("{EntityNamePlural}")]
 public class {EntityName}Controller : ControllerBase
 {
+    private readonly ISender _mediator;
+
+    public {EntityName}Controller(ISender mediator) => _mediator = mediator;
+
     [HttpGet]
-    [RequirePermission(Permissions.{Application}.{Module}.Read)]
-    public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }
+    [RequirePermission(Permissions.{Application}.{Module}.View)]
+    [ProducesResponseType(typeof(List<{EntityName}ListDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<List<{EntityName}ListDto>>> GetAll(CancellationToken ct)
+        => Ok(await _mediator.Send(new Get{EntityNamePlural}Query(), ct));
 
     // ... other CRUD methods
 }

package/templates/skills/business-analyse-design/steps/step-02-wireframes.md

@@ -127,6 +127,20 @@ For each module, update screens.json to embed wireframes at the resource level:
 
 Write via ba-writer for each module. Update index.json hashes.
 
+## Consumer Contract (wireframe field names)
+
+> **IMPORTANT:** Downstream consumers (`/business-analyse-html`) depend on these EXACT field names.
+> Any rename requires updating `business-analyse-html/steps/step-02-build-data.md` (wireframe mapping).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mockupFormat` | `"ascii"` \| `"html"` | Wireframe rendering format |
+| `mockup` | string | Wireframe content (ASCII art or HTML) |
+| `elements` | string[] | UI element names |
+| `componentMapping` | object[] | Wireframe element → React component mapping |
+| `layout` | object | Layout type and regions |
+| `permissionsRequired` | string[] | Permission paths needed |
+
 ## Validation
 
 - [ ] Every resource has a wireframe object

package/templates/skills/business-analyse-develop/references/compact-loop.md

@@ -22,7 +22,7 @@ const queuePath = '.ralph/modules-queue.json';
 let currentPrdPath = '.ralph/prd.json';
 if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
-  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
 }
 ```
 
@@ -226,6 +226,20 @@ for (const task of batch) {
 writeJSON(currentPrdPath, prd);
 ```
 
+### B1b. State Persistence (before delegation)
+
+```javascript
+// Write state BEFORE delegating to apex so position survives context compression
+writeJSON('.ralph/ralph-state.json', {
+  currentStep: 'compact-loop',
+  nextStep: 'step-04-check',
+  currentModule: {current_module},
+  phase: 'apex-delegating',
+  iteration: prdCheck?.config?.current_iteration || 'unknown',
+  timestamp: new Date().toISOString()
+});
+```
+
 ### B2. Invoke /apex
 
 **INVOKE `/apex -d {currentPrdPath}`**

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

@@ -122,11 +122,21 @@ if (missing.length === 0) {
     // 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)

package/templates/skills/business-analyse-develop/references/quality-gates.md

@@ -14,8 +14,9 @@
 | MCP code review | `review_code` | YES (if perm mismatch) | After security |
 | MCP conventions | `validate_conventions` | NO (report) | After code review |
 | MCP test conventions | `validate_test_conventions` | NO (report) | After conventions |
-| BR coverage | grep implementation | YES (100%) | After MCP gates |
+| BR coverage | grep implementation (enriched) | YES (100%) | After MCP gates |
 | File reconciliation | compare expectedFiles vs disk | YES | After BR coverage |
+| Spec fidelity | compare specs vs code | NO (report) | After file reconciliation |
 | Stub test detection | grep stub patterns | YES | During test gate |
 
 ## Stub Test Patterns (AUTO-REJECT)
@@ -66,5 +67,94 @@ BR coverage check
     ↓ (100%)
 File reconciliation
     ↓ (all present)
+Spec fidelity (non-blocking report)
+    ↓ (report)
 MODULE COMPLETE
 ```
+
+## BR Coverage — Enriched Verification
+
+When `prd.specificationFiles` is present and companion files are available, the BR coverage gate uses the enriched `brToCodeMapping` (with `statement`, `formula`, `example`) for verification.
+
+**Standard check:** grep each `brToCodeMapping[].ruleId` in the codebase to confirm implementation.
+
+**Enriched fix context:** When a BR is NOT covered, provide full context for the fix:
+
+```
+MISSING BR IMPLEMENTATION:
+  Rule: {ruleId}
+  Statement: {statement}
+  Example: {example}
+  Formula: {formula}
+  Entities: {entities[]}
+  Category: {category}
+  Severity: {severity}
+  Expected in: {implementationPoints[].component} ({implementationPoints[].layer})
+```
+
+This gives `/apex` or the developer the complete context to implement the missing BR without re-reading the BA artifacts.
+
+## Gate: Specification Fidelity (non-blocking report)
+
+> **When:** After file reconciliation. **Blocking:** NO (report only).
+> **Requires:** `prd.specificationFiles` present with companion files.
+
+Compares generated code against companion specification files to measure implementation fidelity.
+
+**Checks:**
+
+```javascript
+if (prd.specificationFiles) {
+  const specsDir = '.ralph';
+  const entitiesSpec = readJSON(`${specsDir}/${prd.specificationFiles.entities}`);
+  const rulesSpec = readJSON(`${specsDir}/${prd.specificationFiles.rules}`);
+  let totalChecks = 0, passedChecks = 0;
+
+  // 1. Entity property coverage
+  for (const entity of (entitiesSpec.entities || [])) {
+    const entityFile = findFile(`src/**/Domain/**/${entity.name}.cs`);
+    if (entityFile) {
+      const content = readFile(entityFile);
+      for (const attr of (entity.attributes || [])) {
+        totalChecks++;
+        if (content.includes(attr.name)) passedChecks++;
+        else console.warn(`SPEC DRIFT: ${entity.name}.${attr.name} not found in ${entityFile}`);
+      }
+    }
+  }
+
+  // 2. Validator coverage for BR-VAL-*
+  for (const rule of (rulesSpec.rules || [])) {
+    if (rule.id?.startsWith('BR-VAL-')) {
+      totalChecks++;
+      const validatorFiles = findFiles(`src/**/Validators/**/*Validator.cs`);
+      const found = validatorFiles.some(f => readFile(f).includes(rule.id));
+      if (found) passedChecks++;
+      else console.warn(`SPEC DRIFT: ${rule.id} (${rule.statement?.slice(0, 50)}...) has no Validator implementation`);
+    }
+  }
+
+  // 3. Calculation coverage for BR-CALC-*
+  for (const rule of (rulesSpec.rules || [])) {
+    if (rule.id?.startsWith('BR-CALC-') && rule.formula) {
+      totalChecks++;
+      const serviceFiles = findFiles(`src/**/Services/**/*Service.cs`);
+      const found = serviceFiles.some(f => readFile(f).includes(rule.id));
+      if (found) passedChecks++;
+      else console.warn(`SPEC DRIFT: ${rule.id} formula "${rule.formula}" has no Service implementation`);
+    }
+  }
+
+  const fidelityScore = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 100;
+  console.log(`SPEC FIDELITY: ${fidelityScore}% (${passedChecks}/${totalChecks} checks passed)`);
+}
+```
+
+**Output:**
+```
+SPEC FIDELITY: 92% (23/25 checks passed)
+  DRIFT: Employee.TerminationDate not found in Employee.cs
+  DRIFT: BR-CALC-002 formula "netSalary = grossSalary - deductions" has no Service implementation
+```
+
+This gate does NOT block — it provides visibility into specification coverage gaps.

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

@@ -91,6 +91,51 @@ See `references/multi-module-queue.md` for queue initialization.
 
 Quick: `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json
 
+### 4b+. Normalize modules-queue.json (backward-compat with handoff v1 format)
+
+```javascript
+const queuePath = '.ralph/modules-queue.json';
+if (fileExists(queuePath)) {
+  const raw = readJSON(queuePath);
+  let dirty = false;
+
+  // RC1: Rename "queue" → "modules" property (handoff v1 used "queue")
+  if (raw.queue && !raw.modules) {
+    raw.modules = raw.queue;
+    delete raw.queue;
+    dirty = true;
+  }
+
+  // RC2: Rename "moduleCode" → "code" in each entry (handoff v1 used "moduleCode")
+  for (const mod of (raw.modules || [])) {
+    if (mod.moduleCode && !mod.code) {
+      mod.code = mod.moduleCode;
+      delete mod.moduleCode;
+      dirty = true;
+    }
+  }
+
+  // RC3: Add missing fields
+  if (raw.currentIndex === undefined) { raw.currentIndex = 0; dirty = true; }
+  if (raw.completedModules === undefined) { raw.completedModules = 0; dirty = true; }
+  if (raw.totalModules === undefined) { raw.totalModules = raw.modules?.length || 0; dirty = true; }
+  for (const mod of (raw.modules || [])) {
+    if (!mod.prdFile) { mod.prdFile = `.ralph/prd-${mod.code}.json`; dirty = true; }
+    if (!mod.status) { mod.status = 'pending'; dirty = true; }
+  }
+  // Set first module to in-progress if none started
+  if (raw.modules?.length && !raw.modules.some(m => m.status !== 'pending')) {
+    raw.modules[0].status = 'in-progress';
+    dirty = true;
+  }
+
+  if (dirty) {
+    writeJSON(queuePath, raw);
+    console.log('modules-queue.json normalized (format v2)');
+  }
+}
+```
+
 ---
 
 ## 4c. Team Orchestration (multi-module LEGACY — dependency layer mode only)
@@ -175,4 +220,16 @@ MCP: Ready | Branch: {branch} | PRD: v{prd_version}
 -> Loading spec...
 ```
 
+### 7b. Initialize State File (context compression defense)
+
+```javascript
+writeJSON('.ralph/ralph-state.json', {
+  currentStep: 'step-01-task',
+  currentModule: {current_module},
+  iteration: 1,
+  prdVersion: {prd_version},
+  timestamp: new Date().toISOString()
+});
+```
+
 **Proceed directly to step-01-task.md**

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

@@ -6,6 +6,9 @@ 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.
+
 > **MODULE TRANSITION CHECK:** Before "Only Read Once" rule, check for module transition:
 
 ```javascript
@@ -52,7 +55,7 @@ const queuePath = '.ralph/modules-queue.json';
 let currentPrdPath = '.ralph/prd.json';
 if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
-  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
 }
 ```
 
@@ -63,6 +66,149 @@ If `{currentPrdPath}` exists:
    - Write back to `{currentPrdPath}`
    - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
    - Skip directly to section 5 (find next task)
+2b. **v3 filesToCreate PATH:** If `$version === "3.0.0"` AND `implementation.filesToCreate` exists AND NO `tasks[]`:
+   → Transform filesToCreate into tasks[]:
+
+   ```javascript
+   const ftc = prd.implementation.filesToCreate;
+   const tasks = [];
+   let taskId = 1;
+
+   // CATEGORY ORDER: domain → infrastructure → application → api → seedData → frontend → test → documentation
+   const categoryOrder = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'tests', 'documentation'];
+
+   // Load companion specs if available (for rich acceptance criteria)
+   const specFiles = prd.specificationFiles || {};
+   const specsDir = '.ralph';
+   let specEntities = null, specRules = null, specUsecases = null, specScreens = null, specPermissions = null;
+   try {
+     if (specFiles.entities) specEntities = readJSON(`${specsDir}/${specFiles.entities}`);
+     if (specFiles.rules) specRules = readJSON(`${specsDir}/${specFiles.rules}`);
+     if (specFiles.usecases) specUsecases = readJSON(`${specsDir}/${specFiles.usecases}`);
+     if (specFiles.screens) specScreens = readJSON(`${specsDir}/${specFiles.screens}`);
+     if (specFiles.permissions) specPermissions = readJSON(`${specsDir}/${specFiles.permissions}`);
+   } catch (e) { /* companion files absent — fallback to generic AC */ }
+
+   function deriveAcceptanceCriteria(file, category, prd) {
+     const fileName = (file.path || file).split('/').pop().replace(/\.\w+$/, '');
+
+     // If no companion specs available, fallback to generic AC
+     if (!specEntities && !specRules) {
+       return `File ${file.path || file} exists and compiles`;
+     }
+
+     switch (category) {
+       case 'domain': {
+         const entityName = fileName;
+         const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+         if (entity && entity.attributes) {
+           const attrs = entity.attributes.map(a => `${a.name}:${a.type}`).join(', ');
+           const rels = (entity.relationships || []).map(r => `${r.type} ${r.target}`).join(', ');
+           return `Entity ${entityName} with attributes [${attrs}]${rels ? '. Relations: [' + rels + ']' : ''}`;
+         }
+         break;
+       }
+       case 'application': {
+         const linkedBRs = (prd.brToCodeMapping || [])
+           .filter(br => br.implementationPoints?.some(ip => ip.component?.includes(fileName)))
+           .map(br => `${br.ruleId}: ${br.statement || br.title}`);
+         const linkedUCs = (file.linkedUCs || []).join(', ');
+         if (linkedBRs.length > 0 || linkedUCs) {
+           const parts = [];
+           if (linkedBRs.length > 0) parts.push(`Implements BRs: [${linkedBRs.join('; ')}]`);
+           if (linkedUCs) parts.push(`Handles UCs: [${linkedUCs}]`);
+           return parts.join('. ');
+         }
+         break;
+       }
+       case 'infrastructure': {
+         const entityName = fileName.replace('Configuration', '');
+         const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+         if (entity && entity.attributes) {
+           const props = entity.attributes.map(a => a.name).join(', ');
+           return `EF Config for ${entityName}. Attributes: [${props}]`;
+         }
+         break;
+       }
+       case 'api': {
+         const entityName = fileName.replace('Controller', '');
+         const endpoints = (prd.apiEndpointSummary || [])
+           .filter(ep => ep.operation?.includes(entityName))
+           .map(ep => `${ep.method} ${ep.route}`);
+         const perms = (specPermissions?.permissionPaths || [])
+           .filter(p => p.toLowerCase().includes(entityName.toLowerCase()))
+           .slice(0, 5);
+         const parts = [`Controller ${entityName}`];
+         if (endpoints.length > 0) parts.push(`Endpoints: [${endpoints.join(', ')}]`);
+         if (perms.length > 0) parts.push(`Permissions: [${perms.join(', ')}]`);
+         return parts.join('. ');
+       }
+       case 'frontend': {
+         const screen = (specScreens?.screens || []).find(s =>
+           fileName.toLowerCase().includes(s.code?.toLowerCase() || s.name?.toLowerCase() || '')
+         );
+         if (screen) {
+           const parts = [file.type || 'Page'];
+           if (screen.columns) parts.push(`columns [${screen.columns.map(c => c.key || c.name || c).join(', ')}]`);
+           if (screen.filters) parts.push(`filters [${screen.filters.map(f => f.key || f.name || f).join(', ')}]`);
+           if (screen.actions) parts.push(`actions [${screen.actions.map(a => a.key || a.name || a).join(', ')}]`);
+           if (screen.kpis) parts.push(`KPIs [${screen.kpis.map(k => k.label || k.name || k).join(', ')}]`);
+           return `${parts.join(' with ')}`;
+         }
+         break;
+       }
+       case 'seedData': {
+         if (file.category === 'business') {
+           const entityName = fileName.replace('SeedData', '');
+           const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+           if (entity?.seedValues) {
+             const names = entity.seedValues.map(v => v.name || v.label || v.code).filter(Boolean).slice(0, 5);
+             return `Seeds ${entityName} with ${entity.seedValues.length} values: [${names.join(', ')}]`;
+           }
+         }
+         break;
+       }
+       case 'test': case 'tests': {
+         const linkedBRs = (prd.brToCodeMapping || [])
+           .filter(br => br.implementationPoints?.some(ip =>
+             ip.layer === 'Domain' || ip.layer === 'Application'
+           ))
+           .map(br => br.ruleId);
+         const linkedUCs = (file.linkedUCs || []);
+         const parts = [];
+         if (linkedBRs.length > 0) parts.push(`Covers BRs: [${linkedBRs.join(', ')}]`);
+         if (linkedUCs.length > 0) parts.push(`Covers UCs: [${linkedUCs.join(', ')}]`);
+         if (parts.length > 0) return parts.join('. ');
+         break;
+       }
+     }
+     // Fallback: generic AC
+     return `File ${file.path || file} exists and compiles`;
+   }
+
+   for (const category of categoryOrder) {
+     const files = ftc[category] || [];
+     for (const file of files) {
+       tasks.push({
+         id: `T${String(taskId++).padStart(3, '0')}`,
+         description: `Create ${file.type || category}: ${(file.path || file).split('/').pop()}`,
+         status: 'pending',
+         category: category === 'tests' ? 'test' : category,  // normalize
+         dependencies: [],  // implicit ordering via category
+         acceptance_criteria: deriveAcceptanceCriteria(file, category === 'tests' ? 'test' : category, prd),
+         path: file.path || file,
+         started_at: null, completed_at: null, iteration: null,
+         commit_hash: null, files_changed: [], validation: null, error: null
+       });
+     }
+   }
+
+   prd.tasks = tasks;
+   prd.config = { current_iteration: 1, max_iterations: 50 };
+   writeJSON(currentPrdPath, prd);
+   ```
+   → Run CATEGORY COMPLETENESS CHECK (section 4b) — will detect if seedData is missing
+   → Skip to section 5 (find next task)
 3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5)
 4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
 
@@ -117,7 +263,10 @@ Check for BA handoff source (priority):
 3. Markdown handoff: `find . -path "*development-handoff*" -name "*.md"`
 4. Direct task from `{task_description}`
 
-Generate **3-30 subtasks** by category (domain → infrastructure → application → api → frontend → i18n → test → validation).
+Generate **3-30 subtasks** by category (domain → infrastructure → application → api → seedData → frontend → i18n → test → validation).
+
+**seedData category is MANDATORY** — generates navigation entries, permissions, roles, and the IClientSeedDataProvider.
+Without seedData tasks, modules are invisible in the UI (no menu, no permissions, no RBAC).
 
 ## 3. Create prd.json
 

package/templates/skills/business-analyse-develop/steps/step-02-execute.md

@@ -35,7 +35,7 @@ const queuePath = '.ralph/modules-queue.json';
 let currentPrdPath = '.ralph/prd.json';
 if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
-  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
 }
 
 const prd = readJSON(currentPrdPath);
@@ -75,6 +75,19 @@ See `references/parallel-execution.md` for complete parallel protocol:
 
 Continue with section-split mode or standard mode below.
 
+#### 3a+. State Persistence (before delegation)
+
+```javascript
+// Write state BEFORE delegating to apex so position survives context compression
+writeJSON('.ralph/ralph-state.json', {
+  currentStep: 'step-02-execute',
+  nextStep: 'step-03-commit',
+  currentModule: {current_module},
+  phase: 'apex-delegating',
+  timestamp: new Date().toISOString()
+});
+```
+
 #### 3b. Section-Split Mode
 
 ```javascript

package/templates/skills/business-analyse-develop/steps/step-02-v4-verify.md

@@ -12,6 +12,19 @@ After ALL modules are implemented, run final verification across the ENTIRE proj
 
 ---
 
+## VERSION GUARD
+
+```javascript
+// This step is ONLY for v4 PRDs. If a v3 PRD reaches here, route back to step-05-report.md.
+const prd = readJSON(currentPrdPath);
+if (prd.$version !== '4.0.0') {
+  console.error(`step-02-v4-verify loaded with $version=${prd.$version} — expected 4.0.0`);
+  console.log('Routing to step-05-report.md (v3 report generation)');
+  // → Load steps/step-05-report.md instead
+  return;
+}
+```
+
 ## FINAL VERIFICATION SEQUENCE
 
 ### 1. Full Solution Build
@@ -39,11 +52,18 @@ npm test -- --run 2>&1
 
 ### 4. File Reconciliation
 
-For each module's PRD, compare `expectedFiles` against actual files on disk:
+For each module's PRD, compare expected files against actual files on disk:
 
 ```javascript
+// v4 uses prd.expectedFiles, v3 uses prd.implementation.filesToCreate (guard: should be v4 here)
+const fileManifest = prd.expectedFiles || prd.implementation?.filesToCreate;
+if (!fileManifest) {
+  console.error('BLOCKING: PRD has no file manifest (neither expectedFiles nor implementation.filesToCreate)');
+  STOP;
+}
+
 for (const category of ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation']) {
-  const expected = prd.expectedFiles[category] || [];
+  const expected = fileManifest[category] || [];
   for (const file of expected) {
     if (!existsOnDisk(file.path)) {
       MISSING.push({ category, path: file.path, type: file.type });

package/templates/skills/business-analyse-develop/steps/step-03-commit.md

@@ -27,7 +27,7 @@ const queuePath = '.ralph/modules-queue.json';
 let currentPrdPath = '.ralph/prd.json';
 if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
-  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
 }
 
 const prd = readJSON(currentPrdPath);

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

@@ -6,6 +6,9 @@ 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.
+
 ## YOUR TASK:
 
 Check if all tasks are complete and decide: output completion promise, advance module, or continue loop.
@@ -20,7 +23,7 @@ const queuePath = '.ralph/modules-queue.json';
 let currentPrdPath = '.ralph/prd.json';
 if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
-  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+  currentPrdPath = queue.modules[queue.currentIndex].prdFile;
 }
 
 const prd = readJSON(currentPrdPath);