@atlashub/smartstack-cli 3.34.0 → 3.35.0

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

@@ -1,34 +1,201 @@
 ---
 name: step-01b-applications
-description: Application decomposition - identify and define multiple applications within a project
+description: Application identity confirmation (single-app) or full application decomposition (multi-app)
 model: opus
 next_step: steps/step-02-decomposition.md
 ---
 
 > **Context files:** `_shared.md`
 
-# Step 1b: Application Decomposition
+# Step 1b: Application Identity & Decomposition
 
 ## MANDATORY EXECUTION RULES
 
 - ALWAYS use ULTRATHINK mode
-- This step is ONLY loaded when `workflow.mode === "project"` (multi-application mode)
 - ALL communication in `{language}`
-- This step takes the candidate applications identified during cadrage and formalizes them
+- This step ALWAYS runs. It has two modes:
+  - **Single-app mode** (`workflow.mode !== "project"`): Lightweight application identity confirmation — name, code, context, route, icon, table prefix validation, application roles recap. Creates the `seedDataCore.navigationApplications` entry.
+  - **Multi-app mode** (`workflow.mode === "project"`): Full application decomposition as defined in sections 1-7 below.
 
-## YOUR TASK
+---
 
-For each candidate application identified during step-01 cadrage, define its identity, context, roles, and scope. Establish inter-application dependencies and create per-application feature.json files.
+## MODE GATE
+
+```
+IF workflow.mode === "project":
+  → Execute FULL multi-app flow (sections 1-7 below)
+ELSE:
+  → Execute LIGHTWEIGHT single-app identity (sections 0a-0f below)
+```
 
 ---
 
