@atlashub/smartstack-cli 3.9.0 → 3.12.0

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

@@ -0,0 +1,186 @@
+---
+name: step-04c-decide
+description: Final client approval, write consolidation, proceed to handoff
+model: opus
+next_step: steps/step-05a-handoff.md
+---
+
+> **Context files:** `_shared.md`
+
+# Step 4c: Decide - Final Approval & Consolidation Write
+
+## MANDATORY EXECUTION RULES
+- Final client approval is BLOCKING before handoff
+- ALWAYS write consolidation section before proceeding
+- ALWAYS update workflow state for resume support
+
+## YOUR TASK
+Obtain final client approval for the complete application specification, write the consolidation section to feature.json, and prepare for handoff.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 8. Final Client Approval (BLOCKING)
+
+Ask via AskUserQuestion:
+```
+question: "La spécification complète de l'application est prête. Validez-vous l'ensemble ?"
+header: "Approbation"
+options:
+  - label: "Approuvé"
+    description: "Passer au handoff pour la phase d'implémentation"
+  - label: "Réviser un module"
+    description: "Retourner à la spécification d'un module spécifique"
+  - label: "Modifier les interactions"
+    description: "Ajuster les interactions cross-module"
+```
+
+IF "Réviser un module":
+  Ask which module → set currentModuleIndex to that module → load step-03a-data.md
+
+IF "Modifier les interactions":
+  Re-enter step-04a-collect.md (sections 2-4)
+
+### 9. Write Consolidation
+
+> **STRUCTURE CARD: consolidation** — Must match `application-schema.json`. Follow this structure exactly.
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "consolidation",
+  data: {
+    crossModuleInteractions: [
+      {
+        "fromModule": "Orders",
+        "toModule": "Customers",
+        "interactionType": "FK-reference|event-publish|event-subscribe|shared-lookup|cascade-delete|cascade-update",
+        "description": "Order references customer via FK",
+        "entities": ["Order→Customer"]
+      }
+    ],
+    sharedEntities: [
+      {
+        "entity": "Customer",
+        "ownerModule": "Customers",
+        "referencedBy": ["Orders", "Invoices"],
+        "sharedFields": ["code", "name"]
+      }
+    ],
+    permissionCoherence: {
+      "rolesConsistent": true,
+      "pathFormatConsistent": true,
+      "hierarchyRespected": true,
+      "conflicts": [],
+      "warnings": []
+    },
+    e2eFlows: [
+      {
+        "name": "Order to Invoice",
+        "modules": ["Customers", "Orders", "Invoices"],
+        "steps": [
+          { "module": "Orders", "action": "Create order", "permission": "business.sales.orders.create", "dataFlow": "Customer → Order" }
+        ]
+      }
+    ],
+    globalRiskAssessment: [
+      {
+        "risk": "Cross-module coupling complexity",
+        "category": "coupling|complexity|dependency-chain|security|scope",
+        "severity": "critical|high|medium|low",
+        "mitigation": "Event-driven communication instead of direct FK"
+      }
+    ],
+    semanticChecks: [
+      { "check": "permission-orpheline", "status": "PASS|WARNING|ERROR", "details": "..." },
+      { "check": "uc-sans-fr", "status": "PASS|WARNING|ERROR", "details": "..." },
+      { "check": "wireframe-coverage", "status": "PASS|WARNING|ERROR", "details": "..." }
+    ],
+    decision: {
+      "approved": true,
+      "reason": "All cross-module validations passed",
+      "approvedBy": "Client",
+      "approvedAt": "{ISO timestamp}"
+    }
+  }
+})
+
+ba-writer.updateStatus({feature_id}, "consolidated")
+```
+
+> **STRUCTURE DIFFERENCES FROM OLD FORMAT:**
+> - `crossModuleInteractions` is a FLAT ARRAY (not `{fkReferences, sharedEntities, events}` nested object)
+> - `sharedEntities` is TOP-LEVEL (not nested inside crossModuleInteractions)
+> - `decision` is an OBJECT with `approved`, `reason`, `approvedBy`, `approvedAt` (not `clientApproval` string)
+> - `globalRiskAssessment` is an ARRAY of risk objects (not `{totalEntities: {value, threshold}}`)
+
+Add changelog entry:
+```json
+{
+  "step": "step-04-consolidation",
+  "timestamp": "...",
+  "changes": [
+    "Cross-module interactions: X FK, Y events, Z shared entities",
+    "Permission coherence: validated ({count} paths, {conflicts} conflicts resolved)",
+    "E2E flows: {count} identified",
+    "Global risk: {level}",
+    "Client approval: APPROVED"
+  ]
+}
+```
+
+### 10. 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.
+
+---
+
+## SINGLE-MODULE MODE
+
+When only 1 module:
+1. Auto-approve (no cross-module concerns)
+2. Write minimal consolidation section
+3. Display: "Module unique - consolidation automatique ✓"
+4. Proceed to step-05a-handoff.md
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Full module feature.json files |
+| consolidation data (from steps 04a-04b) | Questionnaires |
+| Master feature.json | Templates |
+
+---
+
+## SUCCESS CRITERIA
+
+- Client approval obtained (or auto-approved for single module)
+- Consolidation section written to master feature.json
+- Status updated to "consolidated"
+- Workflow state saved for resume support
+- Ready to proceed to handoff phase
+
+---
+
+## NEXT STEP
+
+Load: `./step-05a-handoff.md`

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

@@ -57,6 +57,50 @@ Include:
 
 ---
 
+### 1b. Cache Warming for Handoff & Deploy
+
+> **Performance Optimization:** Pre-load handoff templates and references to reduce redundant reads during handoff generation.
+> This step runs ONCE at start of step-05a, files retained through step-05b.
+
+```
+// Pre-load handoff & deploy references (Bucket 5)
+const handoffRefs = [
+  "~/.claude/skills/business-analyse/references/handoff-file-templates.md",
+  "~/.claude/skills/business-analyse/references/handoff-mappings.md",
+  "~/.claude/skills/business-analyse/references/deploy-data-build.md",
+  "~/.claude/skills/business-analyse/references/deploy-modes.md",
+  "~/.claude/skills/business-analyse/references/html-data-mapping.md"
+];
+
+for (const file of handoffRefs) {
+  read(file);  // Pre-load into cache
+}
+
+// Pre-load HTML template (large file, loaded once)
+read("~/.claude/skills/business-analyse/html/ba-interactive.html");
+
+Display: "✓ Cache warmed: handoff templates (139KB, 6 files)"
+Display: "  Expected token savings: ~3,000 tokens (handoff refs read 2× → 1×)"
+Display: "  Retention: through step-05b (deploy)"
+```
+
+**Rationale:**
+
+- Handoff templates are read 2× during step-05a + step-05b (without caching)
+- HTML template (85KB) is read once but benefits from explicit pre-load (faster deploy)
+- Token savings: ~3,000 tokens for handoff process
+- Cache retained until session end (needed for both handoff and deploy steps)
+
+**Why NOT loaded at step-00:**
+- Large files (139KB total), especially ba-interactive.html (85KB)
+- Only used at END of workflow (steps 05a, 05b)
+- Low re-use (1-2× each)
+- Loading at step-05a is more efficient (just-in-time caching)
+
+See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) § Bucket 5 for details.
+
+---
+
 ### 2. Implementation Strategy Choice (Multi-Module)
 
 **IF** more than 1 module defined in feature.json:

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
@@ -305,6 +305,27 @@ After writing the HTML file, verify:
    fi
    ```
 
