@atlashub/smartstack-cli 4.74.0 → 4.75.0

package/templates/skills/business-analyse/references/03-post-check-validation.md

@@ -0,0 +1,144 @@
+# POST-CHECK Validation (step-03-specify)
+
+Before advancing to step 04, run these validations for EACH module:
+
+```javascript
+const errors = [];
+const warnings = [];
+
+for (const mod of modules) {
+  // mod.dir = resolveModuleDir(applicationCode, mod.code)
+  // e.g., docs/projet-rh/v1.0/human-resources/employees/
+  const ent = READ(mod.dir + '/entities.json')?.entities || [];
+  const ucs = READ(mod.dir + '/usecases.json')?.useCases || [];
+  const brs = READ(mod.dir + '/rules.json')?.rules || [];
+  const perms = READ(mod.dir + '/permissions.json');
+  const sections = mod.anticipatedSections || [];
+  const sectionCodes = new Set(sections.map(s => s.code));
+
+  // Mandatory checks (BLOCKING)
+  if (ent.length === 0) errors.push(mod.code + ": 0 entities");
+  if (ucs.length === 0) errors.push(mod.code + ": 0 use cases");
+  if (brs.length === 0) errors.push(mod.code + ": 0 business rules");
+  if (!perms?.permissionPaths?.length) errors.push(mod.code + ": no permissions");
+
+  // sectionCode validation
+  for (const uc of ucs) {
+    if (!uc.sectionCode) errors.push(mod.code + ": UC '" + uc.id + "' missing sectionCode");
+    else if (!sectionCodes.has(uc.sectionCode)) errors.push(mod.code + ": UC '" + uc.id + "' sectionCode '" + uc.sectionCode + "' not in anticipatedSections");
+  }
+  for (const br of brs) {
+    if (!br.sectionCode) errors.push(mod.code + ": BR '" + br.id + "' missing sectionCode");
+    else if (!sectionCodes.has(br.sectionCode)) errors.push(mod.code + ": BR '" + br.id + "' sectionCode '" + br.sectionCode + "' not in anticipatedSections");
+  }
+
+  // Entity attribute checks
+  for (const e of ent) {
+    for (const a of (e.attributes || [])) {
+      if (!a.type) warnings.push(mod.code + ": entity " + e.name + " attr '" + a.name + "' missing type");
+      if (a.type === 'enum' && !a.defaultValue) errors.push(mod.code + ": enum attr '" + a.name + "' missing defaultValue");
+      // FK naming convention: must end with "Id"
+      if ((a.type === 'guid' || a.type === 'string') && a.foreignKey && !a.name.endsWith('Id'))
+        warnings.push(mod.code + ": entity " + e.name + " FK attr '" + a.name + "' should end with 'Id'");
+    }
+    // Person Extension Pattern check
+    const personFields = ['firstName', 'lastName', 'email', 'phoneNumber', 'phone'];
+    const foundPersonFields = (e.attributes || []).filter(a => personFields.includes(a.name));
+    if (foundPersonFields.length >= 3 && !e.personRoleConfig) {
+      errors.push(mod.code + ": entity '" + e.name + "' has " + foundPersonFields.length +
+        " person fields (" + foundPersonFields.map(f => f.name).join(", ") +
+        ") but no personRoleConfig — use Person Extension Pattern (entity-architecture-decision.md section 0). " +
+        "Person fields (firstName, lastName, email) belong on auth_Users, not on the domain entity.");
+    }
+  }
+
+  // Canonical usecases key check
+  const rawUCFile = READ(mod.dir + '/usecases.json');
+  if (rawUCFile && !rawUCFile.useCases && rawUCFile.usecases) {
+    errors.push(mod.code + ": usecases.json uses 'usecases' key instead of canonical 'useCases' — fix before proceeding");
+  }
+  // Check steps serialization format
+  for (const uc of ucs) {
+    if (uc.steps && Array.isArray(uc.steps) && uc.steps.length > 0 && typeof uc.steps[0] === 'object') {
+      errors.push(mod.code + ": UC '" + uc.id + "' uses steps[] with objects — must use mainScenario[] with strings");
+    }
+    if (uc.actor && !uc.primaryActor) {
+      warnings.push(mod.code + ": UC '" + uc.id + "' uses 'actor' instead of canonical 'primaryActor'");
+    }
+  }
+
+  // Cross-reference checks
+  for (const uc of ucs) {
+    for (const brRef of (uc.businessRules || [])) {
+      if (!brs.find(br => br.id === brRef)) warnings.push(mod.code + ": UC '" + uc.id + "' references non-existent BR '" + brRef + "'");
+    }
+  }
+
+  // Section permission checks
+  for (const section of sections) {
+    if (section.sectionType === 'view') {
+      const viewPerms = (perms?.permissionPaths || []).filter(p => p.includes('.' + section.code + '.'));
+      if (viewPerms.length > 0) errors.push(mod.code + ": view section '" + section.code + "' has " + viewPerms.length + " permissions (should inherit)");
+    }
+  }
+
+  // Quality gate: UC count (C6 — BLOCKING if < 4, WARNING if < 6)
+  if (ucs.length > 0 && ucs.length < 4) {
+    errors.push(mod.code + ": only " + ucs.length + " use cases (minimum: 4)");
+  } else if (ucs.length > 0 && ucs.length < 6) {
+    warnings.push(mod.code + ": only " + ucs.length + " use cases (recommended: >= 6)");
+  }
+
+  // Quality gate: Permission path count (C7 — WARNING if < 5)
+  const permPaths = perms?.permissionPaths || [];
+  if (permPaths.length > 0 && permPaths.length < 5) {
+    warnings.push(mod.code + ": only " + permPaths.length + " permission paths (recommended: >= 5 — check for missing Export/Import)");
+  }
+
+  // Quality gate: Entity count (C9 — WARNING if single entity)
+  if (ent.length === 1) {
+    warnings.push(mod.code + ": single entity module — verify this is intentional (config/lookup OK)");
+  }
+
+  // Quality gate: BR-CALC must have formula (C13 — BLOCKING)
+  for (const br of brs) {
+    if ((br.category === 'calculation' || (br.id && br.id.includes('CALC'))) && !br.formula) {
+      errors.push(mod.code + ": BR '" + br.id + "' is a calculation rule but missing 'formula' field");
+    }
+  }
+
+  // Quality gate: Computed attributes must have BR-CALC (C11 — BLOCKING)
+  for (const e of ent) {
+    for (const a of (e.attributes || [])) {
+      if (a.computed === true) {
+        const hasBRCalc = brs.some(br =>
+          (br.category === 'calculation' || (br.id && br.id.includes('CALC'))) &&
+          (br.entities || []).includes(e.name)
+        );
+        if (!hasBRCalc) errors.push(mod.code + ": " + e.name + ".'" + a.name + "' is computed:true but no BR-CALC references " + e.name);
+      }
+    }
+  }
+
+  // Quality gate: Versioned attributes detection (C15 — WARNING)
+  for (const e of ent) {
+    for (const a of (e.attributes || [])) {
+      if (['salary', 'rate', 'grade', 'price', 'tarif'].some(k => a.name.toLowerCase().includes(k))) {
+        if (!e.versionedAttributes?.length)
+          warnings.push(mod.code + ": " + e.name + ".'" + a.name + "' may need versioning but no versionedAttributes defined");
+      }
+    }
+  }
+}
+
+if (errors.length > 0) {
+  Display("POST-CHECK FAILED (" + errors.length + " errors):");
+  errors.forEach(e => Display("  ✗ " + e));
+  BLOCKING_ERROR("Fix all errors before advancing to step 04");
+}
+if (warnings.length > 0) {
+  Display("POST-CHECK warnings (" + warnings.length + "):");
+  warnings.forEach(w => Display("  ⚠ " + w));
+}
+Display("POST-CHECK PASS: " + modules.length + " modules validated");
+```

