@atlashub/smartstack-cli 3.19.0 → 3.21.0

package/templates/skills/business-analyse/steps/step-03d-validate.md

@@ -34,21 +34,50 @@ Validate the module specification for completeness and consistency, write to fea
 
 #### 9a. Completeness Checks
 
-| Section | Minimum | Status |
-|---------|---------|--------|
-| actors | 2 | PASS/FAIL |
-| useCases | 2 | PASS/FAIL |
-| functionalRequirements | 4 | PASS/FAIL |
-| permissionMatrix | 1 resource × 2 roles | PASS/FAIL |
-| entities | 1 | PASS/FAIL |
-| entitySchemaFormat | attributes[] not fields[] (BLOCKING) | PASS/FAIL |
-| wireframes | 1 per section (BLOCKING) | PASS/FAIL |
-| wireframeSchema | All required fields present (BLOCKING) | PASS/FAIL |
-| gherkinScenarios | 2 per UC | PASS/FAIL |
-| validations | 1 | PASS/FAIL |
-| messages | 4 | PASS/FAIL |
-| lifeCycles | 1 (if entity has status) | PASS/FAIL |
-| seedDataCore | 7 sections present | PASS/FAIL (BLOCKING) |
+> **CRITICAL:** Checks MUST count ACTUAL elements in arrays, NOT declarative values.
+> A check that reports PASS when the array is empty is a LIE and BLOCKS downstream quality.
+
+| Section | Minimum | How to verify | Status |
+|---------|---------|---------------|--------|
+| actors | 2 | `specification.actors.length >= 2` | PASS/FAIL |
+| useCases | 2 | `specification.useCases.length >= 2` | PASS/FAIL |
+| functionalRequirements | 4 | `specification.functionalRequirements.length >= 4` | PASS/FAIL |
+| permissionMatrix | 1 resource × 2 roles | `specification.permissionMatrix.permissions.length >= 1 && specification.permissionMatrix.roleAssignments.length >= 2` | PASS/FAIL |
+| entities | 1 | `analysis.entities.length >= 1` | PASS/FAIL |
+| entitySchemaFormat | attributes[] not fields[] (BLOCKING) | `analysis.entities.every(e => e.attributes?.length > 0)` | PASS/FAIL |
+| entityAttributeTypes | ALL attributes have `type` field (BLOCKING) | `analysis.entities.every(e => e.attributes.every(a => a.type))` | PASS/FAIL |
+| wireframes | 1 per section (BLOCKING) | `specification.wireframes.length >= specification.sections.length` (count REAL elements) | PASS/FAIL |
+| wireframeSchema | All required fields present (BLOCKING) | `specification.wireframes.every(w => w.screen && w.section && (w.mockup \|\| w.content))` | PASS/FAIL |
+| sections | 1 (BLOCKING) | `specification.sections.length >= 1` (EVERY module needs at least 1 section) | PASS/FAIL |
+| gherkinScenarios | 1 array entry | `Array.isArray(specification.gherkinScenarios) && specification.gherkinScenarios.length >= 1` | PASS/FAIL |
+| gherkinFormat | Array not object (BLOCKING) | `Array.isArray(specification.gherkinScenarios)` (NOT a single object) | PASS/FAIL |
+| validations | 1 | `specification.validations.length >= 1` | PASS/FAIL |
+| validationFormat | rules[] array (BLOCKING) | `specification.validations.every(v => Array.isArray(v.rules))` (NOT singular `rule`) | PASS/FAIL |
+| messages | 4 | `specification.messages.length >= 4` | PASS/FAIL |
+| messageFormat | `message` field present (BLOCKING) | `specification.messages.every(m => m.message)` | PASS/FAIL |
+| lifeCycles | 1 (if entity has status) | `specification.lifeCycles.length >= 1` (if any entity has status/state field) | PASS/FAIL |
+| seedDataCore | 7 arrays present with content | See detailed check below | PASS/FAIL (BLOCKING) |
+| apiEndpoints | 1 | `specification.apiEndpoints.length >= 1` | PASS/FAIL |
+| i18nKeys | present | `specification.i18nKeys !== undefined && specification.i18nKeys !== null` | PASS/FAIL |
+| navigationIcons | non-null | `specification.seedDataCore.navigationModules.every(m => m.icon !== null)` | PASS/FAIL |
+
+**seedDataCore detailed check (BLOCKING):**
+```javascript
+const sdc = specification.seedDataCore;
+const checks = [
+  { key: "navigationModules",      actual: sdc.navigationModules?.length || 0,      min: 1 },
+  { key: "navigationSections",     actual: sdc.navigationSections?.length || 0,     min: 1 },  // EVERY module needs ≥1 section
+  { key: "navigationResources",    actual: sdc.navigationResources?.length || 0,    min: 1 },
+  { key: "navigationTranslations", actual: sdc.navigationTranslations?.length || 0, min: 2 },  // min fr+en
+  { key: "permissions",            actual: sdc.permissions?.length || 0,            min: 1 },
+  { key: "rolePermissions",        actual: sdc.rolePermissions?.length || 0,        min: 1 },
+  { key: "permissionConstants",    actual: sdc.permissionConstants?.length || 0,    min: 1 }
+];
+const failures = checks.filter(c => c.actual < c.min);
+IF failures.length > 0:
+  BLOCKING ERROR: "seedDataCore incomplete — empty arrays: {failures.map(f => f.key).join(', ')}"
+  → Fix: Ensure specification.sections[] has ≥1 entry, then re-run 8f-bis transform
+```
 
 #### 9b. Consistency Checks
 
