Investigation — blast radius of the boresight + omega-ripple figure work

Generated: 2026-06-25 23:52 EDT Question: Did the boresight + omega-ripple figure work change any load-bearing code (new logged fields, GNC/sim changes, analyzer/logger changes), or did it stay contained to the analysis/ figure scripts? “New fields to be logged, or worse?” Mode: investigator (report-only; no code modified).

Answer first

• Omega-ripple figure: ZERO load-bearing footprint. analysis/omega_ripple_figure.py only reads standard logged fields (state.q, state.v, diagnostics.conditioning.s_min_G) and uses pre-existing helpers (GiordanoRobot.Gamma, contiguous_runs, drop_short_runs, pearson_r). Nothing was added to GNC, the logger, or the catalog for it. Safe to delete with no cleanup.
• Boresight figure: DID reach into the controller — but gated and benign. Commit bd7d0e6 (Jun 23) added a diagnostics block to GNC/breve_controller.py that logs three new fields — diagnostics.frame.ee_angle, diagnostics.cruise_lag.floor_pe_realized, diagnostics.cruise_lag.floor_pe_consistent — plus a new controller method _v_breve_consistent and a new v_breve_override parameter on x_ss_floor.
• The new controller code is OPT-IN and does not run by default. The whole block is behind getattr(self.full_cfg, "log_cruise_lag_floor", False) (breve_controller.py:568-573); the default is false (YAMLs_by_domain/parameters.yaml:4). It only flips on when a run-spec overrides it (run_mission.py:64-66, set only when floor is requested).
• No control behavior changed; baselines are byte-identical. The block writes only to diag.* (never feeds the control law), and bd7d0e6 reports max_abs_diff 0.000e+00, no re-pin. The gold-standard gate passes on the current tree (verified 3 passed earlier today).
• One analysis-only addition: SignalAnalysis.velocity_error was added to analysis/data_analyzer.py (+12 lines, commit e06c2d2) for the boresight figure’s “honest error” panel. Additive method, no behavior change.
• “Or worse”? No. Nothing un-gated, nothing in the hot control path, no NPZ schema change in default runs, no baseline re-pin. The only residue is orphan-risk cruft if the figures are retired (see Findings).

Scope

• Inspected: analysis/boresight_roll_figure.py, analysis/omega_ripple_figure.py, GNC/breve_controller.py (560-611), validation/run_mission.py (58-71), YAMLs_by_domain/metrics.yaml (307-326), git history of all of the above.
• External / not inspected: x_ss_floor / _v_breve_consistent internals (their math is out of scope — the question is whether they run, which the gate answers), analysis/data_analyzer.py divergence_matrix / component_matrix internals.
• Boundary respected: no code modified.

What changed, by commit (call order = chronological)

The figure work spans three commits, not one:

1. bd7d0e6 (Jun 23) — feat(diag): log realized floor + EE frame angle — the load-bearing one.
   • GNC/breve_controller.py +41: the gated diagnostics block (breve_controller.py:567-610). Adds floor_pe_realized (584), floor_pe_consistent (587-591), diagnostics.frame.ee_angle via so3_log(R_ed^T @ R_te) (600-605), the _v_breve_consistent helper, and per-step committed-pose stashing (_floor_prev_des_p_e/_R_e, 607-610).
   • YAMLs_by_domain/metrics.yaml +17: catalog entries cruise_lag.floor / cruise_lag.floor_realized / frame.angle, each commented “opt-in (log_cruise_lag_floor)” (metrics.yaml:310,326).
   • analysis/analysis_YAMLs/frame_angle_diag.yaml +35: a run-spec that flips log_cruise_lag_floor on and renders the 3-panel figure.
2. e06c2d2 (Jun 24) — feat(analysis): harvest boresight + omega_b ripple figures into analysis/ — contained.
   • Touched only 3 files, all in analysis/: the two figure scripts (moved out of weekly-purged validation/) + analysis/data_analyzer.py (+12 = the new velocity_error method, data_analyzer.py:1111).
3. 8f73e08 — feat(controller): adopt implicit-damping integration -- cures the omega_b ripple — legitimate, not figure cruft.
   • This is the actual scientific cure for the period-2 ripple (default-ON IMEX integrator, baselines re-pinned, documented in the wiki). The omega figure merely visualizes the phenomenon this fixes. Listed here only to pre-empt confusion: deleting the omega figure does not touch this.

The gate (why baselines survived)

