@atlashub/smartstack-cli 3.16.0 → 3.17.0

package/package.json

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

package/templates/agents/gitflow/finish.md

@@ -77,10 +77,26 @@ git fetch origin develop:refs/remotes/origin/develop --force --quiet
 
 ### 4. Version Bump (Release/Hotfix)
 
-For npm projects:
+After merge-back to develop, invoke `/version-bump` to set the next development version:
+
+| Finished type | Next version | Example |
+|---------------|-------------|---------|
+| Release X.Y.Z | X.(Y+1).0 | 2.8.0 → 2.9.0 |
+| Hotfix X.Y.Z | X.Y.(Z+1) | 2.8.1 → 2.8.2 |
+
 ```bash
-npm version $NEXT_VERSION --no-git-tag-version
-git add package.json package-lock.json
+# Calculate NEXT_VERSION from the released version
+# Then call: /version-bump $NEXT_VERSION
+```
+
+This updates **all** version sources in sync:
+- `Directory.Build.props` → `<VersionPrefix>X.Y.Z</VersionPrefix>`
+- `web/smartstack-web/package.json` → `"version": "X.Y.Z"`
+- `.claude/gitflow/config.json` → `versioning.current`
+
+Then commit and push:
+```bash
+git add Directory.Build.props web/smartstack-web/package.json .claude/gitflow/config.json
 git commit -m "$(cat <<'EOF'
 chore: bump version to $NEXT_VERSION for development
 
@@ -90,6 +106,8 @@ EOF
 git push origin develop
 ```
 
+> **IMPORTANT**: Do NOT use `npm version` directly. Always use `/version-bump` for unified versioning.
+
 ### 5. Cleanup Worktree + Branch
 
 ```bash

package/templates/agents/gitflow/start.md

@@ -75,14 +75,24 @@ git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
 
 **Port allocation:** Hash branch name for unique ports (API: 5200+, Web: 5300+)
 
-### 7. Version Bump (Release only)
+### 7. Version Bump (Release/Hotfix only)
+
+For `release/*` and `hotfix/*` branches, invoke the `/version-bump` skill to synchronize all version files:
 
 ```bash
-# For release: bump version in source files
-npm version $VERSION --no-git-tag-version  # if package.json
-# OR update .csproj <Version> tag
+# Extract version from branch name: release/2.8.0 → 2.8.0, hotfix/2.8.1 → 2.8.1
+VERSION=$(echo "$FULL_BRANCH" | sed 's|^[^/]*/||')
 ```
 
+Then call: `/version-bump $VERSION`
+
+This updates **all** version sources in sync:
+- `Directory.Build.props` → `<VersionPrefix>X.Y.Z</VersionPrefix>`
+- `web/smartstack-web/package.json` → `"version": "X.Y.Z"`
+- `.claude/gitflow/config.json` → `versioning.current`
+
+> **IMPORTANT**: Do NOT use `npm version` or edit `.csproj` directly. Always use `/version-bump` for unified versioning.
+
 ### 8. Summary
 
 ```

package/templates/skills/application/templates-backend.md

@@ -82,6 +82,12 @@ public interface I$MODULE_PASCALService
 
 ## TEMPLATE: SERVICE IMPLEMENTATION
 
