[AZ-589] [AZ-590] [AZ-591] [AZ-592] [AZ-593] Re-classify cycle1 gate findings

Cycle 1 Product Implementation Completeness Gate post-mortem.
AZ-589 + AZ-590 were the wrong abstraction:

- AZ-589 targeted `okvis::ThreadedKFVio` (OKVIS v1 API) which does
  not exist in the vendored OKVIS2 upstream; smartroboticslab/okvis2
  exposes `okvis::ThreadedSlam` instead.
- AZ-590 assumed a "de-ROSified VINS-Mono pin" submodule exists;
  `cpp/vins_mono/upstream/` has no `.gitmodules` entry.
- The actual production gap is the empty central
  `_STRATEGY_REGISTRY`: `register_strategy(...)` is never called
  outside test fixtures, so `compose_root()` raises
  `StrategyNotLinkedError` for every component slug with a
  strategy-selecting config field. Affects c1_vio + c2_vpr +
  c2_5_rerank + c3_matcher + c3_5_adhop + c4_pose + c5_state.

Re-classification:

- AZ-589 + AZ-590 closed Won't Fix (Jira); spec files removed
  from todo/ but rows retained in the dependencies table as
  audit-trail.
- AZ-591 created (todo/, 5pt) — cross-cutting compose_root
  per-binary bootstrap that populates `_STRATEGY_REGISTRY` for
  the airborne binary. Scheduled as Batch 66 sole task.
- AZ-592 created (backlog/, 5pt placeholder) — AZ-332 Tier-2
  validation bundle (real `okvis::ThreadedSlam` wiring + Linux CI
  apt-install + DBoW2 vocab + Jetson). BLOCKED on Tier-2
  prerequisites; honors AZ-332's `AZ-332_tier2_validation`
  self-deferral handle.
- AZ-593 created (backlog/, 5pt placeholder) — AZ-333 Tier-2
  validation bundle (de-ROSified VINS-Mono upstream + binding +
  CI + Jetson). BLOCKED on upstream vendoring decision plus
  Tier-2 prerequisites; honors AZ-333's parallel deferral pattern.
- AZ-332 + AZ-333 re-classified in cycle1 gate report from FAIL
  to BLOCKED-on-Tier-2.

