@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -0,0 +1,281 @@
+# Module Specification Checklist
+
+> **CRITICAL:** This checklist MUST be FULLY COMPLETED before marking module status = "specified".
+> **Rationale:** Prevents incomplete modules from reaching handoff, reduces ralph-loop failures.
+
+## Checklist Structure
+
+**Execute BEFORE updating module status to "specified":**
+
+```javascript
+const checklist = {
+  // SECTION 1: DATA MODEL (BLOCKING)
+  entities: {
+    minimum: 2,
+    actual: specification.entities.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "At least 2 entities required for a meaningful module"
+  },
+
+  entityAttributes: {
+    check: "All entities have ≥3 attributes",
+    status: validateAllEntities(e => e.attributes.length >= 3) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Entities with <3 attributes are likely incomplete"
+  },
+
+  entityRelationships: {
+    check: "All entities have relationships defined (or explicitly marked as standalone)",
+    status: validateEntityRelationships() ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "Standalone entities should be rare in business modules"
+  },
+
+  // SECTION 2: BUSINESS RULES (BLOCKING)
+  businessRules: {
+    minimum: 4,
+    actual: analysis.businessRules.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 4 BRs (mix of VAL/CALC/WF/SEC/DATA)"
+  },
+
+  businessRuleCategories: {
+    check: "BRs cover ≥2 categories (VAL, CALC, WF, SEC, DATA)",
+    status: countUniqueCategories(analysis.businessRules) >= 2 ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Single-category modules are likely incomplete"
+  },
+
+  businessRulePrefixes: {
+    check: "All BR IDs use module prefix (e.g., BR-VAL-{PREFIX}-NNN)",
+    status: validateBRPrefixes() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing prefixes cause ID collisions in multi-module apps"
+  },
+
+  // SECTION 3: USE CASES & REQUIREMENTS (BLOCKING)
+  useCases: {
+    minimum: 6,
+    actual: specification.useCases.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 6 UCs (CRUD + 2 business-specific)"
+  },
+
+  useCasePrefixes: {
+    check: "All UC IDs use module prefix (UC-{PREFIX}-NNN)",
+    status: validateUCPrefixes() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing prefixes cause ID collisions"
+  },
+
+  functionalRequirements: {
+    minimum: 4,
+    actual: specification.functionalRequirements.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "FRs must cover key functionality"
+  },
+
+  ucFrLinkage: {
+    check: "Every UC has ≥1 linked FR",
+    status: validateUCtoFRLinkage() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Orphan UCs indicate incomplete requirements"
+  },
+
+  frBrLinkage: {
+    check: "Every FR has ≥1 linked BR",
+    status: validateFRtoBRLinkage() ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "FRs without BRs may lack validation/calculation logic"
+  },
+
+  // SECTION 4: PERMISSIONS (BLOCKING)
+  permissions: {
+    minimum: 5,
+    actual: specification.permissionMatrix.permissions.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 5 permissions (CRUD + 1 business action)"
+  },
+
+  permissionFormat: {
+    check: "All permissions use full format: business.{app}.{module}.{resource}.{action}",
+    status: validatePermissionFormat() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Wrong format breaks RBAC system"
+  },
+
+  rolePermissions: {
+    check: "All application roles have ≥1 permission assigned",
+    status: validateRoleAssignments() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Roles without permissions are useless"
+  },
+
+  // SECTION 5: UI & NAVIGATION (BLOCKING)
+  sections: {
+    minimum: 2,
+    actual: specification.sections.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Modules need ≥2 sections (list + form minimum)"
+  },
+
+  wireframes: {
+    minimum: specification.sections.length,  // 1 wireframe PER section
+    actual: specification.uiWireframes.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "EVERY section MUST have a wireframe (ASCII/SVG)"
+  },
+
+  navigation: {
+    check: "Module has ≥1 navigation entry",
+    status: specification.navigation.entries.length >= 1 ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Module must be accessible in menu"
+  },
+
+  // SECTION 6: I18N & MESSAGES (BLOCKING)
+  i18nKeys: {
+    minimum: 42,  // Realistic minimum for a module
+    actual: specification.i18nKeys.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Keys needed: entities (×2), fields, messages, validation, navigation"
+  },
+
+  i18nLanguages: {
+    check: "All i18n keys have 4 languages (fr, en, nl, de)",
+    status: validateI18nCompleteness() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing translations break multi-language support"
+  },
+
+  messages: {
+    minimum: 4,
+    actual: specification.messages.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum: 1 success, 1 error, 1 warning, 1 info"
+  },
+
+  // SECTION 7: SEED DATA (BLOCKING)
+  seedDataCore: {
+    check: "All 7 CORE seed data sections present",
+    requiredSections: [
+      "navigationModules",
+      "navigationSections",
+      "navigationResources",
+      "navigationTranslations",
+      "permissions",
+      "rolePermissions",
+      "permissionConstants"
+    ],
+    status: validateSeedDataCore() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing CORE seed data breaks module deployment"
+  },
+
+  seedDataBusiness: {
+    check: "Business seed data template defined for modules with reference/lookup entities",
+    status: specification.seedDataBusiness !== undefined ? "PASS" : "FAIL",
+    blocking: true,  // BLOCKING — missing seed data causes empty dropdowns and test failures
+    details: "Business seed data (reference types, categories, statuses) is required for testing and dev environment"
+  },
+
+  // SECTION 8: API ENDPOINTS (BLOCKING)
+  apiEndpoints: {
+    minimum: 5,
+    actual: specification.apiEndpoints.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 5 endpoints (CRUD + 1 business action)"
+  },
+
+  apiPermissions: {
+    check: "Every API endpoint has permission defined",
+    status: validateAPIPermissions() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Endpoints without permissions are security holes"
+  },
+
+  // SECTION 9: VALIDATIONS (BLOCKING)
+  validations: {
+    minimum: 1,
+    actual: specification.validations.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Modules need field validation rules"
+  },
+
+  // SECTION 10: GHERKIN SCENARIOS (WARNING)
+  gherkinScenarios: {
+    minimum: 2,
+    actual: specification.gherkinScenarios.scenarios.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "Gherkin scenarios enable automated testing"
+  }
+};
+```
+
+## Blocking Check Logic
+
+```javascript
+// BLOCKING CHECK: Count failures in BLOCKING items
+const blockingFailures = Object.entries(checklist)
+  .filter(([key, check]) => check.blocking === true && check.status === "FAIL")
+  .map(([key, check]) => ({ section: key, ...check }));
+
+IF blockingFailures.length > 0:
+  **BLOCKING ERROR:** Module specification incomplete
+
+  Display table:
+  | Section | Required | Actual | Status | Details |
+  |---------|----------|--------|--------|---------|
+  {for each blocking failure}
+
+  ACTIONS REQUIRED:
+  1. Fix ALL blocking failures listed above
+  2. Re-run step-03d validation
+  3. DO NOT mark module as "specified" until ALL blocking checks pass
+
+  STOP - DO NOT PROCEED TO UPDATE STATUS
+ELSE:
+  All blocking checks passed ✓
+  {count} warnings (non-blocking)
+  Proceed to mark module as "specified"
+```
+
+## Display Format
+
+```
+═══════════════════════════════════════════════════════════════
+  MODULE SPECIFICATION CHECKLIST - {currentModule}
+═══════════════════════════════════════════════════════════════
+
+| Category | Checks | Passed | Failed | Warnings |
+|----------|--------|--------|--------|----------|
+| Data Model | 3 | {n} | {n} | {n} |
+| Business Rules | 3 | {n} | {n} | {n} |
+| Use Cases & FRs | 4 | {n} | {n} | {n} |
+| Permissions | 3 | {n} | {n} | {n} |
+| UI & Navigation | 3 | {n} | {n} | {n} |
+| I18N & Messages | 3 | {n} | {n} | {n} |
+| Seed Data | 2 | {n} | {n} | {n} |
+| API Endpoints | 2 | {n} | {n} | {n} |
+| Validations | 1 | {n} | {n} | {n} |
+| Gherkin | 1 | {n} | {n} | {n} |
+
+TOTAL: {total_checks} checks | {passed} ✓ | {failed} ✗ | {warnings} ⚠
+
+STATUS: {failed === 0 ? "READY FOR SPECIFIED" : "INCOMPLETE - FIX REQUIRED"}
+═══════════════════════════════════════════════════════════════
+```
+
+**IF ALL BLOCKING CHECKS PASS → Proceed to update module status to "specified"**

