Documentation

Release Readiness Matrix & Governance Audit

Project: Drive Assist (com.geely.drivemem)
Target Hardware: Geely EX2 / Geometry E (IHU629G Head Unit, Android 9 / API 28, ECARX 250060)
Audit Date: 2026-09-10
Audit Scope: Requirements R1, R2, R3, R4
Audit Status: ALL GATES PASS (READY FOR GOVERNED RELEASE CANDIDATE)
Release Constraint: STRICT NO-RELEASE COMPLIANCE VERIFIED (Zero git tags created; zero external releases triggered)

1. Executive Summary

This document establishes the official Public Release Readiness Assessment for Drive Assist. It synthesizes the technical findings, static code analysis metrics, vehicle safety audits, live hardware verifications, and repository hygiene remediation executed across all project milestones.

The software platform interfaces with physical vehicle hardware via Android Car API / VHAL binder services and operates in an automotive safety-critical context. A multi-perspective audit was conducted to ensure that:

1. Automated Quality Tooling (R1): The build system contains fully automated test coverage and static analysis pipelines (JaCoCo, Android Lint, Checkstyle, SpotBugs) that execute cleanly without regressing or modifying the production release APK.
2. Vehicle Safety & Architecture (R2): All safety invariants—specifically the Park-only gating on disruptive UI, the strictly enforced “No-Reboot Rule”, suspend-to-RAM watchdog survivability, and system UID privilege separation—are verified in code.
3. Live Hardware Documentation (R3): The user and developer documentation portal is backed by authentic, full-resolution (1920x1080) screenshots captured directly from the physical vehicle display via ADB.
4. Repository Hygiene & Governance (R4): The repository adheres to open-source governance best practices with an GPLv3 license, contributor guidelines, Conventional Commits standards, a sanitized gitignore, and an unreleased changelog staging section.

Release Constraint Confirmation: In strict accordance with user requirements, NO GIT RELEASE TAG HAS BEEN CREATED, NO EXTERNAL STORE/OTA ARTIFACT HAS BEEN PUBLISHED, AND NO AUTOMATED CI/CD RELEASE WORKFLOW HAS BEEN TRIGGERED. git tag -l reports only v0.1.0.

2. Objective Go / No-Go Checklist

The following table details every requirement across the 4 milestone areas, evaluating objective pass/fail criteria.

3. Detailed Release Readiness Matrix

Category A: Production Ready (Ready for Release Candidate)

The following components and subsystems have been thoroughly verified and meet all production criteria for the Geely IHU629G head unit:

1. Vehicle Hardware Communication Core (com.geely.drivemem.car):
   • CarActor single-threaded actor model serialized on dedicated HandlerThread.
   • In-memory event routing via EntityBus.
   • Cached property reads preventing main thread binder starvation.
   • Dynamic area ID resolution and readback verification for ambient lighting.
2. Vehicle Safety & Invariant Guards (com.geely.drivemem.util):
   • Dynamic Park check (CarState.isParked()) gating all intrusive dialogues and update flows.
   • Immediate dismissal of active dialogues upon gear shift from Park into Drive/Reverse/Neutral.
   • Total absence of OS-level reboot commands, preventing audio amplifier pop through cabin speakers.
   • 10-minute ELAPSED_REALTIME_WAKEUP watchdog alarm with MY_PACKAGE_REPLACED auto-rearm, ensuring survival across vehicle suspend-to-RAM cycles.
3. Privilege Architecture & Dual-APK Isolation:
   • Headless companion com.geely.modehelper operating with platform signature (android.uid.system, UID 1000) for package management and secure settings persistence.
   • User application com.geely.drivemem operating with standard sandboxed UID, eliminating the fatal Android 9 Chromium WebView crash.
   • IPC bounded by explicit component targets (setPackage("com.geely.modehelper")) and signature verification.
4. Database Subsystem (CarDb.java):
   • Complete compatibility with Android 9’s bundled SQLite 3.22.0 engine.
   • Absence of incompatible window functions (LAG()) and native UPSERT syntax.
   • Dedicated HandlerThread("cardb") single-writer queue eliminating database locks.
