@atlashub/smartstack-cli 3.1.0 → 3.3.0

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

@@ -0,0 +1,727 @@
+---
+name: step-05a-handoff
+description: Build handoff data - file mapping, BR-to-code, API summary - write to feature.json
+model: sonnet
+next_step: steps/step-05b-deploy.md
+---
+
+> **Context files:** `_shared.md` | `_architecture.md`
+
+# Step 5a: Handoff - Build & Write
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** verify status = "consolidated" before proceeding
+- **ALWAYS** ask user for implementation strategy preference (multi-module only)
+- **ALWAYS** derive prd.json from feature.json (NEVER independently)
+- **NEVER** invent entities/FRs/BRs not in feature.json
+- **ALL** API routes from specification.apiEndpoints (exact copy)
+- **Permission** paths from specification.permissionMatrix (full format)
+- **ALWAYS** generate 5 CORE SeedData task entries per module
+
+## 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.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Verify Consolidation Passed
+
+Use ba-reader to locate the feature and verify consolidation status:
+
+```
+ba-reader.findFeature({feature_id})
+→ Check status = "consolidated"
+```
+
+**IF** status ≠ "consolidated" → **STOP**. Return to step-04-consolidation.md.
+
+Display validation summary:
+
+```
+✓ Consolidation: APPROVED
+✓ Modules: {count} specified and validated
+✓ Cross-module: interactions mapped
+✓ Permissions: coherent
+→ Proceeding to handoff...
+```
+
+Include:
+- Number of modules
+- Number of entities across all modules
+- Number of use cases across all modules
+- Number of business rules across all modules
+- Cross-module interaction count
+
+---
+
+### 2. Implementation Strategy Choice (Multi-Module)
+
+**IF** more than 1 module defined in feature.json:
+
+Ask via AskUserQuestion:
+
+```
+question: "Quelle stratégie d'implémentation préférez-vous ?"
+header: "Stratégie d'implémentation"
+options:
+  - label: "Module par module (Recommandé)"
+    description: "Implémenter chaque module complètement avant de passer au suivant. Suit l'ordre topologique des dépendances."
+  - label: "Couche par couche"
+    description: "Implémenter toutes les entités, puis tous les services, puis tous les contrôleurs, etc. Plus de parallélisation possible mais plus complexe."
+  - label: "Hybride"
+    description: "Modules fondation en premier (couche par couche), puis modules dépendants (module par module)"
+```
+
+Store the chosen strategy in `handoff.implementationStrategy`.
+
+**IF** only 1 module → default to "Module par module" (no choice needed).
+
+---
+
+### 3. Calculate Complexity
+
+For each module in feature.json.modules[], calculate:
+
+```json
+{
+  "complexity": "simple|medium|complex",
+  "complexityDetails": {
+    "entities": {count},
+    "useCases": {count},
+    "businessRules": {count},
+    "calculated": "{level} (≤X entities, ≤Y UCs, ≤Z BRs)"
+  }
+}
+```
+
+| Criteria | Simple | Medium | Complex |
+|----------|--------|--------|---------|
+| Entities | ≤3 | ≤6 | >6 |
+| Use Cases | ≤5 | ≤12 | >12 |
+| Business Rules | ≤10 | ≤20 | >20 |
+
+**Global complexity** = highest complexity across all modules.
+
+Example:
+- Module A: 4 entities, 6 use cases, 8 BRs → **simple**
+- Module B: 8 entities, 15 use cases, 25 BRs → **complex**
+- Overall: **complex**
+
+---
+
+### 4. Map Specification to Files
+
+> **IMPORTANT:** Generate `handoff.filesToCreate` as structured object with 7 categories.
+> Each file entry is `{path, type, linkedFRs, linkedUCs, module}`. NO free text.
+> Read `.smartstack/config.json` to extract baseNamespace for project namespace.
+
+**Order by topological dependency** (modules with no deps first, then dependents).
+
+For **EACH module** in topological order:
+
+#### 4.1 Domain Files
+
+From `analysis.entities[]` of the module:
+
+```json
+"domain": [
+  {
+    "path": "src/Domain/Entities/{ModuleName}/{EntityName}.cs",
+    "type": "Entity",
+    "linkedFRs": ["FR-001", "FR-002"],
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- Value objects referenced by entities
+- Enums used in domain
+- Domain exceptions specific to module
+
+#### 4.2 Application Files
+
+From `analysis.useCases[]` of the module:
+
+```json
+"application": [
+  {
+    "path": "src/Application/Services/{ModuleName}/{ServiceName}Service.cs",
+    "type": "Service",
+    "linkedFRs": ["FR-001"],
+    "linkedUCs": ["UC-001", "UC-002"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Application/DTOs/{ModuleName}/{DtoName}Dto.cs",
+    "type": "Dto",
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Application/Validators/{ModuleName}/{ValidatorName}Validator.cs",
+    "type": "Validator",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- Service per use case cluster (or per domain entity if applicable)
+- DTOs for API contracts
+- Validators for FluentValidation
+- Query handlers
+
+#### 4.3 Infrastructure Files
+
+From `analysis.entities[]` of the module:
+
+```json
+"infrastructure": [
+  {
+    "path": "src/Infrastructure/Repositories/{ModuleName}/{EntityName}Repository.cs",
+    "type": "Repository",
+    "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
+- Specifications if complex queries
+
+#### 4.4 API Files
+
+From `specification.apiEndpoints[]` of the module:
+
+```json
+"api": [
+  {
+    "path": "src/API/Controllers/{ModuleName}Controller.cs",
+    "type": "ApiController",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- One controller per domain aggregate root (or logical grouping)
+- Include all HTTP methods (GET, POST, PUT, DELETE, PATCH)
+- Error handling and validation responses
+
+#### 4.5 Frontend Files
+
+From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.useCases[]` of the module:
+
+> **WIREFRAME TRACEABILITY RULE:** Every frontend file (Page, DashboardPage, Component) MUST include `linkedWireframes[]` referencing the wireframe `screen` identifiers from `specification.uiWireframes[]`. This ensures the BA mockups validated by the client are respected during implementation.
+
+```json
+"frontend": [
+  {
+    "path": "src/pages/{ModuleName}/{PageName}Page.tsx",
+    "type": "Page",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "linkedWireframes": ["{module}-list"],
+    "module": "{moduleCode}",
+    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-list': elements [{elements}], actions [{actions}]. See specification.uiWireframes[] for exact mockup."
+  },
+  {
+    "path": "src/pages/{ModuleName}/{PageName}DetailPage.tsx",
+    "type": "Page",
+    "linkedUCs": ["UC-003"],
+    "linkedWireframes": ["{module}-detail"],
+    "module": "{moduleCode}",
+    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-detail': elements [{elements}], actions [{actions}]. See specification.uiWireframes[] for exact mockup."
+  },
+  {
+    "path": "src/pages/{ModuleName}/{DashboardName}DashboardPage.tsx",
+    "type": "DashboardPage",
+    "linkedUCs": ["UC-060"],
+    "linkedWireframes": ["{module}-dashboard"],
+    "module": "{moduleCode}",
+    "dashboardRef": "{module}-dashboard",
+    "instructions": "Use Recharts library. See specification.dashboards[] for KPI definitions, chart types, filters, and data sources.",
+    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-dashboard': KPI card positions, chart placement, filter bar location. See specification.uiWireframes[] AND specification.dashboards[] for exact mockup and KPI specs."
+  },
+  {
+    "path": "src/components/{ModuleName}/{ComponentName}.tsx",
+    "type": "Component",
+    "linkedUCs": ["UC-001"],
+    "linkedWireframes": ["{module}-{section}"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/hooks/use{ModuleName}{Hook}.ts",
+    "type": "Hook",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+**Wireframe Acceptance Criteria (ALL frontend pages):**
+> **MANDATORY** for every Page and DashboardPage task. These criteria ensure the BA mockups are respected.
+- Layout structure matches the validated ASCII/SVG wireframe from `specification.uiWireframes[]`
+- All `elements` listed in the wireframe are present in the generated component
+- All `actions` listed in the wireframe are implemented with correct permissions
+- Component mapping follows the wireframe-to-component table (see step-03 section 3b-bis)
+- If wireframe shows a DataGrid → implement with `SmartTable` or `EntityCard` grid
+- If wireframe shows FilterBar → implement with `SmartFilter`
+- If wireframe shows ActionButton → wrap in `RequirePermission`
+
+**Dashboard pages (type: DashboardPage):**
+- Generated from `specification.dashboards[]` entries
+- `dashboardRef` links to the dashboard code in specification.dashboards[]
+- `linkedWireframes` links to the dashboard wireframe in specification.uiWireframes[]
+- `instructions` MUST reference chart types, KPI definitions, and data sources
+- Acceptance criteria for DashboardPage tasks MUST include:
+  - Chart library (Recharts) installed in package.json
+  - Chart types matching specification.dashboards[].kpis[].visualization
+  - KPI cards for kpi-card type visualizations
+  - Filters functional (dateRange, select, etc.)
+  - CSS variables used (no hardcoded colors) - see ui-components/patterns/dashboard-chart.md
+  - Responsive layout (1-col mobile, 2-col tablet, 3-col desktop)
+  - **KPI card positions match wireframe layout** (e.g., 4 cards in a row if wireframe shows 4)
+  - **Chart placement matches wireframe** (e.g., 2-column grid if wireframe shows side-by-side)
+
+**Standard pages (type: Page):**
+- Pages for major use cases
+- Components for reusable UI elements
+- Custom hooks for business logic
+- Forms for data entry
+- List/Detail views
+- **ALL pages MUST reference their wireframe via `linkedWireframes`**
+
+#### 4.6 SeedData Files
+
+**OBLIGATORY:** 5 CORE SeedData entries per module + business seed data:
+
+```json
+"seedData": [
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationModuleSeedData.cs",
+    "type": "SeedData",
+    "category": "core",
+    "source": "specification.seedDataCore.navigationModules",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/PermissionsSeedData.cs",
+    "type": "SeedData",
+    "category": "core",
+    "source": "specification.seedDataCore.permissions",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs",
+    "type": "SeedData",
+    "category": "core",
+    "source": "specification.seedDataCore.roles",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/TenantSeedData.cs",
+    "type": "SeedData",
+    "category": "core",
+    "source": "specification.seedDataCore.tenants",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/UserSeedData.cs",
+    "type": "SeedData",
+    "category": "core",
+    "source": "specification.seedDataCore.users",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs",
+    "type": "SeedData",
+    "category": "business",
+    "source": "specification.seedDataBusiness.{module}",
+    "module": "{moduleCode}"
+  }
+]
+```
+
+**For client projects (ExtensionsDbContext), add these MANDATORY infrastructure files:**
+
+```json
+"seedData": [
+  // ... 5 core + business entries above ...
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs",
+    "type": "IClientSeedDataProvider",
+    "category": "infrastructure",
+    "description": "Runtime provider that injects core seed data (navigation, permissions, roles) into Core schema",
+    "source": "specification.seedDataCore",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/DevDataSeeder.cs",
+    "type": "DevDataSeeder",
+    "category": "infrastructure",
+    "description": "Seeds development/demo data for domain entities at startup",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs",
+    "type": "SeedConstants",
+    "category": "infrastructure",
+    "description": "Shared constants for deterministic seed data",
+    "module": "{moduleCode}"
+  }
+]
+```
+
+**Path convention:** All seed data files MUST be under `Persistence/Seeding/Data/` (matching SmartStack.app architecture).
+NEVER use `Data/SeedData/` or `Infrastructure/Data/SeedData/`.
+
+**IClientSeedDataProvider (MANDATORY for client projects):** This provider injects core seed data
+(navigation, permissions, roles) into the Core schema at runtime. Generated at
+`src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`.
+See `/application` skill step-03b-provider for the full pattern.
+Without this provider, the 5 core SeedData files are DEAD CODE and will have no effect.
+
+Core categories (ALWAYS 5):
+1. NavigationModuleSeedData (navigation items for module)
+2. PermissionsSeedData (RBAC permissions)
+3. RolesSeedData (roles using permissions)
+4. TenantSeedData (test tenants)
+5. UserSeedData (test users)
+
+Business categories (from specification.seedDataBusiness):
+- Domain-specific reference data
+- Test data fixtures
+- Lookup tables (statuses, categories, etc.)
+
+#### 4.7 Test Files
+
+```json
+"tests": [
+  {
+    "path": "src/Tests/Unit/Domain/{ModuleName}/{Entity}Tests.cs",
+    "type": "UnitTests",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Unit/Application/{ModuleName}/{ServiceName}ServiceTests.cs",
+    "type": "UnitTests",
+    "linkedFRs": ["FR-001"],
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Integration/{ModuleName}/{ApiControllerName}ControllerTests.cs",
+    "type": "IntegrationTests",
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Security/{ModuleName}/{ModuleName}SecurityTests.cs",
+    "type": "SecurityTests",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Test files:
+- Unit tests for domain entities and value objects
+- Unit tests for services and validators
+- Integration tests for API endpoints
+- Security tests for authorization and tenant isolation
+- E2E tests for critical user flows
+
+---
+
+### 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)
+
+Before proceeding to step-05b-deploy.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"
+
+**IF any check fails → FIX before proceeding.** Do NOT generate artifacts (prd.json, progress.txt) without complete handoff data.
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-05b-deploy.md`