package/templates/skills/business-analyse/schemas/sections/specification-schema.json

@@ -382,7 +382,7 @@
     },
     "seedDataCore": {
       "type": "object",
-      "description": "5 mandatory SmartStack core SeedData definitions",
+      "description": "7 mandatory SmartStack core SeedData definitions (modules, sections, resources, translations, permissions, rolePermissions, permissionConstants)",
       "properties": {
         "navigationModules": {
           "type": "array",
@@ -399,6 +399,38 @@
             }
           }
         },
+        "navigationSections": {
+          "type": "array",
+          "description": "Level 4 (Section) navigation entries for core.nav_Sections table. Derived from specification.sections[].",
+          "items": {
+            "type": "object",
+            "required": ["code", "label", "icon", "route", "parentCode", "permission"],
+            "properties": {
+              "code": { "type": "string", "description": "Section code (list, detail, create, dashboard)" },
+              "label": { "type": "string", "description": "Section label in default language (fr)" },
+              "icon": { "type": "string", "description": "Lucide icon name" },
+              "route": { "type": "string", "description": "Full route path" },
+              "parentCode": { "type": "string", "description": "Parent module code" },
+              "permission": { "type": "string", "description": "Required permission path" },
+              "sort": { "type": "integer", "description": "Display order within module" }
+            }
+          }
+        },
+        "navigationResources": {
+          "type": "array",
+          "description": "Level 5 (Resource) navigation entries for core.nav_Resources table. Derived from specification.sections[].resources[].",
+          "items": {
+            "type": "object",
+            "required": ["code", "type", "parentCode"],
+            "properties": {
+              "code": { "type": "string", "description": "Resource code (kebab-case)" },
+              "type": { "type": "string", "description": "SmartStack component type (SmartTable, SmartForm, DetailCard, KpiCard, Chart, etc.)" },
+              "entity": { "type": "string", "description": "Primary entity this resource operates on" },
+              "parentCode": { "type": "string", "description": "Parent section code" },
+              "permission": { "type": "string", "description": "Required permission path (optional if inherited from section)" }
+            }
+          }
+        },
         "navigationTranslations": {
           "type": "array",
           "items": {

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -69,94 +69,51 @@ mcp__smartstack__validate_conventions({ checks: ["tables"] })
 **DO NOT** continue to any subsequent step.
 **STOP the skill immediately.**
 
-## Step 2a: Check for Review Mode
-
-If `{feature_description}` starts with `-review` (with or without extra text):
-
-1. Set `workflow_type = "review"`
-2. Scan `docs/business/` for the most recent application (by updatedAt)
-3. For the latest application version folder, look for `ba-review.json`
-4. If found:
-   - Store `review_json_path` = path to `ba-review.json`
-   - Store `application_name` from the master feature.json metadata
-   - Store `docs_dir` = directory containing `ba-review.json`
-   - Display:
-     ```
-     Review mode: found ba-review.json at {review_json_path}
-     Application: {application_name}
-     ```
-   - **SKIP all remaining steps** → Load `./step-06-review.md` directly
-5. If NOT found:
-   - Display error:
-     ```
-     ERROR: No ba-review.json found in docs/business/
-
-     To create one:
-     1. Open the ba-interactive.html in your browser
-     2. Make your corrections
-     3. Click "Sauvegarder corrections" button
-     4. Save the downloaded ba-review.json in the version folder
-        (e.g., docs/business/{app}/business-analyse/v1.0/ba-review.json)
-     5. Run /business-analyse -review again
-     ```
-   - **STOP EXECUTION**
-
-## Step 2b: Scan Existing Applications
-
-Scan `docs/business/` for existing business analysis features.
+## Step 2-3: Workflow Detection (Review / New / Update)
 
-```
-1. Glob: docs/business/*/business-analyse/*/feature.json
-2. For each feature.json found:
-   - Read metadata.application, metadata.featureDescription
-   - Store: { app: string, featureId: string, description: string, version: string }
-3. Build list of existing applications
-```
+**Objective:** Detect workflow type and match against existing applications.
 
-**Store:**
-```yaml
-existing_apps: array of { app, featureId, description, version }
-```
+**Process:**
 
-## Step 3: Auto-Detect New vs Update (skipped in review mode)
+Execute workflow detection algorithm:
+1. **Review Mode Detection:** Check if `{feature_description}` starts with `-review`
+2. **Existing Applications Scanner:** Glob `docs/business/*/business-analyse/*/feature.json`
+3. **Similarity Analysis:** Score user intent against existing apps (>= 80 = strong match)
+4. **Decision Tree:** Prompt user with relevant options
 
-Compare the user's `{feature_description}` with existing applications.
+```javascript
+const detectionResult = detectWorkflowType(feature_description, existingApps);
 
-```
-IF existing_apps is empty:
-  workflow_type = "new"
-  → Go to Step 4
+IF detectionResult.error OR detectionResult.ambiguous:
+  // CONDITIONAL LOAD: Only load detection strategies on error or ambiguity
+  Read references/detection-strategies.md
+  Display:
+    - Detailed similarity scoring algorithm
+    - Decision tree with thresholds
+    - Error handling procedures
+    - Review mode troubleshooting (if review mode failed)
 
-IF existing_apps has entries:
-  Analyze {feature_description} for similarity with existing apps:
-    - Same application domain?
-    - References an existing module name?
-    - Mentions adding/changing/modifying something existing?
+  → Resolve ambiguity with user clarification
 
-  Ask via AskUserQuestion:
-    question: "J'ai trouvé des analyses existantes. Que souhaitez-vous faire ?"
-    header: "Mode"
-    options:
-      - label: "Nouvelle application"
-        description: "Créer une nouvelle analyse complète"
-      - label: "Mise à jour de {appName} (FEAT-NNN)"
-        description: "Enrichir ou modifier l'application existante (crée v{next})"
-    (repeat for each existing app, max 3 options + "Nouvelle application")
-
-  IF user selects "Nouvelle application":
-    workflow_type = "new"
-  ELSE:
-    workflow_type = "update"
-    existing_feature_id = selected app's featureId
-    Call ba-writer.createVersion(existing_feature_id, {feature_description})
-    version = new version number
+ELSE:
+  Workflow detected: {detectionResult.workflow_type} ✓
+  → Continue to application name determination
 ```
 
+**Key decision points:**
+1. IF review mode → load ba-review.json, skip to step-06-review.md
+2. IF no existing apps → workflow_type = "new"
+3. IF existing apps → analyze similarity → prompt user
+
+**Optimization:** The detailed 400-line detection-strategies.md is loaded **only when detection fails or is ambiguous** (saves ~15,000 tokens on clear detection path).
+
 **Store:**
 ```yaml
-workflow_type: "new" | "update"
+workflow_type: "new" | "update" | "review"
 existing_feature_id: string | null
 version: "1.0" (new) | "1.1"+ (update)
+review_json_path: string | null (review only)
+existing_apps: array of { app, featureId, description, version }
 ```
 
 ## Step 4: Determine Application Name
@@ -277,6 +234,44 @@ docs_dir: "docs/business/{app}/business-analyse/v{version}"
 
 See [references/init-schema-deployment.md](../references/init-schema-deployment.md) for cache-based deployment logic (9 schema files, version-checked via `.schema-cache.json`).
 
+## Step 8b: Cache Warming (PERFORMANCE OPTIMIZATION)
+
+> **Objective:** Pre-load frequently-used templates and context files to reduce redundant reads.
+> **Expected token savings:** 15-20% across entire BA session
+
+**Implementation:**
+
+```javascript
+// Pre-load CRITICAL (schemas) and HIGH (questionnaires) priority buckets
+const schemaFiles = glob("docs/business/{app}/business-analyse/schemas/**/*.json");
+for (const file of schemaFiles) {
+  read(file);  // Triggers cache
+}
+
+const questionnaireFiles = glob("~/.claude/skills/business-analyse/questionnaire/*.md");
+for (const file of questionnaireFiles) {
+  read(file);  // Triggers cache
+}
+
+read("~/.claude/skills/business-analyse/patterns/suggestion-catalog.md");
+
+// Display status
+console.log(`
+✓ Cache warmed: 9 schemas + 16 questionnaires + 1 catalog
+  Expected savings: 15-20% session tokens
+  Retention: schemas (session-wide), questionnaires (until step-02)
+`);
+```
+
+**Bucket Strategy:**
+
+See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) for complete documentation on:
+- 5 cache buckets (schemas, questionnaires, moduleSpec, handoff, etc.)
+- Retention policies and clearing rules
+- Token savings calculations (baseline vs optimized)
+- Monitoring cache efficiency
+- When to pre-load vs lazy-load
+
 ## Step 9: Create Master feature.json
 
 Create the master feature document using ba-writer agent.

package/templates/skills/business-analyse/steps/step-01-cadrage.md

@@ -70,34 +70,20 @@ Launch 3 agents in parallel:
 Merge findings into {codebase_context}
 ```
 
-### 3. MODE ROUTING
+### 3. VIBE CODING FLOW (always — 2 lots)
 
-```
-Read metadata.vibeCoding from feature.json
-
-IF metadata.vibeCoding == true:
-  → Execute VIBE CODING FLOW (section 3v below)
-  → SKIP sections 3s through 8s (standard flow)
-  → Go directly to section 9 (Coverage Matrix)
-
-ELSE:
-  → Execute STANDARD FLOW (sections 3s through 8s below)
-```
-
----
-
-## VIBE CODING FLOW (accelerated — 3 lots max)
-
-> **In vibe coding mode, the developer IS the product owner, the user, and the builder.**
+> **The developer IS the product owner, the user, and the builder.**
 > Skip organizational questions (adoption, change management, governance, KPIs).
 > Focus on functional decisions and technical challenges.
+> **Always optimize for high traffic and production-grade performance.**
 
-See [references/cadrage-vibe-coding.md](../references/cadrage-vibe-coding.md) for the complete 3-lot questionnaire:
+See [references/cadrage-vibe-coding.md](../references/cadrage-vibe-coding.md) for the 2-lot questionnaire:
 - **Lot 1 (3v):** Problem & Scope — capture core need + must-have features
-- **Lot 2 (4v):** Users & Permissions — access model (solo/team/org) + roles
-- **Lot 3 (5v):** Technical Challenges — risks specific to AI-assisted dev + auto-inferred cadrage data
+- **Lot 2 (4v):** Technical Challenges — risks specific to AI-assisted dev + auto-inferred cadrage data
+
+**Users & Permissions:** Always auto-set to Organisation (500+ users) with standard 4-tier roles (Admin, Manager, Contributor, Viewer) and 3 stakeholders. No question needed. Pagination, caching, indexed queries, and async operations are mandatory defaults — not optimizations to discuss.
 
-**After Lot 3:** Go directly to **section 9 (Coverage Matrix)**.
+**After Lot 2:** Go directly to **section 9 (Coverage Matrix)**.
 
 ---