@atlashub/smartstack-cli 3.8.0 → 3.9.0

package/templates/skills/business-analyse/references/handoff-mappings.md

@@ -0,0 +1,81 @@
+# Handoff Mappings: BR-to-Code & API Summary
+
+## Business Rules to Code Mapping
+
+Derive from `analysis.businessRules[]` of **EACH module**.
+
+Generate complete mapping for each BR:
+
+```json
+{
+  "brToCodeMapping": [
+    {
+      "ruleId": "BR-VAL-001",
+      "title": "Order total must equal sum of item prices",
+      "module": "{moduleCode}",
+      "severity": "critical",
+      "implementationPoints": [
+        { "layer": "Domain", "component": "Order.cs", "method": "CalculateTotal()", "implementation": "Validate sum equals sum of OrderItems.Price" },
+        { "layer": "Application", "component": "CreateOrderService.cs", "method": "Handle()", "implementation": "Calculate total before persisting" },
+        { "layer": "API", "component": "OrdersController.cs", "method": "CreateOrder()", "implementation": "Return validation error if total mismatch" },
+        { "layer": "Frontend", "component": "OrderForm.tsx", "method": "calculateTotal()", "implementation": "Real-time calculation on item change" }
+      ]
+    }
+  ]
+}
+```
+
+For each BR include:
+- **ruleId**: Reference to analysis.businessRules[].id
+- **title**: The rule statement
+- **module**: Which module it belongs to
+- **severity**: "critical", "high", "medium", "low"
+- **implementationPoints**: Array of {layer, component, method, implementation}
+
+Layers: Domain, Application, Infrastructure, API, Frontend
+
+## API Endpoint Summary
+
+> **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.
+
+```json
+{
+  "apiEndpointSummary": [
+    {
+      "operation": "ListOrders",
+      "method": "GET",
+      "route": "/api/business/orders",
+      "linkedUC": "UC-001",
+      "linkedFR": "FR-001",
+      "permissions": ["business.orders.read"],
+      "requestSchema": { "type": "query", "params": ["pageNumber", "pageSize", "status"] },
+      "responseSchema": { "type": "PaginatedOrderDto[]" },
+      "errorCodes": [401, 403, 400, 500],
+      "module": "{moduleCode}"
+    },
+    {
+      "operation": "CreateOrder",
+      "method": "POST",
+      "route": "/api/business/orders",
+      "linkedUC": "UC-002",
+      "linkedFR": "FR-002",
+      "permissions": ["business.orders.create"],
+      "requestSchema": { "type": "body", "schema": "CreateOrderDto" },
+      "responseSchema": { "type": "OrderDto" },
+      "errorCodes": [400, 401, 403, 422, 500],
+      "module": "{moduleCode}"
+    }
+  ]
+}
+```
+
+For each endpoint:
+- **operation**: Use case name
+- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- **route**: Full API path from specification
+- **linkedUC/linkedFR**: Use case and feature requirement IDs
+- **permissions**: Array of exact permission paths
+- **requestSchema**: Input contract (query params or body)
+- **responseSchema**: Output contract
+- **errorCodes**: Expected HTTP error codes
+- **module**: Which module

package/templates/skills/business-analyse/references/html-data-mapping.md

@@ -161,8 +161,16 @@ function buildPermissionKeys(moduleFeature) {
   (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);
+      if (action === "*") {
+        // Wildcard: expand to all standard actions
+        Object.values(actionMap).forEach(uiAction => {
+          const key = ra.role + "|" + uiAction;
+          if (!keys.includes(key)) keys.push(key);
+        });
+      } else {
+        const uiAction = actionMap[action] || action;
+        keys.push(ra.role + "|" + uiAction);
+      }
     });
   });
   return keys;

package/templates/skills/business-analyse/references/init-schema-deployment.md

