@1aboveio/skills 1.0.7 → 1.0.9

package/README.md

@@ -23,6 +23,28 @@ using the copies. Run `/reload` after the first start.
 
 Each package also publishes on its own; install either this bundle or the packages, not both.
 
+## Native Codex plugin
+
+This bundle also carries a generated recursive compatibility manifest. The shared Codex
+catalog remains inactive until publication and native certification pass. Codex loads skills
+only; it does not run the Pi extension or selection command and installs no global hooks.
+
+Select the invoked bundle explicitly. Its package.json nativeCodex field records the resource
+metadata path, SHA-256 and release identity. Save those pins and the absolute root in the run;
+resolve canonical dependencies with engineering-runtime/scripts/installation-resolver.mjs,
+and pass verified absolute paths to workers. Keep observed Codex namespaced identities separate
+from canonical names. Never search other caches, fall back to a shared namesake, or install
+missing dependencies implicitly. Shared Pi and Claude copies are preserved.
+
+Engineering capture: node <active-resolve-issues>/scripts/active-installation.mjs capture.
+Save its descriptor as run-level installation in task-plan.json. After resume run the selected
+resolve-issues/scripts/rehydrate.mjs --cwd <project> and read its verified instruction paths.
+Standalone source and flat installations keep their existing behavior.
+
+Codex CLI 0.164.0 local packed discovery is tested. Model-driven worker spawning and native
+compaction/resume still need an isolated run with run-owned credentials before launch.
+See https://github.com/1aboveio/ai/blob/main/docs/native-codex.md for prerequisites and limits.
+
 ## Packages
 
 | Package | Also published as | Skills |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,15 @@
     "skills",
     "bin",
     "extensions",
+    ".codex-plugin",
     "README.md"
   ],
+  "nativeCodex": {
+    "schemaVersion": 1,
+    "metadataPath": ".codex-plugin/resources.json",
+    "metadataDigest": "a136e6a3363e03951e15d3a9e47dbac22e8c01f98efb18cadb317ffb270901b8",
+    "releaseIdentity": "9954a993488d48d15d61488ba06329a6dbc771bcf14c552a3463d68dc31fab26"
+  },
   "pi": {
     "skills": [
       "./skills"
@@ -251,7 +258,7 @@
         ]
       }
     ],
-    "digest": "e43aa391027a19aadfeee683b00d0ab16b6ffdfe622a5b1652c730bc55fd85a5"
+    "digest": "1fb2babf7dc0e9afde23727b28f8609f67c96758ae2835747e81a8d7139afae1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/app-dev/airflow/SKILL.md

@@ -2,7 +2,7 @@
 name: airflow
 description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
 user-invocable: true
-release-version: 0.43.0
+release-version: 0.44.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

package/skills/app-dev/airflow/release-check.mjs

@@ -2,7 +2,7 @@
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -46,6 +46,8 @@ function writeCache(path, value) {
 
 function main(now = Date.now()) {
   if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const bundle = readJson(join(resolve(here, '../../..'), 'package.json'));
+  if (bundle.name === '@1aboveio/skills' && bundle.nativeCodex?.schemaVersion === 1) return;
   const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
   const name = frontmatterValue(skill, 'name');
   const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));

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

@@ -1,20 +1,22 @@
 ---
 name: android-foundation
-description: "Prove an Expo / React Native app on a native Android emulator, and fix it when that proof fails. Use before you fix and re-run or re-dispatch a failed Android CI job (`gh workflow run android.yml`, `gh run rerun`): a re-run is not a debugger, so reproduce the failing journey checkpoint off CI first. Also use when a UiAutomator journey or its Python harness tests fail (a CHECK/FAIL line, a wait that timed out, a control not found, adb offline, a lost Metro bridge, a fixture failing on the runner), to build the debug APK and run the device journey, to set up a fresh Android workspace (SDK/NDK/JDK, Gradle caches, private AVD, disposable PostgreSQL), or to add the emulator job to CI. 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.43.0
+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, fresh SDK/NDK/JDK workspaces, 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.44.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android foundation
 
-Take a native Expo / React Native Android workspace from a fresh checkout to a passing
-device journey, then record the evidence. Use the repo's existing build scripts, native
-project, device harness and journey wrapper. For CI, add one job to the repo's `ci.yml`
-from the template; do not write a separate release runbook.
+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:
 
