@atlashub/smartstack-cli 3.5.0 → 3.6.0

package/templates/skills/business-analyse/steps/step-05a-handoff.md

@@ -1,8 +1,8 @@
 ---
 name: step-05a-handoff
-description: Build handoff data - file mapping, BR-to-code, API summary - write to feature.json
+description: Build the development handoff data - verify consolidation, choose implementation strategy, calculate complexity, and map specification to files (7 categories)
 model: sonnet
-next_step: steps/step-05b-deploy.md
+next_step: steps/step-05b-mapping.md
 ---
 
 > **Context files:** `_shared.md` | `_architecture.md`
@@ -21,7 +21,7 @@ next_step: steps/step-05b-deploy.md
 
 ## YOUR TASK
 
-Build the development handoff data (file mapping, BR-to-code, API summary) and write it to EACH module feature.json AND master feature.json. This step focuses on DATA — artifacts (prd.json, progress.txt, HTML) are generated in step-05b.
+Build the development handoff data: verify consolidation, choose implementation strategy, calculate complexity, and map specification to files (7 categories). BR-to-code mapping, API summary, and writing to feature.json are handled in step-05b.
 
 ---
 
@@ -122,6 +122,26 @@ Example:
 
 For **EACH module** in topological order:
 
+> **PATH HIERARCHY CONVENTION:** All backend file paths MUST include the context and application hierarchy.
+> Derive from module feature.json metadata:
+> - `{ContextPascal}` = PascalCase of `metadata.context` (e.g., `"business"` → `"Business"`)
+> - `{ApplicationName}` = `metadata.application` (e.g., `"HumanResources"`)
+> - `{ModuleName}` = `metadata.module` (e.g., `"Projects"`)
+>
+> **Controller context-to-folder mapping (`{ContextShort}`):**
+> | metadata.context | Controller Folder |
+> |-----------------|-------------------|
+> | `business` | `Business` |
+> | `platform` | `Admin` |
+> | `personal` | `User` |
+>
+> **Example** for context=business, application=HumanResources, module=Projects:
+> - Domain: `src/Domain/Entities/Business/HumanResources/Projects/Project.cs`
+> - Application: `src/Application/Services/Business/HumanResources/Projects/ProjectService.cs`
+> - Infrastructure: `src/Infrastructure/Persistence/Configurations/Business/HumanResources/Projects/ProjectConfiguration.cs`
+> - API: `src/API/Controllers/Business/HumanResources/ProjectsController.cs`
+> - Tests: `src/Tests/Unit/Domain/Business/HumanResources/Projects/ProjectTests.cs`
+
 #### 4.1 Domain Files
 
 From `analysis.entities[]` of the module:
@@ -129,7 +149,7 @@ From `analysis.entities[]` of the module:
 ```json
 "domain": [
   {
-    "path": "src/Domain/Entities/{ModuleName}/{EntityName}.cs",
+    "path": "src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}.cs",
     "type": "Entity",
     "linkedFRs": ["FR-001", "FR-002"],
     "linkedUCs": ["UC-001"],
@@ -139,9 +159,9 @@ From `analysis.entities[]` of the module:
 ```
 
 Include:
-- Value objects referenced by entities
-- Enums used in domain
-- Domain exceptions specific to module
+- Value objects referenced by entities (`src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{ValueObject}.cs`)
+- Enums used in domain (`src/Domain/Enums/{ContextPascal}/{ApplicationName}/{ModuleName}/{EnumName}.cs`)
+- Domain exceptions specific to module (`src/Domain/Exceptions/{ContextPascal}/{ApplicationName}/{ModuleName}/{ExceptionName}.cs`)
 
 #### 4.2 Application Files
 
