on_the_level/AUDIT.md

On the Level — v1 Brief Audit

Auditor: Claude · Date: 2026-07-11 Subject: v1 product/architecture brief (Codex) + concept board (resources/Bubble Level Concepts.dc.html)

Verdict

Approve with amendments. The framework is sound and well-proportioned: single app module, manual DI container, no backend, offline-first, and — the load-bearing decision — the three-value separation of raw sensor → stable measurement → animated display. Findings below are ranked; the first three should be resolved in the brief before code is written.

---

Blocking findings

1. Default sensor: use TYPE_GAME_ROTATION_VECTOR, not TYPE_ROTATION_VECTOR

TYPE_ROTATION_VECTOR fuses the magnetometer, and a level is used precisely where magnetometers lie: against steel studs, appliances, metal door frames, workbenches with power tools. Heading is irrelevant to a level — only the gravity direction matters.

• Primary: TYPE_GAME_ROTATION_VECTOR (gyro + accel, no magnetometer)
• Fallback: TYPE_GRAVITY, then low-passed accelerometer (as the brief already plans)
• Declare uses-feature android.hardware.sensor.accelerometer (required) in the manifest.

2. Missing concept: flat mode vs. edge mode

A bubble level is used two ways: phone lying on a surface (bullseye/cross — what all four mockups show) and phone held on its long edge against a wall, shelf, or picture frame. The math, the meaningful readout, and the UI all differ, and credible level apps auto-switch based on the gravity vector. Edge mode is arguably the more common real-world use.

• Add mode detection/auto-switching to v1 scope.
• This affects the sensor-mapping design, so decide now — it does not retrofit cleanly.

3. Calibration: store a reference orientation per mode, not one scalar offset

Subtracting a single angle baseline is only valid near the orientation where it was captured; a flat-mode calibration silently applied in edge mode makes readings worse.

• Store the baseline as a reference gravity vector/quaternion, per mode (flat / edge).
• Strongly recommend the classic two-measurement flow: measure, flip the phone 180°, measure again — true level is the average. It cancels device bias without needing a known-level surface, mirrors how physical levels are calibrated, and is trust-building UX.
• Invariant: lock detection and the displayed degree readout must be computed from the same calibrated stable value. The lock must never fire while the readout shows 0.1°.

---

Answers to the brief's audit questions

Sensor source / orientation reliability

Yes, once findings 1–2 are addressed. One implicit decision to make explicit: sensor axes are device-frame, not display-frame. Cleanest approach is to lock the Activity to portrait (avoids recreation churn mid-measurement) and remap axes / rotate UI affordances yourself from the gravity vector — in which case "normalize for screen rotation" is your own remapping code, not Display.getRotation(). Either approach works; pick one explicitly.

Calibration consistency

Covered by finding 3.

Feedback/animation separated from measurement truth

The three-value separation handles this. Specify the mechanisms so it's testable:

• Stable value: EMA/low-pass with a defined time constant
• Display value: critically-damped spring
• Readout: 0.1° resolution with a display deadband so it doesn't flicker between 0.0° and 0.1°
• Lock: enter ≤0.2°, exit ≥0.35°, short dwell before feedback (as proposed — good), plus a debounce floor of a few seconds between haptic events

Free tier completeness

Complete and fair as specced. Product concern (non-blocking): the screen ruler is a weak Pro anchor — screen rulers are commodity, ~15 cm, and mediocre by nature. Target-angle alerts and saved angle references are the real Pro value for anyone doing actual work (stair stringers, drainage slope, shelf pitch). Market Pro around those; treat the ruler as a bonus.

Pro boundary containment

The narrow ProEntitlementRepository is right. Make it concrete:

• Entitlement exposed as a StateFlow<Entitlement> from the container
• Billing calls confined to core/billing
• Free path never blocks on billing init (billing client connects lazily/async; level screen renders immediately)
• Cache entitlement in DataStore — Play Billing's queryPurchases needs healthy Google Play services; a Pro user on an offline job site must not lose the ruler

Accessibility / legibility / reduced motion

Two Android-specific corrections:

• There is no first-class reduced-motion preference on Android — the signal is Settings.Global.ANIMATOR_DURATION_SCALE == 0 (user disabled animations). Honor that plus an in-app toggle.
• Haptics: use HapticFeedbackConstants.CONFIRM / VibrationEffect so system haptic settings are respected.
• Bright-light check the amber-on-graphite and lime-lock palette — outdoor use is core. Keep numeric readouts near-white (as mockup 1c does); consider a high-contrast option later.

Over-complexity

No — architecture is right-sized. If anything, add two small things:

• FLAG_KEEP_SCREEN_ON while a tool screen is visible (levels are used hands-free; screen timeout mid-measurement is a one-star review)
• Unregister sensor listeners when backgrounded (battery)

---

Smaller notes

• Ruler calibration UX: calibrate against a credit card (ISO width 85.60 mm) rather than asking the user to hold a physical ruler to the screen. Key calibration by Display identity, not just configuration — foldables have two displays that each need their own scale.
• Percent grade: define as tan(pitch) × 100 and decide display behavior as pitch approaches 90° (cap or show ∞) — otherwise a wall reads a comedy number.
• Testability, made concrete: all math (axis remapping, calibration application, smoothing, hysteresis) lives in pure Kotlin behind an injected SensorSource fake, with recorded real-device sensor traces as golden fixtures. That makes "trustworthy" verifiable rather than aspirational.
• Trivia: mockups use iOS device frames for an Android target (fine — UI is fully custom; just handle edge-to-edge insets and back gesture). The concept HTML references ./support.js and ./ios-frame.jsx not present in the repo.

---

Summary of amendments to the brief

1. Sensor: TYPE_GAME_ROTATION_VECTOR primary; gravity/accel fallback; manifest uses-feature.
2. Add flat-mode / edge-mode detection and switching to v1 scope.
3. Calibration = reference orientation stored per mode; offer 180°-flip calibration; lock and readout share one calibrated value.
4. Rebalance Pro pitch toward target angles / saved references over the ruler.
5. Specify smoothing (EMA + damped spring), display deadband, haptic debounce floor.
6. Entitlement cached in DataStore; billing never blocks the free path.
7. Reduced motion via ANIMATOR_DURATION_SCALE; system-respecting haptics.
8. FLAG_KEEP_SCREEN_ON on tool screens; unregister sensors when backgrounded.