+5. **EMBEDDED_ARTIFACTS wireframes must use renamed fields** (`format`/`content`, NOT `mockupFormat`/`mockup`)
+   ```bash
+   # Check that wireframe field rename was applied (mockup → content, mockupFormat → format)
+   if grep -q '"mockupFormat"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("EMBEDDED_ARTIFACTS wireframes still use 'mockupFormat' — must rename to 'format'")
+     BLOCKING_ERROR("See references/html-data-mapping.md for correct field mapping")
+   fi
+   if grep -q '"mockup":' "{output_path}/ba-interactive.html" | grep -v '"mockupNotes"'; then
+     # Note: "mockup" in EMBEDDED_ARTIFACTS = wrong, must be "content"
+     BLOCKING_ERROR("EMBEDDED_ARTIFACTS wireframes still use 'mockup' — must rename to 'content'")
+   fi
+   ```
+
+6. **EMBEDDED_ARTIFACTS wireframes must exist for ALL modules** (not empty `{}`)
+   ```bash
+   # Each module should have at least one wireframe with "format" and "content"
+   if ! grep -q '"format"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("No wireframe 'format' field found — EMBEDDED_ARTIFACTS wireframes not populated")
+   fi
+   ```
+
 **IF ANY CHECK FAILS → DO NOT PROCEED. Fix the data mapping and regenerate.**
 
 ---
@@ -339,7 +360,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
 
@@ -348,6 +374,20 @@ Effort:    {total_days} days ({total_hours} hours)
 
 ---
 
+## NEXT STEP
+
+**RECOMMENDED:** Load `steps/step-05c-ralph-readiness.md` to run validation gate before /ralph-loop.
+
+This validation ensures:
+- All module handoffs are complete
+- PRD files are structurally valid
+- Cross-module references are resolvable
+- No blocking issues before development
+
+User can skip validation and proceed directly to /ralph-loop, but validation is strongly recommended to catch issues early.
+
+---
+
 ## MODE SUPPORT & TROUBLESHOOTING
 
 See [references/deploy-modes.md](../references/deploy-modes.md) for: