@atlashub/smartstack-cli 3.0.0 → 3.2.0

package/templates/skills/business-analyse/steps/step-05-handoff.md

@@ -917,8 +917,10 @@ Status journey: analyze → consolidate → **handed-off**
 
 ### 9d. Deploy Interactive HTML Document (MANDATORY)
 
-> **The interactive HTML document is deployed to the project for client-facing review.**
-> It allows clients to review, edit, and enrich the business analysis directly in their browser.
+> **The interactive HTML document is deployed to the project PRE-POPULATED with ALL analysis data.**
+> The client opens it in a browser and sees the complete analysis (cadrage, modules, entities, UCs, BRs, wireframes, permissions, consolidation).
+> The client can then review, edit, enrich, and export modifications as JSON.
+> That JSON can be re-imported via `/business-analyse -x` to update the feature.json.
 
 **Source:** `html/ba-interactive.html` (relative to skill root = `~/.claude/skills/business-analyse/html/`)
 
@@ -926,27 +928,318 @@ Status journey: analyze → consolidate → **handed-off**
 
 **Deployment steps:**
 
+#### Step 1: Read source data
+
 1. Read the HTML template from skill directory
-2. Replace template placeholders with actual values:
-   - `{{APPLICATION_NAME}}` → `{application_name}`
-   - `{{APPLICATION_ID}}` → `{feature_id}`
-   - `{{VERSION}}` → `{version}`
-   - `{{CREATED_AT}}` → `{ISO timestamp}`
-3. Write the populated HTML to the output directory
-4. Display deployment confirmation:
+2. Read the master feature.json (application level)
+3. Read EACH module feature.json (module level)
+
+#### Step 2: Build FEATURE_DATA object
+
+> **CRITICAL:** The HTML `data` object MUST be pre-populated with ALL analysis data.
+> An empty data object is a **BUG** — the client would see a blank page.
+
+Build a JSON object following this **exact mapping** from feature.json to the HTML data model:
+
+```javascript
+{
+  metadata: {
+    applicationName: master.metadata.application,       // e.g. "RH"
+    applicationId: master.id,                           // e.g. "FEAT-001"
+    version: master.version,                            // e.g. "1.0"
+    createdAt: master.metadata.createdAt,
+    lastModified: master.metadata.updatedAt
+  },
+  cadrage: {
+    problem: {
+      description: master.cadrage.problem,              // string → problem.description
+      trigger: master.cadrage.trigger,                  // string → problem.trigger
+      impactedPeople: "",                               // not in feature.json, client fills
+      history: "",
+      consequences: ""
+    },
+    current: {
+      tools: master.cadrage.asIs,                       // string → current.tools
+      steps: [],                                        // client can add process steps
+      painPoints: master.cadrage.stakeholders
+        .flatMap(s => s.painPoints || []).join("\n"),    // aggregate all painPoints
+      errors: ""
+    },
+    vision: {
+      changes: master.cadrage.toBe,                     // string → vision.changes
+      results: master.cadrage.acceptanceCriteria
+        .map(ac => ac.criterion).join("\n"),             // AC → results (one per line)
+      successSign: ""
+    },
+    stakeholders: master.cadrage.stakeholders.map(s => ({
+      role: s.role,
+      function: s.function || "",
+      tasks: s.tasks || [],
+      frequency: mapFrequency(s.frequency),             // "Quotidien"→"daily", etc.
+      access: mapAccess(s.involvement),                 // "decision-maker"→"admin", "end-user"→"contributor"
+      frustrations: (s.painPoints || []).join("\n")
+    })),
+    scope: {
+      vital: (master.cadrage.globalScope.mustHave || [])
+        .map(item => ({ name: item, description: "" })),      // string[] → {name,description}[]
+      important: (master.cadrage.globalScope.shouldHave || [])
+        .map(item => ({ name: item, description: "" })),
+      optional: (master.cadrage.globalScope.couldHave || [])
+        .map(item => ({ name: item, description: "" })),
+      excluded: (master.cadrage.globalScope.outOfScope || [])
+        .map(item => ({ name: item, description: "" }))
+    },
+    risks: (master.cadrage.risks || []).map(r => ({
+      description: r.description,
+      probability: r.probability,                       // "high" | "medium" | "low"
+      impact: r.impact,
+      mitigation: r.mitigation || ""
+    })),
+    assumptions: "",
+    success: {
+      definition: (master.cadrage.acceptanceCriteria || [])
+        .map(ac => ac.criterion).join("\n"),
+      metrics: "",
+      timeline: "",
+      minimumConditions: ""
+    }
+  },
+  modules: master.modules.map(m => ({
+    code: m.code,
+    name: m.code,                                       // module code as name
+    description: m.description || "",
+    featureType: m.featureType || "data-centric",
+    priority: m.priority || "must",
+    entities: m.entities || [],
+    status: m.status || "handed-off"
+  })),
+  dependencies: (master.dependencyGraph?.edges || []).map(e => ({
+    from: e.from,
+    to: e.to,
+    description: e.description || ""
+  })),
+  moduleSpecs: {
+    // FOR EACH module: read module feature.json, then map:
+    // [moduleCode]: { useCases, businessRules, entities, permissions, notes, mockupNotes }
+  },
+  consolidation: {
+    interactions: (master.consolidation?.crossModuleInteractions || []).map(i => ({
+      from: i.fromModule,
+      to: i.toModule,
+      description: i.description || ""
+    })),
+    e2eFlows: (master.consolidation?.e2eFlows || []).map(f => ({
+      name: f.name,
+      steps: (f.steps || []).map(s => ({ module: s.module, action: s.action })),
+      actors: (f.steps || []).map(s => s.permission).join(", ")
+    }))
+  },
+  handoff: master.handoff || {}
+}
+```
+
+**Module specs mapping** — for EACH module in `master.modules[]`:
+
+1. Read the module feature.json at `master.modules[i].featureJsonPath`
+2. Map to `moduleSpecs[moduleCode]`:
+
+```javascript
+moduleSpecs[moduleCode] = {
+  useCases: (moduleFeature.specification?.useCases || []).map(uc => ({
+    name: uc.name,
+    actor: uc.primaryActor,
+    steps: (uc.mainScenario || []).join("\n"),           // array → newline-separated string
+    alternative: (uc.alternativeScenarios || [])
+      .map(a => a.name + ": " + (a.steps || []).join(", ")).join("\n")
+  })),
+  businessRules: (moduleFeature.analysis?.businessRules || []).map(br => ({
+    name: br.name,
+    category: br.category,                              // "validation"|"calculation"|"workflow"|"security"|"data"
+    statement: br.statement,
+    example: (br.examples || []).map(e => e.input + " → " + e.expected).join("; ")
+  })),
+  entities: (moduleFeature.analysis?.entities || []).map(ent => ({
+    name: ent.name,
+    description: ent.description || "",
+    attributes: (ent.attributes || []).map(a => ({
+      name: a.name,
+      description: a.description || ""
+    })),
+    relationships: (ent.relationships || []).map(r =>
+      r.target + " (" + r.type + ") - " + (r.description || "")
+    )
+  })),
+  permissions: buildPermissionKeys(moduleFeature),      // see below
+  notes: "",
+  mockupNotes: ""  // Deprecated: wireframes now embedded separately in EMBEDDED_ARTIFACTS
+}
+```
+
+**Permission keys** — the HTML uses `"Role|Action"` format (e.g. `"RH Admin|Consulter"`):
+
+```javascript
+function buildPermissionKeys(moduleFeature) {
+  const keys = [];
+  const matrix = moduleFeature.specification?.permissionMatrix;
+  if (!matrix) return keys;
+  const actionMap = { read: "Consulter", create: "Creer", update: "Modifier",
+                      delete: "Supprimer", validate: "Valider", export: "Exporter",
+                      submit: "Valider", import: "Creer" };
+  (matrix.roleAssignments || []).forEach(ra => {
+    (ra.permissions || []).forEach(permPath => {
+      const action = permPath.split(".").pop();         // last segment = action
+      const uiAction = actionMap[action] || action;
+      keys.push(ra.role + "|" + uiAction);
+    });
+  });
+  return keys;
+}
+```
+
+**Frequency mapping:**
+```
+"Quotidien" → "daily", "Hebdomadaire" → "weekly", "Mensuel" → "monthly"
+Default: "daily"
+```
+
+**Access mapping (involvement → access):**
+```
+"decision-maker" → "admin", "end-user" with manager-like tasks → "manager"
+"end-user" → "contributor", "observer" → "viewer"
+Default: "contributor"
+```
+
+#### Step 2-bis: Build EMBEDDED_ARTIFACTS object (NEW)
+
+> **NEW in v6.2:** Visual artifacts (wireframes, E2E diagrams) are now embedded as a separate JavaScript object in the HTML for client-side rendering and export.
+
+Build a JSON object containing ALL visual artifacts from feature.json:
+
+```javascript
+{
+  wireframes: {
+    // FOR EACH module: extract all wireframes from module feature.json
+    // [moduleCode]: [ {screen, format, content, elements, componentMapping, layout, description} ]
+  },
+  e2eFlows: [
+    // Extract from master consolidation.e2eFlows[]
+    // { name, diagram, steps, actors }
+  ],
+  dependencyGraph: {
+    // Extract from master dependencyGraph
+    // nodes: [ {id, label, type} ], edges: [ {from, to, description} ]
+  }
+}
+```
+
+**Wireframes mapping** — for EACH module in `master.modules[]`:
+
+```javascript
+// Read the module feature.json
+const moduleFeature = readModuleFeature(moduleCode);
+const wireframes = (moduleFeature.specification?.uiWireframes || []).map(wf => ({
+  screen: wf.screen,                                    // e.g. "UM-list", "UM-form"
+  section: wf.section,                                  // e.g. "list", "form"
+  format: wf.mockupFormat || "ascii",                   // "ascii" | "svg"
+  content: wf.mockup,                                   // ASCII art or SVG markup
+  description: wf.description || "",
+  elements: wf.elements || [],                          // ["DataGrid", "FilterBar", ...]
+  actions: wf.actions || [],                            // ["filter", "sort", "create", ...]
+  componentMapping: wf.componentMapping || [],          // [{ wireframeElement, reactComponent }]
+  layout: wf.layout || null,                            // { type, regions: [...] }
+  permissionsRequired: wf.permissionsRequired || []
+}));
+
+// Store in artifacts object
+EMBEDDED_ARTIFACTS.wireframes[moduleCode] = wireframes;
+```
+
+**E2E flows mapping** — from master consolidation:
+
+```javascript
+EMBEDDED_ARTIFACTS.e2eFlows = (master.consolidation?.e2eFlows || []).map(flow => ({
+  name: flow.name,
+  diagram: generateE2EDiagram(flow),                    // ASCII diagram from flow.steps[]
+  steps: flow.steps || [],                              // [{ module, action, permission }]
+  actors: Array.from(new Set((flow.steps || [])
+    .map(s => s.permission?.split(".")[0])              // Extract role from permission path
+    .filter(Boolean))).join(", "),
+  modules: Array.from(new Set((flow.steps || [])
+    .map(s => s.module))).join(" → ")
+}));
+
+function generateE2EDiagram(flow) {
+  // Generate ASCII diagram from flow.steps[]
+  // Example output:
+  // "Customer ──[read]──→ Order ──[create]──→ Invoice ──[send]──→"
+  // "  (Orders)           (Orders)            (Invoices)"
+  // "  Contributor        Manager             System"
+
+  const stepDiagrams = (flow.steps || []).map(s =>
+    `${s.action}(${s.module})`
+  ).join(" ──→ ");
+
+  return stepDiagrams;
+}
+```
+
+**Dependency graph mapping** — from master dependencyGraph:
+
+```javascript
+EMBEDDED_ARTIFACTS.dependencyGraph = {
+  nodes: (master.modules || []).map(m => ({
+    id: m.code,
+    label: m.code,
+    type: m.featureType || "data-centric"
+  })),
+  edges: (master.dependencyGraph?.edges || []).map(e => ({
+    from: e.from,
+    to: e.to,
+    description: e.description || ""
+  }))
+};
+```
+
+#### Step 3: Replace placeholders in template
+
+1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation for readability)
+2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)
+3. Replace `{{FEATURE_DATA}}` with the serialized FEATURE_DATA JSON
+4. Replace `{{EMBEDDED_ARTIFACTS}}` with the serialized EMBEDDED_ARTIFACTS JSON
+5. Replace `{{APPLICATION_NAME}}` → `{application_name}` (still used in `<title>` and header)
+6. Replace `{{APPLICATION_ID}}` → `{feature_id}` (still used in `APP_KEY`)
+7. Replace `{{VERSION}}` → `{version}`
+8. Replace `{{CREATED_AT}}` → `{ISO timestamp}`
+
+> **NOTE:** `{{APPLICATION_NAME}}`, `{{APPLICATION_ID}}`, `{{VERSION}}`, `{{CREATED_AT}}` still appear
+> in the HTML body (`<title>`, header, `APP_KEY`). They MUST be replaced separately from FEATURE_DATA.
+
+> **NEW:** `{{EMBEDDED_ARTIFACTS}}` is a separate JavaScript variable in the HTML that stores all visual artifacts (wireframes, E2E diagrams, dependency graph) for client-side rendering and export.
+
+#### Step 4: Write and confirm
+
+1. Write the populated HTML to the output directory
+2. Display deployment confirmation:
 
 ```
 ✓ Interactive HTML deployed:
   Path: docs/business/{app}/business-analyse/v{version}/ba-interactive.html
+  Pre-populated with: {stakeholder_count} stakeholders, {module_count} modules,
+    {total_uc} use cases, {total_br} business rules, {total_entity} entities
+  Visual artifacts: {total_wireframes} wireframes, {e2e_flow_count} E2E diagrams
   Open in browser to review and edit the business analysis.
   Export JSON and re-import with: /business-analyse -x <exported-json-path>
 ```
 
