@atlashub/smartstack-cli 2.9.0 → 3.1.0

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

@@ -915,6 +915,296 @@ Status journey: analyze → consolidate → **handed-off**
 
 ---
 
+### 9d. Deploy Interactive HTML Document (MANDATORY)
+
+> **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/`)
+
+**Destination:** `docs/business/{app}/business-analyse/v{version}/ba-interactive.html`
+
+**Deployment steps:**
+
+#### Step 1: Read source data
+
+1. Read the HTML template from skill directory
+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: (moduleFeature.specification?.uiWireframes || [])
+    .map(w => "[" + w.screen + "]\n" + w.mockup).join("\n\n")
+}
+```
+
+**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 3: Replace placeholders in template
+
+1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation for readability)
+2. Replace `{{FEATURE_DATA}}` with the serialized JSON
+3. Replace `{{APPLICATION_NAME}}` → `{application_name}` (still used in `<title>` and header)
+4. Replace `{{APPLICATION_ID}}` → `{feature_id}` (still used in `APP_KEY`)
+5. Replace `{{VERSION}}` → `{version}`
+6. 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.
+
+#### 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
+  Open in browser to review and edit the business analysis.
+  Export JSON and re-import with: /business-analyse -x <exported-json-path>
+```
+
+**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
+
+---
+
+### 9e. Update BA Manifest (MANDATORY)
+
+> **The BA manifest enables the SmartStack web app to discover and display all available business analyses.**
+> It is a JSON index file at `docs/business/index.json` that lists all feature.json files.
+
+**Path:** `docs/business/index.json` (project root relative)
+
+**Schema:**
+```json
+{
+  "version": "1.0",
+  "updatedAt": "{ISO timestamp}",
+  "analyses": [
+    {
+      "appCode": "{app_code}",
+      "appName": "{application_name}",
+      "moduleCode": null | "{module_code}",
+      "moduleName": "{module_name}",
+      "version": "{version}",
+      "status": "handed-off",
+      "featureDescription": "{feature_description}",
+      "path": "{app_code}/business-analyse/v{version}/feature.json",
+      "updatedAt": "{ISO timestamp}"
+    }
+  ]
+}
+```
+
+**Update logic:**
+
+1. Read existing manifest at `docs/business/index.json` (or create empty `{ "version": "1.0", "updatedAt": "", "analyses": [] }`)
+2. For the APPLICATION-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: null` and `path: "{app_code}/business-analyse/v{version}/feature.json"`
+3. For EACH MODULE-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: "{module_code}"` and `path: "{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+4. Update root `updatedAt` to current timestamp
+5. Write manifest back to `docs/business/index.json`
+
+**Display confirmation:**
+```
+✓ BA manifest updated: docs/business/index.json
+  Entries: {total_count} ({app_count} applications, {module_count} modules)
+  Web viewer: /system/docs/ba
+```
+
+**Why a manifest?**
+- The web app needs to discover available BAs without scanning the filesystem
+- Static file serving (no backend API needed)
+- Incremental updates: each handoff adds/updates only its entries
+- Consumed by the SmartStack web app BA viewer at `/system/docs/ba`
+
+---
+
 ### 10. User Choice: Next Agent
 
 Present development options after successful handoff:
@@ -935,6 +1225,7 @@ Generated Artifacts:
   ✓ feature.json (master + per-module) - enhanced with handoff section
   ✓ .ralph/prd.json or .ralph/prd-{module}.json - derived from feature.json
   ✓ .ralph/progress.txt - comprehensive task tracker
+  ✓ ba-interactive.html - client-facing interactive review document
   ✓ Implementation strategy selected: {strategy}
 
 Next: Choose development approach
@@ -1003,7 +1294,14 @@ This step enriches **feature.json** (master + per-module) with:
 - **handoff** section: complexity, implementationStrategy, moduleOrder, filesToCreate (7 categories), brToCodeMapping, apiEndpointSummary, prdFiles
 - **status:** "handed-off"
 
-Also generates two working files:
+Also generates working files and updates the manifest:
+
+- **ba-interactive.html** (deployed to docs/business/{app}/business-analyse/v{version}/)
+  - Standalone interactive HTML document for client review
+  - Pre-populated with application name, ID, version
+  - Client can edit, add use cases, modify scope, and export JSON
+  - Re-importable via `/business-analyse -x <exported-json-path>`
+
 - **.ralph/prd.json** (or .ralph/prd-{module}.json per module structure)
   - Derived entirely from feature.json
   - Single source of truth for development team
@@ -1092,6 +1390,8 @@ 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 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
 
 ---