@@ -150,20 +170,20 @@ From `analysis.useCases[]` of the module:
 ```json
 "application": [
   {
-    "path": "src/Application/Services/{ModuleName}/{ServiceName}Service.cs",
+    "path": "src/Application/Services/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}Service.cs",
     "type": "Service",
     "linkedFRs": ["FR-001"],
     "linkedUCs": ["UC-001", "UC-002"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Application/DTOs/{ModuleName}/{DtoName}Dto.cs",
+    "path": "src/Application/DTOs/{ContextPascal}/{ApplicationName}/{ModuleName}/{DtoName}Dto.cs",
     "type": "Dto",
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Application/Validators/{ModuleName}/{ValidatorName}Validator.cs",
+    "path": "src/Application/Validators/{ContextPascal}/{ApplicationName}/{ModuleName}/{ValidatorName}Validator.cs",
     "type": "Validator",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
@@ -184,24 +204,18 @@ From `analysis.entities[]` of the module:
 ```json
 "infrastructure": [
   {
-    "path": "src/Infrastructure/Repositories/{ModuleName}/{EntityName}Repository.cs",
-    "type": "Repository",
+    "path": "src/Infrastructure/Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}Configuration.cs",
+    "type": "EFConfiguration",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/{ModuleName}DbContext.cs",
-    "type": "DbContext",
-    "linkedFRs": ["FR-001", "FR-002"],
-    "module": "{moduleCode}"
   }
 ]
 ```
 
 Include:
-- Repository per entity
-- DbContext configuration (if module-specific)
-- Unit of Work pattern if applicable
+- EF Core configuration per entity (`Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/`)
+- DbSet registration in `IExtensionsDbContext` / `ExtensionsDbContext`
+- DI registration in `DependencyInjection.cs`
 - Specifications if complex queries
 
 #### 4.4 API Files
@@ -211,7 +225,7 @@ From `specification.apiEndpoints[]` of the module:
 ```json
 "api": [
   {
-    "path": "src/API/Controllers/{ModuleName}Controller.cs",
+    "path": "src/API/Controllers/{ContextShort}/{ApplicationName}/{EntityName}Controller.cs",
     "type": "ApiController",
     "linkedUCs": ["UC-001", "UC-002"],
     "linkedFRs": ["FR-001"],
@@ -220,6 +234,8 @@ From `specification.apiEndpoints[]` of the module:
 ]
 ```
 
+> **Context-to-folder mapping (`{ContextShort}`):** `business` → `Business`, `platform` → `Admin`, `personal` → `User`
+
 Include:
 - One controller per domain aggregate root (or logical grouping)
 - Include all HTTP methods (GET, POST, PUT, DELETE, PATCH)
@@ -415,26 +431,26 @@ Business categories (from specification.seedDataBusiness):
 ```json
 "tests": [
   {
-    "path": "src/Tests/Unit/Domain/{ModuleName}/{Entity}Tests.cs",
+    "path": "src/Tests/Unit/Domain/{ContextPascal}/{ApplicationName}/{ModuleName}/{Entity}Tests.cs",
     "type": "UnitTests",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Unit/Application/{ModuleName}/{ServiceName}ServiceTests.cs",
+    "path": "src/Tests/Unit/Application/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}ServiceTests.cs",
     "type": "UnitTests",
     "linkedFRs": ["FR-001"],
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Integration/{ModuleName}/{ApiControllerName}ControllerTests.cs",
+    "path": "src/Tests/Integration/{ContextPascal}/{ApplicationName}/{ModuleName}/{ApiControllerName}ControllerTests.cs",
     "type": "IntegrationTests",
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Security/{ModuleName}/{ModuleName}SecurityTests.cs",
+    "path": "src/Tests/Security/{ContextPascal}/{ApplicationName}/{ModuleName}/{ModuleName}SecurityTests.cs",
     "type": "SecurityTests",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
@@ -451,277 +467,18 @@ Test files:
 
 ---
 
-### 5. Map Business Rules to Code
-
-Derive from `analysis.businessRules[]` of **EACH module**.
-
-Generate complete mapping for each BR:
-
-```json
-{
-  "brToCodeMapping": [
-    {
-      "ruleId": "BR-VAL-001",
-      "title": "Order total must equal sum of item prices",
-      "module": "{moduleCode}",
-      "severity": "critical",
-      "implementationPoints": [
-        {
-          "layer": "Domain",
-          "component": "Order.cs",
-          "method": "CalculateTotal()",
-          "implementation": "Validate sum equals sum of OrderItems.Price"
-        },
-        {
-          "layer": "Application",
-          "component": "CreateOrderService.cs",
-          "method": "Handle()",
-          "implementation": "Calculate total before persisting"
-        },
-        {
-          "layer": "API",
-          "component": "OrdersController.cs",
-          "method": "CreateOrder()",
-          "implementation": "Return validation error if total mismatch"
-        },
-        {
-          "layer": "Frontend",
-          "component": "OrderForm.tsx",
-          "method": "calculateTotal()",
-          "implementation": "Real-time calculation on item change"
-        }
-      ]
-    },
-    {
-      "ruleId": "BR-SEC-002",
-      "title": "User can only view orders from their tenant",
-      "module": "{moduleCode}",
-      "severity": "critical",
-      "implementationPoints": [
-        {
-          "layer": "Domain",
-          "component": "Order.cs",
-          "method": "Validate()",
-          "implementation": "Check TenantId matches user context"
-        },
-        {
-          "layer": "Infrastructure",
-          "component": "OrderRepository.cs",
-          "method": "GetUserOrders()",
-          "implementation": "Filter by TenantId in WHERE clause"
-        },
-        {
-          "layer": "API",
-          "component": "OrdersController.cs",
-          "method": "GetOrders()",
-          "implementation": "Enforce permission check + tenant filter"
-        }
-      ]
-    }
-  ]
-}
-```
-
-For each BR include:
-- **ruleId**: Reference to analysis.businessRules[].id
-- **title**: The rule statement
-- **module**: Which module it belongs to
-- **severity**: "critical", "high", "medium", "low"
-- **implementationPoints**: Array of {layer, component, method, implementation}
-
-Layers: Domain, Application, Infrastructure, API, Frontend
-
----
-
-### 6. API Endpoint Summary
-
-> **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.
-
-Generate summary with full details:
-
-```json
-{
-  "apiEndpointSummary": [
-    {
-      "operation": "ListOrders",
-      "method": "GET",
-      "route": "/api/business/orders",
-      "linkedUC": "UC-001",
-      "linkedFR": "FR-001",
-      "permissions": ["business.orders.read"],
-      "requestSchema": { "type": "query", "params": ["pageNumber", "pageSize", "status"] },
-      "responseSchema": { "type": "PaginatedOrderDto[]" },
-      "errorCodes": [401, 403, 400, 500],
-      "module": "{moduleCode}"
-    },
-    {
-      "operation": "CreateOrder",
-      "method": "POST",
-      "route": "/api/business/orders",
-      "linkedUC": "UC-002",
-      "linkedFR": "FR-002",
-      "permissions": ["business.orders.create"],
-      "requestSchema": { "type": "body", "schema": "CreateOrderDto" },
-      "responseSchema": { "type": "OrderDto" },
-      "errorCodes": [400, 401, 403, 422, 500],
-      "module": "{moduleCode}"
-    }
-  ]
-}
-```
-
-For each endpoint:
-- **operation**: Use case name or operation name
-- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
-- **route**: Full API path from specification
-- **linkedUC**: Use case ID(s) this endpoint implements
-- **linkedFR**: Feature requirement ID(s)
-- **permissions**: Array of exact permission paths
-- **requestSchema**: Input contract (query params or body)
-- **responseSchema**: Output contract
-- **errorCodes**: Expected HTTP error codes
-- **module**: Which module
-
-Total endpoints = count of specification.apiEndpoints[] across all modules.
-
----
-
-### 7. Write Handoff to Feature.json
-
-> **BLOCKING RULE: The handoff MUST be written in EACH module feature.json.**
-> A handoff at master level alone is INSUFFICIENT. Ralph-loop consumes module-level handoffs.
-> An empty module handoff (`"handoff": {}`) is a CRITICAL BUG that blocks all downstream generation.
-
-#### 7a. Module Handoff Loop (MANDATORY)
-
-> **STRUCTURE CARD: handoff** — Field names are EXACT. Include ALL fields below.
-> ```json
-> {
->   "complexity": "simple|medium|complex",
->   "filesToCreate": {
->     "domain": [{"path": "...", "type": "Entity|ValueObject|Enum", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
->     "application": [{"path": "...", "type": "Service|Dto|Validator", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
->     "infrastructure": [{"path": "...", "type": "Repository|DbContext", "linkedFRs": [], "module": "..."}],
->     "api": [{"path": "...", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "..."}],
->     "frontend": [{"path": "...", "type": "Page|Component|Hook|DashboardPage", "linkedUCs": [], "linkedWireframes": [], "module": "..."}],
->     "seedData": [{"path": "...", "type": "HasData", "category": "core|business", "source": "...", "module": "..."}],
->     "tests": [{"path": "...", "type": "UnitTests|IntegrationTests|SecurityTests", "linkedFRs": [], "linkedUCs": [], "module": "..."}]
->   },
->   "brToCodeMapping": [{"ruleId": "BR-...", "files": ["path1", "path2"], "implementation": "description"}],
->   "apiEndpointSummary": [{"method": "GET|POST|PUT|DELETE", "path": "/api/...", "permission": "business.{app}.{module}.{action}", "linkedUC": "UC-..."}],
->   "prdFile": ".ralph/prd-{module}.json",
->   "totalFiles": 0,
->   "totalTasks": 0,
->   "handedOffAt": "{ISO timestamp}"
-> }
-> ```
-> **MANDATORY fields:** ALL of the above. `filesToCreate` MUST have all 7 categories (even if empty arrays).
-> **FORBIDDEN:** `handoff: {}` (empty object is a CRITICAL BUG). Missing `brToCodeMapping` or `apiEndpointSummary`.
-
-**For i = 0; i < modules.length; i++:**
-
-```
-1. moduleCode = modules[i].code
-2. moduleFeatureId = modules[i].featureJsonPath or find via ba-reader.findFeature()
-3. Read the module feature.json via ba-reader.findFeature(moduleFeatureId)
-4. Build the handoff payload for THIS module:
-   - complexity (from step 3 calculation)
-   - filesToCreate (full 7-category structure from step 4, filtered for this module)
-   - brToCodeMapping (from step 5, filtered for this module)
-   - apiEndpointSummary (from step 6, filtered for this module)
-   - prdFile path
-   - totalFiles count
-   - totalTasks count
-   - handedOffAt timestamp
-
-5. Write via ba-writer:
-   ba-writer.enrichModuleHandoff({
-     moduleFeatureId: {moduleFeatureId},
-     handoffData: {
-       complexity: "{simple|medium|complex}",
-       filesToCreate: {...},
-       brToCodeMapping: [...],
-       apiEndpointSummary: [...],
-       prdFile: ".ralph/prd-{moduleCode}.json",
-       totalFiles: {count},
-       totalTasks: {count},
-       handedOffAt: "{ISO timestamp}"
-     }
-   })
-
-6. VERIFICATION (MANDATORY - done automatically by enrichModuleHandoff):
-   - handoff !== {}
-   - handoff.filesToCreate has 7 categories
-   - handoff.brToCodeMapping.length > 0
-   IF verification fails → STOP, report error, do NOT continue
-
-7. Display progress:
-   "✓ Handoff module {i+1}/{N} : {moduleCode} ({fileCount} fichiers, {brCount} BRs mappées)"
-```
-
-#### 7b. Master Handoff (after ALL modules written successfully)
-
-```
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "handoff",
-  data: {
-    status: "handed-off",
-    complexity: "{simple|medium|complex}",
-    implementationStrategy: "{strategy}",
-    moduleCount: {count},
-    moduleOrder: [...],
-    totalFilesToCreate: {sum across all modules},
-    totalTasks: {sum across all modules},
-    prdStructure: "per-module | consolidated",
-    prdFiles: [
-      { module: "{module1}", path: ".ralph/prd-{module1}.json" },
-      { module: "{module2}", path: ".ralph/prd-{module2}.json" }
-    ],
-    progressTrackerPath: ".ralph/progress.txt",
-    handedOffAt: "{ISO timestamp}"
-  }
-})
-```
-
-#### 7c. Final Verification (BLOCKING)
-
-```
-count = 0
-FOR each module in modules[]:
-  Read module feature.json
-  IF module.handoff !== {} AND module.status === "handed-off":
-    count++
-
-IF count < modules.length:
-  → BLOCKING ERROR: {modules.length - count} modules missing handoff
-  → List the missing modules by name
-  → DO NOT proceed to step 10
-  → Return to 9a for missing modules only
-
-IF count === modules.length:
-  ba-writer.updateStatus({feature_id}, "handed-off")
-  Display: "✓ Handoff complet: {count}/{modules.length} modules avec handoff valide"
-```
-
-Status journey: analyze → consolidate → **handed-off**
-
----
-
-## SELF-VERIFICATION (MANDATORY before loading step-05b)
+## SELF-VERIFICATION (MANDATORY before loading step-05b-mapping)
 
-Before proceeding to step-05b-deploy.md, VERIFY:
+Before proceeding to step-05b-mapping.md, VERIFY:
 
-1. **ALL module feature.json** have `handoff` section with 7 categories in `filesToCreate` (domain, application, infrastructure, api, frontend, seedData, tests)
-2. **ALL module feature.json** have `handoff.brToCodeMapping.length > 0`
-3. **ALL module feature.json** status = "handed-off"
-4. **Master feature.json** has `handoff` section with implementationStrategy, moduleOrder, totalFilesToCreate
-5. **Master status** = "handed-off"
+- **filesToCreate** has all 7 categories populated (domain, application, infrastructure, api, frontend, seedData, tests) for each module
+- **Complexity** calculated for all modules using the matrix from section 3
+- **Implementation strategy** chosen (for multi-module features)
 
-**IF any check fails → FIX before proceeding.** Do NOT generate artifacts (prd.json, progress.txt) without complete handoff data.
+**IF any check fails → FIX before proceeding.** The mapping and write operations in step-05b depend on complete handoff data structure.
 
 ---
 
 ## NEXT STEP
 
-Load: `steps/step-05b-deploy.md`
+Load: `steps/step-05b-mapping.md`