@atlashub/smartstack-cli 4.74.0 → 4.76.0

package/templates/skills/business-analyse/references/04-cross-module-validation.md

@@ -0,0 +1,95 @@
+# Cross-Module Validation Rules
+
+> **Purpose:** Define FK validation, circular dependency detection, and dependency graph checks
+> that must be executed before consolidation approval.
+
+## Module Index Files & Granular Data Loading
+
+For each completed module, read `index.json` and discover granular files:
+
+```javascript
+const moduleFiles = {
+  entities: "entities.json",
+  rules: "rules.json",
+  usecases: "usecases.json",
+  permissions: "permissions.json",
+  screens: "screens.json"
+};
+
+for (const module of completedModules) {
+  const index = ba-reader.readSection(module.code, "index");
+  module.files = index.files;
+  // Load only files needed for consolidation
+  module.entities = ba-reader.readSection(module.code, "entities");
+  module.permissions = ba-reader.readSection(module.code, "permissions");
+}
+```
+
+## Foreign Key References & Shared Entities Validation
+
+Build entity registry and validate cross-module references:
+
+```javascript
+const entityRegistry = {};
+for (const module of completedModules) {
+  entityRegistry[module.code] = {
+    entities: module.entities.map(e => ({
+      name: e.name,
+      attributes: e.attributes.map(a => a.name),
+      pk: e.attributes.find(a => a.name === "Id" || a.unique)?.name || "Id"
+    }))
+  };
+}
+
+// Detect shared entities
+const sharedEntities = [];
+for (const module of completedModules) {
+  for (const entity of module.entities) {
+    for (const rel of entity.relationships || []) {
+      if (rel.target.includes(".")) {
+        const [targetModule, targetEntity] = rel.target.split(".");
+        if (!entityRegistry[targetModule]) {
+          BLOCKING_ERROR(`Module ${module.code}: references non-existent module "${targetModule}"`);
+        }
+        sharedEntities.push({
+          entity: targetEntity,
+          definedIn: targetModule,
+          referencedBy: module.code,
+          referenceType: rel.type
+        });
+      }
+    }
+  }
+}
+```
+
+## Circular Dependency Detection
+
+```javascript
+const cycles = detectCycles(dependencyGraph);
+if (cycles.length > 0) {
+  BLOCKING_ERROR("Circular dependencies detected:");
+  for (const cycle of cycles) {
+    ERROR(`  ${cycle.join(" → ")}`);
+  }
+  ACTIONS: Review dependencies, move shared entities to Core module, or use event-driven communication
+  STOP - DO NOT PROCEED
+}
+```
+
+## Cross-Module Interactions Display
+
+```
+═══════════════════════════════════════════════════════════════
+  CROSS-MODULE INTERACTIONS VALIDATED
+═══════════════════════════════════════════════════════════════
+
+| Source Module | Target | Type | Status |
+|---------------|--------|------|--------|
+| Orders        | Customers.Customer | FK (N:1) | ✓ RESOLVED |
+| Invoices      | Customers.Customer | FK (N:1) | ✓ RESOLVED |
+
+Total: {count} cross-module references
+Shared entities: {count}
+═══════════════════════════════════════════════════════════════
+```

package/templates/skills/business-analyse/references/04-file-allocation.md

