@atlashub/smartstack-cli 3.16.0 → 3.18.0

package/package.json

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

package/templates/agents/gitflow/finish.md

@@ -77,10 +77,26 @@ git fetch origin develop:refs/remotes/origin/develop --force --quiet
 
 ### 4. Version Bump (Release/Hotfix)
 
-For npm projects:
+After merge-back to develop, invoke `/version-bump` to set the next development version:
+
+| Finished type | Next version | Example |
+|---------------|-------------|---------|
+| Release X.Y.Z | X.(Y+1).0 | 2.8.0 → 2.9.0 |
+| Hotfix X.Y.Z | X.Y.(Z+1) | 2.8.1 → 2.8.2 |
+
 ```bash
-npm version $NEXT_VERSION --no-git-tag-version
-git add package.json package-lock.json
+# Calculate NEXT_VERSION from the released version
+# Then call: /version-bump $NEXT_VERSION
+```
+
+This updates **all** version sources in sync:
+- `Directory.Build.props` → `<VersionPrefix>X.Y.Z</VersionPrefix>`
+- `web/smartstack-web/package.json` → `"version": "X.Y.Z"`
+- `.claude/gitflow/config.json` → `versioning.current`
+
+Then commit and push:
+```bash
+git add Directory.Build.props web/smartstack-web/package.json .claude/gitflow/config.json
 git commit -m "$(cat <<'EOF'
 chore: bump version to $NEXT_VERSION for development
 
@@ -90,6 +106,8 @@ EOF
 git push origin develop
 ```
 
+> **IMPORTANT**: Do NOT use `npm version` directly. Always use `/version-bump` for unified versioning.
+
 ### 5. Cleanup Worktree + Branch
 
 ```bash

package/templates/agents/gitflow/start.md

@@ -75,14 +75,24 @@ git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
 
 **Port allocation:** Hash branch name for unique ports (API: 5200+, Web: 5300+)
 
-### 7. Version Bump (Release only)
+### 7. Version Bump (Release/Hotfix only)
+
+For `release/*` and `hotfix/*` branches, invoke the `/version-bump` skill to synchronize all version files:
 
 ```bash
-# For release: bump version in source files
-npm version $VERSION --no-git-tag-version  # if package.json
-# OR update .csproj <Version> tag
+# Extract version from branch name: release/2.8.0 → 2.8.0, hotfix/2.8.1 → 2.8.1
+VERSION=$(echo "$FULL_BRANCH" | sed 's|^[^/]*/||')
 ```
 
+Then call: `/version-bump $VERSION`
+
+This updates **all** version sources in sync:
+- `Directory.Build.props` → `<VersionPrefix>X.Y.Z</VersionPrefix>`
+- `web/smartstack-web/package.json` → `"version": "X.Y.Z"`
+- `.claude/gitflow/config.json` → `versioning.current`
+
+> **IMPORTANT**: Do NOT use `npm version` or edit `.csproj` directly. Always use `/version-bump` for unified versioning.
+
 ### 8. Summary
 
 ```

package/templates/skills/application/templates-backend.md

@@ -82,6 +82,12 @@ public interface I$MODULE_PASCALService
 
 ## TEMPLATE: SERVICE IMPLEMENTATION
 
