@atlashub/smartstack-cli 3.10.0 → 3.13.0

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

@@ -1,628 +1,43 @@
 ---
 name: step-04-consolidation
-description: Cross-module consolidation - interactions, permission coherence, E2E flows, final approval
+description: Cross-module consolidation - REDIRECTS to step-04a (refactored into 3 sub-steps)
 model: opus
-next_step: steps/step-05a-handoff.md
+next_step: steps/step-04a-collect.md
 ---
 
-> **Context files:** `_shared.md` | `_suggestions.md`
+> **NOTICE:** This step has been refactored into 3 sub-steps for better context management.
 
-# Step 4: Consolidation
+# Step 4: Consolidation (Entry Point)
 
-## MANDATORY EXECUTION RULES
-- ALWAYS load summaries of ALL completed modules
-- NEVER duplicate module content - work with summaries only
-- ALWAYS validate permission coherence across modules
-- This step auto-validates for single-module (trivial consolidation)
-- Final client approval is BLOCKING before handoff
+This step has been divided into 3 focused sub-steps:
 
-## YOUR TASK
-Consolidate all specified modules into a coherent application. Detect cross-module interactions, verify permission coherence, trace E2E flows, and obtain final client approval.
+1. **step-04a-collect.md** - Collect module summaries and cross-module interactions
+2. **step-04b-analyze.md** - Analyze permissions, validation, E2E flows, and risks
+3. **step-04c-decide.md** - Obtain final approval and write consolidation
 
 ---
 
-## EXECUTION SEQUENCE
+## Automatic Redirect
 
-### 1. Read Module Summaries
+**Loading:** `./step-04a-collect.md`
 
-```
-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 next step."
-  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
-
-### 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 |
-
-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}
-
-═══════════════════════════════════════════════════════════
-```
-
-### 8. Final Client Approval (BLOCKING)
-
-Ask via AskUserQuestion:
-```
-question: "La spécification complète de l'application est prête. Validez-vous l'ensemble ?"
-header: "Approbation"
-options:
-  - label: "Approuvé"
-    description: "Passer au handoff pour la phase d'implémentation"
-  - label: "Réviser un module"
-    description: "Retourner à la spécification d'un module spécifique"
-  - label: "Modifier les interactions"
-    description: "Ajuster les interactions cross-module"
-```
-
-IF "Réviser un module":
-  Ask which module → set currentModuleIndex to that module → load step-03a-data.md
-
-IF "Modifier les interactions":
-  Re-enter section 2-4 of this step
-
-### 9. Write Consolidation
-
-> **STRUCTURE CARD: consolidation** — Must match `application-schema.json`. Follow this structure exactly.
-
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "consolidation",
-  data: {
-    crossModuleInteractions: [
-      {
-        "fromModule": "Orders",
-        "toModule": "Customers",
-        "interactionType": "FK-reference|event-publish|event-subscribe|shared-lookup|cascade-delete|cascade-update",
-        "description": "Order references customer via FK",
-        "entities": ["Order→Customer"]
-      }
-    ],
-    sharedEntities: [
-      {
-        "entity": "Customer",
-        "ownerModule": "Customers",
-        "referencedBy": ["Orders", "Invoices"],
-        "sharedFields": ["code", "name"]
-      }
-    ],
-    permissionCoherence: {
-      "rolesConsistent": true,
-      "pathFormatConsistent": true,
-      "hierarchyRespected": true,
-      "conflicts": [],
-      "warnings": []
-    },
-    e2eFlows: [
-      {
-        "name": "Order to Invoice",
-        "modules": ["Customers", "Orders", "Invoices"],
-        "steps": [
-          { "module": "Orders", "action": "Create order", "permission": "business.sales.orders.create", "dataFlow": "Customer → Order" }
-        ]
-      }
-    ],
-    globalRiskAssessment: [
-      {
-        "risk": "Cross-module coupling complexity",
-        "category": "coupling|complexity|dependency-chain|security|scope",
-        "severity": "critical|high|medium|low",
-        "mitigation": "Event-driven communication instead of direct FK"
-      }
-    ],
-    semanticChecks: [
-      { "check": "permission-orpheline", "status": "PASS|WARNING|ERROR", "details": "..." },
-      { "check": "uc-sans-fr", "status": "PASS|WARNING|ERROR", "details": "..." },
-      { "check": "wireframe-coverage", "status": "PASS|WARNING|ERROR", "details": "..." }
-    ],
-    decision: {
-      "approved": true,
-      "reason": "All cross-module validations passed",
-      "approvedBy": "Client",
-      "approvedAt": "{ISO timestamp}"
-    }
-  }
-})
-
-ba-writer.updateStatus({feature_id}, "consolidated")
-```
-
-> **STRUCTURE DIFFERENCES FROM OLD FORMAT:**
-> - `crossModuleInteractions` is a FLAT ARRAY (not `{fkReferences, sharedEntities, events}` nested object)
-> - `sharedEntities` is TOP-LEVEL (not nested inside crossModuleInteractions)
-> - `decision` is an OBJECT with `approved`, `reason`, `approvedBy`, `approvedAt` (not `clientApproval` string)
-> - `globalRiskAssessment` is an ARRAY of risk objects (not `{totalEntities: {value, threshold}}`)
-
-Add changelog entry:
-```json
-{
-  "step": "step-04-consolidation",
-  "timestamp": "...",
-  "changes": [
-    "Cross-module interactions: X FK, Y events, Z shared entities",
-    "Permission coherence: validated ({count} paths, {conflicts} conflicts resolved)",
-    "E2E flows: {count} identified",
-    "Global risk: {level}",
-    "Client approval: APPROVED"
-  ]
-}
-```
-
----
-
-## SINGLE-MODULE MODE
-
-When only 1 module:
-1. Skip cross-module interactions (no other modules)
-2. Skip permission coherence check (only one module)
-3. Skip E2E flows (single module)
-4. Auto-approve (no cross-module concerns)
-5. Write minimal consolidation section
-6. Display: "Module unique - consolidation automatique ✓"
-7. Proceed to step-05a-handoff.md
-
----
-
-## 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 |
+The consolidation process will execute in sequence:
+- step-04a-collect → step-04b-analyze → step-04c-decide → step-05a-handoff
 
 ---
 
-## WORKFLOW STATE SAVE (for resume support)
+## Why Refactored?
 
-After consolidation approval, update workflow state to enable resume if context is exhausted during handoff steps:
+**Before:** 628 lines in single file (exceeded 400-line recommendation)
 
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "metadata.workflow",
-  data: {
-    lastCompletedStep: "step-04-consolidation",
-    readyForHandoff: true
-  }
-})
-```
+**After:** 3 focused files (~200-280 lines each)
 
-> **Why:** Steps 05a-05b arrive late in the conversation when context may be near exhaustion.
-> If BA is interrupted during handoff, the user can resume with `/business-analyse` which will
-> detect `lastCompletedStep: "step-04-consolidation"` and resume directly at step-05a.
+**Benefits:**
+- Better context management
+- Clearer separation of concerns (collect → analyze → decide)
+- Easier to resume from specific consolidation phase
+- Reduced cognitive load per step
 
 ---
 
-## NEXT STEP
-
-Load: `./step-05a-handoff.md`
+**Proceeding to step-04a-collect.md...**