@atlashub/smartstack-cli 4.47.0 → 4.48.0

package/package.json

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

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/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;
 }
 ```
 

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);

package/templates/skills/business-analyse-handoff/references/prd-generation.md

@@ -80,6 +80,47 @@ ss business-analyse-handoff --feature {path} --output .ralph/prd-{moduleCode}.js
 
 ---
 
+### 2b. PRD v4.0 Structure (spec-oriented)
+
+> **v4 PRDs are generated with `--v4` flag.** They use `expectedFiles` instead of `implementation.filesToCreate`.
+
+```json
+{
+  "$version": "4.0.0",
+  "objectives": [
+    { "description": "...", "acceptanceCriteria": ["..."] }
+  ],
+  "expectedFiles": {
+    "domain": [...],
+    "application": [...],
+    "infrastructure": [...],
+    "api": [...],
+    "frontend": [...],
+    "seedData": [...],
+    "tests": [...],
+    "documentation": [...]
+  },
+  "gates": { /* declarative quality gate definitions */ }
+}
+```
+
+**Key differences from v3:**
+
+| Aspect | v3 (`$version: "3.0.0"`) | v4 (`$version: "4.0.0"`) |
+|--------|--------------------------|--------------------------|
+| File manifest | `implementation.filesToCreate` | `expectedFiles` (root level) |
+| Task model | `tasks[]` (pre-computed) | `objectives[]` (goal-oriented) |
+| Execution | Batch iterations (compact-loop) | Continuous (compaction-enabled) |
+
+**Consumer code must handle both:**
+```javascript
+const fileManifest = prd.$version === '4.0.0'
+  ? prd.expectedFiles
+  : prd.implementation?.filesToCreate;
+```
+
+---
+
 ### 3. Eight Categories (MANDATORY)
 
 All PRD files MUST include these 8 categories under `implementation.filesToCreate`:

package/templates/skills/business-analyse-handoff/steps/step-01-transform.md

@@ -157,7 +157,9 @@ After writing, verify:
 2. All 8 categories present
 3. brToCodeMapping non-empty
 4. Section resources have entity field
-Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped"
+5. SeedData contains CORE entries (NavigationModuleSeedData, NavigationSectionSeedData if sections exist, PermissionsSeedData, RolesSeedData)
+6. For FIRST module only: SeedData contains APP-LEVEL CORE entries (NavigationApplicationSeedData, ApplicationRolesSeedData)
+Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {coreCount} core seeds"
 ```
 
 ### 3. Display Progress

package/templates/skills/business-analyse-handoff/steps/step-02-export.md

@@ -99,11 +99,13 @@ Display verification table showing all 8 categories match between module JSON fi
 
 ```json
 {
-  "queue": [
-    { "moduleCode": "{code}", "order": 1, "dependencies": [], "complexity": "simple" },
-    { "moduleCode": "{code}", "order": 2, "dependencies": ["{dep}"], "complexity": "medium" }
+  "modules": [
+    { "code": "{code}", "prdFile": ".ralph/prd-{code}.json", "status": "pending", "order": 1, "dependencies": [], "complexity": "simple" },
+    { "code": "{code}", "prdFile": ".ralph/prd-{code}.json", "status": "pending", "order": 2, "dependencies": ["{dep}"], "complexity": "medium" }
   ],
-  "totalModules": {count},
+  "currentIndex": 0,
+  "totalModules": "{count}",
+  "completedModules": 0,
   "strategy": "topological"
 }
 ```

package/templates/skills/business-analyse-html/steps/step-02-build-data.md

@@ -198,13 +198,34 @@ handoff: {
 
 ```javascript
 const mod = collected_data.modules[moduleCode];
-const screens = mod.screens?.screens || [];
 
-// Extract wireframes from screens that have mockup/wireframe data
+// STEP 1: Collect wireframe sources from BOTH flat and nested structures
+// Flat: mod.screens.screens[] with mockupFormat/mockup at top level
+// Nested: mod.screens.sections[].resources[].wireframe (design step output)
+let rawWireframes = [];
+
+// Source A: flat screens[] array (original BA output or manually enriched)
+const flatScreens = mod.screens?.screens || [];
+rawWireframes.push(...flatScreens.filter(s => s.mockup || s.mockupFormat));
+
+// Source B: nested sections[].resources[].wireframe (design step output)
+const sections = mod.screens?.sections || [];
+for (const section of sections) {
+  for (const resource of (section.resources || [])) {
+    if (resource.wireframe) {
+      // Unwrap nested wireframe and add section context
+      rawWireframes.push({
+        ...resource.wireframe,
+        section: resource.wireframe.section || section.sectionCode || "",
+        screen: resource.wireframe.screen || `${section.sectionCode}-${resource.code}` || ""
+      });
+    }
+  }
+}
+
+// STEP 2: Map to HTML format (RENAME: mockupFormat → format, mockup → content)
 wireframes: {
-  [moduleCode]: screens
-    .filter(s => s.wireframe || s.mockup || s.mockupFormat)
-    .map(wf => ({
+  [moduleCode]: rawWireframes.map(wf => ({
       screen: wf.screen || wf.name || wf.title || wf.id || "",
       section: wf.section || "",
       format: wf.mockupFormat || "ascii",                   // RENAME: mockupFormat → format