@1aboveio/skills 1.0.12 → 1.0.14

package/skills/app-dev/android-foundation/SKILL.md

@@ -1,248 +0,0 @@
----
-name: android-foundation
-description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for stuck Android debugging, post-deploy startup or rendering failures, Metro answering while the app does not render, UiAutomator failures, missing controls, ADB drops, harness-test failures, APK builds, assigned or fresh SDK/NDK/JDK workspace setup, and native journey validation. Before fixing and rerunning or redispatching a failed Android CI job, reproduce its failing checkpoint off CI: a rerun is not a debugger. Diagnose existing setups without rebuilding the whole environment. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
-release-version: 0.45.1
----
-**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
-# Android foundation
-
-Prove or debug a native Expo / React Native device journey using the repo's existing
-build scripts, native project, harness and wrapper. Use `github-actions` for CI YAML
-and runner integration. The CI template is a starting point; preserve existing workflows.
-
-Pick the mode first:
-
-- **Diagnosis:** an existing workspace or CI run fails or stalls. Follow
-  [Diagnosis](#diagnosis) first; a harness change does not automatically require a cold
-  setup. Re-run only the setup stages whose assumptions changed.
-- **Setup proof:** a new workspace or CI job, or a toolchain, dependency or native
-  change that invalidates setup. Run every stage and write the
-  [evidence record](#evidence-record).
-- **Feature work:** validating a product change in a workspace already set up. Follow
-  [Feature work](#feature-work): focused checks per candidate, targeted device checks
-  where needed, and integrated journeys at explicit checkpoints.
-
-## Routing
-
-| Step | Read |
-| --- | --- |
-| Workspace resolution, then shell snippets for every stage | [references/workspace.md](references/workspace.md), [references/setup.md](references/setup.md) |
-| Stages 6–8 in one command | [scripts/device-run.sh](scripts/device-run.sh) |
-| Adding the Android job to CI | [references/ci.md](references/ci.md), template [assets/android-ci-job.yml](assets/android-ci-job.yml) |
-| Proving a product change on the emulator | [Feature work](#feature-work) |
-| A stage failed or a worker appears stuck | [Diagnosis](#diagnosis), then [references/diagnosis.md](references/diagnosis.md) and [Triage](#triage) |
-| Writing up setup proof | [Evidence record](#evidence-record) |
-
-## Rules
-
-- Resolve the workspace first; [references/workspace.md](references/workspace.md) owns
-  precedence: an assigned isolated workspace and candidate HEAD win, feature work, fixes and
-  diagnosis reuse the owned workspace, and standalone setup creates one managed workspace
-  only with no usable assignment. Read its actual HEAD; never substitute `origin/main`, a new
-  branch or another checkout, mutate a peer's checkout or symlink its writable `node_modules`.
-- Tool shells keep no variables, functions or traps between calls. Write the environment
-  to `.cache/android-env.sh` once and source it at the start of every command. Use the
-  repo's existing owned-resource launcher. For a new local setup without one, use
-  `scripts/device-run.sh` for stages 6–8 in one command. Do not wrap an existing owner
-  with a second emulator/database lifecycle.
-- Keep local writable caches private under `.cache/`: Gradle home, Android user/AVD
-  homes, temporary files, npm, node-gyp and pnpm. In CI, an already isolated runner slot
-  may provide those paths; verify its ownership contract rather than layering another
-  cache system on top. Never share writable state across concurrent owners.
-- Read toolchain versions from the repo: the root `packageManager` and `engines`, the
-  native Gradle config, and the CI preflight. The repo is the source of truth, not this skill.
-- Check that every required SDK component (platform, build-tools, NDK, CMake,
-  platform-tools, emulator, system image) is already installed. If one is missing, stop and
-  provision it separately. Never upgrade or install into a shared SDK during a journey;
-  build with `-Pandroid.builder.sdkDownload=false`.
-- Install with `--frozen-lockfile`. Do not routinely run `clean`, reinstall dependencies or
-  run `expo prebuild`. The native project is tracked, and prebuild needs a reviewed native
-  change.
-- Build every configured ABI for setup proof and release acceptance. An x86_64-only CI
-  APK only proves the emulator ABI. For feature work, the emulator ABI is enough unless the
-  change touches native code or ABI configuration.
-- Determine how the selected build loads code and assets. A typical debug build needs
-  Metro; a release build normally embeds its bundle. Do not introduce Metro or debug
-  preferences into a release failure without evidence that the build uses them.
-  A successful build does not prove execution on a device.
-
-## Stages
-
-These are the full setup-proof stages, not a per-candidate checklist. For established
-workspaces, select checks under [Feature work](#feature-work). Run the selected stages
-in dependency order. Stop at the first failure and triage it.
-
-1. **Workspace and environment.** Resolve the assigned or standalone workspace
-   ([references/workspace.md](references/workspace.md)) and export the private cache paths,
-   `JAVA_HOME` (JDK 17), `ANDROID_HOME` and `ANDROID_SDK_ROOT`. Print the versions of
-   node, pnpm, java, python3, adb and the emulator. Assert that each SDK component
-   directory exists. Read the journey wrapper and device harness for the names they expect:
-   the venv path, the port variables, the database variables and the database-name prefix
-   the harness accepts.
-2. **Install and check.** Run a frozen install, the app's unit tests, typecheck, and
-   `expo export --platform android` with a placeholder `EXPO_PUBLIC_API_URL`. Create a
-   Python venv for UI automation at the path the journey wrapper reads, and pin the
-   `uiautomator2` version the harness expects.
-3. **Gradle dependencies.** Pick one:
-   - Seed: `rsync --ignore-existing` only `caches/modules-2/files-2.1/` from a trusted
-     Gradle home, excluding `*.lock`, `*.lck` and `*.tmp`. Never share writable caches,
-     metadata, credentials or APKs.
-   - Proxy: a private Gradle home does not inherit `~/.gradle/init.d`. Install the proxy's
-     init script into `$GRADLE_USER_HOME/init.d/` and export a route for every repository
-     the build uses, JitPack included. Ping the proxy first.
-   - Neither: build against upstream and expect a long cold build.
-   If the opted-in proxy fails, treat it as an error. Never fall back to direct downloads
-   and never disable TLS checks. The proxy covers Gradle Maven repositories only. Route the
-   Gradle wrapper ZIP and pnpm as the repo's CONTRIBUTING says.
-4. **Build.** Run the repo's Android build script with `--max-workers=2
-   -Dorg.gradle.parallel=false -Pandroid.builder.sdkDownload=false --console=plain
-   --info`, keeping the log. For setup proof, hash the APK and list its `lib/<abi>/`
-   entries.
-5. **Owned emulator.** Create a new private AVD in `$ANDROID_AVD_HOME` by copying only
-   `config.ini` from an installed AVD. Never copy its user data or snapshots. Check that
-   `image.sysdir.1` points to an installed, host-compatible image, and set `target` to
-   match it. Writing `config.ini` from scratch needs the hardware keys:
-   [gotchas](references/gotchas.md#a-hand-written-avd-misses-the-screen). Give the guest
-   4 GB: replace any `hw.ramSize` with `hw.ramSize=4096` (`device-run.sh` also passes
-   `-memory 4096`). At 2 GB, the usual `avdmanager` value, adb drops mid-journey ([gotchas](references/gotchas.md#the-adb-transport-drops-mid-journey)).
-6. **Register cleanup before starting anything.** `device-run.sh` installs the `EXIT`
-   trap and the `INT`/`TERM` handlers first.
-7. **Start resources.** The script refuses an emulator console port outside 5554–5584
-   (adb scans only that range) and any busy port, starts the ADB server, then the emulator
-   (PID recorded) and `postgres` (`--cidfile`, random loopback port), and waits for
-   `sys.boot_completed=1` and `pg_isready` with a time limit on every command.
-8. **Journey.** The script hands the harness a database named with its accepted prefix and
-   runs the journey wrapper. Expect every scenario's `PASS` marker, plus screenshots, the
-   backend log and the Metro log.
-
-## Owned-resource cleanup
-
-- Clean up only what this run started: the emulator child PID, the container ID from the
-  CID file, and the named database; these are short-lived, unlike the development workspace
-  and its private caches. Signal the PID with `TERM`, wait up to 10 seconds, then `KILL`.
-  Then `wait` for it and confirm nothing is left. Count wait status 0 or 143 (ended by your
-  `TERM`) as a clean stop; count a needed `KILL` or any other status as a failure.
-- Never use broad `pkill`, `docker system prune` or a shared `adb kill-server` for cleanup.
-  Use the live child's process owner, not an ADB serial that may be reused. A numeric
-  PID can also be reused after exit; it is not durable ownership evidence.
-- Give every startup, readiness and cleanup command a 30-second limit that kills the
-  command's whole process group. Treat exit 124 (timeout) as a terminal failure, not as
-  "not ready yet".
-- Preserve the stage's original non-zero exit status even when cleanup succeeds. Print
-  `original_stage_exit=<n> cleanup_exit=<n>`.
-- After SIGKILL or a host crash, verify recorded resources before recovery: process
-  start identity, command/run scope and boot identity where available, or container ID
-  and ownership labels. Never signal a numeric PID solely because an old record names
-  it. If ownership cannot be verified, leave it alone and report the gap. Keep logs.
-- For the local setup flow, point the database URL only at its disposable loopback
-  container. An existing isolated remote test flow must use its own disposable data and
-  ownership checks. Never use development, production or another worker's database for
-  fixture writes or cleanup. A public render-only smoke needs no database.
-- Expo may rewrite `android/tsconfig.json` or delete `android/expo-env.d.ts` while it runs.
-  Inspect those changes and restore them before you commit.
-
-## Delivery focus
-
-Read [references/delivery-focus.md](references/delivery-focus.md) before starting or
-continuing work. Keep an existing acceptance checkpoint, reuse available evidence,
-justify new infrastructure and carry failure history across workers. Required CI and
-the full acceptance criteria still apply; report delivered behavior before activity.
-
-## Diagnosis
-
-Follow the procedure below and [references/diagnosis.md](references/diagnosis.md).
-`diagnosing-bugs`, when available, can help with deeper hypothesis testing; it is not
-required to use this skill.
-
-The developer owns technical diagnosis. The coordinator owns its scope and broader
-acceptance scheduling. Failures in focused implementation validation stay with the
-developer within that task's scope. Failures after review handoff or in broader
-acceptance get a separate bounded diagnosis assignment, which may use the same developer:
-name the failed checkpoint, retained evidence, next question and return condition.
-Return scope growth or inconclusive evidence to the coordinator; do not silently extend
-implementation into a full acceptance campaign. Independent review checks the fix.
-
-1. Record the failed SHA, actual checkout, build variant, device type and retained
-   evidence. Locate the earliest failing stage: build/install → launch → load code/assets
-   → initialize → render → interact. Distinguish host/CI, harness, transport and product
-   failures; an absent screen alone does not identify which one failed.
-2. Choose the smallest test that can expose the suspected defect: a host test for logic,
-   real producer/consumer composition for a contract, or a device test for native/runtime
-   behavior. Collect evidence appropriate to that stage. A service probe proves only the
-   probe, not that the application used the same path.
-3. State competing explanations and a distinguishing observation. Change one variable.
-   For reversible defects, a failure → correction → failure comparison can strengthen
-   the finding; it is optional, not a gate. For intermittent failures, use a bounded,
-   repeatable trigger and compare failure rates. Do not replay Authentication or financial
-   actions merely to obtain a comparison.
-4. Keep the first exception and its evidence separate from cleanup errors. Bound the
-   full command and each subprocess wait, allowing the resource owner time to clean up.
-   A live worker or an outstanding tool call is not evidence of progress.
-5. Verify the fix at the failing checkpoint, then run the affected validation once.
-   Broader acceptance belongs to its scheduled integration or release checkpoint, not
-   automatically to this diagnosis assignment. Preserve any explicitly required gate.
-   Report local reproduction, source CI and post-deploy acceptance separately. A local
-   result on another API/ABI or a copied APK is not proof of the original CI artifact.
-
-Continue when the next attempt tests a new prediction, collects a missing observation,
-reduces the reproduction, or adds a justified sample for an intermittent failure. Name
-that purpose and bound its cost. Changing workers or repeating an unchanged run without
-such a purpose is not progress. When no available experiment distinguishes the remaining
-explanations, report the missing evidence or access instead of restarting the campaign.
-
-## Triage
-
-Name the earliest stage that failed. In CI, that is the first failed step. If the same
-journey passed on another run of the same commit, suspect the run or the journey before
-the product.
-
-| Stage | Typical signal |
-| --- | --- |
-| Prerequisites / install | missing SDK directory, wrong JDK, lockfile drift |
-| Harness unit tests (CI, before the APK) | a harness test fails on host state its fixture should fake (`requires 2 GiB reserve`) |
-| Export / APK | Metro bundling error, Gradle compile or dependency-resolution error |
-| Gradle network | Maven download or TLS-handshake errors on a cold build: fix routing, not code |
-| Emulator boot / ADB | `sys.boot_completed` never reaches 1, device offline, exit 124 |
-| Device to Metro | red box, "unable to load script", missing `adb reverse` mapping |
-| Bridge passes, debug app fails to load | possible app/probe endpoint mismatch; inspect the actual request before choosing a cause ([React Native example](references/diagnosis.md#example-react-native-debug-app-uses-another-metro)) |
-| Device to Metro, mid-journey | a screen's first Metro asset fails (`Unable to download asset from url: http://127.0.0.1:8081/assets/…`) while API calls still succeed |
-| Backend / Login | backend log errors, verification code not found in the database |
-| Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
-| adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
-| UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
-| Journey harness | a wait right after a navigation times out while the destination is on screen |
-| Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
-| Product assertion | a screen or state mismatch with a screenshot |
-
-Then match the signal against [references/gotchas.md](references/gotchas.md). If nothing
-matches, [confirm the suspected cause](references/gotchas.md#confirm-a-suspected-cause)
-before changing code.
-
-Preserve the failure evidence. Do not blindly replay steps that send codes, verify sessions
-or charge payments just to get a passing screenshot. One passing run does not prove the
-build is reliable.
-
-## Feature work
-
-Read [references/feature-work.md](references/feature-work.md) before validating a
-product change in an established workspace. Preserve required CI and acceptance gates.
-
-## Evidence record
-
-For setup proof only. Record:
-
-- Source SHA and the workspace root/path/base/branch/owner from the lifecycle record; host OS
-  and architecture, the Expo SDK, and the node, pnpm, JDK, Python and emulator versions.
-- System image API, image type and ABI. The AVD name, serial and ports are run
-  identifiers, not shared resources.
-- Each stage's exit status and duration.
-- The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
-  (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
-- The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
-  container removed, no listeners left on the backend or Metro ports.
-- Earlier failed or incomplete attempts. A later pass does not erase them.
-
-State what the run does not prove: tablet, accessibility (TalkBack), physical devices,
-signing, distribution, and any feature acceptance beyond the journey. Publish only
-sanitized evidence: no authentication codes, session cookies, customer data or raw
-payment payloads.

package/skills/app-dev/android-foundation/references/delivery-focus.md

@@ -1,31 +0,0 @@
-# Delivery focus
-
-Name one immediate checkpoint from the task's existing acceptance criteria: for example,
-open the app and render the expected screen. Keep that target visible while diagnosing;
-passing setup or adding helper code is not a substitute. Each independent work unit has
-its own checkpoint, so this does not serialize unrelated work.
-
-- Preserve a known-working source/artifact and relevant environment as a comparison when
-  one already exists. Do not start a baseline campaign or count that old artifact as proof
-  of the candidate. Reuse caches and valid results under the repo's ownership rules.
-- Run the smallest test that reaches the failing behavior. After it supports the fix,
-  complete focused validation and hand off to independent review. Run affected integrated
-  acceptance at its explicit plan checkpoint and preserve required CI; do not repeatedly
-  rebuild the full campaign to discover the next local defect or defer all journeys to
-  the final task.
-- Before adding a service, transport or test abstraction, state which existing criterion
-  needs it, why the current path cannot answer the question and the smallest alternative.
-  Make routine choices within authorization; preserve shared-resource and acceptance
-  approval boundaries. Do not expand infrastructure merely because a screen failed.
-- Every continuation states the current checkpoint, new evidence or concrete blocker,
-  and the next distinguishing test. Carry prior failures across worker changes. If
-  successive attempts leave the same checkpoint unproved, reassess and reduce the case
-  or change the approach before assigning another similar attempt. Diagnostics can guide
-  that decision but do not count as delivered functionality or reset coordinator limits.
-- Report behavior delivered and criteria still unproved first. Reuse existing results for
-  time to reproduce, time to verified fix and full CI runs when available; never invent
-  those measurements or create a reporting project to obtain them.
-
-When a coordinator owns the run, keep this context in its existing plan note and worker
-result. Follow its retry/replan rules; add no separate ledger, check or acceptance gate.
-

package/skills/app-dev/android-foundation/references/feature-work.md

@@ -1,50 +0,0 @@
-# Feature work
-
-Read the repository's validation and delivery policy first. Preserve required CI and
-acceptance gates; this skill does not authorize skipping them or rewriting project
-policy. Keep validation early without repeating the entire campaign per candidate.
-
-| Stage | Scope | Ownership |
-| --- | --- | --- |
-| Every candidate | Relevant tests, typecheck and applicable build/export checks; targeted device checks for runtime-sensitive behavior. | Developer validates, reports evidence and gaps, then hands off to independent review. |
-| Integration checkpoint | Affected journeys through combined changes. | Coordinator schedules a separate validation task as soon as its prerequisites are ready. |
-| Final acceptance | Remaining cross-feature, device-matrix and release obligations, plus checks invalidated by later changes. | Coordinator accounts for all required gates, reusing earlier evidence only within its proven scope. |
-
-- Name focused checks and integrated journey checkpoints in the plan before implementation,
-  with real prerequisites, an owner and observable results. Do not put all device testing
-  in the last task. Start independent ready work concurrently within device/host capacity
-  and existing ownership boundaries.
-- Choose the smallest check that proves the affected behavior. Host tests can prove logic
-  or a harness correction; native integration, navigation, keyboard, lifecycle and
-  accessibility changes need targeted owned-device evidence where host tests cannot prove
-  runtime behavior. A successful build/export alone is not device proof.
-- Use existing supported journey selectors. If the harness cannot select the affected
-  flow, report that limitation and schedule the smallest existing journey that covers it.
-  Do not invent a flag, weaken assertions or silently omit device validation. For example,
-  a filter change needs open/edit/apply/result evidence, not an unrelated payment campaign.
-- Reuse the workspace's private caches, venv and AVD configuration. Rerun setup stages only
-  when their assumptions change. Rebuild when build inputs change, using the emulator ABI
-  for focused work only where repository policy permits it. Do not require a fresh full
-  build or full journey solely because the candidate HEAD changed. APK reuse still needs
-  the source/configuration and artifact checks the repo requires; never relabel an old
-  artifact or result as current-source proof.
-- At each checkpoint, state what changed and which earlier evidence that change invalidates.
-  Reuse evidence only while source, configuration, artifact and environment remain applicable
-  to the claimed behavior. Required current-source CI still runs; evidence reuse cannot
-  replace a gate that requires a new run.
-- After a failed journey, local or a CI dispatch, enter Diagnosis mode and reproduce the
-  failing checkpoint off CI before running it again. A fake UI can reproduce a harness
-  navigation/scrolling bug; it cannot prove that the app loaded a bundle or rendered.
-  Show the fix passes at the appropriate boundary, then rerun the affected check once.
-  Never send a guessed fix to CI to see whether it passes. Use the Diagnosis continuation
-  rule for unreproduced or intermittent failures; report uncertainty until evidence
-  supports the cause.
-- Report source SHA, commands, results and remaining gaps at review handoff. For device
-  checks, include the selected scenarios, `PASS` markers and cleanup exit. For a failure,
-  name the earliest failing checkpoint and link retained evidence; preserve failed attempts.
-  Separate build duration, device-check duration and total worker time when discussing cost.
-- Broader device acceptance (all ABIs, tablet, TalkBack, physical devices, a release device
-  campaign) runs at the integration, release or campaign checkpoint the spec or repo assigns
-  it. Do not recreate it per feature or postpone affected runtime checks until release.
-  Record outstanding criteria as pending in their owning task or issue, never as passed.
-

package/skills/app-dev/android-foundation/references/setup.md

@@ -1,188 +0,0 @@
-# Android foundation: shell snippets
-
-Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
-functions or traps between calls: step 1 resolves the workspace and writes
-`.cache/android-env.sh`, which also `cd`s into it; every later block starts by sourcing it by
-absolute path, and steps 6–8 run as one command through the bundled `scripts/device-run.sh`.
-
-## 1. Workspace and environment
-
-Workspace precedence is owned by [workspace.md](workspace.md). Do not create a worktree,
-switch branch, fetch or reset when the caller supplied an isolated workspace.
-
-```bash
-set -euo pipefail
-ASSIGNED_WORKSPACE=<assigned-workspace-or-empty>
-CANDIDATE_HEAD=<candidate-head-or-empty>
-WORKSPACE="${ASSIGNED_WORKSPACE:?use the caller assignment or native-start result from workspace.md}"
-test -d "$WORKSPACE"
-git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null
-cd "$WORKSPACE"
-actual_head="$(git rev-parse HEAD)"
-test -z "$CANDIDATE_HEAD" || test "$actual_head" = "$(git rev-parse "$CANDIDATE_HEAD^{commit}")" || {
-  echo "workspace HEAD $actual_head != candidate $CANDIDATE_HEAD; report it; do not switch" >&2
-  exit 1
-}
-mkdir -p .cache
-{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; printf 'export ANDROID_SOURCE_HEAD=%q\n' "$actual_head"; } > .cache/android-env.sh
-cat >> .cache/android-env.sh <<'ENV'
-
-# Repo-specific names, read from the repo's journey wrapper and device harness.
-export APP_FILTER=<android-workspace-package>         # pnpm --filter target
-export DEVICE_PYTHON_DIR=<venv-dir-the-wrapper-reads> # e.g. the default in the wrapper
-export DB_NAME_PREFIX=<db-prefix-the-harness-accepts> # the harness rejects other names
-export DB_URL_VAR=<harness-admin-url-variable>        # e.g. SHARD_ADMIN_URL
-export DB_NAME_VAR=<harness-db-name-variable>         # e.g. SHARD_DB_NAME
-
-# Host paths. Example values are for Apple Silicon with Android Studio.
-export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
-export ANDROID_HOME="$HOME/Library/Android/sdk"
-export ANDROID_SDK_ROOT="$ANDROID_HOME"
-export SOURCE_AVD="$HOME/.android/avd/<installed-avd>.avd"
-export SEED_GRADLE_HOME="$HOME/.gradle"
-export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
-
-# Private caches.
-export GRADLE_USER_HOME="$PWD/.cache/gradle"
-export ANDROID_USER_HOME="$PWD/.cache/android-user"
-export ANDROID_AVD_HOME="$PWD/.cache/android-avd"
-export TMPDIR="$PWD/.cache/tmp"
-export npm_config_cache="$PWD/.cache/npm"
-export npm_config_devdir="$PWD/.cache/node-gyp"
-export PNPM_CONFIG_STORE_DIR="$PWD/.cache/pnpm-store"
-export PNPM_CONFIG_CACHE_DIR="$PWD/.cache/pnpm"
-case "${JAVA_TOOL_OPTIONS:-}" in *java.io.tmpdir*) ;; *)
-  export JAVA_TOOL_OPTIONS="${JAVA_TOOL_OPTIONS:+$JAVA_TOOL_OPTIONS }-Djava.io.tmpdir=$TMPDIR" ;; esac
-
-# Run identifiers: an even console port in 5554-5584 (adb scans only that range),
-# and backend/Metro ports under the names the journey wrapper reads.
-export SETUP_AVD=<new-unique-avd-name>
-export EMULATOR_PORT=<even-port-5554-5584>
-export ANDROID_BACKEND_PORT=<free-port>
-export ANDROID_METRO_PORT=<free-port>
-# Choose the whole-journey deadline; zero disables it and is not suitable for unattended runs.
-export JOURNEY_SECONDS=<positive-journey-timeout-seconds>
-ENV
-source .cache/android-env.sh
-mkdir -p "$TMPDIR" "$npm_config_cache" "$npm_config_devdir" \
-  "$ANDROID_USER_HOME" "$ANDROID_AVD_HOME" .cache/logs
-
-node --version; pnpm --version; java -version; python3 --version
-adb version; "$ANDROID_HOME/emulator/emulator" -version
-# Versions come from the repo's native config and CI preflight.
-for component in platforms/android-<api> build-tools/<build-tools> ndk/<ndk> cmake/<cmake>; do
-  test -d "$ANDROID_HOME/$component" || { echo "Missing SDK: $component" >&2; exit 1; }
-done
-```
-
-The recorded standalone path is reused on retries; verify its lifecycle record names this
-run, branch and base. If an assigned path is missing, is not a Git worktree, or is at another
-revision, stop and report instead of creating another checkout. Never fall back to
-`../<repo>-android-setup`.
-
-If the wrapper reads ports or Python under other names, export aliases in
-`android-env.sh` **as well as** the bundled runner's required names. For example,
-`export APP_METRO_PORT="$ANDROID_METRO_PORT"`; both must select the same port. Adapt
-`DB_URL_VAR` and `DB_NAME_VAR` to the actual harness, not its fallback defaults.
-
-## 2. Install and check
-
-```bash
-source <worktree>/.cache/android-env.sh
-pnpm install --frozen-lockfile --store-dir "$PWD/.cache/pnpm-store"
-pnpm --filter "$APP_FILTER" test
-pnpm --filter "$APP_FILTER" typecheck
-EXPO_PUBLIC_API_URL=https://app.invalid \
-  pnpm --filter "$APP_FILTER" exec expo export --platform android
-python3 -m venv "$DEVICE_PYTHON_DIR"
-"$DEVICE_PYTHON_DIR/bin/python3" -m pip install uiautomator2==<harness-pinned-version>
-```
-
-## 3. Gradle dependencies (pick one)
-
-Seed from a trusted Gradle home:
-
-```bash
-source <worktree>/.cache/android-env.sh
-mkdir -p "$GRADLE_USER_HOME/caches/modules-2/files-2.1"
-rsync -r --ignore-existing \
-  --exclude='*.lock' --exclude='*.lck' --exclude='*.tmp' \
-  "$SEED_GRADLE_HOME/caches/modules-2/files-2.1/" \
-  "$GRADLE_USER_HOME/caches/modules-2/files-2.1/"
-```
-
-Or wire a trusted Maven proxy into the private Gradle home. Append the exports to
-`android-env.sh` so the build in step 4 sees them. Route every repository the build uses,
-JitPack included; a route left unset goes straight upstream.
-
-```bash
-source <worktree>/.cache/android-env.sh
-cat >> "$PWD/.cache/android-env.sh" <<'ENV'
-export GRADLE_MAVEN_REPOSITORY=<proxy>/maven/
-export GRADLE_GOOGLE_REPOSITORY=<proxy>/google-maven/
-export GRADLE_PLUGIN_REPOSITORY=<proxy>/gradle-plugins/
-export GRADLE_JITPACK_REPOSITORY=<proxy>/jitpack/
-ENV
-curl --fail --silent --show-error --max-time 10 <proxy-health-url>
-install -d "$GRADLE_USER_HOME/init.d"
-install -m 0644 <path/to/proxy.init.gradle> "$GRADLE_USER_HOME/init.d/proxy.init.gradle"
-```
-
-## 4. Build
-
-```bash
-source <worktree>/.cache/android-env.sh
-pnpm build:android --max-workers=2 -Dorg.gradle.parallel=false \
-  -Pandroid.builder.sdkDownload=false --console=plain --info \
-  2>&1 | tee .cache/logs/gradle.log
-APK=<path/to/app/build/outputs/apk/debug/app-debug.apk>
-shasum -a 256 "$APK"            # sha256sum on Linux
-unzip -l "$APK" | grep -E 'lib/[^/]+/libreactnative\.so'
-```
-
-## 5. Owned emulator
-
-```bash
-source <worktree>/.cache/android-env.sh
-test -f "$SOURCE_AVD/config.ini"
-test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
-test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
-grep '^image.sysdir.1' "$SOURCE_AVD/config.ini"   # must be an installed, host-compatible image
-mkdir "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
-# Copy without the source's RAM size and give the guest 4 GB (gotchas: adb transport drops).
-grep -Ev '^hw\.ramSize[[:space:]]*=' "$SOURCE_AVD/config.ini" > "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
-echo 'hw.ramSize=4096' >> "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
-printf 'avd.ini.encoding=UTF-8\npath=%s\ntarget=android-<api>\n' \
-  "$ANDROID_AVD_HOME/$SETUP_AVD.avd" > "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
-```
-
-## 6–8. Cleanup, resources and journey: one command
-
-```bash
-source <worktree>/.cache/android-env.sh
-bash <skill-base-dir>/scripts/device-run.sh \
-  --drop node <path/to/device-harness.mjs> drop \
-  -- bash <path/to/foundation-journey-wrapper.sh>
-```
-
-Pass each command as separate words, not as one quoted string. The script:
-
-1. Registers the cleanup trap before anything starts.
-2. Refuses an emulator port outside 5554–5584 and any busy port.
-3. Starts the ADB server, then the emulator (its PID recorded), then `postgres` with
-   `--cidfile` on a random loopback port. Override the image with `POSTGRES_IMAGE`.
-4. Waits for `sys.boot_completed=1` and `pg_isready`. Startup/readiness and cleanup
-   commands have a 30-second limit (`BOUNDED_SECONDS`); exit 124 is terminal. The journey
-   uses the separate `JOURNEY_SECONDS` deadline. Leave time for cleanup after that deadline.
-5. Exports `$DB_URL_VAR`, `$DB_NAME_VAR` (`$DB_NAME_PREFIX` plus a unique suffix) and
-   `ANDROID_EMULATOR_SERIAL`, then runs the journey.
-6. Drops the database, stops the emulator PID (`TERM`, then `KILL` after 10 seconds),
-   removes the container by its CID, and prints `original_stage_exit=<n> cleanup_exit=<n>`.
-   It exits with the journey's status if the journey failed, else the cleanup status.
-
-The runner supervises the journey's process group. Journey children must stay in that
-group; a wrapper that deliberately creates detached services must stop those services
-through its own owner. Send TERM to the launcher and allow its cleanup to finish rather
-than killing it immediately. The generic runner inherits the caller's ADB endpoint and
-does not stop that server: use a verified private endpoint on a shared host and close it
-through the caller's owner. Capture the command's exit status and final summary line.

package/skills/app-dev/android-foundation/references/workspace.md

@@ -1,81 +0,0 @@
-# Android workspace lifecycle
-
-The coordinator or caller owns workspace selection. Resolve it once, before any setup stage,
-and record the result. This reference owns only that lifecycle: private caches, SDK isolation,
-emulator ownership and process cleanup stay in [setup.md](setup.md) and
-[Owned-resource cleanup](../SKILL.md#owned-resource-cleanup).
-
-## Precedence
-
-1. **Assigned workspace and candidate HEAD.** When the caller supplies an isolated workspace
-   and a candidate HEAD, use that workspace and that revision. Do not create a worktree or
-   branch, fetch, reset or switch revisions. Read `git rev-parse HEAD` and report it as the
-   source SHA. If it differs from the candidate HEAD, stop and report the mismatch; never
-   switch the workspace to match.
-2. **Existing owned workspace.** Feature work, fixes and diagnosis reuse the workspace this
-   run or unit already owns, with its private caches, venv and AVD profile. Do not make a
-   second workspace for a retry, a correction or a read-only investigation.
-3. **Standalone fresh setup.** Only when the coordinator reports no usable assignment. Create
-   one managed workspace at
-   `<repo>/.resolve-issues/rush/<run-id>/units/native`. Never create a sibling checkout such
-   as `../<repo>-android-setup`, and never add a second managed path for a retry.
-
-Android and iOS setup in the same run share that one managed workspace; their private cache
-subdirectories and short-lived processes stay separate.
-
-An assigned path that is missing, is not a Git worktree, or is at another revision is not an
-invitation to substitute a fresh checkout: stop and report it. For diagnosis, name the actual
-checkout and HEAD and confirm it contains the failing code; the repository root or another
-checkout may lag the candidate.
-
-## Record before creating
-
-The bundled `scripts/workspace-runtime` is generated from the shared lifecycle
-engine and ships with this skill. Only for standalone fresh setup, run:
-
-```bash
-node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-start --repo <canonical-root> \
-  --platform android --target <verified-target-branch> --base <candidate-SHA> --json
-```
-
-The command records root, owner, exact base, branch, workspace and disposable cache
-paths before creating anything. Use its returned `workspace` as `ASSIGNED_WORKSPACE`
-and `sourceSha` as `CANDIDATE_HEAD` in setup. Keep `run` and `runId`; repeat with
-`--run-id <returned-run-id>` and the same base, target and kind for retries. Never
-invoke it inside a coordinator-assigned unit. It never substitutes `origin/main`
-for the requested source or resets an existing workspace.
-For a package below the root, pass `--native-dir <package-root-containing-android>`.
-Declare other installs or build directories before use with repeated
-`--disposable <exact-workspace-relative-path>`, including package-local `node_modules`.
-
-## Development workspace vs short-lived processes
-
-The workspace, its private caches under `.cache/`, its venv and its AVD profile are
-development resources: retain them across retries and fixes, and keep them private to this
-workspace. Never relocate them to a global cache or share them with a concurrent owner.
-
-Emulators, containers, databases, Metro and ADB endpoints are short-lived: start only those
-the selected checks need and stop only the ones this run started, under the existing
-[cleanup rules](../SKILL.md#owned-resource-cleanup). Never delete a worktree, remove a cache
-with a chmod or `rm` pattern, or use a broad kill to end a process.
-
-A read-only diagnosis does not require a clean environment. Reuse the owned workspace and its
-caches, create only the services the observation needs, and preserve the failed environment's
-evidence. Do not rebuild, reinstall or re-provision merely because the failure is being
-investigated.
-
-## Completion
-
-At the end of the assignment, return the workspace, its cache paths and any retained process
-records to the coordinator for final cleanup. The coordinator owns deletion and retention.
-Register the path with the run's cleanup owner so final cleanup can tell a delivered
-standalone run from unfinished or unpublished work.
-
-- A successful, delivered standalone run must not retain an unbounded cache: mark the
-  workspace and its disposable caches for final cleanup. After stopping its owned
-  services, run `node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-finish --run <run> --json`
-  from the owner checkout. This uses the same cleanup engine as issue workflows.
-- Unfinished or unpublished standalone work keeps the workspace and caches for the next
-  attempt; report what is retained and why.
-
-The parent lifecycle record is authoritative for ownership, retention and final cleanup.