@atlashub/smartstack-cli 4.53.0 → 4.55.0

package/package.json

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

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

@@ -120,11 +120,68 @@ IF docs/**/*.md files found:
 - Pre-identify integration points: new feature may depend on or extend existing modules
 - NEVER re-specify what's already handed-off (status = "handed-off") — reference it instead
 
+### 2d. Domain Research (WebSearch — BEFORE engaging the client)
+
+> **Ground the analysis in real-world patterns. This prevents greenfield mistakes
+> (e.g., putting firstName on Employee instead of linking to User).**
+> This step takes 30-60 seconds and dramatically improves entity design quality.
+
+**WHEN to search:** ALWAYS for the main business domain. Skip only if the domain is purely SmartStack-internal (e.g., config, admin tools).
+
+**HOW to search:** Use WebSearch tool with targeted queries based on the detected domain.
+
+```
+1. DOMAIN MODEL SEARCH
+   Query: "{detected_domain} data model best practices" (e.g., "HR management data model best practices")
+   → Extract: standard entities, common relationships, industry patterns
+   → Store key findings in {domain_research}.dataModel
+
+2. ENTITY PATTERN SEARCH (for the 2-3 most complex detected entities)
+   Query: "{entity_name} entity design pattern ERP" (e.g., "employee entity design pattern ERP")
+   → Extract: standard attributes, versioning patterns, common pitfalls
+   → Store in {domain_research}.entityPatterns[entity_name]
+
+3. WORKFLOW SEARCH (if the domain involves approval/validation flows)
+   Query: "{domain} approval workflow pattern" (e.g., "timesheet approval workflow pattern")
+   → Extract: standard states, transition rules, multi-level approval
+   → Store in {domain_research}.workflows
+```
+
+**WHAT to extract (ULTRATHINK — internal only):**
+```yaml
+domain_research:
+  domain: "{detected domain — e.g., HR, CRM, Billing}"
+  dataModel:
+    standardEntities: ["Entity1", "Entity2"]     # what the industry considers standard
+    commonRelationships: ["Entity1 → Entity2"]   # typical FK patterns
+    antiPatterns: ["storing salary directly on employee"]  # mistakes to avoid
+  entityPatterns:
+    Employee:
+      standardAttributes: ["code", "userId", "departmentId", "hireDate", "status"]
+      versionedData: ["salary → separate table with effectiveDate"]
+      personPattern: "link to User via FK, never duplicate personal info"
+    Invoice:
+      standardAttributes: ["number", "clientId", "issueDate", "dueDate", "status"]
+      calculatedFields: ["subtotal", "taxAmount", "total"]
+      workflowStates: ["Draft", "Sent", "Paid", "Overdue", "Cancelled"]
+  workflows:
+    timesheetApproval: "Draft → Submitted → ManagerApproved → ClientApproved"
+    invoiceLifecycle: "Draft → Validated → Sent → Paid"
+```
+
+> **CRITICAL:** This research is INTERNAL context. Do NOT show raw search results to the client.
+> Use the findings to:
+> - Improve pre-analysis quality (detect shadow zones the client won't mention)
+> - Ground entity architecture decisions in Phase 4d-bis
+> - Inform proactive suggestions in Phase 4 (ANTICIPATION)
+> - Prevent common anti-patterns during step-03 entity specification
+
 ### 2b. Silent Pre-Analysis (ULTRATHINK — no output to client)
 
 > **The AI prepares the conversation before speaking. This is NOT output — it's internal reasoning.**
+> **INCLUDES domain research findings from 2d above.**
 
-Analyze `{feature_description}` silently:
+Analyze `{feature_description}` AND `{domain_research}` silently:
 
 1. **Identify problem type** from keywords (replace, automate, centralize, new tool)
 2. **Extract explicit modules/features** mentioned in the description
@@ -143,6 +200,12 @@ _preAnalysis:
   detected_modules: [{name, description, detected_sections}]
   shadow_zones: [{topic, why_it_matters, challenge_question}]
   anticipated_suggestions: [{suggestion, justification, module}]
+  domain_research:                          # from Phase 2d web search
+    domain: "{detected domain}"
+    standardEntities: [...]
+    antiPatterns: [...]
+    entityPatterns: {entity: {standardAttributes, versionedData, personPattern}}
+    workflows: {name: "state1 → state2 → state3"}
 ```
 
 ---

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

@@ -43,9 +43,41 @@ For each module, execute these sub-steps:
 
 Load via ba-reader:
 - Module's `index.json` (if exists from previous run)
-- Application `cadrage.json` for stakeholder context
+- Application `cadrage.json` for stakeholder context (including `_preAnalysis.domain_research`)
 - Completed modules' summaries (compact, <100 lines each)
 
+### A-bis. Entity Pattern Research (WebSearch — per module)
+
+> **Before defining entities, validate design against industry best practices.**
+> Uses domain_research from step-01 as baseline, then does targeted searches for this specific module.
+
+```
+IF cadrage._preAnalysis.domain_research exists:
+  → Load as baseline (already researched in step-01)
+ELSE:
+  → Run a quick WebSearch: "{module_domain} entity data model best practices"
+
+FOR each main entity in this module (max 2-3 searches):
+  Query: "{entity_name} entity design pattern {domain}"
+  (e.g., "invoice entity design ERP", "timesheet data model best practices")
+
+  EXTRACT (ULTRATHINK — internal only):
+  - Standard attributes for this entity type
+  - Common relationships and cardinality
+  - Versioned vs. inline data patterns (e.g., salary history)
+  - Workflow states if applicable
+  - Known anti-patterns to avoid
+
+  CROSS-CHECK against SmartStack conventions (B-bis rules):
+  - Would this entity trigger Person Extension Pattern?
+  - Are there attributes that should be versioned (salary, rate)?
+  - Does this entity already exist in the SmartStack socle DB?
+```
+
+> **CRITICAL:** This research informs entity design but does NOT override SmartStack conventions.
+> If web research suggests putting firstName on Employee, the B-bis guard still blocks it
+> because SmartStack uses auth_Users for personal data.
+
 ### B. Entities
 
 For each entity identified in step 02:

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

@@ -49,6 +49,8 @@ Generate the interactive HTML document of the business analysis from the JSON an
 - **NEVER** call `.join()` on arrays without checking element types — object elements produce `[object Object]`
 - **Final file** MUST be > 100KB
 - **Final file** MUST NOT contain the string `[object Object]`
+- **NEVER** reuse a build script (`_build-html.js`, `generate-html.js`) from a previous session — always re-execute steps 01→02→03→04 from scratch. Build scripts are throwaway artifacts that bypass the skill's normalization logic.
+- **With `--force`:** delete any existing build script before proceeding
 
 ## References
 

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

@@ -4663,16 +4663,43 @@ function renderSmartDashboardMockup(res) {
         { label: 'Taux', value: '80%' }
     ];
     kpis.forEach(function(kpi) {
-        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(kpi.value || '0') + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
+        var displayValue = kpiDisplayValue(kpi);
+        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(displayValue) + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
     });
     html += '</div>';
 
-    // Chart placeholder
-    html += '<div class="mock-chart-placeholder">Graphique</div>';
+    // Chart placeholders
+    var charts = res.charts || [{ label: 'Graphique' }];
+    charts.forEach(function(chart) {
+        html += '<div class="mock-chart-placeholder">' + escapeHtml(chart.label || chart.type || 'Graphique') + '</div>';
+    });
 
     return html;
 }
 
+function kpiDisplayValue(kpi) {
+    var v = kpi.value || '0';
+    // If value is already a simple display value (number, percentage), use it
+    if (/^\d[\d,.\s]*%?$/.test(v)) return v;
+    // Detect formula patterns and generate realistic sample values
+    if (v.indexOf('(') !== -1) {
+        var label = (kpi.label || '').toLowerCase();
+        var color = (kpi.color || '').toLowerCase();
+        // Percentage indicators
+        if (v.indexOf('ratio') !== -1 || v.indexOf('%') !== -1 || label.indexOf('taux') !== -1 || label.indexOf('rate') !== -1)
+            return '87.5%';
+        // Average
+        if (v.indexOf('avg') !== -1 || label.indexOf('moyen') !== -1 || label.indexOf('average') !== -1)
+            return '12.4';
+        // Sum (monetary or hours)
+        if (v.indexOf('sum') !== -1)
+            return label.indexOf('jour') !== -1 || label.indexOf('day') !== -1 ? '156' : '45,678';
+        // Count (default)
+        return '1,234';
+    }
+    return v;
+}
+
 /* ---------- SmartFilter ---------- */
 function renderSmartFilterMockup(res) {
     var options = res.options || [];

package/templates/skills/business-analyse-html/html/src/scripts/06-render-mockups.js

@@ -303,16 +303,43 @@ function renderSmartDashboardMockup(res) {
         { label: 'Taux', value: '80%' }
     ];
     kpis.forEach(function(kpi) {
-        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(kpi.value || '0') + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
+        var displayValue = kpiDisplayValue(kpi);
+        html += '<div class="mock-kpi"><div class="mock-kpi-value">' + escapeHtml(displayValue) + '</div><div class="mock-kpi-label">' + escapeHtml(kpi.label || '') + '</div></div>';
     });
     html += '</div>';
 
-    // Chart placeholder
-    html += '<div class="mock-chart-placeholder">Graphique</div>';
+    // Chart placeholders
+    var charts = res.charts || [{ label: 'Graphique' }];
+    charts.forEach(function(chart) {
+        html += '<div class="mock-chart-placeholder">' + escapeHtml(chart.label || chart.type || 'Graphique') + '</div>';
+    });
 
     return html;
 }
 
+function kpiDisplayValue(kpi) {
+    var v = kpi.value || '0';
+    // If value is already a simple display value (number, percentage), use it
+    if (/^\d[\d,.\s]*%?$/.test(v)) return v;
+    // Detect formula patterns and generate realistic sample values
+    if (v.indexOf('(') !== -1) {
+        var label = (kpi.label || '').toLowerCase();
+        var color = (kpi.color || '').toLowerCase();
+        // Percentage indicators
+        if (v.indexOf('ratio') !== -1 || v.indexOf('%') !== -1 || label.indexOf('taux') !== -1 || label.indexOf('rate') !== -1)
+            return '87.5%';
+        // Average
+        if (v.indexOf('avg') !== -1 || label.indexOf('moyen') !== -1 || label.indexOf('average') !== -1)
+            return '12.4';
+        // Sum (monetary or hours)
+        if (v.indexOf('sum') !== -1)
+            return label.indexOf('jour') !== -1 || label.indexOf('day') !== -1 ? '156' : '45,678';
+        // Count (default)
+        return '1,234';
+    }
+    return v;
+}
+
 /* ---------- SmartFilter ---------- */
 function renderSmartFilterMockup(res) {
     var options = res.options || [];

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

@@ -192,6 +192,29 @@ function normalizeAction(a) {
   return a.code || a.id || a.label || a.actionCode || "";
 }
 
+// Helper: normalize a KPI — replace formula values with sample display values
+function normalizeKpi(k) {
+  if (typeof k !== 'object') return { label: String(k), value: "0" };
+  const label = k.label || k.displayName || "";
+  const rawValue = k.value || k.metric || "0";
+  let displayValue = rawValue;
+  // Detect formula patterns (e.g., count(...), sum(...), ratio(...), avg(...))
+  if (typeof rawValue === 'string' && rawValue.includes('(')) {
+    const lbl = label.toLowerCase();
+    if (rawValue.includes('ratio') || rawValue.includes('%') || lbl.includes('taux') || lbl.includes('rate'))
+      displayValue = "87.5%";
+    else if (rawValue.includes('avg') || lbl.includes('moyen') || lbl.includes('average'))
+      displayValue = "12.4";
+    else if (rawValue.includes('sum'))
+      displayValue = (lbl.includes('jour') || lbl.includes('day') || lbl.includes('heure') || lbl.includes('hour')) ? "156" : "45,678";
+    else
+      displayValue = "1,234";
+  }
+  // Also handle format hint from the KPI definition
+  if (k.format === 'percentage' && displayValue === rawValue) displayValue = "80%";
+  return { label: label, value: displayValue };
+}
+
 if (flatScr.length > 0) {
   // FORMAT A: flat screens[] array (ba-003 style)
   const bySec = {};
@@ -214,9 +237,7 @@ if (flatScr.length > 0) {
         fields: (t.fields || []).map(normalizeField)
       })),
       actions: (s.actions || []).map(normalizeAction),
-      kpis: (s.kpis || []).map(k => typeof k === 'object'
-        ? { label: k.label || k.displayName || "", value: k.value || k.metric || "0" }
-        : { label: String(k), value: "0" }),
+      kpis: (s.kpis || []).map(normalizeKpi),
       options: s.options || [],
       permission: s.permission || "",
       notes: s.description || s.sectionDescription || ""
@@ -224,39 +245,65 @@ if (flatScr.length > 0) {
   });
   screens = Object.values(bySec);
 } else if (sectionScr.length > 0) {
-  // FORMAT B: sections[] array (ba-004 style — id/displayName/layout convention)
-  // Each section IS a screen resource (columns, tabs, filters are ON the section itself)
-  const bySec = {};
-  sectionScr.forEach(sec => {
-    const secId = sec.id || sec.code || sec.sectionCode || "";
-    const secLabel = sec.displayName || sec.label || sec.sectionLabel || secId;
-    const componentType = sec.layout || sec.componentType || "unknown";
-    if (!bySec[secId]) bySec[secId] = {
-      sectionCode: secId,
-      sectionLabel: secLabel,
-      resources: []
-    };
-    bySec[secId].resources.push({
-      code: secId,
-      label: secLabel,
-      type: componentType,
-      columns: (sec.columns || []).map(normalizeColumn),
-      filters: (sec.filters || []).map(normalizeFilter),
-      fields: [],
-      tabs: (sec.tabs || []).map(t => ({
-        label: t.displayName || t.label || t.code || t.id || "",
-        fields: (t.fields || []).map(normalizeField)
-      })),
-      actions: (sec.actions || []).map(normalizeAction),
-      kpis: (sec.kpis || []).map(k => typeof k === 'object'
-        ? { label: k.displayName || k.label || "", value: k.format === "percentage" ? "80%" : "1,234" }
-        : { label: String(k), value: "0" }),
-      options: sec.options || [],
-      permission: (typeof sec.permissions === 'object' ? sec.permissions?.view : sec.permission) || "",
-      notes: sec.description || ""
+  // DETECT sub-format: canonical (resources[] inside sections) vs ba-004 (data on section itself)
+  const hasNestedResources = sectionScr.some(sec => (sec.resources || []).length > 0);
+
+  if (hasNestedResources) {
+    // FORMAT B-CANONICAL: sections[] with resources[] (ba-005+ style — sectionCode/sectionLabel/resources[])
+    // Resources have their own code/type/columns/tabs/kpis — iterate over them
+    screens = sectionScr.map(sec => ({
+      sectionCode: sec.sectionCode || sec.id || sec.code || "",
+      sectionLabel: sec.sectionLabel || sec.displayName || sec.label || sec.sectionCode || "",
+      resources: (sec.resources || []).map(res => ({
+        code: res.code || res.id || "",
+        label: res.label || res.displayName || res.code || "",
+        type: res.type || res.componentType || res.layout || "unknown",
+        columns: (res.columns || []).map(normalizeColumn),
+        filters: (res.filters || []).map(normalizeFilter),
+        fields: [],
+        tabs: (res.tabs || []).map(t => ({
+          label: t.label || t.displayName || t.code || t.id || "",
+          fields: (t.fields || []).map(normalizeField)
+        })),
+        actions: (res.actions || []).map(normalizeAction),
+        kpis: (res.kpis || []).map(normalizeKpi),
+        options: res.options || [],
+        permission: res.permission || "",
+        notes: res.notes || res.description || ""
+      }))
+    }));
+  } else {
+    // FORMAT B-LEGACY: sections[] without resources[] (ba-004 style — data directly on section)
+    const bySec = {};
+    sectionScr.forEach(sec => {
+      const secId = sec.id || sec.code || sec.sectionCode || "";
+      const secLabel = sec.displayName || sec.label || sec.sectionLabel || secId;
+      const componentType = sec.layout || sec.componentType || "unknown";
+      if (!bySec[secId]) bySec[secId] = {
+        sectionCode: secId,
+        sectionLabel: secLabel,
+        resources: []
+      };
+      bySec[secId].resources.push({
+        code: secId,
+        label: secLabel,
+        type: componentType,
+        columns: (sec.columns || []).map(normalizeColumn),
+        filters: (sec.filters || []).map(normalizeFilter),
+        fields: [],
+        tabs: (sec.tabs || []).map(t => ({
+          label: t.displayName || t.label || t.code || t.id || "",
+          fields: (t.fields || []).map(normalizeField)
+        })),
+        actions: (sec.actions || []).map(normalizeAction),
+        kpis: (sec.kpis || []).map(normalizeKpi),
+        options: sec.options || [],
+        permission: (typeof sec.permissions === 'object' ? sec.permissions?.view : sec.permission) || "",
+        notes: sec.description || ""
+      });
     });
-  });
-  screens = Object.values(bySec);
+    screens = Object.values(bySec);
+  }
 }
 moduleSpecs[moduleCode].screens = screens;
 ```

package/templates/skills/business-analyse-html/steps/step-03-render.md

@@ -13,6 +13,23 @@ Inject FEATURE_DATA and EMBEDDED_ARTIFACTS into the HTML template and write the
 
 ---
 
+## PRE-RENDER CLEANUP (MANDATORY)
+
+> **NEVER reuse a build script from a previous session.**
+> Build scripts (`_build-html.js`, `generate-html.js`) are throwaway artifacts that bypass
+> the skill's normalization logic (normalizeKpi, normalizeColumn, Format B-CANONICAL).
+> Reusing them causes stale data and missed fixes.
+
+```
+Delete any existing build scripts in the project directory:
+  rm -f _build-html.js generate-html.js build-html.js
+
+This ensures the HTML is always generated from the current step-02 output,
+not from a cached script that may use outdated mapping logic.
+```
+
+---
+
 ## EXECUTION SEQUENCE
 
 ### 1. Locate Template