@atlashub/smartstack-cli 3.8.0 → 3.10.0

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

@@ -2,7 +2,7 @@
 name: step-05b-deploy
 description: Generate prd.json, deploy artifacts, interactive HTML
 model: sonnet
-next_step: null
+next_step: steps/step-05c-ralph-readiness.md
 ---
 
 > **Context files:** _shared.md
@@ -80,7 +80,7 @@ prd.json generated for module {moduleCode}:
 **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"
+- prd.json $version: "3.0.0" (unified format with pre-computed tasks)
 - source.type: "ba-handoff-programmatic"
 
 **POST-CHECK (BLOCKING — DO NOT SKIP):**
@@ -221,148 +221,20 @@ IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proce
 
 ---
 
-### 5. Build FEATURE_DATA Object
+### 5-7. Build FEATURE_DATA, EMBEDDED_ARTIFACTS & Replace Placeholders
 
-Reference `references/html-data-mapping.md` EXACTLY. The FEATURE_DATA object must contain:
+See [references/deploy-data-build.md](../references/deploy-data-build.md) for:
+- Complete FEATURE_DATA object structure (metadata, cadrage, modules, moduleSpecs, consolidation, handoff)
+- Complete EMBEDDED_ARTIFACTS object structure (wireframes, e2eFlows, dependencyGraph)
+- 7-step build process for FEATURE_DATA
+- 4-step artifact gathering for EMBEDDED_ARTIFACTS
+- Placeholder replacement rules (8 placeholders)
 
-**Structure:**
-```javascript
-const FEATURE_DATA = {
-  metadata: {
-    applicationName: master.application_name,
-    applicationId: master.feature_id,
-    version: master.version,
-    createdAt: ISO_TIMESTAMP,
-    vibeCoding: master.metadata.vibeCoding // "enabled" or "disabled" — controls UI section visibility
-  },
-  cadrage: {
-    goal: master.cadrage.goal,
-    vision: master.cadrage.vision,
-    success_criteria: master.cadrage.success_criteria,
-    scope: {
-      // CONVERT feature.json keys to HTML keys:
-      // mustHave → vital
-      // shouldHave → important
-      // couldHave → optional
-      // outOfScope → excluded
-      vital: master.globalScope.mustHave || [],
-      important: master.globalScope.shouldHave || [],
-      optional: master.globalScope.couldHave || [],
-      excluded: master.globalScope.outOfScope || []
-    },
-    constraints: master.cadrage.constraints || [],
-    risks: master.cadrage.risks || [],
-    stakeholders: master.stakeholders || []
-  },
-  modules: [
-    {
-      moduleCode: module.code,
-      moduleName: module.name,
-      moduleDescription: module.description || "",
-      // ... per-module fields from feature.json
-    }
-  ],
-  moduleSpecs: {
-    // CRITICAL: Must have ONE entry per module with ALL module data
-    // Each entry keyed by moduleCode:
-    "{moduleCode}": {
-      useCases: module.specification.useCases || [],
-      businessRules: module.analysis.businessRules || [],
-      entities: module.analysis.entities || [],
-      permissions: module.specification.permissions || [],
-      apiEndpoints: module.specification.apiEndpoints || []
-    }
-  },
-  consolidation: {
-    // Cross-module analysis
-    integrations: master.consolidation.integrations || [],
-    sharedEntities: master.consolidation.sharedEntities || [],
-    sequenceDiagrams: master.consolidation.e2eFlows || []
-  },
-  handoff: {
-    // From feature.json handoff section
-    complexity: master.handoff.complexity,
-    implementationStrategy: master.handoff.implementationStrategy,
-    moduleOrder: master.handoff.moduleOrder,
-    filesToCreate: master.handoff.filesToCreate,
-    brToCodeMapping: master.handoff.brToCodeMapping,
-    apiEndpointSummary: master.handoff.apiEndpointSummary
-  }
-};
-```
-
-**Build process:**
-1. Extract metadata from master feature.json
-2. Extract cadrage from master feature.json (CONVERT scope keys)
-3. Extract stakeholders from master.stakeholders
-4. Iterate ALL modules and populate moduleSpecs (THIS IS CRITICAL — empty moduleSpecs = BUG)
-5. For EACH module, extract:
-   - Use cases from specification.useCases
-   - Business rules from analysis.businessRules
-   - Entities from analysis.entities
-   - Permissions from specification.permissions
-   - API endpoints from specification.apiEndpoints
-6. Extract consolidation data (integrations, shared entities, E2E flows)
-7. Extract handoff section (complexity, strategy, module order, file counts)
-
----
-
-### 6. Build EMBEDDED_ARTIFACTS Object
-
-Extract visual artifacts and diagrams from the analysis:
-
-```javascript
-const EMBEDDED_ARTIFACTS = {
-  wireframes: [
-    // Extract from each module's specification.uiWireframes
-    {
-      moduleCode: "{moduleCode}",
-      screen: wireframe.screen,
-      description: wireframe.description,
-      layout: wireframe.layout || "responsive",
-      components: wireframe.components || []
-    }
-  ],
-  e2eFlows: [
-    // Extract from master consolidation.e2eFlows
-    {
-      flowName: flow.name,
-      description: flow.description,
-      sequence: flow.sequence || [],
-      modules: flow.modules || []
-    }
-  ],
-  dependencyGraph: {
-    // From master consolidation.dependencyGraph
-    nodes: master.consolidation.dependencyGraph?.nodes || [],
-    edges: master.consolidation.dependencyGraph?.edges || []
-  }
-};
-```
-
-**Artifact gathering:**
-1. Read each module's `specification.uiWireframes[]` and add to wireframes array
-2. Read master's `consolidation.e2eFlows[]` and add to e2eFlows array
-3. Read master's `consolidation.dependencyGraph` and include as-is
-4. Serialize as JSON with 2-space indentation
-
----
-
-### 7. Replace Placeholders in Template
-
-1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation)
-2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)
-3. Replace `{{FEATURE_DATA}}` with the serialized FEATURE_DATA JSON
-4. Replace `{{EMBEDDED_ARTIFACTS}}` with the serialized EMBEDDED_ARTIFACTS JSON
-5. Replace `{{APPLICATION_NAME}}` with `{application_name}`
-6. Replace `{{APPLICATION_ID}}` with `{feature_id}`
-7. Replace `{{VERSION}}` with `{version}`
-8. Replace `{{CREATED_AT}}` with `{ISO timestamp}`
-
-**Verification during replacement:**
-- Ensure FEATURE_DATA JSON is valid (no trailing commas, proper nesting)
-- Ensure EMBEDDED_ARTIFACTS JSON is valid
-- Verify placeholders are completely replaced (grep for `{{` to confirm)
+**Critical reminders:**
+- FEATURE_DATA.**moduleSpecs** MUST have ONE entry per module (empty = BUG)
+- FEATURE_DATA.**cadrage.scope** converts `mustHave→vital`, `shouldHave→important`, `couldHave→optional`, `outOfScope→excluded`
+- FEATURE_DATA.**metadata.vibeCoding** from `master.metadata.vibeCoding`
+- Also reference `references/html-data-mapping.md` for the full mapping spec
 
 ---
 