@@ -0,0 +1,162 @@
+# File Allocation Rules
+
+> **Critical reference:** Defines which validation data belongs in `consolidation.json` vs `validation.json`.
+> Mixing contents across files is a BLOCKING ERROR.
+
+## Strict Allocation Table
+
+```
++==============================================================================+
+|  FILE ALLOCATION REFERENCE — MANDATORY                                       |
++==============================================================================+
+|                                                                              |
+|  consolidation.json contient UNIQUEMENT :                                    |
+|    - crossModuleInteractions                                                 |
+|    - sharedEntities                                                          |
+|    - permissionCoherence                                                     |
+|    - e2eFlows                                                                |
+|    - decision (approval)                                                     |
+|                                                                              |
+|  validation.json contient UNIQUEMENT :                                       |
+|    - semanticChecks                                                          |
+|    - contractChecks                                                          |
+|    - namingAudit                                                             |
+|    - acceptanceCriteria                                                      |
+|    - globalRiskAssessment                                                    |
+|                                                                              |
+|  INTERDICTION de melanger les contenus entre les deux fichiers.              |
+|  Toute cle ecrite dans le mauvais fichier = ERREUR BLOQUANTE.               |
+|                                                                              |
++==============================================================================+
+```
+
+## Data Structures
+
+### consolidation.json structure
+
+```javascript
+{
+  crossModuleInteractions: [
+    {
+      fromModule: string,
+      toModule: string,
+      interactionType: "FK-reference|event|shared-lookup",
+      description: string,
+      entities: string[]
+    }
+  ],
+  sharedEntities: [
+    {
+      entity: string,
+      ownerModule: string,
+      referencedBy: string[],
+      sharedFields: string[]
+    }
+  ],
+  permissionCoherence: {
+    rolesConsistent: boolean,
+    pathFormatConsistent: boolean,
+    hierarchyRespected: boolean,
+    conflicts: any[],
+    warnings: any[]
+  },
+  e2eFlows: [
+    {
+      name: string,
+      modules: string[],
+      steps: object[]
+    }
+  ],
+  decision: {
+    approved: boolean,
+    reason: string,
+    approvedBy: string,
+    approvedAt: string
+  }
+}
+```
+
+### validation.json structure
+
+```javascript
+{
+  semanticChecks: [
+    {
+      check: string,
+      status: "PASS|WARNING|ERROR",
+      details: string[]
+    }
+  ],
+  contractChecks: [
+    {
+      module: string,
+      check: string,
+      details: string
+    }
+  ],
+  namingAudit: {
+    auditedAt: string,
+    issues: object[],
+    approved: boolean,
+    renames: object[]
+  },
+  acceptanceCriteria: [
+    {
+      module: string,
+      criteria: string,
+      type: "functional|business-rule|performance|security"
+    }
+  ],
+  globalRiskAssessment: [
+    {
+      risk: string,
+      severity: "low|medium|high",
+      mitigation?: string
+    }
+  ]
+}
+```
+
+## Data Writing Pattern
+
+Write consolidation.json:
+```javascript
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "consolidation",
+  data: {
+    crossModuleInteractions: [...],
+    sharedEntities: [...],
+    permissionCoherence: {...},
+    e2eFlows: [...],
+    decision: {...}
+  }
+});
+```
+
+Write validation.json:
+```javascript
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "validation",
+  data: {
+    semanticChecks: [...],
+    contractChecks: [...],
+    namingAudit: {...},
+    acceptanceCriteria: [...],
+    globalRiskAssessment: [...]
+  }
+});
+```
+
+## Validation Checklist
+
+Before writing either file, verify:
+
+- ✓ No keys from consolidation.json appear in validation.json
+- ✓ No keys from validation.json appear in consolidation.json
+- ✓ All cross-module FK references are in consolidation.json (not validation.json)
+- ✓ All semantic check results are in validation.json (not consolidation.json)
+- ✓ All naming audit results are in validation.json (not consolidation.json)
+- ✓ Client approval decision is in consolidation.json (not validation.json)
+- ✓ Risk assessment is in validation.json (not consolidation.json)

package/templates/skills/business-analyse/references/04-naming-audit-checks.md