@@ -0,0 +1,65 @@
+# Init: JSON Schema Deployment
+
+> Reference for step-00-init.md — cache-based schema deployment.
+
+## Cache-Based Deployment Logic
+
+### Step 1: Check Deployment Cache
+
+Cache file location: `docs/business/{app}/business-analyse/.schema-cache.json`
+
+```
+IF EXISTS .schema-cache.json:
+  Read cache file
+  IF cache.version == "{CLI_VERSION}" (from package.json):
+    Display: "Schemas already deployed ({CLI_VERSION}) - skipping"
+    SKIP deployment → Go to Step 9
+  ELSE:
+    Display: "Schema version mismatch (cache: {cache.version}, current: {CLI_VERSION})"
+    Proceed to deployment
+ELSE:
+  Display: "Deploying schemas (first time)..."
+  Proceed to deployment
+```
+
+### Step 2: Deploy Schemas (if needed)
+
+Source: `schemas/` (relative to skill root = `~/.claude/skills/business-analyse/schemas/`)
+Destination: `docs/business/{app}/business-analyse/schemas/`
+
+```
+docs/business/{app}/business-analyse/schemas/
+├── feature-schema.json
+├── application-schema.json
+├── sections/
+│   ├── metadata-schema.json
+│   ├── discovery-schema.json
+│   ├── analysis-schema.json
+│   ├── specification-schema.json
+│   ├── validation-schema.json
+│   └── handoff-schema.json
+└── shared/
+    └── common-defs.json
+```
+
+**Total: 9 files to deploy.**
+
+### Step 3: Write Cache File
+
+```json
+{
+  "version": "{CLI_VERSION}",
+  "deployedAt": "{ISO timestamp}",
+  "schemas": [
+    "feature-schema.json",
+    "application-schema.json",
+    "sections/metadata-schema.json",
+    "sections/discovery-schema.json",
+    "sections/analysis-schema.json",
+    "sections/specification-schema.json",
+    "sections/validation-schema.json",
+    "sections/handoff-schema.json",
+    "shared/common-defs.json"
+  ]
+}
+```

package/templates/skills/business-analyse/references/review-data-mapping.md

