@atlashub/smartstack-cli 3.10.0 → 3.13.0

package/templates/skills/business-analyse/references/detection-strategies.md

@@ -0,0 +1,424 @@
+# Detection Strategies - New vs Update vs Review
+
+Source: business-analyse step-00-init.md
+
+This document describes the algorithms used in step-00-init.md to automatically detect the workflow type (new application, update, or review mode) and match user intent against existing business analyses.
+
+---
+
+## 1. Review Mode Detection
+
+**Trigger:** `{feature_description}` starts with `-review` (with or without extra text)
+
+### Algorithm
+
+```javascript
+function detectReviewMode(feature_description) {
+  const isReviewMode = feature_description.trim().startsWith('-review');
+
+  if (!isReviewMode) {
+    return { mode: null };
+  }
+
+  // Scan docs/business/ for most recent application
+  const applications = glob('docs/business/*/business-analyse/*/feature.json')
+    .map(path => ({
+      path,
+      metadata: readJSON(path).metadata,
+      updatedAt: readJSON(path).metadata.updatedAt
+    }))
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+
+  if (applications.length === 0) {
+    return {
+      mode: 'review',
+      error: 'NO_APPLICATIONS_FOUND',
+      fix: 'Create an application first using /business-analyse'
+    };
+  }
+
+  const latestApp = applications[0];
+  const versionDir = path.dirname(latestApp.path);
+  const reviewFilePath = path.join(versionDir, 'ba-review.json');
+
+  if (!fs.existsSync(reviewFilePath)) {
+    return {
+      mode: 'review',
+      error: 'NO_REVIEW_FILE',
+      applicationName: latestApp.metadata.application,
+      expectedPath: reviewFilePath,
+      fix: `
+        To create ba-review.json:
+        1. Open ba-interactive.html in your browser
+        2. Make your corrections
+        3. Click "Sauvegarder corrections" button
+        4. Save the downloaded ba-review.json in: ${versionDir}/
+        5. Run /business-analyse -review again
+      `
+    };
+  }
+
+  return {
+    mode: 'review',
+    reviewJsonPath: reviewFilePath,
+    applicationName: latestApp.metadata.application,
+    docsDir: versionDir,
+    nextStep: 'step-06-review.md'
+  };
+}
+```
+
+### Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| `{feature_description}` starts with `-review` | Activate review mode detection |
+| ba-review.json found | Skip to step-06-review.md |
+| ba-review.json NOT found | Display error with fix instructions, STOP |
+| No applications exist | Display error, STOP |
+
+### Error Messages
+
+**Error 1: No Applications Found**
+```
+ERROR: No existing applications found in docs/business/
+
+You must create an application first using:
+  /business-analyse
+
+Then generate ba-interactive.html, make corrections, and export ba-review.json.
+```
+
+**Error 2: No Review File**
+```
+ERROR: No ba-review.json found in docs/business/{app}/business-analyse/v{version}/
+
+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
+5. Run /business-analyse -review again
+
+Expected path: {expectedPath}
+```
+
+---
+
+## 2. Existing Applications Scanner
+
+**Objective:** Build a catalog of existing business analyses for comparison.
+
+### Scan Algorithm
+
+```javascript
+function scanExistingApplications() {
+  const featureFiles = glob('docs/business/*/business-analyse/*/feature.json');
+
+  const existingApps = featureFiles.map(path => {
+    const feature = readJSON(path);
+    return {
+      app: feature.metadata.application,
+      featureId: feature.id,
+      description: feature.metadata.featureDescription,
+      version: extractVersion(path),  // e.g., "1.0" from "v1.0"
+      path: path,
+      updatedAt: feature.metadata.updatedAt,
+      modules: feature.modules?.map(m => m.code) || [],
+      status: feature.status
+    };
+  });
+
+  // Sort by most recent first
+  existingApps.sort((a, b) => b.updatedAt - a.updatedAt);
+
+  return existingApps;
+}
+```
+
+### Output Schema
+
+```typescript
+interface ExistingApp {
+  app: string;              // "HumanResources"
+  featureId: string;        // "FEAT-001"
+  description: string;      // "Gestion des projets et absences"
+  version: string;          // "1.0", "1.1", "2.0"
+  path: string;             // "docs/business/HumanResources/..."
+  updatedAt: string;        // ISO timestamp
+  modules: string[];        // ["Projects", "TimeTracking", "Reporting"]
+  status: string;           // "draft", "consolidated", "handed-off"
+}
+```
+
+### Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No feature.json files found | Return empty array → triggers "new application" mode |
+| Corrupted feature.json | Skip file, log warning, continue scan |
+| Multiple versions of same app | Include all, sorted by updatedAt |
+| Incomplete applications (status="draft") | Include but flag in description |
+
+---
+
+## 3. New vs Update Detection
+
+**Objective:** Determine if user wants to create a new application or update an existing one.
+
+### Similarity Analysis Algorithm
+
+```javascript
+function analyzeSimilarity(feature_description, existingApps) {
+  const scores = existingApps.map(app => ({
+    app,
+    score: calculateSimilarityScore(feature_description, app)
+  }));
+
+  // Sort by highest score first
+  scores.sort((a, b) => b.score - a.score);
+
+  return scores;
+}
+
+function calculateSimilarityScore(description, existingApp) {
+  let score = 0;
+
+  // 1. Application name match (50 points)
+  if (description.toLowerCase().includes(existingApp.app.toLowerCase())) {
+    score += 50;
+  }
+
+  // 2. Module name match (30 points)
+  for (const module of existingApp.modules) {
+    if (description.toLowerCase().includes(module.toLowerCase())) {
+      score += 30;
+      break;
+    }
+  }
+
+  // 3. Update keywords (40 points)
+  const updateKeywords = [
+    'ajouter', 'modifier', 'changer', 'enrichir', 'mettre à jour',
+    'add', 'modify', 'change', 'update', 'extend'
+  ];
+  for (const keyword of updateKeywords) {
+    if (description.toLowerCase().includes(keyword)) {
+      score += 40;
+      break;
+    }
+  }
+
+  // 4. Domain overlap (20 points)
+  // Check if description and existing app share domain terms
+  const domainTerms = extractDomainTerms(existingApp.description);
+  for (const term of domainTerms) {
+    if (description.toLowerCase().includes(term.toLowerCase())) {
+      score += 5;  // Up to 20 points (4 terms)
+    }
+  }
+
+  return score;
+}
+
+function extractDomainTerms(text) {
+  // Extract nouns/domain entities (simplified)
+  const words = text.toLowerCase().split(/\s+/);
+  return words.filter(w => w.length > 4);  // Filter short words
+}
+```
+
+### Decision Tree
+
+```
+┌─────────────────────────────────────┐
+│ existing_apps.length === 0?         │
+└──┬─────────────────────────┬────────┘
+   │ YES                     │ NO
+   │                         │
+   v                         v
+┌──────────────┐      ┌──────────────────────┐
+│ workflow_type │      │ Calculate similarity  │
+│ = "new"       │      │ scores for all apps   │
+└──────────────┘      └──────┬───────────────┘
+                              │
+                              v
+                     ┌─────────────────────┐
+                     │ Top score >= 80?    │
+                     └──┬─────────────┬────┘
+                        │ YES         │ NO
+                        │             │
+                        v             v
+              ┌──────────────┐  ┌──────────────┐
+              │ Suggest       │  │ Show all     │
+              │ update to     │  │ options with │
+              │ matched app   │  │ "New app" as │
+              │ as first      │  │ first option │
+              │ option        │  │              │
+              └───────────────┘  └──────────────┘
+                        │             │
+                        v             v
+                   ┌────────────────────────┐
+                   │ Ask via                │
+                   │ AskUserQuestion        │
+                   └─────────┬──────────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              v                             v
+    ┌──────────────────┐        ┌──────────────────┐
+    │ User selects     │        │ User selects     │
+    │ "Update {app}"   │        │ "New app"        │
+    └────────┬─────────┘        └────────┬─────────┘
+             │                            │
+             v                            v
+    ┌──────────────────┐        ┌──────────────────┐
+    │ workflow_type =  │        │ workflow_type =  │
+    │ "update"         │        │ "new"            │
+    │ existing_feature │        │                  │
+    │ = app.featureId  │        │                  │
+    └──────────────────┘        └──────────────────┘
+```
+
+### AskUserQuestion Format
+
+**When similarity score >= 80 (strong match):**
+```javascript
+AskUserQuestion({
+  question: "J'ai trouvé une analyse existante similaire. Que souhaitez-vous faire ?",
+  header: "Mode",
+  options: [
+    {
+      label: `Mise à jour de ${matchedApp.app} (${matchedApp.featureId})`,
+      description: `Enrichir ou modifier l'application existante (crée v${nextVersion})`
+    },
+    {
+      label: "Nouvelle application",
+      description: "Créer une nouvelle analyse complète"
+    }
+  ]
+});
+```
+
+**When multiple apps but no strong match:**
+```javascript
+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"
+    },
+    ...existingApps.slice(0, 3).map(app => ({
+      label: `Mise à jour de ${app.app} (${app.featureId})`,
+      description: `Enrichir ${app.app} — modules: ${app.modules.join(', ')}`
+    }))
+  ]
+});
+```
+
+### Update Mode Flow
+
+When user selects an existing app for update:
+
+```javascript
+function initiateUpdateMode(existingApp) {
+  // 1. Call ba-writer to create new version
+  const newVersion = ba_writer.createVersion(
+    existingApp.featureId,
+    feature_description
+  );
+
+  // 2. Copy previous version data as baseline
+  const previousFeature = readJSON(existingApp.path);
+  const newFeature = {
+    ...previousFeature,
+    id: existingApp.featureId,  // Keep same feature ID
+    version: newVersion.version,  // Increment version (e.g., "1.0" → "1.1")
+    status: "draft",
+    metadata: {
+      ...previousFeature.metadata,
+      featureDescription: feature_description,  // New description
+      workflowType: "update",
+      previousVersion: extractVersion(existingApp.path),
+      updatedAt: new Date().toISOString()
+    }
+  };
+
+  // 3. Write new version feature.json
+  const newPath = `docs/business/${existingApp.app}/business-analyse/v${newVersion.version}/feature.json`;
+  writeJSON(newPath, newFeature);
+
+  return {
+    workflow_type: "update",
+    existing_feature_id: existingApp.featureId,
+    version: newVersion.version,
+    application_name: existingApp.app,
+    docs_dir: path.dirname(newPath)
+  };
+}
+```
+
+---
+
+## Similarity Scoring Reference
+
+| Match Type | Score | Example |
+|-----------|-------|---------|
+| **Application name exact** | 50 | "HumanResources" in description → matches HumanResources app |
+| **Module name exact** | 30 | "Projects" in description → matches app with Projects module |
+| **Update keyword** | 40 | "ajouter", "modifier", "mettre à jour" |
+| **Domain term overlap** | 5 per term (max 20) | "project", "absence", "employee" |
+
+**Total possible:** 140 points
+
+**Thresholds:**
+- **>= 80:** Strong match → suggest update as first option
+- **50-79:** Moderate match → show as option but list "New app" first
+- **< 50:** Weak match → show in list but deprioritize
+
+---
+
+## State Variables After Detection
+
+After detection completes, these variables are set:
+
+```typescript
+interface DetectionResult {
+  workflow_type: "new" | "update" | "review";
+  existing_feature_id: string | null;        // Set only if workflow_type = "update"
+  version: string;                           // "1.0" (new) or "1.1"+ (update)
+  application_name: string;
+  review_json_path?: string;                 // Set only if workflow_type = "review"
+  docs_dir: string;
+}
+```
+
+---
+
+## Testing Detection Logic
+
+**Test Case 1: New Application (No Existing Apps)**
+- Input: `"Créer une application de gestion des congés"`
+- Expected: `workflow_type = "new"`, no prompt shown
+
+**Test Case 2: Strong Match for Update**
+- Input: `"Ajouter module de reporting à HumanResources"`
+- Existing: `HumanResources (FEAT-001)` with modules `[Projects, TimeTracking]`
+- Expected: Prompt with "Update HumanResources" as first option, score ~120
+
+**Test Case 3: Ambiguous (Multiple Matches)**
+- Input: `"Gérer les projets"`
+- Existing: `HumanResources (FEAT-001)` with Projects module, `ProjectManagement (FEAT-002)`
+- Expected: Prompt with "New app" first, both existing apps listed
+
+**Test Case 4: Review Mode**
+- Input: `"-review"`
+- Existing: `HumanResources` with ba-review.json present
+- Expected: Load ba-review.json, skip to step-06-review.md
+
+**Test Case 5: Review Mode - File Missing**
+- Input: `"-review"`
+- Existing: `HumanResources` but no ba-review.json
+- Expected: Display error with fix instructions, STOP

package/templates/skills/business-analyse/references/html-data-mapping.md

@@ -196,6 +196,10 @@ Default: "contributor"
 
 ## EMBEDDED_ARTIFACTS Mapping
 
+> **FIELD RENAME WARNING:** feature.json stores wireframes with `mockupFormat` and `mockup` fields.
+> The HTML renderer reads `format` and `content`. You MUST rename: `mockupFormat` → `format`, `mockup` → `content`.
+> Failure to rename = empty mockup display in the browser.
+
 Build a JSON object containing ALL visual artifacts from feature.json:
 
 ```javascript