@@ -278,6 +307,44 @@ ba-writer.updateStatus({module_feature_id}, "specified")
 ba-writer.updateModuleStatus({feature_id}, {currentModule.code}, "specified")
 ```
 
+#### 11-POST-CHECK: Verify Written Data (BLOCKING)
+
+> **CRITICAL — Data loss prevention.** After writing, READ BACK the module feature.json and verify the following arrays are **non-empty**:
+
+```javascript
+// READ BACK the written feature.json
+const written = ba-reader.read({module_feature_id});
+
+// BLOCKING checks — if ANY fails, the write was incomplete
+const checks = [
+  { key: "specification.actors",          actual: written.specification?.actors?.length,          min: 2 },
+  { key: "specification.useCases",        actual: written.specification?.useCases?.length,        min: 2 },
+  { key: "specification.wireframes",      actual: written.specification?.wireframes?.length,      min: 1 },
+  { key: "specification.sections",        actual: written.specification?.sections?.length,        min: 1 },
+  { key: "specification.seedDataCore",    actual: Object.keys(written.specification?.seedDataCore || {}).length, min: 7 },
+  { key: "specification.lifeCycles",      actual: written.specification?.lifeCycles?.length,      min: 0 },
+  { key: "specification.gherkinScenarios",actual: written.specification?.gherkinScenarios?.length,min: 1 },
+  { key: "specification.apiEndpoints",    actual: written.specification?.apiEndpoints?.length,    min: 1 }
+];
+
+const failures = checks.filter(c => (c.actual || 0) < c.min);
+
+IF failures.length > 0:
+  BLOCKING ERROR: "Feature.json write INCOMPLETE — missing data in: {failures.map(f => f.key).join(', ')}"
+  → Re-execute section 11 write with ALL specification data
+  → DO NOT proceed to next module until ALL checks pass
+
+// SPECIAL CHECK: wireframes content verification
+IF written.specification?.wireframes?.length > 0:
+  const emptyMockups = written.specification.wireframes.filter(wf => !wf.mockup && !wf.content);
+  IF emptyMockups.length > 0:
+    WARNING: "{emptyMockups.length} wireframes have empty mockup content — verify step-03b data"
+```
+
+> **WHY:** Step-03b generates wireframes in memory, step-03c only writes seedDataCore explicitly.
+> If the comprehensive write in section 11 is skipped or partial, wireframes/sections are LOST.
+> This POST-CHECK catches the data loss BEFORE advancing to the next module.
+
 ---
 
 ### 11-bis. Deploy Incremental Interactive HTML (MANDATORY)

package/templates/skills/business-analyse/steps/step-05a-handoff.md

@@ -194,7 +194,7 @@ See [references/handoff-file-templates.md](../references/handoff-file-templates.
 |----------|--------|-----------|
 | **4.1 Domain** | `analysis.entities[]` | Entities, ValueObjects, Enums, Exceptions |
 | **4.2 Application** | `analysis.useCases[]` | Services, DTOs, Validators |
-| **4.3 Infrastructure** | `analysis.entities[]` | EF Configurations, DbSet, DI |
+| **4.3 Infrastructure** | `analysis.entities[]` | EF Configurations, DbSet, DI. **DEPENDENCY:** Each EF config task MUST `dependsOn` its corresponding domain entity task. |
 | **4.4 API** | `specification.apiEndpoints[]` | Controllers with `{ContextShort}` mapping |
 | **4.5 Frontend** | `specification.uiWireframes[]` | Pages, Components, Hooks + wireframe traceability |
 | **4.6 SeedData** | `specification.seedDataCore` | 5 CORE + business + IClientSeedDataProvider |
@@ -204,6 +204,7 @@ See [references/handoff-file-templates.md](../references/handoff-file-templates.
 - All backend paths include `{ContextPascal}/{ApplicationName}/` hierarchy
 - Frontend pages MUST have `linkedWireframes[]` + `wireframeAcceptanceCriteria`
 - SeedData: 5 CORE entries ALWAYS + IClientSeedDataProvider for client projects
+- **Acceptance Criteria Mapping:** Each task's `acceptanceCriteria` MUST be derived from its own `linkedFRs[]` entries (lookup FR → `acceptanceCriteria`). NEVER map by sequential FR index — use the task's explicit linkedFRs to resolve the correct criteria.
 - Path convention: `Persistence/Seeding/Data/` (NEVER `Data/SeedData/`)
 
 ---
@@ -228,6 +229,52 @@ For each endpoint: operation, method, route, linkedUC, linkedFR, permissions, re
 
 Total endpoints = count of specification.apiEndpoints[] across all modules.
 
+### 6b. Frontend Task Splitting (MANDATORY)
+
+> **CRITICAL:** Frontend MUST be split into discrete tasks, NOT bundled as a single mega-task.
+> A single mega-task covering 5-8 files prevents granular error recovery in ralph-loop.
+
+For each module, generate these SEPARATE frontend file entries (not one monolithic entry):
+
+```json
+"frontend": [
+  { "path": "src/pages/{Mod}/{ListPage}Page.tsx", "type": "Page", "linkedWireframes": ["{module}-list"], "module": "{moduleCode}" },
+  { "path": "src/pages/{Mod}/{DetailPage}Page.tsx", "type": "Page", "linkedWireframes": ["{module}-detail"], "module": "{moduleCode}" },
+  { "path": "src/hooks/use{Module}.ts", "type": "Hook", "module": "{moduleCode}" },
+  { "path": "src/i18n/{module}.json", "type": "I18n", "module": "{moduleCode}" }
+]
+```
+
+Additional per-section pages (dashboard, import, etc.) are separate entries.
+
+**Route wiring task (MANDATORY — separate entry):**
+```json
+{ "path": "src/App.tsx", "type": "RouteWiring", "module": "{moduleCode}", "description": "Wire {module} routes into App.tsx Layout wrappers (standard + tenant-prefixed blocks). BLOCKING: pages without route wiring = blank pages." }
+```
+
+### 6c. Cross-Module PRD (MANDATORY for multi-module features)
+
+> **CRITICAL:** Cross-module integration tasks MUST exist in a dedicated PRD file.
+> Without this, ralph-loop will NOT execute E2E tests or FK validation.
+
+Generate `.ralph/prd-CrossModule.json` with:
+```json
+{
+  "$version": "3.0.0",
+  "implementation": {
+    "filesToCreate": {
+      "tests": [
+        { "path": "src/Tests/Integration/CrossModule/ForeignKeyValidationTests.cs", "type": "IntegrationTests", "module": "CrossModule" },
+        { "path": "src/Tests/Integration/CrossModule/PermissionMatrixTests.cs", "type": "SecurityTests", "module": "CrossModule" },
+        { "path": "src/Tests/Integration/CrossModule/E2EFlowTests.cs", "type": "E2ETests", "module": "CrossModule" }
+      ]
+    }
+  }
+}
+```
+
+Add to progress.txt after all module tasks.
+
 ---
 
 ### 7. Write Handoff to Feature.json
@@ -317,7 +364,7 @@ const seedDataCore = {
     code: m.code,
     label: m.name || m.code,
     description: m.description,
-    icon: null,  // set by ralph-loop
+    icon: inferIconFromModule(m) || "folder",  // MUST be non-null — use sensible default
     iconType: "lucide",
     route: `/business/${master.metadata.application.toLowerCase()}/${m.code.toLowerCase()}`,
     displayOrder: (i + 1) * 10
@@ -386,6 +433,28 @@ const seedDataCore = {
   )
 };
 
+// Icon inference from module context (NEVER leave as null)
+function inferIconFromModule(module) {
+  const codeLC = module.code.toLowerCase();
+  const iconMap = {
+    'employee': 'users', 'staff': 'users', 'personnel': 'users', 'user': 'users',
+    'project': 'folder-kanban', 'task': 'check-square', 'work': 'briefcase',
+    'time': 'clock', 'schedule': 'calendar', 'planning': 'calendar-days',
+    'absence': 'calendar-off', 'leave': 'calendar-off', 'vacation': 'palm-tree',
+    'finance': 'wallet', 'billing': 'receipt', 'invoice': 'file-text',
+    'inventory': 'warehouse', 'stock': 'package', 'product': 'shopping-bag',
+    'customer': 'building', 'client': 'building-2', 'contact': 'contact',
+    'report': 'bar-chart', 'dashboard': 'layout-dashboard', 'analytics': 'trending-up',
+    'document': 'file-text', 'notification': 'bell', 'setting': 'settings',
+    'order': 'shopping-cart', 'vehicle': 'car', 'maintenance': 'wrench',
+    'audit': 'shield-check', 'workflow': 'git-branch', 'approval': 'check-circle'
+  };
+  for (const [keyword, icon] of Object.entries(iconMap)) {
+    if (codeLC.includes(keyword)) return icon;
+  }
+  return "folder";  // fallback — NEVER null
+}
+
 ba-writer.enrichSection({
   featureId: {feature_id},
   section: "seedDataCore",
@@ -393,12 +462,17 @@ ba-writer.enrichSection({
 })
 ```
 