-**Why deploy at handoff?**
-- The feature.json is complete at this point (all modules specified and consolidated)
-- The client can review the full analysis in an interactive format
+**Why a FINAL deployment at handoff?**
+- Step 03 already deploys the HTML incrementally after each module (partial data)
+- This final deployment adds the COMPLETE data: all modules + consolidation + handoff info
+- The client sees the FULL analysis pre-populated — including cross-module interactions and E2E flows
+- The client can review, edit, and enrich directly in the browser
 - Any client modifications can be re-imported via `-x` extraction mode
 - The HTML is standalone (no server required) with localStorage persistence
+- On first open: pre-populated data displays. After client edits: localStorage overrides
+- **NOTE:** This overwrites the incremental HTML from step-03 with the complete version
 
 ---
 
@@ -1043,7 +1336,7 @@ options:
   - label: "Feature Full (Recommandé)"
     description: "Génération parallèle rapide (code + tests). Couverture 70-80%. ~{hours/3} heures."
   - label: "Ralph Loop"
-    description: "Développement task-driven séquentiel. Couverture 95-100%. ~{hours} heures."
+    description: "Développement itératif task-par-task avec cycle : Analyse → Dev (backend + tests unitaires + tests non-régression + frontend + tests + documentation) → Validation → Correction → Test ... jusqu'à 100% tests pass. Couverture 95-100%. ~{hours} heures."
   - label: "Terminer le BA"
     description: "Finir l'analyse, développement manuel par l'équipe."
 ```
@@ -1055,6 +1348,179 @@ options:
 
 ---
 
+### 10-bis. Execute User Choice (Automatic Skill Launch)
+
+> **NEW in v6.1:** Automatically launch the chosen development approach for seamless transition.
+
+**After receiving AskUserQuestion response:**
+
+```javascript
+const choice = userAnswer; // "Feature Full (Recommandé)" | "Ralph Loop" | "Terminer le BA"
+
+// Extract choice label (remove "(Recommandé)" suffix)
+const choiceLabel = choice.replace(/\s*\(.*?\)\s*$/g, '').trim();
+
+if (choiceLabel === "Ralph Loop") {
+  // Launch ralph-loop skill automatically
+  display("");
+  display("🚀 Lancement de Ralph Loop - Développement itératif automatique");
+  display("");
+  display("╔══════════════════════════════════════════════════════════════╗");
+  display("║  CYCLE RALPH LOOP - Comment ça fonctionne ?                 ║");
+  display("╠══════════════════════════════════════════════════════════════╣");
+  display("║                                                              ║");
+  display("║  Ralph Loop exécute un cycle itératif jusqu'à 100% tests:   ║");
+  display("║                                                              ║");
+  display("║  1️⃣ ANALYSE      → Charger task suivante du prd.json       ║");
+  display("║  2️⃣ DÉVELOPPEMENT → Générer le code demandé                 ║");
+  display("║     • Backend (Entities, Services, Controllers, Repos)      ║");
+  display("║     • Tests unitaires (xUnit) + non-régression              ║");
+  display("║     • Frontend (Pages, Components, Hooks)                   ║");
+  display("║     • Tests frontend (React Testing Library)                ║");
+  display("║     • SeedData (Core RBAC + business data)                  ║");
+  display("║     • Documentation utilisateur (inline + tooltips)         ║");
+  display("║  3️⃣ VALIDATION   → Commit + MCP conventions check           ║");
+  display("║  4️⃣ TEST         → Exécuter dotnet test + npm test          ║");
+  display("║  5️⃣ CORRECTION   → Si échec, analyser et corriger           ║");
+  display("║  6️⃣ BOUCLE       → Répéter 4-5 jusqu'à 100% tests pass      ║");
+  display("║  7️⃣ NEXT TASK    → Passer à la task suivante (retour à 1)  ║");
+  display("║                                                              ║");
+  display("║  🎯 Objectif: ZÉRO ERREUR avant de passer à la task suivante║");
+  display("║  📊 Couverture: 95-100% (tests générés automatiquement)     ║");
+  display("║                                                              ║");
+  display("╚══════════════════════════════════════════════════════════════╝");
+  display("");
+  display("   Configuration du projet:");
+  display("   ┌────────────────────────────────────────────────────────────┐");
+  display("   │ Modules:   " + modules.map(m => m.code).join(", "));
+  display("   │ Stratégie: " + implementationStrategy);
+  display("   │ PRD:       " + (modules.length > 1 ? ".ralph/prd-{module}.json (per module)" : ".ralph/prd.json"));
+  display("   │ Progress:  .ralph/progress.txt");
+  display("   │ Ordre:     " + (modules.length > 1 ? "topologique (dépendances d'abord)" : "module unique"));
+  display("   └────────────────────────────────────────────────────────────┘");
+  display("");
+  display("   Modules à traiter (dans l'ordre):");
+  for (let i = 0; i < modules.length; i++) {
+    display("   " + (i+1) + ". " + modules[i].code + " (" + modules[i].complexity + ") - " + modules[i].tasksCount + " tasks");
+  }
+  display("");
+  display("   📂 Fichiers générés par le BA (inputs pour Ralph):");
+  display("   ├─ feature.json (master + modules) → Spécification source");
+  display("   ├─ prd.json (ou prd-{module}.json) → Task breakdown avec UC/FR/BR");
+  display("   ├─ progress.txt                    → Tracker hiérarchique (module → layer → tasks)");
+  display("   └─ ba-interactive.html             → Revue client (mockups, wireframes)");
+  display("");
+  display("   🔄 Ralph Loop va maintenant:");
+  display("   1. Détecter les prd-*.json par module (si multi-module)");
+  display("   2. Créer modules-queue.json avec l'ordre de traitement");
+  display("   3. Traiter module par module dans l'ordre topologique");
+  display("   4. Pour chaque module: parcourir les tasks (domain → seeddata → application → infrastructure → api → frontend → i18n → tests)");
+  display("   5. Pour chaque task: générer code → commit → tests → correction si échec → re-test → next task");
+  display("   6. Passer au module suivant quand 100% tasks du module actuel = completed");
+  display("   7. Générer rapport final avec métriques de couverture");
+  display("");
+  display("═══════════════════════════════════════════════════════════════");
+  display("");
+  display("➡️  Transition vers Ralph Loop...");
+  display("");
+
+  // Call the ralph-loop skill (no arguments needed - prd.json exists)
+  Skill({ skill: "ralph-loop" });
+
+  // EXIT - ralph-loop takes over
+  // The skill does NOT return here - ralph-loop continues in a new context
+
+} else if (choiceLabel === "Feature Full") {
+  // Launch feature-full skill automatically
+  display("");
+  display("🚀 Lancement de Feature Full...");
+  display("");
+  display("   Configuration:");
+  display("   - Mode: Parallel generation");
+  display("   - Couverture: 70-80%");
+  display("   - Durée estimée: ~" + Math.round(totalHours / 3) + " heures");
+  display("");
+  display("═══════════════════════════════════════════════════════════════");
+  display("");
+
+  Skill({ skill: "feature-full" });
+
+  // EXIT
+
+} else {
+  // "Terminer le BA" - no skill launch, end gracefully
+  display("");
+  display("✅ Business Analysis terminée.");
+  display("");
+  display("   Les équipes peuvent commencer le développement manuel.");
+  display("   Tous les artefacts sont prêts pour l'implémentation.");
+  display("");
+  display("📂 Fichiers générés:");
+  display("   - feature.json (master + modules) - Spécification complète");
+  display("   - .ralph/prd.json (ou prd-{module}.json) - Task breakdown");
+  display("   - .ralph/progress.txt - Tracker de progression");
+  display("   - ba-interactive.html - Document de revue client");
+  display("");
+  display("📊 Métriques:");
+  display("   - Modules: " + modules.length);
+  display("   - Entités: " + totalEntities);
+  display("   - Use cases: " + totalUseCases);
+  display("   - Business rules: " + totalBusinessRules);
+  display("   - Fichiers à créer: " + totalFiles);
+  display("");
+  display("🎯 Prochaines étapes recommandées:");
+  display("   1. Ouvrir ba-interactive.html dans le navigateur");
+  display("   2. Partager avec les stakeholders pour validation finale");
+  display("   3. Utiliser progress.txt comme guide de développement");
+  display("   4. Implémenter module par module selon l'ordre topologique");
+  display("");
+  display("💡 Pour lancer le développement assisté plus tard:");
+  display("   - Ralph Loop: /ralph-loop (détecte automatiquement .ralph/prd.json)");
+  display("   - Feature Full: /feature-full");
+  display("");
+  display("═══════════════════════════════════════════════════════════════");
+
+  // EXIT gracefully - BA workflow complete
+}
+```
+
+**Key behaviors:**
+
+1. **Ralph Loop launch:**
+   - No arguments needed (prd.json already exists)
+   - Ralph automatically detects single vs multi-module
+   - Ralph reads modules-queue.json if multi-module
+   - Seamless transition - user sees continuous flow
+
+2. **Feature Full launch:**
+   - Passes application context
+   - Parallel generation starts immediately
+
+3. **Manual development:**
+   - Clear summary of generated artifacts
+   - Actionable next steps
+   - Instructions for later skill launch
+
+**Error handling:**
+
+```javascript
+try {
+  Skill({ skill: "ralph-loop" });
+} catch (error) {
+  display("⚠️ Échec du lancement automatique de Ralph Loop");
+  display("");
+  display("   Veuillez lancer manuellement:");
+  display("   /ralph-loop");
+  display("");
+  display("   Si le problème persiste:");
+  display("   1. Vérifier que la skill ralph-loop est installée");
+  display("   2. Vérifier les permissions Claude Code");
+  display("   3. Consulter les logs: .ralph/logs/");
+}
+```
+
+---
+
 ## MODE SUPPORT
 
 ### Standard Mode
@@ -1192,7 +1658,7 @@ Before presenting handoff to user:
 - [ ] feature.json updated: handoff section + status "handed-off"
 - [ ] All paths use project namespace from .smartstack/config.json
 - [ ] No invented requirements (everything traced to feature.json)
-- [ ] ba-interactive.html deployed with placeholders replaced
+- [ ] ba-interactive.html deployed PRE-POPULATED with all analysis data (not empty)
 - [ ] BA manifest (docs/business/index.json) updated with current analysis entries
 - [ ] User ready for next agent selection