@atlashub/smartstack-cli 4.17.1 → 4.19.0

package/templates/skills/{business-analyse → derive-prd}/references/handoff-mappings.md

@@ -1,95 +1,95 @@
-# Handoff Mappings: BR-to-Code & API Summary
-
-## Business Rules to Code Mapping
-
-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" }
-      ]
-    }
-  ]
-}
-```
-
-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
-
-## 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.
-
-```json
-{
-  "apiEndpointSummary": [
-    {
-      "operation": "ListOrders",
-      "method": "GET",
-      "route": "/api/orders",
-      "linkedUC": "UC-001",
-      "linkedFR": "FR-001",
-      "permissions": ["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/orders",
-      "linkedUC": "UC-002",
-      "linkedFR": "FR-002",
-      "permissions": ["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
-- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
-- **route**: Full API path from specification
-- **linkedUC/linkedFR**: Use case and feature requirement IDs
-- **permissions**: Array of exact permission paths
-- **requestSchema**: Input contract (query params or body)
-- **responseSchema**: Output contract
-- **errorCodes**: Expected HTTP error codes
-- **module**: Which module
+# Handoff Mappings: BR-to-Code & API Summary
+
+## Business Rules to Code Mapping
+
+Derive from module index.json `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" }
+      ]
+    }
+  ]
+}
+```
+
+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
+
+## Person Extension Mapping
+
+When an entity has `personRoleConfig` in its analysis data, it MUST be carried into the PRD:
+
+| Source (index.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 index.json `specification.apiEndpoints[]`. **NEVER** reinvent routes.
+
+```json
+{
+  "apiEndpointSummary": [
+    {
+      "operation": "ListOrders",
+      "method": "GET",
+      "route": "/api/orders",
+      "linkedUC": "UC-001",
+      "linkedFR": "FR-001",
+      "permissions": ["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/orders",
+      "linkedUC": "UC-002",
+      "linkedFR": "FR-002",
+      "permissions": ["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
+- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- **route**: Full API path from specification
+- **linkedUC/linkedFR**: Use case and feature requirement IDs
+- **permissions**: Array of exact permission paths
+- **requestSchema**: Input contract (query params or body)
+- **responseSchema**: Output contract
+- **errorCodes**: Expected HTTP error codes
+- **module**: Which module