-**POST-CHECK (non-blocking):**
+**POST-CHECK (BLOCKING for icons, warning for counts):**
 ```
 IF seedDataCore.navigationModules.length !== master.modules.length:
   WARNING: seedDataCore has ${seedDataCore.navigationModules.length} nav modules but ${master.modules.length} modules exist
 IF seedDataCore.permissions.length === 0:
   WARNING: seedDataCore has 0 permissions — applicationRoles may be missing
+IF seedDataCore.navigationModules.some(m => !m.icon || m.icon === null):
+  BLOCKING ERROR: "Navigation modules with null icons detected — ralph-loop will render empty navigation"
+  → Fix: Re-run inferIconFromModule() for modules with null icons
+IF seedDataCore.navigationSections.length === 0:
+  WARNING: "0 navigation sections — every module should have at least 1 section (e.g., 'list')"
 ```
 
 #### 7c. Master Handoff (after ALL modules written + seedDataCore generated)

package/templates/skills/business-analyse/steps/step-05b-deploy.md

@@ -357,6 +357,33 @@ After writing the HTML file, verify:
      BLOCKING_ERROR("Module mismatch: expected [${expectedModules}] but wireframes has [${wireframeModules}]")
    ```
 
+9. **MODULE DATA COMPLETENESS** — every module in FEATURE_DATA.modules[] must carry ALL fields from feature.json
+   ```
+   FOR each htmlModule in FEATURE_DATA.modules[]:
+     masterModule = master.modules.find(m => m.code === htmlModule.code)
+
+     // name MUST be display name, NOT code
+     IF htmlModule.name === htmlModule.code AND masterModule.name !== masterModule.code:
+       BLOCKING_ERROR("Module '${htmlModule.code}' has name === code. Expected: '${masterModule.name}'")
+
+     // anticipatedSections MUST be present (drives Structure tab + navigation tree)
+     IF masterModule.anticipatedSections?.length > 0 AND (!htmlModule.anticipatedSections OR htmlModule.anticipatedSections.length === 0):
+       BLOCKING_ERROR("Module '${htmlModule.code}' lost anticipatedSections: master has ${masterModule.anticipatedSections.length}, HTML has 0")
+       → FIX: Copy anticipatedSections from master.modules[].anticipatedSections
+
+     // dependencies/dependents MUST be present (drives dependency graph)
+     IF masterModule.dependencies?.length > 0 AND (!htmlModule.dependencies OR htmlModule.dependencies.length === 0):
+       BLOCKING_ERROR("Module '${htmlModule.code}' lost dependencies array")
+   ```
+
+   Display verification table:
+   ```
+   POST-CHECK: Module data completeness
+   | Module         | name    | sections | deps | wireframes | specs | Match |
+   |----------------|---------|----------|------|------------|-------|-------|
+   | {code}         | {name}  | {n}      | {n}  | {n}        | OK    | OK/FAIL |
+   ```
+
 **IF ANY CHECK FAILS → DO NOT PROCEED. Fix the data mapping and regenerate.**
 
 ---

package/templates/skills/gitflow/_shared.md

@@ -57,32 +57,34 @@ normalize_path_for_platform() {
       fi
       ;;
     *)
-      # Normalize backslashes to forward slashes
-      echo "${input_path//\\//}"
-      ;;
-  esac
-}
-
-# Translates a path to storage-neutral format for config.json (forward slashes, drive letter)
-normalize_path_for_storage() {
-  local input_path="$1"
-  case "$GF_PLATFORM" in
-    wsl)
-      # WSL path → Windows-style for config: /mnt/d/foo/bar → D:/foo/bar
+      # WSL path → Windows path: /mnt/d/foo → D:/foo
       if [[ "$input_path" =~ ^/mnt/([a-z])/(.*) ]]; then
         local drive=$(echo "${BASH_REMATCH[1]}" | tr '[:lower:]' '[:upper:]')
         echo "${drive}:/${BASH_REMATCH[2]}"
       else
-        echo "$input_path"
+        # Normalize backslashes to forward slashes
+        echo "${input_path//\\//}"
       fi
       ;;
-    *)
-      # Normalize backslashes to forward slashes
-      echo "${input_path//\\//}"
-      ;;
   esac
 }
 
+# Translates a path to storage-neutral format for config.json (forward slashes, drive letter)
+# Always converts WSL paths to Windows-style, regardless of current platform
+normalize_path_for_storage() {
+  local input_path="$1"
+  # WSL path → Windows-style: /mnt/d/foo → D:/foo (always, regardless of platform)
+  if [[ "$input_path" =~ ^/mnt/([a-z])/(.*) ]]; then
+    local drive=$(echo "${BASH_REMATCH[1]}" | tr '[:lower:]' '[:upper:]')
+    echo "${drive}:/${BASH_REMATCH[2]}"
+  elif [[ "$input_path" =~ ^[A-Za-z]:[\\/] ]]; then
+    # Normalize backslashes only
+    echo "${input_path//\\//}"
+  else
+    echo "$input_path"
+  fi
+}
+
 # Returns current directory in platform-appropriate format
 get_current_dir() {
   local raw_pwd
@@ -314,6 +316,52 @@ cleanup_worktree_for_branch() {
 
 ---
 
+## REPAIR_WORKTREE_PATHS
+
+Repairs worktree metadata files that contain paths from a different platform (e.g., WSL paths `/mnt/d/...` on Windows, or Windows paths `D:/...` on WSL). Scans `.bare/worktrees/*/gitdir` and the corresponding `{worktree}/.git` files.
+
+```bash
+repair_worktree_paths() {
+  local BARE_DIR="$1"  # Path to .bare directory
+  local WORKTREES_DIR="$BARE_DIR/worktrees"
+  [ ! -d "$WORKTREES_DIR" ] && return 0
+
+  local REPAIRED=0
+  for wt_dir in "$WORKTREES_DIR"/*/; do
+    [ ! -d "$wt_dir" ] && continue
+    local wt_name=$(basename "$wt_dir")
+    local gitdir_file="$wt_dir/gitdir"
+    [ ! -f "$gitdir_file" ] && continue
+
+    # Fix .bare/worktrees/{name}/gitdir
+    local stored_path=$(cat "$gitdir_file" | tr -d '\n\r')
+    local fixed_path=$(normalize_path_for_platform "$stored_path")
+    if [ "$stored_path" != "$fixed_path" ]; then
+      echo "$fixed_path" > "$gitdir_file"
+      echo "REPAIRED: $wt_name/gitdir → $fixed_path"
+      REPAIRED=$((REPAIRED + 1))
+    fi
+
+    # Fix the worktree's .git file
+    local wt_real_dir=$(dirname "$fixed_path")
+    if [ -f "$wt_real_dir/.git" ]; then
+      local git_content=$(cat "$wt_real_dir/.git" | tr -d '\n\r')
+      local git_path="${git_content#gitdir: }"
+      local fixed_git_path=$(normalize_path_for_platform "$git_path")
+      if [ "$git_path" != "$fixed_git_path" ]; then
+        echo "gitdir: $fixed_git_path" > "$wt_real_dir/.git"
+        echo "REPAIRED: $wt_name/.git → $fixed_git_path"
+        REPAIRED=$((REPAIRED + 1))
+      fi
+    fi
+  done
+
+  [ "$REPAIRED" -gt 0 ] && echo "Worktree paths: $REPAIRED file(s) repaired"
+}
+```
+
+---
+
 ## RESOLVE_WORKSPACE
 
 Resolves the workspace JSON file by walking up the directory tree.

package/templates/skills/gitflow/phases/status.md

@@ -61,15 +61,20 @@ HOTFIXES=$(git branch -r | grep "origin/${GF_HOTFIX_PREFIX}" | sed 's/origin\///
 ### 4. Worktree Status
 
 ```bash