5. Unit Test Suite & Verification Baseline:
   • 131 tests passing across 15 test suites with 0 failures and 0 errors (100% pass rate).
   • Verified execution on both testDebugUnitTest and testReleaseUnitTest.
6. Quality Tooling & Static Analysis Pipeline:
   • JaCoCo coverage report generation (drivemem/build/reports/jacoco/test/jacocoTestReport.xml and HTML).
   • Android Lint baseline established with zero fatal errors.
   • Checkstyle configuration (config/checkstyle/checkstyle.xml) with Android rules.
   • SpotBugs configuration (config/spotbugs/exclude.xml) with filter rules.
7. Visual Documentation & Real Vehicle Screenshots:
   • Verified 1920x1080 RGBA PNG captures (comfort-view.png, daily-stats.png, telemetry-settings.png) stored in docs/screenshots/.
   • Comprehensive visual embedding across Docsify documentation and README.md.
8. Repository Governance & Cleanliness:
   • GPLv3 LICENSE file.
   • CONTRIBUTING.md with Conventional Commits, validation commands, and safety invariants.
   • Fully sanitized .gitignore excluding agent metadata, IDE, OS, and Python artifacts.
   • CHANGELOG.md with comprehensive ## [Unreleased] staging.

Category B: In-Progress / Remediated (Resolved During Audit)

The following issues were identified during the audit and have been successfully remediated and verified:

1. Basque Locale Runtime Crash (Resolved):
   • Finding: drivemem/src/main/res/values-eu/strings.xml:222 contained unescaped %100 (~%1$d min %100era arte). In Java String.format(), %100 was parsed as a 100th argument specifier, causing an UnknownFormatConversionException crash on Basque head units during charging.
   • Remediation: Escaped %100 to %%100. Verified via Android Lint StringFormatMatches passing with 0 errors.
2. Checkstyle Classpath Capability Conflict (Resolved):
   • Finding: Checkstyle 10.12.7 transitively brought com.google.collections:google-collections:1.0, causing Gradle 8.7+ to reject the configuration due to a capability conflict with com.google.guava:guava.
   • Remediation: Added explicit exclusion in drivemem/build.gradle:

     configurations.checkstyle {
         exclude group: 'com.google.collections', module: 'google-collections'
     }
     

   • Verification: ./gradlew checkstyle executes cleanly in 15 seconds.
3. SpotBugs Groovy DSL Enum Resolution (Resolved):
   • Finding: SpotBugs Gradle plugin 6.0.26 compiled Confidence with inner class Confidence$MEDIUM.class, causing Groovy Confidence.MEDIUM to resolve to Class instead of enum.
   • Remediation: Configured property using Confidence.valueOf('MEDIUM').
   • Verification: ./gradlew spotbugs executes cleanly without evaluation errors.
4. Credential & Personal Vehicle Identifier Exposure (Resolved):
   • Finding: Live ABRP API key committed in tools/configure-car.sh:322, private local broker IP in lines 275, 278, and 16 occurrences of personal partial VIN <PARTIAL_VIN> in docs/MQTT-GUIDE.md.
   • Remediation: Sanitized ABRP key to "", broker IP to tcp://homeassistant.local:1883, and partial VIN to 123456.
   • Verification: Automated git grep scans for private credentials (<PARTIAL_VIN>, <ABRP_KEY>, and <PRIVATE_BROKER_IP>) return exit code 1 (0 matches across all tracked git files).
5. Black Screenshot Capture Block (Resolved):
   • Finding: Live vehicle ADB screencaps produced blank 10 KB black PNGs due to SystemUI’s SheildLayerUtil standby lock when set_back_light == 0.
   • Remediation: Discovered, documented, and automated screen wake via settings put system set_back_light 1, capturing genuine 1920x1080 UI pixels, and restoring set_back_light 0.
6. Untracked Agent Workspace in Git Status (Resolved):
   • Finding: .agents/ and ORIGINAL_REQUEST.md appeared as untracked files in git status.
   • Remediation: Added .agents/, ORIGINAL_REQUEST.md, IDE, OS, and Python patterns to .gitignore.

Category C: Recommended Post-v1.0 Enhancements (Roadmap)

These non-blocking items represent architectural recommendations for post-v1.0 iterations:

1. Robolectric UI Unit Testing:
   • Current State: Unit test coverage is 5.55% overall, but UI classes (com.geely.drivemem.ui) and overlay services (com.geely.drivemem.services) have 0% JVM unit test coverage because they instantiate Android framework views directly.
   • Roadmap: Introduce Robolectric or decouple business logic from Activities into pure Java Presenter/ViewModel classes.
2. Secondary Locale Unescaped % Lint Warnings:
   • Current State: Seven non-English string resources (values-ca, values-hu, values-b+es+419, values-es-rUS, values-es, values-tl) have unescaped % signs in cfg_bar_soc (% a, % b, % e, % s), generating non-fatal StringFormatInvalid lint warnings.
   • Roadmap: Standardize all locale translations to escape % as %% across all language resource files.
3. Dynamic Home Gateway Subnet Configuration:
   • Current State: AdbGate.isHome() evaluates DEFAULT_HOME_GW = "192.168.0.1". Users with home subnets on 192.168.1.1 or 10.0.0.1 must modify this constant.
   • Roadmap: Expose the home gateway IP as a configurable preference in TelemetryActivity and configure-car.sh.
4. Incremental Static Analysis Clean-Up:
   • Current State: Checkstyle baselines 2,338 warnings (primarily indentation and javadoc formatting), and SpotBugs catalogs 117 issues.
   • Roadmap: Establish automated pre-commit formatters (e.g. Spotless) to systematically burn down formatting warnings in future releases.

4. Strict Release Constraint Confirmation

Under the mandate of this audit, strict constraints were placed on repository release operations:

1. Git Tag Status:
   • Executed: git tag -l
   • Output:

     v0.1.0
     

   • Confirmed: Exactly one tag (v0.1.0) exists in the repository. NO NEW GIT TAG WAS CREATED.
2. GitHub Actions Release Trigger Guard:
   • In .github/workflows/build.yml:113-115: ```yaml
     • name: Create Release on Tag if: startsWith(github.ref, ‘refs/tags/v’) uses: softprops/action-gh-release@v2 ```
   • Confirmed: Because no tag matching v* was pushed or created, no automated release pipeline has been triggered.
3. Release Script Suppression:
   • tools/push-release.sh was not executed.
   • origin/master was not modified or pushed.
4. Artifact Publishing:
   • Zero APKs or binaries were published to public stores, GitHub releases, or OTA endpoints.
   • All build artifacts generated during testing (drivemem/build/) remain machine-local and gitignored.

5. Verification Commands & Independent Replication

To independently verify the assertions made in this Release Readiness Matrix, execute the following commands in the repository root:

# 1. Verify Unit Test Suite & JaCoCo Coverage Report
./gradlew test jacocoTestReport
# Expected: BUILD SUCCESSFUL with 131 tests passing; reports in drivemem/build/reports/jacoco/test/

# 2. Verify Release Build Uninstrumented Assembly
./gradlew :drivemem:assembleRelease
# Expected: BUILD SUCCESSFUL; drivemem/build/outputs/apk/release/drive_assist.apk generated

# 3. Verify Static Code Analysis (Lint, Checkstyle, SpotBugs)
./gradlew lint checkstyle spotbugs
# Expected: BUILD SUCCESSFUL with 0 fatal errors

# 4. Verify Credential Sanitization
# Verify that no private broker IPs (<PRIVATE_BROKER_IP>), ABRP API keys (<ABRP_KEY>), or vehicle VIN suffixes (<PARTIAL_VIN>) appear in git
git grep -E "(abrp_api_key.*[0-9a-f]{8}-|mqtt_uri.*tcp://192\.)" || echo "CLEAN"
# Expected: Exit code 1 (zero matches across tracked files)

# 5. Verify Vehicle Safety Invariants
git grep -i "reboot" -- drivemem/
# Expected: Zero reboot commands in Android application source

# 6. Verify Screenshot Assets Integrity
file docs/screenshots/*.png
# Expected: 3 valid 1920x1080 RGBA non-interlaced PNG files

# 7. Verify Strict No-Release Tag Constraint
git tag -l
# Expected: Output MUST contain ONLY "v0.1.0"

# 8. Verify Repository Hygiene Status
git status
# Expected: .agents/ and ORIGINAL_REQUEST.md ignored; clean tree on dev branch