@@ -0,0 +1,363 @@
+# Review Data Mapping Reference (references/review-data-mapping.md)
+
+> **Used by:** step-06-review (Apply Review Corrections)
+> **Purpose:** Reverse mapping from ba-review.json (HTML export) back to feature.json format
+> **Complement of:** `references/html-data-mapping.md` (forward mapping)
+
+---
+
+## Overview
+
+The ba-review.json is exported from the interactive HTML with the same structure as the HTML data model. This document defines the **reverse transformation** to apply corrections back into feature.json format.
+
+---
+
+## Cadrage Reverse Mapping
+
+### Scope (HTML → feature.json)
+
+```javascript
+// HTML format: { vital: [{name, description}], important: [...], optional: [...], excluded: [...] }
+// feature.json format: { mustHave: [string], shouldHave: [string], couldHave: [string], outOfScope: [string] }
+
+reverseScope(reviewCadrage) {
+  return {
+    mustHave: (reviewCadrage.scope?.vital || []).map(s => s.name),
+    shouldHave: (reviewCadrage.scope?.important || []).map(s => s.name),
+    couldHave: (reviewCadrage.scope?.optional || []).map(s => s.name),
+    outOfScope: (reviewCadrage.scope?.excluded || []).map(s => s.name)
+  };
+}
+```
+
+### Stakeholders (HTML → feature.json)
+
+```javascript
+// HTML format: { role, function, tasks[], frequency, access, frustrations }
+// feature.json format: { role, function, involvement, tasks[], frequency, painPoints[] }
+
+const accessToInvolvement = {
+  admin: "decision-maker",
+  manager: "consulted",
+  contributor: "end-user",
+  viewer: "informed"
+};
+
+const frequencyReverse = {
+  daily: "Quotidien",
+  weekly: "Hebdomadaire",
+  monthly: "Mensuel",
+  occasional: "Occasionnel"
+};
+
+reverseStakeholder(htmlStakeholder) {
+  return {
+    role: htmlStakeholder.role,
+    function: htmlStakeholder.function || "",
+    involvement: accessToInvolvement[htmlStakeholder.access] || "end-user",
+    tasks: htmlStakeholder.tasks || [],
+    frequency: frequencyReverse[htmlStakeholder.frequency] || htmlStakeholder.frequency,
+    painPoints: (htmlStakeholder.frustrations || "").split("\n").filter(Boolean)
+  };
+}
+```
+
+### Problem / Vision / Current (HTML → feature.json)
+
+```javascript
+// HTML has detailed sub-fields; feature.json has flat strings
+reverseProblemVision(reviewCadrage) {
+  return {
+    problem: reviewCadrage.problem?.description || "",
+    trigger: reviewCadrage.problem?.trigger || "",
+    asIs: reviewCadrage.current?.tools || "",
+    toBe: reviewCadrage.vision?.changes || ""
+  };
+}
+```
+
+### Risks (HTML → feature.json)
+
+```javascript
+// HTML format: { description, probability, impact, mitigation }
+// feature.json format: { id, type, description, probability, impact, mitigation }
+
+reverseRisks(reviewRisks, existingRisks) {
+  return (reviewRisks || []).map((r, i) => {
+    // Try to match with existing risk by description
+    const existing = (existingRisks || []).find(er => er.description === r.description);
+    return {
+      id: existing?.id || "RISK-" + String(i + 1).padStart(3, "0"),
+      type: existing?.type || "business",
+      description: r.description,
+      probability: r.probability,
+      impact: r.impact,
+      mitigation: r.mitigation || ""
+    };
+  });
+}
+```
+
+### Acceptance Criteria (HTML → feature.json)
+
+```javascript
+// HTML format: success.definition (string, one criterion per line)
+// feature.json format: acceptanceCriteria[]: { id, criterion, validated }
+
+reverseAcceptanceCriteria(reviewSuccess, existingCriteria) {
+  const lines = (reviewSuccess?.definition || "").split("\n").filter(Boolean);
+  return lines.map((line, i) => {
+    const existing = (existingCriteria || []).find(ac => ac.criterion === line);
+    return {
+      id: existing?.id || "AC-" + String(i + 1).padStart(3, "0"),
+      criterion: line.trim(),
+      validated: existing?.validated || false
+    };
+  });
+}
+```
+
+---
+
+## Module Specifications Reverse Mapping
+
+### Use Cases (HTML → feature.json)
+
+```javascript
+// HTML format: { id, name, actor, steps (newline-separated string), alternative (string) }
+// feature.json format: { id, name, primaryActor, permission, preconditions[], postconditions[], mainScenario[], alternativeScenarios[], linkedRules[] }
+
+reverseUseCase(htmlUC, existingUC) {
+  return {
+    id: htmlUC.id || existingUC?.id,
+    name: htmlUC.name,
+    primaryActor: htmlUC.actor,
+    permission: existingUC?.permission || "",
+    preconditions: existingUC?.preconditions || [],
+    postconditions: existingUC?.postconditions || [],
+    mainScenario: (htmlUC.steps || "").split("\n").filter(Boolean),
+    alternativeScenarios: existingUC?.alternativeScenarios || [],
+    errorScenarios: existingUC?.errorScenarios || [],
+    linkedRules: existingUC?.linkedRules || []
+  };
+}
+```
+
+### Business Rules (HTML → feature.json)
+
+```javascript
+// HTML format: { id, name, category, statement, example (string) }
+// feature.json format: { id, name, category, statement, priority, conditions[], examples[], testability }
+
+reverseBusinessRule(htmlBR, existingBR) {
+  return {
+    id: htmlBR.id || existingBR?.id,
+    name: htmlBR.name,
+    category: htmlBR.category,
+    statement: htmlBR.statement,
+    priority: existingBR?.priority || "must",
+    conditions: existingBR?.conditions || [],
+    examples: htmlBR.example
+      ? [{ input: htmlBR.example, expected: "" }]
+      : (existingBR?.examples || []),
+    testability: existingBR?.testability || ""
+  };
+}
+```
+
+### Entities (HTML → feature.json)
+
+```javascript
+// HTML format: { name, description, attributes: [{name, description}], relationships: [string] }
+// feature.json format: { name, description, attributes: [{name, description, required}], relationships: [{target, type, description}] }
+
+reverseEntity(htmlEntity, existingEntity) {
+  return {
+    name: htmlEntity.name,
+    description: htmlEntity.description || "",
+    attributes: (htmlEntity.attributes || []).map(a => {
+      const existing = (existingEntity?.attributes || []).find(ea => ea.name === a.name);
+      return {
+        name: a.name,
+        description: a.description || "",
+        required: existing?.required ?? true
+      };
+    }),
+    relationships: (htmlEntity.relationships || []).map(relStr => {
+      // Parse "Target (type) - description" format back to structured
+      const match = relStr.match(/^(.+?)\s*\((.+?)\)\s*-\s*(.*)$/);
+      if (match) {
+        return { target: match[1].trim(), type: match[2].trim(), description: match[3].trim() };
+      }
+      return { target: relStr, type: "reference", description: "" };
+    })
+  };
+}
+```
+
+### Permissions (HTML → feature.json)
+
+```javascript
+// HTML format: permissions[] = ["Role|Action", "Role|Action", "Role|*"]
+// feature.json format: permissionMatrix = { permissions: [{path, action, description}], roleAssignments: [{role, permissions[]}] }
+
+const actionToPermission = {
+  Consulter: "read",
+  Creer: "create",
+  Modifier: "update",
+  Supprimer: "delete",
+  Valider: "validate",
+  Exporter: "export"
+};
+
+reversePermissions(htmlPermissions, moduleCode, appName) {
+  const rolePerms = {};
+
+  // Group permissions by role
+  (htmlPermissions || []).forEach(p => {
+    const [role, action] = p.split("|");
+    if (!rolePerms[role]) rolePerms[role] = [];
+    if (action === "*") {
+      // Wildcard: add all standard permission paths
+      Object.values(actionToPermission).forEach(permAction => {
+        const path = `business.${appName}.${moduleCode}.*.${permAction}`;
+        if (!rolePerms[role].includes(path)) rolePerms[role].push(path);
+      });
+    } else {
+      const permAction = actionToPermission[action] || action.toLowerCase();
+      const path = `business.${appName}.${moduleCode}.*.${permAction}`;
+      if (!rolePerms[role].includes(path)) rolePerms[role].push(path);
+    }
+  });
+
+  // Build unique permission paths
+  const allPaths = new Set();
+  Object.values(rolePerms).forEach(perms => perms.forEach(p => allPaths.add(p)));
+
+  return {
+    permissions: Array.from(allPaths).map(path => ({
+      path,
+      action: path.split(".").pop(),
+      description: ""
+    })),
+    roleAssignments: Object.entries(rolePerms).map(([role, perms]) => ({
+      role,
+      permissions: perms
+    }))
+  };
+}
+```
+
+---
+
+## Modules Reverse Mapping
+
+### Module List (HTML → feature.json)
+
+```javascript
+// HTML format: modules[] = [{ code, name, description, featureType, priority, entities[], status }]
+// feature.json format: modules[] = [{ code, description, featureType, dependencies[], dependents[], status, priority, sortOrder, entities[], estimatedComplexity }]
+
+reverseModule(htmlModule, existingModule) {
+  return {
+    code: htmlModule.code,
+    description: htmlModule.description || "",
+    featureType: htmlModule.featureType || "data-centric",
+    dependencies: existingModule?.dependencies || [],
+    dependents: existingModule?.dependents || [],
+    status: existingModule?.status || "pending",
+    priority: htmlModule.priority || "must",
+    sortOrder: existingModule?.sortOrder || 0,
+    entities: htmlModule.entities || [],
+    estimatedComplexity: existingModule?.estimatedComplexity || "medium",
+    featureJsonPath: existingModule?.featureJsonPath
+  };
+}
+```
+
+---
+
+## Consolidation Reverse Mapping
+
+### Cross-Module Interactions (HTML → feature.json)
+
+```javascript
+// HTML format: consolidation.interactions[] = [{ from, to, description }]
+// feature.json format: consolidation.crossModuleInteractions[] = [{ fromModule, toModule, interactionType, description, entities[] }]
+
+reverseInteraction(htmlInteraction, existingInteraction) {
+  return {
+    fromModule: htmlInteraction.from,
+    toModule: htmlInteraction.to,
+    interactionType: existingInteraction?.interactionType || "data-reference",
+    description: htmlInteraction.description || "",
+    entities: existingInteraction?.entities || []
+  };
+}
+```
+
+### E2E Flows (HTML → feature.json)
+
+```javascript
+// HTML format: consolidation.e2eFlows[] = [{ name, steps: [{module, action}], actors }]
+// feature.json format: consolidation.e2eFlows[] = [{ name, steps: [{module, action, permission}] }]
+
+reverseE2EFlow(htmlFlow, existingFlow) {
+  return {
+    name: htmlFlow.name,
+    steps: (htmlFlow.steps || []).map((s, i) => ({
+      module: s.module,
+      action: s.action,
+      permission: existingFlow?.steps?.[i]?.permission || ""
+    }))
+  };
+}
+```
+
+---
+
+## Review Comments Preservation
+
+Comments from the review are stored in a new `review` section of the master feature.json:
+
+```javascript
+{
+  review: {
+    appliedAt: "ISO timestamp",
+    sourceVersion: "1.0",
+    comments: [
+      // Inline structured comments from data.comments[]
+      { id, sectionId, cardIndex, author, timestamp, content, status, category }
+    ],
+    specComments: {
+      // Textarea comments keyed as "moduleCode.type.index"
+      "Employees.uc.0": "Comment text",
+      "Employees.br.1": "Another comment"
+    },
+    wireframeComments: {
+      // Wireframe feedback keyed by module
+      "Employees": { "EM-list": "Comment on list wireframe" }
+    },
+    changeSummary: {
+      cadrageModified: true,
+      modulesAdded: [],
+      modulesRemoved: [],
+      modulesModified: ["Employees", "LeaveRequests"],
+      commentsCount: 5
+    }
+  }
+}
+```
+
+---
+
+## Matching Strategy
+
+When applying corrections, always try to **match existing items** before creating new ones:
+
+1. **By ID**: If the review item has an ID (UC-001, BR-VAL-001), find the same ID in feature.json
+2. **By name**: If no ID match, find by exact name match
+3. **New item**: If no match found, create a new item with a generated ID
+4. **Removed items**: Items present in feature.json but absent from review are marked as removed (not deleted)
+
+This preserves referential integrity (linked rules, use case references) across the update.