+# Repair cross-platform paths before listing (WSL ↔ Windows)
+detect_platform
+repair_worktree_paths "$(git rev-parse --git-common-dir 2>/dev/null || echo '.bare')"
+
 WORKTREES=$(git worktree list)
 WORKTREE_COUNT=$(echo "$WORKTREES" | wc -l)
 
-# Check for orphaned worktrees
+# Check for orphaned worktrees (normalize paths for cross-platform compatibility)
 ORPHANED=""
 while read -r line; do
-  PATH=$(echo "$line" | awk '{print $1}')
+  WT_PATH=$(echo "$line" | awk '{print $1}')
+  WT_PATH=$(normalize_path_for_platform "$WT_PATH")
   BRANCH=$(echo "$line" | awk '{print $3}' | tr -d '[]')
-  [ ! -d "$PATH" ] && ORPHANED="$ORPHANED\n$PATH ($BRANCH)"
+  [ ! -d "$WT_PATH" ] && ORPHANED="$ORPHANED\n$WT_PATH ($BRANCH)"
 done <<< "$WORKTREES"
 ```
 

package/templates/skills/gitflow/steps/step-start.md

@@ -158,6 +158,9 @@ esac
 
 mkdir -p "$(dirname $WORKTREE_PATH)"
 git worktree add -b "$FULL_BRANCH" "$WORKTREE_PATH" "origin/$BASE_BRANCH"
+
+# Fix cross-platform paths in worktree metadata (if created from different platform)
+repair_worktree_paths "$(git rev-parse --git-common-dir)"
 ```
 
 **Mode: --no-worktree**