@atlashub/smartstack-cli 2.6.2 → 2.7.0

package/templates/skills/business-analyse/schemas/shared/common-defs.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "common-defs.json",
+  "title": "SmartStack BA - Shared Definitions",
+  "description": "Reusable $defs shared across all BA sub-schemas",
+
+  "$defs": {
+    "stepStatus": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["pending", "in-progress", "completed", "skipped"] },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" }
+      }
+    },
+
+    "moduleStatus": {
+      "type": "string",
+      "enum": ["draft", "framed", "analysed", "specified", "approved", "consolidated", "handed-off"]
+    },
+
+    "priority": {
+      "type": "string",
+      "enum": ["must", "should", "could"]
+    },
+
+    "roleLevel": {
+      "type": "string",
+      "enum": ["admin", "manager", "contributor", "viewer"]
+    },
+
+    "fileSpec": {
+      "type": "object",
+      "required": ["path", "type"],
+      "properties": {
+        "path": { "type": "string", "description": "Relative file path" },
+        "type": { "type": "string", "description": "File type (Entity, Service, DTO, Repository, Migration, HasData, Constants, ApiController, Page, DashboardPage, Component, ApiClient, ReduxSlice, UnitTests, IntegrationTests, Enum)" },
+        "linkedFRs": { "type": "array", "items": { "type": "string" }, "description": "Linked functional requirement IDs (FR-XXX)" },
+        "linkedUCs": { "type": "array", "items": { "type": "string" }, "description": "Linked use case IDs (UC-XXX)" },
+        "linkedWireframes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Linked wireframe screen identifiers from specification.uiWireframes[].screen. MANDATORY for Page and DashboardPage types."
+        },
+        "wireframeAcceptanceCriteria": {
+          "type": "string",
+          "description": "Acceptance criteria describing how the implementation must match the wireframe layout. MANDATORY for Page and DashboardPage types."
+        },
+        "category": { "type": "string", "enum": ["core", "business"], "description": "SeedData category: core (navigation/permissions) or business (lookup tables)" },
+        "source": { "type": "string", "description": "Source path in feature.json for derivation" },
+        "description": { "type": "string" },
+        "pattern": { "type": "string", "description": "Reference pattern from existing codebase" },
+        "instructions": { "type": "string" },
+        "dashboardRef": { "type": "string", "description": "Reference to specification.dashboards[].code for DashboardPage type files" }
+      }
+    },
+
+    "resource": {
+      "type": "object",
+      "required": ["code", "type", "entity"],
+      "description": "Level 5 (Resource) - a SmartStack React component within a section",
+      "properties": {
+        "code": { "type": "string", "description": "Unique resource code (kebab-case: repair-grid, repair-form)" },
+        "type": {
+          "type": "string",
+          "enum": ["SmartTable", "SmartForm", "DetailCard", "KpiPanel", "KpiCard", "Timeline", "EntitySelect", "Chart", "Map", "FileUpload", "StatusBadge", "ActionMenu", "FilterBar", "Tabs"],
+          "description": "SmartStack React component type"
+        },
+        "entity": { "type": "string", "description": "Primary entity this resource displays/edits" },
+        "parentEntity": { "type": "string", "description": "Parent entity for child tables (e.g., RepairPart parent=Repair)" },
+        "permission": { "type": "string", "description": "Permission required for this resource" },
+        "columns": { "type": "array", "items": { "type": "string" }, "description": "For SmartTable: visible columns" },
+        "fields": {
+          "type": "array",
+          "description": "For SmartForm: form fields",
+          "items": {
+            "type": "object",
+            "required": ["name", "component"],
+            "properties": {
+              "name": { "type": "string" },
+              "component": { "type": "string", "enum": ["Input", "TextArea", "Select", "MultiSelect", "DatePicker", "DateRangePicker", "NumberInput", "Toggle", "EntitySelect", "FileUpload", "RichText", "ColorPicker"] },
+              "source": { "type": "string", "description": "Lookup table entity for Select/MultiSelect" },
+              "required": { "type": "boolean" },
+              "validation": { "type": "string" }
+            }
+          }
+        },
+        "actions": { "type": "array", "items": { "type": "string" }, "description": "Row/item actions (view, edit, delete, etc.)" },
+        "filters": { "type": "array", "items": { "type": "string" }, "description": "Available filter fields" },
+        "kpis": { "type": "array", "items": { "type": "string" }, "description": "For KpiPanel: entity fields to display as KPIs" },
+        "chartType": { "type": "string", "enum": ["bar", "line", "pie", "area", "donut", "stacked-bar"], "description": "For Chart resource" },
+        "dataSource": { "type": "string", "description": "API endpoint or entity for data" }
+      }
+    },
+
+    "suggestion": {
+      "type": "object",
+      "required": ["type", "code", "reason"],
+      "properties": {
+        "type": { "type": "string", "enum": ["module", "section", "integration", "enhancement"] },
+        "code": { "type": "string", "description": "Suggested module/section code (PascalCase)" },
+        "title": { "type": "string" },
+        "reason": { "type": "string", "description": "Why this is suggested based on the current analysis" },
+        "accepted": { "type": ["boolean", "null"], "description": "null = not yet answered, true = accepted, false = rejected" }
+      }
+    },
+
+    "changelogEntry": {
+      "type": "object",
+      "required": ["timestamp", "changes"],
+      "properties": {
+        "step": { "type": "string" },
+        "version": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "author": { "type": "string" },
+        "changes": { "type": "array", "items": { "type": "string" } },
+        "warnings": { "type": "array", "items": { "type": "string" } },
+        "decision": { "type": "string" }
+      }
+    },
+
+    "documentation": {
+      "type": "object",
+      "description": "Documentation requirements captured during BA",
+      "properties": {
+        "userDocRequired": { "type": "boolean", "default": true },
+        "techDocRequired": { "type": "boolean", "default": false },
+        "generatedAt": { "type": ["string", "null"], "format": "date-time" },
+        "status": { "type": "string", "enum": ["pending", "generated", "skipped"], "default": "pending" }
+      }
+    }
+  }
+}

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

