@atlashub/smartstack-cli 2.6.2 → 2.7.0

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

@@ -545,202 +545,42 @@ Total endpoints = count of specification.apiEndpoints[] across all modules.
 
 ---
 
-### 7. Generate prd.json
+### 7. Generate prd.json (PROGRAMMATIC)
 
-> **FUNDAMENTAL RULE:** prd.json is **DERIVED** from feature.json, **NEVER** generated independently.
+> **RULE:** prd.json is extracted by CLI code, **NEVER** generated by LLM.
+> The `ss derive-prd` command performs a deterministic data transformation from feature.json.
 
-**For multi-module, ask user:**
+**For each module:**
 
 ```
-question: "Comment souhaitez-vous structurer le prd.json ?"
-header: "Structure PRD"
-options:
-  - label: "Un par module (Recommandé)"
-    description: "Chaque module a son propre prd.json (.ralph/prd-{module}.json). Plus facile à suivre individuellement."
-  - label: "Consolidé"
-    description: "Un seul prd.json (.ralph/prd.json) avec tous les modules. Vue d'ensemble unique."
+Execute: ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
 ```
 
-**For single-module**, default to single prd.json at `.ralph/prd.json`.
+**For consolidated view (multi-module, optional):**
 
-**prd.json structure (per module or consolidated):**
+```
+Execute: ss derive-prd --application {masterFeaturePath}
+→ Generates .ralph/prd-{moduleCode}.json for each module
+```
 
-```json
-{
-  "prd": {
-    "version": "2.0.0",
-    "source": {
-      "type": "ba-handoff",
-      "feature_json": "path/to/feature.json",
-      "step": "step-05-handoff",
-      "timestamp": "2026-02-02T14:30:00Z"
-    },
-    "metadata": {
-      "title": "Product Requirements Document - {application} {module}",
-      "status": "handed-off",
-      "createdBy": "business-analyse skill v4.0",
-      "createdAt": "2026-02-02T14:30:00Z"
-    },
-    "project": {
-      "name": "...",
-      "application": "...",
-      "module": "... (or omit for consolidated)",
-      "namespace": "From .smartstack/config.json.baseNamespace"
-    },
-    "overview": {
-      "summary": "From feature.json.specification.overview.summary",
-      "businessGoals": ["Goal 1", "Goal 2"],
-      "stakeholders": ["Stakeholder 1"],
-      "constraints": "From feature.json.specification.overview.constraints"
-    },
-    "requirements": {
-      "functional": {
-        "useCases": [
-          {
-            "id": "UC-001",
-            "title": "...",
-            "description": "...",
-            "actors": ["..."],
-            "steps": "...step 1, step 2...",
-            "postconditions": "..."
-          }
-        ],
-        "features": [
-          {
-            "id": "FR-001",
-            "title": "...",
-            "description": "...",
-            "priority": "must | should | could",
-            "linkedUCs": ["UC-001"]
-          }
-        ]
-      },
-      "nonFunctional": {
-        "performance": "...",
-        "security": "...",
-        "scalability": "...",
-        "usability": "..."
-      }
-    },
-    "businessRules": [
-      {
-        "id": "BR-VAL-001",
-        "title": "...",
-        "description": "...",
-        "type": "validation | constraint | calculation | security",
-        "severity": "critical | high | medium | low",
-        "implementedIn": ["Domain.Order", "API.OrdersController"]
-      }
-    ],
-    "architecture": {
-      "entities": [
-        {
-          "name": "...",
-          "description": "...",
-          "properties": ["prop1: string", "prop2: int"],
-          "relationships": ["Order → Customer", "Order → OrderItems"],
-          "linkedFR": "FR-001"
-        }
-      ],
-      "apiEndpoints": [
-        {
-          "method": "GET",
-          "route": "/api/business/orders",
-          "operation": "ListOrders",
-          "permissions": ["business.orders.read"],
-          "linkedUC": "UC-001"
-        }
-      ],
-      "permissionMatrix": [
-        {
-          "role": "OrderManager",
-          "permissions": ["business.orders.read", "business.orders.create"],
-          "description": "Can view and create orders"
-        }
-      ],
-      "dataModels": "From specification.dataModels"
-    },
-    "implementation": {
-      "strategy": "module-by-module | layer-by-layer | hybrid",
-      "moduleOrder": ["Module1", "Module2", "Module3"],
-      "dependencyOrder": "Topologically ordered based on feature.json.modules[].dependencies",
-      "taskBreakdown": {
-        "domain": "X tasks across entities, value objects, domain logic",
-        "application": "Y tasks across services, DTOs, validators",
-        "infrastructure": "Z tasks across repositories, persistence",
-        "api": "A tasks across controllers, error handling",
-        "frontend": "B tasks across pages, components, hooks (each with linkedWireframes)",
-        "seedData": "5 CORE + C business seed data tasks",
-        "tests": "D unit + E integration + F security tests",
-        "i18n": "G i18n key implementations"
-      },
-      "totalTasks": "X + Y + Z + A + B + (5 + C) + (D + E + F) + G",
-      "fileMapping": "See handoff.filesToCreate structured object"
-    },
-    "testing": {
-      "unitTests": [
-        {
-          "component": "Domain.Order",
-          "scenarios": ["Valid order creation", "Invalid total rejection"],
-          "coverage": "95%"
-        }
-      ],
-      "integrationTests": [
-        {
-          "endpoint": "POST /api/business/orders",
-          "scenarios": ["Happy path", "Validation failure", "Authorization failure"],
-          "coverage": "90%"
-        }
-      ],
-      "e2eTests": [
-        {
-          "userFlow": "Create Order → View Details → Update Status",
-          "coverage": "End-to-end"
-        }
-      ],
-      "testStrategy": "From specification.testing"
-    },
-    "i18n": {
-      "keys": [
-        {
-          "key": "orders.list.title",
-          "defaultValue": "Orders",
-          "usedIn": ["OrdersPage.tsx"],
-          "linkedUC": "UC-001"
-        }
-      ],
-      "locales": ["fr", "en", "it", "de"],
-      "translationStatus": "From specification.i18n.locales"
-    },
-    "seedData": {
-      "core": {
-        "navigationModules": "Module navigation structure",
-        "permissions": "Role-based permissions",
-        "roles": "Predefined roles",
-        "tenants": "Test tenants",
-        "users": "Test users"
-      },
-      "business": [
-        {
-          "entity": "OrderStatus",
-          "samples": ["Pending", "Confirmed", "Shipped", "Delivered"],
-          "source": "specification.seedDataBusiness"
-        }
-      ]
-    },
-    "risks": "From feature.json.risks (if present)",
-    "schedule": "Estimated based on complexity and strategy"
-  }
-}
+**Verification:** After execution, read the generated prd.json and display summary:
+
+```
+prd.json generated for module {moduleCode}:
+  - Use cases: {count}
+  - Functional requirements: {count}
+  - Business rules: {count}
+  - API endpoints: {count}
+  - Sections: {count}
+  - Files to create: {count}
+  - BR-to-code mappings: {count}
 ```
 
-**Key rules for prd.json:**
-- Source MUST reference feature.json (traceability)
-- All use cases, features, and business rules come from feature.json
-- API endpoints are EXACT copy from specification.apiEndpoints
-- Module order follows topological dependency order
-- Task breakdown based on filesToCreate count
-- Everything is **derived**, not invented
+**Key guarantees:**
+- Source MUST reference feature.json path (traceability)
+- All data is EXACT COPY from feature.json (no transformation, no invention)
+- prd.json version: "2.0.0"
+- source.type: "ba-handoff-programmatic"
 
 ---
 
@@ -913,9 +753,54 @@ COLORS:
 
 ### 9. Write Handoff to Feature.json
 
-Update feature.json with handoff data via ba-writer.
+> **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.
+
+#### 9a. Module Handoff Loop (MANDATORY)
+
+**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)"
+```
 
