@atlashub/smartstack-cli 3.46.0 → 3.47.0

package/templates/skills/apex/references/smartstack-api.md

@@ -229,6 +229,72 @@ public class {Name} : BaseEntity, IScopedTenantEntity, IAuditableEntity
 }
 ```
 
+### Entity Pattern — Person Extension (User-linked roles)
+
+For entities representing a "person role" of a User (Employee, Customer, Contact). Avoids duplicating User personal data.
+
+> **Full reference:** See `references/person-extension-pattern.md` for complete entity, config, service, DTO, and frontend patterns.
+
+**Two variants:**
+
+| Variant | UserId | Use case |
+|---------|--------|----------|
+| **Mandatory** | `Guid UserId` | Employee, Manager — always a User |
+| **Optional** | `Guid? UserId` | Customer, Contact — may or may not have account |
+
+**Mandatory variant (entity):**
+```csharp
+public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    public Guid TenantId { get; private set; }
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Person Extension — mandatory UserId
+    public Guid UserId { get; private set; }
+    public User? User { get; private set; }
+
+    // Business properties ONLY — ZERO person fields (FirstName, LastName, Email come from User)
+    public string Code { get; private set; } = null!;
+    public DateOnly HireDate { get; private set; }
+}
+```
+
+**Optional variant (entity):**
+```csharp
+public class Customer : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    public Guid TenantId { get; private set; }
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Person Extension — optional UserId
+    public Guid? UserId { get; private set; }
+    public User? User { get; private set; }
+
+    // Person fields (standalone when no User linked)
+    public string FirstName { get; private set; } = null!;
+    public string LastName { get; private set; } = null!;
+    public string? Email { get; private set; }
+
+    // Computed — resolve from User if linked, else own fields
+    public string DisplayFirstName => User?.FirstName ?? FirstName;
+    public string DisplayLastName => User?.LastName ?? LastName;
+    public string? DisplayEmail => User?.Email ?? Email;
+}
+```
+
+**EF Config (mandatory):** `builder.HasIndex(e => new { e.TenantId, e.UserId }).IsUnique();`
+**EF Config (optional):** `builder.HasIndex(e => new { e.TenantId, e.UserId }).IsUnique().HasFilter("[UserId] IS NOT NULL");`
+
+**Service rules (both):** `Include(x => x.User)` on all queries. Inject `ICoreDbContext` for User reads. CreateAsync verifies User exists + no duplicate `(TenantId, UserId)`.
+
+**DTO rules:** Mandatory CreateDto has `Guid UserId` + business fields only. Optional CreateDto has `Guid? UserId` + person fields. ResponseDto (both) includes `Display*` fields.
+
+**FORBIDDEN (mandatory variant):** `FirstName`, `LastName`, `Email`, `PhoneNumber` properties in entity — these come from User.
+
+---
+
 ### MCP tenantMode Parameter
 
 When calling `scaffold_extension`, use the `tenantMode` parameter:
@@ -738,6 +804,9 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `IEmployeeService.cs` in Infrastructure | Interface belongs in Application — move to `Application/Interfaces/` |
 | Service implementation in Application layer | Implementations belong in Infrastructure — Application only contains interfaces |
 | Controller injects `IRepository<T>` directly | Controllers use Application services, not repositories — add a service layer |
+| `FirstName`/`LastName`/`Email` on mandatory person extension entity | These come from User — use `Display*` computed properties from the User join |
+| Missing `Include(x => x.User)` on person extension service | Person extension entities MUST always include User for display fields |
+| Missing unique index on `(TenantId, UserId)` for person extension | One person-role per User per Tenant — add unique constraint in EF config |
 
 ---
 

package/templates/skills/apex/references/smartstack-layers.md

@@ -59,6 +59,11 @@ Web            → Application (via API clients)
 - No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
 - Domain events for state changes
 - Value objects for composite values
+- **Person Extension Pattern:** If entity has `personRoleConfig` (from PRD or feature.json):
+  - Load `references/person-extension-pattern.md` for full patterns
+  - **Mandatory** (`userLinkMode: 'mandatory'`): `Guid UserId` (non-nullable), ZERO person fields (`FirstName`, `LastName`, `Email`), unique index `(TenantId, UserId)`
+  - **Optional** (`userLinkMode: 'optional'`): `Guid? UserId` (nullable), own person fields + computed `Display*` properties, filtered unique index `(TenantId, UserId) WHERE UserId IS NOT NULL`
+  - EF Config: `builder.Ignore()` on computed `Display*` properties (optional variant only)
 
 ---
 
@@ -119,6 +124,13 @@ Web            → Application (via API clients)
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 - **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
+- **Person Extension services:** If entity has `personRoleConfig`:
+  - `Include(x => x.User)` on ALL queries (mandatory)
+  - Inject `ICoreDbContext` for User existence checks
+  - Mandatory: search on `User.FirstName`, `User.LastName`, `User.Email`
+  - Optional: search fallback `User.FirstName ?? x.FirstName`
+  - CreateAsync: verify User exists + no duplicate `(TenantId, UserId)`
+  - ResponseDto: include `Display*` fields resolved from User join
 
 ---
 
@@ -151,6 +163,7 @@ Web            → Application (via API clients)
 - NEVER use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities
+- **Person Extension DTOs:** ResponseDto MUST include `Display*` fields (`DisplayFirstName`, `DisplayLastName`, `DisplayEmail`) resolved from User join. Mandatory CreateDto: `Guid UserId` only. Optional CreateDto: `Guid? UserId` + person fields.
 
 ---
 

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

@@ -75,6 +75,13 @@ IF delegate_mode:
   Extract entities from domain tasks:
     {entities} = prd.tasks.filter(t => t.category == 'domain').map(t => entity name from t.description)
 
+  Extract code patterns from feature.json (if available):
+    IF {feature_path} exists:
+      Read feature.json → for each entity with codePattern defined:
+        {code_patterns}[] += { entity, strategy, prefix, digits, includeTenantSlug, separator }
+    ELSE:
+      {code_patterns} = []  # will use heuristic fallback in analysis-methods.md
+
   Extract complexity:
     {module_complexity} = heuristic from task count:
       <= 10 tasks → "simple-crud"
@@ -133,7 +140,7 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 > **Reference:** Load `references/challenge-questions.md` for hierarchy rules and challenge questions:
 > - 4-level hierarchy structure (Application → Module → Section → Resource)
-> - Challenge questions (4a: Application, 4b: Module, 4c: Sections, 5a: Entities, 5b: Dependencies)
+> - Challenge questions (4a: Application, 4b: Module, 4c: Sections, 5a: Entities, 5b: Dependencies, 5c: Code Generation)
 > - Validation rules (sections MUST have at least one entry)
 > - Storage format for each level
 > - Delegate mode skip (if -d)
@@ -169,23 +176,37 @@ Load and execute entity questions from `references/challenge-questions.md` secti
 
 Load and execute dependency questions from `references/challenge-questions.md` section 5b.
 
-### 5c. Store Responses
+### 5c. Code Generation Strategy
+
+Load and execute code generation questions from `references/challenge-questions.md` section 5c.
+
+**Skip if:**
+- `delegate_mode` is true (PRD defines code patterns)
+- `foundation_mode` is true (code strategy comes later)
+- `feature.json` exists AND all entities in `{entities}` have `codePattern` defined
+
+**If feature.json covers SOME but not all entities:**
+→ Only ask for entities without `codePattern` in feature.json
+→ Merge feature.json patterns + user answers into `{code_patterns}`
+
+### 5d. Store Responses
 
 ```yaml
 {entities}: string[]            # Main entities to manage
 {module_complexity}: string     # "simple-crud" | "crud-rules" | "crud-workflow" | "complex"
 {has_dependencies}: string      # "none" | "references" | "unknown"
 {key_properties}: string[]      # Key business properties mentioned by user
