@atlashub/smartstack-cli 3.34.0 → 3.36.0

package/templates/skills/apex/steps/step-03-execute.md

@@ -22,6 +22,28 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 
 ---
 
+## Foundation Mode Detection
+
+**IF `{foundation_mode}` == true:**
+
+This is a foundation-only execution (called by ralph-loop Phase 0). Execute ONLY:
+- Layer 0: Domain entities + EF configs + Migration
+
+**SKIP ALL OTHER LAYERS:**
+- Layer 1: Application + API + Seed Data → SKIP
+- Layer 2: Frontend → SKIP
+- Layer 3: Tests → SKIP
+
+After Layer 0 completes and builds successfully:
+- Commit with message: `chore(foundation): entities for {module_code}`
+- Jump to step-04 for POST-CHECKs (domain + infrastructure only)
+- End execution
+
+**IF `{foundation_mode}` == false:**
+Execute ALL layers normally (Layer 0 → Layer 1 → Layer 2 → Layer 3).
+
+---
+
 ## Layer 0 — Domain + Infrastructure (sequential, agent principal)
 
 ### Domain Entities
@@ -44,16 +66,26 @@ For each entity:
 
 ### Migration (BLOCKING)
 
+> **CRITICAL — Migration must cover ALL entities, not just the first batch.**
+> Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities
+> were added later without re-running migration → 4 entities had no database tables.
+> **RULE:** Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
+> If entities are added incrementally, create a NEW migration for each batch.
+
 ```
-1. MCP suggest_migration → get standardized name
-2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
-3. Cleanup corrupted EF Core artifacts:
+1. Verify ALL entities have been added as DbSet in ExtensionsDbContext
+2. Verify ALL EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
+3. MCP suggest_migration → get standardized name
+4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
+5. Cleanup corrupted EF Core artifacts:
    for d in src/*/bin?Debug; do [ -d "$d" ] && rm -rf "$d"; done
-4. dotnet ef database update (if local DB)
-5. dotnet build → MUST PASS
+6. dotnet ef database update (if local DB)
+7. dotnet build → MUST PASS
+8. Verify: dotnet ef migrations has-pending-model-changes → MUST report "No pending model changes"
 ```
 
 **BLOCKING:** If build fails after migration, fix EF configs before proceeding.
+**BLOCKING:** If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
 
 ### Post-Layer 0 Build Gate
 
@@ -67,10 +99,66 @@ dotnet build
 
 ## Layer 1 — Application + API + Seed Data
 
+### NavRoute and Permission Kebab-Case (CRITICAL)
+
+> **ALL NavRoute segments and permission codes MUST use kebab-case for multi-word identifiers.**
+> Root cause (test-apex-007): Controllers had `[NavRoute("business.humanresources.employees")]`
+> instead of `[NavRoute("business.human-resources.employees")]`. This mismatched seed data routes
+> and permission codes, causing 404s and permission denials at runtime.
+
+**Rules:**
+- NavRoute: `business.human-resources.employees` (NEVER `business.humanresources.employees`)
+- Permissions: `business.human-resources.employees.read` (segments MATCH NavRoute exactly)
+- Seed data codes: `human-resources` (NEVER `humanresources`)
+- C# class names stay PascalCase (`HumanResourcesController`) — only route/permission strings use kebab-case
+- POST-CHECKs 41 + 48 validate this. Fix BEFORE committing.
+
+### Controller Route Attribute (BLOCKING)
+
+> **Controllers with `[NavRoute]` must NOT have `[Route]` attribute.**
+> Root cause (test-apex-007): ALL 7 controllers had BOTH `[Route("api/...")]` AND `[NavRoute("...")]`.
+> In SmartStack, `[NavRoute]` resolves routes dynamically from Navigation entities in the database at startup.
+> Having `[Route]` alongside causes route conflicts → all endpoints return 404.
+
+**Rules:**
+- `[NavRoute("context.app.module")]` is the ONLY route attribute needed on controllers
+- **FORBIDDEN:** `[Route("api/business/human-resources/employees")]` alongside `[NavRoute]`
+- **FORBIDDEN:** `[Route("api/[controller]")]` alongside `[NavRoute]`
+- If generating via MCP `scaffold_extension` with `navRoute` option → output is correct (NavRoute only)
+- If generating via `/controller` skill → verify NO `[Route]` is added
+- POST-CHECK 50 validates this. Fix BEFORE committing.
+
+### Validators DI Registration (CRITICAL)
+
+> After creating validators, they MUST be registered in DI. Without registration, `[FromBody]` DTOs are never validated.
+
+```
+In DependencyInjection.cs (or ServiceCollectionExtensions.cs):
+  services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();
+```
+
+POST-CHECK 46 validates this. If validators exist but no DI registration → BLOCKING.
+
 ### If economy_mode: Sequential execution
 
 Execute each item from the plan sequentially using skills and MCP.
 