build_diagnostics(...)            # breve_controller.py, per-step diagnostics
  └─ if getattr(full_cfg, "log_cruise_lag_floor", False)   # :568  ← DEFAULT False
       and des and dyn and isfinite(s_min_G):              # :570-572
         floor_pe, floor_pe_coriolis = x_ss_floor(des)     # :574  (pre-existing)
         floor_pe_realized  = x_ss_floor(des, v_breve_override=v_real)[0]   # :584  ← bd7d0e6
         floor_pe_consistent = x_ss_floor(des, v_breve_override=v_consistent)[0] # :588 ← bd7d0e6
         ee_angle = degrees(norm(so3_log(R_ed.T @ R_te)))  # :600-604  ← bd7d0e6
         diag.frame = Package(ee_angle=ee_angle)           # :605

Default config never enters this branch ⇒ default NPZ schema unchanged ⇒ baselines byte-identical.

Findings

Finding 1 — The only controller change is gated diagnostics; it is correct and safe. Evidence: breve_controller.py:568-605; gate default parameters.yaml:4 (false); bd7d0e6 message (“baselines byte-identical, no re-pin”); gold gate 3 passed today. Impact: No risk to the science or baselines. The figure work did not corrupt the control path. Next step: None required for correctness.

Finding 2 — Orphan-risk cruft exists IF the figures are retired. Evidence: The boresight figure is the primary consumer of ee_angle + the realized/consistent floors. Other consumers are themselves figure/readout artifacts: analysis/analysis_YAMLs/frame_angle_diag.yaml, validation/frame_angle_readout.py:37-39, and analysis/data_analyzer.velocity_error (used only by the boresight figure). Impact: If you decide the boresight figure isn’t worth keeping, ~41 lines of gated controller code, 17 catalog lines, a run-spec, a readout script, and velocity_error become dead weight. Note floor_pe/floor_pe_coriolis (the base cruise-lag floor) are part of the broader, still-relevant cruise-lag investigation (memory cruise-lag-floor-resolved) and should NOT be removed — only the _realized/_consistent/ee_angle extensions are figure-specific. Next step: Decide keep-vs-retire on the boresight figure (Task A). Omega figure is independently deletable (Task B).

Finding 3 — validation/run_mission.py:66 is the lone code path that enables the gate. Evidence: run_mission.py:64-66 (if floor: mapping["log_cruise_lag_floor"] = True); the floor run-specs (full_control_floor_an.yaml, floor_consistent_an.yaml, frame_angle_diag.yaml, …) override it. Impact: The diagnostics are reachable only through an explicit opt-in, never in a bare mission/baseline. Next step: None — this is the intended design.

Proposed next tasks

TASK A — Decide keep-or-retire the boresight (frame-angle) figure. - Body: The boresight figure is the only real consumer of the bd7d0e6 controller diagnostics. If retired, remove the figure-specific extensions; if kept, leave as-is (it’s gated and harmless). - Modify (only if retiring): GNC/breve_controller.py (drop floor_pe_realized/floor_pe_consistent/ee_angle + _v_breve_consistent + the v_breve_override param if unused elsewhere), YAMLs_by_domain/metrics.yaml (cruise_lag.floor_realized, frame.angle), analysis/data_analyzer.py (velocity_error). - Delete (only if retiring): analysis/boresight_roll_figure.py, analysis/analysis_YAMLs/frame_angle_diag.yaml, validation/frame_angle_readout.py. - Keep regardless: floor_pe/floor_pe_coriolis base floor (broader cruise-lag work); the log_cruise_lag_floor gate itself. - Validation: pytest validation/tests/test_gold_standard.py must stay max_abs_diff 0.000e+00; pytest validation -m "not slow" green; re-run any retained floor run-spec.

TASK B — Delete the omega-ripple figure (zero-cleanup). - Body: analysis/omega_ripple_figure.py adds nothing load-bearing and (per user) doesn’t prove its point. Deleting it touches no other code. - Delete: analysis/omega_ripple_figure.py. - Do NOT touch: the implicit-damping integrator (8f73e08) — the legitimate cure, unrelated to the figure. - Validation: git grep confirms no importer; pytest validation -m "not slow" green.

TASK C — (process) The figure investigation edited GNC/ without loading GNC.md rules. - Body: Root cause was the orchestrating agent delegating to subagents that never inspected files, so path-scoped rules never loaded (matches memory read-rules-before-delegating). The byte-identity rule survived only because the author gated the block. Worth a guardrail so GNC edits from sub-agents always carry the GNC hard-rules. - Inspect-not-modify: .claude/rules/GNC.md, the dispatch/delegation flow.