AXP Magisk resurrection track: Speckit 009 port AXP/LOS22 to LOS23.

Ship Magisk like GOLDEN; KernelSU optional recycle only; parallel to sunfish-a16-rom standby.

specs/001-development-environment/research.md

@@ -0,0 +1,110 @@
+# 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.