+> **TENANT ISOLATION RULES (BLOCKING):**
+> - ALL queries MUST include `.Where(x => x.TenantId == _currentUser.TenantId)`
+> - ALL entity creation MUST pass `_currentUser.TenantId` as first parameter to `Entity.Create()`
+> - NEVER use `new Entity { }` without `TenantId =` — always prefer the factory method
+> - NEVER use `Guid.Empty` as a placeholder — resolve the actual value from `_currentUser`
+
 ```csharp
 // src/SmartStack.Infrastructure/Services/$CONTEXT_PASCAL/$APPLICATION_PASCAL/$MODULE_PASCAL/$MODULE_PASCALService.cs
 
@@ -114,7 +120,8 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var query = _context.$ENTITY_PLURAL
-            .AsNoTracking();
+            .AsNoTracking()
+            .Where(x => x.TenantId == _currentUser.TenantId); // MANDATORY: tenant isolation
 
         // Apply filters
         if (!string.IsNullOrWhiteSpace(parameters.SearchTerm))
@@ -167,6 +174,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
     {
         var entity = await _context.$ENTITY_PLURAL
             .AsNoTracking()
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
 
         if (entity == null)
@@ -188,6 +196,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = $ENTITY_PASCAL.Create(
+            _currentUser.TenantId, // MANDATORY: tenant isolation — always first parameter
             request.Name,
             request.Description);
 
@@ -216,6 +225,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = await _context.$ENTITY_PLURAL
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken)
             ?? throw new NotFoundException("$ENTITY_PASCAL", id);
 
@@ -245,6 +255,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         CancellationToken cancellationToken = default)
     {
         var entity = await _context.$ENTITY_PLURAL
+            .Where(x => x.TenantId == _currentUser.TenantId) // MANDATORY: tenant isolation
             .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
 
         if (entity == null)

package/templates/skills/business-analyse/html/ba-interactive.html

@@ -3074,20 +3074,26 @@ function renderModuleMockups(code) {
             </div>` : ''}
             ${(wf.elements || []).length > 0 ? `
             <div class="wireframe-metadata">
-                <div><strong>Elements:</strong> ${wf.elements.join(', ')}</div>
+                <div><strong>Elements:</strong> ${wf.elements.map(e => typeof e === 'string' ? e : (e.type || e.label || e.id || '')).filter(Boolean).join(', ')}</div>
             </div>` : ''}
-            ${(wf.componentMapping || []).length > 0 ? `
+            ${(() => {
+                const cm = wf.componentMapping;
+                const mappings = Array.isArray(cm) ? cm
+                    : (typeof cm === 'object' && cm !== null) ? Object.entries(cm).map(([k,v]) => ({wireframeElement: k, reactComponent: v}))
+                    : [];
+                return mappings.length > 0 ? `
             <details class="wireframe-details">
                 <summary>Mapping composants SmartStack</summary>
                 <table class="mapping-table">
                     <thead><tr><th>Element maquette</th><th>Composant React</th></tr></thead>
                     <tbody>
-                        ${wf.componentMapping.map(m =>
-                            `<tr><td>${m.wireframeElement}</td><td><code>${m.reactComponent}</code></td></tr>`
+                        ${mappings.map(m =>
+                            '<tr><td>' + (m.wireframeElement || '') + '</td><td><code>' + (m.reactComponent || '') + '</code></td></tr>'
                         ).join('')}
                     </tbody>
                 </table>
-            </details>` : ''}
+            </details>` : '';
+            })()}
             <div class="wireframe-comment">
                 <label style="font-size:0.8rem;color:var(--text-muted);display:block;margin-bottom:0.3rem;">Commentaire / Feedback :</label>
                 <textarea class="form-textarea"

package/templates/skills/business-analyse/html/src/scripts/05-render-specs.js

