@atlashub/smartstack-cli 3.9.0 → 3.10.0

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

@@ -113,6 +113,172 @@ Identify shared lookup/reference tables:
 }
 ```
 
+**2e. Cross-Module Reference Validation (ENHANCED)**
+
+> **CRITICAL:** Verify ALL cross-module entity references are resolvable.
+> **Purpose:** Prevent broken FK references and runtime errors in ralph-loop.
+
+**Process:**
+
+1. **Build Entity Registry:**
+   ```javascript
+   const entityRegistry = {};
+   for (const module of completedModules) {
+     entityRegistry[module.code] = {
+       entities: module.analysis.entities.map(e => ({
+         name: e.name,
+         attributes: e.attributes.map(a => a.name),
+         pk: e.attributes.find(a => a.name === "Id" || a.unique)?.name || "Id"
+       }))
+     };
+   }
+   ```
+
+2. **Extract Cross-Module References:**
+
+   For EACH module, scan all entity relationships:
+   ```javascript
+   for (const entity of module.analysis.entities) {
+     for (const rel of entity.relationships) {
+       // Detect cross-module reference
+       if (rel.target.includes(".")) {
+         // Format: "ModuleName.EntityName.FieldName" or "ModuleName.EntityName"
+         const [targetModule, targetEntity, targetField] = rel.target.split(".");
+
+         // Validate: target module exists
+         if (!entityRegistry[targetModule]) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent module "${targetModule}"`);
+         }
+
+         // Validate: target entity exists in target module
+         const targetModuleEntities = entityRegistry[targetModule].entities;
+         const resolvedEntity = targetModuleEntities.find(e => e.name === targetEntity);
+         if (!resolvedEntity) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent entity "${targetEntity}" in module "${targetModule}"`);
+         }
+
+         // Validate: target field exists (if specified)
+         if (targetField && !resolvedEntity.attributes.includes(targetField)) {
+           BLOCKING_ERROR(`Module ${module.code}: Entity ${entity.name} references non-existent field "${targetField}" on "${targetModule}.${targetEntity}"`);
+         }
+
+         // Record valid reference
+         crossModuleReferences.push({
+           sourceModule: module.code,
+           sourceEntity: entity.name,
+           sourceField: rel.sourceField || `${targetEntity}Id`,
+           targetModule,
+           targetEntity,
+           targetField: targetField || resolvedEntity.pk,
+           type: rel.type,
+           cardinality: rel.cardinality || "N:1",
+           status: "RESOLVED"
+         });
+       }
+     }
+   }
+   ```
+
+3. **Validate Dependency Graph Alignment:**
+
+   ```javascript
+   // For each cross-module reference, verify dependency edge exists
+   for (const ref of crossModuleReferences) {
+     const dependencyExists = dependencyGraph.edges.find(edge =>
+       edge.from === ref.sourceModule && edge.to === ref.targetModule
+     );
+
+     if (!dependencyExists) {
+       WARNING(`Dependency missing: ${ref.sourceModule} → ${ref.targetModule}`);
+       WARNING(`Reason: ${ref.sourceEntity}.${ref.sourceField} references ${ref.targetModule}.${ref.targetEntity}`);
+
+       // Auto-fix: add missing dependency edge
+       dependencyGraph.edges.push({
+         from: ref.sourceModule,
+         to: ref.targetModule,
+         type: "FK",
+         reason: `${ref.sourceEntity}.${ref.sourceField} → ${ref.targetEntity}`
+       });
+
+       // Recalculate topological order
+       topologicalOrder = calculateTopologicalOrder(dependencyGraph);
+     }
+   }
+   ```
+
+4. **Display Cross-Module Reference Map:**
+
+   ```
+   ═══════════════════════════════════════════════════════════════
+     CROSS-MODULE REFERENCES VALIDATED
+   ═══════════════════════════════════════════════════════════════
+
+   | Source Module | Source Entity | Target | Type | Status |
+   |---------------|---------------|--------|------|--------|
+   | TimeTracking | TimeEntry | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+   | LeaveManagement | LeaveRequest | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+   | AbsenceManagement | Absence | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+   | Reporting | ProjectReport | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+
+   Total: {count} cross-module references
+   All references RESOLVED ✓
+   ═══════════════════════════════════════════════════════════════
+   ```
+
+5. **Detect Circular Dependencies:**
+
+   ```javascript
+   const cycles = detectCycles(dependencyGraph);
+
+   if (cycles.length > 0) {
+     BLOCKING_ERROR("Circular dependencies detected:");
+     for (const cycle of cycles) {
+       ERROR(`  ${cycle.join(" → ")}`);
+     }
+
+     ACTIONS:
+     1. Review module dependencies
+     2. Break cycles by:
+        - Moving shared entities to a separate "Core" module
+        - Using event-driven communication instead of FK
+        - Removing unnecessary dependencies
+     3. Re-run step-02 decomposition with fixed dependencies
+
+     STOP - DO NOT PROCEED TO HANDOFF
+   }
+   ```
+
+6. **Store Cross-Module Interaction Data:**
+
+   ```javascript
+   ba-writer.enrichSection({
+     featureId: {feature_id},
+     section: "consolidation",
+     data: {
+       crossModuleInteractions: crossModuleReferences.map(ref => ({
+         fromModule: ref.sourceModule,
+         toModule: ref.targetModule,
+         interactionType: "FK_REFERENCE",
+         description: `${ref.sourceEntity}.${ref.sourceField} → ${ref.targetModule}.${ref.targetEntity}.${ref.targetField}`,
+         entities: [ref.sourceEntity, ref.targetEntity],
+         cardinality: ref.cardinality,
+         status: ref.status
+       }))
+     }
+   });
+   ```
+
+**Success Criteria:**
+- ✓ All cross-module references resolved
+- ✓ Dependency graph aligned with actual references
+- ✓ No circular dependencies
+- ✓ Topological order valid
+
+**Failure Handling:**
+- BLOCKING errors for unresolved references
+- Auto-fix missing dependency edges (with warning)
+- Manual intervention required for circular dependencies
+
 ### 3. Permission Coherence
 
 > **All modules MUST use the same application-level roles.**

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
@@ -339,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
 
@@ -348,6 +353,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: