Clean up extended_controller: canonical 2-DOF, direct kwarg, validation

[baggepinnen]

Summary

Follow-up to the extended_controller review. Five things land in one PR; tests stay green (1378 pass / 6 broken pre-existing / 0 fail).

• Canonical 2-DOF observer controller. The old implementation set B1 = 0, meaning the observer estimate x̂ was biased when xᵣ ≠ 0 and a manually-tuned reference pre-filter was required for any kind of DC tracking. With the change, B1 = (B − KD)·L — the reference enters the observer dynamics so x̂ correctly tracks x. For integrator-containing plants (e.g. the cartpole test) this also makes the closed-loop reference-to-output DC gain exactly 1, so the previously-needed dc_gain_compensation prefilter is no longer needed and the related tests now assert dcgain ≈ 1 directly.
• Delete the broken extended_controller(K::AbstractStateSpace) overload. No callers anywhere; it only logged @error("This has not been verified") on invocation.
• New direct::Bool=false kwarg mirroring observer_controller's current-time-correction option for discrete plants. The y-channel matches observer_controller(...; direct=true) matrix-for-matrix (so system_mapping(Ce) == -observer_controller(...; direct=true)). The reference path in direct mode is feedforward-only — the canonical 2-DOF B1 formulation gets awkward in the direct/current-time observer form; the docstring records this caveat.
• Argument validation: size(L) and size(K) are now checked at entry with a clean ArgumentError.
• Cleanup: drop the stale # should be D21? self-questioning comment, the misplaced # l.D21 does not appear here, see comment in kalman line, and add a comment near the z-branch feedback call recording the default pos_feedback=false convention and the meaning of the U2 slice.

DyadControlSystems was audited and has no extended_controller callers, so this is safe to ship without a deprecation shim.

Docs

docs/src/lqg_disturbance.md gets a new "2-DOF tracking with extended_controller" section demonstrating the controller and how to use the z second return value for DC-gain pre-compensation when the plant has no free integrator.

Test plan

• Full test suite (Pkg.test()): 1378 pass / 6 broken (pre-existing) / 0 fail / 0 error.
• New tests in test/test_lqg.jl:
  • Method 7 — discrete-time round-trip: system_mapping(Ce) == -observer_controller(l_d).
  • Method 8 — direct = true round-trip: same equality with direct = true.
  • Dimension validation: wrong-sized L/K raises ArgumentError.
• cd docs && julia --project make.jl — clean build; the new LQG_DIST @example block evaluates and produces a step response that settles on 1.

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.55%. Comparing base (b226e0d) to head (536a8b1).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #140      +/-   ##
==========================================
+ Coverage   90.96%   91.55%   +0.59%     
==========================================
  Files          20       20              
  Lines        3055     3056       +1     
==========================================
+ Hits         2779     2798      +19     
+ Misses        276      258      -18     

Flag	Coverage Δ
unittests	91.55% <100.00%> (+0.59%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.