@@ -392,20 +392,26 @@ function renderModuleMockups(code) {
             </div>` : ''}
             ${(wf.elements || []).length > 0 ? `
             <div class="wireframe-metadata">
-                <div><strong>Elements:</strong> ${wf.elements.join(', ')}</div>
+                <div><strong>Elements:</strong> ${wf.elements.map(e => typeof e === 'string' ? e : (e.type || e.label || e.id || '')).filter(Boolean).join(', ')}</div>
             </div>` : ''}
-            ${(wf.componentMapping || []).length > 0 ? `
+            ${(() => {
+                const cm = wf.componentMapping;
+                const mappings = Array.isArray(cm) ? cm
+                    : (typeof cm === 'object' && cm !== null) ? Object.entries(cm).map(([k,v]) => ({wireframeElement: k, reactComponent: v}))
+                    : [];
+                return mappings.length > 0 ? `
             <details class="wireframe-details">
                 <summary>Mapping composants SmartStack</summary>
                 <table class="mapping-table">
                     <thead><tr><th>Element maquette</th><th>Composant React</th></tr></thead>
                     <tbody>
-                        ${wf.componentMapping.map(m =>
-                            `<tr><td>${m.wireframeElement}</td><td><code>${m.reactComponent}</code></td></tr>`
+                        ${mappings.map(m =>
+                            '<tr><td>' + (m.wireframeElement || '') + '</td><td><code>' + (m.reactComponent || '') + '</code></td></tr>'
                         ).join('')}
                     </tbody>
                 </table>
-            </details>` : ''}
+            </details>` : '';
+            })()}
             <div class="wireframe-comment">
                 <label style="font-size:0.8rem;color:var(--text-muted);display:block;margin-bottom:0.3rem;">Commentaire / Feedback :</label>
                 <textarea class="form-textarea"

package/templates/skills/business-analyse/references/deploy-data-build.md

@@ -42,7 +42,19 @@ const FEATURE_DATA = {
     "{moduleCode}": {
       useCases: module.specification.useCases || [],
       businessRules: module.analysis.businessRules || [],
-      entities: module.analysis.entities || [],
+      // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated from canonical format
+      entities: (module.analysis.entities || []).map(ent => ({
+        name: ent.name,
+        description: ent.description || "",
+        attributes: (ent.attributes || []).length > 0
+          ? ent.attributes.map(a => ({ name: a.name, description: a.description || "" }))
+          : (ent.fields || []).map(f => ({ name: f.name, description: f.description || f.type || "" })),
+        relationships: (ent.relationships || []).length > 0
+          ? ent.relationships.map(r =>
+              typeof r === 'string' ? r : `${r.target} (${r.type}) - ${r.description || ""}`)
+          : (ent.fields || []).filter(f => f.foreignKey)
+              .map(f => `${f.foreignKey.table} (N:1) - ${f.description || f.name}`)
+      })),
       permissions: module.specification.permissions || [],
       apiEndpoints: module.specification.apiEndpoints || []
     }
@@ -85,15 +97,19 @@ const EMBEDDED_ARTIFACTS = {
     // PER-MODULE keyed object (NOT a flat array)
     // FOR EACH module: extract from specification.uiWireframes[]
     [moduleCode]: moduleFeature.specification.uiWireframes.map(wf => ({
-      screen: wf.screen,                          // e.g. "employees-list"
-      section: wf.section,                         // e.g. "list"
-      format: wf.mockupFormat || "ascii",          // RENAME: mockupFormat → format
-      content: wf.mockup,                          // RENAME: mockup → content (ASCII art string)
+      screen: wf.screen || wf.name || wf.id || "",  // SAFETY NET: fallback name/id → screen
+      section: wf.section || "",                      // e.g. "list"
+      format: wf.mockupFormat || "ascii",             // RENAME: mockupFormat → format
+      content: wf.mockup,                             // RENAME: mockup → content (ASCII art string)
       description: wf.description || "",
-      elements: wf.elements || [],                 // ["DataGrid", "FilterBar", ...]
-      actions: wf.actions || [],                   // ["filter", "sort", "create", ...]
-      componentMapping: wf.componentMapping || [],  // [{ wireframeElement, reactComponent }]
-      layout: wf.layout || null,                   // { type, regions: [...] }
+      elements: wf.elements || [],                    // [{ id, type, label }] or ["DataGrid", ...]
+      actions: wf.actions || [],                      // [{ trigger, action }] or ["filter", ...]
+      // SAFETY NET: convert object → array format if agent used { "Header": "PageHeader" } instead of [{ wireframeElement, reactComponent }]
+      componentMapping: Array.isArray(wf.componentMapping) ? wf.componentMapping
+        : typeof wf.componentMapping === 'object' && wf.componentMapping !== null
+          ? Object.entries(wf.componentMapping).map(([k, v]) => ({ wireframeElement: k, reactComponent: v }))
+          : [],
+      layout: typeof wf.layout === 'object' ? wf.layout : null,  // SAFETY NET: ignore string layout ("grid")
       permissionsRequired: wf.permissionsRequired || []
     }))
   },

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -32,6 +32,18 @@ const checklist = {
     details: "Standalone entities should be rare in business modules"
   },
 
+  entitySchemaCompliance: {
+    check: "All entities use canonical format: attributes[] (not fields[]), relationships[] array present",
+    status: specification.entities.every(e =>
+      Array.isArray(e.attributes) && e.attributes.length > 0 &&
+      !e.fields && !e.tableName && !e.primaryKey
+    ) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Entities with 'fields' instead of 'attributes' break HTML data model display and PRD extraction. " +
+             "Check: every entity must have attributes[] (not fields[]), every entity must have relationships[], " +
+             "no entity should have tableName or primaryKey (technical fields belong in implementation, not analysis)"
+  },
+
   // SECTION 2: BUSINESS RULES (BLOCKING)
   businessRules: {
     minimum: 4,
@@ -133,6 +145,21 @@ const checklist = {
     details: "EVERY section MUST have a wireframe (ASCII/SVG)"
   },
 
+  wireframeSchemaCompliance: {
+    check: "All wireframes have required fields: screen, section, mockupFormat, elements[], componentMapping[], layout (object), permissionsRequired[]",
+    status: specification.uiWireframes.every(wf =>
+      wf.screen && wf.section && wf.mockupFormat &&
+      Array.isArray(wf.elements) && wf.elements.length > 0 &&
+      Array.isArray(wf.componentMapping) && wf.componentMapping.length > 0 &&
+      typeof wf.layout === 'object' && wf.layout !== null &&
+      Array.isArray(wf.permissionsRequired)
+    ) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Wireframes missing metadata render as empty frames in HTML documentation. " +
+             "Check: screen (not name/id), section, mockupFormat, elements[] non-empty, " +
+             "componentMapping[] as array of {wireframeElement, reactComponent}, layout as object (not string)"
+  },
+
   navigation: {
     check: "Module has ≥1 navigation entry",
     status: specification.navigation.entries.length >= 1 ? "PASS" : "FAIL",
@@ -261,11 +288,11 @@ ELSE:
 
 | Category | Checks | Passed | Failed | Warnings |
 |----------|--------|--------|--------|----------|
-| Data Model | 3 | {n} | {n} | {n} |
+| Data Model | 4 | {n} | {n} | {n} |
 | Business Rules | 3 | {n} | {n} | {n} |
 | Use Cases & FRs | 4 | {n} | {n} | {n} |
 | Permissions | 3 | {n} | {n} | {n} |
-| UI & Navigation | 3 | {n} | {n} | {n} |
+| UI & Navigation | 4 | {n} | {n} | {n} |
 | I18N & Messages | 3 | {n} | {n} | {n} |
 | Seed Data | 2 | {n} | {n} | {n} |
 | API Endpoints | 2 | {n} | {n} | {n} |

package/templates/skills/business-analyse/steps/step-03a2-analysis.md

@@ -60,6 +60,20 @@ Define entities for this module (business attributes, not technical):
 > ```
 > **FORBIDDEN fields in attributes:** Do NOT use `type`, `values`, `rules`.
 > Use `description` to explain what the attribute is, `validation` for format/constraint rules, `unique` as boolean.
+>
+> **FORBIDDEN FORMAT — DO NOT USE (technical/database schema):**
+> ```json
+> {
+>   "name": "Project",
+>   "tableName": "rh_projects",
+>   "primaryKey": "id",
+>   "fields": [
+>     { "name": "code", "type": "UUID", "required": true }
+>   ]
+> }
+> ```
+> **Why forbidden:** `tableName`, `primaryKey` are technical fields that do NOT belong in analysis. `fields[]` is NOT recognized by the build pipeline — only `attributes[]` is. `type` with SQL types (UUID, string, timestamp) belongs in implementation, not analysis. Using this format causes **empty entity data in the HTML documentation** and **broken PRD extraction**.
+> The canonical format uses `attributes[]` (not `fields[]`), `relationships[]` (not FK inside fields), and NO technical fields (tableName, primaryKey).
 
 #### 6c. Process Flow
 
@@ -130,9 +144,13 @@ Before proceeding to step-03b-ui.md, VERIFY:
 
 1. **Module feature.json exists** at expected path (`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`)
 2. **Module feature.json has analysis section** with `entities[]` (at least 1) and `businessRules[]` (at least 1)
-3. **Module status in master** = "in-progress" (set by section 2 above)
-4. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
-5. **Sections identified** with clear roles and entities assigned
+3. **Entity schema compliance (BLOCKING)** — EVERY entity has `attributes[]` (NOT `fields[]`) and `relationships[]` arrays.
+   Quick check: `analysis.entities.every(e => Array.isArray(e.attributes) && e.attributes.length >= 1)`
+   IF any entity has `fields[]` instead of `attributes[]` → STRUCTURAL ERROR, fix before proceeding.
+   IF any entity has `tableName` or `primaryKey` → STRUCTURAL ERROR, these are technical fields that do not belong in analysis.
+4. **Module status in master** = "in-progress" (set by section 2 above)
+5. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
+6. **Sections identified** with clear roles and entities assigned
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03b-ui with incomplete data.
 

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -167,9 +167,36 @@ Example for a list section:
 Store in specification.uiWireframes[] (**MANDATORY** for every section):
 
 See [references/ui-resource-cards.md](../references/ui-resource-cards.md) for exact JSON format of `specification.uiWireframes[]`.
-**REQUIRED fields:** `screen`, `mockup`, `elements`, `section`, `componentMapping`, `layout` are ALL mandatory.
+**REQUIRED fields:** `screen`, `mockup`, `mockupFormat`, `elements`, `section`, `actions`, `componentMapping`, `layout`, `permissionsRequired` are ALL mandatory.
 A wireframe without `componentMapping` or `layout` will FAIL validation in step 9.
 
+> **STRUCTURE CARD: specification.uiWireframes[]** — ALL fields are MANDATORY. Do NOT omit any.
+> ```json
+> {
+>   "screen": "{module}-{section}",                // MANDATORY — unique screen ID (NOT "name" or "id")
+>   "section": "list|detail|create|approve|...",   // MANDATORY — section code
+>   "description": "Description en français",
+>   "mockupFormat": "ascii",                       // MANDATORY — "ascii" or "svg"
+>   "mockup": "┌───...┘",                         // MANDATORY — ASCII art string
+>   "elements": [                                  // MANDATORY — array of element objects
+>     { "id": "elem-grid", "type": "SmartTable", "label": "Grille" }
+>   ],
+>   "actions": [                                   // MANDATORY — user interactions
+>     { "trigger": "Click row", "action": "Navigate to detail" }
+>   ],
+>   "componentMapping": [                          // MANDATORY — array of mapping objects
+>     { "wireframeElement": "DataGrid", "reactComponent": "SmartTable" }
+>   ],
+>   "layout": {                                    // MANDATORY — object with regions (NOT a string)
+>     "type": "page",
+>     "regions": [{ "id": "main", "position": "main", "span": 12, "components": [...] }]
+>   },
+>   "permissionsRequired": ["read"]                // MANDATORY — required permissions
+> }
+> ```
+> **FORBIDDEN FORMAT:** wireframe with only `name` + `mockup` + `layout: "grid"` (string).
+> Every wireframe MUST have ALL fields above. Missing metadata causes empty frames in the HTML documentation.
+
 > **IF client rejects a mockup:** Revise and re-propose until validated. Do NOT proceed without client approval on the layout.
 
 ### 3b-bis. Wireframe-to-Component Mapping
@@ -250,6 +277,9 @@ Before proceeding to step-03c-compile.md, VERIFY:
 6. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
 7. **Form field completeness** — SmartForm fields[] covers ALL entity attributes except system/audit fields
 8. **Navigation entries for all sections** — Every section (including dashboard) has a corresponding entry in `specification.navigation.entries[]`
+9. **Wireframe structural compliance (BLOCKING)** — ALL wireframes have: `screen` (not just `name`), `section`, `mockupFormat`, `elements[]` (non-empty array of objects), `actions[]`, `componentMapping[]` (array of {wireframeElement, reactComponent}), `layout` (object with regions, NOT a string), `permissionsRequired[]`
+   Quick check: `uiWireframes.every(wf => wf.screen && wf.section && wf.mockupFormat && Array.isArray(wf.elements) && wf.elements.length > 0 && typeof wf.layout === 'object' && wf.layout !== null)`
+   IF any wireframe fails → FIX before proceeding. DO NOT load step-03c with degraded wireframes.
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03c-compile with incomplete data.
 

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

@@ -41,7 +41,9 @@ Validate the module specification for completeness and consistency, write to fea
 | functionalRequirements | 4 | PASS/FAIL |
 | permissionMatrix | 1 resource × 2 roles | PASS/FAIL |
 | entities | 1 | PASS/FAIL |
+| entitySchemaFormat | attributes[] not fields[] (BLOCKING) | PASS/FAIL |
 | wireframes | 1 per section (BLOCKING) | PASS/FAIL |
+| wireframeSchema | All required fields present (BLOCKING) | PASS/FAIL |
 | gherkinScenarios | 2 per UC | PASS/FAIL |
 | validations | 1 | PASS/FAIL |
 | messages | 4 | PASS/FAIL |
@@ -65,6 +67,8 @@ Validate the module specification for completeness and consistency, write to fea
 - BR-{CATEGORY}-NNN format
 - Entity names PascalCase
 - Field names camelCase
+- Entity attribute format: `attributes[]` with {name, description}, NOT `fields[]` with {name, type} — entities must NOT have tableName or primaryKey
+- Wireframe structure: `screen` (not `name`), `componentMapping` is array of {wireframeElement, reactComponent} (not plain key-value object), `layout` is object with regions (not string)
 - Permission paths dot-separated lowercase
 
 #### 9d. Decision
@@ -132,9 +136,9 @@ ba-writer.enrichSection({
 
 **Execute the comprehensive validation checklist:**
 
-Run the 25-check validation process across 10 categories:
-- Data Model (3 checks) | Business Rules (3 checks) | Use Cases & FRs (4 checks)
-- Permissions (3 checks) | UI & Navigation (3 checks) | I18N & Messages (3 checks)
+Run the 27-check validation process across 10 categories:
+- Data Model (4 checks) | Business Rules (3 checks) | Use Cases & FRs (4 checks)
+- Permissions (3 checks) | UI & Navigation (4 checks) | I18N & Messages (3 checks)
 - Seed Data (2 checks) | API Endpoints (2 checks) | Validations (1 check) | Gherkin (1 check)
 
 ```javascript

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

@@ -141,6 +141,13 @@ Rules:
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 
+**Tenant isolation (BLOCKING):**
+- ALL queries on tenant entities MUST include `.Where(x => x.TenantId == _currentUser.TenantId)`
+- ALL entity creation MUST pass `_currentUser.TenantId` as first parameter to `Entity.Create(tenantId, ...)`
+- NEVER use `new Entity { }` without `TenantId =` — always prefer factory method `Entity.Create()`
+- NEVER use `Guid.Empty` as a placeholder for userId, tenantId, or any business identifier
+- Service constructor MUST inject `ICurrentUserService _currentUser` to access TenantId
+
 **Lifecycle-aware services:**
 - Services operating on entities with a `lifeCycle` (status field) MUST validate entity state before mutations
 - Example: `if (entity.Status == EmployeeStatus.Terminated) throw new BusinessException("Cannot update terminated employee")`
@@ -158,6 +165,10 @@ Rules:
 - Empty DependencyInjection.cs with `// TODO` placeholder
 - CreateValidator without matching UpdateValidator
 - Validators not registered in DI container
+- Service query without TenantId filter (cross-tenant data leak)
+- `new Entity { }` without TenantId assignment
+- `Guid.Empty` as a business value in services or controllers
+- Entity.Create() without tenantId as first parameter
 
 ---
 

package/templates/skills/ralph-loop/references/core-seed-data.md

@@ -385,6 +385,52 @@ public class NavigationResourceSeedEntry
 
 ## 3. PermissionsSeedData.cs — MCP-First
 
+### CRITICAL: PermissionAction Safety Rules
+
+> **NEVER use `Enum.Parse<PermissionAction>("...")` — this causes runtime crashes if the string is invalid.**
+> The error only manifests at application startup, not at compile time.
+
+**Valid PermissionAction values (from SmartStack.Domain.Authorization):**
+
+| Enum Value | Int | Description |
+|------------|-----|-------------|
+| `PermissionAction.Access` | 0 | Wildcard permissions only (IsWildcard = true) |
+| `PermissionAction.Read` | 1 | GET/HEAD — View data |
+| `PermissionAction.Create` | 2 | POST — Create new records |
+| `PermissionAction.Update` | 3 | PUT/PATCH — Modify existing records |
+| `PermissionAction.Delete` | 4 | DELETE — Remove records |
+| `PermissionAction.Export` | 5 | Export data (CSV, Excel, etc.) |
+| `PermissionAction.Import` | 6 | Import data |
+| `PermissionAction.Approve` | 7 | Approve workflow items |
+| `PermissionAction.Reject` | 8 | Reject workflow items |
+| `PermissionAction.Assign` | 9 | Assign items to users |
+| `PermissionAction.Execute` | 10 | Execute actions (sync, run, etc.) |
+
+**Anti-patterns (FORBIDDEN):**
+
+```csharp
+// FORBIDDEN — Runtime crash if string is not a valid enum value
+Enum.Parse<PermissionAction>("Validate");          // ArgumentException at startup
+(PermissionAction)Enum.Parse(typeof(PermissionAction), "Validate"); // Same crash
+
+// FORBIDDEN — String-based action in anonymous objects
+new { Action = "read" };  // Not type-safe, silent mismatch possible
+```
+
+**Correct patterns (MANDATORY):**
+
+```csharp
+// ALWAYS use the typed enum directly — compile-time safe
+Action = PermissionAction.Read      // Compile-time checked
+Action = PermissionAction.Create    // Compile-time checked
+Action = PermissionAction.Approve   // Compile-time checked
+
+// For custom actions beyond standard CRUD, pick from the enum:
+// Export, Import, Approve, Reject, Assign, Execute
+```
+
+**MCP validation:** `validate_conventions` with `checks: ["permissions"]` will detect and flag these anti-patterns.
+
 ### Step A: Call MCP (PRIMARY)
 
 ```
@@ -932,6 +978,8 @@ Before marking the task as completed, verify ALL:
 - [ ] NavigationResources seeded (if `seedDataCore.navigationResources` present in feature.json)
 - [ ] Section/Resource translations created (4 languages each, EntityType = Section/Resource)
 - [ ] `dotnet build` passes after generation
+- [ ] NO `Enum.Parse<PermissionAction>` usage anywhere in seeding code (use typed enum directly)
+- [ ] ALL PermissionAction values are from the valid enum: Access, Read, Create, Update, Delete, Export, Import, Approve, Reject, Assign, Execute
 
 **If ANY check fails, the task status = 'failed'.**