+{code_patterns}: object[]       # Per-entity code generation config (from 5c or feature.json)
 ```
 
 These values are propagated to:
-- **step-01 (Analyze):** Guide code exploration focus
+- **step-01 (Analyze):** Guide code exploration focus + code pattern detection (uses `{code_patterns}` as Priority 1)
 - **step-02 (Plan):** Inform layer mapping (e.g., workflow → needs /workflow skill)
-- **step-03 (Execute):** Entity scaffolding with correct properties and relationships
+- **step-03 (Execute):** Entity scaffolding with correct properties, relationships, and code generation strategy
 
 ---
 
-## 5d. Scope Complexity Guard (BLOCKING)
+## 5e. Scope Complexity Guard (BLOCKING)
 
 > **Root cause (test-apex-007):** `/apex` was invoked with 3 applications and 7 entities.
 > The model's context window saturated, causing: incomplete migrations, lost conventions,
@@ -295,6 +316,7 @@ APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
 Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
+Code: {code_patterns summary — e.g., "Employee:sequential(emp), Contract:year-seq(ctr)" or "all manual" or "none"}
 PRD: {prd_path||none} | Feature: {feature_path||none} | Flags: {active_flags}
 MCP: {available|degraded} | Needs: migration/seed/workflow/notification = {yes|no}
 NEXT STEP: step-01-analyze

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

@@ -55,6 +55,19 @@ For each entity to create/modify:
   → Verify entity matches patterns in references/smartstack-api.md
 ```
 