+### Date Fields — Use DateOnly (CRITICAL)
+
+> **ALL date-only fields in DTOs MUST use `DateOnly`, NEVER `string`.**
+> Root cause (test-apex-007): WorkLog DTO had `string Date` instead of `DateOnly Date`.
+> This causes: no date validation, inconsistent date formats, parsing errors.
+
+**Type mapping for DTOs:**
+| Domain type | DTO type | Example |
+|-------------|----------|---------|
+| `DateTime` | `DateTime` | `CreatedAt`, `UpdatedAt` |
+| Date-only field | `DateOnly` | `Date`, `StartDate`, `EndDate`, `BirthDate` |
+| `string` for date | **FORBIDDEN** | Never use `string` for dates |
+| `DateTime` for date-only | **Avoid** | Use `DateOnly` when no time component needed |
+
+POST-CHECK 47 validates this. If a DTO has `string` type for a property named `*Date*` → BLOCKING.
+
 ### Code Generation (if entities have codePattern != "manual")
 
 For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
@@ -114,6 +202,7 @@ Code stays in CreateDto, user provides it, validator has regex rule.
   - A dead link (navigate to a route with no page) is a BLOCKING issue (POST-CHECK 42)
 - Read `references/smartstack-frontend.md` for mandatory patterns (sections 3b + 8)
 - Generate i18n JSON files for all 4 languages (fr, en, it, de) — `src/i18n/locales/{lang}/{module}.json`
+- **I18n REGISTRATION (CRITICAL):** After creating i18n JSON files, register EACH new namespace in the i18n config file (config.ts/index.ts/i18n.ts). Unregistered namespaces → `useTranslation(['module'])` returns empty strings at runtime. POST-CHECK 45 validates this.
 - All pages must follow loading → error → content pattern with CSS variables
 
 ### If NOT economy_mode: Agent Teams (parallel)

package/templates/skills/apex/steps/step-04-examine.md

@@ -262,7 +262,13 @@ AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
 | Security | TenantId filter, RequirePermission, no Guid.Empty, no !.Value | PASS / N/A |
 | Seed data | completeness, deterministic GUIDs, no ContextId/RoleId constants | PASS / N/A |
 | Code quality | PaginatedResult, EntityLookup (no FK select/input), CSS vars, search param | PASS / N/A |
-| POST-CHECKs | 43 checks from references/post-checks.md | PASS / N/A |
+| Migration completeness | ModelSnapshot covers ALL DbSet entities (POST-CHECK 44, 49) | PASS / N/A |
+| NavRoute kebab-case | NavRoute + permissions use kebab-case (POST-CHECK 48) | PASS / N/A |
+| DateOnly DTOs | Date fields use DateOnly not string (POST-CHECK 47) | PASS / N/A |
+| I18n registration | Namespaces registered in i18n config (POST-CHECK 45) | PASS / N/A |
+| Validators DI | FluentValidation registered in DI (POST-CHECK 46) | PASS / N/A |
+| Route/NavRoute conflict | No [Route] alongside [NavRoute] on controllers (POST-CHECK 50) | PASS / N/A |
+| POST-CHECKs | 50 checks from references/post-checks.md | PASS / N/A |
 | Acceptance criteria | AC1..ACn | {X}/{Y} PASS |
 ```
 

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

@@ -43,6 +43,7 @@ The skill auto-detects which use case applies by scanning existing features in `
 
 Step-00 handles detection automatically:
 - **New vs Update**: scans `docs/business/` for existing applications
