@atlashub/smartstack-cli 3.5.0 → 3.6.0

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

@@ -0,0 +1,302 @@
+---
+name: step-05b-mapping
+description: BR-to-code mapping, API endpoint summary, write handoff to feature.json
+model: sonnet
+next_step: steps/step-05c-deploy.md
+---
+
+> **Context files:** `_shared.md` | `_architecture.md`
+
+# Step 5b: Handoff - Mapping & Write
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** derive mappings 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)
+
+## YOUR TASK
+
+Map business rules to code implementation points, generate API endpoint summary, and write the complete handoff data to EACH module feature.json AND master feature.json.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 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.
+> **PATH RULE:** All backend paths MUST include `{ContextPascal}/{ApplicationName}/` hierarchy (see section 4 of step-05a).
+> ```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 step-05a calculation)
+   - filesToCreate (full 7-category structure from step-05a section 4, filtered for this module)
+   - brToCodeMapping (from this step section 5, filtered for this module)
+   - apiEndpointSummary (from this step 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-05c
+  → 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 (MANDATORY before loading step-05c-deploy)
+
+Before proceeding to step-05c-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** have `handoff.apiEndpointSummary.length > 0`
+4. **ALL module feature.json** status = "handed-off"
+5. **Master feature.json** has `handoff` section with implementationStrategy, moduleOrder, totalFilesToCreate
+6. **Master status** = "handed-off"
+
+**IF any check fails → FIX before proceeding.** Do NOT generate artifacts without complete handoff data.
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-05c-deploy.md`

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

