@atlashub/smartstack-cli 3.6.0 → 3.8.0

package/templates/skills/business-analyse/react/components.md

@@ -1,7 +1,7 @@
 # React Components - Business Analyse Viewer
 
 > **Usage:** React component that renders feature.json directly
-> **Loaded in:** step-05d-html.md
+> **Loaded in:** step-05b-deploy.md
 > **Data source (module):** `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 > **Data source (application):** `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
 > **Related:** `react/application-viewer.md` for application-level view

package/templates/skills/business-analyse/react/schema.md

@@ -1,7 +1,7 @@
 # TypeScript Schema - Feature JSON Types
 
 > **Usage:** TypeScript interfaces aligned with feature-schema.json and application-schema.json
-> **Loaded in:** step-05d-html.md (for web app rendering)
+> **Loaded in:** step-05b-deploy.md (for web app rendering)
 > **Source (module):** `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 > **Source (application):** `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
 

package/templates/skills/business-analyse/references/html-data-mapping.md

@@ -1,6 +1,6 @@
 # HTML Data Mapping Reference (references/html-data-mapping.md)
 
-> **Used by:** step-05d-html (Deploy Interactive HTML), step-03d-validate (incremental HTML)
+> **Used by:** step-05b-deploy (Deploy Interactive HTML), step-03d-validate (incremental HTML)
 > **Purpose:** Exact mapping from feature.json to HTML FEATURE_DATA and EMBEDDED_ARTIFACTS objects
 
 ---
@@ -283,7 +283,7 @@ EMBEDDED_ARTIFACTS.dependencyGraph = {
 
 ---
 
-## Usage in step-05d-html
+## Usage in step-05b-deploy
 
 1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation for readability)
 2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)

package/templates/skills/business-analyse/schemas/feature-schema.json

@@ -43,7 +43,7 @@
     }
   },
 