@@ -0,0 +1,174 @@
+# Naming Audit Checks
+
+> **Purpose:** Validate that all application names, module codes, entity names, and permission paths follow conventions,
+> derive logically from their labels, and are free of collisions.
+
+## Naming Registry Collection
+
+Collect all names from the BA:
+
+```javascript
+const namingRegistry = {
+  application: {
+    label: application_name,
+    code: applicationCode,              // PascalCase
+    route: toKebabCase(applicationCode)  // kebab-case
+  },
+  modules: completedModules.map(m => ({
+    label: m.name,
+    code: m.code,                        // PascalCase
+    route: toKebabCase(m.code)           // kebab-case
+  })),
+  entities: completedModules.flatMap(m =>
+    m.entities.map(e => ({
+      name: e.name,                      // PascalCase (C# class name)
+      module: m.code,
+      tableName: e.tableName || pluralize(e.name)  // Plural convention
+    }))
+  ),
+  permissionRoots: [...new Set(
+    permissionPaths.map(p => p.path.split('.').slice(0, 2).join('.'))
+  )]
+};
+```
+
+## Naming Recap Display
+
+```
+═══════════════════════════════════════════════════════════════
+  NAMING AUDIT — {application_name}
+═══════════════════════════════════════════════════════════════
+
+APPLICATION
+| Label | Code (PascalCase) | Route (kebab-case) |
+|-------|-------------------|--------------------|
+| {application_name} | {applicationCode} | /{route} |
+
+MODULES
+| # | Label | Code (PascalCase) | Route (kebab-case) |
+|---|-------|-------------------|--------------------|
+{for each module: index | label | code | /app-route/module-route}
+
+ENTITIES
+| Entity (PascalCase) | Module | Table (plural) |
+|----------------------|--------|----------------|
+{for each entity: name | module | tableName}
+
+PERMISSION ROOTS
+{for each root: path}
+═══════════════════════════════════════════════════════════════
+```
+
+## Coherence Checks
+
+```javascript
+const namingIssues = [];
+
+// 1. Duplicate entity names across modules
+const entityNames = namingRegistry.entities.map(e => e.name);
+const duplicates = entityNames.filter((n, i) => entityNames.indexOf(n) !== i);
+if (duplicates.length > 0) {
+  namingIssues.push({ severity: "ERROR", issue: `Duplicate entity names: ${[...new Set(duplicates)].join(', ')}` });
+}
+
+// 2. Module code vs label coherence (code should derive logically from label)
+for (const mod of namingRegistry.modules) {
+  if (!mod.code || mod.code.length < 2) {
+    namingIssues.push({ severity: "ERROR", issue: `Module "${mod.label}" has invalid code: "${mod.code}"` });
+  }
+}
+
+// 3. Permission root alignment with module codes
+for (const root of namingRegistry.permissionRoots) {
+  const [appSegment, moduleSegment] = root.split('.');
+  const matchingModule = namingRegistry.modules.find(m =>
+    m.code.toLowerCase() === moduleSegment.toLowerCase()
+  );
+  if (!matchingModule) {
+    namingIssues.push({ severity: "WARNING", issue: `Permission root "${root}" has no matching module code` });
+  }
+}
+
+// 4. Route collision detection
+const allRoutes = namingRegistry.modules.map(m =>
+  `/${namingRegistry.application.route}/${m.route}`
+);
+const routeDuplicates = allRoutes.filter((r, i) => allRoutes.indexOf(r) !== i);
+if (routeDuplicates.length > 0) {
+  namingIssues.push({ severity: "ERROR", issue: `Route collisions: ${routeDuplicates.join(', ')}` });
+}
+```
+
+## MCP Validation
+
+```
+mcp__smartstack__validate_conventions({
+  checks: ["tables"],
+  context: {
+    applicationCode: applicationCode,
+    modules: namingRegistry.modules.map(m => m.code),
+    entities: namingRegistry.entities.map(e => e.name)
+  }
+})
+
+→ Merge MCP findings into namingIssues[]
+```
+
+## User Confirmation Flow
+
+**IF namingIssues.length > 0:**
+
+Display issues table:
+```
+| # | Severity | Issue |
+|---|----------|-------|
+{for each issue}
+```
+
+Ask via AskUserQuestion:
+```
+question: "{language == 'fr'
+  ? 'Validez-vous les noms ci-dessus pour l\\'ensemble de l\\'application ?'
+  : 'Do you approve all the names above for the entire application?'}"
+header: "Naming Audit"
+options:
+  - label: "{language == 'fr' ? 'Approuvé' : 'Approved'}"
+    description: "{language == 'fr' ? 'Tous les noms sont corrects' : 'All names are correct'}"
+  - label: "{language == 'fr' ? 'Renommer certains éléments' : 'Rename some elements'}"
+    description: "{language == 'fr' ? 'Corriger des noms avant de finaliser' : 'Fix names before finalizing'}"
+```
+
+**IF "Renommer certains éléments":**
+
+Ask via AskUserQuestion (open-ended):
+```
+question: "{language == 'fr'
+  ? 'Quels éléments souhaitez-vous renommer ? (ex: \"Module Ventes → Commerce\", \"Entity Invoice → BillingDocument\")'
+  : 'Which elements do you want to rename? (e.g., \"Module Sales → Commerce\", \"Entity Invoice → BillingDocument\")'}"
+header: "Renaming"
+```
+
+Process user response:
+1. Parse rename instructions
+2. Update `applicationCode`, module codes, entity names, permission paths accordingly in JSON files via ba-writer
+3. Re-run coherence checks on updated names
+4. Re-run MCP validation on updated names
+5. Re-display the naming recap table for final confirmation
+
+**IF "Approuvé":**
+
+Store naming audit result in `validation.json`:
+```javascript
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "namingAudit",
+  data: {
+    auditedAt: now(),
+    issues: namingIssues,
+    approved: true,
+    renames: []  // or list of applied renames
+  }
+});
+```
+
+Continue to next section.

