Merge branch 'main' into cancelButtonForP2P

Author: KioCoan

.claude/skills/agent-device/flows/README.md

@@ -3,17 +3,29 @@
 ## Directory layout
 
 - `macros/` - reusable helpers for common setup/navigation actions that stop in a navigable state for further interactive work.
+- `macros/<platform>/` - platform-specific overrides of a `macros/` flow, for flows whose selectors differ per platform. See [Platform scoping](#platform-scoping).
 - `tests/` - critical-scenario scripts for QA/perf verification that assert explicit outcomes (for example Sentry spans) and then stop.
 - `lib/` - bash drive libraries for flows that need conditional steering the linear `.ad` format cannot express (snapshot classification, state-dependent branching). Each file documents its own contract; the caller always owns the session lifecycle (`open`/`close`/`record`). Source them from an orchestrator or run them standalone against an already-open session (for example `lib/sign-in-drive.sh --platform web --session <name> --email <email>`).
 
 Composable `.ad` snippets - bounded units of work. A flow may span one or multiple screens as long as it represents a coherent, reusable action with clear start (`@pre`) and completion (`@post`) checkpoints. Each flow advertises machine-matchable metadata (`@pre`, `@post`, `@tag`, `@param`) via `# @`-prefixed comment headers, while flow type is derived from location (`flows/macros/` or `flows/tests/`).
 
+## Platform scoping
+
+Most flows are platform-neutral and live directly in `macros/`. A flow whose selectors genuinely differ per platform gets a copy per platform under `macros/<platform>/`, where `<platform>` is the value passed to `--platform`.
+
+A caller driving platform `P` resolves a macro by name:
+
+1. `macros/<P>/<name>.ad` when that file exists.
+2. `macros/<name>.ad` otherwise.
+
+Split flows today: `sign-in.ad`, `send-message.ad`, `complete-onboarding.ad`. All three fill text inputs, whose accessibility shape differs between web and native. The unscoped copy of a split flow stays in `macros/` as the fallback for platforms that have no folder yet; it is not the contract for any platform that does have one. Everything else stays shared - split a flow only after confirming the divergence per platform with `agent-device is visible "<selector>"`.
+
 ## Agent decision loop (interactive)
 
 Before manually navigating, use this human-in-the-loop loop:
 
 1. `agent-device snapshot -i` - see current state.
-2. `grep -H '^# @' .claude/skills/agent-device/flows/macros/*.ad` - interactive catalog.
+2. `grep -H '^# @' .claude/skills/agent-device/flows/macros/*.ad .claude/skills/agent-device/flows/macros/<platform>/*.ad` - interactive catalog. Where both list the same name, the platform copy wins.
 3. For each candidate flow, run `agent-device is exists "<selector>"` per `@pre`. Keep flows where every `@pre` passes.
 4. Rank survivors by goal closeness and present top macro candidates to the user with a short "why this flow" note:
    - Prefer flows whose `@post` selectors literally match destination language from the user request (same `text`, `label`, or selector phrase).
@@ -69,6 +81,7 @@ agent-device replay <flow>.ad -e EMAIL=other@example.com
 - **No `open`, no `close`, no `context` header.** Caller owns lifecycle.
 - **No fixed `wait` calls.** `fill`/`press` resolve selectors with retry. Only add `wait <selector>` for real post-action blocks.
 - **Durable selectors.** Prefer `id=...` first, then `role=... label=...`, with `||` fallbacks. Avoid `@eN` refs.
+- **Confirm every selector on the platform it is written for.** `snapshot -i` prints display tags, which are not selector values - a node printed as `[text-field]` may only match `role="textbox"`. Check the exit code of `agent-device is visible "<selector>"` before committing a selector, and never carry one across platforms unchecked.
 - **Every flow declares `@desc` and `@pre`.** Add `@post` for outcome-bearing flows; utility flows (for example `go-back`) may omit it. Add `@tag` when applicable.
 - **Choose directory intentionally.** Put reusable setup/navigation steps in `flows/macros/`; put outcome verification scenarios in `flows/tests/`.
 - **Keep scope coherent, not artificially tiny.** Flows can span multiple screens when that sequence is the reusable intent (for example "create and submit manual expense").

.claude/skills/agent-device/flows/lib/sign-in-drive.sh

@@ -35,6 +35,8 @@ fi
 
 # --- selector constants (one source of truth for .ad fallback, classifiers, waits) ---
 readonly SEL_LOGIN_FIELD='id="username" || role="textfield" label="Phone or email" || label="Phone or email"'
+# Mirrors the fill selector in sign-in.ad. Waiting on SEL_LOGIN_FIELD only proves the field exists, and the macro fills it requiring editable=true, so the replay could start against a field that had rendered but was not yet interactive.
+readonly SEL_LOGIN_FIELD_EDITABLE='id="username" editable=true || role="textfield" label="Phone or email" editable=true || label="Phone or email" editable=true'
 readonly SEL_CONTINUE='role="button" label="Continue" || label="Continue"'
 readonly SEL_NAME_FIELD='label="First name" || label="Full name" || role="textfield"'
 # Web wait-union markers. Apostrophe-free substrings dodge the straight-vs-curly
@@ -75,12 +77,21 @@ take_snap() {
 
 snap_has() { printf '%s' "$SNAP" | grep -qiF -- "$1"; }
 
+# Internal drive output lands here, never stdout — callers may parse stdout as a
+# machine protocol, and --settle returns a full settled diff.
+drive_log() {
+  local dir="${GITHUB_WORKSPACE:-/tmp}/artifacts"
+  mkdir -p "$dir" 2>/dev/null || true
+  printf '%s/melvin-drive-%s.log' "$dir" "${SESSION:-unknown}"
+}
+
 # Native verb per platform: press on android, click on web.
 press_label() {
   local sel="role=\"button\" label=\"$1\" || label=\"$1\""
   local verb=click
   [[ "$PLATFORM" = android ]] && verb=press
-  agent-device "$verb" "$sel" --platform "$PLATFORM" --session "$SESSION" 2>/dev/null || true
+  agent-device "$verb" "$sel" --settle --platform "$PLATFORM" --session "$SESSION" \
+    >>"$(drive_log)" 2>&1 || true
 }
 
 # Dismiss splash / runtime permission / ANR overlays that block the login hierarchy.
@@ -166,7 +177,7 @@ wait_for_login_field() {
   local budget_secs="${MELVIN_LOGIN_WAIT_SECS:-40}"
   mkdir -p "${GITHUB_WORKSPACE:-/tmp}/artifacts"
   if [[ "$PLATFORM" = web ]]; then
-    agent-device wait "$SEL_LOGIN_FIELD || $WAIT_ONBOARDING" $((budget_secs * 1000)) \
+    agent-device wait "$SEL_LOGIN_FIELD_EDITABLE || $WAIT_ONBOARDING" $((budget_secs * 1000)) \
       --platform "$PLATFORM" --session "$SESSION" >/dev/null 2>&1 || return 1
     take_snap
     if snap_login_field; then
@@ -218,8 +229,8 @@ clear_onboarding() {
     if snap_has '"First name"' || snap_has '"Full name"' \
       || snap_has "What's your name?" || snap_has $'What\u2019s your name?'; then
       human "sign-in-drive: onboarding — name MelvinBot (${step})"
-      agent-device fill "$SEL_NAME_FIELD" 'MelvinBot' \
-        --platform "$PLATFORM" --session "$SESSION" 2>/dev/null || true
+      agent-device fill "$SEL_NAME_FIELD" 'MelvinBot' --settle \
+        --platform "$PLATFORM" --session "$SESSION" >>"$(drive_log)" 2>&1 || true
       press_label "Continue"
       sleep 1
       continue
@@ -301,7 +312,14 @@ drive_sign_in() {
   fi
   human "sign-in-drive: replay ${sign_in_ad}"
   # Replay must share AGENT_DEVICE_STATE_DIR with open (caller exports it).
-  if ! agent-device replay "$sign_in_ad" -e "EMAIL=${email}" --platform "$PLATFORM" --session "$SESSION"; then
+  # Keep replay's stderr: it names the diverging step, selector, and repair hint.
+  mkdir -p "${GITHUB_WORKSPACE:-/tmp}/artifacts"
+  local replay_log="${GITHUB_WORKSPACE:-/tmp}/artifacts/melvin-signin-replay-${SESSION}.log"
+  if ! agent-device replay "$sign_in_ad" -e "EMAIL=${email}" --platform "$PLATFORM" --session "$SESSION" \
+    >>"$(drive_log)" 2>"$replay_log"; then
+    local replay_err
+    replay_err="$(tail -n 5 "$replay_log" 2>/dev/null | tr '\n' ' ')"
+    [[ -n "$replay_err" ]] && human "sign-in-drive: replay reported: ${replay_err}"
     # Already past login (onboarding residual / signup REPLACE) — clear, don't re-fill.
     take_snap
     if snap_onboarding || snap_has '"Skip"'; then
@@ -316,12 +334,16 @@ drive_sign_in() {
     # already saw the field. Fall back to direct fill+press.
     if snap_login_field; then
       human "sign-in-drive: replay wait flaked — direct fill for ${email}"
-      if agent-device fill "$SEL_LOGIN_FIELD" "${email}" \
-        --platform "$PLATFORM" --session "$SESSION" \
-        && agent-device press "$SEL_CONTINUE" \
-          --platform "$PLATFORM" --session "$SESSION"; then
+      local fallback_log="${GITHUB_WORKSPACE:-/tmp}/artifacts/melvin-signin-fallback-${SESSION}.log"
+      if agent-device fill "$SEL_LOGIN_FIELD" "${email}" --settle \
+        --platform "$PLATFORM" --session "$SESSION" >"$fallback_log" 2>&1 \
+        && agent-device press "$SEL_CONTINUE" --settle \
+          --platform "$PLATFORM" --session "$SESSION" >>"$fallback_log" 2>&1; then
         true
       else
+        local fallback_err
+        fallback_err="$(tail -n 5 "$fallback_log" 2>/dev/null | tr '\n' ' ')"
+        [[ -n "$fallback_err" ]] && human "sign-in-drive: fallback fill/press reported: ${fallback_err}"
         human "sign-in-drive: direct fill failed for ${email}"
         return 1
       fi

.claude/skills/agent-device/flows/macros/android/complete-onboarding.ad

@@ -0,0 +1,14 @@
+context platform=android
+# @desc   Complete onboarding with minimal choices (skip work email, pick "Something else" purpose, enter generic name). Lands on Home.
+# @pre    text="What’s your work email?"
+# @post   text="Home"
+# @post   role="button" label="Search"
+# @tag    onboarding
+# @param  FIRST_NAME First name to enter on onboarding profile step.
+# @param  LAST_NAME Last name to enter on onboarding profile step.
+
+press "id=\"onboardingPrivateEmailSkipButton\" || role=\"button\" label=\"Skip\" || label=\"Skip\""
+press "role=\"button\" label=\"Something else\" || label=\"Something else\""
+fill "role=\"textfield\" label=\"First name\" editable=true || label=\"First name\" editable=true" "${FIRST_NAME}"
+fill "role=\"textfield\" label=\"Last name\" editable=true || label=\"Last name\" editable=true" "${LAST_NAME}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/agent-device/flows/macros/android/send-message.ad

@@ -0,0 +1,10 @@
+context platform=android
+# @desc   Send a chat message from inside an already-open chat. Reusable helper for setting up state in other flows. Does not navigate or open a chat - assumes the composer is visible. For the QA scenario that exercises the ManualSendMessage Sentry span, see flows/tests/send-message.ad.
+# @pre    label="Write something..." editable=true
+# @post   label="Write something..." editable=true
+# @tag    chat
+# @param  MESSAGE Message text to send in the currently open chat.
+
+is exists "label=\"Write something...\" editable=true"
+fill "label=\"Write something...\" editable=true" "${MESSAGE}"
+press "role=\"button\" label=\"Send\" || label=\"Send\""

.claude/skills/agent-device/flows/macros/android/sign-in.ad

@@ -0,0 +1,10 @@
+context platform=android
+# @desc   Sign in with the shared agent-device test account. Supports both new-account and returning-account outcomes. Caller MUST randomize EMAIL via `-e EMAIL=agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+# @pre    id="username"
+# @pre    role="button" label="Continue"
+# @post   role="button" label="Join" || role="button" label="Search"
+# @tag    auth
+# @param  EMAIL Login email. Use randomized alias format `agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+
+fill "id=\"username\" || label=\"Phone or email\" editable=true" "${EMAIL}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/agent-device/flows/macros/web/complete-onboarding.ad

@@ -0,0 +1,14 @@
+context platform=web
+# @desc   Complete onboarding with minimal choices (skip work email, pick "Something else" purpose, enter generic name). Lands on Home.
+# @pre    text="What’s your work email?"
+# @post   text="Home"
+# @post   role="button" label="Search"
+# @tag    onboarding
+# @param  FIRST_NAME First name to enter on onboarding profile step.
+# @param  LAST_NAME Last name to enter on onboarding profile step.
+
+press "role=\"button\" label=\"Skip\" || label=\"Skip\""
+press "role=\"button\" label=\"Something else\" || label=\"Something else\""
+fill "role=\"textbox\" label=\"First name\" || label=\"First name\"" "${FIRST_NAME}"
+fill "role=\"textbox\" label=\"Last name\" || label=\"Last name\"" "${LAST_NAME}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/agent-device/flows/macros/web/send-message.ad

@@ -0,0 +1,10 @@
+context platform=web
+# @desc   Send a chat message from inside an already-open chat. Reusable helper for setting up state in other flows. Does not navigate or open a chat - assumes the composer is visible. For the QA scenario that exercises the ManualSendMessage Sentry span, see flows/tests/send-message.ad.
+# @pre    role="textbox" label="Write something..."
+# @post   role="textbox" label="Write something..."
+# @tag    chat
+# @param  MESSAGE Message text to send in the currently open chat.
+
+is exists "role=\"textbox\" label=\"Write something...\""
+fill "role=\"textbox\" label=\"Write something...\"" "${MESSAGE}"
+press "role=\"button\" label=\"Send\" || label=\"Send\""

.claude/skills/agent-device/flows/macros/web/sign-in.ad

@@ -0,0 +1,11 @@
+context platform=web
+# @desc   Sign in with the shared agent-device test account. Supports both new-account and returning-account outcomes. Caller MUST randomize EMAIL via `-e EMAIL=agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+# @pre    role="textbox" label="Phone or email"
+# @pre    role="button" label="Continue"
+# @post   text="Welcome!" || text="Home"
+# @post   role="button" label="Join" || role="button" label="Search"
+# @tag    auth
+# @param  EMAIL Login email. Use randomized alias format `agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+
+fill "role=\"textbox\" label=\"Phone or email\" || label=\"Phone or email\"" "${EMAIL}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/coding-standards/SKILL.md

@@ -53,6 +53,9 @@ Coding standards for the Expensify App. Each standard is a standalone file in `r
 - [CONSISTENCY-12](rules/consistency-12-callback-named-for-action.md) — Name callbacks for what they do, not the event they handle
 - [CONSISTENCY-13](rules/consistency-13-document-props.md) — Document component props with a JSDoc block comment
 - [CONSISTENCY-14](rules/consistency-14-new-file-header.md) — Non-trivial new files start with a header description
+- [CONSISTENCY-15](rules/consistency-15-comment-why.md) — Comments explain why the code exists, not what it does
+- [CONSISTENCY-16](rules/consistency-16-plain-comment-style.md) — Write comments as plain, natural sentences
+- [CONSISTENCY-17](rules/consistency-17-no-ai-jargon.md) — No AI-generated jargon in code or comments
 
 ### Clean React Patterns
 - [CLEAN-REACT-PATTERNS-0](rules/clean-react-0-compiler.md) — React Compiler compliance

.claude/skills/coding-standards/rules/consistency-15-comment-why.md

@@ -0,0 +1,41 @@
+---
+ruleId: CONSISTENCY-15
+title: Commenting "Why"
+---
+
+## [CONSISTENCY-15] Commenting "Why"
+
+### Reasoning
+
+Comments should explain *why* the code exists, not what it does. Well-named identifiers already say what the code does, so a comment that only restates the code is dead weight.
+
+### Incorrect
+
+```tsx
+// loop through users
+users.forEach(processUser);
+```
+
+### Correct
+
+```tsx
+// We only include active users to avoid reprocessing deactivated ones
+users.forEach(processUser);
+```
+
+---
+
+### Review Metadata
+
+Flag ONLY when BOTH of these are true:
+
+- The changed code adds or modifies a comment
+- The comment restates what the code does instead of explaining why it exists
+
+**DO NOT flag if:**
+
+- The comment is a JSDoc `@param` or `@returns` description, where stating what the parameter or return value is is the expected content, not a why explanation
+- Stating what the code does is genuinely the only way to orient a reader, such as documenting a regex or a bit-flag mask
+
+**Search Patterns** (hints for reviewers):
+- Any newly added or modified `//` or `/* */` comment that only restates the code below it