@atlashub/smartstack-cli 3.1.0 → 3.2.0

package/.documentation/testing-ba-e2e.md

@@ -0,0 +1,462 @@
+# Business Analyse E2E Testing Infrastructure
+
+## Vue d'ensemble
+
+Infrastructure de tests E2E pour valider le pipeline complet **Business Analyse → Handoff → PRD extraction → Ralph Loop**.
+
+**Garanties :**
+- ✅ Validation déterministe du handoff
+- ✅ Extraction programmatique prd.json (zéro hallucination)
+- ✅ Reproductibilité parfaite
+- ✅ Couverture complète des cas d'usage
+
+---
+
+## Architecture
+
+```
+tests/ba/
+├── fixtures/                     # Test data (feature.json examples)
+│   ├── simple-feature.json       # Module simple (Orders, 1 entity, 2 UCs, 3 BRs)
+│   ├── medium-feature.json       # Module medium (Invoices, lifecycle, 4 entities, 6 UCs)
+│   ├── complex-application.json  # Application multi-modules (3 modules, dépendances)
+│   └── complex-app/              # Modules référencés par complex-application.json
+│       ├── Customers/
+│       ├── Products/
+│       └── Orders/
+│
+└── e2e/                          # Test suites E2E
+    ├── handoff-validation.test.ts       # Validation handoff section
+    ├── prd-extraction-simple.test.ts    # Extraction module simple
+    ├── prd-extraction-medium.test.ts    # Extraction module lifecycle
+    └── full-pipeline.test.ts            # Pipeline complet BA → Ralph Loop
+```
+
+---
+
+## Fixtures
+
+### simple-feature.json
+
+**Module:** Orders
+**Complexité:** Basique CRUD
+**Contenu:**
+- 1 entity (Order)
+- 2 use cases (Create, List)
+- 3 business rules (2 validation, 1 calculation)
+- 2 API endpoints
+- 4 permissions
+- 7 file categories
+
+**Use case:** Tester extraction basique sans lifecycle.
+
+### medium-feature.json
+
+**Module:** Invoices
+**Complexité:** Workflow avec lifecycle
+**Contenu:**
+- 4 entities (Invoice, InvoiceLine, Customer, Payment)
+- 6 use cases (Create, Issue, Pay, List, View, Cancel)
+- 6 business rules (2 validation, 2 workflow, 2 calculation)
+- 3 API endpoints (dont 2 transitions)
+- 1 lifecycle (4 états: draft → issued → paid, cancelled)
+- 2 seedData business (InvoiceStatus, PaymentMethod)
+
+**Use case:** Tester extraction avec lifecycle states et transitions.
+
+### complex-application.json + modules
+
+**Application:** SalesManagement
+**Complexité:** Multi-modules avec dépendances
+**Contenu:**
+- 3 modules: Customers, Products, Orders
+- Dependency graph: Orders → Customers + Products
+- 4 application roles (admin, manager, salesperson, viewer)
+
+**Use case:** Tester mode `--application` et génération multi-prd.json.
+
+---
+
+## Tests E2E
+
+### 1. handoff-validation.test.ts
+
+**Objectif:** Valider la fonction `validateForPrdExtraction()`.
+
+**Scénarios:**
+- ✅ Feature complet simple passe validation
+- ✅ Feature complet medium passe validation
+- ❌ Feature sans `metadata.application` échoue
+- ❌ Feature sans `metadata.module` échoue
+- ❌ Feature avec `status !== "handed-off|approved|consolidated"` échoue
+- ❌ Feature sans use cases échoue
+- ❌ Feature sans business rules échoue
+- ❌ Feature sans `filesToCreate` échoue
+- ✅ Feature avec status "approved" passe
+- ✅ Feature avec status "consolidated" passe
+- ✅ Medium feature a lifecycle défini (4 états)
+- ✅ Medium feature a 7 catégories de fichiers
+- ✅ BR to code mappings complets
+- ✅ CORE seedData obligatoire (NavigationModule, Permission)
+
+### 2. prd-extraction-simple.test.ts
+
+**Objectif:** Tester extraction prd.json pour module simple.
+
+**Scénarios:**
+- Extraction complète sans erreur
+- Metadata projet (application, module, namespace)
+- Use cases (2) avec actor, permission, steps, linkedRules
+- Functional requirements (3) avec priority, linkedUCs
+- Business rules (3) avec category, statement, priority
+- Entities (1) avec attributes, type
+- API endpoints (2) avec method, route, permission, linkedUC
+- Permission matrix (4 permissions) avec scope
+- Sections (1) avec resources
+- FilesToCreate (7 catégories)
+- BrToCodeMapping (2 mappings) avec targetFile, targetMethod, implementationType
+- SeedData (core + business)
+- Implementation strategy ("module-by-module")
+- Source traceability (extractedAt, featureJsonPath)
+
+### 3. prd-extraction-medium.test.ts
+
+**Objectif:** Tester extraction prd.json avec lifecycle.
+
+**Scénarios:**
+- Extraction complète avec lifecycle
+- Multiple entities (4) avec relationships
+- Lifecycle states (4) avec allowedTransitions
+- Lifecycle transitions (2) avec action, permission, guards
+- Terminal states (2: paid, cancelled)
+- Workflow business rules (2) mappés au code
+- Calculation business rules (2) avec formulas
+- Multiple use cases (6) incluant transitions
+- Transition API endpoints (2: /issue, /pay)
+- Multiple seedData business entities (2)
+- Multiple domain files (4 entities)
+- Integration tests en plus des unit tests
+- BR mappings complets pour critical rules
+
+### 4. full-pipeline.test.ts
+
+**Objectif:** Tester pipeline complet BA → Ralph Loop.
+
+**Scénarios:**
+
+**Simple Module Pipeline:**
+1. Load feature.json (status = "handed-off")
+2. Validate handoff section complet
+3. Extract prd.json déterministe
+4. Write prd.json to .ralph/
+5. Read back prd.json (verify integrity)
+6. Verify all required sections for Ralph Loop
+7. Verify prd.json meets Ralph Loop requirements (7 categories, BR mappings, CORE seedData)
+
+**Medium Module Pipeline with Lifecycle:**
+1. Load medium feature with lifecycle
+2. Validate handoff including lifecycle
+3. Extract prd.json with lifecycle preserved
+4. Verify lifecycle transitions mapped to BR
+5. Verify lifecycle states match seedData
+6. Write prd.json to .ralph/
+
+**Reproducibility Test:**
+- Multiple extractions = identical prd.json (sans timestamp)
+
+**Error Handling:**
+- Missing optional namespace handled gracefully
+- Empty arrays handled gracefully
+
+**Integration with Ralph Loop:**
+- All required information present (entities, UCs, BRs, endpoints, permissions, filesToCreate, BR mappings, CORE seedData)
+- Use cases linked to API endpoints
+- Business rules linked to use cases
+
+---
+
+## Exécution des Tests
+
+### Installation
+
+```bash
+# Les dépendances de test sont déjà installées (vitest, @vitest/coverage-v8)
+npm install
+```
+
+### Commandes
+
+```bash
+# Exécuter tous les tests BA E2E
+npm run test:ba
+
+# Exécuter tests BA E2E en mode watch (développement)
+npm run test:ba:watch
+
+# Exécuter tests BA E2E avec couverture
+npm run test:ba:coverage
+
+# Exécuter TOUS les tests (MCP + BA)
+npm run test:all
+```
+
+### Filtrage des Tests
+
+```bash
+# Exécuter un seul fichier de test
+npx vitest run tests/ba/e2e/handoff-validation.test.ts
+
+# Exécuter tests contenant "lifecycle" dans le nom
+npx vitest run --grep lifecycle
+
+# Exécuter tests en mode watch avec filtrage
+npx vitest --grep extraction
+```
+
+### Couverture de Code
+
+```bash
+npm run test:ba:coverage
+
+# Rapport généré dans: coverage/
+# Ouvrir: coverage/index.html
+```
+
+---
+
+## Ajouter de Nouveaux Tests
+
+### 1. Créer une Nouvelle Fixture
+
+Créer `tests/ba/fixtures/my-feature.json` :
+
+```json
+{
+  "id": "FEAT-TEST-XXX",
+  "version": "5.0.0",
+  "status": "handed-off",
+  "metadata": {
+    "application": "MyApp",
+    "module": "MyModule",
+    "context": "business"
+  },
+  "discovery": { ... },
+  "analysis": {
+    "businessRules": [...],
+    "entities": [...]
+  },
+  "specification": {
+    "useCases": [...],
+    "functionalRequirements": [...],
+    "apiEndpoints": [...],
+    "permissionMatrix": { ... },
+    "sections": [...],
+    "seedDataCore": [...]
+  },
+  "handoff": {
+    "implementationStrategy": "module-by-module",
+    "filesToCreate": {
+      "domain": [...],
+      "application": [...],
+      "infrastructure": [...],
+      "api": [...],
+      "frontend": [...],
+      "seedData": [...],
+      "tests": [...]
+    },
+    "brToCodeMapping": [...]
+  }
+}
+```
+
+**Checklist fixture valide:**
+- ✅ `status` = "handed-off" | "approved" | "consolidated"
+- ✅ `metadata.application` et `metadata.module` présents
+- ✅ `specification.useCases[]` non vide
+- ✅ `analysis.businessRules[]` non vide
+- ✅ `handoff.filesToCreate` avec 7 catégories
+- ✅ `specification.seedDataCore` avec NavigationModule + Permission
+
+### 2. Créer un Nouveau Test
+
+Créer `tests/ba/e2e/my-test.test.ts` :
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { extractPrd, validateForPrdExtraction } from '../../../src/utils/prd-extractor.js';
+import type { ModuleFeatureJson } from '../../../src/types/feature-json.js';
+import fs from 'fs-extra';
+import { join } from 'path';
+
+describe('My Test Suite', () => {
+  const fixturesDir = join(__dirname, '../fixtures');
+
+  it('should validate my scenario', async () => {
+    const feature = await fs.readJson(join(fixturesDir, 'my-feature.json')) as ModuleFeatureJson;
+    const errors = validateForPrdExtraction(feature);
+
+    expect(errors).toEqual([]);
+  });
+
+  it('should extract prd.json correctly', () => {
+    const feature = await fs.readJson(join(fixturesDir, 'my-feature.json')) as ModuleFeatureJson;
+    const prd = extractPrd(feature, 'my-feature.json', 'MyCompany.MyApp');
+
+    expect(prd.version).toBe('2.0.0');
+    expect(prd.project.module).toBe('MyModule');
+    // ... more assertions
+  });
+});
+```
+
+### 3. Exécuter le Nouveau Test
+
+```bash
+npx vitest run tests/ba/e2e/my-test.test.ts
+```
+
+---
+
+## Intégration CI/CD
+
+### Azure Pipelines
+
+Ajouter dans `azure-pipelines.yml` :
+
+```yaml
+- stage: Test
+  jobs:
+    - job: UnitTests
+      steps:
+        - task: Npm@1
+          inputs:
+            command: 'custom'
+            customCommand: 'run test:ba'
+          displayName: 'Run BA E2E Tests'
+
+        - task: PublishTestResults@2
+          inputs:
+            testResultsFormat: 'JUnit'
+            testResultsFiles: '**/test-results.xml'
+          displayName: 'Publish Test Results'
+
+        - task: PublishCodeCoverageResults@1
+          inputs:
+            codeCoverageTool: 'Cobertura'
+            summaryFileLocation: '**/coverage/cobertura-coverage.xml'
+          displayName: 'Publish Code Coverage'
+```
+
+### GitHub Actions
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install
+      - run: npm run test:ba
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/coverage-final.json
+```
+
+---
+
+## Métriques de Qualité
+
+### Objectifs de Couverture
+
+| Fichier | Couverture Cible |
+|---------|-----------------|
+| `src/utils/prd-extractor.ts` | 100% |
+| `src/commands/derive-prd.ts` | 90% |
+| `templates/skills/business-analyse/**/*.md` | N/A (documentation) |
+
+### KPIs Tests
+
+- **Total tests:** ~60 scénarios
+- **Temps d'exécution:** < 10s
+- **Fixtures:** 3 (simple/medium/complex)
+- **Couverture code:** > 95% sur extraction pipeline
+
+---
+
+## Dépannage
+
+### Erreur: "Cannot find module '...'"
+
+**Cause:** Imports relatifs incorrects ou TypeScript non compilé.
+
+**Solution:**
+```bash
+npm run build
+npm run test:ba
+```
+
+### Erreur: "Feature status is X"
+
+**Cause:** Fixture a `status !== "handed-off"`.
+
+**Solution:** Mettre `status: "handed-off"` dans la fixture.
+
+### Erreur: "No use cases found"
+
+**Cause:** `specification.useCases[]` est vide dans la fixture.
+
+**Solution:** Ajouter au moins 1 use case dans la fixture.
+
+### Tests timeouts
+
+**Cause:** Tests E2E dépassent 30s.
+
+**Solution:** Augmenter `testTimeout` dans `vitest.ba.config.ts` :
+
+```typescript
+export default defineConfig({
+  test: {
+    testTimeout: 60000, // 60s
+  },
+});
+```
+
+---
+
+## Roadmap
+
+### Phase 1 ✅ (Implémenté)
+- Infrastructure Vitest
+- 3 fixtures (simple/medium/complex)
+- 4 test suites (handoff-validation, prd-extraction x2, full-pipeline)
+- Scripts npm
+- Documentation
+
+### Phase 2 (Futur)
+- Tests pour mode `--application` (extraction multi-modules)
+- Tests pour mode `--strict`
+- Tests pour cross-module dependencies
+- Performance benchmarks (extraction < 100ms)
+- Tests pour ba-interactive.html extraction
+
+### Phase 3 (Futur)
+- Tests E2E Ralph Loop integration (mock Ralph Loop server)
+- Tests pour step-05-handoff.md (génération handoff)
+- Tests pour derive-prd CLI (end-to-end avec fs.existsSync)
+- Tests pour validation schema (feature-schema.json)
+
+---
+
+## Voir aussi
+
+- [prd-json v2.0.0 Reference](./prd-json-v2.0.0.md)
+- [Feature JSON Schema](../templates/skills/business-analyse/schemas/feature-schema.json)
+- [Business Analyse Skill](../templates/skills/business-analyse/SKILL.md)
+- [Ralph Loop Documentation](../templates/skills/ralph-loop/SKILL.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
@@ -72,7 +72,11 @@
     "health": "node dist/index.js doctor --json",
     "test:mcp": "vitest run --config vitest.mcp.config.ts",
     "test:mcp:watch": "vitest --config vitest.mcp.config.ts",
-    "test:mcp:coverage": "vitest run --config vitest.mcp.config.ts --coverage"
+    "test:mcp:coverage": "vitest run --config vitest.mcp.config.ts --coverage",
+    "test:ba": "vitest run --config vitest.ba.config.ts",
+    "test:ba:watch": "vitest --config vitest.ba.config.ts",
+    "test:ba:coverage": "vitest run --config vitest.ba.config.ts --coverage",
+    "test:all": "npm run test:mcp && npm run test:ba"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/templates/skills/business-analyse/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: business-analyse
-description: Business Analysis v5.0 - Iterative multi-module workflow with 5-level navigation hierarchy, client checkpoints, interactive HTML documentation, and extraction pipeline.
+description: Business Analysis v6.1 - Iterative multi-module workflow with optimized performance (schema caching), automatic skill launch transition, and streamlined execution.
 argument-hint: "[-a] [-e] [-q <FEAT-ID> \"question\"] [-r <FEAT-ID> \"change\"] [-m] [-x <json-path>] <feature description>"
 ---
 
 <objective>
 Execute VibeCoding-focused business analysis workflows. This skill produces a single feature.json progressively enriched at each step, published to docs/business/ for web app rendering. Supports 5 use cases: new feature analysis, questions about existing features, feature refactoring, one-shot micro-features, and extraction from interactive HTML documentation.
+
+**New in v6.1:**
+- ⚡ **Performance:** Schema deployment caching (~75% faster subsequent runs)
+- 🚀 **Seamless transition:** Automatic launch of chosen development approach (Ralph Loop / Feature Full)
+- 🎯 **Simplified:** Removed interactive mode (-i flag), streamlined execution
+- 📂 **Modern only:** Legacy `.business-analyse/` structure no longer supported
 </objective>
 
 <quick_start>
@@ -50,7 +56,6 @@ See `<parameters>` for complete flag list.
 | `-m` | `--micro` | Micro-feature mode: minimal questions, direct handoff |
 | `-x` | `--extract` | Extract mode: import from interactive HTML export JSON (requires json-path) |
 | `-app` | `--application` | Application mode: multi-module analysis with module decomposition |
-| `-i` | `--interactive` | Interactive mode: configure flags via AskUserQuestion |
 
 **Disable flags (turn OFF):**
 | Short | Long | Description |
@@ -178,6 +183,10 @@ When provided, step-00 will:
     - Per-module validation + client confirmation
 - **Step 04:** Cross-module consolidation (consolidated)
 - **Step 05:** Handoff with per-module prd.json (handed-off)
+  - **NEW v6.1:** User chooses development approach (AskUserQuestion)
+  - **If "Ralph Loop":** Automatic launch → `/ralph-loop` (seamless transition)
+  - **If "Feature Full":** Automatic launch → `/feature-full` (parallel generation)
+  - **If "Terminer":** BA ends, manual development
 
 **Single module workflow (same phases, simplified):**
 - **Step 00:** Parse flags, create master feature.json (draft)
@@ -186,10 +195,12 @@ When provided, step-00 will:
 - **Step 03:** Specification: single iteration (specified)
 - **Step 04:** Consolidation: auto-pass (consolidated)
 - **Step 05:** Handoff (handed-off)
+  - **NEW v6.1:** Automatic skill launch based on user choice
 
 **Micro workflow:**
 - **Step 00:** Create minimal feature.json
 - **Step 05:** Direct handoff (skip 01-04)
+  - **NEW v6.1:** Automatic skill launch
 
 **Extract workflow (from interactive HTML):**
 - **Step 00:** Parse `-x` flag, validate JSON file
@@ -244,21 +255,27 @@ Load ONLY relevant categories based on feature type:
 
 | Categorie | Fichier                               | Questions | Quand charger |
 | --------- | ------------------------------------- | --------- | ------------- |
-| 00        | `questionnaire/00-application.md`     | 8         | Si mode application |
-| 01        | `questionnaire/01-context.md`         | 12        | Toujours      |
-| 02        | `questionnaire/02-stakeholders.md`    | 14        | Toujours      |
-| 03        | `questionnaire/03-scope.md`           | 12        | Toujours      |
-| 04        | `questionnaire/04-data.md`            | 8         | Si module oriente donnees |
-| 05        | `questionnaire/05-integrations.md`    | 8         | Si integrations |
-| 06        | `questionnaire/06-security.md`        | 8         | Si securite mentionnee |
-| 07        | `questionnaire/07-ui.md`              | 12        | Si module oriente interface |
-| 08        | `questionnaire/08-performance.md`     | 4         | Si performance critique |
-| 09        | `questionnaire/09-constraints.md`     | 4         | Si contraintes |
-| 10        | `questionnaire/10-documentation.md`   | 4         | Si documentation requise |
-| 14        | `questionnaire/14-risk-assumptions.md`| 8         | Toujours      |
-| 15        | `questionnaire/15-success-metrics.md` | 8         | Toujours      |
-
-**Total noyau : ~86 questions (en profondeur, langage business)**
+| 00        | `questionnaire/00-application.md`     | 18        | Si mode application |
+| 01        | `questionnaire/01-context.md`         | 32        | Toujours      |
+| 02        | `questionnaire/02-stakeholders.md`    | 33        | Toujours      |
+| 03        | `questionnaire/03-scope.md`           | 32        | Toujours      |
+| 04        | `questionnaire/04-data.md`            | 15        | Si module oriente donnees |
+| 05        | `questionnaire/05-integrations.md`    | 14        | Si integrations |
+| 06        | `questionnaire/06-security.md`        | 13        | Si securite mentionnee |
+| 07        | `questionnaire/07-ui.md`              | 19        | Si module oriente interface |
+| 08        | `questionnaire/08-performance.md`     | 8         | Si performance critique |
+| 09        | `questionnaire/09-constraints.md`     | 6         | Si contraintes |
+| 10        | `questionnaire/10-documentation.md`   | 7         | Si documentation requise |
+| 11        | `questionnaire/11-data-lifecycle.md`  | 14        | Si lifecycle requis (retention, archivage, RGPD) |
+| 12        | `questionnaire/12-migration.md`       | 14        | Si nouveau module (migration donnees existantes) |
+| 13        | `questionnaire/13-cross-module.md`    | 14        | Si nouveau module OU references autres modules |
+| 14        | `questionnaire/14-risk-assumptions.md`| 16        | Toujours      |
+| 15        | `questionnaire/15-success-metrics.md` | 17        | Toujours      |
+
+**Total noyau (toujours chargés) : 130 questions** (contexte, acteurs, périmètre, risques, métriques)
+**Total avec application : 148 questions** (+ identité application si mode multi-module)
+**Total conditionnel : 124 questions** (data, intégrations, sécurité, UI, performance, contraintes, doc, lifecycle, migration, cross-module)
+**Total maximum possible : 272 questions** (noyau + application + tous conditionnels chargés)
 
 </questionnaire_files>