@atlashub/smartstack-cli 3.6.0 → 3.8.0

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

@@ -1,302 +0,0 @@
----
-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

@@ -1,296 +0,0 @@
----
-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