-**Application-level (master/root feature):**
+#### 9b. Master Handoff (after ALL modules written successfully)
 
 ```
 ba-writer.enrichSection({
@@ -927,46 +812,37 @@ ba-writer.enrichSection({
     implementationStrategy: "{strategy}",
     moduleCount: {count},
     moduleOrder: [...],
-    totalFilesToCreate: {count},
-    totalTasks: {count},
+    totalFilesToCreate: {sum across all modules},
+    totalTasks: {sum across all modules},
     prdStructure: "per-module | consolidated",
     prdFiles: [
-      { module: "Orders", path: ".ralph/prd-orders.json" },
-      { module: "Customers", path: ".ralph/prd-customers.json" }
+      { module: "{module1}", path: ".ralph/prd-{module1}.json" },
+      { module: "{module2}", path: ".ralph/prd-{module2}.json" }
     ],
     progressTrackerPath: ".ralph/progress.txt",
-    handedOffAt: "2026-02-02T14:30:00Z"
+    handedOffAt: "{ISO timestamp}"
   }
 })
 ```
 
-**Module-level (each feature.json in modules[] with corresponding module feature):**
+#### 9c. Final Verification (BLOCKING)
 
 ```
-ba-writer.enrichSection({
-  featureId: {module_feature_id},
-  section: "handoff",
-  data: {
-    status: "handed-off",
-    complexity: "{simple|medium|complex}",
-    filesToCreate: {...}, // Full 7-category structure from step 4
-    brToCodeMapping: [...],  // Full mapping from step 5
-    apiEndpointSummary: [...], // Full summary from step 6
-    prdFile: ".ralph/prd-{module}.json | .ralph/prd.json (if consolidated)",
-    totalFiles: {count},
-    totalTasks: {count},
-    handedOffAt: "2026-02-02T14:30:00Z"
-  }
-})
-```
-
-**Update status:**
-
-```
-ba-writer.updateStatus({
-  featureId: {feature_id},
-  status: "handed-off"
-})
+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**