+- **Single vs Multi-app**: multi-app detection in step-01, application identity confirmed in step-01b (always)
 - **Single vs Multi-module**: determined during step-02 decomposition
 - **Language**: detected from config or asked once
 - **Review mode**: if `-review` flag, routes directly to step-06
@@ -151,7 +152,7 @@ When step-00 detects that the description matches an existing application:
 **New application workflow (single or multi-app):**
 - **Step 00:** Detection, scan existing, create master feature.json (draft)
 - **Step 01:** Cadrage: context, stakeholders, scope, application roles (framed)
-- **Step 01b:** *(multi-app only)* Application decomposition: identify applications, contexts, prefixes, inter-app dependencies
+- **Step 01b:** Application identity (always): confirm code, route, icon, seed data (lightweight single-app / full decomposition multi-app)
 - **Step 02:** Decomposition: modules, dependencies, client checkpoint (decomposed) — per application in multi-app mode
 - **Step 03a:** Per-module data: sections, entities, business rules, questionnaires
 - **Step 03b:** Per-module UI: state machines, wireframes, layouts, dashboards
@@ -207,12 +208,12 @@ When step-00 detects that the description matches an existing application:
 | ---- | --------------------------------- | ------ | ---------------------------------------------------- |
 | 00   | `steps/step-00-init.md`           | Sonnet | Auto-detect new/update, scan existing, create master feature.json |
 | 01   | `steps/step-01-cadrage.md`        | Opus   | Framing: context, stakeholders, scope, application roles + multi-app detection |
-| 01b  | `steps/step-01b-applications.md`  | Opus   | *(multi-app only)* Application decomposition, contexts, prefixes, inter-app dependencies |
+| 01b  | `steps/step-01b-applications.md`  | Opus   | Application identity: confirm code, route, icon, seedData (lightweight single-app, full decomposition multi-app) |
 | 02   | `steps/step-02-decomposition.md`  | Opus   | Module decomposition, dependency graph, client checkpoint (per application in multi-app) |
 | 03a1 | `steps/step-03a1-setup.md`        | Opus   | Per-module: setup, sections, questionnaires, cross-refs |
 | 03a2 | `steps/step-03a2-analysis.md`     | Opus   | Per-module: objectives, entities, BRs, process flow |
 | 03b  | `steps/step-03b-ui.md`            | Opus   | Per-module: state machines, wireframes, layouts, dashboards |
-| 03c  | `steps/step-03c-compile.md`       | Opus   | Per-module: actors, UCs, FRs, permissions, navigation, seedDataCore (7 arrays), i18n |
+| 03c  | `steps/step-03c-compile.md`       | Opus   | Per-module: actors, UCs, FRs, permissions, navigation, seedDataCore (9 arrays), i18n |
 | 03d  | `steps/step-03d-validate.md`      | Sonnet | Per-module: validation, write, incremental HTML, loop decision |
 | 04a  | `steps/step-04a-collect.md`       | Opus   | Collect module summaries & cross-module interactions |
 | 04b  | `steps/step-04b-analyze.md`       | Opus   | Analyze permission coherence, semantic validation, E2E flows |

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

