@atlashub/smartstack-cli 4.75.0 → 4.76.0

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

@@ -31,6 +31,26 @@ function resolveModuleDir(appCode, moduleCode) {
 > **Module directory (ba-006):** `mod.dir = resolveModuleDir(applicationCode, module.code)`
 > Example: `docs/projet-rh/v1.0/human-resources/employees/`
 
+## ENFORCEMENT LANGUE (OBLIGATOIRE)
+
+Toutes les valeurs textuelles générées dans les fichiers JSON de ce module DOIVENT être rédigées en `{language}` :
+
+| Champ JSON | Langue | Exemple FR | Exemple EN |
+|------------|--------|-----------|-----------|
+| entity.description | `{language}` | "Représente un employé" | "Represents an employee" |
+| attribute.description | `{language}` | "Code unique de l'employé" | "Unique employee code" |
+| rule.statement | `{language}` | "Le code doit être unique" | "Code must be unique" |
+| rule.examples[].input | `{language}` | "code='EMP-001', doublon" | "code='EMP-001', duplicate" |
+| rule.examples[].expected | `{language}` | "Erreur : code déjà existant" | "Error: code already exists" |
+| usecase.name | `{language}` | "Créer un employé" | "Create employee" |
+| usecase.mainScenario[] | `{language}` | "L'utilisateur ouvre la page" | "User opens the page" |
+| usecase.preconditions[] | `{language}` | "L'utilisateur est connecté" | "User is logged in" |
+| permission.description | `{language}` | "Consulter la liste" | "View the list" |
+
+**Identifiants techniques** (PascalCase) restent en anglais : `Employee`, `AbsenceBalance`, `status`, `BR-VAL-EMP-001`.
+
+**VIOLATION = contenu rejeté à la consolidation (step-04).**
+
 ## Prerequisites
 
 - Step 02 (structure) completed
@@ -82,6 +102,11 @@ Display(`Scope locked: ${expectedApps} app(s), ${confirmedModules.length} module
 |     - INTERDICTION de spawner des ba-writer pour des modules NON encore      |
 |       valides par le client                                                  |
 |                                                                              |
+|  6. JAMAIS "accelerer" en batchant des modules dans des sub-agents.          |
+|     Sub-agents (Agent/Snipper) n'ont PAS acces au schema JSON canonique.     |
+|     PREUVE: audit ba-012 → 4 dialectes JSON, conformite 95% → 35%.          |
+|     Si > 10 modules: maintenir le sequentiel, le retravail coute plus.       |
+|                                                                              |
 +==============================================================================+
 
 ## Sequential Execution
@@ -349,9 +374,12 @@ IF module has workflow states OR approval patterns:
     - BR-VAL-ABS-008: "Medical certificate required for absences > 3 days" [domainSpecific]
     - BR-SEC-ABS-001: "Manager cannot approve their own absences" [domainSpecific]
 
-ELSE (non-workflow module):
+ELSE (non-workflow module with >= 2 entities):
+  SHOULD WebSearch: "{module_domain} data validation rules best practices"
   → Use entity patterns from A-bis for validation rules
   → Load archetype rules from module-completeness-challenge.md
+  → For each archetype rule relevant to this module type, ADD to proposal
+  → Mark rules from research with domainSpecific: true
 ```
 
 ### C-bis. Client Validation — Business Rules (OBLIGATOIRE)
@@ -363,13 +391,63 @@ ELSE (non-workflow module):
    - Patterns domaine (A-bis) : validations standards, calculs attendus
    - Cadrage : errorFlows, processus décrits
 
+   > **Schema:** ALL fields defined in `schemas/sections/analysis-schema.json` property `businessRules`. Use EXACT canonical field names (`id`, `name`, `category`, `statement`, `severity`, `entities`, `examples`, `sectionCode`, `domainSpecific`).
+
    **ENRICHISSEMENT OBLIGATOIRE pour chaque règle :**
 
    Pour chaque BR proposée, inclure ces champs :
    - `severity` : TOUJOURS spécifier (blocking/warning/info)
    - `sectionCode` : TOUJOURS spécifier (section où la règle s'applique)
-   - `examples[]` : OBLIGATOIRE — au moins 1 exemple structuré `{input, expected}`
-     Ex: `{ input: "debut=15/03 fin=12/03", expected: "Erreur : date de fin avant date de debut" }`
+   - `examples[]` : OBLIGATOIRE — format **test-ready** `{scenario, description, given, when, then}`
+     Chaque exemple est un **jeu de test** avec des valeurs concrètes (pas de prose).
+     Minimum **2 exemples** par règle : `happy_path` + `error` (ou `calculation` + `boundary`).
+
+     **Format par catégorie :**
+     - `validation` :
+       ```json
+       { "scenario": "happy_path", "description": "Code unique accepté",
+         "given": { "Employee.code": "EMP-00042", "existingCodes": [] },
+         "when": "create",
+         "then": { "result": "success" } }
+       { "scenario": "error", "description": "Code dupliqué rejeté",
+         "given": { "Employee.code": "EMP-00001", "existingCodes": ["EMP-00001"] },
+         "when": "create",
+         "then": { "result": "error", "message": "Code déjà existant", "field": "code" } }
+       ```
+     - `calculation` :
+       ```json
+       { "scenario": "calculation", "description": "Solde avec report",
+         "given": { "AbsenceBalance.entitled": 25, "AbsenceBalance.carriedForward": 3, "AbsenceBalance.taken": 12 },
+         "when": "calculate_remaining",
+         "then": { "AbsenceBalance.remaining": 16, "formula": "25 + 3 - 12 = 16" } }
+       { "scenario": "boundary", "description": "Solde à zéro",
+         "given": { "AbsenceBalance.entitled": 10, "AbsenceBalance.carriedForward": 0, "AbsenceBalance.taken": 10 },
+         "when": "calculate_remaining",
+         "then": { "AbsenceBalance.remaining": 0 } }
+       ```
+     - `workflow` :
+       ```json
+       { "scenario": "happy_path", "description": "Transition Draft→Submitted",
+         "given": { "Absence.status": "Draft" },
+         "when": "submit",
+         "then": { "Absence.status": "Submitted", "result": "success" } }
+       { "scenario": "error", "description": "Transition interdite Approved→Draft",
+         "given": { "Absence.status": "Approved" },
+         "when": "submit",
+         "then": { "result": "error", "message": "Transition non autorisée" } }
+       ```
+     - `security` :
+       ```json
+       { "scenario": "happy_path", "description": "Admin accède à toutes les fiches",
+         "given": { "user.role": "RH Admin", "Employee.departmentId": "any" },
+         "when": "read",
+         "then": { "result": "success", "scope": "all" } }
+       { "scenario": "error", "description": "Employé accède uniquement à sa fiche",
+         "given": { "user.role": "Employé", "target.employeeId": "other-user" },
+         "when": "read",
+         "then": { "result": "error", "message": "Accès limité à votre fiche" } }
+       ```
+     **Fallback** : `{input, expected}` accepté mais marqué WARNING "format non test-ready".
    - `conditions[]` : OBLIGATOIRE pour les règles conditionnelles (IF/THEN) — structuré `{entity, field, operator, value}`
      Ex: `[{ entity: "Absence", field: "type", operator: "==", value: "Maladie" }, { entity: "Absence", field: "duration", operator: ">", value: 3 }]`
    - `consequences[]` : OBLIGATOIRE pour les règles avec effets de bord
@@ -378,9 +456,20 @@ ELSE (non-workflow module):
    - `domainSpecific: true` si la règle vient de la recherche domaine (C-pre)
 
    **Minimums par module métier (hors Portal/config) :**
-   - >= 4 règles avec `examples[]` structurés `{input, expected}`
+   - 100% des règles avec `examples[]` non vide (minimum 2 par règle : happy_path + error)
+   - >= 4 règles avec exemples test-ready `{scenario, given, when, then}`
    - >= 2 règles avec `conditions[]` structurés
    - >= 1 règle avec `consequences[]`
+   - Toute BR-CALC avec un exemple `calculation` contenant des valeurs numériques chiffrées
+
+   **Self-check AVANT présentation client :**
+   ```
+   domainCount = rules.filter(r => r.domainSpecific === true).length
+   IF domainCount < 2 AND module is NOT config/lookup/Portal:
+     SELF-CHECK: "Only {domainCount} domain-specific rules."
+     → Re-examine module-completeness-challenge.md archetypes for this module type
+     → Add at least 2 domain-specific rules before presenting to client
+   ```
 
 2. **Présenter le LOT complet** (markdown PUIS AskUserQuestion) :
    ```
@@ -398,6 +487,60 @@ ELSE (non-workflow module):
    - Q3.8 si les relations inter-champs sont complexes
    - Q3.9 si les données sensibles ne sont pas identifiées
 
+4. **POST-VALIDATION : Qualité test-ready des exemples (OBLIGATOIRE)**
+
+   Après validation client des règles métier, vérifier la qualité des exemples AVANT écriture :
+
+   ```javascript
+   // 1. Règles sans aucun exemple
+   const rulesWithoutExamples = module.rules.filter(r =>
+     !r.examples || r.examples.length === 0
+   );
+   if (rulesWithoutExamples.length > 0) {
+     // Auto-générer des exemples test-ready à partir du statement et des conditions
+     for (const rule of rulesWithoutExamples) {
+       rule.examples = generateTestReadyExamples(rule);
+       // Génère minimum: 1 happy_path + 1 error avec given/when/then
+     }
+     Display(`${rulesWithoutExamples.length} règle(s) complétée(s) avec exemples test-ready auto-générés.`);
+   }
+
+   // 2. Règles avec exemples en prose (ancien format {input, expected} sans given/when/then)
+   const proseExamples = module.rules.filter(r =>
+     r.examples?.length > 0 && !r.examples.some(e => e.given && e.when && e.then)
+   );
+   if (proseExamples.length > 0) {
+     // Convertir les exemples prose en format test-ready
+     for (const rule of proseExamples) {
+       rule.examples = rule.examples.map(e => convertToTestReady(e, rule));
+     }
+     Display(`${proseExamples.length} règle(s) converties du format prose au format test-ready.`);
+   }
+
+   // 3. BR-CALC sans exemple chiffré
+   const calcWithoutNumbers = module.rules.filter(r =>
+     r.category === 'calculation' &&
+     !r.examples?.some(e => e.scenario === 'calculation' || (e.then && Object.values(e.then).some(v => typeof v === 'number')))
+   );
+   if (calcWithoutNumbers.length > 0) {
+     Display(`⚠ ${calcWithoutNumbers.length} BR-CALC sans exemple chiffré — ajouter des valeurs numériques.`);
+   }
+
+   // 4. Vérification minimale
+   const testReady = module.rules.filter(r =>
+     r.examples?.some(e => e.given && e.when && e.then)
+   );
+   if (testReady.length < 4 && module.featureType !== 'portal') {
+     Display(`⚠ ${testReady.length}/4 règles au format test-ready {given, when, then}. Enrichir.`);
+   }
+   ```
+
+   **Minimum requis par module métier (hors Portal/config) :**
+   - 100% des règles avec `examples[]` non vide (minimum 2 par règle)
+   - >= 4 règles avec exemples test-ready `{scenario, given, when, then}`
+   - Toute BR-CALC avec un exemple `calculation` contenant des valeurs numériques
+   - Zéro exemple en prose vague (tout doit être en format `given/when/then`)
+
 INTERDICTION de passer à D (Use Cases) tant que le client n'a pas validé les règles.
 
 ### D. Use Cases
@@ -767,6 +910,21 @@ For EACH apiEndpoint in module:
 
 **criture :** Stocker dans `usecases.json` sous la cl `apiEndpoints[]` (enrichi).
 
+### H-pre. Schema Refresh (OBLIGATOIRE avant chaque ecriture)
+
+AVANT d'ecrire les JSON pour le module courant :
+→ **Relire** `references/03-json-schemas.md` section "Business Rules Schema Format"
+→ Verifier que CHAQUE rule dans le buffer utilise les champs canoniques :
+  - `id` (pas `code`), `name` (pas `label`), `statement` (pas `description`/`rule`),
+    `category` (pas `type`), `severity` (blocking/warning/info, pas Error/error),
+    `examples[]` (array d'`{input, expected}`, pas string), `entities[]`, `sectionCode`
+→ SI un champ deprecated est detecte : corriger AVANT ecriture
+→ Ce refresh prend ~30 secondes et previent 100% des derives de schema
+
+**POURQUOI ce refresh :** Apres 5+ modules, le contexte est compacte et les exemples
+JSON du debut de conversation sont perdus. Ce refresh garantit que chaque module
+est ecrit avec le format canonique, meme si le contexte a ete compresse.
+
 ### H. Write & Advance (SEULEMENT apres validation complete)
 
 > **GATE:** ba-writer ne peut etre lance QUE si le client a valide :

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

@@ -244,6 +244,120 @@ This includes:
 - 5 contract verification checks (BR formulas, computed attributes, UC counts, permission counts, versioned attributes)
 - Blocking rule: 0 ERROR → PASS, ≥1 ERROR → BLOCK (user must fix before proceeding)
 
+**BR-EXAMPLES-COMPLETE check — qualité test-ready (NEW):**
+```javascript
+for (const module of completedModules) {
+  const rules = module.rules || [];
+  if (rules.length === 0) continue;
+
+  // 1. Couverture : toutes les règles doivent avoir des exemples
+  const withExamples = rules.filter(r => r.examples?.length > 0);
+  const exampleRate = withExamples.length / rules.length;
+
+  if (exampleRate < 0.4) {
+    ERROR(`Module ${module.code}: ${withExamples.length}/${rules.length} BRs ont des exemples (${Math.round(exampleRate*100)}% < 40% minimum) — BLOQUANT`);
+  } else if (exampleRate < 0.7) {
+    WARNING(`Module ${module.code}: ${withExamples.length}/${rules.length} BRs ont des exemples (${Math.round(exampleRate*100)}% — cible: 100%)`);
+  }
+
+  // 2. Format test-ready : exemples avec given/when/then
+  const testReady = rules.filter(r =>
+    r.examples?.some(e => e.given && e.when && e.then)
+  );
+  const proseOnly = rules.filter(r =>
+    r.examples?.length > 0 && !r.examples.some(e => e.given && e.when && e.then)
+  );
+
+  if (testReady.length < 4 && module.featureType !== 'portal') {
+    WARNING(`Module ${module.code}: ${testReady.length}/4 BRs au format test-ready {given, when, then}`);
+  }
+  if (proseOnly.length > 0) {
+    WARNING(`Module ${module.code}: ${proseOnly.length} BRs avec exemples en prose — convertir en format test-ready pour génération de tests`);
+  }
+
+  // 3. BR-CALC : formule + exemple chiffré obligatoires
+  const calcRules = rules.filter(r => r.category === 'calculation');
+  const calcWithoutFormula = calcRules.filter(r => !r.formula);
+  const calcWithoutNumericExample = calcRules.filter(r =>
+    !r.examples?.some(e =>
+      (e.scenario === 'calculation') ||
+      (e.then && Object.values(e.then).some(v => typeof v === 'number'))
+    )
+  );
+
+  if (calcWithoutFormula.length > 0) {
+    ERROR(`Module ${module.code}: ${calcWithoutFormula.length} BR-CALC sans champ formula`);
+  }
+  if (calcWithoutNumericExample.length > 0) {
+    WARNING(`Module ${module.code}: ${calcWithoutNumericExample.length} BR-CALC sans exemple chiffré — les tests de calcul nécessitent des valeurs numériques`);
+  }
+
+  // 4. Couverture scénarios : chaque règle devrait avoir happy_path + error
+  const withBothScenarios = rules.filter(r =>
+    r.examples?.some(e => e.scenario === 'happy_path' || e.then?.result === 'success') &&
+    r.examples?.some(e => e.scenario === 'error' || e.then?.result === 'error')
+  );
+  if (withBothScenarios.length < rules.length * 0.5 && module.featureType !== 'portal') {
+    WARNING(`Module ${module.code}: ${withBothScenarios.length}/${rules.length} BRs couvrent happy_path + error — cible: 100%`);
+  }
+}
+```
+
+### 4b. Language Coherence Check (MANDATORY)
+
+Verify that ALL generated content respects `{language}` from config:
+
+```javascript
+const expectedLang = language; // from config.json
+
+// Heuristics for language detection
+const frIndicators = /\b(le|la|les|un|une|des|du|de|est|sont|doit|peut|dans|pour|avec|sur|par|cette|tout|qui)\b/i;
+const enIndicators = /\b(the|a|an|is|are|must|can|in|for|with|on|by|this|all|who|should|when|each)\b/i;
+
+function detectLang(text) {
+  if (!text || text.length < 10) return null;
+  const frScore = (text.match(frIndicators) || []).length;
+  const enScore = (text.match(enIndicators) || []).length;
+  if (frScore > enScore * 1.5) return 'fr';
+  if (enScore > frScore * 1.5) return 'en';
+  return null; // ambiguous
+}
+
+const langIssues = [];
+for (const module of completedModules) {
+  // Sample entity descriptions
+  (module.entities || []).forEach(e => {
+    const detected = detectLang(e.description);
+    if (detected && detected !== expectedLang) {
+      langIssues.push({ module: module.code, type: 'entity', name: e.name, detected, text: e.description?.substring(0, 60) });
+    }
+  });
+  // Sample BR statements
+  (module.rules || []).forEach(r => {
+    const detected = detectLang(r.statement);
+    if (detected && detected !== expectedLang) {
+      langIssues.push({ module: module.code, type: 'rule', name: r.id, detected, text: r.statement?.substring(0, 60) });
+    }
+  });
+  // Sample UC names
+  (module.useCases || module.usecases || []).forEach(u => {
+    const detected = detectLang(u.name);
+    if (detected && detected !== expectedLang) {
+      langIssues.push({ module: module.code, type: 'useCase', name: u.id || u.name, detected, text: u.name });
+    }
+  });
+}
+
+if (langIssues.length > 0) {
+  WARNING(`${langIssues.length} content items detected in wrong language (expected: ${expectedLang})`);
+  Display(langIssues.slice(0, 10).map(i => `  - ${i.module}/${i.type} "${i.name}": detected ${i.detected}, text: "${i.text}"`).join('\n'));
+
+  if (langIssues.length > completedModules.length * 3) {
+    BLOCKING_ERROR(`Too many language violations (${langIssues.length}). Re-specify affected modules in ${expectedLang}.`);
+  }
+}
+```
+
 ### 5. Data Model Consolidation
 
 Generate global entity relationship diagram:
@@ -389,7 +503,98 @@ for (const step of flow.steps) {
 
 Store as `consolidation.mermaidDiagrams.sequences[{flowName}]` (string).
 
-#### 5b-iv. Storage
+#### 5b-iv. Use Case Diagrams (per module)
+
+For EACH module, generate a Mermaid use case diagram showing actors and their interactions:
+
+```javascript
+const useCaseDiagrams = {};
+
+for (const module of completedModules) {
+  const usecases = module.useCases || module.usecases || [];
+  if (usecases.length === 0) continue;
+
+  // Collect unique actors
+  const actors = [...new Set(usecases.map(uc => uc.primaryActor || uc.actor).filter(Boolean))];
+
+  // Build flowchart-based UC diagram (Mermaid does not have native usecase syntax)
+  let diagram = "flowchart LR\n";
+
+  // Add actors (left side)
+  actors.forEach((actor, i) => {
+    const actorId = 'actor_' + actor.replace(/[^a-zA-Z0-9]/g, '_');
+    diagram += `  ${actorId}[/"👤 ${actor}"\\]\n`;
+    diagram += `  style ${actorId} fill:#e1f5fe,stroke:#0288d1,color:#01579b\n`;
+  });
+
+  // Group UCs by section
+  const sections = [...new Set(usecases.map(uc => uc.sectionCode).filter(Boolean))];
+
+  sections.forEach(section => {
+    const sectionUCs = usecases.filter(uc => uc.sectionCode === section);
+    diagram += `  subgraph ${section}["${section}"]\n`;
+    sectionUCs.forEach(uc => {
+      const ucId = (uc.id || uc.name).replace(/[^a-zA-Z0-9]/g, '_');
+      diagram += `    ${ucId}(("${uc.name}"))\n`;
+    });
+    diagram += `  end\n`;
+  });
+
+  // UCs without section
+  const noSectionUCs = usecases.filter(uc => !uc.sectionCode);
+  noSectionUCs.forEach(uc => {
+    const ucId = (uc.id || uc.name).replace(/[^a-zA-Z0-9]/g, '_');
+    diagram += `  ${ucId}(("${uc.name}"))\n`;
+  });
+
+  // Connect actors to UCs
+  usecases.forEach(uc => {
+    const actor = uc.primaryActor || uc.actor;
+    if (!actor) return;
+    const actorId = 'actor_' + actor.replace(/[^a-zA-Z0-9]/g, '_');
+    const ucId = (uc.id || uc.name).replace(/[^a-zA-Z0-9]/g, '_');
+    diagram += `  ${actorId} --> ${ucId}\n`;
+  });
+
+  useCaseDiagrams[module.code] = diagram;
+}
+```
+
+Store as `consolidation.mermaidDiagrams.useCases` (object: moduleCode → diagram string).
+
+#### 5b-v. MCD (Modèle Conceptuel de Données)
+
+Generate a simplified conceptual data model showing ONLY entity names and named relationships with cardinalities. Unlike the ERD which shows all attributes, the MCD focuses on the conceptual structure.
+
+```javascript
+let mcd = "erDiagram\n";
+
+// Entities: name + PK only (no attributes)
+for (const ent of globalEntities) {
+  mcd += `  ${ent.name} {\n`;
+  mcd += `    ${ent.pk || 'guid'} Id PK\n`;
+  mcd += `  }\n`;
+}
+
+// Named relationships with cardinalities
+for (const rel of globalRelationships) {
+  const card = rel.cardinality === "1:N" ? "||--o{" :
+               rel.cardinality === "N:1" ? "}o--||" :
+               rel.cardinality === "N:M" ? "}o--o{" :
+               rel.cardinality === "1:1" ? "||--||" : "||--o{";
+
+  // Use description as relationship label, or derive from cardinality
+  const label = rel.description ||
+    (rel.cardinality === "1:N" ? "contient" :
+     rel.cardinality === "N:1" ? "appartient" : "associe");
+
+  mcd += `  ${rel.sourceEntity} ${card} ${rel.targetEntity} : "${label}"\n`;
+}
+```
+
+Store as `consolidation.mermaidDiagrams.mcd` (string).
+
+#### 5b-vi. Storage
 
 Write to `consolidation.json`:
 
@@ -397,6 +602,11 @@ Write to `consolidation.json`:
 {
   "mermaidDiagrams": {
     "erd": "erDiagram\n  Employee {\n    guid id\n    string code\n    ...\n  }\n  ...",
+    "mcd": "erDiagram\n  Employee {\n    guid Id PK\n  }\n  Employee ||--o{ Contract : \"contient\"\n  ...",
+    "useCases": {
+      "Employees": "flowchart LR\n  actor_RH[/\"👤 RH Admin\"\\]\n  ...",
+      "Absences": "flowchart LR\n  ..."
+    },
     "stateMachines": {
       "Absence": "stateDiagram-v2\n  [*] --> Draft\n  Draft --> Submitted : submit\n  ...",
       "Invoice": "stateDiagram-v2\n  [*] --> Draft\n  ..."

package/templates/skills/business-analyse-handoff/references/agent-handoff-transform-prompt.md

@@ -47,6 +47,9 @@ When reading flat files, prefer canonical keys but fall back to alternatives:
 - `primaryActor`: `uc.primaryActor || uc.actor`
 - `mainScenario`: `uc.mainScenario || uc.steps` (if `steps[]` contains objects, extract `.action`)
 - `rules`: `data.rules || data.businessRules || []`
+- `rules[].examples`: prefer `rule.examples[]` (`{input, expected}`); fallback: wrap `rule.example` string as `[{input: rule.example, expected: ""}]`
+- `rules[].statement`: prefer `rule.statement`; fallback: `rule.description`
+- `rules[].id`: prefer `rule.id`; fallback: `rule.code`
 - `screens`: `data.sections || data.screens` (if `screens[]` exists, treat each screen as a section with 1 resource)
 
 This safety net handles pre-4.52 BA outputs. It should become unnecessary once step-03-specify enforces canonical keys.