package/templates/skills/business-analyse/references/spec-auto-inference.md

@@ -0,0 +1,57 @@
+# Specification: Auto-Inference Rules
+
+> Reference for step-03a-data.md — convention/override depth auto-generation from entity definitions.
+
+## Entity Attribute → SmartTable Column
+
+| Attribute Type | Column Format | Sortable | Filterable | Notes |
+|---|---|---|---|---|
+| string + unique | text | yes | yes | clickAction: navigate:detail |
+| string | text | yes | yes | — |
+| enum / status | badge | yes | yes (multi-select) | colorMap from lifeCycles if exists |
+| FK:Entity | text (join .name) | yes | yes (entity-select) | Display related entity name |
+| decimal | currency | yes | no | — |
+| int | number | yes | no | — |
+| datetime | date-relative | yes | yes (date-range) | — |
+| bool | boolean | yes | yes (toggle) | — |
+| text (long) | — | no | no | Hidden in table, visible in detail |
+
+## Entity Attribute → SmartForm Field
+
+| Attribute Type | Component | Required from | Notes |
+|---|---|---|---|
+| string | Input | entity.required | — |
+| string (multiline) | TextArea | entity.required | rows: 4 |
+| enum | Select | entity.required | source: enum name |
+| FK:Entity | EntitySelect | entity.required | source: target entity, searchable |
+| decimal | NumberInput | entity.required | — |
+| int | NumberInput | entity.required | — |
+| datetime | DatePicker | entity.required | — |
+| bool | Toggle | — | default: false |
+
+## Auto-Generated Sections by featureType
+
+| featureType | Sections generated |
+|---|---|
+| data-centric | list, create, detail |
+| workflow | list, create, detail, edit |
+| integration | list, detail, config |
+| reporting | dashboard |
+| full-module | list, create, detail, edit, dashboard |
+
+## Section Generation Rules
+
+1. **list section:** SmartTable with all non-long-text attributes as columns, actions = [view, edit, delete], defaultSort = { createdAt, desc }
+2. **create section:** SmartForm with all writable attributes as fields, component inferred from type
+3. **detail section:** DetailCard with all attributes + child SmartTable for each 1:N relationship
+4. **edit section:** Same as create but pre-filled (mode: edit)
+5. **dashboard section:** Trigger 3d (dashboard specification)
+
+## Status/Lifecycle Enhancement
+
+If entity has a status/enum field AND lifeCycles exists:
+- list section: status column gets `format: badge`, `colorMap: stateMachine:{Entity}`
+- list section: rowActions get `showWhen` conditions based on state machine transitions
+- detail section: add StatusBadge resource + transition action buttons
+
+Write auto-generated sections to `specification.sections[]` via `ba-writer.enrichSection()`