-- **Setup proof:** a new workspace or CI job, a toolchain, dependency, native or harness
-  change, or a broken build-to-device path. Run every stage and write the
+- **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:** proving a product change on the emulator in a workspace already set
   up. Follow [Feature work](#feature-work) and report only the journey result.
@@ -27,18 +29,24 @@ Pick the mode first:
 | 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 | [Triage](#triage), then [references/gotchas.md](references/gotchas.md) |
+| 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
 
-- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
-  another checkout, and never symlink another worktree's `node_modules`.
+- Use an isolated checkout. For new work, branch from `origin/main`; for diagnosis,
+  pin the failed source SHA or the reviewed correction. Confirm the checkout actually
+  contains the failing code: the repo root may lag active workspaces. Never 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. Run stages
-  6–8 as one `scripts/device-run.sh` command, never as separate calls.
-- Keep every cache private to the worktree under `.cache/`: Gradle home, Android user home,
-  AVD home, `TMPDIR`, npm, node-gyp and pnpm store. Keep them between runs.
+  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,
@@ -51,8 +59,10 @@ Pick the mode first:
 - 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.
-- A debug APK needs Metro. A successful export or build does not prove the app works on
-  a device. Only the device journey does.
+- 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
 
@@ -106,21 +116,64 @@ Run them in this order. Stop at the first failure and triage it.
   CID file, and the named database. 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 `adb kill-server`, `adb -s <serial> emu kill`, broad `pkill`, or
-  `docker system prune`. An ADB serial can be reused by another process; a PID you own
-  cannot.
+- 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 a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
-  PID and container ID by hand, and keep the failure logs.
-- Point the database URL only at the disposable loopback container. Never at development,
-  production or another worker's database.
+- 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.
+
+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 applicable acceptance once.
+   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
@@ -135,6 +188,7 @@ the product.
 | 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`) |
@@ -156,16 +210,20 @@ build is reliable.
 
 - Reuse the workspace's caches, venv and AVD configuration. Rerun a setup stage only when
   the change touches what it proves (toolchain, dependencies, native code, harness).
-- Build the emulator ABI and run `scripts/device-run.sh` once per candidate HEAD.
-- After a failed journey, local or a CI dispatch, reproduce the failing checkpoint off CI
-  before you run it again: in the harness unit tests with the fake UI scripted to the
-  failing screen, or on the owned emulator. Show the fix passes there, then run the journey
-  once to confirm. Never send a guessed fix to CI to see whether it passes; a failure you
-  cannot reproduce earns one more run, with added diagnostics, then goes in the report as
-  unreproduced.
-- Report the source SHA, the journey command, its `PASS` markers or the failing stage,
-  and the cleanup exit. Nothing else: no APK hash, version inventory, screenshots, copied
-  logs or earlier attempts.
+- Build the emulator ABI when its inputs changed and run the repo's owned journey
+  command once per candidate HEAD. A reused APK needs the source/configuration checks
+  the repo requires; record its hash and any provenance gap during diagnosis.
+- 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 seam, then run the journey once to confirm.
+  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.
+- For a passing feature run, report the source SHA, journey command, `PASS` markers and
+  cleanup exit. For a failure, also name the earliest failing checkpoint, link retained
+  evidence and state what remains unproved; use the diagnosis report instead of hiding
+  the failed attempts.
 - Integrated device acceptance (all ABIs, tablet, TalkBack, physical devices, a release
   device campaign) runs at the release or campaign gate the spec or repo assigns it. Do
   not recreate it per feature. Record it once, as pending, in its owning issue, never as

package/skills/app-dev/android-foundation/assets/android-ci-job.yml

@@ -107,6 +107,12 @@ jobs:
           ' "$props" "$mirror"
           grep '^distributionUrl=' "$props"
 
+      # Prerequisite: runner slots own their writable caches and Android homes.
+      # Otherwise export job-private paths to GITHUB_ENV before install so every
+      # subsequent step (including the emulator action) inherits the same paths.
+      - name: Verify writable runner isolation
+        run: <runner-cache-and-home-isolation-preflight-command>
+
       - name: Install dependencies
         timeout-minutes: 12
         run: pnpm install --frozen-lockfile
@@ -116,6 +122,7 @@ jobs:
           pnpm --filter <android-workspace-package> test
           pnpm --filter <android-workspace-package> typecheck
 
+      # Optional: only after measurement, and never for persistence/recovery tests.
       - name: Relax durability on the disposable Postgres
         env:
           PG_CONTAINER: ${{ job.services.postgres.id }}
@@ -138,9 +145,7 @@ jobs:
         timeout-minutes: 30
         env:
           EXPO_PUBLIC_API_URL: https://app.invalid
-          ANDROID_USER_HOME: ${{ github.workspace }}/.cache/android-user
         run: |
-          mkdir -p "$ANDROID_USER_HOME"
           cpus="$(nproc)"
           if [ -r /sys/fs/cgroup/cpu.max ]; then
             read -r quota period < /sys/fs/cgroup/cpu.max
@@ -148,7 +153,7 @@ jobs:
           fi
           echo "gradle max-workers=$cpus (nproc=$(nproc))"
           <android-project>/gradlew --project-dir <android-project> :app:assembleDebug --no-daemon \
-            -PreactNativeArchitectures=x86_64 --max-workers="$cpus"
+            -PreactNativeArchitectures=x86_64 -Pandroid.builder.sdkDownload=false --max-workers="$cpus"
 
       - uses: actions/setup-python@v5
         with:
@@ -172,8 +177,9 @@ jobs:
       - name: Device journey
         uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
         env:
-          SHARD_ADMIN_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
-          SHARD_DB_NAME: <ci-db-name>
+          # Replace these keys too; the harness owns their names and database prefix.
+          <harness-admin-url-variable>: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
+          <harness-db-name-variable>: <ci-db-name>
         with:
           api-level: <emulator-api>
           arch: x86_64
@@ -182,8 +188,8 @@ jobs:
           enable-hw-keyboard: true
           emulator-port: ${{ env.ANDROID_EMULATOR_PORT }}
           cores: 4
-          # At 2 GB (the usual AVD value) the guest kernel's vsock allocations fail and adb drops
-          # mid-journey, taking every adb reverse with it (references/gotchas.md).
+          # Default for this sample. The documented guest-memory ADB failure occurred
+          # on specific images; a transport drop alone does not establish that cause.
           ram-size: 4096M
           disable-linux-hw-accel: false
           script: bash <path/to/foundation-journey-wrapper.sh>

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

@@ -1,13 +1,16 @@
 # Android CI
 
-Add an Android job to the repo's one `ci.yml`: build the debug APK and run the foundation
-journey on an emulator. Copy [assets/android-ci-job.yml](../assets/android-ci-job.yml) and
-fill every `<placeholder>`. Follow the `github-actions` skill for the `changes` job, the
-`gate` job, runner labels, pinning and hardening; this file covers only what is Android-
-specific.
+Integrate the Android build and journey into the repo's existing CI. For a new
+`changes` → area jobs → `gate` design, adapt
+[assets/android-ci-job.yml](../assets/android-ci-job.yml) and fill every placeholder.
+Use `github-actions` for workflow structure, required checks, runner labels, pinning and
+hardening. Do not replace existing required checks or workflows just to match this example.
 
 ## Wire it in
 
+The following is an example for a new gate-based workflow; retain an established repo's
+trigger and required-check contract unless changing it is part of the task.
+
 1. Add an `android` filter to the `changes` job: the app workspace, the native project,
    the backend code the journey drives, the device harness and journey scripts, the
    lockfile, and `ci.yml`. Leave docs out.
@@ -34,13 +37,18 @@ specific.
   `$GITHUB_ENV` and start the ADB server on its own port.
 - Size Gradle from the cgroup CPU quota (`/sys/fs/cgroup/cpu.max`), not `nproc`. `nproc`
   reports every host core and thrashes the native build.
+- Verify each runner slot owns its writable Gradle, Android user/AVD, temporary, npm,
+  node-gyp and pnpm state. If the runner image already isolates these, keep that contract.
+  Otherwise configure private job paths before install and export them to every later
+  step, including the emulator. A step-local Android home is insufficient.
 - Route the Gradle wrapper distribution and Maven repositories through the runner's
   dependency proxy when it has one. Fail when the proxy variable is missing; never fall
   back to direct downloads.
 
 ## Build
 
-- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon`. Report
+- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon` and
+  `-Pandroid.builder.sdkDownload=false`. Report
   this APK as emulator evidence only. The all-ABI build stays a local or release step.
 - Bundle the JavaScript with `expo export --platform android` before the native build so
   bundling errors fail fast.
@@ -49,8 +57,10 @@ specific.
 
 ## Database and journey
 
-- Run PostgreSQL as a job service on a random host port, with a health check. Turn off
-  `fsync` and `synchronous_commit` on it: the database is disposable.
+- Run PostgreSQL only when the journey needs it, as an isolated service with a random
+  host port and health check. Disable durability only when measured and when the tests
+  do not exercise recovery/persistence semantics. Discover the harness's database variable
+  names and required database prefix; map the service explicitly without shared fallbacks.
 - Run the native auth/integration tests against that service before the device journey.
 - Unit-test the device orchestration scripts (journey wrapper, slot allocator, code
   lookup) before booting the emulator.
@@ -75,11 +85,11 @@ specific.
   and whether it scrolls, and the runner's free disk at preflight. A repo that uploads no
   capture needs these in the log.
 - Upload the APK with `if-no-files-found: error`.
-- Treat one green run as one run. Fix flaky device failures at their cause instead of
-  rerunning, and do not change product code for them. An adb drop after boot means guest
-  RAM ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)). A `RemoteDisconnected`
-  with the adb transport still up means the uiautomator2 server was relaunched
-  ([gotchas](gotchas.md#remotedisconnected-right-after-a-new-process-connects)).
+- Treat one green run as one run. Investigate intermittent device failures rather than
+  retrying without a purpose. An ADB drop may match the documented guest-memory issue;
+  confirm its transport/kernel evidence before choosing that fix. `RemoteDisconnected`
+  with transport still up may match a server restart; verify server/process evidence.
+  These are hypotheses, not universal diagnoses; see [gotchas](gotchas.md).
 
 ## Traps
 

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

@@ -0,0 +1,29 @@
+# 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,
+  run affected acceptance and required CI; do not repeatedly rebuild the full campaign
+  to discover the next local defect.
+- 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/diagnosis.md

@@ -0,0 +1,136 @@
+# Diagnose an existing Android failure
+
+Use the smallest investigation that can distinguish the remaining explanations. Reuse
+established resources and caches; do not build a second test platform to explain one
+failure. This procedure works without another diagnosis skill.
+
+## Locate the failing stage
+
+First identify the failed source, actual checkout, build variant, artifact provenance,
+device/API/ABI and last successful checkpoint. Do not diagnose an old repo checkout
+as though it were the running candidate. Determine whether code/assets are embedded,
+served by a development server, or delivered through another mechanism.
+
+| Stage | Useful evidence and smallest starting point |
+| --- | --- |
+| Build/install | First failing compiler, linker, dependency or package-manager operation; reproduce the affected task before booting a device |
+| Launch | Package and Activity, process start/exit, exception or crash record; use the affected device/runtime when necessary |
+| Load code/assets | Actual resource source and load result; for embedded assets inspect packaging/runtime errors, for remote assets inspect the app's actual request and response |
+| Initialize | Startup exception, configuration, service calls or producer/consumer contract; use a focused host/integration test where it reaches the defect |
+| Render | Foreground Activity, screenshot or hierarchy, runtime errors; distinguish missing rendering from a wrong selector |
+| Interact | State transitions and event ordering around the action; use a deterministic trigger or a bounded repeated lifecycle sequence |
+
+Select evidence by stage. A failed compiler does not need a screenshot. A release APK
+with embedded JavaScript does not need Metro. A physical device does not inherit the
+stock emulator's host alias. Preserve the actual failure environment when those
+properties may affect the cause.
+
+## Choose a test that can expose the defect
+
+- Use a host test when it executes the real defective logic or process lifecycle.
+- Compose the actual producer and consumer for serialization/protocol defects. Separate
+  tests with handwritten fixtures can pass while the integrated path fails.
+- Use the real app/device for native networking, rendering, Activity lifecycle, keyboard
+  or runtime behavior that a host double cannot exercise.
+
+A fake hierarchy containing the expected screen can prove selector handling, ordering
+or error classification; it cannot prove that the app loaded code and rendered that
+screen. Likewise, a service readiness probe does not establish that the app used the
+same endpoint. Observe the relevant application operation, not just its prerequisite.
+
+State competing explanations and what each predicts. Change one relevant variable
+while keeping the others fixed. A failing regression test followed by a passing
+correction may be sufficient. For a safe reversible defect, an optional A/B/A comparison
+can strengthen causal evidence: reproduce, apply one correction, restore that setting
+and see whether the failure returns. Do not make A/B/A a gate for every bug, and do not
+replay authentication, financial or other non-idempotent actions merely to obtain it.
+
+For intermittent failures, preserve the trigger conditions, record failures/attempts and
+use a bounded repeated sequence. Fix randomness or timing inputs where appropriate;
+compare baseline and corrected behavior under equivalent conditions. One passing run
+cannot establish reliability, and another sample is justified only when it answers a
+stated question. Do not claim certainty from a small sample.
+
+## Preserve evidence and resource ownership
+
+Capture the evidence needed for the failing stage before cleanup deletes it. Preserve
+the earliest exception separately from cleanup status; a cleanup timeout must not
+replace the original error. Keep raw logs private under the repo's retention rules and
+outside a checkout the next job deletes. Publish only sanitized findings. If original
+logs are gone, state that limitation rather than treating a new reproduction as the
+historical recording.
+
+Use the repository's established launcher and resource owner. Keep peers' devices,
+ports, databases and writable caches untouched. A borrowed physical device is not a
+disposable AVD: do not reset it or clear its data without task authorization. Reuse a
+shared preparation helper when callers have the same contract, while preserving
+caller-specific behavior that is actually required.
+
+A report needs the failed/tested sources, relevant artifact and environment differences,
+reproduction command, controlled change, observations, evidence locations, primary and
+cleanup outcomes, and remaining uncertainty. Do not require an APK hash for a compiler
+failure that produced no APK.
+
+## Bound work and distinguish progress from waiting
+
+Give commands and child waits explicit deadlines appropriate to their purpose. Reserve
+cleanup time and terminate only owned process groups. A force-exit option, heartbeat or
+worker's "running" status does not impose a timeout or demonstrate progress. The generic
+`device-run.sh` bounds startup/cleanup probes and supports `JOURNEY_SECONDS` for the
+whole journey. Set a positive value for unattended runs; its backward-compatible
+zero default disables that deadline. Allow time for the owner to finish cleanup.
+
+For a hung test, identify the actual outstanding command and last completed assertion.
+If the test waits for a child to exit, check whether its input actually requires exit.
+Reduce that question to a bounded host test before launching another emulator.
+
+Continue when an attempt tests a new prediction, collects a missing observation, shrinks
+the reproduction or adds a justified sample for an intermittent failure. State the
+purpose and cost bound first. When no available experiment distinguishes the remaining
+explanations, report the missing evidence/access. Do not restart an unchanged campaign
+or impose an arbitrary fixed number of retries on every kind of failure.
+
+Choose the environment the assertion requires: local test resources for ordinary
+functional diagnosis, isolated deployed HTTPS when that behavior requires it, or an
+existing shared deployment for explicitly non-destructive smoke checks. Create only the
+services needed by the test. Do not use shared dev data for destructive fixtures or
+cleanup. A request that never reaches its gateway calls for a transport investigation,
+not an assumed product fix.
+
+## Example: React Native debug app uses another Metro
+
+This example applies to a debug build that uses Metro. It is not a prescription for
+release builds, other runtimes or physical-device addressing.
+
+Record the host port, device port, reverse mapping, package and effective app settings.
+Select the private ADB endpoint before importing clients that cache it. Prove readiness,
+then observe an actual bundle request, response and screen.
+
+For RN 0.81.5, `debug_http_host` takes precedence; otherwise `metro.host` or emulator
+detection chooses the host and a compiled resource supplies the port. A stock emulator
+normally selects `10.0.2.2`. Check the pinned library and build before applying that
+explanation elsewhere. With device `tcp:8081` mapped to host `tcp:8158`, the agreed app
+endpoint might be `127.0.0.1:8081`; copying the host port into the app is not equivalent.
+Do not kill another worker's server if the app accidentally connects to it.
+
+- No owned bundle request: inspect selected address, mapping and Activity launch.
+- Request fails: inspect its response or bundling error.
+- Bundle succeeds, expected screen absent: inspect runtime exceptions, actual screen
+  and selector.
+
+In fmm-express #2001, a local API36 ARM64 comparison failed without the preference,
+rendered Login after setting it, and failed again after removing it. The original API35
+x86_64 CI response was not retained; the local HTTP 500 was not claimed as that response.
+The corrected post-deploy CI subsequently passed on its deployed SHA. Ports, package,
+cloud infrastructure and issue identifiers are case-study details, not requirements.
+
+Another repo-specific example was a Node first-login fixture with an empty Organization
+list consumed by Python. Passing the actual producer output through the real reader
+and journey seed selection exposed the mismatch before another cloud/device run. The
+general lesson is to test the composed contract, regardless of language or domain.
+
+- [Case study: issue #2001](https://github.com/1aboveio/fmm-express/issues/2001)
+- [Correction PR #2010](https://github.com/1aboveio/fmm-express/pull/2010)
+- [Passing post-deploy run](https://github.com/1aboveio/fmm-express/actions/runs/40329312705)
+- [RN 0.81.5 preference handling](https://raw.githubusercontent.com/facebook/react-native/v0.81.5/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/packagerconnection/PackagerConnectionSettings.kt)
+- [RN 0.81.5 host selection](https://raw.githubusercontent.com/facebook/react-native/v0.81.5/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/systeminfo/AndroidInfoHelpers.kt)