+> **TENANT ISOLATION RULES (BLOCKING):**
+> - ALL queries MUST include `.Where(x => x.TenantId == _currentUser.TenantId)`
+> - ALL entity creation MUST pass `_currentUser.TenantId` as first parameter to `Entity.Create()`
+> - NEVER use `new Entity { }` without `TenantId =` — always prefer the factory method
+> - NEVER use `Guid.Empty` as a placeholder — resolve the actual value from `_currentUser`
+
 ```csharp
 // src/SmartStack.Infrastructure/Services/$CONTEXT_PASCAL/$APPLICATION_PASCAL/$MODULE_PASCAL/$MODULE_PASCALService.cs
 
@@ -114,7 +120,8 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var query = _context.$ENTITY_PLURAL
-            .AsNoTracking();
+            .AsNoTracking()
+            .Where(x => x.TenantId == _currentUser.TenantId); // MANDATORY: tenant isolation
 
         // Apply filters
         if (!string.IsNullOrWhiteSpace(parameters.SearchTerm))
@@ -167,6 +174,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
     {
         var entity = await _context.$ENTITY_PLURAL
             .AsNoTracking()
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
 
         if (entity == null)
@@ -188,6 +196,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = $ENTITY_PASCAL.Create(
+            _currentUser.TenantId, // MANDATORY: tenant isolation — always first parameter
             request.Name,
             request.Description);
 
@@ -216,6 +225,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = await _context.$ENTITY_PLURAL
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken)
             ?? throw new NotFoundException("$ENTITY_PASCAL", id);
 
@@ -245,6 +255,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = await _context.$ENTITY_PLURAL
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
 
         if (entity == null)

package/templates/skills/business-analyse/SKILL.md

@@ -209,7 +209,7 @@ When step-00 detects that the description matches an existing application:
 | 04c  | `steps/step-04c-decide.md`        | Opus   | Final approval, write consolidation, proceed to handoff |
 | 05a  | `steps/step-05a-handoff.md`       | Sonnet | Handoff: file mapping (7 categories), BR-to-code mapping, API summary, write handoff |
 | 05b  | `steps/step-05b-deploy.md`        | Sonnet | Deploy: prd.json, progress.txt, manifest, ba-interactive.html |
-| 05c  | `steps/step-05c-ralph-readiness.md` | Sonnet | Ralph readiness validation gate (optional but recommended) |
+| 05c  | `steps/step-05c-ralph-readiness.md` | Opus | ULTRATHINK quality review + ralph readiness gate (MANDATORY) |
 | 06   | `steps/step-06-review.md`         | Opus   | Apply review corrections, create new version, regenerate all artifacts |
 
 </step_files>
@@ -252,10 +252,10 @@ Load ONLY relevant categories based on feature type:
 | -------- | ----------------------------------- | ------------ |
 | schema   | `schemas/feature-schema.json`       | All steps    |
 | spec     | `templates/tpl-frd.md`              | 02           |
-| handoff  | `templates/tpl-handoff.md`          | 04           |
+| handoff  | `templates/tpl-handoff.md`          | 05a          |
 | suggestions | `patterns/suggestion-catalog.md` | 01           |
-| interactive | `html/ba-interactive.html`        | 03d (incremental), 05d (final deploy)  |
-| mapping    | `references/html-data-mapping.md`  | 03d, 05d (FEATURE_DATA + EMBEDDED_ARTIFACTS mapping) |
+| interactive | `html/ba-interactive.html`        | 03d (incremental), 05b (final deploy)  |
+| mapping    | `references/html-data-mapping.md`  | 03d, 05b (FEATURE_DATA + EMBEDDED_ARTIFACTS mapping) |
 
 </template_files>
 

package/templates/skills/business-analyse/html/ba-interactive.html

@@ -3074,20 +3074,26 @@ function renderModuleMockups(code) {
             </div>` : ''}
             ${(wf.elements || []).length > 0 ? `
             <div class="wireframe-metadata">
-                <div><strong>Elements:</strong> ${wf.elements.join(', ')}</div>
+                <div><strong>Elements:</strong> ${wf.elements.map(e => typeof e === 'string' ? e : (e.type || e.label || e.id || '')).filter(Boolean).join(', ')}</div>
             </div>` : ''}
-            ${(wf.componentMapping || []).length > 0 ? `
+            ${(() => {
+                const cm = wf.componentMapping;
+                const mappings = Array.isArray(cm) ? cm
+                    : (typeof cm === 'object' && cm !== null) ? Object.entries(cm).map(([k,v]) => ({wireframeElement: k, reactComponent: v}))
+                    : [];
+                return mappings.length > 0 ? `
             <details class="wireframe-details">
                 <summary>Mapping composants SmartStack</summary>
                 <table class="mapping-table">
                     <thead><tr><th>Element maquette</th><th>Composant React</th></tr></thead>
                     <tbody>
-                        ${wf.componentMapping.map(m =>
-                            `<tr><td>${m.wireframeElement}</td><td><code>${m.reactComponent}</code></td></tr>`
+                        ${mappings.map(m =>
+                            '<tr><td>' + (m.wireframeElement || '') + '</td><td><code>' + (m.reactComponent || '') + '</code></td></tr>'
                         ).join('')}
                     </tbody>
                 </table>
-            </details>` : ''}
+            </details>` : '';
+            })()}
             <div class="wireframe-comment">
                 <label style="font-size:0.8rem;color:var(--text-muted);display:block;margin-bottom:0.3rem;">Commentaire / Feedback :</label>
                 <textarea class="form-textarea"