+## SINGLE-APP PATH (sections 0a-0f)
+
+> This path runs when `workflow.mode !== "project"` (single application, most common case).
+> It confirms the application-level identity (Level 2 of the navigation hierarchy) before proceeding to module decomposition.
+
+### 0a. Read Application Context
+
+```
+appFeature = ba-reader.findFeature({feature_id})
+→ Read metadata: application, context, tablePrefix
+→ Read cadrage: applicationRoles, coverageMatrix, globalScope
+→ Read cadrage.codebaseContext (if exists)
+```
+
+### 0b. Derive Application Identity
+
+From the cadrage data, derive the formal application identity:
+
+```javascript
+applicationCode = toPascalCase(metadata.application)  // e.g., "HumanResources"
+applicationLabel = metadata.application                // e.g., "Ressources Humaines" (human-readable)
+context = metadata.context                             // "business" (validated in step-00)
+applicationRoute = `/${context}/${toKebabCase(applicationCode)}`  // e.g., "/business/human-resources"
+applicationIcon = suggestIconFromDomain(applicationCode) // e.g., "users" for HR, "shopping-cart" for Sales
+tablePrefix = metadata.tablePrefix                     // e.g., "rh_" (already defined in step-01)
+sort = 1                                               // First (and only) application
+```
+
+**Icon suggestion heuristics:**
+| Domain pattern | Suggested icon |
+|---------------|---------------|
+| HR, Employee, Staff, Personnel | `users` |
+| Sales, Commerce, Revenue | `shopping-cart` |
+| Finance, Accounting, Budget | `wallet` |
+| Inventory, Stock, Warehouse | `package` |
+| CRM, Customer, Client | `contact` |
+| Project, Task, Planning | `clipboard-list` |
+| Support, Ticket, Help | `headphones` |
+| Reporting, Analytics, Dashboard | `bar-chart-2` |
+| Other | `layout-grid` |
+
+### 0c. Confirm Application Identity (BLOCKING)
+
+Display the application identity:
+
+```
+{language == "fr"
+  ? "## Identité de l'application\n\nVoici l'identité de votre application dans la hiérarchie de navigation SmartStack :"
+  : "## Application Identity\n\nHere is your application's identity in the SmartStack navigation hierarchy:"}
+
+| {language == "fr" ? "Niveau" : "Level"} | {language == "fr" ? "Valeur" : "Value"} |
+|-------|-------|
+| Context | `{context}` |
+| Application Code | `{applicationCode}` |
+| Application Name | `{applicationLabel}` |
+| Route | `{applicationRoute}` |
+| Icon | `{applicationIcon}` |
+| Table Prefix | `{tablePrefix}` |
+| Sort Order | `{sort}` |
+
+{language == "fr"
+  ? "### Rôles applicatifs\n\nCes rôles seront hérités par tous les modules :"
+  : "### Application Roles\n\nThese roles will be inherited by all modules:"}
+
+| Role | Level | Permission Pattern |
+|------|-------|--------------------|
+{for each role in cadrage.applicationRoles: role.role | role.level | {context}.{kebab(applicationCode)}.* }
+```
+
+Ask via AskUserQuestion:
+```
+question: "{language == 'fr' ? 'Cette identité d\'application est-elle correcte ?' : 'Is this application identity correct?'}"
+header: "Application"
+options:
+  - label: "{language == 'fr' ? 'Oui, parfait' : 'Yes, perfect'}"
+    description: "{language == 'fr' ? 'Code, route, icône et rôles sont corrects' : 'Code, route, icon and roles are correct'}"
+  - label: "{language == 'fr' ? 'Modifier' : 'Modify'}"
+    description: "{language == 'fr' ? 'Changer le code, la route, l\'icône ou les rôles' : 'Change code, route, icon or roles'}"
+```
+
+**IF "Modify":**
+→ Ask which field(s) to change via follow-up AskUserQuestion
+→ Apply changes
+→ Re-display and re-confirm (loop until validated)
+
+### 0d. Build Application SeedData Entries
+
+Create the `navigationApplications` entry (Level 2 hierarchy entry):
+
+```json
+{
+  "navigationApplications": [
+    {
+      "code": "{applicationCode}",
+      "label": "{applicationLabel}",
+      "icon": "{applicationIcon}",
+      "route": "{applicationRoute}",
+      "sort": 1
+    }
+  ]
+}
+```
+
+Create the `applicationRoles` entries (from cadrage.applicationRoles):
+
+```json
+{
+  "applicationRoles": [
+    { "code": "admin", "name": "{applicationLabel} Admin", "permissions": "*" },
+    { "code": "manager", "name": "{applicationLabel} Manager", "permissions": "CRU" },
+    { "code": "contributor", "name": "{applicationLabel} Contributor", "permissions": "CR" },
+    { "code": "viewer", "name": "{applicationLabel} Viewer", "permissions": "R" }
+  ]
+}
+```
+
+> **NOTE:** The roles map from `cadrage.applicationRoles` levels. If the cadrage defined custom roles beyond the standard 4, include them here too.
+
+### 0e. Write Application Identity to Feature.json
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata",
+  data: {
+    applicationCode: "{applicationCode}",
+    applicationRoute: "{applicationRoute}",
+    applicationIcon: "{applicationIcon}"
+  }
+})
+```
+
+> **NOTE:** The full `seedDataCore` arrays (`navigationApplications`, `applicationRoles`) will be written in step-03c when compiling the first module's specification. Here we only persist the identity fields in metadata so they are available to step-02 and step-03.
+
+### 0f. Summary and Continue
+
+```
+{language == "fr"
+  ? "✅ Application **{applicationCode}** identifiée\n\n- Route : `{applicationRoute}`\n- Icône : `{applicationIcon}`\n- Préfixe : `{tablePrefix}`\n- Rôles : {roleCount} rôles applicatifs définis\n\n→ Prochaine étape : décomposition en modules"
+  : "✅ Application **{applicationCode}** identified\n\n- Route: `{applicationRoute}`\n- Icon: `{applicationIcon}`\n- Prefix: `{tablePrefix}`\n- Roles: {roleCount} application roles defined\n\n→ Next step: module decomposition"}
+```
+
+→ Load `steps/step-02-decomposition.md`
+
+---
+
+## MULTI-APP PATH (sections 1-7)
+
+> This path runs when `workflow.mode === "project"` (multi-application mode).
+> It takes the candidate applications identified during cadrage and formalizes them.
+
 ### 1. Load Project Context
 
 ```
 projectFeature = ba-reader.findProjectFeature()
