@atlashub/smartstack-cli 4.51.0 → 4.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.51.0",
+  "version": "4.53.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/apex/references/core-seed-data.md

@@ -1003,6 +1003,21 @@ public class RolePermissionSeedEntry
 
 ## 6. IClientSeedDataProvider Implementation
 
+> **IMPORTANT — HasData vs Seed*Async: TWO DIFFERENT MECHANISMS**
+>
+> | Mechanism | Where | When | Purpose |
+> |-----------|-------|------|---------|
+> | **EF Core `HasData()`** | `*Configuration.cs` (Infrastructure) | At migration time | Seeds static reference data into tables via `INSERT` in migration SQL. Data is part of the migration — no runtime code needed. |
+> | **`IClientSeedDataProvider.Seed*Async()`** | `*SeedDataProvider.cs` (Infrastructure) | At runtime startup | Seeds navigation, roles, permissions, role-permissions into the **Core** schema. Runs AFTER `MigrateAsync()` in `Program.cs`. |
+>
+> **Common mistake:** Generating `HasData()` calls for navigation/permissions instead of `Seed*Async()` methods.
+> Navigation and permission data goes into the **Core** schema (`core.nav_*`, `core.auth_*`) which is managed
+> by SmartStack, not by the client's migration. Only `IClientSeedDataProvider` can write to Core tables at runtime.
+>
+> **ANTI-STUB WARNING:** Each of the 4 Seed methods MUST contain real `context.{DbSet}.Add()` calls.
+> If ANY method is just `return Task.CompletedTask;`, the module will be **invisible** in the UI (empty menu).
+> This happens when this reference file is evicted from context by compression — see step-03b safeguard.
+
 **File:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
 
 ### Critical Rules

package/templates/skills/apex/references/error-classification.md

@@ -100,6 +100,28 @@
 
 ---
 
+### Category G: PRD Quality Error (FIX = fix PRD or re-run handoff)
+
+> **These errors are NOT caused by code generation — they originate from invalid PRD data.**
+> The handoff generated file paths with illegal characters (spaces, apostrophes, accents in entity names).
+> Code generation faithfully reproduced the invalid paths → build failure.
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `error CS1001: Identifier expected` with file name containing spaces | `Type d'absence.cs` → CS1001 | Re-run `/business-analyse-handoff` with entity canonicalization |
+| `error CS1513/CS1514` with file name containing apostrophes | `Congé.cs` → accent in identifier | Fix entity name in BA or re-run handoff |
+| Path contains non-ASCII characters in `.cs` file names | `Département.cs` | Canonicalize: strip diacritics, PascalCase |
+
+**Detection heuristic:** If the error file path contains spaces, apostrophes, or accented characters, it is a PRD quality error, not a code error. Do NOT attempt to fix the generated code — fix the PRD source.
+
+**Fix procedure:**
+1. Identify the invalid entity name from the error file path
+2. Report to user: "PRD quality error — entity name '{name}' is not a valid C# identifier"
+3. Either: manually canonicalize in the PRD file, or re-run `/business-analyse-handoff` (which now includes canonicalization)
+4. Re-run `/apex -d` with the corrected PRD
+
+---
+
 ## Decision Tree
 
 When a build or runtime error occurs, follow this tree:
@@ -123,9 +145,11 @@ BUILD/RUNTIME ERROR
   |     YES -> Category E (edit config files)
   |
   +-- error CS#### (C# compiler error) ?
-  |     YES -> Is the missing type in ANY project file?
-  |           NO  -> Category A (missing package)
-  |           YES -> Category F (fix source code)
+  |     YES -> Does the error file path contain spaces, apostrophes, or accents?
+  |           YES -> Category G (PRD quality error — fix handoff, not code)
+  |           NO  -> Is the missing type in ANY project file?
+  |                 NO  -> Category A (missing package)
+  |                 YES -> Category F (fix source code)
   |
   +-- Test failure (Assert/Expected) ?
         YES -> Category F (fix source code, NOT tests)

package/templates/skills/apex/references/post-checks.md

@@ -90,7 +90,7 @@ bash references/checks/infrastructure-checks.sh
 | C20 | WARNING | Section route completeness (NavigationSection → frontend route + permissions) | seed-checks.sh |
 | C21 | WARNING | FORBIDDEN route patterns — /list and /detail/:id | seed-checks.sh |
 | C22 | WARNING | Permission path segment count (2-4 dots expected) | seed-checks.sh |
-| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods + DI registration | seed-checks.sh |
+| C23 | BLOCKING | IClientSeedDataProvider must have 4 methods with real implementation (not stubs) + DI registration | seed-checks.sh |
 | C32 | CRITICAL | Translation seed data must have idempotency guard | seed-checks.sh |
 | C33 | CRITICAL | Resource seed data must use actual section IDs from DB | seed-checks.sh |
 | C34 | BLOCKING | NavRoute segments must use kebab-case for multi-word codes — MCP overlap | seed-checks.sh |
@@ -101,6 +101,8 @@ bash references/checks/infrastructure-checks.sh
 | C47 | WARNING | Person Extension entities must not duplicate User fields | seed-checks.sh |
 | C48 | CRITICAL | Person Extension service must Include(User) | seed-checks.sh |
 | C53 | BLOCKING | Enum serialization — JsonStringEnumConverter required | seed-checks.sh |
+| C57 | BLOCKING | SeedDataProvider Seed*Async methods must NOT be `return Task.CompletedTask` or empty body — stubs cause empty menu | seed-checks.sh |
+| C58 | BLOCKING | File paths in filesToCreate must be valid C# identifiers — no spaces, apostrophes, or accents | seed-checks.sh |
 
 ### Architecture — Clean Architecture Layer Isolation (A1-A8)
 

package/templates/skills/apex/steps/step-00-init.md

