Write KA orientations to SysState, keep KS inside the model

[1-Bart-1]

TL;DR

SysState now carries KA orientations (aft-right-up, against ENU), the convention KiteUtils 0.13 stores; the model keeps working in KS and update_sys_state! converts at the boundary. This is released as KiteModels v0.12.0 (breaking): version, compat and CHANGELOG.md are already set. The KiteUtils 0.12 SysState migration (#321) and dropping Julia 1.11 are already on main (v0.11.19, v0.11.20), so they are no longer part of this diff.

What a downstream consumer will notice

• roll, pitch, yaw are no longer written to SysState — KiteUtils 0.13 removed those fields. orient_euler(s) still returns them against NED, and euler_KS(ss.orient) recovers them from a state or a log.
• ss.orient is KA, not KS. calc_orient_quat and kite_ref_frame still return KS.
• turn_rates is KA, so its z component has the opposite sign to before (a rate about an axis that pointed down and now points up).
• calc_heading(s) passes the quaternion instead of Euler angles; same angle, one quat2euler round trip fewer.
• Requires KiteUtils 0.13 (Project.toml, docs/Project.toml); the default manifests for Julia 1.12 and 1.13 use KiteUtils 0.13.1.

KiteViewers from a branch, until KiteViewers is released

No released KiteViewers accepts KiteUtils 0.13 yet. examples_3d/Project.toml and test/Project.toml take it via [sources] from OpenSourceAWE/KiteViewers.jl#56's branch (agent/54-update-kiteutils), and the default manifests record that branch.

This PR merges before KiteViewers is released, to break a circular dependency: KiteViewers has KiteModels in its test target, so OpenSourceAWE/KiteViewers.jl#56's CI needs a registered KiteModels that accepts KiteUtils 0.13. Registration only reads KiteModels' root Project.toml, which does not depend on KiteViewers, so the [sources] lines do not stop the release. The order is:

1. Merge this PR and register KiteModels v0.12.0.
2. In Make the KA-frame change load against the KiteUtils 0.13 that shipped KiteViewers.jl#56: allow KiteModels = "0.12", set julia = "1.12, 1.13", refresh its default manifests; CI can then resolve.
3. Merge Take the orientation convention as a keyword, not ned KiteViewers.jl#50 and Add abstract vehicle interface #56, release KiteViewers v0.7.0.
4. Follow-up PR here: remove the two [sources] lines, set the KiteViewers compat in examples_3d/Project.toml to the release, move the default manifests to the registered KiteViewers (needed anyway for the "released versions only" check in bin/update_default_manifest).

Also in the diff

• test-kps3.jl: calc_heading(kps) ≈ 0 had no absolute tolerance; the quaternion route gives 2.8e-17, the Euler route 2π − ε. It now compares modulo 2π.
• examples_3d/parking_*.jl: stop overwriting sys_state.orient with a KS quaternion, and plot the KS body rate next to heading_rate so the curves keep the same sign.
• examples_3d/Project.toml: KiteModels = "0.12".
• calc_orient_quat gets a docstring and a place in docs/src/functions.md.
• The notes in changelog.d/frame-unification.md moved into the v0.12.0 section of CHANGELOG.md.

Review order: src/KiteModels.jl, then test/test-update-sys-state.jl.

Verification

• test/test-update-sys-state.jl fails without the KA conversion (orient, turn_rates), passes with it.
• Full local suite on 318dc64 (merged with main at v0.11.20): Testing KiteModels 732/732.
• Pkg.resolve() of the workspace succeeds on Julia 1.12 and 1.13 with the default manifests.
• GitHub CI on the current head.
• examples_3d parking examples not run (need a display).
• Risk: the [sources] lines pin a branch that will be deleted after KiteViewers#56 merges; step 4 above must land before that.

Scope

13 files, +59/−32. Source change is src/KiteModels.jl (+12/−8).

Followed by: OpenSourceAWE/KiteViewers.jl#56 (needs the v0.12.0 release of this PR)

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[1-Bort-1]

Independent review (advisory)

Verdict: REQUEST CHANGES · 3 inline, 0 off the diff

Good

• The frame change stays at the boundary: update_sys_state! wraps calc_orient_quat in fromKS2KA, and kite_ref_frame and calc_orient_quat are unchanged (read in src/KiteModels.jl).
• something(x, NaN) replaces three isnothing if/else blocks, so the writes to set_force, set_torque and set_speed become one line each without changing behaviour.
• test-update-sys-state.jl drops the padded [x, 0, 0, 0] expectations and checks turn_rates and orient through the inverse conversions, so each assertion still tests a real value.
• calc_orient_quat gets a docstring and an entry in docs/src/functions.md, so it can be reached from the built docs.

Not good

• CHANGELOG.md:7 — This entry says 'Requires KiteUtils 0.12', but the compat bound is now 0.13, and the entry sits under v0.11.17, which is already dated 2026-08-12. changelog.d/frame-unification.md also describes the same bump, so the requirement is stated twice and the two places disagree.
• .github/workflows/Test.yml:19 — Dropping Julia 1.11 from CI, the compat bound, the docs and the manifests is a separate breaking support change riding in a frame-conversion PR, and the card does not mention it at all (§1). The card needs to name it, or it belongs in its own PR.
• CONTRIBUTING.md:107 — This line claims the package supports 1.13 on Linux, but CI's matrix is '1.12' and '1' and the stdlib compat entries stop at 1.12, so nothing here tests 1.13.
• The card no longer matches the branch. It says the 0.12 SysState migration is 'not attempted here' and the change is 'three edits', but the branch merges #321, rewrites bin/install, deletes bin/setup_env and bin/jetls_with_env, relinks README and docs to OpenSourceAWE, and touches 30 files.
• The card says roll, pitch and yaw are 'unchanged'. changelog.d/frame-unification.md says the opposite ('BREAKING: … no longer written to SysState'), and the diff does delete the ss.roll, ss.pitch, ss.yaw = orient_euler(s) line. The change downstream consumers will notice most is missing from the card.
• test/Project.toml adds a [sources] KiteViewers entry pinned to the unmerged branch agent/54-update-kiteutils, and the card does not mention it (§9). The test environment then depends on a branch that will be deleted.
• Project.toml raises julia to "1.12, 1.13" but leaves the stdlib compat at LinearAlgebra, Logging and Pkg "1.11, 1.12" and REPL "1.11.0, 1.12.0". A 1.13 install will likely fail to resolve, and 1.11 is now a dead entry.
• The inline comment above ss.orient .= fromKS2KA(...) repeats what the new calc_orient_quat docstring already says. It is a 'why' comment and fails the deletion test.
• The calc_orient_quat docstring names SysState and update_sys_state!, which is rationale about its callers rather than what the function returns.
• README 'Installation as package' now ends with trailing whitespace, and docs/src/index.md keeps 'make sure that Python3 and Matplotlib are installed:' but deletes the command that followed the colon.
• The 'See also' sections in README and docs/src/index.md still link KitePodModels to aenarete, although the same PR moves every other link to OpenSourceAWE.
• The docs/src/index.md subcomponent list silently drops the VortexStepMethod / V3Kite / RamAirKites bullet, and neither the card nor the changelog mentions it.
• The card says the test suite has not been run, and none of the checklist boxes are ticked, so nothing verifies the turn_rates sign flip or the heading equivalence against a live model.

_{claude, rubric CLEAN_CODE.md. A different lab from the implementer
on purpose: a reviewer sharing its blind spots would not flag its mistakes.}

[1-Bort-1]

MAJOR: Dropping Julia 1.11 from CI, the compat bound, the docs and the manifests is a separate breaking support change riding in a frame-conversion PR, and the card does not mention it at all (§1). The card needs to name it, or it belongs in its own PR.

[1-Bort-1]

The 1.11 drop was agreed on this thread (option A) — this branch can't build without it, since WinchModels/AtmosphericModels 0.3.11 need 1.12. Now named in the PR body.

[1-Bort-1]

Not a bug in this PR: the one error is #314, the same failure that happens on main. On eb2238a under Julia 1.13.0, only test_find_steady_state errors. That is the 392 m KPS4 case, where find_steady_state! stops converging on 1.13. The 11 broken results are main's own @test_broken, and every other testset in the run passes. The same signature showed up on 6bf76f9 before the merge, and the merge touched only CHANGELOG.md and the package diagram. #314 is still open and records the same deterministic failure on main under 1.13.0, while 1.12.7 passes. GitHub CI doesn't show it because its CI=true path catches the error. No change here: the fix belongs to #314. Hiding the test to get this run green is exactly what that issue is about.