package/templates/skills/business-analyse/references/prd-generation.md

@@ -0,0 +1,258 @@
+# PRD v3.0 Structure & Validation Rules
+
+Source: business-analyse step-05c-ralph-readiness.md
+
+## PRD File Format v3.0
+
+### File Location
+
+```
+.ralph/prd-{moduleCode}.json
+```
+
+Example: `.ralph/prd-Projects.json`, `.ralph/prd-TimeTracking.json`
+
+---
+
+## Structure Requirements
+
+### 1. Version Field (MANDATORY)
+
+```json
+{
+  "$version": "3.0.0"
+}
+```
+
+**Validation:**
+- MUST be exactly `"3.0.0"`
+- BLOCKING if missing or wrong version
+
+**Common Error:**
+```
+BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
+Fix: Re-run ss derive-prd with latest version
+```
+
+---
+
+### 2. Implementation Section (MANDATORY)
+
+**CRITICAL:** `filesToCreate` MUST be under `implementation`, NOT at root level.
+
+**Correct Structure:**
+```json
+{
+  "$version": "3.0.0",
+  "implementation": {
+    "filesToCreate": {
+      "domain": [...],
+      "application": [...],
+      "infrastructure": [...],
+      "api": [...],
+      "frontend": [...],
+      "seedData": [...],
+      "tests": [...]
+    }
+  }
+}
+```
+
+**Wrong Structure (v2.x legacy):**
+```json
+{
+  "$version": "3.0.0",
+  "filesToCreate": {  // ❌ WRONG - at root level
+    "domain": [...]
+  }
+}
+```
+
+**Validation:**
+- IF `prd.filesToCreate` exists at root level → BLOCKING ERROR
+- IF `prd.implementation.filesToCreate` missing → BLOCKING ERROR
+
+**Fix Command:**
+```bash
+ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json
+```
+
+---
+
+### 3. Seven Categories (MANDATORY)
+
+All PRD files MUST include these 7 categories under `implementation.filesToCreate`:
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| **domain** | Domain entities, value objects, domain services | `Project.cs`, `ProjectStatus.cs` |
+| **application** | Application services, DTOs, interfaces | `ProjectService.cs`, `CreateProjectDto.cs` |
+| **infrastructure** | Data access, repositories, EF Core config | `ProjectRepository.cs`, `ProjectConfiguration.cs` |
+| **api** | Controllers, API endpoints | `ProjectsController.cs` |
+| **frontend** | React pages, components, hooks | `ProjectsPage.tsx`, `useProjects.ts` |
+| **seedData** | Seed data classes | `ProjectSeedData.cs` |
+| **tests** | Unit tests, integration tests | `ProjectServiceTests.cs`, `ProjectsControllerTests.cs` |
+
+**Validation:**
+```javascript
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);
+
+if (missingCategories.length > 0) {
+  BLOCKING_ERROR(`Missing categories: ${missingCategories.join(', ')}`);
+}
+```
+
+**Common Errors:**
+- Missing `tests` category → often forgotten
+- Missing `seedData` category → sometimes omitted for modules without seed data
+- Empty arrays allowed (e.g., `"seedData": []`) if genuinely no files needed
+
+---
+
+### 4. File Count Consistency (MANDATORY)
+
+**Validation:** PRD file counts MUST match feature.json handoff counts.
+
+```javascript
+const featureHandoff = moduleFeature.handoff.filesToCreate;
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+
+for (const cat of categories) {
+  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but feature.json has ${featureCount}`);
+  }
+}
+```
+
+**Why this matters:**
+- Ensures PRD was derived from the correct feature.json
+- Catches stale PRD files (derived from old version)
+- Validates handoff integrity before ralph-loop
+
+**Fix:**
+- Re-derive PRD from latest feature.json
+- Check that feature.json handoff section is complete
+
+---
+
+### 5. File Entry Schema
+
+Each file entry in a category array must have:
+
+```json
+{
+  "path": "src/SmartStack.HumanResources.Domain/Projects/Project.cs",
+  "type": "Entity",
+  "module": "Projects"
+}
+```
+
+**Required Fields:**
+- `path` (string): Absolute or relative path where file will be created
+- `type` (string): File type hint (Entity, Service, Controller, Page, Test, etc.)
+- `module` (string): Module code this file belongs to
+
+**Optional Fields:**
+- `description` (string): Brief description of what the file does
+- `dependencies` (array): Other files this depends on
+
+---
+
+## Validation Checklist
+
+Use this checklist when validating PRD files:
+
+| Check | Validation | Status |
+|-------|-----------|--------|
+| **Version** | `$version === "3.0.0"` | PASS/FAIL |
+| **Structure** | `implementation.filesToCreate` exists (not root) | PASS/FAIL |
+| **Categories** | All 7 categories present | PASS/FAIL |
+| **File Counts** | PRD counts match feature.json handoff | PASS/FAIL |
+| **File Schemas** | All files have path, type, module | PASS/FAIL |
+
+**All checks must PASS before proceeding to /ralph-loop**
+
+---
+
+## Common Errors & Fixes
+
+### Error 1: Wrong Version
+```
+BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
+```
+**Fix:** Re-run `ss derive-prd` with latest SmartStack.mcp version
+
+### Error 2: filesToCreate at Root Level
+```
+BLOCKING_ERROR: filesToCreate is at ROOT level (wrong structure)
+```
+**Fix:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+
+### Error 3: Missing Categories
+```
+BLOCKING_ERROR: Missing categories: seedData, tests
+```
+**Fix:**
+- Check feature.json handoff.filesToCreate has all 7 categories
+- Re-derive PRD after fixing feature.json
+- If genuinely no files needed, use empty array: `"seedData": []`
+
+### Error 4: File Count Mismatch
+```
+BLOCKING_ERROR: api: prd has 8 files but feature.json has 12
+```
+**Fix:**
+- PRD is stale (derived from old feature.json)
+- Re-derive PRD from latest feature.json: `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+
+---
+
+## Generation Command Reference
+
+**Derive PRD from feature.json:**
+```bash
+ss derive-prd \
+  --feature docs/business/{App}/{Module}/business-analyse/v1.0/feature.json \
+  --output .ralph/prd-{ModuleCode}.json
+```
+
+**Example:**
+```bash
+ss derive-prd \
+  --feature docs/business/HumanResources/Projects/business-analyse/v1.0/feature.json \
+  --output .ralph/prd-Projects.json
+```
+
+**Batch generation for all modules:**
+```bash
+# Typically done in step-05a-handoff.md
+for module in $(modules); do
+  ss derive-prd --feature {module_feature_path} --output .ralph/prd-${module}.json
+done
+```
+
+---
+
+## Why PRD Validation Matters
+
+| Risk | Without Validation | With Validation |
+|------|-------------------|-----------------|
+| **Wrong structure** | ralph-loop fails mid-execution | Caught before development starts |
+| **Stale PRD** | Generates code from old spec | Detects version mismatch |
+| **Missing files** | Incomplete implementation | Ensures all layers covered |
+| **Count mismatch** | Silent data loss | Guarantees integrity |
+
+**Bottom line:** Ralph-loop depends on correct PRD structure. Validating upfront saves hours of debugging.
+
+---
+
+## Related Files
+
+- `step-05a-handoff.md`: Generates PRD files via `ss derive-prd`
+- `step-05c-ralph-readiness.md`: Validates PRD structure before ralph-loop
+- `feature-schema.json`: Schema for feature.json (source of PRD)
+- `/ralph-loop` skill: Consumes PRD files for implementation