@@ -98,6 +98,15 @@ Level 1: Context (business)
             Level 4: Section (approve)           ← sidebar nav (workflow)
 ```
 
+**CRITICAL — Application identification (Level 2):**
+The application is formally identified in step-01b (ALWAYS, even for single-app mode):
+- Code: PascalCase (e.g., "HumanResources")
+- Route: kebab-case (e.g., "/business/human-resources")
+- Icon: Lucide icon name
+- Sort order: position in navigation
+This creates the `seedDataCore.navigationApplications` entry that links modules to their parent application.
+The `seedDataCore.applicationRoles` entries are also built from `cadrage.applicationRoles`.
+
 | BA Phase | Levels treated | What is defined |
 |----------|---------------|-----------------|
 | Cadrage (step-01) | Context + Application | Problem, stakeholders, scope, application-level roles |

package/templates/skills/business-analyse/schemas/application-schema.json

@@ -54,6 +54,19 @@
           "pattern": "^[a-z]{2,5}_$",
           "description": "Application table prefix for database tables (e.g., rh_, fi_, crm_). Defined during cadrage, used by all entities in this application."
         },
+        "applicationCode": {
+          "type": "string",
+          "description": "PascalCase application code for navigation hierarchy (e.g., HumanResources). Confirmed in step-01b."
+        },
+        "applicationRoute": {
+          "type": "string",
+          "pattern": "^/[a-z-/]+$",
+          "description": "Kebab-case route path for navigation (e.g., /business/human-resources). Confirmed in step-01b."
+        },
+        "applicationIcon": {
+          "type": "string",
+          "description": "Lucide icon name for application navigation entry (e.g., users, shopping-cart). Confirmed in step-01b."
+        },
         "workflow": {
           "type": "object",
           "description": "Iterative module loop state",

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

@@ -129,10 +129,116 @@ existing_projects: array of { projectName, projectId, applications[], version }
 
 > **Project Resume Detection:** If a project-level feature.json is found at `docs/business-analyse/*/feature.json`, check its `metadata.workflow` to determine resume point. The project may have partially completed applications.
 
+## Step 3b: Early Multi-Application Detection from Prompt (NEW)
+
+> **Detect multi-app structure BEFORE asking for a single application name.**
+> When the user's prompt explicitly describes multiple applications, we must recognize this immediately
+> and set `workflow.mode = "project"` to avoid doing cadrage for a single app.
+
+**Detection patterns (ANY match = multi-app detected):**
+
+```javascript
+const multiAppPatterns = [
+  // French patterns
+  /une\s+application\s+\w+.*une\s+application\s+\w+/is,
+  /application\s*\d?\s*[:]\s*\w+.*application\s*\d?\s*[:]\s*\w+/is,
+  /premier[e]?\s+application.*deuxième\s+application/is,
+  /app\s*1\s*[:.].*app\s*2\s*[:.]*/is,
+  // English patterns
+  /an?\s+application\s+(for\s+)?\w+.*an?\s+application\s+(for\s+)?\w+/is,
+  /application\s*#?\d\s*[:.].*application\s*#?\d\s*[:.]*/is,
+  /first\s+app.*second\s+app/is,
+];
+
+const isMultiApp = multiAppPatterns.some(p => p.test(feature_description));
+```
+
+**IF multi-app detected:**
+
+1. Extract candidate applications from the prompt:
+
+```javascript
+// Parse the prompt to identify application boundaries
+// Each "une application X" / "an application X" block = one candidate
+const candidates = extractApplicationCandidates(feature_description);
+// Result example:
+// [
+//   { name: "RH", description: "gestion des employes, conges, temps", modules: ["Employes", "Conges", "Temps"] },
+//   { name: "Projet", description: "gestion des projets, saisie du temps", modules: ["Projets", "Temps"] }
+// ]
+```
+
+2. Detect shared modules across candidates:
+
+```javascript
+const allModules = candidates.flatMap(c => c.modules);
+const sharedModules = allModules.filter((m, i) => allModules.indexOf(m) !== i);
+// Example: sharedModules = ["Temps"] → appears in both RH and Projet
+```
+
+3. Display detection result and confirm:
+
+```
+{language == "fr"
+  ? "### Détection multi-application\n\nJ'ai détecté **{candidates.length} applications** dans votre description :"
+  : "### Multi-application detection\n\nI detected **{candidates.length} applications** in your description:"}
+
+| # | Application | Modules identifiés |
+|---|-------------|-------------------|
+{for each candidate: index | name | modules.join(", ")}
+
+{sharedModules.length > 0
+  ? "⚠️ **Modules partagés détectés :** {sharedModules.join(', ')} — ces modules apparaissent dans plusieurs applications. Ils pourraient constituer une application transversale dédiée."
+  : ""}
+```
+
+Ask via AskUserQuestion:
+```
+question: "{language == 'fr' ? 'Confirmez-vous cette structure multi-application ?' : 'Do you confirm this multi-application structure?'}"
+header: "Architecture"
+options:
+  - label: "{language == 'fr' ? 'Oui, {candidates.length} applications' : 'Yes, {candidates.length} applications'}"
+    description: "{language == 'fr' ? 'Créer un projet avec les applications identifiées' : 'Create a project with the identified applications'}"
+  - label: "{language == 'fr' ? 'Extraire les modules partagés' : 'Extract shared modules'}" (only if sharedModules.length > 0)
+    description: "{language == 'fr' ? 'Créer une application dédiée pour {sharedModules.join(', ')} ({candidates.length + 1} applications au total)' : 'Create a dedicated app for {sharedModules.join(', ')} ({candidates.length + 1} total)'}"
+  - label: "{language == 'fr' ? 'Application unique' : 'Single application'}"
+    description: "{language == 'fr' ? 'Tout regrouper en une seule application avec plusieurs modules' : 'Group everything into one application with multiple modules'}"
+```
+
+**IF "Oui, N applications" or "Extraire les modules partagés":**
+
+```yaml
+workflow_mode: "project"
+project_name: derived from feature_description
+candidate_applications: [{ name, description, modules, context }]
+shared_modules_extracted: boolean  # true if user chose extraction
+```
+
+→ Skip step 4 (application name) — applications will be confirmed in step-01b
+→ Continue to step 5 (language selection)
+
+**IF "Application unique":**
+
+```yaml
+workflow_mode: "application"
+```
+
+→ Continue to step 4 normally
+
+**IF no multi-app patterns detected:**
+→ Continue to step 4 normally
+
 ## Step 4: Determine Application Name
 
+> **This step is SKIPPED if `workflow_mode = "project"` (multi-app detected in step 3b).**
+
 ```