-  "$comment": "Sub-schema loading guide per BA step: step-00-init → metadata-schema.json | step-01-cadrage → discovery-schema.json (module) OR application-schema.json (master) | step-02-decomposition → application-schema.json (modules[], dependencyGraph) | step-03a-data → analysis-schema.json | step-03b-ui → specification-schema.json (wireframes, layouts) | step-03c-compile → specification-schema.json | step-03d-validate → validation-schema.json | step-04-consolidation → validation-schema.json + application-schema.json (consolidation) | step-05a-handoff → handoff-schema.json | step-05b-mapping → handoff-schema.json (brToCodeMapping, apiEndpointSummary) | step-05c-deploy → (prd, progress, manifest) | step-05d-html → (ba-interactive.html)",
+  "$comment": "Sub-schema loading guide per BA step: step-00-init → metadata-schema.json | step-01-cadrage → discovery-schema.json (module) OR application-schema.json (master) | step-02-decomposition → application-schema.json (modules[], dependencyGraph) | step-03a-data → analysis-schema.json | step-03b-ui → specification-schema.json (wireframes, layouts) | step-03c-compile → specification-schema.json | step-03d-validate → validation-schema.json | step-04-consolidation → validation-schema.json + application-schema.json (consolidation) | step-05a-handoff → handoff-schema.json (filesToCreate, brToCodeMapping, apiEndpointSummary) | step-05b-deploy → (prd, progress, manifest, ba-interactive.html)",
 
   "$defs": {
     "stepStatus": { "$ref": "shared/common-defs.json#/$defs/stepStatus" },

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -416,5 +416,12 @@ If initialization was interrupted:
 
 1. Check `.business-analyse/config.json` for currentFeature
 2. If feature ID exists, search for feature.json in `docs/business/`
-3. If found, offer to resume from last completed step
+3. If found, check `metadata.workflow.lastCompletedStep`:
+   - If `"step-04-consolidation"` AND status = `"consolidated"`:
+     → Resume directly at `step-05a-handoff.md` (skip steps 00-04)
+     → Display: "Resuming from consolidation — proceeding to handoff..."
+   - If status = `"handed-off"` AND `.ralph/prd-*.json` files missing:
+     → Resume at `step-05b-deploy.md` (only deploy artifacts needed)
+     → Display: "Handoff complete but artifacts missing — deploying..."
+   - Otherwise: offer to resume from last completed step
 4. If not found, create fresh feature.json

package/templates/skills/business-analyse/steps/step-03d-validate.md

@@ -244,7 +244,7 @@ ba-writer.updateModuleStatus({feature_id}, {currentModule.code}, "specified")
 
 2. **Build FEATURE_DATA object:**
 
-   > **Use the EXACT SAME mapping defined in step-05d-html.md and references/html-data-mapping.md.**
+   > **Use the EXACT SAME mapping defined in step-05b-deploy.md and references/html-data-mapping.md.**
    > The mapping is identical — the only difference is that `moduleSpecs` only includes completed modules.
    > Modules not yet specified will NOT appear in `moduleSpecs` (their entry in `modules[]` will show `status: "pending"`).
 

package/templates/skills/business-analyse/steps/step-04-consolidation.md

@@ -531,6 +531,27 @@ When only 1 module:
 
 ---
 
+## WORKFLOW STATE SAVE (for resume support)
+
+After consolidation approval, update workflow state to enable resume if context is exhausted during handoff steps:
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata.workflow",
+  data: {
+    lastCompletedStep: "step-04-consolidation",
+    readyForHandoff: true
+  }
+})
+```
+
+> **Why:** Steps 05a-05b arrive late in the conversation when context may be near exhaustion.
+> If BA is interrupted during handoff, the user can resume with `/business-analyse` which will
+> detect `lastCompletedStep: "step-04-consolidation"` and resume directly at step-05a.
+
+---
+
 ## NEXT STEP
 
 Load: `./step-05a-handoff.md`

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

@@ -1,8 +1,8 @@
 ---
 name: step-05a-handoff
-description: Build the development handoff data - verify consolidation, choose implementation strategy, calculate complexity, and map specification to files (7 categories)
+description: Build development handoff data, map business rules to code, write handoff to feature.json
 model: sonnet
-next_step: steps/step-05b-mapping.md
+next_step: steps/step-05b-deploy.md
 ---
 
 > **Context files:** `_shared.md` | `_architecture.md`
@@ -21,7 +21,7 @@ next_step: steps/step-05b-mapping.md
 
 ## YOUR TASK
 
-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.
+Build the development handoff data: verify consolidation, choose implementation strategy, calculate complexity, map specification to files (7 categories), map business rules to code, generate API endpoint summary, and write handoff to EACH module feature.json.
 
 ---
 
@@ -467,18 +467,281 @@ Test files:
 
 ---
 
-## SELF-VERIFICATION (MANDATORY before loading step-05b-mapping)
+### 5. Map Business Rules to Code
 
-Before proceeding to step-05b-mapping.md, VERIFY:
+Derive from `analysis.businessRules[]` of **EACH module**.
 
-- **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)
+Generate complete mapping for each BR:
 
-**IF any check fails → FIX before proceeding.** The mapping and write operations in step-05b depend on complete handoff data structure.
+```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.
+> **PATH RULE:** All backend paths MUST include `{ContextPascal}/{ApplicationName}/` hierarchy (see section 4).
+> ```json
+> {
+>   "complexity": "simple|medium|complex",
+>   "filesToCreate": {
+>     "domain": [{"path": "src/Domain/Entities/{Ctx}/{App}/{Mod}/{Entity}.cs", "type": "Entity|ValueObject|Enum", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
+>     "application": [{"path": "src/Application/Services/{Ctx}/{App}/{Mod}/{Svc}Service.cs", "type": "Service|Dto|Validator", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
+>     "infrastructure": [{"path": "src/Infrastructure/Persistence/Configurations/{Ctx}/{App}/{Mod}/{Entity}Configuration.cs", "type": "EFConfiguration", "linkedFRs": [], "module": "..."}],
+>     "api": [{"path": "src/API/Controllers/{CtxShort}/{App}/{Entity}Controller.cs", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "..."}],
+>     "frontend": [{"path": "src/pages/{Mod}/{Page}Page.tsx", "type": "Page|Component|Hook|DashboardPage", "linkedUCs": [], "linkedWireframes": [], "module": "..."}],
+>     "seedData": [{"path": "src/Infrastructure/Persistence/Seeding/Data/{Mod}/...SeedData.cs", "type": "SeedData", "category": "core|business", "source": "...", "module": "..."}],
+>     "tests": [{"path": "src/Tests/Unit/Domain/{Ctx}/{App}/{Mod}/{Entity}Tests.cs", "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 section 3 calculation)
+   - filesToCreate (full 7-category structure from section 4, filtered for this module)
+   - brToCodeMapping (from section 5, filtered for this module)
+   - apiEndpointSummary (from section 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-05b
+  → Return to 7a 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
+
+Before proceeding to step-05b-deploy.md, VERIFY:
+
+1. **filesToCreate** has all 7 categories populated (domain, application, infrastructure, api, frontend, seedData, tests) for each module
+2. **Complexity** calculated for all modules
+3. **Implementation strategy** chosen (for multi-module features)
+4. **ALL module feature.json** have `handoff.brToCodeMapping.length > 0`
+5. **ALL module feature.json** have `handoff.apiEndpointSummary.length > 0`
+6. **ALL module feature.json** status = "handed-off"
+7. **Master feature.json** has `handoff` section with implementationStrategy, moduleOrder, totalFilesToCreate
+8. **Master status** = "handed-off"
+
+**IF any check fails → FIX before proceeding.**
 
 ---
 
 ## NEXT STEP
 
-Load: `steps/step-05b-mapping.md`
+Load: `steps/step-05b-deploy.md`