Step 7 stays in_progress until AZ-591 lands; after that it can
advance to Step 8 with AZ-592 + AZ-593 parked in backlog/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-16 12:45:58 +03:00
parent be5c6d20aa
commit 6d51e06886
8 changed files with 419 additions and 237 deletions
@@ -0,0 +1,71 @@
# AZ-593 — AZ-333 Tier-2 validation: de-ROSified VINS-Mono upstream + binding + CI + Jetson
**Task**: AZ-593_AZ-333_tier2_validation
**Name**: AZ-333 Tier-2 validation bundle (VINS-Mono)
**Description**: Vendor upstream VINS-Mono (with ROS-strip layer), rewrite `_native/vins_mono_binding.cpp` against the real `Estimator` + `FeatureTracker` API, add the Linux CI apt-install block for the research matrix kind, validate against IT-12 comparative-study fixtures on Jetson hardware.
**Complexity**: 5 points (placeholder; likely 8+ if HKUST + ROS-strip path is chosen — re-size when scheduled)
**Dependencies**: AZ-333, AZ-276 (ImuPreintegrator), AZ-277 (SE3Utils), AZ-591 (compose_root per-binary bootstrap), AZ-592 (OKVIS2 Tier-2 — shares CMake / Eigen pin work)
**Component**: c1_vio (epic AZ-254 / E-C1)
**Tracker**: AZ-593
**Epic**: AZ-254 (E-C1)
**Status**: parked in `backlog/` — BLOCKED on Tier-2 prerequisites (see below)
## Problem
AZ-333 shipped the `VinsMonoStrategy` Python facade + `VinsMonoBackend` skeleton C++ binding (same defect pattern as AZ-332) and explicitly deferred the real estimator wiring. AZ-333's Implementation Notes named the follow-up `AZ-333_tier2_validation`.
The cycle-1 gate initially mis-classified AZ-333 as `FAIL` and created `AZ-590_remediate_vins_mono_estimator_wiring`. That ticket has been closed Won't Fix; this task replaces it with the correct scope.
**Additional blocker unique to AZ-593**: `cpp/vins_mono/upstream/` is referenced by `cpp/vins_mono/CMakeLists.txt` but **does not exist**`.gitmodules` has no entry for it. The original AZ-333 task spec assumed a "de-ROSified VINS-Mono pin" exists; the user / team must pick the vendoring path.
## Outcome
1. **Upstream vendoring decision**: choose between
- (a) Original HKUST `HKUST-Aerial-Robotics/VINS-Mono` (ROS1-locked). Requires in-tree ROS-strip configure-time hook. More work but no fork drift.
- (b) A community de-ROSified fork (e.g., `Karaca-VINS-Mono` or `RonaldSun/vins-fusion-no-ros`). Less work but accepts external maintenance drift.
The decision needs to be made BEFORE work starts. Document in `_docs/03_implementation/refactoring/vins_mono_upstream_choice.md` with the chosen pin commit hash and the rationale.
2. **Add submodule**: `git submodule add <chosen-url> cpp/vins_mono/upstream` against the pinned commit.
3. **ROS-stub layer** (only if option 1a): vendor minimal `cpp/_third_party/vins_mono_ros_stub/` providing the symbols VINS-Mono pulls from `roscpp` / `rosbag` / `std_msgs` / `sensor_msgs` without requiring a real ROS install. Pre-process upstream sources via CMake `configure_file` to redirect ROS headers to the stubs.
4. **C++ binding rewrite**: replace `_native/vins_mono_binding.cpp` skeleton with real `Estimator` + `FeatureTracker` wiring. API surface:
- Construct `feature_tracker::FeatureTracker` + `vins_estimator::Estimator` after parsing `yaml_config_` via VINS-Mono's `readParameters()` / equivalent.
- In `add_frame(image)`: call `feature_tracker_.readImage(image_8uc1, ts_seconds)`, retrieve the resulting feature observations, feed them into `estimator_.processImage(image_msg, header)` (mirroring the upstream `feature_tracker_node.cpp` / `estimator_node.cpp` flows but without ROS message types).
- In `add_imu(ts, accel, gyro)`: `estimator_.processIMU(ts, alpha, omega)`.
- Periodically (or per-frame) call `estimator_.processMeasurements(...)` and `estimator_.solveOdometry()` to drive the sliding-window optimisation.
- Extract output: read `estimator_.Ps[WINDOW_SIZE]` (position), `estimator_.Rs[WINDOW_SIZE]` (rotation), `estimator_.Bas[WINDOW_SIZE]` / `estimator_.Bgs[WINDOW_SIZE]` (biases). Pose covariance from `estimator_.last_marginalization_info`.
- Reset: `estimator_.clearState()` + `estimator_.setParameter()`.
5. **CMake glue**: extend `cpp/vins_mono/CMakeLists.txt` to link the upstream + stub libs against pinned Ceres + OpenCV ≥ 4.2 + Eigen ≥ 3.4. **Pin alignment**: ensure Eigen + Ceres pins match AZ-592 (OKVIS2 Tier-2) to avoid ABI conflict in the research binary which links both.
6. **CI workflow**: gate `BUILD_VINS_MONO=ON` on the `research` / `comparative-study` CI matrix kind only (NOT the airborne kind — `ci/sbom_diff.py` enforces). Apt deps overlap heavily with AZ-592 (Ceres, OpenCV, Eigen, SuiteSparse).
7. **Tier-1 integration test**: `tests/integration/c1_vio/test_az333_vins_mono_real_binding.py` with `@pytest.mark.skipif(not _vins_mono_binding_present())`.
8. **Tier-2 Jetson validation** (comparative-study against AZ-332 OKVIS2): runs IT-12 fixtures, owned by AZ-444 (Tier-2 Jetson harness).
## Prerequisites BLOCKED on
- **Upstream choice (user decision)**: HKUST + ROS-strip (option 1a) vs. community de-ROSified fork (option 1b).
- **AZ-591 landed first**: compose_root per-binary bootstrap so `c1_vio:vins_mono` is registered + reachable on the research binary.
- **AZ-592 landed first or in parallel**: shares Linux CI dep install + Eigen / Ceres pin alignment work.
- **Linux CI runner image with apt deps**: see AZ-592.
- **Jetson hardware**: for IT-12 comparative-study validation.
## Scope notes
- This task as written almost certainly exceeds 5pt. When Tier-2 work actually starts, split into:
- `AZ-593a` — Upstream vendoring decision + ADR addendum + submodule add (2pt)
- `AZ-593b` — ROS-stub layer (if option 1a) (5pt)
- `AZ-593c` — C++ binding rewrite + CMake (5pt)
- `AZ-593d` — Jetson IT-12 validation (5pt)
- The HKUST + ROS-strip path is the more conservative engineering choice (no fork drift, full upstream maintenance available), but it's also the larger effort. The fork path may be 1-2 weeks faster but introduces a maintenance dependency on a third-party fork.
## Notes
- Coordinate Eigen / Ceres pin work with AZ-592. Both link against Ceres + Eigen; the research binary links both AZ-592 and AZ-593 artifacts, so version mismatch = link-time segfault.
- Upstream VINS-Mono's `feature_tracker_node.cpp` and `estimator_node.cpp` are the reference for the binding's I/O flow. Strip the ROS message types and replace with the binding's `add_frame` / `add_imu` surface.
- `_docs/02_tasks/done/AZ-333_c1_vins_mono_strategy.md` documents the original deferral. Keep intact for audit; this task discharges that contract.
- `AZ-444` (Tier-2 Jetson harness) is the consumer of this task's binding artifact. AZ-444's IT-12 comparative-study runs require both OKVIS2 (AZ-592) and VINS-Mono (AZ-593) bindings to be working.