-IF workflow_type = "update":
+IF workflow_mode = "project":
+  application_name = project_name  // Project-level name, not a single app name
+  context = "business"  // Default, each app can have its own context
+  → Skip to step 5
+
+ELSE IF workflow_type = "update":
   application_name = existing app name (from step 3)
 ELSE:
   Analyze {feature_description} to extract application name
@@ -149,12 +255,13 @@ ELSE:
 **Validate business context:**
 ```
 validate_business_context("business")
-→ BA restricted to 'business' context only
+→ BA restricted to 'business' context only (in standalone mode)
+→ In project mode, each application can target any context
 ```
 
 **Store:**
 ```yaml
-application_name: string
+application_name: string  # or project_name if project mode
 context: "business"
 ```
 
@@ -216,15 +323,22 @@ feature_id: string
 ## Step 7: Create Output Directory Structure
 
 ```
-IF workflow_type = "new":
+IF workflow_mode = "project":
+  // Project mode: create project-level directory + per-app directories later (in step-01b)
+  mkdir -p docs/business-analyse/v1.0
+  docs_dir = "docs/business-analyse/v{version}"
+
+ELSE IF workflow_type = "new":
   mkdir -p docs/business/{application_name}/business-analyse/v1.0
+  docs_dir = "docs/business/{app}/business-analyse/v{version}"
+
 ELSE:
   Directory already exists from ba-writer.createVersion()
 ```
 
 **Store:**
 ```yaml
-docs_dir: "docs/business/{app}/business-analyse/v{version}"
+docs_dir: string
 ```
 
 ## Step 8: Deploy JSON Schemas to Project (MANDATORY)
