Cognitive_Agent/docs/superpowers/plans/2026-07-30-vehicle-profile-seat-calibration.md

Vehicle Profile Seat Calibration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add vehicle-selectable Denza N7 seat calibration so natural-language physical deltas can be deterministically converted to absolute seat position_pct before CAN compilation.

Architecture: Add a small vehicle profile layer under src/cognitive_agent/application/ that loads YAML profiles from config/vehicles/. SeatDemoService passes the selected profile into model-plan adaptation and returns available profiles via /api/runtime; the frontend stores a selected vehicle id and includes it in /api/requests. CAN compilers remain unchanged and continue receiving absolute position_pct.

Tech Stack: Python 3.11 stdlib + PyYAML, existing unittest suite, existing static HTML/JS frontend.

---

Task 1: Vehicle Profile Loader

Files:

• Create: config/vehicles/denza_n7.yaml

• Create: src/cognitive_agent/application/vehicle_profile.py

• Test: tests/unit/test_vehicle_profile.py

• Step 1: Write failing tests

Create tests/unit/test_vehicle_profile.py with tests that load the Denza N7 profile, expose all four motors, convert relative physical deltas into target percentages, and expose angle ranges for frontend display.

• Step 2: Run tests and verify RED

Run: PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src:domains/seat/src .omx/python311-venv/bin/python -m unittest tests.unit.test_vehicle_profile -v

Expected: fails because cognitive_agent.application.vehicle_profile does not exist.

• Step 3: Implement loader

Create the Denza N7 YAML profile with longitudinal, cushion_tilt, backrest_recline, and legrest_height motors. Implement VehicleProfileRegistry, VehicleProfile, and SeatMotorProfile with methods to compute clamped absolute targets from relative deltas.

• Step 4: Run tests and verify GREEN

Run the same unittest command and expect PASS.

Task 2: Apply Vehicle Profile During Intent Adaptation

Files:

• Modify: src/cognitive_agent/application/model_plan_adapter.py

• Test: tests/unit/test_vehicle_profile.py

• Step 1: Write failing tests

Add tests showing a request with distance_mm=50 and operation=increase for seat.set_longitudinal_position converts from current 50% to 73% using Denza N7's 215mm range. Add a test showing angle_delta_deg=10 for seat.set_backrest_recline converts from 20% to 38% using the 55 degree range and preserves motion_intent.

• Step 2: Run tests and verify RED

Run the vehicle profile unittest and expect failure because ModelPlanAdapter.adapt() does not accept a vehicle profile and rejects unknown distance_mm / angle_delta_deg parameters.

• Step 3: Implement adaptation

Allow vehicle-profile-backed physical delta parameters for seat motion requests. Translate them to absolute position_pct, preserve relative motion metadata, and keep the compiler-facing FunctionConfig unchanged.

• Step 4: Run tests and verify GREEN

Run the vehicle profile unittest and expect PASS.

Task 3: Thread Vehicle Selection Through API and Runtime

Files:

• Modify: src/cognitive_agent/application/seat_service.py

• Modify: src/cognitive_agent/server.py

• Test: tests/e2e/test_seat_web_api.py

• Step 1: Write failing tests

Add e2e coverage that /api/runtime includes vehicles and default_vehicle_id, and that a POST containing vehicle_id: "denza_n7" records the selected profile in the result and uses it for conversion.

• Step 2: Run tests and verify RED

Run: PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src:domains/seat/src .omx/python311-venv/bin/python -m unittest tests.e2e.test_seat_web_api -v

Expected: fails because runtime has no vehicles and POST ignores vehicle_id.

• Step 3: Implement API threading

Instantiate VehicleProfileRegistry in SeatDemoService, return public profiles from runtime_info(), accept vehicle_id in process(), pass the selected profile to ModelPlanAdapter, and include vehicle_id / vehicle_name in the API result. Update server.py to read vehicle_id from JSON.

• Step 4: Run tests and verify GREEN

Run the e2e unittest and expect PASS.

Task 4: Add Frontend Vehicle Selector

Files:

• Modify: apps/web-console/index.html

• Modify: apps/web-console/app.js

• Modify: apps/web-console/styles.css

• Test: tests/e2e/test_seat_web_api.py

• Step 1: Write failing tests

Extend the static HTML/runtime e2e test to assert that the page has a vehicle selector and that runtime-provided vehicles are expected by the frontend.

• Step 2: Run tests and verify RED

Run the e2e unittest and expect failure because the selector does not exist.

• Step 3: Implement UI

Add a compact selector in the top bar or command panel, populate it from /api/runtime.vehicles, keep denza_n7 selected by default, store the selected id in state.vehicleId, and include vehicle_id in POST /api/requests.

• Step 4: Run tests and verify GREEN

Run the e2e unittest and expect PASS.

Task 5: Verification

Files:

• No new production files beyond Tasks 1-4.

• Step 1: Run targeted tests

Run: PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src:domains/seat/src .omx/python311-venv/bin/python -m unittest tests.unit.test_vehicle_profile domains.seat.tests.unit.test_t2g_hardware tests.e2e.test_seat_web_api -v

• Step 2: Smoke running service

Use the existing Python 3.11 venv to GET /api/runtime and verify Denza N7 appears. POST a local/direct request with vehicle_id=denza_n7 and confirm a successful dry-run still returns a CommandPlan.

• Step 3: Review diff

Run git diff --stat and inspect changed files. Do not revert the pre-existing README.md change unless explicitly requested.