@atlashub/smartstack-cli 4.25.0 → 4.26.0

package/package.json

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

package/templates/agents/ba-writer.md

@@ -63,8 +63,11 @@ Create initial index.json and empty thematic files with metadata and draft statu
    - For application scope: modules: []
    - For module scope: (no modules array)
 5. Create empty thematic files appropriate for scope:
-   - Project/application: cadrage.json, entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json, consolidation.json
-   - Module: discovery.json, analysis.json, specification.json, validation.json, handoff.json
+   - Project/application: cadrage.json, validation.json, handoff.json, consolidation.json
+     > **NOTE:** Do NOT create entities.json, rules.json, usecases.json, permissions.json, screens.json at project/application level.
+     > These thematic files contain module-specific data and are created ONLY at module level by step-03 (specify).
+     > Creating empty versions at app level causes downstream tools (derive-prd) to read empty arrays instead of module data.
+   - Module: entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json
 6. Update `.business-analyse/config.json` with new lastFeatureId
 7. IF scope = "module" AND applicationRef provided AND moduleCode provided:
    a. Read master index.json (via applicationRef FEAT-NNN)
@@ -107,7 +110,8 @@ Create a project-level index.json for multi-application analysis. Only used when
    - fileHashes: {}
    - applications: []
    - applicationDependencyGraph: {}
-5. Create thematic files (cadrage.json, entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, consolidation.json)
+5. Create thematic files (cadrage.json, validation.json, consolidation.json)
+     > Do NOT create entities/rules/usecases/permissions/screens at project level — these exist only at module level.
 6. Update `.business-analyse/config.json` with new lastProjectId
 7. Deploy schemas to `docs/business-analyse/schemas/` (including project-schema.json)
 8. Return project ID (PROJ-NNN) and path

package/templates/skills/ba-generate-html/references/data-build.md