package/templates/skills/business-analyse/references/04-semantic-validation-matrix.md

@@ -0,0 +1,118 @@
+# Semantic Validation Matrix
+
+> **Purpose:** Define all semantic validation checks and contract verification rules required before consolidation approval.
+> These checks catch data integrity gaps and ensure downstream skills have complete information.
+
+## 13 Semantic Checks (Per Module)
+
+Execute these checks for each completed module:
+
+```javascript
+const semanticChecks = [
+  { check: "permission-orpheline", severity: "WARNING" },
+  { check: "uc-sans-fr", severity: "WARNING" },
+  { check: "entity-sans-endpoint", severity: "WARNING" },
+  { check: "uc-sans-scenario", severity: "WARNING" },
+  { check: "role-sans-permissions", severity: "WARNING" },
+  { check: "navigation-sans-traduction", severity: "ERROR" },
+  { check: "lifecycle-terminal", severity: "WARNING" },
+  { check: "schema-conformity", severity: "ERROR" },
+  { check: "wireframe-coverage", severity: "ERROR" },
+  { check: "entity-doublon", severity: "ERROR" },
+  { check: "permission-fantome", severity: "ERROR" },
+  { check: "dashboard-coverage", severity: "WARNING" },
+  { check: "permission-uc-alignment", severity: "WARNING" }
+];
+```
+
+**Blocking rule:** 0 ERROR → PASS, ≥1 ERROR → BLOCK (user must fix before proceeding)
+
+## Contract Verification (Per Module)
+
+Verify the data contract that downstream skills (`/business-analyse-handoff`, `/business-analyse-develop`) depend on.
+These checks catch gaps that abstract semantic checks miss.
+
+```javascript
+for (const module of completedModules) {
+  const ent = module.entities || [];
+  const brs = ba-reader.readSection(module.code, "rules")?.rules || [];
+  const ucs = ba-reader.readSection(module.code, "usecases")?.useCases || [];
+  const perms = ba-reader.readSection(module.code, "permissions");
+
+  // CHECK 1: BR-CALC must have formula (C13)
+  for (const br of brs) {
+    if (br.category === 'calculation' && !br.formula) {
+      errors.push({module: module.code, check: "br-calc-sans-formula",
+        details: `${br.id} is category:calculation but missing 'formula' field`});
+    }
+  }
+
+  // CHECK 2: Computed attributes must have corresponding BR-CALC (C11)
+  for (const entity of ent) {
+    for (const attr of (entity.attributes || [])) {
+      if (attr.computed === true) {
+        const hasBRCalc = brs.some(br =>
+          br.category === 'calculation' && (br.entities || []).includes(entity.name)
+        );
+        if (!hasBRCalc) {
+          errors.push({module: module.code, check: "computed-sans-br-calc",
+            details: `${entity.name}.${attr.name} is computed:true but no BR-CALC references ${entity.name}`});
+        }
+      }
+    }
+  }
+
+  // CHECK 3: UC count minimum (C6)
+  if (ucs.length < 4) {
+    errors.push({module: module.code, check: "uc-count-critical",
+      details: `Only ${ucs.length} use cases (minimum: 4)`});
+  } else if (ucs.length < 6) {
+    warnings.push({module: module.code, check: "uc-count-low",
+      details: `Only ${ucs.length} use cases (recommended: >= 6)`});
+  }
+
+  // CHECK 4: Permission path count (C7)
+  const permCount = perms?.permissionPaths?.length || 0;
+  if (permCount < 5) {
+    warnings.push({module: module.code, check: "permission-count-low",
+      details: `Only ${permCount} permission paths (recommended: >= 5 — check for missing Export/Import)`});
+  }
+
+  // CHECK 5: Versioned attributes detection (C15)
+  const sensitiveKeywords = ['salary', 'rate', 'grade', 'price', 'tarif'];
+  for (const entity of ent) {
+    for (const attr of (entity.attributes || [])) {
+      if (sensitiveKeywords.some(k => attr.name.toLowerCase().includes(k))) {
+        if (!entity.versionedAttributes?.length) {
+          warnings.push({module: module.code, check: "missing-versioned-attributes",
+            details: `${entity.name}.${attr.name} may need versioning but no versionedAttributes defined`});
+        }
+      }
+    }
+  }
+}
+```
+
+## Execution Logic
+
+```javascript
+for (const module of completedModules) {
+  for (const check of semanticChecks) {
+    const result = executeSemanticCheck(module, check);
+    if (result.status === "ERROR") {
+      errors.push({module: module.code, check: check.check, details: result.details});
+    } else if (result.status === "WARNING") {
+      warnings.push({module: module.code, check: check.check, details: result.details});
+    }
+  }
+}
+
+// Blocking rule: 0 ERROR → PASS, ≥1 ERROR → BLOCK (ask user for each)
+if (errors.length > 0) {
+  BLOCKING_ERROR("Semantic validation failed");
+  for (const error of errors) {
+    ERROR(`  [${error.module}] ${error.check}: ${error.details}`);
+  }
+  STOP - User must fix before proceeding
+}
+```

package/templates/skills/business-analyse/references/canonical-json-formats.md

@@ -83,9 +83,10 @@
       "category": "validation",
       "sectionCode": "list",
       "statement": "La date ne peut pas être dans le futur",
-      "example": "Date = 2027-01-01 → erreur",
+      "severity": "blocking",
       "entities": ["Employee"],
-      "severity": "blocking"
+      "examples": [{ "input": "date = 2027-01-01", "expected": "Erreur : date dans le futur" }],
+      "domainSpecific": false
     }
   ]
 }
@@ -95,7 +96,10 @@
 |---------------|------------------------|
 | `rules` (root) | `businessRules` |
 | `statement` | `description` |
-| `id` | `name` (as identifier) |
+| `id` | `name` (as identifier), `code` |
+| `examples` (array of `{input, expected}`) | `example` (singular string) |
+| `category` | `type` |
+| `name` | `label` |
 
 Categories: `validation`, `calculation`, `workflow`, `security`, `data`, `notification`