package/templates/skills/business-analyse/html/src/scripts/05-render-specs.js

@@ -392,20 +392,26 @@ function renderModuleMockups(code) {
             </div>` : ''}
             ${(wf.elements || []).length > 0 ? `
             <div class="wireframe-metadata">
-                <div><strong>Elements:</strong> ${wf.elements.join(', ')}</div>
+                <div><strong>Elements:</strong> ${wf.elements.map(e => typeof e === 'string' ? e : (e.type || e.label || e.id || '')).filter(Boolean).join(', ')}</div>
             </div>` : ''}
-            ${(wf.componentMapping || []).length > 0 ? `
+            ${(() => {
+                const cm = wf.componentMapping;
+                const mappings = Array.isArray(cm) ? cm
+                    : (typeof cm === 'object' && cm !== null) ? Object.entries(cm).map(([k,v]) => ({wireframeElement: k, reactComponent: v}))
+                    : [];
+                return mappings.length > 0 ? `
             <details class="wireframe-details">
                 <summary>Mapping composants SmartStack</summary>
                 <table class="mapping-table">
                     <thead><tr><th>Element maquette</th><th>Composant React</th></tr></thead>
                     <tbody>
-                        ${wf.componentMapping.map(m =>
-                            `<tr><td>${m.wireframeElement}</td><td><code>${m.reactComponent}</code></td></tr>`
+                        ${mappings.map(m =>
+                            '<tr><td>' + (m.wireframeElement || '') + '</td><td><code>' + (m.reactComponent || '') + '</code></td></tr>'
                         ).join('')}
                     </tbody>
                 </table>
-            </details>` : ''}
+            </details>` : '';
+            })()}
             <div class="wireframe-comment">
                 <label style="font-size:0.8rem;color:var(--text-muted);display:block;margin-bottom:0.3rem;">Commentaire / Feedback :</label>
                 <textarea class="form-textarea"

package/templates/skills/business-analyse/references/deploy-data-build.md

@@ -42,7 +42,19 @@ const FEATURE_DATA = {
     "{moduleCode}": {
       useCases: module.specification.useCases || [],
       businessRules: module.analysis.businessRules || [],
-      entities: module.analysis.entities || [],
+      // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated from canonical format
+      entities: (module.analysis.entities || []).map(ent => ({
+        name: ent.name,
+        description: ent.description || "",
+        attributes: (ent.attributes || []).length > 0
+          ? ent.attributes.map(a => ({ name: a.name, description: a.description || "" }))
+          : (ent.fields || []).map(f => ({ name: f.name, description: f.description || f.type || "" })),
+        relationships: (ent.relationships || []).length > 0
+          ? ent.relationships.map(r =>
+              typeof r === 'string' ? r : `${r.target} (${r.type}) - ${r.description || ""}`)
+          : (ent.fields || []).filter(f => f.foreignKey)
+              .map(f => `${f.foreignKey.table} (N:1) - ${f.description || f.name}`)
+      })),
       permissions: module.specification.permissions || [],
       apiEndpoints: module.specification.apiEndpoints || []
     }
@@ -85,15 +97,19 @@ const EMBEDDED_ARTIFACTS = {
     // PER-MODULE keyed object (NOT a flat array)
     // FOR EACH module: extract from specification.uiWireframes[]
     [moduleCode]: moduleFeature.specification.uiWireframes.map(wf => ({
-      screen: wf.screen,                          // e.g. "employees-list"
-      section: wf.section,                         // e.g. "list"
-      format: wf.mockupFormat || "ascii",          // RENAME: mockupFormat → format
-      content: wf.mockup,                          // RENAME: mockup → content (ASCII art string)
+      screen: wf.screen || wf.name || wf.id || "",  // SAFETY NET: fallback name/id → screen
+      section: wf.section || "",                      // e.g. "list"
+      format: wf.mockupFormat || "ascii",             // RENAME: mockupFormat → format
+      content: wf.mockup,                             // RENAME: mockup → content (ASCII art string)
       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: [...] }
+      elements: wf.elements || [],                    // [{ id, type, label }] or ["DataGrid", ...]
+      actions: wf.actions || [],                      // [{ trigger, action }] or ["filter", ...]
+      // SAFETY NET: convert object → array format if agent used { "Header": "PageHeader" } instead of [{ wireframeElement, reactComponent }]
+      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,  // SAFETY NET: ignore string layout ("grid")
       permissionsRequired: wf.permissionsRequired || []
     }))
   },

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -32,6 +32,18 @@ const checklist = {
     details: "Standalone entities should be rare in business modules"
   },
 
+  entitySchemaCompliance: {
+    check: "All entities use canonical format: attributes[] (not fields[]), relationships[] array present",
+    status: specification.entities.every(e =>
+      Array.isArray(e.attributes) && e.attributes.length > 0 &&
+      !e.fields && !e.tableName && !e.primaryKey
+    ) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Entities with 'fields' instead of 'attributes' break HTML data model display and PRD extraction. " +
+             "Check: every entity must have attributes[] (not fields[]), every entity must have relationships[], " +
+             "no entity should have tableName or primaryKey (technical fields belong in implementation, not analysis)"
+  },
+
   // SECTION 2: BUSINESS RULES (BLOCKING)
   businessRules: {
     minimum: 4,
@@ -133,6 +145,21 @@ const checklist = {
     details: "EVERY section MUST have a wireframe (ASCII/SVG)"
   },
 
+  wireframeSchemaCompliance: {
+    check: "All wireframes have required fields: screen, section, mockupFormat, elements[], componentMapping[], layout (object), permissionsRequired[]",
+    status: specification.uiWireframes.every(wf =>
+      wf.screen && wf.section && wf.mockupFormat &&
+      Array.isArray(wf.elements) && wf.elements.length > 0 &&
+      Array.isArray(wf.componentMapping) && wf.componentMapping.length > 0 &&
+      typeof wf.layout === 'object' && wf.layout !== null &&
+      Array.isArray(wf.permissionsRequired)
+    ) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Wireframes missing metadata render as empty frames in HTML documentation. " +
+             "Check: screen (not name/id), section, mockupFormat, elements[] non-empty, " +
+             "componentMapping[] as array of {wireframeElement, reactComponent}, layout as object (not string)"
+  },
+
   navigation: {
     check: "Module has ≥1 navigation entry",
     status: specification.navigation.entries.length >= 1 ? "PASS" : "FAIL",
@@ -261,11 +288,11 @@ ELSE:
 
 | Category | Checks | Passed | Failed | Warnings |
 |----------|--------|--------|--------|----------|
-| Data Model | 3 | {n} | {n} | {n} |
+| Data Model | 4 | {n} | {n} | {n} |
 | Business Rules | 3 | {n} | {n} | {n} |
 | Use Cases & FRs | 4 | {n} | {n} | {n} |
 | Permissions | 3 | {n} | {n} | {n} |
-| UI & Navigation | 3 | {n} | {n} | {n} |
+| UI & Navigation | 4 | {n} | {n} | {n} |
 | I18N & Messages | 3 | {n} | {n} | {n} |
 | Seed Data | 2 | {n} | {n} | {n} |
 | API Endpoints | 2 | {n} | {n} | {n} |

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

@@ -374,12 +374,30 @@ If initialization was interrupted:
 
 1. Check `.business-analyse/config.json` for currentFeature
 2. If feature ID exists, search for feature.json in `docs/business/`
-3. If found, check `metadata.workflow.lastCompletedStep`:
-   - If `"step-04-consolidation"` AND status = `"consolidated"`:
-     → Resume directly at `step-05a-handoff.md` (skip steps 00-04)
-     → Display: "Resuming from consolidation — proceeding to handoff..."
+3. If found, check status and `metadata.workflow.lastCompletedStep`:
+
+   **Status-based resume routing (check in this order):**
+
+   - If status = `"handed-off"` AND `ba-interactive.html` missing:
+     → Resume at `step-05b-deploy.md` (deploy artifacts + HTML)
+     → Display: "Handoff complete but HTML/artifacts missing — deploying..."
+
    - If status = `"handed-off"` AND `.ralph/prd-*.json` files missing:
      → Resume at `step-05b-deploy.md` (only deploy artifacts needed)
-     → Display: "Handoff complete but artifacts missing — deploying..."
+     → Display: "Handoff complete but PRD files missing — deploying..."
+
+   - If status = `"consolidated"` OR lastCompletedStep = `"step-04-consolidation"`:
+     → Resume directly at `step-05a-handoff.md` (skip steps 00-04)
+     → Display: "Resuming from consolidation — proceeding to handoff..."
+
+   - If status = `"specified"` AND `metadata.workflow.allModulesSpecified === true`:
+     → Resume at `step-04a-collect.md` (consolidation phase)
+     → Display: "All modules specified — resuming at consolidation..."
+
+   - If status = `"specified"` AND `metadata.workflow.completedModules.length > 0` AND `metadata.workflow.completedModules.length < metadata.workflow.moduleOrder.length`:
+     → Resume at `step-03a1-setup.md` (continue specifying remaining modules)
+     → Display: "Resuming module specification ({completedCount}/{totalCount})..."
+
    - Otherwise: offer to resume from last completed step
+
 4. If not found, create fresh feature.json

package/templates/skills/business-analyse/steps/step-03a2-analysis.md

@@ -60,6 +60,20 @@ Define entities for this module (business attributes, not technical):
 > ```
 > **FORBIDDEN fields in attributes:** Do NOT use `type`, `values`, `rules`.
 > Use `description` to explain what the attribute is, `validation` for format/constraint rules, `unique` as boolean.
+>
+> **FORBIDDEN FORMAT — DO NOT USE (technical/database schema):**
+> ```json
+> {
+>   "name": "Project",
+>   "tableName": "rh_projects",
+>   "primaryKey": "id",
+>   "fields": [
+>     { "name": "code", "type": "UUID", "required": true }
+>   ]
+> }
+> ```
+> **Why forbidden:** `tableName`, `primaryKey` are technical fields that do NOT belong in analysis. `fields[]` is NOT recognized by the build pipeline — only `attributes[]` is. `type` with SQL types (UUID, string, timestamp) belongs in implementation, not analysis. Using this format causes **empty entity data in the HTML documentation** and **broken PRD extraction**.
+> The canonical format uses `attributes[]` (not `fields[]`), `relationships[]` (not FK inside fields), and NO technical fields (tableName, primaryKey).
 
 #### 6c. Process Flow
 
@@ -130,9 +144,13 @@ Before proceeding to step-03b-ui.md, VERIFY:
 
 1. **Module feature.json exists** at expected path (`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`)
 2. **Module feature.json has analysis section** with `entities[]` (at least 1) and `businessRules[]` (at least 1)
-3. **Module status in master** = "in-progress" (set by section 2 above)
-4. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
-5. **Sections identified** with clear roles and entities assigned
+3. **Entity schema compliance (BLOCKING)** — EVERY entity has `attributes[]` (NOT `fields[]`) and `relationships[]` arrays.
+   Quick check: `analysis.entities.every(e => Array.isArray(e.attributes) && e.attributes.length >= 1)`
+   IF any entity has `fields[]` instead of `attributes[]` → STRUCTURAL ERROR, fix before proceeding.
+   IF any entity has `tableName` or `primaryKey` → STRUCTURAL ERROR, these are technical fields that do not belong in analysis.
+4. **Module status in master** = "in-progress" (set by section 2 above)
+5. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
+6. **Sections identified** with clear roles and entities assigned
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03b-ui with incomplete data.
 

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -167,9 +167,36 @@ Example for a list section:
 Store in specification.uiWireframes[] (**MANDATORY** for every section):
 
 See [references/ui-resource-cards.md](../references/ui-resource-cards.md) for exact JSON format of `specification.uiWireframes[]`.
-**REQUIRED fields:** `screen`, `mockup`, `elements`, `section`, `componentMapping`, `layout` are ALL mandatory.
+**REQUIRED fields:** `screen`, `mockup`, `mockupFormat`, `elements`, `section`, `actions`, `componentMapping`, `layout`, `permissionsRequired` are ALL mandatory.
 A wireframe without `componentMapping` or `layout` will FAIL validation in step 9.
 
+> **STRUCTURE CARD: specification.uiWireframes[]** — ALL fields are MANDATORY. Do NOT omit any.
+> ```json
+> {
+>   "screen": "{module}-{section}",                // MANDATORY — unique screen ID (NOT "name" or "id")
+>   "section": "list|detail|create|approve|...",   // MANDATORY — section code
+>   "description": "Description en français",
+>   "mockupFormat": "ascii",                       // MANDATORY — "ascii" or "svg"
+>   "mockup": "┌───...┘",                         // MANDATORY — ASCII art string
+>   "elements": [                                  // MANDATORY — array of element objects
+>     { "id": "elem-grid", "type": "SmartTable", "label": "Grille" }
+>   ],
+>   "actions": [                                   // MANDATORY — user interactions
+>     { "trigger": "Click row", "action": "Navigate to detail" }
+>   ],
+>   "componentMapping": [                          // MANDATORY — array of mapping objects
+>     { "wireframeElement": "DataGrid", "reactComponent": "SmartTable" }
+>   ],
+>   "layout": {                                    // MANDATORY — object with regions (NOT a string)
+>     "type": "page",
+>     "regions": [{ "id": "main", "position": "main", "span": 12, "components": [...] }]
+>   },
+>   "permissionsRequired": ["read"]                // MANDATORY — required permissions
+> }
+> ```
+> **FORBIDDEN FORMAT:** wireframe with only `name` + `mockup` + `layout: "grid"` (string).
+> Every wireframe MUST have ALL fields above. Missing metadata causes empty frames in the HTML documentation.
+
 > **IF client rejects a mockup:** Revise and re-propose until validated. Do NOT proceed without client approval on the layout.
 
 ### 3b-bis. Wireframe-to-Component Mapping
@@ -250,6 +277,9 @@ Before proceeding to step-03c-compile.md, VERIFY:
 6. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
 7. **Form field completeness** — SmartForm fields[] covers ALL entity attributes except system/audit fields
 8. **Navigation entries for all sections** — Every section (including dashboard) has a corresponding entry in `specification.navigation.entries[]`
+9. **Wireframe structural compliance (BLOCKING)** — ALL wireframes have: `screen` (not just `name`), `section`, `mockupFormat`, `elements[]` (non-empty array of objects), `actions[]`, `componentMapping[]` (array of {wireframeElement, reactComponent}), `layout` (object with regions, NOT a string), `permissionsRequired[]`
+   Quick check: `uiWireframes.every(wf => wf.screen && wf.section && wf.mockupFormat && Array.isArray(wf.elements) && wf.elements.length > 0 && typeof wf.layout === 'object' && wf.layout !== null)`
+   IF any wireframe fails → FIX before proceeding. DO NOT load step-03c with degraded wireframes.
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03c-compile with incomplete data.
 

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

@@ -41,7 +41,9 @@ Validate the module specification for completeness and consistency, write to fea
 | 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 |
@@ -65,6 +67,8 @@ Validate the module specification for completeness and consistency, write to fea
 - BR-{CATEGORY}-NNN format
 - Entity names PascalCase
 - Field names camelCase
+- Entity attribute format: `attributes[]` with {name, description}, NOT `fields[]` with {name, type} — entities must NOT have tableName or primaryKey
+- Wireframe structure: `screen` (not `name`), `componentMapping` is array of {wireframeElement, reactComponent} (not plain key-value object), `layout` is object with regions (not string)
 - Permission paths dot-separated lowercase
 
 #### 9d. Decision
@@ -132,9 +136,9 @@ ba-writer.enrichSection({
 
 **Execute the comprehensive validation checklist:**
 
-Run the 25-check validation process across 10 categories:
-- Data Model (3 checks) | Business Rules (3 checks) | Use Cases & FRs (4 checks)
-- Permissions (3 checks) | UI & Navigation (3 checks) | I18N & Messages (3 checks)
+Run the 27-check validation process across 10 categories:
+- Data Model (4 checks) | Business Rules (3 checks) | Use Cases & FRs (4 checks)
+- Permissions (3 checks) | UI & Navigation (4 checks) | I18N & Messages (3 checks)
 - Seed Data (2 checks) | API Endpoints (2 checks) | Validations (1 check) | Gherkin (1 check)
 
 ```javascript
@@ -161,6 +165,24 @@ ELSE:
 
 ---
 
+### 9g. Anti-Premature-Completion Guard (MANDATORY)
+
+> **CRITICAL — NEVER say "the analysis is complete" or "ready for /ralph-loop" at this point.**
+> Step-03d is the END of SPECIFICATION, NOT the end of the BA workflow.
+> Steps 04a → 04b → 04c (consolidation) + 05a → 05b → 05c (handoff) are STILL REQUIRED.
+> Without handoff, /ralph-loop will generate an INCOMPLETE PRD (no frontend, no tests).
+
+**FORBIDDEN phrases in step-03d output:**
+- "L'analyse métier est complète" / "The business analysis is complete"
+- "Prêt pour /ralph-loop" / "Ready for /ralph-loop"
+- "Vous pouvez maintenant lancer /ralph-loop"
+- Any variation suggesting the BA is finished or /ralph-loop can be invoked
+
+**REQUIRED phrasing:**
+- "Module {name} spécifié. {Remaining} modules restants." (if more modules)
+- "Tous les modules spécifiés. Passage à la consolidation (étapes 04a-04c)..." (if last module)
+- NEVER mention /ralph-loop — only step-05c (ralph readiness) validates the handoff
+
 ### 10. Module Summary with Roles & Permissions
 
 Display comprehensive summary:
@@ -282,8 +304,23 @@ IF currentModuleIndex < moduleOrder.length:
   Load: steps/step-03a1-setup.md
 
 IF currentModuleIndex >= moduleOrder.length:
-  Display: "═══ Tous les modules spécifiés! Passage à la consolidation... ═══"
+  Display: "═══ Tous les modules spécifiés! Passage à la consolidation (04a→04c) puis handoff (05a→05c)... ═══"
+  Display: "⚠ NE PAS lancer /ralph-loop — la consolidation et le handoff sont encore nécessaires."
   ba-writer.updateStatus({feature_id}, "specified")
+
+  // CHECKPOINT: Save progress BEFORE transition (protects against context exhaustion)
+  ba-writer.enrichSection({
+    featureId: {feature_id},
+    section: "metadata.workflow",
+    data: {
+      lastCompletedStep: "step-03d-validate",
+      allModulesSpecified: true
+    }
+  })
+
+  // MANDATORY TRANSITION — DO NOT STOP HERE
+  // If context is near exhaustion, the checkpoint above ensures the user
+  // can resume with /business-analyse and it will route to step-04a automatically.
   Load: steps/step-04a-collect.md
 ```
 

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

@@ -360,10 +360,9 @@ Effort:    {total_days} days ({total_hours} hours)
   1. Ouvrir ba-interactive.html dans le navigateur
   2. Partager avec les stakeholders pour validation
   3. Si retours --> relancer /business-analyse pour une nouvelle itération
-  4. Validation de la compatibilité ralph-loop (recommandé):
+  4. Validation qualité ULTRATHINK (automatique):
 
-     Continuez à step-05c-ralph-readiness.md pour valider
-     la complétude et l'intégrité avant développement
+     → Lancement automatique de step-05c-ralph-readiness.md...
 
   5. Une fois validé, lancer le développement:
 
@@ -376,16 +375,19 @@ Effort:    {total_days} days ({total_hours} hours)
 
 ## NEXT STEP
 
-**RECOMMENDED:** Load `steps/step-05c-ralph-readiness.md` to run validation gate before /ralph-loop.
+**MANDATORY:** Load `steps/step-05c-ralph-readiness.md` — ULTRATHINK quality review & readiness gate.
+
+> **This step is NON-NEGOTIABLE.** The BA skill MUST run step-05c before completing.
+> DO NOT skip this step. DO NOT display a "done" message without running step-05c first.
 
 This validation ensures:
-- All module handoffs are complete
+- ULTRATHINK deep quality review of the entire BA output
+- All module handoffs are complete and content is coherent
 - PRD files are structurally valid
 - Cross-module references are resolvable
+- Specification quality meets production standards
 - No blocking issues before development
 
-User can skip validation and proceed directly to /ralph-loop, but validation is strongly recommended to catch issues early.
-
 ---
 
 ## MODE SUPPORT & TROUBLESHOOTING