# AGENTS.md — AXP_Resurection

How agents must work in **this** repository (AXP Magisk resurrection track).
Global project rules live in `.specify/memory/constitution.md`. Per-feature
requirements live in `specs/*/spec.md`. Do not duplicate those documents here.

Sibling standby repo/workspace `sunfish-a16-rom` keeps the KernelSU /
split-roadmap track; do not merge those ship intents back into this tree
unless the owner explicitly asks.

## Scope

- This project is **independent of SSYSTEMS**.
- Do **not** apply SSYSTEMS `AGENTS.md`, Redmine, `r{ticket}_*` branches, company
  GitLab/MR workflows, or company Spec Kit conventions.
- Do **not** modify PVE / `pm-test01` / company Salt infrastructure from this
  repository. `rom-dev01` is assumed to already exist when host work begins.

## Sources of truth

1. **Constitution** (`.specify/memory/constitution.md`) — global project rules
   for this Magisk-resurrection track.
2. **Feature `spec.md`** — especially `specs/009-axp-los23-port/spec.md`.
3. Upstream / primary sources for LineageOS/AOSP, GrapheneOS, AXP.OS, DivestOS,
   Magisk, microG, and related projects — prefer these over secondary blogs
   or guesses. KernelSU docs are reference-only here (optional recycle).

## Clone AXP first (mandatory)

This track is an **AXP.OS → LOS23/A16** resurrection (~clone). Default method:

1. Find how AXP / EXTENDROM / GOLDEN did it **before inventing a local policy**:
   shipped PRO/GOLDEN zips (`payload.bin` → partition images),
   `/srv/rom/references/axp/` + EXTENDROM on `rom-dev01`, GOLDEN `adb`
   oracle, and real AXP product trees — **not** only Lineage-looking
   `upstream_*` mirrors on disroot.
2. **Copy that method** into this tree (same flags, same packaging shape, same
   virgin/activation UX where applicable).
3. Only invent or diverge when LOS 23.2, Android 16, or a newer dependency
   **breaks** the AXP path — then document why and the minimal fix.

Do **not** redesign Magisk, microG, Phonesky, DNS, connectivity, hardening
package sets, or other AXP-class features “our way” for convenience.
KernelSU/SusFS (`007`) stays **standby** — never mix into Magisk ship boots.

Magisk specifically: EXTENDROM `EXTENDROM_PREROOT_BOOT` (boot patch, Magisk
**not** a `PRODUCT_PACKAGE`, dormant until Additional Setup). See
`docs/009-magisk-preinstall-runbook.md`.

## Working rules

- Do not invent unresolved technical decisions; investigate them in the relevant
  feature spec (or create/clarify that spec first).
- `docs/axp-pro-parity.md` and `docs/hardening-backlog.md` are non-normative
  until a row is promoted into a feature `spec.md`.
- Prefer small, attributable, reversible changes.
- Never commit secrets, private keys, proprietary Google APKs, phone dumps with
  credentials/identifiers, `.repo`, `out/`, or ccache.
- Large Android trees and builds belong on `rom-dev01`, not on the laptop.
- On `rom-dev01`, never leave long `mka`/`ninja` jobs attached to laptop SSH;
  start them detached (`/srv/rom/artifacts/bin/rom-detach`, prefers **tmux**) and
  only poll status/logs with short connections.
- **Upstream freshness (mandatory):** for KernelSU/ReSukiSU, managers, modules,
  toolchains helpers, and similar moving deps, always take the **newest stable
  (or newest tagged pre-release the project currently ships)** that still fits
  sunfish / non-GKI 4.14 / LOS 23.2 — **not** a stale laptop cache, shallow
  clone, or “whatever was already on the host”. Before any long kernel/ROM
  build: `git fetch --tags`, confirm non-shallow history when version codes
  depend on `rev-list`, record tag/commit + version code, and ensure manager
  APK and kernel driver versions match. Lesson from `007`: a depth=1 ReSukiSU
  mirror produced bogus `KSU_VERSION=30701` after a full boot rebuild.
- Keep commits and patches source-attributed; do not dump opaque megapatches.

## Spec Kit workflow

Typical order: `/speckit-specify` → `/speckit-plan` → `/speckit-tasks` →
implement. Regenerate plan/tasks after meaningful `spec.md` edits.

- Do **not** use upstream `/speckit-taskstoissues` for this project; it is
  GitHub-specific. Gitea issue integration may be added separately later.