docs: clean stale documentation state

Harness: docs-release

Scope: docs-only

Evidence: python3 contract id consistency check

Evidence: python3 markdown relative link check

Evidence: git diff --check

Evidence: ctest --test-dir build -N

Author: EdwardOptimization

README.md

@@ -1,15 +1,15 @@
 
 
-# MiniSolver: High-Performance Embedded NMPC Library
+# MiniSolver: High-Performance NMPC Library
 
 ![C++17](https://img.shields.io/badge/C++-17-blue.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Platform](https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Embedded-lightgrey)
+![Platform](https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Embedded--Oriented-lightgrey)
 ![Zero-Malloc](https://img.shields.io/badge/Memory-Zero--Malloc-brightgreen)
 
 **MiniSolver** is a professional-grade, header-only C++17 library for solving Nonlinear Model Predictive Control (NMPC) problems.
 
-Engineered specifically for **embedded robotics** and **autonomous driving**, it combines the flexibility of Python-based symbolic modeling with the raw performance of highly optimized, template-generated C++ code. The default real-time configuration is designed for **Zero Dynamic Memory Allocation (Zero-Malloc)** during the solve phase; profiling and iteration logging are opt-in diagnostics and should stay disabled in hard real-time loops.
+Designed for real-time robotics and autonomous-driving research, it combines the flexibility of Python-based symbolic modeling with the raw performance of highly optimized, template-generated C++ code. The default real-time configuration is designed for **Zero Dynamic Memory Allocation (Zero-Malloc)** during the solve phase; profiling and iteration logging are opt-in diagnostics and should stay disabled in hard real-time loops.
 
 ---
 
@@ -21,7 +21,7 @@ Engineered specifically for **embedded robotics** and **autonomous driving**, it
 * **Analytical Derivatives**: Uses SymPy to generate flattened, algebraically simplified C++ code for Jacobians and Hessians at compile-time, including true Gauss-Newton Hessians for explicit least-squares residuals.
 * **🔥 Fused Riccati Kernels**: Unlike solvers that use generic matrix libraries, MiniSolver uses Python (SymPy) to symbolically fuse the Riccati backward pass (`Q + A'PA`) into a single, flattened C++ function. This eliminates all loop overhead and explicitly bypasses multiplication by zero, achieving **perfect sparsity exploitation** for small-to-medium systems ($N_x < 20$).
 
-### 🛡️ Embedded Safety & Robustness
+### 🛡️ Real-Time Robustness
 * **Zero-Malloc Solve Path**: The default solver configuration performs no `new`/`malloc` calls during `solve()`. Keep profiling and iteration logging disabled for hard real-time use.
 * **Robust Interior Point Method (IPM)**:
     * **Mehrotra Predictor-Corrector**: Drastically reduces iteration counts by utilizing higher-order corrections.
@@ -37,7 +37,11 @@ Engineered specifically for **embedded robotics** and **autonomous driving**, it
 
 ## 📊 Performance Benchmarks
 
-Benchmarks performed on an Intel Core i7 (Single Thread) for a **Kinematic Bicycle Model with Obstacle Avoidance** ($N_x=6, N_u=2, N=50$).
+Historical local benchmark snapshot on an Intel Core i7 (single thread) for a
+**Kinematic Bicycle Model with Obstacle Avoidance** ($N_x=6, N_u=2, N=50$).
+For release claims or solver-to-solver comparisons, use the dated reports in
+the benchmark repository with the exact MiniSolver commit, command line,
+backend, and hardware recorded.
 
 | Strategy | Integrator | Line Search | Avg Time | Iterations | Status |
 | :--- | :--- | :--- | :--- | :--- | :--- |
@@ -129,12 +133,19 @@ MiniSolver includes a one-click build script that handles dependency checking, c
 ./build.sh
 ```
 
-## 📦 Embedded Deployment
-
-1.  Generate your model headers on a PC: `python3 generate_model.py`
-2.  Copy the `minisolver/` include folder and your generated headers to your MCU project.
-3.  Define `USE_CUSTOM_MATRIX` to remove `Eigen3` dependency.
-4.  Compile with `-O3`. **No external libraries required.**
+## 📦 Embedded-Oriented Deployment Notes
+
+1.  Generate your model headers on a development machine:
+    `python3 generate_model.py`.
+2.  Copy the `minisolver/` include folder and your generated headers into the
+    target project.
+3.  Define `USE_CUSTOM_MATRIX` to remove the Eigen dependency when the
+    built-in fixed-size matrix backend is appropriate.
+4.  Keep profiling, iteration logging, snapshots, and code generation out of
+    hard real-time loops.
+5.  Validate the target toolchain and runtime profile. MiniSolver is
+    embedded-oriented, but it is not yet documented as a freestanding C++ or
+    no-exceptions embedded profile.
 
 -----
 

docs/architecture/globalization-mehrotra-theory-plan.md

@@ -2,7 +2,8 @@
 
 Date: 2026-05-03
 
-Status: N-THEORY-3, N-THEORY-6, and N-THEORY-1 implemented; N-THEORY-2 deferred
+Status: current-state ledger. N-THEORY-3, N-THEORY-6, and N-THEORY-1 are
+implemented; N-THEORY-2 is deferred.
 
 Related:
 
@@ -12,17 +13,21 @@ Related:
 
 ## Purpose
 
-The deep review groups four remaining theory items:
+The deep review originally grouped four theory items:
 
-- N-THEORY-1: Filter line-search gaps against the Waechter-Biegler route.
-- N-THEORY-2: Fixed ring-buffer filter history instead of a Pareto frontier.
-- N-THEORY-3: Mehrotra affine step uses one combined fraction-to-boundary
-  instead of separate primal and dual affine step lengths.
-- N-THEORY-6: Merit line search uses finite-difference directional derivative
-  instead of an analytic directional derivative.
+- N-THEORY-1: Filter line-search gaps against the Waechter-Biegler route
+  (implemented except Pareto-frontier history).
+- N-THEORY-2: Fixed ring-buffer filter history instead of a Pareto frontier
+  (deferred).
+- N-THEORY-3: Mehrotra affine step used one combined fraction-to-boundary
+  instead of separate primal and dual affine step lengths (implemented).
+- N-THEORY-6: Merit line search used finite-difference directional derivative
+  instead of an analytic directional derivative (implemented for the default
+  multiple-shooting merit path).
 
-These are not one bug. They touch different solver phases and need separate red
-tests and commits.
+These were not one bug. They touched different solver phases and were handled
+with separate tests and commits. This file now records the current state rather
+than an open implementation queue.
 
 ## Source Survey
 
@@ -39,7 +44,7 @@ Local source survey:
   `sigma`, `alpha_prim`, and `alpha_dual`, matching the standard primal-dual IPM
   distinction between primal and dual step lengths.
 
-MiniSolver previously had:
+Historical baseline before the follow-up work:
 
 - `FilterLineSearch::is_acceptable()` with sufficient decrease plus filter
   entries, but no `theta_max` sentinel, no f-type/h-type switch, and no f-type
@@ -62,15 +67,15 @@ MiniSolver previously had:
 
 ### N-THEORY-3: Split Mehrotra Affine Step Lengths
 
-Classification: theory-standard.
+Status: implemented.
 
-Why it is real:
+Current behavior:
 
-- Standard Mehrotra computes separate affine primal and dual steps, then uses
-  them to estimate the affine complementarity gap.
-- MiniSolver currently uses one scalar fraction-to-boundary for `s`, `lambda`,
-  `soft_s`, and `w-lambda`. This is safe but can be conservative because a
-  primal-limited direction also shortens the dual affine step and vice versa.
+- MiniSolver computes separate affine primal and dual step lengths.
+- `compute_affine_barrier_mu_()` evaluates primal quantities with
+  `alpha_primal_aff` and dual quantities with `alpha_dual_aff`.
+- Accepted primal-dual damping may still use a combined alpha when a single
+  interior step bound is required.
 
 Implementation shape:
 
@@ -82,61 +87,50 @@ struct FractionToBoundaryResult {
 };
 ```
 
-Use:
+Current use:
 
 - `primal` for `s` and L1 `soft_s`.
 - `dual` for `lambda` and L1 `w-lambda`.
 - `combined()` for accepted primal-dual step damping where one scalar is still
   required.
-- `compute_affine_barrier_mu_()` should evaluate `s` and `soft_s` with
+- `compute_affine_barrier_mu_()` evaluates `s` and `soft_s` with
   `alpha_primal`, and `lambda` / `w-lambda` with `alpha_dual`.
 
-Red test:
+Evidence:
 
-- Construct a small solver state where the affine primal step is strongly
-  limited but the dual step is not.
-- Verify `mu_aff` from split steps is lower than the current combined-step
-  value and matches a direct recomputation using separate alphas.
-- Verify L1 soft pair uses `soft_s + alpha_p * dsoft_s` and
-  `w - (lambda + alpha_d * dlambda)`.
+- `tests/test_bugfixes.cpp::BugfixTest.MehrotraUsesSeparateAffinePrimalAndDualStepLengths`.
+- `tests/test_bugfixes.cpp::BugfixTest.MehrotraMuAffIncludesL1SoftPair`.
 
 ### N-THEORY-6: Analytic Merit Directional Derivative
 
-Classification: theory-standard but implementation-sensitive.
+Status: implemented for the default multiple-shooting merit path.
 
-Why it is real:
+Current behavior:
 
-- Current finite-difference `dphi` costs an extra trial construction and model
-  evaluation per search.
-- It is also sensitive to `eps_alpha` and can misclassify nearly flat merit
-  directions.
-- acados computes the directional derivative analytically from cost,
-  dynamics, and inequality contributions.
+- Merit line search computes the directional derivative analytically from
+  already available cost, dynamics, and constraint quantities.
+- The default hot path does not construct an extra finite-difference probe to
+  estimate `dphi`.
 
 Implementation shape:
 
-- Add an internal `MeritDirectionalDerivative` helper, not a public API.
+- Keep the derivative helper internal, not a public API.
 - Compute directional derivative of:
   - cost: `q^T dx + r^T du` using already evaluated gradients;
   - hard/L1/L2 residual penalties using signs of current true residuals and
     linearized residual directions;
   - dynamics defect penalties using signs of current defects and
     `dx_next - A dx - B du`;
   - barrier terms for `s`, `soft_s`, and `w-lambda`.
-- Keep finite-difference derivative behind a debug comparison flag only if a
-  red test shows useful coverage; do not keep both paths in default hot logic.
 
-Red tests:
+Evidence:
 
-- Compare analytic derivative against finite difference on a fixed small model
-  for hard, L1, and L2 constraints.
-- Cover rollout disabled first. Rollout-enabled merit derivative can be
-  deferred unless the feature is used in benchmarks.
-- Verify no extra model evaluation is needed to compute `dphi`.
+- `tests/test_line_search.cpp::LineSearchTest.MeritArmijoDoesNotBuildFiniteDifferenceProbe`.
+- `tests/test_line_search.cpp::LineSearchTest.MeritNonFiniteDphiReturnsNumericalError`.
 
 ### N-THEORY-1: Filter Theory Completion
 
-Classification: implemented except Pareto-frontier history.
+Status: implemented except Pareto-frontier history.
 
 Sub-items:
 
@@ -145,15 +139,14 @@ Sub-items:
    accepted steps.
 3. Done: switching condition using the filter objective directional derivative.
 
-Implementation shape:
+Current implementation shape:
 
-- Add `FilterAcceptanceKind { HType, FType }` as an internal result, not a user
-  API.
+- `FilterAcceptanceKind { HType, FType }` is an internal result, not a user API.
 - Keep `LineSearchType::FILTER` as the user-facing selection.
-- Add `filter_theta_max_factor` / `filter_theta_min_factor` only if needed for
-  behavior tuning; otherwise keep defaults internal first.
+- `filter_theta_max_factor` is a config field for the implemented theta gate;
+  `theta_min` remains an internal constant.
 
-Red tests:
+Evidence:
 
 - `LineSearchTest.FilterRejectsTrialAboveThetaMax`.
 - `LineSearchTest.FilterFTypeUsesArmijoAndDoesNotAugmentFilter`.
@@ -186,10 +179,10 @@ Red test:
 
 ## Recommended Order
 
-1. N-THEORY-3 split affine primal/dual step lengths. It is the smallest
-   standard-route correctness/performance improvement.
-2. N-THEORY-6 analytic merit directional derivative for merit line search.
-3. N-THEORY-1a `theta_max` gate.
+1. Done: N-THEORY-3 split affine primal/dual step lengths.
+2. Done: N-THEORY-6 analytic merit directional derivative for merit line
+   search.
+3. Done: N-THEORY-1a `theta_max` gate.
 4. Done: N-THEORY-1b f-type/h-type acceptance and filter augmentation rules.
 5. Done: N-THEORY-1c switching condition using derivative machinery from
    N-THEORY-6.

docs/architecture/soft-constraint-weight-api-plan.md

@@ -1,9 +1,13 @@
 # Soft Constraint Weight API Plan
 
+Status: implemented design record. Current normative behavior lives in
+[`../contracts/soft-constraints-contract.md`](../contracts/soft-constraints-contract.md)
+and the MiniModel/codegen contracts.
+
 ## Problem
 
-MiniModel currently stores one static `(type, weight)` pair per constraint row.
-That makes two user-facing cases awkward:
+Before the per-knot weight work, MiniModel stored one static `(type, weight)`
+pair per constraint row. That made two user-facing cases awkward:
 
 1. a soft weight cannot be a model parameter updated at runtime;
 2. one physical constraint cannot carry both L1 and L2 soft penalties without
@@ -14,7 +18,7 @@ That makes two user-facing cases awkward:
 MiniModel owns the modeling semantics. C++ must not decide whether a row is L1
 or L2 by inspecting the runtime weight value.
 
-The generated model should expose fixed structure:
+The generated model exposes fixed structure:
 
 ```cpp
 static constexpr std::array<bool, NC> constraint_has_l1 = {...};
@@ -30,10 +34,17 @@ MSVec<T, NC> l1_weight;
 MSVec<T, NC> l2_weight;
 ```
 
-Together, the trajectory stores two `(N + 1) x NC` weight tables. A generated
-model function refreshes both tables for one knot:
+Together, the trajectory stores two `(N + 1) x NC` weight tables. Generated
+models may split L1 and L2 weight updates to avoid redundant clears, with a
+wrapper that refreshes the declared soft-weight tables for one knot:
 
 ```cpp
+template <typename T>
+static void update_l1_soft_constraint_weights(KnotPoint<T, NX, NU, NC, NP>& kp);
+
+template <typename T>
+static void update_l2_soft_constraint_weights(KnotPoint<T, NX, NU, NC, NP>& kp);
+
 template <typename T>
 static void update_soft_constraint_weights(KnotPoint<T, NX, NU, NC, NP>& kp);
 ```
@@ -105,23 +116,25 @@ so the L1 and L2 penalties act on the same relaxation variable.
 
 ## Solver Integration
 
-The solver reads structure and values separately:
+The solver reads structure and values separately. The row route is hard first,
+then mixed L1+L2, then pure L1, then L2 or the regularized weak-L2 relaxation:
 
 ```cpp
-if constexpr (Model::any_l1_constraints) {
-    if (Model::constraint_has_l1[i]) {
-        const double w = kp.l1_weight(i);
-        // existing L1 path
-    }
-}
-if constexpr (Model::any_l2_constraints) {
-    if (Model::constraint_has_l2[i]) {
-        const double w = kp.l2_weight(i);
-        // existing L2 path
-    }
+if (hard_constraint_row<Model>(i)) {
+    // hard path
+} else if (active_mixed_l1_l2_soft_constraint<Model>(kp, i, config)) {
+    // shared soft_s with z = w1 + w2 * soft_s - lambda
+} else if (active_l1_soft_constraint<Model>(kp, i, config)) {
+    // pure L1 path
+} else {
+    // active L2 or declared-soft weak L2 relaxation
+    const double w = effective_l2_soft_weight<Model>(kp, i, config);
 }
 ```
 
+Mixed L1+L2 is not implemented as "run pure L1, then run pure L2"; it has a
+single relaxation variable and a single mixed soft-dual expression.
+
 Hand-written test or example models must use the same structure arrays and
 weight updater. The solver core does not infer L1/L2 semantics from legacy
 `constraint_types` or `constraint_weights`.
@@ -133,5 +146,7 @@ weight updater. The solver core does not infer L1/L2 semantics from legacy
 - MiniModel test: one constraint row can have both L1 and L2 soft weights.
 - Solver test: changing a parameter weight at runtime changes the per-stage
   stored weight before solving.
+- Solver test: same-row L1+L2 uses the mixed KKT route and matches the intended
+  shared-relaxation penalty behavior.
 - Regression tests: existing L1/L2 soft constraint behavior remains unchanged
   after internal test models migrate to the new structure/updater contract.

docs/modules/alg-barrier.md

@@ -67,4 +67,7 @@ No owned state.
 
 ## Known Gaps
 
-- Barrier update contract IDs are not assigned yet.
+- Current barrier-mu contracts live in
+  [`../contracts/barrier-mu-contract.md`](../contracts/barrier-mu-contract.md).
+  Remaining tuning or replay evidence should be tracked in
+  [`../testing/contract-coverage-matrix.md`](../testing/contract-coverage-matrix.md).

docs/modules/alg-initialization.md

@@ -74,4 +74,9 @@ No owned state; mutates caller-owned knot and solver scalar state.
 
 ## Known Gaps
 
-- Initialization contract IDs for mixed soft central path are not assigned yet.
+- Current initialization and mixed soft central-path contracts live in
+  [`../contracts/initialization-contract.md`](../contracts/initialization-contract.md)
+  and
+  [`../contracts/soft-constraints-contract.md`](../contracts/soft-constraints-contract.md).
+  Remaining evidence gaps should stay in the coverage matrix, not this module
+  summary.

docs/modules/alg-line-search.md

@@ -80,4 +80,9 @@ accepted-step refresh, SOC integration points, and barrier-update history reset.
 
 ## Known Gaps
 
-- Separate contracts for merit and filter globalization are not assigned yet.
+- Current globalization contracts are split across
+  [`../contracts/line-search-contract.md`](../contracts/line-search-contract.md),
+  [`../contracts/merit-line-search-contract.md`](../contracts/merit-line-search-contract.md),
+  and
+  [`../contracts/filter-line-search-contract.md`](../contracts/filter-line-search-contract.md).
+  Remaining merit/filter evidence is tracked per contract row.

docs/modules/alg-model-evaluation.md

@@ -80,4 +80,8 @@ constraint evaluation, scaling application, and residual helpers.
 
 ## Known Gaps
 
-- Packet ownership and scaling contract IDs are not assigned yet.
+- Packet ownership and scaling contracts live in
+  [`../contracts/constraint-packets-contract.md`](../contracts/constraint-packets-contract.md),
+  [`../contracts/generated-packets-contract.md`](../contracts/generated-packets-contract.md),
+  [`../contracts/scaling-contract.md`](../contracts/scaling-contract.md), and
+  [`../contracts/row-scaling-contract.md`](../contracts/row-scaling-contract.md).

docs/modules/alg-termination.md

@@ -82,4 +82,9 @@ and residual stagnation monitoring.
 
 ## Known Gaps
 
-- Termination contract IDs are not assigned yet.
+- Termination, postsolve, status, and tolerance semantics are covered by
+  [`../contracts/termination-contract.md`](../contracts/termination-contract.md),
+  [`../contracts/postsolve-contract.md`](../contracts/postsolve-contract.md),
+  [`../contracts/status-semantics-contract.md`](../contracts/status-semantics-contract.md),
+  and
+  [`../contracts/tolerance-contract.md`](../contracts/tolerance-contract.md).