@atlashub/smartstack-cli 3.9.0 → 3.12.0

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

@@ -0,0 +1,304 @@
+---
+name: step-04a-collect
+description: Collect module summaries and cross-module interactions
+model: opus
+next_step: steps/step-04b-analyze.md
+---
+
+> **Context files:** `_shared.md` | `_suggestions.md`
+
+# Step 4a: Collect - Module Summaries & Cross-Module Interactions
+
+## MANDATORY EXECUTION RULES
+- ALWAYS load summaries of ALL completed modules
+- NEVER duplicate module content - work with summaries only
+- This step auto-validates for single-module (trivial consolidation)
+
+## YOUR TASK
+Collect module summaries and identify all cross-module interactions (FK references, shared entities, events, shared data).
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Read Module Summaries
+
+```
+ba-reader.getCompletedModulesSummary({feature_id})
+→ For each module: code, entities[], key BRs, permissions[], dependencies
+→ Max 100 lines per module summary
+
+ba-reader.readApplicationContext({feature_id})
+→ cadrage.applicationRoles, modules[], dependencyGraph
+```
+
+IF status already "consolidated":
+  Display: "Consolidation already completed. Loading step-05a-handoff."
+  Load: steps/step-05a-handoff.md
+  STOP
+
+### 2. Cross-Module Interactions
+
+**2a. Foreign Key References**
+
+For each dependency edge in dependencyGraph:
+```json
+{
+  "from": "Orders",
+  "to": "Customers",
+  "type": "FK",
+  "references": [
+    {
+      "sourceEntity": "Order",
+      "sourceField": "CustomerId",
+      "targetEntity": "Customer",
+      "targetField": "Id",
+      "cardinality": "N:1",
+      "cascadeDelete": false,
+      "required": true
+    }
+  ]
+}
+```
+
+Verify each FK reference exists in the corresponding module's entities.
+IF missing → WARNING + ask user to confirm or add.
+
+**2b. Shared Entities**
+
+Detect entities referenced by multiple modules:
+```json
+{
+  "sharedEntities": [
+    {
+      "entity": "Customer",
+      "definedIn": "Customers",
+      "referencedBy": ["Orders", "Invoices"],
+      "referenceType": "FK"
+    }
+  ]
+}
+```
+
+**2c. Event-Based Interactions**
+
+Identify event flows between modules:
+```json
+{
+  "events": [
+    {
+      "producer": "Orders",
+      "event": "OrderApproved",
+      "consumers": ["Invoices"],
+      "description": "When an order is approved, an invoice is auto-generated"
+    }
+  ]
+}
+```
+
+**2d. Shared Reference Data**
+
+Identify shared lookup/reference tables:
+```json
+{
+  "sharedReferenceData": [
+    {
+      "table": "Currency",
+      "usedBy": ["Orders", "Invoices"],
+      "owner": "shared"
+    }
+  ]
+}
+```
+
+**2e. Cross-Module Reference Validation (ENHANCED)**
+
+> **CRITICAL:** Verify ALL cross-module entity references are resolvable.
+> **Purpose:** Prevent broken FK references and runtime errors in ralph-loop.
+
+**Process:**
+
+1. **Build Entity Registry:**
+   ```javascript
+   const entityRegistry = {};
+   for (const module of completedModules) {
+     entityRegistry[module.code] = {
+       entities: module.analysis.entities.map(e => ({
+         name: e.name,
+         attributes: e.attributes.map(a => a.name),
+         pk: e.attributes.find(a => a.name === "Id" || a.unique)?.name || "Id"
+       }))
+     };
+   }
+   ```
+
+2. **Extract Cross-Module References:**
+
+   For EACH module, scan all entity relationships:
+   ```javascript
+   for (const entity of module.analysis.entities) {
+     for (const rel of entity.relationships) {
+       // Detect cross-module reference
+       if (rel.target.includes(".")) {
+         // Format: "ModuleName.EntityName.FieldName" or "ModuleName.EntityName"
+         const [targetModule, targetEntity, targetField] = rel.target.split(".");
+
+         // Validate: target module exists
+         if (!entityRegistry[targetModule]) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent module "${targetModule}"`);
+         }
+
+         // Validate: target entity exists in target module
+         const targetModuleEntities = entityRegistry[targetModule].entities;
+         const resolvedEntity = targetModuleEntities.find(e => e.name === targetEntity);
+         if (!resolvedEntity) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent entity "${targetEntity}" in module "${targetModule}"`);
+         }
+
+         // Validate: target field exists (if specified)
+         if (targetField && !resolvedEntity.attributes.includes(targetField)) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent field "${targetField}" on "${targetModule}.${targetEntity}"`);
+         }
+
+         // Record valid reference
+         crossModuleReferences.push({
+           sourceModule: module.code,
+           sourceEntity: entity.name,
+           sourceField: rel.sourceField || `${targetEntity}Id`,
+           targetModule,
+           targetEntity,
+           targetField: targetField || resolvedEntity.pk,
+           type: rel.type,
+           cardinality: rel.cardinality || "N:1",
+           status: "RESOLVED"
+         });
+       }
+     }
+   }
+   ```
+
+3. **Validate Dependency Graph Alignment:**
+
+   ```javascript
+   // For each cross-module reference, verify dependency edge exists
+   for (const ref of crossModuleReferences) {
+     const dependencyExists = dependencyGraph.edges.find(edge =>
+       edge.from === ref.sourceModule && edge.to === ref.targetModule
+     );
+
+     if (!dependencyExists) {
+       WARNING(`Dependency missing: ${ref.sourceModule} → ${ref.targetModule}`);
+       WARNING(`Reason: ${ref.sourceEntity}.${ref.sourceField} references ${ref.targetModule}.${ref.targetEntity}`);
+
+       // Auto-fix: add missing dependency edge
+       dependencyGraph.edges.push({
+         from: ref.sourceModule,
+         to: ref.targetModule,
+         type: "FK",
+         reason: `${ref.sourceEntity}.${ref.sourceField} → ${ref.targetEntity}`
+       });
+
+       // Recalculate topological order
+       topologicalOrder = calculateTopologicalOrder(dependencyGraph);
+     }
+   }
+   ```
+
+4. **Display Cross-Module Reference Map:**
+
+   ```
+   ═══════════════════════════════════════════════════════════════
+     CROSS-MODULE REFERENCES VALIDATED
+   ═══════════════════════════════════════════════════════════════
+
+   | Source Module | Source Entity | Target | Type | Status |
+   |---------------|---------------|--------|------|--------|
+   | TimeTracking | TimeEntry | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+   | LeaveManagement | LeaveRequest | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+   | AbsenceManagement | Absence | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+   | Reporting | ProjectReport | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+
+   Total: {count} cross-module references
+   All references RESOLVED ✓
+   ═══════════════════════════════════════════════════════════════
+   ```
+
+5. **Detect Circular Dependencies:**
+
+   ```javascript
+   const cycles = detectCycles(dependencyGraph);
+
+   if (cycles.length > 0) {
+     BLOCKING_ERROR("Circular dependencies detected:");
+     for (const cycle of cycles) {
+       ERROR(`  ${cycle.join(" → ")}`);
+     }
+
+     ACTIONS:
+     1. Review module dependencies
+     2. Break cycles by:
+        - Moving shared entities to a separate "Core" module
+        - Using event-driven communication instead of FK
+        - Removing unnecessary dependencies
+     3. Re-run step-02 decomposition with fixed dependencies
+
+     STOP - DO NOT PROCEED TO HANDOFF
+   }
+   ```
+
+6. **Store Cross-Module Interaction Data:**
+
+   ```javascript
+   ba-writer.enrichSection({
+     featureId: {feature_id},
+     section: "consolidation",
+     data: {
+       crossModuleInteractions: crossModuleReferences.map(ref => ({
+         fromModule: ref.sourceModule,
+         toModule: ref.targetModule,
+         interactionType: "FK_REFERENCE",
+         description: `${ref.sourceEntity}.${ref.sourceField} → ${ref.targetModule}.${ref.targetEntity}.${ref.targetField}`,
+         entities: [ref.sourceEntity, ref.targetEntity],
+         cardinality: ref.cardinality,
+         status: ref.status
+       }))
+     }
+   });
+   ```
+
+**Success Criteria:**
+- ✓ All cross-module references resolved
+- ✓ Dependency graph aligned with actual references
+- ✓ No circular dependencies
+- ✓ Topological order valid
+
+**Failure Handling:**
+- BLOCKING errors for unresolved references
+- Auto-fix missing dependency edges (with warning)
+- Manual intervention required for circular dependencies
+
+---
+
+## SINGLE-MODULE MODE
+
+When only 1 module:
+1. Skip cross-module interactions (no other modules)
+2. Display: "Module unique - interactions cross-module non applicables ✓"
+3. Proceed directly to step-04c-decide.md (skip analysis)
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Full module feature.json files |
+| Module summaries (100 lines each) | Questionnaires |
+| Master feature.json | Templates |
+| cadrage section | React viewer files |
+
+---
+
+## NEXT STEP
+
+Load: `./step-04b-analyze.md`

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

@@ -0,0 +1,239 @@
+---
+name: step-04b-analyze
+description: Analyze permission coherence, semantic validation, E2E flows, and global risks
+model: opus
+next_step: steps/step-04c-decide.md
+---
+
+> **Context files:** `_shared.md`
+
+# Step 4b: Analyze - Permission Coherence & Validation
+
+## MANDATORY EXECUTION RULES
+- ALWAYS validate permission coherence across modules
+- ALWAYS execute semantic validation checks
+- E2E flows are OPTIONAL (informational only)
+
+## YOUR TASK
+Validate permission coherence, execute semantic checks, identify E2E business flows, and assess global application risks.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 3. Permission Coherence
+
+> **All modules MUST use the same application-level roles.**
+
+**3a. Role Consistency**
+
+Verify all modules use the applicationRoles defined in cadrage:
+```
+FOR each module in completedModules:
+  FOR each role in module.specification.permissionMatrix.roles:
+    IF role NOT IN cadrage.applicationRoles → ERROR
+```
+
+**3b. Permission Path Format**
+
+Verify all permission paths follow the pattern:
+`business.{app}.{module}.{resource}.{action}`
+
+Check for:
+- Inconsistent app prefix → ERROR
+- Missing module segment → ERROR
+- Shortcut paths (not full format) → ERROR
+
+**3c. Role Hierarchy Coherence**
+
+Verify the role hierarchy is respected across all modules:
+```
+Admin ⊃ Manager ⊃ Contributor ⊃ Viewer
+
+FOR each module:
+  IF Admin has fewer permissions than Manager → ERROR
+  IF Manager has fewer permissions than Contributor → ERROR
+  IF Contributor has fewer permissions than Viewer → ERROR
+```
+
+**3d. Permission Conflicts**
+
+Detect conflicting permission assignments:
+```json
+{
+  "conflicts": [
+    {
+      "role": "Manager",
+      "module1": "Orders",
+      "permission1": "business.sales.orders.approve",
+      "module2": "Invoices",
+      "permission2": "business.sales.invoices.approve",
+      "issue": "Manager can approve orders but not invoices - is this intentional?"
+    }
+  ]
+}
+```
+
+Present conflicts to user via AskUserQuestion:
+```
+question: "Le Manager peut approuver les commandes mais pas les factures. Est-ce intentionnel ?"
+header: "Permissions"
+options:
+  - label: "Oui, intentionnel"
+    description: "Les factures nécessitent un niveau d'approbation supérieur"
+  - label: "Non, corriger"
+    description: "Le Manager devrait aussi pouvoir approuver les factures"
+```
+
+### 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 |
+| 11 | Permission fantome | Every action used in applicationRoles pattern (read, create, update, delete, assign, export, approve) MUST exist as a permission path in permissionMatrix.permissions[].action for at least one module | ERROR |
+| 12 | Dashboard coverage | If cadrage mentions dashboard for a module OR navigation includes "dashboard" section, then specification.dashboards[] MUST NOT be empty | WARNING |
+| 13 | Permission-UC alignment | Every permission.action (except "read" and wildcard "*") MUST have at least one UC where that permission is referenced in useCases[].permission | WARNING |
+
+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
+
+### 4-bis. Structural Schema Conformity Check (MANDATORY)
+
+> **Post-generation validation.** After semantic checks, verify ALL module feature.json files conform to JSON schema.
+
+See [references/consolidation-structural-checks.md](../references/consolidation-structural-checks.md) for the full 6-category structural check:
+- **A.** Required Sections Presence (18 sections)
+- **B.** Field Name Conformity (forbidden vs correct fields)
+- **C.** ID Pattern Conformity (BR, UC, FR, Permissions)
+- **D.** Cross-Module ID Uniqueness
+- **E.** Wireframe Layout Completeness
+- **F.** SeedDataCore Translation Coverage
+
+**Blocking rule:** 0 ERROR → PASS. ≥1 ERROR → BLOCK (attempt auto-fix, re-write, re-check).
+
+### 5. End-to-End Flows
+
+Identify business processes that span multiple modules:
+
+```json
+{
+  "e2eFlows": [
+    {
+      "name": "Order to Invoice",
+      "steps": [
+        { "module": "Customers", "action": "Customer exists", "permission": "customers.read" },
+        { "module": "Products", "action": "Products selected", "permission": "products.read" },
+        { "module": "Orders", "action": "Order created", "permission": "orders.create" },
+        { "module": "Orders", "action": "Order approved", "permission": "orders.approve" },
+        { "module": "Invoices", "action": "Invoice generated", "permission": "invoices.create" },
+        { "module": "Invoices", "action": "Invoice sent", "permission": "invoices.update" }
+      ],
+      "actors": ["Contributor (create)", "Manager (approve)"],
+      "data": "Customer → Order → OrderLines (Products) → Invoice → InvoiceLines"
+    }
+  ]
+}
+```
+
+Display each E2E flow as a diagram:
+```
+Customer ──[read]──→ Order ──[create]──→ Order ──[approve]──→ Invoice ──[create]──→ Invoice ──[send]──→
+  (Customers)         (Orders)            (Orders)              (Invoices)            (Invoices)
+  Contributor         Contributor          Manager               System                Manager
+```
+
+### 6. Global Risk Assessment
+
+Evaluate application-level risks:
+
+| Risk | Metric | Threshold | Status |
+|------|--------|-----------|--------|
+| Total entities | {sum across modules} | ≤20 | PASS/WARNING |
+| Total BRs | {sum across modules} | ≤50 | PASS/WARNING |
+| Cross-module dependencies | {edge count} | ≤10 | PASS/WARNING |
+| Shared entities | {count} | ≤5 | PASS/WARNING |
+| E2E flow length | {max steps} | ≤8 | PASS/WARNING |
+| Permission paths | {total} | ≤100 | PASS/WARNING |
+
+### 7. Consolidation Summary
+
+Display comprehensive summary:
+```
+═══════════════════════════════════════════════════════════
+  CONSOLIDATION - {application_name}
+═══════════════════════════════════════════════════════════
+
+### Modules ({count})
+| Module | Entités | BRs | UCs | Complexité |
+|--------|---------|-----|-----|------------|
+{for each module}
+
+### Interactions Cross-Module
+- FK References: {count}
+- Shared Entities: {count}
+- Events: {count}
+- Shared Data: {count}
+
+### Permissions
+- Roles: {count} (coherent: ✓/✗)
+- Total paths: {count}
+- Conflicts resolved: {count}
+
+### E2E Flows
+{for each flow: name, modules involved, actors}
+
+### Risques Globaux
+{risk assessment table}
+
+═══════════════════════════════════════════════════════════
+```
+
+---
+
+## SINGLE-MODULE MODE
+
+When only 1 module:
+1. Skip permission coherence check (only one module)
+2. Skip E2E flows (single module)
+3. Execute semantic validation (still required)
+4. Auto-approve global risks (no cross-module complexity)
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Full module feature.json files |
+| Module summaries | Questionnaires |
+| consolidation section (from step-04a) | Templates |
+
+---
+
+## NEXT STEP
+
+Load: `./step-04c-decide.md`