@@ -63,11 +63,13 @@ const FEATURE_DATA = {
   ],
   moduleSpecs: {
     // CRITICAL: Must have ONE entry per module with ALL module data
+    // FLAT-FILE: Data comes from collected_data.modules[moduleCode] (flat files), NOT module index.json
     "{moduleCode}": {
-      useCases: module.specification.useCases || [],
-      businessRules: module.analysis.businessRules || [],
+      // const mod = collected_data.modules[moduleCode];
+      useCases: mod.usecases?.useCases || [],
+      businessRules: mod.rules?.rules || [],
       // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated from canonical format
-      entities: (module.analysis.entities || []).map(ent => ({
+      entities: (mod.entities?.entities || []).map(ent => ({
         name: ent.name,
         description: ent.description || "",
         attributes: (ent.attributes || []).length > 0
@@ -79,8 +81,8 @@ const FEATURE_DATA = {
           : (ent.fields || []).filter(f => f.foreignKey)
               .map(f => `${f.foreignKey.table} (N:1) - ${f.description || f.name}`)
       })),
-      permissions: module.specification.permissionMatrix?.permissions || [],
-      apiEndpoints: module.specification.apiEndpoints || []
+      permissions: mod.permissions?.matrix || mod.permissions?.permissions || [],
+      apiEndpoints: mod.usecases?.apiEndpoints || []
     }
   },
   consolidation: {
@@ -102,10 +104,15 @@ const FEATURE_DATA = {
 ### Build Process
 
 1. Extract metadata from master index.json
-2. Extract cadrage from master index.json (CONVERT scope keys)
-3. Extract stakeholders from master.stakeholders
+2. Extract cadrage from master cadrage.json (CONVERT scope keys)
+3. Extract stakeholders from master cadrage.stakeholders
 4. Iterate ALL modules and populate moduleSpecs (THIS IS CRITICAL — empty moduleSpecs = BUG)
-5. For EACH module, extract: useCases, businessRules, entities, permissions, apiEndpoints
+5. For EACH module, read FLAT FILES from `collected_data.modules[moduleCode]`:
+   - `entities.json` → entities
+   - `rules.json` → businessRules
+   - `usecases.json` → useCases
+   - `permissions.json` → permissions
+   - `screens.json` → wireframes
 6. Extract consolidation data (integrations, shared entities, E2E flows)
 7. Extract handoff section (complexity, strategy, module order, file counts)
 
@@ -119,10 +126,12 @@ const FEATURE_DATA = {
 const EMBEDDED_ARTIFACTS = {
   wireframes: {
     // PER-MODULE keyed object (NOT a flat array)
-    // FOR EACH module: extract from specification.uiWireframes[] OR specification.wireframes[] (SAFETY NET)
-    // IMPORTANT: The agent may write wireframes under either key name — always check BOTH
-    // Read from module JSON files
-    [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
+    // FLAT-FILE: Read from screens.json in each module directory (collected in step-01)
+    // const mod = collected_data.modules[moduleCode];
+    // const screens = mod.screens?.screens || [];
+    [moduleCode]: screens
+      .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+      .map(wf => ({
       screen: wf.screen || wf.name || wf.title || wf.id || "",  // SAFETY NET: fallback name/title/id → screen
       section: wf.section || "",                      // e.g. "list"
       format: wf.mockupFormat || "ascii",             // RENAME: mockupFormat → format
@@ -160,7 +169,7 @@ const EMBEDDED_ARTIFACTS = {
 
 ### Artifact Gathering
 
-1. For EACH module: read `specification.uiWireframes[]` OR `specification.wireframes[]` (check BOTH keys — agent may use either), **rename fields** (`mockupFormat`→`format`, `mockup`/`ascii`/`content`→`content`, `screen`/`name`/`title`→`screen`), store under `wireframes[moduleCode]`
+1. For EACH module: read `screens.json` flat file from `collected_data.modules[moduleCode].screens`, filter screens with wireframe data, **rename fields** (`mockupFormat`→`format`, `mockup`/`ascii`/`content`→`content`, `screen`/`name`/`title`→`screen`), store under `wireframes[moduleCode]`
 2. Read master's `consolidation.e2eFlows[]` and build e2eFlows array with diagram generation
 3. Read master's `dependencyGraph` and build nodes/edges
 4. Serialize as JSON with 2-space indentation

package/templates/skills/ba-generate-html/references/data-mapping.md

@@ -93,29 +93,32 @@ Build a JSON object following this **exact mapping** from index.json to the HTML
 }
 ```
 
-### Module Specs Mapping
+### Module Specs Mapping (FLAT-FILE ARCHITECTURE)
 
 For EACH module in `master.modules[]`:
 
-1. Read the module index.json at `master.modules[i].featureJsonPath`
-2. Map to `moduleSpecs[moduleCode]`:
+1. Use flat file data from `collected_data.modules[moduleCode]` (loaded in step-01)
+2. Data sources: `entities.json`, `rules.json`, `usecases.json`, `permissions.json`, `screens.json`
+3. Do NOT read from `moduleIndex.specification` or `moduleIndex.analysis` — these don't exist in flat-file format
 
 ```javascript
+const mod = collected_data.modules[moduleCode];
+
 moduleSpecs[moduleCode] = {
-  useCases: (moduleFeature.specification?.useCases || []).map(uc => ({
+  useCases: (mod.usecases?.useCases || []).map(uc => ({
     name: uc.name,
     actor: uc.primaryActor,
     steps: (uc.mainScenario || []).join("\n"),           // array → newline-separated string
     alternative: (uc.alternativeScenarios || [])
       .map(a => a.name + ": " + (a.steps || []).join(", ")).join("\n")
   })),
-  businessRules: (moduleFeature.analysis?.businessRules || []).map(br => ({
+  businessRules: (mod.rules?.rules || []).map(br => ({
     name: br.name,
     category: br.category,                              // "validation"|"calculation"|"workflow"|"security"|"data"
     statement: br.statement,
     example: (br.examples || []).map(e => e.input + " → " + e.expected).join("; ")
   })),
-  entities: (moduleFeature.analysis?.entities || []).map(ent => ({
+  entities: (mod.entities?.entities || []).map(ent => ({
     name: ent.name,
     description: ent.description || "",
     attributes: (ent.attributes || []).map(a => ({
@@ -128,7 +131,7 @@ moduleSpecs[moduleCode] = {
       r.target + " (" + r.type + ") - " + (r.description || "")
     )
   })),
-  permissions: buildPermissionKeys(moduleFeature),      // see below
+  permissions: buildPermissionKeys(mod.permissions),    // see below
   notes: "",
   mockupNotes: ""  // Deprecated: wireframes now embedded separately in EMBEDDED_ARTIFACTS
 }
@@ -139,9 +142,10 @@ moduleSpecs[moduleCode] = {
 The HTML uses `"Role|Action"` format (e.g. `"RH Admin|Consulter"`):
 
 ```javascript
-function buildPermissionKeys(moduleFeature) {
+// Input: permissions object from flat file (mod.permissions), NOT moduleFeature
+function buildPermissionKeys(permissionsData) {
   const keys = [];
-  const matrix = moduleFeature.specification?.permissionMatrix;
+  const matrix = permissionsData?.matrix || permissionsData?.permissionMatrix;
   if (!matrix) return keys;
   const actionMap = { read: "Consulter", create: "Creer", update: "Modifier",
                       delete: "Supprimer", validate: "Valider", export: "Exporter",
@@ -207,25 +211,30 @@ Build a JSON object containing ALL visual artifacts from module JSON files (inde
 }
 ```
 
-### Wireframes Mapping
+### Wireframes Mapping (FLAT-FILE: from screens.json)
 
 For EACH module in `master.modules[]`:
 
 ```javascript
-// Read the module index.json file
-const moduleFeature = readModuleFeature(moduleCode);
-const wireframes = (moduleFeature.specification?.uiWireframes || []).map(wf => ({
-  screen: wf.screen,                                    // e.g. "UM-list", "UM-form"
-  section: wf.section,                                  // e.g. "list", "form"
-  format: wf.mockupFormat || "ascii",                   // "ascii" | "svg"
-  content: wf.mockup,                                   // ASCII art or SVG markup
-  description: wf.description || "",
-  elements: wf.elements || [],                          // ["DataGrid", "FilterBar", ...]
-  actions: wf.actions || [],                            // ["filter", "sort", "create", ...]
-  componentMapping: wf.componentMapping || [],          // [{ wireframeElement, reactComponent }]
-  layout: wf.layout || null,                            // { type, regions: [...] }
-  permissionsRequired: wf.permissionsRequired || []
-}));
+// Use flat file data from collected_data (loaded in step-01)
+const mod = collected_data.modules[moduleCode];
+const screens = mod.screens?.screens || [];
+
+// Extract wireframes from screens that have mockup/wireframe data
+const wireframes = screens
+  .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+  .map(wf => ({
+    screen: wf.screen || wf.name || wf.id || "",        // e.g. "UM-list", "UM-form"
+    section: wf.section || "",                            // e.g. "list", "form"
+    format: wf.mockupFormat || "ascii",                   // "ascii" | "svg"
+    content: wf.mockup || wf.ascii || wf.content || "",   // ASCII art or SVG markup
+    description: wf.description || "",
+    elements: wf.elements || [],                          // ["DataGrid", "FilterBar", ...]
+    actions: wf.actions || [],                            // ["filter", "sort", "create", ...]
+    componentMapping: wf.componentMapping || [],          // [{ wireframeElement, reactComponent }]
+    layout: wf.layout || null,                            // { type, regions: [...] }
+    permissionsRequired: wf.permissionsRequired || []
+  }));
 
 // Store in artifacts object
 EMBEDDED_ARTIFACTS.wireframes[moduleCode] = wireframes;

package/templates/skills/ba-generate-html/steps/step-01-collect.md

@@ -51,7 +51,11 @@ ELSE:
     BLOCKING ERROR: "Feature status: {feature.status}, expected consolidated"
 ```
 
-### 4. Read All JSON Files
+### 4. Read All JSON Files (FLAT-FILE ARCHITECTURE)
+
+> **CRITICAL:** Module data lives in separate flat files (entities.json, usecases.json, etc.),
+> NOT inside index.json. The module index.json only contains metadata and file pointers.
+> You MUST read each flat file individually.
 
 ```
 collected_data = {
@@ -63,13 +67,18 @@ collected_data = {
 }
 
 FOR each module in master.index.modules[]:
-  moduleIndexPath = module.featureJsonPath || "{module.code}/business-analyse/v{version}/index.json"
-  moduleIndex = READ(moduleIndexPath)
+  // Resolve module directory path
+  moduleDir = "{app}/{module.code}/business-analyse/v{version}/"
+  moduleIndex = READ(moduleDir + "index.json")
 
+  // Read ALL flat files from module directory
   collected_data.modules[module.code] = {
     index: moduleIndex,
-    specification: moduleIndex.specification || {},
-    analysis: moduleIndex.analysis || {}
+    entities: READ(moduleDir + "entities.json") || { entities: [] },
+    rules: READ(moduleDir + "rules.json") || { rules: [] },
+    usecases: READ(moduleDir + "usecases.json") || { useCases: [] },
+    permissions: READ(moduleDir + "permissions.json") || { roles: [], permissions: [], matrix: [] },
+    screens: READ(moduleDir + "screens.json") || { screens: [] }
   }
 ```
 
@@ -78,7 +87,7 @@ FOR each module in master.index.modules[]:
 ```
 JSON collected:
   Master: index.json + cadrage.json
-  Modules: {module_count} module index files
+  Modules: {module_count} modules (flat files: entities, rules, usecases, permissions, screens)
 → Proceeding to data build...
 ```
 

package/templates/skills/ba-generate-html/steps/step-02-build-data.md

@@ -89,24 +89,29 @@ modules: master.modules.map(m => ({
 
 **moduleSpecs{} — ONE entry per module (CRITICAL):**
 
-For EACH module, read the module index.json and map:
+> **FLAT-FILE ARCHITECTURE:** Module data comes from separate JSON files collected in step-01,
+> NOT from index.json fields. Use `collected_data.modules[moduleCode].entities`, `.usecases`, etc.
+
+For EACH module, use the flat file data from `collected_data.modules[moduleCode]`:
 
 ```javascript
+const mod = collected_data.modules[moduleCode];
+
 moduleSpecs[moduleCode] = {
-  useCases: (moduleFeature.specification?.useCases || []).map(uc => ({
+  useCases: (mod.usecases?.useCases || []).map(uc => ({
     name: uc.name,
     actor: uc.primaryActor,
     steps: (uc.mainScenario || []).join("\n"),
     alternative: (uc.alternativeScenarios || []).map(a => a.name + ": " + (a.steps || []).join(", ")).join("\n")
   })),
-  businessRules: (moduleFeature.analysis?.businessRules || []).map(br => ({
+  businessRules: (mod.rules?.rules || []).map(br => ({
     name: br.name,
     category: br.category,
     statement: br.statement,
     example: (br.examples || []).map(e => e.input + " → " + e.expected).join("; ")
   })),
   // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated
-  entities: (moduleFeature.analysis?.entities || []).map(ent => ({
+  entities: (mod.entities?.entities || []).map(ent => ({
     name: ent.name,
     description: ent.description || "",
     attributes: (ent.attributes || []).length > 0
@@ -115,8 +120,8 @@ moduleSpecs[moduleCode] = {
     relationships: (ent.relationships || []).map(r =>
       typeof r === 'string' ? r : r.target + " (" + r.type + ") - " + (r.description || ""))
   })),
-  permissions: buildPermissionKeys(moduleFeature),
-  apiEndpoints: moduleFeature.specification?.apiEndpoints || []
+  permissions: buildPermissionKeys(mod.permissions),
+  apiEndpoints: mod.usecases?.apiEndpoints || []
 }
 ```
 
@@ -158,24 +163,34 @@ handoff: {
 > **FIELD RENAME WARNING:** Module JSON uses `mockupFormat`/`mockup`. HTML reads `format`/`content`. You MUST rename.
 
 **wireframes{} — per moduleCode:**
+
+> **FLAT-FILE:** Wireframes come from `screens.json` in each module directory (collected in step-01),
+> NOT from `moduleFeature.specification.uiWireframes`.
+
 ```javascript
+const mod = collected_data.modules[moduleCode];
+const screens = mod.screens?.screens || [];
+
+// Extract wireframes from screens that have mockup/wireframe data
 wireframes: {
-  [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
-    screen: wf.screen || wf.name || wf.title || wf.id || "",
-    section: wf.section || "",
-    format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
-    content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
-    svgContent: null,
-    description: wf.description || "",
-    elements: wf.elements || [],
-    actions: wf.actions || [],
-    componentMapping: Array.isArray(wf.componentMapping) ? wf.componentMapping
-      : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
-        ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
-        : [],
-    layout: typeof wf.layout === 'object' ? wf.layout : null,
-    permissionsRequired: wf.permissionsRequired || []
-  }))
+  [moduleCode]: screens
+    .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+    .map(wf => ({
+      screen: wf.screen || wf.name || wf.title || wf.id || "",
+      section: wf.section || "",
+      format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format
+      content: wf.mockup || wf.ascii || wf.content || "",   // RENAME: mockup → content
+      svgContent: null,
+      description: wf.description || "",
+      elements: wf.elements || [],
+      actions: wf.actions || [],
+      componentMapping: Array.isArray(wf.componentMapping) ? wf.componentMapping
+        : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
+          ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
+          : [],
+      layout: typeof wf.layout === 'object' ? wf.layout : null,
+      permissionsRequired: wf.permissionsRequired || []
+    }))
 }
 ```
 

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

@@ -358,13 +358,12 @@ IF workflow_mode = "project":
 
   Output path: docs/business-analyse/v{version}/index.json
   Thematic files (empty, initialized): docs/business-analyse/v{version}/*.json
-    - entities.json
-    - rules.json
-    - usecases.json
-    - permissions.json
-    - screens.json
+    - cadrage.json
     - validation.json
-    - handoff.json
+    - consolidation.json
+    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
+    // They are created by step-03 (specify) in each module directory.
+    // Do NOT create them at project/app level — empty files mislead downstream tools.
 
   Store:
     project_id: string  // PROJ-NNN
@@ -396,13 +395,12 @@ ELSE:
 
   Output path: docs/{app}/business-analyse/v{version}/index.json
   Thematic files (empty, initialized): docs/{app}/business-analyse/v{version}/*.json
-    - entities.json
-    - rules.json
-    - usecases.json
-    - permissions.json
-    - screens.json
+    - cadrage.json
     - validation.json
     - handoff.json
+    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
+    // They are created by step-03 (specify) in each module directory.
+    // Do NOT create them at app level — empty files mislead derive-prd and ralph-loop.
 ```
 
 > **Note:** In project mode, per-application index.json files are created later in step-01-cadrage.

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

@@ -423,6 +423,21 @@ ba-writer.enrichSection({
 // Update status
 ba-writer.updateStatus({feature_id}, "consolidated");
 
+// FIX H3: Clean up app-level index.json files entries
+// Only keep entries for files that actually have content at app level.
+// Module-level data lives in module directories — do NOT declare empty app-level files.
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "files",
+  data: {
+    // Keep only files that exist and have content at app level
+    cadrage: { path: "cadrage.json", hash: "framed", lastModified: now() },
+    validation: { path: "validation.json", hash: "consolidated", lastModified: now() }
+    // REMOVED: entities, rules, usecases, permissions, screens, handoff
+    // These exist only at module level (flat-file architecture)
+  }
+});
+
 // Save workflow state for resume support
 ba-writer.enrichSection({
   featureId: {feature_id},

package/templates/skills/derive-prd/steps/step-01-transform.md

@@ -201,8 +201,12 @@ FOR i = 0 to modules.length-1:
      - totalFiles: count from filesToCreate
      - totalTasks: estimated from complexity
      - handedOffAt: ISO timestamp
-  3. Write via ba-writer.enrichModuleHandoff({ moduleFeatureId, handoffData })
-  4. Display: "handoff {i+1}/{N}: {moduleCode} ({fileCount} files)"
+  3. Propagate featureDescription from app-level index.json:
+     ```javascript
+     handoffPayload.featureDescription = appIndex.metadata.featureDescription || null;
+     ```
+  4. Write via ba-writer.enrichModuleHandoff({ moduleFeatureId, handoffData })
+  5. Display: "handoff {i+1}/{N}: {moduleCode} ({fileCount} files)"
 ```
 
 ### 10. POST-CHECK Per Module (BLOCKING)

package/templates/skills/derive-prd/steps/step-02-export.md

@@ -29,6 +29,18 @@ For each module, generate PRD files via CLI, verify integrity, create progress t
 
 For EACH module:
 
+**Option A — Flat-file BA (recommended):**
+
+```bash
+# Single module:
+ss derive-prd --ba-dir {moduleBaDir} --output .ralph/prd-{moduleCode}.json
+
+# All modules from app-level index.json:
+ss derive-prd --ba-app {appIndexPath}
+```
+
+**Option B — Legacy feature.json:**
+
 ```bash
 ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
 ```

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -130,7 +130,7 @@ if (guardrailsNeeded.length > 0) {
     }
   }
 
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 }
 ```
 
@@ -142,7 +142,7 @@ const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
 
 if (guardrailsNeeded.length > 0) {
   prd.tasks.push(...guardrailsNeeded);
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 
   const newPending = prd.tasks.filter(t => t.status === 'pending').length;
   console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${newPending} pending tasks`);
@@ -186,7 +186,7 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
         t.error = 'Artifacts missing — re-execute';
         t.completed_at = null;
       });
-    writeJSON('.ralph/prd.json', prd);
+    writeJSON(currentPrdPath, prd);
   }
 }
 ```

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -16,6 +16,16 @@
 
 ## Loop Entry
 
+```javascript
+// PRD PATH RESOLUTION (MANDATORY - runs at loop entry)
+const queuePath = '.ralph/modules-queue.json';
+let currentPrdPath = '.ralph/prd.json';
+if (fileExists(queuePath)) {
+  const queue = readJSON(queuePath);
+  currentPrdPath = queue.queue[queue.currentIndex].prdFile;
+}
+```
+
 Display compact progress:
 ```
 [{iteration}/{max}] {completed}/{total} done | Finding eligible tasks...
@@ -26,7 +36,7 @@ Display compact progress:
 ## A0. Section-Split Mode (checked BEFORE standard batching)
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
+const prd = readJSON(currentPrdPath);
 
 if (prd._sectionSplit?.enabled) {
   // SECTION-SPLIT: Delegate per-phase instead of per-category batch
@@ -96,7 +106,7 @@ Apex sees a focused PRD for this phase only. After apex returns, continue:
   }
 
   prd._sectionSplit.currentPhase = nextPhase.phase;
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 
   // → Skip to section C (commit PRD state), then D (loop back)
   // → SKIP sections A and B. Jump directly to section C (COMMIT_PRD) below.
@@ -130,7 +140,7 @@ if (isDeadEnd) {
   // Then fall through to `eligible.length === 0` below which returns to step-04.
   console.log(`DEAD-END: ${prd.tasks.filter(t=>t.status==='completed').length} done, ${failedBeforeRetry.length} failed (retries exhausted), ${prd.tasks.filter(t=>t.status==='blocked').length} blocked`);
   prd.status = 'failed';
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
   // DO NOT reset retries below — skip to eligible search (will find 0 tasks → CHECK_COMPLETION)
 }
 
@@ -172,7 +182,7 @@ if (!isDeadEnd) {
     if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
   }
 
-  writeJSON('.ralph/prd.json', prd);
+  writeJSON(currentPrdPath, prd);
 } // end if (!isDeadEnd)
 
 // Find ALL eligible tasks (dependencies met)
@@ -213,12 +223,12 @@ for (const task of batch) {
   task.status = 'in_progress';
   task.started_at = new Date().toISOString();
 }
-writeJSON('.ralph/prd.json', prd);
+writeJSON(currentPrdPath, prd);
 ```
 
 ### B2. Invoke /apex
 
-**INVOKE `/apex -d .ralph/prd.json`**
+**INVOKE `/apex -d {currentPrdPath}`**
 
 Apex handles everything for the current module:
 - Reads PRD, extracts context (app_name, module_code, entities, sections)
@@ -230,11 +240,37 @@ Apex handles everything for the current module:
 
 > **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
 
-### B3. Verify Post-Apex Results
+### B2b. MANDATORY CHECKPOINT: Verify prd.json tasks updated
 
 ```javascript
 // Re-read PRD after apex execution
-const updatedPrd = readJSON('.ralph/prd.json');
+const updatedPrd = readJSON(currentPrdPath);
+const batchIds = batch.map(t => t.id);
+
+// BLOCKING CHECK: Verify apex actually updated task statuses
+const stillPending = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'pending').length;
+if (stillPending === batchIds.length) {
+  console.error(`BLOCKING ERROR: apex did not update any task statuses — all ${stillPending} tasks still pending`);
+  console.error('Possible causes: apex crashed, PRD path mismatch, or apex did not receive the correct PRD');
+  // Mark tasks as failed so retry logic can handle them
+  for (const task of updatedPrd.tasks) {
+    if (batchIds.includes(task.id) && task.status === 'pending') {
+      task.status = 'failed';
+      task.error = 'apex did not update task status';
+    }
+  }
+  writeJSON(currentPrdPath, updatedPrd);
+}
+```
+
+> **NEVER write progress.txt manually. ALWAYS update prd.json tasks FIRST,
+> then derive progress.txt from prd.json state.**
+
+### B3. Verify Post-Apex Results
+
+```javascript
+// Re-read PRD after apex execution (use currentPrdPath)
+const updatedPrd = readJSON(currentPrdPath);
 const batchIds = batch.map(t => t.id);
 
 const completed = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed').length;
@@ -260,7 +296,7 @@ console.log(`Apex completed: ${completed}/${batchIds.length} tasks`);
 ### C1. Update Progress File (MANDATORY)
 
 ```javascript
-const prdCheck = readJSON('.ralph/prd.json');
+const prdCheck = readJSON(currentPrdPath);
 const totalCompleted = prdCheck.tasks.filter(t => t.status === 'completed').length;
 const total = prdCheck.tasks.length;
 
@@ -275,13 +311,13 @@ appendFile('.ralph/progress.txt',
 ```javascript
 prdCheck.config.current_iteration++;
 prdCheck.updated_at = new Date().toISOString();
-writeJSON('.ralph/prd.json', prdCheck);
+writeJSON(currentPrdPath, prdCheck);
 ```
 
 ### C3. Git Commit (PRD state only — apex already committed code)
 
 ```bash
-git add .ralph/prd.json .ralph/progress.txt
+git add {currentPrdPath} .ralph/progress.txt
 [ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
 
 git commit -m "$(cat <<'EOF'

package/templates/skills/ralph-loop/references/init-resume-recovery.md

@@ -16,7 +16,7 @@ if (!fileExists('.ralph/prd.json')) {
   STOP;
 }
 
-const prd = readJSON('.ralph/prd.json');
+const prd = readJSON(currentPrdPath);
 
 // Detect format
 let resumeValid = false;