# Polisher-Control Roadmap

## Phase 0 — Repository foundation

- [x] Create repository structure.
- [x] Add ecosystem boundary docs.
- [x] Add v1 scope and acceptance checklist.
- [x] Add host/firmware scaffolds.
- [x] Mirror current shared schemas.

## Phase 1 — Contracts first

- [ ] Lock protocol frame format: message IDs, payload layout, CRC, ACK/NACK.
- [ ] Lock telemetry channel list, units, rates, validity encoding.
- [ ] Lock event/alarm code table.
- [ ] Validate `controller-job.v1` and `run-log.v1` fixtures.
- [ ] Implement host-side state machine tests before hardware logic grows.

## Phase 2 — Teensy bench bring-up

- [ ] Teensy boot/status heartbeat.
- [ ] Host↔Teensy serial link with ACK/NACK and CRC.
- [ ] KWR75B-CAN receive path with measured sample rate and stale-frame watchdog.
- [ ] Encoder acquisition for table and arm.
- [ ] ODrive command/telemetry interface selected and documented, including sign mapping for `cw`/`ccw` physical tool rotation.
- [ ] Force actuator command path selected and documented.

## Phase 3 — Manual mode MVP

- [ ] Host UI/manual-mode workflow with geometric gate.
- [ ] Manual setpoints: force, table RPM, spindle RPM, spindle direction (`cw`/`ccw`), optional modulation.
- [ ] Teensy inner loop: setpoint ramping, force PID, telemetry, fast interlocks.
- [ ] Manual-session log and telemetry CSV written to `/data/manual/{session_id}/`.
- [ ] Status file updated at `/data/status.json`.

## Phase 4 — Safety and commissioning

- [ ] E-stop behavior verified independently of software state.
- [ ] Force over-limit, encoder loss, drive fault, F/T invalid/stale faults verified.
- [ ] Host watchdog and firmware heartbeat verified.
- [ ] FAULTED exits only by explicit operator reset.
- [ ] Tool-weight compensation offset commissioned and logged.

## Phase 5 — Controller-job dry run

- [ ] `controller-job.v1` 4-gate intake implemented.
- [ ] Segment lifecycle exercised on bench/simulator.
- [ ] `run-log.v1` emitted with commanded-vs-actual structure.
- [ ] Program execution remains disabled for production until Antoine explicitly accepts readiness.