package/templates/skills/business-analyse/references/ui-dashboard-spec.md

@@ -0,0 +1,85 @@
+# UI: Dashboard Specification
+
+> Reference for step-03b-ui.md — section 3d dashboard KPI and chart capture.
+
+## 3d. Dashboard Specification (if section = dashboard)
+
+When a "dashboard" section is selected, capture structured KPI and chart data **in addition** to the standard ASCII mockup.
+
+1. **Ask client for KPIs** via AskUserQuestion (batch):
+   - KPI name and metric description
+   - Visualization type: `kpi-card`, `bar`, `line`, `pie`, `area`, `donut`, `stacked-bar`
+   - Data source entity
+   - Format: `number`, `currency`, `percent`, `duration`
+   - Thresholds (warning/critical) if applicable
+
+2. **Ask client for filters:**
+   - Date range filter? Default period? (day/week/month/quarter/year)
+   - Entity-based filters? (status, category, etc.)
+
+3. **Ask client for refresh mode:**
+   - Static (load on page open)
+   - Polling (periodic refresh)
+   - SignalR (real-time push)
+
+4. **Store in specification.dashboards[]:**
+
+```json
+{
+  "code": "{module}-dashboard",
+  "title": "{Module} Dashboard",
+  "description": "Vue d'ensemble des métriques {module}",
+  "linkedUCs": ["UC-XXX"],
+  "refreshMode": "static",
+  "defaultPeriod": "month",
+  "kpis": [
+    {
+      "code": "total-items",
+      "label": "Total Items",
+      "metric": "COUNT(entity)",
+      "format": "number",
+      "visualization": "kpi-card",
+      "dataSource": "Entity",
+      "thresholds": { "warning": 100, "critical": 50 }
+    },
+    {
+      "code": "items-by-status",
+      "label": "Items by Status",
+      "metric": "COUNT(entity) GROUP BY status",
+      "format": "number",
+      "visualization": "pie",
+      "dataSource": "Entity",
+      "dimensions": ["status"]
+    }
+  ],
+  "filters": [
+    { "field": "dateRange", "type": "dateRange", "label": "Période" },
+    { "field": "status", "type": "multiselect", "label": "Statut" }
+  ],
+  "permissionsRequired": ["business.{app}.{module}.read"]
+}
+```
+
+5. **ALSO generate the standard ASCII mockup** for the dashboard with KPI cards + chart placeholders:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  {Module} > Dashboard              Période: [Ce mois ▾]     ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    ║
+║  │ KPI #1   │  │ KPI #2   │  │ KPI #3   │  │ KPI #4   │    ║
+║  │  1,234   │  │  567     │  │  89.2%   │  │  12,400  │    ║
+║  │  ↑ +12%  │  │  ↓ -3%  │  │  → 0%   │  │  ↑ +5%   │    ║
+║  └──────────┘  └──────────┘  └──────────┘  └──────────┘    ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌─────────────────────────┐  ┌─────────────────────────┐    ║
+║  │  [Bar Chart]            │  │  [Pie Chart]            │    ║
+║  │  Items by Month         │  │  Items by Status        │    ║
+║  │  ████                   │  │      ████████           │    ║
+║  │  ████ ████              │  │   ███      ███          │    ║
+║  │  ████ ████ ████         │  │  ██   42%    ██         │    ║
+║  └─────────────────────────┘  └─────────────────────────┘    ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Store the mockup in specification.wireframes[] AS WELL (for visual reference).