-candidateApps = projectFeature.cadrage.coverageMatrix grouped by domain
 globalRoles = projectFeature.cadrage.globalRoles (if defined)
 globalScope = projectFeature.cadrage.globalScope
+
+// Candidate applications: PRE-IDENTIFIED from step-00 prompt analysis + enriched by step-01 cadrage
+candidateApps = projectFeature.metadata.candidateApplications
+// These candidates already have: name, description, modules[], context, dependencies[]
+// They may also include transversal apps extracted from shared modules (step-01 section 5b)
+
+IF candidateApps is null or empty:
+  // Fallback: derive from coverage matrix (legacy path)
+  candidateApps = projectFeature.cadrage.coverageMatrix grouped by domain
 ```
 
 ### 2. Application Identity (per candidate)
@@ -154,14 +321,14 @@ options:
   - label: "{language == 'fr' ? 'Modifier' : 'Modify'}"
     description: "{language == 'fr' ? 'Ajouter, supprimer ou modifier des applications' : 'Add, remove, or modify applications'}"
   - label: "{language == 'fr' ? 'Fusionner en une seule' : 'Merge into one'}"
-    description: "{language == 'fr' ? 'Finalement, c'est une seule application avec plusieurs modules' : 'Actually, this is one application with multiple modules'}"
+    description: "{language == 'fr' ? 'Finalement, c\'est une seule application avec plusieurs modules' : 'Actually, this is one application with multiple modules'}"
 ```
 
 **IF "Merge into one":**
 → Convert back to single-application mode
 → Delete project-level feature.json
 → Create application-level feature.json with all scope items
-→ Load `steps/step-02-decomposition.md` directly
+→ Execute single-app path (sections 0a-0f above)
 
 ### 5. Create Per-Application Feature.json Files
 