@@ -277,34 +391,67 @@ See [references/cache-warming-strategy.md](../references/cache-warming-strategy.
 Create the master feature document using ba-writer agent.
 
 ```
-ba-writer.createApplicationFeature({
-  id: {feature_id},
-  version: {version},
-  scope: "application",
-  status: "draft",
-  metadata: {
-    application: {application_name},
-    context: "business",
-    language: {language},
-    featureDescription: {feature_description},
-    workflowType: {workflow_type},
-    analysisMode: "interactive",
-    mcpAvailable: true,
-    workflow: {
-      mode: "application",
-      moduleOrder: [],
-      currentModuleIndex: 0,
-      completedModules: [],
-      currentModule: null
+IF workflow_mode = "project":
+  // PROJECT MODE: Create project-level feature.json
+  ba-writer.createProjectFeature({
+    id: generate_project_id(),  // PROJ-NNN
+    version: {version},
+    scope: "project",
+    status: "draft",
+    metadata: {
+      projectName: {project_name},
+      language: {language},
+      featureDescription: {feature_description},
+      workflowType: {workflow_type},
+      analysisMode: "interactive",
+      mcpAvailable: true,
+      candidateApplications: {candidate_applications},  // From step 3b detection
+      sharedModulesExtracted: {shared_modules_extracted},
+      workflow: {
+        mode: "project",
+        applicationOrder: [],
+        currentApplicationIndex: 0,
+        completedApplications: []
+      }
     }
-  }
-})
-```
+  })
 
-**Output path:**
-`docs/business/{app}/business-analyse/v{version}/feature.json`
+  Output path: docs/business-analyse/v{version}/feature.json
 
-> **Note:** Always create the master feature.json first. Step-02 (decomposition) determines if it's single or multi-module.
+  Store:
+    project_id: string  // PROJ-NNN
+    feature_id: project_id  // In project mode, feature_id = project_id for step-01
+
+ELSE:
+  // SINGLE-APP MODE: Create application-level feature.json
+  ba-writer.createApplicationFeature({
+    id: {feature_id},
+    version: {version},
+    scope: "application",
+    status: "draft",
+    metadata: {
+      application: {application_name},
+      context: "business",
+      language: {language},
+      featureDescription: {feature_description},
+      workflowType: {workflow_type},
+      analysisMode: "interactive",
+      mcpAvailable: true,
+      workflow: {
+        mode: "application",
+        moduleOrder: [],
+        currentModuleIndex: 0,
+        completedModules: [],
+        currentModule: null
+      }
+    }
+  })
+
+  Output path: docs/business/{app}/business-analyse/v{version}/feature.json
+```
+
+> **Note:** In project mode, per-application feature.json files are created later in step-01b.
+> In single-app mode, step-02 (decomposition) determines if it's single or multi-module.
 
 ## Step 10: Update Config
 
@@ -335,13 +482,18 @@ Update `.business-analyse/config.json` with new feature information.
 |--------------------|----------------------------------------------|
 | Feature ID         | {feature_id}                                 |
 | Workflow           | {workflow_type}                               |
-| Application        | business/{application_name}                  |
+| Mode               | {workflow_mode === "project" ? "Multi-application project" : "Single application"} |
+| Application/Project| {workflow_mode === "project" ? project_name + " (" + candidate_applications.length + " apps)" : "business/" + application_name} |
 | Output Path        | {docs_dir}/feature.json                      |
 | Language           | {language}                                   |
 | Version            | {version}                                    |
 | MCP Available      | true                                         |
 | Analysis Mode      | Interactive (always)                         |
 
+{workflow_mode === "project"
+  ? "Candidate applications: " + candidate_applications.map(a => a.name).join(", ")
+  : ""}
+
 NEXT STEP: step-01-cadrage
 ═══════════════════════════════════════════════════════════════
 ```
@@ -352,14 +504,18 @@ After showing initialization summary, proceed to `./step-01-cadrage.md`
 
 **Pass context variables:**
 ```yaml
-feature_id: string
+feature_id: string               # FEAT-NNN (single-app) or PROJ-NNN (project)
 feature_description: string
 workflow_type: "new" | "update"
-application_name: string
+workflow_mode: "application" | "project"
+application_name: string         # Single-app: app name. Project: project name.
+applicationCode: string          # PascalCase derived from application_name (preliminary, confirmed in step-01b)
+project_id: string | null        # PROJ-NNN if project mode, null if single-app
+candidate_applications: array | null  # Pre-identified apps from prompt (project mode only)
+shared_modules_extracted: boolean     # True if user chose to extract shared modules as new app
 language: string
 docs_dir: string
 mcp_available: boolean
-workflow_mode: "application"
 analysisMode: "interactive"
 version: string
 ```