@@ -116,7 +116,7 @@ Load these categories in order:
 - ULTRATHINK: Map stakeholders to application roles
 
 **Category 03 - Scope** (`questionnaire/03-scope.md`)
-- Q3.1-Q3.8: MoSCoW prioritization, flows, errors
+- Q3.1-Q3.8: Priority levels (Essentiel/Important/Optionnel/Hors périmètre), flows, errors
 - 2 AskUserQuestion batches
 - ULTRATHINK: Ensure scope items map to modules
 
@@ -202,7 +202,25 @@ Classify per probability/impact:
 - High/Low or Low/High → Medium (monitor)
 - Low/Low → Low (accept)
 
-### 9. Write Cadrage to Feature.json
+### 9. Coverage Matrix (MANDATORY)
+
+BEFORE transitioning to step-02:
+
+1. Re-read the original prompt/brief in its entirety
+2. For EACH distinct feature/requirement mentioned:
+   a. Create an entry in cadrage.coverageMatrix[]
+   b. Assign it to mustHave, shouldHave, couldHave, or outOfScope
+   c. Assign the module that will cover it (or null if cross-cutting)
+3. Present the matrix to the client:
+   "Voici la matrice de couverture de votre brief. {N} fonctionnalités identifiées :"
+   (show as markdown table)
+4. Ask: "Y a-t-il des éléments que j'ai oublié ou mal classé ?"
+5. Iterate until the client confirms
+
+**VALIDATION:** Every line of the original prompt must map to at least one coverageMatrix entry.
+If a feature is in mustHave → it MUST have at least one UC in the corresponding module (verified in step-03).
+
+### 10. Write Cadrage to Feature.json
 
 Use ba-writer to enrich master feature.json:
 
@@ -225,6 +243,7 @@ ba-writer.enrichSection({
     applicationRoles: [{from section 6}],
     risks: [{from section 8}],
     acceptanceCriteria: [{derived from scope}],
+    coverageMatrix: [{from section 9}],
     codebaseContext: {codebase_context}
   }
 })