package/templates/skills/business-analyse/references/03-smartstack-entity-guards.md

@@ -0,0 +1,32 @@
+# SmartStack Entity Convention Guards (step-03-specify)
+
+Before finalizing each entity, apply these rules:
+
+## B-bis-1. Person Extension Pattern
+
+(ref: `entity-architecture-decision.md` section 0)
+
+IF the entity matches a person role (Employee, Customer, Manager, Consultant, etc.):
+- **DO NOT** add firstName, lastName, email, phoneNumber as direct attributes
+- **DO** add `userId` (type: `string`, FK to auth_Users — ASP.NET Identity uses string IDs)
+- **DO** add `personRoleConfig` metadata with variant (mandatory/optional)
+- Personal fields come from User, not from the domain entity
+
+## B-bis-2. Versioned Sensitive Data
+
+IF the entity has attributes that change over time with audit requirements (salary, rate, grade):
+- **DO NOT** put them directly on the entity as single fields
+- **DO** extract into a versioned satellite table (e.g., Employee → Salary with effectiveDate)
+- Mark with `"versionedAttributes"` in entity spec
+
+## B-bis-3. SmartStack Socle Entities (NEVER redefine)
+
+- Users/Identity → `auth_Users` (managed by SmartStack Identity)
+- Tenants → `tenant_Tenants` (managed by SmartStack Core)
+- Departments → `ref_Departments` or `rh_Departments` (check if exists in target DB)
+
+## B-bis-4. Foreign Key Conventions
+
+- All FK attributes MUST end with `Id` suffix (e.g., `departmentId`, `userId`)
+- FK to Identity users MUST use type `string` (ASP.NET Identity convention, NOT guid)
+- FK to domain entities MUST use type `guid`

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.