docs(bmad): Add Hierarchical Subsystems (FR48) to PRD, Arch, Epics and Sprint

_bmad-output/planning-artifacts/architecture.md

@@ -283,6 +283,32 @@ impl Compressor<Disconnected> {
 - Extensible pour composants custom (e.g., Ejecteur de Robert)
 - AHRI 540 coefficients intégrés dans struct Compressor
 
+### Hierarchical Subsystems (MacroComponents)
+
+**Decision:** Wrapper Pattern matching the `Component` trait
+
+**Core Pattern:**
+```rust
+struct MacroComponent {
+    internal_system: System,
+    port_mapping: HashMap<PortId, InternalLocation>, /* e.g., Exposes 'Condenser Water In' */
+}
+
+impl Component for MacroComponent {
+    fn compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector) {
+        // Delegates or flattens computation to internal_system
+        self.internal_system.compute_residuals(state, residuals);
+    }
+    // ... maps external ports to internal boundary ports ...
+}
+```
+
+**Rationale:**
+- Allows users to build reusable blocks (like a full Chiller, Air Handling Unit)
+- Mimics Modelica/Simulink ecosystem composability
+- The global solver treats `MacroComponent` exactly like a basic Component, preserving zero-cost abstractions
+- `SystemState` flattening ensures equations are solved simultaneously globally, avoiding nested numerical solver delays.
+
 ### Fluid Properties Backend
 
 **Decision:** Trait abstraction with multiple backends
@@ -794,7 +820,7 @@ pub trait Solver {
 | Feature | FRs | Location |
 |---------|-----|----------|
 | Component Modeling | FR1-FR8 | `crates/components/src/` |
-| System Topology | FR9-FR13 | `crates/solver/src/system.rs` |
+| System Topology | FR9-FR13, FR48 | `crates/solver/src/system.rs` & `macro_component.rs` |
 | Solver Engine | FR14-FR21 | `crates/solver/src/strategies/` |
 | Inverse Control | FR22-FR24 | `crates/solver/src/inverse/` |
 | Fluid Properties | FR25-FR29 | `crates/fluids/src/` |

_bmad-output/planning-artifacts/epics.md

@@ -251,6 +251,7 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 | FR45 | Epic 7 | Inverse calibration (parameter estimation) |
 | FR46 | Epic 1 | Air Coils (EvaporatorCoil, CondenserCoil) |
 | FR47 | Epic 2 | Rich Thermodynamic State Abstraction |
+| FR48 | Epic 3 | Hierarchical Subsystems (MacroComponents) |
 
 ## Epic List
 
@@ -273,11 +274,11 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 ---
 
 ### Epic 3: System Topology (Graph)
-**Goal:** Enable component assembly via Ports and manage multi-circuits with thermal coupling.
+**Goal:** Enable component assembly via Ports and manage multi-circuits with thermal coupling, and support hierarchical subsystems.
 
-**Innovation:** Multi-fluid directed graph in a single model.
+**Innovation:** Multi-fluid directed graph in a single model, with natively supported hierarchical sub-blocks.
 
-**FRs covered:** FR9, FR10, FR11, FR12, FR13
+**FRs covered:** FR9, FR10, FR11, FR12, FR13, FR48
 
 ---
 
@@ -664,6 +665,23 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 
 ---
 
+### Story 3.6: Hierarchical Subsystems (MacroComponents)
+
+**As a** system designer,
+**I want** to encapsulate a complete system (e.g., a Chiller with compressor, condenser, valve, evaporator) into a single reusable block,
+**So that** I can compose larger models (like buildings or parallel chiller plants) using these blocks, just like in Modelica.
+
+**Acceptance Criteria:**
+
+**Given** a fully defined `System` with internal components and connections
+**When** I wrap it in a `MacroComponent`
+**Then** I can expose specific internal ports (e.g., Evaporator Water In/Out, Condenser Water In/Out) as the `MacroComponent`'s external ports
+**And** this `MacroComponent` implements the `Component` trait
+**And** I can add it to a higher-level `System` just like any regular component
+**And** the global solver correctly flattens or delegates the residual and jacobian computations down to the nested components.
+
+---
+
 ## Epic 4: Intelligent Solver Engine
 
 ### Story 4.1: Solver Trait Abstraction

_bmad-output/planning-artifacts/prd.md

@@ -460,6 +460,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
 - **FR11** : Le système supporte les connexions entre circuits (couplage thermique)
 - **FR12** : Le système peut résoudre les N circuits simultanément ou séquentiellement
 - **FR13** : Le système gère mathématiquement les branches à débit nul sans division par zéro
+- **FR48** : Le système permet de définir des sous-systèmes hiérarchiques (MacroComponents/Blocks) comme dans Modelica, encapsulant une topologie interne et exposant uniquement des ports (ex: raccorder deux Chillers en parallèle).
 
 ### 3. Résolution du Système (Solver)
 
@@ -552,7 +553,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
 
 **Workflow :** BMAD Create PRD  
 **Steps Completed :** 12/12  
-**Total FRs :** 47  
+**Total FRs :** 48  
 **Total NFRs :** 17  
 **Personas :** 5  
 **Innovations :** 5