# Project Constitution: android-fs5

**Version**: 1.0.0
**Created**: 2026-03-02
**Status**: Active

## Preamble

This constitution governs all development decisions for the android-fs5 project —
a CLI toolset for managing the exone GmbH FS5 Android 9 device connected via USB/ADB.
These principles are NON-NEGOTIABLE and apply to every specification, plan, and task.

---

## Article I: Shell-First Principle

**MUST** implement all device interactions as composable shell scripts or Python CLI tools.
**MUST NOT** build GUI applications or web interfaces unless explicitly requested.

**Rationale**: Infrastructure tooling must be scriptable, automatable, and CI/CD-friendly.

---

## Article II: ADB as the Single Interface

**MUST** use ADB (Android Debug Bridge) as the exclusive communication layer with the device.
**MUST NOT** require rooted device access for core functionality.
**SHOULD** gracefully degrade when optional ADB features are unavailable.

**Rationale**: ADB is the standard, stable, and non-destructive interface for Android devices.

---

## Article III: Test-First Imperative (NON-NEGOTIABLE)

**MUST** write tests before implementation code.
**MUST** validate tests FAIL before writing implementation.
**MUST** validate tests PASS after implementation.
**MUST NOT** merge implementation without passing tests.

**Rationale**: Device management tools can cause data loss; correctness is paramount.

---

## Article IV: Idempotency

**MUST** design all operations to be safely re-runnable without side effects.
**MUST** check state before mutating (e.g., file exists before push, app installed before install).

**Rationale**: Scripts run in automation pipelines must not fail on second execution.

---

## Article V: Non-Destructive by Default

**MUST** default to read-only/dry-run mode for any destructive operation.
**MUST** require explicit `--force` or `--confirm` flags for delete/wipe operations.
**MUST** log all write operations with timestamps.

**Rationale**: Prevent accidental data loss on the connected device.

---

## Article VI: Device Identity Awareness

**MUST** target device by serial number (`RD51QE202392`) to prevent wrong-device operations.
**MUST** validate device connectivity before any operation.
**SHOULD** support multiple device profiles via configuration.

**Rationale**: ADB can connect to multiple devices; explicit targeting prevents mistakes.

---

## Article VII: Simplicity Gate

**MUST** use ≤3 top-level modules/scripts for the initial implementation.
**MUST NOT** add abstraction layers without documented justification.
**MUST NOT** future-proof beyond current requirements.

**Rationale**: Infrastructure tools rot when over-engineered.

---

## Article VIII: Structured Output

**MUST** support `--json` output flag on all commands for machine-readable results.
**MUST** use exit codes correctly (0=success, 1=error, 2=device-not-found).
**SHOULD** provide human-readable output by default.

**Rationale**: Tools must integrate with monitoring, logging, and automation pipelines.

---

## Article IX: Configuration over Hardcoding

**MUST** store device serial, paths, and settings in a `.env` or `config.yaml` file.
**MUST NOT** hardcode device serials or paths in script logic.

**Rationale**: Enables reuse across different devices and environments.