@@ -94,6 +94,46 @@ if (prd.specificationFiles) {
 
 Each layer step (step-03a through step-03d) will load its companion files at the start. This provides full BA specifications (entity attributes, BR formulas, UC steps, screen columns) without loading the entire spec corpus.
 
+**PRD Quality Gate (delegate mode — BLOCKING):**
+
+> Validate that PRD file paths are valid C# identifiers BEFORE starting execution.
+> Invalid entity names (French with spaces/apostrophes/accents) cause CS1001 build errors
+> that waste 3+ retry iterations before being correctly classified.
+
+```javascript
+// Extract all file paths from PRD
+const filesToCreate = prd.$version === '4.0.0' ? prd.expectedFiles : prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  const invalidPaths = [];
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      const filePath = file.path || file;
+      // Extract filename (without extension) from path
+      const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
+      // Check for illegal characters in C# identifiers
+      if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
+        invalidPaths.push({ category, path: filePath, fileName });
+      }
+    }
+  }
+
+  if (invalidPaths.length > 0) {
+    console.error('BLOCKING — PRD QUALITY ERROR (not a code error):');
+    console.error('The following file paths contain illegal C# identifier characters:');
+    for (const p of invalidPaths) {
+      console.error(`  ${p.category}: ${p.path} (invalid name: "${p.fileName}")`);
+    }
+    console.error('');
+    console.error('FIX: Re-run /business-analyse-handoff which now includes entity name canonicalization.');
+    console.error('     Or manually fix entity names in the PRD (strip accents, remove spaces/apostrophes, PascalCase).');
+    console.error('');
+    console.error('This is a PRD quality error (Category G), NOT a code generation error.');
+    console.error('Do NOT attempt to generate code from this PRD — it will fail with CS1001.');
+    STOP; // Do not proceed with invalid PRD
+  }
+}
+```
+
 **Jump to:** section 3 (MCP verify) → section 6 (determine needs) → section 9 (summary)
 
 ---
@@ -248,6 +288,23 @@ needs_notification = {module_complexity} in ["crud-workflow","complex"] OR menti
 
 Read latest task directory in `.claude/output/apex/`:
 - **If state.json exists:** resume step-03 at next uncompleted layer (skip completed)
+  - **Delegate context recovery:** If `state.delegate_mode === true`:
+    1. Restore `{delegate_prd_path}` from `state.delegate_prd_path`
+    2. Restore `{app_name}`, `{module_code}`, `{sections}`, `{entities}` from state
+    3. Re-read PRD at `{delegate_prd_path}` to rebuild `{specification_loading_plan}`:
+       ```javascript
+       const prd = readJSON(state.delegate_prd_path);
+       if (prd.specificationFiles) {
+         const sf = prd.specificationFiles;
+         specification_loading_plan = {
+           layer0_domain:   [sf.entities],
+           layer1_seed:     [sf.entities, sf.permissions],
+           layer2_backend:  [sf.rules, sf.usecases],
+           layer3_frontend: [sf.screens, sf.usecases]
+         };
+       }
+       ```
+    4. Set `{delegate_mode} = true` — companion spec loading will work in remaining layers
 - **Else if 00-context.md exists:** restore step-00 state, re-derive post-step-00 from git + files
 - **Else:** full re-derive from git history + files
 

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

@@ -46,19 +46,35 @@ Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
 BEFORE starting Layer N:
   Verify these variables are still accessible:
     {app_name}, {module_code}, {sections}, {entities}, {code_patterns}
+    IF delegate_mode: also verify {delegate_prd_path}, {specification_loading_plan}
 
   IF any variable is missing or empty:
     1. Read .claude/output/apex/{task_id}/state.json (if exists)
-    2. IF state.json missing → re-derive from filesystem:
+    2. IF state.json has delegate context:
+       - {delegate_prd_path} = state.delegate_prd_path
+       - {delegate_mode} = state.delegate_mode
+       - Re-read PRD at {delegate_prd_path} to rebuild specification_loading_plan:
+         const prd = readJSON(delegate_prd_path);
+         if (prd.specificationFiles) {
+           specification_loading_plan = {
+             layer0_domain:   [prd.specificationFiles.entities],
+             layer1_seed:     [prd.specificationFiles.entities, prd.specificationFiles.permissions],
+             layer2_backend:  [prd.specificationFiles.rules, prd.specificationFiles.usecases],
+             layer3_frontend: [prd.specificationFiles.screens, prd.specificationFiles.usecases]
+           };
+         }
+       - {app_name} = state.app_name || prd.project?.application || prd.metadata?.applicationCode
+       - {module_code} = state.module_code || prd.project?.module || prd.metadata?.moduleCode
+    3. IF state.json missing OR no delegate context → re-derive from filesystem:
        - {app_name}: Glob("docs/business/*/") → first directory name
        - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
        - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
        - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse
        - {code_patterns}: Read state.json or re-derive from DependencyInjection.cs
-    3. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
-    4. IF Layer N-1 already completed: skip to Layer N directly
+    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+    5. IF Layer N-1 already completed: skip to Layer N directly
 
-  Cost: ~5 tool calls. Only triggered if context was compressed.
+  Cost: ~5-8 tool calls. Only triggered if context was compressed.
 ```
 
 ---
@@ -126,6 +142,7 @@ Layer 4: feat({module}): [devdata] test data for development  # if applicable
 ## State Auto-Save (after each layer)
 
 > **Automatic** — not dependent on `-s` flag. Enables reliable resume after context loss.
+> **CRITICAL (audit ba-003):** Delegate context MUST be persisted for resume to work in delegate mode.
 
 After each layer's build gate passes, write state to `.claude/output/apex/{task_id}/state.json`:
 
@@ -137,10 +154,21 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
   "files_created": ["Employee.cs", "EmployeeConfiguration.cs", "..."],
   "build_gates": { "layer0": "pass", "layer1": "pass", "layer2": "pass" },
   "commits": ["abc1234", "def5678", "ghi9012"],
-  "timestamp": "2026-03-06T14:30:00Z"
+  "timestamp": "2026-03-06T14:30:00Z",
+  "delegate_mode": true,
+  "delegate_prd_path": ".ralph/prd-employees.json",
+  "app_name": "HumanResources",
+  "module_code": "employee-management",
+  "sections": ["employees", "departments"],
+  "entities": ["Employee", "Department"]
 }
 ```
 
+> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`**
+> are persisted so that Context Recovery Protocol (above) can restore the full execution context
+> after context compression or resume (`-r`). The `specification_loading_plan` is rebuilt from the
+> PRD file at `delegate_prd_path` — no need to serialize it directly.
+
 ---
 
 ## Save Output (if save_mode)

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -42,6 +42,24 @@ TaskUpdate(taskId: progress_tracker_id,
 
 > This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
 
+> **CONTEXT COMPRESSION SAFEGUARD (delegate mode):**
+> In delegate mode (`-d`), `references/core-seed-data.md` may have been evicted from context by compression
+> before Layer 1 begins (it was loaded at step-03 entry but is ~1464 lines).
+>
+> **CHECK:** Can you see Section 6 "IClientSeedDataProvider Implementation" from `core-seed-data.md` in your context?
+> - **YES** → Proceed normally using the templates from that section.
+> - **NO** → **Re-read** `references/core-seed-data.md` lines 1004-1296 NOW (the IClientSeedDataProvider template).
+>   This section contains the complete C# template for the provider class with all 4 Seed methods.
+>
+> **WARNING — ANTI-STUB RULE:**
+> The SeedDataProvider MUST contain real implementation code. Each of the 4 methods
+> (`SeedNavigationAsync`, `SeedRolesAsync`, `SeedPermissionsAsync`, `SeedRolePermissionsAsync`)
+> MUST have actual entity creation logic with `context.{DbSet}.Add()` calls.
+>
+> **BLOCKING:** If ANY Seed method body is just `return Task.CompletedTask;` or `{ }` (empty),
+> the seed data layer is INVALID. The module will be invisible in the UI (menu vide / empty menu).
+> Re-read the template from `references/core-seed-data.md` Section 6 and generate proper implementation.
+
 ---
 
 ### Mode Detection: CREATE vs UPDATE

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -169,6 +169,9 @@ For each module:
     3. Add the new namespace import + registration for all 4 languages
     4. If config uses dynamic imports: add namespace to the `ns` array
     5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
+    6. **I18n File/Import Alignment Check:** Verify that every locale JSON file on disk for this module
+       has a corresponding import in the i18n config index.ts. Glob `src/**/i18n/locales/*/` for module files,
+       then verify each is imported. Missing imports cause silent translation failures (keys show as raw strings).
 - Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
   then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
 - Section routes: Ensure navigation seed data has ComponentKey matching PageRegistry keys.

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

@@ -131,6 +131,41 @@ IF ANY cell = NO → BLOCKING — return to step-03b to fix
 
 Execute all checks from `references/post-checks.md`. If any fails, fix in step-03 and re-validate.
 
+### 6c. SeedDataProvider Content Verification (BLOCKING)
+
+> **LESSON LEARNED (audit ba-003):** SeedDataProvider existed and had 4 methods (passed C23),
+> but all methods were `return Task.CompletedTask` — stubs generated when `core-seed-data.md`
+> was evicted from context by compression. Result: empty menu, 0 applications visible.
+
+```javascript
+// Find the SeedDataProvider file
+const providerFiles = Glob("**/Seeding/*SeedDataProvider.cs");
+for (const providerFile of providerFiles) {
+  const content = readFile(providerFile);
+
+  // Check 1: No stub methods — each Seed*Async must have real implementation
+  const methods = ['SeedNavigationAsync', 'SeedRolesAsync', 'SeedPermissionsAsync', 'SeedRolePermissionsAsync'];
+  for (const method of methods) {
+    const methodRegex = new RegExp(`${method}[^{]*\\{([^}]*)\\}`, 's');
+    const match = content.match(methodRegex);
+    if (match) {
+      const body = match[1].trim();
+      if (body === 'return Task.CompletedTask;' || body === '' || body === 'return;') {
+        BLOCKING_ERROR(`${providerFile}: ${method} is a STUB (${body || 'empty body'}). ` +
+          `Re-read references/core-seed-data.md Section 6 and generate real implementation. ` +
+          `Stub seed methods cause EMPTY MENU — 0 applications visible in UI.`);
+      }
+    }
+  }
+
+  // Check 2: Must contain actual entity creation calls
+  if (!content.includes('.Add(') && !content.includes('.AddRange(')) {
+    BLOCKING_ERROR(`${providerFile}: No .Add() or .AddRange() calls found. ` +
+      `SeedDataProvider must actually insert seed data, not just return.`);
+  }
+}
+```
+
 ---
 
 ## 7. Acceptance Criteria POST-CHECK

package/templates/skills/business-analyse/references/canonical-json-formats.md

@@ -0,0 +1,200 @@
+# Canonical JSON Formats Reference
+
+> **Purpose:** Single source of truth for all JSON file formats produced by the BA pipeline.
+> **Used by:** `/business-analyse` (step-03), `/business-analyse-design` (step-01), `/business-analyse-html`, `/business-analyse-handoff`, `/business-analyse-develop`
+> **Rule:** All producers MUST write canonical format. All consumers MUST accept canonical + deprecated fallbacks.
+
+---
+
+## entities.json
+
+```json
+{
+  "entities": [
+    {
+      "name": "Employee",
+      "description": "...",
+      "personRoleConfig": { "variant": "mandatory", "userFields": ["firstName", "lastName", "email"] },
+      "attributes": [
+        { "name": "code", "type": "string", "required": true, "description": "..." },
+        { "name": "userId", "type": "string", "required": true, "description": "FK auth_Users (ASP.NET Identity)" }
+      ],
+      "versionedAttributes": [
+        { "entity": "Salary", "attributes": ["grossAmount", "effectiveDate"], "reason": "..." }
+      ],
+      "relationships": [
+        { "target": "Department", "type": "ManyToOne", "description": "..." }
+      ]
+    }
+  ]
+}
+```
+
+**Convention guards:**
+- Person entities → `personRoleConfig` + `userId` (string), NO firstName/lastName/email
+- Versioned data → `versionedAttributes[]`, NOT inline fields
+- FK naming → always `{entity}Id` suffix
+- FK to auth_Users → type `string` (ASP.NET Identity), NOT `guid`
+
+---
+
+## usecases.json
+
+```json
+{
+  "useCases": [
+    {
+      "id": "UC-MODULE-001",
+      "name": "Créer un employé",
+      "sectionCode": "list",
+      "primaryActor": "Responsable RH",
+      "preconditions": ["..."],
+      "mainScenario": [
+        "L'utilisateur ouvre la page de création",
+        "Il remplit les champs obligatoires"
+      ],
+      "alternativeScenarios": [
+        { "name": "Données invalides", "steps": ["Le système affiche les erreurs"] }
+      ],
+      "businessRules": ["BR-VAL-MODULE-001"],
+      "result": "L'entité est créée"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `useCases` (root) | `usecases` | camelCase is canonical |
+| `primaryActor` | `actor` | |
+| `mainScenario` (string[]) | `steps` (object[] or string[]) | MUST be strings, never `{step, action}` objects |
+| `alternativeScenarios` (object[]) | `alternativeFlows`, `alternative` (string) | Must be `[{name, steps}]` |
+
+---
+
+## rules.json
+
+```json
+{
+  "rules": [
+    {
+      "id": "BR-VAL-MODULE-001",
+      "name": "Validation date",
+      "category": "validation",
+      "sectionCode": "list",
+      "statement": "La date ne peut pas être dans le futur",
+      "example": "Date = 2027-01-01 → erreur",
+      "entities": ["Employee"],
+      "severity": "blocking"
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives |
+|---------------|------------------------|
+| `rules` (root) | `businessRules` |
+| `statement` | `description` |
+| `id` | `name` (as identifier) |
+
+Categories: `validation`, `calculation`, `workflow`, `security`, `data`, `notification`
+
+---
+
+## permissions.json
+
+```json
+{
+  "roles": [
+    { "role": "RH Admin", "description": "..." }
+  ],
+  "permissionPaths": [
+    "HumanResources.Employees.Read",
+    "HumanResources.Employees.Create"
+  ],
+  "matrix": {
+    "roleAssignments": [
+      { "role": "RH Admin", "permissions": ["HumanResources.Employees.*"] }
+    ]
+  }
+}
+```
+
+---
+
+## screens.json
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employés",
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "label": "Grille des employés",
+          "columns": [
+            { "field": "code", "label": "Code", "type": "text", "sortable": true }
+          ],
+          "filters": [
+            { "field": "status", "type": "select", "label": "Statut" }
+          ],
+          "actions": ["create", "export"],
+          "permission": "HumanResources.Employees.Read"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Canonical key | Deprecated alternatives | Notes |
+|---------------|------------------------|-------|
+| `sections` (root) | `screens` (flat array) | `sections[]` with `resources[]` is canonical |
+| `sectionCode` | `id`, `code` | |
+| `sectionLabel` | `displayName`, `label` | |
+| resource `type` | `layout`, `componentType` | Must be: SmartTable, SmartForm, SmartDashboard, SmartKanban, SmartCard, SmartFilter |
+| column `field` | `code`, `name`, `id`, `fieldCode` | |
+| column `label` | `displayName` | |
+
+**DEPRECATED format (do NOT produce):**
+```json
+{
+  "screens": [
+    { "screen": "employees-list", "section": "list", "componentType": "SmartTable", "columns": [...] }
+  ]
+}
+```
+
+---
+
+## Consumer normalization pattern
+
+All downstream consumers should normalize input using this priority chain:
+
+```javascript
+// usecases
+const rawUCs = data.useCases || data.usecases || [];
+const uc = {
+  name: raw.name || raw.title || raw.id,
+  actor: raw.primaryActor || raw.actor,
+  steps: (raw.mainScenario || raw.steps || []).map(s =>
+    typeof s === 'string' ? s : (s.action || s.description || "")
+  ),
+  alternatives: raw.alternativeScenarios || raw.alternativeFlows || []
+};
+
+// screens
+const sections = data.sections || [];
+const flatScreens = data.screens || [];
+// If flat format: wrap each screen as a section with 1 resource
+
+// columns
+const col = {
+  field: raw.field || raw.code || raw.name || raw.id,
+  label: raw.label || raw.displayName || raw.code,
+  type: raw.renderAs === "badge" ? "badge" : (raw.type || raw.dataType || "text")
+};
+```