# Research: 001-development-environment

Phase 0 decisions for planning. Implementation may refine versions using live
primary docs on `rom-dev01`.

## R1 — Gitea access model

**Decision**: Bind Gitea to loopback (or other non-public address) and access via
SSH local port forward from the laptop. Do not require public HTTPS exposure.

**Rationale**: Constitution/`001` require private project Git without unnecessary
Internet exposure; single developer; SSH already required for admin/Remote SSH.

**Alternatives considered**:
- Public HTTPS + firewall allowlist — rejected for `001` (more moving parts;
  accidental exposure risk).
- VPN-only bind — rejected as a *required* path (may exist externally; project
  must not depend on company VPN).

## R2 — Semaphore access model

**Decision**: Same as Gitea — loopback/non-public + SSH tunnel. First job is an
**unprivileged** localhost/environment smoke playbook only (facts + path/tool
asserts). No sudo credentials in Semaphore for `001` smoke.

**Rationale**: Semaphore is orchestration UI, not a public portal; Android build
pipeline is explicitly out of scope for `001`; avoid baking privileged secrets
into the first integration.

**Alternatives considered**: Public Semaphore — rejected. Full ROM pipeline in
Semaphore — deferred past `003` manual first build. Privileged playbooks —
later explicit decision.

## R3 — Off-VM Git history backup

**Decision**: Laptop-initiated **bare mirrors** (`git clone --mirror` /
`git remote update`) of the four Gitea repos for `001` (SC-007). Laptop pulls;
VM does not SSH into the laptop. Borg/full Gitea DR later.

**Rationale**: Spec requires off-VM copy of project Git history, not a complete
backup platform. Pull-from-laptop avoids opening inbound access on the laptop.

**Alternatives considered**: Borg-only — optional later. Push-from-VM to laptop
— rejected (would require laptop inbound SSH).

## R4 — Lineage/AOSP host dependencies

**Decision**: At implement time, follow **current primary LineageOS / AOSP host
build documentation** for Ubuntu; record installed package set in logs. Do not
freeze a long package list in the plan.

**Rationale**: Dependency lists drift; stale pins cause false confidence.

**Alternatives considered**: Copy a historical package list from blogs —
rejected.

## R5 — `repo` installation source

**Decision**: Install Google's `repo` launcher via the method recommended by
current Lineage/AOSP docs (typically curl to `~/bin/repo` or distro package if
still adequate); verify `repo --version` as `android-build`.

**Rationale**: Align with upstream bring-up docs used for `003`.

## R6 — ccache policy vs build parallelism

**Decision**: `001` configures `CCACHE_DIR=/srv/rom/ccache` (or equivalent),
ownership for `android-build`, and a disk size cap. Document host capacity
(6 vCPU / 52 GB / 32 GB swap). **Defer `-j` / OOM tuning to `003`.**

**Rationale**: ccache is storage/env; parallel link/compile jobs belong to the
first real build feature.

**Alternatives considered**: Encoding `-j$(nproc)` defaults in `001` — rejected
as premature and confusing with FR-007 (document capacity; don't run builds).

## R7 — Meta-repo bootstrap before Gitea

**Decision**: Copy laptop staging Git tree to host path
`/home/android-build/sunfish-a16-rom` first (rsync/scp/bundle preserving
`.git`), install Gitea, create repos, push, then mark Gitea canonical. Keep
laptop staging until mirror verified. Ansible/automation lives in
`sunfish-rom-build`, not in the meta Spec Kit tree.

**Rationale**: Avoid chicken/egg `git clone` against non-existent Gitea; keep
Cursor edit path single and clear.

## R7b — Gitea Git transport vs OpenSSH base

**Decision**: UI via loopback + SSH tunnel. Exact Git clone/push transport
chosen at implement after host inspection (tunneled HTTP and/or tunneled Git
SSH are valid). Do not assume a public secondary SSH port for Gitea; do not
blindly edit `saltenv=base`-managed sshd.

## R8 — Coexistence with `saltenv=base`

**Decision**: Preflight + stop/report on conflicts with base-managed config.
Project Ansible may manage **project** paths/services; must not silently rewrite
Salt-owned system policy.

**Rationale**: Host is dual-touched (SSYSTEMS base then project). Fighting Salt
causes flapping.

## R9 — data-model / contracts

**Decision**: No application domain model or HTTP API contracts for `001`.
Operational entities only in `data-model.md`. `contracts/` marked N/A.

**Rationale**: Infrastructure bootstrap feature; inventing APIs would be template
noise.