@atlashub/smartstack-cli 3.9.0 → 3.12.0

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

@@ -46,7 +46,7 @@ Validate the module specification for completeness and consistency, write to fea
 | validations | 1 | PASS/FAIL |
 | messages | 4 | PASS/FAIL |
 | lifeCycles | 1 (if entity has status) | PASS/FAIL |
-| seedDataCore | 5 sections present | PASS/FAIL (BLOCKING) |
+| seedDataCore | 7 sections present | PASS/FAIL (BLOCKING) |
 
 #### 9b. Consistency Checks
 
@@ -98,7 +98,7 @@ ba-writer.enrichSection({
       { "section": "useCases", "count": {count}, "minimum": 2, "status": "PASS|FAIL" },
       { "section": "functionalRequirements", "count": {count}, "minimum": 4, "status": "PASS|FAIL" },
       { "section": "wireframes", "count": {count}, "minimum": {section_count}, "status": "PASS|FAIL" },
-      { "section": "seedDataCore", "count": 5, "minimum": 5, "status": "PASS|FAIL" }
+      { "section": "seedDataCore", "count": 7, "minimum": 7, "status": "PASS|FAIL" }
     ],
     consistencyChecks: [
       { "check": "UC-FR linkage", "passed": {n}, "warnings": {n}, "errors": {n}, "status": "PASS|FAIL" },
@@ -126,6 +126,39 @@ ba-writer.enrichSection({
 })
 ```
 
+#### 9f. Module Specification Checklist (BLOCKING)
+
+> **CRITICAL:** This checklist MUST be FULLY COMPLETED before marking module status = "specified".
+
+**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)
+- Seed Data (2 checks) | API Endpoints (2 checks) | Validations (1 check) | Gherkin (1 check)
+
+```javascript
+const blockingFailures = checks.filter(c => c.blocking && c.status === "FAIL");
+
+IF blockingFailures.length > 0:
+  // CONDITIONAL LOAD: Only load detailed checklist on validation failure
+  Read references/validation-checklist.md
+  Display:
+    - Full validation logic for FAILED checks
+    - Exact requirements (minimums, patterns, formats)
+    - Fix recommendations for each failure
+
+  BLOCKING ERROR: Module specification incomplete
+  → Fix all failures before proceeding
+
+ELSE:
+  All blocking checks passed ✓
+  Display: "{warnings_count} warnings (non-blocking)"
+  → Proceed to mark module as "specified"
+```
+
+**Optimization:** The detailed 280-line validation-checklist.md is loaded **only when validation fails** (saves ~10,000 tokens on success path).
+
 ---
 
 ### 10. Module Summary with Roles & Permissions
@@ -201,7 +234,7 @@ ba-writer.enrichSection({
     functionalRequirements: [{id, statement, priority, linkedRules, linkedUseCases, acceptanceCriteria}],  // 8c
     permissionMatrix: {permissions: [], roleAssignments: []},     // 8d
     navigation: {entries: []},                                    // 8e
-    seedDataCore: {navigationModules, navigationTranslations, permissions, rolePermissions, permissionConstants},  // 8f
+    seedDataCore: {navigationModules, navigationSections, navigationResources, navigationTranslations, permissions, rolePermissions, permissionConstants},  // 8f (7 arrays)
     gherkinScenarios: [{feature, scenarios: [{name, tags, given, when, then}]}],  // 8g
     validations: [{entity, field, rules, errorMessageKey}],       // 8h
     messages: [{code, type, title, message, i18nKey}],            // 8i

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

@@ -1,462 +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"
-    }
-  ]
-}
-```
-
-### 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"
-  ]
-}
-```
+The consolidation process will execute in sequence:
+- step-04a-collect → step-04b-analyze → step-04c-decide → step-05a-handoff
 
 ---
 
-## SINGLE-MODULE MODE
+## Why Refactored?
 
-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
+**Before:** 628 lines in single file (exceeded 400-line recommendation)
 
----
+**After:** 3 focused files (~200-280 lines each)
 
-## 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 |
-
----
-
-## WORKFLOW STATE SAVE (for resume support)
-
-After consolidation approval, update workflow state to enable resume if context is exhausted during handoff steps:
-
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "metadata.workflow",
-  data: {
-    lastCompletedStep: "step-04-consolidation",
-    readyForHandoff: true
-  }
-})
-```
-
-> **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...**