@@ -467,7 +339,12 @@ Effort:    {total_days} days ({total_hours} hours)
   1. Ouvrir ba-interactive.html dans le navigateur
   2. Partager avec les stakeholders pour validation
   3. Si retours --> relancer /business-analyse pour une nouvelle itération
-  4. Une fois validé, lancer le développement:
+  4. Validation de la compatibilité ralph-loop (recommandé):
+
+     Continuez à step-05c-ralph-readiness.md pour valider
+     la complétude et l'intégrité avant développement
+
+  5. Une fois validé, lancer le développement:
 
      /ralph-loop -r
 
@@ -476,50 +353,24 @@ Effort:    {total_days} days ({total_hours} hours)
 
 ---
 
-## MODE SUPPORT
-
-### Standard Mode
+## NEXT STEP
 
-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
+**RECOMMENDED:** Load `steps/step-05c-ralph-readiness.md` to run validation gate before /ralph-loop.
 
-### Micro Mode (use_case = micro)
+This validation ensures:
+- All module handoffs are complete
+- PRD files are structurally valid
+- Cross-module references are resolvable
+- No blocking issues before development
 
-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
+User can skip validation and proceed directly to /ralph-loop, but validation is strongly recommended to catch issues early.
 
 ---
 
-## 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. |
-| ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
-| moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
-| Scope keys still show "mustHave" instead of "vital" | Conversion from feature.json keys to HTML keys failed. Check cadrage.scope conversion logic. |
-| Wireframes array is empty | Verify each module has specification.uiWireframes. If missing, add wireframe stubs. |
-| dependencyGraph missing | Verify master feature.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
-| HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
-| Export/re-import fails | Verify exported JSON matches original feature.json schema. Validate with `/business-analyse -x --validate`. |
+## MODE SUPPORT & TROUBLESHOOTING
+
+See [references/deploy-modes.md](../references/deploy-modes.md) for:
+- **Standard Mode** — full handoff (all 7 categories, complete mapping)
+- **Micro Mode** — simplified CRUD (3 core SeedData, lightweight)
+- **Delta Mode** — refactoring focus (affected modules only)
+- **Troubleshooting** — 12 common issues with resolutions