@@ -232,7 +251,7 @@ ba-writer.enrichSection({
 ba-writer.updateStatus({feature_id}, "framed")
 ```
 
-### 10. Display Summary
+### 11. Display Summary
 
 ```
 ## Cadrage Complete - {feature_id}

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

@@ -18,6 +18,27 @@ next_step: steps/step-03-specify.md OR steps/step-04-consolidation.md (condition
 - ALL communication in `{language}`
 - NEVER skip per-module validation
 - **WIREFRAME RULE:** Every section MUST have a wireframe in `specification.uiWireframes[]`. No section without a validated mockup.
+- **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
+  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
+  The prefix is derived from the module code initials (2-4 chars):
+    UserManagement → UM | VehicleManagement → VM | PartsInventory → PI
+    RepairManagement → RM | MaintenanceSchedule → MS | DataSync → DS
+    Notifications → NT | Dashboard → DB | Orders → OR | Customers → CU
+
+  Patterns:
+    UC-{PREFIX}-{NNN}        → UC-RM-001, UC-PI-003
+    BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-RM-001, BR-CALC-PI-002
+    FR-{PREFIX}-{NNN}        → FR-RM-001
+    OBJ-{PREFIX}-{NNN}       → OBJ-RM-001
+    AC-{PREFIX}-{NNN}        → AC-RM-001
+    RISK-{PREFIX}-{NNN}      → RISK-RM-001
+
+  NEVER use bare IDs (UC-001, BR-VAL-001) in multi-module mode.
+- **SCHEMA CONFORMITY RULE:**
+  ALL data MUST fit within the defined feature-schema.json structure.
+  NEVER create custom top-level fields (KPIDefinitions, ChartConfigurations, etc.)
+  Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
+  If truly needed, use specification.extensions: {} (additionalProperties: true).
 
 ## YOUR TASK
 
@@ -58,6 +79,40 @@ ba-reader.readApplicationContext({feature_id})
 
 Update module status in master: "pending" → "in-progress"
 
+### 2-bis. Coverage Verification (MANDATORY)
+
+> **Before specifying any module, verify that the coverageMatrix from cadrage covers this module.**
+
+```
+ba-reader.readApplicationContext({feature_id})
+→ Read cadrage.coverageMatrix[]
+→ Filter entries where module = {currentModule.code}
+→ Group by category: mustHave, shouldHave, couldHave
+```
+
+Display to client:
+```
+Module {currentModule}: Coverage from original brief
+
+| # | Requirement | Category |
+|---|-------------|----------|
+| 1 | {item} | {category} |
+| ... | ... | ... |
+
+Total: {N} requirements mapped to this module
+  - Must-have: {count}
+  - Should-have: {count}
+  - Could-have: {count}
+```
+
+**VALIDATION:** If mustHave count = 0 AND module is in must priority:
+  → WARNING: "Module {currentModule} is must-priority but has no must-have requirements in coverageMatrix. Verify cadrage coverage."
+
+**POST-SPECIFICATION CHECK (at end of module, before advancing):**
+  For EACH mustHave item in coverageMatrix for this module:
+    → Verify at least 1 UC exists that covers this requirement
+    → If uncovered: BLOCK and ask client to either add a UC or reclassify the requirement
+
 ### 3. Section Walkthrough with Client
 
 > **This is the key interactive phase aligned with the 5-level SmartStack hierarchy.**
@@ -94,6 +149,54 @@ options:
     description: "Tableau de bord avec KPIs, graphiques (Recharts) et métriques clés"
 ```
 
+#### 3a-bis. Structure Sections with Resources (Levels 4 & 5)
+
+For EACH section confirmed in 3a, build the `specification.sections[]` structure:
+
+1. For each resource in the section, determine:
+   - The SmartStack component type (SmartTable, SmartForm, DetailCard, KpiPanel, Chart, Map, Timeline, etc.)
+   - The entity it operates on
+   - Columns/fields based on entity attributes
+   - Permission (inherit from section or more specific)
+   - Available actions
+
+2. Link use cases to sections:
+   - Each UC MUST belong to exactly ONE section
+   - Map UC to section based on the primary action (list → UC-XX-001, create → UC-XX-003, etc.)
+
+3. Link business rules to sections:
+   - Each BR can belong to one or more sections
+   - Map BR based on where it's enforced (validation BR → create/edit section, calc BR → detail section)
+
+4. Build the section object:
+```json
+{
+  "code": "list",
+  "labels": { "fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste" },
+  "route": "/business/{app}/{module}/list",
+  "icon": "list",
+  "permission": "business.{app}.{module}.read",
+  "wireframe": "{module}-list",
+  "useCases": ["UC-{PREFIX}-001", "UC-{PREFIX}-002"],
+  "businessRules": ["BR-VAL-{PREFIX}-001"],
+  "resources": [
+    {
+      "code": "{module}-grid",
+      "type": "SmartTable",
+      "entity": "{MainEntity}",
+      "permission": "business.{app}.{module}.read",
+      "columns": ["name", "status", "createdAt"],
+      "actions": ["view", "edit", "delete"],
+      "filters": ["status", "dateRange"]
+    }
+  ]
+}
+```
+
+5. Write `specification.sections[]` via ba-writer.enrichSection()
+
+**VALIDATION:** Every UC must appear in exactly one section.useCases[]. No orphan UCs.
+
 #### 3b. For Each Section: Generate MANDATORY ASCII Mockup
 
 > **BLOCKING RULE:** Every section MUST have a wireframe. No section proceeds to entity definition (step 6) without a validated mockup stored in `specification.uiWireframes[]`.
@@ -156,6 +259,32 @@ After client validates the mockup, map each wireframe element to a SmartStack Re
 
 Store the component mapping alongside the wireframe to ensure downstream skills use the correct components.
 
+#### 3b-ter. Generate Structural Layout
+
+For EACH wireframe generated in 3b, generate a `layout` object alongside the ASCII mockup:
+
+1. From the ASCII mockup, extract the visual regions (header, toolbar, main content, sidebar, etc.)
+2. For each region, map the visual elements to SmartStack component types
+3. Build the layout structure:
+```json
+{
+  "type": "page",
+  "regions": [
+    { "id": "toolbar", "position": "top", "components": [
+      { "type": "FilterBar", "resourceRef": "{module}-filters" },
+      { "type": "ActionMenu", "resourceRef": "{module}-actions", "permission": "business.{app}.{module}.create" }
+    ]},
+    { "id": "content", "position": "main", "span": 12, "components": [
+      { "type": "SmartTable", "resourceRef": "{module}-grid" }
+    ]}
+  ]
+}
+```
+4. Cross-validate: each component in layout.regions[].components[] MUST have a corresponding resource in sections[].resources[]
+5. Write layout alongside mockup in uiWireframes[]
+
+**RULE:** The layout is the source of truth for ralph-loop. The mockup is for human validation only.
+
 #### 3c. Identify Resources per Section
 
 For each section, identify what resources/components are needed:

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

@@ -175,7 +175,40 @@ options:
     description: "Le Manager devrait aussi pouvoir approuver les factures"
 ```
 
-### 4. End-to-End Flows
+### 4. Semantic Validation (MANDATORY)
+
+For EACH module feature.json, execute these checks:
+
+| # | Check | Rule | Severity |
+|---|-------|------|----------|
+| 1 | Permission orpheline | Every permissionMatrix.permissions[].path is used by at least one useCases[].permission | WARNING |
+| 2 | UC sans FR | Every useCases[].id is referenced by at least one functionalRequirements[].linkedUseCases[] | WARNING |
+| 3 | Entity sans endpoint | Every entities[].name has at least one endpoint in apiEndpoints[] | WARNING |
+| 4 | UC sans scenario | Every useCases[].mainScenario has at least 2 steps | WARNING |
+| 5 | Role sans permissions | Every applicationRole has at least one entry in roleAssignments[] | WARNING |
+| 6 | Navigation sans traduction | Every navigation.entries[].code has translations in 4 languages in seedDataCore.navigationTranslations[] | ERROR |
+| 7 | LifeCycle terminal | Every lifeCycles[].states[] has at least one state with isTerminal: true | WARNING |
+| 8 | Schema conformity | No custom fields outside defined schema (no KPIDefinitions, ChartConfigurations, etc.) | ERROR |
+| 9 | Wireframe coverage | Every navigation section has a corresponding uiWireframes[].screen | ERROR |
+| 10 | Doublon entity | No entity with same name in two different modules (unless shared via dependencyGraph) | ERROR |
+
+Store results in consolidation.semanticChecks[]:
+```json
+{
+  "check": "permission-orpheline",
+  "module": "RepairManagement",
+  "status": "PASS|WARNING|ERROR",
+  "details": "Permission business.freebike.repairmanagement.export not referenced by any UC",
+  "autoFixed": false
+}
+```
+
+**Blocking rule:**
+- 0 ERROR → PASS
+- ≥1 ERROR → BLOCK (fix before handoff, ask user for each)
+- WARNING only → PASS with user notification
+
+### 5. End-to-End Flows
 
 Identify business processes that span multiple modules:
 
@@ -206,7 +239,7 @@ Customer ──[read]──→ Order ──[create]──→ Order ──[approv
   Contributor         Contributor          Manager               System                Manager
 ```
 
-### 5. Global Risk Assessment
+### 6. Global Risk Assessment
 
 Evaluate application-level risks:
 
@@ -219,7 +252,7 @@ Evaluate application-level risks:
 | E2E flow length | {max steps} | ≤8 | PASS/WARNING |
 | Permission paths | {total} | ≤100 | PASS/WARNING |
 
-### 6. Consolidation Summary
+### 7. Consolidation Summary
 
 Display comprehensive summary:
 ```
@@ -252,7 +285,7 @@ Display comprehensive summary:
 ═══════════════════════════════════════════════════════════
 ```
 
-### 7. Final Client Approval (BLOCKING)
+### 8. Final Client Approval (BLOCKING)
 
 Ask via AskUserQuestion:
 ```
@@ -273,7 +306,7 @@ IF "Réviser un module":
 IF "Modifier les interactions":
   Re-enter section 2-4 of this step
 
-### 8. Write Consolidation
+### 9. Write Consolidation
 
 ```
 ba-writer.enrichSection({