@@ -0,0 +1,296 @@
+---
+name: step-05c-deploy
+description: Generate prd.json, progress.txt, update BA manifest, display completion summary
+model: sonnet
+next_step: steps/step-05d-html.md
+---
+
+> **Context files:** `_shared.md`
+
+# Step 5c: Deploy Artifacts
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** verify all module handoffs are complete before generating artifacts
+- **ALWAYS** derive prd.json from feature.json (NEVER independently)
+- **NEVER** invent entities/FRs/BRs not in feature.json
+- **ALWAYS** update BA manifest at docs/business/index.json
+
+## YOUR TASK
+
+Generate deployment artifacts from the handoff data written in step-05a: prd.json (per module), progress.txt, and update the BA manifest. The interactive HTML document is handled in step-05d.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 0. Pre-flight Verification
+
+Before generating ANY artifact, verify step-05a completed successfully:
+
+```
+FOR each module in modules[]:
+  Read module feature.json
+  IF module.handoff === {} OR module.status !== "handed-off":
+    → BLOCKING ERROR: Module {module.code} has no handoff data
+    → Return to step-05a-handoff.md
+```
+
+IF all modules have valid handoff → proceed.
+
+---
+
+### 1. Generate prd.json (PROGRAMMATIC)
+
+> **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 each module:**
+
+```
+Execute: ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
+```
+
+**For consolidated view (multi-module, optional):**
+
+```
+Execute: ss derive-prd --application {masterFeaturePath}
+→ Generates .ralph/prd-{moduleCode}.json for each module
+```
+
+**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 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"
+
+**POST-CHECK (BLOCKING — DO NOT SKIP):**
+
+After `ss derive-prd` execution, read the generated prd-{moduleCode}.json and verify structural integrity:
+
+```javascript
+const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
+const featureHandoff = moduleFeature.handoff.filesToCreate;
+
+// 1. Verify structure: filesToCreate MUST be under implementation (NOT root level)
+if (prd.filesToCreate && !prd.implementation?.filesToCreate) {
+  BLOCKING_ERROR("prd.json has filesToCreate at ROOT level — this is NOT from ss derive-prd");
+  BLOCKING_ERROR("Re-run: ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json");
+  STOP;
+}
+
+// 2. Verify ALL 7 categories present and match feature.json
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+for (const cat of categories) {
+  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but feature.json has ${featureCount}`);
+  }
+}
+```
+
+Display verification table:
+
+```
+POST-CHECK: prd-{moduleCode}.json integrity
+| Category       | feature.json | prd.json | Match |
+|----------------|-------------|----------|-------|
+| domain         | {n}         | {n}      | OK/FAIL |
+| application    | {n}         | {n}      | OK/FAIL |
+| infrastructure | {n}         | {n}      | OK/FAIL |
+| api            | {n}         | {n}      | OK/FAIL |
+| frontend       | {n}         | {n}      | OK/FAIL |
+| seedData       | {n}         | {n}      | OK/FAIL |
+| tests          | {n}         | {n}      | OK/FAIL |
+```
+
+IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proceed with incomplete PRD.
+
+---
+
+### 2. Initialize Progress Tracker
+
+> **Template:** Read `templates/tpl-progress.md` for the complete progress tracker template structure.
+> Populate the template with module-specific data from feature.json handoff sections.
+
+**Progress Tracker Rules:**
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module -> layer -> tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Cross-module tasks only if multi-module
+
+---
+
+### 3. Update BA Manifest (MANDATORY)
+
+> **The BA manifest enables the SmartStack web app to discover and display all available business analyses.**
+> It is a JSON index file at `docs/business/index.json` that lists all feature.json files.
+
+**Path:** `docs/business/index.json` (project root relative)
+
+**Schema:**
+```json
+{
+  "version": "1.0",
+  "updatedAt": "{ISO timestamp}",
+  "analyses": [
+    {
+      "appCode": "{app_code}",
+      "appName": "{application_name}",
+      "moduleCode": null | "{module_code}",
+      "moduleName": "{module_name}",
+      "version": "{version}",
+      "status": "handed-off",
+      "featureDescription": "{feature_description}",
+      "path": "{app_code}/business-analyse/v{version}/feature.json",
+      "updatedAt": "{ISO timestamp}"
+    }
+  ]
+}
+```
+
+**Update logic:**
+
+1. Read existing manifest at `docs/business/index.json` (or create empty `{ "version": "1.0", "updatedAt": "", "analyses": [] }`)
+2. For the APPLICATION-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: null` and `path: "{app_code}/business-analyse/v{version}/feature.json"`
+3. For EACH MODULE-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: "{module_code}"` and `path: "{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+4. Update root `updatedAt` to current timestamp
+5. Write manifest back to `docs/business/index.json`
+
+**Display confirmation:**
+```
+✓ BA manifest updated: docs/business/index.json
+  Entries: {total_count} ({app_count} applications, {module_count} modules)
+  Web viewer: /system/docs/ba
+```
+
+**Why a manifest?**
+- The web app needs to discover available BAs without scanning the filesystem
+- Static file serving (no backend API needed)
+- Incremental updates: each handoff adds/updates only its entries
+- Consumed by the SmartStack web app BA viewer at `/system/docs/ba`
+
+---
+
+### 4. Completion Summary
+
+Display the completion summary after successful artifact deployment:
+
+> **Reference:** Read `templates/tpl-launch-displays.md` for user-facing display templates.
+
+```
+═══════════════════════════════════════════════════════════════
+  [OK] BUSINESS ANALYSE TERMINEE - {application_name}
+═══════════════════════════════════════════════════════════════
+
+Modules:   {count} ({names})
+Strategy:  {strategy}
+Files:     {total files across all modules}
+Tasks:     {total tasks} ({core_count} CORE + {biz_count} business + {dev_count} development)
+Complexity: {complexity}
+Effort:    {total_days} days ({total_hours} hours)
+
+[DIR] Artefacts generés:
+  ✓ feature.json (master + per-module) - spécification complète
+  ✓ .ralph/prd.json or .ralph/prd-{module}.json - task breakdown
+  ✓ .ralph/progress.txt - tracker de progression
+  ✓ ba-interactive.html - document de revue interactif (step-05d)
+
+[TARGET] Prochaines étapes:
+  1. Finaliser le document interactif (HTML)
+  2. Ouvrir ba-interactive.html dans le navigateur
+  3. Partager avec les stakeholders pour validation
+  4. Si retours --> relancer /business-analyse pour une nouvelle itération
+  5. Une fois validé, lancer le développement:
+
+     /ralph-loop -r
+
+═══════════════════════════════════════════════════════════════
+```
+
+**No AskUserQuestion here.** Proceed directly to step-05d.
+
+---
+
+## SELF-VERIFICATION
+
+Before proceeding to step-05d, VERIFY:
+
+1. **`.ralph/prd-{module}.json`** exists for ALL modules (file size > 100 bytes each)
+2. **`.ralph/progress.txt`** exists (file size > 500 bytes)
+3. **`docs/business/index.json`** exists with correct entry count (1 app + N modules)
+
+**IF any check fails → GENERATE the missing artifact before proceeding to step-05d.**
+
+---
+
+## MODE SUPPORT
+
+### Standard Mode
+
+Full handoff with all implementation details:
+- All 7 file categories
+- Complete BR-to-code mapping
+- Full API endpoint summary
+- Detailed prd.json
+- Comprehensive progress tracker
+
+### Micro Mode (use_case = micro)
+
+Simplified handoff with minimal scope:
+- Only essential CRUD entity + controller
+- 3 core SeedData entries (omit some optional ones)
+- Basic prd.json with simplified sections
+- Lightweight progress.txt
+- Display `/ralph-loop -r` command for later use
+
+### Delta Mode (use_case = refactoring)
+
+Focused handoff for changes:
+- Only affected modules listed
+- Reuse existing implementation patterns
+- Highlight what changed vs baseline
+- Update only affected prd.json sections
+- Progress tracker shows only delta tasks
+
+---
+
+## TROUBLESHOOTING
+
+| Issue | Resolution |
+|-------|-----------|
+| All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
+| prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
+| progress.txt incomplete | Ensure all 5 CORE SeedData entries are present per module. Check topological order. |
+| BA manifest not found | Create docs/business/index.json if missing. Use schema provided in section 3. |
+| Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.json metadata exactly. |
+
+---
+
+## NEXT STEP
+
+Load: steps/step-05d-html.md