@@ -175,6 +342,9 @@ ba-writer.createApplicationFeature({
   status: "draft",
   metadata: {
     application: {app.code},
+    applicationCode: {toPascalCase(app.code)},
+    applicationRoute: {`/${app.context}/${toKebabCase(app.code)}`},
+    applicationIcon: {app.icon},
     context: {app.context},
     language: {language},
     featureDescription: {app.description},
@@ -208,6 +378,7 @@ ba-writer.enrichApplicationRegistry({
       context: {app1.context},
       tablePrefix: {app1.tablePrefix},
       icon: {app1.icon},
+      route: {app1.route},
       description: {app1.description},
       applicationRoles: [{...}],
       scope: { mustHave: [...], shouldHave: [...], couldHave: [...] },
@@ -236,9 +407,9 @@ ba-writer.updateStatus({project_id}, "decomposed")
   ? "### Décomposition en applications terminée\n\n"
   : "### Application decomposition complete\n\n"}
 
-| Application | Contexte | Préfixe | Feature ID |
-|-------------|----------|---------|------------|
-{for each app: name | context | prefix | FEAT-NNN}
+| Application | Contexte | Préfixe | Route | Feature ID |
+|-------------|----------|---------|-------|------------|
+{for each app: name | context | prefix | route | FEAT-NNN}
 
 {language == "fr"
   ? "→ Prochaine étape : décomposition en modules pour **{firstApp}** (application {1}/{total})"
@@ -249,4 +420,4 @@ ba-writer.updateStatus({project_id}, "decomposed")
 
 ## NEXT STEP
 
-Load: `./step-02-decomposition.md` (for the first application in topological order)
+Load: `./step-02-decomposition.md` (for the first application in topological order, or the single application)

package/templates/skills/business-analyse/steps/step-03c-compile.md

@@ -301,11 +301,20 @@ for (const entry of specification.navigation.entries) {
 
 #### 8f. SeedData Core
 
-7 MANDATORY typed arrays — each with structured objects, NOT flat strings or objects.
+9 MANDATORY typed arrays — each with structured objects, NOT flat strings or objects.
 
 > **STRUCTURE CARD: specification.seedDataCore**
 > ```json
 > {
+>   "navigationApplications": [
+>     { "code": "{app}", "label": "{Application Name}", "icon": "{icon}", "route": "/business/{app-kebab}", "sort": 1 }
+>   ],
+>   "applicationRoles": [
+>     { "code": "admin", "name": "{App} Admin", "permissions": "*" },
+>     { "code": "manager", "name": "{App} Manager", "permissions": "CRU" },
+>     { "code": "contributor", "name": "{App} Contributor", "permissions": "CR" },
+>     { "code": "viewer", "name": "{App} Viewer", "permissions": "R" }
+>   ],
 >   "navigationModules": [
 >     { "code": "{module}", "label": "{Module Name}", "icon": "list", "route": "/business/{app}/{module}", "parentCode": "{app}", "sort": 1 }
 >   ],
@@ -339,7 +348,8 @@ for (const entry of specification.navigation.entries) {
 >   ]
 > }
 > ```
-> **MANDATORY:** All 7 arrays must be present. Each element must be an object, NOT a string.
+> **MANDATORY:** All 9 arrays must be present. Each element must be an object, NOT a string.
+> **NOTE:** `navigationApplications` and `applicationRoles` are populated from the application identity confirmed in step-01b. They are written ONCE for the first module processed and remain empty `[]` for subsequent modules.
 > **CRITICAL:** `navigationSections` and `navigationResources` are DERIVED from `specification.sections[]` — use the transform algorithm below (section 8f-bis).
 > **IMPORTANT:** `create` and `edit` are NEVER sections — they are action pages reached via buttons. Do NOT include them in `navigationSections`. Only include actual sidebar sections (list, dashboard, approve, import, etc.) and hidden route sections (detail).
 > **FORBIDDEN:** Do NOT use `navigationModule` (singular string), `permissions` as flat string array, `rolePermissions` as flat object, `permissionsConstants` as comma-separated string.
@@ -388,6 +398,8 @@ ba-writer.enrichSection({
   section: "specification",
   data: {
     seedDataCore: {
+      navigationApplications: [ ... ],            // FROM step-01b identity (only for first module, else [])
+      applicationRoles: [ ... ],                  // FROM cadrage.applicationRoles (only for first module, else [])
       navigationModules: [ ... ],
       navigationSections: navigationSections,     // DERIVED
       navigationResources: navigationResources,   // DERIVED

package/templates/skills/business-analyse/steps/step-03d-validate.md

@@ -73,7 +73,7 @@ Validate the module specification for completeness and consistency, write to fea
 | messages | 4 | `specification.messages.length >= 4` | PASS/FAIL |
 | messageFormat | `message` field present (BLOCKING) | `specification.messages.every(m => m.message)` | PASS/FAIL |
 | lifeCycles | 1 (if entity has status) | `specification.lifeCycles.length >= 1` (if any entity has status/state field) | PASS/FAIL |
-| seedDataCore | 7 arrays present with content | See detailed check below | PASS/FAIL (BLOCKING) |
+| seedDataCore | 9 arrays present with content | See detailed check below | PASS/FAIL (BLOCKING) |
 | apiEndpoints | 1 | `specification.apiEndpoints.length >= 1` | PASS/FAIL |
 | i18nKeys | present | `specification.i18nKeys !== undefined && specification.i18nKeys !== null` | PASS/FAIL |
 | navigationIcons | non-null | `specification.seedDataCore.navigationModules.every(m => m.icon !== null)` | PASS/FAIL |
@@ -81,7 +81,11 @@ Validate the module specification for completeness and consistency, write to fea
 **seedDataCore detailed check (BLOCKING):**
 ```javascript
 const sdc = specification.seedDataCore;
+const currentModuleIndex = metadata.workflow?.currentModuleIndex || 0;
 const checks = [
+  // navigationApplications and applicationRoles: required for first module (index 0), can be empty for subsequent modules
+  { key: "navigationApplications", actual: sdc.navigationApplications?.length || 0, min: currentModuleIndex === 0 ? 1 : 0 },
+  { key: "applicationRoles",      actual: sdc.applicationRoles?.length || 0,       min: currentModuleIndex === 0 ? 1 : 0 },
   { key: "navigationModules",      actual: sdc.navigationModules?.length || 0,      min: 1 },
   { key: "navigationSections",     actual: sdc.navigationSections?.length || 0,     min: 1 },  // EVERY module needs ≥1 section
   { key: "navigationResources",    actual: sdc.navigationResources?.length || 0,    min: 1 },

package/templates/skills/ralph-loop/SKILL.md

@@ -79,6 +79,8 @@ LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODUL
 | `{current_iteration}` | number | Current iteration |
 | `{current_module}` | string\|null | Current module (multi-module) |
 | `{modules_queue}` | object\|null | Module queue (multi-module) |
+| `{section_split_mode}` | boolean | Section splitting active for current module (>4 entities + >1 section) |
+| `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
 </state_variables>
 
 <mcp_requirements>
@@ -141,6 +143,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 |------|-------------|
 | `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
 | `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
+| `references/section-splitting.md` | Step-01 section 4c when module has >4 entities + >1 section |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>
 
@@ -151,6 +154,8 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 ├── progress.txt          # Persistent memory
 ├── modules-queue.json    # Multi-module tracking (if applicable)
 ├── prd-{module}.json     # Per-module PRDs (from ss derive-prd, unified v3 format)
+├── prd-{module}-phase0.json         # Section split: Foundation (domain+infra+migration)
+├── prd-{module}-section-{code}.json # Section split: Per-section (app+api+seed+frontend+tests)
 ├── logs/
 └── reports/
     └── {feature}.md

package/templates/skills/ralph-loop/references/category-rules.md

@@ -65,3 +65,32 @@ A valid PRD MUST contain tasks in these categories:
 - `test` — at least 1 test task
 
 If any category is missing, ralph step-01 injects a guardrail task.
+
+---
+
+## Section-Level Splitting (>4 Entities)
+
+When a module has many entities, a single `/apex -d` call saturates the context window.
+Section-level splitting breaks the module into smaller, manageable phases.
+
+**Activation threshold:** `> 4 domain tasks` AND `> 1 architecture section`
+
+| Phase | Content | Depends On |
+|-------|---------|------------|
+| Phase 0 | ALL domain + infrastructure + migration + module seed data | — |
+| Phase 1 | Section A: services, controllers, section seed, pages, i18n, tests | Phase 0 |
+| Phase 2 | Section B: idem | Phase 0 (+ Phase 1 if FK cross-section) |
+| Phase N | Section N: idem | Phase 0 (+ earlier phases if FK) |
+| Final | Cross-validation (dotnet build, typecheck, MCP validate) | All phases |
+
+**Key rules:**
+- Phase 0 creates ALL entity classes + ALL EF configs + ONE migration (avoids ModelSnapshot conflicts)
+- Section phases NEVER create entities or migrations — only services, controllers, pages on top
+- FK cross-section dependencies determine section execution order (topological sort)
+- Orphan entities (not in any section) are included in Phase 0 with their services/controllers
+- Each phase produces a temporary PRD file: `.ralph/prd-{module}-phase0.json`, `.ralph/prd-{module}-section-{code}.json`
+- Temporary PRD files are cleaned up in step-05 (report)
+
+**Backward compatible:** Modules with `<= 4 domain tasks` or `1 section` → standard execution, zero impact.
+
+See `references/section-splitting.md` for full detection, mapping, and execution logic.

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -23,10 +23,93 @@ Display compact progress:
 
 ---
 
-## A. Find Eligible Tasks
+## A0. Section-Split Mode (checked BEFORE standard batching)
 
 ```javascript
 const prd = readJSON('.ralph/prd.json');
+
+if (prd._sectionSplit?.enabled) {
+  // SECTION-SPLIT: Delegate per-phase instead of per-category batch
+
+  // Find next pending phase with dependencies met
+  const nextPhase = prd._sectionSplit.phases.find(p => p.status === 'pending');
+
+  if (!nextPhase) {
+    // All phases done — check if master PRD tasks are all complete
+    goto CHECK_COMPLETION;
+  }
+
+  const depsOk = nextPhase.dependsOn.every(depIdx =>
+    prd._sectionSplit.phases[depIdx].status === 'completed'
+  );
+
+  if (!depsOk) {
+    // Phase blocked — should not happen with topological sort
+    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
+    goto CHECK_COMPLETION;
+  }
+
+  const phaseLabel = nextPhase.type === 'foundation'
+    ? `Phase 0: Foundation (${nextPhase.entities.length} entities + migration)`
+    : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (${nextPhase.entities.length} entities)`;
+  console.log(`[{iteration}/{max}] SECTION SPLIT: ${phaseLabel}`);
+
+  // INVOKE /apex -d {nextPhase.prdFile}
+  // Apex sees a normal (smaller) PRD and executes normally
+
+  // After apex returns: merge results back into master PRD
+  // Read references/section-splitting.md sections 7-9
+  const phasePrd = readJSON(nextPhase.prdFile);
+  for (const phaseTask of phasePrd.tasks) {
+    const masterTask = prd.tasks.find(t => t.id === phaseTask.id);
+    if (masterTask) {
+      masterTask.status = phaseTask.status;
+      masterTask.completed_at = phaseTask.completed_at;
+      masterTask.commit_hash = phaseTask.commit_hash;
+      masterTask.files_changed = phaseTask.files_changed;
+      masterTask.error = phaseTask.error;
+      masterTask.validation = phaseTask.validation;
+    }
+  }
+
+  // Handle phase failure
+  if (phasePrd.tasks.some(t => t.status === 'failed')) {
+    const retryCount = nextPhase._retryCount || 0;
+    if (retryCount < 2) {
+      nextPhase.status = 'pending';
+      nextPhase._retryCount = retryCount + 1;
+      console.log(`Phase ${nextPhase.phase} had failures — retry ${retryCount + 1}/2`);
+      // Reset failed tasks in phase PRD for retry
+      for (const task of phasePrd.tasks) {
+        if (task.status === 'failed') { task.status = 'pending'; task.error = null; }
+      }
+      writeJSON(nextPhase.prdFile, phasePrd);
+    } else {
+      nextPhase.status = 'failed';
+      console.error(`Phase ${nextPhase.phase} failed after 2 retries`);
+    }
+  } else {
+    nextPhase.status = 'completed';
+  }
+
+  prd._sectionSplit.currentPhase = nextPhase.phase;
+  writeJSON('.ralph/prd.json', prd);
+
+  // → Skip to section C (commit PRD state), then D (loop back)
+  goto COMMIT_PRD;
+}
+```
+
+> **IMPORTANT:** When `_sectionSplit.enabled`, the standard category-based batching (section A below)
+> is SKIPPED. The loop delegates per-phase to apex instead of per-category-batch.
+
+---
+
+## A. Find Eligible Tasks
+
+> **Note:** This section is SKIPPED when `prd._sectionSplit?.enabled` (handled by A0 above).
+
+```javascript
 const MAX_RETRIES = 3;
 
 // RETRY: Reset failed tasks to pending if retries remain (max 3 attempts per task)
@@ -115,7 +198,7 @@ writeJSON('.ralph/prd.json', prd);
 Apex handles everything for the current module:
 - Reads PRD, extracts context (context_code, app_name, module_code, entities, sections)
 - Executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
-- Runs full POST-CHECKs (43 checks from `references/post-checks.md`)
+- Runs full POST-CHECKs (50 checks from `references/post-checks.md`)
 - Commits per layer (atomic commits)
 - Validates with MCP (`validate_conventions`)
 - Updates task statuses in the PRD file directly