Complete Story 0.2 phantom-gradient regularization standard.

Add analytic derivatives and C1 tests for smooth_max/min/clamp, document epsilon/width guidance, and declare flow_regularization as the HX reference pattern without changing component physics.

Co-authored-by: Cursor <cursoragent@cursor.com>

_bmad-output/implementation-artifacts/0-2-phantom-gradient-regularization-standard.md

@@ -0,0 +1,285 @@
+---
+story_key: 0-2-phantom-gradient-regularization-standard
+epic: 0
+story: 2
+source: _bmad-output/planning-artifacts/epics-solver-hp.md
+baseline_commit: f88cd7f7d83c8c25bf8d4262742fb9736c3bf7c7
+depends_on: 0-1-jacobian-killing-pattern-audit-fd-test-harness
+---
+
+# Story 0.2: Phantom-Gradient Regularization Standard
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Ultimate context engine analysis completed - comprehensive developer guide created -->
+
+## Story
+
+As a component developer,
+I want a standardized C¹ regularization toolkit (smooth max/min/clamp with documented ε) generalizing the existing `flow_regularization.rs` pattern,
+so that fixes are uniform and derivative-safe instead of ad-hoc.
+
+## Acceptance Criteria
+
+1. **Core C¹ toolkit is complete, tested, and derivative-safe.**
+   - **Given** the `entropyk-core` crate
+   - **When** the toolkit lands (or is completed if already present)
+   - **Then** `smooth_max` / `smooth_min` / `smooth_clamp` (C¹ or smoother, parameterized sharpness/width) are available alongside existing `smooth_abs`, with **derivative-continuity unit tests**
+   - **And** ε / width selection guidance is documented (physical scale of the blended region)
+
+2. **`flow_regularization.rs` relationship is resolved without physics churn.**
+   - **Given** the existing `crates/components/src/heat_exchanger/flow_regularization.rs`
+   - **When** reviewed
+   - **Then** it is either unified into the toolkit **or** documented as the **reference implementation** for mass-flow activity / zero-flow blending
+   - **And** no existing component behavior changes in this story (**toolkit + docs only**)
+
+## Tasks / Subtasks
+
+- [x] **Task 1: Inventory what already exists — do not reinvent** (AC: #1, #2)
+  - [x] 1.1 Confirm primitives in `crates/core/src/smoothing.rs`: `smooth_max`, `smooth_min`, `smooth_abs` (+ derivative), `smooth_clamp`, plus `smoothstep` / `cubic_blend` family.
+  - [x] 1.2 Confirm HX-specific adapters in `flow_regularization.rs` already call `smooth_abs` — keep them in `entropyk-components` (domain-specific, not core).
+  - [x] 1.3 Gap check (expected at story creation):
+    | Gap | Expected action |
+    |---|---|
+    | No public `smooth_clamp_derivative` | **Add** analytic ∂/∂x (+ FD unit test) — required by Stories 0.3/0.4 Jacobian paths |
+    | `smooth_max` / `smooth_min` derivatives only inline in tests | **Add** public `smooth_max_da` / `smooth_min_da` (or named `*_derivative` w.r.t. first arg) + FD tests |
+    | No dedicated C¹ join tests for `smooth_clamp` | **Add** FD slope continuity at the four junctions (`lo`, `lo+width`, `hi-width`, `hi`) |
+    | No general ε/width guidance doc | **Add** rustdoc module section + short markdown standard (see Task 3) |
+    | `flow_regularization` not formally declared “reference” | **Document** — do **not** move into core |
+
+- [x] **Task 2: Complete the toolkit APIs in `entropyk-core`** (AC: #1)
+  - [x] 2.1 Add analytic derivatives needed by consumers:
+    - `smooth_clamp_derivative(x, lo, hi, width) -> f64`
+    - `smooth_max` / `smooth_min` first-arg (or both-arg) derivatives — match existing formulas already verified in unit tests
+  - [x] 2.2 Keep APIs pure `f64`, `#[inline]`, zero-alloc, no new crate deps.
+  - [x] 2.3 Guard invalid parameters without panic: `width <= 0`, `hi < lo`, `k <= 0`, `eps <= 0` — document degenerate behavior (hard clamp / hard max / hard abs) and cover with tests. Prefer non-panicking fallbacks consistent with existing `normalize` zero-width handling.
+  - [x] 2.4 Re-export path unchanged: `entropyk_core::smoothing::*` via existing `pub mod smoothing` in `crates/core/src/lib.rs`. No facade/`entropyk` re-export required unless already present.
+
+- [x] **Task 3: Document the Phantom-Gradient Regularization Standard** (AC: #1, #2)
+  - [x] 3.1 Add a focused doc (preferred path): `docs/components/phantom-gradient-regularization.md` **OR** expand `docs/components/flow-regularization.md` with a top-level “Standard” section that links to `smoothing.rs`. Prefer a **dedicated** short doc if the flow doc stays HX-specific.
+  - [x] 3.2 Document **ε / width selection guidance** with physical meaning:
+
+    | Primitive | Parameter | Meaning | Rule of thumb |
+    |---|---|---|---|
+    | `smooth_abs(x, eps)` | `eps` | value at `x=0`; blend half-width | ~1% of characteristic \|x\| scale, or smaller if kink is far from operating region |
+    | `smooth_max` / `smooth_min` | `k` | overshoot at equality = `k/2` | `k` ≪ \|a−b\| in the region you care about; never so large it shifts equilibrium |
+    | `smooth_clamp` | `width` | transition length at each bound | `width ≤ (hi−lo)/2`; pick so Newton steps near bound still see ∂/∂x ∈ (0,1) over a physically small band (e.g. opening width `1e-3`…`1e-2` for [0,1]) |
+    | `flow_activity` | `m_eps` | mass-flow activity scale | keep `DEFAULT_M_EPS_KG_S = 1e-4` as HX reference; do not change the constant in this story |
+
+  - [x] 3.3 Explicit decision (write it into the doc):
+    - **Canonical general toolkit:** `entropyk_core::smoothing`
+    - **Reference specialized pattern:** `heat_exchanger::flow_regularization` (activity / duty / transport blend) — **not** duplicated into core
+    - **Banned in residual/Jacobian paths on Newton unknowns:** bare `.clamp(` / hard `.max(0)` / early `Ok(0.0)` that zeros informative derivatives (fixes deferred to 0.3/0.4)
+  - [x] 3.4 Cross-link from `docs/audits/jacobian-killing-pattern-audit.md` deferred table: mark Story 0.2 standard as landed when done (update the “deferred” row only — do not re-audit).
+  - [x] 3.5 English technical docs; keep code comments English.
+
+- [x] **Task 4: Derivative-continuity unit tests** (AC: #1)
+  - [x] 4.1 Extend `crates/core/src/smoothing.rs` `#[cfg(test)]`:
+    - FD match for `smooth_clamp_derivative` across interior, both ramps, and far exterior.
+    - Slope continuity of `smooth_clamp` across junctions (sample FD slope just inside/outside joins; assert small jump).
+    - FD match for new `smooth_max` / `smooth_min` derivative helpers.
+  - [x] 4.2 Do **not** require `check_jacobian_health` for this story — that harness is component-level (Story 0.1). Core unit FD helpers already in `smoothing.rs` tests are the right layer.
+  - [x] 4.3 Keep using relative/absolute tolerances consistent with existing tests (`~1e-5` FD match for analytic derivatives).
+
+- [x] **Task 5: Hard scope boundary — toolkit only** (AC: #2)
+  - [x] 5.1 **DO NOT** modify production residual/Jacobian physics in:
+    - `valve_flow.rs`
+    - `isenthalpic_expansion_valve.rs`
+    - `heat_exchanger/two_phase_dp.rs`
+    - `heat_exchanger/condenser.rs`
+    - any other component clamp site
+  - [x] 5.2 **DO NOT** change `DEFAULT_M_EPS_KG_S` / `DEFAULT_M_SCALE_KG_S` or HX residual formulas.
+  - [x] 5.3 **DO NOT** change `n_equations()` anywhere.
+  - [x] 5.4 Allowed touch list is essentially: `smoothing.rs` (+ tests), docs under `docs/components/` and a small audit cross-link, optional rustdoc polish on `flow_regularization.rs` module docs pointing to the standard.
+
+- [x] **Task 6: Validation** (AC: #1, #2)
+  - [x] 6.1 `cargo test -p entropyk-core` green (includes new smoothing tests / doctests).
+  - [x] 6.2 `cargo test -p entropyk-components` green — proves no accidental physics regressions from doc-only / non-touch policy.
+  - [x] 6.3 Diff review: production component residual files should show **zero** physics diffs attributable to this story.
+
+## Dev Notes
+
+### Context & Positioning
+
+- **Epic 0** — Physical Regularization & Jacobian Health. Prerequisite for primary KPI **NFR11** (≥95% first-try convergence). Robustness before speed.
+- **FR19** — informative non-zero C¹ Jacobians across the full physical domain via standardized phantom-gradient regularization.
+- **FR20** — FD harness (already delivered in Story 0.1); CI gate is Story **0.5**.
+- **This story owns the standard + toolkit completeness.** Stories **0.3** (valve/EXV) and **0.4** (HX quality/actuators/MSH) **consume** `smooth_clamp` / `smooth_max` / `smooth_abs` to fix P0 killers.
+- Source of truth for solver-HP scope: `_bmad-output/planning-artifacts/epics-solver-hp.md` (supersedes legacy PRD/architecture for this epic).
+
+### CRITICAL: Toolkit already largely exists — complete, don't recreate
+
+```text
+CANONICAL LOCATION (reuse):
+  crates/core/src/smoothing.rs
+    smooth_max(a, b, k)
+    smooth_min(a, b, k)
+    smooth_abs(x, eps) + smooth_abs_derivative
+    smooth_clamp(x, lo, hi, width)          // value exists; derivative API missing
+    smoothstep / smootherstep / cubic_blend / quintic_blend (+ derivatives)
+
+HX REFERENCE PATTERN (keep in components — do not move to core):
+  crates/components/src/heat_exchanger/flow_regularization.rs
+    flow_activity / effective_duty / blend_transport_residual
+    uses entropyk_core::smoothing::smooth_abs
+
+VERIFICATION HARNESS (Story 0.1 — do not reimplement):
+  crates/components/src/jacobian_fd.rs
+  docs/audits/jacobian-killing-pattern-audit.md
+```
+
+**Anti-patterns to prevent:**
+- Creating a second `smoothing` / `regularization` module under `components/`
+- Copy-pasting `tanh` / `LogSumExp` soft-max when `smooth_max` already exists
+- “Unifying” by moving `flow_activity` into core (wrong layer — HX residual units / m_scale)
+- Replacing component clamps in this story (that is 0.3/0.4)
+- Calling `JacobianMatrix::numerical` (forward FD Newton fallback) for anything here
+
+### Architecture Compliance
+
+- **Exact analytic Jacobians** (`project-context.md` / AGENTS.md): production assembly stays analytic; FD only in tests.
+- **C¹ residual policy:** any clamp/branch on a Newton unknown must use toolkit primitives so ∂R/∂x stays informative and continuous.
+- **DoF invariant:** regularization never changes `n_equations()`.
+- **Zero panic** in library code; public APIs need rustdoc + examples.
+- Hot path: pure functions, no allocation, no dynamic dispatch.
+- Layering: `entropyk-core` must not depend on `entropyk-components`.
+
+### Technical Requirements
+
+- **Language:** Rust edition 2021, crate `entropyk-core` (+ docs only elsewhere).
+- **Deps:** no new crates. Existing workspace/`approx` patterns for tests as already used in core.
+- **`smooth_clamp` construction (already implemented — preserve semantics):**
+  ```rust
+  // Lower ramp then upper ramp via smoothstep — output always in [lo, hi], C¹ joins.
+  let lower = lo + (x - lo) * smoothstep(lo, lo + width, x);
+  hi + (lower - hi) * smoothstep(hi, hi - width, lower)
+  ```
+  Derivative must follow the chain rule through both ramps; unit-test against central FD.
+- **`smooth_max` analytic ∂/∂a (already proven in tests):**
+  ```text
+  0.5 * (1 + (a-b) / sqrt((a-b)² + k²))
+  ```
+- Prefer exporting named derivative functions over forcing callers to re-derive formulas (Story 0.3 will clamp EXV opening in both residual and Jacobian).
+
+### Current toolkit gaps (verified 2026-07-18)
+
+| Item | Status |
+|---|---|
+| `smooth_max` / `smooth_min` / `smooth_abs` / `smooth_clamp` values | Present |
+| `smooth_abs_derivative` | Present |
+| Public `smooth_clamp_derivative` | **Missing — add** |
+| Public `smooth_max`/`smooth_min` derivatives | **Missing — add** (formulas exist in tests) |
+| FD C¹ junction tests for `smooth_clamp` | **Missing — add** (current test only saturates/bounds) |
+| General ε/width selection doc | **Missing — add** (`flow-regularization.md` covers HX m_eps only) |
+| Formal “reference vs unify” decision for `flow_regularization` | **Missing — document as reference** |
+
+### Downstream contract (write APIs for these consumers)
+
+| Future story | Will need |
+|---|---|
+| 0.3 Valve / EXV | `smooth_clamp` + derivative for opening ∈ [0,1]; smooth ΔP blend (may use `smooth_max`/`smooth_abs`) |
+| 0.4 HX | `smooth_clamp` for quality / fan / flood; reuse `flow_regularization` patterns |
+| 0.5 CI gate | Assumes toolkit stable; no API churn after this story |
+
+Recommended default widths for docs/examples (not applied to components here):
+- Opening / quality ∈ [0,1]: `width = 1e-3` … `1e-2`
+- Fan actuator ∈ [0, 1.5]: `width ≈ 1e-2`
+- Flood level ∈ [0, 0.98]: `width ≈ 1e-2` (keep `width ≤ (hi−lo)/2`)
+
+### File Structure Requirements
+
+| File | Action |
+|---|---|
+| `crates/core/src/smoothing.rs` | **UPDATE** — add missing derivative APIs + C¹/FD tests; expand module rustdoc with ε guidance |
+| `crates/core/src/lib.rs` | **UPDATE only if** export changes needed (likely unchanged) |
+| `docs/components/phantom-gradient-regularization.md` | **CREATE** (preferred) — standard + ε table + reference decision |
+| `docs/components/flow-regularization.md` | **UPDATE** — link to standard; declare HX module as specialized reference |
+| `crates/components/src/heat_exchanger/flow_regularization.rs` | **UPDATE docs only** (optional module-doc pointer) — **no formula changes** |
+| `docs/audits/jacobian-killing-pattern-audit.md` | **UPDATE** — mark 0.2 standard row as done / link to new doc |
+| `valve_flow.rs` / EXV / `two_phase_dp.rs` / `condenser.rs` | **DO NOT CHANGE** physics |
+
+### Testing Requirements
+
+- Unit tests live next to primitives in `smoothing.rs` (existing pattern with local `fd` helper).
+- Must prove:
+  1. Analytic derivatives match central FD.
+  2. `smooth_clamp` slope is continuous at bound joins (C¹).
+  3. Degenerate parameters do not panic.
+- Run:
+  ```bash
+  cargo test -p entropyk-core
+  cargo test -p entropyk-components
+  ```
+- Do not flip Story 0.1 detection tests to “must be clean” — killers remain until 0.3/0.4.
+
+### Previous Story Intelligence
+
+From **`0-1-jacobian-killing-pattern-audit-fd-test-harness`** (status: review):
+
+- Shared harness: `jacobian_fd::check_jacobian_health` — central FD, flags analytic≈0 while FD informative.
+- Audit catalogue confirms P0 killers; maps EXV opening clamps → **Story 0.2 `smooth_clamp` as the intended replacement API**, applied later in **0.3**.
+- Explicitly noted: `smooth_*` already in core — Story 0.2 is **unify/document/ε-guidance**, not greenfield.
+- Scope discipline that worked: observe/fix tooling without changing production physics. **Reuse that discipline here.**
+- Epic typo note still valid for 0.3: only `valve_mass_flow_dp_up` exists (no `dp_down`).
+- Numbering collision: `0-1-fix-failing-tests` is a **different**, already-done DoF story — ignore for this work.
+
+### Git Intelligence
+
+- Recent commits are FMI/docs-heavy (`f88cd7f` baseline). Smoothing + `flow_regularization` landed earlier (`3358b74` lineage) — brownfield completion, not invention.
+- No commit yet closes the ε-standard doc or `smooth_clamp_derivative` gap.
+
+### Project Context Reference
+
+- `project-context.md` / `AGENTS.md`: exact Jacobians; Component trait; English technical docs; zero panic.
+- Epic/FRs: `_bmad-output/planning-artifacts/epics-solver-hp.md` — Epic 0, Story 0.2, FR19, FR20, NFR11.
+- Supporting: `docs/audits/jacobian-killing-pattern-audit.md`, `docs/components/flow-regularization.md`, `docs/adr/ADR-0001-multi-circuit-heat-exchanger-architecture.md` (smooth_abs / no hard zero-flow branch).
+
+### References
+
+- [Source: `_bmad-output/planning-artifacts/epics-solver-hp.md` — Epic 0, Story 0.2, FR19, NFR11]
+- [Source: `crates/core/src/smoothing.rs` — existing C¹/C∞ toolkit]
+- [Source: `crates/components/src/heat_exchanger/flow_regularization.rs` — HX reference pattern]
+- [Source: `docs/components/flow-regularization.md` — m_eps defaults, DoF rule]
+- [Source: `docs/audits/jacobian-killing-pattern-audit.md` — deferred 0.2 work + P0 map]
+- [Source: `_bmad-output/implementation-artifacts/0-1-jacobian-killing-pattern-audit-fd-test-harness.md` — prior story learnings]
+- [Source: `crates/components/src/jacobian_fd.rs` — verification harness (do not reimplement)]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Cursor Grok 4.5 (bmad-dev-story)
+
+### Debug Log References
+
+- `cargo test -p entropyk-core` — 164 lib + 41 doctests passed (incl. new smoothing derivative / C¹ / degenerate tests)
+- `cargo test -p entropyk-components` — lib 910 passed; jacobian_health_sweep 8 passed; doctests 70 passed
+- Story-owned production touch limited to `flow_regularization.rs` module docs (+4 lines); no clamp→smooth physics changes
+
+### Completion Notes List
+
+- Added public `smooth_max_derivative`, `smooth_min_derivative`, `smooth_clamp_derivative` with chain-rule / analytic formulas; FD-matched in unit tests.
+- Documented ε/width guidance in module rustdoc and `docs/components/phantom-gradient-regularization.md`.
+- Declared `flow_regularization` as HX **reference** pattern (not moved to core); linked from flow-regularization.md + audit deferred table (0.2 landed).
+- Degenerate parameters (`k/eps/width <= 0`, inverted bounds) fall back to hard max/min/abs/clamp without panic.
+- Scope held: valve/EXV/HX clamp physics untouched for Stories 0.3/0.4.
+
+### File List
+
+- `crates/core/src/smoothing.rs` (UPDATE)
+- `crates/components/src/heat_exchanger/flow_regularization.rs` (UPDATE — module docs only)
+- `docs/components/phantom-gradient-regularization.md` (NEW)
+- `docs/components/flow-regularization.md` (UPDATE)
+- `docs/audits/jacobian-killing-pattern-audit.md` (UPDATE — deferred table)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (UPDATE — story status)
+- `_bmad-output/implementation-artifacts/0-2-phantom-gradient-regularization-standard.md` (UPDATE — this file)
+
+### Change Log
+
+- 2026-07-18: Completed phantom-gradient regularization standard — derivative APIs, C¹ tests, ε docs, flow_regularization reference decision; status → review
+
+## Story Completion Status
+
+- Status: **review**
+- Note: All tasks complete; ACs satisfied; ready for `code-review`

_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -1,308 +1,106 @@
-# Sprint Status - Entropyk
-# Last Updated: 2026-04-28 (story 20-1 implementation)
-# Project: Entropyk
-# Project Key: NOKEY
-# Tracking System: file-system
-# Story Location: _bmad-output/implementation-artifacts
-#
-# ORGANIZED BY BUSINESS PILLARS (not historical epics)
-# Priority order: P4 (Solver) → P5 (Interfaces) → P6 (Applications)
-# See: _bmad-output/planning-artifacts/pillars.md for full pillar definitions
-# See: _bmad-output/planning-artifacts/epic-restructuring.md for migration rationale
-#
+# Sprint Status
+# Generated by bmad-create-story workflow
+
 # STATUS DEFINITIONS:
 # ==================
+# Epic Status:
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
 # Story Status:
 #   - backlog: Story only exists in epic file
-#   - ready-for-dev: Story file created in stories folder
+#   - ready-for-dev: Story file created, ready for development
 #   - in-progress: Developer actively working on implementation
-#   - review: Ready for code review (via Dev's code-review workflow)
+#   - review: Implementation complete, ready for review
 #   - done: Story completed
 #
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - done: Retrospective has been completed
+
 # WORKFLOW NOTES:
 # ===============
-# - File is read top-to-bottom by BMAD: first matching status = next action
-# - epic-X keys are kept for BMAD workflow compatibility (do not remove)
-# - Stories are grouped by pillar; within each pillar: active → backlog → done
-# - SM creates next story after previous one is 'done' to incorporate learnings
-# - Dev moves story to 'review', then runs code-review (fresh context recommended)
+# - Mark epic as 'in-progress' when starting work on its first story
+# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
 
-generated: 2026-02-22
+generated: 2026-07-18T12:51:31Z
+last_updated: 2026-07-18T16:30:00Z
 project: Entropyk
-project_key: NOKEY
+project_key: ENTROPYK
 tracking_system: file-system
-story_location: _bmad-output/implementation-artifacts
+story_location: "{project-root}/_bmad-output/implementation-artifacts"
 
 development_status:
-  # ═══════════════════════════════════════════════════════════════
-  # EPIC STATUS (required by BMAD — epic-X keys must stay here)
-  # ═══════════════════════════════════════════════════════════════
-  epic-1: done
-  epic-2: done
-  epic-3: done
-  epic-4: done
-  epic-5: in-progress
-  epic-6: in-progress
-  epic-7: in-progress
-  epic-8: done
-  epic-9: done
-  epic-10: in-progress
-  epic-11: in-progress
-  epic-12: in-progress
-  epic-13: in-progress
-  epic-14: in-progress
-  epic-15: in-progress
-  epic-16: backlog
-  epic-17: backlog
-  epic-18: backlog
-  epic-19: in-progress
-  epic-20: in-progress
-
-  # ═══════════════════════════════════════════════════════════════
-  # P1: FOUNDATION / Fondations — 14/14 DONE
-  # Types, traits, ports, graph topology, state machine
-  # ═══════════════════════════════════════════════════════════════
-  1-1-component-trait-definition: done
-  1-2-physical-types-newtype-pattern: done
-  1-3-port-and-connection-system: done
-  1-7-component-state-machine: done
-  3-1-system-graph-structure: done
-  3-2-port-compatibility-validation: done
-  3-3-multi-circuit-machine-definition: done
-  3-4-thermal-coupling-between-circuits: done
-  3-5-zero-flow-branch-handling: done
-  3-6-hierarchical-subsystems-macrocomponents: done
-  9-1-circuitid-type-unification: done
-  9-2-fluidid-type-unification: done
-  9-7-solver-refactoring-split-files: done
-  9-8-systemstate-dedicated-struct: done
-
-  # ═══════════════════════════════════════════════════════════════
-  # P2: REAL COMPONENTS / Composants — 30/39 (77%)
-  # All thermodynamic components, vendor data parsers, boundary conditions
-  # ═══════════════════════════════════════════════════════════════
-  1-4-compressor-component-ahri-540: done
-  1-5-generic-heat-exchanger-framework: done
-  1-6-expansion-valve-component: done
-  1-8-auxiliary-transport-components: done
-  1-9-air-coils-evaporatorcoil-condensercoil-post-mvp: done
-  1-10-pipe-helpers-for-water-and-refrigerant: done
-  1-11-flow-junctions-flowsplitter-flowmerger: done
-  1-12-boundary-conditions-flowsource-flowsink: done
-  8-1-fluid-backend-component-integration: done
-  10-1-new-physical-types: done
-  10-2-refrigerant-source-sink: done
-  10-3-brine-source-sink: done
-  10-4-air-source-sink: done
-  10-5-migration-deprecation: done
-  10-6-python-bindings-update: done
-  11-1-node-passive-probe: done
-  11-2-drum-recirculation-drum: done
-  11-3-floodedevaporator: done
-  11-4-floodedcondenser: done
-  11-5-bphxexchanger-base: done
-  11-6-bphxevaporator: done
-  11-7-bphxcondenser: done
-  11-8-correlationselector: done
-  11-9-movingboundaryhx-zone-discretization: done
-  11-10-movingboundaryhx-cache-optimization: done
-  11-11-vendorbackend-trait: done
-  11-12-copeland-parser: done
-  11-13-swep-parser: done
-  11-14-danfoss-parser: done
-  11-15-bitzer-parser: done
-
-  # --- Backlog: P2 Extended (from legacy integration) ---
-  20-1-generalized-performance-curve-engine: done  # P2-31
-  20-3-reversing-valve-four-way-component: backlog          # P2-32
-  20-4-high-pressure-control-valve: backlog                 # P2-33
-  20-5-compressor-parallel-units-vfd: backlog               # P2-34
-  20-6-multi-zone-heat-exchanger-component: backlog         # P2-35
-  20-7-additional-plate-hx-correlations: backlog            # P2-36
-  20-8-equipment-catalog-system: backlog                    # P2-37
-  20-9-fouling-encrustation-resistance: backlog             # P2-38
-  20-10-vendor-backend-verification-modernization: backlog  # P2-39
-
-  # ═══════════════════════════════════════════════════════════════
-  # P3: FLUID PROPERTIES / Fluides — 8/9 (89%)
-  # CoolProp, tabular backend, cache, mixtures, CO2 damping, psychrometrics
-  # ═══════════════════════════════════════════════════════════════
-  2-1-fluid-backend-trait-abstraction: done
-  2-2-coolprop-integration-sys-crate: done
-  2-3-tabular-interpolation-backend: done
-  2-4-lru-cache-for-fluid-properties: done
-  2-5-mixture-and-temperature-glide-support: done
-  2-6-critical-point-damping-co2-r744: done
-  2-7-incompressible-fluids-support: done
-  2-8-rich-thermodynamic-state-abstraction: done
-
-  # --- Backlog ---
-  20-2-complete-psychrometric-module: backlog  # P3-09
-
-  # ═══════════════════════════════════════════════════════════════
-  # P4: SIMULATION & SOLVER — 22/26 (85%)
-  # >>> PRIORITY PILLAR — must complete before P5/P6 expansion
-  # ═══════════════════════════════════════════════════════════════
-
-  # --- In Progress ---
-  5-4-multi-variable-control: done
-  7-5-json-serialization-deserialization: done
-
-  # --- Review ---
-  5-6-control-variable-step-clipping-in-solver: review
-
-  # --- Ready for Dev ---
-  7-6-component-calibration-parameters-calib: done
-
-  # --- Backlog ---
-  19-1-inverse-calibration: in-progress  # P4-25: solver-level algorithm
-
-  # --- Backlog: Multi-point calibration ---
-  calib-map-multi-point-calibration: backlog  # P4-26
-
-  # --- Done ---
-  4-1-solver-trait-abstraction: done
-  4-2-newton-raphson-implementation: done
-  4-3-sequential-substitution-picard-implementation: done
-  4-4-intelligent-fallback-strategy: done
-  4-5-time-budgeted-solving: done
-  4-6-smart-initialization-heuristic: done
-  4-7-convergence-criteria-validation: done
-  4-8-jacobian-freezing-optimization: done
-  5-1-constraint-definition-framework: done
-  5-2-bounded-control-variables: done
-  5-3-residual-embedding-for-inverse-control: done
-  5-5-swappable-calibration-variables-inverse-calibration-one-shot: done
-  7-1-mass-balance-validation: done
-  7-2-energy-balance-validation: done
-  7-3-traceability-metadata: done
-  7-4-debug-verbose-mode: done
-  9-3-expansionvalve-energy-methods: done
-  9-4-flowsourceflowsink-energy-methods: done
-  9-5-flowsplitterflowmerger-energy-methods: done
-  9-6-energy-validation-logging-improvement: done
-
-  # ═══════════════════════════════════════════════════════════════
-  # P5: USER INTERFACES — 30/59 (51%)
-  # CLI, Python, C FFI, WASM, Rust API (SystemBuilder)
-  # ═══════════════════════════════════════════════════════════════
-
-  # --- Review ---
-  6-4-webassembly-compilation: in-progress
-  15-4-cli-bphx-exchangers: review
-
-  # --- Ready for Dev ---
-  13-5-simulation-result-structured: done
-  13-6-json-config-serialize: done
-  13-7-fluid-backend-assignment: done
-
-  # --- Backlog: CLI Component Coverage ---
-  15-5-cli-flooded-condenser: backlog
-  15-6-cli-drum: backlog
-  15-7-cli-economizer: backlog
-  15-8-cli-flow-splitter-merger: backlog
-  15-10-cli-real-pipe: backlog
-  15-11-cli-real-fan: backlog
-  15-12-cli-bypass-valve: backlog
-  15-13-cli-node-probe: backlog
-
-  # --- Backlog: CLI Features & Output ---
-  16-1-cli-calib-config: backlog
-  16-2-cli-structured-output: backlog
-  16-3-cli-multi-fluid: backlog
-  16-4-cli-vendor-import: backlog
-  16-5-cli-json-schema: backlog
-  16-6-cli-machine-templates: backlog
-  16-7-cli-parameter-sweep: backlog
-
-  # --- Backlog: Python Parity ---
-  17-1-python-fix-pump: backlog
-  17-2-python-fix-fan: backlog
-  17-3-python-screw-compressor: backlog
-  17-4-python-mchx-condenser: backlog
-  17-5-python-flooded-hx: backlog
-  17-6-python-bphx-exchangers: backlog
-  17-7-python-drum: backlog
-  17-8-python-boundary-conditions: backlog
-  17-9-python-multi-circuit: backlog
-  17-10-python-calib-results: backlog
-  17-11-python-bypass-coils: backlog
-  17-12-python-vendor-parsers: backlog
-  17-13-python-macro-snapshot: backlog
-
-  # --- Backlog: WASM ---
-  18-1-wasm-finalize-compilation: backlog
-  18-2-wasm-all-components: backlog
-  18-3-wasm-multi-circuit: backlog
-  18-4-wasm-calib-results: backlog
-  18-5-wasm-vendor-data: backlog
-
-  # --- Done ---
-  6-1-rust-native-api: done
-  6-2-python-bindings-pyo3: done
-  6-3-c-ffi-bindings-cbindgen: done
-  6-5-cli-for-batch-execution: done
-  6-6-python-solver-configuration-parity: done
-  12-1-cli-internal-state-variables: done
-  12-2-cli-coolprop-backend: done
-  12-3-cli-screw-compressor-config: done
-  12-4-cli-mchx-condenser-config: done
-  12-5-cli-flooded-evaporator-brine: done
-  12-6-cli-control-constraints: done
-  12-7-cli-output-json-metrics: done
-  12-8-cli-batch-improvements: done
-  13-1-systembuilder-multi-circuit: done
-  13-2-systembuilder-port-validated-edges: done
-  13-3-systembuilder-constraints-api: done
-  13-4-systembuilder-thermal-couplings: done
-  15-1-cli-real-compressor: done
-  15-2-cli-real-expansion-valve: done
-  15-3-cli-real-pump: done
-  15-9-cli-boundary-conditions: done
-
-  # ═══════════════════════════════════════════════════════════════
-  # P6: HVAC APPLICATIONS — 0/14 (7%)
-  # Free cooling, calibration, standards compliance, reporting
-  # ═══════════════════════════════════════════════════════════════
-
-  # --- In Progress ---
-  14-1-freecoolingexchanger-component: review
-
-  # --- Backlog ---
-  14-2-automatic-mode-switching-logic: backlog
-  14-3-pumpcontroller-optimal-sequencing: backlog
-  14-4-variable-frequency-drive-vfd-optimization: backlog
-  14-5-bypass-valve-control: backlog
-  14-6-safety-interlocks-protection: backlog
-  14-7-control-configuration-serialization: backlog
-  14-8-python-api-advanced-control: backlog
-  7-7-ashrae-140-bestest-validation-post-mvp: backlog  # P6-09
-  7-8-inverse-calibration-parameter-estimation: backlog  # P6-10
-  19-2-eurovent-reporting: backlog  # P6-12
-  19-3-ashrae-bestest: backlog  # MERGED into P6-09 (see epic-restructuring.md)
-
-  # --- Backlog: Calibration workflow ---
-  calibration-workflow-application: backlog  # P6-14
-
-  # ═══════════════════════════════════════════════════════════════
-  # RETROSPECTIVES
-  # ═══════════════════════════════════════════════════════════════
+  epic-0: in-progress
+  0-1-fix-failing-tests: done
+  epic-0-retrospective: optional
+  # --- Epic 0: Physical Regularization & Jacobian Health (epics-solver-hp.md) ---
+  0-1-jacobian-killing-pattern-audit-fd-test-harness: done
+  0-2-phantom-gradient-regularization-standard: review
+  0-3-valve-flow-exv-regularization: backlog
+  0-4-heat-exchanger-regularization: backlog
+  0-5-domain-sweep-jacobian-health-gate: backlog
+  # --- Epic 1: Performance Foundation - Linear Algebra Modernization ---
+  epic-1: in-progress
+  1-1-phase-0-baseline-golden-safety-net: in-progress
+  1-2-core-crate-typed-convergence-taxonomy: backlog
+  1-3-recoverable-domain-violation-errors: backlog
+  1-4-linearsolver-trait-explicit-lifecycle: backlog
+  1-5-dense-faer-backend-strangler-migration: backlog
+  1-6-factorization-scaling-reuse-frozen-jacobians: backlog
+  1-7-zero-allocation-residual-jacobian-assembly: backlog
+  1-8-system-rs-seam-deconstruction: backlog
+  1-9-performance-validation-baseline-sign-off: backlog
   epic-1-retrospective: optional
+  # --- Epic 2: Structural Intelligence & Diagnostics ---
+  epic-2: backlog
+  2-1-equation-variable-incidence-graph: backlog
+  2-2-matching-dulmage-mendelsohn-decomposition: backlog
+  2-3-localized-structural-no-solution-certificates: backlog
+  2-4-scc-condensation-cached-block-ordering: backlog
+  2-5-numerical-diagnostics-condition-extreme-entries: backlog
+  2-6-robustness-sweep-runner-convergence-histogram: backlog
   epic-2-retrospective: optional
+  # --- Epic 3: Open Strategy Architecture ---
+  epic-3: backlog
+  3-1-strategy-registry-core: backlog
+  3-2-builtin-strategies-registry-migration: backlog
+  3-3-composite-fallback-as-data: backlog
+  3-4-pluggable-observer-api: backlog
+  3-5-third-party-strategy-registration-proof: backlog
+  3-6-physical-parameter-continuation-strategy: backlog
   epic-3-retrospective: optional
+  # --- Epic 4: Multicore Parallelism & Batch Solving ---
+  epic-4: backlog
+  4-1-send-sync-readiness-usage-site-bounds: backlog
+  4-2-parallel-residual-jacobian-evaluation: backlog
+  4-3-batch-parallel-solves-api: backlog
+  4-4-opt-in-deterministic-mode: backlog
+  4-5-parallel-performance-validation: backlog
   epic-4-retrospective: optional
+  # --- Epic 5: Physics-Based Initialization & Warm Start ---
+  epic-5: backlog
+  5-1-component-guess-propagation-api: backlog
+  5-2-loop-walking-smart-initializer: backlog
+  5-3-surrogate-initializer-seam-fallback: backlog
+  5-4-versioned-warm-start-snapshots: backlog
+  5-5-cold-start-robustness-validation: backlog
   epic-5-retrospective: optional
+  # --- Epic 6: Embedded Lite Solver (gate: after Story 1.9 + NFR11 >= 90% trend) ---
+  epic-6: backlog
+  6-1-feature-tiers-std-alloc-core: backlog
+  6-2-static-linear-algebra-kernels: backlog
+  6-3-property-table-format-offline-generator: backlog
+  6-4-lite-solver-lookup-newton-polish: backlog
+  6-5-embedded-validation-mcu-linux: backlog
   epic-6-retrospective: optional
+  # --- Epic 7: Plugin Ecosystem (gate: solver API stable, post Epic 3) ---
+  epic-7: backlog
+  7-1-plugin-interface-contracts-tier1: backlog
+  7-2-c-abi-plugin-tier-abi-versioning: backlog
+  7-3-wasm-component-model-plugin-tier: backlog
+  7-4-plugin-developer-kit-e2e-example: backlog
+  7-5-plugin-sandbox-crash-isolation-validation: backlog
   epic-7-retrospective: optional
-  epic-8-retrospective: optional
-  epic-9-retrospective: optional
-  epic-10-retrospective: optional
-  epic-11-retrospective: optional
-  epic-12-retrospective: optional
-  epic-13-retrospective: optional
-  epic-14-retrospective: optional
-  epic-15-retrospective: optional
-  epic-16-retrospective: optional
-  epic-17-retrospective: optional
-  epic-18-retrospective: optional
-  epic-19-retrospective: optional