+### Person Extension Detection
+
+```
+IF entity has personRoleConfig (from PRD or feature.json):
+  → LOAD references/person-extension-pattern.md
+  → Apply variant: mandatory or optional (from personRoleConfig.userLinkMode)
+  → scaffold_extension with options: { isPersonRole: true, userLinkMode: '{variant}' }
+  → VERIFY: UserId FK present, no duplicate person fields (mandatory)
+  → VERIFY: EF config has unique index on (TenantId, UserId)
+  → VERIFY (mandatory): entity has ZERO person fields (FirstName, LastName, Email, PhoneNumber)
+  → VERIFY (optional): entity has own person fields + computed Display* properties
+```
+
 ### EF Core Configurations
 
 ```

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

@@ -26,6 +26,7 @@
 | `SystemEntity` | - | `Id` (Guid), `CreatedAt` (pas de TenantId) | Entites systeme (navigation, permissions) |
 | `BaseEntity` | `ISoftDeletable` | + `IsDeleted`, `DeletedBy`, `DeletedAt` | Entite avec suppression logique |
 | `HierarchicalEntity` | - | + `ParentId`, `Level`, `Path` | Arborescences (categories, menus) |
+| `BaseEntity + UserId FK` | `ITenantEntity` | + `UserId` (Guid FK to User) | Person Role Extension — entity represents a person linked to User. Use `isPersonRole: true` in scaffold_extension. |
 
 > **IMPORTANT :** Ne JAMAIS proposer `CreatedBy`, `UpdatedBy`, `IsDeleted`, `TenantId` comme champs explicites — ils sont AUTOMATIQUES via la classe de base ou l'interface.
 

package/templates/skills/business-analyse/references/entity-architecture-decision.md

@@ -6,6 +6,28 @@
 
 ---
 
+## 0. Pre-check: Person Extension
+
+**BEFORE** running the entity architecture scoring, check if this entity represents a person role.
+
+### Detection criteria:
+1. **Name match**: Entity name is in the known person role list (Employee, Customer, Manager, Supplier, etc.)
+2. **Attribute match**: Entity has 3+ attributes among (firstName, lastName, email, phoneNumber, department, jobTitle, address)
+
+### If detected:
+→ Recommend **Person Extension Pattern** (link to User via UserId FK)
+→ Ask user to confirm variant: mandatory (always a User) or optional (may or may not have a User)
+→ Store `personRoleConfig` in entity structure card
+→ **Skip standard entity architecture scoring** for person-specific fields (they come from User)
+
+### Known person role names:
+| Variant | Entity names |
+|---------|-------------|
+| **Mandatory** (always a User) | Employee, Manager, Instructor, Teacher, Trainer, Technician |
+| **Optional** (may have a User) | Customer, Client, Supplier, Vendor, Patient, Student, Member, Participant, Candidate, Applicant, Contact, Lead, Prospect, Volunteer, Contractor, Freelancer, Consultant |
+
+---
+
 ## 1. Entity Scoring Grid (5 criteria, 0-3 each)
 
 For EACH referenced entity detected during approfondissement, score silently:

package/templates/skills/business-analyse/references/handoff-mappings.md

@@ -34,6 +34,20 @@ For each BR include:
 
 Layers: Domain, Application, Infrastructure, API, Frontend
 
+## Person Extension Mapping
+
+When an entity has `personRoleConfig` in its analysis data, it MUST be carried into the PRD:
+
+| Source (feature.json) | Target (PRD) |
+|----------------------|--------------|
+| `analysis.entities[].personRoleConfig` | `modules[].entities[].personRoleConfig` |
+| `personRoleConfig.userLinkMode` | Determines scaffold options: `isPersonRole: true, userLinkMode: "{mode}"` |
+| `personRoleConfig.inheritedFields` | Fields to exclude from entity (mandatory) or mark as fallback (optional) |
+
+The `personRoleConfig` object is passed through verbatim to ensure `/apex` and `/ralph-loop` receive the person extension configuration.
+
+---
+
 ## API Endpoint Summary
 
 > **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.

package/templates/skills/business-analyse/references/spec-auto-inference.md

@@ -24,6 +24,7 @@
 | string (multiline) | TextArea | entity.required | rows: 4 |
 | enum | Select | entity.required | source: enum name |
 | FK:Entity | EntityLookup | entity.required | source: target entity, searchable. Component: `@/components/ui/EntityLookup`. NEVER plain text input for FK Guid fields. Backend API MUST support `?search=` param. See `smartstack-frontend.md` section 6. |
+| FK:User (person role) | `EntityLookup` | entity.required | searchable dropdown searching Users by name + email. `<EntityLookup apiEndpoint="/api/administration/users" mapOption={(user) => ({id: user.id, label: `${user.firstName} ${user.lastName}`, sublabel: user.email})} />` |
 | decimal | NumberInput | entity.required | — |
 | int | NumberInput | entity.required | — |
 | datetime | DatePicker | entity.required | — |

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

@@ -143,6 +143,55 @@ If team agent: use heuristic defaults autonomously.
 
 **Reference:** See `apex/references/code-generation.md` for full ICodeGenerator<T> implementation details, DI registration patterns, and backend service integration.
 
+#### 6b-ter. Person Role Detection
+
+> **CRITICAL: Detect entities representing person roles to avoid duplicating User data.**
+> SmartStack User entity already contains: FirstName, LastName, Email, DisplayName, DepartmentId, JobTitleId, PhoneNumber, etc.
+> Entities that represent person roles MUST be linked to User via the Person Extension Pattern.
+
+**Step 1 — Name-based detection:**
+
+Known person role names (mandatory User link):
+- Employee, Manager, Instructor, Teacher, Trainer, Technician
+
+Known person role names (optional User link):
+- Customer, Client, Supplier, Vendor, Patient, Student, Member, Participant, Candidate, Applicant, Contact, Lead, Prospect, Volunteer, Contractor, Freelancer, Consultant
+
+**Step 2 — Attribute-based detection:**
+
+If an entity has 3+ attributes among: firstName, lastName, email, phoneNumber, department, jobTitle, address → flag as potential person role.
+
+**Step 3 — Interactive confirmation:**
+
+IF entity name matches a known person role OR attribute detection triggers:
+
+Use `AskUserQuestion` with 3 options:
+1. "User link mandatory (Recommended)" — the entity is ALWAYS a system User (Employee, Manager)
+2. "User link optional" — the entity MAY have a system account (Customer with portal)
+3. "Independent entity" — no User link (rare: only if the person will NEVER log in)
+
+**Step 4 — Apply Person Extension config:**
+
+IF option 1 or 2 selected:
+- Store `personRoleConfig` in the entity's structure card
+- For mandatory mode: REMOVE attributes that duplicate User (firstName, lastName, email, displayName, department, jobTitle, phoneNumber) from entity attributes
+- For optional mode: KEEP person attributes but mark as "fallback when no User linked"
+
+> **STRUCTURE CARD: analysis.entities[].personRoleConfig**
+> ```json
+> {
+>   "personRoleConfig": {
+>     "linkedEntity": "User",
+>     "fkField": "UserId",
+>     "userLinkMode": "mandatory|optional",
+>     "inheritedFields": ["FirstName", "LastName", "Email", "DisplayName",
+>                         "Department", "JobTitle", "PhoneNumber"]
+>   }
+> }
+> ```
+
+IF option 3 selected: do not add personRoleConfig (entity stays independent).
+
 #### 6c. Process Flow
 
 Define the main business process flow for this module (not lifecycle — that's in 8j):

package/templates/skills/gitflow/_shared.md

@@ -236,7 +236,7 @@ read_gitflow_config() {
   GF_RELEASE_PREFIX=${GF_RELEASE_PREFIX:-release/}
   GF_HOTFIX_PREFIX=${GF_HOTFIX_PREFIX:-hotfix/}
   GF_TAG_PREFIX=${GF_TAG_PREFIX:-v}
-  GF_VERSION=${GF_VERSION:-0.1.0}
+  GF_VERSION=${GF_VERSION:-0.0.0}
 
   # Translate all stored paths to current platform format
   # This ensures WSL paths are /mnt/d/... and Windows paths use forward slashes
@@ -551,7 +551,7 @@ GitFlow configuration JSON template v2.1.0 (aligned with `templates/config.json`
   },
   "versioning": {
     "strategy": "semver",
-    "current": "0.1.0",
+    "current": "0.0.0",
     "tagPrefix": "v",
     "sources": ["csproj", "package.json", "VERSION"]
   },

package/templates/skills/gitflow/references/init-version-detection.md

@@ -13,7 +13,7 @@ VERSION=$(grep -oP '<Version>\K[^<]+' "$DEVELOP_FULL_PATH"/*.csproj 2>/dev/null
 [ -z "$VERSION" ] && VERSION=$(grep -oP '"version":\s*"\K[^"]+' "$DEVELOP_FULL_PATH/package.json" 2>/dev/null)
 [ -z "$VERSION" ] && VERSION=$(cat "$DEVELOP_FULL_PATH/VERSION" 2>/dev/null)
 [ -z "$VERSION" ] && VERSION=$(git -C "$DEVELOP_FULL_PATH" describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
-[ -z "$VERSION" ] && VERSION="0.1.0"
+[ -z "$VERSION" ] && VERSION="0.0.0"
 ```
 
 ## Version will be stored in config.json

package/templates/skills/gitflow/steps/step-init.md

@@ -77,9 +77,20 @@ See [references/init-structure-creation.md](../references/init-structure-creatio
 - Worktree creation (organized and simple modes)
 - GitFlow config directory creation
 
-### 9. Create Configuration
+### 9. Detect Version
 
-**Write `.claude/gitflow/config.json` in develop worktree.**
+**⛔ MUST run BEFORE creating config.json (step 10) — the detected `{VERSION}` is needed in the config template.**
+
+See [references/init-version-detection.md](../references/init-version-detection.md) for:
+- Version detection with priority (csproj, package.json, tags, etc.)
+- Platform-agnostic path handling
+- Fallback: `0.0.0` if no version source found
+
+**⛔ WARNING:** Do NOT confuse the config schema version (`"version": "2.1.0"` at line 1 of config.json) with the project version (`"versioning.current": "{VERSION}"`). They are completely different values.
+
+### 10. Create Configuration
+
+**Write `.claude/gitflow/config.json` in develop worktree using the `{VERSION}` detected in step 9.**
 
 See [references/init-config-template.md](../references/init-config-template.md) for:
 - Full config.json v2.1.0 template (platform, workspace, repository, git, worktrees, versioning, efcore, workflow, language)
@@ -87,12 +98,6 @@ See [references/init-config-template.md](../references/init-config-template.md)
 
 **⛔ IMPORTANT:** Store paths using Windows-style format (`D:/path/to/folder`). The `read_gitflow_config()` in `_shared.md` translates to platform format at read time.
 
-### 10. Detect Version
-
-See [references/init-version-detection.md](../references/init-version-detection.md) for:
-- Version detection with priority (csproj, package.json, tags, etc.)
-- Platform-agnostic path handling
-
 ### 10b. Post-Init Validation
 
 **⛔ MANDATORY: Verify the structure was created correctly.**

package/templates/skills/gitflow/templates/config.json

@@ -47,7 +47,7 @@
   },
   "versioning": {
     "strategy": "semver",
-    "current": "0.1.0",
+    "current": "0.0.0",
     "tagPrefix": "v",
     "sources": ["csproj", "package.json", "VERSION"]
   },

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

@@ -35,6 +35,19 @@ Tasks MUST be executed in this order. Each category depends on the previous ones
 
 ---
 
+## Person Role Entities
+
+Entities with `personRoleConfig` (Person Extension Pattern) have a special architectural requirement:
+
+- **ICoreDbContext access required**: Person Extension entities need to read User data from the core schema
+- This is an **exception** to the normal pattern where extension entities only use `IExtensionsDbContext`
+- Service must inject BOTH `IExtensionsDbContext` (for the entity) AND `ICoreDbContext` (for User reads)
+- Service must `Include(x => x.User)` on all queries
+- For mandatory mode: search on `User.FirstName`, `User.LastName`, `User.Email`
+- For optional mode: search with fallback (`User?.FirstName ?? x.FirstName`)
+
+---
+
 ## Batch Grouping Rules
 
 When selecting tasks for a batch: